@bluewombat/slots 0.10.0 → 0.11.0

package/gates/ci-green.mjs

@@ -20,6 +20,14 @@ import { emitVerdict, GATE_FLAGS, ownArgv, take } from "@bluewombat/slot-kit";
 //                        to it failed only at the first assembly of a real run
 //   --require-checks     wait for a check to appear; without it, a commit with no
 //                        check at all passes
+//   --require-check NAME repeatable. The check run (or status context) called
+//                        exactly NAME must exist and have succeeded. A `skipped` or
+//                        `neutral` one is not a pass, which is what the general
+//                        rule lets through (a job skipped for want of its secrets
+//                        would let the line go green): it is refused. One not
+//                        there yet is waited for like --require-checks, and at the
+//                        ceiling the CI did not answer. A matrix is one check per
+//                        cell, named as GitHub names it ("e2e (chrome)"): list each one.
 //
 // It also receives `--timeout-ms` from Implementer: the ceiling it will be
 // killed at. A Gate that waits on a CI it does not run must not wait to be cut
@@ -38,6 +46,7 @@ if (!options.ok) {
   process.exit(0);
 }
 const apiBase = options.apiBase;
+const requireCheck = options.requireCheck;
 
 if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
   emitVerdict("fail-blocking", "ci-green needs a git workspace.");
@@ -93,6 +102,25 @@ for (;;) {
     await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
     continue;
   }
+  const required = judgeRequired(checks.named);
+  if (required.refused.length > 0) {
+    // A check that settled without running says nothing of the work, and nothing
+    // the work could change (a job skipped for want of its secrets): a person's,
+    // not an agent's to repair.
+    emitVerdict(
+      "fail-blocking",
+      `${required.refused.join("\n")}\nThis is not a refusal of the work: the CI did not run a check the Project requires, and no change to the work makes it run.`,
+    );
+    process.exit(0);
+  }
+  if (required.missing.length > 0) {
+    // Same window as above, for a check the Project named.
+    if (Date.now() >= stopAt) {
+      stopWaiting(pull, `required check ${quoted(required.missing)} has not appeared`, true);
+    }
+    await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
+    continue;
+  }
   if (checks.running === 0) {
     emitVerdict("pass");
     process.exit(0);
@@ -106,6 +134,40 @@ for (;;) {
   await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
 }
 
+/**
+ * What `--require-check` asks of the checks read: each name must have a
+ * success. A name not there yet is `missing` (the CI may still create it); one
+ * still running is waited for with the rest; one that settled without success
+ * (`skipped`, `neutral`) is `refused`: nothing will turn it green, and no change
+ * to the work can, so it goes to a person.
+ *
+ * @param {Map<string, string[]>} named every check by name, with its outcome:
+ *   `success`, `pending`, or the conclusion it settled on
+ * @returns {{ missing: string[]; refused: string[] }}
+ */
+function judgeRequired(named) {
+  /** @type {string[]} */
+  const missing = [];
+  /** @type {string[]} */
+  const refused = [];
+  for (const name of requireCheck) {
+    const outcomes = named.get(name);
+    if (outcomes === undefined) {
+      missing.push(name);
+    } else if (!outcomes.includes("success") && !outcomes.includes("pending")) {
+      refused.push(
+        `${name}: ${outcomes[0]}. It is required to succeed, and a check that did not run is not a pass.`,
+      );
+    }
+  }
+  return { missing, refused };
+}
+
+/** @param {readonly string[]} names */
+function quoted(names) {
+  return names.map((name) => `"${name}"`).join(", ");
+}
+
 /**
  * The moment to stop waiting: a margin before Implementer's ceiling (5 %, between
  * 2 and 30 seconds, and at most half of it), so the verdict is out before the
@@ -153,7 +215,7 @@ function stopWaiting(pr, what, never = false) {
 
 /**
  * @param {readonly string[]} tokens
- * @returns {{ ok: true; remote: string; apiBase: string; pollMs: number; tokenEnv: string; requireChecks: boolean } | { ok: false; reason: string }}
+ * @returns {{ ok: true; remote: string; apiBase: string; pollMs: number; tokenEnv: string; requireChecks: boolean; requireCheck: string[] } | { ok: false; reason: string }}
  */
 function parseOwnArgv(tokens) {
   let remote = "origin";
@@ -161,6 +223,8 @@ function parseOwnArgv(tokens) {
   let pollMs = 15_000;
   let tokenEnv;
   let requireChecks = false;
+  /** @type {string[]} */
+  const requireCheck = [];
   for (let i = 0; i < tokens.length; i++) {
     const token = tokens[i];
     if (token === "--require-checks") {
@@ -176,6 +240,8 @@ function parseOwnArgv(tokens) {
       remote = value;
     } else if (token === "--api-base") {
       apiBase = value.replace(/\/+$/, "");
+    } else if (token === "--require-check") {
+      requireCheck.push(value);
     } else if (token === "--token-env") {
       tokenEnv = value;
     } else if (token === "--poll-ms") {
@@ -195,7 +261,7 @@ function parseOwnArgv(tokens) {
         "ci-green needs --token-env NAME: the environment variable holding a token that can read the checks (the same one @bluewombat/manager-github's tokenEnv names, never GITHUB_TOKEN).",
     };
   }
-  return { ok: true, remote, apiBase, pollMs, tokenEnv, requireChecks };
+  return { ok: true, remote, apiBase, pollMs, tokenEnv, requireChecks, requireCheck };
 }
 
 /**
@@ -269,12 +335,25 @@ async function readChecks(sha) {
   // on the same commit: same name, same log. Said once.
   const seen = new Set();
   let running = 0;
+  /** @type {Map<string, string[]>} */
+  const named = new Map();
+  /**
+   * @param {unknown} name
+   * @param {string} outcome
+   */
+  const note = (name, outcome) => {
+    if (typeof name === "string") {
+      named.set(name, [...(named.get(name) ?? []), outcome]);
+    }
+  };
   for (const entry of checkRuns) {
     const run = record(entry) ?? {};
     if (run.status !== "completed") {
       running += 1;
+      note(run.name, "pending");
       continue;
     }
+    note(run.name, String(run.conclusion));
     if (
       run.conclusion === "success" ||
       run.conclusion === "neutral" ||
@@ -293,6 +372,7 @@ async function readChecks(sha) {
   // and where it said more is all there is.
   for (const entry of statuses) {
     const status = record(entry) ?? {};
+    note(status.context, status.state === "pending" ? "pending" : String(status.state));
     if (status.state === "pending") {
       running += 1;
       continue;
@@ -310,7 +390,7 @@ async function readChecks(sha) {
     );
     failed.push([heading, ...more].join("\n"));
   }
-  return { total: checkRuns.length + statuses.length, running, failed };
+  return { total: checkRuns.length + statuses.length, running, failed, named };
 }
 
 /**

package/gates/feature-tests.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  ownArgv,
+  parseOptions,
+  take,
+  textOption,
+} from "@bluewombat/slot-kit";
+import { parseJunit, scenarioOf } from "../lib/junit.mjs";
+import { createOutputTail } from "../lib/output-tail.mjs";
+
+// The tests of a Feature, run on the assembled Feature line: does the Feature do what the
+// operator agreed it should? Only the scenarios of this Feature run, not the Project's whole suite.
+//
+// Nothing here knows a stack. The Project supplies one command, run in the workspace through the
+// shell, and the Gate owns the rest: running, comparing.
+//
+// --run COMMAND (required): runs the tests of the Feature and writes a JUnit XML report. `{ids}`
+//   stands for the scenario ids of the manifest joined with "|" (a regular expression:
+//   `pnpm test --grep "{ids}"`), `{junit}` for the path the report must be written to.
+// --manifest PATH: the scenarios of the Feature. Default feature-tests/scenarios.json: a JSON
+//   array of ids, or { "scenarios": [ "S1" | { "id": "S1", "title": "…" } ] }.
+// --junit PATH: where --run writes its report. Default feature-tests/results/junit.xml. Removed
+//   before the run.
+// --max-run-ms N: the most the whole Gate may take. Default 600000 (10 minutes), and never more
+//   than the Gate's own ceiling.
+//
+// A scenario is a manifest id; each test carries its id in its name. The comparison is exact: an
+// id with no test, a test with no id, or a test the runner skipped is a failure.
+//
+// Verdicts: pass; fail-retryable for a red run (a wrong test is its author's to fix, a wrong
+// application the producer's: what the caller does with the report is its own rule); fail-blocking for what no change to the application fixes: a missing manifest,
+// a run that writes no report or outlives its ceiling.
+
+const cwd = process.cwd();
+const KEEP_BYTES = 12_000;
+const MARGIN_MS = 5_000;
+const MIN_PHASE_MS = 1_000;
+const REPORT_CHARS = 8_000;
+
+const parsed = parseOptions(
+  ownArgv(process.argv, GATE_FLAGS),
+  {
+    "--run": {},
+    "--manifest": { fallback: "feature-tests/scenarios.json" },
+    "--junit": { fallback: "feature-tests/results/junit.xml" },
+    "--max-run-ms": { fallback: "600000" },
+  },
+  "feature-tests",
+);
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", parsed.reason);
+  process.exit(0);
+}
+const runTemplate = textOption(parsed.values, "run");
+if (runTemplate === undefined || runTemplate.trim().length === 0) {
+  emitVerdict(
+    "fail-blocking",
+    'feature-tests needs --run "<command>". The Project supplies the command that runs the tests.',
+  );
+  process.exit(0);
+}
+const maxRunMs = positive(textOption(parsed.values, "maxRunMs"));
+if (maxRunMs === undefined) {
+  emitVerdict("fail-blocking", "feature-tests: --max-run-ms takes a positive integer.");
+  process.exit(0);
+}
+const manifestPath = inWorkspace(textOption(parsed.values, "manifest") ?? "");
+const junitPath = inWorkspace(textOption(parsed.values, "junit") ?? "");
+
+const manifest = readManifest();
+if (typeof manifest === "string") {
+  emitVerdict("fail-blocking", manifest);
+  process.exit(0);
+}
+// Typed apart from the early exit above: the functions below are hoisted, and a narrowing does not reach them.
+/** @type {string[]} */
+const ids = manifest;
+
+const ceilingMs = Number(take(process.argv, "--timeout-ms"));
+const budgetMs =
+  Number.isFinite(ceilingMs) && ceilingMs > 0
+    ? Math.min(maxRunMs, Math.max(MIN_PHASE_MS, ceilingMs - MARGIN_MS))
+    : maxRunMs;
+
+const [verdict, report] = await judge();
+emitVerdict(/** @type {"pass" | "fail-retryable" | "fail-blocking"} */ (verdict), report);
+process.exit(0);
+
+/** @returns {Promise<[string, string]>} */
+async function judge() {
+  rmSync(junitPath, { force: true });
+  const command = runTemplate?.replaceAll("{ids}", ids.join("|")).replaceAll("{junit}", junitPath);
+  const run = await runShell(/** @type {string} */ (command), budgetMs);
+  if (run.timedOut) {
+    return ["fail-blocking", timeoutReport(run.output)];
+  }
+  const results = readResults();
+  if (typeof results === "string") {
+    return run.code === 0
+      ? ["fail-blocking", results]
+      : ["fail-retryable", `${results}\n${exitLine(run)} End of its output:\n${run.output}`];
+  }
+  const failing = failingOf(results);
+  if (failing.length > 0) {
+    return ["fail-retryable", redReport(results, failing)];
+  }
+  const foreign = results.cases.filter((c) => scenarioOf(c.name, ids) === undefined);
+  if (foreign.length > 0) {
+    return [
+      "fail-retryable",
+      [
+        `feature-tests: ${foreign.length} test(s) carry no scenario id of the manifest (${ids.join(", ")}): only the scenarios of the Feature run.`,
+        ...foreign.map((c) => `  ${c.name}`),
+        "Every test names its scenario id, and --run must run the ids of the manifest only ({ids}).",
+      ].join("\n"),
+    ];
+  }
+  return [
+    "pass",
+    `feature-tests: ${ids.length} scenario(s) of the feature ran and passed: ${ids.join(", ")}.`,
+  ];
+}
+
+/**
+ * @typedef {{ cases: import("../lib/junit.mjs").TestCase[] }} Result
+ */
+
+/** @returns {Result | string} */
+function readResults() {
+  if (!existsSync(junitPath)) {
+    return `The run wrote no JUnit report at ${junitPath}. --run must write one there ({junit}).`;
+  }
+  const cases = parseJunit(readFileSync(junitPath, "utf8"));
+  if (cases.length === 0) {
+    return `The JUnit report at ${junitPath} holds no test case.`;
+  }
+  return { cases };
+}
+
+/** The scenario ids that are not a pass: failed, skipped, or never run. */
+function failingOf(/** @type {Result} */ results) {
+  return ids.filter((id) => {
+    const mine = results.cases.filter((c) => scenarioOf(c.name, ids) === id);
+    return mine.length === 0 || mine.some((c) => c.status !== "passed");
+  });
+}
+
+function redReport(/** @type {Result} */ results, /** @type {string[]} */ failing) {
+  const lines = [
+    `feature-tests: ${failing.length} of ${ids.length} scenario(s) failed on the assembled feature: ${failing.join(", ")}.`,
+  ];
+  for (const id of failing) {
+    const mine = results.cases.filter((c) => scenarioOf(c.name, ids) === id);
+    if (mine.length === 0) {
+      lines.push(`${id} — no test ran for it.`);
+      continue;
+    }
+    for (const c of mine.filter((m) => m.status !== "passed")) {
+      lines.push(`${id} — ${c.name}`);
+      if (c.status === "skipped") {
+        lines.push("  skipped: a skipped scenario is not a passing one.");
+        continue;
+      }
+      lines.push(`  at: ${firstFrame(c.detail) ?? "(no step given)"}`);
+      lines.push(`  message: ${c.message.slice(0, 600)}`);
+    }
+  }
+  lines.push(`Report: ${junitPath}.`);
+  const text = lines.join("\n");
+  return text.length <= REPORT_CHARS ? text : `${text.slice(0, REPORT_CHARS)}\n…`;
+}
+
+/** The first stack line that is the test's own, where a step failed. */
+function firstFrame(/** @type {string} */ detail) {
+  return detail
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => /^at\s|\.(spec|test)\.[cm]?[jt]sx?:\d+/.test(line));
+}
+
+/**
+ * @param {string} command
+ * @param {number} limitMs
+ * @returns {Promise<{ code: number | null, signal: string | null, timedOut: boolean, output: string }>}
+ */
+function runShell(command, limitMs) {
+  return new Promise((done) => {
+    const child = spawn("sh", ["-c", command], {
+      cwd,
+      env: { ...process.env, CI: "true", NO_COLOR: "1", FORCE_COLOR: "0" },
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const tail = createOutputTail(KEEP_BYTES);
+    child.stdout.on("data", (chunk) => tail.push("stdout", chunk));
+    child.stderr.on("data", (chunk) => tail.push("stderr", chunk));
+    let timedOut = false;
+    const timer = globalThis.setTimeout(
+      () => {
+        timedOut = true;
+        killGroup(child);
+      },
+      Math.max(MIN_PHASE_MS, limitMs),
+    );
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      done({ code: 127, signal: null, timedOut: false, output: `cannot start: ${error.message}` });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      done({ code, signal, timedOut, output: tail.text() });
+    });
+  });
+}
+
+/** @param {import("node:child_process").ChildProcess} child */
+function killGroup(child) {
+  try {
+    if (child.pid !== undefined) {
+      process.kill(-child.pid, "SIGKILL");
+    }
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+function timeoutReport(/** @type {string} */ output) {
+  return [
+    `The run did not finish within the ${Math.round(budgetMs / 1000)}s this Gate may take, and was stopped.`,
+    "A person decides: the tests hang.",
+    output.length > 0 ? `Last output:\n${output}` : "It printed nothing.",
+  ].join("\n");
+}
+
+function exitLine(/** @type {{ code: number | null, signal: string | null }} */ run) {
+  return run.signal === null ? `The run exited ${run.code}.` : `The run got ${run.signal}.`;
+}
+
+/** @returns {string[] | string} The ids, or why the manifest is not usable. */
+function readManifest() {
+  if (!existsSync(manifestPath)) {
+    return `The scenarios manifest ${manifestPath} does not exist. The feature-test Ticket writes it: one id per scenario.`;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    return `The scenarios manifest ${manifestPath} is not JSON: ${error instanceof Error ? error.message : error}`;
+  }
+  const list = Array.isArray(raw) ? raw : raw?.scenarios;
+  if (!Array.isArray(list)) {
+    return `The scenarios manifest ${manifestPath} must be an array of ids, or { "scenarios": [...] }.`;
+  }
+  const found = list.map((entry) => (typeof entry === "string" ? entry : entry?.id));
+  if (found.some((id) => typeof id !== "string" || id.trim().length === 0)) {
+    return `Every scenario of ${manifestPath} needs a non-empty id.`;
+  }
+  const unique = [...new Set(found.map((id) => id.trim()))];
+  if (unique.length !== found.length) {
+    return `The scenarios manifest ${manifestPath} lists an id twice.`;
+  }
+  if (unique.length === 0) {
+    return `The scenarios manifest ${manifestPath} lists no scenario: there is nothing to prove.`;
+  }
+  return unique;
+}
+
+function positive(/** @type {string | undefined} */ text) {
+  const value = Number(text);
+  return Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function inWorkspace(/** @type {string} */ path) {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}

package/gates/tests-only.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { emitVerdict, GATE_FLAGS, ownArgv, pathMatchesGlob } from "@bluewombat/slot-kit";
+
+// Fail-retryable when the workspace changed a path that matches none of the globs: the one place
+// the workspace may be written is what the globs name (the tests and their manifest). The other
+// side of `sensitive-path`, which names what may not be touched; a Project whose tests sit among its
+// code (`**/*.test.ts` in every package) cannot say "everything but" with globs that only deny.
+// Remaining argv after Implementer's flags are the globs.
+//
+// What counts is what a fold can carry: tracked paths that differ from HEAD (added, modified,
+// deleted, renamed) and new paths .gitignore does not exclude.
+
+const cwd = process.cwd();
+const globs = ownArgv(process.argv, GATE_FLAGS).filter((token) => token.length > 0);
+
+if (globs.length === 0) {
+  emitVerdict("fail-blocking", "tests-only needs at least one glob.");
+  process.exit(0);
+}
+
+const status = spawnSync(
+  "git",
+  ["-C", cwd, "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+  {
+    encoding: "utf8",
+  },
+);
+if (status.status !== 0) {
+  emitVerdict("fail-blocking", `tests-only needs a git workspace: ${status.stderr.trim()}`);
+  process.exit(0);
+}
+
+/** @type {Set<string>} */
+const changed = new Set();
+const fields = status.stdout.split("\0");
+for (let i = 0; i < fields.length; i++) {
+  const entry = fields[i] ?? "";
+  if (entry.length < 4) {
+    continue;
+  }
+  changed.add(entry.slice(3));
+  // A rename or a copy carries the old path in the next field.
+  if (entry[0] === "R" || entry[0] === "C") {
+    const old = fields[++i];
+    if (old !== undefined && old.length > 0) {
+      changed.add(old);
+    }
+  }
+}
+
+const outside = [...changed]
+  .map((path) => path.replaceAll("\\", "/"))
+  .filter((path) => !globs.some((glob) => pathMatchesGlob(path, glob)))
+  .sort();
+
+if (outside.length > 0) {
+  emitVerdict(
+    "fail-retryable",
+    `Paths changed that are not tests or their manifest (${globs.join(", ")}):\n${outside.join("\n")}`,
+  );
+  process.exit(0);
+}
+
+emitVerdict("pass");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Shipped mason slots: Builders, Gates, publishers, and refreshers a Project names in its config.",
   "keywords": [
@@ -52,7 +52,7 @@
     "test": "tsx --test $(find test -name '*.test.ts')"
   },
   "dependencies": {
-    "@bluewombat/slot-kit": "^0.10.0",
+    "@bluewombat/slot-kit": "^0.11.0",
     "@pinkpuma/deck": "1.1.0"
   }
 }

package/builders/tests.mjs

@@ -1,139 +0,0 @@
-#!/usr/bin/env node
-import {
-  BUILDER_FLAGS,
-  emitFailure,
-  fillPrompt,
-  finishRun,
-  loadPrompt,
-  loadRules,
-  PROMPT_RULES,
-  parseRole,
-  spawnFilled,
-  take,
-  textOption,
-  transcriptArgs,
-} from "@bluewombat/slot-kit";
-import { attemptOf } from "../lib/fill.mjs";
-
-const NAME = "builder tests";
-
-const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
-
-Task:
-{{task}}
-
-YOUR WORK NOW IS TO WRITE THE TESTS OF THIS TASK, AND ONLY THE TESTS. Another agent
-writes the code afterwards and must make your tests pass without editing them. A test it
-cannot pass is not sent back to you: it stops the task and waits for a person. So a test
-you deliver must be one that a correct implementation of the task passes, and you prove
-it before you hand it over (see below).
-
-## The cases
-
-- The task has a "Tests" section: write one test per case of it, in the file and the
-  framework it names (or the ones this repository already uses), each named after the
-  case it covers. Test the behaviour at the seam the section names, not how it is built.
-- The task has no "Tests" section: do not look for one elsewhere. Derive the cases from
-  its acceptance criteria ("Done when" or the like), one case per criterion, and name each
-  test after the criterion and the identifiers it carries. A criterion that describes two
-  sets of data (sixty rows for a page, more than a cap for the cap) is two cases, never one
-  test with two batches of data.
-- Do not write the behaviour. If the interface under test does not exist yet, create the
-  minimal stub — the name and signature the task gives, a body that does nothing useful —
-  so that the tests compile and fail on what they check, not on a missing import.
-- Add or update no other test, and no production code beyond the stubs.
-
-## How a test stays passable
-
-- One data set per test, seeded at the top. Every expectation derives from that set: the
-  rows a filter keeps, the order they take, the page a limit and an offset cut out of it.
-  Write the expected count from the seeded data, not as a figure recounted by hand.
-- To observe a bound, seed past it: a cap of 200 is only visible with more than 200 rows
-  that the filters keep. "At most N" is asserted with \`<= N\`, or by seeding more than N;
-  never as exactly N when fewer exist.
-
-## Prove them: red, green, red
-
-A test you have only seen fail proves nothing about itself: a test no implementation
-could pass fails exactly the same way. The tests must FAIL now, because the behaviour is
-missing, and you prove every one of them passable before you finish:
-
-1. **Red.** Run the tests. Each fails on an assertion (not on an import, a type, a syntax
-   error).
-2. **Green.** In the stub bodies — the same files, no new file — write the shortest
-   implementation of the task that makes every test pass: naive, in memory, unoptimised;
-   it is thrown away. Run the tests. A test still red here is wrong, not the task: fix its
-   data or its expectation (never drop a case, never replace a value the task gives with a
-   looser one), and run again until all are green.
-3. **Red again.** Put every stub body back to no behaviour. Run the tests: each fails
-   again on an assertion. Leave the tree in this state.
-
-Leave no trace of the green step: no helper, no import, no comment. The only non-test
-lines you deliver are the stubs.
-
-{{history}}
-
-## When you cannot act
-
-If the cases are missing, or contradict the task or the code, do not invent them. Change
-nothing and end your final message with exactly one line:
-
-MASON_BLOCKED: <what is missing, in one line>
-
-A person reads that line and decides. It is a correct answer, not a failure.
-
-Rules of this run:
-{{rules}}
-`;
-
-// A retry carries the refusal in --history; the flags themselves are consumed so the
-// role options see only their own.
-take(process.argv, "--report");
-take(process.argv, "--report-from");
-
-const intention = (take(process.argv, "--intention") ?? "").trim();
-if (intention.length === 0) {
-  emitFailure("fail-blocking", "The Builder received no --intention.");
-  process.exit(1);
-}
-
-const parsed = parseRole(process.argv, BUILDER_FLAGS, NAME);
-if (!parsed.ok) {
-  emitFailure("fail-blocking", parsed.reason);
-  process.exit(1);
-}
-
-const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
-if (!template.ok) {
-  emitFailure("fail-blocking", template.reason);
-  process.exit(1);
-}
-const rules = loadRules(parsed.options, PROMPT_RULES);
-if (!rules.ok) {
-  emitFailure("fail-blocking", rules.reason);
-  process.exit(1);
-}
-
-const rendered = fillPrompt(
-  template.value,
-  {
-    task: intention,
-    history: (take(process.argv, "--history") ?? "").trim(),
-    rules: rules.value.trim(),
-    id: take(process.argv, "--id") ?? "",
-    attempt: String(attemptOf(process.argv)),
-  },
-  ["task", "rules"],
-  textOption(parsed.options, "promptFile") ?? "built-in template",
-);
-if (!rendered.ok) {
-  emitFailure("fail-blocking", rendered.reason);
-  process.exit(1);
-}
-
-const spawned = await spawnFilled(parsed.runner, rendered.prompt, transcriptArgs(process.argv));
-if (!spawned.ok) {
-  emitFailure("fail-blocking", spawned.reason);
-  process.exit(1);
-}
-finishRun({ run: spawned.run, bin: spawned.about.bin, name: spawned.about.name });