@spardutti/claude-skills 2.56.2 → 2.57.0

package/README.md

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

package/hooks/gate-config.sh

@@ -18,6 +18,30 @@ load_gauntlet_conf() {  # load_gauntlet_conf <project conf> <fallback conf>
   if [ -f "$conf" ]; then . "$conf"; fi
 }
 
+skill_field() {  # skill_field <SKILL.md> <key pattern> — its first value, quotes stripped
+  sed -n "s/^$2:[[:space:]]*//p" "$1" | head -1 | sed "s/^[\"']//; s/[\"']\$//"
+}
+
+# Claude Code writes gate-paths gitignore-style. A case glob has no **, but * already crosses /
+# here, so dropping the **/ prefix is equivalent. set -f keeps the globs from matching real files.
+skill_hits() {  # skill_hits <gate-paths> <files...> — the files those globs match
+  local g t globs
+  set -f
+  globs=$(printf '%s' "$1" | tr ',' ' ' | sed 's!\*\*/!!g')
+  for t in "${@:2}"; do
+    for g in $globs; do
+      case "$g" in \**|/*) ;; *) g="*$g" ;; esac
+      case "$t" in $g) printf '%s\n' "$t"; break ;; esac
+    done
+  done
+  set +f
+}
+
+json_field() {  # json_field <json> <key> — a flat string value; \" is unescaped, \n is kept as two characters
+  printf '%s' "$1" | grep -oE "\"$2\"[[:space:]]*:[[:space:]]*\"([^\"\\\\]|\\\\.)*\"" | head -1 \
+    | sed -E 's/^[^:]*:[[:space:]]*"//; s/"$//; s/\\"/"/g'
+}
+
 # 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() {

package/hooks/ship-gate-hook.sh

@@ -19,9 +19,10 @@
 # now: the cost is paid once, at the point work actually ships.
 
 INPUT=$(cat)
+. "$(cd "$(dirname "$0")" && pwd)/gate-config.sh" 2>/dev/null || exit 0
 
-CMD=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \
-      | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+CMD=$(json_field "$INPUT" command)
+CWD=$(json_field "$INPUT" cwd)
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
 cd "$PROJECT_DIR" 2>/dev/null || exit 0
@@ -30,16 +31,31 @@ cd "$PROJECT_DIR" 2>/dev/null || exit 0
 # protected branch — that is a direct ship with no PR in front of it. The branch
 # is read from git rather than parsed out of the command, because `git push` with
 # no arguments names no branch at all.
+push_dirs() {  # one "<cd dir><TAB><-C dir>" line per push in the command
+  local dir=. seg re_c='^git -C +"?([^" ]+)"? +push( |$)' re_cd='^cd +"?([^" ]+)"?$' re_push='^git push( |$)'
+  while IFS= read -r seg; do
+    seg=$(printf '%s' "$seg" | sed -E 's/^[[:space:]]*(\$\(|\()?[[:space:]]*//; s/[[:space:]]*$//')
+    if [[ $seg =~ $re_cd ]]; then dir=${BASH_REMATCH[1]}
+    elif [[ $seg =~ $re_c ]]; then printf '%s\t%s\n' "$dir" "${BASH_REMATCH[1]}"
+    elif [[ $seg =~ $re_push ]]; then printf '%s\t\n' "$dir"
+    fi
+  done < <(printf '%s\n' "$CMD" | sed -E 's/\\n|&&|\|\||;|\|/\n/g')
+}
+
+push_branch() {  # push_branch <cd dir> <-C dir>; a folder git cannot read falls back to the main folder
+  git -C "${CWD:-.}" -C "$1" ${2:+-C "$2"} branch --show-current 2>/dev/null || git branch --show-current 2>/dev/null
+}
+
 case "$CMD" in
   *"gh pr create"*|*"gh pr merge"*) ;;
-  *"git push"*)
-    BRANCH=$(git branch --show-current 2>/dev/null)
-    case "$BRANCH" in
-      main|master|develop|development|dev) ;;
-      *) exit 0 ;;
-    esac
+  *)
+    PUSHES=$(push_dirs); [ -n "$PUSHES" ] || exit 0
+    PROTECTED=""
+    while IFS=$'\t' read -r d c; do
+      case "$(push_branch "$d" "$c")" in main|master|develop|development|dev) PROTECTED=1 ;; esac
+    done <<< "$PUSHES"
+    [ -n "$PROTECTED" ] || exit 0
     ;;
-  *) exit 0 ;;
 esac
 
 json_escape() {
@@ -63,7 +79,7 @@ git rev-parse --git-dir >/dev/null 2>&1 || exit 0
 
 pr_branch() {
   case "$CMD" in
-    *"gh pr create"*) printf '%s\n' "$CMD" | sed -nE 's/.*(--head[ =]|-H )([^ ;&|]+).*/\2/p' ;;
+    *"gh pr create"*) printf '%s\n' "$CMD" | sed -nE 's/.*(--head[ =]|-H )"?([^ ;&|"]+).*/\2/p' ;;
     *"gh pr merge"*) merge_branch ;;
   esac
 }
@@ -91,6 +107,9 @@ worktree_of() {
 # A PR from a worktree ships that folder's diff, so its receipt is keyed there,
 # not in the folder this session started in.
 TARGET="$PROJECT_DIR"
+case "$CMD" in *"gh pr create"*)
+  CWD_TOP=$(git -C "${CWD:-.}" rev-parse --show-toplevel 2>/dev/null) && [ -n "$CWD_TOP" ] && TARGET="$CWD_TOP" ;;
+esac
 BRANCH=$(pr_branch)
 [ -n "$BRANCH" ] && WT=$(worktree_of "$BRANCH") && [ -n "$WT" ] && TARGET="$WT"
 
@@ -102,7 +121,7 @@ KEY=$(CLAUDE_PROJECT_DIR="$TARGET" bash "$GATE" --key 2>/dev/null)
 # 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
+case "$CMD" in *"gh pr create"*) MARK_BRANCH=${BRANCH:-$(git -C "$TARGET" 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.
 
@@ -111,8 +130,20 @@ 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
 
+SHIP_LOG="$PROJECT_DIR/.claude/hooks/ship-log.mjs"
+log_ready() {
+  case "$CMD" in *"gh pr create"*) ;; *) return 0 ;; esac
+  [ -f "$SHIP_LOG" ] && command -v node >/dev/null || return 0
+  TODO=$(SHIP_LOG_ROOT="$TARGET" node "$SHIP_LOG" ready 2>/dev/null) || [ -z "$TODO" ] || deny "BLOCKED: the ship log is not filled in for this /ship. Do these, then create the PR again:
+$TODO
+
+A finding's shape is in The ship log section of /ship. Log each one with the verdict
+you already reached; never log a finding you did not settle."
+}
+
 RECEIPT="/tmp/claude-shipgate-$KEY"
 if [ -f "$RECEIPT" ]; then
+  log_ready
   exit 0
 fi
 

package/hooks/ship-gate-projects.sh

@@ -89,6 +89,25 @@ changed_files() {
     git ls-files --others --exclude-standard 2>/dev/null; } | sort -u | grep -vE '(^|/)\.claude/'
 }
 
+file_hunks() {  # file_hunks <base> <file> — its new-side line ranges, one "start-end" a line
+  local h
+  h=$(git diff -U0 "$1" -- "$2" 2>/dev/null | grep -oE '^@@ -[0-9,]+ \+[0-9]+(,[0-9]+)?' | sed 's/.*+//' \
+      | while IFS=, read -r s l; do l=${l:-1}; [ "$l" -gt 0 ] && echo "$s-$((s+l-1))"; done)
+  if [ -n "$h" ]; then printf '%s\n' "$h"; else echo "1-$(wc -l < "$2" | tr -d ' ')"; fi
+}
+
+# The audit's scope: every changed text file, minus generated, vendored and lock files. Tab-separated: paths may hold spaces.
+scope_report() {
+  local f r new
+  echo "base $BASE"
+  printf '%s\n' "$CHANGED" | grep -vE '(^|/)(package-lock\.json|pnpm-lock\.yaml|[^/]*\.lock)$' | while IFS= read -r f; do
+    [ -f "$f" ] && ! is_ignored "$f" && grep -qI . "$f" || continue
+    r=$(file_hunks "$BASE" "$f" | sed -E 's/^([0-9]+)-\1$/\1/' | paste -sd, -)
+    new=""; git cat-file -e "$BASE:$f" 2>/dev/null || new=" (new)"
+    printf '%s\t%s%s\n' "$f" "$r" "$new"
+  done
+}
+
 # Ignored extensions are left out; see the comment where ship-gate.sh first calls this.
 receipt_key() {
   { printf '%s\n' "$PROJECT_DIR"

package/hooks/ship-gate.sh

@@ -52,6 +52,7 @@ HERE=$(cd "$(dirname "$0")" && pwd)
 MODE=""
 case "${1:-}" in
   --key)      MODE=key; shift ;;
+  --scope)    MODE=scope; shift ;;
   --force)    MODE=force; shift ;;
   --baseline) MODE=baseline; shift ;;
 esac
@@ -81,6 +82,7 @@ for B in ${GAUNTLET_BASE:-} develop dev main; do [ -n "$BASE" ] || BASE=$(git me
 [ -n "$BASE" ] || BASE=$(git rev-list --max-parents=0 HEAD | head -1)
 
 CHANGED=$(changed_files)
+[ "$MODE" = scope ] && { scope_report; exit 0; }
 
 # Only the files this gate can actually read go into the key. It used to be every
 # changed file, so a version bump in package.json or a line in a changelog threw
@@ -205,10 +207,7 @@ for owner in $OWNERS; do
   FLAGS=""
   GLOBBED=","
   while IFS= read -r f; do
-    hunks=$(git diff -U0 "$BASE" -- "$f" 2>/dev/null \
-            | grep -oE '^@@ -[0-9,]+ \+[0-9]+(,[0-9]+)?' | sed 's/.*+//' \
-            | while IFS=, read -r s l; do l=${l:-1}; [ "$l" -gt 0 ] && echo "$s-$((s+l-1))"; done)
-    [ -z "$hunks" ] && hunks="1-$(wc -l < "$f")"
+    hunks=$(file_hunks "$BASE" "$f")
     rel=${f#$owner/}
     # A Next.js route folder — [id], [[...slug]] — is a glob expression to
     # Stryker, which refuses "Cannot combine a glob expression with a mutation

package/hooks/ship-log.mjs

@@ -12,10 +12,10 @@ 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 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\\nDIARY_DIR=%s\\n" "$GAUNTLET_SHIP_LOG" "$GAUNTLET_SHIP_LOG_DIR" "$(diary_dir "$1")"';
   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 };
+  return { on: value("SHIP_LOG_ON") === "1", dir: value("SHIP_LOG_DIR") || join(process.env.HOME ?? "", ".claude", "ship-logs"), diary: value("DIARY_DIR"), root };
 }
 
 function identity(root) {
@@ -106,6 +106,33 @@ function addStep(record, [name, edge]) {
   if (step.start && step.end) step.seconds = Math.round((Date.parse(step.end) - Date.parse(step.start)) / 1000);
 }
 
+// Worktrees share one diary, so only this branch's latest review since the ship started counts.
+function lastReview(diary, branch, since) {
+  const file = join(diary, "review-findings.jsonl");
+  const rows = existsSync(file) ? readFileSync(file, "utf8").split("\n").filter(Boolean) : [];
+  const last = rows.map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter((r) => r?.branch === branch && r.ts >= since && typeof r.reply === "string").at(-1);
+  const json = last?.reply.match(/```json\s*([\s\S]*?)```/)?.[1];
+  try {
+    const list = json && JSON.parse(json);
+    return Array.isArray(list) ? { ts: last.ts, count: list.length } : null;
+  } catch { return null; }
+}
+
+// Agents skipped the log's steps even when the text sat inside them, so the PR hook asks this.
+// A ship with no review (a release, a forced run) is never held.
+function missing(record, c) {
+  const review = lastReview(c.diary, record.branch, record.started);
+  if (!review) return [];
+  const quote = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+  const cmd = (args) => `SHIP_LOG_ROOT=${quote(c.root)} node ${quote(join(HERE, "ship-log.mjs"))} ${args}`;
+  const out = [];
+  if (!record.steps.review?.end) out.push(cmd("step review end"));
+  const have = record.findings.filter((f) => f.by === "review" && f.ts >= review.ts).length;
+  if (have < review.count) out.push(`${cmd("finding '<json>'")} for every review finding: ${have} of ${review.count} logged; a duplicate is verdict "skipped", note "duplicate of <what>"`);
+  return out;
+}
+
 function run(mode, args) {
   const c = conf();
   if (mode === "report") return printReport(args[0] ?? c.dir);
@@ -113,8 +140,13 @@ function run(mode, args) {
   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 === "ready") {
+    const todo = existsSync(path) ? missing(record, c) : [];
+    if (todo.length) console.log(todo.map((t) => `  - ${t}`).join("\n"));
+    return todo.length ? 1 : 0;
+  }
+  // A gate run or a review outside /ship is not a ship; only /ship's start opens one.
+  if ((mode === "gate" || mode === "step") && !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);
@@ -123,12 +155,13 @@ function run(mode, args) {
     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]");
+  else throw new Error("usage: ship-log.mjs on | start | ready | gate <report> <exit> <seconds> <base> | step <name> start|end | finding '<json>' | pr <number> | end [reason] | report [dir]");
   save(path, record);
   return 0;
 }
 
 try {
+  if (process.env.SHIP_LOG_ROOT) process.chdir(process.env.SHIP_LOG_ROOT);
   process.exit(run(process.argv[2], process.argv.slice(3)) ?? 0);
 } catch (err) {
   console.error(`ship-log: ${err.message}`);

package/hooks/ship-prep.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+HERE=$(cd "$(dirname "$0")" && pwd)
+. "$HERE/gate-config.sh" || { echo "ship-prep: cannot read $HERE/gate-config.sh"; exit 1; }
+cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || { echo "ship-prep: cannot read ${CLAUDE_PROJECT_DIR:-$PWD}"; exit 1; }
+
+stop() { echo "ship-prep: STOP — $1"; exit 1; }
+
+first_remote() {  # first_remote <branch...> — the first one origin has
+  local b
+  for b in "$@"; do git rev-parse -q --verify "origin/$b" >/dev/null && { echo "$b"; return; }; done
+}
+
+base_branch() { local dev; dev=$(first_remote develop development dev); echo "${dev:-$(first_remote main master)}"; }
+
+start() {
+  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || stop "not a git repo."
+  local branch base dirty behind ahead
+  branch=$(git branch --show-current)
+  [ -n "$branch" ] || stop "Detached HEAD — check out a branch first."
+  if git remote | grep -qx origin; then git fetch -q origin 2>/dev/null; else echo "remote none: pr, merge and release cannot run"; fi
+  base=$(base_branch)
+  echo "branch $branch"
+  echo "base ${base:-none} (main $(first_remote main master))"
+  if ! git rev-parse -q --verify HEAD >/dev/null; then echo "commits none"
+  elif [ -n "$base" ]; then
+    read -r behind ahead < <(git rev-list --left-right --count "origin/$base...HEAD")
+    echo "ahead $ahead, behind $behind of origin/$base"
+  fi
+  dirty=$(git status --porcelain)
+  echo "uncommitted $(printf '%s' "$dirty" | grep -c .)"
+  [ -n "$dirty" ] && printf '%s\n' "$dirty" | sed 's/^/  /'
+  if gh auth status >/dev/null 2>&1; then
+    echo "gh logged in"
+    echo "pr $(gh pr view --json state,number,url -q '.state+" #"+(.number|tostring)+" "+.url' 2>/dev/null || echo none)"
+  else
+    echo "gh NOT logged in: pr, merge and release cannot run"
+  fi
+  bash "$HERE/ship-mark.sh" begin || stop "ship-mark.sh begin failed."
+}
+
+skills_report() {  # skills_report <files...>
+  local f name paths hits
+  for f in "$(diary_dir "$HERE")"/skills/*/SKILL.md; do
+    [ -f "$f" ] || continue
+    name=$(skill_field "$f" name); paths=$(skill_field "$f" '[[:space:]]*gate-paths')
+    if [ -z "$paths" ]; then echo "skill $name: decide from its description"; continue; fi
+    hits=$(skill_hits "$paths" "$@" | paste -sd' ' -)
+    if [ -n "$hits" ]; then echo "skill $name: audit $hits"; else echo "skill $name: skip, no changed file matches $paths"; fi
+  done
+}
+
+scope() {
+  local branch scope base files=() diff f
+  cd "$(git rev-parse --show-toplevel)" || stop "cannot find the repo root."
+  branch=$(git branch --show-current)
+  scope=$(bash "$HERE/ship-gate.sh" --scope) || stop "ship-gate.sh --scope failed: $scope"
+  printf '%s\n' "$scope"
+  base=$(printf '%s\n' "$scope" | sed -n '1s/^base //p')
+  while IFS=$'\t' read -r f _; do [ -n "$f" ] && files+=("$f"); done < <(printf '%s\n' "$scope" | sed '1d')
+  skills_report "${files[@]}"
+  diff="/tmp/claude-ship-$(printf '%s %s' "$PWD" "$branch" | cksum | cut -d' ' -f1).diff"
+  : > "$diff"
+  if [ ${#files[@]} -gt 0 ]; then
+    git diff "$base" -- "${files[@]}" >> "$diff"
+    for f in "${files[@]}"; do
+      git ls-files --error-unmatch "$f" >/dev/null 2>&1 || git diff --no-index /dev/null "$f" >> "$diff"
+    done
+  fi
+  echo "diff $diff"
+  echo "review /code-review medium origin/$(base_branch)...$branch"
+  node "$HERE/ship-log.mjs" step audit start >/dev/null 2>&1
+  node "$HERE/ship-log.mjs" step review start >/dev/null 2>&1
+  return 0
+}
+
+secrets() {
+  local branch names hits
+  branch=$(git branch --show-current)
+  case "$branch" in main|master|develop|development|dev) stop "on protected branch $branch — commit on a feature or hotfix/<desc> branch." ;; esac
+  git status --short
+  names=$({ git diff HEAD --name-only --diff-filter=d; git ls-files --others --exclude-standard; } 2>/dev/null \
+    | grep -iE '(^|/)(\.env(\..*)?|[^/]*\.pem|[^/]*credentials[^/]*|[^/]*\.key)$' | grep -viE '\.(example|sample|template)$')
+  hits=$({ git diff HEAD; git ls-files --others --exclude-standard -z | xargs -0 -r -I{} git diff --no-index /dev/null {}; } 2>/dev/null \
+    | grep -E '^\+' | grep -E 'AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|xox[abprs]-[A-Za-z0-9-]{10,}|[Bb]earer [A-Za-z0-9._~+/-]{20,}' | cut -c1-120)
+  [ -z "$names$hits" ] && { echo "secrets none"; return 0; }
+  echo "secrets FOUND — STOP and tell the user; suggest gitleaks or git-secrets as a pre-commit guard:"
+  [ -n "$names" ] && printf '%s\n' "$names" | sed 's/^/  file /'
+  [ -n "$hits" ] && printf '%s\n' "$hits" | sed 's/^/  line /'
+  return 1
+}
+
+CHECKS_FAILED='[.statusCheckRollup[]? | select(((.conclusion // .state) // "") | test("FAILURE|ERROR|CANCELLED|TIMED_OUT|ACTION_REQUIRED")) | (.name // .context)] | join(",")'
+CHECKS_RUNNING='[.statusCheckRollup[]? | select((.status // .state // "") | test("IN_PROGRESS|QUEUED|PENDING|WAITING")) | (.name // .context)] | join(",")'
+PR_JQ="[.number, .isDraft, .mergeable, (.reviewDecision // \"\"), ($CHECKS_FAILED), ($CHECKS_RUNNING), .baseRefName, .headRefName] | map(tostring) | join(\"|\")"
+
+merge_check() {  # merge_check [pr]; sets PR_BASE and PR_HEAD
+  local line n draft mergeable review failing pending why=""
+  line=$(gh pr view ${1:+"$1"} --json number,isDraft,mergeable,reviewDecision,statusCheckRollup,baseRefName,headRefName -q "$PR_JQ") || stop "no open PR found."
+  IFS='|' read -r n draft mergeable review failing pending PR_BASE PR_HEAD <<< "$line"
+  [ "$draft" = true ] && why="$why draft;"
+  [ "$mergeable" = CONFLICTING ] && why="$why conflicts with the base;"
+  [ -n "$failing" ] && why="$why CI failing: $failing;"
+  case "$review" in REVIEW_REQUIRED|CHANGES_REQUESTED) why="$why review: $review;" ;; esac
+  [ -n "$pending" ] && why="$why CI still running: $pending;"
+  [ -z "$why" ] && { echo "merge ok #$n"; return 0; }
+  echo "merge STOP #$n:$why"; return 1
+}
+
+land() {  # land <pr> [squash|merge]
+  local worktree=""
+  [ -n "${1:-}" ] || stop "usage: ship-prep.sh land <pr> [squash|merge]"
+  merge_check "$1" >/dev/null || { merge_check "$1"; exit 1; }
+  [ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] && worktree=1
+  if [ "${2:-squash}" = merge ]; then gh pr merge "$1" --merge || stop "gh pr merge failed."
+  elif [ -n "$worktree" ]; then
+    # gh --delete-branch switches the local checkout, which a worktree cannot; delete the branch on origin instead.
+    gh pr merge "$1" --squash || stop "gh pr merge failed."
+    git push -q origin --delete "$PR_HEAD" 2>/dev/null
+  else gh pr merge "$1" --squash --delete-branch || stop "gh pr merge failed."; fi
+  if [ -n "$worktree" ]; then
+    git fetch -q origin 2>/dev/null
+    echo "landed #$1; this is a worktree, so it stays on its branch — close the session to remove it"
+  else
+    git checkout -q "$PR_BASE" && git pull -q --ff-only origin "$PR_BASE" 2>/dev/null
+    echo "landed #$1; now on $(git branch --show-current) at $(git rev-parse --short HEAD)"
+  fi
+}
+
+release() {
+  local tag v major minor patch commits breaking feat next
+  git fetch -q --tags origin 2>/dev/null
+  tag=$(git tag --sort=-v:refname | head -1)
+  [ -n "$tag" ] || { echo "tag none; suggest v0.1.0 (confirm with the user)"; return 0; }
+  commits=$(git log "$tag"..HEAD --format='%s')
+  [ -n "$commits" ] || stop "no commits since $tag — nothing to release."
+  v=${tag##*[!0-9.]}; IFS=. read -r major minor patch <<< "$v"
+  breaking=$(( $(printf '%s\n' "$commits" | grep -cE '^[a-z]+(\([^)]*\))?!:') + $(git log "$tag"..HEAD --format=%B | grep -c 'BREAKING CHANGE') ))
+  feat=$(printf '%s\n' "$commits" | grep -cE '^feat(\([^)]*\))?!?:')
+  if [ "$major" -ge 1 ]; then
+    if [ "$breaking" -gt 0 ]; then next="$((major+1)).0.0"; elif [ "$feat" -gt 0 ]; then next="$major.$((minor+1)).0"; else next="$major.$minor.$((patch+1))"; fi
+  elif [ "$breaking" -gt 0 ]; then next="0.$((minor+1)).0"
+  else next="0.$minor.$((patch+1))"; fi
+  echo "tag $tag"
+  echo "suggest ${tag%"$v"}$next (confirm with the user)"
+  printf '%s\n' "$commits" | sed 's/^/  /'
+}
+
+case "${1:-}" in
+  start) start ;;
+  scope) scope ;;
+  secrets) secrets ;;
+  merge) merge_check "${2:-}" ;;
+  land) land "${2:-}" "${3:-}" ;;
+  release) release ;;
+  *) echo "usage: ship-prep.sh start | scope | secrets | merge [pr] | land <pr> [squash|merge] | release" >&2; exit 2 ;;
+esac

package/hooks/skill-flags-record.sh

@@ -20,8 +20,13 @@ MODEL=""
 [ -f "$TRANSCRIPT" ] && MODEL=$(grep -o '"model":"[^"]*"' "$TRANSCRIPT" | tail -1 | sed 's/.*:"//; s/"$//')
 
 . "$SCRIPT_DIR/gate-config.sh" 2>/dev/null || exit 0
-BRANCH=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null | json_string)
+CWD=$(json_field "$INPUT" cwd)
+# A review run in a worktree belongs to the worktree's branch, not the main folder's.
+BRANCH=$(git -C "${CWD:-$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" \
   >> "$(diary_dir "$SCRIPT_DIR")/$LOG"
 
+case "$LOG" in skill-flags.jsonl) STEP=audit ;; *) STEP=review ;; esac
+SHIP_LOG_ROOT="${CWD:-$PROJECT_DIR}" node "$SCRIPT_DIR/ship-log.mjs" step "$STEP" end >/dev/null 2>&1
+
 exit 0

package/hooks/skill-gate.sh

@@ -4,6 +4,7 @@
 INPUT=$(cat)
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+. "$SCRIPT_DIR/gate-config.sh"
 PROJECT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
 
 if ! find "$PROJECT_DIR" -path '*/.claude/skills/*/SKILL.md' 2>/dev/null | grep -q .; then
@@ -130,25 +131,14 @@ if [ -n "$TARGETS" ]; then
     #
     # The value must be quoted in YAML either way: a scalar opening with * is
     # an alias indicator.
-    UNQUOTE='s/^["'"'"']//; s/["'"'"']$//'
-    SPATHS=$(sed -n 's/^[[:space:]]*gate-paths:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
-    STRACKS=$(sed -n 's/^tracks:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
-    SNAME=$(sed -n 's/^name:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
+    SPATHS=$(skill_field "$SKILL_FILE" '[[:space:]]*gate-paths')
+    STRACKS=$(skill_field "$SKILL_FILE" tracks)
+    SNAME=$(skill_field "$SKILL_FILE" name)
     [ -z "$SPATHS" ] && continue
     [ -z "$SNAME" ] && continue
     case "$INSTALLED" in *"\"$SNAME\""*) ;; *) continue ;; esac  # automark marks only installed and custom skills
-
-    HIT=""
-    for G in $(printf '%s' "$SPATHS" | tr ',' ' '); do
-      # Claude Code writes these gitignore-style. A case glob has no **, but *
-      # already crosses / here, so dropping the **/ prefix is equivalent.
-      G=$(printf '%s' "$G" | sed 's!\*\*/!!g')
-      case "$G" in \**|/*) ;; *) G="*$G" ;; esac
-      for T in $TARGETS; do
-        case "$T" in $G) HIT=1 ;; esac
-      done
-    done
-    [ -z "$HIT" ] && continue
+    # shellcheck disable=SC2086
+    [ -n "$(skill_hits "$SPATHS" $TARGETS)" ] || continue
 
     # A .tsx file is not proof of React — it could be Astro, Solid or Preact.
     # The packages the skill tracks are the proof, so the manifests decide.

package/lib/setup-hook.mjs

@@ -22,6 +22,7 @@ import { homedir } from "node:os";
 //   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
+//   ship-prep.sh              run by /ship — prechecks, scope and skills in one call
 //   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
@@ -55,6 +56,7 @@ 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 SHIP_PREP_FILENAME = "ship-prep.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -163,6 +165,7 @@ export async function setupHook(targetDir = process.cwd()) {
     SHIP_LOG_PARSE_FILENAME,
     SHIP_LOG_REPORT_FILENAME,
     SHIP_MARK_FILENAME,
+    SHIP_PREP_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.56.2",
+  "version": "2.57.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/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/",
+    "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 ../scripts/ship-prep.sh hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {