@selesai/code 0.9.11 → 0.9.13

package/dist/skills/unlazy/scripts/lib/process-tree.mjs

@@ -0,0 +1,161 @@
+// Best-effort process-tree cleanup shared by the gate runner and tests.
+// Zero dependencies. Node 16+.
+
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { win32 } from "node:path";
+
+export const WINDOWS_TASKKILL_TIMEOUT_MS = 1000;
+
+export function windowsTaskkillPath(env = process.env) {
+  const normalizeRoot = (value) => String(value || "").replace(/\//g, "\\").replace(/\\+$/, "");
+  const systemRoot = normalizeRoot(env.SystemRoot);
+  const windir = normalizeRoot(env.WINDIR);
+  const systemDrive = String(env.SystemDrive || "").replace(/[\\/]+$/, "").toUpperCase();
+  const driveRoot = /^[A-Za-z]:\\Windows$/i;
+  // Require the three standard Windows launcher values to identify the same
+  // drive-root directory. A single arbitrary absolute variable must not select
+  // an executable, and disagreement fails closed to the ChildProcess handle.
+  if (driveRoot.test(systemRoot) && driveRoot.test(windir) &&
+      systemRoot.toLowerCase() === windir.toLowerCase() &&
+      systemDrive === systemRoot.slice(0, 2).toUpperCase()) {
+    return win32.join(systemRoot, "System32", "taskkill.exe");
+  }
+  // A bare executable name consults cwd/PATH, which are controlled by the
+  // CHECK environment. If neither trusted system root exists, skip the helper
+  // and use the already-held ChildProcess handle instead.
+  return null;
+}
+
+function syncFailure(result) {
+  if (!result) return "returned no result";
+  if (result.error) return result.error.code || result.error.message || "spawn error";
+  if (result.signal) return "signal " + result.signal;
+  if (result.status !== 0) return "exit " + String(result.status);
+  return null;
+}
+
+const childExited = (child) => child.exitCode !== null && child.exitCode !== undefined ||
+  child.signalCode !== null && child.signalCode !== undefined;
+
+export function terminateProcessTree(child, options = {}) {
+  const platform = options.platform || process.platform;
+  const spawnSyncImpl = options.spawnSyncImpl || nodeSpawnSync;
+  const killGroup = options.killGroup || process.kill;
+  const pid = child && child.pid;
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return { ok: false, fallback: false, diagnostic: "child PID is unavailable" };
+  }
+
+  if (platform !== "win32") {
+    // The gate runner launches a detached Node supervisor as the group leader
+    // and keeps it alive until the shell and inherited stdout/stderr close. If
+    // Node has already observed that supervisor exit, the numeric PGID no
+    // longer carries identity and may have been reused; never signal it.
+    if (childExited(child)) {
+      return { ok: true, fallback: false, diagnostic: "process supervisor already exited" };
+    }
+    try {
+      killGroup(-pid, "SIGKILL");
+      return { ok: true, fallback: false, diagnostic: null };
+    } catch (error) {
+      if (childExited(child)) {
+        return {
+          ok: true,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) + "); supervisor already exited",
+        };
+      }
+      try {
+        const requested = child.kill("SIGKILL");
+        if (requested === false) {
+          return {
+            ok: false,
+            fallback: true,
+            diagnostic: "process-group kill failed (" + (error.code || error.message) +
+              "); child fallback returned false",
+          };
+        }
+        return {
+          ok: true,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) + "); child fallback requested",
+        };
+      } catch (fallbackError) {
+        return {
+          ok: false,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) +
+            "); child fallback failed (" + (fallbackError.code || fallbackError.message) + ")",
+        };
+      }
+    }
+  }
+
+  // taskkill addresses the stored leader PID, unlike a POSIX process-group
+  // request. Do not target it after Node reports exit because the PID may have
+  // been reused while an inherited pipe remains open.
+  if (childExited(child)) {
+    return { ok: true, fallback: false, diagnostic: "child already exited" };
+  }
+
+  const command = windowsTaskkillPath(options.env || process.env);
+  const requestedTimeout = Number(options.taskkillTimeoutMs);
+  const taskkillTimeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0
+    ? Math.floor(requestedTimeout)
+    : WINDOWS_TASKKILL_TIMEOUT_MS;
+  let result;
+  let failure;
+  if (!command) {
+    failure = "trusted system taskkill path unavailable";
+  } else {
+    try {
+      result = spawnSyncImpl(command, ["/pid", String(pid), "/f", "/t"], {
+        stdio: "ignore",
+        windowsHide: true,
+        // Cleanup runs inside the gate timeout path. A broken helper must not
+        // replace a bounded CHECK with an unbounded synchronous wait.
+        timeout: taskkillTimeoutMs,
+        killSignal: "SIGKILL",
+      });
+      failure = syncFailure(result);
+    } catch (error) {
+      failure = error.code || error.message || "spawn threw";
+    }
+  }
+  if (!failure) return { ok: true, fallback: false, diagnostic: null, command };
+
+  if (childExited(child)) {
+    return {
+      ok: true,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child already exited",
+    };
+  }
+
+  try {
+    const requested = child.kill("SIGKILL");
+    if (requested === false) {
+      return {
+        ok: false,
+        fallback: true,
+        command,
+        diagnostic: "taskkill failed (" + failure + "); child fallback returned false",
+      };
+    }
+    return {
+      ok: true,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child fallback requested",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child fallback failed (" +
+        (error.code || error.message) + ")",
+    };
+  }
+}

package/dist/skills/unlazy/scripts/lib/regex-worker.mjs

@@ -0,0 +1,9 @@
+import { parentPort } from "node:worker_threads";
+
+parentPort.once("message", ({ source, flags, output }) => {
+  try {
+    parentPort.postMessage({ matched: new RegExp(source, flags).test(output) });
+  } catch (error) {
+    parentPort.postMessage({ error: error.message });
+  }
+});

package/dist/skills/unlazy/scripts/stop-hook.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// Claude Code Stop hook for one unlazy pipeline. Zero dependencies. Node 16+.
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  UNLAZY_DIR, gateState, hookStatePath, parseGates, qualify, resolveTarget,
+  sha256, validateScopeId, withFileLock, writeAtomic,
+} from "./lib/gates.mjs";
+import { dispatchStatus } from "./lib/dispatch.mjs";
+
+const MAX_BLOCKS = 6;
+const safeHostText = (value, max = 500) => String(value)
+  .replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, " ")
+  .replace(/\s+/g, " ")
+  .trim()
+  .slice(0, max);
+
+function normalizeHookState(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.schema !== 1 ||
+      !value.sessions || typeof value.sessions !== "object" || Array.isArray(value.sessions)) {
+    return { schema: 1, sessions: {} };
+  }
+  const sessions = {};
+  for (const [key, current] of Object.entries(value.sessions)) {
+    if (!/^[a-f0-9]{24}$/.test(key) || !current || typeof current !== "object" || Array.isArray(current) ||
+        !/^[a-f0-9]{24}$/.test(String(current.hash || "")) ||
+        !Number.isInteger(current.blocks) || current.blocks < 0 ||
+        typeof current.updatedAt !== "string" || Number.isNaN(Date.parse(current.updatedAt))) continue;
+    sessions[key] = current;
+  }
+  return { schema: 1, sessions };
+}
+
+const args = process.argv.slice(2);
+const scopeIndex = args.indexOf("--scope");
+const scopeArg = scopeIndex === -1 ? null : args[scopeIndex + 1];
+
+const allow = (message) => {
+  if (message) console.log(JSON.stringify({ systemMessage: message }));
+  process.exit(0);
+};
+
+if (scopeIndex !== -1 && (!scopeArg || validateScopeId(scopeArg))) {
+  allow("unlazy: installed hook has an invalid --scope value; not blocking.");
+}
+
+let payload = {};
+try { payload = JSON.parse(readFileSync(0, "utf8") || "{}"); }
+catch { allow(null); }
+
+const root = resolve(typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd());
+const sessionId = payload.session_id || payload.sessionId || "anonymous";
+const sessionKey = sha256(String(sessionId)).slice(0, 24);
+const target = resolveTarget({ root, scope: scopeArg, sessionId });
+
+if (target.ambiguous) {
+  allow("unlazy: " + target.ambiguous.length + " pipelines under " + UNLAZY_DIR +
+    "/ (" + target.ambiguous.join(", ") + ") and none bound to this session; not blocking.");
+}
+if (target.error && !target.ambiguous) allow("unlazy: " + safeHostText(target.error) + "; not blocking.");
+
+const statePath = hookStatePath(root, target.scope);
+
+async function clearSessionState() {
+  if (!existsSync(statePath)) return;
+  try {
+    await withFileLock(root, statePath, () => {
+      let state = { schema: 1, sessions: {} };
+      try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* replace invalid local state */ }
+      state = normalizeHookState(state);
+      delete state.sessions[sessionKey];
+      if (!Object.keys(state.sessions).length) {
+        try { unlinkSync(statePath); } catch { /* already absent */ }
+      } else writeAtomic(statePath, JSON.stringify(state, null, 2) + "\n", { root });
+    }, { timeoutMs: 10000 });
+  } catch {
+    // State cleanup must never trap a session after the gates are complete.
+  }
+}
+
+const dispatch = dispatchStatus(root, target.scope);
+
+if (!target.files.length && !dispatch.blocking.length && !dispatch.abandoned.length) {
+  await clearSessionState();
+  allow(null);
+}
+
+const unmet = [...dispatch.blocking];
+const invalid = [];
+const handoffs = [...dispatch.abandoned];
+const handoffMessage = () => {
+  if (!handoffs.length) return "";
+  const shown = handoffs.slice(0, 5).join(", ") +
+    (handoffs.length > 5 ? ", +" + (handoffs.length - 5) + " more" : "");
+  return " HANDOFF REQUIRED: " + handoffs.length + " abandoned item(s): " + safeHostText(shown) + ".";
+};
+// The loop guard compares resolved gate state between stops, not raw bytes.
+// Byte comparison counted any edit as progress: a comment, a reflowed line, or
+// the checker rewriting an evidence line with a fresh PATH hash. That rearmed
+// the guard indefinitely, so the six-block release could only ever fire for an
+// agent doing literally nothing, which is the one case least in need of it.
+// Dispatch issue strings encode only canonical state and counts, not raw JSON
+// bytes or timestamps, so metadata-only edits do not reset the same guard.
+const resolved = [...dispatch.resolved];
+for (const file of [...target.files].sort()) {
+  let text;
+  try { text = readFileSync(file, "utf8"); }
+  catch (error) {
+    invalid.push(qualify(file, "PARSE") + " unreadable: " + safeHostText(error.message));
+    resolved.push(qualify(file, "PARSE") + "=unreadable");
+    continue;
+  }
+  const doc = parseGates(text);
+  if (doc.errors.length) {
+    invalid.push(qualify(file, "PARSE") + " " + doc.errors.slice(0, 2).map((error) => safeHostText(error)).join("; "));
+    // Record only that the ledger is invalid. Diagnostic text carries line
+    // numbers, which shift on an unrelated edit and would restore byte coupling.
+    resolved.push(qualify(file, "PARSE") + "=invalid");
+    continue;
+  }
+  for (const gate of doc.gates) {
+    const state = gateState(gate, doc.abandoned);
+    resolved.push(qualify(file, gate.id) + "=" + state);
+    if (state === "unmet" || state === "unmet-no-evidence") unmet.push(qualify(file, gate.id));
+    else if (state === "abandoned") handoffs.push(qualify(file, gate.id));
+  }
+}
+
+if (!unmet.length && !invalid.length) {
+  await clearSessionState();
+  if (!handoffs.length) allow(null);
+  const where = target.scope ? " [scope " + target.scope + "]" : "";
+  allow("unlazy" + where + ":" + handoffMessage());
+}
+
+const progressHash = sha256(resolved.sort().join("\0")).slice(0, 24);
+let sessionState;
+try {
+  sessionState = await withFileLock(root, statePath, () => {
+    let state = { schema: 1, sessions: {} };
+    try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* new or corrupt local state */ }
+    state = normalizeHookState(state);
+    let current = state.sessions[sessionKey];
+    if (!current || current.hash !== progressHash) current = { hash: progressHash, blocks: 0 };
+    current.blocks += 1;
+    current.updatedAt = new Date().toISOString();
+    state.sessions[sessionKey] = current;
+    // Bound abandoned session debris without mixing counters between sessions.
+    const entries = Object.entries(state.sessions).sort((a, b) => String(b[1].updatedAt).localeCompare(String(a[1].updatedAt)));
+    state.sessions = Object.fromEntries(entries.slice(0, 64));
+    writeAtomic(statePath, JSON.stringify(state, null, 2) + "\n", { root });
+    return current;
+  }, { timeoutMs: 10000 });
+} catch (error) {
+  allow("unlazy: could not update the serialized hook state (" + safeHostText(error.message) + "); not blocking to avoid a trap.");
+}
+
+const where = target.scope ? " [scope " + target.scope + "]" : "";
+const outstanding = [...invalid, ...unmet].map((item) => safeHostText(item));
+if (sessionState.blocks > MAX_BLOCKS) {
+  allow("unlazy: releasing after " + MAX_BLOCKS + " blocks without gate progress" + where +
+    "; " + outstanding.length + " item(s) remain (" + outstanding.slice(0, 4).join(", ") + ")." +
+    handoffMessage());
+}
+
+const list = outstanding.slice(0, 5).join(", ") + (outstanding.length > 5 ? ", +" + (outstanding.length - 5) + " more" : "");
+console.log(JSON.stringify({
+  decision: "block",
+  reason: "unlazy" + where + ": " + outstanding.length + " gate/ledger/dispatch item(s) need work: " + list +
+    ". Run gate-check.mjs --status to inspect without execution. To run inherited CHECK lines, inspect them and use --approve. " +
+    "Use ABANDON: <id> <non-blank reason> only when a gate is genuinely impossible." + handoffMessage(),
+}));
+process.exit(0);

package/dist/skills/unlazy/templates/PLAN.md

@@ -0,0 +1,65 @@
+# Plan: <task>
+
+Scope: <validated pipeline id; store this file at .unlazy/<scope>/PLAN.md>
+Depth: tree <N>
+Mode: orchestrated
+
+## Contract
+
+Decide before fan-out:
+
+- Interfaces: <signatures, schemas, formats, integration points>
+- Ownership: <one complete set of repository-relative paths per leaf; no absolute paths, traversal, or concurrent overlap>
+- Dependencies: <leaf ids that must be VERIFIED first>
+- Host launch mode: <Codex native subagents | Claude background Agents | Claude Dynamic Workflow | sequential fallback>
+- Wave policy: <which independent READY leaves launch together and the maximum host concurrency>
+- Toolchain: <runtime versions, shell, working-directory rules, test commands>
+- Conventions: <naming, errors, compatibility, formatting>
+- Manual review: <owner and evidence standard for consequential manual gates>
+
+## Current contract inventory
+
+Contract revision: 1. Before fan-out, reread the original request and current amendments. Record every independently omittable required outcome and every constraint that changes acceptance; do not copy credentials, private text, or unrelated context.
+
+| ID | Required outcome or constraint | Owner | Observing gate or manual review | Disposition | Revision |
+|---|---|---|---|---|---|
+| C1 | <concise paraphrase> | <leaf/node> | <qualified gate/reviewer> | ACTIVE | 1 |
+
+Use stable ids. On an amendment, increment the revision and reconcile every affected row before dispatch or completion credit. `ACTIVE` is complete only with a current owner and observation. `ABANDONED`, `DEFERRED`, and `OWNER_DECISION` are honest non-completion; only explicit user authority may use `REMOVED_BY_USER`.
+
+## State vocabulary
+
+Leaf state is exactly one of:
+
+- WAITING: at least one id in Needs is not VERIFIED
+- READY: dependencies are VERIFIED and ownership can be claimed
+- IN-FLIGHT: dispatched, not yet parent-verified
+- VERIFIED: parent --reverify passed and manual gates were reviewed
+- ABANDONED: a required gate has a visible handoff
+
+Branch state is exactly one of OPEN, VERIFIED, or ABANDONED.
+
+## Tree
+
+Use `leaf-` paths for work leaves and `node-` paths for branch integration.
+
+- 1 <task> .............. GATES.md ..................... State: OPEN
+  - 1.1 <branch> ........ gates/node-1.1.md ............ State: OPEN
+    - 1.1.1 <leaf> ...... gates/leaf-1.1.1.md .......... Needs: - ...... State: READY
+    - 1.1.2 <leaf> ...... gates/leaf-1.1.2.md .......... Needs: - ...... State: READY
+  - 1.2 <branch> ........ gates/node-1.2.md ............ State: OPEN
+    - 1.2.1 <leaf> ...... gates/leaf-1.2.1.md .......... Needs: - ...... State: READY
+    - 1.2.2 <leaf> ...... gates/leaf-1.2.2.md .......... Needs: 1.2.1 .. State: WAITING
+
+Every leaf repeats its complete ownership as an `OWNS:` header in its ledger. Claim each concurrently dispatched leaf with `--claim`, then open and seal a native launch wave as described in `references/dispatch.md` before changing its state to IN-FLIGHT.
+
+## Status log
+
+Append events to `.unlazy/<scope>/status.log`; do not copy the event history into this file:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 dispatched"
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 verified"
+```
+
+Record contract amendments, plan changes, dispatch, parent verification, abandonment, branch integration, and lease release. Update the live State and Needs fields above when state changes; keep the log append-only. Before root completion, reread the current request and review every current inventory row against its owner and observing gate or manual review.

package/dist/skills/unlazy/templates/gates-leaf.md

@@ -0,0 +1,51 @@
+# Gates: <leaf or task name>
+
+OWNS: <repository-relative globs this leaf may write, for example src/api/**, tests/api/**>
+
+Scope: <one sentence describing the complete deliverable>
+
+- [ ] G1: <observable outcome measured directly from the artifact>
+  CHECK: node scripts/verify-outcome.mjs
+  EXPECT: outcome verification passed
+  EVIDENCE: pending
+
+- [ ] G2: <integration outcome in a subproject>
+  CHECK: node scripts/verify-integration.mjs
+  EXPECT: integration verification passed
+  CWD: packages/example
+  EVIDENCE: pending
+
+- [ ] G3: <manual outcome that no command can decide>
+  EVIDENCE: pending
+
+<!--
+Replace every placeholder before running the checker.
+
+Strict format:
+- Use a unique explicit id for every gate.
+- Indent CHECK, EXPECT, CWD, and EVIDENCE.
+- Give a runnable gate both CHECK and EXPECT; give a manual gate neither.
+- Success requires process exit 0 and EXPECT.
+- Make EXPECT a success-only marker produced after every assertion passes.
+- For an absence or negative assertion, test the same checker against a known
+  positive fixture and record that control in the gate's manual review.
+- Measure supplied figures from source. Do not copy a supplied number into
+  EXPECT as its own proof.
+- Use repository-owned Node scripts for portable examples. Declare any
+  non-default shell or external tool requirement explicitly.
+- Scoped and legacy discovery anchor checks at the repository root. When this
+  ledger is named explicitly from `.unlazy/`, pass an explicit repository
+  `--root` and `--cwd` so repository-relative commands keep the same base.
+- Record exact manual evidence and review consequential manual gates by risk.
+- OWNS paths must be repository-relative, complete, and disjoint from every
+  concurrently dispatched leaf. Claims coordinate writers; they do not sandbox.
+
+If a gate becomes genuinely impossible, keep the gate and add:
+
+```text
+ABANDON: G<n> <non-empty reason and handoff>
+```
+
+Surface every abandonment as a non-successful handoff in the final report; an
+abandoned leaf is not complete. See references/gates.md.
+-->

package/dist/skills/unlazy/templates/gates-node.md

@@ -0,0 +1,50 @@
+# Gates: <branch name> integration
+
+Scope: integrate children <explicit child ids> into one verified result
+
+- [ ] N1: every named child leaf is reverified from its exact ledger
+  CHECK: node <skill-dir>/scripts/gate-check.mjs --root . --cwd . --reverify --jobs 1 .unlazy/<scope>/gates/leaf-<a>.md .unlazy/<scope>/gates/leaf-<b>.md
+  EXPECT: ALL MET
+  EVIDENCE: pending
+
+- [ ] N2: child interfaces match the contract in PLAN.md
+  CHECK: node scripts/verify-interfaces.mjs
+  EXPECT: interface verification passed
+  EVIDENCE: pending
+
+- [ ] N3: cross-child behavior works end to end
+  CHECK: node scripts/verify-integration.mjs
+  EXPECT: integration verification passed
+  EVIDENCE: pending
+
+- [ ] N4: affected sibling behavior has not regressed
+  CHECK: node scripts/verify-regressions.mjs
+  EXPECT: regression verification passed
+  EVIDENCE: pending
+
+- [ ] N5: every direct child ownership lease was released after parent verification
+  EVIDENCE: pending
+
+- [ ] N6: consequential manual outcomes from the children were reviewed at branch level
+  EVIDENCE: pending
+
+<!--
+Replace every placeholder before running the checker.
+
+N1 must name every direct child explicitly and use --reverify, not --status.
+Status reports old evidence without executing it. Keep --jobs 1 unless the child
+checks are independent and deterministic parallel execution is intentional.
+If a child reports an abandonment, N1 exits 1 with `HANDOFF REQUIRED`. Mark the
+branch ABANDONED and surface the handoff; never rewrite that result as completion.
+
+Branch paths use node-<id>.md. Leaf paths use leaf-<id>.md. Branch completion
+requires integration evidence; a set of locally complete leaves is not enough.
+
+For N5, run this once for each direct child after verification and record the
+outputs as manual evidence:
+
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --leaf leaf-<id> --release
+
+Drop N5 only when no child claimed ownership. See references/orchestration.md
+and references/parallel.md.
+-->

package/dist/skills/unlazy/tests/contract-tests.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// Focused fixtures for PLAN contract reconciliation. Zero dependencies.
+//
+// The required ids below stand for a human reread of the current request. This
+// test intentionally does not infer requirements from prose; it checks that the
+// documented inventory control can discriminate omissions once that authority
+// is supplied.
+
+import assert from "node:assert/strict";
+
+const tests = [];
+const test = (name, fn) => tests.push({ name, fn });
+
+function reviewContract(spec) {
+  const gaps = [];
+  const rows = new Map();
+  for (const row of spec.rows) {
+    if (rows.has(row.id)) gaps.push(row.id + ": duplicate row");
+    rows.set(row.id, row);
+  }
+  for (const id of spec.required) {
+    const row = rows.get(id);
+    if (!row) { gaps.push(id + ": missing row"); continue; }
+    if (row.revision !== spec.revision) gaps.push(id + ": stale revision");
+    if (row.disposition === "REMOVED_BY_USER") {
+      if (!spec.removedByUser.has(id)) gaps.push(id + ": removal lacks explicit user authority");
+      continue;
+    }
+    if (row.disposition !== "ACTIVE") gaps.push(id + ": non-completion disposition " + row.disposition);
+    if (!row.owner || !spec.owners.has(row.owner)) gaps.push(id + ": missing or stale owner");
+    if (!row.observation || !spec.observations.has(row.observation)) {
+      gaps.push(id + ": missing or stale observation");
+    } else if (!spec.observations.get(row.observation).has(id)) {
+      gaps.push(id + ": observation does not cover outcome");
+    }
+  }
+  return gaps;
+}
+
+const base = () => ({
+  required: ["A", "B"],
+  revision: 1,
+  removedByUser: new Set(),
+  owners: new Set(["leaf-a", "leaf-b"]),
+  observations: new Map([["GA", new Set(["A"])], ["GB", new Set(["B"])]]),
+  rows: [
+    { id: "A", owner: "leaf-a", observation: "GA", disposition: "ACTIVE", revision: 1 },
+    { id: "B", owner: "leaf-b", observation: "GB", disposition: "ACTIVE", revision: 1 },
+  ],
+});
+
+test("contract: A and B mapped to live owners and observations reconcile", () => {
+  assert.deepEqual(reviewContract(base()), []);
+});
+
+test("contract: an omitted B is reported", () => {
+  const spec = base();
+  spec.rows.pop();
+  assert.match(reviewContract(spec).join("\n"), /B: missing row/);
+});
+
+test("contract: an unowned B is reported", () => {
+  const spec = base();
+  spec.rows[1].owner = "";
+  assert.match(reviewContract(spec).join("\n"), /B: missing or stale owner/);
+});
+
+test("contract: missing, stale, or wrong observations are reported", () => {
+  const missing = base();
+  missing.rows[1].observation = "";
+  assert.match(reviewContract(missing).join("\n"), /missing or stale observation/);
+  const stale = base();
+  stale.rows[1].observation = "OLD";
+  assert.match(reviewContract(stale).join("\n"), /missing or stale observation/);
+  const wrong = base();
+  wrong.rows[1].observation = "GA";
+  assert.match(reviewContract(wrong).join("\n"), /does not cover outcome/);
+});
+
+test("contract: explicit removal is distinct from abandonment or deferment", () => {
+  const removed = base();
+  removed.rows[1].disposition = "REMOVED_BY_USER";
+  removed.removedByUser.add("B");
+  assert.deepEqual(reviewContract(removed), []);
+  for (const disposition of ["ABANDONED", "DEFERRED", "OWNER_DECISION"]) {
+    const spec = base();
+    spec.rows[1].disposition = disposition;
+    assert.match(reviewContract(spec).join("\n"), new RegExp("non-completion disposition " + disposition));
+  }
+});
+
+test("contract: amendment C invalidates the prior revision until reconciled", () => {
+  const spec = base();
+  spec.revision = 2;
+  spec.required.push("C");
+  assert.match(reviewContract(spec).join("\n"), /stale revision/);
+  assert.match(reviewContract(spec).join("\n"), /C: missing row/);
+});
+
+test("contract: acceptance constraints count while optional ideas do not", () => {
+  const spec = base();
+  spec.required.push("NO_WRITE");
+  spec.optional = ["NICE_TO_HAVE"];
+  assert.match(reviewContract(spec).join("\n"), /NO_WRITE: missing row/);
+  assert.doesNotMatch(reviewContract(spec).join("\n"), /NICE_TO_HAVE/);
+});
+
+test("contract: a table cannot pass without the current request denominator", () => {
+  const spec = base();
+  spec.rows = [spec.rows[0]];
+  assert.notDeepEqual(reviewContract(spec), []);
+});
+
+let passed = 0;
+const failures = [];
+for (const current of tests) {
+  try {
+    current.fn();
+    passed++;
+    console.log("ok   " + current.name);
+  } catch (error) {
+    failures.push(current.name);
+    console.log("FAIL " + current.name + "\n     " + String(error.message).replace(/\n/g, "\n     "));
+  }
+}
+console.log("\n" + passed + "/" + tests.length + " passed");
+process.exit(failures.length ? 1 : 0);