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

package/CHANGELOG.md

@@ -9,6 +9,81 @@ versioning follows [SemVer](https://semver.org/).
 
 ### Added
 
+- **Watch Studio from a phone on the same Wi-Fi.** A viewer is a second token that only reads: the Machines tab makes
+  one, lists each with its last request, and revokes it. **Add viewer** shows its link as a QR code; a phone on
+  the same network scans it and the panel opens there, with no ssh and no tunnel. While a viewer is live the server
+  also listens on the machine's private Wi-Fi address, for viewer tokens only (the panel's own token gets `401` from
+  the network); with none, nothing listens beyond `127.0.0.1`. A viewer lasts eight hours, then the phone shows
+  Session expired; revoking it closes its stream at once, and the last one closes the Wi-Fi listener. Transcripts
+  are hidden by default: the server sends such a link no transcript text at all (an allow-list of fields, applied to
+  every answer and to the event stream), and shows them only for a link added with them ticked. Every viewer
+  connection and refusal is logged. Measured with an Android phone; the firewall asks once (macOS: allow `node`;
+  Windows: Private networks).
+
+- **The advisor, measured.** `review-bench --advisor <model>` runs the agent arm with an advisor and reports each
+  run's cost by model and its advisor calls; a case of `kind: "task"` is an implementation graded by a check the
+  session never saw. Against Opus alone on five review cases and a task (24 runs), Sonnet with an Opus advisor
+  never called it: 6 of 6 defects caught against 5 of 6, for $1.06 against $2.23. No rule is added; the runs and
+  their numbers are in `packaging/advisor-bench/`.
+
+- **An organisation preset.** `--preset <name|file>` on the installers (and `preset.sh --apply` later) writes an
+  organisation's critical paths, model floors, verify commands and language as one marked block at the top of
+  `.claude/crew-model-rules`; the project's own lines stay below it and win where the rules let them. Three ship:
+  `default`, `strict`, `solo`. An invalid preset is refused before anything is installed; `doctor` names the one
+  in force. It covers the surfaces the gates read today; which agents a project gets is not part of it.
+
+- **Continue here says what it will do before it is pressed.** Studio continues a session it did not start as
+  that same session when nothing else holds it open, and starts a copy when something does; the read-only foot now
+  says which it will be before the press, from the check it acts on, and offers the command that opens the session
+  in the desktop app again (`claude --desktop --resume <id>`) to copy. Measured with a real session: its id stayed
+  the same from a terminal, through Studio, and back to a terminal, in one transcript.
+  On Windows the desktop command is a PowerShell line, and the terminal Studio opens runs `claude --resume <id>`
+  without single quotes, which cmd.exe handed to the program as part of the id. An id that is not a session id
+  builds no command at all.
+  The terminal Studio opens runs `claude --resume <id>` and nothing else: the route no longer takes a `command`
+  from the request, which it ran unchecked and the panel never sent.
+
+- **A stopped command says what it would have touched.** When the shell gate stops `git reset --hard`,
+  `git clean -f`, `git push --force` or `rm -r`, or asks about a commit or a push, one line says what it would
+  have done: the uncommitted changes and commits it discards, the paths a dry run lists, the remote commits it
+  overwrites, the files under a target inside the project, what a commit takes and a push sends. Read only, after
+  the decision and in a subshell of its own, so a failing preview never changes the decision. The push question
+  became cheaper too: the branch is read from HEAD without a process.
+
+- **What a compaction keeps is written down first.** A PreCompact hook writes the state of the work from the files
+  and the gates (branch, uncommitted files, the last gate refusal, the findings on record, a handover if there is
+  one) inside the repository's git directory, and SessionStart gives it back after the compaction, to the same
+  session only. It never blocks the compaction. Studio's session card adds how much of the context since the last
+  compaction is tool output, and how many times the session was compacted.
+
+- **The Map reads like a project, not a graph.** Studio's Map draws modules in the layers `/crew-map` wrote (UI,
+  API, Service, Data, Infrastructure, Library, Tools), each card naming the module in full with its domain, up to
+  three of what it is built with and the outside services it calls folded into one line under it. A search dims
+  what it does not name; the tour `/crew-map` wrote steps through the map over the bottom of the pane; the
+  inspector shows the layer, the domain and what is inside a module (its entry point, its folders and their file
+  counts). A map with no layers is drawn in the bands the scan gives, as before.
+
+- **The Crew Map says where each module sits, and how to read the project.** `/crew-map` now has the model add,
+  to each module, its layer (`ui`, `api`, `service`, `data`, `infra`, `tool`, `library`) and the part of the
+  business it serves, and to the map a tour of up to eight stops a newcomer reads in order. Each rests on lines
+  the scan read; `--validate` refuses a layer not on the list, a domain written as a sentence, a tour stop at no
+  node, citing another node's lines or visiting a node twice, and a scan again drops what no longer holds.
+  A module's README is read too: its first line of prose is a line a description may rest on (measured on a real
+  project, four of ten modules had nothing else to describe them by).
+
+- **How right the review is, in numbers.** `eval/review-bench.sh` runs the review on labelled cases and reports
+  recall, precision and every false alarm by name; the pre-pass arm costs nothing, the agent arm runs Claude Code
+  headless as the review agent under a per-case and a per-run dollar cap, isolated from the user's own settings.
+  Crewforth's 27 cases come from its own history (a fix undone, its explanation left out) and 8 are held out; the
+  pre-pass's floor on them is a CI gate. Measured with Sonnet: 18 of 20 defects found, 34 of 49 findings about the defect, $1.62.
+
+- **The review starts from a deterministic pre-pass.** `eval/lib/review-prepass/prepass.sh` reads the lines a
+  change adds (staged, or `--base <ref>` for a branch) and writes `.crewforth/review-prepass.json` in the findings
+  shape: a secret pattern (cited by hash), a debug call or a TODO comment left in code, shellcheck on shell files, a lock
+  file that moved without its manifest, a very large change. The review agent carries those over and writes its
+  own findings to `.crewforth/review.json`, blockers through the refuter. What it could not check (no shellcheck,
+  a file edited after staging, no Node) is said, never read as clean.
+
 - **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
@@ -60,9 +135,6 @@ versioning follows [SemVer](https://semver.org/).
 - **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
@@ -79,6 +151,17 @@ versioning follows [SemVer](https://semver.org/).
 
 ### 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
@@ -114,6 +197,53 @@ versioning follows [SemVer](https://semver.org/).
 
 ### Fixed
 
+- **The Crew Map says what a project is made of.** A Flutter project read as a pile of Gradle modules and its
+  server as an external API (seen on a real project). The scanner now reads Dart: one module per `pubspec.yaml`,
+  its packages and `path:` references, and a Flutter app's `android/` and `ios/` folders as platforms of the app.
+  Each module says what it is built with (Hono, Cloudflare Workers, Flutter, Riverpod…, from `rules/tech.json`)
+  and what is inside it (folders with file counts, tests apart). A module served at a host its wrangler routes or
+  `fly.toml` name is called, module to module, by any module that writes that host; a Dart call to that host or a
+  Dio call's relative path is matched to the endpoints provided. A `.dart` file no `pubspec.yaml` owns is listed
+  as not measured, as is Dart package usage: Flutter declares packages nothing imports.
+
+- **A commit message and a reworded paragraph no longer go to the expensive model.** Two floors of the model gate
+  raised prose for no gain (seen on a real project): with no verify command a commit message was held to sonnet,
+  though the commit hook checks it, and a two-sentence fix under a critical path such as `legal/` was held to opus.
+  A text change now runs on haiku without a verify command, the commit agent too; on a critical path a text change
+  whose every file is prose (`.md`, `.txt`, `.rst`, `.adoc`) is written on sonnet, and the audit of it stays on opus.
+  One code file on the card keeps it on opus, and an agent on sonnet still writes no code there. A project that
+  wants opus for such text says so in `.claude/crew-model-rules` (`floor * text critical opus`).
+- **The gate log is written in every project, and Studio shows a refused agent call.** A project that tracks
+  `.claude/` had no gate log at all: no record of a refusal, no 🛡 on the status line, no note of a model lowered to
+  its card's floor (seen on a real project). The log now goes inside the repository's own `.git` there
+  (`crewforth-gate-log.tsv`, never committed); one rule (`eval/lib/gate-log.sh`) serves every gate and reader. A
+  call the model gate refused starts no agent, so the canvas showed nothing while the session said "2 failed"; the
+  session's card now says how many calls were refused and not made again, with the gate's words on hover.
+- **`/crew-doctor` offers a verify rule that works, in every mode.** For `cd sub && ./check.sh` it offered the line
+  with the `cd` in it, which allows nothing (the rule names the command alone), and in default mode it offered
+  nothing, because that refusal is worded differently. Measured on Windows.
+- **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

package/README.md

@@ -33,6 +33,8 @@ Then open Claude Code and run `/crew-doctor` to confirm the setup. Requires bash
 - **40 skills** holding the method: testing, migrations, API contracts, observability, accessibility, deployment.
 - **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.
+- A stopped destructive command says what it would have touched; a review starts from a deterministic pre-pass, and `crew-refuter` tries to refute each finding that blocks.
+- **Organisation presets.** `npx crewforth init --preset strict` (or `solo`, or your own JSON file) carries critical paths, model floors and verify commands to every project.
 - **Safe adoption.** `adopt` lands everything on a branch, staged and uncommitted; `main` is never touched.
 
 ## Updating

package/VERSION

@@ -1 +1 @@
-3.2.0
+3.2.0-rc.3

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,24 +24,68 @@ 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; }
 
 # --- flags (B5 — where a refresh lands) ---  --here: the current branch · --new-branch: a fresh review branch.
 # Left empty, Stage 2 picks a smart default (first adopt -> new; update + untracked .claude -> here; update +
 # tracked -> ask). Unknown flags are ignored here (start.sh owns --backend/--frontend/… ; adopt auto-detects shape).
-BRANCH_MODE=""; ASSUME_YES=0
+BRANCH_MODE=""; ASSUME_YES=0; PRESET=""; _preset_take=0
 _lang_flag=""; _lang_take=0
 for _a in "$@"; do
   # `--lang` with no value must not swallow the next flag: `--lang --yes` is --yes with no language given.
   if [ "$_lang_take" = 1 ]; then _lang_take=0; case "$_a" in -*) ;; *) _lang_flag="$_a"; continue ;; esac; fi
+  if [ "$_preset_take" = 1 ]; then _preset_take=0; PRESET="$_a"; continue; fi
   case "$_a" in
+  --preset=*)   PRESET="${_a#--preset=}" ;;
+  --preset)     _preset_take=1 ;;
   --here)       BRANCH_MODE=here ;;
   --new-branch) BRANCH_MODE=new  ;;
   --yes|-y)     ASSUME_YES=1     ;;   # assume "yes" at every gate — for agent-driven / CI updates (no TTY to prompt)
   --lang=*)     _lang_flag="${_a#--lang=}" ;;
   --lang)       _lang_take=1 ;;
 esac; done
+[ "$_preset_take" = 1 ] && { echo "ERROR: --preset needs a name or a file (default, strict, solo, or ./org.json)."; exit 1; }
+# A preset is checked before anything is changed: one that is not valid stops the update here.
+if [ -n "$PRESET" ]; then bash "$SRC/eval/lib/preset.sh" --check "$PRESET" || exit 1; fi
 
 # ---- CREW-I18N (the twin of start.sh's; see the long note there for why the English string is the key) ----
 # Short version, because the reasoning belongs in one place: `m 'text'` prints the translation of that text
@@ -1535,19 +1580,23 @@ fi
   # set up in Turkish to English from its first unattended update on.
   [ "$_LANG_CHOSEN" = 1 ] && echo "lang=$CREW_LANG"
 } > .claude/kit.conf
+# The organisation's preset (checked before anything was changed): a block at the top of crew-model-rules. Without
+# --preset an update leaves the block that is there, with the project's own lines, as they were.
+if [ -n "$PRESET" ]; then bash .claude/eval/lib/preset.sh --apply "$PRESET" || exit 1; fi
 # What changed, for /crew-update to report: the package's own CHANGELOG sections newer than the version this
 # project had, and no newer than the one being installed — read from the package on disk, never from the network.
 # 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

package/bin/cli.js

@@ -18,12 +18,13 @@ if (sub === '--help' || sub === '-h' || sub === 'help') {
   console.log(`Crewforth
 
 Usage:
-  npx crewforth [init] [--private|--shared] [--yes]
+  npx crewforth [init] [--private|--shared] [--yes] [--preset <name|file.json>]
       Set up Crewforth in a fresh project (start.sh wizard). Every install ships everything and
       is stack-agnostic: the stack is recorded per project in CLAUDE.md ## Stack.
       (--dotnet was removed in 3.0; it is still accepted, warns, and installs the same setup.)
-  npx crewforth adopt
+  npx crewforth adopt [--preset <name|file.json>]
       Hand Crewforth over onto an existing project (adopt.sh).
+      --preset applies an organisation preset (default, strict, solo, or your own JSON file).
   npx crewforth@latest update
       Refresh a project that already has Crewforth. Alias of 'adopt': it reads .claude/kit.conf,
       migrates a pre-3.0 .NET install (its pattern skill stays, as a project skill), and

package/kit/CLAUDE.md

@@ -55,16 +55,16 @@ sequence. All are installed: "no owner" is an `ls`.
 
 **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 |
-| `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 |
+| `haiku` | text, commit agent; test-run, mechanical work with `verify:` |
+| `sonnet` | feature, fix-known, refactor, test-write, audit, review; other `verify: none`; critical-path prose |
+| `opus` | **critical**: migration, security, architecture, fix-unknown, or a critical-path file (auth, payments, legal…), and its referees |
 
 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.

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

@@ -30,6 +30,8 @@ Read-only; the trigger for the `crew-code-review` skill.
 Before a work package closes (pre-commit), on the changed diff.
 
 ## How (applies the `crew-code-review` skill)
+- First the deterministic pre-pass (`eval/lib/review-prepass/prepass.sh`), carried over as it is; your own findings
+  go to `.crewforth/review.json` in the same findings shape, blockers through crew-refuter (skill §0).
 - Simplicity: flag when 200 lines could be 50.
 - Surgical: catch out-of-scope touches.
 - Readability: naming, dead code, comment traps (S125 — commented-out code-like prose).

package/kit/eval/doctor.sh

@@ -7,7 +7,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/lib/crew-env.sh" ] && . "$_crew_d/lib/crew-env.sh"; unset _crew_d
+[ -f "$_crew_d/lib/crew-env.sh" ] && . "$_crew_d/lib/crew-env.sh"
+[ -f "$_crew_d/lib/version.sh" ] && . "$_crew_d/lib/version.sh"   # an rc orders before its final
+_DOC_LIB="$(cd "$_crew_d/lib" 2>/dev/null && pwd)"; unset _crew_d          # absolute: the doctor cd's into ROOT below
 ROOT="${1:-.}"
 cd "$ROOT" 2>/dev/null || { echo "doctor: cannot enter '$ROOT'"; exit 2; }
 
@@ -106,6 +108,8 @@ _mt() {
       'advisor: off (CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1)') s='advisor: kapalı (CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1)' ;;
       "status line: Crewforth's (from %s)") s="durum satırı: Crewforth'unki (%s içinden)" ;;
       "status line: your own (from %s); Crewforth's is not used") s="durum satırı: seninki (%s içinden); Crewforth'unki kullanılmıyor" ;;
+      "organisation preset: %s") s="kurum preset'i: %s" ;;
+      "verify commands never run, %s time(s), because nothing allows them; to let the hook run one, add its line to .claude/crew-model-rules: %s") s="doğrulama komutları %s kez hiç koşmadı, çünkü hiçbir şey izin vermiyor; hook'un koşturması için satırını .claude/crew-model-rules dosyasına ekle: %s" ;;
       "status line: none; Crewforth's: bash .claude/eval/lib/statusline.sh --install (Bash tool, not PowerShell)") s="durum satırı: yok; Crewforth'unki: bash .claude/eval/lib/statusline.sh --install (Bash tool, not PowerShell)" ;;
       "advisor: off (no advisorModel set; Crewforth never turns it on)") s='advisor: kapalı (advisorModel ayarlı değil; Crewforth onu hiç açmaz)' ;;
       'advisorModel is %s in %s, but CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 turns the advisor off') s="advisorModel %s (%s içinde), ama CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 advisor'ı kapatıyor" ;;
@@ -218,8 +222,7 @@ if [ -f .claude/VERSION ] && [ -f .claude/.state/update-check ]; then
   read -r DLATEST _ < .claude/.state/update-check 2>/dev/null || DLATEST=""
   DLATEST="$(printf '%s' "${DLATEST:-}" | tr -cd '0-9A-Za-z.-')"
   DCUR="$(head -1 .claude/VERSION 2>/dev/null | tr -cd '0-9A-Za-z.-')"
-  if [ -n "$DLATEST" ] && awk -v a="$DLATEST" -v b="$DCUR" '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}'; then
+  if [ -n "$DLATEST" ] && awk -v a="$DLATEST" -v b="$DCUR" "${CREW_VCMP_AWK:-}"' BEGIN { exit !(vcmp(a, b) > 0) }' 2>/dev/null; then
     warn "Crewforth v%s installed, v%s published — update with /crew-update" "$DCUR" "$DLATEST"
   fi
 elif [ -f .claude/VERSION ]; then
@@ -772,6 +775,37 @@ case "$_sl" in
   *) [ -f .claude/eval/lib/statusline.sh ] && ok "status line: none; Crewforth's: bash .claude/eval/lib/statusline.sh --install (Bash tool, not PowerShell)" ;;
 esac
 
+# 9e) What model routing costs. Advisory. A verify command the hook was never allowed to run cannot vouch for
+#     cheaper work: the ones refused for that reason are listed with the line that allows them (measured on one
+#     project: 23 of 71 refusals).
+[ -f .claude/eval/lib/verify-cmd.sh ] && . .claude/eval/lib/verify-cmd.sh   # the rule names the command a cd prefix leads to
+_vbn=0; _vbl=""
+for _f in .claude/state/crew-model/results/*; do
+  [ -f "$_f" ] || continue
+  _vb=0; _vw=""; _vc=""
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    case "$_l" in verify=blocked) _vb=1 ;; whynot=*) _vw="${_l#whynot=}" ;; cmd=*) _vc="${_l#cmd=}" ;; esac
+  done < "$_f"
+  [ "$_vb" = 1 ] || continue
+  # Both ways of saying "nothing allows it": in auto/bypassPermissions (not on the runner list) and in the other
+  # modes (Claude Code itself would not run it unallowed). Measured on Windows: the second was not listed at all.
+  case "$_vw" in *"not a test or build command on this hook's list"*|*"does not run a command the user has not allowed"*) ;; *) continue ;; esac
+  # A rule names the command alone: `cd sub && ./check.sh` is allowed by `verify ./check.sh` (measured on Windows:
+  # the line with the cd in it did not allow it).
+  declare -F crew_verify_split >/dev/null && { crew_verify_split "$_vc" .; _vc="$_AMVC"; }
+  _vc="${_vc:0:80}"; [ -n "$_vc" ] || continue
+  _vbn=$((_vbn+1))
+  case "$_vc" in *'('*|*' + '*) continue ;; esac     # a sentence, not a command: counted, not offered as a rule
+  case "$_vbl" in *"| verify $_vc |"*) ;; *) _vbl="$_vbl| verify $_vc |" ;; esac
+done
+if [ "$_vbn" -gt 0 ]; then
+  _vsep=' || '; _vdot=' · '; _vbs="${_vbl//"$_vsep"/$_vdot}"; _vbs="${_vbs#| }"; _vbs="${_vbs% |}"; _vbs="${_vbs:0:300}"
+  warn "verify commands never run, %s time(s), because nothing allows them; to let the hook run one, add its line to .claude/crew-model-rules: %s" "$_vbn" "$_vbs"
+fi
+# The organisation preset in force: the block preset.sh wrote at the top of crew-model-rules, asked of preset.sh itself.
+_pre=""; [ -n "$_DOC_LIB" ] && [ -f "$_DOC_LIB/preset.sh" ] && _pre="$(bash "$_DOC_LIB/preset.sh" --show 2>/dev/null)"
+ok "organisation preset: %s" "${_pre:-none}"
+
 # 10) Gate activity. The suite proves the gates CAN fire; this reports whether anything actually tripped them.
 #     Recording is on by default (rule names only, never the command), so "no log" here means no gate has
 #     fired yet — a measured zero, not a gap. Never a failure either way.

package/kit/eval/gate-report.sh

@@ -29,6 +29,8 @@ HOOKS="./.claude/hooks"; [ -d "$HOOKS" ] || HOOKS="./hooks"
 [ -f "$HOOKS/guard-bash.sh" ] || { echo "gate-report: guard-bash.sh not found (run from the project root)" >&2; exit 4; }
 
 # Default log location, so `--log` is not required once logging is on.
+# The same rule the gates write by (eval/lib/gate-log.sh): .claude/gate-log.tsv, or the repository's .git.
+if [ -z "$LOG" ] && [ -f ./.claude/eval/lib/gate-log.sh ]; then . ./.claude/eval/lib/gate-log.sh; crew_gate_log_read; LOG="$_CREW_GL"; fi
 [ -z "$LOG" ] && [ -f "./.claude/gate-log.tsv" ] && LOG="./.claude/gate-log.tsv"
 
 TMP="${TMPDIR:-/tmp}/crew-gate-$$"; mkdir -p "$TMP"; trap 'rm -rf "$TMP"' EXIT

package/kit/eval/lib/crew-map/narrative.mjs

@@ -5,18 +5,27 @@
 // model fill them, and nothing else:
 //   node.narrative  { text, cites }  what the module is for, in at most two sentences; `cites` are "file:line"
 //                   strings, each one a line the scanner itself cited for THAT node (its evidence)
+//                   and, optionally, `layer` (one of LAYERS: where the module sits) and `domain` (what part of the
+//                   business it serves, a short phrase), both resting on the same cites
 //   doc.overview    { text, cites }  a short orientation for someone new to the project; its cites may be any
 //                   node's evidence
+//   doc.tour        [{ node, text, cites }]  one to eight stops a newcomer reads in order: each names a node of the
+//                   map, says in at most two sentences why to look there, and cites that node's own lines
 // A narrative with no citation, or one citing a line the scan did not read, is refused: the model may describe
 // what the scan found, not add to it. A scanner field changed by hand is refused too (validate).
 
 const MAX_NODE = 400;
 const MAX_OVERVIEW = 2000;
+const MAX_STOP = 300;
+const MAX_STOPS = 8;
+const MAX_DOMAIN = 60;
+export const LAYERS = ['ui', 'api', 'service', 'data', 'infra', 'tool', 'library'];
 
-/** The "file:line" a node's evidence lets a narrative cite. */
+/** The "file:line" a narrative of this node may cite. */
 export function citesOf(node) {
   const out = new Set();
-  for (const e of Array.isArray(node?.evidence) ? node.evidence : []) {
+  // Its evidence, its entry point and what its README says about it: every line the scan read for this node.
+  for (const e of [node?.evidence, node?.entryPoint?.evidence, node?.about?.evidence].flatMap((x) => (Array.isArray(x) ? x : []))) {
     if (e && typeof e.file === 'string' && Number.isInteger(e.line)) out.add(`${e.file}:${e.line}`);
   }
   return out;
@@ -35,11 +44,14 @@ const sentences = (t) => (String(t).trim().match(/[.!?](\s|$)/g) ?? []).length;
  * Why a narrative is not acceptable, or null when it is (null itself is: not written yet).
  * @param allowed  the set of "file:line" it may cite
  */
-export function problemOf(n, allowed, { max = MAX_NODE, twoSentences = true } = {}) {
+export function problemOf(n, allowed, { max = MAX_NODE, twoSentences = true, module = false } = {}) {
   if (n === null || n === undefined) return null;
   if (typeof n !== 'object' || Array.isArray(n)) return 'is not { text, cites }';
-  const keys = Object.keys(n).sort().join();
-  if (keys !== 'cites,text') return `has fields other than text and cites (${keys})`;
+  const may = module ? ['cites', 'domain', 'layer', 'text'] : ['cites', 'text'];
+  const odd = Object.keys(n).filter((k) => !may.includes(k));
+  if (odd.length || !('text' in n) || !('cites' in n)) return `has fields other than ${may.join(', ')} (${Object.keys(n).sort().join()})`;
+  if ('layer' in n && !LAYERS.includes(n.layer)) return `names the layer ${JSON.stringify(n.layer)}, not one of ${LAYERS.join(', ')}`;
+  if ('domain' in n && (typeof n.domain !== 'string' || !n.domain.trim() || n.domain.length > MAX_DOMAIN || /[.!?]/.test(n.domain))) return `has a domain that is not a short phrase (at most ${MAX_DOMAIN} characters, no sentence)`;
   if (typeof n.text !== 'string' || !n.text.trim()) return 'has no text';
   if (n.text.length > max) return `is ${n.text.length} characters, more than ${max}`;
   if (twoSentences && sentences(n.text) > 2) return 'is more than two sentences';
@@ -52,7 +64,24 @@ export function problemOf(n, allowed, { max = MAX_NODE, twoSentences = true } =
 /** The document without what the model may add: the scanner's fields alone. */
 export function strip(doc) {
   if (!doc || typeof doc !== 'object') return doc;
-  return { ...doc, nodes: (doc.nodes ?? []).map((n) => ({ ...n, narrative: null })), overview: null };
+  return { ...doc, nodes: (doc.nodes ?? []).map((n) => ({ ...n, narrative: null })), overview: null, tour: null };
+}
+
+/** Why a tour is not acceptable, or null when it is (null itself is: not written yet). */
+export function tourProblem(tour, doc) {
+  if (tour === null || tour === undefined) return null;
+  if (!Array.isArray(tour) || !tour.length || tour.length > MAX_STOPS) return `is not a list of 1 to ${MAX_STOPS} stops`;
+  const byId = new Map((doc?.nodes ?? []).map((n) => [n.id, n]));
+  const seen = new Set();
+  for (const [i, s] of tour.entries()) {
+    if (!s || typeof s !== 'object' || Array.isArray(s) || Object.keys(s).sort().join() !== 'cites,node,text') return `stop ${i + 1} is not { node, text, cites }`;
+    if (!byId.has(s.node)) return `stop ${i + 1} names ${JSON.stringify(s.node)}, which is not a node of this map`;
+    if (seen.has(s.node)) return `stop ${i + 1} names ${s.node} again: a tour stops at a node once`;
+    seen.add(s.node);
+    const p = problemOf({ text: s.text, cites: s.cites }, citesOf(byId.get(s.node)), { max: MAX_STOP });
+    if (p) return `stop ${i + 1} (${s.node}) ${p}`;
+  }
+  return null;
 }
 
 /**
@@ -65,7 +94,7 @@ export function carry(old, fresh) {
   const nodes = fresh.nodes.map((n) => {
     const nar = was.get(n.id);
     if (nar === null || nar === undefined) return n;
-    if (problemOf(nar, citesOf(n)) === null) { kept += 1; return { ...n, narrative: nar }; }
+    if (problemOf(nar, citesOf(n), { module: n.kind === 'module' }) === null) { kept += 1; return { ...n, narrative: nar }; }
     dropped += 1; return n;
   });
   const doc = { ...fresh, nodes };
@@ -73,6 +102,9 @@ export function carry(old, fresh) {
     if (problemOf(old.overview, allCites(doc), { max: MAX_OVERVIEW, twoSentences: false }) === null) { doc.overview = old.overview; kept += 1; }
     else dropped += 1;
   }
+  if (old?.tour != null) {
+    if (tourProblem(old.tour, doc) === null) { doc.tour = old.tour; kept += 1; } else dropped += 1;
+  }
   return { doc, kept, dropped };
 }
 
@@ -89,10 +121,12 @@ export function validate(file, fresh, serialize) {
   }
   const byId = new Map((fresh.nodes ?? []).map((n) => [n.id, n]));
   for (const n of file.nodes ?? []) {
-    const p = problemOf(n.narrative, citesOf(byId.get(n.id) ?? n));
+    const p = problemOf(n.narrative, citesOf(byId.get(n.id) ?? n), { module: (byId.get(n.id) ?? n).kind === 'module' });
     if (p) out.push({ at: n.id, message: `the narrative ${p}` });
   }
   const p = problemOf(file.overview, allCites(fresh), { max: MAX_OVERVIEW, twoSentences: false });
   if (p) out.push({ at: 'overview', message: `the overview ${p}` });
+  const t = tourProblem(file.tour, fresh);
+  if (t) out.push({ at: 'tour', message: `the tour ${t}` });
   return out;
 }

package/kit/eval/lib/crew-map/project.mjs

@@ -130,14 +130,15 @@ export function risky(text, patterns) {
 // A host is the only part of a connection string or URL the map keeps. Credentials are cut off first; then a host
 // that looks like a secret by Crewforth's own scanner patterns is replaced. Without those patterns every host is
 // replaced: a map with fewer names is a smaller loss than one that published a token.
-export function loadSecretPatterns(fromDir) {
+// skip: pattern lines left out, as written (a project's .secret-allowlist.txt names the exact line it allows).
+export function loadSecretPatterns(fromDir, skip = new Set()) {
   for (const rel of ['../../../hooks/secret-blocklist.txt', '../../../../hooks/secret-blocklist.txt']) {
     const f = path.join(fromDir, rel);
     let text; try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
     const out = [];
     for (const raw of text.split('\n')) {
       const l = raw.replace(/\r$/, '');
-      if (!l || l.startsWith('#')) continue;
+      if (!l || l.startsWith('#') || skip.has(l)) continue;
       const js = l.replace(/\[\[:alnum:\]\]/g, '[A-Za-z0-9]').replace(/\[:alnum:\]/g, 'A-Za-z0-9')
         .replace(/\[:space:\]/g, '\\s').replace(/\[:alpha:\]/g, 'A-Za-z').replace(/\[:digit:\]/g, '0-9');
       try { out.push(new RegExp(js)); } catch { /* a pattern JS cannot read is skipped; the rest still apply */ }

package/kit/eval/lib/crew-map/rules/tech.json

@@ -0,0 +1,35 @@
+{
+  "about": "What a module is built with, in the words a newcomer reads: a package a manifest declares, or a file the module holds, gives a label. One list for every stack; a label is shown once per module, frameworks before tools, in the order of this file. Versions are not part of a label: the manifest line the label was read from is the module's evidence.",
+  "packages": {
+    "npm": [
+      ["next", "Next.js"], ["react", "React"], ["vue", "Vue"], ["svelte", "Svelte"], ["@angular/core", "Angular"],
+      ["astro", "Astro"], ["react-native", "React Native"], ["expo", "Expo"], ["electron", "Electron"],
+      ["hono", "Hono"], ["express", "Express"], ["fastify", "Fastify"], ["@nestjs/core", "NestJS"], ["koa", "Koa"],
+      ["graphql", "GraphQL"], ["socket.io", "Socket.IO"], ["wrangler", "Cloudflare Workers"],
+      ["@prisma/client", "Prisma"], ["prisma", "Prisma"], ["drizzle-orm", "Drizzle"], ["typeorm", "TypeORM"],
+      ["mongoose", "Mongoose"], ["tailwindcss", "Tailwind CSS"], ["vite", "Vite"], ["typescript", "TypeScript"],
+      ["vitest", "Vitest"], ["jest", "Jest"], ["@playwright/test", "Playwright"]
+    ],
+    "pypi": [
+      ["django", "Django"], ["fastapi", "FastAPI"], ["flask", "Flask"], ["sqlalchemy", "SQLAlchemy"],
+      ["celery", "Celery"], ["pydantic", "Pydantic"], ["langchain", "LangChain"], ["torch", "PyTorch"],
+      ["transformers", "Transformers"], ["spacy", "spaCy"], ["uvicorn", "Uvicorn"], ["pytest", "pytest"]
+    ],
+    "pub": [
+      ["flutter_riverpod", "Riverpod"], ["hooks_riverpod", "Riverpod"], ["riverpod", "Riverpod"],
+      ["flutter_bloc", "Bloc"], ["bloc", "Bloc"], ["provider", "Provider"], ["get", "GetX"], ["go_router", "go_router"],
+      ["dio", "Dio"], ["http", "http"], ["drift", "Drift"], ["sqflite", "sqflite"], ["hive", "Hive"], ["isar", "Isar"],
+      ["firebase_core", "Firebase"], ["freezed", "Freezed"], ["google_mobile_ads", "Google Mobile Ads"],
+      ["in_app_purchase", "In-app purchase"], ["flutter_test", "flutter_test"]
+    ],
+    "go": [
+      ["github.com/gin-gonic/gin", "Gin"], ["github.com/labstack/echo/v4", "Echo"], ["github.com/go-chi/chi/v5", "chi"],
+      ["gorm.io/gorm", "GORM"]
+    ]
+  },
+  "files": [
+    ["wrangler.toml", "Cloudflare Workers"], ["wrangler.jsonc", "Cloudflare Workers"], ["tsconfig.json", "TypeScript"],
+    ["Dockerfile", "Docker"], ["vercel.json", "Vercel"], ["netlify.toml", "Netlify"], ["fly.toml", "Fly.io"],
+    ["firebase.json", "Firebase"]
+  ]
+}