@spardutti/claude-skills 2.53.1 → 2.54.1

package/README.md

@@ -36,7 +36,7 @@ npx @spardutti/claude-skills
 ```
 
 ```text
-  Claude Skills Installer v2.53.1
+  Claude Skills Installer v2.54.1
 
   ── Frontend ──────────────────────────────
   ◉ react              ◯ tanstack-query

package/hooks/gate-config.sh

@@ -8,6 +8,9 @@ GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alem
 # 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)$'
+# The /ship log is off unless a conf sets GAUNTLET_SHIP_LOG=1; every project writes to one folder.
+GAUNTLET_SHIP_LOG=""
+GAUNTLET_SHIP_LOG_DIR="${HOME:-}/.claude/ship-logs"
 
 load_gauntlet_conf() {  # load_gauntlet_conf <project conf> <fallback conf>
   [ -n "${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ] && . "$HOME/.claude/gauntlet.conf"

package/hooks/ship-gate-files.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
-# Sourced by ship-gate.sh: which changed files a Stryker run can skip, and what its output says.
 
 TEST_RE='(\.|_)(test|spec)\.[^.]+$|(^|/)tests?/'
 
@@ -90,20 +89,25 @@ files_record() {  # files_record <context> <owner> <findings>
 # NoCoverage is printed exactly like Survived and means something worse: not
 # "a test missed this mutation" but "no test executes this line at all". The
 # gate matched only [Survived], so a diff whose files have no tests came back
-# PASS — 306 uncovered mutants reported as proven on one commit. It is judged
-# only for files that went in WITH a range: a glob-shaped path is mutated
-# whole, so its untouched lines would report uncovered forever, and a finding
-# nobody can close is what teaches people to --force.
+# PASS — 306 uncovered mutants reported as proven on one commit. A glob-shaped
+# path is mutated whole, so only its changed lines are judged: the rest would
+# report forever, and a finding nobody can close is what teaches people to --force.
 #
 # The status line carries no file name; the line under it does, as
 # file:line:column. They are paired here rather than grepped separately.
-stryker_findings() {  # stryker_findings <output> <globbed paths, comma-wrapped>
+stryker_findings() {  # stryker_findings <output> <",path:ranges," per globbed file>
   printf '%s\n' "$1" | awk -v globbed="$2" '
+    function changed(rs, l,   parts, ab, i) {
+      for (i = split(rs, parts, " "); i > 0; i--) { split(parts[i], ab, "-"); if (l >= ab[1] + 0 && l <= ab[2] + 0) return 1 }
+      return 0
+    }
+    BEGIN { for (i = split(globbed, g, ","); i > 0; i--) if (g[i] != "") { k = g[i]; sub(/:[^:]*$/, "", k); r = g[i]; sub(/^.*:/, "", r); ranges[k] = r } }
     /^\[Survived\]/   { pend = $0; kind = "s"; next }
     /^\[NoCoverage\]/ { pend = $0; kind = "n"; next }
     pend != "" {
       file = $0; sub(/:[0-9]+:[0-9]+$/, "", file)
-      if (kind == "s" || index(globbed, "," file ",") == 0) print pend "  " $0
+      line = $0; sub(/:[0-9]+$/, "", line); sub(/^.*:/, "", line)
+      if (!(file in ranges) || changed(ranges[file], line + 0)) print pend "  " $0
       pend = ""
     }
     # A survivor with no location under it is still a survivor, never dropped.
@@ -120,8 +124,23 @@ stryker_zero_tests() {  # stryker_zero_tests <output> <label> <seconds>
   echo "      On Vitest 5 this is stryker-js#6210: pin vitest@4 until a fixed runner ships."
 }
 
+# Read by header name, so a reordered column cannot shift the numbers.
+stryker_counts() {  # stryker_counts <output> <label>
+  printf '%s\n' "$1" | awk -F'|' -v label="$2" '
+    /# killed/ { for (i = 1; i <= NF; i++) { h = $i; gsub(/^ +| +$/, "", h); col[h] = i } next }
+    /^ *All files/ && col["# killed"] {
+      for (k in col) { v = $col[k]; gsub(/ /, "", v); n[k] = v + 0 }
+      t = n["# killed"] + n["# survived"] + n["# timeout"] + n["# no cov"] + n["# errors"]
+      printf "  %s stryker — %d mutants: %d killed, %d survived, %d uncovered, %d timed out, %d errors\n",
+        label, t, n["# killed"], n["# survived"], n["# no cov"], n["# timeout"], n["# errors"]
+      exit
+    }'
+}
+
 # Sets ALL from a Stryker run. Fails when a broken run leaves nothing provable.
 stryker_judge() {  # uses OUT GLOBBED FCTX RC owner label T from ship-gate.sh
+  echo "  $label stryker — mutated: $(while IFS= read -r f; do printf '%s ' "${f#"$owner"/}"; done <<< "$OWNED")"
+  stryker_counts "$OUT" "$label"
   ALL=$(stryker_findings "$OUT" "$GLOBBED")
   if stryker_zero_tests "$OUT" "$label" "$T"; then
     ALL=$(grep -v '^\[Survived\]' <<< "$ALL"); [ -n "$ALL" ]; return
@@ -129,3 +148,38 @@ stryker_judge() {  # uses OUT GLOBBED FCTX RC owner label T from ship-gate.sh
   [ -n "$FCTX" ] && [ "$RC" -eq 0 ] && files_record "$FCTX" "$owner" "$ALL"
   return 0
 }
+
+# Files that decide whether Stryker can run the suite at all; none of them is code it mutates.
+SETUP_RE='(^|/)(stryker\.conf[^/]*|stryker\.config\.[^/]*|vitest\.(config|workspace)\.[^/]*|vite\.config\.[^/]*|jest\.config\.[^/]*|tsconfig[^/]*\.json|package(-lock)?\.json|pnpm-(lock|workspace)\.yaml|yarn\.lock|bun\.lockb?|\.npmrc)$|(^|/)patches/'
+
+# A version bump touches package.json on every release and proves nothing about Stryker.
+setup_files() {
+  printf '%s\n' "$CHANGED" | grep -E "$SETUP_RE" | while IFS= read -r f; do
+    [ -n "$({ git diff "$BASE" -- "$f"; git ls-files --error-unmatch -- "$f" >/dev/null 2>&1 || sed 's/^/+/' "$f"; } 2>/dev/null \
+      | grep -E '^[-+]' | grep -vE '^(\+\+\+|---) ' | grep -v '"version"')" ] && printf '%s\n' "$f"
+  done
+}
+
+# A PR can break Stryker (a dropped patch, a test config) with no code to mutate, so a trial
+# runs the suite under it. A project with code to mutate skips it: its real run starts the same way.
+setup_check() {
+  [ -z "$GAUNTLET_MUTATE" ] || return 0
+  local o b bin label key out rc t0 mutated
+  mutated=$(printf '%s\n' "$FILES" | grep -vE "$GAUNTLET_NO_MUTATE" | while IFS= read -r f; do [ -n "$f" ] && owner_of "$f"; done)
+  for o in $(setup_files | while IFS= read -r f; do owner_of "$f"; done | sort -u); do
+    grep -qxF "$o" <<< "$mutated" && continue
+    b=""; [ "$o" != . ] && b="$o/"; [ "$o" = . ] && label="<repo root>" || label="$o/"
+    grep -qs '@stryker-mutator/core' "${b}package.json" || continue
+    key="/tmp/claude-shipgate-project-$(project_key "$o" dryrun)"
+    [ -f "$key" ] && { echo "  $label stryker setup — ok, not re-run: its trial run passed"; continue; }
+    bin=$(stryker_bin "$b"); t0=$SECONDS; out=$(cd "${b:-.}" && $bin run --dryRunOnly --concurrency "$(gate_workers)" 2>&1); rc=$?
+    if [ $rc -eq 0 ]; then echo "  $label stryker setup ($((SECONDS - t0))s) — ok, its trial run passed"; touch "$key"
+    elif grep -qE 'initial test run|DryRunExecutor' <<< "$out"; then
+      echo "  $label stryker setup ($((SECONDS - t0))s) — this change breaks Stryker's own test run:"
+      printf '%s\n' "$out" | tail -12 | sed 's/^/      /'; STATUS=1
+    else
+      echo "  $label stryker setup ($((SECONDS - t0))s) — UNPROVEN, the trial run could not start:"
+      printf '%s\n' "$out" | tail -6 | sed 's/^/      /'; stryker_elsewhere stryker "$b"; [ "$STATUS" = 0 ] && STATUS=2
+    fi
+  done
+}

package/hooks/ship-gate-hook.sh

@@ -42,6 +42,21 @@ case "$CMD" in
   *) exit 0 ;;
 esac
 
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\r'/\\r}"
+  s="${s//$'\t'/\\t}"
+  printf '"%s"' "$s"
+}
+
+deny() {
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$(json_escape "$1")"
+  exit 0
+}
+
 GATE="$PROJECT_DIR/.claude/hooks/ship-gate.sh"
 [ -x "$GATE" ] || exit 0
 git rev-parse --git-dir >/dev/null 2>&1 || exit 0
@@ -84,6 +99,18 @@ BRANCH=$(pr_branch)
 KEY=$(CLAUDE_PROJECT_DIR="$TARGET" bash "$GATE" --key 2>/dev/null)
 [ -z "$KEY" ] && exit 0
 
+# A gate run by hand skips /ship's audit and review, so the PR waits for /ship itself.
+# A merge whose branch gh cannot name is left to the receipt alone.
+MARKER="$PROJECT_DIR/.claude/hooks/ship-mark.sh"
+case "$CMD" in *"gh pr create"*) MARK_BRANCH=${BRANCH:-$(git branch --show-current)} ;; *) MARK_BRANCH=$BRANCH ;; esac
+if [ -f "$MARKER" ] && [ -n "$MARK_BRANCH" ] && ! CLAUDE_PROJECT_DIR="$TARGET" bash "$MARKER" check "$MARK_BRANCH"; then
+  deny "BLOCKED: /ship has not run on branch $MARK_BRANCH.
+
+Load the /ship command with the Skill tool and follow it from the start. A gate run
+by hand is not enough: /ship also runs the skills audit and the code review.
+The gate's earlier pass is reused, so only those two steps cost time."
+fi
+
 RECEIPT="/tmp/claude-shipgate-$KEY"
 if [ -f "$RECEIPT" ]; then
   exit 0
@@ -111,15 +138,4 @@ To publish without the gate, say so out loud and run:
 
   bash .claude/hooks/ship-gate.sh --force"
 
-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 '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$(json_escape "$MSG")"
-exit 0
+deny "$MSG"

package/hooks/ship-gate-projects.sh

@@ -92,7 +92,7 @@ changed_files() {
 # Ignored extensions are left out; see the comment where ship-gate.sh first calls this.
 receipt_key() {
   { printf '%s\n' "$PROJECT_DIR"
-    changed_files | grep -viE "\.($GAUNTLET_IGNORE_EXT)$" | while IFS= read -r f; do
+    { changed_files | grep -viE "\.($GAUNTLET_IGNORE_EXT)$"; setup_files; } | LC_ALL=C sort -u | while IFS= read -r f; do
       [ -n "$f" ] || continue
       printf '%s\n' "$f"
       [ -f "$f" ] && cat "$f"

package/hooks/ship-gate-structure.sh

@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
-# Sourced by ship-gate.sh: a new file must sit in the folder named for its kind.
-# Only ADDED files are judged, so a repo laid out the old way cannot get worse and need not move.
 
 STRUCTURE_JS_KINDS="components|hooks|api|queries|schemas|types|utils|stores|test"
 STRUCTURE_KIND_FILE='(^|[._])(router|routes|controller|service|schema|model)s?\.[cm]?[jt]s$|(Router|Routes|Controller|Service|Schema|Model)s?\.[cm]?[jt]s$'
@@ -69,6 +67,7 @@ py_misplaced() {  # py_misplaced <path>
   fi
 }
 
+# Only ADDED files are judged, so a repo laid out the old way cannot get worse and need not move.
 structure_check() {
   bad=""; count=0
   while IFS= read -r f; do
@@ -115,13 +114,44 @@ gate_report() {
 # 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
+  [ "$1" = 1 ] || [ "$GAUNTLET_SHIP_LOG" = 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
+  [ "$1" = 1 ] && gate_diary
+  ship_log "$REPORT" "$1"
+  return 0
+}
+
+gate_diary() {
   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")" \
     >> "$diary/gate-findings.jsonl"
 }
+
+# Every run goes to the /ship log when it is on; a broken log never changes the verdict.
+ship_log() {  # ship_log <report> <exit code>
+  [ "$GAUNTLET_SHIP_LOG" = 1 ] && command -v node >/dev/null || return 0
+  SHIP_LOG_TEST_RE="$TEST_RE" SHIP_LOG_SOURCE_EXT="$GAUNTLET_SOURCE_EXT" node "$HERE/ship-log.mjs" gate "$1" "$2" "$SECONDS" "$BASE" >/dev/null 2>&1 || true
+}
+
+gate_force() {
+  printf 'FORCED %s\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
+  echo "ship-gate: FORCED — receipt written without running any check."
+  local r; r=$(mktemp); echo "ship-gate: FORCED" > "$r"
+  ship_log "$r" 0; rm -f "$r"
+  exit 0
+}
+
+# Nothing to mutate, but a Stryker trial run may still have been unable to start.
+no_code_exit() {
+  echo "ship-gate: no changed code files — nothing to check"
+  if [ "$STATUS" = 2 ]; then
+    printf 'ship-gate: UNPROVEN in %ss — nothing is wrong, but nothing was proven either\n' "$SECONDS"
+    printf 'UNPROVEN %s setup-trial\n' "$(date -u +%FT%TZ)" > "$RECEIPT"; exit 2
+  fi
+  printf 'PASS %s no-code-changes\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
+  exit 0
+}

package/hooks/ship-gate.sh

@@ -100,11 +100,7 @@ CHANGED=$(changed_files)
 RECEIPT_KEY=$(receipt_key); RECEIPT="/tmp/claude-shipgate-$RECEIPT_KEY"
 
 if [ "$MODE" = key ]; then printf '%s\n' "$RECEIPT_KEY"; exit 0; fi
-if [ "$MODE" = force ]; then
-  printf 'FORCED %s\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
-  echo "ship-gate: FORCED — receipt written without running any check."
-  exit 0
-fi
+[ "$MODE" = force ] && gate_force
 gate_report "$RECEIPT_KEY"
 SOURCED=$(printf '%s\n' "$CHANGED" | grep -E "\.($GAUNTLET_SOURCE_EXT)$" \
         | grep -vE "$TEST_RE|(^|/)\.stryker-tmp/" | while read -r f; do
@@ -134,7 +130,7 @@ if [ -n "$IGNORED" ]; then
 fi
 
 [ -n "$FILES" ] && echo "ship-gate: $(printf '%s\n' "$FILES" | wc -l) changed code file(s), base $(git rev-parse --short "$BASE")"
-STATUS=0; structure_check || { STATUS=1; [ -z "$FILES" ] && structure_fail; }
+STATUS=0; structure_check || STATUS=1; [ "$STATUS" = 1 ] || setup_check; [ "$STATUS" = 1 ] && [ -z "$FILES" ] && structure_fail
 if [ -z "$FILES" ]; then
   # "I recognised nothing" is not "there is nothing", and the gate used to report
   # both as a PASS. A Godot repo changed only .gd files, which no extension in
@@ -154,9 +150,7 @@ if [ -z "$FILES" ]; then
     printf 'UNPROVEN %s unknown-extensions\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
     exit 2
   fi
-  echo "ship-gate: no changed code files — nothing to check"
-  printf 'PASS %s no-code-changes\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
-  exit 0
+  no_code_exit
 fi
 
 # ------------------------------------------------- check 1: file length (hard)
@@ -224,7 +218,7 @@ for owner in $OWNERS; do
     # superset of the diff, slower than a range but never less than what changed.
     case "$rel" in
       *[][*?{}]*) FLAGS="$FLAGS,$(printf '%s' "$rel" | sed 's/[][*?{}]/?/g')"
-                  GLOBBED="$GLOBBED$rel," ;;
+                  GLOBBED="$GLOBBED$rel:$(echo $hunks)," ;;
       *) for r in $hunks; do FLAGS="$FLAGS,$rel:$r"; done ;;
     esac
   done <<< "$OWNED"

package/hooks/ship-log-parse.mjs

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+const PROJECT = /^ {2}(\S.*?) (stryker|mutmut|config)(?: \((\d+)s\))? — (.*)$/;
+const SURVIVOR = /^ {6}\[(Survived|NoCoverage)\] (\S+)\s+(\S+)$/;
+const MUTMUT = /^ {6}(\S+__mutmut_\d+)$/;
+const COUNTS = /^(\d+) mutants: (\d+) killed, (\d+) survived, (\d+) uncovered, (\d+) timed out, (\d+) errors$/;
+const VERDICT = /^ship-gate: (PASS|FAIL|UNPROVEN|FORCED)(?: in (\d+)s)?/;
+
+function projectFor(run, label, tool) {
+  let p = run.projects.find((x) => x.label === label && x.tool === tool);
+  if (!p) {
+    p = { label, tool, seconds: null, result: null, reused: [], mutated: [], counts: null, survivors: [] };
+    run.projects.push(p);
+  }
+  return p;
+}
+
+function applyProject(p, seconds, text) {
+  if (seconds) p.seconds = Number(seconds);
+  const counts = text.match(COUNTS);
+  if (counts) {
+    const [, total, killed, survived, uncovered, timedOut, errors] = counts.map(Number);
+    p.counts = { total, killed, survived, uncovered, timedOut, errors };
+  } else if (text.startsWith("mutated:")) p.mutated = text.slice(8).trim().split(/\s+/);
+  else if (text.startsWith("ok, not re-run: passed and unchanged since:")) p.reused = text.split(":").pop().trim().split(/\s+/);
+  else if (text.startsWith("ok, not re-run")) p.result = "cached";
+  else if (text.startsWith("ok,")) p.result = "ok";
+  else if (text.startsWith("these lines can break")) p.result = "survivors";
+  else if (text.startsWith("the run failed")) p.result = "failed";
+  else if (text.startsWith("UNPROVEN")) p.result = "unproven";
+}
+
+function readSection(run, line, state) {
+  if (line.startsWith("STRUCTURE — ")) { run.structure = line.slice(12); state.list = line.includes("outside") ? run.misplaced : null; return; }
+  if (line.startsWith("FILE LENGTH — ")) { run.length = line.slice(14); state.list = line.includes("over the limit") ? run.overLimit : null; return; }
+  if (line.startsWith("ship-gate: not gated")) { state.list = run.ignored; return; }
+  const scope = line.match(/^ship-gate:\s+(\d+) changed code file\(s\)/);
+  if (scope) run.scope = Number(scope[1]);
+  const verdict = line.match(VERDICT);
+  if (verdict) run.verdict = verdict[1];
+  if (line.startsWith("ship-gate: no changed code files")) run.verdict = "PASS";
+  if (!/^ {2}\S/.test(line) || line.includes("Move them") || line.includes("Splitting a file")) state.list = null;
+}
+
+function readLine(run, line, state) {
+  const project = line.match(PROJECT);
+  if (project) {
+    state.project = projectFor(run, project[1], project[2]);
+    applyProject(state.project, project[3], project[4]);
+    state.list = null;
+    return;
+  }
+  const survivor = line.match(SURVIVOR) ?? line.match(MUTMUT);
+  if (survivor && state.project) {
+    state.project.survivors.push(survivor.length > 2 ? { kind: survivor[1], mutator: survivor[2], at: survivor[3] } : { kind: "Survived", at: survivor[1] });
+    return;
+  }
+  if (state.list && /^ {2}\S/.test(line)) { state.list.push(line.trim()); return; }
+  readSection(run, line, state);
+}
+
+export function parseReport(text) {
+  const run = { verdict: null, scope: 0, ignored: [], structure: null, misplaced: [], length: null, overLimit: [], projects: [] };
+  const state = { project: null, list: null };
+  for (const line of text.split("\n")) readLine(run, line, state);
+  // The verdict is the last line the gate prints; a run killed before it never earned one.
+  run.verdict ??= "INTERRUPTED";
+  return run;
+}
+
+export function git(args) {
+  const r = spawnSync("git", args, { encoding: "utf8", maxBuffer: 1 << 26 });
+  return r.status === 0 ? r.stdout.trim() : "";
+}
+
+function kindOf(path, testRe, sourceExt) {
+  if (testRe && new RegExp(testRe).test(path)) return "tests";
+  return sourceExt && new RegExp(`\\.(${sourceExt})$`).test(path) ? "code" : "other";
+}
+
+function untracked() {
+  return git(["ls-files", "--others", "--exclude-standard"]).split("\n").filter(Boolean).map((f) => {
+    let text = "";
+    try { text = readFileSync(f, "utf8"); } catch { /* unreadable: count the file, not its lines */ }
+    return [text ? text.split("\n").length - (text.endsWith("\n") ? 1 : 0) : 0, 0, f];
+  });
+}
+
+// What the PR will hold: the fork point against the working tree, plus files not yet added.
+export function prSize(base, testRe, sourceExt) {
+  const fork = git(["merge-base", base, "HEAD"]).trim() || base;
+  const rows = git(["diff", "--numstat", "--no-renames", fork]).split("\n").filter(Boolean).map((l) => l.split("\t"));
+  const size = { files: 0, added: 0, removed: 0, code: { files: 0, added: 0, removed: 0 }, tests: { files: 0, added: 0, removed: 0 }, other: { files: 0, added: 0, removed: 0 } };
+  for (const [a, r, f] of [...rows, ...untracked()]) {
+    if (/(^|\/)\.claude\/|(^|\/)\.(line-limit|lint|mutmut)-baseline$/.test(f)) continue;
+    const add = Number(a) || 0, rem = Number(r) || 0, bucket = size[kindOf(f, testRe, sourceExt)];
+    size.files++; size.added += add; size.removed += rem;
+    bucket.files++; bucket.added += add; bucket.removed += rem;
+  }
+  return size;
+}

package/hooks/ship-log-report.mjs

@@ -0,0 +1,48 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+function records(dir) {
+  const read = (d) => (existsSync(d) ? readdirSync(d).filter((f) => f.endsWith(".json")).map((f) => join(d, f)) : []);
+  return [...read(dir), ...read(join(dir, "open"))].flatMap((f) => {
+    try {
+      const r = JSON.parse(readFileSync(f, "utf8"));
+      return r?.v === 1 && Array.isArray(r.gate) && Array.isArray(r.findings) ? [r] : [];
+    } catch { return []; }
+  });
+}
+
+export function tally(findings) {
+  const by = {};
+  for (const f of findings) {
+    const s = (by[f.by.split(":")[0]] ??= { found: 0, confirmed: 0, refuted: 0, unconfirmed: 0, fixed: 0 });
+    s.found++; s[f.verdict]++; if (f.fixed) s.fixed++;
+  }
+  return by;
+}
+
+function findingCell(by = {}) {
+  const parts = Object.entries(by).map(([src, s]) => `${src} ${s.found}/${s.confirmed}/${s.fixed}`);
+  return parts.join(" · ") || "-";
+}
+
+function row(r) {
+  const s = r.summary ?? { minutes: null, gateRuns: r.gate.length, gateSeconds: r.gate.reduce((n, g) => n + (g.seconds ?? 0), 0), findings: tally(r.findings) };
+  const size = r.size ? `${r.size.files} +${r.size.added} -${r.size.removed}` : "-";
+  return [r.app, (r.finished ?? r.started).slice(0, 10), r.pr ? `#${r.pr}` : r.branch, r.status, s.minutes ?? "-", s.gateRuns, `${s.gateSeconds}s`, size, findingCell(s.findings)];
+}
+
+function table(rows) {
+  const head = ["app", "date", "pr", "status", "min", "gate runs", "gate time", "files +/-", "findings found/confirmed/fixed"];
+  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
+  for (const r of [head, ...rows]) console.log(r.map((c, i) => String(c).padEnd(widths[i])).join("  ").trimEnd());
+}
+
+export function printReport(dir) {
+  const all = records(dir).sort((a, b) => (a.finished ?? a.started).localeCompare(b.finished ?? b.started));
+  if (all.length === 0) {
+    console.log(`ship-log: no logs in ${dir}. Turn logging on with GAUNTLET_SHIP_LOG=1 in ~/.claude/gauntlet.conf.`);
+    return 0;
+  }
+  table(all.map(row));
+  return 0;
+}

package/hooks/ship-log.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { git, parseReport, prSize } from "./ship-log-parse.mjs";
+import { printReport, tally } from "./ship-log-report.mjs";
+
+const HERE = dirname(resolve(process.argv[1]));
+const VERDICTS = ["confirmed", "refuted", "unconfirmed"];
+const now = () => new Date().toISOString().replace(/\.\d+Z$/, "Z");
+
+// gate-config.sh owns the config files and their order, so the gate and this agree on "on".
+function conf() {
+  const root = git(["rev-parse", "--show-toplevel"]) || process.cwd();
+  const script = 'cd "$2" && . "$1/gate-config.sh" || exit 1; load_gauntlet_conf .claude/gauntlet.conf "$1/../gauntlet.conf"; printf "\\nSHIP_LOG_ON=%s\\nSHIP_LOG_DIR=%s\\n" "$GAUNTLET_SHIP_LOG" "$GAUNTLET_SHIP_LOG_DIR"';
+  const out = spawnSync("bash", ["-c", script, "_", HERE, root], { encoding: "utf8" }).stdout;
+  const value = (key) => out.split("\n").findLast((l) => l.startsWith(`${key}=`))?.slice(key.length + 1) ?? "";
+  return { on: value("SHIP_LOG_ON") === "1", dir: value("SHIP_LOG_DIR") || join(process.env.HOME ?? "", ".claude", "ship-logs"), root };
+}
+
+function identity(root) {
+  const origin = git(["remote", "get-url", "origin"]);
+  const app = basename(origin || root).replace(/\.git$/, "");
+  return { app, branch: git(["branch", "--show-current"]) || "detached" };
+}
+
+function openPath(dir, { app, branch }) {
+  return join(dir, "open", `${app}__${branch.replace(/[^\w.-]+/g, "-")}.json`);
+}
+
+function load(path, id) {
+  if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
+  return { v: 1, ...id, started: now(), status: "open", pr: null, base: null, size: null, gate: [], steps: {}, findings: [] };
+}
+
+function save(path, record) {
+  mkdirSync(dirname(path), { recursive: true });
+  record.updated = now();
+  writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`);
+}
+
+function summarize(record) {
+  const by = tally(record.findings);
+  const minutes = (Date.parse(record.finished) - Date.parse(record.started)) / 60000;
+  return { minutes: Math.round(minutes * 10) / 10, gateRuns: record.gate.length, gateSeconds: record.gate.reduce((n, r) => n + (r.seconds ?? 0), 0), findings: by };
+}
+
+function finalize(dir, path, record, tag, status, reason) {
+  Object.assign(record, { status, reason: reason ?? null, finished: now() });
+  record.summary = summarize(record);
+  const stem = `${record.app}_${record.finished.slice(0, 10)}_${tag}`;
+  let out = join(dir, `${stem}.json`);
+  for (let i = 2; existsSync(out); i++) out = join(dir, `${stem}-${i}.json`);
+  save(path, record);
+  renameSync(path, out);
+  console.log(`ship-log: saved ${out}`);
+}
+
+// A ship that never reached pr or end was abandoned; keep it, but never fold it into the next one.
+function restart(dir, path, record, id) {
+  if (existsSync(path)) finalize(dir, path, record, id.branch.replace(/[^\w.-]+/g, "-"), "abandoned");
+  save(path, load(path, id));
+}
+
+function addGateRun(record, [report, exit, seconds, base]) {
+  const text = readFileSync(report, "utf8");
+  record.gate.push({ ts: now(), exit: Number(exit), seconds: Number(seconds), ...parseReport(text), report: text });
+  if (base) { record.base = base; record.size = prSize(base, process.env.SHIP_LOG_TEST_RE ?? "", process.env.SHIP_LOG_SOURCE_EXT ?? ""); }
+}
+
+function addFinding(record, json) {
+  const f = JSON.parse(json ?? "");
+  if (typeof f.by !== "string" || typeof f.what !== "string" || !VERDICTS.includes(f.verdict) || typeof f.fixed !== "boolean") {
+    throw new Error(`a finding needs by, what, verdict (${VERDICTS.join("|")}) and fixed (true|false)`);
+  }
+  record.findings.push({ ts: now(), ...f });
+}
+
+function lastEvent(record, skip) {
+  const ends = Object.entries(record.steps).filter(([k]) => k !== skip).map(([, s]) => s.end);
+  return [record.started, ...record.gate.map((g) => g.ts), ...ends].filter(Boolean).sort().at(-1);
+}
+
+function addStep(record, [name, edge]) {
+  if (!name || !["start", "end"].includes(edge)) throw new Error("usage: step <name> start|end");
+  const step = (record.steps[name] ??= {});
+  step[edge] = now();
+  if (edge === "end" && !step.start) step.start = lastEvent(record, name);
+  if (step.start && step.end) step.seconds = Math.round((Date.parse(step.end) - Date.parse(step.start)) / 1000);
+}
+
+function run(mode, args) {
+  const c = conf();
+  if (mode === "report") return printReport(args[0] ?? c.dir);
+  if (mode === "on") return c.on ? 0 : 1;
+  if (!c.on) return 0;
+  const id = identity(c.root), path = openPath(c.dir, id), record = load(path, id);
+  if (mode === "start") return restart(c.dir, path, record, id), 0;
+  // A gate run by hand or on a release is not a ship; only /ship's start opens one.
+  if (mode === "gate" && !existsSync(path)) return 0;
+  if (mode === "gate") addGateRun(record, args);
+  else if (mode === "finding") addFinding(record, args[0]);
+  else if (mode === "step") addStep(record, args);
+  else if (mode === "pr" && /^\d+$/.test(args[0] ?? "")) {
+    record.pr = Number(args[0]);
+    return finalize(c.dir, path, record, `pr${args[0]}`, "pr-opened"), 0;
+  }
+  else if (mode === "end") return finalize(c.dir, path, record, id.branch.replace(/[^\w.-]+/g, "-"), "stopped", args.join(" ") || null), 0;
+  else throw new Error("usage: ship-log.mjs on | start | gate <report> <exit> <seconds> <base> | step <name> start|end | finding '<json>' | pr <number> | end [reason] | report [dir]");
+  save(path, record);
+  return 0;
+}
+
+try {
+  process.exit(run(process.argv[2], process.argv.slice(3)) ?? 0);
+} catch (err) {
+  console.error(`ship-log: ${err.message}`);
+  process.exit(1);
+}

package/hooks/ship-mark.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || exit 1
+# The shared .git dir, so a worktree's mark is found from the main folder.
+COMMON=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null && pwd) || exit 1
+BRANCH=${2:-$(git branch --show-current 2>/dev/null)}
+[ -n "$BRANCH" ] || exit 1
+MARK="/tmp/claude-ship-$(printf '%s %s' "$COMMON" "$BRANCH" | cksum | cut -d' ' -f1)"
+
+# A mark lasts 12 hours, so a branch reused later (dev, for a release) needs /ship again.
+case "${1:-}" in
+  begin) touch "$MARK" ;;
+  check) [ -n "$(find "$MARK" -mmin -720 2>/dev/null)" ] ;;
+  *) echo "usage: ship-mark.sh begin | check [branch]" >&2; exit 2 ;;
+esac

package/lib/setup-claude-md.mjs

@@ -26,7 +26,7 @@ The hooks and skills in \`.claude/\` come from \`@spardutti/claude-skills\`. Fac
 - **Your own skill:** write \`.claude/skills/<name>/SKILL.md\` with \`name\` and \`description\`, then add \`<name>\` to \`"custom"\` in \`.claude/.claude-skills.json\`. Never add it to \`"skills"\`: a sync deletes anything there that is not in the catalog.
 - **Make it mandatory on some files:** put \`gate-paths: "src/**/*.tsx"\` under \`metadata:\`, quoted. A bare top-level \`paths:\` makes Claude Code drop the skill. Add \`tracks: react@19\` to fire only when the project depends on that package.
 - **Hook settings** live in \`.claude/gauntlet.conf\` (shell syntax): \`GAUNTLET_TEST\`, \`GAUNTLET_TYPECHECK\`, \`GAUNTLET_BASE\` (the trunk branch, if not develop/dev/main), \`GAUNTLET_MAX_LINES\`, \`GAUNTLET_IGNORE_FILES\`, \`GAUNTLET_OFF=1\`.
-- **Ship gate:** \`bash .claude/hooks/ship-gate.sh\` before a PR. Never run it with \`--force\` or \`--baseline\` unless the user asks.
+- **Shipping:** open, merge or release a PR only through the \`/ship\` command; load it every time, even when you remember the steps. Never run \`ship-gate.sh\` with \`--force\` or \`--baseline\` unless the user asks.
 - **Never edit \`.claude/hooks/\`** — a sync overwrites it. Update with \`npx @spardutti/claude-skills --sync\`.`;
 
 const BLOCKS = [

package/lib/setup-hook.mjs

@@ -21,10 +21,13 @@ import { homedir } from "node:os";
 //   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
+//   ship-mark.sh              written by /ship — no PR on a branch /ship never ran on
 //   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
+//   ship-log.mjs              the /ship log, when GAUNTLET_SHIP_LOG=1 — every gate run
+//                             and finding, one file per ship, in one folder
 //   edit-check.sh             PostToolUse — line-limit.sh, lint-ratchet.mjs and
 //                             text-rules.mjs on each edited file
 
@@ -48,6 +51,10 @@ 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 SHIP_LOG_FILENAME = "ship-log.mjs";
+const SHIP_LOG_PARSE_FILENAME = "ship-log-parse.mjs";
+const SHIP_LOG_REPORT_FILENAME = "ship-log-report.mjs";
+const SHIP_MARK_FILENAME = "ship-mark.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -152,6 +159,10 @@ export async function setupHook(targetDir = process.cwd()) {
     RATCHET_BASELINE_FILENAME,
     DIARY_CHECK_FILENAME,
     DIARY_LIB_FILENAME,
+    SHIP_LOG_FILENAME,
+    SHIP_LOG_PARSE_FILENAME,
+    SHIP_LOG_REPORT_FILENAME,
+    SHIP_MARK_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.53.1",
+  "version": "2.54.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 ../scripts/diary-check.mjs ../scripts/diary-lib.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 ../scripts/ship-log.mjs ../scripts/ship-log-parse.mjs ../scripts/ship-log-report.mjs ../scripts/ship-mark.sh hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {