@fusengine/harness 0.1.90 → 0.1.91

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

package/src/policy/design/gates.ts

@@ -0,0 +1,87 @@
+import { basename } from "node:path";
+import type { Prompt } from "../../prompt/types";
+import { loadDesignState, type DesignState } from "./state";
+import { activeDesignAgent } from "./flag";
+import { isUiWrite } from "./skill-gate";
+import { SKILL_TRIGGERS } from "./skill-triggers";
+import { ALLOWED_WRITE, isAllowedWrite } from "./allowed-write";
+
+export { validateDesignSystem } from "./design-system-rules";
+export { ALLOWED_WRITE, isAllowedWrite } from "./allowed-write";
+
+export const EXEMPT_DIRS: readonly string[] = ["node_modules/", "dist/", "build/", ".claude/"];
+const NAV = "mcp__fuse-browser__browser_navigate";
+const SHOT = "mcp__fuse-browser__browser_screenshot";
+const GEMINI = "mcp__gemini-design__create_frontend";
+
+export const deny = (reason: string): Prompt => ({
+  kind: "block", title: "Design pipeline", reason,
+  actions: ["Follow the design pipeline phases (0→identity, 1→inspiration, 2→screenshots, 3→design-system, 4→generate) in order"],
+});
+
+/** Block the design agent from writing anything but .html/.css/.md/.json (+ motion*.js). */
+export function htmlCssOnlyGate(filePath: string): Prompt | null {
+  if (EXEMPT_DIRS.some((d) => filePath.includes(d)) || isAllowedWrite(filePath)) return null;
+  return deny(
+    "BLOCKED: design-expert can only write .html, .css, .json, .md, and motion*.js files. " +
+      "Framework files (.tsx, .astro, .vue, .swift, .php) must be written by the domain expert " +
+      "(astro-expert, react-expert, etc.) AFTER design validation.",
+  );
+}
+
+/** Block edits to the harness-managed `.design-state-*` files (read-only to the agent). */
+export function stateFileGate(filePath: string): Prompt | null {
+  return filePath.includes(".design-state-")
+    ? deny(
+        "BLOCKED: .design-state files are READ-ONLY for you. Hooks update them automatically as you progress. " +
+          "Do NOT try to modify them — it will not unblock you. Follow the pipeline: Phase 0→1→2→3→4→5→6 in order.",
+      )
+    : null;
+}
+
+/** Gate a screenshot: require a scroll since the last navigate (lazy-load content). */
+export function screenshotScrollGate(state: DesignState): Prompt | null {
+  return state.scrolledSinceNav
+    ? null
+    : deny("BLOCKED: scroll the page before a screenshot — browser_scroll to:'end', wait, scroll back, then fullPage screenshot.");
+}
+
+/** The Gemini design gates are OPT-IN: off unless `FUSE_DESIGN_GEMINI` is `1`/`true`. */
+export function geminiEnabled(): boolean {
+  const v = process.env.FUSE_DESIGN_GEMINI;
+  return v === "1" || v === "true";
+}
+
+/** Inputs for {@link designPassNotice} — primitives only, so policy stays runtime-free. */
+export interface PassNoticeInput { agentId: string; tool: string; filePath: string; content: string; url: string; phase: "pre" | "post" }
+
+/**
+ * Python-parity pass notices (`hook_output.allow_pass`/`post_pass`): the
+ * user-visible `script: detail` lines the old plugins printed on EVERY passing
+ * design hook. Call AFTER the gates allowed the event; returns an `inform`
+ * Prompt carrying only `userMessage` (for the human, never agent context), or
+ * null when nothing applies. The check-design-skill line fires for ANY agent
+ * on a UI write; the rest only inside the active design-agent context.
+ */
+export function designPassNotice(i: PassNoticeInput & { corpusMissing?: boolean }, cacheDir: string): Prompt | null {
+  const isWrite = i.tool === "Write" || i.tool === "Edit";
+  const fp = i.filePath;
+  const lines: string[] = [];
+  if (i.phase === "pre" && isUiWrite(i.tool, fp, i.content)) {
+    const domains = SKILL_TRIGGERS.filter((t) => t.patterns.some((re) => re.test(i.content))).map((t) => t.skill).join(", ");
+    lines.push(`check-design-skill: pass (domain: ${domains || "base"})`);
+  }
+  const state = i.agentId && activeDesignAgent(cacheDir) === i.agentId ? loadDesignState(cacheDir, i.agentId) : null;
+  if (state && i.phase === "pre") {
+    if (i.corpusMissing) lines.push("design-corpus: refs-design corpus not found — corpus requirement waived (screenshot-only fallback, install defect)");
+    if (isWrite && fp && !EXEMPT_DIRS.some((d) => fp.includes(d)) && ALLOWED_WRITE.test(fp)) lines.push(`enforce-html-css-only: allowed: ${basename(fp)}`);
+    if (i.tool === NAV) lines.push(`check-inspiration-read: pass (${i.url})`);
+    if (i.tool === GEMINI && geminiEnabled()) lines.push("validate-design-system: design-system.md ok");
+    if (isWrite || i.tool === NAV || i.tool === SHOT || i.tool === GEMINI) lines.push(`pipeline-gate: phase ${state.currentPhase} ok`);
+  }
+  if (state && i.phase === "post" && isWrite) {
+    if (basename(fp) === "design-system.md") lines.push("validate-design: design-system.md → phase 3");
+    else if (/\.(tsx|jsx|css)$/.test(fp)) lines.push("validate-design: design ok");
+  }
+  return lines.length ? { kind: "inform", title: "Design pipeline", reason: "", userMessage: lines.join("\n") } : null;
+}

package/src/policy/design/screenshot-tools.ts

@@ -0,0 +1,24 @@
+/**
+ * @module screenshot-tools
+ * Screenshot-credit tool set (C1), split out of `runtime/design-helpers.ts` to
+ * keep that file within the SOLID size budget (SRP).
+ * @packageDocumentation
+ */
+
+/**
+ * Screenshot-credit tools: the single-shot capture PLUS the two fuse-browser
+ * batch capture primitives (`browser_shots_batch`, `browser_site_shots`) — a
+ * batch call that captures N urls/viewports must credit the quota too, or
+ * capturing efficiently would make the quota infranchissable. LIMITATION
+ * (deliberate, documented): this repo's cross-harness `NormalizedEvent` (see
+ * `runtime/normalize.ts`) never surfaces `tool_response` for any tool — by
+ * design, since its shape is undocumented for MCP tools and harness-specific
+ * for built-ins — so no per-call item count reaches this gate. A batch call
+ * therefore credits EXACTLY 1, same as a unit screenshot, never the N it may
+ * have captured.
+ */
+export const SHOT_TOOLS: ReadonlySet<string> = new Set([
+  "mcp__fuse-browser__browser_screenshot",
+  "mcp__fuse-browser__browser_shots_batch",
+  "mcp__fuse-browser__browser_site_shots",
+]);

package/src/policy/design/skill-evidence.ts

@@ -0,0 +1,34 @@
+/**
+ * @module design/skill-evidence
+ * IO side of the UI design-skill gate: read the verified session track and
+ * derive {@link DesignEvidence} (read references + doc-consulted) for
+ * {@link uiDesignSkillGate}. Kept separate from the pure gate logic (SRP).
+ * @packageDocumentation
+ */
+import type { SessionTrack } from "../../tracking/session-state";
+import { trackJournalEnabled } from "../../tracking/store";
+import { readTrackSync } from "../../tracking/track-compact";
+import { defaultStateDir, trackFile } from "../../runtime/paths";
+import { isDocConsulted } from "../../freshness/doc-helpers";
+import type { DesignEvidence } from "./skill-gate";
+
+/**
+ * Read the verified session track (snapshot ⊕ journal) and derive
+ * {@link DesignEvidence}. Fail-closed on a missing/corrupt/tampered track (no
+ * evidence → the gate blocks).
+ * @param sessionId - the Claude session id.
+ * @param cwd - the project root (selects the per-project state dir).
+ * @param baseDir - override the track base dir (tests); defaults to the project state dir.
+ */
+export function collectDesignEvidence(sessionId: string, cwd: string, baseDir: string = defaultStateDir(cwd)): DesignEvidence {
+  let track: SessionTrack | null = null;
+  try {
+    track = readTrackSync(trackFile(sessionId, baseDir), trackJournalEnabled());
+  } catch {
+    track = null;
+  }
+  return {
+    refsRead: track?.refsRead ?? [],
+    docConsulted: track ? isDocConsulted(track.authorizations, sessionId) : false,
+  };
+}

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

@@ -0,0 +1,81 @@
+/**
+ * @module design/skill-gate
+ * UI design-skill gate — ports `check-design-skill.py` WITHOUT requiring Gemini.
+ *
+ * Fires for ANY agent writing a UI file (.tsx/.jsx/.scss/.vue/.svelte) in a
+ * UI-ish path (or with Tailwind classes). Blocks unless BOTH: (1) a design skill
+ * reference was read this session (reuses the `refsRead` track), and (2) both
+ * Context7 AND Exa were consulted via {@link isDocConsulted}.
+ * Gemini is NEVER a condition — doc research alone satisfies the gate.
+ * @packageDocumentation
+ */
+import type { Prompt } from "../../prompt/types";
+import { missingDomainSkills } from "./skill-triggers";
+
+/** UI source files the gate polices (.html/.css are handled by the pipeline gate, not here). */
+const UI_FILE_RE = /\.(tsx|jsx|scss|vue|svelte)$/;
+/** Generated/vendored paths that never need a design skill (match at start or mid-path). */
+const EXEMPT_RE = /(^|\/)(node_modules|dist|build)\/|\.claude\//;
+/** UI-intent path fragments (ports the Python `UI_PATH_PATTERNS`). */
+const UI_PATH_RE = /(components|ui|styles|page|layout|content|view|feature|section|hero|footer|header|sidebar|nav|modal|dialog)/;
+/** Tailwind utility usage in JSX `className` (ports the Python `has_jsx_tailwind`). */
+const TAILWIND_RE = /className\s*=.*(?:flex|grid|p-|m-|bg-|text-|rounded|shadow|border|gap-|w-|h-)/;
+/** A read reference path that counts as "a design skill was consulted". */
+const DESIGN_SKILL_RE = /skills\/(design-method|design-system|design-web|design-webapp|design-motion|design-review|ux-copy|design-ios|design-android)/i;
+
+/** Session evidence the gate consumes: read references + whether docs were consulted. */
+export interface DesignEvidence {
+  refsRead: readonly string[];
+  docConsulted: boolean;
+}
+
+/** True when this Write/Edit targets a UI file in a UI-ish path or with Tailwind classes. */
+export function isUiWrite(tool: string, filePath: string, content: string): boolean {
+  if (tool !== "Write" && tool !== "Edit") return false;
+  if (!UI_FILE_RE.test(filePath) || EXEMPT_RE.test(filePath)) return false;
+  return UI_PATH_RE.test(filePath) || TAILWIND_RE.test(content);
+}
+
+/** True when a design skill reference was read this session (scans the `refsRead` track). */
+export function designSkillRead(refsRead: readonly string[]): boolean {
+  return refsRead.some((p) => DESIGN_SKILL_RE.test(p));
+}
+
+const block = (reason: string, action: string): Prompt => ({
+  kind: "block", title: "Design skill", reason, actions: [action],
+});
+
+/**
+ * Gate a UI write: require a design-skill read AND any doc source. Returns a
+ * blocking {@link Prompt}, or `null` to allow. NEVER requires Gemini.
+ * @param tool - the tool name ("Write" | "Edit" | ...).
+ * @param filePath - the written file path.
+ * @param content - the written content (snippet on Edit, full file on Write).
+ * @param ev - the session evidence (refsRead + docConsulted).
+ */
+export function uiDesignSkillGate(tool: string, filePath: string, content: string, ev: DesignEvidence): Prompt | null {
+  if (!isUiWrite(tool, filePath, content)) return null;
+  if (!designSkillRead(ev.refsRead)) {
+    return block(
+      "BLOCKED: design skill not consulted before writing UI. Read a design SKILL.md "
+      + "(design-system, design-web, or design-motion), then retry.",
+      "Read a design skill reference, then retry",
+    );
+  }
+  const missing = missingDomainSkills(content, ev.refsRead);
+  if (missing.length) {
+    return block(
+      `BLOCKED: code uses ${missing.join(", ")} but the matching design skill(s) were not consulted. `
+      + `Read the SKILL.md FILE (with the Read tool) for: ${missing.join(", ")}, then retry.`,
+      `Read design skill(s): ${missing.join(", ")}, then retry`,
+    );
+  }
+  if (!ev.docConsulted) {
+    return block(
+      "BLOCKED: no documentation consulted. Use BOTH mcp__context7__query-docs AND "
+      + "mcp__exa__web_search_exa, or a web fallback alone (WebSearch/WebFetch). Gemini is NOT required.",
+      "Consult Context7+Exa, or web docs alone (Gemini not required), then retry",
+    );
+  }
+  return null;
+}

package/src/policy/design/skill-triggers.ts

@@ -0,0 +1,51 @@
+/**
+ * @module design/skill-triggers
+ * Domain-specific design-skill detection: maps written code patterns to the
+ * precise design SKILL.md that must have been consulted. Ports the Python
+ * `design_skill_triggers.py` `SKILL_TRIGGERS` table + `detect_required_skills`.
+ * @packageDocumentation
+ */
+
+/** A domain skill + the code patterns that require it + its `refsRead` path fragment. */
+export interface SkillTrigger {
+  /** Skill id for the block message, e.g. "design-motion". */
+  skill: string;
+  /** Path fragment proving the skill was read (matched against `refsRead`). */
+  readFragment: string;
+  /** Code patterns that trigger the requirement (case-insensitive). */
+  patterns: readonly RegExp[];
+}
+
+/** Domain skill triggers (ported 1:1 from `design_skill_triggers.py`). */
+export const SKILL_TRIGGERS: readonly SkillTrigger[] = [
+  { skill: "design-web", readFragment: "design-web", patterns: [
+    /className\s*=\s*["{]/i, /<(div|section|main|header|footer|nav|aside)\s/i,
+    /flex|grid|gap-|p-|m-|bg-|text-|rounded|shadow|border/i,
+    /(Button|Card|Dialog|Sheet|Input|Select|Table)\b/i,
+    /cva|class-variance-authority|variants\b/i, /VariantProps|variant.*:\s*\{/i,
+    /children|slots|asChild|Slot|render.?prop/i, /forwardRef|React\.cloneElement|compound/i,
+  ] },
+  { skill: "design-system", readFragment: "design-system", patterns: [
+    /--(\w+-)+color:|:root\s*\{|@theme\b/i, /design.?system|token|palette|typography.?scale/i,
+    /--(\w+)-(foreground|background|primary|muted|accent):/i, /cssVariables|themeConfig|colorScheme/i,
+    /dark:|prefers-color-scheme|next-themes|useTheme/i, /ThemeProvider|data-theme|color-scheme/i,
+    /sm:|md:|lg:|xl:|2xl:/i, /@container|container-type|@media/i, /clamp\(|fluid|min-width:/i,
+  ] },
+  { skill: "design-motion", readFragment: "design-motion", patterns: [
+    /motion\.|framer-motion|animate|variants/i, /whileHover|whileTap|AnimatePresence|transition/i,
+    /@keyframes\b|animation:\s/i, /backdrop-blur|bg-.*\/([\d]+)|glass/i, /backdrop-filter:\s*blur/i,
+    /hover:|focus:|active:|disabled:|focus-visible:/i, /data-\[state=|data-\[disabled\]/i,
+    /bg-gradient|from-|via-|to-/i, /radial-gradient|conic-gradient|bg-\[url/i, /blur-.*xl|opacity-|mix-blend/i,
+  ] },
+  { skill: "design-review", readFragment: "design-review", patterns: [
+    /aria-|role=|sr-only|tabIndex|alt=/i, /WCAG|a11y|contrast|screen.?reader/i,
+  ] },
+];
+
+/** Return the domain skills required by `content` but NOT present in `refsRead`. */
+export function missingDomainSkills(content: string, refsRead: readonly string[]): string[] {
+  return SKILL_TRIGGERS
+    .filter((t) => t.patterns.some((re) => re.test(content)))
+    .filter((t) => !refsRead.some((p) => p.includes(t.readFragment)))
+    .map((t) => t.skill);
+}

package/src/policy/design/state.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, renameSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWrite } from "../../util/json-io";
+
+/** Pipeline mode — drives the screenshot quota and phase expectations. */
+export type DesignMode = "full" | "page" | "component";
+
+/** The design-agent pipeline state-machine snapshot (phases 0→4). */
+export interface DesignState {
+  agentId: string;
+  mode: DesignMode;
+  currentPhase: number;
+  phasesCompleted: string[];
+  inspirationRead: boolean;
+  scrolledSinceNav: boolean;
+  screenshotsCount: number;
+  /** Distinct refs-design files read (paths relative to the corpus root), deduped. */
+  corpusReads: string[];
+  designSystemExists: boolean;
+  designSystemValid: boolean;
+  geminiCalls: number;
+}
+
+/** Minimum fuse-browser screenshots required before writing design-system.md, per mode (corpus present). */
+export const MIN_SCREENSHOTS: Readonly<Record<DesignMode, number>> = { full: 2, page: 1, component: 1 };
+
+/**
+ * Screenshot quotas when the refs-design corpus is ABSENT (install defect →
+ * fail-open): exactly today's effective behavior, so the fallback can never be
+ * weaker than the pre-doctrine gate. Component is 1 explicitly — the effective
+ * quota today (the first screenshot trips `1 >= 0`), no longer a hidden quirk.
+ */
+export const MIN_SCREENSHOTS_NO_CORPUS: Readonly<Record<DesignMode, number>> = { full: 4, page: 2, component: 1 };
+
+/** Screenshot quota for `mode` — the SINGLE choice point between the two tables, driven by corpus availability. */
+export function quotaFor(mode: DesignMode, corpusRequired: boolean): number {
+  return (corpusRequired ? MIN_SCREENSHOTS : MIN_SCREENSHOTS_NO_CORPUS)[mode];
+}
+
+const stateFile = (cacheDir: string, agentId: string): string => join(cacheDir, `.design-state-${agentId}.json`);
+
+/** Load the design state for `agentId`, or null when absent/corrupt (fail-open). */
+export function loadDesignState(cacheDir: string, agentId: string): DesignState | null {
+  const path = stateFile(cacheDir, agentId);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as DesignState;
+    // Retrocompat: states persisted before corpusReads existed load with an
+    // empty list (never undefined — an undefined count would silently
+    // fail-open or fail-closed the corpus conjunction downstream).
+    return { ...parsed, corpusReads: parsed.corpusReads ?? [] };
+  } catch {
+    return null;
+  }
+}
+
+/** Persist the design state under its agent id. */
+export function saveDesignState(cacheDir: string, state: DesignState): void {
+  atomicWrite(stateFile(cacheDir, state.agentId), JSON.stringify(state, null, 2));
+}
+
+/** Build the initial state for a design agent starting a run. */
+export function initDesignState(agentId: string, mode: DesignMode, designSystemExists: boolean): DesignState {
+  return {
+    agentId, mode, currentPhase: 0, phasesCompleted: [], inspirationRead: false,
+    scrolledSinceNav: false, screenshotsCount: 0, corpusReads: [], designSystemExists, designSystemValid: false, geminiCalls: 0,
+  };
+}
+
+/** Archive the active state file (timestamp suffix) and drop archives older than 7 days. */
+export function cleanupDesignStates(cacheDir: string, agentId: string, stamp: string, now: number): void {
+  if (agentId) {
+    const src = stateFile(cacheDir, agentId);
+    if (existsSync(src)) renameSync(src, join(cacheDir, `.design-state-${agentId}-${stamp}.json`));
+  }
+  let entries: string[];
+  try {
+    entries = readdirSync(cacheDir);
+  } catch {
+    return;
+  }
+  const cutoff = now - 7 * 86_400_000;
+  for (const name of entries) {
+    if (!name.startsWith(".design-state-")) continue;
+    const path = join(cacheDir, name);
+    try {
+      if (statSync(path).mtimeMs < cutoff) rmSync(path);
+    } catch {
+      /* ignore unlink races */
+    }
+  }
+}

package/src/policy/design/template-urls.ts

@@ -0,0 +1,54 @@
+/**
+ * Template-platform detection for the phase-1 navigate gate
+ * (design-inspiration.md §FORBIDDEN Navigation Targets). Two rules, because
+ * neither alone matches the doctrine:
+ *  - template SHOPS are banned outright, on the host (subdomains included);
+ *  - the path rule (/templates, /themes) applies ONLY to real product
+ *    platforms that also host a template catalog — never to the whole web,
+ *    or sothebys.com/en/marketplace (register research) would be denied.
+ * The host is normalized (lowercase, port, userinfo, trailing dot stripped).
+ * HONEST SCOPE: this is a LEXICAL filter — it follows no redirect, is not and
+ * will never be exhaustive, and it is NOT the taste gate: the source of taste
+ * is the refs-design corpus. This list exists to catch the reflex, not to map
+ * the template economy. Frozen by owner decision (C5): no host or pattern may
+ * be added or removed without re-opening that decision.
+ * Award galleries are deliberately absent: they pass, as outbound-link finders.
+ */
+
+/** Template shops: banned outright, any path (subdomains included). */
+const TEMPLATE_HOSTS: readonly string[] = [
+  "themeforest.net", "themes.shopify.com", "marketplace.atlassian.com",
+  "templatemonster.com", "creativemarket.com", "ui8.net", "html5up.net",
+  "colorlib.com", "bootstrapmade.com", "startbootstrap.com", "cruip.com",
+  "uideck.com", "envato.com", "tailwindui.com",
+];
+
+/** Real-product platforms whose template CATALOGS are banned via the path rule. */
+const PLATFORM_HOSTS: readonly string[] = [
+  "framer.com", "webflow.com", "vercel.com", "astro.build", "squarespace.com", "wix.com",
+];
+
+/**
+ * Template-catalog path segments — evaluated ONLY on PLATFORM_HOSTS, and
+ * deliberately WITHOUT `/marketplace`: those platforms run real, non-template
+ * marketplaces (vercel.com/marketplace is infra). Atlassian/Shopify template
+ * stores are already covered by the full host ban above.
+ */
+const TEMPLATE_PATH_RE = /^\/(templates|themes)(\/|$)/i;
+
+/** Host part of `url`, normalized: lowercase, no port, no userinfo, no trailing dot. */
+function hostOf(url: string): string {
+  return (/^https?:\/\/(?:[^@/?#]*@)?([^/:?#]+)/i.exec(url)?.[1] ?? "").replace(/\.$/, "").toLowerCase();
+}
+
+const under = (host: string, domain: string): boolean => host === domain || host.endsWith(`.${domain}`);
+
+/** True when `url` points at a banned template source (host rule, then platform path rule). */
+export function isTemplateUrl(url: string): boolean {
+  const host = hostOf(url);
+  if (!host) return false;
+  if (TEMPLATE_HOSTS.some((d) => under(host, d))) return true;
+  if (!PLATFORM_HOSTS.some((d) => under(host, d))) return false;
+  const path = /^https?:\/\/(?:[^@/?#]*@)?[^/?#]*(\/[^?#]*)/i.exec(url)?.[1] ?? "/";
+  return TEMPLATE_PATH_RE.test(path);
+}