@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/README.md

@@ -2,7 +2,7 @@
 
 > Native spec-driven workflow and runtime bundle for Claude Code and Codex CLI.
 
-[![Version](https://img.shields.io/badge/version-0.16.0-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.16.1-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Native-orange.svg)](https://claude.ai/code)
 [![Codex%20CLI](https://img.shields.io/badge/Codex%20CLI-Native-111111.svg)](https://developers.openai.com/codex)
@@ -138,21 +138,97 @@ cat .claude/cafekit.json
 cat .codex/cafekit.json
 ```
 
+### Statusline configuration
+
+The Claude statusline reads three keys from `.claude/runtime.json`:
+
+- `"statusline"`: render mode — `full` (default), `compact`, `minimal`, or `none`.
+- `statuslineColors`: set `false` to disable ANSI colors (`NO_COLOR` also wins).
+- `statuslineLayout`: optional custom layout. Global shape
+  `{ "lines": [["model", "context"], ["directory", "git"]] }` — each inner
+  array is one output line; modes only slice the line count (minimal = first
+  line, compact = first two, full = all). Valid section ids: `model`,
+  `context`, `quota`, `directory`, `git`, `plan`, `cost`, `changes`. Unknown
+  ids are ignored; an empty or invalid layout falls back to the default
+  renderers, and leaving the key out keeps the default output unchanged. The
+  `cost` section renders only when enabled here, billing mode is API, and cost
+  data exists. Quota shows five-hour and weekly windows only while the usage
+  cache is fresh.
+
 ## Core Skills
 
 CafeKit ships many skills, but the main release surface is:
 
-- `/hapo:question <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when local evidence is insufficient
-- `/hapo:brainstorm <idea-or-problem>`: scout the repo, clarify exact requirements, compare approaches, and hand off to specs
-- `/hapo:specs <feature-description>`: create or resume a structured spec workflow
-- `/hapo:develop <feature-name>`: implement from approved spec artifacts
-- `/hapo:debug <issue>`: diagnose bugs, incidents, CI failures, flaky tests, UI regressions, and performance issues before fixing
-- `/hapo:hotfix <issue>`: fix diagnosed bugs with root-cause, verification, prevention, and side-effect gates
-- `/hapo:docs [--init|--update|--summarize|--reconstruct]`: create project docs or reconstruct as-is system documentation from source code
-- `/hapo:test [scope|--full]`: run verification and return a structured verdict
-- `/hapo:code-review [scope|--pending]`: adversarial review focused on correctness, regressions, and security
+- `/cf:ask <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when local evidence is insufficient
+- `/cf:scout <search-target>`: discover relevant files locally first, delegating only for permitted broad independent scopes
+- `/cf:brainstorm <idea-or-problem>`: scout the repo, clarify exact requirements, compare approaches, and hand off to specs
+- `/cf:research <decision>`: choose proportional depth and return traceable evidence for an uncertain technical decision
+- `/cf:route <material-request>`: classify ambiguous, multi-step, multi-domain, or elevated-risk work and compose the shortest valid installed chain
+- `/cf:loop <bounded-experiment>`: run explicit-only numeric optimization in an isolated worktree and return a base-bound patch handoff
+- `/cf:specs <feature-description>`: create or resume a structured spec workflow
+- `/cf:develop <feature-name>`: implement from approved spec artifacts
+- `/cf:debug <issue>`: run adaptive-depth, diagnostic-only root-cause analysis with elimination and prevention-aware handoff
+- `/cf:fix <issue>`: repair the diagnosed root cause with proportional depth; Quick/local stays direct, while Standard and Incident/deep bound the repair and use post-diagnosis research, brainstorm, or staged planning only when evidence leaves a real decision; every path consumes the `cf:debug` handoff and reports shared `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED` verdicts through verification, prevention, and side-effect gates
+- `/cf:test [scope|--full]`: run verification and return a structured verdict
+- `/cf:code-review [scope|--pending]`: adversarial review focused on correctness, regressions, and security
+
+### Adaptive Brainstorm controls
+
+Brainstorm stays proportional by default: Direct classification runs before any
+analysis overlay, then non-direct work selects the smallest adequate Standard or
+Deep depth. Controls are parsed only from the leading control segment. Combine
+the single-use exact flags `--deep`, `--visual`, and `--advice` in any order;
+an unknown or duplicate leading `--*` stops with usage and no action. `--` ends
+controls, so literal flag content can start with `/cf:brainstorm -- --dry-run`.
+
+`--deep` raises non-direct analysis depth only. `--visual` changes presentation
+and falls back to text. `--advice` uses the advisory brainstormer only after a
+material choice exists. External visual/adviser context is minimized and
+redacted first; neither overlay writes, approves, persists, dispatches, or
+completes work. Chat is the default output. A durable file needs explicit user
+authority, and no Brainstorm output is live proof or Specs/Develop approval or
+execution authority.
+
+### Adaptive Research and bounded Loop
+
+Use `/cf:research` when the result is a decision: Quick, Standard, or Deep
+research binds material claims to a URL or repository anchor, authority,
+date/version, applicability, and `confirmed`, `inferred`, or `unresolved`
+state. Research returns evidence and tradeoffs; it does not implement the
+recommendation or guarantee correctness.
+
+Use `/cf:loop` only by explicit request and only after its preflight freezes
+Goal, isolated Scope, finite numeric Metric and Direction, reproducible
+Baseline, distinct Guard, noise policy and minimum delta, budget, and stop
+conditions. Each iteration stays in a detached worktree. The result is a
+base-bound isolated patch handoff, never an automatic apply, commit, push, or
+guarantee of improvement.
+
+```text
+/cf:research Compare current local-first search libraries for this repository
+/cf:loop Goal="reduce parser latency" Scope="packages/parser" Metric="median ms, lower" Baseline="pinned base" Guard="npm test" Noise="MAD; minimum delta 2%" Budget="10 iterations" Stop="budget, drift, or failed guard"
+$cf-research Compare current local-first search libraries for this repository
+$cf-loop Goal="reduce parser latency" Scope="packages/parser" Metric="median ms, lower" Baseline="pinned base" Guard="npm test" Noise="MAD; minimum delta 2%" Budget="10 iterations" Stop="budget, drift, or failed guard"
+```
+
+Optional document skills are `docs`, `docx`, `pdf`, `pptx`, `xlsx`, and
+`ai-multimodal`. Select them interactively or run:
+
+```bash
+npx @haposoft/cafekit --with-document-skills
+```
+
+Fresh non-interactive installs leave them out by default. Use
+`--without-document-skills` to skip them or remove pristine CafeKit-owned
+copies; user-modified files are preserved. Documentation validators, hooks,
+and the `docs-keeper` agent remain part of the core runtime.
 
-Common companion skills bundled in this package include `inspect`, `research`, `ai-multimodal`, `frontend-development`, `backend-development`, and `react-best-practices`.
+When installed, `cf:docs` consumes a post-task docs checkpoint from
+Develop/Sync (`none | minor | major` — `none` reports only, `minor`/`major`
+update only affected existing docs, and a checkpoint never invents a new
+document), dispatches `docs-keeper` or parallel readers only through the
+Delegation Gate, and keeps every reconstructed claim on the
+`Observed | Inferred | Unknown` evidence taxonomy.
 
 CafeKit uses rule-based skill routing guidance instead of an automatic prompt-scoring hook. See `.claude/rules/skill-workflow-routing.md`, `.claude/rules/skill-domain-routing.md`, or run:
 
@@ -160,7 +236,16 @@ CafeKit uses rule-based skill routing guidance instead of an automatic prompt-sc
 node .claude/scripts/generate-skill-catalog.cjs --skills
 ```
 
-On Codex, invoke the transformed native skill names as `$hapo-<name>` or browse
+Routing uses progressive disclosure: live catalog metadata selects a candidate,
+the selected `SKILL.md` supplies its contract, and only relevant references are
+loaded. Invoke an installed skill directly for explicit or obvious low-risk
+work; use `cf:route` only when classification or chaining is material. When a
+capability or agent is absent, continue inline when safe or name the gap.
+Hooks are not a skill router and never grant capability presence or authority. Source
+and installed projections are verified; live-model adherence remains
+`UNPROVEN`, not deterministic.
+
+On Codex, invoke the transformed native skill names as `$cf-<name>` or browse
 them with `/skills`. Explicit custom-agent delegation uses snake_case agent
 names and `fork_turns: "none"`.
 
@@ -169,32 +254,36 @@ names and `fork_turns: "none"`.
 Claude Code:
 
 ```bash
-/hapo:question "Which files define the current CafeKit install/runtime behavior?" --repo
-/hapo:brainstorm Explore approaches for a Google Meet transcript extension
-/hapo:specs Build a Google Meet transcript extension with AI summaries
-/hapo:develop meet-transcript-mvp
-/hapo:test meet-transcript-mvp --full
-/hapo:code-review meet-transcript-mvp --pending
+/cf:ask "Which files define the current CafeKit install/runtime behavior?" --repo
+/cf:scout "Find the runtime entrypoints for skill installation"
+/cf:brainstorm Explore approaches for a Google Meet transcript extension
+/cf:research Compare current transcript storage options for this repository
+/cf:specs Build a Google Meet transcript extension with AI summaries
+/cf:develop meet-transcript-mvp
+/cf:test meet-transcript-mvp --full
+/cf:code-review meet-transcript-mvp --pending
 ```
 
 Codex CLI:
 
 ```text
-$hapo-question "Which files define the current CafeKit runtime?" --repo
-$hapo-brainstorm Explore approaches for a Google Meet transcript extension
-$hapo-specs Build a Google Meet transcript extension with AI summaries
-$hapo-develop meet-transcript-mvp
-$hapo-test meet-transcript-mvp --full
-$hapo-code-review meet-transcript-mvp --pending
+$cf-ask "Which files define the current CafeKit runtime?" --repo
+$cf-scout "Find the runtime entrypoints for skill installation"
+$cf-brainstorm Explore approaches for a Google Meet transcript extension
+$cf-research Compare current transcript storage options for this repository
+$cf-specs Build a Google Meet transcript extension with AI summaries
+$cf-develop meet-transcript-mvp
+$cf-test meet-transcript-mvp --full
+$cf-code-review meet-transcript-mvp --pending
 ```
 
 Reconstruct as-is docs from a legacy codebase:
 
 ```bash
-/hapo:docs --reconstruct apps/legacy-admin
+/cf:docs --reconstruct apps/legacy-admin
 ```
 
-The reconstruct bundle includes as-is markdown/JSON evidence and a self-contained `overview.html` review dashboard before the approved docs are handed to `/hapo:specs`.
+The reconstruct bundle includes as-is markdown/JSON evidence and a self-contained `overview.html` review dashboard before the approved docs are handed to `/cf:specs`.
 
 ## Codex hook safety
 
@@ -215,9 +304,9 @@ specs/<feature-name>/
 └── task-NN-<slug>.md
 ```
 
-The process-first workflow has three human decision gates. `hapo:specs` opens
+The process-first workflow has three human decision gates. `cf:specs` opens
 C1 to fix scope before authoring and C2 to resolve adversarial findings, then
-stops. A later explicit `hapo:develop` invocation executes the tasks and
+stops. A later explicit `cf:develop` invocation executes the tasks and
 presents C3 for closeout only after real execution proof. Each task has one
 `Status:` field and keeps its canonical `## Receipt` inline, including the
 exact Verification Plan command, `Exit: 0`, `Verification: PASS`,

package/bin/__tests__/codex-hooks-ownership.test.js

@@ -0,0 +1,239 @@
+'use strict';
+
+// `.codex/hooks.json` is a shared configuration file, not a CafeKit payload. It used to be
+// copied verbatim, so a single user-added hook turned the whole file into a user-modified
+// artifact: a normal install then preserved CafeKit's stale hooks, and `--force-overwrite`
+// destroyed the user's. These tests pin the merge that replaced that copy, mirroring how
+// `.claude/settings.json` has always been handled.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+const INSTALLER = path.join(PACKAGE_ROOT, 'bin/install.js');
+const TEMPLATE = path.join(PACKAGE_ROOT, 'src/codex/hooks.json');
+const MANIFEST = require(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'));
+const { hookScript } = require(path.join(PACKAGE_ROOT, 'bin/phases/codex-hooks.js'));
+
+const USER_STOP_COMMAND = 'node "$(git rev-parse --show-toplevel)/scripts/my-own-stop.js"';
+const USER_PRETOOL_COMMAND = 'echo user-owned-pretooluse';
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-hooks-own-'));
+  try {
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, extraArgs = []) {
+  return spawnSync(
+    process.execPath,
+    [INSTALLER, '--platform', 'codex', '--yes', ...extraArgs],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } }
+  );
+}
+
+function hooksPath(root) {
+  return path.join(root, '.codex', 'hooks.json');
+}
+
+function readHooks(root) {
+  return JSON.parse(fs.readFileSync(hooksPath(root), 'utf8'));
+}
+
+/** Every handler across every event, flattened. */
+function allHandlers(config) {
+  return Object.values(config.hooks || {})
+    .flatMap((groups) => (Array.isArray(groups) ? groups : []))
+    .flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks : []));
+}
+
+function allCommands(config) {
+  return allHandlers(config).map((handler) => handler?.command).filter(Boolean);
+}
+
+/** The CafeKit hook scripts the template registers, per event. */
+function managedScripts() {
+  const template = JSON.parse(fs.readFileSync(TEMPLATE, 'utf8'));
+  const byEvent = {};
+  for (const [eventName, groups] of Object.entries(template.hooks || {})) {
+    byEvent[eventName] = groups
+      .flatMap((group) => group.hooks || [])
+      .map((handler) => hookScript(handler.command))
+      .filter(Boolean);
+  }
+  return byEvent;
+}
+
+/** Add two hooks CafeKit does not author: one under an event it owns, one under a new event. */
+function addUserHooks(root) {
+  const config = readHooks(root);
+  config.hooks.Stop.push({ matcher: '*', hooks: [{ type: 'command', command: USER_STOP_COMMAND }] });
+  config.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [{ type: 'command', command: USER_PRETOOL_COMMAND }] });
+  fs.writeFileSync(hooksPath(root), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+test('a fresh install registers every CafeKit hook under its own event', () => {
+  inTempProject((root) => {
+    const result = install(root);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+
+    const installed = readHooks(root);
+    for (const [eventName, scripts] of Object.entries(managedScripts())) {
+      const registered = (installed.hooks[eventName] || [])
+        .flatMap((group) => group.hooks || [])
+        .map((handler) => hookScript(handler.command))
+        .filter(Boolean);
+      for (const script of scripts) {
+        assert.ok(registered.includes(script), `${script} missing from ${eventName}`);
+      }
+    }
+  });
+});
+
+test('a reinstall preserves user-added hooks instead of overwriting them', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+    addUserHooks(root);
+
+    const second = install(root);
+    assert.equal(second.status, 0, `${second.stdout}\n${second.stderr}`);
+
+    const commands = allCommands(readHooks(root));
+    assert.ok(commands.includes(USER_STOP_COMMAND), 'user Stop hook was erased by the reinstall');
+    assert.ok(commands.includes(USER_PRETOOL_COMMAND), 'user PreToolUse hook was erased by the reinstall');
+  });
+});
+
+test('--force-overwrite does not destroy hooks CafeKit did not author', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+    addUserHooks(root);
+
+    const forced = install(root, ['--force-overwrite']);
+    assert.equal(forced.status, 0, `${forced.stdout}\n${forced.stderr}`);
+
+    const commands = allCommands(readHooks(root));
+    assert.ok(commands.includes(USER_STOP_COMMAND), '--force-overwrite erased the user Stop hook');
+    assert.ok(commands.includes(USER_PRETOOL_COMMAND), '--force-overwrite erased the user PreToolUse hook');
+  });
+});
+
+test('repeated installs never duplicate a CafeKit hook', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+    const afterFirst = allHandlers(readHooks(root)).length;
+
+    assert.equal(install(root).status, 0);
+    assert.equal(install(root).status, 0);
+
+    const config = readHooks(root);
+    assert.equal(allHandlers(config).length, afterFirst, 'a reinstall added handlers that were already registered');
+
+    // Uniqueness is per event, not global: state.cjs and completion-authority.cjs each
+    // register under several events by design.
+    for (const [eventName, groups] of Object.entries(config.hooks)) {
+      const scripts = groups
+        .flatMap((group) => group.hooks || [])
+        .map((handler) => hookScript(handler.command))
+        .filter(Boolean);
+      assert.equal(
+        new Set(scripts).size, scripts.length,
+        `duplicate hook scripts under ${eventName}: ${scripts.join(', ')}`
+      );
+    }
+  });
+});
+
+test('a hook the user moved to another event is not re-added to the one CafeKit chose', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+
+    // Move a CafeKit hook out of the group the template put it in, the way a user editing
+    // matchers would. Re-adding it on the next install would fire it twice.
+    const config = readHooks(root);
+    let moved = null;
+    for (const group of config.hooks.PreToolUse) {
+      const index = (group.hooks || []).findIndex((handler) => hookScript(handler.command) === 'inspect-block.cjs');
+      if (index >= 0) { moved = group.hooks.splice(index, 1)[0]; break; }
+    }
+    assert.ok(moved, 'fixture expects inspect-block.cjs under PreToolUse');
+    config.hooks.PreToolUse.push({ matcher: 'Read|Grep', hooks: [moved] });
+    fs.writeFileSync(hooksPath(root), `${JSON.stringify(config, null, 2)}\n`);
+
+    assert.equal(install(root).status, 0);
+
+    const scripts = allCommands(readHooks(root)).map(hookScript).filter(Boolean);
+    assert.equal(
+      scripts.filter((script) => script === 'inspect-block.cjs').length, 1,
+      'the moved hook was re-added under its original matcher'
+    );
+  });
+});
+
+test('obsolete CafeKit hooks are pruned while similarly named foreign hooks stay', () => {
+  const obsolete = MANIFEST.obsolete.settingsHookCommandSubstrings;
+  assert.ok(obsolete.length > 0, 'fixture requires at least one retired hook substring');
+
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+
+    const config = readHooks(root);
+    const retired = `node ".codex/${obsolete[0]}"`;
+    const foreign = 'node "scripts/my-skill-router.cjs"';
+    config.hooks.UserPromptSubmit.push({
+      matcher: '*',
+      hooks: [{ type: 'command', command: retired }, { type: 'command', command: foreign }]
+    });
+    fs.writeFileSync(hooksPath(root), `${JSON.stringify(config, null, 2)}\n`);
+
+    const second = install(root);
+    assert.equal(second.status, 0, `${second.stdout}\n${second.stderr}`);
+
+    const commands = allCommands(readHooks(root));
+    assert.ok(!commands.includes(retired), 'retired CafeKit hook survived the prune');
+    assert.ok(commands.includes(foreign), 'prune removed a hook CafeKit never authored');
+  });
+});
+
+test('a malformed hooks.json is reported and left byte-identical, never overwritten', () => {
+  inTempProject((root) => {
+    fs.mkdirSync(path.join(root, '.codex'), { recursive: true });
+    const broken = '{ "hooks": { "Stop": [ }\n';
+    fs.writeFileSync(hooksPath(root), broken);
+
+    const result = install(root);
+    assert.notEqual(result.status, 0, 'a malformed hooks.json must fail the install, not pass silently');
+    assert.match(`${result.stdout}${result.stderr}`, /not valid JSON/);
+    assert.equal(fs.readFileSync(hooksPath(root), 'utf8'), broken, 'the malformed file was overwritten');
+  });
+});
+
+test('a dry run reports the merge without writing hooks.json', () => {
+  inTempProject((root) => {
+    const result = install(root, ['--dry-run']);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.match(result.stdout, /Codex hooks/);
+    assert.equal(fs.existsSync(hooksPath(root)), false, 'a dry run wrote hooks.json');
+  });
+});
+
+test('hooks.json stays outside the ownership manifest, like settings.json', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+
+    const manifestPath = path.join(root, '.codex', 'cafekit-manifest.json');
+    assert.equal(fs.existsSync(manifestPath), true, 'the install manifest is missing');
+    const tracked = Object.keys(JSON.parse(fs.readFileSync(manifestPath, 'utf8')).files || {});
+    assert.ok(
+      !tracked.some((file) => file.endsWith('hooks.json')),
+      'hooks.json is tracked as a payload file, so a user edit would be classified user-modified again'
+    );
+  });
+});

package/bin/__tests__/codex-hooks.test.js

@@ -156,6 +156,56 @@ function canonicalProcessTask(root, title, dependency = 'none') {
   ].join('\n');
 }
 
+test('Claude and Codex docs sync ignore committed Specs state but report source changes', () => {
+  inHookFixture((root, hooks) => {
+    const docsDir = path.join(root, 'docs');
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(path.join(root, 'package.json'), '{"name":"docs-sync-fixture"}\n');
+    fs.writeFileSync(path.join(docsDir, 'project-overview-pdr.md'), '# Fixture\n');
+    let result = spawnSync('git', ['-C', root, 'add', 'package.json', 'docs/project-overview-pdr.md'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    result = spawnSync('git', ['-C', root, 'commit', '-qm', 'source baseline'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    const sourceBase = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).stdout.trim();
+    fs.writeFileSync(path.join(docsDir, '.sync_hash'), `${sourceBase}\n`);
+    result = spawnSync('git', ['-C', root, 'add', 'docs/.sync_hash'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    result = spawnSync('git', ['-C', root, 'commit', '-qm', 'sync docs'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+
+    const featureDir = path.join(root, 'specs', 'demo');
+    fs.mkdirSync(featureDir, { recursive: true });
+    fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Completed packet\n');
+    result = spawnSync('git', ['-C', root, 'add', 'specs/demo/plan.md'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    result = spawnSync('git', ['-C', root, 'commit', '-qm', 'refresh receipt state'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+
+    const payload = { cwd: root, session_id: 'docs-sync-session', hook_event_name: 'SessionStart' };
+    const docsSyncHooks = [
+      path.join(hooks, 'docs-sync.cjs'),
+      path.join(PACKAGE_ROOT, 'src/claude/hooks/docs-sync.cjs'),
+    ];
+    for (const hook of docsSyncHooks) {
+      const afterSpecCommit = runHook(hook, root, payload);
+      assert.equal(afterSpecCommit.status, 0, afterSpecCommit.stderr);
+      assert.equal(afterSpecCommit.stdout, '', `${hook}: spec-only commits must not stale docs sync`);
+    }
+
+    fs.mkdirSync(path.join(root, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'src', 'app.js'), 'module.exports = true;\n');
+    result = spawnSync('git', ['-C', root, 'add', 'src/app.js'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    result = spawnSync('git', ['-C', root, 'commit', '-qm', 'change source'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    for (const hook of docsSyncHooks) {
+      const afterSourceCommit = runHook(hook, root, payload);
+      assert.equal(afterSourceCommit.status, 0, afterSourceCommit.stderr);
+      assert.match(afterSourceCommit.stdout, /Docs sync needed/);
+    }
+  });
+});
+
 function inInstalledProcessSpecStateFixture(run) {
   return inHookFixture((root, hooks) => {
     const feature = path.join(root, 'specs', 'auth');
@@ -1696,3 +1746,128 @@ test('Claude and Codex fail closed consistently for malformed cwd payloads', ()
     assert.equal(JSON.parse(codex.stdout).hookSpecificOutput.permissionDecision, 'deny');
   });
 });
+
+test('Codex emits the required decision for all six receipt states', () => {
+  // Codex owns no checker of its own: both wrappers in .codex/hooks/lib forward to
+  // the shared module, so the two receipt modes arrive by inheritance. This case is
+  // the regression lock on that inheritance. Each state asserts the decision Codex
+  // must emit on its own terms; parity with Claude is checked in addition, never
+  // instead, because both runtimes execute the same module and a broken
+  // implementation would agree with itself.
+  //
+  // The dirty-tree state runs the hook from a directory below the project root with
+  // the uncommitted change outside that directory's subtree. Without that, an
+  // implementation resolving the repository root from the working directory returns
+  // the same decision as a correct one and the case cannot fail.
+  inHookFixture((root, hooks) => {
+    const nested = path.join(root, 'packages', 'app');
+    const feature = path.join(root, 'specs', 'auth');
+    const taskFile = path.join(feature, 'task-01-auth.md');
+    const outsideDirt = path.join(root, 'src', 'outside.txt');
+    fs.mkdirSync(nested, { recursive: true });
+    fs.mkdirSync(feature, { recursive: true });
+    fs.mkdirSync(path.dirname(outsideDirt), { recursive: true });
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n');
+    fs.writeFileSync(outsideDirt, 'committed\n');
+
+    const staleBase = 'f'.repeat(40);
+    const staleHead = 'e'.repeat(40);
+    const taskBody = [
+      '# Task 01: auth', '', 'Status: done', '',
+      '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '## Receipt', '',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${staleBase}`, `Head: ${staleHead}`,
+      '```text', '$ node --test', 'pass: 1', '```', '',
+    ].join('\n');
+    fs.writeFileSync(taskFile, taskBody);
+
+    const gate = path.join(hooks, 'spec-gate.cjs');
+    const payload = {
+      cwd: nested,
+      featureName: 'auth',
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+    };
+    const git = (...args) => {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+      return result;
+    };
+    const decide = () => {
+      const result = runHook(gate, nested, payload);
+      assert.equal(result.status, 0, result.stderr);
+      return result.stdout.trim() === '' ? 'accept' : 'block';
+    };
+    // Use the same module instance that minted the context: a trusted runtime
+    // context is tracked per module, so mixing the package copy with the fixture
+    // copy would report a spurious binding failure.
+    const RECEIPT = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-receipt.cjs'));
+    const sharedDecides = () => {
+      const failures = RECEIPT.checkWorkflowTaskReceipt(
+        feature, 'task-01-auth.md', workflowRuntimeContext(root), POLICY,
+      ).failures;
+      return failures.length === 0 ? 'accept' : 'block';
+    };
+
+    // 1. untracked task file — never committed, so the binding stays.
+    assert.equal(decide(), 'block', 'an untracked task file must keep full binding');
+
+    // 2. staged but not committed — `git add` alone must not read as committed.
+    git('add', '-A');
+    assert.equal(decide(), 'block', 'a staged-only task file must keep full binding');
+
+    // 3. committed on a clean tree — the one accepting state.
+    git('commit', '-qm', 'receipt and source');
+    // Generated runtime state is excluded by design, so assert cleanliness the way
+    // the selector sees it: nothing dirty outside the specs root and the runtime
+    // state roots. The gate's own cache write must not read as a dirty worktree.
+    const cleanStatus = spawnSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all',
+      '--', '.', ':(exclude,literal)specs', ':(exclude,literal).codex/hooks/.logs',
+      ':(exclude,literal).claude/hooks/.logs', ':(exclude,literal).codex/runtime.json'], { encoding: 'utf8' });
+    assert.equal(cleanStatus.stdout.trim(), '', 'nothing outside specs and runtime state may be dirty for this state to mean anything');
+    assert.equal(decide(), 'accept', 'a committed, unchanged receipt on a clean tree must be accepted');
+    assert.equal(sharedDecides(), 'accept', 'the shared checker must agree');
+
+    // 4. dirty tree outside the specs root, hook run from a nested directory with
+    //    the change outside that directory's subtree.
+    fs.writeFileSync(outsideDirt, 'uncommitted\n');
+    assert.ok(!path.relative(nested, outsideDirt).startsWith('..') === false,
+      'the dirt must lie outside the working directory used for the run');
+    assert.equal(decide(), 'block', 'an uncommitted change outside the specs root must rebind');
+    assert.equal(sharedDecides(), 'block', 'the shared checker must agree');
+    git('checkout', '--', 'src/outside.txt');
+
+    // 5. work confined to the specs root does not reopen a committed receipt.
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n\nEdited after the receipt landed.\n');
+    assert.equal(decide(), 'accept', 'edits inside the specs root must not rebind');
+    git('checkout', '--', 'specs/auth/plan.md');
+
+    // 6. committed then modified — the receipt itself changed after the commit.
+    fs.writeFileSync(taskFile, taskBody.replace(`Head: ${staleHead}`, `Head: ${'d'.repeat(40)}`));
+    assert.equal(decide(), 'block', 'a receipt edited after commit must be rebound');
+    assert.equal(sharedDecides(), 'block', 'the shared checker must agree');
+  });
+});
+
+test('Codex wrappers stay pass-through and carry no receipt-mode logic', () => {
+  // The mode selector must exist in exactly one place. If it is ever duplicated
+  // into the Codex wrapper, the two runtimes can drift apart silently.
+  const wrapper = fs.readFileSync(
+    path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/spec-receipt.cjs'),
+    'utf8',
+  );
+  for (const marker of ['receiptBindingMode', 'skip-worktree', 'ls-files', 'cat-file', 'structure']) {
+    assert.ok(
+      !wrapper.includes(marker),
+      `the Codex wrapper must not reimplement receipt-mode logic; found ${marker}`,
+    );
+  }
+  assert.match(wrapper, /checkWorkflowTaskReceipt\(featureDir, taskPath, runtimeContext, policy\)/);
+  assert.match(
+    fs.readFileSync(path.join(PACKAGE_ROOT, 'src/codex/hooks/spec-state.cjs'), 'utf8'),
+    /Stop re-checks every done receipt/,
+  );
+});