@haposoft/cafekit 0.15.3 → 0.16.0-rc.2

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])

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

@@ -11,6 +11,10 @@ const {
   readPayload
 } = require('./lib/hook-context.cjs');
 const { findActiveSpec } = 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'));
 
 function cacheFile(projectRoot, sessionId) {
   const key = crypto.createHash('sha256')
@@ -29,7 +33,9 @@ try {
   if (!active) process.exit(0);
 
   const phase = active.spec.current_phase || active.spec.phase || 'unknown';
-  const tasks = Object.entries(active.spec.task_registry || {});
+  const taskRegistry = active.spec.task_registry || {};
+  const flashTasks = POLICY.flashState(taskRegistry);
+  const tasks = Object.entries(taskRegistry);
   const counts = tasks.reduce((result, [, task]) => {
     const status = task?.status || 'pending';
     result[status] = (result[status] || 0) + 1;
@@ -62,6 +68,9 @@ try {
     `- Phase: \`${phase}\` | Tasks: ${counts.done || 0} done / ${tasks.length} total`
   ];
   if (next) lines.push(`- Next unblocked: \`${next[0]}\``);
+  if (flashTasks.length > 0) {
+    lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. PASS promotion keeps task in_progress until explicit sync-finalize.`);
+  }
   lines.push(
     '- Sync `spec.json` and the task file only after verified work.',
     `- Validate with \`node .codex/scripts/validate-spec-output.cjs specs/${active.featureName}\`.`,

package/src/common/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md
+
+## 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.
+- `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.
+
+## Response style
+
+Keep replies focused and brief. Match written-file length to task needs. Do not add filler sections or redundant summaries. Lead with the outcome.
+
+## Uncertainty
+
+Say when you are unsure and what would settle it. Label inferences instead of presenting them as verified facts.
+
+## Delegation
+
+Do the work yourself when it takes a handful of tool calls. Delegate genuinely independent parallel tracks. Verification comes from the project's hooks and validators, not from spawning more agents.
+
+## Runtime ownership
+
+- This `CORE` block is runtime-neutral and safe for every runtime.
+- Runtime-specific instructions live in that runtime's own managed block, not in `CORE`.
+- In a combined install, consume `CORE` plus your native block only. Ignore managed blocks not owned by your runtime. If ownership is unclear, treat the file as `CORE`-only (fail-safe).
+
+## Commands
+
+<!-- Add project-specific install, test, lint, and build commands here. Keep commands executable. -->
+
+## Do not touch
+
+<!-- List files, directories, generated artifacts, or secrets that tasks must leave unchanged. -->
+
+## Slow or expensive
+
+<!-- Note commands, environments, or operations that need explicit planning before running. -->
+
+## Language Consistency <!-- cafekit:lang -->
+
+Match the language the user writes in. Technical terms, code identifiers, and file paths may remain in English.