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

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

@@ -0,0 +1,152 @@
+#!/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, '.claude', '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, '.claude');
+  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, '..');
+  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 requestedSpec = path.resolve(root, claim.spec_file);
+  const identity = identityFor(root, requestedSpec, 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 }; }
+  const file = recordPath(root, identity);
+  let record;
+  try { record = JSON.parse(fs.readFileSync(file, '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`);
+  }
+}
+
+module.exports = { MARKER, REVIEWER_ROLE_ALLOWLIST, recordFromSubagentStop, verifyAttestation, identityFor, recordPath };

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

@@ -5,7 +5,7 @@
  * Stop Hook — spec-gate.cjs
  * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
  *
- * Blocks turn end when *newly-done* tasks lack a verification receipt.
+ * Blocks turn end when any done task lacks a verification receipt.
  * Block contract (exit 0 + stdout): {"decision":"block","reason":"..."}.
  *
  * Safety: stop_hook_active loop guard; no worker-writable completion-gate
@@ -83,11 +83,17 @@ try {
 
   let POLICY;
   let RESOLVER;
+  let RECEIPT;
+  let FINAL_STATE;
   try {
     POLICY = require(policyPath);
     RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
+    RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
+    FINAL_STATE = require('./completion-authority-check.cjs');
     if (typeof POLICY.validateCanonicalReceipt !== 'function'
-      || typeof POLICY.completionDecisionForSpec !== 'function') {
+      || typeof POLICY.completionDecisionForSpec !== 'function'
+      || typeof RECEIPT.checkTaskReceipt !== 'function'
+      || typeof FINAL_STATE.evaluateCloseout !== 'function') {
       throw new Error('shared workflow policy lacks completion authority functions');
     }
   } catch (error) {
@@ -106,11 +112,9 @@ try {
   } catch { /* gate stays on */ }
   // 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 });
+  const resolved = FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
   if (!resolved) process.exit(0);
-  if (resolved.error === 'multiple_active') {
+  if (resolved.error === 'multiple_active' || resolved.error === 'multiple_persisted') {
     process.stdout.write(JSON.stringify({
       decision: 'block',
       reason: `Completion gate: multiple active specs detected (${resolved.candidates.join(', ')}). Provide explicit feature target or resolve ambiguity before completing tasks. Candidates: ${resolved.candidates.join(', ')}`
@@ -136,6 +140,23 @@ try {
   const activeSpec = resolved.spec;
   const featureName = resolved.featureName;
   const specsPath = resolved.specsDir;
+  const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
+  const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
+    || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
+  if (activeSpec.schema_version === '2.1') {
+    const finalState = FINAL_STATE.evaluateCloseout({
+      resolver: RESOLVER,
+      policy: POLICY,
+      projectRoot: baseDir,
+      runtime,
+      payload: { ...payload, session_id: sessionIdentity(payload) },
+    });
+    if (!finalState.ok) {
+      emitBlock(`Completion gate: ${finalState.reason}`);
+      process.exit(0);
+    }
+    if (finalState.active) process.exit(0);
+  }
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
@@ -181,117 +202,27 @@ 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;
-
-  /** Body of first Evidence heading until next same-or-higher heading. */
-  function evidenceBody(text) {
-    const lines = text.split('\n');
-    let start = -1, level = 0;
-    for (let i = 0; i < lines.length; i++) {
-      const m = lines[i].match(/^(#{2,3})\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/);
-      if (m) { start = i + 1; level = m[1].length; break; }
-    }
-    if (start < 0) return null;
-    let end = lines.length;
-    for (let i = start; i < lines.length; i++) {
-      const hm = lines[i].match(/^(#{1,6})\s+/);
-      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, 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(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 checkReceipt(taskPath) {
-    const fails = [];
-    const featureDir = path.join(specsPath, featureName);
-    const abs = safeTaskFile(featureDir, taskPath);
-    if (!abs || !fs.existsSync(abs)) return ['a'];
-    let text = '';
-    try { text = fs.readFileSync(abs, 'utf8'); } catch { return ['a']; }
-
-    const statusLine = text.split('\n').find((l) => /^\s*(\*\*)?Status(\*\*)?\s*:/i.test(l));
-    if (!statusLine || !/\bdone\b/i.test(statusLine)) fails.push('a');
-
-    const body = evidenceBody(text);
-    if (body !== null) receiptBodies.set(taskPath, body);
-    if (body === null || !EVID_RE.test(text)) {
-      fails.push('b');
-    } else if (
-      /\{\{[^}]+\}\}/.test(body) ||
-      !(PASS_MARKER_RE.test(body) || LEGACY_SUCCESS_RE.test(body))
-    ) {
-      fails.push('c');
-    } else {
-      // 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' || 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];
-        if (letter && !fails.includes(letter)) fails.push(letter);
-      }
-      // Enforce strict Verification: PASS, not just legacy success
-      if (!PASS_MARKER_RE.test(body) && !fails.includes('c')) fails.push('c');
-    }
-
-    const at = taskRegistry[taskPath]?.completed_at;
-    if (
-      typeof at !== 'string' ||
-      !/^\d{4}-\d{2}-\d{2}T/.test(at) ||
-      Number.isNaN(Date.parse(at))
-    ) fails.push('d');
-    return fails;
-  }
-
+  const featureDir = path.join(specsPath, featureName);
   const failures = allDoneTasks
-    .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
+    .map((taskPath) => ({
+      taskPath,
+      fails: RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
+    }))
     .filter((f) => f.fails.length > 0);
 
-  const firstReceiptTask = allDoneTasks.find((taskPath) => receiptBodies.has(taskPath));
-  const completion = allDoneTasks.length > 0 && Object.prototype.hasOwnProperty.call(activeSpec, 'workflow_policy')
+  const featureCloseoutRequired = explicitCloseout && allDoneTasks.length > 0;
+  const featureReceipt = featureCloseoutRequired
+    ? RECEIPT.checkFeatureReceipt(featureDir, runtimeContext, POLICY)
+    : null;
+  if (featureReceipt && featureReceipt.failures.length) {
+    failures.push({ taskPath: 'feature-receipt.md', fails: featureReceipt.failures });
+  }
+  const completion = featureCloseoutRequired && featureReceipt?.failures.length === 0
+    && Object.prototype.hasOwnProperty.call(activeSpec, 'workflow_policy')
     ? POLICY.completionDecisionForSpec(activeSpec, {
       runtimeContext,
-      executionReceipt: firstReceiptTask ? receiptBodies.get(firstReceiptTask) : null,
-      taskContext: firstReceiptTask ? taskRegistry[firstReceiptTask] : null,
+      executionReceipt: featureReceipt.body,
+      taskContext: {},
     })
     : null;
 
@@ -310,20 +241,19 @@ try {
     fs.writeFileSync(cacheFile, JSON.stringify(cache));
   } catch { /* fail-open */ }
 
-  if (allDoneTasks.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 = [
     failures.length > 0
-      ? `⚠️ Completion gate: ${failures.length} newly-done task(s) lack a verification receipt.`
+      ? `⚠️ Completion gate: ${failures.length} done task(s) lack a verification receipt.`
       : '⚠️ Completion gate: workflow completion proof is incomplete.',
   ];
   for (const { taskPath, fails } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
-    lines.push(
-      `  Fix: add \`Verification: PASS\` plus commands and successful outcomes to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`, then re-sync spec.json`
-    );
+    lines.push(taskPath === 'feature-receipt.md'
+      ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
+      : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {
     lines.push(`- Completion decision unfinished: ${completion.blocker || 'required workflow proof is missing.'}`);

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

@@ -54,9 +54,11 @@ try {
 
   let POLICY;
   let RESOLVER;
+  let RECEIPT;
   try {
     POLICY = require(path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs'));
     RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
+    RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
     if (typeof POLICY.flashState !== 'function') throw new Error('shared workflow policy has no flashState function');
   } catch (error) {
     logCrash(error);
@@ -132,6 +134,8 @@ try {
     const deps = Array.isArray(task?.dependencies) ? task.dependencies : [];
     return status === 'pending' && deps.every((dep) => taskStatusByPath.get(dep) === 'done');
   });
+  const featureDir = path.join(specsPath, featureName);
+  const featureReceiptPresent = RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
 
   // ── State-change gate: only emit the full tollgate when spec state changed ──
   // The cache is shared by installed hook copies, so its key must carry the
@@ -150,6 +154,7 @@ try {
     phase,
     done: taskCounts.done || 0,
     total: taskEntries.length,
+    featureReceiptPresent,
   });
   const cacheFile = path.join(__dirname, '.logs', 'tollgate-last.txt');
 
@@ -182,8 +187,9 @@ try {
   if (flashTasks.length > 0) {
     lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. A PASS proof keeps the persisted task in_progress until explicit sync-finalize.`);
   }
-  lines.push(`- Sync \`spec.json\` + task file after verified work; run \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\` before \`ready_for_implementation=true\`.`);
-  lines.push(`- A completion gate verifies receipts when you end a turn with newly-done tasks.`);
+  lines.push(`- Sync \`spec.json\` + task Markdown status after verified work; task proof belongs in \`receipts/<task-basename>.md\`.`);
+  lines.push(`- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`);
+  lines.push(`- Validate with \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
   lines.push('');
 
   console.log(lines.join('\n'));

package/src/claude/migration-manifest.json

@@ -63,6 +63,11 @@
       "scan-staged-secrets.cjs",
       "workflow-policy.cjs",
       "spec-resolver.cjs",
+      "spec-receipt.cjs",
+      "spec-ground.cjs",
+      "spec-semantic-model.cjs",
+      "spec-final-state.cjs",
+      "spec-readiness.cjs",
       "provenance.cjs"
     ]
   },
@@ -107,6 +112,7 @@
       "hooks/completion-authority.cjs",
       "hooks/completion-authority-check.cjs",
       "hooks/completion-authority-state.cjs",
+      "hooks/semantic-review-authority.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
       "hooks/lib/parser.cjs",
@@ -114,7 +120,9 @@
       "hooks/lib/git.cjs",
       "hooks/lib/config.cjs",
       "hooks/lib/context.cjs",
-      "hooks/lib/detect.cjs"
+      "hooks/lib/detect.cjs",
+      "hooks/lib/privacy-command-analysis.cjs",
+      "hooks/lib/runtime-path-safety.cjs"
     ]
   },
   "settings": {

package/src/claude/rules/state-sync.md

@@ -1,31 +1,62 @@
-# Tollgate Protocol (State Sync)
+# Specs v2.1 state synchronization
 
-## Single Source of Truth
+## Authority layers
 
-In any Spec-driven workflow (`specs`), the state of the project is physically persisted in **two layers**:
-1. **Machine Layer (`spec.json`)**: Tracks phase, status, overall completion, and per-task machine state via `task_registry`.
-2. **Human Layer (`tasks/task-*.md`)**: Checkboxes indicating granular execution progress.
+`spec.json` is machine semantic authority. Requirements, design, conditional
+research, and conditional task Markdown are human projections. Host state may
+record authority or integrity, but it never supplies product semantics.
 
-## The Sync-back Rule (Mandatory)
+Planning depth and assurance level remain independent. The artifact router runs
+before discovery: None persists no spec; Compact and Full persist the bounded
+core; research and tasks remain absent unless their semantic triggers exist.
 
-Whenever an agent finishes a task or blocks due to an issue, it **MUST NOT** simply respond with "Done" or "Blocked" in chat. 
-Before returning control to the user or orchestrator, the agent **MUST**:
+## Canonical lifecycle
 
-### On Success:
-1. Update `spec.json`: Modify `current_phase` if moving forward, ensure `status` accurately reflects progress, keep `task_files` synchronized with the real files on disk, and update the corresponding `task_registry` entry (`status`, `blocker`, `started_at`, `completed_at`, `last_updated_at`).
-2. Edit `task-R*.md`: Change `Status` only after real verification has passed (build/test/runtime/artifact). Then check `[x]` the sub-task boxes and relevant completion criteria.
-3. Call `TaskUpdate` if Claude Tasks are active, setting the status to "completed" only after the physical files were updated.
+The feature lifecycle is exactly `in_progress`, `paused`, `blocked`, or `done`.
+Authoring state is independently `draft`, `validated`, or `absent`. Do not emit
+legacy lifecycle aliases in a new 2.1 artifact.
 
-### On Block/Failure (>3 retries):
-1. Update `spec.json`: Set `"status": "blocked"` and fill out the `"blocker"` string with the root cause.
-2. Update the corresponding `task_registry` entry to `blocked`, persist the blocker reason, and stamp `last_updated_at`.
-3. Edit `task-R*.md`: Change `Status: pending` (or `in_progress`) to `Status: blocked` with a note.
-4. Alert the orchestrator or user via `AskUserQuestion` or explicit warning.
+Technical readiness is not lifecycle completion. `ready_for_implementation`
+may change only through the installed machine finalization path after every
+routed artifact, projection, semantic review, grounding check, and deterministic
+gate passes. An author must not directly declare readiness, authority, approval,
+review capability, execution proof, or closeout.
 
-**Canonical state values:** New specs MUST use `status: "in_progress"` for active work. Legacy `in-progress` may be read for compatibility, but must not be emitted in new files.
+## Projection sync
 
-**Golden Rule:** If the current phase changes, or a task completes, the agent must update the physical files. Never mark a task completed before there is execution proof, and never let `task_registry` disagree with the matching markdown task file. The context is intentionally NOT persisted in the chat to save tokens. An injected Hook (`spec-state.cjs`) constantly enforces and validates this state.
+After any semantic Markdown edit:
 
-### Completion gate (Stop)
+1. invoke the explicit installed machine semantic-sync step to promote `semantic_model`;
+2. regenerate or reconcile every affected Markdown projection;
+3. verify requirements, decisions, anchors, task registry, typed boundaries,
+   and verification refs round-trip without loss; and
+4. rerun the applicable deterministic validation and grounding checks.
 
-Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, `## Evidence` (legacy heading aliases still parse) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).
+For Claude Code, the isolated promotion is
+`node .claude/scripts/spec-scaffold.cjs <feature> --sync-semantic-model`.
+
+Task Markdown exists only when typed ownership, dependency, transition, proof,
+or parallel topology requires it. Its status and dependencies project the
+matching `task_registry` entry. Its Verification Plan is prospective and never
+contains an execution verdict or proof claim. Topology comes only from typed
+`coordination.boundaries`, never from legacy trigger fields, priority markers,
+related-file lists, or prose.
+
+## Lifecycle updates
+
+- Starting or continuing authored work keeps the feature `in_progress`.
+- A deliberate resumable stop uses `paused` with the exact remaining decision.
+- An external or semantic blocker uses `blocked` with a concrete cause.
+- Task state changes update `task_registry` and the matching task projection
+  together, but only from observed work and verification.
+- Feature `done` is reserved for final-state authority after implementation
+  closeout; authoring or readiness cannot produce it.
+
+State synchronization never fabricates commands, PASS results, timestamps,
+receipts, completed work, reviewer identity, or user approval. When execution
+evidence is absent, preserve the unfinished state and report the missing proof.
+Never hand-author the `semantic_model` shape or treat an unsynchronized Markdown
+edit as machine authority.
+
+Claude-native plan/task state may mirror physical state when available, but it
+is never a substitute for `spec.json` or authority to advance the lifecycle.

package/src/claude/rules/workflow.md

@@ -13,14 +13,16 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 ## 2. Plan
 
 - For non-trivial features, use `/specs` to create or validate the spec.
-- For approved specs, work one task file at a time.
+- For technically ready specs, start implementation only after a new explicit Develop invocation and work one task file at a time.
 - Extract from the active task:
-  - `Context`
-  - `Steps`
-  - `Requirements`
-  - `Related Files`
-  - `Completion Criteria`
-  - `Evidence`
+  - `Status`
+  - `Outcome`
+  - `Scope`
+  - `Anchors and Ownership`
+  - `Changes`
+  - `Acceptance`
+  - `Dependencies`
+  - `Verification Plan`
 - If these are missing or too vague to verify, route back to spec correction.
 
 ## 3. Execute
@@ -32,7 +34,7 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 
 ## 4. Verify
 
-- Run exact commands from `Evidence` first.
+- Run exact commands from `Verification Plan` first.
 - Then run repo-level lint/test/build as needed for confidence.
 - Use only fresh verification from the current run when claiming completion.
 - `PRECHECK_FAIL` outranks `NO_TESTS`.
@@ -42,7 +44,13 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 ## 5. Sync
 
 - Mark task state only after implementation, tests/evidence, and review pass.
-- Write a verification receipt with commands run, outcomes, and artifact/runtime proof.
+- Write task proof to `receipts/<task-basename>.md`; use legacy task-local
+  `## Evidence` only when consuming an old task format.
+- Create `feature-receipt.md` only for final integration closeout.
+- Treat `spec.json` as machine authority; task Markdown is a human projection.
+- Derive task ordering, ownership, proof, and parallel eligibility only from
+  typed `coordination.boundaries`, never `(P)`, `task_triggers`, `Related Files`,
+  or prose markers.
 - Keep `spec.json.task_registry` and markdown task files aligned.
 - Run docs checkpoint when a completed task affects public docs or architecture docs.