crewforth 3.3.0 → 3.5.0-rc.1

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/untrusted-text.awk

@@ -0,0 +1,38 @@
+# untrusted-text.awk — make text other people wrote safe to put into a model's context, line by line.
+#
+#   LC_ALL=C awk -f untrusted-text.awk < text
+#
+# Text a hook injects (a teammate's board title, a decision's author) reaches the model with the authority of
+# the hook that carried it. This does not decide what the text means; it removes what can hide or disguise it:
+#   - C0 controls other than tab, DEL, and the C1 controls (U+0080-U+009F), which a terminal or a renderer acts on;
+#   - zero-width and direction marks: U+200B-U+200F, U+202A-U+202E, U+2066-U+2069 (a bidi override shows a line
+#     in an order other than the order the model reads it in);
+#   - `<` and `>`, so no line can open or close a tag-shaped block, which become ‹ and ›;
+#   - a line that starts with `#`, three backticks or `---`, which could pass for a heading, a fence or a frontmatter
+#     break, gets a leading `| `.
+# Run under LC_ALL=C: every pattern is a byte sequence of UTF-8, so the result does not depend on the locale.
+BEGIN {
+  bad = ""
+  # U+200B-U+200F: E2 80 8B..8F · U+202A-U+202E: E2 80 AA..AE · U+2066-U+2069: E2 81 A6..A9
+  for (b = 139; b <= 143; b++) bad = bad (bad == "" ? "" : "|") sprintf("%c%c%c", 226, 128, b)
+  for (b = 170; b <= 174; b++) bad = bad "|" sprintf("%c%c%c", 226, 128, b)
+  for (b = 166; b <= 169; b++) bad = bad "|" sprintf("%c%c%c", 226, 129, b)
+  # C1 controls as UTF-8: C2 80..9F
+  for (b = 128; b <= 159; b++) bad = bad "|" sprintf("%c%c", 194, b)
+  ctl = ""
+  for (b = 1; b <= 31; b++) if (b != 9) ctl = ctl (ctl == "" ? "" : "|") sprintf("%c", b)
+  ctl = ctl "|" sprintf("%c", 127)
+  lt = sprintf("%c%c%c", 226, 128, 185)   # ‹
+  gt = sprintf("%c%c%c", 226, 128, 186)   # ›
+}
+{
+  sub(/\r$/, "")
+  # Control bytes first, then the marks until none is left: removing one can join the bytes around it into
+  # another (E2 01 80 AE, or E2 · E2 80 8B · 80 AE, both become U+202E after one pass).
+  gsub(ctl, "")
+  while (gsub(bad, "") > 0) ;
+  gsub(/</, lt); gsub(/>/, gt)
+  t = $0; sub(/^[ \t]+/, "", t)
+  if (t ~ /^#/ || t ~ /^```/ || t ~ /^---/) $0 = "| " $0
+  print
+}

package/kit/eval/scan-skill.sh

@@ -15,6 +15,8 @@
 # are different answers, and only one of them belongs on a security surface.
 # Usage:  bash scan-skill.sh [path]   (default: .claude)
 set -uo pipefail
+# The C locale, so the byte patterns below are matched as bytes and `-i` folds ASCII only (as in every other gate).
+export LC_ALL=C
 TARGET="${1:-.claude}"
 
 # --- pattern groups (ERE) ------------------------------------------------------------------------------------
@@ -31,11 +33,51 @@ CRIT='(curl|wget|fetch)[^|]*\|[[:space:]]*(sudo[[:space:]]+)?(bash|sh|zsh|python
 # 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)'
+# A HIDDEN INSTRUCTION in an HTML comment: it renders as nothing in a Markdown preview and in a PR's rich diff, and the
+# model reads it like any other line. Only a comment that OPENS on an imperative is flagged, so Crewforth's own
+# machine-readable markers (`<!-- routing-eval …`, `<!-- Requires-tool …`) and explanatory comments stay clean.
+HIGH="$HIGH"'|<!--[[:space:]]*(ignore|disregard|forget|override|run|execute|send|post|upload|fetch|download|install|delete|remove|exfiltrate|you[[:space:]]+(must|should|are|will)|do[[:space:]]+not|always|never)([^a-z]|$)'
+# INVISIBLE TEXT, as UTF-8 bytes (one more grep, in the C locale): Unicode tag characters (U+E0000-E007F, which spell
+# ASCII nobody sees), bidi overrides and isolates (U+202A-202E, U+2066-2069, which reorder what an editor shows), and a
+# zero-width character (U+200B-200D, U+2060, U+FEFF) BETWEEN two letters, where it splits a word a pattern would catch
+# (`ign<ZWSP>ore previous instructions`). A BOM at the start of a file is not between letters and is not flagged.
+# Reported as a count only: printing the decoded text would put the hidden instruction in front of the reader.
+_ZW='('$'\xe2\x80\x8b''|'$'\xe2\x80\x8c''|'$'\xe2\x80\x8d''|'$'\xe2\x81\xa0''|'$'\xef\xbb\xbf'')'
+INVIS=$'\xf3\xa0[\x80\x81]|\xe2\x80[\xaa\xab\xac\xad\xae]|\xe2\x81[\xa6\xa7\xa8\xa9]|[A-Za-z]'"$_ZW"'+[A-Za-z]'
 # 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'
 
+# FRONTMATTER: what a component asks the HOST for, read from its YAML header — one awk over all files. A `hooks:` or
+# `mcpServers:` key (it brings its own code to run), a `permissionMode:` other than default/plan/manual, and an
+# `allowed-tools:` entry that is a bare `Bash` or a `Bash(…)` rule with `*` in it (any command, or any arguments).
+# The one `*` rule not counted is a call of the component's OWN script: `Bash(bash ${CLAUDE_SKILL_DIR}/…)` reaches
+# only files that ship inside the skill, and the scan already reads those. Anywhere in the file, a `!`cmd`` line
+# counts too: it runs when the component loads, before anyone reads it.
+FM_AWK='
+function tools(v,   n, m, inner) {
+  n = 0; sub(/^[[:space:]]*-[[:space:]]*/, "", v)
+  if (v ~ /(^|[^A-Za-z])Bash([^A-Za-z(]|$)/) n++
+  if (v ~ /(^|[,[:space:]])\*([,[:space:]]|$)/) n++
+  while (match(v, /Bash\([^)]*\)/)) {
+    inner = substr(v, RSTART + 5, RLENGTH - 6); v = substr(v, RSTART + RLENGTH)
+    if (inner ~ /\*/ && inner !~ /^((bash|sh)[[:space:]]+)?\$\{CLAUDE_SKILL_DIR\}\//) n++
+  }
+  return n }
+FNR == 1 { if (NR > 1) print f ":" c; f = FILENAME; c = 0; key = ""; sub(/^\357\273\277/, ""); fm = ($0 ~ /^---[[:space:]]*$/); if (fm) next }
+fm && /^---[[:space:]]*$/ { fm = 0; next }
+fm {
+  if ($0 ~ /^[A-Za-z]/) { key = $0; sub(/:.*/, "", key) }
+  if ($0 ~ /^(hooks|mcpServers):/) c++
+  if ($0 ~ /^permissionMode:/) { v = $0; sub(/^permissionMode:/, "", v); gsub(/["\047[:space:]]/, "", v)
+    if (v != "" && v != "default" && v != "plan" && v != "manual") c++ }
+  if (key == "allowed-tools") { v = $0; sub(/^allowed-tools:/, "", v); c += tools(v) }
+}
+/(^|[[:space:]])!`[^`]+`/ { c++ }
+END { if (NR > 0) print f ":" c }'
+fm_counts(){ awk "$FM_AWK" "$@" 2>/dev/null; return 0; }   # `path:count` per non-empty file, in the order given
+
 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
@@ -81,36 +123,38 @@ emit(){        # prints one line per file, in FILES order, from the four count a
   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}"
+    report "$f" "$c" "$h" "${CNT_I[$i]:-0}" "${CNT_F[$i]:-0}" "$m" "$l"
     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
 }
 
+# One file's line. Invisible text and frontmatter requests score as HIGH and are named beside the counts: the reader
+# cannot see the first in an editor, and should not have to guess which header line the second is.
+report(){      # $1 file, $2 crit, $3 high, $4 invisible, $5 frontmatter, $6 med, $7 low
+  local f="$1" c="$2" h=$(( $3 + $4 + $5 )) m="$6" l="$7" score v x=""
+  [ "$4" -gt 0 ] && x="$x · invisible characters: $4"
+  [ "$5" -gt 0 ] && x="$x · frontmatter requests: $5"
+  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%s) — REVIEW\n' "$score" "$f" "$c" "$h" "$m" "$l" "$x"; FAIL=1 ;;
+    DANGER) printf '  ❌ %-3s %s  (crit:%s high:%s med:%s low:%s%s) — DANGER\n' "$score" "$f" "$c" "$h" "$m" "$l" "$x"; FAIL=1 ;;
+  esac
+}
+
 # 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
+  local c h m l iv fm
   # 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
+  iv=$(grep -cE "$INVIS" "$f" 2>/dev/null); fm=$(fm_counts "$f"); fm="${fm##*:}"
+  report "$f" "${c:-0}" "${h:-0}" "${iv:-0}" "${fm:-0}" "${m:-0}" "${l:-0}"
 }
 
 echo "== skill/agent security scan: $TARGET =="
@@ -141,12 +185,15 @@ elif [ -d "$TARGET" ]; then
     ST="$(mktemp -d)"
     counts_of "$CRIT" "$ST/c"; counts_of "$HIGH" "$ST/h"
     counts_of "$MED"  "$ST/m"; counts_of "$LOW"  "$ST/l"
+    grep -cHE "$INVIS" -- "${FILES[@]}" > "$ST/i" 2>/dev/null; fm_counts "${FILES[@]}" > "$ST/f"
     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
+    read_counts "$ST/i" CNT_I; NI=$RC_N;  read_counts "$ST/f" CNT_F; NF=$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
+    # misaligned count would score the wrong file. Fall back to the per-file path rather than report a guess. awk
+    # prints nothing for an empty file, so one empty file sends the whole run down that path: correct, only slower.
+    if [ "$NC" = "${#FILES[@]}" ] && [ "$NH" = "$NC" ] && [ "$NM" = "$NC" ] && [ "$NL" = "$NC" ] && [ "$NI" = "$NC" ] && [ "$NF" = "$NC" ]; then
       emit
     else
       for f in "${FILES[@]}"; do scan_file "$f"; done