shapeup-sdlc 3.1.2 → 3.3.0

package/kernel/probe/stats.mjs

@@ -20,7 +20,7 @@
 // Usage: node `harness probe stats` [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table]
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { resolve, join } from "node:path";
+import { resolve, join, relative, sep } from "node:path";
 import { validate } from "../verify/envelope.mjs";
 import { runArgs } from "../lib/argv.mjs";
 import { localDir, decisions as decisionsPath, metricsDir as metricsDirPath, SHARED } from "../lib/paths.mjs";
@@ -283,6 +283,49 @@ export function readDecisions(cwd) {
   } catch { return []; }
 }
 
+/**
+ * Decision ledgers that landed OUTSIDE the project root — the trace a hook left when it filed
+ * under the shell's working directory instead of the project's.
+ *
+ * The hooks now resolve the root themselves, so a stray is either history from before that fix or
+ * evidence the resolver missed a layout; either way the rows in it are missing from the ledger
+ * `--hooks` reads, and a count that silently omits them is the inert-layer signature this report
+ * exists to expose. Bounded walk: depth-limited, skipping dependency and VCS directories.
+ *
+ * @param {string} cwd - Project root.
+ * @param {number} [maxDepth=8] - How deep to look.
+ * @returns {Array<{path:string, rows:number}>} Each stray ledger and its row count.
+ */
+export function strayLedgers(cwd, maxDepth = 8) {
+  const SKIP = new Set(["node_modules", ".git", ".hg", ".svn", ".hvigor", ".idea", "dist", "build", "target", ".next", ".cache"]);
+  const out = [];
+  const home = decisionsPath(cwd);
+  /**
+   * Visit one directory level.
+   * @param {string} dir - Directory to scan.
+   * @param {number} depth - Its depth below `cwd`.
+   * @returns {void}
+   */
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory() || SKIP.has(e.name)) continue;
+      const sub = join(dir, e.name);
+      const candidate = decisionsPath(sub);
+      if (candidate !== home && existsSync(candidate)) {
+        let rows = 0;
+        try { rows = readFileSync(candidate, "utf8").split("\n").filter((l) => l.trim()).length; } catch { /* unreadable */ }
+        out.push({ path: relative(cwd, candidate).split(sep).join("/"), rows });
+      }
+      walk(sub, depth + 1);
+    }
+  };
+  walk(cwd, 1);
+  return out;
+}
+
 /**
  * Render a StatsReport as a human-readable fixed-width table.
  * @param {object} report - A validated StatsReport (see {@link aggregate}).
@@ -382,6 +425,10 @@ function renderHooks(r) {
     lines.push("", "(zero rows: either no hook has run in this checkout, or the enforcement layer is inert —");
     lines.push(" and that distinction is exactly what this ledger exists to make.)");
   }
+  if (Array.isArray(r.stray_ledgers) && r.stray_ledgers.length) {
+    lines.push("", `stray ledgers: ${r.stray_ledgers.length} decisions.jsonl outside the project root — rows not counted above:`);
+    for (const s of r.stray_ledgers) lines.push(`  ${s.path}  (${s.rows} row(s))`);
+  }
   return lines.join("\n");
 }
 
@@ -403,7 +450,7 @@ export async function cli(rawArgv) {
   if (args.ratchet || args.hooks) {
     const out = {};
     if (args.ratchet) out.ratchet = ratchetReport(readAllTrials(cwd, args.slug ?? null));
-    if (args.hooks) out.hooks = hooksReport(readDecisions(cwd));
+    if (args.hooks) out.hooks = { ...hooksReport(readDecisions(cwd)), stray_ledgers: strayLedgers(cwd) };
     if (format === "table") {
       const parts = [];
       if (out.ratchet) parts.push(renderRatchet(out.ratchet));

package/kernel/reduce/hill.mjs

@@ -9,6 +9,7 @@ import { runArgs } from "../lib/argv.mjs";
 import { scopesDir, hillDir, verdictsDir, resultsDir, discoveryLedger } from "../lib/paths.mjs";
 import { readAllContracts, SCOPE_CONTRACT } from "../lib/contract.mjs";
 import { evalVerdict } from "../probe/eval.mjs";
+import { redBuildRounds } from "../verify/build.mjs";
 
 /**
  * Derive and write the hill phase for all scopes mechanically based on T0, T1, and ledger facts.
@@ -16,7 +17,7 @@ import { evalVerdict } from "../probe/eval.mjs";
  * The derived phase follows these progression rules (facts move dots, not authors):
  * - UPHILL_UNKNOWN: open unknowns > 0 in the ledger for this scope
  * - UPHILL_SOLVED: unknowns 0, no T0-green yet
- * - DOWNHILL_EXECUTION: ≥1 T0-green; T1/seesaw pending
+ * - DOWNHILL_EXECUTION: ≥1 T0-green in a round whose build gate is not red; T1/seesaw pending
  * - FINISHED: T1 PASS ∧ seesaw green
  *
  * @param {string} cwd - The project root directory.
@@ -52,6 +53,15 @@ export function deriveHill(cwd, slug) {
   }
 
   // 2. T0 facts per scope: has it achieved a green overall verdict? was seesaw also green?
+  //
+  // MINUS THE ROUNDS WHOSE BUILD GATE IS RED. A T0 verdict is one scope's fixtures inside its own
+  // substrate; the round build gate (`verify build`) is the feature's build and launch. Measured on
+  // a live run, all fourteen committed shards read DOWNHILL_EXECUTION off T0 verdicts from rounds in
+  // which the app never compiled and never launched — the dashboard showed a feature going downhill
+  // that had not started. A green fixture in a round the gate failed is not evidence the scope
+  // works; it is evidence the fixture does not test the build. No gate artifact at all leaves every
+  // verdict counting exactly as before.
+  const redRounds = redBuildRounds(cwd, slug);
   const t0Facts = {};
   if (existsSync(vDir)) {
     for (const f of readdirSync(vDir)) {
@@ -59,7 +69,7 @@ export function deriveHill(cwd, slug) {
       try {
         const b = JSON.parse(readFileSync(join(vDir, f), "utf8"));
         if (!t0Facts[b.scope_id]) t0Facts[b.scope_id] = { hasGreen: false, seesawGreen: false };
-        if (b.overall === "green") {
+        if (b.overall === "green" && !redRounds.has(Number(b.round))) {
           t0Facts[b.scope_id].hasGreen = true;
           // Read the REAL seesaw result off the verdict artifact (`t0.mjs`'s `writeArtifact()`
           // already persists the full `{ran, pass, scopes_checked, failing}` object), rather than

package/kernel/verify/build.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// The round build gate — does the FEATURE build and launch, before the judge is asked about it.
+//
+// WHY A GATE ABOVE T0. A T0 verdict is one scope's fixtures, run inside that scope's substrate, and
+// the fixtures are the scope-architect's to write. Nothing in that layer proves the feature as a
+// whole compiles or starts. Measured on a live mobile run: every one of 30 T0 trials went green on
+// its first try — the fixtures were TypeScript stand-ins, structural greps and a test-suite wrapper
+// that never compiled its sources — while the ledger's own `run_cmd` failed, and once the compiler
+// could actually reach the new files it reported 58 errors. Three rounds of EVAL then graded a
+// blank screen: nothing in the loop had ever installed or launched the app. The hill shards, derived
+// from those T0 verdicts, all read DOWNHILL_EXECUTION.
+//
+// Two lessons, and this gate is both:
+//
+//   1. A green exit code from the build is not proof the feature compiled. Some toolchains compile
+//      only what is reachable from an entry point, so a scope's files can sit outside the compiled
+//      set and the build stays green. The exit code is the necessary half; `build_probe` is where a
+//      project asserts the other half (the artifact covers what the run wrote), in whatever way its
+//      toolchain makes possible.
+//   2. Nothing else in the loop launches the app. `launch_probe` is where a project installs, starts
+//      and asserts a first screen. For the mobile archetype its absence is called out every round,
+//      because "on-device install unverified" was an L0 risk with no owner for three rounds.
+//
+// WHAT RUNS, in order, each stopping the rest on failure: the ledger's `run_cmd` (the build),
+// then the profile's `build_probe`, then its `launch_probe`. All three are commands the tech lead
+// pinned at GATE L0 — this script invents none of them, and a run that declares none of them gets
+// exit 3 and no artifact, which every reader treats as "no gate declared" rather than as green.
+//
+// THE RED GATE IS THE NEXT ROUND'S BUG LIST. `harness compile` reads the latest gate artifact for
+// the previous round and addresses each failing step to the scopes whose substrate contains the
+// files the output names (unowned → every scope, marked), exactly as it does for an EVAL verdict.
+// `reduce hill` reads the same artifact: a T0-green verdict from a round whose gate is red moves no
+// scope downhill. Both are the same file, written once here — zero LLM tokens, same as T0.
+//
+// Usage:
+//   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify build --slug <slug> --round N [--cwd <dir>]
+//
+// Exit code: 0 = green, 1 = red, 2 = bad argv, 3 = nothing declared (no run_cmd, no probes).
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { runArgs, isMain } from "../lib/argv.mjs";
+import { harnessRun, projectProfile, roundBuildDir, localRoot, runIdFromRoot } from "../lib/paths.mjs";
+import { readContract, readAllContracts, PROJECT_PROFILE, SCOPE_CONTRACT, splitFrontmatter } from "../lib/contract.mjs";
+import { scopesDir } from "../lib/paths.mjs";
+import { digest } from "../probe/digest.mjs";
+
+/** The three steps, in the order they run. */
+export const STEPS = ["run_cmd", "build_probe", "launch_probe"];
+
+/** Archetypes whose product cannot be judged without being launched on a device or simulator. */
+export const LAUNCH_REQUIRED_ARCHETYPES = new Set(["mobile"]);
+
+const TAIL_BYTES = 8 * 1024;
+const tail = (s) => (s || "").length > TAIL_BYTES ? (s || "").slice(-TAIL_BYTES) : (s || "");
+
+/**
+ * The commands this gate runs for a feature, read from the artifacts that declare them.
+ *
+ * `run_cmd` comes from the run ledger's frontmatter (`harness-run.md`, written at GATE L0 and
+ * already what every EVAL order carries); the two probes come from the committed project profile.
+ * Nothing is inferred: an absent field is an absent step.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {{archetype:(string|null), steps:Array<{kind:string, cmd:string}>, warnings:string[]}}
+ *   The declared steps in run order, the profile's archetype, and the warnings a reader should
+ *   see — currently one: a launch-required archetype with no `launch_probe`.
+ */
+export function declaredSteps(cwd, slug) {
+  const warnings = [];
+  let runCmd = null;
+  try {
+    const hr = splitFrontmatter(readFileSync(harnessRun(cwd, slug), "utf8")).meta || {};
+    runCmd = typeof hr.run_cmd === "string" && hr.run_cmd.trim() ? hr.run_cmd.trim() : null;
+  } catch { /* no ledger — no run_cmd */ }
+
+  let profile = null;
+  const pp = projectProfile(cwd, slug);
+  if (existsSync(pp)) profile = readContract(pp, PROJECT_PROFILE)?.contract || null;
+  const archetype = typeof profile?.archetype === "string" ? profile.archetype : null;
+  const pick = (k) => (typeof profile?.[k] === "string" && profile[k].trim() ? profile[k].trim() : null);
+
+  const steps = [];
+  if (runCmd) { steps.push({ kind: "run_cmd", cmd: runCmd }); warnings.push(...fixtureCoverageWarnings(cwd, slug, runCmd)); }
+  else warnings.push("the run ledger declares no run_cmd — the build itself is not part of this gate");
+  const buildProbe = pick("build_probe");
+  if (buildProbe) steps.push({ kind: "build_probe", cmd: buildProbe });
+  const launchProbe = pick("launch_probe");
+  if (launchProbe) steps.push({ kind: "launch_probe", cmd: launchProbe });
+  else if (archetype && LAUNCH_REQUIRED_ARCHETYPES.has(archetype)) {
+    warnings.push(`archetype ${archetype} declares no launch_probe in project-profile.md — nothing in the loop ` +
+      `launches the app, so a blank first screen survives every round. Give the install/launch risk an owner: ` +
+      `a command that installs the built artifact, starts it, asserts the first screen and fails on fatal logs.`);
+  }
+  return { archetype, steps, warnings };
+}
+
+/**
+ * The executable a run command actually invokes — its basename, past any `cd …&&`, `env`, or
+ * `VAR=value` prefix. `cd app && DEVECO_SDK_HOME=/x /tools/hvigor/bin/hvigorw assembleHap` → `hvigorw`.
+ * @param {string} runCmd - The ledger's run command.
+ * @returns {(string|null)} The tool's basename, or null when none can be read.
+ */
+export function buildTool(runCmd) {
+  const segments = String(runCmd || "").split(/&&|;|\|\|/).map((s) => s.trim()).filter(Boolean);
+  for (const seg of segments) {
+    const tokens = seg.split(/\s+/).filter((t) => t && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(t) && t !== "env" && t !== "cd");
+    if (seg.startsWith("cd ")) continue;
+    if (!tokens.length) continue;
+    const base = tokens[0].split(/[\\/]/).pop();
+    if (base) return base;
+  }
+  return null;
+}
+
+/**
+ * Scopes whose fixtures never invoke the build tool `run_cmd` names — ADVISORY.
+ *
+ * A T0 layer can be entirely green on a feature that does not compile when every fixture is a
+ * grep or a stand-in compiler (measured: 13 of 15 fixtures on one run). The harness cannot know
+ * what a project's fixtures should run, but it can see when none of a scope's fixture commands
+ * mention the tool the ledger builds with, and say so beside the gate's verdict. A warning, not a
+ * failure: a library scope with no compiled surface is a legitimate reason for the mismatch.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {(string|null)} runCmd - The ledger's run command.
+ * @returns {string[]} One warning per scope whose fixtures name the tool nowhere.
+ */
+export function fixtureCoverageWarnings(cwd, slug, runCmd) {
+  const tool = buildTool(runCmd);
+  if (!tool) return [];
+  const out = [];
+  let contracts = [];
+  try { contracts = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT).map((x) => x.contract); } catch { return []; }
+  for (const c of contracts) {
+    const fixtures = Array.isArray(c.e2e_verification_fixtures) ? c.e2e_verification_fixtures : [];
+    if (!fixtures.length || fixtures.some((f) => String(f).includes(tool))) continue;
+    out.push(`scope ${c.scope_id}: none of its ${fixtures.length} fixture(s) invoke ${tool} (the ledger's build tool) — ` +
+      `its T0 green is not evidence the scope compiles; only this gate's run_cmd is.`);
+  }
+  return out;
+}
+
+/**
+ * Run one gate command and capture its outcome (10-minute timeout), output tails kept for the digest.
+ * @param {{kind:string, cmd:string}} step - The step to run.
+ * @param {string} cwd - Working directory.
+ * @returns {object} `{kind, cmd, exit, pass, stdout_tail, stderr_tail, error?}`.
+ */
+export function runStep(step, cwd) {
+  const r = spawnSync(step.cmd, { shell: true, cwd, encoding: "utf8", timeout: 10 * 60 * 1000 });
+  const error = r.error ? String(r.error.message || r.error) : null;
+  return {
+    kind: step.kind, cmd: step.cmd,
+    exit: r.status ?? 1, pass: r.status === 0,
+    stdout_tail: tail(r.stdout), stderr_tail: tail(r.stderr),
+    ...(error ? { error } : {}),
+  };
+}
+
+/**
+ * Run the declared steps in order, stopping at the first failure — a probe over a build that did
+ * not complete answers nothing, and would only bury the real error under a second one.
+ *
+ * @param {Array<{kind:string, cmd:string}>} steps - From {@link declaredSteps}.
+ * @param {string} cwd - Working directory.
+ * @returns {{overall:("green"|"red"), steps:Array<object>}} Every declared step, the ones not
+ *   reached marked `skipped: true`.
+ */
+export function runGate(steps, cwd) {
+  const out = [];
+  let failed = false;
+  for (const step of steps) {
+    if (failed) { out.push({ kind: step.kind, cmd: step.cmd, skipped: true }); continue; }
+    const r = runStep(step, cwd);
+    out.push(r);
+    if (!r.pass) failed = true;
+  }
+  return { overall: failed ? "red" : "green", steps: out };
+}
+
+/**
+ * Every gate artifact for a round, oldest first.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} round - Round number.
+ * @returns {Array<{path:string, trial:number, body:object}>} Parsed artifacts; unreadable ones skipped.
+ */
+export function roundBuildArtifacts(cwd, slug, round) {
+  const dir = roundBuildDir(cwd, slug);
+  let files;
+  try { files = readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const f of files) {
+    const m = f.match(/^r(\d+)-t(\d+)\.json$/);
+    if (!m || Number(m[1]) !== Number(round)) continue;
+    try { out.push({ path: join(dir, f), trial: Number(m[2]), body: JSON.parse(readFileSync(join(dir, f), "utf8")) }); }
+    catch { /* skip */ }
+  }
+  return out.sort((a, b) => a.trial - b.trial);
+}
+
+/**
+ * The gate's latest word on a round — the artifact readers branch on.
+ *
+ * Latest, because the gate may run again after a hand fix between launches, and the run must act on
+ * the current state of the build, not the first one recorded. Every earlier artifact stays on disk.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} round - Round number.
+ * @returns {(object|null)} The latest artifact body, or null when the gate never ran for this round.
+ */
+export function latestRoundBuild(cwd, slug, round) {
+  const all = roundBuildArtifacts(cwd, slug, round);
+  return all.length ? all[all.length - 1].body : null;
+}
+
+/**
+ * The rounds whose latest gate artifact is red — the set `reduce hill` subtracts from.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {Set<number>} Round numbers; empty when the gate never ran (non-regression: every
+ *   T0 verdict then counts exactly as it did before the gate existed).
+ */
+export function redBuildRounds(cwd, slug) {
+  const latest = new Map();
+  let files;
+  try { files = readdirSync(roundBuildDir(cwd, slug)); } catch { return new Set(); }
+  for (const f of files) {
+    const m = f.match(/^r(\d+)-t(\d+)\.json$/);
+    if (!m) continue;
+    const round = Number(m[1]), trial = Number(m[2]);
+    if (!latest.has(round) || latest.get(round).trial < trial) latest.set(round, { trial, file: f });
+  }
+  const red = new Set();
+  for (const [round, { file }] of latest) {
+    try {
+      if (JSON.parse(readFileSync(join(roundBuildDir(cwd, slug), file), "utf8")).overall === "red") red.add(round);
+    } catch { /* unreadable → not proven red */ }
+  }
+  return red;
+}
+
+/**
+ * Write the gate artifact immutably (`wx`, next ordinal on collision — the T0 convention).
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} round - Round number.
+ * @param {object} body - Artifact fields.
+ * @returns {{path:string, sha256:string, trial:number}} Where it landed and its digest.
+ */
+export function writeRoundBuild(cwd, slug, round, body) {
+  const dir = roundBuildDir(cwd, slug);
+  mkdirSync(dir, { recursive: true });
+  const existing = roundBuildArtifacts(cwd, slug, round);
+  for (let trial = (existing.length ? existing[existing.length - 1].trial : 0) + 1; ; trial++) {
+    const path = join(dir, `r${round}-t${trial}.json`);
+    const text = JSON.stringify({ schema_version: 1, round, trial, at: new Date().toISOString(), ...body }, null, 2);
+    try {
+      writeFileSync(path, text, { flag: "wx" });
+      return { path, sha256: createHash("sha256").update(text).digest("hex"), trial };
+    } catch (e) { if (e.code !== "EEXIST") throw e; }
+  }
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs verify build --slug <slug> --round <N> [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  round: { type: "int", min: 1, required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Run the round build gate and write its artifact.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {Promise<void>} Exits 0 green, 1 red, 3 nothing declared, 2 bad argv.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const { slug, round } = args;
+  const { archetype, steps, warnings } = declaredSteps(cwd, slug);
+  for (const w of warnings) console.error(`build-gate: ${w}`);
+
+  if (steps.length === 0) {
+    console.log(JSON.stringify({ round, overall: "skipped", steps: [], warnings,
+      reason: "nothing declared — no run_cmd in the run ledger, no build_probe or launch_probe in project-profile.md" }, null, 2));
+    process.exit(3);
+  }
+
+  const gate = runGate(steps, cwd);
+  const failing = gate.steps.filter((s) => !s.skipped && !s.pass);
+  const discovered = failing.flatMap((s) => digest(`${s.stdout_tail}\n${s.stderr_tail}`));
+  const runId = runIdFromRoot(localRoot(cwd, slug));
+  const { path, sha256, trial } = writeRoundBuild(cwd, slug, round, {
+    ...(runId ? { run_id: runId } : {}),
+    archetype,
+    overall: gate.overall,
+    steps: gate.steps,
+    warnings,
+    discovered_tasks: discovered.slice(0, 16),
+  });
+
+  console.log(JSON.stringify({
+    path, sha256, trial, round, overall: gate.overall, warnings,
+    steps: gate.steps.map((s) => (s.skipped ? { kind: s.kind, skipped: true } : { kind: s.kind, exit: s.exit, pass: s.pass })),
+    ...(failing.length ? { failed_step: failing[0].kind, stderr_tail: failing[0].stderr_tail.slice(-1200) } : {}),
+  }, null, 2));
+  process.exit(gate.overall === "green" ? 0 : 1);
+}
+
+if (isMain(import.meta.url)) cli(process.argv.slice(2));

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.3.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"