shapeup-sdlc 3.18.3 → 4.0.0

package/README.md

@@ -10,9 +10,8 @@ Your agent says it's done. It isn't. This is a [Claude Code](https://code.claude
 that runs a full Shape Up lifecycle — idea → pitch → build → evaluate → ship — where the
 important rules are enforced by the runtime instead of asked for in a prompt.
 
-The ceremony is right-sized: `/ship` runs the full gated pipeline for real features, and
-`/ship --tiny` runs a two-gate lane (orient → build → smoke-test → done) for the one-file
-fixes where the gates would have nothing to say.
+The ceremony is sized by the pitch's appetite: `/ship` runs the full gated loop, and a small
+pitch is a one-scope run with a short round budget — the gates and the verification floor are the same.
 
 <p align="center">
   <img src="docs/assets/demo-gate.svg" alt="Terminal recording: a worker tries to edit a file outside the scope it was given, a PreToolUse hook denies the write and names the path, and the next edit inside the scope is permitted." width="700">
@@ -33,17 +32,16 @@ prompt-based harness:
 **1. A worker cannot act on an order nobody compiled.** Every dispatch carries a schema-validated
 WorkOrder, and a `PreToolUse` hook hard-denies the call when that order is missing or malformed —
 the tool call never reaches the worker. The same layer denies any write the order's own substrate
-does not permit, and blocks a session that dispatched the orchestrator and left no run receipt.
+does not permit. A run that left no receipt did not happen.
 → *Prevents: an agent inventing its own brief, then reporting against it.*
 
-(GATE L2, the board-green check before evaluation, is advisory: it warns when a round's evaluation
+(The Round Close gate, the board-green check before evaluation, is advisory: it warns when a round's evaluation
 runs over unfinished tasks rather than denying it. The board is local to the machine running the
-harness — see [ADR-0001](docs/design/adr/0001-consumer-file-organization.md).)
+harness.)
 
-**2. Progress is measured, not claimed.** A scope counts as built only when `t0-verify` runs
+**2. Progress is measured, not claimed.** A scope counts as built only when `verify t0` runs
 its fixtures and its DB probe and writes an artifact to disk — with each command's exit code,
-its captured output, and whether it ran at all. The evaluator must cite that artifact, and the
-hill phase is derived from artifacts rather than from a worker's own account of its progress.
+its captured output, and whether it ran at all. The evaluator must cite that artifact, and a worker's own account of its progress counts for nothing.
 Two limits, stated here because the point of this section is that a claim without a mechanism
 behind it is the thing this harness exists to prevent: a citation is re-hashed from disk, checked
 against the scope, round and run the artifact records, and refused unless it names a file this
@@ -57,7 +55,7 @@ told from a regression. That block measures and judges nothing.
 → *Prevents: "done" asserted with nothing behind it.*
 
 **3. Parallel work can't corrupt shared state.** Each scope gets a write-whitelist of files
-enforced by a hook, and one script performs every board/ledger/verdict write.
+enforced by a hook, and the loop alone applies every board and ledger change.
 → *Prevents: two parallel executors both rewriting the board, and one's completions vanishing.*
 
 Under the hood this rests on a typed worker envelope and a single-writer state layer. Those
@@ -92,18 +90,10 @@ quickstart.
 > npx shapeup-sdlc init -d . -y
 > ```
 >
-> **And lift the print-mode background ceiling, or the run is killed at ten minutes.** `claude -p`
-> terminates a session's background tasks after 600 s by default, and the whole pipeline runs as
-> one background launch — so an unattended run dies mid-BUILD with the CLI reporting nothing worse
-> than "background tasks still running after 600s; terminating". Measured, on a run that had
-> reached WIRE:
 >
-> ```bash
-> CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0 claude -p "/shapeup-sdlc-plugin:ship …" …
-> ```
->
-> Nothing is lost when it happens — resume state is on disk, so relaunching fast-forwards past the
-> phases that finished. It costs a relaunch, not a run.
+> The loop runs in your own session, in the foreground, so print mode's background-task ceiling does
+> not apply to it. A killed session loses nothing: `/ship` again over the open run reads the artifacts on
+> disk and carries on from the first step that is not done.
 
 Want to see a full run before installing anything? **[docs/quickstart.md](docs/quickstart.md)**
 walks one small feature end to end — including what the hooks do to a premature eval, a FAIL round
@@ -117,9 +107,9 @@ installer, and troubleshooting are in
 ## Agent support
 
 The harness targets **Claude Code only**. The reason is the row that never travelled when we
-compiled to other CLIs: hooks. The 13 skills, 11 slash commands and the kernel are
-portable prose and plain Node — but hook-enforced gates (envelope validation, substrate
-sandbox, safety spine, the zero-work block) are a per-CLI mechanism, and without them every gate degrades from
+compiled to other CLIs: hooks. The 6 skills, 10 slash commands and the kernel are
+portable prose and plain Node — but hook-enforced gates (envelope validation, the substrate
+fence, the safety spine, dispatch receipts) are a per-CLI mechanism, and without them every gate degrades from
 **enforced** to **instructed** — the same honor system every other framework runs on
 everywhere. If the deny hooks are why you're here, that means Claude Code.
 
@@ -130,16 +120,15 @@ rest of this README after this table and nothing will be a surprise.
 
 | Term | In plain English |
 |---|---|
-| **board** | The round's task list. "Green" means every task is done. GATE L2's hook reads this before an evaluation and warns if it is not green. |
+| **board** | The round's task list. "Green" means every task is done. The Round Close gate reads this before an evaluation and warns if it is not green. |
 | **round** | One build → evaluate cycle. A FAIL verdict starts round *r+1*. |
 | **T0** | The smoke test a scope must pass before it counts as built: its fixtures and a DB probe. Writes an artifact to disk that the evaluator must cite. |
 | **substrate** | The exact list of files one dispatch is allowed to write, stamped into its work order. A hook blocks anything outside it — and anything the order marks frozen. |
 | **scope contract** | The file defining one vertical slice: its substrate, its fixtures, its affordances. |
 | **affordance** | The thing a user can actually click, type or call. UI is graded on affordances, not on looks. |
-| **hill / hill phase** | How much of a scope is still *unknown* versus merely *unfinished*. Derived from T0 facts — never self-reported. |
-| **gate (L0–L4)** | A numbered checkpoint in a run. Most pause for you; GATE L2 is the one a hook observes and reports on. |
-| **covers-closure** | Every requirement clause has at least one task claiming to cover it. Nothing silently drops. |
-| **wiring reachability** | Every engine has a call site reachable from the app's real entry point. Catches "built, but never wired up". Reports itself unchecked, with a reason, when the import walk cannot be rooted — an unfollowable import, or no reachable engine to control it. |
+| **hill / hill phase** | How much of a scope is still *unknown* versus merely *unfinished*. The Scout reports a signal at orient; nothing later derives it. |
+| **gate** | A checkpoint in a run, called by its plain name: Intake & Config, Orient Review, Wiring Review, Board Review, Round Close, Verdict, QA Edge Hunt, Cut-List Review, Ship Sign-off and Retro Ownership. [`AGENTS.md`'s Gate names](AGENTS.md#gate-names) says what each one checks. Most pause for you; the Round Close gate is advisory: it can be crossed over unfinished work, recorded as a flagged `warn`. |
+| **covers-closure** | Every requirement clause is graded by at least one acceptance criterion or claimed by a scope, or the PO marks it `CUT`. The loop reads the plan back for this before the board review; nothing silently drops. |
 | **discovery ledger** | The one file everything found mid-run gets written to, so nothing is lost between rounds. |
 
 A longer version, including the internals, is in [docs/glossary.md](docs/glossary.md).
@@ -153,41 +142,36 @@ document as a whole starts at [`docs/design/`](docs/design/README.md). This diag
 full phase and gate mechanism — simpler than that per-attempt detail, but the whole pipeline:
 
 <p align="center">
-  <img src="docs/assets/workflow-mechanism.svg" alt="The shapeup-sdlc harness pipeline from raw idea to Coach Retro: Shaping produces a Pitch, the Betting Table bets into the tech-lead-orchestrated run or rejects back to raw idea, Kick-off through Ship Sign-off cross gates L0, L1a, L1a.5, L1b, advisory L2, L3, GATE H and L4, the Build/Evaluate round loops on FAIL, and a circuit breaker routes straight to GATE H — bypassing QA — when the round or wall-clock budget runs out." width="900">
+  <img src="docs/assets/workflow-mechanism.svg" alt="The shapeup-sdlc harness pipeline from raw idea to Retro: Shaping produces a Pitch, the Betting Table bets into the loop-driven run or rejects back to raw idea, Kick-off through Ship Sign-off cross gates Intake & Config, Orient Review, Wiring Review, Board Review, the advisory Round Close, Verdict, Cut-List Review and Ship Sign-off, the Build/Evaluate round loops on FAIL, and a circuit breaker routes straight to Cut-List Review — bypassing QA — when the round budget runs out." width="900">
 </p>
 
 <p align="center"><sub>
 Plan-phase skills in blue, build-phase in green, QA-phase in pink; amber pills are gates —
-the outlined <b>L2</b> is advisory, the rest block. The dashed region marks what
-<code>/tech-lead</code> orchestrates end to end.
+the outlined <b>Round Close</b> gate is advisory, the rest block. The dashed region marks what
+<code>/ship</code> drives end to end.
 </sub></p>
 
-Since v1.3 the pipeline carries a **traceability spine**: `ba-pitch-analyzer`'s `coverage`
-operation writes a requirement registry (`requirements.md`), `solution-architect` commits a
-per-use-case wiring map (`wiring-map.md`, gate L1a.5) resolved against the L0
-`project-profile.md`, and the covers-closure + reachability oracle
-`kernel/verify/trace.mjs` checks that no engine ships orphaned. It runs
-advisory (warn-only) and is promoted to a blocking gate only once `covers:` is populated;
-every arm is skipped when its artifact is absent, so older specs are unaffected.
+Since v1.3 the pipeline carries a **traceability spine**: the plan activity's requirements
+substep writes a requirement registry (`requirements.md`), its wire substep commits a
+per-use-case wiring map (`wiring-map.md`, the Wiring Review gate) resolved against the Intake & Config `project-profile.md`, and the loop reads the plan back at the board review for a
+registered requirement that no acceptance criterion grades. It is advisory until `covers:` is
+populated; every arm is skipped when its artifact is absent, so older specs are unaffected.
 
 ## What's included
 
 ### Skills
 
-| Phase | Skill | Version | What it does |
-|-------|-------|---------|--------------|
-| Shaping (1–4) | `shapeup` | — | Frame the problem, breadboard affordances, spike risks, write the pitch. Sub-commands: `full`, `shaping`, `spike`, `breadboarding`, `framing-doc`, `kickoff-doc`, `breadboard-reflection`. |
-| Intake (GATE L0) | `translator` | — | Normalizes non-English intake (pitch/PRD/transcript) to faithful English before planning. The harness is English-only downstream. |
-| Orient (7) | `orient` | — | Builder-led recon: reads the code, spikes the single riskiest area, emits a code-surface map, spike findings, discovered-task seed, and a hill signal. Writes no production code. |
-| Wire (GATE L1a.5) | `solution-architect` | v1.1 | Sole writer of the committed wiring map (`wiring-map.md`): per-UC engine → integration seam → entry-point call site → player-visible affordance, resolved against `project-profile.md`. Front-loads the integration seam so no engine ships orphaned; the reachability input `harness verify trace` checks. Operation: wire. |
-| Map Scopes (8) | `ba-pitch-analyzer` | v4.0 | The spec-analyzer (pure worker). Decomposes a pitch into a linked DDD document tree (domain model → use cases → tasks) with BDD scenarios, a UC system flow, and a derived `## Test Surface`. One craft, four order-selected operations (analyze / reconcile / retrofit-surface / coverage — the last writes the shared `requirements.md` registry for covers-closure); graph math + audits delegated to `harness reduce board`/`harness verify spec`. |
-| Map Scopes (8) | `scope-architect` | v1.0 | Sole writer of committed, write-whitelisted scope contracts (`scopes/*.md`): import-graph slicing by flow, substrates, affordance manifests, fixtures. Operation: map-scopes. |
-| Build (9) | `task-executor` | v2.0 | Pure worker: work order in → code out. Assumption scan, minimum-code/surgical-change discipline, Layer 1/2/3 UI rules, substrate-sandboxed, zero-memory. Never writes boards/ledgers/run-state. |
-| Evaluate (GATE L3) | `spec-evaluator` | v1.0 | The single judge (pure worker). Verifies spec-conformance, TDD surface, and integration against the running app — skeptical, files `file:line` bugs, runs exactly once per build round. Requires a T0 artifact citation, grades UI affordance-only; verdict + refuted boxes return as data. |
-| QA (post-PASS) | `qa-edge-hunter` | v1.1 | Exploratory edge hunt on the running app through six fixed lenses, charting edges *outside* what the evaluator probed. Findings go to the ledger as `~`; never blocks ship. |
-| Stop (11) | `scope-hammer` | v0.1 | GATE H: must-have census → baseline comparison (never vs. the ideal) → cut list + ship verdict. Handles the normal stop and both circuit-breaker triggers. |
-| Retro (post-L4) | `coach` | — | RLHF for the harness: turns raw PO/TL feedback at Ship Sign-off into per-skill guidelines under committed `shapeup/knowledge-base/<skill>.md`, read back by six coachable workers on their next run and by `tech-lead` at GATE L0 (workflow guidance, never a gate answer). `--scan` seeds the same files from the project on disk before the first run; `--research <stack>` seeds them from the platform's official documentation when the project has nothing to scan, and cross-checks a scan's rules when it has. GATE COACH-1 asks the PO which skill owns each rule — never assumes; mechanism defects are filed to the harness-defect register instead. |
-| Orchestrator | `tech-lead` | v1.0 | Owns the run end-to-end: PLAN once → BUILD all tasks → EVAL once per round, looping on FAIL. Three-level circuit breaker (rounds / T0 attempts / wall clock), T0-verified build rounds, mechanical hill derivation. Sole writer of run-state. |
+| Phase | Skill | What it does |
+|-------|-------|--------------|
+| Shaping | `shapeup` | Frame the problem, breadboard affordances, spike risks, write the pitch. Sub-commands: `full`, `shaping`, `spike`, `breadboarding`, `framing-doc`, `kickoff-doc`, `breadboard-reflection`. |
+| Intake & Config | `building` | The `intake` sub-command, done by the loop itself: a non-English intake (pitch/PRD/transcript) becomes a faithful English `<name>.en.md` plus a persisted glossary, verified (residual-language scan, structural diff) before the run opens on it. The harness is English-only downstream. |
+| Orient | `orient` | Builder-led recon: reads the code, spikes the single riskiest area, emits a code-surface map, spike findings, discovered-task seed, and a hill signal. Writes no production code. |
+| Plan (Wiring Review, Board Review) | `building` | The loop that drives a run in your session, reading the run's files to decide what comes next. Planning is its `plan` activity, done in the loop's own context — no sub-agent — under a write fence (a fence-only `plan` order): requirements registry (`requirements.md`) → linked DDD spec tree + board (use cases with BDD scenarios, a system flow and a derived `## Test Surface`) → the committed wiring map (`wiring-map.md`: per-UC engine → seam → entry-point call site → affordance, resolved against `project-profile.md`) → write-whitelisted scope contracts (`scopes/*.md`). The loop reads the plan back against each substep's checklist; no script lints it. |
+| Build | `task-executor` | Pure worker: work order in → code out. Assumption scan, minimum-code/surgical-change discipline, Layer 1/2/3 UI rules, substrate-sandboxed, zero-memory. Never writes boards/ledgers/run-state. |
+| Evaluate (Verdict) | `spec-evaluator` | The single judge (pure worker). Verifies spec-conformance, TDD surface, and integration against the running app — skeptical, files `file:line` bugs, runs exactly once per build round. Requires a T0 artifact citation, grades UI affordance-only; verdict + refuted boxes return as data. |
+| QA (post-PASS) | `qa-edge-hunter` | Exploratory edge hunt on the running app through six fixed lenses, charting edges *outside* what the evaluator probed. Findings go to the ledger as QA findings; never blocks ship. |
+| Stop (Cut-List Review) | `building` | The `stop` sub-command — the Cut-List Review gate, done by the loop itself: must-have census (every ownership, exhaustion and requirement claim names the file it came from) → baseline comparison (never vs. the ideal) → cut list + ship verdict, written as data that the Ship Sign-off gate reads. Handles the normal stop and both circuit-breaker triggers. |
+| Retro (after Ship Sign-off) | `building` | The `retro` sub-command — RLHF for the harness: turns raw PO/TL feedback at Ship Sign-off into per-reader guidelines under committed `shapeup/knowledge-base/<reader>.md` (readers: `task-executor`, `orient`, `qa-edge-hunter`, the `plan` activity, and the loop itself at the Intake & Config gate — workflow guidance, never a gate answer). `--scan` seeds the same files from the project on disk before the first run; `--research <stack>` seeds them from the platform's official documentation when the project has nothing to scan, and cross-checks a scan's rules when it has. The Retro Ownership gate asks the PO which reader owns each rule — never assumes; mechanism defects are filed to the harness-defect register instead. |
 
 ### Commands
 
@@ -198,15 +182,15 @@ learnable from `/`-completion alone. Names are written short here; the real name
 | Command | Phase | Description |
 |---------|-------|-------------|
 | `/ship` | all | Run the full harness on a pitch (interactive gates by default; `--auto`, `--unattended`). |
-| `/shape` | 1 | Shape a raw idea into a pitch: boundaries → breadboard → spike → `pitch.md`. |
-| `/orient` | 7 | Builder-led recon; spikes the riskiest area, writes no production code. |
-| `/wire` | L1a.5 | Write the wiring map — engine → seam → entry-point call site, per use case. |
-| `/scopes` | 8 | Spec tree + board (`ba-pitch-analyzer`), then scope contracts (`scope-architect`). |
-| `/build` | 9 | Implement one task's acceptance criteria exactly. |
-| `/eval` | L3 | The single judge. Round mode is hook-gated — see the demo above. |
+| `/shape` | Shaping | Shape a raw idea into a pitch: boundaries → breadboard → spike → `pitch.md`. |
+| `/orient` | Orient | Builder-led recon; spikes the riskiest area, writes no production code. |
+| `/wire` | Wiring Review | Alias of `/ship plan`, through the wiring map — engine → seam → entry-point call site, per use case. |
+| `/scopes` | Board Review | Alias of `/ship plan`: spec tree + board, then scope contracts. |
+| `/build` | Build | Implement one task's acceptance criteria exactly. |
+| `/eval` | Verdict | The single judge. Round mode crosses the Round Close gate first. |
 | `/qa` | post-PASS | Exploratory edge hunt; findings never block ship. |
-| `/hammer` | H | Must-have census, baseline comparison, cut list + ship verdict. |
-| `/retro` | post-L4 | File ship-gate feedback into the per-skill knowledge base. |
+| `/hammer` | Cut-List Review | Must-have census, baseline comparison, cut list + ship verdict. |
+| `/retro` | after Ship Sign-off | File ship-gate feedback into the per-reader knowledge base; `--scan` and `--research <stack>` seed it. |
 
 ### What is enforced, and by what
 
@@ -216,34 +200,29 @@ the layer that carries it, and the three layers here fail differently:
 | Layer | Works when | Fails how |
 |---|---|---|
 | **Wall** — a hook | Under every permission mode, including `bypassPermissions`. The CLI runs it; the model cannot decline it. | Fail-OPEN on anything ambiguous, and every evaluation writes a decision row, so "permitted" never looks like "never ran". |
-| **Runtime** — the kernel and the run script | When the run goes through the harness. A schema rejection or a non-zero exit stops the step. | A lane that never calls the kernel is never checked — which is why the hooks below cover the doors, not the steps. |
+| **Runtime** — the kernel | When the run goes through the harness. A schema rejection or a non-zero exit stops the step. | A lane that never calls the kernel is never checked — which is why the hooks below cover the doors, not the steps. |
 | **Advisory** — a report section | When somebody reads the artifact. | Silently, if nobody does. It is a cleanup list, never a verdict. |
 
-**Five walls.** These are hooks because nothing in the runtime can substitute for them:
+**Four walls.** These are hooks because nothing in the runtime can substitute for them:
 
-- `PreToolUse` (`Skill`) — **`hooks/gate-intake.mjs` denies a `tech-lead` dispatch that carries no
-  pitch, no spec folder, and no requirement text.** Observed, not theorized: when the requirement
-  text is dropped on the hand-off and only a flag survives, the run prints the gate list, builds
-  nothing, and reads like a success while leaving every defect in the deliverable.
 - `PreToolUse` (`Skill|Agent`) — **`harness verify envelope` denies any worker dispatch whose order
   file is missing or fails the WorkOrder schema.** A malformed envelope never reaches a worker.
 - `PreToolUse` (`Edit|Write|MultiEdit`) — **`hooks/sandbox-guard.mjs` blocks a write that no LIVE
-  order's substrate permits.** It reads every order that is compiled and not yet answered — a result
-  at least as new as the order itself — rather than a pointer to one, so scopes building
-  concurrently are each held to their own contract and a finished run fences nothing. A phase
-  dispatch the run has already moved past stops fencing too: once a later phase compiles its order,
-  an evaluation or a QA leg that never returned a result no longer holds the board. `frozen` is
-  checked first and outranks everything, across every live contract — including the carve-out that
-  otherwise keeps the active feature's own run trace writable, so a path a live order froze stays
-  frozen wherever it lives. An order's own result answers to the sub-agent that took its
-  dispatch, so with two legs live neither can write the other's.
-- `PreToolUse` (`Edit|Write|MultiEdit`) — **`hooks/tier-guard.mjs` refuses a committed-tier write
-  whose content names a path into the local run trace or a board id.** Same rule spec-lint reds at
-  GATE L1b, asked at the moment of writing: four different producers wrote a committed file their
-  own lint then rejected, and one of them did it twice in one session, an hour apart, after fixing
-  the first occurrence itself. A worker carries no lesson across a dispatch, so the remedy is a
-  refusal the writer can act on while it still knows what it meant to say. The knowledge base is
-  outside it — those files are instructions, not references a reader has to resolve.
+  order's substrate permits.** It reads every order that is written and not yet answered rather than
+  a pointer to one, so scopes building concurrently are each held to their own contract and a finished
+  run fences nothing. `frozen` is checked first and outranks everything, across every live contract,
+  and an order's own result answers to the sub-agent that took its dispatch, so with two legs live
+  neither can write the other's. The fence is armed by a pointer the loop sets with `harness order open`
+  and retires with `harness order close`; with no pointer it allows every write, which is why those are
+  commands that read the pointer back rather than a file the loop edits. The close that records a
+  `shipped` ending refuses unless a Ship Sign-off row of the same run says `ship`, so the gate's
+  refusals cannot be walked around by ending the run.
+- `PreToolUse` (`Edit|Write|MultiEdit`) — **the same hook also refuses a committed-tier write whose
+  content names a path into the local run trace or a board id.** Four different producers wrote a
+  committed file that a later check rejected, and one did it twice in a session, because a worker carries
+  no lesson across a dispatch; the remedy is a refusal the writer can act on while it still knows what
+  it meant to say. The knowledge base is outside it — those files are instructions, not references a
+  reader has to resolve.
 - `PreToolUse` (`Bash|Read|Write|Edit|MultiEdit`) — **`hooks/safety-spine.mjs` denies destructive
   commands** (`rm -rf` on unrecoverable targets, force-push/push-to-main, `git reset --hard`,
   `DROP TABLE`) and secret-file reads. A machine guard, not a pipeline guard; the escape hatch is
@@ -251,38 +230,27 @@ the layer that carries it, and the three layers here fail differently:
 
 **One recorder**, which denies nothing and is what makes a wall possible one layer down:
 
-- `PostToolUse` (`Skill|Agent`) — **`hooks/dispatch-receipt.mjs` writes down which skill actually
+- `PostToolUse` (`Skill|Agent`) — **`hooks/dispatch-receipt.mjs` writes down which agent actually
   ran.** Until it existed, a dispatch that failed — plugin absent, disabled, or a different version
-  loaded — was indistinguishable from one that succeeded: the sub-agent would do the craft itself
-  from the prose in its own prompt, the artifacts landed in exactly the place the order permitted, so
-  the order gate and the sandbox guard both passed and the run advanced having applied none of the
-  shipped craft. A green run was consistent with zero worker craft. The hook appends
-  `{order_id, worker_declared, skill_invoked, dispatch_ok, at}` to `.shapeup/<slug>/receipts/`, and
-  `harness reduce ingest` refuses an orchestrated result with no matching receipt. A failed dispatch
-  never reaches `PostToolUse` at all, so the receipt's *existence* is the evidence. It has no deny
-  path, every write is guarded, and `--no-receipt-check` is the documented way through when the
-  channel itself fails.
-
-**One blocking Stop hook**, and it is the narrowest thing in the repo:
-
-- `Stop` — **`hooks/gate-zerowork.mjs` blocks a session that dispatched the orchestrator and left
-  no run receipt.** Its predicate is mechanical — orchestrator dispatched AND no
-  `.shapeup/<slug>/receipt.json` — so it never judges quality; it reports that no work exists to
-  judge. It exists because this harness was repeatedly observed describing its own pipeline instead
-  of running it: a narrated run that reads like a clean success. Fails open on everything
-  ambiguous, and `stop_hook_active` caps it at one block per stop chain.
-
-**What the runtime carries instead** (v2.0 retired six hooks whose work moved here):
-
-| Was a hook | Is now | What changed |
-|---|---|---|
-| `gate-l2` (EVAL over an unfinished board) | The GATE L2 block, which names `green_scopes` and `hammer_proposals` | It was advisory either way; now the same facts reach the human who answers the gate rather than a warning line above it. |
-| `gate-deadline` (deny builds past the wall clock) | `harness verify budget --strict`, checked at every round boundary | **A real coverage change, stated rather than hidden:** the round loop stops the run from opening ANOTHER round, but no longer interrupts a single build leg that runs long. `attempt_budget` bounds that leg by attempts instead. |
-| `session-rehydrate` + `compact-snapshot` | `harness reduce graph --slug <slug> --subgraph run` | A hook fired at two moments the platform chose; a command answers whenever the question is asked, including the moments a hook never saw. |
-| `anti-rationalization` (claims the facts contradict) | The ship report's census, derived from the board and the T0 artifacts | The facts are in an artifact a teammate finds on `git pull`, not in a transcript nobody re-reads. |
-| `slop-cleaner` (TODO/`console.log` leftovers) | The ship report's **Leftovers** section | Same scan, same added-lines-only rule; it lands somewhere checkable. |
-
-**Nothing load-bearing depends on permission mode.** The five walls plus the zero-work gate run
+  loaded — was indistinguishable from one that succeeded: the sub-agent would do the craft itself from
+  the prose in its own prompt, the artifacts landed where the order permitted, so the order gate and the
+  fence both passed and the run advanced having applied none of the shipped craft. The hook appends
+  `{order_id, worker_declared, skill_invoked, dispatch_ok, usage, model_requested, at}` to `.shapeup/<slug>/receipts/`,
+  with the tokens, duration and model the host measured beside the model the call asked for (the
+  agents inherit the session's model unless the dispatch names one, and Ship Sign-off reads what ran
+  against the launch record). A failed dispatch never reaches `PostToolUse`
+  at all, so the receipt's *existence* is the evidence. The loop counts an attempt against a receipt, not
+  against the artifact. It has no deny path and every write is guarded.
+
+**What the runtime no longer carries.** Earlier versions also checked, with scripts, that a spec was
+well-linked at the board review, that a worker's result was applied exactly once, that a run's attempts
+and rounds were counted from attested records, that the build and launch probes were green before
+evaluation, and that a ship report matched the board. Those are now the loop's own discipline, written
+in the `building` skill and checked by the PO and the evaluator. A measured comparison found the scripted
+sequencing completed more runs than the same loop reading its own table, at lower cost; the scripted
+engine was removed on the PO's decision anyway, and the record of that decision names the result.
+
+**Nothing load-bearing depends on permission mode.** The walls run
 under every mode. The kernel needs a grant to be *invoked* — two Bash lines `npx shapeup-sdlc init`
 writes — but a session that never gets that grant is a session that cannot run the pipeline at all,
 not one that runs it unguarded.
@@ -304,30 +272,19 @@ These hold across the harness and are the reason it stays predictable:
 - **Ledger is the single source of truth** — orient, task-executor, and QA all write to `discovery/ledger.md`.
 - **QA is a level-up, not a gate** — `--no-qa` skips it; the circuit breaker outranks the hunter; findings default to `~`.
 - **Role separation** — evaluator grades, task-executor fixes, QA discovers; no one does another's job.
-- **Three-level circuit breaker** — an outer `round_budget` (build+eval cycles) nests an inner
-  per-scope `attempt_budget` (T0 attempts); an exhausted scope queues a GATE H proposal instead
-  of blocking the round. An opt-in third breaker bounds the **wall clock**, because the other two
-  count events and neither can notice a single round running for half an hour — tripping it routes
-  to GATE H, so a run out of time ships what is green instead of being killed and shipping nothing.
-- **Hill phase is mechanical, never self-reported** — derived only from T0/T1 facts, closing the
-  self-reported-confidence risk. A scope with no
-  discovery ledger derives no phase rather than a solved one, so absence no longer reads as
-  progress on that arm.
-- **One writer per shared file** — every board/ledger/verdict write goes through
-  `harness reduce ingest`; workers return data and never touch shared state.
-- **Traceability is oracle-checked, opt-in** — `harness verify trace` verifies covers-closure and
-  wiring reachability from the committed spine artifacts; it ships advisory (warn-only) and every
-  arm is skipped when its artifact is absent, so older specs are non-regressed. Reachability also
-  skips when it cannot root its walk — an import it cannot follow, or no reachable engine to
-  control the result — because "every engine is orphaned" and "this is the wrong entry point" are
-  the same evidence, and a check that cannot tell them apart must say so rather than pick.
+- **Two circuit breakers** — an outer `round_budget` (build+eval cycles) nests an inner per-scope
+  `attempt_budget` (T0 attempts); an exhausted scope queues a Cut-List Review proposal instead of
+  blocking the round, and running out of rounds routes to the Cut-List Review too, so a run out of budget ships what is
+  green instead of being killed and shipping nothing.
+- **The witness is mechanical** — a T0 verdict is a command's exit code and a hash, not a report; the
+  evaluator re-hashes the artifact it cites.
+- **One writer per shared file** — the loop applies every board and ledger change; workers return data
+  and never touch shared state.
 
 ## Known rough edges
 
 Stated plainly, because you will hit them:
 
-- **The `--tiny` lane is young.** It right-sizes the ceremony (two gates instead of eight) but
-  keeps the T0 verification floor; its fit-check heuristics will need tuning against real use.
 - **Nothing here measures skill quality or activation.** There is no number for whether a
   skill's description makes it fire on the right request, no measured craft delta, and no CI
   check enforcing the honesty invariant on such numbers. The structural suite is the coverage
@@ -353,27 +310,28 @@ claude --plugin-dir .                # load this working copy without installing
 .claude-plugin/
   plugin.json         # plugin manifest
   marketplace.json    # marketplace listing (points at this repo)
-skills/<name>/SKILL.md # the 13 harness skills (+ references/ and assets/)
-skills/tech-lead/workflows/shapeup-run.js # the BUILD-phase pipeline, on the native Workflow runtime
+skills/<name>/SKILL.md # the 6 harness skills (+ references/, resources/ and assets/)
+agents/<worker>.md    # the 4 workers as plugin subagents: each preloads its skill; a dispatch names the agent
 kernel/harness.mjs    # ONE entry point for every deterministic step; the whole permission grant
-kernel/{verify,reduce,probe,init,report}/ #   its subcommands, plus compile and gate at the root
+kernel/{verify,init}/ #   its subcommands: the T0 witness, the envelope check, the roster check, init run
+kernel/{gate,order}.mjs #   the gate resolver, and the verb that arms and retires the fence
 kernel/lib/           # argv (the typed CLI boundary), paths (+ the run key), contract (shape)
 kernel/schemas/       # the envelope port: WorkOrder, WorkResult, domain registry
 commands/*.md         # slash commands (/ship + the 9 phase commands)
-hooks/                # hooks.json + the five walls: safety-spine, gate-intake, sandbox-guard,
-                      #   tier-guard (PreToolUse) + gate-zerowork (Stop, the one blocking hook)
-                      #   + dispatch-receipt (PostToolUse, denies nothing, attests which skill ran)
+hooks/                # hooks.json + the three walls: safety-spine, sandbox-guard (the substrate fence and the
+                      #   committed-tier write check) — PreToolUse, beside the kernel's `verify envelope`
+                      #   + dispatch-receipt (PostToolUse, denies nothing, attests which worker ran and what the host measured)
                       #   + lib/decision.mjs (every hook records allow / deny / error)
 oracles/              # the evaluation-contract oracle registry (test · snapshot · http · process)
-bin/init.mjs          # `npx shapeup-sdlc init` — scaffolds all three CLI targets
+bin/init.mjs          # `npx shapeup-sdlc init` — the permission grant, the AGENTS.md harness block, the ignore rules
 scripts/install-harness.sh, migrate.sh   # stable public entrypoints (fresh install / update)
 scripts/shapeup-sdlc/lib/                # shell libs both entrypoints source
 tools/                # repo-only: demo/
                       #   demo/record-demo.mjs (regenerates docs/assets/demo-gate.svg)
-tests/structural.mjs, tests/structural/*.mjs   # Tier 0 — 880+ checks, zero LLM calls
+tests/structural.mjs, tests/structural/*.mjs   # Tier 0 — ten modules, zero LLM calls
 docs/install.md, upgrading.md, glossary.md
-docs/design/          # the design document (pipeline, gates, circuit breaker, ERD) + adr/
-docs/visualize/       # rendered views of the tree and the pipeline
+docs/design/          # the design document (pipeline, gates, circuit breaker, ERD)
+docs/visualize/       # the before-and-after view of the v4 loop
 .github/workflows/    # CI + release (release publishes to npm via OIDC)
 ```
 

package/SECURITY.md

@@ -1,8 +1,8 @@
 # Security
 
-This plugin installs **eight hook entries (seven Node scripts + one `echo`)**: five in a
-`PreToolUse` position, **all five of which can deny a tool call**, one `PostToolUse` hook that has no
-deny path at all, and one `Stop`-position hook that can block a session from ending. That is the
+This plugin installs **four hook entries (three Node scripts + the kernel's `verify envelope`)**: three in a
+`PreToolUse` position, **all three of which can deny a tool call**, and one `PostToolUse` hook that has no
+deny path at all. No hook can block a session from ending. That is the
 product — and it is also exactly the kind of surface a careful reviewer should want spelled out
 before installing. This page is that spelling-out.
 
@@ -13,14 +13,14 @@ it to four walls and updated the table below without updating the sentence above
 ```bash
 node -e "const h=require('./hooks/hooks.json').hooks;
   for (const [e,gs] of Object.entries(h)) for (const g of gs) for (const x of g.hooks)
-    console.log(e, g.matcher||'*', x.command.match(/[^/ ]+\.mjs/)?.[0] ?? '(echo)')"
+    console.log(e, g.matcher||'*', x.command.match(/[^/ ]+\.mjs/)?.[0])"
 ```
 
 ## Reporting a vulnerability
 
 Use [GitHub private vulnerability reporting](https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin/security/advisories/new)
 for anything exploitable — especially anything that would let a run **escape a deny** (write
-outside a substrate, dispatch on an uncompiled order, widen its own safety overrides) or
+outside a substrate, dispatch without a schema-valid order, widen its own safety overrides) or
 exfiltrate data.
 For non-sensitive hardening ideas, an ordinary issue is fine.
 
@@ -38,23 +38,20 @@ test against machines you don't own.
 3. **Every hook is fail-open by design.** Unparseable input, missing state files, or an
    unrecognized invocation shape → the hook defers and the normal permission flow proceeds. A
    hook denies only when it can positively prove its condition (a matched destructive command, a
-   path no live order's substrate permits, an invalid order file, an empty intake).
+   path no live order's substrate permits, an invalid order file).
 4. **The model cannot widen its own safety envelope.** The escape hatch
    (`.shapeup/safety-overrides.json`) is human-authored; `safety-spine` itself denies any
    write/move/delete touching that file, a malformed overrides file is treated as absent
    (override channel fails closed), and every exercised override is logged. The same principle
    covers `.shapeup/active-order`, which `sandbox-guard` reads to find the run whose orders fence
    a worker's writes: it sits outside the run-trace carve-out, so a worker cannot repoint its own
-   sandbox. The `last-run` breadcrumb a terminal close leaves beside it is read for one purpose — keying a decision row to the run that just ended, marked `run_closed` — and arms nothing: liveness is derived from the order set and the pointer, never from that file. Every hook resolves that pointer, the decision ledger and the substrate globs against
+   sandbox. The `close.json` a terminal close writes beside the run's records names the ending and arms nothing: liveness is derived from the order set and the pointer, never from that file, and the close retires the pointer. Every hook resolves that pointer, the decision ledger and the substrate globs against
    the project root it finds above the tool call's working directory (a run pointer, the committed
    tier, or a git boundary) — a worker that `cd`s into a sub-folder is fenced exactly as one at the
    top, and its receipts land in the same ledger.
-5. **Exactly one hook can block, and only on a mechanical absence.** `gate-zerowork` returns
-   `decision: "block"` in one state: the session dispatched the orchestrator and left no run
-   receipt on disk. It makes no judgement about quality — it reports that there is no work to
-   judge. `stop_hook_active` caps it at one block per stop chain. Every other check that used to
-   emit an advisory `systemMessage` at `Stop` now lands in the ship report instead, where it is a
-   section a person can read afterwards rather than a line in a transcript.
+5. **No hook can block a session from ending.** A session that narrates a run instead of opening one
+   is not stopped by the runtime; `building` opens its run as its first act and the receipt it writes is
+   what every later guard reads.
 6. **Every hook decision is recorded.** `hooks/lib/decision.mjs` is the only exit path a hook
    has, so allow, deny, block and error each leave a row in `.shapeup/decisions.jsonl`. An
    inert hook and a permitting hook are therefore distinguishable — which matters, because
@@ -73,14 +70,9 @@ sitting, and reading them is the recommended review.
 | Hook | Event (matcher) | Reads | Can deny | Never does |
 |---|---|---|---|---|
 | [`safety-spine.mjs`](hooks/safety-spine.mjs) | PreToolUse (`Bash\|Read\|Write\|Edit\|MultiEdit`) | The proposed command/path; `.shapeup/safety-overrides.json` | Yes — provably destructive ops only: `rm -rf` on unrecoverable targets, `git push --force` / push to main, `git reset --hard`, `git clean -fdx`, `DROP TABLE`/`TRUNCATE`, reads of `.env`/keys/cloud credentials, and any write to its own overrides file | Never blocks an unmatched command; `--force-with-lease` stays allowed |
-| [`gate-intake.mjs`](hooks/gate-intake.mjs) | PreToolUse (`Skill`) | The `tech-lead` dispatch's own arguments | Yes — an orchestrator dispatch carrying no resolvable intake (no pitch, spec, resume or requirement text) | Fails open on `--order` and on any ambiguous arg shape |
 | [`harness verify envelope`](kernel/verify/envelope.mjs) | PreToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the JSON schemas | Yes — a worker dispatch whose order file is missing or schema-invalid | Never gates a dispatch that carries no `--order` (standalone skill use stays free) |
-| [`sandbox-guard.mjs`](hooks/sandbox-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path, resolved through the filesystem before it is compared — symlinks followed, the unborn tail re-attached to its real ancestor, case folded where the filesystem folds case — so a spelling variant of a frozen file is the frozen file; the `substrate` block of every LIVE order — compiled, with no result at least as new as the order's own `compiled_at`, and, for a run-level phase dispatch, not yet superseded by a later phase's order | Yes — any write no live order permits: inside any `frozen`, outside every `allowed`/`shared`, or a `Write` to an `append_only` path. `frozen` is checked FIRST, so it also outranks the run-trace carve-out. An order's own paths (its result first) are writable only by the sub-agent its dispatch receipt names, so one live leg cannot write another's result; a write with no sub-agent id, or an order with no receipt, keeps the path-only rule | No-op unless an order is live, which a finished run no longer is: the pointer names the run, never a dispatch. The active feature's own `.shapeup/<slug>/` run trace is writable EXCEPT where a live order freezes a path inside it. Appends denials to the local pathology log |
-| [`tier-guard.mjs`](hooks/tier-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path; the text the call is about to write (`content`, `new_string`, or any edit in a `MultiEdit` batch) | Yes — a write into `shapeup/<slug>/` whose content names a `.shapeup/` path or a `TASK-NNN` board id: the same tier-direction rule spec-lint reds at GATE L1b, refused at the moment of writing, with the offending token quoted back | No-op outside `shapeup/<slug>/`, on file forms the lint does not scan, and on `shapeup/knowledge-base/` (instructions to a worker, not references). Reads nothing off disk and writes only its decision row; it never inspects a file it is not being asked to write |
-| [`dispatch-receipt.mjs`](hooks/dispatch-receipt.mjs) | PostToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the tool result's own report of which skill ran | **No — it has no deny path at all.** It records that the shipped skill ran, so `harness reduce ingest` can refuse a result no dispatch produced | Never writes an attestation for a result that does not name a resolved skill; never fails the call it observes (every write is inside `try`/`catch`) |
-| [`gate-zerowork.mjs`](hooks/gate-zerowork.mjs) | Stop | Run receipts on disk; the session transcript; the decision ledger | **Yes — the one blocking hook.** Returns `decision:"block"` when the session dispatched the orchestrator and produced no run receipt | Defers the moment any receipt exists; `stop_hook_active` caps it at one block per stop chain |
-
-(The remaining `hooks.json` entry is a plain `echo` on SessionStart confirming the plugin loaded.)
+| [`sandbox-guard.mjs`](hooks/sandbox-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path, resolved through the filesystem before it is compared — symlinks followed, the unborn tail re-attached to its real ancestor, case folded where the filesystem folds case — so a spelling variant of a frozen file is the frozen file; the `substrate` block of every LIVE order — written, with no result at least as new as the order's own `compiled_at`, and, for a run-level phase dispatch, not yet superseded by a later phase's order | Yes — any write no live order permits: inside any `frozen`, outside every `allowed`/`shared`, or a `Write` to an `append_only` path. `frozen` is checked FIRST, so it also outranks the run-trace carve-out. An order's own paths (its result first) are writable only by the sub-agent its dispatch receipt names, so one live leg cannot write another's result; a write with no sub-agent id, or an order with no receipt, keeps the path-only rule. Independently of any order, a write into `shapeup/<slug>/` whose content names a `.shapeup/` path or a `TASK-NNN` board id: the tier-direction rule, refused at the moment of writing with the offending token quoted back | The substrate fence is a no-op unless an order is live, which a finished run no longer is: the pointer names the run, never a dispatch. The active feature's own `.shapeup/<slug>/` run trace is writable EXCEPT where a live order freezes a path inside it. Appends denials to the local pathology log. The tier check is a no-op outside `shapeup/<slug>/`, on file forms the lint does not scan, and on `shapeup/knowledge-base/` (instructions to a worker, not references); it never inspects a file it is not being asked to write |
+| [`dispatch-receipt.mjs`](hooks/dispatch-receipt.mjs) | PostToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the tool result's own report of which skill ran | **No — it has no deny path at all.** It records that the shipped skill ran, so the loop counts an attempt only against a dispatch that produced it | Never writes an attestation for a result that does not name a resolved skill; never fails the call it observes (every write is inside `try`/`catch`) |
 
 ## Data handling
 
@@ -90,11 +82,10 @@ sitting, and reading them is the recommended review.
   any kind.
 - **The safety-spine actively blocks secret reads** (`.env`, `*.pem`, `*.key`, ssh/cloud
   credentials) rather than merely not making them.
-- **The script the run executes is a copy, and the copy is the shipped file.** Opening a run
-  copies the plugin's own workflow scripts into the gitignored `.shapeup/workflows/`, because the
-  Workflow tool loads a script only from a directory the session may already read and the plugin
-  installs outside your project. They are copied byte for byte — never generated, templated or
-  rewritten — so what you review in the plugin is what runs, and nothing else is added to your tree.
+- **Nothing is copied into your project to run.** The run is driven by the loop in your session
+  through two kernel Bash rules, so there is no script staged into your tree, no launch to authorise,
+  and no unscoped `Workflow` permission to grant: the installer writes the two rules and nothing else,
+  and a `Workflow` token you already have is yours and is left alone.
 - The installer (`scripts/install-harness.sh`) writes only into the target project
   (`.claude/`, `shapeup/`, `.gitignore`) and tells you what it
   is going to do first; the `curl | bash` form requires an explicit `--yes` for exactly that

package/agents/orient.md

@@ -0,0 +1,14 @@
+---
+name: orient
+description: The Scout. Dispatched by the run loop with a WorkOrder path to map the code surface a pitch touches and to run its spikes before any board exists. Never invoke by hand; use /ship.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+skills:
+  - orient
+---
+
+You are the `orient` worker of a Shape Up run. Your craft is the `orient` skill, which is already loaded
+into this context. Your whole brief is the WorkOrder path and the note you were dispatched with: follow the
+skill against that order, write the artifacts the order names, write your WorkResult where the order says,
+and return one line. You were told nothing about the run's history or the other workers, and you should not
+go looking for it.

package/agents/qa-edge-hunter.md

@@ -0,0 +1,13 @@
+---
+name: qa-edge-hunter
+description: The edge hunter. Dispatched by the run loop after the first PASS with a WorkOrder path to explore the running app for what the evaluator did not probe. Never invoke by hand; use /ship.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+skills:
+  - qa-edge-hunter
+---
+
+You are the `qa-edge-hunter` worker of a Shape Up run. Your craft is the `qa-edge-hunter` skill, which is
+already loaded into this context. Your whole brief is the WorkOrder path and the note you were dispatched
+with: follow the skill against that order, log what you find with a repro and no verdict, write your
+WorkResult where the order says, and return one line. You discover; you never block and never score.

package/agents/spec-evaluator.md

@@ -0,0 +1,14 @@
+---
+name: spec-evaluator
+description: The single judge. Dispatched by the run loop with a WorkOrder path to grade a round against the spec and the Test Surface. Never invoke by hand; use /ship.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+skills:
+  - spec-evaluator
+---
+
+You are the `spec-evaluator` worker of a Shape Up run. Your craft is the `spec-evaluator` skill, which is
+already loaded into this context. Your whole brief is the WorkOrder path and the note you were dispatched
+with: follow the skill against that order, cite the T0 artifacts the order lists by re-hashing them
+yourself, write your WorkResult where the order says, and return one line. You did not build what you
+grade, and you should not fix it.

package/agents/task-executor.md

@@ -0,0 +1,14 @@
+---
+name: task-executor
+description: The builder. Dispatched by the run loop with a WorkOrder path to implement one scope's acceptance criteria inside its write substrate. Never invoke by hand; use /ship.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+skills:
+  - task-executor
+---
+
+You are the `task-executor` worker of a Shape Up run. Your craft is the `task-executor` skill, which is
+already loaded into this context. Your whole brief is the WorkOrder path and the note you were dispatched
+with: follow the skill against that order, write only inside the substrate the order declares, write your
+WorkResult where the order says, and return one line. You were told nothing about the run's history or the
+other scopes, and you should not go looking for it.