shapeup-sdlc 1.6.2

package/skills/ba-pitch-analyzer/references/contract-patterns.md

@@ -0,0 +1,152 @@
+# Contract Patterns — Repository Boundary Contracts
+
+Reference for Phase 2b. Read before writing any `.contract.md` file.
+
+---
+
+## Why Contracts Exist
+
+Repository interfaces in `domain-model.md` define *what* a repository does.
+Contract files define *exactly what shape* goes in and comes out.
+
+A developer must be able to read a contract and answer:
+- What exact fields do I send?
+- What fields come back, and what are their types and invariants?
+- What errors can occur, and how do I handle each one?
+
+If any of those questions require opening another document, the contract is incomplete.
+
+---
+
+## Determining Source Type
+
+Read the pitch and domain model. For each repository interface, ask:
+
+```
+Is the data store internal to the monorepo?
+├── YES and it's a database/file/local cache → offline-storage
+└── YES and it's another service in the system → be-service
+
+Is the data store an external vendor?
+└── YES → third-party-api
+```
+
+Use the corresponding template from `assets/templates/contracts/`.
+
+---
+
+## Source Type: `be-service`
+
+Use when: repository calls an internal HTTP service (same org, different service/package).
+
+**Key contract fields:**
+- HTTP method + path (exact, including path params)
+- Auth header type — never leave this implicit
+- Request body table with `Source` column tracing each field to a UC input or env var
+- Response table per HTTP status code (200, 201, etc.)
+- Error table with HTTP status, error code, UX action
+
+**Contract is `status: confirmed` immediately** — Dev can verify from service code.
+
+**Source column values:**
+```
+UC-[Name].input.[fieldName]     ← from a use case input interface
+env.[ENV_VAR_NAME]              ← from environment config
+session.[claim]                 ← from JWT/auth context (e.g. session.userId)
+domain.[Aggregate].[field]      ← derived from domain model state
+computed:[formula]              ← calculated by application layer before calling repo
+```
+
+---
+
+## Source Type: `third-party-api`
+
+Use when: repository calls an external vendor API or SDK (Framer, Stripe, Twilio, etc.).
+
+**Key contract fields:**
+- Same as be-service PLUS:
+- `feasibility_ref: API-NN` — links to api-feasibility.md investigation block
+- `spike_task` — links to the SPIKE task that will confirm this contract
+- `status: speculative` — MUST remain speculative until SPIKE is done
+- `⚠️ SPECULATIVE CONTRACT` header — visible warning to all readers
+
+**⏳ TBD annotation format:**
+```markdown
+| pageId | string | ⏳ TBD — field name unverified | publishPage() |
+```
+Every `⏳ TBD` field must reference what needs to be confirmed.
+
+**Transition to confirmed:**
+When SPIKE task is complete, Dev:
+1. Replaces all `⏳ TBD` entries with confirmed values + source URL
+2. Changes `status: speculative` → `status: confirmed`
+3. Removes `⚠️ SPECULATIVE CONTRACT` header
+4. Fills `Post-SPIKE Update Log` table
+5. Implementation tasks blocking annotation can now be removed
+
+---
+
+## Source Type: `offline-storage`
+
+Use when: repository reads/writes to local device storage (SQLite, AsyncStorage, MMKV,
+file system, or in-memory cache).
+
+**Key contract fields:**
+- Engine name (SQLite via Drizzle, AsyncStorage, MMKV, etc.)
+- Table/key schema with column types, constraints, and migration version
+- Migration version must match `domain-model.md` schema version — they stay in sync
+- Conflict strategy — what happens on concurrent writes
+- Null behavior for read methods — must be explicit (null vs empty array vs throw)
+
+**Contract is `status: confirmed` immediately** — schema is defined in the spec.
+
+**Null behavior rule:**
+```
+findById → returns null (never throws) when not found
+findAll  → returns [] (never null) when empty
+write    → throws StorageError (never returns null) on failure
+```
+These invariants must appear in the contract Error Cases table.
+
+---
+
+## Contract Registry (`contracts/_index.md`)
+
+Every contracts folder must have an `_index.md` registry:
+
+```markdown
+# Contract Registry — [feature-slug]
+
+| Repository | Source Type | Service / Engine | Status | SPIKE Task |
+|-----------|------------|-----------------|--------|------------|
+| [[FramerPageRepository]] | third-party-api | Framer REST API | ⚠️ speculative | [[TASK-001]] |
+| [[PageCacheRepository]] | offline-storage | SQLite/Drizzle | ✅ confirmed | — |
+| [[UserSessionRepository]] | be-service | apps/api /auth | ✅ confirmed | — |
+```
+
+This registry is the entry point for the spec-lint structure checks.
+
+---
+
+## Contract → Task Traceability
+
+Every implementation task that uses a repository MUST:
+
+1. Reference the contract in the Context section:
+   ```markdown
+   ## Context
+   Implement FramerPageRepository per [[contracts/framer-page.contract.md]].
+   ```
+
+2. Include these three AC lines under Baseline:
+   ```markdown
+   - [ ] Request shape matches [[contracts/framer-page.contract.md#Request]] table
+   - [ ] Response mapping matches [[contracts/framer-page.contract.md#Response]] table
+   - [ ] All error codes in contract Error Cases table are handled
+   ```
+
+3. If contract is still `speculative` at task-generation time:
+   ```markdown
+   > ⏳ BLOCKED by [[TASK-001-spike-framer-feasibility]]
+   > Unblock condition: [[contracts/framer-page.contract.md]] has no remaining ⏳ TBD fields
+   ```

package/skills/ba-pitch-analyzer/references/ddd-patterns.md

@@ -0,0 +1,173 @@
+# DDD Patterns — Domain Modeling Guide
+
+Reference for Phase 2 of the BA Pitch Analyzer. Read this before writing `domain-model.md`.
+
+---
+
+## Bounded Context Decision
+
+Ask these questions from the pitch:
+
+1. **Who owns the data lifecycle?** The context that creates AND deletes an entity owns it.
+2. **What crosses a context boundary?** Cross-context = domain event or anti-corruption layer, never direct DB join.
+3. **Does this pitch create a new context or extend existing?** Extending = add to existing `domain-model.md`. New = create new bounded context folder.
+
+### Common Bounded Contexts (reference for monorepo)
+
+| Context | Owns | Does NOT own |
+|---------|------|-------------|
+| `ordering` | Order, LineItem, Cart | Product catalog, Stock levels |
+| `inventory` | StockItem, Warehouse | Order details |
+| `identity` | User, Session, Role | Profile preferences |
+| `payment` | Payment, PaymentAttempt | Order totals |
+| `notification` | Message, Channel, Template | Business triggers |
+
+---
+
+## Aggregate Design Rules
+
+### Identifying Aggregate Roots
+
+An entity is an Aggregate Root if:
+- Other entities can't exist without it (LineItem can't exist without Order)
+- It enforces invariants across child entities
+- It's the entry point for all external writes
+
+### Invariant Checklist
+
+For every aggregate, document at least one invariant:
+- `Order.totalAmount` must equal sum of `LineItem.subtotals`
+- `Order` can only transition: `draft → placed → paid | failed`
+- `PaymentAttempt` count must not exceed 3 per `Payment`
+
+### Aggregate Size Heuristic
+
+- **Too large:** aggregate has more than 3-4 entity types → split
+- **Too small:** every operation needs to load 3 aggregates → merge
+- **Right size:** one transaction boundary, one invariant set
+
+---
+
+## Value Object Patterns
+
+Value Objects have no identity — equality is by value, not ID.
+
+```typescript
+// ✅ Value Object — no ID field
+class Money {
+  constructor(
+    readonly amount: number,   // integer cents/VND — no float
+    readonly currency: 'VND' | 'USD'
+  ) {
+    if (amount < 0) throw new DomainError('Money cannot be negative')
+  }
+  equals(other: Money): boolean {
+    return this.amount === other.amount && this.currency === other.currency
+  }
+}
+
+// ✅ Value Object — wraps primitive with validation
+class OrderId {
+  constructor(readonly value: string) {
+    if (!isUUID(value)) throw new DomainError('Invalid OrderId')
+  }
+}
+```
+
+When to use VO vs Entity:
+- Has identity that persists across mutations → Entity
+- Replaced entirely when changed → Value Object
+- Examples of VOs: Money, Address, Email, PhoneNumber, DateRange, Coordinates
+
+---
+
+## Domain Event Patterns
+
+### Naming Convention
+`[AggregateRoot][PastTense]` — e.g., `OrderPlaced`, `PaymentConfirmed`, `UserRegistered`
+
+### Event Payload Design
+```typescript
+// Include: what happened, when, who, minimal context for consumers
+interface OrderPlaced {
+  eventId: string          // UUID
+  occurredAt: Date
+  orderId: string
+  customerId: string
+  totalAmount: number
+  lineItemCount: number
+  // Do NOT include: full line items, customer PII, computed fields
+}
+```
+
+### Event → Consumer Mapping Table Format
+```
+| Event | Emitted By | Consumed By | Purpose |
+|-------|------------|-------------|---------|
+| OrderPlaced | ordering ctx | inventory ctx | Reserve stock |
+| OrderPlaced | ordering ctx | notification ctx | Send confirmation |
+| PaymentConfirmed | payment ctx | ordering ctx | Transition order to paid |
+```
+
+---
+
+## Repository Interface Rules
+
+1. **Return domain objects, not DTOs** — `findById` returns `Order`, not `OrderRow`
+2. **No query logic in interface** — business queries get named methods
+3. **Async always** — all methods return `Promise<T>`
+4. **Soft-delete pattern** — if entities are soft-deleted, interface reflects it
+
+```typescript
+// ✅ Well-designed repository interface
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>
+  findByCustomer(customerId: string, limit: number): Promise<Order[]>
+  findPendingPayment(): Promise<Order[]>         // named business query
+  save(order: Order): Promise<void>              // insert or update
+  // NO: findAll(), count(), rawQuery()
+}
+```
+
+---
+
+## Anti-Patterns to Flag in Pitch Analysis
+
+When reading a pitch, look for these and document them as **Rabbit Holes**:
+
+| Anti-Pattern | Symptom | Better Approach |
+|---|---|---|
+| Shared DB table | "Both services read the orders table" | Domain events + projection |
+| Aggregate too large | "Order contains everything incl. shipping" | Split shipping to own aggregate |
+| Anemic domain | "Service layer contains all business logic" | Move invariants into aggregate |
+| Primitive obsession | `userId: string` everywhere | Typed `UserId` value object |
+| Missing domain event | State change with no downstream consumer | Add event even if no consumer yet |
+
+---
+
+## Template: Aggregate Section in domain-model.md
+
+```markdown
+## Aggregate: [Name]
+
+**Aggregate Root:** `[EntityName]`
+**Invariants:**
+- [invariant 1]
+- [invariant 2]
+
+\`\`\`
+[EntityName] (Aggregate Root)
+├── id: [EntityName]Id (VO)
+├── status: [EntityName]Status ([values])
+├── [field]: [Type]
+└── [childEntity]: [ChildEntity][] (Entity, owned)
+    ├── id: [ChildEntity]Id
+    └── [field]: [Type]
+\`\`\`
+
+**State Transitions:**
+\`\`\`
+draft ──place()──► placed ──confirm()──► confirmed
+                       └───fail()────► failed
+\`\`\`
+```

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

@@ -0,0 +1,275 @@
+# Document Schemas — Frontmatter Taxonomy
+
+Shared vocabulary used across all document types. Every field listed here uses the same
+values so wikilinks and tag queries work consistently across the spec tree.
+
+---
+
+## Shared Taxonomy Fields
+
+```yaml
+# TYPE — document classification
+type: pitch | domain-model | ux-spec | usecase | integration | task
+     | assess-report | run-state | context-map | event-choreography
+     | migration-plan | team-handoff | synthesis
+
+# FEATURE — namespace for the entire spec tree (kebab-case)
+feature: checkout-vnpay
+
+# LENS — architectural perspective used when generating this document
+# Determines which phases ran and which documents are authoritative
+lens: lite | standard | cross-context
+
+# BOUNDED CONTEXT — DDD context that owns this feature
+bounded_context: ordering | inventory | identity | notification | payment
+
+# STATUS — lifecycle state
+status: draft | ready | in-progress | blocked | done
+
+# ENTITIES — domain entities referenced or defined
+entities: [Order, LineItem, Payment]
+
+# REPOSITORIES — repository interfaces referenced or defined
+repositories: [OrderRepository, PaymentRepository]
+
+# USECASES — use case IDs referenced (e.g. UC-CreateOrder)
+usecases: [UC-CreateOrder, UC-InitiatePayment]
+
+# TAGS — free-form, for cross-cutting search
+tags: [payment, vnpay, checkout, mobile]
+
+# DEPENDS_ON — wikilinks to docs this doc depends on
+depends_on: ["[[_index]]", "[[domain-model]]"]
+```
+
+---
+
+## Lens-Aware Document Authority
+
+Each lens has a **central document** — the most detailed and authoritative spec.
+Other documents exist but are less exhaustive.
+
+| Lens | Central Document | Secondary | Skipped |
+|------|-----------------|-----------|---------|
+| `lite` | `ux-behavior.md` | domain-model, usecases, tasks | contracts/, integration.md, synthesis S-02/S-03 |
+| `standard` | `contracts/` | domain-model, ux-behavior, usecases, integration, synthesis full | — |
+| `cross-context` | `_cross-context/` | all standard docs per context | — |
+
+When upgrading `lite → standard`:
+- `ux-behavior.md` stays authoritative for screen specs
+- Use cases are **reconciled** (API boundary sub-section added, not overwritten)
+- `contracts/` generated from reconciled UC API sub-sections
+- Reconciled files reported in the WorkResult's `deviations[]`
+
+---
+
+## Schema Per Document Type
+
+### `_index.md` — Pitch Digest
+
+```yaml
+---
+type: pitch
+feature: [slug]
+appetite: "6 weeks"              # Shape Up time box
+status: draft | ready
+bounded_context: [context]
+entities: []
+tags: []
+---
+```
+
+Required sections: Problem, Appetite, Boundaries, Breadboarding, Rabbit Holes, Document Map
+
+---
+
+### `domain-model.md` — DDD Model
+
+```yaml
+---
+type: domain-model
+feature: [slug]
+bounded_context: [context]
+entities: []
+value_objects: []
+domain_events: []
+repositories: []
+tags: [ddd]
+depends_on: ["[[_index]]"]
+status: draft | ready
+---
+```
+
+Required sections: Bounded Context, Aggregates (one subsection each), Value Objects table,
+Domain Events table, Repository Interfaces (TypeScript interface blocks)
+
+---
+
+### `ux-behavior.md` — UX Spec
+
+```yaml
+---
+type: ux-spec
+feature: [slug]
+entities: []
+usecases: []
+screens: []                      # list of screen/view names
+figma_link: [Figma Project URL]  # Optional: Link to the overall Figma file
+tags: [ux]
+depends_on: ["[[domain-model]]"]
+status: draft | ready
+---
+```
+
+Required sections: Screen Flow (ASCII diagram), one section per Screen with:
+- **Figma Frame**: [Figma Frame Node ID / URL] (Mandatory if Figma mocks exist)
+- **Visual & Layout Specs**: Flex/Grid structure, spacing, alignment rules, and desktop/mobile responsiveness
+- **Design Tokens**: Specific CSS variables or Tailwind classes used for background, borders, fonts, and actions
+- **States table**, **Behavior Rules list**, **Error States table**
+
+
+---
+
+### `usecases/UC-[Name].md` — Use Case
+
+```yaml
+---
+type: usecase
+feature: [slug]
+id: UC-[Name]                    # PascalCase, must be unique in feature
+bounded_context: [context]
+actor: Customer | Admin | System
+entities: []
+repositories: []
+domain_events_emitted: []
+tags: []
+depends_on: ["[[domain-model]]", "[[ux-behavior]]"]
+status: draft | ready
+---
+```
+
+> **No `related_tasks` (retired in v3.3).** UC→task linkage is one-directional by design:
+> tasks carry `use_case_refs` (LOCAL, per-machine board); reverse lookup is always computed
+> live (synthesis S-01, audit coverage) — never stored on the committed UC. Rule: **never
+> declare a bidirectional field across the committed/local boundary** — task IDs renumber
+> per machine (generate-board bootstrap), so a stored back-link is wrong on every machine
+> but one. Tolerate (ignore) the field on pre-v3.3 specs; do not emit or update it.
+
+Required sections: Summary (1 sentence), Preconditions, Input (TS interface), Steps
+(numbered application layer), Output (TS interface), Error Cases table, Integration Points
+
+---
+
+### `usecases/_index.md` — Use Case Index
+
+```yaml
+---
+type: usecase-index
+feature: [slug]
+tags: []
+---
+```
+
+Required: table of all UCs with columns: ID | Title | Actor | Status | Depends On
+Plus: dependency diagram (ASCII or mermaid)
+
+---
+
+### `integration.md` — System Impact Map
+
+```yaml
+---
+type: integration
+feature: [slug]
+affected_services: []            # internal services, external APIs
+domain_events_consumed: []
+domain_events_produced: []
+tags: [integration]
+depends_on: ["[[domain-model]]", "[[usecases/_index]]"]
+status: draft | ready
+---
+```
+
+Required sections: Impact Summary, one subsection per affected system with:
+Data Flow, Trigger, Risk, Mitigation
+
+---
+
+### `tasks/TASK-NNN-slug.md` — Task
+
+> **Locality (v3.2):** written under the LOCAL gitignored root
+> (`.shapeup/<slug>/tasks/`), not `spec_folder`. Every other schema on this page is a
+> SHARED, committed document. Tier direction: the task file must fully anchor INTO the
+> committed spec (`use_case_refs`, `linked_docs`, the Context wikilink — LOCAL→SHARED);
+> no SHARED doc ever wikilinks `[[tasks/...]]` back (spec-lint TIER-DIRECTION red).
+
+```yaml
+---
+type: task
+feature: [slug]
+id: TASK-[NNN]                   # zero-padded 3 digits: TASK-001
+title: "[imperative verb phrase]"
+lens: lite | standard            # inherited from run-state
+package: apps/api | apps/web | packages/shared | apps/mobile
+status: ready | in-progress | blocked | done
+priority: [integer]              # 1 = highest
+depends_on: []                   # other TASK IDs: [TASK-001, TASK-002] — the AUTHORITATIVE edge
+unlocks: []                      # DERIVED — inverse of the board's depends_on graph, recomputed
+                                 # on every board write; never hand-authored (v3.3)
+use_case_refs: []                # UC IDs this task implements: [UC-CreateOrder]
+entities: []
+repositories: []
+linked_docs: []                  # [[usecase]], [[domain-model#section]]
+estimated_hours: [number]
+tags: []
+---
+```
+
+Required sections: Context (2-3 sentences with wikilink to spec), Acceptance Criteria
+(checkboxes, all verifiable by command), Implementation Notes (optional hints),
+Non-go (what is explicitly NOT in scope for this task)
+
+---
+
+### `tasks/_index.md` — Task Board
+
+```yaml
+---
+type: task-board
+feature: [slug]
+tags: []
+---
+```
+
+Required: table with columns: ID | Title | Package | Status | Priority | Depends On | Est.Hours
+Sorted by priority ascending. Status uses emoji: ⬜ ready | 🔄 in-progress | 🚫 blocked | ✅ done
+
+---
+
+## Wikilink Conventions
+
+```markdown
+[[_index]]                           # pitch digest
+[[domain-model]]                     # full domain model doc
+[[domain-model#Aggregate-Order]]     # specific section
+[[ux-behavior#CheckoutScreen]]       # specific screen
+[[usecases/UC-CreateOrder]]          # specific use case
+[[usecases/_index]]                  # use case index
+[[integration]]                      # integration map
+```
+
+Always use wikilinks (double brackets), never relative paths like `../domain-model.md`.
+
+**Tier-direction rule.** Persisted links flow **LOCAL → SHARED only**:
+
+- A LOCAL task file must **fully anchor** into the committed spec — `use_case_refs`
+  (single-anchor rule), `linked_docs`, and the Context wikilink. spec-lint flags a task
+  with an empty or unresolvable anchor as a red `UC-ANCHOR` finding.
+- A SHARED spec doc links only its committed siblings (the list above) and **never**
+  `[[tasks/...]]`: task ids are machine-local (boards regenerate and renumber) and
+  `.shapeup/` is gitignored, so a committed task link dangles on every fresh clone.
+  spec-lint flags it as a red `TIER-DIRECTION` finding. Coverage views (synthesis
+  traceability) record derived counts/status, not task ids.
+- `[[tasks/...]]` wikilinks are valid only inside LOCAL documents (task files, the board,
+  EVAL reports), where they resolve against the LOCAL root (`.shapeup/<slug>/`);
+  every wikilink in a SHARED doc stays `spec_folder`-relative.