cross-audit
Iterative cross-audit with Claude + Codex working independently then consolidating findings. Runs in background — does not block the main conversation.
SKILL.mdskills/cross-audit/SKILL.md
GitHubCross-Audit: Background Parallel Review
Cross-audit runs Claude (Opus) and Codex (GPT, model from ~/.codex/config.toml) as independent auditors, consolidates their findings into KB documents, then iterates until clean. Runs in the background so you can continue working.
/cross-audit runs in background — you can keep working while it runs
User-input prompt presentation in this skill follows the banner
convention in docs/user-input-banner-convention.md — the per-finding
decision fork in Phase 3 carries the AWAITING YOUR INPUT banner.
Caveman activation in this flow
Caveman compression is mandatory in this flow. The wire prefix [COMPRESSION:terse] MUST be prepended to every subagent Task description and to every Codex MCP developer-instructions: field within this flow. Machine-output payloads (haiku scorer JSON, render_findings / dedupe_findings IO, parser inputs) are exempt per skills/caveman/SKILL.md §7.
Argument Parsing
Re-audit detection: if $ARGUMENTS matches *-findings.md AND the file exists on disk → re-audit iteration. If it looks like a path but doesn't exist → error out and ask the user. Otherwise → new audit.
PR-mode detection: if $ARGUMENTS starts with pr <N>, pr owner/repo#<N>, or pr <url> → PR audit. Skip legacy scope parsing; run Phase 0.5 (below) to resolve pr_repo / pr_url / pr_number and fetch pr_changed_files. Three accepted input forms:
pr <N>(bare number, e.g.pr 472) — resolve repo viagh repo view --json nameWithOwnerin the caller's cwd; if cwd is not a gh-known repo, stop with remediation.pr owner/repo#<N>(e.g.pr roman-karpovich/ai-dev-team#472) — repo taken from theowner/repoprefix.pr <url>(e.g.pr https://github.com/roman-karpovich/ai-dev-team/pull/472) — repo and number parsed from the URL.
Standalone publish: /cross-audit publish <slug> <ids> is a second entry point that invokes the publish action against an existing findings doc resolved from <slug> (e.g. 2026-04-14-webhooks). Skips Phases 0.5 / 1-2 / 3-fix; jumps straight into publish using the pr_files / pr_head_oid / pr_url persisted in findings frontmatter. See references/publish.md for the full recipe. Publish is orthogonal to the status state machine — it does NOT flip OPEN→FIXED.
Ref-range detection: if $ARGUMENTS contains .. (literal two-dot) or ... (literal three-dot) forming a <refA>..<refB> or <refA>...<refB> pattern AND both <refA> and <refB> resolve via git rev-parse --verify <ref> AND neither half is empty → ref-range mode. Optional path filter suffix -- <path> is preserved verbatim. Detection uses the literal .. substring; disambiguation from path scopes containing .. (e.g. ../sibling/) relies on the rev-parse preflight — such paths fail to resolve and fall through to legacy scope parsing. Hard-stops: invalid ref (either half fails git rev-parse --verify) → error "ref does not exist: <ref>"; refA and refB resolve to the same SHA → error "no changes between refs". Two-dot (..) and three-dot (...) semantics follow git diff conventions — the operator is passed through verbatim. The ref-range resolver helper (hooks/lib/cross_audit_resolve_range.sh) is the single source of parsing + validation logic; call it in this branch and hard-stop on non-zero exit.
Flags (orthogonal to each other):
--diff→ scope the audit to files changed sincebase_branch(default: auto-detected repo default, falls back tomain). Can combine with any mode: e.g.--diff --mode logicaudits only changed files using logic focus areas.--mode logic|security|full|decision→ audit mode (default:full).decisionmode audits the decisions recorded in a/featureartifact trail (not code) — its scope is a KB spec path (/cross-audit <kb-spec-path> --mode decision), it returns findings inline (no findings.md written), and it defaults--severitytomedium+. See Decision mode below.--severity high|medium+→ severity floor (default:high).highcollects only CRITICAL/HIGH (current behavior).medium+also includes MEDIUM — useful for small features where serious findings are unlikely but nitpick-level review is still valuable.--force-publish-stale→ (publish only) bypasses the force-push preflight when the current PRheadRefOidhas diverged from the audit-timepr_head_oid. Records the stale OID inhead_oid_at_publishfor audit trail. Seereferences/publish.md.--republish <ids>→ (publish only) forces re-posting IDs already present in apublished_torecord for the same PR URL. Adds a new record.--materialize=worktree→ (ref-range mode only) create a temporary worktree atrefB(git worktree add /tmp/cross-audit-<audit_slug> <refB>) so the cross-auditor reads file content fromrefBrather than the current working tree. Cleanup:git worktree remove --force+rm -rfat audit end (best-effort). Default off (no materialization). Anti-combinations: PR mode +--materialize→ hard-stop ("PR mode already materializes viagh pr checkout;--materializeis for ref-range only"); non-ref-range scope +--materialize→ warn ("--materializeis a no-op outside ref-range mode") and proceed.--worktree→ (any mode: default /--diff/--mode */ ref-range) snapshot-isolate the current tree into a skill-owned worktree so the user can keep editing while the audit runs. Mechanics:WT=$(mktemp -d) && git worktree add --detach "$WT" HEAD(snapshot of committed HEAD;mktemp -dnot a slug-derived path so it never collides on repeat same-day runs), passworking_directory: $WTto the cross-auditor, register cleanup on completion OR error:git worktree remove --force "$WT"thenrm -rf "$WT"(best-effort — failure logged, not fatal). This reuses the same skill-owned worktree lifecycle as PR mode ($PR_WT) and--materialize(/tmp/cross-audit-<audit_slug>) — one mechanism, three triggers. Snapshot semantics:--worktreeaudits the committed HEAD state; uncommitted / working-tree changes in the primary are NOT carried into the worktree (git worktree addchecks out a committed ref). To audit uncommitted work, either commit first, or run in-place (default) and accept live-file reads. Requires a git repo: if the caller cwd is not inside a git repo, hard-stop with remediation "--worktreeneeds a git repo; omit it to run in-place" — do NOT silently fall back (the user explicitly asked for isolation). Anti-combinations:--worktree+--materialize=worktree→--materializewins (it also selects refrefB); emit one warning--worktree is redundant with --materialize; using --materialize (refB)and proceed;--worktree+ PR mode → redundant no-op (PR mode already materializes a worktree); emit one warning--worktree is redundant in PR mode (already worktree-isolated)and proceed.
Removed-flag hard-fail (per docs/cut-spec-policy.md). If $ARGUMENTS contains either of the flags below, hard-stop with the corresponding canonical error message — do NOT attempt to interpret the argument or silently drop it:
--probe-downgrade→ emitERROR: --probe-downgrade was removed in cut spec design/2026-04-26-cut-probe-downgrade.md. Read that spec for the migration path.--account→ emitERROR: --account was removed in cut spec design/2026-04-27-cut-multi-gh-account.md. Read that spec for the migration path.
Decision mode (--mode decision)
--mode decision audits the implementation decisions recorded in a /feature artifact trail — spec §9 Log decision lines, the grill ## Decisions table, workdoc planned/observed blocks + design_decision fields, findings-doc triage statuses, audit-evidence frontmatter — rather than auditing code. Reviewer scenario: a large PR shipped via /feature, code cross-audit is clean, and the reviewer runs decision-audit on the KB artifacts to check whether the decisions were verified or rubber-stamped. Standalone-first: the invocation surface is /cross-audit <kb-spec-path> --mode decision.
Scope + standalone slug derivation. The <scope> argument is the audited KB spec path (e.g. design/2026-07-02-decision-audit-mode.md). No /feature orchestrator supplies the slug, so the skill derives it: feature_slug = basename(scope) minus the .md extension minus the leading YYYY-MM-DD- date prefix. Then workdoc_path = <kb>/repos/<project>/design/workdocs/<feature_slug>/exec.md and findings_paths = sorted(glob <kb>/repos/<project>/security/<feature_slug>-*findings.md). Worked example: design/2026-07-02-decision-audit-mode.md → feature_slug = decision-audit-mode → workdoc design/workdocs/decision-audit-mode/exec.md, findings glob security/decision-audit-mode-*findings.md. Raw-basename (date-prefix-retaining) resolution is WRONG — it points at a non-existent workdoc dir and an empty findings glob silently. A missing workdoc or empty findings glob at the derived paths is NOT an error (a greenfield spec legitimately has neither — pass what exists), but the derivation itself must be the date-stripped form.
Dispatch param block. Decision mode threads into the cross-auditor (all names except findings_paths are the agent's existing §Input params — do NOT introduce a separate project_path / spec_path vocabulary):
scope: <kb-spec-path> # the audited spec (spec-mode channel)
workdoc_path: <derived design/workdocs/<feature_slug>/exec.md>
findings_paths: [<sorted security/<feature_slug>-*findings.md>, ...] # pass what exists; [] is legal
working_directory: <source-repo content root> # premise re-derivation reads THIS root
project_type: <detected>
kb_path: <kb_path>
project: <project>
audit_slug: <feature_slug>-decisions
iteration: <N>
previously_fixed: <ids, if re-audit>
next_finding_id: <N>
severity_floor: <medium+> # decision-mode DEFAULT; --severity overrides
base_branch / range_spec are OMITTED — decision mode reads documents, not a diff. severity_floor DEFAULTS to medium+ for decision mode (NOT the global high default): the decision-mode severity ladder parks fork-analysis and most vacuous-rationale forms at MEDIUM, so a high floor would take two of the five focus clusters dark. --severity high still resolves to narrow on demand.
Return. Decision mode rides the spec-mode inline-footer channel: it returns findings inline plus the 3-line evidence footer and writes NO findings doc to disk. Phase 3 presents the inline findings directly (see Decision-mode return handling in Phase 3, which also carries the classifier channel, the orchestrator Log-append rule, and the no-publish rule).
Phase 0: KB Discovery
KB discovery algorithm (resolving kb_path and project via .ai-dev-team.local.yml → .ai-dev-team.yml → memory → sibling → ask) follows docs/kb-discovery.md — single source of truth.
Cross-audit extensions
Cross-audit reads codex.model and codex.reasoning_effort from the resolved config and passes them into the cross-auditor dispatch.
cross_audit.probes.<id>.mode read (probes kill-switch)
Phase 0 also reads the optional cross_audit.probes block from the resolved config. Each probe id (e, f, g, h, and any future id) carries a four-mode kill-switch — off | shadow | warn | block. The resolved probe_modes dict (probe id → effective mode) is threaded into the cross-auditor dispatch in Phase 1-2.
- Default off: when
cross_audit.probesis absent from the resolved config, OR a given probe id is missing undercross_audit.probes, the effective mode defaults tooff. Absence is a user-declared floor, not a synthesized gap (per §3.4 X9 resolution). - Unknown probe id → warning, not hard-stop: when the YAML names a probe id the plugin does not ship a
probe_<id>.shfor (e.g.z: { mode: shadow }), emit a one-line warningcross_audit.probes.<id>: unknown probe id, treated as off — ignored for this runand continue. Probes are a forward-looking enum; new ids arrive in follow-up specs without needing a Foundation re-release. Unknown-id emissions never hard-stop Phase 0. - Mode enumeration: the four allowed values are
off|shadow|warn|block. Any other string emits the same one-line warning and falls back tooff.
See docs/kb-discovery.md for the canonical YAML schema and docs/kb-discovery.md → "cross_audit.probes.<id>.mode kill-switch" for the full mode semantics (shadow section routing, blocking semantics, Phase 3 presentation).
New audit: generate audit_slug = YYYY-MM-DD-<scope-slug>.
Re-audit: extract audit_slug from the existing findings doc filename — strip the path prefix and -findings.md suffix (e.g. …/2026-04-14-workflow-definitions-findings.md → 2026-04-14-workflow-definitions). Do NOT regenerate from the current date; the slug must match the original to write to the same file.
Phase 0.5: PR discovery (PR mode only)
Runs only when $ARGUMENTS selected the pr <N> / pr owner/repo#<N> / pr <url> form. Produces the five fields (pr_number, pr_repo, pr_url, pr_head_oid, pr_changed_files) that Phase 1-2 threads into the cross-auditor dispatch. Skipped entirely for non-PR audits — they still use the legacy <scope> path.
Preflights (hard-stop on failure — never silent fallback)
ghauthentication:gh auth status. Absent or unauthenticated → stop with remediationgh auth login/gh auth refresh -s repo. Never pretend the audit ran.- REST rate budget:
gh api rate_limit -q '.rate.remaining'. Ifremaining < 50, stop with the output ofgh api rate_limit(reset time included). Audit + publish together consume ≈3-5 REST calls. - cwd-repo matches pr_repo: once
pr_repois resolved (see below), rungh repo view --json nameWithOwner -q '.nameWithOwner'inside the caller's cwd. If that value ≠pr_repo, stop with remediation "Run/cross-audit pr <N>from a clone of<pr_repo>(currently in<cwd_repo>)". Rationale: the skill materializes the PR worktree from the caller's cwd viagit worktree add;gh pr checkoutonly succeeds when the local repo targetspr_repo.
Resolve pr_number / pr_repo / pr_url / headRefOid
Parse the argument form:
pr <N>:pr_number = N. Rungh repo view --json nameWithOwner -q '.nameWithOwner'in cwd →pr_repo. If cwd is not a gh-known repo, stop.pr owner/repo#<N>: split on#→pr_repo,pr_number.pr <url>: parsehttps://github.com/<owner>/<repo>/pull/<N>→pr_repo,pr_number.
Then fetch PR metadata and capture headRefOid:
gh pr view <pr_number> --repo <pr_repo> \
--json number,url,baseRefName,headRefName,headRefOid,headRepositoryOwner,headRepository,baseRepository
- Extract
.url→pr_url,.headRefOid→pr_head_oid. Both are threaded into the cross-auditor input. headRepositoryOwnermay differ frombaseRepository.owner(fork PR). The cross-auditor materializes PR content viagh pr checkout --forcewhich fetches the fork remote — fork PRs are first-class. Do NOT fall back to localgit diff.
Fetch pr_changed_files (authoritative, paginated)
GitHub's /pulls/{N}/files endpoint caps at 100 without pagination; gh pr view --json files silently truncates at 100. Always use the paginated REST endpoint with an explicit jq projection that preserves status, previous_filename, and patch_present (the raw patch text is stripped — is_submodule is resolved in the worktree, see agents/cross-auditor.md):
gh api "repos/<pr_repo>/pulls/<pr_number>/files" \
--paginate \
--jq '.[] | {filename, status, previous_filename, patch_present: (.patch != null)}'
Collect the resulting line-delimited JSON objects into the pr_changed_files list of objects (not strings). This list is the single source of truth for the audit's "Files to audit" and for publish routing.
Dispatch into cross-auditor
In addition to the fields documented in Phase 1-2 below, thread:
pr_number: <N>pr_repo: <owner/repo>pr_url: <url>pr_head_oid: <sha>— headRefOid captured abovepr_changed_files: [ {filename, status, previous_filename, patch_present}, ... ]
The cross-auditor persists all five into findings frontmatter (plus a pr_files list with per-file is_submodule resolved inside the worktree). Publish reads those fields back from KB — it never re-runs Phase 0.5 itself.
PR-mode worktree materialization (skill-owned — replaces harness isolation)
PR mode is mandatory worktree-isolated (not user-disableable): gh pr checkout --force is destructive, so an in-place PR audit would clobber the caller's checkout. The skill materializes a dedicated worktree from the caller's repo (preflight 3 above already guarantees it is a clone of pr_repo) and threads it as working_directory, mirroring the --materialize=worktree lifecycle. BEFORE spawning the cross-auditor in Phase 1-2:
PR_WT=$(mktemp -d) && git worktree add --detach "$PR_WT" HEAD— usemktemp -dfor the path, NOT/tmp/cross-audit-<audit_slug>-pr: PR mode skips legacy scope parsing soaudit_slugis undefined at PR dispatch, and a fixed slug-derived path would collide on same-day repeat PR audits / stale leftovers. The--detachkeeps HEAD off any branch ref (branch refs are shared across all worktrees of one repo, so a non-detached checkout could force-reset a branch the primary worktree holds).- Pass
working_directory: $PR_WTto the cross-auditor (the agent's Step 0 then runsgh pr checkout <pr_number> --detach --force --repo <pr_repo>inside it). - Register cleanup on completion OR error:
git worktree remove --force "$PR_WT"thenrm -rf "$PR_WT"(best-effort — failure logged, not fatal), identical to the--materializecleanup contract.
--worktree + PR mode is a redundant no-op (PR mode already materializes a worktree) — emit the warning documented in §Argument Parsing Flags and proceed without a second worktree.
Phase 1-2: Background Audit + Consolidation
DO NOT block the main conversation. Dispatch to cross-auditor agent immediately.
Step 1: Determine parameters
From $ARGUMENTS derive:
- scope: files/directories/feature area (for
--mode decisionthis is the audited KB spec path — see Decision mode above) - mode:
logic|security|full|decision - severity_floor:
high(default) |medium+— from--severityflag.--mode decisiondefaults tomedium+(nothigh) — its severity ladder parks fork-analysis and most vacuous-rationale forms at MEDIUM, so ahighfloor would take two of the five focus clusters dark;--severity highstill narrows on demand. - base_branch: for diff mode (default: auto-detected via
git symbolic-ref refs/remotes/origin/HEAD, falls back tomain) - range_spec: for ref-range mode — the full diff range string passed verbatim to
git diff --name-only, e.g.v1.7.0...v2.0.2orv1.7.0..v2.0.2 -- subdir/. Formatted by joining<op>with refA/refB:<refA><op><refB>(then appending-- <path_filter>if path_filter is non-empty). - materialize_mode:
worktreewhen--materialize=worktreewas given; unset otherwise. - previously_fixed: if re-audit, extract from existing findings doc
- project_type: detect from codebase (smart_contract, backend, frontend, data_pipeline) — extend with
none(a project may declare itself typeless, e.g. a markdown+bash+python plugin) - iteration: 1 for new audit, N+1 for re-audit
- kb_path: from discovery above
- project: project name
- audit_slug:
YYYY-MM-DD-<scope-slug>(new audit) or extracted from the existing findings filename (re-audit — see Phase 0). For ref-range mode:YYYY-MM-DD-range-<sanitized-refA>__<sanitized-refB>where sanitization replaces[^a-zA-Z0-9._-]with-and caps each half at 60 chars (produced bycross_audit_resolve_range.sh'sslug_pairoutput).
Decision mode (--mode decision) derives these additional params — the canonical rule is in the Decision mode section above (§Scope + standalone slug derivation + Dispatch param block); reproduced here so Step 2 has values to thread:
- feature_slug:
basename(scope)minus the.mdextension minus the leadingYYYY-MM-DD-date prefix (the date-stripped form — raw-basename resolution is WRONG). - workdoc_path:
<kb>/repos/<project>/design/workdocs/<feature_slug>/exec.md. - findings_paths:
sorted(glob <kb>/repos/<project>/security/<feature_slug>-*findings.md)— pass what exists;[]is legal (a greenfield spec has neither; missing artifacts are NOT an error). - next_finding_id:
1for a new audit; on re-audit continue past the highest finding id already assigned. - audit_slug:
<feature_slug>-decisions(overrides the date-slug form above — decision mode reads a spec, not a diff or a-findings.md). - base_branch / range_spec are NOT derived (decision mode reads documents, not a diff); severity_floor defaults to
medium+per the bullet above.
Step 2: Launch cross-auditor agent in background
Standalone in-place warning (A2 — emit BEFORE dispatch). When standalone /cross-audit runs in-place — the caller cwd IS a git repo AND no worktree mode is active (NOT PR mode, NOT --materialize=worktree, NOT --worktree) — emit one loud line before the dispatch: ⚠️ In-place audit: running in the primary checkout. The §3.2 read-only-git contract is the only safeguard — there is NO automatic branch restore on this path. Use /feature's flow, or commit first / pass --worktree, if you want the guard. This standalone path has no §3.5d orchestrator branch-guard; the contract is the front-line defense. Omit the line entirely when a worktree mode is active (the worktree is the physical barrier) or when cwd is not a git repo.
Cross-audit the following scope.
scope: [derived scope]
project_type: [detected type]
mode: [logic|security|full|decision]
severity_floor: [high|medium+]
codex_model: [from config, if set]
codex_reasoning_effort: [from config, if set]
kb_path: [kb_path]
project: [project]
audit_slug: [audit_slug]
iteration: [N]
base_branch: [branch, if diff mode]
range_spec: [range_spec, if ref-range mode]
previously_fixed: [list of IDs, if re-audit]
working_directory: [cwd]
[Decision mode only (`--mode decision`) — derived in Step 1 / see the Decision mode section:]
workdoc_path: [derived <kb>/repos/<project>/design/workdocs/<feature_slug>/exec.md]
findings_paths: [sorted security/<feature_slug>-*findings.md; [] is legal]
next_finding_id: [N]
# base_branch / range_spec are OMITTED for decision mode (it reads documents, not a diff);
# severity_floor is threaded above with the decision-mode default medium+ (not the global high).
[PR mode only — populated from Phase 0.5:]
pr_number: [N]
pr_repo: [owner/repo]
pr_url: [https://github.com/.../pull/N]
pr_head_oid: [headRefOid sha]
pr_changed_files: [ {filename, status, previous_filename, patch_present}, ... ]
[Probe plumbing — populated from Phase 0:]
probe_modes: [dict mapping probe id → effective mode resolved from the cross_audit.probes YAML kill-switch; empty dict when no probe configured]
# probe_receipts is NO LONGER threaded by the skill — probe dispatch happens
# inside the cross-auditor agent at Step 0.5 (spec 2026-04-21-probe-e-diff-
# scope-leak §3.5 / X2); receipts are produced there.
[If re-audit: include the current findings doc path for context]
Ref-range materialization (when materialize_mode == worktree): before dispatching, create the worktree: git worktree add /tmp/cross-audit-<audit_slug> <refB>. Pass working_directory: /tmp/cross-audit-<audit_slug> to the cross-auditor. Register cleanup: after audit completion (or on error), run git worktree remove --force /tmp/cross-audit-<audit_slug> then rm -rf /tmp/cross-audit-<audit_slug> (best-effort — failure is logged, not fatal). When materialize_mode is unset and neither refA nor refB equals HEAD, emit one warning line before dispatch: "⚠️ Reading file content from current working tree (not from <refB>). Use --materialize=worktree for precise content at refB."
Step 3: Inform the user
Cross-audit running in background on [scope] (mode: [mode], iter [N]). Findings →
KB/repos/<project>/security/<slug>-findings.mdContinue working — I'll present results when both auditors finish.
Decision mode (--mode decision) variant. Decision mode writes NO findings doc, so DROP the Findings → … line — there is no findings path to surface and printing one points at a file that will never exist; decision findings return inline. Emit instead:
Cross-audit running in background on [scope] (mode: decision, iter [N]). Decision findings return inline — I'll present them when both auditors finish.
Phase 3: Present & Decide (foreground, interactive)
When cross-auditor completes:
- Apply the §3.5b-2 recovery algorithm to the agent's raw return before step 1 — this is callsite 5 of the 6 §3.5b-2 recovery callsites (the standalone
/cross-auditPhase 1-2 initial dispatch). The recovery algorithm body is canonical inskills/feature/SKILL.md§3.5b-2; the standalone-mode specifics are in the §Cross-auditor return-contract gate subsection below. Classifier output gates whether the findings.md read in step 1 proceeds, or the §3.4d standalone terminal banner fires. - Read the findings doc from KB (logic / security / full modes). Decision mode has NO findings doc — skip this read and follow the Decision-mode return handling subsection below instead.
- Present to user:
Audited HEAD: <oid>(logic / security / full — file-backed modes ONLY) — one line rendered from the leading findings-frontmatteraudited_head:pin (re-audit iterations refresh it via the overwrite rule). OMITTED for spec / decision modes (no findings doc;audited_headis not part of the inline-footer contract) and for non-git file-backed runs where the pin was omitted at emit per the §3.2 carve-out.- Count by severity and confidence
- HIGH CONFIDENCE findings first (both auditors agreed)
- REVIEW findings second (one auditor only)
- Stop and wait for user decision per finding — present the banner below.
Decision-mode return handling
For --mode decision the flow above changes as follows — decision rides the spec-mode inline-footer channel and writes NO findings doc:
Classifier channel. Decision-mode returns ride the
specclassifier channel: a decision-mode return is classified through thecheck_dispatch_response.py --mode specpath (footer shape identical to spec mode; no--findings-path). The return-contract gate below runs the same--mode specinvocation it already runs for spec-mode returns — otherwise identical.Skip the findings.md read. Step 1 above reads a findings doc; decision mode has none. SKIP the findings.md read and present the inline findings from the agent return directly (count by severity, HIGH-confidence first, then REVIEW) — the same presentation as step 2, sourced from the inline report rather than from KB.
Log-append (single persistence trace). After the return-contract gate passes (classifier PROCEED), the orchestrator — NOT the agent — appends ONE line to the audited spec's §9 Log:
- YYYY-MM-DD: decision audit — <N> findings (crit=X high=Y med=Z); evidence=<dual_model|...>The severity counts (
crit=X high=Y med=Z) come from the agent's inline summary table (the inline report of the decision return), NOT from the 3-line evidence footer (which carries onlyevidence_class/evidence_blockers);evidence=is filled from the footer'sevidence_class.Report-only — no per-finding triage, no Phase 4 status mutation. Decision findings are transient by design (grill D3 — the single persistence trace is the §9 Log-append line above, not a findings doc). The Phase 3 step-3 per-finding decision banner (
fix/accept/defer/fix all) and the Phase 4 findings-doc status mutation (OPEN→FIXED / ACCEPTED / DEFERRED) do NOT apply for decision-mode returns — there is no findings doc to mutate. The user acts on decision findings by editing the audited spec or opening follow-ups, outside this skill's Phase 3/4 lifecycle (which ends at the inline presentation + the §9 Log-append above). The §Shadow & low-confidence findings.md sections and their Phase-3 banner footers (… — see <findings_path>#…) likewise do NOT apply — decision writes no findings doc, so any low-confidence decision findings are surfaced inline with the rest of the report rather than routed to a<findings_path>section.No publish. Decision findings are NEVER published to a PR: they cite KB paths (spec / workdoc / findings-doc lines) by nature, and publishing KB paths to a PR violates R8 public-output hygiene. The Phase 3
publishaction is unavailable for decision-mode returns.
Cross-auditor return-contract gate
Standalone /cross-audit runs the same return-contract recovery as the feature flow. After the cross-auditor returns (Phase 1-2 initial dispatch — callsite 5 — and Phase 5 re-audit re-spawn — callsite 6), the orchestrator:
- Captures the raw response atomically to
<kb>/repos/<project>/security/<audit_slug>-contract-violation-iter<N>-attempt<M>.raw.txtper the §3.5b-1 atomic-write protocol inskills/feature/SKILL.md. - Invokes the classifier —
invoke hooks/lib/check_dispatch_response.py --mode <spec|code|full> --raw-response-file <captured-.raw.txt-path> --audit-slug <slug> --iteration <N> --expected-claude-model claude-opus(plus--findings-path <path>and--expected-head <workspace-HEAD>for code/full mode, and--require-rules-loadedfor standalonesecurity/fullmodes only). The--projectflag is passed ONLY when KB-discovery resolution finds.ai-dev-team.*yml project: ai-dev-team— standalone callsites do not assumeai-dev-teamotherwise.--expected-head— file-backed modes ONLY. Forlogic/security/full(classifier--mode code|full) pass--expected-head=git rev-parse HEADof the workspace the audit ran in (worktree HEAD in materialized mode; caller-cwd HEAD in in-place mode). Spec/decision-mode standalone runs (--mode spec) NEVER pass--expected-headand never render the Phase 3 pin —audited_headis not part of the inline-footer contract and decision mode writes no findings doc, so passing the flag there would false-fireHEAD_ATTESTATION_MISSINGon every clean run (the deliberate asymmetry vs--expected-claude-model, which IS passed in spec/decision). Non-git in-place file-backed runs likewise SKIP--expected-headper the §3.2 emit carve-out (the pin was omitted at emit when the workspace HEAD was unresolvable — the non-git in-place path atskills/cross-audit/SKILL.md:192); with the flag absent the classifier computes nohead_gate.--require-rules-loaded— standalonesecurity/fullmodes ONLY (NARROWER than--expected-head). The R-rule cluster loader runs ONLY inmode ∈ {security, full}(notlogic), so pass--require-rules-loadedfor those two standalone modes only.logicNEVER passes it — the loader does not run in logic mode, so the flag would false-fireRULES_ATTESTATION_MISSINGon every clean logic audit.spec/decisionstandalone runs (--mode spec) never pass it either — the inline-footer channel carries norules_loadedkey. With the flag absent the classifier computes norules_gate. - Writes a sidecar JSON atomically at
<kb>/repos/<project>/security/<audit_slug>-contract-violation-iter<N>-attempt<M>.jsonAFTER classification — standalone mode has no spec frontmatter to write*_audit_evidenceinto, so the two-file pair (.raw.txt+ sidecar JSON) is the persistent record. The sidecar shape is exit-code aware — the orchestrator reads step 2's exit code first: on classifier exit 0/1 theclassifier_outputfield is the classifier's stdout JSON andclassifier_exitrecords0/1; on classifier exit 2 (crash — empty stdout, no JSON)classifier_outputisnull,classifier_exitis2, andclassifier_stderrcarries the classifier's stderr truncated to 1000 chars. Theraw_responsefield carries the raw response embedded inline when its byte count ≤ 65536 (64 KiB), ornullplus araw_response_pathreference otherwise (independent of the classifier exit code — the raw response is captured in step 1, before classification). On sidecar-write failure → capture-failure banner (the §3.5b-2c capture-failure banner inskills/feature/SKILL.md) and STOP. - Branches on the classifier exit code — the same four-way branch as the feature skills/feature/SKILL.md §3.5b-2 recovery algorithm (step 4), adapted for standalone mode (no spec frontmatter; the
.raw.txt+ sidecar JSON pair is the persistent record):- Exit
2(classifier crash — empty stdout, no JSON; the classifier's own failure) → the standalone classifier-crash banner below. This is a single-attempt diagnostic — it does NOT use the two-attempt §3.4d template, because an exit-2 crash on the initial dispatch produced no classifier JSON to populateattempt-1/attempt-2with. - Exit
0ANDpolicy_gate: null→ evaluate the model-attestation gate (model_gate, set when--expected-claude-model claude-opuswas passed AND the classification isCLEAN_*) BEFORE the Phase 1 findings read:model_gate: null→ evaluate the audited-HEAD gate (head_gate, see the exit-0 head-gate note below);head_gate: null→ evaluate the degraded-rules gate (rules_gate, see the exit-0 rules-gate note below) and PROCEED to the findings.md read (step 1 above) only when it too resolvesnull;model_gate: MODEL_ATTESTATION_MISSING→ ONE identical-params transport retry FIRST (sharing the §3.5b-2b retry budget; SKIP the retry if attempt2 is already consumed and go straight to the banner), and only if still MISSING/non-null after the retry → the standalone model-attestation gate banner below;model_gate: MODEL_DEGRADED→ the standalone model-attestation gate banner below immediately (no auto-retry — the user decides). (Whenpolicy_gate: STOP_AND_DISCUSSco-fires with a non-nullmodel_gate, see the co-fire mapping in the standalone project-policy gate banner below — the policy banner fires first.) - Exit
0ANDpolicy_gate: STOP_AND_DISCUSS(arises standalone when--project ai-dev-teamwas passed and the classification isCLEAN_SINGLE) → the standalone project-policy gate banner below. - Exit
1(any of the 10 violation classifications) → enter the §3.5b-2b retry-outcome matrix (one bounded TRANSPORT retry). If the retry recovers (CLEAN_DUAL, or consumer-projectCLEAN_SINGLE), re-evaluate the model-attestation gate on the recovered-clean retry's JSON (identically to the exit-0 branch above):model_gate: null→ then the audited-HEAD gate (head_gate, if--expected-headwas passed):head_gate: null→ then the degraded-rules gate (rules_gate, if--require-rules-loadedwas passed):rules_gate: null→ PROCEED; a non-nullrules_gate→ the standalone degraded-rules gate banner below (its Fix-environment option is a semantic iteration, independent of the spent transport budget — a transport retry cannot clear an environment condition, so a recovered-clean run re-attests the same degradation); a non-nullhead_gate→ the standalone audited-HEAD gate banner below (its Re-audit option is a semantic iteration, independent of the spent transport budget); a non-nullmodel_gate→ the standalone model-attestation gate banner below INSTEAD of PROCEEDing (the violation retry already consumed attempt2, so the shared transport budget is spent — the banner's Option 1 is "Retry from scratch" per its budget rule). If the retry is an unrecovered SAME-violation / DIFFERENT-violation, OR the retry's classifier itself crashes (classifier exit-2 on the retry — §3.5b-2b Matrix A's third terminal row), route to the §3.4d standalone terminal banner below. The retry's classifier-exit-2 outcome is NOT the same as an exit-2 on the INITIAL dispatch: an initial-dispatch crash produced no classifier JSON and uses the single-attempt classifier-crash banner above; a crash on the RETRY has an attempt-1 violation classification to present and routes to the two-attempt §3.4d banner.
- Exit
Exit-0 audited-HEAD gate (head_gate) — file-backed modes. Evaluated on classifier exit 0 AFTER policy_gate and model_gate resolve null/cleared — orchestrator consumption order is policy → model → head. The classifier computes all three gates INDEPENDENTLY, so a co-fire JSON can carry more than one non-null gate; the orchestrator acts on head_gate only once the prior gates are cleared. head_gate is set only when --expected-head was passed (file-backed modes) AND the classification is CLEAN_*: head_gate: null → PROCEED to the findings.md read; a non-null head_gate (HEAD_ATTESTATION_MISSING or HEAD_MISMATCH) → the standalone audited-HEAD gate banner below. head_gate NEVER consumes the shared §3.5b-2b transport-retry budget and never auto-retries — BOTH values route straight to the banner; its Re-audit option IS the retry (a semantic iteration that re-pins the new HEAD), not a transport attempt. Spec/decision standalone runs never pass --expected-head, so head_gate is always null there — no banner ever fires.
Exit-0 degraded-rules gate (rules_gate) — standalone security/full modes. Evaluated on classifier exit 0 AFTER policy_gate, model_gate, and head_gate resolve null/cleared — orchestrator consumption order is policy → model → head → rules. The classifier computes all four gates INDEPENDENTLY, so a co-fire JSON can carry more than one non-null gate; the orchestrator acts on rules_gate only once the prior gates are cleared. rules_gate is set only when --require-rules-loaded was passed (standalone security/full modes) AND the classification is CLEAN_*: rules_gate: null → PROCEED to the findings.md read; a non-null rules_gate (RULES_ATTESTATION_MISSING or RULES_NOT_LOADED) → the standalone degraded-rules gate banner below. rules_gate NEVER consumes the shared §3.5b-2b transport-retry budget and never auto-retries — a rules degradation is an environment condition (unreachable rules file / unset project_type) that an identical-params transport retry cannot clear, so BOTH values route straight to the banner; its Fix-environment option IS a semantic iteration, not a transport attempt. logic/spec/decision standalone runs never pass --require-rules-loaded, so rules_gate is always null there — no banner ever fires.
Standalone classifier-crash banner
The classifier (hooks/lib/check_dispatch_response.py) exited 2 — its own failure, distinct from a contract violation (we cannot tell whether the cross-auditor's response was valid). Single attempt, no classifier JSON:
⏸ AWAITING YOUR INPUT
hooks/lib/check_dispatch_response.py exited 2 (classifier crash) on the cross-audit return. Stderr:
<classifier stderr verbatim, truncated to 1000 chars>
Raw response captured to <raw-path-attempt-1> for manual inspection. Options:
- Re-run the classifier with
--debug(full traceback to stderr; you diagnose) — no auto-retry. - Manual review of the raw output — read
<raw-path-attempt-1>; if findings can be salvaged, paste manually into Phase 3 triage. - Re-run
/cross-auditfrom scratch (treats the crash as a transient transport failure).
Which option?
Standalone project-policy gate banner
The classifier returned CLEAN_SINGLE with policy_gate: STOP_AND_DISCUSS — Claude-only audit (Codex stalled), and --project ai-dev-team resolved, so project policy feedback_ai_dev_team_dual_model_cross_audit_always.md requires dual-model evidence. Standalone has no spec frontmatter to write, so the options are expressed in standalone terms:
⏸ AWAITING YOUR INPUT
Cross-audit returned CLEAN_SINGLE — Claude-only audit (Codex stalled with reason: <reason>). For the ai-dev-team project, policy requires dual-model cross-audit evidence.
Options:
- Re-spawn cross-auditor to retry Codex (may take 8-15 min; TRANSPORT retry). Re-spawn outcome governed by the §3.5b-2b Matrix B branch —
CLEAN_DUALrecovers, and the audit PROCEEDs only when the recovered JSON clears the full gate chain in order: the model-attestation gate returnsmodel_gate: null, then the audited-HEAD gate returnshead_gate: null(repairing this option's pre-existing head_gate omission — a recovered-clean run re-attests the same HEAD), then the degraded-rules gate returnsrules_gate: null(a transport retry cannot clear an environment condition, so a recovered-clean run re-attests the same rules degradation); any non-null gate routes to its standalone banner below instead — a non-nullmodel_gateto the standalone model-attestation gate banner (attempt2 consumed, so its Option 1 is "Retry from scratch"), a non-nullhead_gateto the standalone audited-HEAD gate banner, a non-nullrules_gateto the standalone degraded-rules gate banner (the latter two are semantic iterations, independent of the spent transport budget);CLEAN_SINGLEagain re-renders this banner; a violation routes to the §3.4d standalone terminal banner. - Accept single_model for this audit — proceed to Phase 3 triage with the Claude-only findings; the sidecar JSON records
CLEAN_SINGLEas the audit evidence. - Abandon this audit — no findings recorded; consider escalating the Codex outage.
Which option?
Co-fire with a non-null model_gate (the classifier returned CLEAN_SINGLE policy gate AND a model-attestation gate fired on the same JSON): the policy banner above fires FIRST, with one preamble line added — Note: model_gate=<value> also fired (attested <claimed>). The three policy options then map onto the model gate: Re-spawn cross-auditor → the recovered JSON re-evaluates BOTH gates (if the model gate then fires with attempt2 consumed → the model-gate banner fires directly per its budget rule); Accept single_model → the model-gate protocol fires on the SAME JSON before the Phase 1 findings read; Abandon this audit → the flow terminates and the model_gate value is reported in the abandon summary.
Standalone model-attestation gate banner
Reached on classifier exit 0 with policy_gate: null and a non-null model_gate (--expected-claude-model claude-opus was passed and the attested model is missing/degraded), evaluated BEFORE the Phase 1 findings read. Standalone has no spec frontmatter; the persistent record splits by WHEN the value is known (see below). Same 3 options as the feature §3.5b-2e banner, with the same BUDGET-state-conditional Option 1 — the discriminator is whether the shared transport attempt2 is consumed, NOT the gate value (applies identically to MODEL_DEGRADED and MODEL_ATTESTATION_MISSING; the MISSING path takes ONE transport retry with identical params first, sharing the §3.5b-2b retry budget). attempt2 UNCONSUMED → Option 1 = "Re-spawn cross-auditor" (consumes attempt2); attempt2 CONSUMED → Option 1 = "Retry from scratch" — a new audit run, NOT a third transport attempt (attempt3 forbidden). A budget-exhausted banner lists both capture paths in its summary.
⏸ AWAITING YOUR INPUT
Model attestation gate fired — model_gate=<value>. Cross-auditor attested <claimed>; the audit half is expected to run claude-opus*. iter=<N>.
[If attempt2 consumed:] Captures: <raw-path-attempt-1> + <sidecar-path-attempt-1>, <raw-path-attempt-2> + <sidecar-path-attempt-2>.
Options:
- Re-spawn cross-auditor (attempt2 unconsumed) / Retry from scratch (attempt2 consumed — a new audit run; attempt3 forbidden) — the outcome is re-evaluated by the same gate.
- Accept degraded run — the findings stay valid (the Opus half ran, not an absent half); proceed to Phase 3 triage.
- Abandon this audit — no findings recorded; review Fable quota / outage.
Which option?
Persistence (X12/X15 — no new sidecar field). The gate inputs (claude_model, model_gate) are already inside the sidecar JSON's embedded classifier_output — sealed at step-3 classification time under the atomic no-overwrite protocol; there is NO new sidecar field carrying the chosen action (such a write is unimplementable — the action is chosen in step 4, AFTER the sidecar is sealed; the re-write would raise PreExistingCaptureTarget). The POST-action record lands ONLY in the audit workdoc <audit_slug>-workdoc-iter<N>.md (orchestrator-written after the banner choice, no overwrite constraint):
- Model attestation: <claimed> vs <expected> → <gate> → action=<action>
Standalone audited-HEAD gate banner
Reached on classifier exit 0 with policy_gate: null, model_gate: null, and a non-null head_gate (--expected-head was passed for a file-backed run and the attested audited_head is missing/mismatched vs the audit-workspace HEAD), evaluated BEFORE the Phase 1 findings read. Same banner shape as the model-attestation gate banner — options re-audit / accept / stop — but head_gate NEVER consumes the transport-retry budget and never auto-retries: BOTH HEAD_ATTESTATION_MISSING and HEAD_MISMATCH route here directly, and Option 1 (Re-audit) is a semantic iteration (re-spawn per the Pass 2 parameter block — refreshed findings re-pin the new HEAD), NOT a transport attempt.
⏸ AWAITING YOUR INPUT
Audited-HEAD gate fired — head_gate=<value>. Findings pinned audited_head=<oid|absent>; the audit workspace HEAD is <expected-oid>. iter=<N>.
Options:
- Re-audit the delta — re-spawn cross-auditor per the Pass 2 parameter block (a semantic iteration; refreshed findings re-pin the new HEAD). NOT a transport retry.
- Accept — the findings stay valid for the attested HEAD; proceed to Phase 3 triage.
- Stop — no findings triaged; resolve the HEAD drift and re-run.
Which option?
Persistence (no new sidecar field — mirror of the model-gate rule). As with the model-attestation gate, the gate inputs (audited_head, head_gate) are already sealed inside the sidecar JSON's embedded classifier_output at step-3 classification time under the atomic no-overwrite protocol; there is NO new sidecar field carrying the chosen action and NO post-seal sidecar write (the action is chosen in step 4, AFTER the sidecar is sealed — a re-write would raise PreExistingCaptureTarget). The POST-action record lands ONLY in the audit workdoc <audit_slug>-workdoc-iter<N>.md (orchestrator-written after the banner choice, no overwrite constraint):
- Audited HEAD: <audited_head|absent> vs <expected> → <gate> → action=<action>
Standalone degraded-rules gate banner
Reached on classifier exit 0 with policy_gate: null, model_gate: null, head_gate: null, and a non-null rules_gate (--require-rules-loaded was passed for a standalone security/full run and the attested rules_loaded is missing/malformed or false), evaluated BEFORE the Phase 1 findings read. Same banner shape as the audited-HEAD gate banner — options fix-environment-and-re-audit / accept / stop — but rules_gate NEVER consumes the transport-retry budget and never auto-retries: both RULES_ATTESTATION_MISSING and RULES_NOT_LOADED route here directly, and Option 1 (Fix environment and re-audit) is a semantic iteration (re-spawn per the Pass 2 parameter block after the environment is fixed — refreshed findings re-attest), NOT a transport attempt (an identical-params transport retry hits the same broken environment).
⏸ AWAITING YOUR INPUT
Degraded-rules gate fired — rules_gate=<value>. Findings attested rules_loaded=<false|absent> (reason: <rules_reason|absent>); the R-rule cluster was not loaded for this security/full audit. iter=<N>.
Options:
- Fix environment and re-audit — restore
CLAUDE_PLUGIN_ROOT/ the plugin checkout (unreachable-file case), or setproject_typein.ai-dev-team.ymlor the spec frontmatter — or declareproject_type: nonefor a genuinely typeless project — then re-spawn cross-auditor per the Pass 2 parameter block (a semantic iteration; refreshed findings re-attest). NOT a transport retry. - Accept degraded run — the findings stay valid as focus-areas-only coverage; proceed to Phase 3 triage. Recorded in the audit workdoc.
- Stop — no findings triaged; resolve the rules-load degradation and re-run.
Which option?
Persistence (no new sidecar field — mirror of the head-gate rule). As with the audited-HEAD gate, the gate inputs (rules_loaded, rules_reason, rules_gate) are already sealed inside the sidecar JSON's embedded classifier_output at step-3 classification time under the atomic no-overwrite protocol; there is NO new sidecar field carrying the chosen action and NO post-seal sidecar write (the action is chosen in step 4, AFTER the sidecar is sealed — a re-write would raise PreExistingCaptureTarget). The POST-action record lands ONLY in the audit workdoc <audit_slug>-workdoc-iter<N>.md (orchestrator-written after the banner choice, no overwrite constraint):
- Rules loaded: <rules_loaded|absent> (reason=<rules_reason|absent>) → <gate> → action=<action>
§3.4d Standalone terminal banner
For the SAME-violation / DIFFERENT-violation / classifier-exit-2-on-retry branches of the §3.5b-2b retry-outcome matrix in standalone mode — i.e. an Exit-1 violation that the one bounded retry did NOT recover (no spec frontmatter — the .raw.txt + sidecar JSON pair is the persistent record). This is the standalone counterpart of the feature-mode §3.5b-2d terminal banner; both halves of the handshake terminate symmetrically. This banner is restricted to the unrecovered-after-retry case: it covers an Exit-2 classifier crash on the RETRY (attempt-1 still carries a violation classification to present), but an Exit-2 classifier crash on the INITIAL dispatch — which produced no attempt-1 classifier JSON — uses the standalone classifier-crash banner above, not this template.
⏸ AWAITING YOUR INPUT
Cross-audit contract violation — auto-respawn attempted, classifier output:
- attempt-1:
<initial-classification>—<initial-blocker>(captures:<raw-path-attempt-1>+<sidecar-path-attempt-1>) - attempt-2:
<retry-classification-or-crash>—<retry-blocker>(captures:<raw-path-attempt-2>+<sidecar-path-attempt-2>)
When attempt-2 is a classifier crash, <retry-classification-or-crash> reads classifier exit-2 (crash on retry) and <retry-blocker> carries the §3.5b-2b Matrix A blocker ['<initial-blocker>'; 'classifier crash on retry: <stderr-excerpt>'].
Options:
- Manual review of raw output — read the sidecar JSON(s); if findings can be salvaged from the raw response, paste manually into Phase 3 triage.
- Re-run
/cross-auditwith adjusted scope (smaller diff / different mode) to retry from scratch. - Abandon this audit — no findings recorded; consider whether the underlying truncation pattern needs a BACKLOG #51 incident update.
Which option?
Shadow & low-confidence sections (informational, non-banner)
Per spec 2026-04-21-cross-audit-probes-foundation §3.5a + §3.8, findings.md carries up to three sections — ## Summary, ## Shadow findings (informational), and ## Low-confidence LLM findings (advisory). Phase 3 renders each:
## Shadow findings (informational): probe findings withmode_at_emit: shadow(including merged probe+LLM findings whose probe half is in shadow per §3.5a routing cascade step 1). These are NOT surfaced in the decision banner — the user is not asked for a per-finding decision on them. They are rendered as read-only informational content in the findings doc.## Low-confidence LLM findings (advisory): pure-LLM findings (noprobe:*insources[]) withconfidence < 80(X11 resolution). These are also NOT surfaced in the decision banner; they live in findings.md for context and calibration review.- Both sections are omitted from findings.md entirely when empty (the renderer handles this; skill relays the count only when the section has entries).
Banner footer lines: the decision banner gains up to two footer lines, each added by the skill at Phase 3 presentation time:
- Shadow footer (emitted when the shadow section has ≥1 entry):
N shadow-mode findings — see <findings_path>#shadow-findings - Advisory footer (emitted when the advisory section has ≥1 entry):
M low-confidence LLM findings (advisory) — see <findings_path>#low-confidence-llm-findings-advisory
Both footers coexist when both sections are non-empty; each footer is omitted when its section is empty. Together these footers enforce §3.5a's miscalibration-risk mitigation (advisory entries stay visible even though they are suppressed from per-finding decisions).
⏸ AWAITING YOUR INPUT
Cross-audit finished. Decide per finding:
fix X1 X3— apply fixesaccept X2— known issue, intentionaldefer X4— address laterfix all— fix everythingpublish X1 X3— (PR mode only) post findings as GitHub PR review comments. Creates onegh apiPOST to/repos/<pr_repo>/pulls/<N>/reviewsthat bundles inline + body comments.publish alldefaults toOPEN/REOPENEDonly. Publish is orthogonal to the status state machine — it does NOT flip OPEN→FIXED. Seereferences/publish.mdfor the full recipe (force-push preflight,pr_filesrouting, failure matrix,published_torecord schema).
[If shadow section non-empty:] N shadow-mode findings — see <findings_path>#shadow-findings
[If advisory section non-empty:] M low-confidence LLM findings (advisory) — see <findings_path>#low-confidence-llm-findings-advisory
How should each finding be handled?
Phase 4: Fix (foreground, interactive)
- Update finding statuses in findings doc before writing any code:
fixtargets: OPEN|REOPENED → FIXEDaccepttargets: OPEN|REOPENED → ACCEPTEDdefertargets: OPEN|REOPENED → DEFERRED
- Apply code fixes for the
fixtargets - Run build/tests to verify
- Commit changes if user wants (small logical commits, no co-authored-by)
Phase 5: Re-Audit (background)
When user invokes /cross-audit <findings-doc-path>:
- Read the existing findings doc
- Extract two separate lists:
fixed_ids: IDs with statusFIXED(whether previously OPEN or REOPENED) — the auditor will verify these and flip to VERIFIED if confirmedaccepted_ids: IDs with statusACCEPTEDorDEFERRED— skip re-reporting, preserve their status (do NOT flip to FIXED)
- Launch cross-auditor with both lists:
previously_fixed: <fixed_ids>,accepted_ids: <accepted_ids>3a. Apply the §3.5b-2 recovery algorithm to the re-spawn's classifier output before step 4 — this is callsite 6 of the 6 §3.5b-2 recovery callsites (the standalone Phase 5 re-audit re-spawn). Per the §Cross-auditor return-contract gate subsection above: capture the raw return, invokehooks/lib/check_dispatch_response.py, write the sidecar JSON, and branch on the classifier exit code. Classifier output gates whether fix-verification in step 4 proceeds, or the §3.4d standalone terminal banner fires. - Agent verifies each fix (reads file:line, confirms fix is present) and looks for new issues
- Confirmed fixes → VERIFIED
- Absent or broken fixes → REOPENED
- On completion: findings doc updated, new workdoc-iter<N>.md created, present delta
Convergence
- COMPLETE when no CRITICAL or HIGH findings remain OPEN or REOPENED
- Typically 2-4 iterations
Audit findings handling
If the user's request references an audit-findings document (a file under <kb>/repos/<project>/security/, or mentions specific finding IDs like "X3", "H1", "починим N из findings", "fix audit item N"), do NOT dive into the code directly. First ask: "оформить как spec через /feature new или чинить напрямую?" — and wait for the answer. If the user chooses spec, invoke /feature new citing the finding. If they choose direct fix, proceed without the flow.
Rationale: the spec-driven flow adds a baseline red test and compliance checks that catch the exact class of bug where a findings doc claims "FIXED" but the code is not. Cheap one line fixes do not need this overhead, but the user should decide — not Claude.
Exception: lines starting with a decision keyword matching publish|fix|accept|defer (e.g. publish X1 X3, fix H2, accept L4, defer M1) inside an active /cross-audit Phase 3 loop are pass-through. Do NOT prompt "spec or direct fix?" in that case; the keyword-prefixed form is an in-flow decision, not a user-initiated finding reference.
Confirmation cadence
Once agreed to a direction, drive to completion without re-asking. See docs/confirmation-cadence.md.
Iteration Loop
/cross-audit <scope> → Background: parallel audit, save to KB
[user continues working...]
[results arrive]
user: "fix X1 X3, defer X2" → Foreground: apply fixes
/cross-audit <findings-doc-path> → Background: re-audit diff, update KB
[results arrive]
→ Status: COMPLETE
Adaptation by Project Type
Focus areas depend on detected project_type and audit mode — see agents/cross-auditor.md §Mode Focus Areas for the canonical per-mode list (logic / security / full / spec / decision). The SKILL orchestrator selects mode and project_type only; it does not dispatch the focus-areas list itself, so this file deliberately carries no subsections.