@fusengine/harness 0.1.28 → 0.1.30

package/dist/describe-CPtgUzFS.mjs

@@ -0,0 +1,1038 @@
+import { r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
+import { k as countLines } from "./evaluate-j3gRJ_ng.mjs";
+import { r as isDocConsulted, t as formatDocDeny } from "./doc-helpers-Dd_x1-tZ.mjs";
+import { t as routeReferences } from "./router-D8cVrI-s.mjs";
+import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+//#region src/policy/detect-project.ts
+/** Keywords that signal a development task (APEX trigger). */
+const DEV_KEYWORDS = /\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. */
+function isApexCommand(prompt) {
+	return /(?:^|\s)\/apex|\/fuse-ai-pilot:apex/i.test(prompt);
+}
+/**
+* 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.
+*/
+function detectModularArchitecture(dir) {
+	const has = (f) => 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.
+*/
+function requiredArchSkill(cwd) {
+	switch (detectModularArchitecture(cwd)) {
+		case "nextjs-modular": return "solid-nextjs";
+		case "fusecore": return "fusecore";
+		default: return null;
+	}
+}
+/** Detect the project type by scanning config files in `dir`. */
+function detectProjectType(dir) {
+	const has = (f) => 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 (has("tailwind.config.js") || has("tailwind.config.ts")) 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";
+}
+//#endregion
+//#region src/policy/apex.ts
+/** Gate: Context7 + Exa must have been consulted this session. */
+const docConsultedGate = (ctx) => isDocConsulted(ctx.authorizations, ctx.sessionId) ? null : {
+	kind: "block",
+	title: "APEX: documentation not consulted",
+	reason: formatDocDeny(ctx.framework),
+	actions: ["Call mcp__context7__query-docs", "Call mcp__exa__web_search_exa"]
+};
+/** Gate: the routed SOLID references for this edit must have been read. */
+const solidReadGate = (ctx) => {
+	if (!ctx.refs?.length) return null;
+	const routed = routeReferences(ctx.refs, ctx.filePath, ctx.content);
+	if (!routed) return null;
+	const read = new Set(ctx.refsRead ?? []);
+	const missing = routed.required.map((r) => r.meta.filePath).filter((p) => !read.has(p));
+	if (missing.length === 0) return null;
+	return {
+		kind: "block",
+		title: `APEX: read SOLID references for ${ctx.framework}`,
+		reason: `Read these before editing ${ctx.filePath}:`,
+		actions: missing
+	};
+};
+/** Gate: the required prior agents (explore + research) must have run within the window. */
+const freshnessGate = (ctx) => ctx.agentsFresh === false ? {
+	kind: "block",
+	title: "APEX: explore + research required",
+	reason: `Run explore-codebase and research-expert (within the freshness window) before editing ${ctx.framework}.`,
+	actions: ["Launch the explore-codebase agent", "Launch the research-expert agent"]
+} : null;
+/** Gate: brainstorming must precede creating new files when flagged. */
+const brainstormGate = (ctx) => ctx.brainstormRequired && ctx.brainstormFresh === false ? {
+	kind: "block",
+	title: "APEX: brainstorm first",
+	reason: `Creation intent detected — brainstorm before creating new ${ctx.framework} files.`,
+	actions: ["Launch the brainstorming agent"]
+} : null;
+/** Default APEX gate chain (brainstorm, freshness, docs, SOLID refs). */
+const APEX_GATES = [
+	brainstormGate,
+	freshnessGate,
+	docConsultedGate,
+	solidReadGate
+];
+/**
+* Run the APEX gates (chain-of-responsibility): the first failing gate's prompt
+* wins; null means every gate passed (allow).
+*/
+function evaluateApex(ctx, gates = APEX_GATES) {
+	return gates.reduce((hit, gate) => hit ?? gate(ctx), null);
+}
+//#endregion
+//#region src/policy/creation-intent.ts
+const CREATE_RE = /\b(?:create|implement|add|build|new|feature|component|generate|make|develop|scaffold)\b/i;
+const SKIP_RE = /\b(?:fix|bug|debug|update|refactor|rename|move|delete|remove|commit|push|edit|modify|change)\b/i;
+/**
+* True when a prompt expresses creation intent (a new feature/component) and is
+* not a fix/refactor — the signal that brainstorming should precede creation.
+* The harness calls this on UserPromptSubmit, then `recordBrainstormRequired`.
+*/
+function detectCreationIntent(prompt) {
+	return CREATE_RE.test(prompt) && !SKIP_RE.test(prompt);
+}
+//#endregion
+//#region src/policy/verbosity.ts
+/** Exa MCP tools whose result count + token budget are capped. */
+const EXA_TOOLS = /exa__web_search|exa__get_code_context|exa_web_search|exa_get_code_context/i;
+/** Context7 doc tool whose token budget is capped. */
+const CONTEXT7_TOOLS = /context7__query-docs|context7_query-docs|query-docs/i;
+/** Max results an exa MCP call may request. */
+const MAX_EXA_RESULTS = 3;
+/** Max token budget for exa `tokensNum` / context7 `tokens`. */
+const MAX_TOKENS = 2e3;
+/**
+* Cap an MCP call's verbosity — exa `numResults` ≤ 3 (+ `tokensNum` ≤ 2000),
+* Context7 `tokens` ≤ 2000. Returns the capped input (a mutation for the harness
+* to apply) when a change is needed, else null.
+*/
+function capVerbosity(tool, input) {
+	const out = { ...input };
+	let changed = false;
+	const cap = (key, max, force) => {
+		const v = out[key];
+		if (typeof v === "number" && v > max || force && typeof v !== "number") {
+			out[key] = max;
+			changed = true;
+		}
+	};
+	if (EXA_TOOLS.test(tool)) {
+		cap("numResults", 3, true);
+		cap("tokensNum", MAX_TOKENS, false);
+	} else if (CONTEXT7_TOOLS.test(tool)) cap("tokens", MAX_TOKENS, false);
+	return changed ? out : null;
+}
+//#endregion
+//#region src/policy/framework-solid-exclude.ts
+/** Build-output / dependency paths excluded from React/Next.js SOLID gating. */
+const JS_EXCLUDE_RE = /(node_modules|dist|build|\.next)/;
+/** Vendored dependency paths excluded from Laravel/PHP SOLID gating. */
+const PHP_EXCLUDE_RE = /\/vendor\//;
+/** Derived/build artifact paths excluded from Swift SOLID gating. */
+const SWIFT_EXCLUDE_RE = /(\.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
+*/
+function isExcludedJsPath(filePath) {
+	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
+*/
+function isExcludedPhpPath(filePath) {
+	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
+*/
+function isExcludedSwiftPath(filePath) {
+	return SWIFT_EXCLUDE_RE.test(filePath);
+}
+//#endregion
+//#region src/policy/framework-solid-gates.ts
+/** Custom hook export (React): `export function/const use[A-Z]`. */
+const HOOK_RE = /^export (function|const) use[A-Z]/m;
+/** Top-level TS interface/type declaration. */
+const TS_DECL_RE = /^(export )?(interface|type) [A-Z]/m;
+/** Client-only React hooks that require the `'use client'` directive. */
+const CLIENT_HOOK_RE = /(useState|useEffect|useRef|onClick|onChange)/;
+/** PHP top-level `interface` declaration. */
+const PHP_INTERFACE_RE = /^interface /m;
+/** Swift top-level `protocol` declaration. */
+const SWIFT_PROTOCOL_RE = /^protocol /m;
+/** Swift type declaration (`class`/`struct`) opening a body. */
+const SWIFT_TYPE_RE = /^(class|struct) [^\n{]* \{/m;
+/** React: line limit, interface separation, custom hooks under `/hooks/`. */
+function reactGate(filePath, content, fileLines) {
+	const v = [];
+	const max = resolveMaxLines();
+	const lines = fileLines ?? countLines(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)) v.push("Interface/type in component. Move to src/interfaces/ or src/types/.");
+	if (HOOK_RE.test(content) && !filePath.includes("/hooks/")) v.push("Custom hook defined outside hooks/ directory. Move to hooks/.");
+	return v;
+}
+/** Next.js: adaptive line limit, interface separation, `'use client'`. */
+function nextGate(filePath, content, fileLines) {
+	const v = [];
+	const max = /(page|layout|loading|error|not-found)\.(tsx|ts)$/.test(filePath) ? 150 : 100;
+	const lines = fileLines ?? countLines(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)) v.push("Interface/type in component. Move to modules/[feature]/src/interfaces/.");
+	if (CLIENT_HOOK_RE.test(content)) {
+		const head = content.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). */
+function laravelGate(filePath, content, fileLines) {
+	const v = [];
+	const lines = fileLines ?? countLines(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/")) v.push("Interface defined outside Contracts/. Move to app/Contracts/ or FuseCore/{Module}/App/Contracts/.");
+	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. */
+function swiftGate(filePath, content, fileLines) {
+	const v = [];
+	const max = /(View|Screen)\.swift$/.test(filePath) ? 150 : 100;
+	const lines = fileLines ?? countLines(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/")) v.push("Protocol defined outside Protocols/ directory.");
+	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;
+}
+//#endregion
+//#region src/policy/framework-solid.ts
+/** Next.js detection: directive, runtime types, or a `next` import. */
+const NEXT_RE = /(use client|use server|NextRequest|NextResponse|from ['"]next)/;
+/** Build a SOLID `block` prompt from one or more violation messages. */
+function block(filePath, violations) {
+	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, content, fileLines) {
+	if (isExcludedJsPath(filePath)) return [];
+	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) 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.
+* @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.
+*/
+function frameworkSolidGate(filePath, content, fileLines) {
+	if (!filePath || !content) return null;
+	let violations = [];
+	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);
+	return violations.length ? block(filePath, violations) : null;
+}
+//#endregion
+//#region src/policy/skill-patterns/shadcn.ts
+/**
+* shadcn/ui HTML-to-component detection patterns, ported verbatim from the
+* shared `shadcn_patterns.py` (FORM/OVERLAY/DATA/NAV/LAYOUT/FEEDBACK groups).
+* 32 patterns total (3+6+8+5+5+5). Matched case-insensitively (source `re.IGNORECASE`).
+*/
+/** Forms: Button, Input, Textarea, Select, Checkbox, Radio, Switch, etc. */
+const FORM = [
+	"<(button|input|select|textarea|label|option|optgroup)\\b",
+	"type=\"(checkbox|radio|range|file)\"",
+	"<input[^>]*maxLength=\"[1-2]\""
+];
+/** Overlay: Dialog, AlertDialog, Sheet, Popover, Tooltip, ContextMenu, etc. */
+const OVERLAY = [
+	"<dialog\\b",
+	"role=\"(dialog|alertdialog)\"",
+	"(aria-haspopup|aria-expanded|aria-pressed)=\"",
+	"(onContextMenu|onMouseEnter.*onMouseLeave)\\b",
+	"\\b(confirm|window\\.confirm)\\(",
+	"title=\"[^\"]{2,}\""
+];
+/** Data: Table, Card, Badge, Avatar, Calendar, Chart, Carousel, Pagination. */
+const DATA = [
+	"<(table|thead|tbody|tfoot|th|td|tr|caption|colgroup)\\b",
+	"<(article|section)\\b[^>]*className",
+	"rounded-full[^>]*className|className[^>]*rounded-full",
+	"<img\\b[^>]*rounded",
+	"(new Date|\\.toLocaleDateString|date-fns|dayjs)\\b",
+	"(recharts|chart\\.js|<svg[^>]*viewBox)",
+	"(scroll-snap|embla-carousel|useEmbla)\\b",
+	"(page=|currentPage|totalPages|pageSize)\\b"
+];
+/** Navigation: Breadcrumb, NavigationMenu, Menubar, Sidebar, Tabs. */
+const NAV = [
+	"<(nav|aside)\\b",
+	"<(menu|menuitem)\\b",
+	"role=\"(menubar|menu|menuitem|tablist|tab|tabpanel)\"",
+	"aria-label=\"(breadcrumb|navigation|sidebar)\"",
+	"aria-current=\"(page|step)\""
+];
+/** Layout: Accordion, Collapsible, Separator, ScrollArea, AspectRatio. */
+const LAYOUT = [
+	"<(hr|details|summary)\\b",
+	"role=\"separator\"",
+	"overflow-(auto|scroll|y-auto|x-auto)",
+	"(aspect-ratio|aspect-video|aspect-square)\\b",
+	"(resize|cursor-(col|row)-resize)\\b"
+];
+/** Feedback: Alert, Toast, Progress, Skeleton, Spinner. */
+const FEEDBACK = [
+	"role=\"(alert|status|progressbar)\"",
+	"aria-live=\"(polite|assertive)\"",
+	"<progress\\b",
+	"(animate-pulse|animate-spin)\\b",
+	"(sonner|react-hot-toast|\\.toast\\()\\b"
+];
+/** All 32 shadcn detection patterns combined. */
+const SHADCN = [
+	...FORM,
+	...OVERLAY,
+	...DATA,
+	...NAV,
+	...LAYOUT,
+	...FEEDBACK
+];
+//#endregion
+//#region src/policy/skill-patterns/react.ts
+/**
+* React skill-trigger patterns, ported verbatim from `react_skill_triggers.py`.
+* Matched case-insensitively (source `re.IGNORECASE`).
+*/
+/** Map of React sub-skill name → triggering code patterns. */
+const REACT_TRIGGERS = {
+	"react-19": [
+		"\\buse\\b\\s*\\(",
+		"useOptimistic\\b",
+		"useActionState\\b",
+		"useEffectEvent\\b",
+		"<Activity\\b",
+		"from\\s+['\"]react['\"]"
+	],
+	"react-tanstack-router": [
+		"(createRouter|createRoute|createRootRoute)\\b",
+		"(useNavigate|useParams|useSearch|useLoaderData)\\b",
+		"from\\s+['\"]@tanstack/(react-router|router)",
+		"(routeTree|createFileRoute|createLazyFileRoute)\\b"
+	],
+	"react-forms": [
+		"(useForm|useAppForm|createFormHook|formOptions)\\b",
+		"(mergeForm|formApi|FieldApi|FormApi)\\b",
+		"form\\.(Field|Subscribe|handleSubmit)\\b",
+		"from\\s+['\"]@tanstack/(react-form|zod-form-adapter)"
+	],
+	"react-state": [
+		"(create|createStore)\\(\\s*\\(\\s*set",
+		"from\\s+['\"]zustand(/\\w+)?\"",
+		"(useShallow|useStore|skipHydration)\\b",
+		"(persist|devtools|immer)\\("
+	],
+	"react-testing": [
+		"(render|screen|fireEvent|waitFor)\\b",
+		"from\\s+['\"]@testing-library/react",
+		"(describe|it|expect|vi\\.|jest\\.)\\b",
+		"from\\s+['\"]vitest"
+	],
+	"react-shadcn": SHADCN,
+	"react-i18n": [
+		"(useTranslation|Trans)\\b",
+		"from\\s+['\"]react-i18next",
+		"\\bt\\(\\s*['\"]",
+		"i18n\\.(language|changeLanguage)"
+	]
+};
+//#endregion
+//#region src/policy/skill-patterns/nextjs.ts
+/**
+* Next.js skill-trigger patterns, ported verbatim from `nextjs_skill_triggers.py`.
+* Matched case-insensitively (source `re.IGNORECASE`).
+*/
+/** Map of Next.js sub-skill name → triggering code patterns. */
+const NEXTJS_TRIGGERS = {
+	"better-auth": [
+		"(authClient|betterAuth|createAuthClient)\\b",
+		"(signIn|signUp|signOut|useSession|getSession)\\b",
+		"auth\\.(api|handler)\\b",
+		"(prismaAdapter|drizzleAdapter|mongodbAdapter)\\b",
+		"(twoFactor|passkey|magicLink|emailOtp|organization)\\b",
+		"(apiKey|bearer|jwt|sso|scim|captcha|anonymous)\\b",
+		"from\\s+['\"].*better-auth"
+	],
+	"nextjs-tanstack-form": [
+		"(useForm|useAppForm|createFormHook|formOptions)\\b",
+		"(mergeForm|formApi|FieldApi|FormApi)\\b",
+		"form\\.(Field|Subscribe|handleSubmit)\\b",
+		"(zodValidator|onServerValidate)\\b",
+		"from\\s+['\"]@tanstack/(react-form|zod-form-adapter)"
+	],
+	"prisma-7": [
+		"(PrismaClient|prismaAdapter)\\b",
+		"prisma\\.(\\w+\\.\\w+|\\$\\w+)",
+		"(globalForPrisma|\\$transaction|\\$queryRaw|\\$executeRaw)\\b",
+		"from\\s+['\"](@prisma|\\..*generated.*prisma)"
+	],
+	"nextjs-shadcn": SHADCN,
+	"nextjs-zustand": [
+		"(create|createStore)\\(\\s*\\(\\s*set",
+		"from\\s+['\"]zustand(/\\w+)?\"",
+		"(useShallow|useStore|skipHydration)\\b",
+		"\\.(getState|setState|subscribe)\\(\\)",
+		"(persist|devtools|immer)\\("
+	],
+	"nextjs-i18n": [
+		"(useTranslations|useLocale|useMessages|useFormatter)\\b",
+		"(getTranslations|getLocale|getMessages|getFormatter)\\b",
+		"(NextIntlClientProvider|defineRouting)\\b",
+		"from\\s+['\"]next-intl(/\\w+)?\"",
+		"\\bt\\(\\s*['\"]"
+	]
+};
+//#endregion
+//#region src/policy/skill-patterns/laravel.ts
+/**
+* Laravel skill-trigger patterns, ported verbatim from `laravel_patterns.py`
+* (consumed by `laravel_skill_triggers.py`). Matched case-insensitively.
+*/
+/** Map of Laravel sub-skill name → triggering PHP code patterns. */
+const LARAVEL_TRIGGERS = {
+	"fusecore": [
+		"FuseCore\\\\[A-Za-z]+\\\\App\\\\",
+		"use HasModule\\b",
+		"ModuleServiceProvider\\b",
+		"ModuleInterface\\b"
+	],
+	"laravel-eloquent": [
+		"(extends Model|HasFactory|belongsTo|hasMany|hasOne|morphTo)\\b",
+		"\\$this->belongsToMany|->with\\(|->whereHas\\(",
+		"(Eloquent|Model)::(find|where|create|update|all)\\b"
+	],
+	"laravel-api": [
+		"(JsonResource|ResourceCollection|apiResource)\\b",
+		"Route::(get|post|put|delete|apiResource)\\(",
+		"(response\\(\\)->json|Request \\$request)\\b"
+	],
+	"laravel-auth": [
+		"(Auth::|auth\\(\\)|Sanctum|Passport|Socialite)\\b",
+		"(Gate::|Policy|can\\(|authorize)\\b",
+		"(middleware\\(['\"]auth|LoginController|RegisterController)\\b"
+	],
+	"laravel-livewire": [
+		"(extends Component|Livewire|wire:|#\\[On)\\b",
+		"(mount|render|emit|dispatch)\\(\\)",
+		"@livewire|<livewire:"
+	],
+	"laravel-queues": [
+		"(implements ShouldQueue|dispatch\\(|Bus::)\\b",
+		"(Queue::|Job|Batch|Chain)\\b",
+		"(onQueue|onConnection|tries|backoff)\\b"
+	],
+	"laravel-billing": ["(Billable|subscription|Cashier)\\b", "(createSubscription|newSubscription|charge)\\("],
+	"laravel-stripe-connect": [
+		"(StripeConnect|connectAccount|onboardingUrl)\\b",
+		"(paymentIntent|transfer|payout|splitPayment)\\b",
+		"Stripe\\\\\\\\(Account|Transfer|PaymentIntent)\\b"
+	],
+	"laravel-testing": [
+		"(extends TestCase|RefreshDatabase|WithFaker)\\b",
+		"(assertStatus|assertJson|assertSee|assertRedirect)\\(",
+		"(factory\\(|Pest|it\\(|test\\(|expect\\()\\b"
+	],
+	"laravel-migrations": [
+		"(Schema::|Blueprint|->table|->create)\\b",
+		"(->string|->integer|->boolean|->foreignId|->index)\\(",
+		"extends Migration\\b"
+	],
+	"laravel-blade": [
+		"(@extends|@section|@yield|@component|@slot)\\b",
+		"(@if|@foreach|@include|@push|@stack)\\b",
+		"(Blade::|x-[a-z])\\b"
+	],
+	"laravel-permission": [
+		"(hasRole|givePermissionTo|assignRole|spatie)\\b",
+		"(Permission|Role)::(create|findByName)\\b",
+		"@can\\b|@role\\b|middleware.*role:"
+	],
+	"laravel-i18n": ["(__\\(|trans\\(|trans_choice\\(|@lang)\\b", "Lang::|->locale\\(|setLocale\\b"],
+	"laravel-vite": ["(@vite|@viteReactRefresh|Vite::)\\b"]
+};
+//#endregion
+//#region src/policy/skill-patterns/swift.ts
+/**
+* Swift / Apple skill-trigger patterns, ported verbatim from
+* `swift_skill_triggers.py`. 9 skills.
+*
+* NOTE: Swift uses case-SENSITIVE matching (source `re.search` WITHOUT
+* `re.IGNORECASE`). The framework name is registered in
+* `CASE_SENSITIVE_FRAMEWORKS` so the gate compiles these without the `i` flag.
+*/
+/** Map of Swift sub-skill name → triggering code patterns (case-sensitive). */
+const SWIFT_TRIGGERS = {
+	"swiftui-core": [
+		"\\bstruct\\s+\\w+\\s*:\\s*View\\b",
+		"@State\\b",
+		"@Binding\\b",
+		"@Observable\\b",
+		"@Environment\\b",
+		"NavigationStack\\b",
+		"\\.sheet\\b",
+		"\\.toolbar\\b",
+		"\\.task\\b"
+	],
+	"swift-core": [
+		"\\bactor\\b",
+		"\\basync\\s+(let|func|throws)\\b",
+		"\\bawait\\b",
+		"Task\\s*\\{",
+		"TaskGroup\\b",
+		"Sendable\\b",
+		"@MainActor\\b"
+	],
+	"ios": [
+		"UIKit|UIViewController|UIView\\b",
+		"UIApplication\\b",
+		"\\.simulatorId\\b",
+		"import\\s+UIKit\\b"
+	],
+	"macos": [
+		"AppKit|NSViewController|NSWindow\\b",
+		"NSApplication\\b",
+		"\\.menuBar\\b",
+		"import\\s+AppKit\\b"
+	],
+	"watchos": [
+		"WatchKit|WKInterface|WKExtension\\b",
+		"HealthKit|HKWorkout\\b",
+		"WatchConnectivity\\b"
+	],
+	"visionos": [
+		"RealityKit|RealityView|ImmersiveSpace\\b",
+		"\\.volumeBaseplateVisibility\\b",
+		"SpatialTapGesture\\b"
+	],
+	"ipados": [
+		"UISplitViewController|UIKeyCommand\\b",
+		"\\.horizontalSizeClass\\b",
+		"pencilInteraction\\b"
+	],
+	"tvos": [
+		"TVUIKit|focusable\\b",
+		"\\.focusSection\\b",
+		"TVMonogram\\b"
+	],
+	"build-distribution": [
+		"TestFlight|AppStore\\b",
+		"\\.entitlements\\b",
+		"codesign|notarize|archive\\b"
+	]
+};
+//#endregion
+//#region src/policy/skill-trigger-patterns.ts
+/**
+* Per-framework code-pattern → required sub-skill data, ported verbatim from the
+* fusengine `*_skill_triggers.py` + `*_patterns.py`
+* (react/nextjs/laravel/swift) and the shared `shadcn_patterns.py`.
+*
+* Pattern groups live in `./skill-patterns/*`. Most frameworks match
+* case-insensitively (source `re.IGNORECASE`); `swift` matches case-SENSITIVELY
+* (source `re.search` without the flag) — see {@link CASE_SENSITIVE_FRAMEWORKS}.
+*/
+/**
+* Frameworks whose Python source omits `re.IGNORECASE`, so their regexes must
+* be compiled WITHOUT the `i` flag to stay faithful.
+*/
+const CASE_SENSITIVE_FRAMEWORKS = /* @__PURE__ */ new Set(["swift"]);
+/** Map of required sub-skill name → triggering code patterns, keyed by framework. */
+const SKILL_TRIGGERS = {
+	react: REACT_TRIGGERS,
+	nextjs: NEXTJS_TRIGGERS,
+	laravel: LARAVEL_TRIGGERS,
+	swift: SWIFT_TRIGGERS
+};
+//#endregion
+//#region src/policy/shadcn-project.ts
+/** Directories whose presence indicates shadcn/ui is installed. */
+const UI_DIRS = [
+	"src/components/ui",
+	"components/ui",
+	"src/modules/cores/shadcn/components/ui"
+];
+/**
+* Whether `cwd` is a shadcn/ui project, ported from the shared Python
+* `is_shadcn_project` (`shadcn_patterns.py`): true when a `components.json`
+* file exists, or any known `components/ui` directory exists under the root.
+* Used to skip `*-shadcn` sub-skill requirements when shadcn is not installed.
+* @param cwd - project root directory to scan.
+* @returns `true` when shadcn/ui is detected on disk.
+*/
+function isShadcnProject(cwd) {
+	if (existsSync(join(cwd, "components.json"))) return true;
+	return UI_DIRS.some((dir) => existsSync(join(cwd, dir)));
+}
+//#endregion
+//#region src/policy/skill-triggers.ts
+/**
+* Detect which sub-skills the written `content` requires for a `framework`.
+* Faithful to the Python `detect_required_skills`: first matching pattern per
+* skill wins. Most frameworks match case-insensitively (source `re.IGNORECASE`);
+* `swift` matches case-sensitively (see {@link CASE_SENSITIVE_FRAMEWORKS}).
+* @param framework - "react" | "nextjs" | "laravel" | "swift".
+* @param content - the code being written.
+* @returns required sub-skill names (empty when framework unknown / no match).
+*/
+function detectRequiredSkills(framework, content) {
+	const groups = SKILL_TRIGGERS[framework];
+	if (!groups) return [];
+	const flags = CASE_SENSITIVE_FRAMEWORKS.has(framework) ? "" : "i";
+	const required = [];
+	for (const [skill, patterns] of Object.entries(groups)) if (patterns.some((p) => new RegExp(p, flags).test(content))) required.push(skill);
+	return required;
+}
+/**
+* Block when a required sub-skill's `skills/<name>/` path is absent from
+* `refsRead`. Mirrors `specific_skill_consulted`, which confirms a skill was
+* read by checking the tracking file contains `skills/<name>/`.
+* @param framework - "react" | "nextjs" | "laravel".
+* @param content - the code being written.
+* @param refsRead - in-session read reference paths.
+* @param forcedSkill - a skill the detected modular architecture forces (optional).
+* @param cwd - project root; when set and not a shadcn project, `*-shadcn`
+*   requirements are skipped (ports the Python `is_shadcn_project` filter).
+* @returns a `block` Prompt naming the missing sub-skills, or `null` when satisfied.
+*/
+function skillTriggerGate(framework, content, refsRead, forcedSkill, cwd) {
+	let required = detectRequiredSkills(framework, content);
+	if (forcedSkill && !required.includes(forcedSkill)) required.push(forcedSkill);
+	if (cwd && !isShadcnProject(cwd)) required = required.filter((s) => !s.endsWith("-shadcn"));
+	const missing = required.filter((s) => !refsRead.some((r) => r.includes(`skills/${s}/`)));
+	if (missing.length === 0) return null;
+	return {
+		kind: "block",
+		title: "Required sub-skill not consulted",
+		reason: `${framework}: code uses APIs covered by ${missing.join(", ")} but its skill reference was not read this session.`,
+		actions: missing.map((s) => `Read skills/${s}/ before writing this code`)
+	};
+}
+//#endregion
+//#region src/policy/claude-md-context.ts
+/** Dev-verb regex (FR/EN) that triggers the APEX preamble (case-insensitive). */
+const DEV_VERBS = /(cr[ée]er|impl[ée]menter|ajouter|d[ée]velopper|construire|build|refactor|migrer|implement|create|add|develop)/i;
+/**
+* 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.
+*/
+function detectClaudeMdProjectType(cwd) {
+	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 {}
+	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 {}
+	return "generic";
+}
+/**
+* Build the APEX instruction preamble for a development task.
+* @param projectType - Detected project type label.
+* @param maxLines - SOLID per-file line ceiling.
+* @returns The APEX instruction text.
+*/
+function buildApexInstruction(projectType, maxLines) {
+	return `INSTRUCTION: This is a development task. Use APEX methodology:
+
+**TRACKING FILE**: [project]/.claude/apex/task.json
+
+1. **ANALYZE** (3 AGENTS IN PARALLEL):
+   - explore-codebase + research-expert + general-purpose
+   - Project type: ${projectType}\n\n2. **PLAN**: TaskCreate (<${maxLines} lines per file)\n\n3. **EXECUTE**: ${projectType}-expert, SOLID principles\n\n4. **EXAMINE**: Run sniper agent after ANY modification`;
+}
+/**
+* Build the UserPromptSubmit injection text: read `~/.claude/CLAUDE.md` and,
+* when the prompt matches a dev verb, prepend the APEX instruction. Returns
+* `null` when CLAUDE.md is absent/unreadable (the hook then emits nothing).
+* @param prompt - The raw user prompt.
+* @param cwd - Project root (for project-type detection).
+* @returns The injection text, or `null` to emit nothing.
+*/
+function buildClaudeMdContext(prompt, cwd) {
+	const claudeMd = join(homedir(), ".claude", "CLAUDE.md");
+	if (!existsSync(claudeMd)) return null;
+	let claudeContent;
+	try {
+		claudeContent = readFileSync(claudeMd, "utf-8");
+	} catch {
+		return null;
+	}
+	if (!DEV_VERBS.test(prompt)) return `# CLAUDE.md\n${claudeContent}`;
+	return `${buildApexInstruction(detectClaudeMdProjectType(cwd), resolveMaxLines())}\n\n# CLAUDE.md\n${claudeContent}`;
+}
+//#endregion
+//#region src/policy/apex-task-context.ts
+/**
+* Read the current task state from `task.json`, reproducing the legacy Python
+* logic. Any read/parse error falls back to `("1", "", "analyze", "none")`.
+* @param taskFile - Absolute path to `.claude/apex/task.json`.
+* @returns The parsed {@link ApexTaskState}.
+*/
+function loadApexTaskState(taskFile) {
+	try {
+		const data = JSON.parse(readFileSync(taskFile, "utf-8"));
+		const id = String(data.current_task ?? "1");
+		const task = (data.tasks ?? {})[id] ?? {};
+		const subject = typeof task.subject === "string" ? task.subject : "";
+		const phase = typeof task.phase === "string" ? task.phase : "analyze";
+		const consultedMap = task.doc_consulted ?? {};
+		return {
+			id,
+			subject,
+			phase,
+			docs: Object.entries(consultedMap).filter(([, v]) => typeof v === "object" && v !== null && v.consulted === true).map(([k]) => k).join(", ") || "none"
+		};
+	} catch {
+		return {
+			id: "1",
+			subject: "",
+			phase: "analyze",
+			docs: "none"
+		};
+	}
+}
+/**
+* Build the APEX context string injected into a Task sub-agent prompt.
+* @param state - The parsed task state.
+* @param maxLines - SOLID per-file line ceiling.
+* @returns The injection text.
+*/
+function buildApexTaskContext(state, maxLines) {
+	return `⚠️ APEX MODE - Read .claude/apex/AGENTS.md for rules\n\nCurrent: Task #${state.id} - ${state.subject} (Phase: ${state.phase})\nDocs consulted: ${state.docs}\n\nAgent must:\n1. Read task.json → find last 3 completed tasks\n2. Read their notes in docs/ (task-{ID}-{subject}.md)\n3. TaskList → see pending tasks\n4. TaskUpdate(in_progress) → before starting\n5. Apply SOLID (files < ${maxLines} lines)\n6. Write notes to docs/task-{ID}-{subject}.md\n7. TaskUpdate(completed) → triggers auto-commit`;
+}
+/**
+* Build the PreToolUse Task injection, gated on the existence of the project's
+* `.claude/apex/` directory. Returns `null` when APEX is not active (no dir).
+* @param projectRoot - `CLAUDE_PROJECT_DIR` or cwd.
+* @returns The injection text, or `null` to emit nothing.
+*/
+function buildApexTaskInjection(projectRoot) {
+	const apexDir = join(projectRoot, ".claude", "apex");
+	if (!existsSync(apexDir)) return null;
+	return buildApexTaskContext(loadApexTaskState(join(apexDir, "task.json")), resolveMaxLines());
+}
+//#endregion
+//#region src/policy/cartographer/indicators.ts
+/**
+* Cartographer indicators — pure data sets used to detect a project root and to
+* exclude noise directories when walking a tree. Ports the constant tables from
+* `generate_project_map.py` / `write_recursive.py`.
+*/
+/** Filenames whose presence marks a directory as a project root. */
+const PROJECT_INDICATORS = /* @__PURE__ */ new Set([
+	"package.json",
+	"deno.json",
+	"bun.lockb",
+	"bun.lock",
+	"tsconfig.json",
+	"package-lock.json",
+	"yarn.lock",
+	"pnpm-lock.yaml",
+	"pnpm-workspace.yaml",
+	"composer.json",
+	"artisan",
+	"Cargo.toml",
+	"rust-toolchain.toml",
+	"go.mod",
+	"pyproject.toml",
+	"setup.py",
+	"setup.cfg",
+	"Pipfile",
+	"requirements.txt",
+	"environment.yml",
+	"Gemfile",
+	"Package.swift",
+	"Podfile",
+	"pubspec.yaml",
+	"pom.xml",
+	"build.gradle",
+	"build.gradle.kts",
+	"settings.gradle",
+	"build.sbt",
+	"Makefile",
+	"CMakeLists.txt",
+	"meson.build",
+	"configure.ac",
+	"Directory.Build.props",
+	"global.json",
+	"mix.exs",
+	"rebar.config",
+	"project.clj",
+	"deps.edn",
+	"stack.yaml",
+	"cabal.project",
+	"dune-project",
+	"build.zig",
+	"gleam.toml",
+	"v.mod",
+	"Project.toml",
+	"DESCRIPTION",
+	"cpanfile",
+	"Makefile.PL",
+	".luacheckrc",
+	"astro.config.mjs",
+	"next.config.js",
+	"next.config.mjs",
+	"nuxt.config.ts",
+	"vite.config.ts",
+	"next.config.ts",
+	"angular.json",
+	"svelte.config.js",
+	"svelte.config.ts",
+	"main.tf",
+	"ansible.cfg",
+	"pulumi.yaml",
+	"cdk.json",
+	"Chart.yaml",
+	"wrangler.toml",
+	"fly.toml",
+	"turbo.json",
+	"nx.json",
+	"BUILD",
+	"WORKSPACE",
+	"Justfile",
+	"Taskfile.yml",
+	"docker-compose.yml",
+	"docker-compose.yaml",
+	"compose.yml",
+	"compose.yaml",
+	"Dockerfile",
+	".git"
+]);
+/** Directory names skipped entirely during the tree walk. */
+const EXCLUDE_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	".next",
+	".nuxt",
+	"dist",
+	"build",
+	".output",
+	"vendor",
+	"__pycache__",
+	".venv",
+	"venv",
+	".cartographer",
+	".claude",
+	".ruff_cache",
+	".DS_Store",
+	"coverage",
+	".turbo",
+	".vercel",
+	".netlify",
+	"Pods",
+	"DerivedData",
+	".build",
+	".swiftpm"
+]);
+//#endregion
+//#region src/policy/cartographer/frontmatter.ts
+/**
+* Frontmatter parsing — pure text helpers (no fs). Ports `parse_frontmatter.py`.
+*/
+const BLOCK_SCALARS = /* @__PURE__ */ new Set([
+	"|",
+	">",
+	"|+",
+	"|-",
+	">+",
+	">-"
+]);
+/** Escape regex metacharacters in an arbitrary field name. */
+function escapeRe(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Extract a single frontmatter field's value from `text`. Strips surrounding
+* quotes; skips YAML block-scalar markers. Returns "" when absent.
+* @param text - The full document text.
+* @param field - The frontmatter key to read.
+* @returns The field value, or "".
+*/
+function parseField(text, field) {
+	const fm = /^---\s*\n([\s\S]*?)\n---/.exec(text);
+	if (!fm || fm[1] === void 0) return "";
+	const lineRe = new RegExp(`^${escapeRe(field)}\\s*:\\s*(.+)$`);
+	for (const line of fm[1].split("\n")) {
+		const m = lineRe.exec(line);
+		if (!m || m[1] === void 0) continue;
+		const val = m[1].trim().replace(/^["']|["']$/g, "");
+		if (BLOCK_SCALARS.has(val)) continue;
+		return val;
+	}
+	return "";
+}
+/**
+* Derive a short description from the body following the frontmatter: the first
+* non-empty trimmed line, sliced to `maxLen`. Returns "" when none.
+* @param text - The full document text.
+* @param maxLen - Maximum length of the returned description.
+* @returns The body-derived description, or "".
+*/
+function parseBodyDesc(text, maxLen = 60) {
+	const m = /^---\s*\n[\s\S]*?\n---\s*\n([\s\S]*)/.exec(text);
+	if (!m || m[1] === void 0) return "";
+	for (const raw of m[1].split("\n")) {
+		const line = raw.trim();
+		if (line) return line.slice(0, maxLen);
+	}
+	return "";
+}
+//#endregion
+//#region src/policy/cartographer/entry.ts
+const ENTRY_RE = /^(.*?)\[([^\]]+)\]\(([^)]+)\)\s*(?:—|-{1,2})\s*(.*)$/;
+const ENRICH_RE = /^(?:.*?)\[([^\]]+)\]\(([^)]+)\)\s*(?:—|-{1,2})\s*(.+)$/;
+/**
+* Parse a `merge_index` tree line into its parts. Returns null on no match.
+* @param line - The raw tree line.
+* @returns The parsed entry, or null.
+*/
+function parseEntry(line) {
+	const m = ENTRY_RE.exec(line);
+	if (!m || m[1] === void 0 || m[2] === void 0 || m[3] === void 0 || m[4] === void 0) return null;
+	return {
+		prefix: m[1],
+		name: m[2],
+		path: m[3],
+		desc: m[4]
+	};
+}
+/**
+* Parse an enrichment line into `[path, desc]`, requiring a non-empty desc.
+* @param line - The raw index line.
+* @returns The `[path, desc]` pair, or null.
+*/
+function parseEnrichment(line) {
+	const m = ENRICH_RE.exec(line);
+	if (!m || m[2] === void 0 || m[3] === void 0) return null;
+	const desc = m[3].trim();
+	return desc ? [m[2], desc] : null;
+}
+//#endregion
+//#region src/policy/cartographer/describe.ts
+/**
+* File-description heuristics — pure text in, description out (no fs). Ports
+* `describe.py`.
+*/
+const SOURCE_SUFFIXES = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".py",
+	".swift"
+]);
+/**
+* First `# ` Markdown heading text (sans hashes), sliced to 60. "" when none.
+* @param text - The document text.
+* @returns The heading text, or "".
+*/
+function firstHeading(text) {
+	for (const line of text.split("\n")) if (line.startsWith("# ")) return line.replace(/^#+/, "").trim().slice(0, 60);
+	return "";
+}
+/**
+* First leading comment among the first 10 lines (`//`, `#` but not `#!`, or a
+* `"""`/`'''` docstring), sliced to 60. "" when none.
+* @param text - The source text.
+* @returns The comment text, or "".
+*/
+function firstComment(text) {
+	const lines = text.split("\n").slice(0, 10);
+	for (const raw of lines) {
+		const line = raw.trim();
+		if ((line.startsWith("//") || line.startsWith("#")) && !line.startsWith("#!")) return line.replace(/^[/#! ]+/, "").slice(0, 60);
+		if (line.startsWith("\"\"\"") || line.startsWith("'''")) return line.replace(/^['"\s]+|['"\s]+$/g, "").slice(0, 60);
+	}
+	return "";
+}
+/**
+* Derive a description from a file's suffix + text. For `.md`, the supplied
+* frontmatter `description` (truncated) wins over the first heading; for known
+* source suffixes, the first comment; else "".
+* @param suffix - The file extension (with dot).
+* @param text - The file text.
+* @param mdField - The pre-parsed frontmatter `description` (md only).
+* @returns The derived description, or "".
+*/
+function descFromText(suffix, text, mdField) {
+	if (suffix === ".md") return mdField.slice(0, 60) || firstHeading(text);
+	if (SOURCE_SUFFIXES.has(suffix)) return firstComment(text);
+	return "";
+}
+//#endregion
+export { solidReadGate as A, capVerbosity as C, docConsultedGate as D, brainstormGate as E, requiredArchSkill as F, detectModularArchitecture as M, detectProjectType as N, evaluateApex as O, isApexCommand as P, MAX_TOKENS as S, APEX_GATES as T, detectRequiredSkills as _, parseEntry as a, frameworkSolidGate as b, EXCLUDE_DIRS as c, buildApexTaskInjection as d, loadApexTaskState as f, detectClaudeMdProjectType as g, buildClaudeMdContext as h, parseEnrichment as i, DEV_KEYWORDS as j, freshnessGate as k, PROJECT_INDICATORS as l, buildApexInstruction as m, firstComment as n, parseBodyDesc as o, DEV_VERBS as p, firstHeading as r, parseField as s, descFromText as t, buildApexTaskContext as u, skillTriggerGate as v, detectCreationIntent as w, MAX_EXA_RESULTS as x, SKILL_TRIGGERS as y };