@haposoft/cafekit 0.16.3 → 0.16.5

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.5-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');
@@ -1831,13 +1866,19 @@ test('Codex emits the required decision for all six receipt states', () => {
     assert.equal(decide(), 'accept', 'a committed, unchanged receipt on a clean tree must be accepted');
     assert.equal(sharedDecides(), 'accept', 'the shared checker must agree');
 
-    // 4. dirty tree outside the specs root, hook run from a nested directory with
-    //    the change outside that directory's subtree.
+    // 4. Contract change: an uncommitted file outside the specs root no longer
+    //    rebinds a committed receipt. Base is the last commit touching anything
+    //    outside the specs root, so every receipt written before a later commit
+    //    records an older Base by construction — measured at 52 of 52 on the
+    //    CafeKit repository. The condition therefore failed every historical
+    //    receipt at once whenever any unrelated file was dirty, and could not
+    //    tell a tampered receipt from an untouched one. Case 6 below still
+    //    catches the receipt that actually changed.
     fs.writeFileSync(outsideDirt, 'uncommitted\n');
     assert.ok(!path.relative(nested, outsideDirt).startsWith('..') === false,
       'the dirt must lie outside the working directory used for the run');
-    assert.equal(decide(), 'block', 'an uncommitted change outside the specs root must rebind');
-    assert.equal(sharedDecides(), 'block', 'the shared checker must agree');
+    assert.equal(decide(), 'accept', 'unrelated dirt must not reopen a committed receipt');
+    assert.equal(sharedDecides(), 'accept', 'the shared checker must agree');
     git('checkout', '--', 'src/outside.txt');
 
     // 5. work confined to the specs root does not reopen a committed receipt.

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.5",
   "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/__tests__/spec-gate.test.js

@@ -1621,43 +1621,61 @@ test('41. unborn HEAD fails closed before any receipt check', () => {
   }
 });
 
-test('42. dirty tree outside specs requires binding, regardless of working directory', () => {
-  const dir = makeWorkflowFixture(boundReceipt());
+test('42. a dirty tree outside specs does not reopen a committed receipt', () => {
+  // Contract change. This used to require a block. `Base` is the last commit
+  // touching anything outside the specs root, so a receipt written before any
+  // later commit records an older `Base` by construction — 52 of 52 done
+  // receipts on the CafeKit repository. Reopening on a dirty tree therefore
+  // failed every historical receipt at once, every time, which blocked projects
+  // on their first turn of a session with nothing changed. What still blocks is
+  // the task file that actually differs from its committed bytes, asserted
+  // below from both working directories, since the git call must pin the
+  // project root rather than the working directory.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
   try {
     commitAll(dir, 'receipt');
     fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
     fs.writeFileSync(path.join(dir, 'src', 'dirty.txt'), 'uncommitted\n');
     clearCache();
-    const fromRoot = parseBlock(runHook({}, dir).stdout);
-    assert.ok(fromRoot && fromRoot.decision === 'block', 'an uncommitted change outside specs must rebind');
-    assert.match(fromRoot.reason, /\bprovenance\b/);
+    assert.strictEqual(runHook({}, dir).stdout, '', 'unrelated dirt must not reopen a committed receipt');
     clearCache();
-    const fromSpecs = parseBlock(runHookFrom(dir, path.join(dir, 'specs', FEATURE)).stdout);
-    assert.ok(fromSpecs && fromSpecs.decision === 'block', 'the status check must pin the project root, not the working directory');
-    assert.match(fromSpecs.reason, /\bprovenance\b/);
+    assert.strictEqual(runHookFrom(dir, path.join(dir, 'specs', FEATURE)).stdout, '',
+      'and must not reopen it when the hook runs from inside the specs root either');
+
+    const taskFile = path.join(dir, 'specs', FEATURE, 'task-01-demo.md');
+    fs.writeFileSync(taskFile, fs.readFileSync(taskFile, 'utf8').replace(STALE_HEAD, 'd'.repeat(64)));
+    for (const [label, run] of [['project root', () => runHook({}, dir)],
+      ['specs root', () => runHookFrom(dir, path.join(dir, 'specs', FEATURE))]]) {
+      clearCache();
+      const body = parseBlock(run().stdout);
+      assert.ok(body && body.decision === 'block', `an edited task file must rebind, run from the ${label}`);
+      assert.match(body.reason, /\bprovenance\b/);
+    }
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test('42b. a change hidden by skip-worktree or assume-unchanged requires binding', () => {
-  // `git status` honors both index flags, so a tracked file outside the specs
-  // root can differ from HEAD while the tree reports clean. Structure mode must
-  // not be granted from a report that git itself is suppressing.
+test('42b. skip-worktree and assume-unchanged cannot hide an edited task file', () => {
+  // Both index flags make `git status` report a modified file as clean. The mode
+  // selector no longer consults status at all, but it must not become hideable
+  // some other way: the committed-bytes check reads the file from disk and asks
+  // git for `HEAD:<path>`, and neither consults the index. Marking the task file
+  // with either flag must therefore change nothing.
   for (const flag of ['--skip-worktree', '--assume-unchanged']) {
     const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
     try {
-      fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
-      fs.writeFileSync(path.join(dir, 'src', 'hidden.txt'), 'committed\n');
-      commitAll(dir, 'receipt and source');
-      const marked = spawnSync('git', ['-C', dir, 'update-index', flag, 'src/hidden.txt'], { encoding: 'utf8' });
+      commitAll(dir, 'receipt');
+      const taskRelative = `specs/${FEATURE}/task-01-demo.md`;
+      const marked = spawnSync('git', ['-C', dir, 'update-index', flag, taskRelative], { encoding: 'utf8' });
       assert.strictEqual(marked.status, 0, marked.stderr);
-      fs.writeFileSync(path.join(dir, 'src', 'hidden.txt'), 'tampered\n');
+      const taskFile = path.join(dir, taskRelative);
+      fs.writeFileSync(taskFile, fs.readFileSync(taskFile, 'utf8').replace(STALE_HEAD, 'd'.repeat(64)));
       const status = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' });
       assert.strictEqual(status.stdout.trim(), '', `${flag} must make the tree look clean for this case to mean anything`);
       clearCache();
       const body = parseBlock(runHook({}, dir).stdout);
-      assert.ok(body && body.decision === 'block', `${flag} must not grant structure-only`);
+      assert.ok(body && body.decision === 'block', `${flag} must not hide an edited task file`);
       assert.match(body.reason, /\bprovenance\b/);
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
@@ -1771,10 +1789,10 @@ test('46. a dirty file inside the specs root does not force binding', () => {
   }
 });
 
-test('47. completed-set branch accepts committed receipts and blocks a tampered one', () => {
+test('47. completed-set branch accepts committed receipts and blocks an edited one', () => {
   // Two finished packets resolve to the completed-set branch, which is the path
-  // that revalidated every done receipt on every Stop. Prove the new mode works
-  // there, then prove it still blocks.
+  // that revalidated every done receipt on every Stop. Prove committed receipts
+  // survive both a clean and a dirty tree, then prove an edited one still blocks.
   const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
   try {
     const secondDir = path.join(dir, 'specs', 'second');
@@ -1788,13 +1806,27 @@ test('47. completed-set branch accepts committed receipts and blocks a tampered
     clearCache();
     const accepted = runHook({}, dir);
     assert.strictEqual(accepted.stdout, '', 'the completed-set branch must accept committed receipts on a clean tree');
+    // Contract change: unrelated dirt no longer reopens committed receipts. This
+    // used to assert a block, which is what made the gate unusable in a project
+    // holding several finished packets — one untracked file failed every receipt
+    // in the repository at once. Base is the last commit touching anything
+    // outside the specs root, so a historical receipt records an older Base by
+    // construction and the check fired on all of them, always.
     fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
     fs.writeFileSync(path.join(dir, 'src', 'dirty.txt'), 'uncommitted\n');
     clearCache();
+    assert.strictEqual(runHook({}, dir).stdout, '', 'unrelated dirt must not reopen committed receipts');
+
+    // What still blocks: the receipt that actually changed after being committed.
+    fs.writeFileSync(
+      path.join(secondDir, 'task-01-second.md'),
+      fs.readFileSync(path.join(secondDir, 'task-01-second.md'), 'utf8').replace(STALE_HEAD, 'd'.repeat(64)),
+    );
+    clearCache();
     const body = parseBlock(runHook({}, dir).stdout);
-    assert.ok(body && body.decision === 'block', 'the completed-set branch must rebind on a dirty tree');
+    assert.ok(body && body.decision === 'block', 'a receipt edited after commit must still be rebound');
     assert.match(body.reason, /\bprovenance\b/);
-    assert.match(body.reason, /second|demo/);
+    assert.match(body.reason, /second/);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }

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 });
@@ -235,10 +240,10 @@ try {
   // task currently marked done, so a cached PASS cannot hide later mutations
   // (deletion, placeholder, changed Verification/Command/Exit, missing
   // output, edited artifact bytes). Base/Head are compared against the live
-  // runtime only while the task file differs from its committed bytes or the
-  // tree outside the specs root is dirty; a committed, unchanged receipt on a
-  // clean tree is checked on structure alone. Cache is an optimization, not
-  // truth.
+  // runtime only while the task file differs from its committed bytes; once it
+  // is committed and unchanged the receipt is checked on structure alone, and
+  // work elsewhere in the tree no longer reopens it. Cache is an optimization,
+  // not truth.
   const featureCache = cacheExists ? (cache[featureName] || {}) : {};
   const allDoneTasks = Object.keys(taskRegistry).filter((tp) =>
     (taskRegistry[tp]?.status || 'pending') === 'done'

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

@@ -226,7 +226,7 @@ try {
       lines.push('- Migration required: add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.');
     }
     lines.push('- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.');
-    lines.push(`- Workflow source: \`specs/${featureName}/plan.md\`; Stop re-checks every done receipt, binding Base/Head to the runtime until the task file is committed, unchanged, and the tree outside the specs root is clean.`);
+    lines.push(`- Workflow source: \`specs/${featureName}/plan.md\`; Stop re-checks every done receipt, binding Base/Head to the runtime until the task file is committed and unchanged.`);
   } else {
     lines.push('- Sync `spec.json` + task Markdown status after verified work; task proof belongs in `receipts/<task-basename>.md`.');
     lines.push(`- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`);

package/src/claude/rules/state-sync.md

@@ -33,8 +33,11 @@ Set `Status: done` only after the inline Receipt passes the
 fenced block of current command output.
 
 A done task keeps that binding while its file differs from its committed bytes,
-and is validated on structure alone once the file is committed, unchanged, and the
-tree outside the specs root is clean. The gate detects drift, not invention: a valid
+and is validated on structure alone once that file is committed and unchanged. Work
+elsewhere in the tree does not reopen it: Base is the last commit touching anything
+outside the specs root, so every finished receipt records an older Base by
+construction and reopening on a dirty tree failed all of them at once.
+The gate detects drift, not invention: a valid
 Base and Head pair costs one command and no verification run, so neither mode proves
 that the command was executed. Missing, stale, contradictory,
 placeholder, copied, failure, or zero-test evidence leaves the task unfinished.

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

@@ -5,7 +5,6 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { annotatedMarkdownLines } = require('./spec-resolver.cjs');
-const { RUNTIME_STATE_ROOTS } = require('./provenance.cjs');
 
 const EVIDENCE_HEADINGS = new Set([
   'Evidence',
@@ -185,14 +184,19 @@ function tryGitBytes(root, args) {
   return result.stdout;
 }
 
-// A receipt is bound to live Base/Head while it is being written or altered.
-// Once its task file matches the committed bytes and nothing outside the specs
-// root is uncommitted, later commits must not reopen it: rebinding every done
-// receipt on every Stop made each unrelated commit a refresh of all of them.
-// Every state that cannot be read as committed-and-clean keeps the binding,
-// including an unborn HEAD, a staged-only file, and any git failure. The git
-// calls pin the project root; a working-directory-relative status query run
-// from inside the specs root reports a dirty tree as clean.
+// A receipt is bound to live Base/Head while its own task file is being written
+// or altered, and validates on structure alone once that file matches its
+// committed bytes. The binding used to require the whole tree outside the specs
+// root to be clean as well. That condition was removed because it carried no
+// information: Base is the last commit touching anything outside the specs root,
+// so every receipt written before a later commit records an older Base by
+// construction. Measured on this repository, 52 of 52 done receipts differed
+// from the live Base, so one uncommitted unrelated file failed all of them at
+// once and a tampered receipt was indistinguishable from an untouched one. The
+// signal it was meant to carry — marking a task done and then editing the code —
+// is still caught, because doing that leaves the task file uncommitted. Every
+// state that cannot be read as committed-and-unchanged keeps the binding,
+// including an unborn HEAD, a staged-only file, and any git failure.
 function receiptBindingMode(featureDir, taskPath, taskBytes, runtimeContext) {
   const root = runtimeContext && typeof runtimeContext.project_root === 'string' ? runtimeContext.project_root : null;
   const specsRoot = runtimeContext && typeof runtimeContext.specs_root === 'string' ? runtimeContext.specs_root : null;
@@ -208,24 +212,6 @@ function receiptBindingMode(featureDir, taskPath, taskBytes, runtimeContext) {
   // so a checkout that converts line endings can still reach structure mode.
   const committed = tryGitBytes(root, ['cat-file', '--filters', `HEAD:${taskRelative}`]);
   if (committed === null || !committed.equals(taskBytes)) return 'binding';
-  // The same roots the provenance manifest calls generated runtime state rather
-  // than source evidence. Without them the gate defeats itself: writing its own
-  // cache dirties the tree, so a project that tracks its runtime directory could
-  // never reach structure mode.
-  const outsideSpecs = ['--', '.', `:(exclude,literal)${specsRelative}`,
-    ...RUNTIME_STATE_ROOTS.map((entry) => `:(exclude,literal)${entry}`)];
-  const status = tryGitBytes(root, ['status', '--porcelain', '--untracked-files=all', ...outsideSpecs]);
-  if (status === null || status.length !== 0) return 'binding';
-  // `git status` obeys skip-worktree and assume-unchanged, so a tracked file can
-  // be modified while the tree reports clean. Require every index entry outside
-  // the specs root to carry the plain cached tag `H`; any other tag, including
-  // `S` and the lowercase assume-unchanged tags, keeps the binding.
-  const indexTags = tryGitBytes(root, ['ls-files', '-v', ...outsideSpecs]);
-  if (indexTags === null) return 'binding';
-  const hidden = indexTags.toString('utf8').split('\n')
-    .filter((line) => line.trim() !== '')
-    .some((line) => line[0] !== 'H');
-  if (hidden) return 'binding';
   return 'structure';
 }
 

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/claude/skills/specs/SKILL.md

@@ -128,7 +128,7 @@ The shared workflow resolver recognizes only a regular `plan.md` plus one or mor
 regular flat `task-*.md` files in one direct feature directory, and projects exact
 `Status:` values without inferring blockers from prose. The Stop gate re-reads every
 done Receipt, binding Base and Head to the live runtime until the task file is
-committed, unchanged, and the tree outside the specs root is clean. It detects drift
+committed and unchanged; work elsewhere in the tree does not reopen it. It detects drift
 between a receipt and the tree, not invention: a valid pair costs one command and no
 verification run, so a receipt for a command that never ran satisfies it in either
 mode. C3 is where a human weighs the evidence. These checks are a final safety net,

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);

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

@@ -156,7 +156,7 @@ try {
     }
     lines.push(
       '- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.',
-      `- Workflow source: \`specs/${active.featureName}/plan.md\`; Stop re-checks every done receipt, binding Base/Head to the runtime until the task file is committed, unchanged, and the tree outside the specs root is clean.`,
+      `- Workflow source: \`specs/${active.featureName}/plan.md\`; Stop re-checks every done receipt, binding Base/Head to the runtime until the task file is committed and unchanged.`,
       '- Hooks revalidate receipt bytes but never grant approval.'
     );
   } else {

package/src/codex/rules/state-sync.md

@@ -33,8 +33,11 @@ Set `Status: done` only after the inline Receipt passes the
 fenced block of current command output.
 
 A done task keeps that binding while its file differs from its committed bytes,
-and is validated on structure alone once the file is committed, unchanged, and the
-tree outside the specs root is clean. The gate detects drift, not invention: a valid
+and is validated on structure alone once that file is committed and unchanged. Work
+elsewhere in the tree does not reopen it: Base is the last commit touching anything
+outside the specs root, so every finished receipt records an older Base by
+construction and reopening on a dirty tree failed all of them at once.
+The gate detects drift, not invention: a valid
 Base and Head pair costs one command and no verification run, so neither mode proves
 that the command was executed. Missing, stale, contradictory,
 placeholder, copied, failure, or zero-test evidence leaves the task unfinished.