@fusengine/harness 0.1.90 → 0.1.91

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

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

@@ -0,0 +1,93 @@
+/**
+ * Extended convention violations — the NEW rules of the conventions module
+ * (owner Amendments 3-5), all advisory-first: the caller wraps them with
+ * {@link rolloutVerdict}, so they surface as non-blocking `inform` until
+ * `FUSE_CONVENTIONS_MODE=deny`. Only fires when the legacy gates found
+ * nothing (no double-reporting of cases the legacy reactGate already blocks).
+ *
+ * Rules: (1) custom hook outside `hooks/` — widened to `export default`/
+ * `async` syntaxes and to the nextjs/tanstack family (legacy covered react
+ * only); (2) hook file over its line budget — `hookBudget`, ratio 0.3 of the
+ * global `FUSE_SOLID_MAX_LINES` limit (default 30; one variable drives every
+ * budget, owner decision — no per-file-kind env vars); (3) TanStack Start
+ * route files kept routing-only (no interface declarations in `src/routes/`);
+ * (4) store declared outside `stores/` or over `storeBudget` (ratio 0.4);
+ * (5) TanStack Query hook defined in a component/page (only when the
+ * `@tanstack/*-query` cap is detected in the nearest manifest — `query/` or
+ * `hooks/` are both accepted homes); (6) component file misplaced inside
+ * `src/hooks|stores|query|interfaces|types/` (deterministic case only).
+ */
+import { isHooksPath, isStoresPath, isComponentsPath } from "./conventions/langs";
+import { maskCommentsAndStrings } from "./conventions/strip";
+import { declaresCustomHook } from "./conventions/react-hooks";
+import { declaresInterface } from "./conventions/interfaces";
+import { declaresStore } from "./conventions/stores";
+import { declaresQueryHook, queryCapActive } from "./conventions/query";
+import { isStoreOrQueryDefinition } from "./conventions/store-or-query";
+import { countFrameworkCodeLines } from "./file-size";
+import { hookBudget, resolveMaxLines, storeBudget } from "../config/limits";
+
+/** TanStack Start content signal (file routes, server fns, start/router imports). */
+const TANSTACK_RE = /createFileRoute|createServerFn|from ['"]@tanstack\/react-(start|router)/;
+/** A custom-hook source file under a hooks directory. */
+const HOOK_FILE_RE = /(^|\/)use[A-Z][^/]*\.(ts|tsx|js|jsx)$/;
+
+/**
+ * Collect the extended convention violations for a JS/TS-family file.
+ * @param filePath - The written/edited file's path.
+ * @param content - Its raw content (masked internally).
+ * @returns The violation messages (empty when clean or out of scope).
+ */
+export function extendedViolations(filePath: string, content: string): string[] {
+  const v: string[] = [];
+  if (!/\.(tsx|ts|jsx|js|vue)$/.test(filePath)) return v;
+  const masked = maskCommentsAndStrings(content, "c");
+  // Store/query-definition files are governed by their own rules below,
+  // never by the hook-location rule (signature+cap-gated exemption, F0.2).
+  if (declaresCustomHook(content) && !isHooksPath(filePath) && !isStoreOrQueryDefinition(filePath, content)) {
+    v.push("Custom hook defined outside hooks/ directory. Move to modules/[feature]/src/hooks/.");
+  }
+  if (isHooksPath(filePath) && HOOK_FILE_RE.test(filePath)) {
+    const max = hookBudget(resolveMaxLines());
+    const lines = countFrameworkCodeLines(masked);
+    if (lines > max) v.push(`Hook file has ${lines} lines (limit: ${max}). Extract smaller hooks.`);
+  }
+  if (filePath.includes("/routes/") && TANSTACK_RE.test(masked) && declaresInterface(filePath, content)) {
+    v.push("Route files are routing-only. Move the interface to src/modules/[feature]/src/interfaces/.");
+  }
+  // (4) Stores: location + budget (signature-strict detection — see stores.ts).
+  const storeLib = declaresStore(content, "zustand") ? "zustand" : declaresStore(content, "pinia") ? "pinia" : null;
+  if (storeLib && !isStoresPath(filePath)) {
+    v.push("Store defined outside stores/ directory. Move to modules/[feature]/src/stores/.");
+  }
+  if (storeLib && isStoresPath(filePath)) {
+    const max = storeBudget(resolveMaxLines());
+    const lines = countFrameworkCodeLines(masked);
+    if (lines > max) v.push(`Store file has ${lines} lines (limit: ${max}).`);
+  }
+  // (5) TanStack Query definition in a component/page — only with the cap.
+  if (isComponentOrPagePath(filePath) && declaresQueryHook(content) && queryCapActive(filePath)) {
+    v.push("Query hook defined outside query/ directory. Move to modules/[feature]/src/query/.");
+  }
+  // (6) Component misplaced inside a non-component src/ subdirectory.
+  if (/\.(tsx|vue)$/.test(filePath)) {
+    const m = /\/src\/(hooks|stores|query|interfaces|types)\//.exec(filePath);
+    if (m && declaresComponent(masked)) {
+      v.push(`Component does not belong in ${m[1]}/. Move to modules/[feature]/components/.`);
+    }
+  }
+  return v;
+}
+
+/** Component/page directories where a store or query DEFINITION is a violation. */
+function isComponentOrPagePath(filePath: string): boolean {
+  return isComponentsPath(filePath) || /\/(pages|app|routes)\//.test(filePath);
+}
+
+/** True when the file declares an exported component (function/const, Vue SFC
+ * `export default {}` or `defineComponent(` included — audit F0 option). */
+function declaresComponent(masked: string): boolean {
+  return /^\s*export\s+(?:default\s+)?(?:function|const)\s+[A-Z]\w*/m.test(masked)
+    || /^\s*export\s+default\s*\{/m.test(masked)
+    || /defineComponent\s*\(/.test(masked);
+}

package/src/policy/framework-solid-gates-systems.ts

@@ -0,0 +1,99 @@
+import { resolveMaxLines } from "../config/limits";
+import { countFrameworkCodeLines } from "./file-size";
+import { moduleAwarePath } from "./module-layout";
+import { maskCommentsAndStrings } from "./conventions/strip";
+
+/**
+ * Systems-language SOLID gates (Go, Rust). Split out of `framework-solid-gates.ts`
+ * to stay under the SOLID line ceiling — the JS/framework gates already sit
+ * near it, and Go/Rust share no logic with React/Next/Laravel/Swift beyond the
+ * `moduleAwarePath` helper.
+ */
+
+/** Go top-level `type Foo interface` declaration. */
+const GO_INTERFACE_DECL_RE: RegExp = /^type\s+[A-Z]\w*\s+interface\b/m;
+/** Go method with a (pointer) receiver: `func (r *Foo) Bar(...)` — receiver type may be unexported (`repo`), unlike the interface it implements. */
+const GO_METHOD_RE: RegExp = /^func\s*\(\s*\w+\s+\*?[A-Za-z]\w*\)\s+\w+/m;
+/** Rust top-level `trait Foo` declaration (captures the name for impl co-location). */
+const RUST_TRAIT_DECL_RE: RegExp = /^(pub(\(\w+\))?\s+)?trait\s+([A-Z]\w*)/m;
+/** Rust top-level `struct`/`enum`/`trait` declaration. */
+const RUST_TYPE_DECL_RE: RegExp = /^(pub\s+)?(struct|enum|trait)\s+[A-Z]/m;
+/** Rust top-level `impl` block. */
+const RUST_IMPL_RE: RegExp = /^(pub\s+)?impl\b/m;
+/** Rust `unsafe fn/impl/trait/{` usage. */
+const RUST_UNSAFE_RE: RegExp = /\bunsafe\s*(fn|impl|trait|\{)/;
+/** `// SAFETY:` justification comment (case-insensitive). */
+const RUST_SAFETY_COMMENT_RE: RegExp = /\/\/\s*SAFETY:/i;
+/** Rust entry-point file: `main.rs`. */
+const RUST_MAIN_RE: RegExp = /(^|\/)main\.rs$/;
+/** Rust `src/bin/*.rs` binary target. */
+const RUST_BIN_RE: RegExp = /\/bin\/[^/]+\.rs$/;
+/** A single top-level `struct`/`enum` declaration (used for the clap-Args exemption). */
+const RUST_STRUCT_ENUM_RE: RegExp = /^(pub\s+)?(struct|enum)\s+[A-Z]\w*/gm;
+/** clap `#[derive(...Parser...)]` attribute. */
+const RUST_DERIVE_PARSER_RE: RegExp = /#\[derive\([^)]*Parser[^)]*\)\]/;
+
+/** Go: line limit, interface co-located with its (pointer-receiver) implementation. */
+export function goGate(filePath: string, content: string, fileLines?: number): string[] {
+  const v: string[] = [];
+  content = maskCommentsAndStrings(content, "c");
+  const max = resolveMaxLines();
+  const lines = fileLines ?? countFrameworkCodeLines(content);
+  if (lines > max) {
+    const dest = moduleAwarePath(filePath, "{services,handlers}.go", "an internal/ package by responsibility");
+    v.push(`File has ${lines} lines (limit: ${max}). Split into ${dest}.`);
+  }
+  const isExempt = filePath.endsWith("_test.go") || /\/mocks?\//.test(filePath) || /\/interfaces\//.test(filePath);
+  if (!isExempt && GO_INTERFACE_DECL_RE.test(content) && GO_METHOD_RE.test(content)) {
+    const dest = moduleAwarePath(filePath, "interfaces/", "internal/interfaces/ (consumer-side, Go idiom)");
+    v.push(`Interface declared alongside its implementation. Move the interface to ${dest}.`);
+  }
+  return v;
+}
+
+/**
+ * Whether `content`'s only top-level `struct`/`enum` is a clap `#[derive(...Parser...)]`
+ * args struct — the god-main.rs check's sole exemption (a CLI entry point wiring
+ * its own arg struct is not "business logic").
+ */
+function isClapArgsOnly(content: string): boolean {
+  const matches = [...content.matchAll(RUST_STRUCT_ENUM_RE)];
+  if (matches.length !== 1) return false;
+  const idx = matches[0]?.index;
+  if (idx === undefined) return false;
+  const before = content.slice(0, idx).split("\n");
+  for (let i = before.length - 1, checked = 0; i >= 0 && checked < 3; i--) {
+    const line = (before[i] ?? "").trim();
+    if (!line) continue;
+    checked++;
+    return RUST_DERIVE_PARSER_RE.test(line);
+  }
+  return false;
+}
+
+/** Rust: line limit, trait co-location, god-main.rs, unsafe without `// SAFETY:`. */
+export function rustGate(filePath: string, content: string, fileLines?: number): string[] {
+  const v: string[] = [];
+  const raw = content;
+  content = maskCommentsAndStrings(content, "c");
+  const max = resolveMaxLines();
+  const lines = fileLines ?? countFrameworkCodeLines(content);
+  if (lines > max) {
+    const dest = moduleAwarePath(filePath, "{...}.rs", "mod.rs + submodules");
+    v.push(`File has ${lines} lines (limit: ${max}). Split into ${dest}.`);
+  }
+  if (!/\/(traits|interfaces)\//.test(filePath) && !filePath.endsWith("traits.rs")) {
+    const m = RUST_TRAIT_DECL_RE.exec(content);
+    const name = m?.[3];
+    if (name && new RegExp(`impl\\s+${name}\\s+for\\s+\\w+`).test(content)) {
+      const dest = moduleAwarePath(filePath, "traits.rs", "a dedicated traits.rs / interfaces module");
+      v.push(`Trait declared alongside its implementation. Move the trait to ${dest}.`);
+    }
+  }
+  const isMain = RUST_MAIN_RE.test(filePath) || RUST_BIN_RE.test(filePath);
+  if (isMain && (RUST_TYPE_DECL_RE.test(content) || RUST_IMPL_RE.test(content)) && !isClapArgsOnly(content))
+    v.push("Entry point contains business logic — keep main.rs to wiring only (parse args, init, call lib.rs/app::run()).");
+  if (RUST_UNSAFE_RE.test(content) && !RUST_SAFETY_COMMENT_RE.test(raw))
+    v.push("unsafe without a // SAFETY: comment. Justify the invariant above each unsafe block.");
+  return v;
+}

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

@@ -0,0 +1,98 @@
+import { resolveMaxLines } from "../config/limits";
+import { countFrameworkCodeLines } from "./file-size";
+import { moduleAwarePath } from "./module-layout";
+import { maskCommentsAndStrings, maskCommentsOnly } from "./conventions/strip";
+import { isStoreOrQueryDefinition } from "./conventions/store-or-query";
+
+/** Custom hook export (React): `export function/const use[A-Z]`. */
+const HOOK_RE: RegExp = /^export (function|const) use[A-Z]/m;
+/** Top-level TS interface/type declaration. */
+const TS_DECL_RE: RegExp = /^(export )?(interface|type) [A-Z]/m;
+/** Client-only React hooks that require the `'use client'` directive. */
+const CLIENT_HOOK_RE: RegExp = /\b(useState|useEffect|useRef|onClick|onChange)\b/;
+/** PHP top-level `interface` declaration. */
+const PHP_INTERFACE_RE: RegExp = /^interface /m;
+/** Swift top-level `protocol` declaration. */
+const SWIFT_PROTOCOL_RE: RegExp = /^protocol /m;
+/** Swift type declaration (`class`/`struct`) opening a body. */
+const SWIFT_TYPE_RE: RegExp = /^(class|struct) [^\n{]* \{/m;
+
+/** React: line limit, interface separation, custom hooks under `/hooks/`. */
+export function reactGate(filePath: string, content: string, fileLines?: number): string[] {
+  const v: string[] = [];
+  const raw = content; // store/query detectors probe raw imports (F0.1)
+  content = maskCommentsAndStrings(content, "c");
+  const max = resolveMaxLines();
+  const lines = fileLines ?? countFrameworkCodeLines(content);
+  if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Split to hooks/, components/, or utils/.`);
+  if (filePath.includes("/components/") && TS_DECL_RE.test(content)) {
+    const dest = moduleAwarePath(filePath, "src/interfaces/", "src/interfaces/ or src/types/");
+    v.push(`Interface/type in component. Move to ${dest}.`);
+  }
+  // Store/query-definition files are NOT hooks: the legacy hook rule would
+  // hard-deny `useXStore`/`useUsers` into hooks/, shadowing the store/query
+  // conventions (owner E1/E5). The exemption itself is signature+cap gated
+  // (owner F0.2): no real import / no `@tanstack/*-query` dep → hook rule
+  // fires as before, byte-identical.
+  if (HOOK_RE.test(content) && !filePath.includes("/hooks/") && !isStoreOrQueryDefinition(filePath, raw))
+    v.push("Custom hook defined outside hooks/ directory. Move to hooks/.");
+  return v;
+}
+
+/** Next.js: adaptive line limit, interface separation, `'use client'`. */
+export function nextGate(filePath: string, content: string, fileLines?: number): string[] {
+  const v: string[] = [];
+  const raw = content; // the directive is a string literal — masking blanks it (F1.1)
+  content = maskCommentsAndStrings(content, "c");
+  const base = resolveMaxLines();
+  const max = /(page|layout|loading|error|not-found)\.(tsx|ts)$/.test(filePath) ? base + 50 : base;
+  const lines = fileLines ?? countFrameworkCodeLines(content);
+  if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Split to lib/, hooks/, or components/.`);
+  if (/\/(app|components|modules)\//.test(filePath) && !filePath.includes("/interfaces/") && TS_DECL_RE.test(content)) {
+    const dest = moduleAwarePath(filePath, "src/interfaces/", "src/interfaces/");
+    v.push(`Interface/type in component. Move to ${dest}.`);
+  }
+  if (CLIENT_HOOK_RE.test(content)) {
+    // Directive check on comment-masked content only: a `// "use client"`
+    // comment is NOT a directive, but the real string literal stays readable.
+    const head = maskCommentsOnly(raw, "c").split("\n").slice(0, 5).join("\n");
+    if (!head.includes("'use client'") && !head.includes('"use client"'))
+      v.push("Client hooks detected but 'use client' directive missing at top.");
+  }
+  return v;
+}
+
+/** Laravel/PHP: line limit, interface outside `/Contracts/`, fat controller (>80). */
+export function laravelGate(filePath: string, content: string, fileLines?: number): string[] {
+  const v: string[] = [];
+  content = maskCommentsAndStrings(content, "php");
+  const lines = fileLines ?? countFrameworkCodeLines(content);
+  const max = resolveMaxLines();
+  if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Split using Services, Actions, or Traits.`);
+  if (PHP_INTERFACE_RE.test(content) && !filePath.includes("/Contracts/")) {
+    const dest = moduleAwarePath(filePath, "Contracts/", "app/Contracts/ or FuseCore/{Module}/App/Contracts/");
+    v.push(`Interface defined outside Contracts/. Move to ${dest}.`);
+  }
+  if (filePath.includes("/Controllers/") && lines > 80)
+    v.push(`Fat controller (${lines} lines). Extract logic to Services or Actions.`);
+  return v;
+}
+
+/** Swift: adaptive limit, protocol separation, @MainActor, Sendable. */
+export function swiftGate(filePath: string, content: string, fileLines?: number): string[] {
+  const v: string[] = [];
+  content = maskCommentsAndStrings(content, "c");
+  const base = resolveMaxLines();
+  const max = /(View|Screen)\.swift$/.test(filePath) ? base + 50 : base;
+  const lines = fileLines ?? countFrameworkCodeLines(content);
+  if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Extract to ViewModels, Services, or subviews.`);
+  if (SWIFT_PROTOCOL_RE.test(content) && !filePath.includes("/Protocols/")) {
+    const dest = moduleAwarePath(filePath, "Protocols/", "Protocols/ directory");
+    v.push(`Protocol defined outside Protocols/ directory. Move to ${dest}.`);
+  }
+  if (filePath.endsWith("ViewModel.swift") && !content.includes("@MainActor"))
+    v.push("ViewModel missing @MainActor annotation.");
+  if (SWIFT_TYPE_RE.test(content) && content.includes("async ") && !content.includes("Sendable"))
+    v.push("Type uses async but doesn't conform to Sendable.");
+  return v;
+}

package/src/policy/framework-solid.ts

@@ -0,0 +1,88 @@
+import type { Prompt } from "../prompt/types";
+import {
+  isExcludedJsPath,
+  isExcludedPhpPath,
+  isExcludedSwiftPath,
+  isSelfGateSourcePath,
+} from "./framework-solid-exclude";
+import { laravelGate, nextGate, reactGate, swiftGate } from "./framework-solid-gates";
+import { goGate, rustGate } from "./framework-solid-gates-systems";
+import { jsGateRoute } from "./js-gate-route";
+import { extendedViolations } from "./framework-solid-extended";
+import { rolloutVerdict } from "./conventions/verdict";
+
+/** Next.js detection: directive, runtime types, or a `next` import. */
+const NEXT_RE: RegExp = /(use client|use server|NextRequest|NextResponse|from ['"]next)/;
+
+/** Build a SOLID `block` prompt from one or more violation messages. */
+function block(filePath: string, violations: string[]): Prompt {
+  return {
+    kind: "block",
+    title: "SOLID violation",
+    reason: `SOLID VIOLATION in ${filePath}: ${violations.join(" ")}`,
+    actions: violations,
+  };
+}
+
+/** Run the JS/TS gate (React or Next.js), honoring build-artifact exclusions. */
+function jsViolations(filePath: string, content: string, fileLines?: number): string[] {
+  if (isExcludedJsPath(filePath) || isSelfGateSourcePath(filePath)) return [];
+  // H1: manifest-first routing — the PROJECT's declared framework picks the
+  // gate, so a marker-less client component in a Next.js app still gets the
+  // directive rule (content routing sent it to reactGate → runtime crash).
+  // No JS-framework capability (no manifest, backend, vue) → legacy NEXT_RE
+  // content routing, byte-identical (fixtures/sim without manifests rely on it).
+  const route = jsGateRoute(filePath);
+  if (route === "nextjs") return nextGate(filePath, content, fileLines);
+  if (route === "react") return reactGate(filePath, content, fileLines);
+  return NEXT_RE.test(content)
+    ? nextGate(filePath, content, fileLines)
+    : reactGate(filePath, content, fileLines);
+}
+
+/**
+ * Framework-specific SOLID gate. Dispatches by extension/path to the matching
+ * validator (React, Next.js, Laravel, Swift, Go, Rust) and returns a blocking
+ * {@link Prompt} when any BLOCKING rule fires, or `null` when clean. Excluded
+ * build/dependency paths (node_modules, dist, build, .next, vendor, .build,
+ * DerivedData, Pods) early-return `null` to avoid false positives. Go and Rust
+ * have no exclusion list yet (no vendor/target FPs reported) — additive only.
+ * @param filePath - absolute path of the file being written/edited
+ * @param content - the file (or new) content under validation
+ * @param fileLines - full on-disk line count (set on Edit so a partial
+ *   `new_string` snippet still judges the whole file, mirroring the base
+ *   file-size guard / Python `get_full_file_content`). Omit on Write.
+ */
+export function frameworkSolidGate(filePath: string, content: string, fileLines?: number): Prompt | null {
+  if (!filePath || !content) return null;
+  // TanStack Router's generated route tree is never edited (Amendment 8 —
+  // protected artifact, like the existing protected-path guard).
+  if (filePath.endsWith("routeTree.gen.ts")) {
+    return {
+      kind: "block",
+      title: "Generated file",
+      reason: `SOLID VIOLATION in ${filePath}: routeTree.gen.ts is generated by TanStack Router — never edit it directly.`,
+      actions: ["Edit the source route files instead, then regenerate"],
+    };
+  }
+  let violations: string[] = [];
+  if (filePath.endsWith(".php")) {
+    if (isExcludedPhpPath(filePath)) return null;
+    violations = laravelGate(filePath, content, fileLines);
+  } else if (filePath.endsWith(".swift")) {
+    if (isExcludedSwiftPath(filePath)) return null;
+    violations = swiftGate(filePath, content, fileLines);
+  } else if (/\.(tsx|ts|jsx|js)$/.test(filePath)) {
+    violations = jsViolations(filePath, content, fileLines);
+  } else if (filePath.endsWith(".go")) {
+    violations = goGate(filePath, content, fileLines);
+  } else if (filePath.endsWith(".rs")) {
+    violations = rustGate(filePath, content, fileLines);
+  }
+  if (violations.length) return block(filePath, violations);
+  // Legacy gates clean: the NEW convention rules surface advisory-first —
+  // same exclusions as the JS path (build artifacts + self-gate sources).
+  if (!/\.(tsx|ts|jsx|js|vue)$/.test(filePath) || isExcludedJsPath(filePath) || isSelfGateSourcePath(filePath)) return null;
+  const extended = extendedViolations(filePath, content);
+  return extended.length ? rolloutVerdict(block(filePath, extended), true) : null;
+}

package/src/policy/gemini-mcp-gate.ts

@@ -0,0 +1,83 @@
+/**
+ * @module gemini-mcp-gate
+ * OPT-IN gate porting core-guards `enforce-gemini-mcp.py`: when enabled via
+ * `FUSE_ENFORCE_GEMINI_MCP`, blocks a UI write (`.tsx/.jsx/.vue/.svelte`) that
+ * hand-writes >= 3 Tailwind utility classes unless a `mcp__gemini-design__*`
+ * call was made this session. DISABLED BY DEFAULT — the flag is read fresh on
+ * every call, so nothing is gated unless the owner explicitly turns it on (a
+ * gate blocking a common dev action must never be always-on).
+ * @packageDocumentation
+ */
+import type { Prompt } from "../prompt/types";
+import type { AuthEntry } from "../freshness/doc-helpers";
+
+/** UI file extensions the gate polices (parity enforce-gemini-mcp.py UI_EXT). */
+const UI_EXT_RE = /\.(tsx|jsx|vue|svelte)$/;
+/** Paths exempt from the gate (parity EXEMPT_DIRS). */
+const GEMINI_EXEMPT_RE = /(node_modules|dist|build|\.next|\.claude)\//;
+/** A live `mcp__gemini-design__*` call recorded this session proves consultation. */
+const GEMINI_MCP_SOURCE_RE = /gemini-mcp/i;
+/** Tailwind utility patterns (parity TAILWIND_PATTERNS). */
+const TW_PATTERNS: readonly RegExp[] = [
+  /\bflex\b/, /\bgrid\b/, /\bp-\d/, /\bpx-\d/, /\bpy-\d/,
+  /\bm-\d/, /\bmx-\d/, /\bmy-\d/, /\bmt-\d/, /\bmb-\d/,
+  /\bbg-\w+/, /\btext-\w+/, /\brounded/, /\bshadow/,
+  /\bborder\b/, /\bgap-\d/, /\bw-\w+/, /\bh-\w+/,
+  /\bjustify-\w+/, /\bitems-\w+/, /\bspace-\w+-\d/,
+];
+/** Min distinct Tailwind patterns before the gate fires (parity MIN_TAILWIND_CLASSES). */
+const MIN_TW = 3;
+/** Min newlines an Edit's new_string must have to be gated (parity MIN_LINES_FOR_EDIT). */
+const MIN_LINES_EDIT = 2;
+
+/** OPT-IN: off unless `FUSE_ENFORCE_GEMINI_MCP` is `1`/`true`. Read fresh each call (dynamic). */
+export function geminiMcpEnforced(): boolean {
+  const v = process.env.FUSE_ENFORCE_GEMINI_MCP;
+  return v === "1" || v === "true";
+}
+
+/** Count distinct Tailwind utility patterns present in `content` (parity count_tailwind_classes). */
+function countTailwindClasses(content: string): number {
+  return TW_PATTERNS.reduce((n, re) => (re.test(content) ? n + 1 : n), 0);
+}
+
+/** Session evidence the gate consumes. */
+export interface GeminiEvidence {
+  authorizations?: Record<string, AuthEntry>;
+  sessionId: string;
+}
+
+/** True when a `mcp__gemini-design__*` call was recorded this session (parity gemini_was_called). */
+export function geminiMcpConsulted(authorizations: Record<string, AuthEntry> | undefined, sessionId: string): boolean {
+  if (!authorizations) return false;
+  return Object.values(authorizations).some(
+    (a) => a.doc_sessions?.includes(sessionId) && (a.sources ?? (a.source ? [a.source] : [])).some((s) => GEMINI_MCP_SOURCE_RE.test(s)),
+  );
+}
+
+/**
+ * Gate a UI write when `FUSE_ENFORCE_GEMINI_MCP` is on: block hand-written
+ * Tailwind (>= 3 classes) in a `.tsx/.jsx/.vue/.svelte` file unless a Gemini
+ * Design MCP call was made this session. Returns `null` when disabled (default),
+ * out of scope, or already satisfied.
+ * @param tool - the tool name.
+ * @param filePath - the file being written.
+ * @param content - the written content (new_string on Edit).
+ * @param ev - session evidence (authorizations + sessionId).
+ */
+export function geminiMcpGate(tool: string, filePath: string, content: string, ev: GeminiEvidence): Prompt | null {
+  if (!geminiMcpEnforced()) return null;
+  if (tool !== "Write" && tool !== "Edit") return null;
+  if (!filePath || !UI_EXT_RE.test(filePath) || GEMINI_EXEMPT_RE.test(filePath)) return null;
+  if (!content) return null;
+  if (tool === "Edit" && (content.match(/\n/g)?.length ?? 0) < MIN_LINES_EDIT) return null;
+  if (countTailwindClasses(content) < MIN_TW) return null;
+  if (geminiMcpConsulted(ev.authorizations, ev.sessionId)) return null;
+  return {
+    kind: "block",
+    title: "Gemini Design MCP",
+    reason:
+      "BLOCKED: UI code with Tailwind detected but Gemini Design MCP not used. Use mcp__gemini-design__create_frontend, modify_frontend, or snippet_frontend BEFORE writing UI code manually.",
+    actions: ["Call mcp__gemini-design__create_frontend / modify_frontend / snippet_frontend, then retry"],
+  };
+}