@spardutti/claude-skills 2.8.1 → 2.10.0

package/README.md

@@ -47,7 +47,7 @@ The CLI will:
 2. Let you pick skills to install → `.claude/skills/`
 3. Let you pick commands to install → `.claude/commands/`
 4. Auto-install any subagents the selected commands declare → `.claude/agents/`
-5. Optionally set up the **skill-evaluation hook** (recommended — see [How It Works](#how-it-works))
+5. Optionally set up the **hooks** — skill evaluation before edits, verification after (recommended — see [How It Works](#how-it-works))
 
 ## Skill Catalog
 
@@ -132,11 +132,17 @@ npx @spardutti/claude-skills --sync
 
 After installing skills, the CLI offers to set up a hook that **guarantees** Claude evaluates your skills before writing code — instead of a soft reminder it can ignore.
 
-It installs two hooks and appends a rule to your `CLAUDE.md`:
+It installs four hooks and appends a rule to your `CLAUDE.md`. Three guard the
+**front** — nothing is written until your skills are considered:
 
 - `skill-gate.sh` — a `PreToolUse` gate on `Write|Edit|MultiEdit`
+- `skill-application-gate.sh` — a second `PreToolUse` gate requiring each loaded skill to be applied, not just read
 - `skill-gate-automark.sh` — a `PostToolUse` hook on `Skill` that clears the gate
 
+The fourth guards the **back** — nothing finishes until the code passes:
+
+- `gauntlet.sh` — a `Stop` hook running the fast gates on your changed files (see [Automatic Verification](#automatic-verification-gauntlet))
+
 <details>
 <summary>How the gate works</summary>
 
@@ -151,7 +157,9 @@ It registers in `.claude/settings.json`:
   "hooks": {
     "PreToolUse": [
       { "matcher": "Write|Edit|MultiEdit", "hooks": [
-        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate.sh" } ] }
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate.sh" } ] },
+      { "matcher": "Write|Edit|MultiEdit", "hooks": [
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-application-gate.sh" } ] }
     ],
     "PostToolUse": [
       { "matcher": "Skill", "hooks": [
@@ -163,6 +171,109 @@ It registers in `.claude/settings.json`:
 
 </details>
 
+### Automatic Verification (Gauntlet)
+
+The same install adds `gauntlet.sh` — a `Stop` hook that runs the cheap, deterministic
+gates on your changed files every time Claude finishes a turn. Green is silent; red returns
+`{"decision":"continue"}` so the turn doesn't end, handing the failure back to Claude to
+fix before you ever see it.
+
+Keep the gates fast for a reason beyond patience: a `command` hook that reaches its timeout
+(600s by default) is cancelled and its **output discarded**, so the turn ends as if the hook
+never ran. A stalled gate is a silent pass, not a block.
+
+Only fast gates live here (target: under ~30s). Mutation testing and deep review stay
+manual — they belong to `/test-review` and `/deep-review`, not to every turn.
+
+At install time the CLI reports what it found, so a silent no-op is never a surprise:
+
+```text
+Gauntlet detected tsc + vitest — it will run those on changed files.
+```
+
+If no test runner is detected it says so, and offers to write a `.claude/gauntlet.conf`
+pointing at your test command. Detection covers vitest, jest, pytest, `tsc`, and `mypy`;
+everything else needs that one config line.
+
+<details>
+<summary>How the gauntlet hook works</summary>
+
+It runs a skip ladder first, cheapest check first, and quits at the first "no":
+
+1. no changed files (planning turns, questions)
+2. no changed **code** files (docs/config only)
+3. this exact diff already passed — the hash of a green run is cached per session and repo
+4. no gates detected for this repo
+
+Rule 3 is what makes repeated `/ship` runs free: the gates run once per distinct diff.
+
+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. `GAUNTLET_DEBUG=1` prints
+the same line to stderr:
+
+```text
+gauntlet: green: gates passed
+gauntlet: skipped: no changed code files (docs/config only)
+gauntlet: green: gates passed, but the runner matched 0 test files — the changed code was never executed
+```
+
+That last one is the false green worth knowing about. A test runner given files it has no
+tests for exits 0 and looks exactly like a pass — in a monorepo whose vitest workspace
+excludes a package, **no** change in that package can ever be covered. The hook names it
+instead of reporting green. Set `GAUNTLET_REQUIRE_TESTS=1` to make it block instead.
+
+The stack is auto-detected: vitest / jest / pytest for tests, and for typechecking the
+repo's own `typecheck` script if it has one, else bare `tsc --noEmit` or `mypy`. The script
+is preferred because a workspace root `tsconfig.json` is often solution-style, where
+`tsc --noEmit` does not mean what the repo's `tsc -b` means.
+
+**Monorepos with more than one stack work.** Detection collects every gate it finds rather
+than stopping at the first, and each gate carries the file pattern it applies to — so a
+JS + Python repo gets four gates, and a turn that touched only `.py` files runs the Python
+two and skips the JS two entirely. Typechecks always run before tests, and the first red
+stops the rest.
+
+Setting `GAUNTLET_TEST` or `GAUNTLET_TYPECHECK` switches the repo to explicit mode:
+auto-detection is off and only what you set runs.
+
+**A missing tool is a skip, not a red.** A fresh clone with no `node_modules`, or a venv
+without pytest, would otherwise fail every gate and block every turn — so the hook reports
+`skipped: node_modules is missing — run your install first` and gets out of the way. Only
+a gate that actually ran and actually failed blocks. Override anything in
+a config file — two are read, in this order, and the project's wins key by key:
+
+```text
+~/.claude/gauntlet.conf          your defaults for every project
+<project>/.claude/gauntlet.conf  overrides for this one
+```
+
+```bash
+GAUNTLET_OFF=1                       # disable entirely
+GAUNTLET_TYPECHECK='npm run check'   # "" to skip the gate
+GAUNTLET_TEST='npm test -- $FILES'   # $FILES = changed code files
+GAUNTLET_CODE_EXT='ts|tsx|py'        # what counts as code
+GAUNTLET_DEBUG=1                     # print the outcome to stderr every run
+GAUNTLET_REQUIRE_TESTS=1             # block when the runner matched 0 test files
+```
+
+Set your house rules once in `~/.claude/gauntlet.conf`; only reach for the project file
+where a repo does something unusual (or set `GAUNTLET_OFF=1` there to opt one out).
+
+It registers in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      { "hooks": [
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/gauntlet.sh" } ] }
+    ]
+  }
+}
+```
+
+</details>
+
 <details>
 <summary>Manual install (without the CLI)</summary>
 
@@ -186,6 +297,7 @@ skills/        Skill playbooks — some are bundles (SKILL.md + on-demand refere
 commands/      Slash commands installed to .claude/commands/
 agents/        Subagent definitions — commands declare which they need via requires-agents
 scripts/       validate-skills.mjs — checks skill length caps and reference integrity
+               gauntlet.sh — the Stop-hook verification gates, embedded by the CLI
 cli/           The npm installer (npx @spardutti/claude-skills); version in cli/package.json
 .husky/        pre-push hook running the skill validator
 package.json   Private dev-tooling package (claude-skills-dev) — not the published one
@@ -200,6 +312,19 @@ Skills live in `skills/<name>/SKILL.md`. Authoring conventions are in [CLAUDE.md
 - References are one level deep — `SKILL.md` links them, they don't link each other.
 - `npm run validate-skills` enforces this; it also runs on `pre-push`.
 
+To get the validator on **every turn** instead of only on push, drop this into
+this repo's `.claude/gauntlet.conf` — `.claude/` is gitignored, so each contributor adds it
+locally. It has to be the project file, not `~/.claude/gauntlet.conf`: these settings are
+only right for a skills repo:
+
+```bash
+GAUNTLET_CODE_EXT='md|mjs|js|json|sh'   # markdown IS the product here
+GAUNTLET_TYPECHECK=''
+GAUNTLET_TEST='node scripts/validate-skills.mjs'
+```
+
+Without the `CODE_EXT` line the hook treats a skill edit as a docs-only change and skips.
+
 ## License
 
 MIT

package/bin/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { confirm } from "@inquirer/prompts";
+import { confirm, input } from "@inquirer/prompts";
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -8,7 +8,7 @@ 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 } from "../lib/setup-hook.mjs";
+import { setupHook, detectStack, writeGauntletConf } from "../lib/setup-hook.mjs";
 import { setupClaudeMd } from "../lib/setup-claude-md.mjs";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
@@ -143,17 +143,40 @@ async function main() {
     process.exit(0);
   }
 
-  // --- Hook setup (only if skills were installed) ---
-  if (selectedSkills.length > 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 skill evaluation hook + CLAUDE.md rule? (Recommended)",
+      message: "Set up hooks — skill evaluation before edits, verification after? (Recommended)",
       default: true,
     });
     if (shouldSetup) {
       console.log();
       await setupHook();
       await setupClaudeMd();
+
+      // Report what the gauntlet will actually run, so a silent no-op is visible.
+      const { test, typecheck } = await detectStack(CWD);
+      if (test) {
+        const found = [typecheck, test].filter(Boolean).join(" + ");
+        console.log(`  ${chalk.dim(`Gauntlet detected ${found} — it will run those on changed files.`)}`);
+      } 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 + "/", "")}`);
+          }
+        }
+      }
     }
   }
 

package/lib/setup-hook.mjs

@@ -1,5 +1,5 @@
 import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { join, resolve, dirname } from "node:path";
 
 // PreToolUse gate on Write|Edit|MultiEdit. Blocks the tool call unless
 // a per-session marker file exists at /tmp/claude-skill-gate-<SESSION_ID>.
@@ -155,18 +155,329 @@ printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision"
 exit 0
 `;
 
+// Stop hook: fast deterministic gates on the changed diff. Silent when green,
+// blocks the turn when a gate is red so the model fixes it before the user sees
+// it. Canonical source: scripts/gauntlet.sh in the claude-skills repo.
+const GAUNTLET_SCRIPT = `#!/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 returns
+# {"decision":"continue"} so the turn does not end, handing the failure back to
+# Claude to fix before the user sees it.
+#
+# 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.
+#
+# 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" ]; then quit "skipped: no changed files"; fi
+
+# ---------------------------------------------------------------- skip rule 2
+FILES_NL=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_CODE_EXT)$" || true)
+if [ -z "$FILES_NL" ]; 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" ]; 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)$'
+
+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
+
+  # Without node_modules every npm/npx gate fails on a missing binary, which
+  # would block every turn in a fresh clone. That is a missing tool, not a red.
+  if [ -f package.json ] && [ ! -d node_modules ]; then
+    SKIP_NOTE="node_modules is missing — run your install first"
+  elif [ -f package.json ]; then
+    # Prefer the repo's own typecheck script. In a workspace repo the root
+    # tsconfig is often solution-style (references only), where bare
+    # \`tsc --noEmit\` does not mean what \`tsc -b\` means.
+    if grep -q '"typecheck"[[:space:]]*:' package.json; then
+      add_gate typecheck "$JS_EXT" 'npm run --silent typecheck'
+    elif [ -f tsconfig.json ]; then
+      add_gate typecheck '\\.(ts|tsx)$' 'npx --no-install tsc --noEmit'
+    fi
+    if grep -q '"vitest"' package.json; then
+      add_gate tests "$JS_EXT" 'npx --no-install vitest related --run $FILES'
+    elif grep -q '"jest"' package.json; then
+      add_gate tests "$JS_EXT" 'npx --no-install jest --findRelatedTests $FILES --passWithNoTests'
+    fi
+  fi
+
+  if [ -f pyproject.toml ] || [ -f pytest.ini ] || [ -f setup.cfg ]; then
+    if [ -f mypy.ini ] || grep -qs 'tool.mypy' pyproject.toml; then
+      add_gate typecheck '\\.py$' 'python -m mypy .'
+    fi
+    add_gate tests '\\.py$' 'python -m pytest -q'
+  fi
+}
+detect
+
+# Typechecks before tests — cheapest first, so the slow gate is usually unpaid.
+GATES="$TC_GATES$TEST_GATES"
+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 FILE_ARR <<< "$GFILES"
+  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|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"
+
+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 '%s\\n' "red: the $FAILED gate failed" > "$WHY" 2>/dev/null
+if [ -n "\${GAUNTLET_DEBUG:-}" ]; then printf 'gauntlet: red: the %s gate failed\\n' "$FAILED" >&2; fi
+# A Stop hook's decision is "continue" / "stop" / "escalate" — "block" is not a
+# valid value and would be ignored, letting the turn end on a red gate.
+printf '{"decision":"continue","reason":%s}\\n' "$(json_escape "$MSG")"
+exit 0
+`;
+
 const GATE_FILENAME = "skill-gate.sh";
 const AUTO_MARK_FILENAME = "skill-gate-automark.sh";
 const APPLICATION_GATE_FILENAME = "skill-application-gate.sh";
+const GAUNTLET_FILENAME = "gauntlet.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
+// Mirrors the detect() in scripts/gauntlet.sh. Kept in sync by hand: this one
+// only reports what the hook will find, it never decides anything.
+export async function detectStack(targetDir = process.cwd()) {
+  const dir = resolve(targetDir);
+  const has = async (f) => {
+    try { await readFile(join(dir, f), "utf-8"); return true; } catch { return false; }
+  };
+  const read = async (f) => {
+    try { return await readFile(join(dir, f), "utf-8"); } catch { return ""; }
+  };
+
+  let test = null;
+  let typecheck = null;
+
+  const pkg = await read("package.json");
+  if (pkg) {
+    if (pkg.includes('"vitest"')) test = "vitest";
+    else if (pkg.includes('"jest"')) test = "jest";
+    if (/"typecheck"\s*:/.test(pkg)) typecheck = "npm run typecheck";
+    else if (await has("tsconfig.json")) typecheck = "tsc";
+  }
+  if (!test && (await has("pyproject.toml") || await has("pytest.ini") || await has("setup.cfg"))) {
+    test = "pytest";
+    if (await has("mypy.ini") || (await read("pyproject.toml")).includes("tool.mypy")) {
+      typecheck = "mypy";
+    }
+  }
+  return { test, typecheck };
+}
+
+// Written only when detection finds nothing — otherwise the hook auto-detects and
+// no config file is needed.
+export async function writeGauntletConf(targetDir, testCommand) {
+  const confPath = join(resolve(targetDir), ".claude", "gauntlet.conf");
+  await mkdir(dirname(confPath), { recursive: true });
+  await writeFile(confPath, [
+    "# Gauntlet config. Read after ~/.claude/gauntlet.conf, and wins over it.",
+    "# GAUNTLET_OFF=1 disables the hook in this project.",
+    "",
+    "GAUNTLET_TYPECHECK=''",
+    `GAUNTLET_TEST='${testCommand.replace(/'/g, "'\\''")}'`,
+    "",
+  ].join("\n"), { mode: 0o644 });
+  return confPath;
+}
+
 export async function setupHook(targetDir = process.cwd()) {
   const resolved = resolve(targetDir);
   const hooksDir = join(resolved, ".claude", "hooks");
   const gatePath = join(hooksDir, GATE_FILENAME);
   const autoMarkPath = join(hooksDir, AUTO_MARK_FILENAME);
   const applicationGatePath = join(hooksDir, APPLICATION_GATE_FILENAME);
+  const gauntletPath = join(hooksDir, GAUNTLET_FILENAME);
   const settingsPath = join(resolved, ".claude", "settings.json");
 
   await mkdir(hooksDir, { recursive: true });
@@ -176,6 +487,8 @@ export async function setupHook(targetDir = process.cwd()) {
   await chmod(autoMarkPath, 0o755);
   await writeFile(applicationGatePath, APPLICATION_GATE_SCRIPT, { mode: 0o755 });
   await chmod(applicationGatePath, 0o755);
+  await writeFile(gauntletPath, GAUNTLET_SCRIPT, { mode: 0o755 });
+  await chmod(gauntletPath, 0o755);
 
   // Remove the legacy audit-runner hook file from prior installs (2.3.x).
   try {
@@ -252,10 +565,24 @@ export async function setupHook(targetDir = process.cwd()) {
     settings.hooks.PostToolUse = [autoMarkEntry];
   }
 
+  // Register Stop gauntlet hook.
+  const gauntletCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GAUNTLET_FILENAME}`;
+  const gauntletEntry = { hooks: [{ type: "command", command: gauntletCommand }] };
+
+  if (Array.isArray(settings.hooks.Stop)) {
+    const exists = settings.hooks.Stop.some((entry) =>
+      entry.hooks?.some((h) => h.command?.endsWith(GAUNTLET_FILENAME))
+    );
+    if (!exists) settings.hooks.Stop.push(gauntletEntry);
+  } else {
+    settings.hooks.Stop = [gauntletEntry];
+  }
+
   await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o644 });
 
   console.log(`  Hook installed: .claude/hooks/${GATE_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${AUTO_MARK_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${APPLICATION_GATE_FILENAME}`);
+  console.log(`  Hook installed: .claude/hooks/${GAUNTLET_FILENAME}`);
   console.log(`  Settings updated: .claude/settings.json`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {