audit git:20260716.f098193B

Immutable. This exact content is served forever at /api/v1/blob/0eea6f11abd51a1f.

---
name: audit
description: Read-only quality gate that audits already-built work against its stated requirement and Definition of Done before it is allowed to move to 2_done/. Produces a severity-ranked decision proposal (BLOCKER/MAJOR/MINOR/NIT) with evidence, never a fix. Use when an item is claimed complete, before moving anything to 2_done/, when asked to audit or review finished work for completeness against requirements, or when acting as the dedicated post-completion review subagent. This gate is mandatory in every session mode. Not for diagnosing why something is broken (use diag) and not for verifying rendered UI behavior (use verify).
---

# audit

A **read-only** quality gate. `audit` inspects work that is claimed complete and
judges whether it actually satisfies its stated requirement and Definition of Done,
BEFORE the item is allowed into `2_done/`. The output is a decision proposal for the
user, never a change.

> **Task backend.** If `CREDO_TASK_BACKEND=gsd`, the credo item lifecycle is inactive and
> there is no `2_done/` gate to run - GSD owns task tracking. audit is still usable as a
> standalone read-only review tool, but it does not gate credo items in that mode.

## Scope boundary (read this first)

`audit` judges whether FINISHED work is genuinely done and correct against its
requirement. It does not investigate causes and it does not exercise UI.

- Something is broken and you need the root cause -> use **diag**, not audit.
- A rendered UI needs its layout and behavior confirmed -> use **verify** (audit may
  cite verify evidence, but it does not drive a browser itself).
- audit only reports findings and a verdict. It never edits code, never fixes, never
  commits.

## Hard constraints (never violate)

- **Read-only.** No code change, no file edit to the work under review, no commit, no
  push, no browser automation, no builds, no installs.
- **No secrets.** Never read credentials, tokens, `.env*`, key files, or shell/session
  history. Never exfiltrate or encode such content.
- The only files `audit` writes are its own report under `.credo/process/reports/`.
- **Dedicated auditor.** The audit MUST be performed by a subagent that is NOT the
  builder of the item under review. A builder auditing their own work does not satisfy
  the gate.

## The mandatory completion gate

Audit-after-completed is a **mandatory gate before any item moves to `2_done/`**, in
**all** session modes (active, passive, autonomous). No exceptions:

1. A builder claims an item complete.
2. A dedicated audit subagent (not the builder) runs `audit` against that item.
3. Only a passing audit lets the item move to `2_done/`. A failing audit sends the
   item back out (see Findings handling).

Whatever is needed to complete the core of the item is part of that item and is NOT a
separate side finding. The gate is about the item's own Definition of Done.

## What to audit against

For the item under review, gather the ground truth first (read, do not guess):

- The item's `Requirement (verbatim)` and its source. Treat user-verbatim text as
  authoritative; never trim, soften, reinterpret, or invent constraints.
- The item's `Success Criteria (= DoD)` (the observable "user can X" statements).
- The `ui` frontmatter flag. If `ui: true`, a visual verify (via the `verify` skill)
  is a DoD requirement, and its evidence must exist and be current.
- Any living conventions under `.credo/docs/` and relevant project `docs/**`.

Then compare the actual built result (files, wiring, tests, verify evidence) against
that ground truth. Confirm each success criterion is genuinely met, that new code is
reachable and wired (not present-but-unreachable), and that documentation was updated
in the same change (stale docs = incomplete).

## Severity levels

Rank every finding with exactly one level:

- **BLOCKER** - the item does not meet its core requirement or a success criterion; it
  must not enter `2_done/`.
- **MAJOR** - a significant defect or gap that materially degrades the result but is
  short of a hard blocker.
- **MINOR** - a small defect or deviation that should be fixed but does not endanger
  the core.
- **NIT** - cosmetic or stylistic; optional.

## Evidence (required for every finding)

Every finding MUST carry concrete, checkable evidence:

- `file:line` for code or documentation findings.
- The screenshot location under `.credo/screenshots/` for visual findings (naming
  `<task-or-feature>-<viewport>-<YYYY-MM-DD>.png`; viewport widths come from the config
  key `verify.viewports`).
- The exact requirement or success-criterion text the finding contradicts.

No evidence -> not a finding. A verdict without evidence is not acceptable.

## Findings handling (what happens on a failing audit)

- **Core deviation:** if a finding shows the item misses its core requirement, the
  WHOLE item plus the finding goes back out of done. Move it back to `1_todo/2_go` if
  the fix is clear and approved, or to `1_todo/1_clarify` if it needs a user decision.
  Record in the item's `Historie` why it came back.
- **New independent item:** create a separate item ONLY if a finding is genuinely
  independent of the core of the audited item. If the finding is something the core
  completion needs, it is part of this item, not a new one.
- The auditor never silently downgrades or repairs; it proposes, the move follows the
  verdict.

## Result: a decision proposal

The audit result is a **decision proposal** for the user, not a unilateral action.
State a clear verdict (pass, or fail with the highest severity present) and the
recommended item move. The user (or, in autonomous mode, the governing session rules)
acts on it.

## Report

Write one report per audit to `.credo/process/reports/` (resolve `.credo` via the repo
root; the reports directory is created by `credo-init`). Use frontmatter `kind: audit`:

```
---
kind: audit
item: 124
date: YYYY-MM-DD
verdict: fail
highest_severity: BLOCKER
auditor: <subagent role, not the builder>
---

## Summary
<one-line verdict and recommended item move>

## Findings
- [BLOCKER] <what> - evidence: path/to/file.ext:42 (or screenshot path) - contradicts: "<criterion text>"
- [MINOR] <what> - evidence: ...

## Recommendation
<move item back to 1_todo/2_go | 1_clarify | allow into 2_done/; new independent items, if any>
```

Reference the item as `#<id>` and by date; do not rely on transcript line numbers.

## dogma-first

Where dogma already governs a concern (versioning, git rules, language, linting),
audit checks against dogma first and treats credo rules as fallback only, never as a
duplicate or a conflict. DOGMA-PERMISSIONS always take precedence.