@fusengine/harness 0.1.90 → 0.1.91

package/src/policy/skill-patterns/react.ts

@@ -0,0 +1,27 @@
+/**
+ * React skill-trigger patterns, ported verbatim from `react_skill_triggers.py`.
+ * Matched case-insensitively (source `re.IGNORECASE`).
+ */
+import { SHADCN } from "./shadcn";
+
+/** Map of React sub-skill name → triggering code patterns. */
+export const REACT_TRIGGERS: Readonly<Record<string, ReadonlyArray<string>>> = {
+  "react-19": ["\\buse\\b\\s*\\(", "useOptimistic\\b", "useActionState\\b",
+    "useEffectEvent\\b", "<Activity\\b", "from\\s+['\"]react['\"]"],
+  "react-tanstack-router": ["(createRouter|createRoute|createRootRoute)\\b",
+    "(useNavigate|useParams|useSearch|useLoaderData)\\b",
+    "from\\s+['\"]@tanstack/(react-router|router)",
+    "(routeTree|createFileRoute|createLazyFileRoute)\\b"],
+  "react-forms": ["(useForm|useAppForm|createFormHook|formOptions)\\b",
+    "(mergeForm|formApi|FieldApi|FormApi)\\b",
+    "form\\.(Field|Subscribe|handleSubmit)\\b",
+    "from\\s+['\"]@tanstack/(react-form|zod-form-adapter)"],
+  "react-state": ["(create|createStore)\\(\\s*\\(\\s*set", "from\\s+['\"]zustand(/\\w+)?\"",
+    "(useShallow|useStore|skipHydration)\\b", "(persist|devtools|immer)\\("],
+  "react-testing": ["(render|screen|fireEvent|waitFor)\\b",
+    "from\\s+['\"]@testing-library/react",
+    "(describe|it|expect|vi\\.|jest\\.)\\b", "from\\s+['\"]vitest"],
+  "react-shadcn": SHADCN,
+  "react-i18n": ["(useTranslation|Trans)\\b", "from\\s+['\"]react-i18next",
+    "\\bt\\(\\s*['\"]", "i18n\\.(language|changeLanguage)"],
+};

package/src/policy/skill-patterns/shadcn-subskills.ts

@@ -0,0 +1,33 @@
+/**
+ * shadcn/ui domain skill-trigger patterns, ported verbatim from
+ * `shadcn_skill_triggers.py` (the standalone shadcn-expert plugin, distinct
+ * from the `SHADCN` HTML-detection patterns in `./shadcn.ts` consumed by
+ * react/nextjs). 5 sub-skills. Matched case-insensitively (source `re.IGNORECASE`).
+ */
+
+/** Map of shadcn/ui sub-skill name → triggering code patterns. */
+export const SHADCN_TRIGGERS: Readonly<Record<string, ReadonlyArray<string>>> = {
+  "shadcn-detection": [
+    "components\\.json", "@radix-ui/", "@base-ui/",
+    "data-\\[state=", "data-\\[disabled\\]",
+  ],
+  "shadcn-components": [
+    "from\\s+['\"].*components/ui/",
+    "<(Button|Input|Select|Dialog|Card|Table|Tabs|Badge)\\b",
+    "(Popover|Tooltip|Sheet|Drawer|Command|Accordion)\\b",
+  ],
+  "shadcn-theming": [
+    "--(primary|secondary|muted|accent|destructive|foreground):",
+    "(cssVariables|themeConfig|globals\\.css)\\b",
+    ":root\\s*\\{|\\.dark\\s*\\{",
+  ],
+  "shadcn-registries": [
+    "mcp__shadcn__(search|view|get_add_command|list_items)",
+    "bunx.*shadcn@latest\\s+add\\b",
+    "(registries|@shadcn|@acme)\\b",
+  ],
+  "shadcn-migration": [
+    "(@radix-ui.*@base-ui|@base-ui.*@radix-ui)",
+    "(migrat|convert|switch).*(radix|base.?ui)",
+  ],
+};

package/src/policy/skill-patterns/shadcn.ts

@@ -0,0 +1,66 @@
+/**
+ * shadcn/ui HTML-to-component detection patterns, ported verbatim from the
+ * shared `shadcn_patterns.py` (FORM/OVERLAY/DATA/NAV/LAYOUT/FEEDBACK groups).
+ * 32 patterns total (3+6+8+5+5+5). Matched case-insensitively (source `re.IGNORECASE`).
+ */
+
+/** Forms: Button, Input, Textarea, Select, Checkbox, Radio, Switch, etc. */
+const FORM: ReadonlyArray<string> = [
+  "<(button|input|select|textarea|label|option|optgroup)\\b",
+  "type=\"(checkbox|radio|range|file)\"",
+  "<input[^>]*maxLength=\"[1-2]\"",
+];
+
+/** Overlay: Dialog, AlertDialog, Sheet, Popover, Tooltip, ContextMenu, etc. */
+const OVERLAY: ReadonlyArray<string> = [
+  "<dialog\\b",
+  "role=\"(dialog|alertdialog)\"",
+  "(aria-haspopup|aria-expanded|aria-pressed)=\"",
+  "(onContextMenu|onMouseEnter.*onMouseLeave)\\b",
+  "\\b(confirm|window\\.confirm)\\(",
+  "title=\"[^\"]{2,}\"",
+];
+
+/** Data: Table, Card, Badge, Avatar, Calendar, Chart, Carousel, Pagination. */
+const DATA: ReadonlyArray<string> = [
+  "<(table|thead|tbody|tfoot|th|td|tr|caption|colgroup)\\b",
+  "<(article|section)\\b[^>]*className",
+  "rounded-full[^>]*className|className[^>]*rounded-full",
+  "<img\\b[^>]*rounded",
+  "(new Date|\\.toLocaleDateString|date-fns|dayjs)\\b",
+  "(recharts|chart\\.js|<svg[^>]*viewBox)",
+  "(scroll-snap|embla-carousel|useEmbla)\\b",
+  "(page=|currentPage|totalPages|pageSize)\\b",
+];
+
+/** Navigation: Breadcrumb, NavigationMenu, Menubar, Sidebar, Tabs. */
+const NAV: ReadonlyArray<string> = [
+  "<(nav|aside)\\b",
+  "<(menu|menuitem)\\b",
+  "role=\"(menubar|menu|menuitem|tablist|tab|tabpanel)\"",
+  "aria-label=\"(breadcrumb|navigation|sidebar)\"",
+  "aria-current=\"(page|step)\"",
+];
+
+/** Layout: Accordion, Collapsible, Separator, ScrollArea, AspectRatio. */
+const LAYOUT: ReadonlyArray<string> = [
+  "<(hr|details|summary)\\b",
+  "role=\"separator\"",
+  "overflow-(auto|scroll|y-auto|x-auto)",
+  "(aspect-ratio|aspect-video|aspect-square)\\b",
+  "(resize|cursor-(col|row)-resize)\\b",
+];
+
+/** Feedback: Alert, Toast, Progress, Skeleton, Spinner. */
+const FEEDBACK: ReadonlyArray<string> = [
+  "role=\"(alert|status|progressbar)\"",
+  "aria-live=\"(polite|assertive)\"",
+  "<progress\\b",
+  "(animate-pulse|animate-spin)\\b",
+  "(sonner|react-hot-toast|\\.toast\\()\\b",
+];
+
+/** All 32 shadcn detection patterns combined. */
+export const SHADCN: ReadonlyArray<string> = [
+  ...FORM, ...OVERLAY, ...DATA, ...NAV, ...LAYOUT, ...FEEDBACK,
+];

package/src/policy/skill-patterns/swift.ts

@@ -0,0 +1,30 @@
+/**
+ * Swift / Apple skill-trigger patterns, ported verbatim from
+ * `swift_skill_triggers.py`. 9 skills.
+ *
+ * NOTE: Swift uses case-SENSITIVE matching (source `re.search` WITHOUT
+ * `re.IGNORECASE`). The framework name is registered in
+ * `CASE_SENSITIVE_FRAMEWORKS` so the gate compiles these without the `i` flag.
+ */
+
+/** Map of Swift sub-skill name → triggering code patterns (case-sensitive). */
+export const SWIFT_TRIGGERS: Readonly<Record<string, ReadonlyArray<string>>> = {
+  "swiftui-core": ["\\bstruct\\s+\\w+\\s*:\\s*View\\b", "@State\\b", "@Binding\\b",
+    "@Observable\\b", "@Environment\\b", "NavigationStack\\b",
+    "\\.sheet\\b", "\\.toolbar\\b", "\\.task\\b"],
+  "swift-core": ["\\bactor\\b", "\\basync\\s+(let|func|throws)\\b",
+    "\\bawait\\b", "Task\\s*\\{", "TaskGroup\\b", "Sendable\\b", "@MainActor\\b"],
+  "ios": ["UIKit|UIViewController|UIView\\b", "UIApplication\\b",
+    "\\.simulatorId\\b", "import\\s+UIKit\\b"],
+  "macos": ["AppKit|NSViewController|NSWindow\\b", "NSApplication\\b",
+    "\\.menuBar\\b", "import\\s+AppKit\\b"],
+  "watchos": ["WatchKit|WKInterface|WKExtension\\b", "HealthKit|HKWorkout\\b",
+    "WatchConnectivity\\b"],
+  "visionos": ["RealityKit|RealityView|ImmersiveSpace\\b",
+    "\\.volumeBaseplateVisibility\\b", "SpatialTapGesture\\b"],
+  "ipados": ["UISplitViewController|UIKeyCommand\\b", "\\.horizontalSizeClass\\b",
+    "pencilInteraction\\b"],
+  "tvos": ["TVUIKit|focusable\\b", "\\.focusSection\\b", "TVMonogram\\b"],
+  "build-distribution": ["TestFlight|AppStore\\b", "\\.entitlements\\b",
+    "codesign|notarize|archive\\b"],
+};

package/src/policy/skill-patterns/tailwind.ts

@@ -0,0 +1,40 @@
+/**
+ * Tailwind CSS skill-trigger patterns, ported verbatim from
+ * `tailwind_skill_triggers.py`. 12 skills.
+ *
+ * NOTE: Tailwind uses case-SENSITIVE matching (source `re.search` WITHOUT
+ * `re.IGNORECASE`). The framework name is registered in
+ * `CASE_SENSITIVE_FRAMEWORKS` so the gate compiles these without the `i` flag.
+ */
+
+/** Map of Tailwind sub-skill name → triggering utility-class patterns (case-sensitive). */
+export const TAILWIND_TRIGGERS: Readonly<Record<string, ReadonlyArray<string>>> = {
+  "tailwindcss-v4": ["@theme\\b", "@source\\b", "@utility\\b", "@variant\\b",
+    "@import\\s+['\"]tailwindcss", "@config\\b"],
+  "tailwindcss-layout": ["\\b(flex|grid|inline-flex|inline-grid)\\b",
+    "(justify|items|place)-(start|end|center|between)",
+    "(grid-cols|grid-rows|col-span|row-span)-",
+    "(absolute|relative|fixed|sticky)\\b"],
+  "tailwindcss-typography": ["(font-sans|font-serif|font-mono|font-bold|font-semibold)\\b",
+    "(text-xs|text-sm|text-base|text-lg|text-xl|text-2xl)\\b",
+    "(tracking-|leading-|line-clamp-)\\b"],
+  "tailwindcss-backgrounds": ["(bg-gradient|bg-linear|bg-radial|bg-conic)\\b",
+    "(from-|via-|to-)\\w+", "bg-\\[url\\b"],
+  "tailwindcss-borders": ["(rounded-|border-|ring-|outline-|divide-)\\w+",
+    "(border-dashed|border-dotted|border-double)\\b"],
+  "tailwindcss-effects": ["(shadow-|opacity-|blur-|brightness-|contrast-)\\w+",
+    "(backdrop-blur|backdrop-brightness|backdrop-contrast)\\b",
+    "(inset-shadow-|mask-)\\w+"],
+  "tailwindcss-transforms": ["(scale-|rotate-|translate-|skew-)\\w+",
+    "(transition-|duration-|ease-|delay-)\\w+",
+    "(animate-spin|animate-pulse|animate-bounce)\\b"],
+  "tailwindcss-responsive": ["(sm:|md:|lg:|xl:|2xl:)\\w+",
+    "(@container|container-type)\\b", "(min-\\[|max-\\[)\\d+"],
+  "tailwindcss-spacing": ["\\b[pm][xytblr]?-\\d+\\b", "(space-x-|space-y-|gap-)\\d+"],
+  "tailwindcss-sizing": ["\\b[wh]-(full|screen|auto|min|max|fit)\\b",
+    "(min-w-|max-w-|min-h-|max-h-)\\w+", "(aspect-video|aspect-square)\\b"],
+  "tailwindcss-interactivity": ["(cursor-|select-|pointer-events-|scroll-)\\w+",
+    "(snap-|overscroll-|touch-)\\w+"],
+  "tailwindcss-custom-styles": ["@apply\\b", "@utility\\s+\\w+",
+    "@variant\\s+\\w+", "theme\\(\\s*['\"]"],
+};

package/src/policy/skill-source.ts

@@ -0,0 +1,52 @@
+/**
+ * Framework -> SKILL.md doc source for the APEX Check-1 non-routed deny —
+ * parity with the Python plugin's enforce-helpers.ts `getSkillSource()`
+ * (10-entry map, fallback "mcp__context7__query-docs"). The map is ported
+ * faithfully as skill NAMES only: disk paths are resolved DYNAMICALLY via
+ * {@link resolveSkillPath} (proprietary rule — no static path table; installed
+ * plugin dir names differ from upstream's `react-expert/...`, and a hardcoded
+ * table drifts from what is actually installed).
+ */
+import { resolveSkillPath } from "./skill-path";
+
+/**
+ * Fallback doc source when no SKILL.md can be promised: the consigne to query
+ * context7 (a TOOL name, not a path) — parity enforce-helpers.ts:51.
+ */
+export const CONTEXT7_SOURCE = "mcp__context7__query-docs";
+
+/**
+ * Framework -> sub-skill dir name, faithful to the Python
+ * `getSkillSource` map (enforce-helpers.ts:39-50, all 10 entries).
+ */
+const SKILL_NAMES: Record<string, string> = {
+  react: "react-19",
+  nextjs: "nextjs-16",
+  swift: "swiftui-components",
+  laravel: "laravel-eloquent",
+  tailwind: "tailwindcss-v4",
+  generic: "solid-generic",
+  java: "solid-java",
+  go: "solid-go",
+  ruby: "solid-ruby",
+  rust: "solid-rust",
+};
+
+/**
+ * The doc source a Check-1 deny may promise for `framework` (parity
+ * `getSkillSource`): the REAL installed SKILL.md absolute path when it exists
+ * on disk, else {@link CONTEXT7_SOURCE}. `resolveSkillPath` returns a
+ * `/SKILL.md`-suffixed path ONLY on an `existsSync` hit; its
+ * `${PLUGINS_DIR}/<name>` not-found fallback (no marketplace installed, or a
+ * mapped skill absent on disk — e.g. upstream's `swiftui-components`) is
+ * converted to the context7 consigne here, because a deny must never promise
+ * a nonexistent path (every option a deny offers must actually unblock).
+ * @param framework - Detected framework (the `detectFramework()` domain).
+ * @param pluginsDirOverride - Marketplace plugins dir override (tests).
+ */
+export function getSkillSource(framework: string, pluginsDirOverride?: string): string {
+  const name = SKILL_NAMES[framework];
+  if (!name) return CONTEXT7_SOURCE;
+  const path = resolveSkillPath(name, pluginsDirOverride);
+  return path.endsWith("/SKILL.md") ? path : CONTEXT7_SOURCE;
+}

package/src/policy/skill-trigger-patterns.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-framework code-pattern → required sub-skill data, ported verbatim from the
+ * fusengine `*_skill_triggers.py` + `*_patterns.py`
+ * (react/nextjs/laravel/swift) and the shared `shadcn_patterns.py`.
+ *
+ * Pattern groups live in `./skill-patterns/*`. Most frameworks match
+ * case-insensitively (source `re.IGNORECASE`); `swift` matches case-SENSITIVELY
+ * (source `re.search` without the flag) — see {@link CASE_SENSITIVE_FRAMEWORKS}.
+ */
+import { REACT_TRIGGERS } from "./skill-patterns/react";
+import { NEXTJS_TRIGGERS } from "./skill-patterns/nextjs";
+import { LARAVEL_TRIGGERS } from "./skill-patterns/laravel";
+import { SWIFT_TRIGGERS } from "./skill-patterns/swift";
+import { TAILWIND_TRIGGERS } from "./skill-patterns/tailwind";
+import { SHADCN_TRIGGERS } from "./skill-patterns/shadcn-subskills";
+
+/**
+ * Frameworks whose Python source omits `re.IGNORECASE`, so their regexes must
+ * be compiled WITHOUT the `i` flag to stay faithful.
+ */
+export const CASE_SENSITIVE_FRAMEWORKS: ReadonlySet<string> = new Set(["swift", "tailwind"]);
+
+/** Map of required sub-skill name → triggering code patterns, keyed by framework. */
+export const SKILL_TRIGGERS: Readonly<
+  Record<string, Readonly<Record<string, ReadonlyArray<string>>>>
+> = {
+  react: REACT_TRIGGERS,
+  nextjs: NEXTJS_TRIGGERS,
+  laravel: LARAVEL_TRIGGERS,
+  swift: SWIFT_TRIGGERS,
+  tailwind: TAILWIND_TRIGGERS,
+  shadcn: SHADCN_TRIGGERS,
+};

package/src/policy/skill-triggers.ts

@@ -0,0 +1,108 @@
+/**
+ * Content → sub-skill consultation gate, ported from the fusengine Python
+ * `*_skill_triggers.py` (react/nextjs/laravel) + `check_skill_common.py`
+ * `specific_skill_consulted`. Maps written-code API patterns to a required
+ * sub-skill and blocks when its `skills/<name>/` path was not read in-session.
+ */
+import type { Prompt } from "../prompt/types";
+import { CASE_SENSITIVE_FRAMEWORKS, SKILL_TRIGGERS } from "./skill-trigger-patterns";
+import { isShadcnProject } from "./shadcn-project";
+import { resolveSkillPath } from "./skill-path";
+
+export { SKILL_TRIGGERS } from "./skill-trigger-patterns";
+
+/**
+ * Detect which sub-skills the written `content` requires for a `framework`.
+ * Faithful to the Python `detect_required_skills`: first matching pattern per
+ * skill wins. Most frameworks match case-insensitively (source `re.IGNORECASE`);
+ * `swift` matches case-sensitively (see {@link CASE_SENSITIVE_FRAMEWORKS}).
+ * @param framework - "react" | "nextjs" | "laravel" | "swift".
+ * @param content - the code being written.
+ * @returns required sub-skill names (empty when framework unknown / no match).
+ */
+export function detectRequiredSkills(framework: string, content: string): string[] {
+  const groups = SKILL_TRIGGERS[framework];
+  if (!groups) return [];
+  const flags = CASE_SENSITIVE_FRAMEWORKS.has(framework) ? "" : "i";
+  const required: string[] = [];
+  for (const [skill, patterns] of Object.entries(groups)) {
+    if (patterns.some((p) => new RegExp(p, flags).test(content))) required.push(skill);
+  }
+  return required;
+}
+
+/**
+ * `.tsx`/`.jsx` — the only extensions `check-tailwind-skill.py` actually gates
+ * (its regex also lists `.css`/`.html`, but both hit an early return right
+ * after, in the Python source).
+ */
+const TAILWIND_FILE = /\.(tsx|jsx)$/;
+
+/** Ported verbatim from `check-tailwind-skill.py`'s `TW_PATTERN`. */
+const TAILWIND_CONTENT = /(className|class).*['"].*\b(flex|grid|p-|m-|w-|h-|text-|bg-|border-)/;
+
+/**
+ * True when `filePath`/`content` match the Python Tailwind gate's trigger
+ * condition. React/Next.js components embed Tailwind utility classes in
+ * `className` — this check fires IN ADDITION TO the primary framework gate,
+ * never instead of it: {@link detectFramework} keeps returning "react"/
+ * "nextjs" for these files (framework SOLID rules stay correct).
+ */
+export function usesTailwindUtilities(filePath: string, content: string): boolean {
+  return TAILWIND_FILE.test(filePath) && TAILWIND_CONTENT.test(content);
+}
+
+/**
+ * Block when a required sub-skill's `skills/<name>/` path is absent from
+ * `refsRead`. Mirrors `specific_skill_consulted`, which confirms a skill was
+ * read by checking the tracking file contains `skills/<name>/`.
+ * @param framework - "react" | "nextjs" | "laravel".
+ * @param content - the code being written.
+ * @param refsRead - in-session read reference paths.
+ * @param forcedSkill - a skill the detected modular architecture forces (optional).
+ * @param cwd - project root; when set and not a shadcn project, `*-shadcn`
+ *   requirements are skipped (ports the Python `is_shadcn_project` filter).
+ * @param filePath - the file being written; when it's a `.tsx`/`.jsx` file
+ *   with Tailwind utility classes in `className`, the "tailwind" domain
+ *   skills are merged in alongside `framework`'s own (ports the separate
+ *   `check-tailwind-skill.py` gate, independent of react/nextjs).
+ * @returns a `block` Prompt naming the missing sub-skills, or `null` when satisfied.
+ */
+export function skillTriggerGate(
+  framework: string,
+  content: string,
+  refsRead: readonly string[],
+  forcedSkill?: string | null,
+  cwd?: string,
+  filePath?: string,
+): Prompt | null {
+  // Phase 1.5 parity (check-laravel-skill.py:57-62): a forced FuseCore skill is
+  // denied on its own, BEFORE domain sub-skills — never merged into their message.
+  if (forcedSkill === "fusecore" && !refsRead.some((r) => r.includes("skills/fusecore/"))) {
+    return {
+      kind: "block",
+      title: "FuseCore skill not consulted",
+      reason:
+        "BLOCKED: FuseCore project detected. Read the FuseCore skill before writing code in FuseCore modules.",
+      actions: [`Read ${resolveSkillPath("fusecore")}`],
+    };
+  }
+  let required = detectRequiredSkills(framework, content);
+  if (framework !== "tailwind" && filePath && usesTailwindUtilities(filePath, content)) {
+    required = [...required, ...detectRequiredSkills("tailwind", content)];
+  }
+  if (forcedSkill && !required.includes(forcedSkill)) required.push(forcedSkill);
+  if (cwd && !isShadcnProject(cwd)) required = required.filter((s) => !s.endsWith("-shadcn"));
+  const missing = required.filter(
+    (s) => !refsRead.some((r) => r.includes(`skills/${s}/`)),
+  );
+  if (missing.length === 0) return null;
+  return {
+    kind: "block",
+    title: "Required sub-skill not consulted",
+    reason:
+      `${framework}: code uses APIs covered by ${missing.join(", ")} ` +
+      "but its skill reference was not read this session.",
+    actions: missing.map((s) => `Read ${resolveSkillPath(s)}`),
+  };
+}

package/src/policy/tailwind-skill-gate.ts

@@ -0,0 +1,63 @@
+/**
+ * @module tailwind-skill-gate
+ * Standalone Tailwind base-skill gate — ports Phase 1 of the tailwindcss plugin's
+ * `check-tailwind-skill.py`. A `.tsx`/`.jsx` write carrying Tailwind utility
+ * classes must have consulted a base Tailwind skill (`tailwindcss-v4` or
+ * `tailwindcss-utilities`) this session. Phase 2 (domain sub-skills) and Phase 3
+ * (MCP research) are already enforced by {@link skillTriggerGate} (via
+ * `usesTailwindUtilities`) and `docConsultedGate`, so this gate covers only the
+ * base-skill gap, independent of the detected framework.
+ * @packageDocumentation
+ */
+import type { Prompt } from "../prompt/types";
+import { usesTailwindUtilities } from "./skill-triggers";
+import { resolveSkillPath } from "./skill-path";
+
+/** Vendored/build paths exempt (parity check-tailwind-skill.py `/(node_modules|dist|build)/`). */
+const TW_EXCLUDE_RE = /(^|\/)(node_modules|dist|build)\//;
+/** A read reference proving a base Tailwind skill was consulted (Phase 1). */
+const TW_BASE_SKILL_RE = /skills\/(tailwindcss-v4|tailwindcss-utilities)\//;
+
+/**
+ * True when this Write/Edit is a `.tsx`/`.jsx` file carrying Tailwind utility
+ * classes, outside vendored dirs — the trigger condition of Phase 1.
+ * @param tool - the tool name.
+ * @param filePath - the file being written.
+ * @param content - the written content.
+ */
+export function isTailwindWrite(tool: string, filePath: string, content: string): boolean {
+  if (tool !== "Write" && tool !== "Edit") return false;
+  if (TW_EXCLUDE_RE.test(filePath)) return false;
+  return usesTailwindUtilities(filePath, content);
+}
+
+/** True when `tailwindcss-v4` or `tailwindcss-utilities` was read this session (Phase 1 base skill). */
+export function tailwindBaseSkillRead(refsRead: readonly string[]): boolean {
+  return refsRead.some((p) => TW_BASE_SKILL_RE.test(p));
+}
+
+/**
+ * Gate a Tailwind-scoped write: block until a base Tailwind skill is read
+ * (parity check-tailwind-skill.py Phase 1). Returns `null` when out of scope
+ * or already satisfied.
+ * @param tool - the tool name.
+ * @param filePath - the file being written.
+ * @param content - the written content.
+ * @param refsRead - in-session read reference paths.
+ */
+export function tailwindSkillGate(
+  tool: string,
+  filePath: string,
+  content: string,
+  refsRead: readonly string[],
+): Prompt | null {
+  if (!isTailwindWrite(tool, filePath, content)) return null;
+  if (tailwindBaseSkillRead(refsRead)) return null;
+  return {
+    kind: "block",
+    title: "Tailwind CSS skill",
+    reason:
+      "BLOCKED: Tailwind skill not consulted. Read tailwindcss-v4/SKILL.md or tailwindcss-utilities/SKILL.md, or use mcp__context7__query-docs (topic: tailwindcss), then retry.",
+    actions: [`Read ${resolveSkillPath("tailwindcss-v4")} or ${resolveSkillPath("tailwindcss-utilities")}`],
+  };
+}

package/src/policy/trivial-edits.ts

@@ -0,0 +1,52 @@
+import type { Prompt } from "../prompt/types";
+
+/**
+ * Pre-filters of the ported enforce-apex-phases.ts hook, in Python order
+ * (lines 48-65): protected-path guard first, then the dependency/build-dir
+ * skip, then the trivial-edit fast path. The trivial COUNTER itself lives in
+ * the SessionTrack (`trivialEdits`, see recordTrivialEdit/trivialCount) — no
+ * separate state file.
+ */
+
+/** Hook-managed state paths — Write/Edit always denied (parity enforce-apex-phases.ts PROTECTED_PATHS). */
+export const PROTECTED_PATHS: RegExp = /\.claude\/(plugins\/(marketplaces|cache)|logs\/00-apex|fusengine-cache\/skill-tracking)/;
+
+/** Dependency/build dirs the APEX gates skip entirely (parity enforce-apex-phases.ts SKIP_DIRS). */
+export const SKIP_DIRS: RegExp = /(node_modules|vendor|dist|build|\.next|DerivedData)/;
+
+/**
+ * Absolute deny on Write/Edit of hook-managed state paths, with the Python
+ * wording byte-for-byte. Runs BEFORE the code-ext/skip-dirs filters (parity
+ * enforce-apex-phases.ts:48-54), so non-code files under the protected roots
+ * are covered too.
+ * @param tool - The harness tool name (only Write/Edit are policed).
+ * @param filePath - Target path of the edit (or undefined).
+ * @returns A blocking prompt, or null to fall through.
+ */
+export function protectedPathGate(tool: string, filePath: string | undefined): Prompt | null {
+  if ((tool !== "Write" && tool !== "Edit") || !filePath || !PROTECTED_PATHS.test(filePath)) return null;
+  return {
+    kind: "block",
+    title: "APEX Hook Guard: protected path",
+    reason:
+      "[APEX Hook Guard] Write blocked — this path is managed automatically by APEX hooks. Manual edits are forbidden and would corrupt tracked state.",
+  };
+}
+
+/** An Edit whose new_string spans fewer lines than this is "trivial" (parity: < 5). */
+export const TRIVIAL_MAX_LINES = 5;
+
+/**
+ * True when this tool-use qualifies for the trivial fast path (parity
+ * enforce-apex-phases.ts:58-65): only an Edit (a Write always creates or
+ * replaces a file wholesale), NEVER `replace_all`, and a new_string under
+ * {@link TRIVIAL_MAX_LINES} lines. Absent content is NOT trivial (fail closed
+ * — the full gates run).
+ * @param tool - The harness tool name.
+ * @param content - The Edit's new_string (adapter-normalized).
+ * @param isReplaceAll - The Edit's replace_all flag.
+ */
+export function isTrivialEdit(tool: string, content: string | undefined, isReplaceAll?: boolean): boolean {
+  if (tool !== "Edit" || isReplaceAll === true || content === undefined) return false;
+  return content.split("\n").length < TRIVIAL_MAX_LINES;
+}

package/src/policy/verbosity.ts

@@ -0,0 +1,39 @@
+/** Exa search tool — result count force-capped + token budget capped. */
+const EXA_SEARCH = /exa__web_search|exa_web_search/i;
+/** Exa code-context tool — token budget capped; `numResults` capped only when
+ * already present (parity: limit-mcp-verbosity.py never injects it). */
+const EXA_CODE = /exa__get_code_context|exa_get_code_context/i;
+/** Context7 doc tool whose token budget is capped. */
+const CONTEXT7_TOOLS = /context7__query-docs|context7_query-docs|query-docs/i;
+
+/** Max results an exa MCP call may request. */
+export const MAX_EXA_RESULTS = 3;
+/** Max token budget for exa `tokensNum` / context7 `tokens`. */
+export const MAX_TOKENS = 2000;
+
+/**
+ * Cap an MCP call's verbosity — exa `numResults` ≤ 3 (+ `tokensNum` ≤ 2000),
+ * Context7 `tokens` ≤ 2000. Returns the capped input (a mutation for the harness
+ * to apply) when a change is needed, else null.
+ */
+export function capVerbosity(tool: string, input: Record<string, unknown>): Record<string, unknown> | null {
+  const out: Record<string, unknown> = { ...input };
+  let changed = false;
+  const cap = (key: string, max: number, force: boolean): void => {
+    const v = out[key];
+    if ((typeof v === "number" && v > max) || (force && typeof v !== "number")) {
+      out[key] = max;
+      changed = true;
+    }
+  };
+  if (EXA_SEARCH.test(tool)) {
+    cap("numResults", MAX_EXA_RESULTS, true);
+    cap("tokensNum", MAX_TOKENS, false);
+  } else if (EXA_CODE.test(tool)) {
+    cap("numResults", MAX_EXA_RESULTS, false);
+    cap("tokensNum", MAX_TOKENS, false);
+  } else if (CONTEXT7_TOOLS.test(tool)) {
+    cap("tokens", MAX_TOKENS, false);
+  }
+  return changed ? out : null;
+}

package/src/prompt/index.ts

@@ -0,0 +1 @@
+export * from "./types";

package/src/prompt/types.ts

@@ -0,0 +1,36 @@
+/** How a policy outcome should surface in a harness. */
+export type PromptKind = "ask" | "block" | "inform";
+
+/**
+ * Portable, harness-agnostic representation of a policy outcome as a prompt.
+ * Adapters render this into their harness's native shape (a Claude
+ * `permissionDecision`, a Cursor block, a CLI exit + message, ...).
+ */
+export interface Prompt {
+  kind: PromptKind;
+  /** Stable policy identifier for confirmation diagnostics. */
+  ruleId?: string;
+  /** Short title, e.g. "SOLID file-size limit". */
+  title: string;
+  /** Why this fired. */
+  reason: string;
+  /** Concrete next actions to proceed. */
+  actions?: string[];
+  /**
+   * User-facing notice (Python `hook_output.allow_pass`/`post_pass` parity):
+   * shown to the HUMAN — Claude Code's `systemMessage` — never to the agent,
+   * unlike `reason`/additionalContext. Excluded from {@link formatPrompt}.
+   */
+  userMessage?: string;
+}
+
+/** Render a {@link Prompt} as a consistent, agent-readable memo block. */
+export function formatPrompt(p: Prompt): string {
+  const tag = p.kind === "block" ? "BLOCKED" : p.kind === "ask" ? "CONFIRM" : "NOTE";
+  const lines = [`[${tag}] ${p.title}`, p.reason];
+  if (p.actions?.length) {
+    lines.push("Next:");
+    p.actions.forEach((a, i) => lines.push(`  ${i + 1}. ${a}`));
+  }
+  return lines.join("\n");
+}