Setup

---
description: "Verify harness-config's readiness for this repository: the external CLI prerequisites its audit scripts need, jq (the JSON-parsing audit scripts) and curl (the plugin-drift check), and the tracked suppression record audit-pass reads at .claude/audit-pass.md, so the audit skills run instead of failing. Use when: 'set up harness-config', 'configure harness-config', 'is harness-config working', 'set up audit-pass suppressions', or an audit skill reported a missing prerequisite. Actions: check (read-only verification, default) | apply (resolve what check found). Re-runnable and safe."
argument-hint: "[check|apply]"
user-invocable: true
disable-model-invocation: true
shell: bash
---

## Pre-computed context

`check`'s tool probes ran at load time. Read these rows instead of re-issuing them; each shows the
tool's path when present, or `absent` when missing:

- `jq`: !`{ command -v jq 2>/dev/null || echo "absent"; }`
- `curl`: !`{ command -v curl 2>/dev/null || echo "absent"; }`
- `awk`: !`{ command -v awk 2>/dev/null || echo "absent"; }`
- `sort`: !`{ command -v sort 2>/dev/null || echo "absent"; }`

A row reading `[shell command execution disabled by policy]` carries no result: run that tool's
`command -v` probe via Bash instead.

## Purpose

Setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in
the marketplace repository): `check` inspects and reports, `apply` resolves. This plugin declares no
`userConfig`, and has two setup concerns:

- the external command-line tools its bundled scripts require, where `apply` is guidance-and-verify
  with no write path: it points at platform install instructions and never installs a system package;
- the **tracked consumer-project configuration** `audit-pass` reads, the suppression record at
  `.claude/audit-pass.md`, the one surface `apply` may write.

Action routing: no argument or `check` runs the check; `apply` runs the check first, then remediation.
Both are non-interactive, so never prompt when the action is given.

## `check` (read-only)

The bundled scripts are the single source of truth for what this plugin requires.

**Read it first.** Probe what it actually does, don't recite this file. Then read the
pre-computed tool rows, run the remaining probes via Bash, and report a PASS/FAIL/INFO table with one remediation line per FAIL. Do not modify anything.

The runtime scripts and their tools:

- `${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/check-plugin-drift.sh`: jq **and** curl
- `${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/check-structure.sh`, `check-hook-coverage.sh` and `fix-plugin-drift.sh`: jq
- `${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/scripts/inventory.sh`: jq
- `${CLAUDE_PLUGIN_ROOT}/skills/audit-permission-grants/scripts/permission-rule-check.sh`: jq plus awk and sort
- `${CLAUDE_PLUGIN_ROOT}/skills/audit-permission-state/scripts/*.sh`: jq (required; `permission-state.sh` exits 2 without it), awk and sort; `automode-block-lint.sh` and `automode-entry-diff.sh` add python3 for an optional lane
- `${CLAUDE_PLUGIN_ROOT}/skills/draft-auto-mode-rules/scripts/draft-automode-block.sh`: jq plus awk
- `${CLAUDE_PLUGIN_ROOT}/skills/audit-pass/scripts/run-state.sh` and `${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh`: jq (`run-state.sh` falls back to python3, then to a scan that announces itself)
- `${CLAUDE_PLUGIN_ROOT}/skills/audit-instructions/scripts/instruction-scan.sh`: grep only (POSIX; no jq)
- `${CLAUDE_PLUGIN_ROOT}/skills/audit-instructions/scripts/conflict-scan.sh`: awk **and** sort (no jq)

Only `conflict-scan.sh` and `permission-state.sh` probe for their tools; the rest call them with no
guard, so read each script's actual calls rather than trusting a single script's prerequisite block to
speak for the plugin.

1. **`jq`**, from the pre-computed `jq` row. FAIL if absent: the JSON-parsing scripts need it (`inventory.sh` degrades
   to an empty inventory; the others `exit 2` with an install remediation). Missing `jq` blocks every
   skill whose scripts parse JSON (`audit`, `audit-automation-gaps`, `audit-permission-grants`,
   `audit-permission-state`, `draft-auto-mode-rules`, and `audit-pass`'s run-state and retirement
   helpers); `audit-instructions` scans markdown and is unaffected.
2. **`curl`**, from the pre-computed `curl` row. FAIL if absent, but scoped: only the plugin-drift check
   (`check-plugin-drift.sh`) uses it and `exit 2`s without it. The rest of `audit` and every other
   skill still run; say so in the remediation line.
3. **`awk` and `sort`**, from the pre-computed `awk` and `sort` rows. FAIL if either is absent, and **not**
   scoped to one skill: `conflict-scan.sh` executes both and `exit 2`s naming the missing one, while
   `check-plugin-drift.sh` (both), `permission-rule-check.sh` (both), and `fix-plugin-drift.sh`
   (`sort`) reach them with no prerequisite check at all, so `audit` and `audit-permission-grants`
   fail mid-run on a bare `command not found` rather than on a named prerequisite. Say in the
   remediation line that this FAIL reaches three skills, not just `audit-instructions`. Report `awk`
   and `sort` by name rather than as one row, since a minimal shell can carry one and not the other.
4. **Bash shell**, INFO: the scripts are bash (arrays, `[[ ]]`, process substitution, `BASH_SOURCE`),
   run through Claude Code's Bash tool, which is the bash shell on every platform and Git Bash on native Windows.
   Report the resolved interpreter; FAIL only if no bash is resolvable.
5. **Network reachability**, INFO only: `audit`'s drift/freshness fetches read
   `raw.githubusercontent.com`, and a failed fetch degrades to SKIP rather than a setup failure. Do not
   fetch here; `check` performs no network call.

### The `audit-pass` suppression record

`audit-pass` reads a tracked suppression record layered per the marketplace's config-cascade
convention. Read the operative shape from
`${CLAUDE_PLUGIN_ROOT}/skills/audit-pass/reference/suppression.md` rather than inferring it. That
reference ships inside this plugin, so it resolves in an installed cache where a path out to the
marketplace's own docs does not. The cross-consumer key contract is the marketplace's published
**finding-suppression** convention, which is not a runtime dependency of this plugin. All layers
absent is a valid state (no suppressions), so report INFO, never FAIL, when none exists.

Anchor at the repo root (`${CLAUDE_PROJECT_DIR}`, else `git rev-parse --show-toplevel`), never a
CWD-relative read, which resolves a different (or missing) file depending on the subdirectory or
nested worktree the skill was invoked from, then report one row per layer. The same
tracked/ignored question has opposite correct answers per layer, so verify each on its own terms:

- **user-global** `~/.claude/audit-pass.md`: outside the worktree; no git command applies. INFO only.
- **team** `.claude/audit-pass.md`: must be tracked, probed as the pair:
  `git check-ignore -v` reports no match (a match is FAIL with the pattern) AND
  `git ls-files --error-unmatch` exits 0. Untracked while present is a hard STOP:
  teammates never receive the shared suppressions.
- **local overlay** `.claude/audit-pass.local.md`: must be gitignored and never staged. Staged or
  tracked is a FAIL: a personal deviation can reach team history.

Parse each present layer and report as malformed any entry missing **any** of its five required
keys: `check`, `claim`, `sites`, `reason`, `date`. Checking only `reason` and `date` would pass an
entry that `audit-pass` itself rejects, so readiness would report green on configuration that cannot
suppress anything. Report as malformed too an entry whose stored constituents do not hash to its own
key: the constituents are authoritative and the key is derived from them. A malformed entry does not
suppress, and a silent partial parse would turn a formatting slip into a lost check.

Report a **user-global or overlay entry for an id the team layer does not carry** as INFO
`personal-only, not applied`, naming promotion to the team layer as what makes it take effect. The
team layer is the only one that enacts a suppression, so a personal-only entry that looks live is a
finding the operator believes is accepted and is not.

## `apply` (idempotent)

Run `check`, then for each FAIL give the platform install instructions from the README Requirements.
This skill never installs system packages:

- **missing `jq`:** the platform's jq install (for example `winget install jqlang.jq`, `brew install
  jq`, or `apt-get install jq`); rerun `check` after.
- **missing `curl`:** the platform's curl install. Modern Windows and Git Bash already ship `curl`.
  Only the plugin-drift check needs it, so the rest of the plugin works meanwhile.
- **missing `awk` or `sort`:** both ship with every POSIX userland, so absence means the shell
  environment is minimal rather than that one package is missing. Git Bash and Windows `busybox`
  shims are where this shows up. Remediate by installing a full userland rather than the single tool:
  Git for Windows, which bundles both; the distribution's `gawk`/`mawk` and `coreutils` on Linux;
  `brew install gawk coreutils` on macOS. Report the two separately, since a minimal shell can carry
  one and not the other. Five skills depend on them (`audit`, `audit-permission-grants`,
  `audit-permission-state`, `draft-auto-mode-rules`, and `audit-instructions`), and only
  `conflict-scan.sh` and `permission-state.sh` `exit 2` cleanly, so do not offer the others as still
  working meanwhile.
- **no resolvable bash:** also not remediable by one package. The scripts use arrays, `[[ ]]`,
  process substitution, and `BASH_SOURCE`, so they need a real bash on `PATH`: Git for Windows on
  native Windows, the distribution's `bash` elsewhere. Nothing bundled runs until it resolves, so
  say that this FAIL blocks the plugin rather than offering a partial workaround.

The network row stays INFO and has no `apply` entry on purpose: a failed fetch degrades to SKIP by
design, so there is nothing to remediate.

After any install, re-run the relevant probe via Bash (`command -v <tool>`; the pre-computed rows
predate the install) and report its actual result. Never claim resolved
on the install command's exit code alone. Re-running `apply` once every probe passes changes nothing and
reports "already configured".

Then converge the one surface this plugin owns, conservatively:

- **No suppression record anywhere**: leave it that way and say so. Absent is valid; an empty
  scaffold is noise. Scaffold the team layer with the documented shape only on an explicit request.
- **Team layer present but untracked**: report the STOP and the exact `git add` the operator should
  run. Never stage on their behalf.
- **Overlay present but not ignored**: recommend the recursive `.claude/**/*.local.*` line and leave
  the `.gitignore` edit to the consumer.
- **Malformed or unrecognized entries**: report them and stop. Never rewrite, reorder, or drop an
  operator's suppression: an entry this skill cannot reconcile is a question for the operator, and a
  silent rewrite would hide the very finding the entry was suppressing.

Every write names the file and the exact change before making it, and preserves unrelated content.

## Gotchas

- **Never run a git command against the user-global layer.** `~/.claude/audit-pass.md` is outside the
  worktree, so `git check-ignore` and `git status` return a meaningless verdict there, or a
  confidently wrong one when the home directory is itself a git repository.
- **Missing config is not a failure.** All three suppression layers absent means no suppressions,
  which is the normal state for a repo that has never suppressed a finding. INFO, never FAIL.
- **Recommend the recursive gitignore line, and leave the edit to the consumer.** `.claude/**/*.local.*`
  covers flat, folder-form, and profiled overlays alike; the narrower `.claude/*.local.*` silently
  misses any nested overlay. The consumer's ignore file is their artifact; this skill never writes it.
- **An install command's exit code is not verification.** After any install, re-run the probe and
  report its actual result.

## What this skill does NOT do

- Run an audit; that is the plugin's audit and drafting skills (`/harness-config:audit`,
  `audit-automation-gaps`, `audit-instructions`, `audit-pass`, `audit-permission-grants`,
  `audit-permission-state`, `audit-prompting-postures`, `draft-auto-mode-rules`, `unhobble`).
- Write the plugin cache, Claude Code user settings, or `pluginConfigs`.
- Install system packages.
- Write the consumer's `.gitignore`, stage anything, or edit an operator's suppression entries.
- Download anything. `check` makes no network call; the audit skills' own doc/marketplace fetches are
  theirs, not setup's.