shapeup-sdlc 1.7.0 → 3.0.1

package/.claude/settings.local.example.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Tier C template (design spec addendum §F.2). Copy to .claude/settings.local.json and edit — that file is gitignored and merges over the committed .claude/settings.json team defaults. Every key under env is optional; omit what you don't want to override. GATE L0.5/L0.8 resolves: /ship flags > settings.local.json (this file) > settings.json (team) > skill-shipped defaults. Model keys degrade one tier down (never hard-fail) when unavailable on your plan (R2). Budget keys are the two-level circuit breaker (DD-9): round_budget is outer (build+eval cycles), attempt_budget is inner (per-scope T0 attempts).",
+  "_readme": "Tier C template (design spec addendum \u00a7F.2). Copy to .claude/settings.local.json and edit \u2014 that file is gitignored and merges over the committed .claude/settings.json team defaults. Every key under env is optional; omit what you don't want to override. GATE L0.5/L0.8 resolves: /ship flags > settings.local.json (this file) > settings.json (team) > skill-shipped defaults. Model keys degrade one tier down (never hard-fail) when unavailable on your plan (R2). Budget keys are the two-level circuit breaker (DD-9): round_budget is outer (build+eval cycles), attempt_budget is inner (per-scope T0 attempts).",
   "env": {
     "SHAPEUP_ORCH_MODEL": "opus",
     "SHAPEUP_EXEC_MODEL": "sonnet",
@@ -9,12 +9,12 @@
     "SHAPEUP_ATTEMPT_BUDGET": "5",
     "SHAPEUP_DIGESTER_MODEL": "script"
   },
-  "_permissions_readme": "The harness's pipeline scripts ship with the plugin and therefore live OUTSIDE your project. Under any permission mode short of bypassPermissions, running a script from outside the working directory needs approval — once per session interactively, and never in a headless run, where nobody is there to grant it. `npx shapeup-sdlc init` writes this block for you; it is reproduced here so you can see exactly what is being pre-approved. Scope is the harness's own deterministic, dependency-free, network-free scripts and nothing else — not a general Bash(node:*).",
+  "_permissions_readme": "The harness kernel ships with the plugin and therefore lives OUTSIDE your project. Under any permission mode short of bypassPermissions, running a script from outside the working directory needs approval \u2014 once per session interactively, and never in a headless run, where nobody is there to grant it. `npx shapeup-sdlc init` writes this block for you; it is reproduced here so you can see exactly what is being pre-approved. TWO Bash rules, because the trailing ` *` form requires at least one argument and the bare form is what covers a no-flag invocation. The leading `*` spans the install root, which differs between a marketplace install (a version-stamped cache directory) and a `--plugin-dir` checkout \u2014 that wildcard is what keeps the grant working across a plugin upgrade instead of silently expiring. Scope is one dependency-free, network-free script and nothing else \u2014 not a general Bash(node:*). The third entry, \"Workflow\", is what lets the tech-lead launch its run script without approving each launch; it is UNSCOPED (it authorises every dynamic workflow script in the project, not only this plugin's), so `npx shapeup-sdlc init --no-native-workflow` declines it and the harness stays fully usable interactively. This list is GENERATED by bin/lib/grant.mjs and verified by execution rather than by string comparison: npm run test:grant.",
   "permissions": {
     "allow": [
-      "Bash(node ${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/:*)",
-      "Bash(node ${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/:*)",
-      "Bash(node ${CLAUDE_PLUGIN_ROOT}/skills/spec-evaluator/scripts/:*)"
+      "Bash(node \"*/kernel/harness.mjs\" *)",
+      "Bash(node \"*/kernel/harness.mjs\")",
+      "Workflow"
     ]
   }
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "1.7.0",
+  "version": "3.0.1",
   "description": "Shape Up SDLC harness for Claude Code: shaping, intake, orient, scope-mapping, building (T0-verified, sandboxed, scope-contracted), evaluation and QA skills orchestrated by a tech-lead.",
   "author": {
     "name": "Liberty Nguyen",

package/AGENTS.md

@@ -5,9 +5,13 @@
 
 A three-phase Shape Up loop orchestrated by `/tech-lead`. Invariants live in the runtime, not this file — expect hook denials, not arguments.
 
+Skills and commands are named short throughout this file; every one of them resolves only under the plugin's namespace — `Skill(shapeup-sdlc-plugin:orient)`, `/shapeup-sdlc-plugin:ship`. A bare name is not a typo you get a warning for: an unknown skill name is rejected upstream of the hook layer, so the dispatch fires no hook, leaves no decision row, and is answered by improvisation.
+
 - Hook-denied: dispatching a worker without a schema-valid WorkOrder, writing outside the scope's substrate, stopping a run with no receipt (the run's first act writes one).
+- Attested, not assumed: a dispatch leaves a receipt naming the skill that ran, and ingest refuses an orchestrated result that has none. A dispatch that fails is answered by the sub-agent improvising the craft, which every other check accepts — so "the artifact exists" is not evidence that the shipped skill produced it. `--no-receipt-check` is the way through when the receipt channel itself fails.
 - GATE L2 is advisory — warns when EVAL runs over unfinished tasks, permits the call (per-machine board, operator asked; ADR-0001) — a signal, not a bug.
 - Sign-off is a file: each gate resolves from the answer set (`ci`/`guarded`/`interactive`) — cross, stop for the PO, or abort; the decision's source is ledgered.
+- **Your scope cut decides your concurrency, not the dial.** Two scopes that both declare a write to one path never build at the same time: `shared` substrate is the sanctioned escape from disjointness, and an edit is read-modify-write, so concurrent writers silently drop each other's work. An entry point listed as writable by five scopes therefore builds five scopes one at a time whatever `--parallel-scopes` says. The run states the ceiling its contracts actually permit before dispatching anything, as a BUILD-order line — a peak below that ceiling is a dispatch problem, a ceiling below the dial is a scope-cut problem, and only the second is fixable by re-cutting. The fix is a cut where exactly one scope owns each entry point. Note the ceiling is narrated, not gated: it does not travel in the ⏸ L1b block, so an unattended run carries it only in its log.
 - The build+eval loop breaks only three ways ✦: EVAL PASS → QA → Ship; outer `round_budget` exhausted; opt-in `wall_clock_budget_s` tripped (the wall-clock axis event counters miss). Budget trips route to GATE H — ship what's green, never kill the run from outside. A scope exhausting its per-scope `attempt_budget` (T0 attempts) queues a GATE H proposal, never blocks the round.
 
 ### Phase 1 — Shaping (`/shapeup`)
@@ -22,17 +26,19 @@ Betting Table: PO decides; rejected pitches loop back to raw idea.
 ### Phase 3 — Building
 | Step | Gate | Action |
 |------|------|--------|
-| Kick-off | ⏸ **L0** — Intake & Config (L0.8 model/budget matrix) | `/translator` if non-English |
+| Kick-off | ⏸ **L0** — Intake & Config (L0.8 model/budget matrix) + worker roster ✧ | `/translator` if non-English |
 | Orient (Scout) | ⏸ **L1a** — Orient Review | `/orient` |
 | Analyze | — (reviewed at L1b) | `/ba-pitch-analyzer` (`analyze`): spec tree + board (UC + Invariants + Test Surface ★); before Wire (needs its use cases) |
 | Wire | ⏸ **L1a.5** — Wiring Review ✚ | `/solution-architect` (`wire`): sole writer of committed `wiring-map.md` — per-UC engine → seam → entry-point call site → affordance, per `project-profile.md` |
 | Map Scopes | ⏸ **L1b** — Board Review (+ substrate disjointness lint) | `/scope-architect` (scope contracts ✦ — sole writer); traceability oracle advisory ✚ |
-| Build Vertically | ⏸ **L2** — Board 100% ✅ + T0-green ✦ | per dispatch: compile order → `/task-executor` (--order) → ingest result; T0-verified per attempt (fixtures + DB probe + seesaw ✦), substrate-sandboxed ✦ |
+| Build Vertically | ⏸ **L2** — Board 100% ✅ + T0-green ✦ | per dispatch: compile order → `/task-executor` (--order) → ingest result; T0-verified per attempt (fixtures + DB probe + seesaw ✦), substrate-sandboxed ✦. Scopes build **concurrently** ✦ — `--parallel-scopes N` caps it (default 4), a scope is released the moment its own dependencies are green, and a scope green in this round is skipped rather than rebuilt |
 | EVAL (once per round) | ⏸ **L3** — Verdict | `/spec-evaluator` (--order): spec- + test-surface-conformance ★, T0 citation ✦; refuted boxes/verdict applied by ingest |
 | FAIL → round r+1 | — | regression rule ★: bugs + full Test Surface of touched UC |
 
 ✦ = requires scope contracts (`shapeup/<slug>/scopes/*.md`); ✚ = requires the spine artifacts (`requirements.md`, `wiring-map.md`, `project-profile.md`). Traceability stays advisory until `covers:` is populated. Absent artifact ⇒ arm skipped (non-regression).
 
+✧ **Two refusals, and they answer different questions.** Opening a run refuses outright when the worker skills are not on disk — the roster comes from the schema that defines it, so it cannot drift from a hand-kept list. That alone passes green on the two states that actually happen (installed but disabled, or a different version loaded), so the run's first act is one live canary dispatch, and the evidence is the hook layer's rather than the sub-agent's account of it. A run that cannot reach its workers stops before it spends anything, instead of reporting phases complete while none of the shipped craft was applied.
+
 
 ### QA Edge Hunt (`/qa-edge-hunter`, post-PASS, pre-ship)
 **Q0** Preflight → **Q1** Charter (6 lenses − EVAL-covered) → **Hunt** (repro required, findings `~` → ledger) → report (no verdict, no score). Skip with `--no-qa`.
@@ -58,8 +64,16 @@ Everything discovered funnels into `.shapeup/<slug>/discovery/ledger.md` (Orient
 ## Setup & Execution
 
 - Orders/results live in `.shapeup/<slug>/orders|results/`; the envelope schemas ship inside the tech-lead skill.
-- The plugin's run entry points need a one-time permission grant — `npx shapeup-sdlc init` writes it into `.claude/settings.json` (`permissions.allow`); without it a headless run stalls at step one.
+- The plugin's run entry points need a one-time permission grant — `npx shapeup-sdlc init` writes it into `.claude/settings.json` (`permissions.allow`); without it a headless run stalls at step one. That grant is necessary, not sufficient: it covers the run's own deterministic entry points, not the generic file edits every worker skill makes constantly, or any command a worker reaches for beyond the grant's own exact shape. A truly unattended run also needs a Claude Code permission mode that covers those (`acceptEdits` at minimum) — the plugin cannot grant that on your behalf.
 - Two storage tiers (ADR-0001): COMMITTED `shapeup/<slug>/` (shaping, spec, scopes, wiring-map, project-profile, requirements, hill, `REPORT.md` frozen at L4) vs GITIGNORED `.shapeup/` (board, orders/results, T0/eval/QA artifacts, ledgers, metrics, gate answers).
+- Every run has a `run_id` — the receipt mints it, and orders, T0 artifacts, trial rows, agent-call journal rows and hook decisions all carry it. It is the only key that separates two runs of the same feature: everything else (`order_id`, round/attempt) repeats. It is **not** a time boundary — a relaunch resumes the same run and reuses the key, so one `run_id` legitimately spans every launch after a paused gate or a kill, with hours of wall clock between them, and `orders/<id>.json` is rewritten by each. Anything measuring elapsed time reads the append-only records, never the span of a key. SHIP S.7 exports the run's records as fact tables under `.shapeup/exports/<run_id>/` before the run trace is superseded; a WorkResult carries no `run_id` and reaches it through `order_id`.
+- Every run projects a **run graph** — `.shapeup/<slug>/graph.jsonl`, append-only, written only by
+  `reduce graph`. Two families kept separate: work lineage (Run, Order, Result, Verdict, Trial,
+  GateDecision) and domain (Scope, UseCase, Requirement, Seam). It is derived from the artifacts,
+  never authored, so it can be deleted and rebuilt — and a run recorded before it existed backfills
+  on first touch. `--subgraph run` is the fast-forward as one bounded query; `--trace <node>` walks
+  a verdict back to the objective, the plan, the source, the execution record and the gate that
+  crossed it.
 - Contracts: markdown on disk, JSON on the wire; a single library reads/writes the file form.
 - Never hard-code a storage root — generated paths resolve through the shared path resolver.
 - The traceability oracle emits `.shapeup/<slug>/trace/report.json` from the spine artifacts.

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 names both unfinished tasks and records the evaluation as taken over a partial board." 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 GATE L2 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>
@@ -59,10 +59,19 @@ they are documented for [contributors](CONTRIBUTING.md), not for users.
 ```
 /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
@@ -72,6 +81,19 @@ they are documented for [contributors](CONTRIBUTING.md), not for users.
 > ```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 what the hooks do to a premature eval, a FAIL round
@@ -85,7 +107,7 @@ 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 12 skills, 10 slash commands and pipeline scripts are
+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
@@ -118,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.
 
@@ -161,8 +170,8 @@ 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, 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 `board-derive.mjs`/`spec-lint.mjs`. |
+| 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. |
@@ -174,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 |
 |---------|-------|-------------|
@@ -189,55 +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. |
 
-### Hooks
-
-Ten Node hooks in `hooks/`, plus `validate-envelope.mjs` which ships with the orchestrator skill.
-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` warns when the once-per-round EVAL
-  delegation runs over an unfinished task board**, naming the offending tasks and recording a
-  `warn` row. Advisory since ADR-0001 — the board is per-machine and the operator asked for the
-  call. 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` and `qa-edge-hunter` 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
@@ -264,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.
 
@@ -275,13 +301,11 @@ 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.** The repo used to carry two evidence
-  layers — a Tier-1 activation dataset per skill, and a Day-1/Day-2 craft-and-efficacy register —
-  and both have been removed. What that cost is worth stating plainly rather than leaving to be
-  discovered: there is now 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 (Tier 0) and the functional planted-bug fixtures (Tier 2) are the
-  coverage that remains, and both are about mechanism rather than quality.
+- **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.
 
@@ -303,17 +327,15 @@ claude --plugin-dir .                # load this working copy without installing
   plugin.json         # plugin manifest
   marketplace.json    # marketplace listing (points at this repo)
 skills/<name>/SKILL.md # the 12 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/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)
-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
@@ -321,7 +343,6 @@ scripts/install-harness.sh, migrate.sh   # stable public entrypoints (fresh inst
 scripts/shapeup-sdlc/lib/                # shell libs both entrypoints source
 tools/                # repo-only: demo/
                       #   demo/record-demo.mjs (regenerates docs/assets/demo-gate.svg)
-evals/                # Tier-2 functional apparatus only: fixtures/, oracles/
 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) + adr/

package/SECURITY.md

@@ -1,45 +1,57 @@
 # Security
 
-This plugin installs **twelve hook entries (eleven Node scripts + one `echo`)**: six in a
-`PreToolUse` position, of which **five can deny a tool call**, plus 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.
+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 matched destructive command, a
-   path the active order's substrate does not permit, an invalid order file, an empty intake, a
-   spent wall-clock budget).
+   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. The same principle
-   covers `.shapeup/active-order`, the pointer `sandbox-guard` reads to decide what a worker may
-   write: 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.** Two of the three
-   `Stop`-position hooks (`anti-rationalization`, `slop-cleaner`) are advisory — at most a
-   `systemMessage`, always exit 0. The third, `gate-zerowork`, **does** return
-   `decision: "block"`, and only 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.
+   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
@@ -56,17 +68,12 @@ sitting, and reading them is the recommended review.
 |---|---|---|---|---|
 | [`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 |
-| [`gate-deadline.mjs`](hooks/gate-deadline.mjs) | PreToolUse (`Skill`) | The run's opt-in `wall_clock_budget_s` and start time | Yes — a `task-executor` dispatch once the budget is spent, routing to the ship gate instead | Never denies `spec-evaluator`, `scope-hammer` or `qa-edge-hunter`; off entirely unless a budget is configured |
-| [`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 order's `substrate` block, via `.shapeup/active-order` | Yes — any write the order does not permit: outside `allowed`/`shared`, inside `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 |
-| [`gate-l2.mjs`](hooks/gate-l2.mjs) | PreToolUse (`Skill`) | The round's task board (`.shapeup/<slug>/tasks/`) | **No** — advisory since ADR-0001. It detects a non-green board by two independent reads, names the unfinished tasks in a `systemMessage`, and permits the call | Never denies; records a `warn` row so "evaluated a partial board" stays countable |
+| [`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 |
-| [`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 (`startup\|compact\|resume\|clear`) | 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 |
 
-(The twelfth `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