@haposoft/cafekit 0.15.1 → 0.16.0-rc.1

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;

package/src/claude/skills/inspect/references/external-gemini-inspection.md

@@ -1,169 +0,0 @@
-# External Discovery with Gemini
-
-Use external Gemini CLI for faster searches with large context windows (1M+ tokens) when SCALE ≤ 5.
-
-## Tool Selection
-
-```
-SCALE ≤ 5   → gemini CLI
-SCALE ≥ 6   → Use internal discovery instead
-```
-
-## Configuration
-
-Read from `.claude/runtime.json`:
-```json
-{
-  "gemini": {
-    "model": "gemma-4-31b-it"
-  }
-}
-```
-
-Default model: `gemma-4-31b-it`
-
-**Note:** This file is automatically installed when you run `npx @haposoft/cafekit`.
-
-## When External Mode is Allowed
-
-External Gemini inspection requires:
-
-**Gemini-Specific Requirements:**
-1. The prompt explicitly includes `ext` argument
-2. SCALE ≤ 5 (calculated from estimated file count)
-
-**General Preflight Gate (applies to all modes):**
-3. At least one concrete directory scope is present
-4. The request is not a repo-root or root-wide scan
-5. The built-in no-scan guidance has been applied
-
-If any condition fails, use internal discovery instead.
-
-## Gemini CLI
-
-### Command
-```bash
-gemini -y -m <model> "[prompt]"
-```
-
-### Example
-```bash
-gemini -y -m gemma-4-31b-it "Search src/ for authentication files. List paths with brief descriptions."
-```
-
-## Installation Check
-
-Before using, verify Gemini CLI is installed:
-```bash
-which gemini
-```
-
-If not installed, ask user:
-1. **Yes** - Provide installation instructions (may need manual auth steps)
-2. **No** - Fall back to internal discovery (`internal-inspection.md`)
-
-## Running Parallel Gemini Commands
-
-Use the `Bash` tool for each scoped Gemini command. Run them in the same tool turn when the runtime supports parallel tool calls; otherwise run them sequentially. Do not use `Agent` with `subagent_type: "Bash"` — `Bash` is a tool, not a subagent.
-
-```
-Bash: gemini -y -m gemma-4-31b-it '[prompt1]'
-Bash: gemini -y -m gemma-4-31b-it '[prompt2]'
-Bash: gemini -y -m gemma-4-31b-it '[prompt3]'
-```
-
-Group by independent scopes so each command can return a focused report.
-
-## Prompt Guidelines
-
-- Be specific about directories to search
-- Request file paths with descriptions
-- Set clear scope boundaries
-- Ask for patterns/relationships if relevant
-- Do not include no-scan paths
-- Do not request secret material or generated bundles
-
-## Prompt Template
-
-```text
-Inspect these scoped directories only:
-- {dir-1}
-- {dir-2}
-
-Goal:
-- {what to find}
-
-Return:
-1. relevant file paths
-2. one-line description per file
-3. notable patterns or relationships
-4. unresolved questions
-
-Do not inspect repo root, generated directories, or sensitive content.
-Do not expand beyond the provided scope.
-```
-
-## Example Workflow
-
-User: "Find database migration files" with `ext`
-
-Run 3 scoped Gemini CLI commands:
-```
-Bash: gemini -y -m gemma-4-31b-it 'Search db/, migrations/ for migration files'
-Bash: gemini -y -m gemma-4-31b-it 'Search lib/, src/ for database schema files'
-Bash: gemini -y -m gemma-4-31b-it 'Search config/ for database configuration'
-```
-
-## Reading File Content
-
-When needing to read file content, use chunking to stay within context limits (<150K tokens safe zone).
-
-### Step 1: Get Line Counts
-Use Read tool to check file size before reading.
-
-### Step 2: Calculate Chunks
-- **Target:** ~500 lines per chunk (safe for most files)
-- **Max files per agent:** 3-5 small files OR 1 large file chunked
-
-**Chunking formula:**
-```
-chunks = ceil(total_lines / 500)
-lines_per_chunk = ceil(total_lines / chunks)
-```
-
-### Step 3: Read Strategy
-
-**Small files (<500 lines each):**
-- Read entire file with Read tool
-
-**Large file (>500 lines):**
-- Use Read tool with offset/limit parameters
-- Read in 500-line chunks
-
-### Chunking Decision Tree
-```
-File < 500 lines     → Read entire file
-File 500-1500 lines  → Split into 2-3 chunks
-File > 1500 lines    → Split into ceil(lines/500) chunks
-```
-
-## Timeout and Error Handling
-
-- Set 3-minute timeout per bash call
-- Skip timed-out agents
-- Don't restart failed agents
-- On persistent failures, fall back to internal discovery
-
-## Fallback Behavior
-
-If Gemini is unavailable, misconfigured, or errors out:
-1. Stop external mode
-2. Continue with internal discovery
-3. Note the fallback in the final report
-
-## Expected Outcome
-
-- Scoped Gemini discovery
-- Concise file list with descriptions
-- Patterns and relationships
-- Fallback to internal mode if Gemini cannot run