crewforth 0.0.1 → 3.0.0-rc.2

package/kit/eval/preflight.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+# Preflight — name the tools this machine is missing BEFORE they turn into a surprise mid-session.
+#
+# Why this exists. Crewforth is written to degrade rather than break: sha256sum -> shasum -> cksum for digests,
+# and so on. (It no longer needs jq or python at all — every JSON read and write is one bash/awk path on every
+# OS — so neither is reported here: a row for a tool nothing uses would send people to install it.) That is the right design, and it is also
+# why a missing tool never announces itself — the fallback runs, something is quietly worse, and the user finds
+# out later from a symptom that points somewhere else. A Windows Git Bash install with no jq and no python is
+# the normal case, not the exotic one, and it was where every surprise in this project came from.
+#
+# So: report, do not install. Nothing here writes to the machine or blocks a run. The user asked for exactly
+# that boundary — a scaffolding tool that silently installs software on someone's workstation is a worse problem
+# than the one it solves, and on a managed corporate machine it simply fails in a new way.
+#
+# Called from start.sh and adopt.sh (before the install summary) and from doctor.sh (so it stays re-runnable).
+#   bash preflight.sh            # human-readable report, always exit 0
+#   bash preflight.sh --quiet    # print only what is missing; exit 1 if any REQUIRED tool is absent
+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
+
+QUIET=0
+case "${1:-}" in --quiet|-q) QUIET=1 ;; esac
+# A machine-readable question, so a caller can branch on one tool without parsing
+# the display output or restating the rule. `--has node` answers with an exit
+# code and prints nothing. The rule it answers with is works(), the same one the
+# report uses — the version floor and the does-it-actually-run probe live in one
+# place, and a second copy could drift from it silently.
+HAS=""
+case "${1:-}" in --has) HAS="${2:-}" ;; esac
+
+B=""; D=""; R=""; YE=""; GR=""
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then B=$'\033[1m'; D=$'\033[2m'; R=$'\033[0m'; YE=$'\033[33m'; GR=$'\033[32m'; fi
+
+MISSING_REQ=""; MISSING_OPT=""
+
+have(){ command -v "$1" >/dev/null 2>&1; }
+# `have` answers "is it on PATH", which is the wrong question for an interpreter on Windows. Windows puts
+# %LOCALAPPDATA%\Microsoft\WindowsApps\python3 on PATH BY DEFAULT: the Microsoft Store redirector stub, which
+# passes `command -v`, writes "Python was not found" to stderr and exits 49. Measured on a stock Windows 11
+# desktop, this preflight printed "✓ jq or python → python3 · Everything Crewforth wants is here" on a machine
+# with no Python at all — and the settings merge that line is about cannot run there. So for the interpreters,
+# ask whether they RUN. Everything else is a plain binary where presence is the whole question.
+#
+# The probe always passes arguments. An ARGLESS run of that stub is the one that opens the Microsoft Store,
+# which is why doctor.sh warns against calling it unconditionally; `-c …` makes it print and exit instead.
+works(){
+  have "$1" || return 1
+  case "$1" in
+      # The panel needs 18+, and a name that resolves is not an interpreter that runs: the Windows Store ships a
+      # python3 that satisfies `command -v` and then exits 49. So run node, read the major it reports, and hold
+      # the floor. A node that cannot execute fails here rather than at first use.
+      node)              v="$("$1" -p 'process.versions.node.split(".")[0]' 2>/dev/null)" || return 1
+                         case "$v" in ''|*[!0-9]*) return 1 ;; esac
+                         [ "$v" -ge 18 ] ;;
+    *)                 return 0 ;;
+  esac
+}
+# printf's %-Ns pads by bytes, and a translated label ("sha256 aracı") is longer in bytes than in characters,
+# so its column came out one short. Count characters: drop UTF-8 continuation bytes under C, pad the rest.
+padr() {   # $1 = text, $2 = width; sets PADDED
+  local LC_ALL=C n
+  n="${1//[$'\200'-$'\277']/}"; n=$(( $2 - ${#n} ))
+  PADDED="$1"
+  while [ "$n" -gt 0 ]; do PADDED="$PADDED "; n=$((n-1)); done
+}
+# any_of "label" "why it matters" "fix hint" cmd...
+any_of(){
+  # label, why and fix are ENGLISH keys, translated here so no call site forks. A tool name passes through.
+  _mt "$1"; label="$_M"; _mt "$2"; why="$_M"; _mt "$3"; fix="$_M"; shift 3
+  found=""
+  for c in "$@"; do works "$c" && { found="$c"; break; }; done
+  if [ -n "$found" ]; then
+    [ "$QUIET" = 1 ] || { padr "$label" 22; printf '  %s✓%s %s %s%s%s\n' "$GR" "$R" "$PADDED" "$D" "$found" "$R"; }
+    return 0
+  fi
+  padr "$label" 22
+  printf '  %s✗%s %s %s\n' "$YE" "$R" "$PADDED" "$why"
+  _mt 'fix: '; printf '      %s%s%s%s\n' "$D" "$_M" "$fix" "$R"
+  return 1
+}
+
+  if [ -n "$HAS" ]; then
+    works "$HAS" && exit 0 || exit 1
+  fi
+
+# ---- CREW-I18N ------------------------------------------------------------------------------------------
+# This script prints during the install, so it speaks the installer's language. Same contract as start.sh:
+# the English string is the key, a missing translation prints English, and TOOL NAMES ARE NEVER TRANSLATED —
+# `bash`, `git`, `jq`, `node` are identifiers, not words. Only the prose around them is.
+case "${CREW_LANG:-}" in tr|en) ;; *)
+  _loc="${LC_ALL:-}"; [ -n "$_loc" ] || _loc="${LC_MESSAGES:-}"; [ -n "$_loc" ] || _loc="${LANG:-}"
+  case "$_loc" in tr*|TR*) CREW_LANG=tr ;; *) CREW_LANG=en ;; esac ;;
+esac
+# `_mt` writes into _M with printf -v: a `$(m …)` call site is a fork, ~50 ms each on Git Bash.
+m() { _mt "$@"; printf '%s' "$_M"; }
+_mt() {
+  # An empty key must still ASSIGN: bash 3.2's `printf -v _M ""` leaves _M holding the previous translation.
+  [ -n "${1:-}" ] || { _M=""; return 0; }
+  local s="$1"; shift
+  if [ "$CREW_LANG" = tr ]; then
+    case "$s" in
+      "Preflight — what this machine has") s='Ön kontrol — bu makinede neler var' ;;
+      "Missing REQUIRED:") s='Eksik ZORUNLU araçlar:' ;;
+      "— install these first.") s='— önce bunları kurun.' ;;
+      "All required tools present.") s='Zorunlu araçların hepsi kurulu.' ;;
+      "Optional gaps above are safe but worth closing.") s='Yukarıdaki isteğe bağlı eksikler sorun çıkarmaz ama gidermeye değer.' ;;
+      "Everything Crewforth needs is here.") s="Crewforth'un ihtiyaç duyduğu her şey kurulu." ;;
+      "is the panel only — every gate still holds without it.") s='yalnızca panel için gerekli — o olmadan da tüm kapılar çalışır.' ;;
+      "Or let Crewforth get one: %s") s='İsterseniz Crewforth sizin için indirebilir: %s' ;;
+      "fix: ") s='çözüm: ' ;;
+      "node 18+") s='node 18+' ;;
+      "sha256 tool") s='sha256 aracı' ;;
+      "all of Crewforth is bash") s="Crewforth'un tamamı bash ile yazıldı" ;;
+      "Windows: install Git for Windows (git-scm.com) and run Claude Code from Git Bash") s="Windows: Git for Windows'u kurun (git-scm.com) ve Claude Code'u Git Bash'ten çalıştırın" ;;
+      "context measurement, routing, doctor") s='bağlam ölçümü, yönlendirme ve doctor için' ;;
+      "Windows: ships with Git Bash · macOS: preinstalled · Linux: apt install gawk") s='Windows: Git Bash ile gelir · macOS: hazır gelir · Linux: apt install gawk' ;;
+      "the commit-time trace/secret gates are git hooks") s="commit anındaki iz ve gizli bilgi kapıları git hook'u olarak çalışır" ;;
+      "the Crewforth Studio panel (/crew-studio); the gates themselves are bash and do not need it") s='Crewforth Studio paneli (/crew-studio) için; kapılar bash ile çalışır, Node gerektirmez' ;;
+      "the skill-trust gate falls back to cksum (catches accidental edits, not crafted ones)") s="skill güven kapısı cksum'a düşer (kazara değişiklikleri yakalar, kasıtlı olanları yakalayamaz)" ;;
+      "Windows/Linux: coreutils (sha256sum) · macOS: shasum is preinstalled") s='Windows/Linux: coreutils (sha256sum) · macOS: shasum hazır gelir' ;;
+      "bash") ;;   # identifier, printed as is
+      "awk") ;;   # identifier, printed as is
+      "git") ;;   # identifier, printed as is
+      "nodejs.org · Windows: winget install OpenJS.NodeJS.LTS · macOS: brew install node · Linux: apt install nodejs") ;;   # identifier, printed as is
+      "git-scm.com · macOS: xcode-select --install · Linux: apt install git") ;;   # identifier, printed as is
+      # No row: the line prints in English. CREW_I18N_MISS (set by e2e case 18) collects every such key, so a
+      # missing translation is caught by NAME rather than guessed from which English words it happens to contain.
+      *) [ -n "${CREW_I18N_MISS:-}" ] && printf '%s\n' "$s" >> "$CREW_I18N_MISS" ;;
+    esac
+  fi
+  # shellcheck disable=SC2059
+  printf -v _M "$s" "$@"
+}
+# ---- /CREW-I18N -----------------------------------------------------------------------------------------
+
+[ "$QUIET" = 1 ] || { _mt 'Preflight — what this machine has'; printf '\n  %s%s%s\n' "$B" "$_M" "$R"; }
+
+# --- REQUIRED: without these Crewforth does not work at all -------------------------------------------------
+# Hooks are wired in SHELL form on purpose, and `bash` is resolved by the shell Claude Code already runs them
+# in — not off the Windows PATH. That distinction is not academic. On a Windows box checked during this work,
+# `where bash` answered `C:\Windows\System32\bash.exe`, which is not Git Bash at all: it is the WSL launcher,
+# living in a filesystem namespace where `C:\Repos\app` does not exist (`/mnt/c/Repos/app` does). A wiring that
+# spawns `bash` by PATH name would have run THAT, or failed outright where WSL is not installed — every gate
+# gone, with an error pointing nowhere near the cause. Hence shell form, and hence this note.
+any_of "bash" 'all of Crewforth is bash' \
+  'Windows: install Git for Windows (git-scm.com) and run Claude Code from Git Bash' bash || MISSING_REQ="$MISSING_REQ bash"
+any_of "awk" 'context measurement, routing, doctor' \
+  'Windows: ships with Git Bash · macOS: preinstalled · Linux: apt install gawk' awk gawk mawk || MISSING_REQ="$MISSING_REQ awk"
+any_of "git" 'the commit-time trace/secret gates are git hooks' \
+  "git-scm.com · macOS: xcode-select --install · Linux: apt install git" git || MISSING_REQ="$MISSING_REQ git"
+  # Node is required for the panel and for nothing else: every gate in Crewforth is bash, and they all hold on a
+  # machine that has never seen node. It sits in REQUIRED anyway, deliberately, because the panel now installs
+  # into every project, and a component that silently does not start on some machines is worse than one that
+  # says what it needs. The reason string names which half is affected, so the REQUIRED heading stays true.
+  any_of 'node 18+' 'the Crewforth Studio panel (/crew-studio); the gates themselves are bash and do not need it' \
+    "nodejs.org · Windows: winget install OpenJS.NodeJS.LTS · macOS: brew install node · Linux: apt install nodejs" \
+    node || MISSING_REQ="$MISSING_REQ node"
+
+# --- OPTIONAL: Crewforth falls back, but the fallback is worse in a way worth knowing about ------------------
+any_of 'sha256 tool' 'the skill-trust gate falls back to cksum (catches accidental edits, not crafted ones)' \
+  'Windows/Linux: coreutils (sha256sum) · macOS: shasum is preinstalled' sha256sum shasum || MISSING_OPT="$MISSING_OPT sha256"
+
+if [ -n "$MISSING_REQ" ]; then
+  _mt 'Missing REQUIRED:'; _a="$_M"; _mt '— install these first.'
+  printf '\n  %s%s%s%s %s\n' "$YE$B" "$_a" "$R" "$MISSING_REQ" "$_M"
+    case "$MISSING_REQ" in
+      # Which half is gone. "Crewforth will not work" is false when only node is missing: every gate is bash and
+      # still holds; what is lost is the panel.
+      *node*) _mt 'is the panel only — every gate still holds without it.'; printf '    %snode%s %s\n' "$B" "$R" "$_M"
+              # And it is not a dead end: Crewforth fetches a runtime for the panel itself, into one
+              # directory under $HOME, verified against the published checksum. It asks first.
+              printf '    %s\n' "$(m 'Or let Crewforth get one: %s' "${B}bash .claude/studio/ensure-node.sh --plan${R}")" ;;
+    esac
+elif [ -n "$MISSING_OPT" ]; then
+  [ "$QUIET" = 1 ] || { _mt 'All required tools present.'; _a="$_M"; _mt 'Optional gaps above are safe but worth closing.'
+                        printf '\n  %s%s%s %s\n' "$GR" "$_a" "$R" "$_M"; }
+else
+  [ "$QUIET" = 1 ] || { _mt 'Everything Crewforth needs is here.'; printf '\n  %s%s%s\n' "$GR" "$_M" "$R"; }
+fi
+
+# Report-only by design: a missing OPTIONAL tool never fails. `--quiet` exits non-zero only for REQUIRED gaps,
+# so a caller can branch on it without having to parse this output.
+[ "$QUIET" = 1 ] && [ -n "$MISSING_REQ" ] && exit 1
+exit 0

package/kit/eval/routing-eval.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# Behavioral eval: does a golden prompt route to the expected target via a trigger (deterministic)?
+# Does NOT run Claude Code; it statically proxies the routing correctness of the trigger design:
+#   1) Golden routing  — each example prompt must contain (as a substring) one trigger of its expected target.
+#   2) Agent collision  — two DIFFERENT agents must not share the same trigger phrase (routing ambiguity).
+# Turkish diacritics are normalized on both sides (guvenlik == güvenlik), so it is also robust for
+# users who type without diacritics. In a pruned install, a line whose target is not installed is SKIPPED.
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$HERE/.." && pwd)"
+AGENTS="$ROOT/agents"; SKILLS="$ROOT/skills"
+GOLD="$HERE/golden-routing.txt"
+FAIL=0; SKIP=0
+pass(){ echo "  ✅ $1"; }
+fail(){ echo "  ❌ $1"; FAIL=$((FAIL+1)); }
+skip(){ echo "  ⏭  $1"; SKIP=$((SKIP+1)); }
+
+# Turkish diacritics -> ascii, lowercase, then every run of non-alphanumerics becomes ONE space and the whole
+# string is space-padded. That padding is what makes the match word-bounded: a bare substring test routed "the
+# build fails on CI" to the frontend expert, because `build` contains `ui` and `UI` is one of its triggers.
+# Every short trigger has that failure mode (ui · api · e2e), and it points the wrong way — a CI failure sent to
+# the frontend agent is worse than no routing at all, because it looks like Crewforth worked.
+norm() {
+  printf '%s' "$1" | sed \
+    -e 's/Ç/c/g' -e 's/ç/c/g' -e 's/Ğ/g/g' -e 's/ğ/g/g' -e 's/İ/i/g' -e 's/ı/i/g' \
+    -e 's/Ö/o/g' -e 's/ö/o/g' -e 's/Ş/s/g' -e 's/ş/s/g' -e 's/Ü/u/g' -e 's/ü/u/g' \
+    | tr '[:upper:]' '[:lower:]' | sed -e 's/[^a-z0-9]\{1,\}/ /g' -e 's/^/ /' -e 's/$/ /'
+}
+
+triggers_of() {  # $1 = target name; prints its trigger phrases line by line (exit 1 if none)
+  local n="$1" f=""
+  if   [ -f "$AGENTS/$n.md" ];      then f="$AGENTS/$n.md"
+  elif [ -f "$SKILLS/$n/SKILL.md" ]; then f="$SKILLS/$n/SKILL.md"
+  else return 1; fi
+  grep -i "Trigger phrases:" "$f" | head -1 | grep -oE '"[^"]+"' | sed 's/"//g'
+}
+
+# The working set and the held-out set are read by the SAME matcher on purpose: if the holdout were scored more
+# leniently, its failures would stop meaning anything. What differs is only where the prompts came from.
+GOLD_SETS="$GOLD"
+[ -f "$(dirname "$GOLD")/golden-holdout.txt" ] && GOLD_SETS="$GOLD $(dirname "$GOLD")/golden-holdout.txt"
+echo "== 1) Golden routing (prompt -> expected target) =="
+[ -f "$GOLD" ] || { fail "golden-routing.txt missing"; }
+while IFS='|' read -r prompt expected; do
+  case "$prompt" in ''|\#*) continue ;; esac
+  # `[:space:]` includes CR, and that is the ONLY thing standing between this suite and a CRLF golden file.
+  # The Crewforth repo pins `*.txt text eol=lf` in .gitattributes, but these files are also INSTALLED into a user's
+  # project, where nothing pins them and Git for Windows sets core.autocrlf=true by default — so a Windows user
+  # who commits .claude/ and re-clones gets CRLF here. Measured on Windows with the golden files converted to
+  # CRLF byte for byte: 151 passes, 0 failures, identical to the LF run. Without this strip `expected` carries a
+  # trailing CR, matches no installed component, and every row fails as "target not installed".
+  expected="$(printf '%s' "$expected" | tr -d '[:space:]')"
+  [ -n "$expected" ] || continue
+  neg=0; case "$expected" in '!'*) neg=1; expected="${expected#!}" ;; esac   # !target = must NOT route here
+  # Pre-2.0 this skipped when the target was pruned by profile. Profiles are gone: every install carries every
+  # agent and skill, so an absent target is a missing component or a stale golden row — both real failures.
+  # (Until 3.0 the .NET pattern skill was the one exception; 3.0 ships one install shape, so there is none.)
+  if ! trs="$(triggers_of "$expected")"; then
+    fail "\"$prompt\" -> $expected: target not installed — every install ships every component"
+    continue
+  fi
+  np="$(norm "$prompt")"
+  hit=0
+  while IFS= read -r ph; do
+    [ -n "$ph" ] || continue
+    nph="$(norm "$ph")"
+    case "$np" in *"$nph"*) hit=1; break ;; esac
+  done <<EOF
+$trs
+EOF
+  if [ "$neg" = 1 ]; then
+    if [ "$hit" = 0 ]; then pass "\"$prompt\" -/-> $expected (correctly not matched)"
+    else fail "\"$prompt\" -/-> $expected (over-broad trigger — matched a prompt it should not route)"; fi
+  else
+    if [ "$hit" = 1 ]; then pass "\"$prompt\" -> $expected"
+    else fail "\"$prompt\" -> $expected (no trigger matched — routing gap)"; fi
+  fi
+done < <(cat $GOLD_SETS)
+
+echo "== 1b) Routing COVERAGE — every installed component has at least one positive case =="
+# The golden set proves that the cases in it route. It never proved that every component HAS a case, and an audit
+# found 12 skills and one agent with none — including security-scan, code-review, testing and spec-planning. A
+# component with no case is a component whose reachability is nobody's job to check, which is exactly how
+# crew-frontend-expert stayed unreachable for a whole class of request while every gate reported green. Adding a
+# component now means adding the sentence that must reach it.
+MISSING_CASE=""
+for f in "$AGENTS"/*.md "$SKILLS"/*/SKILL.md; do
+  [ -e "$f" ] || continue
+  case "$f" in */SKILL.md) n="$(basename "$(dirname "$f")")" ;; *) n="$(basename "$f" .md)" ;; esac
+  # A slash command (a skill marked `metadata: kind: command` since 3.0) is typed as /name, never routed to.
+  case "$f" in */SKILL.md) grep -q '^  kind: command' "$f" && continue ;; esac
+  grep -qE "^[^#]*\|$n\$" $GOLD_SETS || MISSING_CASE="$MISSING_CASE $n"
+done
+[ -z "$MISSING_CASE" ] && pass "every installed agent/skill has a positive routing case" \
+  || fail "no positive golden case for:$MISSING_CASE — add the sentence a user would type to reach it"
+
+echo "== 1c) Routing WINNER — what the real hook names, not only whether a trigger is present =="
+# Section 1 asks whether the expected target's trigger APPEARS in the prompt. That never asked whether the target
+# WINS: a prompt can carry its owner's trigger and still be routed somewhere else, because a louder word from a
+# rival scored higher. Measured, with every golden prompt run through the real route-hint.sh: two working-set
+# prompts routed to the wrong owner while section 1 reported both green. "the app feels laggy after the last
+# release" went to `release`; "is this endpoint fast enough on the hot path" went to the backend agent.
+#
+# So this section feeds every golden case through the REAL hook — not a second matcher, which would be the same
+# rule written twice and free to drift from the one that actually routes. It counts a positive as a hit when the
+# hook names the expected target, or names the agent whose body applies that expected skill: by design the hook
+# prefers an agent over a skill, and the agent carries the skill with it (the same notion §3b uses to call a
+# skill routed). A negative (`!target`) must never be what the hook names.
+#
+# KNOWN MISSES ARE A RATCHET, NOT A TOLERANCE. They are listed below by exact prompt. A wrong route that is not
+# on the list fails the suite; a listed one that starts routing correctly asks for its line to be removed, so the
+# number can only get better. The scorer itself is deliberately untouched: whether a single loud keyword should
+# be allowed to win is an open decision recorded in the roadmap, and this is the measurement that decision waits on.
+#
+# Rank the target among all rivals, not just check that it could match — scored by Crewforth's own scorer, the one
+# the hook runs, rather than a TF-IDF approximation.
+RH="$ROOT/hooks/route-hint.sh"
+KNOWN_MISSES='the app feels laggy after the last release
+is this endpoint fast enough on the hot path'
+if [ -f "$RH" ]; then
+  # CLAUDE_PLUGIN_ROOT points the hook at $ROOT/agents and $ROOT/skills directly, which is the same layout in
+  # Crewforth's own repo (kit/) and in an installed project (.claude/). No copy, no second tree to drift.
+  rh_names(){ printf '{"hook_event_name":"UserPromptSubmit","prompt":"%s"}' "$1" \
+      | CLAUDE_PROJECT_DIR=/nonexistent CLAUDE_PLUGIN_ROOT="$ROOT" bash "$RH" 2>/dev/null \
+      | sed -n -e 's/.*Use the \([a-z][a-z0-9-]*\) subagent.*/\1/p' -e 's/.*Use the .\([a-z][a-z0-9-]*\). skill.*/\1/p'; }
+  # Calibrate before trusting a single verdict: a prompt the hook is known to route must come back named. An
+  # extractor that silently returns nothing makes EVERY positive read as "silent" — measured, the first version
+  # of this section did exactly that, with a `\|` that BSD sed does not support, and reported 0 of 82.
+  if [ "$(rh_names 'add an endpoint that returns unpaid invoices')" != "crew-backend-expert" ]; then
+    fail "winner check cannot read the hook's answer (calibration prompt came back unnamed) — the measurement is broken, not the routing"
+  else
+    WIN_HIT=0; WIN_N=0; NEG_N=0; NEW_MISS=""; FIXED_MISS=""; NEG_BAD=""
+    while IFS='|' read -r prompt expected; do
+      case "$prompt" in ''|\#*) continue ;; esac
+      expected="$(printf '%s' "$expected" | tr -d '[:space:]')"
+      [ -n "$expected" ] || continue
+      got="$(rh_names "$prompt")"
+      case "$expected" in
+        '!'*)
+          NEG_N=$((NEG_N+1))
+          [ "$got" = "${expected#!}" ] && NEG_BAD="$NEG_BAD
+     ↳ named '$got' for: $prompt" ;;
+        *)
+          WIN_N=$((WIN_N+1))
+          ok=0
+          if [ -n "$got" ] && [ "$got" = "$expected" ]; then ok=1
+          elif [ -n "$got" ] && [ -f "$AGENTS/$got.md" ] && [ -f "$SKILLS/$expected/SKILL.md" ] \
+               && grep -qE "\`$expected\`|\*\*$expected\*\*" "$AGENTS/$got.md"; then ok=1
+          fi
+          known=0; printf '%s\n' "$KNOWN_MISSES" | grep -qxF -- "$prompt" && known=1
+          if [ "$ok" = 1 ]; then
+            WIN_HIT=$((WIN_HIT+1))
+            [ "$known" = 1 ] && FIXED_MISS="$FIXED_MISS
+     ↳ now routes correctly, remove it from KNOWN_MISSES: $prompt"
+          elif [ "$known" = 0 ]; then
+            NEW_MISS="$NEW_MISS
+     ↳ expected $expected, hook named '${got:-nothing}': $prompt"
+          fi ;;
+      esac
+    done <<EOF_GOLD
+$(cat $GOLD_SETS)
+EOF_GOLD
+    [ -z "$NEW_MISS" ] && pass "winner: $WIN_HIT of $WIN_N positive prompts routed to their owner by the real hook (known misses: $(printf '%s\n' "$KNOWN_MISSES" | grep -c .))" \
+                       || { fail "winner: a prompt is routed to the wrong owner and is not a known miss"; printf '%s\n' "$NEW_MISS"; }
+    [ -z "$FIXED_MISS" ] || { fail "winner: a known miss now routes correctly — tighten the ratchet"; printf '%s\n' "$FIXED_MISS"; }
+    # A known miss that is not a golden prompt is never evaluated, so it would sit on the list forever and inflate
+    # the count shown above. Measured: a stray line reported "known misses: 3" in a green run. A ratchet entry
+    # nothing checks is the same defect as a blocklist pattern nothing matches.
+    STALE=""
+    while IFS= read -r km; do
+      [ -n "$km" ] || continue
+      cat $GOLD_SETS | cut -d'|' -f1 | grep -qxF -- "$km" || STALE="$STALE
+     ↳ not a golden prompt: $km"
+    done <<EOF_KM
+$KNOWN_MISSES
+EOF_KM
+    [ -z "$STALE" ] || { fail "winner: a KNOWN_MISSES line is not in any golden set, so nothing ever checks it"; printf '%s\n' "$STALE"; }
+    [ -z "$NEG_BAD" ] && pass "winner: none of the $NEG_N negative cases is named by the real hook" \
+                      || { fail "winner: the real hook named a target a negative case forbids"; printf '%s\n' "$NEG_BAD"; }
+  fi
+else
+  skip "winner check skipped: $RH not present in this layout"
+fi
+
+echo "== 2) Agent-agent trigger collision =="
+# NOTE: Only AGENT-AGENT collisions matter (routing ambiguity lives here). An agent sharing a trigger
+# with the skill it OWNS (crew-backend-expert<->backend-architecture, crew-security-expert<->security-scan,
+# crew-devops-expert<->incident-runbook ...) is EXPECTED: the skill is the agent's internal "how"
+# source, not a separate dispatch — the router picks the agent, the agent reads the skill inside a
+# single subagent. So an agent<->its-own-skill overlap is intentional and is NOT a FAIL here.
+# Collect each agent's unique (normalized) triggers; anything appearing in 2+ agents = collision.
+dupe="$(
+  for f in "$AGENTS"/*.md; do
+    grep -i "Trigger phrases:" "$f" | head -1 | grep -oE '"[^"]+"' | sed 's/"//g' | while IFS= read -r p; do
+      [ -n "$p" ] && norm "$p"
+    done | sort -u
+  done | sort | uniq -d
+)"
+if [ -n "$dupe" ]; then
+  while IFS= read -r d; do [ -n "$d" ] && fail "same trigger in multiple agents: \"$d\""; done <<EOF
+$dupe
+EOF
+else
+  pass "agent triggers unique (no collision)"
+fi
+
+echo "---"
+if [ "$FAIL" -eq 0 ]; then echo "ROUTING-EVAL: PASSED ✅  (skipped: $SKIP)"; exit 0
+else echo "ROUTING-EVAL: $FAIL errors ❌  (skipped: $SKIP)"; exit 1; fi

package/kit/eval/scan-skill.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Install-time skill/agent security scanner — zero-dep bash + regex. Scans a directory or file (meant for a
+# project's EXISTING third-party .claude skills/agents that adopt.sh will coexist with) for supply-chain red flags
+# and scores each file:  score = 100 − CRIT×20 − HIGH×10 − MED×3 − LOW×1  (floored at 0).
+#   SAFE  ≥ 90 AND no CRIT/HIGH   ·   REVIEW  70–89, or any HIGH   ·   DANGER  < 70, or any CRIT
+#
+# ADVISORY + HEURISTIC. It substring-matches, so a *security-education* skill (a red-team guide, an exfil example)
+# can legitimately score low — REVIEW the flagged file, don't trust the number blindly. Its job is to SURFACE
+# curl|bash, prompt-injection directives, credential/exfil patterns, not to prove intent.
+#
+# Exit: 0 if every scanned file is SAFE, 1 if any is REVIEW/DANGER, 3 if NOTHING WAS SCANNED.
+# 3 exists because 0 was answering a question nobody asked. skill-trust.sh gates on this exit code and prints
+# "scanner: SAFE" when it is 0 — so a path the scanner never looked at (an empty directory, a vanished target,
+# a folder with no manifest) was reported to the user as clean. "I found nothing wrong" and "I did not look"
+# are different answers, and only one of them belongs on a security surface.
+# Usage:  bash scan-skill.sh [path]   (default: .claude)
+set -uo pipefail
+TARGET="${1:-.claude}"
+
+# --- pattern groups (ERE) ------------------------------------------------------------------------------------
+# CRIT: download-and-exec, known exfil/collaborator hosts, rm -rf of home/root.
+CRIT='(curl|wget|fetch)[^|]*\|[[:space:]]*(sudo[[:space:]]+)?(bash|sh|zsh|python[0-9.]*|node|perl|ruby)|(bash|sh)[[:space:]]+<\(|(webhook\.site|requestbin|pipedream\.net|ngrok\.io|burpcollaborator|oastify|interactsh|dnslog\.|\.oast\.)|rm[[:space:]]+-[A-Za-z]*r[A-Za-z]*[[:space:]]+(~|/|\$HOME)([[:space:]]|$|/)'
+# HIGH: prompt-injection directives; a credential file READ/exfil (a reader verb + the path — a bare `~/.ssh/id_rsa`
+# config value is NOT flagged); base64-decode piped to a shell; and a RUNTIME INSTRUCTION FETCH.
+#
+# That last one is not a missing regex, it is the assumption the trust model rests on. skill-trust.sh accepts a
+# component by DIGEST, and a digest answers "have these bytes changed?" — which is the wrong question for a file
+# whose bytes say "fetch your real instructions from this URL". The digest never moves while the behaviour is
+# rewritten by whoever controls the endpoint, and the component stays on the accepted list forever. So fetching
+# an instruction-shaped file (.md/.txt/.yml/.json) and a WebFetch tied to instructions/prompts are HIGH, while
+# an ordinary outbound URL stays LOW: measured against Crewforth's own payload, this flags 0 of 59 files, and the
+# two places Crewforth itself names WebFetch (a `tools:` line and a `Requires-tool` marker) are untouched.
+HIGH='ignore[[:space:]]+(all[[:space:]]+)?(the[[:space:]]+)?(previous|prior|above)[[:space:]]+(instruction|prompt)|disregard[[:space:]]+(the[[:space:]]+|all[[:space:]]+)?(previous|above|prior)|ignore[[:space:]]+your[[:space:]]+(system[[:space:]]+)?(prompt|instruction)|(cat|less|more|tail|head|base64|xxd|od|strings|curl|wget|scp|cp|rsync)[^|]*(~/\.ssh|id_rsa|/etc/(passwd|shadow)|\.aws/credentials|\.netrc|\.git-credentials)|(~/\.ssh|id_rsa|/etc/(passwd|shadow)|\.aws/credentials|\.netrc|\.git-credentials)[^|]{0,80}(curl|wget|scp|nc |netcat|base64|exfiltrat)|base64[[:space:]]+-[A-Za-z]*d[^|]*\||(curl|wget)[[:space:]][^|]*https?://[^[:space:]]*\.(md|txt|ya?ml|json)|(WebFetch|web_fetch)[^|]{0,120}(instruction|prompt|then follow|steps to follow)'
+# MED: named cloud/CI secret env vars, process.env secret access, chmod 777, code eval/exec.
+MED='(GITHUB_TOKEN|AWS_SECRET|AWS_ACCESS_KEY|NPM_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY|SLACK_TOKEN)|process\.env\.[A-Za-z_]*(TOKEN|SECRET|KEY|PASSWORD)|chmod[[:space:]]+(-R[[:space:]]+)?0?777|[^a-zA-Z](eval|exec)[[:space:]]*\('
+# LOW: an outbound URL fetch or a raw socket — common in benign deploy/example prose, hence low weight.
+LOW='(^|[^a-zA-Z])(curl|wget)[[:space:]]+[^|]*https?://|/dev/tcp/|[^a-zA-Z]nc[[:space:]]+-[A-Za-z]*e'
+
+FAIL=0; N=0
+# The score ranks; the SEVERITY decides. A single HIGH costs 10 points and lands on exactly 90 — the SAFE line —
+# so one credential-exfil line or one prompt-injection directive used to pass as safe on arithmetic alone. That
+# is the wrong way round: the score exists to order a review queue, not to let a high-severity hit through it.
+# So severity floors the verdict — any CRIT is DANGER, any HIGH is never SAFE — and the number still ranks what
+# is left. (Measured: Crewforth's own 59 payload files carry no CRIT or HIGH at all, lowest score 99.)
+verdict(){   # $1 = score, $2 = crit count, $3 = high count
+  if [ "${2:-0}" -gt 0 ]; then echo DANGER; return; fi
+  if [ "${3:-0}" -gt 0 ]; then [ "$1" -ge 70 ] && echo REVIEW || echo DANGER; return; fi
+  if [ "$1" -ge 90 ]; then echo SAFE; elif [ "$1" -ge 70 ]; then echo REVIEW; else echo DANGER; fi; }
+
+# One grep PER SEVERITY over ALL files, not four greps per file.
+#
+# Measured on a user's Windows machine: scanning 64 files took 8m07s — user 12.6s, sys 2m46s. The regex work is
+# not the cost; process creation is. Git Bash has no real fork, so every spawn is a CreateProcess plus MSYS
+# emulation plus an antivirus scan of the binary, and 64 files × 4 greps = 256 of them. adopt.sh calls this on
+# every refresh, which is where most of a "the update is hung" report actually went.
+#
+# grep accepts many files at once and `-cH` prints `path:count` for each, including zeros — so the same regex
+# engine, the same `-i` semantics and the same per-file line counts come back in 4 processes instead of 256.
+# Deliberately NOT rewritten in awk: these patterns carry intervals and alternations whose behaviour would have
+# to be re-proved against a different engine, and the win here is process count, not matching speed.
+counts_of(){   # $1 = pattern, $2 = output file. `path:count` per input file, in the order given.
+  grep -cHiE "$1" -- "${FILES[@]}" > "$2" 2>/dev/null
+  return 0     # grep exits 1 when nothing matched anywhere; that is a normal result, not an error
+}
+
+# Sets the named array AND the global RC_N. Deliberately not "$(read_counts …)": command substitution runs in a
+# SUBSHELL, so the array assignments would be discarded and every file would score a spotless 100. That is exactly
+# what the first version did — and the output diff against the old implementation is what caught it.
+read_counts(){ # $1 = grep -cH output file, $2 = array name
+  local line i=0
+  while IFS= read -r line; do
+    # split from the RIGHT: a path may contain ':' (a Windows drive letter), a count never does
+    eval "$2[$i]=\"\${line##*:}\""
+    i=$((i+1))
+  done < "$1"
+  RC_N=$i
+}
+
+emit(){        # prints one line per file, in FILES order, from the four count arrays
+  local f c h m l score v i=0
+  while [ "$i" -lt "${#FILES[@]}" ]; do
+    f="${FILES[$i]}"
+    c="${CNT_C[$i]:-0}"; h="${CNT_H[$i]:-0}"; m="${CNT_M[$i]:-0}"; l="${CNT_L[$i]:-0}"
+    i=$((i+1))
+    score=$((100 - c*20 - h*10 - m*3 - l*1)); [ "$score" -lt 0 ] && score=0
+    v="$(verdict "$score" "$c" "$h")"
+    N=$((N+1))
+    case "$v" in
+      SAFE)   printf '  ✅ %-3s %s\n' "$score" "$f" ;;
+      REVIEW) printf '  ⚠️  %-3s %s  (crit:%s high:%s med:%s low:%s) — REVIEW\n' "$score" "$f" "$c" "$h" "$m" "$l"; FAIL=1 ;;
+      DANGER) printf '  ❌ %-3s %s  (crit:%s high:%s med:%s low:%s) — DANGER\n' "$score" "$f" "$c" "$h" "$m" "$l"; FAIL=1 ;;
+    esac
+  done
+}
+
+# A single file keeps the old path: grep prints a bare count with one argument, so the batch parser would have to
+# special-case it anyway, and one file means one process either way.
+scan_file(){
+  local f="$1"
+  local c h m l
+  # grep -c prints the count (0 on no match) and exits 1 on no match; that non-zero exit is fine here (no set -e),
+  # and a `|| echo 0` would DOUBLE the printed 0 and break the arithmetic — so don't add one.
+  c=$(grep -icE "$CRIT" "$f" 2>/dev/null); h=$(grep -icE "$HIGH" "$f" 2>/dev/null)
+  m=$(grep -icE "$MED"  "$f" 2>/dev/null); l=$(grep -icE "$LOW"  "$f" 2>/dev/null)
+  c=${c:-0}; h=${h:-0}; m=${m:-0}; l=${l:-0}
+  local score=$((100 - c*20 - h*10 - m*3 - l*1)); [ "$score" -lt 0 ] && score=0
+  local v; v="$(verdict "$score" "$c" "$h")"
+  N=$((N+1))
+  case "$v" in
+    SAFE)   printf '  ✅ %-3s %s\n' "$score" "$f" ;;
+    REVIEW) printf '  ⚠️  %-3s %s  (crit:%s high:%s med:%s low:%s) — REVIEW\n' "$score" "$f" "$c" "$h" "$m" "$l"; FAIL=1 ;;
+    DANGER) printf '  ❌ %-3s %s  (crit:%s high:%s med:%s low:%s) — DANGER\n' "$score" "$f" "$c" "$h" "$m" "$l"; FAIL=1 ;;
+  esac
+}
+
+echo "== skill/agent security scan: $TARGET =="
+if [ -f "$TARGET" ]; then
+  scan_file "$TARGET"
+elif [ -d "$TARGET" ]; then
+  # Skill/agent definition files only (markdown). Skip Crewforth's own crew- agents (trusted, not third-party).
+  FILES=()
+  while IFS= read -r f; do
+    case "$f" in agents/crew-*.md|*/agents/crew-*.md) continue ;; esac   # kit agents only — a skill dir named crew-* is still scanned
+    FILES+=("$f")
+  done < <(find "$TARGET" \( -name 'SKILL.md' -o -name '*.md' \) -path '*/skills/*' -o -path '*/agents/*' -name '*.md' 2>/dev/null | sort -u)
+  # A skill directory with no SKILL.md is invisible to the scan above — the loop only ever sees files, so a
+  # folder carrying scripts and references but no manifest was scanned file by file (or not at all) and never
+  # named as odd. It is also the shape a component takes when it is trying not to look like a component.
+  # Globs, not `find`: `-depth 2` means "process contents first" to GNU find and takes no argument, so the
+  # BSD spelling that works on macOS is a syntax error on Linux and in Git Bash — i.e. on two of the three
+  # platforms Crewforth ships to. Globbing is also fork-free, which this scanner cares about (see the cost note).
+  for d in "$TARGET"/skills/*/ "$TARGET"/*/skills/*/; do
+    [ -d "$d" ] || continue                       # an unmatched glob expands to itself
+    [ -f "${d}SKILL.md" ] && continue
+    printf '  ⚠️  ---  %s  (no SKILL.md) — REVIEW: a skill directory without its manifest\n' "${d%/}"
+    FAIL=1; N=$((N+1))
+  done
+  if [ "${#FILES[@]}" -le 1 ]; then
+    [ "${#FILES[@]}" -eq 1 ] && scan_file "${FILES[0]}"
+  else
+    ST="$(mktemp -d)"
+    counts_of "$CRIT" "$ST/c"; counts_of "$HIGH" "$ST/h"
+    counts_of "$MED"  "$ST/m"; counts_of "$LOW"  "$ST/l"
+    read_counts "$ST/c" CNT_C; NC=$RC_N;  read_counts "$ST/h" CNT_H; NH=$RC_N
+    read_counts "$ST/m" CNT_M; NM=$RC_N;  read_counts "$ST/l" CNT_L; NL=$RC_N
+    rm -rf "$ST"
+    # If grep skipped a file (unreadable, vanished mid-run) the rows no longer line up with FILES, and a silently
+    # misaligned count would score the wrong file. Fall back to the per-file path rather than report a guess.
+    if [ "$NC" = "${#FILES[@]}" ] && [ "$NH" = "$NC" ] && [ "$NM" = "$NC" ] && [ "$NL" = "$NC" ]; then
+      emit
+    else
+      for f in "${FILES[@]}"; do scan_file "$f"; done
+    fi
+  fi
+else
+  echo "  (nothing to scan at '$TARGET')"; exit 3
+fi
+
+echo "---"
+if [ "$N" -eq 0 ]; then echo "scan: nothing scanned"; exit 3; fi
+if [ "$FAIL" -eq 0 ]; then echo "SCAN: all $N file(s) SAFE ✅"; exit 0
+else echo "SCAN: review the flagged file(s) above ⚠️  (heuristic — security-education skills can score low by design)"; exit 1; fi