impl(sprint-12/wave-G): 6 Sonnet + 1 Opus — D-CSV-5b/6b/13/15 + E-META-10 iron rule (sprint-12 grade B+)

.claude/board/EPIPHANIES.md

@@ -143,6 +143,23 @@ stay as historical references.
 
 ## Entries (reverse chronological)
 
+## 2026-05-16 — E-META-10 (FINDING): v1-API-under-v2-feature alias pattern — systematic layout-bit boundary testing required
+
+**Status (2026-05-16):** PROMOTED to iron rule `I-LEGACY-API-FEATURE-GATED` in CLAUDE.md
+following Wave F Opus honest review recommendation. Original FINDING content preserved
+below for historical context.
+
+**Status:** FINDING (surfaced sprint-11 Wave A codex review; confirmed by W-Meta-Opus sprint-12 Wave F)
+
+**Click:** Sprint-11 Wave A codex P1 review caught the same anti-pattern 5 times in one PR (PR #383): v1 API paths (accessors and setters on `CausalEdge64`) reading or writing OLD bit positions that v2 had reclaimed for plasticity[2], W-slot, lens, and spare. The same function name silently produces different semantics depending on which feature flag is active; downstream callers see corruption only at runtime on workloads that hit the reclaim zone. Wave F Opus meta-review (CSI-2) identified this as a systemic pattern, not a per-site fix.
+
+**Doctrinal claim:** Every v1 API path under a v2-layout feature must transparently route through the canonical mapping OR be feature-gated to a documented no-op with a migration pointer. Field-isolation matrix tests (writing each field, asserting all other fields unchanged) are MANDATORY when a layout reclaims previously-used bits. The codex P1 review is the canonical pre-merge gate for this pattern.
+
+**Cross-ref:** CLAUDE.md §Substrate-level iron rules → I-LEGACY-API-FEATURE-GATED; `.claude/knowledge/i4-substrate-decisions.md` §5 "Codex P1 Anti-Pattern" (5-instance catalogue); `.claude/board/sprint-log-11/meta-review-opus.md` CSI-2; sprint-log-11/meta-review.md E-META-10 original entry.
+
+---
+
+
 ## 2026-05-14 — E-META-7 (FINDING): dual `CausalEdge64` types in workspace + p64 drift origin pinpointed + three-zone hot-path model
 
 **Status:** FINDING (verified 2026-05-14 against shipped source; recorded in PR #372 merge commit `9fa206d`).

.claude/board/TECH_DEBT.md

@@ -12,6 +12,16 @@
 
 ---
 
+
+### TD-LEGACY-API-FEATURE-GATED-RESOLVED-1
+
+- **Severity:** N/A (RESOLVED 2026-05-16)
+- **Surfaced in:** sprint-11 Wave A codex review (caught the pattern 5×); confirmed by W-Meta-Opus in sprint-12 Wave F
+- **Resolution:** Promoted to iron rule `I-LEGACY-API-FEATURE-GATED` in CLAUDE.md. Future PRs touching layout-bit boundaries MUST add field-isolation matrix tests and route every v1 accessor through the canonical v2 mapping (or feature-gate to no-op with migration pointer). Codex P1 review is the canonical pre-merge gate.
+- **Cross-ref:** CLAUDE.md §Substrate-level iron rules; EPIPHANIES.md E-META-10; sprint-log-11/meta-review-opus.md CSI-2; .claude/knowledge/i4-substrate-decisions.md "Codex P1 anti-pattern" section.
+
+---
+
 ## Double-entry discipline
 
 Same pattern as `ISSUES.md`:

CLAUDE.md

@@ -400,6 +400,69 @@ identities, not content.
 
 ---
 
+#### I-LEGACY-API-FEATURE-GATED (iron rule, added 2026-05-16)
+
+**Every v1 API path under a v2-layout feature must transparently route
+through the canonical mapping OR be feature-gated to a documented
+no-op with a migration pointer.**
+
+The anti-pattern: leaving a v1 accessor or setter that reads/writes the
+OLD bit positions under a v2 feature that reclaimed those bits. The same
+function name silently produces different semantics depending on which
+feature is active, and downstream callers see corruption only at runtime
+on workloads that hit the reclaim zone.
+
+Sprint-11 caught this anti-pattern **5 times** via codex review:
+
+1. `CausalEdge64::pack(..., temporal=X)` under v2 writing `temporal << 52`
+   into bits 52-63 which v2 reclaimed for plasticity[2] + W-slot + lens
+   + spare. Fix: feature-gate the temporal write to no-op under v2.
+2. `CausalEdge64::inference_type()` reading 3 unsigned bits 46-48 under
+   v2 where the actual storage is 4-bit signed mantissa at 46-49. Fix:
+   route through `from_mantissa(inference_mantissa())` under v2.
+3. `CausalEdge64::set_temporal()` writing bits 52-63 unconditionally
+   even under v2 (where those bits are W/lens/spare). Fix: feature-gate
+   the entire setter to a documented no-op under v2.
+4. `CausalEdge64::pack(..., InferenceType::Counterfactual, ...)` under
+   v2 writing the raw enum discriminant (6) into the mantissa field;
+   `inference_mantissa()` reads it as +6 → `from_mantissa(+6)` decodes
+   as Intervention (not Counterfactual). Fix: write
+   `inference.to_mantissa()` (-6 for Counterfactual) instead of the raw
+   discriminant under v2.
+5. W3 spec test `pal8_v1_v2_round_trip_zero_default` used `temporal=1023`
+   to construct a v1 edge; under v2 those bits aliased W/truth/spare and
+   the test would fail on ordinary v1 data. Fix: use `temporal=0` (the
+   only safe v1 migration value) for the round-trip and add a paired
+   `pal8_v1_nonzero_temporal_is_blocked_by_version_gate` test to assert
+   the corruption is observable (the version gate is mandatory).
+
+Consequences:
+
+- **Backward-compat shims for layout-breaking changes require
+  systematic test coverage of the layout-bit boundary.** Field-isolation
+  matrix tests (writing each field, asserting all other fields unchanged)
+  are MANDATORY when a layout reclaims previously-used bits.
+- **The same function name MUST NOT silently produce different
+  semantics under different feature flags.** If the v1 API can't route
+  to the v2 canonical mapping, feature-gate it to a no-op AND add a
+  doc-comment migration pointer to the v2 successor (e.g.
+  `inference_mantissa()`, `pack_v2()`).
+- **Layout reclaim must be paired with a version gate on serialization
+  paths.** A v1 binary blob under a v2 reader MUST refuse to decode
+  without an explicit version byte (otherwise the bit aliases silently
+  corrupt the reclaim zone).
+- **The codex P1 review is the canonical pre-merge gate for this
+  pattern.** When a PR ships v2-feature work, expect codex to flag any
+  v1 accessor that hasn't been routed through the canonical mapping.
+  Resolve before merge; don't defer.
+
+Cross-ref: `EPIPHANIES.md` E-META-10 (the original finding);
+`.claude/knowledge/i4-substrate-decisions.md` (the 5-instance catalogue);
+`.claude/board/sprint-log-11/meta-review-opus.md` CSI-2 (Opus's
+identification of the systemic pattern across Wave A).
+
+---
+
 ## Session Start — MANDATORY READS (in this order)
 
 **Start here:** `.claude/BOOT.md` — the one-page session entry point.