shapeup-sdlc 3.2.0 → 3.4.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Shape Up SDLC harness for Claude Code: shaping, intake, orient, scope-mapping, building (T0-verified, sandboxed, scope-contracted), evaluation and QA skills orchestrated by a tech-lead.",
   "author": {
     "name": "Liberty Nguyen",

package/AGENTS.md

@@ -31,8 +31,8 @@ Betting Table: PO decides; rejected pitches loop back to raw idea.
 | Analyze | — (reviewed at L1b) | `/ba-pitch-analyzer` (`analyze`): spec tree + board (UC + Invariants + Test Surface ★); before Wire (needs its use cases) |
 | Wire | ⏸ **L1a.5** — Wiring Review ✚ | `/solution-architect` (`wire`): sole writer of committed `wiring-map.md` — per-UC engine → seam → entry-point call site → affordance, per `project-profile.md` |
 | Map Scopes | ⏸ **L1b** — Board Review (+ substrate disjointness lint) | `/scope-architect` (scope contracts ✦ — sole writer); traceability oracle advisory ✚ |
-| Build Vertically | ⏸ **L2** — Board 100% ✅ + T0-green ✦ | per dispatch: compile order → `/task-executor` (--order) → ingest result; T0-verified per attempt (fixtures + DB probe + seesaw ✦), substrate-sandboxed ✦. Scopes build **concurrently** ✦ — `--parallel-scopes N` caps it (default 4), a scope is released the moment its own dependencies are green, and a scope green in this round is skipped rather than rebuilt |
-| EVAL (once per round) | ⏸ **L3** — Verdict | `/spec-evaluator` (--order): spec- + test-surface-conformance ★, T0 citation ✦; refuted boxes/verdict applied by ingest |
+| Build Vertically | ⏸ **L2** — Board 100% ✅ + T0-green ✦ | per dispatch: compile order → `/task-executor` (--order) → ingest result; T0-verified per attempt (fixtures + DB probe + seesaw ✦), substrate-sandboxed ✦. Scopes build **concurrently** ✦ — `--parallel-scopes N` caps it (default 4), a scope is released the moment its own dependencies are green, and a scope green in this round is skipped rather than rebuilt. Then the **round build gate** ⚙: the ledger's run command, then the profile's `build_probe` and `launch_probe`, run once per round before EVAL — a red gate ends the round with no verdict and its failing step is compiled into the next round's orders as bugs; a `mobile` profile with no `launch_probe` is warned about every round, so the install/launch risk has an owner |
+| EVAL (once per round) | ⏸ **L3** — Verdict | `/spec-evaluator` (--order), only over a round whose build gate ⚙ is not red: spec- + test-surface-conformance ★, T0 citation ✦; refuted boxes/verdict applied by ingest |
 | FAIL → round r+1 | — | regression rule ★: bugs + full Test Surface of touched UC |
 
 ✦ = requires scope contracts (`shapeup/<slug>/scopes/*.md`); ✚ = requires the spine artifacts (`requirements.md`, `wiring-map.md`, `project-profile.md`). Traceability stays advisory until `covers:` is populated. Absent artifact ⇒ arm skipped (non-regression).
@@ -44,9 +44,9 @@ Betting Table: PO decides; rejected pitches loop back to raw idea.
 **Q0** Preflight → **Q1** Charter (6 lenses − EVAL-covered) → **Hunt** (repro required, findings `~` → ledger) → report (no verdict, no score). Skip with `--no-qa`.
 
 ### Ship & Triage
-- **SHIP S.0 / GATE H** — `/scope-hammer`: census (QA findings + discovered ledger + attempt-budget proposals ✦) → baseline comparison (never the ideal) → cut list; TL/PO promotes selected items only.
+- **SHIP S.0 / GATE H** — `/scope-hammer`: census (QA findings + discovered ledger + attempt-budget proposals ✦; every "no scope owns X" cites `probe owner`, which derives ownership from the contracts) → baseline comparison (never the ideal) → cut list; TL/PO promotes selected items only.
 - ⏸ **L4** — Ship Sign-off (shows QA status ★).
-- **Coach retro** — L4 feedback → `/coach`; GATE COACH-1 asks the PO which skill owns each rule (never assumes) → committed `shapeup/knowledge-base/<skill>.md` (team inherits on pull). Coachable: `/task-executor`, `/ba-pitch-analyzer`, `/qa-edge-hunter`; `/spec-evaluator` is not (single judge). Mechanism defects file to `knowledge-base/harness-defects.md` as Betting Table raw ideas, never worker steering.
+- **Coach retro** — L4 feedback → `/coach`; GATE COACH-1 asks the PO which skill owns each rule (never assumes) → committed `shapeup/knowledge-base/<skill>.md` (team inherits on pull). Coachable: `/task-executor`, `/ba-pitch-analyzer`, `/qa-edge-hunter`, `/orient`, `/scope-architect`, `/solution-architect`, and `/tech-lead` (workflow guidance read at L0, plus suggested L0 values it confirms before pinning); `/spec-evaluator` is not (single judge) and neither is `/scope-hammer` (its census cites `probe owner`). **Guidance never decides a gate**: a rule may add a question or a check to a gate block, never an answer, a skip or a wider substrate. `/retro --scan` seeds the same files from the project on disk before the first run, and `/retro --research <stack>` from the platform's official documentation when there is nothing on disk yet (a source, never a verification: nothing it reads runs until the tech lead pins it at L0), optional, every rule confirmed at COACH-1. Mechanism defects file to `knowledge-base/harness-defects.md` as Betting Table raw ideas, never worker steering.
 - Post-fix: `eval --single-pass` → remaining `~` + new feedback → new raw idea.
 
 ### Discovered Tasks
@@ -58,7 +58,7 @@ Everything discovered funnels into `.shapeup/<slug>/discovery/ledger.md` (Orient
 - **Ledger = single source of truth** — every discovery flow writes only its own section.
 - **QA is a level-up, not a gate** — `--no-qa` skips it; circuit breaker outranks the Hunter.
 - **Role separation** — Evaluator grades, task-executor fixes, QA discovers.
-- **Hill phase is mechanical ✦** — derived only from T0/T1/seesaw artifacts, never self-reported; the evaluator cites a T0 artifact it re-hashes itself, from the list its order carries. A scoped verdict citing none is refused: its round stays open and is evaluated again, never advanced.
+- **Hill phase is mechanical ✦** — derived only from T0/T1/seesaw artifacts, never self-reported, and a T0-green from a round whose build gate ⚙ is red moves no dot (a green fixture in a round the feature did not build is evidence about the fixture); the evaluator cites a T0 artifact it re-hashes itself, from the list its order carries. A scoped verdict citing none is refused: its round stays open and is evaluated again, never advanced.
 - **Envelope port (v1.0)** — every dispatch is WorkOrder in / WorkResult out; shared state has exactly one writer (the ingest step); malformed envelopes are hook-denied. Workers: stateless, craft-only, pipeline-blind.
 
 ## Setup & Execution
@@ -79,5 +79,6 @@ Everything discovered funnels into `.shapeup/<slug>/discovery/ledger.md` (Orient
 - `/hill-chart` (skill `hill-chart`, not a pipeline worker — invoked directly, like `shapeup`) renders both the committed hill shards (`shapeup/<slug>/hill/<scope-id>.yml`, the mechanical phase from the invariant above) and the local run graph as one dashboard: a portfolio card per pitch, and per-pitch a Hill Chart, an attention list, a scope board, round history, and the run graph one click deeper. A pitch whose local run trace was cleaned up after shipping still renders — marked Archived — from its committed hill shards alone.
 - Contracts: markdown on disk, JSON on the wire; a single library reads/writes the file form.
 - Never hard-code a storage root — generated paths resolve through the shared path resolver.
+- Hooks file under the project root they find above the shell's working directory (a run pointer, the committed tier, or a git boundary), never under the folder a worker happened to `cd` into — so a sub-folder shell neither splits the decision ledger nor slips the substrate fence. `probe stats --hooks` lists any stray ledger it still finds.
 - The traceability oracle emits `.shapeup/<slug>/trace/report.json` from the spine artifacts.
 <!-- HARNESS_END -->

package/README.md

@@ -177,7 +177,7 @@ every arm is skipped when its artifact is absent, so older specs are unaffected.
 | Evaluate (GATE L3) | `spec-evaluator` | v1.0 | The single judge (pure worker). Verifies spec-conformance, TDD surface, and integration against the running app — skeptical, files `file:line` bugs, runs exactly once per build round. Requires a T0 artifact citation, grades UI affordance-only; verdict + refuted boxes return as data. |
 | QA (post-PASS) | `qa-edge-hunter` | v1.1 | Exploratory edge hunt on the running app through six fixed lenses, charting edges *outside* what the evaluator probed. Findings go to the ledger as `~`; never blocks ship. |
 | Stop (11) | `scope-hammer` | v0.1 | GATE H: must-have census → baseline comparison (never vs. the ideal) → cut list + ship verdict. Handles the normal stop and both circuit-breaker triggers. |
-| Retro (post-L4) | `coach` | — | RLHF for the harness: turns raw PO/TL feedback at Ship Sign-off into per-skill guidelines under committed `shapeup/knowledge-base/<skill>.md`, read back by `task-executor` / `ba-pitch-analyzer` / `qa-edge-hunter` on their next run. GATE COACH-1 asks the PO which skill owns each rule — never assumes; mechanism defects are filed to the harness-defect register instead. |
+| Retro (post-L4) | `coach` | — | RLHF for the harness: turns raw PO/TL feedback at Ship Sign-off into per-skill guidelines under committed `shapeup/knowledge-base/<skill>.md`, read back by six coachable workers on their next run and by `tech-lead` at GATE L0 (workflow guidance, never a gate answer). `--scan` seeds the same files from the project on disk before the first run; `--research <stack>` seeds them from the platform's official documentation when the project has nothing to scan, and cross-checks a scan's rules when it has. GATE COACH-1 asks the PO which skill owns each rule — never assumes; mechanism defects are filed to the harness-defect register instead. |
 | Orchestrator | `tech-lead` | v1.0 | Owns the run end-to-end: PLAN once → BUILD all tasks → EVAL once per round, looping on FAIL. Three-level circuit breaker (rounds / T0 attempts / wall clock), T0/seesaw-verified build rounds, mechanical hill derivation. Sole writer of run-state. |
 
 ### Commands

package/SECURITY.md

@@ -45,7 +45,10 @@ test against machines you don't own.
    (override channel fails closed), and every exercised override is logged. The same principle
    covers `.shapeup/active-order`, which `sandbox-guard` reads to find the run whose orders fence
    a worker's writes: it sits outside the run-trace carve-out, so a worker cannot repoint its own
-   sandbox.
+   sandbox. Every hook resolves that pointer, the decision ledger and the substrate globs against
+   the project root it finds above the tool call's working directory (a run pointer, the committed
+   tier, or a git boundary) — a worker that `cd`s into a sub-folder is fenced exactly as one at the
+   top, and its receipts land in the same ledger.
 5. **Exactly one hook can block, and only on a mechanical absence.** `gate-zerowork` returns
    `decision: "block"` in one state: the session dispatched the orchestrator and left no run
    receipt on disk. It makes no judgement about quality — it reports that there is no work to

package/bin/init.mjs

@@ -181,6 +181,9 @@ for (const [srcRel, note] of [
 
 console.log("\n✅ Harness installation and scaffolding completed.");
 console.log("   Next: open a Claude Code session in this directory and run /ship \"<your idea>\".");
+console.log("   Optional: /retro --scan first seeds the team knowledge base from this project's");
+console.log("   build files, or /retro --research \"<stack>\" seeds it from the platform's official");
+console.log("   docs when there is nothing on disk yet (every drafted rule is confirmed by you).");
 console.log("   ([ui] evaluation needs a browser — `npx playwright install chromium` — but only");
 console.log("   when a run actually reaches a [ui] criterion; nothing else requires it.)");
 

package/commands/retro.md

@@ -5,9 +5,26 @@ Use the **coach** skill on $ARGUMENTS.
 
 Turns raw PO/TL feedback (usually from the L4 Ship gate) into per-skill guideline files under
 committed `shapeup/knowledge-base/<skill>.md`, which the coachable skills read back at
-the top of their next run.
+the top of their next run, and which the tech lead reads at GATE L0 for workflow guidance.
+
+`/retro --scan` runs the coach's **scan** operation instead: it reads the project on disk (build
+and toolchain files, CI config, CLAUDE.md, README) and drafts the same kind of guidelines from
+it, before the first feature or after the toolchain changes. Optional, and never on the scan's
+own authority — every drafted rule goes through GATE COACH-1 like feedback.
+
+`/retro --research <stack>` runs the **research** operation: for a project with nothing on disk
+yet, it drafts the same kind of guidelines from the platform's official documentation only —
+build, launch, test, package manager, lint, in that order of leverage — each rule cited with url,
+version and fetch date; on a project that has been scanned, it cross-checks every scan rule
+against the documentation and reports each as confirmed, contradicted or unknown. The stack is
+required and never guessed. Research is a source, not a verification: nothing it reads runs, and
+the tech lead still pins every suggested command at GATE L0 before the kernel executes it. A
+later `--scan`, once the first feature has created a toolchain, retires the research rules it
+confirms with disk evidence.
 
 Two rules the skill enforces and this command must not soften: GATE COACH-1 **asks** the PO
 which skill owns each rule — it never assumes; and feedback whose root cause is the mechanism
 itself (a gate, hook, or contract defect) is categorized `harness-defect` and filed to the
-defect register as a raw idea for the Betting Table, never as worker steering.
+defect register as a raw idea for the Betting Table, never as worker steering. A third holds
+for every category: guidance never decides a gate — a rule may add a question or a check to a
+gate block, never an answer.

package/hooks/dispatch-receipt.mjs

@@ -49,7 +49,7 @@ import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { isMain } from "../kernel/lib/argv.mjs";
 import { dispatchReceipts } from "../kernel/lib/paths.mjs";
-import { runHook, readStdin, settle } from "./lib/decision.mjs";
+import { runHook, readStdin, settle, projectRoot } from "./lib/decision.mjs";
 
 /**
  * The `--order` matcher, character-for-character the one the PreToolUse order gate uses
@@ -173,7 +173,10 @@ export async function main() {
       defer("dispatch result names no resolved skill — nothing to attest", "no-skill-named");
     }
 
+    // The order path is relative to the shell; the receipt file is relative to the project root
+    // (see `projectRoot`) — the same ledger whichever folder the dispatch was issued from.
     const cwd = p.cwd || process.cwd();
+    const root = projectRoot(cwd);
     const orderPath = resolve(cwd, cited);
     let order;
     try { order = JSON.parse(readFileSync(orderPath, "utf8")); }
@@ -181,9 +184,9 @@ export async function main() {
     if (!order?.order_id) defer("order carries no order_id — nothing to key a receipt by", "order-unkeyed");
 
     const row = receiptRow(order, skillInvoked, p);
-    const written = writeReceipt(row, cwd);
+    const written = writeReceipt(row, root);
     return {
-      verdict: "allow", event: "PostToolUse", tool: p.tool_name, cwd, subject: row.order_id,
+      verdict: "allow", event: "PostToolUse", tool: p.tool_name, cwd: root, subject: row.order_id,
       rule: written ? "receipt-written" : "receipt-write-failed",
       reason: written
         ? `dispatch receipt: ${row.order_id} ran ${skillInvoked} (declared ${row.worker_declared}, ok=${row.dispatch_ok})`

package/hooks/gate-zerowork.mjs

@@ -57,7 +57,7 @@ import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { isMain } from "../kernel/lib/argv.mjs";
 import { localDir, globLocal, globWorkflowsStage } from "../kernel/lib/paths.mjs";
-import { runHook, readStdin, settle, decisionsPath } from "./lib/decision.mjs";
+import { runHook, readStdin, settle, decisionsPath, projectRoot } from "./lib/decision.mjs";
 
 const MAX_TRANSCRIPT_BYTES = 20 * 1024 * 1024;
 
@@ -287,7 +287,10 @@ async function main() {
   // (read-only cwd, missing node) would be held open forever.
   if (p.stop_hook_active) defer("stop_hook_active — at most one block per stop chain", "loop-guard");
 
-  const cwd = p.cwd || process.cwd();
+  // Receipts and the decision ledger sit at the project root, wherever the session's shell ended
+  // up (see `projectRoot`); a run started from the top must not read as "never started" because
+  // the last command `cd`ed somewhere.
+  const cwd = projectRoot(p.cwd || process.cwd());
   const events = readEvents(p.transcript_path);
   // no transcript → no facts → fail open
   if (!events || events.length === 0) defer("no readable transcript — no facts to assert", "no-transcript");

package/hooks/lib/decision.mjs

@@ -46,11 +46,52 @@
 // failed tool call: a receipt that can break a run would get the whole layer disabled, which is
 // the exact outcome this file exists to prevent. Every write here is inside a try/catch.
 
-import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { decisions } from "../../kernel/lib/paths.mjs";
+import { appendFileSync, mkdirSync, existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { decisions, activeScope, sharedDir } from "../../kernel/lib/paths.mjs";
 import { resolveRunId } from "../../kernel/lib/paths.mjs";
 
+/**
+ * The project root a hook should file under, from wherever the tool call happened to fire.
+ *
+ * THE HOOK PAYLOAD'S `cwd` FOLLOWS THE SHELL, NOT THE PROJECT. A worker that `cd`s into a
+ * sub-folder — a mobile app's module directory, a package in a monorepo, even the run trace
+ * itself while it inspects an artifact — fires every later hook with that folder as `cwd`. Read
+ * as the project root, that started a fresh `.shapeup/decisions.jsonl` in the sub-folder (nine of
+ * them on one measured run, one inside the committed tier and two inside the run trace), left
+ * every row there with `run_id: null` because the active-scope pointer was not beside it, and —
+ * the part that matters more than a split audit log — made `sandbox-guard` fail open on every
+ * write from that shell, since the active-order pointer it fences from was not beside it either.
+ *
+ * So the root is FOUND, not assumed: walk up from `cwd` to the nearest ancestor that carries a
+ * run pointer, the committed tier, or a git boundary. The order is the order of specificity — a
+ * live run outranks a repo boundary, so a project nested inside a larger repository still files
+ * under its own root — and a bare `.shapeup/` directory is deliberately NOT a marker, because the
+ * stray ledgers this fixes are exactly what would create one.
+ *
+ * Fail-open: no marker anywhere up the tree returns `cwd` unchanged, which is the pre-fix
+ * behaviour. Never throws.
+ *
+ * @param {string} cwd - Where the hook fired (`payload.cwd`, else the process cwd).
+ * @returns {string} The nearest project root at or above `cwd`, or `cwd` itself.
+ */
+export function projectRoot(cwd) {
+  let dir;
+  try { dir = resolve(cwd || process.cwd()); } catch { return cwd; }
+  const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+  for (let i = 0; i < 64; i++) {
+    try {
+      if (existsSync(activeScope(dir))) return dir;
+      if (isDir(sharedDir(dir))) return dir;
+      if (existsSync(resolve(dir, ".git"))) return dir;
+    } catch { /* unreadable ancestor — keep climbing */ }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return cwd;
+}
+
 /**
  * Where the receipts land.
  *
@@ -60,12 +101,14 @@ import { resolveRunId } from "../../kernel/lib/paths.mjs";
  * they were evaluations from a real run. A measurement instrument that its own test suite
  * contaminates is not an instrument.
  *
- * @param {string} [cwd] - Project root; defaults to the process cwd.
+ * @param {string} [cwd] - Where the hook fired; defaults to the process cwd. Resolved to the
+ *   project root through {@link projectRoot} — a hook fired from a sub-folder files under the
+ *   same ledger as one fired from the top.
  * @returns {string} The ledger path — `SHAPEUP_DECISIONS_PATH` when set, else the LOCAL root's
  *   `decisions.jsonl`, resolved through `lib/paths.mjs`.
  */
 export function decisionsPath(cwd) {
-  return process.env.SHAPEUP_DECISIONS_PATH || decisions(cwd || process.cwd());
+  return process.env.SHAPEUP_DECISIONS_PATH || decisions(projectRoot(cwd || process.cwd()));
 }
 
 /**
@@ -178,7 +221,7 @@ export async function runHook(name, fn) {
     // run, and recording that is what lets the export tier partition ambient decisions from run
     // ones. Resolution reads two small files and swallows every error — a receipt must never be
     // able to fail a tool call.
-    run_id: (() => { try { return resolveRunId(d.cwd || process.cwd()); } catch { return null; } })(),
+    run_id: (() => { try { return resolveRunId(projectRoot(d.cwd || process.cwd())); } catch { return null; } })(),
     event: d.event ?? null,
     tool: d.tool ?? null,
     subject: d.subject ?? null,

package/hooks/safety-spine.mjs

@@ -36,7 +36,7 @@ import { globToRegExp, logPathology } from "./sandbox-guard.mjs";
 import { isMain } from "../kernel/lib/argv.mjs";
 import { LOCAL, safetyOverrides, metricsShard } from "../kernel/lib/paths.mjs";
 
-import { runHook, readStdin, settle } from "./lib/decision.mjs";
+import { runHook, readStdin, settle, projectRoot } from "./lib/decision.mjs";
 
 // --- overrides ---------------------------------------------------------------
 
@@ -225,9 +225,12 @@ async function main() {
 
   if (!HOOK_TOOLS.has(p.tool_name)) defer(`${p.tool_name ?? "no tool_name"} is not a guarded tool — out of scope`);
 
+  // The envelope and the telemetry shard live at the project root; the shell may be anywhere below
+  // it (see `projectRoot`). A relative tool path still means "relative to the shell".
   const cwd = p.cwd || process.cwd();
-  const overrides = loadOverrides(cwd);
-  const metricsPath = metricsShard(cwd);
+  const root = projectRoot(cwd);
+  const overrides = loadOverrides(root);
+  const metricsPath = metricsShard(root);
 
   const deny = (category, reason, detail) => {
     logPathology(metricsPath, {
@@ -240,7 +243,7 @@ async function main() {
       ...detail,
     });
     settle({
-      verdict: "deny", event: "PreToolUse", tool: p.tool_name, cwd, rule: category,
+      verdict: "deny", event: "PreToolUse", tool: p.tool_name, cwd: root, rule: category,
       subject: detail?.path ?? detail?.command ?? null, reason,
       payload: {
         hookSpecificOutput: {
@@ -282,7 +285,7 @@ async function main() {
   }
 
   // Write | Edit | MultiEdit — only the self-protect rule; substrates stay sandbox-guard's job.
-  const overridesAbs = resolve(safetyOverrides(cwd));
+  const overridesAbs = resolve(safetyOverrides(root));
   const hit = extractPaths(p.tool_input).find((raw) => resolve(cwd, raw) === overridesAbs);
   if (hit) {
     deny("self-protect", `The safety-overrides file is human-authored only — the session must never widen (or remove) its own safety envelope. Ask the PO to edit ${LOCAL}/safety-overrides.json.`, { path: hit });

package/hooks/sandbox-guard.mjs

@@ -74,7 +74,7 @@ import { readFileSync, existsSync, appendFileSync, mkdirSync, readdirSync, statS
 import { resolve, join, relative, dirname, sep } from "node:path";
 import { isMain } from "../kernel/lib/argv.mjs";
 import { LOCAL, SHARED, activeOrder, ordersDir, resultsDir, metricsShard } from "../kernel/lib/paths.mjs";
-import { runHook, readStdin, settle } from "./lib/decision.mjs";
+import { runHook, readStdin, settle, projectRoot } from "./lib/decision.mjs";
 
 // --- tiny glob matcher: supports *, **, ? — enough for substrate globs, zero dependencies ---
 export function globToRegExp(glob) {
@@ -184,8 +184,15 @@ async function main() {
     defer(`${p.tool_name ?? "no tool_name"} is not a write tool — out of scope`);
   }
 
+  // WHERE THE SHELL IS versus WHERE THE PROJECT IS. `p.cwd` follows the worker's shell — a leg that
+  // `cd`s into a sub-folder fires this hook from there — and the pointer, the order set and the
+  // substrate globs all live at the project root. Read from the sub-folder, the pointer was simply
+  // absent and this guard deferred at `no-round` on every write from that shell: a substrate fence
+  // that switches off whenever the worker changes directory. Raw tool paths still resolve against
+  // the shell's own cwd, because that is what a relative path in the tool input means.
   const cwd = p.cwd || process.cwd();
-  const activeOrderPath = activeOrder(cwd);
+  const root = projectRoot(cwd);
+  const activeOrderPath = activeOrder(root);
   if (!existsSync(activeOrderPath)) defer("no active-order pointer — no tracked task running", "no-round");
 
   const active = readJSON(activeOrderPath);
@@ -202,7 +209,7 @@ async function main() {
   // Live = compiled and not yet answered. An order whose result is on disk has finished; leaving it
   // in the candidate set would keep a finished scope's substrate open for the rest of the run — and
   // leaving the POINTER's own order in unconditionally kept a finished RUN's substrate open forever.
-  const orders = liveOrders(cwd, active.slug);
+  const orders = liveOrders(root, active.slug);
   if (orders.length === 0) defer(`no live order for ${active.slug}`, "no-order");
 
   const withSubstrate = orders.filter((o) => o.substrate);
@@ -220,14 +227,14 @@ async function main() {
   const targetPaths = extractPaths(p.tool_input);
   if (targetPaths.length === 0) defer("no writable path in the tool input", "no-target");
 
-  const metricsPath = metricsShard(cwd);
+  const metricsPath = metricsShard(root);
   const runTracePrefix = join(LOCAL, active.slug) + sep;
   const violations = [];
   const blockReasons = [];
 
   for (const raw of targetPaths) {
     const abs = resolve(cwd, raw);
-    const rel = relative(cwd, abs);
+    const rel = relative(root, abs);
     if (rel.startsWith(runTracePrefix)) continue;
 
     // Frozen takes absolute precedence, and it is checked across EVERY live contract: a path one
@@ -283,7 +290,7 @@ async function main() {
   });
 
   return {
-    verdict: "deny", event: "PreToolUse", tool: p.tool_name, subject: active.order_path, cwd,
+    verdict: "deny", event: "PreToolUse", tool: p.tool_name, subject: active.order_path, cwd: root,
     rule: "outside-substrate",
     reason: `${violations.length} write(s) rejected by substrate boundaries: ${blockReasons.join("; ")}`,
     payload: {

package/kernel/compile.mjs

@@ -26,7 +26,7 @@
 // pretty-printed envelope, colocated so audits can read it). Prints the path on stdout.
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
-import { resolve, join, dirname, basename } from "node:path";
+import { resolve, join, dirname, basename, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { validate } from "./verify/envelope.mjs";
 import { readTrials } from "./verify/t0.mjs";
@@ -41,11 +41,22 @@ import {
 import { readContract, readAllContracts, tasksForScope, SCOPE_CONTRACT } from "./lib/contract.mjs";
 import { writeActiveOrder } from "./probe/resume.mjs";
 import { greenVerdict } from "./probe/t0.mjs";
+import { latestRoundBuild } from "./verify/build.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";
 
+/**
+ * Workers that read a coaching file. Kept beside the compile step because this is the only place
+ * the file is handed over: a worker not in this set never sees `payload.kb_rules_path`, however
+ * many rules the coach files for it. Mirrored by the coach skill's category list (structural test).
+ */
+export const COACHABLE = new Set([
+  "task-executor", "ba-pitch-analyzer", "qa-edge-hunter",
+  "orient", "scope-architect", "solution-architect",
+]);
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ORDER_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "./../skills/tech-lead/schemas/work-order.schema.json"), "utf8"));
 
@@ -167,13 +178,20 @@ export const OP_OWNER = {
   wire: "solution-architect", evaluate: "spec-evaluator", orient: "orient",
   hunt: "qa-edge-hunter", translate: "translator",
   hammer: "scope-hammer", coach: "coach",
+  // `scan` is the coach reading the project instead of L4 feedback, and `research` the coach
+  // reading the platform's official documentation instead of the project — a project with nothing
+  // on disk has nothing to scan. Same worker, same write surface, same categorization gate. An
+  // operation the schema enumerates but this table does not route compiles no order at all, so the
+  // suite checks the two the other way round as well.
+  scan: "coach",
+  research: "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.
  * @param {string} operation - The order's operation (execute|fix|spike|analyze|reconcile|
- *   retrofit-surface|coverage|map-scopes|wire|evaluate|orient|hunt|translate|hammer|coach).
+ *   retrofit-surface|coverage|map-scopes|wire|evaluate|orient|hunt|translate|hammer|coach|scan|research).
  * @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
@@ -236,6 +254,13 @@ export function substrateFor(operation, { slug, specDir, scope } = {}) {
     case "hammer":
       return { allowed: [globShared(slug, "REPORT.md"), `${local}/reports/**`] };
     case "coach":
+    case "scan":
+    case "research":
+      // `scan` seeds the same files from the project on disk and `research` from the platform's
+      // official documentation, instead of from L4 feedback; all three write only the knowledge
+      // base, and the profile they suggest probes for stays the tech lead's to write (single
+      // writer of the committed tier). Research is a source, not a verification: what it reads
+      // is still a claim until the tech lead pins it at L0 and the kernel runs it.
       return { allowed: [relKnowledgeBase("*")] };
     default:
       return { allowed: [`${local}/**`] };
@@ -379,6 +404,80 @@ export function verdictBugs(cwd, slug, round) {
   return v.bugs.filter((b) => !refuted.has(String(b?.id)) && !refuted.has(String(b?.criterion)));
 }
 
+/**
+ * The previous round's RED BUILD GATE, as bug entries the fix round can act on.
+ *
+ * THE JUDGE IS NOT THE ONLY SOURCE OF A FAIL. `verify build` runs the feature's build and its
+ * launch probe once per round, before EVAL, and a red gate ends the round with no verdict — there is
+ * nothing to grade in an app that does not compile or start. But a round that ends without a
+ * verdict left the next round with no `payload.bugs`, so it compiled as a plain `execute`, every
+ * worker re-ran its fixtures, found them green (they never tested the build) and reported done —
+ * the identical loop the ledgered verdict was threaded through {@link verdictBugs} to break.
+ *
+ * So a failing step becomes a bug: the criterion is the command that must exit 0, the locator is
+ * every file the tool's own output names that exists in the tree, and the evidence is the output's
+ * tail. Addressed by {@link bugsForScope} exactly like a judged defect — the scope whose substrate
+ * holds the cited file gets it, and a failure citing no file goes to every scope marked `unowned`.
+ *
+ * @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>} One entry per failing step of the previous round's latest gate
+ *   artifact; empty when the gate did not run, was green, or this is round 1.
+ */
+export function buildBugs(cwd, slug, round) {
+  if (!round || round < 2) return [];
+  const gate = latestRoundBuild(cwd, slug, round - 1);
+  if (!gate || gate.overall !== "red") return [];
+  const out = [];
+  for (const step of gate.steps || []) {
+    if (step.skipped || step.pass) continue;
+    const text = `${step.stdout_tail || ""}\n${step.stderr_tail || ""}`;
+    const files = outputPaths(text, cwd);
+    out.push({
+      id: `BUILD-r${round - 1}-${step.kind}`,
+      severity: "blocker",
+      source: "verify build",
+      criterion: `${step.kind} exits 0: ${step.cmd}`,
+      location: files.join(", "),
+      expected: "exit 0",
+      actual: step.error ? `did not run: ${step.error}` : `exit ${step.exit}`,
+      evidence: (step.stderr_tail || step.stdout_tail || "").slice(-2000),
+      digest: Array.isArray(gate.discovered_tasks) ? gate.discovered_tasks.slice(0, 8) : [],
+    });
+  }
+  return out;
+}
+
+/**
+ * The project files a build or launch log names, repo-relative and de-duplicated.
+ *
+ * Wider than {@link bugLocations} in one way and narrower in another: it accepts absolute paths
+ * (compilers print them) and strips the project root off; and it keeps only paths that EXIST under
+ * the project, because a tool's own stack frames and cache paths look exactly like file citations
+ * and would address the bug to nobody. First-seen order.
+ *
+ * @param {string} text - Raw log text.
+ * @param {string} cwd - Project root.
+ * @returns {string[]} Repo-relative POSIX paths.
+ */
+export function outputPaths(text, cwd) {
+  const out = [];
+  const root = resolve(cwd);
+  for (const m of String(text || "").matchAll(/(?:^|[\s(,\[:"'`])((?:\/|\.\/)?[\w@][\w.\/-]*\.[A-Za-z][A-Za-z0-9]{0,5})(?::\d+)?/gm)) {
+    let p = m[1].replace(/^\.\//, "");
+    if (p.startsWith("/")) {
+      const rel = relative(root, p);
+      if (!rel || rel.startsWith("..")) continue;
+      p = rel.split(sep).join("/");
+    }
+    if (out.includes(p)) continue;
+    if (!existsSync(join(root, p))) continue;
+    out.push(p);
+  }
+  return out;
+}
+
 /**
  * Every repo-relative file a bug is cited against.
  *
@@ -543,7 +642,7 @@ export function t0ArtifactsFor(cwd, slug, round) {
  * @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
+ *   payload{…}}. A coachable worker ({@link COACHABLE}) also gets payload.kb_rules_path. Not validated here — the CLI
  *   validates before writing.
  */
 export function compileOrder({
@@ -620,8 +719,12 @@ export function compileOrder({
       ...(payloadExtra || {}),
     },
   };
-  const kbByWorker = { "task-executor": "task-executor", "ba-pitch-analyzer": "ba-pitch-analyzer", "qa-edge-hunter": "qa-edge-hunter" };
-  if (kbByWorker[worker]) order.payload.kb_rules_path = relKnowledgeBase(kbByWorker[worker]);
+  // The coachable set — every worker that reads `shapeup/knowledge-base/<worker>.md` at the top
+  // of its run. Guidance only: a rule here steers craft and never resolves, skips or reorders a
+  // gate, and never widens a substrate (the sandbox hook reads the order, not the KB). The judge
+  // (spec-evaluator) and the census (scope-hammer) are excluded on purpose: coaching the judge
+  // makes a second grader, and the hammer's ownership claims must come from `probe owner`.
+  if (COACHABLE.has(worker)) order.payload.kb_rules_path = relKnowledgeBase(worker);
   return order;
 }
 
@@ -695,7 +798,10 @@ export async function cli(rawArgv) {
   // 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)) : [];
+  // Two sources, one channel: the judge's cited defects and the build gate's failing steps.
+  const bugs = scope
+    ? bugsForScope([...verdictBugs(cwd, slug, round), ...buildBugs(cwd, slug, round)], scope.scope_id, scopeSubstrates(cwd, slug))
+    : [];
 
   // A ROUND CARRYING CITED DEFECTS IS A `fix`, AND THE ORDER HAS TO SAY SO.
   //

package/kernel/harness.mjs

@@ -21,14 +21,17 @@
 //
 //   verify   t0 · budget · envelope ·        Measured, not claimed. A model verifying itself is
 //            trace · spec · skills ·          claiming; these read artifacts and re-hash them.
-//            dispatch                         `skills` reads the roster off disk; `dispatch` reads
+//            dispatch · build                 `skills` reads the roster off disk; `dispatch` reads
 //                                             the hook layer's evidence that a skill really resolved
 //                                             in this session — the half a file check cannot answer.
+//                                             `build` runs the feature's build and launch probes once
+//                                             per round before EVAL — T0 is per scope and proves
+//                                             nothing about whether the whole compiles or starts.
 //   reduce   ingest · hill · snapshot ·       Single writer. Shared state has exactly one author.
 //            ship · board · verdict · graph
 //   gate                                      An answer file with a source, not a vibe.
 //   probe    resume · t0 · stats · digest ·   Read-only queries over run state. `concurrency`
-//            concurrency · leg · eval          answers how many legs ran at once and what the
+//            concurrency · leg · eval · owner  answers how many legs ran at once and what the
 //                                              fan-out bought, and refuses a figure the record set
 //                                              cannot support rather than printing a plausible one.
 //                                              `leg` answers whether a scope's work reached the
@@ -39,7 +42,10 @@
 //                                              `eval` answers what an EVAL round's WorkResult
 //                                              actually said, mechanically — the round-loop branch
 //                                              reads this instead of trusting a dispatching agent's
-//                                              own end-of-turn summary of its own verdict.
+//                                              own end-of-turn summary of its own verdict. `owner`
+//                                              answers which scope may write a path, elected from
+//                                              the contracts — so a census cites it instead of
+//                                              asserting ownership from memory.
 //   init     run · fit                        Opens a run, or refuses it (exit 3).
 //   report   export                           Projects the run's records as fact tables.
 //   compile                                   The WorkOrder: schema-valid or nothing is dispatched.
@@ -64,7 +70,7 @@ export const ROUTES = {
   verify: {
     t0: "./verify/t0.mjs", budget: "./verify/budget.mjs", envelope: "./verify/envelope.mjs",
     trace: "./verify/trace.mjs", spec: "./verify/spec.mjs", skills: "./verify/skills.mjs",
-    dispatch: "./verify/dispatch.mjs",
+    dispatch: "./verify/dispatch.mjs", build: "./verify/build.mjs",
   },
   reduce: {
     ingest: "./reduce/ingest.mjs", hill: "./reduce/hill.mjs", snapshot: "./reduce/snapshot.mjs",
@@ -74,7 +80,7 @@ export const ROUTES = {
   probe: {
     resume: "./probe/resume.mjs", t0: "./probe/t0.mjs", stats: "./probe/stats.mjs",
     digest: "./probe/digest.mjs", concurrency: "./probe/concurrency.mjs",
-    leg: "./probe/leg.mjs", eval: "./probe/eval.mjs",
+    leg: "./probe/leg.mjs", eval: "./probe/eval.mjs", owner: "./probe/owner.mjs",
   },
   init: { run: "./init/run.mjs", fit: "./init/fit.mjs" },
   report: { export: "./report/export.mjs", _default: "export" },