@haposoft/cafekit 0.16.0-rc.6 → 0.16.0-rc.8

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

@@ -28,6 +28,68 @@ 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 IMPLEMENTATION_READINESS_BOUNDARY_ROWS = [
+  ['API/CLI', 'entrypoint/route or command grammar; identity/auth; input/default/normalization; success output; error/status/exit; duplicate/retry/idempotency; compatibility'],
+  ['Schema', 'version; exact keys/nesting/types; required/optional; enum/format/bounds/cardinality; unknown-field behavior; compatibility/migration'],
+  ['State/concurrency', 'initial/terminal states; event + guard + effect + next + error; ordering; duplicate/retry; writer/lock acquire/contention/release; rollback/recovery'],
+  ['Filesystem/security', 'authoritative root; trusted/untrusted segment grammar; lexical + canonical containment and symlink policy; flags/mode; temp/rename/fsync; lock/stale reclaim; crash cleanup'],
+  ['Time/retention', 'clock source; unit/precision/timezone; endpoints and inclusion/comparator; anomaly behavior; expiry/purge/recovery'],
+  ['Integration/proof', 'caller; export/registration; packaging/config; native path/consumer; proof level (`source`/`installed`/`live`); observable failure oracle']
+];
+const IMPLEMENTATION_READINESS_CLAUSES = {
+  noInvention: 'Before implementation handoff, apply the **no-invention gate**: if two implementations conform to the packet text yet can produce different externally observable output, state, error, security, or compatibility behavior, surface the missing choice as an explicit C1 or C2 question and block handoff.',
+  materialDefinition: 'A boundary is material when the task creates, changes, or depends on it and a different choice changes an external observation, security, durable data, compatibility, or proof reachability. Require only the matching material row; omit nonmaterial categories.',
+  exactBoundaryChoices: 'For every required row, name each listed choice exactly; labels such as “JSON”, “local path”, “locked”, or “timestamped” alone remain unresolved.',
+  proofPlanLines: [
+    '- Command: `<exact runnable command>`',
+    '- Named probe: <existing concrete probe/test/hook ID; never only a suite label>',
+    '- Reachability: <real entrypoint/caller at each `source`/`installed`/`live` level; `UNKNOWN` if unexecuted>',
+    '- Oracle: <externally observable success or failure>',
+    '- Counterexample: <material alternative behavior that must make this proof fail>',
+    '- Artifacts: <required artifact path plus digest algorithm/comparison rule, or explicitly ephemeral with cleanup rule>'
+  ],
+  proofTrace: 'Trace `Command → Named probe → Reachability → Oracle`.',
+  namedProbeOwnership: 'Aggregate suites\nname the owning concrete probe.',
+  proofLevelSeparation: 'Proof at `source`/`installed`/`live` stays\nseparate; one level never promotes another.',
+  disposableTemplateControls: 'Run mutation or destructive\nnegative controls only on disposable copies under a verified temporary root,\nnever tracked worktree or canonical source bytes.',
+  disposableReviewControls: 'Run mutation or destructive negative controls only on disposable copies below a verified temporary root, never tracked worktree or canonical source bytes.',
+  failureSemantics: '`Crash` means abrupt unhandled termination before the claimed catch point; a catchable failure returns/raises an error or exits nonzero. Never use them interchangeably.',
+  privacyIdentifiers: 'Any privacy/security claim names the exact identifier surface at risk, such as an env var, header, path, token class, or field name; generic “sensitive data” is insufficient.',
+  freshReplay: 'After applying an accepted C2 finding, a fresh-context closure pass records and freshly replays its original counterexample after the repair under this exact review-log header:',
+  distinctRepairProof: '`Repaired at` cites the repair edit; `Proved at` must cite distinct evidence from the fresh replay, never the repair-edit citation.',
+  closureTransition: 'An accepted finding transitions `accepted → repaired → PASS|FAIL|UNKNOWN`.',
+  unknownBlocks: 'Only `PASS` closes it; `FAIL` remains open for the remaining paper-review round; `UNKNOWN` blocks implementation handoff.',
+  scopeReturnsToC1: 'A repair that adds user semantics or scope returns to C1.'
+};
+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,95 +192,498 @@ 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('|'));
+function markdownSection(content, heading) {
+  const lines = String(content).split('\n');
+  const start = lines.findIndex((line) => line.trim() === `## ${heading}`);
+  if (start < 0) return '';
+  const end = lines.findIndex((line, index) => index > start && /^##\s+/.test(line));
+  return lines.slice(start + 1, end < 0 ? undefined : end).join('\n');
+}
+
+function markdownTableUnderHeading(content, heading) {
+  const lines = markdownSection(content, heading).split('\n');
+  const tableStart = lines.findIndex((line) => line.trim().startsWith('|'));
+  if (tableStart < 0) return [];
   const rows = [];
-  for (let index = start; index >= 0 && index < lines.length && lines[index].trim().startsWith('|'); index += 1) {
+  for (let index = tableStart; 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);
+    if (cells.every((cell) => /^:?-+:?$/.test(cell))) continue;
+    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] || '']))
-  ]));
+  return rows;
+}
+
+function normalizeMarkdownWhitespace(content) {
+  return String(content).replace(/\s+/g, ' ').trim();
+}
+
+function markdownBetweenHeadings(content, startHeading, endHeading) {
+  const value = String(content);
+  const startMarker = `## ${startHeading}`;
+  const endMarker = `## ${endHeading}`;
+  const startIndex = value.indexOf(startMarker);
+  const endIndex = value.indexOf(endMarker, startIndex + startMarker.length);
+  if (startIndex < 0 || endIndex < 0) return '';
+  return value.slice(startIndex + startMarker.length, endIndex);
+}
+
+function implementationReadinessIssues(templates, review) {
+  if (typeof templates !== 'string' || typeof review !== 'string') {
+    throw new TypeError('implementation-readiness checker expects templates and review UTF-8 strings');
+  }
+
+  const issues = new Set();
+  const authoring = markdownSection(templates, 'No-invention and conditional boundary contracts');
+  if (!authoring.includes(IMPLEMENTATION_READINESS_CLAUSES.noInvention)) {
+    issues.add('no-invention');
+  }
+
+  const boundaryTable = markdownTableUnderHeading(
+    templates,
+    'No-invention and conditional boundary contracts'
+  );
+  const expectedBoundaryTable = [
+    ['Boundary', 'Required contract when material'],
+    ...IMPLEMENTATION_READINESS_BOUNDARY_ROWS
+  ];
+  if (!authoring.includes(IMPLEMENTATION_READINESS_CLAUSES.materialDefinition)
+    || !authoring.includes(IMPLEMENTATION_READINESS_CLAUSES.exactBoundaryChoices)
+    || IMPLEMENTATION_READINESS_BOUNDARY_ROWS.length !== 6
+    || boundaryTable.length !== expectedBoundaryTable.length
+    || JSON.stringify(boundaryTable) !== JSON.stringify(expectedBoundaryTable)) {
+    issues.add('boundary-contract');
+  }
+
+  const proof = markdownSection(templates, 'Verification Plan');
+  const proofPlanLines = proof.split('\n').map((line) => line.trim()).filter((line) => line.startsWith('- '));
+  const normalizedProofContract = normalizeMarkdownWhitespace(markdownBetweenHeadings(
+    templates,
+    'Verification Plan',
+    'Canonical inline Receipt'
+  ));
+  const normalizedProofClauses = [
+    IMPLEMENTATION_READINESS_CLAUSES.proofTrace,
+    IMPLEMENTATION_READINESS_CLAUSES.namedProbeOwnership,
+    IMPLEMENTATION_READINESS_CLAUSES.proofLevelSeparation,
+    IMPLEMENTATION_READINESS_CLAUSES.disposableTemplateControls
+  ].map(normalizeMarkdownWhitespace);
+  const reviewNegativeControls = normalizeMarkdownWhitespace(
+    markdownSection(review, 'B2 — fresh-context red team')
+  );
+  if (JSON.stringify(proofPlanLines) !== JSON.stringify(IMPLEMENTATION_READINESS_CLAUSES.proofPlanLines)
+    || normalizedProofClauses.some((clause) => !normalizedProofContract.includes(clause))
+    || !reviewNegativeControls.includes(normalizeMarkdownWhitespace(
+      IMPLEMENTATION_READINESS_CLAUSES.disposableReviewControls
+    ))) {
+    issues.add('proof-chain');
+  }
+
+  const failureGuidance = markdownSection(templates, 'Twelve edge-case dimensions');
+  if (!failureGuidance.includes(IMPLEMENTATION_READINESS_CLAUSES.failureSemantics)) {
+    issues.add('failure-semantics');
+  }
+
+  const evidenceRules = markdownSection(review, 'B1 — evidence rule');
+  if (!evidenceRules.includes(IMPLEMENTATION_READINESS_CLAUSES.privacyIdentifiers)) {
+    issues.add('privacy-identifiers');
+  }
+
+  const closure = markdownSection(review, 'Accepted-repair closure');
+  const normalizedClosure = normalizeMarkdownWhitespace(closure);
+  const closureHeader = markdownTableUnderHeading(review, 'Accepted-repair closure')[0] || [];
+  if (JSON.stringify(closureHeader) !== JSON.stringify([
+    'ID', 'Decision', 'Original counterexample', 'Repaired at', 'Proved at', 'Replay', 'Closure'
+  ])
+    || !normalizedClosure.includes(normalizeMarkdownWhitespace(IMPLEMENTATION_READINESS_CLAUSES.freshReplay))
+    || !closure.includes(IMPLEMENTATION_READINESS_CLAUSES.distinctRepairProof)
+    || !closure.includes(IMPLEMENTATION_READINESS_CLAUSES.closureTransition)
+    || !closure.includes(IMPLEMENTATION_READINESS_CLAUSES.unknownBlocks)
+    || !closure.includes(IMPLEMENTATION_READINESS_CLAUSES.scopeReturnsToC1)) {
+    issues.add('repair-closure');
+  }
+
+  return [...issues].sort();
 }
 
-function installedAuthoringProjectionIssues(files) {
+function authoringProjectionIssues(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');
-  }
-  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 (/\balways search\b|\bcomprehensive research\b|\bcapture all findings\b/i.test(files.discovery)) {
-    issues.push('default-research');
-  }
-  if (/(?:limit|maximum|at most|top|≤|<=)\s*(?:to\s*)?3\b/i.test(files.review)) {
-    issues.push('review-cap');
-  }
-  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}`);
+  issues.push(...implementationReadinessIssues(files.templates, files.review));
+  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');
+  }
+  if (!files.templates.includes('The primary layout is always flat:')
+    || !files.templates.includes('task-NN-<slug>.md')) {
+    issues.push('flat-layout-template');
+  }
+  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 (!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 (!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}`);
   }
-  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');
+  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}`);
   }
-  return issues;
+  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 [...new Set(issues)].sort();
 }
 
-function assertInstalledAuthoringProjection(root) {
-  const read = (relative) => fs.readFileSync(path.join(root, 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')
+function canonicalInstalledSpecsRoot(projectRoot, installedRoot) {
+  assert.equal(path.isAbsolute(projectRoot), true, 'project root must be absolute');
+  assert.equal(path.isAbsolute(installedRoot), true, 'installed Specs root must be absolute');
+  const canonicalProject = fs.realpathSync(projectRoot);
+  const canonicalInstalled = fs.realpathSync(installedRoot);
+  const relative = path.relative(canonicalProject, canonicalInstalled);
+  assert.ok(relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative), 'installed Specs root must stay inside project');
+  assert.equal(
+    canonicalInstalled,
+    fs.realpathSync(path.join(canonicalProject, '.agents/skills/specs')),
+    'checker must read the native installed Codex Specs root'
+  );
+  return canonicalInstalled;
+}
+
+function readInstalledAuthoringProjection(projectRoot, installedRoot) {
+  const canonicalRoot = canonicalInstalledSpecsRoot(projectRoot, installedRoot);
+  const read = (relative) => fs.readFileSync(path.join(canonicalRoot, relative), 'utf8');
+  return {
+    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(projectRoot, 'AGENTS.md'), 'utf8'),
+      fs.readFileSync(path.join(projectRoot, '.codex/rules/state-sync.md'), 'utf8')
+    ].join('\n')
   };
-  assert.deepEqual(installedAuthoringProjectionIssues(files), []);
+}
+
+function installedAuthoringProjectionIssues(projectRoot, installedRoot) {
+  return authoringProjectionIssues(readInstalledAuthoringProjection(projectRoot, installedRoot));
+}
+
+function assertInstalledMutationTarget(projectRoot, installedRoot, relative) {
+  const canonicalProject = fs.realpathSync(projectRoot);
+  const canonicalInstalled = canonicalInstalledSpecsRoot(projectRoot, installedRoot);
+  const targetPath = path.join(canonicalInstalled, relative);
+  const targetLstat = fs.lstatSync(targetPath);
+  assert.equal(targetLstat.isSymbolicLink(), false, 'installed mutation target must not be a symlink');
+  assert.equal(targetLstat.isFile(), true, 'installed mutation target must be a regular file');
+  const canonicalTarget = fs.realpathSync(targetPath);
+  const installedRelative = path.relative(canonicalInstalled, canonicalTarget);
+  const projectRelative = path.relative(canonicalProject, canonicalTarget);
+  assert.ok(
+    installedRelative && installedRelative !== '..'
+      && !installedRelative.startsWith(`..${path.sep}`)
+      && !path.isAbsolute(installedRelative),
+    'installed mutation target must stay inside .agents/skills/specs'
+  );
+  assert.ok(
+    projectRelative && projectRelative !== '..'
+      && !projectRelative.startsWith(`..${path.sep}`)
+      && !path.isAbsolute(projectRelative),
+    'installed mutation target must stay inside the disposable project'
+  );
+  const canonicalSource = fs.realpathSync(path.join(SPECS_SOURCE_ROOT, relative));
+  assert.notEqual(
+    canonicalTarget,
+    canonicalSource,
+    'installed mutation target must not resolve to canonical source'
+  );
+  const targetStat = fs.statSync(canonicalTarget);
+  const sourceStat = fs.statSync(canonicalSource);
+  assert.notDeepEqual(
+    [targetStat.dev, targetStat.ino],
+    [sourceStat.dev, sourceStat.ino],
+    'installed mutation target must not share an inode with canonical source'
+  );
+  return canonicalTarget;
+}
+
+function assertCanonicalSpecsSourceBytesUnchanged(sourceBytes) {
+  for (const [relative, expected] of sourceBytes) {
+    assert.deepEqual(
+      fs.readFileSync(path.join(SPECS_SOURCE_ROOT, relative)),
+      expected,
+      `canonical Specs source bytes changed during installed mutation: ${relative}`
+    );
+  }
+}
+
+function assertInstalledAuthoringProjection(root, installedRoot) {
+  canonicalInstalledSpecsRoot(root, installedRoot);
+  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 files = readInstalledAuthoringProjection(root, installedRoot);
+  const sourceBytes = new Map(V3_SPECS_BUNDLE.map((relative) => [
+    relative,
+    fs.readFileSync(path.join(SPECS_SOURCE_ROOT, relative))
+  ]));
+  assert.deepEqual(installedAuthoringProjectionIssues(root, installedRoot), []);
+  assertCanonicalSpecsSourceBytesUnchanged(sourceBytes);
+
+  if (process.platform !== 'win32') {
+    const relative = 'references/templates.md';
+    const installedPath = path.join(installedRoot, relative);
+    const backupPath = `${installedPath}.cafekit-backup`;
+    const sourcePath = path.join(SPECS_SOURCE_ROOT, relative);
+    fs.renameSync(installedPath, backupPath);
+    try {
+      fs.linkSync(sourcePath, installedPath);
+      assert.throws(
+        () => assertInstalledMutationTarget(root, installedRoot, relative),
+        /must not share an inode with canonical source/
+      );
+      assertCanonicalSpecsSourceBytesUnchanged(sourceBytes);
+    } finally {
+      try { fs.unlinkSync(installedPath); } catch { /* best-effort disposable cleanup */ }
+      fs.renameSync(backupPath, installedPath);
+    }
+  }
+
+  const boundaryMutation = (name, boundary, replacements) => {
+    const row = IMPLEMENTATION_READINESS_BOUNDARY_ROWS.find(([label]) => label === boundary);
+    assert.ok(row, `${name} references unknown boundary ${boundary}`);
+    let weakened = row[1];
+    for (const [from, to] of replacements) {
+      const next = weakened.replace(from, to);
+      assert.notEqual(next, weakened, `${name} weakening anchor must exist in ${boundary}`);
+      weakened = next;
+    }
+    return {
+      name,
+      issue: 'boundary-contract',
+      relative: 'references/templates.md',
+      from: `| ${row[0]} | ${row[1]} |`,
+      to: `| ${row[0]} | ${weakened} |`
+    };
+  };
+
+  const readinessMutations = [
+    {
+      name: 'no-invention-blocking',
+      issue: 'no-invention',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.noInvention,
+      to: 'Before implementation handoff, note ambiguous choices without blocking handoff.'
+    },
+    {
+      name: 'material-boundary-definition',
+      issue: 'boundary-contract',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.materialDefinition,
+      to: 'A boundary is material when it seems relevant to the task.'
+    },
+    {
+      name: 'exact-boundary-choices',
+      issue: 'boundary-contract',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.exactBoundaryChoices,
+      to: 'For every required row, describe the listed choices generally.'
+    },
+    boundaryMutation('api-success-and-error-semantics', 'API/CLI', [
+      ['success output; ', ''],
+      ['error/status/exit; ', '']
+    ]),
+    boundaryMutation('schema-shape-and-unknown-fields', 'Schema', [
+      ['exact keys/nesting/types; ', ''],
+      ['unknown-field behavior; ', '']
+    ]),
+    boundaryMutation('state-lock-lifecycle', 'State/concurrency', [
+      ['writer/lock acquire/contention/release', 'writer/lock']
+    ]),
+    boundaryMutation('filesystem-segment-grammar', 'Filesystem/security', [
+      ['trusted/untrusted segment grammar; ', '']
+    ]),
+    boundaryMutation('filesystem-stale-lock-reclaim', 'Filesystem/security', [
+      ['lock/stale reclaim; ', '']
+    ]),
+    boundaryMutation('retention-clock-and-endpoints', 'Time/retention', [
+      ['clock source; ', ''],
+      ['unit/precision/timezone; ', ''],
+      ['endpoints and inclusion/comparator; ', '']
+    ]),
+    boundaryMutation('proof-level-partition', 'Integration/proof', [
+      ['proof level (`source`/`installed`/`live`)', 'proof level']
+    ]),
+    {
+      name: 'concrete-named-probe',
+      issue: 'proof-chain',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.proofPlanLines[1],
+      to: '- Named probe: <suite label>'
+    },
+    {
+      name: 'aggregate-suite-probe-owner',
+      issue: 'proof-chain',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.namedProbeOwnership,
+      to: 'Aggregate suites may cite only the suite label.'
+    },
+    {
+      name: 'reachability-levels',
+      issue: 'proof-chain',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.proofPlanLines[2],
+      to: '- Reachability: <entrypoint or consumer>'
+    },
+    {
+      name: 'proof-level-separation',
+      issue: 'proof-chain',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.proofLevelSeparation,
+      to: 'Proof may be promoted between source, installed, and live levels.'
+    },
+    {
+      name: 'disposable-template-negative-controls',
+      issue: 'proof-chain',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.disposableTemplateControls,
+      to: 'Run mutation or destructive negative controls against the available project copy.'
+    },
+    {
+      name: 'disposable-review-negative-controls',
+      issue: 'proof-chain',
+      relative: 'references/review.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.disposableReviewControls,
+      to: 'Run mutation or destructive negative controls against the available project copy.'
+    },
+    {
+      name: 'artifact-path-and-digest-or-ephemeral',
+      issue: 'proof-chain',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.proofPlanLines[5],
+      to: '- Artifacts: <required artifact path, or none>'
+    },
+    {
+      name: 'proof-counterexample',
+      issue: 'proof-chain',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.proofPlanLines[4],
+      to: '- Counterexample: <example>'
+    },
+    {
+      name: 'repair-and-proof-columns',
+      issue: 'repair-closure',
+      relative: 'references/review.md',
+      from: '| ID | Decision | Original counterexample | Repaired at | Proved at | Replay | Closure |',
+      to: '| ID | Decision | Original counterexample | Repaired at | Evidence | Replay | Closure |'
+    },
+    {
+      name: 'fresh-original-counterexample-replay',
+      issue: 'repair-closure',
+      relative: 'references/review.md',
+      from: 'After applying an accepted C2 finding, a fresh-context closure pass records and\nfreshly replays its original counterexample after the repair under this exact review-log header:',
+      to: 'After applying an accepted C2 finding, record the repair under this review-log header:'
+    },
+    {
+      name: 'distinct-repair-and-proof-evidence',
+      issue: 'repair-closure',
+      relative: 'references/review.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.distinctRepairProof,
+      to: '`Repaired at` and `Proved at` may cite the same repair edit.'
+    },
+    {
+      name: 'unknown-blocks-handoff',
+      issue: 'repair-closure',
+      relative: 'references/review.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.unknownBlocks,
+      to: '`PASS` closes it; `FAIL` and `UNKNOWN` may continue to implementation handoff.'
+    },
+    {
+      name: 'crash-versus-catchable-failure',
+      issue: 'failure-semantics',
+      relative: 'references/templates.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.failureSemantics,
+      to: 'Crash and catchable failure both mean an error occurred.'
+    },
+    {
+      name: 'privacy-identifier-surface',
+      issue: 'privacy-identifiers',
+      relative: 'references/review.md',
+      from: IMPLEMENTATION_READINESS_CLAUSES.privacyIdentifiers,
+      to: 'Any privacy/security claim names the sensitive data at risk.'
+    }
+  ];
+
+  for (const { name, issue, relative, from, to } of readinessMutations) {
+    const target = assertInstalledMutationTarget(root, installedRoot, relative);
+    const installedBytes = fs.readFileSync(target, 'utf8');
+    const anchorIndex = installedBytes.indexOf(from);
+    assert.ok(anchorIndex >= 0, `${name} mutation anchor must exist in installed bytes`);
+    assert.equal(
+      installedBytes.indexOf(from, anchorIndex + from.length),
+      -1,
+      `${name} mutation anchor must be unique in installed bytes`
+    );
+    const weakened = `${installedBytes.slice(0, anchorIndex)}${to}${installedBytes.slice(anchorIndex + from.length)}`;
+    try {
+      fs.writeFileSync(assertInstalledMutationTarget(root, installedRoot, relative), weakened);
+      assertCanonicalSpecsSourceBytesUnchanged(sourceBytes);
+      assert.deepEqual(installedAuthoringProjectionIssues(root, installedRoot), [issue], name);
+    } finally {
+      fs.writeFileSync(assertInstalledMutationTarget(root, installedRoot, relative), installedBytes);
+    }
+    assert.deepEqual(installedAuthoringProjectionIssues(root, installedRoot), [], `${name} restore`);
+    assertCanonicalSpecsSourceBytesUnchanged(sourceBytes);
+  }
+
   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]) };
-    assert.notDeepEqual(installedAuthoringProjectionIssues(changed), []);
+    assert.notDeepEqual(authoringProjectionIssues(changed), []);
   }
 }
 
@@ -271,7 +736,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 +752,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 +1110,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 +1118,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 +1130,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}`);
     }
@@ -682,7 +1143,20 @@ test('Codex install is project-local, native, and upgrade-safe', () => {
       path.join(root, '.codex/scripts/spec-ground.cjs'),
       installedDesign
     );
-    assertInstalledAuthoringProjection(root);
+    const installedSpecsRoot = path.join(root, '.agents/skills/specs');
+    assert.throws(
+      () => installedAuthoringProjectionIssues(root, '.agents/skills/specs'),
+      /must be absolute/
+    );
+    assert.throws(
+      () => installedAuthoringProjectionIssues(root, SPECS_SOURCE_ROOT),
+      /must stay inside project/
+    );
+    assert.throws(
+      () => installedAuthoringProjectionIssues(root, path.dirname(root)),
+      /must stay inside project/
+    );
+    assertInstalledAuthoringProjection(root, installedSpecsRoot);
 
     const installedTask = fs.readFileSync(
       path.join(root, '.agents/skills/specs/templates/task.md'), 'utf8'
@@ -777,7 +1251,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 +1276,23 @@ 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.deepEqual(installedAuthoringProjectionIssues(root, installedSpecsRoot), []);
     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'));
@@ -808,7 +1301,13 @@ 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.deepEqual(installedAuthoringProjectionIssues(root, installedSpecsRoot), []);
     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']);