crewforth 0.0.1 → 3.0.0-rc.2

package/kit/hooks/pre-commit

@@ -0,0 +1,577 @@
+#!/usr/bin/env bash
+# Pre-commit gate on staged ADDED lines:
+#  (1) §4.1/§4.2 trace scanner — AI-authorship traces / vendor names (trace-blocklist.txt)
+#  (2) secret scanner        — API keys / tokens / private keys       (secret-blocklist.txt)
+#  (3) private-path scanner  — this machine's $HOME + .private-terms.txt (§4.3)
+# Skipping requires an explicit request per §4.5 (git commit --no-verify).
+set -euo pipefail
+# The 2.x names of the variables a user can set still work (one helper: eval/lib/crew-env.sh).
+_crew_d="${BASH_SOURCE%/*}"; [ "$_crew_d" = "${BASH_SOURCE}" ] && _crew_d=.
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"; unset _crew_d
+HERE="$(cd "$(dirname "$0")" && pwd)"
+BL="$HERE/trace-blocklist.txt"
+SL="$HERE/secret-blocklist.txt"
+
+# Repo-root exception lists (optional): a pattern appearing here as a FULL line is SKIPPED.
+# These files are NOT part of the payload; they are specific to their own repo.
+GITROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+AL="";  [ -n "$GITROOT" ] && [ -f "$GITROOT/.trace-allowlist.txt" ]  && AL="$GITROOT/.trace-allowlist.txt"
+SAL=""; [ -n "$GITROOT" ] && [ -f "$GITROOT/.secret-allowlist.txt" ] && SAL="$GITROOT/.secret-allowlist.txt"
+
+# Only added content lines (start with +, excluding the +++ file header).
+#
+# The added lines go to FILES, and every scan greps a file. Never `printf "$ADDED" | grep -q`: grep -q exits on
+# the first match, the pipe closes, printf dies of SIGPIPE (141), and `set -o pipefail` turns that into a failed
+# `if` — so a match in a LARGE staged diff would silently count as no match. A gate that only works on small
+# commits is worse than no gate.
+TRACE_F="$(mktemp)"; SECRET_F="$(mktemp)"
+# Cleanup runs on EXIT; the SIGNAL handlers additionally EXIT. A bare `trap '...' EXIT INT TERM` looks like it
+# handles all three, but bash returns to the script after a signal handler that does not exit — so TERM removed
+# the temp files this hook is still reading from and then let it carry on, printing `grep: /tmp/tmp.X: No such
+# file or directory` for the rest of the run. Measured here: after a TERM the hook exited 0, not 143, which is
+# the signature — a process killed by a signal cannot exit 0.
+#
+# That is how a slow commit becomes a STUCK one. A wrapper with a two-minute timeout sends TERM, the hook
+# swallows it, git keeps running, and `.git/index.lock` stays behind holding the repository. Every later git
+# command then fails with "Another git process seems to be running", which names nothing about the real cause.
+# 143 = 128 + SIGTERM, the exit status a shell reports for a process the signal actually stopped.
+_crew_cleanup(){ rm -f "$TRACE_F" "$SECRET_F" ${PRIV_F:+"$PRIV_F"} ${PTERM_F:+"$PTERM_F"} ${FLOOR_F:+"$FLOOR_F"} ${FLOOR_P:+"$FLOOR_P"}; }
+trap _crew_cleanup EXIT
+trap '_crew_cleanup; exit 143' INT TERM
+
+# Secrets are scanned EVERYWHERE. A token pasted into .claude/settings.json is still a token.
+# Crewforth's own blocklist files are excluded — they definitionally contain the patterns (circular), and since
+# 1.8.0 they also carry their own `#test:` cases. Matched by NAME rather than by the installed path: the same
+# files live at .claude/hooks/ in a project, kit/hooks/ in Crewforth's own repo and hooks/ in the
+# plugin build, and a path-anchored exclusion silently stopped applying in every layout but the first.
+git diff --cached --unified=0 -- . \
+  ':(top,exclude,glob)**/trace-blocklist.txt' ':(top,exclude,glob)**/secret-blocklist.txt' \
+  ':(top,exclude)trace-blocklist.txt' ':(top,exclude)secret-blocklist.txt' \
+  | grep -E '^\+' | grep -Ev '^\+\+\+' > "$SECRET_F" || true
+
+# Traces (§4.1/§4.2) are scanned in the PROJECT's own files only. `.claude/` is Crewforth's tree: it configures the
+# assistant, it legitimately names the tool it configures, and an update overwrites it — it is not an artifact the
+# project authored. Teams that share `.claude/` would otherwise be unable to commit it at all.
+# The blocklist is excluded by name for the same circularity reason as above: in an installed project it already
+# falls under .claude/, but in Crewforth's own repo it sits at kit/hooks/ where that exclusion misses it.
+git diff --cached --unified=0 -- . ':(top,exclude).claude' \
+  ':(top,exclude,glob)**/trace-blocklist.txt' ':(top,exclude)trace-blocklist.txt' \
+  | grep -E '^\+' | grep -Ev '^\+\+\+' > "$TRACE_F" || true
+
+# `git commit -a` stages tracked changes as part of the commit. As a git hook that is invisible — git stages
+# first, so --cached already contains them by the time this runs. Called AHEAD of the commit (the plugin
+# edition's PreToolUse path, which has no core.hooksPath to hook into), it is not: the content about to be
+# committed is still unstaged, and scanning only --cached would wave it through. The caller sets this when it
+# sees -a/--all.
+if [ "${CREW_SCAN_UNSTAGED:-0}" = 1 ]; then
+  git diff --unified=0 -- . \
+    ':(top,exclude,glob)**/trace-blocklist.txt' ':(top,exclude,glob)**/secret-blocklist.txt' \
+    ':(top,exclude)trace-blocklist.txt' ':(top,exclude)secret-blocklist.txt' \
+    | grep -E '^\+' | grep -Ev '^\+\+\+' >> "$SECRET_F" || true
+  git diff --unified=0 -- . ':(top,exclude).claude' \
+    ':(top,exclude,glob)**/trace-blocklist.txt' ':(top,exclude)trace-blocklist.txt' \
+    | grep -E '^\+' | grep -Ev '^\+\+\+' >> "$TRACE_F" || true
+fi
+
+HIT=0
+# (0) repo-bloat gate — scans the staged FILE LIST, not added lines: a binary produces no '^+' line, so this
+#     must run BEFORE the added-text early-exit below or it would never fire on the very files it targets.
+MAXBYTES="${CREW_MAX_FILE_BYTES:-5242880}"   # 5 MiB; override per-repo via env
+BLOAT_DIRS='(^|/)(node_modules|bower_components|dist|build|out|\.next|\.nuxt|\.svelte-kit|target|bin|obj|vendor|__pycache__|\.venv|venv|coverage|\.gradle)/'
+# COST NOTE, measured on a 373-file merge: the loop below used to spawn ~7 processes per file — three
+# `printf | grep` pairs plus a `git cat-file` — for 2,644 processes in total. On Git Bash a process costs
+# 20-50 ms and this hook ran for over twenty minutes on a real merge, which is how a gate turns into the thing
+# people reach for --no-verify to avoid. The pattern scanning was never the expensive part: 23 patterns are one
+# grep each. The file loop was. So the name tests are pure bash `case` now (no process at all) and the two
+# object lookups are batched into one `git cat-file --batch-check` after the loop. Same rules, same verdicts.
+BLOAT_CANDIDATES=""; BLOAT_QUERY=""
+SIZE_TARGETS=""; SIZE_QUERY=""
+NL='
+' 
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  base="${f##*/}"
+  # (F) secret-FILE gate — a file that is a secret by its very NAME. The content scan (2) can miss it: a private
+  #     key is high-entropy, not a known prefix. .env.example/.sample/.template/.dist are committable templates.
+  is_secret_file=0
+  case "$base" in
+    .env|.env.*)
+      # Case-insensitive for THIS test only — the rule it replaces used `grep -qiE` here and plain `grep -qE`
+      # everywhere else. Turning nocasematch on for the whole loop looked harmless and quietly widened a
+      # different rule: `server.PEM` went from allowed to blocked. Arguably an improvement, but not one to make
+      # inside a performance change, and not one to make without casing the "must not block" half.
+      shopt -s nocasematch 2>/dev/null || true
+      case "$base" in
+        *.example|*.sample|*.template|*.dist|*.schema|*.md) : ;;
+        *) is_secret_file=1 ;;
+      esac
+      shopt -u nocasematch 2>/dev/null || true ;;
+  esac
+  # Case-insensitive, and that IS a widening — the rule this replaced used a case-SENSITIVE `grep -qE`, so
+  # `server.PEM`, `id.KEY` and `cert.P12` were committable while their lowercase twins were blocked. Left open
+  # once already, on the grounds that widening a gate does not belong inside a performance change. It belongs
+  # here: Windows and macOS filesystems are case-insensitive, so `server.PEM` and `server.pem` are the SAME
+  # FILE, and a rule that blocks one spelling of a private key while allowing another has protected nothing.
+  # Same class as the `chmod 777` vs `chmod 1777` hole and the `rm -rf` vs `rm -Rf` one this file already fixed.
+  #
+  # nocasematch is opened and closed around this block ALONE. Left on across the whole loop it silently changed
+  # the .env test above, which is exactly how `server.PEM` moved from allowed to blocked as an invisible side
+  # effect the first time. The must-not-block half is cased too: `.pem.example`, `key.md`, `monkey.ts`,
+  # `KEYS.md` and `public.pub` all stay committable, and smoke-test pins them in both directions.
+  shopt -s nocasematch 2>/dev/null || true
+  case "$base" in
+    *.example|*.sample|*.template|*.dist|*.md|*.pub) : ;;
+    id_rsa|id_dsa|id_ecdsa|id_ed25519|.npmrc|.pypirc|.htpasswd|credentials.json) is_secret_file=1 ;;
+    *.pem|*.pfx|*.p12|*.ppk|*.key|*.keystore|*.jks) is_secret_file=1 ;;
+  esac
+  shopt -u nocasematch 2>/dev/null || true
+  if [ "$is_secret_file" = 1 ] && ! { [ -n "$SAL" ] && grep -qxF -- "$f" "$SAL"; }; then
+    echo "SECRET-FILE: '$f' is a secrets / credentials / private-key file — never commit it (gitignore it; ship a .env.example instead)."
+    HIT=1; continue
+  fi
+  # The PATTERN half only judges files that are NEW to the repository. A path already in HEAD is one the project
+  # decided to keep, and refusing it means that file can never be edited again without --no-verify — the exact
+  # shape of a gate that gets worked around. This repo hit it on its own `bin/cli.js`: `bin/` is build output in
+  # .NET and Java, and the conventional home of a CLI entry point in Node, where package.json's `bin` field
+  # points at it. The SIZE check below still applies to tracked files, so a tracked path cannot quietly grow.
+  case "/$f" in
+    */node_modules/*|*/bower_components/*|*/dist/*|*/build/*|*/out/*|*/.next/*|*/.nuxt/*|*/.svelte-kit/*|*/target/*|*/bin/*|*/obj/*|*/vendor/*|*/__pycache__/*|*/.venv/*|*/venv/*|*/coverage/*|*/.gradle/*)
+      BLOAT_CANDIDATES="$BLOAT_CANDIDATES$f
+"; BLOAT_QUERY="$BLOAT_QUERY${NL}HEAD:$f" ;;
+  esac
+  SIZE_TARGETS="$SIZE_TARGETS$f
+"; SIZE_QUERY="$SIZE_QUERY${NL}:$f"
+done < <(git diff --cached --name-only --diff-filter=AM -- . 2>/dev/null)
+
+# Both object lookups, batched. `--batch-check` answers in input order, so the paths are pasted back on rather
+# than looked up again — bash 3.2 (what macOS ships) has no associative arrays, and a second lookup per file
+# would put back the cost this removes.
+if [ -n "$BLOAT_CANDIDATES" ]; then
+  while IFS='	' read -r f verdict; do
+    [ -z "$f" ] && continue
+    case "$verdict" in *missing*)
+      echo "REPO-BLOAT: '$f' is a build/vendored artifact — gitignore it, don't commit it."
+      HIT=1 ;;
+    esac
+  done < <(printf '%s\n' "${BLOAT_QUERY#$NL}" | git cat-file --batch-check 2>/dev/null \
+             | paste -d'\t' <(printf '%s' "$BLOAT_CANDIDATES") - 2>/dev/null)
+fi
+
+if [ -n "$SIZE_TARGETS" ]; then
+  while IFS='	' read -r f info; do
+    [ -z "$f" ] && continue
+    sz="${info##* }"
+    case "$sz" in ''|*[!0-9]*) sz=0;; esac
+    if [ "$sz" -gt "$MAXBYTES" ]; then
+      echo "REPO-BLOAT: '$f' is $((sz/1024)) KiB (> $((MAXBYTES/1024)) KiB) — large blobs bloat history; use Git LFS or gitignore."
+      HIT=1
+    fi
+  done < <(printf '%s\n' "${SIZE_QUERY#$NL}" | git cat-file --batch-check 2>/dev/null \
+             | paste -d'\t' <(printf '%s' "$SIZE_TARGETS") - 2>/dev/null)
+fi
+
+# Floor guard, STRUCTURAL half — a test file deleted outright, or assertions taken out of one that stays.
+#
+# It sits here, ahead of the early exit below, because neither move adds a line: a commit that only deletes has
+# nothing for the text scans, and that exit used to end the hook before this ever ran — measured, a deleted test
+# file committed cleanly. The line-pattern half of the floor guard is further down with the other text scans.
+# (The line patterns and why each exists: floor-blocklist.txt.)
+FAL=""; [ -n "$GITROOT" ] && [ -f "$GITROOT/.floor-allowlist.txt" ] && FAL="$GITROOT/.floor-allowlist.txt"
+# .floor-allowlist.txt: `path:<glob>` exempts a path, `rule:<name>` turns a rule off, any other line exempts that
+# EXACT pattern line. `path:` is matched as a shell `case` pattern: `*` crosses `/` and `**` is not special, so
+# `path:*.cs` exempts every C# file in the tree. Documented in floor-blocklist.txt and pinned in smoke §7h2. The allowlist sits in the same diff as the code it excuses, which is the point: an exception
+# is a decision someone can see, not a rule that quietly got weaker.
+_floor_allowed(){ # $1 = rule, $2 = pattern (may be empty), $3 = path
+  [ -n "$FAL" ] || return 1
+  local a
+  while IFS= read -r a || [ -n "$a" ]; do
+    a="${a%$'\r'}"
+    case "$a" in
+      ''|\#*) continue ;;
+      path:*) case "$3" in ${a#path:}) return 0 ;; esac ;;
+      rule:*) [ "${a#rule:}" = "$1" ] && return 0 ;;
+      *)      [ -n "$2" ] && [ "$a" = "$2" ] && return 0 ;;
+    esac
+  done < "$FAL"
+  return 1
+}
+
+# Test files, by the naming each ecosystem uses. Names and not whole `test/` directories, because deleting a
+# fixture or a helper there is not a test made easier. Rust integration tests are the one convention that is a
+# directory rather than a name.
+_floor_is_test(){ # $1 = path
+  case "$1" in
+    *.test.*|*.spec.*|*_test.*|*_spec.rb|test_*.py|*/test_*.py) return 0 ;;
+    *Test.java|*Tests.java|*Test.kt|*Tests.kt|*Test.cs|*Tests.cs|*Test.php|*Spec.scala|*Tests.swift) return 0 ;;
+    __tests__/*|*/__tests__/*|tests/*.rs|*/tests/*.rs) return 0 ;;
+  esac
+  return 1
+}
+
+# One diff pass serves both checks, so the cost on an ordinary commit is two processes rather than four. Headers
+# are read only between `diff --git` and the first hunk: a removed content line that itself starts with `-- ` (a
+# SQL comment) shows up as `--- ` and would otherwise be mistaken for a file header.
+#
+# Assertions are counted NET per file, not line by line: changing an expectation removes one and adds one, and a
+# line-level rule would flag every such edit. A test only loses its checks when it ends with fewer than it began.
+# A rename is not a deletion and git does not report it as one, so moving a test file stays free.
+# Whether a path is a test is decided once, by _floor_is_test, rather than written a second time in awk.
+# ONE diff and ONE awk serve the whole floor guard — the deleted-test and assertion checks here, and the added-line
+# corpus the pattern half reads further down. They used to be two diffs and two awks, plus two mktemps, which is
+# what an ordinary commit paid for this guard: +7 processes, measured on Windows 11 at about +304 ms over a ~900 ms
+# hook. Merging them removes four processes; the corpus files are named off TRACE_F and created with a builtin
+# redirection, so no process makes them. Nothing about the trace or secret scans changed.
+#
+# Headers are read only between `diff --git` and the first hunk. The corpus parser used to treat any `+++ ` line as a
+# file header, so an added line that itself began `++ ` came through as `+++ …` and re-pointed the path of every line
+# after it; tracking the header state closes that as well. Unfiltered on purpose: deletions, modifications, additions
+# and renames all arrive in one stream. A new file is never counted for assertions (it cannot lose any); a renamed
+# test that also lost assertions is counted, which the old DM-only filter let through.
+FLOOR_F="$TRACE_F.floor"; FLOOR_P="$TRACE_F.floorp"; : > "$FLOOR_F"; : > "$FLOOR_P"
+_floor_diff(){ # $@ = extra git diff arguments
+  git diff "$@" --unified=0 --no-color --src-prefix=a/ --dst-prefix=b/ -- . ':(top,exclude).claude' 2>/dev/null
+}
+while IFS=$'\t' read -r kind f r a; do
+  [ -n "$f" ] || continue
+  _floor_is_test "$f" || continue
+  case "$kind" in
+    D) _floor_allowed "test-deleted" "" "$f" && continue
+       echo "FLOOR-GUARD [test-deleted]: $f is a test file this commit removes"
+       HIT=1 ;;
+    M) [ "$r" -gt "$a" ] || continue
+       _floor_allowed "assertion-removed" "" "$f" && continue
+       echo "FLOOR-GUARD [assertion-removed]: $f loses $((r - a)) assertion(s) and stays in the tree (removed $r, added $a)"
+       HIT=1 ;;
+  esac
+done < <({ _floor_diff --cached; [ "${CREW_SCAN_UNSTAGED:-0}" = 1 ] && _floor_diff; } \
+  | LC_ALL=C awk -v F="$FLOOR_F" -v P="$FLOOR_P" '
+      /^diff --git / { hdr = 1; old = ""; p = ""; isnew = 0; skip = 1; next }
+      hdr && /^--- /     { old = $0; sub(/^--- (a\/)?/, "", old); isnew = (old == "/dev/null"); next }
+      hdr && /^\+\+\+ /  { np = $0; sub(/^\+\+\+ (b\/)?/, "", np)
+                           if (np == "/dev/null") { if (old != "" && old != "/dev/null") printf "D\t%s\t0\t0\n", old; p = ""; skip = 1 }
+                           else { p = np; skip = (np ~ /\.(md|mdx|txt|rst|adoc)$/) }
+                           next }
+      /^@@/ { hdr = 0; s = $0; sub(/^@@ -[0-9,]+ \+/, "", s); sub(/[, ].*$/, "", s); ln = s + 0; next }
+      hdr   { next }
+      p == "" { next }
+      /^[-+]/ {
+        b = substr($0, 2); plus = (substr($0, 1, 1) == "+")
+        if (plus && !skip) { print b >> F; print p ":" ln >> P }
+        if (plus) ln++
+        if (!isnew && (b ~ /(^|[^A-Za-z0-9_])(assert|Assert|expect|Expect|should|Should|verify|Verify)[A-Za-z_]*[[:space:]]*[.(]/ ||
+            b ~ /(^|[^A-Za-z0-9_])t\.(Error|Errorf|Fatal|Fatalf)\(/ ||
+            b ~ /(^|[^A-Za-z0-9_])require\./ ||
+            b ~ /(^|[[:space:]])assert[[:space:]]/)) {
+          if (plus) add[p]++; else rem[p]++
+          seen[p] = 1
+        }
+      }
+      END { for (f in seen) printf "M\t%s\t%d\t%d\n", f, rem[f] + 0, add[f] + 0 }')
+
+# Nothing staged for the text scans AND the bloat gate is clean -> done.
+{ [ -s "$TRACE_F" ] || [ -s "$SECRET_F" ] || [ "$HIT" -ne 0 ]; } || exit 0
+
+
+# Ask "can ANY pattern match" once, before asking "which one".
+#
+# The three loops below spawn one grep PER PATTERN — 12 + 11 + 3 = 26 processes on every commit, and the
+# overwhelming majority of commits are clean, so 26 of them exist only to say "no". Measured on 205 added
+# lines: the trace loop 0.621 s -> 0.063 s, the secret loop 0.572 s -> 0.059 s. One decision, then the loop
+# ONLY when the decision says there is something to name.
+#
+# Three-way on purpose, because grep has three answers and two of them must not shortcut:
+#   rc=1  nothing matches      -> done. This is the fast path and the common one.
+#   rc=0  something matches    -> run the loop, which names the pattern. The user still reads
+#                                 "forbidden expression -> '<pattern>'" verbatim; nothing is lost but time.
+#   rc=2  grep could not decide -> run the loop. TODAY'S BEHAVIOUR, deliberately.
+#
+# That last rung is what makes this safe rather than clever, and it was earned: joining the patterns compiles
+# them TOGETHER, so ONE broken regex kills the whole alternation. Measured with a pattern file carrying a valid
+# `Co-Authored-By` and a broken `foo[`, against a message that really does carry the trailer:
+#     grep -inEf together   rc=2, ZERO matches   <- the trailer goes unreported
+#     one grep per pattern  catches it; only the broken pattern is skipped
+# A blocklist is a file users edit by hand, so a broken pattern is not exotic — and failing OPEN there would be
+# the worst possible direction. rc=2 also covers an alternation too large to compile (measured: 40 KB fine,
+# 200 KB -> "grep: Memory exhausted", rc=2 -> loop), so the ARG_MAX question answers itself.
+#
+# Verified on the blocklists' OWN #test:/#test-clean: cases — 32 of them, the payload the gate actually
+# defends: 32/32 identical verdicts. Calibrated by mutation (strip the parentheses so a group-scoped `|`
+# escapes to top level): 8 mismatches, in BOTH directions — three clean messages newly rejected and two real
+# secrets newly passed. Also checked structurally: no pattern in either shipped blocklist carries a bare
+# top-level `|` (every one is inside a group) and none uses a back-reference, so joining cannot reshape them.
+_crew_any(){   # $1 = pattern list  $2 = corpus  $3 = grep flags  $4 = 1 for newline-joined fixed strings
+  local pat alt="" sep="|"
+  [ "$4" = 1 ] && sep="
+"
+  while IFS= read -r pat || [ -n "$pat" ]; do
+    pat="${pat%$'\r'}"
+    case "$pat" in ''|\#*) continue;; esac
+    alt="${alt:+$alt$sep}$pat"
+  done < "$1"
+  [ -n "$alt" ] || return 1
+  grep -q$3 -- "$alt" "$2" 2>/dev/null
+}
+# (1) trace scan — case-INsensitive (vendor / AI-authorship strings), project files only
+# `!= 1` AND NOT `= 0`, AND THE DIFFERENCE IS THE WHOLE GATE. _crew_any joins every pattern into ONE
+# alternation and runs a single grep, so one malformed pattern anywhere in the file takes that grep down with
+# it -- exit 2, not 1. Measured, with a list holding `(AKIA|ASIA)[A-Z0-9]{16}` and `[unclosed`:
+#     good   list + matching corpus -> 0     good   list + clean corpus -> 1
+#     broken list + matching corpus -> 2     broken list + clean corpus -> 2
+# rc 2 means "I could not look", which is not "there is nothing there". So the guard treats anything that is
+# not a clean 1 as a reason to run the per-pattern loop below, where every pattern is tried on its own and the
+# broken one merely fails by itself.
+#
+# `= 0` reads as the same thing and is not: it skips the loop whenever the combined grep errors, so ONE typo
+# in a project's own added pattern turns the entire scanner fail-open and lets the commit through.
+#
+# NOTHING WOULD CATCH THAT SUBSTITUTION. On a well-formed blocklist the two spellings are identical in every
+# case -- measured above, 0 and 1 both route the same way -- so every test in this repo stays green, including
+# the malformed-pattern case, which only goes red BECAUSE the loop still runs. This comment is the only thing
+# standing between that rewrite and a silently open gate.
+if _crew_any "$BL" "$TRACE_F" iE 0; then _dec=0; else _dec=$?; fi
+if [ -f "$BL" ] && [ -s "$TRACE_F" ] && [ "$_dec" != 1 ]; then
+  while IFS= read -r pat || [ -n "$pat" ]; do
+    pat="${pat%$'\r'}"                       # tolerate a CRLF blocklist (Windows/autocrlf checkout) — a trailing \r
+    case "$pat" in ''|\#*) continue;; esac   # in the pattern never matches the LF-normalised diff, blinding the gate
+    if [ -n "$AL" ] && grep -qxF -- "$pat" "$AL"; then continue; fi
+    # A PATTERN THAT CANNOT COMPILE IS A GATE THAT IS NOT THERE, and it used to say so in grep's words, not
+    # ours: an unbalanced bracket printed "grep: brackets ([ ]) not balanced" into the middle of the commit
+    # output with nothing naming the file, the line, or the consequence. This file invites users to add their
+    # own vendor pattern, and a user who adds a broken one believes they are covered while nothing matches.
+    # CI catches it in this repo -- smoke drives every pattern with its own case and goes red -- but a consumer
+    # project runs no such suite, so the hook has to say it itself. It warns rather than blocks: the other
+    # patterns all still ran, so the commit is no less scanned than it was, and refusing every commit over one
+    # typo would cost more than the typo does.
+    # `|| _gr=$?` and not a bare call: `set -e` is in force at the top of this file, and a grep that simply
+    # does not match exits 1, which would kill the hook on the first clean pattern. Measured the wrong way once
+    # already -- the bare form made every commit exit 1 with no output at all.
+    _gr=0; grep -iqE -- "$pat" "$TRACE_F" 2>/dev/null || _gr=$?
+    if [ "$_gr" = 0 ]; then
+      echo "TRACE-SCANNER: forbidden expression in added code -> '$pat' (§4.1/§4.2)"
+      HIT=1
+    elif [ "$_gr" -ge 2 ]; then
+      echo "TRACE-SCANNER: /$pat/ in $BL is not a valid regular expression, so it matches NOTHING. Every other pattern still ran; fix or remove this line."
+    fi
+  done < "$BL"
+fi
+# (2) secret scan — case-SENSITIVE (token prefixes are case-specific); prints the PATTERN, never the value
+if _crew_any "$SL" "$SECRET_F" E 0; then _dec=0; else _dec=$?; fi
+if [ -f "$SL" ] && [ -s "$SECRET_F" ] && [ "$_dec" != 1 ]; then
+  while IFS= read -r pat || [ -n "$pat" ]; do
+    pat="${pat%$'\r'}"                       # tolerate a CRLF blocklist (Windows/autocrlf checkout)
+    case "$pat" in ''|\#*) continue;; esac
+    if [ -n "$SAL" ] && grep -qxF -- "$pat" "$SAL"; then continue; fi
+    _gr=0; grep -qE -- "$pat" "$SECRET_F" 2>/dev/null || _gr=$?
+    if [ "$_gr" = 0 ]; then
+      echo "SECRET-SCANNER: a staged line matches a secret pattern -> /$pat/"
+      HIT=1
+    elif [ "$_gr" -ge 2 ]; then
+      # Same reasoning as the trace loop above; the comment there is the long form.
+      echo "SECRET-SCANNER: /$pat/ in $SL is not a valid regular expression, so it matches NOTHING. Every other pattern still ran; fix or remove this line."
+    fi
+  done < "$SL"
+fi
+
+# (3) private-path scan — a path that only exists on THIS machine has no business in a shared artifact.
+#
+# Why this is not a blocklist regex: "is this path private?" cannot be answered by a pattern. `/Users/me` is a
+# placeholder every README wants, `/Users/ada` is a real person's home, and no ERE separates them (and ERE has
+# no negative lookahead to spell "not a placeholder"). So the terms are derived from the machine doing the
+# commit — where the answer is knowable exactly — plus whatever the repo owner adds by hand.
+#
+# It exists because this failure is not hypothetical: a work project's absolute path, pasted from a terminal
+# into a CHANGELOG entry, shipped in eight consecutive releases before anyone noticed. The paste is the vector,
+# so the gate has to sit where pasted text becomes a commit.
+#
+#   automatic  : $HOME, in the three spellings the same directory gets written as on Windows
+#                (/c/Users/x · C:/Users/x · C:\Users\x) — case-insensitively, since that filesystem is.
+#   by hand    : .private-terms.txt at the repo root, one literal term per line ('#' comments). Put internal
+#                project names, client names, and host names there. GITIGNORE IT — it is a list of the very
+#                strings you do not want published.
+#   escape     : .private-allowlist.txt, a term per full line, for the rare case a term is legitimately public.
+PRIV_F="$(mktemp)"; PTERM_F="$(mktemp)"
+PTF="";  [ -n "$GITROOT" ] && [ -f "$GITROOT/.private-terms.txt" ]     && PTF="$GITROOT/.private-terms.txt"
+PAL="";  [ -n "$GITROOT" ] && [ -f "$GITROOT/.private-allowlist.txt" ] && PAL="$GITROOT/.private-allowlist.txt"
+{
+  # A home path shorter than this cannot be distinguishing (`/root`, `/`), and matching it would flag everything.
+  if [ -n "${HOME:-}" ] && [ "${#HOME}" -ge 8 ]; then
+    printf '%s\n' "$HOME"
+    # Git Bash reports /c/Users/x for what Windows itself calls C:\Users\x — both spellings reach a file.
+    case "$HOME" in
+      /[a-zA-Z]/?*)
+        d="$(printf '%s' "${HOME:1:1}" | tr 'a-z' 'A-Z')"; r="${HOME:3}"
+        printf '%s\n' "$d:/$r" "$d:\\${r//\//\\}" ;;
+    esac
+  fi
+  [ -n "$PTF" ] && sed -e 's/[[:space:]]*$//' -e '/^#/d' -e '/^$/d' "$PTF"
+} > "$PTERM_F" 2>/dev/null || true
+if _crew_any "$PTERM_F" "$SECRET_F" iF 1; then _dec=0; else _dec=$?; fi
+if [ -s "$PTERM_F" ] && [ -s "$SECRET_F" ] && [ "$_dec" != 1 ]; then
+  while IFS= read -r term || [ -n "$term" ]; do
+    term="${term%$'\r'}"
+    [ -n "$term" ] || continue
+    if [ -n "$PAL" ] && grep -qxF -- "$term" "$PAL"; then continue; fi
+    if grep -qiF -- "$term" "$SECRET_F"; then
+      # The term is echoed back deliberately: unlike a secret, the author has to see WHICH private string to
+      # replace, and it is already sitting in their own working tree.
+      echo "PRIVATE-PATH SCANNER: a staged line contains a machine-private string -> '$term' (§4.3)"
+      HIT=1
+    fi
+  done < "$PTERM_F"
+fi
+rm -f "$PRIV_F"
+
+# (4) floor guard — a commit must not LOWER the quality bar on its way to a green check.
+#
+# An agent that hits a red check does not invent a clever loophole; it takes the cheapest road to green. That road
+# is nearly always visible in the lines a commit adds (a checker switched off where it fired, a test told to stop
+# running, a stub or a swallowed error where the work should be) or in what it takes away (a test file, the
+# assertions inside one that stays). The patterns and their cases live in floor-blocklist.txt; the two structural
+# checks that a single line cannot show are here.
+#
+# Built for this hook: the STAGED diff rather than a merge base, since at commit time that is exactly what enters
+# history; bash, since every gate here must run with nothing installed; and the two exemptions a real stack needs,
+# documentation and generated code.
+#
+# It reports the rule, the file, the line and the PATTERN, never the line's text: a suppressed line can carry a
+# secret beside the comment, and the secret scan above is the only place that decides how a value is shown.
+FL="$HERE/floor-blocklist.txt"
+# FLOOR_F (added lines of project code) and FLOOR_P (`path:line` at the same line number) were built by the single
+# floor pass ahead of the early exit above.
+
+# A file that opens with a generator marker was not written by this commit's author, and an EF Core project needs
+# this: EF Core puts a warning pragma into every model snapshot it emits (395k such files on GitHub, measured).
+# `sed -n '1,5p'` and NOT `head -n 5`: under `set -o pipefail`, head closing the pipe early makes the producer die
+# of SIGPIPE, and the pipeline reports 141 even when grep matched — measured, so the exemption would never apply.
+_FLOOR_GEN="|"
+_floor_generated(){ # $1 = repo-relative path; 0 when the file opens with a generator marker
+  case "$_FLOOR_GEN" in *"|$1=1|"*) return 0 ;; *"|$1=0|"*) return 1 ;; esac
+  local hdr
+  hdr="$(git show ":$1" 2>/dev/null | sed -n '1,5p')" || hdr=""
+  [ -n "$hdr" ] || hdr="$(sed -n '1,5p' -- "${GITROOT:-.}/$1" 2>/dev/null)" || hdr=""
+  if printf '%s\n' "$hdr" | grep -qE '<auto-generated|@generated|Code generated .*DO NOT EDIT|DO NOT EDIT|[Aa]uto-?generated|This file (is|was) (automatically )?generated'; then
+    _FLOOR_GEN="$_FLOOR_GEN$1=1|"; return 0
+  fi
+  _FLOOR_GEN="$_FLOOR_GEN$1=0|"; return 1
+}
+
+# (4a) line patterns. `!= 1` and not `= 0`, for the reason spelled out at the trace scan: a malformed pattern takes
+# the combined grep down with exit 2, which means "could not look", not "nothing is there".
+#
+# EXEMPTIONS ARE APPLIED BEFORE THE PER-PATTERN LOOP, not inside it, and that ordering is a measured cost fix.
+# Attributing a hit to its rule costs one grep per pattern (34 of them). The first version paid that on every
+# commit the cheap pre-check flagged, then exempted the lines — so an EF Core migration, whose three generated files
+# all carry a warning pragma, went from 20 processes to 73 and was allowed anyway. At the 62-135 ms a Git Bash
+# process was measured to cost, that is several seconds on every migration commit of an EF Core project. Now the
+# candidate lines are found with one grep, their files checked once each, and the loop runs only when a line that
+# is NOT exempt remains. A malformed pattern takes the combined grep down with exit 2; then the slow path runs over
+# every line, exactly as before, so a broken list still reports itself and still scans.
+if _crew_any "$FL" "$FLOOR_F" E 0; then _dec=0; else _dec=$?; fi
+if [ -f "$FL" ] && [ -s "$FLOOR_F" ] && [ "$_dec" != 1 ]; then
+  FLOOR_ALT=""
+  while IFS= read -r pat || [ -n "$pat" ]; do
+    pat="${pat%$'\r'}"
+    case "$pat" in ''|\#*) continue ;; esac
+    FLOOR_ALT="${FLOOR_ALT:+$FLOOR_ALT|}$pat"
+  done < "$FL"
+  KEEP="|"; SLOW=0; FLOOR_MAP=""
+  _cg=0; cand="$(grep -nE -- "$FLOOR_ALT" "$FLOOR_F" 2>/dev/null)" || _cg=$?
+  if [ "$_cg" -ge 2 ]; then
+    SLOW=1
+  elif [ -n "$cand" ]; then
+    nums="$(printf '%s\n' "$cand" | sed 's/:.*//' | tr '\n' ' ')"
+    # One awk maps every candidate line number to its `path:line` at once, instead of one sed per line.
+    CANDMAP="$(LC_ALL=C awk -v L="$nums" 'BEGIN { n = split(L, a, " "); for (i = 1; i <= n; i++) w[a[i]] = 1 } (NR in w) { print NR ":" $0 }' "$FLOOR_P")"
+    FLOOR_MAP="
+$CANDMAP
+"
+    # WHICH CANDIDATE FILES ARE GENERATED, ASKED ONCE FOR ALL OF THEM — measured on Windows, not assumed. Asking per
+    # file cost a Git Bash process pipeline each (~40 ms marginal there, three processes here), so 120 candidate
+    # files took 4.8 s while a single pass over all of them stayed flat at ~130 ms whatever the count. The pass is
+    # awk over the first FIVE lines of each file, not `grep -l` over whole files: a hand-written file that merely
+    # mentions a generator marker in a comment further down must not be exempted. It reads the working tree rather
+    # than the index; a generator header present in one and absent from the other is not a case worth a process per
+    # file, and the direction that could matter only makes the guard stricter.
+    # The answer seeds the same cache _floor_generated uses, so the attribution loop below pays nothing again.
+    FGEN_FILES=""; FGEN_SEEN="|"; set -- 
+    while IFS=: read -r n fpath _; do
+      [ -n "$fpath" ] || continue
+      case "$FGEN_SEEN" in *"|$fpath|"*) continue ;; esac
+      FGEN_SEEN="$FGEN_SEEN$fpath|"
+      [ -f "${GITROOT:-.}/$fpath" ] && set -- "$@" "${GITROOT:-.}/$fpath"
+    done <<EOF_FLOOR_CAND
+$CANDMAP
+EOF_FLOOR_CAND
+    FGEN_LIST=""
+    if [ "$#" -gt 0 ]; then
+      FGEN_LIST="$(LC_ALL=C awk 'FNR > 5 { nextfile }
+        /<auto-generated|@generated|Code generated .*DO NOT EDIT|DO NOT EDIT|[Aa]uto-?generated|This file (is|was) (automatically )?generated/ { print FILENAME; nextfile }' "$@" 2>/dev/null)" || FGEN_LIST=""
+    fi
+    for f in "$@"; do
+      rel="${f#"${GITROOT:-.}"/}"
+      case "
+$FGEN_LIST
+" in *"
+$f
+"*) _FLOOR_GEN="$_FLOOR_GEN$rel=1|" ;; *) _FLOOR_GEN="$_FLOOR_GEN$rel=0|" ;; esac
+    done
+    set --
+    while IFS=: read -r n fpath _; do
+      [ -n "$n" ] || continue
+      _floor_allowed "" "" "$fpath" && continue      # path: exemptions only — no rule or pattern is known yet
+      _floor_generated "$fpath" && continue          # answered from the cache seeded above
+      KEEP="$KEEP$n|"
+    done <<EOF_FLOOR_CAND2
+$CANDMAP
+EOF_FLOOR_CAND2
+  fi
+  if [ "$SLOW" = 1 ] || [ "$KEEP" != "|" ]; then
+    rule="unclassified"
+    while IFS= read -r pat || [ -n "$pat" ]; do
+      pat="${pat%$'\r'}"
+      case "$pat" in
+        '# rule: '*) rule="${pat#\# rule: }"; continue ;;
+        ''|\#*) continue ;;
+      esac
+      _gr=0; hits="$(grep -nE -- "$pat" "$FLOOR_F" 2>/dev/null)" || _gr=$?
+      if [ "$_gr" -ge 2 ]; then
+        echo "FLOOR-GUARD: /$pat/ in $FL is not a valid regular expression, so it matches NOTHING. Every other pattern still ran; fix or remove this line."
+        continue
+      fi
+      [ -n "$hits" ] || continue
+      while IFS=: read -r n _; do
+        [ -n "$n" ] || continue
+        [ "$SLOW" = 1 ] || case "$KEEP" in *"|$n|"*) ;; *) continue ;; esac
+        # The location comes from CANDMAP, already in memory, with parameter expansion — not one sed per hit. A commit
+        # that sweeps a suppression across many files is exactly the one this loop sees, and it is typically retried
+        # after each fix, so a process per hit was paid again on every attempt. The slow path has no map; it uses sed.
+        if [ "$SLOW" = 1 ]; then
+          loc="$(sed -n "${n}p" "$FLOOR_P")"
+        else
+          loc="${FLOOR_MAP#*"
+$n:"}"; loc="${loc%%
+*}"
+        fi
+        fpath="${loc%:*}"
+        _floor_allowed "$rule" "$pat" "$fpath" && continue
+        _floor_generated "$fpath" && continue
+        echo "FLOOR-GUARD [$rule]: $loc adds a move that lowers the bar -> /$pat/"
+        HIT=1
+      done <<EOF_FLOOR_HITS
+$hits
+EOF_FLOOR_HITS
+    done < "$FL"
+  fi
+fi
+
+if [ "$HIT" -ne 0 ]; then
+  echo "-----------------------------------------------------------"
+  echo "Commit stopped. Remove the AI-authorship trace / vendor name / secret / bloated file / bar-lowering move from the staged changes."
+  echo "A bar-lowering move that is genuinely warranted? record it in .floor-allowlist.txt at the repo root (path:<glob>, rule:<name>, or the exact pattern line) — in the same commit, where review sees it. A path: glob's * also crosses directories: write the narrowest path."
+  echo "False positive (trace/secret)? add the EXACT pattern line to .trace-allowlist.txt or .secret-allowlist.txt at the repo root."
+  echo "Private path flagged but genuinely public? add that exact term to .private-allowlist.txt at the repo root."
+  echo "Large file is intentional? raise CREW_MAX_FILE_BYTES, use Git LFS, or gitignore the build/vendored path."
+  echo "Deliberate exception: 'git commit --no-verify' — only on an EXPLICIT request (§4.5)."
+  exit 1
+fi
+exit 0