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

package/src/claude/skills/specs/rules/design-review.md

@@ -1,110 +1,55 @@
-# Design Review Process
+# Design review contract
 
-## Objective
-Conduct interactive quality review of technical design documents to ensure they are solid enough to proceed to implementation with acceptable risk.
+Review the complete routed artifact graph for implementation-blocking semantic
+gaps. Concise presentation is encouraged; inventory size is never capped.
 
-## Review Philosophy
-- **Quality assurance, not perfection seeking**
-- **Critical focus**: Limit to 3 most important concerns
-- **Interactive dialogue**: Engage with designer, not one-way evaluation
-- **Balanced assessment**: Recognize strengths and weaknesses
-- **Clear decision**: Definitive GO/NO-GO with rationale
+## Coverage
 
-## Scope & Non-Goals
+For every `RN.M` criterion:
 
-- Scope: Evaluate the quality of the design document against project context and standards to decide GO/NO-GO.
-- Non-Goals: Do not perform implementation-level design, deep technology research, or finalize technology choices. Defer such items to the design phase iteration.
+1. trace the exact implementation owner, boundary, applicable `D`/`I`/`C`
+   definitions, and canonical `V` definition;
+2. construct a concrete counterexample or failure scenario;
+3. confirm the expected result rejects or handles that scenario;
+4. confirm referenced anchors are reachable and grounded; and
+5. record every unresolved contradiction, ambiguity, missing owner, broken
+   dependency, unreachable proof, or scope violation as a blocker.
 
-## Core Review Criteria
+Also review cross-criterion contracts, state transitions, concurrency,
+authorization, recovery, compatibility, and rollback where scope activates
+them. Do not perform broad technology research during review; return an exact
+uncertainty to the artifact router when new material uncertainty is discovered.
 
-### 1. Existing Architecture Alignment (Critical)
-- Integration with existing system boundaries and layers
-- Consistency with established architectural patterns
-- Proper dependency direction and coupling management
-- Alignment with current module organization
+## Finding shape
 
-### 2. Design Consistency & Standards
-- Adherence to project naming conventions and code standards
-- Consistent error handling and logging strategies
-- Uniform configuration and dependency management
-- Alignment with established data modeling patterns
+Each blocker states:
 
-### 3. Extensibility & Maintainability
-- Design flexibility for future requirements
-- Clear separation of concerns and single responsibility
-- Testability and debugging considerations
-- Appropriate complexity for requirements
+- affected criterion and design/verification refs;
+- concrete counterexample;
+- observed conflicting or missing artifact content;
+- impact on implementation or proof; and
+- smallest semantic decision or correction required.
 
-### 4. Type Safety & Interface Design
-- Proper type definitions and interface contracts
-- Avoidance of unsafe patterns (e.g., `any` in TypeScript)
-- Clear API boundaries and data structures
-- Input validation and error handling coverage
+Group duplicates for readability without dropping distinct blockers. Positive
+observations are optional and never displace a blocker.
 
-## Review Process
+## Decision
 
-### Step 1: Analyze
-Analyze design against all review criteria, focusing on critical issues impacting integration, maintainability, complexity, and requirements fulfillment.
+- `PASS`: the full routed graph is coherent, grounded, and every criterion's
+  counterexample is resolved.
+- `FAIL`: at least one semantic or structural blocker is actionable now.
+- `BLOCKED`: required product input, trusted capability, or external evidence
+  is unavailable.
 
-### Step 2: Identify Critical Issues (≤3)
-For each issue:
-```
-🔴 **Critical Issue [1-3]**: [Brief title]
-**Concern**: [Specific problem]
-**Impact**: [Why it matters]
-**Suggestion**: [Concrete improvement]
-**Traceability**: [Requirement ID/section from requirements.md]
-**Evidence**: [Design doc section/heading]
-```
+Routine and Elevated require semantic review but no reviewer ceremony. Strict
+requires an independent allowlisted reviewer capability observed by the host
+hook. An author, task marker, receipt text, or claimed role cannot self-attest
+that capability. Risk alone has an Elevated floor; Strict is opt-in only for an
+explicit user/project audit requirement or a user-confirmed, scope-specific
+audit decision. If the host event is unavailable, pause once rather than retry,
+downgrade, or simulate authority. Deterministic validation checks implemented
+structure and grounding; it never replaces this semantic judgment.
 
-### Step 3: Recognize Strengths
-Acknowledge 1-2 strong aspects to maintain balanced feedback.
-
-### Step 4: Decide GO/NO-GO
-- **GO**: No critical architectural misalignment, requirements addressed, clear implementation path, acceptable risks
-- **NO-GO**: Fundamental conflicts, critical gaps, high failure risk, disproportionate complexity
-
-## Traceability & Evidence
-
-- Link each critical issue to the relevant requirement(s) from `requirements.md` (ID or section).
-- Cite evidence locations in the design document (section/heading, diagram, or artifact) to support the assessment.
-- When applicable, reference constraints from steering context to justify the issue.
-
-## Output Format
-
-### Design Review Summary
-2-3 sentences on overall quality and readiness.
-
-### Critical Issues (≤3)
-For each: Issue, Impact, Recommendation, Traceability (e.g., 1.1, 1.2), Evidence (design.md section).
-
-### Design Strengths
-1-2 positive aspects.
-
-### Final Assessment
-Decision (GO/NO-GO), Rationale (1-2 sentences), Next Steps.
-
-### Interactive Discussion
-Engage on designer's perspective, alternatives, clarifications, and necessary changes.
-
-## Length & Focus
-
-- Summary: 2–3 sentences
-- Each critical issue: 5–7 lines total (including Issue/Impact/Recommendation/Traceability/Evidence)
-- Overall review: keep concise (~400 words guideline)
-
-## Review Guidelines
-
-1. **Critical Focus**: Only flag issues that significantly impact success
-2. **Constructive Tone**: Provide solutions, not just criticism
-3. **Interactive Approach**: Engage in dialogue rather than one-way evaluation
-4. **Balanced Assessment**: Recognize both strengths and weaknesses
-5. **Clear Decision**: Make definitive GO/NO-GO recommendation
-6. **Actionable Feedback**: Ensure all suggestions are implementable
-
-## Final Checklist
-
-- **Critical Issues ≤ 3** and each includes Impact and Recommendation
-- **Traceability**: Each issue references requirement ID/section
-- **Evidence**: Each issue cites design doc location
-- **Decision**: GO/NO-GO with clear rationale and next steps
+Readiness stays false until the complete blocker inventory is resolved and all
+required machine gates pass. Review does not claim implementation execution,
+approval, closeout, or lifecycle completion.

package/src/claude/skills/specs/rules/ears-format.md

@@ -1,50 +1,42 @@
-# EARS Format Guidelines
-
-## Overview
-EARS (Easy Approach to Requirements Syntax) is the standard format for acceptance criteria in spec-driven development.
-
-EARS patterns describe the logical structure of a requirement (condition + subject + response) and are not tied to any particular natural language.  
-Canonical acceptance criteria are written in **English** (`spec.json.language` is `en`). A non-English rendering only appears in the optional translation mirror (`i18n/<lang>/`, see `references/translation-mirror.md`), never in the canonical files.  
-Keep EARS trigger keywords and fixed phrases in English (`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`). In the mirror, localize only the variable parts (`[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]`); do not interleave translated text inside the trigger or fixed English phrases themselves.
-
-## Primary EARS Patterns
-
-### 1. Event-Driven Requirements
-- **Pattern**: When [event], the [system] shall [response/action]
-- **Use Case**: Responses to specific events or triggers
-- **Example**: When user clicks checkout button, the Checkout Service shall validate cart contents
-
-### 2. State-Driven Requirements
-- **Pattern**: While [precondition], the [system] shall [response/action]
-- **Use Case**: Behavior dependent on system state or preconditions
-- **Example**: While payment is processing, the Checkout Service shall display loading indicator
-
-### 3. Unwanted Behavior Requirements
-- **Pattern**: If [trigger], the [system] shall [response/action]
-- **Use Case**: System response to errors, failures, or undesired situations
-- **Example**: If invalid credit card number is entered, then the website shall display error message
-
-### 4. Optional Feature Requirements
-- **Pattern**: Where [feature is included], the [system] shall [response/action]
-- **Use Case**: Requirements for optional or conditional features
-- **Example**: Where the car has a sunroof, the car shall have a sunroof control panel
-
-### 5. Ubiquitous Requirements
-- **Pattern**: The [system] shall [response/action]
-- **Use Case**: Always-active requirements and fundamental system properties
-- **Example**: The mobile phone shall have a mass of less than 100 grams
-
-## Combined Patterns
-- While [precondition], when [event], the [system] shall [response/action]
-- When [event] and [additional condition], the [system] shall [response/action]
-
-## Subject Selection Guidelines
-- **Software Projects**: Use concrete system/service name (e.g., "Checkout Service", "User Auth Module")
-- **Process/Workflow**: Use responsible team/role (e.g., "Support Team", "Review Process")
-- **Non-Software**: Use appropriate subject (e.g., "Marketing Campaign", "Documentation")
-
-## Quality Criteria
-- Requirements must be testable, verifiable, and describe a single behavior.
-- **Measurability:** Avoid qualitative terms (e.g. "safe state", "fast", "some coverage"). Replace with measurable thresholds (e.g., "HTTP 400 error", "< 500ms response", ">= 80% coverage").
-- Use objective language: "shall" for mandatory behavior, "should" for recommendations; avoid ambiguous terms.
-- Follow EARS syntax: [condition], the [system] shall [response/action].
+# EARS authoring rules
+
+Use EARS to make behavior testable, not to fill a template.
+
+## Canonical IDs
+
+- Top-level headings: `Requirement N: <outcome>`.
+- Acceptance criteria: literal `RN.M` (`R1.1`, `R1.2`, ...).
+- Task mappings: numeric `N.M` only.
+- Do not emit `REQ-01`, `NFR-1`, alphabetic IDs, or bare numbered criteria.
+
+## Patterns
+
+| Need | Pattern |
+|---|---|
+| Event | `When <event>, the <system> shall <observable response>.` |
+| State | `While <state>, the <system> shall <observable response>.` |
+| Negative/error | `If <invalid or failure condition>, the <system> shall <observable response or recovery>.` |
+| Optional scope | `Where <feature is enabled>, the <system> shall <observable response>.` |
+| Always true | `The <system> shall <observable property>.` |
+
+Combine conditions only when they describe one behavior. Split criteria that
+have independent triggers, outcomes, or proof.
+
+## Quality gate
+
+Every criterion must be singular, unambiguous, observable, and testable. Name a
+concrete subject and replace words such as “fast”, “safe”, “graceful”, or “some”
+with an observable result or threshold. Use `shall` for mandatory behavior.
+
+Add a negative/error criterion when invalid input, missing permission,
+unavailable dependency, conflict, timeout, retry, rollback, or partial failure
+is relevant. Add a concrete example when values, ordering, boundaries, or
+transformation rules would otherwise admit multiple interpretations.
+
+User Story, rationale, scenario narrative, and role framing are optional. Keep
+them only when they explain a product decision not already clear from the
+outcome and criteria.
+
+Non-functional requirements are not a standard appendix. Add one only for a
+feature-specific measurable performance, security, privacy, accessibility,
+reliability, or compatibility constraint, continuing the same numeric sequence.

package/src/claude/skills/specs/rules/phase-decision-matrix.md

@@ -1,55 +1,56 @@
-# Phase Decision Matrix
+# Task and phase decision matrix
 
-CafeKit does not create `phase-XX.md` files. In `hapo:specs`, "phase" means an implementation slice or task cluster that becomes one or more `tasks/task-R*.md` files.
+Tasks and phases are conditional structure, not mandatory planning ceremony.
 
-Use this matrix after `requirements.md` and `design.md` exist, before generating task files.
+## Task gate
 
-## Slice Types
+Create a task only when at least one boundary is real:
 
-| Slice | Use when | Output pattern | Must prove |
-|---|---|---|---|
-| R0 Foundation | Shared setup, contracts, schema, config, base runtime, permissions, package wiring | `task-R0-01-<slug>.md` | Later tasks depend on it or explicitly consume it |
-| Risk Spike | Risk = Complex, API/platform behavior uncertain, or feasibility not proven by evidence | `task-R{N}-00-spike-<slug>.md` | Go/no-go, findings, time-box <= 4h |
-| Vertical Slice | User-visible behavior crosses multiple layers but can be delivered end-to-end | `task-R{N}-01-<feature-slice>.md` | Runtime entrypoint reaches the behavior |
-| Layer Slice | Work naturally splits by layer and dependencies are clear | `task-R{N}-01-api.md`, `task-R{N}-02-ui.md` | Contract handoff between layers |
-| Cross-Cutting Slice | One concern affects many requirements, e.g. language handling, privacy, error policy | One primary task plus secondary requirement refs in related tasks | No duplicated implementation across tasks |
-| Integration Gate | Prior outputs must be wired into a route, app, command, worker, extension manifest, or runtime surface | Final task in dependency chain | No orphaned services/components/files |
-| Verification Gate | Security/performance/migration/critical path needs dedicated proof | Dedicated task only when proof cannot live inside related task | Exact command/artifact/negative-path evidence |
-| Release/Packaging | Store/package/release behavior is explicitly in scope | Last task | Build artifact and release-specific checks |
+| Boundary | Create a separate task when |
+|---|---|
+| Ownership | A distinct owner can change the files or contract without overlap. |
+| Dependency | One durable output must exist before another consumer can begin. |
+| Transition | Stateful, migration, async, retry, or recovery behavior needs one named owner. |
+| Proof | The outcome needs proof that cannot coherently live with the implementation slice. |
+| Parallel coordination | Independent work can proceed with disjoint ownership and no hidden shared resource. |
 
-## Selection Rules
+Do not create tasks from estimated effort, requirement count, architectural
+layers, risk labels, or a desire for uniform files.
 
-1. Start with requirement IDs and design contracts.
-2. Extract shared infrastructure into R0 only when 2+ later tasks consume it or a contract must exist first.
-3. Prefer vertical slices for user-facing workflows because they prove reachability early.
-4. Use layer slices when one layer blocks another or file ownership would conflict.
-5. Add a spike before implementation when evidence says the outcome is uncertain.
-6. Add an integration gate for every feature with runtime-facing outputs.
-7. Add a verification gate only when the required proof is too broad for a single implementation task.
-8. Do not create a slice just because the plan "feels large"; every slice needs a deliverable boundary.
+When the gate passes, encode the real reason as one or more typed
+`coordination.boundaries` entries. Legacy trigger fields, priority markers,
+related-file lists, and free-form declarations are not authority.
 
-## Split / Merge Signals
+## Split preference
 
-Split into separate task files when:
+Start with one vertical outcome slice that reaches a real user or runtime
+entrypoint. Split horizontally only because dependency, ownership, or proof
+requires it.
 
-- Acceptance criteria span multiple architectural layers.
-- Effort exceeds 4 hours.
-- A task would modify unrelated files or contracts.
-- One part can be verified independently before the next part starts.
-- Different agents could own the work without touching the same files.
+- Foundation: only when two or more consumers need the same owned prerequisite.
+- Spike: only for a named uncertainty with a time-box and go/no-go output.
+- Integration: only when earlier outputs are not already proven reachable.
+- Verification: only when separate ownership or evidence is genuinely required.
+- Release/packaging: only when explicitly in `scope_lock`.
 
-Merge when:
+Merge slices that touch the same files, share one proof, or would otherwise
+produce an orphaned intermediate output.
 
-- Work touches the same files and cannot be verified separately.
-- A task would only wrap another task with no independent deliverable.
-- Splitting would create orphaned support code before integration.
+## Owner-before-consumer
 
-## Output Requirements
+Every cross-task contract, invariant, schema transition, or recovery authority
+has exactly one owner task. All consumers reference its stable ID and depend
+directly or transitively on the owner. The typed dependency boundary is machine
+authority; Markdown and `task_registry.dependencies` are projections that must
+agree with it.
 
-Before writing task files, capture the chosen slices in working notes and ensure:
+## Lightweight phases
 
-- Every slice maps to at least one requirement ID or R0 foundation rationale.
-- Every runtime-facing slice names its entrypoint or later integration task.
-- Every dependency is explicit.
-- Every parallel-capable slice has no shared file ownership with sibling tasks.
-- Scope additions route through `references/ask-user-question-gates.md`.
+Use phases only for a complex `Full` task graph where grouping materially helps
+navigation or sequencing. Persist them as lightweight task-ID groups in
+`spec.json`.
+
+- Never create `phase-*.md` files.
+- Never copy requirement, design, or task prose into a phase.
+- A phase does not replace dependency edges or ownership.
+- Compact specs and simple Full graphs omit phases.

package/src/claude/skills/specs/rules/task-scoring-rubric.md

@@ -30,7 +30,8 @@ independent proof path.
 - Low evidence plus risk ≥2: consider a time-boxed spike, but do not create one
   solely because a Cynefin label says `Complex`.
 - Blast radius 3: include rollback/negative-path proof.
-- File conflict ≥2: remove `(P)` unless ownership is isolated.
+- File conflict ≥2: parallel eligibility remains false unless a typed parallel
+  boundary proves isolated ownership and disjoint resources.
 - High value plus dependency ≥2: schedule early only after real prerequisites.
 
 Cynefin is advisory discovery language. It may suggest a spike or research