doc-audit-2026-05-07

Documentation Audit — 2026-05-07

Scope: Reconcile every doc in ./docs, root README.md / CLAUDE.md, and nested READMEs against docs/PROJECT-ORCHESTRATION-HANDBOOK.md (rewritten in 35ee16a) and the current state of the code.

Reference: Part of #144.

Method

1. Read handbook end-to-end (1126 lines) — treat as source of truth.
2. Inventory actual code: skills/ (13), commands/ (16), agents/ (4), registry/skills/ (31), registry/commands/ (18), registry/agents/ (17), hooks/ (26), bin/ (5), profiles/ (3), schemas/ (3), Makefile, root claude-*.sh (4).
3. Read each doc and root file; classify: aligned (matches handbook + code), needs-update (drift, but content still valid), archive (superseded, leave a redirect).
4. Note specific drifts so chunk 3 can act without re-reading every file.

Classification

Root files

File	Verdict	Drift
README.md	needs-update	Bad component counts (“12 universal skills, 28 registry / 8 commands / 3 universal agents, 12 registry agents / 12 hooks” — actual: 13/31, 16, 4/17, 26). Mentions cdr reprovision (legacy alias). Missing cdfork, cdg, cds, claude shell wrapper, warp CLI, make check. Doesn’t mention GitHub-Issues hierarchy or the handbook itself as the entry point.
CLAUDE.md	needs-update	Inaccurate counts (~10 skills, ~8 commands, ~4 agents, ~27 registry skills / ~16 commands / ~16 agents). Priority labels listed as p1/p2/p3/p4 but actual GitHub labels are p1-critical/p2-high/p3-medium/p4-low. Missing claude shell wrapper section. Mentions cdfork/cdfork-pair only — drops warp CLI, bin/dev-up, make check.

./docs/ files

File	Verdict	Drift / Notes
PROJECT-ORCHESTRATION-HANDBOOK.md	aligned	Source of truth. Improvements in chunk 4.
prime-directive.md	aligned	Matches handbook §1 verbatim. State ownership map correct. No changes.
vision.md	aligned	Living vision doc; handbook §1 references it. Last updated 2026-04-11; vision content current.
cdfork-guide.md	aligned	Matches handbook §8. Cross-links to vision and research dir. No drift.
dev-lifecycle.md	aligned	Matches handbook §5. dev.json schema, adapter table, warp-drive integration table all current.
warp-drive-guide.md	aligned	Matches handbook §7. Phase table, warp CLI, hook table, config table all current. Cross-links to token-monitoring.md and dev-lifecycle.md.
token-monitoring.md	aligned	Internal reference for token capture pipeline. Correctly describes state-machine.js, token-snapshot.js, token-report.js, JSONL persistence.
branch-config.md	needs-update (small)	One reference to /auto-loop (“Same as warp-drive”) in the Consumer Commands table. Auto-loop is being removed; either drop the row or move it under a “(legacy)” note. Otherwise correct.
verification-system.md	needs-update (small)	Refers to “30 projects” (current projects.json is unknown). Test counts (34 / 75 / 13) drift if state machine grows. Otherwise mechanically correct. Re-verify counts against Makefile.
backup-recovery.md	needs-update (small)	Mentions cdr (claude disaster recovery) alias as if first-class. Handbook §13.1 lists cdr as (Legacy) sync requirements index. The two purposes have collided — cdr is also the disaster-recovery alias per bob-install.sh. Either pick one, or document both clearly. Recovery procedure itself is correct.
automation-behavior.md	needs-update	Decision-classification table is accurate but doesn’t mention warp-drive specific behaviors (already added in handbook §7). Consider rolling this file into the handbook as the canonical reference, leaving a redirect — its content is now duplicated by handbook §7.1 and the table in §12.8.
new-machine-setup.md	needs-update	Step 5 manually creates ~/bin symlinks — handbook §3.1 says bob-install.sh handles aliases (cdprov, cdr, cdfork). The ~/bin symlink dance for cdi/cdb/cdp/cdl/cdg/cds is NOT done by bob-install.sh — verify which script provisions these. Step 8 mentions cdr reprovision (legacy). PATH instruction export PATH="$HOME/bin:$PATH" is sensible but should also mention ~/.claude/bin for warp/dev-up.
project-setup-guide.md	needs-update	Only mentions cdi / cdl / cdb / cdp. Missing cdprov (manifest provisioning is now the canonical path per handbook §3.4). Section 9 Product Planning Workflow correctly mentions /vision /capability /requirement /warp-drive. Symlink direction explanation correct (project → BOB_SOURCE).
NATURAL-LANGUAGE-GUIDE.md	aligned	Pure terminology reference. No drift.
how-to-auto-loop.md	aligned	Already a redirect stub pointing to handbook. Keep.
PM-CHEATSHEET.md	aligned	Already a redirect stub pointing to handbook. Keep.
PROJECT-MANAGEMENT-REFERENCE.md	archive	Massive drift. Describes the deprecated REQ-NNNN/SOL-NNNN markdown PM system, auto-loop (not warp-drive), and forbidden directory patterns (.claude/project-management/, .claude/requirements/, .claude/journal/decisions/). Status enums, file layouts, entity glossaries — all superseded by GitHub Issues hierarchy. Handbook explicitly notes “(predates GitHub Issues migration; due for its own audit)” in §17. Action: move to docs/archive/2026-05-pm/ with a redirect stub left in place.
pm-conventions.md	archive	Same kind as PROJECT-MANAGEMENT-REFERENCE.md — defines the forbidden file/directory patterns as if they were the convention. Action: archive with redirect.
PM-WORKFLOWS.md	archive	Mermaid diagrams of /spec, /risk assess, /release plan, /change create, /backlog add, /standup, /retrospective workflows. Most of these commands are deprecated registry commands per handbook §12.9. Action: archive with redirect.
iac-audit-2026-02-19.md	aligned	Historical audit snapshot, dated. Keep as historical reference (does not claim to be current).
automation-workflow.txt	archive	Pre-BoB brain-dump narrative (“Create requirements for this functionality.” — the user is asking themselves what to build). Predates the framework’s existence in current form. Action: move to docs/archive/.
deploy-skill-prompt.md	archive	One-shot prompt that was used to generate the deploy-cloudflare registry skill. The skill exists at registry/skills/deploy-cloudflare/. The prompt is no longer load-bearing. Action: move to docs/archive/.

Nested READMEs

File	Verdict	Drift
templates/seed/README.md	aligned	Documents seed file naming, idempotency, lifecycle states, test users. Matches handbook §5.3 + dev-lifecycle.md. No changes.

Existing archive

docs/archive/2026-02-pm/ already contains old backlog.md, bugs/, product-spec.md, rebob-log.md, releases/, traceability-matrix.md. Use the same date-stamped subdir convention for the new archive: docs/archive/2026-05-pm/.

Summary counts

• Aligned (no change): 9 docs (handbook, prime-directive, vision, cdfork-guide, dev-lifecycle, warp-drive-guide, token-monitoring, NATURAL-LANGUAGE-GUIDE, iac-audit-2026-02-19, how-to-auto-loop, PM-CHEATSHEET, templates/seed/README)
• Needs-update: 6 docs (README, CLAUDE, branch-config, verification-system, backup-recovery, automation-behavior, new-machine-setup, project-setup-guide)
• Archive (with redirect): 5 docs (PROJECT-MANAGEMENT-REFERENCE, pm-conventions, PM-WORKFLOWS, automation-workflow.txt, deploy-skill-prompt)

Cross-cutting fixes

These appear in multiple docs and should be normalized when chunk 3 runs:

1. Priority labels: Use p1-critical / p2-high / p3-medium / p4-low (the actual labels), not the abbreviated p1/p2/p3/p4 form. Handbook §4 has it right; CLAUDE.md needs the fix.
2. Component counts: README and CLAUDE.md both quote outdated counts. Pull live numbers when updating: 13 universal skills, 16 universal commands, 4 universal agents, 31 registry skills, 18 registry commands, 17 registry agents, 26 hooks.
3. cdr ambiguity: cdr shows up as both “claude disaster recovery” (backup-recovery.md) and “(legacy) sync requirements index” (handbook §13.1). The bob-install.sh wrapper aliases cdr to scripts/lib/cdr.sh — confirm which it actually is and remove the other usage.
4. /auto-loop references: Handbook deprecates /auto-loop. Sweep branch-config.md and any other doc that lists it as a current command — mark legacy or remove.

Improvements to fold back into the handbook (chunk 4)

Findings during this audit that warrant edits to the handbook itself:

1. §3.1 / §13.1 — disambiguate cdr. The handbook lists cdr as legacy in §13.1 but bob-install.sh adds it as an alias and backup-recovery.md treats it as the recovery CLI. Pick one canonical meaning and document.
2. §3.7 — Makefile target counts. Handbook lists targets but the test-count specifics in verification-system.md (34 schemas / 75 warp-drive / 13 checks) aren’t surfaced. Adding a one-line “current test counts” pointer or a make help example would close the loop.
3. §13.4 — bin/ count. Handbook lists 5 entrypoints (warp, cdfork, cdfork-pair, dev-up, dev-health). Verified — all 5 exist on disk. No fix needed; just confirming.
4. §14 — hook count. Handbook lists ~26 hooks across events. Verified — hooks/ has exactly 26. README’s “12” is the gap.
5. §17 — note the audit. Add this audit doc to See Also so the methodology is discoverable for the next audit cycle.

These get implemented in chunk 4 alongside the link sweep and user-global drift check.