crewforth 3.1.1 → 3.2.0-rc.10

package/kit/hooks/refuter-ledger.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# refuter-ledger.sh - the record of what crew-refuter concluded, written by the hook and not by the session.
+#
+# WHY. A findings document can say a finding was verified. That sentence is the session's own; the ledger is not.
+# When a crew-refuter agent stops, this hook reads the TASK it was given (the first record of its own transcript)
+# and the ANSWER it ended with (last_assistant_message), and adds one line when the two agree on the finding and
+# the lens:
+#
+#   ts  session  agent_id  finding  lens  verdict              .claude/state/crew-refuter.tsv
+#
+# kit/eval/lib/findings/findings.mjs `validate --ledger` holds a document to it: a medium-or-higher finding needs
+# verifiers, and every verifier it names must be a line here, with the same finding, lens and verdict.
+#
+# Wired to SubagentStop with a matcher on the agent type, so it starts for crew-refuter only; the type is checked
+# again here. It works whatever CREW_MODEL_ROUTING says: this is not model routing.
+# THIS NEVER BLOCKS. It exits 0 on every path: a stop hook that failed closed would keep an agent running.
+# The ledger is protected from the session the way the routing records are (guard-bash.sh, guard-write.sh): a plain
+# attempt to write it is refused; a determined one (an interpreter, a name built from pieces) is not, and that is
+# the stated scope of those guards.
+set -uo pipefail
+export LC_ALL=C
+_rl_here="${BASH_SOURCE%[/\\]*}"; [ "$_rl_here" = "${BASH_SOURCE}" ] && _rl_here=.
+[ -f "$_rl_here/guard-agent-model.sh" ] || exit 0
+. "$_rl_here/guard-agent-model.sh"
+declare -F _json_slice >/dev/null 2>&1 || exit 0
+
+IFS= read -r -d '' INPUT || true
+_json_slice "$INPUT" hook_event_name >/dev/null; [ "$_JS" = SubagentStop ] || exit 0
+_json_slice "$INPUT" agent_type >/dev/null; [ "${_JS##*:}" = crew-refuter ] || exit 0
+_json_slice "$INPUT" agent_id >/dev/null; AID="$_JS"
+case "$AID" in ''|*[!A-Za-z0-9._-]*) exit 0 ;; esac
+_json_slice "$INPUT" session_id >/dev/null; SID="$_JS"
+case "$SID" in ''|*[!A-Za-z0-9._-]*) SID=- ;; esac
+
+# One field of a text: the value after "<key>:" at the start of a line, first occurrence, trimmed.
+_rl_field(){  # $1 text, $2 key (any case) -> _RLF
+  local line k; _RLF=""
+  while IFS= read -r line; do
+    line="${line%$'\r'}"; line="${line#"${line%%[![:space:]]*}"}"
+    k="${line%%:*}"; [ "$k" = "$line" ] && continue
+    shopt -s nocasematch
+    if [[ "$k" == "$2" ]]; then shopt -u nocasematch
+      _RLF="${line#*:}"; _RLF="${_RLF#"${_RLF%%[![:space:]]*}"}"; _RLF="${_RLF%"${_RLF##*[![:space:]]}"}"; return 0
+    fi
+    shopt -u nocasematch
+  done <<< "$1"
+  return 1
+}
+
+# The task: the first record of the agent's own transcript (a string, or a list whose first block holds the text).
+_json_slice "$INPUT" agent_transcript_path >/dev/null; _json_unescape "$_JS" >/dev/null; ATP="${_JU//\\//}"
+[ -f "$ATP" ] || exit 0
+L1=""; IFS= read -r L1 < "$ATP" || true
+_json_slice "$L1" content >/dev/null; TXT="$_JS"
+[ -n "$TXT" ] || { _json_slice "$L1" text >/dev/null; TXT="$_JS"; }
+_json_unescape "${TXT:0:8000}" >/dev/null; TASK="$_JU"
+_rl_field "$TASK" finding || exit 0; F_TASK="$_RLF"
+_rl_field "$TASK" lens || exit 0; L_TASK="$_RLF"
+
+# The answer, and it must be about the same finding and lens.
+_json_slice "$INPUT" last_assistant_message >/dev/null; _json_unescape "$_JS" >/dev/null; ANS="$_JU"
+_rl_field "$ANS" finding || exit 0; F_ANS="$_RLF"
+_rl_field "$ANS" lens || exit 0; L_ANS="$_RLF"
+_rl_field "$ANS" verdict || exit 0; V="$_RLF"
+[ "$F_TASK" = "$F_ANS" ] && [ "$L_TASK" = "$L_ANS" ] || exit 0
+[[ "$F_TASK" =~ ^[a-z0-9][a-z0-9._:-]*$ ]] && [ "${#F_TASK}" -le 200 ] || exit 0
+case "$L_TASK" in reachability|protection|reproduction|exclusion|blast-radius|claim) ;; *) exit 0 ;; esac
+case "$V" in TRUE_POSITIVE|FALSE_POSITIVE|CANNOT_VERIFY) ;; *) exit 0 ;; esac
+
+P="${CLAUDE_PROJECT_DIR:-$PWD}"; P="${P//\\//}"; P="${P%/}"
+D="$P/.claude/state"; T="$D/crew-refuter.tsv"
+mkdir -p "$D" 2>/dev/null || exit 0
+# An agent that is resumed stops again: it answered once, and that answer stands.
+if [ -f "$T" ]; then
+  while IFS=$'\t' read -r _ _ a _; do [ "$a" = "$AID" ] && exit 0; done < "$T"
+fi
+[ -s "$T" ] || printf 'ts\tsession\tagent_id\tfinding\tlens\tverdict\n' > "$T" 2>/dev/null
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"; case "$TS" in [0-9][0-9][0-9][0-9]-*Z) ;; *) TS=- ;; esac
+printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$TS" "$SID" "$AID" "$F_TASK" "$L_TASK" "$V" >> "$T" 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/hooks/trace-blocklist.txt

@@ -12,6 +12,15 @@
 
 Co-Authored-By
 #test: Co-Authored-By: An Assistant <noreply@example.com>
+# The session-link trailer Claude Code asks the model to end a commit message with: it reached six pushed commits of a
+# project with Crewforth installed (2026-10-18), because nothing here named it. The trailer and the address are both
+# caught, so a message that keeps only one of them is still stopped. One line, not two: each line is one grep on every
+# commit (a process, 62-135 ms on Git Bash).
+Claude-Session:|claude\.ai/code/session_
+#test: Claude-Session: https://claude.ai/code/session_0123456789abcdef
+#test: see https://claude.ai/code/session_0123456789abcdef for the run
+#test-clean: the claude session limit is reached
+#test-clean: https://claude.ai/code is the web app
 # "Generated by/with" alone matched every machine-written header in existence — a pubspec.lock, an EF Core
 # scaffold, protoc, openapi-generator. A live --dotnet install could not make its FIRST commit because the
 # cloned base carries a Dart lockfile saying "Generated by pub". §4.1 is about AI AUTHORSHIP, so the pattern

package/kit/owned-blobs.tsv

@@ -1,10 +1,10 @@
-# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.1.0 (below VERSION 3.1.1) — do not edit by hand.
+# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.1.1 (below VERSION 3.2.0) — do not edit by hand.
 # The flat files Crewforth owns: a copy whose bytes (CR aside) are one of these ids was never edited.
 # install_path	blob_sha1	first_tag	last_tag
 .claude/AGENT_TEMPLATE.md	075e2c26706c06f56af01652cd24c36918513bee	v3.0.0	v3.0.4
 .claude/AGENT_TEMPLATE.md	3fdc551d221ee3665b21ef8cc3563de861a9abe6	v1.4.0	v1.6.3
 .claude/AGENT_TEMPLATE.md	686fed306c873b45c245c77a95a8e6de6ee383d5	v1.7.0	v2.11.0
-.claude/AGENT_TEMPLATE.md	7ab19417b6ff3ac732e2c894be17ffb3ec091f7d	v3.1.0	v3.1.0
+.claude/AGENT_TEMPLATE.md	7ab19417b6ff3ac732e2c894be17ffb3ec091f7d	v3.1.0	v3.1.1
 .claude/AGENT_TEMPLATE.md	981df9ea27b6f1c5ab5cb509d40875a07603858d	v2.12.0	v2.13.0
 .claude/AGENT_TEMPLATE.md	b38b9c9b799156e07280ca886230524563acc75c	v1.0.5	v1.3.0
 .claude/AGENT_TEMPLATE.md	faec09e45543b75763c43bb24114a7b6355649ec	v1.0.0	v1.0.4
@@ -26,7 +26,7 @@
 .claude/DISCIPLINE.md	76d73a4e25c559ea361618862cde8480b1a6d8c2	v3.0.0	v3.0.0
 .claude/DISCIPLINE.md	b1ab7549b571dd2fc80d5777e0ae3185d29bd7b6	v2.13.0	v2.13.0
 .claude/DISCIPLINE.md	b7e1066451a8590e0a2607ad0a6fe80b21599c53	v1.1.3	v1.1.8
-.claude/DISCIPLINE.md	b90a067ee323a08146862b889293f8feb49f8e7e	v3.1.0	v3.1.0
+.claude/DISCIPLINE.md	b90a067ee323a08146862b889293f8feb49f8e7e	v3.1.0	v3.1.1
 .claude/DISCIPLINE.md	bf062c2b51a9cf3cc4d0caac389c148cf6fdc977	v2.12.0	v2.12.0
 .claude/DISCIPLINE.md	c693f1bd5832ce570058c6eedcacb5dff13d89e8	v1.10.0	v1.10.0
 .claude/DISCIPLINE.md	d63a01a183c9a80d739c840a511d338dc2765820	v1.4.0	v1.4.4
@@ -43,4 +43,4 @@
 .claude/README.md	97d4dd1f7f1695052cc1d06cc43f5bcdc603c989	v1.0.0	v1.0.4
 .claude/README.md	a3419891cfda7385564008e4befc1007bc5364cb	v1.1.1	v1.7.0
 .claude/README.md	a3b76e0fa31267610d28b742c122a962f6db59c4	v3.0.1	v3.0.4
-.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.1.0
+.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.1.1

package/kit/settings.json

@@ -108,6 +108,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-question.sh",
+            "timeout": 600
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -142,6 +153,12 @@
             "shell": "bash",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/session-guard.sh",
             "timeout": 60
+          },
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/prompt-approval.sh",
+            "timeout": 60
           }
         ]
       }
@@ -168,6 +185,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "(.*:)?crew-refuter",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/refuter-ledger.sh",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -181,6 +209,29 @@
             "timeout": 60
           }
         ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/prompt-approval.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/precompact-snapshot.sh",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "SessionStart": [

package/kit/skills/crew-approve/SKILL.md

@@ -26,4 +26,11 @@ Read the line Crewforth added to this turn and do what it says:
   the argument was not `commit`, `push` or `commit+push`. Say which, and in the first case run the command and let
   the gate's own prompt ask.
 
+In `auto` the same approval can be given with one click: the gate's refusal prints a fixed AskUserQuestion, and
+the user's answer is recorded exactly like this command. Where a `PermissionRequest` hook may be wired (in the
+user's, the project's or a plugin's settings, or in a skill's or an agent's front matter), that question is closed,
+and so is the gate's own prompt in `default` / `acceptEdits`, because such a hook answers a prompt before the user
+does. This command is then the one approval left, in those modes too. Settings passed with `--settings` and
+managed settings delivered by a server cannot be read, so a hook there is past the check.
+
 Force-push and the rest of §4.5 are not opened by this.

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.

package/kit/skills/crew-doctor/SKILL.md

@@ -24,7 +24,7 @@ Verify Crewforth is actually *active* in this project (not just present on disk)
 5. Summarise: **healthy**, or the precise fixes applied/needed, plus the readiness score. If it's not a git repo,
    note that the commit-time gates need `git init` + `git config core.hooksPath .claude/hooks`.
    If the output contains a line starting with ⭐, pass it to the user verbatim as the LAST line of your summary —
-   it prints once per Crewforth version, and it is meant for the user, not for you.
+   it prints once per Crewforth version here (the installer has its own once), and it is meant for the user, not for you.
 
 If `.claude/eval/doctor.sh` doesn't exist, this is not a full (start.sh / adopt.sh) install — Crewforth is likely
 running as a **plugin**, whose hooks are managed by Claude Code itself; there's nothing for the doctor to check,
@@ -52,3 +52,7 @@ found no Git Bash: tell the user the gates do not run and that the fix is Git fo
 scripts are developer instruments: they inspect an installation from outside it, and the plugin edition has no
 installation to inspect. Say this plainly when someone asks why `/crew-doctor` reports only the listing (and, on Windows, Git Bash) on a plugin install,
 rather than treating it as a defect. The Studio panel ships in both editions (`/crew-studio`).
+
+**On a plugin install, end with the star line** the full install's doctor prints: `bash "${CLAUDE_PLUGIN_ROOT}/eval/lib/star.sh" --once . doctor`
+(Bash tool, not PowerShell). It prints once per plugin version, or nothing; if it prints a line starting with ⭐, pass it to the
+user verbatim as the LAST line of your summary.

package/kit/skills/crew-handoff/SKILL.md

@@ -6,8 +6,9 @@ metadata:
 ---
 # /crew-handoff
 applies the `handoff` skill:
-1. Read the measured fill: the `🔋 Session` line, or `bash .claude/hooks/context-usage.sh --verbose` (Bash tool, not PowerShell).
-2. Write an actionable handover to `docs/SESSION_STATE.md`: Done · In progress (exactly where) · Next step · Open decisions · File pointers · Blockers.
+1. **crew-session-manager** (@agent-crew-session-manager) measures the fill (`context-usage.sh`, never a guess), gives the
+   recommendation and drafts the handover. The steps below work from its draft.
+2. Write the handover to `docs/SESSION_STATE.md`: Done · In progress (exactly where) · Next step · Open decisions · File pointers · Blockers.
 3. Preserve decision rationale; the next session should not start from scratch.
 4. **Cold-reader pass** (`handoff/references/cold-reader.md`): the questions are written from the work BEFORE the
    file, then answered from the file alone. Anything unanswerable goes back into the handover and is re-checked.

package/kit/skills/crew-map/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: crew-map
+description: Map the project — modules, what they touch, the gaps between them — and describe each module from the lines the scan cites.
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+# /crew-map
+
+Write `.crewforth/crew-map.json`, then describe it. The scanner draws the map from the files; you add only what
+it cannot: a sentence or two on what each module is for, and a short overview. Every description points at lines
+the scan itself read, and a gate holds it to that. **Never commit.** Show the diff and stop.
+
+1. **Resolve the scanner.** Both editions carry it, in different places:
+
+   ```
+   PLUGIN_MAP=${CLAUDE_PLUGIN_ROOT}/eval/lib/crew-map/crew-map.sh
+   ```
+
+   Claude Code replaces `${CLAUDE_PLUGIN_ROOT}` in this text before you read it, and only in the plugin. If the
+   line above names a real path, that is the scanner; if it still shows `${CLAUDE_PLUGIN_ROOT}`, this is a full
+   install and the scanner is `.claude/eval/lib/crew-map/crew-map.sh`. Below, `MAP` is whichever it is.
+
+2. **Scan:** `bash MAP` at the project root (Bash tool, not PowerShell). It writes the map and keeps the
+   descriptions of an earlier run that still cite only lines this scan cites; it says how many it kept and dropped.
+   rc 3 is no usable Node: say so and stop, it is not a pass.
+
+3. **Describe.** Read `.crewforth/crew-map.json`, and as much of the cited source as you need. Then edit that
+   file, changing ONLY these fields:
+   - each `module` node's `narrative`: `{ "text": "…", "cites": ["file:line", …], "layer": "…", "domain": "…" }`.
+     What the module is for, in at most two sentences. Every cite is a `file:line` the scan read for THAT node: its
+     `evidence`, its `entryPoint`, or its `about` (the first prose line of its README); cite at least one. `layer` is where it sits, one of `ui` (what a person uses: an app, a site),
+     `api` (serves requests to others), `service` (runs work: a worker, a job), `data` (holds or shapes data),
+     `infra` (deploys and runs the rest), `tool` (a script or CLI for the team), `library` (code other modules
+     import); `domain` is the part of the business it serves, a short phrase ("payments", "mail import"). Both
+     are optional and rest on the same cites: leave one out rather than guess. Leave a node `null` when its
+     evidence does not tell you what it is for: an honest gap beats a guess.
+   - the document's `overview`: the same shape, at most 2000 characters, for someone new to the project: the entry
+     points, where data goes, the risky places. Its cites may be any node's evidence.
+   - the document's `tour`: `[{ "node": "<id>", "text": "…", "cites": ["file:line"] }, …]`, one to eight stops a
+     newcomer reads in order, usually the entry point first and the riskiest place last. Each stop names a node of
+     the map, says in at most two sentences why to look there, and cites lines from that node's own evidence.
+   Describe what the cited lines show. A connection, a purpose or a risk the scan did not find is not added here:
+   say it to the user instead.
+
+4. **Validate:** `bash MAP --validate` (Bash tool, not PowerShell). It refuses a description that cites a line
+   the scan did not read, cites nothing, or runs past two sentences; a layer not on the list or a domain written
+   as a sentence; a tour stop at no node, citing another node's lines, or at a node twice; and a map whose
+   scanner fields were changed.
+   Fix what it names, in the descriptions only, until it holds.
+
+5. **Hand over:** the scan's summary line, how many modules you described (and gave a layer) and how many you
+   left `null` and why, the tour's stops,
+   then `git diff --stat .crewforth/crew-map.json`. Studio's **Map** view (`/crew-studio`) draws the result.
+   Committing it is the user's call.

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

@@ -9,12 +9,15 @@ Run the change set through the review trio (read-only). **The audits go out in p
 1. **At once, in ONE message** — several `Agent` calls, because none of these writes code and so there is
    nothing to serialise:
    - @agent-crew-security-expert (security-scan) — auth/IDOR/injection/secret; findings with severity.
+     Each `medium`-or-higher one then goes to **crew-refuter** (@agent-crew-refuter; claim + `file:line`, one call per lens, in
+     parallel) before it is reported; `findings.sh write --verified` refuses one its ledger does not back.
    - @agent-crew-performance-expert (`performance`) — hot path, query/loop, render, payload. Reports
      **candidates** (reasoned) and **findings** (measured) separately; an unmeasured claim is never a verdict.
    - @agent-crew-privacy-agent (`privacy-compliance`) — **when the diff touches personal data**: legal basis,
      minimisation, retention, transfer.
 2. (if SonarQube is in use) **sonarqube-check** — 0/0/0/0 gate (language-agnostic).
-3. **Last, once 1-2 leave no blocker:** @agent-crew-review-agent (crew-code-review) — "does it improve overall
+3. **Last, once 1-2 leave no blocker:** @agent-crew-review-agent (crew-code-review) — it starts from the
+   deterministic pre-pass (`.crewforth/review-prepass.json`) and writes `.crewforth/review.json`; "does it improve overall
    code health": the plan (what changed, the risks), then findings with a severity and a category. "Clean" means
    what crew-code-review means by it: **no critical or high finding open**. A medium or low audit finding does not
    hold the reviewer back; hand it over in the reviewer's prompt and keep it in the report. A critical or high one

package/kit/skills/crew-ship/SKILL.md

@@ -9,7 +9,9 @@ Closure flow — in order:
 1. **DoD gate:** was `/simplify` applied · are tests green (@agent-crew-test-expert) · (if SonarQube is used) `sonarqube-check` 0/0/0/0.
    If any one is red, **STOP**, report what is missing; no deferral.
 2. If clean, @agent-crew-commit-agent (commit-message) **proposes** an atomic Conventional Commit from the staged diff.
-3. Commit runs ONLY if the user says "commit" (§4.4). "Done" is not approval.
+3. Commit runs ONLY if the user says "commit" (§4.4). "Done" is not approval. In `auto`, Crewforth hands the session the
+   one-click approval question when crew-commit-agent is called: ask it with the message; the typed `/crew-approve` is
+   for when no question is offered.
 4. **Close the board item too** (`teamboard`), when one is held. Closing work is one movement: ask what shipped,
    run `board.sh done <id> "<note>"`, name the items it unblocked, and offer the next one as options. Do not
    leave this to the user to remember — a claim nobody closes reads to the whole team as still in progress, and

package/kit/skills/crew-update/SKILL.md

@@ -32,7 +32,7 @@ Bring the Crewforth install up to the latest published version:
    (no flags) in **their own terminal**, where both the npx and the interactive prompts work.
 7. **After:** run `bash .claude/eval/update-guard.sh post` (Bash tool, not PowerShell) and show the user its lists — added, changed, moved,
    removed.
-8. **Verify:** run `/crew-doctor` (or `bash .claude/eval/doctor.sh` — Bash tool, not PowerShell) so a bad/partial update surfaces immediately.
+8. **Verify:** run `CREW_NO_STAR=1 bash .claude/eval/doctor.sh` (Bash tool, not PowerShell) so a bad/partial update surfaces immediately; the updater has already shown the star line, if it was due.
    If the updater's or doctor's output contains a line starting with ⭐, pass it to the user verbatim as the LAST
    line of your summary — it prints once per Crewforth version, and it is meant for the user, not for you.
 9. **Report** old → new + the headline changes. Take them from `.claude/.state/whats-new.md` — the updater writes

package/kit/skills/incident-runbook/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: incident-runbook
 description: |
-  Production incident response: diagnose → mitigate → resolve, then a blameless postmortem and a repeatable
+  Incident response: diagnose → mitigate → resolve, then a blameless postmortem and a repeatable
   runbook. Stop the impact first, root cause second.
-  Use when production is degraded or broken, and again for the postmortem afterwards.
+  Use when production is degraded or broken, an outage keeps recurring, or for the postmortem.
 ---
 
 # Incident Response & Runbook

package/kit/skills/security-scan/references/verify.md

@@ -19,9 +19,12 @@ audit). Each verifier:
 Three passes inside one context window are not three verifiers. The second pass has already read the first one's
 reasoning; the blindness above is then a wish, not a property, and the agreement it produces is one argument
 counted three times. So:
-- **Each verifier is its own subagent** (`Agent`, one call per verifier, run in parallel). A subagent has its own
-  context window: it cannot see what the others concluded, which is the whole point. Read-only work, so no
-  `worktree` is needed — nothing is being written.
+- **Each verifier is its own `crew-refuter` call** (one call per verifier and lens, run in parallel). A subagent
+  has its own context window: it cannot see what the others concluded, which is the whole point. Read-only work,
+  so no `worktree` is needed — nothing is being written. Its task is the card, then `finding:`, `lens:`, `cite:`
+  and `claim:` (its agent file has the exact form); when it stops, `hooks/refuter-ledger.sh` records the verdict
+  in the refuter ledger, and `findings.sh write --verified` refuses a `medium`-or-higher finding whose verifiers
+  are not there. The ledger is the gate; the prompt that carries no reasoning is still discipline.
 - **Give it the finding and the file:line, never your reasoning.** Not "I think X is exploitable because Y" —
   just "claim: X at file:line. Try to refute it."
 - **If you did not isolate, say so.** Write `verifiers: 1 (single pass, not isolated)` in the verdict block. A

package/kit/studio/README.md

@@ -198,6 +198,27 @@ reported as unreachable, never as empty.
 Nothing listens on a network interface in this arrangement: both Studios stay on
 loopback and the tunnel does the crossing.
 
+## Remote viewers
+
+A viewer is a second token that reads and changes nothing, for watching the
+panel from a phone on the same Wi-Fi without handing it the panel. Add one in
+the Machines tab; its link is shown once, as a QR code (`web/qr.js`, made in the
+page). The server refuses a viewer's every request that is not a `GET`, and its
+reads of `/api/remote`, with 403 before any handler runs (`server/lib/remote.js`).
+A viewer lasts eight hours, then its link answers 401 and the page says Session
+expired. Revoke ends the token at once and closes a stream it holds open.
+Viewers live in memory and end with the server.
+
+Transcripts are hidden unless the viewer was added with them shown: the routes
+that are only transcript are refused, and every other answer, the event stream
+included, passes through `server/lib/redact.js`, which drops every string whose
+key is not on its allow-list.
+
+While a viewer is live the server also listens on the machine's private Wi-Fi
+address (`server/lib/lan.js`), and there it takes a viewer's token only, never
+the panel's. With none, it is on loopback alone. Every viewer connection and
+refusal is logged (`GET /api/remote`, and the server's output).
+
 ## What Crewforth already measured
 
 The panel does not recompute any of it. Selecting the session node opens what
@@ -249,8 +270,10 @@ channel that does not exist.
 
 ## Security
 
-The server binds to `127.0.0.1` only, and the host is deliberately not
-configurable — it reads a developer's live sessions and can start new ones.
+The server binds to `127.0.0.1`, and the host is deliberately not configurable —
+it reads a developer's live sessions and can start new ones. The one exception is
+the Wi-Fi listener above: open only while a viewer is live, for viewer tokens
+only, read-only.
 
 A token is always required for `/api/`. Supply one, or let the server generate
 one and print it with the URL: