@haposoft/cafekit 0.7.23 → 0.7.25

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,13 @@ 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.
+- `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.
+
 ### Output Criteria
 - Never implement code — only create spec documents
 - Return file paths and a brief summary
@@ -66,7 +73,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" }
     ],
@@ -126,7 +133,7 @@ flowchart TD
     P --> Q["Step 6: Design — pick discovery mode"]
     Q --> R["Write design.md"]
     R --> S["Step 7: Tasks — split into individual files"]
-    S --> T["Create tasks/task-01.md, task-02.md..."]
+    S --> T["Create tasks/task-R*.md + task_registry"]
     T --> U["Step 8: Hydrate Claude Tasks if >= 3 task files"]
     U --> V{Review?}
     V -->|Yes| W["Run review — auto-pick red team or validation"]
@@ -202,6 +209,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 +218,16 @@ 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.
+- Build `spec.json.task_registry` alongside `task_files`. For each task file, register at minimum:
+  - `id`
+  - `title`
+  - `status` (`pending` by default)
+  - `dependencies` (relative task paths, not prose labels)
+  - `blocker`
+  - `started_at`
+  - `completed_at`
+  - `last_updated_at`
 - Update `spec.json` phase + task metadata
 
 #### Requirement-Driven Task Grouping (MANDATORY)
@@ -229,7 +247,7 @@ tasks/
 ├── task-R1-02-gap-marker-detector.md
 ├── task-R1-03-chunk-api-endpoint.md
 ├── task-R2-01-summarize-orchestrator.md
-├── task-R2-02-haiku-integration.md
+├── task-R2-02-provider-integration.md
 ├── task-R3-01-consent-onboarding.md
 ...
 ```
@@ -279,9 +297,30 @@ 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.
+- **Reconciliation Rule:** `validation.status = "completed"` is forbidden until all accepted findings and validation decisions are physically propagated into `requirements.md`, `design.md`, `tasks/*.md`, and `spec.json` where applicable.
+
+### Step 9.5: Finalization Audit (MANDATORY)
+- Re-scan the `tasks/` directory and rebuild `spec.json.task_files` from the real filesystem (sorted, relative paths)
+- Rebuild `spec.json.task_registry` from the real filesystem if it is missing, stale, or missing keys. Preserve task status fields when the path still matches.
+- 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 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 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 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
+  2. privacy-preserving re-registration lock using a non-raw identifier (for example `email_hash` / `email_fingerprint`) with a retention period.
+  Tasks and requirements must reuse the same policy verbatim; mixed policies are invalid.
+- FAIL if `validation.status = "completed"` but `timestamps.validation_done` / `timestamps.review_done`, `updated_at`, and report metadata are not synchronized with the final reviewed state.
+- 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 +339,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 |
 
@@ -311,24 +350,36 @@ When user calls `hapo:specs`, system checks `specs/`:
 | `init` done | "Next: write requirements" |
 | `requirements` done | "Next: architectural design" |
 | `design` done | "Next: break into tasks" |
-| `tasks` done | "Next: `/hapo:develop <feature>`" |
+| `tasks` done + validation recommended but incomplete | "Next: `/hapo:specs --validate <feature>`" |
+| `tasks` done + ready_for_implementation = true | "Next: `/hapo:develop <feature>`" |
 | Spec is `blocked` | "Warning: spec `X` is blocking this spec" |
 
 **State persistence:** Update `spec.json` `phase` field on each transition. `spec.json` is the single source of truth.
 
 ### spec.json Update Rules (MANDATORY)
 
-**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.
+**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. This includes `review_done` and `validation_done` after review/validate workflows. 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`.
+
+**Task machine-state:** `task_registry` MUST be present after Step 7. Each key is a relative task path, and each value MUST contain `id`, `title`, `status`, `dependencies`, `blocker`, `started_at`, `completed_at`, and `last_updated_at`.
+
+**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. `task_registry` matches the real filesystem and does not omit any task file
+7. 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`.
 
@@ -337,7 +388,7 @@ If any approval is `false`, `ready_for_implementation` MUST remain `false`.
 ```
 specs/
 └── <feature-name>/
-    ├── spec.json              # Metadata, state, scope_lock, dependencies
+    ├── spec.json              # Metadata, state, scope_lock, dependencies, task_registry
     ├── requirements.md        # Technical requirements (EARS format)
     ├── research.md            # Research notes
     ├── design.md              # Architectural design
@@ -359,7 +410,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 +444,18 @@ 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
+- [ ] **task_registry synced**: every task file has exactly one machine-state entry with valid status + dependencies
+- [ ] **Validation gate consistent**: validation_recommended and validation.status agree with spec risk
+- [ ] **Provider wording clean**: no stale vendor/provider strings outside allowed research context
+- [ ] **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
@@ -40,6 +40,9 @@ These rules override any self-reasoning or optimization the system may attempt:
 2. **No implementation code files.** This workflow produces ONLY `.md` files. If a finding requires a new shared module or config file, describe it inside the relevant `task-*.md` file. Do NOT create `.ts`, `.js`, `.py`, or any source code file.
 3. **Findings must use the exact format** defined in Part A Step 5 below. No shortened or custom formats.
 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`.
 
 ---
 
@@ -110,6 +113,7 @@ If "Review each one": For each finding, ask: "Apply" | "Reject" | "Modify sugges
 #### Step 8: Apply to Spec
 - Edit design.md / task files directly for accepted findings
 - Create `reports/red-team-report.md` documenting the full review session
+- Mark a finding as `Applied To = ...` only after the physical file really contains the change
 
 ### Finding Output Format
 
@@ -141,7 +145,7 @@ If "Review each one": For each finding, ask: "Apply" | "Reject" | "Modify sugges
 
 ## Part B: Validation Interview
 
-### 6-Step Workflow
+### 8-Step Workflow
 
 #### Step 1: Read Spec
 - `requirements.md` — technical requirements
@@ -211,6 +215,31 @@ Save to `reports/validate-log.md`:
 | Risk | Task files (Risk Assessment section) |
 | Unknown | `design.md` (add new subsection) |
 
+**Additional propagation rules:**
+- If the decision changes implementation behavior, update an implementation-facing section, not only `Risk Assessment`.
+- If the decision changes scope or provider choice, scan `requirements.md`, `design.md`, and `tasks/*.md` for stale wording and normalize it.
+- If the decision changes deletion/privacy behavior, update `Canonical Contracts & Invariants` first, then tasks that inherit that contract.
+
+#### Step 7: Reconciliation Audit (MANDATORY)
+Before declaring validation complete:
+1. Re-read `spec.json`, `requirements.md`, `design.md`, and all `tasks/task-*.md`
+2. Verify every accepted red-team finding and every validation action item is reflected in the correct physical file(s)
+3. Fail the audit if:
+   - a report says "applied" but the file still contains the old text
+   - stale provider strings remain after a provider change
+   - delete-data/privacy artifacts mix multiple canonical policies
+   - `spec.json.updated_at`, `timestamps.review_done`, or `timestamps.validation_done` do not reflect the final reviewed state
+4. Only after the audit passes may you:
+   - set `spec.json.validation.status = "completed"`
+   - set `spec.json.timestamps.validation_done`
+   - set `spec.json.timestamps.review_done`
+   - set `spec.json.ready_for_implementation = true` when all other gates are satisfied
+
+#### Step 8: Final Status Write-Back
+- Update `spec.json.updated_at` to the reconciliation time
+- Ensure `red-team-report.md` and `validate-log.md` do not contradict `spec.json`
+- If reconciliation fails, keep `validation.status` as `not-run` or `in_progress` and list blockers explicitly
+
 ---
 
 ## Combined Output
@@ -225,5 +254,5 @@ Validate: {Q} questions asked, {D} decisions confirmed
 
 Files modified: {list}
 
-📌 Next step: /hapo:develop <feature>
+📌 Next step: /hapo:develop <feature>    (ONLY if reconciliation audit passed)
 ```

package/src/claude/skills/specs/references/task-hydration.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Convert task files (persistent storage) into Claude Tasks (session-scoped only), enabling real-time progress tracking and automatic unblocking when predecessor tasks complete.
+Convert task files (persistent storage) into Claude Tasks (session-scoped only), enabling real-time progress tracking and automatic unblocking when predecessor tasks complete. `spec.json.task_registry` is the machine-state bridge between markdown task files and session-scoped Claude Tasks.
 
 ## When to Run
 
@@ -37,23 +37,24 @@ Convert task files (persistent storage) into Claude Tasks (session-scoped only),
 
 | Field | Description | Example |
 |---|---|---|
-| `taskNumber` | Task sequence number | `1` |
+| `taskNumber` | Task sequence number | `R0-02` |
 | `priority` | Priority level | `P1`, `P2`, `P3` |
 | `effort` | Time estimate | `2h` |
 | `specDir` | Spec directory path | `specs/mobile-app/` |
-| `taskFile` | Task file name | `task-01-setup.md` |
+| `taskFile` | Task file name | `task-R0-02-extension-shell.md` |
 
 ## Hydration Workflow
 
-1. Read all `tasks/task-*.md` files → filter incomplete tasks
-2. Create `TaskCreate` for each major task, attach `addBlockedBy` per dependency chain:
+1. Read all `tasks/task-R*.md` files → filter incomplete tasks
+2. Load `spec.json.task_registry` and prefer its task status/dependencies when present
+3. Create `TaskCreate` for each major task, attach `addBlockedBy` per dependency chain:
    ```
-   Task 01 (no blockers) ← start here
-   Task 02 (addBlockedBy: [task-01-id])
-   Task 03 (addBlockedBy: [task-02-id])
+   Task R0-01 (no blockers) ← start here
+   Task R0-02 (addBlockedBy: [task-R0-01-id])
+   Task R1-01 (addBlockedBy: [task-R0-02-id])
    ```
-3. Create additional `TaskCreate` for high-risk steps within tasks (if any)
-4. Verify: no dependency cycles, all tasks have complete metadata
+4. Create additional `TaskCreate` for high-risk steps within tasks (if any)
+5. Verify: no dependency cycles, all tasks have complete metadata, and every hydrated task has a corresponding `task_registry` entry
 
 ## Fallback
 
@@ -78,8 +79,9 @@ Convert task files (persistent storage) into Claude Tasks (session-scoped only),
 ### Sync-back (after code completes)
 1. `TaskUpdate` marks tasks as completed
 2. Update `[ ]` → `[x]` in task files
-3. Update `spec.json` progress for the corresponding phase
-4. Git commit captures the state transition
+3. Update `spec.json.task_registry[path].status`, timestamps, blocker, and last_updated_at
+4. Update `spec.json` progress for the corresponding phase
+5. Git commit captures the state transition
 
 ## Quality Checks
 

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

@@ -32,6 +32,8 @@ 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)
+- Reuse canonical contracts from `design.md` verbatim; never invent alternate auth/provider/deletion policies in task prose
 - 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.
@@ -112,6 +114,7 @@ Every task file MUST contain the Risk Assessment table, even if no risks are ide
 - `_Requirements: X.X, Y.Y_` listing **only numeric requirement IDs** (comma-separated). Never append descriptive text, parentheses, translations, or free-form labels.
 - For cross-cutting requirements, list every relevant requirement ID. All requirements MUST have numeric IDs in requirements.md. If an ID is missing, stop and correct requirements.md before generating tasks.
 - Reference components/interfaces from design.md when helpful (e.g., `_Contracts: AuthService API`)
+- If a validation interview or red-team finding changes implementation behavior, update the sub-task itself. Do NOT hide the decision only inside `Risk Assessment`.
 
 ### 5. Code-Only Focus
 
@@ -131,6 +134,24 @@ 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.
+- For provider-sensitive work, use provider-neutral wording unless the scope lock explicitly names a vendor.
+- For delete-data/privacy work, task text MUST match the single deletion/retention policy chosen in `design.md`. Mixed policies are invalid.
 
 ## Task Hierarchy Rules
 

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

@@ -65,6 +65,20 @@ 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 | | | |
+| Deletion / retention policy | | | |
+| Generated artifacts / runtime outputs | | | |
+
+> Task files must reuse the same contract wording. If the feature touches delete-data or privacy retention, explicitly decide whether re-registration is blocked and how that lock works without keeping raw PII. 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,9 @@
     "blockedBy": [],
     "blocks": []
   },
+  "task_files": [],
+  "task_registry": {},
+  "blocker": null,
   "progress": {
     "init": "done",
     "requirements": "pending",
@@ -50,7 +54,8 @@
     "tasks_done": null,
     "code_done": null,
     "test_done": null,
-    "review_done": null
+    "review_done": null,
+    "validation_done": null
   },
   "design_context": {
     "discovery_mode": null,

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.

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

@@ -1,22 +1,22 @@
 ---
 name: hapo:sync
-description: "Dumb-proof status tracker and file synchronizer. Updates spec.json and tasks/*.md without breaking structural schemas. Includes Auto-Audit."
+description: "Dumb-proof status tracker and file synchronizer. Updates spec.json, task_registry, and tasks/*.md without breaking structural schemas. Includes Auto-Audit."
 version: 1.0.0
-argument-hint: "<feature_name> <task_id> <status> [blocker] | phase <feature_name> <next_phase> | audit <feature_name>"
+argument-hint: "<feature_name> <task_id|task-file> <status> [blocker] | phase <feature_name> <next_phase> | audit <feature_name>"
 ---
 
 # Sync (State Tracking Protocol)
 
-This skill safely bridges the gap between active development state and physical documentation files (`spec.json` & `task-0*.md`). Instead of relying on risky raw AI edits, this skill executes precise contextual replacements.
+This skill safely bridges the gap between active development state and physical documentation files (`spec.json` + `task_registry` + `tasks/task-R*.md`). Instead of relying on risky raw AI edits, this skill executes precise contextual replacements.
 
 ## Supported Commands
 
 ### 1. Task Synchronization
 Update a specific task's status and automatically check its relevant sub-checkboxes.
 
-**Usage:** `/hapo:sync <feature_name> <task_id> <status> ["optional blocker msg"]`
-- Example 1: `/hapo:sync auth task-01 completed`
-- Example 2: `/hapo:sync payment task-03 blocked "API Endpoint Down"`
+**Usage:** `/hapo:sync <feature_name> <task_id|task-file> <status> ["optional blocker msg"]`
+- Example 1: `/hapo:sync auth R0-02 done`
+- Example 2: `/hapo:sync payment task-R1-03-chunks-api.md blocked "API Endpoint Down"`
 
 ### 2. Phase Advancement
 Advance the entire project to the next logical phase.
@@ -25,16 +25,17 @@ Advance the entire project to the next logical phase.
 - Example: `/hapo:sync phase shopping_cart test`
 
 ### 3. State Audit
-Scans the `spec.json` against all physical `task-0*.md` files to detect mismatches or un-checked boxes and repairs them.
+Scans the `spec.json` against all physical `task-R*.md` files to detect mismatches between `task_files`, `task_registry`, and markdown task headers, then repairs them.
 
 **Usage:** `/hapo:sync audit <feature_name>`
 - Example: `/hapo:sync audit auth`
 
 ## Directives
 
-1. **Precision Edits:** Never overwrite the entire `spec.json` string. Provide surgical JSON modification protocols.
-2. **Markdown Integrity:** When marking a task "completed", use Regex to turn `[ ]` into `[x]` ONLY inside the `## Các bước thực hiện` section.
-3. **Task Completion Hook:** When `hapo:sync` marks the final pending task as `completed`, it should automatically prompt the user if they'd like to advance the Phase via `hapo:sync phase`.
+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. **Task Completion Hook:** When `hapo:sync` marks the final pending task as `done`, it should automatically prompt the user if they'd like to advance the phase.
 
 ## References
 Read `references/sync-protocols.md` for exact Search/Replace regex patterns and JSON schema expectations before acting on the files.

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

@@ -2,34 +2,54 @@
 
 The following guidelines dictate exactly how `hapo:sync` should interact with files to prevent data corruption.
 
+**Canonical task status vocabulary:** `pending`, `in_progress`, `blocked`, `done`
+
 ## 1. Updating `spec.json`
 
 When requested to update a phase or change task configuration, `spec.json` must maintain its strict schema (defined in `hapo:specs/templates/init.json`).
 
-*   **JSON Modification Rule:** Do not output whole files. Instead, load the JSON structure, apply the update to `status`, `current_phase`, `blocker` (if any), and overwrite the file cleanly.
-*   **Status Update:** If a task changes to `blocked`, `spec.json`'s main `status` must transition to `"blocked"`, and the `"blocker"` string must record the task ID & reason.
+*   **JSON Modification Rule:** Do not output whole files. Instead, load the JSON structure, apply the update to `status`, `current_phase`, `blocker` (if any), `task_files`, and the relevant `task_registry` entry, then overwrite the file cleanly.
+*   **Task Registry Rule:** Resolve the incoming task reference to a single relative path in `task_registry`. Accept either:
+    - compact task ID like `R0-02`
+    - full filename like `task-R0-02-extension-shell.md`
+    - 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`.
 
 ## 2. Updating `tasks/task-**.md`
 
-The structure of `tasks/task.md` relies heavily on exact keyword markers. Follow these surgical regex protocols:
+The structure of `tasks/task.md` relies heavily on exact keyword markers. Follow these surgical protocols against `tasks/task-R*.md`:
 
 ### A. Completing a Task
-When `/hapo:sync <feature> <task-id> completed`:
-1. Find: `**Trạng thái:** pending` (or `in_progress`).
-2. Replace with: `**Trạng thái:** completed`.
-3. Locate block: `## Các bước thực hiện`.
-4. Convert every `- [ ]` into `- [x]` strictly within that section. Ignore checkboxes elsewhere in the document.
+When `/hapo:sync <feature> <task-id> done`:
+1. Find: `**Status:** pending` (or `in_progress` / `blocked`).
+2. Replace with: `**Status:** done`.
+3. Locate block: `## Implementation Steps`.
+4. Convert `- [ ]` into `- [x]` strictly within that section.
+5. Update relevant checkboxes in `## Completion Criteria` and `## Verification & Evidence` only when the caller provides or the file already contains real proof.
 
 ### B. Blocking a Task
 When `/hapo:sync <feature> <task-id> blocked "API error"`:
-1. Find: `**Trạng thái:** <anything>`.
-2. Replace with: `**Trạng thái:** blocked`.
-3. Ensure that an entry under `## Đánh giá Rủi ro` or a new section `## Blocker Log` is injected recording the explicit reason (e.g. `API error`).
+1. Find: `**Status:** <anything>`.
+2. Replace with: `**Status:** blocked`.
+3. Ensure that an entry under `## Blocker Log` exists recording the explicit reason (e.g. `API error`) and timestamp.
+
+### C. Starting / Resuming a Task
+When `/hapo:sync <feature> <task-id> in_progress`:
+1. Find: `**Status:** pending` (or `blocked`).
+2. Replace with: `**Status:** in_progress`.
+3. Do NOT pre-check completion boxes.
+4. Stamp `task_registry[path].started_at` if missing and refresh `last_updated_at`.
 
 ## 3. Audit Protocol
 
 When `/hapo:sync audit <feature>` is activated:
 1. **Load Truth:** Read `specs/<feature>/spec.json`.
 2. **Scan Directory:** Loop through `specs/<feature>/tasks/`.
-3. **Compare Constraints:** If parsing `task-01.md` reveals `Trạng thái: completed` but `spec.json` is missing this accounting, update the JSON. 
-4. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed.
+3. **Compare Constraints:** Rebuild `task_files` from disk, ensure every file exists in `task_registry`, and compare markdown `**Status:**` headers against `task_registry[path].status`.
+4. **Reconciliation Rules:**
+   - Missing registry entry → create it
+   - 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
+5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.