@haposoft/cafekit 0.16.0-rc.3 → 0.16.0-rc.4

package/src/claude/skills/specs/templates/design.md

@@ -1,296 +1,82 @@
-# Design Document Template
+# Design
 
----
-**Purpose**: Provide sufficient detail to ensure implementation consistency across different implementers, preventing interpretation drift.
+<!-- Delete every optional section that is not relevant. Compact keeps only the four core sections. -->
 
-**Approach**:
-- Include essential sections that directly inform implementation decisions
-- Omit optional sections unless critical to preventing implementation errors
-- Match detail level to feature complexity
-- Use diagrams and tables over lengthy prose
+## Boundary
 
-**Warning**: Approaching 1000 lines indicates excessive feature complexity that may require design simplification.
----
+- **Owns:** {{Behavior/state this design owns}}
+- **Reads:** {{Relevant inputs or existing state, or none}}
+- **Writes/exposes:** {{Outputs, state, route, artifact, or none}}
+- **Outside boundary:** {{Explicit non-goal or delegated responsibility}}
 
-> Sections may be reordered (e.g., surfacing Requirements Traceability earlier or moving Data Models nearer Architecture) when it improves clarity. Within each section, keep the flow **Summary → Scope → Decisions → Impacts/Risks** so reviewers can scan consistently.
+## Typed Anchors
 
-## Overview 
-2-3 paragraphs max
-**Purpose**: This feature delivers [specific value] to [target users].
-**Users**: [Target user groups] will utilize this for [specific workflows].
-**Impact** (if applicable): Changes the current [system state] by [specific modifications].
+<!-- Files-first. IDs are unique across the whole spec. Design-owned anchors use A-D-NN. Access/Action are machine authority; Role never implies lifecycle. -->
 
+| ID | Type | Target | Role | Access | Action |
+|---|---|---|---|---|---|
+| A-D-01 | file | `{{path/to/existing-or-planned-file}}` | {{owner / consumer / entrypoint / proof / constraint}} | {{read / write}} | {{read / create / modify / delete}} |
+<!-- For a typed proof boundary, add: | A-D-02 | artifact | `{{path/to/proof-artifact}}` | proof evidence owner | write | create | -->
 
-### Goals
-- Primary objective 1
-- Primary objective 2  
-- Success criteria
+## Decisions and Invariants
 
-### Non-Goals
-- Explicitly excluded functionality
-- Future considerations outside current scope
-- Integration points deferred
+<!-- Keep stable D/I/C IDs: every RN.M semantic-review counterexample cites one exact design reference. -->
 
-## Architecture
+### D1 — {{Decision name}}
 
-> Reference detailed discovery notes in `research.md` only for background; keep design.md self-contained for reviewers by capturing all decisions and contracts here.
-> Capture key decisions in text and let diagrams carry structural detail—avoid repeating the same information in prose.
+- **Decision:** {{Canonical behavior or boundary}}
+- **Rejects ambiguity:** {{Alternative interpretation implementers must not choose}}
+- **Negative path:** {{Failure/error behavior when relevant}}
+- **Anchors:** A-D-01
 
-### Existing Architecture Analysis (if applicable)
-When modifying existing systems:
-- Current architecture patterns and constraints
-- Existing domain boundaries to be respected
-- Integration points that must be maintained
-- Technical debt addressed or worked around
+### I1 — {{Invariant name}}
 
-### Architecture Pattern & Boundary Map
-**RECOMMENDED**: Include Mermaid diagram showing the chosen architecture pattern and system boundaries (required for complex features, optional for simple additions)
+{{Property that must remain true across implementation and verification.}}
 
-**Architecture Integration**:
-- Selected pattern: [name and brief rationale]
-- Domain/feature boundaries: [how responsibilities are separated to avoid conflicts]
-- Existing patterns preserved: [list key patterns]
-- New components rationale: [why each is needed]
-- Steering compliance: [principles maintained]
+### Named Contracts (conditional)
 
-### Technology Stack
+<!-- Define each implementation-significant contract once. Tasks reference IDs and never copy bodies. For any public, replay, or operator API contract, include method, route, auth, required headers, request schema, success response, error semantics, and idempotency/concurrency behavior. -->
 
-| Layer | Choice / Version | Role in Feature | Notes |
-|-------|------------------|-----------------|-------|
-| Frontend / CLI | | | |
-| Backend / Services | | | |
-| Data / Storage | | | |
-| Messaging / Events | | | |
-| Infrastructure / Runtime | | | |
+#### C1 — {{Contract name}}
 
-> Keep rationale concise here and, when more depth is required (trade-offs, benchmarks), add a short summary plus pointer to the Supporting References section and `research.md` for raw investigation notes.
+- **Owner:** {{boundary or future owner task}}
+- **Consumers:** {{boundaries or future consumer tasks}}
+- **Shape/behavior:** {{typed request, response, event, schema, state, or error contract}}
+- **Compatibility:** {{versioning or migration constraint when relevant}}
 
-## Canonical Contracts & Invariants
+## Verification Definitions
 
-Capture only the contracts whose inconsistency would break downstream implementation or verification. If the feature touches auth/session, transport/entrypoints, persistence/schema, generated artifacts, or runtime outputs, this section is mandatory.
+<!--
+Canonical parser syntax is one single-line definition per V ID. Keep every
+label on the same line; do not replace this with a table or a V heading.
+-->
 
-| Contract Area | Canonical Decision | Applies To | Must Stay Consistent In |
-|---------------|--------------------|------------|-------------------------|
-| Auth / session | | | |
-| Transport / entrypoints | | | |
-| Data / persistence | | | |
-| Deletion / retention policy | | | |
-| Generated artifacts / runtime outputs | | | |
+- **V1**: Criteria R{{SUBJECT_REQ}}.{{X}}; Owner A-D-01; Decision refs D1, I1, C1; Method command `{{exact command}}`; Expected {{concrete observable result}}; Negative/failure {{concrete rejected or recovery case}}; Reachability/grounding entrypoint `{{exact/repository/entrypoint}}` via A-D-01.
 
-> Task files must reuse the same contract wording. If the feature touches delete-data or privacy retention, explicitly decide whether re-registration is blocked and how that lock works without keeping raw PII. If implementation later needs a different contract, update this section first before generating or editing tasks.
+<!-- Only for a typed proof boundary, insert after Owner: Proof criteria Rn.m; Proof owner <distinct owner>; Evidence anchor <proof-owned anchor>; -->
 
-### Machine-checkable contracts (optional, recommended for cross-layer work)
+<!-- Full-only conditional sections follow. Keep only those relevant to this feature. -->
 
-When a data shape must stay identical across layers (e.g. a response consumed by both a backend task and a frontend task), define it as a **named contract block** so the validator can detect drift. Mark it with an HTML comment `<!-- contract:NAME -->` on its own line, immediately followed by a fenced code block holding the shape. For example, a contract named `OrderResponse` would be an HTML marker line followed by a json fenced block containing `{ "orderId": "string", "total": "number" }`.
+## Flow (Full, conditional)
 
-Any task that produces or consumes this shape adds a `Contracts: OrderResponse` line in its body and **copies the same fenced block verbatim**. `validate-spec-output.cjs` then fails the spec if a task's copy diverges from this canonical definition, or references a contract name not defined here. This is opt-in: specs without `<!-- contract:* -->` markers are unaffected.
+{{Only multi-step, branching, asynchronous, or cross-boundary flow decisions.}}
 
-## System Flows
+## Data and Consistency (Full, conditional)
 
-Provide only the diagrams needed to explain non-trivial flows. Use pure Mermaid syntax. Common patterns:
-- Sequence (multi-party interactions)
-- Process / state (branching logic or lifecycle)
-- Data / event flow (pipelines, async messaging)
+{{Ownership, schema, constraints, concurrency, lifecycle, or idempotency. For any retention/lifecycle policy, state clock anchor, clock source, timezone/precision, cutoff comparator/inclusivity, enforcement boundary, and a wrong-clock/boundary counterexample.}}
 
-Skip this section entirely for simple CRUD changes.
-> Describe flow-level decisions (e.g., gating conditions, retries) briefly after the diagram instead of restating each step.
+## Errors and Recovery (Full, conditional)
 
-## Requirements Traceability
+{{Trigger, error contract, retry/rollback/reconciliation, and terminal state.}}
 
-Use this section for complex or compliance-sensitive features where requirements span multiple domains. Straightforward 1:1 mappings can rely on the Components summary table.
+## Security and Privacy (Full, conditional)
 
-Map each requirement ID (e.g., `2.1`) to the design elements that realize it.
+{{Trust boundary, authorization, sensitive data, deletion, and retention decisions.}}
 
-| Requirement | Summary | Components | Interfaces | Flows |
-|-------------|---------|------------|------------|-------|
-| 1.1 | | | | |
-| 1.2 | | | | |
+## Migration and Compatibility (Full, conditional)
 
-> Omit this section only when a single component satisfies a single requirement without cross-cutting concerns.
+{{Ordering, compatibility window, rollback trigger, and migration proof.}}
 
-## Components and Interfaces
+## Unresolved Questions
 
-Provide a quick reference before diving into per-component details.
-
-- Summaries can be a table or compact list. Example table:
-  | Component | Domain/Layer | Intent | Req Coverage | Key Dependencies (P0/P1) | Contracts |
-  |-----------|--------------|--------|--------------|--------------------------|-----------|
-  | ExampleComponent | UI | Displays XYZ | 1, 2 | GameProvider (P0), MapPanel (P1) | Service, State |
-- Only components introducing new boundaries (e.g., logic hooks, external integrations, persistence) require full detail blocks. Simple presentation components can rely on the summary row plus a short Implementation Note.
-
-Group detailed blocks by domain or architectural layer. For each detailed component, list requirement IDs as `2.1, 2.3` (omit “Requirement”). When multiple UI components share the same contract, reference a base interface/props definition instead of duplicating code blocks.
-
-### [Domain / Layer]
-
-#### [Component Name]
-
-| Field | Detail |
-|-------|--------|
-| Intent | 1-line description of the responsibility |
-| Requirements | 2.1, 2.3 |
-| Owner / Reviewers | (optional) |
-
-**Responsibilities & Constraints**
-- Primary responsibility
-- Domain boundary and transaction scope
-- Data ownership / invariants
-
-**Dependencies**
-- Inbound: Component/service name — purpose (Criticality)
-- Outbound: Component/service name — purpose (Criticality)
-- External: Service/library — purpose (Criticality)
-
-Summarize external dependency findings here; deeper investigation (API signatures, rate limits, migration notes) lives in `research.md`.
-
-**Contracts**: Service [ ] / API [ ] / Event [ ] / Batch [ ] / State [ ]  ← check only the ones that apply.
-
-##### Service Interface
-```typescript
-interface [ComponentName]Service {
-  methodName(input: InputType): Result<OutputType, ErrorType>;
-}
-```
-- Preconditions:
-- Postconditions:
-- Invariants:
-
-##### API Contract
-| Method | Endpoint | Request | Response | Errors |
-|--------|----------|---------|----------|--------|
-| POST | /api/resource | CreateRequest | Resource | 400, 409, 500 |
-
-##### Event Contract
-- Published events:  
-- Subscribed events:  
-- Ordering / delivery guarantees:
-
-##### Batch / Job Contract
-- Trigger:  
-- Input / validation:  
-- Output / destination:  
-- Idempotency & recovery:
-
-##### State Management
-- State model:  
-- Persistence & consistency:  
-- Concurrency strategy:
-
-**Implementation Notes**
-- Integration: 
-- Validation: 
-- Risks:
-
-## Data Models
-
-Focus on the portions of the data landscape that change with this feature.
-
-### Domain Model
-- Aggregates and transactional boundaries
-- Entities, value objects, domain events
-- Business rules & invariants
-- Optional Mermaid diagram for complex relationships
-
-### Logical Data Model
-
-**Structure Definition**:
-- Entity relationships and cardinality
-- Attributes and their types
-- Natural keys and identifiers
-- Referential integrity rules
-
-**Consistency & Integrity**:
-- Transaction boundaries
-- Cascading rules
-- Temporal aspects (versioning, audit)
-
-### Physical Data Model
-**When to include**: When implementation requires specific storage design decisions
-
-**For Relational Databases**:
-- Table definitions with data types
-- Primary/foreign keys and constraints
-- Indexes and performance optimizations
-- Partitioning strategy for scale
-
-**For Document Stores**:
-- Collection structures
-- Embedding vs referencing decisions
-- Sharding key design
-- Index definitions
-
-**For Event Stores**:
-- Event schema definitions
-- Stream aggregation strategies
-- Snapshot policies
-- Projection definitions
-
-**For Key-Value/Wide-Column Stores**:
-- Key design patterns
-- Column families or value structures
-- TTL and compaction strategies
-
-### Data Contracts & Integration
-
-**API Data Transfer**
-- Request/response schemas
-- Validation rules
-- Serialization format (JSON, Protobuf, etc.)
-
-**Event Schemas**
-- Published event structures
-- Schema versioning strategy
-- Backward/forward compatibility rules
-
-**Cross-Service Data Management**
-- Distributed transaction patterns (Saga, 2PC)
-- Data synchronization strategies
-- Eventual consistency handling
-
-Skip subsections that are not relevant to this feature.
-
-## Error Handling
-
-### Error Strategy
-Concrete error handling patterns and recovery mechanisms for each error type.
-
-### Error Categories and Responses
-**User Errors** (4xx): Invalid input → field-level validation; Unauthorized → auth guidance; Not found → navigation help
-**System Errors** (5xx): Infrastructure failures → graceful degradation; Timeouts → circuit breakers; Exhaustion → rate limiting  
-**Business Logic Errors** (422): Rule violations → condition explanations; State conflicts → transition guidance
-
-**Process Flow Visualization** (when complex business logic exists):
-Include Mermaid flowchart only for complex error scenarios with business workflows.
-
-### Monitoring
-Error tracking, logging, and health monitoring implementation.
-
-## Testing Strategy
-
-### Default sections (adapt names/sections to fit the domain)
-- Unit Tests: 3–5 items from core functions/modules (e.g., auth methods, subscription logic)
-- Integration Tests: 3–5 cross-component flows (e.g., webhook handling, notifications)
-- E2E/UI Tests (if applicable): 3–5 critical user paths (e.g., forms, dashboards)
-- Performance/Load (if applicable): 3–4 items (e.g., concurrency, high-volume ops)
-
-## Conditional Sections (Include when relevant)
-
-### Security Considerations
-_**REQUIRED** when features handle user data, authentication, PII, external integrations, or permissions. Omit only for purely internal UI changes._
-- Threat modeling, security controls, compliance requirements
-- Authentication and authorization patterns
-- Data protection and privacy considerations
-
-### Performance & Scalability
-_Use this section when performance targets, high load, or scaling concerns exist. Record only feature-specific targets or trade-offs and rely on steering documents for general practices._
-- Target metrics and measurement strategies
-- Scaling approaches (horizontal/vertical)
-- Caching strategies and optimization techniques
-
-### Migration Strategy
-Include a Mermaid flowchart showing migration phases when schema/data movement is required.
-- Phase breakdown, rollback triggers, validation checkpoints
-
-## Supporting References (Optional)
-- Create this section only when keeping the information in the main body would hurt readability (e.g., very long TypeScript definitions, vendor option matrices, exhaustive schema tables). Keep decision-making context in the main sections so the design stays self-contained.
-- Link to the supporting references from the main text instead of inlining large snippets.
-- Background research notes and comparisons continue to live in `research.md`, but their conclusions must be summarized in the main design.
+- None.

package/src/claude/skills/specs/templates/requirements.md

@@ -1,52 +1,42 @@
-# Requirements Document
+# Requirements
 
-## Introduction
-{{INTRODUCTION}}
+## Outcomes
 
-## Requirements
+- {{Observable product or system outcome}}
 
-### Requirement 1: {{REQUIREMENT_AREA_1}}
-<!-- Requirement headings MUST include a leading numeric ID only (for example: "Requirement 1: ...", "1. Overview", "2 Feature: ..."). Alphabetic IDs like "Requirement A" are not allowed. -->
-<!-- Acceptance criteria use EXPLICIT literal IDs `R{N}.{M}` (R1.1, R1.2, ...), NOT a bare numbered list. This lets the validator verify per-criterion coverage (each R1.1 must be mapped by a task `_Requirements: 1.1_`). Do not switch to a bare `1. 2. 3.` list — that silently disables sub-criterion coverage. -->
-**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
+## Scope
 
-#### Acceptance Criteria
-- **R1.1** When [event], the [system] shall [response/action]
-- **R1.2** If [trigger], then the [system] shall [response/action]
-- **R1.3** While [precondition], the [system] shall [response/action]
-- **R1.4** Where [feature is included], the [system] shall [response/action]
-- **R1.5** The [system] shall [response/action]
+### In scope
 
-### Requirement 2: {{REQUIREMENT_AREA_2}}
-**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
+- {{Approved behavior or boundary}}
 
-#### Acceptance Criteria
-- **R2.1** When [event], the [system] shall [response/action]
-- **R2.2** When [event] and [condition], the [system] shall [response/action]
+### Non-goals
 
-<!-- Additional requirements follow the same pattern, with literal R{N}.{M} IDs -->
+- {{Explicit exclusion that prevents scope inference}}
 
-## Non-Functional Requirements
+## Requirements
 
-<!-- Continue the SAME numeric sequence as functional requirements. Do NOT switch to labels like NFR-1, SEC-1, PERF-1. -->
+### Requirement 1: {{Outcome area}}
 
-### Requirement {{NEXT_REQ_NUMBER}}: Performance & Scalability
-**Objective:** As a system owner, I want predictable performance characteristics, so that the feature remains usable under expected load.
+<!-- Keep Objective/User Story only when role and benefit remove ambiguity. -->
+{{Optional: **Objective:** As a <role>, I want <capability>, so that <benefit>.}}
 
 #### Acceptance Criteria
-- **R{{NEXT_REQ_NUMBER}}.1** The [system] shall [measurable performance metric, e.g. "respond within 500ms"]
-- **R{{NEXT_REQ_NUMBER}}.2** The [system] shall [measurable scale metric, e.g. "support 100 concurrent users"]
 
-### Requirement {{NEXT_REQ_NUMBER_PLUS_ONE}}: Security & Privacy
-**Objective:** As a security/compliance stakeholder, I want the feature to protect sensitive data and enforce access boundaries, so that the system is safe to ship.
+- **R1.1** When {{event}}, the {{system}} shall {{measurable subject response}}.
 
-#### Acceptance Criteria
-- **R{{NEXT_REQ_NUMBER_PLUS_ONE}}.1** The [system] shall [measurable security behavior, e.g. "encrypt data at rest using AES-256"]
-- **R{{NEXT_REQ_NUMBER_PLUS_ONE}}.2** If [unauthorized or invalid condition], the [system] shall [deny or recover with explicit behavior]
+<!-- Add a separate proof criterion only when a typed proof boundary exists. -->
 
-### Requirement {{NEXT_REQ_NUMBER_PLUS_TWO}}: Reliability & Availability
-**Objective:** As an operator, I want predictable failure handling, so that incidents remain diagnosable and recoverable.
+<!-- Add state, optional-feature, or ubiquitous EARS criteria only when relevant. -->
+<!-- Add a concrete example only when values, order, boundaries, or transformation could be interpreted differently. -->
 
-#### Acceptance Criteria
-- **R{{NEXT_REQ_NUMBER_PLUS_TWO}}.1** If [failure condition], the [system] shall [recovery behavior]
-- **R{{NEXT_REQ_NUMBER_PLUS_TWO}}.2** The [system] shall [durability / retry / fallback expectation]
+#### Examples (conditional)
+
+- {{Input/state}} → {{expected output/state}}
+
+<!-- Repeat Requirement N with literal RN.M acceptance IDs. -->
+<!-- Add feature-specific NFRs in the same numeric sequence only when measurable and relevant. -->
+
+## Unresolved Questions
+
+- None.

package/src/claude/skills/specs/templates/research.md

@@ -1,108 +1,19 @@
-# Research & Design Decisions
+# Research: {{FEATURE_NAME}}
 
----
-**Purpose**: Capture discovery findings, architectural investigations, and rationale that inform the technical design.
+Research exists only because this uncertainty can change requirements or design. Record evidence and a decision; do not use this file as a generic discovery log.
 
-**Usage**:
-- Log research activities and outcomes during the discovery phase.
-- Document design decision trade-offs that are too detailed for `design.md`.
-- Provide references and evidence for future audits or reuse.
----
+## Uncertainty
 
-## Summary
-- **Feature**: `<feature-name>`
-- **Discovery Scope**: New Feature / Extension / Simple Addition / Complex Integration
-- **Key Findings**:
-  - Finding 1
-  - Finding 2
-  - Finding 3
+- {{UNCERTAINTY}}
 
 ## Evidence Summary
-This section is mandatory for non-trivial specs. It must be written before finalizing requirements, design, or tasks.
 
-- **Codebase Scout**: Required / Skipped
-  - Result or skip rationale:
-  - Relevant files/modules:
-  - Existing patterns/contracts:
-  - Tests or checks affected:
-- **External / Current Research**: Required / Skipped
-  - Result or skip rationale:
-  - Primary sources:
-  - Current constraints or best practices:
-- **Selected Decision**:
-  - Decision:
-  - Why it fits the current codebase:
-  - Why it fits current external constraints:
-- **Rejected Alternatives**:
-  - Alternative 1 — rejection reason
-  - Alternative 2 — rejection reason
-- **Remaining Gaps / Questions**:
-  - Gap 1
-  - Gap 2
-- **Downstream Task & Test Implications**:
-  - Task implication:
-  - Test/verification implication:
+<!-- Cite concrete repository evidence or current primary sources that resolve the uncertainty. -->
 
-## Codebase Scout
-Capture only useful repo evidence, not raw file dumps.
+## Decision
 
-| Area | Finding | Evidence / Path | Implication |
-|------|---------|-----------------|-------------|
-| Project surface | | | |
-| Relevant files/modules | | | |
-| Existing patterns | | | |
-| Contracts | | | |
-| Tests and verification | | | |
-| Blast radius | | | |
-| Staleness / conflicts | | | |
+<!-- State the selected decision and how the evidence supports it. -->
 
-## External / Current Research
-Use official docs, standards, package repos, release notes, or maintained upstream references first.
+## Remaining Gaps
 
-| Question | Source | Finding | Decision Impact |
-|----------|--------|---------|-----------------|
-| | | | |
-
-## Research Log
-Document notable investigation steps and their outcomes. Group entries by topic for readability.
-
-### [Topic or Question]
-- **Context**: What triggered this investigation?
-- **Sources Consulted**: Links, documentation, API references, benchmarks
-- **Findings**: Concise bullet points summarizing the insights
-- **Implications**: How this affects architecture, contracts, or implementation
-
-_Repeat the subsection for each major topic._
-
-## Architecture Pattern Evaluation
-List candidate patterns or approaches that were considered. Use the table format where helpful.
-
-| Option | Description | Strengths | Risks / Limitations | Notes |
-|--------|-------------|-----------|---------------------|-------|
-| Hexagonal | Ports & adapters abstraction around core domain | Clear boundaries, testable core | Requires adapter layer build-out | Aligns with existing steering principle X |
-
-## Design Decisions
-Record major decisions that influence `design.md`. Focus on choices with significant trade-offs.
-
-### Decision: `<Title>`
-- **Context**: Problem or requirement driving the decision
-- **Alternatives Considered**:
-  1. Option A — short description
-  2. Option B — short description
-- **Selected Approach**: What was chosen and how it works
-- **Rationale**: Why this approach fits the current project context
-- **Status**: [Proposed / Accepted / Superseded]
-- **Trade-offs**: Benefits vs. compromises
-- **Follow-up**: Items to verify during implementation or testing
-
-_Repeat the subsection for each decision._
-
-## Risks & Mitigations
-- Risk 1 — Proposed mitigation
-- Risk 2 — Proposed mitigation
-- Risk 3 — Proposed mitigation
-
-## References
-Provide canonical links and citations (official docs, standards, ADRs, internal guidelines).
-- [Title](https://example.com) — brief note on relevance
-- ...
+<!-- List only unresolved gaps that still affect scope/design, or state `None` with evidence. -->