arc-auditing-spec

name	arc-auditing-spec
description	Read-only advisory audit of an SDD spec family — design, spec, dag, and decision anchors.
category	sdd
status	promoted
disable-model-invocation	true
argument-hint	<spec-id> [--save]

Skill: arc-auditing-spec

Iron Law

READ-ONLY ADVISORY. NEVER MUTATE.

Skill body and all three sub-agents MUST NOT Edit, Write, rename, delete, or run any mutating git / filesystem operation. Phase 5 prints a Decisions table and exits. Main session (or a subsequent skill) owns any actual edits — not this skill, never.

No --apply flag, no "while I'm here let me fix this typo" shortcut, no Phase 6 that starts applying decisions. Diagnostic role only.

When to Use

• User types /arcforge:arc-auditing-spec <spec-id> wanting cross-artifact alignment, internal consistency, and state-transition integrity checked across the spec family
• The spec has reached a state where at least design.md exists (spec.xml and dag.yaml optional; graceful degradation per fr-aa-004)

When NOT to Use

• Source code review, PR review → use /review or pr-review-toolkit
• You want this skill to apply resolutions — it won't; it's diagnostic only
• You want an automatic check at the end of arc-refining or arc-planning — those skills do not and must not auto-invoke this one (fr-sc-001-ac3); invocation is always user-initiated

Invocation Contract

/arcforge:arc-auditing-spec <spec-id> [--save]

• <spec-id> — directory name under specs/. Exact match only; no fuzzy resolution.
• --save — optional. When present, writes the full Phase 2 report + Phase 5 Decisions table to ~/.arcforge/reviews/<project-hash>/<spec-id>/<YYYY-MM-DD-HHMM>.md (hash from ${ARCFORGE_ROOT}/scripts/lib/worktree-paths.js). When absent, no file is written anywhere.

Phase 0 — Precondition Check (MANDATORY)

Before Phase 1 fan-out, verify specs/<spec-id>/ exists as a directory.

If it exists: proceed to Phase 1. No file is written at this point.

If it does NOT exist: STOP. Print:

Error: specs/<spec-id>/ does not exist.

Available spec-ids:
  - <id-1>
  - <id-2>
  ...

Then exit non-zero. Write nothing. Spawn no sub-agent. This is the only valid response — see Red Flags for the specific failure modes this rule forbids.

Phase Structure

Phase 0 precondition check (above) → Phase 1 parallel fan-out → Phase 2 markdown report → Phase 3 triage → Phase 4 resolution → Phase 5 Decisions table (terminal).

Phase 1 — Parallel Fan-Out to Three Audit Axes

You MUST dispatch all three audit agents in a SINGLE message using three parallel subagent dispatches. Do NOT dispatch them one at a time. Sequential dispatch is the baseline failure mode this rule exists to prevent — a stock agent defaults to serial execution; this skill forbids it. (For your harness's subagent-dispatch tool, see arc-using/references/codex-tools.md.)

Dispatch these three agents concurrently, in a single message:

• arc-auditing-spec-cross-artifact-alignment
• arc-auditing-spec-internal-consistency
• arc-auditing-spec-state-transition-integrity

Phase 1 Prompt Template

Assemble the sub-agent prompt per references/phase1-prompt.md — that file is the authoritative layout. The prompt carries the spec-id plus resolved absolute paths to design.md (newest docs/plans/<spec-id>/*/design.md), spec.xml (specs/<spec-id>/spec.xml), details/*.xml (specs/<spec-id>/details/), dag.yaml (specs/<spec-id>/dag.yaml), decisions.yml (specs/<spec-id>/decisions.yml), and product/vision.md. When an artifact is missing, substitute the literal absence marker (absent — file does not exist) verbatim — do not omit the line, do not invent placeholder paths. The axis agents depend on the marker for their graceful-degradation branches (fr-aa-004). Absent decisions.yml or product/vision.md causes the cross-artifact-alignment agent to skip its spec↔decision↔anchor graph checks (patterns 7–9) without error.

REQUIRED BACKGROUND: skills/arc-auditing-spec/references/phase1-prompt.md

Partial Failure Contract (fr-aa-004-ac3)

When an axis agent returns an error_flag in its findings, that axis has failed mid-audit. The main session MUST:

1. Surface the error_flag in the Phase 2 Summary table (as a warning row for that axis).
2. Continue rendering Phases 2–5 using findings from the axes that succeeded.
3. NOT halt the audit because one axis encountered an error.

One axis's error_flag does NOT stop the other two axes' findings from being shown and triaged. The sections below are the decision logic; the reference file carries the full worked examples with exact column headers.

REQUIRED BACKGROUND: skills/arc-auditing-spec/references/report-templates.md

Phase 2 — Markdown Report

Print three sections in order. No omissions regardless of severity.

Section A — Summary table (axis | HIGH | MED | LOW | INFO | Total). One row per axis plus a Totals row. If an axis returned error_flag, replace its counts with ERR and note the error below the table.

Section B — Findings Overview table (ID | Sev | Axis | Title | Primary file). Every finding from all three axes MUST appear — MED, LOW, and INFO findings appear in this table exactly as HIGH findings do. No omissions.

When exactly one HIGH finding exists (N_HIGH == 1), the Title cell for that row MUST start with ⚠️ and render the title in bold: ⚠️ **<title>** — so the lone HIGH is conspicuous even when Phase 3 triage does not fire. When N_HIGH is 0 or >= 2, render all Overview rows without the ⚠️ prefix. The prefix MUST NOT appear in the per-finding Detail block header — it is Overview-row-only.

Section C — Per-finding Detail blocks. One block per finding, same order as the Overview. Each block contains:

• Observed evidence as a markdown table (location | evidence).
• "Why it matters" — the ONLY section that may remain free prose.
• Suggested resolutions as a markdown table (Resolution | Description | Side-effect / Cost). When a resolution has a preview diff from the agent, append the diff block under the table row.

MED, LOW, and INFO findings get full Detail blocks here even though they do not enter Phase 3 triage — the Detail block is the visibility mechanism for them.

Phase 3 — Triage UX

Goal: let the reviewer select which HIGH findings to address in this session. MED, LOW, INFO MUST NOT appear as options — only reachable via the Other free-text channel (F-01, pinned). Phase 3 fires only when N_HIGH >= 2; below that threshold the skill takes a degraded path.

Step 0 — Threshold check (MANDATORY before any AskUserQuestion call). Count the HIGH-severity findings across all three axes (N_HIGH).

• N_HIGH == 0: Phase 3 does NOT fire. Do NOT issue any AskUserQuestion call, enter Phase 4, or render a Phase 5 Decisions table. Print the concluding recommendation line (references/report-templates.md §Concluding Recommendation Line) and exit cleanly. The Phase 2 Detail blocks are the complete deliverable.

• N_HIGH == 1: Phase 3 multi-select does NOT fire (a single option would violate options.minItems: 2). Skip Phase 3; proceed directly into Phase 4 with that single HIGH as the sole Stage-2 queue entry (its Overview row already carries the visual emphasis). No Other injection channel exists on this path.

• N_HIGH >= 2: Phase 3 fires. Continue to the steps below.

Step 1 — Determine HIGH finding list. Collect all HIGH-severity findings across all three axes. Sort: A1 before A2 before A3; within each axis sort by NNN ascending.

Step 2 — Batched multi-select loop. Present up to 4 HIGH findings per AskUserQuestion call. When more than 4 HIGH findings exist, make sequential calls batching up to 4 each time until every HIGH finding has been presented exactly once.

Use AskUserQuestion with header: "Triage" and multiSelect: true. Template: see references/report-templates.md §Phase 3.

Step 3 — Parse Other free-text. The AskUserQuestion tool appends an auto-generated Other field. After each call, scan the Other string for the regex A[1-3]-\d{3} and add each matched finding ID to the Stage 2 resolution queue alongside the HIGH IDs the user checked. This is the ONLY channel through which MED, LOW, and INFO findings enter the queue, and it exists only when Phase 3 fires (N_HIGH >= 2).

Phase 4 — Resolution UX

Goal: for each finding in the resolution queue, ask the reviewer which resolution to apply. One resolution per finding (multiSelect: false). Only findings with at least 2 suggested resolutions receive an AskUserQuestion question; findings with fewer than 2 suggested resolutions are auto-skipped (see Per-Finding Skip Rule below).

Batched loop: iterate the Stage-2 queue. For each entry, check its resolution count before issuing a question. Batch qualifying findings (those with >= 2 resolutions) at most 4 per AskUserQuestion call. Sequential calls until all qualifying findings are asked exactly once.

Use AskUserQuestion with header = finding ID and multiSelect: false. Template: see references/report-templates.md §Phase 4.

Rules:

• header = finding ID (format A<n>-<NNN> is 6 chars — no truncation needed).
• When the agent marked a Recommended resolution (per finding-schema.md Recommended prefix rule), the first option's label MUST start with "(Recommended)".
• Options whose resolution corresponds to an editable-artifact change MUST include a preview diff. Engine-fix-type options (e.g., "file a bug against coordinator.js") MAY omit preview.
• Other free-text is a valid decision — accept it, do not throw or drop it. Record it verbatim in the Phase 5 Decisions table User Note column.

Per-Finding Skip Rule: When a finding has fewer than 2 suggested resolutions (0 or 1), the skill MUST NOT issue an AskUserQuestion question for it (options.minItems: 2 forbids a single-option question). Such findings rely on their Phase 2 Detail block's Resolutions table as the deliverable. In the Decisions table, a skipped finding's Chosen Resolution column is the sentinel (no ceremony — see Detail) with an empty User Note. This skip is NOT an error — do not warn or halt the loop; proceed to the next finding.

Phase 5 — Decisions Table (TERMINAL)

Conditional firing gate: Phase 5 renders the Decisions table ONLY when Phase 3 or Phase 4 actually fired. Use the in-memory ceremony_fired flag, set to true the moment either phase issues its first AskUserQuestion call; carry it forward, do NOT re-derive it at Phase 5 entry. The N_HIGH == 1 + <2-resolutions path and the N_HIGH == 0 exit both issue no question, so the flag stays false.

When ceremony_fired is false, Phase 5 MUST NOT print a Decisions table, a stub "No decisions" line, or any output — the concluding recommendation line from Phase 3's threshold check is the terminal output on that path.

When ceremony_fired is true, print the Decisions table, then exit. This is the final deliverable. Template: see references/report-templates.md §Phase 5.

• Finding ID: the A<n>-<NNN> id.
• Chosen Resolution: label of the option the user selected, or "(Other)" when answered via free-text. For findings auto-skipped at Phase 4 (fewer than 2 resolutions), use the sentinel (no ceremony — see Detail).
• User Note: when the user answered via Other, store that free-text verbatim — no paraphrasing, no summarizing. Empty when no Other text was provided. Empty for auto-skipped findings.

The Decisions table MUST include ALL findings that went through Phase 3 triage or Phase 4 resolution, including any findings auto-skipped at Phase 4 whose rows carry the (no ceremony — see Detail) sentinel. The record must be complete — no finding that entered the Stage-2 queue MUST be left out.

Phase 5 is TERMINAL. After printing the Decisions table, the skill exits. The main session MUST NOT apply any resolution via Edit, Write, or any mutating tool based on user decisions — that action is explicitly out of scope for this skill. If you find yourself about to call Edit or Write, or about to invoke /arc-refining to apply changes, STOP — see Red Flags.

--save Flag

When --save is present, the main session writes the full Phase 2 report + Phase 5 Decisions table to ~/.arcforge/reviews/<project-hash>/<spec-id>/<YYYY-MM-DD-HHMM>.md after Phase 5 prints (24-hour time). Without --save: zero files are written anywhere. Derive <project-hash> via a node subprocess calling hashRepoPath from ${ARCFORGE_ROOT}/scripts/lib/worktree-paths.js — never reimplement the hash inline (drift risk). The reference file carries the exact subprocess one-liner, filename example, and mkdir -p command.

REQUIRED BACKGROUND: skills/arc-auditing-spec/references/save-flag.md

Hard Boundaries

• The read-only constraint is enforced structurally via the tools: allowlist in each agent's frontmatter (agents/arc-auditing-spec-*.md) — not via prose. No Edit, Write, git commit, branch/worktree creation, or file deletion, at any phase.
• --save is the ONLY permitted write, and only to ~/.arcforge/reviews/ under the arcforge home directory — never into specs/, docs/, or any project-tracked path.

Red Flags — STOP

If you find yourself doing any of these, STOP immediately:

Rationalization	Why it's wrong	Do instead
"The user's spec-id doesn't exist, but this other one is clearly what they meant — I'll audit that and note the substitution at the top"	fr-sc-001-ac2 forbids substitution. This is a baseline failure mode observed in RED testing — the rationalization "don't ask clarifying questions" does NOT justify picking a different spec.	Print available ids, exit. Let the user re-invoke with the right id.
"The user said <id> and specs/<id>/ is missing, but docs/plans/<id>/ has a design.md — I'll audit in pure-design mode since the design clearly exists"	Phase 0 requires specs/<id>/ specifically. docs/plans/<id>/ is not a fallback path — not for pure-design audits, not for partial, not for anything. A design doc without a spec directory is a pre-refining state; the audit skill does not operate on it.	Print available ids, exit. If the user wanted a design-only review, that's /arc-brainstorming or manual review territory, not this skill.
"I spotted an obvious typo while reading — fixing it saves a round trip"	Read-only is absolute. Even typos are reported as findings, never patched.	Add a finding (LOW severity) to the axis agent's output; let main session decide.
Any of: • "User picked resolution (a) for A1-003 — I should Edit the spec now" • "Phase 5 ended — I'll invoke /arc-refining to apply the decision" • "User selected (Recommended) — applying saves a round-trip"	Phase 5 is terminal (fr-oi-004-ac3). No mutation, no auto-chain, no Edit — even for an obvious Recommended choice. This skill's scope ends at the Decisions table.	Print Decisions table, exit. Main session owns all subsequent action.
"I'll have arc-refining/arc-planning call this skill at the end of their flow for free quality gating"	fr-sc-001-ac3 forbids pipeline auto-invocation. The skill must remain user-triggered.	Do not add any invocation from any pipeline SKILL.md body.
"Let me add a --apply flag so this is one-step for users"	Makes the skill a mutator, defeating its diagnostic-only contract.	Don't. The contract is the contract.
"The agent marked option A as (Recommended), so I can lean on it — emphasize it in the question wording, sort it visually first, fold the others under 'more options'"