@fusengine/harness 0.1.90 → 0.1.92

package/src/policy/never-approval.ts

@@ -0,0 +1,95 @@
+import type { Prompt } from "../prompt/types";
+import { RALPH_SAFE } from "./patterns";
+
+/**
+ * Shell metacharacters that turn a "simple" command into a chained/composite
+ * one: `&&`, `||`, `;`, `|`, a lone background `&` (POSIX control operator —
+ * `cmd1 & cmd2` runs BOTH; `&(?!>)` excludes bash's `&>`/`&>>` redirects, which
+ * cannot introduce a second command), a backtick, `$(`, or a literal newline.
+ * Bounded alternation, no nested quantifiers — no ReDoS. Quote-unaware by
+ * design: a quoted `"R&D"` gates as ask (fail-closed).
+ */
+const CHAIN_RE = /&&|\|\||[;|`]|&(?!>)|\$\(|\n/;
+
+/**
+ * True when `cmd` has no chaining operator. evaluate.ts's neverApproval
+ * exemption must NEVER fire on a composite command — `git commit -m x &&
+ * git push --force` would otherwise slip a blocked op past the RALPH_SAFE
+ * subset check, since that check is a `startsWith` on the leading verb only.
+ */
+export function isSingleCommand(cmd: string): boolean {
+  return !CHAIN_RE.test(cmd);
+}
+
+/**
+ * Commands exempt from `ask` under Codex `approval_policy=never` — a superset
+ * of {@link RALPH_SAFE} plus `git push`. Kept as its OWN list, never merged
+ * into RALPH_SAFE: the RALPH_MODE path (evaluate.ts's `ralphSafe`) has no
+ * equivalent to {@link isSafePushForm}, only the shared GIT_BLOCKED +
+ * isSingleCommand guards — adding push to RALPH_SAFE would auto-allow
+ * `git push origin --delete branch` under RALPH_MODE, since GIT_BLOCKED only
+ * covers force-push, not remote deletion. Only the neverApproval path in
+ * evaluate.ts consults NEVER_SAFE, and it always pairs it with
+ * isSafePushForm for any push entry.
+ */
+export const NEVER_SAFE: ReadonlyArray<string> = [...RALPH_SAFE, "git push"];
+
+/**
+ * `--delete`/`-d` (git-push(1): "deleted from the remote repository", no
+ * `--force` needed), `--mirror` (force-updates AND deletes remote-only refs),
+ * `--prune` (removes remote refs with no local counterpart) — all delete or
+ * force-overwrite a remote ref without going through the `--force` flag
+ * GIT_BLOCKED already checks. Boundary-anchored like patterns.ts's FORCE_FLAG
+ * so `-d` never matches inside a longer token (e.g. a branch name).
+ */
+const PUSH_DESTRUCTIVE_FLAG = /\s(?:--delete|--mirror|--prune|-d)(?:\s|=|$)/;
+/** A refspec colon (e.g. `git push origin :branch`) deletes the remote ref — the legacy form of `--delete` (git-push(1): "prefixing all refs with a colon"). */
+const REFSPEC_COLON = /\s:\S/;
+/**
+ * A leading `+` on a pushed refspec force-updates the remote ref on a
+ * non-fast-forward — git-push(1): "The `+` is optional and does the same thing
+ * as `--force`". It carries NO `--force`/`-f` flag, so GIT_BLOCKED's FORCE_FLAG
+ * misses it; this guard is the `--force` twin. The `\s` anchor makes `+` open
+ * its token (`+main`, `+src:dst`), never a mid-token `feature+x` ref name.
+ */
+const REFSPEC_FORCE = /\s\+\S/;
+
+/**
+ * True unless `cmd` is a `git push` carrying an irreversible remote-mutation
+ * form GIT_BLOCKED doesn't already cover: `--delete`/`-d`/`--mirror`/`--prune`,
+ * a `:refspec` remote-delete, or a `+refspec` force-update (the `--force` twin
+ * FORCE_FLAG misses). Plain `--force`/`-f` stays GIT_BLOCKED's job, checked
+ * upstream in evaluate.ts. Non-push commands always pass — this guard exists
+ * solely to narrow the `git push` entry of {@link NEVER_SAFE}.
+ */
+export function isSafePushForm(cmd: string): boolean {
+  if (!cmd.startsWith("git push")) return true;
+  return !PUSH_DESTRUCTIVE_FLAG.test(cmd) && !REFSPEC_COLON.test(cmd) && !REFSPEC_FORCE.test(cmd);
+}
+
+/** Next steps offered on the auto-approve notice — the only channel left once `ask` is unavailable. */
+const ACTIONS: readonly string[] = [
+  "Set approval_policy=on-request for interactive confirmation",
+  "Or set RALPH_MODE=1 to auto-approve silently (no notice)",
+  "Or run the command manually outside the agent loop",
+];
+
+/**
+ * Builds the auto-approve `inform` prompt for a command evaluate.ts has
+ * already proven safe (RALPH_SAFE subset, not GIT_BLOCKED, not chained —
+ * see {@link isSingleCommand}). Pure formatting only; the 3-condition
+ * decision itself lives in evaluate.ts, where the anti-chaining guarantee
+ * must stay visible and auditable.
+ * @param cmd - The already-vetted command.
+ */
+export function buildNeverApprovalPrompt(cmd: string): Prompt {
+  const trimmed = cmd.trim();
+  const reason = `Auto-approved "${trimmed}" under approval_policy=never.`;
+  return {
+    kind: "inform",
+    title: "Auto-approved (approval_policy=never)",
+    reason,
+    actions: [...ACTIONS],
+    userMessage: `[fuse-harness] Auto-approved "${trimmed}" — approval_policy=never has no ask channel. Destructive git commands still deny. Set approval_policy=on-request, or RALPH_MODE=1, to keep asking.`,
+  };
+}

package/src/policy/patterns.ts

@@ -0,0 +1,80 @@
+/**
+ * Guard pattern data, ported verbatim from the fusengine git/install guards.
+ * Note (faithful): `--force` also matches `--force-with-lease` — preserved
+ * from the source guard, now as an explicit alternation instead of an
+ * accidental substring match (see {@link GIT_BLOCKED}).
+ */
+
+/**
+ * Token-boundary suffix for a destructive flag: only whitespace, `=`, or
+ * end-of-string may follow — never another word character. Without this, a
+ * flag regex matches as a plain substring of any argument (a branch/file name
+ * like `fix/guard-false-positives` contains `-f`, `feature-force-refactor`
+ * contains `-force`), turning a rename into a false-positive hard block
+ * (proven live: `git push -u origin fix/api-keys-fossil` denied as
+ * "Destructive git command"). No leading-boundary group is needed on the flag
+ * side — every pattern below prefixes the flag with a literal `\s`, and the
+ * flag can never be the first character of the whole command since a git
+ * verb (`git push`, `git reset`, ...) always precedes it.
+ */
+const FLAG_END = "(?:\\s|=|$)";
+/** `-f` / `--force` / `--force-with-lease`, boundary-anchored on both flag forms. */
+const FORCE_FLAG = `\\s(?:--force(?:-with-lease)?|-f)${FLAG_END}`;
+/**
+ * `git clean` short-flag cluster containing both `f` and `d` in any order
+ * (`-fd`, `-df`, `-fdx`, `-fdX`, `-xfd`…): a MORE destructive superset than a
+ * bare `-fd` — must stay blocked, never downgrade to `git clean`'s GIT_ASK.
+ */
+const CLEAN_FD_FLAG = `\\s-(?=[a-zA-Z]*f)(?=[a-zA-Z]*d)[a-zA-Z]+${FLAG_END}`;
+
+/** Destructive git operations to block outright. */
+export const GIT_BLOCKED: ReadonlyArray<RegExp> = [
+  new RegExp(`git push.*${FORCE_FLAG}`),
+  new RegExp(`git reset.*\\s--hard${FLAG_END}`),
+  new RegExp(`git clean.*${CLEAN_FD_FLAG}`),
+  new RegExp(`git branch.*\\s-D${FLAG_END}`),
+  new RegExp(`git rebase.*${FORCE_FLAG}`),
+];
+
+/** Git operations that warrant a confirmation prompt. */
+export const GIT_ASK: ReadonlyArray<RegExp> = [
+  /git push/, /git checkout/, /git reset/, /git rebase/, /git merge/,
+  /git stash/, /git clean/, /git rm/, /git mv/, /git restore/,
+  /git revert/, /git cherry-pick/, /git commit/, /git add/, /git branch -d/,
+];
+
+/** System-level package installs (need confirmation). */
+export const SYSTEM_INSTALL: ReadonlyArray<RegExp> = [
+  /brew install/, /brew upgrade/, /brew cask/, /apt install/, /apt-get install/,
+  /dnf install/, /pacman -S/,
+];
+
+/** Project-level package installs. */
+export const PROJECT_INSTALL: ReadonlyArray<RegExp> = [
+  /npm install/, /npm i /, /yarn add/, /pnpm add/, /pip install/, /pip3 install/,
+  /composer require/, /bun add/, /bun install/, /cargo install/, /go install/,
+  /gem install/, /pipx install/,
+];
+
+/** True when `cmd` matches any pattern in `patterns`. */
+export function matchPatterns(cmd: string, patterns: ReadonlyArray<RegExp>): boolean {
+  return patterns.some((re) => re.test(cmd));
+}
+
+/** Git commands exempt from confirmation when Ralph mode is on (parity git-guard.py RALPH_SAFE). */
+export const RALPH_SAFE: ReadonlyArray<string> = [
+  "git add", "git commit", "git checkout -b", "git branch --show-current",
+  "git status", "git diff", "git log",
+];
+
+/**
+ * OPT-IN autonomous "Ralph" mode: OFF unless `RALPH_MODE` is `1`/`true`, read
+ * fresh on each call. Only the env var activates it — the Python source also
+ * auto-enabled on a `.claude/ralph/prd.json` file or a `feature/*` branch, but
+ * those silent activations are dropped here: a mode that removes git/install
+ * confirmations must never turn on implicitly (owner: default OFF, env opt-in).
+ */
+export function isRalphMode(): boolean {
+  const v = process.env.RALPH_MODE;
+  return v === "1" || v === "true";
+}

package/src/policy/seo/validate.ts

@@ -0,0 +1,51 @@
+/**
+ * SEO completeness checks — pure text in, missing-items out (no fs). Ports the
+ * `validate()` of `seo/hooks/validate-seo.ts` using regex instead of cheerio so
+ * the harness keeps zero runtime HTML-parser dependency (presence-only gate).
+ */
+
+/** Extensions the SEO hook validates (HTML-like rendered output). */
+const HTML_LIKE = /\.(html|astro|tsx|vue|blade\.php)$/;
+
+/** True when `path` is an HTML-like file the SEO hook should validate. */
+export function isHtmlLike(path: string): boolean {
+  return HTML_LIKE.test(path);
+}
+
+/** True when a `<tag …>…</tag>` carries non-empty inner text. */
+function hasNonEmptyTag(html: string, tag: string): boolean {
+  const m = new RegExp(`<${tag}[\\s>][\\s\\S]*?</${tag}>`, "i").exec(html);
+  return !!m && m[0].replace(/<[^>]*>/g, "").trim().length > 0;
+}
+
+/** True when a `<meta …>` whose `selAttr=selVal` has a non-empty `content`. */
+function hasMetaContent(html: string, selAttr: string, selVal: string): boolean {
+  const re = new RegExp(`<meta\\b[^>]*\\b${selAttr}\\s*=\\s*["']${selVal}["'][^>]*>`, "i");
+  const tag = re.exec(html)?.[0] ?? "";
+  const c = /\bcontent\s*=\s*["']([^"']*)["']/i.exec(tag)?.[1] ?? "";
+  return c.trim().length > 0;
+}
+
+/** True when a `<link rel="canonical">` carries a non-empty `href`. */
+function hasCanonical(html: string): boolean {
+  const tag = /<link\b[^>]*\brel\s*=\s*["']canonical["'][^>]*>/i.exec(html)?.[0] ?? "";
+  return (/\bhref\s*=\s*["']([^"']*)["']/i.exec(tag)?.[1] ?? "").trim().length > 0;
+}
+
+/**
+ * Report the SEO elements missing from HTML-like content (title, meta
+ * description, OG title/description/image, canonical, JSON-LD schema).
+ * @param html - The file content.
+ * @returns The missing element labels (empty when complete).
+ */
+export function missingSeoElements(html: string): string[] {
+  const missing: string[] = [];
+  if (!hasNonEmptyTag(html, "title")) missing.push("<title>");
+  if (!hasMetaContent(html, "name", "description")) missing.push("<meta name='description'>");
+  if (!hasMetaContent(html, "property", "og:title")) missing.push("og:title");
+  if (!hasMetaContent(html, "property", "og:description")) missing.push("og:description");
+  if (!hasMetaContent(html, "property", "og:image")) missing.push("og:image");
+  if (!hasCanonical(html)) missing.push("canonical");
+  if (!/<script\b[^>]*type\s*=\s*["']application\/ld\+json["']/i.test(html)) missing.push("JSON-LD schema");
+  return missing;
+}

package/src/policy/shadcn-project.ts

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Directories whose presence indicates shadcn/ui is installed. */
+const UI_DIRS: ReadonlyArray<string> = [
+  "src/components/ui",
+  "components/ui",
+  "src/modules/cores/shadcn/components/ui",
+];
+
+/**
+ * Whether `cwd` is a shadcn/ui project, ported from the shared Python
+ * `is_shadcn_project` (`shadcn_patterns.py`): true when a `components.json`
+ * file exists, or any known `components/ui` directory exists under the root.
+ * Used to skip `*-shadcn` sub-skill requirements when shadcn is not installed.
+ * @param cwd - project root directory to scan.
+ * @returns `true` when shadcn/ui is detected on disk.
+ */
+export function isShadcnProject(cwd: string): boolean {
+  if (existsSync(join(cwd, "components.json"))) return true;
+  return UI_DIRS.some((dir) => existsSync(join(cwd, dir)));
+}

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

@@ -0,0 +1,97 @@
+/**
+ * @module shadcn-skill-gate
+ * Standalone shadcn/ui skill gate, ported from the shadcn-expert plugin's
+ * `check-skill-loaded.py`. Distinct from the `*-shadcn` sub-skill entries
+ * consumed by react/nextjs (`./skill-patterns/shadcn.ts`, the HTML-detection
+ * patterns): this polices ANY Write/Edit in a shadcn-scoped path
+ * (components|ui|shadcn|components.json), independent of the detected
+ * `framework` — mirroring the plugin's own PreToolUse hook, which runs
+ * alongside (not instead of) the react/nextjs framework gate.
+ * @packageDocumentation
+ */
+import type { Prompt } from "../prompt/types";
+import type { AuthEntry } from "../freshness/doc-helpers";
+import { skillTriggerGate } from "./skill-triggers";
+import { docConsultedGate } from "./apex";
+
+/** File extensions the shadcn gate polices (source: `\.(tsx|jsx|css|scss|json)$`). */
+const SHADCN_FILE_RE = /\.(tsx|jsx|css|scss|json)$/;
+/**
+ * Vendored/build paths exempt from the gate. Uses `(^|\/)` (not just a
+ * leading `/`) so a relative root-start path like `node_modules/x` is also
+ * exempt — mirrors the same deliberate widening already applied in
+ * `design/skill-gate.ts`'s `EXEMPT_RE`, not the Python's stricter `/x/`-only match.
+ */
+const EXEMPT_RE = /(^|\/)(node_modules|dist|build)\//;
+/** Path fragments that put a write in shadcn scope (source: `(components|ui|shadcn|components\.json)`). */
+const SHADCN_PATH_RE = /(components|ui|shadcn|components\.json)/;
+/** A read reference proving one of the two named base skills was consulted (Phase 1). */
+const SHADCN_BASE_SKILL_RE = /skills\/(shadcn-detection|shadcn-components)\//;
+/** Session `authorizations` source proving a live `mcp__shadcn__*` call was made this session (Phase 1, option 3). */
+const SHADCN_MCP_SOURCE_RE = /shadcn-mcp/i;
+
+/** Session evidence the gate consumes: read references + doc authorizations. */
+export interface ShadcnEvidence {
+  refsRead: readonly string[];
+  authorizations?: Record<string, AuthEntry>;
+  sessionId: string;
+}
+
+/**
+ * True when this Write/Edit is shadcn-scoped: a `.tsx/.jsx/.css/.scss/.json`
+ * file under a `components|ui|shadcn|components.json` path, outside vendored
+ * dirs. Ports `check-skill-loaded.py`'s file-path filter (lines 35-42).
+ */
+export function isShadcnWrite(tool: string, filePath: string): boolean {
+  if (tool !== "Write" && tool !== "Edit") return false;
+  if (!SHADCN_FILE_RE.test(filePath) || EXEMPT_RE.test(filePath)) return false;
+  return SHADCN_PATH_RE.test(filePath);
+}
+
+/** True when `shadcn-detection/` or `shadcn-components/` was read this session (Phase 1 base skill). */
+export function shadcnBaseSkillRead(refsRead: readonly string[]): boolean {
+  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). */
+export function shadcnMcpConsulted(authorizations: Record<string, AuthEntry> | undefined, sessionId: string): boolean {
+  if (!authorizations) return false;
+  return Object.values(authorizations).some(
+    (a) => a.doc_sessions?.includes(sessionId) && (a.sources ?? (a.source ? [a.source] : [])).some((s) => SHADCN_MCP_SOURCE_RE.test(s)),
+  );
+}
+
+/**
+ * Gate a shadcn-scoped write. Phase 1 requires a base skill read
+ * (shadcn-detection or shadcn-components); Phase 2 requires the domain
+ * sub-skill(s) matching the written content, via {@link skillTriggerGate}
+ * keyed on the "shadcn" framework (registered in `SKILL_TRIGGERS`); Phase 3
+ * requires doc research, delegated to the existing {@link docConsultedGate}
+ * (Context7 AND Exa, or a web fallback alone — not the Python's strict AND).
+ * Returns a blocking {@link Prompt}, or `null` to allow.
+ */
+export function shadcnSkillGate(
+  tool: string,
+  filePath: string,
+  content: string,
+  ev: ShadcnEvidence,
+): Prompt | null {
+  if (!isShadcnWrite(tool, filePath)) return null;
+  if (!shadcnBaseSkillRead(ev.refsRead) && !shadcnMcpConsulted(ev.authorizations, ev.sessionId)) {
+    return {
+      kind: "block",
+      title: "shadcn/ui skill",
+      reason: "BLOCKED: shadcn skill not consulted. Read shadcn-detection/SKILL.md or shadcn-components/SKILL.md, or use mcp__shadcn__search_items_in_registries, then retry.",
+      actions: ["Read skills/shadcn-detection/ or skills/shadcn-components/, or call mcp__shadcn__search_items_in_registries, then retry"],
+    };
+  }
+  const domainBlock = skillTriggerGate("shadcn", content, ev.refsRead);
+  if (domainBlock) return domainBlock;
+  return docConsultedGate({
+    sessionId: ev.sessionId,
+    framework: "shadcn",
+    filePath,
+    content,
+    authorizations: ev.authorizations,
+  });
+}

package/src/policy/shell-read-refs.ts

@@ -0,0 +1,96 @@
+/**
+ * @module shell-read-refs
+ * Codex teammates frequently read skill/SOLID reference `.md` files through a
+ * shell Bash call (`cat`, `head`, …) instead of a native `Read` — the
+ * refsRead/ref-journal freshness gates only ever credited a native `Read`
+ * (`src/runtime/activity.ts`'s `READ_TOOLS` branch), so a shell-read skill
+ * consultation was invisible to every SOLID/skill gate. This detects the
+ * `.md` paths a KNOWN read-only command targets in a Bash `command`, for a
+ * caller to fold into the SAME `{kind:"ref", path, ts}` activity
+ * `src/runtime/record.ts` already persists (no new store, no new gate).
+ *
+ * Fail-open by construction: only a whitelisted read-only command name
+ * credits its `.md` arguments — a non-read command (`echo`, `mv`, `tee`, …)
+ * sharing a chained/piped segment is never credited, and `sed -i`/
+ * `--in-place` (a MUTATION despite the `sed` name) is explicitly excluded.
+ * @packageDocumentation
+ */
+import { commandToString } from "../runtime/command-string";
+import { shellOutputRedirects } from "./guards/bash-write-redirects";
+
+/** Read-only shell commands that can target a `.md` reference by path. */
+const READ_COMMANDS = new Set(["cat", "head", "tail", "sed", "rg", "ripgrep", "less", "more", "bat"]);
+
+/** POSIX shells whose `-c`-style argv (or inline string) wraps a real script. */
+const SHELL_BINS = new Set(["bash", "sh", "zsh", "dash"]);
+
+/** `sed -i` / `sed --in-place` mutates the file in place — never a read. */
+const SED_INPLACE = /(^|\s)(-i\b|--in-place\b)/;
+
+/** Split a command string on `&&`, `||`, `;`, `|`, and newlines — each side scanned independently. */
+function segments(command: string): string[] {
+  return command.split(/&&|\|\||[;|\n]/);
+}
+
+/** Strip a redirection (`>`, `>>`, `<`, `2>`, `&>`, …) and everything after — its target is WRITTEN, not read. */
+function beforeRedirect(segment: string): string {
+  const first = shellOutputRedirects(segment)[0];
+  return first ? segment.slice(0, first.start) : segment;
+}
+
+/** Naive shell tokenizer: whitespace-split, stripping one matching layer of quotes per token. */
+function tokenize(segment: string): string[] {
+  const tokens = segment.match(/(?:"[^"]*"|'[^']*'|\S+)/g) ?? [];
+  return tokens.map((t) => (/^(['"]).*\1$/.test(t) ? t.slice(1, -1) : t));
+}
+
+/** Index of the first token that isn't an env-assignment prefix (`KEY=VAL cmd …`). */
+function firstCommandIndex(tokens: string[]): number {
+  let i = 0;
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i] ?? "")) i++;
+  return i;
+}
+
+/** The inner script of a `sh|bash|zsh|dash -c <script>` wrapper (as ONE token, since {@link tokenize} keeps a quoted phrase whole), or undefined when `tokens` isn't that shape. */
+function unwrapShellC(tokens: string[]): string | undefined {
+  const i = firstCommandIndex(tokens);
+  const bin = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
+  if (!bin || !SHELL_BINS.has(bin)) return undefined;
+  const flag = tokens[i + 1];
+  if (!flag || !/^-[a-z]*c$/.test(flag)) return undefined;
+  return tokens[i + 2];
+}
+
+/** Credit the `.md` arguments of one segment if its command is a whitelisted read; recurses once into a `sh -c` wrapper. */
+function scanSegment(raw: string, out: string[]): void {
+  const segment = beforeRedirect(raw);
+  const tokens = tokenize(segment);
+  const inner = unwrapShellC(tokens);
+  if (inner !== undefined) {
+    for (const s of segments(inner)) scanSegment(s, out);
+    return;
+  }
+  const i = firstCommandIndex(tokens);
+  const name = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
+  if (!name || !READ_COMMANDS.has(name)) return;
+  if (name === "sed" && SED_INPLACE.test(segment)) return;
+  for (const t of tokens.slice(i + 1)) {
+    if (t.endsWith(".md") && !t.startsWith("-")) out.push(t);
+  }
+}
+
+/**
+ * The `.md` paths a read-only shell command reads in `command` (a Bash
+ * `tool_input.command` — plain string or Codex's argv-array form, both
+ * normalized via {@link commandToString}). Empty for a non-read command,
+ * `sed -i` in-place, or an unparseable/absent command — fail-open, never a
+ * false credit.
+ * @param command - Raw `tool_input.command` value (string | string[] | unknown).
+ */
+export function shellReadRefPaths(command: unknown): string[] {
+  const str = commandToString(command);
+  if (!str) return [];
+  const out: string[] = [];
+  for (const seg of segments(str)) scanSegment(seg, out);
+  return out;
+}

package/src/policy/skill-path.ts

@@ -0,0 +1,46 @@
+/**
+ * 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`.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { findMarketplacePlugins } from "../runtime/lifecycle/cartographer/detect";
+import { PLUGINS_DIR } from "./file-size";
+
+/** Sorted entry names of `dir` (alpha, byte-order), or `[]` on error. */
+function pluginDirNames(dir: string): string[] {
+  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).
+ */
+export function resolveSkillPath(skillName: string, pluginsDirOverride?: string): string {
+  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}`;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Laravel skill-trigger patterns, ported verbatim from `laravel_patterns.py`
+ * (consumed by `laravel_skill_triggers.py`). Matched case-insensitively.
+ */
+
+/** Map of Laravel sub-skill name → triggering PHP code patterns. */
+export const LARAVEL_TRIGGERS: Readonly<Record<string, ReadonlyArray<string>>> = {
+  "fusecore": ["FuseCore\\\\[A-Za-z]+\\\\App\\\\", "use HasModule\\b",
+    "ModuleServiceProvider\\b", "ModuleInterface\\b"],
+  "laravel-eloquent": ["(extends Model|HasFactory|belongsTo|hasMany|hasOne|morphTo)\\b",
+    "\\$this->belongsToMany|->with\\(|->whereHas\\(",
+    "(Eloquent|Model)::(find|where|create|update|all)\\b"],
+  "laravel-api": ["(JsonResource|ResourceCollection|apiResource)\\b",
+    "Route::(get|post|put|delete|apiResource)\\(",
+    "(response\\(\\)->json|Request \\$request)\\b"],
+  "laravel-auth": ["(Auth::|auth\\(\\)|Sanctum|Passport|Socialite)\\b",
+    "(Gate::|Policy|can\\(|authorize)\\b",
+    "(middleware\\(['\"]auth|LoginController|RegisterController)\\b"],
+  "laravel-livewire": ["(extends Component|Livewire|wire:|#\\[On)\\b",
+    "(mount|render|emit|dispatch)\\(\\)", "@livewire|<livewire:"],
+  "laravel-queues": ["(implements ShouldQueue|dispatch\\(|Bus::)\\b",
+    "(Queue::|Job|Batch|Chain)\\b", "(onQueue|onConnection|tries|backoff)\\b"],
+  "laravel-billing": ["(Billable|subscription|Cashier)\\b",
+    "(createSubscription|newSubscription|charge)\\("],
+  "laravel-stripe-connect": ["(StripeConnect|connectAccount|onboardingUrl)\\b",
+    "(paymentIntent|transfer|payout|splitPayment)\\b",
+    "Stripe\\\\\\\\(Account|Transfer|PaymentIntent)\\b"],
+  "laravel-testing": ["(extends TestCase|RefreshDatabase|WithFaker)\\b",
+    "(assertStatus|assertJson|assertSee|assertRedirect)\\(",
+    "(factory\\(|Pest|it\\(|test\\(|expect\\()\\b"],
+  "laravel-migrations": ["(Schema::|Blueprint|->table|->create)\\b",
+    "(->string|->integer|->boolean|->foreignId|->index)\\(", "extends Migration\\b"],
+  "laravel-blade": ["(@extends|@section|@yield|@component|@slot)\\b",
+    "(@if|@foreach|@include|@push|@stack)\\b", "(Blade::|x-[a-z])\\b"],
+  "laravel-permission": ["(hasRole|givePermissionTo|assignRole|spatie)\\b",
+    "(Permission|Role)::(create|findByName)\\b", "@can\\b|@role\\b|middleware.*role:"],
+  "laravel-i18n": ["(__\\(|trans\\(|trans_choice\\(|@lang)\\b",
+    "Lang::|->locale\\(|setLocale\\b"],
+  "laravel-vite": ["(@vite|@viteReactRefresh|Vite::)\\b"],
+};

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

@@ -0,0 +1,29 @@
+/**
+ * Next.js skill-trigger patterns, ported verbatim from `nextjs_skill_triggers.py`.
+ * Matched case-insensitively (source `re.IGNORECASE`).
+ */
+import { SHADCN } from "./shadcn";
+
+/** Map of Next.js sub-skill name → triggering code patterns. */
+export const NEXTJS_TRIGGERS: Readonly<Record<string, ReadonlyArray<string>>> = {
+  "better-auth": ["(authClient|betterAuth|createAuthClient)\\b",
+    "(signIn|signUp|signOut|useSession|getSession)\\b", "auth\\.(api|handler)\\b",
+    "(prismaAdapter|drizzleAdapter|mongodbAdapter)\\b",
+    "(twoFactor|passkey|magicLink|emailOtp|organization)\\b",
+    "(apiKey|bearer|jwt|sso|scim|captcha|anonymous)\\b", "from\\s+['\"].*better-auth"],
+  "nextjs-tanstack-form": ["(useForm|useAppForm|createFormHook|formOptions)\\b",
+    "(mergeForm|formApi|FieldApi|FormApi)\\b",
+    "form\\.(Field|Subscribe|handleSubmit)\\b", "(zodValidator|onServerValidate)\\b",
+    "from\\s+['\"]@tanstack/(react-form|zod-form-adapter)"],
+  "prisma-7": ["(PrismaClient|prismaAdapter)\\b", "prisma\\.(\\w+\\.\\w+|\\$\\w+)",
+    "(globalForPrisma|\\$transaction|\\$queryRaw|\\$executeRaw)\\b",
+    "from\\s+['\"](@prisma|\\..*generated.*prisma)"],
+  "nextjs-shadcn": SHADCN,
+  "nextjs-zustand": ["(create|createStore)\\(\\s*\\(\\s*set", "from\\s+['\"]zustand(/\\w+)?\"",
+    "(useShallow|useStore|skipHydration)\\b", "\\.(getState|setState|subscribe)\\(\\)",
+    "(persist|devtools|immer)\\("],
+  "nextjs-i18n": ["(useTranslations|useLocale|useMessages|useFormatter)\\b",
+    "(getTranslations|getLocale|getMessages|getFormatter)\\b",
+    "(NextIntlClientProvider|defineRouting)\\b", "from\\s+['\"]next-intl(/\\w+)?\"",
+    "\\bt\\(\\s*['\"]"],
+};

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)",
+  ],
+};