@optitransfer/proofline 0.0.0-stage → 0.2.0-next.1

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@optitransfer/proofline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0-next.1",
+  "description": "Independent V&V for coding agents. The agent says done; Proofline re-runs every check against a contract, rejects claims the evidence does not support, and gates the push.",
+  "keywords": [
+    "ai-agents",
+    "llm",
+    "mcp",
+    "mcp-server",
+    "agentic-ai",
+    "claude-code",
+    "verification",
+    "validation",
+    "testing",
+    "test-automation",
+    "quality-gate",
+    "ci-cd",
+    "devops",
+    "code-review",
+    "git-hooks",
+    "audit",
+    "attestation",
+    "developer-tools",
+    "nodejs",
+    "cli"
+  ],
+  "homepage": "https://github.com/mgillr/proofline",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mgillr/proofline.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mgillr/proofline/issues"
+  },
+  "author": "mgillr",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "bin": { "proofline": "bin/proofline.mjs" },
+  "engines": { "node": ">=22" },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "PATENTS-NONASSERT.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "demo": "node examples/demo/demo.mjs",
+    "self-gate": "node bin/proofline.mjs gate PL-SELF --skip-pushed",
+    "mcp": "node bin/proofline.mjs mcp"
+  },
+  "devDependencies": {
+    "hivevault": "0.3.3"
+  }
+}

package/src/cache.mjs

@@ -0,0 +1,81 @@
+// Result cache: a PASS of an expensive check (command, metric) on a clean tree runs once per HEAD and is reused.
+// Opt-in per contract (defaults.reuse_results). The PASS is recorded in the evidence log; the cache file points at
+// that entry, and a result is reused only from an entry that is still in an intact chain with the same hash.
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, sha256, canon, readJson } from './util.mjs';
+import { record, readLog, verifyChain } from './evidence.mjs';
+
+/** The only verifiers whose PASS is reused. The others are cheap, or depend on the base. */
+export const REUSABLE = ['command', 'metric'];
+export const DEFAULT_MAX_AGE_H = 24;
+export const cacheDir = (root) => path.join(root, '.proofline', 'cache');
+const cacheFile = (root, key) => path.join(cacheDir(root), `${key}.json`);
+
+/** A contract's reuse settings: on only when defaults.reuse_results is true. */
+export function settings(c) {
+  const d = c.defaults || {};
+  const age = d.reuse_max_age_h;
+  return { on: d.reuse_results === true, maxAgeH: typeof age === 'number' && age > 0 ? age : DEFAULT_MAX_AGE_H, maxLoad: typeof d.max_load_per_cpu === 'number' ? d.max_load_per_cpu : undefined };
+}
+
+/** The env vars a check names: `$VAR` and `${VAR}` in its command, `{VAR}` in a metric's output_file. */
+export function namedEnv(v) {
+  const names = new Set();
+  for (const m of String(v.cmd ?? '').matchAll(/\$\{?([A-Za-z_]\w*)/g)) names.add(m[1]);
+  for (const m of String(v.output_file ?? '').matchAll(/\{(\w+)\}/g)) names.add(m[1]);
+  return [...names].sort();
+}
+
+/**
+ * The cache key of a criterion's verifier, or null when its result is neither reused nor stored: not a reusable
+ * verifier, no HEAD, or a tree that differs from HEAD outside .proofline/ (an uncommitted edit never reuses a result).
+ * The key holds the verifier (canonical JSON), HEAD, process.version and the values of the env vars the check names;
+ * for a metric also its baseline and the regression tolerance, which decide its verdict.
+ */
+export function keyFor(root, v, { baseline, tolerancePct } = {}) {
+  if (!REUSABLE.includes(v.type)) return null;
+  const head = git(['rev-parse', '--verify', '--quiet', 'HEAD'], root);
+  if (!head.ok || !head.out) return null;
+  // --untracked-files=normal: an untracked file counts even where status.showUntrackedFiles=no hides it.
+  const st = git(['status', '--porcelain', '--untracked-files=normal'], root);
+  if (!st.ok || st.out.split('\n').some((l) => l && !l.includes('.proofline/'))) return null;
+  const env = Object.fromEntries(namedEnv(v).map((n) => [n, v.env?.[n] ?? process.env[n] ?? null]));
+  const k = { verifier: v, head: head.out, node: process.version, env };
+  if (v.type === 'metric') Object.assign(k, { baseline: baseline?.[v.name || v.key] ?? null, tolerance_pct: tolerancePct ?? 20 });
+  return { key: sha256(canon(k)), head: head.out };
+}
+
+/**
+ * The evidence entry of a PASS that may be reused for `key`, or null (then the check runs). The cache file must name
+ * an entry that is in an intact chain with the hash it stored, records a PASS for this key, is no older than
+ * maxAgeH hours, and, for a metric, ran at a load per CPU within maxLoad when that is set.
+ */
+export function lookup(root, key, { maxAgeH = DEFAULT_MAX_AGE_H, maxLoad, now = Date.now() } = {}) {
+  const c = readJson(cacheFile(root, key));
+  if (!c || c.key !== key || c.status !== 'pass' || !Number.isInteger(c.entry)) return null;
+  let e;
+  try { if (!verifyChain(root).ok) return null; e = readLog(root)[c.entry]; } catch { return null; }
+  if (!e || e.hash !== c.entry_hash || e.type !== 'result' || e.data?.key !== key || e.data.status !== 'pass') return null;
+  const age = now - Date.parse(e.ts);
+  if (!(age >= 0 && age <= maxAgeH * 3600e3)) return null;
+  if (e.data.type === 'metric' && typeof maxLoad === 'number' && !(e.data.evidence?.machine?.load_per_cpu <= maxLoad)) return null;
+  return e;
+}
+
+/** Record a fresh PASS in the evidence log and point the cache file for its key at that entry. Returns the entry. */
+export function store(root, { key, head }, task, a, r) {
+  const data = { task, criterion: a.id, type: a.verifier.type, key, head, status: r.status, detail: r.detail, evidence: r.evidence };
+  const e = record(root, 'result', data);
+  const f = cacheFile(root, key), tmp = `${f}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(tmp, JSON.stringify({ ...data, ts: e.ts, entry: e.seq, entry_hash: e.hash }, null, 2) + '\n');
+  fs.renameSync(tmp, f);
+  return e;
+}
+
+/** A criterion's result taken from the evidence entry that recorded its PASS. */
+export function reusedResult(e) {
+  const from = `reused from ${e.ts} (evidence entry ${e.seq})`;
+  return { status: 'pass', detail: `${from}: ${e.data.detail}`, evidence: { ...e.data.evidence, reused_from: { ts: e.ts, entry: e.seq, hash: e.hash, head: e.data.head } }, reused: { ts: e.ts, entry: e.seq } };
+}

package/src/checks.mjs

@@ -0,0 +1,276 @@
+// Deterministic verifiers. Each returns { status: pass|fail|flaky|error|blocked, detail, evidence }.
+// "error" means the check could not be run (missing tool/file/base) and leads to BLOCKED, never PASS.
+// "blocked" means it must not be run now (a metric on a busy machine) and also leads to BLOCKED.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { run, git, tail, pick, lastJson, matchAny, onRemote } from './util.mjs';
+
+/** The machine a metric runs on: 1-minute load average and CPU count. verifyTask takes a replacement as `machine`. */
+export const readMachine = () => ({ load1: os.loadavg()[0], cpus: os.cpus().length });
+
+/** `node --version` as the bench command would resolve it (same cwd and env), or null. */
+function nodeVersion(root, env) {
+  const r = run('node --version', { cwd: root, timeoutS: 30, env });
+  return r.exit === 0 ? r.stdout.trim() : null;
+}
+
+export const TEST_FILE_RE = /(^|\/)(test|tests|__tests__)\/|\.(test|spec)\.[mc]?[jt]sx?$/;
+const sub = (s, vars) => s.replace(/\{(\w+)\}/g, (m, k) => (vars[k] ?? m));
+
+export function resolveBase(root, ref) {
+  const r = git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], root);
+  return r.ok ? r.out : null;
+}
+
+/** Changed files between base and the working tree (tracked + untracked). */
+export function changedFiles(root, base) {
+  const out = new Map();
+  const d = git(['diff', '--name-status', '-M', base, '--'], root);
+  for (const l of d.out.split('\n').filter(Boolean)) {
+    const [st, a, b] = l.split('\t');
+    out.set(b || a, st[0]);
+  }
+  for (const f of git(['ls-files', '--others', '--exclude-standard'], root).out.split('\n').filter(Boolean)) out.set(f, 'A');
+  for (const f of [...out.keys()]) if (f.startsWith('.proofline/')) out.delete(f);
+  return out;
+}
+
+/** Parse a unified diff (-U0) into per-file hunks of added/removed lines. */
+export function diffHunks(root, base) {
+  const d = git(['diff', '-U0', base, '--'], root).out;
+  const files = [];
+  let cur = null, hunk = null;
+  for (const l of d.split('\n')) {
+    if (l.startsWith('diff --git')) { cur = { file: l.split(' b/').pop(), hunks: [] }; files.push(cur); continue; }
+    if (!cur) continue;
+    if (l.startsWith('+++') || l.startsWith('---')) continue;
+    if (l.startsWith('@@')) { hunk = { add: [], del: [] }; cur.hunks.push(hunk); continue; }
+    if (!hunk) continue;
+    if (l[0] === '+') hunk.add.push(l.slice(1)); else if (l[0] === '-') hunk.del.push(l.slice(1));
+  }
+  // untracked files count as fully added
+  for (const f of git(['ls-files', '--others', '--exclude-standard'], root).out.split('\n').filter(Boolean)) {
+    if (f.startsWith('.proofline/')) continue;
+    let txt = ''; try { txt = fs.readFileSync(path.join(root, f), 'utf8'); } catch {}
+    files.push({ file: f, hunks: [{ add: txt.split('\n'), del: [] }] });
+  }
+  return files;
+}
+
+function runCounted(cmd, root, v, ctx) {
+  const r = ctx?.sandbox
+    ? ctx.sandbox(cmd, { cwd: root, timeoutS: v.timeout_s || 900, env: v.env, writable: v.writable })
+    : run(cmd, { cwd: root, timeoutS: v.timeout_s || 900, env: v.env });
+  const txt = r.stdout + '\n' + r.stderr;
+  const num = (k) => { const m = txt.match(new RegExp(`^[#ℹ]\\s*${k}\\s+(\\d+)`, 'm')); return m ? +m[1] : undefined; };
+  r.counts = { tests: num('tests'), pass: num('pass'), fail: num('fail'), skipped: num('skipped'), todo: num('todo'), cancelled: num('cancelled') };
+  return r;
+}
+
+export const FAILING_CAP = 100;
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+// TAP: `not ok <n> - <name>`, subtests indented. node writes a `#` inside a name as `\#`, so an unescaped ` #` starts the directive.
+const TAP_FAIL_RE = /^\s*not ok\s+\d+(?:\s+-)?(?:\s+(.*))?$/;
+const TAP_DIRECTIVE_RE = /(?:^|\s)#\s*(\w*)/;
+// spec and dot reporters: `✖ <name> (<ms>ms)`. The duration comes last, except for a todo or skip, which node marks with
+// ` # <reason>` (or `# TODO`, `# SKIP`) after it. The `failing tests:` and `Failed tests:` summaries repeat these lines.
+const SPEC_FAIL_RE = /^\s*\u2716\s+(.*)\s\(\d+(?:\.\d+)?ms\)(\s+#.*)?$/;
+
+/**
+ * Names of the failed tests anywhere in a run's output, in order of first appearance, without repeats, todos or skips.
+ * At most `cap` names; `failing_total` is set only when there were more.
+ */
+export function failingTests(text, cap = FAILING_CAP) {
+  const seen = new Set();
+  for (const line of String(text).replace(ANSI_RE, '').split(/\r?\n/)) {
+    let m = line.match(TAP_FAIL_RE), name;
+    if (m) {
+      const rest = m[1] || '', d = rest.match(TAP_DIRECTIVE_RE);
+      if (!d || !/^(todo|skip)/i.test(d[1])) name = (d ? rest.slice(0, d.index) : rest).replace(/\\([\\#])/g, '$1');
+    } else if ((m = line.match(SPEC_FAIL_RE)) && !m[2]) name = m[1];
+    if (name && name.trim()) seen.add(name.trim());
+  }
+  const all = [...seen];
+  return all.length > cap ? { failing: all.slice(0, cap), failing_total: all.length } : { failing: all };
+}
+
+const ev = (r) => ({ cmd: r.cmd, exit: r.exit, ms: r.ms, counts: r.counts, timedOut: r.timedOut, ...failingTests(r.stdout + '\n' + r.stderr), out_tail: tail(r.stdout + (r.stderr ? '\n[stderr]\n' + r.stderr : ''), 1200) });
+/** "12 tests failed: a, b, ... and 2 more" from a run's evidence (first 10 names), or '' when it names none. */
+const named = (e) => {
+  const n = e.failing_total ?? e.failing.length, show = e.failing.slice(0, 10);
+  return n ? `${n} test${n === 1 ? '' : 's'} failed: ${show.join(', ')}${n > show.length ? ` and ${n - show.length} more` : ''}` : '';
+};
+
+export const verifiers = {
+  command(v, ctx) {
+    const expect = v.expect_exit ?? 0;
+    let r = runCounted(v.cmd, ctx.root, v, ctx);
+    const first = ev(r), firstExit = r.exit;
+    if (r.exit === 127) return { status: 'error', detail: `command not found: ${v.cmd}`, evidence: first };
+    const tooMany = (r2) => {
+      const c = r2.counts; const p = [];
+      if ((c.cancelled || 0) > 0) p.push(`${c.cancelled} cancelled/hung`);
+      if (v.max_skipped !== undefined && (c.skipped || 0) + (c.todo || 0) > v.max_skipped) p.push(`${(c.skipped || 0) + (c.todo || 0)} skipped/todo > allowed ${v.max_skipped}`);
+      if (v.min_tests !== undefined && (c.tests ?? c.pass ?? 0) < v.min_tests) p.push(`only ${c.tests ?? c.pass ?? 0} tests ran, contract requires ≥ ${v.min_tests} (tests deleted or not discovered?)`);
+      return p;
+    };
+    if (r.exit === expect && !tooMany(r).length) return { status: 'pass', detail: `exit ${r.exit} in ${r.ms} ms`, evidence: first };
+    if (r.exit === expect) return { status: 'fail', detail: [...tooMany(r), named(first)].filter(Boolean).join('; '), evidence: first };
+    // Both runs keep their failing names: on a flaky result the first run's list is the tests that flapped.
+    for (let i = 0; i < (ctx.flakyReruns ?? 1); i++) {
+      r = runCounted(v.cmd, ctx.root, v, ctx);
+      if (r.exit === expect && !tooMany(r).length) return { status: 'flaky', detail: `failed (exit ${firstExit}${named(first) ? `; ${named(first)}` : ''}) then passed on re-run ${i + 1}: flaky, not a pass. Root-cause the non-determinism.`, evidence: { first, rerun: ev(r) } };
+    }
+    const rerun = ev(r), n = named(rerun.failing.length ? rerun : first);
+    return { status: 'fail', detail: `exit ${r.exit} (expected ${expect})${r.timedOut ? ', timed out' : ''}; failed again on re-run, so it is real${n ? `; ${n}` : ''}`, evidence: { first, rerun } };
+  },
+
+  file_exists(v, ctx) {
+    return fs.existsSync(path.join(ctx.root, v.path)) ? { status: 'pass', detail: `${v.path} exists` } : { status: 'fail', detail: `${v.path} does not exist in the repo` };
+  },
+
+  test_exists(v, ctx) {
+    const f = path.join(ctx.root, v.test_file);
+    if (!fs.existsSync(f)) return { status: 'fail', detail: `test file ${v.test_file} not found` };
+    if (v.test_name && !fs.readFileSync(f, 'utf8').includes(v.test_name)) return { status: 'fail', detail: `test "${v.test_name}" not found in ${v.test_file}` };
+    return { status: 'pass', detail: 'test present' };
+  },
+
+  /** The test must exist now, FAIL at the base revision (with the new test copied in), and PASS now. */
+  test_red_green(v, ctx) {
+    const exists = verifiers.test_exists(v, ctx);
+    if (exists.status !== 'pass') return exists;
+    if (!ctx.base) return { status: 'error', detail: 'base revision unresolved; cannot prove red-green' };
+    const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'proofline-base-'));
+    try {
+      const add = git(['worktree', 'add', '--detach', '--force', wt, ctx.base], ctx.root);
+      if (!add.ok) return { status: 'error', detail: `git worktree add failed: ${add.err}` };
+      for (const f of [v.test_file, ...(v.support_files || [])]) {
+        fs.mkdirSync(path.dirname(path.join(wt, f)), { recursive: true });
+        fs.copyFileSync(path.join(ctx.root, f), path.join(wt, f));
+      }
+      if (v.setup) run(v.setup, { cwd: wt, timeoutS: 900 });
+      const cmd = sub(v.cmd, { test: v.test_file, name: v.test_name || '' });
+      const red = runCounted(cmd, wt, v, ctx);
+      const green = runCounted(cmd, ctx.root, v, ctx);
+      const evd = { base: ctx.base, red: ev(red), green: ev(green) };
+      if (red.exit === 127 || green.exit === 127) return { status: 'error', detail: 'test command not found', evidence: evd };
+      if (red.exit === 0) return { status: 'fail', detail: `test PASSES on base ${ctx.base.slice(0, 8)} without the change: it does not prove the change (tests how, not what?)`, evidence: evd };
+      if (green.exit !== 0) return { status: 'fail', detail: `test fails on the current tree (exit ${green.exit})`, evidence: evd };
+      if (v.test_name && !(green.stdout + green.stderr).includes(v.test_name)) return { status: 'fail', detail: `"${v.test_name}" did not appear in the run output: it was not executed`, evidence: evd };
+      return { status: 'pass', detail: `red on base (exit ${red.exit}), green now`, evidence: evd };
+    } finally {
+      git(['worktree', 'remove', '--force', wt], ctx.root);
+      fs.rmSync(wt, { recursive: true, force: true });
+    }
+  },
+
+  metric(v, ctx) {
+    // One bench run serves every metric criterion that uses the same command (benches are slow).
+    // The load is read before the run: a number taken on a busy machine is not evidence either way.
+    ctx.cmdCache ??= {};
+    const ck = v.cmd + JSON.stringify(v.env || {});
+    const max = ctx.contract?.defaults?.max_load_per_cpu;
+    const { r, machine } = ctx.cmdCache[ck] ??= (() => {
+      const m = (ctx.machine || readMachine)();
+      const machine = { load1: m.load1, cpus: m.cpus, load_per_cpu: +(m.load1 / Math.max(1, m.cpus)).toFixed(2), node: nodeVersion(ctx.root, v.env) };
+      if (typeof max === 'number' && m.load1 / Math.max(1, m.cpus) > max) return { r: null, machine };
+      const exec = ctx.sandbox
+        ? (cmd, o) => ctx.sandbox(cmd, { ...o, writable: v.writable })
+        : (cmd, o) => run(cmd, o);
+      return { r: exec(v.cmd, { cwd: ctx.root, timeoutS: v.timeout_s || 1800, env: v.env }), machine };
+    })();
+    const on = `load ${machine.load1.toFixed(2)} / ${machine.cpus} CPUs, node ${machine.node || 'not found'}`;
+    if (!r) return { status: 'blocked', detail: `machine busy: load ${machine.load1.toFixed(2)} over ${machine.cpus} CPUs = ${machine.load_per_cpu.toFixed(2)} per CPU > max_load_per_cpu ${max}; the bench was not run. Re-run when the machine is idle.`, evidence: { cmd: v.cmd, machine } };
+    let data;
+    if (v.output_file) { try { data = JSON.parse(fs.readFileSync(path.resolve(ctx.root, sub(v.output_file, process.env)), 'utf8')); } catch {} }
+    else data = lastJson(r.stdout);
+    const e = { cmd: v.cmd, exit: r.exit, ms: r.ms, machine, out_tail: tail(r.stdout + r.stderr, 800) };
+    if (r.exit === 127) return { status: 'error', detail: `bench command not found: ${v.cmd} (is the bench rig committed in the repo?)`, evidence: e };
+    if (data === undefined) return { status: 'error', detail: `no JSON output from bench (exit ${r.exit})`, evidence: e };
+    const val = pick(data, v.key);
+    e.key = v.key; e.measured = val; e.threshold = `${v.op} ${v.value}`;
+    if (typeof val !== 'number') return { status: 'error', detail: `metric ${v.key} missing from bench output`, evidence: e };
+    const ok = { '<': val < v.value, '<=': val <= v.value, '>': val > v.value, '>=': val >= v.value, '==': val === v.value }[v.op];
+    const name = v.name || v.key;
+    ctx.measured[name] = val;
+    const b = ctx.baseline?.[name];
+    let reg = '';
+    if (typeof b === 'number' && b !== 0) {
+      const tol = (ctx.tolerancePct ?? 20) / 100;
+      const worse = v.op.startsWith('<') ? val > b * (1 + tol) : v.op.startsWith('>') ? val < b * (1 - tol) : false;
+      e.baseline = b;
+      if (worse) reg = ` REGRESSION vs baseline ${b} (> ${ctx.tolerancePct ?? 20}%)`;
+    }
+    if (!ok) return { status: 'fail', detail: `${name} = ${val}, needs ${v.op} ${v.value}${reg} (${on})`, evidence: e };
+    if (reg) return { status: 'fail', detail: `${v.key} = ${val} meets threshold but${reg} (${on})`, evidence: e };
+    return { status: 'pass', detail: `${v.key} = ${val} ${v.op} ${v.value} (${on})`, evidence: e };
+  },
+
+  grep(v, ctx) {
+    const f = path.join(ctx.root, v.file);
+    if (!fs.existsSync(f)) return { status: 'fail', detail: `${v.file} not found` };
+    const txt = fs.readFileSync(f, 'utf8');
+    const re = new RegExp(v.pattern, v.flags || 'm');
+    const m = txt.match(re);
+    const want = (v.must || 'present') === 'present';
+    if (!!m === want) return { status: 'pass', detail: `/${v.pattern}/ ${want ? 'present' : 'absent'} in ${v.file}`, evidence: m ? { line: txt.slice(0, m.index).split('\n').length, text: m[0] } : undefined };
+    return { status: 'fail', detail: `/${v.pattern}/ ${want ? 'NOT found' : 'still present'} in ${v.file}${v.why ? ` (${v.why})` : ''}` };
+  },
+
+  /** The symbol must be referenced (not just defined) in a file reachable by static imports from the default entry point. */
+  wiring(v, ctx) {
+    const entry = path.join(ctx.root, v.entry);
+    if (!fs.existsSync(entry)) return { status: 'fail', detail: `entry ${v.entry} not found` };
+    const seen = new Map([[entry, null]]); const q = [entry];
+    const exts = ['', '.mjs', '.js', '.cjs', '.ts', '/index.mjs', '/index.js', '/index.ts'];
+    const defRe = new RegExp(`(function\\*?|class|const|let|var)\\s+${v.symbol}\\b|^\\s*(async\\s+)?${v.symbol}\\s*\\([^)]*\\)\\s*\\{`, 'm');
+    const useRe = new RegExp(`\\b${v.symbol}\\b`);
+    while (q.length) {
+      const f = q.shift(); let src = '';
+      try { src = fs.readFileSync(f, 'utf8'); } catch { continue; }
+      const uses = src.split('\n').filter((l) => useRe.test(l) && !defRe.test(l) && !/^\s*(\/\/|\*|import\b|export\s*\{)/.test(l));
+      if (uses.length) {
+        const chain = []; for (let x = f; x; x = seen.get(x)) chain.unshift(path.relative(ctx.root, x));
+        return { status: 'pass', detail: `${v.symbol} used on the default path: ${chain.join(' → ')}`, evidence: { chain, line: uses[0].trim().slice(0, 200) } };
+      }
+      for (const m of src.matchAll(/(?:import|export)[^'"]*?from\s*['"](\.[^'"]+)['"]|import\s*\(\s*['"](\.[^'"]+)['"]\s*\)|require\(\s*['"](\.[^'"]+)['"]\s*\)|^\s*import\s+['"](\.[^'"]+)['"]/gm)) {
+        const spec = m[1] || m[2] || m[3] || m[4];
+        for (const e of exts) {
+          const p = path.resolve(path.dirname(f), spec + e);
+          if (fs.existsSync(p) && fs.statSync(p).isFile()) { if (!seen.has(p)) { seen.set(p, f); q.push(p); } break; }
+        }
+      }
+    }
+    return { status: 'fail', detail: `${v.symbol} is not referenced from the default path (${v.entry}; ${seen.size} files reachable). Built but not wired in.` };
+  },
+
+  scope(v, ctx) {
+    if (!ctx.base) return { status: 'error', detail: 'base unresolved; cannot compute scope' };
+    const allow = v.allow || ctx.task.scope?.allow || ['**'];
+    const out = [...ctx.changed.keys()].filter((f) => !matchAny(f, allow));
+    return out.length ? { status: 'fail', detail: `changes outside the approved scope: ${out.join(', ')}`, evidence: { outside: out, allow } } : { status: 'pass', detail: `${ctx.changed.size} changed files, all in scope` };
+  },
+
+  docs(v, ctx) {
+    const r = run(v.cmd, { cwd: ctx.root, timeoutS: v.timeout_s || 300 });
+    if (r.exit !== 0) return { status: r.exit === 127 ? 'error' : 'fail', detail: `docs generator exit ${r.exit}`, evidence: ev(r) };
+    const st = git(['status', '--porcelain', '--', ...v.paths], ctx.root).out;
+    return st ? { status: 'fail', detail: `generated docs differ from what is committed:\n${st}`, evidence: { changed: st } } : { status: 'pass', detail: 'docs regenerated, no diff' };
+  },
+
+  pushed(v, ctx) {
+    const branch = v.branch || ctx.contract.defaults?.branch || 'main';
+    const remote = v.remote || ctx.contract.defaults?.remote || 'origin';
+    const dirty = git(['status', '--porcelain'], ctx.root).out.split('\n').filter((l) => l && !l.includes('.proofline/'));
+    if (dirty.length) return { status: 'fail', detail: `working tree not clean (${dirty.length} paths); work held locally`, evidence: { dirty: dirty.slice(0, 20) } };
+    const head = git(['rev-parse', 'HEAD'], ctx.root).out;
+    // HEAD passes as the branch's tip or as a commit under it: a task whose commit sits inside a pushed stack is pushed
+    const o = onRemote(ctx.root, head, remote, branch);
+    if (!o.ok) return { status: 'error', detail: `cannot reach ${remote}: ${o.err}` };
+    if (o.at) return { status: 'pass', detail: `HEAD ${head.slice(0, 8)} is ${remote}/${branch}`, evidence: { tip: o.tip, behind: 0 } };
+    if (o.contains) return { status: 'pass', detail: `HEAD ${head.slice(0, 8)} is on ${remote}/${branch}, ${o.behind} commit${o.behind === 1 ? '' : 's'} under its tip ${o.tip.slice(0, 8)}`, evidence: { tip: o.tip, behind: o.behind } };
+    return { status: 'fail', detail: `HEAD ${head.slice(0, 8)} not pushed: ${remote}/${branch} is ${(o.tip || 'missing').slice(0, 8)}${o.unknown ? ', which could not be fetched to see whether it holds HEAD' : ''}`, evidence: { tip: o.tip || null, unknown: o.unknown } };
+  },
+};

package/src/claims.mjs

@@ -0,0 +1,60 @@
+// Parse an agent's status report and check every claim against evidence. Claims are never trusted.
+import { git, onRemote } from './util.mjs';
+
+const DONE = /^(done|complete(d)?|verified|pass(ed)?|fixed|finished|green)$/i;
+const HEDGE = /\b(should work|likely|probably|untested|not tested|later|follow[- ]?up|out of scope|defer(red)?|todo|next session|in a future)\b/i;
+
+/** Lines: TASK-ID | status | commit | tests | measured vs target | missing */
+export function parseClaims(text, taskIds) {
+  const out = [];
+  for (const raw of String(text || '').split('\n')) {
+    if (!raw.includes('|')) continue;
+    const cells = raw.split('|').map((s) => s.trim()).filter((s, i, a) => !(s === '' && (i === 0 || i === a.length - 1)));
+    if (cells.length < 2) continue;
+    const id = cells[0].replace(/[*`]/g, '');
+    if (taskIds && !taskIds.includes(id)) continue;
+    out.push({ raw: raw.trim(), id, status: cells[1] || '', commit: cells[2] || '', tests: cells[3] || '', numbers: cells[4] || '', missing: cells[5] || '' });
+  }
+  return out;
+}
+
+/** results: per-task { decision, measured: {key: val}, metricLabels: {key: [aliases]} } */
+export function checkClaim(root, claim, res, { requirePushed = false, remote = 'origin', branch = 'main' } = {}) {
+  const issues = [];
+  const claimedDone = DONE.test(claim.status.replace(/[^a-z]/gi, ''));
+  if (claimedDone && res.decision !== 'PASS') issues.push(`claimed "${claim.status}" but the independent gate says ${res.decision}: ${res.failing.join('; ') || 'see report'}`);
+  if (HEDGE.test(claim.raw)) issues.push(`hedged or deferred wording ("${claim.raw.match(HEDGE)[0]}"): not an acceptable status; never defer, report blocked with what you need`);
+  const sha = (claim.commit.match(/\b[0-9a-f]{7,40}\b/i) || [])[0];
+  if (claimedDone && !sha) issues.push('claimed done without a commit hash');
+  if (sha) {
+    const full = git(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`], root);
+    if (!full.ok) issues.push(`commit ${sha} does not exist`);
+    else {
+      if (!git(['merge-base', '--is-ancestor', full.out, 'HEAD'], root).ok) issues.push(`commit ${sha} is not in HEAD's history`);
+      if (requirePushed) {
+        const o = onRemote(root, full.out, remote, branch);
+        if (!o.ok) issues.push(`cannot check that commit ${sha} is on ${remote}/${branch}: ${o.err}`);
+        else if (!o.contains) issues.push(`commit ${sha} is not on ${remote}/${branch}${o.unknown ? ` (its tip ${o.tip.slice(0, 8)} could not be fetched)` : ''}`);
+      }
+    }
+  }
+  const names = claim.tests.split(/[,;]+/).map((s) => s.trim().replace(/^`|`$/g, '')).filter((s) => s && !/^(-|n\/a|none)$/i.test(s));
+  if (claimedDone && !names.length) issues.push('claimed done without naming the test(s) that prove it');
+  for (const n of names) {
+    const base = n.replace(/\s*\(.*\)$/, '').split(/\s+/)[0];
+    if (!git(['grep', '-q', '-F', base], root).ok && !git(['ls-files', '--', `*${base}*`], root).out) issues.push(`named test "${base}" not found in the repo`);
+  }
+  const keys = Object.keys(res.measured || {});
+  if (claimedDone && keys.length && !/\d/.test(claim.numbers)) issues.push(`task has metric targets (${keys.join(', ')}) but the claim gives no measured numbers`);
+  for (const k of keys) {
+    const aliases = [k, ...(res.metricLabels?.[k] || [])];
+    for (const a of aliases) {
+      const m = claim.numbers.match(new RegExp(a.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\D{0,12}?(\\d+(?:\\.\\d+)?)', 'i'));
+      if (!m) continue;
+      const said = +m[1], got = res.measured[k];
+      if (Math.abs(said - got) > Math.max(0.15 * Math.abs(got), 1)) issues.push(`claimed ${a} ${said} but measured ${got}`);
+      break;
+    }
+  }
+  return { claim: claim.raw, id: claim.id, ok: issues.length === 0, issues };
+}