audit

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 the task backend is gsd (.credo/config: task_backend, or the CREDO_TASK_BACKEND env override), 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.