@haposoft/cafekit 0.7.22 → 0.7.24

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

@@ -19,7 +19,7 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Requirements
 
 **CRITICAL:** Before starting, the system MUST:
 1. Scan `specs/` directory for incomplete specs
-2. If any spec is `in-progress` → ask user whether to continue or create new
+2. If any spec is `in_progress` (accept legacy `in-progress` when reading) → ask user whether to continue or create new
 3. Detect cross-spec dependencies (see `references/cross-spec-dependency.md`)
 
 ## Core Responsibilities & Rules
@@ -40,6 +40,12 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Requirements
 - Never silently expand or shrink scope
 - If scope change needed → ask user, record reason in `spec.json`
 
+### State & Integrity Rules
+- Canonical active status string is `in_progress`. Legacy `in-progress` may be READ for compatibility but MUST NOT be generated in new specs.
+- `current_phase` is required for live work and must track the active phase (`init`, `requirements`, `design`, `tasks`, `develop`, `test`, `review`).
+- `task_files` in `spec.json` MUST exactly match the real files under `tasks/` after Step 7.
+- `ready_for_implementation` is a hard gate, not a convenience flag. Never set it before the finalization audit passes.
+
 ### Output Criteria
 - Never implement code — only create spec documents
 - Return file paths and a brief summary
@@ -66,7 +72,7 @@ Display selection menu via `AskUserQuestion`:
     "options": [
       { "label": "Create new spec", "description": "Initialize spec from a feature description" },
       { "label": "status", "description": "View status of all specs in specs/" },
-      { "label": "resume", "description": "Continue an in-progress spec" },
+      { "label": "resume", "description": "Continue an active spec" },
       { "label": "--validate", "description": "Review spec (auto-decides: red team or validation)" },
       { "label": "archive", "description": "Archive completed specs + write journal" }
     ],
@@ -120,7 +126,7 @@ flowchart TD
     K --> L
     L --> M["Step 5: Requirements — write EARS"]
     M --> N{Need deep research?}
-    N -->|Yes| O["Research: researchers + scout + docs"]
+    N -->|Yes| O["Research: researchers + inspector + docs"]
     O --> P["Write research.md"]
     N -->|No| P
     P --> Q["Step 6: Design — pick discovery mode"]
@@ -202,6 +208,7 @@ Load: `references/scope-inquiry.md`
 - Record findings in `research.md` before finalizing design
 - Write `design.md` from template `templates/design.md` (see `rules/design-principles.md`)
 - 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
 
 ### Step 7: Task Breakdown
@@ -210,6 +217,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`
+- 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.
 - Update `spec.json` phase + task metadata
 
 #### Requirement-Driven Task Grouping (MANDATORY)
@@ -240,6 +248,7 @@ tasks/
 - If a requirement has only 1 natural task, create 1 file (no forced splitting)
 - If a requirement has many acceptance criteria spanning different concerns → split into multiple task files
 - After generating all tasks: verify **every requirement ID** appears as primary in at least one task file — gaps = failure
+- **Legacy Protection:** If the `research.md` identified existing codebase files or tests that will be broken (Blast Radius), you MUST generate explicitly tasked files (e.g., `task-R5-01-update-legacy-tests.md`) to fix those breakages. Do not leave broken tests out of scope.
 
 **Dependency ordering:** Tasks within the same requirement are ordered by natural implementation flow. Cross-requirement dependencies use `Dependencies:` field referencing other task file names.
 
@@ -278,10 +287,20 @@ Load: `references/review.md` + `rules/design-review.md`
   - **< 3 task files, no security concerns** → Validate only (lightweight interview)
   - **>= 5 task files OR security/migration keywords** → Red Team first, then Validate
   - **User explicit request** → respect user's intent
+- Set `design_context.validation_recommended = true` if the spec includes any of: auth/session, privacy, deletion, migration, schema change, external AI/provider switching, browser extension permissions, or 5+ task files.
 - When both run: Red Team ALWAYS before Validate (red team may change the spec)
 - **PROHIBITION:** The system MUST NOT skip Red Team because of a prior code-auditor review. Code review ≠ Spec review.
 - **PROHIBITION:** The system MUST NOT create `.ts`, `.js`, `.py` or any implementation files during validation. Spec-only outputs.
 
+### Step 9.5: Finalization Audit (MANDATORY)
+- Re-scan the `tasks/` directory and rebuild `spec.json.task_files` from the real filesystem (sorted, relative paths)
+- FAIL if any task file exists on disk but is missing from `task_files`
+- FAIL if any path in `task_files` does not exist on disk
+- 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`
+- If `validation_recommended = true` and `validation.status` is not `completed` (or an explicit accepted-risk state recorded by the user), `ready_for_implementation` MUST remain `false`
+- Only after this audit passes may the system mark `progress.tasks = "done"` and `ready_for_implementation = true`
+
 ### Step 10: Completion — Context Reminder (MANDATORY)
 After completing the spec, output a short summary of what was generated, then you MUST output the following block EXACTLY as written. DO NOT use awkward translations like "Điểm đã phản ánh đúng quyết định của bạn", keep it professional or just output the block directly:
 
@@ -299,7 +318,7 @@ When user calls `hapo:specs`, system checks `specs/`:
 
 | Situation | Action |
 |---|---|
-| A spec is `in-progress` | Ask: "You have spec `<name>` at phase `<phase>`. Continue? [Y/n]" |
+| A spec is `in_progress` | Ask: "You have spec `<name>` at phase `<phase>`. Continue? [Y/n]" |
 | A spec matches current git branch | Ask: "Branch `feature/X` has spec `X`. Activate or create new?" |
 | Nothing found | Create new spec or show menu |
 
@@ -317,17 +336,25 @@ When user calls `hapo:specs`, system checks `specs/`:
 
 ### spec.json Update Rules (MANDATORY)
 
+**Canonical status vocabulary:** Use `in_progress`, `blocked`, `done`, and `archived`. New specs MUST NOT emit `in-progress`.
+
 **Timestamps:** Each `timestamps.*_done` field MUST use the **actual current time** (ISO 8601 with timezone) when that specific phase completes. Do NOT reuse the `init` timestamp for later phases. If running the full pipeline end-to-end, capture a fresh timestamp at each phase transition.
 
 **Approvals (auto-approval behavior):**
 - When running the **full pipeline end-to-end** (init → tasks in one session): set `approvals.{phase}.generated = true` AND `approvals.{phase}.approved = true` for each completed phase before proceeding to the next.
 - When running a **single phase**: set `generated = true` but leave `approved = false` — user must explicitly approve before continuing.
 
+**Task inventory:** `task_files` MUST be present and MUST list every real task file exactly once using relative paths like `tasks/task-R1-01-example.md`.
+
+**Validation recommendation:** `design_context.validation_recommended` MUST be `true` for auth, privacy, delete-data, migration, schema-change, browser-extension-permission, external-provider, or 5+ task file specs.
+
 **`ready_for_implementation`:** This field MUST only be set to `true` when ALL of the following conditions are met:
 1. `approvals.requirements.approved = true`
 2. `approvals.design.approved = true`
 3. `approvals.tasks.approved = true`
 4. `progress.tasks = "done"`
+5. `task_files` matches the real filesystem
+6. If `design_context.validation_recommended = true`, `validation.status = "completed"` (or another explicit user-accepted risk state that is recorded)
 
 If any approval is `false`, `ready_for_implementation` MUST remain `false`.
 
@@ -349,7 +376,7 @@ specs/
     │   └── ...
     └── reports/               # Auxiliary reports
         ├── researcher-01.md
-        ├── scout-report.md
+        ├── inspect-report.md
         └── red-team-report.md
 ```
 
@@ -358,7 +385,7 @@ specs/
 | Command | Purpose | Reference |
 |---|---|---|
 | `/hapo:specs status` | View status of all specs | — |
-| `/hapo:specs resume <feature>` | Continue an in-progress spec | — |
+| `/hapo:specs resume <feature>` | Continue an active spec | — |
 | `/hapo:specs --validate <feature>` | Validate spec (auto: red team + validate based on complexity) | `references/review.md` |
 | `/hapo:specs archive` | Archive completed specs + write journal | `references/archive-workflow.md` |
 
@@ -392,12 +419,16 @@ Before finalizing any specification, assert all the following:
 - [ ] **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
 - [ ] **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
 - [ ] **Test strategy defined**: what gets unit tested, integration tested, e2e validated
-- [ ] **spec.json fully updated**: phase, progress, timestamps, approvals, design_context
+- [ ] **task_files inventory synced**: no missing or orphaned task references
+- [ ] **Validation gate consistent**: validation_recommended and validation.status agree with spec risk
+- [ ] **spec.json fully updated**: phase, current_phase, progress, timestamps, approvals, design_context
 
 ## When TO Use
 

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

@@ -6,7 +6,7 @@ Understand the current codebase before designing solutions — ensure the new sp
 
 ## Skip Conditions
 
-- Already provided with scout reports → skip, use directly
+- Already provided with inspector reports → skip, use directly
 
 ## 4 Mandatory Files to Read First
 
@@ -17,7 +17,12 @@ Understand the current codebase before designing solutions — ensure the new sp
 | 3 | `./docs/code-standards.md` | Coding conventions, language-specific patterns | High |
 | 4 | `./docs/design-guidelines.md` | Design system, branding, UI/UX conventions | If exists |
 
-> If a file doesn't exist → skip it silently. If all are missing → use scout to explore the codebase directly.
+### Validation & Fallback Protocol (MANDATORY)
+1. **Trust but Verify:** If `codebase-summary.md` or `code-standards.md` exists, you MUST verify their technical claims by cross-checking `package.json`, `go.mod`, etc. (e.g., if Docs say Redux but package.json only has Zustand → Flag documentation as STALE in your research).
+2. **The "Blind Flight" Halt:** If ALL 4 mandatory docs are missing in a non-empty repository:
+   - **DO NOT** blindly use `inspector` to scan the whole repo.
+   - **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?"*
 
 ## Analysis Activities
 
@@ -27,28 +32,40 @@ Understand the current codebase before designing solutions — ensure the new sp
 - Identify required dependencies
 - Understand build and deployment processes
 
+### 2. Core Data Structures (MANDATORY for Enhancements)
+Before designing any logic, you must identify and read the existing schemas:
+- Tell `inspector` to grep for database schema files (`schema.ts`, `schema.prisma`, entities, migrations).
+- 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
 - Study existing patterns in codebase
 - Identify conventions and architectural decisions
 - Note consistency in implementation approaches
 - Understand error handling patterns
 
-### 3. Integration Planning
+### 4. Integration Planning
 - Identify how new features integrate with existing architecture
 - Map dependencies between components
 - Understand data flow and state management
 - Consider backward compatibility
 
-### 4. Scout Usage (when needed)
-- Use scout agents for targeted file discovery in large codebases
-- Each scout targets a specific aspect of the task
-- Wait for all scouts to report before analysis
-- Save results to `reports/scout-report.md`
+### 5. Blast Radius & Regression Check
+Write a "Collateral Damage" section in your `research.md`:
+- List EXACTLY which existing files will need to be modified.
+- **Test Invalidation:** Identify which existing `.test.ts` or `.spec.ts` files will break because of these modifications.
+- Ensure the mitigation for these breaking changes is passed downstream to the Task generation phase.
+
+### 6. Inspector Usage (when needed)
+- Use inspector agents for targeted file discovery in large codebases
+- Each inspector targets a specific aspect of the task
+- Wait for all inspectors to report before analysis
+- Save results to `reports/inspect-report.md`
 
 ## Best Practices
 
 - Start with documentation before diving into code
-- Use scouts for targeted file discovery
+- Use inspectors for targeted file discovery
 - Document patterns found for consistency
 - Note any inconsistencies or technical debt
 - Consider impact on existing features

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

@@ -18,7 +18,7 @@ Provide tools and methods to gather necessary information before writing require
 | 3 | **Docs seeker** | Look up framework/package docs from official sources | Need to understand external APIs/libraries, find best practices |
 | 4 | **GitHub analysis** (`gh`) | Read action logs, PRs, issues, discussions | Need context from project history, understand past decisions |
 | 5 | **Repomix remote** (`repomix --remote <url>`) | Generate codebase summary from remote repo | Reference how other repos solve similar problems. *(If not installed, use WebFetch as fallback)* |
-| 6 | **Scout agents** | Search for files across large codebases | Find relevant files faster than grep in large projects |
+| 6 | **Inspector agents** | Search for files across large codebases | Find relevant files faster than grep in large projects |
 | 7 | **Debugger delegation** | Hand off to debugger agent for analysis | Investigate root cause of bugs |
 
 ## Workflow
@@ -32,7 +32,7 @@ Before detailing requirements, list unanswered questions:
 
 ### 2. Pick the Right Tool
 - Framework/API questions → Docs seeker
-- Current codebase questions → Scout agents
+- Current codebase questions → Inspector agents
 - Architecture/approach questions → Researcher agents
 - Complex multi-step reasoning → Sequential thinking
 - Historical decision questions → GitHub analysis
@@ -46,7 +46,7 @@ Before detailing requirements, list unanswered questions:
 ### 4. Record Findings
 - Write to `research.md` using template `templates/research.md`
 - Save researcher reports to `reports/researcher-{NN}.md`
-- Save scout reports to `reports/scout-report.md`
+- Save inspector reports to `reports/inspect-report.md`
 
 ## Best Practices
 

package/src/claude/skills/specs/references/review.md

@@ -7,7 +7,7 @@ Review a spec before implementation. The system auto-decides the review depth ba
 ## Spec Resolution
 
 1. If `<feature>` argument provided → use `specs/<feature>/`
-2. If not → check active spec (spec with `in-progress` status)
+2. If not → check active spec (spec with `in_progress` status; accept legacy `in-progress` when reading existing files)
 3. If nothing found → ask user to specify path
 
 ## Auto-Decision: When to Red Team vs Validate

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

@@ -32,6 +32,7 @@ Detail bullets must include:
 - Validate core functionality early in sequence
 - Respect architecture boundaries defined in design.md (Architecture Pattern & Boundary Map)
 - Honor interface contracts documented in design.md
+- Translate completion criteria into concrete proof (commands, artifacts, routes, manifests, schema objects, UI states)
 - Use major task summaries sparingly—omit detail bullets if the work is fully captured by child tasks.
 
 **End with integration tasks** to wire everything together.
@@ -131,6 +132,22 @@ Every task file MUST contain the Risk Assessment table, even if no risks are ide
 - When the design already guarantees functional coverage and rapid MVP delivery is prioritized, mark purely test-oriented follow-up work (e.g., baseline rendering/unit tests) as **optional** using the `- [ ]*` checkbox form.
 - Only apply the optional marker when the sub-task directly references acceptance criteria from requirements.md in its detail bullets.
 - 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
+
+Every task file MUST include a `## Verification & Evidence` section.
+
+That section 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
+
+Rules:
+- If the task produces a build artifact or generated file, name the exact artifact path to inspect.
+- If the task wires entrypoints (popup, content script, route, worker, CLI command), name the exact runtime surface that must exist after implementation.
+- If verification depends on environment or manual setup, document the blocker explicitly instead of implying success.
+- Build success alone is NEVER enough evidence for a completed task.
 
 ## Task Hierarchy Rules
 

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

@@ -65,6 +65,19 @@ When modifying existing systems:
 
 > Keep rationale concise here and, when more depth is required (trade-offs, benchmarks), add a short summary plus pointer to the Supporting References section and `research.md` for raw investigation notes.
 
+## Canonical Contracts & Invariants
+
+Capture only the contracts whose inconsistency would break downstream implementation or verification. If the feature touches auth/session, transport/entrypoints, persistence/schema, generated artifacts, or runtime outputs, this section is mandatory.
+
+| Contract Area | Canonical Decision | Applies To | Must Stay Consistent In |
+|---------------|--------------------|------------|-------------------------|
+| Auth / session | | | |
+| Transport / entrypoints | | | |
+| Data / persistence | | | |
+| Generated artifacts / runtime outputs | | | |
+
+> Task files must reuse the same contract wording. If implementation later needs a different contract, update this section first before generating or editing tasks.
+
 ## System Flows
 
 Provide only the diagrams needed to explain non-trivial flows. Use pure Mermaid syntax. Common patterns:

package/src/claude/skills/specs/templates/init.json

@@ -3,8 +3,9 @@
   "created_at": "{{TIMESTAMP}}",
   "updated_at": "{{TIMESTAMP}}",
   "language": "vi",
-  "status": "pending",
+  "status": "in_progress",
   "phase": "initialized",
+  "current_phase": "init",
   "priority": "P2",
   "effort": null,
   "tags": [],
@@ -32,6 +33,8 @@
     "blockedBy": [],
     "blocks": []
   },
+  "task_files": [],
+  "blocker": null,
   "progress": {
     "init": "done",
     "requirements": "pending",

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

@@ -25,14 +25,27 @@
 
 <!-- Additional requirements follow the same pattern -->
 
-## Non-Functional Requirements (NFRs)
+## Non-Functional Requirements
 
-### Performance & Scalability
-- The [system] shall [measurable performance metric, e.g. "respond within 500ms"]
-- The [system] shall [measurable scale metric, e.g. "support 100 concurrent users"]
+<!-- Continue the SAME numeric sequence as functional requirements. Do NOT switch to labels like NFR-1, SEC-1, PERF-1. -->
 
-### Security & Privacy
-- The [system] shall [measurable security behavior, e.g. "encrypt data at rest using AES-256"]
+### Requirement {{NEXT_REQ_NUMBER}}: Performance & Scalability
+**Objective:** As a system owner, I want predictable performance characteristics, so that the feature remains usable under expected load.
 
-### Reliability & Availability
-- If [failure condition], the [system] shall [recovery behavior]
+#### Acceptance Criteria
+{{NEXT_REQ_NUMBER}}.1 The [system] shall [measurable performance metric, e.g. "respond within 500ms"]
+{{NEXT_REQ_NUMBER}}.2 The [system] shall [measurable scale metric, e.g. "support 100 concurrent users"]
+
+### Requirement {{NEXT_REQ_NUMBER_PLUS_ONE}}: Security & Privacy
+**Objective:** As a security/compliance stakeholder, I want the feature to protect sensitive data and enforce access boundaries, so that the system is safe to ship.
+
+#### Acceptance Criteria
+{{NEXT_REQ_NUMBER_PLUS_ONE}}.1 The [system] shall [measurable security behavior, e.g. "encrypt data at rest using AES-256"]
+{{NEXT_REQ_NUMBER_PLUS_ONE}}.2 If [unauthorized or invalid condition], the [system] shall [deny or recover with explicit behavior]
+
+### Requirement {{NEXT_REQ_NUMBER_PLUS_TWO}}: Reliability & Availability
+**Objective:** As an operator, I want predictable failure handling, so that incidents remain diagnosable and recoverable.
+
+#### Acceptance Criteria
+{{NEXT_REQ_NUMBER_PLUS_TWO}}.1 If [failure condition], the [system] shall [recovery behavior]
+{{NEXT_REQ_NUMBER_PLUS_TWO}}.2 The [system] shall [durability / retry / fallback expectation]

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

@@ -54,9 +54,21 @@
 
 ## Completion Criteria
 
-- [ ] {{Criteria 1 — observable, testable, maps to acceptance criteria R{{REQ_NUMBER}}}}
-- [ ] {{Criteria 2 — measurable, objective}}
-- [ ] {{Criteria 3 — maps directly to acceptance criteria from requirements.md}}
+- [ ] {{Criteria 1 — observable output or artifact, maps to acceptance criteria R{{REQ_NUMBER}}}}
+- [ ] {{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
+
+- [ ] Automated verification
+  - Command(s): `{{TYPECHECK / TEST / BUILD COMMANDS OR N/A}}`
+  - Expected proof: {{What output, exit code, or report proves success}}
+- [ ] Artifact / runtime verification
+  - Inspect: `{{artifact path | route | UI state | DB object | manifest entry}}`
+  - Expect: {{Observable result that proves the task is really wired}}
+- [ ] Contract / negative-path verification
+  - Check: {{Unauthorized path, validation error, permission omission, missing env behavior, deletion effect, etc.}}
+  - Expect: {{Concrete failure mode or contract-preserving behavior}}
 
 ## Risk Assessment
 
@@ -70,3 +82,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.