@haposoft/cafekit 0.16.3 → 0.16.4

package/README.md

@@ -2,7 +2,7 @@
 
 > Native spec-driven workflow and runtime bundle for Claude Code and Codex CLI.
 
-[![Version](https://img.shields.io/badge/version-0.16.3-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.16.4-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Native-orange.svg)](https://claude.ai/code)
 [![Codex%20CLI](https://img.shields.io/badge/Codex%20CLI-Native-111111.svg)](https://developers.openai.com/codex)

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

@@ -782,6 +782,41 @@ test('Codex process-v3 Receipt command must match the exact Verification Plan co
   });
 });
 
+test('Codex recorded active feature turns the identity block into receipt validation', () => {
+  // Issue #79 end to end on this runtime. Two legacy packets both claiming closeout make
+  // the gate answer a missing-receipt violation with an identity complaint whose stated
+  // remedy nothing wrote. Naming the feature resolves it and the violation surfaces.
+  inHookFixture((root, hooks) => {
+    for (const name of ['alpha', 'beta']) {
+      const feature = path.join(root, 'specs', name);
+      fs.mkdirSync(path.join(feature, 'tasks'), { recursive: true });
+      fs.writeFileSync(path.join(feature, 'spec.json'), `${JSON.stringify({
+        feature_name: name,
+        status: 'done',
+        current_phase: 'closeout',
+        task_registry: { 'tasks/task-R0-01-x.md': { status: 'done', completed_at: '2026-01-01T00:00:00.000Z' } },
+      }, null, 2)}\n`);
+      fs.writeFileSync(path.join(feature, 'tasks', 'task-R0-01-x.md'), '# Task\n\nStatus: done\n');
+    }
+    const payload = { cwd: root, session_id: 'session-a', hook_event_name: 'Stop', stop_hook_active: false };
+
+    const blocked = runHook(path.join(hooks, 'spec-gate.cjs'), root, payload);
+    assert.equal(blocked.status, 0, blocked.stderr);
+    assert.match(JSON.parse(blocked.stdout).reason, /multiple active specs detected/);
+
+    const shared = path.join(root, 'specs', '_shared');
+    fs.mkdirSync(shared, { recursive: true });
+    fs.writeFileSync(path.join(shared, 'active-feature.json'), '{"featureName": "beta"}\n');
+
+    const resolved = runHook(path.join(hooks, 'spec-gate.cjs'), root, payload);
+    assert.equal(resolved.status, 0, resolved.stderr);
+    const reason = JSON.parse(resolved.stdout).reason;
+    assert.doesNotMatch(reason, /multiple active specs/, 'the recorded feature must resolve it');
+    assert.match(reason, /lack a verification receipt/, 'the gate must now reach receipt validation');
+    assert.match(reason, /specs\/beta\//, 'and validate the named feature, not a sibling');
+  });
+});
+
 test('Codex process-v3 Stop ignores a completed packet when one packet remains active', () => {
   inHookFixture((root, hooks) => {
     const completed = path.join(root, 'specs', 'auth');

package/bin/__tests__/package-inventory.test.js

@@ -2162,6 +2162,10 @@ process.stdout.write(JSON.stringify({ ok: result.ok, active: result.active, reas
   });
 }
 
+// `assertInstalledCompletion` leaves this fixture claiming closeout, which is what makes
+// it the one packet closeout approval resolves among the scaffolded siblings.
+const CLOSING_FIXTURE = 'compact-installed';
+
 function assertInstalledResolution(paths, root, platform, explicitFeature) {
   const code = `
 const checker = require(process.argv[1]); const resolver = require(process.argv[2]);
@@ -2170,13 +2174,45 @@ const base = { projectRoot: root, runtime: {}, payload: {} };
 if (platform === 'claude') base.resolver = resolver;
 const explicit = checker.resolveCandidate({ ...base, payload: { featureName: feature } });
 const ambiguous = checker.resolveCandidate(base);
-process.stdout.write(JSON.stringify({ explicit: explicit && explicit.featureName, error: ambiguous && ambiguous.error, candidates: ambiguous && ambiguous.candidates }));`;
-  const result = spawnSync(process.execPath, ['-e', code, paths.completion, paths.resolver, root, platform, explicitFeature], { cwd: root, encoding: 'utf8' });
-  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
-  const resolution = JSON.parse(result.stdout);
-  assert.equal(resolution.explicit, explicitFeature);
-  assert.equal(resolution.error, 'multiple_persisted');
-  assert.ok(resolution.candidates.length >= 2);
+process.stdout.write(JSON.stringify({ explicit: explicit && explicit.featureName, isNull: ambiguous === null, name: ambiguous && ambiguous.featureName, error: ambiguous && ambiguous.error, candidates: ambiguous && ambiguous.candidates }));`;
+  const run = () => {
+    const result = spawnSync(process.execPath, ['-e', code, paths.completion, paths.resolver, root, platform, explicitFeature], { cwd: root, encoding: 'utf8' });
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    return JSON.parse(result.stdout);
+  };
+
+  // Contract change: closeout approval counts only packets actually claiming closeout.
+  // This used to assert `multiple_persisted` from these fixtures, which pinned the
+  // over-strict behaviour issue #79 reports. `assertInstalledCompletion` above drove
+  // `compact-installed` to closeout, so exactly one of the three is claiming it; the
+  // scaffolded siblings are not rivals and must not block the approval.
+  const narrowed = run();
+  assert.equal(narrowed.explicit, explicitFeature);
+  assert.equal(narrowed.name, CLOSING_FIXTURE, `the one packet claiming closeout must resolve: ${JSON.stringify(narrowed)}`);
+  assert.equal(narrowed.error, undefined);
+
+  // Genuine ambiguity still blocks, and the installed copy must prove it rather than
+  // being assumed from the source tree this test deliberately deleted.
+  const closing = ['closing-a-installed', 'closing-b-installed'];
+  for (const name of closing) {
+    const dir = path.join(root, 'specs', name);
+    fs.mkdirSync(path.join(dir, 'tasks'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'spec.json'), `${JSON.stringify({
+      feature_name: name,
+      status: 'done',
+      current_phase: 'closeout',
+      task_registry: { 'tasks/task-R0-01-x.md': { status: 'done', completed_at: '2026-01-01T00:00:00.000Z' } },
+    }, null, 2)}\n`);
+    fs.writeFileSync(path.join(dir, 'tasks', 'task-R0-01-x.md'), '# Task\n\nStatus: done\n');
+  }
+  try {
+    const ambiguous = run();
+    assert.equal(ambiguous.explicit, explicitFeature, 'an explicit target still wins');
+    assert.equal(ambiguous.error, 'multiple_persisted');
+    assert.deepEqual([...ambiguous.candidates].sort(), [...closing, CLOSING_FIXTURE].sort(), 'only claiming packets are named');
+  } finally {
+    for (const name of closing) fs.rmSync(path.join(root, 'specs', name), { recursive: true, force: true });
+  }
 }
 
 function assertStrictSimulatedHandlerGuardrail(paths, root, fixture) {

package/bin/__tests__/spec-narrowing.test.js

@@ -0,0 +1,381 @@
+'use strict';
+
+// Two Stop hooks ask two different questions about the same repository, so they narrow an
+// ambiguous scan differently. The gate asks which packet still has unfinished work, so it
+// can validate that packet's receipts. Closeout approval asks which packet is claiming
+// closeout, so it can demand a one-time approval for it. Counting finished history as
+// ambiguity is what left a repository of accumulated features permanently blocked, with
+// the documented escape — an explicit feature target — unavailable.
+
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
+const RESOLVER = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-resolver.cjs'));
+
+function withProject(run) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-narrowing-'));
+  try {
+    return run(fs.realpathSync(dir));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** A legacy packet: spec.json plus nested tasks, the shape issue #79 reports. */
+function legacyPacket(root, name, { status, phase, taskStatus = 'done' } = {}) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(path.join(dir, 'tasks'), { recursive: true });
+  const spec = { feature_name: name, task_registry: { 'tasks/task-R0-01-x.md': { status: taskStatus, completed_at: '2026-01-01T00:00:00.000Z' } } };
+  if (status !== undefined) spec.status = status;
+  if (phase !== undefined) spec.current_phase = phase;
+  fs.writeFileSync(path.join(dir, 'spec.json'), `${JSON.stringify(spec, null, 2)}\n`);
+  fs.writeFileSync(path.join(dir, 'tasks', 'task-R0-01-x.md'), `# Task\n\nStatus: ${taskStatus}\n`);
+}
+
+/** A process-first packet: plan.md plus one flat task file. */
+function workflowPacket(root, name, taskStatus) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'plan.md'), '# Plan\nSpecs-Contract: process-first-ready-v1\n');
+  fs.writeFileSync(
+    path.join(dir, 'task-01-x.md'),
+    `# Task 01\n\nStatus: ${taskStatus}\n\n## Dependencies\n- none\n`
+  );
+}
+
+function recordActiveFeature(root, contents) {
+  const dir = path.join(root, 'specs', '_shared');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'active-feature.json'), contents);
+}
+
+function gateResolution(root) {
+  const resolved = RESOLVER.resolveWorkflowCandidate({
+    projectRoot: root, runtime: {}, target: null, includeCompleted: true,
+  });
+  return RESOLVER.refineWorkflowGateResolution(resolved);
+}
+
+// ── The gate: which packet still has work ───────────────────────────────────────────
+
+test('a legacy repository resolves its one unfinished packet', () => {
+  withProject((root) => {
+    for (let index = 1; index <= 3; index += 1) {
+      legacyPacket(root, `done-${index}`, { status: 'done', phase: 'closeout' });
+    }
+    legacyPacket(root, 'active-now', { status: 'in_progress', phase: 'execution', taskStatus: 'pending' });
+    const resolved = gateResolution(root);
+    assert.equal(resolved.error, undefined, `expected a resolution, got ${resolved.error}`);
+    assert.equal(resolved.featureName, 'active-now');
+  });
+});
+
+test('a legacy registry written with the older vocabulary counts as finished', () => {
+  // Issue #79's repository was upgraded from an older release whose task_registry used
+  // `completed`. Today's validator allows only pending/in_progress/blocked/done, so
+  // narrowing read those packets as unfinished and the block survived the fix that was
+  // supposed to clear it. Measured on the reported shape before this: 18 candidates.
+  for (const status of ['done', 'completed', 'complete']) {
+    withProject((root) => {
+      for (let index = 1; index <= 3; index += 1) {
+        legacyPacket(root, `history-${index}`, { taskStatus: status });
+      }
+      legacyPacket(root, 'active-now', { status: 'in_progress', phase: 'execution', taskStatus: 'pending' });
+      assert.equal(gateResolution(root).featureName, 'active-now', `task status ${status} must read as finished`);
+    });
+  }
+});
+
+test('a process-first packet keeps the strict task vocabulary', () => {
+  // The widened set is legacy-only. A process-first task saying `completed` is malformed,
+  // not finished, and must not be silently read as done.
+  withProject((root) => {
+    workflowPacket(root, 'done-1', 'done');
+    workflowPacket(root, 'odd', 'completed');
+    const resolved = gateResolution(root);
+    assert.notEqual(resolved.layoutKind, 'process-v3-completed-set', 'an invalid status is not done');
+  });
+});
+
+test('a legacy candidate never reaches the bulk branch', () => {
+  // The bulk branch exits before the semantic-digest, FLASH_UNVERIFIED, feature-receipt
+  // and completion-policy layers, so a legacy packet reaching it would turn a block into
+  // a silent pass. With every legacy packet finished there is nothing to narrow to, and
+  // the existing ambiguity must stand rather than the set being audited.
+  withProject((root) => {
+    legacyPacket(root, 'done-1', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'done-2', { status: 'done', phase: 'closeout' });
+    const resolved = gateResolution(root);
+    assert.notEqual(resolved.layoutKind, 'process-v3-completed-set');
+    assert.ok(resolved.error, 'an all-legacy finished set must stay ambiguous');
+  });
+});
+
+test('a process-first set still reaches the bulk branch', () => {
+  withProject((root) => {
+    workflowPacket(root, 'done-1', 'done');
+    workflowPacket(root, 'done-2', 'done');
+    assert.equal(gateResolution(root).layoutKind, 'process-v3-completed-set');
+  });
+});
+
+test('one unfinished process-first packet still narrows', () => {
+  withProject((root) => {
+    workflowPacket(root, 'done-1', 'done');
+    workflowPacket(root, 'active-now', 'pending');
+    assert.equal(gateResolution(root).featureName, 'active-now');
+  });
+});
+
+// ── Closeout approval: which packet is claiming closeout ────────────────────────────
+
+test('one packet claiming closeout among finished ones resolves', () => {
+  withProject((root) => {
+    legacyPacket(root, 'shipped', { status: 'in_progress', phase: 'execution', taskStatus: 'done' });
+    legacyPacket(root, 'closing', { status: 'done', phase: 'closeout' });
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.error, undefined);
+    assert.equal(resolved.featureName, 'closing');
+  });
+});
+
+test('a lone finished packet still resolves', () => {
+  // Four existing cases depend on this: closeout approval is claimed against a finished
+  // spec, so a single packet must resolve whatever its status.
+  for (const status of ['done', 'completed']) {
+    withProject((root) => {
+      legacyPacket(root, 'only', { status });
+      const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+      assert.equal(resolved.featureName, 'only', `status ${status} must still resolve`);
+    });
+  }
+});
+
+test('a lone packet mid-execution still resolves', () => {
+  // The closeout filter would drop this one, so the single-candidate return above it is
+  // what keeps a repository holding exactly one in-flight packet resolvable. Without it
+  // the hook goes silent for that repository instead of checking the packet.
+  withProject((root) => {
+    legacyPacket(root, 'solo', { status: 'in_progress', phase: 'implementation', taskStatus: 'pending' });
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.featureName, 'solo');
+  });
+});
+
+test('no packet claiming closeout resolves to null', () => {
+  // null means nothing is in flight and the hook stays silent; an error would keep
+  // blocking a repository where no closeout is being claimed at all.
+  withProject((root) => {
+    legacyPacket(root, 'a', { status: 'in_progress', phase: 'execution' });
+    legacyPacket(root, 'b', { status: 'in_progress', phase: 'execution' });
+    assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }), null);
+  });
+});
+
+test('several packets claiming closeout stay ambiguous and name only those', () => {
+  withProject((root) => {
+    legacyPacket(root, 'closing-a', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'closing-b', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'working', { status: 'in_progress', phase: 'execution' });
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.error, 'multiple_persisted');
+    assert.deepEqual(resolved.candidates, ['closing-a', 'closing-b']);
+  });
+});
+
+test('codex resolveCandidate agrees with the shared resolver', () => {
+  // Codex kept its own candidate count, reachable because spec-utils did not export the
+  // shared function. A Claude-only change would leave every Codex turn blocked.
+  const codexCheck = require(path.join(PACKAGE_ROOT, 'src/codex/hooks/completion-authority-check.cjs'));
+  const utils = require(path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/spec-utils.cjs'));
+  assert.equal(typeof utils.resolvePersistedSpec, 'function', 'the wrapper must be exported');
+  withProject((root) => {
+    legacyPacket(root, 'shipped', { status: 'in_progress', phase: 'execution', taskStatus: 'done' });
+    legacyPacket(root, 'closing', { status: 'done', phase: 'closeout' });
+    const shared = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    const viaCodex = codexCheck.resolveCandidate({ projectRoot: root, runtime: {}, payload: {} });
+    assert.equal(viaCodex.featureName, shared.featureName);
+  });
+});
+
+// ── The recorded active feature: the escape the block told users to take ────────────
+
+test('a recorded active feature resolves two packets claiming closeout', () => {
+  withProject((root) => {
+    legacyPacket(root, 'closing-a', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'closing-b', { status: 'done', phase: 'closeout' });
+    assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }).error, 'multiple_persisted');
+    recordActiveFeature(root, '{"featureName": "closing-b"}\n');
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.error, undefined, `expected a resolution, got ${resolved.error}`);
+    assert.equal(resolved.featureName, 'closing-b');
+  });
+});
+
+test('a payload target beats the recorded file', () => {
+  withProject((root) => {
+    legacyPacket(root, 'alpha', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'beta', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "alpha"}\n');
+    const resolved = RESOLVER.resolvePersistedSpec({
+      projectRoot: root, runtime: {}, target: { featureName: 'beta' },
+    });
+    assert.equal(resolved.featureName, 'beta', 'the caller must win');
+  });
+});
+
+test('a blank recorded feature is ignored rather than malformed', () => {
+  // explicitTargetValue turns a blank into null, and a null target becomes an
+  // explicit_malformed error that blocks. The reader must return null instead, or every
+  // project holding a stray file would be blocked by the very escape hatch.
+  for (const contents of ['{"featureName": "   "}', '{"featureName": 42}', '{}', 'not json', '[]']) {
+    withProject((root) => {
+      legacyPacket(root, 'only', { status: 'done', phase: 'closeout' });
+      recordActiveFeature(root, contents);
+      assert.equal(
+        RESOLVER.readActiveFeatureTarget({ projectRoot: root, runtime: {} }), null,
+        `${contents} must be invisible`
+      );
+      assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }).featureName, 'only');
+    });
+  }
+});
+
+test('a recorded feature cannot escape the specs root', () => {
+  // The reader adds no trust: the value goes through the resolver's existing checks.
+  withProject((root) => {
+    legacyPacket(root, 'a', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'b', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "../../etc"}');
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.ok(resolved.error, 'an escaping name must produce the existing error, not a resolution');
+    assert.notEqual(resolved.featureName, '../../etc');
+  });
+});
+
+test('a symlinked recorded feature is refused', () => {
+  // The file is read from inside the project, so a symlink could name a target the
+  // project does not contain. The repository already refuses symlinked runtime
+  // dependencies elsewhere; this reader follows the same rule.
+  withProject((root) => {
+    legacyPacket(root, 'only', { status: 'done', phase: 'closeout' });
+    const outside = path.join(root, 'outside.json');
+    fs.writeFileSync(outside, '{"featureName": "only"}');
+    const dir = path.join(root, 'specs', '_shared');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.symlinkSync(outside, path.join(dir, 'active-feature.json'));
+    assert.equal(RESOLVER.readActiveFeatureTarget({ projectRoot: root, runtime: {} }), null);
+  });
+});
+
+test('an absent file leaves every project exactly as it was', () => {
+  withProject((root) => {
+    legacyPacket(root, 'only', { status: 'in_progress', phase: 'execution' });
+    assert.equal(RESOLVER.readActiveFeatureTarget({ projectRoot: root, runtime: {} }), null);
+    assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }).featureName, 'only');
+  });
+});
+
+test('the approval prompt names its feature', () => {
+  // Without the name a user types a bare nonce and cannot tell which closeout they are
+  // approving, while the recorded file can influence which packet resolves.
+  for (const runtimeDir of ['claude', 'codex']) {
+    const hook = fs.readFileSync(
+      path.join(PACKAGE_ROOT, 'src', runtimeDir, 'hooks', 'completion-authority.cjs'), 'utf8'
+    );
+    assert.match(hook, /const feature = result\.candidate\?\.featureName;/, `${runtimeDir} must read the name`);
+    assert.match(hook, /closeout approval is required for \$\{feature \?/, `${runtimeDir} must print it`);
+  }
+});
+
+test('the shared workflow resolver ignores the recorded file', () => {
+  // resolveWorkflowCandidate has five consumers, including spec-state.cjs and
+  // precompact.cjs. Reading the file inside it would retarget hooks that never asked,
+  // so the two gates apply it at their own call sites instead. Neither of those suites
+  // writes the file, so nothing else pins this containment.
+  withProject((root) => {
+    legacyPacket(root, 'alpha', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'beta', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "beta"}');
+    const resolved = RESOLVER.resolveWorkflowCandidate({
+      projectRoot: root, runtime: {}, target: null, includeCompleted: true,
+    });
+    assert.ok(resolved.error, 'the shared resolver must stay ambiguous on its own');
+    assert.notEqual(resolved.featureName, 'beta');
+  });
+});
+
+test('the codex gate consults the file only after its payload', () => {
+  const utils = require(path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/spec-utils.cjs'));
+  assert.equal(typeof utils.readActiveFeatureTarget, 'function', 'the wrapper must be exported');
+  assert.equal(typeof utils.extractExplicitTarget, 'function', 'the gate needs the payload extractor');
+  withProject((root) => {
+    legacyPacket(root, 'alpha', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "alpha"}');
+    assert.deepEqual(
+      utils.extractExplicitTarget({ featureName: 'beta' }) || utils.readActiveFeatureTarget({ projectRoot: root, runtime: {} }),
+      { explicitFeature: 'beta' }
+    );
+    assert.deepEqual(
+      utils.extractExplicitTarget({}) || utils.readActiveFeatureTarget({ projectRoot: root, runtime: {} }),
+      { explicitFeature: 'alpha' }
+    );
+  });
+});
+
+// ── End to end: the block the report describes, and the escape from it ──────────────
+
+/** A git project the Stop gate will accept as a real project root. */
+function gitProject(run) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-gate-')));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'],
+      ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+      const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    return run(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function runGate(hook, dir) {
+  const result = spawnSync(process.execPath, [path.join(PACKAGE_ROOT, hook)], {
+    input: JSON.stringify({
+      hook_event_name: 'Stop', session_id: 'test', transcript_path: '/tmp/t',
+      stop_hook_active: false, cwd: dir,
+    }),
+    // PROJECT_ROOT wins over cwd in the hook, so the host's own specs cannot leak in.
+    encoding: 'utf8', env: { ...process.env, PROJECT_ROOT: dir },
+  });
+  return (result.stdout || '').trim();
+}
+
+// The Codex gate resolves PROJECT_ROOT from its own installed location, so its end-to-end
+// twin lives in bin/__tests__/codex-hooks.test.js, which owns the installer fixture.
+for (const [runtimeName, hook] of [['claude', 'src/claude/hooks/spec-gate.cjs']]) {
+  test(`${runtimeName}: the recorded feature turns the identity block into receipt validation`, () => {
+    // This is issue #79 end to end. Ambiguity answers a missing-receipt violation with an
+    // identity complaint whose stated remedy nothing could supply; naming the feature
+    // makes the gate resolve it and report the violation that was there all along.
+    gitProject((dir) => {
+      legacyPacket(dir, 'alpha', { status: 'done', phase: 'closeout' });
+      legacyPacket(dir, 'beta', { status: 'done', phase: 'closeout' });
+
+      const blocked = runGate(hook, dir);
+      assert.match(blocked, /multiple active specs detected/, 'the reported block must reproduce');
+
+      recordActiveFeature(dir, '{"featureName": "beta"}\n');
+      const resolved = runGate(hook, dir);
+      assert.doesNotMatch(resolved, /multiple active specs/, 'the recorded feature must resolve it');
+      assert.match(resolved, /lack a verification receipt/, 'the gate must now reach receipt validation');
+      assert.match(resolved, /specs\/beta\//, 'and validate the named feature, not a sibling');
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "description": "Native spec-driven workflows for Claude Code and Codex CLI. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/hooks/__tests__/completion-authority.test.js

@@ -700,7 +700,14 @@ for (const kind of ['claude', 'codex']) {
       assert.match(block(stop(runtime, { featureName: 'other-feature' })).reason, /explicit/i);
       prepare(root, { feature: 'other-feature', phase: 'implementation' });
       assert.ok(nonceFrom(stop(runtime, { featureName: FEATURE })).nonce);
-      assert.match(block(stop(runtime)).reason, /multiple_persisted|multiple/i);
+      // Contract change: a sibling that is not claiming closeout is no longer a rival.
+      // This used to assert ambiguity, which is the over-strict behaviour issue #79
+      // reports: a repository that had merely accumulated features could never name its
+      // current one again. Only FEATURE is at closeout here, so it resolves and its
+      // approval is demanded. Two packets both claiming closeout still block, which
+      // `several packets claiming closeout stay ambiguous and name only those` covers in
+      // bin/__tests__/spec-narrowing.test.js.
+      assert.ok(nonceFrom(stop(runtime)).nonce, 'the one packet claiming closeout resolves');
       for (const malformed of [
         { featureName: '' },
         { featureName: 42 },

package/src/claude/hooks/completion-authority.cjs

@@ -131,7 +131,10 @@ function stop(payload) {
   const consumed = STATE.consumeGrant(root, result.binding);
   if (consumed.ok) return;
   const pending = STATE.createPending(root, result.binding);
-  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
+  // Name the feature: a recorded target can influence which packet resolves, so an
+  // approval the user cannot identify is an approval they cannot withhold.
+  const feature = result.candidate?.featureName;
+  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required for ${feature ? `"${feature}"` : 'the resolved feature'}. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
 }
 
 let mode = process.argv[2] || null;

package/src/claude/hooks/spec-gate.cjs

@@ -119,9 +119,14 @@ try {
   } catch { /* gate stays on */ }
   // Active-spec discovery via shared resolver — explicit target if present, else fail on ambiguity.
   const baseDir   = cwd;
-  const target = typeof RESOLVER.extractExplicitTarget === 'function'
+  const target = (typeof RESOLVER.extractExplicitTarget === 'function'
     ? RESOLVER.extractExplicitTarget(payload)
-    : null;
+    : null)
+    // Only when the host named nothing. The recorded target is what makes "Provide
+    // explicit feature target" an instruction a user can actually follow.
+    || (typeof RESOLVER.readActiveFeatureTarget === 'function'
+      ? RESOLVER.readActiveFeatureTarget({ projectRoot: baseDir, runtime })
+      : null);
   let resolved = typeof RESOLVER.resolveWorkflowCandidate === 'function'
     ? RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true })
     : FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });

package/src/claude/scripts/spec-resolver.cjs

@@ -289,6 +289,12 @@ function inspectWorkflowFeature(specsDir, canonicalSpecs, requestedName) {
   };
 }
 
+// Legacy registries written before the current vocabulary use `completed`, which today's
+// validator rejects but which exists in upgraded repositories. Reading it as finished is
+// what lets those packets stop competing for the gate's attention; `spec-final-state.cjs`
+// already reads spec status the same way. Process-first packets keep the strict set.
+const LEGACY_TASK_DONE = new Set(['done', 'completed', 'complete']);
+
 function normalizeLegacyWorkflowCandidate(candidate) {
   const registry = candidate.spec?.task_registry || {};
   const tasks = Object.entries(registry).map(([taskPath, task]) => ({
@@ -302,7 +308,7 @@ function normalizeLegacyWorkflowCandidate(candidate) {
     phase: candidate.spec?.current_phase || candidate.spec?.phase || 'unknown',
     taskRegistry: registry,
     tasks,
-    allTasksDone: tasks.length > 0 && tasks.every((task) => task.status === 'done'),
+    allTasksDone: tasks.length > 0 && tasks.every((task) => LEGACY_TASK_DONE.has(task.status)),
   };
 }
 
@@ -491,6 +497,47 @@ function explicitTargetValue(value) {
   return typeof value === 'string' ? value.trim() : value;
 }
 
+/**
+ * Read the feature a project has recorded as the one being worked on. This answers a
+ * genuine ambiguity that no host payload resolves, so it is deliberately not a source
+ * inside `extractExplicitTarget`: that function recurses and is shared with consumers
+ * that are not the Stop hooks. Anything other than a non-empty single-line
+ * `featureName` string is invisible rather than an error, because an error here would
+ * block every turn in a project that merely has a stray file. The value is then treated
+ * exactly like a host-supplied feature name and still faces containment, existence, and
+ * JSON checks.
+ */
+function readActiveFeatureTarget({ projectRoot, runtime } = {}) {
+  if (!projectRoot) return null;
+  let specsDir;
+  try {
+    specsDir = specsDirectory(projectRoot, runtime || {});
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    const file = path.join(specsDir, '_shared', 'active-feature.json');
+    // A symlink here could name a file outside the project, so only a regular file counts.
+    const info = lstatOptional(file);
+    if (!info.exists || info.isSymlink || !info.stat.isFile()) return null;
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const value = parsed.featureName;
+  if (typeof value !== 'string' || /[\r\n]/.test(value)) return null;
+  const trimmed = value.trim();
+  return trimmed ? { explicitFeature: trimmed } : null;
+}
+
 /**
  * Normalize host-provided feature targets without making runtime adapters
  * guess from the first active directory. The resolver remains the authority
@@ -708,14 +755,27 @@ function resolvePersistedSpec({ projectRoot, runtime, explicitFeature, explicitP
     }
     return resolveActiveSpec({ projectRoot, runtime, ...normalized });
   }
+  // Only now, with the caller having named nothing: a recorded target must never
+  // redirect a hook that already knows which feature its turn is about.
+  const recorded = readActiveFeatureTarget({ projectRoot, runtime });
+  if (recorded) return resolveActiveSpec({ projectRoot, runtime, ...recorded });
   try {
     const candidates = findAllSpecCandidates(projectRoot, runtime);
     if (candidates.length === 0) return null;
+    // One packet resolves on its own terms. Closeout approval is claimed against a
+    // finished spec, so status must never decide identity here.
     if (candidates.length === 1) return candidates[0];
+    // This path serves closeout approval, so only a packet actually claiming closeout is
+    // a real rival. Counting finished history as ambiguity is what made the gate
+    // unsatisfiable in a repository that had simply accumulated features.
+    const { isDurableCloseout } = require('./spec-final-state.cjs');
+    const claiming = candidates.filter((candidate) => isDurableCloseout(candidate.spec));
+    if (claiming.length === 1) return claiming[0];
+    if (claiming.length === 0) return null;
     return {
       error: 'multiple_persisted',
-      candidates: candidates.map((candidate) => candidate.featureName),
-      reason: `Multiple persisted specs found: ${candidates.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
+      candidates: claiming.map((candidate) => candidate.featureName),
+      reason: `Multiple persisted specs found: ${claiming.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
     };
   } catch (error) {
     return {
@@ -893,10 +953,11 @@ function refineWorkflowGateResolution(resolved) {
     return resolved;
   }
   const candidates = resolved.active;
-  if (candidates.length === 0 || candidates.some((candidate) => candidate.layoutKind !== 'process-v3')) {
-    return resolved;
-  }
+  if (candidates.length === 0) return resolved;
 
+  // Which packet still has work decides this, not which layout it uses: a repository of
+  // legacy packets was permanently ambiguous only because the check below used to sit
+  // here and reject the whole set on sight.
   const unfinished = candidates.filter((candidate) => !candidate.allTasksDone);
   if (unfinished.length === 1) return unfinished[0];
   if (unfinished.length > 1) {
@@ -908,6 +969,10 @@ function refineWorkflowGateResolution(resolved) {
       reason: `Multiple active workflows found: ${unfinished.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
     };
   }
+  // The bulk-audit branch exits before the semantic-digest, FLASH_UNVERIFIED,
+  // feature-receipt, and completion-policy layers that the single-candidate path runs, so
+  // only process-first packets may reach it. Anything else keeps the existing ambiguity.
+  if (candidates.some((candidate) => candidate.layoutKind !== 'process-v3')) return resolved;
   return {
     layoutKind: 'process-v3-completed-set',
     candidates,
@@ -923,6 +988,7 @@ module.exports = {
   findAllSpecCandidates,
   extractExplicitTarget,
   resolveActiveSpec,
+  readActiveFeatureTarget,
   resolvePersistedSpec,
   resolveWorkflowCandidate,
   refineWorkflowGateResolution,

package/src/codex/hooks/completion-authority-check.cjs

@@ -37,6 +37,10 @@ function explicitTarget(payload) {
 function resolveCandidate({ projectRoot, runtime, payload }) {
   const target = explicitTarget(payload);
   if (target) return RESOLVER.resolveActiveSpec({ projectRoot, runtime, ...target });
+  // Delegate so both runtimes answer the same question; the count below stays only as a
+  // fallback for an installed resolver older than this wrapper.
+  const shared = RESOLVER.resolvePersistedSpec({ projectRoot, runtime });
+  if (shared !== null) return shared;
   const candidates = RESOLVER.findAllSpecCandidates(projectRoot, runtime);
   if (candidates.length > 1) return { error: 'multiple_persisted', candidates: candidates.map((candidate) => candidate.featureName) };
   return candidates[0] || null;

package/src/codex/hooks/completion-authority.cjs

@@ -79,7 +79,10 @@ function stop(payload) {
   const consumed = STATE.consumeGrant(projectRoot, result.binding);
   if (consumed.ok) return;
   const pending = STATE.createPending(projectRoot, result.binding);
-  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
+  // Name the feature: a recorded target can influence which packet resolves, so an
+  // approval the user cannot identify is an approval they cannot withhold.
+  const feature = result.candidate?.featureName;
+  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required for ${feature ? `"${feature}"` : 'the resolved feature'}. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
 }
 
 let mode = process.argv[2] || null;

package/src/codex/hooks/lib/spec-utils.cjs

@@ -140,8 +140,29 @@ function taskStatusMap(spec) {
   );
 }
 
+function extractExplicitTarget(...sources) {
+  const resolver = sharedResolver();
+  if (typeof resolver.extractExplicitTarget !== 'function') return null;
+  return resolver.extractExplicitTarget(...sources);
+}
+
+function readActiveFeatureTarget(options) {
+  const resolver = sharedResolver();
+  if (typeof resolver.readActiveFeatureTarget !== 'function') return null;
+  return resolver.readActiveFeatureTarget(options);
+}
+
+function resolvePersistedSpec(options) {
+  const resolver = sharedResolver();
+  if (typeof resolver.resolvePersistedSpec !== 'function') return null;
+  return resolver.resolvePersistedSpec(options);
+}
+
 module.exports = {
   findActiveSpec,
+  extractExplicitTarget,
+  readActiveFeatureTarget,
+  resolvePersistedSpec,
   findAllActiveSpecs,
   findAllSpecCandidates,
   resolveActiveSpec,

package/src/codex/hooks/spec-gate.cjs

@@ -49,8 +49,12 @@ try {
     throw new Error('shared workflow policy lacks completion authority functions');
   }
   const resolver = require('./lib/spec-utils.cjs');
+  // The payload is still the authority. The recorded target only answers the ambiguity
+  // the payload leaves, which is what made the block unescapable on this runtime too.
+  const target = resolver.extractExplicitTarget(payload)
+    || resolver.readActiveFeatureTarget({ projectRoot, runtime });
   let resolved = typeof resolver.resolveWorkflowCandidate === 'function'
-    ? resolver.resolveWorkflowCandidate({ projectRoot, runtime, target: payload, includeCompleted: true })
+    ? resolver.resolveWorkflowCandidate({ projectRoot, runtime, target, includeCompleted: true })
     : FINAL_STATE.resolveCandidate({ resolver, projectRoot, runtime, payload });
   if (typeof resolver.refineWorkflowGateResolution === 'function') {
     resolved = resolver.refineWorkflowGateResolution(resolved);