shapeup-sdlc 3.18.2 → 4.0.0

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

@@ -1,605 +0,0 @@
-# Tech-Lead Gate Playbooks
-
-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 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.
-
-**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/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.
-
----
-
-## GATE L0 — Intake & Run Config
-
-**Purpose:** Pin everything the run needs once, up front, so the loop never has to guess.
-
-```
-Collect (explicit — never inferred):
-  L0.1  Kicked-off pitch source: `shaping.md` — and its `breadboard.md`, which the run finds
-          beside it (or in `shaping/`) or takes from `--breadboard`; a `pitch.md` may carry the
-          breadboard inline. Already shaped + bet by PO.
-          Not a raw idea — shaping (1-4) / betting (5) / kick-off (6) are PO-personal, upstream.
-  L0.1a Language gate, BEFORE init run: Agent (model: exec) → Skill(shapeup-sdlc-plugin:translator)
-          --check over the pitch AND its breadboard.
-          English      → use both as-is.
-          non-English  → Agent (model: exec) → Skill(shapeup-sdlc-plugin:translator) <pitch> <breadboard>
-                         (--auto under auto/unattended), then open the run on the produced
-                         <name>.en.md — init run prefers a breadboard.en.md beside it, and warns
-                         when it can find only the untranslated breadboard. The run's intake is
-                         what every planning worker reads, so a translation made after the run
-                         opened reaches nobody: re-open with --force naming the .en.md. Log in ledger.
-  L0.1b Appetite: read the `appetite` field from the pitch's YAML frontmatter (set by /shapeup).
-          Surface it in the gate output. Use it to:
-            - Contextualise the scope at L1b (right-size cuts to the budget).
-            - Anchor max_rounds suggestion: 1-week → 2 rounds, 2-week → 3, 6-week → 4.
-          If appetite is missing or "TBD (uncapped)": flag as a risk and note it in the ledger;
-          proceed, but the PO should set scope expectations manually at GATE L1b.
-  L0.2  Workspace roots (both keyed off <slug>, set here and threaded to every worker as args):
-          - SHARED  shapeup/<slug>/  — durable source + deliverable (committed):
-              shaping/ (from /shapeup), spec/ (where ba-pitch-analyzer writes the spec tree:
-              _index, domain-model, usecases/, contracts/, scopes/, scope-summary.md — NOT tasks/)
-          - 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
-          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 `auto` — each EVAL order resolves the set from the spec
-        (spec-conformance + tdd-surface always; integration for .be/.e2e tasks; completeness
-        when a UC has Invariants; test-surface-conformance when one has a Test Surface).
-        Name a set only if the user asks. It must reach `harness init run --dimensions <a,b>`
-        — it is recorded in the ledger's `eval_dimensions:` line and replaces the resolved
-        set, 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
-          --auto                 — sub-skills run unattended (--auto); tech lead still pauses
-                                   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 (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
-        Env knobs read at this layer: SHAPEUP_ORCH_MODEL, SHAPEUP_EXEC_MODEL,
-        SHAPEUP_EVAL_MODEL, SHAPEUP_QA_MODEL, SHAPEUP_ATTEMPT_BUDGET (default 5),
-        SHAPEUP_DIGESTER_MODEL (default "script" — harness probe digest's regex pass; falls
-        back to a Sonnet dispatch only when the digester reports unrecognized log formats).
-        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, 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
-        when the spec folder has scope contracts; a spec with none skips the attempt loop
-        entirely and BUILD behaves exactly as in v0.2.6 (task-executor --next, no T0).
-        no_progress_k (v1.5): the STAGNATION term of the same inner breaker. Default 2 — the
-        number of consecutive non-`kept` trials after which a scope ends early and queues the
-        same GATE H proposal. attempt_budget counts ATTEMPTS and cannot see that the last two
-        produced nothing; this term can, and on a flailing scope it saves three of five
-        attempts. Set per scope (`no_progress_k` on the contract) or per run in the payload.
-  L0.10 knowledge base (read, never obeyed): if `shapeup/knowledge-base/tech-lead.md` exists,
-        read it now. Its **Workflow guidance** may add a question, a check or a warning line to
-        any gate block below and may name the spike to insist on at L1a; its **Suggested run
-        config** lines are PROPOSALS for L0.2–L0.9 and the profile — confirm each with the PO
-        before pinning it, and record `(source: knowledge-base)` beside a value taken from there.
-        Nothing in that file answers a gate: the answer set resolves exactly as it would without
-        it, and a line that could only be honoured by skipping, reordering or relaxing a gate is
-        reported as a suspected harness defect, not applied. If `shapeup/knowledge-base/` has no
-        file at all, offer the optional seed once — `/retro --scan` (the coach's scan operation)
-        drafts guidelines from the project on disk, or `/retro --research <stack>` (its
-        research operation) from the platform's official documentation when the project has no
-        build file to scan; both put every rule through GATE COACH-1 — and continue whether or
-        not the PO takes it. A Suggested run config line with `web-research` provenance has
-        never run in this project: confirm it like any other, and expect the first round build
-        gate to be its first execution.
-```
-
-**L0.9b — the launch record.** Every switch the operator typed to *this launch* becomes a `RunArgs`
-field, or it does nothing at all: the workflow cannot read a config file and cannot ask a follow-up,
-so a flag that stops at the skill boundary was accepted and ignored. That is not hypothetical —
-`--no-qa` was documented in seven places across the shipped set and inert in all of them, because no
-line of this protocol ever put `noQa` into the record. `--wall-clock-budget` is the one flag below
-that is not a `RunArgs` field at all — it is consumed earlier, at `init run` itself, and never
-needed to reach this launch; see its row for where it actually lands.
-
-| Flag | `RunArgs` field |
-|---|---|
-| `--no-eval` | `noEval: true` |
-| `--no-qa` | `noQa: true` |
-| `--parallel-scopes N` | `maxParallelScopes: N` — how many scopes build at once (default 4; `1` = sequential) |
-| `--adversarial-verify` | `adversarialVerify: true` |
-| `--rounds N` / `--attempts N` | `budgets.{maxRounds,attemptBudget}` |
-| `--gate-answers <set>` | `answers` |
-| `--wall-clock-budget S` | *(not a `RunArgs` field)* — typed once, on the `harness init run` command line itself, not on this launch; it lands straight in the run receipt as `wall_clock_budget_s`, and the deadline breaker reads that receipt field directly — consumed by `kernel/verify/budget.mjs` as `wall_clock_budget_s`. `budgets` declares only `maxRounds`/`attemptBudget` — the schema, `SKILL.md`'s own RunArgs contract line and this script's own header comment all agree there is no third member |
-| `--orch-model/--exec-model/--eval-model/--qa-model` | `models.{…}` (L0.8) |
-
-`harness init run-args` (invoked at Step 2 of `SKILL.md`) is the sole writer of the assembled
-object: it takes the resolved values above, writes `.shapeup/<slug>/run-args.json` fresh on every
-launch and relaunch, and prints the same object back so the launch never re-assembles it by hand. It
-is the only artifact that records what a run was configured with; the ship report, a resumed session
-and any later measurement all read it, and none of them can recover a value that only ever existed
-as an argument. Step 2 is not merely advisory: `shapeup-run.js`'s own Preflight refuses to dispatch
-ORIENT (or anything past it) when this file is missing at the run's local root — a launch that
-skipped this step aborts there rather than proceeding on a silent default.
-
-**L0.0 — intake precondition (before any other L0 collection):**
-```
-resolve intake from, in order:
-  1. --pitch <path>            (a shaping/pitch file on disk)
-  2. --spec <folder>           (an existing spec tree)
-  3. <intake> requirement text passed to the skill
-none resolvable  ->  ABORT. Print the ✋ NO INTAKE block from SKILL.md and stop.
-                     Do NOT emit the GATE L0 block. Do NOT list downstream gates.
-                     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. Fail loudly instead.
-
-**GATE L0 Output:**
-```
-⏸ GATE L0 — Intake & Run Config
-Feature      : [slug]   (kicked-off pitch: [path])
-Intake lang  : [English | translated via /translator → <name>.en.md]
-Appetite     : [~1 week | ~2 weeks | ~6 weeks | ⚠️ missing — scope uncapped]
-Spec folder  : [path]   (lens: [lite|standard])
-Eval dims    : [auto | the named set]   max_rounds: [N, appetite-informed]   auto: [interactive|auto|unattended]
-Run commands : [web: ... | api: ... | mobile: ...]   (run_cmd → the round build gate, every round before EVAL)
-Build gate   : build_probe [set | —]   launch_probe [set | — ⚠ mobile: the install/launch risk has no owner]
-Model matrix : orch=[model] exec=[model] eval=[model] qa=[model] digester=[script|sonnet]  (source: [flags|settings.local|settings.json|default])
-Budgets      : round_budget=[N] (outer)   attempt_budget=[N] (inner, per scope)
-Knowledge    : [tech-lead.md — N workflow rules, M suggested values (confirmed above) | none — `/retro --scan` or `/retro --research <stack>` seeds it (optional)]
-```
-**Resolve it** — this gate is this skill's own (the workflow never sees it), so it is this skill
-that runs the same tool every other gate resolves through, not a paragraph read as a stand-in for
-one: `node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" gate --resolve L0 --slug <slug>
-[--file <path>|--preset <name>]`. Exit 4 (`ask`) is the confirmation this block already asks for —
-put it to the PO and wait, same as the paragraph above always meant. Exit 0 (`decision=proceed`) —
-continue straight to ORIENT, which is what `--unattended`'s pre-answered set resolves to. Exit 5
-(`abort`) — stop; do not launch. Either way, the gate's own ledger row is what lets a later reader
-see the decision that opened the run, not only the decisions that closed it.
-
----
-
-## ORIENT (step 7) — delegate to orient (the Scout)
-
-The Shape Up Building phase opens with **Orient, not planning**: the team reads the real code
-and spikes the scary parts *before* any board exists, so the board comes out reality-born.
-
-```
-Invoke via Agent (model: exec — see references/protocol.md "Invocation mechanism"):
-        Skill(shapeup-sdlc-plugin:orient) --pitch <intake> --spec <path> --stack "<hint>" [--auto]
-Owns:   its own GATE O-A/O-B; runs straight through under --auto.
-Writes: .shapeup/<slug>/orient/ → code-surface.md, spike-<area>.md, discovered-seed.md, hill-signal.md.
-Record in ledger: orient duration + the spiked area + spike result (resolved | SPIKE-UNRESOLVED).
-```
-The four artifacts are the **orient → ba contract**: `ba` (step 8) consumes them instead of
-re-scanning the codebase. Pass `--auto` only when the run level is `--auto`/`--unattended`.
-
----
-
-## GATE L1a — Orient Review
-
-**Purpose:** PO sees where the pitch lands in real code and what's still unknown — *before*
-committing to a scope map. This is the first Hill read (area-level — slices don't exist yet).
-
-```
-Read .shapeup/<slug>/orient/. Render the 🗻 Hill from hill-signal.md (see protocol.md "Hill report"):
-  - each suspected area → uphill (open unknowns) | crest (approach proven by the spike) | downhill
-Print: `Breadboard: <source> | none` (how init run found the pitch's breadboard — flag, sibling,
-       shaping-dir, shared-root, embedded — or none), the code-surface headline (where it lands),
-       the spiked area + result, the riskiest open unknowns going into mapping.
-Ask (max 2): is the riskiest area the right one to have spiked? any unknown that must be
-             resolved (another spike) before we map scopes?
-```
-Do NOT enter MAP SCOPES until Orient is accepted.
-
----
-
-## WIRE (step 7.5) + traceability spine ✚ — delegate to solution-architect
-
-**Active only when the spine is in use** — on a legacy spec skip it; `trace-lint` self-skips every arm whose artifact is absent (non-regression).
-
-```
-1. PROFILE (you write it at L0 — compile-order stays pipeline-blind): SHARED project-profile.md
-   = {schema_version:1, archetype, entry_point, source_extensions?, build_probe?, launch_probe?}.
-   archetype ∈ {client-only-game|web-service|mobile|library|data-pipeline}; entry_point is the
-   reachability seam (a game's main.js is NOT a service's src/server.ts). Validate the enum — a
-   typo must fail, not silently disable the check. entry_point is also the root reachability walks
-   the import graph from, so where some module does compose the app, name that one rather than the
-   file the platform happens to start. Where the screens are registered in a MANIFEST instead (a
-   route map, a plugin table, a string-loaded page), no entry point roots an import walk at all —
-   measured on a real ArkTS app, where the navigation host imports nothing and every screen arrives
-   through route_map.json. The arm then reports that it could not check, and that is the correct
-   end state for such a project rather than a profile to keep re-declaring.
-   source_extensions is optional and only needed when the project's modules end in something the
-   entry point does not (e.g. [".ets"] when the entry is a .ts file); leaving it out costs a
-   skipped arm, never a false red. The two probes feed the round build gate (`harness verify
-   build`, every round before EVAL): build_probe asserts 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); launch_probe installs, starts and asserts the first screen. A `mobile`
-   profile without a launch_probe is warned about every round — nothing else in the loop launches
-   the app.
-2. WIRE — compile-order --operation wire --slug <slug> (worker→solution-architect), payload
-   {project_profile, breadboard?}. 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.
-   ⟐ 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}/kernel/harness.mjs" probe resume
-   --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}/kernel/harness.mjs" verify trace --slug <slug>. ADVISORY at L1b:
-   covers-closure (every covered REQ named by ≥1 AC's covers:) + reachability (every UC engine
-   reaches entry_point). Promote to --gate only once covers: is populated. Reachability reports
-   checked:false with a reason rather than a verdict in two cases, both warns: an import it could
-   not follow (the graph is incomplete) and no engine reachable at all (nothing controls the walk,
-   so an orphan and a wrong root look identical). Read either as "re-declare the profile", never
-   as a clean arm. When it does run it also reports, per scope, how many of that scope's own source
-   files the app reaches, and warns (SCOPE-UNREACHABLE) on a scope it reaches none of — a scope's
-   build fixture can be green while its code never compiles, on any toolchain that compiles only
-   what the entry point reaches. Warn only: the wiring may be a later scope's job by design.
-```
-
----
-
-## 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/protocol.md):
-1. ANALYZE + BOARD — compile-order --operation analyze --slug <slug> --worker ba-pitch-analyzer
-     --payload '{"pitch": "<path>", "breadboard": "<the path init run printed, when it printed one>", "lens": "<lens>", "orient_dir": ".shapeup/<slug>/orient/"}'
-   dispatch: Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>. The order hands it
-   code-surface.md (Phase-1 ingest consumes the map, does not re-scan), discovered-seed.md
-   (task gen starts from reality), spike-<area>.md (feasibility/contracts).
-   Output expected: spec_folder populated with _index, domain-model, usecases/, contracts/,
-   scope-summary.md (all SHARED/committed) + tasks/TASK-NNN*.md, tasks/_index.md (board)
-   written to the LOCAL root .shapeup/<slug>/tasks/ (v3.2) + a WorkResult → ingest.
-2. MAP SCOPES — compile-order --operation map-scopes --slug <slug> --worker scope-architect
-   dispatch: Skill(shapeup-sdlc-plugin:scope-architect) --order <path>. Sole writer of the
-   committed scopes/<scope-id>.md contracts (import-graph slicing, substrate whitelists,
-   affordance manifest, fixtures, PA1/PA2 — mechanically linted by harness verify spec).
-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, not
-"pure Shape Up". State it; don't pretend otherwise.
-
----
-
-## GATE L1b — Board Review (Plan Acceptance)
-
-**Purpose:** PO sees the shape of the work before a single line of code. This is where scope
-is cut or confirmed — cheap here, expensive later.
-
-**v3.2 (local-tasks-architecture):** on a spec with
-scope contracts, the PO reviews the SHARED, committed plan — `usecases/_index.md` +
-`scopes/*.md` + `scope-summary.md`'s Done-when headlines — never the LOCAL task board
-(`tasks/_index.md`, gitignored, per-machine run-trace). Implementation-level task detail stays
-hidden at this gate by design; the PO signs off on the UCs covered and how they're cut into
-scopes, not a line-by-line task list. A pre-v0.3.0 spec (no scope contracts) has no scope
-board to substitute for — this gate still reads `tasks/_index.md` directly, unchanged from
-v0.2.6 (non-regression).
-
-**Bootstrap check (local tasks board) — run BEFORE the read below, always:**
-```
-`.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.
-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
-any machine that already has one — this only fires for the second-developer / resumed-run case.
-```
-
-```
-Scope contracts present:
-  Read usecases/_index.md + scopes/*.md (scope-board.md) + scope-summary.md. Print:
-    - UC count + actors (usecases/_index.md)
-    - scope board: scope_id, topology_type, substrate file count (scopes/*.md / scope-board.md)
-    - any SPIKE blockers (scope-summary.md)
-    - scope-summary "Done when" headline statements
-    - the Deferred Places from ux-behavior.md (breadboard Places this shape will not build) —
-      each one needs the PO's yes; a rejected deferral goes back to the planner as a screen
-    - the REQ → AC table from requirements.md, one row per registered requirement: REQ-id, the
-      source clause it came from (`REQ-12 ← shaping.md R12`), and the acceptance criterion that
-      grades it — or the scope that claims it, or CUT (PO-approved). Omitted entirely when the run
-      has no registry. A requirement with none of the three is already a red below; this table is
-      what the PO reads to answer it — cover it, or cut it on the record. Printed, never asked:
-      the table decides nothing at this gate
-No scope contracts (pre-v0.3.0, unchanged from v0.2.6):
-  Read tasks/_index.md (LOCAL root). Print:
-    - task count by package/variant (.shared / .be / .web / .mobile / .e2e)
-    - layer distribution (Layer 1→6) and the critical dependency path
-    - any SPIKE tasks (third-party feasibility) that block others
-    - scope-summary "Done when" headline statements
-
-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}/kernel/harness.mjs" verify spec --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), SCOPE-ANCHOR (a scope
-    naming no committed use case, or one that does not resolve), TIER-DIRECTION (a committed
-    contract naming LOCAL task ids), SCOPE-DEPS (a build-order id naming a scope that is not
-    in this run), REQ-UNCOVERED (a requirement in requirements.md that no acceptance criterion
-    grades and no scope claims — the PO's two ways out are an AC carrying `(covers: REQ-…)` or
-    `CUT (PO-approved)` in the registry; silent on a run with no registry),
-    CONTRACT-SCHEMA (a scope contract that parses but not into the shape a WorkOrder carries —
-    most often a list written bare in a table cell where the dialect wants `[a, b]`; without
-    this the compiler refuses the order later and the scope is never dispatched at all, with
-    the board green and the leg reporting done), CONTRACT-UNREADABLE (a table the parser could
-    not see, or a table field also declared in frontmatter where nothing reads it),
-    BREADBOARD-PLACE (a breadboard Place with UI affordances has no
-    `## Screen: … (P#)` in ux-behavior.md and is not deferred), BREADBOARD-UI (a U# not
-    specified on a screen of its own Place). Any red → HARD STOP, past a 🔴 at the
-    architect's own checkpoint. The breadboard reds are the planner's to fix — add the screen
-    or defer the Place; never fold it into another screen.
-  - 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
-    alphabetical — Shape Up's "solve in the right sequence" (step 10).
-    DEPENDENCIES CONSTRAIN THAT ORDER, and each contract declares its own: scope A follows scope
-    B when A names B in `depends_on`. The order lives in the same committed tier as the contracts
-    it orders, so it survives a clone. Risk orders the scopes; the dependencies decide when each one is
-    RELEASED — a scope starts as soon as the scopes it consumes have settled, not when its whole
-    level has, so a scope may well start while a sibling is still building. A scope that consumes
-    the others' output (an entry point wiring up command modules) therefore cannot be scheduled
-    alongside them however low its unknowns count. It fails open: a contract declaring no
-    `depends_on`, or naming a scope that is not in this run, falls back to releasing a level at a
-    time, and then to no constraint at all (spec-lint SCOPE-DEPS reports the dangling id).
-
-Ask (max 2): scope cuts? lens correct? any SPIKE to resolve before build?
-  Scope-hammer framing: reference the appetite from the pitch
-  (e.g. "Given a ~1-week appetite, which of these scopes feels right-sized?").
-  Also surface any rabbit holes identified in the pitch — they flag where scope
-  may expand unexpectedly if not cut now. A scope cut here is cheap; after
-  BUILD round 1 it's expensive.
-```
-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
-Build gate: [green | red — <failing step> | undeclared]
-```
-
-The build gate is `harness verify build --slug <slug> --round <r>` — the ledger's `run_cmd`, then
-the profile's `build_probe` and `launch_probe`, stopping at the first failure. It runs before this
-gate so the block shows it; `red` means EVAL is NOT dispatched this round (the judge grades a running
-feature) and the failing step is compiled into round r+1's orders as `payload.bugs`. `undeclared`
-means L0 pinned no run command and the profile names no probe — the round proceeds over an
-unproven build, and the block says so.
-
-Under `--interactive` / `--auto`, the gate block carries the board facts — `green_scopes`, `hammer_proposals` — and requires explicit PO approval to proceed. Under `--unattended` the answer set resolves it. **There is no hook behind this gate**: the `PreToolUse` warning it used to carry was retired into the block in v2.0, so what an unfinished board costs you here is a human reading the numbers, not a machine refusing the call.
-
----
-
-## 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, never authored). No contracts →
-  fall back to the board + open-unknowns heuristic (uphill/crest/downhill/done). See
-  references/protocol.md "Hill report". Roadmap rule unchanged either way: progress is
-  reported by hill position, never by "N/M tasks done".
-
-Read EVAL-FEATURE-<slug>.md verdict.
-
-PASS:
-  → first PASS of the run AND not --no-qa:
-      delegate ▶ QA EDGE HUNT → Agent (model: qa — see references/protocol.md
-      "Invocation mechanism"): Skill(shapeup-sdlc-plugin:qa-edge-hunter) (pure worker; see
-      round-protocol "QA edge hunt"). Args: spec folder, EVAL report path, ledger path, app URL.
-      Its GATE Q0/Q1 pauses surface here. Output: `~` findings → .shapeup/<slug>/discovery/ledger.md
-      + .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):
-  → --no-qa or skill absent: proceed straight to SHIP; ledger records `qa: skipped`.
-
-FAIL:
-  → a round whose build gate was red never reached the judge: the block carries `build_gate: red`,
-    the "bug list" is the gate's failing step (its command, exit and output tail), and round r+1
-    is a fix round over exactly that. Nothing the evaluator would have said is missing — it was
-    never asked.
-  → print the bug list grouped by task/severity. For each bug: task ID + failed Done-when criterion + repro.
-    DO NOT prescribe fix options or root cause hypotheses — that is the implementer's job.
-    The tech lead names scope; the implementer diagnoses and fixes.
-  → ask (max 1): approve fixing these in BUILD round r+1? (or cut scope / waive a bug)
-  → if r+1 > max_rounds: STOP. Escalate to PO with the residual bug list — do not loop
-    forever. The harness reports honestly that it hit its round budget.
-  → else: go to BUILD round r+1 (bug-only).
-```
-
-**GATE L3 Output:**
-```
-⏸ GATE L3 — Verdict (round [r])
-🗻 Hill    : S1-spine 🔽 downhill · S2-filters ⛰️ crest · S3-export 🔼 uphill
-Verdict   : [PASS | FAIL]   bugs: [N]   (rounds used: [r]/[max])
-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, report at task-group level and note the fallback in the ledger.
-
----
-
-## SHIP (step 11) — close out
-
-```
-S.0  GATE H — delegate to scope-hammer (this IS Shape Up's "Decide When to Stop", step 11):
-     Invoke via Agent (model: exec — see references/protocol.md "Invocation mechanism"):
-       Skill(shapeup-sdlc-plugin:scope-hammer) --slug <slug> --baseline <shaping/baseline.md if present>
-             [--breaker outer]   when round_budget hit 0 with scopes still open
-             [--breaker inner --scope <id>]   once per queued hammer proposal (attempt_budget
-                                              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,
-               the hammer-proposal queue from BUILD (attempt-budget exhaustions).
-     Ownership facts in its census — "no scope owns X", "X belongs to scope Y" — come from
-       node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe owner --slug <slug> [--path <p>]...
-       which elects the owner from the committed contracts' substrates, never from prose.
-     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.
-       - Cut list confirmed → all cuts carried to discovery/ledger.md as raw ideas (debt-free).
-       - Verdict = CANNOT SHIP (a must-have item failed H1.2) → do NOT proceed to S.1; escalate
-         to PO honestly with scope-hammer's ship-blocking list, same spirit as a max-rounds
-         escalation.
-     Pre-v0.3.0 spec (no scope contracts) → scope-hammer still runs; H0's only census sources
-       are QA + discovery ledger (no scope/attempt-budget inputs), equivalent to the old inline
-       triage this step used to do.
-S.1  Confirm board green + latest eval verdict = PASS.
-S.1b Checklist-hygiene assert: `grep -c "^- \[ \]" .shapeup/<slug>/tasks/TASK-*.md` →
-     every count must be 0 on a shipping board. An unchecked AC box on a done task means
-     either an unverified criterion (real gap — back to BUILD/EVAL) or an ingest miss (the
-     WorkResult's ac_results never covered it — re-run ingest-result on that result, or route
-     back to the owning worker for a corrected result; the tech lead does not tick boxes
-     itself). Do not SHIP past a non-zero count without logging the reason in the ledger.
-S.2  Print a feature summary: tasks shipped, rounds used, final verdict, dims evaluated
-     (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 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'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 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`
-     (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
-     `harness probe stats`, or `cat .shapeup/metrics/*.jsonl`).
-     Copy fields that ALREADY exist as structured output (run-state, final EVAL report,
-     discovery ledger, qa/hunt-report, and the receipt's `breadboard.ids.V` for `slice_count` —
-     the slices init run counted in the staged breadboard, never a hand copy). 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 two run-quality measurements, both produced by scripts at zero model tokens:
-       node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe stats --ratchet --slug <slug>
-         → `ratchet`: {trials, scopes_multi_trial, improvement_rate, monotone_rate,
-                       sawtooth_count, mean_trials_to_green}
-       node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe stats --hooks
-         → `hooks`: {evaluations, denials, errors, per_hook}
-     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.
-     ALSO copy `run_id` from `receipt.json`. It is the row's only link to the run trace
-     that produced it: every other field here is a count, and `feature_slug` groups runs
-     TOGETHER rather than apart. It is what joins this row to the S.7 export.
-     → full field list + row template: references/protocol.md "Harvest row".
-S.7  Export the run's records → one keyed dataset, before the trace is superseded.
-       node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" report export --slug <slug>
-     Same argument as S.6, applied to the records the harvest row does NOT carry: orders,
-     results, T0 verdicts, trial rows, criterion verdicts and this run's hook decisions all
-     live in the LOCAL tier, which is regenerable and gets wiped.
-     The export freezes them as fact tables under `.shapeup/exports/<run_id>/` (JSONL, one
-     object per line), keyed by run id so a second run of the same feature is a second
-     dataset rather than an overwrite. `--out <dir>` sends it somewhere durable instead.
-     It is READ-ONLY: it writes nothing into the trace, so it may be re-run at any time.
-     NOT COST/WALL-CLOCK. This harness carries no run-economics record — the design once
-     called for one derived from a per-agent-call journal, but nothing in the pipeline ever
-     wrote that journal, so the derivation and its reporting command were removed rather than
-     left presenting nulls as measurements. Even a real cost record would not belong in the
-     harvest row's schema either way — that row's contract rejects clock fields on purpose
-     (see protocol.md "Rejected fields"), because a signal feed that carried a duration would
-     become a velocity feed on the next person who read it.
-```
-
----
-
-## GATE L4 — Ship Sign-Off
-
-```
-⏸ GATE L4 — Ship Sign-Off
-Feature   : [slug] — [SHIPPED (deployed) | BUILT & VERIFIED — deploy pending (PO)]
-Rounds    : [r] (build+eval cycles)
-Verdict   : PASS (dims: [dims_evaluated]; not evaluated: [dims_not_evaluated])
-QA        : [hunt done — N findings, M promoted+fixed, rest ~ | skipped (--no-qa) | n/a (pre-QA spec)]
-Requirements: [15/17 PASS · 1 CUT (PO) · 1 no evidence (REQ-12 ← R12) | n/a (no registry)]
-Ledger    : harness-run.md
-```
-The Requirements line is TRANSCRIBED, never composed — run
-`node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe requirements --slug <slug> --format table`
-and copy its `Requirements:` summary. It joins each registered clause to the acceptance criterion
-that covers it and to the criterion the judge graded, over the run named in its own output. It
-decides nothing here: a requirement with no PASS evidence is a fact GATE H's census and the
-baseline comparison weigh, not a ship blocker.
-Question (max 1): "Anything to record before I close the run? (y/n) or provide feedback for the next sprint."
-On confirm:
-- If the PO provides substantive feedback (not just 'y' or empty) → automatically delegate via Agent (model: exec — see references/protocol.md "Invocation mechanism"): Skill(shapeup-sdlc-plugin:coach) with the provided feedback for RLHF. The coach runs its own GATE COACH-1 to have the PO categorize each rule, then files it under the responsible skill in `shapeup/knowledge-base/<skill>.md` (committed → team-shared). Coachable: `task-executor`, `ba-pitch-analyzer`, `qa-edge-hunter`, `orient`, `scope-architect`, `solution-architect` (each reads its own file at the top of its next run) and `tech-lead` (workflow guidance, read at the next GATE L0). Guidance never decides a gate: a filed rule may add a question or a check to a gate block, never an answer. The tech lead does not categorize the feedback itself — that is the coach's gate, by design (no assumptions).
-- Then output → `✅ [slug] [shipped & deployed | built & verified, deploy pending] — [r] rounds, verdict PASS.`
-
-**A launched run already crossed L4 — never resolve it again after a `shipped` or `escalated`
-return; a second row after the close is a second sign-off.** In the prose lane, **resolve the gate
-itself before any of the above** — this is the decision that shipped the run,
-and without it the trace holds no record of that decision at all: `node
-"${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" gate --resolve L4 --slug <slug>
-[--file <path>|--preset <name>]`. Exit 0 (`decision=ship|hold`) — render the block above and close
-the run: `node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe resume --slug <slug> --close shipped
---cause "verdict=<verdict> rounds=<r> decision=<ship|hold>"`. **This applies to the prose lane
-only.** A launched run (`shapeup-run.js`) resolves L4 itself, on both the PASS path and a breaker
-path: it dispatches the census, crosses GATE H, writes the ship report with the verdict as it is,
-crosses L4, and only then closes — `shipped` when the census and L4 clear it, `escalated` naming
-the census when they do not. A run that returned `{status: "shipped"}` or `{status: "gate_h"}` is
-already closed; do not close it again, and do not run the census by hand after it.
-The close itself is a once-only fact IN THE KERNEL (`closeRun`'s own guard reads a `closed_status:`
-line that only `closeRun` ever writes — never the mutable `status:` line every phase rewrites, this
-call included), not a conditional this instruction has to get right: if this run_id was NOT already
-closed, this call performs the close, fresh. If it was already closed `shipped` (or `aborted`) and
-the cause text is byte-identical to what is already on the ledger, this call is a true idempotent
-no-op. If it was already closed with the SAME status but a genuinely different cause — a run closed
-more than once across relaunches, the ordinary shape a `gate_h` hand-off after an earlier abort takes
-— this call SUPERSEDES it: the new cause is written, the prior one is folded into the same
-`close_cause` line rather than lost, and the kernel call itself still exits 0 (only the RunReturn a
-launch's own `withWarnings` wraps carries the resulting `state_warning` — a prose-driven close like
-this one has no RunReturn to attach it to, so read `close_cause` by hand if this branch matters to
-you). If it was already closed with a DIFFERENT status altogether, this call is refused outright —
-cause intact, never silently flipped. Exit 4 (`ask`) — the block above IS that stop; put it to the
-PO and wait, same as always. L4's answer set carries no `abort`.
-
----
-