@haposoft/cafekit 0.16.4 → 0.16.6

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.4-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.16.6-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

@@ -1782,7 +1782,7 @@ test('Claude and Codex fail closed consistently for malformed cwd payloads', ()
   });
 });
 
-test('Codex emits the required decision for all six receipt states', () => {
+test('Codex emits the required decision for every receipt state', () => {
   // Codex owns no checker of its own: both wrappers in .codex/hooks/lib forward to
   // the shared module, so the two receipt modes arrive by inheritance. This case is
   // the regression lock on that inheritance. Each state asserts the decision Codex
@@ -1847,12 +1847,19 @@ test('Codex emits the required decision for all six receipt states', () => {
       return failures.length === 0 ? 'accept' : 'block';
     };
 
-    // 1. untracked task file — never committed, so the binding stays.
-    assert.equal(decide(), 'block', 'an untracked task file must keep full binding');
+    // 1. untracked task file — no copy in HEAD, so there is no baseline to drift
+    //    from. Committing a packet is the user's choice and a project that
+    //    gitignores its specs root cannot do it at all, so binding here only failed
+    //    the receipt permanently once the source moved on. The structural checks
+    //    still run; state 6 below is the state that binds.
+    assert.equal(decide(), 'accept', 'an uncommitted task file must not be bound');
+    assert.equal(sharedDecides(), 'accept', 'the shared checker must agree');
 
-    // 2. staged but not committed — `git add` alone must not read as committed.
+    // 2. staged but not committed — `git add` puts the file in the index, not in
+    //    HEAD, so it reads exactly like state 1.
     git('add', '-A');
-    assert.equal(decide(), 'block', 'a staged-only task file must keep full binding');
+    assert.equal(decide(), 'accept', 'staging does not create a committed baseline');
+    assert.equal(sharedDecides(), 'accept', 'the shared checker must agree');
 
     // 3. committed on a clean tree — the one accepting state.
     git('commit', '-qm', 'receipt and source');
@@ -1866,13 +1873,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.16.4",
+  "version": "0.16.6",
   "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__/spec-gate.test.js

@@ -1317,14 +1317,18 @@ test('32. process-v3 requires Receipt heading and runtime-bound provenance', ()
     fs.rmSync(legacyHeading, { recursive: true, force: true });
   }
 
-  const stale = makeWorkflowFixture([
-    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
-    `Base: ${VALID_BASE}`, `Head: ${VALID_BASE}`, '```text', 'pass', '```',
-  ]);
+  // Base and Head are compared against the runtime for a task file that has a copy in
+  // HEAD and no longer matches it. That is the state a stale pair has to reach now:
+  // committing a packet is the user's choice, so an uncommitted one is not bound.
+  const stale = makeWorkflowFixture(boundReceipt());
   try {
+    commitAll(stale, 'receipt');
+    const taskFile = path.join(stale, 'specs', FEATURE, 'task-01-demo.md');
+    fs.writeFileSync(taskFile, fs.readFileSync(taskFile, 'utf8')
+      .replace(/^Head: .*$/m, `Head: ${VALID_BASE}`));
     clearCache();
     const body = parseBlock(runHook({}, stale).stdout);
-    assert.ok(body, 'stale process-v3 provenance should block');
+    assert.ok(body, 'stale process-v3 provenance should block once the packet is committed');
     assert.match(body.reason, /provenance/);
   } finally {
     fs.rmSync(stale, { recursive: true, force: true });
@@ -1534,13 +1538,15 @@ test('37. committed receipt on a clean tree survives later commits', () => {
   }
 });
 
-test('38. untracked task file requires binding', () => {
+test('38. an uncommitted task file is not bound to live Base and Head', () => {
+  // Contract change. Committing a packet is the user's choice, and a project that
+  // gitignores its specs root cannot do it at all. A task file with no copy in HEAD
+  // has no baseline to drift from, so binding it only failed it permanently once the
+  // source moved on. Case 50 proves the structural checks still run on such a file.
   const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
   try {
     clearCache();
-    const body = parseBlock(runHook({}, dir).stdout);
-    assert.ok(body && body.decision === 'block', 'an untracked task file must keep full binding');
-    assert.match(body.reason, /\bprovenance\b/);
+    assert.strictEqual(runHook({}, dir).stdout, '', 'an uncommitted task file must not be bound');
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -1560,15 +1566,19 @@ test('38b. the same stale receipt is accepted once committed on a clean tree', (
   }
 });
 
-test('39. staged but uncommitted task file requires binding', () => {
+test('39. a staged task file reads the same as an uncommitted one', () => {
+  // Staging puts the file in the index, not in HEAD, so there is still no committed
+  // baseline to compare against and the selector treats it exactly like case 38.
+  // Case 40 covers the state that does bind: committed, then modified.
   const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
   try {
     const add = spawnSync('git', ['-C', dir, 'add', '-A'], { encoding: 'utf8' });
     assert.strictEqual(add.status, 0, add.stderr);
+    const inHead = spawnSync('git', ['-C', dir, 'ls-tree', '--name-only', 'HEAD', '--',
+      `specs/${FEATURE}/task-01-demo.md`], { encoding: 'utf8' });
+    assert.strictEqual(inHead.stdout.trim(), '', 'staging must not put the file in HEAD');
     clearCache();
-    const body = parseBlock(runHook({}, dir).stdout);
-    assert.ok(body && body.decision === 'block', 'git add alone must not grant structure-only');
-    assert.match(body.reason, /\bprovenance\b/);
+    assert.strictEqual(runHook({}, dir).stdout, '', 'a staged task file has no committed baseline either');
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -1621,43 +1631,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 +1799,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,18 +1816,83 @@ 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 });
+  }
+});
+
+test('49. an unversioned specs root does not keep every receipt bound', () => {
+  // Committing specs/ is the user's choice, not the tool's requirement. Without a
+  // committed copy of the task file there is no baseline, so the selector used to keep
+  // full binding — which fails every receipt permanently after the first source edit.
+  // A project that has chosen not to version its packets has no drift to detect.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'app.js'), 'module.exports = 1;\n');
+    for (const args of [['add', 'src'], ['commit', '-qm', 'source only']]) {
+      const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+      assert.strictEqual(result.status, 0, result.stderr);
+    }
+    const tracked = spawnSync('git', ['-C', dir, 'ls-files', '--', 'specs'], { encoding: 'utf8' });
+    assert.strictEqual(tracked.stdout.trim(), '', 'the specs root must be untracked for this case to mean anything');
+    fs.writeFileSync(path.join(dir, 'src', 'app.js'), 'module.exports = 2;\n');
+    clearCache();
+    assert.strictEqual(runHook({}, dir).stdout, '', 'an unversioned specs root must not stay bound forever');
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
 
+test('50. an uncommitted task file is still checked, only not against Base and Head', () => {
+  // Dropping the binding must not stop the gate reading the packet. A gitignored or
+  // simply uncommitted specs root keeps every structural check: a failing exit, a
+  // placeholder, an empty output block, and a command that does not match the
+  // Verification Plan all still block.
+  const cases = [
+    [['## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 1',
+      `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`, '```text', '$ node --test', 'fail: 1', '```'], /exit_result/],
+    [['## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`, '```text', '```'], /command_output/],
+    [['## Receipt', '', 'Verification: PASS', 'Command: pnpm test', 'Exit: 0',
+      `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`, '```text', '$ pnpm test', 'pass', '```'], /command_identity/],
+  ];
+  for (const [receipt, expected] of cases) {
+    const dir = makeWorkflowFixture(receipt);
+    try {
+      const tracked = spawnSync('git', ['-C', dir, 'ls-files', '--', 'specs'], { encoding: 'utf8' });
+      assert.strictEqual(tracked.stdout.trim(), '', 'the packet must be uncommitted for this case to mean anything');
+      clearCache();
+      const body = parseBlock(runHook({}, dir).stdout);
+      assert.ok(body && body.decision === 'block', `an uncommitted packet must still be checked: ${expected}`);
+      assert.match(body.reason, expected);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
 test('48. the gate\'s own runtime state does not defeat structure mode', () => {
   // The gate writes its cache under .claude/hooks/.logs on every Stop. If that
   // write counted as a dirty tree, a project tracking its runtime directory could

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

@@ -240,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 has a copy in HEAD that it no longer
+  // matches; committed-and-unchanged and never-committed are both checked on
+  // structure alone, and work elsewhere in the tree never reopens a receipt.
+  // 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 only while a committed task file no longer matches its committed bytes.`);
   } 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

@@ -32,9 +32,15 @@ Set `Status: done` only after the inline Receipt passes the
 `Verification: PASS`, runtime-derived Base and Head values, and a non-empty
 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
+A done task is bound to live Base and Head only while its own task file has a copy in
+`HEAD` that its current bytes no longer match. A file that is committed and unchanged,
+and a file that was never committed at all, are both validated on structure alone: the
+first has a baseline it still matches, the second has no baseline to drift from, and
+committing a packet is the user's choice that a gitignored specs root removes entirely.
+Work elsewhere in the tree never reopens a receipt, because Base is the last commit
+touching anything outside the specs root, so every finished receipt records an older
+Base by construction. Every structural check runs in all cases.
+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;
@@ -204,28 +208,18 @@ function receiptBindingMode(featureDir, taskPath, taskBytes, runtimeContext) {
   const specsRelative = toPosix(path.relative(root, specsRoot));
   const escapes = (value) => !value || value === '..' || value.startsWith('../') || path.isAbsolute(value);
   if (escapes(taskRelative) || escapes(specsRelative)) return 'binding';
+  // Whether the packet is committed at all is the user's choice, and for a project
+  // that gitignores its specs root it is not even available. A task file with no copy
+  // in HEAD therefore has no baseline to drift from, and binding it to live Base/Head
+  // only fails it permanently once the source moves on. Its structural checks still
+  // run in full. A git failure is not the same thing and stays fail-safe.
+  const inHead = tryGitBytes(root, ['ls-tree', '-z', '--name-only', 'HEAD', '--', taskRelative]);
+  if (inHead === null) return 'binding';
+  if (inHead.length === 0) return 'structure';
   // `--filters` applies the same smudge/eol conversion the worktree copy has,
   // 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/skills/specs/SKILL.md

@@ -127,8 +127,8 @@ it does not invent product approval, review independence, or runtime coverage.
 The shared workflow resolver recognizes only a regular `plan.md` plus one or more
 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
+done Receipt, binding Base and Head to the live runtime only while the task file has a
+committed copy it no longer matches; work elsewhere in the tree never reopens 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/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 only while a committed task file no longer matches its committed bytes.`,
       '- Hooks revalidate receipt bytes but never grant approval.'
     );
   } else {

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

@@ -32,9 +32,15 @@ Set `Status: done` only after the inline Receipt passes the
 `Verification: PASS`, runtime-derived Base and Head values, and a non-empty
 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
+A done task is bound to live Base and Head only while its own task file has a copy in
+`HEAD` that its current bytes no longer match. A file that is committed and unchanged,
+and a file that was never committed at all, are both validated on structure alone: the
+first has a baseline it still matches, the second has no baseline to drift from, and
+committing a packet is the user's choice that a gitignored specs root removes entirely.
+Work elsewhere in the tree never reopens a receipt, because Base is the last commit
+touching anything outside the specs root, so every finished receipt records an older
+Base by construction. Every structural check runs in all cases.
+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.