Audit — Project State Catalog

Operate the .context/audits/ convention: scaffold new audit runs, validate coherence, escalate findings to backlog, migrate legacy folders out of plans/.

See audit-conventions for the full convention.

Default autonomy

On run start, apply Mode A autonomy automatically — do not wait for the user to grant it. Questions live in the initial alignment moment only; after that the run proceeds start-to-finish per the shared canon (deny/pre-authorized/mandated/autonomous). See "Sweep doctrine" below for how this applies once a sweep is running.

Sub-actions

Dispatch by first argument:

--loop guard (anti-cargo-cult). Use --loop ONLY when the finding is bulk + machine-checkable — a gate the machine can run to say pass/fail across many sites (lint clean / contrast ratios / type-clean / remove-all-X). Single fixes and ideas go to the backlog (plain escalate, no flag). Never auto-loop: the operator still writes the exact Stop condition and picks an engine before the loop runs. If there is no machine gate, it is not a loop — escalate to backlog.

Supported audit types (for new)

ux · ai-opportunities · security · perf · a11y · hitl · retest · test-coverage · docs-coverage · rule-ablation · custom — short English names per decision/2026-07-02-audit-rebuild-canon-decisions; the legacy -audit-suffixed and ia-opportunities forms are accepted as input aliases and normalized, as is the coverage short form for test-coverage and docs/documentation for docs-coverage. For a one-shot analysis with no recurring methodology, use new --standalone <slug>: it scaffolds a dated run folder directly under audits/ with no boards (canon §Standalone one-shot runs).

Read ${CLAUDE_PLUGIN_ROOT}/skills/audit/references/04-playbooks.md before choosing a type. It holds what each methodology actually checks, when it is the wrong fit, and which one a vague request ("audit my app") maps to. Choosing wrong scaffolds boards you then have to migrate.

Dispatch logic

When invoked with arguments, run the script the sub-actions table above names for that command, passing the remaining arguments through. The table is the only command→script mapping; it is deliberately not restated here, because a second copy drifts and ends up naming scripts that do not exist.

One command is not 1:1 — escalate has two scripts, chosen by the flag:

# escalate --loop takes the loop variant; every other command takes its table row.
if [ "${1:-}" = "escalate" ] && printf '%s\n' "$@" | grep -q -- '--loop'; then
  bash "${CLAUDE_SKILL_DIR}/scripts/escalate-finding-to-loop.sh" "$@"
fi

If no arguments are given, show the help table above and run a status check:

# Quick status (when invoked with no args):
if [ -d .context/audits ]; then
  bash "${CLAUDE_SKILL_DIR}/scripts/reindex-audits.sh" >/dev/null 2>&1  # refresh roll-up
  cat .context/audits/00-index.md                                      # run-level state
  # Changelogs live per methodology (D-02). The root path is legacy-only —
  # migrate-audit.sh leaves it in place without --methodology — so it is a
  # fallback, not the primary read.
  for cl in .context/audits/*/00-changelog.md .context/audits/00-changelog.md; do
    [ -f "$cl" ] && { echo "== $cl"; head -15 "$cl"; }
  done
fi

Workflows

Starting fresh

/aidex:audit new ux login-redesign

Scaffolds the canon per-methodology layout (D-02):

• .context/audits/ux/2026-07-02-login-redesign/index.md
• .context/audits/ux/2026-07-02-login-redesign/findings.md
• .context/audits/ux/00-inventory.md (if missing)
• .context/audits/ux/00-methodology.md (if missing — seeded from the type's playbook)
• .context/audits/ux/00-changelog.md (if missing)

For a one-shot analysis (no recurring methodology):

/aidex:audit new --standalone usage-retro-q3

Scaffolds only .context/audits/2026-07-02-usage-retro-q3/index.md — no boards (canon §Standalone one-shot runs; escalation uses origin_ref: audit/<run>/<id>).

Running an audit

Front-load the area order (work-list). At kickoff, after scope/borders, emit the audit's areas/findings in execution order as a durable .context/worklists/ work-list (via the AskUserQuestion survey → worklist-new.sh). Read ${CLAUDE_PLUGIN_ROOT}/skills/conventions/references/worklist-conventions.md first — it holds the work-list format, the three classes of mid-run question, and which ones the queue is supposed to absorb. The sweep then walks areas with worklist-advance.sh instead of pausing to ask "next area?" between them — the one ordering decision is fixed once, up front. (For a fan-out Workflow run below, the same ordered areas become the shards.) No interactive channel (claude -p, cron): skip the survey, emit the areas in the order scope/borders produced them, and note the defaulting in the audit brief — autonomy-conventions.md § When there is no interactive channel.

Durable Workflow promotion (mandatory evaluation at kickoff). At /aidex:audit new — the single sanctioned question point, before the sweep begins — classify whether the audit has enough independent dimensions or shards to amortize the ~22k/agent Workflow floor. If yes, propose the durable fan-out Workflow form in one line, batched with the kickoff scope questions — e.g. "12 independent dimensions -> run as a durable Workflow (fan-out of analysts, schema-gated, arbiter at the escalate gate)? else in-process sweep." A one-word "yes" is the opt-in: invoking this skill plus this proposal is the sanctioned authorization to call the Workflow tool — no ultracode needed. If the audit does not qualify (few dimensions, small scope, not unattended), run the normal in-process sweep and do not ask. This is a kickoff question, never a mid-sweep interruption.

model-policy: per-stage. Every agent this skill spawns carries its own model and effort — the plugin-level agents/*.md definitions declare theirs (the arbiter consult included), and the fan-out script assigns per stage. Nothing here inherits the spawning session's by omission.

The fan-out form ships as assets/workflows/audit-fanout.workflow.js, which embeds the single-sourced durability CORE (../conventions/references/workflow-core.md) and is covered by the drift-lock test.

1. Open the methodology/<type>.md playbook.
2. Walk through checks in scope.
3. Read ${CLAUDE_PLUGIN_ROOT}/skills/audit/references/02-id-conventions.md before writing the first finding id — it decides structured vs global ids for this run, and an id scheme changed after the fact invalidates every inbound origin_ref.
4. Add rows to 00-inventory.md for each finding.
5. Reference IDs from this run's findings.md (filtered view).
6. Read ${CLAUDE_PLUGIN_ROOT}/skills/audit/references/03-lifecycle.md before setting any finding's status — it is the state machine (which transitions are legal, what closes a finding vs. escalates it) that validate-audit.sh and close-audit.sh enforce.
7. Close out index.md summary.

Sweep doctrine (autonomy). Scope and borders are set at kickoff (/aidex:audit new) — that is the initial phase where any question is asked. After that the run is an uninterrupted sweep: catalog each finding with your best-judgment severity and log the assumption — do not stop to ask whether something is worth noting. Escalation to backlog/loop is the explicit border (the separate escalate sub-action); for security audits, active exploitation or destructive verification is deny. Full rule: autonomy-conventions.md.

Don't pause at the escalate gate for one finding. A single confirmed finding goes to backlog without a question. When more than one is confirmed, build the consultation page with /aidex:artifact first (a consultation page citing every finding id; the owner decides the batch there), then run escalate <ids...> --page <page.html>; the script refuses a batch without it. If a specific finding is genuinely ambiguous, decide CONTINUE / ASK / STOP yourself per finding against the policy in the ARBITER block of workflow-core.md and put any ASK on that page.

Isolation. An audit is read-mostly — usually no worktree. The exception is a security audit that needs destructive verification: run it in an isolated worktree with its own DB (worktree.sh new) so it never mutates real state. In that case read ${CLAUDE_PLUGIN_ROOT}/skills/conventions/references/worktree-conventions.md for the isolation contract before touching anything.

After the audit

/aidex:audit validate              # verify coherence
/aidex:audit escalate BUG-01-1     # one finding at a time → backlog
/aidex:audit escalate BUG-01-1 BUG-01-2 --page <page.html>  # a batch (or a 2nd escalation within 10 min) needs a consultation page built with /aidex:artifact (a kit-stamped .html with consult-groups, citing the ids; it may live under .context/audits/)
/aidex:audit escalate A11Y-02-1 --loop  # bulk, machine-checkable finding → loop-spec
/aidex:audit remediate 2026-06-21-retro  # the whole run's open findings → one remediation loop-spec

Re-testing

/aidex:audit new retest post-sprint-5

Open the retest playbook; for each previously-open finding, classify (fixed / still open / regression / new adjacent) and update INVENTORY in place.

Legacy migration

If audits have accumulated inside .context/plans/:

/aidex:audit migrate

migrate-audit.sh scores each .context/plans/ folder on file-presence heuristics and prints the candidate list plus the manual move steps. Once folders are moved, inventory-seeder generates the initial INVENTORY rows from their findings.

Read ${CLAUDE_PLUGIN_ROOT}/skills/audit/references/05-migration-guide.md before accepting any move. It holds what the legacy plans/-era layouts look like, which folders are audits and which only resemble one, and the order the boards must be seeded in.

When to run the sweep

/aidex:audit coverage-sweep is a drift check, not a calendar chore: run it at the natural moments when src is likely to have outpaced tests —

• after a feature push on a tracked module,
• after closing a plan that touched tracked paths,
• after any incident (something broke → coverage was probably thin there).

It is advisory (exit 0 whenever it runs; 2 when it cannot — no/invalid map, bad flag): a ranked table of modules whose src commits moved without their tests since the last matrix. Act on the flagged rows with /aidex:audit new test-coverage <slug> scoped to them, then regenerate the matrix. plan-exec (at plan close) and bugfix (at GREEN) surface a one-line suggestion to run it (Phase 6).

Subagents

Scripts delegate to this agent when needed. Direct use is also fine during manual migration work. Candidate detection is not an agent — migrate-audit.sh scores folders deterministically.

Principles

Quick summary. Read ${CLAUDE_PLUGIN_ROOT}/skills/audit/references/01-principles.md before your first audit — it holds the why and the practical under each of these, which is what tells you why a finding is never deleted and why the methodology's inventory, not the run folder, is the source of truth. The principles themselves are stated by conventions/references/audit-conventions.md § Core principles.

1. Finding ≠ Issue ≠ Task — distinct objects with links, not copies
2. Per-methodology inventory as single source of truth — per-run findings are views of 00-inventory.md. The auto-generated 00-index.md is the run-level roll-up (which runs exist, open/closed, finding counts) — complementary to the finding-level board. Do not hand-edit 00-index.md.
3. Living methodology — 00-changelog.md records every methodology change
4. Findings never deleted — use status transitions
5. Escalation flow — audit → backlog → plan → commit → re-test → done
6. Shared concerns flagged [SHARED] in Module column

Templates

All templates in assets/templates/:

• Core: 00-inventory.md, 00-methodology.md, 00-changelog.md, index.md, findings.md
• Playbooks: methodology/<type>.md.template for each of nine stock types

Related

• conventions — defines the audit convention itself
• backlog — handles the other side of escalation (/aidex:backlog --origin audit --finding <id>)
• artifact — renders inventory boards and the coverage matrix as interactive HTML on demand (render.sh audit <methodology> / render.sh coverage); publishing stays user-gated
• aidex — audits the audits directory for coherence as part of overall ecosystem health