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

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

@@ -10,7 +10,40 @@ const EVIDENCE_NAMES = [
 ];
 const PASS_MARKER = /^\s*Verification:\s*PASS\s*$/m;
 const LEGACY_SUCCESS = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
-const EXPLICIT_FAILURE = /\bFAIL(?:ED|URE|URES|ING)?\b|tests?\s+failed|exit\s+code\s*[:=]?\s*[1-9]\d*|\b0\s+tests?\b/i;
+
+// Single authority: delegate to shared workflow-policy validator. If an
+// installed policy exists but is broken, do not fall back to another copy.
+function loadSharedPolicy() {
+  const installed = path.join(__dirname, '../../scripts/workflow-policy.cjs');
+  const repo = path.join(__dirname, '../../../claude/scripts/workflow-policy.cjs');
+  const candidates = fs.existsSync(installed) ? [installed] : [repo];
+  let lastError = new Error('shared workflow policy is missing');
+  for (const candidate of candidates) {
+    try {
+      const policy = require(candidate);
+      if (typeof policy?.validateCanonicalReceipt !== 'function') {
+        throw new Error('shared workflow policy has no validateCanonicalReceipt function');
+      }
+      return { policy, error: null, path: candidate };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  return { policy: null, error: lastError, path: candidates[0] };
+}
+
+function getSharedPolicy() {
+  return loadSharedPolicy().policy;
+}
+
+function getSharedValidate() {
+  return loadSharedPolicy().policy?.validateCanonicalReceipt || null;
+}
+
+function isTapMetadataHeading(line) {
+  const policy = getSharedPolicy();
+  return typeof policy?.isTapMetadataHeading === 'function' && policy.isTapMetadataHeading(line);
+}
 
 function evidenceBody(text) {
   const lines = text.split('\n');
@@ -28,7 +61,7 @@ function evidenceBody(text) {
   let end = lines.length;
   for (let index = start; index < lines.length; index += 1) {
     const heading = lines[index].match(/^(#{1,6})\s+/);
-    if (heading && heading[1].length <= level) {
+    if (heading && heading[1].length <= level && !isTapMetadataHeading(lines[index])) {
       end = index;
       break;
     }
@@ -37,37 +70,29 @@ function evidenceBody(text) {
 }
 
 function safeTaskFile(featureDir, taskPath) {
+  const resolvedFeature = path.resolve(featureDir);
   const target = path.resolve(featureDir, taskPath);
-  const relative = path.relative(featureDir, target);
+  const relative = path.relative(resolvedFeature, target);
   if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+  if (!fs.existsSync(target)) return null;
+  try {
+    const canonicalFeature = fs.realpathSync(resolvedFeature);
+    const canonicalTarget = fs.realpathSync(target);
+    const rel = path.relative(canonicalFeature, canonicalTarget);
+    if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
+  } catch {
+    return null;
+  }
   return target;
 }
 
-function validateCanonicalReceipt(body) {
-  const failures = [];
-  if (!/^\s*Verification:\s*PASS\s*$/m.test(body)) {
-    failures.push('verification_state');
-  }
-  if (!/^\s*Command(?:\(s\))?\s*:/m.test(body)) {
-    failures.push('command');
-  }
-  if (!/^\s*Exit\s*:|exit\s+code\s*[:=]|\bResult\s*:\s*PASS\b/im.test(body)) {
-    failures.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))) {
-    failures.push('provenance');
-  }
-  if (/\bartifact\b/i.test(body) && !/sha256:/i.test(body)) {
-    failures.push('artifact_hash');
-  }
-  return failures;
+function validateCanonicalReceipt(body, options = {}) {
+  const fn = getSharedValidate();
+  if (!fn) return ['shared_validator'];
+  return fn(body, options);
 }
 
-function checkReceipt(featureDir, taskPath, task) {
+function checkReceipt(featureDir, taskPath, task, runtimeContext) {
   const failures = [];
   const file = safeTaskFile(featureDir, taskPath);
   if (!file || !fs.existsSync(file)) return ['a'];
@@ -83,37 +108,38 @@ function checkReceipt(featureDir, taskPath, task) {
     failures.push('b');
   } else if (
     /\{\{[^}]+\}\}/.test(body)
-    || EXPLICIT_FAILURE.test(body)
     || !(PASS_MARKER.test(body) || LEGACY_SUCCESS.test(body))
   ) {
     failures.push('c');
   } else {
-    // Canonical receipt requirements: command, exit/result, provenance, unambiguous PASS
-    // For done tasks, require canonical fields. If missing, add e/f/g.
-    const canonical = validateCanonicalReceipt(body);
-    // Map canonical failures to letters e,f,g,h for backward compat checks
-    // Use detailed names but also add letters for gate reporting
+    const policy = loadSharedPolicy().policy;
+    const options = typeof policy?.receiptValidatorOptions === 'function'
+      ? policy.receiptValidatorOptions(task, { runtimeContext, requireProvenanceBinding: true })
+      : { requireProvenanceBinding: true };
+    const canonical = validateCanonicalReceipt(body, options);
     const map = {
-      verification_state: 'c', // already covers but keep distinct
+      verification_state: 'c',
       command: 'e',
       exit_result: 'f',
       provenance: 'g',
       artifact_hash: 'h',
+      artifact_declaration: 'h',
+      placeholder: 'c',
+      shared_validator: 'c',
+      validator_unavailable: 'c',
     };
     for (const fail of canonical) {
-      const letter = map[fail];
-      // Avoid duplicating c if already failed, but add specific
-      if (fail === 'verification_state' && failures.includes('c')) continue;
-      if (fail === 'verification_state') {
-        // This should have been caught by c, but if PASS present via legacy, still need strict PASS
-        if (!PASS_MARKER.test(body)) failures.push('c');
+      if (fail === 'verification_state' || fail === 'shared_validator' || fail === 'validator_unavailable') {
+        if (!failures.includes('c')) failures.push('c');
         continue;
       }
+      if (fail === 'placeholder') {
+        if (!failures.includes('c')) failures.push('c');
+        continue;
+      }
+      const letter = map[fail];
       if (letter && !failures.includes(letter)) failures.push(letter);
     }
-    // Additional strict check: legacy success alone is not sufficient for canonical
-    // If body contains only legacy PASS but not canonical Verification: PASS, c already would have caught if no PASS_MARKER?
-    // But we allow legacy for backward compat in c, but canonical requires PASS_MARKER, so we must enforce.
     if (!PASS_MARKER.test(body)) {
       if (!failures.includes('c')) failures.push('c');
     }
@@ -128,4 +154,11 @@ function checkReceipt(featureDir, taskPath, task) {
   return failures;
 }
 
-module.exports = { checkReceipt, evidenceBody, safeTaskFile, validateCanonicalReceipt };
+module.exports = {
+  checkReceipt,
+  evidenceBody,
+  safeTaskFile,
+  validateCanonicalReceipt,
+  loadSharedPolicy,
+  getSharedPolicy,
+};

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

@@ -2,49 +2,75 @@
 
 const fs = require('fs');
 const path = require('path');
-const { resolveProjectPath } = require('./hook-context.cjs');
+
+// Installed Codex hooks use .codex/scripts; source tests use the Claude-side
+// source path. If an installed resolver exists but is malformed, do not fall
+// back to another copy: the shared authority is unavailable.
+const RESOLVER_CANDIDATES = [
+  path.join(__dirname, '../../scripts/spec-resolver.cjs'),
+  path.join(__dirname, '../../../claude/scripts/spec-resolver.cjs'),
+];
+
+function sharedResolver() {
+  const candidate = RESOLVER_CANDIDATES.find((file) => fs.existsSync(file)) || RESOLVER_CANDIDATES[0];
+  try {
+    const resolver = require(candidate);
+    if (typeof resolver?.resolveActiveSpec !== 'function') {
+      throw new Error('shared spec resolver has no resolveActiveSpec function');
+    }
+    return resolver;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message} (${candidate})`);
+  }
+}
 
 function specsDirectory(projectRoot, runtime) {
-  return resolveProjectPath(
+  return sharedResolver().specsDirectory(projectRoot, runtime);
+}
+
+function findAllActiveSpecs(projectRoot, runtime) {
+  return sharedResolver().findAllActiveSpecs(projectRoot, runtime);
+}
+
+function findAllSpecCandidates(projectRoot, runtime) {
+  return sharedResolver().findAllSpecCandidates(projectRoot, runtime);
+}
+
+function resolveActiveSpec(projectRoot, runtime, explicitFeature, explicitPath) {
+  if (projectRoot && typeof projectRoot === 'object') {
+    return sharedResolver().resolveActiveSpec(projectRoot);
+  }
+  return sharedResolver().resolveActiveSpec({
     projectRoot,
-    runtime.paths?.specs,
-    'specs'
-  );
+    runtime,
+    explicitFeature,
+    explicitPath,
+  });
 }
 
 function findActiveSpec(projectRoot, runtime) {
-  const specsDir = specsDirectory(projectRoot, runtime);
-  if (!fs.existsSync(specsDir)) return null;
-  const entries = fs.readdirSync(specsDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .sort((left, right) => left.name.localeCompare(right.name));
-
-  for (const entry of entries) {
-    const file = path.join(specsDir, entry.name, 'spec.json');
-    if (!fs.existsSync(file)) continue;
-    try {
-      const spec = JSON.parse(fs.readFileSync(file, 'utf8'));
-      if (spec.status === 'in_progress' || spec.status === 'in-progress') {
-        return { featureName: entry.name, spec, specsDir };
-      }
-    } catch {
-      // Ignore an unrelated malformed spec and continue discovery.
-    }
-  }
-  return null;
+  const resolved = resolveActiveSpec(projectRoot, runtime);
+  if (!resolved) return null;
+  if (resolved.error === 'multiple_active' || resolved.error === 'invalid_specs') return resolved;
+  if (resolved.error) return null;
+  return resolved;
 }
 
 function taskStatusMap(spec) {
   return Object.fromEntries(
     Object.entries(spec.task_registry || {}).map(([taskPath, task]) => [
       taskPath,
-      task?.status || 'pending'
-    ])
+      task?.status || 'pending',
+    ]),
   );
 }
 
 module.exports = {
   findActiveSpec,
+  findAllActiveSpecs,
+  findAllSpecCandidates,
+  resolveActiveSpec,
   specsDirectory,
-  taskStatusMap
+  taskStatusMap,
 };

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,93 @@ 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 { checkReceipt, evidenceBody, loadSharedPolicy } = require('./lib/spec-receipt.cjs');
+const { taskStatusMap } = require('./lib/spec-utils.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;
+}
+
+function readReceiptBody(featureDir, taskPath) {
+  const featureRoot = path.resolve(featureDir);
+  const target = path.resolve(featureRoot, taskPath);
+  const relative = path.relative(featureRoot, target);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+  try {
+    const canonicalFeature = fs.realpathSync(featureRoot);
+    const canonicalTarget = fs.realpathSync(target);
+    const canonicalRelative = path.relative(canonicalFeature, canonicalTarget);
+    if (canonicalRelative === '..' || canonicalRelative.startsWith(`..${path.sep}`) || path.isAbsolute(canonicalRelative)) return null;
+    return evidenceBody(fs.readFileSync(canonicalTarget, 'utf8'));
+  } catch (_) {
+    return 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 explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
+  const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
+  const { resolveActiveSpec } = require('./lib/spec-utils.cjs');
+  const resolved = resolveActiveSpec(projectRoot, runtime, explicitFeature, explicitPath);
+  if (!resolved) process.exit(0);
+  if (resolved.error === 'multiple_active') {
+    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 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 +114,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,24 +143,43 @@ 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 body = readReceiptBody(featureDir, taskPath);
+      if (body !== null) receiptBodies.set(taskPath, body);
+      return {
+        taskPath,
+        failures: checkReceipt(featureDir, taskPath, registry[taskPath], runtimeContext)
+      };
+    })
     .filter((result) => result.failures.length);
 
+  const firstReceiptTask = allDoneTasks.find((taskPath) => receiptBodies.has(taskPath));
+  const completion = allDoneTasks.length > 0 && Object.prototype.hasOwnProperty.call(active.spec, 'workflow_policy')
+    ? POLICY.completionDecisionForSpec(active.spec, {
+      runtimeContext,
+      executionReceipt: firstReceiptTask ? receiptBodies.get(firstReceiptTask) : null,
+      taskContext: firstReceiptTask ? registry[firstReceiptTask] : null,
+    })
+    : 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} newly-done task(s) lack a verification receipt.`
+      : 'Completion gate: workflow completion proof is incomplete.'
   ];
   for (const result of failures) {
     lines.push(
@@ -82,10 +187,17 @@ try {
       `  Add \`Verification: PASS\`, commands, and successful outcomes under \`## Evidence\` in \`specs/${active.featureName}/${result.taskPath}\`, then re-sync spec.json.`
     );
   }
+  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`);
 } 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 } = 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,42 @@ 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 { 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 +81,21 @@ 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 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,
+  });
+  const cache = cacheFile(projectRoot, runtimeContext.runtime_session);
   let previous = '';
   try { previous = fs.readFileSync(cache, 'utf8').trim(); } catch { /* first run */ }
 
@@ -69,7 +114,7 @@ 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.',
@@ -79,4 +124,5 @@ try {
   process.stdout.write(`${lines.join('\n')}\n`);
 } catch (error) {
   logCrash('spec-state', error);
+  emitControlledFailure(error.message);
 }

package/src/codex/hooks.json

@@ -43,6 +43,11 @@
             "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-approval.cjs\"",
             "commandWindows": "node \".codex/hooks/privacy-approval.cjs\""
           },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/completion-authority.cjs\"",
+            "commandWindows": "node \".codex/hooks/completion-authority.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/rules.cjs\"",
@@ -98,6 +103,11 @@
             "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-gate.cjs\"",
             "commandWindows": "node \".codex/hooks/spec-gate.cjs\""
           },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/completion-authority.cjs\"",
+            "commandWindows": "node \".codex/hooks/completion-authority.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",

package/src/opencode/AGENTS.md

@@ -28,9 +28,11 @@ The underlying CafeKit skills are still named `hapo:*` in their documentation.
 
 ## OpenCode limits
 
-Claude Code hooks, statusline, and settings do not run in OpenCode. Map Claude-only tools to OpenCode built-ins: `TodoWrite` → `todowrite`, `AskUserQuestion` → `question`, `Task` → the agent/subtask flow. The installed plugins under `.opencode/plugins/` provide the privacy, inspect-scope, spec-state, scaffold-guard, session-state, and docs-sync gates; other Claude runtime behavior has no OpenCode equivalent. The completion gate (`spec-gate`: `Verification: PASS` + `## Evidence` + `task_registry.completed_at`) is **advisory in OpenCode** — OpenCode has no Stop-hook equivalent and the `spec-gate` plugin (if present) runs as a best-effort `tool.execute.after` check, not a hard turn block like Claude/Codex.
+Claude Code hooks, statusline, and settings do not run in OpenCode. Map Claude-only tools to OpenCode built-ins: `TodoWrite` → `todowrite`, `AskUserQuestion` → `question`, `Task` → the agent/subtask flow. The installed plugins under `.opencode/plugins/` provide the privacy, inspect-scope, spec-state, scaffold-guard, session-state, and docs-sync gates; other Claude runtime behavior has no OpenCode equivalent.
 
-Runtime tier: OpenCode is **tier-2** for completion enforcement. Do not claim parity with Claude/Codex on `completion_gate`; `done` without a receipt emits an advisory warning/banner but does not hard-block the turn — rely on `spec-state` tollgate + manual `/hapo:test` verification.
+The installed `spec-gate` plugin uses the cancellable `tool.execute.before` hook to hard-block supported completion/state tools (`task`, `taskupdate`, and `todowrite`) with a controlled `CAFEKIT_SPEC_GATE_BLOCKED` result when shared policy/resolver or receipt evidence is invalid or unavailable. Receipt-repair tools remain available where the host boundary permits correction.
+
+OpenCode does not expose a cancellable `session.idle`/Stop hook or final assistant-turn cancellation boundary. Those event and prompt-injection paths are observational only; do not claim full-turn parity with Claude/Codex.
 
 ## Combined-install boundary