@fusengine/harness 0.1.90 → 0.1.92

package/src/policy/detect-primitive-checks.ts

@@ -0,0 +1,100 @@
+/**
+ * Detection checks for Radix UI vs Base UI primitives, ported verbatim from
+ * `detect_primitive_checks.py` (the shadcn-expert plugin's standalone
+ * detection script — not wired into any hook; called on demand by the agent
+ * to decide which shadcn-detection reference to read).
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+/** Package manager inferred from the project's lockfile. */
+export type PackageManager = "bun" | "pnpm" | "yarn" | "npm";
+
+/** `grep -rq <pattern> <path>`; true on a match, false on no-match/timeout/error. */
+function grepQuiet(pattern: string, path: string): boolean {
+  try {
+    execFileSync("grep", ["-rq", pattern, path], { timeout: 10_000, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Check `package.json` for UI library deps (weight: 40). Returns `[radix, baseui]`. */
+export function checkPkgJson(root: string, signals: string[]): [number, number] {
+  const pkg = join(root, "package.json");
+  if (!existsSync(pkg)) return [0, 0];
+  let radix = 0;
+  let baseui = 0;
+  try {
+    const content = readFileSync(pkg, "utf8");
+    if (content.includes('"@radix-ui/react-')) { radix = 40; signals.push("pkg:radix-ui"); }
+    if (content.includes('"@base-ui/react')) { baseui = 40; signals.push("pkg:base-ui"); }
+  } catch {
+    return [0, 0];
+  }
+  return [radix, baseui];
+}
+
+/** Check `components.json` style (weight: 20). Returns `[radix, baseui]`. */
+export function checkComponentsJson(root: string, signals: string[]): [number, number] {
+  const cjson = join(root, "components.json");
+  if (!existsSync(cjson)) return [0, 0];
+  try {
+    const data = JSON.parse(readFileSync(cjson, "utf8")) as { style?: string };
+    const style = data.style ?? "";
+    if (style === "new-york" || style === "default") {
+      signals.push(`style:${style}`);
+      return [20, 0];
+    }
+    if (style === "base-vega") {
+      signals.push("style:base-vega");
+      return [0, 20];
+    }
+  } catch {
+    return [0, 0];
+  }
+  return [0, 0];
+}
+
+/** Dirs scanned for import/data-attribute signals. */
+const SCAN_DIRS: ReadonlyArray<string> = ["src", "components", "app"];
+
+function existingScanDirs(root: string): string[] {
+  return SCAN_DIRS.map((d) => join(root, d)).filter((d) => {
+    try { return statSync(d).isDirectory(); } catch { return false; }
+  });
+}
+
+/** Scan imports (weight: 25) and data attributes (weight: 15). Returns `[radix, baseui]`. */
+export function scanImportsAndAttrs(root: string, signals: string[]): [number, number] {
+  const dirs = existingScanDirs(root);
+  let radix = 0;
+  let baseui = 0;
+  if (dirs.some((d) => grepQuiet("@radix-ui/react-", d))) { radix += 25; signals.push("import:radix"); }
+  if (dirs.some((d) => grepQuiet("@base-ui/react", d))) { baseui += 25; signals.push("import:base-ui"); }
+  if (dirs.some((d) => grepQuiet("data-state=", d))) { radix += 15; signals.push("attr:data-state"); }
+  if (dirs.some((d) => grepQuiet("data-\\[open\\]", d))) { baseui += 15; signals.push("attr:data-[open]"); }
+  return [radix, baseui];
+}
+
+/** Lockfile → package manager + runner, checked in priority order. */
+const LOCKFILES: ReadonlyArray<readonly [string, PackageManager, string]> = [
+  ["bun.lockb", "bun", "bunx"],
+  ["bun.lock", "bun", "bunx"],
+  ["pnpm-lock.yaml", "pnpm", "pnpm dlx"],
+  ["yarn.lock", "yarn", "yarn dlx"],
+];
+
+/** Detect the package manager from lockfiles present at `root` (defaults to npm/npx). */
+export function detectPm(root: string, signals: string[]): [PackageManager, string] {
+  for (const [lockfile, pm, runner] of LOCKFILES) {
+    if (existsSync(join(root, lockfile))) {
+      signals.push(`pm:${pm}`);
+      return [pm, runner];
+    }
+  }
+  signals.push("pm:npm");
+  return ["npm", "npx"];
+}

package/src/policy/detect-primitive-lib.ts

@@ -0,0 +1,55 @@
+/**
+ * Compose the Radix vs Base UI weighted detection, ported verbatim from
+ * `detect-primitive-lib.py`'s `main()`. Pure aggregation over
+ * {@link checkPkgJson}/{@link checkComponentsJson}/{@link scanImportsAndAttrs}/
+ * {@link detectPm} (`./detect-primitive-checks`).
+ */
+import { checkComponentsJson, checkPkgJson, detectPm, scanImportsAndAttrs, type PackageManager } from "./detect-primitive-checks";
+
+export type { PackageManager } from "./detect-primitive-checks";
+
+/** Which shadcn/ui primitive library the project uses, per the weighted signal score. */
+export type PrimitiveLib = "radix" | "base-ui" | "mixed" | "none";
+
+/** Result of {@link detectPrimitiveLib}. */
+export interface PrimitiveDetection {
+  primitive: PrimitiveLib;
+  confidence: number;
+  pm: PackageManager;
+  runner: string;
+  signals: string[];
+}
+
+/**
+ * Detect whether `root` uses Radix UI or Base UI as its shadcn/ui primitive,
+ * from weighted signals (package.json 40, components.json style 20, imports 25,
+ * data attributes 15). `"mixed"` when both accumulate signal, `"none"` when
+ * neither does.
+ * @param root - project root to scan (defaults to `process.cwd()`).
+ */
+export function detectPrimitiveLib(root: string = process.cwd()): PrimitiveDetection {
+  const signals: string[] = [];
+  const [r1, b1] = checkPkgJson(root, signals);
+  const [r2, b2] = checkComponentsJson(root, signals);
+  const [r3, b3] = scanImportsAndAttrs(root, signals);
+  const [pm, runner] = detectPm(root, signals);
+  const radix = r1 + r2 + r3;
+  const baseui = b1 + b2 + b3;
+
+  let primitive: PrimitiveLib;
+  let confidence: number;
+  if (radix > 0 && baseui > 0) {
+    primitive = "mixed";
+    confidence = Math.floor((radix + baseui) / 2);
+  } else if (radix > baseui) {
+    primitive = "radix";
+    confidence = radix;
+  } else if (baseui > radix) {
+    primitive = "base-ui";
+    confidence = baseui;
+  } else {
+    primitive = "none";
+    confidence = 0;
+  }
+  return { primitive, confidence, pm, runner, signals };
+}

package/src/policy/detect-project.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Project types detected from filesystem indicators. */
+export type ProjectType =
+  | "nextjs" | "nuxt" | "angular" | "svelte" | "vue" | "react" | "tailwind"
+  | "laravel" | "rails" | "django" | "python" | "go" | "rust" | "swift"
+  | "java" | "scala" | "elixir" | "ruby" | "generic";
+
+/** Keywords that signal a development task (APEX trigger). */
+export const DEV_KEYWORDS: RegExp =
+  /\b(implement|create|build|fix|add|refactor|develop|feature|bug|update|modify|change|write|code)\b/i;
+
+/** True when the prompt invokes the /apex command. */
+export function isApexCommand(prompt: string): boolean {
+  return /(?:^|\s)\/apex|\/fuse-ai-pilot:apex/i.test(prompt);
+}
+
+/** Modular architecture variants layered on top of the framework. */
+export type ModularArchitecture = "fusecore" | "nextjs-modular" | null;
+
+/**
+ * Detect a project-internal modular architecture (a sub-architecture the
+ * framework-level {@link detectProjectType} doesn't capture): Fusengine's
+ * FuseCore (Laravel) or a `modules/`-based Next.js layout.
+ */
+export function detectModularArchitecture(dir: string): ModularArchitecture {
+  const has = (f: string): boolean => existsSync(join(dir, f));
+  if (has("FuseCore") && has("artisan")) return "fusecore";
+  if (has("modules") && (has("next.config.js") || has("next.config.ts") || has("next.config.mjs"))) {
+    return "nextjs-modular";
+  }
+  return null;
+}
+
+/**
+ * Resolve the skill a detected modular architecture forces.
+ *
+ * Ports the Python `check-nextjs-skill.py` / `check-laravel-skill.py` gates:
+ * when the project is detected on disk as a modular architecture, a specific
+ * skill is required ('solid-nextjs' for nextjs-modular, 'fusecore' for
+ * fusecore). Returns `null` when no modular architecture is detected.
+ *
+ * @param cwd - Project root directory to scan.
+ * @returns The forced skill name, or `null` when none applies.
+ */
+export function requiredArchSkill(cwd: string): string | null {
+  switch (detectModularArchitecture(cwd)) {
+    case "nextjs-modular":
+      return "solid-nextjs";
+    case "fusecore":
+      return "fusecore";
+    default:
+      return null;
+  }
+}
+
+/** Config file names that mark a project as using Tailwind (v3 JS config or legacy). */
+const TAILWIND_CONFIG_FILES = ["tailwind.config.js", "tailwind.config.ts", "tailwind.config.mjs", "tailwind.config.cjs"];
+
+/** True when `package.json` lists `tailwindcss` as a dep (Tailwind v4 CSS-first, no config file). */
+function hasTailwindDependency(dir: string): boolean {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    return "tailwindcss" in { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch {
+    return false;
+  }
+}
+
+/** Detect the project type by scanning config files in `dir`. */
+export function detectProjectType(dir: string): ProjectType {
+  const has = (f: string): boolean => existsSync(join(dir, f));
+  if (has("next.config.js") || has("next.config.ts") || has("next.config.mjs")) return "nextjs";
+  if (has("nuxt.config.ts") || has("nuxt.config.js")) return "nuxt";
+  if (has("angular.json")) return "angular";
+  if (has("svelte.config.js") || has("svelte.config.ts")) return "svelte";
+  if (has("vite.config.ts") && has("src/App.vue")) return "vue";
+  if (has("vite.config.ts") || has("vite.config.js")) return "react";
+  if (TAILWIND_CONFIG_FILES.some(has) || hasTailwindDependency(dir)) return "tailwind";
+  if (has("composer.json") && has("artisan")) return "laravel";
+  if (has("Gemfile") && has("config/routes.rb")) return "rails";
+  if (has("requirements.txt") || has("pyproject.toml") || has("setup.py")) {
+    return has("manage.py") ? "django" : "python";
+  }
+  if (has("go.mod")) return "go";
+  if (has("Cargo.toml")) return "rust";
+  if (has("Package.swift")) return "swift";
+  if (has("pom.xml") || has("build.gradle") || has("build.gradle.kts")) return "java";
+  if (has("build.sbt")) return "scala";
+  if (has("mix.exs")) return "elixir";
+  if (has("Gemfile")) return "ruby";
+  return "generic";
+}

package/src/policy/edit-outcome.ts

@@ -0,0 +1,53 @@
+import { countLines } from "./file-size";
+
+/**
+ * Count non-overlapping literal occurrences of `needle` in `haystack`. An
+ * empty `needle` returns 0 — treated as "not found" by callers, since Edit's
+ * `old_string` is never legitimately empty and an empty needle has no
+ * well-defined occurrence count.
+ * @param haystack - The on-disk file content to search.
+ * @param needle - The literal substring to count.
+ */
+function countOccurrences(haystack: string, needle: string): number {
+  if (needle === "") return 0;
+  let count = 0;
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) break;
+    count++;
+    from = at + needle.length;
+  }
+  return count;
+}
+
+/**
+ * Compute the line count an Edit would PRODUCE, before it lands on disk —
+ * `existingLines − countLines(old_string) + countLines(new_string)`, scaled
+ * by how many `old_string` occurrences are actually replaced (1 normally, or
+ * every occurrence under `replace_all`). Pure arithmetic on the literal
+ * strings — no regex/fuzzy matching, matching the real Edit tool's own
+ * exact-substring semantics.
+ *
+ * Returns `null` (fail-closed — caller must fall back to judging the stale
+ * on-disk count alone) when `old_string` is missing/empty, or does not occur
+ * in `existingContent` at all: an Edit whose `old_string` doesn't match the
+ * real file is stale or adversarial, never a case to special-case an allow for.
+ * @param existingContent - Full on-disk content of the file being edited.
+ * @param oldString - The Edit's `old_string` (tool_input, unmodified).
+ * @param newString - The Edit's `new_string` (tool_input, unmodified).
+ * @param replaceAll - The Edit's `replace_all` flag.
+ */
+export function computeEditResultLines(
+  existingContent: string,
+  oldString: string | undefined,
+  newString: string,
+  replaceAll: boolean,
+): number | null {
+  if (!oldString) return null;
+  const occurrences = countOccurrences(existingContent, oldString);
+  if (occurrences === 0) return null;
+  const times = replaceAll ? occurrences : 1;
+  const delta = countLines(newString) - countLines(oldString);
+  return countLines(existingContent) + delta * times;
+}

package/src/policy/evaluate.ts

@@ -0,0 +1,81 @@
+import { isFileSizeScoped, resolveSolidRefFramework } from "./file-size-scope";
+import { countLines, evaluateFileSize } from "./file-size";
+import { computeEditResultLines } from "./edit-outcome";
+import { resolveMaxLines } from "../config/limits";
+import { matchPatterns, GIT_BLOCKED, RALPH_SAFE, isRalphMode } from "./patterns";
+import { runGuards } from "./guards";
+import { isSingleCommand, buildNeverApprovalPrompt, NEVER_SAFE, isSafePushForm } from "./never-approval";
+import { evaluateGitGates } from "./git-gates";
+import type { PolicyContext, PolicyResult } from "./interfaces/types";
+
+export type { PolicyContext, PolicyResult } from "./interfaces/types";
+
+/**
+ * Evaluate a single tool-use against the bundled policies, returning a pure
+ * decision plus a portable {@link Prompt}. Adapters translate the prompt into
+ * their harness's native response (Claude `permissionDecision`, etc.).
+ */
+export function evaluate(ctx: PolicyContext): PolicyResult {
+  const guard = runGuards(ctx);
+  if (guard) return { decision: "deny", message: guard.reason, prompt: guard };
+  // Ralph mode (opt-in via RALPH_MODE) exempts the SAFE git commands from the git
+  // block/ask gates for autonomous runs — parity git-guard.py:48-51. Destructive
+  // commands are NOT in RALPH_SAFE, so force-push / reset --hard stay blocked.
+  const cmd = ctx.command;
+  const ralphSafe = !!cmd && isRalphMode() && RALPH_SAFE.some((s) => cmd.startsWith(s));
+  // Codex `approval_policy=never` has no ask channel: for the NEVER_SAFE subset
+  // (RALPH_SAFE + "git push"), never destructive (GIT_BLOCKED) and never chained
+  // (isSingleCommand — `git commit -m x && git push --force` must NOT slip
+  // through), auto-approve with a visible `warn` instead of falling through to
+  // GIT_ASK's normal `ask`. isSafePushForm additionally narrows the "git push"
+  // entry: it excludes --delete/--mirror/--prune and a `:refspec` remote-delete,
+  // none of which GIT_BLOCKED catches (that gate only covers --force). RALPH_MODE
+  // takes priority (ralphSafe already silent-allows above this) — its own path
+  // stays on RALPH_SAFE, unaffected by this push exemption.
+  const neverExempt = !ralphSafe && !!ctx.neverApproval && !!cmd && !matchPatterns(cmd, GIT_BLOCKED) && isSingleCommand(cmd) && NEVER_SAFE.some((s) => cmd.startsWith(s)) && isSafePushForm(cmd);
+  if (neverExempt && cmd) {
+    const prompt = buildNeverApprovalPrompt(cmd);
+    return { decision: "warn", message: prompt.reason, prompt };
+  }
+  const gitGate = evaluateGitGates(ctx.command, ralphSafe);
+  if (gitGate) return gitGate;
+  if (ctx.filePath && isFileSizeScoped(ctx.filePath) && ctx.agentType !== "Explore" && ctx.agentType !== "Plan") {
+    const incoming = ctx.content !== undefined ? countLines(ctx.content) : 0;
+    const existing = ctx.existingLines ?? 0;
+    const max = ctx.maxLines ?? resolveMaxLines();
+    // A computable Edit outcome bypasses the on-disk-only ceiling below: either
+    // the result itself is compliant, or the file was already oversized and
+    // this Edit strictly shrinks it (see policy/edit-outcome.ts). Fails closed
+    // to the ceiling whenever the outcome isn't computable.
+    const editResult = ctx.tool === "Edit" && ctx.existingContent !== undefined && ctx.content !== undefined
+      ? computeEditResultLines(ctx.existingContent, ctx.oldString, ctx.content, ctx.isReplaceAll === true)
+      : null;
+    if (editResult !== null && (editResult <= max || editResult < existing)) {
+      return { decision: "allow", message: null };
+    }
+    // Write provides the full new content → judge it. Edit judges the computed
+    // outcome when known (closes the old grow-via-Edit hole), else the on-disk file.
+    const lines = ctx.tool === "Edit" ? (editResult ?? Math.max(incoming, existing)) : incoming || existing;
+    const framework = resolveSolidRefFramework(ctx.filePath);
+    // Python parity (enforce-file-size.py:44-57): the block message always
+    // reports the pre-existing on-disk count, even for a Write whose new
+    // content is itself over the limit — the incoming count only ever gates
+    // an early "shrunk to compliant" allow, it's never what gets displayed.
+    const displayLines = ctx.tool === "Write" ? ctx.existingLines ?? lines : lines;
+    const verdict = evaluateFileSize(lines, max, ctx.filePath, framework, displayLines);
+    if (lines > 0 && !verdict.ok) {
+      return {
+        decision: "deny",
+        message: verdict.message,
+        prompt: {
+          kind: "block",
+          title: "SOLID file-size limit",
+          reason: verdict.message ?? "",
+          actions: [`Split into modules under ${verdict.max} lines (Single Responsibility)`, "Then re-run the write"],
+        },
+        meta: { framework, lines: verdict.lines, max: verdict.max },
+      };
+    }
+  }
+  return { decision: "allow", message: null };
+}

package/src/policy/expert-agents.ts

@@ -0,0 +1,60 @@
+/**
+ * Dynamic expert-agent resolution (fs). Replaces a hardcoded agent-id table:
+ * scans installed marketplace plugins for an `agents/*.md` whose frontmatter
+ * `name` matches the detected {@link ProjectType}, returning the real
+ * `<plugin>:<agent>` id — never a fictional one absent from disk.
+ *
+ * Reuses the cartographer's own fs primitives ({@link findMarketplacePlugins},
+ * {@link readPluginMeta}, {@link scanAgents}) — the same shallow,
+ * non-recursive scan already run uncached on every SessionStart
+ * (`generateEcosystemMap`), scoped here to just `agents/*.md` (skips
+ * skills/commands/hooks) to keep the per-prompt cost minimal.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { findMarketplacePlugins, readPluginMeta } from "../runtime/lifecycle/cartographer/detect";
+import { scanAgents } from "../runtime/lifecycle/cartographer/scan";
+import type { ProjectType } from "./detect-project";
+
+/** Sorted plugin-dir names directly under `pluginsDir` (dirs only, alpha), or `[]`. */
+function pluginDirs(pluginsDir: string): string[] {
+  let names: string[];
+  try {
+    names = readdirSync(pluginsDir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => !n.startsWith(".") && !n.startsWith("_"))
+    .filter((n) => {
+      try {
+        return statSync(join(pluginsDir, n)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .sort((a, b) => a.localeCompare(b, "en"));
+}
+
+/**
+ * Resolve the real, installed expert-agent id for `type`.
+ * @param type - Detected project type.
+ * @param pluginsDirOverride - Override for the marketplace plugins dir
+ *   (tests); defaults to the auto-detected marketplace root.
+ * @returns `<plugin>:<agent>` for the first installed plugin whose agent name
+ *   starts with `type`, or "general-purpose" when none is installed.
+ */
+export function getExpertAgent(type: ProjectType, pluginsDirOverride?: string): string {
+  const pluginsDir = pluginsDirOverride ?? findMarketplacePlugins();
+  for (const dir of pluginDirs(pluginsDir)) {
+    const pluginPath = join(pluginsDir, dir);
+    const agent = scanAgents(pluginPath)
+      .map(([, name]) => name)
+      .find((name) => name.toLowerCase().startsWith(type.toLowerCase()));
+    if (agent) {
+      const [, pkgName] = readPluginMeta(pluginPath);
+      return `${pkgName || dir}:${agent}`;
+    }
+  }
+  return "general-purpose";
+}

package/src/policy/file-size-scope.ts

@@ -0,0 +1,32 @@
+import { detectFramework } from "./detect-framework";
+
+/**
+ * File-size gate scope — parity `enforce-file-size.py` CODE_EXT (both pre- and
+ * post-tool-use variants; deliberately excludes `.css`, matching the product
+ * decision already applied to `runtime/gate-helpers.ts::isApexScoped` for the
+ * sibling `require-apex-agents.py`). NOT `util/project-root.ts::isCodeFile`, a
+ * broader general-purpose predicate whose other two callers (`cli/run.ts`,
+ * `lifecycle/lessons/dispatch.ts`) are unrelated to this Python source.
+ */
+const FILE_SIZE_CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|dart|vue|svelte|astro)$/;
+
+/** True when `filePath` is in scope for the SOLID file-size gate (see {@link FILE_SIZE_CODE_EXT}). */
+export function isFileSizeScoped(filePath: string): boolean {
+  return FILE_SIZE_CODE_EXT.test(filePath);
+}
+
+/**
+ * Resolve the SOLID_REF framework key for a file — now project-real via
+ * {@link detectFramework} (nearest-manifest caps ∩ file signal), NOT the old
+ * extension-only default that mislabeled every `.ts` as react (the "twin bug" of
+ * the require-solid-read pipeline; it only escaped when `next.config` sat in the
+ * SAME dir). A backend `.ts` in a react project — or any `.ts` in this generic
+ * Bun repo — now resolves to "generic". Content is unavailable at this call site
+ * (evaluate.ts:59 passes only the path), so `.tsx`/`.jsx` still resolve via caps
+ * while `.ts`/`.js` lacking a content signal fall to "generic". Return values
+ * stay in the existing union; fail-open to "generic".
+ * @param filePath - Absolute path of the file being written/edited.
+ */
+export function resolveSolidRefFramework(filePath: string): string {
+  return detectFramework(filePath, "");
+}

package/src/policy/file-size.ts

@@ -0,0 +1,99 @@
+import { basename } from "node:path";
+import { resolveMaxLines, splitTarget } from "../config/limits";
+
+/**
+ * Fixed marketplace plugins root — parity with Python `enforce-file-size.py`'s
+ * literal, unexpanded `~/...` string. Exported: reused by
+ * `policy/apex.ts::solidReadGate` for its "no reference matched" deny message.
+ */
+export const PLUGINS_DIR = "~/.claude/plugins/marketplaces/fusengine-plugins/plugins";
+
+/**
+ * Skill-dir fragment per framework — parity with Python
+ * `enforce-file-size.py::get_solid_ref()` (falls back to `generic/`). Exported:
+ * reused by `policy/apex.ts::solidReadGate` (see {@link PLUGINS_DIR}).
+ */
+export const SOLID_REF: Record<string, string> = {
+  react: "react-expert/skills/solid-react/",
+  nextjs: "nextjs-expert/skills/solid-nextjs/",
+  "tanstack-start": "tanstack-start-expert/skills/solid-tanstack-start/",
+  laravel: "laravel-expert/skills/solid-php/",
+  swift: "swift-apple-expert/skills/solid-swift/",
+  go: "solid/skills/solid-go/",
+  rust: "solid/skills/solid-rust/",
+};
+
+/** Verdict from {@link evaluateFileSize}. */
+export interface FileSizeVerdict {
+  ok: boolean;
+  lines: number;
+  max: number;
+  message: string | null;
+}
+
+/**
+ * Count physical lines — parity with the Python `enforce-file-size.py`
+ * (`sum(1 for _ in f)`): every line counts (blanks and comments included), and a
+ * single trailing newline does not add a phantom line. The SOLID ceiling is
+ * measured on raw file length, not substantive code, to match the upstream plugin.
+ */
+export function countLines(content: string): number {
+  if (content === "") return 0;
+  return content.split("\n").length - (content.endsWith("\n") ? 1 : 0);
+}
+
+/**
+ * Count non-empty, non-comment lines — parity with the Python `count_code_lines`
+ * shared by the framework-specific SOLID validators: `_shared/scripts/validate_solid_common.py`
+ * (imported by `nextjs-expert/scripts/validate-nextjs-solid.py` and
+ * `swift-apple-expert/scripts/validate-swift-solid.py`), duplicated verbatim in
+ * `react-expert/scripts/validate-react-solid.py` / `laravel-expert/scripts/validate-laravel-solid.py`.
+ * Strips blank lines and lines starting with `//` or `*` — a SINGLE fixed rule
+ * for all 4 callers (the Python `comment` param defaults to, and every real
+ * call site leaves it at, `"//"` — never per-language despite covering
+ * ts/tsx/js/jsx, php and swift).
+ *
+ * Deliberately distinct from two other "code-only" counters already in this
+ * repo, neither of which is a faithful substitute here:
+ *  - `countLoc` (`runtime/lifecycle/check-file-size.ts`): a genuinely
+ *    per-language table (PHP additionally strips `#`, Python strips
+ *    `#`/`"""`/`'''`) — ported from the unrelated `solid/scripts/check-file-size.py`.
+ *  - `countCodeLines` (`runtime/lifecycle/aipilot/solid-compliance.ts`): also
+ *    strips `#` — ported from `ai-pilot/scripts/check-solid-compliance.py`.
+ * Reusing either would silently strip PHP `#`/Python-style comments that the
+ * real react/nextjs/laravel/swift validators do NOT strip.
+ * @param content - The file content to measure.
+ */
+export function countFrameworkCodeLines(content: string): number {
+  let count = 0;
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("//") || line.startsWith("*")) continue;
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Evaluate a file's line count against the SOLID limit.
+ * @param lines - the file's line count
+ * @param max - the limit (defaults to `resolveMaxLines()`)
+ */
+export function evaluateFileSize(
+  lines: number,
+  max: number = resolveMaxLines(),
+  filePath = "",
+  framework = "generic",
+  displayLines: number = lines,
+): FileSizeVerdict {
+  if (lines <= max) return { ok: true, lines, max, message: null };
+  const split = splitTarget(max);
+  const fname = filePath ? basename(filePath) : "file";
+  const ref = SOLID_REF[framework] ?? "generic/";
+  return {
+    ok: false,
+    lines,
+    max,
+    message: `BLOCKED: '${fname}' has ${displayLines} lines (max: ${max}). TO SPLIT: 1) Read SOLID rules: ${PLUGINS_DIR}/${ref} 2) Create new module files (<${split} lines each) 3) Use Write to replace '${fname}' with <${max} lines version.`,
+  };
+}

package/src/policy/framework-solid-exclude.ts

@@ -0,0 +1,52 @@
+/** Build/dep paths excluded from React/Next.js SOLID gating — segment-anchored (parity `r"/(node_modules|dist|build|\.next)/"`), NOT a bare substring, so `distance.ts`/`rebuild/` stay gated. */
+const JS_EXCLUDE_RE: RegExp = /(^|\/)(node_modules|dist|build|\.next)(\/|$)/;
+/** Vendored dependency paths excluded from Laravel/PHP SOLID gating. */
+const PHP_EXCLUDE_RE: RegExp = /\/vendor\//;
+/** Derived/build artifact paths excluded from Swift SOLID gating. */
+const SWIFT_EXCLUDE_RE: RegExp = /(\.build|DerivedData|Pods)/;
+
+/**
+ * Whether a JS/TS (React/Next.js) file path is an excluded build artifact.
+ * Matches the Python validators' early-return guard to avoid false positives.
+ * @param filePath - absolute path of the file under validation
+ */
+export function isExcludedJsPath(filePath: string): boolean {
+  return JS_EXCLUDE_RE.test(filePath);
+}
+
+/**
+ * Whether a PHP (Laravel) file path is a vendored dependency to skip.
+ * @param filePath - absolute path of the file under validation
+ */
+export function isExcludedPhpPath(filePath: string): boolean {
+  return PHP_EXCLUDE_RE.test(filePath);
+}
+
+/**
+ * Whether a Swift file path is a derived/build artifact to skip.
+ * @param filePath - absolute path of the file under validation
+ */
+export function isExcludedSwiftPath(filePath: string): boolean {
+  return SWIFT_EXCLUDE_RE.test(filePath);
+}
+
+/**
+ * This harness's own gate-detection source files. They hold the React/Next
+ * detection literals as regex source text (client-directive string, hook/
+ * event names, store/query/route signals) — scanning them as JS/TS would
+ * self-match the very heuristics they define. Exempt by exact filename or by
+ * the conventions/ detector directory, not by broad directory, so a genuine
+ * SOLID violation elsewhere in src/policy/ stays gated by the
+ * framework-agnostic line-size check in policy/evaluate.ts, untouched.
+ */
+const SELF_GATE_EXCLUDE_RE: RegExp = /(^|\/)src\/policy\/(framework-solid-gates(-systems)?\.ts|framework-solid-extended\.ts|detect-framework\.ts|conventions\/[^/]+\.ts|guards\/interface-separation-ext\.ts)$/;
+
+/**
+ * Whether a JS/TS file path is this harness's own gate-detection source —
+ * exempt from the pattern heuristics (not the line-size ceiling) to avoid
+ * self-blocking on regex literals that look like the code they detect.
+ * @param filePath - absolute path of the file under validation
+ */
+export function isSelfGateSourcePath(filePath: string): boolean {
+  return SELF_GATE_EXCLUDE_RE.test(filePath);
+}