/audit

name: audit
description: Audit a documentation-led repo against its own conventions — contiguous ADR numbering, INDEX sync, plan/ coverage, required sections, status validity, cross-reference resolution, language mandate, ADR-privacy leaks into user-visible code, cross-worktree collisions (duplicate numbers, duplicate plan ownership, same ADR edited on two branches), and — for a multi-repo product — cross-repo federation checks (bidirectional membership, identity collisions, dangling cross-repo references, roll-up drift, convention drift). Reports a punch list and offers to fix the mechanical issues. Use when the user says "audit the ADRs", "lint the conventions", "check repo consistency", or "are the ADRs in sync".

audit

Check a documentation-led repo against the conventions it declares. This is the enforcement `AGENTS.md` cannot guarantee on its own.

Step 0 — Preconditions and context

1. Confirm the repo is bootstrapped. 2. Read `CONVENTIONS.md` to learn what to enforce: the **ADR shape scheme** — a single shape, two shapes declared by a `shape:` field in each ADR's metadata block (no number boundary is recorded and none is read), or the **legacy range encoding** described in item 4 — status lifecycle, integration model, multi-agent mode, language mandate, optional artefacts present (GLOSSARY, domains/), and any Q10 domain hard rules, and the **artefact root** (default: repository root) — resolve `adr/`, `plan/`, `INDEX.md`, `_agent/` against it and honour it in the cross-reference and INDEX-sync checks. 3. If a `federation.md` exists, this repo is part of a multi-repo product. Note its `Role` (`central` / `home` / `coordinator` index-holder, or a plain `member`) and read the recorded identity scheme; the cross-repo checks (check 12) run from the index-holding repo. 4. **Legacy range encoding.** Some two-shape repos were scaffolded before the shape became a declared field and encode it in the **number** instead: capability ADRs below a cutoff, technology ADRs at or above it, and the technology template sitting at the boundary as a pseudo-ADR. Two signals identify it, and **either one alone is enough**:

• `CONVENTIONS.md` §ADR Shapes records a cutoff — a capability range

and a technology range rather than a `shape:` field; or

• `adr/` holds a template file numbered other than `0000` (e.g.

`adr/0100-template.md`, or whatever boundary the project chose).

Treat the two as one condition, not two findings. When it holds the catalogue is **valid, not broken** — it predates the declared field. Run the checks below under the **legacy rules** noted against checks 1, 2 and 4, so a repo that passed before keeps passing, and report the single finding of check 15. A migration onto the declared field is offered in Step 4; nothing is rewritten here.

Step 1 — Run the checks (read-only)

Report each as PASS / FAIL / N/A with specifics (file + line where relevant):

**Templates are not decisions.** Every check that walks the catalogue excludes each `adr/0000-*.md` file — `0000-template.md` and, in a two-shape repo, `0000-template-technology.md`. They are never numbered, indexed, plan-covered, or section-checked as ADRs. Under the **legacy range encoding** the boundary-numbered template is excluded in exactly the same way: it is a template, not the first technology ADR.

1. **Numbering.** ADR filenames contiguous, zero-padded, no gaps, no duplicates — **one sequence for the whole catalogue**, whatever each ADR's shape. Flag any template numbered other than `0000`. *Legacy encoding:* apply the range rules exactly as they stood — numbering contiguous **within each block** with no duplicates, the gap at the cutoff expected rather than flagged, capability ADRs below the cutoff and technology ADRs at or above it, and the boundary-numbered template neither flagged nor counted as an ADR. 2. **INDEX sync.** Every ADR appears in `INDEX.md`; every INDEX row has a matching file; metadata fields (status, title, date) agree. In a two-shape repo the table carries a **Shape** column and its values agree with each ADR's `shape:` field (an absent field reads as `capability`); a single-shape repo has no such column. *Legacy encoding:* the table carries no Shape column — shape is read from the range — so do not flag its absence. 3. **Plan coverage.** Every `Accepted` ADR has a `plan/todo/` item; every `Implemented` ADR has a `plan/done/` entry. Flag orphans both ways. After a range migration, resolve an unchanged done entry's old identity through the migration commit's recorded old-to-new map before checking coverage. Cite that commit and pair; do not require history to name today's number. Bind the full old path in the pre-migration tree to the mapped current file using that commit's tree/rename evidence; an equal number or title alone never establishes identity. A different filename sharing the old prefix gains no exemption. Missing mapping or tree evidence is unverifiable, not proof of coverage. Unrelated or unmapped missing entries remain findings. 4. **Section completeness.** Each ADR has the required sections in the order its **declared shape** mandates — read the `shape:` field: `capability`, or an absent field, means the capability order (Context, Capability statement, User stories / scenarios, …); `technology` means the technology order (Context, Decision, Rationale, Consequences, …). In a single-shape repo every ADR takes that repo's one order. Flag any `shape:` value that is neither `capability` nor `technology`. A `shape:` field in a single-shape repo is redundant, not wrong — report it as hygiene. Acceptance criteria are numbered. *Legacy encoding:* the shape is the ADR's side of the cutoff — below it capability, at or above it technology — and no `shape:` field is expected. Validate the section order a