@haposoft/cafekit 0.14.1 → 0.15.0

package/bin/phases/select-platform.js

@@ -22,30 +22,39 @@ const OTHER = '__other__';
  * Read saved locale label from .claude/runtime.json (written by post-install).
  * Returns the freeform label string (e.g. "Tiếng Việt") or null.
  */
-function getInstalledLocale() {
-  const runtimeJson = path.join(process.cwd(), '.claude', 'runtime.json');
-  if (!fs.existsSync(runtimeJson)) return null;
-  try {
-    const data = JSON.parse(fs.readFileSync(runtimeJson, 'utf8'));
-    return (data && data.locale && typeof data.locale.responseLanguage === 'string')
-      ? data.locale.responseLanguage
-      : null;
-  } catch { return null; }
+function getInstalledLocale(platformKeys = getPlatformKeys()) {
+  for (const key of platformKeys) {
+    const runtimeJson = path.join(process.cwd(), PLATFORMS[key].folder, 'runtime.json');
+    if (!fs.existsSync(runtimeJson)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(runtimeJson, 'utf8'));
+      if (data && data.locale && typeof data.locale.responseLanguage === 'string') {
+        return data.locale.responseLanguage;
+      }
+    } catch { /* try the next installed runtime */ }
+  }
+  return null;
 }
 
 /** First step: pick the installer/UI language (interactive only). */
 async function selectLanguage(ctx) {
-  if (!ctx.interactive || ctx.options.lang) return ctx;
-
-  // If already installed, restore saved locale and skip the prompt
-  const savedLocale = getInstalledLocale();
-  if (savedLocale) {
-    const code = Object.keys(LANGUAGE_LABELS).find((k) => LANGUAGE_LABELS[k] === savedLocale) || 'en';
-    ctx.setLang(code, savedLocale); // updates ctx.t to the saved language
-    ctx.ui.info(ctx.t('langKept', { lang: savedLocale }));
-    return ctx;
+  // Restore the saved locale BEFORE the interactivity check: a non-interactive
+  // upgrade (--yes) must not forget the configured language. Skipping this left
+  // ctx at the 'en' default, and patchRuntimeLocale then clobbered the user's
+  // responseLanguage on every upgrade.
+  if (!ctx.options.lang) {
+    const requested = (ctx.options.platforms || []).filter((key) => PLATFORMS[key]);
+    const savedLocale = getInstalledLocale(requested.length ? requested : getPlatformKeys());
+    if (savedLocale) {
+      const code = Object.keys(LANGUAGE_LABELS).find((k) => LANGUAGE_LABELS[k] === savedLocale) || 'en';
+      ctx.setLang(code, savedLocale); // updates ctx.t to the saved language
+      if (ctx.interactive) ctx.ui.info(ctx.t('langKept', { lang: savedLocale }));
+      return ctx;
+    }
   }
 
+  if (!ctx.interactive || ctx.options.lang) return ctx;
+
   const options = [
     ...SUPPORTED.map((code) => ({ value: code, label: LANGUAGE_LABELS[code] })),
     { value: OTHER, label: OTHER_LABEL.en + ' / その他 / Ngôn ngữ khác' }
@@ -99,26 +108,67 @@ async function confirmAllDetected(ctx, detected) {
   return r;
 }
 
+function platformNames(platforms) {
+  return platforms.map((key) => PLATFORMS[key].name).join(', ');
+}
+
+function reportInstallMode(ctx) {
+  if (ctx.options.forceOverwrite) {
+    ctx.ui.info(ctx.t('modeForce'));
+  } else if (ctx.dryRun) {
+    ctx.ui.info(ctx.t('modeDryRun'));
+  } else {
+    ctx.ui.info(ctx.t('modeInstall'));
+  }
+}
+
+function cancelSelection(ctx) {
+  ctx.ui.outro(ctx.t('cancelled'));
+  ctx.cancelled = true;
+  return [];
+}
+
+async function promptPlatforms(ctx) {
+  const platforms = await promptPlatformSelection(ctx);
+  return platforms.length > 0 ? platforms : cancelSelection(ctx);
+}
+
 /**
  * Resolve ctx.platforms via detection + prompts. Sets ctx.cancelled on backout.
  * If cafekit.json exists (prior install), reads platform from it to skip prompt.
  * Note: ctx.isUpdate is set later by checkVersions and cannot be used here.
  */
 async function resolvePlatforms(ctx) {
+  const requested = [...new Set((ctx.options.platforms || []).map((key) => key.trim()).filter(Boolean))];
+  if (requested.length > 0) {
+    const unknown = requested.filter((key) => !PLATFORMS[key]);
+    if (unknown.length > 0) {
+      throw new Error(`Unknown platform: ${unknown.join(', ')}. Expected: ${getPlatformKeys().join(', ')}`);
+    }
+    ctx.platforms = requested;
+    ctx.ui.info(ctx.t('installingFor', {
+      names: platformNames(requested)
+    }));
+    warnLegacyClaudeFolder(requested);
+    reportInstallMode(ctx);
+    return ctx;
+  }
+
   // Skip platform prompt when a prior install is detected via cafekit.json
-  const savedPlatform = getInstalledPlatform();
-  if (savedPlatform) {
-    ctx.platforms = [savedPlatform];
-    const platformNames = PLATFORMS[savedPlatform].name;
-    ctx.ui.info(ctx.t('platformKept', { names: platformNames }));
-
-    if (ctx.options.forceOverwrite) {
-      ctx.ui.info(ctx.t('modeForce'));
-    } else if (ctx.dryRun) {
-      ctx.ui.info(ctx.t('modeDryRun'));
-    } else {
-      ctx.ui.info(ctx.t('modeInstall'));
+  const savedPlatforms = getInstalledPlatforms();
+  if (savedPlatforms.length > 0) {
+    let platforms = [...new Set([...savedPlatforms, ...detectPlatforms()])];
+    if (ctx.interactive && platforms.some((key) => !savedPlatforms.includes(key))) {
+      const proceed = await confirmAllDetected(ctx, platforms);
+      if (!proceed) {
+        platforms = await promptPlatforms(ctx);
+        if (ctx.cancelled) return ctx;
+      }
     }
+    ctx.platforms = platforms;
+    ctx.ui.info(ctx.t('platformKept', { names: platformNames(platforms) }));
+
+    reportInstallMode(ctx);
     return ctx;
   }
 
@@ -126,12 +176,8 @@ async function resolvePlatforms(ctx) {
 
   if (platforms.length === 0) {
     if (ctx.interactive) {
-      platforms = await promptPlatformSelection(ctx);
-      if (platforms.length === 0) {
-        ctx.ui.outro(ctx.t('cancelled'));
-        ctx.cancelled = true;
-        return ctx;
-      }
+      platforms = await promptPlatforms(ctx);
+      if (ctx.cancelled) return ctx;
     } else {
       platforms = ['claude'];
       ctx.ui.info('No platform detected; defaulting to Claude Code (.claude/).');
@@ -139,28 +185,17 @@ async function resolvePlatforms(ctx) {
   } else if (platforms.length > 1 && ctx.interactive) {
     const proceed = await confirmAllDetected(ctx, platforms);
     if (!proceed) {
-      platforms = await promptPlatformSelection(ctx);
-      if (platforms.length === 0) {
-        ctx.ui.outro(ctx.t('cancelled'));
-        ctx.cancelled = true;
-        return ctx;
-      }
+      platforms = await promptPlatforms(ctx);
+      if (ctx.cancelled) return ctx;
     }
   }
 
   ctx.platforms = platforms;
 
-  const platformNames = platforms.map((key) => PLATFORMS[key].name).join(', ');
-  ctx.ui.info(ctx.t('installingFor', { names: platformNames }));
+  ctx.ui.info(ctx.t('installingFor', { names: platformNames(platforms) }));
   warnLegacyClaudeFolder(platforms);
 
-  if (ctx.options.forceOverwrite) {
-    ctx.ui.info(ctx.t('modeForce'));
-  } else if (ctx.dryRun) {
-    ctx.ui.info(ctx.t('modeDryRun'));
-  } else {
-    ctx.ui.info(ctx.t('modeInstall'));
-  }
+  reportInstallMode(ctx);
 
   return ctx;
 }
@@ -169,24 +204,28 @@ async function resolvePlatforms(ctx) {
  * Get the installed platform from cafekit.json files.
  * Returns the platform key (e.g. 'claude', 'opencode') or null.
  */
-function getInstalledPlatform() {
-  const claudeJson = path.join(process.cwd(), '.claude', 'cafekit.json');
-  if (fs.existsSync(claudeJson)) {
-    try {
-      const data = JSON.parse(fs.readFileSync(claudeJson, 'utf8'));
-      if (data.platform) return data.platform;
-    } catch { /* ignore */ }
-  }
-
-  const opencodeJson = path.join(process.cwd(), '.opencode', 'cafekit.json');
-  if (fs.existsSync(opencodeJson)) {
+function getInstalledPlatforms() {
+  const installed = [];
+  for (const key of getPlatformKeys()) {
+    const metadataPath = path.join(process.cwd(), PLATFORMS[key].folder, 'cafekit.json');
+    if (!fs.existsSync(metadataPath)) continue;
     try {
-      const data = JSON.parse(fs.readFileSync(opencodeJson, 'utf8'));
-      if (data.platform) return data.platform;
+      const data = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      const platformKey = data.platform && PLATFORMS[data.platform] ? data.platform : key;
+      if (!installed.includes(platformKey)) installed.push(platformKey);
     } catch { /* ignore */ }
   }
+  return installed;
+}
 
-  return null;
+function getInstalledPlatform() {
+  return getInstalledPlatforms()[0] || null;
 }
 
-module.exports = { selectLanguage, promptPlatformSelection, resolvePlatforms };
+module.exports = {
+  selectLanguage,
+  promptPlatformSelection,
+  resolvePlatforms,
+  getInstalledPlatform,
+  getInstalledPlatforms
+};

package/bin/phases/summary.js

@@ -53,7 +53,12 @@ function printSummary(ctx) {
 
   const lines = [];
   for (const key of platforms) {
-    lines.push(key === 'claude' ? t('nsClaude') : t('nsOpencode'));
+    const messageKey = {
+      claude: 'nsClaude',
+      opencode: 'nsOpencode',
+      codex: 'nsCodex'
+    }[key];
+    if (messageKey) lines.push(t(messageKey));
   }
   // rtk token-saver result (set by phases/setup-rtk.js when setup completed).
   if (ctx.rtkSetupRan) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.14.1",
-  "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
+  "version": "0.15.0",
+  "description": "Native spec-driven workflows for Claude Code, Codex CLI, and OpenCode. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",
   "private": false,
@@ -34,6 +34,7 @@
     "spec-driven",
     "workflow",
     "claude-code",
+    "codex-cli",
     "ai-coding",
     "specification",
     "requirements",

package/src/claude/CLAUDE.md

@@ -37,7 +37,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 ### 4. Goal-Driven Execution
 
 - Convert requests into verifiable success criteria.
-- For spec tasks, use `Completion Criteria` and `Evidence` as the source of truth. Existing task files may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
+- For spec tasks, use `Completion Criteria` and `## Evidence` (legacy heading aliases still parse) as the source of truth.
 - For bugs, reproduce with a failing test or concrete evidence when feasible before fixing.
 - Loop until verification passes or a real blocker is recorded.
 

package/src/claude/agents/code-auditor.md

@@ -23,7 +23,7 @@ Extract and verify:
 1. Declared deliverables (files, routes, entrypoints, UI surfaces, schemas, migrations)
 2. Declared task scope (`Related Files` and direct support files that are clearly justified)
 3. Completion Criteria
-4. Task Evidence expectations (or Task Test Plan & Verification Evidence / legacy Verification & Evidence)
+4. Task `## Evidence` (legacy heading aliases still parse) expectations
 5. Canonical Contracts & Invariants from the design
 6. Named technologies and runtime choices that the task/spec explicitly requires
 7. Runtime entrypoints/callers and reachability obligations from task evidence or the task-aware scout report

package/src/claude/agents/debugger.md

@@ -2,6 +2,7 @@
 name: debugger
 description: "Investigates bugs, incidents, CI/log/DB/performance/frontend failures, traces exact root causes with evidence, and hands off a verification-ready fix plan. Edits code only when explicitly requested by a fix workflow."
 model: sonnet
+memory: user
 tools: Glob, Grep, Read, Bash, WebFetch, WebSearch
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: god-developer
-description: "Primary code execution agent. Receives specifications (spec) from hapo:specs or task files and transforms them into production-grade source code. Operates on a Single-Track principle (linear, non-parallel)."
+description: "Primary code execution agent. Receives specifications (spec) from hapo:specs or task files and transforms them into production-grade source code. Operates on a Single-Track principle within its workspace (linear inside one working tree; multiple instances may run concurrently in separate isolated worktrees)."
 model: sonnet
 tools: Glob, Grep, Read, Edit, Write, NotebookEdit, Bash, WebFetch, WebSearch
 ---
@@ -94,3 +94,12 @@ Upon completion, output a concise report in this format:
 - Do not add AI attribution to code or commit messages.
 - Prioritize security (validate input, never hardcode secrets).
 - Code should be self-documenting — only add comments for complex logic.
+
+## Worktree Conduct (Parallel Wave dispatch)
+
+When dispatched into an isolated git worktree by `hapo:develop --parallel`:
+
+- Work ONLY inside this worktree; Single-Track discipline applies unchanged within it.
+- Do NOT edit `spec.json` or any `tasks/*.md` — the orchestrator is the single writer of spec state.
+- Do NOT touch files outside this task's `Related Files`.
+- Commit your completed work: `git commit -m "task(<id>): <title>"` — an uncommitted worktree cannot be merged back.

package/src/claude/agents/inspector.md

@@ -3,6 +3,7 @@ name: inspector
 tools: Glob, Grep, Read, Bash
 description: "Codebase structure scanner. Use this agent when you need to quickly scout/inspect the codebase architecture, files, and directories. Specializes in finding relevant files for a given work scope before implementation begins."
 model: haiku
+memory: user
 ---
 
 # Inspect — Codebase Scout

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

@@ -127,7 +127,7 @@ Before writing `design.md`, select a discovery mode and record the reason:
 - When requirement coverage format: list numeric IDs only, no descriptive suffixes
 - Apply `(P)` parallel markers when applicable (load `.claude/skills/specs/rules/tasks-parallel-analysis.md`)
 - Every task MUST use the compact implementation-ready shape: `Context`, `Steps`, `Requirements`, `Related Files`, `Completion Criteria`, `Evidence`, `Risk Assessment`.
-- `Evidence` MUST include exact commands, artifacts/runtime surfaces, runtime reachability proof, and negative-path checks. Existing specs may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
+- `## Evidence` (legacy heading aliases still parse) MUST include exact commands, artifacts/runtime surfaces, runtime reachability proof, and negative-path checks.
 - Completion criteria MUST be objective enough that a downstream quality gate can prove them without guesswork.
 - UI/app/runtime workflows MUST include a final integration/reachability task or final integration section that names the real entrypoint and proves all scoped user-facing surfaces are wired.
 - Do not allow orphan task outputs: components, services, hooks, routes, commands, workers, providers, reducers, data loaders, and generated artifacts must be reachable now or assigned to a named later integration task.

package/src/claude/agents/test-runner.md

@@ -11,7 +11,7 @@ You are a battle-hardened QA engineer who has been burned by production incident
 
 ## Task-Aware Inputs
 
-If the prompt includes task file paths, Completion Criteria, Evidence, Task Test Plan & Verification Evidence, or legacy Verification & Evidence instructions, treat them as authoritative.
+If the prompt includes task file paths, Completion Criteria, or `## Evidence` (legacy heading aliases still parse) instructions, treat them as authoritative.
 Diff-aware test selection does NOT replace task-specific verification.
 If the task/spec names a specific framework, auth system, transport, or shared-state boundary, keep that contract visible while evaluating evidence.
 If the prompt includes a feature name or `specs/<feature>`, load `spec.json`, `requirements.md`, `design.md`, and the active/recent task files. Treat `scope_lock`, Completion Criteria, and Evidence as the test contract.
@@ -30,7 +30,7 @@ Select tests by the task's touched surface:
 ## Command Resolution Order
 
 When the task file names exact commands, use this order:
-1. Run every exact executable command from `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`) in declaration order.
+1. Run every exact executable command from `## Evidence` (legacy heading aliases still parse) in declaration order.
 2. Run repo-default typecheck/test/build commands only to fill gaps not already covered above.
 3. Apply diff-aware test selection only after task-mandated commands are satisfied.
 

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 });
+  }
+});