toolroll 0.5.0

package/scripts/launchd-certification.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * The disposable macOS launchd certificate (docs/PROCESS_CONTAINMENT_PLAN.md,
+ * acceptance 5). It INSTALLS A DISPOSABLE LaunchAgent under a throwaway
+ * label in the current user's gui domain, so it runs only where an operator
+ * decided to run it:
+ *
+ *   npm run certify:launchd -- [--observe-ms 60000] [--output <file>] [--keep]
+ *
+ * With the shared unit generator (daemon.ts, the same document the CLI
+ * daemon and the desktop service use) it proves, against the real launchd:
+ *   1. automatic relaunch after an UNEXPECTED CLEAN EXIT (exit 0) — with no
+ *      manual kickstart: the certificate only watches;
+ *   2. automatic relaunch after SIGKILL;
+ *   3. explicit stop (bootout + disable) stays down beyond the throttle, and
+ *      a start (enable + bootstrap) comes back with a FRESH incarnation and
+ *      exactly one writer at a time — no duplicate;
+ *   4. observation beyond ThrottleInterval (at least 60 s in total).
+ * It then boots the disposable label out, re-enables it (leaving no
+ * disabled record behind) and removes its plist. Nothing here touches an
+ * installed Toolroll service, a database, or another label.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+if (process.platform !== "darwin") { console.error("the launchd certificate runs on macOS only; Linux/Windows service behaviour is covered by the generation tests and the restart certificate"); process.exit(2); }
+let observeMs = 60_000;
+let output = resolve("output/certification/launchd.json");
+let keep = false;
+for (let index = 2; index < process.argv.length; index++) {
+  const arg = process.argv[index];
+  if (arg === "--keep") keep = true;
+  else if (arg === "--observe-ms") observeMs = Number(process.argv[++index]);
+  else if (arg === "--output") output = resolve(process.argv[++index]);
+  else if (arg === "--help") { console.log("npm run certify:launchd -- [--observe-ms 60000] [--output <file>] [--keep]"); process.exit(0); }
+  else throw new Error(`unknown argument ${arg}`);
+}
+if (!Number.isFinite(observeMs) || observeMs < 60_000) throw new Error("--observe-ms must be at least 60000: the throttle is 15 s and the assertion must outlast it");
+
+const { launchdPlist, installLaunchdService, stopLaunchdService, daemonStatus } = await import(pathToFileURL(resolve(root, "dist/daemon.js")));
+const { run } = await import(pathToFileURL(resolve(root, "dist/exec.js")));
+
+const sleep = ms => new Promise(resolvePromise => setTimeout(resolvePromise, ms));
+const state = realpathSync(await mkdtemp(join(tmpdir(), "so-launchd-cert-")));
+const label = `com.standing-orders.certificate.${state.split("-").pop()}`;
+const uid = process.getuid();
+const service = `gui/${uid}/${label}`;
+const home = process.env["HOME"];
+const definition = {
+  platform: "darwin",
+  label,
+  unitPath: join(home, "Library", "LaunchAgents", `${label}.plist`),
+  unitContent: launchdPlist({ label, command: [process.execPath, resolve(root, "scripts/fixtures/restart-service.mjs")], workingDirectory: state, pathEnv: dirname(process.execPath), logPath: join(state, "service.log"), environment: { SO_CERT_STATE: state } }),
+  logPath: join(state, "service.log"),
+  bin: process.execPath,
+  entry: resolve(root, "scripts/fixtures/restart-service.mjs"),
+};
+const supervise = (file, args) => run(file, args, { timeoutMs: 30_000 });
+const heartbeat = () => { try { return JSON.parse(readFileSync(join(state, "heartbeat.json"), "utf8")); } catch { return null; } };
+const alive = pid => { try { process.kill(pid, 0); return true; } catch { return false; } };
+async function until(predicate, ms, what) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { const value = predicate(); if (value) return value; await sleep(100); }
+  throw new Error(`timed out waiting for ${what}`);
+}
+/** Writers that beat inside a window: exactly one pid at a time means no duplicate controller. */
+const writersWithin = ms => { const now = Date.now(); return readdirSync(join(state, "writers")).filter(name => now - Number(readFileSync(join(state, "writers", name), "utf8")) < ms).map(name => Number(name.split("-")[0])); };
+
+const started = Date.now();
+const steps = [];
+const step = (name, ok, detail) => { steps.push({ name, ok, detail, at: new Date().toISOString() }); console.log(`${ok ? "ok  " : "FAIL"} ${name}: ${detail}`); if (!ok) throw new Error(`${name}: ${detail}`); };
+let installed = false;
+try {
+  mkdirSync(join(state, "writers"), { recursive: true });
+  const first = await installLaunchdService(definition, supervise);
+  installed = true;
+  step("install", first.ok, first.ok ? `${first.action} ${label}` : first.message);
+  const beat1 = await until(() => heartbeat(), 20_000, "the first heartbeat");
+  step("first-incarnation", alive(beat1.pid), `pid ${beat1.pid} incarnation ${beat1.incarnation}`);
+
+  // 1. Unexpected clean exit: the fixture exits 0 on request. NO kickstart
+  //    from here — launchd alone must bring it back (KeepAlive=true, after
+  //    ThrottleInterval).
+  writeFileSync(join(state, "exit-now"), "");
+  await until(() => !alive(beat1.pid), 10_000, "the clean exit");
+  const beat2 = await until(() => { const b = heartbeat(); return b !== null && b.incarnation !== beat1.incarnation && alive(b.pid) ? b : null; }, 45_000, "the relaunch after exit 0");
+  step("relaunch-after-clean-exit", beat2.pid !== beat1.pid, `launchd relaunched after exit 0 without a kickstart: pid ${beat1.pid} → ${beat2.pid}, incarnation ${beat2.incarnation}`);
+
+  // 2. Crash: SIGKILL the running incarnation.
+  process.kill(beat2.pid, "SIGKILL");
+  await until(() => !alive(beat2.pid), 10_000, "the kill");
+  const beat3 = await until(() => { const b = heartbeat(); return b !== null && b.incarnation !== beat2.incarnation && alive(b.pid) ? b : null; }, 45_000, "the relaunch after SIGKILL");
+  step("relaunch-after-sigkill", beat3.pid !== beat2.pid, `launchd relaunched after SIGKILL: pid ${beat2.pid} → ${beat3.pid}`);
+
+  // 3. Explicit stop stays down beyond the throttle; start brings a fresh
+  //    incarnation with exactly one writer.
+  const stopped = await stopLaunchdService(definition, supervise);
+  step("explicit-stop", stopped.wasLoaded, "bootout + disable");
+  await until(() => !alive(beat3.pid), 10_000, "the stop to end the process");
+  await sleep(20_000);
+  const afterStop = heartbeat();
+  step("stays-down", afterStop !== null && afterStop.incarnation === beat3.incarnation && !alive(afterStop.pid), `no relaunch 20 s after an explicit stop (last incarnation ${afterStop?.incarnation})`);
+  const status = await daemonStatus(definition, supervise);
+  step("status-disabled", status.state === "disabled", `status reads ${status.state}: ${status.detail}`);
+  const again = await installLaunchdService(definition, supervise);
+  step("start-again", again.ok, again.ok ? `${again.action} (changed=${again.changed})` : again.message);
+  const beat4 = await until(() => { const b = heartbeat(); return b !== null && b.incarnation !== beat3.incarnation && alive(b.pid) ? b : null; }, 30_000, "the fresh incarnation after start");
+  await sleep(1_500);
+  const writers = [...new Set(writersWithin(1_000))];
+  step("one-writer", writers.length === 1 && writers[0] === beat4.pid, `writers beating in the last second: ${writers.join(", ") || "none"} (fresh incarnation ${beat4.incarnation})`);
+  const idempotent = await installLaunchdService(definition, supervise);
+  await sleep(1_500);
+  step("idempotent-start", idempotent.ok && idempotent.action === "started" && heartbeat().incarnation === beat4.incarnation, `a second start on a running unchanged definition left pid ${beat4.pid} alone (${idempotent.ok ? idempotent.action : idempotent.message})`);
+
+  // 4. Observe beyond the throttle.
+  const remaining = observeMs - (Date.now() - started);
+  if (remaining > 0) await sleep(remaining);
+  const final = heartbeat();
+  step("observed-beyond-throttle", final !== null && alive(final.pid) && Date.now() - started >= observeMs, `observed ${Math.round((Date.now() - started) / 1000)} s (throttle 15 s); live pid ${final?.pid}`);
+} catch (error) {
+  steps.push({ name: "error", ok: false, detail: String(error), at: new Date().toISOString() });
+  console.error(String(error));
+} finally {
+  if (installed && !keep) {
+    await stopLaunchdService(definition, supervise);
+    // Leave no disabled record for a label that no longer exists.
+    await supervise("launchctl", ["enable", service]);
+    try { rmSync(definition.unitPath); } catch { /* already gone */ }
+  }
+  const ok = steps.every(one => one.ok);
+  mkdirSync(dirname(output), { recursive: true });
+  writeFileSync(output, `${JSON.stringify({ ok, label, state: keep ? state : null, node: process.version, observedMs: Date.now() - started, steps, limits: [
+    "this certifies launchd's automatic relaunch and the shared unit's lifecycle for a disposable label in this user's gui domain",
+    "it does not reboot; LaunchAgents resume at user login after a reboot, not before FileVault unlock/login",
+  ] }, null, 2)}\n`);
+  if (!keep) rmSync(state, { recursive: true, force: true });
+  console.log(`${ok ? "PASS" : "FAIL"} — launchd certificate written to ${output}`);
+  process.exit(ok ? 0 : 1);
+}

package/scripts/pilot.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/** Twenty real subscription tasks under preapproved fixture contracts, with explicit lead completion. */
+import assert from 'node:assert/strict';
+import {spawn} from 'node:child_process';
+import {createHash,randomUUID} from 'node:crypto';
+import {mkdir,mkdtemp,readFile,readdir,realpath,writeFile} from 'node:fs/promises';
+import {join,dirname,resolve} from 'node:path';
+import {tmpdir} from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {scenario,scenarioIds} from './fixtures/pilot-scenarios.mjs';
+import {createFixtureLead,completeFixtureAssignment} from './canary-assertions.mjs';
+const root=resolve(dirname(fileURLToPath(import.meta.url)),'..');
+let output=resolve('output/certification/pilot.json'), concurrency=4, playwright=null, selected=scenarioIds, providers=['claude','codex'];
+for(let i=2;i<process.argv.length;i++) {
+  const arg=process.argv[i];
+  if(arg==='--output') output=resolve(process.argv[++i]);
+  else if(arg==='--concurrency') concurrency=Number(process.argv[++i]);
+  else if(arg==='--playwright') playwright=resolve(process.argv[++i]);
+  else if(arg==='--scenario') selected=[process.argv[++i]];
+  else if(arg==='--provider') providers=[process.argv[++i]];
+  else if(arg==='--help') {console.log('node scripts/pilot.mjs [--scenario id] [--provider claude|codex] [--concurrency 4] --playwright /installed/playwright/index.mjs [--output file]');process.exit(0);}
+  else throw new Error('unknown argument '+arg);
+}
+assert(Number.isInteger(concurrency)&&concurrency>=1&&concurrency<=4);
+assert(selected.every(x=>scenarioIds.includes(x))&&providers.every(x=>['claude','codex'].includes(x)));
+const models={claude:'sonnet',codex:'gpt-5.6-sol'};
+function run(file,args,options={}) {
+  return new Promise((resolvePromise,reject)=>{
+    const child=spawn(file,args,{cwd:options.cwd??root,env:process.env,stdio:['ignore','pipe','pipe']});
+    let stdout='',stderr=''; child.stdout.on('data',c=>stdout+=c); child.stderr.on('data',c=>stderr+=c);
+    const timer=setTimeout(()=>child.kill('SIGTERM'),options.timeoutMs??20*60_000);
+    child.on('error',e=>{clearTimeout(timer);reject(e);});
+    child.on('close',(code,signal)=>{clearTimeout(timer);resolvePromise({code,signal,stdout,stderr});});
+  });
+}
+async function identity() {
+  const hash=createHash('sha256');
+  async function visit(dir,prefix) {for(const e of (await readdir(dir,{withFileTypes:true})).sort((a,b)=>a.name.localeCompare(b.name))) {const p=join(dir,e.name),name=prefix+'/'+e.name;if(e.isDirectory()) await visit(p,name);else hash.update(name).update('\0').update(await readFile(p)).update('\0');}}
+  await visit(join(root,'dist'),'dist'); const executableSha256=hash.copy().digest('hex');
+  for(const file of ['package.json','scripts/pilot.mjs','scripts/fixtures/pilot-scenarios.mjs','scripts/canary-assertions.mjs']) hash.update(file).update('\0').update(await readFile(join(root,file))).update('\0');
+  return {sha256:hash.digest('hex'),executableSha256,sourceCommit:(await run('git',['rev-parse','HEAD'])).stdout.trim()};
+}
+const runtime=await identity(), startedAt=new Date();
+const base=await realpath(await mkdtemp(join(tmpdir(),'standing-orders-real-pilot-')));
+const results=[];
+async function one(id,provider,wave) {
+  const spec=scenario(id,playwright), model=models[provider], name=provider+'-'+id;
+  const dir=join(base,name), repo=join(dir,'repo'), db=join(dir,'orders.db'), pool=join(dir,'worktrees');
+  const steps=[]; let final=null,baseSha=null;
+  const record={name,scenario:id,category:spec.category,provider,model,wave,passed:false,manualInterventions:0,retainedAt:dir,startedAt:new Date().toISOString(),steps};
+  async function cli(label,args,accepted=[0]) {
+    assert.deepEqual(await identity(),runtime,'runtime changed during the pilot');
+    const start=Date.now(), result=await run(process.execPath,[join(root,'dist/bin.js'),...args,'--db',db,'--json']);
+    steps.push({label,durationMs:Date.now()-start,exitCode:result.code});
+    if(!accepted.includes(result.code)) throw new Error(label+': '+(result.stdout+'\n'+result.stderr).slice(0,6000));
+    return JSON.parse(result.stdout);
+  }
+  const git=async args=>{const r=await run('git',args,{cwd:repo}); assert.equal(r.code,0,r.stderr);return r.stdout.trim();};
+  try {
+    await mkdir(repo,{recursive:true});
+    for(const [name,body] of Object.entries(spec.files)) {const path=join(repo,name);await mkdir(dirname(path),{recursive:true});await writeFile(path,body);}
+    if(spec.dependency) {const lock=await run('npm',['install','--package-lock-only','--ignore-scripts','--offline'],{cwd:repo});assert.equal(lock.code,0,lock.stderr);}
+    await git(['init','-q','-b','main']);await git(['config','user.email','pilot@example.invalid']);await git(['config','user.name','Unattended Pilot']);await git(['add','.']);await git(['commit','-qm','seed fixed pilot assignment']);baseSha=await git(['rev-parse','HEAD']);
+    const password='pilot-'+randomUUID(),auth=['--as','pilot','--token',password];
+    await cli('isolated fixture approver',['approver','add','pilot','--password',password]);
+    const registered=await cli('repository-bound worker',['runner','register','worker','--repo',repo,...auth]);
+    for(const phase of ['plan','build','repair']) await cli('route '+phase,['config','set',phase,'--provider',provider,'--model',model,...auth]);
+    await cli('bounded standing mode',['mode','set','--repo',repo,'--name','standard','--days','1',...auth]);
+    if(spec.dependency) await cli('approved offline setup',['setup','set','--repo',repo,'--command','npm ci --offline --ignore-scripts','--timeout-seconds','120','--yes',...auth]);
+    await cli('approved verification',['verify','set','--repo',repo,'--command','npm test','--timeout-seconds','120','--yes',...auth]);
+    const title='Pilot '+id+': implement the approved scope in '+spec.paths.join(', ')+'. Run npm test before writing proof. Do not modify verification, package, or vendor files.';
+    await cli('file assignment',['task','add',title,'--id','work','--repo',repo]);
+    const rubric=[
+      'The requested behavior passes every assertion in the provided verify.mjs.|check',
+      'The implementation changes only '+spec.paths.join(' and ')+'.|changed-path',
+      ...(spec.ui?['Desktop and mobile screenshots show the requested interface after the tested interaction at 1280x800 and 390x844.|screenshot,check']:[]),
+    ].join(';');
+    await cli('file fixed scope',['task','scope','work','--goal',spec.goal,'--touches',spec.paths.join(','),'--acceptance',rubric,'--not','Changing tests or dependency definitions, external publication, or unrelated files.']);
+    const preview=await cli('read scope',['task','show','work']);
+    await cli('approve exact fixture scope',['task','approve','work','--yes','--digest',preview.scope.digest,...auth]);
+    await writeFile(join(dir,'runner-token'),registered.token,{mode:0o600});
+    console.log(name+': starting unattended build and check');
+    const start=Date.now();
+    const worker=await run(process.execPath,[join(root,'dist/bin.js'),'watch','--runner','worker','--token-file',join(dir,'runner-token'),'--repo',repo,'--pool',pool,'--for','1000','--tick-every','200','--reconcile-every','1000','--bridge-every','3600000','--db',db,'--json']);
+    await writeFile(join(dir,'watch-result.json'),JSON.stringify(worker,null,2));
+    steps.push({label:'unattended watch build and check',durationMs:Date.now()-start,exitCode:worker.code});
+    final=await cli('read final result',['task','show','work']);
+    record.final=final;
+    assert.equal(worker.code,0,'watch failed');
+    assert.equal(final.task.state,'done','task did not complete');
+    const build=final.runs.find(r=>r.role==='builder'&&r.outcome==='built'); assert(build,'missing completed build');
+    assert(final.runs.every(r=>r.outcome!==null),'open orphan run');
+    const head=await git(['rev-parse',build.branch]); assert.notEqual(head,baseSha);
+    const changed=(await git(['diff','--name-only',baseSha,head])).split('\n').filter(Boolean).sort();
+    assert.deepEqual(changed,[...spec.paths].sort(),'unexpected or missing changed paths');
+    assert.equal(await git(['rev-parse','main']),baseSha,'default branch changed');
+    const leadFile=await createFixtureLead(args=>cli('scope fixture lead',args),{repo,auth,tokenFile:join(dir,'lead.token')});
+    record.completion=await completeFixtureAssignment(args=>cli('inspect and handle result',args),'work',leadFile,{head,runId:build.id});
+    const duplicate=await cli('duplicate dispatch',['tick','--runner','worker','--token',registered.token,'--repo',repo,'--pool',pool],[3]);assert.equal(duplicate.reason,'empty');
+    assert.deepEqual(await identity(),runtime);
+    record.commit=head;record.changed=changed;record.duplicateDispatch='refused-empty';record.passed=true;
+  } catch(error) {
+    record.error=error.stack;
+    if(final===null) {try{record.final=await cli('failure state',['task','show','work']);}catch{}}
+  }
+  record.finishedAt=new Date().toISOString();record.durationSeconds=(Date.parse(record.finishedAt)-Date.parse(record.startedAt))/1000;
+  results.push(record);await writeFile(join(dir,'result.json'),JSON.stringify(record,null,2));
+  console.log(name+': '+(record.passed?'PASS':'FAIL '+record.error.split('\n')[0]));
+}
+// Two successive service batches, each with fresh provider sessions and repositories.
+for(let wave=1;wave<=2;wave++) {
+  const ids=selected.filter((_,i)=>selected.length===1?wave===1:(i<5?wave===1:wave===2));
+  const queue=ids.flatMap(id=>providers.map(provider=>({id,provider})));
+  await Promise.all(Array.from({length:Math.min(concurrency,queue.length)},async()=>{while(queue.length){const job=queue.shift();await one(job.id,job.provider,wave);}}));
+}
+const times=results.map(r=>r.durationSeconds).sort((a,b)=>a-b), percentile=p=>times[Math.ceil(times.length*p)-1]??null;
+const report={version:1,passed:results.every(r=>r.passed),runtime,runtimeUnchanged:JSON.stringify(await identity())===JSON.stringify(runtime),startedAt:startedAt.toISOString(),finishedAt:new Date().toISOString(),platform:process.platform,node:process.versions.node,retainedAt:base,total:results.length,completed:results.filter(r=>r.passed).length,p50Seconds:percentile(.5),p95Seconds:percentile(.95),manualInterventions:0,results,
+ scope:'Real subscription builds, approved checks, and explicit lead completion in disposable repositories across two sequential batches. Contracts are fixed and approved before unattended dispatch. Failed cases receive no manual rescue.',
+ exclusions:['provider-authored planning (separately exercised by certify:provider)','mid-flight human revision or approval','direct-provider latency comparison','Windows','actual subscription exhaustion','production publication']};
+report.passed&&=report.runtimeUnchanged;
+await mkdir(dirname(output),{recursive:true});await writeFile(output,JSON.stringify(report,null,2)+'\n');console.log('Pilot: '+output+' ('+report.completed+'/'+report.total+')');if(!report.passed)process.exitCode=1;

package/scripts/proof-preflight.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Preflight the protocol files an agent writes at the end of an attempt —
+// the handoff (DONE), the proof (PROOF), and a park mailbox — with the SAME
+// parsers the machine ingests them through (dist/decision.js and
+// dist/proof.js), so a cap or a shape the brief names is checked before the
+// attempt ends instead of refusing the whole file after it. Beyond parsing,
+// every proof evidence ref is resolved against its source list — a check
+// ref must be an exact command in `checks`, a changed-path ref an exact
+// path in `changed`, a screenshot ref an exact path in `screenshots` — and
+// every signed criterion id given on the command line must be answered.
+// A caveat that names a criterion the proof marks `met` (its exact id as a
+// standalone token — `c1: …`) is a blocking exception: the proof's verdict
+// disagrees with its own words, the plane refutes it, and this preflight
+// refuses it first so the criterion can be marked not-met before the end.
+// Every caveat must name at least one known criterion — a signed id when
+// `--criteria` names the rubric (a proof-authored extra id is no authority
+// then), or one the proof answers only when nothing was signed: an
+// unassigned caveat, or one tagged with an unknown id, is refused the same
+// way — unrelated ideas belong in the handoff's followUps.
+// A criterion marked `met` whose cited check exited nonzero is refused in
+// the adjudicator's own words (`criterion "c1"'s check "…" exited 1`): a
+// met criterion rests only on checks that exited zero, so the agent marks
+// it not-met or cites a durable current-tree command that passes. A
+// not-met or not-checked criterion may cite a failed check honestly.
+//
+//   node scripts/proof-preflight.mjs [--done <file>] [--proof <file>]
+//        [--park <file>] [--rubric <canonical-json-file>] [--criteria c1,c2,…]
+//
+// Exit 0 when every named file parses and resolves; 1 with the problems
+// listed otherwise; 2 when dist/ is missing (run `npm run build` first).
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const dist = join(root, "dist");
+if (!existsSync(join(dist, "proof.js")) || !existsSync(join(dist, "decision.js"))) {
+  console.error("proof-preflight: dist/ is not built — run `npm run build` first");
+  process.exit(2);
+}
+const { parseProof, proofSubmissionProblems, failedMetChecks, failedCheckWords, blockingCaveats, caveatAttributionProblems, caveatAttributionWords } = await import(pathToFileURL(join(dist, "proof.js")).href);
+const { parseAcceptanceCriteria } = await import(pathToFileURL(join(dist, "scope.js")).href);
+const { parseHandoff, parseDecision } = await import(pathToFileURL(join(dist, "decision.js")).href);
+
+const args = process.argv.slice(2);
+const flag = name => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? null : (args[at + 1] ?? null);
+};
+const files = { done: flag("done"), proof: flag("proof"), park: flag("park") };
+let signed = (flag("criteria") ?? "").split(",").map(one => one.trim()).filter(one => one !== "");
+let rubric = null;
+const rubricFile = flag("rubric");
+if (args.includes("--rubric")) {
+  try {
+    if (rubricFile === null) throw new Error("--rubric needs a JSON file");
+    const value = JSON.parse(readFileSync(rubricFile, "utf8"));
+    if (!Array.isArray(value)) throw new Error("the rubric must be an array");
+    const parsed = parseAcceptanceCriteria(value);
+    if (parsed.problems.length > 0) throw new Error(parsed.problems.map(one => one.message).join("; "));
+    rubric = parsed.criteria;
+    const ids = rubric.map(one => one.id);
+    if (signed.length > 0 && (signed.length !== ids.length || signed.some(id => !ids.includes(id)))) throw new Error("--criteria disagrees with --rubric");
+    signed = ids;
+  } catch (error) {
+    console.error(`proof-preflight: invalid rubric (${error.message})`);
+    process.exit(2);
+  }
+}
+if (files.done === null && files.proof === null && files.park === null) {
+  console.error("proof-preflight: name at least one file (--done, --proof, --park)");
+  process.exit(2);
+}
+
+const problems = [];
+const read = (path, what) => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    problems.push(`${what}: cannot read ${path} (${error instanceof Error ? error.message : String(error)})`);
+    return null;
+  }
+};
+
+if (files.done !== null) {
+  const raw = read(files.done, "handoff");
+  if (raw !== null) {
+    const parsed = parseHandoff(raw);
+    if (!parsed.ok) for (const one of parsed.problems) problems.push(`handoff: ${one.reason} — ${one.message}`);
+    else console.log(`handoff: ok (${parsed.handoff.status}; ${parsed.handoff.changes.length} change(s), ${parsed.handoff.verification.length} verification line(s), ${parsed.handoff.followUps.length} follow-up(s))`);
+  }
+}
+
+if (files.park !== null) {
+  const raw = read(files.park, "park");
+  if (raw !== null) {
+    const parsed = parseDecision(raw);
+    if (!parsed.ok) for (const one of parsed.problems) problems.push(`park: ${one.reason} — ${one.message}`);
+    else console.log(`park: ok (${parsed.decision.options.length} option(s), recommendation ${parsed.decision.recommendation})`);
+  }
+}
+
+if (files.proof !== null) {
+  const raw = read(files.proof, "proof");
+  if (raw !== null) {
+    const parsed = parseProof(raw);
+    if (!parsed.ok) {
+      for (const one of parsed.problems) problems.push(`proof: ${one.reason} — ${one.message}`);
+    } else {
+      const { proof } = parsed;
+      const failed = new Set(failedMetChecks(proof).map(failedCheckWords));
+      problems.push(...proofSubmissionProblems(proof, rubric ?? []).map(one => `proof: ${one}${failed.has(one) ? " — a criterion marked met cites only checks that exited zero; mark it not-met, or cite a durable current-tree command that passed" : ""}`));
+      const answered = new Set(proof.criteria.map(one => one.id));
+      for (const id of signed) {
+        if (!answered.has(id)) problems.push(`proof: signed criterion ${id} is not answered`);
+      }
+      for (const one of blockingCaveats(proof)) {
+        problems.push(`proof: criterion ${one.criterionId} is marked met, but caveat ${one.index + 1} admits an exception to it — mark it not-met or drop the exception: ${JSON.stringify(one.caveat)}`);
+      }
+      // Every caveat names a known criterion (final authority closure): an
+      // unassigned caveat, or one tagged with an id nobody signed (or, with
+      // no signed rubric, the proof never answers), refuses here — the
+      // plane refutes the same proof, so it is said before the attempt
+      // ends. Unrelated ideas go to the handoff's followUps.
+      for (const one of caveatAttributionProblems(proof, signed)) {
+        problems.push(`proof: ${caveatAttributionWords(one)}`);
+      }
+      for (const shot of proof.screenshots) {
+        if (!existsSync(resolve(dirname(files.proof), shot.path)) && !existsSync(resolve(shot.path))) problems.push(`proof: screenshot ${shot.path} does not exist beside the proof`);
+      }
+      if (problems.length === 0) console.log(`proof: ok (${proof.criteria.length} criteria, ${proof.checks.length} checks, ${proof.changed.length} changed, ${proof.caveats.length} caveat(s), none blocking, ${proof.screenshots.length} screenshot(s))`);
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`proof-preflight: ${problems.length} problem(s)\n  ${problems.join("\n  ")}`);
+  process.exit(1);
+}
+console.log("proof-preflight: every named file parses and resolves");