crewforth 0.0.1 → 3.0.0-rc.1

package/kit/eval/gate-report.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# What did the gates actually DO? — reads CREW_GATE_LOG and reports it against the rule inventory.
+#
+# Crewforth's claim is that rules are enforced at the tool level rather than remembered. That claim is only worth
+# what its evidence is worth, and until now the evidence was a green test suite: proof the gates CAN fire, never
+# a record that they DID. This reads the other half.
+#
+# Two failure modes it is built around, both learned here the hard way:
+#   1. "0 firings" and "never measured" leave identical artifacts. So a rule is reported as `not observed`, never
+#      as dead, and a missing log is reported as NOT MEASURED — never as zero.
+#   2. A hand-maintained rule list drifts from the rules. So the inventory is DERIVED from the installed hooks
+#      on every run: a rule added to guard-bash.sh shows up here without anyone remembering to add it.
+#
+# Usage:  gate-report.sh [--log <path>] [--json]
+# Exit:   0 report produced · 3 no log to read (not an error: logging is opt-in) · 4 hooks not found
+set -u
+# 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
+
+LOG="${CREW_GATE_LOG:-}"; JSON=0
+while [ $# -gt 0 ]; do case "$1" in
+  --log) LOG="${2:-}"; shift 2 ;;
+  --json) JSON=1; shift ;;
+  *) echo "gate-report.sh: unknown argument '$1'" >&2; exit 64 ;;
+esac; done
+
+HOOKS="./.claude/hooks"; [ -d "$HOOKS" ] || HOOKS="./hooks"
+[ -f "$HOOKS/guard-bash.sh" ] || { echo "gate-report: guard-bash.sh not found (run from the project root)" >&2; exit 4; }
+
+# Default log location, so `--log` is not required once logging is on.
+[ -z "$LOG" ] && [ -f "./.claude/gate-log.tsv" ] && LOG="./.claude/gate-log.tsv"
+
+TMP="${TMPDIR:-/tmp}/crew-gate-$$"; mkdir -p "$TMP"; trap 'rm -rf "$TMP"' EXIT
+
+# Match on a KEY, display the full label. A rule label can carry a trailing parenthetical, and one of them
+# interpolates a shell variable ("… that cannot prompt (${PERM_MODE:-unknown})"): the inventory reads the
+# source, the log holds the expanded value, so the two never compare equal and the rule is reported as never
+# observed forever — a false negative in the one direction that matters. Both sides drop the trailing (...).
+key(){ printf '%s' "$1" | sed 's/[[:space:]]*([^()]*)[[:space:]]*$//'; }
+
+# ---- inventory: derived from the hooks, one awk pass per file (no per-rule subprocess: Windows forks cost 62-135 ms)
+awk '
+  # 23 rules of the form:  … && block "RULE" "SECTION"
+  match($0, /&& *block +"[^"]*" +"[^"]*"/) {
+    s=substr($0,RSTART,RLENGTH); n=split(s,q,"\"");  print q[4] "\t" q[2]; next
+  }
+  # direct calls:  gatelog VERDICT SECTION "RULE"
+  /^[[:space:]]*gatelog +[A-Z]+ +[0-9.]+ +"/ {
+    n=split($0,q,"\""); split($0,f," "); print f[3] "\t" q[2]; next
+  }
+' "$HOOKS/guard-bash.sh" > "$TMP/inv"
+# guard-write.sh emits its one line inline rather than through a helper, so read the label out of the printf
+# arguments the same way — the earlier version skipped the very line it needed (it matched CREW_GATE_LOG first)
+# and the rule silently never appeared in the inventory, which reads exactly like a rule that never fires.
+# guard-write.sh emits its one line inline rather than through a helper, so read the label out of the printf
+# arguments. Two traps here, both hit on the way: the line also mentions CREW_GATE_LOG (skipping on that name
+# skipped the rule itself), and the FIRST quoted field on the line is `${CREW_GATE_LOG:-}`, not the label — so
+# take the last quoted field that is not a variable reference.
+[ -f "$HOOKS/guard-write.sh" ] && awk '
+  /printf .BLOCK\\t/ {
+    n=split($0,q,"\""); lab=""
+    for (i=2; i<=n; i+=2) if (q[i] !~ /^\$/ && q[i] != "") lab=q[i]
+    if (lab != "") print "4.5\t" lab
+  }' "$HOOKS/guard-write.sh" >> "$TMP/inv"
+
+sort -u "$TMP/inv" -o "$TMP/inv"
+NRULES=$(grep -c . "$TMP/inv" 2>/dev/null); NRULES=$(( ${NRULES:-0} + 0 ))
+
+# ---- 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
+#                       measurement of zero, and it is the healthy reading.
+#   .claude/ missing -> there was nowhere to write. Nothing was measured; zero would be a lie.
+if [ -z "$LOG" ] || [ ! -f "$LOG" ]; then
+  if [ -d "./.claude" ]; then
+    if [ "$JSON" = 1 ]; then printf '{"measured":true,"rules":%s,"decisions":0}\n' "$NRULES"; else
+      echo "== gate report =="
+      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.)"
+    fi
+    exit 0
+  fi
+  if [ "$JSON" = 1 ]; then printf '{"measured":false,"rules":%s,"reason":"nowhere to record"}\n' "$NRULES"; else
+    echo "== gate report =="
+    echo "  ·  NOT MEASURED — no .claude/ to record into. $NRULES rules are wired; how often they fire is unknown."
+    echo "     ↳ point it somewhere:  export CREW_GATE_LOG=\"\$PWD/gate-log.tsv\""
+  fi
+  exit 3
+fi
+
+# ---- read the log: VERDICT \t §SECTION \t RULE \t COMMAND
+awk -F'\t' 'NF>=3 { k=$3; sub(/[[:space:]]*\([^()]*\)[[:space:]]*$/,"",k); c[k]++; lab[k]=$3; v[$1]++; tot++ } END {
+  print "TOTAL\t" tot+0
+  for (k in v) print "VERDICT\t" k "\t" v[k]
+  for (k in c) print "RULE\t" k "\t" c[k] "\t" lab[k]
+}' "$LOG" > "$TMP/agg"
+
+TOT=$(awk -F'\t' '$1=="TOTAL"{print $2}' "$TMP/agg"); TOT="${TOT:-0}"
+FIRST=$(head -1 "$LOG" 2>/dev/null | cut -f3); LINES=$(grep -c . "$LOG" 2>/dev/null); LINES=$(( ${LINES:-0} + 0 ))
+
+if [ "$JSON" = 1 ]; then
+  awk -F'\t' -v n="$NRULES" -v t="$TOT" '
+    $1=="RULE" { r=r sep "{\"rule\":\"" $4 "\",\"count\":" $3 "}"; sep="," }
+    END { printf "{\"measured\":true,\"rules\":%s,\"decisions\":%s,\"fired\":[%s]}\n", n, t, r }' "$TMP/agg"
+  exit 0
+fi
+
+echo "== gate report =="
+echo "  log: $LOG  ($LINES line(s), $TOT decision(s))"
+echo
+echo "  verdicts:"
+awk -F'\t' '$1=="VERDICT"{printf "    %-6s %s\n",$2,$3}' "$TMP/agg" | sort
+echo
+echo "  rules that fired:"
+awk -F'\t' '$1=="RULE"{printf "    %5s  %s\n",$3,$4}' "$TMP/agg" | sort -rn || true
+[ "$TOT" = 0 ] && echo "    (none)"
+echo
+# One awk over both files instead of sort|comm|join: that chain compared a two-field inventory line against a
+# one-field fired list, so a rule could land in BOTH lists at once (it did — `chmod world-writable` showed as
+# fired and as unseen in the same report). It also spawned four processes per run, which is real cost on
+# Windows. Here the fired set and the inventory meet in one pass, keyed the same way.
+UNSEEN="$(awk -F'\t' '
+  FILENAME==f1 && $1=="RULE" { fired[$2]=1; next }
+  FILENAME==f2 {
+    lbl=$2; k=lbl; sub(/[[:space:]]*\([^()]*\)[[:space:]]*$/,"",k)
+    if (!(k in fired) && !(k in seen)) { seen[k]=1; printf "    \302\267 %s\n", lbl }
+  }' f1="$TMP/agg" f2="$TMP/inv" "$TMP/agg" "$TMP/inv")"
+NUNSEEN=$(printf '%s' "$UNSEEN" | grep -c . 2>/dev/null || true); NUNSEEN="${NUNSEEN:-0}"
+echo "  wired but not observed in this log ($NUNSEEN of $NRULES):"
+[ -n "$UNSEEN" ] && printf '%s\n' "$UNSEEN"
+
+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."

package/kit/eval/golden-holdout.txt

@@ -0,0 +1,53 @@
+# HELD-OUT routing set: <example user prompt>|<expected target>
+#
+# Same format as golden-routing.txt and read by the same matcher. The difference is the method, and it is the
+# whole point: these prompts were written from the TASK a user would describe, in the words a user would use,
+# WITHOUT reading the target's trigger phrases first. In the working set the prompt is where the trigger came
+# from, so a passing row proves only that the author copied one into the other. Here the two were produced
+# independently, so a row can fail — and a failure means the trigger is too narrow to reach a request nobody
+# tuned it for, which is the only thing this eval was ever supposed to measure.
+#
+# WHEN A ROW FAILS, the fix is a decision, not a reflex:
+#   · widen the trigger — and re-run, because the negative rows in golden-routing.txt exist to catch a widening
+#     that starts stealing a neighbour's work;
+#   · or judge the prompt unreasonable for that target and say so here, in a comment, rather than deleting it
+#     quietly. A row removed without a reason is how a held-out set decays back into a working set.
+# Never "fix" a failure by editing the prompt toward the trigger. That is the thing being measured.
+
+my checkout is failing on the pipeline and I cannot tell why|ci-pipeline
+the page is unusable with a keyboard, tab order jumps everywhere|a11y
+we are adding a column to the users table next week|db-migration
+customers in Germany are asking what we store about them|privacy-compliance
+someone pasted an API key into a config file, what now|security-scan
+the app takes eight seconds to open the dashboard|performance
+I need to cut a new version and tell people what changed|release
+this endpoint returns different shapes depending on the caller|api-design
+we keep discovering the same outage twice a month|incident-runbook
+I want to know if this library is still maintained|dependency-audit
+three of us are working on the same repo and duplicating work|teamboard
+I am about to run out of room in this conversation|handoff
+nobody knows why we chose this queue over the other one|adr
+the tests pass locally and fail in the pipeline every third run|testing
+I want to be sure this change did not make anything slower|performance
+we need to put this build on the server tonight|deploy
+
+# --- REJECTED, with the reason. Not deleted: a row removed without a reason is how a held-out set decays -----
+#
+# "the German strings are missing on the checkout page" -> i18n-integrity
+#   The only phrase that could carry it is "strings are missing", which is a verbatim slice of this sentence —
+#   memorising the test, not widening the trigger — AND it steals: "the connection strings are missing from
+#   appsettings" then routes to the translation skill. Matching is contiguous, so "missing string" never
+#   reaches it either. The class is real; no phrase separates it from a config problem. Reported, not forced.
+#
+# "the model keeps ignoring my instructions when it reads a file" -> red-team
+#   The intent (indirect prompt injection) does belong here, but the only substrings that could carry it —
+#   "my instructions", "ignoring my instructions", "reads a file" — are indistinguishable from two far more
+#   common requests: a user saying the assistant is not following instructions, and a parser bug on file read.
+#   Any phrase that catches this prompt takes both of those with it.
+#
+# Both stay listed so the next person sees the class was considered and why the trigger cannot express it. If
+# route-hint ever scores on more than contiguous substrings, reopen them.
+# 3.0 rows for backend-architecture. Honesty note: written by the same person who wrote that skill's triggers,
+# 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

package/kit/eval/golden-routing.txt

@@ -0,0 +1,199 @@
+# Golden routing: <example user prompt>|<expected target agent/skill>
+#
+# THIS FILE IS THE WORKING SET, and what it can and cannot prove is worth stating. AGENT_TEMPLATE.md tells the
+# author to add the line FIRST and then choose trigger phrases against it — "you're designing the description
+# against a concrete prompt" — and the matcher below is a substring test. So a row here proves the trigger was
+# chosen for this prompt; it cannot prove the trigger generalises, because the prompt is where the trigger came
+# from. `golden-holdout.txt` is the other half: prompts written for the same target WITHOUT looking at its
+# triggers. Only a holdout row can fail for the reason this eval exists.
+# routing-eval.sh reads this: the expected target's trigger phrase must appear in the prompt (substring).
+# If the target isn't installed in this profile, the line is SKIPPED (won't fail a pruned install).
+# NEGATIVE line: <prompt>|!<target> asserts the prompt must NOT route to <target> (none of its triggers match) —
+# a guard against over-broad triggers. See the "must NOT route" block at the end of this file.
+add a new handler for the order endpoint|crew-backend-expert
+write a migration for this table|crew-database-expert
+build a responsive component for the login screen|crew-frontend-expert
+# Positive twins of the seven over-broad-word rows below: the replacement phrase must still route.
+cut a release and tag it|release
+review the code in this PR|crew-code-review
+the page layout is broken on mobile|frontend-design
+requests are timing out under load|crew-performance-expert
+add client routing to the app|crew-frontend-expert
+add a new rn screen with expo router|frontend-rn-expo
+run an OWASP check and a full security scan|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
+do a PR review and look at the diff|crew-review-agent
+plan first and produce a task breakdown|crew-planner
+deploy this and go to production on the VPS|deploy
+prepare the changelog and cut a tag|release
+set up a ci pipeline with github actions|ci-pipeline
+write an adr for this architecture decision|adr
+run npm audit for a dependency audit|dependency-audit
+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
+update the README and write the API docs|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
+write an incident runbook and a postmortem|incident-runbook
+red team the prompt injection defenses|red-team
+ship to prod and be ready to rollback|crew-devops-expert
+set up a reverse proxy and ssl|crew-devops-expert
+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
+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
+
+# --- How a user actually phrases it -> the AGENT that must own the work ---
+# Added after a real install where a design request produced good analysis and no delegation. Every case here
+# asserts an AGENT, deliberately: the skills already carried this vocabulary ("visual design", "typography",
+# "memory leak") so the skill fired and the gate stayed green, while the agent that OWNS the work was
+# unreachable by the words anyone actually types. Testing the skill proved the mapping existed; it never proved
+# a real sentence reached the delegation layer.
+the app does not look premium, improve the visual design|crew-frontend-expert
+add a dark mode and a design token layer|crew-frontend-expert
+the icons are inconsistent, we need a design system|crew-frontend-expert
+we have a memory leak in production|crew-performance-expert
+the app feels laggy after the last release|crew-performance-expert
+users report the app crashes on startup|systematic-debugging
+the login is broken and I do not know why|systematic-debugging
+# Narrowing a trigger has to be paid for with a positive case, or the fix for a false route quietly creates an
+# unreachable component. token-budget had NO positive case at all before this line.
+the context is full, check the token budget before we continue|token-budget
+
+# --- Core components that had NO positive case until 1.11.0 ---
+# An audit found 12 skills and one agent that the routing gate never checked — including security-scan,
+# code-review, testing and spec-planning, i.e. most of what Crewforth advertises. A component with no case is a
+# component whose reachability is assumed, which is exactly how crew-frontend-expert went unreachable for a whole
+# class of request while every gate stayed green.
+i am not sure what we want here yet, help me scope it|brainstorm
+review the code I just wrote before I push|crew-code-review
+write a commit message for the staged changes|commit-message
+add column last_login to the users table|db-migration
+add a query handler with a validator for this module|backend-architecture
+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
+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
+is a handover needed, the context status looks high|crew-session-manager
+
+# --- 3.0: the stack is resolved per project by backend-architecture (it replaced cqrs-aop-module) ---
+which stack should we use for this backend|backend-architecture
+set up the project structure for a new API|backend-architecture
+choose a database for this service|backend-architecture
+
+# --- Negative: prompt must NOT route to target (over-broad-trigger guard) ---
+#
+# The seven rows below are the ones that were REPORTED FROM LIVE USE, not invented. Each generic English word
+# was a standalone trigger, and a single trigger of six characters or more clears the score floor on its own —
+# so any sentence containing the word routed somewhere unrelated. Measured before the fix: all seven misrouted.
+#   "context"  -> token-budget            "version"  -> release             "review"  -> crew-review-agent
+#   "routing"  -> crew-frontend-expert     "timeout"  -> performance-expert  "screen"  -> crew-frontend-expert
+#   "layout"   -> frontend-design
+# None of them came from this release's widening: all seven were triggers in 2.6.0 and earlier, which the diff
+# against v2.6.0 confirms. Each was replaced by the phrase that carries the intent rather than deleted, and the
+# POSITIVE twin of every row sits in the block above — a guard that only proves silence would be satisfied by
+# a component with no triggers at all.
+give me more context on this bug|!token-budget
+review the jira ticket before I send it|!crew-review-agent
+the image version is 3.2, rebuild it|!release
+the routing table is misconfigured|!crew-frontend-expert
+the request timeout is 30 seconds|!crew-performance-expert
+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
+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
+# bare `UI` trigger for `UI polish`; this line fails if either regresses.
+the build fails on CI|!crew-frontend-expert
+the docker build is broken in the pipeline|!crew-frontend-expert
+# Same class, found while verifying the fix above: a bare `token` trigger sent "design token layer" to the
+# 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
+before I start, am I sure enough to implement this|confidence-check
+upgrade dependencies to current versions|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
+is my auto mode classifier policy still intact|automode-policy
+
+# --- negative guards added with the trigger widening -------------------------------------------------
+# Each widening below opened a class of request; each row here is a request that belongs to a NEIGHBOUR
+# and must NOT reach the widened component. A widening without its guard is a steal nobody would notice.
+add keyboard shortcuts for power users on the dashboard|!a11y
+pick a color palette for the dark mode|!a11y
+the focus this sprint is the new checkout component|!a11y
+add a mouse hover state to the card|!a11y
+reorder the tab bar items on the profile screen|!a11y
+bump the default text size in the design system|!a11y
+add a motion blur transition between routes|!a11y
+make the empty state look more premium on the profile page|!a11y
+is the lodash version in our lockfile affected by a published CVE|!security-scan
+payments are down in production, who owns the incident right now|!security-scan
+we have a memory leak in the worker process after the release|!security-scan
+map the trust boundaries and entry points before we start the audit|!security-scan
+the goroutine leaked memory and the pod restarted|!security-scan
+the connection pool leaked connections under load|!security-scan
+trim what we store in the session cache so redis stops growing|!privacy-compliance
+someone pushed a database password to the repo, rotate the credentials|!privacy-compliance
+delete the old event rows from the analytics table to save disk|!privacy-compliance
+fix the sql injection in the search filter before release|!red-team
+you keep ignoring my instructions about the commit format|!red-team
+the importer crashes when it reads a large file|!red-team
+the ci build takes 20 minutes and blocks every pr|!performance
+the webpack build takes ninety seconds to finish in the pipeline|!performance
+add a duration metric and a correlation id to this handler|!performance
+the github actions workflow needs a build and test stage before the pr gate|!testing
+the docker build step fails in the pipeline but works on my machine|!testing
+users hit an intermittent bug on checkout that I cannot reproduce|!testing
+add a column chart to the analytics dashboard|!db-migration
+the results grid needs an extra column on the settings screen|!db-migration
+we are migrating the frontend build to vite next week|!db-migration
+the login endpoint throws a 500 for half the requests|!api-design
+add a new endpoint that returns the user profile|!api-design
+upgrading the sdk to v4 is not backward compatible|!api-design
+users get a different response from the cache than the database|!api-design
+bump versions of the outdated packages and verify the build|!dependency-audit
+wire up a new dependency injection container for the module|!dependency-audit
+we send analytics events to a third party service|!dependency-audit
+the npm ci step fails on the windows runner|!dependency-audit
+the context is full, check the token budget before we continue|!handoff
+is it time to clear, how healthy is this session|!handoff
+the disk is about to run out of space on the server tonight|!handoff
+resume the half-finished migration on the users table|!handoff
+run two agents in parallel without them touching the same files|!teamboard
+isolate this refactor in a sandbox worktree so the parallel edits do not collide|!teamboard
+break the release work down into tasks with acceptance criteria|!teamboard
+my two agents are working on the same files|!teamboard
+nobody knows why the nightly job fails every other night|!adr
+write the README section explaining how the retry queue works|!adr
+how do we split this into tasks with acceptance criteria|!adr
+explain the reasoning behind this stack trace|!adr
+the unit tests are failing after my refactor|!ci-pipeline
+cut the release, write the changelog and tag it|!ci-pipeline
+the deploy to the server failed last night|!ci-pipeline
+add a build step to the github actions workflow|!deploy
+we have an outage in production, start the incident runbook|!deploy
+bump the version and add the changelog entry|!deploy
+tail the nginx logs on the server for me|!deploy
+the cron job on the server never fires|!deploy
+the tests fail on the server but pass in my ide|!deploy
+we push to produce a release candidate every friday|!deploy
+add a link to product detail from the search results|!deploy
+build a responsive component for the login screen|!i18n-integrity
+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

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

@@ -0,0 +1,14 @@
+# Sourced, not run. The ONE bash place that still reads the pre-3.0 CSK_* names.
+#
+# 3.0 renamed every CSK_* variable to CREW_*. The ones a user can have set — because a README, --help, a command
+# file or a message names them — keep working for the whole 3.x line: when CREW_<X> is not set at all and CSK_<X>
+# is, CREW_<X> takes its value. A CREW_<X> that is set, even to 0 or empty, wins. Internal and test variables were
+# renamed with no fallback. The old names go in 4.0.
+#
+# Builtins only (a loop of `eval`s): sourcing this costs no process, which matters in hooks on Git Bash.
+# Kept after this file runs: the updater and doctor read it to say which set 2.x names still work.
+_crew_legacy=" LANG NO_STAR NO_UPDATE_CHECK NO_BOARD GATE_LOG GATE_LOG_CMD STUDIO_TOKEN STUDIO_PEERS STUDIO_RUNTIME MAX_FILE_BYTES ALLOW_SOURCE_INSTALL "
+for _crew_v in $_crew_legacy; do
+  eval "if [ -z \"\${CREW_$_crew_v+x}\" ] && [ -n \"\${CSK_$_crew_v+x}\" ]; then CREW_$_crew_v=\"\$CSK_$_crew_v\"; export CREW_$_crew_v; fi"
+done
+unset _crew_v

package/kit/eval/lib/settings-json.awk

@@ -0,0 +1,154 @@
+# settings-json.awk — Crewforth's one JSON reader for settings.json, POSIX awk only (no jq, no python3), so the
+# same code runs on macOS BSD awk, Linux mawk/gawk and Windows Git-Bash gawk.
+#
+#   awk -v op=validate -f settings-json.awk FILE              rc 0 = FILE is a JSON object, 1 = it is not
+#   awk -v op=get -v path=hooks.Stop.0 -f settings-json.awk FILE   the value there, as the merge would print it
+#   awk -v op=len -v path=hooks.Stop -f settings-json.awk FILE     how many entries an array/object holds
+#   awk -v op=strings -v path=permissions.deny -f settings-json.awk FILE   each string element of that array, one per
+#       line, quotes off, escapes as written (rc 1 = not an array)
+#       path = dot-separated keys, a number indexes an array (0-based), empty = the root. rc 1 = no such path
+#       (or, for len, a scalar there), 10 = FILE is not a JSON object.
+#   awk -v op=overlay -v key=K [-v setk=M -v setv=RAWJSON] -f settings-json.awk FILE1 FILE2
+#       FILE1 with FILE1.K shallow-merged from FILE2.K (FILE2 wins, FILE1's other members and order kept), then
+#       member M set to RAWJSON. rc 10 = FILE1 (or its K) is not an object, 11 = FILE2 has no object at K.
+#   awk -v op=merge -v retired='R1|R2' -f settings-json.awk KIT PROJECT > OUT
+#       rc 0 = merged JSON on stdout · 10 = PROJECT is not a JSON object · 11 = KIT is not · 12 = "hooks" has a
+#       shape the merge cannot place (not an object of arrays). Nothing is printed on a non-zero rc. The codes sit
+#       clear of awk's own 2 (bad program, unreadable file), so a caller never reads a missing file as bad JSON.
+#
+# Reader contract: a recursive-descent parse into nodes (T = o/a/s, N = child count, K = key, C = child, V = raw
+# scalar text). Strings are kept as their raw token, escapes included and never decoded, so they are written back
+# byte-for-byte; two spellings of one string (\u0041 vs A) therefore count as different. Object key order and
+# array order are preserved. Numbers are checked against the JSON grammar and kept as written.
+#
+# Merge semantics (what the former jq program in adopt.sh did, held to it by the parity fixture in
+# packaging/e2e.sh): objects deep-merge, the PROJECT's scalar wins, arrays concat+dedup with Crewforth's entries
+# first, and "hooks" is rebuilt per event as Crewforth's entries followed by the project's entries that do not
+# reference .claude/hooks/ (in "command" or "args"). permissions.ask then loses every rule named in -v retired.
+# Output is pretty-printed with two-space indent, the layout jq writes, so merging Crewforth onto itself gives its
+# own bytes back.
+# The text is split into CH[] once. substr(S,P,1) is O(len) per call on BSD awk, which made a 1 MB file take ~20 s;
+# array indexing is O(1), so parsing is linear. split(s, CH, "") splits into characters in onetrue/BSD awk, gawk
+# and mawk alike.
+function sk(){ while(P<=L && index(" \t\r\n", CH[P])) P++ }
+# Strings are held to RFC 8259, the grammar Claude Code's JSON.parse applies: an escape is one of \" \\ \/ \b \f \n
+# \r \t or \u + 4 hex digits, and no raw control character (below 0x20). The raw token is returned, escapes kept.
+function ps(  t,c,i){ t=CH[P]; P++
+  while(P<=L){ c=CH[P]; P++
+    if(c=="\\"){ if(P>L) return ""; c=CH[P]; P++
+      if(c=="u"){ t=t "\\u"; for(i=0;i<4;i++){ if(P>L || !index("0123456789abcdefABCDEF", CH[P])) return ""; t=t CH[P]; P++ }; continue }
+      if(!index("\"\\/bfnrt", c)) return ""; t=t "\\" c; continue }
+    if(index(CTL, c)) return ""
+    t=t c; if(c=="\"") return t }
+  return "" }
+function pv(  id,c,k,q,st){ sk(); c=CH[P]; id=++NN; N[id]=0
+  if(c=="{" || c=="["){ T[id]=(c=="{" ? "o" : "a"); P++; sk()
+    if(CH[P]==(c=="{" ? "}" : "]")){ P++; return id }
+    while(1){ k=""
+      if(c=="{"){ sk(); if(CH[P]!="\"" || (k=ps())=="") return 0; sk(); if(CH[P++]!=":") return 0 }
+      if(!(q=pv())) return 0
+      N[id]++; K[id,N[id]]=k; C[id,N[id]]=q; sk(); st=CH[P++]
+      if(st==(c=="{" ? "}" : "]")) return id
+      if(st!=",") return 0 } }
+  T[id]="s"
+  if(c=="\""){ V[id]=ps(); return (V[id]=="" ? 0 : id) }
+  st=""; while(P<=L && CH[P] ~ /[-+.0-9A-Za-z]/){ st=st CH[P]; P++ }; V[id]=st
+  return (V[id] ~ /^(true|false|null|-?(0|[1-9][0-9]*)([.][0-9]+)?([eE][-+]?[0-9]+)?)$/ ? id : 0) }
+# doc(f): parse file number f. CH[] is built from that file's lines directly: gluing the lines into one string
+# first was itself quadratic (each append copies the whole buffer) on a many-line file.
+function doc(f,  r,i,j,n,tc){ split("",CH); L=0
+  for(i=1;i<=NL[f];i++){ n=split(LN[f,i],tc,""); for(j=1;j<=n;j++) CH[++L]=tc[j]; CH[++L]="\n" }
+  P=1
+  if(CTL==""){ for(r=1;r<32;r++) CTL=CTL sprintf("%c",r) }
+  r=pv(); sk(); return (r && P>L && T[r]=="o") ? r : 0 }
+# A duplicated key: the LAST value wins, as in JSON.parse and jq — the value Claude Code actually reads.
+function get(o,k,  i){ for(i=N[o];i>=1;i--) if(K[o,i]==k) return C[o,i]; return 0 }
+function isnull(id){ return T[id]=="s" && V[id]=="null" }
+function at(id,path,  n,sg,i){ n=split(path,sg,".")
+  for(i=1;i<=n && id;i++) id=(T[id]=="o") ? get(id,"\"" sg[i] "\"") : (T[id]=="a" && sg[i] ~ /^[0-9]+$/ && sg[i]<N[id]) ? C[id,sg[i]+1] : 0
+  return id }
+function mk(t){ NN++; T[NN]=t; N[NN]=0; return NN }
+function add(o,k,c){ N[o]++; K[o,N[o]]=k; C[o,N[o]]=c }
+function canon(id,  i,j,n,s,t,ord){
+  if(T[id]=="s") return V[id]
+  if(T[id]=="a"){ s="["; for(i=1;i<=N[id];i++) s=s (i>1 ? "," : "") canon(C[id,i]); return s "]" }
+  n=N[id]; for(i=1;i<=n;i++) ord[i]=i
+  for(i=2;i<=n;i++) for(j=i;j>1 && K[id,ord[j-1]]>K[id,ord[j]];j--){ t=ord[j]; ord[j]=ord[j-1]; ord[j-1]=t }
+  s="{"; for(i=1;i<=n;i++) s=s (i>1 ? "," : "") K[id,ord[i]] ":" canon(C[id,ord[i]]); return s "}" }
+function cat(a,b,  r,i,c,seen){ r=mk("a")
+  for(i=1;i<=N[a];i++){ c=canon(C[a,i]); if(!(c in seen)){ seen[c]=1; add(r,"",C[a,i]) } }
+  for(i=1;i<=N[b];i++){ c=canon(C[b,i]); if(!(c in seen)){ seen[c]=1; add(r,"",C[b,i]) } }
+  return r }
+function dm(a,b,  r,i,x){ r=mk("o")
+  for(i=1;i<=N[a];i++){ x=get(b,K[a,i]); add(r,K[a,i], !x ? C[a,i] : (T[C[a,i]]=="o" && T[x]=="o") ? dm(C[a,i],x) : (T[C[a,i]]=="a" && T[x]=="a") ? cat(C[a,i],x) : x) }
+  for(i=1;i<=N[b];i++) if(!get(a,K[b,i])) add(r,K[b,i],C[b,i])
+  return r }
+function has_kit(s){ return T[s]=="s" && index(V[s], ".claude/hooks/") }
+function is_kit(e,  hs,i,h,a,j){ hs=get(e,"\"hooks\""); if(T[e]!="o" || T[hs]!="a") return 0
+  for(i=1;i<=N[hs];i++){ h=C[hs,i]; if(T[h]!="o") continue
+    if(has_kit(get(h,"\"command\""))) return 1
+    a=get(h,"\"args\""); if(T[a]=="a") for(j=1;j<=N[a];j++) if(has_kit(C[a,j])) return 1 }
+  return 0 }
+function hooks(kh,ph,  r,i,e,a,x,y,j){ r=mk("o")
+  for(i=1;i<=N[kh];i++){ e=K[kh,i]; if(!get(r,e)) add(r,e,mk("a")) }
+  for(i=1;i<=N[ph];i++){ e=K[ph,i]; if(!get(r,e)) add(r,e,mk("a")) }
+  for(i=1;i<=N[r];i++){ e=K[r,i]; a=C[r,i]; x=get(kh,e); y=get(ph,e)
+    if(isnull(x)) x=0; if(isnull(y)) y=0          # null event = no entries, as the jq merge's `// []` read it
+    if((x && T[x]!="a") || (y && T[y]!="a")) return 0
+    for(j=1;j<=N[x];j++) add(a,"",C[x,j])
+    for(j=1;j<=N[y];j++) if(!is_kit(C[y,j])) add(a,"",C[y,j]) }
+  return r }
+function put(id,ind,  i,s,o){
+  if(T[id]=="s") return V[id]
+  o=(T[id]=="o"); if(!N[id]) return (o ? "{}" : "[]")
+  s=(o ? "{" : "["); for(i=1;i<=N[id];i++) s=s (i>1 ? "," : "") "\n" ind "  " (o ? K[id,i] ": " : "") put(C[id,i], ind "  ")
+  return s "\n" ind (o ? "}" : "]") }
+# dls(s): parse one string (a JSONL record) the same way.
+function dls(s,  r,n){ split("",CH); L=split(s,CH,""); P=1
+  if(CTL==""){ for(r=1;r<32;r++) CTL=CTL sprintf("%c",r) }
+  r=pv(); sk(); return (r && P>L && T[r]=="o") ? r : 0 }
+FILENAME!=cur{ f++; cur=FILENAME } { LN[f,++NL[f]]=$0 }
+END{
+  # op=usage (hooks/context-usage.sh): FILE is a transcript tail (JSONL). Walking from the LAST line back, print the
+  # context total of the last record that is a real top-level `type: assistant`, not a sidechain, carrying
+  # message.usage.cache_read_input_tokens — the predicate the former jq program applied. Each candidate is PARSED:
+  # a regex over the line matched the same key names inside tool inputs and results, and could count a nested
+  # object instead of the record's own usage. A line that does not parse (the window's cut first line) is skipped.
+  if(op=="usage"){ for(i=NL[1];i>=1;i--){ l=LN[1,i]; if(!index(l,"cache_read_input_tokens")) continue
+      if(!(r=dls(l))) continue
+      x=get(r,"\"isSidechain\""); if(x && !(isnull(x) || V[x]=="false")) continue
+      x=get(r,"\"type\""); if(!x || V[x]!="\"assistant\"") continue
+      u=at(r,"message.usage"); if(T[u]!="o") continue
+      cr=get(u,"\"cache_read_input_tokens\""); if(!cr || isnull(cr)) continue
+      it=get(u,"\"input_tokens\""); cc=get(u,"\"cache_creation_input_tokens\"")
+      print (it && !isnull(it) ? V[it] : 0) + V[cr] + (cc && !isnull(cc) ? V[cc] : 0); exit 0 }
+    exit 0 }
+  if(op=="validate") exit !doc(1)
+  if(op=="get" || op=="len"){ if(!(r=doc(1))) exit 10; if(!(r=at(r,path))) exit 1
+    if(op=="get"){ print put(r,""); exit 0 } if(T[r]=="s") exit 1; print N[r]; exit 0 }
+  if(op=="strings"){ if(!(r=doc(1))) exit 10; if(!(r=at(r,path))) exit 1; if(T[r]!="a") exit 1
+    for(i=1;i<=N[r];i++){ c=C[r,i]; if(T[c]=="s" && substr(V[c],1,1)=="\"") print substr(V[c],2,length(V[c])-2) }
+    exit 0 }
+  if(op=="overlay"){ if(!(t=doc(1))) exit 10; if(!(q=doc(2))) exit 11; kk="\"" key "\""
+    qv=get(q,kk); if(T[qv]!="o") exit 11; tv=get(t,kk); if(tv && T[tv]!="o") exit 10
+    nv=mk("o"); for(i=1;i<=N[tv];i++){ x=get(qv,K[tv,i]); add(nv,K[tv,i], x ? x : C[tv,i]) }
+    for(i=1;i<=N[qv];i++) if(!get(nv,K[qv,i])) add(nv,K[qv,i],C[qv,i])
+    if(setk!=""){ sn=mk("s"); V[sn]=setv; x=0
+      for(i=1;i<=N[nv];i++) if(K[nv,i]=="\"" setk "\""){ C[nv,i]=sn; x=1 }
+      if(!x) add(nv,"\"" setk "\"",sn) }
+    x=0; for(i=1;i<=N[t];i++) if(K[t,i]==kk){ C[t,i]=nv; x=1 }
+    if(!x) add(t,kk,nv)
+    print put(t,""); exit 0 }
+  if(!(k=doc(1))) exit 11
+  if(!(p=doc(2))) exit 10
+  kh=get(k,"\"hooks\""); ph=get(p,"\"hooks\""); if(isnull(kh)) kh=0; if(isnull(ph)) ph=0
+  if((kh && T[kh]!="o") || (ph && T[ph]!="o")) exit 12
+  r=dm(k,p); if(!(h=hooks(kh ? kh : mk("o"), ph ? ph : mk("o")))) exit 12
+  for(i=1;i<=N[r];i++) if(K[r,i]=="\"hooks\""){ C[r,i]=h; h=0 }
+  if(h) add(r,"\"hooks\"",h)
+  n=split(retired,rr,"|"); for(i=1;i<=n;i++) ret["\"" rr[i] "\""]=1
+  pm=get(r,"\"permissions\""); ak=(T[pm]=="o" ? get(pm,"\"ask\"") : 0)
+  if(T[ak]=="a"){ na=mk("a"); for(i=1;i<=N[ak];i++) if(T[C[ak,i]]!="s" || !(V[C[ak,i]] in ret)) add(na,"",C[ak,i])
+    for(i=1;i<=N[pm];i++) if(K[pm,i]=="\"ask\"") C[pm,i]=na }
+  print put(r,"")
+}

package/kit/eval/lib/star.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# The one "leave a star" line. Single source of its URL, its text in both languages, and when it stays quiet.
+#
+#   star.sh --once <project>   ONCE PER KIT VERSION per clone. The installers (first install, and every update)
+#                              and doctor.sh on a healthy verdict all call it this way and share one marker, so a
+#                              version shows the line once — whichever of them reaches it first — and never again
+#                              until the Crewforth version changes. The marker holds the version it was shown for.
+#   star.sh                    unconditional (tests, and anyone who wants to see it).
+#
+# Nothing else prints it: not a hook, not a session start. Cost: one line (~30 tokens) per version, and only when
+# the model relays it — /crew-update and /crew-doctor tell it to pass the line through as the last line.
+#
+# The marker lives in the git dir (`git rev-parse --git-path`), NOT under .claude/: a project that tracks .claude/
+# would otherwise commit it, and one person's "seen" would silence the line for the whole team. Outside a git
+# repository it falls back to <project>/.claude/star-shown.
+#
+# Quiet when CREW_NO_STAR is set to anything but 0, or when CI is defined at all: an unattended run has nobody to
+# read it. A silenced run writes NO marker, so the line is still owed to whoever runs it by hand later.
+set -u
+# 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/./crew-env.sh" ] && . "$_crew_d/./crew-env.sh"; unset _crew_d
+CREW_REPO_URL="https://github.com/Crewforth/crewforth"
+
+case "${CREW_NO_STAR:-}" in ''|0) ;; *) exit 0 ;; esac
+[ -n "${CI+set}" ] && exit 0
+
+MARK=""; VER=""
+if [ "${1:-}" = --once ]; then
+  _dir="${2:-.}"
+  # Builtin reads, not `head | tr` in a $( ): on Git Bash those two pipelines were 4 of ~11 processes and ~250 ms
+  # of ~395 ms per call (measured on stock Windows). `read` takes the first line; the CR is stripped by expansion.
+  # The braces matter: a failed `<` reports before a trailing 2>/dev/null applies (measured: 450 bytes of stderr).
+  VER=""; { IFS= read -r VER < "$_dir/.claude/VERSION"; } 2>/dev/null; VER="${VER%$'\r'}"; VER="${VER:-unknown}"
+  # GIT_DIR/GIT_WORK_TREE dropped: exported by a caller (a hook), they would point the marker at another repo.
+  MARK="$(cd "$_dir" 2>/dev/null && env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-path crewforth-star 2>/dev/null)" || MARK=""
+  case "$MARK" in
+    '') MARK="$_dir/.claude/star-shown" ;;
+    /*|[A-Za-z]:*) ;;                          # absolute (POSIX or a Windows drive path from git)
+    *) MARK="$_dir/$MARK" ;;                   # git answers relative to the directory it was asked in
+  esac
+  _seen=""; { IFS= read -r _seen < "$MARK"; } 2>/dev/null; [ "${_seen%$'\r'}" = "$VER" ] && exit 0
+fi
+
+# ---- CREW-I18N ------------------------------------------------------------------------------------------
+# Same contract as preflight.sh: the installer exports CREW_LANG; run on its own (doctor), the locale decides.
+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() {
+  [ -n "${1:-}" ] || { _M=""; return 0; }
+  local s="$1"; shift
+  if [ "$CREW_LANG" = tr ]; then
+    case "$s" in
+      "⭐ If Crewforth saves you a review round, a star helps others find it: %s") s='⭐ Crewforth bir inceleme turunu kurtardıysa, bir yıldız başkalarının da bulmasına yardım eder: %s' ;;
+      *) [ -n "${CREW_I18N_MISS:-}" ] && printf '%s\n' "$s" >> "$CREW_I18N_MISS" ;;
+    esac
+  fi
+  # shellcheck disable=SC2059
+  printf -v _M -- "$s" "$@"
+}
+# ---- /CREW-I18N -----------------------------------------------------------------------------------------
+
+_mt '⭐ If Crewforth saves you a review round, a star helps others find it: %s' "$CREW_REPO_URL"
+# The marker only after the line actually went out: a closed stdout must not record "shown".
+if printf '%s\n' "$_M" && [ -n "$MARK" ]; then
+  { printf '%s\n' "$VER" > "$MARK"; } 2>/dev/null
+fi
+exit 0