crewforth 3.1.1 → 3.2.0-rc.2

package/CHANGELOG.md

@@ -5,6 +5,177 @@ Crewforth was named Claude Starter Kit until 3.0.0.
 Notable changes to this project are recorded here. Format follows [Keep a Changelog](https://keepachangelog.com/en/),
 versioning follows [SemVer](https://semver.org/).
 
+## [Unreleased] — 3.2.0
+
+### Added
+
+- **In `auto`, approve a commit or a push with one click.** The refusal now also offers a fixed question, asked with
+  AskUserQuestion: Commit only, Commit + push, Push only, No. A new gate, `guard-question.sh`, answers `ask` on it,
+  so a hook that fills in the answer cannot answer it for you (measured in 34 runs and by hand in the terminal), and
+  `prompt-approval.sh` records your click exactly as it records `/crew-approve`: tied to what is staged, `HEAD`, the
+  session, for 30 minutes.
+  Any other wording, a question with answers already in it, or an answer the hook did not ask for records nothing.
+- **Studio's Models view shows normal work that ran above the table's model.** The gate holds a floor, not a
+  ceiling, so this is shown and nothing is blocked: the classes of normal work that ran higher than Sonnet and than
+  the floor the gate held them to, with what they cost as run and the same tokens at Sonnet's list price. That
+  Sonnet is enough for a class is said only when its last ten verified calls on Sonnet all passed first time, the
+  test a held class is offered for lowering by; otherwise the view says it is not measured.
+- **Studio draws a project's crew map.** The Map view (`p`, or **Map** under a project in the navigator, beside its
+  number of findings) reads `.crewforth/crew-map.json` and scans nothing. Modules sit in bands from the clients down
+  to the external resources, and a module the map does not place goes to Unplaced. Lines are solid where a file
+  proves them, dotted where inferred, and marked where the model proposed them. The pane pans and zooms with the
+  graph's own code; a card placed by hand stays placed for the project, and modules sharing a folder fold into one
+  card. The findings are listed proven first, with the scanner's hidden rules counted until asked for. The inspector
+  copies any `file:line` and copies a finding as a task. Compare with matches another project's calls against this
+  one's endpoints. On a phone, the findings and a list of the modules stand in for the pane.
+- **A crew map of the project.** `bash .claude/eval/lib/crew-map/crew-map.sh` reads the modules (Node and TypeScript,
+  Python, Go, .NET, Java and Kotlin), the external resources they touch, the endpoints they provide and call, and
+  writes `.crewforth/crew-map.json`. Every module, line and finding cites the `file:line` it was read from, the same
+  tree gives the same bytes (`--check` holds it in CI), and a configuration value is read only to name its kind. Ten
+  gap rules: five proven by the lines they cite, five concluded from absence and hidden until their false-positive
+  rate is measured.
+- **Findings are held to the lines they cite.** The findings core (`.claude/eval/lib/findings/findings.sh`) checks
+  every citation: the file is inside the project, the lines exist, and they are still the lines that were read. A
+  document that does not verify is reported entry by entry and never written.
+- **A finding is verified by an agent that tries to refute it.** `crew-refuter` gets one claim and its cited lines,
+  not the reasoning, and works on one lens. `refuter-ledger.sh` records its verdict from the agent's own task and
+  answer in `.claude/state/crew-refuter.tsv`. With `--verified`, a `medium` finding needs one verdict and a `high` or
+  `critical` one three, each a line of that ledger.
+- **`crew-docs-agent` writes the text.** README, guides, release notes, legal and privacy texts and store listings had
+  no owner and ran outside model routing. Legal, privacy, consent and terms paths and store metadata are critical
+  paths, so that text runs on the critical tier and a legal or privacy text is audited by `crew-privacy-agent` before
+  it closes.
+- **Doctor names three more things, none of which changes its verdict.** Both editions enabled at once (every hook
+  would run twice), read from `claude plugin list --json`; the advisor, whether it is on, on what and from which
+  settings file, or turned off; and, before any update check has run, the published version, said as not measured
+  instead of nothing.
+- **Studio shows why work was critical, and says when an agent is outside routing.** The gate records its reason
+  (`risk_why`, a new last column of `model-outcomes.tsv`) and the inspector shows it under the task card; an older
+  line shows none rather than a guessed one. An agent that is not `crew-*` gets a Model routing note: the gate leaves
+  it alone, so it has no card.
+- **Studio counts the advisor in what a session cost.** An advisor call is billed at the advisor model's rates and the
+  API keeps it out of a response's top-level usage; Studio now reads it from `usage.iterations` and prices it at its
+  own model. The session table has an Advisor line (calls, tokens, cost) when a call is recorded. Measured on a real
+  session: Studio read $0.0567 before, $0.2110 after, the same as Claude Code's own figure.
+- **Studio's Models view marks the classes whose agents consulted the advisor.** The cost cell carries an advisor tag
+  whose hover says how many calls and how much of the cost they were, already included; a class whose agents consulted
+  none has no tag.
+- **Read-only remote viewers for Studio.** The Machines tab makes a viewer link that only reads, lists each viewer
+  with its last request, and revokes it. The server still binds to `127.0.0.1`; watching from another device goes
+  through a tunnel you run (`ssh -L`, Tailscale).
+- **A visible way to the repository.** `/crew-doctor` now shows the star line once per version under its own marker,
+  so a line already shown at install no longer silences it, and a plugin install shows it too, with the plugin's
+  version. `/crew-update` keeps it to one line per update. The READMEs and the site's home page have a Star on GitHub
+  button.
+- **A status line.** One line under the prompt: the gate's last word in this session, a commit or push approval that
+  still holds, the crew agents still running, the measured context fill and the session's cost. The installers set it
+  only where no status line is set, in the project or in your own settings, and `/crew-doctor` says which one is in
+  use.
+- **`/crew-map`.** It runs the scanner, then has the model describe what it found: at most two sentences per module on
+  what it is for, and a short overview, each citing lines the scan itself read. `crew-map.sh --validate` refuses a
+  description that cites anything else or nothing, or a scanner field changed by hand; a scan again keeps the
+  descriptions that still hold and drops the rest. Studio's Map shows them, and `crew-planner` reads the map on an
+  unfamiliar project.
+
+### Changed
+
+- **A model is chosen to cost what the work needs.** Measured on a real project: 186 crew tasks, 0 on haiku, 73 (39%)
+  above their card's floor, and no verify command ever passing, so the cheaper path never opened. Now:
+  - the card's model is the default: a call above it runs on it (the gate rewrites the call's model), unless the
+    card adds `above: <why>`;
+  - outside the crew, a call asking for opus or fable runs on sonnet, and so does a general-purpose call that names
+    no model in a session that is not on haiku (it took the session's model; measured on Claude Code 2.1.299, the
+    project's settings `env` could not change that, so the gate does);
+  - a verify command in a sub-folder (`cd apps/x && <command>`, 41 of 71 refusals) is run in that folder;
+    `none (why)` is none; and `/crew-doctor` lists the commands that were never allowed to run, with the line that
+    allows each.
+
+- **A commit's command is read by one reader.** `guard-bash.sh` paired quotes in three places: the reader of a call,
+  an older walk that looks for a path or `-a` in a commit, and the check of a call the user's approval covers. The
+  last two now take their text from the first, and keep only their own question. What a call the user approved may
+  hold is unchanged. The older walk read a here-document's body and a comment as arguments of the commit; it no
+  longer does, so a call that only holds the words of a commit inside a here-document body, or `-a` after a `#`,
+  asks as any other commit does instead of being refused.
+- **npm releases are published over OIDC.** The release job proves its identity with a short-lived GitHub Actions
+  token (npm Trusted Publishing); the repository holds no npm token, and each version carries a provenance statement.
+- **The session line shows the measured fill.** The last line of a reply was `🔋 Session: low fill · …`: the template
+  had no number, so the figure the hook measures every turn stayed out of sight. It is now `🔋 Session %NN → low fill ·
+  …`, the hook's own figure, never an estimate.
+- **Studio keeps cards for a longer session.** At Auto density a picture may now run up to half again past the pane
+  before its cards become chips; it opens at the zoom cards are read at, from its top, and Fit still shows all of it.
+  A compact group card says how its agents went as well as their models (`5 done · 3 Sonnet · 2 Opus`).
+- **The session's own write to a critical path is recorded.** Agents not on Opus are refused a critical path; the
+  session's own writes were not looked at at all. They are still not refused (the choice is yours), but each one now
+  leaves a NOTE line in the gate log with the path and the rule that made it critical, which Studio's Gates tab and
+  the status line show.
+
+### Security
+
+- **A `PermissionRequest` hook could approve a commit with nobody at the keyboard.** Such a hook answers a
+  permission prompt before the person does, and the answer cannot be told from a click: measured, it approved the
+  Bash prompt `guard-bash.sh` raises for a commit in `default`, and it answered the new question too. Before it
+  asks, the gate now looks for one in every source it can read (user, project and local settings, the
+  managed-settings files, skill, agent and command front matter, installed plugins). Where one may be wired the
+  question closes, and so does the gate's own prompt in `default` and `acceptEdits`: `/crew-approve`, which no hook
+  can type, is the approval left. The limit: settings passed with `--settings` and managed settings delivered by a
+  server cannot be read.
+- **`crewforth.hookschain` is guarded the way `core.hooksPath` is.** The key holds the path of a project hook chain
+  the shim reads on every commit, and `git config crewforth.hookschain …` passed. A write is now refused in every form
+  `core.hooksPath` is (a value, `--unset`, `-c`, `--config-env`, `GIT_CONFIG_` variables); reading it still passes.
+
+### Fixed
+
+- **Studio keeps answering with many conversations open.** Each conversation pane held its own stream, and a
+  browser opens six connections to one host: at five panes a message sent and every request the page made waited
+  for a pane to close (on Windows a send did not arrive in 35 s; on macOS the page's own request timed out at 4 s).
+  Every open conversation now shares one stream, resumed from each session's last event when it reconnects.
+- **Studio finds sessions under a moved config dir.** It read `~/.claude/projects` only, so sessions under
+  `CLAUDE_CONFIG_DIR` were not listed and read a cost of 0. It now reads `projects` there, as Claude Code writes.
+- **Studio says when it needs a restart.** A running server keeps the code it started with, and an update
+  replaces the files the page is read from: on a real project the Map view of the new page asked a server from
+  before it and showed "Not read — HTTP 404". The server now says whether its code changed on disk since it
+  started; a page that hears so, or talks to a server too old to say, shows a note to restart it, and Map says the
+  same instead of the 404.
+- **Two agents starting together no longer share one model record on Windows.** A record was taken by renaming
+  it, which is a lock on macOS and Linux; on Windows two hook processes both reported the rename as done (seen
+  twice on the Windows CI). Each record is now locked first with an exclusive create, a shell builtin that costs no
+  process, and only the hook that made the lock takes it.
+- **An rc says it is one, and its final is offered.** A release candidate installed `.claude/VERSION` as the final's
+  number (3.2.0 for 3.2.0-rc.1), so the update check, doctor and the refresh's "what's new" all read it as the final,
+  and someone who tried the rc was never told the final shipped. The rc's archive and npm package now carry its own
+  version, and one definition (`eval/lib/version.sh`) orders an rc before its final. A version off the network is
+  still held to X.Y.Z.
+- **`adopt.sh --help` prints its usage.** It ran the project detection instead; the usage now comes in English and
+  Turkish, before anything is read.
+- **The crew map reads what two real projects showed it missing.** Scanned before release, they put three rules
+  well over a 20% false-positive rate, and one scan refused its own document. Read now: a route with an empty path,
+  a decorator whose path is on the next line, `api.get<T>(` and a call split over lines, a client made in one file
+  and called in another (it had read as a server), an import ending in a comment, twelve more import names, and a
+  string in a test that looks like an import. A call with a run-time host is matched but never reported missing. A
+  route a healthcheck or a Kubernetes probe calls has a caller, and a package that works without an import (a
+  server started from the command line, a database driver named in a URL, a pytest plugin) is not unused.
+  Source in a language the scanner has no reader for, and routes registered with a variable path, are listed in
+  `notMeasured` instead of being silently absent. On the Python project the proven `endpoint-missing` went from 2
+  real out of 10 to 4 out of 4.
+- **Studio's cards no longer flicker while a window is resized.** At Auto density, an edge dragged across the limit
+  between cards and chips redrew every card on every frame (measured: 57 times in 60 frames with 43 agents). The view
+  still follows the edge at once; the choice between cards and chips is made once the window has stopped for 150 ms.
+- **`crew-commit-agent` and `crew-session-manager` are called.** Both were exempt from the delegation cue and nothing
+  pulled them, so the main thread wrote every commit message and handover itself. The discipline and `/crew-handoff`
+  now call them, and smoke fails when a chain-step agent has no caller.
+- **Doctor names the 2.x plugin enabled beside a 3.x install.** The 2.x plugin, under its old name, wires the same
+  hooks; the check looked for `crewforth@…` only and said one edition while every hook ran twice.
+- **The crew map no longer reads a regex literal as an import.** `from '[^']*…` inside a regular expression was
+  reported as a proven undeclared dependency named `[^`; a specifier counts as a package only when it is named the way
+  npm names one.
+- **A cache write the usage split leaves out is counted.** Studio dropped cache writes that the top-level split of a
+  response did not account for; they are now the five-minute kind, which is how they were billed.
+- **Doctor's advisor lines match how Claude Code attaches it.** An advisor below the model it would advise is not
+  attached at all, so critical work runs without one; the warning said it would advise a stronger model.
+- **`incident-runbook` is picked for an outage that keeps coming back.** Its description named only a production that
+  is degraded or broken; a request about a recurring outage picked it in none of three held-out eval runs before, and
+  in two of three after.
+
 ## [3.1.1] — 2026-10-12
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 <p align="center"><img src="https://raw.githubusercontent.com/Crewforth/crewforth/main/assets/logo.svg" alt="Crewforth" width="420"></p>
 
-**Crewforth is your engineering crew for Claude Code.** It adds subagents, skills, commands and hooks to Claude Code: 12 specialist agents that each own a domain, 40 skills that hold the method, 12 commands you start with `/crew-…`, and hooks that enforce the rules that matter.
+**Crewforth is your engineering crew for Claude Code.** It adds subagents, skills, commands and hooks to Claude Code: 14 specialist agents that each own a domain, 40 skills that hold the method, 13 commands you start with `/crew-…`, and hooks that enforce the rules that matter.
 
 ```bash
 npx crewforth init              # set up a new project
@@ -13,6 +13,7 @@ Then open Claude Code and run `/crew-doctor` to confirm the setup. Requires bash
 
 [![npm](https://img.shields.io/npm/v/crewforth?style=flat-square&color=6D28D9)](https://www.npmjs.com/package/crewforth)
 [![License](https://img.shields.io/badge/license-MIT-5c6472?style=flat-square)](https://github.com/Crewforth/crewforth/blob/main/LICENSE)
+[![Star on GitHub](https://img.shields.io/badge/Star_on_GitHub-24292f?style=flat-square&logo=github)](https://github.com/Crewforth/crewforth)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Crewforth/crewforth/main/assets/flow-en-dark.svg">
@@ -28,9 +29,9 @@ Then open Claude Code and run `/crew-doctor` to confirm the setup. Requires bash
 
 ## What you get
 
-- **12 specialist agents**, from `crew-planner` to `crew-commit-agent`, each owning one domain.
+- **14 specialist agents**, from `crew-planner` to `crew-commit-agent`, each owning one domain.
 - **40 skills** holding the method: testing, migrations, API contracts, observability, accessibility, deployment.
-- **12 commands**, each started with its `/crew-…` name: `/crew-plan`, `/crew-review`, `/crew-ship`, `/crew-handoff`, `/crew-brainstorm`, `/crew-update`, `/crew-doctor`, `/crew-gates`, `/crew-skill`, `/crew-studio`, `/crew-approve`, `/crew-loosen`.
+- **13 commands**, each started with its `/crew-…` name: `/crew-plan`, `/crew-review`, `/crew-ship`, `/crew-handoff`, `/crew-brainstorm`, `/crew-update`, `/crew-doctor`, `/crew-gates`, `/crew-skill`, `/crew-studio`, `/crew-approve`, `/crew-loosen`, `/crew-map`.
 - In `auto` mode a commit or a push waits for you: type `/crew-approve` and what was just refused is approved, tied to what is staged.
 - **Safe adoption.** `adopt` lands everything on a branch, staged and uncommitted; `main` is never touched.
 

package/VERSION

@@ -1 +1 @@
-3.1.1
+3.2.0-rc.2

package/adopt.sh

@@ -11,7 +11,8 @@
 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/kit/eval/lib/crew-env.sh" ] && . "$_crew_d/kit/eval/lib/crew-env.sh"; unset _crew_d
+[ -f "$_crew_d/kit/eval/lib/crew-env.sh" ] && . "$_crew_d/kit/eval/lib/crew-env.sh"
+[ -f "$_crew_d/kit/eval/lib/version.sh" ] && . "$_crew_d/kit/eval/lib/version.sh"; unset _crew_d   # an rc orders before its final
 HERE="$(CDPATH= cd "$(dirname "$0")" && pwd)"
 
 # --version (or -v) is answered first, before the payload check below: it reads only VERSION, so it works
@@ -23,6 +24,44 @@ for _a in "$@"; do
   fi
 done
 
+# --help (or -h) is answered here too, before anything is read: an unknown flag is ignored further down, so without
+# this `adopt.sh --help` ran the detection instead of saying what the script does. The language comes from --lang or
+# CREW_LANG; the rest of the script asks for it later, which is too late for a help text.
+_hl="${CREW_LANG:-}"; _hh=0; _ht=0
+for _a in "$@"; do
+  if [ "$_ht" = 1 ]; then _ht=0; _hl="$_a"; continue; fi
+  case "$_a" in -h|--help) _hh=1 ;; --lang) _ht=1 ;; --lang=*) _hl="${_a#--lang=}" ;; esac
+done
+if [ "$_hh" = 1 ]; then
+  if [ "$_hl" = tr ]; then
+    cat <<'USAGE_TR'
+Kullanım: bash adopt.sh [SEÇENEKLER]   (ya da: npx crewforth adopt [SEÇENEKLER])
+Crewforth'u MEVCUT bir projeye kurar ya da kurulu olanı yeniler. Önce projeyi okur ve ne yapacağını gösterir;
+projenin kendi dosyalarına, hook'larına ve status line'ına dokunmaz. Değişiklikleri hazırlar (stage), commit atmaz.
+  --here         değişiklikleri şu anki dalda yap
+  --new-branch   değişiklikleri yeni bir inceleme dalında yap (ilk kurulumda varsayılan)
+  --yes, -y      her soruya evet de (gözetimsiz kurulum)
+  --lang tr|en   dil (verilmezse sorulur)
+  --version, -v  Crewforth sürümünü yazdırıp çık
+  --help, -h     bu metni yazdırıp çık
+USAGE_TR
+  else
+    cat <<'USAGE'
+Usage: bash adopt.sh [OPTIONS]   (or: npx crewforth adopt [OPTIONS])
+Installs Crewforth into an EXISTING project, or refreshes an install. It reads the project first and shows what it
+will do; the project's own files, hooks and status line are left alone. Changes are staged, never committed.
+  --here         make the changes on the current branch
+  --new-branch   make the changes on a fresh review branch (the default for a first adopt)
+  --yes, -y      answer yes at every gate (unattended)
+  --lang tr|en   language (asked when not given)
+  --version, -v  print Crewforth's version and exit
+  --help, -h     print this text and exit
+USAGE
+  fi
+  exit 0
+fi
+unset _hl _hh _ht
+
 SRC="$HERE/kit"
 [ -d "$SRC" ] || { echo "ERROR: kit/ not found (must be in the same directory as adopt.sh)."; exit 1; }
 
@@ -273,6 +312,8 @@ _mt() {   # $1 = English text (the key); further args fill %s; result in _M
       "custom hooks and every other permission PRESERVED") s="özel hook'lar ve diğer tüm izinler KORUNDU" ;;
       "custom hooks/permissions PRESERVED") s="özel hook'lar ve izinler KORUNDU" ;;
       "settings.json: was missing in the project -> Crewforth's was installed") s="settings.json: projede yoktu -> Crewforth'unki kuruldu" ;;
+      "Status line: Crewforth's (the gate's last word, a standing approval, crew agents, fill, cost).") s="Durum satırı: Crewforth'unki (kapının son sözü, geçerli onay, crew ajanları, doluluk, maliyet)." ;;
+      "Status line: yours is kept; Crewforth's is one command away (see /crew-doctor).") s="Durum satırı: seninki korundu; Crewforth'unki tek komutla açılır (/crew-doctor'a bak)." ;;
       "settings.json: hook-aware MERGE (Crewforth hooks refreshed - %s)") s="settings.json: hook'ları gözeten BİRLEŞTİRME (Crewforth hook'ları yenilendi - %s)" ;;
       "settings.json: %s") s='settings.json: %s' ;;
       "merge failed -> project setting PRESERVED (not overwritten)") s='birleştirme başarısız -> proje ayarı KORUNDU (üzerine yazılmadı)' ;;
@@ -1538,14 +1579,15 @@ fi
 # A fresh adopt has no "before", so it gets no file (and a stale one from an earlier update is removed).
 rm -f .claude/.state/whats-new.md 2>/dev/null
 _kv="$(printf '%s' "$KIT_VER" | tr -d '\r')"
-case "$_kv" in *[!0-9.]*|'') _kv="" ;; [0-9]*.[0-9]*.[0-9]*) ;; *) _kv="" ;; esac   # an odd old version compares as 0.0.0 — every section would look new
+_kv="$(crew_local_version "$_kv" 2>/dev/null)" || _kv=""   # an odd old version compares as 0.0.0 — every section would look new
 if [ "$KIT_PRESENT" = 1 ] && [ -n "$_kv" ] && [ -f "$HERE/CHANGELOG.md" ] && [ -f "$HERE/VERSION" ]; then
   mkdir -p .claude/.state 2>/dev/null
-  awk -v from="$_kv" -v to="$(head -1 "$HERE/VERSION" | tr -d '\r')" '
-    function cmp(a,b,  x,y,i){ split(a,x,"."); split(b,y,"."); for(i=1;i<=3;i++){ if(x[i]+0>y[i]+0) return 1; if(x[i]+0<y[i]+0) return -1 } return 0 }
+  # The upper bound is the target's X.Y.Z: an rc's notes are its final's section ("[Unreleased] — 3.2.0").
+  awk -v from="$_kv" -v to="$(head -1 "$HERE/VERSION" | tr -d '\r')" "${CREW_VCMP_AWK:-}"'
+    BEGIN { sub(/-.*/, "", to) }
     /^## \[/ { v=$0; sub(/^## \[/,"",v); w=v; sub(/\].*/,"",v)
                 if (v=="Unreleased") { v=w; sub(/^[^—]*— */,"",v); sub(/[^0-9.].*/,"",v) }
-                keep = (v ~ /^[0-9]+\.[0-9]+\.[0-9]+$/ && cmp(v,from)>0 && cmp(v,to)<=0) }
+                keep = (v ~ /^[0-9]+\.[0-9]+\.[0-9]+$/ && vcmp(v,from)>0 && vcmp(v,to)<=0) }
     keep' "$HERE/CHANGELOG.md" | tr -d '\r' > .claude/.state/whats-new.md 2>/dev/null
   [ -s .claude/.state/whats-new.md ] || rm -f .claude/.state/whats-new.md
 fi
@@ -1673,6 +1715,15 @@ if [ -n "$SET_NOTE" ]; then HAND_SET="NOT merged — ${SET_NOTE%.}"
 elif [ "$SET_FRESH" = 1 ]; then HAND_SET="Crewforth's settings.json installed (the project had none, so nothing was merged)"
 else HAND_SET="hook-aware merge (Crewforth hooks REFRESHED to current — new events + timeouts land; your own custom hooks/permissions PRESERVED${RET_GONE:+, except the retired §4.4 ask rule(s) REMOVED: $RET_GONE — guard-bash.sh asks for these itself})"; fi
 
+# The status line, only where none is set (a user's own would lose to the project's setting, so it is never
+# replaced). eval/lib/statusline.sh --install decides and writes; this only says what it did.
+if [ -f .claude/eval/lib/statusline.sh ]; then
+  case "$(bash .claude/eval/lib/statusline.sh --install 2>/dev/null)" in
+    installed) say "Status line: Crewforth's (the gate's last word, a standing approval, crew agents, fill, cost)." ;;
+    kept) say "Status line: yours is kept; Crewforth's is one command away (see /crew-doctor)." ;;
+  esac
+fi
+
 # ============ [STAGE 4] GIT-HOOK ARMING (SHIM) + PROOF ============
 h1m 'Stage 4 — arm the git gates (SHIM via husky) + PROOF'
 

package/kit/AGENT_TEMPLATE.md

@@ -49,7 +49,8 @@ verify: npm test -- orders
 `architecture` · `test-run` · `test-write` · `audit`. `verify` is the command that proves the work, or `none`.
 
 **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`; the
+on a critical path (auth, payments, billing, migrations, security, crypto, secrets, legal, privacy, consent, terms,
+`*.sql`, `schema.prisma`, store-listing text under `store/` or `fastlane/metadata/`; the
 project's own are listed in `.claude/state/crew-critical-paths.auto`, and `.claude/crew-model-rules` adds or removes).
 Otherwise `normal`.
 

package/kit/CLAUDE.md

@@ -34,12 +34,13 @@ recommend, with the rationale.**
 code — RISK decides, not size: behaviour changes and a subagent's diff review go to the owner.
 
 **Classify before the first tool call:** name the DOMAIN in your own words, then read its owner from
-`.claude/agents/`. Classify *intent*, never wording — the request arrives in any language.
+`.claude/agents/`. Classify *intent*, not wording, in any language.
 What the user sees → **crew-frontend-expert** · server behaviour → **crew-backend-expert** · stored data →
 **crew-database-expert** · run/deploy/CI → **crew-devops-expert** · **crew-security-expert** ·
-**crew-privacy-agent** (personal data) · **crew-test-expert** · **crew-performance-expert** · what to build →
+**crew-privacy-agent** (personal data) · **crew-test-expert** · **crew-performance-expert** · docs/legal/store
+text → **crew-docs-agent** · what to build →
 **crew-planner** · unknown cause → **general-purpose** + `systematic-debugging`. Two domains → delegate in
-sequence. Every agent above is installed; "no owner" is an `ls`, not a default.
+sequence. All are installed: "no owner" is an `ls`.
 
 1. **Diagnose, then plan** — unknown cause → `systematic-debugging` first; unclear scope → **crew-planner** (`/crew-plan`).
 2. **Produce** — the domain owner above.
@@ -49,21 +50,21 @@ sequence. Every agent above is installed; "no owner" is an `ls`, not a default.
    A finding or a red test goes back to the owner that wrote the code, and after the fix **all of them run
    again**: the diff they cleared no longer exists.
 4. **Close — only once 3 is clean.** DoD → **crew-review-agent** (LAST, never first) clean → **crew-commit-agent**
-   proposes, waits for approval (`/crew-ship`); held items close here.
-5. **Hand off** — phase boundary or full context → **crew-session-manager** → `handoff` → `/clear` (`/crew-handoff`).
+   writes the message, not you; waits for approval (`/crew-ship`); held items close here.
+5. **Hand off** — phase boundary or 🔋 ≥ medium → **crew-session-manager** → `handoff` → `/clear` (`/crew-handoff`).
 
 **Model per call — RISK decides, not size.** A `crew-*` task opens with its card, and the call names `model`:
 `files:` files/globs · `change:` text|feature|fix-known|fix-unknown|refactor|migration|security|architecture|test-run|test-write|audit
-· `verify:` the command that proves it, or `none`. **crew-planner** writes the card; with no plan, you do.
+· `verify:` the command that proves it, or `none`. **crew-planner** writes the card, or you do.
 
-| `model` | the card |
+| `model` (`guard-agent-model.sh`: floor = default; `above: <why>` for more) | the card |
 |---|---|
-| `haiku` | text, test-run, mechanical work — only with a `verify:` command |
+| `haiku` | text, test-run, mechanical work — only with `verify:` |
 | `sonnet` | feature, fix-known, refactor, test-write, audit, review; anything with `verify: none` |
-| `opus` | **critical**: migration, security, architecture, fix-unknown, or a file on a critical path (auth, payments, migrations…) — its test-write, audit and review too |
+| `opus` | **critical**: migration, security, architecture, fix-unknown, or a critical-path file (auth, payments, migrations…) — its test-write, audit, review too |
 
 The referee follows the RISK, not the author's model. Verify fails → the agent fixes once; again → re-run ONCE one
-model up; again → AskUserQuestion. The same for a report that ends `confidence: low`. `guard-agent-model.sh` holds it.
+model up; again → AskUserQuestion. The same for a report that ends `confidence: low`.
 
 **Naming an agent in prose is a hope; `@agent-<name>` is a guarantee** — measured here: 0/3 vs 3/3. Use that form
 whenever an agent must run, and tell the user they can too.
@@ -126,9 +127,9 @@ more tokens, because each one re-pays for its own context — plan for that.
 > **Honest boundary.** Measuring fill **is a gate** (`context-usage.sh` + `session-guard.sh`). The four bullets above
 > are **model discipline** — no exit code can judge a delegate-or-not call, so they rest on your reasoning.
 
-## Session management (crew-session-manager)
-Last line of a reply, after the next step: `🔋 Session: [low/medium/high fill] · Recommendation: [continue / handoff+clear / new session]`
-— **only when you have a reading**; with none there is nothing to report, so omit the line.
+## Session status line
+Last line of a reply, after the next step: `🔋 Session %NN → [low/medium/high] fill · Recommendation: [continue / handoff+clear / new session]`
+— **only with a reading** (%NN is its measured figure); with none, omit the line.
 
 **Never guess the fill.** You cannot run `/context`; the `UserPromptSubmit` hook injects the measured line
 `🔋 Session %NN.N → level` every turn (`input + cache_read + cache_creation` = the `/context` figure). Use it. Exact

package/kit/agents/crew-commit-agent.md

@@ -2,8 +2,8 @@
 name: crew-commit-agent
 color: cyan
 description: |
-  Commit message specialist (thin trigger). Reads the staged diff and proposes a Conventional Commits message
-  via the `commit-message` skill. Writes no source; commits only with user approval.
+  Use immediately after the DoD is clean, before any git commit: proposes the Conventional Commits message
+  from the staged diff (`commit-message`). Commits only with user approval.
 tools: Read, Grep, Glob, Bash, PowerShell
 model: haiku
 metadata:
@@ -102,6 +102,11 @@ write is refused because the file is on a critical path, do not reach it another
   `/crew-approve push` or `/crew-approve commit+push`. The user approves by sending
   that command alone; a sentence that says yes is not an approval, and you cannot run `/crew-approve` for them. It covers what is staged on that HEAD. If the gate says the approval path is closed in this session (the
   recording hook is not wired), say so and offer Shift+Tab or their own terminal instead.
+  In `auto` the refusal may also offer the approval question: show the message, then call AskUserQuestion with
+  exactly the input the refusal prints (the fixed question and its four answers, no answers of your own). The
+  user's click is recorded the same way; read the line Crewforth adds and run what it names. Where a
+  `PermissionRequest` hook may be wired the gate closes the question, and in `default` / `acceptEdits` its own
+  prompt too, because such a hook can answer either before the user does: then `/crew-approve` is the way.
   Then run `git commit -m '…'` alone in its call (single-quoted, or from a here-document with a quoted delimiter),
   and a push as `git push <remote> <branch>`. Never write that message yourself. Under `plan` and
   `bypassPermissions` the gate fails closed; there the user must switch modes or pre-authorise with

package/kit/agents/crew-docs-agent.md

@@ -0,0 +1,71 @@
+---
+name: crew-docs-agent
+color: yellow
+description: |
+  Use proactively for docs: README, guides, release notes, legal, privacy and store texts. Writes no code.
+tools: Read, Grep, Glob, Edit, Write
+metadata:
+  stage: produce
+  skills: [docs-writer, i18n-integrity]
+---
+
+# Docs Agent
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "readme", "user guide", "release notes", "changelog entry", "privacy policy", "terms of service", "terms of use", "cookie notice", "consent text", "legal text", "store listing", "app store description", "play store description", "documentation page"
+
+Writes the text; the `docs-writer` skill holds how. Code is someone else's: a sentence inside a component goes to its
+owner, a document beside it comes here.
+
+## Expertise stance (technical writer who has been sued once)
+- **Every claim is checkable.** A number, a flag, a behaviour is read from the code or the tool's own documentation
+  before it is written; what could not be checked is written as not checked, or left out.
+- **The reader acts on it.** Lead with what they do, then why; one idea per paragraph, no history in a guide.
+- **Legal and privacy text is not paraphrased into a promise.** It says what the product does, measured from the code
+  and the data flow, and nothing the product does not do. Anything that reads as a legal commitment the code does
+  not back goes to the user before it is written.
+- **Both languages or neither.** A text the project ships in two languages changes in both in the same change
+  (`i18n-integrity`).
+
+## When
+README, guides, docs pages, release notes and CHANGELOG, legal and privacy texts (`legal/`, `privacy*`, `terms*`,
+`consent*`), store listings (`fastlane/metadata/`, `store/`, `store-listing/`, `metadata/android|ios/`).
+
+## How (follow its skill)
+`docs-writer`: structure, what a README states and what it does not, the voice. `i18n-integrity` when the text has a
+translation. The model follows the RISK: legal, privacy and store texts are critical paths, so their card runs on
+the critical tier and the write itself is refused on a lower model.
+
+## Coordination (cross-agent)
+- A legal or privacy text is audited by **crew-privacy-agent** before it closes: what the text says against what the
+  code collects, keeps and shares.
+- A sentence about behaviour the code does not have goes to the owner of that code first, not into the text.
+
+## DoD
+Every checkable statement checked; translations in step; the audit above clean for a legal or privacy text.
+
+## Output & context (token)
+To the main thread: what changed, in which files, and every statement that could not be checked. Not the text itself.
+
+## Errors/escalation
+A claim the code contradicts, or a legal commitment nobody has decided: stop and report it, do not soften it into
+the text.
+
+## Example delegation
+- ✅ "update the privacy policy for the new retention period"
+- ❌ "add a consent checkbox to the signup form" (UI: crew-frontend-expert)
+
+## Confidence
+The LAST line of every report is exactly `confidence: high` or exactly `confidence: low`: lower case, nothing else
+on the line, nothing after it. `low` when you guessed, could not verify, or the task was above the model this run
+was given; the caller then repeats it once, one model up. Your task opens with a card (`files:`, `change:`,
+`verify:`): the `verify` command is run when you stop, and if it fails you are asked once to fix the work. If a
+write is refused because the file is on a critical path, do not reach it another way: stop, and put
+`escalate: <the file>` on the line before `confidence: low`.
+
+## Constraints
+- Writes text files only; no source, no configuration, no build files.
+- Does not invent a policy: what the product does is read from the code, what it should do is the user's decision.
+
+## Prohibitions (absolute)
+CLAUDE.md §4 applies: no AI trace, no third-party template name, nothing under `docs/` named in a shipped text.

package/kit/agents/crew-planner.md

@@ -33,6 +33,8 @@ before planning. You are read-only: when it ends at "ask", return its questions
 decision — the main thread asks and records the answer.
 
 ## How (applies the `spec-planning` skill)
+- On an unfamiliar project, read `.crewforth/crew-map.json` first when it exists (its modules, what they touch,
+  the gaps, each with the lines it rests on); with none, `/crew-map` writes one, and that is the user's call.
 - Define the problem in a single sentence; clarify what is in scope and out of scope.
 - Break tasks into atomic steps; derive the dependency order.
 - For each step, write acceptance criteria (how "done" is judged).

package/kit/agents/crew-refuter.md

@@ -0,0 +1,77 @@
+---
+name: crew-refuter
+color: gray
+description: |
+  Use proactively on each medium+ finding before it is reported: given one claim and its file:line, refutes it.
+tools: Read, Grep, Glob
+metadata:
+  stage: audit
+  skills: [security-scan]
+---
+
+# Refuter
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "refute this finding", "disprove this claim", "try to prove it wrong", "verify this finding independently", "is this finding a false positive"
+
+Read-only. A fresh context is the point: it has not seen the reasoning that produced the finding, so it cannot
+inherit its blind spot. The method is `security-scan` → `references/verify.md`.
+
+## When
+After discovery, before a finding is written to a report or a findings document. Every finding of `medium` or
+higher severity goes through it; `critical` and `high` through three calls, each on a different lens.
+
+## Expertise stance (the colleague whose job is to find the hole in your argument)
+- **Starts from the cited lines, never from the summary.** Reads the code at `cite:` first and only then the claim.
+- **Hunts for why the claim is false**: unreachable input, a guard on every path, a test or dead file, a control
+  the claim did not look for. Agreement is what is left when that search fails, not where it starts.
+- **One lens, held to it**: reachability, protection, reproduction, exclusion or blast-radius — the one it is given.
+- **Names the missing fact** instead of guessing: a verdict it cannot reach from the repository is CANNOT_VERIFY.
+
+## How (follow its skill)
+`security-scan` → `references/verify.md`: the verifier stance, the lens, the three verdicts and the exclusion
+rules. The task it is given is exactly this, and nothing of the caller's reasoning. It opens with the card every
+crew agent is called with (`change: audit`, so the model follows the risk of the cited file):
+
+```
+files:  <the cited file>
+change: audit
+verify: none
+finding: <the finding's id in the findings document>
+lens: reachability | protection | reproduction | exclusion | blast-radius
+cite: <file>:<line>
+claim: <one sentence>
+```
+
+## Output & context (token)
+Its last lines are read by `hooks/refuter-ledger.sh`, which records the verdict against the finding and lens of
+the task it was given, so they are exactly:
+
+```
+FINDING: <id>
+LENS: <lens>
+VERDICT: TRUE_POSITIVE | FALSE_POSITIVE | CANNOT_VERIFY
+REASON: <one or two sentences, citing file:line>
+```
+
+## Confidence
+The LAST line of every report is exactly `confidence: high` or exactly `confidence: low`: lower case, nothing else
+on the line, nothing after it. `low` when you guessed or could not read what the claim needs; the caller then
+repeats the call once, one model up. Your task opens with a card (`files:`, `change: audit`, `verify: none`), so
+nothing is run when you stop. The `FINDING`, `LENS`, `VERDICT` and `REASON` lines come before it.
+
+## Errors/escalation
+A task without `finding:`, `lens:` and `cite:` is answered with `VERDICT: CANNOT_VERIFY` and the reason, never
+with a guess; the ledger records nothing for it.
+
+## Example delegation
+- ✅ "finding: sec-idor-orders · lens: protection · cite: src/orders.ts:88 · claim: any user can read any order"
+- ❌ "audit the orders module for security issues" (discovery: crew-security-expert)
+
+## Constraints
+- Read-only: no Edit, no Write, no Bash, and no `Agent`, so it cannot hand the question to a context that has
+  seen more than it should.
+- One claim per call. The caller runs the calls of one finding in parallel, never in one context.
+- HONEST SCOPE: what keeps the record true is the hook writing the ledger from this agent's own task and answer;
+  what keeps the answer independent is that the caller gave it the claim and not the reasoning, which is model
+  discipline.

package/kit/agents/crew-security-expert.md

@@ -27,7 +27,7 @@ Read-only auditor. The relevant expert (backend/database) makes the fix; this ag
 - **Prove** each finding: how it's exploited + impact + fix; not a theoretical warning.
 - Assign a **severity** to every finding; high-impact first — **derived from preconditions × access, not the category** ("real" is not "critical").
 - **Defense in depth**: don't rely on a single control; add layers.
-- **Signal, not noise**: every candidate goes through the **adversarial verify pass** (N independent verifiers that start from the code and hunt for why it's *wrong* → TRUE_POSITIVE / FALSE_POSITIVE / CANNOT_VERIFY). See `security-scan` → `references/verify.md`.
+- **Signal, not noise**: every candidate goes through the **adversarial verify pass** (N independent verifiers that start from the code and hunt for why it's *wrong* → TRUE_POSITIVE / FALSE_POSITIVE / CANNOT_VERIFY). See `security-scan` → `references/verify.md`. This agent has no `Agent` tool: it returns the candidates, and the session runs one **crew-refuter** per finding and lens.
 
 ## When
 On changes touching auth, token/credential, externally exposed endpoints, or sensitive data.
@@ -52,6 +52,8 @@ Each finding: `file:line · risk · suggested fix`, or a "clean on this axis" ra
 
 ## Output & context (token)
 To the main thread: a **severity-ranked findings summary** (area · severity · fix). Full scan output → `docs/SECURITY_FINDINGS.md`, returns a summary + count.
+The candidates also go out as a findings document (`kit/eval/lib/findings`, one `id` and `file:line` evidence each) for the session to verify; the
+verified one is stored with `findings.sh write --verified security <file>` (`eval/lib/findings/` in either edition), which refuses a `medium`-or-higher finding without its refuters.
 
 ## Errors/escalation
 On an exploitable CRITICAL finding, **warn clearly**; don't report a finding you're unsure of as 'certain', add a verifiability note.