@haposoft/cafekit 0.16.0-rc.6 → 0.16.0-rc.8

package/src/claude/skills/sync/SKILL.md

@@ -1,103 +1,79 @@
 ---
 name: hapo:sync
-description: "Dumb-proof status tracker and file synchronizer. Updates spec.json, task_registry, and tasks/*.md without breaking structural schemas. Includes Auto-Audit."
+description: "Synchronize process-first task Status and inline Receipts without inventing proof; also preserves existing legacy Specs state."
 user-invocable: true
-when_to_use: "Invoke to synchronize spec state, docs, or task tracking after changes."
+when_to_use: "Invoke after implementation or verification changes a task's real state, or to audit a feature packet for drift."
 category: utilities
 keywords: [sync, state, tracking, consistency]
-argument-hint: "<feature_name> <task_id|task-file> <status> [blocker] | phase <feature_name> <next_phase> | audit <feature_name>"
+argument-hint: "<feature> <task-file> <pending|in_progress|paused|blocked|done|sync-finalize> [blocker] | audit <feature>"
 metadata:
   author: haposoft
-  version: "1.0.0"
+  version: "3.0.0"
 ---
-# Sync (State Tracking Protocol)
+# Sync — file-state synchronization
 
-This skill safely bridges the gap between active development state and physical documentation files (`spec.json` + `task_registry` + `tasks/task-R*.md`). Instead of relying on risky raw AI edits, this skill executes precise contextual replacements.
+Synchronize only observed state. For the primary process-first layout, the
+single `Status:` field and inline `## Receipt` in each flat task file are the
+state. Never infer proof, approval, review independence, or product readiness.
 
-## v2.1 authority-aware synchronization
+## Commands
 
-Read canonical policy before mutating state. Lane is a derived view:
-
-```bash
-node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
+```text
+/hapo:sync <feature> <task-NN-slug.md> in_progress
+/hapo:sync <feature> <task-NN-slug.md> blocked "reason"
+/hapo:sync <feature> <task-NN-slug.md> done
+/hapo:sync <feature> <task-NN-slug.md> sync-finalize
+/hapo:sync audit <feature>
 ```
 
-- Direct may have no spec/state/registry; sync only concrete targeted evidence
-  and never invents proof, readiness, approval, or audit state.
-- Standard stores one bounded spec; final integration creates one canonical
-  feature receipt. A combined closeout review is required only when the
-  persisted policy says an independent audit is needed.
-- Critical requires strict durable evidence and the persisted capability obligations; choose available actors or the main session according to required capability and independence, never a fixed actor sequence.
-- Authoring states are only `draft`, `validated`, or `absent`. Legacy approval
-  fields are readable but inert.
-- Preserve `classified_minimum`. Reclassification happens before persistence;
-  after persistence, the same-feature baseline is monotonic and no downgrade is
-  supported until a trusted issuer exists.
-- `spec.json` is machine authority. Task status/checkboxes, dependencies, and
-  ownership Markdown are projections. Typed `coordination.boundaries` are the
-  only topology authority.
-
-## Supported Commands
-### 1. Task Synchronization
-Update a specific task's status and automatically check its relevant sub-checkboxes.
-
-**Usage:** `/hapo:sync <feature_name> <task_id|task-file> <status> ["optional blocker msg"]`
-- Example 1: `/hapo:sync auth R0-02 done`
-- Example 2: `/hapo:sync payment task-R1-03-chunks-api.md blocked "API Endpoint Down"`
-
-### 2. Phase Advancement
-Advance the entire project to the next logical phase.
-
-**Usage:** `/hapo:sync phase <feature_name> <next_phase>`
-- Example: `/hapo:sync phase shopping_cart test`
-
-### 3. State Audit
-Scans the `spec.json` against all physical `task-R*.md` files to detect mismatches between `task_files`, `task_registry`, and markdown task headers, then repairs them.
-
-**Usage:** `/hapo:sync audit <feature_name>`
-- Example: `/hapo:sync audit auth`
-
-## Directives
-
-1. **Precision Edits:** Never overwrite the entire `spec.json` string blindly. Update only the required keys, while keeping JSON valid.
-2. **Machine + Human Sync:** Every task status update MUST modify both `spec.json.task_registry[...]` and the matching markdown task file header/status section.
-3. **Markdown Integrity:** Task Markdown is a plan plus `**Status:**`. Update
-   Status and `Changes` checkboxes only when their implementation is real; never
-   insert Base/Head, verdicts, command outcomes, or receipt proof into the plan.
-4. **Verification Receipt Rule:** `done` is illegal without a valid canonical
-   `receipts/<task-basename>.md`, or a readable legacy `## Evidence` receipt.
-   Prefer the separate receipt; if both exist and proof identity conflicts,
-   refuse completion. If proof is missing, keep the task `in_progress` or
-   `blocked`.
-5. **Task Docs Hook:** When `hapo:sync` marks a task as `done`, assess actual documentation impact and report `Docs impact: major|minor|none`; do not create a docs update request when impact is `none`.
-6. **Topology Rule:** Never infer dependency or parallel state from `(P)`,
-   `task_triggers`, `Related Files`, or prose; project typed boundaries instead.
-
-### 4. Explicit Flash Finalization
-
-**Usage:** `/hapo:sync <feature_name> <task_id|task-file> sync-finalize` (the adapter must call `workflow-policy.cjs --sync-finalize --task-json <current-task> --verdict PASS --proof <canonical-receipt> --json`)
-
-This is the only operation allowed to turn the current `FLASH_UNVERIFIED` task into `done` and unblock dependencies. The policy derives promotion from that current state and explicit proof; `readyForSync`, `flashTransition`, and `promotionReceipt` supplied by the caller are not proof. A normal `done` request cannot bypass flash promotion or stale `FLASH_UNVERIFIED` state.
-
-The current state must be the exact stored form: `status: "in_progress"`,
-`receipt: "FLASH_UNVERIFIED"`, `dependencyBlocked: true`, `unblocks: false`, a
-concrete blocker, and no caller promotion fields. The canonical proof must be
-bound by the runtime adapter with `policy.createReceiptBinding({ base, head })`
-and must match both receipt anchors; arbitrary valid-length Base/Head values do
-not authorize finalization.
-
-### Flash implementation state
-
-Executable policy source: `.claude/scripts/workflow-policy.cjs` (source: `src/claude/scripts/workflow-policy.cjs`). Trusted sync-finalize invokes `promoteFlashTask` only after the exact task Verification Plan and reachability return PASS; test PASS itself only supplies canonical proof and leaves the persisted task blocked in progress. FAIL, BLOCKED, and NO_TESTS remain blocked in progress.
-
-`FLASH_UNVERIFIED` is storage for implemented-but-unverified work, not a completion status. Store it as `status: "in_progress"` with `dependencyBlocked: true`, `unblocks: false`, a concrete blocker, and no promotion fields; do not unblock dependencies. `/hapo:test` may produce canonical proof, but the supported sync-finalize boundary must receive explicit `--verdict PASS` and `--proof`, require the runtime Base/Head binding, revalidate the receipt/artifact, derive the transition, and only then set `done`. FAIL, BLOCKED, NO_TESTS, marker-only proof, minimal state, and pre-promoted caller JSON remain `in_progress`.
-
-After the last task is done, sync does not synthesize proof. Test/Develop must
-run final integration and create `feature-receipt.md` once. Task-bearing
-completion requires all task receipts plus the feature receipt. Taskless
-Compact/Full completion requires the feature receipt only; its absence before
-final closeout is normal. No receipt grants or infers approval, readiness, or
-audit status.
-
-## References
-Read `references/sync-protocols.md` for exact Search/Replace regex patterns and JSON schema expectations before acting on the files.
+Resolve one regular direct-child task inside `specs/<feature>/`. Reject path
+escape, symlink, ambiguity, missing `plan.md`, duplicate Status fields, and
+unsupported status values.
+
+## Task synchronization
+
+1. Read the task Outcome, Acceptance, Dependencies, Verification Plan, current
+   Status, and Receipt before editing.
+2. Starting or resuming changes only Status to `in_progress`. Update only
+   checkboxes whose implementation is real.
+3. Blocking changes Status to `blocked` and records a concrete blocker; it does
+   not create proof.
+4. Done requires a current inline Receipt with `Verification: PASS`, exact
+   Command, `Exit: 0`, runtime-bound Base/Head, non-empty fenced output, and any
+   required negative/reachability/artifact proof.
+5. Write or replace the Receipt before changing Status to `done`. Missing,
+   stale, contradictory, placeholder, failure, or zero-test evidence keeps the
+   task `in_progress` or `blocked`.
+6. Re-read the file after the surgical edit and confirm exactly one Status and
+   one Receipt section.
+
+`sync-finalize` is the only promotion path for `FLASH_UNVERIFIED`. It requires
+fresh canonical PASS proof, revalidates Base/Head and artifacts, clears the
+flash blocker, then derives `done`. Caller-supplied promotion booleans and a
+marker alone have no authority.
+
+## Audit
+
+Scan only `specs/<feature>/task-*.md` beside `plan.md`. Compare plan task rows,
+task filenames, dependencies, Status, acceptance mapping, and Receipts. Report
+missing files, unknown rows, cycles, duplicate fields, done-without-proof,
+proof-on-unfinished-task, and overlapping ownership.
+
+Repair deterministic formatting drift only. A semantic conflict, missing
+evidence, or ownership decision requires user or implementation input; do not
+pick a winner. After any edit, report exact files changed and unresolved items.
+
+Read `references/sync-protocols.md` for surgical update and audit rules.
+
+## Docs impact
+
+When a task becomes done, report `Docs impact: none|minor|major`. Create no docs
+work for `none`; update only affected existing docs for minor or major.
+
+## Legacy workflow compatibility
+
+If `specs/<feature>/spec.json` exists, use the legacy adapter instead: preserve
+its machine authority, `task_registry`, nested `tasks/task-R*.md`, timestamps,
+typed topology, separate receipts, `workflow_policy`, `planning_depth`, lane,
+and `execution_tier`. Keep JSON and Markdown synchronized, retain the exact
+legacy sync-finalize contract, and require its feature receipt at closeout.

package/src/claude/skills/sync/references/sync-protocols.md

@@ -1,83 +1,62 @@
-# Sync Protocols 
-
-The following guidelines dictate exactly how `hapo:sync` should interact with files to prevent data corruption.
-
-**Flash implementation state:** `FLASH_UNVERIFIED` MUST remain the exact stored form: `status: "in_progress"`, `dependencyBlocked: true`, `unblocks: false`, a concrete blocker, and no `readyForSync`, `flashTransition`, or `promotionReceipt` fields. It never unblocks dependencies. The supported sync-finalize adapter must pass the current task, `--verdict PASS`, and canonical `--proof` to `workflow-policy.cjs`; the policy derives promotion, requires a runtime `createReceiptBinding({ base, head })` match for both receipt anchors, revalidates receipt/artifact requirements, and rejects caller-supplied promotion fields before setting `done`. FAIL, BLOCKED, NO_TESTS, marker-only proof, minimal state, and pre-promoted caller JSON stay `in_progress`.
-
-**Policy state rule:** read the v2.1 policy input before sync. Direct/Standard/
-Critical are derived views. Preserve `classified_minimum`, risks, and explicit
-override receipt. Authoring states are only `draft`, `validated`, or `absent`;
-legacy approval fields are inert.
-
-**Authority rule:** `spec.json` is machine authority. Markdown is a projection.
-Typed `coordination.boundaries` own dependency, ownership, transition, proof,
-and parallel semantics; never infer them from `(P)`, `task_triggers`, `Related
-Files`, or prose.
-
-## 1. Updating `spec.json`
-
-*   **JSON Modification Rule:** Do not output whole files. Load the JSON,
-    update only lifecycle fields and the relevant registry entry, then write
-    valid JSON without changing semantic topology.
-*   **Task Registry Rule:** Resolve the incoming task reference to a single relative path in `task_registry`. Accept either:
-    - compact task ID like `R0-02`
-    - full filename like `task-R0-02-extension-shell.md`
-    - full relative path like `tasks/task-R0-02-extension-shell.md`
-*   **Status Update:** If a task changes to `blocked`, the matching `task_registry[path].status` must become `"blocked"`, `task_registry[path].blocker` must record the reason, and `spec.json.status` / `spec.json.blocker` must reflect the top-level block if work is globally blocked.
-*   **Timestamp Rule:** Update `task_registry[path].started_at`, `completed_at`, and `last_updated_at` consistently with the new state. Also refresh `spec.json.updated_at`.
-*   **Done-State Rule:** Never set `task_registry[path].status = "done"` unless `receipts/<task-basename>.md` is valid, or a legacy `## Evidence` receipt is valid. Write proof to the separate receipt first; never add execution evidence to a new-format task plan.
-*   **Receipt Integrity Rule:** A valid task receipt includes task identity/path, exact commands and outcomes, expected versus observed behavior, applicable negative/reachability/artifact proof, and Base/Head binding. If separate and legacy receipts both exist with conflicting proof identity, refuse `done`. `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, placeholders, and contract substitutions are not eligible.
-*   **Contract Fidelity Rule:** If the task file notes or evidence show that a named framework/auth/runtime choice from the spec was silently replaced, sync MUST refuse `done` until the spec is amended or the implementation is corrected.
-*   **Task Docs Rule:** After a task is moved to `done`, assess actual documentation impact and report `Docs impact: major|minor|none`. Only affected docs receive a follow-up checkpoint.
-
-## 2. Updating `tasks/task-**.md`
-
-The structure of `tasks/task.md` relies heavily on exact keyword markers. Follow these surgical protocols against `tasks/task-R*.md`:
-
-### A. Completing a Task
-When `/hapo:sync <feature> <task-id> done`:
-1. Find: `**Status:** pending` (or `in_progress` / `blocked`).
-2. Resolve `receipts/<task-basename>.md` first, with legacy `## Evidence` as fallback. If neither has valid proof, STOP and refuse to mark the task done.
-3. Refuse completion if the receipt contains any non-passing marker such as `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation substituted a named contract with a placeholder/custom simplification.
-4. Replace with: `**Status:** done`.
-5. Update only implemented checkboxes under `## Changes`; never append receipt fields to the task plan.
-6. Surface `Docs impact: major|minor|none`; if impact is not `none`, name the affected docs and the follow-up checkpoint.
-
-### B. Blocking a Task
-When `/hapo:sync <feature> <task-id> blocked "API error"`:
-1. Find: `**Status:** <anything>`.
-2. Replace with: `**Status:** blocked`.
-3. Record the reason and timestamp in `task_registry[path].blocker`; do not add
-   a non-canonical task section.
-
-### C. Starting / Resuming a Task
-When `/hapo:sync <feature> <task-id> in_progress`:
-1. Find: `**Status:** pending` (or `blocked`).
-2. Replace with: `**Status:** in_progress`.
-3. Do NOT pre-check completion boxes.
-4. Stamp `task_registry[path].started_at` if missing and refresh `last_updated_at`.
-
-## 3. Audit Protocol
-
-When `/hapo:sync audit <feature>` is activated:
-1. **Load Truth:** Read `specs/<feature>/spec.json`.
-2. **Scan Directory:** Loop through `specs/<feature>/tasks/`.
-3. **Compare Constraints:** Rebuild `task_files` from disk, ensure every file exists in `task_registry`, and compare markdown `**Status:**` headers against `task_registry[path].status`.
-4. **Reconciliation Rules:**
-   - Missing registry entry → create it
-   - Missing disk file referenced in registry → remove or flag it
-   - Markdown says `done` but registry not done → registry wins only if a canonical separate or legacy receipt exists; otherwise downgrade markdown or flag conflict
-   - Registry says `done` but markdown still pending → update markdown only if a canonical separate or legacy receipt exists
-   - Either side says `done` but neither receipt source has concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
-   - Both receipt sources exist with conflicting proof identity → fail closed and require manual reconciliation
-   - Either side says `done` but the receipt contains `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit contract-substitution notes → downgrade to `in_progress` or flag conflict
-5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.
-6. **Task Docs Alert:** If audit reveals tasks newly marked `done`, include the actual docs impact; do not emit a generic docs-sync request when no docs are affected.
-
-## 4. Feature closeout
-
-- Before all tasks are done, missing `feature-receipt.md` is normal.
-- After all tasks are done, require final integration execution and one valid
-  `feature-receipt.md`; never derive it from task status alone.
-- A taskless Compact/Full spec uses the same final feature receipt and does not
-  require a synthetic registry entry.
+# Sync protocols
+
+Use surgical edits and verify bytes after writing. Never replace a whole packet
+to change one task state.
+
+## Resolve safely
+
+1. Canonicalize `specs/<feature>/` under the configured specs root.
+2. Require regular non-symlink `plan.md` and flat `task-*.md` files.
+3. Match the requested task by exact basename; reject aliases and ambiguity.
+4. Require exactly one `Status: pending|in_progress|paused|blocked|done` line.
+5. Read dependencies and acceptance IDs before choosing a transition.
+
+## Transitions
+
+- `pending|paused|blocked -> in_progress`: change Status only; preserve a real
+  blocker in history or remove it only when its prerequisite changed.
+- `* -> blocked`: write a concrete reason and keep existing proof unchanged.
+- `in_progress -> done`: validate the current inline Receipt first, then change
+  Status. Never perform this order in reverse.
+- `done -> in_progress`: allowed when proof becomes stale or implementation
+  changes; retain the stale receipt only when clearly labelled non-authoritative.
+
+For Flash, keep `Status: in_progress`, `FLASH_UNVERIFIED`, and blocker
+`awaiting /hapo:test <feature>`. Only sync-finalize with fresh canonical proof
+may replace that marker and set done.
+
+## Receipt update
+
+The primary Receipt is the final `## Receipt` section in the task file. It must
+contain one Verification PASS, one exact Command, one successful Exit, one
+runtime-bound Base/Head pair, and non-empty fenced current output. Preserve
+additional concrete negative, reachability, and artifact evidence.
+
+Reject duplicate Receipt headings, placeholders, copied output, conflicting
+success/failure markers, zero executed tests when tests are required, stale
+provenance, and path or artifact mismatch.
+
+## Audit reconciliation
+
+- Plan row without task file: report missing; do not synthesize scope.
+- Task file without plan row: report unknown; do not silently adopt it.
+- Done without valid Receipt: downgrade only when the repair is deterministic,
+  otherwise block and request direction.
+- Receipt on unfinished task: preserve it only if it is clearly historical;
+  otherwise report the conflict.
+- Missing or cyclic dependency: block affected tasks.
+- Overlapping write ownership in one proposed wave: serialize or request an
+  ownership decision.
+- Acceptance ID not mapped both ways: report traceability drift.
+
+After a repair, re-read every changed file and print a concise mismatch/fix/
+unresolved summary. Never claim execution proof from the audit itself.
+
+## Legacy workflow compatibility
+
+For `spec.json` packets, resolve exact `task_registry` paths and synchronize
+registry timestamps plus nested task Markdown. Validate the canonical separate
+receipt (with legacy inline Evidence only as the supported fallback), reject
+conflicting proof identities, preserve classified minimum and planning_depth,
+and use the installed legacy policy for lane, execution_tier, Flash promotion,
+and final feature closeout.

package/src/codex/AGENTS.md

@@ -8,12 +8,25 @@
 - CafeKit agents live in `.codex/agents/*.toml` and are auto-discovered after the repository is trusted.
 - Runtime support lives in `.codex/rules/`, `.codex/scripts/`, `.codex/references/`, and `.codex/runtime.json`.
 - Project hooks live in `.codex/hooks.json`; review trusted hooks with `/hooks`.
-- Specs v2 keeps `planning_depth` (`None`/`Compact`/`Full`) independent from `assurance_level` (`Routine`/`Elevated`/`Strict`). Any risk has an Elevated automatic floor; Strict is opt-in only for an explicit user/project independent-audit requirement or a user-confirmed scope-specific audit decision, never a keyword or severity label. Run the artifact router before discovery: None has no durable spec; Compact/Full share the bounded `spec.json` + `requirements.md` + `design.md` core. Research requires material unresolved uncertainty, an external-current fact, or an explicit request; tasks require typed coordination topology. Full/Strict never create either automatically.
-- In v2.1, `spec.json` is machine authority and Markdown is a human projection. Task plans have exactly seven sections: `Outcome`, `Scope`, `Anchors and Ownership`, `Changes`, `Acceptance`, `Dependencies`, `Verification Plan`; the only ownership table is `ID | Type | Target | Role | Access | Action`.
-- Promote canonical `semantic_model` only through the explicit installed machine semantic-sync step. A semantic Markdown edit requires resynchronization and round-trip validation; never hand-author the machine shape.
-- `coordination.boundaries` typed as ownership/dependency/transition/proof/parallel is topology authority. Legacy trigger fields, priority markers, related-file lists, approval fields, and prose are inert compatibility inputs, never canonical authoring.
-- Canonical lifecycle is exactly `in_progress`, `paused`, `blocked`, or `done`. Technical readiness differs from closeout; authors cannot self-declare readiness, review authority, execution proof, or final `done`.
-- Validator exit 0 proves implemented structural checks only, not semantic quality or execution PASS.
+- New Specs work uses the process-first flow. `$hapo-specs` opens C1, writes
+  `specs/<feature>/plan.md` with flat `task-NN-*.md` files beside it, then opens
+  C2 after adversarial review. It never starts implementation.
+- Start implementation only through a new explicit `$hapo-develop` invocation.
+  Execute one unblocked task at a time; each task has exactly one `Status:`
+  field and the controller is its sole state-and-proof writer.
+- Use `$hapo-sync` for surgical updates to observed file state. A done task
+  requires a canonical final inline `## Receipt` with the exact command,
+  `Exit: 0`, `Verification: PASS`, runtime-derived Base and Head values, and
+  non-empty fenced current output.
+- At C3, show current receipts and unresolved limitations. The user decides
+  completion; no command, review, or host state may invent approval or proof.
+
+### Legacy Specs compatibility
+
+Existing packets containing `spec.json`, nested tasks, or legacy kernel
+artifacts keep their installed adapter, `task_registry`, `semantic_model`,
+`planning_depth`, lane, `execution_tier`, machine authority, separate receipts,
+and closeout contract. Do not migrate them during unrelated process-first work.
 
 ## Codex caveats
 
@@ -25,4 +38,4 @@
 
 Codex's native project instruction surface is root `AGENTS.md`. Combined installs keep this Codex block there because no separate Codex project entrypoint is configured by CafeKit. Other runtimes may read the same root file; this shared-root trade-off is intentional and must not be treated as filesystem isolation.
 
-**Ownership / ignore contract (fail-safe):** This Codex block is owned by Codex CLI only. If you are Claude Code, OpenCode, or any other runtime, ignore this entire Codex block and consume only CORE plus your native block. If you cannot determine which block is yours, treat the file as CORE-only. Do not treat another runtime's block as instructions.
+**Ownership / ignore contract (fail-safe):** This Codex block is owned by Codex CLI only. If you are Claude Code or any other runtime, ignore this entire Codex block and consume only CORE plus your native block. If you cannot determine which block is yours, treat the file as CORE-only. Do not treat another runtime's block as instructions.

package/src/codex/hooks/lib/spec-receipt.cjs

@@ -69,6 +69,22 @@ function checkReceiptDetails(featureDir, taskPath, task, runtimeContext) {
   if (!policy) return { failures: ['shared_validator'], status: 'missing' };
   return receiptHelper().checkTaskReceipt(featureDir, taskPath, task, runtimeContext, policy);
 }
+function checkWorkflowReceiptDetails(featureDir, taskPath, runtimeContext) {
+  const policy = getSharedPolicy();
+  const receipt = receiptHelper();
+  if (!policy || typeof receipt.checkWorkflowTaskReceipt !== 'function') {
+    return { failures: ['shared_validator'], status: 'missing' };
+  }
+  return receipt.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy);
+}
+function checkWorkflowReceiptSet(candidates, projectRoot, runtimeSession) {
+  const policy = getSharedPolicy();
+  const receipt = receiptHelper();
+  if (!policy || typeof receipt.checkWorkflowReceiptSet !== 'function') {
+    return { failures: [{ featureName: '<set>', taskPath: '<set>', failures: ['shared_validator'] }] };
+  }
+  return receipt.checkWorkflowReceiptSet(candidates, projectRoot, runtimeSession, policy);
+}
 function checkReceipt(featureDir, taskPath, task, runtimeContext) {
   const map = {
     unsafe_path: 'a', missing_receipt: 'b', task_status: 'a', completed_at: 'd',
@@ -91,6 +107,8 @@ module.exports = {
   checkFeatureReceipt,
   checkReceipt,
   checkReceiptDetails,
+  checkWorkflowReceiptDetails,
+  checkWorkflowReceiptSet,
   evidenceBody,
   getSharedPolicy,
   getSharedValidate,

package/src/codex/hooks/lib/spec-utils.cjs

@@ -100,6 +100,29 @@ function resolveActiveSpec(projectRoot, runtime, explicitFeature, explicitPath)
   });
 }
 
+function resolveWorkflowCandidate(projectRoot, runtime, explicitFeature, explicitPath) {
+  const resolver = sharedResolver();
+  if (typeof resolver.resolveWorkflowCandidate !== 'function') {
+    return resolveActiveSpec(projectRoot, runtime, explicitFeature, explicitPath);
+  }
+  if (projectRoot && typeof projectRoot === 'object') {
+    return resolver.resolveWorkflowCandidate(projectRoot);
+  }
+  return resolver.resolveWorkflowCandidate({
+    projectRoot,
+    runtime,
+    explicitFeature,
+    explicitPath,
+  });
+}
+
+function refineWorkflowGateResolution(resolved) {
+  const resolver = sharedResolver();
+  return typeof resolver.refineWorkflowGateResolution === 'function'
+    ? resolver.refineWorkflowGateResolution(resolved)
+    : resolved;
+}
+
 function findActiveSpec(projectRoot, runtime) {
   const resolved = resolveActiveSpec(projectRoot, runtime);
   if (!resolved) return null;
@@ -122,6 +145,8 @@ module.exports = {
   findAllActiveSpecs,
   findAllSpecCandidates,
   resolveActiveSpec,
+  resolveWorkflowCandidate,
+  refineWorkflowGateResolution,
   specsDirectory,
   taskStatusMap,
 };

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

@@ -12,6 +12,8 @@ const {
 const {
   checkFeatureReceipt,
   checkReceiptDetails,
+  checkWorkflowReceiptDetails,
+  checkWorkflowReceiptSet,
   loadSharedPolicy,
 } = require('./lib/spec-receipt.cjs');
 const { taskStatusMap } = require('./lib/spec-utils.cjs');
@@ -46,13 +48,33 @@ try {
     throw new Error('shared workflow policy lacks completion authority functions');
   }
   const resolver = require('./lib/spec-utils.cjs');
-  const resolved = FINAL_STATE.resolveCandidate({
-    resolver,
-    projectRoot,
-    runtime,
-    payload,
-  });
+  let resolved = typeof resolver.resolveWorkflowCandidate === 'function'
+    ? resolver.resolveWorkflowCandidate({ projectRoot, runtime, target: payload, includeCompleted: true })
+    : FINAL_STATE.resolveCandidate({ resolver, projectRoot, runtime, payload });
+  if (typeof resolver.refineWorkflowGateResolution === 'function') {
+    resolved = resolver.refineWorkflowGateResolution(resolved);
+  }
   if (!resolved) process.exit(0);
+  if (resolved.layoutKind === 'process-v3-completed-set') {
+    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 checked = checkWorkflowReceiptSet(
+      resolved.candidates,
+      projectRoot,
+      sessionIdentity(payload),
+    );
+    if (checked.failures.length === 0) process.exit(0);
+    const lines = [`Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
+    for (const failure of checked.failures) {
+      lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
+      lines.push(`  Write a runtime-bound \`## Receipt\` with the planned command in \`specs/${failure.featureName}/${failure.taskPath}\`.`);
+    }
+    emitBlock(lines.slice(0, 8).join('\n'));
+    process.exit(0);
+  }
   if (resolved.error === 'multiple_active' || resolved.error === 'multiple_persisted') {
     process.stdout.write(`${JSON.stringify({
       decision: 'block',
@@ -76,10 +98,12 @@ 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)
+  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);
-  if (active.spec.schema_version === '2.1') {
+  if (!processWorkflow && activeSpec.schema_version === '2.1') {
     const finalState = FINAL_STATE.evaluateCloseout({
       policy: POLICY,
       projectRoot,
@@ -95,7 +119,7 @@ try {
   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: sessionIdentity(payload),
   });
@@ -104,8 +128,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.spec.task_registry || {};
-  const currentStatuses = taskStatusMap(active.spec);
+  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 cacheFile = path.join(
     projectRoot,
     '.codex',
@@ -137,7 +163,7 @@ try {
   const previous = cacheExists && cacheEntries[runtimeContext.context_id]
     ? cacheEntries[runtimeContext.context_id].tasks || {}
     : {};
-  const staleFlashTasks = Object.entries(registry)
+  const staleFlashTasks = processWorkflow ? [] : Object.entries(registry)
     .filter(([, task]) => POLICY.isStaleFlashDone(task))
     .map(([taskPath]) => taskPath);
   if (staleFlashTasks.length > 0) {
@@ -154,7 +180,9 @@ try {
   const receiptBodies = new Map();
   const failures = allDoneTasks
     .map((taskPath) => {
-      const proof = checkReceiptDetails(featureDir, taskPath, registry[taskPath], runtimeContext);
+      const proof = processWorkflow
+        ? checkWorkflowReceiptDetails(featureDir, taskPath, runtimeContext)
+        : checkReceiptDetails(featureDir, taskPath, registry[taskPath], runtimeContext);
       if (proof.body) receiptBodies.set(taskPath, proof.body);
       return {
         taskPath,
@@ -163,7 +191,7 @@ try {
     })
     .filter((result) => result.failures.length);
 
-  const featureCloseoutRequired = explicitCloseout && allDoneTasks.length > 0;
+  const featureCloseoutRequired = !processWorkflow && explicitCloseout && allDoneTasks.length > 0;
   const featureReceipt = featureCloseoutRequired
     ? checkFeatureReceipt(featureDir, runtimeContext)
     : null;
@@ -200,7 +228,9 @@ try {
     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.`);
+      : processWorkflow
+        ? `  Write a runtime-bound \`## Receipt\` with command output in \`specs/${active.featureName}/${path.posix.basename(result.taskPath)}\`.`
+        : `  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.'}`);