@haposoft/cafekit 0.14.1 → 0.14.2

package/src/claude/hooks/__tests__/privacy-block.test.js

@@ -1,8 +1,7 @@
 'use strict';
 
 // Behavioral tests for privacy-block.cjs. The hook is run as a real subprocess:
-// a PreToolUse payload is piped to stdin and the exit code is asserted
-// (0 = allow, 2 = block). Covers the symlink-bypass hardening.
+// a PreToolUse payload is piped to stdin and native permission output asserted.
 
 const { test } = require('node:test');
 const assert = require('node:assert');
@@ -13,40 +12,47 @@ const path = require('node:path');
 
 const HOOK = path.join(__dirname, '..', 'privacy-block.cjs');
 
-/** Run the hook with a tool payload; return { code, stderr }. */
+/** Run the hook with a tool payload; return process output. */
 function runHook(payload, cwd) {
   const res = spawnSync(process.execPath, [HOOK], {
     input: JSON.stringify({ ...payload, cwd: cwd || payload.cwd }),
     encoding: 'utf8',
   });
-  return { code: res.status, stderr: res.stderr || '' };
+  return { code: res.status, stdout: res.stdout || '', stderr: res.stderr || '' };
 }
 
 function tmpDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'ck-privacy-'));
 }
 
-test('blocks a direct Read of .env (exit 2)', () => {
+function permissionDecision(stdout) {
+  if (!stdout.trim()) return null;
+  return JSON.parse(stdout).hookSpecificOutput?.permissionDecision || null;
+}
+
+test('asks natively for a direct Read of .env', () => {
   const dir = tmpDir();
   try {
     const env = path.join(dir, '.env');
     fs.writeFileSync(env, 'SECRET=1');
-    const { code } = runHook({ tool_name: 'Read', tool_input: { file_path: env } }, dir);
-    assert.strictEqual(code, 2);
+    const { code, stdout } = runHook({ tool_name: 'Read', tool_input: { file_path: env } }, dir);
+    assert.strictEqual(code, 0);
+    assert.strictEqual(permissionDecision(stdout), 'ask');
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test('blocks a symlink whose target is .env (regression: symlink bypass)', () => {
+test('asks for a symlink whose target is .env (regression: symlink bypass)', () => {
   const dir = tmpDir();
   try {
     const env = path.join(dir, '.env');
     fs.writeFileSync(env, 'SECRET=1');
     const link = path.join(dir, 'notes.txt'); // harmless-looking name
     fs.symlinkSync(env, link);
-    const { code } = runHook({ tool_name: 'Read', tool_input: { file_path: link } }, dir);
-    assert.strictEqual(code, 2, 'symlink to .env must be blocked, not allowed');
+    const { code, stdout } = runHook({ tool_name: 'Read', tool_input: { file_path: link } }, dir);
+    assert.strictEqual(code, 0);
+    assert.strictEqual(permissionDecision(stdout), 'ask');
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -77,3 +83,37 @@ test('allows a symlink to an exempt .env.example (exemption still wins)', () =>
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('an exempt-looking symlink to .env still asks based on its target', () => {
+  const dir = tmpDir();
+  try {
+    const env = path.join(dir, '.env');
+    fs.writeFileSync(env, 'SECRET=1');
+    const link = path.join(dir, '.env.example');
+    fs.symlinkSync(env, link);
+    const { stdout } = runHook({ tool_name: 'Read', tool_input: { file_path: link } }, dir);
+    assert.strictEqual(permissionDecision(stdout), 'ask');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+for (const command of [
+  'cat ".env"',
+  'cat .env',
+  'cat .env*',
+  'sed -n 1p .env',
+  "bash -c 'sed -n 1p .env'",
+]) {
+  test(`asks natively for Bash sensitive reference: ${command}`, () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, '.env'), 'SECRET=1');
+      const { code, stdout } = runHook({ tool_name: 'Bash', tool_input: { command } }, dir);
+      assert.strictEqual(code, 0);
+      assert.strictEqual(permissionDecision(stdout), 'ask');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+}

package/src/claude/hooks/__tests__/spec-gate.test.js

@@ -64,7 +64,7 @@ function readCache() {
  * @param {string} [opts.taskStatus='done']
  * @param {string|null} [opts.completed_at='2026-07-01T00:00:00Z']
  * @param {string} [opts.mdStatus='done']
- * @param {'valid'|'missing-evidence'|'placeholder'|'none'} [opts.evidence='valid']
+ * @param {'valid'|'legacy-valid'|'failed'|'fence-only'|'missing-evidence'|'placeholder'|'none'} [opts.evidence='valid']
  * @param {object|null} [opts.runtime] — if set, write .claude/runtime.json
  */
 function makeFixture(opts = {}) {
@@ -97,12 +97,19 @@ function makeFixture(opts = {}) {
     evidenceBlock = [
       '## Evidence',
       '',
+      'Verification: PASS',
       '```',
       'npm test',
       'PASS: 10 tests',
       '```',
       '',
     ].join('\n');
+  } else if (evidence === 'legacy-valid') {
+    evidenceBlock = '## Evidence\n\nnpm test — passed, exit code 0\n';
+  } else if (evidence === 'failed') {
+    evidenceBlock = '## Evidence\n\nVerification: PASS\n\nFAIL: tests failed, exit code 1\n';
+  } else if (evidence === 'fence-only') {
+    evidenceBlock = '## Evidence\n\n```\nnpm test\n```\n';
   } else if (evidence === 'placeholder') {
     evidenceBlock = [
       '## Evidence',
@@ -268,3 +275,70 @@ test('7. Evidence with {{...}} placeholder → blocked (check c)', () => {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('8. explicit failure cannot pass even when PASS text is present', () => {
+  const dir = makeFixture({ evidence: 'failed' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body);
+    assert.match(body.reason, /\bc\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('9. a code fence alone is not verification proof', () => {
+  const dir = makeFixture({ evidence: 'fence-only' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    assert.ok(parseBlock(runHook({}, dir).stdout));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('10. completed_at must be a valid ISO timestamp', () => {
+  const dir = makeFixture({ completed_at: 'yesterday' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body);
+    assert.match(body.reason, /\bd\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('11. done → pending cache transition is persisted and can be gated again', () => {
+  const dir = makeFixture({ taskStatus: 'pending', mdStatus: 'pending' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'done' } });
+    assert.strictEqual(runHook({}, dir).stdout, '');
+    assert.strictEqual(readCache()[FEATURE][TASK_REL], 'pending');
+
+    const specFile = path.join(dir, 'specs', FEATURE, 'spec.json');
+    const spec = JSON.parse(fs.readFileSync(specFile, 'utf8'));
+    spec.task_registry[TASK_REL] = {
+      status: 'done',
+      completed_at: '2026-07-01T00:00:00Z',
+    };
+    fs.writeFileSync(specFile, JSON.stringify(spec));
+    const taskFile = path.join(dir, 'specs', FEATURE, TASK_REL);
+    fs.writeFileSync(taskFile, '# Task\n\n**Status:** done\n\n## Evidence\n\nFAIL: tests failed\n');
+
+    assert.ok(parseBlock(runHook({}, dir).stdout), 're-completed failing task must be gated');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('12. legacy successful receipt remains read-compatible', () => {
+  const dir = makeFixture({ evidence: 'legacy-valid' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    assert.strictEqual(runHook({}, dir).stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/__tests__/state.test.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const HOOK = path.join(__dirname, '..', 'state.cjs');
+
+test('Stop snapshot includes tracked modifications and untracked files', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-state-'));
+  try {
+    fs.mkdirSync(path.join(dir, '.claude'));
+    spawnSync('git', ['init', '-q'], { cwd: dir });
+    spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd: dir });
+    spawnSync('git', ['config', 'user.name', 'Test'], { cwd: dir });
+    fs.writeFileSync(path.join(dir, 'tracked.txt'), 'before\n');
+    spawnSync('git', ['add', 'tracked.txt'], { cwd: dir });
+    spawnSync('git', ['commit', '-qm', 'initial'], { cwd: dir });
+
+    fs.writeFileSync(path.join(dir, 'tracked.txt'), 'after\n');
+    fs.writeFileSync(path.join(dir, 'new-untracked.json'), '{}\n');
+    const result = spawnSync(process.execPath, [HOOK], {
+      cwd: dir,
+      input: JSON.stringify({ hook_event_name: 'Stop', cwd: dir }),
+      encoding: 'utf8',
+    });
+
+    assert.strictEqual(result.status, 0);
+    const state = fs.readFileSync(
+      path.join(dir, '.claude', 'session-state', 'latest.md'),
+      'utf8',
+    );
+    assert.match(state, /- tracked\.txt/);
+    assert.match(state, /- new-untracked\.json/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('Stop snapshot includes untracked files before the first commit', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-state-no-head-'));
+  try {
+    fs.mkdirSync(path.join(dir, '.claude'));
+    spawnSync('git', ['init', '-q'], { cwd: dir });
+    fs.writeFileSync(path.join(dir, 'first-untracked.txt'), 'new\n');
+
+    const result = spawnSync(process.execPath, [HOOK], {
+      cwd: dir,
+      input: JSON.stringify({ hook_event_name: 'Stop', cwd: dir }),
+      encoding: 'utf8',
+    });
+
+    assert.strictEqual(result.status, 0);
+    const state = fs.readFileSync(
+      path.join(dir, '.claude', 'session-state', 'latest.md'),
+      'utf8',
+    );
+    assert.match(state, /- first-untracked\.txt/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/docs-sync.cjs

@@ -39,24 +39,20 @@ try {
 
   const lines = [];
 
-  // Trường hợp 1: Có Code nhưng chưa có thư mục docs
+  // Case 1: source present but docs/ missing
   if (!fs.existsSync(docsDir)) {
     lines.push('');
-    lines.push('### 🔴 URGENT SYSTEM ACTION: MISSING DOCUMENTATION 🔴');
-    lines.push(`> BẮT BUỘC (MANDATORY): Hệ thống phát hiện dự án đã có Source Code nhưng thư mục \`docs/\` chưa tồn tại.`);
-    lines.push(`> Nhiệm vụ ĐẦU TIÊN của bạn trong session này là đọc hiểu mã nguồn hiện tại và tạo ra các tài liệu tiêu chuẩn:`);
-    lines.push(`> 1. \`docs/system-architecture.md\` (Kiến trúc hệ thống, phân tích flow)`);
-    lines.push(`> 2. \`docs/project-overview-pdr.md\` (Tổng quan, mục tiêu, tính năng)`);
-    lines.push(`> 3. Khởi tạo file hidden \`docs/.sync_hash\` để theo dõi cập nhật.`);
-    lines.push(`> `);
-    lines.push(`> LƯU Ý BẮT BUỘC: Bạn phải chạy lệnh Git này trong Terminal để lấy Hash Code mới nhất: \`git log -1 --format="%H" -- . ":(exclude)docs"\``);
-    lines.push(`> Sau đó ghi chuẩn giá trị Hash đó vào file \`docs/.sync_hash\`.`);
+    lines.push('### Missing docs/');
+    lines.push('> Source exists but `docs/` does not. Create baseline docs first:');
+    lines.push('> 1. `docs/system-architecture.md` — system architecture and flows');
+    lines.push('> 2. `docs/project-overview-pdr.md` — overview, goals, features');
+    lines.push('> 3. Write current hash to `docs/.sync_hash` via `git log -1 --format="%H" -- . ":(exclude)docs"`');
     lines.push('');
-  } 
-  // Trường hợp 2: Có Code, đã có Docs. Kiểm tra Continuous Sync
+  }
+  // Case 2: docs exist — check continuous sync vs source-only git hash
   else {
     try {
-      // Lấy hash của lần thay đổi SOURCE CODE gần nhất (Bỏ qua những commit chỉ sửa docs)
+      // Latest SOURCE-only hash (ignore docs-only commits)
       const currentHash = execSync('git log -1 --format="%H" -- . ":(exclude)docs"', { 
         cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] 
       }).trim();
@@ -69,18 +65,16 @@ try {
 
         if (lastSyncHash !== currentHash) {
           lines.push('');
-          lines.push('### 🔄 CONTINUOUS DOCS SYNC REQUIRED 🔄');
-          lines.push(`> Source Code vừa có sự thay đổi mới (Git Hash: \`${currentHash}\`) kể từ lần đồng bộ Docs cuối cùng (\`${lastSyncHash || 'Chưa gán'}\`).`);
-          lines.push(`> YÊU CẦU TRƯỚC KHI LÀM THÊM TÍNH NĂNG:`);
-          lines.push(`> 1. Rà soát file bị thay đổi gần đây (dùng \`git diff ${lastSyncHash} ${currentHash}\` hoặc \`git log\`).`);
-          lines.push(`> 2. Cập nhật lại \`docs/system-architecture.md\` hoặc các chuẩn code nếu cần thiết.`);
-          lines.push(`> 3. Cập nhật Changelog (nhật ký thay đổi).`);
-          lines.push(`> 4. KHI HOÀN TẤT, BẠN PHẢI GHI ĐÈ GIÁ TRỊ SAU: \`${currentHash}\` VÀO FILE \`docs/.sync_hash\` ĐỂ CHỐT TRẠNG THÁI HIỆN TẠI.`);
+          lines.push('### Docs sync needed');
+          lines.push(`> Source changed (\`${currentHash}\`) since last docs sync (\`${lastSyncHash || 'none'}\`).`);
+          lines.push(`> 1. Review recent changes (\`git diff ${lastSyncHash} ${currentHash}\` or \`git log\`).`);
+          lines.push('> 2. Update architecture/code-standards docs and changelog as needed.');
+          lines.push(`> 3. Write \`${currentHash}\` to \`docs/.sync_hash\` when done.`);
           lines.push('');
         }
       }
     } catch (e) {
-      // Git chưa init hoặc chưa có commit nào thì im lặng fail-open
+      // Git not initialized or no commits — fail-open
     }
   }
 

package/src/claude/hooks/inspect-block.cjs

@@ -21,7 +21,7 @@ try {
   // Directories that should never be read (too large / irrelevant to LLM)
   const BLOCKED_DIRS = [
     'node_modules', 'dist', 'build', '.next', '.nuxt', '.output',
-    '__pycache__', '.venv', 'venv', '.env',
+    '__pycache__', '.venv', 'venv',
     'vendor', 'target',
     '.git', 'coverage', '.nyc_output',
   ];

package/src/claude/hooks/lib/config.cjs

@@ -52,11 +52,6 @@ const DEFAULT_CONFIG = {
     packageManager: 'auto',
     framework: 'auto'
   },
-  skills: {
-    research: {
-      useGemini: true  // Toggle Gemini CLI usage in research skill
-    }
-  },
   assertions: [],
   statusline: 'full',
   statuslineColors: true,

package/src/claude/hooks/privacy-block.cjs

@@ -7,12 +7,11 @@
  * Claude Code CLI privacy gate for sensitive files.
  *
  * Runtime contract:
- * - Non-bash file access to sensitive files is blocked with a JSON marker
- * - Assistant must use AskUserQuestion with that JSON payload
- * - If user approves, assistant should read via `bash cat "file"`
- * - Bash access is allowed with a warning to enable the approved follow-up path
+ * - Sensitive access returns Claude Code's native PreToolUse "ask" decision
+ * - The same decision applies to direct tools and Bash commands
+ * - Symlinks are classified by their resolved target before their alias
  *
- * Exit: 0 = allow, 2 = block
+ * Exit: 0 (the JSON hook output carries the permission decision)
  */
 
 try {
@@ -20,7 +19,7 @@ try {
   const path = require('path');
 
   const RESTRICTED_PATTERNS = [
-    /^\.env(\.|$)/i,
+    /^\.env(?:[.\[*?{]|$)/i,
     /^credentials/i,
     /secrets?\.(ya?ml|json)$/i,
     /\.pem$/i,
@@ -66,22 +65,28 @@ try {
    * when the path cannot be resolved (missing file, broken link) — fail-open to
    * the original-path check in that case.
    */
-  function resolveTarget(filePath) {
+  function resolveTarget(filePath, cwd) {
     try {
-      return fs.realpathSync(filePath);
+      const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+      return fs.realpathSync(requested);
     } catch {
       return null;
     }
   }
 
   function extractBashPaths(command) {
-    const paths = [];
-    const regex = /(?:cat|less|more|head|tail|source|\.)\s+(?:"([^"]+)"|'([^']+)'|([^\s]+))/g;
-    let match;
-    while ((match = regex.exec(command)) !== null) {
-      paths.push(match[1] || match[2] || match[3]);
+    const paths = new Set();
+    // Quotes are delimiters rather than grouped tokens so nested shell
+    // commands such as `bash -c 'cat .env'` cannot hide the sensitive path.
+    const tokens = command.split(/[\s|;&<>"']+/).filter(Boolean);
+    for (const token of tokens) {
+      const cleaned = token.replace(/^["'()`]+|["'(),]+$/g, '');
+      for (const candidate of cleaned.split('=')) {
+        const value = candidate.replace(/^["'()`]+|["'(),]+$/g, '');
+        if (value && (isSensitive(value) || isSafe(value))) paths.add(value);
+      }
     }
-    return paths;
+    return [...paths];
   }
 
   function extractPaths(toolName, input) {
@@ -107,42 +112,15 @@ try {
     return paths.filter(Boolean);
   }
 
-  function formatBlockMessage(filePath) {
+  function askForPermission(filePath) {
     const basename = path.basename(filePath);
-    const promptData = {
-      type: 'PRIVACY_PROMPT',
-      file: filePath,
-      basename,
-      question: {
-        header: 'File Access',
-        text: `I need to read "${basename}" which may contain sensitive data (API keys, passwords, tokens). Do you approve?`,
-        options: [
-          {
-            label: 'Yes, approve access',
-            description: `Allow reading ${basename} this time`
-          },
-          {
-            label: 'No, skip this file',
-            description: 'Continue without accessing this file'
-          }
-        ]
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'ask',
+        permissionDecisionReason: `Sensitive file access requires approval: ${basename}`
       }
-    };
-
-    return [
-      'NOTE: This is not an error. This block protects sensitive data.',
-      '',
-      `PRIVACY BLOCK: Sensitive file access requires user approval`,
-      `File: ${filePath}`,
-      '',
-      '@@PRIVACY_PROMPT_START@@',
-      JSON.stringify(promptData, null, 2),
-      '@@PRIVACY_PROMPT_END@@',
-      '',
-      'Claude Code follow-up:',
-      `- If approved: use bash to read: cat "${filePath}"`,
-      '- If denied: continue without this file'
-    ].join('\n');
+    }) + '\n');
   }
 
   const stdin = fs.readFileSync(0, 'utf8').trim();
@@ -160,22 +138,21 @@ try {
   if (!paths.length) process.exit(0);
 
   for (const filePath of paths) {
-    // Check the requested path and, when it is a symlink, its real target.
-    const target = resolveTarget(filePath);
-    const candidates = target && target !== filePath ? [filePath, target] : [filePath];
-
-    // An exemption on either name wins (e.g. a symlink to .env.example).
-    if (candidates.some(isSafe)) continue;
-    // Sensitive if the requested path OR its symlink target is sensitive.
-    if (!candidates.some(isSensitive)) continue;
-
-    if (toolName === 'Bash') {
-      console.error(`WARN: Privacy-sensitive file access via bash allowed for approved follow-up: ${path.basename(filePath)}`);
-      process.exit(0);
+    const target = resolveTarget(filePath, cwd);
+
+    // The real target is authoritative: an exempt-looking alias must not hide
+    // a sensitive target, while a real .env.example target remains safe.
+    if (target) {
+      if (isSensitive(target) && !isSafe(target)) {
+        askForPermission(filePath);
+        process.exit(0);
+      }
+      if (isSafe(target)) continue;
     }
 
-    console.error(formatBlockMessage(filePath));
-    process.exit(2);
+    if (isSafe(filePath) || !isSensitive(filePath)) continue;
+    askForPermission(filePath);
+    process.exit(0);
   }
 
   process.exit(0);

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

@@ -84,11 +84,12 @@ try {
   const newlyDone = Object.keys(taskRegistry).filter((tp) =>
     (taskRegistry[tp]?.status || 'pending') === 'done' && featureCache[tp] !== 'done'
   );
-  if (newlyDone.length === 0) process.exit(0);
-
   // /m so ^ matches line starts (Evidence is never at byte 0 of the file).
+  // legacy heading aliases: read-compat only, no longer advertised
   const EVID_RE = /^#{2,3}\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/m;
-  const PROOF_RE = /(PASS|FAIL|exit code|passed|✓)/;
+  const PASS_MARKER_RE = /^\s*Verification:\s*PASS\s*$/m;
+  const LEGACY_SUCCESS_RE = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
+  const EXPLICIT_FAILURE_RE = /\bFAIL(?:ED|URE|URES|ING)?\b|tests?\s+failed|exit\s+code\s*[:=]?\s*[1-9]\d*|\b0\s+tests?\b/i;
 
   /** Body of first Evidence heading until next same-or-higher heading. */
   function evidenceBody(text) {
@@ -122,12 +123,20 @@ try {
     const body = evidenceBody(text);
     if (body === null || !EVID_RE.test(text)) {
       fails.push('b');
-    } else if (/\{\{[^}]+\}\}/.test(body) || !(/```/.test(body) || PROOF_RE.test(body))) {
+    } else if (
+      /\{\{[^}]+\}\}/.test(body) ||
+      EXPLICIT_FAILURE_RE.test(body) ||
+      !(PASS_MARKER_RE.test(body) || LEGACY_SUCCESS_RE.test(body))
+    ) {
       fails.push('c');
     }
 
     const at = taskRegistry[taskPath]?.completed_at;
-    if (typeof at !== 'string' || at.trim() === '') fails.push('d');
+    if (
+      typeof at !== 'string' ||
+      !/^\d{4}-\d{2}-\d{2}T/.test(at) ||
+      Number.isNaN(Date.parse(at))
+    ) fails.push('d');
     return fails;
   }
 
@@ -135,7 +144,8 @@ try {
     .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
     .filter((f) => f.fails.length > 0);
 
-  // Leave failing newly-done at old cache status so the gate re-fires next Stop.
+  // Always persist status transitions, including done → pending. Leave failing
+  // newly-done tasks at their old status so the gate re-fires next Stop.
   try {
     const nextFeature = { ...featureCache, ...currentStatuses };
     for (const { taskPath } of failures) {
@@ -147,6 +157,7 @@ try {
     fs.writeFileSync(cacheFile, JSON.stringify(cache));
   } catch { /* fail-open */ }
 
+  if (newlyDone.length === 0) process.exit(0);
   if (failures.length === 0) process.exit(0);
 
   const lines = [
@@ -155,7 +166,7 @@ try {
   for (const { taskPath, fails } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
     lines.push(
-      `  Fix: add a verification receipt to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`: commands run + outcomes, then re-sync spec.json`
+      `  Fix: add \`Verification: PASS\` plus commands and successful outcomes to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`, then re-sync spec.json`
     );
   }
   process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');

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

@@ -30,6 +30,10 @@ try {
     if (fs.existsSync(p)) runtime = JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch { /* ignore */ }
 
+  // Reminder toggle — same key the OpenCode spec-state plugin honors.
+  // (The Stop completion gate has its own toggle: spec.completion_gate.)
+  if (runtime.spec && runtime.spec.tollgate === false) process.exit(0);
+
   const baseDir   = process.env.PROJECT_ROOT || cwd;
   const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
 

package/src/claude/hooks/state.cjs

@@ -120,19 +120,29 @@ try {
       }
     }
 
+    const changed = [];
     try {
       const diff = execSync('git diff --name-only HEAD', {
         encoding: 'utf8',
         timeout: 3000,
         stdio: ['pipe', 'pipe', 'pipe']
       }).trim();
+      if (diff) changed.push(...diff.split('\n'));
+    } catch {
+      // A repository without HEAD can still report untracked files below.
+    }
 
-      if (diff) {
-        data.modifiedFiles = diff.split('\n').slice(0, MAX_MODIFIED_FILES_DISPLAY);
-      }
+    try {
+      const untracked = execSync('git ls-files --others --exclude-standard', {
+        encoding: 'utf8',
+        timeout: 3000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      if (untracked) changed.push(...untracked.split('\n'));
     } catch {
       // fail-open
     }
+    data.modifiedFiles = [...new Set(changed)].slice(0, MAX_MODIFIED_FILES_DISPLAY);
 
     return data;
   }

package/src/claude/hooks/usage.cjs

@@ -8,6 +8,12 @@
  * Fetches Claude Code usage limits from Anthropic OAuth API and writes to cache.
  * Cache is read by status.cjs for statusline display.
  *
+ * ⚠ EXPERIMENTAL / UNDOCUMENTED API: api.anthropic.com/api/oauth/usage with the
+ * "oauth-2025-04-20" beta header is not a public contract and may break or
+ * change shape without notice. Every failure path degrades to
+ * status:"unavailable" (statusline hides the segment) — never block on it.
+ * Disable entirely with "usage": { "enabled": false } if it misbehaves.
+ *
  * Features:
  * - Cross-platform credential retrieval (macOS Keychain, file-based)
  * - Throttled API calls: 1 min (prompt) / 5 min (tool use)

package/src/claude/rules/orchestrator.md

@@ -23,7 +23,7 @@ Example prompt:
 ## Resource Constraints
 
 - Each subagent has a **200K token context window** — scope tasks to fit comfortably within it
-- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out
+- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out. For parallel implementation waves the cap is 3 concurrent agents by default, never more than 5 (each agent carries the 200K budget above)
 - Prefer fewer, well-scoped agents over many overlapping ones
 - Include system resource info (from hook injection) when delegating tasks so subagents can self-regulate
 
@@ -48,7 +48,7 @@ For implementation tasks, keep the chain explicit:
 2. Verify with `test-runner` using task files and exact evidence commands.
 3. Review with `code-auditor` using task files, design contracts, and the diff.
 
-Do not dispatch multiple implementation agents against the same files or same task. Parallelize only independent scopes with distinct file ownership.
+Do not dispatch multiple implementation agents against the same files or same task **within the same working tree**. Parallelize only independent scopes with distinct file ownership — the sanctioned pattern for parallel implementation is **worktree isolation** (one agent per task, each in its own git worktree) with a **single writer per file per wave** and orchestrator-only spec-state writes, per `skills/develop/references/parallel-waves.md`.
 
 ### Parallel (independent tasks)