shapeup-sdlc 3.1.2 → 3.2.0

package/.claude-plugin/plugin.json

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

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

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,

package/kernel/verify/spec.mjs

@@ -42,6 +42,16 @@
 //             Edge-cases heading with real content under it) but no usecases/UC-*.md declares
 //             a single [INV-NN] anywhere — a criteria-count check can't tell a healthy small
 //             tree from one that silently derived nothing from the pitch
+//   BREADBOARD-PLACE (red) a breadboard Place that owns UI affordances has no ux-behavior.md
+//             `## Screen: … (P#)` section and is not under `## Deferred Places`
+//   BREADBOARD-UI (red) a UI affordance (U#) not cited inside the screen section of any Place the
+//             breadboard puts it in. CITING IS NOT PLACING: a U# specified under another Place's
+//             screen passes a presence check and is exactly the defect this rule exists for
+//   BREADBOARD-TRACE (warn) N#/S# cited nowhere in the spec, V# slices no scope board records,
+//             U# the spec places that no manifest entry names as its `source`
+//   BREADBOARD-UNPARSED (warn) a staged breadboard this reader finds no ids in — a layout it
+//             cannot read must never become a hard stop
+//   All four are silent when the run has no breadboard (staged, or inline in the intake).
 //
 // Zero dependencies (glob matcher inlined from hooks/sandbox-guard.mjs). Judgment stays in the skill
 // (gap severity, lens choice); this script only reports facts.
@@ -56,6 +66,8 @@ import { runArgs } from "../lib/argv.mjs";
 import { LOCAL } from "../lib/paths.mjs";
 import { specDir, scopesDir, tasksDir, intake, sharedRoot, requirements } from "../lib/paths.mjs";
 import { readAllContracts, unreadableReason, ucId, scopePartitionConflicts, SCOPE_CONTRACT } from "../lib/contract.mjs";
+import { breadboard as stagedBreadboard } from "../lib/paths.mjs";
+import { parseBreadboard, hasBreadboardTables, idCounts } from "../lib/breadboard.mjs";
 
 // Inlined from hooks/sandbox-guard.mjs so this skill ships self-contained (a skill's scripts
 // must not reach outside its own folder — channels that copy only skills/ would dangle).
@@ -494,12 +506,169 @@ export function lintStructure({ specDir, tasks, intakeContent = "" }) {
   return findings;
 }
 
+/** Every Place id inside a heading's parentheses — `## Screen: Sheet (P2)`, `(P1, P3)`. */
+const PLACE_IN_PARENS = /\(([^)]*)\)/g;
+const PLACE_ID = /\bP\d+(?:\.\d+)*\b/g;
+
+/**
+ * Cut ux-behavior.md into the screen sections a breadboard's Places are checked against.
+ *
+ * A section runs from its `Screen:` heading to the next heading at the same level or higher, so
+ * a screen's `### States` table and behavior rules belong to it. Its Places are the P# ids in the
+ * heading's parentheses; a screen with none is kept (its citations are still "somewhere") but can
+ * place nothing.
+ *
+ * @param {string} uxText - ux-behavior.md, verbatim ("" when absent).
+ * @returns {{screens: {heading: string, places: string[], body: string}[], deferred: Set<string>}}
+ *   The screen sections, and the Place ids listed first-cell under `## Deferred Places`.
+ */
+export function uxScreens(uxText) {
+  const lines = String(uxText ?? "").split(/\r?\n/);
+  const screens = [];
+  const deferred = new Set();
+  let cur = null; // { level, heading, places, body[] } for a screen, or { level, deferred: true }
+  for (const line of lines) {
+    const h = line.match(/^(#{1,6})\s+(.*)$/);
+    if (h) {
+      const level = h[1].length;
+      if (cur && level <= cur.level) cur = null;
+      if (!cur) {
+        const text = h[2].trim();
+        if (/^screen\s*:/i.test(text)) {
+          const places = [...text.matchAll(PLACE_IN_PARENS)].flatMap((m) => m[1].match(PLACE_ID) ?? []);
+          cur = { level, heading: text, places, body: [] };
+          screens.push(cur);
+          continue;
+        }
+        if (/^deferred places\b/i.test(text)) { cur = { level, deferred: true }; continue; }
+      }
+    }
+    if (!cur) continue;
+    if (cur.deferred) {
+      const row = line.match(/^\s*\|\s*([^|]*)\|/);
+      const id = row ? row[1].replace(/[*`\[\]]/g, "").match(/^\s*(P\d+(?:\.\d+)*)\b/) : null;
+      if (id) deferred.add(id[1]);
+    } else cur.body.push(line);
+  }
+  return {
+    screens: screens.map((s) => ({ heading: s.heading, places: s.places, body: s.body.join("\n") })),
+    deferred,
+  };
+}
+
+/**
+ * Lint the spec against the pitch's breadboard: every Place with UI affordances has a screen, and
+ * every UI affordance is specified on a screen of a Place the breadboard puts it in.
+ *
+ * PLACEMENT, NOT CITATION. The loss this exists for did not drop a new sheet's affordances — they
+ * were all in the spec, inside the composer's state table. What was lost was the Place. A rule that
+ * only asks "is U2 cited?" passes that spec; this one asks "is U2 cited under P2?". It checks WHICH
+ * screen, never where on the screen: layout inside a Place stays the designer's.
+ *
+ * Absent breadboard ⇒ zero findings, the same "absent artifact ⇒ arm skipped" rule INV-FLOOR and
+ * SCOPE-COVERS follow — every pre-breadboard spec and every run without one is untouched.
+ *
+ * @param {object} input - What to lint (destructured).
+ * @param {string} input.uxText - ux-behavior.md, verbatim ("" when absent).
+ * @param {string} input.specText - Every markdown file under the spec tree, concatenated.
+ * @param {Array<object>} [input.scopes] - Parsed scope contracts ([] before MAP SCOPES).
+ * @param {(string|null)} [input.scopeSummaryText] - scope-summary.md, or null when absent.
+ * @param {(string|null)} [input.scopeBoardText] - scope-board.md, or null when absent — the scope
+ *   architect's own write surface, where it records which scopes deliver each slice.
+ * @param {(string|null)} input.bbText - The breadboard, or null when the run has none.
+ * @returns {Array<{rule:string, level:("red"|"warn"), detail:string}>} Findings; [] when clean or
+ *   when there is no breadboard.
+ */
+export function lintBreadboard({ uxText = "", specText = "", scopes = [], scopeSummaryText = null, scopeBoardText = null, bbText = null }) {
+  if (!bbText) return [];
+  const findings = [];
+  const bb = parseBreadboard(bbText);
+  const counts = idCounts(bb);
+  if (Object.values(counts).every((n) => n === 0)) {
+    findings.push({ rule: "BREADBOARD-UNPARSED", level: "warn", detail: "the run has a breadboard but no P#/U#/N#/S#/V# ids could be read from its tables — placement was not checked. A `#` or `ID` first column holding the id, and a `Place` column on affordance rows, is the layout this reads" });
+    return findings;
+  }
+
+  const { screens, deferred } = uxScreens(uxText);
+  /**
+   * A Place as a finding names it — id and breadboard name.
+   * @param {string} p - Place id.
+   * @returns {string} e.g. `P2 Payment Sheet`.
+   */
+  const name = (p) => {
+    const n = bb.places.find((x) => x.id === p)?.name;
+    return n ? `${p} ${n}` : p;
+  };
+  /**
+   * Does the text cite this exact id — `U2` but not `U21` or `U2a`?
+   * @param {string} text - Markdown to search.
+   * @param {string} id - A breadboard id.
+   * @returns {boolean} True when the id appears as a whole word.
+   */
+  const cites = (text, id) => new RegExp(`\\b${id.replace(/\./g, "\\.")}\\b`).test(text);
+
+  // BREADBOARD-PLACE — a Place with something to place needs a screen of its own.
+  const owners = new Map(); // Place → the U# it owns
+  for (const u of bb.ui) for (const p of u.places) (owners.get(p) ?? owners.set(p, []).get(p)).push(u.id);
+  for (const [p, us] of owners) {
+    if (deferred.has(p)) continue;
+    if (screens.some((s) => s.places.includes(p))) continue;
+    findings.push({ rule: "BREADBOARD-PLACE", level: "red", detail: `${name(p)} owns ${us.join(", ")} but ux-behavior.md has no "## Screen: … (${p})" section — add the screen or defer the Place under "## Deferred Places"; never fold it into another screen` });
+  }
+
+  // BREADBOARD-UI — each U# is specified on a screen of a Place the breadboard puts it in.
+  const unplaceable = [];
+  for (const u of bb.ui) {
+    if (!u.places.length) { unplaceable.push(u.id); continue; }
+    const live = u.places.filter((p) => !deferred.has(p));
+    if (!live.length) continue;
+    if (screens.some((s) => s.places.some((p) => live.includes(p)) && cites(s.body, u.id))) continue;
+    const elsewhere = [...new Set(screens.filter((s) => cites(s.body, u.id)).flatMap((s) => s.places.length ? s.places : [`"${s.heading}"`]))];
+    const where = elsewhere.length
+      ? `is cited only under ${elsewhere.join(", ")}`
+      : cites(uxText, u.id) ? "is cited in ux-behavior.md but on no screen" : "is cited on no screen";
+    findings.push({ rule: "BREADBOARD-UI", level: "red", detail: `${u.id} (${live.map(name).join(" / ")}) ${where} — specify it in the screen section of its own Place` });
+  }
+
+  // BREADBOARD-TRACE — the rest of the breadboard, reported and never blocking.
+  const trace = [];
+  const lost = [...bb.code, ...bb.stores].map((x) => x.id).filter((id) => !cites(specText, id));
+  if (lost.length) trace.push(`N#/S# cited nowhere in the spec: ${lost.join(", ")}`);
+  const slicesText = [scopeSummaryText, scopeBoardText].filter((t) => t !== null && t !== undefined).join("\n");
+  if (scopeSummaryText !== null || scopeBoardText !== null) {
+    const unsliced = bb.slices.map((v) => v.id).filter((id) => !cites(slicesText, id));
+    if (unsliced.length) trace.push(`V# slices no scope board or scope summary records: ${unsliced.join(", ")}`);
+  }
+  if (scopes.length) {
+    const sourced = new Set(scopes.flatMap((s) => (s.affordance_manifest ?? []).map((a) => String(a?.source ?? "").trim())));
+    const unsourced = bb.ui.map((u) => u.id).filter((id) => cites(uxText, id) && !sourced.has(id));
+    if (unsourced.length) trace.push(`U# the spec places but no manifest entry names as its source: ${unsourced.join(", ")}`);
+  }
+  if (unplaceable.length) trace.push(`U# with no Place column to check placement against: ${unplaceable.join(", ")}`);
+  if (trace.length) findings.push({ rule: "BREADBOARD-TRACE", level: "warn", detail: trace.join("; ") });
+  return findings;
+}
+
+/**
+ * The breadboard a run's spec is linted against: the staged copy, else the intake when it carries
+ * one inline, else null — and null switches every BREADBOARD-* rule off.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} intakeContent - The run's intake, verbatim ("" when absent).
+ * @returns {(string|null)} The breadboard text, or null when the run has none.
+ */
+export function runBreadboard(cwd, slug, intakeContent) {
+  const p = stagedBreadboard(cwd, slug);
+  if (existsSync(p)) return readFileSync(p, "utf8");
+  return hasBreadboardTables(intakeContent) ? intakeContent : null;
+}
+
 /**
  * Run the full spec lint (scopes + structure) for a slug.
  * @param {{cwd:string, slug:string}} opts - Working root and feature slug.
  * @returns {{slug:string, scopes:number, tasks:number, red:number, warn:number,
- *   findings:Array<object>}} Counts and the combined findings from {@link lintScopes} and
- *   {@link lintStructure}.
+ *   findings:Array<object>}} Counts and the combined findings from {@link lintScopes},
+ *   {@link lintStructure} and, when the run has a breadboard, {@link lintBreadboard}.
  */
 export function lint({ cwd, slug }) {
   const specRoot = specDir(cwd, slug);
@@ -525,6 +694,25 @@ export function lint({ cwd, slug }) {
     ...lintScopeAnchors({ scopes, specDir: specRoot, reqIds, tasks }),
     ...lintCommittedTier({ cwd, slug }),
     ...lintStructure({ specDir: specRoot, tasks, intakeContent }),
+    ...(() => {
+      const bbText = runBreadboard(cwd, slug, intakeContent);
+      if (!bbText) return [];
+      /**
+       * A file's text, or null when it does not exist.
+       * @param {string} p - Absolute path.
+       * @returns {(string|null)} The contents, or null.
+       */
+      const readOr = (p) => (existsSync(p) ? readFileSync(p, "utf8") : null);
+      const specFiles = existsSync(specRoot) ? walkFiles(specRoot).filter((f) => f.endsWith(".md")) : [];
+      return lintBreadboard({
+        uxText: readOr(join(specRoot, "ux-behavior.md")) ?? "",
+        specText: specFiles.map((f) => readFileSync(join(specRoot, f), "utf8")).join("\n"),
+        scopes,
+        scopeSummaryText: readOr(join(specRoot, "scope-summary.md")),
+        scopeBoardText: readOr(join(sharedRoot(cwd, slug), "scope-board.md")),
+        bbText,
+      });
+    })(),
   ];
   return {
     slug,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "Shape Up for coding agents \u2014 with gates the agent can't talk its way past. Harness for Claude Code.",
   "bin": {
     "shapeup-sdlc": "bin/init.mjs"

package/skills/ba-pitch-analyzer/SKILL.md

@@ -26,6 +26,7 @@ Invoked as `--order <path>`. Fields you may rely on (absent = unknown; surface i
 |---|---|
 | `operation` | `analyze` (pitch → full spec tree + board) · `reconcile` (fold discovered-ledger items into the board + UC invariants) · `retrofit-surface` (append `## Test Surface` to a pre-surface spec) · `coverage` (extract atomic requirement clauses → the SHARED `requirements.md` registry) |
 | `payload.pitch` | The pitch/PRD path (analyze) |
+| `payload.breadboard` | The breadboard (analyze): its Places are your screens; its U# and N# are the affordances you place and cite. Absent = none separate; never inferred |
 | `payload.requirements` | (coverage) the REQ source to extract atomic clauses from — pitch / a customer-requirements doc / the use-case bodies. Absent → default to the pitch and record the choice in `assumptions[]` |
 | `payload.lens` | `lite` \| `standard` \| `cross-context`. Absent → judge it: LITE for ≤2-week appetite, no third-party, ≤3 user-facing actions; STANDARD for multi-team, third-party, or bigger appetite; genuinely unclear → one binary question, or `status: "escalated"` with the question in `deviations[]` |
 | `payload.orient_dir` | The Scout's artifacts — `code-surface.md` IS your codebase map (do not re-scan), `discovered-seed.md` seeds task gen, `spike-*.md` feeds feasibility |
@@ -43,8 +44,11 @@ Phases, each with a checkpoint (pause only per `interaction`). Read the referenc
 its phase; templates live in `assets/templates/`.
 
 ```
-1  INGEST      pitch + orient artifacts + KB. Extract slug, appetite, in/out boundaries,
-               rabbit holes, third-party mentions. No files written yet.
+1  INGEST      pitch + breadboard (`payload.breadboard`, or tables inline in the pitch) +
+               orient artifacts + KB. Extract slug, appetite, in/out boundaries, rabbit
+               holes, third-party mentions. With a breadboard, list every Place (P#) and UI
+               affordance (U#) first — they are the screens and interactive elements Phase 3
+               must place. No files written yet.
 1b FEASIBILITY (third-party/API/SDK/webhook mentioned) verification questions + fallback
                scope per API-NN → api-feasibility.md
 2  DDD         bounded contexts, aggregates (new vs extended), value objects, domain events,
@@ -52,8 +56,9 @@ its phase; templates live in `assets/templates/`.
 2b CONTRACTS   (standard lens) typed Request/Response/Error per repository; two-pass rule:
                unresolvable at spec time → `⏳ TBD — verify in the [UC-x] spike`, resolved
                post-SPIKE with citation → contracts/            [references/contract-patterns.md]
-3  UX          per screen: state table (idle→loading→error→success), error cases with
-               message+action, ASCII flows → ux-behavior.md     [references/ux-behavior-patterns.md]
+3  UX          per screen — with a breadboard, one screen per Place that owns UI affordances:
+               state table (idle→loading→error→success), error cases with message+action,
+               ASCII flows → ux-behavior.md                     [references/ux-behavior-patterns.md]
 4  USE CASES   one file per actor+action: typed Input/Output, numbered Steps, all error
                cases with codes, ## System Flow (UI→API→UC→Repo→DB), ## Test Surface
                (DERIVED ONLY from D1 Invariants · D2 Error Cases · D3 Contract shape ·
@@ -69,7 +74,8 @@ its phase; templates live in `assets/templates/`.
                   overflow is a fact you REPORT for the caller's HAMMER gate, never resolve)
                node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify spec --slug <slug>
                  (structure, wikilinks, edge symmetry — fix reds, then re-run; you never
-                  self-grade with a hand-walked checklist)
+                  self-grade with a hand-walked checklist. BREADBOARD-PLACE / BREADBOARD-UI:
+                  add the screen or defer the Place; never fold it into another screen)
                → scope-summary.md + synthesis.md (traceability matrix, risk register,
                  dependency graph — the JUDGMENT layers over board-derive's numbers)
 8  INDEX       _index.md (pitch digest + document map) + feedback.md template

package/skills/ba-pitch-analyzer/assets/templates/_index.tmpl.md

@@ -29,7 +29,8 @@ audit_rules_version: "2.5"
 ## Solution Elements
 
 ### Breadboarding
-<!-- Text-based flow showing the key interaction path, no images needed -->
+<!-- Text-based flow showing the key interaction path, no images needed. With a breadboard,
+     name Places and affordances by id: P1 Cart ──U1──► P2 Payment Sheet -->
 ```
 [Screen A] ──action──► [Screen B] ──action──► [Outcome]
                │

package/skills/ba-pitch-analyzer/assets/templates/ux-behavior.tmpl.md

@@ -29,7 +29,7 @@ status: draft
 
 ---
 
-## Screen: [ScreenName]
+## Screen: [ScreenName] ([P#] — omit without a breadboard)
 
 ### States
 
@@ -54,7 +54,7 @@ status: draft
 
 ---
 
-<!-- Repeat "Screen: [Name]" section for each screen -->
+<!-- Repeat "Screen: [Name]" section for each screen — one per breadboard Place with UI affordances -->
 
 ---
 
@@ -63,3 +63,13 @@ status: draft
 | Behavior | Mobile | Web |
 |---|---|---|
 | [behavior] | [mobile treatment] | [web treatment] |
+
+---
+
+## Deferred Places
+
+<!-- Breadboard Places with UI affordances this shape will not build. Each needs the PO's yes at GATE L1b. Omit the section when there are none. -->
+
+| Place | Reason |
+|---|---|
+| [P#] [Place name] | [why this shape does not build it] |

package/skills/ba-pitch-analyzer/references/doc-schemas.md

@@ -126,6 +126,9 @@ Required sections: Screen Flow (ASCII diagram), one section per Screen with:
 - **Visual & Layout Specs**: Flex/Grid structure, spacing, alignment rules, and desktop/mobile responsiveness
 - **Design Tokens**: Specific CSS variables or Tailwind classes used for background, borders, fonts, and actions
 - **States table**, **Behavior Rules list**, **Error States table**
+- Screen headings carry the breadboard Place id when a breadboard exists — `## Screen: Payment Sheet (P2)`, one screen per Place that owns UI affordances, each U# cited inside its own Place's section
+
+Plus **Deferred Places**, when any: a `Place | Reason` table of breadboard Places this shape will not build.
 
 
 ---

package/skills/ba-pitch-analyzer/references/ux-behavior-patterns.md

@@ -15,6 +15,15 @@ From the pitch breadboarding and fat marker sketches, identify:
 
 Each decision point is typically a screen boundary.
 
+> **With a breadboard, the screens are its Places.** Write one `## Screen:` section per Place that
+> owns at least one UI affordance, with the Place id in the heading — `## Screen: Payment Sheet (P2)`.
+> Cite each UI affordance's id (`U3`) in the state-table row or behavior rule that specifies it,
+> inside the section of the Place the breadboard puts it in. A Place is a screen boundary: a sheet or
+> modal the breadboard names as its own Place is never folded into its parent's state table, even
+> when the pitch's prose describes it as part of the parent. A Place with no UI affordances (a
+> backend, a store) needs no screen. A Place this shape will not build goes in `## Deferred Places`
+> with the reason; it surfaces at GATE L1b, where the PO accepts or rejects the deferral.
+
 ---
 
 ## State Machine per Screen

package/skills/orient/SKILL.md

@@ -42,7 +42,8 @@ from `tech-lead`; it never reads or writes a shared run-state file.
 ## Input contract (pure worker)
 
 Orchestrated, you are invoked as `--order <path>` (a WorkOrder): `payload.pitch` (the
-kicked-off pitch path), `payload.stack` (sweep hint), `payload.spec_folder` (the SHARED spec
+kicked-off pitch path), `payload.breadboard` (the pitch's breadboard — Places, affordances, slices;
+absent = none separate), `payload.stack` (sweep hint), `payload.spec_folder` (the SHARED spec
 deliverable dir) and `payload.feature` (the run slug), plus `substrate.allowed` naming your one
 write surface — the orient output dir. Anything absent = unknown: confirm at GATE O-A
 (standalone) or report it in the result's `deviations`, never guess. Standalone, the
@@ -104,7 +105,8 @@ Confirm (do not guess):
       Shaped signal: frontmatter status: shaped AND bet: <S1|S2|...> (or equivalent).
       If the pitch lacks appetite AND solution boundaries → STOP and tell tech-lead:
         "Orient runs on a kicked-off pitch, not a raw idea. Shape/bet first (PO upstream)."
-  - breadboard.md path — read it if it exists; record "no breadboard" if absent
+  - breadboard — read `payload.breadboard` when present; absent means the pitch has no separate
+    breadboard — look for Places and affordance tables in the pitch itself
   - spec folder target (create orient/ if absent)
   - codebase root
 ```
@@ -136,7 +138,8 @@ Useful sweeps (adapt to the stack arg):
 ```
 
 Write `code-surface.md`: one row per pitch element → `file:line` it touches (or "NEW — no
-existing home"), the seam it extends, and whether it's new vs. existing. Flag every place the
+existing home"), the seam it extends, and whether it's new vs. existing. With a breadboard, each row
+carries the P#, U# or N# of the element it locates — a Place with no existing home is a NEW screen. Flag every place the
 map is uncertain — uncertainty is signal for Phase 3, not something to hide.
 
 > **Output location.** All four orient artifacts are run-trace (recon scratch), so they
@@ -257,7 +260,7 @@ Tech-lead uses this to render the GATE L1a Hill and confirm the spike before han
 ### Flags
 | Flag | Effect |
 |------|--------|
-| `--pitch <path>` | The kicked-off pitch (+ sibling `breadboard.md` if present) |
+| `--pitch <path>` | The kicked-off pitch. Read `payload.breadboard` when present; absent means the pitch has no separate breadboard — look for Places and affordance tables in the pitch itself |
 | `--spec <path>` | SHARED spec deliverable dir (shapeup/<feat>/spec/); orient *artifacts* are written to the LOCAL root `.shapeup/<feat>/orient/` |
 | `--stack <hint>` | Stack hint to aim the code-surface sweeps |
 | `--auto` | Auto-confirm O-A and O-B; run straight through |

package/skills/scope-architect/SKILL.md

@@ -21,6 +21,7 @@ the ship report's census table.
 |---|---|
 | `operation` | `map-scopes` — the only operation this skill has. It covers first slicing after the board exists, folding discovered items in, and re-slicing a stuck scope; the payload says which of those you are doing |
 | `payload.feature` / `payload.spec_folder` | Slug + committed spec (read ux-behavior.md for manifests; usecases for flows) |
+| `payload.breadboard` | When present, every U# the spec places is one manifest entry's `source`; record which scopes deliver each V# slice in `scope-board.md` (your write surface — `scope-summary.md` is the planner's) |
 | `payload.tasks[]` | The board's tasks with their touched files — the slicing INPUT only. Each carries `use_case_refs`; those UC ids are what you write into the contract. Never copy a task id into a contract |
 | `substrate.allowed` | `scopes/*.md` + `scope-board.md` — your ONLY write surface |
 
@@ -65,6 +66,8 @@ the ship report's census table.
                                                                element as {test_id, role} +
                                                                required_states [idle, loading,
                                                                success, error, empty]
+                                                               + `source` — the U# the
+                                                               ux-behavior row cites
              e2e_verification_fixtures[]                     — the command(s)/spec file(s)
                                                                that drive this scope
                                                                end-to-end (T0 layer); too
@@ -134,6 +137,7 @@ territory — and any lint warn left standing, with why). You never touch task f
 - [ ] Every scope that consumes another's output declares it in `depends_on`
 - [ ] Substrates disjoint except declared shared_substrate (DISJOINT = 0 red)
 - [ ] Every interactive element in scope screens appears in exactly one affordance_manifest
+- [ ] Every U# the spec places is some manifest entry's `source`
 - [ ] Every scope has fixtures or an explicit TBD flag
 - [ ] Every hill_phase written is UPHILL_UNKNOWN; superseded contracts kept
 - [ ] The WorkResult validates against `work-result.schema.json`

package/skills/solution-architect/SKILL.md

@@ -42,6 +42,7 @@ return as a WorkResult.
 |---|---|
 | `operation` | `wire` (author/refresh the wiring map after `analyze`, before `map-scopes`) |
 | `payload.feature` / `payload.spec_folder` | Slug + committed spec — read `usecases/` for the UCs and the engine each one needs, `domain-model.md`/`synthesis.md` for the module surface |
+| `payload.breadboard` | When present, name each UC's `affordance` by its U# and Place |
 | `payload.project_profile` | Path to the SHARED `project-profile.md`. Its `entry_point` is the composition root every engine must attach to — **archetype-specific** (a client-only game's `main.js` is not a web-service's `src/server.ts`). Read it; never guess the entry point |
 | `substrate.allowed` | `wiring-map.md` — your ONLY write surface (the spec core, scopes, and the profile are frozen) |
 
@@ -69,7 +70,9 @@ guessed `main.js` would make the later oracle certify nothing.
                                file:line is a build-time fact (the oracle proves reachability by
                                the import graph, it does not parse this field)
              affordance        the player-visible thing this UC exposes once wired (the human
-                               end of the chain — what a user can DO, not an internal call)
+                               end of the chain — what a user can DO, not an internal call);
+                               with a breadboard, name it by U# and Place —
+                               `U1 Pay (P1) → P2 Payment Sheet`
 3 WRITE    shapeup/<slug>/wiring-map.md (WiringMap): frontmatter for schema_version, feature
            and entry_point (echo of the profile), then entries[] as ONE MARKDOWN TABLE under a
            `## Wiring` heading — this exact shape, because it is the only one the reader parses:

package/skills/tech-lead/SKILL.md

@@ -23,7 +23,7 @@ turns fighting shell quoting):
 node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" init run \
   --slug <slug-from-the-request> --intake-file <path/to/the/requirement.md> \
   --auto-level <interactive|auto|unattended> \
-  [--dimensions <a,b>] [--gate-answers <ci|guarded|path.json>] [--wall-clock-budget <seconds>] [--max-rounds 3]
+  [--dimensions <a,b>] [--gate-answers <ci|guarded|path.json>] [--wall-clock-budget <seconds>] [--max-rounds 3] [--breadboard <path>]
 ```
 
 **After a compaction, or in a fresh session over an open run, re-derive before you act.** One
@@ -43,11 +43,11 @@ counts.
 plugin and need a one-time permission grant (`npx shapeup-sdlc init` writes it). Do not route
 around it, and do not silently hand-build the feature instead.
 
-**Language gate (delegated to `translator`, not this skill):** at GATE L0, before Step 2, dispatch
-an Agent (model: exec) that calls `Skill(shapeup-sdlc-plugin:translator) --check <intake>`.
-English → proceed as-is. Non-English → dispatch a second Agent (`--auto` under auto/unattended)
-and orchestrate against the produced `<name>.en.md`. The tech lead detects and sequences; it never
-translates itself.
+**Language gate (delegated to `translator`, not this skill):** before Step 1 opens the run, dispatch
+an Agent (model: exec) calling `Skill(shapeup-sdlc-plugin:translator) --check` on the pitch *and* its
+breadboard. English → proceed as-is. Non-English → a second Agent translates both (`--auto` under
+auto/unattended); Step 1 then names the `.en.md` files (a run already open on the original: re-open
+it with `--force` — nothing is dispatched yet). The tech lead detects and sequences; never translates.
 
 **Step 2 — pin GATE L0, then launch.** Collect the L0.1–L0.9 config (spec folder, lens, stack,
 eval dims, max_rounds, the model/budget matrix — see `references/gates.md` GATE L0 for the full

package/skills/tech-lead/references/gates.md

@@ -31,13 +31,19 @@ escalates, writes nothing, and every relaunch re-dispatches it.
 
 ```
 Collect (explicit — never inferred):
-  L0.1  Kicked-off pitch source: path to a shaping.md / pitch.md (already shaped + bet by PO).
+  L0.1  Kicked-off pitch source: `shaping.md` — and its `breadboard.md`, which the run finds
+          beside it (or in `shaping/`) or takes from `--breadboard`; a `pitch.md` may carry the
+          breadboard inline. Already shaped + bet by PO.
           Not a raw idea — shaping (1-4) / betting (5) / kick-off (6) are PO-personal, upstream.
-  L0.1a Language gate: Agent (model: exec) → Skill(shapeup-sdlc-plugin:translator) --check <intake>.
-          English      → use intake as-is.
-          non-English  → Agent (model: exec) → Skill(shapeup-sdlc-plugin:translator) <intake>
-                         (--auto under auto/unattended), then use the produced <name>.en.md as
-                         the ORIENT/MAP-SCOPES input. Log in ledger.
+  L0.1a Language gate, BEFORE init run: Agent (model: exec) → Skill(shapeup-sdlc-plugin:translator)
+          --check over the pitch AND its breadboard.
+          English      → use both as-is.
+          non-English  → Agent (model: exec) → Skill(shapeup-sdlc-plugin:translator) <pitch> <breadboard>
+                         (--auto under auto/unattended), then open the run on the produced
+                         <name>.en.md — init run prefers a breadboard.en.md beside it, and warns
+                         when it can find only the untranslated breadboard. The run's intake is
+                         what every planning worker reads, so a translation made after the run
+                         opened reaches nobody: re-open with --force naming the .en.md. Log in ledger.
   L0.1b Appetite: read the `appetite` field from the pitch's YAML frontmatter (set by /shapeup).
           Surface it in the gate output. Use it to:
             - Contextualise the scope at L1b (right-size cuts to the budget).
@@ -167,8 +173,9 @@ committing to a scope map. This is the first Hill read (area-level — slices do
 ```
 Read .shapeup/<slug>/orient/. Render the 🗻 Hill from hill-signal.md (see protocol.md "Hill report"):
   - each suspected area → uphill (open unknowns) | crest (approach proven by the spike) | downhill
-Print: the code-surface headline (where it lands), the spiked area + result, the riskiest
-       open unknowns going into mapping.
+Print: `Breadboard: <source> | none` (how init run found the pitch's breadboard — flag, sibling,
+       shaping-dir, shared-root, embedded — or none), the code-surface headline (where it lands),
+       the spiked area + result, the riskiest open unknowns going into mapping.
 Ask (max 2): is the riskiest area the right one to have spiked? any unknown that must be
              resolved (another spike) before we map scopes?
 ```
@@ -186,7 +193,7 @@ Do NOT enter MAP SCOPES until Orient is accepted.
    mobile|library|data-pipeline}; entry_point is the reachability seam (a game's main.js is NOT a
    service's src/server.ts). Validate the enum — a typo must fail, not silently disable the check.
 2. WIRE — compile-order --operation wire --slug <slug> (worker→solution-architect), payload
-   {project_profile}. Sole writer of committed wiring-map.md (per-UC engine → seam → entry-point
+   {project_profile, breadboard?}. Sole writer of committed wiring-map.md (per-UC engine → seam → entry-point
    call site → affordance). ⏸ GATE L1a.5: confirm each UC has a declared seam before slicing.
    ⟐ PRECONDITION: MAP SCOPES step 1 (ANALYZE) has already run and usecases/ is
    populated. WIRE writes one entry per use case, so dispatching it against an empty spec folder
@@ -212,7 +219,7 @@ against the seams WIRE declared. Sequence: ORIENT → L1a → **ANALYZE** → **
 ```
 Two orders, two workers, one step (both model: exec — see references/protocol.md):
 1. ANALYZE + BOARD — compile-order --operation analyze --slug <slug> --worker ba-pitch-analyzer
-     --payload '{"pitch": "<path>", "lens": "<lens>", "orient_dir": ".shapeup/<slug>/orient/"}'
+     --payload '{"pitch": "<path>", "breadboard": "<the path init run printed, when it printed one>", "lens": "<lens>", "orient_dir": ".shapeup/<slug>/orient/"}'
    dispatch: Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>. The order hands it
    code-surface.md (Phase-1 ingest consumes the map, does not re-scan), discovered-seed.md
    (task gen starts from reality), spike-<area>.md (feasibility/contracts).
@@ -265,6 +272,8 @@ Scope contracts present:
     - scope board: scope_id, topology_type, substrate file count (scopes/*.md / scope-board.md)
     - any SPIKE blockers (scope-summary.md)
     - scope-summary "Done when" headline statements
+    - the Deferred Places from ux-behavior.md (breadboard Places this shape will not build) —
+      each one needs the PO's yes; a rejected deferral goes back to the planner as a screen
 No scope contracts (pre-v0.3.0, unchanged from v0.2.6):
   Read tasks/_index.md (LOCAL root). Print:
     - task count by package/variant (.shared / .be / .web / .mobile / .e2e)
@@ -280,7 +289,11 @@ this is the orchestrator's own re-confirmation before committing to a build sequ
     waiting to happen), PA1 (directory-aligned scope), PA2 (size cap), SCOPE-ANCHOR (a scope
     naming no committed use case, or one that does not resolve), TIER-DIRECTION (a committed
     contract naming LOCAL task ids), SCOPE-DEPS (a build-order id naming a scope that is not
-    in this run). Any red → HARD STOP, past a 🔴 at the architect's own checkpoint.
+    in this run), BREADBOARD-PLACE (a breadboard Place with UI affordances has no
+    `## Screen: … (P#)` in ux-behavior.md and is not deferred), BREADBOARD-UI (a U# not
+    specified on a screen of its own Place). Any red → HARD STOP, past a 🔴 at the
+    architect's own checkpoint. The breadboard reds are the planner's to fix — add the screen
+    or defer the Place; never fold it into another screen.
   - Lock the build SEQUENCE riskiest-first: order scopes by open-unknowns count (from
     hill/<scope-id>.yml if present, else the orient hill signal), not by file count or
     alphabetical — Shape Up's "solve in the right sequence" (step 10).
@@ -414,7 +427,8 @@ S.6  Harvest one signal row → append to `.shapeup/metrics/<machine-id>.jsonl`
      deliberately without colliding on one filename. The read plane is
      `harness probe stats`, or `cat .shapeup/metrics/*.jsonl`).
      Copy fields that ALREADY exist as structured output (run-state, final EVAL report,
-     discovery ledger, qa/hunt-report, breadboard B5). Two hard rules:
+     discovery ledger, qa/hunt-report, and the receipt's `breadboard.ids.V` for `slice_count` —
+     the slices init run counted in the staged breadboard, never a hand copy). Two hard rules:
        1. Harvest only fields that already exist at ship time — never evaluate something new.
        2. Record facts, never compute a new verdict (no `run_quality_score` — that would be
           a second judge behind spec-evaluator). The eval suite interprets; harvest records.

package/skills/tech-lead/references/protocol.md

@@ -311,14 +311,15 @@ workers keep only their own product-idempotency key and emit domain artifacts.
 
 ## 0. LANGUAGE GATE → translator (GATE L0, only if non-English)
 ```
-Invoke via Agent (model: exec): Skill(shapeup-sdlc-plugin:translator) --check "<intake path>"
+Invoke via Agent (model: exec), BEFORE init run: Skill(shapeup-sdlc-plugin:translator) --check "<intake path>" "<breadboard path>"
                  # detect-only, writes nothing
   English      → skip; ORIENT against the original.
-  non-English  → Agent (model: exec): Skill(shapeup-sdlc-plugin:translator) "<intake path>" [--auto]
-                 # full pass
-                 Writes: <name>.en.md (English copy; original untouched) + glossary.md
+  non-English  → Agent (model: exec): Skill(shapeup-sdlc-plugin:translator) "<intake path>" "<breadboard path>" [--auto]
+                 # full pass — the pitch AND its breadboard, before init run
+                 Writes: <name>.en.md per file (English copy; original untouched) + glossary.md
                          + translation-report.md.
-                 ORIENT against the <name>.en.md copy.
+                 Open the run on the .en.md pitch: init run stages breadboard.en.md beside it,
+                 and every planning worker reads what init run pinned — never a later copy.
 Read back: the detect table (--check) / the .en.md path + residual scan result (full pass).
 Authority: translator normalizes language only — it does not orient/plan/build/judge. The tech
 lead never translates itself; it only detects and sequences this step before ORIENT.
@@ -340,7 +341,7 @@ Authority: pure worker — no code, no board, no run-state, no reporting.
 ```
 Order A (the spec tree + board):
   compile-order --operation analyze --slug <slug> --worker ba-pitch-analyzer
-    --payload '{"pitch": "<path>", "lens": "<lens>", "orient_dir": ".shapeup/<slug>/orient/"}'
+    --payload '{"pitch": "<path>", "breadboard": "<the path init run printed, when it printed one>", "lens": "<lens>", "orient_dir": ".shapeup/<slug>/orient/"}'
   Agent (model: exec): Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>
   The order hands it code-surface.md (Phase-1 ingest, no re-scan), discovered-seed.md (task
   gen from reality), spike-<area>.md (feasibility/contracts).
@@ -826,7 +827,7 @@ fixtures run in isolation and do not consume it.
 | `spike_unresolved_count` | `SPIKE-UNRESOLVED` markers at bet | shaping quality — open risk into bet |
 | `scope_cut_count` | `~` items cut at SHIP S.0 | appetite pressure / scope hammer |
 | `qa_findings` | `.shapeup/<slug>/qa/hunt-report.md` + triage → `{total, promoted, held}` | edge quality |
-| `slice_count` | breadboard B5 (≤9) | **normalizer / denominator** |
+| `slice_count` | `receipt.json` → `breadboard.ids.V` (the V# slices init run counted in the staged breadboard; omit the field when `breadboard` is null) | **normalizer / denominator** |
 | `sources` | path to each **SHARED** source artifact — never a LOCAL `.shapeup/` path (the run-trace is superseded run by run, so a LOCAL path dangles by the time anyone reads the row; SHARED paths resolve on any clone — tier-direction rule) | auditability |
 
 - `slice_count` is the **denominator**: `round_count=4` on a 2-slice feature is alarming,

package/skills/tech-lead/schemas/domain.schema.json

@@ -314,6 +314,7 @@
     ],
     "ba-pitch-analyzer": [
       "pitch",
+      "breadboard",
       "lens",
       "orient_dir",
       "spec_folder",
@@ -324,12 +325,14 @@
     "scope-architect": [
       "feature",
       "spec_folder",
-      "tasks"
+      "tasks",
+      "breadboard"
     ],
     "solution-architect": [
       "feature",
       "spec_folder",
-      "project_profile"
+      "project_profile",
+      "breadboard"
     ],
     "spec-evaluator": [
       "spec_folder",
@@ -342,6 +345,7 @@
     ],
     "orient": [
       "pitch",
+      "breadboard",
       "stack",
       "spec_folder",
       "feature"
@@ -709,6 +713,10 @@
             "type": "string"
           },
           "description": "Subset of [idle, loading, success, error, empty] the element must express via data-state."
+        },
+        "source": {
+          "type": "string",
+          "description": "The breadboard UI affordance (U#) this element implements; absent without a breadboard."
         }
       }
     },
@@ -2248,6 +2256,10 @@
           "type": "string",
           "description": "ba-pitch-analyzer (analyze) / orient: the kicked-off pitch path (shaped + bet; frontmatter appetite/status/bet)."
         },
+        "breadboard": {
+          "type": "string",
+          "description": "orient / ba-pitch-analyzer (analyze) / solution-architect / scope-architect: the run's staged breadboard — Places (P#), UI and code affordances (U#, N#), stores (S#), slices (V#). Absent = the pitch has no separate breadboard (it may carry one inline); never inferred from the pitch's folder."
+        },
         "lens": {
           "type": "string",
           "enum": [
@@ -2379,6 +2391,20 @@
           "type": "string",
           "description": "Resolved path to the run's intake — the pitch a fresh ORIENT dispatch is compiled against."
         },
+        "breadboard_path": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Resolved path to the run's staged breadboard (`.shapeup/<slug>/breadboard.md`), the pitch's second half, handed to the four planning dispatches as payload.breadboard. Null when the pitch had no separate breadboard file."
+        },
+        "breadboard_source": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "How `init run` found the breadboard — flag | sibling | shaping-dir | shared-root | embedded — read from the receipt. Null when there was none or the receipt is unreadable."
+        },
         "spec_folder": {
           "type": [
             "string",

package/skills/tech-lead/workflows/shapeup-run.js

@@ -400,6 +400,7 @@ const RESUME = {
   type: "object",
   properties: {
     intake_path: nullable("string"), spec_folder: nullable("string"), orient_dir: nullable("string"),
+    breadboard_path: nullable("string"), breadboard_source: nullable("string"),
     project_profile_path: nullable("string"), status: nullable("string"),
     lens: nullable("string"), stack: nullable("string"),
     run_cmd: nullable("string"), app_url: nullable("string"),
@@ -972,7 +973,7 @@ if (!rs.has_orient_artifacts) {
   await setRunStatus("orienting", "Orient");
   const o = await worker({
     skill: "orient", operation: "orient", schema: ORIENT, phase: "Orient", label: "orient",
-    payload: { pitch: rs.intake_path, spec_folder: specFolder, feature: slug, stack: rs.stack },
+    payload: { pitch: rs.intake_path, breadboard: rs.breadboard_path, spec_folder: specFolder, feature: slug, stack: rs.stack },
     // NAME THE FILES. "write the orient/ artifacts" was the whole instruction, while completion is
     // decided by four exact filenames — so a leg that did the work and called its output
     // `code-surface-map.md` and `discovered-tasks.md` aborted the run at the post-condition, having
@@ -998,8 +999,10 @@ if (!rs.has_orient_artifacts) {
 }
 
 {
+  // `breadboard` travels in the block because a missing one is invisible anywhere later: every
+  // downstream artifact reads the same whether or not the pitch's second half reached the run.
   const g = await crossGate("L1a", "Orient", ["proceed", "ask", "abort"],
-    { spiked_area: spikedArea, spike_result: spikeResult, riskiest_unknowns: riskiest });
+    { breadboard: rs.breadboard_source ?? "none", spiked_area: spikedArea, spike_result: spikeResult, riskiest_unknowns: riskiest });
   if (g.stop) return withWarnings(g.stop);
 }
 
@@ -1015,7 +1018,7 @@ if (!rs.has_spec_tree) {
   await setRunStatus("mapping", "Analyze");
   const a = await worker({
     skill: "ba-pitch-analyzer", operation: "analyze", schema: PHASE_OK, phase: "Analyze", label: "analyze",
-    payload: { pitch: rs.intake_path, spec_folder: specFolder, feature: slug, lens: rs.lens, orient_dir: rs.orient_dir },
+    payload: { pitch: rs.intake_path, breadboard: rs.breadboard_path, spec_folder: specFolder, feature: slug, lens: rs.lens, orient_dir: rs.orient_dir },
     extra: "Write the spec tree and the board from the orient artifacts — do not re-scan the code.",
   });
   if (a.__failed) return diedAt("ANALYZE", a);
@@ -1047,7 +1050,7 @@ if (!rs.has_wiring_map) {
   log(`WIRE — dispatching (slug ${slug})`);
   const w = await worker({
     skill: "solution-architect", operation: "wire", schema: PHASE_OK, phase: "Wire", label: "wire",
-    payload: { feature: slug, spec_folder: specFolder, project_profile: rs.project_profile_path },
+    payload: { feature: slug, spec_folder: specFolder, project_profile: rs.project_profile_path, breadboard: rs.breadboard_path },
     extra: "Write the wiring map: per use case, engine → seam → entry-point call site → affordance.",
   });
   if (w.__failed) return diedAt("WIRE", w);
@@ -1078,7 +1081,7 @@ if (scopes.length === 0) {
   log(`MAP SCOPES — dispatching (slug ${slug})`);
   const m = await worker({
     skill: "scope-architect", operation: "map-scopes", schema: MAPSCOPES, phase: "MapScopes", label: "map-scopes",
-    payload: { feature: slug },
+    payload: { feature: slug, breadboard: rs.breadboard_path },
     // SAY THE PASS RULE, for the same reason ORIENT's filenames are named above: the rule lives in
     // `verify t0` (a fixture passes iff it exits 0) and the architect never saw it. Given a contract
     // that said only "commands that drive this scope end-to-end", it wrote the scope's error paths
@@ -1163,11 +1166,13 @@ if (waves.length > 1 || excluded.added || ceiling < maxParallelScopes) {
       `${ceiling < maxParallelScopes ? ` (the window is ${maxParallelScopes}; the substrate the contracts declared is what caps it, not the dial)` : ""}`);
 }
 
-// Advisory lints at L1b. spec-lint is hard — a substrate overlap makes parallel builds unsafe;
-// trace-lint stays advisory until `covers:` is populated; hill-derive is a projection.
+// Advisory lints at L1b. spec-lint is hard — a substrate overlap makes parallel builds unsafe, and
+// a breadboard Place with no screen builds the wrong thing; trace-lint stays advisory until
+// `covers:` is populated; hill-derive is a projection. The abort names no cause of its own: spec-lint
+// has more than one kind of red, and the detail says which.
 const specLint = await cmd(`verify spec --slug ${slug}`, "MapScopes", "spec-lint");
 if (!specLint.ok) {
-  return aborted("L1b", `spec-lint reported a disjointness or size problem before BUILD: ${specLint.detail || `exit ${specLint.exit_code}`}`);
+  return aborted("L1b", `spec-lint reported red findings before BUILD: ${specLint.detail || `exit ${specLint.exit_code}`}`);
 }
 await advisory(`verify trace --slug ${slug} --quiet`, "MapScopes", "trace-lint");
 await advisory(`reduce hill --slug ${slug}`, "MapScopes", "hill-derive");