audit ยท diff
git:20260716.6f439dd to git:20260719.df0d873
45 added, 1 removed. Audit B to B.
---
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 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).
+ in the same change (stale docs = incomplete). Docs currency includes the project wiki
+ (a separate repo) and in-repo READMEs, not just files inside the commit; where dogma is
+ present, check that `/dogma:docs-update` was the mechanism (or an equivalent manual
+ update happened). audit checks and flags stale docs - it does not run the update itself.
## 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.
+
+ ## Disposition of findings (nothing is silently dropped)
+
+ EVERY finding - at every severity, MINOR and NIT included - must be explicitly
+ DISPOSITIONED. Dropping a finding with no disposition is not allowed. The three allowed
+ dispositions are:
+
+ 1. **Fixed now** - the finding is corrected at its root.
+ 2. **Deferred** - captured as a tracked item (see the credo items skill) with a recorded
+ reason for deferring.
+ 3. **Wontfix** - a conscious decision by the USER not to act (in autonomous mode, a
+ documented default stands in for the user's call).
+
+ The severity levels and the evidence rule above are unchanged; this governs what happens
+ to a finding AFTER it is reported, not whether it is reported.
+
+ **Code fix beats a doc workaround.** When a finding can be fixed cleanly in code, fix it at
+ the root rather than bloating the docs to describe or justify the messiness. Follow the
+ language and project best practices and do not mix conventions - for example a config
+ getter should emit canonical lowercase booleans rather than leaking Python-style
+ `True`/`False` and then documenting the leak. A doc-only workaround is a fallback only when
+ a clean code fix genuinely harms (a real, stated reason - e.g. it would break other
+ callers) or is impossible. Convenience is not such a reason.
+
+ **audit still only proposes.** audit is read-only: it names each finding and its
+ recommended disposition, but it never edits, fixes, or commits. The disposition is carried
+ out by the acting/building agent per the audit's proposal - that separation is the point of
+ the gate.
+
+ **How the acting agent acts on it, by session mode:**
+
+ - **Presence modes (active, passive)** - the acting agent EXPLAINS each finding to the user
+ and recommends the fix via a question. Default recommendation: fix. The user may deem a
+ finding unimportant; borderline calls go to the user, never to the agent's own
+ convenience.
+ - **Autonomous mode** - the acting agent fixes the findings inline BY DEFAULT without
+ asking (asking would block an unattended run), and records what was fixed in the item
+ and the digest. Where a clean fix is genuinely impossible or harmful (a real, stated
+ reason), or the finding is genuinely independent of the audited item's core, it records
+ a documented wontfix (the documented default standing in for the user) or defers it as a
+ tracked item with the reason - never blocking the unattended run to ask.
## 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.