shapeup-sdlc 3.18.2 → 4.0.0

package/skills/scope-architect/SKILL.md

@@ -1,174 +0,0 @@
----
-name: scope-architect
-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)
-
-**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
-the ship report's census table.
-
-## Input contract — the WorkOrder
-
-**Kernel commands.** `<kernel>` below is the absolute path in your order's `kernel` field: run every kernel command as `node "<kernel>" …`. Never spell it `${CLAUDE_PLUGIN_ROOT}` — a command carrying a variable is refused in a headless session before any permission rule is read, and the query your contract requires never runs. With no order (invoked by hand), the kernel is `kernel/harness.mjs` two directories above this skill's base directory.
-
-| Field | What it is |
-|---|---|
-| `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.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` (your write surface — `scope-summary.md` is the planner's) |
-| `payload.tasks[]` | The board's tasks with their touched files — the slicing INPUT only. Each carries `use_case_refs`; those UC ids are what you write into the contract. Never copy a task id into a contract |
-| `payload.kb_rules_path` | Team guidelines (read if the file exists) — 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, noted in `deviations` |
-| `substrate.allowed` | `scopes/*.md` + `scope-board.md` — your ONLY write surface |
-
-## Core process
-
-```
-0 READ     the team guidelines at payload.kb_rules_path, if the file exists — they aim the
-           slicing and name the config seams that must have one owner; absent = none recorded.
-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.
-           ► 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 copy 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 — the board green, the contract
-             lint-clean, each leg reporting done with no error, every round, until EVAL refused
-             to grade a round whose scopes had never run. 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.
-             scope_id, topology_type                         — the stable join key is the scope
-             use_cases[]                                     — the UC 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-NNN here dangles on
-                                                               every other clone (spec-lint
-                                                               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; stable, never renumbered.
-                                                               WRITE THE REGISTRY'S OWN KEY:
-                                                               `REQ-12`, not the pitch's `R12`.
-                                                               Both resolve — readers normalise —
-                                                               but one spelling in the committed
-                                                               contract is one thing to read
-             depends_on[]                                    — scope_ids this scope builds AFTER.
-                                                               This is the build ORDER — declare
-                                                               it whenever one scope consumes
-                                                               another's output, or the two race
-             allowed_file_substrate[]                        — exact globs; the sandbox hook's
-                                                               write-whitelist; wrong here =
-                                                               a legitimate ESCALATE later
-             shared_substrate[]                              — files ≥2 scopes both touch;
-                                                               declaring one costs concurrency:
-                                                               they build one at a time
-             affordance_manifest                             — from ux-behavior.md state
-                                                               tables: every interactive
-                                                               element as {test_id, role} +
-                                                               required_states [idle, loading,
-                                                               success, error, empty]
-                                                               + `source` — the U# the
-                                                               ux-behavior row cites
-             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 facts later,
-                                                               never authored
-4 LINT     node "<kernel>" verify spec --slug <slug>
-           → PA1 (directory alignment), PA2 (>~15 files), DISJOINT (undeclared overlap),
-           SCOPE-ANCHOR (empty/unresolvable use_cases), TIER-DIRECTION (a task id in a
-           committed contract), SCOPE-DEPS (depends_on naming a scope that isn't here).
-           Fix reds by re-slicing, not by silencing.
-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` and
-           `probe resume` derives them at dispatch — a hand-written copy of a derived value drifts,
-           which is exactly why `unlocks` stopped being authored. The BUILD ORDER lives in each
-           contract's `depends_on`; the board only shows it.
-
-           A `TASK-` id anywhere in a contract or the board — a column, a cell, or a sentence in
-           the prose — is spec-lint TIER-DIRECTION red. The board is committed; 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+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. |
-| "Both scopes implement that UC, the tasks will sort themselves out" | They will not — both scopes get every task of that UC and three of four writes get denied. Give each scope its own use cases, or say so in deviations[] so the board can be stamped. |
-| "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 UCs — the tasks are re-derived from them. |
-| "Build order is obvious from the slice, I'll leave depends_on empty" | Nothing infers it any more. An undeclared edge means the two scopes are released into the same wave and race. |
-| "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
-
-**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), `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
-
-- [ ] Every scope crosses layers or is declared CHOWDER; spec-lint 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 disjoint except declared shared_substrate (DISJOINT = 0 red)
-- [ ] Every interactive element in scope screens appears in exactly one affordance_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 kept
-- [ ] The WorkResult validates against `work-result.schema.json`
-
-## Invocation
-
-```bash
-# 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 --map --split cart-creation shapeup/checkout-vnpay/   # re-slice one scope
-```

package/skills/scope-hammer/SKILL.md

@@ -1,231 +0,0 @@
----
-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, 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
-re-derived inline at every SHIP.
-
----
-
-## When this fires
-
-```
-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 (`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
-
-**Kernel commands.** `<kernel>` below is the absolute path in your order's `kernel` field: run every kernel command as `node "<kernel>" …`. Never spell it `${CLAUDE_PLUGIN_ROOT}` — a command carrying a variable is refused in a headless session before any permission rule is read, and the query your contract requires never runs. With no order (invoked by hand), the kernel is `kernel/harness.mjs` two directories above this skill's base directory.
-
-**Purpose:** Gather every open item into one list before judging any of them. Never judge
-piecemeal — a partial view produces a wrong cut.
-
-```
-H0.0  Ownership is DERIVED, never stated. Before the census says "no scope owns X" or "X is
-      scope Y's", run
-        node "<kernel>" probe owner --slug <slug> [--path <p>]...
-      and cite its row. With no --path it answers for every engine and entry call site the wiring
-      map names plus the profile's entry point; `writers: []` is an unowned seam and `missing`
-      lists seams the wiring names that are not on disk — owned but never written. A census that
-      narrated ownership from memory once told the PO no scope owned a screen directory that a
-      committed contract listed in plain sight — and pointed the ship decision at the wrong gap.
-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. Exhaustion
-          is DERIVED, never read off `t0/verdicts/*.json` directly — a compiled order or a T0
-          verdict is writable by the very scope being judged and proves nothing on its own. Run
-            node "<kernel>" probe attempts --slug <slug> \
-              --scope <scope-id> --round <n> --attempt-budget <n>
-          and cite its `spent`/`tripped` fields (exit 1 = tripped) — an attempt counts only when a
-          dispatch receipt AND either a leg-completion row or a WorkResult attest it, so a leg still
-          in flight holds it open rather than reading as exhausted. This is the SAME derivation the
-          round loop's own inner breaker reads, so the census and the breaker cannot disagree about
-          the same exhaustion the way a live run once measured.
-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  Attempt-budget hammer proposals (scopes that exhausted their T0 attempts during BUILD).
-H0.4b Requirements with no PASS evidence — the pitch clauses the run never showed working. Run
-        node "<kernel>" probe requirements --slug <slug> --format table
-      and take its `no evidence` rows; cite the row, the same way H0.0 cites ownership. Each is a
-      census item carrying its source clause (`REQ-12 ← shaping.md R12`). A `cut` row is an answer
-      the PO already gave — not an item. An inconsistency row (a criterion anchored to a
-      requirement no acceptance criterion covers) is reported to the PO as a reconciliation, never
-      counted as evidence and never promoted as a finding. No registry on disk → this input is
-      empty and the census is unchanged (absent artifact ⇒ arm skipped).
-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 | requirement |
-                                 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 — 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
-(`kernel/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.
-
-**The census is also written as data**, at `.shapeup/<slug>/reports/hammer-census.json` (inside
-this operation's substrate), shape `HammerCensus` in the domain registry:
-
-```json
-{ "schema_version": 1, "order_id": "<the order>", "verdict": "ship-now | ship-after-fixes | cannot-ship",
-  "cut_list": ["…"], "ship_blocking": ["…"], "breaker": "outer | inner | deadline | null", "baseline": "<path or null>" }
-```
-
-GATE L4's resolver reads this file — and nothing else — before it lets any answer set say `ship`.
-It is the same proposal as the H2 block, written by the same hand, in a shape a gate can read:
-a census that lives only in printed blocks cannot be read by a gate, and a run that reached L4
-with a green census could only be recorded as `ask`. Still a proposal: the file grants nothing.
-
----
-
-## 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
-
-# The ownership query every census claim cites (H0.0)
-node "<kernel>" probe owner --slug checkout-vnpay --format table
-node "<kernel>" probe owner --slug checkout-vnpay --path src/pages/Cart.ets
-```
-
-### 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 |
-| Every ownership claim in the census cites `harness probe owner` | Ownership is what the contracts' substrates say — the same election `harness compile` uses to address a bug — never what the report remembers |
-| 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" |

package/skills/solution-architect/SKILL.md

@@ -1,158 +0,0 @@
----
-name: solution-architect
-description: "Use this skill to design how each use-case's engine integrates into the running application — the wiring map that guarantees no engine ships orphaned. Triggers on: \"write the wiring map\", \"declare the integration seam for each use case\", \"how does each use case get wired in\", \"map engines to the entry point\", \"which use cases are reachable from the composition root\", \"the asset pipeline has zero call sites\", \"front-load the integration seam before we slice scopes\", or a tech-lead --order dispatch (operation wire) at gate L1a.5. Writes the per-use-case wiring map: engine → integration seam → composition-root attachment → player-visible affordance, resolved against the project profile's entry_point. NOT for slicing scopes (scope-architect) or decomposing a pitch into tasks (ba-pitch-analyzer)."
----
-
-# Solution Architect (pure worker v1.1)
-
-**Design the seam, or the engine ships orphaned.**
-
-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
-to the application's entry point.
-
-You work at **design time (gate L1a.5), before any code exists.** Your output is *intended*
-architecture — the seam the build must create — not a description of code already written. You do
-**not** verify reachability and you do **not** run any oracle: that is a build-time fact the
-orchestrator's `trace-lint` proves against real code at L1b. Your job is to make the seam
-*explicit and buildable*.
-
-Two payoffs, one artifact:
-- **Reachability becomes checkable later.** Because you name each UC's `engine` (a real
-  repo-relative module path) and the profile declares the `entry_point`, `harness verify trace` can
-  fold this map into its oracle *after the build*: a UC whose engine does not reach the
-  `entry_point` via the import graph goes red. You supply the two anchors; the oracle does the
-  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 — 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
-`scope-architect` has over `scopes/*.md` — you bypass `ingest-result`). Everything else you
-return as a WorkResult.
-
-## Input contract — the WorkOrder
-
-**Kernel commands.** `<kernel>` below is the absolute path in your order's `kernel` field: run every kernel command as `node "<kernel>" …`. Never spell it `${CLAUDE_PLUGIN_ROOT}` — a command carrying a variable is refused in a headless session before any permission rule is read, and the query your contract requires never runs. With no order (invoked by hand), the kernel is `kernel/harness.mjs` two directories above this skill's base directory.
-
-| Field | What it is |
-|---|---|
-| `operation` | `wire` (author/refresh the wiring map after `analyze`, before `map-scopes`) |
-| `payload.feature` / `payload.spec_folder` | Slug + committed spec — read `usecases/` for the UCs and the engine each one needs, `domain-model.md`/`synthesis.md` for the module surface |
-| `payload.breadboard` | When present, name each UC's `affordance` by its U# and Place |
-| `payload.kb_rules_path` | Team guidelines (read if the file exists) — the seams this codebase actually wires through, entry points that are not where the template says. Steering, never spec: the profile's `entry_point` still wins, and a guideline that disagrees with it is reported in `deviations`, not applied |
-| `payload.project_profile` | Path to the SHARED `project-profile.md`. Its `entry_point` is the composition root every engine must attach to — **archetype-specific** (a client-only game's `main.js` is not a web-service's `src/server.ts`). Read it; never guess the entry point |
-| `substrate.allowed` | `wiring-map.md` — your ONLY write surface (the spec core, scopes, and the profile are frozen) |
-
-**If the profile is absent in an orchestrated run, ESCALATE (spec-ambiguity) — do not invent an
-entry point.** The whole point is that the seam resolves against a *declared* composition root; a
-guessed `main.js` would make the later oracle certify nothing.
-
-## Core process
-
-```
-1 READ     the team guidelines at payload.kb_rules_path if the file exists (absent = none),
-           then the project profile → entry_point + archetype. Read every use case in usecases/.
-           For each UC, identify the engine module that carries its core logic (the file that
-           WILL exist, named from the domain model / synthesis surface — not a guess at a folder).
-2 DESIGN   for each UC, design the integration path from the entry_point inward:
-             engine            the module implementing the UC (repo-relative path — the ONE
-                               field the later reachability oracle resolves; name the real path)
-             wiring_seam       HOW it attaches — the mechanism: an event handler, a route
-                               registration, an init hook, a subscription, a DI registration, a
-                               CLI command, a cron trigger (prose the slicer reads)
-             entry_call_site   WHERE it attaches — the composition root it registers into, named
-                               from the profile's entry_point as design intent, e.g.
-                               "src/server.ts — POST /checkout route" or "main.js — game-loop
-                               init hook". This is the seam the build will CREATE, symbolic, not
-                               an existing coordinate. Never invent a line number; the concrete
-                               file:line is a build-time fact (the oracle proves reachability by
-                               the import graph, it does not parse this field)
-             affordance        the player-visible thing this UC exposes once wired (the human
-                               end of the chain — what a user can DO, not an internal call);
-                               with a breadboard, name it by U# and Place —
-                               `U1 Pay (P1) → P2 Payment Sheet`
-3 WRITE    shapeup/<slug>/wiring-map.md (WiringMap): frontmatter for schema_version, feature
-           and entry_point (echo of the profile), then entries[] as ONE MARKDOWN TABLE under a
-           `## Wiring` heading — this exact shape, because it is the only one the reader parses:
-
-             ## Wiring
-
-             | use_case | engine | wiring_seam | entry_call_site | affordance |
-             |---|---|---|---|---|
-             | UC-01 | src/parsing.mjs | argv dispatch calls parseEnv | bin/envlint.mjs | envlint <file> |
-
-           One ROW per use case + engine pair — a UC carried by two engines gets two rows, never
-           one cell naming both. `engine` is a bare repo-relative path and nothing else: the
-           oracle resolves that cell against disk, and a cell like "`a.mjs` and `b.mjs` — two pure
-           modules" resolves to no file and is reported unverifiable. Put the explanation in the
-           `## Deviations` prose, never in the cell.
-
-           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[], 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 an engine stays orphaned; there
-is always an attachment to the entry point, or the code never runs.
-
-## Anti-rationalization table
-
-| Excuse | Reality |
-|---|---|
-| "The engine is imported somewhere, that's enough" | Reachability (proven later) is from the *entry_point*, transitively. Imported by a sibling that nothing runs is still orphaned. Design the attachment to the composition root. |
-| "I'll guess the entry point is main.js" | The profile declares it. A game's `main.js` is not a service's `src/server.ts`. Read the profile or ESCALATE. |
-| "I'll write the call site as main.js:42" | You design at L1a.5 — that code does not exist yet, so a line number is a fabrication no oracle reads. Name the composition root + mechanism as intent; leave the concrete line to the build. |
-| "This UC has no visible affordance, skip it" | Then name its boot/cron/init attachment. A UC with no entry point is a UC that never runs. |
-| "I'll run trace-lint to check my map" | Not your step. You design the seam; the orchestrator runs the reachability oracle against real code at L1b. Pre-build there is no code to trace — running it here proves nothing. |
-| "I'll also slice the scopes while I'm here" | Not your authority. You design seams; scope-architect slices. Cross-role work is a defect. |
-
-## 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), `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
-
-- [ ] Every use case in `usecases/` has exactly one wiring-map entry
-- [ ] Every entry names a real repo-relative `engine` and a `wiring_seam` (attachment mechanism); a player-facing UC also names an `affordance`
-- [ ] `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[]` (the wiring the build must close), never silently dropped
-- [ ] The WorkResult validates against `work-result.schema.json`
-
-## Invocation
-
-```bash
-# Orchestrated — compile-order --operation wire --worker solution-architect (or resolved by op) …
-/solution-architect --order .shapeup/checkout-vnpay/orders/wire.json
-
-# Standalone shim (compiles the same envelope)
-/solution-architect --wire shapeup/checkout-vnpay/
-
-# The reachability oracle is the ORCHESTRATOR's, run advisory at L1b — not part of your craft.
-# Standalone, you MAY preview it after writing the map (it self-skips arms whose artifacts are
-# absent, and is near-vacuous pre-build since the engine code does not exist yet):
-#   node "<kernel>" verify trace --slug checkout-vnpay
-```