@fusengine/harness 0.1.44 → 0.1.45

package/dist/cache/index.d.mts

@@ -1,2 +1,2 @@
-import { a as mcpCacheKey, c as extractText, d as summarizeIndex, f as compactMarkdown, i as cacheStore, l as IndexSummary, m as queryHash, n as cacheLookupSubstring, o as mcpCacheWrite, p as jaccardSimilar, r as cachePath, s as webfetchCacheWrite, t as cacheLookup, u as loadIndex } from "../index-BX-xcvhY.mjs";
-export { IndexSummary, cacheLookup, cacheLookupSubstring, cachePath, cacheStore, compactMarkdown, extractText, jaccardSimilar, loadIndex, mcpCacheKey, mcpCacheWrite, queryHash, summarizeIndex, webfetchCacheWrite };
+import { _ as queryHash, a as cacheLookupSubstringMeta, c as mcpCacheKey, d as extractText, f as IndexSummary, g as jaccardSimilar, h as compactMarkdown, i as cacheLookupSubstring, l as mcpCacheWrite, m as summarizeIndex, n as cacheLookup, o as cachePath, p as loadIndex, r as cacheLookupMeta, s as cacheStore, t as CacheHit, u as webfetchCacheWrite } from "../index-BUwEmIK-.mjs";
+export { CacheHit, IndexSummary, cacheLookup, cacheLookupMeta, cacheLookupSubstring, cacheLookupSubstringMeta, cachePath, cacheStore, compactMarkdown, extractText, jaccardSimilar, loadIndex, mcpCacheKey, mcpCacheWrite, queryHash, summarizeIndex, webfetchCacheWrite };

package/dist/cache/index.mjs

@@ -1,3 +1,3 @@
-import { a as cachePath, c as extractText, d as compactMarkdown, f as jaccardSimilar, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, o as cacheStore, p as queryHash, r as cacheLookup, s as mcpCacheKey, t as mcpCacheWrite, u as summarizeIndex } from "../mcp-store-CnsW9oFj.mjs";
+import { a as cacheLookupSubstring, c as cacheStore, d as loadIndex, f as summarizeIndex, h as queryHash, i as cacheLookupMeta, l as mcpCacheKey, m as jaccardSimilar, n as webfetchCacheWrite, o as cacheLookupSubstringMeta, p as compactMarkdown, r as cacheLookup, s as cachePath, t as mcpCacheWrite, u as extractText } from "../mcp-store-BkBDmuxN.mjs";
 import "../cache-la_KkjCS.mjs";
-export { cacheLookup, cacheLookupSubstring, cachePath, cacheStore, compactMarkdown, extractText, jaccardSimilar, loadIndex, mcpCacheKey, mcpCacheWrite, queryHash, summarizeIndex, webfetchCacheWrite };
+export { cacheLookup, cacheLookupMeta, cacheLookupSubstring, cacheLookupSubstringMeta, cachePath, cacheStore, compactMarkdown, extractText, jaccardSimilar, loadIndex, mcpCacheKey, mcpCacheWrite, queryHash, summarizeIndex, webfetchCacheWrite };

package/dist/cli/bin.mjs

@@ -4,7 +4,7 @@ import { t as detectHarness } from "../harness-C8Nxxyn_.mjs";
 import { t as claudeHome } from "../home-state-mKZxP4oZ.mjs";
 import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-DLXtA5DH.mjs";
 import { n as writeInitFile, t as initFor } from "../run-Do2JltgU.mjs";
-import { Mt as todayUtc, t as handleHook } from "../handle-CtMMVoxT.mjs";
+import { Mt as todayUtc, t as handleHook } from "../handle-DJaaD2BT.mjs";
 import { delimiter, dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

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

@@ -1,14 +1,14 @@
 import { a as parseEnvInt, i as splitTarget, r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
 import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
-import { A as detectCreationIntent, B as detectProjectType$1, C as skillTriggerGate, E as frameworkSolidGate, H as requiredArchSkill, L as detectFramework, N as docConsultedGate, P as evaluateApex, _ as scanPlugin, b as findMarketplacePlugins, 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, x as readPluginMeta, y as parseField, z as detectModularArchitecture } from "./validate-Ca7NSp-r.mjs";
-import { F as countFrameworkCodeLines, I as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-d7Pp8XJH.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 { 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";
@@ -3709,7 +3709,8 @@ function dryGate(tool, filePath, content, cwd) {
 	const dup = detectDuplication(filePath, content, cwd);
 	if (dup.duplicates.length === 0) return null;
 	const names = dup.names.slice(0, 5).join(", ");
-	const files = dup.duplicates.slice(0, 3).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)",
@@ -3834,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;
 }
@@ -3929,6 +3930,8 @@ const EXEMPT_RE$1 = /(^|\/)(node_modules|dist|build)\//;
 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
@@ -3943,6 +3946,11 @@ function isShadcnWrite(tool, filePath) {
 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
@@ -3954,11 +3962,11 @@ function shadcnBaseSkillRead(refsRead) {
 */
 function shadcnSkillGate(tool, filePath, content, ev) {
 	if (!isShadcnWrite(tool, filePath)) return null;
-	if (!shadcnBaseSkillRead(ev.refsRead)) return {
+	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, then retry.",
-		actions: ["Read skills/shadcn-detection/ or skills/shadcn-components/, then retry"]
+		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;
@@ -4283,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.
@@ -4292,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)
@@ -4613,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",
@@ -4633,19 +4640,11 @@ 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;
-}
-/** 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.`);
-	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).`);
-	return 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;
 }
 /**
 * Ports browser_helpers.is_exempt: design-system.md is NOT exempt (it must meet
@@ -4675,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.");
@@ -4698,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";
@@ -4878,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

package/dist/{index-BX-xcvhY.d.mts → index-BUwEmIK-.d.mts}

@@ -57,8 +57,15 @@ declare function webfetchCacheWrite(dir: string, tool: string, key: string, body
 declare function mcpCacheKey(tool: string, query: string): string;
 /** Path of a cache entry under `dir`. */
 declare function cachePath(dir: string, tool: string, query: string): string;
+/** A cache hit's body plus its age in ms (now − mtime), for caller-side reporting. */
+interface CacheHit {
+  body: string;
+  ageMs: number;
+}
 /** Read a cached entry if it exists and is fresh (mtime within `ttlMs`), else null. */
 declare function cacheLookup(dir: string, tool: string, query: string, ttlMs: number, now: number): string | null;
+/** Like {@link cacheLookup}, but also reports the entry's age (for `CACHE HIT` wrapper text). */
+declare function cacheLookupMeta(dir: string, tool: string, query: string, ttlMs: number, now: number): CacheHit | null;
 /**
 * First fresh cache file whose body contains the (normalized, case-insensitive)
 * query substring, else null. Relaxes the exact-key match to lift the hit-rate —
@@ -69,7 +76,9 @@ declare function cacheLookup(dir: string, tool: string, query: string, ttlMs: nu
 * @param now - Current epoch ms.
 */
 declare function cacheLookupSubstring(dir: string, query: string, ttlMs: number, now: number): string | null;
+/** Like {@link cacheLookupSubstring}, but also reports the matched entry's age. */
+declare function cacheLookupSubstringMeta(dir: string, query: string, ttlMs: number, now: number): CacheHit | null;
 /** Store a cache entry (creates the dir; no-op on empty content). */
 declare function cacheStore(dir: string, tool: string, query: string, content: string): void;
 //#endregion
-export { mcpCacheKey as a, extractText as c, summarizeIndex as d, compactMarkdown as f, cacheStore as i, IndexSummary as l, queryHash as m, cacheLookupSubstring as n, mcpCacheWrite as o, jaccardSimilar as p, cachePath as r, webfetchCacheWrite as s, cacheLookup as t, loadIndex as u };
+export { queryHash as _, cacheLookupSubstringMeta as a, mcpCacheKey as c, extractText as d, IndexSummary as f, jaccardSimilar as g, compactMarkdown as h, cacheLookupSubstring as i, mcpCacheWrite as l, summarizeIndex as m, cacheLookup as n, cachePath as o, loadIndex as p, cacheLookupMeta as r, cacheStore as s, CacheHit as t, webfetchCacheWrite as u };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { n as PromptKind, r as formatPrompt, t as Prompt } from "./types-D56jSgD9.mjs";
-import { a as mcpCacheKey, c as extractText, d as summarizeIndex, f as compactMarkdown, i as cacheStore, l as IndexSummary, m as queryHash, n as cacheLookupSubstring, o as mcpCacheWrite, p as jaccardSimilar, r as cachePath, s as webfetchCacheWrite, t as cacheLookup, u as loadIndex } from "./index-BX-xcvhY.mjs";
+import { _ as queryHash, a as cacheLookupSubstringMeta, c as mcpCacheKey, d as extractText, f as IndexSummary, g as jaccardSimilar, h as compactMarkdown, i as cacheLookupSubstring, l as mcpCacheWrite, m as summarizeIndex, n as cacheLookup, o as cachePath, p as loadIndex, r as cacheLookupMeta, s as cacheStore, t as CacheHit, u as webfetchCacheWrite } from "./index-BUwEmIK-.mjs";
 import { _ as parseEnvInt, a as ProjectLayout, c as projectLayout, d as resolveMaxLines, f as splitTarget, g as ttlLabel, h as resolveTtlSec, i as parseEnvFile, l as DEFAULT_MAX_LINES, m as TTL_ENV_KEY, n as envCandidates, o as STATE_GITIGNORE, p as DEFAULT_TTL_SEC, r as loadDotenv, s as STATE_ROOT, t as HOME_DIR, u as MAX_LINES_ENV_KEY } from "./index-BXPySPxE.mjs";
 import { a as HarnessInfo, i as HarnessId, n as detectMode, o as HarnessMode, r as modeFor, s as HarnessVia, t as detectHarness } from "./harness-BPPu5CrN.mjs";
 import { a as isDocConsulted, i as formatDocSatisfactionStatus, n as DocSatisfactionStatus, o as resolveSessions, r as formatDocDeny, t as AuthEntry } from "./doc-helpers-BNfYWvYv.mjs";
@@ -11,4 +11,4 @@ import { a as ReminderState, c as readState, d as throttleMs, i as registryFile,
 import { a as globToRe, i as scoreReferences, n as toRefMeta, o as parseFrontmatter, r as routeReferences, t as loadRefs } from "./index-mmRF3KNp.mjs";
 import { a as taskStart, c as ensureStateDir, d as stateFilePath, f as acquireLock, i as taskCreate, l as loadState, n as ApexTaskFile, o as ApexState, r as taskComplete, s as apexStateDir, t as ApexTask, u as saveState } from "./index-BA-SqNR7.mjs";
 import { _ as TIME_INTERVALS, a as formatCost, c as formatTokens, d as colors, f as progressiveColor, g as PROGRESS_CHARS, h as PROGRESS_BAR_DEFAULTS, i as formatBasename, l as ColorFn, m as GRADIENT_BLOCKS, n as generateGradientBar, o as formatPath, p as COLOR_THRESHOLDS, r as generateProgressBar, s as formatTimeLeft, t as ProgressBarOptions, u as Palette } from "./index-BWK8slRi.mjs";
-export { APEX_GATES, ASK_PATTERNS, ASK_WRITERS, ApexContext, ApexGate, ApexState, ApexTask, ApexTaskFile, ApexTaskState, AuthEntry, CODE_MUTATORS, CODE_REDIRECT, COLOR_THRESHOLDS, CRITICAL_PATTERNS, ColorFn, DEFAULT_MAX_LINES, DEFAULT_TTL_SEC, DEV_KEYWORDS, DEV_VERBS, DocSatisfactionStatus, EXCLUDE_DIRS, FAIL_CLOSED, FILE_REDIRECT, FileSizeVerdict, GIT_ASK, GIT_BLOCKED, GO_DECL_RE, GRADIENT_BLOCKS, GUARDS, Guard, GuardContext, HOME_DIR, type HarnessId, type HarnessInfo, type HarnessMode, type HarnessVia, IndexSummary, JAVA_DECL_RE, LabeledPattern, MAX_EXA_RESULTS, MAX_LINES_ENV_KEY, MAX_TOKENS, ModularArchitecture, PHP_DECL_RE, PLUGINS_DIR, PROGRESS_BAR_DEFAULTS, PROGRESS_CHARS, PROJECT_INDICATORS, PROJECT_INSTALL, PROTECTED_FRAGMENTS, PROTECTED_GIT_RE, PY_MODEL_RE, Palette, type PolicyContext, type PolicyResult, ProgressBarOptions, ProjectLayout, ProjectType, Prompt, PromptKind, RefMeta, ReminderState, RouteResult, SAFE_PREFIXES, SESSION_STATE_FRAGMENT, SKILL_TRIGGERS, SOLID_REF, STATE_GITIGNORE, STATE_ROOT, SWIFT_PROTO_RE, SYSTEM_INSTALL, ScoredRef, TIME_INTERVALS, TS_DECL_RE, TTL_ENV_KEY, TreeEntry, acquireLock, addRoot, apexStateDir, bashWriteGuard, brainstormGate, buildApexInstruction, buildApexTaskContext, buildApexTaskInjection, buildClaudeMdContext, cacheLookup, cacheLookupSubstring, cachePath, cacheStore, capVerbosity, clearUserGuards, colors, compactJson, compactMarkdown, countFrameworkCodeLines, countLines, descFromText, detectClaudeMdProjectType, detectCreationIntent, detectFramework, detectHarness, detectMode, detectModularArchitecture, detectProjectType, detectRequiredSkills, docConsultedGate, ensureMemoryGitignore, ensureStateDir, envCandidates, evaluate, evaluateApex, evaluateFileSize, extractText, firstComment, firstHeading, formatBasename, formatCost, formatDocDeny, formatDocSatisfactionStatus, formatPath, formatPrompt, formatTimeLeft, formatTokens, frameworkSolidGate, freshnessGate, generateGradientBar, generateProgressBar, globToRe, incrementTrivialEditCounter, installGuard, interfaceSeparationGuard, isApexCommand, isCodeFile, isDocConsulted, isHtmlLike, jaccardSimilar, lessonsFileFor, loadApexTaskState, loadDotenv, loadIndex, loadRefs, loadState, matchPatterns, mcpCacheKey, mcpCacheWrite, missingSeoElements, modeFor, nowStamp, parseBodyDesc, parseEnrichment, parseEntry, parseEnvFile, parseEnvInt, parseField, parseFrontmatter, progressiveColor, projectLayout, projectRoot, projectRootOrNull, protectedPathGuard, queryHash, readRoots, readState, registerGuard, registryFile, requiredArchSkill, resolveMaxLines, resolveSessions, resolveTtlSec, routeReferences, runGuards, saveState, scoreReferences, securityGuard, setStateField, skillTriggerGate, solidReadGate, splitTarget, stateFileFor, stateFilePath, summarizeIndex, taskComplete, taskCreate, taskStart, throttleMs, toRefMeta, ttlLabel, usesTailwindUtilities, walkUpFor, webfetchCacheWrite };
+export { APEX_GATES, ASK_PATTERNS, ASK_WRITERS, ApexContext, ApexGate, ApexState, ApexTask, ApexTaskFile, ApexTaskState, AuthEntry, CODE_MUTATORS, CODE_REDIRECT, COLOR_THRESHOLDS, CRITICAL_PATTERNS, CacheHit, ColorFn, DEFAULT_MAX_LINES, DEFAULT_TTL_SEC, DEV_KEYWORDS, DEV_VERBS, DocSatisfactionStatus, EXCLUDE_DIRS, FAIL_CLOSED, FILE_REDIRECT, FileSizeVerdict, GIT_ASK, GIT_BLOCKED, GO_DECL_RE, GRADIENT_BLOCKS, GUARDS, Guard, GuardContext, HOME_DIR, type HarnessId, type HarnessInfo, type HarnessMode, type HarnessVia, IndexSummary, JAVA_DECL_RE, LabeledPattern, MAX_EXA_RESULTS, MAX_LINES_ENV_KEY, MAX_TOKENS, ModularArchitecture, PHP_DECL_RE, PLUGINS_DIR, PROGRESS_BAR_DEFAULTS, PROGRESS_CHARS, PROJECT_INDICATORS, PROJECT_INSTALL, PROTECTED_FRAGMENTS, PROTECTED_GIT_RE, PY_MODEL_RE, Palette, type PolicyContext, type PolicyResult, ProgressBarOptions, ProjectLayout, ProjectType, Prompt, PromptKind, RefMeta, ReminderState, RouteResult, SAFE_PREFIXES, SESSION_STATE_FRAGMENT, SKILL_TRIGGERS, SOLID_REF, STATE_GITIGNORE, STATE_ROOT, SWIFT_PROTO_RE, SYSTEM_INSTALL, ScoredRef, TIME_INTERVALS, TS_DECL_RE, TTL_ENV_KEY, TreeEntry, acquireLock, addRoot, apexStateDir, bashWriteGuard, brainstormGate, buildApexInstruction, buildApexTaskContext, buildApexTaskInjection, buildClaudeMdContext, cacheLookup, cacheLookupMeta, cacheLookupSubstring, cacheLookupSubstringMeta, cachePath, cacheStore, capVerbosity, clearUserGuards, colors, compactJson, compactMarkdown, countFrameworkCodeLines, countLines, descFromText, detectClaudeMdProjectType, detectCreationIntent, detectFramework, detectHarness, detectMode, detectModularArchitecture, detectProjectType, detectRequiredSkills, docConsultedGate, ensureMemoryGitignore, ensureStateDir, envCandidates, evaluate, evaluateApex, evaluateFileSize, extractText, firstComment, firstHeading, formatBasename, formatCost, formatDocDeny, formatDocSatisfactionStatus, formatPath, formatPrompt, formatTimeLeft, formatTokens, frameworkSolidGate, freshnessGate, generateGradientBar, generateProgressBar, globToRe, incrementTrivialEditCounter, installGuard, interfaceSeparationGuard, isApexCommand, isCodeFile, isDocConsulted, isHtmlLike, jaccardSimilar, lessonsFileFor, loadApexTaskState, loadDotenv, loadIndex, loadRefs, loadState, matchPatterns, mcpCacheKey, mcpCacheWrite, missingSeoElements, modeFor, nowStamp, parseBodyDesc, parseEnrichment, parseEntry, parseEnvFile, parseEnvInt, parseField, parseFrontmatter, progressiveColor, projectLayout, projectRoot, projectRootOrNull, protectedPathGuard, queryHash, readRoots, readState, registerGuard, registryFile, requiredArchSkill, resolveMaxLines, resolveSessions, resolveTtlSec, routeReferences, runGuards, saveState, scoreReferences, securityGuard, setStateField, skillTriggerGate, solidReadGate, splitTarget, stateFileFor, stateFilePath, summarizeIndex, taskComplete, taskCreate, taskStart, throttleMs, toRefMeta, ttlLabel, usesTailwindUtilities, walkUpFor, webfetchCacheWrite };

package/dist/index.mjs

@@ -4,15 +4,15 @@ import { n as STATE_ROOT, r as projectLayout, t as STATE_GITIGNORE } from "./lay
 import { t as compactJson } from "./compact-json-DK2nX-MK.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
 import { n as detectMode, r as modeFor, t as detectHarness } from "./harness-C8Nxxyn_.mjs";
-import { A as detectCreationIntent, B as detectProjectType, C as skillTriggerGate, D as MAX_EXA_RESULTS, E as frameworkSolidGate, F as freshnessGate, H as requiredArchSkill, I as solidReadGate, L as detectFramework, M as brainstormGate, N as docConsultedGate, O as MAX_TOKENS, P as evaluateApex, R as DEV_KEYWORDS, S as detectRequiredSkills, T as SKILL_TRIGGERS, V as isApexCommand, a as firstHeading, c as EXCLUDE_DIRS, d as buildApexTaskInjection, f as loadApexTaskState, g as detectClaudeMdProjectType, h as buildClaudeMdContext, i as firstComment, j as APEX_GATES, k as capVerbosity, l as PROJECT_INDICATORS, m as buildApexInstruction, n as missingSeoElements, o as parseEnrichment, p as DEV_VERBS, r as descFromText, s as parseEntry, t as isHtmlLike, u as buildApexTaskContext, v as parseBodyDesc, w as usesTailwindUtilities, y as parseField, z as detectModularArchitecture } from "./validate-Ca7NSp-r.mjs";
+import { A as detectCreationIntent, B as detectProjectType, D as MAX_EXA_RESULTS, E as frameworkSolidGate, F as freshnessGate, H as requiredArchSkill, I as solidReadGate, L as detectFramework, M as brainstormGate, N as docConsultedGate, O as MAX_TOKENS, P as evaluateApex, R as DEV_KEYWORDS, S as usesTailwindUtilities, T as SKILL_TRIGGERS, V as isApexCommand, a as firstHeading, b as detectRequiredSkills, c as EXCLUDE_DIRS, d as buildApexTaskInjection, f as loadApexTaskState, g as detectClaudeMdProjectType, h as buildClaudeMdContext, i as firstComment, j as APEX_GATES, k as capVerbosity, l as PROJECT_INDICATORS, m as buildApexInstruction, n as missingSeoElements, o as parseEnrichment, p as DEV_VERBS, r as descFromText, s as parseEntry, t as isHtmlLike, u as buildApexTaskContext, v as parseBodyDesc, x as skillTriggerGate, y as parseField, z as detectModularArchitecture } from "./validate-DcQaKzau.mjs";
 import { A as PROJECT_INSTALL, C as PROTECTED_GIT_RE, D as securityGuard, E as CRITICAL_PATTERNS, F as countFrameworkCodeLines, I as countLines, L as evaluateFileSize, M as matchPatterns, N as PLUGINS_DIR, O as GIT_ASK, P as SOLID_REF, S as PROTECTED_FRAGMENTS, T as ASK_PATTERNS, _ as CODE_MUTATORS, a as registerGuard, b as SAFE_PREFIXES, c as GO_DECL_RE, d as PY_MODEL_RE, f as SWIFT_PROTO_RE, g as ASK_WRITERS, h as bashWriteGuard, i as clearUserGuards, j as SYSTEM_INSTALL, k as GIT_BLOCKED, l as JAVA_DECL_RE, m as interfaceSeparationGuard, n as FAIL_CLOSED, o as runGuards, p as TS_DECL_RE, r as GUARDS, s as installGuard, t as evaluate, u as PHP_DECL_RE, v as CODE_REDIRECT, w as protectedPathGuard, x as SESSION_STATE_FRAGMENT, y as FILE_REDIRECT } from "./evaluate-d7Pp8XJH.mjs";
 import { i as resolveSessions, n as formatDocSatisfactionStatus, r as isDocConsulted, t as formatDocDeny } from "./doc-helpers-CWZegVdR.mjs";
 import { i as parseFrontmatter, n as scoreReferences, r as globToRe, t as routeReferences } from "./router-PKVNBHge.mjs";
 import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { a as nowStamp, c as stateFileFor, i as lessonsFileFor, l as throttleMs, n as readRoots, o as readState, r as registryFile, s as setStateField, t as addRoot, u as ensureMemoryGitignore } from "./registry-CymilZiZ.mjs";
-import { a as cachePath, c as extractText, d as compactMarkdown, f as jaccardSimilar, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, o as cacheStore, p as queryHash, r as cacheLookup, s as mcpCacheKey, t as mcpCacheWrite, u as summarizeIndex } from "./mcp-store-CnsW9oFj.mjs";
+import { a as cacheLookupSubstring, c as cacheStore, d as loadIndex, f as summarizeIndex, h as queryHash, i as cacheLookupMeta, l as mcpCacheKey, m as jaccardSimilar, n as webfetchCacheWrite, o as cacheLookupSubstringMeta, p as compactMarkdown, r as cacheLookup, s as cachePath, t as mcpCacheWrite, u as extractText } from "./mcp-store-BkBDmuxN.mjs";
 import { t as incrementTrivialEditCounter } from "./freshness-BV3PQkDB.mjs";
 import { n as toRefMeta, t as loadRefs } from "./loader-AGz4nK7d.mjs";
 import { a as ensureStateDir, c as stateFilePath, i as apexStateDir, l as acquireLock, n as taskCreate, o as loadState, r as taskStart, s as saveState, t as taskComplete } from "./state-9lWvvWk8.mjs";
 import { a as formatPath, c as colors, d as GRADIENT_BLOCKS, f as PROGRESS_BAR_DEFAULTS, i as formatCost, l as progressiveColor, m as TIME_INTERVALS, n as generateProgressBar, o as formatTimeLeft, p as PROGRESS_CHARS, r as formatBasename, s as formatTokens, t as generateGradientBar, u as COLOR_THRESHOLDS } from "./statusline-D87eUNXl.mjs";
-export { APEX_GATES, ASK_PATTERNS, ASK_WRITERS, CODE_MUTATORS, CODE_REDIRECT, COLOR_THRESHOLDS, CRITICAL_PATTERNS, DEFAULT_MAX_LINES, DEFAULT_TTL_SEC, DEV_KEYWORDS, DEV_VERBS, EXCLUDE_DIRS, FAIL_CLOSED, FILE_REDIRECT, GIT_ASK, GIT_BLOCKED, GO_DECL_RE, GRADIENT_BLOCKS, GUARDS, HOME_DIR, JAVA_DECL_RE, MAX_EXA_RESULTS, MAX_LINES_ENV_KEY, MAX_TOKENS, PHP_DECL_RE, PLUGINS_DIR, PROGRESS_BAR_DEFAULTS, PROGRESS_CHARS, PROJECT_INDICATORS, PROJECT_INSTALL, PROTECTED_FRAGMENTS, PROTECTED_GIT_RE, PY_MODEL_RE, SAFE_PREFIXES, SESSION_STATE_FRAGMENT, SKILL_TRIGGERS, SOLID_REF, STATE_GITIGNORE, STATE_ROOT, SWIFT_PROTO_RE, SYSTEM_INSTALL, TIME_INTERVALS, TS_DECL_RE, TTL_ENV_KEY, acquireLock, addRoot, apexStateDir, bashWriteGuard, brainstormGate, buildApexInstruction, buildApexTaskContext, buildApexTaskInjection, buildClaudeMdContext, cacheLookup, cacheLookupSubstring, cachePath, cacheStore, capVerbosity, clearUserGuards, colors, compactJson, compactMarkdown, countFrameworkCodeLines, countLines, descFromText, detectClaudeMdProjectType, detectCreationIntent, detectFramework, detectHarness, detectMode, detectModularArchitecture, detectProjectType, detectRequiredSkills, docConsultedGate, ensureMemoryGitignore, ensureStateDir, envCandidates, evaluate, evaluateApex, evaluateFileSize, extractText, firstComment, firstHeading, formatBasename, formatCost, formatDocDeny, formatDocSatisfactionStatus, formatPath, formatPrompt, formatTimeLeft, formatTokens, frameworkSolidGate, freshnessGate, generateGradientBar, generateProgressBar, globToRe, incrementTrivialEditCounter, installGuard, interfaceSeparationGuard, isApexCommand, isCodeFile, isDocConsulted, isHtmlLike, jaccardSimilar, lessonsFileFor, loadApexTaskState, loadDotenv, loadIndex, loadRefs, loadState, matchPatterns, mcpCacheKey, mcpCacheWrite, missingSeoElements, modeFor, nowStamp, parseBodyDesc, parseEnrichment, parseEntry, parseEnvFile, parseEnvInt, parseField, parseFrontmatter, progressiveColor, projectLayout, projectRoot, projectRootOrNull, protectedPathGuard, queryHash, readRoots, readState, registerGuard, registryFile, requiredArchSkill, resolveMaxLines, resolveSessions, resolveTtlSec, routeReferences, runGuards, saveState, scoreReferences, securityGuard, setStateField, skillTriggerGate, solidReadGate, splitTarget, stateFileFor, stateFilePath, summarizeIndex, taskComplete, taskCreate, taskStart, throttleMs, toRefMeta, ttlLabel, usesTailwindUtilities, walkUpFor, webfetchCacheWrite };
+export { APEX_GATES, ASK_PATTERNS, ASK_WRITERS, CODE_MUTATORS, CODE_REDIRECT, COLOR_THRESHOLDS, CRITICAL_PATTERNS, DEFAULT_MAX_LINES, DEFAULT_TTL_SEC, DEV_KEYWORDS, DEV_VERBS, EXCLUDE_DIRS, FAIL_CLOSED, FILE_REDIRECT, GIT_ASK, GIT_BLOCKED, GO_DECL_RE, GRADIENT_BLOCKS, GUARDS, HOME_DIR, JAVA_DECL_RE, MAX_EXA_RESULTS, MAX_LINES_ENV_KEY, MAX_TOKENS, PHP_DECL_RE, PLUGINS_DIR, PROGRESS_BAR_DEFAULTS, PROGRESS_CHARS, PROJECT_INDICATORS, PROJECT_INSTALL, PROTECTED_FRAGMENTS, PROTECTED_GIT_RE, PY_MODEL_RE, SAFE_PREFIXES, SESSION_STATE_FRAGMENT, SKILL_TRIGGERS, SOLID_REF, STATE_GITIGNORE, STATE_ROOT, SWIFT_PROTO_RE, SYSTEM_INSTALL, TIME_INTERVALS, TS_DECL_RE, TTL_ENV_KEY, acquireLock, addRoot, apexStateDir, bashWriteGuard, brainstormGate, buildApexInstruction, buildApexTaskContext, buildApexTaskInjection, buildClaudeMdContext, cacheLookup, cacheLookupMeta, cacheLookupSubstring, cacheLookupSubstringMeta, cachePath, cacheStore, capVerbosity, clearUserGuards, colors, compactJson, compactMarkdown, countFrameworkCodeLines, countLines, descFromText, detectClaudeMdProjectType, detectCreationIntent, detectFramework, detectHarness, detectMode, detectModularArchitecture, detectProjectType, detectRequiredSkills, docConsultedGate, ensureMemoryGitignore, ensureStateDir, envCandidates, evaluate, evaluateApex, evaluateFileSize, extractText, firstComment, firstHeading, formatBasename, formatCost, formatDocDeny, formatDocSatisfactionStatus, formatPath, formatPrompt, formatTimeLeft, formatTokens, frameworkSolidGate, freshnessGate, generateGradientBar, generateProgressBar, globToRe, incrementTrivialEditCounter, installGuard, interfaceSeparationGuard, isApexCommand, isCodeFile, isDocConsulted, isHtmlLike, jaccardSimilar, lessonsFileFor, loadApexTaskState, loadDotenv, loadIndex, loadRefs, loadState, matchPatterns, mcpCacheKey, mcpCacheWrite, missingSeoElements, modeFor, nowStamp, parseBodyDesc, parseEnrichment, parseEntry, parseEnvFile, parseEnvInt, parseField, parseFrontmatter, progressiveColor, projectLayout, projectRoot, projectRootOrNull, protectedPathGuard, queryHash, readRoots, readState, registerGuard, registryFile, requiredArchSkill, resolveMaxLines, resolveSessions, resolveTtlSec, routeReferences, runGuards, saveState, scoreReferences, securityGuard, setStateField, skillTriggerGate, solidReadGate, splitTarget, stateFileFor, stateFilePath, summarizeIndex, taskComplete, taskCreate, taskStart, throttleMs, toRefMeta, ttlLabel, usesTailwindUtilities, walkUpFor, webfetchCacheWrite };

package/dist/{mcp-store-CnsW9oFj.mjs → mcp-store-BkBDmuxN.mjs}

@@ -130,10 +130,19 @@ function cachePath(dir, tool, query) {
 }
 /** Read a cached entry if it exists and is fresh (mtime within `ttlMs`), else null. */
 function cacheLookup(dir, tool, query, ttlMs, now) {
+	return cacheLookupMeta(dir, tool, query, ttlMs, now)?.body ?? null;
+}
+/** Like {@link cacheLookup}, but also reports the entry's age (for `CACHE HIT` wrapper text). */
+function cacheLookupMeta(dir, tool, query, ttlMs, now) {
 	const path = cachePath(dir, tool, query);
 	try {
-		if (!existsSync(path) || now - statSync(path).mtimeMs > ttlMs) return null;
-		return readFileSync(path, "utf8");
+		if (!existsSync(path)) return null;
+		const ageMs = now - statSync(path).mtimeMs;
+		if (ageMs > ttlMs) return null;
+		return {
+			body: readFileSync(path, "utf8").slice(0, MAX_BODY),
+			ageMs
+		};
 	} catch {
 		return null;
 	}
@@ -148,6 +157,10 @@ function cacheLookup(dir, tool, query, ttlMs, now) {
 * @param now - Current epoch ms.
 */
 function cacheLookupSubstring(dir, query, ttlMs, now) {
+	return cacheLookupSubstringMeta(dir, query, ttlMs, now)?.body ?? null;
+}
+/** Like {@link cacheLookupSubstring}, but also reports the matched entry's age. */
+function cacheLookupSubstringMeta(dir, query, ttlMs, now) {
 	const needle = query.replace(/[\r\n]+/g, " ").slice(0, NEEDLE_LEN).trim().toLowerCase();
 	if (!needle) return null;
 	let names;
@@ -160,9 +173,13 @@ function cacheLookupSubstring(dir, query, ttlMs, now) {
 		if (!name.endsWith(".md")) continue;
 		const path = join(dir, name);
 		try {
-			if (now - statSync(path).mtimeMs > ttlMs) continue;
+			const ageMs = now - statSync(path).mtimeMs;
+			if (ageMs > ttlMs) continue;
 			const body = readFileSync(path, "utf8").slice(0, MAX_BODY);
-			if (body.toLowerCase().includes(needle)) return body;
+			if (body.toLowerCase().includes(needle)) return {
+				body,
+				ageMs
+			};
 		} catch {
 			continue;
 		}
@@ -235,4 +252,4 @@ function webfetchCacheWrite(dir, tool, key, body, now) {
 	cacheStore(dir, tool, key, `---\ntool: ${tool}\nkey: ${JSON.stringify(key)}\nts: ${stamp(now)}\nhash: ${hash}\n---\n\n` + compacted);
 }
 //#endregion
-export { cachePath as a, extractText as c, compactMarkdown as d, jaccardSimilar as f, cacheLookupSubstring as i, loadIndex as l, webfetchCacheWrite as n, cacheStore as o, queryHash as p, cacheLookup as r, mcpCacheKey as s, mcpCacheWrite as t, summarizeIndex as u };
+export { cacheLookupSubstring as a, cacheStore as c, loadIndex as d, summarizeIndex as f, queryHash as h, cacheLookupMeta as i, mcpCacheKey as l, jaccardSimilar as m, webfetchCacheWrite as n, cacheLookupSubstringMeta as o, compactMarkdown as p, cacheLookup as r, cachePath as s, mcpCacheWrite as t, extractText as u };

package/dist/policy/index.mjs

@@ -1,4 +1,4 @@
-import { A as detectCreationIntent, B as detectProjectType, C as skillTriggerGate, D as MAX_EXA_RESULTS, E as frameworkSolidGate, F as freshnessGate, H as requiredArchSkill, I as solidReadGate, L as detectFramework, M as brainstormGate, N as docConsultedGate, O as MAX_TOKENS, P as evaluateApex, R as DEV_KEYWORDS, S as detectRequiredSkills, T as SKILL_TRIGGERS, V as isApexCommand, a as firstHeading, c as EXCLUDE_DIRS, d as buildApexTaskInjection, f as loadApexTaskState, g as detectClaudeMdProjectType, h as buildClaudeMdContext, i as firstComment, j as APEX_GATES, k as capVerbosity, l as PROJECT_INDICATORS, m as buildApexInstruction, n as missingSeoElements, o as parseEnrichment, p as DEV_VERBS, r as descFromText, s as parseEntry, t as isHtmlLike, u as buildApexTaskContext, v as parseBodyDesc, w as usesTailwindUtilities, y as parseField, z as detectModularArchitecture } from "../validate-Ca7NSp-r.mjs";
+import { A as detectCreationIntent, B as detectProjectType, D as MAX_EXA_RESULTS, E as frameworkSolidGate, F as freshnessGate, H as requiredArchSkill, I as solidReadGate, L as detectFramework, M as brainstormGate, N as docConsultedGate, O as MAX_TOKENS, P as evaluateApex, R as DEV_KEYWORDS, S as usesTailwindUtilities, T as SKILL_TRIGGERS, V as isApexCommand, a as firstHeading, b as detectRequiredSkills, c as EXCLUDE_DIRS, d as buildApexTaskInjection, f as loadApexTaskState, g as detectClaudeMdProjectType, h as buildClaudeMdContext, i as firstComment, j as APEX_GATES, k as capVerbosity, l as PROJECT_INDICATORS, m as buildApexInstruction, n as missingSeoElements, o as parseEnrichment, p as DEV_VERBS, r as descFromText, s as parseEntry, t as isHtmlLike, u as buildApexTaskContext, v as parseBodyDesc, x as skillTriggerGate, y as parseField, z as detectModularArchitecture } from "../validate-DcQaKzau.mjs";
 import { A as PROJECT_INSTALL, C as PROTECTED_GIT_RE, D as securityGuard, E as CRITICAL_PATTERNS, F as countFrameworkCodeLines, I as countLines, L as evaluateFileSize, M as matchPatterns, N as PLUGINS_DIR, O as GIT_ASK, P as SOLID_REF, S as PROTECTED_FRAGMENTS, T as ASK_PATTERNS, _ as CODE_MUTATORS, a as registerGuard, b as SAFE_PREFIXES, c as GO_DECL_RE, d as PY_MODEL_RE, f as SWIFT_PROTO_RE, g as ASK_WRITERS, h as bashWriteGuard, i as clearUserGuards, j as SYSTEM_INSTALL, k as GIT_BLOCKED, l as JAVA_DECL_RE, m as interfaceSeparationGuard, n as FAIL_CLOSED, o as runGuards, p as TS_DECL_RE, r as GUARDS, s as installGuard, t as evaluate, u as PHP_DECL_RE, v as CODE_REDIRECT, w as protectedPathGuard, x as SESSION_STATE_FRAGMENT, y as FILE_REDIRECT } from "../evaluate-d7Pp8XJH.mjs";
 import "../policy-la_KkjCS.mjs";
 export { APEX_GATES, ASK_PATTERNS, ASK_WRITERS, CODE_MUTATORS, CODE_REDIRECT, CRITICAL_PATTERNS, DEV_KEYWORDS, DEV_VERBS, EXCLUDE_DIRS, FAIL_CLOSED, FILE_REDIRECT, GIT_ASK, GIT_BLOCKED, GO_DECL_RE, GUARDS, JAVA_DECL_RE, MAX_EXA_RESULTS, MAX_TOKENS, PHP_DECL_RE, PLUGINS_DIR, PROJECT_INDICATORS, PROJECT_INSTALL, PROTECTED_FRAGMENTS, PROTECTED_GIT_RE, PY_MODEL_RE, SAFE_PREFIXES, SESSION_STATE_FRAGMENT, SKILL_TRIGGERS, SOLID_REF, SWIFT_PROTO_RE, SYSTEM_INSTALL, TS_DECL_RE, bashWriteGuard, brainstormGate, buildApexInstruction, buildApexTaskContext, buildApexTaskInjection, buildClaudeMdContext, capVerbosity, clearUserGuards, countFrameworkCodeLines, countLines, descFromText, detectClaudeMdProjectType, detectCreationIntent, detectFramework, detectModularArchitecture, detectProjectType, detectRequiredSkills, docConsultedGate, evaluate, evaluateApex, evaluateFileSize, firstComment, firstHeading, frameworkSolidGate, freshnessGate, installGuard, interfaceSeparationGuard, isApexCommand, isHtmlLike, loadApexTaskState, matchPatterns, missingSeoElements, parseBodyDesc, parseEnrichment, parseEntry, parseField, protectedPathGuard, registerGuard, requiredArchSkill, runGuards, securityGuard, skillTriggerGate, solidReadGate, usesTailwindUtilities };

package/dist/runtime/index.mjs

@@ -1,6 +1,6 @@
 import { r as projectLayout } from "../layout-C0jaaCQC.mjs";
 import { a as sanitizeSessionId, c as sessionsDir, i as loadSessionState, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, s as sessionStatePath, t as claudeHome } from "../home-state-mKZxP4oZ.mjs";
-import { $ as saveApexState, A as trackSkillRead, At as securityStateDir, B as writePluginMap, C as seoPostToolUse, Ct as defaultStateDir, D as postTrackingSideEffects, Dt as isoUtc, E as securityAdvisory, Et as normalizeEvent, F as dispatchLessons, G as mergeLines, H as isProject, I as lessonsFileFor, J as listChildren, K as countFiles, L as lessonsStateFileFor, M as dispatchLifecycle, Mt as todayUtc, N as aipilotPostToolUse, O as trackWatchResearch, Ot as loadSecurityState, P as dispatchAipilot, Q as cleanupSession, R as cartoSessionStart, S as postEditContext, St as taskContext, T as dispatchMemory, Tt as trackFile, U as writeTree, V as generateProjectMap, W as loadEnriched, X as trackSessionChanges, Y as postEditTypescript, Z as validateRulesLoaded, _ as preCommitGate, _t as trimLogFile, a as recordActivity, at as validateSolidGate, b as extractSymbols, bt as projectContext, c as MCP_TTL_MS, ct as detectSolidProfile, d as isMcpTool, dt as readRules, et as logToolFailure, f as queryOf, ft as runSessionStartCleanups, g as gate, gt as removeOldFiles, h as TRIVIAL_BUDGET, ht as purgeTtlTree, i as respond, it as validateTailwind, j as trackEnrichment, jt as securityStatePath, k as trackMcpResearch, kt as saveSecurityState, l as WEBFETCH_TTL_MS, lt as solidDetectStart, m as REQUIRED_AGENTS, mt as pruneEmptyDirs, n as activityFor, nt as trackAgentMemory, o as mcpPostStore, ot as checkFileSize, p as DEFAULT_WINDOW_MS, pt as sessionStartCore, q as getFileDesc, r as handlePre, rt as subagentCacheContext, s as mcpPreIntercept, st as countLoc, t as handleHook, tt as validateTeammateOutput, u as cacheQueryOf, ut as injectRules, v as detectDuplication, vt as devContext, w as seoPostToolUseResponse, wt as projectHash, x as lifecycleStdout, xt as promptSubmitContext, y as dryGate, yt as gitContext, z as generateEcosystemMap } from "../handle-CtMMVoxT.mjs";
+import { $ as saveApexState, A as trackSkillRead, At as securityStateDir, B as writePluginMap, C as seoPostToolUse, Ct as defaultStateDir, D as postTrackingSideEffects, Dt as isoUtc, E as securityAdvisory, Et as normalizeEvent, F as dispatchLessons, G as mergeLines, H as isProject, I as lessonsFileFor, J as listChildren, K as countFiles, L as lessonsStateFileFor, M as dispatchLifecycle, Mt as todayUtc, N as aipilotPostToolUse, O as trackWatchResearch, Ot as loadSecurityState, P as dispatchAipilot, Q as cleanupSession, R as cartoSessionStart, S as postEditContext, St as taskContext, T as dispatchMemory, Tt as trackFile, U as writeTree, V as generateProjectMap, W as loadEnriched, X as trackSessionChanges, Y as postEditTypescript, Z as validateRulesLoaded, _ as preCommitGate, _t as trimLogFile, a as recordActivity, at as validateSolidGate, b as extractSymbols, bt as projectContext, c as MCP_TTL_MS, ct as detectSolidProfile, d as isMcpTool, dt as readRules, et as logToolFailure, f as queryOf, ft as runSessionStartCleanups, g as gate, gt as removeOldFiles, h as TRIVIAL_BUDGET, ht as purgeTtlTree, i as respond, it as validateTailwind, j as trackEnrichment, jt as securityStatePath, k as trackMcpResearch, kt as saveSecurityState, l as WEBFETCH_TTL_MS, lt as solidDetectStart, m as REQUIRED_AGENTS, mt as pruneEmptyDirs, n as activityFor, nt as trackAgentMemory, o as mcpPostStore, ot as checkFileSize, p as DEFAULT_WINDOW_MS, pt as sessionStartCore, q as getFileDesc, r as handlePre, rt as subagentCacheContext, s as mcpPreIntercept, st as countLoc, t as handleHook, tt as validateTeammateOutput, u as cacheQueryOf, ut as injectRules, v as detectDuplication, vt as devContext, w as seoPostToolUseResponse, wt as projectHash, x as lifecycleStdout, xt as promptSubmitContext, y as dryGate, yt as gitContext, z as generateEcosystemMap } from "../handle-DJaaD2BT.mjs";
 //#region src/runtime/storage.ts
 /**
 * The project's single state dir (`<root>/.harness`) — neutral + harness-agnostic,

package/dist/{validate-Ca7NSp-r.mjs → validate-DcQaKzau.mjs}

@@ -804,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`.
@@ -867,56 +955,10 @@ function skillTriggerGate(framework, content, refsRead, forcedSkill, cwd, filePa
 		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/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/cartographer/frontmatter.ts
 /**
 * Frontmatter parsing — pure text helpers (no fs). Ports `parse_frontmatter.py`.
@@ -1497,4 +1539,4 @@ function missingSeoElements(html) {
 	return missing;
 }
 //#endregion
-export { detectCreationIntent as A, detectProjectType as B, skillTriggerGate 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, detectRequiredSkills as S, SKILL_TRIGGERS as T, isApexCommand as V, scanPlugin as _, firstHeading as a, findMarketplacePlugins 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, usesTailwindUtilities as w, readPluginMeta as x, parseField as y, detectModularArchitecture as z };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusengine/harness",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "Harness-agnostic toolkit for AI coding agents: runtime harness detection (Claude Code, Codex, Cursor, Cline, Gemini, Aider...), pure policy core (env config, project/framework detection, SOLID/file-size limits, APEX freshness, guard patterns, portable prompts), cache, project memory, ref routing, state/locks, statusline, per-harness adapters (Claude/Cursor/Cline/Gemini) and a cli-mode harness-check binary. Bun-native, with a built dist for Node + bundlers.",
   "type": "module",
   "module": "src/index.ts",