shapeup-sdlc 3.18.2 → 4.0.0

package/skills/building/resources/orders.md

@@ -0,0 +1,69 @@
+# Orders — what you write before every dispatch
+
+An order is a JSON file at `.shapeup/<slug>/orders/<stem>.json`. It is checked against the order schema when the
+dispatch leaves, and the write fence reads its `substrate` for as long as it has no result. Write it by copying the
+template for the operation and filling the bracketed fields from the files named in the last column.
+
+## The envelope — the same for every operation
+
+```json
+{
+  "schema_version": 1,
+  "order_id": "<slug>/<stem>",
+  "kernel": "<absolute path of this plugin copy's kernel entry point>",
+  "run_id": "<run_id from .shapeup/<slug>/receipt.json>",
+  "compiled_at": "<any ISO time; `order open` replaces it with the real one>",
+  "worker": "<orient | task-executor | spec-evaluator | qa-edge-hunter | building>",
+  "mode": "orchestrated",
+  "operation": "<orient | execute | fix | evaluate | hunt | plan>",
+  "interaction": { "pause_gates": false },
+  "substrate": { },
+  "payload": { }
+}
+```
+
+`compiled_at` is not yours to get right: `order open` overwrites it with the clock, because the fence compares it with the result's age and a time typed by hand that runs ahead of the clock keeps the order live after its worker returned. `kernel` is the absolute path, never a variable: a worker runs it as a command, and a command that spells it through a
+variable is refused in a headless session. A `plan` order takes `"worker": "building"` and `"mode": "standalone"` —
+no sub-agent answers it, it only opens the fence.
+
+The stem is the file name without `.json`: `orient`, `plan-<step>`, `<scope>-r<R>-a<A>`, `evaluate-r<R>`, `hunt`. The
+order's own `order_id` is `<slug>/<stem>`, and the result is written to `results/<stem>.json`. **An order with no result is
+live**, and a live order keeps its substrate in force — so a worker that never answers stays fenced until the run is
+re-opened with `--force` or the result lands.
+
+## Substrate per operation
+
+`allowed` is what the worker may write; `shared` is the sanctioned escape for a path two scopes declare;
+`frozen` outranks everything; `own` is the worker's own result and bookkeeping, and only the dispatch that took the order may write it.
+
+| Operation | `allowed` | `frozen` | `own` |
+|---|---|---|---|
+| `orient` | `.shapeup/<slug>/orient/**` | `shapeup/<slug>/spec/**` | `.shapeup/<slug>/results/orient.json` |
+| `execute` / `fix` | the scope contract's `allowed_file_substrate` plus `.shapeup/<slug>/spikes/**`; `shared` = its `shared_substrate` | `.shapeup/<slug>/**` | `results/<stem>.json`, `.shapeup/<slug>/tasks/TASK-*.md`, `.shapeup/<slug>/discovery/**`, `.shapeup/<slug>/spikes/**` |
+| `evaluate` | none | `shapeup/<slug>/spec/**`, `.shapeup/<slug>/**` | `.shapeup/<slug>/evaluation/**`, `results/evaluate-r<R>.json` |
+| `hunt` | none | `shapeup/<slug>/spec/**`, `.shapeup/<slug>/**` | `.shapeup/<slug>/qa/**`, `results/hunt.json` |
+| `plan` (`requirements`) | `shapeup/<slug>/requirements.md` | the spec's domain model, use-case Steps, contracts, UX file; the run's intake, orders, results, receipts and T0 verdicts | `results/plan-requirements.json` |
+| `plan` (`spec`) | `shapeup/<slug>/spec/**`, `.shapeup/<slug>/tasks/**`, `.shapeup/<slug>/working/**` | the intake, project profile, orders, results, receipts, T0 verdicts | `results/plan-spec.json` |
+| `plan` (`wire`) | `shapeup/<slug>/wiring-map.md` | as `requirements`, plus `shapeup/<slug>/scopes/**` | `results/plan-wire.json` |
+| `plan` (`scopes`) | `shapeup/<slug>/scopes/*.md`, `shapeup/<slug>/scope-board.md` | as `requirements`, plus `.shapeup/<slug>/tasks/**` | `results/plan-scopes.json` |
+
+**Answer an order before you write the next one.** An order with no result is live, and a live `plan` order freezes `orders/**` — so writing the next order while the last is unanswered is refused by the fence. Write the result first, then the next order.
+
+A needed file outside the table is the PO's decision, not yours: widen a scope's substrate by amending its contract, then write the order again.
+Do not widen an order to make a worker's escalation go away.
+
+## Payload per operation
+
+Pass a path wherever a path will do; a worker reads files, and an embedded copy goes stale.
+
+| Operation | Payload | Where each field comes from |
+|---|---|---|
+| `orient` | `pitch`, `feature`, `spec_folder`, `kb_rules_path` | the intake path; the slug; the launch record's spec folder; `shapeup/knowledge-base/orient.md` if it exists |
+| `execute` | `scope_contract` (path of `<spec>scopes/<id>.md`), `tasks` (`[{id, body_path}]` for the scope's tasks), `verify.test_cmd`, `kb_rules_path`, `round` | the scope file; the board's tasks whose `scope_id` is the scope; the contract's `e2e_verification_fixtures`; `shapeup/knowledge-base/task-executor.md` |
+| `fix` | as `execute`, plus `bugs`, `digested_errors`, `trial_history` | the last verdict's FAIL criteria addressed to this scope's files; the failing lines of the last T0 verdict; the scope's rows in `t0/trials.jsonl`, oldest first, at most 8 |
+| `evaluate` | `spec_folder`, `feature`, `dimensions`, `run_cmd`, `t0_artifacts`, `build_gate`, `round` | the spec path; the slug; the dimensions the PO named at L0, else the set the spec calls for (a Test Surface turns on test-surface-conformance, Invariants turn on completeness); the project profile's run command; the paths of each scope's latest `t0/verdicts/*.json` for the round; the note you wrote from your own build and launch this round (`.shapeup/<slug>/build/r<R>.md`: each step's command, exit code and output tail), omitted when you ran none |
+| `hunt` | `feature`, `spec_folder`, `eval_report`, `app_url`, `round`, `kb_rules_path` | the slug; the spec path; the PASS evaluation report; the running app, or `null` for a deliverable that is not served |
+| `plan` | `step`, `feature`, `spec_folder`, `kb_rules_paths` | the substep; the slug; the spec path; the knowledge-base files `resources/guidance.md` lists for planning |
+
+A scope that did not go green in the round has its test-surface rows graded FAIL: name it in an `evaluate` order's `scopes_without_t0` rather than leaving the judge to find the gap.
+A criterion the last verdict graded FAIL reaches the next round whether or not the judge filed a bug for it — a FAIL verdict with nothing to fix is how a run stalls.

package/skills/{ba-pitch-analyzer/references → building/resources/plan-references}/doc-schemas.md

@@ -59,7 +59,7 @@ When upgrading `lite → standard`:
 - `ux-behavior.md` stays authoritative for screen specs
 - Use cases are **reconciled** (API boundary sub-section added, not overwritten)
 - `contracts/` generated from reconciled UC API sub-sections
-- Reconciled files reported in the WorkResult's `deviations[]`
+- Reconciled files are told to the PO when the spec step closes
 
 ---
 

package/skills/{ba-pitch-analyzer/references → building/resources/plan-references}/task-generation.md

@@ -118,7 +118,7 @@ Every task at Layer N depends on all relevant tasks at Layer N-1.
 
 ## Lens-Aware Task Layer Breakdown
 
-The layer structure differs by lens. Read the order's `payload.lens` for the active lens
+The layer structure differs by lens. Read the step's `inputs.lens` for the active lens
 before generating tasks.
 
 ### LITE — Mobile-first layer breakdown
@@ -165,7 +165,7 @@ Errors   → [[contracts/[repo].contract.md#Error-Cases]]
 ```
 
 Do NOT overwrite existing Steps section — append API Contract sub-section only.
-Report reconciled files in the WorkResult's `deviations[]` with note `reconciled-by-upgrade`.
+Tell the PO which files were reconciled (`reconciled-by-upgrade`) when the spec step closes.
 
 ---
 
@@ -361,8 +361,8 @@ Slug rules:
 ## Link-Field Integrity (v3.3)
 
 **`depends_on` is the single authoritative edge; `unlocks` is derived, never hand-authored.**
-On EVERY board write — analyze, reconcile — recompute (via
-`harness reduce board --write`, never by hand) the `unlocks` field of every task on the board as the
+On EVERY board write — a full spec step, a reconcile — recompute (from the whole board, every time — never
+by feel) the `unlocks` field of every task on the board as the
 exact inverse of the full board's `depends_on` graph, then write it. Adding one task that
 declares `depends_on: [TASK-007]` therefore rewrites `TASK-007.unlocks` in the same pass.
 "Write both sides when you remember" allows drift; a derived field cannot drift
@@ -516,9 +516,9 @@ Non-Go:
 
 ---
 
-## Discovered-Task Reconciliation (operation: reconcile)
+## Discovered-Task Reconciliation (spec substep, mode: reconcile)
 
-Used by the reconcile operation over the discovered ledger at a round boundary. This is a pure
+Used by the spec substep in `reconcile` mode over the discovered ledger at a round boundary. This is a pure
 reducer: read existing state + the ledger delta, emit new state. The pitch and the
 upfront DDD layer are FROZEN — this mode never re-runs Phase 1–5.
 
@@ -531,8 +531,8 @@ tasks). Scope (Basecamp sense) maps onto a UC; an invariant lives *inside* the U
 1. Verify the ledger belongs to this spec. A discovered ledger rarely carries a pitch_hash
    (its frontmatter names the raw materials, e.g. source: shaping.md + breadboard.md).
    So match on identity that DOES exist:
-     a. ledger.feature == run-state.feature   (REQUIRED — mismatch → STOP)
-     b. if ledger carries pitch_hash, it must == run-state.pitch_hash
+     a. ledger.feature == this run's feature slug   (REQUIRED — mismatch → STOP)
+     b. if ledger carries pitch_hash, it must == the staged pitch's hash
    Neither resolvable → STOP: "ledger does not match this spec (different feature slug)."
 2. READ-ONLY for the frozen zone: domain-model, usecases/ (Steps), ux-behavior, contracts/.
 3. Parse ledger scopes → map each to its owning UC (S1→UC-…, S2→UC-…, S3→UC-…).
@@ -545,7 +545,7 @@ tasks). Scope (Basecamp sense) maps onto a UC; an invariant lives *inside* the U
      [ ] already has a file → skip
 5. For a Keep item that asserts a new invariant on its scope's UC:
      APPEND an [INV-NN] line to that UC's ## Invariants section (append-only,
-     never touch Steps/Input/Output). Log the UC path in run-state.human_edited_files.
+     never touch Steps/Input/Output).
      Generate the regression task with command-verifiable AC (see AC Trigger Matrix).
 6. Number new tasks by reading max id in tasks/_index.md and incrementing.
    NEVER renumber existing tasks — that would break every depends_on wikilink the
@@ -563,7 +563,7 @@ tasks). Scope (Basecamp sense) maps onto a UC; an invariant lives *inside* the U
    task-executor / the tech lead; this mode only surfaces the disagreement.
 9. Regenerate ONLY the derived files: tasks/_index.md, scope-summary.md, synthesis.md
    (+ the unlocks frontmatter recompute from step 7).
-10. Run harness reduce board (Appetite Guard arithmetic, below); report overflow as a discovery.
+10. Do the Appetite Guard arithmetic below over the whole board; report overflow as a discovery.
 ```
 
 **Appetite Guard (forcing function, not a report):**
@@ -584,7 +584,7 @@ This is scope hammering at the gate boundary — the overflow is surfaced, never
 **Naming note:** the discovery ledger's "scope" sections (above) predate the formal Scope
 Contract artifact below and name the same thing — a `discovery/ledger.md` scope heading MUST
 match an existing `scope_id` from a `scopes/<scope-id>.md` contract, or (a Keep item
-introducing new flow) become the seed for a new one via a scope-architect `map-scopes` order. One concept, two touch points.
+introducing new flow) become the seed for a new one via the scopes substep. One concept, two touch points.
 
 **Import/flow slicing (PA1 countermeasure).** Build a lightweight import graph over the task
 board's touched files: for each file a task writes, note what it imports and what imports it
@@ -614,8 +614,8 @@ or entirely `apps/api/**` with no cross-layer flow is the PA1 failure mode — r
 }
 ```
 `hill_phase` is always written `UPHILL_UNKNOWN` at generation time — it is derived later from
-mechanical T0/T1 facts, never declared by `ba`. `superseded_by` stays
-`null` until a scope-architect `map-scopes` order retires this contract in favor of its replacements.
+mechanical T0/T1 facts, never declared by the planner. `superseded_by` stays
+`null` until the scopes substep retires this contract in favor of its replacements.
 
 **PA2 size lint:** a scope whose `allowed_file_substrate` glob set resolves to more than ~15
 files gets a ⚠️ from spec-lint PA2 (hard-cap configurable via pitch frontmatter `scope_size_cap`, default

package/skills/{ba-pitch-analyzer/references → building/resources/plan-references}/test-surface.md

@@ -35,7 +35,7 @@ gap → surface it at GATE 4 as a question (max 2 rule applies), do not silently
 
 ```markdown
 ## Test Surface
-<!-- DERIVED — regenerate via a retrofit-surface order; do not hand-author rows here.
+<!-- DERIVED — regenerate via a retrofit-surface spec step; do not hand-author rows here.
      Source must cite D1–D4. Exploratory/edge tests live in QA's charters, not here. -->
 | ID | Oracle | Probe | Expect | Source |
 |---|---|---|---|---|
@@ -82,17 +82,16 @@ gathered, never *who* decides.
 
 1. **Phase 4 (fresh run, v2.9+):** derived per UC immediately after Error Cases are
    written, included in the GATE 4 review.
-2. **retrofit-surface operation (retrofit, incremental reducer):** for pre-v2.9 specs.
-   Frozen-zone discipline identical to the reconcile operation (the order's substrate enforces it):
+2. **retrofit-surface mode of the spec substep (retrofit, incremental reducer):** for specs that predate the Test Surface.
+   Frozen-zone discipline identical to the reconcile mode (the plan order's substrate enforces it):
    - READ-ONLY: domain-model, UC Steps/Input/Output/Invariants, ux-behavior, contracts/, tasks/
    - WRITE: append `## Test Surface` to each UC (after Error Cases; skip UCs that already
-     have one unless `--force-surface`), log touched UCs in `run-state.human_edited_files`,
-     set `run-state.test_surface: true`. Regenerate nothing else.
+     have one unless `--force-surface`), tell the PO which UCs were touched. Regenerate nothing else.
    - Source material missing (no Invariants, no contracts on lite) → derive from what
      exists; a UC whose four sources are all empty gets a one-line section:
      `_No derivable surface — sources empty. Exploratory coverage only (see qa-edge-hunter)._`
-3. **reconcile operation:** when a new `[INV-NN]` is appended to a UC, also
-   append its `TS-INV-NN` row (same append-only discipline, same `human_edited_files` log).
+3. **reconcile mode:** when a new `[INV-NN]` is appended to a UC, also
+   append its `TS-INV-NN` row (same append-only discipline).
 
 ## Audit hooks (spec-lint)
 - L2: every UC (v2.9 spec or `test_surface: true`) has `## Test Surface` with ≥1 row or the

package/skills/building/resources/plan-scopes.md

@@ -0,0 +1,95 @@
+# Plan — the scope contracts
+
+**Slice by flow, never by directory — and write it as a contract a hook can enforce.** Groups a feature's
+tasks into independent, vertically-sliced **scopes** and writes each as a committed contract,
+`shapeup/<slug>/scopes/<scope-id>.md`, that the rest of the harness enforces mechanically: the sandbox
+hook denies writes outside a substrate, the T0 verifier runs the fixtures, the evaluator asserts only
+against the affordance manifest. This substep is the sole writer of scope contracts and of `scope-board.md`
+(`scope-summary.md` belongs to the spec substep).
+
+Inputs: the board's tasks with their touched files — the slicing INPUT only. Each carries `use_case_refs`;
+those use-case ids are what you write into the contract, never a task id. Also: `ux-behavior.md` for the
+affordance manifests, the use cases for flows, the breadboard when present (every U# the spec places is one
+manifest entry's `source`; record which scopes deliver each V# slice in `scope-board.md`), and the guidance
+files (slicing habits for this codebase, config files that must have exactly one owner, fixtures that have
+proved vacuous — steering, never spec: a guideline cannot widen a substrate or stand in for the lint;
+conflict → the spec and the lint win, told to the PO).
+
+## Process
+
+```
+0 READ     the guidance, if any exists.
+1 SLICE    build an import/business-flow graph over the tasks' touched files (a grep heuristic is fine; an
+           AST is an optimisation). One scope = one call chain: the UI screen + the API route + the use
+           case + the repository it drives. A scope aligned 1:1 with a top-level directory (all-frontend,
+           all-backend) FAILS — that is layer-thinking.
+2 CLASSIFY topology_type: LAYER_CAKE (thin balanced UI + backend) | ICEBERG (complexity on one side) |
+           CHOWDER (true strays with no shared flow — the one deliberate exception).
+3 CONTRACT per scope, write scopes/<scope-id>.md — MARKDOWN: frontmatter for scalars and [a, b] lists, a
+           `## Affordances` table for the affordance manifest, a short `## Why this slice` paragraph. A
+           reviewer must be able to read the substrate in a PR; regeneration preserves prose under
+           headings you do not own.
+4 READ BACK the contracts together, once, and say what you found: PA1 (a scope aligned 1:1 with a top-level
+           directory), PA2 (> ~15 files, a warning), DISJOINT (a file in two scopes' substrate without both
+           declaring it shared — the write fence enforces substrates, so an overlap here is a collision there),
+           SCOPE-ANCHOR (empty or unresolvable use_cases), SCOPE-DEPS (depends_on naming a scope that is not
+           here). Fix reds by re-slicing, not by silencing. A task id in a committed contract is refused by the
+           write fence itself.
+5 BOARD    regenerate scope-board.md — a VIEW of the contracts, nothing more:
+             | scope_id | topology | use_cases | depends_on | files | lint |
+           Every column restates a field the contract already declares, so the board can be thrown away and
+           rebuilt. Do NOT add a `wave` column: waves are Kahn levels of `depends_on`, derived at dispatch;
+           a hand-written copy of a derived value drifts, which is why `unlocks` stopped being authored.
+           The BUILD ORDER lives in each contract's `depends_on`; the board only shows it.
+```
+
+## The contract's fields
+
+| Field | Rule |
+|---|---|
+| `scope_id`, `topology_type` | the stable join key is the scope id |
+| `use_cases[]` | the use-case ids this scope implements — **the ONLY link you write to the work: never task ids.** The contract is committed and the board is not, so a task id here dangles on every other clone (TIER-DIRECTION reds it). The scope's tasks are re-derived from the board's own `use_case_refs` |
+| `covers[]` | optional REQ-ids from `requirements.md` this scope answers for. Write the registry's own key — `REQ-12`, not the pitch's `R12`: both resolve, but one spelling in the committed contract is one thing to read |
+| `depends_on[]` | scope ids this scope builds AFTER — the build ORDER. Declare it whenever one scope consumes another's output, or the two race: nothing infers it, and an undeclared edge releases both into the same wave |
+| `allowed_file_substrate[]` | exact globs; the sandbox hook's write whitelist. Wrong here = a legitimate escalation later |
+| `shared_substrate[]` | files ≥ 2 scopes both touch. Declaring one costs concurrency: they build one at a time |
+| `affordance_manifest` | from the `ux-behavior.md` state tables: every interactive element as `{test_id, role}` + `required_states` [idle, loading, success, error, empty] + `source`, the U# the ux row cites |
+| `e2e_verification_fixtures[]` | the command(s) / spec file(s) that drive this scope end to end (the T0 layer). Too speculative to fixture → mark TBD and flag it, never invent a fixture for unbuilt behavior. **Every fixture MUST EXIT 0 when the scope is correct** — T0 scores any non-zero exit as a failure, so a bare error-path invocation can never pass; put expected non-zero exits inside a test file that itself exits 0, and name that file. Write them as a FRONTMATTER key holding bare commands |
+| `hill_phase` | `"UPHILL_UNKNOWN"`, ALWAYS; phase is derived from T0/T1 facts later, never authored |
+
+**`affordance_manifest` lives in the TABLE and NOWHERE ELSE.** Do not also write it in the frontmatter:
+nothing reads it there, so the copy is discarded — and a run has been lost to exactly that (the frontmatter
+said `required_states: [idle]`, the table cell said a bare `idle`, the table won, the value was a string
+where an array was required, and four scopes were never dispatched with every check green). A contract
+declaring no affordances writes `affordance_manifest: []` in frontmatter and no table.
+
+**A list inside a table cell is written `[a, b]`, brackets and all** — `[idle]`, never `idle`. A bare word in
+that cell is a string, and `required_states` is an array.
+
+A `TASK-` id anywhere in a contract or the board — a column, a cell, a sentence of prose — is TIER-DIRECTION
+red. The board is committed; task ids are not.
+
+**Folding in a discovered item:** it joins the nearest scope only if the flow matches (extend that substrate
+minimally); otherwise propose a NEW scope — never silently widen an existing one. **Re-slicing a stuck
+scope:** re-run step 1 on just that scope's task and file set → N new contracts; mark the old one
+`superseded_by: [ids]` — never delete (the branch and the T0 history stay attributable).
+
+## Reasons not to cut a corner
+
+| Excuse | Reality |
+|---|---|
+| "The discovered item obviously fits scope A" | Run the flow match. "Obviously" is how substrates silently widen. |
+| "One scope per directory is cleaner" | That is PA1 — a layer, not a flow. A scope must ship something a user can do. |
+| "I'll widen the substrate so the doer stops escalating" | A wide substrate is no substrate. Split, or add a `shared_substrate` entry, deliberately. |
+| "This scope looks downhill, I'll set the phase" | `hill_phase` is `UPHILL_UNKNOWN` at write, always. Facts move dots, not authors. |
+| "The old contract is superseded, delete it" | Supersede, never delete. History must stay attributable. |
+| "Both scopes implement that use case, the tasks will sort themselves out" | They will not — both get every task of that use case and three of four writes get denied. Give each scope its own use cases, or tell the PO. |
+| "I'll list the task ids so the contract says what it builds" | The board is gitignored and renumbers per machine; the contract is committed. Cite the use cases. |
+| "Fixtures can come later" | A fixture at contract time or an explicit TBD flag — silence is how T0 goes blind. |
+
+Verify before `close`: every scope crosses layers or is declared CHOWDER (PA1 = 0 red); every scope names ≥ 1
+`use_cases` that resolves on disk and no contract carries a task id; every scope that consumes another's
+output declares it in `depends_on`; substrates are disjoint except declared `shared_substrate`; every
+interactive element in a scope's screens appears in exactly one manifest; every U# the spec places is some
+manifest entry's `source`; every scope has fixtures or an explicit TBD flag; every `hill_phase` written is
+`UPHILL_UNKNOWN`; superseded contracts are kept.

package/skills/building/resources/plan-spec.md

@@ -0,0 +1,102 @@
+# Plan — the spec tree and the board
+
+Converts the pitch into a fully linked tree: `_index` → `domain-model` → `ux-behavior` → `usecases/` →
+`integration` → `tasks/`, with Obsidian wikilinks and a shared frontmatter taxonomy, navigable from pitch to
+atomic task. Formats live in `plan-references/` (the rules each phase follows) and `plan-templates/` (one
+template per document).
+
+**Modes.** `full` (the default) writes the whole tree and the board. `board-only` — the tree is already
+committed and FROZEN; the board is per-machine and is not on this machine — regenerates `tasks/` from the
+use cases as they are: the same task derivation, every acceptance criterion carrying its
+`(covers: REQ-…)` clause, ids numbered fresh for this machine. In `board-only` never touch the spec folder,
+re-derive or "improve" a use case, or invent a task no use-case step or Test Surface row sources.
+
+Payload the step may carry: `lens` (`lite` | `standard` | `cross-context`; absent → judge it: LITE for a
+≤ 2-week appetite, no third party, ≤ 3 user-facing actions; STANDARD for multi-team, third-party or bigger;
+genuinely unclear → one binary question to the PO), the pitch, the breadboard (its Places are your screens;
+its U# and N# are the affordances you place and cite — absent = none separate, never inferred) and the
+orient directory.
+
+## The pipeline (mode `full`)
+
+Read the reference file before its phase; pause for the PO at a checkpoint only when the run is
+interactive, at most two questions each.
+
+```
+1  INGEST      pitch + breadboard + orient artifacts + guidance. Extract slug, appetite, in/out boundaries,
+               rabbit holes, third-party mentions. With a breadboard, list every Place (P#) and UI
+               affordance (U#) first — they are the screens and interactive elements phase 3 must place.
+               No files written yet.
+1b FEASIBILITY (third-party / API / SDK / webhook mentioned) verification questions + a fallback scope per
+               API-NN → api-feasibility.md
+2  DDD         bounded contexts, aggregates (new vs extended), value objects, domain events, repository
+               interfaces → domain-model.md                              [plan-references/ddd-patterns.md]
+2b CONTRACTS   (standard lens) typed Request/Response/Error per repository; two-pass rule: unresolvable at
+               spec time → `⏳ TBD — verify in the [UC-x] spike`, resolved post-spike with a citation →
+               contracts/                                          [plan-references/contract-patterns.md]
+3  UX          per screen — with a breadboard, one screen per Place that owns UI affordances: state table
+               (idle → loading → error → success), error cases with message + action, ASCII flows →
+               ux-behavior.md                                    [plan-references/ux-behavior-patterns.md]
+4  USE CASES   one file per actor + action: typed Input/Output, numbered Steps, all error cases with
+               codes, ## System Flow (UI → API → UC → Repo → DB), ## Test Surface (DERIVED ONLY from
+               D1 Invariants · D2 Error Cases · D3 Contract shape · D4 No-gos — a sourceless test idea is
+               a spec gap to raise, never a row to invent) → usecases/      [plan-references/test-surface.md]
+5  INTEGRATION (standard lens) cross-system data flows, events, silent-failure risks → integration.md
+                                                                      [plan-references/integration-analysis.md]
+6  TASKS       atomic, ordered, executable → tasks/ (the LOCAL root, the one uncommitted branch of the
+               tree: regenerable, machine-local)                      [plan-references/task-generation.md]
+7  DERIVE+READ BACK  not yours to grade, and no script does it for you:
+                 recompute `unlocks` as the depends_on inverse over the whole board; sum the hours; find the
+                 critical path; do the appetite arithmetic — an overflow is a fact you REPORT for the stop
+                 gate, never resolve. Then read the tree back: structure, wikilinks, edge symmetry — fix what
+                 you find. BREADBOARD-PLACE / BREADBOARD-UI: every Place with UI affordances is its own
+                 screen — add it or defer the Place with the PO's yes; never fold it into another
+               → scope-summary.md + synthesis.md (traceability matrix, risk register, dependency graph —
+                 the judgment layers over the board's numbers)
+8  INDEX       _index.md (pitch digest + document map) + feedback.md template
+```
+
+Working notes (`scope-summary.md`, `synthesis.md`, `assess-report.md`, `feedback.md`, `api-feasibility.md`,
+`integration.md`) live in the LOCAL tier since the consumer layout split: the committed `spec/` keeps what
+the evaluator grades against and a reviewer needs.
+
+## Task generation rules (what makes a task executable)
+
+- One task = one verifiable change (one package, one concern); acceptance criteria checkable by running
+  commands.
+- `depends_on` explicit; `unlocks` is the `depends_on` inverse, recomputed whenever a task changes, never filled in by feel.
+- Contract-first: an implementation task touching a repository requires its contract file (else generate
+  the contract-stub task first); third-party + `⏳ TBD` → the SPIKE task precedes and blocks it
+  (`time_box_hours` hard cap, `api_ref`, `blocks[]`).
+- AC trigger matrix (full rules in `plan-references/task-generation.md`): conditional rendering → 🔁
+  Inverse Conditions; data fetching → 📭 Empty & Null States; numeric limits → 🔢 Boundary Values; FEAT +
+  a user actor or cross-layer → 🧪 BDD Scenarios; ≥ 1 service boundary → 🔗 Integration Flow; not
+  triggered → remove the section entirely.
+- After all implementation tasks: one integration-test task (DB round-trip, auth rejection, cross-service
+  BDD).
+
+**Coverage trust = use case.** Every task carries `use_case_refs`; a task with none is an orphan (red). An
+invariant-backed regression task still anchors to its owning use case — there is no second path to green.
+
+**The requirement edge is written on the AC line, or it does not exist.** An acceptance criterion that
+grades a registry requirement ends with `(covers: REQ-…)` — the trailing clause, in the checkbox text, not a
+mention in prose. A board AC reaches the judge through the refuted list alone: it can yield a FAIL and can
+never yield a PASS, so an AC nothing cites by id produces no evidence for the requirement it was written
+for. A board whose criteria carry no `covers:` clause beside a registry is sent back once.
+
+**A requirement with no natural use-case home still becomes a task.** Contrast, localisation, a
+performance ceiling, a test surface — a non-functional clause has no actor + action and so no use case of
+its own, and the habit is to record it in the risk register, where nothing grades it. Give it a task whose
+AC reaches the committed spec (the invariant, the contract field or the Test Surface row that states it)
+and carries its `(covers: REQ-…)`. A line in the risk table is a note; a covered AC is a requirement the
+run can be measured against.
+
+## What is yours and what is not
+
+You write the spec tree, the board and the working notes. You do not write `run-state` (dead — the loop
+owns run truth), `tasks/_index.md` status flips for built work (the loop's, when it applies a result), scope contracts (the
+scopes substep's), or any discovered-rounds counter. Verify before `close`: every task has
+`use_case_refs`, explicit `depends_on`, command-verifiable acceptance criteria; no hand-authored `unlocks`;
+`unlocks` was recomputed after the last board change; you read the tree back and found 0 red (or each remaining red
+is explained to the PO); every Test Surface row cites a D1–D4 source (gaps raised, not filled); appetite
+overflow, if any, is reported, not resolved.

package/skills/{ba-pitch-analyzer/assets/templates → building/resources/plan-templates}/_index.tmpl.md

@@ -65,7 +65,7 @@ audit_rules_version: "2.5"
 
 ## Audit Report
 
-*Generated from harness verify spec output — do not edit manually.*
+*Written by the planning step from its own read-back — do not edit manually.*
 *skill_version: 2.1 | audit_rules_version: 2.1*
 
 ### Score Summary

package/skills/{ba-pitch-analyzer/assets/templates → building/resources/plan-templates}/assess-report.tmpl.md

@@ -83,17 +83,16 @@ This pitch touches N bounded contexts: [context-a], [context-b], [context-c]
 
 **Option A — Single standard run** *(faster, boundaries may be blurry)*
 ```bash
-/ba-pitch-analyzer --lens standard docs/pitch.md
+# plan the spec step with lens=standard for docs/pitch.md
 ```
 Estimated tokens: ~N tokens
 
 **Option B — Split + cross-context** *(slower, precise boundaries)*
 ```bash
-/ba-pitch-analyzer --lens standard docs/pitch-[context-a].md
-/ba-pitch-analyzer --lens standard docs/pitch-[context-b].md
-/ba-pitch-analyzer --cross-context FEATURE_SLUG \
-    shapeup/[context-a]/spec/ \
-    shapeup/[context-b]/spec/
+# plan the spec step with lens=standard for docs/pitch-[context-a].md
+# plan the spec step with lens=standard for docs/pitch-[context-b].md
+# then plan the cross-context documents (FEATURE_SLUG) over
+#   shapeup/[context-a]/spec/  and  shapeup/[context-b]/spec/
 ```
 Estimated tokens: ~N total (reusable per context)
 
@@ -116,12 +115,12 @@ Choose: **[A]** or **[B]**
 
 ```bash
 # Proceed with recommended lens
-/ba-pitch-analyzer --lens LENS docs/pitch.md
+# plan the spec step with lens=LENS for docs/pitch.md
 
 # Override lens
-/ba-pitch-analyzer --lens lite docs/pitch.md
-/ba-pitch-analyzer --lens standard docs/pitch.md
+# plan the spec step with lens=lite for docs/pitch.md
+# plan the spec step with lens=standard for docs/pitch.md
 
-# Skip assess on next run (pitch already reviewed)
-/ba-pitch-analyzer --lens LENS --skip-assess docs/pitch.md
+# Skip the assessment on the next run (pitch already reviewed)
+# plan the spec step with lens=LENS for docs/pitch.md
 ```

package/skills/{ba-pitch-analyzer/assets/templates → building/resources/plan-templates}/run-state.tmpl.md

@@ -55,14 +55,14 @@ upgrade_adds: []
 
 ```bash
 # Check current upgrade options
-/ba-pitch-analyzer --status shapeup/FEATURE_SLUG/spec/
+# re-read the spec and recompute `unlocks` over the board
 
 # Upgrade to standard lens (adds contracts + integration + full synthesis)
-/ba-pitch-analyzer --upgrade standard shapeup/FEATURE_SLUG/spec/
+# re-plan the spec step with lens=standard over shapeup/FEATURE_SLUG/spec/ (extend, never overwrite Steps)
 
 # Upgrade specific module only
-/ba-pitch-analyzer --upgrade contracts shapeup/FEATURE_SLUG/spec/
-/ba-pitch-analyzer --upgrade synthesis shapeup/FEATURE_SLUG/spec/
+# re-plan the spec step for the contracts only
+# re-plan the spec step for the synthesis only
 ```
 
 ## Metrics

package/skills/{ba-pitch-analyzer/assets/templates → building/resources/plan-templates}/scope-summary.tmpl.md

@@ -39,7 +39,7 @@ The longest sequential chain — minimum time to complete if parallelized optima
 *(All other work can happen in parallel alongside this chain)*
 
 <!-- Record the DERIVED numbers only — total hours and step count, both from
-     `harness reduce board`. The chain's task ids belong to the LOCAL board
+     the board you recomputed. The chain's task ids belong to the LOCAL board
      (.shapeup/<slug>/tasks/), which is gitignored and renumbers per machine; this
      document is committed, so an id written here dangles on every other clone
      (spec-lint TIER-DIRECTION). Read the id-level chain off the board itself. -->
@@ -99,7 +99,7 @@ Carried from [[_index#Rabbit-Holes]]:
 
 ## Execution Recommendation
 
-<!-- Filled from harness verify spec output -->
+<!-- Filled from the planning step's own read-back -->
 
 **Audit Score: N/100**
 

package/skills/{ba-pitch-analyzer/assets/templates → building/resources/plan-templates}/synthesis.tmpl.md

@@ -28,9 +28,9 @@ depends_on:
 |-----------|--------|--------|
 <!-- Coverage here is USE CASES × TASKS, derived by inverting each task's use_case_refs over the
      local board. It is NOT requirement coverage: whether every REQ-id reaches an acceptance
-     criterion that a judge graded is a projection derived per run (`probe requirements`), and a
+     criterion that a judge graded is a projection read per run off the verdict and the `covers:` edges, and a
      committed file that states it is corroborating something no run measured. Name REQ ids in this
-     row and spec-lint reds it (REQ-NARRATED). Count use cases and tasks; say nothing about REQ. -->
+     row and the claim goes stale the day it is written. Count use cases and tasks; say nothing about REQ. -->
 | Coverage | COVERAGE_STATUS | COVERAGE_SIGNAL |
 | Risk | RISK_STATUS | RISK_SIGNAL |
 | Dependency | DEPENDENCY_STATUS | DEPENDENCY_SIGNAL |
@@ -165,7 +165,7 @@ Derived from: `_index.md` rabbit holes + `api-feasibility.md` SPIKE blocks + `in
 <!--
   The SINGLE source of truth for tasks that were scope-hammered out of the cycle.
   A Cut produces NO task file (no bet yet, so no spec). Only record a trace line here.
-  Mostly populated/appended by the reconcile operation over the discovered ledger.
+  Mostly populated/appended by the spec substep's reconcile mode over the discovered ledger.
   Each line: what was cut — Cut @ GATE-N · reason · (if hammer-traded) which task it was traded for.
 -->
 
@@ -194,6 +194,6 @@ spec-lint reds a `TASK-` id anywhere in the committed tree (TIER-DIRECTION).
 | Single points of failure (block > 2 downstream) | N |
 
 **The per-scope build order — which scopes go in which wave, and what each waits on — lives in
-`scope-board.md`, not here.** `scope-architect` writes that board and is the only worker that knows
+`scope-board.md`, not here.** the scopes substep writes that board and is the only step that knows
 the scope ids; it runs after this document, so the ordering cannot be expressed here in a key that
 survives a clone. Cite the board, never restate it.

package/skills/{ba-pitch-analyzer/assets/templates → building/resources/plan-templates}/usecase.tmpl.md

@@ -68,7 +68,7 @@ interface [UseCaseName]Output {
   An invariant must STILL hold after this UC is built.
   Each invariant is a source of regression tasks — that task anchors use_case_refs back to THIS UC
   (do NOT create a new anchor axis; an invariant is a property of the UC, not a UC of its own).
-  This section MAY be APPENDED by the reconcile operation when a build discovers a new constraint
+  This section MAY be APPENDED by the spec substep's reconcile mode when a build discovers a new constraint
   (append-only — never edit the locked Steps/Input/Output).
   Drop this section if the UC produces no invariants.
 -->
@@ -86,7 +86,7 @@ interface [UseCaseName]Output {
   DERIVED section — generated mechanically from Invariants (D1) + Error Cases (D2) +
   Contract/Input shape (D3) + pitch No-gos touching this UC (D4).
   Rules → references/test-surface.md. Never hand-author rows; never invent behaviors.
-  Regenerable via a retrofit-surface order. Appended-to (TS-INV rows) by the reconcile operation when
+  Regenerable via the spec substep's retrofit-surface mode. Appended-to (TS-INV rows) by its reconcile mode when
   a new invariant lands. Exploratory/edge tests do NOT live here (qa-edge-hunter owns those).
   If all four sources are empty, replace the table with:
   _No derivable surface — sources empty. Exploratory coverage only (see qa-edge-hunter)._