audit · git:20260913.cc04d59 · 2026-09-13 · sha256 53ac213d263fe529

audit git:20260913.cc04d59A

Immutable. This exact content never changes and is served at /api/v1/blob/53ac213d263fe529.

---
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.
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 against that, exactly as before,
with the one carve-out the encoding forces and these repos record for
themselves: an ADR below the cutoff that `CONVENTIONS.md` names as a
**documented exception** — typically the ADR adopting the method,
which is technology-shaped but has to be first in the sequence — is
checked against the technology order, not flagged. A mismatch the
conventions do **not** record is still a finding. A `shape:` field
contradicting the range is a real inconsistency; one agreeing with it
is hygiene, not a failure.
5. **Status validity.** Every `status:` is in the declared lifecycle.
`Superseded` ADRs name a successor in `superseded-by:`; the successor
names them in `supersedes:` (symmetry).
6. **Revision/Approvals.** Revision History present; Approvals populated
for ADRs at `Accepted` or beyond.
7. **Cross-references.** Relative `adr/NNNN-*.md` links resolve to real
files. Glossary anchors (if used) resolve.
8. **Language mandate.** If set, spot-check user-facing docs for the
required spellings.
9. **ADR-privacy leaks.** Grep source / product directories for ADR
identifiers in user-visible strings — patterns like `ADR 0042`,
`adr-0042`, `see ADR`, ADR titles — in UI copy, API responses,
error messages, customer-facing logs, public docs, release notes.
Report each suspect; this rule is easy to violate by reflex.
10. **Coordination hygiene.** `_agent/` is the agent operating
contract — who writes what, the one real mutex, and how an
unattended run behaves — and holds nothing git already records.
N/A if the repo has no `_agent/` directory (a valid state: a single
writer that is not eligible for the run prompt has none). Otherwise
read the recorded coordination mode. First recognise the legacy marker set
below: it gets one non-failing migration-available finding, and its
recorded hygiene rules remain active until migration. Modern-only file
and derived-state failures below do not duplicate that finding. Check:
- **Only the prescribed files exist.** Single writer:
`prompts/autonomous.md` and nothing else. Shared checkout:
`ROLES.md`, `LOCKS.md`, `prompts/autonomous.md`. Separate
worktrees: `ROLES.md`, `prompts/autonomous.md` — no lock ledger,
because the branch and its pull request are the claim.
`prompts/autonomous.md` is prescribed only where the repo is
eligible for it — a recorded verify gate **and** the `plan/todo/`
queue the prompt walks. A prompt in a repo with no plan queue is
an unprescribed file: report it, and say the fix is to add the
queue or drop the prompt. Under a single writer, no eligibility
means no `_agent/` directory at all. **Fail** on any other file
under `_agent/`, and on a
prescribed file the mode does not allow (a lock ledger in
separate-worktree mode, a roles list under a single writer).
- **No file carries derived state.** **Fail** on any `_agent/` file
whose content duplicates what git, the queue, or the live
branches already say: a log of shipped items, an in-flight or
per-worktree table, a snapshot of branch or queue state ("active
branch", "last shipped", "next item"), or a clause telling the
reader that git wins where the two disagree — that clause is the
file admitting it is a stale copy.
- **Stale claims.** In a shared checkout, a row in
`_agent/LOCKS.md` is a live mutex until there is **evidence** its
owner has finished or abandoned it. Writers claim a file *before*
editing it, so a claim with no pending change is the normal state
of a writer preparing an edit — **never** infer staleness from an
absent diff alone. Evidence must be tied to **this** claim, never
to the actor's history on the file — writers reuse files across
tasks, so a commit older than the row proves nothing about it.
Evidence is one of:
- a commit by the claiming actor that touches that path, with a
commit time **later than the row's timestamp**, has landed on
the integration branch and the row is still there (the claim
outlived its own work);
- the operator confirms the owner is gone.
Report rows with evidence as **hygiene**, naming the evidence.
Report every other claim as an **uncertain** row — listed for the
operator to confirm, counted as neither clean nor stale, and never
cleared automatically. Where the audit cannot attribute a row to a
commit at all (no matching actor in the history), it is uncertain,
not stale.
- **The in-flight view is derived, not read from a file.** Compute
it and render it in the report: `git worktree list` for the
worktrees on this machine, the remote branches matching the claim
convention (`claim/<item-key>`, the queue file name without its
extension), and open pull requests, draft or ready, where a pull-request
host is reachable. Then check it:
- **Fail** on an **item claimed twice** — two claim branches for
one item key, or a claim branch and a claim recorded on the item
naming different actors. One item maps to one ref precisely so
this cannot happen quietly; if it has, name both claims and the
item.
- **Resolve the item at the integration base and claim tip**, not
only in the auditor's checkout. An unmerged ready PR can already
contain the todo-to-done move: use its item reference and git move
history to connect the done entry. Only fail an orphan claim when
neither tree nor the linked PR explains its item. Missing read
access makes this unverifiable, not an orphan.
- **Stale branch-backed claim:** after successful fetch/prune, its
remote ref is confirmed absent. Offer cleanup with evidence, never
delete an uncommitted or unnamed worktree. Detached worktrees are
neither claims nor stale. Shared-checkout Claimed by and lock rows
have no remote claim branch: use the ownership evidence above;
absent remote refs and absent diffs alone prove nothing.
- Confirmed merged PRs and claim tips already reachable from the
integration branch are not live. An item still queued is merged but
unshipped and needs reconciliation; a linked completion entry on
the base is shipped. Use PR merge state when squash/rebase changed
ancestry. Unmerged draft and ready PRs remain live. Normal actor
changes in a continued claim's history are not duplicate ownership.
- **No remote, no verdict.** Where no remote is reachable the
branch and pull-request halves cannot be computed at all. Report
the in-flight view **unverifiable**, naming what could not be
reached — never PASS. Worktrees are still listed; they just do
not answer the question on their own.
- **Legacy layout.** Where the offending files are the former
scaffolded set — `WORKLOG.md`, `worklog/`, `CURRENT_FOCUS.md`,
`IN_FLIGHT.md`, `HANDOFF.md`, a `merge=union` attribute for the
worklog, or a `.gitignore` entry for the snapshot — report them
as **one** finding naming the layout and every file in it, not
one finding per file, at non-failing **migration available** severity.
Include a mode-inappropriate ROLES or LOCKS file as a marker too.
Offer the coordination migration below. Separately offer evidenced
stale-content cleanup; keep valid legacy rules if migration is declined.
11. **Cross-worktree collisions** (repos that record several writers on
separate worktrees, or any audit that spans unmerged branches).
These catch semantic conflicts that a line-level git merge cannot,
and all three are **FAIL**, never hygiene — each one merges clean and
lands an incoherent catalogue:
- **Duplicate ADR or plan/todo numbers** — two ADR files, or two
`plan/todo/` items, (across branches/worktrees) claiming the same
`NNNN`. Distinct from check 1, which only sees one tree. This is the
collision the concurrency guardrails (G2 pre-merge / G3 gate) guard
against; flag it so the later author renumbers.
- **Duplicate plan ownership** — two `plan/todo/` items naming the
same owning ADR for the same scope, i.e. two worktrees building
the same thing.
- **Same ADR edited on two unmerged branches** — compare ADR files
across the live worktrees / open PRs; flag any ADR modified in
more than one. A `merge=union` would concatenate them silently.
Cross-check against the identifier blocks the wave reserved — read
them from each branch's pull-request description, or its first commit
message under direct-to-main, and from the claim branch each worktree
pushed. Every collision should correspond to a writer working outside
its reserved block or editing an artefact another claim names. There
is no file to cross-check against: the blocks are stated where the
work is.
12. **Cross-repo (federation) checks** — only when a `federation.md`
exists; run from the **index-holding** repo (`Role: central`, `home`,
or `coordinator` — whichever holds `federation-index.md`). Reach each
member through the local checkout named in `federation-index.md`. A member not checked
out locally is reported **"unverified this run"** — never silently
passed, never a hard failure.
- **Bidirectional membership.** Every repo listed in the member index
carries a `federation.md` back-pointer to this index-holder, and
every repo whose back-pointer names this repo is listed in the
index. Flag either half-edge (in-index-without-back-pointer, or
points-here-but-unlisted).
- **Identity collisions.** Under the repo-prefixed scheme an identity
is `repo-id` + local number, so the only reachable collision is a
**duplicate `repo-id`**. Flag any repo-id that appears on more than
one `federation-index.md` row or in two members' `federation.md`
back-pointers.
- **Dangling cross-repo references.** Resolve each cross-repo link
along `repo-id → Pointer → adr/NNNN-*.md` — look up the repo-id's
Pointer in `federation-index.md`, then the ADR file under that repo.
A repo-id with **no index row** is a dangling reference. If the row
exists but the **checkout is absent**, report it **"unverified this
run"** (not dangling); only an **absent ADR in a present checkout**
is a true dangling reference. (Same-repo relative links are
check 7.)
- **Roll-up drift.** The roll-up agrees with each member's `INDEX.md`
metadata; flag rows that are stale, missing, or extra.
- **Convention drift.** Compare each member's **shared** conventions
against the index-holder's authoritative copy; flag a member whose
shared conventions have drifted from the source. Members' **local-only**
conventions are exempt.
13. **Coverage (undocumented developments).** A heuristic nudge, not a
precise diff: scan the major modules / top-level source directories and
the recent `git log` for **substantial behaviour or an area with no
owning ADR** — a large feature, subsystem, or dependency the catalogue
never records. Report each as a prompt to **capture** it (reconstruct
the decision as an `Implemented` ADR + `plan/done`, per the backfill
path), **not** as a hard failure. Because the audit is doc-centric, keep
this conservative — flag clear, sizable gaps, not every file.
14. **Artefact-root discovery.** If a `.docflow` **file** exists at the
repository root, its `root:` line must agree with the artefact root
recorded in `CONVENTIONS.md`, and it must not redundantly name
`.docflow/` (the directory is its own marker — flag the file for
removal). If the artefact root is **not** `.docflow/` and no pointer
file exists, surface it as an **offer** to add one (external tools
discover the catalogue through it) — never as a hard failure;
migration is offered, not forced.
15. **Legacy shape encoding.** N/A unless Step 0 item 4 holds. When it
does, report exactly **one** finding at severity **migration
available**: name the signal(s) that identified the encoding (the
cutoff recorded in §ADR Shapes, the boundary-numbered template file,
or both), state that the catalogue is valid and passing under the
range rules, and say that a complete mechanical migration onto the
declared-field scheme is available (Step 4). Never split it into a
second finding — a template numbered off `0000` and a recorded
cutoff are the same condition — and never fail the audit for it.

16. **Item status and reports.** Surface every nonempty Stopped field for
human attention. Modern queued items carry Claimed by / Blockers /
Stopped; done entries carry no live Status section. Check that the
Reporting convention and AGENTS pointer both exist or are both opted
out, with the same heading/labels. Inspect accessible PR bodies, wave
item/summary reports and stop records for Status at a glance, the three
labels, exact gate outcomes and outstanding work. Missing/inconsistent
blocks are drift; inaccessible reports are unverifiable. Draft PRs may
report verification as not run; they must never imply success.

## Step 2 — Report

Translate the audit verdict into the closing block's Overall vocabulary:
verified only when all in-scope checks are complete and clean; partially
verified when findings remain; blocked or unknown when required evidence
is unavailable. Put the issue count and severity in the explanation, not
in place of that status value.

Lead with a one-line verdict (clean / N issues). Then the punch list,
grouped by severity: **blocking** (privacy leaks, status/lifecycle
violations, broken cross-refs), **drift** (INDEX out of sync, missing
plan files), **hygiene** (evidenced stale locks, uncertain lock rows
awaiting confirmation, formatting), and **migration
available** (a superseded scheme the repo can move off — check 15).
A migration-available finding does not count towards the issue count in
the verdict and never makes the run dirty: a repo whose only finding is
that one is **clean, with a migration available**.

## Step 3 — Offer fixes

Offer to fix the **mechanical** issues automatically: regenerate
`INDEX.md`, create missing `plan/todo` stubs, clear the lock rows check
10 found evidence for, prune the stale worktrees and delete the leftover
claim refs check 10 named, fix broken relative links. A worktree is
pruned only on a confirmation naming it — it may hold uncommitted
work — and a claim branch is deleted only where its item has shipped or
the operator says the work is abandoned. For shipped claims, follow
ship-item's cleanup protocol using the source verified for integration;
preserve the claim if that source is unavailable or the ref has changed.
For explicitly abandoned work, lease deletion against the exact tip covered
by the operator's confirmation; a later tip requires fresh confirmation.
**Only** rows with
that evidence are clearable: clearing a live claim in a shared checkout
removes another writer's only mutex and lets two writers edit the same
file. Uncertain rows are listed for the operator to confirm one at a
time and are never included in a "fix everything" confirmation. **Do not** auto-edit ADR content, rewrite
acceptance criteria, or remove suspected privacy leaks without the
user confirming each — those need judgement. Commit fixes as
`fix(adr): ...` / `docs: ...` with a `Rationale:` footer where an ADR
is touched.

If check 15 fired, offer the **legacy range migration** here too — as
its own offer, separate from the mechanical fixes above, and never
bundled into a "fix everything" confirmation. Step 4 is the procedure.

## Step 4 — Offer the legacy range migration (only when check 15 fired)

The migration is **offered, never forced**. A repo that declines keeps
the range encoding, keeps passing under the legacy rules, and is offered
again on the next audit. Nothing below is written without the
confirmation in 4.2.

### 4.1 — Dry run: show the old-to-new number map

Compute the map and show it **before touching a single file**:

- **Capability ADRs** — those below the cutoff — keep their numbers.
Nothing moves, so the numbers already cited in commits, tickets and
shipped plan entries still resolve.
- **Technology ADRs** — those at or above the cutoff — take the numbers
immediately following the **highest capability ADR**, in their
original relative order. With capability ADRs ending at `0012` and
technology ADRs `0101`, `0102`, `0104`, the map is `0101 → 0013`,
`0102 → 0014`, `0104 → 0015`. Order is preserved; gaps in the old
technology block are closed, not carried over.
- **The moved set is the technology *range*, not every technology-shaped
ADR.** The range encoding forces one exception — the ADR that adopts
the method is a technology-shaped decision that has to be first in the
sequence — and repos record it as such in their conventions. It is
below the cutoff, so it does **not** move: it keeps its number and
simply gains `shape: technology`, which is what retires the exception
clause in step 6. Renumbering it would churn the one number every
early commit cites, for nothing.

Render the map as an `old → new` table with each ADR's title, then list
what follows from it: every `depends-on`, `supersedes` /
`superseded-by`, relative `adr/NNNN-*.md` link, `INDEX.md` row, domain
`README.md` listing, and `plan/todo/` owning-ADR reference that names a
moved number; the boundary template replaced by
`adr/0000-template-technology.md`; §ADR Shapes rewritten to the declared
field. Say plainly what is **not** touched: `plan/done/` footers, commit
messages, tags, and any reference from outside the catalogue. Those are
history, and history is not rewritten.

### 4.2 — Confirm

Ask for an explicit confirmation of **that map**. Write nothing without
it. Acceptance of the audit report is not acceptance of the migration:
ask for it as its own question, and take silence or ambiguity as a no.

### 4.3 — Apply, as one commit

1. `git mv` each moved technology ADR to its new number, keeping its
slug. Capability files do not move.
2. In each moved file, update the `adr:` metadata field and the H1
heading to the new number.
3. Write `shape:` on **every** ADR — the shape each one **actually
has**, not the block it came from. `technology` on the moved ones and
on the documented exception that stayed (4.1); `capability` on the
rest. Stamping the exception `capability` because it did not move
would put the field at odds with its sections, and the check in 4.4
would fail the catalogue the migration just produced. Write the field
explicitly on all of them: it is the encoding now, and a catalogue
carrying it on only half its ADRs is still readable but no longer
self-describing.
4. Rewrite every in-catalogue reference to a moved number: `depends-on:`,
`supersedes:`, `superseded-by:`, relative `adr/NNNN-*.md` links in
any ADR body, `INDEX.md` rows, domain `README.md` listings, and the
owning-ADR line — and any other relative ADR link — of every
`plan/todo/` item. Rewrite by resolved
identity, not by text search alone — a bare `0101` in prose may be a
quantity, and a number that did **not** move must not be touched.
5. Delete the boundary-numbered template and write
`adr/0000-template-technology.md` in its place — the technology
template, `shape: technology` pre-filled. `adr/0000-template.md`
stays as the capability template; no template carries any other
number afterwards.
6. Rewrite `CONVENTIONS.md` §ADR Shapes to the declared-field form: two
shapes named by the field, an absent field meaning capability, one
contiguous sequence with no boundary, both templates numbered
`0000`, and a Shape column in `INDEX.md`. Delete the cutoff, and
delete any clause recording the seed ADR as an exception to the
range — under the declared field the seed is simply
`shape: technology`, and there is nothing to except. If `AGENTS.md`
mirrors the section, give it the matching shape hard rules.
7. Regenerate `INDEX.md` from the new metadata, with the **Shape**
column.
8. Commit **once**. The message lists **every** old-to-new pair, one per
line, so the renumbering is reconstructible from history alone — it
is the only record of the old numbers, and there is no alias field to
fall back on. Conventional Commit, with the `Rationale:` footer the
repo's git contract requires for ADR changes.

### 4.4 — Verify before handing back

Re-run Step 1 with the legacy rules **off**: one contiguous sequence,
each ADR's sections matching its declared shape, a Shape column whose
values agree with the fields, every relative link resolving, and no
template numbered other than `0000`. The catalogue must pass with **no
manual edit**. If anything fails, the migration is incomplete — finish
it in the same commit rather than leaving a half-migrated catalogue,
which is the one state neither rule set describes.

## Coordination migration

This is independent of range-number migration. Recognise any legacy
worklog file/directory, IN_FLIGHT dashboard, CURRENT_FOCUS snapshot,
HANDOFF, mode-inappropriate ROLES/LOCKS, worklog union attribute or snapshot
ignore entry. Do not combine its report with unrelated semantic failures.

1. **Dry run:** list each removal and its evidence/content destination.
Match live claims against git/PRs; carry owner, reservations and blockers
into the corresponding queue item or claim commit/PR. Preserve custom
operating instructions in their appropriate convention or run prompt.
Shipped history stays in git and plan/done. Uncertain ownership stays
unresolved and is never cleared merely because there is no pending diff.
2. **Approval:** apply an existing explicit grant covering this migration,
or ask for approval of the displayed changes. Audit acceptance alone
is not migration approval. If declined, keep the old conventions/files.
Stale-content cleanup can be approved separately, per named removal.
3. **Apply:** retire the legacy files and only their attribute/ignore rows;
preserve unrelated entries. Remove ROLES for a single writer and LOCKS
for separate worktrees. Add Status to open items, retaining live facts.
Write AGENTS' Picking up this repo from actual files: conventions,
catalogue, queue/status, newest done entries, first-parent git log,
and applicable worktree/claim/PR commands. Rewrite coordination rules;
regenerate the prompt from recorded root, mode, integration and gate.
4. **Commit:** one migration commit lists every removed/moved file and
where its content now lives. Do not remove live branches or worktrees as
a side effect. Run the gate and repeat the audit under the new rules;
finish any incomplete migration before claiming it passed.

Name checked scope, unresolved findings, inaccessible evidence and any applied fixes.

## Closing report

End every run, including blocked, failed and stopped runs, with a section
headed exactly **Status at a glance**, containing these three labels:

- **This run:** only actions actually attempted and their outcomes; quote each verify gate's exact output and exit code, including timeouts or interruptions.
- **Overall:** implemented, partially verified, verified, blocked, failed or unknown. A passing sub-step is not an overall pass; incomplete or missing evidence never becomes success.
- **Yet to do:** every remaining action, unresolved finding, verification, cleanup or required input. Write None only when the whole task is verifiably complete; never omit work because a budget ended.

Routine progress messages need no block. Keep final results brief and
distinguish work prepared on a PR from work confirmed shipped.