shapeup-sdlc 1.6.2 → 1.7.0

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

@@ -31,10 +31,10 @@ The WorkOrder carries everything the worker may rely on (payload, decisions, dig
 substrate write-contract); the WorkResult carries everything the worker used to write into
 shared files. `validate-envelope.mjs` runs as a PreToolUse hook on Skill|Agent and DENIES a
 dispatch whose `--order` file is missing or schema-invalid. Workers write only their own
-domain artifacts inside their substrate — never boards, ledgers, or run-state (D6, closed).
+domain artifacts inside their substrate — never boards, ledgers, or run-state.
 
 Role → model, resolved once at GATE L0.8 from the `orch`/`exec`/`eval`/`qa` matrix
-(`t0-verify.mjs` is mechanical tooling run directly via Bash, never an Agent — DD-7, zero LLM
+(`t0-verify.mjs` is mechanical tooling run directly via Bash, never an Agent — zero LLM
 tokens):
 
 | Skill | L0.8 role | Why this tier |
@@ -44,7 +44,6 @@ tokens):
 | ba-pitch-analyzer | exec | planner — builder tier, not judgment |
 | scope-architect | exec | scope-contract author (sole writer of scopes/*.md) — builder tier |
 | task-executor | exec | the builder itself |
-| advisor-protocol | exec | adjudicates ESCALATE by precedent/default, budget-capped — not the single judge |
 | spec-evaluator | eval | the single judge (judge ≠ doer) — keep its own matrix key even if a PO points it at the same model as `exec`, so it can be split later without a harness change |
 | qa-edge-hunter | qa | cheapest tier by design — exploratory breadth over depth |
 | scope-hammer | exec | census + baseline comparison, proposes only — not a verdict |
@@ -95,7 +94,6 @@ Order A (the spec tree + board):
   gen from reality), spike-<area>.md (feasibility/contracts).
   Writes (its substrate): spec_folder → _index.md, domain-model.md, ux-behavior.md, usecases/*,
     contracts/*.contract.md, scope-summary.md (+ api-feasibility.md if third-party) and the
-    LOCAL board .shapeup/<slug>/tasks/ (v3.2; regenerable via a generate-board order).
   Returns: WorkResult (artifacts list + discoveries) → ingest-result.
 Order B (the scope contracts):
   compile-order --operation map-scopes --slug <slug> --worker scope-architect
@@ -121,11 +119,6 @@ Returns: WorkResult → ingest-result (which updates the board and bumps discove
 Read back: updated tasks/_index.md + scope-summary.md before routing back to GATE L1b.
 ```
 
-## 2c. BOOTSTRAP LOCAL BOARD → ba-pitch-analyzer (operation: generate-board, v3.2)
-```
-Only when GATE L1b's bootstrap check fires (LOCAL .shapeup/<slug>/tasks/_index.md missing
-AND SHARED shapeup/<slug>/spec/usecases/ present):
-  compile-order --operation generate-board --slug <slug> --worker ba-pitch-analyzer
   Agent (model: exec): Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>
 Effect: regenerates the LOCAL task board fresh from the committed usecases/domain-model/scopes
         — no ledger, no reconciliation. Status bootstraps from committed T0/hill facts at
@@ -149,40 +142,53 @@ r>1 (fix) per bug:
 Scope contracts present (isolated attempt loop, per scope, per attempt):
   compile-order --scope shapeup/<slug>/scopes/<id>.md --round <N> --attempt <M>
   → orders/r<N>-a<M>.json inlines the scope contract, this scope's tasks, promoted ledger
-    decisions, and the previous attempt's AEGIS triples — the zero-memory handoff, compiled
-    from facts only. Dispatch a fresh Agent per attempt (this IS the isolation boundary):
+    decisions, the previous attempt's AEGIS triples, and `trial_history` — the last 8 trials
+    for this scope (score, status, delta, top-3 digest), CROSSING the round boundary so a fix
+    round cannot re-propose a change the build round already reverted. The zero-memory
+    handoff, compiled from facts only. Dispatch a fresh Agent per attempt (the isolation
+    boundary):
     Skill(shapeup-sdlc-plugin:task-executor) --order <path>
-  ingest-result — any escalates[] in the WorkResult are queued → dispatch 3b below.
+  ingest-result — a WorkResult with status "escalated" leaves its artifact unwritten → see 3b below.
 
-Read back: ingest-result's summary line (tasks updated, unblocked, escalates) — not raw board
+Read back: ingest-result's summary line (tasks updated, ACs ticked, unblocked, discoveries) — not raw board
 files. SPIKE tasks close before the tasks they block can build (compile-order enforces the
 dependency order).
 ```
 
-## 3b. ESCALATE adjudication → advisor-protocol (scope contracts present, mid-attempt)
+## 3b. A worker that cannot finish (scope contracts present, mid-attempt)
 ```
-Invoke via Agent (model: exec): Skill(shapeup-sdlc-plugin:advisor-protocol)
-        --ledger shapeup/<slug>/round-ledger.md --escalate <block> [--unattended]
-Effect: adjudicates via precedent / substrate-expansion (→ a scope-architect remap order) / PO ask / conservative
-        default; appends one row to round-ledger.md "Decisions" the instant it resolves.
-Read back: the answer, to fold into the SAME attempt if still in progress, or the next
-        attempt's isolated brief otherwise.
-Authority: advises; never designs, builds, or judges. Budget ≤3/scope/round — the 4th+
-        ESCALATE this scope/round auto-resolves conservatively and flags a GATE H proposal.
+There is NO adjudication dispatch. A worker has no port for "I cannot decide this": WorkResult
+        carries no escalates field, so the question never reaches you as data.
+What you see: the phase produces no artifact. The workflow's post-condition
+        (resume-state.mjs --require <phase>) fails and the run ABORTS, naming the phase.
+Do: read the phase's result file to find what it could not complete, resolve it yourself —
+        by amending the spec, widening the scope contract, or answering the ambiguity in the
+        round-ledger "Decisions" table — then relaunch. The fast-forward re-dispatches only
+        what is still unfinished.
+Why it aborts rather than pauses: nothing persists an answer between launches, so a pause
+        would relaunch into the same order and hit the same wall. Aborting puts the question
+        in front of a human once instead of looping silently.
 ```
 
 ## 3c. T0 verify → scripts/t0-verify.mjs (skill-local; scope contracts present, every attempt)
 ```
-Invoke via Bash directly — NOT an Agent, this is deterministic tooling, not a worker (DD-7):
+Invoke via Bash directly — NOT an Agent, this is deterministic tooling, not a worker:
   node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/t0-verify.mjs" shapeup/<slug>/scopes/<scope-id>.md
         --round <N> --attempt <M> --seesaw-registry .shapeup/<slug>/seesaw/registry.json
 Effect: runs the scope's e2e fixtures + DB probe, then (on green) the seesaw regression check
         over every FINISHED scope's fixtures. Writes the verdict artifact spec-evaluator's
-        GATE V0.7 will require a citation to. Zero LLM tokens — deterministic tooling, not a
+        T0-citation rule will require a citation to, appends one row to t0/trials.jsonl, and — this
+        is the ratchet — scores the attempt against the last kept trial and snapshots or
+        restores the working tree ITSELF. Zero LLM tokens — deterministic tooling, not a
         judge (this is what keeps "T1 once per round" true even though verification runs
-        every attempt, DD-7).
-Read back: overall (green|red) + regression (bool) — drives the attempt-loop branch in
-        round-protocol.md "Isolated attempt loop". On red, its `discovered_tasks` field is
+        every attempt).
+Read back: the stdout JSON — {path, sha256, trial, overall, regression, score, status,
+        baseline_trial, delta, tree_ref}. `status` (kept|reverted|rebased|crash) is what
+        drives the attempt-loop branch in round-protocol.md "Isolated attempt loop"; by the
+        time you read it the tree action has already happened. Never branch on the process
+        exit code: it carries the T0 binary (0 green / 1 red / 2 bad argv, the oracles/*
+        convention), so a `kept` red-but-improved attempt, the ratchet's own signature case,
+        exits 1. On red, its `discovered_tasks` field is
         the AEGIS digest to fold into the next brief — no separate digester dispatch needed
         (t0-verify.mjs calls its sibling aegis-digest.mjs internally on failure).
 ```
@@ -245,10 +251,11 @@ Read back: the proposed cut list + verdict (SHIP now | SHIP after fixing ship-bl
 | `scope-summary.md` | planner (analyze/reconcile orders) | tech lead (Done-when), evaluator (Done-when criteria) |
 | `evaluation/EVAL-FEATURE-<slug>.md` + `.verdicts-*.jsonl` | evaluator (report) / **ingest-result.mjs** (verdict ledger, un-ticks) | tech lead (verdict), next fix order (bug list) |
 | `harness-run.md` | **tech lead (sole writer)** | tech lead (round ledger + Hill + run-state), PO (audit) |
-| `scopes/<scope-id>.md` | `scope-architect` (sole writer, incl. remap/split orders) | tech lead (substrate/sequence), sandbox hook (write-whitelist), compile-order (inlined into orders) |
-| `t0/verdicts/r<N>-a<M>.json` | `scripts/t0-verify.mjs` (skill-local, mechanical — not a worker) | spec-evaluator (required citation), tech lead (hill derivation), compile-order (digested errors) |
-| `round-ledger.md` | **tech lead (sole writer)** | compile-order (decisions into every order), advisor-protocol (appends), 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` | `scripts/t0-verify.mjs` (skill-local, mechanical — not a worker) | spec-evaluator (required citation), tech lead (hill derivation), compile-order (digested errors) |
+| `t0/trials.jsonl` (the ratchet ledger, append-only, `baseline_trial` as the parent link) | `scripts/t0-verify.mjs` (one row per attempt: score, status, delta, tree_ref) | compile-order (`trial_history` into the next order), ship-report (T0 + Ratchet sections), `stats.mjs --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) |
 
-> D6 is closed (v1.0): no worker writes `run-state.md`, the board, or the ledger. A worker
+> The single-writer rule is closed mechanically: no worker writes `run-state.md`, the board, or the ledger. A worker
 > performing a shared-state write is a defect — route it back through its WorkResult.

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

@@ -2,12 +2,26 @@
 
 The full collect-lists, gate-output blocks, and delegation scripts for every gate and delegation
 step, extracted from `SKILL.md` (progressive disclosure). **Read the relevant section when you
-reach that gate** — `SKILL.md` carries the workflow spine, the build/eval loop, and the hard
-rules; this file carries the step-by-step playbooks. The L2/L4 gates stay hook-enforced regardless
-of where the prose lives.
+reach that gate** — `SKILL.md` carries the workflow spine and the hard rules; this file carries the
+step-by-step playbooks. The L2/L4 gates stay hook-enforced regardless of where the prose lives.
 
-Order matches the run: GATE L0 → ORIENT → GATE L1a → WIRE/L1a.5 → MAP SCOPES → GATE L1b →
-(BUILD → GATE L2 → EVAL, in SKILL.md) → GATE L3 → SHIP → GATE L4.
+**Which lane these playbooks serve.** The gate blocks below are lane-independent: every
+lane emits them verbatim, and on the scoped lane `shapeup-run.js` returns the `block` field for
+`SKILL.md` to print unchanged. What differs is who runs the loop *between* the gates:
+
+| lane | BUILD → GATE L2 → EVAL is | read |
+|---|---|---|
+| a spec with committed `scopes/*.md` (the common case) | **code** — `skills/tech-lead/workflows/shapeup-run.js`'s round loop | that script's comments |
+| `--tiny`, or a spec with no scope contracts yet | **prose**, unchanged and non-regression | `references/round-protocol.md` (`:11-22` states the same split) |
+
+Order matches the run: GATE L0 → ORIENT → GATE L1a → ANALYZE → WIRE/L1a.5 → MAP SCOPES →
+GATE L1b → (BUILD → GATE L2 → EVAL — see the table above) → GATE L3 → SHIP → GATE L4.
+
+⟐ **ANALYZE runs before WIRE.** MAP SCOPES' two dispatches split around
+L1a.5: `analyze` writes the spec tree, then `wire` reads its `usecases/` — one wiring-map entry per
+use case — then `map-scopes` slices. Dispatching WIRE first hands `solution-architect` an empty
+spec folder, which its own input contract excludes (`skills/solution-architect/SKILL.md:43-44`); it
+escalates, writes nothing, and every relaunch re-dispatches it.
 
 ---
 
@@ -37,11 +51,16 @@ Collect (explicit — never inferred):
           - LOCAL   .shapeup/<slug>/      — run-trace (hidden, gitignorable):
               harness-run.md (this ledger), digest, orient/, evaluation/, qa/,
               discovery/ledger.md, orders/ + results/ (the envelope port), tasks/ (the task
-              board, v3.2 — regenerable via a generate-board order on any machine)
           spec_folder = shapeup/<slug>/spec/ (the deliverable arg passed to ba/eval/exec)
   L0.3  lens: lite | standard | cross-context   (passed to planner at step 8)
   L0.4  stack hint (e.g. "pnpm, Next 16 web :3000") — aims orient's code-surface sweeps + run commands
-  L0.5  eval dimensions: default [spec-conformance]; only add if user asks
+  L0.5  eval dimensions: default [spec-conformance]; only add if user asks. An added dimension
+        must reach `init-run.mjs --dimensions <a,b>` — it is recorded in the ledger's
+        `eval_dimensions:` line and every EVAL order is compiled from there, so a set agreed
+        in conversation and not passed to the flag grades nothing. Shipped ids:
+        spec-conformance, tdd-surface, integration, completeness, test-surface-conformance
+        (security + performance ship disabled). Whatever is left out is reported at L4 as
+        `dims_not_evaluated` — "shipped" never silently means "verified for all".
   L0.6  max_rounds: default 3, appetite-informed (see L0.1b)
   L0.7  auto level:
           interactive (default) — pause at every L-gate; sub-skills keep their own gates
@@ -49,7 +68,7 @@ Collect (explicit — never inferred):
                                    at L1a/L1b (orient+plan), L3 (verdict), L4 (ship)
           --unattended           — auto-confirm all L-gates too; stop only on PASS,
                                    max_rounds, or hard error (for headless / Agent SDK / CI)
-  L0.8  Model & budget resolution (addendum Blueprint F, four layers, highest precedence
+  L0.8  Model & budget resolution (four layers, highest precedence
         first) — resolve ONCE here, record the resulting matrix in the ledger header:
           /ship flags  →  .claude/settings.local.json (per-member, Tier C)  →
           .claude/settings.json (team defaults, committed)  →  skill-shipped defaults
@@ -60,7 +79,7 @@ Collect (explicit — never inferred):
         A requested model unavailable on the member's plan → degrade to the next tier down,
         record the degrade in the ledger (R2 — invariants are code paths, so adherence
         survives even when the model tier doesn't).
-  L0.9  attempt_budget: the INNER circuit breaker (design spec DD-9), nested inside
+  L0.9  attempt_budget: the INNER circuit breaker, nested inside
         max_rounds (the OUTER breaker, unchanged, L0.6). Default 5 — the number of T0 verify
         attempts a single scope gets inside one round before its attempt loop trips and
         queues a hammer PROPOSAL for GATE H rather than blocking the round. Only meaningful
@@ -84,8 +103,7 @@ none resolvable  ->  ABORT. Print the ✋ NO INTAKE block from SKILL.md and stop
                      Do NOT describe the pipeline that "will" run.
 ```
 An orchestrator with no spec has nothing to orchestrate. Narrating the gate list in that state
-produces output that reads exactly like a successful run and contains no work — measured at 29%
-acceptance, n=3, on the benchmark. Fail loudly instead.
+produces output that reads exactly like a successful run and contains no work. Fail loudly instead.
 
 **GATE L0 Output:**
 ```
@@ -149,7 +167,12 @@ Do NOT enter MAP SCOPES until Orient is accepted.
 2. WIRE — compile-order --operation wire --slug <slug> (worker→solution-architect), payload
    {project_profile}. Sole writer of committed wiring-map.md (per-UC engine → seam → entry-point
    call site → affordance). ⏸ GATE L1a.5: confirm each UC has a declared seam before slicing.
-3. COVERAGE (folds into MAP SCOPES) — compile-order --operation coverage → ba writes the SHARED
+   ⟐ PRECONDITION: MAP SCOPES step 1 (ANALYZE) has already run and usecases/ is
+   populated. WIRE writes one entry per use case, so dispatching it against an empty spec folder
+   is an escalation, not a wiring map — and a phase that writes no artifact is re-dispatched on
+   every relaunch. Verify: node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/resume-state.mjs"
+   --slug <slug> --require analyze (exit 0 = the spec tree is there; exit 6 = do not dispatch WIRE).
+   Post-check the same way after the dispatch: --require wire.
    requirements.md registry (atomic REQ clauses, frozen ids).
 4. trace-lint — node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/trace-lint.mjs" --slug <slug>. ADVISORY at L1b:
    covers-closure (every covered REQ named by ≥1 AC's covers:) + reachability (every UC engine
@@ -160,6 +183,11 @@ Do NOT enter MAP SCOPES until Orient is accepted.
 
 ## MAP SCOPES (step 8) — delegate to ba-pitch-analyzer (orient-informed)
 
+⟐ **Step 1 runs BEFORE the WIRE section above; step 2 runs after it.** The two
+dispatches sit either side of L1a.5: ANALYZE writes the use cases WIRE reads, and MAP SCOPES slices
+against the seams WIRE declared. Sequence: ORIENT → L1a → **ANALYZE** → **WIRE** → L1a.5 →
+**MAP SCOPES** → L1b.
+
 ```
 Two orders, two workers, one step (both model: exec — see references/delegation.md):
 1. ANALYZE + BOARD — compile-order --operation analyze --slug <slug> --worker ba-pitch-analyzer
@@ -179,7 +207,7 @@ Record in ledger: planner duration + task count + scope count.
 Faithful note: keep the planner ambitious on scope but high-level on tech — do not push it
 to over-specify implementation. Errors baked into the spec cascade into every build round.
 Honest deviation: `ba` is heavier than Shape Up's light "map scopes" bucketing — that extra
-upfront spec-traceability is a deliberate trade for an LLM builder (redesign doc D8), not
+upfront spec-traceability is a deliberate trade for an LLM builder, not
 "pure Shape Up". State it; don't pretend otherwise.
 
 ---
@@ -203,7 +231,6 @@ v0.2.6 (non-regression).
 `.shapeup/<slug>/tasks/_index.md` missing AND `shapeup/<slug>/spec/usecases/`
 exists → a teammate (or a `--from build` resumed run) has the SHARED spec via git but no LOCAL
 task board on this machine — `.shapeup/` is gitignored and never travels with a branch.
-compile-order --operation generate-board --slug <slug> --worker ba-pitch-analyzer, then
 Agent (model: exec): Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path> + ingest —
 regenerates the board from the committed usecases/domain-model/scopes. Record the bootstrap in
 the ledger. No-op on a fresh r=1 run (MAP SCOPES just wrote the board on this same machine) or
@@ -224,13 +251,12 @@ No scope contracts (pre-v0.3.0, unchanged from v0.2.6):
     - any SPIKE tasks (third-party feasibility) that block others
     - scope-summary "Done when" headline statements
 
-Substrate-disjointness assertion (design spec §5.1 Blueprint A, only when
+Substrate-disjointness assertion (only when
 shapeup/<slug>/scopes/*.md exist — scope-architect's lint pass already ran;
 this is the orchestrator's own re-confirmation before committing to a build sequence):
   - Run `node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/spec-lint.mjs" --slug <slug>`: DISJOINT (a file in two
     scopes' `allowed_file_substrate` without BOTH declaring it `shared_substrate` — PA3
     waiting to happen), PA1 (directory-aligned scope), PA2 (size cap). Any red → HARD STOP,
-    route a remap order to scope-architect before BUILD — a human may have hand-approved
     past a 🔴 at the architect's own checkpoint.
   - Lock the build SEQUENCE riskiest-first: order scopes by open-unknowns count (from
     hill/<scope-id>.yml if present, else the orient hill signal), not by file count or
@@ -247,11 +273,27 @@ Do NOT enter BUILD until the board is accepted.
 
 ---
 
+## GATE L2 — Board 100% Done (Pre-Eval)
+
+**Purpose:** The single exit point from the BUILD loop into EVAL. It ensures every scope is green before invoking the evaluator.
+
+**Output:**
+```
+⏸ GATE L2 — Board 100% ✅ + T0-green
+Feature   : [slug]
+Round     : [r]
+Scopes    : [N] green, [M] queued for hammer
+```
+
+Under `--interactive` / `--auto`, the hook warns if the board is not truly green (advisory) and requires explicit PO approval to proceed. Under `--unattended`, it automatically aborts on a red board or proceeds on a green one.
+
+---
+
 ## GATE L3 — Verdict & Loop
 
 ```
 Render the 🗻 Hill report (slice-level) — NOT a task count. Scope contracts present → read
-  committed hill/<scope-id>.yml shards (mechanical phases from GATE L2.4, DD-10). No contracts →
+  committed hill/<scope-id>.yml shards (mechanical phases from GATE L2, never authored). No contracts →
   fall back to the board + open-unknowns heuristic (uphill/crest/downhill/done). See
   references/ledger-schema.md "Hill report". Roadmap rule unchanged either way: progress is
   reported by hill position, never by "N/M tasks done".
@@ -267,7 +309,6 @@ PASS:
       + .shapeup/<slug>/qa/hunt-report.md. No verdict — the run's verdict stays this EVAL's PASS.
       → then proceed to SHIP (triage of QA findings happens at SHIP S.0/GATE L4).
   → subsequent PASS (a promoted-findings fix round): Agent (model: qa):
-    Skill(shapeup-sdlc-plugin:qa-edge-hunter) --recheck on the promoted items only, then SHIP.
   → --no-qa or skill absent: proceed straight to SHIP; ledger records `qa: skipped`.
 
 FAIL:
@@ -289,7 +330,7 @@ Decision  : [SHIP | re-build bugs in round r+1 | escalate: max rounds hit]
 ```
 The Hill is the progress narrative; the board's `N/N ✅` is execution substrate (it gates
 EVAL at L2), never the headline. Slices come from `ba`'s board; if slice IDs aren't present
-yet (D3 deferred), report at task-group level and note the fallback in the ledger.
+yet, report at task-group level and note the fallback in the ledger.
 
 ---
 
@@ -304,7 +345,7 @@ S.0  GATE H — delegate to scope-hammer (this IS Shape Up's "Decide When to Sto
                                               exhausted scopes accumulated during BUILD)
              (no --breaker flag)              normal stop — all scopes FINISHED, post-QA-hunt
      Feeds it: qa/hunt-report.md findings (when present), discovery/ledger.md open items,
-               advisor-protocol budget-overflow flags, the hammer-proposal queue from BUILD.
+               the hammer-proposal queue from BUILD (attempt-budget exhaustions).
      Reads back: its GATE H0/H1/H2 output — census, baseline comparison, cut list + verdict.
      Authority: scope-hammer proposes; the tech lead records the PO's decision in
        round-ledger.md and performs the actual close (S.1 onward). It never ships on its own.
@@ -326,35 +367,36 @@ S.2  Print a feature summary: tasks shipped, rounds used, final verdict, dims ev
      (and explicitly: dims NOT evaluated, so "shipped" is never read as "verified for all").
 S.3  Point to the traceability: tasks/_index.md (all ✅) + EVAL-FEATURE-<slug>.md (PASS) +
      harness-run.md (the round ledger).
-S.4  task-executor's GATE E remains the formal per-task close; the tech lead confirms the
-     feature-level close.
+S.4  task-executor's own verification checklist remains the formal per-task close; the tech
+     lead confirms the feature-level close.
 S.5  Deploy truth — "done means deployed", honestly. Building stops at "built & verified";
      deployment is an outward-facing action gated to the PO. Either:
-       - PO says yes → run the project deploy (docs/infra/DEPLOYMENT.md) and record "deployed".
+       - PO says yes → run the project's own deploy procedure and record "deployed".
        - otherwise → record "built & verified — deploy pending (PO)".
      NEVER auto-deploy; "shipped" must never silently mean "deployed".
-     (Baseline-anchored scope-hammering at ship time is redesign-doc D5 — deferred; for now,
+     (Baseline-anchored scope-hammering at ship time is deliberately deferred; for now,
       `ba`'s Appetite Guard covers overflow and cuts go to synthesis "Hammered Out".)
-S.6  Harvest one signal row → append to `shapeup/metrics/<machine-id>.jsonl`
-     (committed, SHARED root; sharded per machine so concurrent runs never merge-conflict on
-     one file — addendum Δ3; an aggregate view is `cat shapeup/metrics/*.jsonl`).
+S.6  Harvest one signal row → append to `.shapeup/metrics/<machine-id>.jsonl`
+     (LOCAL root, gitignored since ADR-0001 — a committed shard keyed on a hostname only
+     grows and publishes a machine name; sharded per machine so shards can be pooled
+     deliberately without colliding on one filename. The read plane is
+     `stats.mjs`, or `cat .shapeup/metrics/*.jsonl`).
      Copy fields that ALREADY exist as structured output (run-state, final EVAL report,
      discovery ledger, qa/hunt-report, breadboard B5). Two hard rules:
        1. Harvest only fields that already exist at ship time — never evaluate something new.
        2. Record facts, never compute a new verdict (no `run_quality_score` — that would be
           a second judge behind spec-evaluator). The eval suite interprets; harvest records.
      `final_audit_score` is COPIED from the EVAL report, never re-graded.
-     ALSO copy the two v1.5 exit measurements, both produced by scripts at zero model tokens:
+     ALSO copy two run-quality measurements, both produced by scripts at zero model tokens:
        node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/stats.mjs" --ratchet --slug <slug>
          → `ratchet`: {trials, scopes_multi_trial, improvement_rate, monotone_rate,
                        sawtooth_count, mean_trials_to_green}
        node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/stats.mjs" --hooks
          → `hooks`: {evaluations, denials, errors, per_hook}
-     Harvest them HERE or lose them: both read LOCAL ledgers (t0/trials.jsonl,
-     decisions.jsonl) under the gitignored `.shapeup/` root, so a number left there
-     answers its question exactly once and is then wiped. The committed shard is the only
-     record that accumulates across runs and across machines — which is what both exit
-     criteria require, since neither is meaningful from a single run.
+     Harvest them HERE or lose them: both read per-run working ledgers (t0/trials.jsonl,
+     decisions.jsonl) that the next run's bookkeeping supersedes, so a number left there
+     answers its question exactly once. The metrics shard is the one record that
+     accumulates across runs — and neither measurement is meaningful from a single run.
      → full field list + row template: references/ledger-schema.md "Harvest row".
 ```
 

package/skills/tech-lead/references/hard-rules.md

@@ -0,0 +1,34 @@
+# Hard Rules (never override without explicit user instruction)
+
+Moved out of `SKILL.md` when the round loop became a launchable script:
+most of what this table used to guard against — a partial board reaching EVAL, a gate crossed
+on the model's own authority, an evaluator called mid-BUILD — is now a property of
+`skills/tech-lead/workflows/shapeup-run.js`'s code, not a rule a model has to remember to obey.
+The table stays as the readable rationale for WHY the code is shaped the way it is; the runtime
+guarantee lives in the script and, where noted, in a hook.
+
+| Rule | Rationale |
+|------|-----------|
+| Orchestrates Building only (steps 7–11); shaping/betting/kick-off are PO-personal, upstream | Intake is a kicked-off pitch, not a raw idea — the tech lead does no shaping/planning-authority work |
+| ORIENT (step 7) runs before MAP SCOPES (step 8) | Roadmap: no pre-divided tasks at kick-off; the team orients first so the board is reality-born |
+| Intake must be English before ORIENT; tech lead does NOT translate — it delegates to `translator` at GATE L0 | Translation is a separate single-purpose skill; the intake conversation only detects + sequences it, before RunArgs is ever compiled |
+| Every worker dispatch goes through the envelope port: compile-order → `--order` → ingest-result; shared state is written ONLY by ingest | The single-writer rule is mechanically true: a worker that writes boards/ledgers/run-state is a defect, and a malformed envelope is denied by the validate-envelope hook before it can corrupt run truth. `shapeup-run.js` uses this same shape for every operation in the central registry — orient, wire, analyze, map-scopes, evaluate, hunt, hammer alike |
+| Progress is reported by Hill position, never by counting tasks | The roadmap forbids task-counting; a 90%-done slice can still be stuck uphill on the one unknown that matters |
+| Evaluator runs once per round, only after GATE L2 (board 100% done) | The whole point: cheap end-of-round QA, never per task. `shapeup-run.js`'s round loop dispatches spec-evaluator exactly once per iteration, after the GATE L2 resolution — there is no code path that calls it from inside the scope attempt loop |
+| Evaluator never called inside the BUILD loop | Keeps the build coherent and the run cheap |
+| r>1 builds bugs only, never the whole board | Don't re-do passing work; minimize churn — see round-protocol.md's regression rule for what DOES re-run (touched UCs' full Test Surface) |
+| Stop at max_rounds; escalate honestly | No infinite fix loops; `shapeup-run.js` returns `{status: "gate_h", breaker: "outer"}` rather than looping past the budget |
+| Tech lead delegates, never reimplements a sub-skill | Stays thin; each skill keeps its own gates and authority |
+| Every delegation to a sub-skill (except the mechanical `t0-verify.mjs`/`compile-order.mjs`/`ingest-result.mjs`) is a fresh Agent on the L0.8-resolved model | Isolation the zero-memory-handoff design assumes; a direct inline call would silently drop the model matrix — see references/delegation.md "Invocation mechanism" |
+| Planner stays high-level on tech | Spec errors cascade into every build round |
+| Never auto-deploy; "shipped" never silently means "deployed" | Deploy is outward-facing, PO-gated; record "deploy pending (PO)" otherwise |
+| "Shipped" names the dims NOT evaluated | `RunReturn`'s `dims_not_evaluated` field carries this; the L4 sign-off block shows it, never silently drops it |
+| Every gate emits the canonical `⏸ GATE LN — Title` block before any narrative | Composed by the workflow (`gateBlock()`), emitted VERBATIM by the skill — conversational re-summary is not a gate |
+| In interactive/--auto: a `paused` return stops and waits for PO confirmation | Never auto-proceed past a gate; the PO must cross each threshold explicitly — see "The pause protocol" in SKILL.md |
+| At GATE L3 FAIL: name scope (task + failed criterion), never prescribe fix options | Root cause analysis and fix paths belong to the implementer, not the orchestrator |
+| SHIP harvest records facts only — copies existing structured output, never computes a new verdict/score | A self-computed score = a second judge behind spec-evaluator (breaks single-judge, invites Goodhart); the eval suite interprets, harvest records |
+| Three-level circuit breaker: attempt_budget (inner, per scope) nests inside round_budget (outer), with an opt-in wall_clock_budget_s deadline | An exhausted scope queues a GATE H hammer proposal, it never blocks the round; only round_budget hitting 0 stops the whole run; the deadline breaker (checked every round boundary in `shapeup-run.js`) routes to GATE H so a run out of clock still ships what is green instead of being killed from outside |
+| The tech lead never hand-edits a scope contract | scope-architect is its sole writer (single-writer-per-file) |
+| Substrate-disjointness + PA1/PA2 lints are re-asserted at GATE L1b (spec-lint.mjs) even when scope-architect already checked them | A human may have hand-approved past a 🔴 at the architect's checkpoint; `shapeup-run.js` runs spec-lint itself, in code, before resolving L1b |
+| Hill phase is read from mechanical facts (T0/T1/seesaw), never declared by a worker | Closes the self-reported-confidence risk outright — facts move dots, not authors |
+| GATE H is delegated to scope-hammer, never adjudicated inline by the tech lead | Keeps the orchestrator thin; census/baseline-comparison/cut-list logic has one owner |

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

@@ -34,12 +34,12 @@ disclosure). Read this when you need the exact CLI shape or a flag's effect.
 | `--unattended` | Auto-confirm all L-gates (headless / CI) |
 | `--max-rounds N` | BUILD→EVAL cycles before escalating (default 3) — the OUTER breaker |
 | `--attempts N` | Per-scope T0 attempts before queuing a GATE H hammer proposal (default 5) — the INNER breaker; no-op on specs without scope contracts |
-| `--orch-model / --exec-model / --eval-model / --qa-model <name>` | Override L0.8's resolved model matrix for this run only (highest precedence) |
+| `--exec-model / --eval-model / --qa-model <name>` | Override L0.8's resolved model matrix (`RunArgs.models`: exec/eval/qa) for this run only — highest precedence. The orchestrator itself runs in-session; it has no model knob here |
 | `--from orient\|plan\|build\|eval` | Resume an in-progress run at a build-phase step |
 | `--no-eval` | Skip the evaluation pass this run (trivial feature) |
 | `--no-qa` | Skip the post-PASS /qa-edge-hunter pass (ledger records `qa: skipped`) |
 | `--tiny` | The small-change lane: orient (light) → single-task board → build → T0 → done. Implies `--no-eval --no-qa`, skips WIRE and scope contracts, collapses the gates to L0 + L4. See "The tiny lane" in SKILL.md — the L0 fit-check is mandatory and the ledger records `lane: tiny` |
-| `--dimensions <list>` | Eval dimensions (default spec-conformance) |
+| `--dimensions <list>` | Eval dimensions, comma-separated (default `spec-conformance`). Passed straight through to `init-run.mjs --dimensions`, which records the set in the ledger's `eval_dimensions:` — that line is what every EVAL order is compiled from, so a dimension named anywhere else does not run. Ids the evaluator ships: `spec-conformance`, `tdd-surface`, `integration`, `completeness`, `test-surface-conformance`, `security`, `performance` (the last two are disabled stubs); a dimension you inject yourself is named here the same way |
 
 ---
 

package/skills/tech-lead/references/ledger-schema.md

@@ -6,7 +6,7 @@ not a shared deliverable). It is the structured
 artifact that carries state across rounds and across sessions (so `--from` can resume), and
 the PO's audit of how the feature was built.
 
-**The tech lead is the sole writer of this file** (redesign doc D6). It is the authoritative
+**The tech lead is the sole writer of this file.** It is the authoritative
 run-state for the whole build phase — rounds, gate decisions, Hill positions, verdicts,
 `discovered_rounds`, config, language record. Workers never write here; the tech lead passes
 them what they need (`feature`, `spec`, `stack`, `discovered_rounds`) as args. The board
@@ -19,7 +19,7 @@ type: harness-run
 feature: [slug]
 spec_folder: [path to SHARED spec deliverable, e.g. shapeup/<slug>/spec/]
 lens: lite | standard | cross-context
-eval_dimensions: [spec-conformance]
+eval_dimensions: [spec-conformance]   # the set from GATE L0.5 (init-run --dimensions); every EVAL order is compiled from THIS line
 max_rounds: 3
 auto_level: interactive | auto | unattended
 status: orienting | mapping | building | evaluating | shipped | escalated
@@ -71,7 +71,7 @@ Position triggers:
 - ✅ **Done** — slice clickable-done.
 
 Source: `orient/hill-signal.md` (area-level, at L1a) then the board + open SPIKE/contract state
-(slice-level, L1b onward). If slice IDs aren't on the board yet (D3 deferred), report at
+(slice-level, L1b onward). If slice IDs aren't on the board yet, report at
 task-group level and note the fallback here.
 
 ## Decisions log
@@ -116,7 +116,7 @@ Decision owner: PO.
 
 Lives at `shapeup/<slug>/round-ledger.md` (SHARED root, tracked). Not a replacement
 for `harness-run.md` — a small, committed **subset** of it: the two things that must survive
-a `.shapeup/` wipe or a crash (design spec addendum §F.3). Absent on specs with no scope
+a `.shapeup/` wipe or a crash. Absent on specs with no scope
 contracts; `harness-run.md`'s existing Decisions log stays the only ledger there.
 
 ```yaml
@@ -142,9 +142,9 @@ budgets:
 | 2 | cart-creation | design-decision | cart-total rounding | round half-up | PO (interactive) |
 | 2 | cart-creation | substrate-expansion | needs packages/shared/http.ts | approved → shared_substrate | PO (interactive) |
 ```
-**Promotion timing:** a row is appended the INSTANT `advisor-protocol` resolves an ESCALATE —
+**Promotion timing:** a row is appended the INSTANT the PO answers —
 never batched to round close. This is the file `task-executor`'s isolated briefs read back
-(zero-memory handoff, DD-8): an answer given once in round 2 must still be known in round 5's
+(the zero-memory handoff): an answer given once in round 2 must still be known in round 5's
 fresh-context attempt without replaying any chat history.
 
 ---
@@ -156,16 +156,16 @@ FAIL-loop, and QA reconcile; worthless after ship. At SHIP the tech-lead **harve
 the durable-mineable *signals* out of it into one append-only row:
 
 ```
-shapeup/metrics/<machine-id>.jsonl   # one row = one e2e run; COMMITTED (tracked)
+.shapeup/metrics/<machine-id>.jsonl   # one row = one e2e run; LOCAL (gitignored)
 ```
 
-Path note: the per-slug local run dirs `.shapeup/[slug]/` are gitignored wholesale
-(`.shapeup/`), but `metrics/` lives under the **shared** workspace
-`shapeup/` and stays **tracked** — it is the committed report surface, the
-durable signal feed that survives the gitignored run-trace. Sharded per machine (addendum
-Δ3) so concurrent runs append without merge-conflicting on one file; an aggregate view is
-`cat shapeup/metrics/*.jsonl`. `schema_version` makes a v2.1 row readable by later
-skill versions.
+Path note: `metrics/` lives under the LOCAL root with the rest of the run trace — moved
+there by ADR-0001, because a committed shard keyed on `$HOSTNAME` only grows and puts a
+person's machine name in the repo. It outlives any single run (the per-slug run dirs are
+superseded run by run; the shard only appends), which is what makes it the durable signal
+feed. Sharded per machine so shards can be pooled deliberately without colliding on one
+filename; the read plane is `stats.mjs`, or `cat .shapeup/metrics/*.jsonl`.
+`schema_version` makes an old row readable by later skill versions.
 
 ### Two hard rules (same discipline as the Test Surface: *derived, never invented*)
 1. **Harvest only fields that already exist as structured output at ship time.** If a
@@ -175,9 +175,8 @@ skill versions.
    single-judge rule and invites Goodhart. The eval suite *interprets* downstream;
    harvest *records*.
 
-Scope: the harvest feeds **only tier-3 (e2e pipeline benchmark)**. Tier-1
-(trigger-evals) and tier-2 (per-skill functional, golden fixtures) run on isolated
-fixtures and do not consume it.
+Scope: the harvest feeds **only the e2e pipeline measurement**. The per-skill functional
+fixtures run in isolation and do not consume it.
 
 ### Row schema (one JSON object per line)
 | Field | Existing source (copied, never re-graded) | Signal |
@@ -192,7 +191,7 @@ fixtures and do not consume it.
 | `scope_cut_count` | `~` items cut at SHIP S.0 | appetite pressure / scope hammer |
 | `qa_findings` | `.shapeup/<slug>/qa/hunt-report.md` + triage → `{total, promoted, held}` | edge quality |
 | `slice_count` | breadboard B5 (≤9) | **normalizer / denominator** |
-| `sources` | path to each **SHARED** source artifact — never a LOCAL `.shapeup/` path (this row is committed; the run-trace is gitignored/wiped, so a LOCAL path dangles on every clone — tier-direction rule) | auditability |
+| `sources` | path to each **SHARED** source artifact — never a LOCAL `.shapeup/` path (the run-trace is superseded run by run, so a LOCAL path dangles by the time anyone reads the row; SHARED paths resolve on any clone — tier-direction rule) | auditability |
 
 - `slice_count` is the **denominator**: `round_count=4` on a 2-slice feature is alarming,
   on a 9-slice feature is normal. Without it, e2e comparisons are apples-to-oranges.