@fusengine/harness 0.1.90 → 0.1.91

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

package/src/policy/design/corpus.ts

@@ -0,0 +1,92 @@
+/**
+ * Corpus anchoring for the design pipeline: refs-design/ read classification,
+ * per-mode readiness, citation form, citation↔read jointure. Nothing about
+ * the corpus content (slugs, section titles, count) is hardcoded — everything
+ * is matched by shape or discovered on disk, so a new reference or a renamed
+ * section never requires reopening the harness. Pure string logic only; root
+ * resolution and the write guard live in `corpus-resolve.ts`.
+ */
+import { basename, join } from "node:path";
+import type { DesignMode } from "./state";
+
+export { resolveCorpusRoot, resolvePluginsRoot, pluginsWriteGuard } from "./corpus-resolve";
+
+/**
+ * What a read under the corpus root is: the index, a tokens-* procedure
+ * file, or a per-reference `design-system.md` DIRECTION sheet (C6) — the
+ * fiche a reference ships alongside its `tokens-*.md`: register, tone,
+ * macrostructure, signature element (the PROCEDURES live in tokens-*;
+ * design-system.md is what you read to CHOOSE a reference in the first
+ * place). "sheet" is a new variant, not folded into "index" — the two are
+ * read for opposite reasons (corpus-wide index vs one reference's direction).
+ */
+export type CorpusKind = "index" | "tokens" | "sheet";
+
+const TOKENS_RE = /^tokens-.+\.md$/;
+const CORPUS_LINE_RE = /^[-*]\s*Corpus:\s*(.+)$/gim;
+
+/** Classify a read path against the DELIVERED corpus root (null = not a corpus read). */
+export function classifyCorpusRead(filePath: string, corpusRoot: string): CorpusKind | null {
+  if (!corpusRoot) return null;
+  if (filePath === join(corpusRoot, "README.md")) return "index";
+  if (!filePath.startsWith(`${corpusRoot}/`)) return null;
+  if (TOKENS_RE.test(basename(filePath))) return "tokens";
+  if (basename(filePath) === "design-system.md") return "sheet";
+  return null;
+}
+
+/**
+ * Per-mode corpus-read threshold (component >= 1 file, page >= 2 files,
+ * full = index + 3 tokens — C5: raised from 2, since 2 references still let
+ * an agent pattern-match by tonal affinity without ever opening the one
+ * reference that actually answered the brief). `"sheet"` reads (C6,
+ * `design-system.md`) never count toward this — only `TOKENS_RE` matches do.
+ */
+export function corpusReady(reads: readonly string[], mode: DesignMode): boolean {
+  if (mode === "component") return reads.length >= 1;
+  if (mode === "page") return reads.length >= 2;
+  return reads.includes("README.md") && reads.filter((r) => TOKENS_RE.test(basename(r))).length >= 3;
+}
+
+/** True when the content carries a `- Corpus: ref/section` citation line (form only). */
+export function hasCorpusCitation(content: string): boolean {
+  return citedCorpusRefs(content).length > 0;
+}
+
+/**
+ * Extract the reference slugs cited on EVERY `- Corpus:` line (token before
+ * `/`, or a bare slug). Anchored at line start with NO indentation
+ * (fail-closed: a citation inside a code block does not count — an indented
+ * match would also recognize the examples inside the doctrine doc itself).
+ * The regex is fence-blind, documented: a `- Corpus:` line at column 0 inside
+ * a fenced block WILL be matched — its refs must join like any other.
+ */
+export function citedCorpusRefs(content: string): string[] {
+  const refs: string[] = [];
+  for (const m of content.matchAll(CORPUS_LINE_RE)) {
+    const line = m[1] ?? "";
+    refs.push(...line.split(",").map((item) => item.trim().match(/^([\w][\w-]*)(?:\/|\s|$)/)?.[1] ?? "").filter(Boolean));
+  }
+  return refs;
+}
+
+/**
+ * True when the cited ref names a REFERENCE in a recorded corpus read, in
+ * either naming convention (`reve` README-style ↔ `reve-recode/` on disk —
+ * the `-recode` suffix is normalized away on BOTH sides) and either layout
+ * (per-reference directories, or flat `tokens-<ref>.md` files). Comparison is
+ * exact after normalization: no prefix matching, so `acme` never joins
+ * `acme-corp`, `tokens` never joins every tokens file, and `README` names no
+ * reference.
+ */
+export function citationJoinsReads(ref: string, reads: readonly string[]): boolean {
+  const norm = (s: string): string => s.replace(/\.md$/, "").replace(/-recode$/, "");
+  const target = norm(ref);
+  return reads.some((r) => {
+    const segs = r.split("/");
+    const file = segs[segs.length - 1] ?? "";
+    const names = segs.slice(0, -1).map(norm);
+    if (file.startsWith("tokens-")) names.push(norm(file.slice("tokens-".length)));
+    return names.includes(target);
+  });
+}