shapeup-sdlc 3.1.1 → 3.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "3.1.1",
+  "version": "3.2.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

@@ -18,7 +18,7 @@ Skills and commands are named short throughout this file; every one of them reso
 1. Set Boundaries → `/shapeup shaping`
 2. Find the Elements → `/shapeup breadboarding`
 3. Risks & Rabbit Holes → `/shapeup spike`
-(The completed pitch is formed by `shaping.md` + `breadboard.md`)
+(The completed pitch is formed by `shaping.md` + `breadboard.md`. A run takes both: `/ship` finds the breadboard beside the pitch or in `shaping/`, takes one named with `--breadboard`, or reads it inline in a single pitch file, and hands it to every planning worker. Each breadboard Place with UI affordances becomes its own screen in the spec — spec-lint stops the run at L1b when one is missing or folded into another screen — and a Place the shape will not build is deferred there, with the PO's yes.)
 
 ### Phase 2 — Betting (PO governance, no skill)
 Betting Table: PO decides; rejected pitches loop back to raw idea.
@@ -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.
+- **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.
 - **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

package/commands/ship.md

@@ -71,6 +71,11 @@ Only run headless/auto if the user explicitly asks for it in their message:
   tiny, it will say so and recommend the full lane.
 
 Additional flags, pass through to `tech-lead` only when the user names them:
+- `--breadboard <path>` → the pitch's breadboard, when it is not beside the pitch. A pitch shaped
+  with `/shapeup` is `shaping.md` + `breadboard.md`; the run finds a `breadboard.md` in the same
+  folder (or in `shaping/`) on its own, and reads one written inline in a single `pitch.md`. Name
+  it only when it lives somewhere else. Its Places become the spec's screens, and spec-lint stops
+  the run at GATE L1b when one is missing or folded into another screen.
 - `--gate-answers <ci|guarded|interactive|path.json>` → the pre-recorded PO decisions this run
   crosses its gates with. Gates still emit their blocks and still record a decision; the
   decision's **source** becomes the answer set instead of a live human, and the ledger says so.

package/hooks/gate-intake.mjs

@@ -73,7 +73,7 @@ const hasResume = /--from\s+\S/.test(args); // resuming an existing run has its
 // the spec.
 // Adding a valued flag anywhere in the harness means adding it here, and structural test §39
 // enforces exactly that against commands/ship.md.
-const VALUED_FLAGS = /--(pitch|spec|from|lens|rounds|attempts|parallel-scopes|orch-model|exec-model|eval-model|qa-model|feature|task|gate-answers|wall-clock-budget|slug|auto-level|max-rounds|intake-file|intake-text|spec-folder|cwd|out|by|preset|file|order)\s+\S+/g;
+const VALUED_FLAGS = /--(pitch|spec|from|lens|rounds|attempts|parallel-scopes|orch-model|exec-model|eval-model|qa-model|feature|task|gate-answers|wall-clock-budget|slug|auto-level|max-rounds|intake-file|intake-text|spec-folder|cwd|out|by|preset|file|order|breadboard)\s+\S+/g;
 const BARE_FLAGS = /--[a-z0-9-]+/g;
 const freeText = args.replace(VALUED_FLAGS, " ").replace(BARE_FLAGS, " ").trim();
 

package/kernel/compile.mjs

@@ -36,10 +36,11 @@ import { readRunId } from "./lib/paths.mjs";
 // --spec-overridden directory, and the import is the convention-derived default.
 import {
   tasksDir, specDir as defaultSpecDir, roundLedger, trials, verdictsDir, ordersDir,
-  relShared, globLocal, globShared, relKnowledgeBase, resultsDir, scopesDir,
+  relShared, relLocal, globLocal, globShared, relKnowledgeBase, resultsDir, scopesDir,
 } from "./lib/paths.mjs";
-import { readContract, tasksForScope, SCOPE_CONTRACT } from "./lib/contract.mjs";
+import { readContract, readAllContracts, tasksForScope, SCOPE_CONTRACT } from "./lib/contract.mjs";
 import { writeActiveOrder } from "./probe/resume.mjs";
+import { greenVerdict } from "./probe/t0.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.
@@ -482,6 +483,43 @@ export function scopeSubstrates(cwd, slug) {
   return out;
 }
 
+// --- the T0 artifacts the judge must cite ----------------------------------------------------
+//
+// WHY THE KERNEL DERIVES THEM. spec-evaluator treats a scoped spec whose order lists no T0 artifact
+// as NOT gradeable and returns `failed` without grading a criterion. The precondition is right —
+// its verdict must cite a T0 artifact it re-hashed itself — and nothing met it: the list was once
+// assembled by an orchestrator courier from the paths each scope reported, and was lost when the
+// orchestrator became a workflow script that passes only `{dimensions, run_cmd, round}`. Evaluators
+// that went looking on disk graded anyway; one that followed its contract refused, and the run
+// aborted at L3 over a round whose every scope was green.
+//
+// Derived here for the reason `bugs` is: this is the one line every lane compiles through, and the
+// evidence is already on disk. A caller could not rebuild the list from filenames in any case —
+// verdict files are addressed by round, attempt and trial, never by scope, so the scope lives only
+// inside each body, which is what `probe t0` reads.
+
+/**
+ * The green T0 verdict each scope contract holds for a round — an evaluate order's `t0_artifacts`.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} [round] - The round being evaluated. Omitted, each scope's newest green verdict
+ *   of any round — a standalone evaluation has no round.
+ * @returns {{artifacts: string[], missing: string[]}} Repo-relative verdict paths in scope-id
+ *   order, one per scope that has one; and the scopes that have none. Both empty on an unscoped spec.
+ */
+export function t0ArtifactsFor(cwd, slug, round) {
+  const artifacts = [];
+  const missing = [];
+  for (const { contract, id } of readAllContracts(scopesDir(cwd, slug))) {
+    const scopeId = contract?.scope_id || id;
+    const { green, path } = greenVerdict(cwd, slug, scopeId, round);
+    if (green) artifacts.push(relLocal(slug, "t0", "verdicts", basename(path)));
+    else missing.push(scopeId);
+  }
+  return { artifacts, missing };
+}
+
 /**
  * Assemble a WorkOrder envelope. Pure given its inputs — the CLI wrapper does the disk reads.
  * @param {object} opts - The order inputs (destructured):
@@ -743,6 +781,17 @@ export async function cli(rawArgv) {
   let payloadExtra = flag("payload") || {};
   if (specDir && !payloadExtra.spec_folder) payloadExtra.spec_folder = specDir;
   if (!payloadExtra.feature) payloadExtra.feature = slug;
+  // The judge's citations, for every lane (see t0ArtifactsFor). An explicit `--payload` list still
+  // wins, as it does for `bugs`: an operator naming the evidence outranks the derivation.
+  if (operation === "evaluate" && payloadExtra.t0_artifacts === undefined) {
+    const { artifacts, missing } = t0ArtifactsFor(cwd, slug, round);
+    if (artifacts.length) payloadExtra.t0_artifacts = artifacts;
+    // On stderr, never stdout: stdout is the order path the caller consumes.
+    if (missing.length) {
+      console.error(`compile-order: warning — no green T0 verdict${round ? ` in round ${round}` : ""} for ` +
+        `${missing.join(", ")}; the evaluator has nothing to cite for ${missing.length === 1 ? "that scope" : "those scopes"}`);
+    }
+  }
 
   const order = compileOrder({
     slug, worker, operation, round, attempt, scope, tasks, decisions, digestedErrors, trialHistory, bugs,

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
@@ -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. */