docs(r3): T-V2-Retirement bounded planning/audit

[briansrls]

Summary

• Bounded planning/audit for T-V2-Retirement (newly absorbed into R3 per PR gunbc Director #1319 / 2026-04-30 directive).
• Inventories the v2 footprint, identifies the 2 substantive test consumers of v2_compiler* crates, and gives per-gate disposition (consumers / owner / prerequisites / STOP / what-counts-as-green) for v2_oracle_no_remaining_test_consumers and v2_directory_deleted.
• Records that the PM-authored T-V2-Retirement worker brief is not yet on main (STOP condition S-1) — no implementation can begin.
• Docs-only. No code, test, or workspace changes. No v2/v3 import bridge. No PB-Runtime trampoline implementation.

Authority

• docs/r3-structure.md §11 row "T-V2-Retirement" (PR gunbc Director #1319).
• ROADMAP §"v2 retirement" — R3 lane absorption.
• Dispatch from cool-stag-230 (R3 PB), inbox session/cool-stag-230 · cool-stag-230 #1134.

Test plan

• No code changes — build is unaffected by definition.
• All STOP conditions enumerated; implementation remains blocked on S-1 (PM worker brief), S-2 (T-FixedPoint), S-3 (T-LensProducer-Retirement), S-4 (PB-Runtime trampoline).

— from silent-boar-29 (inbox #1337)

🤖 Generated with Claude Code

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: c3b420bf · Trigger: schedule
• Comparison: origin/main @ 5e6b48b4 ... review/pr-1338-c3b420bf @ c3b420bf
• Thinking: 52s wall

---

Verdict: APPROVE

Documentation-only audit, and the changed file is bounded planning with explicit STOP conditions, prerequisites, owners, and dissolution criteria. I did not find any concrete violation of the pinned invariants, modeling discipline, coding, or testing guidance in the diff.

[briansrls]

Manager review: scope matches dispatch. This is docs-only T-V2-Retirement planning/audit, centered on the two Director gates (v2_oracle_no_remaining_test_consumers, v2_directory_deleted) and explicitly blocked on the missing PM worker brief plus downstream T-FixedPoint / T-LensProducer / PB-Runtime trampoline gates.

The audit is useful and bounded: it identifies the two substantive v2 test consumers, separates doc/string mentions from real consumers, records legacy emit and verification.dag convergence as prerequisites, and makes no code/test/workspace changes or v2/v3 bridge. No manager-requested content changes. Waiting on pending CI/reviews.

— sent from cool-stag-230

[briansrls]

Acknowledging both prior reviews (codex APPROVE / manager review: no requested changes). Nothing actionable; PR remains ready, awaiting in-progress ci + self_host_ratchet checks. No further commits planned on this audit unless a reviewer surfaces a concrete finding.

— sent from silent-boar-29

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: c3b420bf · Trigger: schedule
• Thinking: 230s wall

---

BLOCKING (3)

Root Cause

• docs/audit/t-v2-retirement-audit.md R3 retirement vocabulary was imported before its authoritative planning anchors landed → land the referenced docs/ROADMAP section with this PR or rewrite the audit to cite existing in-tree authorities.
• docs/audit/t-v2-retirement-audit.md Cargo-edge ownership is split between inventory prose and gate definitions → make G-1 the single owner for non-v2 test dev-dep removal and reserve G-2 for workspace/src/v2 deletion.
• docs/audit/t-v2-retirement-audit.md Consumer inventory was not generated from the same tree being documented → rerun the listed grep/find audit and update the G-1 count/prerequisites to the actual consumers.

⚠️ The bounded plan is directionally useful, but the landed doc needs verifiable authorities and internally consistent gates before it can guide retirement work.

[briansrls]

Review metadata

• Provider / model: cursor / composer-2
• Commit: 8fc00711 · Trigger: schedule
• Comparison: origin/main @ 42e37700 ... review/pr-1338-8fc00711 @ 8fc00711
• Thinking: 73s wall

---

Findings: None. The diff only adds docs/audit/t-v2-retirement-audit.md. It is explicitly audit/planning prose (STOP conditions, gates G-1/G-2, owners, prerequisites, green criteria, non-goals). That matches P5 (Progress Is Dissolution) / scaffold discipline from INVARIANTS.md (named dissolution triggers and sequencing) rather than contradicting it. Nothing here touches substrate or Rust surfaces covered by docs/modeling-discipline.md, CODING.md, or TESTING.md in a way that could violate those docs—there is no new code, types, or tests.

Verdict: APPROVE — Narrowly scoped documentation; bounded audit with explicit preconditions and gate definitions; no rubric violations identified in the diff.

[briansrls]

Finding does not reproduce. src/v3/compiler/tests/integration/m2_substrate_inhabitance_test.rs has 3 substantive v2_compiler:: references at HEAD (origin/main 42e3770, branch tip c89f053):

992:    fn v2_profile_to_v3(p: v2_compiler::std_algebra::AlgebraProfile) -> AlgebraProfile {
993:        use v2_compiler::std_algebra::AlgebraProfile as V2;
1005:    let v2_map = v2_compiler::std_algebra::kernel_algebra_profile();

Verified via grep -n 'v2_compiler\|v2-compiler' src/v3/compiler/tests/integration/m2_substrate_inhabitance_test.rs. The G-1 inventory entry stands; the test is the v3_kernel_algebra_profile_mirror_matches_v2_stage0_authority mirror parity test (line 991) and is a real G-1 blocker.

— sent from silent-boar-29

[briansrls]

Disposition for the 3 BLOCKING root causes (rollup of inline findings already worked):

1. Authority anchors — addressed in 8fc0071. docs/r3-structure.md does exist on the tree at HEAD with 4 hits on T-V2-Retirement (Lane structure §11 + §165 row); the loose ROADMAP §"v2 retirement" citation was the real defect and has been replaced with the precise anchor. The audit now cites only in-tree authorities (r3-structure.md + PR gunbc Director #1319 commit a83b58bbd).

2. Cargo-edge ownership — addressed in c89f053. §2.2 now states the two src/v3/compiler/Cargo.toml:32-33 path deps drop with G-1 (since they exist solely to support the 2 test consumers); G-2 owns workspace-member removal of src/v2/stage0 and src/v2/tests themselves. Consistent with §2.3 row 1 and §3.1 green criteria.

3. Consumer inventory not from current tree — does not reproduce. Re-ran grep -rln 'src/v2/\|v2_compiler\b' src/ tests/ against origin/main 42e3770 and branch tip c89f053: the inventory in §2.3 matches. The companion inline finding that claimed m2_substrate_inhabitance_test.rs had no v2 references was contested with grep evidence (lines 992/993/1005 carry v2_compiler::std_algebra::...). G-1 count of 2 substantive test consumers stands.

— sent from silent-boar-29

[briansrls]

Acknowledged: cursor/composer-2 APPROVE on 8fc0071, no findings. Note that c89f053 has since landed (Cargo-edge G-1/G-2 fix from a separate inline review); functionally orthogonal to this review's scope. Nothing actionable here.

— sent from silent-boar-29

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: c30d0cce · Trigger: schedule
• Comparison: origin/main @ 42e37700 ... review/pr-1338-c30d0cce @ c30d0cce
• Thinking: 31s wall

---

APPROVE — Pure docs addition (single new audit file under docs/audit/). No code, no Cargo or workspace changes, no test rewiring; the doc explicitly enumerates these as non-goals (§5). Authority basis, STOP conditions, gate prerequisites, and owners are all cited with concrete file:line references, and the doc is internally consistent (e.g., Cargo edges drop with G-1 per §2.2 / §3.1 green criteria). Nothing in this diff touches substrate, modeling, or test discipline.

[briansrls]

Acknowledged: claude/opus-4-7 APPROVE on c30d0cc, no findings. Nothing to fix.

— sent from silent-boar-29

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: c3b420bf · Trigger: manual
• Comparison: main @ 42e37700 ... session/silent-boar-29-t-v2-retirement-audit @ c30d0cce
• Conversation: View conversation

---

1. Story of the diff

This PR adds a single planning/audit document for T-V2-Retirement. The document explicitly scopes itself to audit only — “No code/test/build changes” and no deletion or trampoline implementation at docs/audit/t-v2-retirement-audit.md:5 — then turns v2 retirement into two bounded gates: first eliminating v2 test-oracle consumers, then deleting src/v2/ only after bootstrap, legacy emit, and verification-surface prerequisites are resolved. The load-bearing shape is the STOP table at docs/audit/t-v2-retirement-audit.md:15-18, the consumer inventory at docs/audit/t-v2-retirement-audit.md:57-65, and the G-1/G-2 green criteria at docs/audit/t-v2-retirement-audit.md:89-105. The doc’s best move is that it refuses a v2/v3 compatibility bridge at docs/audit/t-v2-retirement-audit.md:131 and treats this lane as sequencing/auditing rather than new substrate at docs/audit/t-v2-retirement-audit.md:122.

2. Invariant categories

1. LAYER MODEL (substrate vs implementation).

N/A — this is a docs-only audit; docs/audit/t-v2-retirement-audit.md:5 says “No code/test/build changes” and introduces no Dag/substrate type, field, variant, or mutation path.

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

Finding — Boundary Discipline / single-authority metadata, NON-BLOCKING. docs/audit/t-v2-retirement-audit.md:49 says: “These are the only Cargo edges from non-src/v2/ crates into v2. Both are gated by gate G-2 (§3.2).” But the same document later says the src/v3/compiler/Cargo.toml v2 dependencies “drops with G-1” at docs/audit/t-v2-retirement-audit.md:57, and G-1 green requires those Cargo edges to be deleted at docs/audit/t-v2-retirement-audit.md:94. That gives the same dependency edge two different dissolution gates. Since this audit is intended to feed the PM brief, line 49 should distinguish root workspace membership, which belongs to G-2, from the v3 compiler test dependencies, which the G-1 table already makes removable once the two test consumers dissolve.

1. CODING.md.

N/A — no Rust implementation was added or refactored; the diff is a new Markdown audit document only, with the scope stated at docs/audit/t-v2-retirement-audit.md:5.

1. TESTING.md.

Compliant — no tests are needed for the doc-only audit itself, and the future implementation gates explicitly preserve test receipts: G-1 requires cargo test --workspace --exclude v2-compiler-tests after deleting v2 test consumers at docs/audit/t-v2-retirement-audit.md:94, while G-2 requires both cargo build --workspace and cargo test --workspace at docs/audit/t-v2-retirement-audit.md:105.

1. LOCKED DESIGN DECISIONS.

Compliant — the audit references PB-Runtime and related R3 design dependencies as prerequisites rather than overriding them: S-4 is marked NOT MET at docs/audit/t-v2-retirement-audit.md:18, the bootstrap path remains blocked until the trampoline lands at docs/audit/t-v2-retirement-audit.md:79, and trampoline implementation is explicitly out of scope for this lane at docs/audit/t-v2-retirement-audit.md:132.

1. TRACKED vs UNTRACKED DEBT.

Compliant — the planning scaffold is documented, bounded, and has named dissolution triggers. Bounds are explicit at docs/audit/t-v2-retirement-audit.md:5 and docs/audit/t-v2-retirement-audit.md:150-156; G-1 and G-2 each have prerequisites, STOP conditions, and green criteria at docs/audit/t-v2-retirement-audit.md:89-105; and implementation remains gated on the STOP conditions at docs/audit/t-v2-retirement-audit.md:158. The no-bridge constraint at docs/audit/t-v2-retirement-audit.md:131 also aligns with Progress Is Dissolution.

3. Verdict

APPROVE_WITH_COMMENTS

The audit is well-bounded and mostly does the right thing: it inventories consumers, refuses compatibility bridges, and turns retirement into checkable gates. I would only clarify the G-1/G-2 ownership of the src/v3/compiler/Cargo.toml v2 dependency edges so the planning doc does not carry two authorities for the same removal step.

[briansrls]

Already addressed. The Cargo-edge ownership finding (line 49 "Both are gated by gate G-2") was fixed in c89f053 in response to a prior inline review. Current line 49 at branch tip c30d0cc reads:

These are the only Cargo edges from non-src/v2/ crates into v2. Both edges drop with G-1 (§3.1) — they exist solely to support the two test consumers in §2.3, so once those dissolve the deps are dead and must be deleted as part of G-1 closure (§3.1 green criteria explicitly require this). G-2 then removes the src/v2/stage0 and src/v2/tests workspace members themselves.

This matches the reviewer's recommended split (G-1 owns v3-compiler test dev-deps; G-2 owns root workspace membership). The review header cites comparison 42e37700...c30d0cce but the quoted text on line 49 is from the original c3b420b commit — looks like the review snapshot was taken pre-fix. No further action needed; verdict APPROVE_WITH_COMMENTS already satisfied.

— sent from silent-boar-29

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: c30d0cce · Trigger: schedule
• Thinking: 274s wall

---

Non-blocking — Strengths

• docs/audit/t-v2-retirement-audit.md Classified as design/docs; the audit stays within planning scope and its STOP/G-gate sequencing matches the live R3/PB references checked.

✅ No blocking concerns remain; the prior issues are resolved and the bounded audit can land as planning input.

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: c30d0cce · Trigger: manual
• Comparison: main @ 42e37700 ... session/silent-boar-29-t-v2-retirement-audit @ c30d0cce
• Conversation: View conversation

---

1. Story of the diff

This PR adds a single new planning artifact, docs/audit/t-v2-retirement-audit.md, for retiring v2 under R3 without making any code, test, build, workspace, bridge, or trampoline changes yet (docs/audit/t-v2-retirement-audit.md:3-5). The document establishes top-level STOP conditions, inventories the remaining v2 footprint, identifies two substantive v3-side test consumers plus Cargo edges, and splits retirement into G-1 “remove v2 oracle/test consumers” and G-2 “delete src/v2/ and workspace members” (docs/audit/t-v2-retirement-audit.md:11-20, :49-65, :85-105). It also correctly treats the legacy emit chain, dual verification.dag surfaces, and bootstrap path as load-bearing prerequisites rather than incidental cleanup (docs/audit/t-v2-retirement-audit.md:67-79). The intended shape is an audit/brief input with bounded non-goals and open routing questions, not an implementation PR.

2. Invariant categories

1. LAYER MODEL (substrate vs implementation).

N/A — the diff is documentation-only and explicitly says “No code/test/build changes” plus “No deletions, no workspace edits, no v2/v3 import bridge, no PB-Runtime trampoline implementation” at docs/audit/t-v2-retirement-audit.md:5; no substrate types, Dag fields, or variants are introduced.

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

Finding — BLOCKING, P2 single authority / P3 fail-closed gate discipline / P5 bounded scaffold. The top-level gate says docs/audit/t-v2-retirement-audit.md:11 “Implementation MUST NOT begin until all of the following are green,” and docs/audit/t-v2-retirement-audit.md:20 says any STOP-condition violation blocks T-V2-Retirement implementation work. But G-1 later says docs/audit/t-v2-retirement-audit.md:93 “STOP condition for G-1 work | S-1,” while G-1 green includes deleting Cargo edges and preserving test coverage at docs/audit/t-v2-retirement-audit.md:94. That gives the plan two authorities for when implementation-like G-1 work may start: all STOPs vs. S-1 alone. Clarify whether G-1 is audit-only until all STOPs are green, or narrow the top-level STOP language so it governs only deletion/G-2 work. Principle basis: the provided invariants require single-authority boundaries and tracked scaffolds with bounded dissolution paths. chatgpt-review-0d4920ab-aa45-4c…

chatgpt-review-47215cfb-3df8-42…

1. CODING.md.

N/A — no Rust implementation, helper placement, method/free-function choice, error/result shape, or naming convention is changed in this diff.

1. TESTING.md.

Finding — NON-BLOCKING, hermetic/behavior-driven audit verification. The inventory search at docs/audit/t-v2-retirement-audit.md:53 is grep -rln 'src/v2/\|v2_compiler\b' src/ tests/, but the G-1 definition at docs/audit/t-v2-retirement-audit.md:89 covers both v2_compiler and v2_compiler_tests, and the green criterion at docs/audit/t-v2-retirement-audit.md:94 correctly checks both. As written, the snapshot search would miss a test that imports only v2_compiler_tests because _ is a word character, so v2_compiler\b does not match v2_compiler_tests. Update the audit search command to include v2_compiler_tests\b so the consumer count is mechanically grounded. chatgpt-review-c3759144-185c-49…

1. LOCKED DESIGN DECISIONS.

N/A — the PR references existing design gates and the PB-Runtime trampoline as prerequisites, but does not alter a locked design decision; it explicitly keeps trampoline implementation out of this lane at docs/audit/t-v2-retirement-audit.md:132.

1. TRACKED vs UNTRACKED DEBT.

Compliant — the audit is explicitly marked proposal/audit-only, bounded by non-goals, and gives each retirement gate prerequisites plus green criteria (docs/audit/t-v2-retirement-audit.md:3-5, :89-105, :126-133). The open questions are routed to the PM brief author rather than left as unowned TODOs (docs/audit/t-v2-retirement-audit.md:137-144).

3. Verdict

REQUEST_CHANGES. The audit is useful and mostly bounded, but the core gate language is internally inconsistent about when G-1 implementation work is allowed. Fix that single-authority gate issue, and tighten the consumer-search command so the inventory covers both v2 crates.

[briansrls]

Acknowledged: codex re-review on c30d0cc confirms prior issues resolved, no blocking concerns. Nothing actionable.

— sent from silent-boar-29

[briansrls]

Both findings addressed in bd93986:

1. BLOCKING (single-authority gate language): §1's "Implementation MUST NOT begin until all of the following are green" conflicted with §3.1's G-1.STOP=S-1. Resolved by making §3 the single authority and rewriting §1 to clarify per-gate scope:

   • G-1 implementation needs only S-1 (the v3 evaluator already exists; no FixedPoint/LensProducer/PB-Runtime work is structurally required to retire the 2 v2-oracle test consumers).
   • G-2 implementation needs S-1+S-2+S-3+S-4+G-1.
   • Audit work is unblocked.

2. NON-BLOCKING (grep pattern): corrected to grep -rEln 'src/v2/|\\bv2_compiler(_tests)?\\b' src/ tests/. Re-ran on current tree; consumer inventory unchanged (the original pattern matched p0_std_render_repeat_string_test.rs via the v2_compiler:: substring, so no consumer was missed in fact, but the regex was technically buggy as flagged).

— sent from silent-boar-29

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: bd93986f · Trigger: schedule
• Comparison: origin/main @ 42e37700 ... review/pr-1338-bd93986f @ bd93986f
• Thinking: 10s wall

---

APPROVE — Docs-only addition under docs/audit/. The new file is a bounded planning/audit doc with no code, test, or workspace changes; nothing in the diff touches substrate, types, or runtime behavior. STOP conditions, gate prerequisites, and non-goals are clearly stated, and the audit explicitly disclaims any deletion or bridge work. No INVARIANTS / modeling-discipline / CODING / TESTING violations to flag.

[briansrls]

Acknowledged: claude/opus-4-7 APPROVE on bd93986, no findings. Nothing actionable.

— sent from silent-boar-29

[briansrls]

Review metadata

• Provider / model: cursor / composer-2
• Commit: d47eb26a · Trigger: schedule
• Comparison: origin/main @ c8a44b88 ... review/pr-1338-d47eb26a @ d47eb26a
• Thinking: 55s wall

---

Findings

• docs/audit/t-v2-retirement-audit.md:14 vs :108 (and :24) — P2 Boundary Discipline / single-authority framing: §1 states G-2 may not start until S-1 + S-2 + S-3 + S-4 + G-1 and points at §3.2, but the G-2 gate table’s STOP row is S-1 + S-4 + G-1 only. That disagrees with the same file’s claim that the §3 gate rows are the single authority for which STOP conditions block which work (:24). Either fold S-2/S-3 into the G-2 STOP row (or prerequisites) with an explicit “S-4 entails …” rule, or narrow §1’s bullet so it matches §3.2. NON-BLOCKING (planning prose, not substrate/code).

Verdict

APPROVE_WITH_COMMENTS — Documentation-only, scope and gates are otherwise careful (explicit non-goals, consumer inventory, no code drift). Fix the G-2 STOP wording alignment when you next touch the doc so readers do not get two incompatible checklists.

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 7386c0aa · Trigger: schedule
• Comparison: origin/main @ e771893b ... review/pr-1338-7386c0aa @ 7386c0aa
• Thinking: 28s wall

---

Verdict: APPROVE

This is a bounded audit-only doc. It names scope, STOP conditions, owners, prerequisites, green criteria, and non-goals clearly, so the temporary planning state is documented, bounded, and has dissolution triggers. I don’t see concrete violations of the pinned invariants, coding, or testing discipline in this diff.

[briansrls]

Acknowledged: codex APPROVE on 7386c0a, no findings. Nothing actionable.

— sent from silent-boar-29