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

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

@@ -39,10 +39,10 @@ try {
   const RECEIPT = receiptLoaded.receipt;
   const { projectRoot, runtime } = getHookContext(payload);
   if (runtime.spec?.tollgate === false) process.exit(0);
-  const { resolveActiveSpec } = require('./lib/spec-utils.cjs');
+  const { resolveWorkflowCandidate } = require('./lib/spec-utils.cjs');
   const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
   const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
-  const resolved = resolveActiveSpec(projectRoot, runtime, explicitFeature, explicitPath);
+  const resolved = resolveWorkflowCandidate(projectRoot, runtime, explicitFeature, explicitPath);
   if (!resolved) process.exit(0);
   if (resolved.error === 'multiple_active') {
     process.stdout.write(`> ⚠️ Multiple active specs detected: ${resolved.candidates.join(', ')}. Provide explicit feature target or resolve ambiguity. Tollgate paused.\n`);
@@ -59,16 +59,17 @@ try {
   }
   if (resolved.error) process.exit(0);
   const active = resolved;
+  const processWorkflow = active.layoutKind === 'process-v3';
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot,
     specsRoot: active.specsDir,
-    specFile: active.specFile || path.join(active.specsDir, active.featureName, 'spec.json'),
+    specFile: active.stateFile || active.specFile || path.join(active.specsDir, active.featureName, 'spec.json'),
     featureName: active.featureName,
     runtimeSession: payload.session_id || payload.sessionId || payload.sessionID || payload.session?.id,
   });
 
-  const phase = active.spec.current_phase || active.spec.phase || 'unknown';
-  const taskRegistry = active.spec.task_registry || {};
+  const phase = active.phase || active.spec?.current_phase || active.spec?.phase || 'unknown';
+  const taskRegistry = active.taskRegistry || active.spec?.task_registry || {};
   const flashTasks = POLICY.flashState(taskRegistry);
   const tasks = Object.entries(taskRegistry);
   const counts = tasks.reduce((result, [, task]) => {
@@ -85,7 +86,8 @@ try {
     && (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 featureReceiptPresent = !processWorkflow
+    && RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
   const stateKey = JSON.stringify({
     project_root: runtimeContext.project_root,
     specs_root: runtimeContext.specs_root,
@@ -122,12 +124,20 @@ 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` 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}\`.`,
-    '- Hooks revalidate receipt bytes but never grant approval.'
-  );
+  if (processWorkflow) {
+    lines.push(
+      '- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.',
+      `- Workflow source: \`specs/${active.featureName}/plan.md\`; Stop revalidates every task currently marked done.`,
+      '- Hooks revalidate receipt bytes but never grant approval.'
+    );
+  } else {
+    lines.push(
+      '- 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}\`.`,
+      '- Hooks revalidate receipt bytes but never grant approval.'
+    );
+  }
   process.stdout.write(`${lines.join('\n')}\n`);
 } catch (error) {
   logCrash('spec-state', error);

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

@@ -1,61 +1,57 @@
-# Specs v2.1 state synchronization
-
-## Authority 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.
-
-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.
-
-## Canonical lifecycle
-
-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.
-
-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.
-
-## Projection sync
-
-After a semantic Markdown edit:
-
-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.
-
-For Codex, the isolated promotion is
-`node .codex/scripts/spec-scaffold.cjs <feature> --sync-semantic-model`.
-
-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.
-
-## Lifecycle updates
-
-- 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.
-
-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.
+# Process-first state synchronization
+
+## Primary file state
+
+For new work, `specs/<feature>/plan.md` and its direct-child
+`task-NN-*.md` files are canonical, hand-editable state. Task files stay flat
+beside the plan; indexes and host task views are disposable projections.
+
+Each task has exactly one `Status:` field using `pending`, `in_progress`,
+`paused`, `blocked`, or `done`. The controller is the sole writer of task
+status and proof. A task's final `## Receipt` is its only canonical execution
+proof.
+
+## Surgical synchronization
+
+Before changing state:
+
+1. read the plan row and the task's Outcome, Acceptance, Dependencies,
+   Verification Plan, Status, and Receipt;
+2. confirm every dependency and owned path at the requested boundary;
+3. edit only the observed Status, concrete blocker, implemented checkbox, or
+   Receipt; and
+4. re-read the file and confirm exactly one Status field and one Receipt
+   section.
+
+Starting or resuming changes only Status to `in_progress`. Blocking records a
+specific cause without creating proof. Do not replace a whole packet to make a
+state transition.
+
+Set `Status: done` only after the inline Receipt passes the
+`validateCanonicalReceipt` contract: exact command, `Exit: 0`,
+`Verification: PASS`, runtime-derived Base and Head values, and a non-empty
+fenced block of current command output. Missing, stale, contradictory,
+placeholder, copied, failure, or zero-test evidence leaves the task unfinished.
+
+Synchronization never fabricates commands, output, timestamps, completed
+work, reviewer identity, user approval, or product readiness. A passing command
+proves only the boundary it executed.
+
+## Human gates and workflow ownership
+
+- C1 records the user's scope decision before the plan is written.
+- C2 records the user's disposition of deduplicated adversarial findings.
+- Develop starts only after a new explicit user invocation and executes one
+  unblocked task at a time.
+- Sync changes only observed file state and never starts implementation.
+- C3 occurs after current receipts and limitations are shown; the user decides
+  whether the requested feature is complete.
+
+## Legacy compatibility
+
+Existing packets containing `spec.json`, nested `tasks/task-R*.md`, or other
+legacy kernel artifacts stay on their installed adapters. Preserve their
+`task_registry`, `semantic_model`, `planning_depth`, lane,
+`execution_tier`, typed topology, separate receipts, and feature closeout
+contract. Do not migrate that machine authority or storage shape while syncing
+an unrelated process-first packet.

package/src/common/AGENTS.md

@@ -3,7 +3,14 @@
 ## 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 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.
+- For process-first Specs, `plan.md` and flat `task-NN-*.md` files are
+  canonical, hand-editable state. Each task has exactly one `Status:` field and
+  keeps canonical execution proof in its final inline `## Receipt`.
+- Specs uses three user decisions: C1 for scope, C2 for adversarial findings,
+  and C3 for completion. Planning never starts implementation; implementation
+  requires a new explicit user invocation.
+- Synchronize only observed task state with surgical edits. Never invent proof,
+  readiness, approval, review independence, or completed work.
 - `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.