@haposoft/cafekit 0.7.29 → 0.8.1

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
@@ -85,9 +86,11 @@ Display selection menu via `AskUserQuestion`:
 ### When called WITH a feature description
 
 System auto-analyzes the description:
-- If description is too short (< 20 words) or vague → stop and ask 1-2 clarifying questions
+- If description is too short (< 20 words) or missing one concrete detail → stop and ask 1-2 clarifying questions
+- 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
 
@@ -111,7 +114,9 @@ flowchart TD
     A["Call /hapo:specs"] --> B{Has description?}
     B -->|No| C["Menu: init / status / resume / --validate / archive"]
     B -->|Yes| D["Step 1: Analyze description"]
-    D --> E{Clear enough?}
+    D --> DB{"Needs pre-spec brainstorm?"}
+    DB -->|Yes| DB2["Stop: run /hapo:brainstorm with same idea"]
+    DB -->|No| E{Clear enough?}
     E -->|No| F["Ask user 1-2 clarifying questions"]
     F --> D
     E -->|Yes| G["Step 2: Scan specs/ for related specs"]
@@ -125,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"]
@@ -148,6 +153,12 @@ flowchart TD
 
 ### Step 1: Analyze Description
 - Assess clarity and complexity of the description
+- Route to `hapo:brainstorm` before creating files when:
+  - the expected output or acceptance criteria are not concrete
+  - the scope boundary is unknown
+  - the request has 2-3 viable architectures and no user-approved direction
+  - the feature spans 3+ independent subsystems and needs decomposition
+  - the user is explicitly asking to explore, compare, debate, or decide
 - **Multimodal & Document Auto-Ingestion (MANDATORY)**: If the input includes file paths or URLs pointing to images, audio, video, or Office documents, you MUST spawn the matching subagent to extract content BEFORE proceeding:
   - `.mp3`, `.wav`, `.mp4`, `.mov`, `.jpg`, `.png`, `.webp` → `Task(subagent_type="hapo:ai-multimodal", prompt="Transcribe/Analyze [path]")`
   - `.pdf` → `Task(subagent_type="hapo:pdf", prompt="Extract text and tables from [path]")`
@@ -185,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
@@ -208,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
@@ -218,7 +237,8 @@ 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`
-- Each task file MUST include `Completion Criteria` and `Verification & Evidence` sections detailed enough that a downstream quality gate can prove the task is truly done.
+- `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`
   - `title`
@@ -310,9 +330,10 @@ 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 `Verification & Evidence`
-- 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`, `Verification & Evidence`, canonical contracts, or requirements text).
+- 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).
 - FAIL if the spec scope/provider was switched away from Anthropic/Claude but `requirements.md`, `design.md`, or `tasks/*.md` still contain stale provider-specific strings such as `Claude API`, `Haiku`, or `haiku_reachable`. `research.md` is the only allowed place for historical cost comparisons.
 - FAIL if privacy/delete-data work lacks a single canonical deletion policy. The design MUST explicitly choose either:
   1. hard-delete with no re-registration lock, or
@@ -440,13 +461,14 @@ 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
 - [ ] **Requirements traceability** matrix present in design.md
 - [ ] **Canonical Contracts & Invariants** filled for auth/transport/persistence/artifact-sensitive work
 - [ ] **Every task file** maps to at least 1 valid in-scope requirement ID
-- [ ] **Every task file** includes `Verification & Evidence` with executable or inspectable proof
+- [ ] **Every task file** includes `Task Test Plan & Verification Evidence` with executable or inspectable proof
 - [ ] **State Machine Blueprint:** design.md contains Mermaid diagrams for non-trivial flows
 - [ ] **Dependency graph complete**: no task can start before its blockers are listed
 - [ ] **Risk matrix filled**: likelihood × impact, with mitigation for High items

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/references/review.md

@@ -42,7 +42,7 @@ These rules override any self-reasoning or optimization the system may attempt:
 4. **Apply YAGNI to fixes.** When user says "configure later" or "decide later", add a single note to the task file. Do NOT generate multiple concrete implementations (e.g., 4 provider files when user only asked for abstraction).
 5. **No false completion.** You MUST NOT set `validation.status = "completed"` or `ready_for_implementation = true` until a reconciliation audit proves the accepted findings and validation decisions are reflected in the physical spec artifacts.
 6. **Provider drift is a real defect.** If the scope changed away from Claude/Anthropic, stale strings like `Claude API`, `Haiku`, or `haiku_reachable` in `requirements.md`, `design.md`, or `tasks/*.md` are validation failures. `research.md` may mention them only as historical comparison.
-7. **Implementation-facing propagation is mandatory.** A decision that affects implementation is NOT considered applied if it only appears in `Risk Assessment`, `validate-log.md`, or `red-team-report.md`. It must update at least one of: `requirements.md`, `Canonical Contracts & Invariants`, `Objective`, `Constraints`, `Implementation Steps`, `Completion Criteria`, or `Verification & Evidence`.
+7. **Implementation-facing propagation is mandatory.** A decision that affects implementation is NOT considered applied if it only appears in `Risk Assessment`, `validate-log.md`, or `red-team-report.md`. It must update at least one of: `requirements.md`, `Canonical Contracts & Invariants`, `Objective`, `Constraints`, `Implementation Steps`, `Completion Criteria`, or `Task Test Plan & Verification Evidence`.
 
 ---
 

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

@@ -136,11 +136,11 @@ Every task file MUST contain the Risk Assessment table, even if no risks are ide
 - Never mark implementation work or integration-critical verification as optional—reserve `*` for auxiliary/deferrable test coverage that can be revisited post-MVP.
 - Never mark auth, permissions, privacy, data deletion, migration, schema, or contract verification work as optional.
 
-### Mandatory Verification & Evidence
+### Mandatory Task Test Plan & Verification Evidence
 
-Every task file MUST include a `## Verification & Evidence` section.
+Every new task file MUST include a `## Task Test Plan & Verification Evidence` section. Existing specs may still use the legacy `## Verification & Evidence` heading; readers and sync tools must support both.
 
-That section MUST contain:
+That section is the task-level test plan and MUST contain:
 1. **Automated proof** — exact command(s) for typecheck, tests, build, or explicit `N/A`
 2. **Artifact/runtime proof** — exact files, routes, UI surfaces, generated outputs, or persisted state to inspect
 3. **Contract/negative-path proof** — at least one contract-preserving check for unauthorized, invalid, missing-permission, rollback, or failure-path behavior when relevant

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.
 

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

@@ -58,7 +58,9 @@
 - [ ] {{Criteria 2 — measurable behavior or negative-path outcome}}
 - [ ] {{Criteria 3 — maps directly to acceptance criteria from requirements.md and can be proven below}}
 
-## Verification & Evidence
+## Task Test Plan & Verification Evidence
+
+This section is the task-level test plan. It names the exact commands, observable runtime/artifact proof, and negative-path checks required before this task can be marked done.
 
 - [ ] Automated verification
   - Command(s): `{{TYPECHECK / TEST / BUILD COMMANDS OR N/A}}`
@@ -82,4 +84,4 @@
 > **Parallel marker**: Append `(P)` to the title if this task can run concurrently with another (usually when serving different requirements).
 > **Test note**: If a test coverage sub-task can be deferred post-MVP, mark it with `- [ ]*`.
 > **Requirement mapping**: Every sub-task MUST end with `_Requirements: X.X_`. No mapping = invalid task file.
-> **Verification rule**: No `## Verification & Evidence` section = invalid task file.
+> **Verification rule**: No `## Task Test Plan & Verification Evidence` section = invalid task file. Existing specs may use legacy `## Verification & Evidence`; agents must support both headings.

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

@@ -34,8 +34,8 @@ Scans the `spec.json` against all physical `task-R*.md` files to detect mismatch
 
 1. **Precision Edits:** Never overwrite the entire `spec.json` string blindly. Update only the required keys, while keeping JSON valid.
 2. **Machine + Human Sync:** Every task status update MUST modify both `spec.json.task_registry[...]` and the matching markdown task file header/status section.
-3. **Markdown Integrity:** When marking a task `done`, only then turn `[ ]` into `[x]` inside `## Implementation Steps` and relevant `Completion Criteria` / `Verification & Evidence` checkboxes that have actual proof.
-4. **Verification Receipt Rule:** `done` is illegal without a human-readable verification receipt already present in `## Verification & Evidence` (commands executed, artifact/runtime proof, or equivalent concrete evidence). If proof is missing, keep the task `in_progress` or `blocked`.
+3. **Markdown Integrity:** When marking a task `done`, only then turn `[ ]` into `[x]` inside `## Implementation Steps` and relevant `Completion Criteria` / `Task Test Plan & Verification Evidence` checkboxes that have actual proof. Legacy `Verification & Evidence` sections are supported.
+4. **Verification Receipt Rule:** `done` is illegal without a human-readable verification receipt already present in `## Task Test Plan & Verification Evidence` or legacy `## Verification & Evidence` (commands executed, artifact/runtime proof, or equivalent concrete evidence). If proof is missing, keep the task `in_progress` or `blocked`.
 5. **Task Docs Hook:** Every time `hapo:sync` marks a task as `done`, it must flag that a task-level docs checkpoint is now due for that verified task.
 6. **Phase Prompt Rule:** When `hapo:sync` marks the final pending task in the whole feature as `done`, it should automatically prompt the user if they'd like to advance the phase, but only after the docs checkpoint for that last completed task has been considered.
 

package/src/claude/skills/sync/references/sync-protocols.md

@@ -15,7 +15,7 @@ When requested to update a phase or change task configuration, `spec.json` must
     - full relative path like `tasks/task-R0-02-extension-shell.md`
 *   **Status Update:** If a task changes to `blocked`, the matching `task_registry[path].status` must become `"blocked"`, `task_registry[path].blocker` must record the reason, and `spec.json.status` / `spec.json.blocker` must reflect the top-level block if work is globally blocked.
 *   **Timestamp Rule:** Update `task_registry[path].started_at`, `completed_at`, and `last_updated_at` consistently with the new state. Also refresh `spec.json.updated_at`.
-*   **Done-State Rule:** Never set `task_registry[path].status = "done"` unless the matching markdown task file already contains a verification receipt in `## Verification & Evidence`, or the caller explicitly provides proof that can be written there first.
+*   **Done-State Rule:** Never set `task_registry[path].status = "done"` unless the matching markdown task file already contains a verification receipt in `## Task Test Plan & Verification Evidence` or legacy `## Verification & Evidence`, or the caller explicitly provides proof that can be written there first.
 *   **Receipt Integrity Rule:** A valid verification receipt must include the exact commands run, their outcomes, and artifact/runtime proof. Receipts containing `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit "placeholder / simplified for MVP / production later" contract deviations are not eligible for `done`.
 *   **Contract Fidelity Rule:** If the task file notes or evidence show that a named framework/auth/runtime choice from the spec was silently replaced, sync MUST refuse `done` until the spec is amended or the implementation is corrected.
 *   **Task Docs Rule:** After a task is moved to `done`, emit a short alert that a task-level docs checkpoint is due for this verified task.
@@ -27,12 +27,12 @@ The structure of `tasks/task.md` relies heavily on exact keyword markers. Follow
 ### A. Completing a Task
 When `/hapo:sync <feature> <task-id> done`:
 1. Find: `**Status:** pending` (or `in_progress` / `blocked`).
-2. Inspect `## Verification & Evidence` first. If it has no explicit proof lines (commands run, artifact proof, runtime proof, or blockers cleared), STOP and refuse to mark the task done.
+2. Inspect `## Task Test Plan & Verification Evidence` first. If the task uses legacy `## Verification & Evidence`, inspect that section instead. If it has no explicit proof lines (commands run, artifact proof, runtime proof, or blockers cleared), STOP and refuse to mark the task done.
 3. Refuse completion if the receipt contains any non-passing marker such as `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation substituted a named contract with a placeholder/custom simplification.
 4. Replace with: `**Status:** done`.
 5. Locate block: `## Implementation Steps`.
 6. Convert `- [ ]` into `- [x]` strictly within that section.
-7. Update relevant checkboxes in `## Completion Criteria` and `## Verification & Evidence` only when the caller provides or the file already contains real proof.
+7. Update relevant checkboxes in `## Completion Criteria` and `## Task Test Plan & Verification Evidence` only when the caller provides or the file already contains real proof. For legacy task files, update `## Verification & Evidence` instead.
 8. Surface a note such as: `Docs checkpoint due: task Rn-mm just completed`.
 
 ### B. Blocking a Task
@@ -59,7 +59,7 @@ When `/hapo:sync audit <feature>` is activated:
    - Missing disk file referenced in registry → remove or flag it
    - Markdown says `done` but registry not done → registry wins only if evidence already exists; otherwise downgrade markdown or flag conflict
    - Registry says `done` but markdown still pending → update markdown only if evidence exists
-   - Either side says `done` but `## Verification & Evidence` has no concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
+   - Either side says `done` but `## Task Test Plan & Verification Evidence` / legacy `## Verification & Evidence` has no concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
    - Either side says `done` but the receipt contains `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit contract-substitution notes → downgrade to `in_progress` or flag conflict
 5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.
 6. **Task Docs Alert:** If audit reveals tasks newly marked `done`, include whether task-level docs sync appears still due or already accounted for in the current run summary.

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

@@ -27,6 +27,7 @@ Designed to work **after `hapo:develop`**. Standalone `/hapo:test` uses the same
 NEVER claim tests pass when they were NOT actually executed.
 NEVER mock, stub, or skip a failing test to produce a green result.
 If no test command is detected, report NO_TESTS — do not fabricate results.
+If a test command exits 0 but runs 0 tests, report NO_TESTS — this is a green lie, not a PASS.
 If tests fail, list every failure explicitly — do not summarize failures away.
 </HARD-GATE>
 
@@ -65,7 +66,8 @@ affected by recent file changes. See `references/execution-strategy.md` Phase A.
 **Code testing (default):**
 1. Pre-flight: run typecheck/lint to catch compile errors first
 2. Execute test command with coverage flags
-3. Collect results, coverage percentages, and fail stack traces
+3. Collect test counts, coverage percentages, and fail stack traces
+4. Treat 0 executed tests as `NO_TESTS`, even if the command exits 0
 
 **UI verification (`--ui` / `--ui-auth` / `--ui-flow`):**
 Execute multi-page discovery, then spawn **Parallel UI Subagents** (test-runner instances) to handle Smoke, Core-Vitals, Accessibility, SEO, Security, and User Flows simultaneously.
@@ -146,6 +148,7 @@ It merges the JSON data into `.hapo/test-memory.json` per `references/test-memor
 
 - `references/execution-strategy.md` — Blast-radius algorithm, auto-detect logic, UI verification phases (A–E)
 - `references/failure-triage.md` — Failure categories, triage decision tree, escalation rules
+- `references/test-memory.md` — `.hapo/test-memory.json` schema and merge rules
 
 ## Related
 

package/src/claude/skills/test/references/execution-strategy.md

@@ -84,6 +84,9 @@ cargo test
 flutter test --coverage
 ```
 
+After each command, parse the runner output for executed test count. A successful
+exit with 0 executed tests is `NO_TESTS`, not `PASS`.
+
 ### Coverage Thresholds
 
 | Metric    | Minimum | Focus Areas                        |
@@ -360,4 +363,3 @@ Flag as `Security Warning` if:
 - API keys, secrets, or JWT tokens visible in page HTML
 - Mixed content (HTTP resources on HTTPS page) detected via network audit
 - `autocomplete="off"` missing on password fields
-

package/src/claude/skills/test/references/test-memory.md

@@ -1,6 +1,6 @@
 # Test Memory
 
-The `packages/spec/src/claude/test-memory.json` file serves as the Long-Term Memory for the testing ecosystem. 
+The `.hapo/test-memory.json` file in the target project serves as the Long-Term Memory for the testing ecosystem.
 
 ## Schema
 
@@ -37,4 +37,4 @@ Example:
 </lessons_learned>
 ```
 
-The orchestrating `hapo:test` skill (Phase 4) then intercepts this block and automatically merges it into `packages/spec/src/claude/test-memory.json`.
+The orchestrating `hapo:test` skill (Phase 4) then intercepts this block and automatically merges it into `.hapo/test-memory.json`.