@haposoft/cafekit 0.18.0 → 0.18.2

package/bin/__tests__/codex-projection-parity.test.js

@@ -0,0 +1,314 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+const { spawnSync } = require('node:child_process');
+const Module = require('node:module');
+const { convertCodexAgentContent, normalizeCodexBody } = require('../lib/codex-install');
+const { sha256 } = require('../lib/manifest');
+
+const ROOT = path.resolve(__dirname, '../..');
+const STRATEGIST = fs.readFileSync(path.join(ROOT, 'src/claude/agents/strategist.md'), 'utf8');
+const { splitFrontmatter } = require('../lib/codex-frontmatter');
+
+function withInstalledSkills(check) {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-routing-description-'));
+  try {
+    const result = spawnSync(process.execPath, [path.join(ROOT, 'bin/install.js'), '--platform', 'codex', '--with-document-skills', '-y'], { cwd: temp, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    check(temp);
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+function installedInstructionText(temp) {
+  const read = directory => fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) return read(file);
+    if (!/\.(?:md|toml)$/.test(file)) return [];
+    let content = fs.readFileSync(file, 'utf8');
+    if (file.endsWith('.toml')) {
+      content = content.replace(/^developer_instructions = (.+)$/m, (_line, value) => JSON.parse(value));
+    }
+    return [[path.relative(temp, file), content.replace(/\s+/g, ' ')]];
+  });
+  return [...read(path.join(temp, '.agents/skills')), ...read(path.join(temp, '.codex'))];
+}
+
+for (const [label, needle] of [
+  ['duplicate runtime roots', /(\.codex\/?)[\s,`]+\1/],
+  ['duplicate instruction filenames', /(`?AGENTS\.md`?)[\s,]+\1/],
+  ['AskUserQuestion', /AskUserQuestion/],
+  ['structured user-input', /structured user-input/],
+  ['native input tool', /native input tool/],
+  ['native structured', /native structured/],
+  ['Codex CLI own worktree', /Codex CLI's own worktree/],
+  ['runtime-specific nested worktree path', /\.codex\/worktrees\//]
+]) {
+  test(`installed Codex instruction corpus excludes ${label}`, () => {
+    withInstalledSkills(temp => {
+      const matches = installedInstructionText(temp).filter(([_file, text]) => needle.test(text)).map(([file]) => file);
+      assert.deepEqual(matches, [], label);
+    });
+  });
+}
+
+for (const needle of ['send_message(type', 'shutdown_', 'task-state inspection']) {
+  test(`installed Codex agents omit Team protocol ${needle}`, () => {
+    withInstalledSkills(temp => {
+      for (const name of ['git_ops', 'project_manager']) {
+        const text = fs.readFileSync(path.join(temp, '.codex/agents', `${name}.toml`), 'utf8');
+        assert.ok(!text.includes(needle), name);
+      }
+    });
+  });
+}
+
+test('installed Codex agents retain force-push and planning-owner boundaries', () => {
+  withInstalledSkills(temp => {
+    const texts = new Map(installedInstructionText(temp));
+    assert.ok(texts.get('.codex/agents/git_ops.toml').includes('NEVER arbitrarily use `force push` unless explicitly and securely designated.'));
+    assert.ok(texts.get('.codex/agents/project_manager.toml').includes('You aggregate after GATE-REVIEW and during explicitly invoked execution. An incomplete packet returns to the planning owner; do not expand it yourself.'));
+    assert.doesNotMatch(texts.get('.codex/agents/git_ops.toml'), /## Team Mode\s+3\. /);
+  });
+});
+
+test('installed Brainstorm asks a question in the final answer without a runtime possessive', () => {
+  withInstalledSkills(temp => {
+    for (const relative of ['SKILL.md', 'references/question-framework.md']) {
+      const text = fs.readFileSync(path.join(temp, '.agents/skills/brainstorm', relative), 'utf8').replace(/\s+/g, ' ');
+      assert.ok(text.includes("Use a question in the turn's final answer when available."), relative);
+      assert.ok(!text.includes("the runtime's question"), relative);
+    }
+  });
+});
+
+test('installed Codex host lists retain Claude names alongside converted single-host paths', () => {
+  withInstalledSkills(temp => {
+    const texts = new Map(installedInstructionText(temp));
+    assert.match(texts.get('.agents/skills/git/references/worktree-blueprint.md'), /\.claude/);
+    assert.match(texts.get('.agents/skills/ask/SKILL.md'), /CLAUDE\.md/);
+    assert.match(texts.get('.agents/skills/docs/references/init-workflow.md'), /\.codex\/scripts\//);
+  });
+});
+
+test('host-list preservation applies only to instruction assets including a missing source path', () => {
+  const source = 'Copy `.claude/`, `.codex/`; read `CLAUDE.md`, `AGENTS.md`; run `.claude/scripts/check.cjs`.';
+  const expected = 'Copy `.claude/`, `.codex/`; read `CLAUDE.md`, `AGENTS.md`; run `.codex/scripts/check.cjs`.';
+  assert.equal(normalizeCodexBody(source), expected);
+  assert.equal(normalizeCodexBody(source, 'guide.md'), expected);
+  assert.equal(normalizeCodexBody(source, 'script.cjs'), 'Copy `.codex/`, `.codex/`; read `AGENTS.md`, `AGENTS.md`; run `.codex/scripts/check.cjs`.');
+});
+
+test('standalone host filenames do not prevent conversion of a single-host file path on the same line', () => {
+  assert.equal(normalizeCodexBody('Read `CLAUDE.md`, `AGENTS.md`; load `.claude/CLAUDE.md`.', 'guide.md'),
+    'Read `CLAUDE.md`, `AGENTS.md`; load `.codex/AGENTS.md`.');
+});
+
+test('installed Codex catalog help labels the shared skills root for Codex', () => {
+  withInstalledSkills(temp => {
+    const result = spawnSync(process.execPath, ['.codex/scripts/generate-skill-catalog.cjs', '--help'], { cwd: temp, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stdout.replace(/\s+/g, ' '), /\.agents\/skills for Claude/);
+    assert.match(result.stdout, /\.agents\/skills for Codex/);
+  });
+});
+
+test('installed skill descriptions carry Use when within the routing length limit', () => {
+  withInstalledSkills(temp => {
+    let checked = 0;
+    for (const name of fs.readdirSync(path.join(temp, '.agents/skills'))) {
+      const installed = path.join(temp, '.agents/skills', name, 'SKILL.md');
+      const source = path.join(ROOT, 'src/claude/skills', name, 'SKILL.md');
+      if (!fs.existsSync(installed) || !fs.existsSync(source)) continue;
+      const { frontmatter } = splitFrontmatter(fs.readFileSync(source, 'utf8'));
+      if (!frontmatter.when_to_use) continue;
+      const expected = `${normalizeCodexBody(frontmatter.description)} Use when: ${normalizeCodexBody(frontmatter.when_to_use)}`;
+      if (expected.length > 1024) continue;
+      const actual = JSON.parse(fs.readFileSync(installed, 'utf8').match(/^description: (.+)$/m)[1]);
+      const boundary = name === 'ask' ? ' A request to fix or change something is still answered without editing any file; point the user to $cf-fix.' : '';
+      assert.equal(actual, expected + boundary, name);
+      assert.ok(actual.length <= 1024, name);
+      checked++;
+    }
+    assert.ok(checked >= 18);
+  });
+});
+
+test('brainstorm description stays unchanged when Use when exceeds the routing length limit', () => {
+  withInstalledSkills(temp => {
+    const source = splitFrontmatter(fs.readFileSync(path.join(ROOT, 'src/claude/skills/brainstorm/SKILL.md'), 'utf8')).frontmatter;
+    assert.ok(`${source.description} Use when: ${source.when_to_use}`.length > 1024);
+    const installed = splitFrontmatter(fs.readFileSync(path.join(temp, '.agents/skills/brainstorm/SKILL.md'), 'utf8')).frontmatter;
+    assert.equal(installed.description, source.description);
+  });
+});
+
+for (const name of ['agent-browser', 'chrome-devtools', 'web-testing']) {
+  test(`installed ${name} description serializes Use when as a JSON string`, () => {
+    withInstalledSkills(temp => {
+      const content = fs.readFileSync(path.join(temp, '.agents/skills', name, 'SKILL.md'), 'utf8');
+      const description = JSON.parse(content.match(/^description: (.+)$/m)[1]);
+      const source = splitFrontmatter(fs.readFileSync(path.join(ROOT, 'src/claude/skills', name, 'SKILL.md'), 'utf8')).frontmatter;
+      assert.ok(description.endsWith(`Use when: ${normalizeCodexBody(source.when_to_use)}`));
+    });
+  });
+}
+
+test('Codex catalog emits the fix Use when text only once', () => {
+  withInstalledSkills(temp => {
+    const result = spawnSync(process.execPath, ['.codex/scripts/generate-skill-catalog.cjs', '--skills'], { cwd: temp, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    const when = normalizeCodexBody(splitFrontmatter(fs.readFileSync(path.join(ROOT, 'src/claude/skills/fix/SKILL.md'), 'utf8')).frontmatter.when_to_use);
+    assert.equal(result.stdout.split(when).length - 1, 1);
+  });
+});
+
+test('Use when projection applies without a source path and preserves quoted metadata', () => {
+  const source = '---\nname: cf:example\ndescription: Choose "one" option.\nwhen_to_use: When evidence is available.\n---\nBody\n';
+  const projected = normalizeCodexBody(source);
+  assert.equal(JSON.parse(projected.match(/^description: (.+)$/m)[1]), 'Choose "one" option. Use when: When evidence is available.');
+});
+
+test('strategist inherits native model, configures high reasoning and keeps advisory boundaries', () => {
+  const projected = convertCodexAgentContent(STRATEGIST, 'strategist.md');
+  assert.match(projected, /^model_reasoning_effort = "high"$/m);
+  assert.doesNotMatch(projected, /^model\s*=/m);
+  assert.doesNotMatch(projected, /fable|opus|sonnet|haiku|CLAUDE_CODE_SUBAGENT_MODEL|strongest available model|model override/);
+  assert.match(projected, /inherits the session model/);
+  assert.match(projected, /Advisory-only/);
+  assert.match(projected, /never implement, scaffold, or edit project files/);
+  assert.match(projected, /spawn_agent\(agent_type=\\"explorer\\", fork_turns=\\"none\\"/);
+});
+
+test('instruction projection converts Explore shorthand and native model guidance without rewriting executable code', () => {
+  const instruction = '`Task(Explore)`; set `CLAUDE_CODE_SUBAGENT_MODEL` in project settings.';
+  const converted = normalizeCodexBody(instruction, 'guide.md');
+  assert.doesNotMatch(converted, /Task\(Explore\)|CLAUDE_CODE_SUBAGENT_MODEL/);
+  assert.match(converted, /spawn_agent\(agent_type="explorer", fork_turns="none"/);
+  assert.match(converted, /configured agent model/);
+  assert.equal(normalizeCodexBody(instruction, 'script.js'), instruction);
+});
+
+for (const state of ['pristine', 'modified', 'untracked', 'dry-run']) {
+  test(`retired Codex init.json migration: ${state}`, () => {
+    const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-projection-'));
+    const relative = '.agents/skills/specs/templates/init.json';
+    const target = path.join(temp, relative);
+    const original = '{"legacy":true}\n';
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, state === 'modified' ? '{"custom":true}\n' : original);
+    const custom = path.join(path.dirname(target), 'my-custom-template.json');
+    fs.writeFileSync(custom, '{"keep":true}\n');
+    const before = fs.readFileSync(target, 'utf8');
+    const runner = `
+      const { copyPlatformFiles } = require(${JSON.stringify(path.join(ROOT, 'bin/phases/copy-payload'))});
+      const { createTracker } = require(${JSON.stringify(path.join(ROOT, 'bin/lib/manifest'))});
+      const tracker = createTracker('.codex', 'test', { recordRoot: '.', allowedRoots: ['.codex', '.agents'] });
+      const ctx = {
+        dryRun: ${state === 'dry-run'}, options: {},
+        manifest: { skills: { required: [] }, agents: { required: [] } },
+        ownership: { '.codex': { files: ${JSON.stringify(state === 'untracked' ? {} : { [relative]: { sha256: sha256(original) } })} } },
+        trackers: { codex: tracker },
+        ui: { detail() {}, warn() {}, error() {} },
+        results: { installedSkills: 0, copied: 0, updated: 0, unchanged: 0, preserved: 0, missingDependencies: 0, preservedFiles: [] }
+      };
+      copyPlatformFiles(ctx, 'codex');
+      if (${JSON.stringify(state)} !== 'dry-run' && !tracker._pruned.has(${JSON.stringify(relative)})) throw new Error('ownership baseline was not pruned');
+    `;
+    try {
+      const result = spawnSync(process.execPath, ['-e', runner], { cwd: temp, encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+      if (state !== 'dry-run') assert.equal(fs.existsSync(target), false);
+      else assert.equal(fs.readFileSync(target, 'utf8'), before);
+      assert.equal(fs.readFileSync(custom, 'utf8'), '{"keep":true}\n');
+    } finally {
+      fs.rmSync(temp, { recursive: true, force: true });
+    }
+  });
+}
+
+test('shared and projected provenance ignore native generated roots while retaining source changes', () => {
+  const sourcePath = path.join(ROOT, 'src/claude/scripts/provenance.cjs');
+  const source = fs.readFileSync(sourcePath, 'utf8');
+  const projected = new Module(sourcePath);
+  projected._compile(normalizeCodexBody(source, sourcePath), sourcePath);
+  for (const runtime of [require(sourcePath), projected.exports]) {
+    const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-provenance-projection-'));
+    const paths = ['.claude/runtime.json', '.claude/hooks/.logs/session.json', '.claude/.logs/events.json',
+      '.codex/session-state/session/context.json', '.codex/hooks/.privacy/request.json'];
+    const write = (relative, data) => {
+      const target = path.join(temp, relative);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, data);
+    };
+    const git = (...args) => {
+      const result = spawnSync('git', ['-C', temp, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+      return result.stdout;
+    };
+    try {
+      write('app.js', 'export const value = 1;\n');
+      write('specs/feature/plan.md', '# Feature\n');
+      for (const relative of paths) write(relative, '{}\n');
+      git('init', '--quiet'); git('add', '.');
+      git('-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.test', 'commit', '--quiet', '-m', 'baseline');
+      const input = { projectRoot: temp, specsRoot: path.join(temp, 'specs'),
+        specFile: path.join(temp, 'specs/feature/plan.md'), featureName: 'feature', runtimeSession: 'fixture' };
+      const baseline = runtime.deriveRuntimeProvenance(input).Head;
+      const capturedGenerated = [];
+      for (const relative of paths) {
+        write(relative, '{"generated":true}\n');
+        assert.match(git('status', '--porcelain', '--', relative), /M/);
+        if (runtime.deriveRuntimeProvenance(input).Head !== baseline) capturedGenerated.push(relative);
+        write(relative, '{}\n');
+      }
+      write('app.js', 'export const value = 2;\n');
+      assert.notEqual(runtime.deriveRuntimeProvenance(input).Head, baseline);
+      assert.deepEqual(capturedGenerated, [], 'generated state changed Head');
+    } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+  }
+});
+
+test('optional env functions read fake native runtime global env on Claude and projected Codex', () => {
+  const python = `import ast, json, sys
+from pathlib import Path
+from types import SimpleNamespace
+case = json.load(sys.stdin)
+tree = ast.parse(case['source'])
+function = next(node for node in tree.body if isinstance(node, ast.FunctionDef) and node.name == case['function'])
+env = {}
+loaded = []
+def load_dotenv(target):
+    loaded.append(str(target))
+    env['GEMINI_API_KEY'] = Path(target).read_text().strip()
+scope = {'Path': Path, 'Optional': __import__('typing').Optional, '__file__': case['script'],
+         'os': SimpleNamespace(getenv=lambda key: env.get(key)), 'load_dotenv': load_dotenv}
+exec(compile(ast.Module(body=[function], type_ignores=[]), '<fixture>', 'exec'), scope)
+result = scope[case['function']]()
+assert (result if case['function'] == 'find_api_key' else env.get('GEMINI_API_KEY')) == 'fixture-native-key', loaded
+assert loaded == [case['expected']], loaded
+`;
+  for (const [file, functionName] of [['media_optimizer.py', 'load_env_files'], ['document_converter.py', 'find_api_key']]) {
+    const sourcePath = path.join(ROOT, 'src/claude/skills/ai-multimodal/scripts', file);
+    const original = fs.readFileSync(sourcePath, 'utf8');
+    for (const native of ['claude', 'codex']) {
+      const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-native-env-'));
+      try {
+        const expected = path.join(temp, `.${native}`, '.env');
+        fs.mkdirSync(path.dirname(expected), { recursive: true });
+        fs.writeFileSync(expected, 'fixture-native-key');
+        const script = path.join(temp, native === 'claude' ? '.claude/skills' : '.agents/skills', 'ai-multimodal/scripts', file);
+        const result = spawnSync('python3', ['-c', python], { encoding: 'utf8', input: JSON.stringify({
+          source: native === 'claude' ? original : normalizeCodexBody(original, sourcePath),
+          function: functionName, script, expected
+        }) });
+        assert.equal(result.status, 0, `${native}/${file}: ${result.stderr}`);
+      } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+    }
+  }
+});

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

@@ -0,0 +1,170 @@
+'use strict';
+
+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 SOURCE = path.resolve(__dirname, '../../src');
+
+function fixture({ specs = 'specs', packets = ['auth-flow'] } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-codex-quiet-'));
+  const hooks = path.join(root, '.codex/hooks');
+  fs.cpSync(path.join(SOURCE, 'codex/hooks'), hooks, { recursive: true });
+  for (const name of ['privacy-paths.cjs', 'privacy-command-analysis.cjs']) {
+    fs.copyFileSync(path.join(SOURCE, 'claude/hooks/lib', name), path.join(hooks, 'lib', name));
+  }
+  fs.copyFileSync(path.join(SOURCE, 'claude/hooks/lib/spec-touch.cjs'), path.join(hooks, 'lib/spec-touch.cjs'));
+  fs.copyFileSync(path.join(SOURCE, 'claude/hooks/lib/secret-keywords.cjs'), path.join(hooks, 'lib/secret-keywords.cjs'));
+  fs.copyFileSync(path.join(SOURCE, 'claude/hooks/lib/update-check.cjs'), path.join(hooks, 'lib/update-check.cjs'));
+  fs.copyFileSync(path.join(SOURCE, 'claude/hooks/lib/runtime-path-safety.cjs'), path.join(hooks, 'lib/runtime-path-safety.cjs'));
+  fs.cpSync(path.join(SOURCE, 'claude/scripts'), path.join(root, '.codex/scripts'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.codex/runtime.json'), JSON.stringify({ paths: { specs } }));
+  fs.writeFileSync(path.join(root, '.gitignore'), '.codex/\n');
+  for (const args of [['init', '-q'], ['config', 'user.email', 'probe@example.invalid'], ['config', 'user.name', 'Probe'], ['add', '.gitignore'], ['commit', '-qm', 'base']]) {
+    const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+  }
+  for (const name of packets) {
+    const dir = path.join(root, specs, name); fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'plan.md'), '# Plan\nSpecs-Contract: process-first-ready-v1\n');
+    fs.writeFileSync(path.join(dir, 'task-01-work.md'), '# Work\nStatus: pending\n## Dependencies\n- none\n## Verification Plan\n- Command: node --test\n');
+  }
+  const run = (hook, payload, cwd = root) => {
+    const result = spawnSync(process.execPath, [path.join(hooks, `${hook}.cjs`)], {
+      cwd, input: JSON.stringify({ cwd, ...payload }), encoding: 'utf8',
+    });
+    assert.equal(result.status, 0, result.stderr);
+    return result.stdout.trim();
+  };
+  return { root, hooks, specs, run, prompt: (id, prompt, more = {}) => run('spec-state', { hook_event_name: 'UserPromptSubmit', session_id: id, prompt, ...more }), cleanup: () => fs.rmSync(root, { recursive: true, force: true }) };
+}
+function within(options, fn) { const fx = fixture(options); try { fn(fx); } finally { fx.cleanup(); } }
+// Native shape pinned by openai/codex apply-patch tests: string stdout summary,
+// not the empty object code mode returns (core/src/tools/context.rs).
+function patch(fx, session, command, response, cwd = fx.root) {
+  if (response === undefined) {
+    const files = [];
+    for (const line of command.split('\n')) {
+      const header = line.match(/^\*\*\* (Add|Update|Delete) File: (.+)$/);
+      if (header) files.push(`${{ Add: 'A', Update: 'M', Delete: 'D' }[header[1]]} ${header[2]}`);
+      else if (line.startsWith('*** Move to: ')) files[files.length - 1] = `M ${line.slice(13)}`;
+    }
+    response = `Success. Updated the following files:\n${files.join('\n')}\n`;
+  }
+  return fx.run('spec-state', { hook_event_name: 'PostToolUse', session_id: session, tool_name: 'apply_patch', tool_input: { command }, tool_response: response }, cwd);
+}
+function snapshot(fx, id, content, generated = new Date().toISOString()) {
+  const dir = path.join(fx.root, '.codex/session-state', crypto.createHash('sha256').update(id).digest('hex'));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'latest.md'), `# Session State\n<!-- Generated: ${generated} -->\n${content}\n`);
+}
+
+test('untouched sessions remain quiet even beside malformed and multiple active packets', () => {
+  within({ packets: ['auth-flow', 'billing-2'] }, (fx) => {
+    fs.writeFileSync(path.join(fx.root, 'specs/billing-2/task-01-work.md'), 'Status: invented\n');
+    assert.equal(fx.prompt('a', 'Explain README'), '');
+    assert.match(fx.prompt('a', '$cf-develop auth-flow'), /Spec state changed: `auth-flow`/);
+    assert.equal(fx.prompt('b', 'Continue'), '');
+    assert.match(fx.prompt('a', 'Continue'), /auth-flow/);
+  });
+});
+test('named packets narrow relevant ambiguity and explicit targets are remembered', () => {
+  within({ packets: ['auth-flow', 'billing-2'] }, (fx) => {
+    fs.mkdirSync(path.join(fx.root, 'specs/_shared'));
+    fs.writeFileSync(path.join(fx.root, 'specs/_shared/active-feature.json'), '{"featureName":"billing-2"}');
+    assert.match(fx.prompt('a', '/cf:develop auth-flow'), /Spec state changed: `auth-flow`/);
+    assert.match(fx.prompt('a', 'specs/billing-2'), /Spec state changed: `billing-2`/);
+    assert.match(fx.prompt('a', 'Continue'), /Multiple active specs/);
+    assert.match(fx.prompt('b', 'Continue', { explicitPath: 'specs/auth-flow/plan.md' }), /auth-flow/);
+    assert.match(fx.prompt('b', 'Continue'), /auth-flow/);
+    assert.match(fx.prompt('c', 'Continue', { explicitFeature: 'billing-2' }), /billing-2/);
+  });
+});
+test('native successful add/update/delete/move patches touch silently without loading policy or resolver', () => {
+  within({ packets: ['auth-flow', 'billing-2'] }, (fx) => {
+    fs.writeFileSync(path.join(fx.root, '.codex/scripts/workflow-policy.cjs'), 'throw new Error("must not load");');
+    fs.writeFileSync(path.join(fx.root, '.codex/scripts/spec-resolver.cjs'), 'throw new Error("must not resolve");');
+    for (const [session, body] of [
+      ['add', '*** Add File: specs/auth-flow/new.md\n+new'],
+      ['update', '*** Update File: specs/auth-flow/plan.md\n@@\n-old\n+new'],
+      ['delete', '*** Delete File: specs/auth-flow/deleted.md'],
+      ['move', '*** Update File: specs/auth-flow/old.md\n*** Move to: specs/billing-2/new.md\n@@\n-old\n+new'],
+    ]) assert.equal(patch(fx, session, `*** Begin Patch\n${body}\n*** End Patch`), '');
+    const records = fs.readdirSync(path.join(fx.hooks, '.logs')).filter((name) => name.startsWith('spec-touched-'));
+    assert.equal(records.length, 4);
+    assert.ok(records.some((name) => JSON.parse(fs.readFileSync(path.join(fx.hooks, '.logs', name))).length === 2));
+    assert.ok(!fs.existsSync(path.join(fx.hooks, '.logs/hook-log.jsonl')));
+  });
+});
+test('failed, malformed, shell and unrelated tool payloads never touch', () => {
+  within({}, (fx) => {
+    const command = '*** Begin Patch\n*** Add File: specs/auth-flow/new.md\n+new\n*** End Patch';
+    for (const response of [null, {}, 'unknown', 'Error: Failed to apply patch', { content: [{ type: 'text', text: 'Failed to find expected lines' }] }, { isError: true }, { success: false }, { exit_code: 1 }, { error: 'failed' }]) assert.equal(patch(fx, 'a', command, response), '');
+    for (const invalid of ['echo specs/auth-flow', '*** Begin Patch\n*** Add File: specs/auth-flow/new.md\n*** End Patch']) assert.equal(patch(fx, 'a', invalid), '');
+    fx.run('spec-state', { hook_event_name: 'PostToolUse', session_id: 'a', tool_name: 'apply_patch', tool_input: { command } });
+    fx.run('spec-state', { hook_event_name: 'PostToolUse', session_id: 'a', tool_name: 'exec_command', tool_input: { command } });
+    assert.equal(fx.prompt('a', 'Continue'), '');
+  });
+});
+test('custom root, nested cwd, deleted paths and symlink containment preserve canonical ownership', () => {
+  within({ specs: 'work/packets' }, (fx) => {
+    const nested = path.join(fx.root, 'nested'); fs.mkdirSync(nested);
+    assert.match(fx.prompt('absolute', path.join(fx.root, 'work/packets/auth-flow/plan.md')), /auth-flow/);
+    assert.equal(patch(fx, 'a', '*** Begin Patch\n*** Delete File: ../work/packets/auth-flow/deleted.md\n*** End Patch', 'Success. Updated the following files:\nD ../work/packets/auth-flow/deleted.md\n', nested), '');
+    assert.match(fx.prompt('a', 'Continue'), /auth-flow/);
+    assert.match(fx.prompt('b', 'work/packets/auth-flow'), /auth-flow/);
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-quiet-outside-'));
+    try {
+      fs.symlinkSync(outside, path.join(fx.root, 'work/packets/escape'));
+      patch(fx, 'c', '*** Begin Patch\n*** Add File: work/packets/escape/new.md\n+new\n*** End Patch');
+      assert.equal(fx.prompt('c', 'Continue'), '');
+      assert.match(fx.prompt('explicit', 'Continue', { explicitPath: 'work/packets/auth-flow/task-01-work.md' }), /auth-flow/);
+    } finally { fs.rmSync(outside, { recursive: true, force: true }); }
+  });
+});
+test('legacy-compatible writes touch; failed writes and no-session observer do not share an unknown session', () => {
+  within({}, (fx) => {
+    for (const tool of ['Edit', 'Write', 'MultiEdit']) {
+      assert.equal(fx.run('spec-state', { hook_event_name: 'PostToolUse', session_id: tool, tool_name: tool, tool_input: { file_path: 'specs/auth-flow/plan.md' }, tool_response: { ok: true } }), '');
+      assert.match(fx.prompt(tool, 'Continue'), /auth-flow/);
+    }
+    fx.run('spec-state', { hook_event_name: 'PostToolUse', session_id: 'failed', tool_name: 'Write', tool_input: { file_path: 'specs/auth-flow/plan.md' }, tool_response: { success: false } });
+    assert.equal(fx.prompt('failed', 'Continue'), '');
+    fx.run('spec-state', { hook_event_name: 'PostToolUse', tool_name: 'Write', tool_input: { file_path: 'specs/auth-flow/plan.md' } });
+    assert.equal(fx.prompt('new', 'Continue'), '');
+    assert.match(fx.prompt(undefined, 'Continue'), /runtime_session must be a non-empty/, 'session-less prompt preserves the original provenance failure without inventing identity');
+  });
+});
+test('legacy migration notice stays once per session independently of packet touch', () => {
+  within({ packets: [] }, (fx) => {
+    const dir = path.join(fx.root, 'specs/old'); fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, 'spec.json'), '{}');
+    assert.match(fx.prompt('a', 'Hello'), /legacy Specs packet/);
+    assert.equal(fx.prompt('a', 'Hello'), '');
+    assert.match(fx.prompt('b', 'Hello'), /legacy Specs packet/);
+  });
+});
+test('state hides placeholders and invalid/expired timestamps but restores meaningful per-session content', () => {
+  within({ packets: [] }, (fx) => {
+    const filler = '## What Worked\n- (No completed tasks recorded)\n## Left\n- (No pending tasks recorded)\n## Agent\n- Completed at 12:30:40\n- Completed without a result message.\n## Files\n- (No file changes detected)';
+    snapshot(fx, 'a', filler);
+    assert.equal(fx.run('state', { hook_event_name: 'SessionStart', session_id: 'a' }), '');
+    for (const timestamp of ['invalid', new Date(Date.now() - 8 * 86400000).toISOString()]) {
+      snapshot(fx, 'a', '- real work', timestamp);
+      assert.equal(fx.run('state', { hook_event_name: 'SessionStart', session_id: 'a' }), '');
+    }
+    for (const content of ['- [ ] Build API', '## Agent Result\nVerified endpoint', '## Latest Assistant Message\nSaved edits', '## Key Files Modified\n- src/api.js']) {
+      snapshot(fx, 'a', content);
+      assert.match(fx.run('state', { hook_event_name: 'SessionStart', session_id: 'a' }), /Prior Execution Context/);
+      assert.equal(fx.run('state', { hook_event_name: 'SessionStart', session_id: 'b' }), '');
+    }
+  });
+});
+test('template keeps on-demand docs file and registers native mutation observer separately', () => {
+  const template = JSON.parse(fs.readFileSync(path.join(SOURCE, 'codex/hooks.json')));
+  assert.ok(!JSON.stringify(template.hooks.SessionStart).includes('docs-sync.cjs'));
+  assert.ok(fs.existsSync(path.join(SOURCE, 'codex/hooks/docs-sync.cjs')));
+  assert.ok(template.hooks.PostToolUse.some((entry) => entry.matcher.includes('apply_patch') && entry.hooks.some((hook) => hook.command.includes('spec-state.cjs'))));
+});

package/bin/__tests__/codex-research-projection.test.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { test } = require('node:test');
+const { normalizeCodexBody, CODEX_RESEARCH_DEPTH_MARKER, CODEX_RESEARCH_DEPTH_NOTE } = require('../lib/codex-install');
+const { splitFrontmatter } = require('../lib/codex-frontmatter');
+
+const SKILLS = path.resolve(__dirname, '../../src/claude/skills');
+const researchPath = path.join(SKILLS, 'research/SKILL.md');
+const research = fs.readFileSync(researchPath, 'utf8');
+
+function skillFiles(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const file = path.join(directory, entry.name);
+    return entry.isDirectory() ? skillFiles(file) : entry.name === 'SKILL.md' ? [file] : [];
+  });
+}
+
+function assertMarker() {
+  assert.equal(typeof CODEX_RESEARCH_DEPTH_MARKER, 'string');
+  assert.ok(CODEX_RESEARCH_DEPTH_MARKER.length > 0);
+}
+
+test('codex research projection carries the depth note immediately after unchanged frontmatter', () => {
+  assertMarker();
+  assert.equal(typeof CODEX_RESEARCH_DEPTH_NOTE, 'string');
+  const plain = normalizeCodexBody(research);
+  const projected = normalizeCodexBody(research, researchPath);
+  assert.match(projected, /^---\r?\n/);
+  const before = splitFrontmatter(plain), after = splitFrontmatter(projected);
+  assert.equal(after.frontmatter.name, 'cf-research');
+  assert.equal(after.frontmatter.description, before.frontmatter.description);
+  assert.deepEqual(after.frontmatter, before.frontmatter);
+  assert.equal(projected.slice(0, projected.length - after.body.length), plain.slice(0, plain.length - before.body.length));
+  assert.equal(after.body, `\n${CODEX_RESEARCH_DEPTH_NOTE}\n\n${before.body}`);
+  assert.equal(projected.split(CODEX_RESEARCH_DEPTH_MARKER).length - 1, 1);
+  assert.ok(CODEX_RESEARCH_DEPTH_NOTE.includes(CODEX_RESEARCH_DEPTH_MARKER));
+  assert.match(CODEX_RESEARCH_DEPTH_NOTE, /known option/);
+  assert.match(CODEX_RESEARCH_DEPTH_NOTE, /Quick/);
+  assert.match(CODEX_RESEARCH_DEPTH_NOTE, /outdated supporting rationale/i);
+  assert.match(CODEX_RESEARCH_DEPTH_NOTE, /changes the recommendation/);
+  assert.match(CODEX_RESEARCH_DEPTH_NOTE, /conflicting evidence/i);
+  assert.doesNotMatch(CODEX_RESEARCH_DEPTH_NOTE, /\b(?:Write|Edit|Read|Bash|WebSearch|WebFetch|AskUserQuestion|Drizzle|Prisma|BullMQ|pg-boss|billing|ADR-004)\b/);
+});
+
+test('research marker is absent from every other projected skill including ask', () => {
+  assertMarker();
+  const others = skillFiles(SKILLS).filter(file => file !== researchPath);
+  assert.ok(others.includes(path.join(SKILLS, 'ask/SKILL.md')));
+  for (const file of others) {
+    const source = fs.readFileSync(file, 'utf8');
+    const projected = normalizeCodexBody(source, file);
+    assert.ok(!projected.includes(CODEX_RESEARCH_DEPTH_MARKER), file);
+    // Ask intentionally has its own boundary; all other skill bodies stay identical.
+    if (![path.join(SKILLS, 'ask/SKILL.md'), path.join(SKILLS, 'specs/SKILL.md')].includes(file)) assert.equal(projected, normalizeCodexBody(source), file);
+  }
+});
+
+test('research note is scoped to the exact skill source path and supports Windows separators', () => {
+  assertMarker();
+  for (const sourcePath of ['', 'skills/research/templates/x.md', 'other-skills/research/SKILL.md']) {
+    const projected = normalizeCodexBody(research, sourcePath);
+    assert.ok(!projected.includes(CODEX_RESEARCH_DEPTH_MARKER), sourcePath);
+    assert.equal(projected, normalizeCodexBody(research), sourcePath);
+  }
+  const windows = normalizeCodexBody(research, 'C:\\project\\skills\\research\\SKILL.md');
+  assert.ok(windows.includes(CODEX_RESEARCH_DEPTH_MARKER));
+});

package/bin/__tests__/codex-specs-projection.test.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { test } = require('node:test');
+const { normalizeCodexBody, CODEX_SPECS_SCOPE_MARKER, CODEX_SPECS_SCOPE_NOTE,
+  CODEX_RESEARCH_DEPTH_MARKER } = require('../lib/codex-install');
+const { splitFrontmatter } = require('../lib/codex-frontmatter');
+
+const SKILLS = path.resolve(__dirname, '../../src/claude/skills');
+const specsPath = path.join(SKILLS, 'specs/SKILL.md');
+const specs = fs.readFileSync(specsPath, 'utf8');
+
+function skillFiles(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const file = path.join(directory, entry.name);
+    return entry.isDirectory() ? skillFiles(file) : entry.name === 'SKILL.md' ? [file] : [];
+  });
+}
+
+function assertMarker() {
+  assert.equal(typeof CODEX_SPECS_SCOPE_MARKER, 'string');
+  assert.ok(CODEX_SPECS_SCOPE_MARKER.length > 0);
+}
+
+test('codex specs projection carries the scope note immediately after unchanged frontmatter', () => {
+  assertMarker();
+  assert.equal(typeof CODEX_SPECS_SCOPE_NOTE, 'string');
+  const plain = normalizeCodexBody(specs);
+  const projected = normalizeCodexBody(specs, specsPath);
+  assert.match(projected, /^---\r?\n/);
+  const before = splitFrontmatter(plain), after = splitFrontmatter(projected);
+  assert.equal(after.frontmatter.name, 'cf-specs');
+  assert.deepEqual(after.frontmatter, before.frontmatter);
+  assert.equal(projected.slice(0, projected.length - after.body.length), plain.slice(0, plain.length - before.body.length));
+  assert.equal(after.body, `\n${CODEX_SPECS_SCOPE_NOTE}\n\n${before.body}`);
+  assert.equal(projected.split(CODEX_SPECS_SCOPE_MARKER).length - 1, 1);
+  assert.equal(normalizeCodexBody(projected, specsPath), projected);
+  assert.ok(CODEX_SPECS_SCOPE_NOTE.includes(CODEX_SPECS_SCOPE_MARKER));
+  assert.match(CODEX_SPECS_SCOPE_MARKER, /GATE-SCOPE.*final answer/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /not in commentary or through `request_user_input`/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /Do not send a summary after/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /\[NEEDS CLARIFICATION: <question>\]/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /real question.*not a placeholder/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /EXPAND, KEEP, and CUT together/);
+  assert.match(CODEX_SPECS_SCOPE_NOTE, /Preserve.*NEEDS CLARIFICATION.*EXPAND.*KEEP.*CUT.*do not translate/);
+  assert.doesNotMatch(CODEX_SPECS_SCOPE_NOTE, /\b(?:Write|Edit|Read|Bash|WebSearch|WebFetch|AskUserQuestion)\b/);
+  assert.doesNotMatch(CODEX_SPECS_SCOPE_NOTE, /customer|sales|notif|khách|bán hàng|thông báo/i);
+});
+
+test('specs marker is absent from every other skill and research retains exactly one depth marker', () => {
+  assertMarker();
+  const others = skillFiles(SKILLS).filter(file => file !== specsPath);
+  for (const name of ['ask', 'research']) assert.ok(others.includes(path.join(SKILLS, name, 'SKILL.md')));
+  for (const file of others) {
+    const source = fs.readFileSync(file, 'utf8');
+    const projected = normalizeCodexBody(source, file);
+    assert.ok(!projected.includes(CODEX_SPECS_SCOPE_MARKER), file);
+    if (file === path.join(SKILLS, 'research/SKILL.md')) {
+      assert.equal(projected.split(CODEX_RESEARCH_DEPTH_MARKER).length - 1, 1);
+    } else if (file !== path.join(SKILLS, 'ask/SKILL.md')) {
+      assert.equal(projected, normalizeCodexBody(source), file);
+    }
+  }
+});
+
+test('specs note is scoped to the exact skill source path and supports Windows separators', () => {
+  assertMarker();
+  for (const sourcePath of ['', 'skills/specs/references/templates.md', 'other-skills/specs/SKILL.md']) {
+    const projected = normalizeCodexBody(specs, sourcePath);
+    assert.ok(!projected.includes(CODEX_SPECS_SCOPE_MARKER), sourcePath);
+    assert.equal(projected, normalizeCodexBody(specs), sourcePath);
+  }
+  assert.ok(normalizeCodexBody(specs, 'C:\\project\\skills\\specs\\SKILL.md').includes(CODEX_SPECS_SCOPE_MARKER));
+});