shapeup-sdlc 1.6.3 → 3.0.0

package/README.md

@@ -15,11 +15,11 @@ The ceremony is right-sized: `/ship` runs the full gated pipeline for real featu
 fixes where the gates would have nothing to say.
 
 <p align="center">
-  <img src="docs/assets/demo-gate.svg" alt="Terminal recording: the agent tries to run EVAL with two tasks unfinished, and a PreToolUse hook denies the tool call outright." width="700">
+  <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">
 </p>
 
 <p align="center"><sub>
-The denial text above is <b>verbatim stdout</b> from <code>hooks/gate-l2.mjs</code> —
+The denial above is <b>verbatim stdout</b> from <code>hooks/sandbox-guard.mjs</code> —
 <a href="tools/demo/record-demo.mjs">the recorder runs the real hook</a> and fails rather than
 draw a picture. <a href="docs/assets/demo-gate.txt">Plain-text transcript.</a>
 </sub></p>
@@ -32,8 +32,8 @@ 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 outside the active scope's
-file substrate, and blocks a session that dispatched the orchestrator and left no run receipt.
+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.
 → *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
@@ -54,52 +54,64 @@ Under the hood this rests on a typed worker envelope and a single-writer state l
 are load-bearing plumbing, and you should not have to think about them to use the harness —
 they are documented for [contributors](CONTRIBUTING.md), not for users.
 
-> ### Just want the gate?
->
-> The enforcement layer ships separately as the **[Anti-Lying Kit](plugins/anti-lying-kit/)** —
-> three hooks, no methodology, installable *alongside* spec-kit, OpenSpec, or your own
-> `tasks.md`. You should not have to adopt Shape Up to stop your agent claiming done.
->
-> ```
-> /plugin install anti-lying-kit@nvptuoc-marketplace
-> ```
-
 ## Quickstart
 
 ```
 /plugin marketplace add nguyenvanphituoc/shapeup-sdlc-plugin
 /plugin install shapeup-sdlc-plugin@nvptuoc-marketplace
-/ship "add dark mode to the settings screen"
+/shapeup-sdlc-plugin:ship "add dark mode to the settings screen"
 ```
 
-`/ship` walks the whole lifecycle and pauses at each gate for you. That's the whole quickstart.
+That last one walks the whole lifecycle and pauses at each gate for you. That's the whole
+quickstart.
+
+> **The `shapeup-sdlc-plugin:` prefix is not optional.** A plugin's commands are namespaced by the
+> plugin that ships them, so the bare `/ship` is not a command and answers `Unknown command: /ship`
+> — measured on both a marketplace install and a `--plugin-dir` checkout. Interactively you will
+> normally pick the command off `/`-completion and never type the prefix yourself; it matters when
+> you are writing the command down, which is exactly what a headless `claude -p` invocation or a CI
+> step does. **Everything below writes commands in the short form for readability — prepend
+> `shapeup-sdlc-plugin:` to any of them you actually type.**
+
+> **Running unattended?** The plugin install grants no permissions — every pipeline step is a Node
+> script that ships *with* the plugin and therefore lives outside your project, so it needs
+> approval. You click once interactively; headless there is nobody to click. Scaffold instead, which
+> writes the grant:
+>
+> ```bash
+> 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.
 
 Want to see a full run before installing anything? **[docs/quickstart.md](docs/quickstart.md)**
-walks one small feature end to end — including the hook denying a premature eval, a FAIL round
+walks one small feature end to end — including what the hooks do to a premature eval, a FAIL round
 with real evaluator output, and the fix that turns it green.
 
 <sub>No prerequisites for non-UI work — a browser (`npx playwright install chromium`) is needed
 only when a run actually reaches a `[ui]` acceptance criterion. Team installs, the scaffolding
-installer (Claude Code / Antigravity / Codex), and troubleshooting are in
+installer, and troubleshooting are in
 **[docs/install.md](docs/install.md)**; upgrading is **[docs/upgrading.md](docs/upgrading.md)**.</sub>
 
 ## Agent support
 
-The harness is written once and compiled to other agent CLIs (`npm run distribute` emits
-`dist/`; the [scaffolding installer](docs/install.md#local-scaffolding) wires targets in one
-run). The matrix is honest — the row that matters most does not travel:
-
-| | Claude Code | Cursor | Antigravity | Codex |
-|---|:---:|:---:|:---:|:---:|
-| The 13 skills | ✅ plugin | ✅ `.mdc` rules (references inlined) | ✅ subagent defs + skill files | ✅ skill files |
-| Slash commands | ✅ all 10 | ✅ VS Code/Cursor extension + rules | — | — |
-| Pipeline scripts (`t0-verify`, `trace-lint`, oracles) | ✅ | ✅ plain Node, run from any CLI | ✅ | ✅ |
-| **Hook-enforced gates** (deny on premature EVAL, substrate sandbox, safety spine) | ✅ | ❌ | ❌ | ❌ |
-| Advisory Stop hooks | ✅ | ❌ | ❌ | ❌ |
-
-Hooks are a per-CLI mechanism, so outside Claude Code the gates degrade from **enforced** to
-**instructed** — the same honor system every other framework runs on everywhere. If the deny
-hook is why you're here, that currently means Claude Code.
+The harness targets **Claude Code only**. The reason is the row that never travelled when we
+compiled to other CLIs: hooks. The 12 skills, 10 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
+**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.
 
 ## Glossary
 
@@ -108,15 +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. The deny hook reads this. |
+| **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. |
 | **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 + a DB probe + the seesaw. Writes an artifact to disk that the evaluator must cite. |
 | **seesaw** | The part of T0 that re-runs *other* scopes' fixtures — so a regression is never mistaken for progress. |
-| **substrate** | The exact list of files one scope is allowed to write. A hook blocks anything outside it. |
+| **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 enforced by a hook. |
+| **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". |
 | **discovery ledger** | The one file everything found mid-run gets written to, so nothing is lost between rounds. |
@@ -128,37 +140,24 @@ A longer version, including the internals, is in [docs/glossary.md](docs/glossar
 The harness walks a pitch from idea to ship. The full annotated pipeline — the build round,
 the gate walkthrough, the circuit breaker — is
 [`docs/design/04-functional-design.md`](docs/design/04-functional-design.md), and the design
-document as a whole starts at [`docs/design/`](docs/design/README.md). A simplified view:
-
-```mermaid
-graph LR
-    A([Raw Idea]) --> S["Shaping<br>/shapeup"]
-    S --> P["Pitch"]
-    P --> BET{"Betting<br>(PO)"}
-    BET --> KO["Kick-off + Orient<br>/orient"]
-    KO --> WIRE["Wire<br>/solution-architect"]
-    WIRE --> MAP["Map Scopes<br>/ba-pitch-analyzer<br>+ /scope-architect"]
-    MAP --> BUILD["Build Vertically<br>/task-executor"]
-    BUILD --> EVAL["Evaluate<br>/spec-evaluator"]
-    EVAL -- FAIL --> BUILD
-    EVAL -- PASS --> QA["Edge Hunt<br>/qa-edge-hunter"]
-    QA --> SHIP["Triage + Ship<br>/scope-hammer"]
-    SHIP --> RETRO["Coach Retro<br>/coach"]
-    TL["/tech-lead orchestrates Orient → Ship"] -.-> KO
-
-    classDef plan fill:#e3f2fd,stroke:#1e88e5;
-    classDef build fill:#e8f5e9,stroke:#43a047;
-    classDef qa fill:#fce4ec,stroke:#c2185b;
-    class S,WIRE,MAP plan;
-    class KO,BUILD build;
-    class QA,EVAL qa;
-```
+document as a whole starts at [`docs/design/`](docs/design/README.md). This diagram shows the
+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">
+</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.
+</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
-`skills/tech-lead/scripts/trace-lint.mjs` checks that no engine ships orphaned. It runs
+`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.
 
@@ -171,13 +170,12 @@ every arm is skipped when its artifact is absent, so older specs are unaffected.
 | 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 `trace-lint.mjs` 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, five order-selected operations (analyze / generate-board / reconcile / retrofit-surface / coverage — the last writes the shared `requirements.md` registry for covers-closure); graph math + audits delegated to `board-derive.mjs`/`spec-lint.mjs`. |
-| 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. Operations: map-scopes / remap / split-scope. |
+| 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. |
-| Advisor (mid-build) | `advisor-protocol` | v0.1 | Adjudicates a worker's structured `ESCALATE` (design decision / spec ambiguity / substrate expansion) within a per-scope-per-round budget; persists answers to the committed round ledger so they survive a zero-memory reset. |
 | 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 `task-executor` / `ba-pitch-analyzer` / `qa-edge-hunter` on their next run. 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/seesaw-verified build rounds, mechanical hill derivation. Sole writer of run-state. |
@@ -185,7 +183,8 @@ every arm is skipped when its artifact is absent, so older specs are unaffected.
 ### Commands
 
 `/ship` runs the whole lifecycle; the phase commands run one step each, so the pipeline is
-learnable from `/`-completion alone.
+learnable from `/`-completion alone. Names are written short here; the real name of each carries the
+`shapeup-sdlc-plugin:` prefix, which `/`-completion fills in for you and a script must spell out.
 
 | Command | Phase | Description |
 |---------|-------|-------------|
@@ -200,58 +199,71 @@ learnable from `/`-completion alone.
 | `/hammer` | H | Must-have census, baseline comparison, cut list + ship verdict. |
 | `/retro` | post-L4 | File ship-gate feedback into the per-skill knowledge base. |
 
-### Agents
-
-| Agent | Description |
-|-------|-------------|
-| `reviewer` | Independent correctness/security code reviewer (returns findings, never edits). |
-
-### Hooks
-
-Nine Node hooks. What each one reads and what it can deny:
-
-- `SessionStart` — prints a load confirmation so you know the plugin is active; on
-  `startup|compact|resume|clear`, `hooks/session-rehydrate.mjs` additionally injects the mid-run
-  `RunSnapshot` hint ("trust the files, not the summary") when a harness run is in flight. On a
-  cold `startup` it leads with the stronger sentence — *a run is already open; resume it, do not
-  re-open it* — because that is the failure a fresh session actually makes. Silent when no run is
-  in flight, which is the ordinary case.
-- `PreToolUse` (matcher `Skill`) — **`hooks/gate-l2.mjs` hard-blocks the once-per-round EVAL
-  delegation while the task board isn't fully green.** This is the gate in the demo above.
-- `PreToolUse` (matcher `Skill`) — **`hooks/gate-intake.mjs` denies a `tech-lead` dispatch that
-  carries no pitch, no spec folder, and no requirement text.** Measured on the SDD harness
-  benchmark: when the requirement text was dropped on the hand-off and only a flag survived, the
-  run printed the gate list, built nothing, and scored 29% against a hidden acceptance suite while
-  looking like a success (n=3, zero variance). An orchestrator with no spec now fails loudly
-  instead of narrating.
-- `PreToolUse` (matcher `Skill`) — **`hooks/gate-deadline.mjs` denies a `task-executor` dispatch
-  once the run's opt-in wall-clock budget is spent**, routing to GATE H instead. `spec-evaluator`,
-  `scope-hammer`, `qa-edge-hunter` and `advisor-protocol` stay reachable — a run past its deadline
-  must still be able to judge, hammer and close. Off unless a budget is configured.
-- `PreToolUse` (matcher `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. Machine guard, not pipeline guard;
-  escape hatch is the human-authored `.shapeup/safety-overrides.json`.
-- `PreToolUse` (matcher `Edit|Write|MultiEdit`) — `hooks/sandbox-guard.mjs` blocks writes
-  outside the active scope's substrate whitelist (no-op unless scope contracts exist).
-- `PreToolUse` (matcher `Skill|Agent`) — `skills/tech-lead/scripts/validate-envelope.mjs`
-  denies any worker dispatch whose order file is missing or schema-invalid.
-- `Stop` — **`hooks/gate-zerowork.mjs` blocks a session that dispatched the orchestrator and
-  left no run receipt.** The one blocking `Stop` hook, and the narrowest: 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 the benchmark caught
-  this harness describing its own pipeline instead of running it (Haiku 4.5, n=5, zero variance,
-  29% acceptance) while both existing guards structurally could not see it: one is scoped to an
-  active run, and a run that never started leaves no files; the other matches past-tense
-  completion claims, and narration is future-tense. Fails open on everything ambiguous, and
-  `stop_hook_active` caps it at one block per stop chain.
-- `Stop` — two **advisory, never-blocking** hooks (`hooks/anti-rationalization.mjs` flags
-  completion claims the board/T0 facts contradict — including a future-tense promise left as the
-  session's last word; `hooks/slop-cleaner.mjs` flags TODO/`console.log`/commented-out-code
-  leftovers in the session's diff). They emit at most a `systemMessage` — "QA is a level-up, not
-  a gate."
-- `PreCompact` — `hooks/compact-snapshot.mjs` persists the mid-run `RunSnapshot` to
-  `.shapeup/<slug>/run-snapshot.json` before the conversation is compacted.
+### What is enforced, and by what
+
+The honest version of this table matters more than a long one. A guarantee is only as strong as
+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. |
+| **Advisory** — a report section | When somebody reads the artifact. | Silently, if nobody does. It is a cleanup list, never a verdict. |
+
+**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 compiled-but-not-yet-ingested order rather than a
+  pointer to one, so scopes building concurrently are each held to their own contract; `frozen`
+  outranks everything, across all of them.
+- `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
+  the human-authored `.shapeup/safety-overrides.json`.
+
+**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
+  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 four walls plus the zero-work gate 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.
 
 No hook makes a network request, none has dependencies, and all are plain, readable `.mjs`
 files. **[SECURITY.md](SECURITY.md)** states what each hook reads, what it can deny, and what
@@ -278,8 +290,8 @@ These hold across the harness and are the reason it stays predictable:
 - **Hill phase is mechanical, never self-reported** — derived only from T0/T1/seesaw facts, closing
   the self-reported-confidence risk outright.
 - **One writer per shared file** — every board/ledger/verdict write goes through
-  `ingest-result.mjs`; workers return data and never touch shared state.
-- **Traceability is oracle-checked, opt-in** — `trace-lint.mjs` verifies covers-closure and
+  `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.
 
@@ -289,14 +301,13 @@ 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.
-- **Only half the trigger-eval story is measured.** Skill *discrimination* is:
-  **0 false activations across 75 cross-skill hard negatives** (Haiku 4.5, 2026-07-26 — the
-  thirteen descriptions do not steal each other's work). *Activation* rate is measured but
-  confounded and deliberately not quoted as a headline: 38 of 74 positive cases point at a
-  referent ("coach **this feedback**") the probe never supplies, so a model that names the right
-  skill and asks for the missing input scores as a miss. Method, per-skill numbers, and the fix
-  are in [evals/README.md](evals/README.md) — the harness ships a CI test that *fails* if
-  fabricated results appear, and three earlier baselines were discarded rather than published.
+- **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
+  that exists, and it is about mechanism rather than quality — it proves a gate denies and an
+  oracle discriminates, never that a skill's output is good.
+- **The gates are verified; the craft is not.** A hook that denies is proven by a test that
+  watches it deny. A skill that writes a good spec tree is, at present, taken on trust.
 
 Contributions to any of these are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
@@ -315,37 +326,40 @@ 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/scripts|schemas/        # orchestrator pipeline: init-run, gate-answers,
-                                         #   budget-check, compile-order, ingest-result, validate-envelope,
-                                         #   t0-verify, trace-lint, aegis-digest, run-snapshot,
-                                         #   stats + envelope and gate-answer schemas
-skills/ba-pitch-analyzer/scripts/        # planner mechanics: board-derive, spec-lint
-skills/spec-evaluator/scripts/           # verdict-ledger (reference impl of the flip/confidence grammar)
+skills/<name>/SKILL.md # the 12 harness skills (+ references/ and assets/)
+skills/tech-lead/schemas/                # the envelope port: WorkOrder, WorkResult, domain registry
+skills/tech-lead/workflows/shapeup-run.js # the BUILD-phase pipeline, on the native Workflow runtime
+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/lib/           # argv (the typed CLI boundary), paths (+ the run key), contract (shape)
 commands/*.md         # slash commands (/ship + the 9 phase commands)
-agents/*.md           # subagents (reviewer)
-hooks/                # hooks.json + safety-spine, gate-l2, gate-intake, gate-deadline,
-                      #   sandbox-guard (PreToolUse),
-                      #   gate-zerowork (Stop, blocking), anti-rationalization, slop-cleaner (Stop, advisory),
-                      #   compact-snapshot (PreCompact), session-rehydrate (SessionStart)
+hooks/                # hooks.json + the four walls: safety-spine, gate-intake, sandbox-guard
+                      #   (PreToolUse) + gate-zerowork (Stop, the one blocking hook)
+                      #   + dispatch-receipt (PostToolUse, denies nothing, attests which skill ran)
+                      #   + 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
 scripts/install-harness.sh, migrate.sh   # stable public entrypoints (fresh install / update)
-tools/demo/record-demo.mjs             # regenerates docs/assets/demo-gate.svg
-scripts/shapeup-sdlc/                    # dev/CI tooling: lib/, migrations/, oracles/,
-                                         #   trigger-eval.mjs, distribute.js
+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
 docs/install.md, upgrading.md, glossary.md
-docs/design/          # the design document (pipeline, gates, circuit breaker, ERD)
-docs/internal/launch/          # directory-submission copy
-.github/workflows/    # CI + release
+docs/design/          # the design document (pipeline, gates, circuit breaker, ERD) + adr/
+docs/visualize/       # rendered views of the tree and the pipeline
+.github/workflows/    # CI + release (release publishes to npm via OIDC)
 ```
 
 ## Release
 
-1. Bump `version` in `.claude-plugin/plugin.json`.
+1. Bump `version` in **both** `.claude-plugin/plugin.json` and `package.json` — the release
+   workflow fails if either disagrees with the tag.
 2. Update `CHANGELOG.md`.
-3. Tag and push: `git tag v1.3.1 && git push origin v1.3.1`.
+3. Tag and push: `git tag v1.7.0 && git push origin main --follow-tags`.
 
-The release workflow validates the plugin, checks the tag matches the manifest version,
-and publishes a GitHub release.
+The workflow validates the plugin, checks the tag against both manifests, publishes a GitHub
+release, and publishes to npm through **trusted publishing (OIDC)** — no `NPM_TOKEN`, no OTP, with
+a SLSA provenance attestation attached automatically.
 
 ## Credits
 

package/SECURITY.md

@@ -1,38 +1,61 @@
 # Security
 
-This plugin installs **eight hook entries (seven Node scripts + one `echo`)**, four of them in
-a `PreToolUse` position where they can deny tool calls. 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.
+This plugin installs **seven hook entries (six Node scripts + one `echo`)**: four in a
+`PreToolUse` position, **all four 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
+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.
+
+Count them yourself rather than taking the paragraph's word for it, because this paragraph has been
+wrong before — it described a twelve-entry surface for the whole life of v2.0, after the hook diet cut
+it to four walls and updated the table below without updating the sentence above it:
+
+```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)')"
+```
 
 ## 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** (talk
-past GATE L2, write outside a substrate, widen its own safety overrides) or exfiltrate data.
+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
+exfiltrate data.
 For non-sensitive hardening ideas, an ordinary issue is fine.
 
-In scope: the hooks, the pipeline scripts (`compile-order` / `ingest-result` /
-`validate-envelope` / `t0-verify`), the installer/migration shell scripts, and any prompt-
-injection path through skill files. Please do not test against machines you don't own.
+In scope: the hooks, the kernel (`kernel/harness.mjs` and every subcommand beneath it), the
+installer/migration shell scripts, and any prompt-injection path through skill files. Please do not
+test against machines you don't own.
 
 ## The claims, stated so they can be falsified
 
-1. **No hook or pipeline script makes a network request.** There is no `fetch`, no
+1. **No hook or kernel subcommand makes a network request.** There is no `fetch`, no
    `node:http(s)`, no `node:net`, no shelling out to `curl`/`wget` anywhere in `hooks/` or
-   `skills/*/scripts/`. Verify: `grep -rnE "fetch|node:http|node:net|curl|wget" hooks/ skills/*/scripts/`.
+   `kernel/`. Verify: `grep -rnE "fetch|node:http|node:net|curl|wget" hooks/ kernel/`.
 2. **No hook has dependencies.** Plain `.mjs`, Node standard library only, no `node_modules`,
    no install-time scripts. What you read is what runs.
 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 non-green board, a matched
-   destructive command, a path outside a declared substrate, an invalid order file).
+   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).
 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.
-5. **Stop hooks never block.** The two Stop-position hooks are advisory: they emit at most a
-   `systemMessage` and always exit 0.
+   (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.
+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.
+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
+   "exit 0, no output" is what both used to look like.
 
 If you find any of these to be false, that is a vulnerability — report it as claim #ⁿ.
 
@@ -44,25 +67,24 @@ 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-l2.mjs`](hooks/gate-l2.mjs) | PreToolUse (`Skill`) | The round's task board (`.shapeup/<slug>/tasks/`) | Yes — the once-per-round EVAL dispatch while any task is unfinished | Never gates a single-task eval (`--task`); no board → defers |
-| [`validate-envelope.mjs`](skills/tech-lead/scripts/validate-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; the active scope contract | Yes — writes outside the active scope's substrate whitelist | No-op unless a scope is active; the active feature's own `.shapeup/<slug>/` run-trace is always writable. Appends denials to the local pathology log |
-| [`anti-rationalization.mjs`](hooks/anti-rationalization.mjs) | Stop | Board/T0 facts vs. the reply's completion claims | **No** — advisory `systemMessage` only | Never `decision:"block"`, never exit 2 |
-| [`slop-cleaner.mjs`](hooks/slop-cleaner.mjs) | Stop | The session's git diff (local `git diff`, via `spawnSync`) | **No** — advisory `systemMessage` flagging TODO / `console.log` / commented-out leftovers | Same — never blocks |
-| [`compact-snapshot.mjs`](hooks/compact-snapshot.mjs) | PreCompact | Run state | No — writes `.shapeup/<slug>/run-snapshot.json` before compaction | Touches nothing outside `.shapeup/` |
-| [`session-rehydrate.mjs`](hooks/session-rehydrate.mjs) | SessionStart (`compact\|resume`) | The saved run snapshot | No — injects the "trust the files, not the summary" hint when a run is in flight | Silent when no run is in flight |
+| [`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; the `substrate` block of every LIVE order (compiled, not yet ingested) | Yes — any write no live order permits: outside every `allowed`/`shared`, inside any `frozen`, or a `Write` to an `append_only` path | No-op unless an order is live; the active feature's own `.shapeup/<slug>/` run-trace is always writable. Appends denials to the local pathology log |
+| [`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 eighth `hooks.json` entry is a plain `echo` on SessionStart confirming the plugin loaded.)
+(The remaining `hooks.json` entry is a plain `echo` on SessionStart confirming the plugin loaded.)
 
 ## Data handling
 
 - **Nothing leaves the machine.** Run state lives in the gitignored `.shapeup/`; telemetry
-  is a per-machine JSONL shard under `shapeup/metrics/` that travels only if you
-  commit it. There is no phone-home of any kind.
+  is a per-machine JSONL shard under `.shapeup/metrics/`, inside that same gitignored root,
+  so it travels only if you deliberately un-ignore and commit it. There is no phone-home of
+  any kind.
 - **The safety-spine actively blocks secret reads** (`.env`, `*.pem`, `*.key`, ssh/cloud
   credentials) rather than merely not making them.
 - The installer (`scripts/install-harness.sh`) writes only into the target project
-  (`.claude/`, `.agents/`, `.codex/`, `shapeup/`, `.gitignore`) and tells you what it
+  (`.claude/`, `shapeup/`, `.gitignore`) and tells you what it
   is going to do first; the `curl | bash` form requires an explicit `--yes` for exactly that
   reason.