@haposoft/cafekit 0.16.5 → 0.16.7

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.7-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.7",
   "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,95 @@ test('47. completed-set branch accepts committed receipts and blocks an edited o
   }
 });
 
+test('51. Receipt fields written as list items are accepted', () => {
+  // Every neighbouring section writes its fields as list items — the Verification Plan's
+  // own `- Command:` sits a few lines above — so continuing that house style inside the
+  // Receipt is the natural mistake. It used to fail verification_state, command,
+  // exit_result and command_identity at once, with a message telling the user to rewrite
+  // a Receipt whose content was already correct.
+  const bulleted = boundReceipt().map((line) => (
+    /^(Verification|Command|Exit|Base|Head):/.test(line) ? `- ${line}` : line
+  ));
+  assert.ok(bulleted.some((line) => line.startsWith('- Verification:')), 'the fixture must be bulleted');
+  const dir = makeWorkflowFixture(bulleted);
+  try {
+    clearCache();
+    assert.strictEqual(runHook({}, dir).stdout, '', 'a bulleted Receipt must be read, not rejected');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('52. the block names what to change, not just which check failed', () => {
+  // The same sentence used to answer every receipt failure, including the ones where
+  // the Receipt was present and one field simply could not be read.
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block');
+    assert.match(body.reason, /add a `Verification: PASS` line/, 'the fix must name the missing field');
+    assert.doesNotMatch(body.reason, /write a runtime-bound `## Receipt` with command output/,
+      'the generic instruction must not stand in for a specific one');
+  } 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

@@ -150,7 +150,8 @@ try {
     const lines = [`⚠️ Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
     for (const failure of checked.failures) {
       lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
-      lines.push(`  Fix: write a runtime-bound \`## Receipt\` with the planned command in \`specs/${failure.featureName}/${failure.taskPath}\`.`);
+      const hint = typeof RECEIPT.receiptFixHint === 'function' ? RECEIPT.receiptFixHint(failure.failures) : null;
+      lines.push(`  Fix in \`specs/${failure.featureName}/${failure.taskPath}\`: ${hint || 'write a runtime-bound `## Receipt` with the planned command'}.`);
     }
     emitBlock(lines.slice(0, 8).join('\n'));
     process.exit(0);
@@ -240,10 +241,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'
@@ -302,7 +303,7 @@ try {
     lines.push(taskPath === 'feature-receipt.md'
       ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
       : processWorkflow
-        ? `  Fix: write a runtime-bound \`## Receipt\` with command output in \`specs/${featureName}/${path.posix.basename(taskPath)}\`.`
+        ? `  Fix in \`specs/${featureName}/${path.posix.basename(taskPath)}\`: ${(typeof RECEIPT.receiptFixHint === 'function' && RECEIPT.receiptFixHint(fails)) || 'write a runtime-bound `## Receipt` with command output'}.`
         : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {

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

@@ -113,7 +113,10 @@ function hasNonEmptyFencedBlock(body) {
 
 function fieldValues(body, name) {
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const matcher = new RegExp(`^\\s*${escaped}\\s*:\\s*(.*?)\\s*$`, 'i');
+  // A leading list marker is accepted: every neighbouring section of a task file writes
+  // its fields as list items, so continuing that style inside the Receipt is the
+  // natural mistake rather than a malformed receipt.
+  const matcher = new RegExp(`^\\s*(?:[-*+]\\s+)?${escaped}\\s*:\\s*(.*?)\\s*$`, 'i');
   return String(body || '').split('\n').map((line) => line.match(matcher)).filter(Boolean).map((match) => match[1]);
 }
 
@@ -208,6 +211,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}`]);
@@ -327,6 +338,31 @@ function checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy)
   };
 }
 
+// The gate used to answer every receipt failure with the same sentence — write a
+// runtime-bound Receipt — which is the wrong instruction whenever the Receipt is
+// present and one field simply could not be read. Name what to change instead.
+const RECEIPT_FIX_HINTS = Object.freeze([
+  ['missing_receipt', 'add exactly one `## Receipt` section at the end of the file'],
+  ['task_status', 'the file needs exactly one `Status: done` line outside any fence'],
+  ['verification_state', 'add a `Verification: PASS` line'],
+  ['command', 'add a `Command:` line holding the exact command that was run'],
+  ['command_identity', 'the `Command:` line must match the Verification Plan command exactly'],
+  ['exit_result', 'add `Exit: 0`; a non-zero exit or a failure marker does not close a task'],
+  ['command_output', 'add a non-empty fenced block holding the real command output'],
+  ['placeholder', 'replace the placeholder values with real ones'],
+  ['provenance', 'add runtime-derived `Base:` and `Head:` lines matching the current runtime'],
+]);
+
+/**
+ * Turn receipt check codes into one instruction naming what to change.
+ */
+function receiptFixHint(failures) {
+  const codes = new Set(Array.isArray(failures) ? failures : []);
+  const hints = RECEIPT_FIX_HINTS.filter(([code]) => codes.has(code)).map(([, hint]) => hint);
+  if (hints.length === 0) return null;
+  return hints.length === 1 ? hints[0] : `${hints.slice(0, -1).join('; ')}; and ${hints[hints.length - 1]}`;
+}
+
 function workflowProofSignature(taskPath, proof) {
   const hash = crypto.createHash('sha256');
   hash.update('cafekit-workflow-proof-v1\0');
@@ -396,6 +432,7 @@ module.exports = {
   checkTaskReceipt,
   checkWorkflowReceiptSet,
   checkWorkflowTaskReceipt,
+  receiptFixHint,
   evidenceBody,
   readTaskProof,
   safeRead,

package/src/claude/scripts/workflow-policy.cjs

@@ -1884,6 +1884,18 @@ function flashState(taskRegistry = {}) {
     .map(([taskPath]) => taskPath);
 }
 
+// Every other section of a task file writes its fields as list items — the Verification
+// Plan's own `- Command:` sits a few lines above the Receipt — so continuing that house
+// style inside the Receipt is the natural mistake, and it used to fail five checks at
+// once with a message that pointed at the content instead of the dash. Accept either
+// form. The receipt body is cut to its own `## Receipt` section, so this cannot pick up
+// the Verification Plan's fields.
+const RECEIPT_FIELD_PREFIX = '\\s*(?:[-*+]\\s+)?';
+
+function receiptFieldPattern(name, tail = '\\s*:', flags = '') {
+  return new RegExp(`^${RECEIPT_FIELD_PREFIX}${name}${tail}`, flags);
+}
+
 function validateCanonicalReceipt(body, options = {}) {
   if (typeof body !== 'string') return ['verification_state'];
   const failures = [];
@@ -1900,15 +1912,15 @@ function validateCanonicalReceipt(body, options = {}) {
     addFailure('verification_state');
   }
   // Unambiguous verification state: must be Verification: PASS exactly
-  if (!/^\s*Verification:\s*PASS\s*$/m.test(body)) {
+  if (!receiptFieldPattern('Verification', '\\s*:\\s*PASS\\s*$', 'm').test(body)) {
     addFailure('verification_state');
   }
   // Command must be present with non-empty concrete value on same line, not placeholder
-  const cmdLine = body.split('\n').find((l) => /^\s*Command(?:\(s\))?\s*:/m.test(l)) || null;
-  if (!cmdLine || !/^\s*Command(?:\(s\))?\s*:[ \t]*\S/m.test(cmdLine)) {
+  const cmdLine = body.split('\n').find((l) => receiptFieldPattern('Command(?:\\(s\\))?', '\\s*:', 'm').test(l)) || null;
+  if (!cmdLine || !receiptFieldPattern('Command(?:\\(s\\))?', '\\s*:[ \\t]*\\S', 'm').test(cmdLine)) {
     addFailure('command');
   } else {
-    const m = cmdLine.match(/^\s*Command(?:\(s\))?\s*:[ \t]*(.*)$/m);
+    const m = cmdLine.match(receiptFieldPattern('Command(?:\\(s\\))?', '\\s*:[ \\t]*(.*)$', 'm'));
     const val = m ? m[1].trim() : '';
     if (isPlaceholderToken(val)) {
       addFailure('command');
@@ -1921,15 +1933,15 @@ function validateCanonicalReceipt(body, options = {}) {
   const exitValues = [];
   const resultValues = [];
   for (const line of lines) {
-    if (/^\s*Exit\s*:/i.test(line)) {
-      const m = line.match(/^\s*Exit\s*:\s*(.*)$/i);
+    if (receiptFieldPattern('Exit', '\\s*:', 'i').test(line)) {
+      const m = line.match(receiptFieldPattern('Exit', '\\s*:\\s*(.*)$', 'i'));
       exitValues.push(m ? m[1].trim() : '');
     } else if (/exit\s+code\s*[:=]/i.test(line)) {
       const m = line.match(/exit\s+code\s*[:=]\s*(.*)$/i);
       if (m) exitValues.push(m[1].trim());
     }
-    if (/^\s*Result\s*:/i.test(line)) {
-      const m = line.match(/^\s*Result\s*:\s*(.+?)\s*$/i);
+    if (receiptFieldPattern('Result', '\\s*:', 'i').test(line)) {
+      const m = line.match(receiptFieldPattern('Result', '\\s*:\\s*(.+?)\\s*$', 'i'));
       resultValues.push(m ? m[1].trim() : '');
     }
   }
@@ -1954,8 +1966,8 @@ function validateCanonicalReceipt(body, options = {}) {
   // Without expected values this validates schema only; it does not claim identity binding.
   const receiptLines = body.split('\n');
   const readField = (name) => receiptLines
-    .filter((line) => new RegExp(`^\\s*${name}\\s*:`, 'i').test(line))
-    .map((line) => line.replace(new RegExp(`^\\s*${name}\\s*:\\s*`, 'i'), '').trim());
+    .filter((line) => receiptFieldPattern(name, '\\s*:', 'i').test(line))
+    .map((line) => line.replace(receiptFieldPattern(name, '\\s*:\\s*', 'i'), '').trim());
   const baseValues = readField('Base');
   const headValues = readField('Head');
   const baseShaValues = readField('base_sha');

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

@@ -131,9 +131,10 @@ Tests: 3 passed, 3 total
 ```
 ````
 
-The receipt is invalid when it has a placeholder, missing output fence, zero
-executed tests where tests are required, a failure marker, nonzero exit, stale
-Base/Head, or a bare PASS claim without the command output.
+Each field is its own line; a leading `- ` reads identically. The receipt is
+invalid when it has a placeholder, missing output fence, zero executed tests
+where tests are required, a failure marker, nonzero exit, stale Base/Head, or a
+bare PASS claim without the command output.
 
 ## EARS sentence patterns
 

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

@@ -99,6 +99,10 @@ function checkFeatureReceipt(featureDir, runtimeContext) {
   if (!policy) return { failures: ['shared_validator'], status: 'missing' };
   return receiptHelper().checkFeatureReceipt(featureDir, runtimeContext, policy);
 }
+function receiptFixHint(failures) {
+  const helper = receiptHelper();
+  return typeof helper.receiptFixHint === 'function' ? helper.receiptFixHint(failures) : null;
+}
 function readTaskProof(featureDir, taskPath) {
   return receiptHelper().readTaskProof(featureDir, taskPath, getSharedPolicy() || {});
 }
@@ -115,6 +119,7 @@ module.exports = {
   loadSharedPolicy,
   loadSharedReceipt,
   readTaskProof,
+  receiptFixHint,
   safeTaskFile,
   validateCanonicalReceipt,
 };

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

@@ -16,6 +16,7 @@ const {
   checkWorkflowReceiptDetails,
   checkWorkflowReceiptSet,
   loadSharedPolicy,
+  receiptFixHint,
 } = require('./lib/spec-receipt.cjs');
 const { taskStatusMap } = require('./lib/spec-utils.cjs');
 const FINAL_STATE = require('./completion-authority-check.cjs');
@@ -75,7 +76,7 @@ try {
     const lines = [`Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
     for (const failure of checked.failures) {
       lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
-      lines.push(`  Write a runtime-bound \`## Receipt\` with the planned command in \`specs/${failure.featureName}/${failure.taskPath}\`.`);
+      lines.push(`  In \`specs/${failure.featureName}/${failure.taskPath}\`: ${receiptFixHint(failure.failures) || 'write a runtime-bound `## Receipt` with the planned command'}.`);
     }
     emitBlock(lines.slice(0, 8).join('\n'));
     process.exit(0);
@@ -228,7 +229,7 @@ try {
     lines.push(result.taskPath === 'feature-receipt.md'
       ? `  Run final integration proof, then write \`specs/${active.featureName}/feature-receipt.md\`.`
       : processWorkflow
-        ? `  Write a runtime-bound \`## Receipt\` with command output in \`specs/${active.featureName}/${path.posix.basename(result.taskPath)}\`.`
+        ? `  In \`specs/${active.featureName}/${path.posix.basename(result.taskPath)}\`: ${receiptFixHint(result.failures) || 'write a runtime-bound `## Receipt` with command output'}.`
         : `  Write canonical proof to \`specs/${active.featureName}/receipts/${path.posix.basename(result.taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {

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,