shapeup-sdlc 1.6.3 → 3.0.0

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

@@ -4,7 +4,7 @@
 // The orchestrator's pipeline sub-layer: assembles the structured input envelope a worker is
 // dispatched with. Replaces tech-lead's hand-assembled `isolated_brief()` prose step and every
 // worker's GATE A/B plumbing (path resolution, run-state parse, board glob-matching, dependency
-// reads, mode detection). Deterministic, zero LLM tokens (DD-7).
+// reads, mode detection). Deterministic, zero LLM tokens.
 //
 // A worker depends on its ORDER, never on filesystem topology — moving a directory again
 // (the v3.2 lesson) touches this script, zero skills.
@@ -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,20 +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 { 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) --------------------------
 /**
@@ -71,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.
@@ -98,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,
   };
@@ -143,11 +149,30 @@ 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, not trusted to prose.
- * @param {string} operation - The order's operation (execute|analyze|generate-board|reconcile|
- *   retrofit-surface|coverage|map-scopes|remap|split-scope|wire|evaluate|hunt|recheck|orient|…).
+ * operation, so mode/flag differences are enforced by the sandbox hook reading the order's substrate, not trusted to prose.
+ * @param {string} operation - The order's operation (execute|fix|spike|analyze|reconcile|
+ *   retrofit-surface|coverage|map-scopes|wire|evaluate|orient|hunt|translate|hammer|coach).
  * @param {{slug?:string, specDir?:string, scope?:object}} [ctx] - slug (names LOCAL/SHARED roots),
  *   specDir (overrides the default spec path), scope (contract supplying allowed/shared substrates).
  * @returns {{allowed:string[], shared?:string[], frozen?:string[], append_only?:string[]}} The
@@ -171,11 +196,7 @@ export function substrateFor(operation, { slug, specDir, scope } = {}) {
       };
     case "analyze":
       return { allowed: [`${spec}/**`, `${local}/**`], frozen: [] };
-    case "generate-board":
-      return {
-        allowed: [`${local}/tasks/**`, `${spec}/scope-summary.md`, `${working}/**`],
-        frozen: [...FROZEN_SPEC_CORE, `${scopesDir}/**`],
-      };
+
     case "reconcile":
       return {
         allowed: [`${local}/tasks/**`, `${spec}/scope-summary.md`, `${working}/**`],
@@ -184,14 +205,14 @@ export function substrateFor(operation, { slug, specDir, scope } = {}) {
       };
     case "retrofit-surface":
       return { allowed: [], append_only: [`${spec}/usecases/*.md#Test Surface`], frozen: FROZEN_SPEC_CORE };
+
     case "coverage":
-      // ba-pitch-analyzer writes the SHARED requirement registry only — the REQ source and the
-      // spec core stay frozen (the registry is a separate derived file, never an edit of the source).
-      return {
-        allowed: [globShared(slug, "requirements.md")],
-        frozen: [...FROZEN_SPEC_CORE, `${scopesDir}/**`, `${local}/tasks/**`],
-      };
-    case "map-scopes": case "remap": case "split-scope":
+      // The covers-closure input truth. Writes ONLY the derived registry: the REQ source it
+      // extracts from is frozen alongside the spec core, because a planner that may edit the
+      // requirements it is being measured against is not measuring anything.
+      return { allowed: [globShared(slug, "requirements.md")], frozen: FROZEN_SPEC_CORE };
+
+    case "map-scopes":
       return {
         allowed: [`${scopesDir}/*.md`, globShared(slug, "scope-board.md")],
         frozen: [...FROZEN_SPEC_CORE, `${local}/tasks/**`],
@@ -205,10 +226,16 @@ export function substrateFor(operation, { slug, specDir, scope } = {}) {
       };
     case "evaluate":
       return { allowed: [`${local}/evaluation/**`], frozen: [`${spec}/**`, `${local}/tasks/**`] };
-    case "hunt": case "recheck":
+    case "hunt":
       return { allowed: [`${local}/qa/**`], frozen: [`${spec}/**`, `${local}/tasks/**`] };
     case "orient":
       return { allowed: [`${local}/orient/**`], frozen: [`${spec}/**`] };
+    case "translate":
+      return { allowed: [globShared(slug, "shaping/*.md"), globShared(slug, "glossary.md")] };
+    case "hammer":
+      return { allowed: [globShared(slug, "REPORT.md"), `${local}/reports/**`] };
+    case "coach":
+      return { allowed: [relKnowledgeBase("*")] };
     default:
       return { allowed: [`${local}/**`] };
   }
@@ -278,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
@@ -299,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):
@@ -313,22 +496,74 @@ 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,
 }) {
-  const suffix = round && attempt ? `r${round}-a${attempt}` : round ? `${operation}-r${round}` : operation;
+  // 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. ``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 "/" (`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
+  // comes from its own `scope_id` field; a caller that passes a path instead still works. The id is
+  // lowercased and stripped to the character class `work-order.schema.json` allows after the "/" —
+  // an order that cannot pass its own schema is refused before it is written, and a naming
+  // improvement must not be able to cause that.
+  const rawScopeId = scope && typeof scope === "object"
+    ? scope.scope_id
+    : (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;
+  // 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 } : {}),
@@ -340,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 || {}),
     },
@@ -352,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)" },
@@ -371,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.
@@ -409,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", "generate-board": "ba-pitch-analyzer", reconcile: "ba-pitch-analyzer",
-    "retrofit-surface": "ba-pitch-analyzer", coverage: "ba-pitch-analyzer",
-    "map-scopes": "scope-architect", remap: "scope-architect", "split-scope": "scope-architect",
-    wire: "solution-architect", evaluate: "spec-evaluator", orient: "orient",
-    hunt: "qa-edge-hunter", recheck: "qa-edge-hunter", translate: "translator",
-    hammer: "scope-hammer", coach: "coach", adjudicate: "advisor-protocol",
-  };
-  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);
@@ -436,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.
@@ -450,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 = [];
@@ -484,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);
@@ -501,6 +767,29 @@ if (isMainModule) {
   writeFileSync(outPath, JSON.stringify(order, null, 2) + "\n");
   console.log(outPath);
 
+  // POINT THE SANDBOX AT THIS ORDER, HERE, because this is the only place every lane passes
+  // through.
+  //
+  // `hooks/sandbox-guard.mjs` enforces the order's own `substrate` block — allowed/shared,
+  // append_only, frozen — and it finds the order through `.shapeup/active-order`. Until this
+  // write existed the pointer had exactly one author, the workflow script, so the guard fenced
+  // the workflow lane and DEFERRED everywhere else: `--tiny`, the prose round loop, and a
+  // standalone `/build` all compiled an order carrying a write contract that nothing enforced.
+  // A substrate that is only enforced on the lane that also happens to be the most supervised
+  // one is the wrong way round.
+  //
+  // Compiling an order is the moment the write contract comes into existence, so it is the
+  // correct moment to publish it. The workflow script still sets the pointer explicitly before
+  // dispatch (it interleaves phases and must be exact about which order is live); this write
+  // makes the SAME mechanism cover callers that never reach that code.
+  //
+  // Best-effort, on stderr, and never fatal: a compiled order that cannot publish its pointer is
+  // still a valid order, and stdout belongs to the order path the caller consumes. The guard
+  // fails open on a missing pointer by design, so the failure mode is "unfenced", which is
+  // exactly what a warning is for.
+  const ptr = writeActiveOrder(cwd, slug, outPath);
+  if (!ptr.ok) console.error(`compile-order: warning — ${ptr.reason} (this order's substrate will not be enforced)`);
+
   // The stagnation breaker reports on stderr, never on stdout: stdout is the order path the
   // orchestrator consumes, and a breaker that corrupts the pipeline's own output would be worse
   // than the flailing it detects. It advises; the orchestrator queues the GATE H proposal.