@spardutti/claude-skills 2.9.0 → 2.10.0

package/README.md

@@ -174,8 +174,13 @@ It registers in `.claude/settings.json`:
 ### 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
-blocks the turn and hands the failure back to Claude to fix before you ever see it.
+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.
@@ -197,12 +202,44 @@ 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
-4. no test runner detected in the repo
+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.
 
-The stack is auto-detected (vitest / jest / pytest, `tsc` / `mypy`). Override anything in
+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
@@ -215,6 +252,8 @@ 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

package/lib/setup-hook.mjs

@@ -161,8 +161,15 @@ exit 0
 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. Blocks the turn when a
-# gate is red, handing the failure back to Claude to fix before the user sees it.
+# 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.
@@ -171,15 +178,23 @@ const GAUNTLET_SCRIPT = `#!/usr/bin/env bash
 #   1. no changed files
 #   2. no changed *code* files (docs/config only)
 #   3. this exact diff already passed
-#   4. no test runner detected
+#   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"       override the typecheck command ("" to skip)
-#   GAUNTLET_TEST="cmd"            override the test command; $FILES = changed code files
+#   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
 
@@ -190,11 +205,24 @@ 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 || exit 0
+cd "$PROJECT_DIR" 2>/dev/null || quit "skipped: project dir unreadable"
 
-git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || quit "skipped: not a git repo"
 
 GAUNTLET_OFF=""
 GAUNTLET_TYPECHECK="__auto__"
@@ -203,78 +231,159 @@ GAUNTLET_CODE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|
 # 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 exit 0; 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 exit 0; fi
+if [ -z "$CHANGED" ]; then quit "skipped: no changed files"; fi
 
 # ---------------------------------------------------------------- skip rule 2
-FILES=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_CODE_EXT)$" || true)
-if [ -z "$FILES" ]; then exit 0; fi
+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
-DIFF_HASH=$( { git diff HEAD 2>/dev/null; printf '%s\\n' "$CHANGED"; } \\
+# 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 )
-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"
-if [ -f "$MARKER" ] && [ "$(cat "$MARKER")" = "$DIFF_HASH" ]; then exit 0; fi
+if [ -f "$MARKER" ] && [ "$(cat "$MARKER")" = "$DIFF_HASH" ]; then
+  quit "skipped: this diff already passed"
+fi
 
 # ---------------------------------------------------------------- skip rule 4
-# Detect the stack once. Auto-detection is a default, not a decision — the conf
-# file wins whenever a repo does something unusual.
+# 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() {
-  if [ "$GAUNTLET_TEST" != "__auto__" ]; then return; fi
-  GAUNTLET_TEST=""
-  GAUNTLET_TYPECHECK=""
-  if [ -f package.json ]; then
+  # 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
-      GAUNTLET_TEST='npx --no-install vitest related --run $FILES'
+      add_gate tests "$JS_EXT" 'npx --no-install vitest related --run $FILES'
     elif grep -q '"jest"' package.json; then
-      GAUNTLET_TEST='npx --no-install jest --findRelatedTests $FILES --passWithNoTests'
-    fi
-    if [ -f tsconfig.json ]; then
-      GAUNTLET_TYPECHECK='npx --no-install tsc --noEmit'
+      add_gate tests "$JS_EXT" 'npx --no-install jest --findRelatedTests $FILES --passWithNoTests'
     fi
   fi
-  if [ -z "$GAUNTLET_TEST" ] && { [ -f pyproject.toml ] || [ -f pytest.ini ] || [ -f setup.cfg ]; }; then
-    GAUNTLET_TEST='python -m pytest -q'
+
+  if [ -f pyproject.toml ] || [ -f pytest.ini ] || [ -f setup.cfg ]; then
     if [ -f mypy.ini ] || grep -qs 'tool.mypy' pyproject.toml; then
-      GAUNTLET_TYPECHECK='python -m mypy .'
+      add_gate typecheck '\\.py$' 'python -m mypy .'
     fi
+    add_gate tests '\\.py$' 'python -m pytest -q'
   fi
 }
 detect
-if [ -z "$GAUNTLET_TEST" ]; then exit 0; fi
+
+# 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
-# Cheapest first, stop at the first red. Most failures land in the first gate,
-# so the expensive ones are usually never paid for.
-export FILES=$(printf '%s' "$FILES" | tr '\\n' ' ')
 FAILED=""
 OUTPUT=""
-
-run_gate() {
-  GATE_NAME="$1"
-  GATE_CMD="$2"
-  if [ -z "$GATE_CMD" ]; then return 0; fi
-  GATE_OUT=$(eval "$GATE_CMD" 2>&1)
+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
-    FAILED="$GATE_NAME"
+    # 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"
-    return 1
+    break
   fi
-  return 0
-}
+  # 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
 
-run_gate "typecheck" "$GAUNTLET_TYPECHECK" && run_gate "tests" "$GAUNTLET_TEST"
+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"
-  exit 0
+  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
@@ -301,7 +410,11 @@ json_escape() {
   printf '"%s"' "$s"
 }
 
-printf '{"decision":"block","reason":%s}\\n' "$(json_escape "$MSG")"
+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
 `;
 
@@ -330,7 +443,8 @@ export async function detectStack(targetDir = process.cwd()) {
   if (pkg) {
     if (pkg.includes('"vitest"')) test = "vitest";
     else if (pkg.includes('"jest"')) test = "jest";
-    if (await has("tsconfig.json")) typecheck = "tsc";
+    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";

package/package.json

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