shapeup-sdlc 1.6.2

package/skills/ba-pitch-analyzer/assets/templates/synthesis.tmpl.md

@@ -0,0 +1,215 @@
+---
+type: synthesis
+feature: FEATURE_SLUG
+generated_at: YYYY-MM-DD
+skill_version: "2.8"
+coverage_status: 🟢 | 🟡 | 🔴
+risk_status: 🟢 | 🟡 | 🔴
+dependency_status: 🟢 | 🟡 | 🔴
+depends_on:
+  - "[[domain-model]]"
+  - "[[ux-behavior]]"
+  - "[[usecases/_index]]"
+  - "[[scope-summary]]"
+---
+
+# Synthesis: FEATURE TITLE
+
+> **How to use this document:**
+> Read the Health Dashboard first (30 seconds).
+> Each indicator tells you which section to open next — skip green sections.
+> 🟢 = no action needed · 🟡 = review recommended · 🔴 = must resolve before execution
+
+---
+
+## Health Dashboard
+
+| Indicator | Status | Signal |
+|-----------|--------|--------|
+| Coverage | COVERAGE_STATUS | COVERAGE_SIGNAL |
+| Risk | RISK_STATUS | RISK_SIGNAL |
+| Dependency | DEPENDENCY_STATUS | DEPENDENCY_SIGNAL |
+
+### Execution Gate (Synthesis)
+
+<!-- 
+  ✅ PASS   = Coverage 🟢 AND Risk 🟢
+  ⚠️ REVIEW = any indicator 🟡, none 🔴
+  🚫 BLOCK  = any indicator 🔴
+-->
+SYNTHESIS_GATE
+
+*Combine with Audit score gate: both must pass for autonomous `/execute-plan`.*
+
+---
+
+## S-01 — Traceability Matrix
+
+> Open this section when **Coverage** is 🟡 or 🔴.
+
+Derived from: `use_case_refs` in each task frontmatter — the single link source (v3.3: UC
+frontmatter carries no back-link; reverse lookup is always computed live from the task board).
+
+### UC × Task Coverage
+
+<!-- 
+  Coverage is DERIVED by inverting each task's use_case_refs over the LOCAL board
+  (.shapeup/<slug>/tasks/) at generation time. Record only the count + status —
+  never task ids or [[tasks/...]] links: ids are machine-local (boards regenerate and
+  renumber) and this doc is committed. Tier rule: links flow LOCAL → SHARED only;
+  spec-lint flags [[tasks/...]] here as a red TIER-DIRECTION finding.
+  Status key:
+    ✅ covered   = ≥ 1 task with this UC in use_case_refs
+    ❌ missing   = no task references this UC
+-->
+
+| Use Case | Actor | Covering Tasks | Status |
+|----------|-------|----------------|--------|
+| [[usecases/UC-Name]] | Actor | 3 | ✅ covered |
+| [[usecases/UC-Name]] | Actor | 0 | ❌ missing |
+
+**Coverage gaps (❌ items above — must resolve before execution):**
+- [ ] UC-[Name]: no tasks found — create task or mark UC as deferred in Non-Go
+
+### UC × Entity Participation
+
+<!--
+  For each UC row: list entities from its frontmatter `entities` field.
+  Role key:
+    actor    = UC operates ON this entity (create/update/delete)
+    target   = UC reads this entity
+    emits    = UC emits a domain event on this entity
+-->
+
+| Use Case | Entity | Role |
+|----------|--------|------|
+| [[usecases/UC-Name]] | `EntityName` | actor |
+| [[usecases/UC-Name]] | `EntityName` | target |
+
+**Entity orphans (entities in domain-model with no UC reference):**
+<!--
+  🔴 orphan = aggregate root entity with no UC reference → coverage gap
+  🟡 orphan = value object or child entity with no UC reference → acceptable
+-->
+- `EntityName` — aggregate root — 🔴 no UC references this entity
+
+### Screen → UC Backing
+
+<!--
+  For each screen in ux-behavior.md `screens` frontmatter:
+  Check if at least one UC in ux-behavior `usecases` frontmatter references it.
+  ❌ unbacked screen = screen with no UC → UX spec is ahead of domain model
+-->
+
+| Screen | Backed By | Status |
+|--------|-----------|--------|
+| ScreenName | [[usecases/UC-Name]] | ✅ |
+| ScreenName | — | ❌ no UC |
+
+### Domain Event Flow
+
+<!--
+  For each domain event in domain-model `domain_events` frontmatter:
+  Check if any UC has it in `domain_events_emitted`.
+  Check if integration.md has a consumer for it.
+  dead-end = event emitted but no consumer declared in integration.md
+-->
+
+| Event | Emitted By UC | Consumer (integration.md) | Status |
+|-------|--------------|--------------------------|--------|
+| `EventName` | [[usecases/UC-Name]] | [[integration#Section]] | ✅ |
+| `EventName` | [[usecases/UC-Name]] | — | ⚠️ dead-end |
+
+---
+
+## S-02 — Risk Register
+
+> Open this section when **Risk** is 🟡 or 🔴.
+
+Derived from: `_index.md` rabbit holes + `api-feasibility.md` SPIKE blocks + `integration.md` external deps.
+
+### SPIKE Risks
+
+<!-- Only present if api-feasibility.md exists -->
+
+| Ref | Third-Party | Capability Claimed | Investigation | Time Box | Status |
+|-----|------------|-------------------|---------------|----------|--------|
+| API-01 | ServiceName | what pitch assumes | [[api-feasibility#API-01]] | Nh | ⏳ open |
+
+**Risk formula:** SPIKE risk is 🔴 when any SPIKE `time_box_hours` × (number of blocked tasks) > 20% of appetite hours.
+
+### Rabbit Hole Register
+
+| Risk | From | Likelihood | Mitigation | Status |
+|------|------|-----------|------------|--------|
+| [risk description] | [[_index#Rabbit Holes]] | high/med/low | [mitigation] | ✅ mitigated |
+| [risk description] | [[_index#Rabbit Holes]] | high | — | ❌ no mitigation |
+
+**Unmitigated risks (❌ items — PO must decide: accept, mitigate, or cut scope):**
+- [ ] [risk] — no mitigation declared
+
+### External Dependency Risks
+
+| Dependency | Declared In | Type | Unblock Condition |
+|------------|------------|------|------------------|
+| ENV_VAR_NAME | [[integration#Env]] | env var | add to `.env.example` |
+| External Account | [[integration#Setup]] | sandbox | provision before sprint |
+
+### Hammered Out (Cut)
+
+<!--
+  The SINGLE source of truth for tasks that were scope-hammered out of the cycle.
+  A Cut produces NO task file (no bet yet, so no spec). Only record a trace line here.
+  Mostly populated/appended by the reconcile operation over the discovered ledger.
+  Each line: what was cut — Cut @ GATE-N · reason · (if hammer-traded) which task it was traded for.
+-->
+
+| Cut | At | Reason | Traded for (if any) |
+|-----|-----|-------|---------------------|
+| ~~[cut capability]~~ | GATE-N | appetite overflow — saved for a later bet | TASK-NNN |
+
+*A Cut is a healthy shaping signal, not debt. Revisit it at the betting table next cycle.*
+
+---
+
+## S-03 — Dependency Graph
+
+> Open this section when **Dependency** is 🟡 or 🔴, or when planning parallel work.
+
+Derived from: `depends_on` and `unlocks` in every task frontmatter + `estimated_hours`.
+
+### Critical Path
+
+```
+Critical path: N tasks · NN hours · NN% of total estimated hours
+
+TASK-001 [SPIKE]  spike-[api]-feasibility         2h
+  └─ blocks ──► TASK-004, TASK-005, TASK-006
+TASK-002 [TASK]   shared-schema                   3h  ← parallel (no dependency on 001)
+TASK-003 [TASK]   contract-stub                   2h  ← parallel
+TASK-004 [FEAT]   implement-[repo]               ⏳ blocked by TASK-001   4h
+  └─ blocks ──► TASK-005
+TASK-005 [FEAT]   [use-case]-service             ⏳ blocked by TASK-004   6h
+  └─ blocks ──► TASK-006, TASK-007
+TASK-006 [FEAT]   [feature]-ui                   ⏳ blocked by TASK-005   8h
+TASK-007 [FEAT]   [feature]-ui-edge-cases        ⏳ blocked by TASK-005   4h
+```
+
+### Parallel Opportunities
+
+Tasks at the same dependency depth with no interdependency — can be executed in parallel:
+
+| Wave | Tasks | Total Hours | Can Parallelize |
+|------|-------|-------------|-----------------|
+| Wave 1 (no deps) | TASK-001, TASK-002, TASK-003 | Nh | ✅ yes — 3 agents |
+| Wave 2 (after 001) | TASK-004 | Nh | — single task |
+| Wave 3 (after 004) | TASK-005 | Nh | — single task |
+| Wave 4 (after 005) | TASK-006, TASK-007 | Nh | ✅ yes — 2 agents |
+
+### Single Points of Failure
+
+Tasks whose delay cascades to > 2 downstream tasks:
+
+| Task | Blocks | Cascaded Hours at Risk |
+|------|--------|----------------------|
+| TASK-NNN | TASK-NNN, TASK-NNN, TASK-NNN | Nh |

package/skills/ba-pitch-analyzer/assets/templates/task-board.tmpl.md

@@ -0,0 +1,35 @@
+---
+type: task-board
+feature: FEATURE_SLUG
+tags: []
+---
+
+# Task Board: FEATURE TITLE
+
+## Progress
+⬜ 0 / N tasks complete · Est. total: Xh
+
+## Tasks
+
+| ID | Title | Package | Status | Priority | Depends On | Est. |
+|----|-------|---------|--------|----------|------------|------|
+| [[TASK-001\|TASK-001]] | [title] | shared | ⬜ | 1 | — | Xh |
+| [[TASK-002\|TASK-002]] | [title] | api | ⬜ | 2 | TASK-001 | Xh |
+
+<!-- Status: ⬜ ready · 🔄 in-progress · 🚫 blocked · ✅ done -->
+
+## Execution Order
+
+```
+TASK-001 (schema)
+    └──► TASK-002 (repository)
+              └──► TASK-003 (use case)
+                       └──► TASK-004 (endpoint)
+                                 └──► TASK-005 (frontend)
+```
+
+## Blocked Tasks
+
+<!-- Move tasks here if they are blocked, with reason -->
+| ID | Blocked By | Reason |
+|----|------------|--------|

package/skills/ba-pitch-analyzer/assets/templates/task-spike.tmpl.md

@@ -0,0 +1,86 @@
+---
+id: TASK-[NNN]
+type: SPIKE
+slug: spike-[api-name]-feasibility
+feature: "[feature-slug]"
+api_ref: "API-[NN]"
+time_box_hours: 4
+priority: 1
+package: research
+estimated_hours: ~
+status: todo
+blocks:
+  - TASK-[NNN]
+  - TASK-[NNN]
+linked_docs:
+  - "[[api-feasibility#API-NN]]"
+  - "[[contracts/[repo].contract.md]]"
+---
+
+# SPIKE: [ServiceName] API Feasibility
+
+> This is a **SPIKE task** — output is a decision document, not code.
+> Time-boxed to `[N]h`. If questions remain unanswered, escalate to PO.
+
+## Objective
+
+Determine whether [ServiceName] API/SDK supports [capability claimed in pitch],
+and produce a confirmed contract skeleton for [[contracts/[repo].contract.md]].
+
+---
+
+## Questions to Answer
+
+- [ ] Does [ServiceName] support [specific operation] via REST or SDK?
+- [ ] What is the exact request input format? (field names, types, limits)
+- [ ] What does the success response body look like? (field names, types)
+- [ ] What auth model is required? (API Key, OAuth, Bearer, Service Account)
+- [ ] Is there a sandbox / test environment available?
+- [ ] What are the rate limits? Is there a retry-after header?
+- [ ] Are there known deprecations or upcoming breaking changes?
+
+---
+
+## Verification Method
+
+```
+1. Read official docs at: [URL — search during SPIKE]
+   Target sections: Authentication, [relevant endpoint group], Error Handling
+
+2. If official docs are incomplete or ambiguous:
+   Search: "[ServiceName] [operation] site:github.com OR site:stackoverflow.com"
+   Check: [ServiceName] official GitHub issues, changelog, Discord/Slack
+
+3. If still unconfirmed: write a minimal test:
+   curl -X POST [endpoint] -H "Authorization: [key]" -d '[minimal payload]'
+   or: write 5-line SDK test against sandbox credentials
+
+4. Record all findings with direct source URL before closing task
+```
+
+---
+
+## Definition of Done
+
+- [ ] All questions above answered — each with direct source URL citation
+- [ ] [[contracts/[repo].contract.md]] updated — all `⏳ TBD` fields replaced with confirmed values
+- [ ] [[api-feasibility#API-NN]] `Resolution` block filled: status, source URL, date
+- [ ] If capability confirmed: tasks in `blocks` list have `⏳ BLOCKED` annotation removed
+- [ ] If capability NOT confirmed: PO notified with fallback scope options from [[api-feasibility#API-NN]]
+
+---
+
+## Non-Go (not in this task)
+
+- Writing any implementation code
+- Integrating the API into the application
+- Performance testing or load testing the API
+- Evaluating alternative providers
+
+---
+
+## Output Location
+
+Update directly in:
+- `[[api-feasibility#API-NN]]` — Resolution block
+- `[[contracts/[repo].contract.md]]` — replace all ⏳ TBD fields

package/skills/ba-pitch-analyzer/assets/templates/task.tmpl.md

@@ -0,0 +1,84 @@
+---
+type: task
+feature: FEATURE_SLUG
+id: TASK-NNN
+title: "[imperative verb phrase — e.g. Create Order aggregate schema]"
+package: packages/shared | apps/api | apps/web
+status: ready
+priority: N
+depends_on: []
+unlocks: []
+use_case_refs: []
+entities: []
+repositories: []
+linked_docs: []
+estimated_hours: N
+tags: []
+---
+
+# TASK-NNN: [Title]
+
+## Context
+[2-3 sentences. Wikilink to the source spec, not re-describe it.]
+Reference: [[domain-model#Section]] / [[usecases/UC-Name#Steps]]
+Style reference: `[path/to/existing/similar/file.ts]`
+
+## Acceptance Criteria
+
+### ✅ Baseline (always required)
+- [ ] [File X is created at path Y]
+- [ ] `pnpm --filter [package] typecheck` exits 0
+- [ ] `pnpm --filter [package] test [file]` passes
+- [ ] [Exported type Z is available from package index]
+
+### 🔁 Inverse Conditions
+<!-- _trigger: layer=ui + keyword=show/hide/display/visible/render -->
+<!-- Include ONLY if this task has conditional rendering logic. Remove section if not applicable. -->
+- [ ] [Element X does NOT appear when condition C1 is false]
+- [ ] [Element X does NOT appear before prerequisite state S is reached]
+
+### 📭 Empty & Null States
+<!-- _trigger: layer=repository/api + keyword=fetch/load/list, OR ui task references data prop -->
+<!-- Include ONLY if this task fetches data or renders data-driven UI. Remove section if not applicable. -->
+- [ ] Loading: [Skeleton/spinner renders while fetch is pending]
+- [ ] Empty result: [EmptyState component renders when API returns `[]`]
+- [ ] Null guard: [No crash or render error when `[field]` is `null` or `undefined`]
+
+### 🔢 Boundary Values
+<!-- _trigger: any numeric value, file size, limit, max, min mentioned in description -->
+<!-- Include ONLY if this task enforces a limit or validates a range. Remove section if not applicable. -->
+- [ ] At min value ([N]): [expected behavior]
+- [ ] At max value ([N]): [expected behavior — e.g. reject with error code E_XXX]
+- [ ] At zero/empty string: [expected behavior]
+
+### 🧪 BDD Scenarios
+<!-- _trigger: task.type=FEAT + user-facing action OR cross-layer boundary (UI→API, API→DB) -->
+<!-- 1–3 scenarios max: happy path required, key rejection optional. Remove for CHORE/DOCS/MIGRATION/SPIKE. -->
+
+**Scenario: [describe the happy-path action]**
+Given [precondition — who/what is in what state]
+When  [actor performs specific action]
+Then  [expected observable outcome]
+
+**Scenario: [describe a key guard or rejection]**
+Given [precondition that leads to rejection]
+When  [action is attempted]
+Then  [error response or system rejection]
+
+### 🔗 Integration Flow
+<!-- _trigger: task crosses ≥1 service boundary (UI→API, API→DB, service→external) -->
+<!-- Name layers explicitly. Remove for tasks isolated to a single layer (domain types, pure domain logic). -->
+
+**[Source layer] → [Target layer/service]**
+Given [upstream caller/actor is in [state]]
+When  [action triggers at [layer — e.g. POST /api/resource or Repository.save()]]
+Then  [downstream side effect — DB row created, event published]
+And   [caller receives — HTTP status + response body shape]
+
+## Implementation Notes
+<!-- Optional — only include non-obvious decisions -->
+<!-- Remove this section if empty -->
+
+## Non-Go (not in this task)
+- [What explicitly comes later — with task reference if known]
+- [Another thing that's out of scope]

package/skills/ba-pitch-analyzer/assets/templates/usecase.tmpl.md

@@ -0,0 +1,105 @@
+---
+type: usecase
+feature: FEATURE_SLUG
+id: UC-[Name]
+bounded_context: CONTEXT
+actor: Customer | Admin | System
+entities: []
+repositories: []
+domain_events_emitted: []
+tags: []
+depends_on: ["[[domain-model]]", "[[ux-behavior]]"]
+status: draft
+---
+
+# Use Case: [Name]
+
+## Summary
+[One sentence: Actor does X which results in Y.]
+
+## Preconditions
+- [condition that must be true before this use case can execute]
+
+## Input
+
+```typescript
+interface [UseCaseName]Input {
+  // fields from [[ux-behavior#ScreenName]] form
+}
+```
+
+## Steps
+
+```
+1. Validate input schema
+2. [Load aggregate from repository]
+3. [Call domain method — business logic stays in aggregate]
+4. [Repository.save()]
+5. [Publish domain event]
+6. Return output
+```
+
+## Output
+
+```typescript
+interface [UseCaseName]Output {
+  // fields returned to caller
+}
+```
+
+## System Flow
+
+<!--
+  Trace the full path this use case travels from UI trigger to data persistence.
+  Include only layers relevant to the current lens. Remove if a SPIKE is unresolved.
+-->
+
+```
+[UI: ScreenName → CTA/event]
+  → [API: METHOD /endpoint]
+    → [Use Case: Actor.action()]
+      → [Repository.method() → DB: table_name]
+        ← [Domain Event: EventName emitted (if any)]
+```
+
+## Invariants
+
+<!--
+  An invariant must STILL hold after this UC is built.
+  Each invariant is a source of regression tasks — that task anchors use_case_refs back to THIS UC
+  (do NOT create a new anchor axis; an invariant is a property of the UC, not a UC of its own).
+  This section MAY be APPENDED by the reconcile operation when a build discovers a new constraint
+  (append-only — never edit the locked Steps/Input/Output).
+  Drop this section if the UC produces no invariants.
+-->
+- [INV-01] [Short invariant description — e.g. "A board saved before this cycle (old schema) loads without error and without data loss"]
+
+## Error Cases
+
+| Error Code | Condition | HTTP Status | Handling |
+|---|---|---|---|
+| `[CODE]` | [when] | 400/404/409/422 | [description] |
+
+## Test Surface
+
+<!--
+  DERIVED section — generated mechanically from Invariants (D1) + Error Cases (D2) +
+  Contract/Input shape (D3) + pitch No-gos touching this UC (D4).
+  Rules → references/test-surface.md. Never hand-author rows; never invent behaviors.
+  Regenerable via a retrofit-surface order. Appended-to (TS-INV rows) by the reconcile operation when
+  a new invariant lands. Exploratory/edge tests do NOT live here (qa-edge-hunter owns those).
+  If all four sources are empty, replace the table with:
+  _No derivable surface — sources empty. Exploratory coverage only (see qa-edge-hunter)._
+  Oracle = how the evaluator verifies the row (ui|process|test|snapshot|http); default ui.
+  Non-ui when this UC's deliverable has no browser (CLI/library/service). See references/test-surface.md.
+-->
+| ID | Oracle | Probe | Expect | Source |
+|---|---|---|---|---|
+| TS-INV-01 | ui | [action that would violate INV-01] | [rejection + state unchanged] | D1: INV-01 |
+| TS-ERR-[CODE] | http | [trigger the Condition] | [error code + HTTP status] | D2 |
+| TS-REQ-[field]-missing | http | [omit required field] | [400 validation, no side effect] | D3 |
+| TS-NOGO-[NN] | ui | [attempt the excluded behavior] | [blocked/absent] | D4 |
+
+## Integration Points
+- → [[integration#[service-section]]] — [what flows out]
+- ← [[ux-behavior#[ScreenName]]] — triggered by [which CTA/event]

package/skills/ba-pitch-analyzer/assets/templates/ux-behavior.tmpl.md

@@ -0,0 +1,65 @@
+---
+type: ux-spec
+feature: FEATURE_SLUG
+entities: []
+usecases: []
+screens: []
+tags: [ux]
+depends_on: ["[[domain-model]]"]
+status: draft
+---
+
+# UX Behavior: FEATURE TITLE
+
+## Screen Flow
+
+```
+[ScreenA]
+    │
+    ├─ [condition] ──► [ScreenB]
+    │
+    └─ [condition] ──► [ScreenC]
+                           │
+                   ┌───────┴───────┐
+                   │               │
+               success           failed
+                   │               │
+           [SuccessScreen]   [ErrorScreen]
+```
+
+---
+
+## Screen: [ScreenName]
+
+### States
+
+| State | Trigger | UI Behavior | CTA |
+|-------|---------|-------------|-----|
+| `idle` | screen mount | form editable | enabled |
+| `submitting` | user taps CTA | full loader | loading |
+| `error` | API failure | error banner | enabled |
+| `success` | API success | [redirect / toast] | — |
+
+### Behavior Rules
+
+- [RULE-01] ...
+- [RULE-02] ...
+
+### Error Catalog
+
+| Error Code | Condition | User Message | Action |
+|---|---|---|---|
+| `NETWORK_TIMEOUT` | No response in 30s | "Can't connect, please retry" | [Retry] |
+| `[CODE]` | [condition] | "[message in English]" | [action] |
+
+---
+
+<!-- Repeat "Screen: [Name]" section for each screen -->
+
+---
+
+## Platform Differences
+
+| Behavior | Mobile | Web |
+|---|---|---|
+| [behavior] | [mobile treatment] | [web treatment] |