@fusengine/harness 0.1.89 → 0.1.91

package/src/policy/conventions/query.ts

@@ -0,0 +1,49 @@
+/**
+ * TanStack Query definition detection over MASKED content (React and Vue
+ * variants share the call names; the family scoping is the gate's job, via
+ * project deps). Canonical home: `src/query/` — one file per domain. Only
+ * DEFINITIONS are gated; inline consumption of a hook defined in `query/`
+ * stays allowed.
+ */
+import { maskCommentsAndStrings } from "./strip";
+import { nearestManifestDir, projectCaps } from "../nearest-manifest";
+import { dirname, resolve } from "node:path";
+
+/** Import line of a TanStack Query package (raw scan: masking blanks the module string). */
+const QUERY_IMPORT_RE = /^\s*import\s+[^;]*@tanstack\/[\w-]*query[\w-]*/m;
+
+/** A TanStack Query definition call. */
+const QUERY_CALL_RE = /\b(?:useQuery|useMutation|useInfiniteQuery|queryOptions)\s*(?:<[^()]*>)?\s*\(/;
+
+/** Exported declaration (`export const|function`) — a defined query hook. */
+const EXPORT_DECL_RE = /^\s*export\s+(?:const|function)\s+\w+/m;
+
+/**
+ * True when the file imports a TanStack Query package (raw scan, anchored to
+ * real import lines so `// import …` comments cannot match).
+ * @param content - Raw file content.
+ */
+export function importsTanstackQuery(content: string): boolean {
+  return QUERY_IMPORT_RE.test(content);
+}
+
+/**
+ * True when the file DEFINES an exported query/mutation hook (export +
+ * query call, masked scan) — as opposed to merely consuming one inline.
+ * @param content - Raw file content.
+ */
+export function declaresQueryHook(content: string): boolean {
+  const masked = maskCommentsAndStrings(content, "c");
+  return QUERY_CALL_RE.test(masked) && EXPORT_DECL_RE.test(masked);
+}
+
+/**
+ * True when the nearest manifest of `filePath` declares a TanStack Query
+ * dependency (`@tanstack/react-query` or `@tanstack/vue-query`) — the
+ * cap gate of every query convention (owner: no cap, no query rule).
+ * @param filePath - The file being judged (its nearest manifest wins).
+ */
+export function queryCapActive(filePath: string): boolean {
+  const caps = projectCaps(nearestManifestDir(dirname(resolve(filePath))));
+  return caps.has("tanstack-query") || caps.has("vue-query");
+}

package/src/policy/conventions/react-hooks.ts

@@ -0,0 +1,18 @@
+/**
+ * Custom React hook declaration detection over MASKED content. Historical
+ * rule (`framework-solid-gates.ts`): an exported custom hook belongs in
+ * `hooks/` — the regex was naive (`^export (function|const) use[A-Z]`,
+ * missing `export default`, `async`, and matching inside comments/strings).
+ */
+import { maskCommentsAndStrings } from "./strip";
+
+/** Exported custom hook: `export [default] [async] function|const useX`. */
+const HOOK_DECL_RE = /^\s*export\s+(?:default\s+)?(?:async\s+)?(?:function|const)\s+use[A-Z]\w*/m;
+
+/**
+ * True when the file declares an exported custom `use*` hook (masked scan).
+ * @param content - Raw file content.
+ */
+export function declaresCustomHook(content: string): boolean {
+  return HOOK_DECL_RE.test(maskCommentsAndStrings(content, "c"));
+}

package/src/policy/conventions/store-or-query.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared store/query-definition exemption (owner F0.2): a file is governed
+ * by the store/query conventions — NOT by the hook-location rule — ONLY when
+ * its signature is validated AND its ecosystem is confirmed:
+ * - store: the real `zustand`/`pinia` import (or the v5 curried signature);
+ * - query: a TanStack Query definition AND the `@tanstack/*-query` cap in
+ *   the nearest manifest. Without the cap, a fake `useQuery(` caller is just
+ *   a hook — the legacy hook rule applies, byte-identical.
+ */
+import { declaresStore } from "./stores";
+import { declaresQueryHook, queryCapActive } from "./query";
+
+/**
+ * True when the file is a store or query definition (exempt from hook rules).
+ * @param filePath - The file being judged (manifest resolution for the cap).
+ * @param content - Its RAW content (detectors mask internally).
+ */
+export function isStoreOrQueryDefinition(filePath: string, content: string): boolean {
+  if (declaresStore(content, "zustand") || declaresStore(content, "pinia")) return true;
+  return declaresQueryHook(content) && queryCapActive(filePath);
+}

package/src/policy/conventions/stores.ts

@@ -0,0 +1,56 @@
+/**
+ * State-store declaration detection over MASKED content — Zustand (React
+ * family) and Pinia (Vue family), per the owner's framework scoping: a rule
+ * only fires inside its own family (the gate checks the project deps, this
+ * module only reads content). Canonical home: `src/stores/`, `*.store.ts`,
+ * one store per domain, budget = ratio 0.4 of the global line limit.
+ *
+ * Signature-strict (audit lesson): `Object.create(` and home-made
+ * `create(` factories never match — Zustand requires the `zustand` import
+ * (or the v5 curried `create<T>()(...)` call), Pinia requires the `pinia`
+ * import alongside `defineStore(`.
+ */
+import { maskCommentsAndStrings, maskCommentsOnly } from "./strip";
+
+/** Store library whose declarations are being scanned. */
+export type StoreLib = "zustand" | "pinia";
+
+/** Import line of the store package — comments masked (a `// import …` line
+ * never matches), strings KEPT (masking would blank the module literal). */
+const STORE_IMPORT_RE: Record<StoreLib, RegExp> = {
+  zustand: /^\s*import\s+[^;]*from\s+['"]zustand/m,
+  pinia: /^\s*import\s+[^;]*from\s+['"]pinia/m,
+};
+
+/** Zustand v5 curried declaration: `export const useX = create<S>()(`. */
+const ZUSTAND_CURRIED_RE = /^\s*export\s+const\s+\w+\s*=\s*create\s*<[^=]*>\s*\(\s*\)\s*\(/m;
+/** Zustand declaration with import context: `export const useX = create(`. */
+const ZUSTAND_DECL_RE = /^\s*export\s+const\s+\w+\s*=\s*create(?:Store)?\s*(?:<[^(]+>)?\s*\(/m;
+/** Pinia declaration: `export const useX = defineStore(`. */
+const PINIA_DECL_RE = /^\s*export\s+const\s+\w+\s*=\s*defineStore\s*\(/m;
+
+/**
+ * True when the file declares a store of the given library (masked scan,
+ * signature-strict).
+ * @param content - Raw file content.
+ * @param lib - Store library to detect.
+ */
+export function declaresStore(content: string, lib: StoreLib): boolean {
+  const masked = maskCommentsAndStrings(content, "c");
+  const importable = maskCommentsOnly(content, "c");
+  if (lib === "pinia") return STORE_IMPORT_RE.pinia.test(importable) && PINIA_DECL_RE.test(masked);
+  return ZUSTAND_CURRIED_RE.test(masked) || (STORE_IMPORT_RE.zustand.test(importable) && ZUSTAND_DECL_RE.test(masked));
+}
+
+/**
+ * Count store declarations in one file (multi-store advisory: one per domain).
+ * @param content - Raw file content.
+ * @param lib - Store library to count.
+ */
+export function countStores(content: string, lib: StoreLib): number {
+  const masked = maskCommentsAndStrings(content, "c");
+  const re = lib === "pinia" ? PINIA_DECL_RE : ZUSTAND_DECL_RE;
+  const curried = masked.match(new RegExp(ZUSTAND_CURRIED_RE.source, "gm"))?.length ?? 0;
+  const plain = masked.match(new RegExp(re.source, "gm"))?.length ?? 0;
+  return lib === "pinia" ? plain : Math.max(curried, plain);
+}

package/src/policy/conventions/strip.ts

@@ -0,0 +1,87 @@
+/**
+ * Lexical comment/string masking for convention detectors. Every convention
+ * rule (interfaces, types, hooks, stores, query) matches against MASKED
+ * content so a declaration-looking line inside a comment, string, template
+ * literal, or heredoc can never trigger a verdict. Masking replaces the
+ * covered CHARACTERS with spaces but keeps every newline: line offsets and
+ * `^…/m` anchors stay valid, and the output has the same line count.
+ * Not a parser — a per-family state machine (c-like, python, ruby, php).
+ */
+
+/** Lexical profile of a language family. */
+export type LexProfile = "c" | "py" | "rb" | "php";
+
+/** Mask PHP heredoc/nowdoc blocks (`<<<TAG` … terminator line), offsets kept. */
+function maskHeredocs(content: string): string {
+  return content.replace(/<<<['"]?(\w+)['"]?\r?\n[\s\S]*?^\1;?$/gm, (block) => block.replace(/[^\n]/g, " "));
+}
+
+/**
+ * Mask comments and strings of `content` according to its lexical profile.
+ * @param content - Source text.
+ * @param profile - Lexical family (see `langs.ts` `lexProfileOf`).
+ * @returns Same-length text with comment/string interiors blanked.
+ */
+export function maskCommentsAndStrings(content: string, profile: LexProfile): string {
+  return maskScan(content, profile, false);
+}
+
+/**
+ * Mask COMMENTS only (strings kept) — for detectors whose signal IS a string
+ * literal (module imports like `from "zustand"`): a `// import …` comment
+ * cannot match, while the real import line stays readable.
+ * @param content - Source text.
+ * @param profile - Lexical family.
+ * @returns Same-length text with comment interiors blanked.
+ */
+export function maskCommentsOnly(content: string, profile: LexProfile): string {
+  return maskScan(content, profile, true);
+}
+
+/** Shared scanner; `keepStrings` skips the string-masking branch. */
+function maskScan(content: string, profile: LexProfile, keepStrings: boolean): string {
+  if (profile === "php") content = maskHeredocs(content);
+  const out = content.split("");
+  const blank = (i: number) => { if (out[i] !== "\n") out[i] = " "; };
+  const isPy = profile === "py" || profile === "rb";
+  let i = 0;
+  while (i < out.length) {
+    const two = content.slice(i, i + 2);
+    if (!isPy && two === "//") { while (i < out.length && out[i] !== "\n") blank(i++); continue; }
+    if (isPy && out[i] === "#") { while (i < out.length && out[i] !== "\n") blank(i++); continue; }
+    if (profile === "php" && out[i] === "#") { while (i < out.length && out[i] !== "\n") blank(i++); continue; }
+    if (!isPy && two === "/*") { const end = content.indexOf("*/", i + 2); const stop = end === -1 ? out.length : end + 2; while (i < stop) blank(i++); continue; }
+    if (isPy && (content.startsWith("'''", i) || content.startsWith('"""', i))) {
+      const q = content.slice(i, i + 3);
+      const end = content.indexOf(q, i + 3);
+      const stop = end === -1 ? out.length : end + 3;
+      while (i < stop) blank(i++);
+      continue;
+    }
+    if (!keepStrings && (out[i] === "'" || out[i] === '"' || (profile === "c" && out[i] === "`"))) {
+      const q = out[i] as string;
+      // Unterminated-quote guard: a single/double quote never opens a string
+      // past its own line (JS/TS has no multiline plain strings — a JSX
+      // apostrophe like `Don't` must not swallow the rest of the file), and
+      // an unterminated template literal masks nothing (unpaired backtick).
+      let j = i + 1, closed = -1;
+      while (j < out.length && out[j] !== "\n") {
+        if (out[j] === "\\") { j += 2; continue; }
+        if (out[j] === q) { closed = j; break; }
+        j++;
+      }
+      if (q === "`") {
+        if (closed !== -1) { while (i <= closed) blank(i++); continue; }
+        const end = content.indexOf("`", i + 1);
+        if (end !== -1) { while (i <= end) blank(i++); continue; }
+        i++;
+        continue;
+      }
+      if (closed === -1) { i++; continue; }
+      while (i <= closed) blank(i++);
+      continue;
+    }
+    i++;
+  }
+  return out.join("");
+}

package/src/policy/conventions/verdict.ts

@@ -0,0 +1,38 @@
+/**
+ * Rollout control for NEW convention denies (owner decision, inverted
+ * 2026-07): new convention rules BLOCK by default — `FUSE_CONVENTIONS_MODE`
+ * is an opt-OUT. Set it to `advisory` to observe without blocking (`inform`
+ * output); any absent or invalid value means `deny`. Denies that already
+ * existed before the conventions module are unaffected (byte-parity); this
+ * module only ever MODULATES the new ones.
+ */
+import type { Prompt } from "../../prompt/types";
+
+/** Rollout mode for new convention denies. */
+export type ConventionsMode = "advisory" | "deny";
+
+/**
+ * Current rollout mode: `advisory` ONLY on the exact explicit value —
+ * anything else (absent, typo, empty) is `deny` (owner decision: deny-first).
+ * @param env - Environment (defaults to `process.env`).
+ */
+export function conventionsMode(env: Record<string, string | undefined> = process.env): ConventionsMode {
+  return env.FUSE_CONVENTIONS_MODE === "advisory" ? "advisory" : "deny";
+}
+
+/**
+ * Resolve a convention verdict under the rollout flag: a NEW rule yields an
+ * `inform` prompt in advisory mode (explicit opt-out), the blocking prompt
+ * otherwise; an EXISTING rule always yields the blocking prompt unchanged.
+ * @param prompt - The blocking prompt the rule would emit.
+ * @param isNew - True when the rule is new (post-conventions module).
+ * @param env - Environment (defaults to `process.env`).
+ */
+export function rolloutVerdict(
+  prompt: Prompt,
+  isNew: boolean,
+  env: Record<string, string | undefined> = process.env,
+): Prompt {
+  if (!isNew || conventionsMode(env) === "deny") return prompt;
+  return { kind: "inform", title: prompt.title, reason: prompt.reason, actions: prompt.actions };
+}

package/src/policy/creation-intent.ts

@@ -0,0 +1,11 @@
+const CREATE_RE = /\b(?:create|implement|add|build|new|feature|component|generate|make|develop|scaffold)\b/i;
+const SKIP_RE = /\b(?:fix|bug|debug|update|refactor|rename|move|delete|remove|commit|push|status|edit|modify|change|adjust|tweak|existing|current)\b/i;
+
+/**
+ * True when a prompt expresses creation intent (a new feature/component) and is
+ * not a fix/refactor — the signal that brainstorming should precede creation.
+ * The harness calls this on UserPromptSubmit, then `recordBrainstormRequired`.
+ */
+export function detectCreationIntent(prompt: string): boolean {
+  return CREATE_RE.test(prompt) && !SKIP_RE.test(prompt);
+}

package/src/policy/deny-loop.ts

@@ -0,0 +1,88 @@
+/**
+ * @module deny-loop
+ * Pure anti-loop logic: hash a tool-call, decide if it repeats a prior deny, and
+ * enrich the repeated block's message.
+ *
+ * The proprietary rule "NEVER propose the same fix twice" is prose a model under
+ * pressure ignores. This makes it machine-enforced: when a call whose
+ * `(tool + normalized input)` hash was ALREADY denied in-window is retried, the
+ * harness keeps the deny but rewrites the message — `[REPEAT]` title, a
+ * mid-sentence STOP warning, forced `research-expert` action. State + wiring live in the sidecar
+ * store ({@link module:deny-loop-store}); this file is IO-free and pure.
+ * @packageDocumentation
+ */
+import { hashText } from "../util/json-io";
+import type { Prompt } from "../prompt/types";
+
+/** One recorded deny: identical-in-window count, and when the last landed. */
+export interface DenyEntry { count: number; lastTs: number; }
+
+/** Loop-check outcome: does the input repeat an in-window deny, and its running count. */
+export interface DenyLoopResult { isRepeat: boolean; count: number; hash: string; deduped?: boolean; }
+
+/** Stable JSON: keys sorted at every depth so `{a,b}` and `{b,a}` hash identically. */
+function stableStringify(v: unknown): string {
+  if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  const o = v as Record<string, unknown>;
+  return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(",")}}`;
+}
+
+/**
+ * Stable identity hash of a tool-call = tool name + normalized (key-sorted) input,
+ * so re-ordered keys never mask a repeat.
+ * @param tool - Tool name (e.g. "Write", "Bash").
+ * @param input - Identifying tool input (filePath/content/command...).
+ * @returns 8-char hex hash.
+ */
+export function denyHash(tool: string, input: Record<string, unknown>): string {
+  return hashText(`${tool}\n${stableStringify(input)}`);
+}
+
+/**
+ * Pure loop check: given the already-pruned in-window map, compute the running
+ * count for `hash` and whether it repeats (count > 1). No IO — the caller persists.
+ *
+ * When `dedupMs` is set (>0) and an identical prior deny landed within that
+ * window, the current call is a sibling hook echoing the SAME event (see
+ * {@link module:burst-window}): it returns the prior verdict VERBATIM with
+ * `deduped:true` and does NOT bump the count, so all N fan-out processes agree
+ * on one number instead of counting to N. Absent `dedupMs` (mono-process
+ * callers / unit tests) the historical increment-every-time behaviour holds.
+ * @param hash - {@link denyHash}-derived map key of the current call.
+ * @param priorDenies - The `{ hash -> DenyEntry }` map, pruned to `now`/`windowMs`.
+ * @param opts - Clock + window, plus an optional burst-dedup window.
+ * @returns `{ isRepeat, count, hash, deduped? }`.
+ */
+export function denyLoopCheck(hash: string, priorDenies: Record<string, DenyEntry>, opts: { now: number; windowMs: number; dedupMs?: number }): DenyLoopResult {
+  const prev = priorDenies[hash];
+  const fresh = prev && typeof prev.lastTs === "number" && opts.now - prev.lastTs < opts.windowMs;
+  if (!fresh) return { isRepeat: false, count: 1, hash };
+  if ((opts.dedupMs ?? 0) > 0 && opts.now - prev.lastTs < (opts.dedupMs ?? 0)) {
+    return { isRepeat: prev.count > 1, count: prev.count, hash, deduped: true };
+  }
+  const count = prev.count + 1;
+  return { isRepeat: count > 1, count, hash };
+}
+
+/**
+ * Enrich a REPEATED block prompt — a NEW object, never a mutation (the input may
+ * be a shared const like FAIL_CLOSED). The decision stays `block`; only the
+ * message changes, so every harness renders it through the same adapter.
+ * @param prompt - The original block prompt.
+ * @param count - The running identical-deny count (n).
+ * @returns A block prompt with `[REPEAT]` title, STOP-prefixed reason, forced research action.
+ */
+export function enrichRepeatDeny(prompt: Prompt, count: number): Prompt {
+  // H2b: the counter cannot know whether new reads/actions happened since the
+  // last deny, so the hard STOP is reserved for the UNCHANGED retry — a retry
+  // after completing the required reads/actions is legitimate and expected.
+  const stop = `Identical attempt #${count} already denied for the same reason. Do not retry this same call UNCHANGED — if you have since completed the required reads/actions, retry now; otherwise STOP and pick a DIFFERENT approach. `;
+  const action = "Launch fuse-ai-pilot:research-expert to find a DIFFERENT approach";
+  return {
+    ...prompt,
+    title: prompt.title.startsWith("[REPEAT]") ? prompt.title : `[REPEAT] ${prompt.title}`,
+    reason: stop + prompt.reason,
+    actions: [action, ...(prompt.actions ?? [])],
+  };
+}

package/src/policy/design/allowed-write.ts

@@ -0,0 +1,28 @@
+/**
+ * @module allowed-write
+ * The design-agent write allowlist, split out of `gates.ts` to keep that file
+ * within the SOLID size budget (SRP).
+ * @packageDocumentation
+ */
+import { basename } from "node:path";
+
+/** Extensions the design agent may always write: .html/.css/.md/.json. */
+export const ALLOWED_WRITE: RegExp = /\.(html|css|md|json)$/;
+
+/**
+ * C4: `motion*.js` ONLY, matched on the BASENAME — every one of the 11
+ * corpus references ships its animation as a separate `motion.js` /
+ * `motion-nav.js` / `motion-scroll.js` file, so banning every `.js` forced
+ * the agent to inline scripts the corpus explicitly teaches out-of-band.
+ * Deliberately NOT `\.js$` in general (that would open arbitrary app code,
+ * the exact thing this gate exists to block) — after the `motion` prefix,
+ * either nothing (`motion.js`) or `.`/`-` then more (`motion-nav.js`) must
+ * lead into `.js`; `app.js` and `motionless-app.js` — a bare `^motion`
+ * prefix would wrongly pass this — do not match.
+ */
+const MOTION_JS: RegExp = /^motion([.-].*)?\.js$/;
+
+/** True when `filePath` is a write the design agent may make: .html/.css/.md/.json, or a `motion*.js` file. */
+export function isAllowedWrite(filePath: string): boolean {
+  return ALLOWED_WRITE.test(filePath) || MOTION_JS.test(basename(filePath));
+}

package/src/policy/design/content-checks.ts

@@ -0,0 +1,45 @@
+/** Accessibility warnings: icon buttons need aria-label, images need alt. */
+function checkAccessibility(content: string): string[] {
+  const w: string[] = [];
+  if (!/<(button|a|input|img)/.test(content)) return w;
+  if (/<button[^>]*>/.test(content) && !/aria-label|aria-labelledby/.test(content) && /<button[^>]*>[^<]*<[^>]*Icon/.test(content)) {
+    w.push("Accessibility: icon buttons need an aria-label.");
+  }
+  for (const m of content.matchAll(/<img[^>]*?>/g)) {
+    if (!m[0].includes("alt=")) {
+      w.push("Accessibility: images need an alt attribute.");
+      break;
+    }
+  }
+  return w;
+}
+
+/** Anti-pattern warnings: colored left borders, AI-slop gradients, emoji-as-icons. */
+function checkPatterns(content: string): string[] {
+  const w: string[] = [];
+  if (/border-l-[0-9]+ border-l-(blue|green|red|purple)/.test(content)) w.push("Design: avoid colored left borders — use shadow/gradient.");
+  if (/from-purple|to-purple|via-purple|from-pink.*to-purple/.test(content)) w.push("Design: avoid purple/pink gradients (AI slop) — use brand colors.");
+  if (/>[^\x00-\x7F]+</.test(content)) w.push("Design: avoid emojis as icons — use a real icon set.");
+  return w;
+}
+
+/** Forbidden-font warnings (CSS font-family + Google Fonts import). */
+function checkFonts(content: string): string[] {
+  const w: string[] = [];
+  if (/font-family:\s*['"]?(Roboto|Inter|Arial|Open Sans|Lato)\b/i.test(content)) w.push("Font: forbidden family (Roboto/Inter/Arial/Open Sans/Lato) — use identity fonts.");
+  if (/@import.*fonts\.googleapis.*family=(Roboto|Inter)\b/.test(content)) w.push("Font: Google Fonts import for a forbidden family.");
+  return w;
+}
+
+/** Hard-coded-color warnings (hex in className or inline style). */
+function checkColors(content: string): string[] {
+  const w: string[] = [];
+  if (/className="[^"]*#[0-9a-fA-F]{3,8}[^"]*"/.test(content)) w.push("Color: hard-coded hex in className — use CSS variables.");
+  if (/(?:color|background(?:-color)?|fill|stroke):\s*['"]?#[0-9a-fA-F]{3,8}/.test(content)) w.push("Color: hard-coded hex in style — use var(--color-*).");
+  return w;
+}
+
+/** Run all design content checks → non-blocking warnings (empty = clean). */
+export function runDesignChecks(content: string): string[] {
+  return [...checkAccessibility(content), ...checkPatterns(content), ...checkFonts(content), ...checkColors(content)];
+}

package/src/policy/design/corpus-fs.ts

@@ -0,0 +1,21 @@
+/**
+ * @module corpus-fs
+ * Shared fs primitives for corpus/plugins root resolution, split out of
+ * `corpus-resolve.ts` so `corpus-resolve-cache.ts` can reuse them without a
+ * circular import (both modules feed `corpus-resolve.ts`'s `probeClaude`).
+ * @packageDocumentation
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** The refs-design/ path suffix common to every design-corpus-bearing plugin tree. */
+export const CORPUS_SUFFIX: string = join("skills", "design-web", "references", "refs-design");
+
+/** Immediate child dir names of `dir`, alphabetically sorted, or [] when unreadable. */
+export function children(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort();
+  } catch {
+    return [];
+  }
+}

package/src/policy/design/corpus-resolve-cache.ts

@@ -0,0 +1,49 @@
+/**
+ * @module corpus-resolve-cache
+ * Claude Code's per-plugin VERSIONED CACHE tree, split out of
+ * `corpus-resolve.ts` to keep that file within the SOLID size budget (SRP).
+ *
+ * Claude Code caches every installed marketplace plugin at
+ * `~/.claude/plugins/cache/<mkt>/<plugin>/<version>/` — a tree SEPARATE from
+ * `~/.claude/plugins/marketplaces/<mkt>/plugins/<plugin>/` (the marketplace's
+ * own checkout), one version dir per `plugin.json` version bump, orphaned
+ * versions pruned ~14 days after being superseded (docs: "Plugin caching and
+ * file resolution"). The design corpus can ship under EITHER tree, and under
+ * a DIFFERENT plugin id in each: a machine observed 2026-07-29 has the corpus
+ * at `cache/fusengine-plugins/fuse-design/2.2.3/...` while the marketplace
+ * checkout is `marketplaces/fusengine-plugins/plugins/design-expert/...`.
+ * Identification here is therefore STRUCTURAL, never by plugin name: a
+ * candidate `<mkt>/<plugin>/<version>/` dir qualifies iff it itself contains
+ * `CORPUS_SUFFIX` — matching a hardcoded name would silently miss a
+ * renamed/relocated corpus (the exact defect this module fixes).
+ * @packageDocumentation
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { maxSemver } from "../../util/semver";
+import { CORPUS_SUFFIX, children } from "./corpus-fs";
+
+/** Real (non-prerelease) semver dirs, same filter `probeCodex` uses. */
+const SEMVER_RE = /^\d+\.\d+(\.\d+)?$/;
+
+/**
+ * Claude: `<home>/.claude/plugins/cache/<mkt>/<plugin>/<highest STABLE semver
+ * containing refs-design>` ("" when no plugin under any marketplace cache
+ * ships the corpus). Marketplaces and plugin ids are both walked — neither is
+ * assumed — so a corpus shipped under any plugin name is found.
+ */
+export function probeClaudeCache(home: string): string {
+  const cacheRoot = join(home, ".claude", "plugins", "cache");
+  for (const mkt of children(cacheRoot)) {
+    const mktDir = join(cacheRoot, mkt);
+    for (const plugin of children(mktDir)) {
+      const pluginDir = join(mktDir, plugin);
+      const versions = children(pluginDir).filter(
+        (v) => SEMVER_RE.test(v) && existsSync(join(pluginDir, v, CORPUS_SUFFIX)),
+      );
+      const latest = maxSemver(versions);
+      if (latest) return join(pluginDir, latest);
+    }
+  }
+  return "";
+}

package/src/policy/design/corpus-resolve.ts

@@ -0,0 +1,99 @@
+/**
+ * Corpus/plugins root resolution (fs) and the write guard over it. Resolution
+ * is PER RUNTIME (Claude marketplaces, Codex versioned plugin cache — same
+ * pattern as rules-root.ts); runtimes without a plugin structure (kimi today)
+ * resolve to "" and the corpus gates stay dormant. There is NO cwd fallback
+ * anywhere: an agent-controlled directory can never become its own taste
+ * reference (self-attested proof — the failure this gate exists to prevent).
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize } from "node:path";
+import type { Prompt } from "../../prompt/types";
+import { detectHarness, type HarnessId } from "../../detect/harness";
+import { maxSemver } from "../../util/semver";
+import { CORPUS_SUFFIX, children } from "./corpus-fs";
+import { probeClaudeCache } from "./corpus-resolve-cache";
+
+/** Claude marketplace checkout: `<home>/.claude/plugins/marketplaces/<mkt>/plugins/design-expert` ("" when absent). */
+function probeClaudeMarketplace(home: string): string {
+  const markets = join(home, ".claude", "plugins", "marketplaces");
+  for (const m of children(markets)) {
+    const de = join(markets, m, "plugins", "design-expert");
+    if (existsSync(de)) return de;
+  }
+  return "";
+}
+
+/**
+ * Claude: the marketplace checkout WINS when present (a single unambiguous
+ * live git checkout); the versioned plugin CACHE tree is the fallback, since
+ * Claude Code keeps orphaned prior-version cache dirs ~14 days after a bump.
+ */
+function probeClaude(home: string): string {
+  return probeClaudeMarketplace(home) || probeClaudeCache(home);
+}
+
+/** Codex: `<CODEX_HOME|~/.codex>/plugins/cache/<mkt>/design-expert/<highest STABLE semver>` ("" when absent). */
+function probeCodex(env: Record<string, string | undefined>, home: string): string {
+  const cache = join(env.CODEX_HOME ?? join(home, ".codex"), "plugins", "cache");
+  for (const m of children(cache)) {
+    const de = join(cache, m, "design-expert");
+    // Only real version dirs compete — no pre-release, no stray backup/ dir.
+    const latest = maxSemver(children(de).filter((v) => /^\d+\.\d+(\.\d+)?$/.test(v) && existsSync(join(de, v, "skills"))));
+    if (latest) return join(de, latest);
+  }
+  return "";
+}
+
+/**
+ * The design-expert plugin root for the ACTIVE runtime ("" = not installed).
+ * `pluginsDirOverride` short-circuits resolution (tests): a PLUGINS dir whose
+ * `design-expert` child is used when present, else itself.
+ */
+export function resolvePluginsRoot(
+  pluginsDirOverride?: string,
+  home: string = homedir(),
+  id: HarnessId = detectHarness().id,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  if (pluginsDirOverride) {
+    const de = join(pluginsDirOverride, "design-expert");
+    return existsSync(de) ? de : pluginsDirOverride;
+  }
+  if (id === "claude-code") return probeClaude(home);
+  if (id === "codex") return probeCodex(env, home);
+  return "";
+}
+
+/** Resolve the delivered refs-design/ root, or "" when absent/unusable (the fail-open signal). */
+export function resolveCorpusRoot(
+  pluginsDirOverride?: string,
+  home: string = homedir(),
+  id: HarnessId = detectHarness().id,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const root = resolvePluginsRoot(pluginsDirOverride, home, id, env);
+  if (!root) return "";
+  const corpus = join(root, CORPUS_SUFFIX);
+  return existsSync(corpus) ? corpus : "";
+}
+
+/**
+ * Deny Write/Edit/apply_patch-file under the resolved plugins root: the corpus
+ * is the artefact the pipeline checks reads against, so it must stay
+ * agent-proof — including while refs-design/ is still absent. Relative paths
+ * (the normal form of Codex patches) are resolved against `cwd` first. SCOPE:
+ * no Bash, no symlinks, no sibling marketplace — the gate protects against
+ * oversight, not an adversary (the mandatory screenshot stays the unforgeable
+ * proof; forging the corpus only lowers a quota).
+ */
+export function pluginsWriteGuard(filePath: string, pluginsRoot: string, cwd = ""): Prompt | null {
+  const abs = isAbsolute(filePath) ? filePath : cwd ? normalize(join(cwd, filePath)) : filePath;
+  if (!pluginsRoot || !abs.startsWith(`${pluginsRoot}/`)) return null;
+  return {
+    kind: "block", title: "Design pipeline",
+    reason: "BLOCKED: the design-expert plugin dir (refs-design corpus) is read-only — it is the taste reference your reads are checked against. Never create or modify files there.",
+    actions: ["Read the corpus with the Read tool; write your own files in the project"],
+  };
+}