@spardutti/claude-skills 2.31.0 → 2.32.0

package/hooks/ship-gate.sh

@@ -0,0 +1,506 @@
+#!/usr/bin/env bash
+# ship-gate.sh — the deterministic half of /ship's quality gate.
+#
+# File length and mutation are not judgement calls, so they do not live in prose
+# where a model can decide they are not worth it. They live here, behind an exit
+# code. /ship runs this and obeys the result; the skills audit stays in the
+# command, because that one genuinely needs a model.
+#
+#   bash .claude/hooks/ship-gate.sh [base-ref]
+#   bash .claude/hooks/ship-gate.sh --key      print the receipt key and stop
+#   bash .claude/hooks/ship-gate.sh --force    write a FORCED receipt, run nothing
+#   bash .claude/hooks/ship-gate.sh --baseline record today's mutmut survivors as
+#                                              accepted debt, write no receipt
+#
+# On completion it writes a RECEIPT at /tmp/claude-shipgate-<key>, and the
+# PreToolUse hook refuses `git commit` / `git push` without a matching one. The
+# point is that a gate has to be evidence rather than an instruction: a sentence
+# saying "run this first" is a sentence an agent can decide is not worth it, and
+# then report a pass it never earned. A receipt cannot be reported, only produced.
+#
+# The key is the content of everything about to ship, so it is the same before
+# and after `git commit` — and it changes the moment anything is edited, which is
+# what makes a fix re-gate itself instead of riding on the previous verdict.
+#
+# Exit codes:
+#   0  clean — nothing over the line limit, nothing survived, nothing uncovered
+#   1  findings that must be dealt with before shipping
+#   2  ran, but could not prove the tests (a mutation tool is missing) — report,
+#      don't block; the output names exactly what to install and where
+#
+# Config: the same .claude/gauntlet.conf as the Stop hook.
+#   GAUNTLET_MAX_LINES=200   the per-file limit; 0 turns the check off
+#   GAUNTLET_SOURCE_EXT=...  which extensions count as source. Deliberately NOT
+#                            GAUNTLET_CODE_EXT: the Stop hook's key answers a
+#                            different question, and a docs repo sets it to .md
+#   GAUNTLET_IGNORE_EXT=...  extensions that need no gate at all. An extension in
+#                            neither list is reported UNPROVEN rather than passed
+#   GAUNTLET_IGNORE_FILES=.. space-separated globs, matched against /<path>, for
+#                            files nobody wrote: generated code and vendored
+#                            components. They are named in the output, never
+#                            dropped silently. Set it to "" to gate everything
+#   GAUNTLET_MUTATE="cmd"    one explicit mutation command for the whole repo,
+#                            replacing per-project detection. $MUTATE_FLAGS holds
+#                            the --mutate flags, $FILES the changed files.
+
+set -uo pipefail
+
+MODE=""
+case "${1:-}" in
+  --key)      MODE=key; shift ;;
+  --force)    MODE=force; shift ;;
+  --baseline) MODE=baseline; shift ;;
+esac
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$PROJECT_DIR" 2>/dev/null || { echo "ship-gate: cannot read $PROJECT_DIR"; exit 1; }
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "ship-gate: not a git repo"; exit 1; }
+
+# `git diff --name-only` prints paths from the repo ROOT, but CLAUDE_PROJECT_DIR
+# can point at a subdirectory of it. Testing those paths from the subdirectory
+# found no files at all, so the gate said "nothing to check" and wrote a PASS
+# receipt over a diff it never looked at. Work from the root and the paths git
+# prints are the paths this script tests. The receipt key moves with it, and the
+# PreToolUse hook asks this script for the key rather than computing its own, so
+# the two cannot disagree.
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -n "$ROOT" ]; then
+  cd "$ROOT" || { echo "ship-gate: cannot read $ROOT"; exit 1; }
+  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|json|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 */*.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"
+[ -f ".claude/gauntlet.conf" ] && . ".claude/gauntlet.conf"
+
+# ------------------------------------------------------------------- the scope
+BASE="${1:-}"
+if [ -z "$BASE" ]; then
+  BASE=$(git merge-base HEAD develop 2>/dev/null \
+         || git merge-base HEAD main 2>/dev/null \
+         || git rev-list --max-parents=0 HEAD | head -1)
+fi
+
+CHANGED=$( { git diff "$BASE"...HEAD --name-only 2>/dev/null
+             git diff HEAD --name-only 2>/dev/null
+             git ls-files --others --exclude-standard 2>/dev/null; } | sort -u )
+
+# 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
+# away a receipt the gate would have re-earned unchanged — fifteen minutes of
+# mutation testing to prove nothing about the file that moved, at the one moment
+# a release is trying to ship. An ignored extension is one no check here opens,
+# so it cannot change a verdict. Unknown extensions stay in, because UNPROVEN is
+# a verdict about exactly those.
+KEYED=$(printf '%s\n' "$CHANGED" | grep -viE "\.($GAUNTLET_IGNORE_EXT)$")
+
+# The repo path plus the names and contents of the changed files, in a fixed
+# order. The path is in there because the key is otherwise pure content: two
+# repos holding the same file would share a receipt, and one would be waved
+# through on the other's verdict. Deliberately not a diff: a file moves from "untracked" to "in the diff" at commit time, so a
+# diff-based key changes when the content did not, and the receipt would go stale
+# the moment it was committed. This is identical either side of a commit, and
+# changes the instant any of those files is edited.
+RECEIPT_KEY=$( { printf '%s\n' "$PROJECT_DIR"
+                 printf '%s\n' "$KEYED" | while IFS= read -r f; do
+                   [ -n "$f" ] || continue
+                   printf '%s\n' "$f"
+                   [ -f "$f" ] && cat "$f"
+                 done; } | git hash-object --stdin )
+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
+SOURCED=$(printf '%s\n' "$CHANGED" | grep -E "\.($GAUNTLET_SOURCE_EXT)$" \
+        | grep -vE '(\.|_)(test|spec)\.[^.]+$|(^|/)tests?/|(^|/)\.stryker-tmp/' | while read -r f; do
+          [ -f "$f" ] && printf '%s\n' "$f"
+        done)
+
+# A generated file cannot be split and a vendored one is not ours to split, so
+# the length check fires on every route regeneration and teaches people to
+# --force. A gate that is always forced is not a gate. These are held out of
+# both checks — and printed, because a silent skip is the same lie as a fake
+# PASS. The leading / is what lets one pattern match components/ui at the repo
+# root and apps/web/src/components/ui alike.
+#
+# */*.config.* is here for the same reason, and became urgent the moment an
+# 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)
+IGNORED=$(printf '%s\n' "$SOURCED" | while IFS= read -r f; do
+            [ -n "$f" ] && is_ignored "$f" && printf '%s\n' "$f"
+          done)
+if [ -n "$IGNORED" ]; then
+  echo "ship-gate: not gated, matched GAUNTLET_IGNORE_FILES:"
+  printf '%s\n' "$IGNORED" | sed 's/^/  /'
+fi
+
+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
+  # the list named, so zero source files were found and a PASS receipt was
+  # written over work nothing had checked. An extension this gate cannot place is
+  # UNPROVEN: it does not block, but it never claims a pass either.
+  UNKNOWN=$(printf '%s\n' "$CHANGED" | grep -E '\.[A-Za-z0-9]+$' \
+            | grep -viE "\.($GAUNTLET_SOURCE_EXT)$" \
+            | grep -viE "\.($GAUNTLET_IGNORE_EXT)$" \
+            | sed 's/.*\.//' | sort -u | tr '\n' ' ')
+  if [ -n "$UNKNOWN" ]; then
+    echo "ship-gate: UNPROVEN — nothing here was checked. These changed files are"
+    echo "  in a language this gate does not know: $UNKNOWN"
+    echo "  If they are source, add the extension in .claude/gauntlet.conf:"
+    echo "    GAUNTLET_SOURCE_EXT=\"\$GAUNTLET_SOURCE_EXT|${UNKNOWN%% *}\""
+    echo "  If they are not, add it to GAUNTLET_IGNORE_EXT the same way."
+    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
+fi
+
+echo "ship-gate: $(printf '%s\n' "$FILES" | wc -l) changed code file(s), base $(git rev-parse --short "$BASE")"
+echo
+STATUS=0
+
+# ------------------------------------------------- check 1: file length (hard)
+OVER=""
+LARGEST=0
+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)
+"
+  done <<< "$FILES"
+fi
+
+if [ "$GAUNTLET_MAX_LINES" -le 0 ]; then
+  echo "FILE LENGTH — off (GAUNTLET_MAX_LINES=0)"
+elif [ -n "$OVER" ]; then
+  echo "FILE LENGTH — over the limit:"
+  printf '%s' "$OVER"
+  echo "  Splitting a file is a design decision. Do it deliberately, or ship with --force."
+  STATUS=1
+else
+  echo "FILE LENGTH — ok, largest is $LARGEST lines"
+fi
+
+# ---------------------------------------------------------- which project owns
+# A monorepo holds several projects, each with its own runner and its own
+# mutation tool. Walk up from each changed file to the nearest manifest.
+# mutmut is installed into the project's environment, not onto PATH. Ask the
+# project how to run its own tools before falling back to a bare binary.
+py_mutmut() {
+  d="$1"
+  # Returned relative to the PROJECT, because the command runs from inside it.
+  # Tests that need a database, a queue, or any other service cannot run on the
+  # host: mutmut still generates every mutant and reports them all "not
+  # checked", which prints exactly like a clean run. An executable .mutmut-run
+  # in the project runs mutmut wherever those services are — typically
+  # `docker compose run` against the app container — and takes precedence over
+  # every host-local option below.
+  if [ -x "$d.mutmut-run" ]; then printf './.mutmut-run\n'; return; fi
+  if [ -x "$d.venv/bin/mutmut" ]; then printf './.venv/bin/mutmut\n'; return; fi
+  if [ -f "$d""uv.lock" ] && command -v uv >/dev/null 2>&1; then printf 'uv run mutmut\n'; return; fi
+  if [ -f "$d""poetry.lock" ] && command -v poetry >/dev/null 2>&1; then printf 'poetry run mutmut\n'; return; fi
+  command -v mutmut >/dev/null 2>&1 && printf 'mutmut\n'
+}
+
+owner_of() {
+  d=$(dirname "$1")
+  while :; do
+    if [ -f "$d/package.json" ] || [ -f "$d/pyproject.toml" ] \
+       || [ -f "$d/pytest.ini" ] || [ -f "$d/setup.cfg" ]; then
+      printf '%s\n' "${d#./}"; return
+    fi
+    [ "$d" = "." ] || [ "$d" = "/" ] && { printf '.\n'; return; }
+    d=$(dirname "$d")
+  done
+}
+
+OWNERS=$(while IFS= read -r f; do owner_of "$f"; done <<< "$FILES" | sort -u)
+
+# --------------------------------------------- check 2: mutation, per project
+echo
+echo "MUTATION — $(printf '%s\n' "$OWNERS" | wc -l) project(s) in this diff"
+MISSING=""
+
+for owner in $OWNERS; do
+  [ "$owner" = "." ] && label="<repo root>" || label="$owner/"
+  OWNED=$(while IFS= read -r f; do
+            [ "$(owner_of "$f")" = "$owner" ] && printf '%s\n' "$f"
+          done <<< "$FILES" | grep -vE "$GAUNTLET_NO_MUTATE" || true)
+  [ -z "$OWNED" ] && continue
+
+  # ONE comma-joined --mutate value, never a flag per range. Stryker's CLI
+  # parses --mutate with `(val) => val.split(",")`, a coercion that ignores the
+  # previous value, so a repeated flag OVERRIDES instead of appending and only
+  # the last one survives. Measured on two files: the repeated form found 1 of
+  # 1808 files and 28 mutants, the joined form 2 files and 51. Every run since
+  # this gate shipped mutated exactly one file and called the rest proven — and
+  # when that one file had no tests, Stryker exited on "No tests were executed"
+  # and the gate reported UNPROVEN, which writes a receipt and blocks nothing.
+  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")"
+    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
+    # range" and fails the entire run, not just that file. Escaping the brackets
+    # stops the path resolving at all. Replacing each with ? keeps it matching
+    # that one file and drops the range, so the file is mutated whole: a
+    # 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," ;;
+      *) for r in $hunks; do FLAGS="$FLAGS,$rel:$r"; done ;;
+    esac
+  done <<< "$OWNED"
+
+  base=""; RUN=""
+  if [ "$owner" != "." ]; then base="$owner/"; RUN="cd '$owner' && "; fi
+  if [ -n "$GAUNTLET_MUTATE" ]; then
+    CMD="$GAUNTLET_MUTATE"; TOOL="config"
+  elif [ -f "$base"package.json ] && grep -qs '@stryker-mutator/core' "$base"package.json; then
+    TOOL="stryker"
+    # From inside the owning package: npx resolves against ITS node_modules, and
+    # stryker.config.json lives there too. A monorepo root usually has neither.
+    #
+    # Deliberately NOT --incremental. --force does rerun every mutant in scope,
+    # so the diff itself was always judged fresh — but incremental mode still
+    # merges reports/stryker-incremental.json into the REPORT for everything
+    # out of scope, and this gate greps the whole report. Survivors recorded
+    # months ago came back as findings against a diff that never touched them:
+    # 8 of them on one commit, all long since killed. --mutate already scopes
+    # the run to the changed hunks, so incremental buys nothing here and costs
+    # a cache that goes stale exactly the way mutmut's did.
+    CMD="${RUN}npx --no-install stryker run --mutate '${FLAGS#,}'"
+  elif [ -f "$base"package.json ]; then
+    MISSING="$MISSING  $label needs Stryker:
+      npm --prefix ${owner} i -D @stryker-mutator/core @stryker-mutator/vitest-runner
+      then ${base}stryker.config.json:
+        {\"testRunner\":\"vitest\",\"plugins\":[\"@stryker-mutator/vitest-runner\"],\"coverageAnalysis\":\"perTest\"}
+"
+    continue
+  elif [ -n "$(py_mutmut "$base")" ]; then
+    TOOL="mutmut"
+    # mutmut takes its scope from [tool.mutmut] in pyproject, not from a flag:
+    # --paths-to-mutate was 2.x, and 3.x filters by fnmatch globs over mutant
+    # NAMES (app.balance.reserve.*). There is no per-line scoping at all.
+    #
+    # `mutmut run` prints 🙁 for a survivor and exits 0 either way — parsing it
+    # reports clean with survivors sitting there, which is a false green and
+    # worse than reporting nothing. `mutmut results` is the readable source:
+    # it prints "<mutant name>: survived" per survivor.
+    M="$(py_mutmut "$base")"
+    # mutmut caches verdicts in ./mutants and only invalidates one when the
+    # SOURCE of that function changes. Adding a test does not, so it replays the
+    # old "survived" and calls mutants the new tests kill still alive — measured
+    # at 20 of them on one commit. `results` then prints that whole cache, so
+    # survivors turn up for files nowhere near the diff. Deleting the dir first
+    # makes both describe the tree being shipped; `mutmut run` rewrites it
+    # anyway, and a cold run is ~35s for ~1000 mutants.
+    # One cd for all three: they run in the same shell, already there.
+    CMD="${RUN}rm -rf mutants; $M run >/dev/null 2>&1; $M results"
+  else
+    MISSING="$MISSING  $label needs mutmut:
+      uv add --dev mutmut     # or: poetry add --group dev mutmut, pip install mutmut
+      then ${base}pyproject.toml:
+        [tool.mutmut]
+        source_paths = [\"src/\"]
+        pytest_add_cli_args_test_selection = [\"tests/\"]
+      (mutmut 3 renamed these — paths_to_mutate/tests_dir are 2.x and are ignored)
+"
+    continue
+  fi
+
+  OUT=$(eval "$CMD" 2>&1); RC=$?
+  # Match a finding, never a summary row. Stryker prints a `# survived` COLUMN
+  # HEADER every run and repeats the word in its table, so a bare grep reports
+  # survivors on a clean run — worse than not running at all. Stryker marks each
+  # real finding `[Survived]`; table and border lines are excluded outright.
+  # 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.
+  #
+  # The status line carries no file name; the line under it does, as
+  # file:line:column. They are paired here rather than grepped separately.
+  if [ "$TOOL" = stryker ]; then
+    ALL=$(printf '%s\n' "$OUT" | awk -v globbed="$GLOBBED" '
+      /^\[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
+        pend = ""
+      }
+      # A survivor with no location under it is still a survivor, never dropped.
+      END { if (pend != "" && kind == "s") print pend }
+    ')
+  else
+    ALL=$(printf '%s\n' "$OUT" | grep -E '[Ss]urvived' \
+          | grep -vE '^[[:space:]]*[#│|+-]|# *surviv')
+  fi
+  # The detail list is capped so one bad file cannot bury the output. The cap
+  # used to be the whole story, and it hid the WORST file: 20 findings from one
+  # file filled it, and a second file with 54 uncovered mutants never appeared
+  # at all. A gate whose biggest finding is invisible gets under-fixed. Every
+  # file with findings is now named below the cut, worst first.
+  FOUND=$(printf '%s\n' "$ALL" | grep -c .)
+  SURVIVED=$(printf '%s\n' "$ALL" | head -20)
+  FIXED=0
+  NOTE=""
+
+  # Stryker takes --mutate per changed hunk, so it already answers "did YOUR
+  # change get tested". mutmut cannot be asked that — 3.x dropped 1.x's
+  # --use-patch-file and never replaced it — so it mutates all of source_paths
+  # and reports the repo's entire backlog. Held to the same bar, the Python half
+  # answers "is this repo perfect" instead, which it never is, so it could never
+  # go green. The baseline supplies the missing half: survivors recorded once
+  # are accepted debt, and only a name that is not in it fails the gate.
+  #
+  # A mutant name carries an index within its own function, not a line number,
+  # so editing elsewhere in the file does not rename it — and editing the
+  # function itself DOES, which correctly re-charges its survivors to that edit.
+  if [ "$TOOL" = mutmut ]; then
+    BL="$base.mutmut-baseline"
+    NOWF=$(mktemp)
+    printf '%s\n' "$OUT" \
+      | sed -n 's/^[[:space:]]*\([^[:space:]]*\): survived$/\1/p' | sort -u > "$NOWF"
+
+    # When the tests need a service the run cannot reach — a database, a queue
+    # — mutmut still generates every mutant and records it "not checked". No
+    # survivors come out, so the gate printed "nothing survived" and, with no
+    # baseline yet, wrote an EMPTY one and told the user to commit it. That
+    # repo's Python gate could never fail again.
+    #
+    # Counting kills cannot catch it: `mutmut results` SKIPS killed mutants
+    # unless --all (mutmut/__main__.py results()), so a perfect suite and a
+    # suite that ran nothing both print nothing. The status string is what
+    # separates them — "not checked" is exit code None in status_by_exit_code,
+    # meaning the mutant was never executed at all.
+    NOTCHECKED=$(printf '%s\n' "$OUT" | grep -c ': not checked$')
+    if [ "$NOTCHECKED" -gt 0 ]; then
+      echo "  $label mutmut — UNPROVEN: $NOTCHECKED mutant(s) were never run."
+      echo "      They are recorded \"not checked\", so the suite proved nothing"
+      echo "      about them. Usually the tests need a service this run cannot"
+      echo "      reach — a database, a queue. Put an executable .mutmut-run in"
+      echo "      ${base}that runs mutmut where those services are, typically"
+      echo "      docker compose run against the app container; the gate uses"
+      echo "      it ahead of every host-local option."
+      [ "$STATUS" = 0 ] && STATUS=2
+      rm -f "$NOWF"
+      continue
+    fi
+
+    if [ "$MODE" = baseline ]; then
+      cp "$NOWF" "$BL"
+      NOTE="  $label mutmut — baseline set: $(wc -l < "$BL") survivor(s) accepted. Commit $BL."
+      SURVIVED=""
+    elif [ -f "$BL" ]; then
+      # -Fxv against an empty baseline reports every survivor, which is right:
+      # an empty baseline means nothing has been accepted.
+      SURVIVED=$(grep -Fxv -f "$BL" "$NOWF" | head -20)
+      FIXED=$(grep -Fxvc -f "$NOWF" "$BL")
+    else
+      cp "$NOWF" "$BL"
+      NOTE="  $label mutmut — no baseline, so nothing could be compared. Recorded
+      $(wc -l < "$BL") existing survivor(s) in $BL — commit it, then run the
+      gate again. From here only NEW survivors fail; --baseline accepts more."
+      SURVIVED=""
+      [ "$STATUS" = 0 ] && STATUS=2
+    fi
+    rm -f "$NOWF"
+  fi
+
+  if [ -n "$SURVIVED" ]; then
+    echo "  $label $TOOL — these lines can break and no test notices:"
+    printf '%s\n' "$SURVIVED" | sed 's/^/      /'
+    if [ "$FOUND" -gt 20 ]; then
+      echo "      ... $((FOUND - 20)) more not shown. Every file with findings:"
+      if [ "$TOOL" = stryker ]; then
+        printf '%s\n' "$ALL" \
+          | awk '{ f = $NF; sub(/:[0-9]+:[0-9]+$/, "", f); n[f]++ }
+                 END { for (k in n) printf "%8d  %s\n", n[k], k }' \
+          | sort -rn | sed 's/^/      /'
+      fi
+    fi
+    [ "$FIXED" -gt 0 ] && echo "      ($FIXED baselined survivor(s) now killed — --baseline banks them)"
+    STATUS=1
+  elif [ $RC -ne 0 ]; then
+    echo "  $label $TOOL — the run failed:"
+    printf '%s\n' "$OUT" | tail -12 | sed 's/^/      /'
+    [ "$STATUS" = 0 ] && STATUS=2
+  elif [ -n "$NOTE" ]; then
+    printf '%s\n' "$NOTE"
+  else
+    echo "  $label $TOOL — ok, nothing survived and nothing was uncovered"
+    [ "$FIXED" -gt 0 ] && echo "      ($FIXED baselined survivor(s) now killed — --baseline banks them)"
+  fi
+done
+
+if [ -n "$MISSING" ]; then
+  echo "  UNPROVEN — no mutation tool for these, so their tests were never shown"
+  echo "  to catch a break. Install per project:"
+  printf '%s' "$MISSING"
+  [ "$STATUS" = 0 ] && STATUS=2
+fi
+
+if [ "$MODE" = baseline ]; then
+  echo
+  echo "ship-gate: baselines updated. No receipt written — run the gate for real."
+  exit 0
+fi
+
+# The receipt is written by this script and nothing else. A hand-rolled check
+# produces no receipt, which is the whole point: substituting a weaker check is
+# a choice that can be argued for, but it cannot be passed off as this one.
+echo
+case $STATUS in
+  0) echo "ship-gate: PASS"
+     printf 'PASS %s\n' "$(date -u +%FT%TZ)" > "$RECEIPT" ;;
+  1) echo "ship-gate: FAIL — deal with the findings above, then run this again."
+     echo "           To ship anyway: bash .claude/hooks/ship-gate.sh --force"
+     rm -f "$RECEIPT" ;;
+  2) echo "ship-gate: UNPROVEN — nothing is wrong, but nothing was proven either"
+     printf 'UNPROVEN %s\n' "$(date -u +%FT%TZ)" > "$RECEIPT" ;;
+esac
+exit $STATUS

package/hooks/skill-application-gate.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# PreToolUse application gate: blocks file edits until each loaded skill
+# has been explicitly applied (acked) for this session.
+
+INPUT=$(cat)
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+SESSION_ID=$(printf '%s' "$INPUT" | grep -o '"session_id":"[^"]*"' | head -1 | sed 's/"session_id":"//; s/"$//')
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+# Keyed exactly as the loading gate and the automark key it — see those two.
+# A subagent carries the parent's session_id, so all three must agree.
+AGENT_ID=$(printf '%s' "$INPUT" | grep -o '"agent_id":"[^"]*"' | head -1 | sed 's/"agent_id":"//; s/"$//')
+KEY="$SESSION_ID"
+if [ -n "$AGENT_ID" ]; then
+  KEY=$(printf '%s' "$AGENT_ID" | tr -cd 'A-Za-z0-9_-')
+fi
+
+# Defer to the loading gate until it's been satisfied for this key.
+if [ ! -f "/tmp/claude-skill-gate-$KEY" ]; then
+  exit 0
+fi
+
+# Same reason as the loading gate: Bash can write files, and a heredoc into an
+# interpreter shows no redirect at all.
+
+# Skills are about code. Blocking a plan document to ask how the React rules
+# apply is pure noise, and a repo full of PLAN_*.md hits it on every write.
+# Config files stay gated — skills do have rules about tsconfig and compose.
+PROSE_EXT='md|mdx|txt|rst|adoc|png|jpg|jpeg|gif|svg|webp|ico'
+CODE_EXT='ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|sql|sh|json|ya?ml|toml'
+
+TOOL=$(printf '%s' "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | sed 's/.*:"//; s/"$//')
+
+if [ "$TOOL" != "Bash" ]; then
+  # The structured tools name their target outright.
+  TARGET=$(printf '%s' "$INPUT" | grep -o '"file_path":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+  case "$TARGET" in
+    # The settings file that configures the escape hatch cannot sit behind the
+    # gate, or a denied ack has no way to be un-denied.
+    */.claude/settings.json|*/.claude/settings.local.json) exit 0 ;;
+    *.*) printf '%s' "$TARGET" | grep -qiE ".($PROSE_EXT)$" && exit 0 ;;
+  esac
+fi
+if [ "$TOOL" = "Bash" ]; then
+  CMD=$(printf '%s' "$INPUT" | grep -o '"command":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+  case "$CMD" in
+    *claude-skill-gate-*|*claude-skill-acked-*|*claude-skill-loaded-*) exit 0 ;;
+    *.claude/settings.json*|*.claude/settings.local.json*) exit 0 ;;
+  esac
+
+  # A command that names a prose file and no code file is writing prose.
+  if printf '%s' "$CMD" | grep -qiE ".($PROSE_EXT)([^A-Za-z0-9]|$)"      && ! printf '%s' "$CMD" | grep -qiE ".($CODE_EXT)([^A-Za-z0-9]|$)"; then
+    exit 0
+  fi
+  STRIPPED=$(printf '%s' "$CMD" | sed 's![12]*>>*[[:space:]]*/dev/null!!g')
+  WRITES=""
+  case "$STRIPPED" in
+    *">"*|*"tee "*|*"sed -i"*|*"cp "*|*"mv "*|*"truncate "*|*"dd "*) WRITES=1 ;;
+  esac
+  case "$CMD" in
+    *"<<"*|*python*" -c"*|*node*" -e"*|*perl*" -e"*|*ruby*" -e"*) WRITES=1 ;;
+  esac
+  [ -z "$WRITES" ] && exit 0
+fi
+
+
+# Collect every loaded-but-unacked skill so a single ack clears them all.
+UNACKED=""
+for marker in /tmp/claude-skill-loaded-$KEY-*; do
+  [ ! -f "$marker" ] && continue
+  skill_name="${marker##/tmp/claude-skill-loaded-$KEY-}"
+  if [ ! -f "/tmp/claude-skill-acked-$KEY-$skill_name" ]; then
+    UNACKED="$UNACKED $skill_name"
+  fi
+done
+UNACKED="${UNACKED# }"
+
+if [ -z "$UNACKED" ]; then
+  exit 0
+fi
+
+# One touch call with explicit paths — brace expansion is not used because
+# bash leaves a single-element {name} literal, creating a garbage marker.
+ACK_CMD="touch"
+NAMES=""
+RULES_BLOCKS=""
+for skill in $UNACKED; do
+  ACK_CMD="$ACK_CMD /tmp/claude-skill-acked-$KEY-$skill"
+  NAMES="$NAMES, '$skill'"
+  SKILL_MD="$PROJECT_DIR/.claude/skills/$skill/SKILL.md"
+  RULES=""
+  if [ -f "$SKILL_MD" ]; then
+    RULES=$(awk '/^## Rules/{flag=1} /^## /{if(flag && !/^## Rules/)exit} flag' "$SKILL_MD")
+  fi
+  if [ -z "$RULES" ]; then
+    RULES="(Rules section not found in $SKILL_MD — refer to the loaded skill content already in context.)"
+  fi
+  RULES_BLOCKS="$RULES_BLOCKS
+### Rules from $skill/SKILL.md
+
+$RULES
+"
+done
+NAMES="${NAMES#, }"
+
+MSG="BLOCKED: loaded skills not yet applied to your work: $NAMES
+
+Before this Write/Edit, you must:
+
+1. For each skill listed above, say whether it applies to the file you're about to
+   write. If it does not — a Python skill and a TypeScript file, say — write
+   \"does not apply\" and move on. Do not invent a connection.
+2. For the ones that do apply: state the specific rules that bear on this file, and
+   how your next write respects each.
+3. Then ack all of them in a single Bash tool call:
+     $ACK_CMD
+
+One ack per skill per session. After acking, retry the Write/Edit.
+
+If that Bash call is denied by the auto mode classifier, STOP. Do not ask your
+user to run it for you, do not look for another route to create the files, and
+do not try to add the allow rule yourself — an agent editing permission settings
+is denied by the same classifier, so that attempt fails too and costs a round
+trip that ends in the same place. All three are what the classifier is there to
+stop, and asking a human to run a command you were just denied makes them the
+tool that performs it. Report this to them instead and let them decide:
+
+  Auto mode's built-in Auto-Mode Bypass rule counts a hook's ack file as working
+  around the permission system. It is a soft rule, so an allow entry clears it.
+  The user has to add it — you cannot. The shortest route is for them to re-run
+  npx @spardutti/claude-skills and accept the auto mode prompt, which writes it.
+  Otherwise /permissions, Auto mode tab. Editing the file by hand works too, and
+  it has to be ~/.claude/settings.json — the classifier does not read a
+  project's .claude/settings.json. Keep the
+  \$defaults line or every built-in allow rule is discarded:
+
+  \"autoMode\": { \"allow\": [ \"\$defaults\",
+    \"Touching marker files under /tmp/claude-skill-gate-*, /tmp/claude-skill-acked-*
+     and /tmp/claude-skill-loaded-* is allowed: they are acknowledgement files for
+     the user's own PreToolUse skill gates. Creating one satisfies a workflow gate
+     the user installed, grants no permission and executes no code, and is a false
+     positive for Auto-Mode Bypass.\" ] }
+$RULES_BLOCKS"
+
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\r'/\\r}"
+  s="${s//$'\t'/\\t}"
+  printf '"%s"' "$s"
+}
+
+REASON=$(json_escape "$MSG")
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$REASON"
+exit 0