@haposoft/cafekit 0.8.0 → 0.8.1

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "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",
   "private": false,
   "bin": {
-    "cafekit": "./bin/install.js"
+    "cafekit": "bin/install.js"
   },
   "scripts": {
     "test": "node scripts/run-skill-self-tests.mjs"

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

@@ -11,10 +11,10 @@ argument-hint: "<feature-description> | status | resume | --validate | archive"
 
 ## Overview
 
-This skill provides a 10-step workflow to transform ideas into specs:
+This skill provides a 10-step workflow to transform ideas into evidence-backed specs:
 
 ```
-Analyze → Dependency Scan → Complexity Assessment → Init → Requirements → Design → Tasks → Hydration → Review → Completion
+Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate + Requirements → Design → Tasks → Hydration → Review → Completion
 ```
 
 **CRITICAL:** Before starting, the system MUST:
@@ -46,6 +46,7 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Requirements
 - `task_files` in `spec.json` MUST exactly match the real files under `tasks/` after Step 7.
 - `task_registry` in `spec.json` MUST exist once task files are generated and MUST contain one entry per task file, keyed by relative path.
 - `ready_for_implementation` is a hard gate, not a convenience flag. Never set it before the finalization audit passes.
+- Non-trivial specs MUST have an evidence trail in `research.md` before requirements, design, or tasks are finalized. Evidence can be codebase scout findings, external/current research, or an explicit skip rationale.
 
 ### Output Criteria
 - Never implement code — only create spec documents
@@ -89,6 +90,7 @@ System auto-analyzes the description:
 - If the idea has unresolved architecture choices, unclear acceptance criteria, unclear scope boundaries, or multiple plausible approaches → stop and route to `/hapo:brainstorm <idea>` before creating spec artifacts
 - If task is simple (small bugfix, config change) → suggest "A spec may not be needed for this. Continue anyway?"
 - If task is complex (multi-module, security/migration related) → auto-activate deep research, ask user 3 scope questions
+- For non-trivial specs, execute the Step 5 Evidence Gate before writing final requirements. Do not design from memory when codebase or current external evidence can answer the question.
 
 ### When called WITH `--validate` argument
 
@@ -128,11 +130,11 @@ flowchart TD
     H3 -->|No| K["Keep default scope"]
     J --> L["Step 4: Init — create specs/<feature>/"]
     K --> L
-    L --> M["Step 5: Requirements — write EARS"]
-    M --> N{Need deep research?}
-    N -->|Yes| O["Research: researchers + inspector + docs"]
-    O --> P["Write research.md"]
-    N -->|No| P
+    L --> M["Step 5A: Evidence Gate — scout + research"]
+    M --> N{Evidence sufficient?}
+    N -->|No| O["Ask user / run targeted scout / external research"]
+    O --> M
+    N -->|Yes| P["Step 5B: Requirements — write EARS"]
     P --> Q["Step 6: Design — pick discovery mode"]
     Q --> R["Write design.md"]
     R --> S["Step 7: Tasks — split into individual files"]
@@ -194,12 +196,19 @@ Load: `references/scope-inquiry.md`
   - `expansion_policy`: `requires-user-approval`
 - Do NOT generate requirements, design, or tasks at this step
 
-### Step 5: Requirements & Research
+### Step 5: Evidence Gate, Requirements & Research
 - Read `spec.json` — stop if init hasn't completed
 - Stop if requirements already exist, unless user wants to regenerate
 - Respect `scope_lock` — keep new requirements within `in_scope`
-- Analyze existing codebase if this is an enhancement (not greenfield)
-- **MANDATORY Research:** Spawn `researcher` subagent to gather best practices, documentation, and technical foundation before detailing requirements. Use `Task(subagent_type="researcher", prompt="Research [feature]", description="Research")`.
+- Load `references/research-strategy.md` and `references/codebase-analysis.md`
+- Classify evidence needs before writing requirements:
+  - **Targeted codebase scout is mandatory** when the spec changes existing behavior, touches an API/CLI/package export/schema/auth/session/permission/config/hook/runtime contract, lacks exact file paths, may invalidate tests, resumes an older spec, or crosses monorepo/package/runtime boundaries.
+  - **External/current research is mandatory** when the spec depends on third-party APIs, libraries, platform policies, AI providers/models/tooling, security/auth/payment/privacy/delete-data rules, performance/accessibility/SEO/security standards, or the user asks for "best", "optimal", "latest", "recommended", or equivalent.
+  - **Skip evidence gathering only** for trivial one-file edits, internal text/docs changes, isolated new files with no integration points, or decisions already backed by a recent user-provided report. Record the skip rationale in `research.md`.
+- Codebase scout must be targeted, not a blind full-repo crawl. Identify relevant files/modules, current patterns, existing tests, contracts, and likely blast radius.
+- External/current research must prefer official docs, standards, primary sources, or maintained upstream references. Record source links and the date/context of the finding.
+- Write `research.md` before final requirements. It MUST include an Evidence Summary with: codebase scout result, external research result or skip rationale, selected decision, rejected alternatives, remaining gaps, and downstream task/test implications.
+- If evidence exposes unresolved architecture choices, unclear acceptance criteria, or multiple viable approaches with no obvious winner, stop and route to `/hapo:brainstorm` instead of forcing a spec.
 - Write requirements in **EARS** format (see `rules/ears-format.md`)
 - **Feasibility Check:** Cross-check each requirement against known technical constraints from `research.md`.
 - Each requirement gets a unique numeric ID
@@ -217,6 +226,7 @@ Load: `references/scope-inquiry.md`
   - **full**: integration, security, schema, or performance
 - Record findings in `research.md` before finalizing design
 - Write `design.md` from template `templates/design.md` (see `rules/design-principles.md`)
+- Design decisions MUST trace back to `research.md` evidence. If a design choice lacks evidence and is not a user-approved constraint, gather more evidence or ask the user before finalizing.
 - Add diagrams only when design has multi-step or cross-boundary flows
 - For auth/session, transport/entrypoint, persistence/schema, generated-artifact, or runtime-sensitive work, the design MUST fill the `Canonical Contracts & Invariants` section and tasks MUST inherit the same decisions verbatim.
 - Update `spec.json` phase, timestamps, discovery mode
@@ -227,6 +237,7 @@ Load: `references/scope-inquiry.md`
 - Load `rules/tasks-generation.md` for core principles
 - 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.
 - Each task file MUST include `Completion Criteria` and `Task Test Plan & Verification Evidence` sections detailed enough that a downstream quality gate can prove the task is truly done.
 - Build `spec.json.task_registry` alongside `task_files`. For each task file, register at minimum:
   - `id`
@@ -319,6 +330,7 @@ Load: `references/review.md` + `rules/design-review.md`
 - FAIL if any path in `task_files` does not exist on disk
 - FAIL if any task file exists on disk but is missing from `task_registry`
 - FAIL if any path in `task_registry` does not exist on disk
+- FAIL if a newly generated non-trivial spec lacks a `research.md` Evidence Summary with codebase scout result, external research result or skip rationale, selected decision, rejected alternatives, and downstream task/test implications.
 - FAIL if any requirement or NFR mapping uses non-numeric labels (`NFR-1`, `SEC-1`, etc.)
 - FAIL if a task lacks `Completion Criteria` or `Task Test Plan & Verification Evidence` (legacy `Verification & Evidence` is accepted only for pre-existing task files)
 - FAIL if accepted validation decisions exist in reports but are not reflected in the implementation-facing sections of affected artifacts (`Objective`, `Constraints`, `Implementation Steps`, `Completion Criteria`, `Task Test Plan & Verification Evidence`, canonical contracts, or requirements text).
@@ -449,6 +461,7 @@ specs/
 ### Pre-Finalization Checklist
 Before finalizing any specification, assert all the following:
 - [ ] **scope_lock** initialized and respected throughout all phases
+- [ ] **Evidence Summary** exists in `research.md` with codebase scout, external research or skip rationale, selected decision, rejected alternatives, and task/test implications
 - [ ] **EARS format** applied to all acceptance criteria in requirements.md
 - [ ] **Numeric requirement IDs** assigned to every requirement
 - [ ] **Discovery mode** selected and recorded in spec.json.design_context

package/src/claude/skills/specs/references/codebase-analysis.md

@@ -2,11 +2,26 @@
 
 ## Purpose
 
-Understand the current codebase before designing solutions — ensure the new spec aligns with existing architecture, patterns, and conventions.
+Understand the current codebase before designing solutions — ensure the new spec aligns with existing architecture, patterns, contracts, tests, and runtime boundaries.
 
 ## Skip Conditions
 
 - Already provided with inspector reports → skip, use directly
+- Greenfield artifact that does not integrate with existing code → record skip rationale in `research.md`
+- Internal docs/text-only spec with no runtime behavior → record skip rationale in `research.md`
+
+## Targeted Codebase Scout Gate
+
+Run a targeted scout before requirements when any of these are true:
+
+- The feature modifies existing behavior, UI, API, CLI, data flow, runtime config, hooks, settings, generated artifacts, or package exports.
+- The feature touches database schemas, migrations, auth/session, permissions, external integrations, or shared contracts.
+- The task may break existing tests, snapshots, build scripts, type checks, e2e flows, or docs generation.
+- The spec crosses monorepo boundaries such as source package → installed `.claude/`, library package → docs app, package manifest → publish/install runtime.
+- `Related Files` cannot be named precisely yet.
+- A resumed or validated spec may be stale because files, tests, dependencies, or contracts changed since the spec was created.
+
+The scout must be narrow and question-driven. Do not scan the whole repo just because the repo is available.
 
 ## 4 Mandatory Files to Read First
 
@@ -24,6 +39,19 @@ Understand the current codebase before designing solutions — ensure the new sp
    - **HALT** the spec process immediately.
    - Ask the User: *"No codebase documentation found. Exploring blind will drain tokens and produce inaccurate specs. Shall I trigger `docs-keeper` or `/hapo:docs` to generate a baseline `codebase-summary.md` first?"*
 
+## Scout Output Contract
+
+Record the concise findings in `research.md`; if inspector agents are used, save detailed output to `reports/inspect-report.md`.
+
+Required output:
+- **Project surface:** project type, package/workspace boundaries, languages, frameworks, and relevant commands.
+- **Relevant files/modules:** exact paths likely to be created, modified, deleted, or read.
+- **Existing patterns:** naming, architecture, state/data flow, error handling, testing, and docs conventions that tasks must follow.
+- **Contracts:** API/CLI/schema/auth/config/runtime/package/export contracts affected by the spec.
+- **Tests and verification:** existing tests/checks likely to pass, fail, or require updates.
+- **Blast radius:** affected modules, consumers, generated artifacts, publish/install paths, and rollback considerations.
+- **Staleness check:** docs or prior specs that conflict with source code or manifests.
+
 ## Analysis Activities
 
 ### 1. Environment Analysis
@@ -38,7 +66,7 @@ Before designing any logic, you must identify and read the existing schemas:
 - Identify Global State setups (Redux stores, Zustand, React Context).
 - Output the relational impact: How will the new feature alter existing tables or state structures?
 
-### 2. Pattern Recognition
+### 3. Pattern Recognition
 - Study existing patterns in codebase
 - Identify conventions and architectural decisions
 - Note consistency in implementation approaches
@@ -61,6 +89,7 @@ Write a "Collateral Damage" section in your `research.md`:
 - Each inspector targets a specific aspect of the task
 - Wait for all inspectors to report before analysis
 - Save results to `reports/inspect-report.md`
+- If the scout cannot name exact paths/tests after inspection, stop and ask a grounded question instead of generating vague tasks
 
 ## Best Practices
 
@@ -69,3 +98,5 @@ Write a "Collateral Damage" section in your `research.md`:
 - Document patterns found for consistency
 - Note any inconsistencies or technical debt
 - Consider impact on existing features
+- Use `rg`/targeted search terms or inspector agents before broad traversal
+- Pass exact file and test findings downstream into `design.md` and task `Related Files`

package/src/claude/skills/specs/references/research-strategy.md

@@ -2,12 +2,34 @@
 
 ## Purpose
 
-Provide tools and methods to gather necessary information before writing requirements and design. Prioritize breadth before depth.
+Provide tools and methods to gather necessary information before writing requirements and design. The goal is evidence-backed decision-making: use the current codebase and current external knowledge before locking requirements, architecture, and tasks.
 
 ## Skip Conditions
 
-- Simple task, small scope → no research needed
-- User already provided research reports → skip, use directly
+- Simple one-file task with no integration point → record skip rationale in `research.md`
+- Internal text/docs-only change → record skip rationale in `research.md`
+- User already provided recent research reports → use directly, but record what was reused
+
+Skipping research does NOT mean skipping the evidence trail. Every non-trivial spec still needs an Evidence Summary in `research.md`.
+
+## Evidence Gate Triggers
+
+### Targeted Codebase Scout — Mandatory When
+
+- The spec changes existing behavior rather than creating an isolated new artifact.
+- The spec touches API routes, CLI commands, package exports, database schemas, migrations, auth/session, permissions, runtime config, hooks, generated artifacts, or settings.
+- Requirements or tasks cannot name exact affected files, modules, tests, or contracts.
+- The change may invalidate existing `.test.*`, `.spec.*`, e2e, build, or integration checks.
+- The spec is being resumed or validated after the codebase may have changed.
+- The work crosses monorepo, package source, installed runtime, docs site, or publish/install boundaries.
+
+### External / Current Research — Mandatory When
+
+- The spec depends on third-party APIs, libraries, SDKs, browser/platform policies, package manager behavior, cloud services, or external protocols.
+- The spec touches security, auth, payment, privacy, delete-data, compliance, performance, accessibility, SEO, or current framework best practices.
+- The spec involves AI providers, model behavior, agent tooling, browser automation, or fast-moving platform constraints.
+- The user asks for "best", "optimal", "latest", "recommended", "current", "modern", or equivalent.
+- Existing internal docs are stale, incomplete, or contradict package manifests/source code.
 
 ## 7 Research Tools
 
@@ -23,27 +45,50 @@ Provide tools and methods to gather necessary information before writing require
 
 ## Workflow
 
-### 1. Identify What Needs Research
+### 1. Classify Evidence Needs
 Before detailing requirements, list unanswered questions:
 - Which technology is most suitable?
 - Is there an existing pattern/library that solves this?
 - How does the current codebase handle similar functionality?
 - Are there technical risks that need verification?
+- What evidence is needed from the repository?
+- What evidence requires current external sources?
+
+### 2. Run Targeted Codebase Scout
+- Read project docs first, then verify claims against source files such as `package.json`, `go.mod`, schemas, routes, tests, and runtime config.
+- Use inspector agents for large codebases or when multiple focused searches are needed.
+- Save scout details to `reports/inspect-report.md` when inspector agents are used.
+- Record the useful summary in `research.md`; do not dump raw search output.
 
-### 2. Pick the Right Tool
+### 3. Run External / Current Research
+- Prefer official documentation, standards, release notes, package repositories, or maintained upstream examples.
+- Use broader web search only when primary sources do not answer the question.
+- Record links and explain why each source matters.
+- If sources conflict, state which source wins and why.
+
+### 4. Pick the Right Tool
 - Framework/API questions → Docs seeker
 - Current codebase questions → Inspector agents
 - Architecture/approach questions → Researcher agents
 - Complex multi-step reasoning → Sequential thinking
 - Historical decision questions → GitHub analysis
 
-### 3. Spawn Researchers (when needed)
+### 5. Spawn Researchers (when needed)
 - Max 2 agents running in parallel
 - Each agent gets a specific aspect (e.g., agent 1 researches auth approach, agent 2 researches database schema)
 - Limit each agent to max 5 tool calls
 - Wait for all agents to complete before synthesizing
 
-### 4. Record Findings
+### 6. Synthesize Decisions
+- Convert raw findings into decisions before writing requirements:
+  - selected approach
+  - rejected alternatives
+  - codebase fit
+  - external/current constraints
+  - downstream task and test implications
+- If evidence leaves multiple viable choices with no obvious winner, route to `/hapo:brainstorm` or ask the user for a decision.
+
+### 7. Record Findings
 - Write to `research.md` using template `templates/research.md`
 - Save researcher reports to `reports/researcher-{NN}.md`
 - Save inspector reports to `reports/inspect-report.md`
@@ -55,3 +100,5 @@ Before detailing requirements, list unanswered questions:
 - Identify multiple approaches for comparison
 - Consider edge cases during research
 - Flag security concerns early
+- Do not design from memory when repository or current external evidence can settle the decision
+- Keep external research concise: source, finding, implication, decision

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

@@ -17,6 +17,52 @@
   - Finding 2
   - Finding 3
 
+## 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:
+
+## Codebase Scout
+Capture only useful repo evidence, not raw file dumps.
+
+| Area | Finding | Evidence / Path | Implication |
+|------|---------|-----------------|-------------|
+| Project surface | | | |
+| Relevant files/modules | | | |
+| Existing patterns | | | |
+| Contracts | | | |
+| Tests and verification | | | |
+| Blast radius | | | |
+| Staleness / conflicts | | | |
+
+## External / Current Research
+Use official docs, standards, package repos, release notes, or maintained upstream references first.
+
+| Question | Source | Finding | Decision Impact |
+|----------|--------|---------|-----------------|
+| | | | |
+
 ## Research Log
 Document notable investigation steps and their outcomes. Group entries by topic for readability.