@spardutti/claude-skills 2.12.1 → 2.13.1

package/README.md

@@ -142,8 +142,20 @@ After installing skills, the CLI offers to set up a hook that **guarantees** Cla
 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-gate.sh` — a `PreToolUse` gate on `Write|Edit|MultiEdit|Bash`
 - `skill-application-gate.sh` — a second `PreToolUse` gate requiring each loaded skill to be applied, not just read
+
+Both cover **Bash**, not only the file-writing tools. A session that edits through
+`python3 - <<'PY'` in Bash walked past the old matcher entirely — twelve source files, not
+one prompt — and some harnesses actively tell the model to prefer Bash for edits. Only
+commands that can write are gated (a redirect, `tee`, `sed -i`, `cp`/`mv`, or an
+interpreter given inline code or a heredoc); `git status` and a redirect to `/dev/null`
+pass untouched, and the command that clears the gate is never gated against itself.
+
+Neither gate fires on **prose** — `.md`, `.mdx`, `.txt`, `.rst`, `.adoc`, images. Skills
+are about code, and a repo full of `PLAN_*.md` otherwise hits the gate on every write.
+Config files (`.json`, `.yml`, `.toml`) stay gated, because skills do have rules about
+`tsconfig`, `package.json`, and Compose.
 - `skill-gate-automark.sh` — a `PostToolUse` hook on `Skill` that clears the gate
 
 The last two guard the **back** — nothing finishes or ships until the code passes:
@@ -164,9 +176,9 @@ It registers in `.claude/settings.json`:
 {
   "hooks": {
     "PreToolUse": [
-      { "matcher": "Write|Edit|MultiEdit", "hooks": [
+      { "matcher": "Write|Edit|MultiEdit|Bash", "hooks": [
         { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate.sh" } ] },
-      { "matcher": "Write|Edit|MultiEdit", "hooks": [
+      { "matcher": "Write|Edit|MultiEdit|Bash", "hooks": [
         { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-application-gate.sh" } ] }
     ],
     "PostToolUse": [
@@ -334,6 +346,7 @@ scripts/       validate-skills.mjs — checks skill length caps and reference in
                ship-gate-hook.sh — refuses git commit/push without a ship-gate receipt
                gauntlet-selftest.sh — 15 behavioural tests for the hook (runs on pre-push)
                gauntlet-survey.sh — what the hook would do in every repo under a directory
+               preflight.sh — everything that must pass before a release
 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
@@ -347,6 +360,9 @@ Skills live in `skills/<name>/SKILL.md`. Authoring conventions are in [CLAUDE.md
 - `SKILL.md` ≤ 350 lines; reference files ≤ 500 and need a `## Contents` TOC past 100 lines.
 - 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`.
+- Before any release, run `bash scripts/preflight.sh` — validator, self-tests, a check that the
+  hook scripts embedded in the CLI still match `scripts/`, detection against every repo under
+  `~/projects`, and that the version is ahead of the registry. Do not publish while it is red.
 - Changing `scripts/gauntlet.sh`? Run `bash scripts/gauntlet-selftest.sh` (also on `pre-push`),
   and run `bash scripts/gauntlet-survey.sh ~/projects` before releasing. Detection is where
   this hook keeps breaking, because real repos are shaped in ways invented test repos aren't —

package/lib/setup-hook.mjs

@@ -34,6 +34,56 @@ if [ -f "$MARKER" ]; then
   exit 0
 fi
 
+# Write|Edit|MultiEdit is not the only way to change a file. A session that edits
+# through \`python3 - <<'PY'\` in Bash walked past this gate entirely — twelve
+# source files, not one prompt — and some harnesses actively tell the model to
+# prefer Bash for edits. So Bash is gated too, but only for commands that can
+# write, and only until the gate is cleared once for the session.
+
+# Skills are about code. Blocking a plan document to ask how the React rules
+# apply is pure noise, and a repo full of PLAN_*.md hits it on every write.
+# Config files stay gated — skills do have rules about tsconfig and compose.
+PROSE_EXT='md|mdx|txt|rst|adoc|png|jpg|jpeg|gif|svg|webp|ico'
+CODE_EXT='ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|sql|sh|json|ya?ml|toml'
+
+TOOL=$(printf '%s' "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | sed 's/.*:"//; s/"$//')
+
+if [ "$TOOL" != "Bash" ]; then
+  # The structured tools name their target outright.
+  TARGET=$(printf '%s' "$INPUT" | grep -o '"file_path":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+  case "$TARGET" in
+    *.*) printf '%s' "$TARGET" | grep -qiE "\.($PROSE_EXT)$" && exit 0 ;;
+  esac
+fi
+if [ "$TOOL" = "Bash" ]; then
+  CMD=$(printf '%s' "$INPUT" | grep -o '"command":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+
+  # Never gate the command that clears the gate, or this deadlocks.
+  case "$CMD" in
+    *claude-skill-gate-*|*claude-skill-acked-*|*claude-skill-loaded-*) exit 0 ;;
+  esac
+
+  # /dev/null redirects are not file writes; drop them before looking for one.
+
+  # A command that names a prose file and no code file is writing prose.
+  if printf '%s' "$CMD" | grep -qiE "\.($PROSE_EXT)([^A-Za-z0-9]|$)" \
+     && ! printf '%s' "$CMD" | grep -qiE "\.($CODE_EXT)([^A-Za-z0-9]|$)"; then
+    exit 0
+  fi
+  STRIPPED=$(printf '%s' "$CMD" | sed 's![12]*>>*[[:space:]]*/dev/null!!g')
+  WRITES=""
+  case "$STRIPPED" in
+    *">"*|*"tee "*|*"sed -i"*|*"cp "*|*"mv "*|*"truncate "*|*"dd "*) WRITES=1 ;;
+  esac
+  # An interpreter given inline code or a heredoc can write anything, and the
+  # shell shows no redirect at all — this is the shape that got past the gate.
+  case "$CMD" in
+    *"<<"*|*python*" -c"*|*node*" -e"*|*perl*" -e"*|*ruby*" -e"*) WRITES=1 ;;
+  esac
+  [ -z "$WRITES" ] && exit 0
+fi
+
+
 cat <<EOF
 {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: skill evaluation required before file edits in this session.\\n\\nStep 1 — evaluate every available skill as ACTIVATE or SKIP with a one-line reason.\\n\\nStep 2 — you MUST take EXACTLY ONE of these tool actions to clear the gate. Listing skills in text is NOT enough; retrying the edit without doing one of these will be denied again:\\n  (a) If any skill is ACTIVATE → call Skill(name) for it. This auto-clears the gate.\\n  (b) If ALL skills are SKIP → run this Bash tool call: touch /tmp/claude-skill-gate-$SESSION_ID\\n\\nStep 3 — only after Step 2 completes, retry the file edit."}}
 EOF
@@ -90,6 +140,47 @@ if [ ! -f "/tmp/claude-skill-gate-$SESSION_ID" ]; then
   exit 0
 fi
 
+# Same reason as the loading gate: Bash can write files, and a heredoc into an
+# interpreter shows no redirect at all.
+
+# Skills are about code. Blocking a plan document to ask how the React rules
+# apply is pure noise, and a repo full of PLAN_*.md hits it on every write.
+# Config files stay gated — skills do have rules about tsconfig and compose.
+PROSE_EXT='md|mdx|txt|rst|adoc|png|jpg|jpeg|gif|svg|webp|ico'
+CODE_EXT='ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|sql|sh|json|ya?ml|toml'
+
+TOOL=$(printf '%s' "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | sed 's/.*:"//; s/"$//')
+
+if [ "$TOOL" != "Bash" ]; then
+  # The structured tools name their target outright.
+  TARGET=$(printf '%s' "$INPUT" | grep -o '"file_path":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+  case "$TARGET" in
+    *.*) printf '%s' "$TARGET" | grep -qiE "\.($PROSE_EXT)$" && exit 0 ;;
+  esac
+fi
+if [ "$TOOL" = "Bash" ]; then
+  CMD=$(printf '%s' "$INPUT" | grep -o '"command":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+  case "$CMD" in
+    *claude-skill-gate-*|*claude-skill-acked-*|*claude-skill-loaded-*) exit 0 ;;
+  esac
+
+  # A command that names a prose file and no code file is writing prose.
+  if printf '%s' "$CMD" | grep -qiE "\.($PROSE_EXT)([^A-Za-z0-9]|$)" \
+     && ! printf '%s' "$CMD" | grep -qiE "\.($CODE_EXT)([^A-Za-z0-9]|$)"; then
+    exit 0
+  fi
+  STRIPPED=$(printf '%s' "$CMD" | sed 's![12]*>>*[[:space:]]*/dev/null!!g')
+  WRITES=""
+  case "$STRIPPED" in
+    *">"*|*"tee "*|*"sed -i"*|*"cp "*|*"mv "*|*"truncate "*|*"dd "*) WRITES=1 ;;
+  esac
+  case "$CMD" in
+    *"<<"*|*python*" -c"*|*node*" -e"*|*perl*" -e"*|*ruby*" -e"*) WRITES=1 ;;
+  esac
+  [ -z "$WRITES" ] && exit 0
+fi
+
+
 # Collect every loaded-but-unacked skill so a single ack clears them all.
 UNACKED=""
 for marker in /tmp/claude-skill-loaded-$SESSION_ID-*; do
@@ -133,8 +224,11 @@ MSG="BLOCKED: loaded skills not yet applied to your work: $NAMES
 
 Before this Write/Edit, you must:
 
-1. For each skill listed above, state the specific rules that apply to the file you're about to write.
-2. State how your next write respects each rule.
+1. For each skill listed above, say whether it applies to the file you're about to
+   write. If it does not — a Python skill and a TypeScript file, say — write
+   "does not apply" and move on. Do not invent a connection.
+2. For the ones that do apply: state the specific rules that bear on this file, and
+   how your next write respects each.
 3. Then ack all of them in a single Bash tool call:
      $ACK_CMD
 
@@ -847,6 +941,18 @@ export async function writeGauntletConf(targetDir, testCommand) {
   return confPath;
 }
 
+// Register the entry, or CORRECT the one already there. Skipping when a hook of
+// this name exists leaves an existing install pinned to whatever matcher it was
+// first written with — which is how the skill gates kept watching only
+// Write|Edit|MultiEdit after they learned to cover Bash.
+function upsert(list, filename, entry) {
+  const existing = list.find((e) => e.hooks?.some((h) => h.command?.endsWith(filename)));
+  if (!existing) return list.push(entry);
+  if (entry.matcher === undefined) delete existing.matcher;
+  else existing.matcher = entry.matcher;
+  existing.hooks = entry.hooks;
+}
+
 export async function setupHook(targetDir = process.cwd()) {
   const resolved = resolve(targetDir);
   const hooksDir = join(resolved, ".claude", "hooks");
@@ -907,15 +1013,12 @@ export async function setupHook(targetDir = process.cwd()) {
   // Register PreToolUse gate.
   const gateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GATE_FILENAME}`;
   const gateEntry = {
-    matcher: "Write|Edit|MultiEdit",
+    matcher: "Write|Edit|MultiEdit|Bash",
     hooks: [{ type: "command", command: gateCommand }],
   };
 
   if (Array.isArray(settings.hooks.PreToolUse)) {
-    const exists = settings.hooks.PreToolUse.some((entry) =>
-      entry.hooks?.some((h) => h.command?.endsWith(GATE_FILENAME))
-    );
-    if (!exists) settings.hooks.PreToolUse.push(gateEntry);
+    upsert(settings.hooks.PreToolUse, GATE_FILENAME, gateEntry);
   } else {
     settings.hooks.PreToolUse = [gateEntry];
   }
@@ -923,13 +1026,10 @@ export async function setupHook(targetDir = process.cwd()) {
   // Register PreToolUse application gate (after the loading gate).
   const applicationCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${APPLICATION_GATE_FILENAME}`;
   const applicationEntry = {
-    matcher: "Write|Edit|MultiEdit",
+    matcher: "Write|Edit|MultiEdit|Bash",
     hooks: [{ type: "command", command: applicationCommand }],
   };
-  const applicationAlreadyRegistered = settings.hooks.PreToolUse.some((entry) =>
-    entry.hooks?.some((h) => h.command?.endsWith(APPLICATION_GATE_FILENAME))
-  );
-  if (!applicationAlreadyRegistered) settings.hooks.PreToolUse.push(applicationEntry);
+  upsert(settings.hooks.PreToolUse, APPLICATION_GATE_FILENAME, applicationEntry);
 
   // Register PreToolUse ship-gate receipt check on Bash.
   const shipGateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${SHIP_GATE_HOOK_FILENAME}`;
@@ -937,10 +1037,7 @@ export async function setupHook(targetDir = process.cwd()) {
     matcher: "Bash",
     hooks: [{ type: "command", command: shipGateCommand }],
   };
-  const shipGateRegistered = settings.hooks.PreToolUse.some((entry) =>
-    entry.hooks?.some((h) => h.command?.endsWith(SHIP_GATE_HOOK_FILENAME))
-  );
-  if (!shipGateRegistered) settings.hooks.PreToolUse.push(shipGateEntry);
+  upsert(settings.hooks.PreToolUse, SHIP_GATE_HOOK_FILENAME, shipGateEntry);
 
   // Register PostToolUse auto-mark on Skill.
   const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
@@ -950,10 +1047,7 @@ export async function setupHook(targetDir = process.cwd()) {
   };
 
   if (Array.isArray(settings.hooks.PostToolUse)) {
-    const exists = settings.hooks.PostToolUse.some((entry) =>
-      entry.hooks?.some((h) => h.command?.endsWith(AUTO_MARK_FILENAME))
-    );
-    if (!exists) settings.hooks.PostToolUse.push(autoMarkEntry);
+    upsert(settings.hooks.PostToolUse, AUTO_MARK_FILENAME, autoMarkEntry);
   } else {
     settings.hooks.PostToolUse = [autoMarkEntry];
   }
@@ -963,10 +1057,7 @@ export async function setupHook(targetDir = process.cwd()) {
   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);
+    upsert(settings.hooks.Stop, GAUNTLET_FILENAME, gauntletEntry);
   } else {
     settings.hooks.Stop = [gauntletEntry];
   }

package/package.json

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