@haposoft/cafekit 0.16.7 → 0.18.1

package/bin/__tests__/docs-sync-on-demand.test.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// docs-sync printed "Docs sync needed" at every Claude SessionStart, and nothing ever
+// cleared it. It now runs only when the docs skill asks for it. The skill text is shared
+// with Codex, whose copy crashes silently on an empty stdin, so the command feeds `{}`.
+// Each case names the failure it prevents.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync, execSync } = 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 DOCS_SKILL = path.join(PACKAGE_ROOT, 'src/claude/skills/docs');
+const ON_DEMAND = "echo '{}' | node .claude/hooks/docs-sync.cjs";
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-docs-sync-'));
+  try {
+    const init = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+    assert.equal(init.status, 0, init.stderr);
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, platforms) {
+  const result = spawnSync(process.execPath, [INSTALLER, '--platform', platforms.join(','), '--yes'],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+}
+
+function commands(settings, event) {
+  return (settings.hooks[event] || []).flatMap((group) => (group.hooks || []).map((hook) => hook.command));
+}
+
+/** A git project with code, docs and a `.sync_hash` that no longer matches the source. */
+function makeStale(root) {
+  fs.writeFileSync(path.join(root, 'package.json'), '{"name":"fixture"}\n');
+  fs.mkdirSync(path.join(root, 'docs'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'docs', 'README.md'), '# Docs\n');
+  fs.writeFileSync(path.join(root, 'docs', '.sync_hash'), '0000000000000000000000000000000000000000\n');
+  execSync('git -c user.email=t@t -c user.name=t add -A && git -c user.email=t@t -c user.name=t commit -qm fixture', { cwd: root });
+}
+
+test('fresh claude install runs no docs-sync at SessionStart', () => {
+  inTempProject((root) => {
+    install(root, ['claude']);
+    const settings = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'settings.json'), 'utf8'));
+    assert.equal(commands(settings, 'SessionStart').some((c) => c.includes('docs-sync.cjs')), false);
+    assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', 'docs-sync.cjs')), true, 'the hook stays installed for on-demand use');
+  });
+});
+
+test('upgrade drops the SessionStart docs-sync entry', () => {
+  inTempProject((root) => {
+    install(root, ['claude']);
+    const settingsPath = path.join(root, '.claude', 'settings.json');
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    const kept = commands(settings, 'SessionStart');
+    settings.hooks.SessionStart[0].hooks.push({ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs"' });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    install(root, ['claude']);
+    const after = commands(JSON.parse(fs.readFileSync(settingsPath, 'utf8')), 'SessionStart');
+    assert.equal(after.some((c) => c.includes('docs-sync.cjs')), false);
+    for (const command of kept) assert.ok(after.includes(command), `kept: ${command}`);
+  });
+});
+
+test('the docs skill runs docs-sync on demand', () => {
+  for (const rel of ['SKILL.md', 'references/update-workflow.md']) {
+    assert.ok(fs.readFileSync(path.join(DOCS_SKILL, rel), 'utf8').includes(ON_DEMAND), `${rel} names the on-demand command`);
+  }
+  const files = fs.readdirSync(DOCS_SKILL, { recursive: true }).filter((f) => f.endsWith('.md'));
+  for (const rel of files) {
+    assert.doesNotMatch(fs.readFileSync(path.join(DOCS_SKILL, rel), 'utf8'), /SessionStart docs-sync/, rel);
+  }
+});
+
+for (const [runtime, folder] of [['claude', '.claude'], ['codex', '.codex']]) {
+  test(`the ${runtime === 'claude' ? 'Claude' : 'Codex'} copy prints its signal on demand`, () => {
+    inTempProject((root) => {
+      install(root, [runtime]);
+      makeStale(root);
+      const out = execSync(`echo '{}' | node ${folder}/hooks/docs-sync.cjs`, { cwd: root, encoding: 'utf8' });
+      assert.match(out, /Docs sync needed/);
+    });
+  });
+}

package/bin/__tests__/grok-envelope.test.js

@@ -134,36 +134,6 @@ test('a broad glob is denied with its full reason in JSON', () => {
   });
 });
 
-test('a nested task write is denied under the grok write tool', () => {
-  withInstall((root) => {
-    const target = path.join(root, 'specs', 'demo', 'tasks', 'task-R0-01-x.md');
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    // grok creates files with `write`; `search_replace` edits an existing one. The guard
-    // fires on Write only, so the alias has to keep those two apart.
-    const r = runHook(root, 'task-scaffold-guard.cjs', {
-      hookEventName: 'pre_tool_use',
-      cwd: root,
-      toolName: 'write',
-      toolInput: { path: target, content: '# x' },
-    });
-    const { decision, reason } = decisionOf(r.stdout);
-    assert.equal(decision, 'deny');
-    assert.match(reason, /TASK SCAFFOLD REQUIRED/);
-    assert.match(reason, /spec-scaffold\.cjs/, 'the command the model must run has to reach it');
-    assert.equal(r.code, 2);
-
-    // The escape route the message names must stay open: an edit is not a create.
-    const edit = runHook(root, 'task-scaffold-guard.cjs', {
-      hookEventName: 'pre_tool_use',
-      cwd: root,
-      toolName: 'search_replace',
-      toolInput: { path: target, old_string: 'a', new_string: 'b' },
-    });
-    assert.equal(decisionOf(edit.stdout).decision, null, 'search_replace must not be treated as a create');
-    assert.equal(edit.code, 0);
-  });
-});
-
 /** A packet the Stop gate will block: one done task with no receipt. */
 function unprovenPacket(root) {
   const feature = path.join(root, 'specs', 'demo');
@@ -206,32 +176,6 @@ test('the Stop gate still blocks an unproven done task', () => {
   }, { git: true });
 });
 
-test('the approval hook takes its approve path on a grok prompt', () => {
-  withInstall((root) => {
-    // Registered without an argv mode, this hook picks its mode from the event name, and
-    // approve() returns immediately unless that name is exactly 'UserPromptSubmit'. An
-    // approval phrase with no pending request is therefore the oracle: only the approve
-    // path can print a rejection line, so the line proves the event name was translated.
-    // Under an unreadable envelope the mode fell back to the stop path on every prompt.
-    const nonce = 'a'.repeat(24);
-    const r = runHook(root, 'completion-authority.cjs', {
-      hookEventName: 'user_prompt_submit',
-      sessionId: 'grok-1',
-      cwd: root,
-      prompt: `APPROVE CAFEKIT COMPLETION ${nonce}`,
-    });
-    assert.match(r.stdout, /CafeKit completion approval rejected/,
-      'the approve path must run and refuse an approval that matches no pending request');
-    assert.equal(decisionOf(r.stdout).decision, null, 'and it must not block the prompt');
-
-    // An ordinary prompt stays silent on both counts.
-    const plain = runHook(root, 'completion-authority.cjs', {
-      hookEventName: 'user_prompt_submit', sessionId: 'grok-1', cwd: root, prompt: 'please continue',
-    });
-    assert.equal(plain.stdout.trim(), '', 'an ordinary prompt produces nothing');
-  }, { git: true });
-});
-
 test('the secret guardrail sees a grok prompt', () => {
   withInstall((root) => {
     // grok's spelling for the prompt field is unverified, so the reader accepts the Claude

package/bin/__tests__/hook-payload.test.js

@@ -49,8 +49,8 @@ test('read_file path becomes file_path', () => {
     toolInput: { path: '/p/.env' },
   });
   assert.equal(out.tool_name, 'Read');
-  // privacy-block reads file_path and path, but task-scaffold-guard reads file_path first
-  // and inspect-block's path list is keyed the same way.
+  // privacy-block and inspect-block both read file_path first, so the normalized key
+  // must be file_path.
   assert.equal(out.tool_input.file_path, '/p/.env');
   assert.equal(out.tool_input.path, '/p/.env', 'the original key stays for hooks that read it');
 });
@@ -83,7 +83,6 @@ test('Stop and subagent fields map', () => {
     subagentId: 'agent-7',
     lastAssistantMessage: 'REVIEW: PASS',
   });
-  // semantic-review-authority refuses to record an attestation without agent_id.
   assert.equal(sub.hook_event_name, 'SubagentStop');
   assert.equal(sub.agent_type, 'code-auditor');
   assert.equal(sub.agent_id, 'agent-7');
@@ -102,9 +101,8 @@ test('every name reaching a Bash matcher becomes Bash', () => {
 });
 
 test('write and search_replace map to different Claude tools', () => {
-  // The scaffold guard only fires on Write. Grok creates files with `write` and edits
-  // them with `search_replace`; conflating them would either disable the guard or make it
-  // reject the Edit-fill step the guard's own message tells the model to run.
+  // Grok creates files with `write` and edits them with `search_replace`; they must stay
+  // distinct Claude tools so a hook matcher on Write or on Edit sees the event it names.
   assert.equal(normalizeToolName('write'), 'Write');
   assert.equal(normalizeToolName('delete_file'), 'Write');
   assert.equal(normalizeToolName('search_replace'), 'Edit');

package/bin/__tests__/legacy-authority-decoupled.test.js

@@ -0,0 +1,154 @@
+'use strict';
+
+// The Stop gates and the session hooks must not depend on the completion-authority hook files,
+// so those files can be deleted without blocking every Stop or crashing SessionStart. Each case
+// runs against a real install (bin/install.js), with and without the five legacy files.
+
+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 INSTALLER = path.join(__dirname, '..', 'install.js');
+const LEGACY_FILES = [
+  'completion-authority.cjs',
+  'completion-authority-check.cjs',
+  'completion-authority-state.cjs',
+  'semantic-review-authority.cjs',
+  'task-scaffold-guard.cjs',
+];
+
+function inTempProject(run) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-decoupled-')));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'test@example.invalid'], ['config', 'user.name', 'Test'], ['commit', '--allow-empty', '-qm', 'base']]) {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    const installed = spawnSync(process.execPath, [INSTALLER, '--platform', 'claude,codex', '--yes'],
+      { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
+    assert.equal(installed.status, 0, `${installed.stdout}\n${installed.stderr}`);
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function removeLegacyFiles(root) {
+  for (const runtime of ['.claude', '.codex']) {
+    for (const file of LEGACY_FILES) {
+      const target = path.join(root, runtime, 'hooks', file);
+      fs.rmSync(target, { force: true });
+    }
+  }
+}
+
+function runHook(root, kind, script, event, extra = {}) {
+  const hook = path.join(root, kind === 'claude' ? '.claude' : '.codex', 'hooks', script);
+  const result = spawnSync(process.execPath, [hook], {
+    cwd: root,
+    input: JSON.stringify({ hook_event_name: event, session_id: 's', stop_hook_active: false, cwd: root, ...extra }),
+    env: { ...process.env, PATH: '/usr/bin:/bin', ...(kind === 'claude' ? { CLAUDE_PROJECT_DIR: root } : {}) },
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  return result.stdout.trim();
+}
+
+function stopGate(root, kind) {
+  return runHook(root, kind, 'spec-gate.cjs', 'Stop');
+}
+
+function isBlocked(stdout) {
+  return stdout !== '' && JSON.parse(stdout.split('\n').pop()).decision === 'block';
+}
+
+function blockReason(stdout) {
+  assert.equal(isBlocked(stdout), true, `expected a block, got: ${stdout}`);
+  return JSON.parse(stdout.split('\n').pop()).reason;
+}
+
+function provenance(root, taskFile) {
+  const result = spawnSync(process.execPath, [
+    path.join(root, '.claude', 'scripts', 'provenance.cjs'),
+    '--project-root', root, '--specs-root', 'specs', '--spec-file', taskFile,
+    '--feature-name', 'demo', '--session', 's', '--json',
+  ], { cwd: root, encoding: 'utf8' });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  const parsed = JSON.parse(result.stdout);
+  return { base: parsed.Base, head: parsed.Head };
+}
+
+function writeProcessFirst(root, { receipt }) {
+  const featureDir = path.join(root, 'specs', 'demo');
+  fs.mkdirSync(featureDir, { recursive: true });
+  fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\n');
+  const taskFile = path.join(featureDir, 'task-01-demo.md');
+  const body = ['# Task 01: demo', '', 'Status: done', '', '## Dependencies', '', '- none', '', '## Verification Plan', '', '- Command: node --test', ''];
+  fs.writeFileSync(taskFile, body.join('\n'));
+  if (!receipt) return;
+  const { base, head } = provenance(root, taskFile);
+  fs.writeFileSync(taskFile, [...body, '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${base}`, `Head: ${head}`, '```text', '$ node --test', 'pass: 1', '```', ''].join('\n'));
+}
+
+// A 2.1 packet keeps its machine state in spec.json and its tasks in a nested tasks/ directory.
+function writeLegacy(root, { status, doneTask = false }) {
+  const featureDir = path.join(root, 'specs', 'legacy');
+  fs.mkdirSync(path.join(featureDir, 'tasks'), { recursive: true });
+  const task = 'tasks/task-R1-01-legacy.md';
+  const spec = { schema_version: '2.1', feature_name: 'legacy', status, current_phase: 'implementation', task_registry: {} };
+  if (doneTask) spec.task_registry[task] = { status: 'done', completed_at: '2026-08-13T00:00:00.000Z', dependencies: [] };
+  fs.writeFileSync(path.join(featureDir, 'spec.json'), JSON.stringify(spec));
+  if (doneTask) {
+    fs.writeFileSync(path.join(featureDir, task), ['# Task R1-01: legacy', '**Status:** done', '## Outcome', 'Legacy work.',
+      '## Verification Plan', '- **Command:** `node --test`', '- **Expected:** passes', ''].join('\n'));
+  }
+}
+
+function checkProcessFirst(kind) {
+  inTempProject((root) => {
+    writeProcessFirst(root, { receipt: true });
+    assert.equal(stopGate(root, kind), '', 'valid receipt passes with the legacy files');
+    writeProcessFirst(root, { receipt: false });
+    assert.match(blockReason(stopGate(root, kind)), /missing_receipt/, 'no receipt blocks with the legacy files');
+    removeLegacyFiles(root);
+    assert.match(blockReason(stopGate(root, kind)), /missing_receipt/, 'no receipt blocks without the legacy files');
+    writeProcessFirst(root, { receipt: true });
+    assert.equal(stopGate(root, kind), '', 'valid receipt passes without the legacy files');
+  });
+}
+
+// CafeKit no longer reads spec.json packets: a leftover one, closed or mid-execution, never
+// blocks Stop on its own, and beside a process-first packet the decision is that packet's alone.
+function checkLegacyIgnored(kind) {
+  for (const legacy of [{ status: 'done' }, { status: 'completed' }, { status: 'in_progress', doneTask: true }]) {
+    inTempProject((root) => {
+      writeLegacy(root, legacy);
+      removeLegacyFiles(root);
+      assert.equal(stopGate(root, kind), '', `${kind} ${legacy.status} legacy packet alone`);
+      writeProcessFirst(root, { receipt: false });
+      const reason = blockReason(stopGate(root, kind));
+      assert.match(reason, /missing_receipt/);
+      assert.doesNotMatch(reason, /task-R1-01-legacy\.md/);
+      writeProcessFirst(root, { receipt: true });
+      assert.equal(stopGate(root, kind), '', `${kind} ${legacy.status} legacy packet beside a proven process-first packet`);
+    });
+  }
+}
+
+function checkSession(kind) {
+  inTempProject((root) => {
+    removeLegacyFiles(root);
+    runHook(root, kind, 'session.cjs', 'SessionStart', { source: 'startup' });
+  });
+}
+
+test('claude gate passes and blocks process-first with and without the legacy files', () => checkProcessFirst('claude'));
+test('codex gate passes and blocks process-first with and without the legacy files', () => checkProcessFirst('codex'));
+test('claude gate ignores a leftover legacy packet', () => checkLegacyIgnored('claude'));
+test('codex gate ignores a leftover legacy packet', () => checkLegacyIgnored('codex'));
+test('claude session starts without the legacy files', () => checkSession('claude'));
+test('codex session starts without the legacy files', () => checkSession('codex'));

package/bin/__tests__/legacy-hooks-retired.test.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// The five spec.json-era hooks (completion authority, its check and state modules, the semantic
+// review authority and the scaffold guard) are gone from every runtime. Each case pins one way
+// they could survive: a fresh install, an upgrade on Claude (settings prune matches by substring,
+// so a user's own hook with the same file name must stay), an upgrade on Codex (whose tracker
+// keys are `.codex/…` and whose handlers come in three shapes), an upgrade on omp, an omp bridge
+// that still lists the removed gates, and the source lists themselves.
+
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+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 SRC = path.join(PACKAGE_ROOT, 'src');
+const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const MANIFEST = readJson(path.join(SRC, 'claude/migration-manifest.json'));
+const SOURCE_SETTINGS = readJson(path.join(SRC, 'claude/settings/settings.json'));
+const SOURCE_BRIDGE_PATH = path.join(SRC, 'omp/extensions/cafekit-bridge.mjs');
+
+const NAMES = [
+  'completion-authority.cjs',
+  'completion-authority-check.cjs',
+  'completion-authority-state.cjs',
+  'semantic-review-authority.cjs',
+  'task-scaffold-guard.cjs',
+];
+const REGISTERED = ['completion-authority.cjs', 'semantic-review-authority.cjs', 'task-scaffold-guard.cjs'];
+const FOREIGN = REGISTERED.map((name) => `node ~/my-hooks/${name}`);
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-legacy-retired-'));
+  try {
+    const init = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+    assert.equal(init.status, 0, init.stderr);
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, platforms) {
+  const result = spawnSync(process.execPath, [INSTALLER, '--platform', platforms.join(','), '--yes'],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+}
+
+function commands(settings) {
+  return Object.values(settings.hooks || {})
+    .flat()
+    .flatMap((group) => (group.hooks || []).map((hook) => hook.command));
+}
+
+function mentionsName(text) {
+  return NAMES.filter((name) => text.includes(name));
+}
+
+test('fresh installs ship and register none of the five legacy hooks', () => {
+  inTempProject((root) => {
+    install(root, ['claude', 'codex', 'omp']);
+    for (const dir of ['.claude', '.codex', '.omp']) {
+      for (const name of NAMES) assert.equal(fs.existsSync(path.join(root, dir, 'hooks', name)), false, `${dir}/hooks/${name}`);
+    }
+    const claude = commands(readJson(path.join(root, '.claude', 'settings.json')));
+    const codex = commands(readJson(path.join(root, '.codex', 'hooks.json')));
+    for (const command of [...claude, ...codex]) assert.deepEqual(mentionsName(command), [], command);
+    const bridge = fs.readFileSync(path.join(root, '.omp', 'extensions', 'cafekit-bridge.mjs'), 'utf8');
+    assert.deepEqual(mentionsName(bridge), []);
+  });
+});
+
+test('claude upgrade removes the legacy hooks and their CafeKit entries but keeps foreign ones', () => {
+  inTempProject((root) => {
+    install(root, ['claude']);
+    const settingsPath = path.join(root, '.claude', 'settings.json');
+    const manifestPath = path.join(root, '.claude', 'cafekit-manifest.json');
+    const settings = readJson(settingsPath);
+    const kept = commands(settings);
+
+    const manifest = readJson(manifestPath);
+    for (const name of NAMES) {
+      fs.writeFileSync(path.join(root, '.claude', 'hooks', name), '// user edit\n');
+      manifest.files[`hooks/${name}`] = { sha256: '0'.repeat(64) };
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    const cmd = (name) => `node "$CLAUDE_PROJECT_DIR/.claude/hooks/${name}"`;
+    settings.hooks.UserPromptSubmit[0].hooks.push(
+      { type: 'command', command: cmd('completion-authority.cjs') },
+      ...FOREIGN.map((command) => ({ type: 'command', command })),
+    );
+    settings.hooks.Stop[0].hooks.push({ type: 'command', command: cmd('completion-authority.cjs') });
+    settings.hooks.PreToolUse.push({ matcher: 'Write', hooks: [{ type: 'command', command: cmd('task-scaffold-guard.cjs') }] });
+    settings.hooks.SubagentStop[0].hooks.push({ type: 'command', command: cmd('semantic-review-authority.cjs') });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+
+    install(root, ['claude']);
+    for (const name of NAMES) assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', name)), false, name);
+    const after = readJson(manifestPath);
+    for (const name of NAMES) assert.equal(Object.prototype.hasOwnProperty.call(after.files, `hooks/${name}`), false, `record ${name}`);
+    const afterCommands = commands(readJson(settingsPath));
+    for (const name of REGISTERED) {
+      assert.equal(afterCommands.some((command) => command.includes(`.claude/hooks/${name}`)), false, name);
+    }
+    for (const command of FOREIGN) assert.ok(afterCommands.includes(command), `foreign: ${command}`);
+    for (const command of kept) assert.ok(afterCommands.includes(command), `kept: ${command}`);
+  });
+});
+
+test('codex upgrade removes the legacy hooks, their records and their CafeKit entries but keeps foreign ones', () => {
+  inTempProject((root) => {
+    install(root, ['codex']);
+    const hooksPath = path.join(root, '.codex', 'hooks.json');
+    const manifestPath = path.join(root, '.codex', 'cafekit-manifest.json');
+    const config = readJson(hooksPath);
+    const kept = commands(config);
+
+    // A record whose file is already gone must leave the manifest too.
+    const manifest = readJson(manifestPath);
+    for (const name of NAMES) {
+      if (name !== 'completion-authority-state.cjs') fs.writeFileSync(path.join(root, '.codex', 'hooks', name), '// user edit\n');
+      manifest.files[`.codex/hooks/${name}`] = { sha256: '0'.repeat(64) };
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    const posix = kept.find((command) => command.includes('spec-gate.cjs'));
+    assert.ok(posix, 'the installed spec-gate launcher is the template for the POSIX form');
+    const add = (event, command) => config.hooks[event].push({ matcher: '*', hooks: [{ type: 'command', command }] });
+    add('Stop', posix.split('spec-gate.cjs').join('completion-authority.cjs'));
+    add('PreToolUse', 'node ".codex/hooks/task-scaffold-guard.cjs"');
+    add('SubagentStop', "node 'C:\\work\\proj\\.codex\\hooks\\semantic-review-authority.cjs'");
+    add('UserPromptSubmit', FOREIGN[0]);
+    fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2));
+
+    install(root, ['codex']);
+    for (const name of NAMES) assert.equal(fs.existsSync(path.join(root, '.codex', 'hooks', name)), false, name);
+    const after = readJson(manifestPath);
+    for (const name of NAMES) assert.equal(Object.prototype.hasOwnProperty.call(after.files, `.codex/hooks/${name}`), false, `record ${name}`);
+    const afterCommands = commands(readJson(hooksPath));
+    for (const name of REGISTERED) {
+      assert.equal(afterCommands.some((command) => command.includes(`.codex/hooks/${name}`) || command.includes(`.codex\\hooks\\${name}`)), false, name);
+    }
+    assert.ok(afterCommands.includes(FOREIGN[0]), 'a foreign hook with a legacy name survives');
+    for (const command of kept) assert.ok(afterCommands.includes(command), `kept: ${command}`);
+  });
+});
+
+test('omp upgrade removes the legacy hooks and their records', () => {
+  inTempProject((root) => {
+    install(root, ['omp']);
+    const manifestPath = path.join(root, '.omp', 'cafekit-manifest.json');
+    const manifest = readJson(manifestPath);
+    // omp records keys relative to the project root (recordRoot '.').
+    for (const name of NAMES) {
+      fs.writeFileSync(path.join(root, '.omp', 'hooks', name), '// shipped by an older CafeKit\n');
+      manifest.files[`.omp/hooks/${name}`] = { sha256: '0'.repeat(64) };
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    install(root, ['omp']);
+    const after = readJson(manifestPath);
+    for (const name of NAMES) {
+      assert.equal(fs.existsSync(path.join(root, '.omp', 'hooks', name)), false, name);
+      assert.equal(Object.prototype.hasOwnProperty.call(after.files, `.omp/hooks/${name}`), false, `record ${name}`);
+    }
+  });
+});
+
+test('omp upgrade replaces a pristine old bridge that still lists the removed gates', () => {
+  inTempProject((root) => {
+    install(root, ['omp']);
+    const bridgePath = path.join(root, '.omp', 'extensions', 'cafekit-bridge.mjs');
+    const manifestPath = path.join(root, '.omp', 'cafekit-manifest.json');
+    const old = fs.readFileSync(SOURCE_BRIDGE_PATH, 'utf8')
+      .replace("'inspect-block.cjs']", "'inspect-block.cjs', 'task-scaffold-guard.cjs']")
+      .replace("'rules.cjs', 'spec-state.cjs'", "'rules.cjs', 'completion-authority.cjs', 'spec-state.cjs'")
+      .replace("'spec-gate.cjs', 'state.cjs'", "'spec-gate.cjs', 'completion-authority.cjs', 'state.cjs'");
+    assert.deepEqual(mentionsName(old).sort(), ['completion-authority.cjs', 'task-scaffold-guard.cjs'], 'the fixture lists the removed gates');
+    fs.writeFileSync(bridgePath, old);
+    const manifest = readJson(manifestPath);
+    manifest.files['.omp/extensions/cafekit-bridge.mjs'] = { sha256: crypto.createHash('sha256').update(old).digest('hex') };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    install(root, ['omp']);
+    const installed = fs.readFileSync(bridgePath, 'utf8');
+    assert.deepEqual(mentionsName(installed), []);
+    assert.equal(installed, fs.readFileSync(SOURCE_BRIDGE_PATH, 'utf8'));
+  });
+});
+
+test('no source ships, registers or bridges the five legacy hooks', () => {
+  for (const name of NAMES) {
+    assert.equal(fs.existsSync(path.join(SRC, 'claude/hooks', name)), false, `claude ${name}`);
+    assert.equal(fs.existsSync(path.join(SRC, 'codex/hooks', name)), false, `codex ${name}`);
+  }
+  for (const test of ['completion-authority.test.js', 'semantic-review-authority.test.js']) {
+    assert.equal(fs.existsSync(path.join(SRC, 'claude/hooks/__tests__', test)), false, test);
+  }
+  const runtimeFiles = MANIFEST.runtime.files.join('\n');
+  assert.deepEqual(mentionsName(runtimeFiles), []);
+  assert.deepEqual(mentionsName(JSON.stringify(SOURCE_SETTINGS)), []);
+  assert.deepEqual(mentionsName(fs.readFileSync(path.join(SRC, 'codex/hooks.json'), 'utf8')), []);
+  assert.deepEqual(mentionsName(fs.readFileSync(SOURCE_BRIDGE_PATH, 'utf8')), []);
+  for (const name of NAMES) assert.ok(MANIFEST.obsolete.runtimeFiles.includes(`hooks/${name}`), name);
+  const substrings = MANIFEST.obsolete.settingsHookCommandSubstrings;
+  assert.equal(substrings[0], 'hooks/skill-router.cjs');
+  for (const name of REGISTERED) {
+    for (const entry of [`.claude/hooks/${name}`, `.codex/hooks/${name}`, `.codex\\hooks\\${name}`]) {
+      assert.ok(substrings.includes(entry), entry);
+    }
+  }
+  // The installer's merge drops an empty group, so only the source can show one.
+  for (const [event, groups] of Object.entries(SOURCE_SETTINGS.hooks)) {
+    for (const group of groups) assert.ok(group.hooks.length > 0, `${event} ${group.matcher} has no hooks`);
+  }
+});

package/bin/__tests__/omp-bridge.test.js

@@ -17,7 +17,6 @@ const PACKAGE_ROOT = path.join(__dirname, '../..');
 const BRIDGE = path.join(PACKAGE_ROOT, 'src/omp/extensions/cafekit-bridge.mjs');
 const SETTINGS = require(path.join(PACKAGE_ROOT, 'src/claude/settings/settings.json'));
 const MANIFEST = require(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'));
-const { PREFIX } = require(path.join(PACKAGE_ROOT, 'src/claude/hooks/completion-authority-state.cjs'));
 
 /**
  * The hooks an omp install runs: the Claude set the manifest ships, then `src/omp/hooks/`
@@ -50,6 +49,11 @@ function registered(eventName) {
     .filter(Boolean);
 }
 
+// Deliberate, named divergences while omp is not yet updated. Each must still be a real
+// difference, so the test fails (and the entry must go) once omp catches up.
+const CLAUDE_ONLY = { PostToolUse: ['spec-state.cjs'] };
+const OMP_ONLY = { SessionStart: ['docs-sync.cjs'] };
+
 test('the dispatch table mirrors settings.json for every event omp can deliver', () => {
   const { DISPATCH } = bridge;
   const pairs = [
@@ -58,8 +62,18 @@ test('the dispatch table mirrors settings.json for every event omp can deliver',
     ['tool_result', 'PostToolUse'], ['session_stop', 'Stop'],
   ];
   for (const [omp, claude] of pairs) {
-    assert.deepEqual([...DISPATCH[omp].hooks].sort(), [...new Set(registered(claude))].sort(),
-      `${omp} must dispatch exactly the hooks settings.json registers for ${claude}`);
+    const claudeOnly = CLAUDE_ONLY[claude] || [];
+    const ompOnly = OMP_ONLY[claude] || [];
+    const claudeHooks = [...new Set(registered(claude))];
+    for (const hook of claudeOnly) {
+      assert.ok(claudeHooks.includes(hook) && !DISPATCH[omp].hooks.includes(hook), `${hook} is no longer Claude-only for ${claude}; drop it from CLAUDE_ONLY`);
+    }
+    for (const hook of ompOnly) {
+      assert.ok(!claudeHooks.includes(hook) && DISPATCH[omp].hooks.includes(hook), `${hook} is no longer omp-only for ${claude}; drop it from OMP_ONLY`);
+    }
+    const expected = [...claudeHooks.filter((hook) => !claudeOnly.includes(hook)), ...ompOnly].sort();
+    assert.deepEqual([...DISPATCH[omp].hooks].sort(), expected,
+      `${omp} must dispatch the hooks settings.json registers for ${claude}, minus CLAUDE_ONLY, plus OMP_ONLY`);
   }
   // omp has no subagent events; the gap is deliberate and documented, not forgotten.
   assert.ok(!Object.values(DISPATCH).some((e) => e.event.startsWith('Subagent')));
@@ -83,7 +97,7 @@ test('each denial mechanism becomes an omp block carrying the hook reason', () =
   assert.deepEqual([stop.block, stop.reason], [true, 'R1']);
   const deny = interpretVerdict({ code: 0, stdout: JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: 'R2' } }) }, 'privacy-block.cjs');
   assert.deepEqual([deny.block, deny.reason], [true, 'R2']);
-  // inspect-block / task-scaffold-guard exit 2 and write the reason on STDOUT, not stderr.
+  // inspect-block exits 2 and writes the reason on STDOUT, not stderr.
   const exit2 = interpretVerdict({ code: 2, stdout: 'SCOPE LIMIT EXCEEDED\nRestricted zones: node_modules', stderr: '' }, 'inspect-block.cjs');
   assert.equal(exit2.block, true);
   assert.match(exit2.reason, /SCOPE LIMIT EXCEEDED/, 'a stderr-only reader would drop this reason');
@@ -127,10 +141,10 @@ test('a slow hook blocks with its own name before omp cuts it off', async () =>
 test('a crashing or missing gate blocks on gating events instead of silently allowing', async () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-omp-crash-'));
   try {
-    // Only the crashing gate is under test; the other two PreToolUse gates get allow stubs,
+    // Only the crashing gate is under test; the other PreToolUse gate gets an allow stub,
     // otherwise their absence is what blocks (see the missing-gate case below).
     fs.writeFileSync(path.join(dir, 'privacy-block.cjs'), 'throw new Error("boom");');
-    for (const stub of ['inspect-block.cjs', 'task-scaffold-guard.cjs']) fs.writeFileSync(path.join(dir, stub), 'process.exit(0);');
+    fs.writeFileSync(path.join(dir, 'inspect-block.cjs'), 'process.exit(0);');
     const crash = await bridge.runEvent('tool_call', { toolName: 'bash', input: { command: 'ls' } }, { cwd: dir }, { dir });
     // A bare exit 1 with no verdict is an allow under the hooks' own contract. Real gates
     // never surface a crash this way: the fork's privacy-block catch-all converts its own
@@ -147,17 +161,6 @@ test('stop_hook_active short-circuits the gate so a blocked turn cannot loop for
   assert.deepEqual([r.block, r.skipped], [false, 'stop_hook_active']);
 });
 
-test('the approval phrase reaches completion-authority through the input event', async () => {
-  const { DISPATCH, shapePayload } = bridge;
-  assert.ok(DISPATCH.input.hooks.includes('completion-authority.cjs'),
-    'the --approve path only runs on UserPromptSubmit; without this routing a blocked turn has no exit');
-  const phrase = `${PREFIX}${'a'.repeat(24)}`;
-  const p = shapePayload('input', { text: phrase, source: 'user' }, { cwd: '/tmp/p' });
-  assert.equal(p.hook_event_name, 'UserPromptSubmit', 'completion-authority selects --approve from this field');
-  assert.equal(p.prompt, phrase, 'the phrase must arrive byte-exact; the hook compares it exactly');
-  assert.ok(p.session_id, 'approve() returns early without a session id');
-});
-
 test('input injections flow back as a transform that keeps the user text intact', async () => {
   const root = tempProject(false);
   try {