Skills/audit/SKILL.md

name, description

name	description
audit	Use at cycle close OR when baseline drift is suspected. Runs architect drift review against the design ledger plus the configured regression scripts. Mandatory at every cycle close; deferral requires an explicit backlog issue naming the reason and the re-run date.

audit — cycle-close tidy

Violating the letter of these rules is violating the spirit.

Overview

Without a scheduled clean-up step, codebases grow by accretion: every iteration adds, none tear out, and deferred drift compounds across cycles. This skill is the cleanup step. It runs after the last iteration of a cycle closes and before the next cycle starts.

When to Use / Skipping

Mandatory at every cycle close. Skipping requires an explicit backlog issue (issue tracker configured under git.issue_tracker) naming:

• the blocking sibling cycle (if any),
• the reason for deferral,
• the date the audit will be re-run.

"We want to keep moving" is not a valid reason.

Also triggered manually when baseline drift is suspected outside a cycle close (e.g. the bencher reports an unexplained metric shift).

The Iron Law

TIDY IS NON-OPTIONAL AT CYCLE CLOSE
REGRESSION-SCRIPT EXIT CODE 2 = FIX INFRASTRUCTURE FIRST, NEVER REPORT AS REGRESSION
NO BASELINE UPDATE WITHOUT A PAIRED RATIFY STATEMENT IN THE AUDIT COMMIT BODY

The Process

Step 1 — Architect drift review

Dispatch architect with the cycle scope (commit range from the previous cycle-close to HEAD):

For cycle <X>: read the project's design ledger (configured
under paths.design_ledger), walk its contracts;
`git log <prev-close>..HEAD --format=full` for the cycle's
iter and audit commit bodies; `git diff <prev-close>..HEAD`
for the diff; report drift.

Architect produces a prioritised drift list (see agents/architect.md output format).

Step 2 — Regression check

Run the scripts configured under commands.regression in the project profile, in order. If the list is empty, the project has no regression gate and this step is a no-op (architect remains the gate).

The exit code of each script is the gate:

Exit	Classification	Action
0	Green	All metrics within tolerance vs. the script's baseline. The cycle's drift gate is clear (drift-clean, not a milestone close — see ../docs/pipeline.md § Milestone-close gate).
1	Drift / regression	At least one metric regressed past tolerance. Treat like a drift item.
2	Infrastructure failure	Script-output format changed, fixture missing, or harness can't spawn. Fix the infrastructure FIRST, re-run. Never claim a regression on exit 2.

A non-zero exit on any script in the list triggers the bencher (agents/bencher.md) for hypothesis-driven diagnostics if the regression needs localising.

Step 3 — Classify and report

Combine architect drift items + regression results into one report to the orchestrator. Each item is one of:

• fix (specific iter scoped, plan + implement)
• ratify (--update-baseline on the firing script + an explicit ratify statement in the audit commit body naming the iter that intentionally moved the metric and why)
• carry-on (architect found nothing actionable, regression green)

Step 4 — Resolve

The orchestrator picks per item:

• fix path: dispatch planner + implement for a tidy iteration. The implement skill leaves the fix in the working tree; the orchestrator commits per the iter's pattern (suggested subject: iter <X>.tidy: <fix>).
• ratify path: run --update-baseline (or the equivalent) on the firing script. The audit-close commit carries both the updated baseline and a ratify paragraph in its body naming the iter that moved the metric and the substantive reason (semantic cost, intentional trade-off).
• carry-on path: the audit-close commit body says cycle <X> tidy (clean) and ratifies whatever the regression check drove. Here clean means drift-clean — the cycle's code matches the ledger; it is not a milestone close, which additionally requires a green milestone fieldtest (see ../docs/pipeline.md § Milestone-close gate). Audit commits always exist at cycle close — they carry the architect findings, the regression numbers, and the resolution.

Handoff Contract

audit hands to the orchestrator:

Field	Content
drift_items	prioritised list (path + 1-line justification) from architect
regression_results	per script: exit code + raw output verbatim (no rounding, no summarisation — the orchestrator second-guesses with the full numbers)
recommendation	per-item: fix / ratify / carry-on

The orchestrator decides the per-item outcome; audit does not self-resolve.

Common Rationalisations

Excuse	Reality
"Tidy can wait until next week, let's keep moving"	The project's CLAUDE.md is explicit: tidy at cycle close is non-optional. Deferral compounds; next cycle adds its own drift.
"Regression red, just bump the baseline, the regression is expected"	"Expected" is exactly the claim that needs evidence. Localise the regression, then either fix OR ratify with a paragraph in the audit commit body naming the iter and reason.
"Drift item is trivial, ignore it"	Trivial drift left open trains future-orchestrator to treat the architect's findings as advisory. Six items in, six items out.
"Regression scripts are hanging, skip them this cycle"	Exit code 2 = fix infrastructure FIRST. No skipping.
"Architect report is empty, fast-close"	Empty report is a possible outcome. Run the regression scripts anyway. Both gates must pass.

Red Flags — STOP

• Skipping any configured regression script
• Bumping baseline without a paired ratify statement in the audit commit body
• Treating exit code 2 as a regression to fix
• Closing a cycle with drift items in pending state
• "We'll re-run after the holidays" without a dated backlog issue
• Declaring a milestone closeable on the strength of an audit-clean while the milestone fieldtest has not run green — audit proves drift-clean, never functional (see ../docs/pipeline.md § Milestone-close gate)

Cross-references

• Agents dispatched:
  • agents/architect.md — drift review against the design ledger
  • agents/bencher.md — hypothesis-driven regression diagnostics when a metric needs localising
• Hand-off target: the orchestrator, or ../planner + ../implement for a tidy iteration.