@haposoft/cafekit 0.16.6 → 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.6-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/package.json

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

@@ -1842,6 +1842,44 @@ 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

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);
@@ -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/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]);
 }
 
@@ -335,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');
@@ -404,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/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) {