crewforth 3.4.0 → 3.5.0-rc.1

package/kit/eval/doctor.sh

@@ -125,6 +125,7 @@ _mt() {
       '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 has no .claude/settings.json — a Claude Code session resumed there runs none of Crewforth's hooks (entering it with the EnterWorktree tool copies .claude/ in; otherwise copy it yourself)") s="%s worktree'sinde .claude/settings.json yok — orada sürdürülen bir Claude Code oturumu Crewforth'un hiçbir hook'unu koşmaz (EnterWorktree aracıyla girilince .claude/ oraya kopyalanır; yoksa kendiniz kopyalayın)" ;;
       "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)" ;;
       "fix the syntax by hand — restoring Crewforth's file would drop any hooks you added") s="sözdizimini elle düzeltin — Crewforth'un dosyasını geri yüklemek eklediğiniz hook'ları siler" ;;
       'settings.json wires hooks through the %s placeholder — on Windows its separators are stripped before bash runs, so NO hook launches and every gate is silently absent') s="settings.json hook'ları %s yer tutucusuyla bağlıyor — Windows'ta ayırıcılar bash çalışmadan silinir, bu yüzden HİÇBİR hook başlamaz ve bütün kapılar sessizce yok olur" ;;
@@ -153,6 +154,13 @@ _mt() {
       'CLAUDE.md (or a doc it references) names auto-delegated agent(s) that no installed agent matches — delegation to them silently fails') s='CLAUDE.md (ya da başvurduğu bir belge) kurulu hiçbir ajanla eşleşmeyen, otomatik devredilen ajan(lar) anıyor — onlara devretmek sessizce başarısız olur' ;;
       'rename each bare reference to its `crew-` id:') s='her çıplak anmayı `crew-` kimliğiyle değiştirin:' ;;
       'CLAUDE.md (or a referenced doc) names pull-only agent(s) by their old bare id — invoked explicitly, so delegation still works; rename for consistency:%s') s='CLAUDE.md (ya da başvurduğu bir belge) yalnız açıkça çağrılan ajan(lar)ı eski çıplak kimliğiyle anıyor — açıkça çağrıldıkları için devretme yine çalışır; tutarlılık için yeniden adlandırın:%s' ;;
+      'CLAUDE.md imports file(s) that do not exist — they load nothing, silently:%s') s='CLAUDE.md var olmayan dosya(lar)ı içe aktarıyor — hiçbir şey yüklenmiyor ve bu söylenmiyor:%s' ;;
+      'CLAUDE.md points at path(s) that do not exist (moved or deleted?):%s') s='CLAUDE.md var olmayan yol(lar)ı gösteriyor (taşındı ya da silindi mi?):%s' ;;
+      'set in this environment, read by no Crewforth file (a typo?):%s — it changes nothing') s="bu ortamda ayarlı ama hiçbir Crewforth dosyası okumuyor (yazım hatası mı?):%s — hiçbir şeyi değiştirmiyor" ;;
+      'Crewforth switch(es) that take a whole number set to something else:%s — a hook may ignore it and use its default') s='tam sayı bekleyen Crewforth anahtar(lar)ı başka bir şeye ayarlı:%s — hook onu yok sayıp varsayılanını kullanabilir' ;;
+      'CLAUDE.md line(s)%s read as loosening a §4 rule (approval, review or hooks) — a project CLAUDE.md can tighten §4, never loosen it, and the gates still apply; reword them so the model and the gates agree') s="CLAUDE.md satır(lar)ı%s bir §4 kuralını (onay, review ya da hook) gevşetiyor gibi okunuyor — proje CLAUDE.md'si §4'ü sıkılaştırabilir, asla gevşetemez, kapılar yine işler; model ile kapılar aynı şeyi söylesin diye bu satırları yeniden yazın" ;;
+      '%s points at path(s) that do not exist (moved or deleted?):%s') s='%s var olmayan yol(lar)ı gösteriyor (taşındı ya da silindi mi?):%s' ;;
+      'every import and file path in CLAUDE.md resolves') s="CLAUDE.md'deki her içe aktarma ve dosya yolu çözülüyor" ;;
       'agent references resolve to installed agents (CLAUDE.md + referenced docs)') s='ajan anmaları kurulu ajanlara çözülüyor (CLAUDE.md ve başvurduğu belgeler)' ;;
       'CLAUDE.md missing — .claude/DISCIPLINE.md is never loaded (routing / DoD / session rules absent)') s='CLAUDE.md yok — .claude/DISCIPLINE.md hiç yüklenmiyor (yönlendirme / DoD / oturum kuralları yok)' ;;
       'create CLAUDE.md with this as its own line: @.claude/DISCIPLINE.md') s="CLAUDE.md'yi oluşturun ve şunu ayrı bir satır olarak yazın: @.claude/DISCIPLINE.md" ;;
@@ -189,6 +197,9 @@ _mt() {
       'CLAUDE.md project section is still the template (placeholders left in)') s='CLAUDE.md proje bölümü hâlâ şablon (yer tutucular duruyor)' ;;
       'fill in Project / Stack / Project skills — agents read the stack from there') s='Project / Stack / Project skills bölümlerini doldurun — ajanlar yığını oradan okur' ;;
       'CLAUDE.md project section is filled in') s='CLAUDE.md proje bölümü doldurulmuş' ;;
+      'quality analysis recorded: %s') s='kalite analizi kayıtlı: %s' ;;
+      'CLAUDE.md names no quality analysis (## Stack → Quality analysis: %s) — the quality gate cannot tell a skipped analysis from a declined one') s='CLAUDE.md kalite analizi belirtmiyor (## Stack → Quality analysis: %s) — kalite kapısı atlanmış analizi reddedilmiş olandan ayıramıyor' ;;
+      'add "Quality analysis: sonarqube-local" (or sonarqube-server, or declined) under ## Stack; sonarqube-check stands a local server up') s='## Stack altına "Quality analysis: sonarqube-local" (ya da sonarqube-server, ya da declined) ekleyin; sonarqube-check yerel sunucuyu kurar' ;;
       "%s project-specific skill(s) alongside Crewforth's") s="Crewforth'unkilerin yanında %s projeye özel skill" ;;
       "no project-specific skill — every skill installed here ships with Crewforth") s="projeye özel skill yok — burada kurulu her skill Crewforth ile geliyor" ;;
       "no project-specific skill — %s, which CLAUDE.md lists under Project skills, ships with Crewforth") s="projeye özel skill yok — CLAUDE.md'nin Project skills altında saydığı %s Crewforth ile geliyor" ;;
@@ -205,6 +216,18 @@ _mt() {
       're-read it against the code and update Stack / Project skills; keep the @.claude/DISCIPLINE.md line and your own rule sections as they are') s='kodla karşılaştırarak yeniden okuyun ve Stack / Project skills bölümlerini güncelleyin; @.claude/DISCIPLINE.md satırını ve kendi kural bölümlerinizi olduğu gibi bırakın' ;;
       'freshness signal skipped (cannot read CLAUDE.md mtime on this platform)') s="güncellik sinyali atlandı (bu platformda CLAUDE.md'nin değişme zamanı okunamıyor)" ;;
       '  → readiness %s/%s') s='  → hazırlık %s/%s' ;;
+      'hook injection every turn (UserPromptSubmit): %s bytes, ~%s tokens (estimate: bytes/4), %s hook(s) run') s="hook enjeksiyonu her turda (UserPromptSubmit): %s bayt, ~%s token (tahmin: bayt/4), %s hook çalıştı" ;;
+      'hook injection each session start (SessionStart): %s bytes, ~%s tokens (estimate: bytes/4), %s hook(s) run') s="hook enjeksiyonu her oturum başında (SessionStart): %s bayt, ~%s token (tahmin: bayt/4), %s hook çalıştı" ;;
+      '%s (%s): %s bytes') s='%s (%s): %s bayt' ;;
+      '%s (%s): 0 bytes for this fixture') s='%s (%s): bu fixture için 0 bayt' ;;
+      'not measured: %s (%s) — %s') s='ölçülmedi: %s (%s) — %s' ;;
+      'writes .claude/state/crew-critical-paths.auto in the project') s="projede .claude/state/crew-critical-paths.auto dosyasını yazıyor" ;;
+      'writes .claude/.state/update-asked (it would silence the real update question) and starts a network check') s="projede .claude/.state/update-asked dosyasını yazıyor (gerçek güncelleme sorusunu susturur) ve bir ağ denetimi başlatıyor" ;;
+      'its scratch folder is inside a git repository, where it would empty a recorded approval') s="geçici klasörü bir git deposunun içinde; orada kayıtlı bir onayı boşaltırdı" ;;
+      'the script is not in .claude/hooks') s=".claude/hooks içinde betik yok" ;;
+      "not one of Crewforth's checked hooks, so what it writes is unknown") s="Crewforth'un denetlenmiş hook'larından değil; ne yazdığı bilinmiyor" ;;
+      'a floor for one fixture (prompt: %s; a new session), not a maximum: a hook that speaks only for some prompts or states says nothing here') s='tek bir fixture için alt sınır (istem: %s; yeni oturum), üst sınır değil: yalnız bazı istemlerde ya da durumlarda konuşan bir hook burada hiçbir şey söylemez' ;;
+      'hook injection NOT MEASURED — the measurement printed no totals (eval/lib/hook-inject.sh)') s='hook enjeksiyonu ÖLÇÜLMEDİ — ölçüm toplam basmadı (eval/lib/hook-inject.sh)' ;;
       'npx crewforth adopt') ;;   # identifier, printed as is
       'chmod +x .claude/hooks/*.sh .claude/hooks/pre-commit .claude/hooks/commit-msg') ;;   # identifier, printed as is
       'git config core.hooksPath .claude/hooks') ;;   # identifier, printed as is
@@ -450,7 +473,12 @@ if [ -f .claude/VERSION ] && git rev-parse --git-dir >/dev/null 2>&1; then
   _wv0="$(head -1 .claude/VERSION 2>/dev/null | tr -cd '0-9A-Za-z.-')"; _wt0="$(git rev-parse --show-toplevel 2>/dev/null)"
   while IFS= read -r _wl; do
     case "$_wl" in "worktree "*) _wp="${_wl#worktree }" ;; *) continue ;; esac
-    [ "$_wp" != "$_wt0" ] && [ -f "$_wp/.claude/VERSION" ] || continue
+    [ "$_wp" != "$_wt0" ] || continue
+    # A linked worktree with no settings.json loads no project hook in a session resumed there (measured, see
+    # worktree-provision.sh). One Claude Code makes under .claude/worktrees/ still runs this checkout's hooks.
+    case "$_wp" in "$_wt0"/.claude/worktrees/*) ;; *)
+      [ -d "$_wp" ] && [ ! -f "$_wp/.claude/settings.json" ] && warn "worktree %s has no .claude/settings.json — a Claude Code session resumed there runs none of Crewforth's hooks (entering it with the EnterWorktree tool copies .claude/ in; otherwise copy it yourself)" "$_wp" ;; esac
+    [ -f "$_wp/.claude/VERSION" ] || continue
     _wv="$(head -1 "$_wp/.claude/VERSION" 2>/dev/null | tr -cd '0-9A-Za-z.-')"
     [ "$_wv" = "$_wv0" ] || warn "worktree %s carries Crewforth %s, this one %s — a session there runs that version's gates and approval path (update Crewforth there)" "$_wp" "${_wv:-?}" "$_wv0"
   done <<EOF_WT
@@ -512,6 +540,56 @@ EOF_SLA
   fi
 fi
 
+# 4c) Per-turn hook injection. What the hooks on UserPromptSubmit (every turn) and SessionStart (each start, resume,
+#     clear, compact) add to the context, in bytes: eval/lib/hook-inject.sh runs each one on a fixture payload with a
+#     throwaway HOME/TMPDIR and a session id no real session has, and skips, by name, a hook it cannot run without a
+#     lasting write. A FLOOR for that fixture, not a maximum: a hook that speaks only for some prompts or states says
+#     nothing here, and Claude Code's own framing around each injection is not counted. Tokens are bytes/4, an
+#     estimate, not a tokenizer count. Advisory, never a failure.
+_HI="$_DOC_LIB/hook-inject.sh"; [ -f "$_HI" ] || _HI=.claude/eval/lib/hook-inject.sh
+if [ -f .claude/settings.json ] && [ -f "$_HI" ]; then
+  _hio="$(bash "$_HI" . 2>/dev/null)"
+  _hip=""; _hiu=""; _his=""; _hil=""
+  while IFS=$'\t' read -r _k _e _h _b _r; do
+    case "$_k" in
+      prompt) _hip="$_e" ;;
+      total) case "$_e" in UserPromptSubmit) _hiu="$_h $_b" ;; *) _his="$_h $_b" ;; esac ;;
+      run) _hil="$_hil$_e	$_h	$_b
+" ;;
+      skip) case "$_b" in
+              writes-state)   _mt "writes .claude/state/crew-critical-paths.auto in the project" ;;
+              writes-update)  _mt "writes .claude/.state/update-asked (it would silence the real update question) and starts a network check" ;;
+              scratch-in-repo) _mt "its scratch folder is inside a git repository, where it would empty a recorded approval" ;;
+              missing)        _mt "the script is not in .claude/hooks" ;;
+              *)              _mt "not one of Crewforth's checked hooks, so what it writes is unknown" ;;
+            esac
+            _hil="$_hil$_e	$_h	!$_M
+" ;;
+    esac
+  done <<EOF_HI
+$_hio
+EOF_HI
+  if [ -n "$_hiu" ] && [ -n "$_his" ]; then
+    read -r _ub _un <<< "$_hiu"; read -r _sb _sn <<< "$_his"
+    ok "hook injection every turn (UserPromptSubmit): %s bytes, ~%s tokens (estimate: bytes/4), %s hook(s) run" "$_ub" "$((_ub / 4))" "$_un"
+    ok "hook injection each session start (SessionStart): %s bytes, ~%s tokens (estimate: bytes/4), %s hook(s) run" "$_sb" "$((_sb / 4))" "$_sn"
+    while IFS=$'\t' read -r _e _h _v; do
+      [ -n "$_h" ] || continue
+      case "$_v" in
+        !*) _mt "not measured: %s (%s) — %s" "$_h" "$_e" "${_v#!}" ;;
+        0)  _mt "%s (%s): 0 bytes for this fixture" "$_h" "$_e" ;;
+        *)  _mt "%s (%s): %s bytes" "$_h" "$_e" "$_v" ;;
+      esac
+      echo "     ↳ $_M"
+    done <<EOF_HL
+$_hil
+EOF_HL
+    _mt "a floor for one fixture (prompt: %s; a new session), not a maximum: a hook that speaks only for some prompts or states says nothing here" "$_hip"; echo "     ↳ $_M"
+  else
+    skip "hook injection NOT MEASURED — the measurement printed no totals (eval/lib/hook-inject.sh)"
+  fi
+fi
+
 # 4b) Is delegation itself switched off? The documented way to stop Claude using ANY subagent is to deny the `Agent`
 #     tool in permissions.deny. A project that does that keeps twelve agents on disk that can never run, and the only
 #     symptom is that every task quietly happens on the main thread — which reads as "Crewforth does nothing" rather
@@ -637,6 +715,94 @@ if [ -f .claude/DISCIPLINE.md ]; then
   fi
 fi
 
+# 6a) Pointers in ./CLAUDE.md that lead nowhere. An `@path` import whose file is gone loads nothing and says nothing;
+#     a backticked path to a file that was moved or deleted sends the model to read what is not there. Imports are read
+#     where Claude Code reads them (its memory docs: `@` anywhere in the file, not inside a code span or block):
+#     a line of its own is always one; inside a sentence only a word shaped like a file (an extension), so `@types/node`
+#     or `@agent-x` is not mistaken for one. `~/` and absolute paths live outside the repository and are not judged,
+#     nor is a path with an escaped space. A backticked path counts when it is shaped like one (a `/`, an extension, no
+#     placeholder, glob or space); a `:42` or `#L10` after it is a location in the file, not part of its name. An
+#     example path in prose that is shaped like a real one is still named: doctor cannot tell an example from a pointer.
+#     Nested instruction files (a CLAUDE.md or AGENTS.md below the root, and an AGENTS.md at it) are read the same
+#     way: Claude Code loads a subdirectory's CLAUDE.md when it works there, and AGENTS.md is the file other tools
+#     read. A path in one resolves against its own folder first, then the root. Found by find, not git ls-files: an
+#     install gitignores CLAUDE.md, and the pattern hides the nested ones too. Dependency and build folders are not
+#     walked, and at most 20 files are read, so a monorepo does not make the doctor slow. Information only.
+# _ptrs FILE BASE: the imports and backticked paths in FILE that resolve neither under BASE nor at the root.
+_ptrs() {
+  _imp=""; _btp=""; local _fen=0 _l _r _p _t _own _w _ws _b="$2"
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    _l="${_l%$'\r'}"
+    case "$_l" in '```'*|'~~~'*) _fen=$((1-_fen)); continue ;; esac
+    [ "$_fen" = 1 ] && continue
+    # Backticked spans: collected as path candidates, and removed from the text the imports are read in.
+    _r="$_l"; _p=""
+    while case "$_r" in *'`'*'`'*) true ;; *) false ;; esac; do
+      _p="$_p ${_r%%\`*}"; _r="${_r#*\`}"; _t="${_r%%\`*}"; _r="${_r#*\`}"
+      _t="${_t%%#*}"; case "$_t" in *:[0-9]*) _t="${_t%%:[0-9]*}" ;; esac
+      case "$_t" in *[[:space:]\<\>\*\{\}\$\|]*|'~'*|@*|/*|http*|-*|*://*) continue ;; */*.[A-Za-z]*) ;; *) continue ;; esac
+      _t="${_t#./}"; [ -e "$_b/$_t" ] || [ -e "$_t" ] || case "$_btp" in *" $_t"*) ;; *) _btp="$_btp $_t" ;; esac
+    done
+    _p="$_p $_r"
+    case "$_l" in @*) _own=1 ;; *) _own=0 ;; esac
+    read -r -a _ws <<< "$_p"
+    for _w in "${_ws[@]+"${_ws[@]}"}"; do
+      case "$_w" in @?*) ;; *) continue ;; esac
+      _t="${_w#@}"; while case "$_t" in *[.,\;:\)\]]) true ;; *) false ;; esac; do _t="${_t%?}"; done
+      case "$_t" in ''|'~/'*|/*|*\\*) continue ;; esac
+      [ "$_own" = 1 ] || case "$_t" in *.[A-Za-z]*) ;; *) continue ;; esac
+      _own=0
+      [ -e "$_b/$_t" ] || case "$_imp" in *" @$_t"*) ;; *) _imp="$_imp @$_t" ;; esac
+    done
+  done < "$1"
+  # A path written relative to a sub-project (`services/x.py` for backend/app/services/x.py) is not missing: one
+  # `git ls-files`, asked only when something looked missing, and a tracked file that ends with the path resolves it.
+  if [ -n "$_btp" ] && [ -n "${_ls:=$(git ls-files 2>/dev/null)}" ]; then
+    local _nl=$'\n' _k=""
+    for _t in $_btp; do case "$_nl$_ls$_nl" in *"/$_t$_nl"*|*"$_nl$_t$_nl"*) ;; *) _k="$_k $_t" ;; esac; done
+    _btp="$_k"
+  fi
+}
+_ls=""
+if [ -f CLAUDE.md ]; then
+  _ptrs CLAUDE.md .
+  [ -n "$_imp" ] && warn "CLAUDE.md imports file(s) that do not exist — they load nothing, silently:%s" "$_imp"
+  [ -n "$_btp" ] && warn "CLAUDE.md points at path(s) that do not exist (moved or deleted?):%s" "$_btp"
+  [ -z "$_imp$_btp" ] && ok "every import and file path in CLAUDE.md resolves"
+fi
+_nst=0
+while IFS= read -r _nf; do
+  _nf="${_nf#./}"; [ "$_nf" = CLAUDE.md ] && continue
+  _nst=$((_nst+1)); [ "$_nst" -gt 20 ] && break
+  _ptrs "$_nf" "$(dirname "$_nf")"
+  [ -n "$_imp$_btp" ] && warn "%s points at path(s) that do not exist (moved or deleted?):%s" "$_nf" "$_imp$_btp"
+done < <(find . -maxdepth 6 \( -name .git -o -name .claude -o -name node_modules -o -name vendor -o -name dist \
+           -o -name build -o -name target -o -name .venv -o -name venv -o -name Pods \) -prune \
+           -o \( -name CLAUDE.md -o -name AGENTS.md \) -type f -print 2>/dev/null | LC_ALL=C sort)
+
+# 6b) A line in ./CLAUDE.md that reads as loosening §4. The discipline says a project CLAUDE.md can tighten §4, never
+#     loosen it, and the gates hold either way; but a line like "no need to ask before committing" tells the model
+#     the opposite of what the gate will do, and the session then argues with the gate. Information only, and a
+#     phrase list, not a judge: a loosening phrase on a line about commits, pushes, reviews or hooks, with no
+#     "never", "do not", "don't" or "must not" before it. Code fences and the @import line are not read.
+if [ -f CLAUDE.md ]; then
+  _lz="$(LC_ALL=C awk '
+    /^[[:space:]]*(```|~~~)/ { f = !f; next }
+    f || /^@/ { next }
+    { l = tolower($0) }
+    l !~ /commit|push|review|hook|verify|approv|force|reset/ { next }
+    {
+      n = split("no need to ask|no need for approval|no approval needed|without asking|without approval|without confirmation|skip the review|skip review|skip the hook|auto-commit|autocommit|commit directly|push directly|commit freely|push freely|you may commit|you may push|use --no-verify|--no-verify is fine|--no-verify is ok|force-push is fine|force push is fine", ph, "|")
+      for (i = 1; i <= n; i++) {
+        p = index(l, ph[i]); if (!p) continue
+        pre = substr(l, 1, p - 1)
+        if (pre ~ /never|do not|don.t|must not|not allowed|forbidden/) continue
+        printf " %d", NR; break
+      }
+    }' CLAUDE.md 2>/dev/null)"
+  [ -n "$_lz" ] && warn "CLAUDE.md line(s)%s read as loosening a §4 rule (approval, review or hooks) — a project CLAUDE.md can tighten §4, never loosen it, and the gates still apply; reword them so the model and the gates agree" "$_lz"
+fi
+
 # 8b) The shell matcher. Claude Code's hooks reference is explicit: inspect shell commands with
 #     `Bash|PowerShell`, because wherever the PowerShell tool is enabled it IS the shell — and it is on by
 #     default for claude.ai and Console accounts on Windows. An install from before 2.5.0 watches only `Bash`,
@@ -858,6 +1024,27 @@ fi
 _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}"
 
+# 9f) Crewforth's own switches, as set in this environment. A CREW_ variable no Crewforth file reads is almost always
+#     a typo (a misspelt routing switch set to off switches nothing off, and nothing says so), and a switch that
+#     takes a number set to something else may be ignored for its default without a word. The names are read from the installed files
+#     themselves, so the list cannot go stale; a value is judged only for names that end like a number (_MAX, _MIN,
+#     _PCT, _N, _TIMEOUT, _AGE, _BYTES, _CHARS, _TURNS, _TOOLS, _ERRORS, _TOLERANCE). Information only.
+# Read where this doctor runs from too (its own eval/ and hooks/ beside it): a suite that drives it sets names of its own.
+_kd="${_DOC_LIB:+${_DOC_LIB%/lib}}"
+_kn="$(grep -rhoE 'CREW_[A-Z0-9_]+' .claude/hooks .claude/eval .claude/skills .claude/studio ${_kd:+"$_kd" "${_kd%/eval}/hooks"} 2>/dev/null | LC_ALL=C sort -u)"
+if [ -n "$_kn" ]; then
+  _nl=$'\n'; _uk=""; _nv=""
+  while IFS='=' read -r _vn _vv; do
+    case "$_vn" in CREW_[A-Z0-9_]*) ;; *) continue ;; esac
+    case "$_nl$_kn$_nl" in *"$_nl$_vn$_nl"*) ;; *) _uk="$_uk $_vn"; continue ;; esac
+    case "$_vn" in *_MAX|*_MIN|*_PCT|*_N|*_TIMEOUT|*_AGE|*_BYTES|*_CHARS|*_TURNS|*_TOOLS|*_ERRORS|*_TOLERANCE|*_MAX_*|*_MIN_*)
+      case "$_vv" in ''|*[!0-9]*) _nv="$_nv $_vn=$_vv" ;; esac ;;
+    esac
+  done < <(env 2>/dev/null | LC_ALL=C sort)
+  [ -n "$_uk" ] && warn "set in this environment, read by no Crewforth file (a typo?):%s — it changes nothing" "$_uk"
+  [ -n "$_nv" ] && warn "Crewforth switch(es) that take a whole number set to something else:%s — a hook may ignore it and use its default" "$_nv"
+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.
@@ -906,6 +1093,19 @@ if [ -f CLAUDE.md ]; then
     gap "CLAUDE.md project section is still the template (placeholders left in)" \
         "fill in Project / Stack / Project skills — agents read the stack from there"
   else rdy "CLAUDE.md project section is filled in"; fi
+  # R1b) Which quality analysis the DoD's quality gate runs. It was written six times as "(if SonarQube is in use)",
+  #      and on a project with no server that condition was simply false: one project measured 0 analyses in its
+  #      first 8 days. The answer is now a line in ## Stack; a missing or empty one is said here, by value.
+  QA="<missing>"
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    case "$_l" in 'Quality analysis:'*) _l="${_l#Quality analysis:}"; _l="${_l%$'\r'}"; _l="${_l# }"; QA="${_l:-<empty>}"; break ;; esac
+  done < CLAUDE.md
+  case "$QA" in '<missing>'|'<empty>') ;; '<'*) QA='<template>' ;; esac
+  case "$QA" in
+    sonarqube-local*|sonarqube-server*|declined*) rdy "quality analysis recorded: %s" "${QA%% *}" ;;
+    *) gap "CLAUDE.md names no quality analysis (## Stack → Quality analysis: %s) — the quality gate cannot tell a skipped analysis from a declined one" \
+           'add "Quality analysis: sonarqube-local" (or sonarqube-server, or declined) under ## Stack; sonarqube-check stands a local server up' "${QA%% *}" ;;
+  esac
 fi
 
 # R2) A project-specific skill — Crewforth ships the generic 'how's; the domain ones (payment-contract,

package/kit/eval/gate-report.sh

@@ -69,6 +69,30 @@ awk '
 sort -u "$TMP/inv" -o "$TMP/inv"
 NRULES=$(grep -c . "$TMP/inv" 2>/dev/null); NRULES=$(( ${NRULES:-0} + 0 ))
 
+# ---- the exceptions a project wrote down. A gate with many exceptions is a rule the project disagrees with, and that
+# is worth an ADR or a change to the rule rather than one more line. Counted per rule: a `rule:<name>` entry, and an
+# exact pattern line, credited to the rule heading it sits under in floor-blocklist.txt; a `path:` entry names no rule.
+allowlists(){
+  local fa=./.floor-allowlist.txt pa=./.private-allowlist.txt fb="$HOOKS/floor-blocklist.txt"
+  [ -f "$fa" ] || [ -f "$pa" ] || return 0
+  echo "  exceptions written down:"
+  if [ -f "$fa" ]; then
+    awk -v fb="$fb" '
+      FILENAME == fb { sub(/\r$/, ""); if ($0 ~ /^# rule: /) { r = substr($0, 9); next } if ($0 ~ /^#/ || $0 == "") next; rule[$0] = r; next }
+      { sub(/\r$/, ""); if ($0 ~ /^#/ || $0 == "") next
+        e = $0; i = index(e, " # "); if (i) e = substr(e, 1, i - 1); sub(/[[:space:]]+$/, "", e); n++
+        if (e ~ /^rule:/) c[substr(e, 6)]++; else if (e !~ /^path:/ && (e in rule)) c[rule[e]]++ }
+      END { printf "    .floor-allowlist.txt    %d entr%s\n", n, (n == 1 ? "y" : "ies")
+            for (k in c) if (c[k] >= 3) printf "    \342\232\240  rule %s is allowlisted %d times: write an ADR or change the rule\n", k, c[k] }
+    ' "$fb" "$fa" 2>/dev/null
+  fi
+  if [ -f "$pa" ]; then
+    local np; np="$(grep -cvE '^[[:space:]]*(#|$)' "$pa" 2>/dev/null)"; np="${np:-0}"
+    printf '    .private-allowlist.txt  %s entr%s\n' "$np" "$([ "$np" = 1 ] && echo y || echo ies)"
+  fi
+  echo
+}
+
 # ---- no log. Since 2.5.0 recording is ON by default, so the absence of a file means one of two DIFFERENT
 # things and the report must not blur them:
 #   .claude/ exists  -> recording had somewhere to go and nothing has tripped a gate yet. That is a real
@@ -81,6 +105,7 @@ if [ -z "$LOG" ] || [ ! -f "$LOG" ]; then
       echo "  ✅ no gate has fired in this project yet — $NRULES rules wired, recording on,"
       echo "     nothing has tripped one. (Recording writes .claude/gate-log.tsv, which is gitignored;"
       echo "     rule names and verdicts only, never the command — CREW_GATE_LOG_CMD=1 adds it for debugging.)"
+      echo; allowlists
     fi
     exit 0
   fi
@@ -137,3 +162,6 @@ echo
 echo "  Not observed is NOT dead. It means one of: nobody attempted it, the model never reached for that"
 echo "  command, or the rule cannot match. Only the first two are healthy, and this report cannot tell them"
 echo "  apart — smoke-test is what proves a rule CAN fire; this shows whether anything tripped it."
+
+echo
+allowlists

package/kit/eval/golden-holdout.txt

@@ -51,3 +51,5 @@ we need to put this build on the server tonight|deploy
 # in the same change — so these are weaker held-out evidence than the rows above.
 empty repo, nobody has picked a language or framework for the api yet|backend-architecture
 we cannot agree whether this service should be layered or split per feature|backend-architecture
+# P14 row for the docs-writer "diagram" trigger: same honesty note, written in the change that added it.
+sketch a diagram of how the services call each other|docs-writer

package/kit/eval/golden-routing.txt

@@ -36,6 +36,8 @@ flutter ekranı ekle|crew-frontend-expert
 add a SwiftUI view for the profile|crew-frontend-expert
 build a Jetpack Compose screen for settings|crew-frontend-expert
 run an OWASP check and a full security scan|crew-security-expert
+check the login flow for session fixation|crew-security-expert
+the oauth redirect accepts any callback url|crew-security-expert
 we need a kvkk privacy audit|crew-privacy-agent
 commit the changes|crew-commit-agent
 run tests and give me a coverage report|crew-test-expert
@@ -50,7 +52,9 @@ check i18n for any missing translation|i18n-integrity
 run the sonarqube quality gate|sonarqube-check
 prepare a handoff with the current session state|handoff
 add a structured log with a correlation id|observability
+add metrics to the checkout service|observability
 update the README and write the API docs|docs-writer
+draw an architecture diagram for the README|docs-writer
 run an accessibility audit and check WCAG|a11y
 handle api versioning with an openapi contract|api-design
 the page is slow, do a performance optimization|performance
@@ -62,6 +66,7 @@ keep going until the tests pass and the review is clean|iterate
 debug this and find the root cause of the intermittent bug|systematic-debugging
 improve the visual design — the spacing and typography look off|frontend-design
 build an MCP server to expose these tools to Claude|mcp-builder
+add an MCP tool to my agent|mcp-builder
 build a threat model and map the attack surface before we scan|threat-model
 set up an eval to measure output quality against a baseline|eval-grader
 
@@ -96,6 +101,7 @@ the settings screen needs a state management fix|frontend
 we need a consent flow before we store any of this|privacy-compliance
 let us step back and see what we missed this week|reflect
 scan for vulnerabilities in the auth flow|security-scan
+review our github actions security before we add pull_request_target|security-scan
 how do we split this into tasks with acceptance criteria|spec-planning
 are the tests green after that change|testing
 check for AI trace before the commit|trace-scan
@@ -140,6 +146,7 @@ the screen froze during the demo|!crew-frontend-expert
 fix the layout of this json file|!frontend-design
 design the database schema|!frontend-design
 read the model context and summarize it|!mcp-builder
+redirect the user to the dashboard after login|!crew-security-expert
 optimize the slow sql query performance|!systematic-debugging
 # `build` contains `ui`, and `UI` used to be a trigger, so a CI failure routed to the frontend expert. A wrong
 # route is worse than none: it looks like Crewforth worked. Fixed by word-bounded matching AND by retiring the
@@ -150,8 +157,10 @@ the docker build is broken in the pipeline|!crew-frontend-expert
 # session-context skill. A one-word trigger for a word that lives in two vocabularies is not a trigger.
 add a dark mode and a design token layer|!token-budget
 isolate this work in a git worktree before the parallel agents run|worktree
+remove the worktree once the experiment is done|worktree
 before I start, am I sure enough to implement this|confidence-check
 upgrade dependencies to current versions|dependency-upgrade
+land the open dependabot PRs|dependency-upgrade
 is this endpoint fast enough on the hot path|crew-performance-expert
 who is working on which sprint item right now|teamboard
 audit this against ccpa and lgpd for data protection regulation|crew-privacy-agent
@@ -237,3 +246,11 @@ fix the failing unit test in the payment module|!crew-docs-agent
 # Positive twins of the read-only prompts smoke-test pins silent (route-hint.sh): the same README, an action verb.
 update the README with the notes at the end|crew-docs-agent
 tuval README'nin sonundaki notları güncelle|crew-docs-agent
+# Dependency added inside the request (the trigger is the diff, §4.7; these catch the request that names it), each with its negative twin.
+the lockfile changed after the merge, check the new dependency|dependency-audit
+the build changed after the merge, check the new module|!dependency-audit
+axios paketini ekle ve sürümünü sabitle|dependency-audit
+axios isteğinin zaman aşımını düzelt|!dependency-audit
+# WCAG 2.2 criteria a 2.1 checklist misses.
+make the buttons at least 24 pixels so the target size passes|a11y
+the focus is hidden under the sticky header when tabbing|a11y

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

@@ -0,0 +1,77 @@
+// contracts.mjs — the rules a project writes down for its own code, and what holds them to the tree.
+//
+// .crewforth/contracts.md is written by the team (or by /crew-map when the user names a rule), never by the scanner,
+// so a rescan cannot drop it. One section per contract:
+//
+//   ## totals-round-once
+//   Order totals are rounded once, at the end, so a split order adds up to the same cents as the whole.
+//   - Core/Orders.cs:Total
+//   - Core/Invoices.cs:Sum
+//
+// The heading is the key (kebab case, unique in the file); the first paragraph is the rule, one or two sentences;
+// each `- path:symbol` line is where the rule lives: a file of the project and a name that appears in it as a word.
+// A symbol, not a line number: a rule outlives the edits that move it. Text before the first heading is free.
+//
+// Who reads it: map-stale.sh tells an agent, the moment it edits a cited file, which rules live there; at Stop it
+// tells the user which keys the session's edits touched; crew-review-agent gives a verdict per touched key. The
+// validator below (scan.mjs --contracts, and --validate when the file exists) keeps every cite pointing at code.
+
+export const CONTRACTS_FILE = '.crewforth/contracts.md';
+const KEY = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SYMBOL = /^[A-Za-z_$/][\w$./-]*$/;
+const MAX_RULE = 300;
+const MAX_KEY = 60;
+
+/** Parse the file: [{ key, line, rule, cites: [{ path, symbol, line }] }] and the problems a parse alone can see. */
+export function parse(text) {
+  const out = []; const problems = [];
+  let cur = null; let para = null;
+  String(text).split('\n').forEach((raw, i) => {
+    const l = raw.replace(/\r$/, '');
+    const h = /^##\s+(.*?)\s*$/.exec(l);
+    if (h) { cur = { key: h[1], line: i + 1, rule: '', cites: [] }; out.push(cur); para = 'want'; return; }
+    if (!cur) return;
+    const c = /^\s*[-*]\s+(\S+)\s*$/.exec(l);
+    if (c) {
+      const at = c[1].lastIndexOf(':');
+      cur.cites.push({ path: at > 0 ? c[1].slice(0, at) : c[1], symbol: at > 0 ? c[1].slice(at + 1) : '', line: i + 1 });
+      if (para === 'in') para = 'done';
+      return;
+    }
+    if (!l.trim()) { if (para === 'in') para = 'done'; return; }
+    if (para === 'want') { cur.rule = l.trim(); para = 'in'; }
+    else if (para === 'in') cur.rule += ` ${l.trim()}`;
+    else problems.push({ at: `${cur.key}`, message: `line ${i + 1} is neither the rule nor a "- path:symbol" cite` });
+  });
+  return { contracts: out, problems };
+}
+
+const sentences = (t) => (String(t).trim().match(/[.!?](\s|$)/g) ?? []).length;
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Hold the file to the tree. `files` is the scanner's listing (a Set), `read(rel)` its reader ({ text } or null).
+ * Returns { contracts, problems: [{ at, message }] }; no problem means every rule is stated and every cite lands.
+ */
+export function validate(text, files, read) {
+  const { contracts, problems } = parse(text);
+  const seen = new Set();
+  for (const c of contracts) {
+    const at = c.key || `line ${c.line}`;
+    if (!KEY.test(c.key) || c.key.length > MAX_KEY) problems.push({ at, message: `the key is not kebab case (a-z, 0-9 and single dashes, ${MAX_KEY} characters at most)` });
+    if (seen.has(c.key)) problems.push({ at, message: 'the key is used twice: a review gives one verdict per key' });
+    seen.add(c.key);
+    if (!c.rule) problems.push({ at, message: 'states no rule: the first paragraph under the heading is the rule' });
+    else if (c.rule.length > MAX_RULE || sentences(c.rule) > 2) problems.push({ at, message: `the rule runs past two sentences or ${MAX_RULE} characters` });
+    if (!c.cites.length) problems.push({ at, message: 'cites nothing: a rule says where it lives with "- path:symbol"' });
+    for (const x of c.cites) {
+      const where = `${x.path}:${x.symbol}`;
+      if (!x.symbol || !SYMBOL.test(x.symbol) || /^\d+$/.test(x.symbol)) { problems.push({ at, message: `${where} names no symbol (a function, type, key or route that appears in the file, not a line number)` }); continue; }
+      if (x.path.startsWith('/') || /^[A-Za-z]:/.test(x.path) || x.path.split('/').includes('..') || !files.has(x.path)) { problems.push({ at, message: `${where}: ${x.path} is not a file of this project` }); continue; }
+      const src = read(x.path);
+      if (!src) { problems.push({ at, message: `${where}: ${x.path} could not be read` }); continue; }
+      if (!new RegExp(`(^|[^\\w$])${escape(x.symbol)}($|[^\\w$])`, 'm').test(src.text)) problems.push({ at, message: `${where}: ${x.symbol} does not appear in ${x.path} (renamed or moved?)` });
+    }
+  }
+  return { contracts, problems };
+}

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

@@ -1,7 +1,8 @@
 #!/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)
+#   bash crew-map.sh [--root DIR] [--stdout | --check | --validate] [--force]   the arguments and exit codes of
+#       scan.mjs (0, 1, 2); --force writes a rescan that would lose most of the map (it refuses with rc 1 otherwise)
 #       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

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

@@ -10,7 +10,7 @@
 
 import crypto from 'node:crypto';
 import { canon } from './surface.mjs';
-import { sortEv } from './project.mjs';
+import { sortEv, isTestModule } 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'];
@@ -85,6 +85,7 @@ export function detect(ctx) {
     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
+      if (isTestModule(m)) continue; // a test project is run by the test runner, never referenced
       out.push(finding('module-orphan', m.id, `No module references ${m.name}, and it has no entry point`, m.evidence, { module: m.id }));
     }
   }

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

@@ -24,8 +24,9 @@ export const LAYERS = ['ui', 'api', 'service', 'data', 'infra', 'tool', 'library
 /** The "file:line" a narrative of this node may cite. */
 export function citesOf(node) {
   const out = new Set();
-  // 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 : []))) {
+  // Its evidence, its entry point, what its README says about it and the WHY/HACK/FIXME lines in its code: every
+  // line the scan read for this node.
+  for (const e of [node?.evidence, node?.entryPoint?.evidence, node?.about?.evidence, node?.markers?.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;
@@ -67,6 +68,16 @@ export function strip(doc) {
   return { ...doc, nodes: (doc.nodes ?? []).map((n) => ({ ...n, narrative: null })), overview: null, tour: null };
 }
 
+/**
+ * What a later scan of the same tree must reproduce byte for byte: the document without what the model wrote, the
+ * commit it was scanned at, and how often each module changed. The last two move with every commit, the map's own
+ * included, so a committed map is not called stale for them.
+ */
+export function steady(doc) {
+  const { source, ...rest } = strip(doc);
+  return { ...rest, nodes: rest.nodes.map(({ commits, ...n }) => n) };
+}
+
 /** 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;
@@ -115,7 +126,7 @@ export function carry(old, fresh) {
  */
 export function validate(file, fresh, serialize) {
   const out = [];
-  const bare = (d) => { const { source, ...rest } = strip(d); return serialize(rest); };
+  const bare = (d) => serialize(steady(d));
   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)' });
   }