@haposoft/cafekit 0.18.0 → 0.18.2

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

@@ -1,218 +1,6 @@
 #!/usr/bin/env node
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
-const {
-  APPROVAL_PREFIX,
-  createPending,
-  hasGrant
-} = require('./lib/privacy-state.cjs');
-const {
-  getHookContext,
-  readPayload
-} = require('./lib/hook-context.cjs');
-const { commandAccess } = require('./lib/privacy-command-analysis.cjs');
-
-const RESTRICTED = [
-  /^\.env(?:[.\[*?{]|$)/i,
-  /^credentials/i,
-  /secrets?\.(ya?ml|json)$/i,
-  /\.pem$/i,
-  /\.key$/i,
-  /\.p12$/i,
-  /\.pfx$/i,
-  /^id_(rsa|ed25519|ecdsa|dsa)$/i,
-  /\.netrc$/i,
-  /\.pgpass$/i,
-  /kubeconfig/i,
-  /\.keystore$/i,
-  /\.jks$/i,
-  /auth\.json$/i,
-  /token(s)?\.json$/i
-];
-
-const EXEMPT = [/\.env\.(example|sample|template|test)$/i];
-
-function isPathKey(key) {
-  return /^(?:file_?paths?|paths?|search_?paths?|director(?:y|ies)|cwd|root|locations?)$/i
-    .test(key);
-}
-
-function matchesAny(filePath, rules) {
-  const base = path.basename(filePath);
-  return rules.some((rule) => rule.test(base) || rule.test(filePath));
-}
-
-function isSafe(filePath) {
-  return matchesAny(filePath, EXEMPT);
-}
-
-function isSensitive(filePath) {
-  return matchesAny(filePath, RESTRICTED);
-}
-
-function resolveTarget(filePath, cwd) {
-  try {
-    const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-    return fs.realpathSync(requested);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 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;
-  }
-}
-
-function extractCommandPaths(command) {
-  // The analyzer parses the command and returns the operands of every reading
-  // command it recognises, nested shells and `find -exec` included. Treating
-  // every unresolved expansion as sensitive, as this did before, denied
-  // `cat $FILE`, `wc -l *.cjs` and `cat ~/.zshrc` alike -- and every denial here
-  // costs a round trip through a one-shot approval prompt.
-  // A heredoc whose delimiter is quoted (<<'BODY') is inert: the shell expands
-  // nothing inside it, so no word in the body is ever read. The analyzer has no
-  // notion of heredocs and parses the body as shell, so prose that quotes a
-  // command -- a PR body carrying `cat .env` in backticks -- came back as a real
-  // command substitution. Blank those bodies out first. An unquoted delimiter
-  // (<<BODY) does expand, so it is left to the analyzer.
-  const scrubbed = String(command).replace(
-    /(<<-?[ \t]*)(['"])([A-Za-z_]\w*)\2[^\n]*\n[\s\S]*?\n[ \t]*\3\b/g,
-    '$1$2$3$2'
-  );
-
-  const paths = new Set(commandAccess(scrubbed).paths);
-
-  // Two shapes the analyzer cannot return. It drops any word carrying an
-  // expansion, so `~/.ssh/id_rsa` and `certs/*.pem` still have to be matched by
-  // name. And it only walks commands it recognises, so an unknown tool handed a
-  // secret through a file-shaped option, such as
-  // `docker compose --env-file .env`, is invisible to it.
-  const FILE_OPTION = /^--?[\w-]*(?:file|config|key|cert|identity)$/i;
-  const tokens = scrubbed.split(/[\s|;&<>"'()`]+/);
-  for (let index = 0; index < tokens.length; index += 1) {
-    const token = tokens[index];
-    const shaped = /^~|[*?[{]/.test(token);
-    const optionFed = index > 0 && FILE_OPTION.test(tokens[index - 1]);
-    if (!shaped && !optionFed) continue;
-    const value = token.replace(/^~/, '').replace(/^["'()`]+|["'(),]+$/g, '');
-    if (value && isSensitive(value) && !isSafe(value)) paths.add(value);
-  }
-
-  return [...paths];
-}
-
-function extractPatchPaths(patch) {
-  return [...String(patch).matchAll(
-    /^\*\*\* (?:(?:Add|Update|Delete) File:|Move to:)\s+(.+)$/gm
-  )]
-    .map((match) => match[1].trim())
-    .filter(Boolean);
-}
-
-function shellInput(input) {
-  if (typeof input?.command === 'string') return input.command;
-  if (typeof input?.cmd === 'string') return input.cmd;
-  return '';
-}
-
-function patchInput(input) {
-  if (typeof input === 'string') return input;
-  for (const key of ['command', 'patch', 'input']) {
-    if (typeof input?.[key] === 'string') return input[key];
-  }
-  return '';
-}
-
-function collectPathValues(value, key, out) {
-  if (typeof value === 'string' && isPathKey(key)) {
-    out.push(value);
-    return;
-  }
-  if (Array.isArray(value)) {
-    if (isPathKey(key)) out.push(...value.filter((item) => typeof item === 'string'));
-    return;
-  }
-  if (!value || typeof value !== 'object') return;
-  for (const [childKey, childValue] of Object.entries(value)) {
-    collectPathValues(childValue, childKey, out);
-  }
-}
-
-function extractPaths(toolName, input) {
-  const paths = [];
-  collectPathValues(input, '', paths);
-  const normalizedTool = String(toolName).toLowerCase();
-  if (['bash', 'exec_command', 'shell'].includes(normalizedTool)) {
-    paths.push(...extractCommandPaths(shellInput(input)));
-  } else if (['apply_patch', 'edit', 'write'].includes(normalizedTool)) {
-    paths.push(...extractPatchPaths(patchInput(input)));
-  }
-  return [...new Set(paths.filter(Boolean))];
-}
-
-function sensitiveRequest(filePath, cwd) {
-  const target = resolveTarget(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);
-}
-
-function sensitivePaths(toolName, input, cwd) {
-  return extractPaths(toolName, input)
-    .filter((filePath) => sensitiveRequest(filePath, cwd));
-}
-
 function deny(reason) {
   process.stdout.write(`${JSON.stringify({
     hookSpecificOutput: {
@@ -224,9 +12,14 @@ function deny(reason) {
 }
 
 try {
+  const { APPROVAL_PREFIX, createPending, hasGrant } = require('./lib/privacy-state.cjs');
+  const { PROJECT_ROOT, readRuntime, resolveSessionCwd, readPayload } = require('./lib/hook-context.cjs');
+  const { sensitivePaths } = require('./lib/privacy-paths.cjs');
   const data = readPayload();
   if (!data) process.exit(0);
-  const { projectRoot, sessionCwd, runtime } = getHookContext(data);
+  const projectRoot = PROJECT_ROOT;
+  const runtime = readRuntime(PROJECT_ROOT);
+  const sessionCwd = resolveSessionCwd(data);
   if (runtime.privacyBlock === false) process.exit(0);
 
   const filePaths = sensitivePaths(data.tool_name || '', data.tool_input || {}, sessionCwd);
@@ -250,8 +43,9 @@ try {
   const pending = createPending(grantInput);
   deny(
     `Sensitive file access denied: ${pending.displayName}. ` +
-    `To approve access to exactly these paths for the next hour of this Codex ` +
-    `session, send this exact user prompt: ` +
+    `To allow exactly these paths for one hour of this Codex session, the user replies ` +
+    `y (or yes / có) as their very next message; any other reply cancels that shortcut, ` +
+    `and it only works while this is the only pending request. Fallback exact prompt: ` +
     `${APPROVAL_PREFIX}${pending.requestId}`
   );
   process.exit(0);

package/src/codex/hooks/rules.cjs

@@ -1,40 +1,14 @@
 'use strict';
 
-const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const {
-  getHookContext,
-  hookStateDir,
+  PROJECT_ROOT,
   logCrash,
   readPayload,
   resolveProjectPath
 } = require('./lib/hook-context.cjs');
-
-function reservationFile(projectRoot, sessionId) {
-  const key = crypto.createHash('sha256')
-    .update(String(sessionId || 'unknown'))
-    .digest('hex')
-    .slice(0, 16);
-  return path.join(hookStateDir(projectRoot), `rules-${key}.json`);
-}
-
-/** Reserve one injection slot per session. Returns null on reservation errors. */
-function reserveSession(projectRoot, sessionId) {
-  if (!sessionId) return null;
-  try {
-    const file = reservationFile(projectRoot, sessionId);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify({ sessionId: String(sessionId) }), {
-      encoding: 'utf8',
-      flag: 'wx',
-      mode: 0o600
-    });
-    return true;
-  } catch (error) {
-    return error.code === 'EEXIST' ? false : null;
-  }
-}
+const { reserveSession } = require('./lib/rules-reservation.cjs');
 
 /**
  * Body of the output style for `codingLevel`, or null.
@@ -70,10 +44,10 @@ function readRuntime(projectRoot) {
 try {
   const payload = readPayload();
   if (!payload) process.exit(0);
-  const { projectRoot } = getHookContext(payload);
-  if (reserveSession(projectRoot, payload.session_id) !== true) process.exit(0);
+  const projectRoot = PROJECT_ROOT;
   const runtime = readRuntime(projectRoot);
   if (runtime === null) process.exit(0);
+  if (reserveSession(projectRoot, payload.session_id) !== true) process.exit(0);
 
   const respondLang = runtime.locale?.responseLanguage || '';
   const thinkLang = runtime.locale?.thinkingLanguage || (respondLang ? 'en' : '');

package/src/codex/hooks/secret-output-guardrail.cjs

@@ -15,9 +15,9 @@
  */
 
 const { logCrash, readPayload } = require('./lib/hook-context.cjs');
-const { REMINDER, containsSecretKeyword } = require('./lib/secret-keywords.cjs');
 
 try {
+  const { REMINDER, containsSecretKeyword } = require('./lib/secret-keywords.cjs');
   const payload = readPayload();
   if (!payload) process.exit(0);
 

package/src/codex/hooks/session.cjs

@@ -3,13 +3,18 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const {
-  getHookContext,
+  PROJECT_ROOT,
+  hookStateDir,
+  readRuntime,
+  resolveSessionCwd,
   logCrash,
   readPayload
 } = require('./lib/hook-context.cjs');
 const { clearState } = require('./lib/privacy-state.cjs');
+const { clearSessionReservation } = require('./lib/rules-reservation.cjs');
 
 function readPackage(projectRoot) {
   try {
@@ -69,10 +74,48 @@ function gitBranch(projectRoot) {
   }
 }
 
+function printCompactAnchors(projectRoot, sessionId) {
+  if (!sessionId) return;
+  try {
+    const key = crypto.createHash('sha256').update(sessionId).digest('hex');
+    const file = path.join(hookStateDir(projectRoot), `compact-recovery-${key}.json`);
+    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (record.session_id !== sessionId) return;
+    const parts = [];
+    if (record.branch) parts.push(`branch ${record.branch}`);
+    if (record.head) parts.push(`HEAD ${record.head}`);
+    if (typeof record.dirty_count === 'number') parts.push(`${record.dirty_count} uncommitted path(s)`);
+    process.stdout.write('\n=== State before compaction ===\n');
+    if (record.captured_at) process.stdout.write(`Captured: ${record.captured_at}\n`);
+    if (parts.length) process.stdout.write(`Repository: ${parts.join(' | ')}\n`);
+    process.stdout.write('Re-read these from disk before acting; they describe the moment before compaction.\n');
+    process.stdout.write('=== End of pre-compaction state ===\n');
+  } catch { /* no matching capture available */ }
+}
+
+(async () => {
 try {
   const payload = readPayload();
   if (!payload) process.exit(0);
-  const { projectRoot, runtime, sessionCwd } = getHookContext(payload);
+  // Invalidate this session before runtime configuration can interrupt startup.
+  const sessionId = [payload.session_id, payload.sessionId, payload.sessionID, payload.session?.id]
+    .find((value) => typeof value === 'string' && value.trim());
+  clearState(PROJECT_ROOT, sessionId);
+  let updateNotice = '';
+  try {
+    const { checkCafeKitUpdate } = require('./lib/update-check.cjs');
+    updateNotice = await checkCafeKitUpdate(path.join(PROJECT_ROOT, '.codex'));
+  } catch { /* an update failure must not interrupt session startup */ }
+  if (payload.source === 'compact') {
+    clearSessionReservation(PROJECT_ROOT, sessionId);
+    process.stdout.write(
+      'Session compacted. Pending confirmations may have been lost. Pending CafeKit privacy approvals were invalidated; request fresh user approval before continuing.\n'
+    );
+    printCompactAnchors(PROJECT_ROOT, sessionId);
+  }
+  const projectRoot = PROJECT_ROOT;
+  const runtime = readRuntime(PROJECT_ROOT);
+  const sessionCwd = resolveSessionCwd(payload);
   const pkg = readPackage(projectRoot);
   const configured = runtime.project || {};
   const projectType = configured.type && configured.type !== 'auto'
@@ -86,9 +129,6 @@ try {
     : detectFramework(pkg);
   const branch = gitBranch(projectRoot);
 
-  // Approval tokens never survive a session boundary or compaction.
-  clearState(projectRoot);
-
   // Orca (onorca.dev) sets ORCA_PANE_KEY in every pane; it is a presence marker, not a
   // secret. ORCA_AGENT_HOOK_TOKEN and ORCA_AGENT_LAUNCH_TOKEN live in the same
   // environment and must never be read or printed here.
@@ -101,7 +141,7 @@ try {
     insideOrcaPane && 'Orca: pane'
   ].filter(Boolean);
   process.stdout.write(
-    `Session ${payload.source || 'unknown'}. ${parts.join(' | ') || 'No project info detected.'}\n`
+    `Session ${payload.source || 'unknown'}. ${parts.join(' | ') || 'No project info detected.'}${updateNotice}\n`
   );
 
   if (sessionCwd !== projectRoot) {
@@ -109,11 +149,7 @@ try {
       `CafeKit project root: ${projectRoot} (session working directory: ${sessionCwd}).\n`
     );
   }
-  if (payload.source === 'compact') {
-    process.stdout.write(
-      'Session compacted. Pending CafeKit privacy approvals were invalidated; request fresh user approval if needed.\n'
-    );
-  }
 } catch (error) {
   logCrash('session', error);
 }
+})();

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

@@ -11,14 +11,11 @@ const {
   readPayload
 } = require('./lib/hook-context.cjs');
 const {
-  checkFeatureReceipt,
-  checkReceiptDetails,
   checkWorkflowReceiptDetails,
   checkWorkflowReceiptSet,
   loadSharedPolicy,
   receiptFixHint,
 } = require('./lib/spec-receipt.cjs');
-const { taskStatusMap } = require('./lib/spec-utils.cjs');
 
 function emitBlock(reason) {
   process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\n`);
@@ -34,6 +31,7 @@ function sessionIdentity(payload) {
   return candidates.find((value) => typeof value === 'string' && value.trim() !== '') || null;
 }
 
+let hasDoneTasks = false;
 try {
   const payload = readPayload();
   if (payload.stop_hook_active === true) process.exit(0);
@@ -44,8 +42,10 @@ try {
     process.exit(0);
   }
   const POLICY = loaded.policy;
+  // Match Claude: one invocation validates receipts against one checkout snapshot.
+  require(path.join(path.dirname(loaded.path), 'provenance.cjs')).enableSnapshotMemo();
   const { projectRoot, runtime } = getHookContext(payload);
-  if (typeof POLICY.completionDecisionForSpec !== 'function') {
+  if (typeof POLICY.deriveRuntimeContext !== 'function') {
     throw new Error('shared workflow policy lacks completion authority functions');
   }
   const resolver = require('./lib/spec-utils.cjs');
@@ -59,6 +59,8 @@ try {
   }
   if (!resolved) process.exit(0);
   if (resolved.layoutKind === 'process-v3-completed-set') {
+    hasDoneTasks = resolved.candidates.some(candidate =>
+      Object.values(candidate.taskRegistry || {}).some(task => task?.status === 'done'));
     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.');
@@ -88,7 +90,7 @@ try {
   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.`
+      reason: `Completion gate: invalid workflow packet detected (${resolved.candidates.join(', ')}): ${resolved.reason}. Fix the packet's plan.md or task files before completing tasks.`
     })}\n`);
     process.exit(0);
   }
@@ -101,20 +103,11 @@ try {
   }
   if (resolved.error) process.exit(0);
   const active = resolved;
-  const activeSpec = active.spec || {};
-  const processWorkflow = active.layoutKind === 'process-v3';
-  const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
-  const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
-    || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
-  // Legacy 2.1 closeout is retired; a 2.1 packet mid-execution keeps the ordinary receipt checks.
-  if (!processWorkflow && activeSpec.schema_version === '2.1' && explicitCloseout) {
-    emitBlock('Completion gate: Legacy spec.json closeout is no longer supported; move the packet to plan.md with flat task files');
-    process.exit(0);
-  }
+  hasDoneTasks = Object.values(active.taskRegistry || {}).some(task => task?.status === 'done');
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot,
     specsRoot: active.specsDir,
-    specFile: active.stateFile || active.specFile || path.join(active.specsDir, active.featureName, 'spec.json'),
+    specFile: active.stateFile,
     featureName: active.featureName,
     runtimeSession: sessionIdentity(payload),
   });
@@ -123,10 +116,10 @@ try {
     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.taskRegistry || activeSpec.task_registry || {};
-  const currentStatuses = processWorkflow
-    ? Object.fromEntries(Object.entries(registry).map(([taskPath, task]) => [taskPath, task?.status || 'pending']))
-    : taskStatusMap(activeSpec);
+  const registry = active.taskRegistry || {};
+  const currentStatuses = Object.fromEntries(
+    Object.entries(registry).map(([taskPath, task]) => [taskPath, task?.status || 'pending']),
+  );
   const cacheFile = path.join(hookStateDir(projectRoot), 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
@@ -152,86 +145,51 @@ try {
   const previous = cacheExists && cacheEntries[runtimeContext.context_id]
     ? cacheEntries[runtimeContext.context_id].tasks || {}
     : {};
-  const staleFlashTasks = processWorkflow ? [] : Object.entries(registry)
-    .filter(([, task]) => POLICY.isStaleFlashDone(task))
-    .map(([taskPath]) => taskPath);
-  if (staleFlashTasks.length > 0) {
-    process.stdout.write(`${JSON.stringify({
-      decision: 'block',
-      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /cf:test, then use explicit sync-finalize.`
-    })}\n`);
-    process.exit(0);
-  }
   const allDoneTasks = Object.keys(registry).filter((taskPath) => (
     currentStatuses[taskPath] === 'done'
   ));
   const featureDir = path.join(active.specsDir, active.featureName);
-  const receiptBodies = new Map();
   const failures = allDoneTasks
     .map((taskPath) => {
-      const proof = processWorkflow
-        ? checkWorkflowReceiptDetails(featureDir, taskPath, runtimeContext)
-        : checkReceiptDetails(featureDir, taskPath, registry[taskPath], runtimeContext);
-      if (proof.body) receiptBodies.set(taskPath, proof.body);
+      const proof = checkWorkflowReceiptDetails(featureDir, taskPath, runtimeContext);
       return {
         taskPath,
+        body: proof.body,
         failures: proof.failures
       };
     })
     .filter((result) => result.failures.length);
 
-  const featureCloseoutRequired = !processWorkflow && 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];
   }
-  atomicWrite(cacheFile, `${JSON.stringify({
-    schema_version: '2',
-    entries: { ...cacheEntries, [runtimeContext.context_id]: { identity: cacheIdentity, tasks: next } },
-  })}\n`);
+  try {
+    atomicWrite(cacheFile, `${JSON.stringify({
+      entries: { ...cacheEntries, [runtimeContext.context_id]: { identity: cacheIdentity, tasks: next } },
+    })}\n`);
+  } catch { /* Cache persistence is not completion authority. */ }
 
-  const completionBlocked = completion && completion.completion !== 'complete' && completion.completion !== 'not_applicable';
-  if (!failures.length && !completionBlocked) process.exit(0);
-  const lines = [
-    failures.length > 0
-      ? `Completion gate: ${failures.length} done task(s) lack a verification receipt.`
-      : 'Completion gate: workflow completion proof is incomplete.'
-  ];
+  if (!failures.length) process.exit(0);
+  const lines = [`Completion gate: ${failures.length} done task(s) lack a verification receipt.`];
   for (const result of failures) {
     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\`.`
-      : processWorkflow
-        ? `  In \`specs/${active.featureName}/${path.posix.basename(result.taskPath)}\`: ${receiptFixHint(result.failures, result.body) || 'write a runtime-bound `## Receipt` with command output'}.`
-        : `  Write canonical proof to \`specs/${active.featureName}/receipts/${path.posix.basename(result.taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
-  }
-  if (completionBlocked) {
-    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(', ')}`);
-    }
+    lines.push(`  In \`specs/${active.featureName}/${path.posix.basename(result.taskPath)}\`: ${receiptFixHint(result.failures, result.body) || 'write a runtime-bound `## Receipt` with command output'}.`);
   }
   process.stdout.write(`${JSON.stringify({
     decision: 'block',
     reason: lines.slice(0, 8).join('\n')
   })}\n`);
 } catch (error) {
+  if (error.code === 'no_git_history') {
+    if (hasDoneTasks) emitBlock('Completion gate: repo has no commits yet; create the first commit, then record Base/Head after it.');
+    process.exit(0);
+  }
   logCrash('spec-gate', error);
-  emitBlock(`Completion gate controlled failure: ${error.message}. Completion is blocked until the hook is repaired.`);
+  if (/^(?:runtime\.paths\.specs|configured specs root)/.test(error.message)) {
+    emitBlock(`Completion gate: invalid workflow packet detected (<specs>): ${error.message}. Fix the packet's plan.md or task files before completing tasks.`);
+  } else {
+    emitBlock(`Completion gate controlled failure: ${error.message}. Completion is blocked until the hook is repaired.`);
+  }
 }