docs(v4): give param-value rows a real lifecycle (review feedback)

param-value rows now share the symbol lifecycle instead of being
schema-only: planned -> shimmed -> removed statuses, test_ref required at
shim/removal (value behavior - old spelling warns then rejects, new spelling
accepted - lives in that suite), and full due-gate coverage (overdue and
early-removal). No reality probe (accepted values are not introspectable).
Negative fixtures added for both the schema rule and the due gate; spec
section 11 updated in the same diff. Closes the M-086 park-silently gap.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017eVKbBqzenDKa5idwtexQa

Author: igerber

docs/v4-design.md

@@ -451,7 +451,9 @@ state). `deprecated_in`/`removed_in`/`new` are required-present but nullable;
 versions match `\d+\.\d+(\.\d+)?`.
 
 **Kinds.** `param` (constructor or method parameter), `param-value` (accepted
-value spelling; schema-checked only), `class`, `field` (results attribute),
+value spelling; full symbol lifecycle and due gate but NO reality probe -
+accepted values are not introspectable, so behavioral enforcement lives in
+the row's `test_ref` suite), `class`, `field` (results attribute),
 `function`, `alias` (top-level export alias), `default-flip` (same param, new
 default), `env-default` (environment-variable-resolved default),
 `warning-retirement` (a warning message scheduled to disappear), `behavior`
@@ -468,8 +470,10 @@ never a legal absence.
 
 **Status lifecycle.** Symbol kinds (param/class/field/function): `planned` ->
 `shimmed` -> `removed`; the `shimmed` stop may be skipped only when the row's
-deprecation rides a parent row (stated in `notes`, e.g. [M-011]). Non-symbol
-kinds (alias/default-flip/env-default/warning-retirement/behavior): `planned`
+deprecation rides a parent row (stated in `notes`, e.g. [M-011]).
+`param-value` rows follow the same lifecycle (with `test_ref` required at
+`shimmed`/`removed` and due-gate coverage). Remaining non-symbol kinds
+(alias/default-flip/env-default/warning-retirement/behavior): `planned`
 or `evaluate` -> `done`. Terminal rows (`removed`/`done`) keep asserting
 forever - a removed symbol resurrecting is a test failure.
 
@@ -492,7 +496,11 @@ forever - a removed symbol resurrecting is a test failure.
   "on" expects True, "off" expects False).
 - `warning-retirement`: `snippet` present in the `code_refs` file (`done`:
   absent).
-- `param-value`/`behavior`: schema + `code_refs` existence only.
+- `param-value`: schema + due gate + `test_ref` existence at
+  `shimmed`/`removed`; no reality probe (value behavior asserted in the
+  `test_ref` suite: old spelling warns at shim, rejected at removal, new
+  spelling accepted).
+- `behavior`: schema + `code_refs` existence only.
 - Release gate (all kinds): once `diff_diff.__version__` reaches a row's
   `removed_in` (symbol/alias rows), flip version (`deprecated_in` on
   default-flip/warning-retirement/behavior rows), or `decision_due`

tests/test_v4_matrix.py

@@ -61,6 +61,10 @@
     "behavior",
 }
 KINDS = SYMBOL_KINDS | NONSYMBOL_KINDS
+# param-value rows share the symbol LIFECYCLE (planned -> shimmed -> removed, test_ref at
+# shim/removal, due-gated) but skip reality probes - accepted values are not introspectable;
+# their behavioral enforcement lives in the row's test_ref suite.
+LIFECYCLE_KINDS = SYMBOL_KINDS | {"param-value"}
 SYMBOL_STATUSES = {"planned", "shimmed", "removed"}
 NONSYMBOL_STATUSES = {"planned", "evaluate", "done"}
 WARNING_VALUES = {"FutureWarning", "DeprecationWarning"}
@@ -188,7 +192,7 @@ def validate_schema(rows):
         if kind not in KINDS:
             errors.append(f"{rid}: unknown kind '{kind}'")
             continue
-        legal = SYMBOL_STATUSES if kind in SYMBOL_KINDS else NONSYMBOL_STATUSES
+        legal = SYMBOL_STATUSES if kind in LIFECYCLE_KINDS else NONSYMBOL_STATUSES
         if status not in legal:
             errors.append(
                 f"{rid}: status '{status}' illegal for kind '{kind}' (legal: {sorted(legal)})"
@@ -199,7 +203,7 @@ def validate_schema(rows):
                 errors.append(f"{rid}: {vfield}={val!r} does not match \\d+.\\d+(.\\d+)?")
         if row.get("warning") is not None and row["warning"] not in WARNING_VALUES:
             errors.append(f"{rid}: warning={row['warning']!r} not in {sorted(WARNING_VALUES)}")
-        if kind in SYMBOL_KINDS and status in ("shimmed", "removed") and not row.get("test_ref"):
+        if kind in LIFECYCLE_KINDS and status in ("shimmed", "removed") and not row.get("test_ref"):
             errors.append(
                 f"{rid}: status '{status}' requires a test_ref (dedicated behavioral test)"
             )
@@ -447,7 +451,7 @@ def collect_due_problems(rows, current):
                     f"still in the future - early removal/flip breaks the shim window promise"
                 )
         if removed_in and current >= _version_tuple(removed_in):
-            if kind in SYMBOL_KINDS and status != "removed":
+            if kind in LIFECYCLE_KINDS and status != "removed":
                 problems.append(f"{rid}: removed_in {removed_in} is due but status is '{status}'")
             if kind == "alias" and status != "done":
                 problems.append(f"{rid}: removed_in {removed_in} is due but status is '{status}'")
@@ -469,7 +473,7 @@ def collect_due_problems(rows, current):
                 "(new surface not shipped?)"
             )
         if (
-            kind in SYMBOL_KINDS
+            kind in LIFECYCLE_KINDS
             and row.get("warning")
             and row.get("deprecated_in")
             and current >= _version_tuple(row["deprecated_in"])
@@ -585,6 +589,22 @@ def test_all_membership_helper_semantics():
             "removed_in 4.0 is due",
             (3, 9, 0),
         ),
+        # overdue param-value removal: value migrations are due-gated like symbol rows
+        (
+            {
+                "id": "M-906",
+                "kind": "param-value",
+                "old": "diff_diff:WooldridgeDiDResults.aggregate[type]=event",
+                "new": "diff_diff:WooldridgeDiDResults.aggregate[type]=event_study",
+                "deprecated_in": "3.9",
+                "removed_in": "4.0",
+                "status": "shimmed",
+                "phase": 5,
+            },
+            (4, 0, 0),
+            "removed_in 4.0 is due",
+            (3, 9, 0),
+        ),
         # EARLY removal: row flipped to removed while removed_in is still in the future
         (
             {
@@ -606,6 +626,7 @@ def test_all_membership_helper_semantics():
         "overdue-introduce-only-alias",
         "overdue-env-default-decision",
         "overdue-removal",
+        "overdue-param-value-removal",
         "early-removal-before-schedule",
     ],
 )
@@ -625,7 +646,12 @@ def test_row_matches_reality(row, monkeypatch):
     rid, kind, status = row["id"], row["kind"], row["status"]
     old, new = row["old"], row["new"]
 
-    if kind in ("param-value", "behavior"):
+    if kind == "param-value":
+        pytest.skip(
+            "no reality probe (accepted values are not introspectable); lifecycle is "
+            "schema+due-gate enforced and value behavior lives in the row's test_ref suite"
+        )
+    if kind == "behavior":
         pytest.skip("schema-checked kind; flipped manually, swept at the cut")
 
     if kind in ("param", "class", "function"):
@@ -849,6 +875,12 @@ def _schema_errors_for(text):
             "code_refs must be a non-empty list",
         ),
         (lambda t: t.replace("    group: fixture\n", ""), "missing required field"),
+        (
+            lambda t: t.replace("    kind: param\n", "    kind: param-value\n").replace(
+                "    status: planned\n", "    status: shimmed\n"
+            ),
+            "requires a test_ref",
+        ),
         (
             lambda t: t.replace("    kind: param\n", "    kind: behavior\n").replace(
                 "    status: planned\n", "    status: done\n"
@@ -866,6 +898,7 @@ def _schema_errors_for(text):
         "dotted-locator-on-removable",
         "empty-code-refs",
         "missing-group",
+        "param-value-shimmed-without-test-ref",
         "behavior-done-without-test-ref",
     ],
 )