shapeup-sdlc 1.6.3 → 1.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "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

@@ -1,133 +1,66 @@
 <!-- HARNESS_START -->
 # Shape Up SDLC Local Harness
 
-This project is scaffolded with the Shape Up SDLC Harness for coding agents.
+## Enforcement model
 
-## mechanism instruction
+A three-phase Shape Up loop orchestrated by `/tech-lead`. Invariants live in the runtime, not this file — expect hook denials, not arguments.
 
-The harness follows a **three-phase Shape Up SDLC loop** orchestrated by `/tech-lead`.
-
-**The organising idea: every invariant that matters lives in the runtime, not in a prompt.**
-Three consequences, in the order a reader should meet them:
-
-1. **Gates are enforced, not requested.** A `PreToolUse` hook
-   (`skills/tech-lead/scripts/validate-envelope.mjs`) hard-denies any worker dispatch whose
-   WorkOrder is missing or fails its schema — the malformed order never reaches a worker.
-   `hooks/sandbox-guard.mjs` denies every write outside the active scope's substrate, and
-   `hooks/gate-zerowork.mjs` blocks `Stop` on a run that left no receipt.
-   *Prevents: a worker acting on an order nobody compiled; a scope overwriting another's work.*
-   GATE L2 (`hooks/gate-l2.mjs`) is deliberately **advisory** — it reads the board from two
-   independent sources and warns when the once-per-round EVAL runs over unfinished tasks, but it
-   permits the call. The board is per-machine and the operator asked for the evaluation; see
-   `docs/design/adr/0001-consumer-file-organization.md` for why the denial was traded for a signal.
-   Sign-off itself is a file, not prose: `scripts/gate-answers.mjs` resolves each gate from a
-   schema-validated answer set (`ci` / `guarded` / `interactive`) and the orchestrator branches on
-   its exit code — 0 cross, 4 stop for the PO, 5 abort. Gates still emit their blocks and still
-   record a decision; what changes is that the decision's **source** is named in the ledger.
-   *Prevents: consent carried in a prompt paragraph, which gets paraphrased instead of acted on.*
-2. **Progress is derived, never claimed.** Hill phase comes only from T0/T1/seesaw artifacts on
-   disk, and the evaluator must cite a T0 artifact it re-hashes itself. *Prevents: a worker
-   asserting "done" with nothing behind it.*
-   And **starting** is itself a fact on disk: `scripts/init-run.mjs` writes
-   `.shapeup/<slug>/receipt.json` as the run's first tool call, so a session that dispatched
-   the orchestrator and left no receipt is blocked at `Stop` by `hooks/gate-zerowork.mjs`.
-   *Prevents: the orchestrator describing its own pipeline in future tense and stopping — measured
-   at 29% acceptance with 10 escaped defects while reading like a clean run.*
-3. **Parallel work cannot corrupt shared state.** Per-scope substrate write-whitelists are hook-
-   enforced, and exactly one script (`ingest-result.mjs`) performs every board/ledger/verdict
-   write. *Prevents: two executors rewriting the board, one's completions vanishing.*
-
-Those three rest on one piece of plumbing — the **pure-skill architecture** (v1.0). The
-orchestrator owns ALL pipeline management and talks to workers through two JSON envelopes: a
-WorkOrder in (`compile-order.mjs`, schema-validated by a `validate-envelope.mjs` PreToolUse
-hook) and a WorkResult out (applied by `ingest-result.mjs`). Worker skills contain craft only —
-zero pipeline knowledge; everything they used to write into shared files they now return as data
-(D6 closed: single-writer is mechanically true). Treat the envelope as an implementation detail:
-it is what makes 1–3 mechanically true, and it should never be the first thing a user learns.
+- 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).
+- 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.
+- 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`)
 1. Set Boundaries → `/shapeup shaping`
 2. Find the Elements → `/shapeup breadboarding`
 3. Risks & Rabbit Holes → `/shapeup spike`
-4. Write the Pitch → `/generate-pitch` → `pitch.md`
+(The completed pitch is formed by `shaping.md` + `breadboard.md`)
 
 ### Phase 2 — Betting (PO governance, no skill)
-- PO decides at the Betting Table; rejected pitches loop back to raw idea.
+Betting Table: PO decides; rejected pitches loop back to raw idea.
 
-### Phase 3 — Building (orchestrated by `/tech-lead`)
+### Phase 3 — Building
 | Step | Gate | Action |
 |------|------|--------|
 | Kick-off | ⏸ **L0** — Intake & Config (L0.8 model/budget matrix) | `/translator` if non-English |
-| Orient (Scout) | ⏸ **L1a** — Orient Review | delegate → `/orient` |
-| Wire (Reachability) | ⏸ **L1a.5** — Wiring Review ✚ | delegate → `/solution-architect` (`wire`): committed `wiring-map.md` — per-UC engine → seam → entry-point call site → affordance, against `project-profile.md` entry_point; front-loads the integration seam |
-| Map Scopes | ⏸ **L1b** — Board Review (+ substrate disjointness via `spec-lint.mjs`) | delegate → `/ba-pitch-analyzer` (spec tree + board: UC + Invariants + Test Surface ★; `coverage` op writes the `requirements.md` registry ✚) then `/scope-architect` (scope contracts ✦ — sole writer). Traceability oracle `trace-lint.mjs` runs 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 ✦), sandboxed to each scope's substrate ✦ |
-| EVAL (once per round) | ⏸ **L3** — Verdict | delegate → `/spec-evaluator` (--order; spec-conformance + test-surface-conformance ★; requires a T0 artifact citation on scoped specs ✦); refuted boxes/verdict ledger applied by ingest |
-| FAIL → fix round r+1 | — | regression rule ★: bugs + full Test Surface of touched UC |
+| 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 ✦ |
+| 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).
 
-✦ = v0.3.0 mechanisms, active only when the spec folder has scope contracts
-(`shapeup/<slug>/scopes/*.md`); non-regression on older specs.
-✚ = spine v1.3 traceability mechanisms (covers-closure + reachability), active only when the
-spine artifacts exist (`requirements.md`, `wiring-map.md`, `project-profile.md`); `trace-lint`
-ships advisory (warn-only) and is promoted to a blocking gate only once `covers:` is populated.
-Non-regression on older specs — every arm is skipped when its artifact is absent.
 
 ### 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`.
+**Q0** Preflight → **Q1** Charter (6 lenses − EVAL-covered) → **Hunt** (repro required, findings `~` → ledger) → report (no verdict, no score). Skip with `--no-qa`.
 
 ### Ship & Triage
-- **SHIP S.0 / GATE H** — delegated to `/scope-hammer`: census (QA findings + discovered ledger
-  + attempt-budget hammer proposals ✦) → baseline comparison (never vs. the ideal) → cut list;
-  TL/PO confirms, promotes only selected items.
-- ⏸ **L4** Gate — Ship Sign-off (shows QA status ★).
-- **RLHF (Coach Retro)** — Post-sprint feedback from L4 Gate is processed by `/coach`, which runs a categorization gate (GATE COACH-1 — asks the PO which skill each rule belongs to, never assumes) and files each rule under the responsible skill in `shapeup/knowledge-base/<skill>.md`. These files are **committed** (not the gitignored `.shapeup/` run-trace), so the whole team inherits them on `git pull`. The `/tech-lead` automatically invokes `/coach` when it receives human feedback during the Ship Gate. Coachable skills — each reads its own file at the top of its next run — are `/task-executor` (Phase 1), `/ba-pitch-analyzer` (Phase 1), and `/qa-edge-hunter` (Phase Q1). `/spec-evaluator` is deliberately not coachable (single-judge rule: the KB is guidance, never an invariant). Feedback whose root cause is the mechanism itself (a gate, hook, or skill-contract defect) is categorized `harness-defect` at GATE COACH-1 and filed to the committed defect register (`knowledge-base/harness-defects.md`) as a drafted raw idea for the Betting Table — read by no worker, never worker steering.
-- Post-fix: `eval --single-pass` → `qa --recheck` (only re-probes promoted items ✦).
-- Remaining `~` findings + new feedback → new raw idea (debt-free).
+- **SHIP S.0 / GATE H** — `/scope-hammer`: census (QA findings + discovered ledger + attempt-budget proposals ✦) → baseline comparison (never the ideal) → cut list; TL/PO promotes selected items only.
+- ⏸ **L4** — Ship Sign-off (shows QA status ★).
+- **Coach retro** — L4 feedback → `/coach`; GATE COACH-1 asks the PO which skill owns each rule (never assumes) → committed `shapeup/knowledge-base/<skill>.md` (team inherits on pull). Coachable: `/task-executor`, `/ba-pitch-analyzer`, `/qa-edge-hunter`; `/spec-evaluator` is not (single judge). Mechanism defects file to `knowledge-base/harness-defects.md` as Betting Table raw ideas, never worker steering.
+- Post-fix: `eval --single-pass` → remaining `~` + new feedback → new raw idea.
 
 ### Discovered Tasks
-All discovered tasks are funnelled into `.shapeup/<slug>/discovery/ledger.md` (Orient, task-executor P3.7, QA). A new invariant triggers `ba --tasks-only --from-discovered` which appends a `TS-INV-NN` row to the Test Surface ★.
+Everything discovered funnels into `.shapeup/<slug>/discovery/ledger.md` (Orient, task-executor P3.7, QA); a new invariant triggers `ba --tasks-only --from-discovered` → `TS-INV-NN` Test Surface row ★.
 
 ### Architectural Invariants
-- **Single judge** — verdict belongs to `spec-evaluator`; QA has no verdict and no score.
+- **Single judge** — verdict belongs to `spec-evaluator`; QA has no verdict, no score.
 - **EVAL exactly once per round** — QA sits after PASS, outside the loop.
-- **Ledger = single source of truth** — all discovery flows write only to their own section.
-- **QA is a level-up, not a gate** — `--no-qa` can skip it; circuit breaker outranks the Hunter.
-- **Role separation** — Evaluator grades, task-executor fixes, QA discovers; no cross-role work.
-- **Three-level circuit breaker ✦** — outer `round_budget` (build+eval cycles) nests an inner
-  per-scope `attempt_budget` (T0 attempts); an exhausted scope queues a GATE H proposal, it
-  never blocks the round. A third, opt-in `wall_clock_budget_s` breaker (`budget-check.mjs`,
-  enforced by `hooks/gate-deadline.mjs`) covers the axis the other two cannot see — both count
-  events, so neither notices a single round running for half an hour. Tripping it routes to
-  GATE H rather than killing the run: a run killed from outside ships nothing, a run that trips
-  its own breaker ships what is green.
-- **Hill phase is mechanical, never self-reported ✦** — derived only from T0/T1/seesaw facts.
-- **Envelope port (v1.0)** — every worker dispatch is WorkOrder in / WorkResult out; shared
-  state is written only by `ingest-result.mjs`; a malformed envelope is denied by hook before
-  it reaches a worker. Workers are stateless and pipeline-blind by construction.
-
-## Installed Skills
-
-- **shapeup**: Run Shape Up workflows before writing code (S1-S4, B1-B5).
-- **ba-pitch-analyzer**: The spec-analyzer — pitch → DDD spec tree + board, one craft with five order-selected operations (analyze | generate-board | reconcile | retrofit-surface | coverage); graph math and audits delegated to `board-derive.mjs`/`spec-lint.mjs`; the `coverage` op writes the SHARED requirement registry (`requirements.md`) for covers-closure; stateless pure worker.
-- **scope-architect**: Sole writer of committed scope contracts (`scopes/*.md`) — import-graph slicing by flow, write-whitelist substrates, affordance manifests, fixtures; map-scopes | remap | split-scope operations.
-- **solution-architect**: Sole writer of the committed wiring map (`wiring-map.md`) at gate L1a.5 — per-UC engine → seam → entry-point call site → player-visible affordance, resolved against `project-profile.md`; the reachability input `trace-lint.mjs` checks so no engine ships orphaned; `wire` operation; stateless pure worker.
-- **task-executor**: Implement a work order's acceptance criteria exactly — WorkOrder in, code + WorkResult out; zero-memory, substrate-sandboxed, Layer 1/2/3 UI rules; never writes boards/ledgers/run-state.
-- **spec-evaluator**: The single judge — evaluates the running app against the committed spec; verdict + refuted boxes return as data; requires a T0 artifact citation and grades UI affordance-only on scoped specs.
-- **qa-edge-hunter**: Exploratory QA hunt.
-- **translator**: Bilingual Vietnamese/English gate at intake.
-- **tech-lead**: Orchestrate runs — envelope port (compile-order → dispatch → ingest-result), two-level circuit breaker, T0/seesaw-verified build rounds, mechanical hill derivation.
-- **coach**: Ingests L4 feedback, asks the PO to categorize each rule (GATE COACH-1), and files it under the responsible skill in committed `shapeup/knowledge-base/<skill>.md` for team-shared, read-back continuous learning (RLHF).
-- **advisor-protocol**: 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.
-- **scope-hammer**: GATE H — must-have census, baseline comparison, cut list + ship verdict; handles the normal stop and both circuit-breaker triggers.
+- **Ledger = single source of truth** — every discovery flow writes only its own section.
+- **QA is a level-up, not a gate** — `--no-qa` skips it; circuit breaker outranks the Hunter.
+- **Role separation** — Evaluator grades, task-executor fixes, QA discovers.
+- **Hill phase is mechanical ✦** — derived only from T0/T1/seesaw artifacts, never self-reported; the evaluator cites a T0 artifact it re-hashes itself.
+- **Envelope port (v1.0)** — every dispatch is WorkOrder in / WorkResult out; shared state has exactly one writer (the ingest step); malformed envelopes are hook-denied. Workers: stateless, craft-only, pipeline-blind.
 
 ## Setup & Execution
 
-- Envelope schemas ship inside the orchestrator skill: \`skills/tech-lead/schemas/\`; the pipeline scripts live beside their owning skill (\`skills/tech-lead/scripts/\`, \`skills/ba-pitch-analyzer/scripts/\`); orders/results live in \`.shapeup/<slug>/orders|results/\`
-- **Run entry points** — \`init-run.mjs\` (GATE L0.1, opens the run and writes the receipt), \`gate-answers.mjs\` (resolves a gate from the answer set), \`budget-check.mjs\` (the deadline breaker). Because these ship WITH the plugin they live outside your project, so they need a one-time permission grant; \`npx shapeup-sdlc init\` writes it into \`.claude/settings.json\` (\`permissions.allow\`). Without it a headless run cannot take its first step — measured, 26 approval denials in one session.
-- **Central domain registry** — \`skills/tech-lead/schemas/domain.schema.json\` defines every cross-boundary record type and payload field ONCE (annotated with tier/location/writer/readers, the \`x-erd\` relationship map, and the \`x-payload-by-worker\` table); the envelope schemas \`$ref\` it and no skill defines its own cross-boundary field
-- **Two storage tiers (ADR-0001) — prose is the team's, structured data is the machine's.** COMMITTED \`shapeup/<slug>/\`: \`shaping/\`, \`spec/\`, \`scopes/*.md\`, \`wiring-map.md\`, \`project-profile.md\`, \`requirements.md\`, \`hill/*.yml\`, and \`REPORT.md\` (frozen once at GATE L4 — the only run evidence a teammate sees). GITIGNORED \`.shapeup/\`: the board, orders/results, \`t0/\`, \`evaluation/\`, \`qa/\`, \`working/\`, \`round-ledger.md\`, \`metrics/\`, \`gate-answers.json\`, \`safety-overrides.json\`, \`decisions.jsonl\`
-- The three contracts are MARKDOWN on disk and JSON on the wire: frontmatter for scalars and \`[a, b]\` lists, a markdown table for the one array-of-objects field. \`skills/tech-lead/scripts/lib/contract-md.mjs\` is the only reader/writer of the file form; the envelope is unchanged
-- Every generated path resolves through \`skills/tech-lead/scripts/lib/paths.mjs\` — never hard-code a storage root (structural test #45 enforces this)
-- **Traceability spine (v1.3)** — the covers-closure + reachability oracle \`skills/tech-lead/scripts/trace-lint.mjs\` reads three committed SHARED artifacts: the requirement registry \`shapeup/<slug>/requirements.md\` (RequirementClause rows, written by \`ba-pitch-analyzer coverage\`), the wiring map \`shapeup/<slug>/wiring-map.md\` (written by \`solution-architect wire\`), and \`shapeup/<slug>/project-profile.md\` (archetype + entry_point, written by \`tech-lead\` at L0). It emits the LOCAL run-trace \`.shapeup/<slug>/trace/report.json\`; ships advisory, promoted to a gate only once \`covers:\` is populated
+- 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.
+- 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).
+- 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.
 <!-- HARNESS_END -->

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: 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">
 </p>
 
 <p align="center"><sub>
-The denial text above is <b>verbatim stdout</b> from <code>hooks/gate-l2.mjs</code> —
+The GATE L2 text above is <b>verbatim stdout</b> from <code>hooks/gate-l2.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,16 +54,6 @@ 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
 
 ```
@@ -74,32 +64,32 @@ they are documented for [contributors](CONTRIBUTING.md), not for users.
 
 `/ship` walks the whole lifecycle and pauses at each gate for you. That's the whole quickstart.
 
+> **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
+> ```
+
 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 pipeline scripts 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 +98,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. |
@@ -172,12 +162,11 @@ every arm is skipped when its artifact is absent, so older specs are unaffected.
 | 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. |
+| 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`. |
+| 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. |
@@ -200,15 +189,10 @@ 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:
+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
@@ -216,8 +200,10 @@ Nine Node hooks. What each one reads and what it can deny:
   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-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
@@ -226,7 +212,7 @@ Nine Node hooks. What each one reads and what it can deny:
   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
+  `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,
@@ -289,14 +275,15 @@ 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.** 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.
+- **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,7 +302,7 @@ 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/<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,
@@ -323,29 +310,35 @@ skills/tech-lead/scripts|schemas/        # orchestrator pipeline: init-run, gate
 skills/ba-pitch-analyzer/scripts/        # planner mechanics: board-derive, spec-lint
 skills/spec-evaluator/scripts/           # verdict-ledger (reference impl of the flip/confidence grammar)
 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)
+                      #   + 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)
+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)
-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,9 +1,9 @@
 # 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 **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.
 
 ## Reporting a vulnerability
 
@@ -25,14 +25,25 @@ injection path through skill files. Please do not test against machines you don'
    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 the active order's substrate does not permit, an invalid order file, an empty intake, a
+   spent wall-clock budget).
 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`, 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.
+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 +55,29 @@ 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 |
+| [`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 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 |
+| [`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 |
+| [`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 (`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 |
+| [`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 eighth `hooks.json` entry is a plain `echo` on SessionStart confirming the plugin loaded.)
+(The twelfth `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.