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

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

@@ -9,8 +9,13 @@ const {
   logCrash,
   readPayload
 } = require('./lib/hook-context.cjs');
-const { checkReceipt, evidenceBody, loadSharedPolicy } = require('./lib/spec-receipt.cjs');
+const {
+  checkFeatureReceipt,
+  checkReceiptDetails,
+  loadSharedPolicy,
+} = require('./lib/spec-receipt.cjs');
 const { taskStatusMap } = require('./lib/spec-utils.cjs');
+const FINAL_STATE = require('./completion-authority-check.cjs');
 
 function emitBlock(reason) {
   process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\n`);
@@ -26,22 +31,6 @@ function sessionIdentity(payload) {
   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.stop_hook_active === true) process.exit(0);
@@ -56,12 +45,15 @@ try {
   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);
+  const resolver = require('./lib/spec-utils.cjs');
+  const resolved = FINAL_STATE.resolveCandidate({
+    resolver,
+    projectRoot,
+    runtime,
+    payload,
+  });
   if (!resolved) process.exit(0);
-  if (resolved.error === 'multiple_active') {
+  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.`
@@ -84,6 +76,22 @@ try {
   }
   if (resolved.error) process.exit(0);
   const active = resolved;
+  const lifecyclePhase = active.spec.current_phase || active.spec.phase;
+  const explicitCloseout = ['done', 'completed', 'complete'].includes(active.spec.status)
+    || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
+  if (active.spec.schema_version === '2.1') {
+    const finalState = FINAL_STATE.evaluateCloseout({
+      policy: POLICY,
+      projectRoot,
+      runtime,
+      payload: { ...payload, session_id: sessionIdentity(payload) },
+    });
+    if (!finalState.ok) {
+      emitBlock(`Completion gate: ${finalState.reason}`);
+      process.exit(0);
+    }
+    if (finalState.active) process.exit(0);
+  }
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot,
     specsRoot: active.specsDir,
@@ -146,21 +154,28 @@ try {
   const receiptBodies = new Map();
   const failures = allDoneTasks
     .map((taskPath) => {
-      const body = readReceiptBody(featureDir, taskPath);
-      if (body !== null) receiptBodies.set(taskPath, body);
+      const proof = checkReceiptDetails(featureDir, taskPath, registry[taskPath], runtimeContext);
+      if (proof.body) receiptBodies.set(taskPath, proof.body);
       return {
         taskPath,
-        failures: checkReceipt(featureDir, taskPath, registry[taskPath], runtimeContext)
+        failures: proof.failures
       };
     })
     .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')
+  const featureCloseoutRequired = explicitCloseout && allDoneTasks.length > 0;
+  const featureReceipt = featureCloseoutRequired
+    ? checkFeatureReceipt(featureDir, runtimeContext)
+    : null;
+  if (featureReceipt && featureReceipt.failures.length) {
+    failures.push({ taskPath: 'feature-receipt.md', failures: featureReceipt.failures });
+  }
+  const completion = featureCloseoutRequired && featureReceipt?.failures.length === 0
+    && Object.prototype.hasOwnProperty.call(active.spec, 'workflow_policy')
     ? POLICY.completionDecisionForSpec(active.spec, {
       runtimeContext,
-      executionReceipt: firstReceiptTask ? receiptBodies.get(firstReceiptTask) : null,
-      taskContext: firstReceiptTask ? registry[firstReceiptTask] : null,
+      executionReceipt: featureReceipt.body,
+      taskContext: {},
     })
     : null;
 
@@ -178,14 +193,14 @@ try {
   if (!failures.length && !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 result of failures) {
-    lines.push(
-      `- \`${result.taskPath}\`: failed check(s) ${result.failures.join(', ')}`,
-      `  Add \`Verification: PASS\`, commands, and successful outcomes under \`## Evidence\` in \`specs/${active.featureName}/${result.taskPath}\`, then re-sync spec.json.`
-    );
+    lines.push(`- \`${result.taskPath}\`: failed check(s) ${result.failures.join(', ')}`);
+    lines.push(result.taskPath === 'feature-receipt.md'
+      ? `  Run final integration proof, then write \`specs/${active.featureName}/feature-receipt.md\`.`
+      : `  Write canonical proof to \`specs/${active.featureName}/receipts/${path.posix.basename(result.taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {
     lines.push(`- Completion decision unfinished: ${completion.blocker || 'required workflow proof is missing.'}`);

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

@@ -10,7 +10,7 @@ const {
   logCrash,
   readPayload
 } = require('./lib/hook-context.cjs');
-const { loadSharedPolicy } = require('./lib/spec-receipt.cjs');
+const { loadSharedPolicy, loadSharedReceipt } = require('./lib/spec-receipt.cjs');
 
 function emitControlledFailure(reason) {
   process.stdout.write(`> ⚠️ Spec tollgate unavailable: ${reason}. Repair the installed workflow policy before continuing.\n`);
@@ -34,6 +34,9 @@ try {
     process.exit(0);
   }
   const POLICY = loaded.policy;
+  const receiptLoaded = loadSharedReceipt();
+  if (!receiptLoaded.receipt) throw receiptLoaded.error;
+  const RECEIPT = receiptLoaded.receipt;
   const { projectRoot, runtime } = getHookContext(payload);
   if (runtime.spec?.tollgate === false) process.exit(0);
   const { resolveActiveSpec } = require('./lib/spec-utils.cjs');
@@ -81,6 +84,8 @@ try {
     (task?.status || 'pending') === 'pending'
     && (task?.dependencies || []).every((dependency) => statuses.get(dependency) === 'done')
   ));
+  const featureDir = path.join(active.specsDir, active.featureName);
+  const featureReceiptPresent = RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
   const stateKey = JSON.stringify({
     project_root: runtimeContext.project_root,
     specs_root: runtimeContext.specs_root,
@@ -94,6 +99,7 @@ try {
     phase,
     done: counts.done || 0,
     total: tasks.length,
+    feature_receipt_present: featureReceiptPresent,
   });
   const cache = cacheFile(projectRoot, runtimeContext.runtime_session);
   let previous = '';
@@ -117,9 +123,10 @@ try {
     lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. A PASS proof keeps the persisted task in_progress until explicit sync-finalize.`);
   }
   lines.push(
-    '- Sync `spec.json` and the task file only after verified work.',
+    '- Sync `spec.json` and task Markdown status only after verified work; task proof belongs in `receipts/<task-basename>.md`.',
+    `- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`,
     `- Validate with \`node .codex/scripts/validate-spec-output.cjs specs/${active.featureName}\`.`,
-    '- The Stop completion gate checks receipts for newly-done tasks.'
+    '- Hooks revalidate receipt bytes but never grant approval.'
   );
   process.stdout.write(`${lines.join('\n')}\n`);
 } catch (error) {

package/src/codex/hooks/state.cjs

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

package/src/codex/hooks.json

@@ -63,7 +63,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Bash|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*",
+        "matcher": "Bash|exec_command|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*|shell",
         "hooks": [
           {
             "type": "command",
@@ -120,6 +120,11 @@
       {
         "matcher": "*",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/semantic-review-authority.cjs\"",
+            "commandWindows": "node \".codex/hooks/semantic-review-authority.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",

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

@@ -1,41 +1,61 @@
-# Tollgate Protocol (State Sync)
+# Specs v2.1 state synchronization
 
-## Sources Of Truth
+## Authority layers
 
-Spec-driven work persists state in two synchronized layers:
+`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.
 
-1. `spec.json` tracks phase, overall status, and `task_registry`.
-2. `tasks/task-*.md` tracks the human-readable checklist and verification receipt.
+Planning depth and assurance level remain independent. Route artifacts before
+discovery: None persists no spec; Compact and Full persist the bounded core;
+research and tasks remain absent unless their semantic triggers exist.
 
-## Sync-back Rule
+## Canonical lifecycle
 
-Before reporting a task completed or blocked:
+The feature lifecycle is exactly `in_progress`, `paused`, `blocked`, or `done`.
+Authoring state is independently `draft`, `validated`, or `absent`. New 2.1
+artifacts never emit legacy lifecycle aliases.
 
-### On success
+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. The author cannot directly declare readiness, authority, approval,
+review capability, execution proof, or closeout.
 
-1. Update `spec.json` only after verification. Keep `current_phase`,
-   `task_files`, status, timestamps, and the matching `task_registry` entry accurate.
-2. Update the matching task Markdown status, checkboxes, completion criteria,
-   and `## Evidence` receipt from the current verification run.
-3. Update native plan or task state when the active Codex session provides it,
-   but never use chat-only state as a substitute for the files above.
+## Projection sync
 
-### On block after repeated attempts
+After a semantic Markdown edit:
 
-1. Set the spec and matching registry entry to `blocked`, with the root cause and timestamp.
-2. Mark the task Markdown `blocked` and record the evidence.
-3. Tell the user or orchestrator exactly what external input or state change is required.
+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 applicable deterministic validation and grounding checks.
 
-New specs use `in_progress`; legacy `in-progress` may be read but not emitted.
-Never let `task_registry` disagree with its task Markdown file.
+For Codex, the isolated promotion is
+`node .codex/scripts/spec-scaffold.cjs <feature> --sync-semantic-model`.
 
-## Completion Gate
+Task Markdown exists only for typed ownership, dependency, transition, proof,
+or parallel topology. Its status and dependencies project the matching
+`task_registry` entry. Its Verification Plan is prospective, never execution
+proof. Typed `coordination.boundaries` alone define topology; legacy trigger
+fields, priority markers, related-file lists, and prose do not.
 
-The Stop hook checks newly completed tasks. Each requires:
+## Lifecycle updates
 
-- `Status: done`;
-- a non-placeholder `## Evidence` section with a command block or PASS/FAIL result;
-- a non-empty `task_registry[path].completed_at`.
+- Active work uses `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 the registry and matching projection together only
+  from observed work and verification.
+- Feature `done` is reserved for final-state authority after implementation
+  closeout; authoring or readiness cannot produce it.
 
-The first run seeds completion history without blocking. Humans can disable the
-gate with `"spec": { "completion_gate": false }` in `.codex/runtime.json`.
+State synchronization never fabricates commands, PASS results, timestamps,
+receipts, completed work, reviewer identity, or user approval. When execution
+evidence is absent, preserve unfinished state and report the missing proof.
+Never hand-author the `semantic_model` shape or treat an unsynchronized Markdown
+edit as machine authority.
+
+Codex-native plan or task state may mirror physical state when available, but
+it is never a substitute for `spec.json` or authority to advance lifecycle.

package/src/common/AGENTS.md

@@ -3,7 +3,7 @@
 ## Shared CafeKit instructions
 
 - Deliver exactly what was asked. Do not expand, polish, or add optional work beyond the request. Match existing code style and structure.
-- For spec work, `Completion Criteria` and `## Evidence` in `specs/<feature>/tasks/*.md` are the source of truth for task state.
+- For Specs v2.1, treat `spec.json` as machine authority and Markdown as human projections. Keep task status and plan synchronized with `task_registry`; derive ownership, dependencies, transitions, proof, and parallelism only from typed `coordination.boundaries`. Never invent proof, readiness, approval, or audit state.
 - `NO_TESTS` and `0 tests + exit 0` do not pass when the task requires automated tests.
 - When a hook blocks an action, that is an instruction boundary — do not work around it.
 - Use conventional commits. Do not add AI attribution unless requested.