@haposoft/cafekit 0.16.5 → 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.5-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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.16.5",
+  "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 });
   }
@@ -1832,6 +1842,57 @@ test('47. completed-set branch accepts committed receipts and blocks an edited o
   }
 });
 
+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; 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.
+  // 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 and unchanged.`);
+    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,11 +32,14 @@ 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 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.
+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,

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

@@ -208,6 +208,14 @@ 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}`]);

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 and unchanged; work elsewhere in the tree does not reopen it. 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 and unchanged.`,
+      `- 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,11 +32,14 @@ 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 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.
+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,