@haposoft/cafekit 0.15.3 → 0.16.0-rc.1

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.

package/src/opencode/AGENTS.md

@@ -1,139 +1,39 @@
-# AGENTS.md
-
 Primary operating instructions for OpenCode using the CafeKit runtime.
 
 ## OpenCode Runtime Mapping
 
 - Project instructions live in `AGENTS.md`.
-- CafeKit commands live in `.opencode/commands/` and use OpenCode-native slash names without the `hapo:` prefix.
-- CafeKit subagents live in `.opencode/agents/` using OpenCode frontmatter.
-- CafeKit skills live in `.opencode/skills/` and are read natively by OpenCode.
-- Shared CafeKit support files live in `.opencode/rules/`, `.opencode/scripts/`, `.opencode/references/`, and `.opencode/runtime.json`.
-- OpenCode config is merged into `opencode.json`; keep project-specific model/provider choices there.
+- CafeKit commands live in `.opencode/commands/` and use OpenCode-native slash names.
+- CafeKit agents live in `.opencode/agents/` using OpenCode frontmatter.
+- CafeKit skills live in `.opencode/skills/` and are read natively by OpenCode; edit project-local skills there.
+- Run Python skill scripts with the project venv:
+  - macOS/Linux: `.opencode/skills/.venv/bin/python3 scripts/<script>.py`
+  - Windows: `.opencode\\skills\\.venv\\Scripts\\python.exe scripts\\<script>.py`
+- Support files live in `.opencode/rules/`, `.opencode/scripts/`, `.opencode/references/`, and `.opencode/runtime.json`.
+- OpenCode config is merged into `opencode.json`; keep project model/provider choices there.
 
-## Command Surface
+## Command surface
 
-Use these OpenCode commands:
+Use these OpenCode commands without the `hapo:` prefix:
 
-- `/brainstorm <idea-or-problem>`: scout and narrow an unclear idea before specs.
-- `/question <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when needed.
+- `/question <question>`: answer from repository evidence first.
+- `/brainstorm <idea-or-problem>`: narrow unclear ideas before specs.
 - `/specs <feature-or-spec-command>`: create, update, validate, or approve specs.
 - `/develop <feature> [task-file] [--flash]`: implement approved spec tasks.
 - `/test [scope|--full]`: verify implementation and collect evidence.
-- `/code-review [scope|--pending]`: review for correctness, regressions, and scope drift.
-- `/debug <issue>`: diagnose root cause without product-code edits.
-- `/hotfix <issue>`: apply a narrow, scout-first production fix.
-- `/docs [--init|--update|--summarize|--reconstruct]`: maintain or reconstruct project docs.
-- `/inspect <target>`: inspect source, artifacts, or external context.
-
-The underlying CafeKit skills are still named `hapo:*` in their documentation. In OpenCode, use the commands above; each command reads the matching skill from `.opencode/skills/<skill>/SKILL.md`.
-
-## Core Objective
-
-Act as the project orchestrator: understand the request, keep scope tight, use the right CafeKit skill/agent, and deliver verified work that follows the project's architecture.
-
-## Core Behavior
-
-These rules reduce common agent coding failures: hidden assumptions, overbuilt solutions, unrelated edits, and unverified completion claims. They take priority over speed-oriented shortcuts.
-
-### 1. Think Before Coding
-
-- Do not assume silently. State assumptions when they affect the work.
-- If multiple interpretations are plausible, surface them before implementation.
-- If the simpler option is likely better, say so and push back.
-- If the user asks a question about the project, use `/question` to answer from source evidence before planning.
-- Before feature planning or coding, read `./README.md` for project context.
-
-### 2. Simplicity First
-
-- Solve the requested problem with the smallest maintainable change.
-- Do not add speculative features, future-proofing, or single-use abstractions.
-- Reuse existing modules before creating new ones.
-- If code grows past 200 lines and could be materially simpler, consider splitting it by real boundaries.
-- Prefer YAGNI, KISS, and DRY in that order.
-
-### 3. Surgical Changes
-
-- Touch only files required by the task.
-- Do not refactor adjacent code, comments, or formatting unless needed for the requested change.
-- Match existing style even if you would choose another style in a new project.
-- Remove only dead code/imports created by your own change.
-- Mention unrelated issues instead of fixing them opportunistically.
-
-### 4. Goal-Driven Execution
-
-- Convert requests into verifiable success criteria.
-- For spec tasks, use `Completion Criteria` and `Evidence` as the source of truth. Existing task files may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
-- For bugs, reproduce with a failing test or concrete evidence when feasible before fixing.
-- Loop until verification passes or a real blocker is recorded.
-
-## CafeKit Operating Loop
-
-Use this loop for non-trivial work:
-
-1. Understand: read README, relevant docs, active spec/task, and existing code.
-2. Plan: choose the smallest coherent path; use `/question` for evidence-backed project questions and `/specs` for feature specs when ready.
-3. Execute: implement only the active task/scope; no placeholder completion.
-4. Verify: run exact task commands first, then repo-level lint/test/build as needed.
-5. Sync: mark task state only after proof exists.
-
-## OpenCode Runtime Limits And Replacements
-
-- Claude Code hooks/statusline/settings do not run in OpenCode.
-- Treat `.claude/rules/*` as explicit reference material, not injected hook context.
-- Map Claude-specific tools to OpenCode built-ins: `TodoWrite` → the `todowrite` tool; `AskUserQuestion` → the `question` tool; `Task` → OpenCode's agent/subtask flow.
-- Privacy and inspect gates are instruction-level gates in OpenCode unless a project-specific OpenCode plugin adds hard enforcement.
-
-## Operating Discipline
-
-- If a CafeKit skill may apply, read and use that skill before acting.
-- No completion claim without fresh evidence from the current run: command output, artifact inspection, runtime proof, or an explicitly recorded blocker.
-- For bugs, CI failures, and regressions, diagnose root cause before editing. Symptom patches are not completion.
-- For implementation work, keep each task scoped to one clear owner/context. Reviewers should receive task files, diffs, and acceptance criteria, not chat history.
-- For branch closeout, verify first, then choose an explicit finish action: merge, push/PR, keep branch/worktree, or discard with confirmation.
-
-## Definition Of Done
-
-A task is done only when all apply:
-
-- implementation satisfies `Completion Criteria`
-- `Evidence` is satisfied with concrete proof
-- preflight/build/test outcomes are passing or an explicit blocker is recorded
-- code review has no critical issues
-- a verification receipt exists before task state is synced to `done`
-
-`NO_TESTS` and `0 tests + exit 0` are not passing outcomes when the task requires automated tests.
-
-## Rule References
-
-Consult these when the task touches the relevant area:
+- `/code-review [scope|--pending]`: review correctness and regressions.
+- `/debug <issue>` and `/hotfix <issue>`: diagnose, then apply narrow fixes.
 
-- Primary workflow: `./.claude/rules/workflow.md`
-- Development rules: `./.claude/rules/ai-dev-rules.md`
-- Subagent coordination: `./.claude/rules/orchestrator.md`
-- Docs maintenance: `./.claude/rules/manage-docs.md`
-- State sync: `./.claude/rules/state-sync.md`
-- Hook handling reference: `./.claude/rules/hook-protocols.md`
-- Other protocols: `./.claude/rules/*`
+The underlying CafeKit skills are still named `hapo:*` in their documentation.
 
-## Skill And Script Use
+## OpenCode limits
 
-- Evaluate the installed skill catalog before work and activate the relevant skill(s).
-- If there is a reasonable chance a skill applies, prefer the skill workflow over ad hoc execution.
-- If modifying skills, edit the current project/runtime files, not `~/.claude/skills` directly.
-- Run Python skill scripts with the skill venv:
-  - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`
-  - Windows: `.claude\skills\.venv\Scripts\python.exe scripts\<script>.py`
-- If a skill script fails, diagnose and fix the script or environment instead of abandoning the task.
+Claude Code hooks, statusline, and settings do not run in OpenCode. Map Claude-only tools to OpenCode built-ins: `TodoWrite` → `todowrite`, `AskUserQuestion` → `question`, `Task` → the agent/subtask flow. The installed plugins under `.opencode/plugins/` provide the privacy, inspect-scope, spec-state, scaffold-guard, session-state, and docs-sync gates; other Claude runtime behavior has no OpenCode equivalent. The completion gate (`spec-gate`: `Verification: PASS` + `## Evidence` + `task_registry.completed_at`) is **advisory in OpenCode** — OpenCode has no Stop-hook equivalent and the `spec-gate` plugin (if present) runs as a best-effort `tool.execute.after` check, not a hard turn block like Claude/Codex.
 
-## Git And Reporting
+Runtime tier: OpenCode is **tier-2** for completion enforcement. Do not claim parity with Claude/Codex on `completion_gate`; `done` without a receipt emits an advisory warning/banner but does not hard-block the turn — rely on `spec-state` tollgate + manual `/hapo:test` verification.
 
-- Use conventional commits.
-- Do not add AI attribution by default.
-- Lint before commit and run the full required verification before push.
-- Keep commits focused on actual changes.
-- Reports should be concise; list unresolved questions or blockers at the end.
+## Combined-install boundary
 
-## Language Consistency
+OpenCode's native project instruction surface is root `AGENTS.md`. Combined installs keep this OpenCode block there because CafeKit has not proven a separate project instruction entrypoint for OpenCode. Other runtimes may read the same root file; this shared-root trade-off is intentional and must not be treated as filesystem isolation.
 
-When generating specs or structured project output, use the user's preferred language consistently across the whole spec workspace. Technical terms, code samples, and file paths may remain English.
+**Ownership / ignore contract (fail-safe):** This OpenCode block is owned by OpenCode only. If you are Claude Code, Codex CLI, or any other runtime, ignore this entire OpenCode 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/opencode/plugins/rules.ts

@@ -19,8 +19,12 @@
  */
 
 import type { Plugin } from "@opencode-ai/plugin";
+import {
+  createHash,
+} from "node:crypto";
 import {
   existsSync,
+  mkdirSync,
   readFileSync,
   writeFileSync,
 } from "node:fs";
@@ -36,7 +40,7 @@ function resolveProjectDir(directory?: string): string {
   return dirname(dirname(PLUGIN_DIR));
 }
 
-function readRuntime(cwd: string): Record<string, any> {
+function readRuntime(cwd: string): Record<string, any> | null {
   try {
     const file = join(cwd, ".opencode", "runtime.json");
     if (existsSync(file)) {
@@ -44,12 +48,27 @@ function readRuntime(cwd: string): Record<string, any> {
     }
   } catch {
     /* fail-open */
+    return null;
+  }
+  return null;
+}
+
+function reserveSession(cwd: string, sessionId?: string): boolean {
+  if (!sessionId) return false;
+  try {
+    const key = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+    const file = join(cwd, ".opencode", "plugins", ".logs", `rules-${key}.json`);
+    mkdirSync(join(cwd, ".opencode", "plugins", ".logs"), { recursive: true });
+    writeFileSync(file, JSON.stringify({ sessionId }), { encoding: "utf8", flag: "wx", mode: 0o600 });
+    return true;
+  } catch {
+    return false;
   }
-  return {};
 }
 
-function renderDynamicRules(cwd: string): string {
+function renderDynamicRules(cwd: string): string | null {
   const runtime = readRuntime(cwd);
+  if (runtime === null) return null;
   const thinkLang: string = runtime?.locale?.thinkingLanguage || "";
   const respondLang: string = runtime?.locale?.responseLanguage || "";
   const effectThink = thinkLang || (respondLang ? "en" : "");
@@ -77,34 +96,6 @@ function renderDynamicRules(cwd: string): string {
     "- **DO NOT** create markdown files outside of those directories unless explicitly asked.",
   );
   lines.push(`- docs.maxLoc: ${maxLoc} lines max per doc file`);
-  lines.push("- Follow **YAGNI · KISS · DRY** principles");
-  lines.push(
-    "- Sacrifice grammar for concision in reports. List unresolved Qs at end.",
-  );
-  lines.push("- Ensure token efficiency while maintaining high quality.");
-  lines.push("");
-
-  lines.push("### Skill Routing");
-  lines.push(
-    "- Choose skills from intent using `.opencode/rules/skill-workflow-routing.md` and `.opencode/rules/skill-domain-routing.md`.",
-  );
-  lines.push(
-    "- Use the OpenCode slash commands installed under `.opencode/commands/` (no `hapo:` prefix).",
-  );
-  lines.push(
-    "- Explicit user commands and direct-answer requests override routing suggestions.",
-  );
-  lines.push("");
-
-  lines.push("### Modularization");
-  lines.push("- If a file exceeds 200 lines, consider splitting it");
-  lines.push("- Check existing modules before creating new ones");
-  lines.push(
-    "- Prefer kebab-case (JS/TS/Python/shell); PascalCase (C#/Java); snake_case (Go/Rust)",
-  );
-  lines.push(
-    "- Skip modularization for: markdown, plain text, bash scripts, config files, .env files",
-  );
   lines.push("");
   lines.push(RULES_BLOCK_END);
 
@@ -145,16 +136,17 @@ function upsertBlock(filePath: string, block: string): boolean {
 export const RulesPlugin: Plugin = async ({ directory }) => {
   const cwd = resolveProjectDir(directory);
 
-  const refresh = () => {
+  const refresh = (sessionId?: string) => {
+    if (!reserveSession(cwd, sessionId)) return;
     const agentsFile = join(cwd, "AGENTS.md");
     const block = renderDynamicRules(cwd);
-    upsertBlock(agentsFile, block);
+    if (block) upsertBlock(agentsFile, block);
   };
 
   return {
     event: async ({ event }) => {
       if (event.type === "session.created") {
-        refresh();
+        refresh(event.properties?.info?.id);
       }
     },
   };

package/src/opencode/plugins/spec-gate.ts

@@ -0,0 +1,283 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * OpenCode Plugin — spec-gate.ts
+ *
+ * Advisory port of .claude/hooks/spec-gate.cjs and .codex/hooks/spec-gate.cjs.
+ *
+ * OpenCode has no Stop-hook equivalent that can hard-block a turn end.
+ * This plugin provides a best-effort advisory gate:
+ * - On tool.execute.after for writes to specs/<feature>/spec.json or task markdown, re-validate
+ *   any newly-done task receipts (Verification: PASS, Command, Exit, provenance, completed_at).
+ * - On session.idle (≈ Claude Stop), run the same check and surface a banner + stderr warning.
+ *
+ * It never throws to break the turn (fail-open). Disable via `.opencode/runtime.json`
+ * `{ "spec": { "completion_gate": false } }`. Missing key keeps the advisory gate ON.
+ * This is tier-2 compared to Claude/Codex hard gates — docs must not claim parity.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  appendFileSync,
+  readdirSync,
+} from "node:fs";
+import { join, dirname, relative, resolve, sep, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+const SPEC_GATE_BANNER_START = "<!-- CAFEKIT SPEC-GATE START -->";
+const SPEC_GATE_BANNER_END = "<!-- CAFEKIT SPEC-GATE END -->";
+
+type TaskEntry = {
+  status?: string;
+  completed_at?: string;
+  receipt?: string;
+};
+
+type SpecJson = {
+  status?: string;
+  current_phase?: string;
+  phase?: string;
+  task_registry?: Record<string, TaskEntry>;
+};
+
+const EVIDENCE_NAMES = ["Evidence", "Task Test Plan & Verification Evidence", "Verification & Evidence"];
+const PASS_MARKER = /^\s*Verification:\s*PASS\s*$/m;
+const LEGACY_SUCCESS = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
+const EXPLICIT_FAILURE = /\bFAIL(?:ED|URE|URES|ING)?\b|tests?\s+failed|exit\s+code\s*[:=]?\s*[1-9]\d*|\b0\s+tests?\b/i;
+
+function readRuntime(cwd: string): Record<string, any> {
+  try {
+    const file = join(cwd, ".opencode", "runtime.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+function evidenceBody(text: string): string | null {
+  const lines = text.split("\n");
+  let start = -1;
+  let level = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{2,3})\s+(.+?)\s*$/);
+    if (m && EVIDENCE_NAMES.includes(m[2])) {
+      start = i + 1;
+      level = m[1].length;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let i = start; i < lines.length; i++) {
+    const hm = lines[i].match(/^(#{1,6})\s+/);
+    if (hm && hm[1].length <= level) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+function validateCanonicalReceipt(body: string): string[] {
+  const fails: string[] = [];
+  if (!/^\s*Verification:\s*PASS\s*$/m.test(body)) fails.push("verification_state");
+  if (!/^\s*Command(?:\(s\))?\s*:/m.test(body)) fails.push("command");
+  if (!/^\s*Exit\s*:|exit\s+code\s*[:=]|\bResult\s*:\s*PASS\b/im.test(body)) fails.push("exit_result");
+  const hasBase = /^\s*Base\s*:[ \t]*\S/im.test(body);
+  const hasHead = /^\s*Head\s*:[ \t]*\S/im.test(body);
+  const hasBaseSha = /\bbase_sha\s*:[ \t]*\S/im.test(body);
+  const hasHeadSha = /\bhead_sha\s*:[ \t]*\S/im.test(body);
+  if (!((hasBase && hasHead) || (hasBaseSha && hasHeadSha))) fails.push("provenance");
+  if (/\bartifact\b/i.test(body) && !/sha256:/i.test(body)) fails.push("artifact_hash");
+  return fails;
+}
+
+function checkReceipt(featureDir: string, taskPath: string, task: TaskEntry): string[] {
+  const fails: string[] = [];
+  const abs = resolve(join(featureDir, taskPath));
+  const resolvedFeatureDir = resolve(featureDir);
+  const rel = relative(resolvedFeatureDir, abs);
+  // prevent path traversal: taskPath must stay inside featureDir (cross-platform sibling-prefix safe)
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return ["a"];
+  if (!existsSync(abs)) return ["a"];
+  let text: string;
+  try {
+    text = readFileSync(abs, "utf8");
+  } catch {
+    return ["a"];
+  }
+  const statusLine = text.split("\n").find((l) => /^\s*(?:\*\*)?Status(?:\*\*)?\s*:/i.test(l));
+  if (!statusLine || !/\bdone\b/i.test(statusLine)) fails.push("a");
+  const body = evidenceBody(text);
+  if (body === null) {
+    fails.push("b");
+  } else if (/\{\{[^}]+\}\}/.test(body) || EXPLICIT_FAILURE.test(body) || !(PASS_MARKER.test(body) || LEGACY_SUCCESS.test(body))) {
+    fails.push("c");
+  } else {
+    const canonical = validateCanonicalReceipt(body);
+    const map: Record<string, string> = { verification_state: "c", command: "e", exit_result: "f", provenance: "g", artifact_hash: "h" };
+    for (const f of canonical) {
+      if (f === "verification_state") {
+        if (!PASS_MARKER.test(body) && !fails.includes("c")) fails.push("c");
+        continue;
+      }
+      const letter = map[f];
+      if (letter && !fails.includes(letter)) fails.push(letter);
+    }
+    if (!PASS_MARKER.test(body) && !fails.includes("c")) fails.push("c");
+  }
+  const at = task?.completed_at;
+  if (typeof at !== "string" || !/^\d{4}-\d{2}-\d{2}T/.test(at) || Number.isNaN(Date.parse(at))) fails.push("d");
+  return fails;
+}
+
+function findActiveSpec(specsPath: string): { featureName: string; spec: SpecJson; specsDir: string; featureDir: string } | null {
+  if (!existsSync(specsPath)) return null;
+  let entries;
+  try {
+    entries = readdirSync(specsPath, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const specFile = join(specsPath, entry.name, "spec.json");
+    if (!existsSync(specFile)) continue;
+    try {
+      const data = JSON.parse(readFileSync(specFile, "utf8")) as SpecJson;
+      if (data.status === "in_progress" || data.status === "in-progress") {
+        return { featureName: entry.name, spec: data, specsDir: specsPath, featureDir: join(specsPath, entry.name) };
+      }
+    } catch {
+      // skip bad json
+    }
+  }
+  return null;
+}
+
+function isStaleFlashDone(task: TaskEntry): boolean {
+  return task?.status === "done" && task.receipt === "FLASH_UNVERIFIED";
+}
+
+function collectFailures(cwd: string): { featureName: string; failures: { taskPath: string; fails: string[] }[] } | null {
+  const runtime = readRuntime(cwd);
+  if (runtime.spec && runtime.spec.completion_gate === false) return null;
+  const specsPath = join(cwd, runtime.paths?.specs || "specs");
+  const active = findActiveSpec(specsPath);
+  if (!active) return null;
+  const registry = active.spec.task_registry || {};
+  const staleFlash = Object.entries(registry).filter(([, t]) => isStaleFlashDone(t as TaskEntry));
+  if (staleFlash.length > 0) {
+    return {
+      featureName: active.featureName,
+      failures: staleFlash.map(([p]) => ({ taskPath: p, fails: ["flash"] })),
+    };
+  }
+  // Check every done task (advisory — we have no cache to know newly-done, so check all)
+  const failures: { taskPath: string; fails: string[] }[] = [];
+  for (const [taskPath, task] of Object.entries(registry)) {
+    if ((task as TaskEntry)?.status !== "done") continue;
+    const fails = checkReceipt(active.featureDir, taskPath, task as TaskEntry);
+    if (fails.length > 0) failures.push({ taskPath, fails });
+  }
+  if (failures.length === 0) return null;
+  return { featureName: active.featureName, failures };
+}
+
+function formatReason(featureName: string, failures: { taskPath: string; fails: string[] }[]): string {
+  const flashOnly = failures.length === 1 && failures[0].fails.includes("flash");
+  if (flashOnly) {
+    return `Completion gate (advisory): 1 task(s) marked done with FLASH_UNVERIFIED (${failures[0].taskPath}). Run /hapo:test for exact proof, then use explicit sync-finalize.`;
+  }
+  const lines = [`⚠️ Completion gate (advisory): ${failures.length} done task(s) lack a verification receipt.`];
+  for (const { taskPath, fails } of failures) {
+    if (fails.includes("flash")) {
+      lines.push(`- \`${taskPath}\`: FLASH_UNVERIFIED`);
+    } else {
+      lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(", ")}`);
+    }
+  }
+  return lines.slice(0, 8).join("\n");
+}
+
+function writeBanner(cwd: string, reason: string | null): void {
+  try {
+    const file = join(cwd, ".opencode", "session-banner.md");
+    const dir = dirname(file);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    let existing = "";
+    try {
+      existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+    } catch {
+      existing = "";
+    }
+    const pattern = new RegExp(`${SPEC_GATE_BANNER_START}[\\s\\S]*?${SPEC_GATE_BANNER_END}\\n?`);
+    const cleaned = existing.replace(pattern, "").trimEnd();
+    if (!reason) {
+      if (cleaned !== existing.trimEnd()) writeFileSync(file, cleaned ? `${cleaned}\n` : "");
+      return;
+    }
+    const block = [SPEC_GATE_BANNER_START, reason, SPEC_GATE_BANNER_END].join("\n");
+    const next = cleaned ? `${cleaned}\n\n${block}\n` : `${block}\n`;
+    writeFileSync(file, next);
+  } catch {
+    // fail-open
+  }
+}
+
+function logCrash(error: unknown): void {
+  try {
+    const logDir = join(PLUGIN_DIR, ".logs");
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    appendFileSync(
+      join(logDir, "hook-log.jsonl"),
+      JSON.stringify({ ts: new Date().toISOString(), hook: "spec-gate", status: "crash", error: error instanceof Error ? error.message : String(error) }) + "\n",
+    );
+  } catch {
+    // fail-open
+  }
+}
+
+const RELEVANT_TOOLS = new Set(["edit", "write", "apply_patch", "task", "taskcreate", "taskupdate", "todowrite"]);
+
+export const SpecGate: Plugin = async ({ directory }) => ({
+  event: async ({ event }) => {
+    try {
+      if (event.type === "session.idle") {
+        const result = collectFailures(directory);
+        if (result) {
+          const reason = formatReason(result.featureName, result.failures);
+          writeBanner(directory, reason);
+          console.error(reason);
+        } else {
+          writeBanner(directory, null);
+        }
+      }
+    } catch (error) {
+      logCrash(error);
+    }
+  },
+  "tool.execute.after": async (input) => {
+    try {
+      if (!RELEVANT_TOOLS.has(input.tool)) return;
+      const result = collectFailures(directory);
+      if (result) {
+        const reason = formatReason(result.featureName, result.failures);
+        writeBanner(directory, reason);
+        console.error(`[spec-gate advisory] ${reason}`);
+      } else {
+        // clear banner if no failures after a relevant tool
+        // (keep banner if failures still exist from other tasks — collectFailures already handles)
+      }
+    } catch (error) {
+      logCrash(error);
+    }
+  },
+});
+
+export default SpecGate;