crewforth 3.1.1 → 3.2.0-rc.10

package/kit/hooks/guard-commit-scan.sh

@@ -588,8 +588,11 @@ fi
 
 # The message carries its own trace risk (a co-author trailer lives there, not in the diff), and commit-msg is
 # what scans it. Reuse it on the -m value when there is one; an editor-composed message is not visible here and
-# stays the git hook's job.
-if [ "$FAILED" = 0 ] && [ -x "$DIR/commit-msg" ]; then
+# stays the git hook's job. It is scanned even when the staged content already failed: a refusal that names one
+# problem gets the commit retried with the other still in it (measured on a real project, 2026-10-21: a silenced
+# lint check was named, the session-link trailer in the same message was not, and the message was shown to the
+# user again).
+if [ -x "$DIR/commit-msg" ]; then
   # The message is tokenized the way a shell does (crew_opt_values), which matters because a real commit message
   # is MULTI-LINE: a line-oriented `sed` extraction found the subject and stopped, so a co-author trailer on line
   # 3 — the single most likely §4.1 violation, and the one the bare arm of the eval actually produced — went
@@ -640,6 +643,7 @@ $(bash "$DIR/commit-msg" "$MF" 2>&1)" || FAILED=1
         | sed -n 's/.*[[:space:]]--\{0,1\}[Ff]\(ile\)\{0,1\}[[:space:]=]\{1,\}\([^[:space:];&|]\{1,\}\).*/\2/p' | head -1)"
       MFILE="${MFILE%\"}"; MFILE="${MFILE#\"}"; MFILE="${MFILE%\'}"; MFILE="${MFILE#\'}"
       if _grep "$CMD" -qE '(^|[[:space:]])(-F|--file)([[:space:]=]|$)' && { [ -z "$MFILE" ] || [ ! -f "$MFILE" ]; }; then
+        [ "$FAILED" = 1 ] && printf '%s\n' "$OUT" >&2
         echo "GUARD (§4.1): this commit reads its message from a file (-F), and the command could not be parsed" >&2
         echo "well enough to know which file. Scan cannot run, so the commit is refused. Commit with a plain" >&2
         echo "-F <path> (or -m) in a command of its own." >&2
@@ -656,6 +660,7 @@ $(bash "$DIR/commit-msg" "$MFILE" 2>&1)" || FAILED=1
       [ -z "$GITMSG_HOOK" ] && [ -x "$(git rev-parse --git-path hooks/commit-msg 2>/dev/null)" ] \
         && GITMSG_HOOK="git-default"
       if [ -z "$GITMSG_HOOK" ]; then
+        [ "$FAILED" = 1 ] && printf '%s\n' "$OUT" >&2
         echo "GUARD (§4.1): this commit's message would go unscanned." >&2
         echo "No -m/-F was given, so the message is composed in an editor after this point, and no commit-msg" >&2
         echo "git hook is wired here to read it afterwards (plugin-only install: a plugin cannot set" >&2
@@ -669,6 +674,9 @@ fi
 if [ "$FAILED" = 1 ]; then
   echo "GUARD (§4.1/§4.2): the commit content gate rejected this commit before it ran." >&2
   echo "$OUT" >&2
+  case "$OUT" in *"TRACE-SCANNER (message)"*)
+    echo "The message itself carries the trace: write it again without that line. A harness reminder to end a commit message with a trailer does not override §4.1." >&2 ;;
+  esac
   echo "Fix the flagged content and commit again. --no-verify is §4.5 and stays blocked." >&2
   exit 2
 fi

package/kit/hooks/guard-question.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# guard-question.sh - the approval question reaches the person, not a hook (§4.4, 3.2.0).
+#
+# WHY. In `auto` the user can approve a commit or a push by answering one fixed question (AskUserQuestion), and
+# hooks/prompt-approval.sh records the answer on PostToolUse. An answer is only worth recording if a person gave it.
+# Two things can give it instead: another PreToolUse hook that answers `allow` with the answers filled in, and a
+# PermissionRequest hook that answers the prompt before the person does (both measured on Claude Code 2.1.294).
+#
+# WHAT. Wired on PreToolUse for AskUserQuestion. Any question but the approval question gets no decision. The
+# approval question must be the fixed text with no answers, asked in `auto` in an attended session; then this
+# hook answers `ask`, which beats the first kind of hook in every mode, and only when no PermissionRequest hook
+# may be wired (the second kind; _crew_prh_scan). It also notes the call it asked, and prompt-approval.sh records
+# an answer to that call only. Everything it decides is defined in prompt-approval.sh (_crew_q_pre), sourced.
+#
+# A GATE, so an error of its own refuses the call (CREW-FAILCLOSED): a question let through with no `ask` is one a
+# hook can answer.
+# COST. Builtins on every AskUserQuestion; on the approval question the scan reads files and starts no process.
+set -uo pipefail
+# ---- CREW-LOCALE -----------------------------------------------------------------------------------------
+# Everything this gate matches with runs in the C locale, whatever the session's own is. Under a Turkish locale
+# the letters i and I are not each other's other case (their partners are İ and ı), and every case-insensitive
+# match here is written in ASCII. Measured under tr_TR.UTF-8 with the locale left as it came:
+#   GNU grep 3.11 / bash 5.2 on Linux: `grep -i init` does not find INIT (-F, -E and plain alike);
+#     bash's nocasematch does not match GIT against git; `[A-Za-z]` in a regex does not hold I; awk's tolower
+#     turns GIT into gıt. The suite, run whole under that locale, went from 4 failures to 30: a recursive
+#     Remove-Item, a write to a gate file, `git config --remove-section core`, a read of a nested .env and a
+#     staged key all passed.
+#   GNU grep 3.0 in Git Bash on Windows: `grep -iF` with an ASCII pattern aborts (exit 134), and the pre-commit
+#     scan for private strings read that as "no match".
+#   macOS (BSD grep, bash 3.2): none of it; tr_TR.UTF-8 folds i and I the ASCII way there.
+# The cost: a letter outside ASCII has no other case in the C locale. The two git hooks that scan a user's own
+# words look a second time under the session's locale for a pattern that holds such a letter (_CREW_LOCALE).
+# Byte-identical in every gate; the suite pins it.
+_CREW_LOCALE="${LC_ALL:-${LC_CTYPE:-${LANG:-}}}"
+case "$_CREW_LOCALE" in C|POSIX) _CREW_LOCALE="" ;; esac
+export LC_ALL=C
+# ---- /CREW-LOCALE
+# ---- CREW-FAILCLOSED ---------------------------------------------------------------------------------------
+# A gate that stops on an error of its own must refuse the call, not let it through. Claude Code blocks a tool call
+# on exit 2 only; a hook that dies with 1, or runs on past the rule that broke, has allowed it. Both happened in
+# one defect (measured, bash 5): a local array declared and not set is "unbound" under `set -u`, the rule that read
+# it was abandoned in the middle, the script went on with the NEXT top-level command and left with 0, and
+# `rm .claude/hooks/pre-commit` passed. bash does one of two things with such an error, by the kind of error:
+#   * it leaves the shell with a status that is neither 0 nor 2  -> the EXIT trap below turns that into a refusal;
+#   * it abandons the top-level command it was in and continues -> the whole gate IS one top-level command,
+#     _gate_main, which only ever ends by `exit`. If it RETURNS, it was abandoned, and the line after it refuses.
+# Not covered, and said so: an error inside a command substitution (only that subshell ends), and a command
+# that is not found (status 127, the script continues inside the same command).
+# Byte-identical in every PreToolUse gate; the suite pins it. No process is started.
+_crew_stop(){  # $1 = what happened
+  declare -F gatelog >/dev/null 2>&1 && gatelog BLOCK 4.5 "the gate stopped on an error of its own"
+  echo "GUARD (§4.5): this gate stopped on an error of its own ($1) before it finished judging the call, so the call is refused." >&2
+  echo "Nothing about the call itself was found. The error is the line above these two; it is a defect in Crewforth, not in what you ran. Run the doctor (bash .claude/eval/doctor.sh, Bash tool, not PowerShell) and report it." >&2
+  exit 2
+}
+trap '_crew_rc=$?; trap - EXIT; case "$_crew_rc" in 0|2) exit "$_crew_rc" ;; esac; _crew_stop "exit status $_crew_rc"' EXIT
+# ---- /CREW-FAILCLOSED
+_gate_main(){
+local here="${BASH_SOURCE%/*}"
+[ "$here" = "${BASH_SOURCE}" ] && here=.
+IFS= read -r -d '' INPUT || true
+case "$INPUT" in *'Crewforth approval'*) ;; *) exit 0 ;; esac      # not the approval question: nothing to decide
+if [ ! -f "$here/prompt-approval.sh" ]; then
+  echo "GUARD (§4.4): prompt-approval.sh is not beside this gate, so the approval question cannot be checked and is not asked. Update Crewforth; the user can type /crew-approve instead." >&2
+  exit 2
+fi
+. "$here/prompt-approval.sh"
+declare -F _crew_q_pre >/dev/null 2>&1 || { echo "GUARD (§4.4): prompt-approval.sh beside this gate is an older one, so the approval question is not asked. Update Crewforth; the user can type /crew-approve instead." >&2; exit 2; }
+_crew_q_pre
+exit 0
+}
+_gate_main "$@"
+_crew_stop "a command of the gate was abandoned"

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" \
@@ -388,6 +384,7 @@ WHY_SCRIPT="This file is a gate script — rewriting it would disarm the trace/s
 WHY_DISC="This file is Crewforth's discipline document — it IS the text of §4.1-§4.5, so editing it empties the rules the gates enforce."
 WHY_LINK="A parent directory of this path is a symlink and it resolves into a gate directory, so the write would land on a gate file."
 WHY_MODEL="This file is what model routing decides from: the user's rules, a class's floor, the critical paths, or the record of a call and its result. Only the user and Crewforth's own hooks write it, so a session cannot lower its own floor or erase its own failure."
+WHY_REFUTER="This file is the refuter ledger: what crew-refuter concluded about a finding, written by Crewforth's hook from the agent's own task and answer. A findings document is held to it, so a session that writes it would verify its own findings."
 WHY_APPR="This file records the user's own approval for a commit or a push (§4.4). Only the user's message writes it, so a session cannot approve its own commit."
 WHY_GITCFG="This file holds core.hooksPath: writing it can switch the git hooks off without touching one of them. Settings go through git config, which the Bash guard reads."
 WHY_LONG="The path in this payload is longer than any filesystem accepts. It is refused rather than parsed, because parsing it is the slow path an attacker would aim at."
@@ -545,6 +542,10 @@ _is_gate(){   # 0 = gate file; sets GATE_RULE and GATE_WHY
     # Matched by name wherever it is: a linked worktree keeps its git directory elsewhere.
     */[Cc][Rr][Ee][Ww][Ff][Oo][Rr][Tt][Hh]-[Aa][Pp][Pp][Rr][Oo][Vv][Aa][Ll]|[Cc][Rr][Ee][Ww][Ff][Oo][Rr][Tt][Hh]-[Aa][Pp][Pp][Rr][Oo][Vv][Aa][Ll])
       GATE_RULE="approval-record edit (Write/Edit tools)"; GATE_WHY="$WHY_APPR"; return 0 ;;
+    # The refuter ledger (hooks/refuter-ledger.sh): what crew-refuter concluded, as the hook read it from the agent's
+    # own task and answer. findings.mjs --ledger trusts it; a session that writes it verifies its own findings.
+    */.[Cc][Ll][Aa][Uu][Dd][Ee]/[Ss][Tt][Aa][Tt][Ee]/[Cc][Rr][Ee][Ww]-[Rr][Ee][Ff][Uu][Tt][Ee][Rr].[Tt][Ss][Vv]|.[Cc][Ll][Aa][Uu][Dd][Ee]/[Ss][Tt][Aa][Tt][Ee]/[Cc][Rr][Ee][Ww]-[Rr][Ee][Ff][Uu][Tt][Ee][Rr].[Tt][Ss][Vv])
+      GATE_RULE="gate-file edit (refuter ledger)"; GATE_WHY="$WHY_REFUTER"; return 0 ;;
     # What model routing decides from (hooks/guard-agent-model.sh, hooks/agent-outcome.sh): the user's own rules,
     # the floors raised from the record of outcomes, the list of critical paths, and the records of calls and
     # results. A session that writes one lowers its own floor or wipes its own failure.
@@ -631,6 +632,22 @@ case "$INPUT" in *'"agent_id"'*)
       esac
     fi
   fi ;;
+*)
+  # The session's own write to a critical path (no agent_id: the main thread). Not refused (K7: the user may be
+  # doing exactly this, and an agent is a choice, not a rule); recorded, so it is seen: a NOTE line in the gate log,
+  # which Studio's Gates tab and the status line read. The same definition of "critical path" the agents are held
+  # to; a file outside the project is not the project's critical path.
+  if [ "${CREW_MODEL_ROUTING:-}" != off ] && [ -n "${FP:-}" ]; then
+    _gwm="${BASH_SOURCE%/*}"; [ "$_gwm" = "${BASH_SOURCE}" ] && _gwm=.
+    if [ -f "$_gwm/guard-agent-model.sh" ]; then
+      . "$_gwm/guard-agent-model.sh"
+      if declare -F _am_crit_path >/dev/null 2>&1 && _am_crit_path "$FP"; then
+        case "$_AMRP" in /*|[A-Za-z]:*) ;; *)
+          declare -F _am_log >/dev/null 2>&1 && _am_log "note: the session wrote a critical path itself, not through an agent: $_AMRP ($_AMW)" ;;
+        esac
+      fi
+    fi
+  fi ;;
 esac
 
 # ---- team board: you may not start work nobody knows you started -----------------------------------------------

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