@fusengine/harness 0.1.43 → 0.1.45

package/dist/{handle-BTHcKWQ5.mjs → handle-DJaaD2BT.mjs}

@@ -1,18 +1,17 @@
-import { a as parseEnvInt, r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
+import { a as parseEnvInt, i as splitTarget, r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
 import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
-import { t as HOME_DIR } from "./dotenv-DGyLln7U.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
-import { t as detectHarness } from "./harness-C8Nxxyn_.mjs";
-import { A as evaluateApex, E as detectCreationIntent, L as requiredArchSkill, P as detectModularArchitecture, S as frameworkSolidGate, T as capVerbosity, _ as buildClaudeMdContext, b as skillTriggerGate, c as parseBodyDesc, d as PROJECT_INDICATORS, l as parseField, n as missingSeoElements, o as parseEnrichment, p as buildApexTaskInjection, r as descFromText, s as parseEntry, t as isHtmlLike, u as EXCLUDE_DIRS$1 } from "./validate-xi-zc-22.mjs";
-import { N as detectFramework, j as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-CeivW6G0.mjs";
-import { r as isDocConsulted } from "./doc-helpers-BhzDmJ18.mjs";
-import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
+import { A as detectCreationIntent, B as detectProjectType$1, C as findMarketplacePlugins, E as frameworkSolidGate, H as requiredArchSkill, L as detectFramework, N as docConsultedGate, P as evaluateApex, _ as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, h as buildClaudeMdContext, k as capVerbosity, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, r as descFromText, s as parseEntry, t as isHtmlLike, w as readPluginMeta, x as skillTriggerGate, y as parseField, z as detectModularArchitecture } from "./validate-DcQaKzau.mjs";
+import { F as countFrameworkCodeLines, I as countLines, N as PLUGINS_DIR, n as FAIL_CLOSED, t as evaluate } from "./evaluate-d7Pp8XJH.mjs";
 import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
+import { a as sanitizeSessionId, c as sessionsDir, i as loadSessionState, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, t as claudeHome } from "./home-state-mKZxP4oZ.mjs";
+import { r as isDocConsulted } from "./doc-helpers-CWZegVdR.mjs";
+import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { a as nowStamp, l as throttleMs, n as readRoots, o as readState, s as setStateField, t as addRoot } from "./registry-CymilZiZ.mjs";
-import { c as extractText, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, r as cacheLookup, t as mcpCacheWrite } from "./mcp-store-CnsW9oFj.mjs";
-import { t as loadRefs } from "./loader-Bn-DbZmt.mjs";
-import { _ as saveSessionState, c as recordDoc, d as trivialCount, f as claudeHome, g as sanitizeSessionId, h as loadSessionState, i as agentsFresh, l as recordRefRead, m as fusengineCache, n as saveTrack, o as recordAgent, p as fuseHarnessHome, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTrivialEdit, y as sessionsDir } from "./store-CdWOQ9zD.mjs";
-import { c as collectFiles, d as sleep, f as spawnCapture, l as pathExists, n as contextResponse, p as writeText, t as blockResponse, u as readText } from "./claude-CeRYMOaG.mjs";
+import { d as loadIndex, i as cacheLookupMeta, n as webfetchCacheWrite, o as cacheLookupSubstringMeta, t as mcpCacheWrite, u as extractText } from "./mcp-store-BkBDmuxN.mjs";
+import { t as loadRefs } from "./loader-AGz4nK7d.mjs";
+import { c as recordDoc, d as trivialCount, i as agentsFresh, l as recordRefRead, n as saveTrack, o as recordAgent, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTrivialEdit } from "./store-CNjFenWe.mjs";
+import { d as readText, f as sleep, l as collectFiles, m as writeText, n as contextResponse, p as spawnCapture, r as denyResponse, s as systemMessage, t as blockResponse, u as pathExists } from "./claude-DLh0fHWM.mjs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -300,11 +299,23 @@ function clearActiveDesignAgent(cacheDir) {
 * Handle the design-agent SubagentStart/Stop lifecycle: init the pipeline state +
 * raise the active flag on start, archive/cleanup + clear the flag on stop.
 * Returns true when it handled the event (caller should respond and stop).
+*
+* `SubagentStop` clears the flag whenever `agent_id` matches the currently
+* active one, INDEPENDENTLY of `agent_type` on the stop payload — a stop event
+* is not guaranteed to echo the same `agent_type` string the start event used,
+* and gating the clear on it left the flag stuck (blocking every subsequent
+* top-level Write/Edit in the session — see MEMORY/LESSON.md).
 */
 function designLifecycle(payload, cacheDir, cwd, stamp, now) {
 	const event = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
-	if (!(typeof payload.agent_type === "string" ? payload.agent_type : "").includes("design")) return false;
 	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+	if (event === "SubagentStop") {
+		if (!agentId || agentId !== activeDesignAgent(cacheDir)) return false;
+		cleanupDesignStates(cacheDir, agentId, stamp, now);
+		clearActiveDesignAgent(cacheDir);
+		return true;
+	}
+	if (!(typeof payload.agent_type === "string" ? payload.agent_type : "").includes("design")) return false;
 	if (event === "SubagentStart") {
 		if (!agentId) return false;
 		const dsExists = existsSync(join(cwd, "design-system.md"));
@@ -312,11 +323,6 @@ function designLifecycle(payload, cacheDir, cwd, stamp, now) {
 		setActiveDesignAgent(cacheDir, agentId);
 		return true;
 	}
-	if (event === "SubagentStop") {
-		cleanupDesignStates(cacheDir, agentId, stamp, now);
-		clearActiveDesignAgent(cacheDir);
-		return true;
-	}
 	return false;
 }
 //#endregion
@@ -637,6 +643,176 @@ function solidDetectStart(env = process.env) {
 	return profile.type !== "unknown" ? `SOLID: ${profile.type} project (max ${profile.limit} lines)` : "";
 }
 //#endregion
+//#region src/runtime/lifecycle/check-file-size.ts
+/**
+* PostToolUse (matcher "Write|Edit") for the solid scope: warn when a file
+* exceeds the adaptive `SOLID_FILE_LIMIT` (set by `solidDetectStart` at
+* SessionStart, keyed off the detected project type). Ports `check-file-size.py`.
+* Non-blocking (`additionalContext`), unlike the fixed-ceiling core-guards gate.
+*/
+/** Per-language "blank or comment" line pattern (parity `count_loc`'s `code_comment` map). */
+const COMMENT_RE = {
+	ts: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	tsx: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	js: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	jsx: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	go: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	rs: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	java: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	swift: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+	php: /^\s*$|^\s*\/\/|^\s*#|^\s*\/\*|^\s*\*/,
+	py: /^\s*$|^\s*#|^\s*"""|^\s*'''/
+};
+/** Count lines of code excluding comments/blanks for `filePath`'s extension (raw length when unmapped). */
+function countLoc(filePath, content) {
+	const pattern = COMMENT_RE[extname(filePath).slice(1)];
+	const lines = content.split("\n");
+	return pattern ? lines.filter((l) => !pattern.test(l)).length : lines.length;
+}
+/**
+* Warn when a written/edited file exceeds `SOLID_FILE_LIMIT` (default 100).
+* Inert when `SOLID_PROJECT_TYPE` is absent/"unknown" (parity: the Python hook
+* no-ops outside a detected project).
+* @param tool - The tool name (only "Write"/"Edit" are checked).
+* @param filePath - The written file's absolute path.
+* @param env - Environment (defaults to `process.env`).
+* @returns The PostToolUse `additionalContext` response, or `""` when clean/inert.
+*/
+function checkFileSize(tool, filePath, env = process.env) {
+	const ptype = env.SOLID_PROJECT_TYPE ?? "";
+	if (!ptype || ptype === "unknown") return "";
+	if (tool !== "Write" && tool !== "Edit") return "";
+	if (!filePath || !pathExists(filePath)) return "";
+	let content;
+	try {
+		content = readText(filePath);
+	} catch {
+		return "";
+	}
+	const limit = parseEnvInt(env.SOLID_FILE_LIMIT, 100);
+	const loc = countLoc(filePath, content);
+	if (loc <= limit) return "";
+	return contextResponse("PostToolUse", `SOLID: ${filePath.split("/").pop() ?? filePath} has ${loc} lines (limit: ${limit}). Consider splitting into smaller modules.`);
+}
+//#endregion
+//#region src/runtime/lifecycle/validate-solid.ts
+/**
+* PreToolUse (matcher "Write|Edit") for the solid scope: deny a Go top-level
+* interface or a Python `ABC` subclass defined outside its language's
+* `/interfaces/` directory. Ports `solid/scripts/validate-solid.py`'s
+* `check_go`/`check_python` only — its `check_nextjs`/`check_laravel`/
+* `check_swift` siblings are NOT ported here: they are a strict subset of the
+* already-ported `framework-solid-gates.ts` (react/nextjs/laravel/swift),
+* which fire unconditionally on file extension/content rather than being
+* gated behind `SOLID_PROJECT_TYPE`. Inert when `SOLID_PROJECT_TYPE` is
+* absent/"unknown"/nextjs/laravel/swift/rust (parity: the Python hook only
+* has a `go`/`python` validator).
+*/
+/** Top-level Go interface declaration, e.g. `type Foo interface {`. */
+const GO_INTERFACE_RE = /^type.*interface \{/m;
+/** Python class whose header mentions `ABC` (naive, parity with the Python regex). */
+const PY_ABC_RE = /class.*ABC/;
+/** Go: deny a top-level interface declared outside `/interfaces/`. */
+function checkGo(filePath, content) {
+	if (!filePath.endsWith(".go") || filePath.includes("/interfaces/")) return null;
+	return GO_INTERFACE_RE.test(content) ? "SOLID: Interfaces must be in internal/interfaces/" : null;
+}
+/** Python: deny an ABC subclass declared outside `/interfaces/`. */
+function checkPython(filePath, content) {
+	if (!filePath.endsWith(".py") || filePath.includes("/interfaces/")) return null;
+	return PY_ABC_RE.test(content) ? "SOLID: Abstract classes must be in src/interfaces/" : null;
+}
+/** `SOLID_PROJECT_TYPE` values this gate validates (parity subset — see module doc). */
+const VALIDATORS = {
+	go: checkGo,
+	python: checkPython
+};
+/**
+* Deny a Write/Edit that violates the Go/Python interface-location SOLID rule.
+* @param tool - The tool name (only "Write"/"Edit" are checked).
+* @param filePath - The written file's absolute path.
+* @param content - The written/edited content (`new_string` snippet on Edit).
+* @param env - Environment (defaults to `process.env`).
+* @returns The PreToolUse deny response, or `""` when clean/inert.
+*/
+function validateSolidGate(tool, filePath, content, env = process.env) {
+	const ptype = env.SOLID_PROJECT_TYPE ?? "";
+	if (!ptype || ptype === "unknown") return "";
+	if (tool !== "Write" && tool !== "Edit") return "";
+	if (!filePath) return "";
+	const violation = VALIDATORS[ptype]?.(filePath, content) ?? null;
+	return violation ? denyResponse("PreToolUse", violation) : "";
+}
+//#endregion
+//#region src/runtime/lifecycle/validate-tailwind.ts
+/**
+* PostToolUse (matcher "Write|Edit") for the tailwindcss scope: warn
+* (non-blocking) on a deprecated `@tailwind` directive, excessive `@apply`
+* usage, and an overlong `className` string on a just-written CSS/TSX/JSX
+* file inside a detected Tailwind project. Ports `validate-tailwind.py`.
+*/
+/** Tailwind config file names checked at each ancestor directory. */
+const TAILWIND_CONFIGS = [
+	"tailwind.config.js",
+	"tailwind.config.ts",
+	"tailwind.config.mjs",
+	"tailwind.config.cjs"
+];
+/** Walk up to 20 levels from `filePath`'s directory to the nearest ancestor holding `package.json` or a Tailwind config (parity `find_project_root`). */
+function findProjectRoot(filePath) {
+	let dir = dirname(filePath);
+	for (let i = 0; i < 20; i++) {
+		if (pathExists(join(dir, "package.json")) || TAILWIND_CONFIGS.some((cfg) => pathExists(join(dir, cfg)))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/** True when `filePath` belongs to a Tailwind project (v3 config, or `tailwindcss` in package.json deps). Parity `is_tailwind_project`. */
+function isTailwindProject(filePath) {
+	const root = findProjectRoot(filePath);
+	if (!root) return false;
+	if (TAILWIND_CONFIGS.some((cfg) => pathExists(join(root, cfg)))) return true;
+	const pkgPath = join(root, "package.json");
+	if (!pathExists(pkgPath)) return false;
+	try {
+		const pkg = JSON.parse(readText(pkgPath));
+		return Boolean(pkg.dependencies?.tailwindcss) || Boolean(pkg.devDependencies?.tailwindcss);
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate Tailwind best practices on a just-written file.
+* @param tool - The tool name (only "Write"/"Edit" are checked).
+* @param filePath - The written file's absolute path.
+* @returns The PostToolUse `additionalContext` response, or `""` when clean/inert.
+*/
+function validateTailwind(tool, filePath) {
+	if (tool !== "Write" && tool !== "Edit") return "";
+	if (!/\.(css|tsx|jsx)$/.test(filePath)) return "";
+	if (!pathExists(filePath) || !isTailwindProject(filePath)) return "";
+	let content;
+	try {
+		content = readText(filePath);
+	} catch {
+		return "";
+	}
+	const warnings = [];
+	if (filePath.endsWith(".css")) {
+		if (/@tailwind (base|components|utilities)/.test(content)) warnings.push("Tailwind v4: @tailwind directives are deprecated - use @import 'tailwindcss'.");
+		const applyCount = (content.match(/@apply/g) ?? []).length;
+		if (applyCount > 10) warnings.push(`Excessive @apply usage (${applyCount}) - prefer utility classes directly.`);
+	}
+	if (/\.(tsx|jsx)$/.test(filePath)) {
+		const longClasses = (content.match(/className="[^"]{150,}"/g) ?? []).length;
+		if (longClasses > 0) warnings.push(`Very long className (${longClasses} lines) - extract to @utility or use cn().`);
+	}
+	if (warnings.length === 0) return "";
+	return contextResponse("PostToolUse", warnings.join(" "));
+}
+//#endregion
 //#region src/runtime/lifecycle/subagent-cache.ts
 const DEFAULT_TTL_MIN = 30;
 /** Resolve cache TTL (minutes) from `FUSENGINE_CACHE_TTL_MIN` or default. */
@@ -942,7 +1118,7 @@ function postEditTypescript(filePath) {
 //#endregion
 //#region src/runtime/lifecycle/task-completed.ts
 /** Code-file extensions audited on task completion (mirrors validate-task-solid.py). */
-const CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+const CODE_EXTENSIONS$2 = /* @__PURE__ */ new Set([
 	".ts",
 	".tsx",
 	".js",
@@ -972,7 +1148,7 @@ const CODE_EXTENSIONS = /* @__PURE__ */ new Set([
 function collectViolations(files, max) {
 	const violations = [];
 	for (const fp of files) {
-		if (!CODE_EXTENSIONS.has(extname(fp)) || !existsSync(fp)) continue;
+		if (!CODE_EXTENSIONS$2.has(extname(fp)) || !existsSync(fp)) continue;
 		try {
 			const lines = countLines(readFileSync(fp, "utf-8"));
 			if (lines > max) violations.push(`${basename(fp)}: ${lines} lines (max ${max})`);
@@ -1190,176 +1366,6 @@ function generateProjectMap(cwd, outputDir) {
 	return "";
 }
 //#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/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/cartographer/build-tree.ts
 const SECTION_ORDER = [
 	"agent",
@@ -1701,14 +1707,6 @@ ${agents}
 ### 6. When Done
 - TaskUpdate(taskId, status: completed) triggers auto-commit${cartographerContext()}`);
 }
-//#endregion
-//#region src/runtime/lifecycle/aipilot/cache-base.ts
-/**
-* Shared cache-path + age helpers for the ai-pilot scope.
-* Reuses the harness home-state (`fusengineCache`) so the ai-pilot caches live
-* under the same `~/.fuse-harness/cache` tree as the core MCP cache — no
-* second cache layer.
-*/
 /** 16-char hex SHA-256 of `text` (project hash / doc topic key). */
 function hashText16(text) {
 	return createHash("sha256").update(text).digest("hex").slice(0, 16);
@@ -1839,7 +1837,7 @@ async function cacheAnalyticsSave(home = homedir(), now = Date.now()) {
 * cached architecture report when fresh + config-matching, else inject save
 * instructions. Ports `explore-cache-check.ts`.
 */
-const TTL_SECONDS$2 = 86400;
+const TTL_SECONDS$1 = 86400;
 const CONFIG_FILES = [
 	"package.json",
 	"tsconfig.json",
@@ -1887,7 +1885,7 @@ async function injectExploreCache(cwd, home = homedir(), now = Date.now()) {
 	const snapshot = pathExists(snapFile) ? readText(snapFile) : "";
 	if (meta?.timestamp && snapshot) {
 		const age = cacheAge(meta.timestamp, now);
-		if (age < TTL_SECONDS$2 && meta.config_hash === cfgHash) {
+		if (age < TTL_SECONDS$1 && meta.config_hash === cfgHash) {
 			context = `## CACHED ARCHITECTURE AVAILABLE (age: ${Math.floor(age / 60)}min)\nUSE this cached report. Do NOT run full exploration. Return it immediately.\n\n${snapshot}`;
 			logCacheEvent("explore", "hit", pHash, {}, home);
 		}
@@ -1905,7 +1903,6 @@ async function injectExploreCache(cwd, home = homedir(), now = Date.now()) {
 * cached documentation summaries. Ports `doc-cache-inject.ts`. Doc *saving*
 * happens on SubagentStop (`cache-doc.ts`).
 */
-const TTL_SECONDS$1 = 604800;
 const MAX_SIZE = 8192;
 /** Concatenate fresh, dedup-by-hash cached doc bodies. */
 async function buildDocsContext(entries, docsDir, now) {
@@ -1916,7 +1913,7 @@ async function buildDocsContext(entries, docsDir, now) {
 	for (const entry of entries) {
 		if (!entry.timestamp) continue;
 		const age = cacheAge(entry.timestamp, now);
-		if (age >= TTL_SECONDS$1) continue;
+		if (age >= 604800) continue;
 		if (age > maxAge) maxAge = age;
 		if (!entry.hash || seen.has(entry.hash)) continue;
 		seen.add(entry.hash);
@@ -2213,8 +2210,8 @@ function projectRootFromPaths(filePaths) {
 	}
 	return bestRoot;
 }
-/** Extract all absolute file paths from tool_use entries in a JSONL transcript. */
-async function transcriptFilePaths(transcriptPath) {
+/** Extract absolute file paths from tool_use entries in a JSONL transcript, optionally restricted to `toolNames` (default: any tool). */
+async function transcriptFilePaths(transcriptPath, toolNames) {
 	const text = readText(transcriptPath);
 	const paths = /* @__PURE__ */ new Set();
 	for (const line of text.split("\n").filter(Boolean)) try {
@@ -2222,6 +2219,7 @@ async function transcriptFilePaths(transcriptPath) {
 		if (!Array.isArray(content)) continue;
 		for (const block of content) {
 			if (block?.type !== "tool_use") continue;
+			if (toolNames && !toolNames.includes(block.name)) continue;
 			const fp = block.input?.file_path ?? block.input?.path ?? "";
 			if (typeof fp === "string" && fp.startsWith("/")) paths.add(fp);
 		}
@@ -2677,6 +2675,149 @@ async function syncTaskTracking(payload, cwd) {
 	}
 }
 //#endregion
+//#region src/runtime/lifecycle/aipilot/doc-cache-gate.ts
+/**
+* @module aipilot/doc-cache-gate
+* PreToolUse gate for the ai-pilot scope: DENY a Context7/Exa doc call when the
+* per-project doc cache already holds that library fresh (< 7d). Ports the
+* source `doc-cache-gate.ts`. The inject side (`inject-doc.ts`) serves the same
+* cache on SubagentStart; this side avoids the redundant live re-query.
+* @packageDocumentation
+*/
+const GATED_TOOLS = /context7__query-docs|exa__get_code_context|exa__web_search/;
+/** The library key a gated tool call targets (Context7 libraryId / Exa query), or "". */
+function libraryOf(payload) {
+	const tool = String(payload.tool_name ?? "");
+	const input = payload.tool_input ?? {};
+	if (tool.includes("context7")) {
+		const libraryId = typeof input.libraryId === "string" ? input.libraryId : "";
+		const query = typeof input.query === "string" ? input.query : "";
+		return libraryId && query ? libraryId : "";
+	}
+	if (tool.includes("exa")) return typeof input.query === "string" ? input.query : "";
+	return "";
+}
+/**
+* DENY a redundant doc call when the library is cached fresh, else `null`.
+* @param payload - The raw PreToolUse hook payload.
+* @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+* @param now - Clock (defaults to `Date.now()`).
+* @param home - Home dir (defaults to `~`).
+* @returns A native deny response, or `null` to fall through to the live call.
+*/
+async function docCacheGate(payload, cwd, now = Date.now(), home = homedir()) {
+	const tool = String(payload.tool_name ?? "");
+	if (!GATED_TOOLS.test(tool)) return null;
+	const library = libraryOf(payload);
+	if (!library) return null;
+	const projPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+	const cacheDir = cacheDirFor("doc", projPath, home);
+	const entry = (await readJsonFile(join(cacheDir, "index.json")))?.docs?.find((d) => d.library === library);
+	if (!entry?.hash || !entry.timestamp) return null;
+	const docFile = join(cacheDir, "docs", `${entry.hash}.md`);
+	if (!pathExists(docFile)) return null;
+	const age = cacheAge(entry.timestamp, now);
+	if (age >= 604800) return null;
+	logCacheEvent("doc", "blocked", projectHash(projPath), { library }, home);
+	return denyResponse("PreToolUse", `Doc already cached at ${docFile} (age: ${Math.floor(age / 3600)}h). Use the Read tool to access it instead of re-querying.`);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/solid-compliance.ts
+/**
+* PostToolUse (matcher "Write|Edit") for the ai-pilot scope: validate SOLID
+* file-size and interface-location compliance right after a code write.
+* Ports `check-solid-compliance.py`.
+*/
+const CODE_EXTENSIONS$1 = /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java|astro)$/;
+const COMPONENT_DIR = /(components|pages|views)\//;
+const BACKEND_DIR = /(Controllers|Models|Services)\//;
+const TS_INTERFACE_RE = /^(export )?(interface|type) [A-Z]/m;
+const PHP_INTERFACE_RE = /^interface /m;
+/** Count non-empty, non-comment (`//`/`#`/`*`-prefixed) lines. Shared with {@link checkSolidFromTranscript}. */
+function countCodeLines(content) {
+	let count = 0;
+	for (const raw of content.split("\n")) {
+		const s = raw.trim();
+		if (!s || s.startsWith("//") || s.startsWith("#") || s.startsWith("*")) continue;
+		count++;
+	}
+	return count;
+}
+/**
+* Validate SOLID compliance for a just-written file.
+* @param payload - The raw PostToolUse hook payload (`tool_name`, `tool_input.file_path`).
+* @returns The PostToolUse `additionalContext` response, or `""` when clean/not applicable.
+*/
+function checkSolidCompliance(payload) {
+	const tool = String(payload.tool_name ?? "");
+	if (tool !== "Write" && tool !== "Edit") return "";
+	const input = payload.tool_input ?? {};
+	const filePath = typeof input.file_path === "string" ? input.file_path : "";
+	if (!filePath || !CODE_EXTENSIONS$1.test(filePath) || !pathExists(filePath)) return "";
+	let content;
+	try {
+		content = readText(filePath);
+	} catch {
+		return "";
+	}
+	const violations = [];
+	const max = resolveMaxLines();
+	const split = splitTarget(max);
+	const lc = countCodeLines(content);
+	if (lc > max) violations.push(`FILE SIZE: ${lc} lines (max: ${max})`);
+	else if (lc > split) violations.push(`FILE SIZE WARNING: ${lc} lines (split at ${split})`);
+	if (COMPONENT_DIR.test(filePath)) {
+		if (TS_INTERFACE_RE.test(content)) violations.push("INTERFACE LOCATION: Move to src/interfaces/");
+	} else if (BACKEND_DIR.test(filePath)) {
+		if (PHP_INTERFACE_RE.test(content)) violations.push("INTERFACE LOCATION: Move to app/Contracts/");
+	}
+	if (violations.length === 0) return "";
+	return contextResponse("PostToolUse", `SOLID COMPLIANCE CHECK: ${filePath.split("/").pop() ?? filePath}\n\n${violations.join("\n")}\nINSTRUCTION: Fix violations before continuing.\nRun sniper agent for full validation.`);
+}
+//#endregion
+//#region src/runtime/lifecycle/aipilot/solid-transcript.ts
+/**
+* SubagentStop (matcher "") for the ai-pilot scope: check SOLID file-size and
+* interface-location compliance for every file a sub-agent wrote/edited, per
+* the transcript. Ports `check-solid-from-transcript.py`. Fires unconditionally
+* for every sub-agent, unlike the sniper/research-expert-scoped caches here.
+*/
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|dart|vue|svelte|astro)$/;
+const INTERFACE_PATTERN = /^(export )?(interface|type) [A-Z]/m;
+const INTERFACE_DIRS = [
+	"components/",
+	"pages/",
+	"views/",
+	"app/"
+];
+/**
+* Check every Write/Edit target in a subagent transcript against the SOLID
+* line-count ceiling and interface-location convention.
+* @param transcript - Path to the agent JSONL transcript (`agent_transcript_path`).
+* @returns The SubagentStop `additionalContext` response, or `""` when clean.
+*/
+async function checkSolidFromTranscript(transcript) {
+	if (!transcript || !pathExists(transcript)) return "";
+	const files = await transcriptFilePaths(transcript, ["Write", "Edit"]);
+	const max = resolveMaxLines();
+	const violations = [];
+	for (const fp of files.sort()) {
+		if (!pathExists(fp) || !CODE_EXTENSIONS.test(fp)) continue;
+		const name = fp.split("/").pop() ?? fp;
+		let content;
+		try {
+			content = readText(fp);
+		} catch {
+			continue;
+		}
+		const lc = countCodeLines(content);
+		if (lc > max) violations.push(`SOLID: ${name} = ${lc} lines (max ${max})`);
+		if (INTERFACE_DIRS.some((prefix) => fp.includes(prefix)) && INTERFACE_PATTERN.test(content)) violations.push(`SOLID: ${name}: move interfaces to interfaces/`);
+	}
+	if (violations.length === 0) return "";
+	return contextResponse("SubagentStop", `## SOLID VIOLATIONS DETECTED (subagent output)\n${violations.join("\n")}\nRun sniper to fix these issues.`);
+}
+//#endregion
 //#region src/runtime/lifecycle/aipilot/dispatch-aipilot.ts
 /**
 * ai-pilot scope dispatcher: routes Claude lifecycle events to the ported
@@ -2726,19 +2867,16 @@ async function onSubagentStart(payload, cwd, now) {
 	const agent = agentTypeOf(payload);
 	return combineContext(await injectApexSubagentContext(cwd), await injectLessonsCache(cwd, void 0, now), await typeSpecificCache(agent, cwd, now));
 }
-/** SubagentStop routing: transcript-driven cache writers (side-effects). */
+/** SubagentStop routing: transcript-driven cache writers, then the universal SOLID check. */
 async function onSubagentStop(payload, cwd) {
 	const agent = agentTypeOf(payload);
 	const transcript = transcriptOf(payload);
-	if (agent.includes("research-expert")) {
-		await cacheDocFromTranscript(transcript, cwd);
-		return "";
-	}
+	if (agent.includes("research-expert")) await cacheDocFromTranscript(transcript, cwd);
 	if (agent.includes("sniper")) {
 		await cacheSniperLessons(transcript, cwd);
 		await cacheTestResults(transcript, cwd);
 	}
-	return "";
+	return checkSolidFromTranscript(transcript);
 }
 /**
 * Dispatch an ai-pilot-scope lifecycle event. Returns the native stdout, or
@@ -2751,11 +2889,12 @@ async function dispatchAipilot(event, payload, cwd, now) {
 		await cacheAnalyticsSave(void 0, now);
 		return "";
 	}
+	if (event === "PreToolUse") return docCacheGate(payload, cwd, now);
 	return null;
 }
-/** PostToolUse (TaskCreate/TaskUpdate) sync for the ai-pilot scope. */
+/** PostToolUse (Write/Edit SOLID check, else TaskCreate/TaskUpdate sync) for the ai-pilot scope. */
 async function aipilotPostToolUse(payload, cwd) {
-	return syncTaskTracking(payload, cwd);
+	return checkSolidCompliance(payload) || await syncTaskTracking(payload, cwd);
 }
 //#endregion
 //#region src/runtime/lifecycle/dispatch.ts
@@ -3278,11 +3417,76 @@ function seoPostToolUseResponse(payload) {
 	return block ? blockResponse(block) : null;
 }
 //#endregion
+//#region src/runtime/lifecycle/auto-document-reads.ts
+/**
+* PostToolUse (matcher "Read") for the core scope: auto-document important
+* reads (SKILL.md/README/CLAUDE.md/docs/references) into
+* `.claude/apex/docs/task-<current>-<framework>.md`, once per file per task.
+* Ports `post-tool-use/auto-document-reads.py`.
+*/
+/** Read-tool file paths worth auto-documenting. */
+const DOC_PATTERNS = [
+	/(SKILL\.md|README\.md|CLAUDE\.md)$/,
+	/\/docs\/.*\.md$/,
+	/\/references\/.*\.md$/,
+	/skills\/[^/]+\/SKILL\.md$/
+];
+/** First matching marker (in order) labels the doc-type; "File" otherwise. */
+const TYPE_MAP = [
+	["SKILL.md", "Skill"],
+	["README.md", "README"],
+	["CLAUDE.md", "Rules"],
+	["/references/", "Reference"],
+	["/docs/", "Doc"]
+];
+/** The doc-type label for a matched file path. */
+function docTypeOf(filePath) {
+	return TYPE_MAP.find(([marker]) => filePath.includes(marker))?.[1] ?? "File";
+}
+/**
+* Auto-document a Read of a SKILL.md/README/CLAUDE.md/docs/references file
+* into `.claude/apex/docs/task-<current>-<framework>.md` (skipped when the
+* file is already logged, or no project root is found from `filePath`).
+* @param filePath - The path passed to the Read tool.
+* @param now - Clock (defaults to `Date.now()`).
+* @returns The native `systemMessage` stdout, or "" when nothing was logged.
+*/
+async function autoDocumentRead(filePath, now = Date.now()) {
+	if (!filePath || !DOC_PATTERNS.some((p) => p.test(filePath))) return "";
+	const root = projectRootOrNull(dirname(filePath));
+	if (!root) return "";
+	const framework = detectProjectType$1(root);
+	const current = (await readJsonFile(join(root, ".claude", "apex", "task.json")))?.current_task ?? "1";
+	const docDir = join(root, ".claude", "apex", "docs");
+	const docFile = join(docDir, `task-${current}-${framework}.md`);
+	const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+	const fname = basename(filePath);
+	const docType = docTypeOf(filePath);
+	try {
+		mkdirSync(docDir, { recursive: true });
+		if (!existsSync(docFile)) writeFileSync(docFile, `# Task ${current} - ${framework.charAt(0).toUpperCase() + framework.slice(1)} Documentation\n## Consulted: ${ts} | Source: skill:Read\n## Key Info\n\n`, "utf-8");
+		if (readFileSync(docFile, "utf-8").includes(`\`${fname}\``)) return "";
+		appendFileSync(docFile, `- **[${docType}]** \`${fname}\` - ${ts}\n`, "utf-8");
+	} catch {
+		return "";
+	}
+	return systemMessage(`📖 [${docType}] ${fname} logged`);
+}
+//#endregion
 //#region src/runtime/lifecycle-bridge.ts
 /** Raw event name from a payload (Cline lacks one; lifecycle is Claude-only). */
 function rawEvent(payload) {
 	return typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
 }
+/** Extract the `additionalContext` body from a `contextResponse(...)` stdout string ("" when empty/unparseable). */
+function additionalContextOf(stdout) {
+	if (!stdout) return "";
+	try {
+		return JSON.parse(stdout).hookSpecificOutput?.additionalContext ?? "";
+	} catch {
+		return "";
+	}
+}
 /**
 * Run the ported lifecycle/session/context hooks (SessionStart, SubagentStart/
 * Stop, TeammateIdle, PostToolUseFailure, PreCompact, SessionEnd,
@@ -3304,18 +3508,25 @@ function lifecycleStdout(payload, cwd, scope, now) {
 	});
 }
 /**
-* Post-edit additions for core-scope PostToolUse Write/Edit: track cumulative
-* session changes (sniper reminder) + report eslint/prettier issues. Returns the
-* combined extra stdout (track-changes wins; lint appended only when no track
-* output), or "" when nothing to emit.
+* Post-edit additions for core-scope PostToolUse: auto-document a Read of a
+* SKILL.md/README/docs file; else (Write/Edit) track cumulative session
+* changes (sniper reminder) AND report eslint/prettier issues — parity
+* core-guards hooks.json, which runs both as independent PostToolUse commands
+* rather than short-circuiting one on the other. Returns the combined extra
+* stdout, or "" when nothing to emit.
 * @param scope - The invoking plugin scope.
 * @param event - The normalized event.
 * @param now - Clock.
 * @returns The extra stdout (possibly empty).
 */
-function postEditContext(scope, event, now) {
-	if (scope !== "core" || event.tool !== "Write" && event.tool !== "Edit" || !event.filePath) return "";
-	return trackSessionChanges(event.sessionId, event.filePath, void 0, now) || postEditTypescript(event.filePath);
+async function postEditContext(scope, event, now) {
+	if (scope !== "core" || !event.filePath) return "";
+	if (event.tool === "Read") return autoDocumentRead(event.filePath, now);
+	if (event.tool !== "Write" && event.tool !== "Edit") return "";
+	const sniper = trackSessionChanges(event.sessionId, event.filePath, void 0, now);
+	const lint = postEditTypescript(event.filePath);
+	if (!sniper || !lint) return sniper || lint;
+	return contextResponse("PostToolUse", `${additionalContextOf(sniper)}\n\n${additionalContextOf(lint)}`);
 }
 //#endregion
 //#region src/runtime/gate-helpers.ts
@@ -3341,20 +3552,21 @@ function isApexScoped(filePath) {
 	return !EXEMPT_PATTERNS.some((p) => p.test(filePath));
 }
 /**
-* Code-only line count of the existing on-disk file (undefined if
-* absent/unreadable). Uses {@link countLines} (skips blank/comment lines) so a
-* partial Edit judges the full file by the SAME metric as the incoming snippet —
-* a raw `split("\n").length` would over-count JSDoc/blank lines (and add a
-* trailing-newline off-by-one), falsely blocking well-documented files.
+* Read `path` once and derive both line-count metrics, so the generic
+* core-guards ceiling (`raw`) and the framework SOLID gates (`code`) each get
+* the metric their own Python origin measures, without reading the file twice.
 * @param path - Absolute path of the file being edited (or undefined).
-* @returns Code-only line count, or undefined when the file is absent/unreadable.
 */
-function existingLineCount(path) {
-	if (!path) return void 0;
+function existingLineCounts(path) {
+	if (!path || !existsSync(path)) return {};
 	try {
-		return existsSync(path) ? countLines(readFileSync(path, "utf8")) : void 0;
+		const content = readFileSync(path, "utf8");
+		return {
+			raw: countLines(content),
+			code: countFrameworkCodeLines(content)
+		};
 	} catch {
-		return;
+		return {};
 	}
 }
 //#endregion
@@ -3486,15 +3698,29 @@ function detectDuplication(filePath, content, cwd) {
 		duplicates
 	};
 }
-/** Blocking prompt when a Write/Edit re-declares 2+ existing symbols, else null. */
+/**
+* Prompt when a Write/Edit re-declares an existing symbol: a single match is a
+* softer non-blocking "inform" (could be a false positive / same-name coincidence),
+* escalating to a hard "block" once 2+ existing declarations are found. Returns
+* `null` when no duplicate symbol is found at all.
+*/
 function dryGate(tool, filePath, content, cwd) {
 	if (!cwd || tool !== "Write" && tool !== "Edit" || !content) return null;
 	const dup = detectDuplication(filePath, content, cwd);
-	if (dup.duplicates.length < 2) return null;
+	if (dup.duplicates.length === 0) return null;
+	const names = dup.names.slice(0, 5).join(", ");
+	let files = dup.duplicates.slice(0, 3).join(", ");
+	if (dup.duplicates.length > 3) files += ` (+${dup.duplicates.length - 3} more)`;
+	if (dup.duplicates.length === 1) return {
+		kind: "inform",
+		title: "Possible duplicate code (DRY)",
+		reason: `[${names}] already declared in: ${files}. Consider importing and reusing instead of re-declaring.`,
+		actions: ["Import the existing symbol instead of re-declaring it", "Extend the existing module"]
+	};
 	return {
 		kind: "block",
 		title: "Duplicate code (DRY)",
-		reason: `[${dup.names.slice(0, 5).join(", ")}] already declared in: ${dup.duplicates.slice(0, 3).join(", ")}. Import and reuse instead of re-declaring.`,
+		reason: `[${names}] already declared in: ${files}. Import and reuse instead of re-declaring.`,
 		actions: ["Import the existing symbol instead of re-declaring it", "Extend the existing module"]
 	};
 }
@@ -3609,15 +3835,15 @@ const block$1 = (reason) => ({
 function nextModular(filePath, content, cwd) {
 	const rel = relative(cwd, filePath);
 	const bn = basename(filePath);
-	if ((rel.startsWith("app/") || rel.startsWith("src/app/")) && !NEXT_CONVENTION.test(bn) && !NEXT_STATIC.test(bn)) return block$1(`BLOCKED: modular Next.js — '${bn}' is not an app/ convention file. Move business logic to modules/[feature]/.`);
+	if ((rel.startsWith("app/") || rel.startsWith("src/app/")) && !NEXT_CONVENTION.test(bn) && !NEXT_STATIC.test(bn)) return block$1(`BLOCKED: modular Next.js — '${bn}' is not an app/ convention file. Move business logic to modules/[feature]/. Only page.tsx, layout.tsx, route.ts allowed in app/.`);
 	const mod = filePath.match(/\/modules\/([^/]+)\//);
 	if (!mod) return null;
 	const current = mod[1] ?? "";
 	for (const m of content.matchAll(/from\s+['"][@.][^'"]*?\/modules\/([^/]+)\//g)) {
 		const imported = m[1] ?? "";
 		if (current === "cores") {
-			if (imported !== "cores" && imported !== "core") return block$1(`BLOCKED: modules/cores/ must not import from modules/${imported}/.`);
-		} else if (imported !== current && imported !== "cores" && imported !== "core") return block$1(`BLOCKED: cross-module import — '${current}' imports '${imported}'. Only modules/cores/ is shared.`);
+			if (imported !== "cores" && imported !== "core") return block$1(`BLOCKED: modules/cores/ must not import from modules/${imported}/. Cores must be independent.`);
+		} else if (imported !== current && imported !== "cores" && imported !== "core") return block$1(`BLOCKED: cross-module import — '${current}' imports from '${imported}'. Only modules/cores/ is shared.`);
 	}
 	return null;
 }
@@ -3649,17 +3875,22 @@ function modularGate(tool, filePath, content, cwd) {
 //#region src/runtime/framework-skill-gate.ts
 /**
 * Effective line count for the SOLID size check. On an Edit, `content` is only
-* the `new_string` snippet, so judge the larger of the snippet and the full
-* on-disk file (`existingLines`) — mirroring the base file-size guard and the
-* Python `get_full_file_content`. On Write, `content` IS the full file, so the
-* snippet count stands (undefined → the gate falls back to `countLines`).
+* the `new_string` snippet, so for Next.js — mirroring the base file-size guard
+* and the Python `get_full_file_content` — judge the larger of the snippet and
+* the full on-disk file (`existingCodeLines`). Other frameworks (react/laravel/
+* swift) judge the edited snippet alone, never the on-disk full-file max — their
+* Python source never imports `get_full_file_content`, only nextjs does. On
+* Write, `content` IS the full file, so the snippet count stands regardless of
+* framework (undefined → the gate falls back to `countFrameworkCodeLines`).
 * @param tool - the tool name ("Edit" | "Write" | ...).
+* @param framework - the detected framework; only "nextjs" applies the full-file max.
 * @param content - the written content (snippet on Edit, full file on Write).
-* @param existingLines - full on-disk line count, when known.
+* @param existingCodeLines - full on-disk code-only line count, when known.
 */
-function effectiveLines(tool, content, existingLines) {
-	if (tool !== "Edit" || existingLines === void 0) return void 0;
-	return Math.max(countLines(content), existingLines);
+function effectiveLines(tool, framework, content, existingCodeLines) {
+	if (tool !== "Edit" || existingCodeLines === void 0) return void 0;
+	if (framework !== "nextjs") return countFrameworkCodeLines(content);
+	return Math.max(countFrameworkCodeLines(content), existingCodeLines);
 }
 /**
 * Framework-aware SOLID + sub-skill gate, run on the Write/Edit path once a
@@ -3672,17 +3903,156 @@ function effectiveLines(tool, content, existingLines) {
 *
 * @param input - the gated tool-use (filePath + content + framework + cwd).
 * @param refsRead - in-session read reference paths (from the loaded track).
-* @param existingLines - full on-disk line count (so an Edit on an oversized
-*   file still fires the framework SOLID size rule). Omit on Write.
+* @param existingCodeLines - full on-disk code-only line count (so an Edit on
+*   an oversized file still fires the framework SOLID size rule). Omit on Write.
 * @returns the first blocking {@link Prompt}, or `null` to allow.
 */
-function frameworkSkillGate(input, refsRead, existingLines) {
+function frameworkSkillGate(input, refsRead, existingCodeLines) {
 	if (!input.filePath) return null;
 	const content = input.content ?? "";
-	const solid = frameworkSolidGate(input.filePath, content, effectiveLines(input.tool, content, existingLines));
+	const solid = frameworkSolidGate(input.filePath, content, effectiveLines(input.tool, input.framework, content, existingCodeLines));
 	if (solid) return solid;
 	const forced = input.cwd ? requiredArchSkill(input.cwd) : null;
-	return skillTriggerGate(input.framework, content, refsRead, forced, input.cwd);
+	return skillTriggerGate(input.framework, content, refsRead, forced, input.cwd, input.filePath);
+}
+//#endregion
+//#region src/policy/shadcn-skill-gate.ts
+/** File extensions the shadcn gate polices (source: `\.(tsx|jsx|css|scss|json)$`). */
+const SHADCN_FILE_RE = /\.(tsx|jsx|css|scss|json)$/;
+/**
+* Vendored/build paths exempt from the gate. Uses `(^|\/)` (not just a
+* leading `/`) so a relative root-start path like `node_modules/x` is also
+* exempt — mirrors the same deliberate widening already applied in
+* `design/skill-gate.ts`'s `EXEMPT_RE`, not the Python's stricter `/x/`-only match.
+*/
+const EXEMPT_RE$1 = /(^|\/)(node_modules|dist|build)\//;
+/** Path fragments that put a write in shadcn scope (source: `(components|ui|shadcn|components\.json)`). */
+const SHADCN_PATH_RE = /(components|ui|shadcn|components\.json)/;
+/** A read reference proving one of the two named base skills was consulted (Phase 1). */
+const SHADCN_BASE_SKILL_RE = /skills\/(shadcn-detection|shadcn-components)\//;
+/** Session `authorizations` source proving a live `mcp__shadcn__*` call was made this session (Phase 1, option 3). */
+const SHADCN_MCP_SOURCE_RE = /shadcn-mcp/i;
+/**
+* True when this Write/Edit is shadcn-scoped: a `.tsx/.jsx/.css/.scss/.json`
+* file under a `components|ui|shadcn|components.json` path, outside vendored
+* dirs. Ports `check-skill-loaded.py`'s file-path filter (lines 35-42).
+*/
+function isShadcnWrite(tool, filePath) {
+	if (tool !== "Write" && tool !== "Edit") return false;
+	if (!SHADCN_FILE_RE.test(filePath) || EXEMPT_RE$1.test(filePath)) return false;
+	return SHADCN_PATH_RE.test(filePath);
+}
+/** True when `shadcn-detection/` or `shadcn-components/` was read this session (Phase 1 base skill). */
+function shadcnBaseSkillRead(refsRead) {
+	return refsRead.some((p) => SHADCN_BASE_SKILL_RE.test(p));
+}
+/** True when a `mcp__shadcn__*` tool call was recorded this session (Phase 1's 3rd unblock option). */
+function shadcnMcpConsulted(authorizations, sessionId) {
+	if (!authorizations) return false;
+	return Object.values(authorizations).some((a) => a.doc_sessions?.includes(sessionId) && (a.sources ?? (a.source ? [a.source] : [])).some((s) => SHADCN_MCP_SOURCE_RE.test(s)));
+}
+/**
+* Gate a shadcn-scoped write. Phase 1 requires a base skill read
+* (shadcn-detection or shadcn-components); Phase 2 requires the domain
+* sub-skill(s) matching the written content, via {@link skillTriggerGate}
+* keyed on the "shadcn" framework (registered in `SKILL_TRIGGERS`); Phase 3
+* requires doc research, delegated to the existing {@link docConsultedGate}
+* (Context7 AND Exa, or a web fallback alone — not the Python's strict AND).
+* Returns a blocking {@link Prompt}, or `null` to allow.
+*/
+function shadcnSkillGate(tool, filePath, content, ev) {
+	if (!isShadcnWrite(tool, filePath)) return null;
+	if (!shadcnBaseSkillRead(ev.refsRead) && !shadcnMcpConsulted(ev.authorizations, ev.sessionId)) return {
+		kind: "block",
+		title: "shadcn/ui skill",
+		reason: "BLOCKED: shadcn skill not consulted. Read shadcn-detection/SKILL.md or shadcn-components/SKILL.md, or use mcp__shadcn__search_items_in_registries, then retry.",
+		actions: ["Read skills/shadcn-detection/ or skills/shadcn-components/, or call mcp__shadcn__search_items_in_registries, then retry"]
+	};
+	const domainBlock = skillTriggerGate("shadcn", content, ev.refsRead);
+	if (domainBlock) return domainBlock;
+	return docConsultedGate({
+		sessionId: ev.sessionId,
+		framework: "shadcn",
+		filePath,
+		content,
+		authorizations: ev.authorizations
+	});
+}
+//#endregion
+//#region src/freshness/explore-tools.ts
+/** Native exploration tools (parity `apex_constants.EXPLORE_TOOLS`). */
+const EXPLORE_TOOLS = /* @__PURE__ */ new Set(["Glob", "Grep"]);
+/** Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`). */
+const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
+	"mcp__context7__query-docs",
+	"mcp__context7__resolve-library-id",
+	"mcp__exa__web_search_exa",
+	"mcp__exa__get_code_context_exa",
+	"mcp__exa__deep_researcher_start",
+	"WebSearch",
+	"WebFetch"
+]);
+/** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
+const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
+	"grep",
+	"rg",
+	"find",
+	"ls",
+	"fd",
+	"ast-grep",
+	"tree",
+	"cat",
+	"head",
+	"tail"
+]);
+/** Cached MCP result reads count as research (parity `CACHE_READ_RE` + doc-helpers). */
+const CACHE_READ_RE = /\/context\/mcp\/(exa-search|exa-code-context|context7)-/;
+/**
+* First non-assignment shell token's basename, or "" — mirrors Python
+* `_bash_executable` (skips leading `VAR=value` env prefixes, e.g. `FOO=1 grep`).
+* @param cmd - Raw Bash `command` string.
+* @returns The executable basename, or "" when none.
+*/
+function bashExecutable(cmd) {
+	for (const token of cmd.trim().split(/\s+/)) {
+		if (!token) continue;
+		const last = token.split("/").pop() ?? token;
+		if (!last.includes("=")) return last;
+	}
+	return "";
+}
+/**
+* Classify a direct tool use into an APEX phase, or `null` when it is neither
+* exploration nor research. Mirrors Python `track-subagent-research._classify`.
+* @param tool - Harness tool name (e.g. "Glob", "Bash", "WebSearch").
+* @param input - Tool input payload.
+* @returns The credited phase + cache flag, or `null`.
+*/
+function classifyExplore(tool, input) {
+	if (RESEARCH_TOOLS.has(tool)) return {
+		phase: "research-expert",
+		cacheHit: false
+	};
+	if (EXPLORE_TOOLS.has(tool)) return {
+		phase: "explore-codebase",
+		cacheHit: false
+	};
+	if (tool === "Read") {
+		const path = String(input?.file_path ?? input?.path ?? "");
+		if (path && CACHE_READ_RE.test(path)) return {
+			phase: "research-expert",
+			cacheHit: true
+		};
+		return null;
+	}
+	if (tool === "Bash") {
+		const cmd = String(input?.command ?? "").trim();
+		if (EXPLORE_BASH_CMDS.has(bashExecutable(cmd))) return {
+			phase: "explore-codebase",
+			cacheHit: false
+		};
+	}
+	return null;
 }
 //#endregion
 //#region src/freshness/agent-evidence.ts
@@ -3701,9 +4071,13 @@ function parseTs(raw) {
 }
 /**
 * Return `true` ONLY when, for EVERY name in `names`, the Claude Code
-* transcript at `transcriptPath` contains a genuine `tool_use` of the `Task` or
-* `Agent` tool whose `subagent_type` (or `name`) input field matches — after
-* stripping any plugin prefix — with the entry timestamp within `windowMs` of `now`.
+* transcript at `transcriptPath` contains a genuine `tool_use` of the `Task`/
+* `Agent` tool whose `subagent_type` (or `name`) matches — after stripping any
+* plugin prefix — OR a direct exploration/research tool_use (Glob/Grep, an
+* explore Bash command, mcp__context7/mcp__exa, WebSearch/WebFetch) classified
+* via {@link classifyExplore} into that name, issued by ANY sub-agent or the
+* lead within this same transcript — with the entry timestamp within
+* `windowMs` of `now`.
 *
 * **Timestamp note:** when a transcript entry carries no `timestamp` field it
 * is counted as within-window (we cannot prove staleness). This is
@@ -3741,10 +4115,15 @@ function agentsRanFromTranscript(transcriptPath, names, windowMs, now) {
 		const content = entry.message?.content;
 		if (!Array.isArray(content)) continue;
 		for (const block of content) {
-			if (block?.type !== "tool_use" || block.name !== "Task" && block.name !== "Agent") continue;
-			const raw = block.input?.subagent_type ?? block.input?.name;
-			const agent = typeof raw === "string" ? raw.split(":").pop() ?? raw : void 0;
-			if (agent !== void 0 && names.includes(agent)) found.add(agent);
+			if (block?.type !== "tool_use") continue;
+			if (block.name === "Task" || block.name === "Agent") {
+				const raw = block.input?.subagent_type ?? block.input?.name;
+				const agent = typeof raw === "string" ? raw.split(":").pop() ?? raw : void 0;
+				if (agent !== void 0 && names.includes(agent)) found.add(agent);
+				continue;
+			}
+			const hit = classifyExplore(block.name ?? "", block.input);
+			if (hit && names.includes(hit.phase)) found.add(hit.phase);
 		}
 		if (found.size === names.length) return true;
 	}
@@ -3765,7 +4144,7 @@ function agentsRanFromTranscript(transcriptPath, names, windowMs, now) {
 */
 async function apexScopedGate(input, track, window) {
 	const lineCount = input.content === void 0 ? Number.POSITIVE_INFINITY : input.content.split("\n").length;
-	if (!input.isReplaceAll && lineCount < 5 && trivialCount(track, window, input.now) < 4) {
+	if (input.tool === "Edit" && !input.isReplaceAll && lineCount < 5 && trivialCount(track, window, input.now) < 4) {
 		await saveTrack(input.trackFile, recordTrivialEdit(track, input.now, window, input.now));
 		return null;
 	}
@@ -3779,7 +4158,9 @@ async function apexScopedGate(input, track, window) {
 		refs: input.refs,
 		refsRead: track.refsRead,
 		agentsFresh: freshnessFor([...REQUIRED_AGENTS]),
-		brainstormRequired: track.brainstormRequired,
+		missingAgents: REQUIRED_AGENTS.filter((name) => !freshnessFor([name])),
+		windowMs: window,
+		brainstormRequired: input.tool === "Edit" ? false : track.brainstormRequired,
 		brainstormFresh: freshnessFor(["brainstorming"], Number.MAX_SAFE_INTEGER)
 	};
 	try {
@@ -3792,7 +4173,12 @@ async function apexScopedGate(input, track, window) {
 //#region src/runtime/gate.ts
 /** Prior agents the freshness gate requires before a code edit. */
 const REQUIRED_AGENTS = ["explore-codebase", "research-expert"];
-/** Default freshness window for {@link REQUIRED_AGENTS} (2 min — matches the plugin's `FUSE_ENFORCE_TTL_SEC` default). */
+/**
+* Default freshness window for {@link REQUIRED_AGENTS}, in ms. Matches the
+* plugin's `FUSE_ENFORCE_TTL_SEC` default (120s). Only a fallback for direct
+* programmatic callers that omit `windowMs` (e.g. tests) — the real CLI path
+* always supplies `windowMs` from `resolveTtlSec()` (`src/config/ttl.ts`).
+*/
 const DEFAULT_WINDOW_MS = 12e4;
 /** Trivial edits allowed within the window before the full APEX gates apply. */
 const TRIVIAL_BUDGET = 4;
@@ -3804,7 +4190,7 @@ const TRIVIAL_BUDGET = 4;
 async function gate(input) {
 	const precommit = preCommitGate(input.tool, input.command, input.cwd);
 	if (precommit) return precommit;
-	const existingLines = existingLineCount(input.filePath);
+	const { raw: existingLines, code: existingCodeLines } = existingLineCounts(input.filePath);
 	let quick;
 	try {
 		quick = evaluate({
@@ -3822,10 +4208,19 @@ async function gate(input) {
 	const modular = modularGate(input.tool, input.filePath, input.content, input.cwd);
 	if (modular) return modular;
 	if (!input.filePath) return null;
+	const filePath = input.filePath;
 	const window = input.windowMs ?? 12e4;
 	const track = await loadTrack(input.trackFile);
-	const solidOrSkill = frameworkSkillGate(input, track.refsRead, existingLines);
+	const solidOrSkill = frameworkSkillGate(input, track.refsRead, existingCodeLines);
 	if (solidOrSkill) return solidOrSkill;
+	if (isShadcnWrite(input.tool, filePath)) {
+		const shadcnBlock = shadcnSkillGate(input.tool, filePath, input.content ?? "", {
+			refsRead: track.refsRead,
+			authorizations: track.authorizations,
+			sessionId: input.sessionId
+		});
+		if (shadcnBlock) return shadcnBlock;
+	}
 	if (isApexScoped(input.filePath)) {
 		const apex = await apexScopedGate(input, track, window);
 		if (apex) return apex;
@@ -3896,6 +4291,16 @@ function docSourceOf$1(tool) {
 	if (/context7/i.test(tool)) return "context7";
 }
 /**
+* Wrap a cache hit's body in the harness-facing `CACHE HIT` notice — parity with
+* `webfetch-cache-lookup.py` / `mcp-cache-lookup.py` (KB = body chars/1024 + 1,
+* age hours = ageMs/3_600_000, both floored).
+*/
+function cacheHitText(web, hit) {
+	const kb = Math.floor(hit.body.length / 1024) + 1;
+	const hours = Math.floor(hit.ageMs / 36e5);
+	return web ? `CACHE HIT WebFetch (~${kb}KB economise, cached il y a ${hours}h):\n\n${hit.body}\n\nPour forcer un nouveau fetch, modifie l'URL ou la query.` : `CACHE HIT (~${kb}KB economise, cached il y a ${hours}h): ${hit.body}\n\nReformule pour forcer un re-call.`;
+}
+/**
 * Pre-event MCP interception: serve a fresh cache hit (deny + cached content),
 * else cap exa verbosity (allow + mutated input), else null to allow normally.
 * Harnesses without input-mutation/cache support fall through to null.
@@ -3905,9 +4310,9 @@ function mcpPreIntercept(id, tool, input, dir, ttlMs, now) {
 	const web = isWebFetch(tool);
 	const ttl = web ? WEBFETCH_TTL_MS : ttlMs;
 	const key = cacheQueryOf(tool, input);
-	const cached = cacheLookup(dir, tool, key, ttl, now) ?? (web ? null : cacheLookupSubstring(dir, key, ttl, now));
-	if (cached) {
-		const served = denyWith(id, cached);
+	const hit = cacheLookupMeta(dir, tool, key, ttl, now) ?? (web ? null : cacheLookupSubstringMeta(dir, key, ttl, now));
+	if (hit) {
+		const served = denyWith(id, cacheHitText(web, hit));
 		if (served) return {
 			stdout: served,
 			docSource: docSourceOf$1(tool)
@@ -3943,31 +4348,51 @@ async function recordActivity(file, activity) {
 //#endregion
 //#region src/runtime/respond.ts
 /**
-* Map a portable {@link Prompt} to a harness's native hook response. `block`
-* denies; anything else asks/injects context. (Codex/Cursor parse but ignore
-* `ask` — they only honor deny.)
+* Map a portable {@link Prompt} to a harness's native hook response, honoring
+* all 3 prompt kinds (`block`/`ask`/`inform`) instead of collapsing `ask` and
+* `inform` together. Reuses the Claude adapter's `denyResponse`/
+* `contextResponse` builders for claude-code/codex (same hook shape) to avoid
+* duplicating the JSON.
+* - claude-code/codex: `block` -> deny, `ask` -> interactive
+*   `permissionDecision:"ask"`, `inform` -> non-blocking `additionalContext`.
+* - gemini-cli/cline: their real hook schemas have no interactive "ask"
+*   state (deny is the only blocking outcome), so `ask` and `inform` already
+*   both resolve to non-blocking context injection — unchanged.
+* - cursor: `ask` keeps its current best-effort `permission:"ask"` shape
+*   (unverified against Cursor's exact hook docs); only `inform` is fixed to
+*   a non-blocking `permission:"allow"` note, since it was wrongly conflated
+*   with `ask` before.
 */
 function respond(id, prompt) {
 	const message = formatPrompt(prompt);
-	const deny = prompt.kind === "block";
+	const { kind } = prompt;
 	switch (id) {
 		case "claude-code":
-		case "codex": return JSON.stringify({ hookSpecificOutput: {
-			hookEventName: "PreToolUse",
-			permissionDecision: deny ? "deny" : "ask",
-			permissionDecisionReason: message
-		} });
-		case "gemini-cli": return JSON.stringify(deny ? {
+		case "codex":
+			if (kind === "block") return denyResponse("PreToolUse", message);
+			if (kind === "inform") return contextResponse("PreToolUse", message);
+			return JSON.stringify({ hookSpecificOutput: {
+				hookEventName: "PreToolUse",
+				permissionDecision: "ask",
+				permissionDecisionReason: message
+			} });
+		case "gemini-cli": return JSON.stringify(kind === "block" ? {
 			decision: "deny",
 			reason: message
 		} : { hookSpecificOutput: { additionalContext: message } });
-		case "cursor": return JSON.stringify({
-			permission: deny ? "deny" : "ask",
-			continue: false,
-			userMessage: message,
-			agentMessage: message
-		});
-		case "cline": return JSON.stringify(deny ? {
+		case "cursor":
+			if (kind === "inform") return JSON.stringify({
+				permission: "allow",
+				userMessage: message,
+				agentMessage: message
+			});
+			return JSON.stringify({
+				permission: kind === "block" ? "deny" : "ask",
+				continue: false,
+				userMessage: message,
+				agentMessage: message
+			});
+		case "cline": return JSON.stringify(kind === "block" ? {
 			cancel: true,
 			errorMessage: message
 		} : { contextModification: message });
@@ -4019,6 +4444,65 @@ function runDesignChecks(content) {
 	];
 }
 //#endregion
+//#region src/policy/design/skill-triggers.ts
+/** Domain skill triggers (ported 1:1 from `design_skill_triggers.py`). */
+const SKILL_TRIGGERS = [
+	{
+		skill: "3-generating-components",
+		readFragment: "generating-components",
+		patterns: [
+			/className\s*=\s*["{]/i,
+			/<(div|section|main|header|footer|nav|aside)\s/i,
+			/flex|grid|gap-|p-|m-|bg-|text-|rounded|shadow|border/i,
+			/(Button|Card|Dialog|Sheet|Input|Select|Table)\b/i,
+			/cva|class-variance-authority|variants\b/i,
+			/VariantProps|variant.*:\s*\{/i,
+			/children|slots|asChild|Slot|render.?prop/i,
+			/forwardRef|React\.cloneElement|compound/i
+		]
+	},
+	{
+		skill: "1-designing-systems",
+		readFragment: "designing-systems",
+		patterns: [
+			/--(\w+-)+color:|:root\s*\{|@theme\b/i,
+			/design.?system|token|palette|typography.?scale/i,
+			/--(\w+)-(foreground|background|primary|muted|accent):/i,
+			/cssVariables|themeConfig|colorScheme/i,
+			/dark:|prefers-color-scheme|next-themes|useTheme/i,
+			/ThemeProvider|data-theme|color-scheme/i,
+			/sm:|md:|lg:|xl:|2xl:/i,
+			/@container|container-type|@media/i,
+			/clamp\(|fluid|min-width:/i
+		]
+	},
+	{
+		skill: "4-adding-animations",
+		readFragment: "adding-animations",
+		patterns: [
+			/motion\.|framer-motion|animate|variants/i,
+			/whileHover|whileTap|AnimatePresence|transition/i,
+			/@keyframes\b|animation:\s/i,
+			/backdrop-blur|bg-.*\/([\d]+)|glass/i,
+			/backdrop-filter:\s*blur/i,
+			/hover:|focus:|active:|disabled:|focus-visible:/i,
+			/data-\[state=|data-\[disabled\]/i,
+			/bg-gradient|from-|via-|to-/i,
+			/radial-gradient|conic-gradient|bg-\[url/i,
+			/blur-.*xl|opacity-|mix-blend/i
+		]
+	},
+	{
+		skill: "5-design-audit",
+		readFragment: "design-audit",
+		patterns: [/aria-|role=|sr-only|tabIndex|alt=/i, /WCAG|a11y|contrast|screen.?reader/i]
+	}
+];
+/** Return the domain skills required by `content` but NOT present in `refsRead`. */
+function missingDomainSkills(content, refsRead) {
+	return SKILL_TRIGGERS.filter((t) => t.patterns.some((re) => re.test(content))).filter((t) => !refsRead.some((p) => p.includes(t.readFragment))).map((t) => t.skill);
+}
+//#endregion
 //#region src/policy/design/skill-gate.ts
 /** UI source files the gate polices (.html/.css are handled by the pipeline gate, not here). */
 const UI_FILE_RE = /\.(tsx|jsx|scss|vue|svelte)$/;
@@ -4057,7 +4541,9 @@ const block = (reason, action) => ({
 function uiDesignSkillGate(tool, filePath, content, ev) {
 	if (!isUiWrite(tool, filePath, content)) return null;
 	if (!designSkillRead(ev.refsRead)) return block("BLOCKED: design skill not consulted before writing UI. Read a design SKILL.md (solid-react, generating-components, or designing-systems), then retry.", "Read a design skill reference, then retry");
-	if (!ev.docConsulted) return block("BLOCKED: no documentation consulted. Use ANY ONE of mcp__context7__query-docs, mcp__exa__web_search_exa, WebSearch, or WebFetch. Gemini is NOT required.", "Consult Context7, Exa, or web docs (Gemini not required), then retry");
+	const missing = missingDomainSkills(content, ev.refsRead);
+	if (missing.length) return block(`BLOCKED: code uses ${missing.join(", ")} but the matching design skill(s) were not consulted. Read the SKILL.md for: ${missing.join(", ")}, then retry.`, `Read design skill(s): ${missing.join(", ")}, then retry`);
+	if (!ev.docConsulted) return block("BLOCKED: no documentation consulted. Use BOTH mcp__context7__query-docs AND mcp__exa__web_search_exa, or a web fallback alone (WebSearch/WebFetch). Gemini is NOT required.", "Consult Context7+Exa, or web docs alone (Gemini not required), then retry");
 	return null;
 }
 //#endregion
@@ -4145,17 +4631,6 @@ const FORBIDDEN_FONTS = [
 	"Open Sans"
 ];
 const OKLCH_RE = /oklch\(\s*[\d.]+%?\s+0\.0*[1-9]/;
-const KNOWN_DOMAINS = [
-	"framer.website",
-	"webflow.io",
-	"awwwards.com",
-	"godly.website",
-	"lapa.ninja",
-	"onepagelove.com",
-	"saasframe.io",
-	"bestwebsite.gallery",
-	"landingfolio.com"
-];
 const deny = (reason) => ({
 	kind: "block",
 	title: "Design pipeline",
@@ -4165,18 +4640,29 @@ const deny = (reason) => ({
 /** Block the design agent from writing anything but .html/.css/.md/.json. */
 function htmlCssOnlyGate(filePath) {
 	if (EXEMPT_DIRS.some((d) => filePath.includes(d)) || ALLOWED_WRITE.test(filePath)) return null;
-	return deny("BLOCKED: design-expert can only write .html, .css, .md, and .json files.");
+	return deny("BLOCKED: design-expert can only write .html, .css, .md, and .json files. Framework files (.tsx, .astro, .vue, .swift, .php) must be written by the domain expert (astro-expert, react-expert, etc.) AFTER design validation.");
 }
 /** Block edits to the harness-managed `.design-state-*` files (read-only to the agent). */
 function stateFileGate(filePath) {
-	return filePath.includes(".design-state-") ? deny("BLOCKED: .design-state files are read-only; the hooks update them as you progress.") : null;
+	return filePath.includes(".design-state-") ? deny("BLOCKED: .design-state files are READ-ONLY for you. Hooks update them automatically as you progress. Do NOT try to modify them — it will not unblock you. Follow the pipeline: Phase 0→1→2→3→4→5→6 in order.") : null;
 }
-/** Gate writing design-system.md: requires phase ≥ 2 and the per-mode screenshot quota. */
-function designSystemWriteGate(filePath, state) {
-	if (!filePath.endsWith("design-system.md")) return null;
-	if (state.currentPhase < 2) return deny(`BLOCKED: cannot write design-system.md at phase ${state.currentPhase}. Read identity + inspiration, then browse & screenshot first.`);
+/**
+* Ports browser_helpers.is_exempt: design-system.md is NOT exempt (it must meet
+* the quota); other `.md` files and vendored dirs ARE exempt from the check.
+*/
+function screenshotExempt(filePath) {
+	if (filePath.endsWith("design-system.md")) return false;
+	return filePath.endsWith(".md") || EXEMPT_DIRS.some((d) => filePath.includes(d));
+}
+/**
+* Block ANY non-exempt write (html/css/design-system.md) until the per-mode
+* screenshot quota is met. Ports check-browser-browsing.py's "Browse N sites
+* BEFORE writing" deny for the active design agent.
+*/
+function preScreenshotWriteGate(filePath, state) {
+	if (screenshotExempt(filePath)) return null;
 	const needed = MIN_SCREENSHOTS[state.mode];
-	if (state.screenshotsCount < needed) return deny(`BLOCKED: ${state.screenshotsCount}/${needed} fuse-browser screenshots for mode '${state.mode}'. Take ${needed - state.screenshotsCount} more (fullPage).`);
+	if (state.screenshotsCount < needed) return deny(`BLOCKED: ${state.screenshotsCount}/${needed} fuse-browser screenshots for mode '${state.mode}'. Browse ${needed - state.screenshotsCount} more site(s) BEFORE writing. Read design-inspiration.md, then browser_open + browser_navigate + browser_screenshot.`);
 	return null;
 }
 /** Return the requirements missing from a design-system.md (empty = valid). */
@@ -4188,19 +4674,6 @@ function validateDesignSystem(content) {
 	if (FORBIDDEN_FONTS.some((f) => content.includes(f))) missing.push("forbidden font (Inter/Roboto/Arial/Open Sans)");
 	return missing;
 }
-/** Gate Gemini create_frontend: requires phase ≥ 3 and a validated design system. */
-function geminiCreateGate(state) {
-	if (state.currentPhase < 3) return deny("BLOCKED: cannot call create_frontend before phase 3. Finish screenshots and write a valid design-system.md.");
-	if (!state.designSystemValid) return deny("BLOCKED: design-system.md not validated (needs ## Design Reference, OKLCH, typography, reference URL).");
-	return null;
-}
-/** Gate fuse-browser navigate: phase ≥ 1, inspiration read, URL in the catalog. */
-function browserNavigateGate(state, url) {
-	if (state.currentPhase < 1) return deny("BLOCKED: read identity templates + design-inspiration.md before browsing.");
-	if (!state.inspirationRead) return deny("BLOCKED: design-inspiration.md not read yet — read it then pick catalog URLs.");
-	if (url && !KNOWN_DOMAINS.some((d) => url.includes(d))) return deny(`BLOCKED: '${url}' is not in the catalog. Use design-inspiration-urls.md domains.`);
-	return null;
-}
 /** Gate a screenshot: require a scroll since the last navigate (lazy-load content). */
 function screenshotScrollGate(state) {
 	return state.scrolledSinceNav ? null : deny("BLOCKED: scroll the page before a screenshot — browser_scroll to:'end', wait, scroll back, then fullPage screenshot.");
@@ -4211,6 +4684,41 @@ function geminiEnabled() {
 	return v === "1" || v === "true";
 }
 //#endregion
+//#region src/policy/design/gates-pipeline.ts
+const SKILLS = `${PLUGINS_DIR}/design-expert/skills`;
+const KNOWN_DOMAINS = [
+	"framer.website",
+	"webflow.io",
+	"awwwards.com",
+	"godly.website",
+	"lapa.ninja",
+	"onepagelove.com",
+	"saasframe.io",
+	"bestwebsite.gallery",
+	"landingfolio.com"
+];
+/** Gate writing design-system.md: requires phase >= 2 and the per-mode screenshot quota. */
+function designSystemWriteGate(filePath, state) {
+	if (!filePath.endsWith("design-system.md")) return null;
+	if (state.currentPhase < 2) return deny(`BLOCKED: Cannot write design-system.md at phase ${state.currentPhase}. RECOVERY: 1) Read identity templates from skills/0-identity-system/ 2) Read design-inspiration.md 3) Browse and screenshot sites 4) Then write design-system.md`);
+	const needed = MIN_SCREENSHOTS[state.mode];
+	if (state.screenshotsCount < needed) return deny(`BLOCKED: ${state.screenshotsCount}/${needed} screenshots for mode '${state.mode}'. RECOVERY: 1) Take ${needed - state.screenshotsCount} more fuse-browser screenshots 2) Use browser_open + browser_navigate + browser_screenshot fullPage:true 3) Then write design-system.md`);
+	return null;
+}
+/** Gate Gemini create_frontend: requires phase >= 3 and a validated design system. */
+function geminiCreateGate(state) {
+	if (state.currentPhase < 3) return deny("BLOCKED: Cannot call Gemini create_frontend before phase 3. RECOVERY: 1) Complete screenshot browsing phase 2) Write a valid design-system.md 3) Then call mcp__gemini-design__create_frontend");
+	if (!state.designSystemValid) return deny("BLOCKED: design-system.md not validated. RECOVERY: 1) Ensure design-system.md has ## Design Reference, OKLCH tokens, typography pair, reference URL 2) Then retry mcp__gemini-design__create_frontend");
+	return null;
+}
+/** Gate fuse-browser navigate: phase >= 1, inspiration read, URL in the catalog. */
+function browserNavigateGate(state, url) {
+	if (state.currentPhase < 1) return deny(`BLOCKED: Phase 0 not done. READ: ${SKILLS}/0-identity-system/SKILL.md first.`);
+	if (!state.inspirationRead) return deny(`BLOCKED: Read inspiration catalog first. READ: ${SKILLS}/1-designing-systems/references/design-inspiration.md + design-inspiration-urls.md`);
+	if (url && !KNOWN_DOMAINS.some((d) => url.includes(d))) return deny(`BLOCKED: '${url}' not in catalog. Use URLs from design-inspiration-urls.md. Domains: ${KNOWN_DOMAINS.join(", ")}`);
+	return null;
+}
+//#endregion
 //#region src/runtime/design.ts
 const NAV = "mcp__fuse-browser__browser_navigate";
 const SHOT = "mcp__fuse-browser__browser_screenshot";
@@ -4225,10 +4733,10 @@ function designGate(payload, event, cacheDir, cwd) {
 		if (skillBlock) return skillBlock;
 	}
 	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+	if (!agentId) return null;
 	const active = activeDesignAgent(cacheDir);
-	if (active && agentId && agentId !== active) return null;
-	const id = active || agentId;
-	if (!id) return null;
+	if (active && agentId !== active) return null;
+	const id = agentId;
 	let state = loadDesignState(cacheDir, id);
 	if (!state) {
 		if (!active) return null;
@@ -4251,7 +4759,7 @@ function designGate(payload, event, cacheDir, cwd) {
 	}
 	if (event.tool === "Write" || event.tool === "Edit") {
 		const fp = event.filePath ?? "";
-		const base = stateFileGate(fp) ?? htmlCssOnlyGate(fp) ?? designSystemWriteGate(fp, state);
+		const base = stateFileGate(fp) ?? htmlCssOnlyGate(fp) ?? preScreenshotWriteGate(fp, state) ?? designSystemWriteGate(fp, state);
 		if (base) return base;
 		if (geminiEnabled() && state.geminiCalls === 0 && /\.(html|css)$/.test(fp)) return {
 			kind: "block",
@@ -4311,6 +4819,13 @@ async function handlePre(ctx) {
 		stdout: securityAdvisory(event.tool, event.filePath ?? "", opts.now),
 		exit: 0
 	};
+	if (opts.scope === "solid" && event.filePath) {
+		const solidDeny = validateSolidGate(event.tool, event.filePath, event.content ?? "");
+		if (solidDeny) return {
+			stdout: solidDeny,
+			exit: 0
+		};
+	}
 	if (event.tool === "Task") {
 		const taskCtx = taskContext(opts.cwd);
 		if (taskCtx) return {
@@ -4343,82 +4858,6 @@ async function handlePre(ctx) {
 	};
 }
 //#endregion
-//#region src/freshness/explore-tools.ts
-/** Native exploration tools (parity `apex_constants.EXPLORE_TOOLS`). */
-const EXPLORE_TOOLS = /* @__PURE__ */ new Set(["Glob", "Grep"]);
-/** Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`). */
-const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
-	"mcp__context7__query-docs",
-	"mcp__context7__resolve-library-id",
-	"mcp__exa__web_search_exa",
-	"mcp__exa__get_code_context_exa",
-	"mcp__exa__deep_researcher_start",
-	"WebSearch",
-	"WebFetch"
-]);
-/** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
-const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
-	"grep",
-	"rg",
-	"find",
-	"ls",
-	"fd",
-	"ast-grep",
-	"tree",
-	"cat",
-	"head",
-	"tail"
-]);
-/** Cached MCP result reads count as research (parity `CACHE_READ_RE` + doc-helpers). */
-const CACHE_READ_RE = /\/context\/mcp\/(exa-search|exa-code-context|context7)-/;
-/**
-* First non-assignment shell token's basename, or "" — mirrors Python
-* `_bash_executable` (skips leading `VAR=value` env prefixes, e.g. `FOO=1 grep`).
-* @param cmd - Raw Bash `command` string.
-* @returns The executable basename, or "" when none.
-*/
-function bashExecutable(cmd) {
-	for (const token of cmd.trim().split(/\s+/)) {
-		if (!token) continue;
-		const last = token.split("/").pop() ?? token;
-		if (!last.includes("=")) return last;
-	}
-	return "";
-}
-/**
-* Classify a direct tool use into an APEX phase, or `null` when it is neither
-* exploration nor research. Mirrors Python `track-subagent-research._classify`.
-* @param tool - Harness tool name (e.g. "Glob", "Bash", "WebSearch").
-* @param input - Tool input payload.
-* @returns The credited phase + cache flag, or `null`.
-*/
-function classifyExplore(tool, input) {
-	if (RESEARCH_TOOLS.has(tool)) return {
-		phase: "research-expert",
-		cacheHit: false
-	};
-	if (EXPLORE_TOOLS.has(tool)) return {
-		phase: "explore-codebase",
-		cacheHit: false
-	};
-	if (tool === "Read") {
-		const path = String(input?.file_path ?? input?.path ?? "");
-		if (path && CACHE_READ_RE.test(path)) return {
-			phase: "research-expert",
-			cacheHit: true
-		};
-		return null;
-	}
-	if (tool === "Bash") {
-		const cmd = String(input?.command ?? "").trim();
-		if (EXPLORE_BASH_CMDS.has(bashExecutable(cmd))) return {
-			phase: "explore-codebase",
-			cacheHit: false
-		};
-	}
-	return null;
-}
-//#endregion
 //#region src/runtime/activity.ts
 /** Min response length (chars) for a lead agent call to count as `sufficient`. */
 const AGENT_QUALITY_MIN = 500;
@@ -4460,6 +4899,7 @@ function docSourceOf(tool) {
 	if (/browser_(fetch|crawl|serp)/i.test(tool)) return "fuse-browser";
 	if (tool === "WebSearch") return "websearch";
 	if (tool === "WebFetch") return "webfetch";
+	if (/^mcp__shadcn__/i.test(tool)) return "shadcn-mcp";
 }
 /**
 * Map a live tool-use to the activity to record, or null when nothing is
@@ -4526,14 +4966,28 @@ async function handlePost(ctx) {
 		stdout: seoDeny,
 		exit: 0
 	};
-	if (opts.scope === "aipilot" && (event.tool === "TaskCreate" || event.tool === "TaskUpdate")) {
+	if (opts.scope === "solid" && event.filePath) {
+		const solidWarn = checkFileSize(event.tool, event.filePath);
+		if (solidWarn) return {
+			stdout: solidWarn,
+			exit: 0
+		};
+	}
+	if (opts.scope === "tailwindcss" && event.filePath) {
+		const tailwindWarn = validateTailwind(event.tool, event.filePath);
+		if (tailwindWarn) return {
+			stdout: tailwindWarn,
+			exit: 0
+		};
+	}
+	if (opts.scope === "aipilot" && (event.tool === "TaskCreate" || event.tool === "TaskUpdate" || event.tool === "Write" || event.tool === "Edit")) {
 		const out = await aipilotPostToolUse(payload, opts.cwd);
 		if (out) return {
 			stdout: out,
 			exit: 0
 		};
 	}
-	const extra = postEditContext(opts.scope ?? "core", event, opts.now);
+	const extra = await postEditContext(opts.scope ?? "core", event, opts.now);
 	return {
 		stdout: designWarn ? respond(id, designWarn) : extra,
 		exit: 0
@@ -4578,7 +5032,7 @@ async function handleHook(id, payload, opts) {
 	const file = trackFile(event.sessionId, defaultStateDir(opts.cwd));
 	const mcpDir = layout.cacheDir;
 	const framework = detectFramework(event.filePath ?? "", event.content ?? "");
-	if (designLifecycle(payload, mcpDir, opts.cwd, String(opts.now), opts.now)) return {
+	if (id === "claude-code" && designLifecycle(payload, mcpDir, opts.cwd, String(opts.now), opts.now)) return {
 		stdout: "",
 		exit: 0
 	};
@@ -4620,4 +5074,4 @@ async function handleHook(id, payload, opts) {
 	});
 }
 //#endregion
-export { saveApexState as $, trackSkillRead as A, writePluginMap as B, seoPostToolUse as C, isoUtc as Ct, postTrackingSideEffects as D, securityStatePath as Dt, securityAdvisory as E, securityStateDir as Et, dispatchLessons as F, mergeLines as G, isProject as H, lessonsFileFor as I, listChildren as J, countFiles as K, lessonsStateFileFor as L, dispatchLifecycle as M, aipilotPostToolUse as N, trackWatchResearch as O, todayUtc as Ot, dispatchAipilot as P, cleanupSession as Q, cartoSessionStart as R, postEditContext as S, normalizeEvent as St, dispatchMemory as T, saveSecurityState as Tt, writeTree as U, generateProjectMap as V, loadEnriched as W, trackSessionChanges as X, postEditTypescript as Y, validateRulesLoaded as Z, preCommitGate as _, promptSubmitContext as _t, recordActivity as a, solidDetectStart as at, extractSymbols as b, projectHash$1 as bt, MCP_TTL_MS as c, runSessionStartCleanups as ct, isMcpTool as d, purgeTtlTree as dt, logToolFailure as et, queryOf as f, removeOldFiles as ft, gate as g, projectContext as gt, TRIVIAL_BUDGET as h, gitContext as ht, respond as i, detectSolidProfile as it, trackEnrichment as j, trackMcpResearch as k, WEBFETCH_TTL_MS as l, sessionStartCore as lt, REQUIRED_AGENTS as m, devContext as mt, activityFor as n, trackAgentMemory as nt, mcpPostStore as o, injectRules as ot, DEFAULT_WINDOW_MS as p, trimLogFile as pt, getFileDesc as q, handlePre as r, subagentCacheContext as rt, mcpPreIntercept as s, readRules as st, handleHook as t, validateTeammateOutput as tt, cacheQueryOf as u, pruneEmptyDirs as ut, detectDuplication as v, taskContext as vt, seoPostToolUseResponse as w, loadSecurityState as wt, lifecycleStdout as x, trackFile as xt, dryGate as y, defaultStateDir as yt, generateEcosystemMap as z };
+export { saveApexState as $, trackSkillRead as A, securityStateDir as At, writePluginMap as B, seoPostToolUse as C, defaultStateDir as Ct, postTrackingSideEffects as D, isoUtc as Dt, securityAdvisory as E, normalizeEvent as Et, dispatchLessons as F, mergeLines as G, isProject as H, lessonsFileFor as I, listChildren as J, countFiles as K, lessonsStateFileFor as L, dispatchLifecycle as M, todayUtc as Mt, aipilotPostToolUse as N, trackWatchResearch as O, loadSecurityState as Ot, dispatchAipilot as P, cleanupSession as Q, cartoSessionStart as R, postEditContext as S, taskContext as St, dispatchMemory as T, trackFile as Tt, writeTree as U, generateProjectMap as V, loadEnriched as W, trackSessionChanges as X, postEditTypescript as Y, validateRulesLoaded as Z, preCommitGate as _, trimLogFile as _t, recordActivity as a, validateSolidGate as at, extractSymbols as b, projectContext as bt, MCP_TTL_MS as c, detectSolidProfile as ct, isMcpTool as d, readRules as dt, logToolFailure as et, queryOf as f, runSessionStartCleanups as ft, gate as g, removeOldFiles as gt, TRIVIAL_BUDGET as h, purgeTtlTree as ht, respond as i, validateTailwind as it, trackEnrichment as j, securityStatePath as jt, trackMcpResearch as k, saveSecurityState as kt, WEBFETCH_TTL_MS as l, solidDetectStart as lt, REQUIRED_AGENTS as m, pruneEmptyDirs as mt, activityFor as n, trackAgentMemory as nt, mcpPostStore as o, checkFileSize as ot, DEFAULT_WINDOW_MS as p, sessionStartCore as pt, getFileDesc as q, handlePre as r, subagentCacheContext as rt, mcpPreIntercept as s, countLoc as st, handleHook as t, validateTeammateOutput as tt, cacheQueryOf as u, injectRules as ut, detectDuplication as v, devContext as vt, seoPostToolUseResponse as w, projectHash$1 as wt, lifecycleStdout as x, promptSubmitContext as xt, dryGate as y, gitContext as yt, generateEcosystemMap as z };