@haposoft/cafekit 0.16.4 → 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.4-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

@@ -1866,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/package.json

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