shapeup-sdlc 1.7.0 → 3.0.0

package/{skills/tech-lead/scripts/compile-order.mjs → kernel/compile.mjs}

@@ -13,13 +13,13 @@
 //
 // Usage:
 //   Scope attempt (isolated attempt loop):
-//     node skills/tech-lead/scripts/compile-order.mjs --scope shapeup/<slug>/scopes/<id>.md \
+//     node kernel/harness.mjs compile --scope shapeup/<slug>/scopes/<id>.md \
 //          --round N --attempt M [--cwd <dir>] [--test-cmd "<cmd>"]
 //   Single task (no scope contracts — pre-v0.3.0 boards):
-//     node skills/tech-lead/scripts/compile-order.mjs --task TASK-003 --slug <slug> [--worker task-executor]
-//     node skills/tech-lead/scripts/compile-order.mjs --next --slug <slug>
+//     node kernel/harness.mjs compile --task TASK-003 --slug <slug> [--worker task-executor]
+//     node kernel/harness.mjs compile --next --slug <slug>
 //   Non-build operation (planner/judge/QA dispatches; flag surface → operation + whitelist):
-//     node skills/tech-lead/scripts/compile-order.mjs --operation reconcile --slug <slug> [--round N]
+//     node kernel/harness.mjs compile --operation reconcile --slug <slug> [--round N]
 //          [--worker ba-pitch-analyzer] [--payload '<json>']
 //
 // Output: .shapeup/<slug>/orders/<order-file>.json (schema-validated before write; a
@@ -28,21 +28,25 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
 import { resolve, join, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
-import { validate } from "./validate-envelope.mjs";
-import { readTrials } from "./t0-verify.mjs";
-import { isMain } from "./lib/is-main.mjs";
+import { validate } from "./verify/envelope.mjs";
+import { readTrials } from "./verify/t0.mjs";
 import { runArgs } from "./lib/argv.mjs";
+import { readRunId } from "./lib/paths.mjs";
 // `specDir` is aliased: this module has a local `let specDir` holding the resolved, possibly
 // --spec-overridden directory, and the import is the convention-derived default.
 import {
   tasksDir, specDir as defaultSpecDir, roundLedger, trials, verdictsDir, ordersDir,
-  relShared, globLocal, globShared, relKnowledgeBase,
+  relShared, globLocal, globShared, relKnowledgeBase, resultsDir, scopesDir,
 } from "./lib/paths.mjs";
-import { readContract, SCOPE_CONTRACT } from "./lib/contract-md.mjs";
-import { writeActiveOrder } from "./resume-state.mjs";
+import { readContract, tasksForScope, SCOPE_CONTRACT } from "./lib/contract.mjs";
+import { writeActiveOrder } from "./probe/resume.mjs";
+// The SAME matcher the sandbox hook enforces with. "Is this cited file inside this scope's
+// substrate" has to mean exactly what the guard means, or a bug is addressed to a scope that is
+// then denied the write that fixes it.
+import { matchesAny } from "../hooks/sandbox-guard.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-const ORDER_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "../schemas/work-order.schema.json"), "utf8"));
+const ORDER_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "./../skills/tech-lead/schemas/work-order.schema.json"), "utf8"));
 
 // --- tiny frontmatter reader (scalar keys + [a, b] inline lists) --------------------------
 /**
@@ -72,7 +76,7 @@ export function frontmatter(md) {
  * Parse one TASK-NNN.md file into the task entry a WorkOrder carries.
  * @param {string} path - Absolute path to the task Markdown file.
  * @returns {{id:string, title:string, status:string, priority:number, depends_on:string[],
- *   use_case_refs:string[], body_path:string, acceptance_criteria:Array<string|{text:string,
+ *   use_case_refs:string[], scope_id:string, body_path:string, acceptance_criteria:Array<string|{text:string,
  *   covers:string[]}>}} The task entry. Each acceptance criterion is the checkbox text
  *   byte-identical (so ingest can tick it back); a trailing `(covers: REQ-…)` clause yields
  *   {text, covers} instead of a plain string. `priority` defaults to 999 when unset.
@@ -99,6 +103,7 @@ export function parseTaskFile(path) {
     priority: Number(fm.priority) || 999,
     depends_on: Array.isArray(fm.depends_on) ? fm.depends_on : [],
     use_case_refs: Array.isArray(fm.use_case_refs) ? fm.use_case_refs : [],
+    scope_id: fm.scope_id || "",
     body_path: path,
     acceptance_criteria,
   };
@@ -144,6 +149,25 @@ export function ledgerDecisions(ledgerText, scopeId) {
   return decisions;
 }
 
+/**
+ * Operation → owning worker (mirrors `domain.schema.json#/$defs/Operation` ownership). Lets a
+ * non-build dispatch resolve its worker from the operation alone, without a redundant `--worker`.
+ *
+ * Exported and at module scope so it is ONE table. Every value here must be a member of
+ * `WorkerName`: an operation mapped to a name the enum does not carry compiles an order that fails
+ * its own schema, and the dispatch is then denied by the order gate for a reason that names the
+ * envelope rather than the typo. That parity is checked by the suite, which can only read a table
+ * it can import.
+ */
+export const OP_OWNER = {
+  analyze: "ba-pitch-analyzer", reconcile: "ba-pitch-analyzer",
+  "retrofit-surface": "ba-pitch-analyzer", coverage: "ba-pitch-analyzer",
+  "map-scopes": "scope-architect",
+  wire: "solution-architect", evaluate: "spec-evaluator", orient: "orient",
+  hunt: "qa-edge-hunter", translate: "translator",
+  hammer: "scope-hammer", coach: "coach",
+};
+
 /**
  * Resolve the write-contract (sandbox substrate) for an operation — one whitelist template per
  * operation, so mode/flag differences are enforced by the sandbox hook reading the order's substrate, not trusted to prose.
@@ -281,7 +305,7 @@ export function selectTrialHistory(trials, { scopeId, round } = {}) {
 }
 
 /**
- * The stagnation term of the inner circuit breaker (plan §2.6).
+ * The stagnation term of the inner circuit breaker.
  *
  * `attempt_budget` counts attempts; it cannot see that the last two produced nothing. One term
  * joins it: `no_progress_k` consecutive non-`kept` trials ends the scope early and queues the
@@ -302,6 +326,162 @@ export function stagnation(trials, k = 2) {
   return { stagnant: streak >= k && k > 0, streak, k };
 }
 
+// --- the FAIL verdict's bugs, carried into the round that must fix them ----------------------
+//
+// WHY THE KERNEL OWNS THIS AND NOT THE ORCHESTRATOR (measured twice, two different ways).
+//
+// `WorkOrderPayload.bugs` is defined as "the EVAL report's bug entries for this task — touch
+// nothing else", and AGENTS.md states the regression rule as "bugs + full Test Surface of touched
+// UC". Nothing ever populated it. The orchestrator's first fix threaded the evaluator's findings
+// from memory into the build leg's `payload`, and it could not work, for two independent reasons:
+//
+//   1. A BUILD ORDER TAKES NO PAYLOAD FROM THE CALLER. Build legs override the compile line
+//      (`compile --scope … --round … --attempt …`) because an order is addressed by scope, round
+//      and attempt; only the generic fallback line serialises `--payload`. So the payload object
+//      the orchestrator built for a build leg was constructed, filtered, and dropped on the floor.
+//   2. IT LIVED ONLY IN MEMORY. Round r's verdict is what round r+1 must act on, and a run killed
+//      after EVAL and relaunched — the normal case here — starts round r+1 in a fresh process with
+//      an empty variable. The verdict was on disk the whole time.
+//
+// Both vanish if the evidence is read where the order is written: the same read on a fresh round
+// and a resumed one, no process boundary to survive, and no model in the path — an LLM courier
+// transcribing a repro string is a repro string that no longer reproduces.
+//
+// The shape is also RICHER than the in-memory channel ever was: the ledgered verdict carries
+// severity, file:line, repro, expected and actual per bug, where the structured return carried
+// only `{id, criterion, evidence}`.
+
+/**
+ * The previous round's cited defects, if that round returned FAIL.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} [round] - The round being compiled; round 1 has no predecessor.
+ * @returns {Array<object>} Bug entries, minus any the adversarial check overturned. Empty for a
+ *   first round, a PASS, or an absent/unreadable result — a fix round with nothing to fix is a
+ *   normal build round, never an error.
+ */
+export function verdictBugs(cwd, slug, round) {
+  if (!round || round < 2) return [];
+  const p = join(resultsDir(cwd, slug), `evaluate-r${round - 1}.json`);
+  if (!existsSync(p)) return [];
+  let v;
+  try { v = JSON.parse(readFileSync(p, "utf8"))?.verdict; } catch { return []; }
+  if (v?.overall !== "FAIL" || !Array.isArray(v.bugs)) return [];
+  // A refuted acceptance criterion is one the judge withdrew. Re-dispatching it would send a
+  // worker to "fix" behaviour that was found correct.
+  const refuted = new Set(
+    (Array.isArray(v.refuted) ? v.refuted : [])
+      .flatMap((r) => [r?.id, r?.ac_id, r?.criterion, typeof r === "string" ? r : null])
+      .filter(Boolean).map(String),
+  );
+  return v.bugs.filter((b) => !refuted.has(String(b?.id)) && !refuted.has(String(b?.criterion)));
+}
+
+/**
+ * Every repo-relative file a bug is cited against.
+ *
+ * A LOCATOR NAMES MORE THAN ONE SITE, ROUTINELY. The judge writes what it found, and what it finds
+ * is often the same defect at several lines, sometimes across files:
+ * `"bin/todo.js:53, bin/todo.js:85"`, or `"lib/parse-index.js:5, :13, :21 (rendered by
+ * bin/todo.js:66)"`. A parser that accepts only a lone `file:line` returns nothing for those, and
+ * "nothing" routes the bug to every scope as unowned — the safe direction, but it throws away an
+ * address the judge did supply. On the measured round-1 verdict that was two of five bugs.
+ *
+ * @param {object} bug - One bug entry.
+ * @returns {string[]} Distinct paths, `:line` suffixes and `./` prefixes stripped, in first-seen
+ *   order. Empty when the entry carries no locator this can read.
+ */
+export function bugLocations(bug) {
+  const raw = String(bug?.location ?? bug?.file ?? "").trim();
+  // A path-looking token: at least one dot-extension, and no whitespace. The extension is what
+  // keeps prose out ("exit 1", "Node 20") without needing to know the project's layout.
+  const out = [];
+  for (const m of raw.matchAll(/(?:^|[\s(,[])([\w@][\w./-]*\.[A-Za-z][A-Za-z0-9]{0,5})(?::\d+)?/g)) {
+    const p = m[1].replace(/^\.\//, "");
+    if (!out.includes(p)) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Elect the ONE scope that should fix a defect cited against a given file.
+ *
+ * OWNERSHIP IS BY SUBSTRATE, because that is what the sandbox enforces: a scope is exactly the set
+ * of files its worker may write, so a scope whose substrate excludes the cited line cannot fix it
+ * however well it understands the bug.
+ *
+ * BUT A MATCH IS NOT AN ELECTION. An entry point is routinely SHARED — on the measured run
+ * `bin/todo.js` sits in five scopes' substrate at once — so "address it to every scope that
+ * matches" hands the same one-line fix to five workers building concurrently against one file.
+ * That is a write race the harness sets up itself, and four of the five fixes are waste even when
+ * it resolves. So: prefer a scope that owns the file EXCLUSIVELY (allowed, not shared), and among
+ * equals take the lowest scope id — a rule that needs no coordination to agree with itself, since
+ * each leg compiles its own order in its own process.
+ *
+ * @param {string} path - Repo-relative file the bug cites.
+ * @param {Array<{scope_id:string, allowed:string[], shared:string[]}>} scopes - Every scope.
+ * @returns {string|null} The elected scope id, or null when no scope may write that file.
+ */
+export function electOwner(path, scopes) {
+  const can = (scopes || []).filter((s) => matchesAny(path, s.allowed));
+  if (!can.length) return null;
+  const exclusive = can.filter((s) => !matchesAny(path, s.shared || []));
+  return (exclusive.length ? exclusive : can).map((s) => s.scope_id).sort()[0];
+}
+
+/**
+ * Address each bug to the scope that must fix it.
+ *
+ * AN UNOWNED BUG GOES TO EVERYONE, MARKED. A cited defect matching no scope's substrate — or
+ * carrying no locator this can read — has no owner, and dropping it silently is precisely how a
+ * judged defect survives a fix round to reappear in the next verdict. Better one scope reads a bug
+ * it turns out not to own than the run forgets a defect it already paid to find.
+ *
+ * @param {Array<object>} bugs - The previous verdict's bugs (see {@link verdictBugs}).
+ * @param {string|undefined} scopeId - The scope being compiled for.
+ * @param {Array<{scope_id:string, allowed:string[], shared:string[]}>} scopes - Every scope.
+ * @returns {Array<object>} The subset this order should carry; unowned entries get `unowned: true`.
+ */
+export function bugsForScope(bugs, scopeId, scopes) {
+  const out = [];
+  for (const b of bugs || []) {
+    if (b?.scope_id) {
+      if (b.scope_id === scopeId) out.push(b);
+      continue;
+    }
+    const owners = bugLocations(b).map((p) => electOwner(p, scopes)).filter(Boolean);
+    if (owners.includes(scopeId)) out.push(b);
+    else if (!owners.length) out.push({ ...b, unowned: true });
+  }
+  return out;
+}
+
+/**
+ * Every scope's write substrate, for the election in {@link electOwner}.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {Array<{scope_id:string, allowed:string[], shared:string[]}>} One entry per readable
+ *   contract; `[]` when the scopes directory is absent or unreadable.
+ */
+export function scopeSubstrates(cwd, slug) {
+  const dir = scopesDir(cwd, slug);
+  let files;
+  try { files = readdirSync(dir).filter((f) => f.endsWith(".md") || f.endsWith(".json")); } catch { return []; }
+  const out = [];
+  for (const f of files) {
+    const c = readContract(join(dir, f), SCOPE_CONTRACT)?.contract;
+    if (!c?.scope_id || !Array.isArray(c.allowed_file_substrate)) continue;
+    out.push({
+      scope_id: c.scope_id,
+      allowed: c.allowed_file_substrate,
+      shared: Array.isArray(c.shared_substrate) ? c.shared_substrate : [],
+    });
+  }
+  return out;
+}
+
 /**
  * Assemble a WorkOrder envelope. Pure given its inputs — the CLI wrapper does the disk reads.
  * @param {object} opts - The order inputs (destructured):
@@ -316,27 +496,32 @@ export function stagnation(trials, k = 2) {
  * @param {Array<{id:string,answer:string}>} [opts.decisions] - This scope's advisor answers.
  * @param {Array<object>} [opts.digestedErrors] - Prior-attempt AEGIS triples (payload.digested_errors).
  * @param {Array<object>} [opts.trialHistory] - Compacted trial rows (payload.trial_history).
+ * @param {Array<object>} [opts.bugs] - The previous round's cited defects (payload.bugs).
  * @param {string} [opts.testCmd] - Verify command, recorded under payload.verify.test_cmd.
  * @param {object} [opts.payloadExtra] - Extra payload fields merged last (spec_folder, feature, …).
  * @param {string} [opts.specDir] - Spec directory, threaded into the substrate template.
  * @param {object} [opts.interaction] - Interaction flags (e.g. {pause_gates}).
- * @returns {object} A WorkOrder: {schema_version, order_id ("<slug>/<suffix>"), worker, mode,
- *   operation?, interaction?, substrate (from {@link substrateFor}), payload{…}}. A coachable
- *   worker also gets payload.kb_rules_path. Not validated here — the CLI validates before writing.
+ * @param {string} [opts.runId] - The run key (`mintRunId` in `lib/paths.mjs`); omitted when no receipt is readable.
+ * @param {string} [opts.compiledAt] - ISO compile time; omitted rather than invented.
+ * @returns {object} A WorkOrder: {schema_version, order_id ("<slug>/<suffix>"), run_id?,
+ *   compiled_at?, worker, mode, operation?, interaction?, substrate (from {@link substrateFor}),
+ *   payload{…}}. A coachable worker also gets payload.kb_rules_path. Not validated here — the CLI
+ *   validates before writing.
  */
 export function compileOrder({
   slug, worker, mode = "orchestrated", operation, round, attempt,
-  scope, tasks, decisions, digestedErrors, trialHistory, testCmd, payloadExtra, specDir, interaction,
+  scope, tasks, decisions, digestedErrors, trialHistory, bugs, testCmd, payloadExtra, specDir, interaction,
+  runId, compiledAt,
 }) {
   // A build order's id carries its SCOPE. Without it, `r<round>-a<attempt>` is the same name for
   // every scope in a round, so scope 2's order file overwrites scope 1's the moment it is compiled
   // — measured on the kill/resume probe, where it made `orders/ minus results/` read EMPTY on a run
   // that was re-dispatching a completed phase. The contract row watching that property therefore
-  // passed on the exact failure it exists to catch. `t0-verify.mjs`'s verdict artifacts have always
+  // passed on the exact failure it exists to catch. ``harness verify t0``'s verdict artifacts have always
   // been self-identifying this way (`r<R>-a<A>-t<T>.json`, `wx`-created); orders now match, so
   // `orders/` is an audit trail of dispatches rather than a rolling buffer of the last one.
   //
-  // The shape stays `<slug>/<suffix>`: every consumer splits on the FIRST "/" (ingest-result.mjs
+  // The shape stays `<slug>/<suffix>`: every consumer splits on the FIRST "/" (`harness reduce ingest`
   // reads [0] as the slug and [1] as the file stem), and a scope id is already filename-safe
   // because it is a scope contract's own basename.
   // `scope` arrives as the PARSED contract object (the CLI reads the .md and embeds it), so the id
@@ -349,10 +534,36 @@ export function compileOrder({
     : (scope ? String(scope).split("/").pop().replace(/\.(md|json)$/, "") : null);
   const scopeId = String(rawScopeId || "").toLowerCase().replace(/[^a-z0-9.-]/g, "-").replace(/^[^a-z0-9]+/, "");
   const buildSuffix = round && attempt ? (scopeId ? `${scopeId}-r${round}-a${attempt}` : `r${round}-a${attempt}`) : null;
-  const suffix = buildSuffix || (round ? `${operation}-r${round}` : operation);
+  // A non-BUILD order was suffixed by operation+round alone, with no per-leg discriminator — so two
+  // concurrent non-BUILD legs of the SAME operation and round, dispatched for different scopes
+  // (e.g. two scopes both running `evaluate` in the same round), compiled to the identical suffix
+  // and the second write clobbered the first order file on disk while the run read green. `scopeId`
+  // is already derived above for any operation, not only BUILD; folding it in here — only when a
+  // scope was actually passed — closes that collision. Operation-level dispatches (orient, analyze,
+  // wire, map-scopes, evaluate, hunt, hammer) never pass a scope, so `scopeId` is empty for them and
+  // this reduces to the unchanged `${operation}-r${round}` / `${operation}` shape.
+  const scopedRoundSuffix = scopeId
+    ? (round ? `${operation}-${scopeId}-r${round}` : `${operation}-${scopeId}`)
+    : (round ? `${operation}-r${round}` : operation);
+  const suffix = buildSuffix || scopedRoundSuffix;
   const order = {
     schema_version: 1,
     order_id: `${slug}/${suffix}`,
+    // THE TWO ANALYTIC FIELDS, and why they are on the ORDER rather than the result.
+    //
+    // `order_id` identifies a dispatch within a run and repeats across runs of the same slug, so
+    // the dispatch record needed a run key to be groupable at all. It is stamped here because this
+    // is the one place every lane passes through — the same reason the active-order pointer is
+    // published here — so the workflow lane, `--tiny`, the prose round loop and a standalone
+    // dispatch all carry it without four separate stamps to keep in step.
+    //
+    // The RESULT deliberately gets neither. It is written by the worker, and a field a worker has
+    // to remember to copy is a field that goes missing under exactly the conditions you most want
+    // the record: the run that went wrong. Results join to orders on `order_id`, which they already
+    // echo and `validate-envelope` already checks — so the key reaches the result leg through a
+    // join that is enforced, instead of through a worker's cooperation.
+    ...(runId ? { run_id: runId } : {}),
+    ...(compiledAt ? { compiled_at: compiledAt } : {}),
     worker,
     mode,
     ...(operation ? { operation } : {}),
@@ -364,6 +575,9 @@ export function compileOrder({
       ...(decisions?.length ? { decisions } : {}),
       ...(digestedErrors?.length ? { digested_errors: digestedErrors } : {}),
       ...(trialHistory?.length ? { trial_history: trialHistory } : {}),
+      // Before `payloadExtra`, so an explicit `--payload '{"bugs":…}'` still wins: an operator
+      // hand-addressing a defect outranks the derivation.
+      ...(bugs?.length ? { bugs } : {}),
       ...(testCmd ? { verify: { test_cmd: testCmd, env: [] } } : {}),
       ...(payloadExtra || {}),
     },
@@ -376,7 +590,7 @@ export function compileOrder({
 // ---------------------------------------------------------------------------
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "compile-order.mjs (--scope <contract.json> --round N --attempt M | --task TASK-NNN --slug <slug> " +
+  usage: "harness.mjs compile (--scope <contract.json> --round N --attempt M | --task TASK-NNN --slug <slug> " +
          "| --next --slug <slug> | --operation <op> --slug <slug>) [--worker <skill>] [--payload '<json>'] " +
          "[--spec <dir>] [--test-cmd \"<cmd>\"] [--cwd <dir>] [--pause-gates]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
@@ -395,9 +609,15 @@ export const ARGV_SPEC = {
   "pause-gates": { type: "flag" },
 };
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const argv = runArgs(ARGV_SPEC);
+/**
+ * Compile a WorkOrder for one dispatch and publish the substrate pointer that fences it.
+ *
+ * @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 async function cli(rawArgv) {
+  const argv = runArgs(ARGV_SPEC, rawArgv);
   /**
    * Read a parsed flag's value, normalising "absent" to null (the shape the body below expects).
    * @param {string} name - Flag name without leading dashes.
@@ -433,17 +653,26 @@ if (isMainModule) {
 
   const round = flag("round");
   const attempt = flag("attempt");
-  // Operation → owning worker (mirrors domain.schema.json $defs/Operation ownership). Lets a
-  // non-build dispatch resolve its worker from the operation alone, without a redundant --worker.
-  const OP_OWNER = {
-    analyze: "ba-pitch-analyzer", reconcile: "ba-pitch-analyzer",
-    "retrofit-surface": "ba-pitch-analyzer", coverage: "ba-pitch-analyzer",
-    "map-scopes": "scope-architect",
-    wire: "solution-architect", evaluate: "spec-evaluator", orient: "orient",
-    hunt: "qa-edge-hunter", translate: "translator",
-    hammer: "scope-hammer", coach: "coach",
-  };
-  let operation = flag("operation") || (scopePath || flag("task") || has("next") ? "execute" : null);
+
+  // The fix round's inbound evidence. Derived here, from the ledgered verdict, for every lane —
+  // the workflow, `--tiny`, the prose round loop and a standalone `/build` all compile through
+  // this line, and none of them can pass a payload to a build order (see the banner above).
+  const bugs = scope ? bugsForScope(verdictBugs(cwd, slug, round), scope.scope_id, scopeSubstrates(cwd, slug)) : [];
+
+  // A ROUND CARRYING CITED DEFECTS IS A `fix`, AND THE ORDER HAS TO SAY SO.
+  //
+  // `payload.bugs` is the only field task-executor's input contract binds to a specific operation:
+  // "`fix` (only the bugs in `payload.bugs` — touch nothing else)". Dispatching a fix round as
+  // `execute` hands the worker a field its own contract associates with a different operation,
+  // against a Zero-memory rule that says to treat anything not in the order as unknown. Delivering
+  // evidence the receiving contract does not claim is half a delivery.
+  //
+  // Free of blast radius by construction: `substrateFor` returns the same whitelist for
+  // execute/fix/spike, so the sandbox contract is byte-identical, and the order id is addressed by
+  // scope/round/attempt rather than by operation, so no filename moves. An explicit `--operation`
+  // still wins — an operator naming the operation outranks the derivation.
+  let operation = flag("operation")
+    || (scopePath || flag("task") || has("next") ? (bugs.length ? "fix" : "execute") : null);
   const worker = flag("worker")
     || (scopePath || flag("task") || has("next") ? "task-executor" : null)
     || (operation ? OP_OWNER[operation] : null);
@@ -460,10 +689,18 @@ if (isMainModule) {
     tasks = board.filter((t) => t.status === "ready" && t.depends_on.every((d) => doneIds.has(d))).slice(0, 1);
     if (!tasks.length) { console.error("compile-order: no ready task with satisfied dependencies"); process.exit(2); }
   } else if (scope) {
-    // Scope attempt: the scope's own task list if the contract names one, else every
-    // not-done task on the board (the attempt loop owns sequencing, not the worker).
-    const named = new Set(scope.tasks || []);
-    tasks = board.filter((t) => (named.size ? named.has(t.id) : t.status !== "done"));
+    // Scope attempt: the board tasks anchored to this scope's use cases, else every not-done task
+    // on the board (the attempt loop owns sequencing, not the worker).
+    //
+    // The contract names USE CASES, never task ids: it is committed and the board is not, so a
+    // contract holding `TASK-004` pointed into a gitignored per-machine tier and resolved to
+    // nothing on a fresh clone — silently, because an empty filter and an absent board are the
+    // same empty array. A scope that anchors no use case still falls back to the whole open board
+    // rather than dispatching nothing; spec-lint's SCOPE-ANCHOR is what reports the missing anchor.
+    const anchored = tasksForScope(board, scope);
+    tasks = anchored.length || (scope.use_cases || []).length
+      ? anchored
+      : board.filter((t) => t.status !== "done");
   }
 
   // Ledger decisions for this scope.
@@ -474,7 +711,7 @@ if (isMainModule) {
 
   // inspect() — the attempt loop's history (see selectTrialHistory above).
   //
-  // NON-REGRESSION (plan §7). With no `trials.jsonl` on disk this falls back to exactly today's
+  // NON-REGRESSION. With no `trials.jsonl` on disk this falls back to exactly the pre-ratchet
   // read — the previous attempt's verdict artifact, AEGIS triples only, byte-for-byte the same
   // order. Every new arm is skipped when its artifact is absent, per the ✦/✚ convention.
   let digestedErrors = [];
@@ -508,9 +745,14 @@ if (isMainModule) {
   if (!payloadExtra.feature) payloadExtra.feature = slug;
 
   const order = compileOrder({
-    slug, worker, operation, round, attempt, scope, tasks, decisions, digestedErrors, trialHistory,
+    slug, worker, operation, round, attempt, scope, tasks, decisions, digestedErrors, trialHistory, bugs,
     testCmd: flag("test-cmd"), payloadExtra, specDir,
     interaction: has("pause-gates") ? { pause_gates: true } : { pause_gates: false },
+    // Read off the receipt rather than passed in: a standalone `compile-order` invocation gets the
+    // same key as one the workflow drove, and a dispatch in a workspace with no open run simply
+    // carries no key instead of failing — the analytic field must never be able to block a build.
+    runId: readRunId(cwd, slug),
+    compiledAt: new Date().toISOString(),
   });
 
   const { valid, errors } = validate(order, ORDER_SCHEMA);

package/{skills/tech-lead/scripts/gate-answers.mjs → kernel/gate.mjs}

@@ -32,10 +32,10 @@
 // pre-recorded answer") rather than a silent wait that gets reported as a slow harness.
 //
 // USAGE
-//   node gate-answers.mjs --init [--preset ci|guarded|interactive] [--out <path>] [--by "<name>"]
-//   node gate-answers.mjs --resolve <gate-id> [--file <path>|--preset <name>] [--slug <slug>]
-//   node gate-answers.mjs --list [--file <path>|--preset <name>]
-//   node gate-answers.mjs --verify [--file <path>|--preset <name>] [--auto-level unattended]
+//   node `harness gate` --init [--preset ci|guarded|interactive] [--out <path>] [--by "<name>"]
+//   node `harness gate` --resolve <gate-id> [--file <path>|--preset <name>] [--slug <slug>]
+//   node `harness gate` --list [--file <path>|--preset <name>]
+//   node `harness gate` --verify [--file <path>|--preset <name>] [--auto-level unattended]
 //
 // RESOLUTION ORDER for --resolve / --list / --verify, first hit wins:
 //   1. --file <path>
@@ -50,11 +50,10 @@
 //   5  no answer and on_missing=abort → the run aborts here, attributably
 //   2  usage / validation error
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
 import { runArgs } from "./lib/argv.mjs";
-import { gateAnswerCandidates, LOCAL } from "./lib/paths.mjs";
+import { gateAnswerCandidates, gates as gatesPath, LOCAL } from "./lib/paths.mjs";
 
 export const GATE_IDS = ["L0", "L1a", "L1a.5", "L1b", "L2", "L3", "QA", "H", "L4", "COACH-1"];
 
@@ -204,6 +203,33 @@ export function resolve(set, gate, source) {
   };
 }
 
+/**
+ * Append one row to the per-slug gate-crossing ledger — `.shapeup/<slug>/gates.jsonl` ({@link
+ * gatesPath}, from `lib/paths.mjs`).
+ *
+ * WRITER RULE, same shape as {@link appendTrial} in `verify/t0.mjs` and the dispatch-receipt hook's
+ * ownership of `decisions.jsonl`: one small file, one writer, append-only JSONL so concurrent
+ * scopes crossing gates in the same round cannot clobber each other's row.
+ *
+ * Records every resolution that reached a real status — a crossing (`ok`), a recorded pause
+ * (`ask`), or an abort (`abort`) — because "the run stopped here" is exactly the kind of fact this
+ * ledger exists to hold. Best-effort: a ledger write that could fail a gate crossing would cost more
+ * than the row is worth, matching {@link appendTrial}'s own trade-off.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {object} row - The ledger row (gate, decision, source, note, round, status).
+ * @returns {boolean} True when the row was written.
+ */
+export function appendGateLedger(cwd, slug, row) {
+  try {
+    const p = gatesPath(cwd, slug);
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify(row) + "\n");
+    return true;
+  } catch { return false; }
+}
+
 /** Gates this lane will actually hit — used by --verify to catch a set that stalls halfway. */
 export function requiredGates({ autoLevel = "unattended", tiny = false, qa = true } = {}) {
   if (tiny) return ["L0", "L4"];
@@ -239,9 +265,9 @@ export function discover({ cwd = process.cwd(), file = null, preset = null, slug
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "gate-answers.mjs (--init | --list | --verify | --resolve <gate-id>) [--preset <name>] " +
+  usage: "harness.mjs gate (--init | --list | --verify | --resolve <gate-id>) [--preset <name>] " +
          "[--file <path>] [--slug <slug>] [--cwd <dir>] [--out <path>] [--by <who>] " +
-         "[--auto-level <level>] [--tiny] [--no-qa]",
+         "[--auto-level <level>] [--tiny] [--no-qa] [--round <n>]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   init: { type: "flag" },
@@ -256,6 +282,10 @@ export const ARGV_SPEC = {
   "auto-level": { type: "str" },
   tiny: { type: "flag" },
   "no-qa": { type: "flag" },
+  // The current BUILD round, when the caller has one — L2/L3 are crossed once per round, so the
+  // ledger row needs it to key a `GateDecision` node uniquely per crossing. Round-independent gates
+  // (L0, L1a, …) simply omit it and the row carries `round: null`.
+  round: { type: "int", min: 1 },
 };
 
 function out(obj, code = 0) {
@@ -267,8 +297,15 @@ function die(msg, code = 2) {
   process.exit(code);
 }
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Resolve, verify, list or initialise the gate answer set.
+ *
+ * @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();
 
   if (args.init) {
@@ -327,11 +364,18 @@ export function main() {
 
   const r = resolve(found.set, gate, found.source);
   if (r.status === "error") die(r.reason);
+  // A gate with no `--slug` (e.g. `--file` used ad hoc, outside any run) has nowhere to file a
+  // per-run ledger row — the same reasoning `resolveRunId` uses for "no run is active": absence is
+  // the correct answer, not an error, so the write is skipped rather than guessing a location.
+  if (args.slug) {
+    appendGateLedger(cwd, args.slug, {
+      gate: r.gate, status: r.status, decision: r.decision ?? null,
+      source: r.source ?? found.source, note: r.note ?? r.reason ?? null,
+      round: args.round ?? null,
+    });
+  }
   if (r.status === "ask") out({ ...r, ok: false }, 4);
   if (r.status === "abort") out({ ...r, ok: false }, 5);
   out({ ...r, ok: true }, 0);
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}