shapeup-sdlc 1.6.2

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

@@ -0,0 +1,20 @@
+{
+  "_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).",
+  "env": {
+    "SHAPEUP_ORCH_MODEL": "opus",
+    "SHAPEUP_EXEC_MODEL": "sonnet",
+    "SHAPEUP_EVAL_MODEL": "sonnet",
+    "SHAPEUP_QA_MODEL": "sonnet",
+    "SHAPEUP_ROUND_BUDGET": "3",
+    "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": {
+    "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/:*)"
+    ]
+  }
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "nvptuoc-marketplace",
+  "owner": {
+    "name": "Liberty Nguyen",
+    "email": "nguyenvanphituoc.developer@gmail.com"
+  },
+  "description": "ShapeUp SDLC plugins for Claude Code.",
+  "plugins": [
+    {
+      "name": "shapeup-sdlc-plugin",
+      "source": ".",
+      "description": "Shape Up SDLC harness: shaping → intake → orient → scope-mapping → build → evaluate → QA, orchestrated by a tech-lead.",
+      "license": "MIT"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "shapeup-sdlc-plugin",
+  "displayName": "ShapeUp SDLC Plugin",
+  "version": "1.6.2",
+  "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",
+    "email": "nguyenvanphituoc.developer@gmail.com"
+  },
+  "homepage": "https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin",
+  "repository": "https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "tooling"
+  ]
+}

package/.env.shapeup.example

@@ -0,0 +1,14 @@
+# Tier C template (design spec addendum §F.2). Copy to .env.shapeup.local and fill in real
+# values — that file is gitignored and never committed. GATE L0 validates the merged config
+# against this template's key set and fails fast with a per-key report if something required
+# is missing.
+#
+# File AND keys are SHAPEUP_-namespaced on purpose: the harness's own config must never be
+# confused with, or collide with, the target project's own .env / .env.local (which may
+# already exist and already own DATABASE_URL, API keys, etc. for the app itself).
+#
+# Used by the T0 mechanical layer's DB probe (each scope contract's optional `db_probe`
+# command, design spec §3.5) — set whatever connection string that probe command actually
+# needs. Leave a key blank/absent if no scope in this project declares a db_probe.
+
+SHAPEUP_T0_DATABASE_URL=

package/AGENTS.md

@@ -0,0 +1,133 @@
+<!-- HARNESS_START -->
+# Shape Up SDLC Local Harness
+
+This project is scaffolded with the Shape Up SDLC Harness for coding agents.
+
+## mechanism instruction
+
+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.
+
+### 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`
+
+### Phase 2 — Betting (PO governance, no skill)
+- PO decides at the Betting Table; rejected pitches loop back to raw idea.
+
+### Phase 3 — Building (orchestrated by `/tech-lead`)
+| 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 |
+
+✦ = 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`.
+
+### 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).
+
+### 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 ★.
+
+### Architectural Invariants
+- **Single judge** — verdict belongs to `spec-evaluator`; QA has no verdict and 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.
+
+## 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
+<!-- HARNESS_END -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OS Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# ShapeUp SDLC
+
+**Shape Up for coding agents — with gates the agent can't talk its way past.**
+
+[![CI](https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
+![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-6f42c1)
+
+Your agent says it's done. It isn't. This is a [Claude Code](https://code.claude.com) plugin
+that runs a full Shape Up lifecycle — idea → pitch → build → evaluate → ship — where the
+important rules are enforced by the runtime instead of asked for in a prompt.
+
+The ceremony is right-sized: `/ship` runs the full gated pipeline for real features, and
+`/ship --tiny` runs a two-gate lane (orient → build → smoke-test → done) for the one-file
+fixes where the gates would have nothing to say.
+
+<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">
+</p>
+
+<p align="center"><sub>
+The denial 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>
+
+## What it does to your agent
+
+Every framework in this category answers *"the agent ignored the spec"* with better prose.
+This one answers it with a runtime. Three things are true of a run here that are not true of a
+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.
+→ *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
+runs over unfinished tasks rather than denying it. The board is local to the machine running the
+harness — see [ADR-0001](docs/design/adr/0001-consumer-file-organization.md).)
+
+**2. Progress is measured, not claimed.** A scope counts as built only when `t0-verify` runs
+its fixtures, a DB probe, and the seesaw, and writes an artifact to disk. The evaluator must
+cite that artifact and re-hashes it itself; hill phase is derived from those facts, so no
+worker can self-report confidence.
+→ *Prevents: "done" asserted with nothing behind it.*
+
+**3. Parallel work can't corrupt shared state.** Each scope gets a write-whitelist of files
+enforced by a hook, and one script performs every board/ledger/verdict write.
+→ *Prevents: two parallel executors both rewriting the board, and one's completions vanishing.*
+
+Under the hood this rests on a typed worker envelope and a single-writer state layer. Those
+are load-bearing plumbing, and you should not have to think about them to use the harness —
+they are documented for [contributors](CONTRIBUTING.md), not for users.
+
+> ### Just want the gate?
+>
+> The enforcement layer ships separately as the **[Anti-Lying Kit](plugins/anti-lying-kit/)** —
+> three hooks, no methodology, installable *alongside* spec-kit, OpenSpec, or your own
+> `tasks.md`. You should not have to adopt Shape Up to stop your agent claiming done.
+>
+> ```
+> /plugin install anti-lying-kit@nvptuoc-marketplace
+> ```
+
+## Quickstart
+
+```
+/plugin marketplace add nguyenvanphituoc/shapeup-sdlc-plugin
+/plugin install shapeup-sdlc-plugin@nvptuoc-marketplace
+/ship "add dark mode to the settings screen"
+```
+
+`/ship` walks the whole lifecycle and pauses at each gate for you. That's the whole quickstart.
+
+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
+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
+**[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.
+
+## Glossary
+
+This harness has its own vocabulary. Here is all of it, in plain English — you can read the
+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. |
+| **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. |
+| **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. |
+| **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. |
+
+A longer version, including the internals, is in [docs/glossary.md](docs/glossary.md).
+
+## The workflow
+
+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;
+```
+
+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
+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.
+
+## What's included
+
+### Skills
+
+| Phase | Skill | Version | What it does |
+|-------|-------|---------|--------------|
+| Shaping (1–4) | `shapeup` | — | Frame the problem, breadboard affordances, spike risks, write the pitch. Sub-commands: `full`, `shaping`, `spike`, `breadboarding`, `framing-doc`, `kickoff-doc`, `breadboard-reflection`. |
+| Intake (GATE L0) | `translator` | — | Normalizes non-English intake (pitch/PRD/transcript) to faithful English before planning. The harness is English-only downstream. |
+| Orient (7) | `orient` | — | Builder-led recon: reads the code, spikes the single riskiest area, emits a code-surface map, spike findings, discovered-task seed, and a hill signal. Writes no production code. |
+| Wire (GATE L1a.5) | `solution-architect` | v1.1 | Sole writer of the committed wiring map (`wiring-map.md`): per-UC engine → integration seam → entry-point call site → player-visible affordance, resolved against `project-profile.md`. Front-loads the integration seam so no engine ships orphaned; the reachability input `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. |
+| 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. |
+
+### Commands
+
+`/ship` runs the whole lifecycle; the phase commands run one step each, so the pipeline is
+learnable from `/`-completion alone.
+
+| Command | Phase | Description |
+|---------|-------|-------------|
+| `/ship` | all | Run the full harness on a pitch (interactive gates by default; `--auto`, `--unattended`). |
+| `/shape` | 1 | Shape a raw idea into a pitch: boundaries → breadboard → spike → `pitch.md`. |
+| `/orient` | 7 | Builder-led recon; spikes the riskiest area, writes no production code. |
+| `/wire` | L1a.5 | Write the wiring map — engine → seam → entry-point call site, per use case. |
+| `/scopes` | 8 | Spec tree + board (`ba-pitch-analyzer`), then scope contracts (`scope-architect`). |
+| `/build` | 9 | Implement one task's acceptance criteria exactly. |
+| `/eval` | L3 | The single judge. Round mode is hook-gated — see the demo above. |
+| `/qa` | post-PASS | Exploratory edge hunt; findings never block ship. |
+| `/hammer` | H | Must-have census, baseline comparison, cut list + ship verdict. |
+| `/retro` | post-L4 | File ship-gate feedback into the per-skill knowledge base. |
+
+### Agents
+
+| Agent | Description |
+|-------|-------------|
+| `reviewer` | Independent correctness/security code reviewer (returns findings, never edits). |
+
+### Hooks
+
+Nine Node hooks. What each one reads and what it can deny:
+
+- `SessionStart` — prints a load confirmation so you know the plugin is active; on
+  `startup|compact|resume|clear`, `hooks/session-rehydrate.mjs` additionally injects the mid-run
+  `RunSnapshot` hint ("trust the files, not the summary") when a harness run is in flight. On a
+  cold `startup` it leads with the stronger sentence — *a run is already open; resume it, do not
+  re-open it* — because that is the failure a fresh session actually makes. Silent when no run is
+  in flight, which is the ordinary case.
+- `PreToolUse` (matcher `Skill`) — **`hooks/gate-l2.mjs` hard-blocks the once-per-round EVAL
+  delegation while the task board isn't fully green.** This is the gate in the demo above.
+- `PreToolUse` (matcher `Skill`) — **`hooks/gate-intake.mjs` denies a `tech-lead` dispatch that
+  carries no pitch, no spec folder, and no requirement text.** Measured on the SDD harness
+  benchmark: when the requirement text was dropped on the hand-off and only a flag survived, the
+  run printed the gate list, built nothing, and scored 29% against a hidden acceptance suite while
+  looking like a success (n=3, zero variance). An orchestrator with no spec now fails loudly
+  instead of narrating.
+- `PreToolUse` (matcher `Skill`) — **`hooks/gate-deadline.mjs` denies a `task-executor` dispatch
+  once the run's opt-in wall-clock budget is spent**, routing to GATE H instead. `spec-evaluator`,
+  `scope-hammer`, `qa-edge-hunter` and `advisor-protocol` stay reachable — a run past its deadline
+  must still be able to judge, hammer and close. Off unless a budget is configured.
+- `PreToolUse` (matcher `Bash|Read|Write|Edit|MultiEdit`) — `hooks/safety-spine.mjs` denies
+  destructive commands (`rm -rf` on unrecoverable targets, force-push/push-to-main,
+  `git reset --hard`, `DROP TABLE`) and secret-file reads. Machine guard, not pipeline guard;
+  escape hatch is the human-authored `.shapeup/safety-overrides.json`.
+- `PreToolUse` (matcher `Edit|Write|MultiEdit`) — `hooks/sandbox-guard.mjs` blocks writes
+  outside the active scope's substrate whitelist (no-op unless scope contracts exist).
+- `PreToolUse` (matcher `Skill|Agent`) — `skills/tech-lead/scripts/validate-envelope.mjs`
+  denies any worker dispatch whose order file is missing or schema-invalid.
+- `Stop` — **`hooks/gate-zerowork.mjs` blocks a session that dispatched the orchestrator and
+  left no run receipt.** The one blocking `Stop` hook, and the narrowest: its predicate is
+  mechanical — orchestrator dispatched AND no `.shapeup/<slug>/receipt.json` — so it never
+  judges quality, it reports that no work exists to judge. It exists because the benchmark caught
+  this harness describing its own pipeline instead of running it (Haiku 4.5, n=5, zero variance,
+  29% acceptance) while both existing guards structurally could not see it: one is scoped to an
+  active run, and a run that never started leaves no files; the other matches past-tense
+  completion claims, and narration is future-tense. Fails open on everything ambiguous, and
+  `stop_hook_active` caps it at one block per stop chain.
+- `Stop` — two **advisory, never-blocking** hooks (`hooks/anti-rationalization.mjs` flags
+  completion claims the board/T0 facts contradict — including a future-tense promise left as the
+  session's last word; `hooks/slop-cleaner.mjs` flags TODO/`console.log`/commented-out-code
+  leftovers in the session's diff). They emit at most a `systemMessage` — "QA is a level-up, not
+  a gate."
+- `PreCompact` — `hooks/compact-snapshot.mjs` persists the mid-run `RunSnapshot` to
+  `.shapeup/<slug>/run-snapshot.json` before the conversation is compacted.
+
+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
+it never does — as claims written to be falsified, with the grep to check them.
+
+> A project-local `/gap-scan` command (navigator→driver gap tracking) lives under
+> `.claude/commands/` for this repo's own use. It is **not** bundled in the distributed
+> plugin.
+
+## Architecture invariants
+
+These hold across the harness and are the reason it stays predictable:
+
+- **One judge only** — the verdict belongs to `spec-evaluator`. QA has no verdict and no score.
+- **EVAL exactly once per round** — QA is not a second evaluation pass; it runs after PASS, outside the loop.
+- **Ledger is the single source of truth** — orient, task-executor, and QA all write to `discovery/ledger.md`.
+- **QA is a level-up, not a gate** — `--no-qa` skips it; the circuit breaker outranks the hunter; findings default to `~`.
+- **Role separation** — evaluator grades, task-executor fixes, QA discovers; no one does another's job.
+- **Three-level circuit breaker** — an outer `round_budget` (build+eval cycles) nests an inner
+  per-scope `attempt_budget` (T0 attempts); an exhausted scope queues a GATE H proposal instead
+  of blocking the round. An opt-in third breaker bounds the **wall clock**, because the other two
+  count events and neither can notice a single round running for half an hour — tripping it routes
+  to GATE H, so a run out of time ships what is green instead of being killed and shipping nothing.
+- **Hill phase is mechanical, never self-reported** — derived only from T0/T1/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
+  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.
+
+## Known rough edges
+
+Stated plainly, because you will hit them:
+
+- **The `--tiny` lane is young.** It right-sizes the ceremony (two gates instead of eight) but
+  keeps the T0 verification floor; its fit-check heuristics will need tuning against real use.
+- **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.
+
+Contributions to any of these are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Develop
+
+```bash
+npm test                             # structural tests
+npm run demo                         # re-record the demo asset from the real hook
+claude plugin validate . --strict    # the same check CI runs
+claude --plugin-dir .                # load this working copy without installing
+```
+
+## Layout
+
+```
+.claude-plugin/
+  plugin.json         # plugin manifest
+  marketplace.json    # marketplace listing (points at this repo)
+skills/<name>/SKILL.md # the 13 harness skills (+ references/ and assets/)
+skills/tech-lead/scripts|schemas/        # orchestrator pipeline: init-run, gate-answers,
+                                         #   budget-check, compile-order, ingest-result, validate-envelope,
+                                         #   t0-verify, trace-lint, aegis-digest, run-snapshot,
+                                         #   stats + envelope and gate-answer schemas
+skills/ba-pitch-analyzer/scripts/        # planner mechanics: board-derive, spec-lint
+skills/spec-evaluator/scripts/           # verdict-ledger (reference impl of the flip/confidence grammar)
+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)
+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
+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
+```
+
+## Release
+
+1. Bump `version` in `.claude-plugin/plugin.json`.
+2. Update `CHANGELOG.md`.
+3. Tag and push: `git tag v1.3.1 && git push origin v1.3.1`.
+
+The release workflow validates the plugin, checks the tag matches the manifest version,
+and publishes a GitHub release.
+
+## Credits
+
+- The `shapeup` skill (shaping, breadboarding, spike, framing/kickoff docs) is inspired by and
+  reuses material from [rjs/shaping-skills](https://github.com/rjs/shaping-skills) by Ryan Singer.
+- The Shape Up methodology is from [*Shape Up*](https://basecamp.com/shapeup) by Basecamp.
+
+This project carries Shape Up's *building* apparatus — appetite, hill charts, the scope hammer,
+"QA is for the edges", comparing against baseline rather than the ideal — into a mechanized
+loop. The shaping half is Ryan Singer's work, gratefully used.
+
+## License
+
+MIT — see [LICENSE](LICENSE).