shapeup-sdlc 1.6.2

package/skills/scope-architect/SKILL.md

@@ -0,0 +1,111 @@
+---
+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)."
+---
+
+# Scope Architect (pure worker v1.0)
+
+**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`) the rest of the
+harness enforces mechanically: the sandbox hook denies writes outside a substrate, t0-verify
+runs the fixtures, the evaluator asserts only against the affordance manifest. This skill is
+the **sole writer** of scope contracts — a distinct authority from the planner (task
+decomposition) and a distinct failure mode (directory-thinking, PA1) deserving its own
+anti-rationalization table.
+
+## Input contract — the WorkOrder
+
+| 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) |
+| `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
+
+```
+1 SLICE    build an import/business-flow graph over the tasks' touched files (grep heuristic
+           is fine; AST is an optimization). One scope = one call chain: the UI screen + the
+           API route + the use case + the repository it drives. Scopes aligning 1:1 with a
+           top-level directory (all-frontend, all-backend) FAIL — 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 (ADR-0001): frontmatter for
+           scalars and [a, b] lists, a `## Affordances` table for affordance_manifest, and 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.
+             scope_id, topology_type, tasks[]                — the stable join key is the scope
+             allowed_file_substrate[]                        — exact globs; the sandbox hook's
+                                                               write-whitelist; wrong here =
+                                                               a legitimate ESCALATE later
+             shared_substrate[]                              — files ≥2 scopes both touch;
+                                                               every write there forces a full
+                                                               seesaw run at the next gate
+             affordance_manifest                             — from ux-behavior.md state
+                                                               tables: every interactive
+                                                               element as {test_id, role} +
+                                                               required_states [idle, loading,
+                                                               success, error, empty]
+             e2e_verification_fixtures[]                     — the command(s)/spec file(s)
+                                                               that drive this scope
+                                                               end-to-end (T0 layer); too
+                                                               speculative to fixture → mark
+                                                               TBD and flag it, never invent
+                                                               a fixture for unbuilt behavior
+             hill_phase: "UPHILL_UNKNOWN"                    — ALWAYS; phase is derived from
+                                                               T0/T1/seesaw facts later,
+                                                               never authored (DD-10)
+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
+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).
+
+## Anti-rationalization table
+
+| 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's PA1 — a layer, not a flow. A scope must ship something a user can do. |
+| "I'll widen the substrate a little 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. |
+| "Fixtures can come later, leave the field empty" | Fixture at contract time or an explicit TBD flag — silence is how T0 goes blind. |
+
+## Output contract — the WorkResult
+
+`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,
+`tasks/_index.md`, spec docs, or run-state.
+
+## Verification checklist
+
+- [ ] Every scope crosses layers or is declared CHOWDER; spec-lint PA1 = 0 red
+- [ ] Substrates disjoint except declared shared_substrate (DISJOINT = 0 red)
+- [ ] Every interactive element in scope screens appears in exactly one affordance_manifest
+- [ ] Every scope has fixtures or an explicit TBD flag
+- [ ] Every hill_phase written is UPHILL_UNKNOWN; superseded contracts kept
+- [ ] The WorkResult validates against `work-result.schema.json`
+
+## Invocation
+
+```bash
+# Orchestrated — compile-order --operation map-scopes|remap|split-scope --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/
+```

package/skills/scope-hammer/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: scope-hammer
+description: "Use this skill whenever a Shape Up build run reaches its stop condition — the circuit breaker (round budget or a scope's attempt budget) trips, or all scopes finish and it's time to decide when to stop (step 11) — and needs a must-have census, a baseline-anchored cut list, and a ship verdict. Trigger on: \"scope hammer\", \"hammer this down to must-haves\", \"decide when to stop\", \"cut list vs baseline\", \"circuit breaker tripped, what do we ship\", \"compare against the baseline not the ideal\", \"GATE H\", \"census the open items\". Also triggers on tech-lead's GATE H at SHIP. Compares the product to the pitch's baseline (what customers live with today, not a perfect ideal) and returns a cut list + ship verdict."
+---
+
+# Scope Hammer (GATE H — Decide When to Stop)
+
+The mechanism behind Shape Up step 11: as the appetite/round budget runs out, cut back on
+perfectionist ambitions by comparing the *actual* product to the **baseline** — what customers
+live with today — not to a hypothetical perfect version. "Better than the baseline" is good
+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
+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
+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.
+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`),
+   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
+no unresolved scopes; cases 2/3 do, and those become explicit CUT or CARRY candidates below).
+
+---
+
+## Workflow
+
+```
+INPUT: run's finished/unfinished scopes + baseline + census sources
+          │
+⏸ GATE H0 │  Census ──────────────► collect every open item, classify must-have / nice-to-have
+          │
+⏸ GATE H1 │  Baseline Comparison ──► for each unresolved must-have, is the product still
+          │                          better than the baseline without it?
+          │
+⏸ GATE H2 │  Cut List & Verdict ───► propose cuts (PO confirms), ship / carry-to-next-cycle verdict
+          │
+✅ Done   └─► cut list + verdict handed to tech-lead SHIP; PO owns the final call
+```
+
+---
+
+## GATE H0 — Census
+
+**Purpose:** Gather every open item into one list before judging any of them. Never judge
+piecemeal — a partial view produces a wrong cut.
+
+```
+H0.1  Unresolved scopes (breaker cases only):
+        - uphill/downhill scopes when round_budget hit 0 → CARRY candidates (their own hill
+          phase + open unknowns, from hill/<scope-id>.yml)
+        - scopes with hammer_proposals (attempt_budget exhausted) → CARRY candidates, tagged
+          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.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
+      generous must-have list defeats the point of hammering.
+```
+
+**GATE H0 Output:**
+```
+⏸ GATE H0 — Census
+Must-have (unresolved)  : [N] — [list, each with source: scope | QA | discovered | advisor-overflow]
+Nice-to-have (~)        : [M]
+Carry candidates        : [scopes still uphill/downhill, or exhausted attempt budget]
+```
+
+---
+
+## GATE H1 — Baseline Comparison
+
+**Purpose:** The trade-off algorithm from step 11 — compare to the baseline (status quo the
+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 →
+      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
+      still strictly better than the baseline for the pitch's core problem?"
+        YES → safe to cut/carry — demote to a cut-list candidate anyway (H2 still asks the PO).
+        NO  → this one item blocks shipping as-is; it is not hammer-cuttable. Options are:
+              fix it now (one more focused attempt, not a full extra round) or the run
+              genuinely fails the appetite — escalate to PO honestly, do not ship anyway.
+H1.3  NICE-TO-HAVE items never block H1 — they are cut-list candidates by construction.
+```
+
+---
+
+## GATE H2 — Cut List & Verdict
+
+**Purpose:** Turn H0+H1 into a decision, owned by the PO — this skill proposes, it never cuts
+unilaterally.
+
+```
+⏸ GATE H2 — Cut List & Verdict
+Baseline      : [shapeup/<slug>/shaping/baseline.md | approximate — pitch problem statement]
+Ship-blocking : [none | list of MUST-HAVE items that fail H1.2 — these are NOT cuttable]
+Proposed cuts : [N nice-to-have + N cuttable must-have, each: item — source — one-line why safe]
+Carry-forward : [scopes/items proposed for the next cycle's raw-idea list, debt-free]
+Verdict       : [SHIP now | SHIP after fixing ship-blocking items | CANNOT SHIP — escalate to PO]
+```
+Ask (max 1): "Confirm this cut list? (approve all / list ids to keep / none)". PO can keep any
+proposed cut — this skill never overrides that. On confirm, everything NOT kept becomes:
+- Nice-to-haves + safe must-have cuts → carried to the discovery ledger as raw ideas
+  (debt-free — never silently dropped, never silently promoted back into scope).
+- Ship-blocking items (if any survived because PO overrode SHIP anyway) → logged explicitly
+  as a known gap in the ship report, never hidden.
+
+Authority boundary: this skill produces the proposal; `tech-lead` records the PO's decision in
+the round-ledger and performs the actual SHIP close. Scope-hammer does not write status: done,
+does not deploy, and does not itself decide to ship — same judge/doer separation as the rest of
+the harness (this is neither the generator nor the evaluator).
+
+---
+
+## Envelope contract — the domain layer
+
+Orchestrated, this skill is dispatched like every worker: a **WorkOrder** in (`--order <path>`,
+operation `hammer`), a **WorkResult** out. The standalone flags below map 1:1 onto the payload
+fields registered for this worker in the central domain registry
+(`skills/tech-lead/schemas/domain.schema.json`, `x-payload-by-worker`):
+
+| Payload field | Standalone flag | Meaning |
+|---|---|---|
+| `payload.feature` | `--slug` | The feature slug (resolves scopes/, hill/, ledger paths) |
+| `payload.baseline` | `--baseline` | `shaping/baseline.md` — comparison anchor (absent → the pitch's problem statement, flagged approximate) |
+| `payload.breaker` | `--breaker` | `outer` \| `inner` — which circuit breaker fired (absent = normal stop) |
+| `payload.scope_id` | `--scope` | With `--breaker inner`, the scope whose attempt budget was exhausted |
+
+The WorkResult may carry only `files_touched`, `artifacts`, `assumptions`, `deviations`
+(`x-result-by-worker`): the census, cut list, and ship verdict live in the report artifact as a
+**proposal** — promotion and shipping stay a human call, never envelope data ingest acts on.
+
+---
+
+## Invocation
+
+```bash
+# Normal stop — all scopes FINISHED, after QA hunt
+/scope-hammer --slug checkout-vnpay --baseline shapeup/checkout-vnpay/shaping/baseline.md
+
+# Circuit breaker tripped — some scopes still open
+/scope-hammer --slug checkout-vnpay --breaker outer   # round_budget exhausted
+/scope-hammer --slug checkout-vnpay --breaker inner --scope cart-creation   # attempt_budget exhausted
+
+# Headless — no PO available; still refuses to auto-ship a ship-blocking item
+/scope-hammer --slug checkout-vnpay --unattended
+```
+
+### Flags
+| Flag | Effect |
+|------|--------|
+| `--slug <name>` | The run's feature slug (resolves scopes/, hill/, ledger paths) |
+| `--baseline <path>` | Explicit baseline doc (default: `shaping/baseline.md`, else approximate) |
+| `--breaker outer\|inner` | Which circuit breaker triggered this call (changes H0.1 census scope) |
+| `--scope <id>` | With `--breaker inner`, the scope whose attempt budget was exhausted |
+| `--unattended` | No PO available — still HARD STOPS rather than auto-shipping a ship-blocking item |
+
+---
+
+## Hard Rules (never override without explicit user instruction)
+
+| Rule | Rationale |
+|------|-----------|
+| Compare to the baseline, never to a perfect ideal | Step 11's actual trade-off algorithm — "better than what customers live with today" is the bar |
+| Default classification is NICE-TO-HAVE unless traced to a pitch boundary or business_goal | A generous must-have list defeats the point of hammering |
+| A MUST-HAVE that fails H1.2 is never cut silently | The one case where scope-hammer refuses to make the run "look" shippable |
+| Cuts are proposals; the PO confirms every one | This skill never overrides the human at the ship gate |
+| Cut items are carried to the discovery ledger, never silently dropped | Cool-down must stay debt-free — an idea deferred is still recorded |
+| Never sets status: done, never deploys, never ships unilaterally | Judge/doer/advisor separation holds even at the very last gate |
+| An overridden ship-blocking item is logged explicitly in the ship report | "Shipped" must never quietly mean "shipped with a known must-have gap" |