shapeup-sdlc 1.7.0 → 3.0.0

package/kernel/harness.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// harness — the kernel's single entry point.
+//
+// WHAT THIS IS. Everything in the pipeline that must be DETERMINISTIC — measured rather than
+// claimed, single-writer rather than negotiated, an answer file rather than a vibe — is a
+// subcommand of this one script:
+//
+//     node ${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs <verb> [<action>] [flags]
+//
+// WHY ONE ENTRY POINT. A permission rule is matched against a command string. With one executable
+// the entire grant is two lines a person can read (`bin/lib/grant.mjs`); with twenty it is forty
+// rules that must be regenerated on every add, rename or removal — and a rule that silently
+// matches nothing is indistinguishable from a rule that works until the first dispatch fails.
+// Subcommands are free; entry points are not.
+//
+// WHO CALLS IT. Worker skills, from their own shells, and the hooks. The control plane — the
+// Workflow script — calls no shell at all: it branches on the structured return of an `agent()`
+// and never parses stdout.
+//
+// THE VERBS, and the invariant each one exists to keep:
+//
+//   verify   t0 · budget · envelope ·        Measured, not claimed. A model verifying itself is
+//            trace · spec · skills ·          claiming; these read artifacts and re-hash them.
+//            dispatch                         `skills` reads the roster off disk; `dispatch` reads
+//                                             the hook layer's evidence that a skill really resolved
+//                                             in this session — the half a file check cannot answer.
+//   reduce   ingest · hill · snapshot ·       Single writer. Shared state has exactly one author.
+//            ship · board · verdict · graph
+//   gate                                      An answer file with a source, not a vibe.
+//   probe    resume · t0 · stats · digest ·   Read-only queries over run state. `concurrency`
+//            concurrency · leg · eval          answers how many legs ran at once and what the
+//                                              fan-out bought, and refuses a figure the record set
+//                                              cannot support rather than printing a plausible one.
+//                                              `leg` answers whether a scope's work reached the
+//                                              board — a green T0 says its fixtures passed, not that
+//                                              its result was ever applied, and a leg that skipped
+//                                              its own ingest step is indistinguishable from one that
+//                                              did not until something reads the writer's own record.
+//                                              `eval` answers what an EVAL round's WorkResult
+//                                              actually said, mechanically — the round-loop branch
+//                                              reads this instead of trusting a dispatching agent's
+//                                              own end-of-turn summary of its own verdict.
+//   init     run · fit                        Opens a run, or refuses it (exit 3).
+//   report   export                           Projects the run's records as fact tables.
+//   compile                                   The WorkOrder: schema-valid or nothing is dispatched.
+//
+// EXIT CODES are the subcommand's own and are part of its contract: 0 success · 1 ran, answer is
+// no · 2 malformed input, nothing ran (`lib/argv.mjs`) · 3 `init run` refused to open · 4/5 gate
+// stop/abort · 6 budget tripped. This dispatcher adds exactly one of its own: 2 for an unknown
+// verb, which is the same "the input was malformed" case.
+
+import { isMain } from "./lib/argv.mjs";
+
+/**
+ * verb → action → module, the whole routing table.
+ *
+ * A verb whose value is a string takes no action word (`gate`, `compile`); a verb whose value is an
+ * object requires one, and `_default` names the action taken when it is omitted.
+ *
+ * Exported so the structural suite enumerates the subcommands from THIS table rather than from a
+ * hand-kept list beside it — a second copy of the routing is a second thing to forget.
+ */
+export const ROUTES = {
+  verify: {
+    t0: "./verify/t0.mjs", budget: "./verify/budget.mjs", envelope: "./verify/envelope.mjs",
+    trace: "./verify/trace.mjs", spec: "./verify/spec.mjs", skills: "./verify/skills.mjs",
+    dispatch: "./verify/dispatch.mjs",
+  },
+  reduce: {
+    ingest: "./reduce/ingest.mjs", hill: "./reduce/hill.mjs", snapshot: "./reduce/snapshot.mjs",
+    ship: "./reduce/ship.mjs", board: "./reduce/board.mjs", verdict: "./reduce/verdict.mjs",
+    graph: "./reduce/graph.mjs",
+  },
+  probe: {
+    resume: "./probe/resume.mjs", t0: "./probe/t0.mjs", stats: "./probe/stats.mjs",
+    digest: "./probe/digest.mjs", concurrency: "./probe/concurrency.mjs",
+    leg: "./probe/leg.mjs", eval: "./probe/eval.mjs",
+  },
+  init: { run: "./init/run.mjs", fit: "./init/fit.mjs" },
+  report: { export: "./report/export.mjs", _default: "export" },
+  gate: "./gate.mjs",
+  compile: "./compile.mjs",
+};
+
+/** Every `<verb> <action>` pair, for the usage text and the unknown-verb rejection. */
+function usage() {
+  const lines = [];
+  for (const [verb, target] of Object.entries(ROUTES)) {
+    if (typeof target === "string") lines.push(`  ${verb}`);
+    else lines.push(`  ${verb} ${Object.keys(target).filter((a) => a !== "_default").join(" | ")}`);
+  }
+  return `usage: harness.mjs <verb> [<action>] [flags]\n${lines.join("\n")}\n\nEvery subcommand accepts --help through its own argv spec.`;
+}
+
+/**
+ * Reject an invocation before anything runs, the same way `lib/argv.mjs` rejects a bad flag.
+ * @param {object} detail - Machine-readable rejection record.
+ * @returns {never} Exits 2.
+ */
+function reject(detail) {
+  process.stderr.write(JSON.stringify(detail) + "\n");
+  process.stderr.write(usage() + "\n");
+  process.exit(2);
+}
+
+/**
+ * Resolve `<verb> [<action>]` to a module path and the argv the subcommand should see.
+ *
+ * @param {string[]} argv - `process.argv.slice(2)`.
+ * @returns {{module: string, rest: string[]}} The module to import and its own arguments.
+ */
+export function route(argv) {
+  const [verb, ...rest] = argv;
+  if (!verb || verb === "--help" || verb === "-h") { process.stdout.write(usage() + "\n"); process.exit(0); }
+  const target = ROUTES[verb];
+  if (!target) reject({ error: "unknown_verb", verb, expected: Object.keys(ROUTES).join(" | ") });
+  if (typeof target === "string") return { module: target, rest };
+
+  const action = rest[0] && !rest[0].startsWith("-") ? rest[0] : target._default;
+  const module = action ? target[action] : null;
+  if (!module) {
+    reject({
+      error: action ? "unknown_action" : "missing_action", verb, action: action ?? null,
+      expected: Object.keys(target).filter((a) => a !== "_default").join(" | "),
+    });
+  }
+  return { module, rest: rest[0] === action ? rest.slice(1) : rest };
+}
+
+if (isMain(import.meta.url)) {
+  const { module, rest } = route(process.argv.slice(2));
+  const mod = await import(module);
+  await mod.cli(rest);
+}

package/{skills/tech-lead/scripts/fit-check.mjs → kernel/init/fit.mjs}

@@ -34,17 +34,16 @@
 // symmetric, and the tie goes to the gates.
 //
 // USAGE
-//   node fit-check.mjs --intake-file <path> [--cwd <root>] [--json]
-//   node fit-check.mjs --intake-text "<requirement>" [--cwd <root>]
+//   node `harness init fit` --intake-file <path> [--cwd <root>] [--json]
+//   node `harness init fit` --intake-text "<requirement>" [--cwd <root>]
 //
 // Exit 0 always — this informs a decision, it does not deny a tool call. The orchestrator reads
-// `lane` and acts on it; `init-run.mjs` records it in the receipt.
+// `lane` and acts on it; ``harness init run`` records it in the receipt.
 
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
-import { LOCAL } from "./lib/paths.mjs";
-import { runArgs } from "./lib/argv.mjs";
+import { LOCAL } from "../lib/paths.mjs";
+import { runArgs } from "../lib/argv.mjs";
 
 /** Directories that are never part of "the tree being changed". */
 const IGNORE_DIRS = new Set([".git", "node_modules", LOCAL, "dist", "build", ".next", "coverage", ".claude"]);
@@ -160,15 +159,22 @@ export function decideLane({ intake, files }) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: 'fit-check.mjs (--intake-file <path> | --intake-text "<requirement>") [--cwd <dir>]',
+  usage: 'harness.mjs init fit (--intake-file <path> | --intake-text "<requirement>") [--cwd <dir>]',
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   "intake-text": { type: "str" },
   "intake-file": { type: "path" },
 };
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Decide the lane (full or tiny) for an intake and the tree it will build in.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
   let intake = args.intakeText ?? null;
   const f = args.intakeFile ?? null;
@@ -191,6 +197,3 @@ export function main() {
   }, null, 2));
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}

package/{skills/tech-lead/scripts/init-run.mjs → kernel/init/run.mjs}

@@ -15,7 +15,7 @@
 //
 // Two guards existed and neither could see it:
 //   • `gate-intake.mjs` (L0.0) fires on an EMPTY intake. Intake was valid here. Correct no-op.
-//   • `anti-rationalization.mjs` fires when a completion claim contradicts run facts. It is
+//   • the ship report's census fires when a completion claim contradicts run facts. It is
 //     scoped to an ACTIVE run — and a run that never started produces none of the files it
 //     reads — and its claim detector matches past-tense completion ("done", "shipped"), while
 //     narration is future-tense ("it will"). Two independent misses on the same transcript.
@@ -39,9 +39,9 @@
 // verbatim next to its digest, so "the spec was dropped" is checkable, not arguable.
 //
 // USAGE
-//   node init-run.mjs --slug <slug> --intake-file <path>            [options]   <- prefer this
-//   node init-run.mjs --slug <slug> --intake-text "<requirement>"   [options]
-//   cat spec.md | node init-run.mjs --slug <slug> --intake-stdin    [options]
+//   node `harness init run` --slug <slug> --intake-file <path>            [options]   <- prefer this
+//   node `harness init run` --slug <slug> --intake-text "<requirement>"   [options]
+//   cat spec.md | node `harness init run` --slug <slug> --intake-stdin    [options]
 //
 // PREFER --intake-file. A multi-line requirement inlined into a shell argument is where this step
 // goes wrong: quoting breaks, a `#` after a newline trips path validation, and the run spends six
@@ -53,8 +53,8 @@
 //   --attempts N    inner per-scope T0 budget         (default: 5)
 //   --spec-folder   SHARED spec deliverable path      (default: shapeup/<slug>/spec/)
 //   --dimensions    comma-separated eval dimensions   (default: spec-conformance)
-//   --gate-answers  path | preset name                (see gate-answers.mjs; recorded, not read)
-//   --wall-clock-budget N  deadline breaker, seconds  (off by default; see budget-check.mjs)
+//   --gate-answers  path | preset name                (see `harness gate`; recorded, not read)
+//   --wall-clock-budget N  deadline breaker, seconds  (off by default; see `harness verify budget`)
 //   --cwd           project root                      (default: process.cwd())
 //   --force         re-init over an existing run receipt
 //
@@ -68,15 +68,16 @@
 // that takes a phase, not an init-run flag that takes a slug: the one instruction available at the
 // one moment it mattered named a mechanism that does not parse.
 
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
 import { createHash } from "node:crypto";
-import { decideLane, treeSize } from "./fit-check.mjs";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { uncoerce } from "./lib/contract-md.mjs";
-import { deriveSnapshot } from "./run-snapshot.mjs";
-import { localRoot, activeScope, globLocal, globShared } from "./lib/paths.mjs";
+import { decideLane, treeSize } from "./fit.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { uncoerce } from "../lib/contract.mjs";
+import { deriveSnapshot } from "../reduce/snapshot.mjs";
+import { mintRunId } from "../lib/paths.mjs";
+import { localRoot, activeScope, globLocal, globShared, ordersDir, resultsDir } from "../lib/paths.mjs";
+import { resolveWorkers } from "../verify/skills.mjs";
 
 export const RECEIPT_VERSION = 1;
 
@@ -129,24 +130,43 @@ export function digest(text) {
  * Build the receipt record. Pure — takes resolved inputs, returns the object that gets written.
  * Kept separate from I/O so the structural tests can assert its shape without a filesystem.
  */
-export function buildReceipt({ slug, intake, config, startedAt }) {
+export function buildReceipt({ slug, intake, config, startedAt, plugin = null }) {
   const intakeText = String(intake ?? "");
+  const intakeSha256 = digest(intakeText);
   return {
     receipt_version: RECEIPT_VERSION,
     type: "harness-run-receipt",
     slug,
+    // THE JOIN KEY, minted here because this is where a run acquires an identity at all.
+    //
+    // `order_id` was the nearest thing the harness had, and it is `<slug>/r<N>-a<M>`: unique
+    // WITHIN a run and identical across every run of the same slug. So every record the pipeline
+    // writes — orders, results, journal rows, trial rows, hook receipts — could be grouped by
+    // feature and never by RUN, which makes "compare this run against the last one" and "what did
+    // this run cost" both unanswerable from data that was otherwise all present.
+    //
+    // Derived, not drawn (see `mintRunId` in lib/paths.mjs): a pure function of the three fields below
+    // it, so any writer holding this receipt recomputes the same id without being handed it, and a
+    // receipt written before this field existed still yields the id it would have been given.
+    run_id: mintRunId({ slug, startedAt, intakeSha256 }),
     started_at: startedAt,
-    intake_sha256: digest(intakeText),
+    intake_sha256: intakeSha256,
     intake_chars: intakeText.length,
     intake_lines: intakeText ? intakeText.split("\n").length : 0,
     // The single fact that separates "the harness ran" from "the harness described itself".
     // Written before any gate, so its ABSENCE at Stop is unambiguous.
     started: true,
+    // WHICH COPY OF THE PLUGIN PRODUCED THIS RUN. Recorded while it is in hand, because afterwards
+    // it is unrecoverable: every artifact a run leaves looks identical whether it came from this
+    // version, a stale marketplace install, or a sub-agent improvising past a failed dispatch. A
+    // run whose trace cannot name its own plugin cannot be compared with another run, and cannot be
+    // cleared of the wrong-version failure the roster check exists to catch.
+    plugin: plugin ? { name: plugin.name, version: plugin.version, root: plugin.root } : null,
     config,
   };
 }
 
-/** The `harness-run.md` frontmatter block, per references/ledger-schema.md. */
+/** The `harness-run.md` frontmatter block, per references/protocol.md Part 4 — State. */
 export function runFrontmatter({ slug, config, startedAt }) {
   return [
     "---",
@@ -175,7 +195,7 @@ export function runFrontmatter({ slug, config, startedAt }) {
     "",
     `# Harness run — ${slug}`,
     "",
-    "Opened by `init-run.mjs` (GATE L0.1). The tech lead is the sole writer from here on.",
+    "Opened by ``harness init run`` (GATE L0.1). The tech lead is the sole writer from here on.",
     "",
     "## Rounds",
     "",
@@ -191,15 +211,62 @@ export function runFrontmatter({ slug, config, startedAt }) {
   ].join("\n");
 }
 
+/**
+ * Unwedge `--force`: resolve every order left LIVE by a run nobody is continuing.
+ *
+ * `hooks/sandbox-guard.mjs`'s `liveOrders()` treats any file under `orders/` with no SAME-NAMED
+ * file under `results/` as live, and constrains every later Edit/Write to what some live order's
+ * substrate permits. `--force` used to `mkdirSync(..., {recursive:true})` over the same directories
+ * and stop — a no-op on dirs that already exist and already hold the stale order, so the wedge
+ * survived it exactly as before. This is the real unwedge path: for every order abandoned by the run
+ * being forced over, write a same-named record under `results/` so `liveOrders()` no longer counts
+ * it, without deleting the order file itself (`orders/` is this codebase's own audit trail of what
+ * was dispatched, not a rolling buffer — losing the file loses the record that a dispatch happened).
+ *
+ * Not a real WorkResult: `work-result.schema.json`'s `status` enum (done/partial/escalated/failed)
+ * has no member that honestly means "no worker ever answered" — every one of those values would
+ * misrepresent an abandoned dispatch as an attempt that actually ran. So this writes a plainly
+ * self-labelled, intentionally non-conforming marker instead of forcing a lie into a schema-valid
+ * shape. `liveOrders()` only checks filename presence under `results/`, never content, so this is
+ * sufficient to unwedge on its own.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - The run being forced over.
+ * @returns {string[]} Order-id suffixes (filenames minus `.json`) resolved as abandoned.
+ */
+export function resolveAbandonedOrders(cwd, slug) {
+  const oDir = ordersDir(cwd, slug);
+  const rDir = resultsDir(cwd, slug);
+  if (!existsSync(oDir)) return [];
+  const done = new Set(existsSync(rDir) ? readdirSync(rDir) : []);
+  const resolvedAt = new Date().toISOString();
+  const resolved = [];
+  for (const f of readdirSync(oDir)) {
+    if (!f.endsWith(".json") || done.has(f)) continue;
+    mkdirSync(rDir, { recursive: true });
+    const marker = {
+      synthetic: true,
+      status: "abandoned", // not in work-result.schema.json's enum — deliberately: see banner above
+      order_id: f.slice(0, -".json".length),
+      reason: "dispatched, never answered — resolved by `harness init run --force`",
+      resolved_at: resolvedAt,
+    };
+    writeFileSync(join(rDir, f), JSON.stringify(marker, null, 2) + "\n", "utf8");
+    resolved.push(marker.order_id);
+  }
+  return resolved;
+}
+
 // ---- CLI -------------------------------------------------------------------
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: 'init-run.mjs (--intake-file <path> | --intake-text "<req>" | --intake-stdin) ' +
+  usage: 'harness.mjs init run (--intake-file <path> | --intake-text "<req>" | --intake-stdin) ' +
          "[--slug <slug>] [--auto-level interactive|auto|unattended] [--lens <lens>] " +
          "[--max-rounds N] [--attempts N] [--spec-folder <dir>] [--dimensions <a,b>] " +
          "[--gate-answers <preset|path>] " +
-         "[--lane full|tiny] [--tiny] [--wall-clock-budget <seconds>] [--cwd <dir>] [--force]",
+         "[--lane full|tiny] [--tiny] [--wall-clock-budget <seconds>] [--cwd <dir>] " +
+         "[--plugin-root <dir>] [--force]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   "intake-text": { type: "str" },
@@ -216,6 +283,11 @@ export const ARGV_SPEC = {
   lane: { type: "str" },
   tiny: { type: "flag" },
   "wall-clock-budget": { type: "int", min: 1 },
+  // Which copy of the plugin this run is opened against. Defaults to the one this kernel is part
+  // of, which is right for every ordinary invocation; it is nameable because a machine can carry
+  // several installs, and because the roster refusal below is otherwise unreachable for a test —
+  // a check whose failure path cannot be exercised is a check nobody has seen work.
+  "plugin-root": { type: "path" },
   force: { type: "flag" },
 };
 
@@ -224,10 +296,45 @@ function fail(code, msg) {
   process.exit(code);
 }
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Open a run: mint the receipt, or refuse (exit 3) when one is already live.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
 
+  // GATE L0 — the worker roster, before any spend.
+  //
+  // HERE AND NOT IN THE WORKFLOW SCRIPT, for two reasons. This is what GATE L0 actually executes,
+  // and it covers both lanes rather than only the orchestrated one — the prose/`--tiny` lane opens
+  // its run through exactly this call. And it is genuinely before any spend: the workflow script's
+  // own helpers reach the kernel by spawning a sub-agent first, so a check placed there has already
+  // paid for a model call before it can refuse.
+  //
+  // What it can and cannot prove is stated in verify/skills.mjs and is worth repeating where it is
+  // enforced: this says the files exist at this root at this version. It does not say the SESSION
+  // will resolve that copy. The orchestrator's canary dispatch answers that, and its receipt is the
+  // evidence; this refusal is the cheap half that costs nothing to run on every single run.
+  const plugin = resolveWorkers(args.pluginRoot ? resolve(args.pluginRoot) : undefined);
+  if (plugin.missing.length) {
+    fail(3, [
+      `✋ init-run: refusing to open a run — ${plugin.missing.length} of ${plugin.workers.length} worker skills are missing.`,
+      "",
+      `  plugin: ${plugin.name ?? "unknown"} ${plugin.version ?? "unknown version"}`,
+      `  root:   ${plugin.root}`,
+      `  missing: ${plugin.missing.join(", ")}`,
+      "",
+      "A run against this copy would dispatch workers that cannot resolve, and a failed dispatch is",
+      "answered by the sub-agent improvising the craft itself — phases reporting complete with none",
+      "of the shipped craft applied. Load the working copy (`claude --plugin-dir <repo>`) or install",
+      "and enable the plugin, then retry. `harness verify skills` reports the same thing on demand.",
+    ].join("\n"));
+  }
+
   let intake = args.intakeText ?? null;
   const intakeFile = args.intakeFile ?? null;
   // `--intake-file -` is the shape everyone reaches for; accept it rather than erroring on a
@@ -271,7 +378,7 @@ export function main() {
     spec_folder: args.specFolder ?? `${globShared(slug, "spec")}/`,
     gate_answers: args.gateAnswers ?? null,
     tiny_lane: !!args.tiny,
-    // GATE L0.3 — the lane, computed rather than judged (see fit-check.mjs). Recorded with its
+    // GATE L0.3 — the lane, computed rather than judged (see `harness init fit`). Recorded with its
     // evidence so a heavy lane on a small change is visible instead of accidental. An explicit
     // --lane or --tiny is honoured and marked as an override, because a measured recommendation
     // fitted on three features must not outrank a human who knows the codebase.
@@ -282,7 +389,7 @@ export function main() {
         ? { ...auto, lane: forced, overridden_from: auto.lane, override_source: args.tiny ? "--tiny" : "--lane" }
         : auto;
     })(),
-    // The third breaker (see scripts/budget-check.mjs). Null = off, which is the default and
+    // The third breaker (see `harness verify budget`). Null = off, which is the default and
     // keeps every existing run behaving exactly as before. Set it in any lane with a hard clock
     // — CI, an overnight run — so the harness trips its own breaker and ships what
     // is green, instead of being killed from outside and shipping nothing.
@@ -298,14 +405,14 @@ export function main() {
   // <slug>`)". `--from` is not an init-run flag at all; it is a `/tech-lead` flag, and it takes a
   // PHASE (`--from build`), not a slug. So at the one moment the orchestrator most needs a next
   // step, the runtime named a mechanism that does not exist, on a script whose failure mode was
-  // already invisible (see lib/is-main.mjs — under a symlinked install this whole body did not run).
+  // already invisible — under a symlinked install an entry-point guard once skipped this whole body.
   //
   // Observed consequence on a handoff: a fresh session in a workspace with an open run burns most
   // of its budget before its first write, largely on forensics against this step, and closes none
   // of the gap.
   //
   // So the refusal now DOES the resume work instead of describing it. It emits the derived snapshot
-  // — the same file-only derivation `hooks/session-rehydrate.mjs` injects — so the orchestrator gets
+  // — the same file-only derivation `harness reduce graph --subgraph run` injects — so the orchestrator gets
   // slug, status, round, attempt, board counts and pending orders in THIS tool call rather than
   // needing to discover that it needs another one. Exit 3 still means "do not proceed as if you
   // opened a run"; it now also means "here is the run you are actually in".
@@ -328,13 +435,28 @@ export function main() {
           ].join("\n"),
       "",
       "To re-derive this at any time:",
-      "  node <plugin>/skills/tech-lead/scripts/run-snapshot.mjs --cwd <dir>",
+      "  node <plugin>/kernel/harness.mjs reduce snapshot --cwd <dir>",
       "To abandon the open run and start over, deliberately: --force",
     ].join("\n"));
   }
 
+  // THE REAL UNWEDGE PATH. `--force` used to `mkdirSync(..., {recursive:true})` over orders/,
+  // results/ and discovery/ and stop — a no-op on directories that already exist and already hold a
+  // dispatched-but-unanswered order, so `sandbox-guard.mjs`'s `liveOrders()` kept constraining every
+  // later write to that stale order's substrate regardless of `--force`. Resolve every such order
+  // BEFORE the fresh run starts writing (see `resolveAbandonedOrders()` above for why this writes a
+  // marker under `results/` rather than deleting the order file).
+  if (args.force) {
+    const abandoned = resolveAbandonedOrders(cwd, slug);
+    if (abandoned.length) {
+      console.error(
+        `⚠ init-run --force: resolved ${abandoned.length} dispatched-but-unanswered order(s) as abandoned — ${abandoned.join(", ")}`,
+      );
+    }
+  }
+
   const startedAt = new Date().toISOString();
-  const receipt = buildReceipt({ slug, intake, config, startedAt });
+  const receipt = buildReceipt({ slug, intake, config, startedAt, plugin });
 
   mkdirSync(runRoot, { recursive: true });
   mkdirSync(join(runRoot, "orders"), { recursive: true });
@@ -354,6 +476,8 @@ export function main() {
   console.log(JSON.stringify({
     ok: true,
     slug,
+    // Echoed so the orchestrator can put it in RunArgs without re-reading the receipt.
+    run_id: receipt.run_id,
     run_root: globLocal(slug),
     receipt: globLocal(slug, "receipt.json"),
     intake_sha256: receipt.intake_sha256,
@@ -363,6 +487,3 @@ export function main() {
   }, null, 2));
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}

package/{skills/tech-lead/scripts → kernel}/lib/argv.mjs

@@ -1,44 +1,27 @@
-// parseArgs — the typed argv boundary.
+// argv — the typed CLI boundary: who is running, and with what.
 //
-// WHY THIS FILE EXISTS (measured by executing the shipped scripts, not theorized).
-//
-// This project's envelope boundary is rigorously typed: 38 `$defs` in `domain.schema.json`,
-// both directions validated, and a `PreToolUse` hook that DENIES a malformed WorkOrder before a
-// worker ever sees it. That discipline stopped dead at `process.argv` — which is where the
-// pipeline actually executes.
-//
-// The reproduced defect. `t0-verify.mjs` parsed its own flags with
-//
-//     if (a === "--round") out.round = Number(argv[++i]);      // then: args.round ?? 1
-//
-// `Number(undefined)` is `NaN`, and `??` does not catch `NaN`. So passing a flag WITHOUT a value
-// wrote a real verdict artifact to `t0/verdicts/rNaN-a1.json` and **exited 0**:
-//
-//     $ t0-verify.mjs contract.json --round --attempt 1
-//     { "path": "t0/verdicts/rNaN-a1.json", "overall": "green", ... }   exit=0
-//
-// The orchestrator then looks for `r1-a1.json`, finds nothing, and the evaluator's MANDATORY T0
-// citation cannot resolve — on the single artifact the judge is structurally required to cite.
-// A green verdict at an address nobody will look up is the same failure class as a silent no-op:
-// indistinguishable from working.
-//
-// THE CONTRACT, mirroring `validate-envelope`'s: reject BEFORE anything runs, exit 2, and put a
+// CONTRACT, mirroring the envelope's: reject BEFORE anything runs, exit 2, and put a
 // machine-readable reason on stderr. Nothing here touches the filesystem, so a rejected parse
-// cannot leave a half-written artifact behind.
+// cannot leave a half-written artifact behind. Exit 2 is this plugin's "the input was malformed,
+// nothing ran" code — deliberately NOT 1, which every oracle uses for "ran, and the answer is no".
 //
 //     const SPEC = {
 //       _:           { arity: 1, name: "scope-contract.json" },
 //       round:       { type: "int", min: 1, required: true },
 //       "no-seesaw": { type: "flag" },
 //     };
-//     const args = runArgs(SPEC, process.argv.slice(2));   // args.round, args.noSeesaw, args._
+//     const args = runArgs(SPEC, argv);   // args.round, args.noSeesaw, args._
 //
-// Flag names reach the caller camelCased (`--no-seesaw` → `noSeesaw`), so adoption does not
-// rewrite call sites. Unknown flags are rejected rather than silently swallowed as positionals:
-// a typo'd `--rounds 2` that lands in `_` is the same defect wearing a different hat.
+// Flag names reach the caller camelCased (`--no-seesaw` → `noSeesaw`). Unknown flags are rejected
+// rather than swallowed as positionals: a typo'd `--rounds 2` landing in `_` is the same defect
+// wearing a different hat. Untyped coercion is the failure this guards — `Number(undefined)` is
+// `NaN`, `??` does not catch `NaN`, and a verdict written to `r NaN-a1.json` with exit 0 is
+// indistinguishable from working.
 //
-// The structural suite executes every entry point with each declared int flag
-// both empty and non-numeric, and asserts exit 2 with a parseable reason and no artifact on disk.
+// {@link isMain} answers the other half of the boundary question: was this module executed, or
+// imported? Comparing `import.meta.url` to a raw `file://${process.argv[1]}` is false under a
+// symlinked install path (macOS `/var`, nvm, pnpm, Homebrew) and under any path containing a space,
+// which silently turns an entry point into a no-op that still exits 0.
 
 /** Thrown by {@link parseArgs} when argv does not satisfy the spec. `detail` is the wire shape. */
 export class ArgvError extends Error {
@@ -222,3 +205,41 @@ export function runArgs(spec, argv = process.argv.slice(2)) {
     process.exit(2);
   }
 }
+
+// ---------------------------------------------------------------------------
+// isMain — "was this module executed directly, or imported?"
+// ---------------------------------------------------------------------------
+
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+/**
+ * True when `moduleUrl` belongs to the module Node was asked to execute.
+ *
+ * Resolves both sides through `pathToFileURL` (so percent-encoding matches) and `realpathSync` (so
+ * symlinks match), which is what makes the guard hold where the naive string compare does not.
+ *
+ * @param {string} moduleUrl - The caller's `import.meta.url`.
+ * @returns {boolean} true if executed directly, false if imported (or if there is no entry point,
+ *   e.g. `node --eval`, where nothing should auto-run).
+ */
+export function isMain(moduleUrl) {
+  const entry = process.argv[1];
+  if (!entry || !moduleUrl) return false;
+
+  // Cheap path first: correct encoding, no filesystem access. Handles spaces and unicode.
+  let entryUrl;
+  try { entryUrl = pathToFileURL(entry).href; } catch { return false; }
+  if (entryUrl === moduleUrl) return true;
+
+  try {
+    const realEntry = pathToFileURL(realpathSync(entry)).href;
+    if (realEntry === moduleUrl) return true;
+    return realEntry === pathToFileURL(realpathSync(new URL(moduleUrl))).href;
+  } catch {
+    // An unreadable or deleted entry point is not this function's problem to report. Returning
+    // false means "do not auto-run", which is the safe direction for an imported module and is
+    // never the direction that silently skips a gate.
+    return false;
+  }
+}