@haposoft/cafekit 0.16.0-rc.2 → 0.16.0-rc.4

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

@@ -5,59 +5,171 @@
  * Stop Hook — spec-gate.cjs
  * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
  *
- * Blocks turn end when *newly-done* tasks lack a verification receipt.
+ * Blocks turn end when any done task lacks a verification receipt.
  * Block contract (exit 0 + stdout): {"decision":"block","reason":"..."}.
  *
- * Safety: stop_hook_active loop guard; runtime.spec.completion_gate=false
- * escape hatch (missing key → ON); cache is optimization only - every
- * done transition is validated even on first run / empty cache; crash → fail-open + hooks/.logs/hook-log.jsonl. Exit: 0 always.
+ * Safety: stop_hook_active loop guard; no worker-writable completion-gate
+ * bypass exists; cache is optimization only - every
+ * done transition is validated even on first run / empty cache; crash → controlled block + hooks/.logs/hook-log.jsonl. Exit: 0 always.
  */
 
+const fs = require('fs');
+const path = require('path');
+
+function projectRoot(payload = {}) {
+  const configured = typeof process.env.CLAUDE_PROJECT_DIR === 'string'
+    ? process.env.CLAUDE_PROJECT_DIR.trim()
+    : '';
+  if (configured) {
+    try { return fs.realpathSync(path.resolve(configured)); } catch { /* continue */ }
+  }
+
+  const installedRoot = path.resolve(__dirname, '..', '..');
+  const installedHook = path.join(installedRoot, '.claude', 'hooks', path.basename(__filename));
+  if (fs.existsSync(installedHook)) return installedRoot;
+
+  const sourceFixture = typeof process.env.PROJECT_ROOT === 'string'
+    ? process.env.PROJECT_ROOT.trim()
+    : '';
+  if (sourceFixture) {
+    try { return fs.realpathSync(path.resolve(sourceFixture)); } catch { /* continue */ }
+  }
+
+  const legacy = typeof payload.cwd === 'string' ? payload.cwd.trim() : '';
+  if (legacy) {
+    try { return fs.realpathSync(path.resolve(legacy)); } catch { /* continue */ }
+  }
+  try { return fs.realpathSync(process.cwd()); } catch { return path.resolve(process.cwd()); }
+}
+
+function logCrash(error) {
+  try {
+    const d = path.join(__dirname, '.logs');
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(
+      path.join(d, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'spec-gate', status: 'crash', error: error.message }) + '\n'
+    );
+  } catch (_) {}
+}
+
+function emitBlock(reason) {
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+}
+
+function sessionIdentity(payload) {
+  const candidates = [
+    payload && payload.session_id,
+    payload && payload.sessionId,
+    payload && payload.sessionID,
+    payload && payload.session && payload.session.id,
+  ];
+  return candidates.find((value) => typeof value === 'string' && value.trim() !== '') || null;
+}
+
 try {
-  const fs   = require('fs');
-  const path = require('path');
   const policyPath = path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs');
-  const POLICY = require(policyPath);
 
   const stdin = fs.readFileSync(0, 'utf8').trim();
-  if (!stdin) process.exit(0);
+  if (!stdin) throw new Error('hook payload is empty');
 
   const payload = JSON.parse(stdin);
-  const cwd     = payload.cwd || process.cwd();
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('hook payload must be a JSON object');
+  }
 
   // Never re-block a continuation caused by our own block (infinite-loop guard).
   if (payload.stop_hook_active === true) process.exit(0);
 
+  let POLICY;
+  let RESOLVER;
+  let RECEIPT;
+  let FINAL_STATE;
+  try {
+    POLICY = require(policyPath);
+    RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
+    RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
+    FINAL_STATE = require('./completion-authority-check.cjs');
+    if (typeof POLICY.validateCanonicalReceipt !== 'function'
+      || typeof POLICY.completionDecisionForSpec !== 'function'
+      || typeof RECEIPT.checkTaskReceipt !== 'function'
+      || typeof FINAL_STATE.evaluateCloseout !== 'function') {
+      throw new Error('shared workflow policy lacks completion authority functions');
+    }
+  } catch (error) {
+    logCrash(error);
+    emitBlock(`Completion gate unavailable: shared workflow policy could not be loaded (${error.message}). Repair ${policyPath} before completing tasks.`);
+    process.exit(0);
+  }
+
+  const cwd     = projectRoot(payload);
+
   // Missing/malformed runtime.json keeps the gate ON (fail-closed, valve 3 style).
   let runtime = {};
   try {
     const rp = path.join(cwd, '.claude', 'runtime.json');
     if (fs.existsSync(rp)) runtime = JSON.parse(fs.readFileSync(rp, 'utf8'));
   } catch { /* gate stays on */ }
-  if (runtime.spec && runtime.spec.completion_gate === false) process.exit(0);
-
-  // Active-spec discovery — same rules as spec-state.cjs.
-  const baseDir   = process.env.PROJECT_ROOT || cwd;
-  const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
-  if (!fs.existsSync(specsPath)) process.exit(0);
-
-  let activeSpec = null;
-  let featureName = null;
-  for (const entry of fs.readdirSync(specsPath, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const specFile = path.join(specsPath, entry.name, 'spec.json');
-    if (!fs.existsSync(specFile)) continue;
-    try {
-      const specData = JSON.parse(fs.readFileSync(specFile, 'utf8'));
-      if (specData.status === 'in_progress' || specData.status === 'in-progress') {
-        activeSpec = specData;
-        featureName = entry.name;
-        break;
-      }
-    } catch { /* skip bad JSON */ }
-  }
-  if (!activeSpec) process.exit(0);
+  // Active-spec discovery via shared resolver — explicit target if present, else fail on ambiguity.
+  const baseDir   = cwd;
+  const resolved = FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
+  if (!resolved) process.exit(0);
+  if (resolved.error === 'multiple_active' || resolved.error === 'multiple_persisted') {
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: `Completion gate: multiple active specs detected (${resolved.candidates.join(', ')}). Provide explicit feature target or resolve ambiguity before completing tasks. Candidates: ${resolved.candidates.join(', ')}`
+    }) + '\n');
+    process.exit(0);
+  }
+  if (resolved.error === 'invalid_specs') {
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: `Completion gate: invalid spec JSON detected (${resolved.candidates.join(', ')}): ${resolved.reason}. Fix or remove malformed spec.json before completing tasks.`
+    }) + '\n');
+    process.exit(0);
+  }
+  if (resolved.error === 'explicit_not_found' || resolved.error === 'explicit_malformed') {
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: `Completion gate: explicit spec target invalid (${resolved.error}): ${resolved.reason || resolved.explicitFeature || resolved.explicitPath || 'unknown'}. Provide a valid feature target inside configured specs root.`
+    }) + '\n');
+    process.exit(0);
+  }
+  if (resolved.error) process.exit(0);
 
+  const activeSpec = resolved.spec;
+  const featureName = resolved.featureName;
+  const specsPath = resolved.specsDir;
+  const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
+  const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
+    || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
+  if (activeSpec.schema_version === '2.1') {
+    const finalState = FINAL_STATE.evaluateCloseout({
+      resolver: RESOLVER,
+      policy: POLICY,
+      projectRoot: baseDir,
+      runtime,
+      payload: { ...payload, session_id: sessionIdentity(payload) },
+    });
+    if (!finalState.ok) {
+      emitBlock(`Completion gate: ${finalState.reason}`);
+      process.exit(0);
+    }
+    if (finalState.active) process.exit(0);
+  }
+  const runtimeContext = POLICY.deriveRuntimeContext({
+    projectRoot: baseDir,
+    specsRoot: specsPath,
+    specFile: resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    featureName,
+    runtimeSession: sessionIdentity(payload),
+  });
+
+  const configuredGate = runtime.spec?.completion_gate;
+  if (configuredGate !== undefined && configuredGate !== true) {
+    emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
+    process.exit(0);
+  }
   const taskRegistry = activeSpec.task_registry || {};
   const cacheFile = path.join(__dirname, '.logs', 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
@@ -90,103 +202,30 @@ try {
   const allDoneTasks = Object.keys(taskRegistry).filter((tp) =>
     (taskRegistry[tp]?.status || 'pending') === 'done'
   );
-  // /m so ^ matches line starts (Evidence is never at byte 0 of the file).
-  // legacy heading aliases: read-compat only, no longer advertised
-  const EVID_RE = /^#{2,3}\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/m;
-  const PASS_MARKER_RE = /^\s*Verification:\s*PASS\s*$/m;
-  const LEGACY_SUCCESS_RE = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
-  const EXPLICIT_FAILURE_RE = /\bFAIL(?:ED|URE|URES|ING)?\b|tests?\s+failed|exit\s+code\s*[:=]?\s*[1-9]\d*|\b0\s+tests?\b/i;
-
-  /** Body of first Evidence heading until next same-or-higher heading. */
-  function evidenceBody(text) {
-    const lines = text.split('\n');
-    let start = -1, level = 0;
-    for (let i = 0; i < lines.length; i++) {
-      const m = lines[i].match(/^(#{2,3})\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/);
-      if (m) { start = i + 1; level = m[1].length; break; }
-    }
-    if (start < 0) return null;
-    let end = lines.length;
-    for (let i = start; i < lines.length; i++) {
-      const hm = lines[i].match(/^(#{1,6})\s+/);
-      if (hm && hm[1].length <= level) { end = i; break; }
-    }
-    return lines.slice(start, end).join('\n');
-  }
-
-  function validateCanonicalReceipt(body) {
-    const fails = [];
-    if (!/^\s*Verification:\s*PASS\s*$/m.test(body)) fails.push('verification_state');
-    if (!/^\s*Command(?:\(s\))?\s*:/m.test(body)) fails.push('command');
-    if (!/^\s*Exit\s*:|exit\s+code\s*[:=]|\bResult\s*:\s*PASS\b/im.test(body)) fails.push('exit_result');
-    const hasBase = /^\s*Base[ \t]*:[ \t]*\S/im.test(body);
-    const hasHead = /^\s*Head[ \t]*:[ \t]*\S/im.test(body);
-    const hasBaseSha = /\bbase_sha[ \t]*:[ \t]*\S/im.test(body);
-    const hasHeadSha = /\bhead_sha[ \t]*:[ \t]*\S/im.test(body);
-    if (!((hasBase && hasHead) || (hasBaseSha && hasHeadSha))) fails.push('provenance');
-    if (/\bartifact\b/i.test(body) && !/sha256:/i.test(body)) fails.push('artifact_hash');
-    return fails;
-  }
-
-  // Receipt checks a–h → failed letter list.
-  // a: file + Status header has "done"; b: Evidence heading; c: no {{...}} + unambiguous PASS; d: completed_at; e: command; f: exit/result; g: provenance; h: artifact hash
-  function safeTaskFile(featureDir, taskPath) {
-    const target = path.resolve(featureDir, taskPath);
-    const relative = path.relative(featureDir, target);
-    // sibling-prefix safe: must not be .., ../..., or absolute (cross-platform)
-    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
-    return target;
-  }
-
-  function checkReceipt(taskPath) {
-    const fails = [];
-    const featureDir = path.join(specsPath, featureName);
-    const abs = safeTaskFile(featureDir, taskPath);
-    if (!abs || !fs.existsSync(abs)) return ['a'];
-    let text = '';
-    try { text = fs.readFileSync(abs, 'utf8'); } catch { return ['a']; }
-
-    const statusLine = text.split('\n').find((l) => /^\s*(\*\*)?Status(\*\*)?\s*:/i.test(l));
-    if (!statusLine || !/\bdone\b/i.test(statusLine)) fails.push('a');
-
-    const body = evidenceBody(text);
-    if (body === null || !EVID_RE.test(text)) {
-      fails.push('b');
-    } else if (
-      /\{\{[^}]+\}\}/.test(body) ||
-      EXPLICIT_FAILURE_RE.test(body) ||
-      !(PASS_MARKER_RE.test(body) || LEGACY_SUCCESS_RE.test(body))
-    ) {
-      fails.push('c');
-    } else {
-      // Canonical receipt checks for done tasks
-      const canonicalFails = validateCanonicalReceipt(body);
-      const map = { verification_state: 'c', command: 'e', exit_result: 'f', provenance: 'g', artifact_hash: 'h' };
-      for (const cf of canonicalFails) {
-        if (cf === 'verification_state') {
-          if (!PASS_MARKER_RE.test(body) && !fails.includes('c')) fails.push('c');
-          continue;
-        }
-        const letter = map[cf];
-        if (letter && !fails.includes(letter)) fails.push(letter);
-      }
-      // Enforce strict Verification: PASS, not just legacy success
-      if (!PASS_MARKER_RE.test(body) && !fails.includes('c')) fails.push('c');
-    }
-
-    const at = taskRegistry[taskPath]?.completed_at;
-    if (
-      typeof at !== 'string' ||
-      !/^\d{4}-\d{2}-\d{2}T/.test(at) ||
-      Number.isNaN(Date.parse(at))
-    ) fails.push('d');
-    return fails;
-  }
-
+  const featureDir = path.join(specsPath, featureName);
   const failures = allDoneTasks
-    .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
+    .map((taskPath) => ({
+      taskPath,
+      fails: RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
+    }))
     .filter((f) => f.fails.length > 0);
 
+  const featureCloseoutRequired = explicitCloseout && allDoneTasks.length > 0;
+  const featureReceipt = featureCloseoutRequired
+    ? RECEIPT.checkFeatureReceipt(featureDir, runtimeContext, POLICY)
+    : null;
+  if (featureReceipt && featureReceipt.failures.length) {
+    failures.push({ taskPath: 'feature-receipt.md', fails: featureReceipt.failures });
+  }
+  const completion = featureCloseoutRequired && featureReceipt?.failures.length === 0
+    && Object.prototype.hasOwnProperty.call(activeSpec, 'workflow_policy')
+    ? POLICY.completionDecisionForSpec(activeSpec, {
+      runtimeContext,
+      executionReceipt: featureReceipt.body,
+      taskContext: {},
+    })
+    : null;
+
   // Always persist status transitions, including done → pending. Keep
   // failing done tasks at their previous cached status so a stale valid
   // entry cannot mask a mutated receipt on the next Stop; with
@@ -202,28 +241,31 @@ try {
     fs.writeFileSync(cacheFile, JSON.stringify(cache));
   } catch { /* fail-open */ }
 
-  if (allDoneTasks.length === 0) process.exit(0);
-  if (failures.length === 0) process.exit(0);
+  const completionBlocked = completion && completion.completion !== 'complete' && completion.completion !== 'not_applicable';
+  if (failures.length === 0 && !completionBlocked) process.exit(0);
 
   const lines = [
-    `⚠️ Completion gate: ${failures.length} newly-done task(s) lack a verification receipt.`,
+    failures.length > 0
+      ? `⚠️ Completion gate: ${failures.length} done task(s) lack a verification receipt.`
+      : '⚠️ Completion gate: workflow completion proof is incomplete.',
   ];
   for (const { taskPath, fails } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
-    lines.push(
-      `  Fix: add \`Verification: PASS\` plus commands and successful outcomes to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`, then re-sync spec.json`
-    );
+    lines.push(taskPath === 'feature-receipt.md'
+      ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
+      : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
+  }
+  if (completionBlocked) {
+    lines.push(`- Completion decision unfinished: ${completion.blocker || 'required workflow proof is missing.'}`);
+    if (Array.isArray(completion.missingProof) && completion.missingProof.length > 0) {
+      lines.push(`  Missing proof: ${completion.missingProof.join(', ')}`);
+    }
   }
   process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');
   process.exit(0);
 
 } catch (e) {
-  try {
-    const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
-    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
-      JSON.stringify({ ts: new Date().toISOString(), hook: 'spec-gate', status: 'crash', error: e.message }) + '\n');
-  } catch (_) {}
+  logCrash(e);
+  emitBlock(`Completion gate controlled failure: ${e.message}. Completion is blocked until the hook is repaired.`);
   process.exit(0);
 }

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

@@ -8,14 +8,42 @@
  * Scans for an active spec in progress and dynamically injects
  * the State Sync (Tollgate) rule into the agent's context.
  *
- * Exit: 0 always (fail-open)
+ * Exit: 0 always; unavailable policy is surfaced as a controlled failure.
  */
 
-try {
-  const fs   = require('fs');
-  const path = require('path');
-  const POLICY = require(path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs'));
+const fs = require('fs');
+const path = require('path');
 
+function logCrash(error) {
+  try {
+    const d = path.join(__dirname, '.logs');
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(
+      path.join(d, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'spec-state', status: 'crash', error: error.message }) + '\n'
+    );
+  } catch (_) {}
+}
+
+function emitControlledFailure(reason) {
+  console.log(`\n> ⚠️ Spec tollgate unavailable: ${reason}. Repair the installed workflow policy before continuing.\n`);
+}
+
+function sessionIdentity(payload) {
+  const candidates = [
+    payload && payload.session_id,
+    payload && payload.sessionId,
+    payload && payload.sessionID,
+    payload && payload.session && payload.session.id,
+  ];
+  return candidates.find((value) => typeof value === 'string' && value.length > 0) || null;
+}
+
+function canonicalPath(value) {
+  try { return fs.realpathSync(value); } catch { return null; }
+}
+
+try {
   // ── Main ──────────────────────────────────────────────────────────────────
 
   const stdin = fs.readFileSync(0, 'utf8').trim();
@@ -24,6 +52,20 @@ try {
   const payload = JSON.parse(stdin);
   const cwd     = payload.cwd || process.cwd();
 
+  let POLICY;
+  let RESOLVER;
+  let RECEIPT;
+  try {
+    POLICY = require(path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs'));
+    RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
+    RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
+    if (typeof POLICY.flashState !== 'function') throw new Error('shared workflow policy has no flashState function');
+  } catch (error) {
+    logCrash(error);
+    emitControlledFailure(error.message);
+    process.exit(0);
+  }
+
   // Read runtime configuration if exists
   let runtime = {};
   try {
@@ -36,37 +78,47 @@ try {
   if (runtime.spec && runtime.spec.tollgate === false) process.exit(0);
 
   const baseDir   = process.env.PROJECT_ROOT || cwd;
-  const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
+  const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
+  const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
+  const resolved = RESOLVER.resolveActiveSpec({ projectRoot: baseDir, runtime, explicitFeature, explicitPath });
 
-  if (!fs.existsSync(specsPath)) {
+  if (!resolved) {
+    process.exit(0); // No active spec, do nothing
+  }
+
+  if (resolved.error === 'multiple_active') {
+    const candidates = resolved.candidates.join(', ');
+    console.log(`\n> ⚠️ Multiple active specs detected: ${candidates}. Provide explicit feature target or resolve ambiguity. Tollgate paused.\n`);
+    process.exit(0);
+  }
+
+  if (resolved.error === 'invalid_specs') {
+    const cands = resolved.candidates.join(', ');
+    console.log(`\n> ⚠️ Invalid spec JSON detected: ${cands}. ${resolved.reason}. Fix or remove malformed spec.json before continuing. Tollgate paused.\n`);
     process.exit(0);
   }
 
-  // Find the active spec
-  let activeSpec = null;
-  let featureName = null;
-
-  const entries = fs.readdirSync(specsPath, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      const specFile = path.join(specsPath, entry.name, 'spec.json');
-      if (fs.existsSync(specFile)) {
-        try {
-          const specData = JSON.parse(fs.readFileSync(specFile, 'utf8'));
-          if (specData.status === 'in_progress' || specData.status === 'in-progress') {
-            activeSpec = specData;
-            featureName = entry.name;
-            break; // take the first active one
-          }
-        } catch { /* skip bad JSON */ }
-      }
-    }
+  if (resolved.error === 'explicit_not_found' || resolved.error === 'explicit_malformed') {
+    const detail = resolved.reason || resolved.explicitFeature || resolved.explicitPath || 'unknown';
+    console.log(`\n> ⚠️ Explicit spec target invalid (${resolved.error}): ${detail}. Provide a valid feature target inside configured specs root. Tollgate paused.\n`);
+    process.exit(0);
   }
 
-  if (!activeSpec) {
-    process.exit(0); // No active spec, do nothing
+  if (resolved.error) {
+    process.exit(0);
   }
 
+  const activeSpec = resolved.spec;
+  const featureName = resolved.featureName;
+  const specsPath = resolved.specsDir;
+  const runtimeContext = POLICY.deriveRuntimeContext({
+    projectRoot: baseDir,
+    specsRoot: specsPath,
+    specFile: resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    featureName,
+    runtimeSession: sessionIdentity(payload),
+  });
+
   const phase = activeSpec.current_phase || activeSpec.phase || 'unknown';
   const taskRegistry = activeSpec.task_registry || {};
   const flashTasks = POLICY.flashState(taskRegistry);
@@ -82,27 +134,44 @@ try {
     const deps = Array.isArray(task?.dependencies) ? task.dependencies : [];
     return status === 'pending' && deps.every((dep) => taskStatusByPath.get(dep) === 'done');
   });
+  const featureDir = path.join(specsPath, featureName);
+  const featureReceiptPresent = RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
 
   // ── State-change gate: only emit the full tollgate when spec state changed ──
-  // This hook runs on EVERY UserPromptSubmit. Re-printing the whole block when
-  // phase + done/total are unchanged is wasted context (~460 tok/turn). We keep
-  // a tiny state fingerprint in a temp file: same -> one-line reminder; changed
-  // -> full block (and refresh the fingerprint). Fail-open at every step.
-  const stateKey = `${phase}|${taskCounts.done || 0}/${taskEntries.length}`;
+  // The cache is shared by installed hook copies, so its key must carry the
+  // canonical project, complete session identity, and canonical spec identity.
+  // If any identity is unavailable, skip caching and emit the full block.
+  const stateKey = JSON.stringify({
+    projectRoot: runtimeContext.project_root,
+    specsRoot: runtimeContext.specs_root,
+    specFile: runtimeContext.spec_file,
+    featureName: runtimeContext.feature_name,
+    runtimeSession: runtimeContext.runtime_session,
+    provenanceMode: runtimeContext.provenance_mode,
+    Base: runtimeContext.base,
+    Head: runtimeContext.head,
+    contextId: runtimeContext.context_id,
+    phase,
+    done: taskCounts.done || 0,
+    total: taskEntries.length,
+    featureReceiptPresent,
+  });
   const cacheFile = path.join(__dirname, '.logs', 'tollgate-last.txt');
 
   let lastKey = '';
-  try { lastKey = fs.readFileSync(cacheFile, 'utf8').trim(); } catch { /* first run */ }
+  if (stateKey) {
+    try { lastKey = fs.readFileSync(cacheFile, 'utf8'); } catch { /* first run */ }
+  }
 
-  if (lastKey === stateKey) {
+  if (stateKey && lastKey === stateKey) {
     console.log(`\n> 🔵 Spec \`${featureName}\` @ \`${phase}\` (${taskCounts.done || 0}/${taskEntries.length} tasks done). Tollgate active — sync \`spec.json\` when state changes.\n`);
     process.exit(0);
   }
 
   try {
     fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
-    fs.writeFileSync(cacheFile, stateKey);
-  } catch { /* fail-open: if the write fails we still print the full block */ }
+    if (stateKey) fs.writeFileSync(cacheFile, stateKey);
+  } catch { /* cache failure only disables reminder compression */ }
 
   // Compact state-change block (enforcement lives on Stop via spec-gate.cjs).
   const lines = [];
@@ -116,22 +185,18 @@ try {
     lines.push(`- Next unblocked: \`${nextUnblocked[0]}\``);
   }
   if (flashTasks.length > 0) {
-    lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. PASS promotion keeps task in_progress until explicit sync-finalize.`);
+    lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. A PASS proof keeps the persisted task in_progress until explicit sync-finalize.`);
   }
-  lines.push(`- Sync \`spec.json\` + task file after verified work; run \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\` before \`ready_for_implementation=true\`.`);
-  lines.push(`- A completion gate verifies receipts when you end a turn with newly-done tasks.`);
+  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('');
 
   console.log(lines.join('\n'));
   process.exit(0);
 
 } catch (e) {
-  try {
-    const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
-    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
-      JSON.stringify({ ts: new Date().toISOString(), hook: 'spec-state', status: 'crash', error: e.message }) + '\n');
-  } catch (_) {}
+  logCrash(e);
+  emitControlledFailure(e.message);
   process.exit(0);
 }

package/src/claude/migration-manifest.json

@@ -61,7 +61,14 @@
       "generate-skill-catalog.cjs",
       "validate-spec-output.cjs",
       "scan-staged-secrets.cjs",
-      "workflow-policy.cjs"
+      "workflow-policy.cjs",
+      "spec-resolver.cjs",
+      "spec-receipt.cjs",
+      "spec-ground.cjs",
+      "spec-semantic-model.cjs",
+      "spec-final-state.cjs",
+      "spec-readiness.cjs",
+      "provenance.cjs"
     ]
   },
   "agentReferences": {
@@ -102,6 +109,10 @@
       "hooks/rules.cjs",
       "hooks/spec-state.cjs",
       "hooks/spec-gate.cjs",
+      "hooks/completion-authority.cjs",
+      "hooks/completion-authority-check.cjs",
+      "hooks/completion-authority-state.cjs",
+      "hooks/semantic-review-authority.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
       "hooks/lib/parser.cjs",
@@ -109,7 +120,9 @@
       "hooks/lib/git.cjs",
       "hooks/lib/config.cjs",
       "hooks/lib/context.cjs",
-      "hooks/lib/detect.cjs"
+      "hooks/lib/detect.cjs",
+      "hooks/lib/privacy-command-analysis.cjs",
+      "hooks/lib/runtime-path-safety.cjs"
     ]
   },
   "settings": {