@haposoft/cafekit 0.7.24 → 0.7.26

package/src/claude/skills/develop/references/quality-gate.md

@@ -7,6 +7,13 @@ Green tests are NOT enough. The gate requires three proofs:
 2. Code/spec review
 3. Task evidence (completion criteria + runtime/artifact proof from the task file)
 
+## Automation Semantics
+
+- If the task names exact commands in `Verification & Evidence`, those exact commands are mandatory and must run before any fallback repo defaults.
+- `NO_TESTS` is never an automatic PASS.
+- `NO_TESTS` is acceptable only when the task does **not** require a dedicated test suite command and every other required automated command/evidence item passes.
+- If the task explicitly requires tests and the repo has no such test command or suite, the task is FAIL or BLOCKED, not done.
+
 ## Parallel Quality Cycle
 
 Maximum retry counter: **3 attempts**. Exceeding 3 triggers a collapse warning.
@@ -17,6 +24,7 @@ Variable: retry_count = 0
 Before START_LOOP:
   - Read the active task file(s)
   - Extract Related Files, Completion Criteria, Verification & Evidence
+  - Extract the exact executable verification commands in declaration order
   - Extract relevant design contracts/invariants for the touched area
   - If any of these are missing or too vague to verify, FAIL immediately and route back to spec correction
 
@@ -25,11 +33,11 @@ START_LOOP:
   PARALLEL GATE: Spawn BOTH agents simultaneously
   ---------------------------------------------------------------
   → Task(subagent_type="test-runner",
-        prompt="Run task-aware verification for the recently implemented code. Read the active task file(s) and execute: pre-flight typecheck/lint, relevant tests, build commands, and every Verification & Evidence item that is executable. Inspect named artifacts/runtime outputs. Return PASS only if automated checks and task evidence both pass. Mark anything unexecuted as UNVERIFIED.",
+        prompt="Run task-aware verification for the recently implemented code. Read the active task file(s) and execute the exact verification commands named there first, in order. After that, run any additional repo-level typecheck/test/build checks needed for confidence. Inspect named artifacts/runtime outputs. Return PASS only if automated checks and task evidence both pass. Mark anything unexecuted as UNVERIFIED. Treat NO_TESTS as non-passing unless the task did not require a dedicated test suite.",
         description="Test [feature]")
 
   → Task(subagent_type="code-auditor",
-        prompt="Review all recently written code against the active task file(s), referenced requirements, and design contracts. Missing deliverables, placeholder-only wiring, missing runtime entrypoints, or contract drift are Critical even if build/tests pass. Check security, logic, architecture, YAGNI/KISS/DRY. Return score (X/10), critical count, warning list, and evidence gaps.",
+        prompt="Review all recently written code against the active task file(s), referenced requirements, and design contracts. Missing deliverables, placeholder-only wiring, missing runtime entrypoints, overscope edits outside the task packet, or contract drift are Critical even if build/tests pass. Check security, logic, architecture, YAGNI/KISS/DRY. Return score (X/10), critical count, warning list, and evidence gaps.",
         description="Review [feature]")
 
   Wait for BOTH to return results.
@@ -38,7 +46,7 @@ START_LOOP:
   COMBINE RESULTS
   ---------------------------------------------------------------
 
-  CASE 1 — Test FAIL OR Evidence FAIL / UNVERIFIED:
+  CASE 1 — Automated FAIL OR required command missing OR Evidence FAIL / UNVERIFIED OR NO_TESTS when tests were required:
     - Increment retry_count++
     - If retry_count >= 3:
         → COLLAPSE! AskUserQuestion: "Quality gate cannot prove this task is complete! User intervention required!"
@@ -56,7 +64,7 @@ START_LOOP:
 
   CASE 3 — Test PASS + Evidence PASS + Review PASS (Score >= 9.5 AND Critical = 0):
     → PASS! Auto-approved.
-    → PROCEED to completion report.
+    → PROCEED to completion report with a verification receipt summarizing exact commands executed, artifact/runtime proof, and review result.
 
 REVIEW_ONLY:
   ---------------------------------------------------------------
@@ -77,6 +85,7 @@ REVIEW_ONLY:
 - **Architecture:** Breaking MVC boundaries, cross-module coupling, convention violations.
 - **Principles:** YAGNI violations, KISS violations, DRY violations (excessive code duplication).
 - **Evidence / Done-Criteria Drift:** Missing required artifacts, placeholder-only wiring, missing entrypoints, unproven completion criteria, or runtime contract mismatches.
+- **Overscope Delivery Drift:** Implementing later-task deliverables or editing out-of-scope files without direct justification for the active task.
 
 ## Terminal Log Format
 

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
 
@@ -134,14 +138,14 @@ If "Review each one": For each finding, ask: "Apply" | "Reject" | "Modify sugges
 
 | # | Finding | Severity | Disposition | Applied To |
 |---|---------|----------|-------------|------------|
-| 1 | {title} | Critical | Accept | Task 02 |
+| 1 | {title} | Critical | Accept | task-R0-02-... |
 ```
 
 ---
 
 ## 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
 
@@ -16,16 +16,16 @@ Convert task files (persistent storage) into Claude Tasks (session-scoped only),
 ┌──────────────────┐  Hydrate   ┌───────────────────┐
 │ Task Files       │ ─────────► │ Claude Tasks      │
 │ (persistent)     │            │ (session-scoped)  │
-│ [ ] Task 01      │            │ ◼ pending         │
-│ [ ] Task 02      │            │ ◼ pending         │
+│ [ ] task-R0-01   │            │ ◼ pending         │
+│ [ ] task-R0-02   │            │ ◼ pending         │
 └──────────────────┘            └───────────────────┘
                                         │ Work
                                         ▼
 ┌──────────────────┐  Sync-back ┌───────────────────┐
 │ Task Files       │ ◄───────── │ Task Updates      │
 │ (updated)        │            │ (completed)       │
-│ [x] Task 01      │            │ ✓ completed       │
-│ [ ] Task 02      │            │ ◼ in_progress     │
+│ [x] task-R0-01   │            │ ✓ completed       │
+│ [ ] task-R0-02   │            │ ◼ in_progress     │
 └──────────────────┘            └───────────────────┘
 ```
 
@@ -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,19 @@ 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. **Verification Receipt Rule:** `done` is illegal without a human-readable verification receipt already present in `## Verification & Evidence` (commands executed, artifact/runtime proof, or equivalent concrete evidence). If proof is missing, keep the task `in_progress` or `blocked`.
+5. **Task Docs Hook:** Every time `hapo:sync` marks a task as `done`, it must flag that a task-level docs checkpoint is now due for that verified task.
+6. **Phase Prompt Rule:** When `hapo:sync` marks the final pending task in the whole feature as `done`, it should automatically prompt the user if they'd like to advance the phase, but only after the docs checkpoint for that last completed task has been considered.
 
 ## 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,60 @@
 
 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`.
+*   **Done-State Rule:** Never set `task_registry[path].status = "done"` unless the matching markdown task file already contains a verification receipt in `## Verification & Evidence`, or the caller explicitly provides proof that can be written there first.
+*   **Task Docs Rule:** After a task is moved to `done`, emit a short alert that a task-level docs checkpoint is due for this verified task.
 
 ## 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. Inspect `## Verification & Evidence` first. If it has no explicit proof lines (commands run, artifact proof, runtime proof, or blockers cleared), STOP and refuse to mark the task done.
+3. Replace with: `**Status:** done`.
+4. Locate block: `## Implementation Steps`.
+5. Convert `- [ ]` into `- [x]` strictly within that section.
+6. Update relevant checkboxes in `## Completion Criteria` and `## Verification & Evidence` only when the caller provides or the file already contains real proof.
+7. Surface a note such as: `Docs checkpoint due: task Rn-mm just completed`.
 
 ### 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
+   - Either side says `done` but `## Verification & Evidence` has no concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
+5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.
+6. **Task Docs Alert:** If audit reveals tasks newly marked `done`, include whether task-level docs sync appears still due or already accounted for in the current run summary.

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

@@ -1,14 +1,14 @@
 ---
 name: hapo:test
 description: "Run and verify project tests across all scopes: unit, integration, e2e, and UI. Blast-radius scoping for speed, chrome-devtools for UI verification, structured verdicts for downstream automation."
-argument-hint: "[scope|--full|--ui <url>|--ui-auth <url>]"
+argument-hint: "[scope|--full|--ui <url>|--ui-auth <url>|--ui-flow <url>]"
 version: 2.0.0
 ---
 
 # Test — Verify Implementation Quality
 
 Run the project's test suite, analyze results, and return a structured verdict.
-Designed to work **after `hapo:code`** and to run **in parallel with `hapo:code-review`** during the `hapo:develop` Quality Gate.
+Designed to work **after `hapo:develop`**. Standalone `/hapo:test` uses the same `test-runner` contract that `hapo:develop` relies on during its Quality Gate, and may run **in parallel with `hapo:code-review`**.
 
 **Principles:** Fail-fast | Blast-radius scoping | Zero hidden failures | No mocking to pass
 

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

@@ -38,7 +38,7 @@ When `--full` is NOT specified, narrow the test scope to only what changed:
 ### Pre-flight Checks (always run first)
 
 Catch compile errors before spending time on tests.
-**HARD RULE:** If a pre-flight tool (like `eslint`, `flake8`, `tsc`) is missing, you MUST install it (e.g., `npm install -D eslint`, `pip install flake8`). Do NOT skip the pre-flight check.
+**HARD RULE:** Do NOT auto-install missing tooling during verification. If a required pre-flight tool (like `eslint`, `flake8`, `tsc`) is missing, stop and report it as an environment gap or missing project setup.
 
 ```bash
 # JavaScript / TypeScript
@@ -59,7 +59,7 @@ cargo check
 flutter analyze
 ```
 
-If pre-flight fails → report `Compile Error`, do NOT proceed to test execution.
+If pre-flight fails or a required tool is missing → report `Compile Error` / `Environment Gap`, do NOT proceed to test execution.
 
 ### Test Execution by Language
 
@@ -361,4 +361,3 @@ Flag as `Security Warning` if:
 - Mixed content (HTTP resources on HTTPS page) detected via network audit
 - `autocomplete="off"` missing on password fields
 
-