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

package/src/codex/hooks/privacy-block.cjs

@@ -12,6 +12,10 @@ const {
   getHookContext,
   readPayload
 } = require('./lib/hook-context.cjs');
+const {
+  DYNAMIC_READ_PATH,
+  commandAccess,
+} = require('./lib/privacy-command-analysis.cjs');
 
 const RESTRICTED = [
   /^\.env(?:[.\[*?{]|$)/i,
@@ -28,7 +32,13 @@ const RESTRICTED = [
   /\.keystore$/i,
   /\.jks$/i,
   /auth\.json$/i,
-  /token(s)?\.json$/i
+  /token(s)?\.json$/i,
+  /\.cafekit/i,
+  /hmac\.key/i,
+  /completion-authority/i,
+  /session-state/i,
+  /hook-log/i,
+  /sessions/i
 ];
 
 const EXEMPT = [/\.env\.(example|sample|template|test)$/i];
@@ -48,6 +58,7 @@ function isSafe(filePath) {
 }
 
 function isSensitive(filePath) {
+  if (filePath === DYNAMIC_READ_PATH) return true;
   return matchesAny(filePath, RESTRICTED);
 }
 
@@ -60,18 +71,60 @@ function resolveTarget(filePath, cwd) {
   }
 }
 
-function extractCommandPaths(command) {
-  const paths = new Set();
-  for (const token of String(command).split(/[\s|;&<>"']+/).filter(Boolean)) {
-    const cleaned = token.replace(/^["'()`]+|["'(),:]+$/g, '');
-    for (const candidate of cleaned.split('=')) {
-      const value = candidate.replace(/^["'()`]+|["'(),:]+$/g, '');
-      if (value && (isSensitive(value) || isSafe(value))) paths.add(value);
+/**
+ * When realpath fails, check whether the requested path is a symlink (or chain)
+ * whose lexical target is sensitive. Dangling link to protected target -> true (fail-closed deny);
+ * dangling benign link or link to allowed example/template -> false (allow).
+ * Limit hops to avoid loops; malformed/looping -> fail closed.
+ * TOCTOU note: check and use are not atomic; target could be swapped between this check and the actual read.
+ * This is a best-effort guardrail, not an arbitrary-shell security boundary. For strong isolation use OS sandbox.
+ */
+function isSymlinkToSensitive(filePath, cwd) {
+  try {
+    const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+    let current = requested;
+    let hops = 0;
+    const MAX_HOPS = 8;
+    while (hops < MAX_HOPS) {
+      let stat;
+      try {
+        stat = fs.lstatSync(current);
+      } catch {
+        return false;
+      }
+      if (!stat.isSymbolicLink()) return false;
+      let linkTarget;
+      try {
+        linkTarget = fs.readlinkSync(current);
+      } catch {
+        return true;
+      }
+      if (isSensitive(linkTarget) && !isSafe(linkTarget)) return true;
+      if (isSafe(linkTarget)) return false;
+      const next = path.isAbsolute(linkTarget) ? linkTarget : path.resolve(path.dirname(current), linkTarget);
+      if (next === current) return true;
+      try {
+        const real = fs.realpathSync(next);
+        if (isSensitive(real) && !isSafe(real)) return true;
+        if (isSafe(real)) return false;
+        return false;
+      } catch {
+        current = next;
+        hops += 1;
+        continue;
+      }
     }
+    return true;
+  } catch {
+    return true;
   }
-  return [...paths];
 }
 
+  function extractCommandPaths(command) {
+    const access = commandAccess(command);
+    return access.dynamic ? [...access.paths, DYNAMIC_READ_PATH] : access.paths;
+  }
+
 function extractPatchPaths(patch) {
   return [...String(patch).matchAll(
     /^\*\*\* (?:(?:Add|Update|Delete) File:|Move to:)\s+(.+)$/gm
@@ -126,6 +179,8 @@ function sensitiveRequest(filePath, cwd) {
   if (target) {
     if (isSensitive(target) && !isSafe(target)) return true;
     if (isSafe(target)) return false;
+  } else {
+    if (isSymlinkToSensitive(filePath, cwd)) return true;
   }
   return !isSafe(filePath) && isSensitive(filePath);
 }
@@ -152,7 +207,8 @@ try {
   if (runtime.privacyBlock === false) process.exit(0);
 
   const filePaths = sensitivePaths(data.tool_name || '', data.tool_input || {}, sessionCwd);
-  if (filePaths.length === 0) process.exit(0);
+  const effectivePaths = filePaths;
+  if (effectivePaths.length === 0) process.exit(0);
   if (!data.session_id) {
     deny(
       'Sensitive file access denied because this hook invocation had no Codex session ID. ' +
@@ -164,7 +220,7 @@ try {
     projectRoot,
     sessionCwd,
     sessionId: data.session_id,
-    filePaths,
+    filePaths: effectivePaths,
     toolName: data.tool_name
   };
   if (consumeToken(tokenInput)) process.exit(0);

package/src/codex/hooks/semantic-review-authority.cjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const STATE = require('./completion-authority-state.cjs');
+const PATH_SAFETY = require('./lib/runtime-path-safety.cjs');
+
+const SCHEMA_VERSION = 1;
+const MARKER = 'CAFEKIT_SEMANTIC_REVIEW_ATTESTATION ';
+const SHA256_RE = /^sha256:[a-f0-9]{64}$/;
+const REVIEWER_ROLE_ALLOWLIST = new Set(['code-auditor', 'code_auditor']);
+const RECORD_FIELDS = ['schema_version', 'kind', 'identity', 'semantic_digest', 'event', 'verdict', 'host_session_id', 'reviewer_agent_id', 'reviewer_agent_type', 'issued_at', 'mac'];
+
+function plain(value) { return Boolean(value && typeof value === 'object' && !Array.isArray(value)); }
+function exactKeys(value, fields) { return plain(value) && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...fields].sort()); }
+function inside(root, target) { const relative = path.relative(root, target); return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative); }
+
+function projectRoot(payload = {}) {
+  const installedRoot = path.resolve(__dirname, '..', '..');
+  if (fs.existsSync(path.join(installedRoot, '.codex', 'hooks', path.basename(__filename)))) {
+    try { return STATE.canonicalProjectRoot(installedRoot); } catch {}
+  }
+  for (const candidate of [process.env.CLAUDE_PROJECT_DIR, process.env.PROJECT_ROOT]) {
+    if (typeof candidate === 'string' && candidate.trim()) { try { return STATE.canonicalProjectRoot(candidate); } catch { /* continue */ } }
+  }
+  const cwd = typeof payload.cwd === 'string' && payload.cwd.trim() ? payload.cwd : process.cwd();
+  return STATE.canonicalProjectRoot(cwd);
+}
+
+function identityFor(root, specFile, featureName) {
+  if (typeof featureName !== 'string' || !featureName.trim() || featureName.includes('/') || featureName.includes('\\') || featureName === '.' || featureName === '..' || featureName.includes('..')) throw new Error('feature identity is malformed');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(featureName)) throw new Error('feature identity is malformed');
+  const canonicalRoot = STATE.canonicalProjectRoot(root);
+  const canonicalSpec = fs.realpathSync(path.resolve(specFile));
+  if (!inside(canonicalRoot, canonicalSpec) || path.basename(canonicalSpec) !== 'spec.json') throw new Error('spec identity escapes the project');
+  const relative = path.relative(canonicalRoot, canonicalSpec);
+  const expected = path.join('specs', featureName, 'spec.json');
+  if (relative !== expected) throw new Error(`spec identity must be ${expected}, not ${relative}`);
+  const spec = JSON.parse(fs.readFileSync(canonicalSpec, 'utf8'));
+  if (spec.feature_name !== featureName) throw new Error('feature identity does not match spec.json');
+  return { project_root: canonicalRoot, spec_file: canonicalSpec, feature_name: featureName };
+}
+
+function recordPath(root, identity) {
+  const name = STATE.digest({ namespace: 'cafekit-semantic-review-observation-v1', identity });
+  return path.join(STATE.stateDir(root), 'semantic-reviews', `observation-${name}.json`);
+}
+
+function parseClaim(message) {
+  const lines = String(message || '').split(/\r?\n/).filter((line) => line.startsWith(MARKER));
+  if (lines.length === 0) return null;
+  if (lines.length !== 1) throw new Error('exactly one semantic review attestation marker is required');
+  const claim = JSON.parse(lines[0].slice(MARKER.length));
+  if (!exactKeys(claim, ['feature_name', 'spec_file', 'semantic_digest', 'verdict'])) throw new Error('semantic review claim fields are malformed');
+  if (claim.verdict !== 'PASS' || !SHA256_RE.test(claim.semantic_digest || '')) throw new Error('semantic review claim must contain literal PASS and a sha256 digest');
+  return claim;
+}
+
+function validatorFor(root) {
+  const installedRoot = path.join(root, '.codex');
+  const installedHook = path.join(installedRoot, 'hooks', path.basename(__filename));
+  if (fs.existsSync(installedHook)) {
+    const canonicalHook = PATH_SAFETY.canonicalRegularFile(root, installedHook, 'installed semantic hook');
+    if (canonicalHook !== fs.realpathSync(__filename)) throw new Error('installed semantic hook identity is invalid');
+    const validator = path.join(installedRoot, 'scripts', 'validate-spec-output.cjs');
+    PATH_SAFETY.verifyCommonJsClosure(installedRoot, validator);
+    return PATH_SAFETY.canonicalRegularFile(installedRoot, validator, 'semantic validator');
+  }
+
+  const sourceRuntime = path.resolve(__dirname, '..', '..', 'claude');
+  const sourceRoot = path.resolve(sourceRuntime, '..');
+  if (path.basename(sourceRuntime) !== 'claude' || path.basename(sourceRoot) !== 'src') {
+    throw new Error('semantic validator runtime root is not recognized');
+  }
+  const validator = path.join(sourceRuntime, 'scripts', 'validate-spec-output.cjs');
+  PATH_SAFETY.verifyCommonJsClosure(sourceRoot, validator);
+  return PATH_SAFETY.canonicalRegularFile(sourceRoot, validator, 'semantic validator');
+}
+
+function currentDigest(root, specFile) {
+  const validator = validatorFor(root);
+  const result = spawnSync(process.execPath, [validator, path.dirname(specFile), '--semantic-digest'], { cwd: root, encoding: 'utf8' });
+  const digest = result.stdout.trim();
+  if (result.status !== 0 || !SHA256_RE.test(digest)) throw new Error(`semantic digest could not be recomputed (${result.stderr.trim() || `exit ${result.status}`})`);
+  return digest;
+}
+
+function recordFromSubagentStop(payload) {
+  // Honest-agent guardrail: the host hook observes this SubagentStop payload.
+  // The worker-authored claim is not authenticated input or a security boundary.
+  if (!plain(payload) || payload.hook_event_name !== 'SubagentStop') return { recorded: false, reason: 'event' };
+  for (const field of ['session_id', 'agent_id', 'agent_type', 'last_assistant_message']) if (typeof payload[field] !== 'string' || !payload[field].trim()) return { recorded: false, reason: `missing-${field}` };
+  if (!REVIEWER_ROLE_ALLOWLIST.has(payload.agent_type)) return { recorded: false, reason: 'reviewer-role' };
+  const root = projectRoot(payload);
+  const claim = parseClaim(payload.last_assistant_message);
+  if (claim === null) return { recorded: false, reason: 'no-claim' };
+  const identity = identityFor(root, path.resolve(root, claim.spec_file), claim.feature_name);
+  const digest = currentDigest(root, identity.spec_file);
+  if (digest !== claim.semantic_digest) throw new Error('claimed semantic digest does not match current artifacts');
+  const key = STATE.ensureKey();
+  const record = { schema_version: SCHEMA_VERSION, kind: 'semantic-review-observation', identity, semantic_digest: digest, event: 'SubagentStop', verdict: 'PASS', host_session_id: payload.session_id, reviewer_agent_id: payload.agent_id, reviewer_agent_type: payload.agent_type, issued_at: new Date().toISOString() };
+  record.mac = STATE.recordMac(record, key);
+  STATE.atomicWrite(recordPath(root, identity), record);
+  return { recorded: true, record };
+}
+
+function verifyAttestation(root, specFile, featureName, semanticDigest) {
+  let identity;
+  try { identity = identityFor(root, specFile, featureName); } catch (error) { return { ok: false, reason: error.message }; }
+  let record;
+  try { record = JSON.parse(fs.readFileSync(recordPath(root, identity), 'utf8')); } catch (error) { return { ok: false, reason: error.code === 'ENOENT' ? 'matching host-hook observation is missing' : 'host-hook observation is unreadable' }; }
+  const key = STATE.readKey();
+  if (key.missing) return { ok: false, reason: 'completion authority key is missing' };
+  if (!exactKeys(record, RECORD_FIELDS) || !STATE.macMatches(record, key.key)) return { ok: false, reason: 'host-hook observation is malformed or its MAC is invalid' };
+  if (record.schema_version !== SCHEMA_VERSION || record.kind !== 'semantic-review-observation' || record.event !== 'SubagentStop' || record.verdict !== 'PASS') return { ok: false, reason: 'host-hook observation event or verdict is invalid' };
+  if (STATE.stableStringify(record.identity) !== STATE.stableStringify(identity)) return { ok: false, reason: 'host-hook observation project, feature, or spec identity is invalid' };
+  if (record.semantic_digest !== semanticDigest) return { ok: false, reason: 'host-hook observation semantic digest is stale' };
+  return { ok: true, record };
+}
+
+if (require.main === module) {
+  try { const raw = fs.readFileSync(0, 'utf8').trim(); if (raw) recordFromSubagentStop(JSON.parse(raw)); }
+  catch (error) { process.stderr.write(`CafeKit semantic review SubagentStop claim rejected: ${error.message}\n`); }
+  // Codex SubagentStop requires valid JSON on stdout for every exit-0 hook.
+  process.stdout.write('{}\n');
+}
+
+module.exports = { MARKER, REVIEWER_ROLE_ALLOWLIST, recordFromSubagentStop, verifyAttestation, identityFor, recordPath };

package/src/codex/hooks/session.cjs

@@ -10,6 +10,7 @@ const {
   readPayload
 } = require('./lib/hook-context.cjs');
 const { clearState } = require('./lib/privacy-state.cjs');
+const { clearState: clearCompletionState } = require('./completion-authority-state.cjs');
 
 function readPackage(projectRoot) {
   try {
@@ -88,6 +89,7 @@ try {
 
   // Approval tokens never survive a session boundary or compaction.
   clearState(projectRoot);
+  clearCompletionState(projectRoot, payload.session_id);
 
   const parts = [
     projectType && `Type: ${projectType}`,

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

@@ -9,21 +9,101 @@ const {
   logCrash,
   readPayload
 } = require('./lib/hook-context.cjs');
-const { checkReceipt } = require('./lib/spec-receipt.cjs');
-const { findActiveSpec, taskStatusMap } = require('./lib/spec-utils.cjs');
-const policyPath = path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs');
-const POLICY = require(fs.existsSync(policyPath)
-  ? policyPath
-  : path.join(__dirname, '../../claude/scripts/workflow-policy.cjs'));
+const {
+  checkFeatureReceipt,
+  checkReceiptDetails,
+  loadSharedPolicy,
+} = require('./lib/spec-receipt.cjs');
+const { taskStatusMap } = require('./lib/spec-utils.cjs');
+const FINAL_STATE = require('./completion-authority-check.cjs');
+
+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 payload = readPayload();
-  if (!payload || payload.stop_hook_active === true) process.exit(0);
+  if (payload.stop_hook_active === true) process.exit(0);
+  const loaded = loadSharedPolicy();
+  if (!loaded.policy) {
+    logCrash('spec-gate', loaded.error);
+    emitBlock(`Completion gate unavailable: shared workflow policy could not be loaded (${loaded.error.message}). Repair ${loaded.path} before completing tasks.`);
+    process.exit(0);
+  }
+  const POLICY = loaded.policy;
   const { projectRoot, runtime } = getHookContext(payload);
-  if (runtime.spec?.completion_gate === false) process.exit(0);
-  const active = findActiveSpec(projectRoot, runtime);
-  if (!active) process.exit(0);
-
+  if (typeof POLICY.completionDecisionForSpec !== 'function') {
+    throw new Error('shared workflow policy lacks completion authority functions');
+  }
+  const resolver = require('./lib/spec-utils.cjs');
+  const resolved = FINAL_STATE.resolveCandidate({
+    resolver,
+    projectRoot,
+    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.`
+    })}\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 active = resolved;
+  const lifecyclePhase = active.spec.current_phase || active.spec.phase;
+  const explicitCloseout = ['done', 'completed', 'complete'].includes(active.spec.status)
+    || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
+  if (active.spec.schema_version === '2.1') {
+    const finalState = FINAL_STATE.evaluateCloseout({
+      policy: POLICY,
+      projectRoot,
+      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,
+    specsRoot: active.specsDir,
+    specFile: active.specFile || path.join(active.specsDir, active.featureName, 'spec.json'),
+    featureName: active.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 registry = active.spec.task_registry || {};
   const currentStatuses = taskStatusMap(active.spec);
   const cacheFile = path.join(
@@ -42,7 +122,21 @@ try {
   // Cache hardening: revalidate every done task on every Stop so a
   // cached PASS cannot hide later receipt/provenance mutations.
   // Cache is optimization only - validate every done task even on first run.
-  const previous = cacheExists ? (cache[active.featureName] || {}) : {};
+  const cacheIdentity = {
+    project_root: runtimeContext.project_root,
+    specs_root: runtimeContext.specs_root,
+    spec_file: runtimeContext.spec_file,
+    feature_name: runtimeContext.feature_name,
+    runtime_session: runtimeContext.runtime_session,
+    provenance_mode: runtimeContext.provenance_mode,
+    Base: runtimeContext.base,
+    Head: runtimeContext.head,
+    context_id: runtimeContext.context_id,
+  };
+  const cacheEntries = cache && cache.entries && typeof cache.entries === 'object' ? cache.entries : {};
+  const previous = cacheExists && cacheEntries[runtimeContext.context_id]
+    ? cacheEntries[runtimeContext.context_id].tasks || {}
+    : {};
   const staleFlashTasks = Object.entries(registry)
     .filter(([, task]) => POLICY.isStaleFlashDone(task))
     .map(([taskPath]) => taskPath);
@@ -57,30 +151,62 @@ try {
     currentStatuses[taskPath] === 'done'
   ));
   const featureDir = path.join(active.specsDir, active.featureName);
+  const receiptBodies = new Map();
   const failures = allDoneTasks
-    .map((taskPath) => ({
-      taskPath,
-      failures: checkReceipt(featureDir, taskPath, registry[taskPath])
-    }))
+    .map((taskPath) => {
+      const proof = checkReceiptDetails(featureDir, taskPath, registry[taskPath], runtimeContext);
+      if (proof.body) receiptBodies.set(taskPath, proof.body);
+      return {
+        taskPath,
+        failures: proof.failures
+      };
+    })
     .filter((result) => result.failures.length);
 
+  const featureCloseoutRequired = explicitCloseout && allDoneTasks.length > 0;
+  const featureReceipt = featureCloseoutRequired
+    ? checkFeatureReceipt(featureDir, runtimeContext)
+    : null;
+  if (featureReceipt && featureReceipt.failures.length) {
+    failures.push({ taskPath: 'feature-receipt.md', failures: featureReceipt.failures });
+  }
+  const completion = featureCloseoutRequired && featureReceipt?.failures.length === 0
+    && Object.prototype.hasOwnProperty.call(active.spec, 'workflow_policy')
+    ? POLICY.completionDecisionForSpec(active.spec, {
+      runtimeContext,
+      executionReceipt: featureReceipt.body,
+      taskContext: {},
+    })
+    : null;
+
   const next = { ...previous, ...currentStatuses };
   for (const result of failures) {
     if (previous[result.taskPath] === undefined) delete next[result.taskPath];
     else next[result.taskPath] = previous[result.taskPath];
   }
-  cache[active.featureName] = next;
-  atomicWrite(cacheFile, `${JSON.stringify(cache)}\n`);
+  atomicWrite(cacheFile, `${JSON.stringify({
+    schema_version: '2',
+    entries: { ...cacheEntries, [runtimeContext.context_id]: { identity: cacheIdentity, tasks: next } },
+  })}\n`);
 
-  if (!failures.length) process.exit(0);
+  const completionBlocked = completion && completion.completion !== 'complete' && completion.completion !== 'not_applicable';
+  if (!failures.length && !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 result of failures) {
-    lines.push(
-      `- \`${result.taskPath}\`: failed check(s) ${result.failures.join(', ')}`,
-      `  Add \`Verification: PASS\`, commands, and successful outcomes under \`## Evidence\` in \`specs/${active.featureName}/${result.taskPath}\`, then re-sync spec.json.`
-    );
+    lines.push(`- \`${result.taskPath}\`: failed check(s) ${result.failures.join(', ')}`);
+    lines.push(result.taskPath === 'feature-receipt.md'
+      ? `  Run final integration proof, then write \`specs/${active.featureName}/feature-receipt.md\`.`
+      : `  Write canonical proof to \`specs/${active.featureName}/receipts/${path.posix.basename(result.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',
@@ -88,4 +214,5 @@ try {
   })}\n`);
 } catch (error) {
   logCrash('spec-gate', error);
+  emitBlock(`Completion gate controlled failure: ${error.message}. Completion is blocked until the hook is repaired.`);
 }

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

@@ -10,11 +10,11 @@ const {
   logCrash,
   readPayload
 } = require('./lib/hook-context.cjs');
-const { findActiveSpec } = require('./lib/spec-utils.cjs');
-const policyPath = path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs');
-const POLICY = require(fs.existsSync(policyPath)
-  ? policyPath
-  : path.join(__dirname, '../../claude/scripts/workflow-policy.cjs'));
+const { loadSharedPolicy, loadSharedReceipt } = require('./lib/spec-receipt.cjs');
+
+function emitControlledFailure(reason) {
+  process.stdout.write(`> ⚠️ Spec tollgate unavailable: ${reason}. Repair the installed workflow policy before continuing.\n`);
+}
 
 function cacheFile(projectRoot, sessionId) {
   const key = crypto.createHash('sha256')
@@ -27,10 +27,45 @@ function cacheFile(projectRoot, sessionId) {
 try {
   const payload = readPayload();
   if (!payload) process.exit(0);
+  const loaded = loadSharedPolicy();
+  if (!loaded.policy) {
+    logCrash('spec-state', loaded.error);
+    emitControlledFailure(loaded.error.message);
+    process.exit(0);
+  }
+  const POLICY = loaded.policy;
+  const receiptLoaded = loadSharedReceipt();
+  if (!receiptLoaded.receipt) throw receiptLoaded.error;
+  const RECEIPT = receiptLoaded.receipt;
   const { projectRoot, runtime } = getHookContext(payload);
   if (runtime.spec?.tollgate === false) process.exit(0);
-  const active = findActiveSpec(projectRoot, runtime);
-  if (!active) process.exit(0);
+  const { resolveActiveSpec } = require('./lib/spec-utils.cjs');
+  const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
+  const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
+  const resolved = resolveActiveSpec(projectRoot, runtime, explicitFeature, explicitPath);
+  if (!resolved) process.exit(0);
+  if (resolved.error === 'multiple_active') {
+    process.stdout.write(`> ⚠️ Multiple active specs detected: ${resolved.candidates.join(', ')}. Provide explicit feature target or resolve ambiguity. Tollgate paused.\n`);
+    process.exit(0);
+  }
+  if (resolved.error === 'invalid_specs') {
+    process.stdout.write(`> ⚠️ Invalid spec JSON detected: ${resolved.candidates.join(', ')}. ${resolved.reason}. Fix or remove malformed spec.json. Tollgate paused.\n`);
+    process.exit(0);
+  }
+  if (resolved.error === 'explicit_not_found' || resolved.error === 'explicit_malformed') {
+    const detail = resolved.reason || resolved.explicitFeature || resolved.explicitPath || 'unknown';
+    process.stdout.write(`> ⚠️ Explicit spec target invalid (${resolved.error}): ${detail}. Provide a valid feature target inside configured specs root. Tollgate paused.\n`);
+    process.exit(0);
+  }
+  if (resolved.error) process.exit(0);
+  const active = resolved;
+  const runtimeContext = POLICY.deriveRuntimeContext({
+    projectRoot,
+    specsRoot: active.specsDir,
+    specFile: active.specFile || path.join(active.specsDir, active.featureName, 'spec.json'),
+    featureName: active.featureName,
+    runtimeSession: payload.session_id || payload.sessionId || payload.sessionID || payload.session?.id,
+  });
 
   const phase = active.spec.current_phase || active.spec.phase || 'unknown';
   const taskRegistry = active.spec.task_registry || {};
@@ -49,8 +84,24 @@ try {
     (task?.status || 'pending') === 'pending'
     && (task?.dependencies || []).every((dependency) => statuses.get(dependency) === 'done')
   ));
-  const stateKey = `${active.featureName}|${phase}|${counts.done || 0}/${tasks.length}`;
-  const cache = cacheFile(projectRoot, payload.session_id);
+  const featureDir = path.join(active.specsDir, active.featureName);
+  const featureReceiptPresent = RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
+  const stateKey = JSON.stringify({
+    project_root: runtimeContext.project_root,
+    specs_root: runtimeContext.specs_root,
+    spec_file: runtimeContext.spec_file,
+    feature_name: runtimeContext.feature_name,
+    runtime_session: runtimeContext.runtime_session,
+    provenance_mode: runtimeContext.provenance_mode,
+    Base: runtimeContext.base,
+    Head: runtimeContext.head,
+    context_id: runtimeContext.context_id,
+    phase,
+    done: counts.done || 0,
+    total: tasks.length,
+    feature_receipt_present: featureReceiptPresent,
+  });
+  const cache = cacheFile(projectRoot, runtimeContext.runtime_session);
   let previous = '';
   try { previous = fs.readFileSync(cache, 'utf8').trim(); } catch { /* first run */ }
 
@@ -69,14 +120,16 @@ try {
   ];
   if (next) lines.push(`- Next unblocked: \`${next[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` and the task file only after verified work.',
+    '- Sync `spec.json` and task Markdown status only after verified work; task proof belongs in `receipts/<task-basename>.md`.',
+    `- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`,
     `- Validate with \`node .codex/scripts/validate-spec-output.cjs specs/${active.featureName}\`.`,
-    '- The Stop completion gate checks receipts for newly-done tasks.'
+    '- Hooks revalidate receipt bytes but never grant approval.'
   );
   process.stdout.write(`${lines.join('\n')}\n`);
 } catch (error) {
   logCrash('spec-state', error);
+  emitControlledFailure(error.message);
 }

package/src/codex/hooks/state.cjs

@@ -140,6 +140,7 @@ try {
       refreshGit(data, projectRoot);
       writeData(dir, data);
     });
+    process.stdout.write('{}\n');
     process.exit(0);
   }
 
@@ -151,6 +152,7 @@ try {
       writeData(dir, data);
       archive(dir);
     });
+    process.stdout.write('{}\n');
   }
 } catch (error) {
   logCrash('state', error);