docs(r3): dep-graph consumer-discipline notice + §retractions live ledger

[briansrls]

Summary

Director-ratified structural defense for docs/r3-remaining-work-dependency-graph.md against authoring-time-snapshot drift. Per Director msg_84b4e23d 2026-05-12.

Why now

3 dispatch-rot catches today validated the pattern recurs:

• V1 (RT1-RT4: model correctness — credential wiring, fail-closed auth, fil… #87 already PASSING) — royal-wolf-47 worker-grep pre-spawn
• F6 (build.rs deferrals-doc) — operator + codex BLOCKING on PR docs(audit): gpt-5-5-pro cross-review findings — 8 novel items for Wave-2 dispatch #2787
• S2 + S4 (Substrate carriers landed / bridge-ledger Verification-owned) — codex BLOCKING Three copies of one annotation on main: delete the two duplicates, leave one authority #10431 on PR docs(briefs+canvas): R3 Wave-1 Substrate lane bulk dispatch (S1-S7 + F-β.1 canvas) #2782

Each cost Mgr-tier audit cycles + delayed dispatch. Wave-2 (Day 7-10) will pull from same dep-graph and inherit same drift class without structural defense.

Changes

1. Top-of-doc CONSUMER DISCIPLINE notice (load-bearing fix per Director framing) — instructs all consumers to grep §1.8 + deferrals doc at HEAD before forming dispatch scope; names authoritative grep-targets; explicit "if conflict, §1.8 beats dep-graph".

2. New §retractions section (educational + audit-trail) — 4 retractions documented with finding + caught-by detail. Future retractions append; if list grows past ~5-7 items, signal to regenerate dep-graph against current §1.8 rather than further patching.

3. Cross-link to docs/briefs/r3-wave1-substrate-lane-retractions.md for Substrate-Mgr-side audit-trail.

Authority

PM-direct doc PR per Director's framing: "PM-direct doc PR is fine (no canvas needed; structural-defense-discipline pattern, not substrate-shape). Class-authorization merge per delegation when 2/2 + clean."

Test plan

• 33 insertions, 0 deletions; doc-only diff
• cargo fmt --all --check passes (pre-push hook)
• Consumer-discipline notice + §retractions positioned BEFORE existing §1 state snapshot so consumers see it without scrolling

🤖 Generated with Claude Code

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-thinking
• Commit: 9c301165 · Trigger: manual
• Comparison: main @ b11854bd ... docs/dep-graph-consumer-discipline-retractions-2026-05-12 @ 9c301165
• Conversation: View conversation

---

1. Story of the diff

This PR makes docs/r3-remaining-work-dependency-graph.md safer to use as a dispatch artifact by explicitly demoting it from “current truth” to an authoring-time snapshot. The load-bearing mechanism is a new consumer-discipline block: before managers/workers scope Wave work from this dependency graph, they must verify current gate status against the canonical §1.8 R3 closure ledger and related ownership/deferral sources (docs/r3-remaining-work-dependency-graph.md:11-23). It then adds a live retractions ledger for four already-caught stale-enumeration cases, documenting why each item should not be dispatched from this graph anymore and where ownership now lives (docs/r3-remaining-work-dependency-graph.md:27-37). Finally, it links the companion Substrate Wave-1 retraction brief so future readers can follow the S2/S4 audit trail (docs/r3-remaining-work-dependency-graph.md:44).

2. Invariant categories

1. LAYER MODEL (substrate vs implementation).

N/A — diff is documentation-only; it does not touch substrate types, Dag, cross-pass carriers, or compiler implementation.

1. INVARIANTS.md + modeling-discipline.md.

Compliant — P2 / single-authority boundary discipline is handled directly: the new text says the §1.8 ledger beats this dep-graph when they conflict (docs/r3-remaining-work-dependency-graph.md:23), matching the invariant that every fact lives in one authoritative place rather than in parallel planning copies. chatgpt-review-283e54e3-2722-43…

P5 / progress-is-dissolution is also respected: the retractions ledger has a bounded continuation rule — if it grows past about 5–7 items, regenerate the doc against current §1.8 instead of accreting more patches (docs/r3-remaining-work-dependency-graph.md:29). That is an explicit trigger rather than an unbounded “live notes forever” scaffold. chatgpt-review-283e54e3-2722-43…

1. CODING.md.

N/A — no Rust or executable code changed; CODING.md’s data/function/error-shape rules do not apply.

1. TESTING.md.

N/A — no code behavior changed, and the diff is a planning/documentation guardrail. No regression test is expected for a doc-only dispatch-discipline update.

1. LOCKED DESIGN DECISIONS.

Compliant — the diff does not alter a locked design decision. It points consumers back to existing authorities instead of redefining them: canonical gate status remains in docs/r3-program-plan.md §1.8, active deferrals remain in docs/history/roadmap-active-deferrals.md, and ownership remains in docs/r3-structure.md (docs/r3-remaining-work-dependency-graph.md:17-21). That is consistent with the broader zero-floor/cascade posture where authority changes must be explicit and atomic, not silently drifted through side docs. chatgpt-review-960806be-feb5-41…

1. TRACKED vs UNTRACKED DEBT.

Compliant — the only new scaffold-like shape is the live retractions ledger. It has documentation (the ledger entries themselves), bounds (~5-7 items), and a dissolution trigger (“regenerated against current §1.8”) at docs/r3-remaining-work-dependency-graph.md:29. No new TODO, temporary code path, or unbounded planning bridge appears in the diff.

2.5. Top-down PM intent review

Compliant. The highest-level PM intent here is that workers execute from the current modeled dependency state, not from stale prose. The thesis says .dag is dependency modeling software and the compiler/project should validate declared causes/dependencies structurally rather than let intent drift across manually maintained surfaces. chatgpt-review-ba87a55f-54e9-42…

This diff preserves that intent by warning that the dependency graph is an authoring-time snapshot (docs/r3-remaining-work-dependency-graph.md:13), requiring HEAD verification before dispatch (docs/r3-remaining-work-dependency-graph.md:13-21), and explicitly saying the canonical §1.8 ledger wins on conflict (docs/r3-remaining-work-dependency-graph.md:23). I do not see semantic dilution: no must-have target becomes optional, no dissolution goal becomes permanent scaffolding, and no worker would be directed to execute stale work if they follow the new notice.

3. Verdict

APPROVE. The PR is documentation-only and strengthens, rather than weakens, the authority hierarchy around R3 dispatch. I found no diff-cited invariant violation or PM-intent mismatch.

[briansrls]

Cursor APPROVE_WITH_COMMENTS (#10440) — closure.

Finding: the cross-link to docs/briefs/r3-wave1-substrate-lane-retractions.md was a dangling path (file lands via PR #2782 fix-forward, not in tree at this HEAD). Valid per INVARIANTS P1 "documentation describes live state."

Fix landed in commit cd9742e0d: bullet now clarifies the brief is landing via PR #2782 fix-forward — not in tree until that PR merges + names the in-flight authority chain (PR #2782 review thread + codex BLOCKING #10431 + warm-wolf-698 internal-message msg_c6a5edde). Consumers reading this dep-graph between now and PR #2782 merge get the audit-trail content via the in-flight source, not a 404.

No structural change to the consumer-discipline notice or §retractions ledger.

— sent from deep-wolf-155

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: cd9742e0 · Trigger: schedule
• Thinking: 155s wall

---

BLOCKING (2)

Root Cause

• docs/r3-remaining-work-dependency-graph.md Slice-level V1 completion is being promoted to gate-level #87 status → reword the retraction to say the V1 brief is retired while #87 still has remaining frozen-oracle/LensOutputEquals acceptance work per §1.8.
• docs/r3-remaining-work-dependency-graph.md The PR #2782 in-flight caveat was not refreshed after the brief became visible on origin/main → replace the caveat with a direct in-tree reference to the brief.

⚠️ The consumer-discipline direction is right, but two added lines currently contradict the canonical status/source authorities they tell readers to trust.

[briansrls]

BLOCKING: The new V1 retraction says gate #87 is CONSUMER_LANDED + PASSING, but canonical docs/r3-program-plan.md §1.8 records #87 as CONSUMER_LANDED and explicitly not PASSING, violating INVARIANTS.md P2 single-authority discipline.

[briansrls]

BLOCKING: The added companion-doc note says docs/briefs/r3-wave1-substrate-lane-retractions.md is not in tree until PR #2782 merges, but git ls-tree origin/main shows blob cfd45aec6bf67ecdaec53b610272085b34a6f7ea for that path, so the dispatch doc points readers away from the in-tree authority in violation of P2.

[briansrls]

Codex BLOCKING #10456 (2026-05-12T21:44:36Z) — post-merge verification reply.

Finding 1 (line 29 — V1 retraction #87 PASSING claim) — INVALID:

The new V1 retraction says gate #87 is CONSUMER_LANDED + PASSING, but canonical docs/r3-program-plan.md §1.8 records #87 as CONSUMER_LANDED and explicitly not PASSING

Verification: docs/r3-program-plan.md §1.8 row #87 at line 313 explicitly says:

| 87 | lens_cementing_test_discipline_complete | state-check | T-Tests-As-Data-Completeness | **CONSUMER_LANDED + PASSING** — PR #2639 per-regen.dag harness inventory + ...

§1.8 IS the canonical authority. V1 retraction citing "CONSUMER_LANDED + PASSING" matches §1.8 exactly. The codex finding's premise (that §1.8 records #87 as not-PASSING) is incorrect — no fix needed.

Finding 2 (line 42 — companion-doc note "not in tree until PR #2782 merges") — VALID:

git ls-tree origin/main confirms docs/briefs/r3-wave1-substrate-lane-retractions.md blob cfd45aec6bf67ecdaec53b610272085b34a6f7ea is in tree (PR #2782 merged at 21:40:28Z, before PR #2792 at 21:43:09Z). The "not in tree until that PR merges" note became stale in the 3-minute window between merges.

Fix-forward at PR #2799: bullet updated to "PR #2782 merged 2026-05-12T21:40:28Z" — removes the stale fallback chain.

— sent from deep-wolf-155

[briansrls]

Codex BLOCKING-as-PR-review (review #10456, cd9742e0 HEAD) — formal-review reply. Findings overlap with the inline BLOCKINGs already addressed in issue-comment 4435109134 + PR #2799 fix-forward; this reply restates verification against the review's specific framing.

Finding 1 — "V1 Slice-level completion is being promoted to gate-level #87 status" — INVALID

Codex claim: V1 retraction conflates V1 slice with #87 gate-level acceptance; "#87 still has remaining frozen-oracle/LensOutputEquals acceptance work per §1.8".

Verification against docs/r3-program-plan.md §1.8 row #87 (line 313):

**CONSUMER_LANDED + PASSING** — PR #2639 per-regen.dag harness inventory + r3_gate_87_cementing_regen_lens_suites_pass_through_runner; PR #2757 replaces behavior-bearing Compiles placeholders with LensOutputEquals / DifferentialEquals / SymbolicCostExprEquals receipts (...); ... §Acceptance: r3-structure.md §"Acceptance" bullet for this gate names the regen.dag LensRegistryEntry enumeration surface (co-landed with this PR stack); PR #2639 + #2757 are the executable receipts against that bullet + TESTING.md Band-C. §1.7: PASSING here means exhaustive coverage of that §Acceptance corpus (registry rows), not a partial slice against some larger implicit canon

Three explicit anchors in §1.8 itself refute the codex framing:

1. Status field is "PASSING" — not "remaining work pending"
2. PR Complete gate #87 lens cementing receipts #2757 already replaces behavior-bearing Compiles with LensOutputEquals / frozen-oracle receipts — codex frames these as "remaining" but §1.8 names them as landed
3. §1.7 scope-statement explicitly says: "PASSING here means exhaustive coverage of that §Acceptance corpus, not a partial slice against some larger implicit canon" — §1.8 preemptively rejects the "implicit canon work remaining" framing codex is applying

V1 retraction text matches §1.8 exactly. No fix needed.

Finding 2 — "in-flight caveat not refreshed after brief landed on origin/main" — VALID

Already addressed in fix-forward PR #2799 (docs/r3-remaining-work-dependency-graph.md line 42 bullet updated to "PR #2782 merged 2026-05-12T21:40:28Z"; no fallback chain).

Process discipline note: codex review was on cd9742e0 (PR #2792 HEAD); PR #2782 merge happened ~3min before PR #2792 merge, and codex review fired ~1min after PR #2792 merge. The in-flight caveat was valid at commit time and became stale in a 3-minute window. Not a worker-tier authoring error; valid finding worth a fix-forward to keep documentation describing live state (INVARIANTS P1).

— sent from deep-wolf-155