@haposoft/cafekit 0.9.1 → 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.1-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.1",
+  "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/hooks/state.cjs

@@ -26,6 +26,8 @@ try {
 
   const EXPIRY_DAYS = 7;
   const MAX_ARCHIVES = 5;
+  const MAX_AGENT_SECTIONS = 3;
+  const MAX_MODIFIED_FILES_DISPLAY = 5;
   const TRACKED_POST_TOOL_EVENTS = new Set(['Task', 'TaskCreate', 'TaskUpdate', 'TodoWrite']);
 
   function stateDir(cwd) {
@@ -126,7 +128,7 @@ try {
       }).trim();
 
       if (diff) {
-        data.modifiedFiles = diff.split('\n').slice(0, 20);
+        data.modifiedFiles = diff.split('\n').slice(0, MAX_MODIFIED_FILES_DISPLAY);
       }
     } catch {
       // fail-open
@@ -157,27 +159,40 @@ try {
   }
 
   function buildAgentSection(data) {
-    const agentType = data.agent_type || 'unknown';
+    const agentType = data.agent_type || '';
+    if (!agentType || agentType === 'unknown') return '';
     const time = new Date().toISOString().slice(11, 19);
     return `\n## Agent Result: ${agentType} (${time})\n- Completed at ${time}\n`;
   }
 
+  function takeRecentAgentSections(sections) {
+    if (!Array.isArray(sections) || sections.length <= MAX_AGENT_SECTIONS) return sections || [];
+    return sections.slice(-MAX_AGENT_SECTIONS);
+  }
+
   function mergeAgentSections(existing, content) {
     if (!existing) return content;
 
     const agentSections = existing.match(/## Agent Result:.+?(?=\n## |$)/gs);
     if (!agentSections) return content;
 
+    const kept = takeRecentAgentSections(agentSections);
     const marker = '\n## Key Files Modified';
     if (content.includes(marker)) {
-      return content.replace(marker, `\n${agentSections.join('\n')}${marker}`);
+      return content.replace(marker, `\n${kept.join('\n')}${marker}`);
     }
 
-    return `${content.trimEnd()}\n\n${agentSections.join('\n')}\n`;
+    return `${content.trimEnd()}\n\n${kept.join('\n')}\n`;
   }
 
   function appendAgentSection(existing, agentSection) {
     if (!existing) return agentSection.trimStart();
+    if (!agentSection) {
+      const sections = existing.match(/## Agent Result:.+?(?=\n## |$)/gs) || [];
+      if (sections.length <= MAX_AGENT_SECTIONS) return existing;
+      const kept = takeRecentAgentSections(sections);
+      return existing.replace(/(## Agent Result:.+?(?=\n## |$))+/gs, kept.join('\n'));
+    }
 
     const marker = '\n## Key Files Modified';
     if (existing.includes(marker)) {
@@ -226,8 +241,10 @@ try {
     }
 
     if (event === 'SubagentStop') {
-      const file = path.join(dir, 'latest.md');
       const agentSection = buildAgentSection(data);
+      if (!agentSection) process.exit(0);
+
+      const file = path.join(dir, 'latest.md');
       const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
       const updated = existing
         ? appendAgentSection(existing, agentSection)

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

@@ -69,17 +69,30 @@ Leverage these specific tools or sub-agents to execute the workflow effectively:
 - `brainstormer`: Call only for medium/high-complexity architecture trade-offs.
 - **Ecosystem Swarm (`SendMessage`):** Call `researcher` (validation), `docs-keeper` (architecture boundaries), or `project-manager` (scope warnings) for deeply complex specs.
 
+## Discovery Question Framework
+
+Load and follow `references/question-framework.md` before the first user-facing discovery question.
+
+Use it to:
+- Generate questions from scout evidence, user intent, exact requirement gaps, matching domain matrices, and risk surfaces.
+- Avoid asking the user to answer technical facts that should be verified from code, docs, or current provider/browser documentation.
+- Prioritize only questions that can materially change architecture, MVP scope, UX, cost/privacy/security, acceptance criteria, or delivery format.
+- Record every user-confirmed decision in a decision register in the final report.
+
+If the framework conflicts with the general "one question at a time" rule, prefer the framework's question budget and batching limits: one high-impact question by default, up to 3 independent questions in one `AskUserQuestion` call only when batching reduces friction without mixing unrelated decisions.
+
 ## Authoritative Workflow
 
 ```mermaid
 flowchart TD
     A["Run /hapo:inspect or narrow scout"] --> B["Summarize codebase findings"]
-    B --> C["Ask one grounded clarifying question"]
-    C --> D{"Exact requirements captured?"}
-    D -->|No| C
+    B --> C["Load question framework"]
+    C --> DQ["Ask highest-impact grounded question"]
+    DQ --> D{"Exact requirements captured?"}
+    D -->|No| DQ
     D -->|Yes| E{"Multiple independent subsystems?"}
     E -->|Yes| F["Decompose into sub-projects"]
-    F --> C
+    F --> DQ
     E -->|No| G{"Medium/high complexity?"}
     G -->|Yes| H["Call brainstormer/researcher/docs-keeper as needed"]
     G -->|No| I["Propose 2-3 approaches"]
@@ -107,10 +120,14 @@ flowchart TD
 
 ### 2. Discovery Phase
 
-- Ask exactly **one question at a time**. Do not stack multiple unrelated questions.
+- Load `references/question-framework.md`.
+- Ask exactly **one high-impact question at a time** by default. Do not stack unrelated questions.
+- You may batch up to 3 independent questions only when each question maps to a different required decision surface and none requires explanation before the user can answer.
 - Prefer multiple-choice options grounded in scout findings.
 - Push vague intent into concrete examples, sample inputs/outputs, or acceptance criteria.
 - Challenge the first proposed solution when the underlying goal suggests a simpler path.
+- Do not ask users to decide technical facts. Research browser/runtime/provider/package facts first; then ask only the product or trade-off decision.
+- Track decisions as you go so the final report can distinguish `User Decision`, `Assumption`, and `Open Question`.
 
 ### 3. Scope Guard
 
@@ -154,7 +171,7 @@ Before passing the completed design to the user for final review, you must inter
 ### 8. Final Handoff & Documentation
 Upon the user's explicit final approval of the sanitized design document:
 1. Generate the final **Design Doc / Summary Report**.
-2. Include: problem statement, exact requirements, evaluated approaches, recommended solution, risks, validation criteria, and next steps.
+2. Include: problem statement, exact requirements, evaluated approaches, recommended solution, risks, validation criteria, decision register, open questions, and next steps.
 3. Invoke `/hapo:specs` with the report context to hand off into CafeKit's structured specification phase.
 4. Optionally update an existing project notes, docs, or report file if the approved design context should be persisted for future work.
 

package/src/claude/skills/brainstorm/references/question-framework.md

@@ -0,0 +1,232 @@
+# Brainstorm Question Framework
+
+Use this reference to decide **what to ask**, **what not to ask**, and **how to record decisions** during `hapo:brainstorm`.
+
+The goal is not to ask many questions. The goal is to ask the smallest set of questions that can materially change the design.
+
+## Source Hierarchy
+
+Generate questions from this hierarchy, in order:
+
+1. **Scout evidence** — repo type, framework, existing modules, docs, specs, plans, runtime config, and constraints.
+2. **User intent** — nouns, verbs, success language, target users, examples, and implied deliverables in the prompt.
+3. **Exact requirement gaps** — expected output, acceptance criteria, scope boundary, non-negotiable constraints, touchpoints.
+4. **Domain matrix** — only domains that actually apply to the request.
+5. **Risk matrix** — security, privacy, cost, runtime limits, provider failure, migration, compliance, maintainability.
+
+Never ask a question that the repository, docs, or trusted technical research can answer directly.
+
+## Ask / Do Not Ask
+
+Ask the user when the answer changes:
+
+- product scope or MVP boundaries
+- target user workflow or UX surface
+- expected output artifact or delivery format
+- acceptance criteria
+- business priority, timeline, or rollout
+- cost, privacy, API-key ownership, external provider choice
+- irreversible workspace action such as renaming/moving/deleting
+- whether to accept a trade-off after you explain it
+
+Do **not** ask the user when the answer is a technical fact you should verify:
+
+- browser or runtime limits
+- package/API compatibility
+- dependency maintenance state
+- security best practice
+- exact syntax for framework config
+- existing code location, schema, endpoint, or convention
+
+If a topic mixes user preference and technical fact, verify the technical facts first, then ask the preference question with those facts included.
+
+## Prioritization
+
+Before asking, score each candidate question:
+
+| Signal | Score |
+|---|---:|
+| Could change architecture, data model, or platform | +3 |
+| Could change MVP scope or exclude a feature | +3 |
+| Could affect cost, privacy, security, or compliance | +3 |
+| Defines observable acceptance criteria | +2 |
+| Defines UX flow or primary user surface | +2 |
+| Can be answered from repo/docs/research | -4 |
+| Merely names an implementation detail with a safe default | -2 |
+
+Ask only the highest-impact question. If several are tied and independent, ask at most 3 in one `AskUserQuestion` batch; otherwise ask one at a time.
+
+## Required Decision Surfaces
+
+Every brainstorm must eventually resolve these surfaces:
+
+| Surface | Question Intent |
+|---|---|
+| Outcome | What does the user expect to exist or happen after the work? |
+| Done | How will the user verify it works? |
+| Scope | What is explicitly not included now? |
+| Constraints | What cannot change: stack, platform, naming, runtime, compatibility, deadline? |
+| Touchpoints | Which existing files/modules/contracts will this affect? |
+
+If any surface is missing, ask a grounded question before proposing architecture.
+
+## Domain Matrix
+
+Use only the domains that match the request.
+
+### Product / UX
+
+Ask when the prompt includes UI, workflow, dashboard, extension, app, or user-facing behavior.
+
+- Primary user: who uses this first?
+- Primary flow: what is the shortest successful path?
+- Surface: page, overlay, sidebar, modal, command, background task?
+- State: loading, empty, error, partial result, retry?
+- Accessibility or localization expectations?
+
+### Browser Extension
+
+Ask when the work involves Chrome, Edge, Firefox, YouTube, DOM injection, content scripts, popup, options page, or browser APIs.
+
+- Target browser/runtime and manifest version?
+- UI surface: content overlay, sidebar, popup, options page, or all?
+- Permissions posture: minimal host permissions or broader convenience?
+- Storage: browser storage, IndexedDB, sync storage, or no persistence?
+- Publishing target: dev-only, Chrome Web Store, enterprise install?
+
+Verify instead of asking:
+
+- Manifest V3 service worker lifetime.
+- Browser-reserved shortcut conflicts.
+- Content script isolated-world vs main-world behavior.
+- Current Chrome API compatibility.
+
+### AI / LLM
+
+Ask when the work involves translation, summarization, agents, prompt output, generation, or provider choice.
+
+- Provider ownership: user API key, app-owned key, proxy, or local model?
+- Provider shape: fixed provider, multi-provider, or custom base URL?
+- Output contract: prose, JSON, markdown, SRT, code, patch?
+- Failure behavior: retry, fallback, partial result, ask user, or stop?
+- Cache policy: never, per session, persistent, or shared?
+- Privacy boundary: what content may leave the browser/server?
+
+Verify instead of asking:
+
+- Whether a provider is Anthropic-compatible vs OpenAI-compatible.
+- Whether a provider supports tool use / JSON schema / streaming.
+- Current API endpoint paths and auth header format.
+
+### Data / Transcript / Documents
+
+Ask when the work transforms documents, captions, data, logs, OCR, audio, video, or legacy code into another artifact.
+
+- Source priority and fallback order?
+- Output format and fidelity level?
+- Confidence / evidence tracking requirement?
+- Missing/unknown handling?
+- Export/import requirements?
+
+### Backend / API / Database
+
+Ask when the work includes server endpoints, persistence, auth, jobs, integrations, or migrations.
+
+- API contract: endpoint, method, request/response shape?
+- Persistence: new table, existing table, no DB?
+- Auth/permission model?
+- Idempotency, retries, and background job behavior?
+- Migration and rollback constraints?
+
+### Docs / Legacy Reconstruction
+
+Ask when the work is documentation, legacy analysis, or requirement reconstruction.
+
+- Scope path/module to reconstruct?
+- Output docs required: overview, requirements, architecture, evidence map, unknowns?
+- Evidence level: observed-only or inferred allowed with confidence?
+- Review gate: who approves the reconstructed docs?
+- Change request follows reconstruction or is separate?
+
+### Release / Packaging
+
+Ask when the work includes publish, store listing, npm release, versioning, or deployment.
+
+- Target release channel?
+- Version bump type?
+- Required checks before publish?
+- Store/listing metadata ownership?
+- Rollback or deprecation plan?
+
+## Question Format
+
+Use `AskUserQuestion` when available.
+
+- Use 2-4 concrete options.
+- Put the recommended option first and label it `(Recommended)`.
+- Include a one-sentence impact description per option.
+- Do not add an explicit "Other" option; the tool supplies it.
+- Avoid abstract labels like "Option A" unless paired with concrete meaning.
+
+Good:
+
+> "Where should transcript fallback live?"
+> - "Defer STT for MVP (Recommended)" — Ships faster; no fragile audio extraction now.
+> - "Browser-only STT" — No backend, but fragile and heavy.
+> - "Companion backend" — More robust, but requires hosting and ops.
+
+Bad:
+
+> "What architecture do you want?"
+
+## Explain Before Asking
+
+When the user cannot reasonably know the answer, first explain the trade-off briefly, then ask.
+
+Use this pattern:
+
+1. State why the decision matters.
+2. Give 2-3 viable options with consequences.
+3. Recommend one.
+4. Ask the user to confirm or override.
+
+Do not force a choice before explaining hidden technical risk.
+
+## Decision Register
+
+Every final brainstorm report must include a decision register.
+
+```markdown
+## Decision Register
+
+| ID | Question | Options Presented | User Decision | Rationale | Impact |
+|---|---|---|---|---|---|
+| D-001 | Where does transcript fallback live? | Defer STT / Browser-only / Backend | Defer STT | Ships MVP safely | Phase 7 becomes graceful fallback |
+```
+
+Rules:
+
+- Record only decisions actually made by the user or explicitly accepted in chat.
+- Do not write "user selected" unless `AskUserQuestion` or direct user text confirms it.
+- If you infer a default, label it as `Assumption`, not `User Decision`.
+- Carry unresolved decisions into `Open Questions`.
+
+## Maximum Question Budget
+
+Default budget:
+
+- Small change: 1-2 questions.
+- Medium feature: 3-6 questions.
+- Large/greenfield/architecture-heavy: 6-10 questions across multiple rounds.
+
+Stop asking when the next question would only refine an implementation detail with a safe default. Propose the design and list remaining assumptions instead.
+
+## Final Self-Check
+
+Before presenting design:
+
+- Did each asked question map to one of the required decision surfaces or domain risks?
+- Did any question ask the user to answer a technical fact that should have been researched?
+- Are all user decisions captured in the decision register?
+- Are assumptions clearly separated from user decisions?
+- Are open questions truly blocking, or can they be deferred?

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)