@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

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

@@ -0,0 +1,111 @@
+'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'];
+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 both shipped runtime.json files 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('both runtimes point at the schema that installs beside them', () => {
+  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');
+});
+
+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,7 @@ 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',
   ]);
   if (kind === 'claude') {
     for (const name of [

package/bin/install.js

@@ -22,6 +22,7 @@ const backup = require('./lib/backup');
 const manifestLib = require('./lib/manifest');
 
 const { selectLanguage, resolvePlatforms } = require('./phases/select-platform');
+const { selectDocumentSkills } = require('./phases/select-skill-bundles');
 const { copyPlatformFiles } = require('./phases/copy-payload');
 const {
   copyRoutingFile,
@@ -30,8 +31,10 @@ const {
   copyClaudeMdFile,
   ensureSharedAgentsMdCore,
   copyRulesDirectory,
+  copyOutputStylesDirectory,
   removeObsoleteAgents
 } = require('./phases/claude-runtime');
+const { reconcileSkillInventory } = require('./phases/skill-inventory');
 const { mergeClaudeSettings } = require('./phases/claude-settings');
 const { installCodexRuntime } = require('./phases/codex-runtime');
 const { writePlatformVersionMetadata } = require('./phases/write-metadata');
@@ -58,6 +61,7 @@ function installPlatform(ctx, platformKey) {
   ctx.ui.startSpinner(ctx.t('installingPlatform', { name: platform.name }));
 
   copyPlatformFiles(ctx, platformKey);
+  reconcileSkillInventory(ctx, platformKey);
   removeObsoleteAgents(ctx, platformKey);
 
   if (platformKey === 'claude') {
@@ -67,6 +71,7 @@ function installPlatform(ctx, platformKey) {
     mergeClaudeSettings(ctx, platformKey);
     copyClaudeMdFile(ctx, platformKey);
     copyRulesDirectory(ctx, platformKey);
+    copyOutputStylesDirectory(ctx, platformKey);
   }
 
   if (platformKey === 'codex') {
@@ -102,6 +107,8 @@ Options:
                        Chromium/Playwright). Otherwise prompted interactively.
   --with-rtk           Install the rtk token-saver (binary + Claude Code hook).
                        Otherwise prompted interactively.
+  --with-document-skills     Install docs/DOCX/PDF/PPTX/XLSX/multimodal skills
+  --without-document-skills  Skip or remove CafeKit-owned document skills
   -y, --yes            Non-interactive: skip prompts, use defaults (CI)
   -h, --help           Show this help
   -v, --version        Print version
@@ -162,6 +169,9 @@ async function main() {
       process.exit(result.status ?? 1);
     }
 
+    await selectDocumentSkills(ctx);
+    if (ctx.cancelled) { lock.release(); process.exit(0); }
+
     // ── Pre-run snapshot for rollback ─────────────────────
     // Capture platform folders AND the root files the pipeline mutates
     // (CLAUDE.md, .gitignore) so a mid-run failure rolls back cleanly.

package/bin/lib/codex-install.js

@@ -25,7 +25,6 @@ const AGENT_NAMES = [
   'ui-ux-designer'
 ];
 const INSTRUCTION_REPLACEMENTS = [
-  [/`?\bAskUserQuestion\b`?/g, 'a structured user-input request'],
   [/`?\bTodoWrite\b`?/g, 'task-state tracking'],
   [/`?\bTaskCreate\b`?/g, 'task creation'],
   [/`?\bTaskUpdate\b`?/g, 'task-state updates'],
@@ -64,6 +63,172 @@ function applyReplacements(content, replacements) {
   return next;
 }
 
+function isMarkdownLinkDestination(content, offset) {
+  const opener = content.lastIndexOf('](', offset);
+  if (opener < 0 || content.lastIndexOf('[', opener) < 0) return false;
+
+  let depth = 1;
+  for (let index = opener + 2; index < offset; index += 1) {
+    if (content[index] === '\\') {
+      index += 1;
+    } else if (content[index] === '(') {
+      depth += 1;
+    } else if (content[index] === ')') {
+      depth -= 1;
+      if (depth === 0) return false;
+    }
+  }
+  return depth > 0;
+}
+
+function isUrlLikeToken(content, offset) {
+  const prefix = content.slice(0, offset).split(/[\s]/).at(-1) || '';
+  return /^<?(?:[a-z][a-z0-9+.-]*:\/\/|mailto:|www\.)\S*$/i.test(prefix);
+}
+
+function maskMarkdownCodeSpans(content) {
+  const spans = [];
+  let markerNonce = 0;
+  while (content.includes(`\uE000CAFEKIT_${markerNonce}_`)) markerNonce += 1;
+  const markerPrefix = `\uE000CAFEKIT_${markerNonce}_`;
+  let masked = '';
+  let index = 0;
+
+  const addMarker = (kind, original) => {
+    const marker = `${markerPrefix}${kind}_${spans.length}\uE001`;
+    spans.push({ marker, original });
+    return marker;
+  };
+
+  const fencedBlockEnd = (openerLineEnd, delimiter, delimiterLength) => {
+    let lineStart = openerLineEnd < 0 ? content.length : openerLineEnd + 1;
+    while (lineStart < content.length) {
+      const newline = content.indexOf('\n', lineStart);
+      const lineEnd = newline < 0 ? content.length : newline;
+      const line = content.slice(lineStart, lineEnd);
+      const match = line.match(/^[ \t]{0,3}([`~]+)[ \t]*\r?$/);
+      if (match
+        && [...match[1]].every((character) => character === delimiter)
+        && match[1].length >= delimiterLength) {
+        return lineEnd;
+      }
+      lineStart = newline < 0 ? content.length : newline + 1;
+    }
+    return content.length;
+  };
+
+  while (index < content.length) {
+    if (content[index] !== '`' && content[index] !== '~') {
+      masked += content[index];
+      index += 1;
+      continue;
+    }
+
+    const opener = index;
+    const delimiter = content[index];
+    while (index < content.length && content[index] === delimiter) index += 1;
+    const delimiterLength = index - opener;
+    const lineStart = content.lastIndexOf('\n', opener - 1) + 1;
+    const linePrefix = content.slice(lineStart, opener);
+    const openerLineEnd = content.indexOf('\n', index);
+    const infoEnd = openerLineEnd < 0 ? content.length : openerLineEnd;
+    const info = content.slice(index, infoEnd);
+    const isFence = delimiterLength >= 3
+      && /^[ \t]{0,3}$/.test(linePrefix)
+      && (delimiter === '~' || !info.includes('`'));
+
+    if (isFence) {
+      const end = fencedBlockEnd(openerLineEnd, delimiter, delimiterLength);
+      masked += addMarker('CODE', content.slice(opener, end));
+      index = end;
+      continue;
+    }
+
+    if (delimiter !== '`') {
+      masked += content.slice(opener, index);
+      continue;
+    }
+
+    let cursor = index;
+    let closer = -1;
+    while (cursor < content.length) {
+      const runStart = content.indexOf('`', cursor);
+      if (runStart < 0) break;
+      let runEnd = runStart;
+      while (runEnd < content.length && content[runEnd] === '`') runEnd += 1;
+      if (runEnd - runStart === delimiterLength) {
+        closer = runStart;
+        break;
+      }
+      cursor = runEnd;
+    }
+
+    if (closer < 0) {
+      const newline = content.indexOf('\n', opener);
+      const end = newline < 0 ? content.length : newline;
+      masked += addMarker('CODE', content.slice(opener, end));
+      index = end;
+      continue;
+    }
+
+    const end = closer + delimiterLength;
+    const original = content.slice(opener, end);
+    const inner = content.slice(opener + delimiterLength, closer);
+    const kind = inner.trim() === 'AskUserQuestion' ? 'ASK' : 'CODE';
+    masked += addMarker(kind, original);
+    index = end;
+  }
+
+  return {
+    content: masked,
+    askMarkerPattern: `${markerPrefix}ASK_[0-9]+\uE001`,
+    askMarkerPrefix: `${markerPrefix}ASK_`,
+    restore(value) {
+      return spans.reduce(
+        (next, { marker, original }) => next.split(marker).join(original),
+        value
+      );
+    }
+  };
+}
+
+function normalizeAskUserQuestion(content) {
+  const masked = maskMarkdownCodeSpans(content);
+  const determinerPattern = [
+    'one', 'each', 'every', 'another', 'this', 'that', 'a', 'an', 'the'
+  ].map((word) => [...word].map((letter) => `[${letter}${letter.toUpperCase()}]`).join('')).join('|');
+  const oneSeparator = '(?:[^\\S\\r\\n]+|[^\\S\\r\\n]*\\r?\\n[^\\S\\r\\n]*)';
+  const pattern = new RegExp(
+    `(?:(\\b(?:${determinerPattern}|[0-9]+)\\b)(${oneSeparator}))?`
+      + `(\\bAskUserQuestion\\b|${masked.askMarkerPattern})`,
+    'g'
+  );
+  const normalized = masked.content.replace(pattern, (match, determiner, spacing, _token, offset, source) => {
+    const literalIndex = match.indexOf('AskUserQuestion');
+    const tokenOffset = offset + (literalIndex >= 0
+      ? literalIndex
+      : match.indexOf(masked.askMarkerPrefix));
+    const previous = source[tokenOffset - 1] || '';
+    if (isMarkdownLinkDestination(source, tokenOffset)
+      || isUrlLikeToken(source, tokenOffset)
+      || /[/=?#&%@]/.test(previous)) {
+      return match;
+    }
+
+    if (determiner) {
+      const normalizedDeterminer = /^an$/i.test(determiner)
+        ? (determiner[0] === 'A' ? 'A' : 'a')
+        : determiner;
+      return `${normalizedDeterminer}${spacing}structured user-input request`;
+    }
+
+    const trailing = source.slice(offset + match.length);
+    const pluralContext = new RegExp(`^${oneSeparator}(?:calls|batches)\\b`, 'i').test(trailing);
+    return `${pluralContext ? '' : 'a '}structured user-input request`;
+  });
+  return masked.restore(normalized);
+}
+
 function normalizeRuntimePaths(content) {
   return normalizeSourcePaths(content, {
     runtimeRoot: '.codex',
@@ -78,11 +243,11 @@ function normalizeRuntimePaths(content) {
 
 function normalizeSkillNames(content) {
   return content
-    .replace(/\/hapo:([a-z0-9-]+)/gi, (_match, name) => `$hapo-${name}`)
-    .replace(/\bhapo:([a-z0-9-]+)/gi, (_match, name) => `hapo-${name}`)
+    .replace(/\/cf:([a-z0-9-]+)/gi, (_match, name) => `$cf-${name}`)
+    .replace(/\bcf:([a-z0-9-]+)/gi, (_match, name) => `cf-${name}`)
     .replace(
       /(^|[\s("'`→])\/(brainstorm|code-review|debug|develop|docs|frontend-design|git|hotfix|inspect|question|research|specs|test)(?=$|[\s<`),.:])/gim,
-      (_match, prefix, name) => `${prefix}$hapo-${name}`
+      (_match, prefix, name) => `${prefix}$cf-${name}`
     );
 }
 
@@ -129,7 +294,7 @@ function normalizeCodexBody(content, sourcePath = '') {
   if (!isInstructionAsset(sourcePath)) return next;
 
   next = normalizeAgentInvocations(normalizeAgentNames(normalizeSkillNames(next)));
-  return applyReplacements(next, INSTRUCTION_REPLACEMENTS);
+  return applyReplacements(normalizeAskUserQuestion(next), INSTRUCTION_REPLACEMENTS);
 }
 
 function getCodexCopyOptions(baseOptions = {}) {