Codebase Audit Maintainer

If conflicts exist, update lower-priority docs to match higher-priority sources.

Workflow

1. Inventory active claims

• Extract all "done/complete/active/deferred" statements from active plans.
• Build a checklist keyed by task id.

2. Verify each claim against code reality

• Confirm implementation exists at concrete file/line locations.
• Confirm commit evidence exists on the intended branch.
• Confirm verification command(s) exist and were run.

3. Refresh architecture audit docs

• Update subsystem docs only where behavior/contracts changed.
• Keep callgraphs, entrypoints, invariants, and known traps aligned with current source.
• Mark stale sections with TODO(stale-audit): instead of silently deleting context.

4. Reconcile branch/worktree/stash hygiene

• Ensure critical commits are reachable from the integration branch.
• Reduce stash count to zero by explicit integrate/drop decisions.
• Record unresolved risk in handoff if anything remains.

5. Publish evidence-backed handoff

• Emit one status block with: completed, deferred, risks, next command.

Claim Verification Rules

A planner claim is valid only when all pass:

• Code Evidence: file path + line reference.
• Commit Evidence: hash containing the change.
• Verification Evidence: command + pass/fail result.
• Status Alignment: ROADMAP is authoritative; plans/STATE must align to it.

If any evidence is missing, mark NOT VERIFIED and downgrade completion status.

Required Outputs

Write/update:

• docs/research/ascii/<date>-claim-verification.md
• Relevant plan docs in docs/plans/ (status corrections only when evidence supports changes)
• Optional handoff in docs/plans/handoffs/<date>-<topic>.md

Each verified item must include:

• claim text
• evidence paths
• commit hash
• verification command(s)
• final verdict (verified, partial, not verified)

Suggested Cadence

• Weekly: full audit sweep (claims + architecture docs + git hygiene).
• Per PR/merge: focused audit on touched subsystems.
• Pre-release: full sweep plus pipeline playability verification.

Integration With Existing Skills

• Use agent-context-doc-health for cross-doc and git-state alignment.
• Use xp-pipeline-verifier for final pipeline completion gates.
• Use subsystem skill docs (engine-render, world-loading, editor-asciiid) as audit baselines.

Guardrails

• Never mark complete from test counts alone.
• Never trust planner prose without source/commit verification.
• Never leave ambiguous status wording ("mostly done", "should be done").
• Prefer small, traceable doc updates over large speculative rewrites.