@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/design.ts

@@ -0,0 +1,116 @@
+import type { Prompt } from "../prompt/types";
+import type { NormalizedEvent } from "./normalize";
+import { loadDesignState, saveDesignState, initDesignState } from "../policy/design/state";
+import { recordValidDesignSystem } from "../policy/design/transitions";
+import { activeDesignAgent } from "../policy/design/flag";
+import { runDesignChecks } from "../policy/design/content-checks";
+import { uiDesignSkillGate } from "../policy/design/skill-gate";
+import { collectDesignEvidence } from "../policy/design/skill-evidence";
+import { findDesignSystem, recordPost, designSystemContentGate } from "./design-helpers";
+import { checkDesignSystemContent } from "./design-content-gate";
+import { designFilesGate } from "./design-files-gate";
+import { resolveCorpusRoot, resolvePluginsRoot, pluginsWriteGuard } from "../policy/design/corpus";
+import {
+  htmlCssOnlyGate, stateFileGate, screenshotScrollGate,
+  geminiEnabled,
+} from "../policy/design/gates";
+import { designSystemWriteGate, geminiCreateGate, browserNavigateGate, htmlCssPipelineGate } from "../policy/design/gates-pipeline";
+
+const NAV = "mcp__fuse-browser__browser_navigate";
+const SHOT = "mcp__fuse-browser__browser_screenshot";
+const GEMINI = "mcp__gemini-design__create_frontend";
+
+/**
+ * Design-pipeline gate (effectful: reads/writes the design state + design-system.md).
+ * Returns a Prompt to block, or null when this isn't a design-agent context / nothing fires.
+ */
+export function designGate(payload: Record<string, unknown>, event: NormalizedEvent, cacheDir: string, cwd: string, corpusRootOverride?: string, pluginsRootOverride?: string): Prompt | null {
+  // UI design-skill gate (ports check-design-skill.py): fires for ANY agent on a
+  // UI write — requires a design-skill read + ANY doc source (Context7/Exa/web).
+  // Gemini is NEVER required. Runs before the design-agent pipeline state logic.
+  if (event.phase !== "post" && (event.tool === "Write" || event.tool === "Edit")) {
+    const skillBlock = uiDesignSkillGate(event.tool, event.filePath ?? "", event.content ?? "", collectDesignEvidence(event.sessionId, cwd));
+    if (skillBlock) return skillBlock;
+  }
+  // Codex apply_patch parity (D2 gap, docstring design-files-gate.ts:17-24): the
+  // same UI write can arrive fanned into event.files instead of a single
+  // Write/Edit. Map each non-delete file to its Write/Edit-equivalent tool
+  // ("add" -> Write, "update" -> Edit) and run the SAME gate, so the skill
+  // requirement cannot be bypassed just by routing the write through apply_patch.
+  // Scope matches the Write/Edit block above: ANY agent, before the agentId
+  // early-return — never narrowed to design-agent-only.
+  if (event.phase !== "post" && event.files && event.files.length > 0) {
+    const evidence = collectDesignEvidence(event.sessionId, cwd);
+    for (const f of event.files) {
+      if (f.op === "delete") continue;
+      const skillBlock = uiDesignSkillGate(f.op === "add" ? "Write" : "Edit", f.filePath, f.content, evidence);
+      if (skillBlock) return skillBlock;
+    }
+  }
+
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+  if (!agentId) return null; // top-level (lead) calls are never design-agent-scoped
+  const active = activeDesignAgent(cacheDir);
+  if (active && agentId !== active) return null;
+  const id = agentId;
+  // P5 fail-open fix: when the design flag is active but the state file is missing
+  // (e.g. teammate context), auto-init a fresh state instead of disabling all
+  // gating (parity with pipeline-gate.py:38-60). Without the flag, stay inert.
+  let state = loadDesignState(cacheDir, id);
+  if (!state) {
+    if (!active) return null;
+    const dsExists = findDesignSystem(cwd) !== "";
+    state = initDesignState(id, dsExists ? "page" : "full", dsExists);
+    saveDesignState(cacheDir, state);
+  }
+  // Corpus + plugin roots, resolved INDEPENDENTLY (corpusRoot never decides
+  // pluginsRoot — F4). Corpus absent ⇒ requirement waived (pre-doctrine quotas);
+  // the plugin-root write guard stays active against refs-design fabrication.
+  const corpusRoot = corpusRootOverride ?? resolveCorpusRoot();
+  const corpusRequired = corpusRoot !== "";
+  const pluginsRoot = pluginsRootOverride ?? resolvePluginsRoot();
+
+  if (event.phase === "post") {
+    recordPost(event, cacheDir, state, corpusRoot, corpusRequired, cwd);
+    if ((event.tool === "Write" || event.tool === "Edit") && /\.(tsx|jsx|css)$/.test(event.filePath ?? "")) {
+      const warnings = runDesignChecks(event.content ?? "");
+      if (warnings.length) return { kind: "inform", title: "Design review", reason: warnings.join(" "), actions: [] };
+    }
+    return null;
+  }
+  if (event.tool === "Write" || event.tool === "Edit") {
+    const fp = event.filePath ?? "";
+    // Parity: only design-system.md is screenshot-quota-gated (designSystemWriteGate).
+    const base = pluginsWriteGuard(fp, pluginsRoot) ?? stateFileGate(fp) ?? htmlCssOnlyGate(fp)
+      ?? htmlCssPipelineGate(fp, state, findDesignSystem(cwd) !== "") ?? designSystemWriteGate(fp, state, corpusRequired)
+      ?? designSystemContentGate({ filePath: fp, tool: event.tool, content: event.content ?? "", oldString: event.oldString, replaceAll: event.input.replace_all === true, state, corpusRoot, corpusRequired });
+    if (base) return base;
+    if (geminiEnabled() && state.geminiCalls === 0 && /\.(html|css)$/.test(fp)) {
+      return { kind: "block", title: "Design pipeline", reason: "BLOCKED: generate the frontend via create_frontend before hand-writing HTML/CSS.", actions: ["Call mcp__gemini-design__create_frontend first"] };
+    }
+    return null;
+  }
+  // Codex apply_patch (D2): gate each fanned-out file like a Write.
+  if (event.files && event.files.length > 0) return designFilesGate(event.files, state, pluginsRoot, corpusRoot, corpusRequired, cwd, findDesignSystem(cwd) !== "");
+  if (event.tool === NAV) {
+    return browserNavigateGate(state, typeof event.input.url === "string" ? event.input.url : "");
+  }
+  if (event.tool === SHOT) return screenshotScrollGate(state);
+  if (event.tool === GEMINI) {
+    if (!geminiEnabled()) return null;
+    const block = geminiCreateGate(state);
+    if (block) return block;
+    const ds = findDesignSystem(cwd);
+    // Parity validate-design-system.py DENY_NOT_FOUND: a MISSING file gets its own
+    // recovery message, distinct from the "too generic" message for a present-but-thin one.
+    if (ds === "") {
+      return { kind: "block", title: "Design pipeline", reason: "BLOCKED: design-system.md not found. RECOVERY: 1) Read the identity templates 2) Read design-inspiration.md 3) Read the refs-design corpus (README.md + relevant tokens-*.md) 4) Screenshot 1-2 real sector sites 5) Write design-system.md, then retry create_frontend.", actions: ["Create design-system.md via the pipeline, then retry create_frontend"] };
+    }
+    // Same content rules as the nominal write path (jointure included): the
+    // Gemini branch must not be weaker than the gate the Write just went through.
+    const contentBlock = checkDesignSystemContent(ds, state.corpusReads, corpusRequired);
+    if (contentBlock) return contentBlock;
+    saveDesignState(cacheDir, recordValidDesignSystem(state));
+  }
+  return null;
+}

package/src/runtime/dev-context.ts

@@ -0,0 +1,43 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { capFragment } from "./inject-budget";
+
+/** Run a git subcommand in `cwd`, returning trimmed stdout or "" on error. */
+function git(cwd: string, args: string[]): string {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: "pipe", timeout: 5000 }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Build the git portion of the dev context (branch + up to 5 changed files). */
+export function gitContext(cwd: string): string[] {
+  if (!existsSync(join(cwd, ".git"))) return [];
+  const parts = [`Git branch: ${git(cwd, ["branch", "--show-current"]) || "unknown"}`];
+  const status = git(cwd, ["status", "--porcelain"]);
+  if (status) parts.push("Modified files:\n" + status.split("\n").slice(0, 5).join("\n"));
+  return parts;
+}
+
+/** Build the project-type portion (mirrors load-dev-context.py exactly). */
+export function projectContext(cwd: string): string[] {
+  const parts: string[] = [];
+  const has = (f: string): boolean => existsSync(join(cwd, f));
+  if (["next.config.js", "next.config.ts", "next.config.mjs"].some(has)) parts.push("Project: Next.js");
+  else if (has("package.json")) parts.push("Project: Node.js");
+  if (has("composer.json") && has("artisan")) parts.push("Project: Laravel");
+  if (has("Package.swift")) parts.push("Project: Swift");
+  return parts;
+}
+
+/**
+ * Build the SessionStart dev-context block (git + project type), or "" when
+ * nothing applies. Ports `core-guards/scripts/session-start/load-dev-context.py`.
+ * @param cwd - Project root to inspect.
+ * @returns The joined additionalContext text (possibly empty).
+ */
+export function devContext(cwd: string): string {
+  return capFragment("dev-context", [...gitContext(cwd), ...projectContext(cwd)].join("\n"));
+}

package/src/runtime/dry-patterns.ts

@@ -0,0 +1,32 @@
+/** Short identifiers never worth a duplication check (control flow, tiny names). */
+export const DRY_KEYWORDS: ReadonlySet<string> = new Set([
+  "if", "for", "while", "switch", "catch", "return", "async",
+  "new", "get", "set", "map", "run", "use", "test", "main",
+]);
+
+/** Extensions treated as TS/JS-family for symbol extraction. */
+export const TS_EXT: ReadonlySet<string> = new Set([".ts", ".tsx", ".js", ".jsx", ".astro"]);
+
+/** Declaration patterns whose capture group 1 is the declared symbol name (TS/JS). */
+export const TS_PATTERNS: readonly RegExp[] = [
+  /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*[(<]/g,
+  /(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\(/g,
+  /class\s+(\w+)\b/g,
+];
+
+/**
+ * Declaration patterns for PHP (capture group 1 = symbol name). The modifier run
+ * is bounded (`{0,6}`) on purpose: an unbounded `(?:…\s+)*` is quadratic (O(n²))
+ * on a long whitespace/keyword run with no trailing `function`, which would block
+ * the hook for seconds on a crafted file. A real PHP signature has at most a few
+ * leading keywords, so the bound is behavior-equivalent and keeps matching linear.
+ */
+export const PHP_PATTERNS: readonly RegExp[] = [
+  /(?:(?:public|protected|private|static|final|abstract|readonly)\s+){0,6}function\s+(\w+)\s*\(/g,
+  /(?:class|interface|trait)\s+(\w+)\b/g,
+];
+
+/** Directories grep skips when scanning for existing declarations. */
+export const EXCLUDE_DIRS: readonly string[] = [
+  "vendor", "node_modules", ".next", ".git", "dist", "build", "coverage", ".turbo",
+];

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;
+}