ADR Audit

Reply in the language the user writes in; default to English. Keep command output, identifiers, paths, and ADR file content unchanged.

Use $ARGUMENTS to pick the scope. Empty means the whole codebase, because that is the question people mean when they ask whether the project is still on course. Read-only: this skill reports, it never edits an ADR or a source file.

Why one command for two questions

Two answers are needed and either one alone is misleading:

• Are the decisions any good? A clean judge over vague ADRs proves nothing, because a vague rule cannot be violated.
• Does the code obey them? A sharp ADR set nobody checks the code against is documentation, not governance.

bin/adr-audit runs adr-lint and adr-judge together so the caller does not have to know the answers come from two binaries.

Run it

# The whole codebase: every tracked file judged as if newly added, so forbid
# rules reach code no recent diff touched.
"$ADR_KIT/bin/adr-audit" --whole-codebase --adr-dir docs/adr --repo-root .

# A specific diff: the hook and pull-request case.
git diff --unified=0 origin/main...HEAD | "$ADR_KIT/bin/adr-audit" --diff -

# Machine-readable, for a CI job or another tool.
"$ADR_KIT/bin/adr-audit" --whole-codebase --format json

Add --llm to include the judge's LLM pass for llm_judge ADRs. It costs money and time proportional to the number of opted-in ADRs, so confirm with the user before adding it — never on your own initiative.

Read the exit code before you read the output

The two failures have different owners, so they have different codes:

Never collapse 1 and 3 into "the audit failed". Say which one, and to whom it belongs. Exit 2 is not a finding: report that the audit could not run and why, and do not present its silence as a pass.

Responding to findings

• Code violations — cite ADR, file and line. Offer to fix the code, or, if the decision itself is what is wrong, to supersede it with /adr-kit:adr. Never work around an Accepted ADR silently.
• ADR-quality failures — name the failing gate, not just the ADR. Offer /adr-kit:grill ADR-NNN for a Proposed record. An Accepted record's body is immutable: the honest routes are a supersession or a retirement, never a rewrite.
• Whole-codebase mode surfacing old violations — expected and worth saying plainly. A rule added after a file was written has never been applied to that file. Offer a remediation task rather than a large unrequested edit.

Which gates a green audit covers

By default the lint half runs completeness, audit and consistency -- the structural gates, which have exact answers. A green audit at the default set is not a statement that the records are sharp, and this command's own rationale turns on that distinction: a clean judge over vague ADRs proves nothing, because vague rules cannot be violated.

--gates passes a set through to adr-lint. --gates all adds schema, evidence, clarity, policy and quality.

Say which set produced the answer when you report it. "The audit is green" is a different claim depending on the set, and the reader cannot tell from the verdict line alone.

Where it fits

• /adr-kit:judge judges one staged diff at commit time. Narrower and faster.
• /adr-kit:lint checks the records alone.
• /adr-kit:guardian runs a version of this combination on a cadence.
• /adr-kit:audit is the on-demand form a person, a hook or a CI job can simply demand, and the only one that reaches code no diff has touched.

bin/adr-discover is a different thing despite the old name: it is the init scanner that looks for decision-shaped artefacts. It does not audit anything.