@fusengine/harness 0.1.90 → 0.1.91

package/src/policy/design/transitions.ts

@@ -0,0 +1,68 @@
+import { type DesignState, type DesignMode, quotaFor } from "./state";
+import { corpusReady } from "./corpus";
+
+/** Infer the pipeline mode from the launch prompt + whether a design-system.md already exists. */
+export function detectMode(prompt: string, designSystemExists: boolean): DesignMode {
+  const p = prompt.toLowerCase();
+  if (["component", "composant", "snippet"].some((k) => p.includes(k))) return "component";
+  return designSystemExists ? "page" : "full";
+}
+
+/**
+ * Re-evaluate the phase-2 conjunction MONOTONICALLY: corpus reads (when the
+ * corpus is delivered) AND the screenshot quota must both hold, and the phase
+ * is never written downwards (a Read after phase 3 changes nothing).
+ */
+function maybePhase2(state: DesignState, corpusRequired: boolean): DesignState {
+  if (state.currentPhase >= 2) return state;
+  const corpusOk = !corpusRequired || corpusReady(state.corpusReads, state.mode);
+  if (!corpusOk || state.screenshotsCount < quotaFor(state.mode, corpusRequired)) return state;
+  return { ...state, currentPhase: 2, phasesCompleted: [...new Set([...state.phasesCompleted, "identity", "research"])] };
+}
+
+/** Record a screenshot: bump the count, then re-evaluate the phase-2 conjunction. */
+export function recordScreenshot(state: DesignState, corpusRequired: boolean): DesignState {
+  return maybePhase2({ ...state, screenshotsCount: state.screenshotsCount + 1 }, corpusRequired);
+}
+
+/** Record a fuse-browser navigate (resets the scroll-before-screenshot guard). */
+export function recordNavigate(state: DesignState): DesignState {
+  return { ...state, scrolledSinceNav: false };
+}
+
+/** Record a fuse-browser scroll (satisfies the scroll-before-screenshot guard). */
+export function recordScroll(state: DesignState): DesignState {
+  return { ...state, scrolledSinceNav: true };
+}
+
+/** Mark the design system validated and advance to phase 3 (after a passing create_frontend check). */
+export function recordValidDesignSystem(state: DesignState): DesignState {
+  return {
+    ...state, designSystemExists: true, designSystemValid: true,
+    currentPhase: Math.max(state.currentPhase, 3),
+    phasesCompleted: [...new Set([...state.phasesCompleted, "design-system"])],
+  };
+}
+
+/**
+ * Record a corpus read: distinct files only (a re-read never inflates the
+ * list), then re-evaluate the phase-2 conjunction. `relPath` is relative to
+ * the corpus root, keeping the persisted state small and prefix-independent.
+ */
+export function recordCorpusRead(state: DesignState, relPath: string, corpusRequired: boolean): DesignState {
+  return maybePhase2({ ...state, corpusReads: [...new Set([...state.corpusReads, relPath])] }, corpusRequired);
+}
+
+/**
+ * Record a skill-file Read: reading the identity templates enters phase 1 (browsing
+ * allowed); reading the inspiration catalog satisfies the browse prerequisite.
+ */
+export function recordRead(state: DesignState, filePath: string, corpusRequired = false): DesignState {
+  const next: DesignState = { ...state };
+  if (filePath.includes("design-system/SKILL.md")) {
+    next.currentPhase = Math.max(state.currentPhase, 1);
+    next.phasesCompleted = [...new Set([...state.phasesCompleted, "identity"])];
+  }
+  if (filePath.includes("design-inspiration")) next.inspirationRead = true;
+  return maybePhase2(next, corpusRequired);
+}

package/src/policy/detect-claude-md-project-type.ts

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ProjectType } from "./detect-project";
+
+/**
+ * Detect the project type from the cwd, reproducing the legacy Python logic:
+ * package.json containing "next" → nextjs, else "react" → react; else
+ * composer.json+artisan → laravel; else Package.swift / *.xcodeproj → swift;
+ * else generic.
+ * @param cwd - Project root to scan.
+ * @returns The detected project type label.
+ */
+export function detectClaudeMdProjectType(cwd: string): ProjectType {
+  const pkg = join(cwd, "package.json");
+  if (existsSync(pkg)) {
+    try {
+      const content = readFileSync(pkg, "utf-8");
+      if (content.includes("next")) return "nextjs";
+      if (content.includes("react")) return "react";
+    } catch {
+      /* unreadable package.json → fall through */
+    }
+  }
+  if (existsSync(join(cwd, "composer.json")) && existsSync(join(cwd, "artisan"))) return "laravel";
+  if (existsSync(join(cwd, "Package.swift"))) return "swift";
+  try {
+    if (readdirSync(cwd).some((f) => f.endsWith(".xcodeproj"))) return "swift";
+  } catch {
+    /* unreadable dir → ignore */
+  }
+  return "generic";
+}

package/src/policy/detect-framework.ts

@@ -0,0 +1,99 @@
+import { dirname, resolve } from "node:path";
+import { maskCommentsAndStrings } from "./conventions/strip";
+import { nearestManifestDir, projectCaps, type Cap } from "./nearest-manifest";
+
+/** File-derived signal: a definitive non-JS framework, or a JS-family hint. */
+interface FileSignal {
+  /** Definitive framework from extension/content (non-JS) — wins outright. */
+  definitive?: string;
+  /** JS-family hint needing project caps to confirm (react/nextjs/tanstack-start). */
+  jsHint?: "react" | "nextjs" | "tanstack-start";
+}
+
+/** react markers in a plain .ts/.js file (avoids TS-generic false positives). */
+const REACT_CONTENT = /from ['"]react['"]|\buse(State|Effect|Context|Ref|Memo|Callback|Reducer|LayoutEffect)\b|className=/;
+/** next.js markers in content. */
+const NEXT_CONTENT = /use client|use server|NextRequest|NextResponse|from ['"]next|getServerSideProps|getStaticProps/;
+/** next.js route-file conventions. */
+const NEXT_ROUTE = /(page|layout|loading|error|route|middleware)\.(ts|tsx|js|jsx)$/;
+/** TanStack Start markers (file routes, server fns, start/router imports). */
+const TANSTACK_CONTENT = /createFileRoute|createServerFn|from ['"]@tanstack\/react-(start|router)/;
+/**
+ * C7: Tailwind CSS-file signals, verified against official docs (v3 + v4) —
+ * `@tailwind` (v3 layer directive, removed in v4), `@apply` (both versions),
+ * `@config` (v3 native / v4 compat, JS config path), `@source` (v4 content
+ * globbing), `@theme` (v4 design-token block), `theme(` (the function, both
+ * versions' syntax). Deliberately NOT a bare utility-class-in-selector scan
+ * (e.g. `.flex{}`) — an ordinary hand-written class named `.flex` is exactly
+ * the false-positive shape this fix removes; only genuine Tailwind-specific
+ * at-rules/functions count.
+ */
+const TAILWIND_CSS_CONTENT = /@tailwind\b|@apply\b|@config\b|@source\b|@theme\b|\btheme\(/;
+
+/** Derive the raw signal an extension + content carry (no filesystem access). */
+function fileSignal(filePath: string, content: string): FileSignal {
+  if (/\.swift$/.test(filePath)) return { definitive: "swift" };
+  if (/\.php$/.test(filePath)) return { definitive: "laravel" };
+  if (/\.java$/.test(filePath)) return { definitive: "java" };
+  if (/\.go$/.test(filePath)) return { definitive: "go" };
+  if (/\.rb$/.test(filePath)) return { definitive: "ruby" };
+  if (/\.rs$/.test(filePath)) return { definitive: "rust" };
+  // C7: a .css file is "tailwind" only when its CONTENT shows it — bare
+  // extension used to classify EVERY .css as tailwind, forcing 6 unrelated
+  // skill reads on hand-written CSS. Empty content (file-size-scope.ts's
+  // caller) can never prove Tailwind usage, so it falls through to the
+  // JS-family checks below (all false for .css) and returns "generic" — the
+  // function's existing fail-open contract, not a special case. That caller
+  // never reaches here in practice: .css is already outside its
+  // FILE_SIZE_CODE_EXT scope, so this is inert there either way.
+  if (/\.css$/.test(filePath) && TAILWIND_CSS_CONTENT.test(content)) return { definitive: "tailwind" };
+  // JS branch: content signals ride MASKED content (a `// migrated from
+  // createServerFn pattern` comment must not flip nextjs → tanstack-start).
+  const masked = maskCommentsAndStrings(content, "c");
+  const isTs = TANSTACK_CONTENT.test(masked);
+  const isNext = !isTs && (NEXT_ROUTE.test(filePath) || NEXT_CONTENT.test(masked));
+  if (/\.(tsx|jsx)$/.test(filePath)) return { jsHint: isTs ? "tanstack-start" : isNext ? "nextjs" : "react" };
+  if (/\.(ts|js)$/.test(filePath)) {
+    if (isTs) return { jsHint: "tanstack-start" };
+    if (isNext) return { jsHint: "nextjs" };
+    if (REACT_CONTENT.test(masked)) return { jsHint: "react" };
+  }
+  return {};
+}
+
+/** Reconcile the JS signal against the project's REAL capabilities. */
+function reconcile(caps: Set<Cap>, hint: "react" | "nextjs" | "tanstack-start"): string {
+  const nextCap = caps.has("nextjs");
+  const reactCap = caps.has("react") || nextCap; // next always ships react at runtime
+  if (hint === "tanstack-start") {
+    return caps.has("tanstack-start") || caps.has("tanstack-router") ? "tanstack-start" : reactCap ? "react" : "generic";
+  }
+  if (hint === "nextjs") return nextCap ? "nextjs" : reactCap ? "react" : "generic";
+  return reactCap ? "react" : "generic";
+}
+
+/**
+ * Detect a file's framework as the intersection of the REAL project (its nearest
+ * manifest's capabilities) and the file's own extension/content signal. A
+ * backend `.ts` in a react project is `generic` (no react signal) — fixing the
+ * old extension-only default that flagged every `.ts` as react. Fail-open: any
+ * error yields `"generic"`, never throws. Return values stay within the label
+ * union ("react" | "nextjs" | "tanstack-start" | "laravel" | "swift" |
+ * "tailwind" | "java" | "go" | "ruby" | "rust" | "generic") — `tanstack-start`
+ * added 2026-07 (owner spec: first-class framework, Next.js-equivalent).
+ * @param filePath - Path of the file being written/edited.
+ * @param content - Its (incoming) content, for JS content signals.
+ * @param cwd - Root to resolve a relative `filePath` against (default cwd).
+ * @returns A framework label from the union.
+ */
+export function detectFramework(filePath: string, content: string, cwd: string = process.cwd()): string {
+  try {
+    const sig = fileSignal(filePath, content);
+    if (sig.definitive) return sig.definitive;
+    if (!sig.jsHint) return "generic";
+    const caps = projectCaps(nearestManifestDir(dirname(resolve(cwd, filePath))));
+    return reconcile(caps, sig.jsHint);
+  } catch {
+    return "generic";
+  }
+}

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