Audit

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: ADR shape and

cutoff, 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 against it and honour it in the cross-reference and INDEX-sync checks.

1. 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.

Step 1 — Run the checks (read-only)

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

1. Numbering. ADR filenames contiguous, zero-padded, no gaps, no

duplicates. Split repos: capability below cutoff, technology at/above.

1. INDEX sync. Every ADR appears in INDEX.md; every INDEX row has

a matching file; metadata fields (status, title, date) agree.

1. Plan coverage. Every Accepted ADR has a plan/todo/ item;

every Implemented ADR has a plan/done/ entry. Flag orphans both ways.

1. Section completeness. Each ADR has the required sections in the

order its shape mandates. Acceptance criteria are numbered.

1. Status validity. Every status: is in the declared lifecycle.

Superseded ADRs name a successor in superseded-by:; the successor names them in supersedes: (symmetry).

1. Revision/Approvals. Revision History present; Approvals populated

for ADRs at Accepted or beyond.

1. Cross-references. Relative adr/NNNN-*.md links resolve to real

files. Glossary anchors (if used) resolve.

1. Language mandate. If set, spot-check user-facing docs for the

required spellings.

1. 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.

1. Coordination hygiene. N/A if _agent/ was omitted at bootstrap

(Q5 = None). Otherwise: _agent/LOCKS.md has no stale claims (mode 2); _agent/IN_FLIGHT.md rows match live worktrees (mode 3).

1. Cross-worktree collisions (mode 3, or when auditing across

unmerged branches). These catch semantic conflicts that a line-level git merge cannot:

• 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 _agent/IN_FLIGHT.md: every collision should correspond to a reservation/ownership violation recorded there.

1. 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.

1. 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.

Step 2 — Report

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 (stale locks, formatting).

Step 3 — Offer fixes

Offer to fix the mechanical issues automatically: regenerate INDEX.md, create missing plan/todo stubs, clear stale locks, fix broken relative links. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EvolveHQ
• Source: EvolveHQ/docflow
• License: MIT
• Homepage: https://evolvehq.github.io/docflow/

Install and usage instructions live in the source repository linked above.