@spardutti/claude-skills 2.31.0 → 2.32.1

package/bin/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { confirm, input } from "@inquirer/prompts";
+import { confirm } from "@inquirer/prompts";
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -8,16 +8,8 @@ import { dirname, join } from "node:path";
 import { fetchSkills, fetchCommands, fetchAgents } from "../lib/github.mjs";
 import { promptSkillSelection, promptCommandSelection, promptRemoval } from "../lib/prompt.mjs";
 import { installSkills, installCommands, installRequiredAgents } from "../lib/install.mjs";
-import {
-  setupHook,
-  detectStack,
-  writeGauntletConf,
-  autoModeRuleStatus,
-  writeAutoModeRule,
-} from "../lib/setup-hook.mjs";
-import { makeLocalSource, reportToolNeeds } from "../lib/local.mjs";
-import { scaffoldStryker } from "../lib/scaffold-stryker.mjs";
-import { setupClaudeMd } from "../lib/setup-claude-md.mjs";
+import { makeLocalSource } from "../lib/local.mjs";
+import { runPostInstall } from "../lib/post-install.mjs";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
   MANIFEST_FILE,
@@ -165,153 +157,7 @@ async function main() {
     process.exit(0);
   }
 
-  // --- Hook setup ---
-  // Offered whenever anything was installed: the skill gates need skills, but the
-  // gauntlet guards any repo with a test runner, commands-only installs included.
-  if (selectedSkills.length > 0 || selectedCommands.length > 0) {
-    console.log();
-    const shouldSetup = await confirm({
-      message: "Set up hooks — skill evaluation before edits, verification after? (Recommended)",
-      default: true,
-    });
-    if (shouldSetup) {
-      console.log();
-      await setupHook();
-      await setupClaudeMd();
-
-      // In auto mode the classifier denies the gate's ack, and it only reads
-      // autoMode.allow from the user's own ~/.claude/settings.json. Without this
-      // the gate cannot be satisfied at all, and the session cannot fix it
-      // either — an agent editing permission settings is denied by the same
-      // classifier. The installer is the only thing here running as the user.
-      const autoModeStatus = await autoModeRuleStatus();
-      if (autoModeStatus === "unreadable") {
-        console.log();
-        console.log(`  ${chalk.yellow("!")} ${chalk.dim("~/.claude/settings.json is not valid JSON — skipping the auto mode rule.")}`);
-      } else if (autoModeStatus !== "current") {
-        console.log();
-        console.log(chalk.dim("  Auto mode's classifier denies the gate's acknowledgement files, and"));
-        console.log(chalk.dim("  clearing that needs a rule in your own ~/.claude/settings.json. Claude"));
-        console.log(chalk.dim("  cannot add it — editing permission settings is denied to agents too."));
-        const addRule = await confirm({
-          message:
-            autoModeStatus === "stale"
-              ? "Update the auto mode allow rule in ~/.claude/settings.json? (Recommended)"
-              : "Add an auto mode allow rule to ~/.claude/settings.json? (Recommended)",
-          default: true,
-        });
-        if (addRule) {
-          try {
-            const written = await writeAutoModeRule();
-            console.log(`  Settings updated: ${written}`);
-          } catch (err) {
-            console.log(`  ${chalk.yellow("!")} ${chalk.dim(err.message)}`);
-          }
-        } else {
-          console.log(`  ${chalk.dim("Skipped. In auto mode the gate will block until you add it via /permissions.")}`);
-        }
-      }
-
-      // Report what the gauntlet will actually run, so a silent no-op is visible.
-      // This asks the installed hook itself — never a second copy of its logic.
-      const gates = await detectStack(CWD);
-      if (gates) {
-        for (const gate of gates.split(";").map((g) => g.trim()).filter(Boolean)) {
-          console.log(`  ${chalk.dim(`Gauntlet gate: ${gate}`)}`);
-        }
-      } else {
-        console.log(`  ${chalk.yellow("!")} ${chalk.dim("Gauntlet found no test runner here — it will stay asleep.")}`);
-        console.log();
-        const wantConf = await confirm({
-          message: "Point it at your test command now?",
-          default: false,
-        });
-        if (wantConf) {
-          const cmd = (await input({ message: "Test command:" })).trim();
-          if (cmd) {
-            const written = await writeGauntletConf(CWD, cmd);
-            console.log(`  Config written: ${written.replace(CWD + "/", "")}`);
-          }
-        }
-      }
-    }
-  }
-
-  // --- What the installed commands need that this project does not have ---
-  // /ship's mutation check is per project, so a monorepo needs a tool per project.
-  if (selectedCommands.some((c) => c.fileName === "ship.md")) {
-    const needs = await reportToolNeeds(CWD);
-    console.log();
-    if (needs.length === 0) {
-      console.log(`  ${chalk.dim("/ship's mutation check has a tool in every project here.")}`);
-    } else {
-      console.log(`  ${chalk.yellow("!")} ${chalk.bold("/ship needs a mutation tool per project")} ${chalk.dim("— without one it reports UNPROVEN, and never blocks.")}`);
-      if (!selectedSkills.some((s) => s.dirName === "testing-best-practices")) {
-        console.log(`    ${chalk.dim("Setting these up has traps — install the testing-best-practices skill for MUTATION-TESTING.md.")}`);
-      }
-      for (const n of needs.filter((n) => !n.ignorerOnly)) {
-        console.log(`    ${chalk.bold(n.label)} needs ${n.tool}`);
-        console.log(`      ${chalk.cyan(n.install)}`);
-        console.log(`      ${chalk.dim(n.config)}`);
-        for (const line of n.also ?? []) console.log(`      ${chalk.dim(line)}`);
-      }
-      for (const n of needs.filter((n) => n.ignorerOnly)) {
-        console.log(`    ${chalk.bold(n.label)} runs ${n.tool} without the class-name ignorer`);
-        console.log(`      ${chalk.dim("~40% of a first React run is mutants on className strings, which no test can honestly kill")}`);
-      }
-
-      // Printing five steps meant every project was set up by hand, and the one
-      // step people skipped was the class-name ignorer — the reason a first run
-      // comes back with dozens of mutants on className strings that no test can
-      // honestly kill. Write the two files instead of describing them.
-      const stryker = needs.filter((n) => n.tool === "Stryker");
-      if (stryker.length > 0) {
-        console.log();
-        const doScaffold = await confirm({
-          message: `Write Stryker's config and the class-name ignorer for ${stryker.length} project(s)?`,
-          default: true,
-        });
-        if (doScaffold) {
-          const installs = [];
-          const apiInstalls = [];
-          const vitest = [];
-          for (const n of stryker) {
-            const r = await scaffoldStryker(CWD, n.rel);
-            for (const f of r.wrote) console.log(`  Wrote: ${f}`);
-            for (const f of r.patched) console.log(`  Added the ignorer to: ${f}`);
-            for (const f of r.kept) console.log(`  ${chalk.dim(`Kept yours: ${f}`)}`);
-            for (const f of r.unreadable) {
-              console.log(`  ${chalk.yellow("!")} ${f} is not readable as JSON — left alone, add the ignorer by hand`);
-            }
-            // A project that already runs Stryker needs neither the install nor
-            // the vitest exclude repeated at it; it only lacked the ignorer.
-            if (n.ignorerOnly) {
-              apiInstalls.push(r.apiInstall);
-            } else {
-              installs.push(r.install);
-              vitest.push(r.vitest);
-            }
-          }
-          // Left to the reader on purpose: installing touches the lockfile and
-          // the network, and editing an existing vitest config means parsing
-          // someone's plugins and aliases, where being wrong breaks their tests.
-          if (installs.length > 0) {
-            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("Two steps left, per project:")}`);
-            for (const c of installs) console.log(`      ${chalk.cyan(c)}`);
-            for (const v of vitest) console.log(`      ${chalk.dim(v)}`);
-          }
-          // The ignorer imports @stryker-mutator/api, which npm hoists by
-          // accident and pnpm does not. Missing, it prints one WARN PluginLoader
-          // line, loads nothing, and every className mutant comes back survived.
-          if (apiInstalls.length > 0) {
-            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("The ignorer needs its own dependency:")}`);
-            for (const c of apiInstalls) console.log(`      ${chalk.cyan(c)}`);
-            console.log(`      ${chalk.dim("without it the ignorer silently does not load")}`);
-          }
-        }
-      }
-    }
-  }
+  await runPostInstall({ CWD, selectedSkills, selectedCommands });
 
   // --- Record what is now installed ---
   await writeManifest(CWD, {

package/hooks/gauntlet.sh

@@ -0,0 +1,328 @@
+#!/usr/bin/env bash
+# gauntlet.sh — Stop hook: fast deterministic gates on the changed diff.
+#
+# Runs when Claude finishes a turn. Silent when green. On a red gate it exits 2:
+# the turn keeps going, the user is shown why, and Claude is handed the failure.
+#
+# Two things the hook contract makes non-negotiable:
+#   - stop_hook_active must short-circuit, or a red gate loops forever.
+#   - A hook that hits its timeout (600s default for command hooks) is cancelled
+#     and its output discarded, so the turn ends as if the hook never ran. Keep
+#     the gates fast; that is a silent pass, not a block.
+#
+# Only cheap gates belong here (target: under ~30s). Mutation testing, deep
+# review, and the spec checklist are the /gauntlet command's job, not this hook's.
+#
+# Skip ladder, cheapest first — quits at the first "no":
+#   1. no changed files
+#   2. no changed *code* files (docs/config only)
+#   3. this exact diff already passed
+#   4. no gates detected for this repo
+#
+# Config, both optional and both KEY=value files that get sourced in this order:
+#   ~/.claude/gauntlet.conf          your defaults for every project
+#   <project>/.claude/gauntlet.conf  overrides for this one; wins key by key
+#   GAUNTLET_OFF=1                 disable entirely
+#   GAUNTLET_TYPECHECK="cmd"       explicit typecheck command ("" to skip)
+#   GAUNTLET_TEST="cmd"            explicit test command; $FILES = changed code files
+#   GAUNTLET_CODE_EXT="ts|tsx|py"  override which extensions count as code
+#   GAUNTLET_DEBUG=1               print the outcome to stderr on every run
+#   GAUNTLET_REQUIRE_TESTS=1       block when a runner matched 0 test files
+#
+# Setting either command switches the whole repo to explicit mode — auto-detection
+# is off, and only what you set runs.
+#
+# Per-project runners, for tests that cannot run on the host at all:
+#   <project>/.gauntlet-test        executable; run instead of the detected test
+#                                   command, with $FILES as its arguments
+#   <project>/.gauntlet-typecheck   executable; run instead of the detected
+#                                   typecheck command
+#
+# <project> is any directory holding a package.json or pyproject.toml, so one
+# half of a monorepo can run on the host while the other runs in a container.
+# Unlike GAUNTLET_TEST these do not disable detection anywhere else. Typically a
+# two-line `docker compose run --rm -T api pytest "$@"`. Same shape as
+# ship-gate's .mutmut-run.
+#
+# Every run records why it ended in /tmp/claude-gauntlet-<session>.why, so a green
+# run and a skipped one are told apart without re-running the hook.
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+
+# Never re-block a turn we already blocked — this would loop forever.
+case "$INPUT" in
+  *'"stop_hook_active":true'*) exit 0 ;;
+esac
+
+SESSION_ID=$(printf '%s' "$INPUT" | grep -o '"session_id":"[^"]*"' | head -1 \
+             | sed 's/"session_id":"//; s/"$//')
+if [ -z "$SESSION_ID" ]; then SESSION_ID="nosession"; fi
+MARKER="/tmp/claude-gauntlet-$SESSION_ID"
+WHY="$MARKER.why"
+
+# Records why this run ended, so "green" and "never ran" stop looking identical.
+quit() {
+  printf '%s\n' "$1" > "$WHY" 2>/dev/null
+  if [ -n "${GAUNTLET_DEBUG:-}" ]; then printf 'gauntlet: %s\n' "$1" >&2; fi
+  exit 0
+}
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$PROJECT_DIR" ]; then PROJECT_DIR="$PWD"; fi
+cd "$PROJECT_DIR" 2>/dev/null || quit "skipped: project dir unreadable"
+
+git rev-parse --git-dir >/dev/null 2>&1 || quit "skipped: not a git repo"
+
+GAUNTLET_OFF=""
+GAUNTLET_TYPECHECK="__auto__"
+GAUNTLET_TEST="__auto__"
+GAUNTLET_CODE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|sql"
+# Global defaults first, then the project's on top — project wins, key by key.
+if [ -n "${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ]; then . "$HOME/.claude/gauntlet.conf"; fi
+if [ -f "$PROJECT_DIR/.claude/gauntlet.conf" ]; then . "$PROJECT_DIR/.claude/gauntlet.conf"; fi
+if [ -n "$GAUNTLET_OFF" ]; then quit "skipped: GAUNTLET_OFF is set"; fi
+
+# ---------------------------------------------------------------- skip rule 1
+CHANGED=$( { git diff --name-only HEAD 2>/dev/null; \
+             git ls-files --others --exclude-standard 2>/dev/null; } | sort -u )
+if [ -z "$CHANGED" ] && [ -z "${GAUNTLET_DRYRUN:-}" ]; then quit "skipped: no changed files"; fi
+
+# ---------------------------------------------------------------- skip rule 2
+# .stryker-tmp holds Stryker's sandbox — a full copy of the project. A crashed
+# run leaves it behind, and then every file in it looks like a changed file.
+FILES_NL=$(printf '%s\n' "$CHANGED" | grep -E "\.($GAUNTLET_CODE_EXT)$" \
+           | grep -vE '(^|/)\.stryker-tmp/' || true)
+if [ -z "$FILES_NL" ] && [ -z "${GAUNTLET_DRYRUN:-}" ]; then
+  quit "skipped: no changed code files (docs/config only)"
+fi
+
+# ---------------------------------------------------------------- skip rule 3
+# The repo path is part of the hash: one session can touch several repos, and two
+# of them can legitimately hold an identical diff.
+DIFF_HASH=$( { printf '%s\n' "$PROJECT_DIR"; git diff HEAD 2>/dev/null; printf '%s\n' "$CHANGED"; } \
+             | git hash-object --stdin 2>/dev/null )
+if [ -f "$MARKER" ] && [ "$(cat "$MARKER")" = "$DIFF_HASH" ] \
+   && [ -z "${GAUNTLET_DRYRUN:-}" ]; then
+  quit "skipped: this diff already passed"
+fi
+
+# ---------------------------------------------------------------- skip rule 4
+# A monorepo can hold more than one stack, so detection collects every gate it
+# finds rather than stopping at the first. Each gate carries the file pattern it
+# applies to, and is skipped entirely when the diff touched none of those files —
+# so a Python-only change never runs the JS suite, and vice versa.
+TC_GATES=""
+TEST_GATES=""
+SKIP_NOTE=""
+
+add_gate() {  # kind (typecheck|tests), file regex, command
+  LINE=$(printf '%s\t%s\t%s' "$1" "$2" "$3")
+  if [ "$1" = "typecheck" ]; then
+    TC_GATES="$TC_GATES$LINE
+"
+  else
+    TEST_GATES="$TEST_GATES$LINE
+"
+  fi
+}
+
+JS_EXT='(ts|tsx|js|jsx|mjs|cjs)'
+
+# Builds the gates for one directory. "" is the repo root; anything else is a
+# nested project, and its gates match only files under that path. Commands run
+# from inside the directory, which is why the file list is passed as absolute
+# paths — a relative path would not survive the cd.
+add_dir_gates() {
+  d="$1"
+  if [ -n "$d" ]; then pre="^$d/.*\\." ; run="cd $d && " ; else pre='\.' ; run="" ; fi
+  have_tc=""; have_test=""
+  [ -n "$d" ] && [ -n "${ROOT_TC:-}" ] && have_tc="skip"
+  [ -n "$d" ] && [ -n "${ROOT_TEST:-}" ] && have_test="skip"
+
+  # A project whose tests need a database, a queue, or any other service cannot
+  # run them on the host, and detection here finds the host runner every time.
+  # An executable runner in the project directory says where they DO run —
+  # usually `docker compose run` against the app container — and wins over
+  # everything detected below.
+  #
+  # Per project, not per repo: GAUNTLET_TEST switches the WHOLE repo to explicit
+  # mode, so a monorepo needing a container for one stack had to hand-write
+  # commands for all of them. These let one half run on the host and the other
+  # in a container. Same shape as ship-gate's .mutmut-run, deliberately.
+  RUNNER_EXT="($JS_EXT|py)"
+  if [ -z "$have_tc" ] && [ -x "$d${d:+/}.gauntlet-typecheck" ]; then
+    add_gate typecheck "$pre$RUNNER_EXT\$" "${run}./.gauntlet-typecheck"
+    have_tc="skip"
+  fi
+  if [ -z "$have_test" ] && [ -x "$d${d:+/}.gauntlet-test" ]; then
+    add_gate tests "$pre$RUNNER_EXT\$" "${run}./.gauntlet-test \$FILES"
+    have_test="skip"
+  fi
+
+  if [ -f "$d${d:+/}package.json" ]; then
+    pkg="$d${d:+/}package.json"
+    if [ -z "$have_tc" ]; then
+      if grep -q '"typecheck"[[:space:]]*:' "$pkg"; then
+        add_gate typecheck "$pre($JS_EXT)\$" "${run}npm run --silent typecheck"
+      elif [ -f "$d${d:+/}tsconfig.json" ]; then
+        add_gate typecheck "$pre(ts|tsx)\$" "${run}npx --no-install tsc --noEmit"
+      fi
+    fi
+    if [ -z "$have_test" ]; then
+      if grep -q '"vitest"' "$pkg"; then
+        add_gate tests "$pre($JS_EXT)\$" "${run}npx --no-install vitest related --run \$FILES"
+      elif grep -q '"jest"' "$pkg"; then
+        add_gate tests "$pre($JS_EXT)\$" "${run}npx --no-install jest --findRelatedTests \$FILES --passWithNoTests"
+      elif grep -q '"test"[[:space:]]*:' "$pkg"; then
+        add_gate tests "$pre($JS_EXT)\$" "${run}CI=1 npm run --silent test"
+      fi
+    fi
+  fi
+
+  if [ -f "$d${d:+/}pyproject.toml" ] || [ -f "$d${d:+/}pytest.ini" ] || [ -f "$d${d:+/}setup.cfg" ]; then
+    if [ -z "$have_tc" ]; then
+      if [ -f "$d${d:+/}mypy.ini" ] || grep -qs 'tool.mypy' "$d${d:+/}pyproject.toml"; then
+        add_gate typecheck "${pre}py\$" "${run}python -m mypy ."
+      fi
+    fi
+    if [ -z "$have_test" ]; then
+      add_gate tests "${pre}py\$" "${run}python -m pytest -q"
+    fi
+  fi
+}
+
+detect() {
+  # Explicit config wins outright: auto-detection is off for the whole repo.
+  if [ "$GAUNTLET_TEST" != "__auto__" ] || [ "$GAUNTLET_TYPECHECK" != "__auto__" ]; then
+    if [ "$GAUNTLET_TYPECHECK" != "__auto__" ] && [ -n "$GAUNTLET_TYPECHECK" ]; then
+      add_gate typecheck '.' "$GAUNTLET_TYPECHECK"
+    fi
+    if [ "$GAUNTLET_TEST" != "__auto__" ] && [ -n "$GAUNTLET_TEST" ]; then
+      add_gate tests '.' "$GAUNTLET_TEST"
+    fi
+    return
+  fi
+
+  add_dir_gates ""
+
+  # Many repos keep no manifest at the root — the code lives in web/, api/,
+  # backend/, packages/*. Look two levels down, but only for the kind of gate the
+  # root did not already provide, so a repo that works today keeps working.
+  ROOT_TC="$TC_GATES"
+  ROOT_TEST="$TEST_GATES"
+  while IFS= read -r manifest; do
+    [ -z "$manifest" ] && continue
+    d=$(dirname "$manifest")
+    d=${d#./}
+    [ "$d" = "." ] && continue
+    add_dir_gates "$d"
+  done <<< "$(find . -mindepth 2 -maxdepth 3 \
+               \( -name package.json -o -name pyproject.toml -o -name pytest.ini \) \
+               -not -path '*/node_modules/*' -not -path '*/.git/*' \
+               -not -path '*/dist/*' -not -path '*/build/*' \
+               -not -path '*/.venv/*' -not -path '*/venv/*' 2>/dev/null | sort)"
+}
+detect
+
+# Typechecks before tests — cheapest first, so the slow gate is usually unpaid.
+GATES="$TC_GATES$TEST_GATES"
+if [ -n "${GAUNTLET_DRYRUN:-}" ]; then
+  if [ -z "$GATES" ]; then quit "would run: nothing — no gates detected"; fi
+  quit "would run: $(printf '%s' "$GATES" | cut -f1,3 | tr '\t' ' ' | tr '\n' '; ')"
+fi
+if [ -z "$GATES" ]; then
+  if [ -n "$SKIP_NOTE" ]; then quit "skipped: $SKIP_NOTE"; fi
+  quit "skipped: no gates detected for this repo"
+fi
+
+# ------------------------------------------------------------------ the gates
+FAILED=""
+OUTPUT=""
+NO_TEST_MATCH=""
+RAN=""
+# Kept in variables on purpose: a bare `}` inside a ${var//pat/repl} replacement
+# closes the expansion early and silently mangles the command.
+FILES_REPL='"${FILE_ARR[@]}"'
+PAT_BRACE='${FILES}'
+PAT_PLAIN='$FILES'
+
+while IFS=$'\t' read -r GKIND GEXT GCMD; do
+  [ -z "$GKIND" ] && continue
+  GFILES=$(printf '%s\n' "$FILES_NL" | grep -E "$GEXT" || true)
+  [ -z "$GFILES" ] && continue
+  # $FILES is substituted as a real argument list, not a space-joined string —
+  # word splitting would tear "src/my folder/a.ts" into two bogus paths.
+  mapfile -t REL_ARR <<< "$GFILES"
+  FILE_ARR=()
+  for f in "${REL_ARR[@]}"; do FILE_ARR+=("$PROJECT_DIR/$f"); done
+  export FILES=$(printf '%s' "$GFILES" | tr '\n' ' ')
+  GCMD_RUN=${GCMD//"$PAT_BRACE"/$FILES_REPL}
+  GCMD_RUN=${GCMD_RUN//"$PAT_PLAIN"/$FILES_REPL}
+  RAN="$RAN$GKIND "
+  GATE_OUT=$(eval "$GCMD_RUN" 2>&1)
+  if [ $? -ne 0 ]; then
+    # A gate whose tool is not installed is a missing gate, not a failing one.
+    # Blocking on it would wall off every turn until the user installs something.
+    if printf '%s' "$GATE_OUT" | grep -qiE 'command not found|no module named|cannot find module|could not determine executable|canceled due to missing packages|missing script|is not recognized'; then
+      SKIP_NOTE="the $GKIND tool is not installed"
+      RAN="${RAN%"$GKIND "}"
+      continue
+    fi
+    FAILED="$GKIND"
+    OUTPUT="$GATE_OUT"
+    break
+  fi
+  # A runner handed files it has no tests for exits 0 and looks exactly like a
+  # pass. It is the loudest false green: the changed code was never executed.
+  if [ "$GKIND" = "tests" ] \
+     && printf '%s' "$GATE_OUT" | grep -qiE 'no test files found|no tests found|no tests ran'; then
+    NO_TEST_MATCH="$GCMD"
+    OUTPUT="$GATE_OUT"
+  fi
+done <<< "$GATES"
+
+if [ -z "$FAILED" ] && [ -n "$NO_TEST_MATCH" ] && [ -n "${GAUNTLET_REQUIRE_TESTS:-}" ]; then
+  FAILED="tests"
+  OUTPUT="$OUTPUT
+
+The runner matched 0 test files for the changed code, so nothing was executed.
+Write a test that covers the change, or unset GAUNTLET_REQUIRE_TESTS."
+fi
+
+if [ -z "$FAILED" ]; then
+  printf '%s' "$DIFF_HASH" > "$MARKER"
+  if [ -z "$RAN" ]; then
+    if [ -n "$SKIP_NOTE" ]; then quit "skipped: $SKIP_NOTE"; fi
+    quit "skipped: no gate applied to the changed files"
+  elif [ -n "$SKIP_NOTE" ]; then
+    quit "green: gates passed ($RAN) — but $SKIP_NOTE"
+  elif [ -n "$NO_TEST_MATCH" ]; then
+    quit "green: gates passed, but a runner matched 0 test files — that code was never executed"
+  fi
+  quit "green: gates passed ($RAN)"
+fi
+
+# ------------------------------------------------------------------ block red
+# Last 60 lines only — the hook's reason is read by a model, not archived.
+TAIL=$(printf '%s\n' "$OUTPUT" | tail -60)
+MSG="GAUNTLET FAILED: the $FAILED gate is red on the changed files.
+
+Fix it before ending the turn. Do not weaken or delete a test to make this pass.
+If the failure is unrelated to your change, say so explicitly and stop.
+
+Changed code files:
+$FILES
+
+--- $FAILED output (last 60 lines) ---
+$TAIL"
+
+printf '%s\n' "red: the $FAILED gate failed" > "$WHY" 2>/dev/null
+
+# Exit 2 is the only path where a red is visible to the user: its stderr is shown
+# to them as the reason the turn is continuing. Exit 0 with {"decision":"continue"}
+# also keeps the turn going, but the reason reaches Claude alone — so a failing
+# gate looked, from the outside, exactly like a gauntlet that does nothing.
+printf '%s\n' "$MSG" >&2
+exit 2

package/hooks/ship-gate-hook.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# ship-gate-hook.sh — PreToolUse on Bash. Refuses the commands that publish work
+# unless ship-gate.sh has left a receipt for exactly these changes.
+#
+# A gate written as an instruction is a gate an agent can decide is not worth the
+# time — and then report a pass it never earned, which is the part you cannot see
+# from the outside. This removes the claim entirely: either the receipt exists for
+# this exact content, or git does not run.
+#
+# The receipt key covers everything about to ship, so it survives `git commit`
+# and still matches at push time, and it changes the moment any file is edited —
+# a fix has to be re-gated instead of riding on the previous verdict.
+#
+# It gated `git commit` and `git push` until 2.23.0, and that was the wrong
+# moment. The gate's scope is merge-base..HEAD — the whole branch, because the
+# whole branch is what a PR ships — so a branch touching 46 files re-mutated all
+# 46 on every commit. Fifteen minutes, twenty times, for one branch. Neither a
+# commit nor a push to a feature branch publishes anything, so neither is gated
+# now: the cost is paid once, at the point work actually ships.
+
+INPUT=$(cat)
+
+CMD=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \
+      | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$PROJECT_DIR" 2>/dev/null || exit 0
+
+# Opening or merging a PR publishes. So does pushing while standing on a
+# protected branch — that is a direct ship with no PR in front of it. The branch
+# is read from git rather than parsed out of the command, because `git push` with
+# no arguments names no branch at all.
+case "$CMD" in
+  *"gh pr create"*|*"gh pr merge"*) ;;
+  *"git push"*)
+    BRANCH=$(git branch --show-current 2>/dev/null)
+    case "$BRANCH" in
+      main|master|develop|development|dev) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+  *) exit 0 ;;
+esac
+
+GATE="$PROJECT_DIR/.claude/hooks/ship-gate.sh"
+[ -x "$GATE" ] || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# Ask the gate for the key rather than recomputing it here. Two implementations
+# of the same rule drift, and the drift is silent.
+KEY=$(bash "$GATE" --key 2>/dev/null)
+[ -z "$KEY" ] && exit 0
+
+RECEIPT="/tmp/claude-shipgate-$KEY"
+if [ -f "$RECEIPT" ]; then
+  exit 0
+fi
+
+MSG="BLOCKED: no ship-gate receipt for these changes.
+
+The quality gate has not run against the code you are about to publish, or the
+code changed since it last did. Run it:
+
+  bash .claude/hooks/ship-gate.sh
+
+It checks file length and mutation-tests the changed lines, and writes a receipt
+this hook can see. Fix what it reports and run it again — a fix invalidates the
+previous receipt on purpose.
+
+Do NOT hand-roll a substitute check: only ship-gate.sh writes a receipt, so a
+weaker check you designed yourself cannot be passed off as this one.
+
+To publish without the gate, say so out loud and run:
+
+  bash .claude/hooks/ship-gate.sh --force"
+
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\r'/\\r}"
+  s="${s//$'\t'/\\t}"
+  printf '"%s"' "$s"
+}
+
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$(json_escape "$MSG")"
+exit 0