crewforth 3.2.0-rc.1 → 3.2.0-rc.3

package/kit/hooks/guard-agent-model.sh

@@ -14,10 +14,15 @@
 #   * RISK CLASS. `critical` when the change is migration, security, architecture or fix-unknown, or a file is on a
 #     critical path (auth, payments, billing, migrations, security, crypto, secrets, *.sql, schema.prisma;
 #     .claude/crew-model-rules adds and removes paths). Otherwise `normal`.
-#   * critical work runs on opus, whatever the agent. The one exception is test-run: running the tests is objective.
+#   * critical work runs on opus, whatever the agent. Two exceptions: test-run (running the tests is objective), and
+#     a text change whose every file is prose (.md .txt .rst .adoc), which runs on sonnet or above: a reworded
+#     paragraph under legal/ is read by a person, and opus for it is the cost this gate exists to stop. A project
+#     that wants opus there says so in .claude/crew-model-rules (floor * text critical opus).
 #   * the referee is as strong as the risk: test-write and audit on sonnet or above (opus when critical, by the rule
 #     above); review, privacy, planner and database agents on sonnet or above; the security agent on opus.
-#   * work with no verify command runs on sonnet or above: haiku goes only to work a command can check.
+#   * work with no verify command runs on sonnet or above: haiku goes only to work a command can check. Not for
+#     change: text, nor for the commit agent: a reader is all prose ever has, and a commit message is checked by
+#     the commit-msg hook (seen on a real project: a commit message proposed on sonnet for that reason alone).
 #   * a class that failed too often is held one model up (crew-model-floors.auto, written by hooks/agent-outcome.sh),
 #     until the user lowers it again with /crew-loosen (one model, once for each raise).
 #   * a card whose verify failed is not run again on the same or a lower model, and not a third time at all.
@@ -412,11 +417,23 @@ _am_crit_path(){  # $1 = a path or a glob -> 0 critical (_AMW says by what), 1 n
   return "$hit"
 }
 
+_am_prose(){  # $1 = a path or a glob -> 0 when it is prose a person reads (the exception for a text change)
+  case "$1" in *.md|*.MD|*.markdown|*.txt|*.TXT|*.rst|*.adoc) return 0 ;; esac
+  return 1
+}
+_am_all_prose(){  # after _am_card -> 0 when every file of the card is prose
+  local f r=0 unglob=0
+  case "$-" in *f*) ;; *) unglob=1; set -f ;; esac
+  for f in ${CARD_FILES//,/ }; do _am_prose "$f" || { r=1; break; }; done
+  [ "$unglob" = 1 ] && set +f
+  return "$r"
+}
+
 # ---- THE CARD ---------------------------------------------------------------------------------------------------
 _AM_CHANGES=' text feature fix-known fix-unknown refactor migration security architecture test-run test-write audit '
-_am_card(){  # $1 = a task text -> 0 and CARD_FILES, CARD_CHANGE, CARD_VERIFY; 1 and CARD_WHY
+_am_card(){  # $1 = a task text -> 0 and CARD_FILES, CARD_CHANGE, CARD_VERIFY (CARD_ABOVE); 1 and CARD_WHY
   local s="$1" l k v n=0 seen=""
-  CARD_FILES=""; CARD_CHANGE=""; CARD_VERIFY=""; CARD_WHY=""
+  CARD_FILES=""; CARD_CHANGE=""; CARD_VERIFY=""; CARD_WHY=""; CARD_ABOVE=""
   s="${s//$'\r'/}"
   while [ "$n" -lt 3 ] && [ -n "$s" ]; do
     l="${s%%$'\n'*}"; if [ "$l" = "$s" ]; then s=""; else s="${s#*$'\n'}"; fi
@@ -440,7 +457,16 @@ _am_card(){  # $1 = a task text -> 0 and CARD_FILES, CARD_CHANGE, CARD_VERIFY; 1
   [ -n "$CARD_FILES" ] || { CARD_WHY="files: is empty (name the files or globs, or the folder)"; return 1; }
   case "$_AM_CHANGES" in *" $CARD_CHANGE "*) ;; *) CARD_WHY="change: is '${CARD_CHANGE:0:40}', not one of:$_AM_CHANGES"; return 1 ;; esac
   [ -n "$CARD_VERIFY" ] || { CARD_WHY="verify: is empty (a command, or none)"; return 1; }
-  case "$CARD_VERIFY" in none|None|NONE|-) CARD_VERIFY=none ;; esac
+  case "$CARD_VERIFY" in none|None|NONE|-|'none '*|'none('*|'None '*|'NONE '*) CARD_VERIFY=none ;; esac   # "none (the author ran it)" is none
+  # Optional, right after the three: `above: <why>` keeps a model above the card's floor. Without it a call above
+  # the floor is run on the floor (the cost of a model nobody needed is what this gate exists to stop).
+  while [ -n "$s" ]; do
+    l="${s%%$'\n'*}"; if [ "$l" = "$s" ]; then s=""; else s="${s#*$'\n'}"; fi
+    while :; do case "$l" in [$' \t']*) l="${l:1}" ;; *) break ;; esac; done
+    [ -n "$l" ] || continue
+    case "$l" in above:*) v="${l#above:}"; while :; do case "$v" in [$' \t']*) v="${v:1}" ;; *) break ;; esac; done; CARD_ABOVE="${v:0:200}" ;; esac
+    break
+  done
   return 0
 }
 _am_risk(){  # after _am_card -> CARD_RISK critical|normal, CARD_RISKWHY
@@ -460,6 +486,53 @@ _am_digest(){  # after _am_card -> CARD_ID: 12 hex of what the card says, so "th
   case "$t" in ''|*[!0-9a-f]*) t="$(printf '%s\n%s\n%s\n' "$CARD_FILES" "$CARD_CHANGE" "$CARD_VERIFY" | cksum 2>/dev/null)"; t="${t%% *}"; printf -v t '%012x' "${t:-0}" 2>/dev/null || t=000000000000 ;; esac
   CARD_ID="${t:0:12}"
 }
+# A call to an agent that is not Crewforth's (general-purpose, a project's own): no card and no floor, so only the
+# expensive end is held, the same rewrite as a crew call above its floor.
+#   * It names opus or fable, and its task has no `above: <why>` line: it runs on sonnet.
+#   * It names no model, and the agent takes the session's (general-purpose, or a project or user agent whose
+#     definition has no model of its own): it runs on sonnet, unless the session itself is on haiku, read from the
+#     end of its transcript. An agent whose definition names a model (Explore, claude-code-guide) is left to it:
+#     a model in the call would override a cheaper one there.
+# Measured on 2.1.299: a general-purpose call that named no model ran on the session's model; CLAUDE_CODE_SUBAGENT_MODEL
+# in the project's settings `env` did not change that (in the shell's environment it did), so the hook sets it.
+_am_outside(){  # $1 = the tool_input text, $2 = the agent's name
+  local m pr to=sonnet ui name="$2" f d l ln inherit=0 tp last
+  case "$name" in ''|*[!A-Za-z0-9._-]*) name="an agent" ;; esac
+  _json_keycount "$1" prompt; [ "$_KC" = 1 ] || return 0
+  _json_slice "$1" prompt >/dev/null; pr="${_JS:0:6000}"; _json_unescape "$pr" >/dev/null; pr=$'\n'"${_JU//$'\r'/}"
+  case "$pr" in *$'\n'above:*|*$'\n'[$' \t']above:*) return 0 ;; esac
+  _json_keycount "$1" model
+  if [ "$_KC" = 0 ]; then
+    case "$name" in
+      general-purpose) inherit=1 ;;
+      'an agent') ;;
+      *) for d in "${CLAUDE_PROJECT_DIR:-.}/.claude/agents" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents"; do
+           f="$d/$name.md"; [ -f "$f" ] || continue
+           inherit=1; ln=0
+           while IFS= read -r l || [ -n "$l" ]; do
+             ln=$((ln+1)); [ "$ln" -le 40 ] || break
+             case "$l" in ---*) [ "$ln" -gt 1 ] && break ;; model:*) case "${l#model:}" in *inherit*|'') ;; *) inherit=0 ;; esac ;; esac
+           done < "$f"
+           break
+         done ;;
+    esac
+    [ "$inherit" = 1 ] || return 0
+    _json_slice "$INPUT" transcript_path >/dev/null; _json_unescape "$_JS" >/dev/null; tp="$_JU"
+    if [ -n "$tp" ] && [ -f "$tp" ]; then
+      last="$(tail -c 65536 "$tp" 2>/dev/null)"; last="${last##*\"model\":\"}"; last="${last%%\"*}"
+      case "$last" in *haiku*) return 0 ;; esac
+    fi
+    m="the session's model"
+  else
+    [ "$_KC" = 1 ] || return 0
+    _json_slice "$1" model >/dev/null; _json_unescape "$_JS" >/dev/null; _am_tier "$_JU"; m="$_AMT"
+    case "$m" in opus|fable) ;; *) return 0 ;; esac
+  fi
+  ui="$(printf '%s' "$INPUT" | awk -v op=get -v path=tool_input -v setk=model -v setv="\"$to\"" -f "$_AM_HERE/../eval/lib/settings-json.awk" - 2>/dev/null)" || return 0
+  case "$ui" in '{'*'}') ;; *) return 0 ;; esac
+  _am_log "note: $name (not a crew agent) asked for $m, run on $to; add 'above: <why>' to its task to keep a model above it"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"Crewforth: %s asked for %s and runs on %s (a line above: <why> in its task keeps a model above it)","updatedInput":%s}}\n' "$name" "$m" "$to" "$ui"
+}
 _am_rec_get(){  # $1 = a record file, $2 = key -> _AMV (lines are key=value)
   local l; _AMV=""
   [ -f "$1" ] || return 1
@@ -501,13 +574,10 @@ _am_floor_now(){  # $1 agent, $2 change, $3 risk -> _AMF_TIER (the raised floor,
 
 # ---- the gate log: a refusal of this gate is recorded like any other gate's -------------------------------------
 _am_log(){  # $1 = the rule. Same file and line shape as guard-bash.sh's gatelog; the call's text is never recorded.
-  local gl="${CREW_GATE_LOG:-}" v=BLOCK
+  local gl="" v=BLOCK
   case "$1" in "note: "*) v=NOTE ;; esac          # something worth knowing that refused nothing
-  if [ -z "$gl" ]; then
-    [ -d ".claude" ] || return 0
-    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then git check-ignore -q ".claude/gate-log.tsv" 2>/dev/null || return 0; fi
-    gl=".claude/gate-log.tsv"
-  fi
+  declare -F crew_gate_log_write >/dev/null || return 0
+  crew_gate_log_write; gl="$_CREW_GL"; [ -n "$gl" ] || return 0
   printf '%s\t§model\t%s\t\n' "$v" "$1" >> "$gl" 2>/dev/null || true
 }
 
@@ -538,6 +608,7 @@ _am_log(){  # $1 = the rule. Same file and line shape as guard-bash.sh's gatelog
 #   5. THE SHELL GATE AGREES, asked under a session id that is not the session's: only "nothing to say" or an
 #      explicit allow passes.
 _AM_HERE="${BASH_SOURCE%/*}"; [ "$_AM_HERE" = "${BASH_SOURCE}" ] && _AM_HERE=.
+[ -f "$_AM_HERE/../eval/lib/gate-log.sh" ] && . "$_AM_HERE/../eval/lib/gate-log.sh"   # where the gate log goes
 # CREW-NOT-A-RUNG: names of commands a PROJECT's verify line may begin with; nothing here is called by Crewforth.
 _AM_RUNNERS=('npm test' 'npm t' 'pnpm test' 'yarn test' 'bun test' 'deno test'
   'dotnet test' 'dotnet build' 'flutter test' 'flutter analyze' 'dart test' 'dart analyze' 'go test' 'go build' 'go vet'
@@ -609,6 +680,9 @@ _am_perm_hit(){  # $1 = command, $2 = allow|deny|ask -> 0 a Bash(...) rule of th
   done <<< "$_AMSF"
   return 1
 }
+# How a verify command is read (the `cd <folder> && <command>` split): eval/lib/verify-cmd.sh, shared with doctor.
+[ -f "$_AM_HERE/../eval/lib/verify-cmd.sh" ] && . "$_AM_HERE/../eval/lib/verify-cmd.sh"
+_am_verify_split(){ _AMVD=""; _AMVC="$1"; declare -F crew_verify_split >/dev/null && crew_verify_split "$1" "${_AMP:-.}"; return 0; }
 _am_verify_ok(){  # $1 = the command, $2 = permission mode -> 0 it may run (_AMVB says by what); 1 and _AMVW says why not
   local c="$1" pm="${2:-default}" f r rc k g
   _AMVW=""; _AMVB=""
@@ -690,6 +764,8 @@ _am_write_check(){  # $1 = the payload, $2 = the file about to be written -> ret
     if [ -f "$f" ]; then m="$(grep -m1 -o '"model":"[^"]*"' "$f" 2>/dev/null)" || m=""; _am_tier "$m"; tier="$_AMT"; fi
   fi
   case "$tier" in opus|fable) return 0 ;; esac
+  # A text change on sonnet may write prose there: the call was let through on that floor for exactly that.
+  if [ "$tier" = sonnet ] && _am_prose "$_AMRP" && _am_rec_get "$_AMD/agents/$aid" change && [ "$_AMV" = text ]; then return 0; fi
   _am_log "critical path: write by an agent not on opus"
   echo "GUARD (agent model): $_AMRP is on a critical path ($_AMW) and this agent runs on ${tier:-a model that could not be read}; only an agent on opus writes there. Do not reach the file another way. Stop, and end your report with the two lines: escalate: $_AMRP / confidence: low" >&2
   exit 2
@@ -729,7 +805,7 @@ _json_keycount "$ti" subagent_type
 if [ "$_KC" -gt 1 ]; then echo "GUARD (agent model): this call names subagent_type more than once, so which agent it starts cannot be read and the call is refused. Send one." >&2; _am_log "an ambiguous call"; exit 2; fi
 _json_slice "$ti" subagent_type >/dev/null; _json_unescape "$_JS" >/dev/null; st="$_JU"
 st="${st##*:}"                                  # a plugin names its agents <plugin>:crew-…
-case "$st" in crew-*) ;; *) exit 0 ;; esac
+case "$st" in crew-*) ;; *) _am_outside "$ti" "$st"; exit 0 ;; esac
 case "$st" in *[!A-Za-z0-9_-]*) echo "GUARD (agent model): the agent's name holds a character this gate does not read, so the call is refused." >&2; _am_log "an agent name it cannot read"; exit 2 ;; esac
 _json_keycount "$ti" model
 if [ "$_KC" -gt 1 ]; then echo "GUARD (agent model): this call names model more than once, so which model it asks for cannot be read and the call is refused. Send one." >&2; _am_log "an ambiguous call"; exit 2; fi
@@ -763,9 +839,11 @@ if ! _am_card "$prompt"; then
 fi
 _am_state; _am_risk; _am_digest
 # ---- the floor of THIS card: the highest of what applies, and the reason that set it ----
-if [ "$CARD_VERIFY" = none ] && [ "$floor" -lt 2 ]; then floor=2; why="no verify command, so nothing checks the work but a reader"; fi
+if [ "$CARD_VERIFY" = none ] && [ "$CARD_CHANGE" != text ] && [ "$st" != crew-commit-agent ] && [ "$floor" -lt 2 ]; then floor=2; why="no verify command, so nothing checks the work but a reader"; fi
 case "$CARD_CHANGE" in test-write|audit) if [ "$floor" -lt 2 ]; then floor=2; why="change: $CARD_CHANGE, the referee of the work"; fi ;; esac
-if [ "$CARD_RISK" = critical ] && [ "$CARD_CHANGE" != test-run ] && [ "$floor" -lt 3 ]; then floor=3; why="critical work: $CARD_RISKWHY"; fi
+if [ "$CARD_RISK" = critical ] && [ "$CARD_CHANGE" = text ] && _am_all_prose; then
+  if [ "$floor" -lt 2 ]; then floor=2; why="a text change on a critical path: $CARD_RISKWHY"; fi
+elif [ "$CARD_RISK" = critical ] && [ "$CARD_CHANGE" != test-run ] && [ "$floor" -lt 3 ]; then floor=3; why="critical work: $CARD_RISKWHY"; fi
 # A class the user's rules or the record of outcomes hold higher. Neither can lower anything here.
 _am_rules
 for r in ${_AM_RULES[@]+"${_AM_RULES[@]}"}; do
@@ -802,6 +880,23 @@ if [ "$rank" -lt "$floor" ]; then
   echo "GUARD (agent model): $st runs on $fname or above for this card ($why), and this call asks for $m. Repeat the same call with model $fname." >&2
   _am_log "below the floor of the card"; exit 2
 fi
+# ---- above the floor: run on the floor, unless the card says why not ----
+# The floor is what the work needs; a model above it is cost nobody asked for (measured on a real project: 73 of 186
+# crew tasks ran above their floor, 0 on haiku). Unless the card carries `above: <why>`, the call is let through ON
+# THE FLOOR: the hook hands Claude Code the same input with `model` replaced (PreToolUse updatedInput; measured on
+# 2.1.299: a call asking for opus ran on haiku alone). The rewrite is one awk over the payload, on this path only.
+lowered=""
+low=$floor; [ "$low" -lt 1 ] && low=1
+if [ "$rank" -gt "$low" ] && [ -z "$CARD_ABOVE" ]; then
+  _am_name "$low"; to="$_AMN"
+  ui="$(printf '%s' "$INPUT" | awk -v op=get -v path=tool_input -v setk=model -v setv="\"$to\"" -f "$_AM_HERE/../eval/lib/settings-json.awk" - 2>/dev/null)" || ui=""
+  case "$ui" in '{'*'}') ;; *) ui="" ;; esac
+  if [ -n "$ui" ]; then
+    lowered="$m"
+    _am_log "note: $st asked for $m, run on $to, the floor of this card (${why:-no floor above haiku}); add 'above: <why>' to the card to keep $m"
+    m="$to"
+  fi
+fi
 # ---- where it runs, and what its verify command is ----
 _json_keycount "$ti" run_in_background
 if [ "$_KC" -gt 1 ]; then echo "GUARD (agent model): this call names run_in_background more than once, so where it runs cannot be read and the call is refused. Send one." >&2; _am_log "an ambiguous call"; exit 2; fi
@@ -828,7 +923,11 @@ if mkdir -p "$_AMD/pending" 2>/dev/null; then
   # Why the work counts as critical, as the gate decided it, so a reader shows the reason and does not work it out
   # again: one line, no tab (it ends up in a column of model-outcomes.tsv).
   rw="${CARD_RISKWHY:--}"; rw="${rw//$'\t'/ }"; rw="${rw//$'\r'/ }"; rw="${rw//$'\n'/ }"
-  { printf 'agent=%s\ntier=%s\nchange=%s\nrisk=%s\ncard=%s\nbg=%s\nesc=%s\nverify=%s\nfiles=%s\nwhy=%s\n' "$st" "$m" "$CARD_CHANGE" "$CARD_RISK" "$CARD_ID" "$bg" "${p:--}" "$CARD_VERIFY" "$CARD_FILES" "$rw" > "$_AMD/pending/$t-$tid"; } 2>/dev/null || true
+  { printf 'agent=%s\ntier=%s\nchange=%s\nrisk=%s\ncard=%s\nbg=%s\nesc=%s\nverify=%s\nfiles=%s\nlowered=%s\nwhy=%s\n' "$st" "$m" "$CARD_CHANGE" "$CARD_RISK" "$CARD_ID" "$bg" "${p:--}" "$CARD_VERIFY" "$CARD_FILES" "${lowered:--}" "$rw" > "$_AMD/pending/$t-$tid"; } 2>/dev/null || true
+fi
+# The call, on the floor: the same input with `model` replaced, and allowed. Nothing else is printed on this path.
+if [ -n "$lowered" ]; then
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"Crewforth: %s asked for %s and runs on %s, the floor of its card (add above: <why> to the card to keep %s)","updatedInput":%s}}\n' "$st" "$lowered" "$m" "$lowered" "$ui"
 fi
 exit 0
 }

package/kit/hooks/guard-bash.sh

@@ -148,7 +148,14 @@ _join_cmd(){  # CMD -> CMD with its continued lines joined
 # ---- /CREW-JOIN
 # 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
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"
+# Where the gate log goes: one rule for every gate and reader (eval/lib/gate-log.sh).
+[ -f "$_crew_d/../eval/lib/gate-log.sh" ] && . "$_crew_d/../eval/lib/gate-log.sh"
+# What a stopped or asked command would have touched (eval/lib/preview.sh), read only when one is stopped or asked.
+_CREW_PV_LIB="$_crew_d/../eval/lib/preview.sh"; unset _crew_d
+# The preview of a command. ALWAYS called as "$(_pv_line …)": the command substitution is the subshell that keeps an
+# exit or a failure in the library from ending this hook or changing its decision (smoke plants both).
+_pv_line(){ [ -f "$_CREW_PV_LIB" ] || return 0; . "$_CREW_PV_LIB" 2>/dev/null && crew_preview "$1" "$2" 2>/dev/null && printf '%s' "${_CREW_PV:-}"; return 0; }
 # Read with the builtin, as guard-powershell.sh does: `INPUT="$(cat)"` is a subshell plus a process on EVERY call
 # of this hook. `read` returns 1 at end of input; the text is read regardless.
 IFS= read -r -d '' INPUT || true
@@ -168,20 +175,17 @@ IFS= read -r -d '' INPUT || true
 # token, and `/crew-gates` never prints it — the report is rule names and counts. Recording it by default would
 # buy nothing and add a place for a secret to sit. `CREW_GATE_LOG_CMD=1` puts it back for debugging a false
 # positive, which is the only thing it is good for.
-# Where the default log may go. An explicit CREW_GATE_LOG is the operator's call and is used as given. The
-# DEFAULT path is only used when writing there cannot surprise anyone: outside a git repo, or inside one where
-# the path is already ignored. A kit install gitignores .claude/, so this is the normal case — but the plugin
-# edition drops into repos the installer never touched, and this repo proved the failure itself: the suite left
-# a gate-log.tsv sitting in `git status` as an untracked file waiting to be committed. One `git check-ignore`
-# runs only when a decision is logged (a block, an approval prompt or a CLAUDE_GIT_OK allow); ordinary commands
-# never reach it.
+# Where the log goes. An explicit CREW_GATE_LOG is the operator's call and is used as given. .claude/gate-log.tsv
+# only where writing there cannot surprise anyone: outside a git repo, or where git ignores it (a kit install
+# ignores .claude/; the plugin edition drops into repos the installer never touched, and this repo proved the
+# failure: the suite left a gate-log.tsv in `git status` waiting to be committed). Elsewhere it goes inside the
+# repository's .git, which is never committed. git is asked only when a decision is logged (a block, an approval
+# prompt or a CLAUDE_GIT_OK allow); ordinary commands never reach it.
+# Since 3.2.0 a repository that tracks .claude/ gets the log inside its .git (eval/lib/gate-log.sh), where it was
+# not written at all before.
 _gatelog_path(){
-  if [ -n "${CREW_GATE_LOG:-}" ]; then printf '%s' "$CREW_GATE_LOG"; return; fi
-  [ -d ".claude" ] || return 0
-  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    git check-ignore -q ".claude/gate-log.tsv" 2>/dev/null || return 0
-  fi
-  printf '%s' ".claude/gate-log.tsv"
+  declare -F crew_gate_log_write >/dev/null || return 0
+  crew_gate_log_write; printf '%s' "$_CREW_GL"
 }
 gatelog(){  # $1 = verdict (BLOCK|ASK|ALLOW)  $2 = section  $3 = rule
   # Resolve the path ONCE per hook run and remember it HERE, not inside _gatelog_path: that function is invoked
@@ -720,6 +724,8 @@ block(){
   gatelog BLOCK "$2" "$1"
   echo "GUARD (§$2): '$1' stopped AT THE TOOL LEVEL." >&2
   [ -z "${_BLOCK_NOTE:-}" ] || echo "$_BLOCK_NOTE" >&2
+  # What it would have touched, when the rule names a kind (_PV_KIND): read only, after the decision is made.
+  if [ -n "${_PV_KIND:-}" ]; then _pvo="$(_pv_line "$_PV_KIND" "${_PV_CMD:-$CMD}")"; [ -n "$_pvo" ] && echo "$_pvo" >&2; fi
   case "${3:-}" in
     loss)     echo "Nothing here is undone by retrying — but the refusal is not the end of the task. Do the same job the reversible way: name the paths instead of sweeping, and look first (git clean -n, ls) so you act on what you can see. Only if the broad form is genuinely required does the user run it in their own terminal." >&2 ;;
     history)  echo "This rewrites or discards work that is already committed. Ask the person who shares the branch; a new commit usually reaches the same end without rewriting." >&2 ;;
@@ -865,15 +871,15 @@ _push_forces(){   # $1 = one captured `git push …` span -> 0 when a force flag
 _git_d45(){  # $1 = command text; block() exits on the first rule it breaks
   local CMD="$1" HAS_GIT=0 _PUSHSEG _seg                                         # has() reads CMD: this one
   case "$CMD" in *[Gg][Ii][Tt]*) HAS_GIT=1 ;; esac
-  { git_has "$CMD" 'reset'  && has '--hard'; }                                                && block "git reset --hard" "4.5" history
+  { git_has "$CMD" 'reset'  && has '--hard'; }                                                && { _PV_KIND=reset; _PV_CMD="$CMD"; block "git reset --hard" "4.5" history; }
   if [ "$HAS_GIT" = 1 ] && git_has "$CMD" 'push'; then
     _grep_out "$CMD" -oE 'git[[:space:]]+([^;&|]*[[:space:]])?push([^;&|]*)'; _PUSHSEG="$_GO"
     while IFS= read -r _seg; do
       [ -n "$_seg" ] || continue
-      _push_forces "$_seg" && { block "git push --force" "4.5" history; break; }
+      _push_forces "$_seg" && { _PV_KIND=push; _PV_CMD="$_seg"; block "git push --force" "4.5" history; break; }
     done <<< "$_PUSHSEG"
   fi
-  { git_has "$CMD" 'clean'  && has '-[A-Za-z]*f'; }                                           && block "git clean -f" "4.5" loss
+  { git_has "$CMD" 'clean'  && has '-[A-Za-z]*f'; }                                           && { _PV_KIND=clean; _PV_CMD="$CMD"; block "git clean -f" "4.5" loss; }
   return 0
 }
 # ---- the quoted argument of a command that does not run it ---------------------------------------------------
@@ -1109,7 +1115,7 @@ case "$CMD" in *branch*) _HAS_BRANCH=1 ;; *) _HAS_BRANCH=0 ;; esac
 # short cluster, so `rm -Rf /`, `rm -fR /`, `rm -f -r /` and `rm --recursive --force /` all walked past while
 # `rm -rf /` was blocked. Same class as the chmod hole found in evals/permission-pressure: one spelling gated,
 # another reaching the identical state. Case, flag order and the long form are all the same command.
-case "$CMD" in *[Rr][Mm]*) : ;; *) false ;; esac && _grep "$CMD" -qE 'rm +(-[A-Za-z]* +|--[a-z-]+ +)*(-[A-Za-z]*[rR][A-Za-z]*|--recursive)( +(-[A-Za-z]+|--[a-z-]+))* +.*(/|\*|~)' && block "destructive rm -rf" "4.5" loss
+case "$CMD" in *[Rr][Mm]*) : ;; *) false ;; esac && _grep "$CMD" -qE 'rm +(-[A-Za-z]* +|--[a-z-]+ +)*(-[A-Za-z]*[rR][A-Za-z]*|--recursive)( +(-[A-Za-z]+|--[a-z-]+))* +.*(/|\*|~)' && { _PV_KIND=rm; _PV_CMD="$CMD"; block "destructive rm -rf" "4.5" loss; }
 # ADDED (3.1.0): `.` and `..` as a target carry none of those three characters and are the widest targets there are —
 # `rm -rf .` at a project root takes the whole tree, `..` its parent (both passed). Narrower than the test above on
 # purpose, so that it adds no noise: `rm` must stand at a command position, `sudo` or not (`git rm -r --cached .`, `npm rm`,
@@ -1121,7 +1127,7 @@ case "$CMD" in *[Rr][Mm]*)
   _rmc="$CMD"
   # a backslash-newline continues the line (`rm -rf \⏎.`); folded only when one is there and the command is short
   case "$CMD" in *\\"$_RMNL"*) [ "${#CMD}" -le 4096 ] && _rmc="${CMD//\\$_RMNL/ }" ;; esac
-  [[ $_rmc =~ $_RMDOT ]] && block "destructive rm -rf" "4.5" loss ;; esac
+  [[ $_rmc =~ $_RMDOT ]] && { _PV_KIND=rm; _PV_CMD="$_rmc"; block "destructive rm -rf" "4.5" loss; } ;; esac
 # A whole-tree `git checkout -- .` / `git restore .` destroys every uncommitted change with no reflog and no
 # undo — the same loss as `reset --hard`, which has been gated since the beginning, by a command that was not.
 # Not hypothetical: a verification subagent ran exactly this over uncommitted work in this repo and took the
@@ -3342,17 +3348,26 @@ if git_has "$CMD_SEEN" 'commit|push'; then
       BRANCH_WARN=""
       # symbolic-ref names the branch even before its first commit, where rev-parse answers "HEAD" and the very
       # first commit onto main went by without this line. A detached HEAD reads empty: not the default branch.
-      case "$(git symbolic-ref --short -q HEAD 2>/dev/null)" in
+      # Read from HEAD with builtins (the gate log's crew_git_dir finds the git dir, a linked worktree's too): the
+      # preview below pays one subshell to keep this hook's decision out of its reach, and this pays it back.
+      _hb=""; if declare -F crew_git_dir >/dev/null 2>&1 && crew_git_dir . && [ -f "$_CREW_GD/HEAD" ]; then
+        IFS= read -r _hb < "$_CREW_GD/HEAD"; _hb="${_hb%$'\r'}"; case "$_hb" in "ref: refs/heads/"*) _hb="${_hb#ref: refs/heads/}" ;; *) _hb="" ;; esac
+      else _hb="$(git symbolic-ref --short -q HEAD 2>/dev/null)"; fi
+      case "$_hb" in
         main|master) BRANCH_WARN="⚠️  This commits DIRECTLY to the default branch. Prefer a feature branch unless you meant to.
 
 " ;;
       esac
       _commit_agent_note
+      # What it takes or sends: the staged change for a commit, the commits for a push (read only).
+      _PVA=""; case "$CMD" in *push*) _PVA="$(_pv_line push-ask "$CMD")" ;; *) _PVA="$(_pv_line commit "$CMD")" ;; esac
       ask_user "§4.4 commit/push approval gate. Claude wants to run:
 
 $SHORT
 
-${BRANCH_WARN}${_CAN}Approve only if the commit message above was shown to you and you agree with it. Approving lets Claude run the command itself."
+${_PVA:+$_PVA
+
+}${BRANCH_WARN}${_CAN}Approve only if the commit message above was shown to you and you agree with it. Approving lets Claude run the command itself."
       ;;
     auto|dontAsk)
       _commit_agent_note; [ -n "$_CAN" ] && printf '%s' "$_CAN" >&2

package/kit/hooks/guard-write.sh

@@ -72,7 +72,8 @@ trap '_crew_rc=$?; trap - EXIT; case "$_crew_rc" in 0|2) exit "$_crew_rc" ;; esa
 _gate_main(){
 # 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
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"
+[ -f "$_crew_d/../eval/lib/gate-log.sh" ] && . "$_crew_d/../eval/lib/gate-log.sh"; unset _crew_d   # where the gate log goes
 # Read with the builtin, as guard-powershell.sh does: `INPUT="$(cat)"` is a subshell plus a process on EVERY call
 # of this hook. `read` returns 1 at end of input; the text is read regardless.
 IFS= read -r -d '' INPUT || true
@@ -365,12 +366,7 @@ block(){  # $1 = rule name for the log (must keep the `gate-file edit` prefix
   # and with the same rule about the payload: the path is NOT recorded unless CREW_GATE_LOG_CMD=1, because
   # /crew-gates reports rule names and counts and never the argument. Logged after the verdict; it cannot
   # change it. CREW_GATE_LOG overrides the path; point it at /dev/null to turn recording off.
-  _GL="${CREW_GATE_LOG:-}"
-  if [ -z "$_GL" ] && [ -d ".claude" ]; then
-    if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1 || git check-ignore -q ".claude/gate-log.tsv" 2>/dev/null; then
-      _GL=".claude/gate-log.tsv"
-    fi
-  fi
+  _GL=""; declare -F crew_gate_log_write >/dev/null && { crew_gate_log_write; _GL="$_CREW_GL"; }
   if [ -n "$_GL" ]; then
     if [ "${CREW_GATE_LOG_CMD:-0}" = 1 ]; then
       printf 'BLOCK\t§4.5\t%s\t%s\n' "$1" \

package/kit/hooks/precompact-snapshot.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# PreCompact hook — just before the context is compacted, write down the state of the work in a few lines, so the
+# session that comes back after the compaction is told it (session-rehydrate.sh reads it on SessionStart, source
+# compact). A compaction summary is the model's own retelling; this is what the files and the gates say.
+#
+# What it writes, at most ~2 KB: the branch, the uncommitted files (five named, the rest counted), the last refusal in
+# the gate log, how many findings each document under .crewforth/ holds, and whether a handover
+# (docs/SESSION_STATE.md) is there. With the session id and the trigger, so a snapshot is only read back into the
+# session that wrote it.
+#
+# Where: inside the repository's git directory (crewforth-session-snapshot.json), so it is never committed even in a
+# project that tracks .claude/; outside a repository, .claude/state/session-snapshot.json.
+#
+# NEVER BLOCKS. PreCompact exit 2 blocks the compaction (docs: hooks, PreCompact), and blocking an automatic one at
+# the context limit fails the request that needed it. Every path here ends in exit 0, and nothing is printed: a
+# PreCompact hook's output does not reach the summary.
+set -u
+IN="$(cat 2>/dev/null || true)"
+_here="${BASH_SOURCE%[/\\]*}"; [ "$_here" = "${BASH_SOURCE}" ] && _here=.
+LIB="$_here/../eval/lib"
+
+ROOT="${CLAUDE_PROJECT_DIR:-}"
+[ -n "$ROOT" ] || ROOT="$(printf '%s' "$IN" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)"
+[ -n "$ROOT" ] || ROOT="$PWD"
+ROOT="${ROOT//\\\\//}"; ROOT="${ROOT//\\//}"
+cd "$ROOT" 2>/dev/null || exit 0
+
+field(){ local v="${IN#*\"$1\"}"; [ "$v" = "$IN" ] && return 1; v="${v#*:}"; v="${v#"${v%%[![:space:]]*}"}"; case "$v" in \"*) v="${v#\"}"; printf '%s' "${v%%\"*}" ;; *) printf '%s' "${v%%[,\}]*}" ;; esac; }
+SID="$(field session_id)" || SID=""
+TRIG="$(field trigger)" || TRIG=""
+case "$SID" in ''|*[!A-Za-z0-9._-]*) exit 0 ;; esac   # a snapshot no session can claim is not written
+
+# ---- what the files and the gates say ----
+LINES=()
+GD=""
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  GD="$(git rev-parse --absolute-git-dir 2>/dev/null)" || GD=""
+  BR="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)" || BR=""
+  [ -n "$BR" ] && LINES+=("branch $BR")
+  # quotePath off: a name in Turkish (or any non-ASCII) is given as written, not as octal escapes (seen on Windows).
+  CH="$(git -c core.quotePath=false status --porcelain 2>/dev/null)" || CH=""
+  if [ -n "$CH" ]; then
+    n=0; names=""
+    while IFS= read -r l; do n=$((n+1)); [ "$n" -le 5 ] && names="${names:+$names, }${l:3}"; done <<< "$CH"
+    LINES+=("$n uncommitted file(s): $names$([ "$n" -gt 5 ] && printf ', and %d more' $((n-5)))")
+  else LINES+=("nothing uncommitted"); fi
+fi
+if [ -f "$LIB/gate-log.sh" ]; then
+  . "$LIB/gate-log.sh"; crew_gate_log_read
+  if [ -n "${_CREW_GL:-}" ] && [ -f "$_CREW_GL" ]; then
+    last=""; while IFS= read -r l; do case "$l" in BLOCK$'\t'*) last="$l" ;; esac; done < "$_CREW_GL"
+    if [ -n "$last" ]; then IFS=$'\t' read -r _ rule why _ <<< "$last"; LINES+=("the last refusal in the gate log: ${rule} ${why:0:120}"); fi
+  fi
+fi
+fnd=""
+for f in .crewforth/*.json; do
+  [ -f "$f" ] || continue
+  c=0; while IFS= read -r l; do case "$l" in *'"rule": '*) c=$((c+1)) ;; esac; done < "$f"
+  [ "$c" -gt 0 ] && { b="${f##*/}"; fnd="${fnd:+$fnd, }${b%.json} $c"; }
+done
+[ -n "$fnd" ] && LINES+=("findings on record: $fnd")
+[ -s docs/SESSION_STATE.md ] && LINES+=("a handover is at docs/SESSION_STATE.md")
+[ "${#LINES[@]}" -gt 0 ] || exit 0
+
+SUM=""; for l in "${LINES[@]}"; do SUM="${SUM:+$SUM; }$l"; done
+SUM="${SUM:0:1800}"
+
+# ---- where it goes ----
+if [ -n "$GD" ] && [ -d "$GD" ]; then OUT="$GD/crewforth-session-snapshot.json"
+else mkdir -p .claude/state 2>/dev/null || exit 0; OUT=".claude/state/session-snapshot.json"; fi
+if [ "${BASH_VERSINFO[0]}" -ge 5 ] || { [ "${BASH_VERSINFO[0]}" -eq 4 ] && [ "${BASH_VERSINFO[1]}" -ge 2 ]; }; then printf -v NOW '%(%Y-%m-%dT%H:%M:%SZ)T' -1; else NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"; fi
+ESC="$(printf '%s\n' "$SUM" | LC_ALL=C awk -f "$LIB/json-string.awk" 2>/dev/null)" || exit 0
+printf '{"session_id":"%s","trigger":"%s","at":"%s","summary":"%s"}\n' "$SID" "${TRIG//[!a-z]/}" "$NOW" "$ESC" > "$OUT.$$" 2>/dev/null && mv -f "$OUT.$$" "$OUT" 2>/dev/null
+rm -f "$OUT.$$" 2>/dev/null
+exit 0

package/kit/hooks/session-rehydrate.sh

@@ -68,11 +68,34 @@ if [ -f "$ROOT/.claude/hooks/pre-commit" ] && git -C "$ROOT" rev-parse --git-dir
   esac
 fi
 [ -n "$HOOKMSG" ] && MSG="${MSG:+$MSG }$HOOKMSG"
-[ -n "$MSG" ] || exit 0   # no handover to offer and nothing to say about language -> stay silent
+
+# THE STATE BEFORE THE COMPACTION. precompact-snapshot.sh wrote it just before this context was compacted: the
+# branch, the uncommitted files, the last gate refusal, the findings on record. Read back only after a compaction and
+# only into the session that wrote it (same session id); its summary is already JSON-escaped, so it is put into the
+# output as it is, and the rest of MSG stays fixed text that needs no escaping and no extra process.
+SNAP=""
+_rh="${BASH_SOURCE%[/\\]*}"; [ "$_rh" = "${BASH_SOURCE}" ] && _rh=.
+if [ "$SRC" = compact ] && [ -f "$_rh/../eval/lib/gate-log.sh" ]; then
+  . "$_rh/../eval/lib/gate-log.sh"
+  _sf=""
+  if crew_git_dir "$ROOT" && [ -f "$_CREW_GD/crewforth-session-snapshot.json" ]; then _sf="$_CREW_GD/crewforth-session-snapshot.json"
+  elif [ -f "$ROOT/.claude/state/session-snapshot.json" ]; then _sf="$ROOT/.claude/state/session-snapshot.json"; fi
+  _sid(){ _SID=""; local v="${1#*\"session_id\"}"; [ "$v" = "$1" ] && return 0; v="${v#*\"}"; _SID="${v%%\"*}"; }
+  if [ -n "$_sf" ] && IFS= read -r _sj < "$_sf" 2>/dev/null; then
+    _sid "$IN"; _mine="$_SID"; _sid "$_sj"
+    case "$_sj" in *'"summary":"'*)
+      if [ -n "$_mine" ] && [ "$_mine" = "$_SID" ]; then
+        _sum="${_sj#*\"summary\":\"}"; _sum="${_sum%\"\}*}"
+        SNAP="Before this context was compacted, Crewforth wrote down the state of the work from the files and the gates: $_sum. It is a record of that moment; check the files before relying on it."
+      fi ;;
+    esac
+  fi
+fi
+[ -n "$MSG$SNAP" ] || exit 0   # nothing to offer -> stay silent
 
 # hookSpecificOutput.additionalContext is the documented channel that injects text into the model's context.
 # ONE PATH, no jq: MSG is built from fixed constants with no quote, backslash, control character or newline, so it needs no
 # escaping and every machine emits the same bytes. If you ever make MSG dynamic, escape it the way board-sync.sh
 # does (jq-identical, measured) — a raw quote or tab here makes JSON the CLI silently drops.
-printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$MSG"
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s%s%s"}}\n' "$MSG" "${MSG:+${SNAP:+ }}" "$SNAP"
 exit 0

package/kit/hooks/session-update-check.sh

@@ -44,7 +44,9 @@
 set -uo 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
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"
+# How an install's own version is read and ordered (an rc before its final): one definition, eval/lib/version.sh.
+[ -f "$_crew_d/../eval/lib/version.sh" ] && . "$_crew_d/../eval/lib/version.sh"; unset _crew_d
 
 URL="${CREW_UPDATE_URL:-https://registry.npmjs.org/-/package/crewforth/dist-tags}"
 # plugin-stable, not main: the marketplace installs the plugin from that branch, and only an approved release
@@ -139,7 +141,10 @@ PJSON="$PR_ROOT/.claude-plugin/plugin.json"
 # plugin's copy steps aside whenever a project install is present, instead of asking the project's question too.
 if [ "$IS_PLUGIN" = 1 ] && [ -f "$CL/VERSION" ]; then exit 0; fi
 if [ -f "$CL/VERSION" ]; then
-  read -r _cv < "$CL/VERSION" 2>/dev/null || _cv=""; CUR="$(sane_version "$_cv")" || exit 0
+  # The install's own file, so an rc (X.Y.Z-rc.N) is a version here; what npm answers is still held to X.Y.Z.
+  read -r _cv < "$CL/VERSION" 2>/dev/null || _cv=""
+  declare -F crew_local_version >/dev/null || exit 0
+  CUR="$(crew_local_version "$_cv")" || exit 0
   STATE="$CL/.state"                                            # repo-local: the install lives in the repo
   FEED="${CREW_UPDATE_URL:-$URL}"; KEY=latest; EDITION=project
   ANSWER='bash .claude/hooks/session-update-check.sh --answer'
@@ -186,12 +191,8 @@ fi
 [ -n "$LATEST" ] || exit 0
 LATEST="$(sane_version "$LATEST")" || exit 0
 
-# Numeric field compare, one awk. Pre-release suffixes degrade to their numeric prefix (`1-rc2` -> 1), which is
-# the harmless direction: it can suppress a question, never invent one.
-awk -v a="$LATEST" -v b="$CUR" 'BEGIN{
-  split(a,x,"."); split(b,y,".");
-  for(i=1;i<=3;i++){ if(x[i]+0 > y[i]+0) exit 0; if(x[i]+0 < y[i]+0) exit 1 }
-  exit 1 }' || exit 0
+# One awk, eval/lib/version.sh's order: 3.2.0 is newer than an installed 3.2.0-rc.1, so the rc's user is asked.
+awk -v a="$LATEST" -v b="$CUR" "${CREW_VCMP_AWK:-}"' BEGIN { exit !(vcmp(a, b) > 0) }' 2>/dev/null || exit 0
 
 # Skipped for good? Asked (or answered "later") within the last day?
 if [ -f "$STATE/update-skip" ]; then read -r _sk < "$STATE/update-skip" 2>/dev/null || _sk=""; [ "${_sk//[!0-9.]/}" = "$LATEST" ] && exit 0; fi

package/kit/settings.json

@@ -216,6 +216,18 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/precompact-snapshot.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "startup|resume|clear|compact|fork",

package/kit/skills/crew-code-review/SKILL.md

@@ -17,6 +17,21 @@ Trigger phrases: "code-review", "review the code", "review the PR", "review my c
 A review runs in four steps — **group, plan, review, fact-check** — and reports few findings that are right rather
 than many that might be. Every step below says what it produces.
 
+## 0. The pre-pass first, and the findings in one shape
+Before reading the diff, run the deterministic pre-pass (`eval/lib/review-prepass/` in either edition):
+`bash <dir>/prepass.sh` for the staged change, `--base <ref>` for a branch. It writes
+`.crewforth/review-prepass.json`: secret patterns, a debug call or TODO left in code, shellcheck on shell files, a
+lock file that moved without its manifest, a very large change. **Carry those over, do not re-derive them**; your
+time goes to what a pattern cannot see. rc 3 (no Node) or a `notMeasured` line means that part was NOT checked:
+say so in the review, never read it as clean.
+
+Write your own findings in the same shape (`crewforth.findings/1`: `rule` `review-<category>`, `severity`,
+`confidence`, `evidence` with `file`, `line` and a `text` quote, `detail` = what to do instead) and store them with
+`bash <dir>/../findings/findings.sh write review <file>`. A `critical` or `high` finding first goes to
+**crew-refuter** (claim + `file:line`, one call per lens, in parallel) and the document is written with
+`--verified`, which then refuses any `medium`-or-higher finding without its verifiers. This is model discipline:
+no hook runs the pre-pass or reads `review.json`.
+
 ## 1. Scope
 - **Review the lines this change adds or edits.** Deleted code is context for understanding them, not a target.
 - Code that is correct, or that the change did not touch, gets no comment.
@@ -142,6 +157,7 @@ five questions that decide *answer in the thread* vs *edit the code*: **`referen
 item leaves with a disposition from the triage table above — a reasoned refusal is an answer, silence is not.
 
 ## DoD (this skill's contribution)
+- The pre-pass ran (or its rc 3 / `notMeasured` is reported as unchecked), and the findings are in `.crewforth/review.json`.
 - The plan (what changed, the risks) came before the findings; every file in each group was read.
 - Every finding has a severity, a category and a reason, in the finding format above.
 - Scope creep and hidden complexity are flagged.