@haposoft/cafekit 0.16.6 → 0.18.0

package/bin/__tests__/develop-contract.test.js

@@ -17,7 +17,6 @@ const RECEIPTS = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-receip
 const FINAL_STATE = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-final-state.cjs'));
 const VALIDATOR = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/validate-spec-output.cjs'));
 const GROUNDER = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-ground.cjs'));
-const SEMANTIC_AUTHORITY = require(path.join(PACKAGE_ROOT, 'src/claude/hooks/semantic-review-authority.cjs'));
 const READINESS = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-readiness.cjs'));
 const AUTHORING_VALIDATOR = path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-authoring-validation.cjs');
 const { copyClaudeTestRuntime } = require('./test-runtime-dependency-closure.cjs');
@@ -80,9 +79,6 @@ function installClaudeRuntimeClosure(fixtureRoot, entry = 'hooks/spec-gate.cjs')
   const hooksRoot = path.join(PACKAGE_ROOT, 'src', 'claude', 'hooks');
   for (const hook of [
     'spec-gate.cjs',
-    'completion-authority-check.cjs',
-    'completion-authority-state.cjs',
-    'semantic-review-authority.cjs',
   ]) {
     const target = path.join(destinationRoot, 'hooks', hook);
     fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -759,10 +755,7 @@ test('CLI exposes a derived lane without making it primary Develop authority', (
   const regions = markdownLegacyRegions(develop);
   assert.doesNotMatch(develop, /DO NOT write implementation code until an approved spec exists/i);
   assert.doesNotMatch(regions.primary, /planning_depth|assurance_level|execution_tier|\blane\b/i);
-  assert.match(regions.legacy, /planning_depth/);
-  assert.match(regions.legacy, /assurance_level/);
-  assert.match(regions.legacy, /execution_tier/);
-  assert.match(regions.legacy, /derived lane/i);
+  assert.doesNotMatch(develop, /## Legacy workflow compatibility|Also supports existing legacy Specs packets/);
   assert.match(regions.primary, /specs\/<feature>\/plan\.md[\s\S]*task-NN-\*\.md/i);
   assert.match(regions.primary, /one unblocked task at a time/i);
   assert.match(regions.primary, /Verification Plan/);
@@ -789,66 +782,63 @@ test('Specs primary output is a flat process-first packet with isolated legacy c
   const specs = read(SPECS);
   const regions = markdownLegacyRegions(specs);
   const legacyHeadings = regions.headings.filter(({ text }) => /legacy/i.test(text));
-  assert.equal(legacyHeadings.length, 1);
+  assert.equal(legacyHeadings.length, 0);
   assert.match(regions.primary, /specs\/<feature>\/[\s\S]*plan\.md[\s\S]*task-01-<slug>\.md[\s\S]*task-02-<slug>\.md/i);
   assert.match(regions.primary, /Task files are flat beside `plan\.md`/i);
   assert.match(regions.primary, /one task at a time/i);
   assert.match(regions.primary, /inline `## Receipt`/i);
-  assert.match(regions.primary, /C1 — Scope[\s\S]*C2 — Findings[\s\S]*C3 — Done/i);
-  assert.match(regions.legacy, /spec\.json/i);
-  assert.match(regions.legacy, /never requires the legacy kernel/i);
+  assert.match(regions.primary, /GATE-SCOPE[\s\S]*GATE-REVIEW[\s\S]*GATE-DONE/i);
+  assert.doesNotMatch(specs, /installed legacy adapters?/i);
   assertVocabularyIsLegacyOnly(SPECS, regions);
 });
 
-test('core execution agents default to process-first state and isolate legacy packets', () => {
+test('core execution agents default to process-first state and carry no legacy adapter', () => {
   for (const filePath of PROCESS_FIRST_AGENTS) {
     const content = read(filePath);
     const name = path.basename(filePath);
     assert.match(content, /plan\.md/i, `${name} must read the process-first plan`);
     assert.match(content, /task-NN-\*\.md|task-NN-<slug>\.md/i, `${name} must understand flat tasks`);
-    assert.match(content, /legacy/i, `${name} must isolate legacy compatibility`);
+    assert.doesNotMatch(content, /legacy|spec\.json|scope_lock/i, `${name} must not teach a legacy adapter`);
   }
 
   const implementer = read(PROCESS_FIRST_AGENTS[0]);
   assert.match(implementer, /Under every dispatch mode[\s\S]{0,160}do NOT edit[\s\S]{0,80}`plan\.md`[\s\S]{0,80}`Status:`[\s\S]{0,80}`## Receipt`/i);
   assert.match(implementer, /controller/i);
-  assert.match(implementer, /process-first work[\s\S]{0,100}Ownership[\s\S]{0,100}`Related Files` only for a valid legacy adapter/i);
+  assert.match(implementer, /process-first work[\s\S]{0,100}Ownership\s+boundary\./i);
 
   const auditor = read(PROCESS_FIRST_AGENTS[2]);
-  assert.match(auditor, /accepted C1\/C2 decisions/i);
-  assert.match(auditor, /Only for a valid legacy adapter[\s\S]*`Related Files`[\s\S]*`## Evidence`/i);
-  assert.match(auditor, /Never require those legacy artifacts from a[\s\S]*process-first packet/i);
-  assert.match(auditor, /attestation belongs only to the valid legacy/i);
+  assert.match(auditor, /accepted GATE-SCOPE\/GATE-REVIEW decisions/i);
+  assert.doesNotMatch(auditor, /CAFEKIT_SEMANTIC_REVIEW_ATTESTATION/);
 
   const docsKeeper = read(PROCESS_FIRST_AGENTS[3]);
   assert.match(docsKeeper, /never[\s\S]{0,80}invent or write Status, Receipt, approval, or execution proof/i);
 
   const deployer = read(PROCESS_FIRST_AGENTS[4]);
   assert.match(deployer, /current final inline Receipt/i);
-  assert.match(deployer, /C3\/release authorization/i);
+  assert.match(deployer, /GATE-DONE\/release authorization/i);
   assert.match(deployer, /does not write process-first Status\/Receipt/i);
 });
 
 test('R7 Develop and Sync surfaces teach process-v3 and isolate hierarchical Legacy sections', () => {
   const surfaces = [
-    ['develop', DEVELOP],
-    ['parallel waves', PARALLEL_WAVES],
-    ['sync', SYNC_SKILL],
-    ['sync protocols', SYNC_PROTOCOLS],
+    ['develop', DEVELOP, 0],
+    ['parallel waves', PARALLEL_WAVES, 0],
+    ['sync', SYNC_SKILL, 0],
+    ['sync protocols', SYNC_PROTOCOLS, 0],
   ];
   const regionsByName = new Map();
-  let legacyCorpus = '';
 
-  for (const [name, filePath] of surfaces) {
+  for (const [name, filePath, expectedLegacy] of surfaces) {
     const regions = markdownLegacyRegions(read(filePath));
     const legacyHeadings = regions.headings.filter(({ text }) => /legacy/i.test(text));
-    assert.equal(legacyHeadings.length, 1, `${name} must have exactly one Legacy heading`);
+    assert.equal(legacyHeadings.length, expectedLegacy, `${name} must have exactly ${expectedLegacy} Legacy heading(s)`);
     assert.match(regions.primary, /inline (?:`## )?Receipts?/i, `${name} must teach inline Receipts`);
-    assert.match(regions.legacy, /spec\.json/i, `${name} must retain the spec.json adapter`);
-    assert.match(regions.legacy, /task_registry/i, `${name} must retain task_registry compatibility`);
+    if (expectedLegacy === 1) {
+      assert.match(regions.legacy, /spec\.json/i, `${name} must retain the spec.json adapter`);
+      assert.match(regions.legacy, /task_registry/i, `${name} must retain task_registry compatibility`);
+    }
     assertVocabularyIsLegacyOnly(filePath, regions);
     regionsByName.set(name, regions);
-    legacyCorpus += `\n${regions.legacy}`;
   }
 
   const develop = regionsByName.get('develop').primary;
@@ -874,7 +864,7 @@ test('R7 Develop and Sync surfaces teach process-v3 and isolate hierarchical Leg
   assert.match(protocols, /`plan\.md` and flat `task-\*\.md` files/i);
   assert.match(protocols, /acceptance IDs/i);
   assert.match(protocols, /current inline Receipt/i);
-  assert.match(legacyCorpus, /sync-finalize/i);
+  assert.match(regionsByName.get('sync').primary, /sync-finalize/i);
 });
 
 test('Develop process-first source contract preserves selection, recovery, final-Head, parallel, and Flash boundaries', () => {
@@ -1293,7 +1283,7 @@ test('auto authoring reaches readiness only after promotion, validation, groundi
     assert.ok(executableBlocks.every((block) => !/cf:?develop/i.test(block)), 'Specs must never execute Develop');
     assert.match(specs, /An implementation workflow owns execution/i);
     assert.match(specs, /selects one unblocked task[\s\S]*runs\s+the task's verification[\s\S]*inline `## Receipt`/i);
-    assert.match(specs, /The user decides\s+at C3 whether the feature is done/i);
+    assert.match(specs, /The user decides\s+at GATE-DONE whether the feature is done/i);
   } finally {
     fs.rmSync(fixture.root, { recursive: true, force: true });
   }
@@ -1369,41 +1359,20 @@ test('atomic readiness preserves exact bytes on review, grounding, decision, and
     blocked.workflow_policy = POLICY.canonicalWorkflowPolicySnapshot({ planning_depth: 'Compact', assurance_level: 'Strict' });
     fs.writeFileSync(fixture.specPath, `${JSON.stringify(blocked, null, 2)}\n`);
     const strictBytes = fs.readFileSync(fixture.specPath);
-    assert.throws(() => READINESS.finalizeReadiness({ specDir: fixture.specDir, projectRoot: fixture.root, reviewResult: ordinaryReview() }), /Strict readiness/);
+    assert.throws(() => READINESS.finalizeReadiness({ specDir: fixture.specDir, projectRoot: fixture.root, reviewResult: ordinaryReview() }), /Strict assurance is no longer supported/);
     assert.equal(fs.readFileSync(fixture.specPath).equals(strictBytes), true);
   } finally { fs.rmSync(fixture.root, { recursive: true, force: true }); }
 });
 
-test('Strict atomic readiness succeeds only after current allowlisted host observation', () => {
+test('Strict readiness is refused as no longer supported', () => {
   const fixture = createOrdinaryAuthoringFixture();
   try {
     const spec = JSON.parse(fs.readFileSync(fixture.specPath, 'utf8'));
     spec.workflow_policy = POLICY.canonicalWorkflowPolicySnapshot({ planning_depth: 'Compact', assurance_level: 'Strict' });
     fs.writeFileSync(fixture.specPath, `${JSON.stringify(spec, null, 2)}\n`);
     const before = fs.readFileSync(fixture.specPath);
-    assert.throws(() => READINESS.finalizeReadiness({ specDir: fixture.specDir, projectRoot: fixture.root, reviewResult: ordinaryReview() }), /Strict readiness/);
+    assert.throws(() => READINESS.finalizeReadiness({ specDir: fixture.specDir, projectRoot: fixture.root, reviewResult: ordinaryReview() }), /Strict assurance is no longer supported/);
     assert.equal(fs.readFileSync(fixture.specPath).equals(before), true);
-
-    const digest = VALIDATOR.computeSemanticDigest21(fixture.specDir, spec);
-    assert.equal(digest.errors.length, 0, digest.errors.join('\n'));
-    const authorityHome = path.join(fixture.root, 'authority-home');
-    const claim = `CAFEKIT_SEMANTIC_REVIEW_ATTESTATION ${JSON.stringify({ feature_name: 'ordinary', spec_file: 'specs/ordinary/spec.json', semantic_digest: digest.digest, verdict: 'PASS' })}`;
-    const observed = spawnSync(process.execPath, [path.join(PACKAGE_ROOT, 'src/claude/hooks/semantic-review-authority.cjs')], {
-      cwd: fixture.root,
-      env: { ...process.env, HOME: authorityHome, USERPROFILE: authorityHome, PROJECT_ROOT: fixture.root },
-      input: JSON.stringify({ hook_event_name: 'SubagentStop', session_id: 'host-session', agent_id: 'reviewer-1', agent_type: 'code_auditor', last_assistant_message: claim, cwd: fixture.root }),
-      encoding: 'utf8',
-    });
-    assert.equal(observed.status, 0, observed.stderr);
-    const reviewFile = path.join(fixture.root, 'review.json');
-    fs.writeFileSync(reviewFile, `${JSON.stringify(ordinaryReview())}\n`);
-    const finalized = spawnSync(process.execPath, [path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-readiness.cjs'), fixture.specDir, '--review-result', reviewFile], {
-      cwd: fixture.root,
-      env: { ...process.env, HOME: authorityHome, USERPROFILE: authorityHome, PROJECT_ROOT: fixture.root },
-      encoding: 'utf8',
-    });
-    assert.equal(finalized.status, 0, `${finalized.stdout}\n${finalized.stderr}`);
-    assert.equal(JSON.parse(fs.readFileSync(fixture.specPath, 'utf8')).ready_for_implementation, true);
   } finally { fs.rmSync(fixture.root, { recursive: true, force: true }); }
 });
 
@@ -1423,7 +1392,7 @@ test('done is a final-state request bound to current semantic model and digest',
     const dependencies = () => ({
       validator: VALIDATOR,
       grounder: GROUNDER,
-      semanticAuthority: SEMANTIC_AUTHORITY,
+      semanticAuthority: {},
     });
     const current = FINAL_STATE.validateCanonicalFinalState({
       policy: POLICY, projectRoot: fixture.root, candidate, dependencies,

package/bin/__tests__/docs-sync-on-demand.test.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// docs-sync printed "Docs sync needed" at every Claude SessionStart, and nothing ever
+// cleared it. It now runs only when the docs skill asks for it. The skill text is shared
+// with Codex, whose copy crashes silently on an empty stdin, so the command feeds `{}`.
+// Each case names the failure it prevents.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync, execSync } = 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 DOCS_SKILL = path.join(PACKAGE_ROOT, 'src/claude/skills/docs');
+const ON_DEMAND = "echo '{}' | node .claude/hooks/docs-sync.cjs";
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-docs-sync-'));
+  try {
+    const init = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+    assert.equal(init.status, 0, init.stderr);
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, platforms) {
+  const result = spawnSync(process.execPath, [INSTALLER, '--platform', platforms.join(','), '--yes'],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+}
+
+function commands(settings, event) {
+  return (settings.hooks[event] || []).flatMap((group) => (group.hooks || []).map((hook) => hook.command));
+}
+
+/** A git project with code, docs and a `.sync_hash` that no longer matches the source. */
+function makeStale(root) {
+  fs.writeFileSync(path.join(root, 'package.json'), '{"name":"fixture"}\n');
+  fs.mkdirSync(path.join(root, 'docs'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'docs', 'README.md'), '# Docs\n');
+  fs.writeFileSync(path.join(root, 'docs', '.sync_hash'), '0000000000000000000000000000000000000000\n');
+  execSync('git -c user.email=t@t -c user.name=t add -A && git -c user.email=t@t -c user.name=t commit -qm fixture', { cwd: root });
+}
+
+test('fresh claude install runs no docs-sync at SessionStart', () => {
+  inTempProject((root) => {
+    install(root, ['claude']);
+    const settings = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'settings.json'), 'utf8'));
+    assert.equal(commands(settings, 'SessionStart').some((c) => c.includes('docs-sync.cjs')), false);
+    assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', 'docs-sync.cjs')), true, 'the hook stays installed for on-demand use');
+  });
+});
+
+test('upgrade drops the SessionStart docs-sync entry', () => {
+  inTempProject((root) => {
+    install(root, ['claude']);
+    const settingsPath = path.join(root, '.claude', 'settings.json');
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    const kept = commands(settings, 'SessionStart');
+    settings.hooks.SessionStart[0].hooks.push({ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs"' });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    install(root, ['claude']);
+    const after = commands(JSON.parse(fs.readFileSync(settingsPath, 'utf8')), 'SessionStart');
+    assert.equal(after.some((c) => c.includes('docs-sync.cjs')), false);
+    for (const command of kept) assert.ok(after.includes(command), `kept: ${command}`);
+  });
+});
+
+test('the docs skill runs docs-sync on demand', () => {
+  for (const rel of ['SKILL.md', 'references/update-workflow.md']) {
+    assert.ok(fs.readFileSync(path.join(DOCS_SKILL, rel), 'utf8').includes(ON_DEMAND), `${rel} names the on-demand command`);
+  }
+  const files = fs.readdirSync(DOCS_SKILL, { recursive: true }).filter((f) => f.endsWith('.md'));
+  for (const rel of files) {
+    assert.doesNotMatch(fs.readFileSync(path.join(DOCS_SKILL, rel), 'utf8'), /SessionStart docs-sync/, rel);
+  }
+});
+
+for (const [runtime, folder] of [['claude', '.claude'], ['codex', '.codex']]) {
+  test(`the ${runtime === 'claude' ? 'Claude' : 'Codex'} copy prints its signal on demand`, () => {
+    inTempProject((root) => {
+      install(root, [runtime]);
+      makeStale(root);
+      const out = execSync(`echo '{}' | node ${folder}/hooks/docs-sync.cjs`, { cwd: root, encoding: 'utf8' });
+      assert.match(out, /Docs sync needed/);
+    });
+  });
+}

package/bin/__tests__/grok-envelope.test.js

@@ -134,36 +134,6 @@ test('a broad glob is denied with its full reason in JSON', () => {
   });
 });
 
-test('a nested task write is denied under the grok write tool', () => {
-  withInstall((root) => {
-    const target = path.join(root, 'specs', 'demo', 'tasks', 'task-R0-01-x.md');
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    // grok creates files with `write`; `search_replace` edits an existing one. The guard
-    // fires on Write only, so the alias has to keep those two apart.
-    const r = runHook(root, 'task-scaffold-guard.cjs', {
-      hookEventName: 'pre_tool_use',
-      cwd: root,
-      toolName: 'write',
-      toolInput: { path: target, content: '# x' },
-    });
-    const { decision, reason } = decisionOf(r.stdout);
-    assert.equal(decision, 'deny');
-    assert.match(reason, /TASK SCAFFOLD REQUIRED/);
-    assert.match(reason, /spec-scaffold\.cjs/, 'the command the model must run has to reach it');
-    assert.equal(r.code, 2);
-
-    // The escape route the message names must stay open: an edit is not a create.
-    const edit = runHook(root, 'task-scaffold-guard.cjs', {
-      hookEventName: 'pre_tool_use',
-      cwd: root,
-      toolName: 'search_replace',
-      toolInput: { path: target, old_string: 'a', new_string: 'b' },
-    });
-    assert.equal(decisionOf(edit.stdout).decision, null, 'search_replace must not be treated as a create');
-    assert.equal(edit.code, 0);
-  });
-});
-
 /** A packet the Stop gate will block: one done task with no receipt. */
 function unprovenPacket(root) {
   const feature = path.join(root, 'specs', 'demo');
@@ -206,32 +176,6 @@ test('the Stop gate still blocks an unproven done task', () => {
   }, { git: true });
 });
 
-test('the approval hook takes its approve path on a grok prompt', () => {
-  withInstall((root) => {
-    // Registered without an argv mode, this hook picks its mode from the event name, and
-    // approve() returns immediately unless that name is exactly 'UserPromptSubmit'. An
-    // approval phrase with no pending request is therefore the oracle: only the approve
-    // path can print a rejection line, so the line proves the event name was translated.
-    // Under an unreadable envelope the mode fell back to the stop path on every prompt.
-    const nonce = 'a'.repeat(24);
-    const r = runHook(root, 'completion-authority.cjs', {
-      hookEventName: 'user_prompt_submit',
-      sessionId: 'grok-1',
-      cwd: root,
-      prompt: `APPROVE CAFEKIT COMPLETION ${nonce}`,
-    });
-    assert.match(r.stdout, /CafeKit completion approval rejected/,
-      'the approve path must run and refuse an approval that matches no pending request');
-    assert.equal(decisionOf(r.stdout).decision, null, 'and it must not block the prompt');
-
-    // An ordinary prompt stays silent on both counts.
-    const plain = runHook(root, 'completion-authority.cjs', {
-      hookEventName: 'user_prompt_submit', sessionId: 'grok-1', cwd: root, prompt: 'please continue',
-    });
-    assert.equal(plain.stdout.trim(), '', 'an ordinary prompt produces nothing');
-  }, { git: true });
-});
-
 test('the secret guardrail sees a grok prompt', () => {
   withInstall((root) => {
     // grok's spelling for the prompt field is unverified, so the reader accepts the Claude

package/bin/__tests__/hook-payload.test.js

@@ -49,8 +49,8 @@ test('read_file path becomes file_path', () => {
     toolInput: { path: '/p/.env' },
   });
   assert.equal(out.tool_name, 'Read');
-  // privacy-block reads file_path and path, but task-scaffold-guard reads file_path first
-  // and inspect-block's path list is keyed the same way.
+  // privacy-block and inspect-block both read file_path first, so the normalized key
+  // must be file_path.
   assert.equal(out.tool_input.file_path, '/p/.env');
   assert.equal(out.tool_input.path, '/p/.env', 'the original key stays for hooks that read it');
 });
@@ -83,7 +83,6 @@ test('Stop and subagent fields map', () => {
     subagentId: 'agent-7',
     lastAssistantMessage: 'REVIEW: PASS',
   });
-  // semantic-review-authority refuses to record an attestation without agent_id.
   assert.equal(sub.hook_event_name, 'SubagentStop');
   assert.equal(sub.agent_type, 'code-auditor');
   assert.equal(sub.agent_id, 'agent-7');
@@ -102,9 +101,8 @@ test('every name reaching a Bash matcher becomes Bash', () => {
 });
 
 test('write and search_replace map to different Claude tools', () => {
-  // The scaffold guard only fires on Write. Grok creates files with `write` and edits
-  // them with `search_replace`; conflating them would either disable the guard or make it
-  // reject the Edit-fill step the guard's own message tells the model to run.
+  // Grok creates files with `write` and edits them with `search_replace`; they must stay
+  // distinct Claude tools so a hook matcher on Write or on Edit sees the event it names.
   assert.equal(normalizeToolName('write'), 'Write');
   assert.equal(normalizeToolName('delete_file'), 'Write');
   assert.equal(normalizeToolName('search_replace'), 'Edit');

package/bin/__tests__/legacy-authority-decoupled.test.js

@@ -0,0 +1,159 @@
+'use strict';
+
+// The Stop gates and the session hooks must not depend on the completion-authority hook files,
+// so those files can be deleted without blocking every Stop or crashing SessionStart. Each case
+// runs against a real install (bin/install.js), with and without the five legacy files.
+
+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 INSTALLER = path.join(__dirname, '..', 'install.js');
+const LEGACY_FILES = [
+  'completion-authority.cjs',
+  'completion-authority-check.cjs',
+  'completion-authority-state.cjs',
+  'semantic-review-authority.cjs',
+  'task-scaffold-guard.cjs',
+];
+const MIGRATION = /Legacy spec\.json closeout is no longer supported/;
+
+function inTempProject(run) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-decoupled-')));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'test@example.invalid'], ['config', 'user.name', 'Test'], ['commit', '--allow-empty', '-qm', 'base']]) {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    const installed = spawnSync(process.execPath, [INSTALLER, '--platform', 'claude,codex', '--yes'],
+      { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
+    assert.equal(installed.status, 0, `${installed.stdout}\n${installed.stderr}`);
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function removeLegacyFiles(root) {
+  for (const runtime of ['.claude', '.codex']) {
+    for (const file of LEGACY_FILES) {
+      const target = path.join(root, runtime, 'hooks', file);
+      fs.rmSync(target, { force: true });
+    }
+  }
+}
+
+function runHook(root, kind, script, event, extra = {}) {
+  const hook = path.join(root, kind === 'claude' ? '.claude' : '.codex', 'hooks', script);
+  const result = spawnSync(process.execPath, [hook], {
+    cwd: root,
+    input: JSON.stringify({ hook_event_name: event, session_id: 's', stop_hook_active: false, cwd: root, ...extra }),
+    env: { ...process.env, PATH: '/usr/bin:/bin', ...(kind === 'claude' ? { CLAUDE_PROJECT_DIR: root } : {}) },
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  return result.stdout.trim();
+}
+
+function stopGate(root, kind) {
+  return runHook(root, kind, 'spec-gate.cjs', 'Stop');
+}
+
+function isBlocked(stdout) {
+  return stdout !== '' && JSON.parse(stdout.split('\n').pop()).decision === 'block';
+}
+
+function blockReason(stdout) {
+  assert.equal(isBlocked(stdout), true, `expected a block, got: ${stdout}`);
+  return JSON.parse(stdout.split('\n').pop()).reason;
+}
+
+function provenance(root, taskFile) {
+  const result = spawnSync(process.execPath, [
+    path.join(root, '.claude', 'scripts', 'provenance.cjs'),
+    '--project-root', root, '--specs-root', 'specs', '--spec-file', taskFile,
+    '--feature-name', 'demo', '--session', 's', '--json',
+  ], { cwd: root, encoding: 'utf8' });
+  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  const parsed = JSON.parse(result.stdout);
+  return { base: parsed.Base, head: parsed.Head };
+}
+
+function writeProcessFirst(root, { receipt }) {
+  const featureDir = path.join(root, 'specs', 'demo');
+  fs.mkdirSync(featureDir, { recursive: true });
+  fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\n');
+  const taskFile = path.join(featureDir, 'task-01-demo.md');
+  const body = ['# Task 01: demo', '', 'Status: done', '', '## Dependencies', '', '- none', '', '## Verification Plan', '', '- Command: node --test', ''];
+  fs.writeFileSync(taskFile, body.join('\n'));
+  if (!receipt) return;
+  const { base, head } = provenance(root, taskFile);
+  fs.writeFileSync(taskFile, [...body, '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${base}`, `Head: ${head}`, '```text', '$ node --test', 'pass: 1', '```', ''].join('\n'));
+}
+
+// A 2.1 packet keeps its machine state in spec.json and its tasks in a nested tasks/ directory.
+function writeLegacy(root, { status, doneTask = false }) {
+  const featureDir = path.join(root, 'specs', 'legacy');
+  fs.mkdirSync(path.join(featureDir, 'tasks'), { recursive: true });
+  const task = 'tasks/task-R1-01-legacy.md';
+  const spec = { schema_version: '2.1', feature_name: 'legacy', status, current_phase: 'implementation', task_registry: {} };
+  if (doneTask) spec.task_registry[task] = { status: 'done', completed_at: '2026-08-13T00:00:00.000Z', dependencies: [] };
+  fs.writeFileSync(path.join(featureDir, 'spec.json'), JSON.stringify(spec));
+  if (doneTask) {
+    fs.writeFileSync(path.join(featureDir, task), ['# Task R1-01: legacy', '**Status:** done', '## Outcome', 'Legacy work.',
+      '## Verification Plan', '- **Command:** `node --test`', '- **Expected:** passes', ''].join('\n'));
+  }
+}
+
+function checkProcessFirst(kind) {
+  inTempProject((root) => {
+    writeProcessFirst(root, { receipt: true });
+    assert.equal(stopGate(root, kind), '', 'valid receipt passes with the legacy files');
+    writeProcessFirst(root, { receipt: false });
+    assert.match(blockReason(stopGate(root, kind)), /missing_receipt/, 'no receipt blocks with the legacy files');
+    removeLegacyFiles(root);
+    assert.match(blockReason(stopGate(root, kind)), /missing_receipt/, 'no receipt blocks without the legacy files');
+    writeProcessFirst(root, { receipt: true });
+    assert.equal(stopGate(root, kind), '', 'valid receipt passes without the legacy files');
+  });
+}
+
+function checkLegacyCloseout(kind) {
+  for (const status of ['done', 'completed']) {
+    inTempProject((root) => {
+      writeLegacy(root, { status });
+      removeLegacyFiles(root);
+      assert.match(blockReason(stopGate(root, kind)), MIGRATION, `${kind} ${status}`);
+    });
+  }
+}
+
+function checkLegacyMidExecution(kind) {
+  inTempProject((root) => {
+    writeLegacy(root, { status: 'in_progress', doneTask: true });
+    removeLegacyFiles(root);
+    const reason = blockReason(stopGate(root, kind));
+    assert.doesNotMatch(reason, MIGRATION);
+    assert.match(reason, /task-R1-01-legacy\.md/);
+  });
+}
+
+function checkSession(kind) {
+  inTempProject((root) => {
+    removeLegacyFiles(root);
+    runHook(root, kind, 'session.cjs', 'SessionStart', { source: 'startup' });
+  });
+}
+
+test('claude gate passes and blocks process-first with and without the legacy files', () => checkProcessFirst('claude'));
+test('codex gate passes and blocks process-first with and without the legacy files', () => checkProcessFirst('codex'));
+test('claude gate blocks legacy 2.1 closeout with the migration message', () => checkLegacyCloseout('claude'));
+test('codex gate blocks legacy 2.1 closeout with the migration message', () => checkLegacyCloseout('codex'));
+test('claude gate still receipt-checks a legacy 2.1 packet mid-execution', () => checkLegacyMidExecution('claude'));
+test('codex gate still receipt-checks a legacy 2.1 packet mid-execution', () => checkLegacyMidExecution('codex'));
+test('claude session starts without the legacy files', () => checkSession('claude'));
+test('codex session starts without the legacy files', () => checkSession('codex'));