shapeup-sdlc 3.1.2 → 3.3.0

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

@@ -296,6 +296,27 @@
         "cardinality": "1:N",
         "via": "wiring-map entries[].wiring_seam",
         "note": "projected by reduce graph as UseCase -DEPENDS_ON-> Seam. NOTE: the projection reads `row.seam`/`row.entry_point` while WiringEntry declares `wiring_seam`/`entry_call_site` — see harness-defects"
+      },
+      {
+        "from": "RoundBuildVerdict",
+        "to": "ProjectProfile",
+        "cardinality": "N:1",
+        "via": "build_probe + launch_probe",
+        "note": "the gate runs the probes the profile declares; run_cmd comes from the run ledger"
+      },
+      {
+        "from": "RoundBuildVerdict",
+        "to": "AegisTriple",
+        "cardinality": "1:N",
+        "via": "discovered_tasks[]",
+        "note": "a red gate's output, digested — surfaces as payload.bugs on the next round's orders"
+      },
+      {
+        "from": "RoundBuildVerdict",
+        "to": "HillShard",
+        "cardinality": "1:N",
+        "via": "round",
+        "note": "a red gate withholds DOWNHILL_EXECUTION from every T0-green verdict of that round"
       }
     ]
   },
@@ -314,6 +335,7 @@
     ],
     "ba-pitch-analyzer": [
       "pitch",
+      "breadboard",
       "lens",
       "orient_dir",
       "spec_folder",
@@ -324,12 +346,16 @@
     "scope-architect": [
       "feature",
       "spec_folder",
-      "tasks"
+      "tasks",
+      "breadboard",
+      "kb_rules_path"
     ],
     "solution-architect": [
       "feature",
       "spec_folder",
-      "project_profile"
+      "project_profile",
+      "breadboard",
+      "kb_rules_path"
     ],
     "spec-evaluator": [
       "spec_folder",
@@ -342,9 +368,11 @@
     ],
     "orient": [
       "pitch",
+      "breadboard",
       "stack",
       "spec_folder",
-      "feature"
+      "feature",
+      "kb_rules_path"
     ],
     "qa-edge-hunter": [
       "feature",
@@ -365,7 +393,8 @@
       "scope_id"
     ],
     "coach": [
-      "feedback"
+      "feedback",
+      "stack"
     ]
   },
   "x-result-by-worker": {
@@ -454,7 +483,7 @@
       ]
     },
     "Operation": {
-      "description": "The full operation vocabulary. Replaces lifecycle flags (--tasks-only, --from-discovered, --map-scopes …): the caller knows the pipeline position; the worker never re-derives it. Ownership: execute/fix/spike = task-executor · analyze/reconcile/retrofit-surface/coverage = ba-pitch-analyzer · map-scopes = scope-architect · wire = solution-architect · evaluate = spec-evaluator · orient = orient · hunt = qa-edge-hunter · translate = translator · hammer = scope-hammer · coach = coach.",
+      "description": "The full operation vocabulary. Replaces lifecycle flags (--tasks-only, --from-discovered, --map-scopes …): the caller knows the pipeline position; the worker never re-derives it. Ownership: execute/fix/spike = task-executor · analyze/reconcile/retrofit-surface/coverage = ba-pitch-analyzer · map-scopes = scope-architect · wire = solution-architect · evaluate = spec-evaluator · orient = orient · hunt = qa-edge-hunter · translate = translator · hammer = scope-hammer · coach/scan/research = coach (scan seeds the knowledge base from the project on disk instead of from L4 feedback; research seeds it from the platform's official documentation, aimed by a stack hint, and cross-checks the scan's rules where a scan exists; same write surface, same categorization gate).",
       "type": "string",
       "enum": [
         "execute",
@@ -471,7 +500,9 @@
         "hunt",
         "translate",
         "hammer",
-        "coach"
+        "coach",
+        "scan",
+        "research"
       ]
     },
     "Substrate": {
@@ -709,6 +740,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."
         }
       }
     },
@@ -1434,6 +1469,116 @@
         "status"
       ]
     },
+    "RoundBuildVerdict": {
+      "description": "The round build gate's verdict — did the FEATURE build and launch this round, measured before the judge is asked. A T0Artifact is one scope's fixtures inside its own substrate; this is the whole feature's run_cmd (from the run ledger), then the profile's build_probe and launch_probe, run in that order and stopping at the first failure. Zero LLM tokens. Two readers act on it: reduce hill withholds DOWNHILL_EXECUTION from every T0-green verdict of a round whose gate is red (a green fixture in a round the app did not compile is evidence about the fixture, not the scope), and harness compile turns each failing step into a `bug` for the next round's fix orders, addressed by the files the tool's output names. Immutable per gate run (`wx`, next ordinal); readers take the latest artifact for a round.",
+      "x-tier": "LOCAL",
+      "x-location": ".shapeup/<slug>/build/r<N>-t<T>.json",
+      "x-writer": "harness verify build",
+      "x-readers": "harness reduce hill (red rounds move no dot), harness compile (next round's payload.bugs), tech-lead (GATE L2 block: build gate state)",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "round",
+        "trial",
+        "at",
+        "overall",
+        "steps"
+      ],
+      "properties": {
+        "schema_version": {
+          "type": "integer",
+          "enum": [
+            1
+          ]
+        },
+        "round": {
+          "type": "integer"
+        },
+        "trial": {
+          "type": "integer",
+          "description": "Ordinal of this gate run within the round — a re-run after a hand fix lands beside its predecessor, never over it."
+        },
+        "run_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*-[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$"
+        },
+        "at": {
+          "type": "string",
+          "description": "ISO timestamp."
+        },
+        "archetype": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The profile's archetype, for the reader deciding whether a missing launch_probe matters."
+        },
+        "overall": {
+          "type": "string",
+          "enum": [
+            "green",
+            "red"
+          ]
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "run_cmd",
+                  "build_probe",
+                  "launch_probe"
+                ]
+              },
+              "cmd": {
+                "type": "string"
+              },
+              "exit": {
+                "type": "integer"
+              },
+              "pass": {
+                "type": "boolean"
+              },
+              "skipped": {
+                "type": "boolean",
+                "description": "true when an earlier step failed and this one was not run."
+              },
+              "stdout_tail": {
+                "type": "string"
+              },
+              "stderr_tail": {
+                "type": "string"
+              },
+              "error": {
+                "type": "string",
+                "description": "Spawn failure or timeout — the command did not run to completion, which is not the same fact as a non-zero exit."
+              }
+            },
+            "required": [
+              "kind",
+              "cmd"
+            ]
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "What the gate could not check and why — a launch-required archetype with no launch_probe, a ledger with no run_cmd."
+        },
+        "discovered_tasks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/AegisTriple"
+          },
+          "description": "The failing steps' output digested; populated only on red."
+        }
+      }
+    },
     "SeesawRegistry": {
       "description": "The fixture registry of every FINISHED scope — what seesawCheck re-runs on each later attempt so a new scope cannot silently break a shipped one — a regression mistaken for progress is the pathology the seesaw exists for.",
       "x-tier": "LOCAL",
@@ -2147,7 +2292,7 @@
       "x-tier": "SHARED",
       "x-location": "shapeup/<slug>/project-profile.md",
       "x-writer": "tech-lead (GATE L0 — not harness compile, which stays pipeline-blind)",
-      "x-readers": "harness verify trace (reachability entry_point), solution-architect (wire), tech-lead",
+      "x-readers": "harness verify trace (reachability entry_point), harness verify build (build_probe + launch_probe, once per round before EVAL), solution-architect (wire), tech-lead",
       "type": "object",
       "required": [
         "schema_version",
@@ -2179,6 +2324,14 @@
         "note": {
           "type": "string",
           "description": "Optional context on the archetype/entry-point choice."
+        },
+        "build_probe": {
+          "type": "string",
+          "description": "OPTIONAL — a command that asserts the BUILT ARTIFACT, not the build's exit code, and exits 0 only when it holds. Exists because a green build is not proof the feature compiled: some toolchains compile only the files reachable from an entry point, so a scope's new files can sit outside the compiled set while the build stays green (measured: an app package holding 3 compiled files, 58 errors once the rest became reachable). Archetype-specific by construction — e.g. 'the compiled source map lists every file under each scope's substrate'. Run by harness verify build after run_cmd, once per round before EVAL; absent = no such step, never a failure."
+        },
+        "launch_probe": {
+          "type": "string",
+          "description": "OPTIONAL for most archetypes, EXPECTED for `mobile` — a command that installs the built artifact, starts it, asserts the first screen (ids, text, a screenshot diff) and fails on fatal runtime log patterns. Exists because nothing else in the loop launches the app: a blank first screen survived three EVAL rounds on a run whose every T0 fixture was green. Run by harness verify build after run_cmd and build_probe; a mobile profile without one is warned about on every round so the 'on-device install unverified' risk has a named owner. Absent = no such step."
         }
       }
     },
@@ -2222,7 +2375,7 @@
         },
         "kb_rules_path": {
           "type": "string",
-          "description": "Coachable workers (task-executor, ba-pitch-analyzer, qa-edge-hunter): shapeup/knowledge-base/<skill>.md — steering, never spec; conflict → the AC wins, noted in deviations."
+          "description": "Coachable workers (task-executor, ba-pitch-analyzer, qa-edge-hunter, orient, scope-architect, solution-architect): shapeup/knowledge-base/<skill>.md — steering, never spec and never a gate; conflict → the AC, the contract or the gate wins, noted in deviations. The judge and the census are not coachable."
         },
         "verify": {
           "$ref": "#/$defs/VerifySpec",
@@ -2248,6 +2401,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": [
@@ -2263,7 +2420,7 @@
         },
         "stack": {
           "type": "string",
-          "description": "orient: stack hint aiming the code-surface sweeps (e.g. \"pnpm, Next 16 web :3000\")."
+          "description": "orient: stack hint aiming the code-surface sweeps (e.g. \"pnpm, Next 16 web :3000\"). coach (research): the platform and toolchain the official-documentation research is aimed at — required, since a project with nothing on disk names no stack by itself."
         },
         "discovered_ledger": {
           "type": "string",
@@ -2379,6 +2536,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

@@ -2,7 +2,7 @@
 //
 // WHAT THIS FILE OWNS.
 //   ORIENT → GATE L1a → ANALYZE → WIRE → GATE L1a.5 → MAP SCOPES → GATE L1b →
-//   rounds of (BUILD → GATE L2 → EVAL → GATE L3) bounded by budgets.maxRounds →
+//   rounds of (BUILD → build gate → GATE L2 → EVAL → GATE L3) bounded by budgets.maxRounds →
 //   QA → GATE H → ship report → RunReturn.
 //
 // THE THREE PLANES THIS FILE RESPECTS, because collapsing them is what the previous version cost:
@@ -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");
@@ -1345,17 +1350,54 @@ while (verdict !== "pass" && round <= maxRounds) {
     return withWarnings({ status: "gate_h", breaker: "inner", hammer_proposals: allHammer, green_scopes: allGreen });
   }
 
+  // ---- ROUND BUILD GATE — the feature builds and launches, measured before anyone is asked --------
+  //
+  // T0 is per scope and inside the scope's substrate; nothing in it proves the FEATURE compiles or
+  // starts. Measured on a live mobile run: 30/30 T0 trials green on the first try (TypeScript
+  // stand-ins, structural greps, a suite wrapper that never compiled its sources) while the
+  // ledger's own `run_cmd` failed, and three rounds of EVAL then graded a blank screen because
+  // nothing in the loop had ever installed or launched the app. `verify build` runs the ledger's
+  // `run_cmd`, then the profile's `build_probe` and `launch_probe`, and writes one artifact
+  // `reduce hill` and `harness compile` both read — so a red gate moves no dot downhill and becomes
+  // the next round's bug list without this script carrying anything across the round boundary.
+  //
+  // Exit 3 is "nothing declared" — the honest state of a run whose L0 pinned no run command and
+  // whose profile names no probe — and it is logged, not treated as green. Any other non-0/1 exit
+  // means the gate itself did not run, and the run says so rather than inferring a verdict.
+  const gate = await cmd(`verify build --slug ${slug} --round ${round}`, "Build", `build-gate:r${round}`);
+  let buildGate = "green";
+  if (gate.exit_code === 1) {
+    buildGate = "red";
+    log(`BUILD GATE r${round} — RED${gate.detail ? `: ${gate.detail}` : ""}. EVAL will not run over a feature ` +
+        `that does not build or launch; the failing step is compiled into round ${round + 1}'s orders as bugs.`);
+  } else if (gate.exit_code === 3) {
+    buildGate = "undeclared";
+    log(`BUILD GATE r${round} — nothing declared: no run_cmd in the run ledger and no build_probe or ` +
+        `launch_probe in project-profile.md. EVAL runs over an unproven build; pin them at GATE L0.`);
+  } else if (gate.exit_code !== 0) {
+    buildGate = "unknown";
+    log(`BUILD GATE r${round} — the gate itself did not run (exit ${gate.exit_code}` +
+        `${gate.detail ? `: ${gate.detail}` : ""}). Treated as undeclared, not as green.`);
+  }
+
   await advisory(`reduce hill --slug ${slug}`, "Build", "hill-derive");
   {
     const g = await crossGate("L2", "Build", ["proceed", "ask", "abort"],
-      { round, green_scopes: roundGreen, hammer_proposals: roundHammer });
+      { round, green_scopes: roundGreen, hammer_proposals: roundHammer, build_gate: buildGate });
     if (g.stop) return withWarnings(g.stop);
   }
 
   // ---- EVAL — exactly one feature-level pass per round (the single-judge invariant) ------------
   phase("Eval");
   await setRunStatus("evaluating", "Eval");
-  if (args.noEval) {
+  if (buildGate === "red") {
+    // A red gate outranks --no-eval: skipping the judge is the operator's call, but the build failing
+    // is a measured fact, and a round that does not compile has nothing for anyone to pass.
+    verdict = "fail";
+    findings = [];
+    log(`EVAL r${round} — not dispatched: the round build gate is red. The judge grades a running ` +
+        `feature; this one does not build or launch. Round ${round + 1} fixes the gate's failing step.`);
+  } else if (args.noEval) {
     log("EVAL — skipped (--no-eval)");
     verdict = "pass";
   } else {
@@ -1405,7 +1447,7 @@ while (verdict !== "pass" && round <= maxRounds) {
 
   await advisory(`reduce graph --slug ${slug}`, "Eval", `graph:eval-r${round}`);
   await advisory(`reduce hill --slug ${slug}`, "Eval", "hill-derive");
-  const g3 = await crossGate("L3", "Eval", ["loop", "stop", "ask"], { round, verdict });
+  const g3 = await crossGate("L3", "Eval", ["loop", "stop", "ask"], { round, verdict, build_gate: buildGate });
   if (g3.stop) return withWarnings(g3.stop);
 
   if (verdict === "pass") break;                                  // → QA → GATE H → ship