@fusengine/harness 0.1.90 → 0.1.92

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

package/src/policy/design/design-system-rules.ts

@@ -0,0 +1,45 @@
+/**
+ * Content rules for design-system.md — the four hard requirements the
+ * pipeline validates on the nominal write path (and the opt-in Gemini one).
+ * Split out of `gates.ts` to keep both files within the SOLID size budget.
+ */
+import { hasCorpusCitation } from "./corpus";
+
+const OKLCH_RE = /oklch\(\s*[\d.]+%?\s+0\.0*[1-9]/;
+
+/**
+ * Forbidden fonts, matched in USAGE contexts — never in free prose: a design
+ * system may SAY "Inter" ("## Interaction states", "we never use Inter"), it
+ * may not USE it as a font. Covered forms: CSS declarations (`font:`,
+ * `font-family:` in any case, multiline values), JS config (`fontFamily:`),
+ * custom properties named in English (`--*font*`/`--*ff*`/`--*type*`, value
+ * unquoted or quoted), ANY custom property whose value quotes a forbidden
+ * name (`--police-texte: "Inter", …` — a non-English property name has no
+ * keyword to key off, so the quote itself is the usage signal: a quoted
+ * token in a `--*` value is a font-family entry, not prose), `@import`
+ * URLs, and Markdown table cells (`| Body | Inter |`). Explicitly OUT of
+ * scope (chosen, not overlooked): unquoted prose in bullet lines —
+ * distinguishing "usage" from "mention" there is prose parsing, not a
+ * regex's job. Accepted trade-off of the quote signal: `--comment: "we
+ * never use Inter"` is flagged too — a quoted mention reads identically to
+ * a quoted usage once the property name carries no keyword to disambiguate.
+ */
+const FONT_DECL_RE = /(?:font(?:-family)?|fontFamily|--[\w-]*(?:font|ff|type)[\w-]*)\s*:[^;\n]*(?:\n\s*)?[^;\n]*\b(?:Inter|Roboto|Arial|Open Sans)\b/i;
+const FONT_IMPORT_RE = /family=[^&"')]*\b(?:Inter|Roboto|Arial|Open Sans)\b/i;
+const FONT_TABLE_RE = /\|\s*\*{0,2}(?:Inter|Roboto|Arial|Open Sans)\*{0,2}\s*\|/;
+const FONT_QUOTED_PROP_RE = /--[\w-]+\s*:[^;\n]*["'][^;\n]*(?:\n\s*)?[^;\n]*\b(?:Inter|Roboto|Arial|Open Sans)\b/i;
+
+/**
+ * Return the requirements missing from a design-system.md (empty = valid).
+ * The corpus citation satisfies the source requirement ONLY when the corpus
+ * is actually delivered (`corpusCitationOk`) — absent corpus, the URL is
+ * mandatory again, exactly the pre-doctrine behavior (fallback never weaker).
+ */
+export function validateDesignSystem(content: string, corpusCitationOk = false): string[] {
+  const missing: string[] = [];
+  if (!content.includes("## Design Reference")) missing.push("## Design Reference section");
+  if (!/https?:\/\//.test(content) && !(corpusCitationOk && hasCorpusCitation(content))) missing.push("reference URL (https://…) or Corpus citation");
+  if (!OKLCH_RE.test(content)) missing.push("oklch() color with chroma > 0");
+  if (FONT_DECL_RE.test(content) || FONT_IMPORT_RE.test(content) || FONT_TABLE_RE.test(content) || FONT_QUOTED_PROP_RE.test(content)) missing.push("forbidden font (Inter/Roboto/Arial/Open Sans)");
+  return missing;
+}

package/src/policy/design/flag.ts

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const flagPath = (cacheDir: string): string => join(cacheDir, "design-agent-active");
+
+/** The active design agent id (the flag), or "" when no design agent is running. */
+export function activeDesignAgent(cacheDir: string): string {
+  const path = flagPath(cacheDir);
+  if (!existsSync(path)) return "";
+  try {
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Mark a design agent active (writes its id to the flag file). */
+export function setActiveDesignAgent(cacheDir: string, agentId: string): void {
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(flagPath(cacheDir), agentId);
+}
+
+/** Clear the active-design-agent flag. */
+export function clearActiveDesignAgent(cacheDir: string): void {
+  try {
+    rmSync(flagPath(cacheDir));
+  } catch {
+    /* already absent */
+  }
+}

package/src/policy/design/gates-pipeline.ts

@@ -0,0 +1,105 @@
+import type { Prompt } from "../../prompt/types";
+import { type DesignState, quotaFor } from "./state";
+import { PLUGINS_DIR } from "../file-size";
+import { deny } from "./gates";
+import { isTemplateUrl } from "./template-urls";
+
+const SKILLS = `${PLUGINS_DIR}/design-expert/skills`;
+
+/** Gate writing design-system.md: requires phase >= 2 and the per-mode screenshot quota. */
+export function designSystemWriteGate(filePath: string, state: DesignState, corpusRequired = false): Prompt | null {
+  if (!filePath.endsWith("design-system.md")) return null;
+  if (state.currentPhase < 2) {
+    return deny(
+      `BLOCKED: Cannot write design-system.md at phase ${state.currentPhase}. ` +
+        "RECOVERY: 1) Read identity templates from skills/design-system/ " +
+        "2) Read design-inspiration.md 3) Read the refs-design corpus (README.md + relevant tokens-*.md) with the Read tool " +
+        "4) Screenshot real sector sites with mcp__fuse-browser__browser_screenshot on a LIVE session " +
+        "(browser_shots_batch/browser_site_shots also count, 1 credit per call) " +
+        "5) Then write design-system.md",
+    );
+  }
+  const needed = quotaFor(state.mode, corpusRequired);
+  if (state.screenshotsCount < needed) {
+    return deny(
+      `BLOCKED: ${state.screenshotsCount}/${needed} screenshots for mode '${state.mode}'. ` +
+        `RECOVERY: 1) Read the refs-design corpus (README.md + tokens-*.md) if not done ` +
+        `2) Take ${needed - state.screenshotsCount} more screenshots of REAL sector sites with ` +
+        "mcp__fuse-browser__browser_screenshot (browser_shots_batch/browser_site_shots also count, 1 credit per call) " +
+        "3) Use browser_open + browser_navigate + browser_screenshot fullPage:true 4) Then write design-system.md",
+    );
+  }
+  return null;
+}
+
+/**
+ * Gate writing .html/.css: PIPELINE gate (never `uiDesignSkillGate`/`UI_FILE_RE`
+ * — owner-scoped out of the skill gate's remit). Requires phase >= 3 AND
+ * designSystemValid (same two-condition defense as {@link geminiCreateGate})
+ * AND `designSystemFileExists` (caller-computed via `findDesignSystem` — a
+ * state can say phase 3 after the file was later deleted, or the file can
+ * exist while a fresh agent's state is still phase 0).
+ */
+export function htmlCssPipelineGate(filePath: string, state: DesignState, designSystemFileExists: boolean): Prompt | null {
+  if (!/\.(html|css)$/.test(filePath)) return null;
+  if (state.currentPhase >= 3 && state.designSystemValid && designSystemFileExists) return null;
+  const gaps: string[] = [];
+  if (state.currentPhase < 3) gaps.push(`phase ${state.currentPhase}/3`);
+  if (!state.designSystemValid) gaps.push("design-system.md not validated");
+  if (!designSystemFileExists) gaps.push("design-system.md not found on disk");
+  return deny(
+    `BLOCKED: cannot write '${filePath}' before the design-system pipeline is complete (${gaps.join(", ")}). ` +
+      "RECOVERY: 1) Read identity templates from skills/design-system/ 2) Read design-inspiration.md " +
+      "3) Read the refs-design corpus with the Read tool 4) Screenshot real sector sites with " +
+      "mcp__fuse-browser__browser_screenshot on a LIVE session 5) Write a valid design-system.md " +
+      "6) Then write .html/.css",
+  );
+}
+
+/** Gate Gemini create_frontend: requires phase >= 3 and a validated design system. */
+export function geminiCreateGate(state: DesignState): Prompt | null {
+  if (state.currentPhase < 3) {
+    return deny(
+      "BLOCKED: Cannot call Gemini create_frontend before phase 3. " +
+        "RECOVERY: 1) Complete the inspiration phase (refs-design corpus + sector screenshots) 2) Write a valid design-system.md " +
+        "3) Then call mcp__gemini-design__create_frontend",
+    );
+  }
+  if (!state.designSystemValid) {
+    return deny(
+      "BLOCKED: design-system.md not validated. " +
+        "RECOVERY: 1) Ensure design-system.md has ## Design Reference, OKLCH tokens, typography pair, reference URL or Corpus citation " +
+        "2) Then retry mcp__gemini-design__create_frontend",
+    );
+  }
+  return null;
+}
+
+/**
+ * Gate fuse-browser navigate: phase >= 1, inspiration read, no template source in phase 1.
+ * The allowlist→denylist inversion is the DELIBERATE doctrine change (not a
+ * weakening): the gate was never the proof — the mandatory screenshot is,
+ * unchanged and unforgeable in both configurations. Corpus-absent has its
+ * counterpart already (pre-doctrine quotas + visible warning); what the
+ * denylist cannot cover (sector-browse quality) belongs to the doc, per the
+ * rule "the gate requires what is verifiable, the doc prescribes zeal".
+ */
+export function browserNavigateGate(state: DesignState, url: string): Prompt | null {
+  if (state.currentPhase < 1) {
+    return deny(`BLOCKED: Phase 0 not done. READ: ${SKILLS}/design-system/SKILL.md first.`);
+  }
+  if (!state.inspirationRead) {
+    return deny(
+      `BLOCKED: Read the inspiration doctrine first. READ: ${SKILLS}/design-web/references/design-inspiration.md, then the refs-design corpus (README.md + relevant tokens-*.md) with the Read tool`,
+    );
+  }
+  if (state.currentPhase === 1 && url && isTemplateUrl(url)) {
+    return deny(
+      `BLOCKED: '${url}' is a template source — templates are BUILT to be interchangeable, ` +
+        "so extracting taste from them converges every page to the same body. " +
+        "RECOVERY: 1) taste comes from the refs-design corpus (README.md + relevant tokens-*.md) " +
+        "2) browse 1-2 REAL sites in the client's sector, for register only (award galleries are fine as outbound-link finders)",
+    );
+  }
+  return null;
+}