@haposoft/cafekit 0.9.2 → 0.9.3

package/README.md

@@ -2,7 +2,7 @@
 
 > Claude Code-first spec-driven workflow and runtime bundle for AI coding assistants.
 
-[![Version](https://img.shields.io/badge/version-0.9.2-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.9.3-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Primary-orange.svg)](https://claude.ai/code)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/skills/specs/SKILL.md

@@ -184,6 +184,7 @@ flowchart TD
 ## Detailed Workflow
 
 ### Step 1: Analyze Description
+- Load `references/ask-user-question-gates.md` before asking user questions. Ask only at documented gates; do not ask questions that repo evidence or official/current docs can answer.
 - Assess clarity and complexity of the description
 - Route to `hapo:brainstorm` before creating files when:
   - the expected output or acceptance criteria are not concrete
@@ -209,6 +210,7 @@ Load: `references/cross-spec-dependency.md`
 
 ### Step 3: Complexity Assessment & Scope Inquiry
 Load: `references/scope-inquiry.md`
+- Also load `references/ask-user-question-gates.md` when scope, evidence, contract, or architecture decisions require user input.
 - Evaluate the request across **5 dimensions**: Semantic Intent, Implementation Hypothesis, Gap Sizing, Risk/Uncertainty (Cynefin), and Blast Radius
 - If Risk = **Chaotic** → exit spec workflow, redirect to `hapo:hotfix`
 - If Risk = **Complex** → include spike/prototype tasks in the spec
@@ -252,6 +254,8 @@ Load: `references/scope-inquiry.md`
 - Read `spec.json` — stop if requirements haven't completed
 - Pick discovery mode: `minimal` / `light` / `full` based on complexity. **Default: `light`** unless certain it is simple UI (minimal) or complex integration (full).
 - Load `rules/design-principles.md`
+- Load `rules/phase-decision-matrix.md` to define implementation slices, task clusters, foundation boundaries, spike needs, integration gates, and verification gates before task generation.
+- Load `references/ask-user-question-gates.md` if a design decision would change scope, contract, provider/platform, or implementation safety.
 - Load `rules/design-discovery-[mode].md`:
   - **minimal**: UI-only or simple CRUD
   - **light**: extending existing system
@@ -267,6 +271,9 @@ Load: `references/scope-inquiry.md`
 - Read `spec.json` — stop if `requirements.md` or `design.md` missing
 - Respect `scope_lock` — only use valid requirement IDs within `in_scope`
 - Load `rules/tasks-generation.md` for core principles
+- Load `rules/phase-decision-matrix.md` before generating task files. Treat "phase" as an implementation slice/task cluster, not a `phase-XX.md` artifact.
+- Load `rules/task-scoring-rubric.md` for every candidate task to decide priority, split/merge, spike needs, dependencies, parallel eligibility, and evidence depth.
+- Load `references/ask-user-question-gates.md`; if scoring reveals unapproved scope expansion or an unresolved user-owned choice, pause before writing task files.
 - Load `rules/tasks-parallel-analysis.md` for parallel markers (default: enabled)
 - Each task file follows template `templates/task.md`
 - `Related Files` and test plans must inherit paths, contracts, and test targets from the codebase scout. If exact files/tests cannot be named for an enhancement, run targeted inspect before generating tasks.
@@ -345,6 +352,7 @@ Load: `references/task-hydration.md`
 
 ### Step 9: Validation Review (Optional)
 Load: `references/review.md` + `rules/design-review.md`
+- Load `references/ask-user-question-gates.md` before applying validation or red-team changes. User approval is required when findings modify approved scope, requirements, canonical contracts, design decisions, or task behavior.
 - System auto-evaluates spec complexity and decides review depth:
   - **< 3 task files, no security concerns** → Validate only (lightweight interview)
   - **>= 5 task files OR security/migration keywords** → Red Team first, then Validate
@@ -551,10 +559,13 @@ Before finalizing any specification, assert all the following:
 - `design-discovery-full.md` — Full research workflow
 - `design-discovery-light.md` — Lightweight research workflow
 - `design-review.md` — Design review GO/NO-GO process
+- `phase-decision-matrix.md` — Implementation slice/task-cluster boundary rules
 - `tasks-generation.md` — Task generation rules (includes spike task rules)
 - `tasks-parallel-analysis.md` — Parallel task analysis
+- `task-scoring-rubric.md` — Task priority, split/merge, spike, dependency, and evidence-depth scoring
 
 ### References (`references/`)
+- `ask-user-question-gates.md` — AskUserQuestion gate matrix for user-owned decisions
 - `cross-spec-dependency.md` — Cross-spec dependency detection
 - `scope-inquiry.md` — 5-Dimension Complexity Assessment (Semantic, Hypothesis, Gap, Risk/Cynefin, Blast Radius)
 - `research-strategy.md` — Research strategy (7 tools)

package/src/claude/skills/specs/references/ask-user-question-gates.md

@@ -0,0 +1,61 @@
+# AskUserQuestion Gate Matrix
+
+Use this matrix to decide when `hapo:specs` must pause for user input. Ask only when the answer changes scope, architecture, requirements, task shape, validation disposition, or implementation safety.
+
+## Source Priority
+
+Resolve uncertainty in this order:
+
+1. Existing `spec.json`, `requirements.md`, `research.md`, `design.md`, and task files.
+2. Codebase evidence from targeted scout/inspect.
+3. Official/current external docs when platform/provider behavior matters.
+4. Reasonable default from CafeKit rules.
+5. `AskUserQuestion` only when the remaining decision is user-owned.
+
+Do not ask about facts that codebase or official docs can answer.
+
+## Gate Matrix
+
+| Gate | Trigger | Ask? | Question shape | Record in |
+|---|---|---:|---|---|
+| Operation | `/hapo:specs` called without args | Yes | Choose create/status/resume/validate/archive | none |
+| Active spec | In-progress or branch-matched spec exists | Yes | Continue existing vs create new | `spec.json` if changed |
+| Pre-spec clarity | Description lacks concrete output, actor, or acceptance signal | Yes | 1-2 clarifying questions | `spec.json.scope_lock` |
+| Brainstorm routing | 2+ plausible architectures and no approved direction | Yes | Route to brainstorm vs continue minimal spec | final response / `research.md` |
+| Scope inquiry | Non-trivial task after 5D assessment | Yes | Expand / Hold / Reduce | `spec.json.scope_lock` |
+| Evidence gap | Required evidence is unavailable after targeted research | Yes | Continue with explicit risk / run more scout / narrow scope | `research.md` |
+| Architecture tie | Two approaches are materially similar after evidence | Yes | Pick approach with recommended option first | `design.md` |
+| Contract change | Auth, persistence, provider, API, CLI, schema, permissions, or runtime contract changes | Yes if user intent not explicit | Confirm contract and rollback expectations | `design.md` canonical contracts |
+| Scope expansion | A task candidate adds work not in `scope_lock` | Yes | Approve expansion / defer / reject | `spec.json.scope_lock` + affected docs |
+| High-risk spike | Risk = Complex and spike may change deliverables | Yes if cost/scope impact > 4h | Spike now / reduce / defer | `research.md` + task file |
+| Task conflict | Parallel candidate shares files/contracts with another task | No by default | Resolve sequentially unless business deadline requires parallelization | task dependencies |
+| Validation findings | Red-team/validate findings modify approved scope/design/tasks | Yes | Apply accepted / review each / reject all | `reports/red-team-report.md` or validation log |
+| Final contradiction | Whole-spec sweep finds unresolved contradiction | Yes | Choose authoritative source/decision | affected docs + `spec.json` |
+
+## Question Format
+
+Every `AskUserQuestion` must:
+
+- Ask 1-3 questions max per pause.
+- Provide 2-3 concrete options.
+- Put recommended option first and suffix label with `(Recommended)`.
+- Explain the tradeoff in one sentence per option.
+- Include an implicit free-form "Other" option when the tool supports it.
+
+## Do Not Ask
+
+Do not ask when:
+
+- The answer is discoverable via repo files, tests, docs, or official/current docs.
+- The choice is pure implementation detail with no scope/user impact.
+- The task can safely use an existing codebase convention.
+- The question exists only to avoid making a normal engineering judgment.
+
+## Recording Rules
+
+After a user answer:
+
+- Update the artifact that drives implementation, not only a report.
+- Keep exact selected option and custom free text when provided.
+- Add unresolved questions at the end of the affected document.
+- Do not mark `ready_for_implementation = true` while a blocking question remains unresolved.

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

@@ -0,0 +1,55 @@
+# 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.
+
+Use this matrix after `requirements.md` and `design.md` exist, before generating task files.
+
+## Slice Types
+
+| 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 |
+
+## Selection Rules
+
+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.
+
+## Split / Merge Signals
+
+Split into separate task files when:
+
+- 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.
+
+Merge when:
+
+- 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.
+
+## Output Requirements
+
+Before writing task files, capture the chosen slices in working notes and ensure:
+
+- 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`.

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

@@ -0,0 +1,52 @@
+# Task Scoring Rubric
+
+Use this rubric after applying the Phase Decision Matrix and before writing each task file. The score determines priority, split/merge, spike needs, dependency shape, and evidence depth.
+
+## Score Each Candidate Task
+
+Score each dimension 0-3.
+
+| Dimension | 0 | 1 | 2 | 3 |
+|---|---|---|---|---|
+| Dependency criticality | Standalone | Depends on one task | Blocks one feature slice | Blocks many tasks or core runtime |
+| Implementation risk | Routine | Known pattern, minor edge cases | Complex logic or integration | Unproven behavior, migration, security, provider/platform uncertainty |
+| Blast radius | Isolated file | Feature-local files | Shared component/API/config | Auth, data layer, routing, permissions, package export, or critical path |
+| User value | Internal cleanup | Enables later work | User-visible improvement | Core acceptance criterion or launch blocker |
+| Evidence confidence | Proven by code/tests/docs | Mostly proven | Partial evidence | Low/no evidence |
+| Testability burden | Simple unit/smoke | Component/integration | Multi-step workflow | E2E/security/performance/rollback proof required |
+| File conflict risk | No overlap | Minor shared utility | Shared module with consumers | Same files as another task or cross-agent conflict likely |
+| Scope creep risk | Fully in scope | Small interpretation | Adds adjacent behavior | Adds unapproved feature/contract |
+
+## Interpret Score
+
+| Total | Priority | Action |
+|---:|---|---|
+| 0-6 | P3 | Keep compact. Merge if no independent proof exists. |
+| 7-12 | P2 | Normal task. Include explicit dependencies and evidence. |
+| 13-18 | P1 | High attention. Consider split, stronger evidence, and validation note. |
+| 19+ | P1 critical | Split or add spike. Do not mark parallel unless file ownership is isolated. |
+
+## Mandatory Overrides
+
+- If Scope creep risk = 3, stop and use `AskUserQuestion` before generating the task.
+- If Evidence confidence = 3 and Implementation risk >= 2, create a spike task first.
+- If Blast radius = 3, include rollback/negative-path proof in `Evidence`.
+- If File conflict risk >= 2, remove `(P)` unless ownership is explicitly separated.
+- If User value = 3 and Dependency criticality >= 2, schedule early unless blocked by foundation work.
+
+## Task Metadata Decisions
+
+- `priority`: from total score plus overrides.
+- `dependencies`: list every required predecessor task file.
+- `(P)` marker: allowed only when dependency and file conflict scores are <= 1 and design boundaries do not overlap.
+- `Evidence`: choose proof type from `tasks-generation.md` Test Type Selection table; increase proof depth for high scores.
+- `Risk Assessment`: include all dimensions scored 2-3 as risks or constraints.
+
+## Compact Output
+
+Do not write the raw score table into every task file. Use the rubric to shape task content. Surface only decisions that affect implementation:
+
+- why task is P1/P2/P3
+- why it is split/merged
+- why it is or is not parallel
+- why a spike or extra proof is required

package/src/claude/skills/specs/rules/tasks-generation.md

@@ -2,6 +2,17 @@
 
 ## Core Principles
 
+### 0. Pre-Generation Decision Gates
+
+Before writing any `tasks/task-R*.md` file:
+
+1. Load `phase-decision-matrix.md` and identify implementation slices/task clusters: R0 foundation, risk spikes, vertical slices, layer slices, cross-cutting slices, integration gates, verification gates, and release/packaging slices when in scope.
+2. Load `task-scoring-rubric.md` and score each candidate task. Use the result to choose priority, split/merge, spike needs, dependencies, parallel eligibility, and evidence depth.
+3. Load `../references/ask-user-question-gates.md` if scoring or slicing detects unapproved scope expansion, unresolved architecture tie, missing evidence, contract ambiguity, or final contradiction.
+4. Do not ask about facts that targeted scout, repo files, tests, or official/current docs can answer.
+
+The raw score table does not need to appear in each task file. The task file must reflect the decisions: why the task exists, what it depends on, why it is split/merged, whether it can be parallel, and what proof is required.
+
 ### 1. Natural Language Descriptions
 Focus on capabilities and outcomes, not code structure.
 
@@ -71,6 +82,7 @@ When splitting a requirement into multiple tasks:
 2. **Split by concern** — e.g., R3-01 for consent onboarding UI, R3-02 for consent version re-check logic
 3. **Split by dependency chain** — if acceptance criteria A must finish before B can start, they belong in separate task files with explicit `Dependencies:`
 4. **Never split by arbitrary size** — don't create 3 task files just because "3 feels right"
+5. **Use the Phase Decision Matrix** — only split when the implementation slice has an independent deliverable boundary or proof path.
 
 #### Cross-cutting requirements
 Some requirements (e.g., "language handling", "error handling") naturally touch code in many other requirements' tasks. For these:
@@ -86,6 +98,7 @@ Grouping tasks vertically by requirement carries the risk of "siloed" or fragmen
 2. **Shared Interfaces (Horizontal Contracts)**: Sub-tasks that touch shared cross-requirement architecture (like registering a new page in a global `router.ts` or adding a column to a shared table) MUST explicitly reference the shared contract defined in `design.md`. 
 3. **Integration Enforcers**: If R1 and R2 interact (e.g., R2 UI displays data fetched by R1 backend), the later task MUST have a sub-task explicitly dedicated to "Wiring/Integrating with [Previous Feature] output".
 4. **Final Runtime Integration**: For any feature that has a user-facing screen, public route, CLI command, background worker, browser extension surface, or API flow, create a final integration task (or a final integration section in the last dependent task) that proves the whole scoped feature works from its runtime entrypoint. This task MUST fail if prior-task outputs exist but are not imported, mounted, registered, or invoked.
+5. **Scored Sequencing**: Use `task-scoring-rubric.md` to schedule high-value/high-dependency tasks early, but only after required foundation/spike work. High file-conflict or high blast-radius tasks must not be marked `(P)` without isolated ownership.
 
 ### 3d. Spike Tasks for Complex/Uncertain Areas (MANDATORY)