shapeup-sdlc 1.6.2

package/skills/tech-lead/scripts/ingest-result.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+// WorkResult ingester (pure-skill architecture v1.0, plan P1).
+//
+// The other half of the orchestrator's pipeline sub-layer — and the mechanism that finally
+// closes D6: workers no longer write shared state; they RETURN data (a WorkResult envelope)
+// and this script performs every shared-state write, deterministically, in one place:
+//
+//   task_results[]      → tick AC boxes, flip task frontmatter status, append Execution Log,
+//                         update tasks/_index.md row, propagate unblocks (old P3.1–P3.6)
+//   discoveries[]       → append to .shapeup/<slug>/discovery/ledger.md (old P3.7 / QA H.3)
+//   verdict.criteria[]  → append evaluation/.verdicts-<target>.jsonl (old evaluator B.0)
+//   verdict.refuted[]   → un-tick refuted AC boxes + set eval_verdict frontmatter (old B.2/B.2b)
+//   escalates[]         → queue .shapeup/<slug>/escalates/<order>.json for the orchestrator
+//
+// Zero dependencies, zero network, schema-validated input (a malformed result never mutates
+// the board). Single-writer becomes mechanically true, not aspirational.
+//
+// Usage:  node skills/tech-lead/scripts/ingest-result.mjs <result.json> [--cwd <dir>]
+// Exit:   0 = ingested, 1 = result rejected (schema) or a write failed.
+
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validate } from "./validate-envelope.mjs";
+import { isMain } from "./lib/is-main.mjs";
+import { runArgs } from "./lib/argv.mjs";
+import { tasksDir, localRoot } from "./lib/paths.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const RESULT_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "../schemas/work-result.schema.json"), "utf8"));
+
+/**
+ * @returns {string} Today's date as an ISO `YYYY-MM-DD` string (UTC), for log/frontmatter stamps.
+ */
+const today = () => new Date().toISOString().slice(0, 10);
+
+/**
+ * Locate a task file on the LOCAL board by id.
+ * @param {string} cwd - Working-directory root.
+ * @param {string} slug - Feature slug.
+ * @param {string} taskId - Task id prefix to match (e.g. "TASK-001").
+ * @returns {string|null} Absolute path of the first `<taskId>*.md` file, or null when the tasks
+ *   directory or a matching file does not exist.
+ */
+export function findTaskFile(cwd, slug, taskId) {
+  const dir = tasksDir(cwd, slug);
+  if (!existsSync(dir)) return null;
+  const f = readdirSync(dir).find((n) => n.startsWith(taskId) && n.endsWith(".md"));
+  return f ? join(dir, f) : null;
+}
+
+/**
+ * Set a scalar frontmatter field in a task-file body, adding it when absent.
+ * @param {string} body - Full task-file text.
+ * @param {string} key - Frontmatter key to set.
+ * @param {(string|number)} value - Value to write (stringified inline).
+ * @returns {string} The body with `key: value` set; returned unchanged when the body has no
+ *   frontmatter block.
+ */
+export function setFrontmatter(body, key, value) {
+  const m = body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return body;
+  const re = new RegExp(`^${key}:.*$`, "m");
+  const fm = re.test(m[1]) ? m[1].replace(re, `${key}: ${value}`) : `${m[1]}\n${key}: ${value}`;
+  return body.replace(m[1], fm);
+}
+
+/**
+ * Tick or un-tick the first acceptance-criterion checkbox whose text matches `ac`.
+ * @param {string} body - Full task-file text.
+ * @param {string} ac - Criterion text to match (case/space-insensitive substring, either direction).
+ * @param {boolean} checked - true to write `[x]`, false to write `[ ]`.
+ * @returns {{body:string, hit:boolean}} The updated body and whether a checkbox matched (only the
+ *   first match is changed).
+ */
+export function setCheckbox(body, ac, checked) {
+  const needle = ac.toLowerCase().replace(/\s+/g, " ").trim();
+  const lines = body.split(/\r?\n/);
+  let hit = false;
+  const out = lines.map((line) => {
+    const m = line.match(/^(\s*- \[)([ x])(\]\s+)(.*)$/);
+    if (!m || hit) return line;
+    const text = m[4].toLowerCase().replace(/\s+/g, " ").trim();
+    if (text.includes(needle) || needle.includes(text)) {
+      hit = true;
+      return `${m[1]}${checked ? "x" : " "}${m[3]}${m[4]}`;
+    }
+    return line;
+  });
+  return { body: out.join("\n"), hit };
+}
+
+/**
+ * Flip a task's row in `tasks/_index.md` to a done state.
+ * @param {string} indexBody - Full board-index text.
+ * @param {string} taskId - Task id whose row to update.
+ * @param {boolean} done - When true, rewrite the row's status emoji/word to done; false is a no-op.
+ * @returns {string} The board text with the matching row updated (unchanged when no row matches).
+ */
+export function updateBoardRow(indexBody, taskId, done) {
+  return indexBody.split(/\r?\n/).map((line) => {
+    if (!line.includes(taskId) || !line.includes("|")) return line;
+    if (done) return line.replace(/⬜|🔄|⏳|🚫/g, "✅").replace(/\b(ready|in-progress|blocked)\b/gi, "done");
+    return line;
+  }).join("\n");
+}
+
+/**
+ * Apply one validated WorkResult to the working tree — the single-writer step (D6): ticks AC
+ * boxes, flips task status, appends the Execution Log, propagates unblocks, appends discoveries,
+ * writes the verdict ledger + un-ticks refuted boxes, and queues escalates.
+ * @param {object} result - A schema-valid WorkResult (order_id, task_results[], discoveries[],
+ *   verdict{criteria[],refuted[]}, escalates[]).
+ * @param {{cwd:string}} opts - cwd: working-directory root every LOCAL path resolves against.
+ * @returns {{slug:string, tasks_updated:string[], acs_ticked:number, unblocked:string[],
+ *   discoveries_appended:number, refuted_unticked:number, verdict_lines:number,
+ *   escalates_queued:number}} A summary of every write performed.
+ * @throws {Error} If a task/board/ledger file it must write is not writable (fs error propagates).
+ *   Side effects: writes task files, `tasks/_index.md`, `discovery/ledger.md`,
+ *   `evaluation/.verdicts-*.jsonl`, and `escalates/*.json` under `.shapeup/<slug>/`.
+ */
+export function applyResult(result, { cwd }) {
+  const slug = result.order_id.split("/")[0];
+  const local = localRoot(cwd, slug);
+  const summary = { slug, tasks_updated: [], acs_ticked: 0, unblocked: [], discoveries_appended: 0, refuted_unticked: 0, verdict_lines: 0, escalates_queued: 0 };
+
+  // 1. Task results → task files + board (old task-executor P3.1/P3.2/P3.6).
+  const boardIndex = join(local, "tasks", "_index.md");
+  for (const tr of result.task_results || []) {
+    const path = findTaskFile(cwd, slug, tr.task_id);
+    if (!path) continue;
+    let body = readFileSync(path, "utf8");
+    for (const acr of tr.ac_results || []) {
+      if (acr.result === "pass") {
+        const r = setCheckbox(body, acr.ac, true);
+        body = r.body;
+        if (r.hit) summary.acs_ticked++;
+      }
+    }
+    if (tr.status === "done") {
+      body = setFrontmatter(body, "status", "done");
+      body = setFrontmatter(body, "completed_at", today());
+    } else if (tr.status === "partial" || tr.status === "failed") {
+      body = setFrontmatter(body, "status", "in-progress");
+    }
+    // Execution Log (append; the checkbox list must never disagree with it).
+    const logLines = (tr.ac_results || []).map((a) => `- ${a.ac}: ${a.result}${a.evidence ? ` (${a.evidence})` : ""}`).join("\n");
+    body += `\n\n## Execution Log — ${today()} (${result.order_id})\n- executor: ${result.worker || "task-executor"} via ingest-result\n- status: ${tr.status}\n${logLines}${tr.notes ? `\n- notes: ${tr.notes}` : ""}\n`;
+    writeFileSync(path, body);
+    summary.tasks_updated.push(tr.task_id);
+    if (tr.status === "done" && existsSync(boardIndex)) {
+      writeFileSync(boardIndex, updateBoardRow(readFileSync(boardIndex, "utf8"), tr.task_id, true));
+    }
+  }
+
+  // 2. Unblock propagation (old P3.4): any blocked task whose dependencies are all done → ready.
+  const tasksDir = join(local, "tasks");
+  if (existsSync(tasksDir)) {
+    const files = readdirSync(tasksDir).filter((f) => /^TASK-[\w.-]+\.md$/i.test(f));
+    const statusOf = {};
+    const parsed = files.map((f) => {
+      const body = readFileSync(join(tasksDir, f), "utf8");
+      const id = (body.match(/^id:\s*(TASK-[\w.-]+)/im) || [])[1] || f.replace(/\.md$/, "");
+      const status = (body.match(/^status:\s*(\S+)/im) || [])[1] || "unknown";
+      const deps = (body.match(/^depends_on:\s*\[([^\]]*)\]/im) || [, ""])[1]
+        .split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+      statusOf[id] = status;
+      return { f, id, status, deps, body };
+    });
+    for (const t of parsed) {
+      if (t.status === "blocked" && t.deps.length && t.deps.every((d) => statusOf[d] === "done")) {
+        writeFileSync(join(tasksDir, t.f), setFrontmatter(t.body, "status", "ready"));
+        summary.unblocked.push(t.id);
+        if (existsSync(boardIndex)) {
+          const idx = readFileSync(boardIndex, "utf8").split(/\r?\n/).map((line) =>
+            line.includes(t.id) && line.includes("|")
+              ? line.replace(/🚫|⏳/g, "⬜").replace(/\bblocked\b/gi, "ready")
+              : line).join("\n");
+          writeFileSync(boardIndex, idx);
+        }
+      }
+    }
+  }
+
+  // 3. Discoveries → the ledger (old P3.7 / QA H.3). Single writer: this script.
+  if (result.discoveries?.length) {
+    const ledgerDir = join(local, "discovery");
+    mkdirSync(ledgerDir, { recursive: true });
+    const ledger = join(ledgerDir, "ledger.md");
+    if (!existsSync(ledger)) writeFileSync(ledger, `---\nfeature: ${slug}\n---\n# Discovery Ledger — ${slug}\n`);
+    const lines = result.discoveries.map((d) => {
+      const tags = [d.lens ? `[lens:${d.lens}]` : "", d.severity_hint ? `severity-hint: ${d.severity_hint}` : "", d.test_gap ? `test-gap: ${d.test_gap}` : "", d.contradicts ? `contradicts: ${d.contradicts}` : "", d.traces_to?.length ? `traces_to: ${d.traces_to.join(", ")}` : ""].filter(Boolean);
+      return `${d.marker} ${d.lens ? tags[0] + " " : ""}${d.line}${d.repro ? `\n    repro: ${d.repro}` : ""}${tags.slice(d.lens ? 1 : 0).map((t) => `\n    ${t}`).join("")}`;
+    }).join("\n");
+    appendFileSync(ledger, `\n## Discovered — ${result.order_id} (${today()})\n${lines}\n`);
+    summary.discoveries_appended = result.discoveries.length;
+  }
+
+  // 4. Verdict bookkeeping (old evaluator B.0/B.2/B.2b) — judge returns data, ingest writes.
+  if (result.verdict) {
+    const evalDir = join(local, "evaluation");
+    mkdirSync(evalDir, { recursive: true });
+    if (result.verdict.criteria?.length) {
+      const target = result.order_id.split("/")[1] || "run";
+      const ledger = join(evalDir, `.verdicts-${target}.jsonl`);
+      let run = 1;
+      if (existsSync(ledger)) {
+        const prior = readFileSync(ledger, "utf8").trim().split(/\n/).filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+        run = prior.reduce((mx, r) => Math.max(mx, r.run || 0), 0) + 1;
+      }
+      const lines = result.verdict.criteria.map((c) => JSON.stringify({
+        run, dimension: c.dimension || "spec-conformance", criterion: c.criterion,
+        verdict: c.verdict, confidence: c.confidence, reprobed: !!c.reprobed,
+        evidence: c.evidence || "", at: new Date().toISOString(),
+      })).join("\n");
+      appendFileSync(ledger, lines + "\n");
+      summary.verdict_lines = result.verdict.criteria.length;
+    }
+    for (const ref of result.verdict.refuted || []) {
+      const path = findTaskFile(cwd, slug, ref.task_id);
+      if (!path) continue;
+      let body = readFileSync(path, "utf8");
+      const r = setCheckbox(body, ref.ac, false);
+      if (r.hit) summary.refuted_unticked++;
+      body = setFrontmatter(r.body, "eval_verdict", "fail");
+      body = setFrontmatter(body, "eval_at", today());
+      writeFileSync(path, body);
+    }
+  }
+
+  // 5. Escalates → a queue file the orchestrator adjudicates via advisor-protocol.
+  if (result.escalates?.length) {
+    const escDir = join(local, "escalates");
+    mkdirSync(escDir, { recursive: true });
+    const out = join(escDir, `${result.order_id.split("/")[1] || "run"}.json`);
+    writeFileSync(out, JSON.stringify(result.escalates, null, 2) + "\n");
+    summary.escalates_queued = result.escalates.length;
+  }
+
+  return summary;
+}
+
+// ---------------------------------------------------------------------------
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "ingest-result.mjs <result.json> [--cwd <dir>]",
+  _: { arity: 1, max: 1, name: "result.json" },
+  cwd: { type: "path" },
+};
+
+const isMainModule = isMain(import.meta.url);
+if (isMainModule) {
+  const args = runArgs(ARGV_SPEC);
+  const file = args._[0];
+  const cwd = resolve(args.cwd || process.cwd());
+
+  let result;
+  try { result = JSON.parse(readFileSync(resolve(file), "utf8")); }
+  catch (e) { console.error(`  ✗ result unreadable: ${e.message}`); process.exit(1); }
+
+  const { valid, errors } = validate(result, RESULT_SCHEMA);
+  if (!valid) {
+    console.error("ingest-result: result rejected — a malformed result never mutates the board:");
+    for (const e of errors) console.error(`  ✗ ${e}`);
+    process.exit(1);
+  }
+  const s = applyResult(result, { cwd });
+  console.log(`✅ ingested ${result.order_id} — tasks: [${s.tasks_updated.join(", ")}] · ACs ticked: ${s.acs_ticked} · unblocked: [${s.unblocked.join(", ")}] · discoveries: ${s.discoveries_appended} · verdict lines: ${s.verdict_lines} · refuted un-ticked: ${s.refuted_unticked} · escalates queued: ${s.escalates_queued}`);
+  if (s.escalates_queued) process.exitCode = 0; // escalates are data, not failure
+}

package/skills/tech-lead/scripts/init-run.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+// GATE L0.1 — START THE RUN. The orchestrator's first tool call, before any prose.
+//
+// WHY THIS EXISTS (measured, not theorized).
+//
+// On the SDD harness benchmark (`sdd-harness-bench`, F2, Haiku 4.5, n=5, zero variance) the
+// orchestrator was dispatched with a valid spec and did this:
+//
+//     TOOL   Skill(tech-lead, "--unattended --rounds 3\n\n# F2 — category budgets…")
+//     TEXT   "The tech-lead skill is orchestrating the full Shape Up harness. It will: 1. …"
+//     FINAL  (same text — session ends)
+//
+// It loaded a 450-line instruction file describing eleven gates and returned a description of
+// eleven gates. No code, no board, no gate artifacts — and prose that reads exactly like a
+// successful run. 29% acceptance, 10 escaped defects, five times out of five.
+//
+// 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
+//     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.
+//
+// The root cause of BOTH misses is the same: **whether a run had started was not a fact on
+// disk.** It was an inference from artifacts that only appear later. So this script exists to
+// make starting a run a mechanical event with a receipt, at t=0:
+//
+//   • It is the orchestrator's FIRST action, stated in the first screen of SKILL.md. Everything
+//     emitted before a tool call is narration surface; this shrinks that surface to zero.
+//   • It writes `receipt.json` — the fact "this run started, with THIS intake, at THIS time".
+//     `gate-zerowork.mjs` (Stop) blocks a session that invoked tech-lead and produced no
+//     receipt. Narration now has a detector that does not depend on what the narration says.
+//   • It writes `active-scope`, which is the precondition every downstream guard already
+//     assumed someone had established. Previously that someone was the model, deciding to.
+//     An invariant that depends on the model choosing to establish it is a prompt, not a gate.
+//
+// It also HASHES the intake into the receipt. The benchmark's first (wrong) diagnosis was that
+// requirement text was dropped on the hand-off. It was not, on re-run — but nothing on disk
+// could have settled that either way. Now it can: the intake that reached the orchestrator is
+// recorded 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]
+//
+// 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
+// turns fighting its own command line instead of starting. Measured, on this project's benchmark.
+//
+//   --auto-level    interactive | auto | unattended   (default: interactive)
+//   --lens          lite | standard | cross-context   (default: standard)
+//   --max-rounds N  outer circuit breaker             (default: 3)
+//   --attempts N    inner per-scope T0 budget         (default: 5)
+//   --spec-folder   SHARED spec deliverable path      (default: shapeup/<slug>/spec/)
+//   --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)
+//   --cwd           project root                      (default: process.cwd())
+//   --force         re-init over an existing run receipt
+//
+// Prints a JSON receipt on stdout. Exit 0 on success, 2 on a usage error, 3 when a live run
+// already exists and --force was not given.
+//
+// EXIT 3 IS THE RESUME PATH, not a dead end. It prints the file-derived RunSnapshot for the run that
+// is already open — slug, status, round, attempt, board counts, pending orders — so the orchestrator
+// continues from the phase the files report instead of re-opening the run or restarting the pipeline
+// from phase 1. It previously said "Resume it (`--from <slug>`)", and `--from` is a /tech-lead flag
+// 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 { 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 { deriveSnapshot } from "./run-snapshot.mjs";
+import { localRoot, activeScope, globLocal, globShared } from "./lib/paths.mjs";
+
+export const RECEIPT_VERSION = 1;
+
+const AUTO_LEVELS = new Set(["interactive", "auto", "unattended"]);
+const LENSES = new Set(["lite", "standard", "cross-context"]);
+
+/** Slugify a free-text feature name into a filesystem-safe run id. */
+export function slugify(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "run";
+}
+
+export function digest(text) {
+  return createHash("sha256").update(String(text ?? ""), "utf8").digest("hex");
+}
+
+/**
+ * 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 }) {
+  const intakeText = String(intake ?? "");
+  return {
+    receipt_version: RECEIPT_VERSION,
+    type: "harness-run-receipt",
+    slug,
+    started_at: startedAt,
+    intake_sha256: digest(intakeText),
+    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,
+    config,
+  };
+}
+
+/** The `harness-run.md` frontmatter block, per references/ledger-schema.md. */
+export function runFrontmatter({ slug, config, startedAt }) {
+  return [
+    "---",
+    "type: harness-run",
+    `feature: ${slug}`,
+    `spec_folder: ${config.spec_folder}`,
+    `lens: ${config.lens}`,
+    "eval_dimensions: [spec-conformance]",
+    `max_rounds: ${config.max_rounds}`,
+    `attempt_budget: ${config.attempt_budget}`,
+    `wall_clock_budget_s: ${config.wall_clock_budget_s ?? "~"}`,
+    `auto_level: ${config.auto_level}`,
+    `gate_answers: ${config.gate_answers ?? "~"}`,
+    `lane: ${config.fit?.lane ?? "full"}${config.fit?.overridden_from ? ` (overridden from ${config.fit.overridden_from})` : ""}`,
+    "status: orienting",
+    "final_verdict: ~",
+    "rounds_used: 0",
+    "discovered_rounds: 0",
+    "deploy: ~",
+    `started_at: ${startedAt}`,
+    "closed_at: ~",
+    "---",
+    "",
+    `# Harness run — ${slug}`,
+    "",
+    "Opened by `init-run.mjs` (GATE L0.1). The tech lead is the sole writer from here on.",
+    "",
+    "## Rounds",
+    "",
+    "| Phase | Round | Result | Duration | Notes |",
+    "|-------|-------|--------|----------|-------|",
+    "| Init  | —     | run opened | — | intake recorded, receipt written |",
+    "",
+    "## Decisions log",
+    "",
+    "| Gate | Decision | Source | Note |",
+    "|------|----------|--------|------|",
+    "",
+  ].join("\n");
+}
+
+// ---- 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) ' +
+         "[--slug <slug>] [--auto-level interactive|auto|unattended] [--lens <lens>] " +
+         "[--max-rounds N] [--attempts N] [--spec-folder <dir>] [--gate-answers <preset|path>] " +
+         "[--lane full|tiny] [--tiny] [--wall-clock-budget <seconds>] [--cwd <dir>] [--force]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  cwd: { type: "path" },
+  "intake-text": { type: "str" },
+  "intake-file": { type: "str" }, // "-" is a legitimate value here (stdin), so not type "path"
+  "intake-stdin": { type: "flag" },
+  slug: { type: "str" },
+  "auto-level": { type: "str" },
+  lens: { type: "str" },
+  "max-rounds": { type: "int", min: 1 },
+  attempts: { type: "int", min: 1 },
+  "spec-folder": { type: "path" },
+  "gate-answers": { type: "str" },
+  lane: { type: "str" },
+  tiny: { type: "flag" },
+  "wall-clock-budget": { type: "int", min: 1 },
+  force: { type: "flag" },
+};
+
+function fail(code, msg) {
+  console.error(msg);
+  process.exit(code);
+}
+
+export function main() {
+  const args = runArgs(ARGV_SPEC);
+  const cwd = args.cwd || process.cwd();
+
+  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
+  // file literally named "-". (Measured: an agent tried exactly this on its second attempt.)
+  if (args.intakeStdin || intakeFile === "-") {
+    try { intake = readFileSync(0, "utf8"); } catch { fail(2, "--intake-stdin: nothing on stdin"); }
+  } else if (intakeFile) {
+    const p = intakeFile.startsWith("/") ? intakeFile : join(cwd, intakeFile);
+    if (!existsSync(p)) fail(2, `--intake-file not found: ${p}`);
+    intake = readFileSync(p, "utf8");
+  }
+  if (!intake || !intake.trim()) {
+    fail(2, [
+      "✋ init-run: no intake. Pass --intake-text \"<the requirement>\" or --intake-file <path>.",
+      "",
+      "An orchestrator with no spec has nothing to orchestrate — this is the same precondition",
+      "GATE L0.0 (hooks/gate-intake.mjs) enforces at dispatch, re-checked here where the run is",
+      "actually opened.",
+    ].join("\n"));
+  }
+
+  const slug = (args.slug ?? null) || slugify(intake.split("\n").find((l) => l.trim()) || "run");
+
+  const auto_level = args.autoLevel ?? "interactive";
+  if (!AUTO_LEVELS.has(auto_level)) fail(2, `--auto-level must be one of: ${[...AUTO_LEVELS].join(", ")}`);
+  const lens = args.lens ?? "standard";
+  if (!LENSES.has(lens)) fail(2, `--lens must be one of: ${[...LENSES].join(", ")}`);
+
+  const config = {
+    auto_level,
+    lens,
+    max_rounds: args.maxRounds ?? 3,
+    attempt_budget: args.attempts ?? 5,
+    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
+    // 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.
+    fit: (() => {
+      const auto = decideLane({ intake, files: treeSize(cwd) });
+      const forced = (args.lane ?? null) || (args.tiny ? "tiny" : null);
+      return forced && forced !== auto.lane
+        ? { ...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
+    // keeps every existing run behaving exactly as before. Set it in any lane with a hard clock
+    // — CI, a benchmark, an overnight run — so the harness trips its own breaker and ships what
+    // is green, instead of being killed from outside and shipping nothing.
+    wall_clock_budget_s: args.wallClockBudget ?? null,
+  };
+
+  const runRoot = localRoot(cwd, slug);
+  const receiptPath = join(runRoot, "receipt.json");
+  // A RUN IS ALREADY OPEN. This is the resume path, and it used to be a dead end.
+  //
+  // The refusal is right: silently re-initialising would discard the round history the circuit
+  // breaker counts against. What was wrong was the instruction it gave — "Resume it (`--from
+  // <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).
+  //
+  // Measured consequence, on the SDD harness benchmark's F4 handoff: a fresh session in a workspace
+  // with an open run spent 82–120 turns before its first write, largely on forensics against this
+  // step, and closed 0/3 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
+  // 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".
+  if (existsSync(receiptPath) && !args.force) {
+    let resume = null;
+    try { resume = deriveSnapshot(cwd); } catch { /* a broken run must still produce the refusal */ }
+    fail(3, [
+      `✋ init-run: a run is ALREADY OPEN — receipt exists at ${receiptPath}.`,
+      "",
+      "Do NOT re-initialise and do NOT restart the pipeline from phase 1. Re-opening would discard",
+      "the round history the circuit breaker counts against, and the board, ledger and receipt below",
+      "already hold the run's real state. RESUME from the phase these files report.",
+      "",
+      resume
+        ? `RESUME STATE (derived from files, never from memory):\n${JSON.stringify(resume, null, 2)}`
+        : [
+            "The receipt exists but no run state could be derived, which means the run root is",
+            "incomplete. Inspect it before deciding:",
+            `  ls -R ${runRoot}`,
+          ].join("\n"),
+      "",
+      "To re-derive this at any time:",
+      "  node <plugin>/skills/tech-lead/scripts/run-snapshot.mjs --cwd <dir>",
+      "To abandon the open run and start over, deliberately: --force",
+    ].join("\n"));
+  }
+
+  const startedAt = new Date().toISOString();
+  const receipt = buildReceipt({ slug, intake, config, startedAt });
+
+  mkdirSync(runRoot, { recursive: true });
+  mkdirSync(join(runRoot, "orders"), { recursive: true });
+  mkdirSync(join(runRoot, "results"), { recursive: true });
+  mkdirSync(join(runRoot, "discovery"), { recursive: true });
+
+  // The intake, verbatim. So "the spec was dropped on the hand-off" is a checkable claim.
+  writeFileSync(join(runRoot, "intake.md"), intake.endsWith("\n") ? intake : intake + "\n", "utf8");
+  writeFileSync(receiptPath, JSON.stringify(receipt, null, 2) + "\n", "utf8");
+  writeFileSync(join(runRoot, "harness-run.md"), runFrontmatter({ slug, config, startedAt }), "utf8");
+
+  // The pointer every downstream guard reads to answer "is a run active?".
+  const pointer = activeScope(cwd);
+  mkdirSync(dirname(pointer), { recursive: true });
+  writeFileSync(pointer, JSON.stringify({ slug, started_at: startedAt }, null, 2) + "\n", "utf8");
+
+  console.log(JSON.stringify({
+    ok: true,
+    slug,
+    run_root: globLocal(slug),
+    receipt: globLocal(slug, "receipt.json"),
+    intake_sha256: receipt.intake_sha256,
+    intake_chars: receipt.intake_chars,
+    config,
+    next: "GATE L0 — pin the run config, emit the gate block, then ORIENT.",
+  }, null, 2));
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}