Doc-alignment audit: close documentation gaps (2026-06-29)

[joshua-temple]

Audit of docs vs current code (b1ff53f). No stale/contradictory/broken defects; gaps are MISSING surface. HIGH: cli-reference.md missing the status family (incl. consistency --fix) and the rollback family (preflight/finalize). MED: cli-reference missing graph; configuration.md missing action_pins / pin_mode (prose only) / release_trigger / validate_check / merge_queue rows; hotfix orphan self-heal (--repo, #408) under-documented. TRIVIAL: coverage-matrix callbacks topology row, per-component reserve note. Cross-cut: status consistency --fix is gapped in BOTH audits. Report: ~/llm/plans/cascade/2026-06-29-doc-alignment-audit.md

---

In-code docs (audit scope gap - added 2026-06-29)

The doc-alignment audit scoped to docs/src/content/docs/ and did NOT cover in-code doc comments. A separate (verified) finding:

• Stale reserved-shape comments in internal/config/types.go. The v1 reserved-shape per-callback fields (parse + structural validation only) headers at ~534/560/620/693 are stale: the fields under them (Secrets, Permissions, RunsOn, Concurrency) are now wired into generation (13/14/4/19 generator refs respectively), not parse-only. Verify each reserved-shape header against the generator and correct the comments for the fields that shipped. (Genuinely-reserved: Components/feat: independently versioned components in a single manifest #176, deployable Version, TargetSHA, VersionOverrides pointer - leave those.)
• Consider a one-time in-code doc-comment sweep (the audit's surface was docs/ only).

[joshua-temple]

Branch-protection docs now also need the new --apply --token --repo --branch --api-url apply path (added in #416): document that the default still emits JSON for an operator to apply, and the opt-in apply mode applies directly with a caller-supplied scoped token (operator needs repo-admin authority on the token; GITHUB_TOKEN is insufficient).

[joshua-temple]

Doc-alignment backlog closed across three PRs: cli-reference command families (status/rollback/graph incl the #418 first-env guard) in #421; configuration.md field rows (action_pins, pin_mode, release_trigger, validate_check, merge_queue) in #424; hotfix orphan self-heal docs + corrected stale reserved-shape comments in types.go + the callbacks coverage-matrix row in #425. Each doc claim was verified against current code. Remaining nit (out of scope): the coverage-matrix 'Last validated' tip still reads v0.5.1.