@haposoft/cafekit 0.16.0 → 0.16.1

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

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 
 function logCrash(error) {
   try {
@@ -49,7 +50,8 @@ try {
   const stdin = fs.readFileSync(0, 'utf8').trim();
   if (!stdin) process.exit(0);
 
-  const payload = JSON.parse(stdin);
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload = normalizeHookPayload(JSON.parse(stdin));
   const cwd     = payload.cwd || process.cwd();
 
   let POLICY;
@@ -69,7 +71,7 @@ try {
   // Read runtime configuration if exists
   let runtime = {};
   try {
-    const p = path.join(cwd, '.claude', 'runtime.json');
+    const p = runtimePath(cwd, 'runtime.json');
     if (fs.existsSync(p)) runtime = JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch { /* ignore */ }
 
@@ -77,7 +79,9 @@ try {
   // (The Stop completion gate has its own toggle: spec.completion_gate.)
   if (runtime.spec && runtime.spec.tollgate === false) process.exit(0);
 
-  const baseDir   = process.env.PROJECT_ROOT || cwd;
+  // Same rule as spec-gate: an installed hook trusts its own location over the environment.
+  const installedRoot = path.basename(path.resolve(__dirname, '..')).startsWith('.') ? path.resolve(__dirname, '..', '..') : null;
+  const baseDir   = installedRoot || process.env.PROJECT_ROOT || cwd;
   const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
   const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
   const resolveWorkflow = typeof RESOLVER.resolveWorkflowCandidate === 'function'
@@ -222,11 +226,11 @@ 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 revalidates every task currently marked done.`);
+    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.`);
   } 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)'}.`);
-    lines.push(`- Validate with \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
+    lines.push(`- Validate with \`node ${runtimeDirName()}/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
   }
   lines.push('');
 

package/src/claude/hooks/state.cjs

@@ -12,7 +12,7 @@
  *   Stop          → persist full session state and archive
  *   SubagentStop  → append agent completion note to current state
  *
- * Storage: .claude/session-state/latest.md (+ archive/)
+ * Storage: <runtime>/session-state/latest.md (+ archive/)
  * Exit: 0 always (fail-open)
  */
 
@@ -23,6 +23,7 @@ try {
   const crypto = require('crypto');
   const { execSync } = require('child_process');
   const { parseTranscript } = require('./lib/parser.cjs');
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
 
   const EXPIRY_DAYS = 7;
   const MAX_ARCHIVES = 5;
@@ -32,8 +33,8 @@ try {
 
   function stateDir(cwd) {
     try {
-      const local = path.join(cwd, '.claude', 'session-state');
-      if (fs.existsSync(path.join(cwd, '.claude'))) {
+      const local = runtimePath(cwd, 'session-state');
+      if (fs.existsSync(runtimeDir(cwd))) {
         if (!fs.existsSync(local)) fs.mkdirSync(local, { recursive: true });
         return local;
       }
@@ -224,7 +225,8 @@ try {
     const stdin = fs.readFileSync(0, 'utf8').trim();
     if (!stdin) process.exit(0);
 
-    const data = JSON.parse(stdin);
+    const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+    const data = normalizeHookPayload(JSON.parse(stdin));
     const event = data.hook_event_name || '';
     const cwd = data.cwd || process.cwd();
     const dir = stateDir(cwd);

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -21,7 +21,7 @@
  *   1. fail-open when spec-scaffold.cjs is absent — you cannot force a tool that
  *      is not installed, so a hook shipped without its script must not deadlock.
  *   2. actionable block message — prints the exact scaffold command to run.
- *   3. escape hatch — "spec": { "scaffold_guard": false } in .claude/runtime.json.
+ *   3. escape hatch — "spec": { "scaffold_guard": false } in <runtime>/runtime.json.
  *
  * Exit: 0 = allow, 2 = block.
  */
@@ -29,11 +29,33 @@
 try {
   const fs   = require('fs');
   const path = require('path');
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
+
+/**
+ * Deny the call with a reason every host can read.
+ *
+ * The reason is the JSON `permissionDecisionReason`, which Claude Code reads natively and
+ * grok honours "regardless of exit code"; the same text also goes to stderr, because on
+ * an exit-2 denial that is the channel Claude Code feeds back, and grok reads only the
+ * first stderr line. Exit 2 stays so a host that reads neither still blocks.
+ */
+function denyWithReason(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  }) + '\n');
+  process.stderr.write(reason + '\n');
+  process.exit(2);
+}
 
   const stdin = fs.readFileSync(0, 'utf8').trim();
   if (!stdin) process.exit(0);
 
-  const data      = JSON.parse(stdin);
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const data      = normalizeHookPayload(JSON.parse(stdin));
   const toolName  = data.tool_name  || '';
   const toolInput = data.tool_input || {};
   const cwd       = data.cwd        || process.cwd();
@@ -50,17 +72,17 @@ try {
   const isTaskFile = /(^|\/)specs\/[^/]+\/tasks\/task-[^/]+\.md$/.test(norm);
   if (!isTaskFile) process.exit(0);
 
-  // Valve 3: explicit escape hatch via .claude/runtime.json (fail-closed: a
+  // Valve 3: explicit escape hatch via <runtime>/runtime.json (fail-closed: a
   // missing/broken runtime.json keeps the guard ON).
   let runtime = {};
   try {
-    const rp = path.join(cwd, '.claude', 'runtime.json');
+    const rp = runtimePath(cwd, 'runtime.json');
     if (fs.existsSync(rp)) runtime = JSON.parse(fs.readFileSync(rp, 'utf8'));
   } catch { /* malformed runtime.json -> keep guard on */ }
   if (runtime.spec && runtime.spec.scaffold_guard === false) process.exit(0);
 
   // Valve 1: fail-open if the scaffold script is not installed next to this hook
-  // (hook lives in .claude/hooks/, script in .claude/scripts/). Forcing a tool
+  // (hook lives in <runtime>/hooks/, script in <runtime>/scripts/). Forcing a tool
   // that does not exist would deadlock task creation.
   const scaffold = path.join(__dirname, '..', 'scripts', 'spec-scaffold.cjs');
   if (!fs.existsSync(scaffold)) process.exit(0);
@@ -71,14 +93,13 @@ try {
   // simply disables the guard itself. The hatch stays functional for humans.
   const m = norm.match(/(^|\/)specs\/([^/]+)\/tasks\//);
   const feature = m ? m[2] : '<feature>';
-  console.log(
+  denyWithReason(
     `TASK SCAFFOLD REQUIRED: task files must be generated, not hand-written.\n` +
     `Blocked Write: ${filePath}\n\n` +
     `Generate the stub(s), then Edit-fill the {{...}} placeholders:\n` +
-    `  node .claude/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
+    `  node ${runtimeDirName()}/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
     `Then use Edit (not Write) on each tasks/task-*.md stub.`
   );
-  process.exit(2);
 
 } catch (e) {
   // Never let a hook crash block the user — log and fail-open.

package/src/claude/hooks/usage.cjs

@@ -17,7 +17,7 @@
  * Features:
  * - Cross-platform credential retrieval (macOS Keychain, file-based)
  * - Throttled API calls: 1 min (prompt) / 5 min (tool use)
- * - Disable: set "usage": { "enabled": false } in .claude/runtime.json
+ * - Disable: set "usage": { "enabled": false } in <runtime>/runtime.json
  */
 
 // Crash wrapper
@@ -27,11 +27,12 @@ try {
   const os = require("os");
   const { execSync } = require("child_process");
 
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
     try {
-      const runtimePath = path.join(cwd, '.claude', 'runtime.json');
-      if (fs.existsSync(runtimePath)) {
-        return JSON.parse(fs.readFileSync(runtimePath, 'utf-8'));
+      const rp = runtimePath(cwd, 'runtime.json');
+      if (fs.existsSync(rp)) {
+        return JSON.parse(fs.readFileSync(rp, 'utf-8'));
       }
     } catch { /* fail-open */ }
     return {};

package/src/claude/migration-manifest.json

@@ -148,6 +148,8 @@
       "hooks/lib/context.cjs",
       "hooks/lib/detect.cjs",
       "hooks/lib/hook-state-dir.cjs",
+      "hooks/lib/runtime-dir.cjs",
+      "hooks/lib/hook-payload.cjs",
       "hooks/lib/privacy-command-analysis.cjs",
       "hooks/lib/secret-keywords.cjs",
       "hooks/lib/runtime-path-safety.cjs"

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

@@ -30,7 +30,13 @@ state transition.
 Set `Status: done` only after the inline Receipt passes the
 `validateCanonicalReceipt` contract: exact command, `Exit: 0`,
 `Verification: PASS`, runtime-derived Base and Head values, and a non-empty
-fenced block of current command output. Missing, stale, contradictory,
+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
+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.
 
 Synchronization never fabricates commands, output, timestamps, completed

package/src/claude/rules/workflow.md

@@ -56,6 +56,8 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 - A canonical Receipt contains the exact command, `Exit: 0`,
   `Verification: PASS`, runtime-derived Base and Head values, and non-empty
   fenced current output. Never invent, copy, or infer missing proof.
+- When the binding to Base and Head applies, and what the gate does and does not
+  detect, are stated once in `state-sync.md`.
 - Re-read each edited task and reconcile its plan row, dependencies, acceptance
   mapping, status, and receipt without rewriting unrelated bytes.
 - Run docs checkpoint when a completed task affects public docs or architecture docs.

package/src/claude/scripts/provenance.cjs

@@ -149,15 +149,21 @@ function parseStatus(bytes) {
   return entries;
 }
 
+// Generated runtime state, not source evidence. Shared with the receipt binding
+// selector so the gate's own cache writes cannot be read as a dirty worktree.
+const RUNTIME_STATE_ROOTS = Object.freeze([
+  '.git', 'node_modules',
+  '.claude/hooks/.logs', '.codex/hooks/.logs', '.omp/hooks/.logs',
+  '.claude/.logs', '.codex/.logs', '.omp/.logs',
+  '.claude/runtime.json', '.codex/runtime.json', '.omp/runtime.json',
+]);
+
 function excluded(root, absolute, specsRoot) {
   const relative = path.relative(root, absolute).split(path.sep).join('/');
   const specsRelative = path.relative(root, specsRoot);
   // These roots are generated runtime state, not source evidence. The selected
   // canonical specs root is excluded above to avoid receipt/state recursion.
-  const roots = [
-    '.git', 'node_modules', '.claude/hooks/.logs', '.codex/hooks/.logs',
-    '.claude/.logs', '.codex/.logs', '.claude/runtime.json', '.codex/runtime.json',
-  ];
+  const roots = RUNTIME_STATE_ROOTS;
   if (relative === specsRelative || relative.startsWith(`${specsRelative}/`)) return true;
   return roots.some((entry) => relative === entry || relative.startsWith(`${entry}/`));
 }
@@ -315,6 +321,7 @@ function runCli(argv = process.argv.slice(2)) {
 if (require.main === module) process.exitCode = runCli();
 
 module.exports = {
+  RUNTIME_STATE_ROOTS,
   CONTEXT_SCHEMA_VERSION,
   PROVENANCE_MODE,
   ProvenanceError,

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

@@ -3,7 +3,9 @@
 const crypto = require('crypto');
 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',
@@ -177,11 +179,67 @@ function identity(body) {
   return crypto.createHash('sha256').update(JSON.stringify({ fields, artifacts })).digest('hex');
 }
 
-function canonicalFailures(body, task, runtimeContext, policy) {
+function tryGitBytes(root, args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+  if (result.error || result.status !== 0) return null;
+  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.
+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;
+  if (!root || !specsRoot || !Buffer.isBuffer(taskBytes)) return 'binding';
+  let canonicalFeature;
+  try { canonicalFeature = fs.realpathSync(featureDir); } catch { return 'binding'; }
+  const toPosix = (value) => value.split(path.sep).join('/');
+  const taskRelative = toPosix(path.relative(root, path.join(canonicalFeature, taskPath)));
+  const specsRelative = toPosix(path.relative(root, specsRoot));
+  const escapes = (value) => !value || value === '..' || value.startsWith('../') || path.isAbsolute(value);
+  if (escapes(taskRelative) || escapes(specsRelative)) return 'binding';
+  // `--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';
+}
+
+function canonicalFailures(body, task, runtimeContext, policy, { bindProvenance = true } = {}) {
   if (!policy || typeof policy.validateCanonicalReceipt !== 'function') return ['validator_unavailable'];
   const options = typeof policy.receiptValidatorOptions === 'function'
     ? policy.receiptValidatorOptions(task || {}, { runtimeContext, requireProvenanceBinding: true })
     : { requireProvenanceBinding: true };
+  // Structure-only mode drops the live Base/Head comparison and nothing else.
+  // It is granted only while a trusted artifact root survived, because
+  // withholding the runtime context would also silence artifact byte checks.
+  if (!bindProvenance && typeof options.artifactRoot === 'string' && options.artifactRoot.trim() !== '') {
+    return policy.validateCanonicalReceipt(body, { ...options, expectedProvenance: null, requireProvenanceBinding: false });
+  }
   return policy.validateCanonicalReceipt(body, options);
 }
 
@@ -261,12 +319,15 @@ function checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy)
     const options = typeof policy?.receiptValidatorOptions === 'function'
       ? policy.receiptValidatorOptions({}, { runtimeContext, requireProvenanceBinding: true })
       : { requireProvenanceBinding: true };
-    failures.push(...canonicalFailures(canonicalBody, {}, runtimeContext, policy));
-    failures.push(...canonicalFailures(body, {}, runtimeContext, policy)
+    const requested = receiptBindingMode(featureDir, taskPath, taskFile.bytes, runtimeContext);
+    const artifactRootAvailable = typeof options.artifactRoot === 'string' && options.artifactRoot.trim() !== '';
+    const bindProvenance = !(requested === 'structure' && artifactRootAvailable);
+    failures.push(...canonicalFailures(canonicalBody, {}, runtimeContext, policy, { bindProvenance }));
+    failures.push(...canonicalFailures(body, {}, runtimeContext, policy, { bindProvenance })
       .filter((failure) => ['placeholder', 'verification_state', 'exit_result'].includes(failure)));
     failures.push(...workflowCommandFailures(taskText, canonicalBody));
     if (!hasNonEmptyFencedBlock(body)) failures.push('command_output');
-    if (!options.expectedProvenance) failures.push('provenance');
+    if (bindProvenance && !options.expectedProvenance) failures.push('provenance');
   }
   return {
     status: failures.length === 0 ? 'ok' : 'invalid',

package/src/claude/skills/specs/SKILL.md

@@ -124,17 +124,16 @@ it does not invent product approval, review independence, or runtime coverage.
 
 ## Machine boundary
 
-The shared workflow resolver recognizes only a regular `plan.md` plus one or
-more regular flat `task-*.md` files inside one direct feature directory. The
-Stop gate revalidates every done task's inline Receipt and provenance. The old
-task-scaffold guard remains limited to the older nested layout; flat v3 tasks
-do not invoke that kernel path.
-
-The resolver projects exact `Status:` values; it does not infer blockers from prose.
-
-These checks are a final safety net, not a substitute for C1-C3 judgment. Do
-not add a new schema, approval field, readiness bit, or review state to make the
-Markdown look more authoritative.
+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
+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,
+not a substitute for C1-C3 judgment. Do not add a new schema, approval field,
+readiness bit, or review state to make the Markdown look more authoritative.
 
 ## Legacy compatibility
 

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 revalidates every task currently marked done.`,
+      `- 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.`,
       '- Hooks revalidate receipt bytes but never grant approval.'
     );
   } else {

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

@@ -30,7 +30,13 @@ state transition.
 Set `Status: done` only after the inline Receipt passes the
 `validateCanonicalReceipt` contract: exact command, `Exit: 0`,
 `Verification: PASS`, runtime-derived Base and Head values, and a non-empty
-fenced block of current command output. Missing, stale, contradictory,
+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
+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.
 
 Synchronization never fabricates commands, output, timestamps, completed