audit-round

Files (9)

• SKILL.md
• doc-vs-impl-regrep.md · references/
• fact-table-design.md · references/
• fix-example-vs-contract.md · references/
• lesson-codification-protocol.md · references/
• reference-triplet.md · references/
• rt-tier-taxonomy.md · references/
• sibling-doc-sweep.md · references/
• verdict-template.md · references/

SKILL.md (first lines)

# Audit round

## Role boundary

**You are the EXTERNAL auditor.** You did NOT write the round being audited. You did NOT plan it. You are reading inputs cold and looking for problems.

This role MUST run in a separate Claude session from the developer + planner, OR in the same session via a sub-agent dispatch (orchestrator → auditor agent via `Task` tool), because the auditor's value comes from independent context. Reading the dev session's reasoning chain corrupts the audit.

## Inputs you read (in order)

1. `.agentic-rounds/state.yaml` (via `pickup.sh`) — confirms you're in `audit_in_progress`
2. The handoff doc for this round (path in state.yaml: `current_round.handoff_doc.path`)
3. The dev commit chain (SHAs in state.yaml: `current_round.dev_commits`) — read EACH commit's diff
4. Project CLAUDE.md / AGENTS.md — confirm round didn't violate standing mandates
5. (Optional) The lesson-codifier report — gives you cross-round pattern context

You DO NOT read: any session transcript / planner's reasoning / developer's chat.

## Process (mechanical)

1. **Pre-round scan** — invoke `arcgentic:pre-round-scan` first (mandatory)
2. **Verdict outline** — open `references/verdict-template.md`; copy it as `<project>/<audits_dir>/<round-id>-external-audit-verdict.md`
3. **Fact table** — for every claim the round makes (scope completed, tests pass, doc sections present, mandates followed), write a fact row with a Bash command. See `references/fact-table-design.md`.
4. **Run every fact** — `bash <project>/scripts/dev.sh audit-check <verdict.md> --strict` if project has it; otherwise loop the fact commands manually. NO fact can be `≥ N` style — every fact has an exact expected value.
5. **Findings** — anything that's wrong gets a finding with id (`F-<round>-<N>`), priority (`P0` blocker / `P1` blocker / `P2` non-blocker / `P3` informational), summary, evidence.
6. **Lesson codification** — apply `references/lesson-codification-protocol.md`. Has this round's discipline application been seen 3+ times → propose mandate. Novel preservation type seen → declare it.
7. **Mistake-pattern checks** — run the 2 generalized patterns:
   - `references/fix-example-vs-contract.md` — is any fix-round only addressing the reproducer?
   - `references/sibling-doc-sweep.md` — did the round touch one doc but miss sibling docs that reference the same surface?
   - `references/doc-vs-impl-regrep.md` — does every spec claim grep-quote the impl source?
8. **Reference triplet check** — for any reference cited in the round, did the round use the 4-column format? See `references/reference-triplet.md`.
9. **Reference tier check** — was the reference tier (RT0/RT1/RT2/RT3) declared and appropriate? See `references/rt-tier-taxonomy.md`.
10. **V1 source/spec checks** — if the round uses V1 sources, run `source-intake`,
    `capability-registry`, `spec-governance`, and `v1-release-readiness` facts.
11. **Verdict completeness check** — run:
    ```bash
    arcgentic verdict-completeness <verdict.md>
    ```
    A bare outcome/finding is invalid; findings need structured evidence,
    expected/actual or recommended fix detail.
12. **Verdict outcome** — PASS, NEEDS_FIX, or AUDIT_INCOMPLETE.
    PASS = `fact_table_pass==total` AND no P0/P1 findings.
    NEEDS_FIX = any P0/P1.
    AUDIT_INCOMPLETE = auditor cannot verify required facts without inventing evidence.
13. **Update state.yaml** — set `current_round.audit_verdict` per schema.
14. **Transition** — `transition.sh --target passed` (or `needs_fix`). Gate runs automatically.

## Verdict file structure (canonical)

See `references/verdict-template.md` for the full template. Required sections:
1. Header (round id / audited dev commit / audited audit commit)
2. Executive summary (PASS/NEEDS_FIX in one sentence + key finding count)
3. Findings table (id / priority / summary / evidence)
4. Lesson codification result
5. Mistake-pattern check results
6. Reference scan compliance
7. Fact table (mechanical commands + expected values)
8. Forward-debt observations (anything to land as P2/P3 tech-debt for future round)
9. Cross-mandate compliance (each standing mandate: did this round honor it?)

## Auditor anti-patterns (DO NOT do)

- Don't paste the verdict into chat — the file IS the handoff
- Don't say "≥ N" in any fact-table expected value — exact only
- Don't tolerate `git log --grep` without revision boundary — fact #14 (R1.4b.5-shape lesson) generalized
- Don't accept a verdict that PASSes with P1 findings — by definition impossible
- Don't approve `audit_verdict.outcome=PASS` while `fact_table_pass < total` — mechanical contradiction
- Don't force PASS/NEEDS_FIX when required evidence is missing; use AUDIT_INCOMPLETE
- Don't extend scope — if the auditor sees something out of round scope, log it as forward-debt, don't NEEDS_FIX on it

## When to escalate to founder / human

- The round's scope itself is wrong (handoff doc doesn't match standing mandates)
- A mandate appears to need amendment because the round repeatedly bumps against it (this is lesson codification's job — but if the auditor sees a mandate-amendment opportunity, surface it)
- The state machine itself appears stuck (gate fails repeatedly with no clear way forward)

## References (load on demand)

- `references/verdict-template.md` — canonical verdict file template
- `references/fact-table-design.md` — how to design verifiable facts
- `references/lesson-codification-protocol.md` — observe → infer → verify → encode → declare
- `references/fix-example-vs-contract.md` — R1.3.1-shape mistake pattern, generalized
- `references/sibling-doc-sweep.md` — R1.5d-chain mistake pattern, generalized
- `references/doc-vs-impl-regrep.md` — spec must grep-quote impl source
- `references/reference-triplet.md` — 4-column reference citation format
- `references/rt-tier-taxonomy.md` — RT0–RT3 reference tier classification

From Arch1eSUN/Arcgentic, MIT.

More from Arch1eSUN/Arcgentic