code-auditor-mcp 3.5.0 → 3.7.0

package/plugin/scripts/hook-audit.sh

@@ -5,10 +5,15 @@
 # and runs `code-audit changed --stdin --json` against it.
 #
 # Exit codes:
-#   0 — all clear or degraded (binary not found, no index, no gating findings)
-#   2 — a new gating-rule finding was introduced (Claude Code feeds stdout back)
+#   0 — clean pass
+#   2 — a gating finding was introduced (Claude Code feeds stdout back)
+#   1 — the hook itself broke (binary missing, version mismatch, CLI error) —
+#       reported loudly, never a silent no-op.
 set -euo pipefail
 
+# Shared resolver + compatibility pinning (see hook-common.sh).
+. "${CLAUDE_PLUGIN_ROOT}/scripts/hook-common.sh"
+
 # Read event JSON from stdin
 event="$(cat)"
 
@@ -43,46 +48,31 @@ if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -n "${file}" ]; then
   esac
 fi
 
-# Resolve the code-audit binary: project-local → PATH → npx auto-install
-resolve_code_audit() {
-  # 1. Project-local install (plugin project's own node_modules)
-  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -x "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit" ]; then
-    echo "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit"
-    return
-  fi
-
-  # 2. Global install or PATH
-  if command -v code-audit &>/dev/null; then
-    echo "code-audit"
-    return
-  fi
-
-  # 3. npx auto-install (first use downloads the package; subsequent runs use the npx cache)
-  echo "npx -y -p code-auditor-mcp@^3.0.0 code-audit"
-}
 CODE_AUDIT_BIN="$(resolve_code_audit)"
 
-# Run diff-scoped audit on the changed file
-# stdout/stderr are fed back to the agent by Claude Code
+# Pin the plugin to a compatible CLI version — fail loudly on mismatch.
+assert_compatible "${CODE_AUDIT_BIN}" || exit 1
+
+# Run diff-scoped audit on the changed file. stdout/stderr feed back to the agent.
 set +e
 if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
-	  echo "${file}" | ${CODE_AUDIT_BIN} changed --stdin --json -p "${CLAUDE_PROJECT_DIR}"
-	else
-	  echo "${file}" | ${CODE_AUDIT_BIN} changed --stdin --json
-	fi
+  echo "${file}" | ${CODE_AUDIT_BIN} changed --stdin --json -p "${CLAUDE_PROJECT_DIR}"
+else
+  echo "${file}" | ${CODE_AUDIT_BIN} changed --stdin --json
+fi
 exit_code=$?
 set -e
 
-# Exit code 2 = binary gate triggered (a new gating-rule finding)
-# Let it propagate so Claude Code feeds the finding back to the agent
+# Exit 2 = a finding blocked the edit; propagate so Claude Code feeds it back.
 if [ ${exit_code} -eq 2 ]; then
   exit 2
 fi
 
-# Non-zero exit: npx auto-install failed, network issue, unsupported platform, etc.
-# Degrade gracefully — never wedge the agent loop.
+# Any other non-zero exit is the hook breaking, not a clean pass. Report loudly
+# and fail — a silent no-op here is exactly the failure mode this guards.
 if [ ${exit_code} -ne 0 ]; then
-  echo "[code-auditor] code-audit could not run (exit ${exit_code}). If npx auto-install failed, check your network or install manually: npm install code-auditor-mcp" >&2
+  echo "[code-auditor] HOOK BROKEN: code-audit exited ${exit_code} (neither clean nor a finding). Fix the install — do not treat this as a clean pass." >&2
+  exit 1
 fi
 
 exit 0

package/plugin/scripts/hook-common.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Shared helpers for the code-auditor PostToolUse hooks.
+#
+# Sourced by hook-audit.sh and hook-self-audit.sh. CLAUDE_PLUGIN_ROOT is
+# guaranteed set before either hook runs (the hooks.json guard exits 1 when it
+# is unset), so resolving the plugin's own bundled CLI is always possible here.
+#
+# Two rules enforced here are the fix for "the hook died quietly" (three times:
+# unset CLAUDE_PLUGIN_ROOT, a stale global binary, a removed CLI flag):
+#   1. always prefer the plugin's bundled CLI so a stale global/project binary
+#      can never drive the hook, and
+#   2. a non-zero CLI exit that is NOT a finding (2) is a broken hook and must
+#      fail loudly, never degrade to a silent no-op.
+#
+# The sourcing hook runs with `set -euo pipefail`.
+
+# resolve_code_audit — emit the CLI invocation to use.
+#
+# 1. The plugin's bundled CLI (dist/cli.js ships in the same npm package, so it
+#    is always the exact version this plugin was built against).
+# 2. Project-local install (consumer project's own node_modules).
+# 3. Global install / PATH.
+# 4. npx auto-install (only if nothing else resolves).
+resolve_code_audit() {
+  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js" ]; then
+    echo "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js"
+    return
+  fi
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -x "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit" ]; then
+    echo "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit"
+    return
+  fi
+  if command -v code-audit &>/dev/null; then
+    echo "code-audit"
+    return
+  fi
+  echo "npx -y -p code-auditor-mcp@^3.0.0 code-audit"
+}
+
+# plugin_version — the version this plugin declares in its manifest, or ''.
+plugin_version() {
+  node -e "try{process.stdout.write(JSON.parse(require('fs').readFileSync(process.env.CLAUDE_PLUGIN_ROOT+'/.claude-plugin/plugin.json','utf8')).version||'')}catch(e){process.stdout.write('')}" 2>/dev/null
+}
+
+# assert_compatible <bin> — pin the plugin to a compatible CLI.
+#
+# The bundled CLI always matches (same package), so it needs no check. Any
+# fallback path can drift — a stale global, a project-local pin, or a wider npx
+# range — and a 3.4.0 plugin silently driving a 3.5.0 CLI is exactly the
+# failure this guards. Print a loud error and return 1 on a detected mismatch.
+assert_compatible() {
+  local bin="$1" pv cv
+  case "${bin}" in
+    "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js") return 0 ;;   # pinned by construction
+  esac
+  pv="$(plugin_version)"
+  cv="$($bin --version 2>/dev/null || true)"
+  if [ -n "${pv}" ] && [ -n "${cv}" ] && [ "${pv}" != "${cv}" ]; then
+    echo "[code-auditor] version mismatch: plugin ${pv} vs CLI ${cv} — pin the CLI to the plugin version" >&2
+    return 1
+  fi
+  return 0
+}

package/plugin/scripts/hook-self-audit.sh

@@ -4,15 +4,24 @@
 #
 # Reads the PostToolUse event JSON from stdin, extracts the edited file path,
 # and — only when that file is production source in the self-audit scope — runs
-# `code-audit self-audit --stdin --json` against it. Exit code 2 blocks the edit
-# and feeds the finding JSON back to the agent.
+# `code-audit self-audit` against it. Exit code 2 blocks the edit and feeds the
+# finding JSON back to the agent.
 #
 # This hook is a no-op for every edit outside the self-audit scope (consumer
 # projects, tests, fixtures, and the declarative ruleRegistry table), so it adds
 # no latency to ordinary edits. It runs *in addition to* hook-audit.sh, whose
 # diff-gate enforces invariant rules on every edit.
+#
+# Exit codes:
+#   0 — clean pass or out of scope
+#   2 — a blocking self-audit finding (Claude Code feeds stdout back)
+#   1 — the hook itself broke (binary missing, version mismatch, CLI error) —
+#       reported loudly, never a silent no-op.
 set -euo pipefail
 
+# Shared resolver + compatibility pinning (see hook-common.sh).
+. "${CLAUDE_PLUGIN_ROOT}/scripts/hook-common.sh"
+
 # Read event JSON from stdin
 event="$(cat)"
 
@@ -60,33 +69,12 @@ case "${file_abs}" in
   *"__tests__"*|*".test."*|*".spec."*|*"fixtures"*|*"ruleRegistry.ts"*) exit 0 ;;
 esac
 
-# Resolve the code-audit binary. The `self-audit` command is new in 3.5.0, so a
-# stale PATH/global binary would silently lack it — prefer the plugin's own
-# bundled CLI first (guaranteed to be the version that ships with this hook),
-# then fall back to project-local → PATH → npx auto-install.
-resolve_code_audit() {
-  # 1. The plugin's own bundled CLI (ships alongside this script in the package;
-  #    dist/cli.js is the `code-audit` bin target, so npm marks it executable).
-  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js" ]; then
-    echo "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js"
-    return
-  fi
-  # 2. Project-local install (consumer project's own node_modules).
-  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -x "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit" ]; then
-    echo "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit"
-    return
-  fi
-  # 3. Global install or PATH.
-  if command -v code-audit &>/dev/null; then
-    echo "code-audit"
-    return
-  fi
-  # 4. npx auto-install (first use downloads the package; subsequent runs use the npx cache).
-  echo "npx -y -p code-auditor-mcp@^3.0.0 code-audit"
-}
 CODE_AUDIT_BIN="$(resolve_code_audit)"
 
-# Run the self-audit on the edited file. stdout/stderr are fed back to the agent.
+# Pin the plugin to a compatible CLI version — fail loudly on mismatch.
+assert_compatible "${CODE_AUDIT_BIN}" || exit 1
+
+# Run the self-audit on the edited file. stdout/stderr feed back to the agent.
 set +e
 if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
   echo "${file_abs}" | ${CODE_AUDIT_BIN} self-audit --stdin --json -p "${CLAUDE_PROJECT_DIR}"
@@ -96,12 +84,16 @@ fi
 exit_code=$?
 set -e
 
-# Exit code 2 = a blocking self-audit finding; let it propagate so Claude Code
-# feeds the finding back to the agent.
+# Exit 2 = a blocking self-audit finding; propagate so Claude Code feeds it back.
 if [ ${exit_code} -eq 2 ]; then
   exit 2
 fi
 
-# Non-zero exit (npx auto-install failure, network issue, etc.) degrades
-# gracefully — never wedge the agent loop.
+# Any other non-zero exit is the hook breaking, not a clean pass. Report loudly
+# and fail — a silent no-op here is exactly the failure mode this guards.
+if [ ${exit_code} -ne 0 ]; then
+  echo "[code-auditor] HOOK BROKEN: self-audit exited ${exit_code} (neither clean nor a finding). Fix the install — do not treat this as a clean pass." >&2
+  exit 1
+fi
+
 exit 0

package/plugin/skills/code-auditor/SKILL-RULE-KINDS.md

@@ -178,8 +178,10 @@ Require designated CSS properties to reference a design token instead of a raw v
 
 Severity ranks how urgent a finding is to fix. It never decides whether a
 finding is real, and it never licenses leaving one unresolved. Whether an edit
-is *blocked* is a separate axis: the edit hook gates on invariant rules that
-declare `gating: true` (a binary, per-rule flag), not on severity.
+is *blocked* is decided by severity: the edit hook blocks on any finding at a
+blocking severity (`critical` and `warning` by default, configurable via
+`gateSeverities` in `.codeauditor.json`), from any rule — there is no per-rule
+opt-in.
 
 | Severity | What it means |
 |----------|---------------|

package/plugin/skills/code-auditor/SKILL.md

@@ -5,11 +5,19 @@ description: Audit code quality, search the codebase semantically, enforce invar
 
 # Code Auditor Skill
 
-> **Version 3.4.8** • Run `code-audit --version` to check your installed version.
+> **Version 3.7.0** • Run `code-audit --version` to check your installed version.
 > If versions differ, the CLI is authoritative — use `code-audit <command> --help` to see what your install actually supports.
 
 You have the `code-audit` CLI available. It indexes every function, component, and struct in the codebase for semantic search and invariant enforcement. Use these commands instead of raw grep/find whenever possible.
 
+## The diagnostic frame
+
+`code-audit` is a diagnostic instrument, not a judge. Three terms carry that:
+
+- **Reading** — one rule observation (a "finding" in the JSON). The audit *takes* readings; it does not issue verdicts.
+- **Coverage panel** — the report leads with what was measured (which rules fired, which were clean, which were not applicable), so a zero-reading run is not mistaken for a clean tree.
+- **Triage** — severity is the order to act (`critical` → `warning` → `suggestion`), not a truth score. A suggestion reading is as real as a critical one; it is just lower in the queue.
+
 ## When to use which command
 
 ### `code-audit search` — find code by meaning, not just text
@@ -43,20 +51,20 @@ code-audit changed --json                            # Diff-scoped audit (hook c
 
 Use `code-audit changed` after edits to confirm you haven't introduced violations. If the hook is active it already runs `code-audit changed` automatically on Write/Edit — pay attention to its output.
 
-**Every finding is a defect to resolve, not a suggestion to weigh.** After a full audit, work the violations in severity order — criticals first, then warnings, then suggestions — and fix them all. Severity ranks urgency, never whether a finding is real; there is no "noise" tier. Documentation findings (missing JSDoc) are maintainability defects, not stylistic niceties. If you choose not to fix one, record why before moving on — never silently dismiss it.
+**Every reading is a measurement, not a verdict.** The audit is a diagnostic instrument: it reports what it measured (the coverage panel) and takes one reading per rule violation. Work readings in triage order — critical first, then warning, then suggestion — and resolve them all. Severity is triage, the order to act, never a judgment on whether a reading is real; there is no "noise" tier. Documentation readings (missing JSDoc) are maintainability gaps, not stylistic niceties. If you choose not to resolve one, record why before moving on — never silently dismiss it.
 
-Expected output: JSON violation list (with `--json`) or colored terminal summary. The full `audit` command exits non-zero when violations at or above `--fail-on` severity exist; the diff-scoped `changed` hook gates on per-rule `gating: true` flags, not severity.
+Expected output: JSON violation list (with `--json`) or colored terminal summary. The full `audit` command exits non-zero when violations at or above `--fail-on` severity exist; the `changed` hook blocks on any reading at a blocking severity — `critical` and `warning` by default, configurable via `gateSeverities` in `.codeauditor.json` — from any rule, and enforcement is not diff-scoped (a pre-existing reading in the audited file blocks exactly like a new one).
 
 ### `code-audit next-file` — fix violations one file at a time
 
 ```bash
-code-audit next-file --path .        # Highest-priority file + all its findings
+code-audit next-file --path .        # Highest-priority file + all its readings
 code-audit next-file --path . --json # Machine-readable
 ```
 
-This is the refactoring loop. `next-file` audits the project and returns the single highest-priority file — ranked by highest-severity finding, then total finding count — with every finding on it, ordered critical → warning → suggestion. Fix that file, then run it again: a still-broken file comes back, otherwise the next-worst file surfaces. `{done:true}` means the tree is clean.
+This is the refactoring loop. `next-file` audits the project and returns the single highest-priority file — ranked by highest-severity reading, then total reading count — with every reading on it, ordered critical → warning → suggestion. Fix that file, then run it again: a still-broken file comes back, otherwise the next-worst file surfaces. `{done:true}` means the tree is clean.
 
-There is **no skip or decline affordance**. A finding leaves the queue only by being fixed, or by editing the rule that produces it in `.codeauditor.json` (your rules editor). If a rule keeps firing on something you judge correct, change the rule — never work around it.
+There is **no skip or decline affordance**. A reading leaves the queue only by being fixed, or by editing the rule that produces it in `.codeauditor.json` (your rules editor). If a rule keeps firing on something you judge correct, change the rule — never work around it.
 
 ### `code-audit config` — know the project's laws
 
@@ -73,7 +81,7 @@ These are the codebase's declared constraints — "no importing X from Y," "modu
 
 ### Path Profiles — "my scripts directory is noisy"
 
-When an audit produces too many findings in scripts, tests, or fixtures, use **path profiles** in `.codeauditor.json` to exclude a directory from the blocking gate:
+When an audit produces too many readings in scripts, tests, or fixtures, use **path profiles** in `.codeauditor.json` to exclude a directory from the blocking gate:
 
 ```json
 {
@@ -84,11 +92,11 @@ When an audit produces too many findings in scripts, tests, or fixtures, use **p
 }
 ```
 
-Path profiles are an ordered array — files matching multiple profiles merge overrides (later wins). The `excludeFromGate: true` key excludes all findings in matching files from the blocking gate. Findings still report at their real severity — a path profile excludes a file from the gate, it never softens a finding within it.
+Path profiles are an ordered array — files matching multiple profiles merge overrides (later wins). The `excludeFromGate: true` key excludes all readings in matching files from the blocking gate. Readings still report at their real severity — a path profile excludes a file from the gate, it never softens a reading within it.
 
 A **built-in** `scripts-and-tests` profile ships with every install — it excludes `scripts/**`, `tests/**`, `__tests__/**`, `fixtures/**`, and `*.test.*`/`*.spec.*` files from the gate. Disable it with `"builtin": false` in `.codeauditor.json`.
 
-Invariant violations are **immune** to path profile gate exclusion — invariants enforce declared laws and always block.
+Invariant violations are **immune** to path profile gate exclusion — invariants enforce declared laws and block on the same severity gate as every other rule (`critical` and `warning` by default).
 
 ### `code-audit index` — refresh the index after structural changes
 
@@ -138,7 +146,7 @@ code-audit conventions propose --json                # JSON proposal array
 
 **Usage:** Run a full audit or `code-audit index sync` to mine conventions from the codebase index. Then `code-audit conventions list` to see what was found, and `code-audit conventions propose` to get the rules. Paste the proposals into the `rules` array in `.codeauditor.json`.
 
-Convention violations ship at `suggestion` severity by default. Severity ranks how a finding blocks the edit gate, not whether it matters — resolve suggestions the same way you resolve warnings, and promote them with `severityOverrides` if your team wants them to block edits too.
+Convention readings ship at `suggestion` severity by default. Severity is triage — how a reading blocks the edit gate, not whether it matters. Resolve suggestions the same way you resolve warnings, and promote them with `severityOverrides` if your team wants them to block edits too.
 
 ### `code-audit hotspots` — identify churn-prone code
 
@@ -171,7 +179,7 @@ Use `--format dot` to generate a directed call-graph diagram (Graphviz DOT forma
 
 Terminal output shows rank, function name, file path, PageRank percentile, betweenness percentile, complexity percentile, untested status, and composite risk score. JSON output fields: `functionName`, `filePath`, `pageRankPercentile`, `betweennessPercentile`, `complexityPercentile`, `untested`, `riskScore`.
 
-> **Release checklist**: When bumping the version on a release, update the version stamp on line 8 of all three canonical SKILL.md copies. `npm run verify:close` gates on test + integration + dist verification — the tag cannot move without all three green.
+> **Release checklist**: The version banner above is stamped by `npm run build:skills` from `package.json` (the single source of truth) — do not hand-edit it. Bump the version in `package.json`, run the build, and the skill copies it. `npm run verify:close` gates on test + integration + dist verification — the tag cannot move without all three green.
 
 ## Interpreting hook feedback
 
@@ -180,7 +188,7 @@ When an edit hook blocks your edit with a violation message:
 1. **Read the violation** — it includes the invariant rule's `message` field explaining *why* the edit was blocked
 2. **Fix the violation** — change your approach to comply with the invariant
 3. **Do NOT retry the same edit** — the hook will block it again
-4. The hook runs `code-audit changed`, and its gate is binary and per-rule: an invariant rule blocks the edit only if it declares `gating: true` (regardless of severity). Warnings and suggestions are still violations and must be fixed — they pass the gate, they are not resolved.
+4. The hook runs `code-audit changed`, and its gate is severity-scoped: any reading at a blocking severity (`critical` and `warning` by default, configurable via `gateSeverities` in `.codeauditor.json`) blocks the edit, from any rule. Suggestions are still readings and must be resolved — they report but do not block by default.
 
 The hook auto-installs the package via npx on first use — no manual npm step needed. If the hook reports `[code-auditor] code-audit could not run`, the npx auto-install failed (network, unsupported platform). The agent should try again; if it persists, `npm install code-auditor-mcp` is the manual fix.