@spardutti/claude-skills 2.51.3 → 2.52.0

package/README.md

@@ -36,7 +36,7 @@ npx @spardutti/claude-skills
 ```
 
 ```text
-  Claude Skills Installer v2.51.2
+  Claude Skills Installer v2.52.0
 
   ── Frontend ──────────────────────────────
   ◉ react              ◯ tanstack-query
@@ -138,6 +138,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 | `/optimize` | Make one measured job faster without changing what it proves — fixes a benchmark and a result that must not move, sends 4 read-only subagents to find suspects, then changes one thing per round with a prediction written first, keeping only what beats the noise. Profiles after every wrong prediction, reruns before judging a result that flipped, and ends by writing the cause as a skill rule for you |
 | `/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 |
 
 ## How It Works
@@ -195,7 +196,9 @@ scripts/       validate-skills.mjs — checks skill length caps and reference in
                ship-gate.sh — /ship's file-length, folder-structure and mutation checks, behind an exit code
                ship-gate-hook.sh — refuses gh pr create/merge without a ship-gate receipt
                version-check.sh — SessionStart nudge when a newer catalog is published
-               skill-flags-record.sh — logs each /ship skills-audit verdict; skill-report.mjs tallies it
+               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
+               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
                preflight.sh — everything that must pass before a release

package/hooks/edit-check.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+INPUT=$(cat)
+
+FILE=$(printf '%s' "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
+       | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+[ -z "$FILE" ] && exit 0
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+if [ -f "$HERE/gate-config.sh" ]; then
+  . "$HERE/gate-config.sh"
+  load_gauntlet_conf "$PROJECT_DIR/.claude/gauntlet.conf" "$HERE/../gauntlet.conf"
+  is_ignored "${FILE#"$PROJECT_DIR"/}" && exit 0
+fi
+FAILS=""
+NOTES=""
+
+run() {
+  local out rc
+  out=$("$@" 2>&1); rc=$?
+  [ -z "$out" ] && return
+  if [ "$rc" = 0 ]; then NOTES="$NOTES$out"$'\n'; else FAILS="$FAILS$out"$'\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
+
+if [ -n "$FAILS" ]; then
+  printf '%s%s' "$FAILS" "$NOTES" >&2
+  exit 2
+fi
+if [ -n "$NOTES" ] && declare -F json_string >/dev/null; then
+  printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s"}}\n' "$(printf '%s' "$NOTES" | json_string)"
+fi
+exit 0

package/hooks/gate-config.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+GAUNTLET_MAX_LINES=200
+GAUNTLET_MUTATE=""
+GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|gd"
+GAUNTLET_IGNORE_EXT="md|mdx|txt|rst|adoc|jsonc?|ya?ml|toml|lock|cfg|ini|env|csv|tsv|sql|html|css|scss|svg|png|jpg|jpeg|gif|webp|ico|pdf|woff2?|ttf|otf|mp3|mp4|wav|zip|gz|tres|tscn|import|godot"
+GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx */hooks/use-mobile.ts */*.config.*"
+# Components are length-checked but not mutated: their mutants are class names and JSX, not
+# behaviour. Override in .claude/gauntlet.conf to mutate them too.
+GAUNTLET_NO_MUTATE='\.(tsx|jsx)$'
+
+load_gauntlet_conf() {  # load_gauntlet_conf <project conf> <fallback conf>
+  [ -n "${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ] && . "$HOME/.claude/gauntlet.conf"
+  local conf="$1"; [ -f "$conf" ] || conf="$2"
+  if [ -f "$conf" ]; then . "$conf"; fi
+}
+
+# set -f: unquoted, the list is glob-expanded before it is split, and */components/ui/*.tsx
+# expanded into the very path it should match.
+is_ignored() {
+  set -f
+  for pat in $GAUNTLET_IGNORE_FILES; do
+    case "/$1" in $pat) set +f; return 0 ;; esac
+  done
+  set +f
+  return 1
+}
+
+json_string() {
+  awk 'BEGIN { ORS = "" } {
+    gsub(/\033\[[0-9;?]*[ -\/]*[@-~]/, "")
+    gsub(/[\001-\010\013-\037\177]/, "")  # JSON forbids raw control characters
+    gsub(/\\/, "\\\\"); gsub(/"/, "\\\""); gsub(/\t/, "\\t")
+    if (NR > 1) print "\\n"
+    print
+  }'
+}

package/hooks/line-limit.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+. "$HERE/gate-config.sh" || exit 1
+ROOT="$(cd "${LINE_LIMIT_ROOT:-$(git -C "$HERE" rev-parse --show-toplevel 2>/dev/null || echo "$HERE/..")}" && pwd -P)"
+load_gauntlet_conf "$ROOT/.claude/gauntlet.conf" "$HERE/../gauntlet.conf"
+LIMIT=$GAUNTLET_MAX_LINES
+BASELINE="$ROOT/.line-limit-baseline"
+SELF="${HERE#"$ROOT"/}/line-limit.sh"
+if ! [ "$LIMIT" -gt 0 ] 2>/dev/null; then
+  [ "${1:-}" = "--file" ] || echo "LINE LIMIT — off (GAUNTLET_MAX_LINES=$LIMIT)"
+  exit 0
+fi
+
+is_code() {
+  local ext="\\.($GAUNTLET_SOURCE_EXT|sh)$" skip="(^|/)node_modules/|^\\.claude/"
+  [[ $1 =~ $ext ]] && ! [[ $1 =~ $skip ]] && ! is_ignored "$1"
+}
+
+# Paths are kept relative to ROOT so the baseline is portable between clones.
+files() {
+  { git -C "$ROOT" ls-files --cached --others --exclude-standard 2>/dev/null \
+    || (cd "$ROOT" && find . -type f -not -path './.git/*' | sed 's|^\./||'); } \
+    | while IFS= read -r f; do is_code "$f" && [ -f "$ROOT/$f" ] && printf '%s/%s\n' "$ROOT" "$f"; done | sort
+}
+
+counts() {
+  while IFS= read -r f; do
+    printf '%s %s\n' "$(wc -l < "$f" | tr -d ' ')" "${f#"$ROOT"/}"
+  done
+}
+
+ONE=""
+if [ "${1:-}" = "--file" ]; then
+  ONE="$(cd "$(dirname -- "${2:-.}")" 2>/dev/null && pwd -P)/$(basename -- "${2:-.}")"
+  REL="${ONE#"$ROOT"/}"
+  [ "$REL" != "$ONE" ] && [ -f "$ONE" ] && is_code "$REL" || exit 0
+  git -C "$ROOT" check-ignore -q -- "$REL" 2>/dev/null && exit 0
+  NOW=$(printf '%s\n' "$ONE" | counts)
+else
+  NOW=$(files | counts)
+fi
+
+# On an existing baseline this only banks: an entry may drop or go, never appear or grow.
+if [ "${1:-}" = "--baseline" ]; then
+  if [ -f "$BASELINE" ]; then
+    printf '%s\n' "$NOW" | awk -v lim="$LIMIT" '{ n = $1; p = $0; sub(/^[^ ]+ /, "", p) }
+      NR == FNR { was[p] = n; next } (p in was) && n > lim { print (n < was[p] ? n : was[p]), p }' "$BASELINE" - > "$BASELINE.tmp" \
+      && mv "$BASELINE.tmp" "$BASELINE"
+  else
+    printf '%s\n' "$NOW" | awk -v lim="$LIMIT" '$1 > lim' > "$BASELINE"
+  fi
+  n=$(wc -l < "$BASELINE" | tr -d ' ')
+  echo "line-limit: baseline written — $n file(s) over $LIMIT accepted as debt."
+  echo "Commit $BASELINE. From here they may shrink but never grow."
+  exit 0
+fi
+
+FAILED=0
+NEW_OVER=""
+GREW=""
+SHRANK=""
+
+while read -r n f; do
+  [ -z "$f" ] && continue
+  was=$(awk -v p="$f" '{ n = $1; sub(/^[^ ]+ /, "") } $0 == p { print n }' "$BASELINE" 2>/dev/null)
+  if [ -z "$was" ]; then
+    # Not accepted debt, so the real limit applies.
+    if [ "$n" -gt "$LIMIT" ]; then
+      NEW_OVER="$NEW_OVER  $f — $n lines (limit $LIMIT)
+"
+      FAILED=1
+    fi
+  elif [ "$n" -gt "$was" ]; then
+    GREW="$GREW  $f — $n lines, was $was
+"
+    FAILED=1
+  elif [ "$n" -lt "$was" ]; then
+    SHRANK="$SHRANK  $f — $n lines, was $was
+"
+  elif [ -n "$ONE" ]; then
+    echo "LINE LIMIT — $f is $n lines, over $LIMIT (old debt). Split it if this change allows."
+  fi
+done <<EOF
+$NOW
+EOF
+
+# A file in the baseline that no longer exists is debt that was paid by deleting
+# or renaming it. Report it so the baseline can be trimmed, never fail on it.
+GONE=""
+if [ -z "$ONE" ] && [ -f "$BASELINE" ]; then
+  while read -r was f; do
+    [ -z "$f" ] && continue
+    [ -f "$ROOT/$f" ] || GONE="$GONE  $f — gone (was $was lines)
+"
+  done < "$BASELINE"
+fi
+
+if [ -n "$NEW_OVER" ]; then
+  echo "LINE LIMIT — over $LIMIT and not accepted debt:"
+  printf '%s' "$NEW_OVER"
+  echo "  Split them."
+fi
+
+if [ -n "$GREW" ]; then
+  echo "LINE LIMIT — accepted debt that grew:"
+  printf '%s' "$GREW"
+  echo "  The baseline is a ceiling, not a licence. Take the addition elsewhere."
+fi
+
+if [ -n "$SHRANK" ] || [ -n "$GONE" ]; then
+  echo "LINE LIMIT — debt paid down (not a failure):"
+  [ -n "$SHRANK" ] && printf '%s' "$SHRANK"
+  [ -n "$GONE" ] && printf '%s' "$GONE"
+  echo "  Run: bash $SELF --baseline   to bank it."
+fi
+
+if [ "$FAILED" = 0 ] && [ -z "$SHRANK" ] && [ -z "$GONE" ] && [ -z "$ONE" ]; then
+  over=$(wc -l < "$BASELINE" 2>/dev/null | tr -d ' ')
+  echo "LINE LIMIT — ok. ${over:-0} file(s) of accepted debt, none grew."
+fi
+
+exit $FAILED

package/hooks/lint-ratchet.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { 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";
+import { mergeBaseline, readBaseline, writeBaseline } from "./ratchet-baseline.mjs";
+
+const ROOT = realpathSync(process.cwd());
+const BASELINE = resolve(ROOT, ".lint-baseline");
+const ESLINT = resolve(ROOT, "node_modules/.bin/eslint");
+const SELF = relative(ROOT, fileURLToPath(import.meta.url));
+let TEXT = [];
+let LESSONS = [];
+
+const isTest = (f) => /\.(test|spec)\.|(^|\/)(test|tests|__tests__)\//.test(f);
+
+// A test's describe() callback is one long function by design, and React
+// components are left unannotated by convention, so each rule names its files.
+const RULES = [
+  {
+    id: "max-lines-per-function",
+    skill: "code-structure",
+    config: ["error", { max: 30, skipBlankLines: true, skipComments: true }],
+    applies: (f) => /\.(m?js|jsx|ts|tsx)$/.test(f) && !isTest(f),
+  },
+  {
+    id: "@typescript-eslint/explicit-module-boundary-types",
+    skill: "typescript-best-practices",
+    config: "error",
+    applies: (f) => /\.ts$/.test(f) && !isTest(f),
+  },
+];
+
+// skills/ is where this repo keeps the skills it ships; a consumer has them under .claude/skills/.
+const hasSkill = (name) =>
+  existsSync(resolve(ROOT, ".claude/skills", name, "SKILL.md")) || existsSync(resolve(ROOT, "skills", name, "SKILL.md"));
+const LINT = RULES.filter((r) => hasSkill(r.skill));
+
+// A plugin rule the project's config cannot load makes ESLint crash, so retry without it.
+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 };
+}
+
+function eslintOnce(rules, target) {
+  const args = ["-f", "json"];
+  for (const r of rules) args.push("--rule", JSON.stringify({ [r.id]: r.config }));
+  args.push(target);
+  const run = spawnSync(ESLINT, args, { cwd: ROOT, encoding: "utf8", maxBuffer: 1 << 28 });
+  try {
+    return JSON.parse(run.stdout);
+  } catch {
+    return null;
+  }
+}
+
+function eslintFindings(results) {
+  const out = [];
+  for (const file of results) {
+    const rel = relative(ROOT, file.filePath);
+    for (const m of file.messages) {
+      const rule = RULES.find((r) => r.id === m.ruleId);
+      if (rule && rule.applies(rel)) out.push({ rel, rule: m.ruleId, line: m.line, message: m.message });
+    }
+  }
+  return out;
+}
+
+function countBy(list) {
+  const counts = new Map();
+  for (const f of list) {
+    const key = `${f.rule} ${f.rel}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function baseline(only, newOnly) {
+  const was = readBaseline(BASELINE);
+  const pick = (r) => (only ? r.id === only : !newOnly || !was.rules.has(r.id));
+  const lint = existsSync(ESLINT) ? LINT.filter(pick) : [];
+  const text = TEXT.filter(pick);
+  if (newOnly && was.exists && lint.length + text.length === 0) return 0;
+  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 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]));
+  console.log(`lint-ratchet: baseline written — ${n} rule/file pair(s) accepted as debt.`);
+  return 0;
+}
+
+function scan(rel) {
+  const lint = existsSync(ESLINT) ? LINT.filter((r) => r.applies(rel)) : [];
+  const { results, ran } = lint.length ? eslint(lint, rel) : { results: null, ran: [] };
+  const text = TEXT.filter((r) => r.applies(rel));
+  return {
+    rules: [...(results ? ran : []), ...text],
+    found: [...(results ? eslintFindings(results) : []), ...textFindings(text, ROOT, rel)],
+  };
+}
+
+function checkFile(path) {
+  const abs = resolve(ROOT, path);
+  const rel = relative(ROOT, existsSync(abs) ? realpathSync(abs) : abs);
+  if (rel.startsWith("..") || spawnSync("git", ["check-ignore", "-q", "--", rel], { cwd: ROOT }).status === 0) return 0;
+  const { rules, found } = scan(rel);
+  const was = readBaseline(BASELINE);
+  let failed = 0;
+  for (const rule of rules) {
+    const hits = found.filter((f) => f.rule === rule.id);
+    const before = was.counts.get(`${rule.id} ${rel}`) ?? 0;
+    if (hits.length > before && !was.rules.has(rule.id)) {
+      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;
+      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) {
+      console.log(`NOTE — ${rel} has ${hits.length} old ${rule.id} finding(s). Fix them if this change allows.`);
+    } else if (before > 0) {
+      console.log(`NOTE — ${rel}: ${rule.id} debt paid down. Run node ${SELF} --baseline ${rule.id} to bank it.`);
+    }
+  }
+  for (const lesson of LESSONS.filter((l) => l.applies(rel))) console.log(`LESSON — ${lesson.message}`);
+  return failed;
+}
+
+function selftest() {
+  const broken = brokenRules(TEXT);
+  for (const b of broken) console.log(`RULE — ${b}`);
+  if (broken.length === 0) console.log(`lint-ratchet: ${TEXT.length} text rule(s) catch their bad example and pass their good one.`);
+  return broken.length ? 1 : 0;
+}
+
+function main(mode, arg) {
+  ({ text: TEXT, lessons: LESSONS } = loadEditRules(ROOT));
+  if (mode === "--baseline") return baseline(arg, false);
+  if (mode === "--baseline-new") return baseline(undefined, true);
+  if (mode === "--file") return checkFile(arg ?? "");
+  if (mode === "--selftest") return selftest();
+  console.error("usage: lint-ratchet.mjs --baseline [rule-id] | --baseline-new | --file <path> | --selftest");
+  return 1;
+}
+
+const [mode, arg] = process.argv.slice(2);
+try {
+  process.exit(main(mode, arg));
+} catch (err) {
+  console.log(`NOTE — .edit-rules.json could not be used, so its rules did not run: ${err.message}`);
+  process.exit(mode === "--file" ? 0 : 1);
+}

package/hooks/ratchet-baseline.mjs

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+const ruleOf = (key) => key.split(" ")[0];
+
+// "# rules:" names every rule baselined so far, since a rule with no hits leaves no other line.
+export function readBaseline(path) {
+  const counts = new Map();
+  const rules = new Set();
+  if (!existsSync(path)) return { counts, rules, exists: false };
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.startsWith("# rules:")) {
+      for (const id of line.slice(8).trim().split(/\s+/).filter(Boolean)) rules.add(id);
+      continue;
+    }
+    const m = line.match(/^(\d+) (\S+) (.+)$/);
+    if (!m) continue;
+    counts.set(`${m[2]} ${m[3]}`, Number(m[1]));
+    rules.add(m[2]);
+  }
+  return { counts, rules, exists: true };
+}
+
+// A rule baselined before only banks: its debt may drop or go, never appear or grow.
+export function mergeBaseline(was, now, judged) {
+  const merged = new Map([...was.counts].filter(([key]) => !judged.has(ruleOf(key))));
+  for (const [key, n] of was.counts) {
+    if (judged.has(ruleOf(key)) && now.has(key)) merged.set(key, Math.min(n, now.get(key)));
+  }
+  for (const [key, n] of now) {
+    if (judged.has(ruleOf(key)) && !was.rules.has(ruleOf(key))) merged.set(key, n);
+  }
+  return merged;
+}
+
+export function writeBaseline(path, merged, rules) {
+  const lines = [...merged].map(([key, n]) => `${n} ${key}`).sort();
+  writeFileSync(path, [`# rules: ${[...rules].sort().join(" ")}`, ...lines, ""].join("\n"));
+  return lines.length;
+}

package/hooks/ship-gate-files.sh

@@ -20,7 +20,7 @@ changed_tests() {  # changed_tests <family>
 files_context() {  # files_context <owner> <owned files>
   fam=$(family_of "$1/.")
   { printf '%s\n' "$PROJECT_DIR" "$1" "$(git rev-parse "$BASE" 2>/dev/null)"
-    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh"
+    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh" "$HERE/gate-config.sh" "$HERE/line-limit.sh"
     printf '%s\n' "$CHANGED" | grep -vE '\.(md|mdx|txt|rst|adoc)$' | grep -vE "$TEST_RE" \
       | grep -vxF -f <(printf '%s\n' "$2") | while IFS= read -r f; do
       [ -n "$f" ] || continue

package/hooks/ship-gate-projects.sh

@@ -139,7 +139,7 @@ project_key() {  # project_key <owner> <tool>
   fam=$(family_of "$1/.")
   { printf '%s\n' "$PROJECT_DIR" "$1" "$2" "$(git rev-parse "$BASE" 2>/dev/null)" \
       "$GAUNTLET_NO_MUTATE" "$GAUNTLET_IGNORE_FILES"
-    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh"
+    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh" "$HERE/gate-config.sh" "$HERE/line-limit.sh"
     printf '%s\n' "$CHANGED" | grep -vE '\.(md|mdx|txt|rst|adoc)$' | while IFS= read -r f; do
       [ -n "$f" ] || continue
       case "$(family_of "$f")" in "$fam"|any) printf '%s\n' "$f"; [ -f "$f" ] && cat "$f" ;; esac

package/hooks/ship-gate-structure.sh

@@ -107,6 +107,20 @@ structure_fail() {
 # An agent that pipes the gate through `tail` cuts the findings off; the last line still says where they are.
 gate_report() {
   REPORT="/tmp/claude-shipgate-$1.log"
-  exec > >(tee "$REPORT") 2>&1
-  trap 'echo "ship-gate: full output in $REPORT"' EXIT
+  exec 3>&1 4>&2 > >(tee "$REPORT") 2>&1
+  TEE_PID=${!:-}  # bash before 4.4 does not set $! for process substitution
+  trap 'gate_exit $?' EXIT
+}
+
+# A FAIL goes to the diary /add-rule reads, so a test gap the gate keeps finding can become a rule.
+gate_exit() {
+  echo "ship-gate: full output in $REPORT"
+  [ "$1" = 1 ] || return 0
+  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"
+  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"
 }

package/hooks/ship-gate.sh

@@ -47,7 +47,7 @@
 set -uo pipefail
 
 HERE=$(cd "$(dirname "$0")" && pwd)
-. "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" && . "$HERE/ship-gate-files.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
+. "$HERE/gate-config.sh" && . "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" && . "$HERE/ship-gate-files.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
 
 MODE=""
 case "${1:-}" in
@@ -73,20 +73,7 @@ if [ -n "$ROOT" ]; then
   PROJECT_DIR="$ROOT"
 fi
 
-GAUNTLET_MAX_LINES=200
-GAUNTLET_MUTATE=""
-GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|gd"
-GAUNTLET_IGNORE_EXT="md|mdx|txt|rst|adoc|jsonc?|ya?ml|toml|lock|cfg|ini|env|csv|tsv|sql|html|css|scss|svg|png|jpg|jpeg|gif|webp|ico|pdf|woff2?|ttf|otf|mp3|mp4|wav|zip|gz|tres|tscn|import|godot"
-GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx */hooks/use-mobile.ts */*.config.*"
-# Length-checked and skill-audited like everything else, but not mutated.
-# Mutation pays on logic and burns time on presentation: a component's mutants
-# are class names, copy and JSX shape, none of which is behaviour, and one
-# session spent an evening killing them. Logic that lives inside a component is
-# logic that wants extracting — which the 200-line rule already pushes toward.
-# Override in .claude/gauntlet.conf to mutate components too.
-GAUNTLET_NO_MUTATE='\.(tsx|jsx)$'
-[ -n "${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ] && . "$HOME/.claude/gauntlet.conf"
-CONF=.claude/gauntlet.conf; [ -f "$CONF" ] || CONF="$HERE/../gauntlet.conf"; [ -f "$CONF" ] && . "$CONF"
+load_gauntlet_conf .claude/gauntlet.conf "$HERE/../gauntlet.conf"
 
 # ------------------------------------------------------------------- the scope
 BASE="${1:-}"
@@ -135,17 +122,6 @@ SOURCED=$(printf '%s\n' "$CHANGED" | grep -E "\.($GAUNTLET_SOURCE_EXT)$" \
 # uncovered line started failing the gate: vitest.config.ts has no tests, will
 # never have tests, and is not a thing anyone writes a test for. Left in, every
 # diff that touches a config reports findings nobody can close.
-# set -f matters: an unquoted list is glob-expanded before it is split, so
-# */components/ui/*.tsx turned itself into the very path it was meant to match
-# and then matched nothing.
-is_ignored() {
-  set -f
-  for pat in $GAUNTLET_IGNORE_FILES; do
-    case "/$1" in $pat) set +f; return 0 ;; esac
-  done
-  set +f
-  return 1
-}
 FILES=$(printf '%s\n' "$SOURCED" | while IFS= read -r f; do
           [ -n "$f" ] && ! is_ignored "$f" && printf '%s\n' "$f"
         done)
@@ -190,7 +166,7 @@ if [ "$GAUNTLET_MAX_LINES" -gt 0 ]; then
   while IFS= read -r f; do
     n=$(wc -l < "$f")
     [ "$n" -gt "$LARGEST" ] && LARGEST=$n
-    [ "$n" -gt "$GAUNTLET_MAX_LINES" ] && OVER="$OVER  $f — $n lines (limit $GAUNTLET_MAX_LINES)
+    out=$(LINE_LIMIT_ROOT="$PWD" bash "$HERE/line-limit.sh" --file "$f") || OVER="$OVER$(printf '%s\n' "$out" | grep -E '^  .* — [0-9]+ lines')
 "
   done <<< "$FILES"
 fi

package/hooks/skill-flags-record.sh

@@ -1,10 +1,10 @@
 #!/bin/bash
-# SubagentStop: appends each gauntlet-skills verdict to .claude/skill-flags.jsonl.
 
 INPUT=$(cat | tr -d '\n')
 
 case "$INPUT" in
-  *'"agent_type":"gauntlet-skills"'*) ;;
+  *'"agent_type":"gauntlet-skills"'*) LOG=skill-flags.jsonl ;;
+  *'\"failure_scenario\"'*) LOG=review-findings.jsonl ;;
   *) exit 0 ;;
 esac
 
@@ -19,7 +19,9 @@ TRANSCRIPT=$(printf '%s' "$INPUT" | grep -o '"agent_transcript_path":"[^"]*"' |
 MODEL=""
 [ -f "$TRANSCRIPT" ] && MODEL=$(grep -o '"model":"[^"]*"' "$TRANSCRIPT" | tail -1 | sed 's/.*:"//; s/"$//')
 
-printf '{"ts":"%s","model":"%s","reply":"%s"}\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$MODEL" "$REPLY" \
-  >> "$PROJECT_DIR/.claude/skill-flags.jsonl"
+. "$SCRIPT_DIR/gate-config.sh" 2>/dev/null || json_string() { tr -cd '[:alnum:]/._-'; }
+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"
 
 exit 0

package/hooks/text-rules.mjs

@@ -0,0 +1,46 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function loadEditRules(root) {
+  const file = resolve(root, ".edit-rules.json");
+  const { text = [], lessons = [] } = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  const withFiles = (r) => ({ ...r, applies: (f) => new RegExp(r.files).test(f) });
+  return { text: text.map(withFiles), lessons: lessons.map(withFiles) };
+}
+
+function matchLines(rule, content) {
+  const re = new RegExp(rule.pattern, `g${(rule.flags ?? "").replace("g", "")}`);
+  return [...content.matchAll(re)].map((m) => content.slice(0, m.index).split("\n").length);
+}
+
+export function textFindings(rules, root, rel) {
+  const own = rules.filter((r) => r.applies(rel));
+  const path = resolve(root, rel);
+  if (own.length === 0 || !existsSync(path)) return [];
+  const content = readFileSync(path, "utf8");
+  return own.flatMap((r) => matchLines(r, content).map((line) => ({ rel, rule: r.id, line, message: r.message })));
+}
+
+export function projectFiles(root) {
+  const args = ["ls-files", "--cached", "--others", "--exclude-standard"];
+  const run = spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 1 << 28 });
+  return run.status === 0 ? run.stdout.split("\n").filter(Boolean) : walk(root, "");
+}
+
+function walk(root, dir) {
+  return readdirSync(resolve(root, dir), { withFileTypes: true }).flatMap((e) => {
+    if (e.name === "node_modules" || e.name === ".git") return [];
+    const rel = dir ? `${dir}/${e.name}` : e.name;
+    return e.isDirectory() ? walk(root, rel) : [rel];
+  });
+}
+
+export function brokenRules(rules) {
+  const broken = [];
+  for (const r of rules) {
+    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`);
+  }
+  return broken;
+}

package/lib/hook-settings.mjs

@@ -12,6 +12,7 @@ const SHIP_GATE_FILENAME = "ship-gate.sh";
 const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
 const VERSION_CHECK_FILENAME = "version-check.sh";
 const SKILL_FLAGS_FILENAME = "skill-flags-record.sh";
+const EDIT_CHECK_FILENAME = "edit-check.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -96,6 +97,12 @@ export async function registerHooks(settingsPath) {
     settings.hooks.PostToolUse = [autoMarkEntry];
   }
 
+  const editCheckEntry = {
+    matcher: "Write|Edit|MultiEdit",
+    hooks: [{ type: "command", command: `$CLAUDE_PROJECT_DIR/.claude/hooks/${EDIT_CHECK_FILENAME}` }],
+  };
+  upsert(settings.hooks.PostToolUse, EDIT_CHECK_FILENAME, editCheckEntry);
+
   // Register SessionStart version check. No matcher: startup and resume both
   // want it, and the script's own daily stamp keeps a burst of resumes quiet.
   const versionCheckCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${VERSION_CHECK_FILENAME}`;

package/lib/setup-hook.mjs

@@ -1,7 +1,8 @@
 import { registerHooks } from "./hook-settings.mjs";
 import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 
 // Installs the hook scripts and registers them in .claude/settings.json.
@@ -17,17 +18,21 @@ import { homedir } from "node:os";
 //                             explicitly applied before the first edit
 //   gauntlet.sh               Stop — fast typecheck and tests on the diff
 //   ship-gate.sh              file length and mutation, behind an exit code
+//   gate-config.sh            sourced by ship-gate.sh — shared helpers
 //   ship-gate-projects.sh     sourced by ship-gate.sh — project detection, reuse
 //   ship-gate-hook.sh         PreToolUse on Bash — no commit without a receipt
 //   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
+//   edit-check.sh             PostToolUse — line-limit.sh, lint-ratchet.mjs and
+//                             text-rules.mjs on each edited file
 
 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 SHIP_GATE_FILENAME = "ship-gate.sh";
+const GATE_CONFIG_FILENAME = "gate-config.sh";
 const SHIP_GATE_PROJECTS_FILENAME = "ship-gate-projects.sh";
 const SHIP_GATE_STRUCTURE_FILENAME = "ship-gate-structure.sh";
 const SHIP_GATE_FILES_FILENAME = "ship-gate-files.sh";
@@ -35,6 +40,11 @@ const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
 const VERSION_CHECK_FILENAME = "version-check.sh";
 const SKILL_FLAGS_FILENAME = "skill-flags-record.sh";
 const SKILL_REPORT_FILENAME = "skill-report.mjs";
+const EDIT_CHECK_FILENAME = "edit-check.sh";
+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 LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -99,6 +109,20 @@ export async function writeGauntletConf(targetDir, testCommand) {
   return confPath;
 }
 
+// Before the edit hook is registered, so code that predates it never blocks an edit.
+// Only rules never baselined are recorded: re-recording a known one would bank growth.
+function writeBaselines(dir, hooksDir) {
+  const gitRoot = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout?.trim();
+  const root = gitRoot || dir;
+  if (!existsSync(join(root, ".line-limit-baseline"))) {
+    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 });
+}
+
 export async function setupHook(targetDir = process.cwd()) {
   const resolved = resolve(targetDir);
   const hooksDir = join(resolved, ".claude", "hooks");
@@ -111,6 +135,7 @@ export async function setupHook(targetDir = process.cwd()) {
     APPLICATION_GATE_FILENAME,
     GAUNTLET_FILENAME,
     SHIP_GATE_FILENAME,
+    GATE_CONFIG_FILENAME,
     SHIP_GATE_PROJECTS_FILENAME,
     SHIP_GATE_STRUCTURE_FILENAME,
     SHIP_GATE_FILES_FILENAME,
@@ -118,6 +143,11 @@ export async function setupHook(targetDir = process.cwd()) {
     VERSION_CHECK_FILENAME,
     SKILL_FLAGS_FILENAME,
     SKILL_REPORT_FILENAME,
+    EDIT_CHECK_FILENAME,
+    LINE_LIMIT_FILENAME,
+    LINT_RATCHET_FILENAME,
+    TEXT_RULES_FILENAME,
+    RATCHET_BASELINE_FILENAME,
   ]) {
     const dest = join(hooksDir, name);
     await writeFile(dest, await readHookSource(name), { mode: 0o755 });
@@ -131,6 +161,7 @@ export async function setupHook(targetDir = process.cwd()) {
     // not present — fine
   }
 
+  writeBaselines(resolved, hooksDir);
   await registerHooks(settingsPath);
 
   console.log(`  Hook installed: .claude/hooks/${GATE_FILENAME}`);
@@ -140,5 +171,6 @@ export async function setupHook(targetDir = process.cwd()) {
   console.log(`  Installed: .claude/hooks/${SHIP_GATE_FILENAME} (used by /ship)`);
   console.log(`  Hook installed: .claude/hooks/${SHIP_GATE_HOOK_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${SKILL_FLAGS_FILENAME}`);
+  console.log("  Hook installed: .claude/hooks/edit-check.sh (baselines: .line-limit-baseline, .lint-baseline)");
   console.log(`  Settings updated: .claude/settings.json`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.51.3",
+  "version": "2.52.0",
   "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/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 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 hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {