@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/bin/__tests__/runtime-dir.test.js

@@ -0,0 +1,158 @@
+'use strict';
+
+// The gate hooks derive their runtime directory from their own location instead of a
+// literal `.claude`. Each case copies the helper into a directory shaped like a real
+// layout and requires it from there, so the derivation is exercised against the path the
+// module actually sees — not a mocked one.
+
+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 PACKAGE_ROOT = path.join(__dirname, '../..');
+const HELPER = path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/runtime-dir.cjs');
+const { spawnSync } = require('node:child_process');
+
+/** Place the helper at <root>/<layout>/hooks/lib/ and return what it derives. */
+function deriveAt(root, layout) {
+  const lib = path.join(root, layout, 'hooks', 'lib');
+  fs.mkdirSync(lib, { recursive: true });
+  const target = path.join(lib, 'runtime-dir.cjs');
+  fs.copyFileSync(HELPER, target);
+  // Each copy is a distinct module path, so require caches never collide.
+  return require(target);
+}
+
+function withTemp(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-runtime-dir-'));
+  try { return run(root); } finally { fs.rmSync(root, { recursive: true, force: true }); }
+}
+
+test('installed layouts derive their own folder', () => {
+  withTemp((root) => {
+    for (const folder of ['.claude', '.codex', '.omp']) {
+      const m = deriveAt(root, path.join('project-' + folder.slice(1), folder));
+      assert.equal(m.runtimeDirName(), folder);
+      assert.equal(m.runtimeDir('/p'), path.join('/p', folder));
+      assert.equal(m.runtimePath('/p', 'runtime.json'), path.join('/p', folder, 'runtime.json'));
+    }
+  });
+});
+
+test('the source tree maps platform to dotted name', () => {
+  withTemp((root) => {
+    for (const platform of ['claude', 'omp', 'codex']) {
+      const m = deriveAt(root, path.join('packages', 'spec', 'src', platform));
+      assert.equal(m.runtimeDirName(), `.${platform}`, `source tree for ${platform}`);
+    }
+  });
+});
+
+test('a dotted folder wins over the source marker', () => {
+  withTemp((root) => {
+    // An install whose absolute path happens to contain /packages/spec/src/ must still
+    // report its real folder, not a doubled-dot name derived from the marker.
+    const m = deriveAt(root, path.join('packages', 'spec', 'src', 'fixture', '.codex'));
+    assert.equal(m.runtimeDirName(), '.codex');
+  });
+});
+
+test('an unknown layout falls back to .claude', () => {
+  withTemp((root) => {
+    const m = deriveAt(root, path.join('somewhere', 'else'));
+    assert.equal(m.runtimeDirName(), '.claude', 'the pre-helper behaviour is the fallback');
+  });
+});
+
+test('the helper in the real source tree derives .claude', () => {
+  const m = require(HELPER);
+  assert.equal(m.runtimeDirName(), '.claude');
+});
+
+/** Copy the whole hook tree and the scripts it requires under <root>/<folder>/. */
+function installTreeAs(root, folder) {
+  const rt = path.join(root, folder);
+  fs.cpSync(path.join(PACKAGE_ROOT, 'src/claude/hooks'), path.join(rt, 'hooks'), {
+    recursive: true, filter: (src) => !src.includes(`${path.sep}__tests__`),
+  });
+  fs.cpSync(path.join(PACKAGE_ROOT, 'src/claude/scripts'), path.join(rt, 'scripts'), { recursive: true });
+  return rt;
+}
+
+/** Provenance derives Base/Head with git, so the fixture must be a repository (one empty commit). */
+function gitInit(root) {
+  for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'], ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+    const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+    assert.equal(result.status, 0, `git ${args[0]} failed: ${result.stderr}`);
+  }
+}
+
+function runHook(rt, name, payload) {
+  const r = spawnSync(process.execPath, [path.join(rt, 'hooks', name)], {
+    cwd: path.dirname(rt), input: JSON.stringify(payload), encoding: 'utf8',
+    env: { ...process.env, CLAUDE_PROJECT_DIR: '', PROJECT_ROOT: '' },
+  });
+  return { code: r.status, out: (r.stdout || '') + (r.stderr || '') };
+}
+
+test('a hook tree copied under .omp reads .omp/runtime.json', () => {
+  withTemp((root) => {
+    const rt = installTreeAs(root, '.omp');
+    gitInit(root);
+    fs.mkdirSync(path.join(root, 'specs'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.env'), 'TOKEN=redacted\n');
+    assert.equal(fs.existsSync(path.join(root, '.claude')), false, 'the fixture must hold no .claude path at all');
+
+    // rules.cjs: docs path from the sentinel config
+    fs.writeFileSync(path.join(rt, 'runtime.json'), JSON.stringify({ paths: { docs: 'SENTINEL-DOCS', plans: 'plans' } }));
+    const rules = runHook(rt, 'rules.cjs', { session_id: `s-${Date.now()}`, cwd: root });
+    assert.match(rules.out, /SENTINEL-DOCS/, 'rules.cjs must read .omp/runtime.json');
+
+    // inspect-block.cjs: disabled through the sentinel allows a broad search
+    fs.writeFileSync(path.join(rt, 'runtime.json'), JSON.stringify({ inspect: { enabled: false } }));
+    const inspect = runHook(rt, 'inspect-block.cjs', { tool_name: 'Bash', tool_input: { command: 'grep -rn TODO .' }, cwd: root });
+    assert.equal(inspect.code, 0, 'inspect.enabled:false in .omp/runtime.json must allow');
+
+    // privacy-block.cjs: kill switch through the sentinel allows a .env read
+    fs.writeFileSync(path.join(rt, 'runtime.json'), JSON.stringify({ privacyBlock: false }));
+    const privacy = runHook(rt, 'privacy-block.cjs', { tool_name: 'Read', tool_input: { file_path: path.join(root, '.env') }, cwd: root });
+    assert.doesNotMatch(privacy.out, /permissionDecision/, 'privacyBlock:false in .omp/runtime.json must allow');
+
+    // spec-gate.cjs exits silently unless a packet resolves, and only then reads the
+    // completion_gate flag. Resolving a done task derives provenance through git, so the
+    // fixture is a repository (gitInit above) and holds one done task to look at.
+    const feature = path.join(root, 'specs', 'demo'); fs.mkdirSync(feature, { recursive: true });
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Demo plan\n');
+    fs.writeFileSync(path.join(feature, 'task-01-demo.md'), [
+      '# Task 01: demo', '', 'Status: done', '', '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+    ].join('\n'));
+    // the completion_gate flag is read from the sentinel and answered as a block
+    fs.writeFileSync(path.join(rt, 'runtime.json'), JSON.stringify({ spec: { completion_gate: false } }));
+    const gate = runHook(rt, 'spec-gate.cjs', { session_id: 's', cwd: root, hook_event_name: 'Stop', stop_hook_active: false });
+    assert.match(gate.out, /worker-writable flag/, 'spec-gate.cjs must read .omp/runtime.json');
+  });
+});
+
+test('advice names the directory the hook lives in', () => {
+  withTemp((root) => {
+    for (const [folder, skills] of [['.omp', '.agents/skills'], ['.claude', '.claude/skills']]) {
+      const project = path.join(root, `p${folder}`); fs.mkdirSync(project, { recursive: true });
+      const rt = installTreeAs(project, folder);
+      fs.mkdirSync(path.join(project, 'specs', 'demo'), { recursive: true });
+      fs.writeFileSync(path.join(rt, 'runtime.json'), '{}');
+      // task-scaffold-guard: a raw Write into a nested task path is refused with scaffold advice
+      const guard = runHook(rt, 'task-scaffold-guard.cjs', { tool_name: 'Write', tool_input: { file_path: path.join(project, 'specs', 'demo', 'tasks', 'task-R0-01-x.md'), content: '# x' }, cwd: project });
+      assert.match(guard.out, new RegExp(`node ${folder.replace('.', '\\.')}/scripts/spec-scaffold\\.cjs`), `scaffold advice must name ${folder}`);
+      // inspect-block: header hint names the runtime file (static check on the installed copy)
+      const src = fs.readFileSync(path.join(rt, 'hooks', 'inspect-block.cjs'), 'utf8');
+      assert.match(src, /<runtime>\/runtime\.json/, 'the disable hint no longer hardcodes a platform');
+      // agent.cjs: skills advice follows the platform registry, not the runtime dir
+      const agentSrc = fs.readFileSync(path.join(rt, 'hooks', 'agent.cjs'), 'utf8');
+      assert.match(agentSrc, /'\.agents\/skills'/, 'non-Claude platforms read .agents/skills');
+      void skills;
+    }
+  });
+});

package/bin/__tests__/runtime-schema.test.js

@@ -0,0 +1,113 @@
+'use strict';
+
+// runtime.json is the only configuration surface a CafeKit user edits by hand, so the
+// schema beside it has to stay true: every shipped key described, every documented key
+// still real, and no key silently drifting out of sync with what the runtime honours.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+const SCHEMA_PATH = path.join(PACKAGE_ROOT, 'src/claude/runtime.schema.json');
+const SCHEMA = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
+const RUNTIMES = ['src/claude/runtime.json', 'src/codex/runtime.json', 'src/omp/runtime.json'];
+const MANIFEST = require(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'));
+
+function readRuntime(relative) {
+  return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, relative), 'utf8'));
+}
+
+/** Walk a config object against a schema node, collecting undescribed key paths. */
+function undescribedKeys(value, schemaNode, trail = []) {
+  if (!schemaNode || typeof value !== 'object' || value === null || Array.isArray(value)) return [];
+  const properties = schemaNode.properties || {};
+  const found = [];
+  for (const [key, child] of Object.entries(value)) {
+    const childSchema = properties[key];
+    if (!childSchema) {
+      if (schemaNode.additionalProperties === true || typeof schemaNode.additionalProperties === 'object') continue;
+      found.push([...trail, key].join('.'));
+      continue;
+    }
+    found.push(...undescribedKeys(child, childSchema, [...trail, key]));
+  }
+  return found;
+}
+
+/** Every property node in the schema, keyed by dotted path. */
+function schemaProperties(node, trail = [], out = new Map()) {
+  for (const [key, child] of Object.entries(node.properties || {})) {
+    const dotted = [...trail, key].join('.');
+    out.set(dotted, child);
+    schemaProperties(child, [...trail, key], out);
+  }
+  return out;
+}
+
+test('the schema is a valid, self-describing JSON Schema document', () => {
+  assert.equal(SCHEMA.$schema, 'https://json-schema.org/draft/2020-12/schema');
+  assert.equal(SCHEMA.type, 'object');
+  assert.ok(SCHEMA.title, 'the schema needs a title');
+  assert.ok(SCHEMA.description, 'the schema needs a description');
+  assert.equal(SCHEMA.additionalProperties, false, 'an unknown top-level key must be reported, not accepted silently');
+});
+
+test('every key in each shipped runtime.json is described by the schema', () => {
+  for (const relative of RUNTIMES) {
+    const missing = undescribedKeys(readRuntime(relative), SCHEMA);
+    assert.deepEqual(missing, [], `${relative} ships keys the schema does not describe: ${missing.join(', ')}`);
+  }
+});
+
+test('every runtime points at the schema that installs beside it', () => {
+  for (const relative of RUNTIMES) {
+    assert.equal(readRuntime(relative).$schema, './runtime.schema.json', `${relative} must reference the schema`);
+  }
+  assert.ok(
+    MANIFEST.runtime.files.includes('runtime.schema.json'),
+    'the schema must be installed for Claude, or its $schema reference dangles'
+  );
+  const codexPhase = fs.readFileSync(path.join(PACKAGE_ROOT, 'bin/phases/codex-runtime.js'), 'utf8');
+  assert.match(codexPhase, /runtime\.schema\.json/, 'the schema must also be installed for Codex');
+  const ompPhase = fs.readFileSync(path.join(PACKAGE_ROOT, 'bin/phases/omp-runtime.js'), 'utf8');
+  assert.match(ompPhase, /runtime\.schema\.json/, 'the schema must also be installed for omp');
+});
+
+test('every documented property carries a description a reader can act on', () => {
+  for (const [dotted, node] of schemaProperties(SCHEMA)) {
+    if (dotted === '$schema') continue;
+    assert.ok(node.description, `${dotted} has no description`);
+    assert.ok(node.description.length > 20, `${dotted} has a description too short to help: ${node.description}`);
+  }
+});
+
+test('keys the runtime does not honour are marked deprecated, not documented as working', () => {
+  // develop.parallel and the hooks toggle map are still shipped for compatibility, but
+  // nothing reads them. The schema must say so rather than imply they work.
+  for (const dead of ['hooks', 'develop']) {
+    const node = SCHEMA.properties[dead];
+    assert.ok(node, `${dead} is shipped in runtime.json and must appear in the schema`);
+    assert.equal(node.deprecated, true, `${dead} is not honoured and must be marked deprecated`);
+    assert.match(node.description, /[Nn]ot honoured/, `${dead} must say plainly that it does nothing`);
+  }
+});
+
+test('the completion gate flag is documented as a block, never as a switch', () => {
+  const node = SCHEMA.properties.spec.properties.completion_gate;
+  assert.match(node.description, /[Nn]ot a switch/);
+  assert.match(node.description, /blocks/, 'the description must say the gate blocks while the flag is present');
+});
+
+test('statusline values in the schema match the modes the renderer implements', () => {
+  const status = fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/status.cjs'), 'utf8');
+  const implemented = new Set((status.match(/case '([a-z]+)':/g) || []).map((line) => line.slice(6, -2)));
+  for (const mode of SCHEMA.properties.statusline.enum) {
+    assert.ok(implemented.has(mode), `schema offers statusline "${mode}" but the renderer has no branch for it`);
+  }
+  const sections = SCHEMA.properties.statuslineLayout.properties.lines.items.items.enum;
+  for (const section of sections) {
+    assert.ok(status.includes(`'${section}'`), `schema offers layout section "${section}" but status.cjs never names it`);
+  }
+});

package/bin/__tests__/secret-output-guardrail.test.js

@@ -0,0 +1,122 @@
+'use strict';
+
+// The privacy hook gates whether a sensitive file may be READ. Nothing gated what
+// happens after that approval, so an approved read could still put a raw key into the
+// transcript — which is written to disk, survives compaction, and is replayed to the
+// model every later turn. This hook closes that gap with a reminder, on both runtimes.
+
+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 KEYWORDS = require(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/secret-keywords.cjs'));
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-secret-guardrail-'));
+  try {
+    spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, platform) {
+  const result = spawnSync(process.execPath, [INSTALLER, '--platform', platform, '--yes'],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  return path.join(root, `.${platform}`, 'hooks', 'secret-output-guardrail.cjs');
+}
+
+function run(hookPath, root, prompt) {
+  const result = spawnSync(process.execPath, [hookPath], {
+    cwd: root,
+    input: JSON.stringify({ session_id: 'guardrail-session', prompt, cwd: root }),
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 0, `hook must fail open: ${result.stderr}`);
+  return result.stdout;
+}
+
+test('the matcher fires on credential topics and stays quiet otherwise', () => {
+  for (const prompt of [
+    'read the .env file', 'rotate our credentials', 'where is the secret stored',
+    'print the API key', 'the access key expired', 'this token is stale',
+    'send a bearer header', 'decode the JWT', 'load the private key',
+    'the oauth client secret', 'client secret rotation', 'our cloud keys', 'check the env file',
+  ]) {
+    assert.equal(KEYWORDS.containsSecretKeyword(prompt), true, `should match: ${prompt}`);
+  }
+  for (const prompt of [
+    'add two numbers', 'refactor the tokenizer', 'update the environment setup docs',
+    'fix the keyboard shortcut', '', '   ',
+  ]) {
+    assert.equal(KEYWORDS.containsSecretKeyword(prompt), false, `should not match: ${prompt}`);
+  }
+});
+
+test('the reminder separates permission to read from permission to print', () => {
+  assert.match(KEYWORDS.REMINDER, /does not grant permission to print raw values/);
+  assert.match(KEYWORDS.REMINDER, /\[redacted\]/);
+  assert.match(KEYWORDS.REMINDER, /report only success or failure/);
+});
+
+for (const platform of ['claude', 'codex']) {
+  test(`${platform}: a credential prompt gets the reminder, an ordinary one gets nothing`, () => {
+    inTempProject((root) => {
+      const hook = install(root, platform);
+      assert.equal(fs.existsSync(path.join(root, `.${platform}`, 'hooks', 'lib', 'secret-keywords.cjs')), true,
+        'the shared matcher must install beside the hook');
+
+      const flagged = run(hook, root, 'please read .env and tell me what is set');
+      assert.match(flagged, /## Secret handling/);
+      assert.match(flagged, /does not grant permission to print raw values/);
+
+      assert.equal(run(hook, root, 'rename this variable'), '', 'an unrelated prompt must inject nothing');
+    });
+  });
+
+  test(`${platform}: the guardrail never echoes the prompt or a matched value`, () => {
+    inTempProject((root) => {
+      const hook = install(root, platform);
+      // A realistic-looking secret in the prompt must not come back in the output —
+      // a guardrail that quotes its input would itself write the value to the transcript.
+      const out = run(hook, root, 'my api key is sk-live-abc123SECRETVALUE, is it valid?');
+      assert.match(out, /## Secret handling/);
+      assert.doesNotMatch(out, /sk-live-abc123SECRETVALUE/, 'the hook echoed the secret it was warning about');
+      assert.doesNotMatch(out, /is it valid/, 'the hook echoed the prompt');
+    });
+  });
+
+  test(`${platform}: the hook fails open on malformed input`, () => {
+    inTempProject((root) => {
+      const hook = install(root, platform);
+      for (const input of ['not json', '', '{"prompt":null}']) {
+        const result = spawnSync(process.execPath, [hook], { cwd: root, input, encoding: 'utf8' });
+        assert.equal(result.status, 0, `malformed input must not fail the turn: ${JSON.stringify(input)}`);
+      }
+    });
+  });
+
+  test(`${platform}: the hook is registered for UserPromptSubmit`, () => {
+    inTempProject((root) => {
+      install(root, platform);
+      const configPath = platform === 'claude'
+        ? path.join(root, '.claude', 'settings.json')
+        : path.join(root, '.codex', 'hooks.json');
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      const commands = (config.hooks.UserPromptSubmit || [])
+        .flatMap((group) => group.hooks || [])
+        .map((handler) => handler.command || '');
+      assert.ok(
+        commands.some((command) => command.includes('secret-output-guardrail.cjs')),
+        `${platform} never runs the guardrail`
+      );
+    });
+  });
+}

package/bin/__tests__/skill-routing-source.test.js

@@ -0,0 +1,172 @@
+'use strict';
+
+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 { normalizeCodexBody } = require('../lib/codex-install');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '../..');
+const SCANNER = path.join(PACKAGE_ROOT, 'src/claude/scripts/generate-skill-catalog.cjs');
+const MANIFEST = JSON.parse(fs.readFileSync(
+  path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'), 'utf8'
+));
+
+function withTempRoot(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-routing-'));
+  try {
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function writeSkill(root, directory, fields = {}) {
+  const target = path.join(root, directory);
+  fs.mkdirSync(target, { recursive: true });
+  if (fields.raw) {
+    fs.writeFileSync(path.join(target, 'SKILL.md'), fields.raw);
+    return;
+  }
+  const lines = ['---'];
+  if (fields.name !== undefined) lines.push(`name: ${fields.name}`);
+  if (fields.description !== undefined) lines.push(`description: "${fields.description}"`);
+  if (fields.when !== undefined) lines.push(`when_to_use: "${fields.when}"`);
+  if (fields.category !== undefined) lines.push(`category: ${fields.category}`);
+  if (fields.keywords !== undefined) lines.push(`keywords: [${fields.keywords.join(', ')}]`);
+  lines.push('user-invocable: true', '---', `# ${directory}`, '');
+  fs.writeFileSync(path.join(target, 'SKILL.md'), `${lines.join('\n')}\n`);
+}
+
+function runCatalog(script, cwd, args = ['--json']) {
+  const result = spawnSync(process.execPath, [script, ...args], { cwd, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  return JSON.parse(result.stdout);
+}
+
+function installScanner(source, destination, transform = (content) => content) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, transform(fs.readFileSync(source, 'utf8')));
+}
+
+test('skill routing consumes live catalog without fixed optional commands', () => {
+  withTempRoot((root) => {
+    const claudeScript = path.join(root, '.claude/scripts/generate-skill-catalog.cjs');
+    const codexScript = path.join(root, '.codex/scripts/generate-skill-catalog.cjs');
+    installScanner(SCANNER, claudeScript);
+    installScanner(SCANNER, codexScript, (content) => normalizeCodexBody(content, SCANNER));
+
+    writeSkill(path.join(root, '.claude/skills'), 'question', {
+      name: 'cf:ask', description: 'Answer with evidence.', when: 'Use for factual questions.',
+      category: 'utilities', keywords: ['answer', 'evidence'],
+    });
+    writeSkill(path.join(root, '.claude/skills'), 'docs', {
+      name: 'cf:docs', description: 'Work with docs.', when: 'Use for documentation.',
+      category: 'documents', keywords: ['docs'],
+    });
+    writeSkill(path.join(root, '.agents/skills'), 'question', {
+      name: 'cf-ask', description: 'Answer with evidence.', when: 'Use for factual questions.',
+      category: 'utilities', keywords: ['answer', 'evidence'],
+    });
+
+    const claude = runCatalog(claudeScript, root);
+    const codex = runCatalog(codexScript, root);
+    assert.equal(claude.root, fs.realpathSync(path.join(root, '.claude/skills')));
+    assert.equal(codex.root, fs.realpathSync(path.join(root, '.agents/skills')));
+    assert.deepEqual(claude.skills.map((skill) => skill.public_id), ['cf:ask', 'cf:docs']);
+    assert.deepEqual(codex.skills.map((skill) => skill.public_id), ['cf:ask']);
+    assert.equal(codex.skills.some((skill) => skill.public_id === 'cf:docs'), false);
+  });
+
+  const workflow = fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/rules/skill-workflow-routing.md'), 'utf8');
+  const domain = fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/rules/skill-domain-routing.md'), 'utf8');
+  const codexEntry = fs.readFileSync(path.join(PACKAGE_ROOT, 'src/codex/AGENTS.md'), 'utf8');
+  assert.match(workflow, /user names a valid installed skill[\s\S]*one obvious low-risk[\s\S]*direct factual conversation/);
+  assert.match(workflow, /do not invoke Route or agents for ceremony/);
+  assert.match(workflow.replace(/\s+/g, ' '), /numeric optimization capability remains explicit-only/);
+  assert.match(domain, /examples below are intent hints, not a copied installed inventory/);
+  assert.match(domain, /document\/artifact work \| use only a matching installed optional capability/);
+  assert.doesNotMatch(domain, /\/cf:(?:docs|docx|pdf|pptx|xlsx|ai-multimodal)/);
+  assert.match(codexEntry, /node \.codex\/scripts\/generate-skill-catalog\.cjs --skills/);
+  assert.match(codexEntry, /Codex-bound[\s\S]*\.agents\/skills/);
+});
+
+test('skill catalog exposes discriminating routing metadata', () => {
+  withTempRoot((root) => {
+    const skills = path.join(root, 'skills');
+    writeSkill(skills, 'route', {
+      name: 'cf:route', description: 'Choose a bounded chain.',
+      when: 'Use for ambiguous multi-step work.', category: 'utilities',
+      keywords: ['routing', 'risk'],
+    });
+    writeSkill(skills, 'question', {
+      name: 'cf:ask', description: 'First duplicate.', when: 'Use for questions.',
+      category: 'utilities', keywords: ['answer'],
+    });
+    writeSkill(skills, 'ask', {
+      name: 'cf:ask', description: 'Second duplicate.', when: 'Use for questions.',
+      category: 'utilities', keywords: ['answer'],
+    });
+    writeSkill(skills, 'missing-description', { name: 'cf:missing-description' });
+    writeSkill(skills, 'mismatch', { name: 'cf:wrong', description: 'Wrong folder.' });
+    writeSkill(skills, 'malformed', { raw: '# no frontmatter\n' });
+    writeSkill(skills, 'bad-line', {
+      raw: '---\nname: cf:bad-line\ndescription: Valid-looking description.\nthis is not yaml\n---\n',
+    });
+    writeSkill(skills, 'unterminated', {
+      raw: '---\nname: cf:unterminated\ndescription: "unterminated\n---\n',
+    });
+    writeSkill(skills, 'blank-description', {
+      raw: '---\nname: cf:blank-description\ndescription: "   "\n---\n',
+    });
+    writeSkill(skills, 'invalid-flow', {
+      raw: '---\nname: cf:invalid-flow\ndescription: [unterminated\n---\n',
+    });
+    writeSkill(skills, 'duplicate-key', {
+      raw: '---\nname: cf:wrong\nname: cf:duplicate-key\ndescription: Duplicate name.\n---\n',
+    });
+    writeSkill(skills, 'backend-development', {
+      name: 'cf:backend-development', description: 'User-modified retired skill.',
+    });
+
+    const catalog = runCatalog(SCANNER, root, ['--json', '--root', skills]);
+    assert.deepEqual(catalog.skills.map((skill) => skill.public_id), ['cf:route']);
+    assert.deepEqual(catalog.skills[0], {
+      name: 'cf:route', public_id: 'cf:route', directory: 'route',
+      description: 'Choose a bounded chain.', when_to_use: 'Use for ambiguous multi-step work.',
+      category: 'utilities', keywords: ['routing', 'risk'], user_invocable: true,
+      has_references: false, has_scripts: false,
+    });
+    const codes = catalog.diagnostics.map((item) => item.code);
+    assert.equal(codes.filter((code) => code === 'duplicate_public_name').length, 2);
+    for (const required of [
+      'folder_name_mismatch', 'malformed_frontmatter', 'missing_routing_metadata', 'retired_skill',
+    ]) assert.ok(codes.includes(required), required);
+    for (const directory of ['bad-line', 'unterminated', 'duplicate-key', 'invalid-flow']) {
+      assert.ok(catalog.diagnostics.some((item) =>
+        item.directory === directory && item.code === 'malformed_frontmatter'), directory);
+    }
+    assert.ok(catalog.diagnostics.some((item) =>
+      item.directory === 'blank-description' && item.code === 'missing_routing_metadata'));
+    assert.ok(catalog.diagnostics.every((item) => item.code !== 'duplicate_public_name'
+      || item.message.includes('explicit user disambiguation')));
+  });
+
+  const sourceCatalog = runCatalog(SCANNER, PACKAGE_ROOT);
+  const retiredDiagnostics = sourceCatalog.diagnostics
+    .filter((item) => item.code === 'retired_skill').map((item) => item.directory).sort();
+  assert.deepEqual(retiredDiagnostics, [...MANIFEST.obsolete.skills].sort());
+  assert.equal(sourceCatalog.skills.some((skill) => MANIFEST.obsolete.skills.includes(skill.directory)), false);
+  const route = sourceCatalog.skills.find((skill) => skill.public_id === 'cf:route');
+  assert.ok(route?.description && route.when_to_use && route.category && route.keywords.length > 0);
+});
+
+test('skill catalog rejects a missing root value before path resolution', () => {
+  const result = spawnSync(process.execPath, [SCANNER, '--root', '--json'], {
+    cwd: PACKAGE_ROOT, encoding: 'utf8',
+  });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /--root requires a skills directory/);
+});

package/bin/__tests__/specs-v2-execution-closeout.test.js

@@ -263,7 +263,8 @@ function installGate(root, kind) {
     'scripts/workflow-policy.cjs', 'scripts/provenance.cjs', 'scripts/spec-resolver.cjs',
     'scripts/spec-receipt.cjs', 'scripts/validate-spec-output.cjs', 'scripts/spec-ground.cjs',
     'scripts/spec-semantic-model.cjs', 'scripts/spec-final-state.cjs',
-    'hooks/lib/runtime-path-safety.cjs',
+    'hooks/lib/runtime-path-safety.cjs', 'hooks/lib/hook-state-dir.cjs', 'hooks/lib/runtime-dir.cjs',
+    'hooks/lib/hook-payload.cjs',
   ]);
   if (kind === 'claude') {
     for (const name of [
@@ -466,3 +467,29 @@ test('scaffold creates planning artifacts but no task or feature receipts', () =
     assert.equal(files.some((file) => file.includes('receipt')), false);
   });
 });
+
+test('legacy receipt still requires provenance under a clean committed tree', () => {
+  // The workflow task path may validate a committed, unchanged receipt on
+  // structure alone; the legacy task and feature receipt paths must not.
+  withTempResources((resources) => {
+    const root = gitRoot(resources);
+    const { featureDir } = prepare(root);
+    const stale = { base: 'f'.repeat(40), head: 'e'.repeat(40) };
+    fs.writeFileSync(
+      path.join(featureDir, 'receipts', path.basename(TASK)),
+      receiptBody(stale, `Task: ${path.basename(TASK)}\nTask path: ${TASK}`),
+    );
+    fs.writeFileSync(path.join(featureDir, 'feature-receipt.md'), receiptBody(stale, `Feature: ${FEATURE}`));
+    for (const args of [['add', '-A'], ['commit', '-qm', 'committed legacy receipts']]) {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    const clean = spawnSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8' });
+    assert.equal(clean.stdout.trim(), '', 'fixture tree must be clean before the check');
+    const ctx = runtime(root);
+    const taskFailures = RECEIPT.checkTaskReceipt(featureDir, TASK, { completed_at: '2026-08-13T00:00:00.000Z' }, ctx, POLICY).failures;
+    assert.ok(taskFailures.includes('provenance'), `legacy task receipts keep provenance binding when committed and clean; got ${JSON.stringify(taskFailures)}`);
+    const featureFailures = RECEIPT.checkFeatureReceipt(featureDir, ctx, POLICY).failures;
+    assert.ok(featureFailures.includes('provenance'), `feature receipts keep provenance binding when committed and clean; got ${JSON.stringify(featureFailures)}`);
+  });
+});