shapeup-sdlc 3.1.2 → 3.3.0

package/kernel/init/run.mjs

@@ -54,6 +54,7 @@
 //   --spec-folder   SHARED spec deliverable path      (default: shapeup/<slug>/spec/)
 //   --dimensions    comma-separated eval dimensions   (default: spec-conformance)
 //   --gate-answers  path | preset name                (see `harness gate`; recorded, not read)
+//   --breadboard    path to the pitch's breadboard     (default: found — see resolveBreadboard())
 //   --wall-clock-budget N  deadline breaker, seconds  (off by default; see `harness verify budget`)
 //   --cwd           project root                      (default: process.cwd())
 //   --force         re-init over an existing run receipt
@@ -68,8 +69,8 @@
 // that takes a phase, not an init-run flag that takes a slug: the one instruction available at the
 // one moment it mattered named a mechanism that does not parse.
 
-import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, copyFileSync, rmSync } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, copyFileSync, rmSync, statSync } from "node:fs";
+import { join, dirname, resolve, relative, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { decideLane, treeSize } from "./fit.mjs";
 import { runArgs } from "../lib/argv.mjs";
@@ -78,8 +79,9 @@ import { deriveSnapshot } from "../reduce/snapshot.mjs";
 import { mintRunId } from "../lib/paths.mjs";
 import {
   localRoot, activeScope, activeOrder, globLocal, globShared, ordersDir, resultsDir,
-  workflowsStage, globWorkflowsStage,
+  workflowsStage, globWorkflowsStage, sharedRoot, shapingDir, breadboard as stagedBreadboard,
 } from "../lib/paths.mjs";
+import { parseBreadboard, hasBreadboardTables, idCounts } from "../lib/breadboard.mjs";
 import { resolveWorkers } from "../verify/skills.mjs";
 
 export const RECEIPT_VERSION = 1;
@@ -132,8 +134,19 @@ export function digest(text) {
 /**
  * Build the receipt record. Pure — takes resolved inputs, returns the object that gets written.
  * Kept separate from I/O so the structural tests can assert its shape without a filesystem.
+ *
+ * @param {object} o - Resolved inputs (destructured).
+ * @param {string} o.slug - Feature slug.
+ * @param {string} o.intake - The intake text, verbatim.
+ * @param {object} o.config - The pinned run config.
+ * @param {string} o.startedAt - ISO start time.
+ * @param {(object|null)} [o.plugin] - The plugin copy that answered.
+ * @param {(string|null)} [o.intakeSource] - Repo-relative `--intake-file` path, or "text" / "stdin".
+ * @param {({source: string, path: (string|null), text: string, translated?: boolean}|null)} [o.breadboard] -
+ *   The resolved breadboard, `path` repo-relative (null when embedded in the intake), or null.
+ * @returns {object} The receipt.
  */
-export function buildReceipt({ slug, intake, config, startedAt, plugin = null }) {
+export function buildReceipt({ slug, intake, config, startedAt, plugin = null, intakeSource = null, breadboard = null }) {
   const intakeText = String(intake ?? "");
   const intakeSha256 = digest(intakeText);
   return {
@@ -156,6 +169,23 @@ export function buildReceipt({ slug, intake, config, startedAt, plugin = null })
     intake_sha256: intakeSha256,
     intake_chars: intakeText.length,
     intake_lines: intakeText ? intakeText.split("\n").length : 0,
+    // WHERE THE INTAKE CAME FROM. The copy above is all the run reads, so without its origin nothing
+    // on disk says which file the pitch was — or that it had a second half beside it.
+    intake_source: intakeSource,
+    // THE PITCH'S OTHER HALF. A `/shapeup` pitch is shaping.md + breadboard.md, and a Place that only
+    // the breadboard names reaches no planning worker unless the run carries it. Recorded here, at
+    // t=0, rather than left to a worker to note: the kernel knows whether a breadboard exists before
+    // anything is dispatched, and a worker's prose rule for exactly this case did not hold.
+    breadboard: breadboard
+      ? {
+          source: breadboard.source,
+          path: breadboard.path ?? null,
+          sha256: digest(breadboard.text),
+          chars: String(breadboard.text ?? "").length,
+          ids: idCounts(parseBreadboard(breadboard.text)),
+          ...(typeof breadboard.translated === "boolean" ? { translated: breadboard.translated } : {}),
+        }
+      : null,
     // The single fact that separates "the harness ran" from "the harness described itself".
     // Written before any gate, so its ABSENCE at Stop is unambiguous.
     started: true,
@@ -312,6 +342,70 @@ export function stageWorkflows(cwd, pluginRoot, { refresh = true } = {}) {
   return { ok: true, dir, staged: names };
 }
 
+/**
+ * Find the breadboard that belongs to this run's pitch. First hit wins:
+ *
+ *   1. `flag`        — `--breadboard <path>`, resolved against cwd; a missing file is an error.
+ *   2. `sibling`     — `breadboard.md` in the folder of `--intake-file` (not for text or stdin).
+ *   3. `shaping-dir` — `shapeup/<slug>/shaping/breadboard.md`, the documented location.
+ *   4. `shared-root` — `shapeup/<slug>/breadboard.md`, the flat layout real projects use.
+ *   5. `embedded`    — the intake itself, when it carries Places and UI tables; nothing is staged.
+ *
+ * THE INTAKE'S OWN FOLDER COMES FIRST, not the documented location, because the only consumer that
+ * hit this keeps its pitch flat in `shapeup/<slug>/`: a lookup that reads only the shaping folder
+ * passes every fixture built to the documented layout and misses the real one.
+ *
+ * A discovered candidate that is the intake file itself, or the run's own staged copy, is skipped:
+ * the staged copy is this function's OUTPUT, and re-opening a run from its staged intake must not
+ * inherit the breadboard of the run it replaces.
+ *
+ * A TRANSLATED PITCH GETS ITS TRANSLATED BREADBOARD. When the intake is a translator output
+ * (`<name>.en.md`), each folder is tried for `breadboard.en.md` before `breadboard.md`, and the
+ * result says whether it is translated — an English spec planned from a source-language breadboard
+ * is a mismatch the caller reports, not one it may silently stage.
+ *
+ * @param {object} o - Inputs (destructured).
+ * @param {string} o.cwd - Project root.
+ * @param {string} o.slug - Feature slug.
+ * @param {(string|null)} [o.intakeFile] - The `--intake-file` value as given ("-" = stdin).
+ * @param {(string|null)} [o.flag] - The `--breadboard` value as given.
+ * @param {string} [o.intake] - The intake text, for the embedded case.
+ * @returns {({source: string, path: (string|null), text: string, translated?: boolean}|null)} The
+ *   breadboard, its absolute path (null when embedded), and its text — plus `translated` when the
+ *   intake is a `.en.md` translation; or null when the pitch has none.
+ * @throws {Error} If `--breadboard` names a file that does not exist.
+ */
+export function resolveBreadboard({ cwd, slug, intakeFile = null, flag = null, intake = "" }) {
+  const self = intakeFile && intakeFile !== "-" ? resolve(cwd, intakeFile) : null;
+  const english = Boolean(self && self.endsWith(".en.md"));
+  /** Tag a hit with whether it is translated — only meaningful when the intake is. */
+  const hit = (source, p, text) => ({ source, path: p, text, ...(english ? { translated: p === null || p.endsWith(".en.md") } : {}) });
+  if (flag) {
+    const p = resolve(cwd, flag);
+    if (!existsSync(p) || !statSync(p).isFile()) throw new Error(`--breadboard not found: ${p}`);
+    return hit("flag", p, readFileSync(p, "utf8"));
+  }
+  const staged = stagedBreadboard(cwd, slug);
+  const names = english ? ["breadboard.en.md", "breadboard.md"] : ["breadboard.md"];
+  const folders = [
+    ...(self ? [["sibling", dirname(self)]] : []),
+    ["shaping-dir", shapingDir(cwd, slug)],
+    ["shared-root", sharedRoot(cwd, slug)],
+  ];
+  for (const [source, dir] of folders) {
+    for (const n of names) {
+      const p = join(dir, n);
+      if (p === self || p === staged) continue;
+      if (existsSync(p) && statSync(p).isFile()) return hit(source, p, readFileSync(p, "utf8"));
+    }
+  }
+  if (hasBreadboardTables(intake)) return hit("embedded", null, String(intake));
+  return null;
+}
+
+/** A path relative to the project root, `/`-joined on every platform — the form a receipt records. */
+const repoRel = (cwd, p) => relative(cwd, p).split(sep).join("/");
+
 // ---- CLI -------------------------------------------------------------------
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
@@ -319,7 +413,7 @@ export const ARGV_SPEC = {
   usage: 'harness.mjs init run (--intake-file <path> | --intake-text "<req>" | --intake-stdin) ' +
          "[--slug <slug>] [--auto-level interactive|auto|unattended] [--lens <lens>] " +
          "[--max-rounds N] [--attempts N] [--spec-folder <dir>] [--dimensions <a,b>] " +
-         "[--gate-answers <preset|path>] " +
+         "[--gate-answers <preset|path>] [--breadboard <path>] " +
          "[--lane full|tiny] [--tiny] [--wall-clock-budget <seconds>] [--cwd <dir>] " +
          "[--plugin-root <dir>] [--force]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
@@ -335,6 +429,7 @@ export const ARGV_SPEC = {
   "spec-folder": { type: "path" },
   dimensions: { type: "str" },
   "gate-answers": { type: "str" },
+  breadboard: { type: "path" },
   lane: { type: "str" },
   tiny: { type: "flag" },
   "wall-clock-budget": { type: "int", min: 1 },
@@ -423,6 +518,16 @@ export function cli(rawArgv) {
   let eval_dimensions;
   try { eval_dimensions = parseDimensions(args.dimensions ?? null); }
   catch (e) { fail(2, e.message); }
+  // The pitch's second half, resolved before anything is written so a bad `--breadboard` is a usage
+  // error that ran nothing. Read-only here; staged below, once the run is actually opened.
+  let bb = null;
+  try { bb = resolveBreadboard({ cwd, slug, intakeFile, flag: args.breadboard ?? null, intake }); }
+  catch (e) { fail(2, e.message); }
+  if (bb?.translated === false) {
+    console.error(`⚠ init-run: the intake is a translation but its breadboard is not — staging ${repoRel(cwd, bb.path)} as found.`);
+    console.error("  Translate the breadboard too (translator), and name the .en.md with --breadboard, or the spec is planned from two languages.");
+  }
+  const intakeSource = args.intakeStdin || intakeFile === "-" ? "stdin" : intakeFile ? repoRel(cwd, resolve(cwd, intakeFile)) : "text";
 
   const config = {
     auto_level,
@@ -532,7 +637,10 @@ export function cli(rawArgv) {
   }
 
   const startedAt = new Date().toISOString();
-  const receipt = buildReceipt({ slug, intake, config, startedAt, plugin });
+  const receipt = buildReceipt({
+    slug, intake, config, startedAt, plugin, intakeSource,
+    breadboard: bb ? { ...bb, path: bb.path ? repoRel(cwd, bb.path) : null } : null,
+  });
 
   mkdirSync(runRoot, { recursive: true });
   mkdirSync(join(runRoot, "orders"), { recursive: true });
@@ -541,6 +649,10 @@ export function cli(rawArgv) {
 
   // The intake, verbatim. So "the spec was dropped on the hand-off" is a checkable claim.
   writeFileSync(join(runRoot, "intake.md"), intake.endsWith("\n") ? intake : intake + "\n", "utf8");
+  // The breadboard, verbatim — byte for byte, so the receipt's digest is the file's. A copy left by a
+  // run this one replaces goes first: a re-open without a breadboard must not inherit the last one.
+  rmSync(stagedBreadboard(cwd, slug), { force: true });
+  if (bb?.path) writeFileSync(stagedBreadboard(cwd, slug), bb.text, "utf8");
   writeFileSync(receiptPath, JSON.stringify(receipt, null, 2) + "\n", "utf8");
   writeFileSync(join(runRoot, "harness-run.md"), runFrontmatter({ slug, config, startedAt }), "utf8");
 
@@ -558,6 +670,10 @@ export function cli(rawArgv) {
     receipt: globLocal(slug, "receipt.json"),
     intake_sha256: receipt.intake_sha256,
     intake_chars: receipt.intake_chars,
+    // The staged breadboard the planning dispatches are handed, or null when the pitch has none
+    // separate (`breadboard_source` then says "embedded" or null).
+    breadboard: bb?.path ? globLocal(slug, "breadboard.md") : null,
+    breadboard_source: bb?.source ?? null,
     config,
     // What the launch names. Project-local by necessity, not by preference — see stageWorkflows().
     workflow_script: staged.ok ? globWorkflowsStage("shapeup-run.js") : null,

package/kernel/lib/breadboard.mjs

@@ -0,0 +1,165 @@
+// breadboard — read a `/shapeup` breadboard's element ids out of its markdown tables.
+//
+// WHY THIS EXISTS. A pitch is two files: `shaping.md` (problem, requirements, parts) and
+// `breadboard.md` (Places, affordances, slices). The run used to take only the first, so a Place
+// that existed only in the breadboard — a new sheet, a new modal — reached no planning worker, and
+// the spec folded it into whichever screen the prose happened to mention. The ids read here are what
+// the run pins at open (the receipt's counts) and what spec-lint checks placement against.
+//
+// WHAT IT READS, and nothing more. An element id is the FIRST cell of a markdown table row —
+// `P1`, `P2.1`, `U3`, `N1b`, `S2`, `V4` — after stripping `**` and backticks, so both table layouts
+// the breadboarding guide ships parse the same way: a `#` first column and an `ID` first column. A
+// row's Places come from its `Place` column, every `P#` token in the cell (`P1 / P3`, `P2/P1`); a
+// table with no Place column gives its rows no Places. Places may also be listed as prose under a
+// `## Places` heading (`P1: Composer — …`), which is the guide's own output template.
+//
+// It skips fenced code blocks: a table inside a fence is an example of a breadboard, not this one.
+//
+// Tolerant by design. A layout this reader cannot parse yields zero ids, and every caller treats
+// zero ids as "nothing to check" plus a warning — never as a hard stop. Zero dependencies.
+
+/** A first-cell element id: a Place (`P1`, `P2.1`), or a UI/code affordance, store or slice. */
+export const ID_PATTERN = /^(P\d+(?:\.\d+)*|[UNSV]\d+[a-z]?)$/;
+
+/** Every Place reference inside a cell. Global — use with `match`, never `test`. */
+const PLACE_REF = /\bP\d+(?:\.\d+)*\b/g;
+
+/** A prose Place line under `## Places`: `P1: …`, `- P1 — …`, `**P2** – …`. */
+const PROSE_PLACE = /^\s*(?:[-*+]\s+)?\**(P\d+(?:\.\d+)*)\**\s*[:—–-]\s*(.*)$/;
+
+/**
+ * Split one markdown table row into trimmed cells.
+ * @param {string} line - A line that starts with `|`.
+ * @returns {string[]} The cells between the outer pipes.
+ */
+function cells(line) {
+  const t = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  return t.split("|").map((c) => c.trim());
+}
+
+/**
+ * Strip the emphasis and code marks a breadboard author puts around an id.
+ * @param {string} cell - A raw table cell.
+ * @returns {string} The cell's text without `**` and backticks.
+ */
+function bare(cell) {
+  return String(cell ?? "").replace(/\*\*/g, "").replace(/`/g, "").trim();
+}
+
+/**
+ * Is this line a table's header separator (`|---|:--:|`)?
+ * @param {string} line - A table line.
+ * @returns {boolean} True for a separator row.
+ */
+function isSeparator(line) {
+  return /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(line);
+}
+
+/**
+ * Parse a breadboard's element ids.
+ *
+ * @param {string} text - The breadboard markdown (or a pitch that carries one inline).
+ * @returns {{places: {id: string, name: string}[], ui: {id: string, places: string[]}[],
+ *   code: {id: string, places: string[]}[], stores: {id: string, places: string[]}[],
+ *   slices: {id: string}[]}} Every id found, de-duplicated by id; a repeated row merges its Places.
+ */
+export function parseBreadboard(text) {
+  const lines = String(text ?? "").split(/\r?\n/);
+  const places = new Map();
+  const byKind = { U: new Map(), N: new Map(), S: new Map(), V: new Map() };
+
+  const addPlace = (id, name) => {
+    if (!places.has(id)) places.set(id, { id, name: name || "" });
+    else if (!places.get(id).name && name) places.get(id).name = name;
+  };
+  const addElement = (id, refs) => {
+    const m = byKind[id[0]];
+    if (!m.has(id)) m.set(id, new Set());
+    for (const p of refs) m.get(id).add(p);
+  };
+
+  let inFence = false;
+  let inPlacesSection = false;
+  let header = null; // the current table's header cells, lower-cased
+  let prevWasTable = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; prevWasTable = false; header = null; continue; }
+    if (inFence) continue;
+
+    const heading = line.match(/^\s*#{1,6}\s+(.*)$/);
+    if (heading) {
+      inPlacesSection = /^places\b/i.test(bare(heading[1]));
+      prevWasTable = false; header = null;
+      continue;
+    }
+
+    if (/^\s*\|/.test(line)) {
+      if (!prevWasTable) {
+        // A table starts here. Its first line is the header when the next line is a separator.
+        header = isSeparator(lines[i + 1] ?? "") ? cells(line).map((c) => bare(c).toLowerCase()) : null;
+        prevWasTable = true;
+        if (header) continue;
+      }
+      if (isSeparator(line)) continue;
+      const row = cells(line);
+      const id = bare(row[0]);
+      if (!ID_PATTERN.test(id)) continue;
+      const placeCol = header ? header.indexOf("place") : -1;
+      if (id[0] === "P") {
+        const nameCol = placeCol > 0 ? placeCol : (header ? header.findIndex((h) => h === "name") : -1);
+        addPlace(id, bare(row[nameCol > 0 ? nameCol : 1] ?? ""));
+      } else {
+        const cell = placeCol > 0 ? bare(row[placeCol] ?? "") : "";
+        addElement(id, cell.match(PLACE_REF) ?? []);
+      }
+      continue;
+    }
+    prevWasTable = false; header = null;
+
+    if (inPlacesSection) {
+      const m = line.match(PROSE_PLACE);
+      if (m) addPlace(m[1], bare(m[2]).split(/\s+[—–-]\s+/)[0]);
+    }
+  }
+
+  const list = (m) => [...m].map(([id, refs]) => ({ id, places: [...refs] }));
+  return {
+    places: [...places.values()],
+    ui: list(byKind.U),
+    code: list(byKind.N),
+    stores: list(byKind.S),
+    slices: [...byKind.V.keys()].map((id) => ({ id })),
+  };
+}
+
+/**
+ * Does this text carry a breadboard of its own — at least one Place and one UI affordance?
+ *
+ * The test for a pitch that embeds its breadboard inline rather than as a second file. Both are
+ * required: a shaping doc routinely has tables, and a Place with nothing to place is not a
+ * breadboard anything downstream can check.
+ *
+ * @param {string} text - Markdown to inspect.
+ * @returns {boolean} True when `parseBreadboard` finds a P# and a U#.
+ */
+export function hasBreadboardTables(text) {
+  const bb = parseBreadboard(text);
+  return bb.places.length > 0 && bb.ui.length > 0;
+}
+
+/**
+ * Count a parsed breadboard's ids by kind, the shape the run receipt records.
+ * @param {ReturnType<typeof parseBreadboard>} parsed - A `parseBreadboard` result.
+ * @returns {{P: number, U: number, N: number, S: number, V: number}} Ids per kind.
+ */
+export function idCounts(parsed) {
+  return {
+    P: parsed.places.length,
+    U: parsed.ui.length,
+    N: parsed.code.length,
+    S: parsed.stores.length,
+    V: parsed.slices.length,
+  };
+}

package/kernel/lib/paths.mjs

@@ -91,7 +91,7 @@ export const localRoot = (cwd, slug) => join(cwd, LOCAL, slug);
 export const specDir = (cwd, slug) => join(sharedRoot(cwd, slug), "spec");
 /** Use-case directory inside the spec tree. */
 export const usecasesDir = (cwd, slug) => join(specDir(cwd, slug), "usecases");
-/** Shaping artifacts — pitch, framing, breadboard, baseline, glossary. */
+/** Shaping artifacts — pitch, framing, breadboard, baseline, glossary. `init run` looks here for a breadboard. */
 export const shapingDir = (cwd, slug) => join(sharedRoot(cwd, slug), "shaping");
 // The three contracts are markdown on disk and JSON on the wire (ADR-0001) — see
 // `lib/contract.mjs`. `readContract()` accepts either extension, so a project mid-migration
@@ -111,7 +111,7 @@ export const requirements = (cwd, slug) => join(sharedRoot(cwd, slug), "requirem
 export const hillDir = (cwd, slug) => join(sharedRoot(cwd, slug), "hill");
 /** The frozen ship report, written once at GATE L4. */
 export const report = (cwd, slug) => join(sharedRoot(cwd, slug), "REPORT.md");
-/** Team-shared coaching rules, read back by the three coachable workers. */
+/** Team-shared coaching rules, read back by the coachable workers and by the tech lead at GATE L0. */
 export const knowledgeBaseDir = (cwd) => join(sharedDir(cwd), "knowledge-base");
 /** One worker's coaching file. */
 export const knowledgeBase = (cwd, skill) => join(knowledgeBaseDir(cwd), `${skill}.md`);
@@ -138,6 +138,8 @@ export const RECEIPT_FILE = "receipt.json";
 export const receipt = (cwd, slug) => join(localRoot(cwd, slug), RECEIPT_FILE);
 /** The intake, verbatim, next to its digest in the receipt. */
 export const intake = (cwd, slug) => join(localRoot(cwd, slug), "intake.md");
+/** The breadboard the pitch was shaped with, verbatim, next to its digest in the receipt. */
+export const breadboard = (cwd, slug) => join(localRoot(cwd, slug), "breadboard.md");
 /** The run ledger — rounds, decisions, status frontmatter. */
 export const harnessRun = (cwd, slug) => join(localRoot(cwd, slug), "harness-run.md");
 /** File-derived mid-run digest, frozen by `reduce snapshot --write` as an audit anchor. */
@@ -206,6 +208,16 @@ export const trials = (cwd, slug) => join(t0Dir(cwd, slug), "trials.jsonl");
 export const gates = (cwd, slug) => join(localRoot(cwd, slug), "gates.jsonl");
 /** Finished-scope fixture registry for the seesaw regression check. */
 export const seesawRegistry = (cwd, slug) => join(localRoot(cwd, slug), "seesaw", "registry.json");
+/**
+ * The round build gate's verdicts — one immutable artifact per gate run, `r<N>-t<T>.json`.
+ *
+ * A separate directory from `t0/`, on purpose. A T0 verdict is one scope's fixtures inside that
+ * scope's substrate; this is the FEATURE's build, launched the way the ledger's `run_cmd` and the
+ * profile's probes say a user would, and it belongs to no scope. Written by `harness verify build`,
+ * read by `reduce hill` (a green T0 in a round whose build is red moves no dot) and by
+ * `harness compile` (a red gate is the next round's bug list).
+ */
+export const roundBuildDir = (cwd, slug) => join(localRoot(cwd, slug), "build");
 /** Evaluator output — report, evidence, verdict ledger. */
 export const evaluationDir = (cwd, slug) => join(localRoot(cwd, slug), "evaluation");
 /** The workflow launcher's run directory — `journal.jsonl` and the launch `result.json`. */
@@ -383,7 +395,7 @@ export const globShared = (slug, ...parts) => [SHARED, slug, ...parts].join("/")
 
 /**
  * The coaching file a coachable worker reads, as a repo-relative path for the WorkOrder payload.
- * @param {string} skill - Worker name (task-executor | ba-pitch-analyzer | qa-edge-hunter).
+ * @param {string} skill - A coachable worker name (`COACHABLE` in compile.mjs), or `tech-lead`.
  * @returns {string} e.g. `shapeup/knowledge-base/task-executor.md`.
  */
 export const relKnowledgeBase = (skill) => [SHARED, "knowledge-base", `${skill}.md`].join("/");

package/kernel/probe/owner.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// probe owner — which scope owns a path, derived from the contracts and nothing else.
+//
+// WHY THIS IS A QUERY AND NOT A SENTENCE. GATE H's census stated ownership facts without reading
+// the contracts: a ship report said no scope owned the app's page files, while the composition
+// root's committed substrate listed `pages/**` in plain sight. The real gap was elsewhere (a route
+// table naming files nobody had written), and the report pointed the PO at a scope cut that was
+// not the problem. A census that narrates ownership from memory is a census that can be wrong in
+// exactly the way that looks most authoritative.
+//
+// Ownership already has ONE mechanical definition in this plugin — the substrate the sandbox hook
+// enforces, and the election `harness compile` runs to address a cited bug to the scope that may
+// write the file (`electOwner`). This probe exposes that same answer on the command line, so a
+// worker that needs to say "no scope owns X" can cite the query instead of asserting it.
+//
+// With no `--path`, the input set is what a census would ask about anyway: every engine and
+// entry-point call site the wiring map names, plus the profile's entry point. A row with no
+// writers is an UNOWNED SEAM — the one kind of gap the disjointness lint cannot see, since DISJOINT
+// fails two owners and nothing fails zero.
+//
+// Usage:
+//   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe owner --slug <slug> [--path <p>]... [--format json|table] [--cwd <dir>]
+//
+// Exit code: 0 = answered, 2 = bad argv or no readable scope contracts.
+
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { runArgs, isMain } from "../lib/argv.mjs";
+import { wiringMap, projectProfile } from "../lib/paths.mjs";
+import { readContract, WIRING_MAP, PROJECT_PROFILE } from "../lib/contract.mjs";
+import { scopeSubstrates, electOwner, bugLocations } from "../compile.mjs";
+import { matchesAny } from "../../hooks/sandbox-guard.mjs";
+
+/**
+ * Ownership of one repo-relative path under a set of scope substrates.
+ *
+ * @param {string} path - Repo-relative POSIX path.
+ * @param {Array<{scope_id:string, allowed:string[], shared:string[]}>} scopes - From
+ *   {@link scopeSubstrates}.
+ * @param {string} [cwd] - Project root; when given, `exists` says whether the path is on disk.
+ * @returns {{path:string, owner:(string|null), writers:string[], shared_with:string[], exists:(boolean|null)}}
+ *   `owner` is the elected fixer (exclusive first, lowest id among equals); `writers` every scope
+ *   whose substrate admits the path; `shared_with` the writers that declare it shared. Empty
+ *   `writers` means no scope may write the file — an unowned path. `exists` is the other half a
+ *   census needs: a seam that is owned but not on disk is a route to a file nobody wrote.
+ */
+export function ownership(path, scopes, cwd = null) {
+  const rel = String(path).replace(/^\.\//, "");
+  const writers = (scopes || []).filter((s) => matchesAny(rel, s.allowed)).map((s) => s.scope_id).sort();
+  const shared = (scopes || []).filter((s) => matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
+  return { path: rel, owner: electOwner(rel, scopes), writers, shared_with: shared, exists: cwd ? existsSync(join(cwd, rel)) : null };
+}
+
+/**
+ * The paths a census asks about when none are given: the wiring map's engines and entry call
+ * sites, and the profile's entry point. Only tokens that look like files are kept — an entry call
+ * site is prose around a path (`src/server.ts — POST /checkout route`), and the path is what the
+ * substrate can answer for.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {Array<{path:string, cited_by:string}>} Distinct paths with where each was named.
+ */
+export function seamPaths(cwd, slug) {
+  const out = [];
+  const seen = new Set();
+  const add = (p, by) => { if (p && !seen.has(p)) { seen.add(p); out.push({ path: p, cited_by: by }); } };
+  const wm = wiringMap(cwd, slug);
+  if (existsSync(wm)) {
+    const entries = readContract(wm, WIRING_MAP)?.contract?.entries || [];
+    for (const e of entries) {
+      for (const p of bugLocations({ location: e.engine })) add(p, `${e.use_case || "?"} engine`);
+      for (const p of bugLocations({ location: e.entry_call_site })) add(p, `${e.use_case || "?"} entry_call_site`);
+    }
+  }
+  const pp = projectProfile(cwd, slug);
+  if (existsSync(pp)) {
+    const ep = readContract(pp, PROJECT_PROFILE)?.contract?.entry_point;
+    for (const p of bugLocations({ location: ep })) add(p, "project-profile entry_point");
+  }
+  return out;
+}
+
+/**
+ * Render the report as a fixed-width table for a human reading a gate block.
+ * @param {object} r - The report {@link cli} prints.
+ * @returns {string} One header line and one row per path.
+ */
+export function renderTable(r) {
+  const rows = r.paths.map((p) => [p.path, p.owner || "—", p.writers.join(",") || "UNOWNED", p.exists === null ? "?" : p.exists ? "yes" : "MISSING", p.cited_by || ""]);
+  const head = ["path", "owner", "writers", "on disk", "cited by"];
+  const w = head.map((h, i) => Math.max(h.length, ...rows.map((row) => String(row[i]).length)));
+  const line = (row) => row.map((c, i) => String(c).padEnd(w[i])).join("  ").trimEnd();
+  return [line(head), line(w.map((n) => "-".repeat(n))), ...rows.map(line),
+    "", `${r.scopes} scope(s) read · ${r.unowned.length} unowned path(s)${r.unowned.length ? `: ${r.unowned.join(", ")}` : ""}` +
+    ` · ${r.missing.length} not on disk${r.missing.length ? `: ${r.missing.join(", ")}` : ""}`].join("\n");
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe owner --slug <slug> [--path <p>]... [--format json|table] [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  path: { type: "str", multiple: true },
+  format: { type: "enum", values: ["json", "table"], default: "json" },
+  cwd: { type: "path" },
+};
+
+/**
+ * Answer "which scope owns this path" from the committed contracts.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {Promise<void>} Exits 0 with the report, 2 when no scope contract can be read.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const scopes = scopeSubstrates(cwd, args.slug);
+  if (!scopes.length) {
+    console.error(`probe owner: no readable scope contract for ${args.slug} — ownership is a property of the contracts, and there are none to read`);
+    process.exit(2);
+  }
+  const asked = (args.path || []).map((p) => ({ path: p, cited_by: "--path" }));
+  const inputs = asked.length ? asked : seamPaths(cwd, args.slug);
+  const paths = inputs.map((i) => ({ ...ownership(i.path, scopes, cwd), cited_by: i.cited_by }));
+  const report = {
+    slug: args.slug,
+    scopes: scopes.length,
+    source: asked.length ? "--path" : "wiring-map + project-profile",
+    paths,
+    unowned: paths.filter((p) => p.writers.length === 0).map((p) => p.path),
+    // Owned but absent: the wiring names a file nobody wrote — the gap a census reads as
+    // "unowned" when it does not check the disk.
+    missing: paths.filter((p) => p.exists === false).map((p) => p.path),
+  };
+  console.log(args.format === "table" ? renderTable(report) : JSON.stringify(report, null, 2));
+  process.exit(0);
+}
+
+if (isMain(import.meta.url)) cli(process.argv.slice(2));

package/kernel/probe/resume.mjs

@@ -63,7 +63,7 @@ import { splitFrontmatter } from "../lib/contract.mjs";
 import { globToRegExp } from "../verify/spec.mjs";
 import {
   intake, harnessRun, wiringMap, projectProfile, scopesDir, resultsDir, ordersDir,
-  orientDir, activeOrder, usecasesDir,
+  orientDir, activeOrder, usecasesDir, breadboard, receipt, readReceipt,
 } from "../lib/paths.mjs";
 import { evalVerdict } from "./eval.mjs";
 
@@ -378,6 +378,12 @@ export function deriveResumeState(cwd, slug) {
 
   const facts = {
     intake_path: intake(cwd, slug),
+    // The pitch's other half, staged by `init run` beside the intake. Null when the pitch had no
+    // separate breadboard — the planning dispatches then carry no `breadboard` key at all.
+    breadboard_path: existsSync(breadboard(cwd, slug)) ? breadboard(cwd, slug) : null,
+    // How it was found (flag | sibling | shaping-dir | shared-root | embedded), from the receipt;
+    // null when there was none or the receipt cannot be read.
+    breadboard_source: readReceipt(receipt(cwd, slug))?.breadboard?.source ?? null,
     spec_folder: hr.spec_folder || null,
     status: hr.status || null,
     lens: hr.lens || null,