shapeup-sdlc 1.6.2 → 1.7.0

package/skills/ba-pitch-analyzer/SKILL.md

@@ -24,16 +24,16 @@ Invoked as `--order <path>`. Fields you may rely on (absent = unknown; surface i
 
 | Field | What it is |
 |---|---|
-| `operation` | `analyze` (pitch → full spec tree + board) · `generate-board` (regenerate the LOCAL board from the committed spec) · `reconcile` (fold discovered-ledger items into the board + UC invariants) · `retrofit-surface` (append `## Test Surface` to a pre-surface spec) · `coverage` (extract atomic requirement clauses → the SHARED `requirements.md` registry) |
+| `operation` | `analyze` (pitch → full spec tree + board) · `reconcile` (fold discovered-ledger items into the board + UC invariants) · `retrofit-surface` (append `## Test Surface` to a pre-surface spec) · `coverage` (extract atomic requirement clauses → the SHARED `requirements.md` registry) |
 | `payload.pitch` | The pitch/PRD path (analyze) |
 | `payload.requirements` | (coverage) the REQ source to extract atomic clauses from — pitch / a customer-requirements doc / the use-case bodies. Absent → default to the pitch and record the choice in `assumptions[]` |
-| `payload.lens` | `lite` \| `standard` \| `cross-context`. Absent → judge it: LITE for ≤2-week appetite, no third-party, ≤3 user-facing actions; STANDARD for multi-team, third-party, or bigger appetite; genuinely unclear → one binary question / one `escalates[]` entry |
+| `payload.lens` | `lite` \| `standard` \| `cross-context`. Absent → judge it: LITE for ≤2-week appetite, no third-party, ≤3 user-facing actions; STANDARD for multi-team, third-party, or bigger appetite; genuinely unclear → one binary question, or `status: "escalated"` with the question in `deviations[]` |
 | `payload.orient_dir` | The Scout's artifacts — `code-surface.md` IS your codebase map (do not re-scan), `discovered-seed.md` seeds task gen, `spike-*.md` feeds feasibility |
 | `payload.spec_folder` / `payload.feature` | Where the committed tree lives / the slug |
 | `payload.discovered_ledger` | (reconcile) the ledger whose raw `[+]`/`~` lines you fold in |
 | `payload.kb_rules_path` | Team guidelines (read if present) — steering, never spec |
-| `substrate.allowed / append_only / frozen` | Your write contract for THIS operation. The old frozen-zone prose is now data the sandbox hook enforces: respect it, and when an operation genuinely needs a file outside it, ESCALATE — never widen |
-| `interaction.pause_gates` | Caller policy. `true` (standalone default): pause at the phase checkpoints below, max 2 questions each. `false`: run straight through, surfacing questions as `assumptions[]`/`escalates[]` instead |
+| `substrate.allowed / append_only / frozen` | Your write contract for THIS operation. The old frozen-zone prose is now data the sandbox hook enforces (reading the order's envelope): respect it, and when an operation genuinely needs a file outside it, ESCALATE — never widen |
+| `interaction.pause_gates` | Caller policy. `true` (standalone default): pause at the phase checkpoints below, max 2 questions each. `false`: run straight through, surfacing questions as `assumptions[]` (or `deviations[]` when they block) instead |
 
 ---
 
@@ -94,15 +94,13 @@ second path to green.
 
 ---
 
-## The other four operations — same craft, different payload + whitelist
+## The other three operations — same craft, different payload + whitelist
 
 | Operation | Essence | Never |
 |---|---|---|
-| `generate-board` | Re-derive the full task set fresh from the committed `usecases/` + `domain-model.md` (+ scope contracts if present — tasks respect their substrates). Numbering restarts at TASK-001. Initialize `status` from committed mechanical truth at SCOPE granularity (a scope with hill shard FINISHED → its tasks start `done`) — never join on task id; ids renumber per machine, the scope is the stable key. Then board-derive `--write` + regenerate scope-summary.md | touch the committed spec docs (frozen in your substrate) |
-| `reconcile` | Verify `ledger.feature == payload.feature` (mismatch → STOP). Map each `[+]` Keep item → its owning UC; new task continues numbering (never renumber); `~`/Cut → synthesis "Hammered Out" row, no file. A Keep item asserting a new invariant → APPEND `[INV-NN]` + TS-INV row to that UC (append-only sections in your substrate). A new actor/action with no UC → `escalates[]` (spec-ambiguity): spawning a UC mid-cycle is silent re-shaping, the PO decides. Finish with board-derive (appetite overflow → report) + spec-lint | re-run phases 1–5; edit UC Steps; resolve the appetite HAMMER yourself |
+| `reconcile` | Verify `ledger.feature == payload.feature` (mismatch → STOP). Map each `[+]` Keep item → its owning UC; new task continues numbering (never renumber); `~`/Cut → synthesis "Hammered Out" row, no file. A Keep item asserting a new invariant → APPEND `[INV-NN]` + TS-INV row to that UC (append-only sections in your substrate). A new actor/action with no UC → `status: "escalated"` + a `deviations[]` spec-ambiguity entry: spawning a UC mid-cycle is silent re-shaping, the PO decides. Finish with board-derive (appetite overflow → report) + spec-lint | re-run phases 1–5; edit UC Steps; resolve the appetite HAMMER yourself |
 | `retrofit-surface` | Append `## Test Surface` (derived rows only, after Error Cases) to each UC of a pre-surface spec; an all-sources-empty UC gets the explicit empty-sources line | touch anything else — append-only substrate |
-| `coverage` | Extract **atomic** customer requirement clauses from `payload.requirements` (default: the pitch) and write the SHARED `shapeup/<slug>/requirements.md` registry: one `\| REQ-id \| clause (verbatim) \| source \| status \| note \|` row per clause. Split compound sentences into one testable clause each — the audit's dropped clauses ("side-step OR lure enemies into traps", "low-res world textures") were *lost inside* a bigger sentence. **Assign REQ-ids ONCE and freeze them** (they behave like scope_id, never TASK-NNN — every `covers:` link rots otherwise): re-running, append new clauses with fresh ids, mark a removed clause `CUT (PO-approved)`, never renumber or delete. Status starts `covered` (a live requirement); only the PO sets `CUT`. The REQ source itself is frozen — the registry is a separate derived file | edit the REQ source; renumber existing REQ-ids; delete a dropped clause instead of marking it CUT; invent a requirement not in the source |
-
+| `coverage` | Extract **atomic** customer requirement clauses from `payload.requirements` (default: the pitch) and write the SHARED `shapeup/<slug>/requirements.md` registry: one `\| REQ-id \| clause (verbatim) \| source \| status \| note \|` row per clause. Split compound sentences into one testable clause each — a clause lost *inside* a bigger sentence is a requirement nothing can be traced to. **Assign REQ-ids ONCE and freeze them** (they behave like scope_id, never TASK-NNN — every `covers:` link rots otherwise): re-running, append new clauses with fresh ids, mark a removed clause `CUT (PO-approved)`, never renumber or delete. Status starts `covered` (a live requirement); only the PO sets `CUT`. The REQ source itself is frozen — the registry is a separate derived file | edit the REQ source; renumber existing REQ-ids; delete a dropped clause instead of marking it CUT; invent a requirement not in the source |
 ---
 
 ## Anti-rationalization table
@@ -115,12 +113,19 @@ second path to green.
 | "My output looks complete, score it 92" | You don't grade yourself. spec-lint reports facts; the judge judges. |
 | "The appetite overflow is small, drop a nice-to-have myself" | Overflow is a HAMMER gate for the caller. You report the fact and the candidate cuts. |
 | "Re-scanning the codebase is safer than trusting orient" | code-surface.md IS the map. Re-scanning burns tokens and forks the truth. |
-| "unlocks is quick to fill in by hand" | Hand-authored unlocks produced 10 asymmetric edges (KB-BA-001). board-derive computes it. |
+| "unlocks is quick to fill in by hand" | Hand-authored unlocks drift asymmetric — observed, repeatedly. board-derive computes it. |
 
 ---
 
 ## Output contract — the WorkResult
 
+**Escalation rule.** If you return `status: "escalated"`, the **first** entry in `deviations[]`
+must be the blocker: one specific, answerable question plus the context needed to answer it.
+Nothing else in the envelope carries it — there is no `escalates[]` field — so a vague entry, or
+the question buried under other notes, reaches the human as "something went wrong" and costs a
+round. Write it so someone without your context can answer it in one reply.
+
+
 Domain artifacts land inside your substrate (the committed spec tree + the LOCAL board). Then
 write `.shapeup/<slug>/results/<order-suffix>.json`:
 
@@ -129,9 +134,8 @@ write `.shapeup/<slug>/results/<order-suffix>.json`:
   "schema_version": 1, "order_id": "<copied>", "worker": "ba-pitch-analyzer",
   "status": "done | partial | escalated",
   "artifacts": ["shapeup/<slug>/spec/domain-model.md", "…"],
-  "escalates": [ { "kind": "spec-ambiguity", "question": "New actor 'auditor' has no UC — add UC-07 or cut?" } ],
   "assumptions": ["lens=standard — third-party PSP present"],
-  "deviations": [],
+  "deviations": [ "ESCALATE spec-ambiguity — New actor 'auditor' has no UC — add UC-07 or cut?" ],
   "discoveries": [ { "marker": "+", "line": "appetite overflow 12h — candidate cuts: TASK-014, TASK-017" } ]
 }
 ```
@@ -168,8 +172,9 @@ status flips for built work (ingest's job), scope contracts (scope-architect's),
 ```
 
 Standalone keeps exactly two flags: the pitch input and `--lens`. Every retired flag is now
-caller context: `--tasks-only` → a generate-board order, `--from-discovered` → a reconcile
-order, `--surface-only` → a retrofit-surface order, `--remap`/`--split` → scope-architect
-orders, `--status` → read `spec-lint.mjs`/`board-derive.mjs` output (zero LLM tokens),
+caller context: `--tasks-only`/`--from-discovered` → a reconcile order, `--surface-only` → a
+retrofit-surface order, `--coverage` → a coverage order, `--remap`/`--split` → a
+scope-architect `map-scopes` order,
+`--status` → read `spec-lint.mjs`/`board-derive.mjs` output (zero LLM tokens),
 `--auto`/`--skip-gate*` → `interaction.pause_gates`, `--upgrade` → an analyze order with the
 standard lens over an existing lite tree (reconciliation pass: extend, never overwrite Steps).

package/skills/ba-pitch-analyzer/references/doc-schemas.md

@@ -152,7 +152,7 @@ status: draft | ready
 > tasks carry `use_case_refs` (LOCAL, per-machine board); reverse lookup is always computed
 > live (synthesis S-01, audit coverage) — never stored on the committed UC. Rule: **never
 > declare a bidirectional field across the committed/local boundary** — task IDs renumber
-> per machine (generate-board bootstrap), so a stored back-link is wrong on every machine
+> per machine (the board is regenerated locally), so a stored back-link is wrong on every machine
 > but one. Tolerate (ignore) the field on pre-v3.3 specs; do not emit or update it.
 
 Required sections: Summary (1 sentence), Preconditions, Input (TS interface), Steps

package/skills/ba-pitch-analyzer/references/task-generation.md

@@ -361,12 +361,12 @@ 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, generate-board, reconcile — recompute (via
+On EVERY board write — analyze, reconcile — recompute (via
 `board-derive.mjs --write`, never by hand) 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
-(island-escape shipped 10 asymmetric edges under the old rule). Audit L3-06 fails the board
+(the old rule shipped boards carrying ten asymmetric edges). Audit L3-06 fails the board
 on any asymmetric edge.
 
 The same discipline has a boundary: it applies only when both sides live in the SAME root
@@ -584,12 +584,12 @@ 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 remap order. One concept, two touch points.
+introducing new flow) become the seed for a new one via a scope-architect `map-scopes` order. 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
 (grep for `import .* from ['"](\.\.?/[^'"]+)`-class patterns is sufficient — a full AST parser
-is an optimization, not a prerequisite, per design spec R6). Two files are in the same flow if
+is an optimization, not a prerequisite). Two files are in the same flow if
 they sit on one call chain: a UI component → the API route it calls → the use case that route
 invokes → the repository that use case depends on. Group tasks by flow, not by which top-level
 directory their file lives in. A scope whose `allowed_file_substrate` is entirely `apps/web/**`
@@ -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/seesaw facts, never declared by `ba` (design spec DD-10). `superseded_by` stays
-`null` until a scope-architect split-scope order retires this contract in favor of its replacements.
+mechanical T0/T1/seesaw facts, never declared by `ba`. `superseded_by` stays
+`null` until a scope-architect `map-scopes` order 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/test-surface.md

@@ -7,7 +7,7 @@ source row below, it does not belong here (it belongs to exploratory QA, post-bu
 **Why it exists.** `spec-conformance` grades the AC that were written; it cannot expand
 them. The Test Surface is the systematic expansion — boundary values, negative cases,
 error-code coverage — done once at spec time so the evaluator (`test-surface-conformance`
-dimension) can probe it. Division of labor settled at the QA meeting (2026-06-11):
+dimension) can probe it. Division of labor, a settled design decision:
 derivable tests = BA + Evaluator (this file); exploratory edges = `/qa-edge-hunter`,
 post-PASS, on the running app.
 

package/skills/ba-pitch-analyzer/scripts/board-derive.mjs

@@ -2,7 +2,7 @@
 // Board derivation (pure-skill architecture v1.0, plan §8.2).
 //
 // The mechanical half of the old ba-pitch-analyzer Phase 7b + v3.3 link-field rules — pure
-// graph math a model should never re-derive (and could get wrong: KB-BA-001's 10 asymmetric
+// graph math a model should never re-derive (and gets wrong: hand-authored inverses drift asymmetric
 // edges came from hand-authored `unlocks`):
 //
 //   • `unlocks` = the depends_on inverse, recomputed over the WHOLE board (--write persists
@@ -28,9 +28,9 @@ import { readAllContracts, splitFrontmatter, SCOPE_CONTRACT } from "../../tech-l
 /**
  * Read a list field from a frontmatter string, inline `[a, b]` or YAML block sequence alike.
  *
- * HD-004 — the SECOND instance of HD-003, in a second parser. This repo had two hand-rolled
+ * The SECOND instance of the same defect, in a second parser. This repo had two hand-rolled
  * frontmatter readers: `contract-md.mjs` for the committed contracts, and this one for the board.
- * HD-003 was fixed in the first, and this one still silently dropped a block sequence — so a board
+ * It was fixed in the first, and this one still silently dropped a block sequence — so a board
  * written as
  *   use_case_refs:
  *     - UC-01
@@ -163,8 +163,8 @@ export function driftCheck(tasks, scopes) {
  *   board, deleted before CLI output).
  */
 export function derive({ cwd, slug, appetiteHours = null }) {
-  const tasksDir = tasksDir(cwd, slug);
-  const tasks = parseBoard(tasksDir);
+  const boardDir = tasksDir(cwd, slug);
+  const tasks = parseBoard(boardDir);
   const unlocks = deriveUnlocks(tasks);
   const keepHours = tasks.filter((t) => t.status !== "cut").reduce((a, t) => a + t.hours, 0);
   const packages = {};

package/skills/ba-pitch-analyzer/scripts/spec-lint.mjs

@@ -159,7 +159,7 @@ export function lintStructure({ specDir, tasks }) {
       }
     }
   }
-  // Task frontmatter + graph integrity (edge symmetry = the mechanized KB-BA-001 check).
+  // Task frontmatter + graph integrity (edge symmetry — the hand-authored-unlocks drift, mechanized).
   const ids = new Set(tasks.map((t) => t.id));
   const derived = deriveUnlocks(tasks);
   for (const t of tasks) {
@@ -203,7 +203,7 @@ export function lint({ cwd, slug }) {
   const tasks = parseBoard(tasksDir(cwd, slug));
   const repoFiles = walkFiles(cwd);
   const findings = [
-    // HD-001. A contract whose table this parser cannot see reads as a contract that declared no
+    // A contract whose table this parser cannot see reads as a contract that declared no
     // table, and every rule below then passes for the part it could not read. Loud, not empty.
     ...contracts
       .map(({ contract, path }) => ({ reason: unreadableReason(contract), scope: contract.scope_id || path }))

package/skills/coach/SKILL.md

@@ -41,8 +41,8 @@ they are the **complete** set of categories the gate may offer:
 
 | Category | File | The worker reads it at | Good for |
 |----------|------|------------------------|----------|
-| `task-executor`     | `shapeup/knowledge-base/task-executor.md`     | Phase 1 (Context Load) | implementation discipline, code style, surgical-change habits, recurring over/under-engineering |
-| `ba-pitch-analyzer` | `shapeup/knowledge-base/ba-pitch-analyzer.md` | Phase 1 (Ingest & Scan) | scoping, task decomposition, DDD/spec habits, missed test-surface patterns |
+| `task-executor`     | `shapeup/knowledge-base/task-executor.md`     | PLAN (context load) | implementation discipline, code style, surgical-change habits, recurring over/under-engineering |
+| `ba-pitch-analyzer` | `shapeup/knowledge-base/ba-pitch-analyzer.md` | Phase 1 (INGEST) | scoping, task decomposition, DDD/spec habits, missed test-surface patterns |
 | `qa-edge-hunter`    | `shapeup/knowledge-base/qa-edge-hunter.md`    | Phase Q1 (Charter Map) | recurring edge classes, lenses that keep finding bugs, areas worth probing |
 
 **Not coachable.** `spec-evaluator` is deliberately excluded — the harness has a **single-judge**
@@ -54,7 +54,7 @@ say so plainly — do **not** force-fit it into a coachable category.
 **Harness defect ≠ worker steering.** When the feedback's root cause is the *mechanism itself* —
 a hook that fail-opens, a gate that reads the wrong file, two skill contracts that contradict
 each other — no amount of steering a worker fixes it, and filing it as a KB rule misdiagnoses a
-defect as a habit (island-escape's KB-BA-002 filed an orchestration/hook defect as BA guidance,
+defect as a habit (a real case: an orchestration/hook defect filed as BA guidance,
 on a premise the skill contracts contradict). That is what the `harness-defect` category below is
 for: the coach records it in the committed defect register as a drafted **raw idea** for the
 Betting Table — the debt-free path ("remaining findings + new feedback → new raw idea") — and it

package/skills/orient/SKILL.md

@@ -42,7 +42,8 @@ from `tech-lead`; it never reads or writes a shared run-state file.
 ## Input contract (pure worker)
 
 Orchestrated, you are invoked as `--order <path>` (a WorkOrder): `payload.pitch` (the
-kicked-off pitch path), `payload.stack` (sweep hint), and `substrate.allowed` naming your one
+kicked-off pitch path), `payload.stack` (sweep hint), `payload.spec_folder` (the SHARED spec
+deliverable dir) and `payload.feature` (the run slug), plus `substrate.allowed` naming your one
 write surface — the orient output dir. Anything absent = unknown: confirm at GATE O-A
 (standalone) or report it in the result's `deviations`, never guess. Standalone, the
 `--pitch/--spec/--stack` flags below carry the same fields; the output dir derives from the

package/skills/qa-edge-hunter/SKILL.md

@@ -18,7 +18,7 @@ tech-lead: ... GATE L2 → EVAL → GATE L3 PASS ──► QA EDGE HUNT (you)
             GATE L3 FAIL → fix round (never reaches you — conformance first, edges after)
 ```
 
-**Division of labor (settled at the QA meeting, 2026-06-11):**
+**Division of labor (a settled design decision, not a convention):**
 
 | Tier | Owner | When |
 |---|---|---|
@@ -36,11 +36,11 @@ tech-lead: ... GATE L2 → EVAL → GATE L3 PASS ──► QA EDGE HUNT (you)
 | Execute charters on the **running app** (session-based exploratory) | Read-only speculate from code ("this looks racy") — every finding needs a live repro |
 | Return each finding in the WorkResult's `discoveries[]`, **always `~`** | Promote `~` → must-have (PO/TL at SHIP S.0; severity-hint is advice, not a decision) |
 | Emit `qa/hunt-report.md` — charters run/cut, findings by lens | Render a verdict, score, or PASS/FAIL of any kind |
-| `--recheck`: re-probe ONLY items promoted+fixed after triage | Run a second full hunt in the same cycle; fix code; touch task files; keep run-state |
 
 Pure worker (harness rule: stateless workers, one stateful orchestrator). Its WorkOrder
 carries `payload.feature`, `payload.spec_folder`, `payload.eval_report`, `payload.app_url`,
-`payload.kb_rules_path` (+ read-only ledger path for covered-territory context); its write surface is
+`payload.kb_rules_path`, and `payload.ledger` (the discovery ledger, READ-ONLY — covered-territory
+context so a hunt does not re-report what is already known); its write surface is
 `.shapeup/<feature>/qa/**` only. The Hunter never touches the discovery ledger itself —
 ingest appends its `discoveries[]` under a `## Discovered` section, preserving single-writer
 mechanically.
@@ -272,7 +272,6 @@ an order, the WorkResult envelope `.shapeup/<feature>/results/<order-suffix>.jso
 
 ```markdown
 # Hunt Report — [feature] (round [r], [date])
-mode: [full | degraded | recheck]
 charters: [run]/[approved] · session units spent: [n]
 out of bounds (excluded): […]
 hammered out at GATE Q1 (not hunted): […]
@@ -282,7 +281,8 @@ hammered out at GATE Q1 (not hunted): […]
 |---|---|---|---|
 | ① Boundary | C-01, C-05 | 2 | 0 |
 | … | | | |
-→ details live in .shapeup/<feature>/discovery/ledger.md ## QA Edge Findings (round [r])
+→ details live in .shapeup/<feature>/discovery/ledger.md under the `## Discovered` section
+  ingest appends for this hunt's order
 
 ## Shaping-quality signal (advisory, for the PO — next cycle's input)
 - lens ⑤ findings ≈ No-gos written loosely (breach routes left open)
@@ -298,48 +298,18 @@ No verdict line exists in this file by design. The Hunter's last words:
 
 ---
 
-## `--recheck` mode (after triage promoted + fixed items)
-
-```
-Input: the promoted finding ids (from tech-lead) + the fix round's PASS EVAL report.
-Q0   : hard checks only (app up, new EVAL PASS); no soft check, no charter map.
-Hunt : re-run EXACTLY the recorded repro of each promoted finding — nothing else.
-        fixed   → discoveries[] entry `{ "marker": "~", "line": "[QA-NNN] ✦ fixed r[N], verified" }`
-                  (ingest annotates the ledger — annotate, never delete; the ledger is history)
-        not fixed → `{ "marker": "~", "line": "[QA-NNN] ✦ NOT fixed r[N]", "repro": "<fresh evidence>" }`
-                  back to triage.
-Report: append a `## Recheck (round [r])` section to .shapeup/<feature>/qa/hunt-report.md.
-NEVER a second full hunt in the same cycle — new edges found while rechecking are
-recorded `~` like any finding and wait for triage; they don't restart the loop.
-```
-
----
-
 ## Invocation
 
 ```bash
-# Orchestrated (how tech-lead calls it after first PASS) — the canonical form:
-#   compile-order --operation hunt --slug checkout-vnpay --worker qa-edge-hunter \
-#     --payload '{"eval_report": "…/EVAL-FEATURE-checkout-vnpay.md", "app_url": "http://localhost:3000"}'
-/qa-edge-hunter --order .shapeup/checkout-vnpay/orders/hunt.json
-
-# Standalone flags (the preamble shim compiles the same envelope)
-/qa-edge-hunter --feature checkout-vnpay --spec shapeup/checkout-vnpay/spec/ \
-    --eval .shapeup/checkout-vnpay/evaluation/EVAL-FEATURE-checkout-vnpay.md \
-    --ledger .shapeup/checkout-vnpay/discovery/ledger.md --app http://localhost:3000
-
-# Standalone (same arguments, human-invoked)
 /qa-edge-hunter --feature checkout-vnpay --spec shapeup/checkout-vnpay/spec/ --app http://localhost:3000
 # (--eval/--ledger default to the conventional paths under the LOCAL root .shapeup/<feature>/)
 
-# Recheck after triage promoted + fixed findings
-/qa-edge-hunter --recheck QA-001,QA-004 --feature checkout-vnpay --spec ... --app ...
-
-# Escape hatches
+# Escape hatch
 --auto            # skip GATE Q1 pause (charter list logged, not reviewed) — Q0 hard
                   # checks and the out-of-bounds question are NEVER skipped
---lenses-note     # there is deliberately NO --lenses flag: the 6 lenses are fixed;
-                  # narrow by cutting charters at GATE Q1 (or --auto + report)
+
+# There is deliberately NO --lenses flag: the 6 lenses are fixed; narrow by cutting
+# charters at GATE Q1 (or --auto + report).
 ```
 
 ### Progress Markers

package/skills/scope-architect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scope-architect
-description: "Use this skill to map, remap, or split the vertical scopes of a feature — Shape Up's \"map the scopes\" (step 8) as committed, mechanically enforceable contracts. Triggers on: \"map the scopes\", \"write the scope contracts\", \"scope contract\", \"remap this scope\", \"split this stuck scope\", \"the discovered tasks don't fit any scope\", \"re-slice the substrate\", or a tech-lead --order dispatch (operations map-scopes | remap | split-scope). Writes the committed scopes/*.md contracts by import-graph slicing along business flow, with write-whitelist substrates and e2e fixtures. NOT for decomposing a pitch into tasks (ba-pitch-analyzer) or cutting scope at ship time (scope-hammer)."
+description: "Use this skill to map the vertical scopes of a feature — Shape Up's \"map the scopes\" (step 8) as committed, mechanically enforceable contracts. Triggers on: \"map the scopes\", \"write the scope contracts\", \"scope contract\", \"the discovered tasks don't fit any scope\", \"re-slice the substrate\" (operations map-scopes). Writes the committed scopes/*.md contracts by import-graph slicing along business flow, with write-whitelist substrates and e2e fixtures. NOT for decomposing a pitch into tasks (ba-pitch-analyzer) or cutting scope at ship time (scope-hammer)."
 ---
 
 # Scope Architect (pure worker v1.0)
@@ -19,11 +19,9 @@ anti-rationalization table.
 
 | Field | What it is |
 |---|---|
-| `operation` | `map-scopes` (first slicing after the board exists) · `remap` (fold discovered items into scope contracts) · `split-scope` (re-slice one stuck scope) |
+| `operation` | `map-scopes` — the only operation this skill has. It covers first slicing after the board exists, folding discovered items in, and re-slicing a stuck scope; the payload says which of those you are doing |
 | `payload.feature` / `payload.spec_folder` | Slug + committed spec (read ux-behavior.md for manifests; usecases for flows) |
 | `payload.tasks[]` | The board's tasks with their touched files — the slicing input |
-| `payload.discovered_ledger` | (remap) items that fit no existing substrate |
-| `payload.scope_id` | (split-scope) the stuck scope (`rounds_at_position ≥ 3`, or an approved substrate-expansion) |
 | `substrate.allowed` | `scopes/*.md` + `scope-board.md` — your ONLY write surface |
 
 ## Core process
@@ -59,17 +57,17 @@ anti-rationalization table.
                                                                a fixture for unbuilt behavior
              hill_phase: "UPHILL_UNKNOWN"                    — ALWAYS; phase is derived from
                                                                T0/T1/seesaw facts later,
-                                                               never authored (DD-10)
+                                                               never authored
 4 LINT     node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/spec-lint.mjs" --slug <slug>
            → PA1 (directory alignment), PA2 (>~15 files), DISJOINT (undeclared overlap).
            Fix reds by re-slicing, not by silencing.
 5 BOARD    regenerate scope-board.md (scope_id, topology, task count, substrate size, lint)
 ```
 
-**remap:** a discovered item joins the nearest scope only if the flow matches (extend that
+**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.
-**split-scope:** re-run step 1 on just that scope's task+file set → N new contracts; mark the
-old one `superseded_by: [ids]` — never delete (branch and T0 history stay attributable).
+**Re-slicing a stuck scope:** re-run step 1 on just that scope's task+file set → N new contracts;
+mark the old one `superseded_by: [ids]` — never delete (branch and T0 history stay attributable).
 
 ## Anti-rationalization table
 
@@ -84,10 +82,17 @@ old one `superseded_by: [ids]` — never delete (branch and T0 history stay attr
 
 ## Output contract — the WorkResult
 
+**Escalation rule.** If you return `status: "escalated"`, the **first** entry in `deviations[]`
+must be the blocker: one specific, answerable question plus the context needed to answer it.
+Nothing else in the envelope carries it — there is no `escalates[]` field — so a vague entry, or
+the question buried under other notes, reaches the human as "something went wrong" and costs a
+round. Write it so someone without your context can answer it in one reply.
+
+
 `scopes/*.md` + `scope-board.md` in your substrate, then
 `.shapeup/<slug>/results/<order-suffix>.json`: `status`, `artifacts[]` (the contracts
-written/superseded), `escalates[]` (e.g. a discovered item implying a new UC — the planner's
-territory), `deviations[]` (any lint warn left standing and why). You never touch task files,
+written/superseded), `deviations[]` (e.g. a discovered item implying a new UC — the planner's
+territory — and any lint warn left standing, with why). You never touch task files,
 `tasks/_index.md`, spec docs, or run-state.
 
 ## Verification checklist
@@ -102,10 +107,10 @@ territory), `deviations[]` (any lint warn left standing and why). You never touc
 ## Invocation
 
 ```bash
-# Orchestrated — compile-order --operation map-scopes|remap|split-scope --worker scope-architect …
+# Orchestrated — compile-order --operation map-scopes --worker scope-architect …
 /scope-architect --order .shapeup/checkout-vnpay/orders/map-scopes.json
 
 # Standalone shims (compile the same envelope)
 /scope-architect --map shapeup/checkout-vnpay/
-/scope-architect --split cart-creation shapeup/checkout-vnpay/
+/scope-architect --map --split cart-creation shapeup/checkout-vnpay/   # re-slice one scope
 ```

package/skills/scope-hammer/SKILL.md

@@ -11,7 +11,7 @@ live with today — not to a hypothetical perfect version. "Better than the base
 enough to ship; "not as good as I imagined" is not a reason to keep building.
 
 **Why this is its own skill, not tech-lead prose.** GATE H census pulls from several sources
-that accumulate over a whole run (QA findings, discovered-task ledger, advisor-protocol budget
+that accumulate over a whole run (QA findings, discovered-task ledger, attempt-budget
 overflows, per-scope inner-breaker trips) — a genuinely separate synthesis step from
 orchestration. Splitting it out keeps `tech-lead` thin (it dispatches, this skill decides what
 survives the hammer) and gives the census/cut-list/verdict logic one owner instead of being
@@ -22,10 +22,10 @@ re-derived inline at every SHIP.
 ## When this fires
 
 ```
-1. All scopes reach FINISHED on the hill (design spec B2) → normal stop, post-QA-hunt.
+1. All scopes reach FINISHED on the hill → normal stop, post-QA-hunt.
 2. Outer circuit breaker trips: round_budget reaches 0 with scopes still uphill/downhill.
 3. Inner circuit breaker trips: a scope's attempt_budget (default 5) is exhausted without a
-   T0-green result → queued as a hammer PROPOSAL (design spec Blueprint A `hammer_proposals`),
+   T0-green result → queued as a hammer PROPOSAL (`hammer_proposals`),
    judged here rather than immediately blocking the round.
 ```
 Any of the three routes to this skill; the difference is only what's in the census (case 1 has
@@ -63,7 +63,7 @@ H0.1  Unresolved scopes (breaker cases only):
           with the T0 failure that stalled them (from the last red t0/verdicts/*.json)
 H0.2  QA findings (qa-edge-hunter's hunt-report.md, when present) — all `~` by default.
 H0.3  Discovered-task ledger entries still open (discovery/ledger.md, `[+]`/`~` unresolved).
-H0.4  advisor-protocol budget-overflow flags (auto-resolved ESCALATEs logged for GATE H review).
+H0.4  Attempt-budget hammer proposals (scopes that exhausted their T0 attempts during BUILD).
 H0.5  Classify every item: MUST-HAVE (the pitch's core problem is unsolved without it) vs
       NICE-TO-HAVE (`~`, improves but doesn't block the core promise). Default to NICE-TO-HAVE
       unless the item traces directly to a pitch boundary or a scope's business_goal — a
@@ -87,7 +87,7 @@ customer suffers through today), never to a perfect ideal.
 
 ```
 H1.1  Resolve the baseline: shapeup/<slug>/shaping/baseline.md if present (written at
-      shaping time, design spec Blueprint F — first-class, not a pitch footnote). Absent →
+      shaping time — first-class, not a pitch footnote). Absent →
       degrade honestly: read the pitch's problem statement as the implicit baseline and flag
       "baseline not first-class — comparison is approximate" in the report. Do not invent one.
 H1.2  For each MUST-HAVE item from H0: "with this item cut/carried, is the shipped product

package/skills/shapeup/SKILL.md

@@ -33,7 +33,7 @@ This skill lazily loads detail from resource files. **Read the relevant resource
 | `/shapeup breadboard-reflection` | `resources/breadboard-reflection.md` |
 | `/shapeup full` | Read `resources/shaping.md` first, then `resources/breadboarding.md` before B-phases, and `resources/context-compaction.md` for the run digest |
 
-> Resource paths are relative to this skill's directory. In Claude Code: `.claude/skills/shapeup/resources/`.
+> Resource paths are relative to this skill's directory (`resources/` beside this SKILL.md, wherever the plugin is installed).
 > Multi-gate runs maintain a derived **decision digest** so each gate reads a compact slice instead of full prose — see `resources/context-compaction.md` and the "Run Workspace & Digest" section below.
 
 ---
@@ -374,8 +374,8 @@ Two roots, separated by artifact **nature** (full design →
 - **Shared** root `shapeup/[slug]/` = what the team contributes to
   (source + deliverable). **Local** root `.shapeup/[slug]/` = per-run scratch,
   hidden and fully gitignorable. Add **one** line to `.gitignore`: `.shapeup/`.
-  No carve-out needed — the one committed report surface, the harvest feed
-  `shapeup/metrics.jsonl`, lives in the shared root.
+  No carve-out needed — everything machine-written at run time, including the
+  harvest shards `.shapeup/metrics/*.jsonl`, lives under the local root.
 - `digest.md` is the run's derived decision context (the 4-field, two-zone read
   model the gates consume). It is **never** the source of truth and never crosses
   a skill boundary — `ba-pitch-analyzer` reads `pitch.md`/`shaping.md`, never the

package/skills/shapeup/resources/context-compaction.md

@@ -182,9 +182,10 @@ Everything keys off the feature `<slug>`. Two roots, split by **who needs it**:
 - The **local** root `.shapeup/[slug]/` is per-run scratch + reports — hidden,
   fully gitignorable, dies with the run. It is derived from the same `<slug>`.
 - `.gitignore`: one line — `.shapeup/`. The whole local root is ignored; no
-  carve-out is needed because the one committed report surface, the harvested
-  signal feed `shapeup/metrics.jsonl` (written by the tech-lead at SHIP,
-  fact-only; see the tech-lead skill's SHIP step), lives in the **shared** root.
+  carve-out is needed because everything machine-written at run time lives there,
+  including the harvested signal shards `.shapeup/metrics/*.jsonl` (written by
+  the tech-lead at SHIP, fact-only; see the tech-lead skill's SHIP step). The
+  committed report surface is the frozen `shapeup/[slug]/REPORT.md`.
 - All paths are **project-relative, resolved from the project root / cwd.** Never
   `/mnt/...` — that is the claude.ai authoring sandbox and dies in a user repo.
 

package/skills/solution-architect/SKILL.md

@@ -7,9 +7,9 @@ description: "Use this skill to design how each use-case's engine integrates int
 
 **Design the seam, or the engine ships orphaned.**
 
-The audit that motivated this skill found a 631-line asset pipeline with 26 passing tests and
-**zero call sites** in the app's composition root — built, green, and unreachable from the
-running application. Five more scopes had engines never wired to a player. This skill closes that
+This skill exists because a sizeable engine module can be built, fully tested, and still have
+**zero call sites** in the app's composition root — green, and unreachable from the
+running application; observed across multiple scopes in one run, not theorized. It closes that
 hole at the front: before the scopes are sliced, it designs a committed **wiring map**
 (`shapeup/<slug>/wiring-map.md`) that names, for every use case, the chain from the
 engine module to a player-visible affordance — including **how** and **where** the engine attaches
@@ -29,7 +29,7 @@ Two payoffs, one artifact:
   proving.
 - **The slicer gets its integration seam up front.** Declaring each attachment *before*
   `scope-architect` runs supplies the missing input behind the round-1 substrate-expansion
-  escalations — the four identical "declined by precedent" stalls. (This skill *front-loads* the
+  escalations — repeated identical "declined by precedent" stalls. (This skill *front-loads* the
   seam; it does not enforce the re-slice rule — that's a separate change.)
 
 You are the **sole writer** of the wiring map, written **directly** (the same authority
@@ -73,14 +73,14 @@ guessed `main.js` would make the later oracle certify nothing.
 3 WRITE    shapeup/<slug>/wiring-map.md (WiringMap): {schema_version:1, feature,
            entry_point (echo of the profile), entries[]}. One entry per use case. A UC whose
            engine has no attachment path is exactly the gap this artifact exists to surface —
-           write the entry with the seam you INTEND and raise it in deviations[]/escalates[], so
+           write the entry with the seam you INTEND and raise it in deviations[], so
            the build knows the wiring it must close. Your craft ends here: WRITE, then return the
            WorkResult. You do not run trace-lint — the orchestrator runs it advisory at L1b.
 ```
 
 **No use case is exempt.** If a UC's engine genuinely has no player-facing seam (a pure
 background job), say so in `wiring_seam` and name the boot/cron/init attachment that starts it — a
-cron registration, a boot hook. "It's internal" is how the asset pipeline stayed orphaned; there
+cron registration, a boot hook. "It's internal" is how an engine stays orphaned; there
 is always an attachment to the entry point, or the code never runs.
 
 ## Anti-rationalization table
@@ -96,11 +96,18 @@ is always an attachment to the entry point, or the code never runs.
 
 ## Output contract — the WorkResult
 
+**Escalation rule.** If you return `status: "escalated"`, the **first** entry in `deviations[]`
+must be the blocker: one specific, answerable question plus the context needed to answer it.
+Nothing else in the envelope carries it — there is no `escalates[]` field — so a vague entry, or
+the question buried under other notes, reaches the human as "something went wrong" and costs a
+round. Write it so someone without your context can answer it in one reply.
+
+
 `wiring-map.md` in your substrate, then `.shapeup/<slug>/results/<order-suffix>.json`:
-`status`, `artifacts[]` (the wiring map written), `escalates[]` (e.g. a missing profile, or a UC
-whose engine the spec never names — the planner's territory), `assumptions[]` (engine paths
-inferred from the domain model where the spec was silent), `deviations[]` (any UC left with an
-uncertain seam, or an engine with no attachment path, and why). You never touch spec docs,
+`status`, `artifacts[]` (the wiring map written), `assumptions[]` (engine paths
+inferred from the domain model where the spec was silent), `deviations[]` (a missing profile, a
+UC whose engine the spec never names — the planner's territory — a UC left with an uncertain
+seam, or an engine with no attachment path, and why). You never touch spec docs,
 `scopes/*.md`, `project-profile.md`, task files, or run-state.
 
 ## Verification checklist
@@ -110,7 +117,7 @@ uncertain seam, or an engine with no attachment path, and why). You never touch
 - [ ] `entry_call_site` is a symbolic composition-root attachment resolved against the profile's `entry_point` — no invented line number, no guessed entry point
 - [ ] `entry_point` echoes the profile — no independently-chosen seam
 - [ ] The profile was READ, not guessed; a missing profile in orchestrated mode → ESCALATE, not an invented entry point
-- [ ] Any UC whose engine has no attachment path is raised in `deviations[]`/`escalates[]` (the wiring the build must close), never silently dropped
+- [ ] Any UC whose engine has no attachment path is raised in `deviations[]` (the wiring the build must close), never silently dropped
 - [ ] The WorkResult validates against `work-result.schema.json`
 
 ## Invocation

package/skills/spec-evaluator/SKILL.md

@@ -116,6 +116,13 @@ Done-when statements; `_index.md` Non-Go list. Which UCs are in scope comes from
 
 ## Output contract — the WorkResult
 
+**Escalation rule.** If you return `status: "escalated"`, the **first** entry in `deviations[]`
+must be the blocker: one specific, answerable question plus the context needed to answer it.
+Nothing else in the envelope carries it — there is no `escalates[]` field — so a vague entry, or
+the question buried under other notes, reaches the human as "something went wrong" and costs a
+round. Write it so someone without your context can answer it in one reply.
+
+
 1. Write the report `.shapeup/<slug>/evaluation/EVAL-FEATURE-<slug>.md` (or
    `EVAL-<task_id>.md` for a per-task run) per `references/report-schema.md`: verdict,
    per-dimension criteria table with confidence, stability block (flips), bug list (severity,
@@ -143,10 +150,10 @@ Done-when statements; `_index.md` Non-Go list. Which UCs are in scope comes from
 ```
 
 **Every FAIL criterion's `evidence` MUST carry a `file:line` locator** — schema-enforced, not
-advice: `validate-envelope` rejects the whole result before ingest sees it. A PASS may cite plain
-output. (Measured: a run returned a correct FAIL with `bugs: null` and no locator anywhere, which
-is unactionable without re-investigating. The rule used to be repeated five times in this prompt
-and enforced nowhere; it is now stated once and enforced by `domain.schema.json`.)
+advice: the envelope is validated against `work-result.schema.json` at ingest and a locatorless
+FAIL is rejected before any write. A PASS may cite plain output. (Observed, not theorized: a
+correct FAIL verdict with no locator anywhere is unactionable without re-investigating — the
+rule used to live in prose and be enforced nowhere; it is now data in `domain.schema.json`.)
 
 The orchestrator's ingest appends the verdict ledger, un-ticks the `refuted` boxes, and sets
 `eval_verdict` frontmatter. You never touch a task file, a board, or run-state — and you
@@ -209,5 +216,5 @@ summary — standalone has no orchestrator to ingest for you.
 | Probe the RUNNING app, not the source alone | Apps that look right still break when used |
 | Re-probe every FAIL; flip ⇒ confidence low | A single snapshot lies; the ledger makes it visible |
 | Verdict-ledger lines are returned, appended by ingest, never rewritten | Verdict history is how a single-snapshot judge becomes measurable |
-| A verdict on a scoped spec without a T0 citation is structurally invalid | T0 is a machine fact the generator cannot fabricate (DD-7, PA4) |
+| A verdict on a scoped spec without a T0 citation is structurally invalid | T0 is a machine fact the generator cannot fabricate |
 | UI assertions target affordances only (test_id/role/data-state) | Layer-3 styling is frozen; grading it resurrects the freeze through the judge |