shapeup-sdlc 3.2.0 → 3.3.0

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

@@ -68,7 +68,9 @@ approval of the new tasks and estimates before resuming the BUILD loop.
 
 ## The EVAL timing rule (the core constraint)
 
-EVAL fires **once** per round and **only** when GATE L2 has confirmed the board is 100% done.
+EVAL fires **once** per round and **only** when GATE L2 has confirmed the board is 100% done
+and the round build gate (§3d) is not red — a feature that does not build or launch has nothing
+for a judge to grade, and the gate's failing step is what round r+1 fixes.
 It is never:
 - called per task,
 - called inside the BUILD loop,
@@ -463,6 +465,27 @@ Read back: the stdout JSON — {path, sha256, trial, overall, regression, score,
         (harness verify t0 calls its sibling harness probe digest internally on failure).
 ```
 
+## 3d. Round build gate → `harness verify build` (once per round, before EVAL)
+```
+Invoke via Bash directly — deterministic tooling, not a worker:
+  node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify build --slug <slug> --round <N>
+Effect: runs, in order and stopping at the first failure, the ledger's `run_cmd` (the build), then
+        project-profile.md's `build_probe` (the built artifact covers what the run wrote — a green
+        exit code is not proof the feature compiled when the toolchain compiles only what an entry
+        point reaches) and `launch_probe` (install, start, assert the first screen, fail on fatal
+        logs). Writes .shapeup/<slug>/build/r<N>-t<T>.json, immutable per run of the gate.
+Read back: stdout JSON — {overall: green|red, steps[], warnings[], failed_step?, stderr_tail?}.
+        Exit 0 green · 1 red · 3 nothing declared (no run_cmd, no probes — logged, never green).
+        A `mobile` profile with no launch_probe is warned about on stderr every round, and so is
+        every scope none of whose fixtures invoke the tool run_cmd builds with — advisory, because a
+        green T0 from such fixtures is not evidence the scope compiles.
+Consequences, both mechanical and both read off the artifact, never off this prose:
+        red → EVAL is not dispatched this round; `harness compile` turns each failing step into a
+              `payload.bugs` entry for round N+1, addressed to the scope whose substrate holds the
+              files the tool's output names (unowned → every scope, marked).
+        red → `reduce hill` withholds DOWNHILL_EXECUTION from every T0-green verdict of round N.
+```
+
 ## 4. EVAL → spec-evaluator (once per round)
 ```
 compile-order --operation evaluate --slug <slug> --worker spec-evaluator --round <r>
@@ -527,6 +550,7 @@ Read back: the proposed cut list + verdict (SHIP now | SHIP after fixing ship-bl
 | `harness-run.md` | **tech lead (sole writer)** | tech lead (round ledger + Hill + run-state), PO (audit) |
 | `scopes/<scope-id>.md` | `scope-architect` (sole writer) | tech lead (substrate/sequence), sandbox hook (write-whitelist), compile-order (inlined into orders) |
 | `t0/verdicts/r<N>-a<M>-t<T>.json` | `harness verify t0` (skill-local, mechanical — not a worker) | spec-evaluator (required citation), tech lead (hill derivation), compile-order (digested errors) |
+| `build/r<N>-t<T>.json` (the round build gate) | `harness verify build` (mechanical — run_cmd + build_probe + launch_probe, once per round before EVAL) | tech lead (GATE L2 block), `harness reduce hill` (a red round moves no dot), compile-order (`payload.bugs` for round N+1) |
 | `t0/trials.jsonl` (the ratchet ledger, append-only, `baseline_trial` as the parent link) | `harness verify t0` (one row per attempt: score, status, delta, tree_ref) | compile-order (`trial_history` into the next order), ship-report (T0 + Ratchet sections), `harness probe stats --ratchet` |
 | `round-ledger.md` | **tech lead (sole writer)** | compile-order (decisions into every order), PO (audit) |
 | `hill/<scope-id>.yml` + `hill-chart.md` | **tech lead (sole writer)** | PO ("status without asking"), scope-hammer (H0 census) |

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"
       }
     ]
   },
@@ -326,13 +347,15 @@
       "feature",
       "spec_folder",
       "tasks",
-      "breadboard"
+      "breadboard",
+      "kb_rules_path"
     ],
     "solution-architect": [
       "feature",
       "spec_folder",
       "project_profile",
-      "breadboard"
+      "breadboard",
+      "kb_rules_path"
     ],
     "spec-evaluator": [
       "spec_folder",
@@ -348,7 +371,8 @@
       "breadboard",
       "stack",
       "spec_folder",
-      "feature"
+      "feature",
+      "kb_rules_path"
     ],
     "qa-edge-hunter": [
       "feature",
@@ -369,7 +393,8 @@
       "scope_id"
     ],
     "coach": [
-      "feedback"
+      "feedback",
+      "stack"
     ]
   },
   "x-result-by-worker": {
@@ -458,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",
@@ -475,7 +500,9 @@
         "hunt",
         "translate",
         "hammer",
-        "coach"
+        "coach",
+        "scan",
+        "research"
       ]
     },
     "Substrate": {
@@ -1442,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",
@@ -2155,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",
@@ -2187,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."
         }
       }
     },
@@ -2230,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",
@@ -2275,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",

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:
@@ -1350,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 {
@@ -1410,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