@fusengine/harness 0.1.43 → 0.1.45

package/dist/{validate-xi-zc-22.mjs → validate-DcQaKzau.mjs}

@@ -1,9 +1,11 @@
 import { r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
-import { j as countLines } from "./evaluate-CeivW6G0.mjs";
-import { r as isDocConsulted, t as formatDocDeny } from "./doc-helpers-BhzDmJ18.mjs";
-import { t as routeReferences } from "./router-BfX0hJg8.mjs";
-import { join } from "node:path";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { c as ttlLabel, t as HOME_DIR } from "./dotenv-B9nM4cuQ.mjs";
+import { t as detectHarness } from "./harness-C8Nxxyn_.mjs";
+import { F as countFrameworkCodeLines, N as PLUGINS_DIR, P as SOLID_REF } from "./evaluate-d7Pp8XJH.mjs";
+import { r as isDocConsulted, t as formatDocDeny } from "./doc-helpers-CWZegVdR.mjs";
+import { t as routeReferences } from "./router-PKVNBHge.mjs";
+import { extname, join } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 //#region src/policy/detect-project.ts
 /** Keywords that signal a development task (APEX trigger). */
@@ -41,6 +43,27 @@ function requiredArchSkill(cwd) {
 		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) {
+	const pkgPath = join(dir, "package.json");
+	if (!existsSync(pkgPath)) return false;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		return "tailwindcss" in {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {
+		return false;
+	}
+}
 /** Detect the project type by scanning config files in `dir`. */
 function detectProjectType(dir) {
 	const has = (f) => existsSync(join(dir, f));
@@ -50,7 +73,7 @@ function detectProjectType(dir) {
 	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 (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";
@@ -64,36 +87,79 @@ function detectProjectType(dir) {
 	return "generic";
 }
 //#endregion
-//#region src/policy/apex.ts
-/** Gate: any one documentation source (Context7, Exa, or web) 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: ["Use ANY ONE of: mcp__context7__query-docs, mcp__exa__web_search_exa, WebSearch, or WebFetch"]
-};
+//#region src/policy/detect-framework.ts
+/**
+* Detect the framework from a file path extension + content patterns.
+* Aligned with the fusengine require-solid-read detection (distinct from
+* {@link detectProjectType}, which scans config files on disk).
+*/
+function detectFramework(filePath, content) {
+	if (/\.(tsx?|jsx?|vue|svelte)$/.test(filePath) || /from ['"]react|useState|className=/.test(content)) {
+		if (/(page|layout|loading|error|route)\.(ts|tsx)$/.test(filePath) || /use client|use server/.test(content)) return "nextjs";
+		return "react";
+	}
+	if (/\.swift$/.test(filePath)) return "swift";
+	if (/\.php$/.test(filePath)) return "laravel";
+	if (/\.java$/.test(filePath)) return "java";
+	if (/\.go$/.test(filePath)) return "go";
+	if (/\.rb$/.test(filePath)) return "ruby";
+	if (/\.rs$/.test(filePath)) return "rust";
+	if (/\.css$/.test(filePath) || /@tailwind|@apply/.test(content)) return "tailwind";
+	return "generic";
+}
+//#endregion
+//#region src/policy/apex-gates.ts
 /** 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 ttl = ttlLabel(Math.round((ctx.windowMs ?? 120 * 1e3) / 1e3));
+	if (!routed) {
+		const ref = SOLID_REF[ctx.framework] ?? "generic/";
+		return {
+			kind: "block",
+			title: `APEX: no SOLID reference matched ${ctx.filePath}`,
+			reason: `${ctx.refs.length} SOLID reference(s) are loaded but none scored for this edit (expires every ${ttl}) — read the framework skill directly instead.`,
+			actions: [`Read ${PLUGINS_DIR}/${ref}SKILL.md`]
+		};
+	}
 	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;
+	const optional = routed.optional.map((r) => r.meta.filePath);
+	const reason = [
+		`Read these before editing ${ctx.filePath} (expires every ${ttl}):`,
+		...optional.length ? [`Optional: ${optional.join(", ")}`] : [],
+		`Full skill: ${routed.skillPath}`
+	].join("\n");
 	return {
 		kind: "block",
 		title: `APEX: read SOLID references for ${ctx.framework}`,
-		reason: `Read these before editing ${ctx.filePath}:`,
+		reason,
 		actions: missing
 	};
 };
 /** Gate: the required prior agents (explore + research) must have run within the window. */
-const freshnessGate = (ctx) => ctx.agentsFresh === false ? {
+const freshnessGate = (ctx) => {
+	if (ctx.agentsFresh !== false) return null;
+	const missing = ctx.missingAgents?.length ? ctx.missingAgents : ["explore-codebase", "research-expert"];
+	const ttl = ttlLabel(Math.round((ctx.windowMs ?? 120 * 1e3) / 1e3));
+	return {
+		kind: "block",
+		title: "APEX: explore + research required",
+		reason: `Run ${missing.join(" and ")} within the freshness window (${ttl} TTL) before editing ${ctx.framework}.`,
+		actions: missing.map((name) => `Launch the ${name} agent`)
+	};
+};
+//#endregion
+//#region src/policy/apex.ts
+/** Gate: BOTH Context7 AND Exa (or a web fallback alone) must have been consulted this session. */
+const docConsultedGate = (ctx) => isDocConsulted(ctx.authorizations, ctx.sessionId) ? null : {
 	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;
+	title: "APEX: documentation not consulted",
+	reason: formatDocDeny(ctx.framework),
+	actions: ["Use BOTH mcp__context7__query-docs AND mcp__exa__web_search_exa, or a web fallback alone (WebSearch/WebFetch)"]
+};
 /** Gate: brainstorming must precede creating new files when flagged. */
 const brainstormGate = (ctx) => ctx.brainstormRequired && ctx.brainstormFresh === false ? {
 	kind: "block",
@@ -212,7 +278,7 @@ const SWIFT_TYPE_RE = /^(class|struct) [^\n{]* \{/m;
 function reactGate(filePath, content, fileLines) {
 	const v = [];
 	const max = resolveMaxLines();
-	const lines = fileLines ?? countLines(content);
+	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)) 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/.");
@@ -222,7 +288,7 @@ function reactGate(filePath, content, fileLines) {
 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);
+	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)) v.push("Interface/type in component. Move to modules/[feature]/src/interfaces/.");
 	if (CLIENT_HOOK_RE.test(content)) {
@@ -234,7 +300,7 @@ function nextGate(filePath, content, fileLines) {
 /** Laravel/PHP: line limit, interface outside `/Contracts/`, fat controller (>80). */
 function laravelGate(filePath, content, fileLines) {
 	const v = [];
-	const lines = fileLines ?? countLines(content);
+	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/")) v.push("Interface defined outside Contracts/. Move to app/Contracts/ or FuseCore/{Module}/App/Contracts/.");
@@ -245,7 +311,7 @@ function laravelGate(filePath, content, fileLines) {
 function swiftGate(filePath, content, fileLines) {
 	const v = [];
 	const max = /(View|Screen)\.swift$/.test(filePath) ? 150 : 100;
-	const lines = fileLines ?? countLines(content);
+	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/")) v.push("Protocol defined outside Protocols/ directory.");
 	if (filePath.endsWith("ViewModel.swift") && !content.includes("@MainActor")) v.push("ViewModel missing @MainActor annotation.");
@@ -593,6 +659,106 @@ const SWIFT_TRIGGERS = {
 	]
 };
 //#endregion
+//#region src/policy/skill-patterns/tailwind.ts
+/**
+* Tailwind CSS skill-trigger patterns, ported verbatim from
+* `tailwind_skill_triggers.py`. 12 skills.
+*
+* NOTE: Tailwind 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 Tailwind sub-skill name → triggering utility-class patterns (case-sensitive). */
+const TAILWIND_TRIGGERS = {
+	"tailwindcss-v4": [
+		"@theme\\b",
+		"@source\\b",
+		"@utility\\b",
+		"@variant\\b",
+		"@import\\s+['\"]tailwindcss",
+		"@config\\b"
+	],
+	"tailwindcss-layout": [
+		"\\b(flex|grid|inline-flex|inline-grid)\\b",
+		"(justify|items|place)-(start|end|center|between)",
+		"(grid-cols|grid-rows|col-span|row-span)-",
+		"(absolute|relative|fixed|sticky)\\b"
+	],
+	"tailwindcss-typography": [
+		"(font-sans|font-serif|font-mono|font-bold|font-semibold)\\b",
+		"(text-xs|text-sm|text-base|text-lg|text-xl|text-2xl)\\b",
+		"(tracking-|leading-|line-clamp-)\\b"
+	],
+	"tailwindcss-backgrounds": [
+		"(bg-gradient|bg-linear|bg-radial|bg-conic)\\b",
+		"(from-|via-|to-)\\w+",
+		"bg-\\[url\\b"
+	],
+	"tailwindcss-borders": ["(rounded-|border-|ring-|outline-|divide-)\\w+", "(border-dashed|border-dotted|border-double)\\b"],
+	"tailwindcss-effects": [
+		"(shadow-|opacity-|blur-|brightness-|contrast-)\\w+",
+		"(backdrop-blur|backdrop-brightness|backdrop-contrast)\\b",
+		"(inset-shadow-|mask-)\\w+"
+	],
+	"tailwindcss-transforms": [
+		"(scale-|rotate-|translate-|skew-)\\w+",
+		"(transition-|duration-|ease-|delay-)\\w+",
+		"(animate-spin|animate-pulse|animate-bounce)\\b"
+	],
+	"tailwindcss-responsive": [
+		"(sm:|md:|lg:|xl:|2xl:)\\w+",
+		"(@container|container-type)\\b",
+		"(min-\\[|max-\\[)\\d+"
+	],
+	"tailwindcss-spacing": ["\\b[pm][xytblr]?-\\d+\\b", "(space-x-|space-y-|gap-)\\d+"],
+	"tailwindcss-sizing": [
+		"\\b[wh]-(full|screen|auto|min|max|fit)\\b",
+		"(min-w-|max-w-|min-h-|max-h-)\\w+",
+		"(aspect-video|aspect-square)\\b"
+	],
+	"tailwindcss-interactivity": ["(cursor-|select-|pointer-events-|scroll-)\\w+", "(snap-|overscroll-|touch-)\\w+"],
+	"tailwindcss-custom-styles": [
+		"@apply\\b",
+		"@utility\\s+\\w+",
+		"@variant\\s+\\w+",
+		"theme\\(\\s*['\"]"
+	]
+};
+//#endregion
+//#region src/policy/skill-patterns/shadcn-subskills.ts
+/**
+* shadcn/ui domain skill-trigger patterns, ported verbatim from
+* `shadcn_skill_triggers.py` (the standalone shadcn-expert plugin, distinct
+* from the `SHADCN` HTML-detection patterns in `./shadcn.ts` consumed by
+* react/nextjs). 5 sub-skills. Matched case-insensitively (source `re.IGNORECASE`).
+*/
+/** Map of shadcn/ui sub-skill name → triggering code patterns. */
+const SHADCN_TRIGGERS = {
+	"shadcn-detection": [
+		"components\\.json",
+		"@radix-ui/",
+		"@base-ui/",
+		"data-\\[state=",
+		"data-\\[disabled\\]"
+	],
+	"shadcn-components": [
+		"from\\s+['\"].*components/ui/",
+		"<(Button|Input|Select|Dialog|Card|Table|Tabs|Badge)\\b",
+		"(Popover|Tooltip|Sheet|Drawer|Command|Accordion)\\b"
+	],
+	"shadcn-theming": [
+		"--(primary|secondary|muted|accent|destructive|foreground):",
+		"(cssVariables|themeConfig|globals\\.css)\\b",
+		":root\\s*\\{|\\.dark\\s*\\{"
+	],
+	"shadcn-registries": [
+		"mcp__shadcn__(search|view|get_add_command|list_items)",
+		"bunx.*shadcn@latest\\s+add\\b",
+		"(registries|@shadcn|@acme)\\b"
+	],
+	"shadcn-migration": ["(@radix-ui.*@base-ui|@base-ui.*@radix-ui)", "(migrat|convert|switch).*(radix|base.?ui)"]
+};
+//#endregion
 //#region src/policy/skill-trigger-patterns.ts
 /**
 * Per-framework code-pattern → required sub-skill data, ported verbatim from the
@@ -607,13 +773,15 @@ const SWIFT_TRIGGERS = {
 * 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"]);
+const CASE_SENSITIVE_FRAMEWORKS = /* @__PURE__ */ new Set(["swift", "tailwind"]);
 /** 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
+	swift: SWIFT_TRIGGERS,
+	tailwind: TAILWIND_TRIGGERS,
+	shadcn: SHADCN_TRIGGERS
 };
 //#endregion
 //#region src/policy/shadcn-project.ts
@@ -636,6 +804,94 @@ function isShadcnProject(cwd) {
 	return UI_DIRS.some((dir) => existsSync(join(cwd, dir)));
 }
 //#endregion
+//#region src/runtime/lifecycle/cartographer/detect.ts
+/**
+* Plugin discovery (fs). Ports `detect_plugins.py`: marketplace `plugins` dir
+* resolution + `plugin.json` meta reading.
+*/
+/** Sorted entry names of `dir` (alpha, byte-order), or `[]` on error. */
+function sortedNames$1(dir) {
+	try {
+		return readdirSync(dir).sort((a, b) => a.localeCompare(b, "en"));
+	} catch {
+		return [];
+	}
+}
+/**
+* Read `[version, name]` from `<pluginPath>/.claude-plugin/plugin.json`.
+* @param pluginPath - Absolute plugin directory.
+* @returns The `[version, name]` pair (both "" when absent/unreadable).
+*/
+function readPluginMeta(pluginPath) {
+	const pj = join(pluginPath, ".claude-plugin", "plugin.json");
+	if (!existsSync(pj)) return ["", ""];
+	try {
+		const meta = JSON.parse(readFileSync(pj, "utf-8"));
+		return [meta.version ?? "", meta.name ?? ""];
+	} catch {
+		return ["", ""];
+	}
+}
+/**
+* Auto-detect the marketplace `plugins` dir that contains `cartographer`,
+* falling back to the first marketplace with a `plugins` dir, else `cwd`.
+* Ports `find_marketplace_plugins`, but harness-agnostic: the config dir is
+* derived from the detected harness (`.claude`, `.codex`, `.cursor`, …) via the
+* shared `HOME_DIR` mapping instead of a hardcoded `.claude`.
+* @param home - Home directory (defaults to `~`).
+* @param id - Detected harness id (defaults to runtime detection).
+* @returns The resolved plugins directory.
+*/
+function findMarketplacePlugins(home = homedir(), id = detectHarness().id) {
+	const mp = join(home, HOME_DIR[id] ?? ".claude", "plugins", "marketplaces");
+	const markets = sortedNames$1(mp);
+	for (const m of markets) if (existsSync(join(mp, m, "plugins", "cartographer"))) return join(mp, m, "plugins");
+	for (const m of markets) if (existsSync(join(mp, m, "plugins"))) return join(mp, m, "plugins");
+	return process.cwd();
+}
+//#endregion
+//#region src/policy/skill-path.ts
+/**
+* Dynamic skill-path resolution (fs). Replaces a hardcoded `PLUGIN_DIR`
+* table (framework -> plugin dir name), which can drift from what's actually
+* installed: scans installed marketplace plugins for a `skills/<name>/SKILL.md`
+* that exists ON DISK, returning the first real absolute path found — never a
+* guessed one.
+*
+* Deliberately lighter than the cartographer's own `scanSkills` (which
+* frontmatter-parses every skill in a plugin): this runs once per missing
+* sub-skill on every gated Write/Edit, so it does a single flat `readdirSync`
+* of the plugins dir + one `existsSync` per candidate — no file reads, no
+* recursion, no `statSync`.
+*/
+/** Sorted entry names of `dir` (alpha, byte-order), or `[]` on error. */
+function pluginDirNames(dir) {
+	try {
+		return readdirSync(dir).sort((a, b) => a.localeCompare(b, "en"));
+	} catch {
+		return [];
+	}
+}
+/**
+* Resolve the real, installed `SKILL.md` path for `skillName`.
+* @param skillName - the sub-skill directory name (e.g. "solid-react",
+*   "shadcn-detection", "react-shadcn").
+* @param pluginsDirOverride - override for the marketplace plugins dir
+*   (tests); defaults to the auto-detected marketplace root.
+* @returns the absolute `<pluginDir>/skills/<skillName>/SKILL.md` of the
+*   first installed plugin that actually has it, or the generic
+*   `${PLUGINS_DIR}/<skillName>` fallback when none is found (CI/test
+*   environments without a marketplace).
+*/
+function resolveSkillPath(skillName, pluginsDirOverride) {
+	const pluginsDir = pluginsDirOverride ?? findMarketplacePlugins();
+	for (const dir of pluginDirNames(pluginsDir)) {
+		const candidate = join(pluginsDir, dir, "skills", skillName, "SKILL.md");
+		if (existsSync(candidate)) return candidate;
+	}
+	return `${PLUGINS_DIR}/${skillName}`;
+}
+//#endregion
 //#region src/policy/skill-triggers.ts
 /**
 * Detect which sub-skills the written `content` requires for a `framework`.
@@ -655,6 +911,24 @@ function detectRequiredSkills(framework, content) {
 	return required;
 }
 /**
+* `.tsx`/`.jsx` — the only extensions `check-tailwind-skill.py` actually gates
+* (its regex also lists `.css`/`.html`, but both hit an early return right
+* after, in the Python source).
+*/
+const TAILWIND_FILE = /\.(tsx|jsx)$/;
+/** Ported verbatim from `check-tailwind-skill.py`'s `TW_PATTERN`. */
+const TAILWIND_CONTENT = /(className|class).*['"].*\b(flex|grid|p-|m-|w-|h-|text-|bg-|border-)/;
+/**
+* True when `filePath`/`content` match the Python Tailwind gate's trigger
+* condition. React/Next.js components embed Tailwind utility classes in
+* `className` — this check fires IN ADDITION TO the primary framework gate,
+* never instead of it: {@link detectFramework} keeps returning "react"/
+* "nextjs" for these files (framework SOLID rules stay correct).
+*/
+function usesTailwindUtilities(filePath, content) {
+	return TAILWIND_FILE.test(filePath) && TAILWIND_CONTENT.test(content);
+}
+/**
 * 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>/`.
@@ -664,10 +938,15 @@ function detectRequiredSkills(framework, content) {
 * @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).
+* @param filePath - the file being written; when it's a `.tsx`/`.jsx` file
+*   with Tailwind utility classes in `className`, the "tailwind" domain
+*   skills are merged in alongside `framework`'s own (ports the separate
+*   `check-tailwind-skill.py` gate, independent of react/nextjs).
 * @returns a `block` Prompt naming the missing sub-skills, or `null` when satisfied.
 */
-function skillTriggerGate(framework, content, refsRead, forcedSkill, cwd) {
+function skillTriggerGate(framework, content, refsRead, forcedSkill, cwd, filePath) {
 	let required = detectRequiredSkills(framework, content);
+	if (framework !== "tailwind" && filePath && usesTailwindUtilities(filePath, content)) required = [...required, ...detectRequiredSkills("tailwind", 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}/`)));
@@ -676,10 +955,237 @@ function skillTriggerGate(framework, content, refsRead, forcedSkill, cwd) {
 		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`)
+		actions: missing.map((s) => `Read ${resolveSkillPath(s)}`)
 	};
 }
 //#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/runtime/lifecycle/cartographer/scan-hooks.ts
+/**
+* Hook scanning (fs). Ports `_scan_hooks` from `scan_plugins.py`: reads a
+* plugin's `hooks/hooks.json` and reduces it to a single `("hooks", "<events>", "")`
+* row. The `hooks` value (or the whole document) is either a MAP of event →
+* entries (keys are the events) or a LIST of entries each carrying an `event`.
+*/
+/** True for a non-null plain object (excludes arrays), mirroring Python `isinstance(x, dict)`. */
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Sort unique non-empty strings alpha (byte-order). */
+function sortedEvents(events) {
+	return [...new Set([...events].filter((e) => e))].sort((a, b) => a.localeCompare(b, "en"));
+}
+/** Derive hook event names from the `hooks.json` data (map keys, or list `event` fields). */
+function hookEvents(hooksData) {
+	if (isPlainObject(hooksData)) return sortedEvents(Object.keys(hooksData).filter((k) => !k.startsWith("_")));
+	if (Array.isArray(hooksData)) return sortedEvents(hooksData.map((h) => isPlainObject(h) ? String(h.event ?? "") : ""));
+	return [];
+}
+/**
+* Scan `hooks/hooks.json` into a single `("hooks", "<events>", "")` row.
+* @param root - Absolute plugin directory.
+* @returns The single hooks row, or `[]` when absent/empty/unreadable.
+*/
+function scanHooks(root) {
+	const file = join(root, "hooks", "hooks.json");
+	if (!existsSync(file)) return [];
+	try {
+		const raw = JSON.parse(readFileSync(file, "utf-8"));
+		const events = hookEvents(isPlainObject(raw) ? raw.hooks ?? raw : {});
+		return events.length ? [[
+			"hooks",
+			events.join(", "),
+			""
+		]] : [];
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/runtime/lifecycle/cartographer/scan.ts
+/**
+* Plugin scanning (fs). Ports `scan_plugins.py`: turns a plugin's
+* agents/skills/commands/hooks into ordered `[type, name, desc]` rows.
+*/
+/** Sorted entry names of `dir` (alpha, byte-order), or `[]` on error. */
+function sortedNames(dir) {
+	try {
+		return readdirSync(dir).sort((a, b) => a.localeCompare(b, "en"));
+	} catch {
+		return [];
+	}
+}
+/** Read a `.md` frontmatter field from a file path, "" when missing/unreadable. */
+function fileField(path, field) {
+	try {
+		return parseField(readFileSync(path, "utf-8"), field);
+	} catch {
+		return "";
+	}
+}
+/** Scan `agents/*.md` → `("agent", name, desc[:50])` rows. */
+function scanAgents(root) {
+	const dir = join(root, "agents");
+	return sortedNames(dir).filter((n) => extname(n) === ".md").map((n) => {
+		const f = join(dir, n);
+		return [
+			"agent",
+			fileField(f, "name") || n.replace(/\.md$/, ""),
+			fileField(f, "description").slice(0, 50)
+		];
+	});
+}
+/** Scan `skills/<dir>/SKILL.md` → `("skill", dir, desc)` rows. */
+function scanSkills(root) {
+	const dir = join(root, "skills");
+	const rows = [];
+	for (const name of sortedNames(dir)) {
+		try {
+			if (!statSync(join(dir, name)).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		const skillMd = join(dir, name, "SKILL.md");
+		let desc = "";
+		if (existsSync(skillMd)) {
+			desc = fileField(skillMd, "description");
+			if (!desc) try {
+				desc = parseBodyDesc(readFileSync(skillMd, "utf-8"));
+			} catch {}
+		}
+		rows.push([
+			"skill",
+			name,
+			desc || "(no description)"
+		]);
+	}
+	return rows;
+}
+/** Scan `commands/*.md` → `("command", "/name", desc[:50])` rows. */
+function scanCommands(root) {
+	const dir = join(root, "commands");
+	return sortedNames(dir).filter((n) => extname(n) === ".md").map((n) => [
+		"command",
+		`/${n.replace(/\.md$/, "")}`,
+		fileField(join(dir, n), "description").slice(0, 50)
+	]);
+}
+/**
+* Scan a single plugin directory into ordered `[type, name, desc]` rows.
+* @param pluginDir - Absolute plugin directory.
+* @returns The agents + skills + commands + hooks rows.
+*/
+function scanPlugin(pluginDir) {
+	return [
+		...scanAgents(pluginDir),
+		...scanSkills(pluginDir),
+		...scanCommands(pluginDir),
+		...scanHooks(pluginDir)
+	];
+}
+//#endregion
+//#region src/policy/expert-agents.ts
+/**
+* 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.
+*/
+/** Sorted plugin-dir names directly under `pluginsDir` (dirs only, alpha), or `[]`. */
+function pluginDirs(pluginsDir) {
+	let names;
+	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.
+*/
+function getExpertAgent(type, pluginsDirOverride) {
+	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";
+}
+//#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;
@@ -712,12 +1218,13 @@ function detectClaudeMdProjectType(cwd) {
 * @returns The APEX instruction text.
 */
 function buildApexInstruction(projectType, maxLines) {
+	const expertAgent = getExpertAgent(projectType);
 	return `INSTRUCTION: This is a development task. Use APEX methodology:
 
 **TRACKING FILE**: [project]/.claude/apex/task.json (auto-created on first Write/Edit)
 
 1. **ANALYZE** (MANDATORY - 3 AGENTS IN PARALLEL):
-   - explore-codebase + research-expert + ${projectType}-expert (framework expertise)\n   - Project type detected: ${projectType}\n\n2. **PLAN**: Use TaskCreate to break down tasks (<${maxLines} lines per file)\n\n3. **EXECUTE**: ${projectType}-expert, follow SOLID principles, split at ${maxLines - 10} lines\n\n4. **EXAMINE**: Run sniper agent after ANY modification\n\n**IMPORTANT**: Read .claude/apex/task.json to check documentation status before writing code.`;
+   - explore-codebase + research-expert + ${expertAgent} (framework expertise)\n   - Project type detected: ${projectType}\n\n2. **PLAN**: Use TaskCreate to break down tasks (<${maxLines} lines per file)\n\n3. **EXECUTE**: ${expertAgent}, follow SOLID principles, split at ${maxLines - 10} lines\n\n4. **EXAMINE**: Run sniper agent after ANY modification\n\n**IMPORTANT**: Read .claude/apex/task.json to check documentation status before writing code.`;
 }
 /**
 * Build the UserPromptSubmit injection text: read `~/.claude/CLAUDE.md` and,
@@ -905,59 +1412,6 @@ const EXCLUDE_DIRS = /* @__PURE__ */ new Set([
 	".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*(.+)$/;
@@ -1085,4 +1539,4 @@ function missingSeoElements(html) {
 	return missing;
 }
 //#endregion
-export { evaluateApex as A, MAX_EXA_RESULTS as C, APEX_GATES as D, detectCreationIntent as E, detectProjectType as F, isApexCommand as I, requiredArchSkill as L, solidReadGate as M, DEV_KEYWORDS as N, brainstormGate as O, detectModularArchitecture as P, frameworkSolidGate as S, capVerbosity as T, buildClaudeMdContext as _, firstHeading as a, skillTriggerGate as b, parseBodyDesc as c, PROJECT_INDICATORS as d, buildApexTaskContext as f, buildApexInstruction as g, DEV_VERBS as h, firstComment as i, freshnessGate as j, docConsultedGate as k, parseField as l, loadApexTaskState as m, missingSeoElements as n, parseEnrichment as o, buildApexTaskInjection as p, descFromText as r, parseEntry as s, isHtmlLike as t, EXCLUDE_DIRS as u, detectClaudeMdProjectType as v, MAX_TOKENS as w, SKILL_TRIGGERS as x, detectRequiredSkills as y };
+export { detectCreationIntent as A, detectProjectType as B, findMarketplacePlugins as C, MAX_EXA_RESULTS as D, frameworkSolidGate as E, freshnessGate as F, requiredArchSkill as H, solidReadGate as I, detectFramework as L, brainstormGate as M, docConsultedGate as N, MAX_TOKENS as O, evaluateApex as P, DEV_KEYWORDS as R, usesTailwindUtilities as S, SKILL_TRIGGERS as T, isApexCommand as V, scanPlugin as _, firstHeading as a, detectRequiredSkills as b, EXCLUDE_DIRS as c, buildApexTaskInjection as d, loadApexTaskState as f, detectClaudeMdProjectType as g, buildClaudeMdContext as h, firstComment as i, APEX_GATES as j, capVerbosity as k, PROJECT_INDICATORS as l, buildApexInstruction as m, missingSeoElements as n, parseEnrichment as o, DEV_VERBS as p, descFromText as r, parseEntry as s, isHtmlLike as t, buildApexTaskContext as u, parseBodyDesc as v, readPluginMeta as w, skillTriggerGate as x, parseField as y, detectModularArchitecture as z };