Claude Skill

audit

Full-sweep quality audit of .claude/ config — cross-references, permissions, inventory drift, model tiers, docs freshness. Scope tokens select what to audit; --upgrade applies docs-sourced improvements; --adversarial runs foundry:challenger + Codex adversarial review; --efficienc

LLM Mart · 0 points · 27 views 125 listing impressions 0 install-command copies
Download Borda-AI-Rig-plugins_cc_foundry_skills_audit-9516720.zip · 170 KB

Install

skills CLI npx skills add https://github.com/Borda/AI-Rig/tree/main/plugins/cc_foundry/skills/audit
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install borda-ai-rig@llmmart
Git git clone https://github.com/Borda/AI-Rig.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole borda/ai-rig collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Files (ai-rig)
  • modes
    • adversarial.md 16.2 KB
      Loading…
    • consolidate-guards.md 10.4 KB
      Loading…
    • consolidate.md 20.8 KB
      Loading…
    • efficiency-measured.md 4.6 KB
      Loading…
    • efficiency.md 34.4 KB
      Loading…
    • fix.md 22.8 KB
      Loading…
    • steps-4-5-7.md 28.7 KB
      Loading…
    • upgrade.md 16.3 KB
      Loading…
  • templates
    • audit-fix-prompt.md 16.1 KB
      Loading…
    • checks-agents.md 6.7 KB
      Loading…
    • checks-index.md 10.6 KB
      Loading…
    • checks-install.md 11.1 KB
      Loading…
    • checks-security.md 8.2 KB
      Loading…
    • checks-setup.md 13.3 KB
      Loading…
    • checks-shared.md 42.1 KB
      Loading…
    • checks-skills-bash.md 27.2 KB
      Loading…
    • checks-skills-contract.md 13.5 KB
      Loading…
    • checks-skills-crossplugin.md 17.3 KB
      Loading…
    • checks-skills-deadfiles.md 13.3 KB
      Loading…
    • checks-skills-duplication.md 11.7 KB
      Loading…
    • checks-skills-gaps.md 6.9 KB
      Loading…
    • checks-skills-sweep.md 9.6 KB
      Loading…
    • checks-skills.md 2.3 KB
      Loading…
    • consolidate-cluster-prompt.md 1.9 KB
      Loading…
    • consolidate-judge-prompt.md 4 KB
      Loading…
    • curator-prompt.md 3.3 KB
      Loading…
    • fix-prompt.md 1.4 KB
      Loading…
    • report-template.md 4.2 KB
      Loading…
  • severity-table.md 5.2 KB
    Loading…
  • SKILL.md 63.7 KB
    ---
    name: audit
    description: Full-sweep quality audit of .claude/ config — cross-references, permissions, model tiers, docs freshness. Scope tokens select what to audit; --upgrade applies docs-sourced improvements; --adversarial runs foundry:challenger + Codex adversarial review; --efficiency sweeps model tiers, token bloat, spawn patterns, boilerplate duplication, and bin/ extraction candidates (extraction performed separately via /foundry:distill executables); --consolidate proposes merging overlapping narrow rules into fewer broader ones and sharpening overlapping skill notes and agent clauses (advisory, edits nothing). Fix level chosen via conditional follow-up gate after report.
    argument-hint: '[<scope>...] [--local] [--upgrade | --adversarial | --efficiency | --consolidate] [--measured] [--fast] [--skip-gate] [--keep "<items>"]'
    disable-model-invocation: true
    allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, Skill, TaskCreate, TaskUpdate, TaskList, AskUserQuestion
    effort: high
    ---
    
    <objective>
    
    Full-sweep audit of `.claude/` config + all `plugins/*/` files: agents, skills, rules, settings.json, hooks. Spawns `foundry:curator` per-file, aggregates system-wide for cross-file issues — infinite loops, missing permissions, interop breaks. Reports findings; fix level from follow-up gate.
    
    </objective>
    
    <inputs>
    
    - **$ARGUMENTS**: optional — parse `--flags` first, then resolve remaining tokens as scope
    
      **Flags** (order independent, any combination with scope):
    
      - `--local` — audit source tree (`plugins/*/`) not project setup (`.claude/`); plugin-dev workflows where local edits not yet installed; sets `LOCAL_MODE=true`
      - `--upgrade` — fetch latest Claude Code docs, filter new features by genuine value, apply: **config** changes (apply + correctness check), **capability** changes (`--local` only: calibrate before → apply → calibrate after → accept if Δrecall ≥ 0 and ΔF1 ≥ 0 and at least one delta ≥ 0.05, the noise floor; without `--local` each is reported as skipped). Skip to **Mode: upgrade**. Among `--upgrade`, `--adversarial`, `--efficiency`, `--consolidate`: `--upgrade` and `--consolidate` each exclude all others; `--adversarial` and `--efficiency` may combine; error on all other mode combinations.
      - `--adversarial` (alias: `--challenge`) — adversarial review of all agents + skills in scope using `foundry:challenger` (Phase A) + Codex adversarial pass (Phase B); surfaces issues beyond standard per-file audit; see **Mode: adversarial**. Among `--upgrade`, `--adversarial`, `--efficiency`, `--consolidate`: `--upgrade` and `--consolidate` each exclude all others; `--adversarial` and `--efficiency` may combine; error on all other mode combinations.
      - `--efficiency` — cost and efficiency sweep: model tier validation, token bloat detection, unbounded spawn patterns, cross-file boilerplate duplication, missing model declarations, bin/ extraction candidates (Check 33), size against importance (E11). Generates prioritized cost-reduction plan with estimated savings. Detection only — run `/foundry:distill executables` to act on extraction candidates. Skip to **Mode: efficiency**. Mutually exclusive with `--upgrade` and `--consolidate`; combinable with `--adversarial`.
      - `--consolidate` — advisory consolidation sweep (Check 47): clusters rule, skill and agent sections that express one intent in different words, proposes fewer broader ones with an obligation map and an independent `foundry:challenger` review, and reports tokens saved per load class. Edits nothing; no fix gate. Skip to **Mode: consolidate**. Standalone — error if combined with `--upgrade`, `--adversarial` or `--efficiency`.
      - `--measured` — with `--efficiency` only: a question picks which of the projects whose sessions ran a flagged skill to measure, and the audit adds measured dollars from their transcripts (read-only, ids, counts and dollars only) and append the run to `.notes/efficiency/baselines.jsonl`, so a re-run prints the change against the first recorded baseline (Phase B3). Off by default: it reads transcripts and writes a ledger. Error without `--efficiency`
      - `--skip-gate` — suppress follow-up gate and record BREAKING acknowledgments without a question (for automation pipelines); does not authorize fixes or bypass fatal pre-flight errors
      - `--fast` — widen fan-out from `MAX_BATCHES` toward that phase's model-tier ceiling (`CAP_OPUS`/`CAP_SONNET`, see `<constants>` and claude-config.md §Parallel Spawn Ceilings), trading tokens for wall-clock. **Not free**: each extra agent costs ~120,851 tok of fixed overhead regardless of how little work it does. Curator-spawning phases (opus tier) have little headroom above `MAX_BATCHES=4` toward `CAP_OPUS=5`; Phase D's qa-specialist (sonnet tier) has more, toward `CAP_SONNET=8`. Use when latency matters more than cost; omit by default. Combinable with every other flag.
    
      **Legacy positional tokens** (`fix`, `upgrade`, `adversarial`, `challenge`, `ab`, `apply`, `fast`, `full`) — **hard error**: print migration hint and stop. Example: "`fix medium` removed — run `/foundry:audit` and pick fix level from gate, or pass `--upgrade` / `--adversarial` as flags."
    
      **Scope tokens** (positional, space-separated — resolve each token before Step 2):
    
      - No scope: full sweep — sources per `--local`: **without `--local`** covers `.claude/agents/`, `.claude/skills/`, `.claude/rules/`, hooks, settings — installed plugin cache (`~/.claude/plugins/cache/`) never scanned; audit plugin sources with `--local` in their checkout; **with `--local`** covers `plugins/*/agents/`, `plugins/*/skills/` + `.claude/` secondary
      - `agents` — restrict sweep to agent files only
      - `skills` — restrict sweep to skill files only
      - `rules` — restrict sweep to rule files only
      - `communication` — restrict sweep to communication governance files: `rules/communication.md`, `rules/quality-gates.md`, `TEAM_PROTOCOL.md`, `skills/_shared/file-handoff-protocol.md`
      - `setup` — restrict to system-config files: `settings.json`, `permissions-guide.md`, hooks, `MEMORY.md`, `README.md`, plugin integration, post-install user state (Checks 1–11, 30, I1, I2, I3); Step 3: `setup` SKILL.md only (one foundry:curator spawn); Checks I1–I3 read `~/.claude/` not `.claude/`
      - `plugin` — plugin integration only: codex plugin (Check 7), foundry plugin + init validation (Check 8, including 8g); Step 3: `setup` SKILL.md only (one foundry:curator spawn)
      - `plugins` — full audit of all plugins: per-file audit of every `plugins/*/agents/*.md` and `plugins/*/skills/*/SKILL.md` + integration checks (7, 8) per plugin
      - `plugins <name>` — same as `plugins` scoped to one plugin: resolve `plugins/<name>/` first, then `plugins/cc_<name>/`, then a plugin root whose manifest `name` matches (e.g. `bridge` → `plugins/bridge_cc-codex/`); collect its manifest-declared agents and skills + integration checks (e.g. `plugins foundry`, `plugins oss`, `plugins research`)
      - `<plugin-name>` — **tier 2 shorthand**: plugin name or directory name (e.g. `oss`, `foundry`, `research`, `develop`, `codemap-py`) resolved in the same order as `plugins <name>`; equivalent to that scope; no `plugins` prefix needed
      - `<agent-name>` — **tier 3**: name matches `.claude/agents/<name>.md` in setup mode, or `plugins/*/agents/<name>.md` in local mode with `.claude/agents/<name>.md` as fallback; runs agent checks only (Checks 14a, 14b, 15, 19, 20, 17, 12, 13, 25, 22, 26, 29); one file in Step 3
      - `<skill-name>` — **tier 3**: name matches `.claude/skills/<name>/SKILL.md` in setup mode, or `<skills-dir>/<name>/SKILL.md` under a plugin's `PLUGIN_LAYOUT:` root (from `plugin_layout.py`, Step 2) in local mode with `.claude/skills/<name>/SKILL.md` as fallback; runs skill checks only (Checks 14a, 14b, 15, 17, 12, 23, 22, 13, 24, 25, 26, 27, 28, 29); union all matches in the active source, never silently choose one plugin
      - Multiple scope tokens — space-separated, any combo; scope = union of resolved file sets: `agents skills`, `oss research`, `shepherd curator`, `review resolve`; check list = union (de-duplicated)
    
      **Scope token resolution** (each remaining token after flag-strip), in this order:
    
      - (1) reserved keywords (`agents`, `skills`, `rules`, `communication`, `setup`, `plugin`, `plugins`) → use as-is, resolving the name following `plugins` by tier 2
      - (2) matches `plugins/<token>/`, otherwise `plugins/cc_<token>/`, otherwise a plugin root with matching manifest `name` → tier 2, retaining the actual directory name
      - (3) matches agent file in the active source → tier 3 agent
      - (4) matches `<skills-dir>/<token>/SKILL.md` in the active source → tier 3 skill; union all matches in the active source, including same-named skills in different plugins
      - (5) no match → error and stop
    
      Resolution timing and source:
    
      - Pre-flight resolves tier 2 deterministically and infers local mode; resolve tier 3 before filtering Step 2's inventory.
      - With `LOCAL_MODE=false`, tier-3 lookup uses `.claude/agents/` and `.claude/skills/` only; with `LOCAL_MODE=true`, use Step 2's plugin layout discovery and project-local fallbacks.
    
      **Out-of-scope target** — any path or pasted content that is not an agent, skill, rule, hook, settings, plugin-manifest, `permissions-guide.md`, `MEMORY.md`, or plugin/project-configuration `README.md` file (e.g. a plain application `.py` script or unrelated project docs):
    
      - lead with `**! UNSUPPORTED — <target> is not .claude/ or plugin config**`
      - name the owner (`foundry:sw-engineer`/`foundry:qa-specialist` for code, `foundry:linting-expert` for lint/types, `foundry:doc-scribe` for docs)
      - report `Total: 0`, stop.
      - Never append best-effort review findings after the decline — findings printed under a decline still read as an audit result.
    
      **Valid combinations**: scope tokens + flags mix freely:
    
      - Examples: `foundry --local`, `foundry --adversarial`, `agents skills --local`, `oss research --adversarial`, `foundry --efficiency`, `plugins --efficiency`, `foundry --adversarial --efficiency`, `plugins --local --adversarial --efficiency`.
      - Among `--upgrade`, `--adversarial`, `--efficiency`, `--consolidate`: `--upgrade` and `--consolidate` each exclude all others; `--adversarial` and `--efficiency` may combine; error on all other mode combinations.
      - `--local` compatible with all.
      - When `--adversarial` and `--efficiency` both present: run adversarial Phases A–C then efficiency Phases A–C sequentially; merge findings; single conditional follow-up gate.
    
    </inputs>
    
    <constants>
    
    ```text
    BATCH_SIZE_MIN=5       # minimum files per batch; ensures curator gets sufficient context per spawn
    MAX_BATCHES=4          # total batch cap; EFFECTIVE_BATCH = max(BATCH_SIZE_MIN, ceil(total / MAX_BATCHES))
    ADVERSARIAL_BATCH_SIZE=2  # adversarial phases (A, A-prime) use smaller batches for deeper per-file attention
    AGENT_CALL_BUDGET=55   # target tool-calls per spawned agent; above ~60 agents stall mid-task without returning an envelope
    CAP_OPUS=5             # per claude-config.md §Parallel Spawn Ceilings — foundry:curator, foundry:challenger (opus tier)
    CAP_SONNET=8           # per claude-config.md §Parallel Spawn Ceilings — foundry:qa-specialist (Phase D) (sonnet tier)
    WAVE_STEP=5            # growth toward a tier's ceiling happens this much at a time, never a sudden jump to the cap
    ```
    
    <!-- Fan-out buys WALL-CLOCK, not tokens: ~120K tok fixed cost per agent spawned;
         agents past ~60 calls stall without returning an envelope. Default to the
         fewest batches keeping each agent near AGENT_CALL_BUDGET; --fast only when
         latency outweighs cost, and only up to that phase's own model-tier ceiling
         (CAP_OPUS/CAP_SONNET) — --fast has no headroom on opus-tier phases already
         at or near CAP_OPUS. When adversarial/efficiency phases stack onto Steps
         3-4, each tier's spawns wave toward its own ceiling WAVE_STEP at a time;
         different tiers draw from separate pools and may run concurrently. -->
    
    </constants>
    
    <compaction>
    
    - Key boundary 1: after Steps 3+4 fan-out (curator spawns + system-wide checks complete), before Step 5 aggregate.
    - Key boundary 2: after Step 5 aggregate (aggregate.md + summary.jsonl written), before Step 7 report.
    - Preserve at boundary 1: RUN_DIR, per-batch finding file paths, static-findings.jsonl path.
    - Preserve at boundary 2: RUN_DIR, aggregate.md path, summary.jsonl path, finding counts.
    
    </compaction>
    
    <workflow>
    
    **Task hygiene** — task tools may be deferred; load before first use: `ToolSearch(query="select:TaskList,TaskCreate,TaskUpdate,TaskGet", max_results=4)`.
    
    - Call `TaskList` first and triage each task it returns: `completed` if work clearly done, `deleted` if orphaned, keep `in_progress` only if genuinely continuing.
    - Never spend a turn on bookkeeping alone — every `TaskCreate`/`TaskUpdate` ships in the same response as the next substantive tool call.
      - One exception: `TaskUpdate(completed)` immediately before a long output block
        - Except report-print tasks complete immediately after their table is visible in the same response (`rules/task-lifecycle.md`).
    
    **Orchestration contract**: orchestrator is thin coordinator — issues Glob/Grep for inventory, spawns agents, reads JSON envelopes, aggregates findings. Must NOT read agent/skill/rule file bodies directly, except the communication files listed in Step 2. Other inline reads of non-template files = protocol violation; causes context overflow at scale.
    
    **Task tracking**: TaskCreate for each major phase; mark status live — every status change rides in the response carrying that phase's spawns or checks, never a turn of its own (zero bookkeeping-only turns; profiled runs averaged 9 per run):
    
    - Phase 1: setup + collect (Pre-flight + Steps 1–2) → in_progress on start, completed when file list ready
    - Phase 2: per-file audit (Step 3) → in_progress on agent launch, completed when all reports received
    - Phase 3: system-wide checks (Step 4) → in_progress on start, completed when all checks done
    - **Phases 2 and 3 launch together subject to the global spawn wave cap** — mark both in_progress same update; independent checks run concurrently, curator spawns use the ordered waves below
    - Phase 4: aggregate + fix (Steps 5–10) → in_progress, completed when fixes land; **do NOT mark completed until EITHER: (a) follow-up gate fires (Step 7) AND fixes applied or user chose skip; OR (b) `--skip-gate` active — gate suppressed, complete after Step 5 aggregation; OR (c) the conditional gate needs no question — complete after Step 7 saves the report and any already-authorized fixes finish; Step 5 aggregation alone does NOT complete Phase 4 in normal mode**
    - Phase 5: write final report (Step 11a) → in_progress, completed only once `$RUN_DIR/report.md` exists on disk — assembling the report in context does not complete this phase
    - Phase 6: print report header (Step 11b) → `blockedBy` Phase 5; mark completed immediately after the header table is visible, in the same response (task-lifecycle.md §Exception — report-print tasks)
    - On loop retry or scope change → new task; do not reuse completed task
    
    Surface progress at milestones: after system-wide checks ("✓ Checks 1-20 complete, N findings so far — spawning per-file audits"), after agent reports ("Agent reports received — N medium, N low findings"), before each fix batch ("Fixing N medium findings in parallel").
    
    <!-- ../../assets/images/audit-arch.svg diagrams the runs, gates and parallel fan-out. Documentation only, never loaded — update it in the same commit as any change to step order, gate placement, or agent fan-out. -->
    
    ## Pre-flight checks
    
    **Context budget**: full audit runs close to context limits. File-based handoff mandatory — every sub-agent writes full output to file, returns only compact JSON envelope. Sub-agent echoing findings to context = compaction before audit done.
    
    The helper resolves tier-2 aliases to their actual directory names in `scope=` and persists `LOCAL_MODE=true` before any mode dispatch, preserving flags and the quoted `--keep` value. Pass `$ARGUMENTS` unchanged.
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    python "$PLUGIN_ROOT/bin/audit_preflight.py" --arguments "$ARGUMENTS" || exit $?  # timeout: 20000
    : > "${TMPDIR:-/tmp}/audit-state-${CSID}/run-dir"
    : > "${TMPDIR:-/tmp}/audit-state-${CSID}/unscanned-plugins"
    ```
    
    Reset these sentinels only on a new invocation after successful pre-flight, never when resuming a phase or entering the second mode of a combined run.
    
    If `.claude/` is missing in setup mode, abort immediately; source scopes (`LOCAL_MODE=true`) and `--consolidate` need `plugins/`, not `.claude/`. Missing `jq` is warning — audit continues with Check 4 skipped (fatal for `--consolidate`).
    
    **`dispatch=mode:consolidate` printed → jump to `## Mode: consolidate` now and run no other step**: not Step 1, not Steps 1b–11, not the follow-up gate. Pre-flight already exits 1 on an unknown `--<token>` under `--consolidate`, so the unsupported-flag check below is not skipped by the jump.
    
    **State re-derivation across Bash blocks** — Claude Code spawns a fresh shell per Bash() call; variables set in pre-flight are LOST in Steps 2–11. Every Bash block in subsequent steps that uses `LOCAL_MODE` or `AUDIT_TPL` must re-read them from the persisted state files:
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    IFS= read -r AUDIT_TPL < "${TMPDIR:-/tmp}/audit-state-${CSID}/audit-tpl" 2>/dev/null || AUDIT_TPL=$(python "$PLUGIN_ROOT/bin/resolve_skill_subdir.py" audit templates $( [ "$LOCAL_MODE" = true ] && echo "--local" ))
    ```
    
    Place these three lines at the top of every Bash block in Steps 2–11 that references either variable.
    
    **Unsupported flag check** — after extracting supported flags (`--local`, `--upgrade`, `--adversarial`, `--efficiency`, `--consolidate`, `--measured`, `--fast`, `--skip-gate`, `--keep`, plus the `--challenge` alias of `--adversarial`), scan `$ARGUMENTS` for remaining `--<token>` tokens.
    
    - Found → invoke `AskUserQuestion` with question text `` ! Unknown flag(s): `--<token>`. Supported: `--local`, `--upgrade`, `--adversarial` (alias `--challenge`), `--efficiency`, `--consolidate`, `--measured`, `--fast`, `--skip-gate`, `--keep`. `` with two options:
      - (a) **Abort** (stop, re-invoke with correct flags)
      - (b) **Continue ignoring** (skip unknown flags, proceed)
    - On Abort: stop.
    
    ## Step 1: Validate pre-commit configuration (if configured)
    
    Skip entirely when pre-flight printed `dispatch=mode:consolidate`.
    
    ```bash
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    : > "${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-validate.txt"
    VALIDATION_EXIT=0
    printf 'validation_status=not-configured\n' > "${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-status.txt"
    if [ -f .pre-commit-config.yaml ]; then
        if command -v pre-commit >/dev/null 2>&1; then
            pre-commit validate-config .pre-commit-config.yaml > "${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-validate.txt" 2>&1 # timeout: 15000
            VALIDATION_EXIT=$?
            printf 'validation_status=%s\n' "$VALIDATION_EXIT" > "${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-status.txt"
        else
            printf 'validation_status=unavailable\n' > "${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-status.txt"
            printf '⚠ pre-commit unavailable — config validation skipped\n' > "${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-validate.txt"
            cat "${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-validate.txt"
        fi
    fi
    (exit "$VALIDATION_EXIT")
    ```
    
    This validates configuration only; do not execute auto-fixing hooks in a report-first sweep. The output is persisted in `${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-validate.txt` for the Step 5 consolidator. Report a nonzero validation result as a preflight finding, never cache it as success or claim files are clean. Step 1b supplies the deterministic structural checks. Run any source-changing hooks only as part of an authorized fix pass.
    
    If pre-commit not configured, skip silently.
    
    ## Step 1b: Layer-1 deterministic static pass
    
    Run the zero-LLM checker driver — the same deterministic checkers pre-commit enforces, aggregated into one reproducible findings file. These results are **authoritative** for their check classes: Steps 3–4 (LLM curator + judgment checks) must NOT re-derive them in prose — treat them as already-verified and spend model tokens only on judgment.
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    # timeout: 140000
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    STATIC_SCOPE=$( [ "$LOCAL_MODE" = true ] && echo plugins || echo .claude )
    python "$PLUGIN_ROOT/bin/audit_churn.py" --limit 300 --path plugins \
        > "${TMPDIR:-/tmp}/audit-state-${CSID}/churn-signal.json" 2>/dev/null  # timeout: 20000
    python "$PLUGIN_ROOT/bin/audit_static.py" --scan-dir "$STATIC_SCOPE" \
        --jsonl "${TMPDIR:-/tmp}/audit-state-${CSID}/static-findings.jsonl"  # timeout: 120000
    ```
    
    The block also runs the Step 1c churn pass (independent of the static pass; its output is only read in Steps 3 and 7).
    
    Covered deterministically by the driver (map to legacy check IDs — do NOT re-run these as prose):
    
    - **14a** tag symmetry
    - **14b** fence symmetry
    - **14c** README drift
    - **14d** mode-dispatch integrity
    - **14e** cross-plugin shared-file drift
    - **43** bash-variable persistence
    - **42** spawn-prompt `$VAR` (checks-skills-sweep.md)
    - **32d** orphaned bin/ scripts
    - **cli-flag-drift** SKILL.md flags vs argparse (`check_cli_flag_drift.py`, checks-index 42)
    - **R3** bin/computed-path reference integrity
    - **agent-plugin-root** defaulted bootstrap tokens in skills, agents, modes, templates and references, which the host and literal renderer never substitute (`check_agent_plugin_root.py`)
    
    Driver scope and merge:
    
    - Whole-repo checks (orphaned-bin, routing-links, shared-drift) always scope to `plugins/` regardless of `STATIC_SCOPE`; driver most complete in `--local` mode.
    - Step 5 merges `static-findings.jsonl` into aggregate.
    
    > **Layer-1 recall is benchmarked** — `tests/audit/test_audit_static.py` plants a known defect per scope-aware class and asserts the driver catches every one (100% mechanical recall), so this pass is trusted, not assumed.
    
    ## Step 1c: Layer-3 recurrence signal (attention weighting)
    
    Read a compact git-churn signal so audit attention follows *measured* churn — files and change-classes that keep being re-fixed are where the next defect most likely hides. Report the dominant recurring-fix class, not only point findings. The Step 1b block above already wrote it (`audit_churn.py`).
    
    Use `churn-signal.json` (`commit_types`, `top_churn`, `recurring_hint`) to: (1) prioritize per-file audits toward the most-churned files first in Step 3 batching; (2) add a **Recurring fix class** line to the Step 7 report naming the dominant theme (e.g. "version-bump churn — candidate for automation"). Zero-LLM, best-effort; skip silently if git is unavailable.
    
    ## Step 2: Collect all config files
    
    Enumerate everything in scope with built-in tools. Run all Glob calls in parallel.
    
    **Plugin layout resolution** (`--local`/`plugins` scope — multi-plugin source tree, mandatory before the fixed-pattern Globs below): don't assume every plugin uses `skills/`+`agents/` — a plugin can override the convention in its own manifest (e.g. `plugins/codemap-py/.claude-plugin/plugin.json` declares `"skills": "./claude-skills/"`, not `./skills/`; a fixed `*/skills/*/SKILL.md` glob silently never matches). Resolve each plugin's real dir names first:
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    [ "$LOCAL_MODE" != "true" ] || python "$PLUGIN_ROOT/bin/plugin_layout.py" plugins  # timeout: 5000
    ```
    
    For every `PLUGIN_LAYOUT:` line, use its `skills=`/`agents=` value (not hardcoded `skills`/`agents`) when Globbing that plugin below.
    
    - Example: `codemap-py` prints `skills=claude-skills`, so Glob `claude-skills/*/SKILL.md` under `plugins/codemap-py/`, not `skills/*/SKILL.md`.
    - Plugins with no manifest override resolve to the same `skills`/`agents` names the fixed patterns already assume — no behavior change.
    - **`codex-skills/`-style dirs for non-Claude-Code runtimes intentionally excluded** — only the manifest-declared path is authoritative; a heuristic `*skill*` match would also sweep in skill dirs for a different agent runtime, producing false positives against Claude Code's frontmatter schema.
    
    **Source selection by `LOCAL_MODE`**:
    
    - **`LOCAL_MODE=false` (default — user setup)**: `.claude/` primary; `plugins/` skipped. Installed/active config only.
    - **`LOCAL_MODE=true` (--local — project source)**: `plugins/` primary; `.claude/` secondary for rules/hooks/settings only.
    
    **Without `--local` (`LOCAL_MODE=false`)**:
    
    - **Agents**: Glob tool, pattern `agents/*.md`, path `.claude/`
    - **Skills**: Glob tool, pattern `skills/*/SKILL.md`, path `.claude/`
    - **Rules**: Glob tool, pattern `rules/*.md`, path `.claude/`
    - **Communication**: Read tool on `rules/communication.md`, `rules/quality-gates.md`, `TEAM_PROTOCOL.md`, `skills/_shared/file-handoff-protocol.md`
    - **Settings**: Read tool on `.claude/settings.json`
    - **Hooks**: Glob tool, pattern `hooks/*`, path `.claude/`
    
    **With `--local` (`LOCAL_MODE=true`)**:
    
    - **Agents (source — primary)**: for each `PLUGIN_LAYOUT:` line above, Glob tool pattern `<agents-dir>/*.md`, path `plugins/<plugin_name>/`
    - **Skills (source — primary)**: for each `PLUGIN_LAYOUT:` line above, Glob tool pattern `<skills-dir>/*/SKILL.md`, path `plugins/<plugin_name>/`
    - **Agents (project-local — secondary)**: Glob tool, pattern `agents/*.md`, path `.claude/`
    - **Skills (project-local — secondary)**: Glob tool, pattern `skills/*/SKILL.md`, path `.claude/`
    - **Rules / Settings / Hooks**: same as without `--local` (`.claude/`)
    
    Merge into single flat inventory. When `LOCAL_MODE=true` and same logical name in both `plugins/` and `.claude/`, prefer plugin source — skip `.claude/` duplicate. Record full paths — Step 3 cross-reference checks depend on current inventory. Always use the live disk scan. Stale inventory = primary cause of false-negative cross-reference findings.
    
    **Coverage reconciliation** (bare `plugins` scope, or default full sweep with `--local` — mandatory, not optional; **NOT** `plugins <name>` / tier-2 single-plugin scope, see narrowed check below):
    
    - A plugin contributing zero files to the inventory is invisible to every downstream check and must never pass as a silent clean sweep — same failure shape as a check that always no-ops: absence of findings misread as absence of problems.
    - Base set for this comparison is **every directory under `plugins/`**, not just ones that produced a `PLUGIN_LAYOUT:` line above — a plugin with a missing or malformed `plugin.json` contributes no `PLUGIN_LAYOUT:` line either, so comparing against that subset would make it invisible again:
    
    ```bash
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    mkdir -p "${TMPDIR:-/tmp}/audit-state-${CSID}"
    find plugins -mindepth 1 -maxdepth 1 -type d ! -name ".*" 2>/dev/null | sed 's|plugins/||' | sort > "${TMPDIR:-/tmp}/audit-state-${CSID}/all-plugins"
    ```
    
    After inventory built (model-context comparison — inventory already in context, not re-read from disk): compare every name in `all-plugins` against plugin names actually present in inventory. For each plugin with zero inventory entries, print and persist in the **same** bash call (re-export `CSID` here too — a later call starts a fresh shell and an unexported `$CSID` silently writes to the wrong sentinel path):
    
    ```bash
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    : > "${TMPDIR:-/tmp}/audit-state-${CSID}/unscanned-plugins"
    # for each zero-contribution plugin found above:
    printf "⚠ UNSCANNED: %s — no files matched scope globs\n" "<plugin>" | tee -a "${TMPDIR:-/tmp}/audit-state-${CSID}/unscanned-plugins"
    ```
    
    Step 11 reads this sentinel and surfaces it as a top-level report section — a zero-coverage plugin must never produce a green summary.
    
    **Narrowed check for `plugins <name>` / tier-2 single-plugin scope**: the all-plugins comparison above does NOT apply — every other plugin under `plugins/` is out of scope by design, and reporting it `UNSCANNED` would be a false positive on every such run. Instead, verify only that the one requested plugin contributed at least one file to the inventory; if it contributed zero, print/persist the same `⚠ UNSCANNED: <name> — no files matched scope globs` line for that single plugin only.
    
    **Default-scope coverage guard** (`LOCAL_MODE=false` — full sweep, `agents` or `skills` scope; mandatory): plugin installs never create `.claude/agents/` or `.claude/skills/` — installed agents and skills live in the plugin cache, which this scope does not read. Without this guard a project with no local agents or skills audits zero of them and reports clean. Reset the sentinel first, every run, so an earlier run's lines never leak into this report:
    
    ```bash
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    mkdir -p "${TMPDIR:-/tmp}/audit-state-${CSID}"
    : > "${TMPDIR:-/tmp}/audit-state-${CSID}/unscanned-plugins"
    ```
    
    Inventory holds zero agents and zero skills (`agents`/`skills` scope: zero files of that kind) → print and persist in one bash call:
    
    ```bash
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    _UNSCANNED="${TMPDIR:-/tmp}/audit-state-${CSID}/unscanned-plugins"
    printf "⚠ UNSCANNED: %s — no files matched scope globs\n" ".claude/ agents and skills (installed plugins are not audited; run --local in a plugin checkout)" >> "$_UNSCANNED"
    cat "$_UNSCANNED"
    ```
    
    **Scope filtering for Step 2** (applies on top of `LOCAL_MODE`):
    
    - `agents` scope — collect agents from active source (`.claude/agents/` or `plugins/*/agents/` per `LOCAL_MODE`); skip skills, rules, hooks
    - `skills` scope — collect skills from active source; skip agents, rules, hooks
    - `plugins` scope — always reads every plugin's manifest-declared agents and skills regardless of `LOCAL_MODE`; forces `LOCAL_MODE=true`
    - `plugins <name>` or `<plugin-name>` (tier 2) scope — use Pre-flight's resolved directory (`plugins/<name>/` first, then `plugins/cc_<name>/`, then a plugin root with matching manifest `name`) and collect only that root's manifest-declared agents and skills; Pre-flight forces `LOCAL_MODE=true` even without explicit `--local`
    - `<agent-name>` (tier 3) scope — single matching agent file; `LOCAL_MODE=false`: `.claude/agents/<name>.md`; `LOCAL_MODE=true`: `plugins/*/agents/<name>.md` first, then `.claude/agents/<name>.md`
    - `<skill-name>` (tier 3) scope — `LOCAL_MODE=false`: `.claude/skills/<name>/SKILL.md`; `LOCAL_MODE=true`: union every plugin's `<skills-dir>/<name>/SKILL.md` from `PLUGIN_LAYOUT:`, preferring plugin sources over `.claude/` duplicates; retain all same-named skills from different plugins
    - Multiple scope tokens — union of all resolved file sets
    - `setup`/`plugin` (bare) scope — no agent/skill collection from plugins; see setup/plugin notes below
    - Full sweep (no scope) — collect per `LOCAL_MODE` source selection above
    
    **Setup scope**: when `$SCOPE` is `setup`, also collect `${CLAUDE_PLUGIN_ROOT}/skills/setup/SKILL.md` for Step 3 foundry:curator spawn — only per-file spawn in setup scope. Checks I1–I3 (from `checks-install.md`) run in Step 4 against `~/.claude/` to validate post-install user state.
    
    **`plugins <name>` scope**: resolve `plugins/<name>/` first, then `plugins/cc_<name>/`, then a plugin root with matching manifest `name` — abort `! BREAKING: no plugin directory resolved for <name>` only if none match. Collect the resolved root's `<skills-dir>/setup/SKILL.md` when present plus all its manifest-declared agents/skills. **`plugins` (no name)**: iterate every subdir under `plugins/` — do not filter by literal `agents/`/`skills/` dir presence; PLUGIN_LAYOUT resolution above already covers plugins declaring a non-standard skills/agents path via their own manifest.
    
    ## Step 3: Per-file audit via foundry:curator
    
    **Context management** — accumulating full foundry:curator responses in context causes overflow before aggregation. Use file-based findings to keep main context lean.
    
    **Hard rule — no pre-reading**: Never call Read on agent/skill file before spawning foundry:curator. Spawned agent does the reading. Orchestrator reads only returned JSON envelope. Pre-reading 41 KB files into main context = defeats delegation + causes context overflow at scale.
    
    **Batching rule**: Always apply the grouping algorithm.
    
    - Compute `EFFECTIVE_BATCH = max(BATCH_SIZE_MIN, ceil(total_files / MAX_BATCHES))` before grouping — caps total batches at `MAX_BATCHES` while guaranteeing `BATCH_SIZE_MIN` files per batch for adequate curator context.
    - Group files into batches up to `EFFECTIVE_BATCH`. Never spawn one agent per file.
    - Total files ≤ `EFFECTIVE_BATCH` → one batch, all files.
    - `--fast` passed: recompute with `min(CAP_OPUS, <desired wider batch count>)` in place of `MAX_BATCHES` — Step 3 spawns `foundry:curator` (opus tier), so this phase can never exceed `CAP_OPUS`.
    
    **Spawn-count gate — apply before spawning anything**: every agent costs ~120,851 tok just to exist, ~73 tool-calls' worth of work (see `<constants>`). **Spawn fewest agents keeping each near `AGENT_CALL_BUDGET`**, not the most the cap allows. Two mandatory consequences:
    
    - **Gate on Layer-1 signal.** Step 1b already ran ~10 deterministic checkers at zero LLM cost, authoritative for their classes. A file with no Layer-1 finding and no judgment-bearing content (no `Agent()` dispatch, no cross-file contract, no model/tool declaration) does **not** need a curator — audit by static pass alone, say so in report. Spawning a curator to re-confirm a clean mechanical result is this skill's most common waste.
    - **State the trade in the report.** Record agents spawned + reason for that count. `--fast` widened fan-out → say it bought wall-clock at ~120K tok per extra agent — never present the fast path as free.
    
    **Budget line — include verbatim in every spawn prompt**: `If you approach your budget, stop cleanly and return the envelope with "partial": true and an accurate account of what you finished.` Measured: agents at ≤57 calls returned a clean envelope 5/5; agents at 87–142 calls stalled mid-task 3/5 and returned a progress fragment instead, forcing the orchestrator to reconstruct their state from disk.
    
    **Grouping algorithm**: (1) sort by plugin origin (`plugins/<name>/` prefix); (2) assign each plugin's files to batches, fill to `EFFECTIVE_BATCH` before next — keeps same-plugin files together; (3) remaining files (`.claude/` and mixed) fill open slots. Plugin-first, not strictly ordered — unconnected files assigned randomly to reach `EFFECTIVE_BATCH`.
    
    **Layer-2 — judgment by domain, not by file (plugin scope)**: scope `plugins`, `plugins <name>`, or tier-2 plugin name → override batch cap, group **all of a plugin's files into ONE holistic batch** (one `foundry:curator` per plugin), even past `EFFECTIVE_BATCH`.
    
    Whole-plugin context lets the curator catch cross-file breaks per-file batching misses — tool-grant mismatches (agent frontmatter vs skill dispatch), inter-skill contract splits (a constant clamped differently in two files), dead dispatch paths, version/description drift.
    
    Curator prompt for a holistic batch must say: "You have this plugin's ENTIRE file set — review it as one system: check every `Agent(subagent_type=...)` dispatch targets an agent whose frontmatter grants the needed tools, shared constants/contracts agree across files, no skill references a removed mode/file."
    
    Mechanical checks already done in Step 1b — spend this holistic pass on cross-file judgment only.
    
    (Very large plugins may still split, but keep agents + their dispatching skills in the same batch. This override deliberately accepts stall risk above the `AGENT_CALL_BUDGET` guidance in the Spawn-count gate above — the mitigation is the per-spawn budget line already required there ("stop cleanly, return `partial: true`"), not a hard file-count cap. A holistic batch that returns `partial: true` gets a second, narrower spawn covering only the files it didn't finish — never a full retry of the whole plugin.)
    
    For workflow-bearing targets, the default holistic pass checks declared inputs and outputs at handoffs for contract mismatches within the audit's existing scope and permissions. Note the curator-depth handoff check and any missing consumer context or unexecuted probes in the report; zero findings does not establish end-to-end safety. Deep producer/consumer tracing, counterexamples and challenges to design choices belong to `--adversarial` (`modes/adversarial.md`).
    
    **Scope-restricted runs**: fewer than `EFFECTIVE_BATCH` files → one batch, ALL files in scope (single foundry:curator spawn). Read only relevant template file(s) for active scope, not all 4.
    
    Set up the run directory once before spawning any agents:
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    RUN_DIR=$(python "$PLUGIN_ROOT/bin/make_run_dir.py" .reports/audit)  # timeout: 5000
    [ -z "$RUN_DIR" ] && { printf "! BREAKING: make_run_dir.py returned empty path — check Python availability and write permission on .reports/\n"; exit 1; }
    echo "Run dir: $RUN_DIR"
    echo "$RUN_DIR" > "${TMPDIR:-/tmp}/audit-state-${CSID}/run-dir"
    python "$PLUGIN_ROOT/bin/load_mode.py" audit templates curator-prompt.md $( [ "$LOCAL_MODE" = true ] && echo "--local" )  # timeout: 5000
    ```
    
    Spawn **foundry:curator** agents in batches of up to `EFFECTIVE_BATCH` (grouping algorithm above) — or one batch if scope ≤ `EFFECTIVE_BATCH`. Each spawn prompt must:
    
    1. Include the curator-prompt.md content loaded above
    2. Include the disk inventory from Step 2 (agent/skill list for cross-reference validation)
    3. End with:
    
    > "Write your FULL findings (all severity levels) to `<RUN_DIR>/<file-slug>.md` using the Write tool.
    >
    > - `<file-slug>` is a unique identifier combining plugin prefix and filename (e.g. `foundry-shepherd.md`, `oss-analyse-SKILL.md`, `develop-fix-SKILL.md`) to avoid collisions between cross-plugin files sharing the same basename.
    > - End your full findings file with a `## Confidence` block per quality-gates.md format (Score, Gaps, Refinements).
    > - Then return to the caller ONLY a compact JSON envelope on your final line — nothing else after it: `{\"status\":\"done\",\"file\":\"<RUN_DIR>/<file-slug>.md\",\"findings\":N,\"severity\":{\"security\":N,\"critical\":N,\"high\":N,\"medium\":N,\"low\":N},\"confidence\":0.N,\"summary\":\"<filename>: N critical, N high, N medium, N low\"}`"
    
    Replace `<RUN_DIR>` with actual path, `<file-slug>` with plugin-prefixed unique slug (e.g. `foundry-shepherd`, `oss-analyse-SKILL`, `develop-fix-SKILL`). Slug chars: `[a-zA-Z0-9-]` only — no slashes, spaces, or dots. Plugin dir names carry a `cc_` prefix on disk (`plugins/cc_foundry/`, `plugins/cc_oss/`) — strip it for the slug's plugin segment, matching the examples above (`foundry-shepherd`, never `cc_foundry-shepherd`).
    
    **Critical context discipline**: response body = JSON envelope, final line only. No other text, summaries, findings. All content to file.
    
    > Template file = canonical per-file audit criteria. Disk inventory and RUN_DIR path = runtime values injected per spawn.
    
    After spawns complete: short summaries in context; use to identify files with findings. Full content in run-dir files.
    
    **Health monitoring** (CLAUDE.md §6, `$_FS/agent-spawn-protocol.md` §Deadlines): in the response that spawns a curator wave, Write `$RUN_DIR/agent-watch-<wave>.tsv` — one row per batch, `<batch name>\t-\t900` (envelope-only — a batch writes several slug files) (Steps 4 docs-freshness `300`, Step 5b passes `600`, fix-mode agents `900`). End the turn — never `ScheduleWakeup`, `ListAgents`, `Monitor`, a probe, or a "waiting" line. On each completion or idle notification, before reading any output, run once:
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r RUN_DIR < "${TMPDIR:-/tmp}/audit-state-${CSID}/run-dir" 2>/dev/null || RUN_DIR=""
    [ -n "$RUN_DIR" ] || { echo "! BLOCKED — audit run-dir sentinel missing; cannot check agent deadlines"; exit 1; }
    python "$PLUGIN_ROOT/bin/agent_watch.py" --state-dir "$RUN_DIR"  # timeout: 5000
    ```
    
    `done`, or an envelope-only row whose notification carried its envelope → read it · notification arrived without its envelope or output (empty/missing) → mark `timed_out` now, surface with ⏱ in final report, never wait further · open rows without a notification → end the turn. Never omit timed-out agents; a ⏱ never answers or skips the follow-up gate or a `! BREAKING` acknowledgment.
    
    ## Steps 4–5b: System-wide checks, aggregate, low-confidence remediation
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    python "$PLUGIN_ROOT/bin/load_mode.py" audit modes steps-4-5-7.md $( [ "$LOCAL_MODE" = true ] && echo "--local" )  # timeout: 5000
    ```
    
    > loads: modes/steps-4-5-7.md (§Step 4–5b and §Step 7)
    
    Execute §Step 4–5b loaded above — system-wide checks (scope-dispatched), aggregate + classify findings, low-confidence remediation (conditional, skipped when no file scored \<0.80). Include `${TMPDIR:-/tmp}/audit-state-${CSID}/precommit-validate.txt` as a Step 5 consolidator input alongside the Step 3/4 reports and `static-findings.jsonl`; pass its literal path in the consolidator prompt and classify any validation failure as a preflight finding. State on disk in `summary.jsonl`, `$RUN_DIR`, `$AUDIT_TPL`. Returns here to Step 6.
    
    ## Step 6: Cross-validate critical findings
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    python "$PLUGIN_ROOT/bin/load_shared_doc.py" --optional foundry skills/_shared cross-validation-protocol.md  # timeout: 5000
    ```
    
    Protocol text printed above: follow it. A `⚠ WARNING` line instead = doc missing → skip cross-validation.
    
    **Skill-specific**: the verifier agent is always **foundry:curator**.
    
    ## Step 7: Report findings
    
    Execute §Step 7 of `steps-4-5-7.md` (loaded above in Steps 4–5b) — persists the full findings report, applies the conditional Follow-up gate below instead of an unconditional question, and defers printing the full report to the final reply after the answer (or no-question path); on fix pick or an already-authorized fix scope continues to Steps 8–10 (`modes/fix.md`); otherwise skip to Step 11.
    
    ## Steps 8–10: Fix dispatch, codex cross-file check, re-audit (mode: fix)
    
    Runs **only** when the user picked a fix option (a–c) from the Step 7 follow-up gate or already authorized a concrete fix scope as defined under Follow-up gate. In the latter case, use that granted scope as the dispatch input without another question; do not broaden it or infer decisions for NON_AUTO_FIXABLE items. Resolve the modes dir, load `fix.md`, then execute it inline — it carries Step 8 (delegate fixes to subagents), Step 9 (codex cross-file check), and Step 10 (re-audit + convergence loop), then returns here to Step 11:
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    python "$PLUGIN_ROOT/bin/load_mode.py" audit modes fix.md $( [ "$LOCAL_MODE" = true ] && echo "--local" )  # timeout: 5000
    ```
    
    > loads: modes/fix.md Execute Steps 8–10 loaded above inline (state on disk in `summary.jsonl`, `$RUN_DIR`, `$AUDIT_TPL`). On convergence (clean or 5-pass limit), continue to Step 11 below. If no fix option was picked and no fix scope was already authorized, skip directly to Step 11.
    
    ## Step 11: Final report
    
    <!-- loads: report-template.md -->
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    IFS= read -r RUN_DIR < "${TMPDIR:-/tmp}/audit-state-${CSID}/run-dir" 2>/dev/null || RUN_DIR=""
    python "$PLUGIN_ROOT/bin/load_mode.py" audit templates report-template.md $( [ "$LOCAL_MODE" = true ] && echo "--local" )  # timeout: 5000
    ```
    
    **Step 11a — assemble and persist** — assemble the complete audit report following the template and instructions loaded above, then **Write it to `$RUN_DIR/report.md`** using the Write tool. Set the template's `Path:` field to that same real path. This Write is mandatory, not optional: the terminal step below reads the header back from this file, and the report is the run's only durable artifact once the session ends. Skipping it leaves `Path:` pointing at a file that was never created.
    
    **Unscanned-plugin surfacing** (every scope with a Step 2 coverage check — `--local`/`plugins` reconciliation, tier-2 narrowed check, or default-scope coverage guard): before assembling, read `${TMPDIR:-/tmp}/audit-state-${CSID}/unscanned-plugins` (sentinel from Step 2). Non-empty → include an `### Unscanned Plugins` section in the report immediately after `### Files Audited`, listing every `⚠ UNSCANNED: <plugin>` line verbatim; this makes zero-coverage plugins visible in the durable artifact, not just the transient terminal output. Empty or missing → omit the section.
    
    **Step 11b — terminal output** — prepare this block for the final reply after the answer (or the no-question path), after the last tool call including the completion marker and cleanup below, except the report-print task completion update required immediately after the table in the same response.
    
    Per quality-gates.md universal rule, the final reply opens in this order:
    
    1. Read the `---` header block from the top of `$RUN_DIR/report.md` (all fields from opening `---` up to and including closing `---`) and render as a two-column Markdown table (`Field | Value`, one row per key, file order) as the FIRST content of that final reply — never print the raw `---`-delimited block.
    2. Then print `→ $RUN_DIR/report.md`.
    3. Print the full Step 7 Audit Report from `$RUN_DIR/audit-report.md` (heading, exact `Total: N`, every finding's `one_line`, rendered as normal Markdown).
    4. Print the executive summary.
    
    - The full findings report is printed once here, never before the question or in an option.
    - Omit the `╔═╗` Re:Anchor box (communication.md exempts quality-gates `---` report headers — the table IS the reply header).
    
    **Completion marker** — on successful completion, write `$RUN_DIR/result.jsonl` with one JSONL line summarising the run (severity totals, scope, pass count). On any abort/error path before completion, leave `result.jsonl` absent — the TTL cleanup hook (artifact-lifecycle.md) intentionally skips run directories without `result.jsonl`, preserving incomplete runs for post-mortem debugging. To force cleanup of a known-bad incomplete run, write `{"status":"incomplete","reason":"<one-line>"}` to `result.jsonl` so TTL can age it out.
    
    ```bash
    rm -f .temp/state/skill-contract.md  # clear contract — skill complete (compaction-contract.md §Lifecycle)  # timeout: 5000
    ```
    
    ## Mode: upgrade
    
    **Trigger**: `/foundry:audit --upgrade`
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    python "$PLUGIN_ROOT/bin/load_mode.py" audit modes upgrade.md $( [ "$LOCAL_MODE" = true ] && echo "--local" )  # timeout: 5000
    ```
    
    Execute the mode loaded above.
    
    ## Mode: adversarial (alias: --challenge)
    
    **Trigger**: `/foundry:audit [<scope>...] --adversarial`
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    python "$PLUGIN_ROOT/bin/load_mode.py" audit modes adversarial.md $( [ "$LOCAL_MODE" = true ] && echo "--local" )  # timeout: 5000
    ```
    
    Execute the mode loaded above.
    
    ## Mode: efficiency
    
    **Trigger**: `/foundry:audit [<scope>...] --efficiency`
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r LOCAL_MODE < "${TMPDIR:-/tmp}/audit-state-${CSID}/local-mode" 2>/dev/null || LOCAL_MODE="false"
    python "$PLUGIN_ROOT/bin/load_mode.py" audit modes efficiency.md $( [ "$LOCAL_MODE" = true ] && echo "--local" )  # timeout: 5000
    ```
    
    Execute the mode loaded above.
    
    ## Mode: consolidate
    
    **Trigger**: `/foundry:audit [<scope>...] --consolidate` — advisory, edits nothing, skips Step 1, Steps 1b–11 and the follow-up gate.
    
    ```bash
    PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    python "$PLUGIN_ROOT/bin/load_mode.py" audit modes consolidate.md --local  # timeout: 5000
    ```
    
    Execute the mode loaded above.
    
    ## Combined-run output isolation
    
    When `--adversarial` and `--efficiency` both run in the same invocation:
    
    - Mint the run directory once using Step 3's setup before either mode starts.
    - Pass that literal parent RUN_DIR explicitly in each mode's execution context, retain its run-dir sentinel, and skip any second run-directory setup; never invoke Pre-flight again between modes.
    - Each mode writes finding files to its own subdirectory to prevent overwrite — `$RUN_DIR/adversarial/` for adversarial output, `$RUN_DIR/efficiency/` for efficiency output.
    - After efficiency Phase C stages its rows, return to adversarial Phase C for the sole Step 5 canonical-writer dispatch; it reads both subdirs once and merges the stages.
    - Apply the conditional Follow-up gate once after canonical files exist, using merged finding counts.
    
    ## Bridge quota stop
    
    <!-- policy-sibling: plugins/cc_foundry/skills/audit/templates/audit-fix-prompt.md (**Bridge quota stop**: same rule for the audit-fix sub-agent, which never loads this file) -->
    
    Applies to every `bridge:*` call in this run: Step 5b, adversarial Phase B, fix Steps 8–9 and the audit-fix sub-agent. A peer out of credits fails every later call, and the bridge never retries one.
    
    - After a `blocked` or `timeout` bridge result, Read the incident file its `incident` field names and decide only from that file's `fault`: `quota-exhausted` → run the block below at once, then continue this run in-house.
    - A null `incident`, an unreadable incident file, or any other `fault` (`rate-limited`, `capacity`, `blocked`, …) keeps the current route unchanged. Never decide from verdict or blockers text: a model-authored `blocked` result can carry the same words with a null `incident`.
    - A `foundry:challenger` reply from the `modes/fix.md` gate or the audit-fix gate or R2 scan whose envelope carries `"codex_blocked": "quota"` is the same stop: its own Codex cross-check met that `fault`, so run the block below at once; the key absent keeps the current route.
    - Once `<RUN_DIR>/codex-blocked.txt` exists, no `bridge:*` call runs for the rest of the run: each status probe prints `CODEX_AVAILABLE=false` with status `codex-blocked:quota`, the fix fast path uses the per-file `haiku` agent, and every later `foundry:challenger` prompt carries `--no-codex`.
    - Report the skipped Codex work as `codex-blocked:quota`, never as a no-op, a failure or an absent bridge. The stop adds no question.
    
    ```bash
    export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
    IFS= read -r RUN_DIR < "${TMPDIR:-/tmp}/audit-state-${CSID}/run-dir" 2>/dev/null || RUN_DIR=""
    [ -n "$RUN_DIR" ] || { echo "! BLOCKED — audit run-dir sentinel missing; cannot record the quota stop"; exit 1; }
    printf '%s\n' codex-blocked:quota > "$RUN_DIR/codex-blocked.txt"; echo "codex-blocked:quota recorded in $RUN_DIR"
    ```
    
    ## Follow-up gate
    
    **Conditional gate**: fire only when a required decision or authorization is missing, such as a new fix scope; existing authorization continues within its granted scope (quality-gates.md §Follow-up precedence).
    
    - `--skip-gate` suppresses this gate for programmatic callers.
    - `Total: 0` → no fix options and no question; continue to Step 11.
    - Delivery is checked regardless: on `Stop`, `hooks/enforce-audit-header.js` keeps a turn going once per aggregate when it ends without the Step 7 findings report.
    - When a question is required, call `AskUserQuestion` — do NOT write options as plain text first. Map options directly into tool-call arguments.
    
    When user picks fix option (a–c): run Steps 8–10 inline via `modes/fix.md` (state on disk in `summary.jsonl`); no recursive `/foundry:audit` call.
    
    An already-authorized fix scope requires an explicit user instruction in this session naming a fix level, never inferred from findings or the invocation; NON_AUTO_FIXABLE items still ask through their owning gate. `Total > 0` with no `--skip-gate` and no such instruction → ask for the fix scope. When a concrete fix scope was already authorized and Total > 0, run Steps 8–10 with that scope as dispatch input instead of asking again; unresolved systemic decisions still require the owning gate. With `--skip-gate`, return the report without fix dispatch.
    
    **HARD RULE — Fixed option labels**: Use exactly the labels below verbatim. Do NOT rewrite, paraphrase, or substitute finding-specific alternatives. Finding context must NOT influence option labels. This rule has been violated repeatedly in past runs; enforce strictly.
    
    **Mandatory options (when a fix-scope question is required, never omit)**:
    
    - (a) label: `Fix auto-fixable (Recommended)` — auto-fix security, critical, high, medium, and low findings (skip NON_AUTO_FIXABLE systemic issues)
    - (c) label: `Fix ALL` — collect all NON_AUTO_FIXABLE decisions upfront (max 4 `AskUserQuestion` calls), then run one integrated fix pass covering auto-fixable + resolved systemic items + lows; most thorough option
    - (d) label: `Skip` — decline path; present in every layout, never replaced
    
    **Conditional options (include when condition met)**:
    
    - (b) label: `Fix SECURITY + CRITICAL + HIGH` — include only when security, critical, or high findings present; omit otherwise to stay within 4-option cap
    - `/foundry:distill executables` is never an option: `/foundry:distill` is `disable-model-invocation`, so a selected option could not run it. When `--efficiency` ran and `extract_count > 0` (HIGH or MEDIUM), print `/foundry:distill executables` (N HIGH, M MEDIUM candidates) as plain text in the Step 11 final report instead
    
    **Option slot budget** (`AskUserQuestion` hard cap = 4 options; "Other" always auto-appended as 5th free-text slot):
    
    - Security, critical or high findings present: (b) → (a) → (c) → (d) = 4 ✓
    
    - No sec/crit/high findings, but Total > 0: (c) → (a) → (d) = 3 ✓ — slot freed; do NOT fill with custom finding-specific option
    
    - question: "What next?" The first question's text carries the `Audit Report` headline, exact `Total: N`, severity counts and `→ $RUN_DIR/summary.jsonl`; include `→ $RUN_DIR/audit-report.md` for the saved full findings. Keep the question text to at most 6 plain lines (target 600 characters, hard cap 1,500), with no table, no pipe layout and no code fence.
    
    - Every option: label plus a one-line action description, no `preview`. Display `Fix auto-fixable (Recommended)` second in both layouts, preserving all labels and answer mapping. The full Step 7 findings report is printed once in the final reply after the answer, after the last tool call, below Step 11b's header table — never before the question (`steps-4-5-7.md` §Step 7).
    
    <!-- policy-sibling: plugins/cc_foundry/skills/audit/modes/steps-4-5-7.md (Step 7: same question-text cap, no preview, full findings report once in the final reply) -->
    
    `--consolidate` fires no gate: it is advisory, has no fix option, and prints its apply commands as plain text.
    
    After completing `--upgrade`, `--adversarial`, or `--efficiency`: apply the same conditional gate. For (d) Skip: remove the mode just run from the "for other modes" list. When `--adversarial --efficiency` combined: apply gate once after both complete with merged finding counts; remove both from (d) hint. Efficiency distill: the user runs the printed `/foundry:distill executables` (→ `foundry:sw-engineer` extraction), then `/foundry:audit --efficiency` re-run confirms savings.
    
    </workflow>
    
    <notes>
    
    - **`!` Breaking findings**: when skill or agent completely non-functional (check 7, broken cross-refs, invalid hook events), prefix finding with `!`, state impact + fix in one place — don't bury in table row. Surfaces as **`! BREAKING`** in bash output and as prominent callout in final report.
    
      **`! BREAKING` findings require user acknowledgment before audit proceeds past that check**: call `AskUserQuestion` — state what's broken and impact; user must explicitly confirm awareness before continuing.
    
      **Automation exception**: with `--skip-gate`, record each BREAKING finding with an `ack` value of `acknowledged-by-automation` in the Step 11 final report only; `AskUserQuestion` is not called for it. Preserve the BREAKING severity and impact; fatal pre-flight errors still abort and no fix is authorized by this acknowledgment.
    
      Without `--skip-gate`:
    
      - One question per distinct breaking finding; group only when logically one atomic issue.
      - Batch up to 4 questions into a single `AskUserQuestion` call (communication.md per-call cap) — N breaking findings become `ceil(N/4)` calls, never N.
      - Batching changes only call count; every finding still gets its own question and acknowledgment.
      - Prose acknowledgment in response body does NOT count — `AskUserQuestion` mandatory.
    
    - **settings.json is hands-off**: missing permissions always reported, never auto-edited — structural JSON edits risk breaking Claude Code config loading
    
    - **Dead loops need human judgment**: cycle in follow-up chains may be intentional (e.g. refactor → review → fix → refactor) — flag +

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.