@spardutti/claude-skills 2.8.1 → 2.9.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,70 @@ 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
+blocks the turn and hands the failure back to Claude to fix before you ever see it.
+
+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
+4. no test runner detected in the 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
+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
+```
+
+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 +258,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 +273,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,215 @@ 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. Blocks the turn when a
+# gate is red, handing the failure back to Claude to fix before the user sees it.
+#
+# 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 test runner detected
+#
+# 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_CODE_EXT="ts|tsx|py"  override which extensions count as code
+
+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
+
+PROJECT_DIR="\${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$PROJECT_DIR" ]; then PROJECT_DIR="$PWD"; fi
+cd "$PROJECT_DIR" 2>/dev/null || exit 0
+
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+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 exit 0; 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
+
+# ---------------------------------------------------------------- skip rule 2
+FILES=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_CODE_EXT)$" || true)
+if [ -z "$FILES" ]; then exit 0; fi
+
+# ---------------------------------------------------------------- skip rule 3
+DIFF_HASH=$( { 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
+
+# ---------------------------------------------------------------- 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.
+detect() {
+  if [ "$GAUNTLET_TEST" != "__auto__" ]; then return; fi
+  GAUNTLET_TEST=""
+  GAUNTLET_TYPECHECK=""
+  if [ -f package.json ]; then
+    if grep -q '"vitest"' package.json; then
+      GAUNTLET_TEST='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'
+    fi
+  fi
+  if [ -z "$GAUNTLET_TEST" ] && { [ -f pyproject.toml ] || [ -f pytest.ini ] || [ -f setup.cfg ]; }; then
+    GAUNTLET_TEST='python -m pytest -q'
+    if [ -f mypy.ini ] || grep -qs 'tool.mypy' pyproject.toml; then
+      GAUNTLET_TYPECHECK='python -m mypy .'
+    fi
+  fi
+}
+detect
+if [ -z "$GAUNTLET_TEST" ]; then exit 0; 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)
+  if [ $? -ne 0 ]; then
+    FAILED="$GATE_NAME"
+    OUTPUT="$GATE_OUT"
+    return 1
+  fi
+  return 0
+}
+
+run_gate "typecheck" "$GAUNTLET_TYPECHECK" && run_gate "tests" "$GAUNTLET_TEST"
+
+if [ -z "$FAILED" ]; then
+  printf '%s' "$DIFF_HASH" > "$MARKER"
+  exit 0
+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 '{"decision":"block","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 (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 +373,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 +451,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.9.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {