@haposoft/cafekit 0.7.24 → 0.7.26

package/src/claude/hooks/state.cjs

@@ -3,32 +3,30 @@
  * Copyright (c) 2026 Haposoft. MIT License.
  *
  * Multi-event Hook — state.cjs
- * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
  *
  * Persists and restores session progress across Claude Code sessions.
  *
  * Events:
  *   SessionStart  → load previous state and print to context
- *   Stop          → extract todos + git changes, save to latest.md
+ *   PostToolUse   → refresh state after Task/TaskCreate/TaskUpdate/TodoWrite
+ *   Stop          → persist full session state and archive
  *   SubagentStop  → append agent completion note to current state
  *
  * Storage: .claude/session-state/latest.md (+ archive/)
- * Safety:  atomic writes, 7-day expiry, max 5 archives
- *
  * Exit: 0 always (fail-open)
  */
 
 try {
-  const fs     = require('fs');
-  const path   = require('path');
-  const os     = require('os');
+  const fs = require('fs');
+  const path = require('path');
+  const os = require('os');
   const crypto = require('crypto');
   const { execSync } = require('child_process');
+  const { parseTranscript } = require('./lib/parser.cjs');
 
-  const EXPIRY_DAYS  = 7;
+  const EXPIRY_DAYS = 7;
   const MAX_ARCHIVES = 5;
-
-  // ── Storage ───────────────────────────────────────────────────────────────
+  const TRACKED_POST_TOOL_EVENTS = new Set(['Task', 'TaskCreate', 'TaskUpdate', 'TodoWrite']);
 
   function stateDir(cwd) {
     try {
@@ -37,56 +35,73 @@ try {
         if (!fs.existsSync(local)) fs.mkdirSync(local, { recursive: true });
         return local;
       }
-      const hash   = crypto.createHash('md5').update(cwd).digest('hex').slice(0, 12);
+
+      const hash = crypto.createHash('md5').update(cwd).digest('hex').slice(0, 12);
       const global = path.join(os.homedir(), '.claude', 'session-states', hash);
       if (!fs.existsSync(global)) fs.mkdirSync(global, { recursive: true });
       return global;
-    } catch { return null; }
+    } catch {
+      return null;
+    }
   }
 
   function loadLatest(cwd) {
     try {
-      const dir   = stateDir(cwd);
+      const dir = stateDir(cwd);
       if (!dir) return null;
-      const file  = path.join(dir, 'latest.md');
+
+      const file = path.join(dir, 'latest.md');
       if (!fs.existsSync(file)) return null;
-      const text  = fs.readFileSync(file, 'utf8');
-      const tsMatch = text.match(/<!-- Generated: (.+?) -->/);
-      if (tsMatch) {
-        const parsed = new Date(tsMatch[1]).getTime();
-        if (isNaN(parsed)) return null;
-        if (Date.now() - parsed > EXPIRY_DAYS * 24 * 60 * 60 * 1000) return null;
+
+      const text = fs.readFileSync(file, 'utf8');
+      const match = text.match(/<!-- Generated: (.+?) -->/);
+      if (match) {
+        const generatedAt = new Date(match[1]).getTime();
+        if (Number.isNaN(generatedAt)) return null;
+        if (Date.now() - generatedAt > EXPIRY_DAYS * 24 * 60 * 60 * 1000) return null;
       }
+
       return text;
-    } catch { return null; }
+    } catch {
+      return null;
+    }
   }
 
   function writeAtomic(filePath, content) {
-    const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-    fs.writeFileSync(tmp, content);
-    fs.renameSync(tmp, filePath);
+    const tempFile = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    fs.writeFileSync(tempFile, content);
+    fs.renameSync(tempFile, filePath);
   }
 
   function archive(dir) {
     try {
-      const src  = path.join(dir, 'latest.md');
-      if (!fs.existsSync(src)) return;
-      const aDir = path.join(dir, 'archive');
-      if (!fs.existsSync(aDir)) fs.mkdirSync(aDir);
-      const now  = new Date();
-      const pad  = n => String(n).padStart(2, '0');
-      const ts   = `${now.getFullYear()}${pad(now.getMonth()+1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`;
-      fs.copyFileSync(src, path.join(aDir, `${ts}.md`));
-      const files = fs.readdirSync(aDir).filter(f => f.endsWith('.md')).sort();
+      const latestFile = path.join(dir, 'latest.md');
+      if (!fs.existsSync(latestFile)) return;
+
+      const archiveDir = path.join(dir, 'archive');
+      if (!fs.existsSync(archiveDir)) fs.mkdirSync(archiveDir);
+
+      const now = new Date();
+      const pad = (value) => String(value).padStart(2, '0');
+      const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`;
+
+      fs.copyFileSync(latestFile, path.join(archiveDir, `${stamp}.md`));
+
+      const files = fs.readdirSync(archiveDir).filter((file) => file.endsWith('.md')).sort();
       while (files.length > MAX_ARCHIVES) {
-        try { fs.unlinkSync(path.join(aDir, files.shift())); } catch { /* ignore */ }
+        const oldest = files.shift();
+        try {
+          fs.unlinkSync(path.join(archiveDir, oldest));
+        } catch {
+          // fail-open
+        }
       }
-    } catch { /* fail-open */ }
+    } catch {
+      // fail-open
+    }
   }
 
-  // ── Data extraction ───────────────────────────────────────────────────────
-
-  function extractSessionData(stdinData) {
+  async function extractSessionData(stdinData) {
     const data = {
       timestamp: new Date().toISOString(),
       branch: process.env.GIT_BRANCH || '',
@@ -96,132 +111,159 @@ try {
 
     if (stdinData.transcript_path && fs.existsSync(stdinData.transcript_path)) {
       try {
-        const latest = [];
-        const lines  = fs.readFileSync(stdinData.transcript_path, 'utf8').split('\n').filter(Boolean);
-        for (const line of lines) {
-          try {
-            const entry = JSON.parse(line);
-            const blocks = entry.message?.content;
-            if (!Array.isArray(blocks)) continue;
-            for (const b of blocks) {
-              if (b.type === 'tool_use' && b.name === 'TodoWrite' && Array.isArray(b.input?.todos)) {
-                latest.length = 0;
-                latest.push(...b.input.todos);
-              }
-            }
-          } catch { /* skip bad lines */ }
-        }
-        data.todos = latest;
-      } catch { /* ignore */ }
+        const transcript = await parseTranscript(stdinData.transcript_path);
+        data.todos = transcript.todos;
+      } catch {
+        // fail-open
+      }
     }
 
     try {
-      const out = execSync('git diff --name-only HEAD', {
-        encoding: 'utf8', timeout: 3000, stdio: ['pipe','pipe','pipe']
+      const diff = execSync('git diff --name-only HEAD', {
+        encoding: 'utf8',
+        timeout: 3000,
+        stdio: ['pipe', 'pipe', 'pipe']
       }).trim();
-      if (out) data.modifiedFiles = out.split('\n').slice(0, 20);
-    } catch { /* ignore */ }
+
+      if (diff) {
+        data.modifiedFiles = diff.split('\n').slice(0, 20);
+      }
+    } catch {
+      // fail-open
+    }
 
     return data;
   }
 
-  // ── Markdown builder ──────────────────────────────────────────────────────
-
   function buildStateContent(data) {
-    const done    = data.todos.filter(t => t.status === 'completed');
-    const pending = data.todos.filter(t => t.status !== 'completed');
+    const done = data.todos.filter((todo) => todo.status === 'completed' || todo.status === 'done');
+    const pending = data.todos.filter((todo) => !['completed', 'done'].includes(todo.status));
+
     return [
       '# Session State',
       `<!-- Generated: ${data.timestamp} -->`,
       `<!-- Branch: ${data.branch || 'unknown'} -->`,
       '',
       '## What Worked (Verified)',
-      ...(done.length    ? done.map(t => `- ${t.content}`)    : ['- (No completed tasks recorded)']),
+      ...(done.length ? done.map((todo) => `- ${todo.content}`) : ['- (No completed tasks recorded)']),
       '',
       "## What's Left",
-      ...(pending.length ? pending.map(t => `- [ ] ${t.content}`) : ['- (All tasks completed)']),
+      ...(pending.length ? pending.map((todo) => `- [ ] ${todo.content}`) : ['- (All tasks completed)']),
       '',
       '## Key Files Modified',
-      ...(data.modifiedFiles.length   ? data.modifiedFiles.map(f => `- ${f}`) : ['- (No file changes detected)']),
+      ...(data.modifiedFiles.length ? data.modifiedFiles.map((file) => `- ${file}`) : ['- (No file changes detected)']),
       ''
     ].join('\n');
   }
 
   function buildAgentSection(data) {
-    const type = data.agent_type || 'unknown';
-    const ts   = new Date().toISOString().slice(11, 19);
-    return `\n## Agent Result: ${type} (${ts})\n- Completed at ${ts}\n`;
+    const agentType = data.agent_type || 'unknown';
+    const time = new Date().toISOString().slice(11, 19);
+    return `\n## Agent Result: ${agentType} (${time})\n- Completed at ${time}\n`;
   }
 
-  // ── Main ──────────────────────────────────────────────────────────────────
+  function mergeAgentSections(existing, content) {
+    if (!existing) return content;
+
+    const agentSections = existing.match(/## Agent Result:.+?(?=\n## |$)/gs);
+    if (!agentSections) return content;
 
-  const stdin   = fs.readFileSync(0, 'utf8').trim();
-  if (!stdin) process.exit(0);
+    const marker = '\n## Key Files Modified';
+    if (content.includes(marker)) {
+      return content.replace(marker, `\n${agentSections.join('\n')}${marker}`);
+    }
+
+    return `${content.trimEnd()}\n\n${agentSections.join('\n')}\n`;
+  }
 
-  const data  = JSON.parse(stdin);
-  const event = data.hook_event_name || '';
-  const cwd   = data.cwd || process.cwd();
-  const dir   = stateDir(cwd);
+  function appendAgentSection(existing, agentSection) {
+    if (!existing) return agentSection.trimStart();
 
-  // SessionStart: restore previous state
-  if (event === 'SessionStart') {
-    const prev = loadLatest(cwd);
-    if (prev) {
-      console.log('\n=== Prior Execution Context ===');
-      console.log(prev.trim());
-      console.log('=== End of Prior Context ===\n');
+    const marker = '\n## Key Files Modified';
+    if (existing.includes(marker)) {
+      return existing.replace(marker, `\n${agentSection}${marker}`);
     }
-    process.exit(0);
+
+    return `${existing.trimEnd()}\n${agentSection}`;
   }
 
-  // SubagentStop: append completion note
-  if (event === 'SubagentStop' && dir) {
-    const file    = path.join(dir, 'latest.md');
-    const agentSection = buildAgentSection(data);
+  async function persistSnapshot(dir, data, options = {}) {
+    const file = path.join(dir, 'latest.md');
     const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
-    let updated;
-    if (existing) {
-      updated = existing.replace(/(\n## Key Files Modified)/, `\n${agentSection}$1`);
-      if (updated === existing) updated = existing.trimEnd() + '\n' + agentSection;
-    } else {
-      updated = buildStateContent(extractSessionData(data)) + '\n' + agentSection;
-    }
-    writeAtomic(file, updated);
-    process.exit(0);
+    const content = mergeAgentSections(existing, buildStateContent(data));
+    writeAtomic(file, content);
+    if (options.archive) archive(dir);
   }
 
-  // Stop: persist full state
-  if (event === 'Stop' && dir) {
-    const file    = path.join(dir, 'latest.md');
-    const sessionData = extractSessionData(data);
-    let content = buildStateContent(sessionData);
-
-    // Preserve agent sections from SubagentStop
-    if (fs.existsSync(file)) {
-      const existing = fs.readFileSync(file, 'utf8');
-      const agentMatches = existing.match(/## Agent Result:.+?(?=\n## |$)/gs);
-      if (agentMatches) {
-        content = content.replace(
-          /(\n## Key Files Modified)/,
-          `\n${agentMatches.join('\n')}$1`
-        );
+  async function main() {
+    const stdin = fs.readFileSync(0, 'utf8').trim();
+    if (!stdin) process.exit(0);
+
+    const data = JSON.parse(stdin);
+    const event = data.hook_event_name || '';
+    const cwd = data.cwd || process.cwd();
+    const dir = stateDir(cwd);
+
+    if (event === 'SessionStart') {
+      const previous = loadLatest(cwd);
+      if (previous) {
+        console.log('\n=== Prior Execution Context ===');
+        console.log(previous.trim());
+        console.log('=== End of Prior Context ===\n');
       }
+      process.exit(0);
+    }
+
+    if (!dir) process.exit(0);
+
+    if (event === 'PostToolUse') {
+      const toolName = data.tool_name || '';
+      if (TRACKED_POST_TOOL_EVENTS.has(toolName)) {
+        const sessionData = await extractSessionData(data);
+        await persistSnapshot(dir, sessionData);
+      }
+      process.exit(0);
+    }
+
+    if (event === 'SubagentStop') {
+      const file = path.join(dir, 'latest.md');
+      const agentSection = buildAgentSection(data);
+      const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+      const updated = existing
+        ? appendAgentSection(existing, agentSection)
+        : `${buildStateContent(await extractSessionData(data))}\n${agentSection}`;
+
+      writeAtomic(file, updated);
+      process.exit(0);
+    }
+
+    if (event === 'Stop') {
+      const sessionData = await extractSessionData(data);
+      await persistSnapshot(dir, sessionData, { archive: true });
+      process.exit(0);
     }
 
-    writeAtomic(file, content);
-    archive(dir);
     process.exit(0);
   }
 
-  process.exit(0);
-
-} catch (e) {
+  main().catch(() => {
+    process.exit(0);
+  });
+} catch (error) {
   try {
-    const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
-    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
-      JSON.stringify({ ts: new Date().toISOString(), hook: 'state', status: 'crash', error: e.message }) + '\n');
+    const fs = require('fs');
+    const path = require('path');
+    const logDir = path.join(__dirname, '.logs');
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    fs.appendFileSync(
+      path.join(logDir, 'hook-log.jsonl'),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: 'state',
+        status: 'crash',
+        error: error.message
+      }) + '\n'
+    );
   } catch (_) {}
   process.exit(0);
 }

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

@@ -22,6 +22,7 @@ The project maintains these core documents in `./docs`:
 The `hapo:docs-keeper` agent is responsible for keeping these documents current. Trigger an update whenever:
 
 - A development phase transitions (e.g., "In Progress" → "Complete")
+- A verified task completion changes user-facing behavior, architecture, API contracts, operational flow, or project status enough that docs should be refreshed
 - A significant feature ships or a critical bug is resolved
 - Security patches are applied or dependencies change
 - Project scope or timeline shifts
@@ -67,8 +68,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 +82,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/settings/settings.json

@@ -56,7 +56,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Read|Write|Edit|MultiEdit|Bash|Glob",
+        "matcher": "Read|Write|Edit|MultiEdit|Bash|Glob|Grep",
         "hooks": [
           {
             "type": "command",
@@ -70,6 +70,15 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Task|TaskCreate|TaskUpdate|TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write|MultiEdit",
         "hooks": [

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

@@ -4,9 +4,9 @@ description: "Code execution engine: Reads specs and implements code end-to-end
 argument-hint: "[feature-name|specs-directory-path]"
 ---
 
-# Develop — Feature Implementation (Full Build)
+# Develop — Feature Implementation (Task-Orchestrated Build)
 
-Reads the full project specification (`hapo:specs`) and relentlessly implements code from A to Z in a disciplined, single-track workflow. Automatically overcomes obstacles and only escalates to the user when facing persistent critical failures.
+Reads the project specification (`hapo:specs`) and implements code through a disciplined task loop. In specific-task mode it behaves like a surgical executor. In full-spec mode it behaves like a sequential orchestrator, processing one unblocked task at a time and syncing state after every verified task.
 
 **Principles:** YAGNI, KISS, DRY | Continuous execution | Smart self-healing
 
@@ -18,6 +18,26 @@ Reads the full project specification (`hapo:specs`) and relentlessly implements
 /hapo:develop <feature name> <specific-task-file.md>
 ```
 
+## Execution Modes
+
+### 1. Specific-Task Mode
+Triggered by `/hapo:develop <feature> <task-file>`.
+
+- Load exactly one task file.
+- Implement only that task packet.
+- STOP immediately after the task is verified and synchronized.
+- Never auto-chain into the next task.
+
+### 2. Full-Spec Mode
+Triggered by `/hapo:develop <feature>` or `/hapo:develop specs/<feature>`.
+
+- Build a queue from `spec.json.task_registry`.
+- Select the next `pending` + unblocked task only.
+- Run the full implementation cycle for that single task.
+- Sync state.
+- Recompute the queue and continue.
+- STOP the overall run on the first blocked task, unresolved gate failure, or missing proof.
+
 <HARD-GATE>
 DO NOT write implementation code until an approved spec exists.
 - If the directory `specs/<feature-name>` DOES NOT EXIST or `spec.json` is not ready, automatically trigger `/hapo:specs <feature-name>` first to create the specification. Do not improvise.
@@ -52,17 +72,20 @@ 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`.
+  - If no specific task is mentioned, DO NOT load all tasks into working memory. Resolve the next single unblocked `pending` task from `task_registry` and load only that task packet.
 - **Task Packet Extraction (MANDATORY):** Before coding, extract from the active task file(s):
   - Objective + Constraints
   - Related Files
   - Completion Criteria
   - Verification & Evidence
+  - Exact executable verification commands named in the task
   - 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.
@@ -71,7 +94,13 @@ flowchart TD
 - Act as `god-developer` OR directly write code, executing tasks specified in the loaded Markdown file(s) sequentially.
 - **Important:** You may create and modify files directly, but must faithfully follow the design from the Spec.
 - Progress tracking: Temporarily change `[ ]` to `[/]` in Spec files while coding is in progress. Do NOT mark `[x]` before Step 4 passes.
+- **Task Boundary Protocol (CRITICAL):**
+  - Default editable scope is `Related Files` from the task packet.
+  - You may additionally touch direct test files plus minimal support files required to make the current task executable (shared types, exports, config glue, generated migration wiring).
+  - If you must edit a file outside this scope, explicitly treat it as a `scope escape` and justify why it is required for the current task.
+  - If the out-of-scope change would deliver functionality clearly assigned to a later task, STOP instead of implementing it early.
 - **Hard Stop Protocol:** If you were asked to implement a specific task file, you MUST STOP completely after that task is verified. DO NOT auto-chain or jump to "Next Task" simply because you see it in the spec. Wait for the user's next command.
+- **Full-Spec Loop Protocol:** If you were asked to implement the whole feature, you MUST still work one task at a time. Finish Step 4 and Step 5 for the current task before selecting the next unblocked task from `task_registry`.
 - **Test Integrity Protocol:** You MUST NOT delete, replace, or reduce the scope of existing test cases to make tests pass. If a test fails, you must fix the **implementation code** or fix the **test setup/mock**, NOT remove the assertion. Reducing test count or weakening assertions (e.g., removing `toHaveBeenCalledWith` and replacing with `toEqual(expect.any(...))`) is a Critical violation.
 - **Contract Integrity Protocol:** If implementation appears to require changing auth/session, transport, persistence, entrypoint wiring, or generated artifact behavior beyond what `design.md` states, STOP and route back to spec correction instead of inventing a new contract in code.
 
@@ -80,19 +109,32 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
 **Mantra:** All feedback from code-auditor must be addressed thoroughly: Score >= 9.5 & Zero Critical issues.
 
 - Passing Step 4 requires ALL of the following:
-  1. Automated verification passes (typecheck/test/build as applicable)
+  1. Automated verification passes, including every exact command named in the task's `Verification & Evidence` section
   2. Code review passes
   3. Task evidence passes (artifacts/runtime surfaces/negative-path checks from the task file are proven)
+- `NO_TESTS` is NOT equivalent to PASS. If the task explicitly requires a test command or automated test proof, `NO_TESTS` is a FAIL or BLOCKED outcome until the requirement is satisfied or the spec is corrected.
 - If build/test passes but task evidence is missing, the task is still FAIL.
 - 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.
+### Step 5: State Sync + Task-Level Docs Sync
+- 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.
-- 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.
+- 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`
+  - a human-readable verification receipt inside the task's `Verification & Evidence` section showing which commands ran and what proof was observed
+- After syncing the active task, run a **Task Closeout Docs Checkpoint**
+- Task Closeout Docs Checkpoint:
+  - Evaluate `Docs impact: none | minor | major` based on real behavior changes from the just-completed task
+  - If `none`: record that explicitly in the completion report and stop
+  - If `minor` or `major`: trigger `docs-keeper` to surgically update affected existing docs under `./docs`
+  - Default to **lightweight docs sync**: update only the docs touched by this task and its verified behavior; do NOT run `repomix` unless `docs-keeper` truly cannot verify the required architecture/context from the code, spec, and current docs
 - **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.
-- Do NOT skip this step! The user explicitly requires documentation to be synced immediately after every `/hapo:develop` action, overriding the default Phase 3-only rule.
+- Task-level docs sync happens after every verified completed task, but actual edits still depend on `Docs impact`.
+- In **Specific-Task Mode**, STOP after sync and report the result.
+- In **Full-Spec Mode**, only after sync may you re-read `task_registry`, pick the next unblocked pending task, and repeat from Step 1 for that task.
 
 ---
 ## Attached References