crewforth 3.1.1 → 3.2.0-rc.2

package/kit/agents/crew-session-manager.md

@@ -2,8 +2,8 @@
 name: crew-session-manager
 color: blue
 description: |
-  Session/context health auditor for a PHASE BOUNDARY: audits fill, recommends the handover. The per-turn
-  status line is the main thread's own, from the hook. Evaluates only; writes no code.
+  Use at a phase boundary or when the fill reads medium or more: audits fill, drafts the handover. The
+  per-turn status line stays the main thread's. Writes no code.
 tools: Read, Grep, Glob, Bash, PowerShell
 # No `model` field: the caller names it per call. Not `haiku`: the handover is a synthesis over an entire
 # session and decides what the NEXT session knows, and a thin one fails silently.
@@ -18,7 +18,8 @@ metadata:
 Trigger phrases: "session status", "session health", "context status", "is a handover needed", "is it time to clear", "handover", "hand over", "switch topic", "getting long", "running out of context"
 
 Purpose: so the user never has to track context/token management by hand.
-Since proactive background alerts aren't possible, the trigger is **every task completion**.
+It is called at a **phase boundary** or when the measured fill reads medium or more; the per-turn 🔋 line itself
+is the main thread's, from the hook, and needs no agent.
 
 ## Expertise stance (context/operations manager)
 - **Measure, do NOT guess**: the assistant can't run `/context`; actual fill is read from the transcript via `context-usage.sh` (below).
@@ -27,13 +28,14 @@ Since proactive background alerts aren't possible, the trigger is **every task c
 - **Token discipline:** on the delegate / summary / file-offload decision, apply the `token-budget` skill.
 
 ## When
-- At the close of every task/subtask (at the very end of the DoD chain).
-- When the user says "session status?".
+- At a phase boundary: after crew-commit-agent, at the end of the chain, and as the first step of `/crew-handoff`.
+- When the 🔋 line reads medium or more, or the user says "session status?".
 
 ## What it does
-Appends a single line to the very END of the response:
+Reports the measured fill and the recommendation in the same form as the per-turn line, and, when the
+recommendation is a handover, a draft of it (`handoff` skill) for `/crew-handoff` to write:
 
-`🔋 Session: [low/medium/high fill] · Recommendation: [continue / handoff+clear / new session]`
+`🔋 Session %NN → [low/medium/high] fill · Recommendation: [continue / handoff+clear / new session]`
 
 **Actual fill is MEASURED, guessing is FORBIDDEN.** The `UserPromptSubmit` hook runs `context-usage.sh` each turn,
 automatically injecting the real `🔋 Session: %.. (token) → level` line into the context — use that value. If you want an
@@ -63,13 +65,13 @@ paused should be released with its handover note.
 - Reports the decision; doesn't run `/clear` on the user's behalf.
 
 ## Output & context (token)
-To the main thread: a single health line + recommendation. Do no long analysis; read the `context-usage.sh` output, add no commentary.
+To the main thread: the health line + recommendation, and the handover draft when it recommends one. Do no long analysis; read the `context-usage.sh` output, add no commentary.
 
 ## Errors/escalation
 When you notice a topic change / threshold breach, **recommend but don't interrupt**; don't force a clear mid-task.
 
 ## Example delegation
-- ✅ Session-health line at task completion
+- ✅ A phase boundary, or the 🔋 line at medium or more
 - ❌ Content/code generation (out of scope)
 
 ## Confidence

package/kit/eval/doctor.sh

@@ -7,7 +7,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"; 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"; unset _crew_d   # an rc orders before its final
 ROOT="${1:-.}"
 cd "$ROOT" 2>/dev/null || { echo "doctor: cannot enter '$ROOT'"; exit 2; }
 
@@ -98,6 +99,21 @@ _mt() {
       'settings.json is invalid JSON') s='settings.json geçersiz JSON' ;;
       "Claude Code %s is older than 2.1.293 — the model alias haiku may not resolve to Haiku 5.5 there, so an agent called with model haiku can run on an older model (update Claude Code)") s="Claude Code %s, 2.1.293'ten eski — orada haiku model takma adı Haiku 5.5'e çözülmeyebilir; model haiku ile çağrılan bir ajan eski bir modelde koşabilir (Claude Code'u güncelleyin)" ;;
       'approval by your own message is wired (auto / dontAsk: /crew-approve commit)') s='kendi mesajınızla onay bağlı (auto / dontAsk: /crew-approve commit)' ;;
+      'the published Crewforth version is not measured: no update check has run here yet (.claude/.state/update-check)') s='yayınlanmış Crewforth sürümü ölçülmedi: burada henüz hiç güncelleme denetimi koşmadı (.claude/.state/update-check)' ;;
+      'two editions at once: not measured (the plugin list could not be read)') s='iki edisyon birden: ölçülmedi (plugin listesi okunamadı)' ;;
+      'two editions at once: not measured (no claude CLI here to list the plugins)') s='iki edisyon birden: ölçülmedi (pluginleri listeleyecek claude CLI burada yok)' ;;
+      'the %s plugin is enabled and this project has Crewforth installed in .claude/ — every hook runs twice; turn one off (claude plugin disable %s, or remove the install)') s="%s plugin'i etkin ve bu projede Crewforth .claude/ altında da kurulu — her hook iki kez koşuyor; birini kapatın (claude plugin disable %s ya da kurulumu kaldırın)" ;;
+      'one edition: the Crewforth plugin is not enabled beside this install') s="tek edisyon: Crewforth plugin'i bu kurulumun yanında etkin değil" ;;
+      '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" ;;
+      "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" ;;
+      'advisorModel is %s in %s, but %s is set and the advisor needs the Anthropic API — it is not used') s="advisorModel %s (%s içinde), ama %s ayarlı ve advisor Anthropic API ister — kullanılmıyor" ;;
+      "advisor: on, %s (from %s); not a gate, and its tokens are in /usage and in Studio's session cost") s="advisor: açık, %s (%s içinden); bir kapı değil, token'ları /usage'da ve Studio'nun oturum maliyetinde" ;;
+      'the advisor (%s) is below the critical tier (opus): Claude Code does not attach an advisor below the model it would advise, so critical work runs without one') s="advisor (%s) kritik seviyenin (opus) altında: Claude Code danışacağı modelin altındaki bir advisor'ı eklemiyor, yani kritik iş advisor'sız koşuyor" ;;
       "settings.json wires prompt-approval.sh but the script is missing — in auto and dontAsk '/crew-approve commit' records nothing; switch mode with Shift+Tab or commit in your own terminal (update Crewforth)") s="settings.json prompt-approval.sh'i bağlıyor ama betik yok — auto ve dontAsk modunda '/crew-approve commit' hiçbir şey kaydetmez; Shift+Tab ile mod değiştirin ya da kendi terminalinizden commit edin (Crewforth'u güncelleyin)" ;;
       "prompt-approval.sh is not wired on UserPromptSubmit — in auto and dontAsk '/crew-approve commit' records nothing; switch mode with Shift+Tab or commit in your own terminal (update Crewforth)") s="prompt-approval.sh UserPromptSubmit'e bağlı değil — auto ve dontAsk modunda '/crew-approve commit' hiçbir şey kaydetmez; Shift+Tab ile mod değiştirin ya da kendi terminalinizden commit edin (Crewforth'u güncelleyin)" ;;
       "worktree %s carries Crewforth %s, this one %s — a session there runs that version's gates and approval path (update Crewforth there)") s="%s worktree'sinde Crewforth %s var, burada %s — orada açılan oturum o sürümün kapılarını ve onay yolunu koşar (Crewforth'u orada güncelleyin)" ;;
@@ -204,10 +220,11 @@ 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
+  skip "the published Crewforth version is not measured: no update check has run here yet (.claude/.state/update-check)"
 fi
 
 # 1c) Install trace. An update leaves VERSION, the install manifest and the components on disk agreeing; when they do
@@ -643,9 +660,9 @@ for _v in $(compgen -e); do
   esac
 done
 if [ "$FAIL" -eq 0 ]; then _mt "DOCTOR: healthy ✅%s" "$PANEL_NOTE"; echo "$_M"
-  # Healthy verdict: the star line, once per kit version — the marker is shared with the installers, so the
-  # doctor run that /crew-update makes right after an update stays quiet. Text/URL/silence: lib/star.sh.
-  [ -f "$(dirname "$0")/lib/star.sh" ] && bash "$(dirname "$0")/lib/star.sh" --once .
+  # Healthy verdict: the star line, once per kit version under doctor's own marker (the installers keep theirs).
+  # /crew-update runs this with CREW_NO_STAR=1, so an update shows it once, not twice. Text/URL/silence: lib/star.sh.
+  [ -f "$(dirname "$0")/lib/star.sh" ] && bash "$(dirname "$0")/lib/star.sh" --once . doctor
 else _mt "DOCTOR: %s issue(s) ❌ — apply the fixes above%s" "$FAIL" "$PANEL_NOTE"; echo "$_M"; fi
 
 # 9) The auto-mode classifier. Since 2026-08-14 auto mode is the default permission mode on Pro/Max/Team, so a
@@ -684,6 +701,100 @@ EOF_CCV
     fi ;;
   esac
 fi
+# 9c) Two editions at once, and the advisor. Advisory, never a failure.
+#     PLUGIN AND INSTALL BOTH ON: the plugin edition and this .claude/ install each wire every hook, so with both
+#     enabled each gate runs twice on every call (and a gate's own refusal is printed twice). Asked of the CLI —
+#     `claude plugin list --json`, whose `enabled` is "enabled in your merged settings" — because the settings files
+#     alone cannot say what a managed or a --plugin-dir layer added. No CLI: not measured, and said so.
+#     THE ADVISOR (advisorModel; documented: fable, opus, sonnet or a full model id, unset = off; Anthropic API only;
+#     CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 turns it off). Crewforth never sets it. What is reported is whether it is on
+#     and on what, read from the same three settings files as the skill-listing budget above (a managed layer is not
+#     read), and a note when it sits below the critical tier: Claude Code does not attach an advisor that ranks below
+#     the model it would advise (code.claude.com/docs/en/advisor), so an agent on opus gets none.
+#     Its usage is not reported here. It is in /usage, and in the transcript (usage.iterations, `advisor_message`,
+#     measured on a real advisor session), which is where Studio's session cost reads it.
+if [ -f .claude/hooks/guard-bash.sh ]; then
+  if command -v claude >/dev/null 2>&1 && _pl="$(claude plugin list --json 2>/dev/null)" && [ -n "$_pl" ]; then
+    _pon=""; _pn="$(printf '{"p":%s}' "$_pl" | awk -v op=len -v path=p -f "${SJ:-.claude/eval/lib/settings-json.awk}" - 2>/dev/null)" || _pn=""
+    case "$_pn" in ''|*[!0-9]*) skip "two editions at once: not measured (the plugin list could not be read)" ;;
+      *) _pi=0
+         while [ "$_pi" -lt "$_pn" ]; do
+           _pid="$(printf '{"p":%s}' "$_pl" | awk -v op=get -v path="p.$_pi.id" -f "${SJ:-.claude/eval/lib/settings-json.awk}" - 2>/dev/null)"
+           # crewforth@… is 3.x; claude-starter-kit@… is the 2.x plugin, which wires the same hooks and is often still
+           # enabled at user scope after a 3.x install (measured in a real project).
+           case "$_pid" in '"crewforth@'*|'"claude-starter-kit@'*)
+             _pen="$(printf '{"p":%s}' "$_pl" | awk -v op=get -v path="p.$_pi.enabled" -f "${SJ:-.claude/eval/lib/settings-json.awk}" - 2>/dev/null)"
+             [ "$_pen" = true ] && _pon="${_pid//\"/}" ;;
+           esac
+           _pi=$((_pi+1))
+         done
+         if [ -n "$_pon" ]; then
+           warn "the %s plugin is enabled and this project has Crewforth installed in .claude/ — every hook runs twice; turn one off (claude plugin disable %s, or remove the install)" "$_pon" "$_pon"
+         else ok "one edition: the Crewforth plugin is not enabled beside this install"; fi ;;
+    esac
+  else
+    skip "two editions at once: not measured (no claude CLI here to list the plugins)"
+  fi
+fi
+_adv=""; _advf=""
+for sf in .claude/settings.local.json .claude/settings.json "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"; do
+  [ -f "$sf" ] || continue
+  v="$(awk -v op=get -v path=advisorModel -f "${SJ:-.claude/eval/lib/settings-json.awk}" "$sf" 2>/dev/null)" || v=""
+  v="${v#\"}"; v="${v%\"}"
+  [ -n "$v" ] && { _adv="$v"; _advf="$sf"; break; }
+done
+_advprov=""; for _ev in CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX; do
+  eval "_evv=\"\${$_ev:-}\""; case "$_evv" in ''|0|false) ;; *) _advprov="$_ev"; break ;; esac
+done
+if [ -z "$_adv" ]; then
+  if [ "${CLAUDE_CODE_DISABLE_ADVISOR_TOOL:-}" = 1 ]; then ok "advisor: off (CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1)"
+  else ok "advisor: off (no advisorModel set; Crewforth never turns it on)"; fi
+elif [ "${CLAUDE_CODE_DISABLE_ADVISOR_TOOL:-}" = 1 ]; then
+  warn "advisorModel is %s in %s, but CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 turns the advisor off" "$_adv" "$_advf"
+elif [ -n "$_advprov" ]; then
+  warn "advisorModel is %s in %s, but %s is set and the advisor needs the Anthropic API — it is not used" "$_adv" "$_advf" "$_advprov"
+else
+  ok "advisor: on, %s (from %s); not a gate, and its tokens are in /usage and in Studio's session cost" "$_adv" "$_advf"
+  case "$_adv" in *haiku*|*sonnet*)
+    warn "the advisor (%s) is below the critical tier (opus): Claude Code does not attach an advisor below the model it would advise, so critical work runs without one" "$_adv" ;;
+  esac
+fi
+# 9d) The status line. Advisory, never a failure. The installers set Crewforth's only where none is set; a line of
+#     the user's own is never replaced (the project's setting would win over it). A managed layer is not read.
+_slj="${SJ:-.claude/eval/lib/settings-json.awk}"; _sl=""; _slf=""
+for _f in .claude/settings.json .claude/settings.local.json "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"; do
+  [ -f "$_f" ] && [ -f "$_slj" ] || continue
+  _v="$(awk -v op=get -v path=statusLine.command -f "$_slj" "$_f" 2>/dev/null)" || _v=""
+  [ -n "$_v" ] && { _sl="$_v"; _slf="$_f"; break; }
+done
+case "$_sl" in
+  *eval/lib/statusline.sh*) ok "status line: Crewforth's (from %s)" "${_slf/#$HOME/~}" ;;
+  ?*) ok "status line: your own (from %s); Crewforth's is not used" "${_slf/#$HOME/~}" ;;
+  *) [ -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).
+_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
+  case "$_vw" in *"not a test or build command on this hook's list"*) ;; *) continue ;; esac
+  _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
+
 # 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/golden-routing.txt

@@ -225,3 +225,12 @@ we picked the wrong language for this service, write an adr|!i18n-integrity
 write the README in english for the public repo|!i18n-integrity
 the connection strings are missing from appsettings|!i18n-integrity
 add language support for kotlin to the parser|!i18n-integrity
+try to refute this finding: the token check at src/auth.js:42 can be bypassed|crew-refuter
+disprove this claim before it goes in the report|crew-refuter
+run a security audit of the login flow|!crew-refuter
+review my diff before I commit|!crew-refuter
+update the privacy policy text for the new data retention period|crew-docs-agent
+write the release notes and the changelog entry for this version|crew-docs-agent
+rewrite the app store description for the new release|crew-docs-agent
+add an endpoint that returns the privacy settings|!crew-docs-agent
+fix the failing unit test in the payment module|!crew-docs-agent

package/kit/eval/lib/crew-map/crew-map.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# crew-map.sh — the shell entry to scan.mjs. It does one thing: find a Node that RUNS and hand over.
+#
+#   bash crew-map.sh [--root DIR] [--stdout | --check]      the arguments and exit codes of scan.mjs (0, 1, 2)
+#       rc 3 = no usable Node here, so nothing was scanned. Not a pass: a caller must not read 3 as a fresh map.
+#
+# The same resolution as findings.sh beside it: ask node for its version (the Windows Store's stub resolves and
+# then exits 49), and when PATH has none, ask the panel's resolver. This file never installs anything.
+set -u
+# Cut at either separator: on Windows a caller may name this file with backslashes.
+d="${BASH_SOURCE%[/\\]*}"; [ "$d" = "${BASH_SOURCE}" ] && d=.
+FLOOR=18
+
+usable(){ local v; v="$("$1" -p 'process.versions.node.split(".")[0]' 2>/dev/null)" || return 1
+  case "$v" in ''|*[!0-9]*) return 1 ;; esac; [ "$v" -ge "$FLOOR" ]; }
+
+NODE=""
+if usable node; then NODE=node
+elif [ -f "$d/../../../studio/ensure-node.sh" ]; then
+  n="$(bash "$d/../../../studio/ensure-node.sh" 2>/dev/null)" && [ -n "$n" ] && usable "$n" && NODE="$n"
+fi
+if [ -z "$NODE" ]; then
+  echo "crew-map: no Node $FLOOR+ that runs was found, so nothing was scanned (this is not a pass)" >&2
+  exit 3
+fi
+exec "$NODE" "$d/scan.mjs" "$@"

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

@@ -0,0 +1,238 @@
+// detect.mjs — the ten gap detectors. Each returns findings in the shape of the findings core
+// (kit/eval/lib/findings): every one cites the lines it was read from.
+//
+// Two classes, and the class is the rule's, not the finding's:
+//   proven    the cited lines show it on their own (a cycle, an import with no declaration, a read with no key)
+//   inferred  concluded from absence in THIS repository — an external caller, reflection, a CLI or a framework can use
+//             what the scan did not see. These are written with data.defaultHidden = true: a reader sees them only
+//             when asking for them, until their false-positive rate has been measured in the field.
+// The wording describes what was searched, never who is at fault: "no caller found in this repo".
+
+import crypto from 'node:crypto';
+import { canon } from './surface.mjs';
+import { sortEv } from './project.mjs';
+
+export const RULES = ['cycle', 'module-orphan', 'version-drift', 'dep-undeclared', 'dep-unused', 'config-missing',
+  'config-unread', 'endpoint-missing', 'endpoint-unused', 'external-unowned'];
+// module-orphan and config-unread conclude from absence too: a service started from a CLI, or settings bound by
+// name (pydantic BaseSettings), leave nothing in the lines for a scan to see.
+export const INFERRED = new Set(['dep-unused', 'endpoint-unused', 'external-unowned', 'module-orphan', 'config-unread']);
+const HIDDEN_REASON = 'inferred from absence in this repository; shown on request until its false-positive rate is measured';
+const MAX_EV = 5;
+
+// Collected raw, built once: the same rule and subject seen twice (a missing endpoint called from two places)
+// is ONE finding citing both places, never two findings with one id.
+function finding(rule, subject, title, evidence, data = {}) { return { rule, subject, title, evidence, data }; }
+function build(raw) {
+  const by = new Map();
+  for (const r of raw) {
+    const k = `${r.rule}\u0000${r.subject}`;
+    if (by.has(k)) by.get(k).evidence.push(...r.evidence); else by.set(k, { ...r, evidence: [...r.evidence] });
+  }
+  return [...by.values()].map(({ rule, subject, title, evidence, data }) => {
+    const slug = subject.toLowerCase().replace(/[^a-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 120) || 'x';
+    const h = crypto.createHash('sha1').update(`${rule}\u0000${subject}`).digest('hex').slice(0, 8);
+    const all = sortEv(evidence);
+    const f = { id: `${rule}:${slug}:${h}`, rule, title: title.slice(0, 200),
+      confidence: INFERRED.has(rule) ? 'inferred' : 'proven', evidence: all.slice(0, MAX_EV) };
+    const d = { subject, ...data };
+    if (all.length > MAX_EV) d.evidenceTotal = all.length;
+    if (INFERRED.has(rule)) { d.defaultHidden = true; d.hiddenReason = HIDDEN_REASON; }
+    f.data = d;
+    return f;
+  });
+}
+
+// Endpoint match: same method or either is '*'; same segment count; segments equal or either is a parameter.
+function epMatch(a, b) {
+  if (a.method !== b.method && a.method !== '*' && b.method !== '*') return false;
+  const x = a.path.split('/'); const y = b.path.split('/');
+  return x.length === y.length && x.every((s, i) => s === y[i] || s === '{}' || y[i] === '{}');
+}
+
+export function detect(ctx) {
+  const { st, cfg, eps, names, stdlib, notMeasured } = ctx;
+  const out = [];
+  const mods = st.modules;
+  const byId = new Map(mods.map((m) => [m.id, m]));
+  const refs = mods.flatMap((m) => m.refs.filter((r) => byId.has(r.to)).map((r) => ({ from: m.id, ...r })));
+
+  // ---- cycle (evidence edges only: a cycle through an inferred edge is not shown by the lines) ----
+  {
+    const adj = new Map(mods.map((m) => [m.id, []]));
+    for (const r of refs) if (r.confidence === 'evidence' && r.from !== r.to) adj.get(r.from).push(r.to);
+    let idx = 0; const index = new Map(); const low = new Map(); const stack = []; const on = new Set(); const sccs = [];
+    const strong = (v) => {
+      index.set(v, idx); low.set(v, idx); idx++; stack.push(v); on.add(v);
+      for (const w of [...new Set(adj.get(v))].sort()) {
+        if (!index.has(w)) { strong(w); low.set(v, Math.min(low.get(v), low.get(w))); }
+        else if (on.has(w)) low.set(v, Math.min(low.get(v), index.get(w)));
+      }
+      if (low.get(v) === index.get(v)) { const c = []; let w; do { w = stack.pop(); on.delete(w); c.push(w); } while (w !== v); if (c.length > 1) sccs.push(c.sort()); }
+    };
+    for (const id of [...adj.keys()].sort()) if (!index.has(id)) strong(id);
+    for (const c of sccs) {
+      const inC = new Set(c);
+      const e = refs.filter((r) => r.confidence === 'evidence' && inC.has(r.from) && inC.has(r.to)).map((r) => r.ev);
+      const names2 = c.map((id) => byId.get(id).name);
+      out.push(finding('cycle', c.join(' '), `Modules reference each other in a cycle: ${names2.join(' → ')} → ${names2[0]}`, e, { modules: c }));
+    }
+  }
+
+  // ---- module-orphan ----
+  if (mods.length >= 2) {
+    const incoming = new Set(refs.map((r) => r.to));
+    for (const m of mods) {
+      if (m.dir === '.' || m.entry || m.deployed || incoming.has(m.id)) continue;
+      if (m.tech.has('maven:pom')) continue; // an aggregator is a build entry point
+      out.push(finding('module-orphan', m.id, `No module references ${m.name}, and it has no entry point`, m.evidence, { module: m.id }));
+    }
+  }
+
+  // ---- version-drift ----
+  {
+    const by = new Map();
+    for (const m of mods) for (const d of m.deps) {
+      // A peer range is a range by design, and a URL is not a version.
+      if (!d.version || d.central || d.peer || d.version === 'url' || /^(workspace:|file:|link:|\*$)/.test(d.version)) continue;
+      const k = `${d.eco}\u0000${d.name}`;
+      if (!by.has(k)) by.set(k, []);
+      by.get(k).push({ m, d });
+    }
+    for (const [k, list] of [...by.entries()].sort()) {
+      const versions = [...new Set(list.map((x) => x.d.version))].sort();
+      if (versions.length < 2 || new Set(list.map((x) => x.m.id)).size < 2) continue; // drift is between modules
+      const name = k.split('\u0000')[1];
+      out.push(finding('version-drift', k.replace('\u0000', ':'), `${name} is declared at ${versions.length} versions: ${versions.join(', ')}`,
+        list.map((x) => x.d.ev), { package: name, versions, modules: [...new Set(list.map((x) => x.m.id))].sort() }));
+    }
+  }
+
+  // ---- dep-undeclared / dep-unused (node, python, go) ----
+  const builtins = new Set(names.nodeBuiltins.names);
+  const pyAlias = names.pythonImportNames.map;
+  const never = names.neverImported ?? { python: [], node: {} };
+  const pyNever = never.python.map((g) => new RegExp(`^${g.toLowerCase().replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`));
+  const pyImportName = (dist) => (pyAlias[dist.toLowerCase()] || dist).toLowerCase().replace(/-/g, '_');
+  const pyLocal = new Set(mods.filter((m) => m.stack === 'python').flatMap((m) => [...(m.localNames || []), ...m.selfNames.map((n) => n.toLowerCase().replace(/-/g, '_'))]));
+  for (const m of mods) {
+    if (!['node', 'python', 'go'].includes(m.stack) || !m.manifest) continue;
+    const ancestors = mods.filter((o) => o.stack === m.stack && o !== m && (o.dir === '.' || m.dir.startsWith(o.dir + '/')));
+    const declared = new Set([...m.deps, ...ancestors.flatMap((o) => o.deps)].map((d) => d.name));
+    const roots = new Map();
+    for (const im of m.imports) { if (!roots.has(im.root)) roots.set(im.root, []); roots.get(im.root).push(im.ev); }
+    if (m.stack === 'node') {
+      const aliases = [...m.aliases, ...ancestors.flatMap((o) => o.aliases), ...st.globalAliases].filter(Boolean);
+      for (const [root, evs] of roots) {
+        const bare = root.replace(/^node:/, '');
+        if (root.startsWith('node:') || builtins.has(bare) || builtins.has(bare.split('/')[0])) continue;
+        if (/^(@\/|~\/|#|virtual:|bun:|data:|https?:)|[!?]/.test(root) || root === '@' || root === '~') continue;
+        if (aliases.some((a) => root === a.replace(/\/$/, '') || root.startsWith(a))) continue;
+        if (declared.has(root) || m.selfNames.includes(root) || declared.has(`@types/${root}`)) continue;
+        out.push(finding('dep-undeclared', `${m.id} ${root}`, `${root} is imported but not declared in ${m.manifest}`, evs, { module: m.id, package: root }));
+      }
+      const used = new Set(roots.keys());
+      for (const d of m.deps) {
+        if (d.dev || d.name.startsWith('@types/') || used.has(d.name)) continue;
+        if (never.node[d.name] && declared.has(never.node[d.name])) continue;
+        out.push(finding('dep-unused', `${m.id} ${d.name}`, `${d.name} is declared but no import of it was found in this repo`, [d.ev], { module: m.id, package: d.name }));
+      }
+    } else if (m.stack === 'python') {
+      const decl = new Set([...declared].map(pyImportName));
+      for (const [root, evs] of roots) {
+        const r = root.toLowerCase();
+        if (stdlib.has(root) || root === '__future__' || pyLocal.has(root) || pyLocal.has(r) || decl.has(r)) continue;
+        out.push(finding('dep-undeclared', `${m.id} ${root}`, `${root} is imported but not declared in ${m.manifest}`, evs, { module: m.id, package: root }));
+      }
+      const used = new Set([...roots.keys()].map((x) => x.toLowerCase()));
+      for (const d of m.deps) {
+        if (d.dev || used.has(pyImportName(d.name))) continue;
+        if (pyNever.some((re) => re.test(d.name.toLowerCase()))) continue;
+        out.push(finding('dep-unused', `${m.id} ${d.name}`, `${d.name} is declared but no import of it was found in this repo`, [d.ev], { module: m.id, package: d.name }));
+      }
+    } else {
+      const req = m.deps.map((d) => d.name);
+      for (const [root, evs] of roots) {
+        if (req.some((r) => root === r || root.startsWith(r + '/'))) continue;
+        out.push(finding('dep-undeclared', `${m.id} ${root}`, `${root} is imported but not required in ${m.manifest}`, evs, { module: m.id, package: root }));
+      }
+      for (const d of m.deps) {
+        if (d.indirect || [...roots.keys()].some((r) => r === d.name || r.startsWith(d.name + '/'))) continue;
+        out.push(finding('dep-unused', `${m.id} ${d.name}`, `${d.name} is required but no import of it was found in this repo`, [d.ev], { module: m.id, package: d.name }));
+      }
+    }
+  }
+
+  // ---- config-missing / config-unread ----
+  {
+    const platform = new Set(names.platformEnv.names.map(canon));
+    const framework = names.frameworkConfig.names;
+    const defined = new Set(cfg.defs.map((d) => canon(d.key)));
+    const exactReads = new Set(cfg.reads.filter((r) => !r.prefix).map((r) => canon(r.key)));
+    const prefixReads = cfg.reads.filter((r) => r.prefix).map((r) => canon(r.key));
+    const missing = new Map();
+    const fileDefs = cfg.defs.filter((d) => ['env', 'appsettings', 'properties', 'yaml'].includes(d.source)).length;
+    if (!fileDefs && cfg.reads.some((r) => !r.prefix && !r.hasDefault)) notMeasured.push({ what: 'config-missing', reason: 'this repository has no configuration file (.env, appsettings, application.properties/yml), so where its keys are meant to come from is not on disk' });
+    for (const r of fileDefs ? cfg.reads : []) {
+      if (r.prefix || r.hasDefault) continue;
+      const c = canon(r.key);
+      if (defined.has(c) || platform.has(c)) continue;
+      if (!missing.has(c)) missing.set(c, { key: r.key, evs: [] });
+      missing.get(c).evs.push(r.ev);
+    }
+    for (const [c, x] of [...missing.entries()].sort()) out.push(finding('config-missing', c, `${x.key} is read but defined in no configuration file`, x.evs, { key: x.key }));
+    if (mods.length) {
+      for (const d of cfg.defs) {
+        if (!['env', 'appsettings', 'properties', 'yaml'].includes(d.source)) continue;
+        const c = canon(d.key);
+        if (exactReads.has(c) || prefixReads.some((p) => c === p || c.startsWith(p + '.'))) continue;
+        if (framework.some((fw) => (/[:.]$/.test(fw) ? d.key.startsWith(fw) || d.key === fw.slice(0, -1) : d.key === fw))) continue;
+        out.push(finding('config-unread', `${d.file} ${d.key}`, `${d.key} is configured in ${d.file} but no read of it was found`, [d.ev], { key: d.key, file: d.file }));
+      }
+    }
+  }
+
+  // ---- endpoint-missing / endpoint-unused ----
+  {
+    const prov = eps.provides.filter((e) => e.resolved); const cons = eps.consumes.filter((e) => e.resolved);
+    if (eps.provides.length) {
+      // A call is judged only against a provider it could belong to: one that shares its first path segment. A
+      // path no provider here begins with is most likely another service's, and is left to that service's map.
+      const firsts = new Set(prov.map((p) => p.path.split('/')[1]));
+      // Under a router mounted elsewhere the provider's full path is not known, so a call there is not judged.
+      const under = (c) => eps.mounts.some((mt) => c.path === mt || c.path.startsWith(mt === '/' ? '/' : mt + '/'));
+      for (const c of cons) {
+        if (prov.some((p) => epMatch(p, c))) continue;
+        if (!firsts.has(c.path.split('/')[1]) || under(c)) continue;
+        // Its host is a run-time value: the call may well be to another service (a model server's /api/tags).
+        if (c.base) continue;
+        out.push(finding('endpoint-missing', `${c.module} ${c.method} ${c.path}`, `${c.method} ${c.path} is called but no endpoint in this repo provides it`, c.evidence, { method: c.method, path: c.path, module: c.module }));
+      }
+    } else if (eps.consumes.length) {
+      notMeasured.push({ what: 'endpoint-missing', reason: 'this repository provides no endpoint, so the paths it calls can only be matched against the provider\'s own map' });
+    }
+    if (eps.consumes.length) {
+      for (const p of prov) {
+        if (cons.some((c) => epMatch(p, c))) continue;
+        // A healthcheck or a probe calls it: the platform is its caller.
+        if ((eps.probes ?? []).some((path) => epMatch(p, { method: 'GET', path }))) continue;
+        out.push(finding('endpoint-unused', `${p.module} ${p.method} ${p.path}`, `${p.method} ${p.path} is provided but no caller found in this repo`, p.evidence, { method: p.method, path: p.path, module: p.module }));
+      }
+    } else if (eps.provides.length) {
+      notMeasured.push({ what: 'endpoint-unused', reason: 'this repository calls none of its own endpoints, so their callers are elsewhere' });
+    }
+    const unresolved = [...eps.provides, ...eps.consumes].filter((e) => !e.resolved).length;
+    if (unresolved) notMeasured.push({ what: `endpoints with a run-time path (${unresolved})`, reason: 'the start of the path is built at run time, so they are listed but never matched' });
+  }
+
+  // ---- external-unowned ----
+  {
+    const readCanon = new Set(cfg.reads.map((r) => canon(r.key)));
+    for (const u of ctx.configUrls) {
+      if (!u.host || u.host === '[masked]') continue;
+      if (readCanon.has(canon(u.key)) || ctx.codeHosts.has(u.host)) continue;
+      out.push(finding('external-unowned', `${u.ev.file} ${u.key}`, `${u.host} is configured under ${u.key} but no client using it was found`, [u.ev], { key: u.key, host: u.host }));
+    }
+  }
+  return build(out);
+}

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

@@ -0,0 +1,98 @@
+// narrative.mjs — what the model may add to a crew map, and the rule it is held to. One definition, read by the
+// scanner (--write keeps it, --check ignores it, --validate judges it) and by its tests.
+//
+// The scanner writes every node with `narrative: null` and the document with `overview: null`. /crew-map lets the
+// 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)
+//   doc.overview    { text, cites }  a short orientation for someone new to the project; its cites may be any
+//                   node's evidence
+// 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;
+
+/** The "file:line" a node's evidence lets a narrative cite. */
+export function citesOf(node) {
+  const out = new Set();
+  for (const e of Array.isArray(node?.evidence) ? node.evidence : []) {
+    if (e && typeof e.file === 'string' && Number.isInteger(e.line)) out.add(`${e.file}:${e.line}`);
+  }
+  return out;
+}
+
+/** Every line any node of the document cites: what an overview may point at. */
+export function allCites(doc) {
+  const out = new Set();
+  for (const n of doc?.nodes ?? []) for (const c of citesOf(n)) out.add(c);
+  return out;
+}
+
+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 } = {}) {
+  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})`;
+  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';
+  if (!Array.isArray(n.cites) || !n.cites.length) return 'cites nothing: a description must point at a line the scan read';
+  const bad = n.cites.filter((c) => typeof c !== 'string' || !allowed.has(c));
+  if (bad.length) return `cites ${bad.slice(0, 3).map(String).join(', ')}, which the scan did not cite here`;
+  return null;
+}
+
+/** 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 };
+}
+
+/**
+ * A new scan with the narratives of the old map carried over, where they still hold: a node with the same id
+ * whose narrative still cites only lines this scan cites for it. One that no longer holds is dropped, and counted.
+ */
+export function carry(old, fresh) {
+  const was = new Map((old?.nodes ?? []).map((n) => [n.id, n.narrative]));
+  let kept = 0; let dropped = 0;
+  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 }; }
+    dropped += 1; return n;
+  });
+  const doc = { ...fresh, nodes };
+  if (old?.overview != null) {
+    if (problemOf(old.overview, allCites(doc), { max: MAX_OVERVIEW, twoSentences: false }) === null) { doc.overview = old.overview; kept += 1; }
+    else dropped += 1;
+  }
+  return { doc, kept, dropped };
+}
+
+/**
+ * Hold a map the model wrote to the rules: its scanner fields are what a scan of the tree writes now, and every
+ * narrative and the overview pass `problemOf`. Returns a list of { at, message }; empty means it holds.
+ * @param serialize  how the scanner writes a document (so the comparison is of its own bytes)
+ */
+export function validate(file, fresh, serialize) {
+  const out = [];
+  const bare = (d) => { const { source, ...rest } = strip(d); return serialize(rest); };
+  if (bare(file) !== bare(fresh)) {
+    out.push({ at: 'scan', message: 'the map\'s scanner fields differ from a scan of this tree: a field was changed by hand, or the tree changed since (scan again first)' });
+  }
+  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));
+    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}` });
+  return out;
+}