shapeup-sdlc 3.1.1 → 3.2.0

package/kernel/probe/eval.mjs

@@ -1,8 +1,10 @@
 // probe eval — "what did round N's EVAL WorkResult actually say?"
 //
 // CONTRACT. A bounded, read-only query over the evaluate WorkResult ingest already wrote. Prints
-// `{ok, overall, bug_count, report_path}` on stdout; exits 0 when found and readable, 1 when the
-// result is missing (nothing ran, or ingest hasn't landed yet), 2 on a bad argv. Writes nothing.
+// `{ok, overall, bug_count, report_path, round, status, reason}` on stdout; exits 0 when the round
+// holds a verdict the run may act on, 1 when it does not — nothing ran, ingest hasn't landed, the
+// evaluator refused the round, or the verdict is structurally invalid; `reason` says which — and 2
+// on a bad argv. Writes nothing.
 //
 // WHY THIS EXISTS. `shapeup-run.js` cannot read a file itself (a Workflow script has no filesystem
 // of its own — see this repo's own note on why it may not call `Date.now()`), so every fact it
@@ -23,11 +25,65 @@
 // shared state; the `.md` report is prose for a human. Reading the prose to re-derive a verdict a
 // schema already carries structurally is the paraphrase channel this repo's hooks exist to close
 // everywhere else.
+//
+// WHY "NO VERDICT" CARRIES A REASON. An evaluator that refuses a round — a structural precondition
+// it cannot meet — still writes `evaluate-r<N>.json`, with `status: failed`, no verdict, and the
+// cause as its first deviation. A bare `ok: false` reached the operator as a sub-agent that died
+// after retries, while the one sentence naming the actual cause sat in a file nobody was pointed at.
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
-import { resultsDir } from "../lib/paths.mjs";
+import { resultsDir, scopesDir } from "../lib/paths.mjs";
+
+/** Longest `reason` reported. A deviation is prose written by a worker and can run to paragraphs. */
+const REASON_MAX = 400;
+
+/**
+ * Bound a reason to {@link REASON_MAX} characters.
+ * @param {string} s - The reason.
+ * @returns {string} `s`, or its first REASON_MAX − 1 characters and an ellipsis.
+ */
+const clip = (s) => (s.length > REASON_MAX ? `${s.slice(0, REASON_MAX - 1)}…` : s);
+
+/**
+ * Whether a feature's spec is SCOPED — has scope contracts, the case in which every verdict must
+ * cite the T0 artifacts it re-hashed.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {boolean} True when `scopes/` holds at least one contract (`.md`, or a legacy `.json`).
+ */
+export function isScoped(cwd, slug) {
+  try { return readdirSync(scopesDir(cwd, slug)).some((f) => /\.(md|json)$/.test(f)); }
+  catch { return false; }
+}
+
+/**
+ * Why a verdict cannot stand as its round's judgement on T0 grounds, or null when it can.
+ *
+ * A PASS or FAIL on a scoped spec that cites no T0 artifact is structurally invalid — the
+ * evaluator's own contract says so, because T0 is the machine fact a generator cannot fabricate.
+ * That rule used to live only in the contract, so a verdict citing nothing was ingested, ledgered
+ * and branched on like any other. It is checked here so the round loop, the resume derivation, the
+ * hill and ingest all refuse the same verdict for the same reason.
+ *
+ * PRESENCE, NOT HASHES. The evaluator re-hashes what it cites; a slip transcribing a digest is not
+ * evidence the verdict is wrong, and refusing a round over one would cost a whole re-evaluation.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {object} verdict - The WorkResult's `verdict` block.
+ * @returns {(string|null)} The problem, phrased for an operator; null for a cited verdict, an
+ *   unscoped spec, or a block with no PASS/FAIL in it (there is no judgement to invalidate).
+ */
+export function citationProblem(cwd, slug, verdict) {
+  if (verdict?.overall !== "PASS" && verdict?.overall !== "FAIL") return null;
+  if (Array.isArray(verdict.t0_citations) && verdict.t0_citations.length) return null;
+  if (!isScoped(cwd, slug)) return null;
+  return `the ${verdict.overall} verdict cites no T0 artifact, and a verdict on a scoped spec must ` +
+    "cite the T0 verdict it re-hashed (the order lists them under payload.t0_artifacts)";
+}
 
 /**
  * Read one round's EVAL verdict straight from the WorkResult `reduce ingest` wrote.
@@ -35,20 +91,35 @@ import { resultsDir } from "../lib/paths.mjs";
  * @param {string} cwd - Project root.
  * @param {string} slug - Feature slug.
  * @param {number} round - The EVAL round (`evaluate-r<N>.json`).
- * @returns {{found: boolean, overall: (string|null), bug_count: (number|null),
- *   report_path: (string|null)}} `found: false` when no result exists yet — a fact, not a guess.
+ * @returns {{found: boolean, overall: (string|null), status: (string|null), reason: (string|null),
+ *   bug_count: (number|null), report_path: (string|null)}} `found` is true only for a PASS/FAIL the
+ *   round may act on; otherwise `reason` says why not — a fact, not a guess.
  */
 export function evalVerdict(cwd, slug, round) {
   const path = join(resultsDir(cwd, slug), `evaluate-r${round}.json`);
-  if (!existsSync(path)) return { found: false, overall: null, bug_count: null, report_path: null };
+  const unfit = (reason, status = null, overall = null) =>
+    ({ found: false, overall, status, reason, bug_count: null, report_path: null });
+  if (!existsSync(path)) return unfit("no evaluate result for this round yet");
   let doc;
   try { doc = JSON.parse(readFileSync(path, "utf8")); }
-  catch { return { found: false, overall: null, bug_count: null, report_path: null }; }
+  catch { return unfit("the evaluate result is not readable JSON"); }
+  const status = typeof doc?.status === "string" ? doc.status : null;
   const v = doc?.verdict || {};
   const overall = v.overall === "PASS" || v.overall === "FAIL" ? v.overall : null;
+  if (!overall) {
+    // A worker that refused to grade says why in its FIRST deviation — the only channel it has.
+    const first = Array.isArray(doc?.deviations) && typeof doc.deviations[0] === "string" ? doc.deviations[0] : "";
+    return unfit(clip(first
+      ? `the evaluator returned ${status || "no status"}: ${first}`
+      : `status ${status || "unknown"} with no PASS/FAIL verdict`), status);
+  }
+  const problem = citationProblem(cwd, slug, v);
+  if (problem) return unfit(problem, status, overall);
   return {
-    found: overall !== null,
+    found: true,
     overall,
+    status,
+    reason: null,
     bug_count: Array.isArray(v.bugs) ? v.bugs.length : null,
     report_path: typeof v.report_path === "string" ? v.report_path : null,
   };
@@ -66,12 +137,12 @@ export const ARGV_SPEC = {
  * Report round N's EVAL verdict, mechanically, from the WorkResult on disk.
  *
  * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
- * @returns {void} Exits 0 when a verdict was found, 1 when none exists yet for this round.
+ * @returns {void} Exits 0 when the round holds a verdict the run may act on, 1 when it does not.
  */
 export function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
-  const { found, overall, bug_count, report_path } = evalVerdict(cwd, args.slug, args.round);
-  console.log(JSON.stringify({ ok: found, overall, bug_count, report_path, round: args.round }));
+  const { found, overall, status, reason, bug_count, report_path } = evalVerdict(cwd, args.slug, args.round);
+  console.log(JSON.stringify({ ok: found, overall, bug_count, report_path, round: args.round, status, reason }));
   process.exit(found ? 0 : 1);
 }

package/kernel/probe/resume.mjs

@@ -63,8 +63,9 @@ 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";
 
 /** The run-state values `references/protocol.md` (Part 4 — State) defines. A typo'd status is a rejection,
  *  not a write — the whole point of this file is that a write nobody validates is a write nobody
@@ -377,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,
@@ -405,9 +412,15 @@ export function deriveResumeState(cwd, slug) {
     // that permits the overlap is the same one that makes it invisible to the disjointness lint.
     scope_exclusions: scopeExclusions(cwd, slug, scope_files),
     pending_orders: orderFiles.filter((f) => f.endsWith(".json") && !resultFiles.includes(f)),
+    // A round is DONE when it was graded, not when its result file exists. An evaluator that
+    // refused the round — no PASS/FAIL, or a scoped verdict citing no T0 artifact — still writes
+    // `evaluate-r<N>.json`; counted, the relaunch opened round N+1 over a round nobody judged, with
+    // no bugs to route, and rebuilt every scope. Left open, it re-enters round N, skips the scopes
+    // already green there, and evaluates again.
     eval_rounds_done: resultFiles
       .filter((f) => /^evaluate-r\d+\.json$/.test(f))
-      .map((f) => Number(f.match(/\d+/)[0])),
+      .map((f) => Number(f.match(/\d+/)[0]))
+      .filter((n) => evalVerdict(cwd, slug, n).found),
   };
   return { ...facts, next_phase: nextPhase(facts) };
 }

package/kernel/probe/t0.mjs

@@ -18,13 +18,36 @@ import { join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
 import { verdictsDir } from "../lib/paths.mjs";
 
+/**
+ * Verdict filenames, newest first by their NUMERIC address.
+ *
+ * A string sort files `r1-a1-t10.json` before `r1-a1-t9.json`, and the trial ordinal is shared by
+ * every scope verified at one (round, attempt) — ten scopes on their first attempt are enough to
+ * make an older verdict read as the newest. Names that carry no address sort last.
+ *
+ * @param {string[]} names - Filenames from the verdicts directory.
+ * @returns {string[]} A new array, newest first: round, then attempt, then trial, descending.
+ */
+export function newestFirst(names) {
+  const key = (f) => {
+    const m = f.match(/^r(\d+)-a(\d+)(?:-t(\d+))?\.json$/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : [-1, -1, -1];
+  };
+  return [...names].sort((a, b) => {
+    const ka = key(a), kb = key(b);
+    for (let i = 0; i < 3; i++) if (ka[i] !== kb[i]) return kb[i] - ka[i];
+    return b.localeCompare(a);
+  });
+}
+
 /**
  * The newest green T0 verdict for one scope in one round.
  *
  * @param {string} cwd - Project root.
  * @param {string} slug - Feature slug.
  * @param {string} scopeId - Scope contract id.
- * @param {number} round - Build round.
+ * @param {number} [round] - Build round. Omitted, the newest green verdict of ANY round — what an
+ *   evaluation with no round (a standalone single pass) has to cite.
  * @returns {{green: boolean, path: (string|null)}} `path` is the artifact a later EVAL can cite.
  */
 export function greenVerdict(cwd, slug, scopeId, round) {
@@ -32,11 +55,11 @@ export function greenVerdict(cwd, slug, scopeId, round) {
   if (!existsSync(dir)) return { green: false, path: null };
   // Newest first: an attempt retried after a red one writes a higher trial ordinal at the same
   // (round, attempt) address, and the LAST verdict is the one that stands.
-  for (const f of readdirSync(dir).filter((x) => x.endsWith(".json")).sort().reverse()) {
+  for (const f of newestFirst(readdirSync(dir).filter((x) => x.endsWith(".json")))) {
     const p = join(dir, f);
     try {
       const b = JSON.parse(readFileSync(p, "utf8"));
-      if (b.scope_id === scopeId && b.round === round && b.overall === "green") return { green: true, path: p };
+      if (b.scope_id === scopeId && (round == null || b.round === round) && b.overall === "green") return { green: true, path: p };
     } catch { /* a torn artifact proves nothing; keep looking */ }
   }
   return { green: false, path: null };

package/kernel/reduce/ingest.mjs

@@ -28,6 +28,7 @@ import { fileURLToPath } from "node:url";
 import { validate } from "../verify/envelope.mjs";
 import { runArgs } from "../lib/argv.mjs";
 import { tasksDir, localRoot, dispatchReceipts, legLedger, readRunId } from "../lib/paths.mjs";
+import { citationProblem } from "../probe/eval.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const RESULT_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "../../skills/tech-lead/schemas/work-result.schema.json"), "utf8"));
@@ -596,6 +597,20 @@ export async function cli(rawArgv) {
     process.exit(1);
   }
 
+  // --- T0 citation gate -----------------------------------------------------------------------
+  // A PASS or FAIL on a scoped spec that cites no T0 artifact is not a judgement this run may act
+  // on (see `citationProblem`). `probe eval` refuses it to the round loop; refusing it here as well
+  // keeps the verdict ledger from recording a verdict the loop will never branch on.
+  if (result.verdict) {
+    const problem = citationProblem(cwd, String(result.order_id).split("/")[0], result.verdict);
+    if (problem) {
+      console.error(`ingest-result: result refused — ${problem}.`);
+      console.error(`  The round stays open: re-dispatch the evaluator against its order, which lists`);
+      console.error(`  the T0 artifacts to cite. Nothing was written.`);
+      process.exit(1);
+    }
+  }
+
   // Resolved for EVERY order, not only the gated ones: the attesting receipt is this leg's start,
   // and a standalone or `--no-receipt-check` ingest still deserves a truthful timing row rather
   // than one silently falling back to the order's re-writable `compiled_at`.

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.1",
+  "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