@haposoft/cafekit 0.15.3 → 0.16.0-rc.1

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

@@ -88,6 +88,22 @@ Forbidden generated artifacts:
 - Concise, prefer bullet lists; no fluff
 - Unresolved questions → list at the end of each document
 
+## Lane selection before spec gate
+
+Classify task risk at the runtime boundary before starting spec state or approval flow. Use the executable policy, not keyword count or prose alone:
+
+```bash
+node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
+# Downgrade from Critical requires explicit user authorization — model-supplied lane cannot bypass risk signals
+node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '{"riskSignals":{"auth":true},"override":"Direct","userAuthorized":true}' --json
+```
+
+- **Direct** — clear, isolated, reversible, low-risk work. May skip spec files, registry/state, and subagents. Still run targeted verification, diff self-check, and evidence proportional to blast radius. No spec/state/registry ceremony required.
+- **Standard** — default lane. Create one bounded spec artifact (`requirements.md` + `design.md` in the current layout), keep one canonical receipt, and run exactly one combined `code-auditor` review at feature ship point (not per-task).
+- **Critical** — destructive/irreversible, auth/payment/privacy/data, schema/migration, public contract, cross-runtime coupling, outcome-changing ambiguity, or difficult rollback. Require strict spec/state/evidence; delegation is risk-driven (inspector/test-runner/code-auditor enabled only when risk lens requires), not a fixed four-agent chain.
+
+Explicit `override` is allowed in either direction but is enforced at the runtime boundary. A model-supplied lane or downgrade must not bypass risk signals. Downgrading from Critical requires explicit user-originated authorization (`userAuthorized:true` or `origin:user`) and must surface the trade-off (reduced review/evidence coverage). Agent validation or --auto never fabricates `user_approved`; `generated`, `agent_validated`, and `user_approved` are independent booleans per `schema_version: "2.0"`.
+
 ## Default Behavior
 
 > **This section is the entry/dispatch layer ONLY.** It decides *which part of the pipeline to run and where to stop*. It does NOT change any pipeline step, the validator, templates, or rules.
@@ -112,15 +128,15 @@ Forbidden generated artifacts:
 
 ### Creation Mode Gate
 
-Shown once on the no-flag create path. Selects the **stop point only**.
+Shown once on the no-flag create path. Selects the **stop point only**. Approval schema is versioned (`schema_version: "2.0"`): each phase has `generated`, `agent_validated`, `user_approved` as independent booleans. `ready` requires all three true. Legacy `approved` field is rejected — `--auto` or agent validation never fabricates `user_approved`.
 
-| Option | Runs | Stops after | Approvals |
+| Option | Runs | Stops after | Approvals (v2) |
 |---|---|---|---|
-| **Auto (→ Tasks)** | Step 1→10 end-to-end | full (ready gate) | each phase `generated=true` + `approved=true` |
-| **Stop after Design** | Step 1→6 | `design` (before Step 7) | requirements + design `approved=true`; `ready_for_implementation=false` |
-| **Step by step** | one phase at a time | after each phase | per phase `generated=true`, `approved=false` until user approves |
+| **Auto (→ Tasks)** | Step 1→10 end-to-end | full (ready gate) | each phase `generated=true` + `agent_validated=true`; `user_approved` stays false until explicit user approval (`--auto` does NOT auto-set `user_approved`). Ready requires `generated && agent_validated && user_approved`. |
+| **Stop after Design** | Step 1→6 | `design` (before Step 7) | requirements + design `generated=true` + `agent_validated=true`; `user_approved=true` only after explicit user approval; later phases ungenerated; `ready_for_implementation=false` |
+| **Step by step** | one phase at a time | after each phase | per phase `generated=true`, `agent_validated` per agent check, `user_approved=false` until user explicitly approves |
 
-`--auto` = Auto without the gate. Early stops leave `ready_for_implementation=false` and emit Step 9b. Resume via `/hapo:specs` Interactive State Discovery.
+`--auto` = Auto without the gate. Early stops leave `ready_for_implementation=false` and emit Step 9b. Resume via `/hapo:specs` Interactive State Discovery. If legacy `approved` field is present, fail closed with migration guidance: replace `approved` with `agent_validated` + `user_approved` per `spec-state.json` template.
 
 ### Translation Mirror (optional reference copy)
 
@@ -210,16 +226,16 @@ Load: `references/scope-inquiry.md` (+ `references/ask-user-question-gates.md` f
 - Smell: >8 files / >2 new classes / >12 tasks → challenge; **>15 tasks → sibling specs**
 - User: Expand / Hold / Reduce. Skip if trivial (< 20 words, 1 file, "just do it")
 
-#### Execution Tier (auto-scale — after 5-Dimension assessment)
-Record in `spec.json.design_context.execution_tier`.
+#### Execution Tier (auto-scale — after 5-Dimension assessment) — legacy metadata
+Record in `spec.json.design_context.execution_tier` for backward compatibility. Tier is metadata only; **lane controls ceremony and delegation** (Direct/Standard/Critical). Light/Standard/Deep mappings are preserved for compatibility but lane policy is authoritative.
 
-| Tier | Trigger | Research | Discovery | Red-Team | Always runs |
+| Tier (legacy) | Trigger | Research | Discovery | Red-Team | Always runs |
 |---|---|---|---|---|---|
 | **Light** | Clear + Isolated + ≤2 tasks | skip (rationale) | minimal | Validate-only | scope_lock, EARS, **Layer 1+2** |
 | **Standard** | default / 3-4 tasks | targeted | light | per Step 8 | all of the above |
 | **Deep** | Complex/Critical / security-migration / 5+ tasks | full | full | Red-Team → Validate | all of the above |
 
-Grounding + validator + scope_lock never skip. Auth/payment/migration/schema/privacy force Deep. Tier never changes Hard Output Contract or DoCT.
+Grounding + validator + scope_lock never skip. Auth/payment/migration/schema/privacy force Deep (legacy) and Critical (lane). Tier remains backward-compatible execution metadata; lane controls ceremony and delegation.
 
 ### Step 4: Init
 - Check duplicate slugs; create `specs/<feature-name>/`
@@ -355,17 +371,18 @@ Early stop (**Stop after Design** / **Step by step**): no completion block, no v
 
 | Field | Rule |
 |---|---|
+| `schema_version` | Must be `"2.0"`; approvals use `generated` + `agent_validated` + `user_approved` per phase. Legacy `approved` field is rejected — fail closed with migration guidance. |
 | Status | `in_progress` / `blocked` / `done` / `archived` only (never emit `in-progress`) |
 | Timestamps | Each `timestamps.*_done` = actual ISO 8601 time at that phase; never reuse init |
-| Approvals (Auto / full pipeline) | `generated=true` + `approved=true` per completed phase |
-| Approvals (Stop after Design) | phases that ran: both true; later phases ungenerated; `ready_for_implementation=false` |
-| Approvals (Step by step) | `generated=true`, `approved=false` until user approves |
+| Approvals (Auto / full pipeline) | `generated=true` + `agent_validated=true`; `user_approved` stays false until explicit user approval (`--auto` never fabricates `user_approved`). Ready requires all three true per phase. |
+| Approvals (Stop after Design) | phases that ran: `generated=true` + `agent_validated=true`; `user_approved=true` only after explicit user approval; later phases ungenerated; `ready_for_implementation=false` |
+| Approvals (Step by step) | `generated=true`, `agent_validated` per agent check, `user_approved=false` until user explicitly approves |
 | `task_files` / `task_registry` | Exact match to disk after Step 7; registry keys = relative paths with full registry fields |
 | `validation_recommended` | `true` for auth/privacy/delete/migration/schema/extension/provider or 5+ tasks |
 | `translation` | optional mirror metadata; never affects ready gate |
-| `ready_for_implementation` | `true` only when requirements+design+tasks approved, `progress.tasks=done`, inventories match disk, and validation completed when recommended |
+| `ready_for_implementation` | `true` only when requirements+design+tasks each have `generated && agent_validated && user_approved`, `progress.tasks=done`, inventories match disk, and validation completed when recommended |
 
-If any approval is `false`, keep `ready_for_implementation = false`. Specs with 5+ tasks stay not-ready until `--validate` writes `validation.status = "completed"`.
+If any approval (`generated`, `agent_validated`, or `user_approved`) is `false`, keep `ready_for_implementation = false`. Specs with 5+ tasks stay not-ready until `--validate` writes `validation.status = "completed"`. Legacy `approved` fails closed — do not infer `user_approved` from `generated` or `agent_validated`.
 
 ## Subcommands
 

package/src/claude/skills/specs/references/review.md

@@ -99,7 +99,7 @@ These rules override any self-reasoning or optimization the system may attempt:
 Each reviewer receives:
 - Their specific lens and persona
 - Spec file paths to read directly
-- Instructions: find 5-10 flaws, findings only, NO praise
+- Instructions: report findings only when backed by concrete citations
 
 **Reviewer instructions:**
 ```
@@ -111,8 +111,8 @@ Rules:
 - Be concrete: describe failure scenario, not just "could be a problem"
 - Rate severity: Critical (blocks success) | High (significant risk) | Medium (notable concern)
 - Skip trivial observations (style, naming, formatting)
-- No praise. No "overall looks good". Only findings.
-- 5-10 findings. Quality over quantity.
+- No praise. No "overall looks good". Only evidence-backed findings.
+- Quality over quantity; do not pad to a count.
 ```
 
 #### Step 5: Collect → Deduplicate → Cap

package/src/claude/skills/specs/rules/tasks-generation.md

@@ -32,7 +32,7 @@ Detail bullets must include:
    - API payloads, routes, and JSON contracts.
    - Edge cases, error handling, and exact validation thresholds (e.g., `Return 403 if invalid`).
 
-**Rationale**: Humans review tasks to verify business requirements are met; AI Coders (like god-developer or ck) read tasks to write explicit code. If you only write business jargon, the AI hallucinates. If you only write code names, the human reviewer cannot verify the business value. You MUST provide both.
+**Rationale**: Humans review tasks to verify business requirements are met; AI Coders (like implementer or ck) read tasks to write explicit code. If you only write business jargon, the AI hallucinates. If you only write code names, the human reviewer cannot verify the business value. You MUST provide both.
 
 ### 2. Task Integration & Progression
 

package/src/claude/skills/specs/templates/spec-state.json

@@ -1,4 +1,5 @@
 {
+  "schema_version": "2.0",
   "feature_name": "{{FEATURE_NAME}}",
   "created_at": "{{TIMESTAMP}}",
   "updated_at": "{{TIMESTAMP}}",
@@ -12,15 +13,18 @@
   "approvals": {
     "requirements": {
       "generated": false,
-      "approved": false
+      "agent_validated": false,
+      "user_approved": false
     },
     "design": {
       "generated": false,
-      "approved": false
+      "agent_validated": false,
+      "user_approved": false
     },
     "tasks": {
       "generated": false,
-      "approved": false
+      "agent_validated": false,
+      "user_approved": false
     }
   },
   "scope_lock": {

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

@@ -14,8 +14,21 @@ metadata:
 
 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.
 
-## Supported Commands
+## Lane-aware synchronization
+
+Read lane policy before mutating state:
+
+```bash
+node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
+```
 
+- Direct may have no spec/state/registry; sync only concrete targeted evidence and never invents approval state.
+- Standard stores one bounded spec and one canonical feature receipt; one combined `code-auditor` review gates feature closeout.
+- Critical requires strict durable evidence and `inspector → implementer → test-runner → code-auditor` delegation by default.
+- `generated`, `agent_validated`, and `user_approved` are independent. Missing `user_approved` stays false; sync never auto-approves user-owned state.
+- Explicit lane overrides must preserve automatic classification and warning in receipt/state output, especially Critical downgrades.
+
+## Supported Commands
 ### 1. Task Synchronization
 Update a specific task's status and automatically check its relevant sub-checkboxes.
 
@@ -44,5 +57,17 @@ Scans the `spec.json` against all physical `task-R*.md` files to detect mismatch
 5. **Task Docs Hook:** Every time `hapo:sync` marks a task as `done`, it must flag that a task-level docs checkpoint is now due for that verified task.
 6. **Phase Prompt Rule:** When `hapo:sync` marks the final pending task in the whole feature as `done`, it should automatically prompt the user if they'd like to advance the phase, but only after the docs checkpoint for that last completed task has been considered.
 
+### 4. Explicit Flash Finalization
+
+**Usage:** `/hapo:sync <feature_name> <task_id|task-file> sync-finalize`
+
+This is the only operation allowed to turn a flash-promoted task (`Verification: PASS`, `status: in_progress`, `readyForSync: true`) into `done` and unblock dependencies. A normal `done` request cannot bypass flash promotion or stale `FLASH_UNVERIFIED` state.
+
+### Flash implementation state
+
+Executable policy source: `.claude/scripts/workflow-policy.cjs` (source: `src/claude/scripts/workflow-policy.cjs`). Use `promoteFlashTask` only after exact task Evidence and reachability return PASS; 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 blocker `awaiting /hapo:test <feature>`; do not unblock dependencies. `/hapo:test` may promote one task only after its exact Evidence and reachability PASS, replacing the receipt with proof, clearing blocker, and setting `readyForSync: true` while dependencies remain blocked. Only explicit `/hapo:sync ... sync-finalize` may set `done` and unblock. FAIL, BLOCKED, and NO_TESTS remain `in_progress`.
+
 ## References
 Read `references/sync-protocols.md` for exact Search/Replace regex patterns and JSON schema expectations before acting on the files.

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

@@ -2,11 +2,11 @@
 
 The following guidelines dictate exactly how `hapo:sync` should interact with files to prevent data corruption.
 
-**Canonical task status vocabulary:** `pending`, `in_progress`, `blocked`, `done`
+**Flash implementation state:** `FLASH_UNVERIFIED` MUST remain `status: "in_progress"` with blocker `awaiting /hapo:test <feature>`. It never unblocks dependencies. A task-scoped `/hapo:test` PASS replaces receipt with real `Verification: PASS`, clears blocker, and sets `readyForSync: true` while dependency blocking remains. Only explicit `/hapo:sync ... sync-finalize` may set `done` and unblock; FAIL, BLOCKED, and NO_TESTS stay `in_progress`.
 
-## 1. Updating `spec.json`
+**Lane state rule:** classify Direct/Standard/Critical before sync. Direct may omit spec/state/registry for clear, reversible low-risk work; Standard uses one bounded spec and one feature receipt; Critical requires strict durable evidence. Explicit overrides must retain automatic lane, risk signals, and warning. `generated`, `agent_validated`, and `user_approved` are independent booleans; never infer or write `user_approved: true` from agent fields.
 
-When requested to update a phase or change task configuration, `spec.json` must maintain its strict schema (defined in `hapo:specs/templates/spec-state.json`).
+## 1. Updating `spec.json`
 
 *   **JSON Modification Rule:** Do not output whole files. Instead, load the JSON structure, apply the update to `status`, `current_phase`, `blocker` (if any), `task_files`, and the relevant `task_registry` entry, then overwrite the file cleanly.
 *   **Task Registry Rule:** Resolve the incoming task reference to a single relative path in `task_registry`. Accept either:

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

@@ -43,9 +43,17 @@ When a feature name or `specs/<feature>` path is supplied, testing is spec-aware
 Load `spec.json`, `requirements.md`, `design.md`, active/recent task files, and task `Evidence` / test-plan proof.
 The verdict MUST compare executed/reachable behavior against `scope_lock`, requirements, design contracts, task Completion Criteria, and runtime reachability obligations.
 Build/typecheck success without scoped runtime proof is not PASS.
-</SCOPE-GATE>
+## Flash promotion contract
+
+Executable policy source: `.claude/scripts/workflow-policy.cjs` (source: `src/claude/scripts/workflow-policy.cjs`). Its `consumeReviewVerdict` and `promoteFlashTask` functions are sole source for PASS/FAIL/BLOCKED handling and task-scoped promotion.
+
+When `/hapo:test <feature>` finds a task with `status: "in_progress"` and receipt `FLASH_UNVERIFIED`, evaluate that task's exact Evidence and runtime reachability only:
+
+- PASS → replace receipt with concrete proof while keeping `status: "in_progress"`, `dependencyBlocked: true`, `unblocks: false`, and `readyForSync: true`; only explicit `/hapo:sync ... sync-finalize` may set `done` and unblock dependents.
+- FAIL, BLOCKED, or NO_TESTS → keep `status: "in_progress"`, keep or update blocker, and do not promote any other flash task.
+- Never blanket-promote every flash task in a feature because one task passed.
+
 
-## 4-Phase Execution
 
 ```mermaid
 flowchart TD
@@ -153,7 +161,7 @@ Return a **structured verdict** (required format — not free-form prose):
 
 ### Action
 - PASS → Proceed. Hand off to hapo:code-review.
-- FAIL → [list specific fixes needed] → Return to god-developer. (If REGRESSION: label "Test Regression — tests were deleted or weakened to produce green result")
+- FAIL → [list specific fixes needed] → Return to implementer. (If REGRESSION: label "Test Regression — tests were deleted or weakened to produce green result")
 - PARTIAL → [list uncovered areas] → Consider adding tests.
 - NO_TESTS → No test runner detected. User must configure tests first.
 
@@ -176,7 +184,7 @@ It merges the JSON data into `.hapo/test-memory.json` per `references/test-memor
 | `hapo:code-review` | runs in parallel | Both run at Quality Gate Step 4 |
 | `hapo:develop` | orchestrates | Spawns hapo:test at Step 4 |
 | `inspector` agent | hapo:test → | Scout test file locations when structure is unfamiliar |
-| `god-developer` agent | hapo:test → | FAIL verdicts route back here for fixing |
+| `implementer` agent | hapo:test → | FAIL verdicts route back here for fixing |
 | `test-runner` agent | hapo:test → | Primary executor, spawned via the `Agent` tool |
 | chrome-devtools scripts | test-runner → | UI verification (navigate, screenshot, console, network, performance, aria-snapshot, inject-auth) |
 

package/src/claude/skills/test/references/failure-triage.md

@@ -35,21 +35,21 @@ Failure detected
 ├─ Compile Error (#1)
 │   → STOP immediately. Do NOT run further tests.
 │   → Report: file, line, error message.
-│   → Action: return to god-developer. Fix compile errors first.
+│   → Action: return to implementer. Fix compile errors first.
 │
 ├─ Logic Error (#2)
 │   → Report: test name, file:line, expected value, actual value.
-│   → Action: return to god-developer with precise location.
+│   → Action: return to implementer with precise location.
 │   → Do NOT modify test to make it pass.
 │
 ├─ Environment Error (#3)
 │   → Report: which service/env var is missing.
-│   → Action: escalate to USER (not god-developer).
+│   → Action: escalate to USER (not implementer).
 │     "Environment issue: [DB/service] not reachable. Please start it."
 │
 ├─ Flaky Test (#4)
 │   → Report: test name + "intermittent failure observed".
-│   → Action: flag for god-developer review.
+│   → Action: flag for implementer review.
 │     Likely cause: shared state, async timing, or test ordering.
 │
 ├─ Coverage Gap (#5)
@@ -59,17 +59,17 @@ Failure detected
 │
 ├─ Build Error (#6)
 │   → Report: build command, error output (last 20 lines).
-│   → Action: return to god-developer.
+│   → Action: return to implementer.
 │
 ├─ UI Console Error (#7)
 │   → Report: error message, source file, line number.
-│   → Action: return to god-developer if JS error.
+│   → Action: return to implementer if JS error.
 │     If external script error: flag as warning only.
 │
 ├─ UI Network Error (#8)
 │   → Report: endpoint URL, status code, response body excerpt.
-│   → Action: 404 → god-developer (missing route/resource).
-│     500 → god-developer (server error). 401/403 → auth issue (user).
+│   → Action: 404 → implementer (missing route/resource).
+│     500 → implementer (server error). 401/403 → auth issue (user).
 │
 ├─ UI Performance (#9)
 │   → Report: specific metric name + actual value + threshold.
@@ -77,27 +77,27 @@ Failure detected
 │
 ├─ Accessibility Error (#10)
 │   → Report: element role + missing attribute.
-│   → Action: return to god-developer. Add aria-label / alt / for attributes.
+│   → Action: return to implementer. Add aria-label / alt / for attributes.
 │
 ├─ User Flow Error (#11)
 │   → Report: step failed (e.g., login submit), expected vs actual URL/state.
-│   → Action: return to god-developer to fix E2E UI flow.
+│   → Action: return to implementer to fix E2E UI flow.
 │
 ├─ SEO Error (#12)
 │   → Report: missing tag or invalid setup (e.g., no H1, bad canonical).
-│   → Action: return to god-developer. Add missing HTML meta tags.
+│   → Action: return to implementer. Add missing HTML meta tags.
 │
 ├─ Security Warning (#13)
 │   → Report: missing header names or exposed secret pattern.
-│   → Action: return to god-developer. Add helmet/headers or remove secrets.
+│   → Action: return to implementer. Add helmet/headers or remove secrets.
 │
 ├─ Broken Links (#14)
 │   → Report: crawler source URL → broken target URL (404).
-│   → Action: return to god-developer to fix href paths.
+│   → Action: return to implementer to fix href paths.
 │
 └─ UI Visual Error (#15)
     → Report: AI parsed visual issue (e.g., button overlapping text).
-    → Action: return to god-developer to fix CSS/layout issues.
+    → Action: return to implementer to fix CSS/layout issues.
 ```
 
 ---
@@ -107,11 +107,11 @@ Failure detected
 | Failure count | Verdict | Action |
 |---|---|---|
 | 0 failures | **PASS** | Proceed to hapo:code-review |
-| 1–2 failures | **FAIL** | Return to god-developer with targeted fix list |
-| 3–10 failures | **FAIL** | Return to god-developer, flag as "significant failures" |
+| 1–2 failures | **FAIL** | Return to implementer with targeted fix list |
+| 3–10 failures | **FAIL** | Return to implementer, flag as "significant failures" |
 | > 10 failures OR 0 tests pass | **COLLAPSE** | Call `AskUserQuestion`: "Test suite critically broken. User intervention required." |
 | Only coverage gaps | **PARTIAL** | Proceed to hapo:code-review, attach coverage gap list |
-| Environment errors only | **BLOCKED** | Escalate to user (not god-developer) |
+| Environment errors only | **BLOCKED** | Escalate to user (not implementer) |
 
 ---
 

package/src/claude/skills/test/references/test-memory.md

@@ -19,7 +19,7 @@ If the file does not exist, the `hapo:test` skill (or the orchestrator) MUST cre
 The `test-runner` agent is Read-Only. At Phase 1, it must read `.hapo/test-memory.json` (if it exists) to factor into its testing process:
 - **`env_setup_commands`**: Commands that must be run before tests (e.g. `docker compose up -d redis`). If listed, flag missing dependencies instead of immediate failure.
 - **`flaky_tests`**: Array of test file paths. If a failure occurs in one of these files, the verdict should explicitly note `(Known Flaky Test)`.
-- **`known_issues`**: Issues that god-developer or user marked as ignored.
+- **`known_issues`**: Issues that implementer or user marked as ignored.
 
 ## Writing to Memory
 
@@ -28,7 +28,7 @@ Because `test-runner` is restricted from editing files, it cannot update the mem
 Example:
 ```markdown
 ### Action
-→ [FAIL] Return to god-developer: Fix CSS layout offset.
+→ [FAIL] Return to implementer: Fix CSS layout offset.
 
 <lessons_learned>
 {

package/src/codex/AGENTS.md

@@ -1,30 +1,22 @@
-# CafeKit for Codex CLI
+## Codex runtime
 
-## Native runtime mapping
+- Repository instructions live in `AGENTS.md`.
+- CafeKit skills live in `.agents/skills/`; invoke them as `$hapo-<name>` or browse with `/skills`. Edit skills in the project, not in a global skills directory.
+- Run Python skill scripts with the project venv:
+  - macOS/Linux: `.agents/skills/.venv/bin/python3 scripts/<script>.py`
+  - Windows: `.agents\\skills\\.venv\\Scripts\\python.exe scripts\\<script>.py`
+- 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`.
 
-- Repository instructions: `AGENTS.md`.
-- CafeKit skills: `.agents/skills/`; invoke explicitly as `$hapo-<name>` or browse with `/skills`.
-- CafeKit agents: native auto-discovered definitions in `.codex/agents/*.toml`.
-- Runtime support: `.codex/rules/`, `.codex/scripts/`, `.codex/references/`, and `.codex/runtime.json`.
-- Lifecycle enforcement: `.codex/hooks.json`. Project hooks run only after the repository and hook definitions are trusted; review them with `/hooks`.
-- Do not create deprecated custom prompts or assume Claude/OpenCode command wrappers exist.
+## Codex caveats
 
-## Operating contract
+- Custom agents use snake_case names and `fork_turns: "none"` for explicit delegation.
+- Use Codex-native subagent delegation and task-state tools; do not rely on Claude-only tool labels.
+- Do not edit global trust configuration. Hooks are not a complete security boundary; hosted tools and untrusted project hooks can bypass the local hook path.
 
-- Read `README.md` and relevant project instructions before non-trivial work.
-- Choose the matching CafeKit skill before improvising a workflow.
-- Read `.codex/rules/workflow.md`, `.codex/rules/ai-dev-rules.md`, and
-  `.codex/rules/skill-workflow-routing.md` for non-trivial work. Load the other
-  `.codex/rules/*.md` files when their topic applies.
-- Keep scope surgical; prefer YAGNI, KISS, then DRY.
-- Do not claim completion without fresh build, test, runtime, or artifact evidence.
-- For spec tasks, keep `spec.json`, task status, `Completion Criteria`, and `Evidence` synchronized only after verification.
-- Privacy approvals are one request, one session, one retry. Only the user may submit the exact approval phrase emitted by the privacy hook.
+## Combined-install boundary
 
-## Runtime caveats
+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.
 
-- Codex custom agents use snake_case names.
-- When selecting a CafeKit custom role explicitly, call `spawn_agent` with `agent_type`, a unique snake_case `task_name`, `message`, and `fork_turns: "none"`. A full-history fork cannot change agent type.
-- Use Codex-native subagent delegation and task-state tools; do not rely on Claude-only tool labels.
-- The project `.codex/` layer—agents, config, rules, and hooks—loads only after the repository is trusted. Never edit the user's global trust configuration on their behalf.
-- Hooks are guardrails, not a complete security boundary. Hosted tools and untrusted project hooks may not enter the local hook path.
+**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.

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

@@ -39,9 +39,32 @@ function evidenceBody(text) {
 function safeTaskFile(featureDir, taskPath) {
   const target = path.resolve(featureDir, taskPath);
   const relative = path.relative(featureDir, target);
-  return !relative.startsWith('..') && !path.isAbsolute(relative)
-    ? target
-    : null;
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+  return target;
+}
+
+function validateCanonicalReceipt(body) {
+  const failures = [];
+  if (!/^\s*Verification:\s*PASS\s*$/m.test(body)) {
+    failures.push('verification_state');
+  }
+  if (!/^\s*Command(?:\(s\))?\s*:/m.test(body)) {
+    failures.push('command');
+  }
+  if (!/^\s*Exit\s*:|exit\s+code\s*[:=]|\bResult\s*:\s*PASS\b/im.test(body)) {
+    failures.push('exit_result');
+  }
+  const hasBase = /^\s*Base[ \t]*:[ \t]*\S/im.test(body);
+  const hasHead = /^\s*Head[ \t]*:[ \t]*\S/im.test(body);
+  const hasBaseSha = /\bbase_sha[ \t]*:[ \t]*\S/im.test(body);
+  const hasHeadSha = /\bhead_sha[ \t]*:[ \t]*\S/im.test(body);
+  if (!((hasBase && hasHead) || (hasBaseSha && hasHeadSha))) {
+    failures.push('provenance');
+  }
+  if (/\bartifact\b/i.test(body) && !/sha256:/i.test(body)) {
+    failures.push('artifact_hash');
+  }
+  return failures;
 }
 
 function checkReceipt(featureDir, taskPath, task) {
@@ -64,6 +87,36 @@ function checkReceipt(featureDir, taskPath, task) {
     || !(PASS_MARKER.test(body) || LEGACY_SUCCESS.test(body))
   ) {
     failures.push('c');
+  } else {
+    // Canonical receipt requirements: command, exit/result, provenance, unambiguous PASS
+    // For done tasks, require canonical fields. If missing, add e/f/g.
+    const canonical = validateCanonicalReceipt(body);
+    // Map canonical failures to letters e,f,g,h for backward compat checks
+    // Use detailed names but also add letters for gate reporting
+    const map = {
+      verification_state: 'c', // already covers but keep distinct
+      command: 'e',
+      exit_result: 'f',
+      provenance: 'g',
+      artifact_hash: 'h',
+    };
+    for (const fail of canonical) {
+      const letter = map[fail];
+      // Avoid duplicating c if already failed, but add specific
+      if (fail === 'verification_state' && failures.includes('c')) continue;
+      if (fail === 'verification_state') {
+        // This should have been caught by c, but if PASS present via legacy, still need strict PASS
+        if (!PASS_MARKER.test(body)) failures.push('c');
+        continue;
+      }
+      if (letter && !failures.includes(letter)) failures.push(letter);
+    }
+    // Additional strict check: legacy success alone is not sufficient for canonical
+    // If body contains only legacy PASS but not canonical Verification: PASS, c already would have caught if no PASS_MARKER?
+    // But we allow legacy for backward compat in c, but canonical requires PASS_MARKER, so we must enforce.
+    if (!PASS_MARKER.test(body)) {
+      if (!failures.includes('c')) failures.push('c');
+    }
   }
 
   const completedAt = task?.completed_at;
@@ -75,4 +128,4 @@ function checkReceipt(featureDir, taskPath, task) {
   return failures;
 }
 
-module.exports = { checkReceipt };
+module.exports = { checkReceipt, evidenceBody, safeTaskFile, validateCanonicalReceipt };

package/src/codex/hooks/rules.cjs

@@ -1,20 +1,16 @@
-#!/usr/bin/env node
 'use strict';
 
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const {
-  atomicWrite,
   getHookContext,
   logCrash,
   readPayload,
   resolveProjectPath
 } = require('./lib/hook-context.cjs');
 
-const COOLDOWN_MS = 5 * 60 * 1000;
-
-function cooldownFile(projectRoot, sessionId) {
+function reservationFile(projectRoot, sessionId) {
   const key = crypto.createHash('sha256')
     .update(String(sessionId || 'unknown'))
     .digest('hex')
@@ -22,21 +18,39 @@ function cooldownFile(projectRoot, sessionId) {
   return path.join(projectRoot, '.codex', 'hooks', '.logs', `rules-${key}.json`);
 }
 
-function recentlyInjected(file) {
+/** Reserve one injection slot per session. Returns null on reservation errors. */
+function reserveSession(projectRoot, sessionId) {
+  if (!sessionId) return null;
+  try {
+    const file = reservationFile(projectRoot, sessionId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ sessionId: String(sessionId) }), {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o600
+    });
+    return true;
+  } catch (error) {
+    return error.code === 'EEXIST' ? false : null;
+  }
+}
+
+function readRuntime(projectRoot) {
   try {
-    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return Date.now() - Number(state.ts || 0) < COOLDOWN_MS;
+    const file = path.join(projectRoot, '.codex', 'runtime.json');
+    return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : null;
   } catch {
-    return false;
+    return null;
   }
 }
 
 try {
   const payload = readPayload();
   if (!payload) process.exit(0);
-  const { projectRoot, runtime } = getHookContext(payload);
-  const cache = cooldownFile(projectRoot, payload.session_id);
-  if (recentlyInjected(cache)) process.exit(0);
+  const { projectRoot } = getHookContext(payload);
+  if (reserveSession(projectRoot, payload.session_id) !== true) process.exit(0);
+  const runtime = readRuntime(projectRoot);
+  if (runtime === null) process.exit(0);
 
   const respondLang = runtime.locale?.responseLanguage || '';
   const thinkLang = runtime.locale?.thinkingLanguage || (respondLang ? 'en' : '');
@@ -57,23 +71,10 @@ try {
     '## Rules',
     `- Markdown: Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
     '- Do not create markdown outside those directories unless explicitly asked.',
-    `- docs.maxLoc: ${runtime.docs?.maxLoc || 800} lines per doc file`,
-    '- Follow YAGNI · KISS · DRY.',
-    '- Reports: concise; unresolved questions last.',
-    '',
-    '## Skill Routing',
-    '- Choose skills using `.codex/rules/skill-workflow-routing.md` and `.codex/rules/skill-domain-routing.md`.',
-    '- Inspect installed skills with `node .codex/scripts/generate-skill-catalog.cjs --skills` when needed.',
-    '- Explicit user requests override routing suggestions.',
-    '',
-    '## Modularization',
-    '- Consider splitting code files over 200 lines at real concern boundaries.',
-    '- Check existing modules first; use descriptive names and comments.',
-    '- Skip modularization for markdown, plain text, shell, config, and env files.'
+    `- docs.maxLoc: ${runtime.docs?.maxLoc || 800} lines per doc file`
   );
 
   process.stdout.write(`${lines.join('\n')}\n`);
-  atomicWrite(cache, `${JSON.stringify({ ts: Date.now() })}\n`);
 } catch (error) {
   logCrash('rules', error);
 }

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

@@ -11,6 +11,10 @@ const {
 } = require('./lib/hook-context.cjs');
 const { checkReceipt } = require('./lib/spec-receipt.cjs');
 const { findActiveSpec, taskStatusMap } = require('./lib/spec-utils.cjs');
+const policyPath = path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs');
+const POLICY = require(fs.existsSync(policyPath)
+  ? policyPath
+  : path.join(__dirname, '../../claude/scripts/workflow-policy.cjs'));
 
 try {
   const payload = readPayload();
@@ -35,18 +39,25 @@ try {
     try { cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch { cache = {}; }
   }
 
-  if (!cacheExists) {
-    cache[active.featureName] = currentStatuses;
-    atomicWrite(cacheFile, `${JSON.stringify(cache)}\n`);
+  // Cache hardening: revalidate every done task on every Stop so a
+  // cached PASS cannot hide later receipt/provenance mutations.
+  // Cache is optimization only - validate every done task even on first run.
+  const previous = cacheExists ? (cache[active.featureName] || {}) : {};
+  const staleFlashTasks = Object.entries(registry)
+    .filter(([, task]) => POLICY.isStaleFlashDone(task))
+    .map(([taskPath]) => taskPath);
+  if (staleFlashTasks.length > 0) {
+    process.stdout.write(`${JSON.stringify({
+      decision: 'block',
+      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /hapo:test, then use explicit sync-finalize.`
+    })}\n`);
     process.exit(0);
   }
-
-  const previous = cache[active.featureName] || {};
-  const newlyDone = Object.keys(registry).filter((taskPath) => (
-    currentStatuses[taskPath] === 'done' && previous[taskPath] !== 'done'
+  const allDoneTasks = Object.keys(registry).filter((taskPath) => (
+    currentStatuses[taskPath] === 'done'
   ));
   const featureDir = path.join(active.specsDir, active.featureName);
-  const failures = newlyDone
+  const failures = allDoneTasks
     .map((taskPath) => ({
       taskPath,
       failures: checkReceipt(featureDir, taskPath, registry[taskPath])