crewforth 3.2.0-rc.2 → 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
@@ -125,6 +197,31 @@ 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).

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-rc.2
+3.2.0-rc.3

package/adopt.sh

@@ -68,18 +68,24 @@ SRC="$HERE/kit"
 # --- 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
@@ -1574,6 +1580,9 @@ 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).

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

@@ -59,9 +59,9 @@ sequence. All are installed: "no owner" is an `ls`.
 
 | `model` (`guard-agent-model.sh`: floor = default; `above: <why>` for more) | the card |
 |---|---|
-| `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 critical-path file (auth, payments, migrations…) — its test-write, audit, 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`.

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

@@ -8,7 +8,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/lib/crew-env.sh" ] && . "$_crew_d/lib/crew-env.sh"
-[ -f "$_crew_d/lib/version.sh" ] && . "$_crew_d/lib/version.sh"; unset _crew_d   # an rc orders before its final
+[ -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; }
 
@@ -107,6 +108,7 @@ _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)' ;;
@@ -776,6 +778,7 @@ 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
@@ -784,7 +787,12 @@ for _f in .claude/state/crew-model/results/*; do
     case "$_l" in verify=blocked) _vb=1 ;; whynot=*) _vw="${_l#whynot=}" ;; cmd=*) _vc="${_l#cmd=}" ;; esac
   done < "$_f"
   [ "$_vb" = 1 ] || continue
-  case "$_vw" in *"not a test or build command on this hook's list"*) ;; *) continue ;; esac
+  # 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
@@ -794,6 +802,9 @@ 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

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"]
+  ]
+}

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

@@ -24,15 +24,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { openProject, loadSecretPatterns, makeHostFilter, sortEv, bearsValues, risky, spawned, isTestPath } from './project.mjs';
-import { scanStacks } from './stacks.mjs';
-import { externals, configuration, codeUrls, endpoints, containers } from './surface.mjs';
+import { openProject, loadSecretPatterns, makeHostFilter, sortEv, bearsValues, risky, spawned, isTestPath, ev } from './project.mjs';
+import { scanStacks, applyTech } from './stacks.mjs';
+import { externals, configuration, codeUrls, servedCalls, endpoints, containers } from './surface.mjs';
 import { detect } from './detect.mjs';
 import { stamp, write, serialize, validate, OUT_DIR } from '../findings/findings.mjs';
 import { carry, strip, validate as validateNarrative } from './narrative.mjs';
 
 // Languages with source the scanner has no reader for, by extension.
-const UNREAD = { dart: 'Dart', swift: 'Swift', rb: 'Ruby', php: 'PHP', rs: 'Rust', scala: 'Scala', ex: 'Elixir', exs: 'Elixir',
+const UNREAD = { swift: 'Swift', rb: 'Ruby', php: 'PHP', rs: 'Rust', scala: 'Scala', ex: 'Elixir', exs: 'Elixir',
   c: 'C', cc: 'C++', cpp: 'C++', m: 'Objective-C', mm: 'Objective-C', lua: 'Lua', clj: 'Clojure', hs: 'Haskell', erl: 'Erlang' };
 
 const SELF = fileURLToPath(import.meta.url);
@@ -43,6 +43,50 @@ const MAX_EV = 5;
 const load = (f) => JSON.parse(fs.readFileSync(path.join(HERE, 'rules', f), 'utf8'));
 const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 
+/**
+ * What is inside a module, for a reader who has not opened it: its folders and how many source files each holds.
+ * A folder holding nearly everything (lib/ of a Flutter app, src/ of a package) is opened one level, at most twice,
+ * so the rows say lib/data and lib/features and not just lib. Tests are counted apart. Twelve rows at most.
+ */
+const MAX_ROWS = 12;
+
+/**
+ * What a module says about itself: the first line of prose in its own README (a heading, a badge, an image, an
+ * HTML tag or a code fence is not prose). Kept apart from the evidence, which is cut at five lines, so a
+ * description always has a line to rest on that says what the module is for. Measured on a real project: four of
+ * ten modules were left undescribed because the only line the scan cited for them was the manifest's name.
+ */
+function aboutOf(pj, m) {
+  const base = m.dir === '.' ? '' : `${m.dir}/`;
+  const f = pj.files.find((x) => x.startsWith(base) && /^readme(\.(md|markdown|txt|rst))?$/i.test(x.slice(base.length)));
+  const src = f && pj.read(f); if (!src) return null;
+  let fence = false;
+  for (const [i, raw] of src.lines.entries()) {
+    const l = raw.trim();
+    if (/^(```|~~~)/.test(l)) { fence = !fence; continue; }
+    if (fence || !l || /^(#|=+$|-+$|\[!|!\[|<|\||>\s*\[!)/.test(l)) continue;
+    return { evidence: [ev(f, i + 1, l.slice(0, 60))] };
+  }
+  return null;
+}
+function structure(m) {
+  const base = m.dir === '.' ? '' : `${m.dir}/`;
+  let rel = m.files.filter((f) => !isTestPath(f)).map((f) => f.slice(base.length));
+  const tests = m.files.length - rel.length;
+  let at = '';
+  const group = (list) => { const g = new Map(); for (const r of list) { const k = r.includes('/') ? r.split('/')[0] : ''; g.set(k, (g.get(k) ?? 0) + 1); } return g; };
+  for (let d = 0; d < 2 && rel.length; d++) {
+    const [top, n] = [...group(rel)].sort((a, b) => b[1] - a[1] || cmp(a[0], b[0]))[0];
+    if (!top || n / rel.length < 0.8 || !rel.some((r) => r.startsWith(`${top}/`) && r.split('/').length > 2)) break;
+    at += `${top}/`; rel = rel.filter((r) => r.startsWith(`${top}/`)).map((r) => r.slice(top.length + 1));
+  }
+  const rows = [...group(rel)].map(([k, n]) => ({ folder: k ? `${at}${k}` : (at.replace(/\/$/, '') || '.'), files: n }))
+    .sort((a, b) => b.files - a.files || cmp(a.folder, b.folder));
+  const shown = rows.slice(0, MAX_ROWS);
+  const rest = rows.slice(MAX_ROWS).reduce((s, r) => s + r.files, 0);
+  return { folders: shown, ...(rest ? { otherFiles: rest } : {}), testFiles: tests };
+}
+
 // opts.hostFilter replaces the masking: ONLY the gate's must-fail twin uses it. No command-line flag reaches it.
 export function scan(root = '.', opts = {}) {
   const pj = openProject(root);
@@ -51,10 +95,12 @@ export function scan(root = '.', opts = {}) {
   const rules = load('packages.json'); const names = load('names.json');
   const stdlib = new Set(load('python-stdlib.json').modules);
   const st = scanStacks(pj);
+  applyTech(st, pj, load('tech.json'));
   const out = { edges: [], notMeasured: st.notMeasured, configUrls: [], codeHosts: new Set(), patterns };
   const ex = externals(pj, st, rules, hostOf, out);
   const cfg = configuration(pj, st, rules, hostOf, ex, out);
   codeUrls(pj, st, hostOf, ex, out);
+  servedCalls(pj, st, ex, out);
   const eps = endpoints(pj, st, out);
   const services = containers(pj, st, rules, hostOf, ex, cfg, out);
   const findings = detect({ st, cfg, eps, names, stdlib, notMeasured: out.notMeasured, configUrls: out.configUrls, codeHosts: out.codeHosts });
@@ -73,6 +119,9 @@ export function scan(root = '.', opts = {}) {
     const lang = UNREAD[/\.([a-z]+)$/i.exec(f)?.[1]?.toLowerCase()];
     if (lang && !isTestPath(f)) unread.set(lang, (unread.get(lang) ?? 0) + 1);
   }
+  // Dart is read through its pubspec.yaml: a .dart file no package owns has no module to be drawn in, so it is said.
+  const loose = pj.files.filter((f) => /\.dart$/.test(f) && !isTestPath(f) && !st.modules.some((m) => m.stack === 'dart' && m.files.includes(f))).length;
+  if (loose) out.notMeasured.push({ what: `Dart source outside any pubspec.yaml (${loose} file${loose === 1 ? '' : 's'})`, reason: 'no package owns it: it is not on the map' });
   for (const [lang, n] of unread) out.notMeasured.push({ what: `${lang} source (${n} file${n === 1 ? '' : 's'})`, reason: 'no reader for this language: its modules, dependencies and endpoints are not on the map' });
 
   // ---- one edge per (from, to, kind, confidence), its evidence merged ----
@@ -94,6 +143,8 @@ export function scan(root = '.', opts = {}) {
       // line to cite: the entry is then the file, and it says so.
       ...(m.entry ? { entryPoint: m.entryEv ? { evidence: [m.entryEv] } : { file: m.entryFile, evidence: [] } } : {}),
       dependencies: m.deps.length,
+      structure: structure(m),
+      ...((() => { const a = aboutOf(pj, m); return a ? { about: a } : {}; })()),
       ...capped(m.evidence), narrative: null })),
     ...services.map((s) => ({ id: s.id, kind: 'service', name: s.name, ...(s.image ? { image: s.image } : {}), ...capped(s.evidence), narrative: null })),
     ...[...ex.ext.values()].map((n) => ({ id: n.id, kind: 'external', resource: n.resource, label: n.label, hosts: [...n.hosts].sort(), ...capped(n.evidence), narrative: null })),
@@ -122,6 +173,7 @@ export function scan(root = '.', opts = {}) {
     findings,
     notMeasured: [...nm.values()].sort((a, b) => cmp(`${a.what}\u0000${a.reason}`, `${b.what}\u0000${b.reason}`)),
     overview: null,
+    tour: null,
   };
   // The last net, whatever cited it: a quote is cut before anything that looks like a credential, and a line that
   // carries values (by its file, or by what is on it) is never hashed.