shapeup-sdlc 1.6.2

package/hooks/session-rehydrate.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Session rehydrate — SessionStart hook, matcher "startup|compact|resume|clear".
+//
+// Fires when a session begins with a harness run already in flight, and injects the RunSnapshot's
+// rehydrate_hint as additionalContext: re-derive round/attempt/hill from the files, never from
+// memory. This is the reflex that makes the file-first run-state load-bearing at the exact moment
+// the in-context copy is absent or degraded: without it the orchestrator can re-dispatch an
+// already-ingested order, miscount attempts off a lossy summary, or — measured, below — re-open a
+// run that is already open and rebuild the whole pipeline from phase 1.
+//
+// v1.4.1 — `startup` ADDED TO THE MATCHER, and this is a measured correction, not a widening.
+//
+// The matcher was `compact|resume`. Both of those are continuations of a conversation that still
+// exists. The commonest continuity event in real use has neither: you close the terminal and come
+// back tomorrow, or a teammate picks the work up in a fresh checkout. The CLI reports that as
+// `SessionStart:startup`, and the reflex whose entire purpose is "trust the files, not your
+// memory" did not fire in the one case where there IS no memory to distrust.
+//
+// The SDD harness benchmark measured the cost. Its F4 handoff design is exactly this scenario — a
+// fresh `claude -p` in a workspace where a prior session was cut mid-build — and across three
+// Sonnet rows every one recorded `hooks_fired: ["SessionStart:startup"]` (the plugin's load echo,
+// not this hook). With no pointer to the run in flight, the orchestrator re-entered at phase 1:
+// 82–120 turns before its first write, $4.57–$10.36 for the session, and **0/3 of the gap closed**
+// while the run receipt and board sat on disk the whole time. One row reached GATE L4 — ship
+// sign-off — having advanced the deliverable by zero criteria.
+//
+// Firing on `startup` is free when there is nothing to say: `findRun` returns a run only for an
+// `active-scope` pointer or a `harness-run.md` whose status is mid-run, so an ordinary session in a
+// repo with no run — or with a shipped one — gets silence and exit 0, exactly as before.
+//
+// `clear` is included for the same reason: it discards the conversation and keeps the workspace,
+// which is the same problem wearing a different name.
+//
+// Derivation is always FRESH (files beat any persisted copy); the run-snapshot.json written
+// by hooks/compact-snapshot.mjs is only the fallback if live derivation throws. Fail-open:
+// no active run, or any error → silent exit 0.
+//
+// Contract: SessionStart stdin JSON { cwd, source: "startup"|"resume"|"clear"|"compact" }.
+// Inject via { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext } }.
+
+import { readFileSync } from "node:fs";
+import { deriveSnapshot, snapshotPath } from "../skills/tech-lead/scripts/run-snapshot.mjs";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { runHook, readStdin } from "./lib/decision.mjs";
+import { activeScope } from "../skills/tech-lead/scripts/lib/paths.mjs";
+
+// The snapshot's own hint says "trust the files, not the conversation summary" — correct after a
+// compaction, and slightly wrong on a cold start, where there is no summary and no conversation
+// either. The two sources also fail in DIFFERENT directions, so they need different first sentences:
+//
+//   compact / resume — the risk is acting on a lossy summary of work you remember doing.
+//   startup / clear  — the risk is not knowing the run exists, and OPENING IT AGAIN. That is the
+//                      failure the benchmark measured: a fresh session re-entered at phase 1 and
+//                      spent 82–120 turns rebuilding a pipeline that was already on disk.
+//
+// Naming the right failure is the whole value of the injection. A generic pointer to the files is
+// what a competent agent finds anyway; "there is a run open, do not re-open it" is not.
+function lead(source) {
+  if (source === "startup" || source === "clear") {
+    return "A shapeup-sdlc run is ALREADY OPEN in this workspace and you have no memory of it. " +
+      "Do NOT open a new run, re-run intake, or restart the pipeline from phase 1 — the receipt, " +
+      "the board and the ledger already exist. RESUME from the phase the files say the run is in. ";
+  }
+  return "";
+}
+
+async function main() {
+  await runHook("session-rehydrate", async () => {
+    const raw = await readStdin();
+    let p;
+    try { p = JSON.parse(raw || "{}"); }
+    catch (e) { return { verdict: "error", event: "SessionStart", reason: `unparseable payload: ${e.message}` }; }
+    const cwd = p.cwd || process.cwd();
+
+    let snapshot = null;
+    let source = "live";
+    try {
+      snapshot = deriveSnapshot(cwd);
+    } catch {
+      // Live derivation failed → fall back to the pre-compaction anchor, best effort.
+      source = "anchor";
+      try {
+        const pointer = JSON.parse(readFileSync(activeScope(cwd), "utf8"));
+        if (pointer?.slug) snapshot = JSON.parse(readFileSync(snapshotPath(cwd, pointer.slug), "utf8"));
+      } catch { /* no anchor either → stay silent */ }
+    }
+    if (!snapshot?.rehydrate_hint) {
+      return { verdict: "allow", event: "SessionStart", cwd, subject: p.source ?? null, reason: "no active run — nothing to rehydrate" };
+    }
+
+    return {
+      verdict: "allow", event: "SessionStart", cwd, rule: `injected:${source}`,
+      subject: snapshot.slug ?? p.source ?? null,
+      reason: `rehydrate_hint injected on SessionStart:${p.source ?? "?"}`,
+      // additionalContext is not a deny, but it IS output, so it rides the same channel.
+      payload: {
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: `${lead(p.source)}${snapshot.rehydrate_hint}\n${JSON.stringify(snapshot)}`,
+        },
+      },
+      emit: true,
+    };
+  });
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}

package/hooks/slop-cleaner.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// Slop cleaner — advisory Stop hook (v1.2, absorb-audit P2).
+//
+// Scans what actually changed this session (git diff of the working tree; fallback: the
+// newest WorkResult's files_touched) for the classic leftovers — TODO/FIXME markers,
+// console.log/debugger, blocks of commented-out code, one file swallowing hundreds of added
+// lines — and mentions them to the user on stop.
+//
+// ADVISORY ONLY, same contract as anti-rationalization.mjs: exit 0 always, at most
+// { systemMessage }, never { decision:"block" }, never exit 2 ("QA is a level-up, not a
+// gate"). Harness-scoped: silent unless a run is active.
+//
+// Contract: Stop stdin JSON { cwd, stop_hook_active }.
+
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { activeSlug } from "./anti-rationalization.mjs";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { LOCAL, SHARED, resultsDir } from "../skills/tech-lead/scripts/lib/paths.mjs";
+
+import { runHook, readStdin, settle } from "./lib/decision.mjs";
+
+// Harness bookkeeping is never "slop" — skip both storage roots, whichever names they carry.
+const SKIP_PATH = new RegExp(`^(${[LOCAL, SHARED].map((r) => r.replace(/[.\\]/g, "\\$&")).join("|")})/`);
+const MAX_FILES = 30;
+const MAX_ADDED_LINES_PER_FILE = 400;
+
+const MARKERS = [
+  { name: "TODO/FIXME", re: /\b(TODO|FIXME|XXX|HACK)\b/ },
+  { name: "console.log", re: /\bconsole\.(log|debug)\s*\(/ },
+  { name: "debugger", re: /^\s*debugger\b/ },
+];
+
+/** Scan a unified diff for slop in ADDED lines only.
+ *  Returns [{ file, markers: {name: count}, added, big, commented_code }]. */
+export function scanDiff(diffText) {
+  const findings = [];
+  let current = null;
+  let commentRun = 0;
+  let filesSeen = 0;
+
+  const push = () => {
+    if (!current) return;
+    const dirty = current.added > MAX_ADDED_LINES_PER_FILE ||
+      current.commented_code ||
+      Object.keys(current.markers).length > 0;
+    current.big = current.added > MAX_ADDED_LINES_PER_FILE;
+    if (dirty) findings.push(current);
+  };
+
+  for (const line of (diffText || "").split("\n")) {
+    if (line.startsWith("+++ ")) {
+      push();
+      commentRun = 0;
+      const file = line.replace(/^\+\+\+ (b\/)?/, "").trim();
+      if (file === "/dev/null" || SKIP_PATH.test(file) || ++filesSeen > MAX_FILES) {
+        current = null;
+        continue;
+      }
+      current = { file, markers: {}, added: 0, big: false, commented_code: false };
+      continue;
+    }
+    if (!current || !line.startsWith("+") || line.startsWith("+++")) { commentRun = 0; continue; }
+    const added = line.slice(1);
+    current.added++;
+    for (const { name, re } of MARKERS) {
+      if (re.test(added)) current.markers[name] = (current.markers[name] || 0) + 1;
+    }
+    // ≥4 consecutive added comment lines that look like code = a commented-out block
+    if (/^\s*(\/\/|#)/.test(added) && /[;{}()=]/.test(added)) {
+      if (++commentRun >= 4) current.commented_code = true;
+    } else {
+      commentRun = 0;
+    }
+  }
+  push();
+  return findings;
+}
+
+/** One human-readable fragment per finding. */
+export function summarize(findings) {
+  return findings.slice(0, 6).map((f) => {
+    const bits = Object.entries(f.markers).map(([name, n]) => `${name} ×${n}`);
+    if (f.commented_code) bits.push("commented-out code block");
+    if (f.big) bits.push(`+${f.added} lines in one file`);
+    return `${f.file}: ${bits.join(", ")}`;
+  });
+}
+
+function git(cwd, args) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : null;
+}
+
+/** The session's change set as a unified diff — git first, WorkResult fallback. */
+function collectDiff(cwd, slug) {
+  const tracked = git(cwd, ["diff", "HEAD"]);
+  if (tracked !== null) {
+    // Untracked files never show in `diff HEAD`; synthesize +lines for small text ones.
+    let extra = "";
+    const status = git(cwd, ["status", "--porcelain"]) || "";
+    for (const line of status.split("\n")) {
+      const m = /^\?\?\s+(.+)$/.exec(line);
+      if (!m || SKIP_PATH.test(m[1])) continue;
+      const p = join(cwd, m[1]);
+      try {
+        if (statSync(p).size > 200 * 1024) continue;
+        const body = readFileSync(p, "utf8");
+        if (body.includes("\u0000")) continue; // binary
+        extra += `+++ b/${m[1]}\n` + body.split("\n").map((l) => `+${l}`).join("\n") + "\n";
+      } catch { /* unreadable → skip */ }
+    }
+    return tracked + extra;
+  }
+  // Not a git repo → fall back to the newest WorkResult's files_touched.
+  const resultsPath = resultsDir(cwd, slug);
+  if (!existsSync(resultsPath)) return null;
+  const newest = readdirSync(resultsPath).filter((f) => f.endsWith(".json"))
+    .map((f) => join(resultsPath, f))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+  if (!newest) return null;
+  let diff = "";
+  try {
+    const result = JSON.parse(readFileSync(newest, "utf8"));
+    for (const t of (result.files_touched || []).slice(0, MAX_FILES)) {
+      const rel = t?.path;
+      if (!rel || SKIP_PATH.test(rel)) continue;
+      const p = join(cwd, rel);
+      try {
+        if (statSync(p).size > 200 * 1024) continue;
+        const body = readFileSync(p, "utf8");
+        if (body.includes("\u0000")) continue;
+        diff += `+++ b/${rel}\n` + body.split("\n").map((l) => `+${l}`).join("\n") + "\n";
+      } catch { /* unreadable → skip */ }
+    }
+  } catch { return null; }
+  return diff || null;
+}
+
+async function main() {
+  await runHook("slop-cleaner", async () => {
+  const raw = await readStdin();
+  let p;
+  /** Stay silent — with the reason on the record (hooks/lib/decision.mjs). */
+  const defer = (reason, rule) => settle({ verdict: "allow", event: "Stop", cwd: p?.cwd, reason, rule });
+  try { p = JSON.parse(raw || "{}"); }
+  catch (e) { settle({ verdict: "error", event: "Stop", reason: `unparseable payload: ${e.message}` }); }
+
+  if (p.stop_hook_active) defer("stop_hook_active — never participate in a stop-hook loop", "loop-guard");
+
+  const cwd = p.cwd || process.cwd();
+  const slug = activeSlug(cwd);
+  if (!slug) defer("no active run — stay silent", "no-run");
+
+  const diff = collectDiff(cwd, slug);
+  if (!diff) defer("no diff to scan", "no-diff");
+
+  const findings = scanDiff(diff);
+  if (findings.length === 0) defer("diff scanned, no leftovers found — inspected and permitted", "diff-clean");
+
+  return {
+    verdict: "allow", event: "Stop", cwd, subject: slug, rule: "slop-found", emit: true,
+    reason: `${findings.length} leftover(s) in the recent diff — advisory note emitted, not a block`,
+    payload: {
+      systemMessage:
+        `slop-cleaner (advisory): recent edits carry leftovers — ${summarize(findings).join("; ")}. ` +
+        `Not blocking — consider a cleanup pass.`,
+    },
+  };
+  });
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}

package/oracles/_shared.mjs

@@ -0,0 +1,46 @@
+// Shared helpers for evaluation-contract oracle runners (Stage G of the audit).
+//
+// The `process` oracle (step 1–3) inlined these; the test/snapshot/http oracles (steps 4–5)
+// import them so the matching grammar is identical across the registry. Keeping one definition
+// of `exit`/regex matching means a contract author learns the grammar once.
+
+// Stack-trace / panic signature shared by every oracle's crash check.
+export const CRASH_RE = /at\s+.*:\d+:\d+|Traceback|panic:|unhandled|Segmentation fault/i;
+
+// Interpret an `exit`/`status` spec against an observed number.
+//   undefined | "*"            → any (no constraint)
+//   number                     → strict equality
+//   "==N" "!=N" ">N" "<N" ">=N" "<=N"
+export function matchNum(spec, n) {
+  if (spec === undefined || spec === "*") return true;
+  if (typeof spec === "number") return n === spec;
+  const m = String(spec).match(/^(==|!=|>=|<=|>|<)\s*(-?\d+)$/);
+  if (!m) return false;
+  const want = Number(m[2]);
+  switch (m[1]) {
+    case "==": return n === want;
+    case "!=": return n !== want;
+    case ">":  return n > want;
+    case "<":  return n < want;
+    case ">=": return n >= want;
+    case "<=": return n <= want;
+    default:   return false;
+  }
+}
+
+// "/pattern/flags" → RegExp; a bare string → literal-ish RegExp.
+export function toRegExp(spec) {
+  const m = String(spec).match(/^\/(.*)\/([a-z]*)$/);
+  return m ? new RegExp(m[1], m[2]) : new RegExp(spec);
+}
+
+// Uniform report formatter so every oracle prints the same PASS/FAIL shape.
+export function formatReport(label, { fails, results }) {
+  const lines = [`\nEvaluation report — ${label}\n${"=".repeat(60)}`];
+  for (const r of results) {
+    lines.push(`${r.pass ? "PASS" : "FAIL"}  ${r.id}  ${r.desc || ""}\n        ⇒ ${r.evidence}`);
+  }
+  lines.push("=".repeat(60));
+  lines.push(fails === 0 ? `✅ all ${results.length} criteria PASS` : `❌ ${fails}/${results.length} criteria FAIL`);
+  return lines.join("\n");
+}

package/oracles/http-oracle.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// `http` oracle for the evaluation contract (Stage G, step 5 of the audit).
+//
+// Deliverable: a service / API. The oracle starts the server, waits until it is reachable,
+// sends each criterion's request, and grades the OBSERVED response (status + body) — never the
+// source. It then tears the server down. This reuses the `process` sandbox idea (controlled
+// spawn) but observes over HTTP instead of stdout.
+//
+// Invariants (carried from the evaluator's design):
+//   • Probe behavior, not code presence — the verdict cites response status + body.
+//   • Absence of evidence = FAIL — if the server never becomes reachable, EVERY criterion FAILs
+//     (a service you cannot reach does not pass), and a request that errors out FAILs.
+//   • One verdict per criterion.
+//
+// Contract shape:
+//   { "oracle": "http",
+//     "server": { "cmd": "node ./server.mjs", "ready_path": "/health", "ready_timeout_ms": 4000 },
+//     "criteria": [
+//       { "id": "H1", "desc": "health is ok",
+//         "probe": { "method": "GET", "path": "/health" },
+//         "expect": { "status": 200, "body": "/ok/i" } },
+//       { "id": "H2", "desc": "echo returns the message as json",
+//         "probe": { "method": "POST", "path": "/echo", "json": { "msg": "hi" } },
+//         "expect": { "status": 200, "json": { "msg": "hi" } } } ] }
+//
+// The server is spawned with env.PORT set to a free port the runner picks, so fixtures must read
+// `process.env.PORT`. `status` uses the shared numeric grammar (200 | "!=500" | ">=200" ...).
+//
+// Library use:  const { fails, results } = await runContract({ server, criteria })
+// CLI use:      node http-oracle.mjs <contract.json> ["override server command"]
+//               exit 0 = all PASS, 1 = ≥1 FAIL, 2 = usage/contract error.
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { readFileSync } from "node:fs";
+import { matchNum, toRegExp, formatReport } from "./_shared.mjs";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.unref();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+async function reachable(base, path, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const ctrl = AbortSignal.timeout(500);
+      await fetch(base + path, { signal: ctrl });
+      return true; // any HTTP response (even 404) means the port is serving
+    } catch {
+      await sleep(100);
+    }
+  }
+  return false;
+}
+
+async function probe(base, p) {
+  const init = { method: p.method || "GET", headers: { ...(p.headers || {}) } };
+  if (p.json !== undefined) { init.body = JSON.stringify(p.json); init.headers["content-type"] = "application/json"; }
+  else if (p.body !== undefined) { init.body = p.body; }
+  const res = await fetch(base + (p.path || "/"), { ...init, signal: AbortSignal.timeout(p.timeout_ms || 5000) });
+  const text = await res.text();
+  return { status: res.status, text };
+}
+
+function jsonSubsetMatches(want, gotText) {
+  let got;
+  try { got = JSON.parse(gotText); } catch { return false; }
+  for (const [k, v] of Object.entries(want)) {
+    if (JSON.stringify(got?.[k]) !== JSON.stringify(v)) return false;
+  }
+  return true;
+}
+
+function grade(expect, r) {
+  const reasons = [];
+  let pass = true;
+  if (!matchNum(expect.status ?? "*", r.status)) { pass = false; reasons.push(`status ${r.status} ≠ expected ${expect.status}`); }
+  if (expect.body !== undefined && !toRegExp(expect.body).test(r.text)) { pass = false; reasons.push(`body does not match ${expect.body}`); }
+  if (expect.json !== undefined && !jsonSubsetMatches(expect.json, r.text)) { pass = false; reasons.push(`json does not contain ${JSON.stringify(expect.json)}`); }
+  const evidence = `status ${r.status}, body=${JSON.stringify(r.text.trim().slice(0, 120))}` + (reasons.length ? `  [${reasons.join("; ")}]` : "");
+  return { pass, evidence };
+}
+
+export async function runContract({ server, criteria }) {
+  const results = [];
+  let fails = 0;
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  const [bin, ...args] = String(server.cmd).split(/\s+/).filter(Boolean);
+  const child = spawn(bin, args, {
+    env: { ...process.env, PORT: String(port) },
+    cwd: server.cwd,
+    stdio: ["ignore", "ignore", "ignore"],
+  });
+
+  try {
+    const up = await reachable(base, server.ready_path || "/", server.ready_timeout_ms || 4000);
+    if (!up) {
+      // Absence of evidence = FAIL for every criterion: an unreachable service does not pass.
+      for (const c of criteria) {
+        results.push({ id: c.id, desc: c.desc, pass: false, evidence: `server never became reachable at ${base}${server.ready_path || "/"} within ${server.ready_timeout_ms || 4000}ms` });
+        fails++;
+      }
+      return { fails, results };
+    }
+    for (const c of criteria) {
+      let g;
+      try { g = grade(c.expect || {}, await probe(base, c.probe || {})); }
+      catch (e) { g = { pass: false, evidence: `request failed: ${e.message}` }; }
+      if (!g.pass) fails++;
+      results.push({ id: c.id, desc: c.desc, ...g });
+    }
+    return { fails, results };
+  } finally {
+    child.kill("SIGTERM");
+    // give it a beat, then hard-kill if still alive
+    await sleep(100);
+    if (!child.killed) { try { child.kill("SIGKILL"); } catch { /* already gone */ } }
+  }
+}
+
+export { formatReport };
+
+// --- CLI entry ---------------------------------------------------------------
+if (isMain(import.meta.url)) {
+  const contractPath = process.argv[2];
+  const overrideCmd = process.argv[3];
+  if (!contractPath) {
+    console.error('usage: node http-oracle.mjs <contract.json> ["override server command"]');
+    process.exit(2);
+  }
+  let contract;
+  try { contract = JSON.parse(readFileSync(contractPath, "utf8")); }
+  catch (e) { console.error(`cannot read contract ${contractPath}: ${e.message}`); process.exit(2); }
+  if (!Array.isArray(contract.criteria) || contract.criteria.length === 0) {
+    console.error(`contract ${contractPath} has no criteria[]`); process.exit(2);
+  }
+  const server = { ...(contract.server || {}) };
+  if (overrideCmd) server.cmd = overrideCmd;
+  if (!server.cmd) { console.error(`contract ${contractPath} has no server.cmd`); process.exit(2); }
+  const summary = await runContract({ server, criteria: contract.criteria });
+  console.log(formatReport(`http oracle: ${contractPath}`, summary));
+  process.exit(summary.fails === 0 ? 0 : 1);
+}

package/oracles/index.mjs

@@ -0,0 +1,36 @@
+// Oracle registry for the evaluation contract (Stage G of the audit).
+//
+// The single entry point `spec-evaluator` dispatches through when a criterion / Test-Surface row
+// carries an `oracle:` tag. Adding a new oracle type = registering one runner here (the spec's
+// "new oracle types are added by registering a probe runner"). The contract interface is fixed —
+// `{ fails, results }` where each result is `{ id, desc, pass, evidence }` — implementations grow.
+//
+//   import { runOracle, ORACLES } from ".../oracles/index.mjs";
+//   const { fails, results } = await runOracle("process", { cmd, criteria });
+//
+// `runOracle` is async so a sync runner (process/test/snapshot) and an async one (http) share one
+// call shape; awaiting a non-promise is a no-op.
+
+import { runContract as runProcess } from "./process-oracle.mjs";
+import { runContract as runTest } from "./test-oracle.mjs";
+import { runContract as runSnapshot } from "./snapshot-oracle.mjs";
+import { runContract as runHttp } from "./http-oracle.mjs";
+
+// The registry is the source of truth for "which oracles exist". Docs (probing.md,
+// test-surface.md, evaluation-contract-spec.md) and structural test #8 are checked against it.
+export const ORACLES = {
+  process: runProcess,   // CLI / script   — spawn, grade exit + stdout
+  test: runTest,         // library/module — run the suite, grade exit + failing names
+  snapshot: runSnapshot, // generator/refactor — diff stdout vs golden
+  http: runHttp,         // service / API  — start server, request, grade status + body
+  // ui: handled in-skill by the Playwright CLI loop (not a Node runner) — see probing.md.
+};
+
+export async function runOracle(oracle, args) {
+  const fn = ORACLES[oracle];
+  if (!fn) throw new Error(`unknown oracle "${oracle}" (known: ${Object.keys(ORACLES).join(", ")}, plus "ui" in-skill)`);
+  return await fn(args);
+}
+
+// The full set the evaluator understands, including the in-skill `ui` path.
+export const ORACLE_NAMES = [...Object.keys(ORACLES), "ui"];

package/oracles/process-oracle.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// Shared `process` oracle for the evaluation contract (Stage G of the audit).
+//
+// This is the promoted, parameterized form of the todo-cli prototype: instead of hard-coding
+// criteria, it reads a *declarative contract* (a list of criteria, each with a `probe` and an
+// `expect`) and grades the OBSERVED exit code + stdout/stderr of a spawned process — never the
+// source. It is the runner `spec-evaluator` calls for any criterion tagged `oracle: process`
+// (CLI / script deliverables, where there is no browser to drive).
+//
+// Invariants carried over from the evaluator's design:
+//   • Probe behavior, not code presence — every verdict cites runtime output.
+//   • Absence of evidence = FAIL — a probe that throws or cannot run FAILs, never silently passes.
+//   • One verdict per criterion.
+//
+// Library use (what the evaluator calls):
+//   import { runContract } from ".../oracles/process-oracle.mjs";
+//   const { fails, results } = runContract({ cmd: "node ./todo.js", criteria });
+//
+// CLI use (smoke / CI):
+//   node process-oracle.mjs <contract.json> "<command to run the deliverable>"
+//   e.g. node process-oracle.mjs todo.contract.json "node ./todo.js"
+//   Exit 0 = all criteria PASS, 1 = at least one FAIL, 2 = usage/contract error.
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+
+const CRASH_RE = /at\s+.*:\d+:\d+|Traceback|panic:|unhandled|Segmentation fault/i;
+
+// Spawn the deliverable with controlled argv and a controlled store file.
+// `store` semantics: a string seeds $TODO_STORE with that content; null = no store file
+// (exercises first-run/missing-store behavior). The probe never touches the real cwd.
+function spawnProbe(cmd, probe) {
+  const [bin, ...baseArgs] = cmd.split(/\s+/).filter(Boolean);
+  const argv = probe.argv || [];
+  const dir = mkdtempSync(join(tmpdir(), "process-oracle-"));
+  const store = join(dir, "store.json");
+  const env = { ...process.env };
+  if (probe.store !== undefined && probe.store !== null) {
+    writeFileSync(store, probe.store);
+    env.TODO_STORE = store;
+  } else {
+    env.TODO_STORE = store; // path that does not exist yet → exercises missing-store path
+  }
+  const res = spawnSync(bin, [...baseArgs, ...argv], {
+    encoding: "utf8",
+    env,
+    timeout: probe.timeout_ms || 10_000,
+    input: probe.stdin,
+  });
+  rmSync(dir, { recursive: true, force: true });
+  const out = (res.stdout || "") + (res.stderr || "");
+  return { code: res.status, out, crashed: CRASH_RE.test(out), spawnError: res.error?.message };
+}
+
+// Interpret one `expect` clause against an observed result. Returns true/false.
+//   exit:     number | "==0" | "!=0" | ">0" | "<N" | ">=N" | "*"   (default: any)
+//   stdout:   "/regex/flags"  — must match combined stdout+stderr
+//   stderr:   "/regex/flags"  — alias kept for readability; same combined stream
+//   no_crash: true            — require no stack-trace/panic signature in output
+function matchExit(spec, code) {
+  if (spec === undefined || spec === "*") return true;
+  if (typeof spec === "number") return code === spec;
+  const m = String(spec).match(/^(==|!=|>=|<=|>|<)\s*(-?\d+)$/);
+  if (!m) return false;
+  const n = Number(m[2]);
+  switch (m[1]) {
+    case "==": return code === n;
+    case "!=": return code !== n;
+    case ">":  return code > n;
+    case "<":  return code < n;
+    case ">=": return code >= n;
+    case "<=": return code <= n;
+    default:   return false;
+  }
+}
+function toRegExp(spec) {
+  const m = String(spec).match(/^\/(.*)\/([a-z]*)$/);
+  return m ? new RegExp(m[1], m[2]) : new RegExp(spec);
+}
+function grade(expect, r) {
+  const reasons = [];
+  let pass = true;
+  if (!matchExit(expect.exit, r.code)) { pass = false; reasons.push(`exit ${r.code} ≠ expected ${expect.exit}`); }
+  for (const key of ["stdout", "stderr"]) {
+    if (expect[key] !== undefined && !toRegExp(expect[key]).test(r.out)) {
+      pass = false; reasons.push(`output does not match ${key} ${expect[key]}`);
+    }
+  }
+  if (expect.no_crash && r.crashed) { pass = false; reasons.push("crashed (stack trace / panic in output)"); }
+  const evidence =
+    `exit ${r.code}, crashed=${r.crashed}` +
+    (r.spawnError ? `, spawnError=${r.spawnError}` : "") +
+    `, out=${JSON.stringify(r.out.trim().slice(0, 100))}` +
+    (reasons.length ? `  [${reasons.join("; ")}]` : "");
+  return { pass, evidence };
+}
+
+// Run every criterion in a contract against `cmd`. Pure of I/O except spawning the deliverable.
+export function runContract({ cmd, criteria }) {
+  const results = [];
+  let fails = 0;
+  for (const c of criteria) {
+    let g;
+    try {
+      const r = spawnProbe(cmd, c.probe || {});
+      g = grade(c.expect || {}, r);
+    } catch (e) {
+      g = { pass: false, evidence: `probe threw: ${e.message}` }; // absence of evidence = FAIL
+    }
+    if (!g.pass) fails++;
+    results.push({ id: c.id, desc: c.desc, ...g });
+  }
+  return { fails, results };
+}
+
+export function formatReport(cmd, { fails, results }) {
+  const lines = [`\nEvaluation report — process oracle for: ${cmd}\n${"=".repeat(60)}`];
+  for (const r of results) {
+    lines.push(`${r.pass ? "PASS" : "FAIL"}  ${r.id}  ${r.desc}\n        ⇒ ${r.evidence}`);
+  }
+  lines.push("=".repeat(60));
+  lines.push(fails === 0 ? `✅ all ${results.length} criteria PASS` : `❌ ${fails}/${results.length} criteria FAIL`);
+  return lines.join("\n");
+}
+
+// --- CLI entry (only when run directly, not when imported) -------------------
+if (isMain(import.meta.url)) {
+  const contractPath = process.argv[2];
+  const cmd = process.argv[3];
+  if (!contractPath || !cmd) {
+    console.error('usage: node process-oracle.mjs <contract.json> "<command to run the deliverable>"');
+    process.exit(2);
+  }
+  let contract;
+  try { contract = JSON.parse(readFileSync(contractPath, "utf8")); }
+  catch (e) { console.error(`cannot read contract ${contractPath}: ${e.message}`); process.exit(2); }
+  if (!Array.isArray(contract.criteria) || contract.criteria.length === 0) {
+    console.error(`contract ${contractPath} has no criteria[]`); process.exit(2);
+  }
+  const summary = runContract({ cmd, criteria: contract.criteria });
+  console.log(formatReport(cmd, summary));
+  process.exit(summary.fails === 0 ? 0 : 1);
+}