@haposoft/cafekit 0.16.0-rc.5 → 0.16.0-rc.7

package/README.md

@@ -1,6 +1,6 @@
 # @haposoft/cafekit
 
-> Native spec-driven workflow and runtime bundle for Claude Code, Codex CLI, and OpenCode.
+> Native spec-driven workflow and runtime bundle for Claude Code and Codex CLI.
 
 [![Version](https://img.shields.io/badge/version-0.16.0-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
@@ -28,14 +28,6 @@ Codex CLI install support:
 - merges a CafeKit-owned block into root `AGENTS.md`
 - requires no generated `.codex/config.toml` and never changes global trust config
 
-OpenCode install support:
-- installs command wrappers under `.opencode/commands/`
-- installs converted OpenCode agents under `.opencode/agents/`
-- installs CafeKit skills under `.opencode/skills/`
-- installs OpenCode plugin runtime files under `.opencode/plugins/`
-- merges `opencode.json` and root `AGENTS.md`
-- omits the Claude `hapo:` command prefix
-
 ## Install
 
 Run in your project root:
@@ -59,7 +51,7 @@ npx @haposoft/cafekit --platform codex --force-overwrite
 
 Requirements:
 - Node.js 18+
-- Claude Code, Codex CLI, or OpenCode; choose a runtime when prompted or use `--platform`
+- Claude Code or Codex CLI; choose a runtime when prompted or use `--platform`
 
 ## Git ignore policy
 
@@ -75,15 +67,13 @@ plans/*
 .cafekit-backup/
 .cafekit.lock
 .claude/
-.opencode/
 .codex/
 .agents/
 ```
 
 Runtime folders are local — reinstall with `npx @haposoft/cafekit` rather than
-committing them. Inside the runtime, CafeKit also installs `.claude/.gitignore`,
-`.opencode/.gitignore`, or the Codex pair `.codex/.gitignore` +
-`.agents/.gitignore`. These keep secrets, skill dependencies, session state,
+committing them. Inside the runtime, CafeKit also installs `.claude/.gitignore` or the
+Codex pair `.codex/.gitignore` + `.agents/.gitignore`. These keep secrets, skill dependencies, session state,
 and hook logs out of git even if someone partially un-ignores a runtime.
 Teams may deliberately commit runtime files, but should also commit the
 ownership manifest so selective updates share the same baseline.
@@ -141,37 +131,11 @@ without requiring Git and remain stable when a session starts in a subdirectory.
 CafeKit uses Codex's native status and usage UI instead of installing the
 Claude statusline.
 
-OpenCode targets:
-
-```text
-.opencode/
-├── .gitignore
-├── commands/
-├── agents/
-├── skills/
-├── rules/
-├── scripts/
-├── references/
-├── plugins/
-├── cafekit.json
-├── runtime.json
-└── package.json
-
-AGENTS.md
-opencode.json
-```
-
-OpenCode setup also:
-- binds generated commands to matching CafeKit subagents with `agent` + `subtask`
-- configures `permission.skill` and `permission.task`
-- optionally writes `model` to `opencode.json` from `OPENCODE_MODEL`, `OPENCODE_DEFAULT_MODEL`, or installer input
-
 To check the installed CafeKit package version:
 
 ```bash
 cat .claude/cafekit.json
 cat .codex/cafekit.json
-cat .opencode/cafekit.json
 ```
 
 ## Core Skills
@@ -224,17 +188,6 @@ $hapo-test meet-transcript-mvp --full
 $hapo-code-review meet-transcript-mvp --pending
 ```
 
-OpenCode uses the generated command names without the Claude `hapo:` prefix:
-
-```bash
-/question "Which files define the current CafeKit install/runtime behavior?" --repo
-/brainstorm Explore approaches for a Google Meet transcript extension
-/specs Build a Google Meet transcript extension with AI summaries
-/develop meet-transcript-mvp
-/test --full
-/code-review --pending
-```
-
 Reconstruct as-is docs from a legacy codebase:
 
 ```bash
@@ -253,16 +206,26 @@ hosted or specialized tools may not enter the local hook path.
 
 ## Spec Output
 
-Specs are stored under:
+New process-first Specs packets are stored under:
 
 ```text
 specs/<feature-name>/
-├── spec.json
-├── requirements.md
-├── research.md
-├── design.md
-└── tasks/task-R*.md
-```
+├── plan.md
+├── task-01-<slug>.md
+└── task-NN-<slug>.md
+```
+
+The process-first workflow has three human decision gates. `hapo:specs` opens
+C1 to fix scope before authoring and C2 to resolve adversarial findings, then
+stops. A later explicit `hapo:develop` invocation executes the tasks and
+presents C3 for closeout only after real execution proof. Each task has one
+`Status:` field and keeps its canonical `## Receipt` inline, including the
+exact Verification Plan command, `Exit: 0`, `Verification: PASS`,
+runtime-derived Base and Head, and current command output.
+
+Existing packets with `spec.json`, nested `tasks/task-R*.md`, or separate
+receipts remain supported through the legacy compatibility adapter. New Specs
+work does not author those legacy artifacts.
 
 ## Development
 

package/bin/__tests__/change-firewall.semantic-firewall.test.js

@@ -66,7 +66,7 @@ function initRepo(root, { version = '0.0.1-fixture' } = {}) {
 }
 
 function writeLegacyBridge(root, { baseCommit, semanticDigest = cf.sha256Tag('bridge-digest') }) {
-  writeJson(path.join(root, 'specs/cafekit-semantic-eval-firewall/reports/bootstrap-legacy-bridge-review.json'), {
+  writeJson(path.join(root, 'specs/archive/cafekit-semantic-eval-firewall/reports/bootstrap-legacy-bridge-review.json'), {
     schema_version: '1',
     verdict: 'PASS',
     blocking_count: 0,
@@ -78,7 +78,7 @@ function writeLegacyBridge(root, { baseCommit, semanticDigest = cf.sha256Tag('br
 }
 
 function writeFeatureSeedPass(root, { reviewReceiptDigest = cf.sha256Tag('seed-review-receipt') } = {}) {
-  writeJson(path.join(root, 'specs/cafekit-semantic-eval-firewall/spec.json'), {
+  writeJson(path.join(root, 'specs/archive/cafekit-semantic-eval-firewall/spec.json'), {
     validation: {
       semantic_review_history: {
         entries: [{
@@ -201,7 +201,7 @@ test('R1.14 negative: an absent or malformed legacy-bridge artifact fails the pr
     const inst = cf.createChangeFirewall({ root });
     assert.throws(() => inst.assertLegacyBridgeArtifact(), (error) => error.code === 'legacy_bridge_missing');
 
-    writeJson(path.join(root, 'specs/cafekit-semantic-eval-firewall/reports/bootstrap-legacy-bridge-review.json'), {
+    writeJson(path.join(root, 'specs/archive/cafekit-semantic-eval-firewall/reports/bootstrap-legacy-bridge-review.json'), {
       schema_version: '1', verdict: 'FAIL', blocking_count: 0,
       reviewed_criteria: ['R1.1'], semantic_digest: cf.sha256Tag('x'),
       bootWindowBaseCommit: '0'.repeat(40), written_at: new Date().toISOString(),
@@ -379,7 +379,7 @@ test('C14/R1.8: bootstrapBaseline refuses before the seed PASS exists, and refus
     const inst = cf.createChangeFirewall({ root });
 
     // feature spec.json exists but carries no semantic_review_history yet (no seed PASS).
-    writeJson(path.join(root, 'specs/cafekit-semantic-eval-firewall/spec.json'), { validation: {} });
+    writeJson(path.join(root, 'specs/archive/cafekit-semantic-eval-firewall/spec.json'), { validation: {} });
     assert.throws(
       () => inst.bootstrapBaseline({ baseCommit, headCommit, bootstrapReviewDigest: cf.sha256Tag('x'), packageVersion: '0.0.1-fixture' }),
       (error) => error.code === 'seed_pass_missing',
@@ -2131,4 +2131,3 @@ test('REGRESSION round7 (critical): a committed C10 authority renamed away then
     assert.throws(() => inst.createFreezeManifest(null), (error) => error.code === 'out_of_band_edit');
   });
 });
-

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

@@ -45,6 +45,16 @@ function bindReceipt(root, value, feature = 'auth', session = 'session-a') {
   return value.replaceAll(VALID_BASE, context.base).replaceAll(VALID_HEAD, context.head);
 }
 
+function workflowRuntimeContext(root, feature = 'auth', session = 'session-a') {
+  return PROVENANCE.deriveRuntimeContext({
+    projectRoot: root,
+    specsRoot: path.join(root, 'specs'),
+    specFile: path.join(root, 'specs', feature, 'plan.md'),
+    featureName: feature,
+    runtimeSession: session,
+  });
+}
+
 function installFeatureReceipts(root, session = 'session-a') {
   const specsRoot = path.join(root, 'specs');
   if (!fs.existsSync(specsRoot)) return;
@@ -414,6 +424,133 @@ test('Codex completion gate cannot be bypassed from a nested cwd', () => {
   });
 });
 
+test('Codex completion gate validates explicit process-v3 inline Receipt', () => {
+  inHookFixture((root, hooks) => {
+    const nested = path.join(root, 'packages', 'app');
+    const feature = path.join(root, 'specs', 'auth');
+    const taskFile = path.join(feature, 'task-01-auth.md');
+    fs.mkdirSync(nested, { recursive: true });
+    fs.mkdirSync(feature, { recursive: true });
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n');
+    fs.writeFileSync(taskFile, [
+      '# Task 01: auth', '', 'Status: done', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+    ].join('\n'));
+
+    const gate = path.join(hooks, 'spec-gate.cjs');
+    const payload = {
+      cwd: nested,
+      featureName: 'auth',
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+    };
+    const blocked = runHook(gate, nested, payload);
+    assert.equal(blocked.status, 0, blocked.stderr);
+    assert.match(JSON.parse(blocked.stdout).reason, /missing_receipt/);
+
+    const context = workflowRuntimeContext(root);
+    fs.writeFileSync(taskFile, [
+      '# Task 01: auth', '', 'Status: done', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '## Receipt', '',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${context.base}`, `Head: ${context.head}`,
+      '```text', '$ node --test', 'pass: 1', '```', '',
+    ].join('\n'));
+    const passed = runHook(gate, nested, payload);
+    assert.equal(passed.status, 0, passed.stderr);
+    assert.equal(passed.stdout, '');
+  });
+});
+
+test('Codex process-v3 Receipt command must match the exact Verification Plan command', () => {
+  inHookFixture((root, hooks) => {
+    const feature = path.join(root, 'specs', 'auth');
+    fs.mkdirSync(feature, { recursive: true });
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n');
+    const context = workflowRuntimeContext(root);
+    fs.writeFileSync(path.join(feature, 'task-01-auth.md'), [
+      '# Task 01: auth', '', 'Status: done', '',
+      '## Verification Plan', '', '- Command: pnpm test', '',
+      '## Receipt', '', 'Verification: PASS', 'Command: true', 'Exit: 0',
+      `Base: ${context.base}`, `Head: ${context.head}`,
+      '```text', '$ true', 'pass: 1', '```', '',
+    ].join('\n'));
+
+    const result = runHook(path.join(hooks, 'spec-gate.cjs'), root, {
+      cwd: root,
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.notEqual(result.stdout, '', 'a substituted receipt command must block');
+    assert.match(JSON.parse(result.stdout).reason, /command_identity/);
+  });
+});
+
+test('Codex process-v3 Stop ignores a completed packet when one packet remains active', () => {
+  inHookFixture((root, hooks) => {
+    const completed = path.join(root, 'specs', 'auth');
+    const active = path.join(root, 'specs', 'active');
+    fs.mkdirSync(completed, { recursive: true });
+    fs.mkdirSync(active, { recursive: true });
+    fs.writeFileSync(path.join(completed, 'plan.md'), '# Auth plan\n');
+    fs.writeFileSync(path.join(active, 'plan.md'), '# Active plan\n');
+    const context = workflowRuntimeContext(root);
+    fs.writeFileSync(path.join(completed, 'task-01-auth.md'), [
+      '# Task 01: auth', '', 'Status: done', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '## Receipt', '',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${context.base}`, `Head: ${context.head}`,
+      '```text', '$ node --test', 'pass: 1', '```', '',
+    ].join('\n'));
+    fs.writeFileSync(path.join(active, 'task-01-active.md'), [
+      '# Task 01: active', '', 'Status: pending', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+    ].join('\n'));
+
+    const result = runHook(path.join(hooks, 'spec-gate.cjs'), root, {
+      cwd: root,
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, '');
+  });
+});
+
+test('Codex process-v3 Stop accepts two completed packets with valid Receipts', () => {
+  inHookFixture((root, hooks) => {
+    for (const featureName of ['auth', 'other']) {
+      const feature = path.join(root, 'specs', featureName);
+      fs.mkdirSync(feature, { recursive: true });
+      fs.writeFileSync(path.join(feature, 'plan.md'), `# ${featureName} plan\n`);
+      const context = workflowRuntimeContext(root, featureName);
+      fs.writeFileSync(path.join(feature, `task-01-${featureName}.md`), [
+        `# Task 01: ${featureName}`, '', 'Status: done', '',
+        '## Verification Plan', '', '- Command: node --test', '',
+        '## Receipt', '',
+        'Verification: PASS', 'Command: node --test', 'Exit: 0',
+        `Base: ${context.base}`, `Head: ${context.head}`,
+        '```text', '$ node --test', 'pass: 1', '```', '',
+      ].join('\n'));
+    }
+
+    const result = runHook(path.join(hooks, 'spec-gate.cjs'), root, {
+      cwd: root,
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, '');
+  });
+});
+
 test('empty or forged Codex hook authority fails closed', () => {
   inHookFixture((root, hooks) => {
     const gate = path.join(hooks, 'spec-gate.cjs');

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

@@ -28,6 +28,35 @@ const INSTALLER = path.join(PACKAGE_ROOT, 'bin/install.js');
 const MANIFEST = JSON.parse(
   fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'), 'utf8')
 );
+const SPECS_SOURCE_ROOT = path.join(PACKAGE_ROOT, 'src/claude/skills/specs');
+const V3_SPECS_BUNDLE = [
+  'SKILL.md',
+  'references/review.md',
+  'references/templates.md',
+  'templates/design.md',
+  'templates/requirements-init.md',
+  'templates/requirements.md',
+  'templates/research.md',
+  'templates/spec-state.json',
+  'templates/task.md'
+];
+const OBSOLETE_SPECS_FILES = [
+  'references/archive-workflow.md',
+  'references/ask-user-question-gates.md',
+  'references/codebase-analysis.md',
+  'references/cross-spec-dependency.md',
+  'references/research-strategy.md',
+  'references/scope-inquiry.md',
+  'references/translation-mirror.md',
+  'rules/design-discovery-full.md',
+  'rules/design-discovery-light.md',
+  'rules/design-principles.md',
+  'rules/design-review.md',
+  'rules/ears-format.md',
+  'rules/phase-decision-matrix.md',
+  'rules/task-scoring-rubric.md',
+  'rules/tasks-generation.md'
+];
 
 function inTempProject(run) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-native-'));
@@ -130,91 +159,99 @@ function assertInstalledVerificationModel(grounderPath, designTemplate) {
   }
 }
 
-function artifactRouterRecords(skill) {
-  const lines = skill.split('\n');
-  const heading = lines.findIndex((line) => line.trim() === '## Artifact router');
-  const start = lines.findIndex((line, index) => index > heading && line.trim().startsWith('|'));
-  const rows = [];
-  for (let index = start; index >= 0 && index < lines.length && lines[index].trim().startsWith('|'); index += 1) {
-    const cells = lines[index].split('|').slice(1, -1).map((cell) => cell.trim());
-    if (!cells.every((cell) => /^:?-+:?$/.test(cell))) rows.push(cells);
-  }
-  const header = rows.shift() || [];
-  return new Map(rows.map((cells) => [
-    (cells[0] || '').replaceAll('`', ''),
-    Object.fromEntries(header.map((name, index) => [name, cells[index] || '']))
-  ]));
-}
-
 function installedAuthoringProjectionIssues(files) {
   const issues = [];
-  const routes = artifactRouterRecords(files.skill);
-  const none = routes.get('None');
-  if (!none || none['Durable core'] !== 'none'
-    || none['Research route'] !== 'absent' || none['Task route'] !== 'absent') {
-    issues.push('none-route');
+  const foreignRuntimeBoundary = 'If you are Claude Code or any other runtime, ignore this entire Codex block';
+  if (!files.skill.includes('Task files are flat beside `plan.md`')
+    || !files.skill.includes('Do not create a nested task directory.')) {
+    issues.push('flat-layout-entrypoint');
   }
-  for (const depth of ['Compact', 'Full']) {
-    const route = routes.get(depth);
-    if (!route || !['spec.json', 'requirements.md', 'design.md'].every((name) => (
-      route['Durable core'].includes(`\`${name}\``)
-    ))) issues.push(`${depth.toLowerCase()}-core`);
-    if (!route?.['Research route'].includes('research trigger')) issues.push(`${depth.toLowerCase()}-research`);
-    if (!route?.['Task route'].includes('typed topology trigger')) issues.push(`${depth.toLowerCase()}-tasks`);
+  if (!files.templates.includes('The primary layout is always flat:')
+    || !files.templates.includes('task-NN-<slug>.md')) {
+    issues.push('flat-layout-template');
   }
-  if (/\balways search\b|\bcomprehensive research\b|\bcapture all findings\b/i.test(files.discovery)) {
-    issues.push('default-research');
+  for (const gate of ['C1 — Scope', 'C2 — Findings', 'C3 — Done']) {
+    if (!files.skill.includes(gate)) issues.push(`human-gate-${gate.slice(0, 2).toLowerCase()}`);
   }
-  if (/(?:limit|maximum|at most|top|≤|<=)\s*(?:to\s*)?3\b/i.test(files.review)) {
-    issues.push('review-cap');
+  if (!files.review.includes('fresh-context red team')
+    || !/Cap the presented\s+list at 15/.test(files.review)
+    || !files.review.includes('at most two review-and-repair rounds')) {
+    issues.push('adversarial-review');
   }
-  if (!/For every `RN\.M`/.test(files.review)) issues.push('criterion-coverage');
-  if (/\bcurrent_phase\b/.test(files.codex)) issues.push('phase-alias');
-  for (const state of ['in_progress', 'paused', 'blocked', 'done']) {
-    if (!files.codex.includes(`\`${state}\``)) issues.push(`lifecycle-${state}`);
+  if (!files.skill.includes('inline `## Receipt`')
+    || !files.templates.includes('## Canonical inline Receipt')) {
+    issues.push('inline-receipt');
+  }
+  for (const field of [
+    'Verification: PASS', 'Command:', 'Exit: 0', 'Base:', 'Head:'
+  ]) {
+    if (!files.templates.includes(field)) issues.push(`receipt-${field.toLowerCase()}`);
+  }
+  if (!/^name: hapo-specs$/m.test(files.skill)) issues.push('codex-skill-name');
+  const bundle = [files.skill, files.review, files.templates, files.legacyTemplates].join('\n');
+  const runtimeProjection = `${bundle}\n${files.codex.replace(foreignRuntimeBoundary, '')}`;
+  if (!files.codex.includes(foreignRuntimeBoundary)
+    || files.codex.includes('If you are Codex CLI or any other runtime, ignore this entire Codex block')) {
+    issues.push('codex-ownership-boundary');
   }
-  if (/^##\s+Evidence\s*$/m.test(files.tasks)) issues.push('task-evidence');
-  if (/\(P\)/.test(files.tasks)) issues.push('task-priority-marker');
   for (const claudeOnly of [
     'AskUserQuestion', 'TaskCreate', 'TaskGet', 'TaskUpdate', 'TaskList',
-    'WebSearch', 'WebFetch', 'SendMessage'
+    'WebSearch', 'WebFetch', 'SendMessage', 'Claude Code', '.claude', '/hapo:', 'hapo:'
   ]) {
-    if (files.codex.includes(claudeOnly)) issues.push(`claude-tool-${claudeOnly}`);
+    if (runtimeProjection.includes(claudeOnly)) issues.push(`claude-vocabulary-${claudeOnly}`);
+  }
+  for (const command of ['$hapo-specs', '$hapo-develop', '$hapo-sync']) {
+    if (!files.codex.includes(command)) issues.push(`codex-command-${command}`);
+  }
+  for (const state of ['pending', 'in_progress', 'paused', 'blocked', 'done']) {
+    if (!files.codex.includes(`\`${state}\``)) issues.push(`lifecycle-${state}`);
   }
-  if (!files.codex.includes('semantic_model')
-    || !files.codex.includes('explicit installed machine semantic-sync step')
-    || !files.codex.includes('round-trip')
-    || !files.codex.includes('node .codex/scripts/spec-scaffold.cjs <feature> --sync-semantic-model')) {
-    issues.push('semantic-model-promotion');
+  if (!files.codex.includes('flat `task-NN-*.md` files')
+    || !files.codex.includes('inline `## Receipt`')
+    || !files.codex.includes('C1') || !files.codex.includes('C2') || !files.codex.includes('C3')) {
+    issues.push('codex-process-v3');
   }
   return issues;
 }
 
 function assertInstalledAuthoringProjection(root) {
-  const read = (relative) => fs.readFileSync(path.join(root, relative), 'utf8');
+  const installedRoot = path.join(root, '.agents/skills/specs');
+  const relativeFiles = (directory) => allFiles(directory, () => true)
+    .map((file) => path.relative(directory, file).split(path.sep).join('/'))
+    .sort();
+  assert.deepEqual(relativeFiles(SPECS_SOURCE_ROOT), V3_SPECS_BUNDLE);
+  assert.deepEqual(relativeFiles(installedRoot), V3_SPECS_BUNDLE);
+
+  for (const relative of V3_SPECS_BUNDLE) {
+    const sourcePath = path.join(SPECS_SOURCE_ROOT, relative);
+    const expected = normalizeCodexBody(fs.readFileSync(sourcePath, 'utf8'), sourcePath);
+    const actual = fs.readFileSync(path.join(installedRoot, relative), 'utf8');
+    assert.equal(actual, expected, `Codex Specs projection drifted: ${relative}`);
+  }
+  for (const relative of OBSOLETE_SPECS_FILES) {
+    assert.equal(fs.existsSync(path.join(installedRoot, relative)), false, `obsolete Specs file installed: ${relative}`);
+  }
+
+  const read = (relative) => fs.readFileSync(path.join(installedRoot, relative), 'utf8');
   const files = {
-    skill: read('.agents/skills/specs/SKILL.md'),
-    discovery: [
-      read('.agents/skills/specs/rules/design-discovery-light.md'),
-      read('.agents/skills/specs/rules/design-discovery-full.md')
-    ].join('\n'),
-    review: [
-      read('.agents/skills/specs/rules/design-review.md'),
-      read('.agents/skills/specs/references/review.md')
-    ].join('\n'),
-    tasks: [
-      read('.agents/skills/specs/rules/tasks-generation.md'),
-      read('.agents/skills/specs/rules/task-scoring-rubric.md'),
-      read('.agents/skills/specs/rules/phase-decision-matrix.md')
-    ].join('\n'),
-    codex: [read('AGENTS.md'), read('.codex/rules/state-sync.md')].join('\n')
+    skill: read('SKILL.md'),
+    review: read('references/review.md'),
+    templates: read('references/templates.md'),
+    legacyTemplates: V3_SPECS_BUNDLE
+      .filter((relative) => relative.startsWith('templates/'))
+      .map(read)
+      .join('\n'),
+    codex: [
+      fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8'),
+      fs.readFileSync(path.join(root, '.codex/rules/state-sync.md'), 'utf8')
+    ].join('\n')
   };
   assert.deepEqual(installedAuthoringProjectionIssues(files), []);
   const mutations = [
-    ['discovery', (value) => `${value}\nAlways search before design.`],
-    ['review', (value) => `${value}\nLimit to 3 blockers.`],
-    ['codex', (value) => `${value}\nSet current_phase then call TaskUpdate.`],
-    ['tasks', (value) => `${value}\n## Evidence\nUse (P).`]
+    ['skill', (value) => value.replace('Task files are flat beside `plan.md`', 'Task files may be nested')],
+    ['review', (value) => value.replace('list at 15', 'list without a cap')],
+    ['templates', (value) => value.replace('Verification: PASS', 'Verification: UNKNOWN')],
+    ['codex', (value) => `${value}\nUse TaskUpdate for state changes.`]
   ];
   for (const [key, mutate] of mutations) {
     const changed = { ...files, [key]: mutate(files[key]) };
@@ -271,7 +308,7 @@ test('platform resolver keeps saved runtimes and newly detected Codex', async ()
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-detect-'));
   const originalCwd = process.cwd();
   try {
-    for (const folder of ['.claude', '.opencode', '.codex']) {
+    for (const folder of ['.claude', '.codex']) {
       fs.mkdirSync(path.join(root, folder), { recursive: true });
     }
     fs.writeFileSync(
@@ -287,7 +324,7 @@ test('platform resolver keeps saved runtimes and newly detected Codex', async ()
       t: (key) => key
     };
     await resolvePlatforms(ctx);
-    assert.deepEqual(ctx.platforms, ['claude', 'opencode', 'codex']);
+    assert.deepEqual(ctx.platforms, ['claude', 'codex']);
   } finally {
     process.chdir(originalCwd);
     fs.rmSync(root, { recursive: true, force: true });
@@ -645,7 +682,7 @@ test('Codex Windows hook launchers stay project-bound without Git from nested cw
   });
 });
 
-test('Codex install is project-local, native, and upgrade-safe', () => {
+test('Codex fresh install is exact while refresh and upgrade preserve existing files', () => {
   inTempProject((root) => {
     const userInstructions = '# User rules\n\nKeep this exact.\n';
     fs.writeFileSync(path.join(root, 'AGENTS.md'), userInstructions);
@@ -653,7 +690,6 @@ test('Codex install is project-local, native, and upgrade-safe', () => {
     const first = install(root);
     assert.equal(first.status, 0, `${first.stdout}\n${first.stderr}`);
     assert.equal(fs.existsSync(path.join(root, '.claude')), false);
-    assert.equal(fs.existsSync(path.join(root, '.opencode')), false);
     assert.equal(fs.existsSync(path.join(root, '.codex', 'config.toml')), false);
 
     for (const relative of [
@@ -666,10 +702,7 @@ test('Codex install is project-local, native, and upgrade-safe', () => {
       '.codex/scripts/spec-ground.cjs',
       '.codex/scripts/validate-spec-output.cjs',
       '.agents/.gitignore',
-      '.agents/skills/specs/SKILL.md',
-      '.agents/skills/specs/templates/design.md',
-      '.agents/skills/specs/templates/task.md',
-      '.agents/skills/specs/templates/spec-state.json'
+      ...V3_SPECS_BUNDLE.map((file) => `.agents/skills/specs/${file}`)
     ]) {
       assert.equal(fs.existsSync(path.join(root, relative)), true, `missing ${relative}`);
     }
@@ -777,7 +810,13 @@ test('Codex install is project-local, native, and upgrade-safe', () => {
       ...allFiles(path.join(root, '.agents', 'skills'), (file) => file.endsWith('.md'))
     ];
     const visible = modelVisibleFiles.map((file) => fs.readFileSync(file, 'utf8')).join('\n');
-    assert.doesNotMatch(visible, /\bAgent\(|subagent_type|`Agent`|\bSendMessage\b|\/hapo:|\bhapo:|Claude Code/);
+    const foreignRuntimeBoundary = 'If you are Claude Code or any other runtime, ignore this entire Codex block';
+    assert.match(visible, new RegExp(foreignRuntimeBoundary));
+    assert.doesNotMatch(visible, /If you are Codex CLI or any other runtime, ignore this entire Codex block/);
+    assert.doesNotMatch(
+      visible.replaceAll(foreignRuntimeBoundary, ''),
+      /\bAgent\(|subagent_type|`Agent`|\bSendMessage\b|\/hapo:|\bhapo:|Claude Code/,
+    );
     assert.doesNotMatch(visible, /@@PRIVACY_PROMPT_START@@|Claude Tasks/);
     assert.match(visible, /\$hapo-specs/);
 
@@ -796,10 +835,22 @@ test('Codex install is project-local, native, and upgrade-safe', () => {
 
     const questionSkill = path.join(root, '.agents', 'skills', 'question', 'SKILL.md');
     fs.appendFileSync(questionSkill, '\nUSER-CODEX-SENTINEL\n');
+    // Fresh installs are exact. Refresh/upgrade intentionally documents the
+    // current Codex limitation: removed skill paths are not pruned.
+    const obsoleteSpecsRule = path.join(
+      root, '.agents', 'skills', 'specs', 'rules', 'design-principles.md'
+    );
+    fs.mkdirSync(path.dirname(obsoleteSpecsRule), { recursive: true });
+    fs.writeFileSync(obsoleteSpecsRule, 'LEGACY-CODEX-ORPHAN\n');
 
     const sameVersion = install(root);
     assert.equal(sameVersion.status, 0, `${sameVersion.stdout}\n${sameVersion.stderr}`);
     assert.match(fs.readFileSync(questionSkill, 'utf8'), /USER-CODEX-SENTINEL/);
+    assert.equal(
+      fs.existsSync(obsoleteSpecsRule),
+      true,
+      'known limitation: Codex refresh does not prune obsolete skill files'
+    );
 
     const metadataPath = path.join(root, '.codex', 'cafekit.json');
     const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
@@ -809,6 +860,11 @@ test('Codex install is project-local, native, and upgrade-safe', () => {
     const upgrade = install(root);
     assert.equal(upgrade.status, 0, `${upgrade.stdout}\n${upgrade.stderr}`);
     assert.match(fs.readFileSync(questionSkill, 'utf8'), /USER-CODEX-SENTINEL/);
+    assert.equal(
+      fs.existsSync(obsoleteSpecsRule),
+      true,
+      'known limitation: Codex upgrade does not prune obsolete skill files'
+    );
     assert.ok(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8').startsWith(userInstructions));
 
     const forced = install(root, ['--force-overwrite']);