audit-round

name

audit-round

description

External-audit role for arcgentic rounds. Loaded when arcgentic state.yaml is in awaiting_audit or audit_in_progress, OR when the user explicitly requests an external audit of a finished round, OR when reviewing a handoff doc + commit chain against the round's declared scope. Produces a PASS / NEEDS_FIX / AUDIT_INCOMPLETE verdict document with mechanically-verifiable fact table, structured findings (P0-P3), and applies the lesson codification protocol. The output verdict file IS the handoff — do not paste verdict text into chat.

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:

    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