Audit Plugin Handbook

Two commands, typed into Claude Code rather than a shell: the first registers the marketplace this plugin ships from, the second installs the plugin out of it.

First session? This page is the reference, not the introduction — read QUICKSTART.md instead: install to a rendered report, one page, in order.

/plugin marketplace add AleksandarBisevac/claude-plugins
/plugin install audit@quality-gates

Requirements are deliberately thin: Python 3.8 or newer, reachable as python3, python or py; on Windows, run inside Git Bash. There is nothing to pip install — a guard that needs a dependency is a guard that is switched off on most machines.

[OK     ] plan gate      deny - phase P2 has work in progress, so edits are held to the running plan

Scope decides who else gets it

/plugin install takes a --scope. The choice is about where the enabling record is written, not about which repositories the plugin can read.

Installing enables as a side effect; the separate enable verb exists only to switch a disabled plugin back on.

Updating, and why it is three commands

/plugin marketplace update quality-gates
/plugin install audit@quality-gates
/reload-plugins

Each one undoes a different kind of staleness, which is why dropping one usually leaves you on the old version wondering why a documented flag is rejected:

• marketplace update re-reads the marketplace, so it learns a release exists.
• install bumps the cached copy and the install record. These drift apart: a record can pin a version long since superseded while a newer copy sits in the cache.
• reload-plugins makes the new commands appear in the session you already have open — the command list is read once, at startup.

/plugin list      # audit@quality-gates, enabled
/audit:status     # renders the manifest, or points you at /audit:init

If /audit:* comes back not recognized, it is nearly always one of two things: installed but not enabled, or only ever installed at project scope for some other repository. The three commands above resolve both, and /audit:doctor reports what the hooks will actually use once they do.

The plan hangs off one file — the manifest. It holds phases, each holding tasks, plus bugs and parked proposals. Commands read and write that file; nothing else is the source of truth about what is meant to happen.

What did happen is kept somewhere else. Every gate run is appended to an evidence ledger beside the manifest, and the manifest caches only a pointer — testEvidence — at the run that last exercised each task and each phase. The pointer is disposable: deleting it is always safe, the next run writes it back, and absent means no run was recorded, never “failed”. Running phases is where that gets read.

The manifest is generated once, before the pull request, so most of you will never run this. It is here so the output makes sense when you see it.

A gate that cannot run is not a gate that passed

meta.buildCommands names the commands a phase's sign-off runs, and /audit:doctor checks each one's runner against this machine's PATH. It warns per runner, because a missing one is infrastructure failure, not a red test — one verdict says “your change is wrong” and the other says “nothing was measured”. And the gate is chosen per phase, not per manifest: each phase's testGate lists which keys must pass, so where a repo's Python runner is absent a phase naming only the JS keys still runs a gate that grades. Read the warning against the phase you are about to start.

A phase is the unit of work and the unit of review. Run a whole phase, one task, or “whatever is next” — each of them previews first with --dry-run.

/audit:phase P0 --dry-run   # see the plan
/audit:phase P0             # then run it

  P2   Input validation           In progress [###.........] 1/4  audit/p2-input-validation
     [x] P2.1   Validate the checkout payload                Done         sonnet  -           passed     c4a11b9
     [~] P2.2   Sanitize the product-search query            In progress  opus    -           -          -
     [!] P2.3   Escape server-rendered template output       Blocked      sonnet  -           failed     -
     [ ] P2.4   Add zod schemas for cart mutations           Pending      haiku   -           -          -        READY

That column appears only once a task in view has recorded a run, so a plan that has never run a gate renders as it always did, and - inside it means no run was recorded — not a failure.

The gate is bracketed, and the run is recorded

The gate is never run by hand. It goes through run-test-gate.py, which brackets it and answers the two questions an exit code cannot: did the gate change the working tree (git status --porcelain before and after) and did anything actually run. Both failures used to be exit 0. --record then writes the run into the evidence ledger and points the plan at it.

# what /audit:run does for a task, and /audit:phase at sign-off
python3 "$CLAUDE_PLUGIN_ROOT/scripts/governance/run-test-gate.py" \
    docs/audit/audit-plan.json P2 --task P2.3 --record

  evidence: recorded 2026-07-15T09:40:00Z.13be6d
  pointer:  P2.3 now names it

Those last two lines are separate facts. Rows land in <manifest dir>/evidence/<YYYY-MM>.<writer>.jsonl — one file per writer per month, so two worktrees never conflict on merge — and the directory is meant to be committed: it is the record somebody hands to a client (evidence.dir moves it). A row keeps what ran, what it answered and what it observed; never a runner's output.

python3 "$CLAUDE_PLUGIN_ROOT/scripts/governance/run-test-gate.py" \
    docs/audit/audit-plan.json P2 --reconcile

[run-test-gate] reconcile: 7 subject(s) in the ledger
  already:  phase P1
  already:  task BF1.1

Reading a verdict

The verdict is one word from the run, read off the ledger rather than the cached pointer. Only passed and empty-gate can sign work off.

A run also carries observations, which are not verdicts and sit beside the badge rather than inside it: not “what did it say” but “what else is true about the run that said it”. Each is three-valued, and null is never 0.

Every row below is a real subject in the published example report, acme-store.

/audit:status --gate --fail-on invalid,failing-tests

GATE FAILED: failing-tests (2 subject(s): task P2.3 failed; task BF1.1 no-checks)

The plan is not frozen. /audit:task and /audit:phase change its shape, and every verb records what it did — these are journalled operations, not edits. Every answer is a flag, and the dialogue only covers what you did not pass, so a fully-flagged call is non-interactive.

/audit:task add "Extract the KPI query into a service" --phase P2 \
  --files src/kpi/query.ts,src/kpi/service.ts --tests-mode regression --risk med

/audit:phase add "Cache the catalog query" --outcome "The catalog page issues one query" \
  --area backend --gate lint --gate test --blocked-by P2

/audit:bug add "Sparkline drops the last day on month boundaries"
/audit:bug fix BUG-3 --phase P1
/audit:run T14

Areas — one repo, two stacks

A phase can carry area: one tag ("backend") or a list for cross-cutting work (["backend","frontend"], grouped under each). meta.areas is the registry that gives a tag properties — a root, a description, a default reviewSkill, default executor skills, an advisory owner. Reviewer resolution is phase.reviewSkill → areas[tag].reviewSkill → meta.reviewSkill; executor skills are the area's plus the task's own, deduped, area first. Where a phase carries several tags, written order decides.

This is a manifest label and it reaches no board. It groups and filters in status, the report and the panel, and selects reviewers and skills. It is not System.AreaPath — a backend card and a frontend card leave for ADO carrying the same tag set, and where the board has to tell them apart that is meta.ado.areaPath or a tag on the item itself, which a push preserves.

Two asymmetries. An absent tag is not a tag: a phase with no area raises nothing, and the validator warns only about an unregistered one — usually a typo — so leaving a phase untagged beats inventing a tag to fill the field. And registering an area makes its silence visible: an area declaring no skills resolves none, so a task with none of its own warns no skills resolve. Answer it with the task's own skills, defaults on the area, or "skills": null — that last one records the intention, where leaving the warning standing records nothing.

Work that /audit:init proposed and nobody accepted yet lives in proposals[], outside the phases. It is a queue, not a plan — an empty live plan with parked proposals means nothing is scheduled, not that something was lost.

The sections, in the order they appear:

What the tests said, on Overview

Open a phase and its detail carries two evidence lines, labelled apart: phase sign-off is the phase's own gate run, and tasks is a roll-up counting its tasks by verdict. They measure different things over different files, so one badge for both would claim a measurement nobody made. The task table below them ends in a tests column, in the same position the report uses.

Badges and markers read exactly as they do in Running phases. A badge with a run behind it is also a button: pressing it opens that run's steps (name, exit, checks, took, outcome) and the basis lines for anything it could not determine. A subject with no recorded run is deliberately not a control, because there is nothing to open.

Everywhere else, panel and CLI are one implementation: materialize, drop and revive run the same script from either side, and so does the config validator. The gaps above are missing paths, not second implementations, which is why a change made in the panel shows up in /audit:status immediately.

Every change to the plan and the config appends one hash-chained row to a journal beside the manifest. It is meant to be committed — that is what makes it evidence rather than a log — and that single fact decides everything else about what a row may hold.

What a row may hold, and what it may not

Because the file ships, no row names a machine. A command is stored as commandSha256 + commandBytes + program, so you can still ask “was it this command?” by hashing your candidate while the arguments — where paths, hostnames and tokens live — are not there. cwd is repo-relative, . at the root, or <outside-repo>; unresolvable, empty and outside all land on that token, because a redactor that guesses is a home directory in a file that ships. There is no actor.host at all. And the file name is the session id or a random per-checkout token rather than the machine's, which mattered most of all: the chain is seeded from that base name, so a name committed there could never be corrected without breaking verify on every clone that already had the file.

The rows a test run leaves

The journal anchors the evidence ledger rather than duplicating it: an exit code and a duration are things the plugin observed about the machine, not fields of the plan.

Each action has exactly one writer — never append one by hand, because two writers means duplicate rows and a doctor that can no longer trust the count. These three are written in process rather than by the journal-writes hook, because the hook watches edit tools and these writers use os.replace and git commit.

[OK     ] evidence       7 pointer(s) in the plan, 9 recorded run(s), and every
                          pointer names a run this checkout holds