@haposoft/cafekit 0.7.24 → 0.7.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.24",
+  "version": "0.7.25",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/agents/god-developer.md

@@ -35,7 +35,7 @@ Any logic gaps must be clarified BEFORE typing, not discovered after bugs ship.
 ### 1. Read & Understand Input
 
 When activated, you will receive one of two input types:
-- **Task file list** (`tasks/task-01-*.md`, `task-02-*.md`...) with `spec.json`.
+- **Task file list** (`tasks/task-R0-01-*.md`, `task-R1-01-*.md`...) with `spec.json`.
 - **Direct description** from the main agent or `hapo:develop` skill. 
   *(Always proactively leverage domain-specific best practices by invoking `hapo:frontend-development`, `hapo:backend-development`, `hapo:mobile-development`, or `hapo:react-best-practices` depending on the current task).*
 

package/src/claude/agents/spec-maker.md

@@ -85,6 +85,7 @@ Before writing `design.md`, select a discovery mode and record the reason:
 - For light mode: Load `{{SKILLS_DIR}}/specs/rules/design-discovery-light.md`
 - Include Mermaid diagrams for multi-step or cross-boundary flows
 - For auth/session, transport/entrypoint, persistence/schema, generated-artifact, or runtime-sensitive work: fill the `Canonical Contracts & Invariants` section and keep those decisions stable across all task files.
+- For privacy/delete-data work: the design MUST choose one canonical deletion policy and express it verbatim in `Canonical Contracts & Invariants` before tasks are generated.
 - Record `discovery_mode` and `discovery_reason` in `spec.json.design_context`
 
 ### Requirements Traceability (MANDATORY)
@@ -107,6 +108,7 @@ Before writing `design.md`, select a discovery mode and record the reason:
 - Apply `(P)` parallel markers when applicable (load `{{SKILLS_DIR}}/specs/rules/tasks-parallel-analysis.md`)
 - Every task MUST include `Verification & Evidence` with exact commands, artifacts/runtime surfaces, and negative-path checks.
 - Completion criteria MUST be objective enough that a downstream quality gate can prove them without guesswork.
+- Validation decisions that affect implementation MUST be written into implementation-facing sections (`Objective`, `Constraints`, `Implementation Steps`, `Completion Criteria`, `Verification & Evidence`) rather than only `Risk Assessment`.
 
 ### Sub-Task Detail Requirements (MANDATORY)
 Each task file MUST contain granular sub-tasks with the following structure:
@@ -137,17 +139,22 @@ Task(subagent_type="researcher", prompt="Research [feature topic]")
 
 ## Pre-Completion Checklist
 
-Before finalizing any specification, assert all 11 points in the `Pre-Finalization Checklist` defined in `SKILL.md`. Do not exit or declare completion until verifiable.
+Before finalizing any specification, assert every point in the `Pre-Finalization Checklist` defined in `SKILL.md`. Do not exit or declare completion until verifiable.
 
 ### Finalization Audit (MANDATORY)
 
 Before marking the spec ready:
 1. Re-scan `tasks/` and write `spec.json.task_files` from the real filesystem (sorted, relative paths)
-2. Fail if any on-disk task file is missing from `task_files`
-3. Fail if any path in `task_files` does not exist
-4. Infer `design_context.validation_recommended = true` for auth, privacy, delete-data, migration, schema-change, browser-extension-permission, external-provider, or 5+ task file specs
-5. If `validation_recommended = true` and validation has not completed (or the user did not explicitly accept risk), keep `ready_for_implementation = false`
-6. Reject task files that use legacy non-numeric mappings like `NFR-1`
+2. Build or refresh `spec.json.task_registry` from the same filesystem scan. Each registry entry MUST include `id`, `title`, `status`, `dependencies` (relative task paths), `blocker`, `started_at`, `completed_at`, and `last_updated_at`
+3. Fail if any on-disk task file is missing from `task_files`
+4. Fail if any path in `task_files` does not exist
+5. Fail if any on-disk task file is missing from `task_registry` or any registry path does not exist
+6. Infer `design_context.validation_recommended = true` for auth, privacy, delete-data, migration, schema-change, browser-extension-permission, external-provider, or 5+ task file specs
+7. If the spec scope switched away from Claude/Anthropic, fail if `requirements.md`, `design.md`, or `tasks/*.md` still contain stale provider strings like `Claude API`, `Haiku`, or `haiku_reachable`. `research.md` may mention old providers only as historical comparison.
+8. For delete/privacy specs, fail if requirements/design/tasks mix multiple deletion policies (for example `email_hash` in one place and `deleted-<uuid>` in another) without one canonical design decision.
+9. If `validation_recommended = true` and validation has not completed (or the user did not explicitly accept risk), keep `ready_for_implementation = false`
+10. Reject task files that use legacy non-numeric mappings like `NFR-1`
+11. If validation decisions were accepted, fail unless they are reflected in implementation-facing sections of affected artifacts and `spec.json.updated_at` / review timestamps reflect the reviewed state
 
 ## Execution Workflow Summary
 
@@ -175,7 +182,7 @@ specs/<feature>/
 
 ### 4. Handoff
 - Update `spec.json` with `"status": "in_progress"` and `"current_phase": "develop"`
-- Ensure `task_files` is synchronized and `ready_for_implementation` reflects the finalization audit outcome
+- Ensure `task_files` + `task_registry` are synchronized and `ready_for_implementation` reflects the finalization audit outcome
 - Report the spec directory path to the orchestrator
 - DO NOT begin implementation yourself
 

package/src/claude/hooks/spec-state.cjs

@@ -63,17 +63,36 @@ try {
   }
 
   const phase = activeSpec.current_phase || activeSpec.phase || 'unknown';
-  
+  const taskRegistry = activeSpec.task_registry || {};
+  const taskEntries = Object.entries(taskRegistry);
+  const taskCounts = taskEntries.reduce((acc, [, task]) => {
+    const status = task?.status || 'pending';
+    acc[status] = (acc[status] || 0) + 1;
+    return acc;
+  }, {});
+  const taskStatusByPath = new Map(taskEntries.map(([taskPath, task]) => [taskPath, task?.status || 'pending']));
+  const nextUnblocked = taskEntries.find(([, task]) => {
+    const status = task?.status || 'pending';
+    const deps = Array.isArray(task?.dependencies) ? task.dependencies : [];
+    return status === 'pending' && deps.every((dep) => taskStatusByPath.get(dep) === 'done');
+  });
+
   // Format the output
   const lines = [];
   lines.push('');
   lines.push('### 🔴 URGENT SYSTEM TOLLGATE (STATE SYNC) 🔴');
   lines.push(`- **Active Feature:** \`${featureName}\``);
   lines.push(`- **Current Phase:** \`${phase}\``);
+  if (taskEntries.length > 0) {
+    lines.push(`- **Task Registry:** \`${taskEntries.length} total | ${(taskCounts.done || 0)} done | ${(taskCounts.in_progress || 0)} in_progress | ${(taskCounts.blocked || 0)} blocked | ${(taskCounts.pending || 0)} pending\``);
+    if (nextUnblocked) {
+      lines.push(`- **Next Unblocked Task:** \`${nextUnblocked[0]}\``);
+    }
+  }
   lines.push('');
   lines.push(`> BẮT BUỘC (MANDATORY): Nếu bạn vừa hoàn thành một bước, bạn KHÔNG ĐƯỢC báo cáo "Đã xong" ngay.`);
   lines.push(`> Bạn PHẢI sử dụng công cụ Edit để cập nhật trạng thái vật lý sau khi đã có bằng chứng verify thật (build/test/runtime/artifact), không phải chỉ vì code đã viết xong.`);
-  lines.push(`> 1. Sửa file \`spec.json\` (status, phase/current_phase, timestamps, \`task_files\`, validation state nếu có thay đổi).`);
+  lines.push(`> 1. Sửa file \`spec.json\` (status, phase/current_phase, timestamps, \`task_files\`, \`task_registry\`, validation state nếu có thay đổi).`);
   lines.push(`> 2. Chỉ khi verify xong mới sửa file \`tasks/task-*.md\` (status + tick '[x]' các sub-task và completion criteria liên quan).`);
   lines.push(`> 3. NẾU VỪA HOÀN THÀNH 1 TASK CÓ SỬA SOURCE CODE, BẮT BUỘC cập nhật ngay tài liệu trong \`docs/\` (\`system-architecture.md\` hoặc Changelog) cho đồng bộ.`);
   lines.push(`> CẤM VI PHẠM LUẬT TOLLGATE NÀY NHẰM ĐẢM BẢO TÍNH ĐỒNG BỘ CỦA HỆ THỐNG.`);

package/src/claude/rules/manage-docs.md

@@ -67,8 +67,8 @@ specs/
     ├── spec.json               # System state machine & global status
     ├── design.md               # Architecture, requirements, and data flows
     └── tasks/
-        ├── task-01-setup.md    # Actionable granular steps for development
-        └── task-02-api.md      # Next sequential task
+        ├── task-R0-01-setup.md  # Actionable granular steps for development
+        └── task-R1-01-api.md    # Next requirement-driven task
 ```
 
 ### The State Machine (`spec.json`)
@@ -81,11 +81,11 @@ This blueprint covers:
 - **Data Flow:** Mandatory Mermaid Data Flow Diagram detailing state transitions, DB interactions, and API payloads.
 - **Risk Assessment:** Pre-identified failure points and mitigations.
 
-### Execution Checklists (`tasks/task-0*.md`)
-Work is decomposed into linear markdown task files.
+### Execution Checklists (`tasks/task-R*.md`)
+Work is decomposed into requirement-driven markdown task files.
 Each task file contains:
 - **Prerequisites:** Blockers that must clear before this stage begins. (Task N+1 cannot start without Task N defining its payload).
 - **Execution Checklist:** Granular `[ ]` markdown items for agents to toggle `[x]` as they implement code.
 - **Success Criteria:** Strict definition of "Done".
 
-Comply with the overarching rules in `./rules/ai-dev-rules.md`.
+Comply with the overarching rules in `./rules/ai-dev-rules.md`.

package/src/claude/rules/state-sync.md

@@ -3,7 +3,7 @@
 ## Single Source of Truth
 
 In any Spec-driven workflow (`hapo:specs`), the state of the project is physically persisted in **two layers**:
-1. **Machine Layer (`spec.json`)**: Tracks phase, status, and overall completion.
+1. **Machine Layer (`spec.json`)**: Tracks phase, status, overall completion, and per-task machine state via `task_registry`.
 2. **Human Layer (`tasks/task-*.md`)**: Checkboxes indicating granular execution progress.
 
 ## The Sync-back Rule (Mandatory)
@@ -12,15 +12,16 @@ Whenever an agent finishes a task or blocks due to an issue, it **MUST NOT** sim
 Before returning control to the user or orchestrator, the agent **MUST**:
 
 ### On Success:
-1. Update `spec.json`: Modify `current_phase` if moving forward, ensure `status` accurately reflects progress, and keep `task_files` synchronized with the real files on disk.
-2. Edit `task-XX.md`: Change `Status` only after real verification has passed (build/test/runtime/artifact). Then check `[x]` the sub-task boxes and relevant completion criteria.
+1. Update `spec.json`: Modify `current_phase` if moving forward, ensure `status` accurately reflects progress, keep `task_files` synchronized with the real files on disk, and update the corresponding `task_registry` entry (`status`, `blocker`, `started_at`, `completed_at`, `last_updated_at`).
+2. Edit `task-R*.md`: Change `Status` only after real verification has passed (build/test/runtime/artifact). Then check `[x]` the sub-task boxes and relevant completion criteria.
 3. Call `TaskUpdate` if Claude Tasks are active, setting the status to "completed" only after the physical files were updated.
 
 ### On Block/Failure (>3 retries):
 1. Update `spec.json`: Set `"status": "blocked"` and fill out the `"blocker"` string with the root cause.
-2. Edit `task-XX.md`: Change `Trạng thái: pending` (or `in_progress`) to `Trạng thái: blocked` with a note.
-3. Alert the orchestrator or user via `AskUserQuestion` or explicit warning.
+2. Update the corresponding `task_registry` entry to `blocked`, persist the blocker reason, and stamp `last_updated_at`.
+3. Edit `task-R*.md`: Change `Status: pending` (or `in_progress`) to `Status: blocked` with a note.
+4. Alert the orchestrator or user via `AskUserQuestion` or explicit warning.
 
 **Canonical state values:** New specs MUST use `status: "in_progress"` for active work. Legacy `in-progress` may be read for compatibility, but must not be emitted in new files.
 
-**Golden Rule:** If the current phase changes, or a task completes, the agent must update the physical files. Never mark a task completed before there is execution proof. The context is intentionally NOT persisted in the chat to save tokens. An injected Hook (`spec-state.cjs`) constantly enforces and validates this state.
+**Golden Rule:** If the current phase changes, or a task completes, the agent must update the physical files. Never mark a task completed before there is execution proof, and never let `task_registry` disagree with the matching markdown task file. The context is intentionally NOT persisted in the chat to save tokens. An injected Hook (`spec-state.cjs`) constantly enforces and validates this state.

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

@@ -52,6 +52,7 @@ flowchart TD
 ### Step 1: Initialize & Load Spec
 - Identify input: Open `specs/<feature-name>/spec.json`.
 - Check `ready_for_implementation` status. If not ready, notify user.
+- Load `task_registry` and verify it matches the requested task file(s). If registry is missing or stale, route to `/hapo:sync audit <feature>` before coding.
 - **Task Scoping (CRITICAL):**
   - If the user specifies a particular task file (e.g., `task-R0-02...md`), load **ONLY** that specific file into working memory.
   - If no specific task is mentioned, list and load all Markdown files in `specs/<feature-name>/tasks/*.md`.
@@ -63,6 +64,7 @@ flowchart TD
   - Requirement IDs referenced by the task
   - Relevant `Canonical Contracts & Invariants` from `design.md`
 - If the task file is missing actionable completion or verification detail, STOP and route back to spec correction. Do not guess.
+- Before coding, set the active task(s) to `in_progress` in both markdown and `spec.json.task_registry`, or route through `/hapo:sync` if the runtime expects the sync protocol.
 
 ### Step 2: Scout (Codebase Inspection)
 - **Mandatory:** Call agent `Task(subagent_type="inspect", ...)` to scan the overall codebase structure (e.g., where components live, where utils are). Avoid wandering into forbidden zones.
@@ -87,8 +89,13 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
 - Only escalate to the user after 3 consecutive failed review rounds.
 
 ### Step 5: State Sync + Incremental Docs Sync
-- Only after Step 4 passes may you mark task checkboxes completed and sync `spec.json` progress/timestamps.
+- Only after Step 4 passes may you mark task checkboxes completed and sync `spec.json` progress/timestamps/task_registry.
 - If verification is partial or blocked by environment, keep the task in `pending` or `in_progress` and record the blocker instead of pretending completion.
+- A completed task MUST leave behind:
+  - markdown `**Status:** done`
+  - `spec.json.task_registry[path].status = "done"`
+  - `completed_at` + `last_updated_at`
+  - synchronized top-level `updated_at`
 - After passing the Quality Gate, evaluate if any actual codebase modifications occurred (e.g., check pending files via git status).
 - If files were created or modified: Trigger `docs-keeper` automatically to execute `repomix` and update the global `/docs/` and project logs.
 - **CWD Protocol (CRITICAL):** When spawning `docs-keeper`, you MUST ensure the agent's Current Working Directory (CWD context) is explicitly set to the **Workspace Root**, NOT the inner package directory you were just coding in. Otherwise, `docs-keeper` will search for the root `docs/` folder in the wrong place and crash.

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

@@ -44,6 +44,7 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Requirements
 - 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
@@ -132,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"]
@@ -218,6 +219,15 @@ Load: `references/scope-inquiry.md`
 - 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)
@@ -237,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
 ...
 ```
@@ -291,13 +301,24 @@ Load: `references/review.md` + `rules/design-review.md`
 - 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`
 
@@ -329,7 +350,8 @@ 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.
@@ -338,7 +360,7 @@ When user calls `hapo:specs`, system checks `specs/`:
 
 **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.
+**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.
@@ -346,6 +368,8 @@ When user calls `hapo:specs`, system checks `specs/`:
 
 **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:
@@ -354,7 +378,8 @@ When user calls `hapo:specs`, system checks `specs/`:
 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)
+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`.
 
@@ -363,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
@@ -427,7 +452,9 @@ Before finalizing any specification, assert all the following:
 - [ ] **Risk matrix filled**: likelihood × impact, with mitigation for High items
 - [ ] **Test strategy defined**: what gets unit tested, integration tested, e2e validated
 - [ ] **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

@@ -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

@@ -33,6 +33,7 @@ Detail bullets must include:
 - 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.
@@ -113,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
 
@@ -148,6 +150,8 @@ Rules:
 - 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

@@ -74,9 +74,10 @@ Capture only the contracts whose inconsistency would break downstream implementa
 | Auth / session | | | |
 | Transport / entrypoints | | | |
 | Data / persistence | | | |
+| Deletion / retention policy | | | |
 | 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.
+> 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
 

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

@@ -34,6 +34,7 @@
     "blocks": []
   },
   "task_files": [],
+  "task_registry": {},
   "blocker": null,
   "progress": {
     "init": "done",
@@ -53,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/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.