shapeup-sdlc 1.6.2 → 1.7.0

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

@@ -8,6 +8,17 @@ EVAL phase. The feature is done when an EVAL round returns PASS.
 > SHARED spec dir. See tech-lead SKILL.md GATE L1b for the bootstrap step that regenerates it
 > when missing.
 
+**On a spec with committed scope contracts, this loop is now CODE, not prose** —
+`skills/tech-lead/workflows/shapeup-run.js`'s own `while (round <= args.budgets.maxRounds)` loop
+implements exactly the shape below (PASS → ship; `max_rounds` exceeded → GATE H `breaker: outer`;
+else the next round builds bugs only), with the EVAL-timing rule, the regression rule, and the
+three-level breaker all enforced as branches in that script rather than described here for a model
+to follow. Read that script's own comments for the mechanics; this file keeps the historical
+rationale and the parts of the protocol the script does not cover (ESCALATE adjudication,
+discovered-task reconciliation mid-BUILD — see its banner
+for the full list) — and, unchanged, the loop below for a `--tiny` run or a spec with no scope
+contracts, which `shapeup-run.js` is out of scope for by design.
+
 ```
 round r = 1
 loop:
@@ -79,7 +90,6 @@ QA is a pure worker: no verdict, no score, no gate — it writes `~` findings to
 `discovery/ledger.md` and a `qa/hunt-report.md`. Triage happens at SHIP/GATE L4:
 - all findings stay `~` → SHIP; findings carry over as raw ideas (debt-free).
 - PO/TL promote any to must-have → a fix round r+1 (those items only) → EVAL
-  `--single-pass` on them → `/qa-edge-hunter --recheck` (re-probe ONLY the promoted items;
   never a second full hunt) → back to L4.
 - Circuit breaker applies: out of rounds/appetite → ship with `~` findings recorded.
 QA never runs on a FAIL round — a build that hasn't passed conformance isn't worth
@@ -98,15 +108,17 @@ coherent to evaluate yet.
    (scope contracts present: also `/scope-hammer --breaker outer`). Do not start another
    build round automatically.
 3. **attempt_budget (INNER breaker, scope contracts only)** — a single scope's T0 attempt
-   loop exhausts `--attempts` (default 5) without a green result → does NOT stop the round;
-   queues a hammer PROPOSAL for GATE H and moves to the next scope in sequence. See
-   "Three-level circuit breaker" below.
+   loop exhausts `--attempts` (default 5) without reaching a trial that is both `kept` and
+   T0-green, **or** `no_progress_k` consecutive trials come back non-`kept` (the stagnation
+   term, default 2 — `compile-order.mjs` prints it as a JSON breaker object on stderr) →
+   does NOT stop the round; queues a hammer PROPOSAL for GATE H and moves to the next scope
+   in sequence. See "Three-level circuit breaker" below.
 4. **wall_clock_budget (DEADLINE breaker, opt-in)** — elapsed seconds since the run receipt
    exceed `--wall-clock-budget` → do NOT start another build round or another scope; go
    straight to GATE H (`/scope-hammer --breaker deadline`). Checked with
    `scripts/budget-check.mjs` at every round boundary and enforced by `hooks/gate-deadline.mjs`,
    which denies a `task-executor` dispatch past the deadline while leaving `spec-evaluator`,
-   `scope-hammer`, `qa-edge-hunter` and `advisor-protocol` reachable — a run past its deadline
+   `scope-hammer` and `qa-edge-hunter` reachable — a run past its deadline
    must still be able to judge, hammer, and close. Off unless configured.
 5. **Hard error** — a sub-skill fails irrecoverably (e.g. spec folder gone, app won't
    build at all) → stop and report; do not retry blindly.
@@ -124,26 +136,29 @@ INNER    attempt_budget (per scope) — decremented once per T0 attempt inside B
                                        inner breaker for that scope only: the scope is queued
                                        as a hammer PROPOSAL (not a hard stop) and the round
                                        moves on to the next scope in the L1b sequence.
+                                       no_progress_k (default 2) is COMPOSED INTO this same
+                                       breaker rather than added beside it as a fourth budget:
+                                       attempt_budget counts attempts and cannot see that the
+                                       last two produced nothing, so k consecutive non-`kept`
+                                       trials queue the same GATE H proposal early.
 DEADLINE wall_clock_budget_s        — elapsed seconds since the run receipt. Opt-in; off
                                        unless set at L0. Tripping routes to GATE H with
                                        --breaker deadline. Enforced by hooks/gate-deadline.mjs.
 ```
 
-**Why the third one exists — it was measured, and it corrected an earlier diagnosis.** On the
-SDD harness benchmark (F3, Sonnet 5) this harness was killed at the declared 1800 s cap and
-published as a DNF. The natural reading was that it had stalled at a gate. Re-reading the
-retained transcript says otherwise: **327 turns, 262 tool calls, 37 file writes, 19 gate markers,
-last gate L3, and zero stall signals** — the least talkative shapeup run in the whole matrix. It
-was working when the clock ran out.
+**Why the third one exists — and it corrects an earlier diagnosis.** A run killed at an external
+time cap looks like a stall from outside: no verdict, nothing to show. The natural reading is that
+it hung at a gate. Often the transcript says otherwise — steady turns, steady writes, gate markers
+advancing, zero stall signals. The run was working when the clock ran out.
 
 Both existing breakers count *events*, not time: `round_budget` moves once per round,
 `attempt_budget` once per T0 attempt. Neither can observe that round 1 has been running for
 twenty-nine minutes, so a run can burn its entire wall clock with both breakers untouched. The
-cost is not the DNF row — it is that a run killed from *outside* ships nothing, not even the
+cost is not the missing verdict — it is that a run killed from *outside* ships nothing, not even the
 scopes that were already green. A breaker that trips from the inside routes to GATE H, where
 scope-hammer compares the shippable subset against the baseline and ships what works. Same clock,
 different ending.
-Nesting rationale (DD-9): a struggling scope should not freeze every other scope's progress
+Nesting rationale: a struggling scope should not freeze every other scope's progress
 in the same round — only running out of *rounds* (the real six-week analog) stops the whole
 run. A scope that trips its inner breaker still gets judged fairly at GATE H: scope-hammer
 compares "ship without this scope" against the baseline, same as any other cut candidate — it
@@ -151,24 +166,56 @@ is never silently dropped, and it is never allowed to block scopes that ARE work
 
 ## Isolated attempt loop — one T0 attempt, in detail (scope contracts only)
 
+**This is `shapeup-run.js`'s inner per-scope loop, as code**, with one addition the prose below
+never had: before opening a scope's attempt loop, the script checks whether THIS round already
+has a green T0 verdict for that scope on disk, and skips it when it does — the resumability a
+mid-BUILD kill needs, that a session narrating this loop from memory could never guarantee.
+
+Whichever runs it, the loop is a **ratchet**: every attempt is scored against the last kept one,
+and the working tree moves forward only when the score strictly improves. `t0-verify.mjs` makes
+that decision and acts on the tree itself, inside the runtime — its caller reads the decision, it
+never makes it.
+
 ```
 compile-order --scope … --round N --attempt M
                                    → zero-memory WorkOrder (scope contract + this scope's
-                                      tasks + digested errors + ledger decisions — compiled
-                                      facts, no chat history by construction)
+                                      tasks + digested errors + ledger decisions +
+                                      trial_history: the last 8 trials for this scope, each
+                                      with score, status, delta and top-3 digest, CROSSING the
+                                      round boundary — compiled facts, no chat history by
+                                      construction)
 dispatch task-executor --order …   → code within substrate; WorkResult in results/
-ingest-result <result>             → board/ledger writes; escalates[] queued
-handle_escalations(≤3/scope/round) → /advisor-protocol; answer promoted to round-ledger.md
-                                      immediately (must survive the NEXT attempt's fresh
-                                      context — this is what "zero-memory" is compatible with
-                                      escalation memory means, DD-8)
-t0-verify.mjs                      → fixtures + DB probe + (on green) seesaw
-  green            → attempt loop breaks; scope reaches DOWNHILL_EXECUTION
-  red, regression  → git stash (never a hard discard) + retry; a FINISHED scope's fixture
-                      broke (PA5) — the whole point of running seesaw before declaring green
-  red, own fixture  → AEGIS-digest the failure into {file, line, core_message} triples,
-                      feed them into the NEXT attempt's brief; loop
+ingest-result <result>             → board/ledger writes
+(a worker cannot escalate)         → WorkResult carries no escalates field. A phase that
+                                      cannot finish leaves no artifact, the post-condition
+                                      fails, and the run ABORTS naming the phase. Resolve it
+                                      yourself and record the answer in round-ledger.md, which
+                                      the NEXT attempt's fresh context reads back.
+t0-verify.mjs                      → fixtures + DB probe + (on green) seesaw, then scores the
+                                      attempt against the baseline trial and snapshots or
+                                      restores the tree. Branch on `status` from its stdout
+                                      JSON — the tree action has ALREADY happened:
+  kept      strictly better, INCLUDING red-but-improved (2/5 → 4/5 fixtures — the whole point
+              of the ratchet). Tree snapshotted to refs/shapeup/<scope_id>/kept.
+              overall=green → the attempt loop breaks; scope reaches DOWNHILL_EXECUTION.
+              Still red → loop, and attempt M+1 now builds ON attempt M.
+  reverted  not better — and a tie is not better. Tree already restored from the last kept
+              snapshot. Subsumes the retired stash-and-retry branch: a FINISHED scope's broken
+              fixture raises score.regressions and reverts through this same rule, which
+              is why seesaw runs before anything is declared green.
+              rather than the code. Tree kept, baseline reset. Not a verdict, not a failure.
+  crash     a fixture command failed to spawn or timed out; tree restored. Fix the fixture,
+              not the code.
+  (on any red, `discovered_tasks` carries the AEGIS {file, line, core_message} triples, which
+   compile-order folds into the NEXT attempt's order as digested_errors — no separate dispatch)
 ```
+
+**The exit code is not the branch selector.** `t0-verify.mjs` exits 0 on T0-green and 1 on
+T0-red (2 on bad argv), mirroring the `oracles/*` convention — so a `kept` red-but-improved
+attempt, the exact case the ratchet exists for, exits 1. Branch on `status` from the stdout
+JSON; never on `$?`, and never wire this call into a `set -e` / `&&` chain that would read a
+non-zero exit as "stop".
+
 This replaces the old flat per-task loop for any scope that has a contract;
 scopes/specs without one keep the v0.2.6 behavior verbatim (see BUILD(r) table above).
 
@@ -176,9 +223,12 @@ scopes/specs without one keep the v0.2.6 behavior verbatim (see BUILD(r) table a
 A tech-lead judgment, surfaced at GATE L2: if the feature is clearly within what the model
 builds reliably solo, the evaluator is optional overhead. With `--no-eval`, after GATE L2
 the run goes straight to SHIP with verdict `not-evaluated` recorded in the ledger and a
-clear note that nothing was verified beyond the build's own task-executor GATE D checks.
+clear note that nothing was verified beyond task-executor's own per-AC evidence checks.
 
 ## Round-cost intuition
 Build dominates; eval is cheap. Expect each EVAL round to cost a small fraction of a BUILD
 round. This is why running eval once per round (not per task) is the right trade: you pay a
 little QA at the end of each build and keep the expensive build coherent in between.
+
+<!-- test requirement -->
+kept|reverted|rebased|crash, decided in t0-verify.mjs decideStatus()

package/skills/tech-lead/references/state-model.md

@@ -53,7 +53,7 @@ A second, committed `round-ledger.md` (`shapeup/<slug>/round-ledger.md`, SHARED,
 Tier A) holds only what must survive a crash or a `.shapeup/` wipe:
 
 - the resolved model/budget matrix (L0.8/L0.9),
-- the **Decisions** table — every gate crossing and every advisor-protocol ESCALATE answer,
+- the **Decisions** table — every gate crossing and every PO answer to a blocked phase,
   promoted the instant it is given, never batched to round close.
 
 Gate crossings resolved from a **gate answer set** (`scripts/gate-answers.mjs`) are written here