@spardutti/claude-skills 2.52.0 → 2.53.1

package/README.md

@@ -36,7 +36,7 @@ npx @spardutti/claude-skills
 ```
 
 ```text
-  Claude Skills Installer v2.52.0
+  Claude Skills Installer v2.53.1
 
   ── Frontend ──────────────────────────────
   ◉ react              ◯ tanstack-query
@@ -139,7 +139,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 | `/handoff` | Write a handoff doc so a fresh session picks the work up — captures what auto-compaction loses: decisions made and rejected, dead ends already ruled out, why the tree is dirty, and the one next step |
 | `/lockdown` | Per-repo supply-chain hardening — detects the package managers, Dockerfiles, and CI in use, then guides you through and applies install-time, deploy, and pipeline hardening for npm/pnpm, pip/uv, Docker, and GitHub Actions |
 | `/add-rule` | Turn a mistake Claude keeps making into a check on every edit — a text rule with a bad and a good example from real code when a pattern can catch it, or a lesson shown only on the files it names when it needs judgment. Old hits go into a baseline and come back as "fix it if you can" notes; nothing is added to CLAUDE.md |
-| `/skill-report` | Which installed skills earn their place in this repo — every `/ship` skills audit is logged by a hook, and this tallies it: how often each skill applied, how often it caught a violation, and the rule it catches most. Names rules that break often enough to become a script check, and skills that never flag and may be dead weight |
+| `/skill-report` | Which installed skills earn their place in this repo — every `/ship` skills audit is logged by a hook, and this tallies it: how often each skill applied, how often it caught a violation, and the rule it catches most. Names rules that break often enough to become a script check, and skills that never flag and may be dead weight. Also ranks the rules the edit hook blocks most, by how many branches they hit — a rule Claude keeps writing wrong first is one its skill should state earlier |
 
 ## How It Works
 
@@ -198,6 +198,7 @@ scripts/       validate-skills.mjs — checks skill length caps and reference in
                version-check.sh — SessionStart nudge when a newer catalog is published
                skill-flags-record.sh — logs each /ship skills audit and /code-review; skill-report.mjs tallies them
                edit-check.sh — PostToolUse check on each edited file: line-limit.sh, lint-ratchet.mjs, .edit-rules.json
+               diary-check.mjs — run at the end of /ship; says when the diaries hold enough for /add-rule
                line-limit.sh — the 200-line ratchet, shared by the edit check, the ship gate and preflight
                gauntlet-selftest.sh — behavioural tests for the hooks (runs on pre-push)
                gauntlet-survey.sh — what the hook would do in every repo under a directory

package/hooks/diary-check.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { claudeDir, parseLine, readLines, verdictOf } from "./diary-lib.mjs";
+
+const DIR = claudeDir();
+const STAMP = resolve(DIR, "add-rule-checked");
+const TRUNKS = new Set(["main", "master", "dev", "develop", "development"]);
+const lines = (name) => readLines(resolve(DIR, name));
+
+function entries() {
+  const parsed = (name) => lines(name).map(parseLine).filter(Boolean);
+  const audits = parsed("skill-flags.jsonl").filter((e) => verdictOf(e.reply ?? "")?.violations?.length > 0);
+  const all = [...parsed("review-findings.jsonl"), ...parsed("gate-findings.jsonl"), ...audits];
+  return all.filter((e) => e.branch && !TRUNKS.has(e.branch));
+}
+
+function check() {
+  const since = existsSync(STAMP) ? readFileSync(STAMP, "utf8").trim() : "";
+  const fresh = entries().filter((e) => (e.ts ?? "") > since);
+  const branches = new Set(fresh.map((e) => e.branch));
+  if (branches.size < 2) return;
+  console.log(`${fresh.length} diary entries from ${branches.size} branches since /add-rule last looked (${since || "never"}). Offer only repeats with an entry after that.`);
+}
+
+const mode = process.argv[2];
+if (mode === "--mark") {
+  mkdirSync(DIR, { recursive: true });
+  writeFileSync(STAMP, `${new Date().toISOString().replace(/\.\d+Z$/, "Z")}\n`);
+} else if (mode === "--entries") {
+  for (const e of entries()) console.log(JSON.stringify(e));
+} else if (mode === undefined) {
+  check();
+} else {
+  console.error("usage: diary-check.mjs [--mark | --entries]");
+  process.exit(1);
+}

package/hooks/diary-lib.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+// Asks gate-config.sh's diary_dir, so the hooks that write the diaries and the scripts that
+// read them share one rule. argv[1] keeps a symlinked path the way bash sees it.
+export function claudeDir() {
+  const here = dirname(resolve(process.argv[1]));
+  const run = spawnSync("bash", ["-c", '. "$1/gate-config.sh" && diary_dir "$1"', "_", here], { encoding: "utf8" });
+  return run.stdout?.trim() || resolve(process.env.CLAUDE_PROJECT_DIR || process.cwd(), ".claude");
+}
+
+export function readLines(path) {
+  try {
+    return readFileSync(path, "utf-8").split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function parseLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+export function verdictOf(reply) {
+  try {
+    return JSON.parse(reply.slice(reply.indexOf("{"), reply.lastIndexOf("}") + 1));
+  } catch {
+    return null;
+  }
+}
+
+export function parseVerdict(line) {
+  const entry = parseLine(line);
+  const verdict = entry && verdictOf(entry.reply ?? "");
+  return verdict ? { model: entry.model, verdict } : null;
+}

package/hooks/edit-check.sh

@@ -15,21 +15,42 @@ if [ -f "$HERE/gate-config.sh" ]; then
 fi
 FAILS=""
 NOTES=""
+BLOCKED=""  # one rule id per line
 
-run() {
-  local out rc
+run() {  # run <rule id when it fails, or empty> <command...>
+  local id="$1" out rc
+  shift
   out=$("$@" 2>&1); rc=$?
   [ -z "$out" ] && return
-  if [ "$rc" = 0 ]; then NOTES="$NOTES$out"$'\n'; else FAILS="$FAILS$out"$'\n'; fi
+  if [ "$rc" = 0 ]; then NOTES="$NOTES$out"$'\n'; else FAILS="$FAILS$out"$'\n'; [ -n "$id" ] && BLOCKED="$BLOCKED$id"$'\n'; fi
 }
 
 # The gate measures length from the git root, so a monorepo subfolder shares its baseline.
 GIT_ROOT=$(git -C "$PROJECT_DIR" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$PROJECT_DIR")
-[ -f "$HERE/line-limit.sh" ] && run env LINE_LIMIT_ROOT="$GIT_ROOT" bash "$HERE/line-limit.sh" --file "$FILE"
-lint() { cd "$PROJECT_DIR" && node "$HERE/lint-ratchet.mjs" --file "$FILE"; }
-[ -f "$HERE/lint-ratchet.mjs" ] && command -v node >/dev/null && run lint
+[ -f "$HERE/line-limit.sh" ] && run line-limit env LINE_LIMIT_ROOT="$GIT_ROOT" bash "$HERE/line-limit.sh" --file "$FILE"
+if [ -f "$HERE/lint-ratchet.mjs" ] && command -v node >/dev/null; then
+  IDS=$(mktemp); trap 'rm -f "$IDS"' EXIT TERM
+  lint() { cd "$PROJECT_DIR" && LINT_RATCHET_BLOCKED="$IDS" node "$HERE/lint-ratchet.mjs" --file "$FILE"; }
+  run "" lint
+  BLOCKED="$BLOCKED$(cat "$IDS")"$'\n'
+fi
+
+# A rule that blocks on branch after branch is one its skill should teach up front.
+log_block() {
+  local rules diary
+  rules=$(printf '%s' "$BLOCKED" | sort -u | while IFS= read -r id; do
+    [ -n "$id" ] && printf '"%s",' "$(printf '%s' "$id" | json_string)"
+  done)
+  [ -n "$rules" ] || return 0
+  diary=$(diary_dir "$HERE")
+  mkdir -p "$diary"
+  printf '{"ts":"%s","branch":"%s","file":"%s","rules":[%s]}\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$(git -C "$(dirname "$FILE")" branch --show-current 2>/dev/null | json_string)" \
+    "$(printf '%s' "${FILE#"$PROJECT_DIR"/}" | json_string)" "${rules%,}" >> "$diary/edit-blocks.jsonl"
+}
 
 if [ -n "$FAILS" ]; then
+  declare -F json_string >/dev/null && declare -F diary_dir >/dev/null && log_block
   printf '%s%s' "$FAILS" "$NOTES" >&2
   exit 2
 fi

package/hooks/gate-config.sh

@@ -26,6 +26,12 @@ is_ignored() {
   return 1
 }
 
+# Every diary sits in the .claude that holds the hooks writing it, so a worktree or a
+# subfolder session still shares one set. Outside .claude/hooks (this repo's scripts/), the project.
+diary_dir() {  # diary_dir <script dir>
+  case "$1" in */.claude/hooks) dirname "$1" ;; *) printf '%s/.claude' "${CLAUDE_PROJECT_DIR:-$PWD}" ;; esac
+}
+
 json_string() {
   awk 'BEGIN { ORS = "" } {
     gsub(/\033\[[0-9;?]*[ -\/]*[@-~]/, "")

package/hooks/lint-ratchet.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, realpathSync } from "node:fs";
+import { appendFileSync, existsSync, realpathSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { brokenRules, loadEditRules, projectFiles, textFindings } from "./text-rules.mjs";
@@ -42,7 +42,7 @@ function eslint(rules, target) {
   const results = eslintOnce(rules, target);
   const core = rules.filter((r) => !r.id.includes("/"));
   if (results || core.length === rules.length) return { results, ran: rules };
-  return { results: eslintOnce(core, target), ran: core };
+  return { results: core.length ? eslintOnce(core, target) : [], ran: core };
 }
 
 function eslintOnce(rules, target) {
@@ -84,11 +84,15 @@ function baseline(only, newOnly) {
   const lint = existsSync(ESLINT) ? LINT.filter(pick) : [];
   const text = TEXT.filter(pick);
   if (newOnly && was.exists && lint.length + text.length === 0) return 0;
+  if (newOnly) console.log(`  Recording old code as baseline debt for: ${[...lint, ...text].map((r) => r.id).join(" ")}`);
   const { results, ran } = lint.length ? eslint(lint, ".") : { results: [], ran: [] };
   if (!results) {
     console.error("lint-ratchet: eslint gave no JSON; baseline not written.");
     return 1;
   }
+  const cannot = lint.filter((r) => !ran.includes(r)).map((r) => r.id);
+  if (cannot.length) console.log(`lint-ratchet: ESLint could not run ${cannot.join(" ")}; its plugin is not in the ESLint config.`);
+  if (newOnly && was.exists && ran.length + text.length === 0) return 0;
   const found = [...eslintFindings(results), ...projectFiles(ROOT).flatMap((rel) => textFindings(text, ROOT, rel))];
   const judged = new Set([...ran, ...text].map((r) => r.id));
   const n = writeBaseline(BASELINE, mergeBaseline(was, countBy(found), judged), new Set([...was.rules, ...judged]));
@@ -120,6 +124,7 @@ function checkFile(path) {
       console.log(`NOTE — ${rule.id} has no baseline yet, so its ${hits.length} finding(s) in ${rel} do not block. Run node ${SELF} --baseline-new to record old code.`);
     } else if (hits.length > before) {
       failed = 1;
+      if (process.env.LINT_RATCHET_BLOCKED) appendFileSync(process.env.LINT_RATCHET_BLOCKED, `${rule.id}\n`);
       console.log(`LINT — ${rel}: ${hits.length} × ${rule.id}, was ${before}. Fix the new one(s):`);
       for (const h of hits) console.log(`  ${rel}:${h.line}  ${h.message}`);
     } else if (hits.length > 0) {

package/hooks/ship-gate-structure.sh

@@ -119,8 +119,9 @@ gate_exit() {
   exec 1>&3 2>&4
   # A child left running (a dev server) can hold tee open forever; give it 2s, not a hang.
   for _ in 1 2 3 4 5 6 7 8 9 10; do [ -n "$TEE_PID" ] && kill -0 "$TEE_PID" 2>/dev/null || break; sleep 0.2; done
-  mkdir -p "$PROJECT_DIR/.claude"
+  local diary; diary=$(diary_dir "$HERE")
+  mkdir -p "$diary"
   printf '{"ts":"%s","branch":"%s","status":"FAIL","report":"%s"}\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
     "$(git branch --show-current 2>/dev/null | json_string)" "$(json_string < "$REPORT")" \
-    >> "$PROJECT_DIR/.claude/gate-findings.jsonl"
+    >> "$diary/gate-findings.jsonl"
 }

package/hooks/skill-flags-record.sh

@@ -19,9 +19,9 @@ TRANSCRIPT=$(printf '%s' "$INPUT" | grep -o '"agent_transcript_path":"[^"]*"' |
 MODEL=""
 [ -f "$TRANSCRIPT" ] && MODEL=$(grep -o '"model":"[^"]*"' "$TRANSCRIPT" | tail -1 | sed 's/.*:"//; s/"$//')
 
-. "$SCRIPT_DIR/gate-config.sh" 2>/dev/null || json_string() { tr -cd '[:alnum:]/._-'; }
+. "$SCRIPT_DIR/gate-config.sh" 2>/dev/null || exit 0
 BRANCH=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null | json_string)
 printf '{"ts":"%s","branch":"%s","model":"%s","reply":"%s"}\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$BRANCH" "$MODEL" "$REPLY" \
-  >> "$PROJECT_DIR/.claude/$LOG"
+  >> "$(diary_dir "$SCRIPT_DIR")/$LOG"
 
 exit 0

package/hooks/skill-report.mjs

@@ -1,18 +1,10 @@
 #!/usr/bin/env node
-// Prints, per skill, how often the /ship skills audit applied it and flagged a violation.
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+import { statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { claudeDir, parseLine, parseVerdict, readLines } from "./diary-lib.mjs";
 
-const DEFAULT_LOG = fileURLToPath(new URL("../skill-flags.jsonl", import.meta.url));
-
-function parseVerdict(line) {
-  try {
-    const { model, reply } = JSON.parse(line);
-    return { model, verdict: JSON.parse(reply.slice(reply.indexOf("{"), reply.lastIndexOf("}") + 1)) };
-  } catch {
-    return null;
-  }
-}
+const given = process.argv[2] && resolve(process.argv[2]);
+const DIR = !given ? claudeDir() : statSync(given, { throwIfNoEntry: false })?.isFile() ? dirname(given) : given;
 
 function tally(lines) {
   const skills = new Map();
@@ -52,10 +44,28 @@ function render({ skills, models, unreadable }) {
   return out.join("\n");
 }
 
-let text = "";
-try {
-  text = readFileSync(process.argv[2] ?? DEFAULT_LOG, "utf-8");
-} catch {
-  // no log yet
+function tallyBlocks(lines) {
+  const rules = new Map();
+  for (const line of lines) {
+    const entry = parseLine(line);
+    const ids = Array.isArray(entry?.rules) ? entry.rules : (entry?.rules ?? "").split(" ").filter(Boolean);
+    for (const id of ids) {
+      const r = rules.get(id) ?? { count: 0, branches: new Set() };
+      r.count += 1;
+      if (entry.branch) r.branches.add(entry.branch);
+      rules.set(id, r);
+    }
+  }
+  return rules;
+}
+
+function renderBlocks(rules) {
+  if (rules.size === 0) return "";
+  const rows = [...rules].sort((a, b) => b[1].branches.size - a[1].branches.size || b[1].count - a[1].count);
+  const width = Math.max(22, ...rows.map(([id]) => id.length));
+  const line = ([id, r]) => `${id.padEnd(width)}  ${String(r.count).padStart(5)}  ${String(r.branches.size).padStart(8)}`;
+  return ["", `${"edit-hook blocks".padEnd(width)}  count  branches`, ...rows.map(line)].join("\n");
 }
-console.log(render(tally(text.split("\n").filter(Boolean))));
+
+const audits = tally(readLines(resolve(DIR, "skill-flags.jsonl")));
+console.log(render(audits) + renderBlocks(tallyBlocks(readLines(resolve(DIR, "edit-blocks.jsonl")))));

package/hooks/text-rules.mjs

@@ -39,6 +39,7 @@ function walk(root, dir) {
 export function brokenRules(rules) {
   const broken = [];
   for (const r of rules) {
+    if (/\s/.test(r.id ?? "")) broken.push(`${r.id}: its id has whitespace, which .lint-baseline cannot store`);
     if (matchLines(r, r.bad ?? "").length === 0) broken.push(`${r.id}: its bad example is not caught`);
     if (matchLines(r, r.good ?? "").length > 0) broken.push(`${r.id}: its good example is flagged`);
   }

package/lib/setup-hook.mjs

@@ -24,6 +24,7 @@ import { homedir } from "node:os";
 //   version-check.sh          SessionStart — a line when a newer catalog exists
 //   skill-flags-record.sh     SubagentStop — logs each skills-audit verdict
 //   skill-report.mjs          read by /skill-report — tallies that log
+//   diary-check.mjs           run by /ship — says when /add-rule has repeats to look at
 //   edit-check.sh             PostToolUse — line-limit.sh, lint-ratchet.mjs and
 //                             text-rules.mjs on each edited file
 
@@ -45,6 +46,8 @@ const LINE_LIMIT_FILENAME = "line-limit.sh";
 const LINT_RATCHET_FILENAME = "lint-ratchet.mjs";
 const TEXT_RULES_FILENAME = "text-rules.mjs";
 const RATCHET_BASELINE_FILENAME = "ratchet-baseline.mjs";
+const DIARY_CHECK_FILENAME = "diary-check.mjs";
+const DIARY_LIB_FILENAME = "diary-lib.mjs";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -118,9 +121,8 @@ function writeBaselines(dir, hooksDir) {
     spawnSync("bash", [join(hooksDir, LINE_LIMIT_FILENAME), "--baseline"],
       { cwd: root, env: { ...process.env, LINE_LIMIT_ROOT: root }, stdio: "ignore" });
   }
-  console.log("  Recording old code as baseline debt (runs ESLint once per new rule)...");
   spawnSync(process.execPath, [join(hooksDir, LINT_RATCHET_FILENAME), "--baseline-new"],
-    { cwd: dir, stdio: "ignore", timeout: 600_000 });
+    { cwd: dir, stdio: ["ignore", "inherit", "ignore"], timeout: 600_000 });
 }
 
 export async function setupHook(targetDir = process.cwd()) {
@@ -148,6 +150,8 @@ export async function setupHook(targetDir = process.cwd()) {
     LINT_RATCHET_FILENAME,
     TEXT_RULES_FILENAME,
     RATCHET_BASELINE_FILENAME,
+    DIARY_CHECK_FILENAME,
+    DIARY_LIB_FILENAME,
   ]) {
     const dest = join(hooksDir, name);
     await writeFile(dest, await readHookSource(name), { mode: 0o755 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.52.0",
+  "version": "2.53.1",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "claude-skills": "bin/cli.mjs"
   },
   "scripts": {
-    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/gate-config.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh ../scripts/skill-flags-record.sh ../scripts/skill-report.mjs ../scripts/edit-check.sh ../scripts/line-limit.sh ../scripts/lint-ratchet.mjs ../scripts/text-rules.mjs ../scripts/ratchet-baseline.mjs hooks/",
+    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/gate-config.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh ../scripts/skill-flags-record.sh ../scripts/skill-report.mjs ../scripts/edit-check.sh ../scripts/line-limit.sh ../scripts/lint-ratchet.mjs ../scripts/text-rules.mjs ../scripts/ratchet-baseline.mjs ../scripts/diary-check.mjs ../scripts/diary-lib.mjs hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {