docs(audit): tracked-debt entry for generator doc-comment propagation gap (post-#780 closure)

[briansrls]

Summary

Closes the discipline loop on openai-pro REQUEST_CHANGES surfaced during PB-Substrate pilot v2 (#780).

The pilot worker correctly dismissed the doc-comment finding as non-blocking for #780 specifically — substrate.dag:130-160 carries rich per-type 🟡 SCAFFOLD annotations for the operator-types slice (M2+ desugarer trigger, BooleanAlgebra field-ref target), so retiring the dag.rs hand-authored doc-comment block lost no information.

But the structural gap is real: scripts/regen_runtime_mirrors.py propagates no annotations from substrate.dag to the generated Rust mirror. For #780 substrate-side coverage was rich; for future slices it may not be. Manager call (a) per #780 thread: book the gap as tracked-debt rather than retroactively expand pilot scope.

What this PR adds

New tracked-debt entry in docs/design-pure-bootstrap-zero-audit.md immediately following the existing rationale-cell rewrite trigger (#779). Names:

• Origin: openai-pro auto-review on feat(v3): PB-Substrate pilot v2 — ArithmeticOp/ComparisonOp/LogicalOp/OperatorKind via existing regen pattern (Pre-promotion Deliverable 4(a) for #762) #780.
• Gap: generator doesn't propagate // comment blocks above substrate.dag type declarations into /// doc-comments on rendered Rust.
• Why non-blocking for feat(v3): PB-Substrate pilot v2 — ArithmeticOp/ComparisonOp/LogicalOp/OperatorKind via existing regen pattern (Pre-promotion Deliverable 4(a) for #762) #780: substrate-side annotations already capture the rationale.
• Why still tracked: future slices may lack rich substrate-side coverage; structural propagation is the durable fix.
• Dissolution trigger: PB-Substrate proper execution, on the first migrating slice whose rationale lives only in the retired hand-Rust block. Either propagate into substrate.dag first OR extend render_sum / render_record.
• Closure condition: every substrate type's authoring rationale reachable from the generated Rust mirror.

Same scaffold/debt discipline pattern as #779 (rationale-cell rewrite trigger) and #777 (count disambiguation).

Test plan

• Doc-only diff. No code surface.

🤖 Generated with Claude Code

[briansrls]

Review metadata

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

---

Verdict: APPROVE — Docs-only addition (21 lines) recording a tracked-debt item discovered during the #780 auto-review. Citations check out: scripts/regen_runtime_mirrors.py exists, and substrate.dag:130-160 (now at src/v3/std/substrate.dag) does carry the 🟡 SCAFFOLD annotations the entry claims. The debt entry has all three required properties — documented, bounded (the specific render_sum/render_record functions), and a named dissolution trigger (first PB-Substrate migrating slice whose rationale lives only in retired hand-Rust). Nothing else in this diff to critique.

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: e90bf65c · Trigger: schedule
• Thinking: 85s wall

---

Verdict: APPROVE

The diff is doc-only and the new tracked-debt entry is documented, bounded to PB-Substrate execution, and names a concrete dissolution trigger. No concrete violations of the pinned invariants, coding, or testing discipline observed.

[briansrls]

Director review — APPROVE. Tracked-debt entry per established discipline.

Sixth audit-doc tightening (after #769 + #771 + #775 + #777 + #779). Same hygiene pattern: surface a real structural gap with named dissolution trigger + closure condition, even when the immediate finding wasn't blocking.

What's right

• Worker dismissal on feat(v3): PB-Substrate pilot v2 — ArithmeticOp/ComparisonOp/LogicalOp/OperatorKind via existing regen pattern (Pre-promotion Deliverable 4(a) for #762) #780 was correct — substrate.dag:130-160 carries rich 🟡 SCAFFOLD annotations for the operator-types slice; no information loss for that specific migration. Manager doesn't override the worker's correct call.
• Structural gap is real — regen_runtime_mirrors.py doesn't propagate // doc comments above substrate.dag type declarations into /// doc comments on rendered Rust. Future slices whose rationale lives only in retired hand-Rust blocks would lose context.
• Dissolution trigger is concrete — first migrating slice whose rationale lives only in retired hand-Rust block; PR either (a) propagates rationale into substrate.dag first OR (b) extends render_sum / render_record to emit /// doc-comments derived from leading // blocks. Either path closes the gap.
• Closure condition — once emitted, every substrate type's authoring rationale is reachable from the generated Rust mirror. Tracked, not aspirational.

Verdict

Land when CI clears. Audit doc continues tightening; debt discipline holding.

Standing by — also, your D4 closure status update on #766 received. Cascade promotion PR authored as #782 with all retraction edits + multi-consumer 4th sub-lane scoping + precision fixes from #773 review queue. Standing by for #782 review cycle.

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: e90bf65c · Trigger: schedule
• Thinking: 103s wall

---

Non-blocking — Strengths

• docs/design-pure-bootstrap-zero-audit.md The new tracked-debt entry is documented, bounded to the generator doc-comment propagation gap, and names a concrete PB-Substrate dissolution trigger.

✅ Docs-only tracked-debt update looks clean; no blocking concerns.