crewforth 3.4.0 → 3.5.0-rc.2

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

@@ -16,9 +16,13 @@ export const SKIP_DIRS = new Set(['.git', '.hg', '.svn', 'node_modules', 'bower_
 const MAX_BYTES = 2 * 1024 * 1024;
 
 // Every child process the scanner starts goes through here, so the gate can count them.
+// A git call never runs a program the scanned repository's own config names: /crew-map on a freshly cloned
+// third-party repo would otherwise start its `core.fsmonitor` (measured: `ls-files -co` runs it, git 2.54).
+export const GIT_SAFE = ['-c', 'core.fsmonitor=', '-c', 'core.quotePath=false'];
 export const spawned = { count: 0 };
 export function run(cmd, args, cwd) {
   spawned.count++;
+  if (cmd === 'git') args = [...GIT_SAFE, ...args];
   const r = spawnSync(cmd, args, { cwd, encoding: 'buffer', maxBuffer: 256 * 1024 * 1024, windowsHide: true,
     env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C' } });
   return { ok: r.status === 0 && !r.error, out: r.stdout ? r.stdout.toString('utf8') : '' };
@@ -26,6 +30,34 @@ export function run(cmd, args, cwd) {
 
 const skipped = (rel) => rel.split('/').some((seg) => SKIP_DIRS.has(seg));
 
+// The project's own exclusions: `.crewforth/crew-map-ignore`, one pattern a line, `#` for a comment. A pattern with
+// no `/` but a trailing one matches a name at any depth (`fixtures/`, `*.generated.ts`); one with a `/` inside is
+// anchored at the root (`docs/legacy/`, `/tools/gen.js`). `*` stays inside one segment, `**` crosses them, and a
+// trailing `/` matches the folder and everything in it. No negation: a map that leaves a file out says so in
+// `coverage.excluded`, and a rule that could bring it back is one more thing to read wrong.
+export const IGNORE_FILE = '.crewforth/crew-map-ignore';
+export function ignoreRules(text) {
+  const out = [];
+  for (const raw of String(text).split('\n')) {
+    let p = raw.replace(/\r$/, '').trim();
+    if (!p || p.startsWith('#') || p.startsWith('!')) continue;
+    const dir = p.endsWith('/'); p = p.replace(/\/+$/, '');
+    const anchored = p.startsWith('/') || p.includes('/'); p = p.replace(/^\/+/, '');
+    if (!p) continue;
+    let re = '';
+    for (let i = 0; i < p.length; i++) {
+      const c = p[i];
+      if (c === '*' && p[i + 1] === '*') { i++; if (p[i + 1] === '/') { re += '(.*/)?'; i++; } else re += '.*'; }
+      else if (c === '*') re += '[^/]*';
+      else if (c === '?') re += '[^/]';
+      else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    out.push(new RegExp(`${anchored ? '^' : '(^|/)'}${re}${dir ? '/' : '(/|$)'}`));
+  }
+  return out;
+}
+const excludedBy = (rules, rel) => rules.some((re) => re.test(rel));
+
 export function openProject(root) {
   const real = fs.realpathSync(root);
   let files = null; let commit = null;
@@ -48,10 +80,14 @@ export function openProject(root) {
     };
     walk(real, '');
   }
-  files = [...new Set(files)].sort();
+  let ignore = []; try { ignore = ignoreRules(fs.readFileSync(path.join(real, IGNORE_FILE), 'utf8')); } catch { /* none */ }
+  const listed = [...new Set(files)];
+  files = listed.filter((f) => !excludedBy(ignore, f)).sort();
+  const excluded = listed.length - files.length;
   const cache = new Map();
-  const tooBig = [];
-  // { text, lines } or null (unreadable, binary or over the size limit)
+  const tooBig = []; const unreadable = []; const binary = [];
+  // { text, lines } or null (unreadable, binary or over the size limit). Each null lands in a list, so a file the
+  // scanner asked for and could not use is reported as not measured instead of vanishing.
   const read = (rel) => {
     if (cache.has(rel)) return cache.get(rel);
     let r = null;
@@ -61,16 +97,17 @@ export function openProject(root) {
       if (st.size > MAX_BYTES) tooBig.push(rel);
       else {
         const buf = fs.readFileSync(abs);
-        if (!buf.subarray(0, 8000).includes(0)) {
+        if (buf.subarray(0, 8000).includes(0)) binary.push(rel);
+        else {
           const text = buf.toString('utf8').replace(/^/, '');
           r = { text, lines: text.split('\n').map((l) => l.replace(/\r$/, '')) };
         }
       }
-    } catch { r = null; }
+    } catch { r = null; unreadable.push(rel); }
     cache.set(rel, r);
     return r;
   };
-  return { root: real, files, commit, read, tooBig, git: git.ok };
+  return { root: real, files, commit, read, tooBig, unreadable, binary, git: git.ok, excluded, ignoreRules: ignore.length };
 }
 
 // A citation. `anchor` must be a piece of the cited line (the validator checks it, collapsing whitespace); the
@@ -112,6 +149,8 @@ export function bearsValues(rel) {
 
 // A test, a fixture or an example: its routes, URLs and environment reads describe a fake system, not this one.
 export const isTestPath = (rel) => /(^|\/)(tests?|__tests__|spec|specs|fixtures?|e2e|testdata|examples?|[\w-]*-test)(\/|$)|\.(test|spec)\.[\w]+$|(^|\/)test_[^/]*\.py$|_test\.go$|Tests?\.cs$|Tests?\.(java|kt)$/i.test(rel);
+// A module whose every source file is a test (Api.Tests, a tests package): nothing references it, by design.
+export const isTestModule = (m) => m.files.length > 0 && m.files.every((f) => isTestPath(f));
 // A host that is this machine or a name reserved for tests and documentation is not an external resource.
 export const isLocalHost = (h) => !h || /^(localhost|127\.\d+\.\d+\.\d+|0\.0\.0\.0|\[::1\]|::1)(:\d*)?$/.test(h) || /\.(invalid|example|test|localhost)(:\d*)?$/.test(h);
 

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

@@ -5,6 +5,7 @@
 //   node scan.mjs [--root DIR]            scan, verify, write DIR/.crewforth/crew-map.json, print its path
 //   node scan.mjs [--root DIR] --stdout   scan and verify; print the document, write nothing
 //   node scan.mjs [--root DIR] --check    rc 0 when the file on disk is what a scan writes now, 1 when it is not
+//   node scan.mjs [--root DIR] --contracts  rc 0 when .crewforth/contracts.md is absent or every rule and cite holds
 //       rc 1 = the scan produced a document that does not verify (nothing is written) · rc 2 = usage
 //
 // What it guarantees, each one a gate in packaging/crew-map-test:
@@ -17,19 +18,20 @@
 //   no machine    paths are relative to the project root; the findings core refuses a document that carries the
 //                 machine's own directories
 //   honest        what it cannot read goes to notMeasured with the reason, never read partly
-//   cheap         two child processes per scan (git ls-files, git rev-parse), none per file
+//   cheap         three child processes per scan (git ls-files, git rev-parse, git log), none per file
 //
 // Host-independent like the findings core: plain JSON out, Node's standard library only, no hook payload read.
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { openProject, loadSecretPatterns, makeHostFilter, sortEv, bearsValues, risky, spawned, isTestPath, ev } from './project.mjs';
+import { openProject, loadSecretPatterns, makeHostFilter, sortEv, bearsValues, risky, spawned, isTestPath, isTestModule, ev, run } from './project.mjs';
 import { scanStacks, applyTech } from './stacks.mjs';
 import { externals, configuration, codeUrls, servedCalls, endpoints, containers } from './surface.mjs';
 import { detect } from './detect.mjs';
 import { stamp, write, serialize, validate, OUT_DIR } from '../findings/findings.mjs';
-import { carry, strip, validate as validateNarrative } from './narrative.mjs';
+import { carry, steady, validate as validateNarrative } from './narrative.mjs';
+import { CONTRACTS_FILE, validate as validateContracts } from './contracts.mjs';
 
 // Languages with source the scanner has no reader for, by extension.
 const UNREAD = { swift: 'Swift', rb: 'Ruby', php: 'PHP', rs: 'Rust', scala: 'Scala', ex: 'Elixir', exs: 'Elixir',
@@ -87,6 +89,81 @@ function structure(m) {
   return { folders: shown, ...(rest ? { otherFiles: rest } : {}), testFiles: tests };
 }
 
+/**
+ * Where a module's tests are, by their names: test files among its own source (x.test.ts, test_x.py, x_test.go,
+ * XTests.cs, a tests/ folder), and the files of a test project named for it (Api.Tests, api-test, core_tests).
+ * Twelve paths at most, the count always whole, the order the same on every machine. A reader about to change the
+ * module learns which tests to run before guessing.
+ */
+const MAX_TESTS = 12;
+const TEST_NAME = /[._-]?(unit|integration|functional|e2e)?[._-]?tests?$/i;
+function testsOf(modules) {
+  const byName = new Map();
+  for (const m of modules) byName.set(`${m.stack}\u0000${m.name.toLowerCase()}`, m);
+  const linked = new Map();
+  for (const t of modules) {
+    if (!isTestModule(t) || !TEST_NAME.test(t.name)) continue;
+    const base = t.name.replace(TEST_NAME, '').toLowerCase();
+    const target = base && byName.get(`${t.stack}\u0000${base}`);
+    if (target && target !== t) (linked.get(target.id) ?? linked.set(target.id, []).get(target.id)).push(t);
+  }
+  const out = new Map();
+  for (const m of modules) {
+    const from = linked.get(m.id) ?? [];
+    const files = [...new Set([...m.files.filter((f) => isTestPath(f)), ...from.flatMap((t) => t.files)])].sort(cmp);
+    if (files.length) out.set(m.id, { files: files.slice(0, MAX_TESTS), total: files.length, ...(from.length ? { modules: from.map((t) => t.id).sort(cmp) } : {}) });
+  }
+  return out;
+}
+
+/**
+ * How often each module changed: in how many of the last WINDOW commits on HEAD a file under its folder changed
+ * (the deepest module folder that holds the file; renames followed; paths and commits limited to the scanned root
+ * when it is a folder inside a larger repository). One `git log` for the whole project, never one
+ * per module or file, and none of the repository's own programs: no fsmonitor, signature check, external diff or
+ * textconv. A count window, not a date window, so the same commit gives the same numbers on every machine. These
+ * numbers move with every commit, so --check and the rescan ledger leave them out.
+ */
+const WINDOW = 500;
+function churnOf(pj, modules) {
+  if (!pj.git || !pj.commit) return null;
+  const r = run('git', ['-c', 'log.showSignature=false', '-c', 'log.follow=false', 'log', '-M', '--name-only', '--no-ext-diff', '--no-textconv', '--no-notes',
+    '--relative', '--pretty=format:%x00', '-n', String(WINDOW), 'HEAD', '--', '.'], pj.root);
+  if (!r.ok) return null;
+  const dirs = [...new Set(modules.map((m) => m.dir))].sort((a, b) => b.length - a.length || cmp(a, b));
+  const owner = (f) => dirs.find((d) => d === '.' || f === d || f.startsWith(`${d}/`));
+  const counts = new Map();
+  const commits = r.out.split('\0').slice(1);
+  for (const c of commits) {
+    const hit = new Set();
+    for (const f of c.split('\n')) { const d = f && owner(f.replace(/\r$/, '')); if (d) hit.add(d); }
+    for (const d of hit) counts.set(d, (counts.get(d) ?? 0) + 1);
+  }
+  return { window: commits.length, of: (m) => counts.get(m.dir) ?? 0 };
+}
+
+/**
+ * What the code says about itself where it explains a choice or admits a debt: a comment whose first word is WHY,
+ * HACK or FIXME, in the module's own source (tests apart). The citation is the marker and what follows it on the
+ * line, cut at 72 characters; a line the secret net flags is cited by the marker word alone. Five lines at most, the
+ * count always whole, so /crew-map's tour can point at the reason a piece of code looks the way it does.
+ */
+const MARKER = /(?:^|[\s;])(?:\/\/+|#+|\/\*+|\*|--|<!--)\s*((?:WHY|HACK|FIXME)\b(?![\w-]).*)$/;
+function markersOf(pj, m, patterns) {
+  const out = [];
+  for (const f of m.files) {
+    if (isTestPath(f)) continue;
+    const src = pj.read(f); if (!src) continue;
+    src.lines.forEach((l, i) => {
+      const x = MARKER.exec(l); if (!x) return;
+      const word = /^\w+/.exec(x[1])[0];
+      const quote = x[1].replace(/\s*(\*\/|-->)\s*$/, '').slice(0, 72).trimEnd();
+      out.push(ev(f, i + 1, risky(quote, patterns) >= 0 ? word : quote));
+    });
+  }
+  return out;
+}
+
 // opts.hostFilter replaces the masking: ONLY the gate's must-fail twin uses it. No command-line flag reaches it.
 export function scan(root = '.', opts = {}) {
   const pj = openProject(root);
@@ -104,6 +181,8 @@ export function scan(root = '.', opts = {}) {
   const eps = endpoints(pj, st, out);
   const services = containers(pj, st, rules, hostOf, ex, cfg, out);
   const findings = detect({ st, cfg, eps, names, stdlib, notMeasured: out.notMeasured, configUrls: out.configUrls, codeHosts: out.codeHosts });
+  const tests = testsOf(st.modules);
+  const churn = churnOf(pj, st.modules);
 
   const ids = new Set([...st.modules.map((m) => m.id), ...services.map((s) => s.id), ...ex.ext.keys()]);
   for (const m of st.modules) {
@@ -144,7 +223,10 @@ export function scan(root = '.', opts = {}) {
       ...(m.entry ? { entryPoint: m.entryEv ? { evidence: [m.entryEv] } : { file: m.entryFile, evidence: [] } } : {}),
       dependencies: m.deps.length,
       structure: structure(m),
+      ...(tests.has(m.id) ? { tests: tests.get(m.id) } : {}),
+      ...(churn ? { commits: churn.of(m) } : {}),
       ...((() => { const a = aboutOf(pj, m); return a ? { about: a } : {}; })()),
+      ...((() => { const k = markersOf(pj, m, patterns); return k.length ? { markers: capped(k) } : {}; })()),
       ...capped(m.evidence), narrative: null })),
     ...services.map((s) => ({ id: s.id, kind: 'service', name: s.name, ...(s.image ? { image: s.image } : {}), ...capped(s.evidence), narrative: null })),
     ...[...ex.ext.values()].map((n) => ({ id: n.id, kind: 'external', resource: n.resource, label: n.label, hosts: [...n.hosts].sort(), ...capped(n.evidence), narrative: null })),
@@ -157,15 +239,18 @@ export function scan(root = '.', opts = {}) {
       [b.module, b.path, b.method, b.evidence[0].file, String(b.evidence[0].line).padStart(9, '0')].join('\u0000')));
   };
   const nm = new Map();
+  // After every read (the nodes' README included), so a file that failed late is still said.
+  for (const f of pj.unreadable) out.notMeasured.push({ what: f, reason: 'could not be read' });
+  for (const f of pj.binary) out.notMeasured.push({ what: f, reason: 'binary, not read' });
   for (const x of out.notMeasured) nm.set(`${x.what}\u0000${x.reason}`, x);
 
   const stacks = [...new Set([...st.modules.map((m) => m.stack), ...(services.length ? ['container'] : [])])].sort();
   const doc = {
     schema: SCHEMA,
     producer: { name: NAME, version: '1' },
-    ...(pj.commit ? { source: { commit: pj.commit } } : {}),
+    ...(pj.commit ? { source: { commit: pj.commit, ...(churn ? { commitsRead: churn.window } : {}) } } : {}),
     stacks,
-    coverage: { files: pj.files.length, modules: st.modules.length, listing: pj.git ? 'git' : 'walk' },
+    coverage: { files: pj.files.length, modules: st.modules.length, listing: pj.git ? 'git' : 'walk', ...(pj.ignoreRules ? { excluded: pj.excluded } : {}) },
     nodes,
     edges,
     provides: { endpoints: epSort(eps.provides) },
@@ -193,12 +278,12 @@ export function scan(root = '.', opts = {}) {
   }
   const report = stamp(doc, pj.root);
   for (const c of cites) if (c.sha256 && (bearsValues(c.file) || risky(lineAt(c), patterns) >= 0)) delete c.sha256;
-  return { doc, report, spawned: spawned.count };
+  return { doc, report, spawned: spawned.count, files: new Set(pj.files), read: pj.read };
 }
 
 function usage(msg) {
   if (msg) console.error(`crew-map: ${msg}`);
-  console.error('usage: scan.mjs [--root DIR] [--stdout | --check | --validate]');
+  console.error('usage: scan.mjs [--root DIR] [--stdout | --check | --validate | --contracts | --force]');
   return 2;
 }
 
@@ -211,17 +296,51 @@ function summary(doc) {
     + `${doc.findings.length} finding(s) (${hidden} hidden by default) · ${doc.notMeasured.length} not measured`;
 }
 
+// What a rescan changed, by stable id, so the reader sees which modules came, went or moved and not only a byte
+// count: nodes added, removed and changed (any scanner field but the commit count; descriptions are not the scan's), edges added and
+// removed by from → to and kind. At most eight ids are named per list; the count is always whole.
+export function ledger(was, doc) {
+  const bare = (n) => { const { narrative, commits, ...rest } = n; return JSON.stringify(rest); };
+  const before = new Map((was.nodes ?? []).map((n) => [n.id, bare(n)]));
+  const after = new Map(doc.nodes.map((n) => [n.id, bare(n)]));
+  const added = [...after.keys()].filter((k) => !before.has(k));
+  const removed = [...before.keys()].filter((k) => !after.has(k));
+  const changed = [...after.keys()].filter((k) => before.has(k) && before.get(k) !== after.get(k));
+  const ek = (e) => `${e.from} → ${e.to} (${e.kind})`;
+  const eb = new Set((was.edges ?? []).map(ek)); const ea = new Set(doc.edges.map(ek));
+  const eAdded = [...ea].filter((k) => !eb.has(k)); const eRemoved = [...eb].filter((k) => !ea.has(k));
+  if (!added.length && !removed.length && !changed.length && !eAdded.length && !eRemoved.length) return 'crew-map: since the last scan: no node or edge changed';
+  const list = (xs) => (xs.length ? ` ${xs.length}: ${xs.slice(0, 8).join(', ')}${xs.length > 8 ? `, … ${xs.length - 8} more` : ''}` : ' 0');
+  return ['crew-map: since the last scan:', `  nodes added${list(added)}`, `  nodes removed${list(removed)}`, `  nodes changed${list(changed)}`,
+    `  edges added${list(eAdded)}`, `  edges removed${list(eRemoved)}`].join('\n');
+}
+
 export function main(argv) {
-  let root = '.'; let mode = 'write';
+  let root = '.'; let mode = 'write'; let force = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--root') { root = argv[++i]; if (root === undefined) return usage('--root needs a directory'); }
-    else if (a === '--stdout' || a === '--check' || a === '--validate') { if (mode !== 'write') return usage('--stdout, --check and --validate do not go together'); mode = a.slice(2); }
+    else if (a === '--force') force = true;
+    else if (a === '--stdout' || a === '--check' || a === '--validate' || a === '--contracts') { if (mode !== 'write') return usage('--stdout, --check, --validate and --contracts do not go together'); mode = a.slice(2); }
     else return usage(`no such option: ${a}`);
   }
   try { if (!fs.statSync(root).isDirectory()) throw new Error('not a directory'); }
   catch (e) { console.error(`crew-map: --root ${root}: ${e.message}`); return 2; }
-  const { doc, report } = scan(root);
+  const { doc, report, files, read } = scan(root);
+  // The project's own rules (contracts.mjs): every cite must land on a name in a file of this tree.
+  const contracts = () => {
+    let text = null; try { text = fs.readFileSync(path.join(root, CONTRACTS_FILE), 'utf8'); } catch { /* none */ }
+    if (text === null) return { n: 0, problems: [], absent: true };
+    const r = validateContracts(text, files, read);
+    return { n: r.contracts.length, problems: r.problems.map((p) => ({ at: `contracts ${p.at}`, message: p.message })) };
+  };
+  if (mode === 'contracts') {
+    const c = contracts();
+    if (c.absent) { console.log(`crew-map: ${CONTRACTS_FILE} does not exist, so there is nothing to hold`); return 0; }
+    for (const p of c.problems) console.log(`  FAIL ${p.at}: ${p.message}`);
+    console.log(c.problems.length ? `crew-map: ${c.problems.length} problem(s) in ${CONTRACTS_FILE}` : `crew-map: ${CONTRACTS_FILE} holds: ${c.n} contract(s), every cite names a symbol in a file of this tree`);
+    return c.problems.length ? 1 : 0;
+  }
   if (!report.ok) {
     for (const p of report.problems) console.error(`  FAIL ${p.at}: ${p.code} — ${p.message}`);
     console.error('crew-map: the scan produced citations that do not verify, so nothing was written (a scanner defect)');
@@ -233,11 +352,12 @@ export function main(argv) {
   let was = null; try { was = old === null ? null : JSON.parse(old); } catch { /* unreadable: different */ }
   if (mode === 'validate') {
     if (!was) { console.log(`crew-map: ${OUT_DIR}/${NAME}.json ${old === null ? 'does not exist' : 'is not JSON'}`); return 1; }
-    const problems = validateNarrative(was, doc, serialize);
+    const c = contracts();
+    const problems = [...validateNarrative(was, doc, serialize), ...c.problems];
     const written = (was.nodes ?? []).filter((n) => n.narrative != null).length + (was.overview != null ? 1 : 0);
-    if (!problems.length) { console.log(`crew-map: ${OUT_DIR}/${NAME}.json holds: ${written} description(s), each citing lines the scan read; the scanner's fields untouched`); return 0; }
+    if (!problems.length) { console.log(`crew-map: ${OUT_DIR}/${NAME}.json holds: ${written} description(s), each citing lines the scan read; the scanner's fields untouched${c.absent ? '' : `; ${c.n} contract(s) in ${CONTRACTS_FILE}, every cite landing`}`); return 0; }
     for (const p of problems) console.log(`  FAIL ${p.at}: ${p.message}`);
-    console.log(`crew-map: ${problems.length} problem(s); fix the descriptions, never the scanner's fields`);
+    console.log(`crew-map: ${problems.length} problem(s); fix the descriptions or contracts.md, never the scanner's fields`);
     return 1;
   }
   if (mode === 'check') {
@@ -245,7 +365,8 @@ export function main(argv) {
     // The content is compared, not the commit it was written at: a map committed to the repository is always
     // one commit behind the commit that carries it, and that alone does not make it stale. What the model wrote
     // (narrative, overview) is not the scan's, so it is left out of the comparison.
-    const bare = (d) => { const { source, ...rest } = strip(d); return serialize(rest); };
+    // How often each module changed moves with every commit too, so it is left out the same way.
+    const bare = (d) => serialize(steady(d));
     const then = was && was.source && was.source.commit; const now = doc.source && doc.source.commit;
     const at = then && now && then !== now ? ` (written at ${then.slice(0, 12)}, HEAD is ${now.slice(0, 12)})` : '';
     if (was && bare(was) === bare(doc)) { console.log(`crew-map: ${OUT_DIR}/${NAME}.json is up to date${at}`); return 0; }
@@ -254,8 +375,26 @@ export function main(argv) {
   }
   // The descriptions /crew-map wrote are kept where they still cite only lines this scan cites; the rest are dropped.
   const carried = was ? carry(was, doc) : { doc, kept: 0, dropped: 0 };
+  // A rescan that would lose most of what the map held is far more often a wrong --root or a damaged checkout than a
+  // project that halved: /crew-map never commits, so the descriptions it drops exist nowhere else. Write nothing and
+  // say both counts; --force writes it anyway. Only descriptions whose NODE is gone count here: one whose cited line
+  // moved is dropped by design on an ordinary edit, and that rescan must still write.
+  const modsOf = (d) => (d?.nodes ?? []).filter((n) => n.kind === 'module').length;
+  const shrank = [];
+  if (was) {
+    const ids = new Set(doc.nodes.map((n) => n.id));
+    const described = (was.nodes ?? []).filter((n) => n.narrative != null);
+    const orphaned = described.filter((n) => !ids.has(n.id)).length;
+    if (orphaned * 2 > described.length) shrank.push(`${orphaned} of ${described.length} described node(s) would be gone, with their descriptions`);
+    if (modsOf(doc) * 2 < modsOf(was)) shrank.push(`modules would fall from ${modsOf(was)} to ${modsOf(doc)}`);
+  }
+  if (shrank.length && !force) {
+    console.error(`crew-map: nothing written — ${shrank.join('; ')}. A wrong --root or a damaged checkout does this; if the project really changed, run again with --force`);
+    return 1;
+  }
   const r = write(carried.doc, root, NAME);
   if (!r.ok) { for (const p of r.problems) console.error(`  FAIL ${p.at}: ${p.code} — ${p.message}`); return 1; }
+  if (was) console.error(ledger(was, doc));
   console.error(summary(doc) + (carried.kept || carried.dropped ? ` · ${carried.kept} description(s) kept, ${carried.dropped} dropped (they cited lines this scan no longer reads)` : ''));
   console.log(r.file);
   return 0;

package/kit/eval/lib/findings/findings.schema.json

@@ -56,7 +56,17 @@
           "description": "The producer's own fields. Not interpreted here.",
           "type": "object"
         },
-        "verification": { "$ref": "#/$defs/verification" }
+        "verification": { "$ref": "#/$defs/verification" },
+        "disposition": {
+          "description": "What became of the finding: fixed now, tracked elsewhere, accepted by the user, or dropped as disproved. A later review carries a tracked, accepted or dropped finding with the same id over instead of raising it again, unless the diff changes the lines it cites; a critical or high one is judged again every time.",
+          "type": "object",
+          "required": ["state"],
+          "additionalProperties": false,
+          "properties": {
+            "state": { "enum": ["fixed", "tracked", "accepted", "dropped"] },
+            "reason": { "type": "string", "maxLength": 500 }
+          }
+        }
       }
     },
     "verification": {

package/kit/eval/lib/findings/findings.sh

@@ -26,4 +26,27 @@ if [ -z "$NODE" ]; then
   echo "findings: no Node $FLOOR+ that runs was found, so nothing was checked (this is not a pass)" >&2
   exit 3
 fi
-exec "$NODE" "$d/findings.mjs" "$@"
+[ "${1:-}" = write ] || exec "$NODE" "$d/findings.mjs" "$@"
+
+# A write is also one REVIEW ROUND, and the round is logged here, not in findings.mjs (which reads no repository on
+# purpose): one line per written document in the git directory, so it is never committed —
+#   <time> <branch> <name> <round> <critical> <high> <medium> <low> <info>
+# The round is 1 + the lines already there for the same branch and name. It is what tells whether the late rounds of
+# a review still find anything above low (/crew-review § Rounds). Outside a repository nothing is logged; a --root
+# inside one logs there. Two writes at the same moment may share a round number: a log, not a lock.
+"$NODE" "$d/findings.mjs" "$@"; rc=$?
+[ "$rc" = 0 ] || exit "$rc"
+root=.; name=""; shift
+while [ $# -gt 0 ]; do case "$1" in --root) root="${2:-.}"; shift ;; --verified) ;; *) [ -z "$name" ] && name="$1" ;; esac; shift; done
+log="$(git -C "$root" rev-parse --path-format=absolute --git-path crewforth-review-rounds.tsv 2>/dev/null)" || exit 0
+# A git before 2.31 echoes the unknown --path-format back on a line of its own: that is no path to write to.
+case "$log" in *$'\n'*|-*|'') exit 0 ;; esac
+# symbolic-ref, not rev-parse: it names a branch with no commit yet too. Never empty: an empty tab-separated field
+# collapses when the line is read back, and every round then counted as the first (found by the self-check).
+br="$(git -C "$root" symbolic-ref --short -q HEAD 2>/dev/null)" || br=""; [ -n "$br" ] || br=-
+# Any branch name git allows is logged; only a tab or a newline, which would split the line, is not.
+case "$br" in *$'\t'*|*$'\n'*) exit 0 ;; esac
+n=1; [ -f "$log" ] && while IFS=$'\t' read -r _ b nm _; do [ "$b" = "$br" ] && [ "$nm" = "$name" ] && n=$((n+1)); done < "$log"
+sev="$("$NODE" -e 'const f=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).findings||[];const c={critical:0,high:0,medium:0,low:0,info:0};for(const x of f)if(x.severity in c)c[x.severity]++;process.stdout.write([c.critical,c.high,c.medium,c.low,c.info].join("\t"))' "$root/.crewforth/$name.json" 2>/dev/null)" || exit 0
+printf '%s\t%s\t%s\t%s\t%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$br" "$name" "$n" "$sev" >> "$log" 2>/dev/null
+exit 0

package/kit/eval/lib/hook-inject.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# What the hooks wired on UserPromptSubmit and SessionStart put into the model's context, in bytes. One definition:
+# doctor prints it (4c), smoke-test.sh pins a budget on it. Run from anywhere:
+#
+#   bash .claude/eval/lib/hook-inject.sh [PROJECT_ROOT]
+#
+# Prints tab-separated lines, nothing else on stdout:
+#   run    <event> <hook> <bytes> <rc>      a hook that was run; bytes = what Claude Code would inject (0 when rc != 0)
+#   skip   <event> <hook> <reason-key>      a hook that was NOT run, and why (keys: see the table below)
+#   total  <event> <bytes> <hooks run>
+#   prompt <the fixture prompt>
+#
+# WHY IT IS RUN AND NOT READ. A hook's injection depends on the project (route-hint matches the prompt against the
+# installed agents, board-sync prints the cached board, context-usage the fill), so reading the scripts cannot give a
+# number; running them on a fixture payload can. The number is therefore A FLOOR FOR THIS FIXTURE, not a maximum: a
+# hook that speaks only for some prompts or states (an approval, an update, a compaction) prints nothing here.
+#
+# WHAT "INJECT" MEANS. For both events Claude Code adds a hook's stdout to the context on exit 0, or, when stdout is a
+# JSON object, its hookSpecificOutput.additionalContext (a systemMessage goes to the user, not the model). That is
+# what is counted: the decoded bytes of additionalContext, or the plain stdout. NOT counted (not measured here): the
+# framing Claude Code puts around each injection.
+#
+# NO LASTING SIDE EFFECT. Every hook runs with a throwaway HOME, TMPDIR, XDG_CACHE_HOME and CLAUDE_CONFIG_DIR, a
+# fixture transcript, and a session id no real session has (real ones are UUIDs). What each Crewforth hook writes was
+# read from its source (grep for `> "`, `mkdir`, `.claude/state`) and each is placed in one of three rows:
+#   read-only for these payloads ............ run against the project (route-hint, session-rehydrate, skill-trust,
+#     turn-check: the fixture declares no fast check, so it writes no snapshot;
+#     branch-fresh with CREW_BRANCH_FRESH_FETCH=off: no fetch; its merge-tree check leaves only unreachable objects)
+#   writes only under TMPDIR ................ run against the project, TMPDIR thrown away (context-usage)
+#   board-sync: its detached half fetches over the network when the cache is stale; CREW_BOARD_MAX_AGE[_NOBOARD]
+#     set beyond any age keeps it on the cached read, which writes nothing
+#   prompt-approval: EVERY user message empties a recorded approval in the worktree's git directory and the
+#     question's state in .claude/state, so it runs with the project dir and cwd on a scratch folder outside any
+#     repository. For a prompt that is not an approval it prints nothing wherever it runs (read from its source).
+#   writes into the project, cannot be redirected -> not run, said so:
+#     agent-outcome (SessionStart rewrites .claude/state/crew-critical-paths.auto),
+#     session-update-check (writes .claude/.state/update-asked, which silences the real question for a day, and
+#     starts a network refresh)
+# A hook not in this table (the project's own, or a Crewforth hook added later) is not run: nothing has checked
+# what it writes. smoke-test.sh fails when a hook Crewforth wires on these events is missing from the table.
+#
+# Process cost: two awk per hook and a handful for the wiring, never one per line (Git Bash: 20-130 ms a process).
+set -uo pipefail
+export LC_ALL=C   # bytes, not characters: length() in awk and the shell both count bytes under C
+
+_hi_d="${BASH_SOURCE[0]//\\//}"; _hi_d="${_hi_d%/*}"; [ "$_hi_d" = "${BASH_SOURCE[0]//\\//}" ] && _hi_d=.
+_hi_d="$(cd "$_hi_d" 2>/dev/null && pwd)" || _hi_d=.   # absolute: the script cd's into ROOT below
+SJ="$_hi_d/settings-json.awk"
+ROOT="${1:-.}"
+cd "$ROOT" 2>/dev/null || { echo "hook-inject: cannot enter '$ROOT'" >&2; exit 2; }
+S=.claude/settings.json
+[ -f "$SJ" ] || { echo "hook-inject: Crewforth's JSON reader is missing ($SJ)" >&2; exit 2; }
+[ -f "$S" ] || { echo "hook-inject: no $S" >&2; exit 2; }
+awk -v op=validate -f "$SJ" "$S" 2>/dev/null || { echo "hook-inject: $S is not valid JSON" >&2; exit 2; }
+
+PROMPT="write unit tests for the payment service"
+SID="crew-inject-probe-$$-${RANDOM:-0}"
+GCG="${GIT_CONFIG_GLOBAL:-${HOME:-}/.gitconfig}"
+
+# CREW_INJECT_SCRATCH: a folder to use and KEEP (smoke reads it back to prove the redirection happened). Otherwise a
+# fresh one, removed on exit.
+if [ -n "${CREW_INJECT_SCRATCH:-}" ]; then T="$CREW_INJECT_SCRATCH"; mkdir -p "$T" || exit 2
+else T="$(mktemp -d 2>/dev/null)" || { echo "hook-inject: no scratch folder" >&2; exit 2; }; trap 'rm -rf "$T"' EXIT; fi
+mkdir -p "$T/home/.claude" "$T/tmp" "$T/cache" "$T/proj" || exit 2
+
+# A JSON string body for a path: backslash and quote escaped (a Windows path or an odd folder name).
+_js(){ local s="${1//\\/\\\\}"; _JSV="${s//\"/\\\"}"; }
+_js "$PWD"; PJ="$_JSV"; _js "$T/proj"; SCJ="$_JSV"; _js "$T/transcript.jsonl"; TJ="$_JSV"
+
+# The fixture transcript: one assistant turn with usage, the record context-usage reads (2% of a 1M window).
+printf '%s\n' '{"type":"assistant","message":{"role":"assistant","model":"claude-fixture","usage":{"input_tokens":100,"cache_read_input_tokens":20000,"cache_creation_input_tokens":0,"output_tokens":10}}}' > "$T/transcript.jsonl"
+printf '{"session_id":"%s","transcript_path":"%s","cwd":"%s","permission_mode":"default","hook_event_name":"UserPromptSubmit","prompt":"%s"}\n' "$SID" "$TJ" "$PJ" "$PROMPT" > "$T/ups.json"
+printf '{"session_id":"%s","transcript_path":"%s","cwd":"%s","permission_mode":"default","hook_event_name":"UserPromptSubmit","prompt":"%s"}\n' "$SID" "$TJ" "$SCJ" "$PROMPT" > "$T/ups-scratch.json"
+printf '{"session_id":"%s","transcript_path":"%s","cwd":"%s","hook_event_name":"SessionStart","source":"startup"}\n' "$SID" "$TJ" "$PJ" > "$T/ss.json"
+
+# prompt-approval's scratch folder must not sit inside a repository: its record lives in the enclosing git directory.
+SCRATCH_OK=1; git -C "$T/proj" rev-parse --git-dir >/dev/null 2>&1 && SCRATCH_OK=0
+
+# The decoded byte length of a JSON string token (quotes included in the input), or of plain text. One awk per hook.
+#   \\ and the one-letter escapes are one byte; \uXXXX is the UTF-8 length of that code point (a surrogate half 2,
+#   so a pair is 4). In C locale length() counts bytes, so raw UTF-8 in the string is counted as it will be sent.
+DEC='
+function hx(h,  i, v) { v = 0; h = tolower(h); for (i = 1; i <= 4; i++) v = v * 16 + index("0123456789abcdef", substr(h, i, 1)) - 1; return v }
+{ buf = buf (NR > 1 ? "\n" : "") $0 }
+END {
+  if (mode == "plain") { print length(buf) + (NR > 0 ? 1 : 0); exit }
+  s = buf; sub(/^[[:space:]]*"/, "", s); sub(/"[[:space:]]*$/, "", s)
+  gsub(/\\\\/, "B", s)
+  while (match(s, /\\u[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]/)) {
+    v = hx(substr(s, RSTART + 2, 4)); k = (v < 128 ? 1 : (v < 2048 ? 2 : ((v >= 55296 && v <= 57343) ? 2 : 3)))
+    r = substr("UUU", 1, k); s = substr(s, 1, RSTART - 1) r substr(s, RSTART + 6)
+  }
+  gsub(/\\./, "E", s)
+  print length(s)
+}'
+
+measure(){  # $1 = event, $2 = hook file name -> one run/skip line; adds to TOT_* and RUN_*
+  local ev="$1" h="$2" pl proj="$PWD" rc n ac
+  case "$ev" in UserPromptSubmit) pl="$T/ups.json" ;; *) pl="$T/ss.json" ;; esac
+  case "$h" in
+    context-usage.sh|route-hint.sh|session-rehydrate.sh|skill-trust.sh|board-sync.sh|turn-check.sh|branch-fresh.sh) ;;
+    prompt-approval.sh)
+      [ "$SCRATCH_OK" = 1 ] || { printf 'skip\t%s\t%s\t%s\n' "$ev" "$h" scratch-in-repo; return 0; }
+      proj="$T/proj"; pl="$T/ups-scratch.json" ;;
+    agent-outcome.sh)        printf 'skip\t%s\t%s\t%s\n' "$ev" "$h" writes-state; return 0 ;;
+    session-update-check.sh) printf 'skip\t%s\t%s\t%s\n' "$ev" "$h" writes-update; return 0 ;;
+    *)                       printf 'skip\t%s\t%s\t%s\n' "$ev" "$h" unchecked; return 0 ;;
+  esac
+  [ -f ".claude/hooks/$h" ] || { printf 'skip\t%s\t%s\t%s\n' "$ev" "$h" missing; return 0; }
+  # Launched the way settings.json launches it (`bash .claude/hooks/<name>` from the project root): context-usage
+  # compares its own $0 with that spelling and warns about stale wiring when they differ. git keeps reading the
+  # user's own global config (GIT_CONFIG_GLOBAL, git 2.32+): session-rehydrate's answer depends on core.hooksPath.
+  GIT_CONFIG_GLOBAL="$GCG" HOME="$T/home" TMPDIR="$T/tmp" XDG_CACHE_HOME="$T/cache" CLAUDE_CONFIG_DIR="$T/home/.claude" \
+  CLAUDE_PROJECT_DIR="$proj" CLAUDE_PLUGIN_ROOT="" CREW_BOARD_MAX_AGE=999999999999 CREW_BOARD_MAX_AGE_NOBOARD=999999999999 CREW_BRANCH_FRESH_FETCH=off \
+    bash ".claude/hooks/$h" < "$pl" > "$T/out" 2>/dev/null
+  rc=$?
+  n=0
+  if [ "$rc" = 0 ] && [ -s "$T/out" ]; then
+    awk -v op=get -v path=hookSpecificOutput.additionalContext -f "$SJ" "$T/out" > "$T/ac" 2>/dev/null
+    case $? in
+      0)  n="$(awk -v mode=json "$DEC" "$T/ac")" ;;
+      10) n="$(awk -v mode=plain "$DEC" "$T/out")" ;;   # not a JSON object: Claude Code injects the text as it is
+      *)  n=0 ;;                                         # a JSON object with no additionalContext: nothing reaches the model
+    esac
+  fi
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  printf 'run\t%s\t%s\t%s\t%s\n' "$ev" "$h" "$n" "$rc"
+  case "$ev" in UserPromptSubmit) TOT_U=$((TOT_U + n)); RUN_U=$((RUN_U + 1)) ;; *) TOT_S=$((TOT_S + n)); RUN_S=$((RUN_S + 1)) ;; esac
+}
+
+TOT_U=0; RUN_U=0; TOT_S=0; RUN_S=0
+printf 'prompt\t%s\n' "$PROMPT"
+for ev in UserPromptSubmit SessionStart; do
+  ne="$(awk -v op=len -v path="hooks.$ev" -f "$SJ" "$S" 2>/dev/null)"; case "$ne" in ''|*[!0-9]*) ne=0 ;; esac
+  i=0
+  while [ "$i" -lt "$ne" ]; do
+    nh="$(awk -v op=len -v path="hooks.$ev.$i.hooks" -f "$SJ" "$S" 2>/dev/null)"; case "$nh" in ''|*[!0-9]*) nh=0 ;; esac
+    j=0
+    while [ "$j" -lt "$nh" ]; do
+      c="$(awk -v op=get -v path="hooks.$ev.$i.hooks.$j.command" -f "$SJ" "$S" 2>/dev/null)" || c=""
+      r="${c#*bash .claude/hooks/}"
+      if [ "$r" != "$c" ]; then
+        r="${r%\"}"
+        case "$r" in *.sh) case "$r" in *[!A-Za-z0-9._-]*) r="" ;; esac ;; *) r="" ;; esac
+      else r=""; fi
+      if [ -n "$r" ]; then measure "$ev" "$r"
+      else
+        # Not one of Crewforth's: named by its last word only (no path, no argument is printed).
+        f="${c%\"}"; f="${f//\\//}"; f="${f##*[ /]}"; f="${f//[!A-Za-z0-9._-]/}"
+        printf 'skip\t%s\t%s\t%s\n' "$ev" "${f:-hook}" unchecked
+      fi
+      j=$((j + 1))
+    done
+    i=$((i + 1))
+  done
+done
+printf 'total\tUserPromptSubmit\t%s\t%s\n' "$TOT_U" "$RUN_U"
+printf 'total\tSessionStart\t%s\t%s\n' "$TOT_S" "$RUN_S"
+exit 0