@fusengine/harness 0.1.90 → 0.1.92

package/src/runtime/dry.ts

@@ -0,0 +1,96 @@
+import { execFileSync } from "node:child_process";
+import { extname, resolve, sep } from "node:path";
+import type { Prompt } from "../prompt/types";
+import { DRY_KEYWORDS as KEYWORDS, TS_EXT, TS_PATTERNS, PHP_PATTERNS, EXCLUDE_DIRS } from "./dry-patterns";
+
+/** Extract long (>12 char) declared symbol names from new file content. */
+export function extractSymbols(content: string, ext: string): string[] {
+  const pats = TS_EXT.has(ext) ? TS_PATTERNS : ext === ".php" ? PHP_PATTERNS : [];
+  const names = new Set<string>();
+  for (const re of pats) {
+    for (const m of content.matchAll(re)) {
+      const n = m[1];
+      if (n && !KEYWORDS.has(n) && n.length > 12) names.add(n);
+    }
+  }
+  return [...names];
+}
+
+/** `modules/X/...` -> `"X"`, else `""` (module-boundary key). */
+function moduleOf(path: string): string {
+  const parts = path.split(sep);
+  const i = parts.indexOf("modules");
+  return i >= 0 && i + 1 < parts.length ? (parts[i + 1] ?? "") : "";
+}
+
+/** Verdict from {@link detectDuplication}. */
+export interface DuplicationVerdict {
+  names: string[];
+  duplicates: string[];
+}
+
+/**
+ * Grep the codebase for existing declarations of the symbols a write introduces,
+ * honoring module boundaries (cross-`modules/` matches are ignored). Effectful:
+ * shells out to `grep`. Fails open (returns no duplicates) on any grep error,
+ * timeout, or no-match — matching the original Python hook.
+ */
+export function detectDuplication(filePath: string, content: string, cwd: string): DuplicationVerdict {
+  const ext = extname(filePath).toLowerCase();
+  if (!TS_EXT.has(ext) && ext !== ".php") return { names: [], duplicates: [] };
+  const names = extractSymbols(content, ext);
+  if (!names.length) return { names, duplicates: [] };
+  const include = TS_EXT.has(ext)
+    ? ["--include=*.ts", "--include=*.tsx", "--include=*.js", "--include=*.jsx"]
+    : ["--include=*.php"];
+  const decl = TS_EXT.has(ext) ? "(function|const|let|class|interface)\\s+" : "(function|class|interface|trait)\\s+";
+  const escaped = names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+  const pattern = `${decl}(${escaped})\\b`;
+  let out = "";
+  try {
+    const args = ["-rEl", ...EXCLUDE_DIRS.map((d) => `--exclude-dir=${d}`), ...include, "--", pattern, cwd];
+    out = execFileSync("grep", args, { encoding: "utf8", timeout: 1500 });
+  } catch {
+    return { names, duplicates: [] };
+  }
+  const self = resolve(filePath);
+  const targetMod = moduleOf(filePath);
+  const duplicates: string[] = [];
+  for (const line of out.split("\n")) {
+    const f = line.trim();
+    if (!f || resolve(f) === self) continue;
+    const dupMod = moduleOf(f);
+    if (targetMod && dupMod && dupMod !== targetMod) continue;
+    duplicates.push(f);
+  }
+  return { names, duplicates };
+}
+
+/**
+ * Prompt when a Write/Edit re-declares an existing symbol: a single match is a
+ * softer non-blocking "inform" (could be a false positive / same-name coincidence),
+ * escalating to a hard "block" once 2+ existing declarations are found. Returns
+ * `null` when no duplicate symbol is found at all.
+ */
+export function dryGate(tool: string, filePath: string, content: string | undefined, cwd: string | undefined): Prompt | null {
+  if (!cwd || (tool !== "Write" && tool !== "Edit") || !content) return null;
+  const dup = detectDuplication(filePath, content, cwd);
+  if (dup.duplicates.length === 0) return null;
+  const names = dup.names.slice(0, 5).join(", ");
+  let files = dup.duplicates.slice(0, 3).join(", ");
+  if (dup.duplicates.length > 3) files += ` (+${dup.duplicates.length - 3} more)`;
+  if (dup.duplicates.length === 1) {
+    return {
+      kind: "inform",
+      title: "Possible duplicate code (DRY)",
+      reason: `[${names}] already declared in: ${files}. Consider importing and reusing instead of re-declaring.`,
+      actions: ["Import the existing symbol instead of re-declaring it", "Extend the existing module"],
+    };
+  }
+  return {
+    kind: "block",
+    title: "Duplicate code (DRY)",
+    reason: `[${names}] already declared in: ${files}. Import and reuse instead of re-declaring.`,
+    actions: ["Import the existing symbol instead of re-declaring it", "Extend the existing module"],
+  };
+}

package/src/runtime/fragment-registry.ts

@@ -0,0 +1,33 @@
+/**
+ * @module fragment-registry
+ * Per-process registry of injected fragment sizes, populated by
+ * {@link module:inject-budget.capFragment} as a side effect and consumed by
+ * {@link module:inject-budget-recap} to build ONE event-level recap instead
+ * of the scattered per-injection-point reports (each caller of `capFragment`
+ * only ever saw its OWN fragment, never the total for the whole event).
+ *
+ * Module-level state is safe here: each hook invocation is a fresh short-lived
+ * CLI process (one per Claude Code hook event), so there is no cross-event
+ * leakage in production. {@link resetFragmentRegistry} exists so a single
+ * process handling several events in sequence (unit tests; any future
+ * long-lived host) can still isolate one event's fragments from the next.
+ * @packageDocumentation
+ */
+import type { FragmentSize } from "./inject-budget";
+
+let registry: FragmentSize[] = [];
+
+/** Clear the registry. Call once before dispatching a hook event. */
+export function resetFragmentRegistry(): void {
+  registry = [];
+}
+
+/** Record one fragment's post-cap size. Called by {@link module:inject-budget.capFragment}. */
+export function recordFragment(label: string, chars: number): void {
+  registry.push({ label, chars });
+}
+
+/** Snapshot of every fragment recorded since the last {@link resetFragmentRegistry}. */
+export function fragmentRegistry(): FragmentSize[] {
+  return [...registry];
+}

package/src/runtime/framework-skill-gate.ts

@@ -0,0 +1,79 @@
+import { frameworkSolidGate } from "../policy/framework-solid";
+import { skillTriggerGate } from "../policy/skill-triggers";
+import { requiredArchSkill } from "../policy/detect-project";
+import { countFrameworkCodeLines } from "../policy/file-size";
+import { isExcludedJsPath, isExcludedSwiftPath } from "../policy/framework-solid-exclude";
+import type { GateInput } from "./gate-input";
+import type { Prompt } from "../prompt/types";
+
+/** PHP paths the Laravel skill check skips — broader than the SOLID vendor-only exclude (parity check-laravel-skill.py `/(vendor|storage|bootstrap/cache)/`). */
+const PHP_SKILL_EXCLUDE_RE: RegExp = /\/(vendor|storage|bootstrap\/cache)\//;
+
+/**
+ * Whether the sub-skill gate should skip this path — parity with the early return
+ * in check-*-skill.py (build/vendor artifacts never require a sub-skill).
+ * @param framework - the detected framework ("laravel" | "swift" | JS otherwise).
+ * @param filePath - the file being written.
+ */
+function skillGateExcluded(framework: string, filePath: string): boolean {
+  if (framework === "laravel") return PHP_SKILL_EXCLUDE_RE.test(filePath);
+  if (framework === "swift") return isExcludedSwiftPath(filePath);
+  return isExcludedJsPath(filePath);
+}
+
+/**
+ * Effective line count for the SOLID size check. On an Edit, `content` is only
+ * the `new_string` snippet, so for Next.js — mirroring the base file-size guard
+ * and the Python `get_full_file_content` — judge the larger of the snippet and
+ * the full on-disk file (`existingCodeLines`). Other frameworks (react/laravel/
+ * swift) judge the edited snippet alone, never the on-disk full-file max — their
+ * Python source never imports `get_full_file_content`, only nextjs does. On
+ * Write, `content` IS the full file, so the snippet count stands regardless of
+ * framework (undefined → the gate falls back to `countFrameworkCodeLines`).
+ * @param tool - the tool name ("Edit" | "Write" | ...).
+ * @param framework - the detected framework; only "nextjs" applies the full-file max.
+ * @param content - the written content (snippet on Edit, full file on Write).
+ * @param existingCodeLines - full on-disk code-only line count, when known.
+ */
+function effectiveLines(
+  tool: string,
+  framework: string,
+  content: string,
+  existingCodeLines?: number,
+): number | undefined {
+  if (tool !== "Edit" || existingCodeLines === undefined) return undefined;
+  if (framework !== "nextjs") return countFrameworkCodeLines(content);
+  return Math.max(countFrameworkCodeLines(content), existingCodeLines);
+}
+
+/**
+ * Framework-aware SOLID + sub-skill gate, run on the Write/Edit path once a
+ * `filePath` is present. Combines:
+ *  - {@link frameworkSolidGate}: framework-specific SOLID rules (line limits,
+ *    interface/protocol separation, `'use client'`, @MainActor...).
+ *  - {@link skillTriggerGate}: blocks when written APIs need a sub-skill that
+ *    was not read this session, also forcing the modular-architecture skill
+ *    resolved from disk via {@link requiredArchSkill}.
+ *
+ * @param input - the gated tool-use (filePath + content + framework + cwd).
+ * @param refsRead - in-session read reference paths (from the loaded track).
+ * @param existingCodeLines - full on-disk code-only line count (so an Edit on
+ *   an oversized file still fires the framework SOLID size rule). Omit on Write.
+ * @returns the first blocking {@link Prompt}, or `null` to allow.
+ */
+export function frameworkSkillGate(
+  input: GateInput,
+  refsRead: string[],
+  existingCodeLines?: number,
+): Prompt | null {
+  if (!input.filePath) return null;
+  const content = input.content ?? "";
+  const solid = frameworkSolidGate(input.filePath, content, effectiveLines(input.tool, input.framework, content, existingCodeLines));
+  if (solid) return solid;
+  // Skill-gate path exclusions (parity check-*-skill.py early return): a build/
+  // vendor artifact never triggers the sub-skill requirement. Applied only to the
+  // skill check, not frameworkSolidGate (whose PHP exclude is vendor-only).
+  if (skillGateExcluded(input.framework, input.filePath)) return null;
+  const forced = input.cwd ? requiredArchSkill(input.cwd) : null;
+  return skillTriggerGate(input.framework, content, refsRead, forced, input.cwd, input.filePath);
+}

package/src/runtime/fs-cleanup.ts

@@ -0,0 +1,71 @@
+import { existsSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/** Age of a file in seconds (now - mtime). Infinity when unstat-able. */
+function ageSec(path: string, now: number): number {
+  try {
+    return (now - statSync(path).mtimeMs) / 1000;
+  } catch {
+    return Infinity;
+  }
+}
+
+/** Remove files directly under `dir` matching `test` older than `maxAgeSec`. */
+export function removeOldFiles(dir: string, test: (name: string) => boolean, maxAgeSec: number, now: number = Date.now()): void {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (test(name) && ageSec(path, now) > maxAgeSec) {
+      try { rmSync(path, { force: true }); } catch { /* best effort */ }
+    }
+  }
+}
+
+/** Trim `file` to its last `keepLines` lines when it exceeds `maxBytes`. */
+export function trimLogFile(file: string, maxBytes: number, keepLines: number): void {
+  try {
+    if (!existsSync(file) || statSync(file).size <= maxBytes) return;
+    const lines = readFileSync(file, "utf-8").split("\n");
+    writeFileSync(file, lines.slice(-keepLines).join("\n"), "utf-8");
+  } catch { /* best effort */ }
+}
+
+/** Recursively purge files under `root/<top>` older than `ttls[top]` seconds. */
+export function purgeTtlTree(root: string, ttls: Record<string, number>, now: number = Date.now()): void {
+  if (!existsSync(root)) return;
+  for (const [top, ttlSec] of Object.entries(ttls)) {
+    walkPurge(join(root, top), ttlSec, now);
+  }
+}
+
+function walkPurge(dir: string, ttlSec: number, now: number): void {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    let isDir = false;
+    try { isDir = statSync(path).isDirectory(); } catch { continue; }
+    if (isDir) { walkPurge(path, ttlSec, now); continue; }
+    if (ageSec(path, now) > ttlSec) {
+      try { rmSync(path, { force: true }); } catch { /* best effort */ }
+    }
+  }
+}
+
+/** Bottom-up removal of empty subdirs under each `root/<top>` (best effort). */
+export function pruneEmptyDirs(root: string, tops: string[]): void {
+  for (const top of tops) {
+    const sub = join(root, top);
+    if (!existsSync(sub)) continue;
+    pruneEmpty(sub, sub);
+  }
+}
+
+function pruneEmpty(dir: string, stopAt: string): void {
+  for (const name of existsSync(dir) ? readdirSync(dir) : []) {
+    const path = join(dir, name);
+    try { if (statSync(path).isDirectory()) pruneEmpty(path, stopAt); } catch { /* skip */ }
+  }
+  if (dir !== stopAt && relative(stopAt, dir).split(sep)[0] !== "..") {
+    try { rmdirSync(dir); } catch { /* non-empty or gone */ }
+  }
+}

package/src/runtime/gate-apex.ts

@@ -0,0 +1,81 @@
+import { evaluateApex, PRE_AUTH_GATES, POST_AUTH_GATES, type ApexContext } from "../policy/apex";
+import { apexAuthorizationGate } from "../policy/apex-authorization";
+import { isTrivialEdit, protectedPathGate, SKIP_DIRS } from "../policy/trivial-edits";
+import { FAIL_CLOSED } from "../policy/guards";
+import { agentsFresh, recordTarget, recordTrivialEdit, trivialCount, type SessionTrack } from "../tracking/session-state";
+import { agentsRanFromTranscript } from "../freshness/agent-evidence";
+import { agentsFreshInTrack } from "../freshness/agent-evidence-record";
+import { withTrack } from "../tracking/store";
+import { REQUIRED_AGENTS, TRIVIAL_BUDGET } from "./gate";
+import type { GateInput } from "./gate-input";
+import type { Prompt } from "../prompt/types";
+
+/**
+ * The APEX-scoped portion of {@link gate}, in the Python enforce-apex-phases.ts
+ * order: protected-paths guard, skip-dirs allow, trivial-edit fast path, then
+ * brainstorm/freshness, Check 1 (per-framework doc authorization — a deny
+ * persists `track.target` so recordDoc can cross-credit the framework) and
+ * Check 2 + SOLID refs. Freshness scans the SESSION track first (parity
+ * _scan_agents: sub-agent hooks share the lead's session_id, so sidechain/
+ * Workflow research is visible); the platform-authored transcript scan and the
+ * legacy exact-name track check are fallbacks.
+ * @param input - The tool-use to gate.
+ * @param track - The loaded session track.
+ * @param window - Freshness window in ms.
+ * @returns The first blocking prompt, or null to fall through to the DRY check.
+ */
+export async function apexScopedGate(input: GateInput, track: SessionTrack, window: number): Promise<Prompt | null> {
+  // (1) Hook-managed paths: absolute deny BEFORE any other filter (parity :49-52).
+  const protectedDeny = protectedPathGate(input.tool, input.filePath);
+  if (protectedDeny) return protectedDeny;
+  // (2) CODE_EXT runs upstream (gate.ts isApexScoped); dependency/build dirs skip (parity :53-54).
+  if (SKIP_DIRS.test(input.filePath ?? "")) return null;
+
+  // (3) Trivial-edit fast path: a few tiny, non-replace Edits skip the APEX gates
+  // (parity :58-65 — only Edit ever qualifies as "trivial"; a Write always
+  // creates/replaces a file wholesale and must go through the full gate).
+  if (isTrivialEdit(input.tool, input.content, input.isReplaceAll) && trivialCount(track, window, input.now) < TRIVIAL_BUDGET) {
+    await withTrack(input.trackFile, (fresh) => recordTrivialEdit(fresh, input.now, window, input.now));
+    return null;
+  }
+
+  const freshnessFor = (names: string[], windowMs: number = window): boolean =>
+    agentsFreshInTrack(track, names, windowMs, input.now) ||
+    (input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, windowMs, input.now) : agentsFresh(track, names, windowMs, input.now));
+
+  const ctx: ApexContext = {
+    sessionId: input.sessionId,
+    framework: input.framework,
+    filePath: input.filePath ?? "",
+    content: input.content ?? "",
+    authorizations: track.authorizations,
+    refs: input.refs,
+    refsRead: track.refsRead,
+    refsReadAt: track.refsReadAt, // SOLID-read TTL stamps (absent → no expiry)
+    now: input.now,
+    agentsFresh: freshnessFor([...REQUIRED_AGENTS]),
+    missingAgents: REQUIRED_AGENTS.filter((name) => !freshnessFor([name])),
+    windowMs: window,
+    // Parity require-apex-agents.py:41 — Edit never creates a file (skip brainstorm),
+    // and a subagent (agent_id present) inherits the lead's brainstorm decision, so
+    // only a lead Write is ever brainstorm-gated.
+    brainstormRequired: input.tool === "Edit" || input.agentId ? false : track.brainstormRequired,
+    brainstormFresh: freshnessFor(["brainstorming"], Number.MAX_SAFE_INTEGER),
+  };
+  try {
+    // (4) Brainstorm + explore/research freshness (pre-existing harness gates).
+    const pre = evaluateApex(ctx, PRE_AUTH_GATES);
+    if (pre) return pre;
+    // (5) Check 1 — a deny persists `target` (parity :80-81) for recordDoc's cross-credit.
+    const authDeny = apexAuthorizationGate(ctx);
+    if (authDeny) {
+      const set_at = new Date(input.now).toISOString();
+      await withTrack(input.trackFile, (fresh) => recordTarget(fresh, { project: input.cwd ?? "", framework: input.framework, set_by: "apex-authorization", set_at }));
+      return authDeny;
+    }
+    // (6) Check 2 (doc consulted once per session) + SOLID refs.
+    return evaluateApex(ctx, POST_AUTH_GATES);
+  } catch {
+    return FAIL_CLOSED;
+  }
+}

package/src/runtime/gate-helpers.ts

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from "node:fs";
+import { countFrameworkCodeLines, countLines } from "../policy/file-size";
+
+/** Source extensions the APEX gates apply to (parity: require-apex-agents.py CODE_EXT). */
+const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|dart|vue|svelte|astro)$/;
+
+/** Paths exempt from the APEX gates even when they are code (parity: require-apex-agents.py EXEMPT_PATTERNS). */
+const EXEMPT_PATTERNS: readonly RegExp[] = [
+  /\.claude-plugin\//,
+  /CHANGELOG\.md$/,
+  /marketplace\.json$/,
+  /\/\.(claude|codex)\/(apex|memory|logs|fusengine-cache)\//,
+  /\/\.fuse-harness\//,
+];
+
+/**
+ * True when `filePath` is a code file the APEX freshness/doc/SOLID gates should
+ * police — i.e. it matches a tracked source extension AND no exempt pattern.
+ * Mirrors require-apex-agents.py so non-code (and exempt) paths skip those gates.
+ * @param filePath - Absolute path of the edit target (or undefined).
+ * @returns Whether the APEX gates apply to this path.
+ */
+export function isApexScoped(filePath: string | undefined): boolean {
+  if (!filePath || !CODE_EXT.test(filePath)) return false;
+  return !EXEMPT_PATTERNS.some((p) => p.test(filePath));
+}
+
+/** Raw + code-only line counts of the existing on-disk file. */
+export interface ExistingLineCounts {
+  /** Raw physical count — parity with core-guards `enforce-file-size.py` (`sum(1 for _ in f)`), fed to the generic `evaluate()` ceiling. */
+  raw?: number;
+  /** Code-only count (blank/comment lines excluded) — parity with the framework validators' `count_code_lines`, fed to `frameworkSkillGate`. */
+  code?: number;
+  /** Full on-disk content, read once alongside the counts — fed to the Edit-outcome file-size gate (policy/edit-outcome.ts via evaluate.ts) so it can compute the exact post-edit line count without a second read. */
+  content?: string;
+}
+
+/**
+ * Read `path` once and derive both line-count metrics, so the generic
+ * core-guards ceiling (`raw`) and the framework SOLID gates (`code`) each get
+ * the metric their own Python origin measures, without reading the file twice.
+ * @param path - Absolute path of the file being edited (or undefined).
+ */
+export function existingLineCounts(path: string | undefined): ExistingLineCounts {
+  if (!path || !existsSync(path)) return {};
+  try {
+    const content = readFileSync(path, "utf8");
+    return { raw: countLines(content), code: countFrameworkCodeLines(content), content };
+  } catch {
+    return {};
+  }
+}

package/src/runtime/gate-input.ts

@@ -0,0 +1,26 @@
+import type { RefMeta } from "../refs/types";
+
+/** A tool-use to gate, plus the session pointers needed for the stateful gates. */
+export interface GateInput {
+  sessionId: string;
+  framework: string;
+  tool: string;
+  filePath?: string;
+  content?: string;
+  command?: string;
+  cwd?: string;
+  refs?: RefMeta[];
+  now: number;
+  trackFile: string;
+  windowMs?: number;
+  isReplaceAll?: boolean;
+  /** Edit only: the tool_input.old_string being replaced (runtime/normalize.ts) — threaded to evaluate()'s file-size gate so it can compute the post-edit outcome (policy/edit-outcome.ts) instead of judging the stale on-disk count alone. */
+  oldString?: string;
+  agentType?: string;
+  /** Claude `agent_id` when the tool-use comes from a subagent (parity require-apex-agents.py:41 — subagents inherit the lead's brainstorm decision). */
+  agentId?: string;
+  /** Absolute path to the session transcript (Claude `transcript_path`) for evidence-based freshness. */
+  transcriptPath?: string;
+  /** See PolicyContext.neverApproval — populated only by handle-pre.ts for id==="codex" (approval_policy=never has no interactive ask channel). */
+  neverApproval?: boolean;
+}

package/src/runtime/gate.ts

@@ -0,0 +1,128 @@
+import { evaluate, type PolicyResult } from "../policy/evaluate";
+import { protectedPathGate } from "../policy/trivial-edits";
+import { existingLineCounts, isApexScoped } from "./gate-helpers";
+import { FAIL_CLOSED } from "../policy/guards";
+import { loadTrack } from "../tracking/store";
+import { dryGate } from "./dry";
+import { preCommitGate } from "./precommit";
+import { modularGate } from "./modular";
+import { frameworkSkillGate } from "./framework-skill-gate";
+import { reconcileRefReadsFromTranscript } from "../freshness/ref-evidence";
+import { reconcileRefReadsFromJournal } from "../freshness/ref-journal";
+import { isShadcnWrite, shadcnSkillGate } from "../policy/shadcn-skill-gate";
+import { isTailwindWrite, tailwindSkillGate } from "../policy/tailwind-skill-gate";
+import { geminiMcpGate } from "../policy/gemini-mcp-gate";
+import { apexScopedGate } from "./gate-apex";
+import { withDenyLoop } from "./deny-loop-store";
+import { recordOneShot } from "../tracking/one-shot";
+import { dirname } from "node:path";
+import type { GateInput } from "./gate-input";
+import type { Prompt } from "../prompt/types";
+
+export type { GateInput } from "./gate-input";
+
+/** Prior agents the freshness gate requires before a code edit. */
+export const REQUIRED_AGENTS: ReadonlyArray<string> = ["explore-codebase", "research-expert"];
+
+/**
+ * Default freshness window (ms). Matches the plugin's `FUSE_ENFORCE_TTL_SEC`
+ * default (120s); only a fallback for callers that omit `windowMs` (e.g. tests) —
+ * the real CLI path always supplies it from `resolveTtlSec()` (`src/config/ttl.ts`).
+ */
+export const DEFAULT_WINDOW_MS = 120_000;
+
+/** Trivial edits allowed within the window before the full APEX gates apply. */
+export const TRIVIAL_BUDGET = 4;
+
+/**
+ * Full gate: {@link runGates} yields the first blocking prompt (or null); the tail
+ * records the one-shot metric ({@link recordOneShot}, observation-only) then lets
+ * {@link withDenyLoop} rewrite an identical retried deny (decision unchanged).
+ */
+export async function gate(input: GateInput): Promise<Prompt | null> {
+  const prompt = await runGates(input);
+  return finalizeGate(input, prompt, input.command);
+}
+
+/**
+ * Gate independent Cursor command candidates without merging their shell syntax.
+ * Stateful outcome bookkeeping runs once, against the command that decided the
+ * aggregate result. A single distinct candidate follows {@link gate} verbatim.
+ */
+export async function gateCommandCandidates(input: GateInput, candidates: readonly string[]): Promise<Prompt | null> {
+  const distinct = [...new Set(candidates)];
+  if (distinct.length <= 1) return gate(input);
+
+  let decisive: { prompt: Prompt; command: string } | undefined;
+  for (const command of distinct) {
+    const prompt = await runGates({ ...input, command });
+    if (!prompt) continue;
+    if (!decisive || promptRank(prompt) > promptRank(decisive.prompt)) decisive = { prompt, command };
+    if (prompt.kind === "block") break;
+  }
+  return finalizeGate(input, decisive?.prompt ?? null, decisive?.command ?? input.command);
+}
+
+/** Persist one final gate outcome and apply deny-loop enrichment exactly once. */
+function finalizeGate(input: GateInput, prompt: Prompt | null, command: string | undefined): Prompt | null {
+  const op = { filePath: input.filePath, content: input.content, command };
+  const dir = dirname(input.trackFile);
+  recordOneShot(prompt, op, { now: input.now, dir, sessionId: input.sessionId });
+  return withDenyLoop(prompt, input.tool, op, { now: input.now, dir, windowMs: input.windowMs ?? DEFAULT_WINDOW_MS, sessionId: input.sessionId });
+}
+
+/** Higher numeric values dominate while equal values preserve wire order. */
+function promptRank(prompt: Prompt): number {
+  return prompt.kind === "block" ? 3 : prompt.kind === "ask" ? 2 : 1;
+}
+
+/** Stateless guards, then the trivial fast path, then the stateful APEX gates. */
+async function runGates(input: GateInput): Promise<Prompt | null> {
+  // Pre-commit lint hard-block runs FIRST: evaluate()'s GIT_ASK branch would
+  // otherwise short-circuit a `git commit` before the linters get to veto it.
+  const precommit = preCommitGate(input.tool, input.command, input.cwd);
+  if (precommit) return precommit;
+  // Hook-managed paths: absolute deny on ALL extensions, BEFORE the code-ext/exempt filters (parity enforce-apex-phases.ts:48-52 — isApexScoped never routes a non-code/exempt path to the guard).
+  const protectedDeny = protectedPathGate(input.tool, input.filePath);
+  if (protectedDeny) return protectedDeny;
+  const { raw: existingLines, code: existingCodeLines, content: existingContent } = existingLineCounts(input.filePath);
+  let quick: PolicyResult;
+  try {
+    quick = evaluate({ tool: input.tool, filePath: input.filePath, content: input.content, command: input.command, agentType: input.agentType, existingLines, existingContent, oldString: input.oldString, isReplaceAll: input.isReplaceAll, neverApproval: input.neverApproval });
+  } catch {
+    return FAIL_CLOSED;
+  }
+  if (quick.decision !== "allow" && quick.prompt) return quick.prompt;
+  const modular = modularGate(input.tool, input.filePath, input.content, input.cwd);
+  if (modular) return modular;
+  if (!input.filePath) return null;
+  const filePath = input.filePath;
+  // Reconcile refsRead BEFORE any consumer from two durable, race-immune sources (racy load→save loses lone
+  // writes under the fan-out): the transcript restores the LEAD's flushed read, the append-only journal (ref-journal.ts) the TEAMMATE's un-flushed one (lag > TTL).
+  const track = reconcileRefReadsFromJournal(
+    reconcileRefReadsFromTranscript(await loadTrack(input.trackFile), input.transcriptPath, input.now),
+    dirname(input.trackFile), input.now,
+  );
+  const solidOrSkill = frameworkSkillGate(input, track.refsRead, existingCodeLines);
+  if (solidOrSkill) return solidOrSkill;
+  // Standalone shadcn/ui gate (ports check-skill-loaded.py): runs independently of `framework` since a components.json / .css write may detect as "generic", mirroring the real plugin's own PreToolUse hook alongside react's.
+  if (isShadcnWrite(input.tool, filePath)) {
+    const shadcnBlock = shadcnSkillGate(input.tool, filePath, input.content ?? "", { refsRead: track.refsRead, authorizations: track.authorizations, sessionId: input.sessionId });
+    if (shadcnBlock) return shadcnBlock;
+  }
+  // Standalone Tailwind base-skill gate (ports check-tailwind-skill.py Phase 1): a .tsx/.jsx write with Tailwind classes needs a base Tailwind skill read, independent of framework.
+  if (isTailwindWrite(input.tool, filePath, input.content ?? "")) {
+    const twBlock = tailwindSkillGate(input.tool, filePath, input.content ?? "", track.refsRead);
+    if (twBlock) return twBlock;
+  }
+  // OPT-IN Gemini Design MCP gate (ports enforce-gemini-mcp.py) — a no-op unless FUSE_ENFORCE_GEMINI_MCP is set, then blocks hand-written Tailwind UI until a mcp__gemini-design__* call is made this session.
+  const geminiBlock = geminiMcpGate(input.tool, filePath, input.content ?? "", { authorizations: track.authorizations, sessionId: input.sessionId });
+  if (geminiBlock) return geminiBlock;
+  // The freshness/doc/SOLID APEX gates only police code files (require-apex-agents.py parity): non-code and exempt paths skip straight to the DRY check below.
+  if (isApexScoped(input.filePath)) {
+    const apex = await apexScopedGate(input, track, input.windowMs ?? DEFAULT_WINDOW_MS);
+    if (apex) return apex;
+  }
+  // DRY duplication (effectful: greps the codebase) — runs once the APEX gates pass.
+  return dryGate(input.tool, input.filePath, input.content, input.cwd);
+}