crewforth 3.4.0 → 3.5.0-rc.2

package/kit/eval/lib/lockfiles.sh

@@ -0,0 +1,71 @@
+# Sourced, not run. The ONE list of lockfiles, and the ONE way to find the staged ones, for the two sides of §4.7:
+# guard-bash.sh (reads the audit record back) and skills/dependency-audit/scripts/record.sh (writes it). Both hash
+# what crew_staged_lockfiles returns, so a second copy of the list would let them disagree on which files were
+# audited and turn a correct record into a refusal (or the reverse).
+#
+# Lockfiles, not manifests: a lockfile changes when the RESOLVED set changes, which is what an audit judges. A
+# manifest also changes for a script, a description or a version field, and gating those would ask for an audit
+# that has nothing new to read. (npm's and uv's lockfiles carry the project's own version, so a release bump does
+# trip the gate — the one moment an audit is due anyway.) Left out on purpose: flake.lock and .terraform.lock.hcl,
+# which pin no package ecosystem dependency-audit can read, so every commit touching them would be `unverified`.
+#
+# Every function takes the WORK-TREE TOP. git prints staged paths from the top, and they are handed back to git as
+# pathspecs, so the two must agree: run from a subfolder, the pathspecs named nothing and the diff hashed to the
+# empty blob (found in review: a valid record refused).
+
+# rc 0 when the path's file name is a lockfile.
+crew_is_lockfile(){
+  case "${1##*/}" in
+    package-lock.json|npm-shrinkwrap.json|yarn.lock|pnpm-lock.yaml|bun.lock|bun.lockb|deno.lock) return 0 ;;
+    uv.lock|poetry.lock|Pipfile.lock|pdm.lock|pixi.lock|renv.lock|conan.lock) return 0 ;;
+    Cargo.lock|go.sum|Gemfile.lock|composer.lock|mix.lock|pubspec.lock) return 0 ;;
+    packages.lock.json|paket.lock|*gradle.lockfile|Package.resolved|Podfile.lock|Cartfile.resolved) return 0 ;;
+  esac
+  return 1
+}
+
+# crew_staged_lockfiles <top> -> CREW_LOCKS: the staged lockfiles, an array in git's order. One git process.
+# -z, because without it git QUOTES a path with a non-ASCII byte in it ("\305\237/package-lock.json"): the file name
+# then ends in `"` and is not a lockfile, so a lockfile in a folder named in Turkish passed the gate unaudited.
+# --diff-filter=d: a deleted lockfile has nothing left to audit (deleting one is §4.5's business).
+crew_staged_lockfiles(){
+  local p
+  CREW_LOCKS=()
+  while IFS= read -r -d '' p; do
+    crew_is_lockfile "$p" && CREW_LOCKS+=("$p")
+  done < <(git -C "${1:-.}" -c core.fsmonitor= diff --cached --name-only --no-renames --diff-filter=d -z 2>/dev/null)
+  return 0
+}
+
+# crew_lockfile_pending <top> -> rc 0 when a lockfile differs from HEAD anywhere: staged, changed in the work tree,
+# or new and untracked. For a command that stages AND commits in one call (`git add -A && git commit`): the hook
+# reads the index before the command runs, so what is staged then is not what lands. One git process.
+crew_lockfile_pending(){
+  local e
+  while IFS= read -r -d '' e; do
+    # A porcelain entry is "XY path"; a rename's second field is the bare original path. Both are tested.
+    crew_is_lockfile "${e:3}" && return 0
+    crew_is_lockfile "$e" && return 0
+  done < <(git -C "${1:-.}" -c core.fsmonitor= status --porcelain=v1 -z --untracked-files=all 2>/dev/null)
+  return 1
+}
+
+# crew_lock_oid <top> -> CREW_LOCK_OID: the object id of the staged diff of CREW_LOCKS alone, or "" when there is no
+# such diff to hash. Code staged beside the lockfiles does not change it, so an audit stays valid while the rest of
+# the commit is still being edited.
+#   --literal-pathspecs: a lockfile under a folder named `[x]` is a path, not a glob.
+#   --full-index: the `index` lines carry full object ids, so core.abbrev or the repository's size cannot change the
+#     text, and with it the id, between the audit and the commit.
+#   pipefail and the empty blob: a diff that FAILS still hands hash-object empty input, and both sides would then
+#     agree on e69de29… (found in review). A staged lockfile change is never an empty diff, so that id means "none".
+crew_lock_oid(){
+  CREW_LOCK_OID="$( set -o pipefail
+    git -C "${1:-.}" -c core.fsmonitor= --literal-pathspecs diff --cached --full-index --no-ext-diff --no-textconv -- "${CREW_LOCKS[@]}" 2>/dev/null \
+      | git hash-object --stdin 2>/dev/null )" || CREW_LOCK_OID=""
+  case "$CREW_LOCK_OID" in e69de29bb2d1d6434b8b29ae775ad8c2e48c5391|473a0f4c3be8a93681a267e3b1e9a7dcda1185436fe141f7749120a303721813) CREW_LOCK_OID="" ;; esac   # the empty blob, SHA-1 and SHA-256
+  return 0
+}
+
+# The record's file: crew_git_dir (gate-log.sh) must be loaded. Inside the git directory, so it is never committed,
+# needs no .gitignore line on any install, and each linked worktree keeps its own.
+CREW_DEPS_RECORD=crewforth-deps-audit.json

package/kit/eval/lib/payload-check.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# payload-check.sh KIT_DIR — is this payload whole enough to install? start.sh and adopt.sh run it before their first
+# write, so a broken download (a truncated archive, a copy that lost a folder, a hook settings.json names but the
+# payload does not carry) stops with "nothing installed" instead of leaving a half install whose gates are missing.
+# Read-only and quick: file tests and one read of settings.json, no node, no network. Prints one problem per line
+# (paths relative to KIT_DIR) and exits 1 when there is any, 0 when there is none, 2 on bad usage.
+# CREW_PAYLOAD_UNCHECKED=1 skips it (the installers say so); it exists for a payload someone trimmed on purpose.
+set -uo pipefail
+K="${1:-}"
+[ -n "$K" ] && [ -d "$K" ] || { echo "usage: payload-check.sh KIT_DIR" >&2; exit 2; }
+P=""
+# The files every install copies and every gate depends on.
+for f in CLAUDE.md settings.json hooks/pre-commit hooks/commit-msg hooks/guard-bash.sh hooks/guard-write.sh \
+         eval/doctor.sh eval/lib/settings-json.awk; do
+  [ -s "$K/$f" ] || P="$P"$'\n'"missing or empty: $f"
+done
+for d in agents skills hooks eval; do [ -d "$K/$d" ] || P="$P"$'\n'"missing folder: $d/"; done
+# Every hook settings.json wires is in the payload: a missing one is a gate that fails on every tool call.
+if [ -f "$K/settings.json" ]; then
+  while IFS= read -r h; do
+    [ -s "$K/hooks/$h" ] || P="$P"$'\n'"settings.json names hooks/$h, which the payload does not carry"
+  done < <(grep -o '\.claude/hooks/[A-Za-z0-9._-]*' "$K/settings.json" | sed 's|^\.claude/hooks/||' | LC_ALL=C sort -u)
+fi
+# A skill folder without its SKILL.md and an empty agent file load as nothing, silently.
+for s in "$K"/skills/*/; do [ -d "$s" ] || continue; [ -s "${s}SKILL.md" ] || P="$P"$'\n'"skills/$(basename "$s")/SKILL.md is missing or empty"; done
+for a in "$K"/agents/*.md; do [ -e "$a" ] || continue; [ -s "$a" ] || P="$P"$'\n'"agents/$(basename "$a") is empty"; done
+[ -z "$P" ] && exit 0
+printf '%s\n' "${P#$'\n'}"
+exit 1

package/kit/eval/lib/preview.sh

@@ -66,7 +66,7 @@ _crew_preview(){
   esac
   case "$kind" in
     reset)
-      n="$(git status --porcelain --untracked-files=no 2>/dev/null | wc -l)"; n="${n//[!0-9]/}"
+      n="$(git -c core.fsmonitor= status --porcelain --untracked-files=no 2>/dev/null | wc -l)"; n="${n//[!0-9]/}"
       _pv_words "$cmd" reset; t=""
       for w in $_PV_W; do case "$w" in -*) ;; *) t="$w"; break ;; esac; done
       a=""
@@ -82,7 +82,7 @@ _crew_preview(){
         -*) case "$w" in --*) ;; *) case "$w" in *d*) flags="$flags -d" ;; esac; case "$w" in *x*) flags="$flags -x" ;; *X*) flags="$flags -X" ;; esac ;; esac ;;
       esac; done
       # shellcheck disable=SC2086 # the flags are words of our own
-      n="$(git clean $flags 2>/dev/null | wc -l)"; n="${n//[!0-9]/}"
+      n="$(git -c core.fsmonitor= clean $flags 2>/dev/null | wc -l)"; n="${n//[!0-9]/}"
       _CREW_PV="Preview: a dry run (git clean $flags) lists ${n:-0} path(s) it would delete."
       ;;
     push)
@@ -118,7 +118,7 @@ _crew_preview(){
       [ -n "$out" ] && _CREW_PV="Preview: $out."
       ;;
     commit)
-      case " $cmd " in *' -a'*|*' --all'*|*' -[A-Za-z]*a'*) line="$(git diff HEAD --shortstat 2>/dev/null)" ;; *) line="$(git diff --cached --shortstat 2>/dev/null)" ;; esac
+      case " $cmd " in *' -a'*|*' --all'*|*' -[A-Za-z]*a'*) line="$(git -c core.fsmonitor= diff --no-ext-diff --no-textconv HEAD --shortstat 2>/dev/null)" ;; *) line="$(git -c core.fsmonitor= diff --no-ext-diff --no-textconv --cached --shortstat 2>/dev/null)" ;; esac
       line="${line# }"
       _CREW_PV="Preview: ${line:-nothing staged}."
       ;;

package/kit/eval/lib/review-bench/bench.mjs

@@ -209,7 +209,7 @@ export function run(o) {
   const rows = []; let spent = 0;
   try {
     for (const c of cases) {
-      if (o.arm === 'agent' && spent + o.caseBudget > o.maxCost) { rows.push({ id: c.id, skipped: `the run's cap ($${o.maxCost}) would be passed` }); continue; }
+      if (o.arm === 'agent' && spent + o.caseBudget > o.maxCost) { rows.push({ id: c.id, kind: c.kind, stratum: c.stratum, skipped: `the run's cap ($${o.maxCost}) would be passed` }); continue; }
       const b = build(c, tmp);
       let out;
       if (c.kind === 'task') {
@@ -236,6 +236,10 @@ export function summarise(rows, o, spent = 0) {
   const sum = (k) => done.reduce((n, r) => n + (Number(r[k]) || 0), 0);
   return { arm: o.arm, model: o.arm === 'agent' ? o.model : null, advisor: o.arm === 'agent' ? o.advisor ?? null : null, split: o.split, cases: rows.length, ran: done.length,
     tasks: { done: tasks.filter((r) => r.done).length, of: tasks.length }, ms: sum('ms'), advisorCalls: sum('advisorCalls'),
+    // Worst case: a defect row that did not run counts as missed. Recall over the rows that ran can clear a floor the
+    // whole set would miss, because the cap decides which rows run; this is the figure that cannot.
+    recallWorstCase: rec([...defects, ...rows.filter((r) => r.skipped && r.kind === 'defect')]),
+    byStratumWorstCase: Object.fromEntries(['pattern', 'judgement'].map((s) => [s, rec([...defects, ...rows.filter((r) => r.skipped && r.kind === 'defect')].filter((r) => r.stratum === s))])),
     recall: rec(defects), recallNoHint: rec(defects.filter((r) => !r.hint)), recallHint: rec(defects.filter((r) => r.hint)),
     byStratum: Object.fromEntries(['pattern', 'judgement'].map((s) => [s, rec(defects.filter((r) => r.stratum === s))])),
     precision: { matched, of: claims, pct: pct(matched, claims) },
@@ -249,6 +253,7 @@ function main(argv) {
   const line = (n, x) => `${n} ${x.caught}/${x.of}${x.pct === null ? '' : ` (${x.pct}%)`}`;
   console.log(`review-bench · arm ${s.arm}${s.model ? ` (${s.model}${s.advisor ? ` + ${s.advisor} advisor` : ''})` : ''} · split ${s.split} · ${s.ran}/${s.cases} cases`);
   console.log(`  ${line('recall', s.recall)} · ${line('without a hint', s.recallNoHint)} · ${line('with one', s.recallHint)}`);
+  if (s.recallWorstCase.of > s.recall.of) console.log(`  ${line('recall counting the defect rows that did not run as missed', s.recallWorstCase)}`);
   console.log(`  ${line('pattern', s.byStratum.pattern)} · ${line('judgement', s.byStratum.judgement)}`);
   console.log(`  precision ${s.precision.matched}/${s.precision.of}${s.precision.pct === null ? ' (no claim made)' : ` (${s.precision.pct}%)`} · ${s.falseAlarms.length} false alarm(s)${s.arm === 'agent' ? ` · cost $${s.cost}` : ''}`);
   if (s.tasks.of) console.log(`  tasks done ${s.tasks.done}/${s.tasks.of}`);
@@ -260,12 +265,19 @@ function main(argv) {
   let rc = s.errors.length && o.arm === 'agent' ? 1 : 0;
   if (o.floors) {
     const fl = JSON.parse(fs.readFileSync(o.floors, 'utf8'))[o.arm] ?? {};
+    let skippedPass = false;
     for (const [k, v] of Object.entries(fl)) {
       const got = k === 'precision' ? s.precision.pct : k === 'falseAlarms' ? s.falseAlarms.length : (k === 'recall' ? s.recall : s.byStratum[k.replace(/^recall-/, '')])?.pct;
       const ok = k === 'falseAlarms' ? got <= v : got !== null && got !== undefined && got >= v;
-      console.log(`  floor ${k}: ${got} ${k === 'falseAlarms' ? '≤' : '≥'} ${v} ${ok ? 'ok' : 'BELOW THE FLOOR'}`);
+      // A recall floor that holds only because rows were skipped is not a pass: the worst case is checked beside it.
+      const worst = k === 'recall' ? s.recallWorstCase.pct : k.startsWith('recall-') ? s.byStratumWorstCase[k.replace(/^recall-/, '')]?.pct : null;
+      const onlySkipped = ok && worst !== null && worst !== undefined && worst < v;
+      console.log(`  floor ${k}: ${got} ${k === 'falseAlarms' ? '≤' : '≥'} ${v} ${!ok ? 'BELOW THE FLOOR' : onlySkipped ? `NOT A PASS — met only because rows did not run (worst case ${worst})` : 'ok'}`);
       if (!ok) rc = 1;
+      if (onlySkipped) skippedPass = true;
     }
+    // 3: no floor failed on what ran, but one held only because the cap skipped rows. Not 0, and not a measured 1.
+    if (rc === 0 && skippedPass) rc = 3;
   }
   return rc;
 }

package/kit/eval/lib/review-prepass/prepass.mjs

@@ -4,7 +4,8 @@
 //
 //   node prepass.mjs [--root DIR] [--base REF] [--stdout]
 //       default   the staged change (git diff --cached), what the next commit will hold
-//       --base    the working tree against REF (a branch under review: --base origin/next)
+//       --base    the working tree against REF (a branch under review: --base origin/next), and every untracked,
+//                 not ignored file as added in full: git diff never lists a file git does not track
 //       --stdout  print the document, write nothing; otherwise .crewforth/review-prepass.json, through findings.mjs
 //   rc 0 = written (or printed), whatever it found · 1 = the document did not verify, nothing written ·
 //   2 = usage, or not a git repository
@@ -41,6 +42,7 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const NAME = 'review-prepass';
 const LARGE = 500;
 const QUOTE = 200;
+const MAX_UNTRACKED = 2 * 1024 * 1024;   // the size crew-map stops reading at, too
 
 const DEBUG = [
   { files: /\.(m?[jt]sx?|cjs|cts|vue|svelte)$/, re: /\bconsole\.(log|debug|trace)\(|^\s*debugger\s*;?\s*$/, what: 'a console call or debugger statement' },
@@ -63,7 +65,8 @@ const LOCKS = {
 const GENERATED = /(^|\/)(dist|build|vendor|node_modules|__snapshots__)\/|\.(g|freezed|gr|pb)\.dart$|\.min\.(js|css)$|\.snap$|\.lock$|-lock\.(json|yaml)$/;
 
 const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
-const git = (root, args) => spawnSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+// core.fsmonitor= : a review of someone else's branch must not start the program its .git/config names.
+const git = (root, args) => spawnSync('git', ['-C', root, '-c', 'core.fsmonitor=', '-c', 'core.quotePath=false', ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
 
 // The added lines of a unified diff with no context: { file, line, text }[] and the files it touches.
 export function addedLines(diff) {
@@ -95,6 +98,29 @@ export function prepass(root = '.', { base = null } = {}) {
   const d = git(rootReal, base ? [...diffArgs, base, '--'] : [...diffArgs, '--cached', '--']);
   if (d.status !== 0) throw new Error(`git diff failed: ${(d.stderr || '').trim().split('\n')[0]}`);
   const { added, files, binary } = addedLines(d.stdout);
+  // Under --base the change is the working tree, and a new file nobody has `git add`ed yet is part of it.
+  let untracked = 0; const unread = [];
+  if (base) {
+    // Paths relative to the root, the way every citation here is read back; a subdirectory root lists its own.
+    const u = git(rootReal, ['ls-files', '--others', '--exclude-standard', '-z']);
+    if (u.status !== 0) throw new Error(`git ls-files failed: ${(u.stderr || '').trim().split('\n')[0]}`);
+    // .crewforth/ holds the tools' own documents (this one included), not the change under review.
+    for (const f of u.stdout.split('\0').filter((x) => x && !x.startsWith('.crewforth/')).sort()) {
+      // Never followed, never read whole when large, never dropped without a word.
+      const skip = (reason) => { untracked++; unread.push({ what: f, reason }); };
+      let st; try { st = fs.lstatSync(path.join(rootReal, f)); } catch { skip('untracked, could not be read'); continue; }
+      if (st.isSymbolicLink()) { skip('an untracked symbolic link: not followed'); continue; }
+      if (!st.isFile()) { skip('untracked, not a regular file'); continue; }
+      if (st.size > MAX_UNTRACKED) { skip('untracked, over 2 MiB: not read'); continue; }
+      let buf; try { buf = fs.readFileSync(path.join(rootReal, f)); } catch { skip('untracked, could not be read'); continue; }
+      untracked++; files.push(f);
+      if (buf.subarray(0, 8000).includes(0)) { binary.push(f); continue; }
+      const text = buf.toString('utf8').split('\n');
+      if (text.length > 1 && text[text.length - 1] === '') text.pop();
+      text.forEach((t, i) => added.push({ file: f, line: i + 1, text: t.replace(/\r$/, '') }));
+    }
+    files.sort(); binary.sort();
+  }
 
   const doc = { schema: SCHEMA_ID, producer: { name: NAME, version: '1' }, findings: [], notMeasured: [] };
   const seen = new Set();
@@ -114,6 +140,7 @@ export function prepass(root = '.', { base = null } = {}) {
   const lines = added.filter((a) => { const t = linesOf(a.file); if (t && t[a.line - 1] === a.text) return true; stale.add(a.file); return false; });
   for (const f of [...stale].sort()) doc.notMeasured.push({ what: f, reason: 'edited again after it was staged: its staged lines are not the ones on disk, so they were not read' });
   for (const f of binary) doc.notMeasured.push({ what: f, reason: 'a binary file: no line to read' });
+  doc.notMeasured.push(...unread);
 
   // ---- secrets: the pre-commit gate's list, minus the project's allowlist ----
   let allow = new Set();
@@ -172,6 +199,8 @@ export function prepass(root = '.', { base = null } = {}) {
     }
   }
   doc.findings.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  // Reported on the summary line, not in the document: the findings schema has no field for it.
+  Object.defineProperty(doc, 'untracked', { value: untracked, enumerable: false });
   return doc;
 }
 
@@ -188,7 +217,7 @@ function main(argv) {
   let doc;
   try { doc = prepass(root, { base }); } catch (e) { console.error(`prepass: ${e.message}`); return 2; }
   const count = (s) => doc.findings.filter((f) => f.severity === s).length;
-  const line = `review-prepass: ${doc.findings.length} finding(s) · high ${count('high')} · medium ${count('medium')} · low ${count('low')} · info ${count('info')} · ${doc.notMeasured.length} not measured`;
+  const line = `review-prepass: ${doc.findings.length} finding(s) · high ${count('high')} · medium ${count('medium')} · low ${count('low')} · info ${count('info')} · ${doc.notMeasured.length} not measured${base ? ` · ${doc.untracked} untracked read` : ''}`;
   if (stdout) {
     const r = validate(doc, root);
     if (!r.ok) { for (const p of r.problems) console.error(`prepass: ${p.at} ${p.code}: ${p.message}`); return 1; }

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

@@ -17,6 +17,11 @@
 #   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=hookcheck -f settings-json.awk FILE   the "hooks" block holds the shape Claude Code accepts: an object of
+#       arrays, each entry an object whose "matcher" (when present) is a string and whose "hooks" is an array of
+#       objects with a string "type", and a string "command" when the type is "command". Claude Code discards the
+#       WHOLE file on a mismatch, every gate with it. rc 0 = fine (or no "hooks"), 1 = one problem per line on
+#       stdout, as hooks.EVENT.N[.hooks.M]: what is wrong, 10 = FILE is not a JSON object.
 #   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
@@ -134,6 +139,19 @@ END{
       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=="hookcheck"){ if(!(r=doc(1))) exit 10; h=get(r,"\"hooks\""); if(!h) exit 0; bad=0
+    if(T[h]!="o"){ print "hooks: not an object"; exit 1 }
+    for(i=1;i<=N[h];i++){ ev=substr(K[h,i],2,length(K[h,i])-2); a=C[h,i]
+      if(T[a]!="a"){ print "hooks." ev ": not an array"; bad=1; continue }
+      for(j=1;j<=N[a];j++){ e=C[a,j]; w="hooks." ev "." (j-1)
+        if(T[e]!="o"){ print w ": not an object"; bad=1; continue }
+        m=get(e,"\"matcher\""); if(m && !(T[m]=="s" && substr(V[m],1,1)=="\"")){ print w ": matcher is not a string"; bad=1 }
+        hs=get(e,"\"hooks\""); if(!hs || T[hs]!="a"){ print w ": no \"hooks\" array"; bad=1; continue }
+        for(k=1;k<=N[hs];k++){ o=C[hs,k]; ww=w ".hooks." (k-1)
+          if(T[o]!="o"){ print ww ": not an object"; bad=1; continue }
+          t=get(o,"\"type\""); if(!t || !(T[t]=="s" && substr(V[t],1,1)=="\"")){ print ww ": no string \"type\""; bad=1; continue }
+          if(V[t]=="\"command\""){ c=get(o,"\"command\""); if(!c || !(T[c]=="s" && substr(V[c],1,1)=="\"")){ print ww ": type command without a string \"command\""; bad=1 } } } } }
+    exit bad }
   # gets: several paths in one read (path = "a.b|c.d"), their values on one line, tab-separated; an absent one is
   # empty. One process for what a hot caller (the status line) would otherwise read with one awk per field.
   if(op=="gets"){ if(!(r=doc(1))) exit 10; n=split(path,pp,"|"); o=""

package/kit/eval/lib/statusline.sh

@@ -12,11 +12,14 @@
 #   ⚙   crew agents started in this session that have not stopped yet (model routing's records)
 #   🔋  the context fill Claude Code measured (context_window.used_percentage), never an estimate
 #   ~$  what Claude Code puts the session's cost at (cost.total_cost_usd), at API list price
+#   📋  the plan's count of done tasks (docs/PLAN.md, todo.sh); with the panel open (/crew-todo), the panel itself is
+#       drawn under the line instead: phases and tasks, ✓ done, ☐ open, ▸ the phase and the task in work
 #
 # Wired by the installers only where no status line is set already (theirs is never replaced), from
 # statusline.settings.json beside this file.
 # COST. Claude Code runs this after every change, debounced at 300 ms. Measured: awk (the stdin JSON) and tail (the
-# gate log), and on bash older than 4.2 one date; the rest is builtins. No git, no jq, no python.
+# gate log), and on bash older than 4.2 one date; the rest is builtins. No git, no jq, no python. The plan panel
+# adds one awk only when the plan (or its drawing code) changed since the last line; otherwise it reads its cache.
 set -u
 _here="${BASH_SOURCE%[/\\]*}"; [ "$_here" = "${BASH_SOURCE}" ] && _here=.
 
@@ -93,8 +96,22 @@ case "${COST:-}" in ''|null|*[!0-9.]*) ;; *)
   printf -v c '%.2f' "$COST" 2>/dev/null && OUT+=("~\$$c") ;;
 esac
 
-[ "${#OUT[@]}" -gt 0 ] || exit 0
-line="${OUT[0]}"
-for p in "${OUT[@]:1}"; do line="$line · $p"; done
-printf '%s\n' "$line"
+# 📋 The plan: its count on the line, or with the panel open (/crew-todo), the panel under it.
+PANEL=""
+if [ -d .claude ] && [ -f "$_here/todo.sh" ]; then
+  . "$_here/todo.sh"
+  if [ -e .claude/state/todo/open ]; then
+    col=1; [ -n "${NO_COLOR:-}" ] && col=0
+    crew_todo_read "$col"; PANEL="$_CREW_TODO_PANEL"
+  elif [ -f docs/PLAN.md ] || [ -s .claude/state/todo/path ]; then
+    crew_todo_read 1; [ -n "$_CREW_TODO_HINT" ] && OUT+=("$_CREW_TODO_HINT")
+  fi
+fi
+
+if [ "${#OUT[@]}" -gt 0 ]; then
+  line="${OUT[0]}"
+  for p in "${OUT[@]:1}"; do line="$line · $p"; done
+  printf '%s\n' "$line"
+fi
+[ -n "$PANEL" ] && printf '%s\n' "$PANEL"
 exit 0

package/kit/eval/lib/todo.awk

@@ -0,0 +1,167 @@
+# todo.awk — reads a plan (docs/PLAN.md by default) and draws its to-do panel: the phases and the tasks, a tick on
+# what is done, an empty box on what is not, and the phase and the task in work marked.
+#
+#   LC_ALL=C awk -v color=1 -v maxl=14 -v name=docs/PLAN.md -f todo.awk docs/PLAN.md
+#
+# Run it under LC_ALL=C: lengths are counted in bytes, so a cut never depends on the locale (and is mended so it never
+# splits a UTF-8 character).
+#
+# What it reads, and nothing else:
+#   a task      a list item whose text starts with a box:  `- [ ] …`  `- [x] …`  `1. [ ] …`  (at the margin)
+#               [ ] open · [x] done · [~] or [>] in work. A box indented under a task is a sub-step, not a task.
+#   a phase     a heading (## or deeper) with at least one task under it.
+#   the scope   when the plan has a `## Tasks` heading (or Görevler, İşler, To-do), only what is under it; else the
+#               whole file. An `Acceptance criteria` section is never a phase: its boxes are counted as AC n/m.
+#   code blocks are skipped (a template quoted in the plan is not the plan).
+# The task in work is the first one marked [~]/[>]; with none marked, the first open one. Its phase is the active one.
+#
+# Output: line 1 the short count for the status line ("📋 7/12"), or nothing when the plan has no task; then the panel.
+# It decides nothing and changes nothing.
+BEGIN {
+  if (maxl + 0 < 6) maxl = 14
+  wmax = 64
+  E = sprintf("%c", 27)
+  if (color + 0) { DIM = E "[2m"; BOLD = E "[1m"; ACT = E "[1;36m"; RST = E "[0m" } else { DIM = BOLD = ACT = RST = "" }
+  for (i = 128; i < 192; i++) CONT = CONT sprintf("%c", i)
+  for (i = 192; i < 256; i++) LEAD = LEAD sprintf("%c", i)
+  TICK = "✓"; BOX = "☐"; HERE = "▸"
+  nev = 0; fence = ""
+}
+
+# A fenced code block: skipped whole.
+/^[ ]*(```|~~~)/ {
+  f = $0; sub(/^[ ]*/, "", f); f = substr(f, 1, 3)
+  if (fence == "") fence = f; else if (f == fence) fence = ""
+  next
+}
+fence != "" { next }
+
+/^#+[ \t]/ {
+  t = $0; match(t, /^#+/); lv = RLENGTH
+  t = substr(t, lv + 1); sub(/^[ \t]+/, "", t); sub(/[ \t]+#*[ \t]*$/, "", t); sub(/\r$/, "", t)
+  nev++; EV[nev] = "H"; LV[nev] = lv; TX[nev] = t
+  next
+}
+
+{
+  line = $0; sub(/\r$/, "", line)
+  match(line, /^ */); ind = RLENGTH
+  if (ind > 1) next
+  rest = substr(line, ind + 1)
+  if (match(rest, /^[-*+][ \t]+\[[ xX~>]\][ \t]+/)) num = ""
+  else if (match(rest, /^[0-9]+[.)][ \t]+\[[ xX~>]\][ \t]+/)) { num = rest; sub(/[.)].*/, "", num) }
+  else next
+  head = substr(rest, 1, RLENGTH); txt = substr(rest, RLENGTH + 1)
+  b = head; sub(/^[^[]*\[/, "", b); b = substr(b, 1, 1)
+  st = (b == "x" || b == "X") ? "d" : (b == "~" || b == ">") ? "w" : "o"
+  # The task's name is what comes before its first " — " (the plan's fields: satisfies, size, risk…).
+  k = index(txt, " — "); if (k > 0) txt = substr(txt, 1, k - 1)
+  sub(/[ \t]+$/, "", txt)
+  if (num != "") txt = num ". " txt
+  nev++; EV[nev] = "I"; ST[nev] = st; TX[nev] = txt
+}
+
+function isac(t) { return t ~ /^([Aa]cceptance [Cc]riteria|[Kk]abul [Kk]riter)/ }
+function istasks(t) { return t ~ /^([Tt]asks|TASKS|[Gg]örevler|GÖREVLER|[İi]şler|İŞLER|[Tt]o-?[Dd]o|TODO)([^A-Za-z]|$)/ }
+# A cut in bytes that never leaves half a UTF-8 character: drop trailing continuation bytes, then their lead byte.
+function cut(s, n,   r) {
+  if (length(s) <= n) return s
+  r = substr(s, 1, n - 1)
+  while (length(r) && index(CONT, substr(r, length(r), 1))) r = substr(r, 1, length(r) - 1)
+  if (length(r) && index(LEAD, substr(r, length(r), 1))) r = substr(r, 1, length(r) - 1)
+  return r "…"
+}
+function mark(st) { return st == "d" ? TICK : st == "w" ? HERE : BOX }
+function out(s) { L[++nl] = s }
+
+END {
+  # The scope: under a Tasks heading when the plan has one.
+  s0 = 1; s1 = nev; base = 1; title = ""
+  for (i = 1; i <= nev; i++) if (EV[i] == "H" && LV[i] == 1 && title == "") title = TX[i]
+  for (i = 1; i <= nev; i++) if (EV[i] == "H" && LV[i] >= 2 && istasks(TX[i])) {
+    s0 = i + 1; s1 = nev; base = LV[i]
+    for (j = i + 1; j <= nev; j++) if (EV[j] == "H" && LV[j] <= LV[i]) { s1 = j - 1; break }
+    break
+  }
+  # Acceptance criteria, wherever they are: counted, never shown as a phase.
+  ac = 0; acd = 0; inac = 0
+  for (i = 1; i <= nev; i++) {
+    if (EV[i] == "H") { if (inac && LV[i] <= aclv) inac = 0; if (isac(TX[i])) { inac = 1; aclv = LV[i] } }
+    else if (inac) { ac++; if (ST[i] == "d") acd++ }
+  }
+  # Phases and tasks inside the scope. A heading opens a phase; tasks before any heading sit in an unnamed one.
+  np = 0; cur = 0; skip = 0; skiplv = 0; nt = 0; done = 0
+  for (i = s0; i <= s1; i++) {
+    if (EV[i] == "H") {
+      if (skip && LV[i] <= skiplv) skip = 0
+      if (LV[i] <= base && base > 1) continue
+      if (isac(TX[i]) || (LV[i] == 1 && base == 1)) { if (isac(TX[i])) { skip = 1; skiplv = LV[i] }; cur = 0; continue }
+      if (skip) continue
+      np++; PN[np] = TX[i]; PT[np] = 0; PD[np] = 0; cur = np
+      continue
+    }
+    if (skip) continue
+    if (cur == 0) { np++; PN[np] = ""; PT[np] = 0; PD[np] = 0; cur = np }
+    PT[cur]++; nt++; T[cur, PT[cur]] = i
+    if (ST[i] == "d") { PD[cur]++; done++ }
+  }
+  if (nt == 0) { print ""; print "📋 " cut(name != "" ? name : FILENAME, wmax) ": no task with a box yet ( - [ ] task · - [x] done · - [~] in work )"; exit }
+
+  # The task in work: the first marked [~]/[>], else the first open one.
+  ap = 0; at = 0
+  for (p = 1; p <= np && !ap; p++) for (t = 1; t <= PT[p]; t++) if (ST[T[p, t]] == "w") { ap = p; at = t; break }
+  for (p = 1; p <= np && !ap; p++) for (t = 1; t <= PT[p]; t++) if (ST[T[p, t]] == "o") { ap = p; at = t; break }
+
+  # Phases with no task are not phases.
+  m = 0
+  for (p = 1; p <= np; p++) if (PT[p] > 0) { m++; PN[m] = PN[p]; PT[m] = PT[p]; PD[m] = PD[p]; for (t = 1; t <= PT[p]; t++) T[m, t] = T[p, t]; if (p == ap) ap = m }
+  np = m
+  phased = (np > 1 || PN[1] != "")
+
+  print "📋 " done "/" nt
+  hd = BOLD "📋 " (title != "" ? cut(title, wmax) : "Plan") RST " · " done "/" nt " done"
+  if (phased && ap) hd = hd " · phase " ap "/" np
+  if (ac) hd = hd " · AC " acd "/" ac
+  if (!ap) hd = hd " · all done"
+  out(hd)
+
+  # Which phases get a line: all of them when they fit, else the active one with its neighbours and a count of the rest.
+  budget = maxl - 1
+  pa = 1; pb = np
+  if (phased && np > budget - 3) {
+    c = (ap ? ap : np); pa = c - 1; if (pa < 1) pa = 1; pb = pa + (budget - 6); if (pb > np) pb = np
+    if (pb - pa < budget - 6) { pa = pb - (budget - 6); if (pa < 1) pa = 1 }
+  }
+  # The tasks of the active phase (or of the plan, when it has no phases) get what is left.
+  room = budget - (phased ? (pb - pa + 1) + (pa > 1) + (pb < np) : 0)
+  if (room < 3) room = 3
+
+  if (phased && pa > 1) { k = 0; for (p = 1; p < pa; p++) k += (PD[p] == PT[p]); out(DIM "… " (pa - 1) " phase" (pa > 2 ? "s" : "") " before (" k " done)" RST) }
+  for (p = (phased ? pa : 1); p <= (phased ? pb : 1); p++) {
+    if (phased) {
+      nm = (PN[p] != "" ? cut(PN[p], wmax) : "(no phase)") "  " PD[p] "/" PT[p]
+      if (p == ap) out(ACT HERE " " nm RST)
+      else if (PD[p] == PT[p]) out(DIM TICK " " nm RST)
+      else out(BOX " " nm)
+    }
+    if (p != ap && !(phased == 0 && !ap)) continue
+    # A window over the tasks that keeps the one in work in sight: one before it, the rest after.
+    n = PT[p]; lo = 1; hi = n
+    if (n > room) {
+      lo = (at > 1 ? at - 1 : 1)
+      hi = (lo == 1) ? room - 1 : lo + room - 3
+      if (hi >= n) { hi = n; lo = n - room + 2; if (lo < 1) lo = 1 }
+    }
+    ind = (phased ? "   " : "")
+    if (lo > 1) out(ind DIM "… " (lo - 1) " above" RST)
+    for (t = lo; t <= hi; t++) {
+      e = T[p, t]; s = mark(ST[e]) " " cut(TX[e], wmax)
+      if (t == at && p == ap) out(ind ACT HERE " " cut(TX[e], wmax) RST)
+      else if (ST[e] == "d") out(ind DIM s RST)
+      else out(ind s)
+    }
+    if (hi < n) out(ind DIM "… " (n - hi) " more" RST)
+  }
+  if (phased && pb < np) { k = 0; for (p = pb + 1; p <= np; p++) k += PT[p] - PD[p]; out(BOX " … " (np - pb) " more phase" (np - pb > 1 ? "s" : "") " (" k " open)") }
+  for (i = 1; i <= nl; i++) print L[i]
+}

package/kit/eval/lib/todo.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# todo.sh — the plan's to-do panel: what is done (✓), what is not (☐), and the phase and the task in work (▸), read
+# from the plan file (docs/PLAN.md unless /crew-todo named another). The drawing is todo.awk; this file keeps the
+# panel's two bits of state and serves both its readers.
+#
+#   bash .claude/eval/lib/todo.sh             open the panel if it is closed, close it if it is open
+#   bash .claude/eval/lib/todo.sh on [FILE]   open it (and read FILE from now on)        · off: close it
+#   bash .claude/eval/lib/todo.sh FILE        the same as `on FILE`
+#   bash .claude/eval/lib/todo.sh show [FILE] print the panel here, once (no status line needed)
+#   bash .claude/eval/lib/todo.sh status      one line: open or closed, which file, how far
+#
+# The status line sources this file and calls crew_todo_read: open, the panel is drawn under the line; closed, the
+# line carries only the count ("📋 7/12"). Nothing here decides or blocks anything, and the plan is never written:
+# the plan's own boxes are the record ([ ] open · [x] done · [~] in work), ticked by whoever does the work.
+#
+# State, per project, under .claude/state/todo/: `open` (present = the panel is open) and `path` (the plan file, when
+# it is not docs/PLAN.md); `view` is a cache of the drawing, made again only when the plan, todo.awk or the settings
+# changed, so a status line refresh costs no process at all while the plan stands still.
+# Settings: CREW_TODO_LINES (the panel's height, default 14) · NO_COLOR (set: no colours).
+
+_CREW_TODO_LIB="${BASH_SOURCE%[/\\]*}"; [ "$_CREW_TODO_LIB" = "${BASH_SOURCE}" ] && _CREW_TODO_LIB=.
+_CREW_TODO_DIR=.claude/state/todo
+
+# The plan file this project's panel reads: _CREW_TODO_PLAN. Run from the project root.
+crew_todo_plan(){
+  _CREW_TODO_PLAN=""
+  [ -s "$_CREW_TODO_DIR/path" ] && { IFS= read -r _CREW_TODO_PLAN < "$_CREW_TODO_DIR/path"; _CREW_TODO_PLAN="${_CREW_TODO_PLAN%$'\r'}"; }
+  [ -n "$_CREW_TODO_PLAN" ] || _CREW_TODO_PLAN=docs/PLAN.md
+}
+
+# The drawing: _CREW_TODO_HINT (the count, "" when the plan has no task) and _CREW_TODO_PANEL (its lines, joined with
+# newlines). $1 = color (1/0). From the cache when the cache still matches; one awk when it does not.
+crew_todo_read(){
+  local col="${1:-1}" maxl="${CREW_TODO_LINES:-14}" v="$_CREW_TODO_DIR/view" key l first=1
+  _CREW_TODO_HINT=""; _CREW_TODO_PANEL=""
+  case "$maxl" in ''|*[!0-9]*) maxl=14 ;; esac
+  crew_todo_plan
+  if [ ! -f "$_CREW_TODO_PLAN" ]; then
+    _CREW_TODO_PANEL="📋 no plan at $_CREW_TODO_PLAN yet: /crew-plan writes one, /crew-todo <file> reads another"
+    return 0
+  fi
+  key="k=$col/$maxl/$_CREW_TODO_PLAN"
+  # The cache holds when it is newer than the plan and than the drawing code, and was drawn with these settings.
+  if [ -f "$v" ] && [ "$v" -nt "$_CREW_TODO_PLAN" ] && ! [ "$_CREW_TODO_LIB/todo.awk" -nt "$v" ]; then
+    IFS= read -r l < "$v" 2>/dev/null || l=""
+    [ "$l" = "$key" ] || l=""
+  else l=""; fi
+  if [ -z "$l" ]; then
+    [ -d "$_CREW_TODO_DIR" ] || mkdir -p "$_CREW_TODO_DIR" 2>/dev/null
+    { printf '%s\n' "$key"; LC_ALL=C awk -v color="$col" -v maxl="$maxl" -v name="$_CREW_TODO_PLAN" -f "$_CREW_TODO_LIB/todo.awk" "$_CREW_TODO_PLAN" 2>/dev/null; } > "$v" 2>/dev/null || return 0
+  fi
+  {
+    IFS= read -r l                                     # the key
+    IFS= read -r _CREW_TODO_HINT
+    while IFS= read -r l; do
+      if [ "$first" = 1 ]; then _CREW_TODO_PANEL="$l"; first=0; else _CREW_TODO_PANEL="$_CREW_TODO_PANEL"$'\n'"$l"; fi
+    done
+  } < "$v"
+  return 0
+}
+
+# Sourced: the functions only.
+[ "${BASH_SOURCE[0]}" = "$0" ] || return 0
+
+set -u
+[ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "$CLAUDE_PROJECT_DIR/.claude" ] && cd "$CLAUDE_PROJECT_DIR" 2>/dev/null
+if [ ! -d .claude ]; then echo "todo: no .claude/ here: run it from the project root of a Crewforth install" >&2; exit 1; fi
+
+cmd="${1:-toggle}"; file="${2:-}"
+case "$cmd" in on|off|toggle|show|status) ;; -h|--help) sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  -*) echo "todo: unknown option $cmd (on · off · show · status · a plan file)" >&2; exit 2 ;;
+  *) file="$cmd"; cmd=on ;;
+esac
+case "$file" in *$'\n'*|*$'\r'*) echo "todo: a file name with a line break is not read" >&2; exit 2 ;; esac
+
+if [ "$cmd" = show ]; then
+  # Drawn here, not from the cache, and coloured only on a terminal: this may go to a chat that does not take colour.
+  crew_todo_plan; [ -n "$file" ] && _CREW_TODO_PLAN="$file"
+  if [ ! -f "$_CREW_TODO_PLAN" ]; then echo "📋 no plan at $_CREW_TODO_PLAN yet: /crew-plan writes one"; exit 0; fi
+  c=0; [ -t 1 ] && [ -z "${NO_COLOR:-}" ] && c=1
+  LC_ALL=C awk -v color="$c" -v maxl=999 -v name="$_CREW_TODO_PLAN" -f "$_CREW_TODO_LIB/todo.awk" "$_CREW_TODO_PLAN" | sed 1d
+  exit 0
+fi
+
+mkdir -p "$_CREW_TODO_DIR" 2>/dev/null || { echo "todo: cannot write $_CREW_TODO_DIR" >&2; exit 1; }
+if [ -n "$file" ]; then
+  [ -f "$file" ] || echo "todo: $file does not exist yet; the panel will read it once it does"
+  if [ "$file" = docs/PLAN.md ]; then rm -f "$_CREW_TODO_DIR/path"; else printf '%s\n' "$file" > "$_CREW_TODO_DIR/path"; fi
+fi
+[ "$cmd" = toggle ] && { if [ -e "$_CREW_TODO_DIR/open" ]; then cmd=off; else cmd=on; fi; }
+case "$cmd" in
+  on) : > "$_CREW_TODO_DIR/open" ;;
+  off) rm -f "$_CREW_TODO_DIR/open" ;;
+esac
+
+crew_todo_read 0
+st=closed; [ -e "$_CREW_TODO_DIR/open" ] && st=open
+how=""
+if [ -n "$_CREW_TODO_HINT" ]; then
+  how="${_CREW_TODO_HINT#📋 } done"
+  inwork="$(printf '%s\n' "$_CREW_TODO_PANEL" | grep '▸ ' | tail -n 1 | sed 's/^ *▸ //')"
+  [ -n "$inwork" ] && how="$how, in work: $inwork"
+elif [ -f "$_CREW_TODO_PLAN" ]; then how="no task with a box in it yet"
+else how="the file does not exist yet"; fi
+if [ "$st" = open ]; then echo "plan panel: open · $_CREW_TODO_PLAN · $how"
+else echo "plan panel: closed · $_CREW_TODO_PLAN · $how (the status line keeps the count)"; fi
+
+# Shown under Crewforth's status line only. Say so when this project's status line is another one, or none.
+sl=""
+for f in .claude/settings.local.json .claude/settings.json "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"; do
+  [ -f "$f" ] && [ -f "$_CREW_TODO_LIB/settings-json.awk" ] || continue
+  sl="$(awk -v op=get -v path=statusLine.command -f "$_CREW_TODO_LIB/settings-json.awk" "$f" 2>/dev/null)" || sl=""
+  [ -n "$sl" ] && break
+done
+case "$sl" in
+  *eval/lib/statusline.sh*) ;;
+  ?*) [ "$st" = open ] && echo "note: this project's status line is not Crewforth's, so the panel does not show there; /crew-todo show prints it here" ;;
+  *) [ "$st" = open ] && echo "note: no status line is set; bash .claude/eval/lib/statusline.sh --install (Bash tool, not PowerShell) sets Crewforth's (only where none is set), or /crew-todo show prints the panel here" ;;
+esac
+exit 0