shapeup-sdlc 1.6.3 → 3.0.0

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

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

package/.claude-plugin/plugin.json

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