@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/lifecycle/validate-tailwind.ts

@@ -0,0 +1,80 @@
+/**
+ * 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`.
+ */
+import { dirname, join } from "node:path";
+import { readText, pathExists } from "../../util/runtime-io";
+import { contextResponse } from "../../adapters/claude";
+
+/** 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: string): string | null {
+  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: string): boolean {
+  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)) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    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.
+ */
+export function validateTailwind(tool: string, filePath: string): string {
+  if (tool !== "Write" && tool !== "Edit") return "";
+  if (!/\.(css|tsx|jsx)$/.test(filePath)) return "";
+  if (!pathExists(filePath) || !isTailwindProject(filePath)) return "";
+
+  let content: string;
+  try {
+    content = readText(filePath);
+  } catch {
+    return "";
+  }
+
+  const warnings: string[] = [];
+
+  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(" "));
+}

package/src/runtime/lifecycle-bridge.ts

@@ -0,0 +1,74 @@
+import { dispatchLifecycle, postEditTypescript, trackSessionChanges, type PluginScope } from "./lifecycle";
+import { autoDocumentRead } from "./lifecycle/auto-document-reads";
+import { contextResponse } from "../adapters/claude";
+import { cursorEventContract } from "../adapters/cursor/events";
+import { toCursorLifecycleResponse } from "../adapters/cursor/respond";
+import type { NormalizedEvent } from "./normalize";
+
+/** Raw event name from a payload (Cline lacks one; lifecycle is Claude-only). */
+function rawEvent(payload: Record<string, unknown>): string {
+  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: string): string {
+  if (!stdout) return "";
+  try {
+    const parsed = JSON.parse(stdout) as { hookSpecificOutput?: { additionalContext?: string } };
+    return parsed.hookSpecificOutput?.additionalContext ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Run the ported lifecycle/session/context hooks (SessionStart, SubagentStart/
+ * Stop, TeammateIdle, PostToolUseFailure, PreCompact, SessionEnd,
+ * InstructionsLoaded, rules-scope UserPromptSubmit). Returns the native stdout
+ * when handled, or `null` to fall through to the tool-use pipeline.
+ * @param payload - The raw hook payload.
+ * @param cwd - Project root.
+ * @param scope - The invoking plugin scope (defaults to `core`).
+ * @param now - Clock.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native stdout, or `null` when unhandled.
+ */
+export function lifecycleStdout(payload: Record<string, unknown>, cwd: string, scope: PluginScope, now: number, id: string = "claude-code"): string | null {
+  const wireEvent = rawEvent(payload);
+  if (id !== "cursor") return dispatchLifecycle({ event: wireEvent, payload, cwd, scope, now, id });
+  const lifecycleEvent = cursorEventContract(wireEvent).lifecycle;
+  if (lifecycleEvent === null) return null;
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : payload.conversation_id;
+  const stdout = dispatchLifecycle({
+    event: lifecycleEvent,
+    payload: { ...payload, session_id: sessionId },
+    cwd,
+    scope,
+    now,
+    id,
+  });
+  return stdout === null ? null : toCursorLifecycleResponse(stdout, wireEvent);
+}
+
+/**
+ * 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.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The extra stdout (possibly empty).
+ */
+export async function postEditContext(scope: PluginScope, event: NormalizedEvent, now: number, id: string = "claude-code"): Promise<string> {
+  if (scope !== "core" || !event.filePath) return "";
+  if (event.tool === "Read") return autoDocumentRead(event.filePath, now, id);
+  if (event.tool !== "Write" && event.tool !== "Edit") return "";
+  const sniper = trackSessionChanges(event.sessionId, event.filePath, undefined, now);
+  const lint = postEditTypescript(event.filePath);
+  if (!sniper || !lint) return sniper || lint;
+  return contextResponse("PostToolUse", `${additionalContextOf(sniper)}\n\n${additionalContextOf(lint)}`);
+}

package/src/runtime/mcp-key.ts

@@ -0,0 +1,44 @@
+/** Cache-key + tool-class helpers for the MCP/WebFetch interception pipeline. */
+import { parseEnvInt } from "../config/env";
+
+/** Default cached-MCP freshness in seconds (48h). */
+const MCP_TTL_DEFAULT_SEC = 172_800;
+/** Default WebFetch freshness in seconds (24h, parity with Python). */
+const WEBFETCH_TTL_DEFAULT_SEC = 86_400;
+
+/** Cached-MCP freshness (ms) from `FUSE_MCP_TTL_SEC` (default 48h). */
+export const MCP_TTL_MS: number = parseEnvInt(process.env.FUSE_MCP_TTL_SEC, MCP_TTL_DEFAULT_SEC) * 1000;
+
+/** WebFetch freshness (ms) from `FUSE_WEBFETCH_TTL_SEC` (default 24h; pages stale faster than docs). */
+export const WEBFETCH_TTL_MS: number = parseEnvInt(process.env.FUSE_WEBFETCH_TTL_SEC, WEBFETCH_TTL_DEFAULT_SEC) * 1000;
+
+/** WebFetch prompt slice folded into its cache key (parity with Python prompt[:500]). */
+const PROMPT_TRUNC = 500;
+
+/** True for the WebFetch tool (exact name) or Kimi Code CLI's `FetchURL` equivalent. */
+export function isWebFetch(tool: string): boolean {
+  return tool === "WebFetch" || tool === "FetchURL";
+}
+
+/** MCP doc tools + WebFetch/FetchURL whose calls are cached / verbosity-capped. */
+export function isMcpTool(tool: string): boolean {
+  return /context7|exa|webfetch|web_fetch/i.test(tool) || isWebFetch(tool);
+}
+
+/** The query/url that keys the cache. */
+export function queryOf(input: Record<string, unknown>): string {
+  const q = input.query ?? input.url ?? input.libraryId ?? "";
+  return typeof q === "string" ? q : JSON.stringify(q);
+}
+
+/**
+ * The string that keys the cache for `tool`. WebFetch folds `url + "\n" +
+ * prompt[:500]` (parity with Python) so distinct prompts on the same URL never
+ * collide; every other tool keys on {@link queryOf}.
+ */
+export function cacheQueryOf(tool: string, input: Record<string, unknown>): string {
+  if (!isWebFetch(tool)) return queryOf(input);
+  const url = typeof input.url === "string" ? input.url.trim() : "";
+  const prompt = typeof input.prompt === "string" ? input.prompt : "";
+  return `${url}\n${prompt.slice(0, PROMPT_TRUNC)}`;
+}

package/src/runtime/mcp-tool-name.ts

@@ -0,0 +1,92 @@
+/**
+ * @module mcp-tool-name
+ * Canonicalizes a Codex-only MCP `tool_name` alias back to its original
+ * hyphenated form, so every existing dash-keyed consumer (`SHOT_TOOLS`,
+ * `RESEARCH_TOOLS`/`classifyExplore`, `docSourceOf`, the design-pipeline
+ * `NAV`/`SCROLL`/`GEMINI` constants, …) recognizes a Codex MCP call exactly
+ * like the same call on Claude/Kimi/Cursor/Cline/Gemini — no per-consumer
+ * change needed.
+ *
+ * Codex CLI globally rewrites every `-` to `_` across the FULL qualified MCP
+ * tool identifier before it ever reaches a hook, in `sanitize_responses_api_tool_name()`
+ * (`codex-rs/core/src/mcp_connection_manager.rs`, introduced by
+ * openai/codex#14605 — "Normalize MCP tool names to code-mode safe form",
+ * code-mode forbids `-` in identifiers). openai/codex#18385's own
+ * `SCENARIO_DASH_TOOL` test proves the REWRITTEN form is what reaches hooks:
+ * the `echo-tool` tool of server `rmcp` is delivered to hooks as
+ * `mcp__rmcp__echo_tool`. Confirmed independently in THIS repo's terrain:
+ * `~/.codex/config.toml` declares `[mcp_servers.fuse-browser]` (dash) while
+ * Codex session logs and this harness's own dual-marketplace hook payloads
+ * (`~/.codex/plugins/.../hooks.json` matchers) observe `mcp__fuse_browser__*`
+ * (underscore) — Claude never emits that form (0 occurrences across its
+ * transcripts vs 137x the dash form).
+ *
+ * The rewrite is deliberately NOT undone with a generic `_` -> `-` regex:
+ * openai/codex#15832 and #15565 document it as NON-INVERSIBLE — a server
+ * literally named `autok_local` collides with a dash-named `autok-local`
+ * once both pass through the same rewrite, and OpenAI's own fix was a closed
+ * canonical table, never a general regex. The SAME ambiguity exists on our
+ * side: a generic reversal would corrupt tool segments that legitimately
+ * contain an underscore already (`browser_screenshot`, `node_repl`,
+ * `build_sim`, …). So this module only reverses the FOUR entries proven
+ * above to matter to this repo's gates — every other segment passes through
+ * untouched.
+ * @packageDocumentation
+ */
+
+/**
+ * Codex-mangled MCP server segment -> its real (dash) server name. Closed set
+ * — see module doc. `Object.create(null)` (never a `{}` literal): `serverKey`
+ * is an attacker-influenced string (an MCP server can register itself as
+ * `"__proto__"`/`"constructor"`/`"toString"`), and a `{}`-literal lookup by
+ * such a key returns the INHERITED `Object.prototype` member instead of
+ * `undefined` — an object/function, so `?? serverKey` never falls back and
+ * the result silently corrupts to `"mcp__[object Object]__…"` (proven in
+ * `test/mcp-tool-name.test.ts`, prototype-pollution-read case). A null-
+ * prototype object has no inherited members, so every lookup outside the two
+ * literal keys below is a clean miss.
+ */
+const SERVER_ALIASES: Readonly<Record<string, string>> = Object.assign(Object.create(null), {
+  fuse_browser: "fuse-browser",
+  gemini_design: "gemini-design",
+});
+
+/**
+ * Codex-mangled MCP tool segment -> its real (dash) tool name. Both entries
+ * are `context7`-exclusive tool names — applied ONLY when the canonical
+ * server is `"context7"` (see the explicit guard in
+ * {@link canonicalizeMcpToolName}), never globally. A same-named tool on any
+ * other server (e.g. a hypothetical `exa__query_docs`) passes through
+ * untouched: openai/codex#15832 documents exactly this class of collision as
+ * the reason the rewrite must stay a closed, scoped table, never a blanket
+ * one. Closed set, same null-prototype rationale as {@link SERVER_ALIASES}.
+ */
+const TOOL_ALIASES: Readonly<Record<string, string>> = Object.assign(Object.create(null), {
+  query_docs: "query-docs",
+  resolve_library_id: "resolve-library-id",
+});
+
+/**
+ * Canonicalize a Codex-only MCP tool-name alias to its dash form. Scoped to
+ * `id === "codex"` — every other harness id passes through unchanged. The
+ * server segment is rewritten via the closed {@link SERVER_ALIASES} table;
+ * the tool segment is rewritten via {@link TOOL_ALIASES} ONLY when the
+ * (already-resolved) canonical server is `"context7"` — every other server's
+ * tool segment is left untouched even if it happens to share a name with a
+ * context7 tool. Every other `mcp__<server>__<tool>` segment (or non-MCP
+ * tool name) is returned byte-identical (see `test/mcp-tool-name.test.ts`
+ * for the non-regression proof across ids, trap tool names, and the
+ * server-scoping cases).
+ * @param id - Harness adapter id (e.g. "codex", "claude-code", "kimi").
+ * @param tool - Raw `tool_name` from the hook payload.
+ */
+export function canonicalizeMcpToolName(id: string, tool: string): string {
+  if (id !== "codex") return tool;
+  const parts = tool.split("__");
+  if (parts.length < 3 || parts[0] !== "mcp") return tool;
+  const serverKey = parts[1] ?? "";
+  const toolKey = parts.slice(2).join("__");
+  const server = SERVER_ALIASES[serverKey] ?? serverKey;
+  const rest = server === "context7" ? (TOOL_ALIASES[toolKey] ?? toolKey) : toolKey;
+  return `mcp__${server}__${rest}`;
+}

package/src/runtime/mcp.ts

@@ -0,0 +1,91 @@
+import { capVerbosity } from "../policy/verbosity";
+import { cacheLookupMeta, cacheLookupSubstringMeta, type CacheHit } from "../cache/store";
+import { extractText } from "../cache/mcp-response";
+import { mcpCacheWrite, webfetchCacheWrite } from "../cache/mcp-store";
+import { WEBFETCH_TTL_MS, cacheQueryOf, isMcpTool, isWebFetch } from "./mcp-key";
+import { kimiDenyResponse } from "../adapters/kimi";
+
+export { MCP_TTL_MS, WEBFETCH_TTL_MS, cacheQueryOf, isMcpTool, queryOf } from "./mcp-key";
+
+function denyWith(id: string, content: string): string {
+  if (id === "claude-code" || id === "codex") {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: content } });
+  }
+  if (id === "gemini-cli") return JSON.stringify({ decision: "deny", reason: content });
+  if (id === "kimi") return kimiDenyResponse(content);
+  return "";
+}
+
+function mutateWith(id: string, input: Record<string, unknown>): string {
+  if (id === "claude-code" || id === "codex") {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: input } });
+  }
+  if (id === "gemini-cli") return JSON.stringify({ hookSpecificOutput: { tool_input: input } });
+  // Kimi has no input-mutation contract (`updatedInput` is undocumented
+  // upstream) — the exa verbosity cap stays inoperative there.
+  return "";
+}
+
+/** The doc provider a served cache-hit satisfies (`exa`/`context7`), else undefined. */
+function docSourceOf(tool: string): string | undefined {
+  if (/exa/i.test(tool)) return "exa";
+  if (/context7/i.test(tool)) return "context7";
+  return undefined;
+}
+
+/**
+ * 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: boolean, hit: CacheHit): string {
+  const kb = Math.floor(hit.body.length / 1024) + 1;
+  const hours = Math.floor(hit.ageMs / 3_600_000);
+  return web
+    ? `CACHE HIT WebFetch (~${kb}KB saved, cached ${hours}h ago):\n\n${hit.body}\n\nModify the URL or query to force a fresh fetch.`
+    : `CACHE HIT (~${kb}KB saved, cached ${hours}h ago): ${hit.body}\n\nRephrase to force a re-call.`;
+}
+
+/** A pre-event MCP interception: the native response + any doc source it satisfied. */
+export interface McpIntercept {
+  stdout: string;
+  docSource?: string;
+}
+
+/**
+ * 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.
+ */
+export function mcpPreIntercept(id: string, tool: string, input: Record<string, unknown>, dir: string, ttlMs: number, now: number): McpIntercept | null {
+  if (!isMcpTool(tool)) return null;
+  const web = isWebFetch(tool);
+  const ttl = web ? WEBFETCH_TTL_MS : ttlMs;
+  const key = cacheQueryOf(tool, input);
+  // Exact key first; for MCP docs fall back to a substring hit (Python `rg -i -F`).
+  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(tool) };
+  }
+  const capped = capVerbosity(tool, input);
+  if (capped) {
+    const mutated = mutateWith(id, capped);
+    if (mutated) return { stdout: mutated };
+  }
+  return null;
+}
+
+/**
+ * Post-event: persist the MCP/WebFetch response (extracted to markdown). MCP docs
+ * go through {@link mcpCacheWrite} (compact + Jaccard-dedup + `index.json`);
+ * WebFetch uses {@link webfetchCacheWrite} (compact, exact key, no index).
+ * @param now - Current epoch ms (timestamp source; defaults to `Date.now()`).
+ */
+export function mcpPostStore(tool: string, input: Record<string, unknown>, response: unknown, dir: string, now: number = Date.now()): void {
+  if (!isMcpTool(tool)) return;
+  const text = extractText(response);
+  const key = cacheQueryOf(tool, input);
+  if (isWebFetch(tool)) webfetchCacheWrite(dir, tool, key, text, now);
+  else mcpCacheWrite(dir, tool, key, text, now);
+}

package/src/runtime/modular.ts

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs";
+import { join, relative, basename } from "node:path";
+import type { Prompt } from "../prompt/types";
+import { detectModularArchitecture } from "../policy/detect-project";
+
+const NEXT_CONVENTION = /^(page|layout|loading|error|not-found|route|template|default|global-error|opengraph-image|twitter-image|icon|apple-icon|sitemap|robots|manifest|middleware)\.(tsx|ts|js|jsx)$/;
+const NEXT_STATIC = /\.(css|ico|png|jpg|svg|json)$/;
+const PHP_BLOCKED_IN_APP: readonly string[] = [
+  "/app/Models/", "/app/Services/", "/app/Actions/", "/app/Http/Controllers/",
+  "/app/Http/Requests/", "/app/Http/Resources/", "/app/Contracts/", "/app/DTOs/",
+  "/app/Repositories/", "/app/Events/", "/app/Listeners/", "/app/Jobs/",
+  "/app/Notifications/", "/app/Policies/",
+];
+
+const block = (reason: string): Prompt => ({
+  kind: "block", title: "Modular architecture", reason,
+  actions: ["Move the code into the correct feature module", "Import only from the shared core module"],
+});
+
+/** Next.js `modules/` architecture: `app/` convention + cross-module import rules. */
+function nextModular(filePath: string, content: string, cwd: string): Prompt | null {
+  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(`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(`BLOCKED: modules/cores/ must not import from modules/${imported}/. Cores must be independent.`);
+    } else if (imported !== current && imported !== "cores" && imported !== "core") {
+      return block(`BLOCKED: cross-module import — '${current}' imports from '${imported}'. Only modules/cores/ is shared.`);
+    }
+  }
+  return null;
+}
+
+/** Laravel FuseCore architecture: `app/` domain ban + module.json + cross-module `use` rules. */
+function fusecore(filePath: string, content: string, cwd: string): Prompt | null {
+  for (const b of PHP_BLOCKED_IN_APP) {
+    if (filePath.includes(b)) {
+      // Parity validate-fusecore.py:52-55 — name the precise target sub-path per
+      // entry (blocked.replace("/app/","/FuseCore/{Module}/App/")), not a generic dir.
+      const from = b.replace(/^\/|\/$/g, "");
+      const to = b.replaceAll("/app/", "/FuseCore/{Module}/App/").replace(/^\/|\/$/g, "");
+      return block(`BLOCKED: FuseCore project. Code in '${from}' FORBIDDEN. Move to '${to}'.`);
+    }
+  }
+  const mod = filePath.match(/\/FuseCore\/([A-Za-z]+)\//);
+  if (!mod) return null;
+  const name = mod[1] ?? "";
+  const mj = join(cwd, "FuseCore", name, "module.json");
+  // Parity validate-fusecore.py: name the full path to create ("Create {mj} first.").
+  if (!existsSync(mj)) return block(`BLOCKED: Module '${name}' missing module.json. Create ${mj} first.`);
+  for (const m of content.matchAll(/use\s+FuseCore\\(\w+)\\/g)) {
+    const imported = m[1] ?? "";
+    if (name === "Core") {
+      if (imported !== "Core") return block(`BLOCKED: FuseCore\\Core\\ must not use FuseCore\\${imported}\\.`);
+    } else if (imported !== name && imported !== "Core") {
+      return block(`BLOCKED: cross-module use — '${name}' uses '${imported}'. Only FuseCore\\Core\\ is shared.`);
+    }
+  }
+  return null;
+}
+
+/** Enforce the project's modular architecture (Next.js `modules/` or Laravel FuseCore) on a Write/Edit. */
+export function modularGate(tool: string, filePath: string | undefined, content: string | undefined, cwd: string | undefined): Prompt | null {
+  if ((tool !== "Write" && tool !== "Edit") || !filePath || !cwd) return null;
+  if (/\/(node_modules|dist|build|\.next|vendor|storage)\//.test(filePath)) return null;
+  const arch = detectModularArchitecture(cwd);
+  if (arch === "nextjs-modular" && /\.(tsx|ts|jsx|js)$/.test(filePath)) return nextModular(filePath, content ?? "", cwd);
+  if (arch === "fusecore" && filePath.endsWith(".php")) return fusecore(filePath, content ?? "", cwd);
+  return null;
+}

package/src/runtime/normalize.ts

@@ -0,0 +1,107 @@
+import { parseApplyPatch } from "../adapters/codex/apply-patch";
+import { extractCursorEvent } from "../adapters/cursor/normalize";
+import { commandToString } from "./command-string";
+import { canonicalizeCodexShellTool } from "./codex-shell-tool";
+import { canonicalizeMcpToolName } from "./mcp-tool-name";
+
+/** One file/edit fanned out from Codex `apply_patch` or Cursor `afterFileEdit`. */
+export interface NormalizedFile {
+  filePath: string;
+  content: string;
+  oldString?: string;
+  op: "add" | "update" | "delete";
+}
+
+/** A hook event normalized across harnesses. */
+export interface NormalizedEvent {
+  /** Native event name when the adapter exposes one explicitly (Cursor). */
+  eventName?: string;
+  phase: "pre" | "post";
+  tool: string;
+  input: Record<string, unknown>;
+  sessionId: string;
+  filePath?: string;
+  content?: string;
+  /** Edit only: the tool_input.old_string being replaced — lets the file-size gate (policy/evaluate.ts + policy/edit-outcome.ts) compute the post-edit outcome instead of judging the stale on-disk count alone. Undefined for Write (no such field) and for cline/apply_patch (parsed separately, no equivalent field). */
+  oldString?: string;
+  command?: string;
+  /** Cursor-only independent command candidates from beforeMCPExecution. */
+  commandCandidates?: string[];
+  /** Subagent type, if the tool-use came from one (Explore/Plan are file-size-exempt). */
+  agentType?: string;
+  /** Harness-resolved permission mode (Claude emits it natively; Codex maps `AskForApproval::Never` to the same "bypassPermissions" string — see adapters/codex/permission-mode.ts). Generic field, Codex-only consumer today. */
+  permissionMode?: string;
+  /** Codex logical tool-use identity, shared by sibling hook callbacks. */
+  toolUseId?: string;
+  /** Harness-reported working directory used to scope Codex authorization. */
+  cwd?: string;
+  /** Validated Cursor multi-root workspace paths in wire order. */
+  workspaceRoots?: string[];
+  /**
+   * Per-file changes for Codex `apply_patch` and per-edit changes for Cursor
+   * `afterFileEdit`; undefined for single-file events.
+   */
+  files?: NormalizedFile[];
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * Normalize a hook payload, including Cline nesting and native Cursor events.
+ */
+export function normalizeEvent(id: string, payload: Record<string, unknown>): NormalizedEvent {
+  if (id === "cline") {
+    const post = payload.postToolUse as Record<string, unknown> | undefined;
+    const node = (post ?? (payload.preToolUse as Record<string, unknown> | undefined)) ?? {};
+    const params = (node.parameters as Record<string, unknown> | undefined) ?? {};
+    return {
+      phase: post ? "post" : "pre",
+      tool: str(node.toolName) ?? "",
+      input: params,
+      sessionId: str(payload.taskId) ?? "",
+      filePath: str(params.path),
+      content: str(params.content),
+      command: str(params.command),
+    };
+  }
+  if (id === "cursor") {
+    return {
+      ...extractCursorEvent(payload),
+      sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
+      agentType: str(payload.agent_type),
+      permissionMode: str(payload.permission_mode),
+    };
+  }
+  const event = str(payload.hook_event_name) ?? "";
+  const input = (payload.tool_input as Record<string, unknown> | undefined) ?? payload;
+  const tool = canonicalizeCodexShellTool(id, canonicalizeMcpToolName(id, str(payload.tool_name) ?? ""));
+  const base = {
+    phase: (/post|after/i.test(event) ? "post" : "pre") as "pre" | "post",
+    tool,
+    input,
+    sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
+    agentType: str(payload.agent_type) ?? str(input.subagent_type),
+    permissionMode: str(payload.permission_mode),
+    toolUseId: str(payload.tool_use_id),
+    cwd: str(payload.cwd),
+  };
+  // Codex's `apply_patch` (its PRIMARY edit primitive) carries the whole change
+  // set as a freeform patch in `command` — no `file_path`/`content`, so the
+  // file-size/DRY/protected-path gates saw nothing (enforcement 0%). Fan it out
+  // into `files` and DROP the patch text from `command` so it can't false-match
+  // the git guards. Every other tool is untouched below.
+  if (tool === "apply_patch") {
+    const patch = str(input.command) ?? str(payload.command) ?? "";
+    const files = parseApplyPatch(patch).map((f) => ({ filePath: f.path, content: f.content, op: f.op }));
+    return { ...base, phase: base.phase, files: files.length > 0 ? files : undefined };
+  }
+  return {
+    ...base,
+    filePath: str(input.file_path) ?? str(input.path) ?? str(payload.file_path),
+    content: str(input.content) ?? str(input.new_string),
+    oldString: str(input.old_string),
+    command: commandToString(input.command) ?? commandToString(payload.command),
+  };
+}

package/src/runtime/notices.ts

@@ -0,0 +1,91 @@
+/**
+ * @module notices
+ * Compact, uniform "compliance" notices for the user-visible `systemMessage`
+ * channel — the visual counterpart to the additionalContext-only gate/credit
+ * signals, which land in agent-only context and stay invisible to the human in
+ * the Claude Code UI (deny reasons show in red; these did not show at all).
+ * Owner-reported gap: pass-notices existed in v0.1.49 for design gates, but
+ * nothing surfaced skill credits, freshness, or the sniper reminder to the human.
+ *
+ * The text builders are pure. `refCreditNoticeFor` is the one exception — like
+ * `pre-allow.ts` uses the JSON `oncePerWindow`, this one uses the exclusive
+ * {@link onceExclusive} mode instead: it fires on the same short burst window
+ * as `track-changes.ts`'s sniper reminder, fanned out across every installed
+ * plugin's PostToolUse hook for ONE real edit, so the same lost-update race
+ * applies (lesson 2026-07-05 16:00). Rendering onto a harness's native stdout
+ * always goes through the existing adapter helpers (`respond`/
+ * `attachSystemMessage`); a harness with no `systemMessage` channel (e.g.
+ * cline) silently drops the notice there (documented no-op, never a crash) —
+ * nothing in this module renders directly.
+ *
+ * CHANNEL CONTRACT — human-only, exactly once: the `userMessage`/`systemMessage`
+ * these notices ride is a HUMAN channel by platform contract. It never reaches
+ * the agent — `formatPrompt` (src/prompt/types.ts) excludes it — so the emitting
+ * sub-agent does NOT see its own notice; only the human owner does, and exactly
+ * ONCE even under the multi-plugin fan-out, because the emitter is gated by
+ * {@link onceExclusive}. Verified live 2026-07-06: under the real ×11 fan-out a
+ * single skill-ref Read surfaced one `✓ SOLID refs read` line in the owner's
+ * terminal (not duplicated, and correctly invisible to the agent).
+ */
+import { onceExclusive } from "./inject-dedup";
+import { BURST_DEDUP_MS } from "./burst-window";
+
+/** One compliance line: `✓ <gate> — <detail>` (detail omitted when empty). */
+export function complianceNotice(gate: string, detail: string): string {
+  return detail ? `✓ ${gate} — ${detail}` : `✓ ${gate}`;
+}
+
+/** One non-blocking requirement line: `⚠ <requirement> — <detail>`. */
+export function requirementNotice(requirement: string, detail: string): string {
+  return detail ? `⚠ ${requirement} — ${detail}` : `⚠ ${requirement}`;
+}
+
+/** Extract the skill name from a `.md` ref path (`.../skills/<name>/...`), or null when it isn't a skill reference (a banal doc Read — no notice). */
+export function skillNameFromRefPath(path: string): string | null {
+  const m = /skills\/([^/]+)\//.exec(path);
+  return m?.[1] ?? null;
+}
+
+/** Notice for a SOLID/skill reference credited via an in-session Read, or null for a non-skill `.md`. */
+export function refCreditedNotice(path: string): string | null {
+  const skill = skillNameFromRefPath(path);
+  return skill ? complianceNotice("SOLID refs read", skill) : null;
+}
+
+/** Notice for the APEX freshness gate (explore+research) currently satisfied. */
+export function evidenceFreshNotice(): string {
+  return complianceNotice("evidence fresh", "explore+research");
+}
+
+/** Notice mirroring the existing sniper-required additionalContext reminder. */
+export function sniperRequiredNotice(fileName: string): string {
+  return requirementNotice("sniper required", fileName);
+}
+
+/**
+ * The one `✓ SOLID refs read (<skill>)` notice to show for this PostToolUse
+ * call, or null. Scans the activities `activityFor` recorded from this event
+ * for a skill-ref Read, deduped per (session, path) against the same burst
+ * window as the sniper reminder — the ~11 sibling-plugin fan-out for one real
+ * Read must never repeat it (lesson 2026-07-05 15:21).
+ * @param activities - This event's recorded activities (only `ref` entries matter).
+ * @param sessionId - Current session id (dedup scope).
+ * @param now - Event clock.
+ * @param dir - State-dir override for the dedup sidecar (tests MUST pass an
+ *   isolated dir; production passes the per-project state dir).
+ */
+export function refCreditNoticeFor(
+  activities: ReadonlyArray<{ kind: string; path?: string }>,
+  sessionId: string,
+  now: number,
+  dir?: string,
+): string | null {
+  for (const a of activities) {
+    if (a.kind !== "ref" || !a.path) continue;
+    const notice = refCreditedNotice(a.path);
+    if (!notice) continue;
+    if (!onceExclusive(`ref-credited:${sessionId}:${a.path}`, BURST_DEDUP_MS, { now, dir })) continue;
+    return notice;
+  }
+  return null;
+}