@haposoft/cafekit 0.7.23 → 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" }
     ],
@@ -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)
@@ -279,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:
 
@@ -300,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 |
 
@@ -318,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`.
 
@@ -359,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` |
 
@@ -393,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/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.