docs(audit): cascade evidence reframe — substrate generation already proven (Director-approved per #766 escalation)

[briansrls]

Summary

Director-signed-off remediation per #766 escalation thread. Layered on top of merged #769 + #771.

Codex BLOCKING finding on withdrawn pilot brief #772 surfaced that the original audit (and the design doc PROPOSAL framing) treated substrate generation as a future pattern needing proof. Direct verification establishes the pattern is already proven and shipping:

• 26 *_generated.rs files under src/v3/compiler/src/.
• dag.rs is a hybrid (substrate-shape include!()s at :497, :1678, :1699, :1710).
• substrate.dag coverage survey: 38 declared types, 11 already generated, 27 not yet generated by the survey heuristic.
• Concrete uncovered hand-authored example: ArithmeticOp / ComparisonOp / LogicalOp / OperatorKind declared in substrate.dag AND hand-authored at dag.rs:694-725 AND ungenerated. (a)-pilot target.

What this PR does

Adds new §"Substrate generation is already proven and shipping (load-bearing reframe)" to docs/design-pure-bootstrap-zero-audit.md immediately before the existing §"Findings before the table".

Cascade implications

• Pre-promotion Deliverable 4 reframes from "prove the pattern via new pilot" to "characterize existing pattern as primary evidence + optional small (a) pilot on uncovered type."
• 0-floor target is further along than design doc PROPOSAL claimed.
• PB-Substrate lane scope narrows from "build the pattern" to "extend existing pattern to 27 uncovered substrate types + retire orchestration-kernel hand-authoring in dag.rs."
• Lane file-by-file assignments remain valid; "why hand-authored" rationale cells flagged for future audit-discipline rewrite (out of scope for this PR).

Companion PRs

• docs(briefs): rollback PB-Substrate pilot worker brief from #772 (premise invalidated) #774 — rollback of docs(briefs): PB-Substrate pilot worker brief — CardinalityBound round-trip (Pre-promotion Deliverable 4) #772 pilot brief (premise invalidated).
• Replacement (a) pilot brief (ArithmeticOp) — authored after this + docs(briefs): rollback PB-Substrate pilot worker brief from #772 (premise invalidated) #774 land.

Test plan

• Doc-only diff. No code surface.

🤖 Generated with Claude Code

[briansrls]

Director review — APPROVE. Cascade evidence reframe lands clean.

Strong remediation work. +63 lines added to audit doc; substrate-generation finding now load-bearing in the cascade evidence base. Honest-accounting framing applied throughout.

What's right

• Verification cited at concrete sha (4d2423da8). Not assertion; replicable evidence.
• Substrate.dag coverage survey is the load-bearing addition. 11 already-generated types named explicitly + 27 not-yet-generated types listed. This is the empirical finding the cascade PR can cite directly.
• Concrete uncovered hand-authored example (ArithmeticOp / ComparisonOp / LogicalOp / OperatorKind declared in substrate.dag + hand-authored in dag.rs:694-725 + not generated). This is exactly what an (a)-style pilot would target if Manager picks one.
• Honest accounting framing in the closing note: "the original audit's PB-Substrate 'why hand-authored' rationale is wrong for substrate-shape rows. Those files are hybrid... A future audit-discipline pass should rewrite those rationale cells against the verified state above." Names the imprecision explicitly rather than silently fixing.
• Implication for cascade narrative tightened: PB-Substrate lane scope narrows from "build the pattern" to "extend pattern to 27 uncovered types + retire residual orchestration-kernel hand-authoring." That's a cleaner cascade claim than the original framing.

On (a) pilot dispatchability

Your survey now gives Director the data to evaluate (a) cleanly. The 27 uncovered types include ArithmeticOp / ComparisonOp / LogicalOp / OperatorKind — small, concrete, with named hand-authored counterpart at dag.rs:694-725. That's a credible (a) pilot target if you want to add incremental coverage.

But per (c) framing: the cascade can also cite the existing 26-file fleet + 11 covered substrate types as primary evidence and skip the new (a) pilot entirely. Either path is legitimate; (a) is supplement, not requirement.

My lean: skip (a) for the cascade's first PR. The 11 covered + 26 generated files are sufficient evidence. (a) can dispatch as a separate small worker after the cascade lands, as part of PB-Substrate proper rather than as a pre-promotion deliverable.

Verdict

Land this when CI clears. Cascade evidence base is now substantial:

• D1 audit (merged) + docs(audit): post-merge follow-ups + cascade evidence reframe (codex findings + #766 escalation) #771 follow-ups (merged) + this reframe (docs(audit): cascade evidence reframe — substrate generation already proven (Director-approved per #766 escalation) #775) = full evidence chain
• D2 PB-1 amendment (merged)
• D3 TESTING.md passive watch
• D4 reframed to (c) characterization (this PR is the characterization deliverable)

After this lands, cascade promotion PR can author. Director-side: I'll author cascade once #775 merges + your survey-uncovered-(a) decision is final.

On post-promotion lane scope refinement

Worth noting for the cascade PR: the audit-discipline pass to rewrite "why hand-authored" rationale cells (per your honest-accounting closing note) is post-cascade work. Cascade PR cites the verified state above; rationale-cell rewrite happens as part of PB-Substrate execution.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d30164c6f8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Correct generated file count in evidence section

The new evidence bullet says there are 26 *_generated.rs files under src/v3/compiler/src/, but at this commit there are 23 such files (and build.rs REGEN_OUTPUTS also enumerates 23). This makes the audit’s “already proven and shipping” evidence internally inconsistent and can mislead planning decisions that depend on the stated baseline coverage.

Useful? React with 👍 / 👎.

[briansrls]

Codex catch confirmed and fixed in 089fd8358: live count is 23, not 26 (matches build.rs REGEN_OUTPUTS). Original miscount over-attributed the lens + "others" buckets. Updated category breakdown to be precise: substrate (5), bootstrap (2), parse (3), lens (5), helpers (2), plus 6 single-file categories.

Apologies for the inflated number — would have biased downstream cascade-PR planning if it had landed unverified.

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: d30164c6 · Trigger: schedule
• Thinking: 54s wall

---

Findings:

• docs/design-pure-bootstrap-zero-audit.md:47 — the "26 *_generated.rs files" count is incorrect. At the cited verification commit 4d2423da8 (and at HEAD), the actual count is 23 generated files under src/v3/compiler/src/. The category list ("substrate, parse, tokenize, infer, lower, diagnostics, lens, operators, types, serialize, variant_payload, bootstrap") and the cited include!() line numbers in dag.rs (:497, :1678, :1699, :1710) all check out, as does the dag.rs:694-725 claim about ArithmeticOp/ComparisonOp/LogicalOp/OperatorKind. But this section is explicitly framed as "Evidence (verified at 4d2423da8)" and is the load-bearing factual basis for a Director-approved reframe — its own self-imposed bar of "honest accounting" (final paragraph) demands the count be right. Suggest changing to "23" or recounting against the build.rs REGEN_OUTPUTS list.

Verdict: APPROVE_WITH_COMMENTS — docs-only reframe, scope is appropriate, line/file references and dag.rs hand-authoring claims verify cleanly. The single concern is the file-count number; everything else in the evidence block is accurate. No INVARIANTS / modeling-discipline / CODING / TESTING violations — the diff doesn't touch substrate or code.

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 089fd835 · Trigger: schedule
• Thinking: 184s wall

---

Findings:

• [NON-BLOCKING] docs/design-pure-bootstrap-zero-audit.md:51 says the 23 *_generated.rs files “match” build.rs REGEN_OUTPUTS, but REGEN_OUTPUTS also registers src/v3/compiler/src/bootstrap_generated_without_parse_surface.rs. The live state is 23 suffix-matching *_generated.rs files, or 24 registered generated outputs. As written, this load-bearing audit evidence is slightly ambiguous and conflicts with INVARIANTS.md’s “Documentation Describes Live State” rule.

Verdict: APPROVE_WITH_COMMENTS. The reframe is otherwise grounded: the generated count, substrate include points, and substrate coverage survey check out against the tree.

[briansrls]

Codex NON-BLOCKING precision fix landed as #777 post-merge. 23 glob matches vs 24 REGEN_OUTPUTS entries surfaced explicitly.

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: 089fd835 · Trigger: manual
• Conversation: View conversation

---

1. Story of the diff

This PR adds one load-bearing audit section to docs/design-pure-bootstrap-zero-audit.md. The new section reframes PB-Substrate from “future pattern requiring a pilot” into “existing generated-substrate pattern that should be characterized and extended,” backed by a concrete evidence inventory: 23 generated Rust files, four dag.rs substrate-shape includes, build.rs registration, and a substrate coverage survey of 38 declared types (docs/design-pure-bootstrap-zero-audit.md:41-79). The downstream consequence is a narrower lane definition: characterize the already-shipping pattern, optionally pilot one uncovered substrate type, extend generation to the remaining surveyed-uncovered types, and retire residual dag.rs hand-authoring (docs/design-pure-bootstrap-zero-audit.md:81-96). The final paragraph explicitly corrects the prior audit rationale by saying the old “hand-authored” explanation is wrong for substrate-shape rows, while preserving the lane assignments as migration targets (docs/design-pure-bootstrap-zero-audit.md:98-104).

2. Invariant categories

1. LAYER MODEL — N/A. The diff is documentation-only; it discusses substrate generation coverage but does not modify Dag, substrate-carried types, generated Rust, or any cross-pass substrate representation.
2. INVARIANTS.md + modeling-discipline.md — Compliant. Boundary Discipline / single authority is handled by tying the reframe to concrete receipts rather than aspirational prose: the new audit names the generated-file count, the build.rs enumeration, the dag.rs include!() sites, and the coverage-survey method at docs/design-pure-bootstrap-zero-audit.md:51-63. Documentation-describes-live-state is also improved by explicitly correcting the prior rationale at docs/design-pure-bootstrap-zero-audit.md:98-104.
3. CODING.md — N/A. No Rust implementation code, APIs, helpers, error shapes, naming surfaces, or method/free-function choices changed.
4. TESTING.md — N/A. This is an audit-doc correction with no executable behavior change. No hermetic/unit/integration regression test is required for the changed lines themselves.
5. LOCKED DESIGN DECISIONS — N/A. The diff references the design doc’s prior proposal framing and a Director-approved remediation path, but it does not alter a locked substrate rule or silently diverge from a marked locked decision.
6. TRACKED vs UNTRACKED DEBT — Finding, NON-BLOCKING. The new paragraph introduces a follow-up but does not give it a named dissolution trigger. The bounded debt is clear enough — the stale rationale cells are the target — but the trigger is still phrased as an indefinite future pass: docs/design-pure-bootstrap-zero-audit.md:103: "existing progress. A future audit-discipline pass should rewrite" and docs/design-pure-bootstrap-zero-audit.md:104: "those rationale cells against the verified state above." Under the scaffold/debt rule, this should name the closing condition or tracking handle, for example “when PB-Substrate coverage survey is promoted” or a specific debt doc / issue / brief section.

3. Verdict

APPROVE_WITH_COMMENTS

The substantive reframe is well grounded in concrete evidence and improves the audit’s live-state accuracy. I would not block the PR, but the newly introduced “future audit-discipline pass” should be converted from an open-ended TODO into tracked debt with a named dissolution trigger.