Audit

acta:audit

The trust check. Acta's whole value is a trustworthy engineering memory — this verifies the docs haven't drifted from reality. Read-only by default: it reports; it fixes only mechanical things when asked (--fix), and it never fabricates content or guesses.

Shared resources at ${CLAUDE_PLUGIN_ROOT}/acta/: doc-catalog.md (the contract), disciplines.md, project-types.md, principles.md.

Language

Write findings and any persisted items in the project's documentation language (registry language:, default English); talk to the user in the language they use. See ${CLAUDE_PLUGIN_ROOT}/acta/principles.md.

Pre-condition

Read .claude/acta.md (registry) and ${CLAUDE_PLUGIN_ROOT}/acta/doc-catalog.md. If there is no registry, this project isn't set up with Acta yet → suggest /acta:build (greenfield) or /acta:adopt (existing code). Don't guess a doc set without them.

Checks

Run these read-only checks and collect findings. Rank each 🔴 broken · 🟡 drift/stale · 🔵 hygiene.

1. Brain & index integrity — CLAUDE.md has the <!-- acta:index:start/end --> block and its links resolve; docs/README.md lists exactly the docs on disk (no missing, no orphan); registry rows match the filesystem.
2. Broken links — every relative link inside docs/** (and the brain) points to an existing file.
3. Doc ↔ code drift — compare docs against the code and flag mismatches:
   • stack in arch-overview / registry vs package.json / pyproject.toml / go.mod / etc.
   • endpoints in api.md vs routes; env-var names in env-vars.md vs .env.example (the committed template only — never open a real .env/.env.local; compare names, never values); project-structure tree vs the actual top-level folders; tables in database-design vs schema/migrations.
   • "doc says X, code says Y" → report both sides.
4. Stale / empty — docs still mostly TBD; updated: far behind recent code changes; scaffolds never filled.
5. Contradictions — best-effort scan for conflicting statements across docs (e.g. PRD "no backend" vs architecture "REST API"). Flag them; never resolve by guessing.
6. Conventions — filename casing (root meta UPPERCASE, docs/** lowercase kebab-case); docs living outside the catalog's paths; disciplines/packs in the registry vs what's actually on disk. Do not flag the skill-owned areas docs/design/, docs/business/, docs/legal/ as orphans — they are valid (see the catalog's "Skill-owned areas" note).
7. Anti-bloat — in-place docs that have grown append-only (e.g. PROGRESS.md accumulating dated log lines instead of a snapshot); oversized docs that should be consolidated per their growth policy.
8. Design consistency (only if docs/design/ exists) — the code's real styling vs the design doc-base:
   • rogue colors / spacing / fonts / type used in code but not in tokens.md (and its granular docs — color.md, typography.md, spacing-layout.md, motion.md — where present); a drifted styling approach vs design-system.md.
   • components or variants/states in code missing from components.md.
   • DDR integrity (full tier): docs/design/decisions/README.md index matches the files on disk; no DDR points to a superseding DDR that doesn't exist.
   • a broken or missing {{DESIGN_LINKS}} block in the brain (design docs exist but the "Design & brand" bullet is absent or its links don't resolve). Flag them → the fixer is /acta:track (design sync).
9. Business consistency (only if docs/business/ exists) — a price / plan / tier in the code or config (e.g. a Stripe price, a plans table) that disagrees with pricing.md; a monetization model in code not reflected in business-model.md. Flag the drift → the fixer is /acta:business. (Read-only; never rewrite pricing.)
10. Legal consistency (only if docs/legal/ exists) — legal-relevant reality in the code not reflected in the briefs: cookies / analytics / trackers with no consent.md entry; a data field or vendor / sub-processor absent from data-processing.md; a market/region served that the briefs' regimes don't cover; open "⚠️ needs lawyer re-review" items. Flag them → the fixer is /acta:track (legal sync). (Never write binding legal text or give legal advice.)

Output

Print a concise report — do not create a bloated audit file:

Acta audit — <project>
🔴 Broken (N)      : <one line each>
🟡 Drift/stale (N) : <one line each>
🔵 Hygiene (N)     : <one line each>
Clean              : <areas with no findings>
→ Fix: run /acta:track to re-sync current-state docs; <specific doc> needs <the manual bit only a human can supply>.

If everything passes, say so plainly. By default the audit writes nothing — the report is printed; no file is created and no file grows.

Not losing findings (opt-in, never bloats)

Because the report is ephemeral, offer two ways to keep the findings — the user chooses; nothing is written without consent:

1. Just re-run /acta:audit next session — it's cheap and reflects the current reality, so a real issue is never missed (nothing to forget). This is the default.

2. Record open items into the living memory (only if the user wants persistence): one concise line per unresolved finding into an existing doc — never a separate audit file:

   • blocking / do-next → docs/progress.md Blocked / Next Up
   • deferred quality or debt → docs/project/tech-debt.md (TD-N)
   • a doc's own unknown → that doc's Open Questions

   These are bounded, self-cleaning docs (a snapshot / an open-debt list) linked from the CLAUDE.md brain: acta:track removes each item once it's fixed, so they track the current open set and shrink as you resolve them — never grow without bound. Anti-bloat: one line per item, dedupe, no audit files.

Fixing — only with --fix, only the safe mechanical set

• Regenerate the CLAUDE.md brain block, docs/README.md index, and .claude/acta.md registry from the current filesystem (idempotent, marker-scoped).
• Remove or correct broken internal links.
• Refresh updated: dates only on docs you actually changed.
• NEVER fabricate content, resolve a contradiction, or fill a TBD — those are always reported for the human or for /acta:track, never invented.

Rules

• Read-only by default; --fix performs only the mechanical set above.
• Never fabricate; unknown / contradiction / gap → report, don't invent.
• Idempotent. Content in the project's documentation language. Operate by ${CLAUDE_PLUGIN_ROOT}/acta/principles.md.