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

package/src/claude/hooks/session.cjs

@@ -18,10 +18,10 @@ try {
   const { execSync } = require('child_process');
 
   // ── Utilities ─────────────────────────────────────────────────────────────
-  function run(cmd, fallback = '') {
+  function run(cmd, fallback = '', cwd = process.cwd()) {
     try {
       return execSync(cmd, {
-        encoding: 'utf8', timeout: 3000,
+        cwd, encoding: 'utf8', timeout: 3000,
         stdio: ['pipe', 'pipe', 'pipe']
       }).trim();
     } catch { return fallback; }
@@ -40,6 +40,21 @@ try {
     } catch { /* fail-open */ }
   }
 
+  function projectRoot() {
+    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;
+
+    try { return fs.realpathSync(process.cwd()); } catch { return path.resolve(process.cwd()); }
+  }
+
   /** Read .claude/runtime.json config */
   function readRuntime(cwd) {
     try {
@@ -50,8 +65,7 @@ try {
 
   // ── Project Detection ──────────────────────────────────────────────────────
 
-  function detectProjectType() {
-    const cwd = process.cwd();
+  function detectProjectType(cwd) {
     if (fs.existsSync(path.join(cwd, 'pnpm-workspace.yaml')) ||
         fs.existsSync(path.join(cwd, 'lerna.json'))) return 'monorepo';
     try {
@@ -62,8 +76,7 @@ try {
     return 'app';
   }
 
-  function detectPackageManager() {
-    const cwd = process.cwd();
+  function detectPackageManager(cwd) {
     if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')))  return 'pnpm';
     if (fs.existsSync(path.join(cwd, 'yarn.lock')))        return 'yarn';
     if (fs.existsSync(path.join(cwd, 'bun.lockb')))        return 'bun';
@@ -71,10 +84,10 @@ try {
     return '';
   }
 
-  function detectFramework() {
+  function detectFramework(cwd) {
     try {
       const pkg = JSON.parse(
-        fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')
+        fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')
       );
       const deps = { ...pkg.dependencies, ...pkg.devDependencies };
       if (deps['next'])        return 'next';
@@ -185,31 +198,32 @@ try {
   const payload = stdin ? JSON.parse(stdin) : {};
   const source  = payload.source || 'unknown';
   const envFile = process.env.CLAUDE_ENV_FILE;
-  const cwd     = process.cwd();
+  const cwd     = projectRoot();
   const runtime = readRuntime(cwd);
+  try { require('./completion-authority-state.cjs').clearState(cwd, payload.session_id); } catch { /* old installs remain fail-open */ }
 
   // Check CafeKit update in parallel with project detection (async, fail-open).
   const updateCheckPromise = checkCafeKitUpdate(cwd);
 
   // Project detection
   const projectType = runtime.project?.type !== 'auto'
-    ? (runtime.project?.type || detectProjectType())
-    : detectProjectType();
+    ? (runtime.project?.type || detectProjectType(cwd))
+    : detectProjectType(cwd);
 
   const packageManager = runtime.project?.packageManager !== 'auto'
-    ? (runtime.project?.packageManager || detectPackageManager())
-    : detectPackageManager();
+    ? (runtime.project?.packageManager || detectPackageManager(cwd))
+    : detectPackageManager(cwd);
 
   const framework = runtime.project?.framework !== 'auto'
-    ? (runtime.project?.framework || detectFramework())
-    : detectFramework();
+    ? (runtime.project?.framework || detectFramework(cwd))
+    : detectFramework(cwd);
 
   // Static environment
-  const gitBranch  = run('git branch --show-current');
-  const gitUrl     = run('git remote get-url origin');
-  const gitRoot    = run('git rev-parse --show-toplevel');
+  const gitBranch  = run('git branch --show-current', '', cwd);
+  const gitUrl     = run('git remote get-url origin', '', cwd);
+  const gitRoot    = run('git rev-parse --show-toplevel', '', cwd);
   const nodeVer    = process.version;
-  const pythonVer  = run('python3 --version') || run('python --version');
+  const pythonVer  = run('python3 --version', '', cwd) || run('python --version', '', cwd);
   const user       = process.env.USERNAME || process.env.USER
                      || process.env.LOGNAME || os.userInfo().username;
   const timezone   = Intl.DateTimeFormat().resolvedOptions().timeZone;

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

@@ -8,56 +8,147 @@
  * Blocks turn end when *newly-done* tasks lack 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;
+  try {
+    POLICY = require(policyPath);
+    RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
+    if (typeof POLICY.validateCanonicalReceipt !== 'function'
+      || typeof POLICY.completionDecisionForSpec !== '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 */ }
+  // Active-spec discovery via shared resolver — explicit target if present, else fail on ambiguity.
+  const baseDir   = cwd;
+  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 (!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. Candidates: ${resolved.candidates.join(', ')}`
+    }) + '\n');
+    process.exit(0);
   }
-  if (!activeSpec) 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 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,12 +181,12 @@ try {
   const allDoneTasks = Object.keys(taskRegistry).filter((tp) =>
     (taskRegistry[tp]?.status || 'pending') === 'done'
   );
+  const receiptBodies = new Map();
   // /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) {
@@ -109,32 +200,33 @@ try {
     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; }
+      const isTapMetadata = typeof POLICY.isTapMetadataHeading === 'function'
+        && POLICY.isTapMetadataHeading(lines[i]);
+      if (hm && hm[1].length <= level && !isTapMetadata) { 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;
+  function validateCanonicalReceipt(body, options) {
+    return POLICY.validateCanonicalReceipt(body, options);
   }
 
   // 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 resolvedFeature = path.resolve(featureDir);
     const target = path.resolve(featureDir, taskPath);
-    const relative = path.relative(featureDir, target);
-    // sibling-prefix safe: must not be .., ../..., or absolute (cross-platform)
+    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;
   }
 
@@ -150,21 +242,28 @@ try {
     if (!statusLine || !/\bdone\b/i.test(statusLine)) fails.push('a');
 
     const body = evidenceBody(text);
+    if (body !== null) receiptBodies.set(taskPath, body);
     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' };
+      // Canonical receipt checks for done tasks — delegated to shared validator (single authority)
+      const canonicalFails = validateCanonicalReceipt(body, POLICY.receiptValidatorOptions(taskRegistry[taskPath], {
+        runtimeContext,
+        requireProvenanceBinding: true,
+      }));
+      const map = { 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 cf of canonicalFails) {
-        if (cf === 'verification_state') {
-          if (!PASS_MARKER_RE.test(body) && !fails.includes('c')) fails.push('c');
+        if (cf === 'verification_state' || cf === 'shared_validator' || cf === 'validator_unavailable') {
+          if (!fails.includes('c')) fails.push('c');
+          continue;
+        }
+        if (cf === 'placeholder') {
+          if (!fails.includes('c')) fails.push('c');
           continue;
         }
         const letter = map[cf];
@@ -187,6 +286,15 @@ try {
     .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
     .filter((f) => f.fails.length > 0);
 
+  const firstReceiptTask = allDoneTasks.find((taskPath) => receiptBodies.has(taskPath));
+  const completion = allDoneTasks.length > 0 && Object.prototype.hasOwnProperty.call(activeSpec, 'workflow_policy')
+    ? POLICY.completionDecisionForSpec(activeSpec, {
+      runtimeContext,
+      executionReceipt: firstReceiptTask ? receiptBodies.get(firstReceiptTask) : null,
+      taskContext: firstReceiptTask ? taskRegistry[firstReceiptTask] : null,
+    })
+    : 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
@@ -203,10 +311,13 @@ try {
   } 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} newly-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(', ')}`);
@@ -214,16 +325,17 @@ try {
       `  Fix: add \`Verification: PASS\` plus commands and successful outcomes to \`## Evidence\` in \`specs/${featureName}/${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');
   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,18 @@ try {
   const payload = JSON.parse(stdin);
   const cwd     = payload.cwd || process.cwd();
 
+  let POLICY;
+  let RESOLVER;
+  try {
+    POLICY = require(path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs'));
+    RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.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 +76,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);
@@ -84,25 +134,39 @@ try {
   });
 
   // ── 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,
+  });
   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,7 +180,7 @@ 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.`);
@@ -126,12 +190,7 @@ try {
   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);
 }