shapeup-sdlc 1.6.2

package/skills/shapeup/resources/kickoff-doc.md

@@ -0,0 +1,95 @@
+# Kickoff Doc — Reference
+
+> Source: rjs/shaping-skills (upstream). Loaded on demand by the shapeup skill.
+
+---
+
+## What This Does
+
+Turns a shaped project kickoff transcript into a **builder reference document**. Captures what was shaped, what was agreed, and what the builder needs before starting.
+
+**⚠️ GIGO Warning:** Same as framing-doc — formats and distills, doesn't evaluate.
+
+---
+
+## When to Use
+
+- You have a transcript of a kickoff/handoff meeting for a shaped project
+- You need a document the builder can reference during implementation
+- The shape already exists and decisions have been made
+
+**This is a document skill for team contexts.** Not part of the solo shaping workflow.
+
+---
+
+## Phase K1 — Parse Transcript
+
+```
+Read entire transcript before writing. Extract:
+- The shaped solution: what parts/mechanisms were agreed
+- Scope boundaries: what's in, what's explicitly out
+- Known rabbit holes flagged
+- Decisions already made (builder should not re-open these)
+- Open questions for the builder to resolve
+- Constraints: timeline, integration dependencies, platform limits
+```
+
+---
+
+## Phase K2 — Write Kickoff Document
+
+Write `shapeup/[feature-slug]/shaping/kickoff.md`
+
+```markdown
+---
+shaping: true
+feature: [feature-slug]
+doc_type: kickoff
+status: active
+---
+
+# [Feature Name] — Kickoff Reference
+
+## What We're Building
+[1–2 sentences: the core mechanism from the user's perspective]
+
+## The Shape
+A1: [part name] — [one sentence description]
+A2: ...
+
+## In Scope
+[Explicit boundaries of this cycle's work]
+
+## Out of Scope
+[Things deferred — not "never", just "not this cycle"]
+
+## Known Rabbit Holes
+[Areas flagged as risky. Include the specific risk if mentioned.]
+
+## Decisions Already Made
+[Things the builder should NOT re-open during implementation.
+ If something seems wrong: raise it before building, not after.]
+
+## Open Questions for the Builder
+[Things left for builder to resolve during implementation]
+
+## Constraints
+[Timeline, integration dependencies, platform limits]
+[Omit if not mentioned in transcript]
+
+---
+*Generated from kickoff transcript. Reference, not specification.*
+*For wiring detail: [[breadboard.md]]*
+```
+
+---
+
+## Phase K3 — Quality Check
+
+```
+- [ ] "Decisions Already Made" contains ONLY things explicitly agreed — no assumptions
+- [ ] "Open Questions" are builder-resolvable, not business strategy questions
+- [ ] Shape parts are at mechanism level, not implementation detail
+- [ ] No technology choices in shape unless explicitly agreed in transcript
+- [ ] Wikilink to breadboard.md included if it exists
+```

package/skills/shapeup/resources/shaping.md

@@ -0,0 +1,194 @@
+# Shaping — Reference
+
+> Source: rjs/shaping-skills (upstream) + local v1.x extensions. Loaded on demand by the shapeup skill.
+
+---
+
+## What Shaping Does
+
+Shaping separates **what you need** (requirements) from **how you might build it** (shape). It ends when every requirement maps to a shape part. Unknowns are flagged for spikes.
+
+**Stop here — do not slice yet.** Slicing is the final phase of breadboarding.
+
+---
+
+## When to Use Shaping
+
+- You have an idea but haven't separated problem from solution
+- You want to explore multiple solution options before committing
+- Any "should we build X or Y?" decision
+
+---
+
+## Phase S1 — Problem Frame + Appetite
+
+```
+1. Ask: "Describe the problem from the user's perspective. What's broken or missing?"
+2. Capture:
+   - Situation: what triggers the need
+   - Complication: what's wrong or missing right now
+   - Desired outcome: what success looks like for the user
+   - Anti-goals: what we're explicitly NOT solving
+3. Collect appetite (time budget):
+   Ask: "How long is the right amount of time to spend on this? (e.g. ~1 week, ~2 weeks)"
+   Appetite is the scope anchor — it decides what's in vs. out when tradeoffs arise.
+   If the user gives no bound: prompt once, then proceed with "appetite: TBD (uncapped)".
+   Warning: an uncapped appetite tends to produce shapes that are too large.
+4. Write a one-paragraph problem statement.
+   Rule: no solution language — observable symptoms only.
+5. Ask: "Is this the right problem, or is there a more fundamental one?"
+```
+
+Output: Internal only. Do NOT write files yet.
+
+---
+
+## Phase S2 — Requirements (R)
+
+```
+1. Derive requirements as observable outcomes from the problem frame.
+   Format: R[N]: [observable condition that must be true when feature is done]
+   Example: R0: User sees empty dashboard with guided setup when no data exists
+2. Number them R0..RN
+3. Flag any R that blurs into solution territory — note it, keep it for discussion
+```
+
+**Good requirements are:**
+- Observable from the outside (a QA person could verify them)
+- Technology-agnostic (no tables, components, API names)
+- Non-redundant (each R covers exactly one observable thing)
+
+Output: Internal R-list only.
+
+---
+
+## Phase S2.5 — Rabbit Holes + No-goes
+
+Before selecting a shape, surface the known traps.
+
+```
+1. Ask: "Are there any approaches that look obvious but would derail the build?
+         Any known rabbit holes — things that could eat weeks of implementation time?"
+2. Also capture explicit no-goes: things the user has already decided NOT to build.
+3. Record both lists. They constrain shape selection in S3:
+   - A shape that passes through a rabbit hole needs extra justification or a spike.
+   - No-goes block shape parts silently assumed — call them out.
+```
+
+**Why this matters:** Rabbit holes are the most common reason a well-shaped feature blows
+its appetite. Naming them before shape selection keeps S3 honest.
+
+Skip if: input has already listed no-goes and confirmed no known traps.
+
+---
+
+## Phase S3 — Solution Shape (A)
+
+```
+1. Generate 2–3 possible shapes — named sets of parts/mechanisms.
+   Format: A[N]: [part name] — [one sentence: what it does for the user]
+   Rule: parts are higher-level than affordances.
+         "a settings page with webhook URL" not "a <CopyButton> component"
+2. For each shape, note:
+   - What requirements it covers
+   - What it leaves unresolved
+   - Complexity signal: simple / moderate / complex
+3. Ask: "Which shape resonates? Any better option?"
+4. Select one shape. Record selection rationale.
+```
+
+**Fat marker rule:** If describing a part takes more than one sentence, it's too detailed for shaping — save it for breadboarding.
+
+---
+
+## Phase S4 — Fit Check
+
+```
+For each requirement R[N]:
+  Map to shape part(s) A[N] that satisfy it.
+  Mark: ✅ covered | ⚠️ partially covered | ❌ not covered
+
+If any R is ❌ not covered:
+  - Either extend shape with a new part (preferred)
+  - Or reclassify as non-goal (with user agreement)
+  → Do NOT proceed to breadboarding with uncovered requirements.
+
+If any R is ⚠️ partially:
+  - Document what remains unresolved
+  - Flag whether a spike is needed before breadboarding
+```
+
+**Output table:**
+```
+| R#  | Requirement                           | Covered by | Status |
+|-----|---------------------------------------|------------|--------|
+| R0  | Empty dashboard shows guided setup    | A4         | ✅     |
+| R2  | Auto-generated secret per account     | A1         | ✅     |
+| R5  | One-click backfill from UI            | A3, A4     | ✅     |
+```
+
+---
+
+## Output File: shaping.md
+
+Write `shapeup/[feature-slug]/shaping/shaping.md`
+
+```markdown
+---
+shaping: true
+feature: [feature-slug]
+status: shaped
+appetite: [~1 week | ~2 weeks | ~6 weeks | TBD (uncapped)]
+---
+
+# [Feature Name] — Shaping
+
+## Problem Frame
+[one paragraph, no solution language]
+
+## Appetite
+[time budget + rationale: "~1 week — small improvement, already understand the surface"]
+
+## Requirements
+R0: ...
+R1: ...
+
+## Rabbit Holes
+[Known traps that could eat the budget — be specific about what makes them dangerous]
+- RH1: [name] — [why it's a rabbit hole]
+(Omit section if none identified — don't invent them)
+
+## No-goes
+[Things explicitly outside this feature's scope]
+- [item] — [brief reason]
+(Omit section if none stated by user)
+
+## Selected Shape — [Name]
+Rationale: [why this over alternatives; how it fits within the appetite]
+
+### Parts
+A1: ...
+A2: ...
+
+## Fit Check
+| R# | Requirement | Covered by | Status |
+|----|-------------|------------|--------|
+
+## Unknowns → Spike Needed?
+- [ ] [unknown 1] → spike-[slug].md
+```
+
+**Note:** This file is a kicked-off pitch. `/ba-pitch-analyzer` and `/tech-lead` consume it as-is — the appetite, rabbit holes, and no-goes inform scope decisions downstream.
+
+---
+
+## Common Mistakes
+
+| Mistake | Why it matters |
+|---|---|
+| Skipping appetite collection | Without a time budget, every option seems equally valid — the shape has no natural stopping point |
+| Putting slicing inside shaping | Slicing is breadboarding's final phase, not shaping's |
+| Solution language in requirements | "User sees a modal" is not a requirement — it's a shape |
+| Fat marker parts (multi-sentence) | Details belong in breadboarding, not shaping |
+| Skipping fit check | Uncovered requirements lead to missing features in implementation |
+| No rabbit holes section | Known traps go undocumented and derail the build once implementation starts |

package/skills/shapeup/resources/spike.md

@@ -0,0 +1,86 @@
+# Spike — Reference
+
+> Loaded on demand by the shapeup skill.
+
+---
+
+## What a Spike Is
+
+A spike is a **time-boxed investigation** — not a prototype, not a full implementation. It answers a specific question so the breadboard can be grounded in fact.
+
+**When to use:** After fit check, when any shape part depends on an assumption that hasn't been verified (library capability, API behavior, performance characteristic).
+
+**When NOT to use:** When the unknown is trivial to verify with a quick search. Only spike things that could change the shape if the answer is "no."
+
+---
+
+## Spike Process
+
+```
+1. State the question precisely:
+   "Can we use Python's built-in zoneinfo for DST-aware timezone math,
+    or do we need a network API like Google Timezone?"
+
+2. Define the acceptance condition:
+   Yes: [what shape part looks like if confirmed]
+   No: [what changes to the shape]
+
+3. Conduct the investigation:
+   - Check official docs, not community posts
+   - Write minimal proof-of-concept code if needed
+   - Document what you found and the source
+
+4. Record the decision:
+   - What was confirmed
+   - Which shape part this affects
+   - Any constraints or caveats discovered
+```
+
+---
+
+## Output File: spike-[part].md
+
+```markdown
+---
+shaping: true
+feature: [feature-slug]
+doc_type: spike
+part: A[N]
+status: resolved | open
+---
+
+# Spike: [Question]
+
+## Question
+[precise question this spike answers]
+
+## Acceptance Condition
+Yes: [what shape part looks like if confirmed]
+No: [what changes to the shape]
+
+## Investigation
+[what was found, with sources]
+
+## Decision
+[yes/no + one sentence impact on shape]
+
+## Constraints Discovered
+[any caveats the breadboard must account for]
+```
+
+---
+
+## SPIKE-UNRESOLVED Fallback
+
+If a spike cannot be resolved (external dependency, blocked, time-boxed):
+
+```
+SPIKE-UNRESOLVED: [part name]
+- Question: [precise question]
+- Blocker: [why unresolvable now]
+- Risk: [how this could affect the breadboard]
+- Assumption for now: [what we're proceeding with]
+- Revisit when: [condition that unblocks this]
+```
+
+Proceed with the assumption clearly documented. Revisit before implementation of that specific part.

package/skills/solution-architect/SKILL.md

@@ -0,0 +1,129 @@
+---
+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.**
+
+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
+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`, `trace-lint.mjs` 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 — the four 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
+
+| 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.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 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)
+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
+           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
+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
+
+`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,
+`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[]`/`escalates[]` (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 "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/trace-lint.mjs" --slug checkout-vnpay
+```

package/skills/spec-evaluator/README.md

@@ -0,0 +1,93 @@
+# spec-evaluator
+
+The **judge** in a planner → generator → evaluator harness. Pairs with `task-executor`
+(generator) and `ba-pitch-analyzer` (planner). Reads the same spec tree, exercises the
+**running** app, returns a hard-threshold verdict + file:line bug list, and hands bugs back
+to the generator. Skeptical by default; never marks a task `done`.
+
+v0.1 evaluates one dimension only — **spec-conformance** (AC + Done-when + contract shapes +
+non-go). Security / performance ship disabled, injectable later with zero core changes.
+
+---
+
+## Resource map
+
+```
+spec-evaluator/
+├── SKILL.md                              # entry point — frontmatter, GATE V0–V3, flags, hard rules
+├── README.md                             # this file
+└── references/
+    ├── dimension-contract.md             # ★ the injection interface every dimension implements
+    ├── anti-leniency.md                  # skeptical posture — read before any verdict (GATE V2)
+    ├── probing.md                        # Phase A — Playwright CLI + per-variant probe strategy
+    ├── report-schema.md                  # Phase B — the EVAL-TASK-NNN.md handoff file
+    └── dimensions/
+        ├── _registry.md                  # which dimensions are active + how to add one
+        ├── spec-conformance.md           # ✅ the only enabled dimension (correctness)
+        ├── security.md                   # ⛔ disabled stub — worked example of the contract
+        └── performance.md                # ⛔ disabled stub — worked example of the contract
+```
+
+| Resource | Loaded at | Purpose |
+|----------|-----------|---------|
+| `SKILL.md` | always | gate pipeline, invocation, authority rules |
+| `references/dimension-contract.md` | GATE V0.5 | the interface; validates each dimension before running it |
+| `references/dimensions/_registry.md` | GATE V0.5 | active set resolution (`--dimensions` overrides) |
+| `references/dimensions/spec-conformance.md` | per task | the default correctness dimension |
+| `references/dimensions/{security,performance}.md` | only if enabled | injectable stubs, off by default |
+| `references/anti-leniency.md` | before GATE V2 | absence of evidence = FAIL; banned phrases |
+| `references/probing.md` | Phase A | how to collect evidence (CLI > MCP, per variant) |
+| `references/report-schema.md` | Phase B | the file the generator reads next |
+
+★ = the load-bearing file for "spec now, more dimensions later."
+
+---
+
+## Install
+
+```bash
+# Project scope (shareable via version control) — recommended
+cp -r spec-evaluator <repo>/.claude/skills/
+
+# or user scope (all your projects)
+cp -r spec-evaluator ~/.claude/skills/
+```
+
+Restart the session (or re-open the skills interface) so the new skill is discovered.
+
+## Invoke
+
+```bash
+/spec-evaluator --spec shapeup/checkout-vnpay/spec/ --task TASK-007  # default: spec-conformance
+/spec-evaluator --spec ... --task TASK-007.web                                # platform variant
+/spec-evaluator --spec ... --task TASK-007.be --browser none                  # backend-only, no browser
+/spec-evaluator --spec ... --task TASK-007 --dimensions spec-conformance,security   # inject a dimension
+/spec-evaluator --spec ... --task TASK-007 --single-pass --auto               # one end pass, skip sign-off
+```
+
+## Pipeline position
+
+```
+ba-pitch-analyzer (planner) ─► task-executor (generator) ─► spec-evaluator (judge)
+                                      ▲                                │
+                                      └──── bug list (EVAL-TASK-NNN) ◄─┘  on FAIL
+```
+The evaluator writes `.shapeup/<slug>/evaluation/EVAL-<task_id>.md` (LOCAL run-trace root) and sets `eval_verdict` on the task.
+`task-executor` owns `status: done`. Judge and doer stay separate by design.
+
+## Inject a new dimension (zero core edits)
+
+1. Copy the "Minimal valid dimension" block from `references/dimension-contract.md` to
+   `references/dimensions/<id>.md`; fill criteria, probes, threshold, bug template.
+2. Set `enabled: true` in `references/dimensions/_registry.md` (or pass `--dimensions … ,<id>`).
+3. Re-run. GATE V0.5 validates it against the contract and loads it; non-conforming files
+   are skipped with a warning, never half-run.
+
+`applies_to` scopes a dimension to a lens / package / platform variant, so a `visual`
+dimension can run only on `.web` tasks and `security` only on `.be`/`.shared`.
+
+---
+
+## Version
+0.1 — initial template. GATE V0–V3, skeptical-by-default, single enabled dimension,
+pluggable dimension contract, Playwright CLI probing, file:line bug handoff.