@fusengine/harness 0.1.90 → 0.1.92

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

package/src/policy/design/transitions.ts

@@ -0,0 +1,68 @@
+import { type DesignState, type DesignMode, quotaFor } from "./state";
+import { corpusReady } from "./corpus";
+
+/** Infer the pipeline mode from the launch prompt + whether a design-system.md already exists. */
+export function detectMode(prompt: string, designSystemExists: boolean): DesignMode {
+  const p = prompt.toLowerCase();
+  if (["component", "composant", "snippet"].some((k) => p.includes(k))) return "component";
+  return designSystemExists ? "page" : "full";
+}
+
+/**
+ * Re-evaluate the phase-2 conjunction MONOTONICALLY: corpus reads (when the
+ * corpus is delivered) AND the screenshot quota must both hold, and the phase
+ * is never written downwards (a Read after phase 3 changes nothing).
+ */
+function maybePhase2(state: DesignState, corpusRequired: boolean): DesignState {
+  if (state.currentPhase >= 2) return state;
+  const corpusOk = !corpusRequired || corpusReady(state.corpusReads, state.mode);
+  if (!corpusOk || state.screenshotsCount < quotaFor(state.mode, corpusRequired)) return state;
+  return { ...state, currentPhase: 2, phasesCompleted: [...new Set([...state.phasesCompleted, "identity", "research"])] };
+}
+
+/** Record a screenshot: bump the count, then re-evaluate the phase-2 conjunction. */
+export function recordScreenshot(state: DesignState, corpusRequired: boolean): DesignState {
+  return maybePhase2({ ...state, screenshotsCount: state.screenshotsCount + 1 }, corpusRequired);
+}
+
+/** Record a fuse-browser navigate (resets the scroll-before-screenshot guard). */
+export function recordNavigate(state: DesignState): DesignState {
+  return { ...state, scrolledSinceNav: false };
+}
+
+/** Record a fuse-browser scroll (satisfies the scroll-before-screenshot guard). */
+export function recordScroll(state: DesignState): DesignState {
+  return { ...state, scrolledSinceNav: true };
+}
+
+/** Mark the design system validated and advance to phase 3 (after a passing create_frontend check). */
+export function recordValidDesignSystem(state: DesignState): DesignState {
+  return {
+    ...state, designSystemExists: true, designSystemValid: true,
+    currentPhase: Math.max(state.currentPhase, 3),
+    phasesCompleted: [...new Set([...state.phasesCompleted, "design-system"])],
+  };
+}
+
+/**
+ * Record a corpus read: distinct files only (a re-read never inflates the
+ * list), then re-evaluate the phase-2 conjunction. `relPath` is relative to
+ * the corpus root, keeping the persisted state small and prefix-independent.
+ */
+export function recordCorpusRead(state: DesignState, relPath: string, corpusRequired: boolean): DesignState {
+  return maybePhase2({ ...state, corpusReads: [...new Set([...state.corpusReads, relPath])] }, corpusRequired);
+}
+
+/**
+ * Record a skill-file Read: reading the identity templates enters phase 1 (browsing
+ * allowed); reading the inspiration catalog satisfies the browse prerequisite.
+ */
+export function recordRead(state: DesignState, filePath: string, corpusRequired = false): DesignState {
+  const next: DesignState = { ...state };
+  if (filePath.includes("design-system/SKILL.md")) {
+    next.currentPhase = Math.max(state.currentPhase, 1);
+    next.phasesCompleted = [...new Set([...state.phasesCompleted, "identity"])];
+  }
+  if (filePath.includes("design-inspiration")) next.inspirationRead = true;
+  return maybePhase2(next, corpusRequired);
+}

package/src/policy/detect-claude-md-project-type.ts

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ProjectType } from "./detect-project";
+
+/**
+ * Detect the project type from the cwd, reproducing the legacy Python logic:
+ * package.json containing "next" → nextjs, else "react" → react; else
+ * composer.json+artisan → laravel; else Package.swift / *.xcodeproj → swift;
+ * else generic.
+ * @param cwd - Project root to scan.
+ * @returns The detected project type label.
+ */
+export function detectClaudeMdProjectType(cwd: string): ProjectType {
+  const pkg = join(cwd, "package.json");
+  if (existsSync(pkg)) {
+    try {
+      const content = readFileSync(pkg, "utf-8");
+      if (content.includes("next")) return "nextjs";
+      if (content.includes("react")) return "react";
+    } catch {
+      /* unreadable package.json → fall through */
+    }
+  }
+  if (existsSync(join(cwd, "composer.json")) && existsSync(join(cwd, "artisan"))) return "laravel";
+  if (existsSync(join(cwd, "Package.swift"))) return "swift";
+  try {
+    if (readdirSync(cwd).some((f) => f.endsWith(".xcodeproj"))) return "swift";
+  } catch {
+    /* unreadable dir → ignore */
+  }
+  return "generic";
+}

package/src/policy/detect-framework.ts

@@ -0,0 +1,99 @@
+import { dirname, resolve } from "node:path";
+import { maskCommentsAndStrings } from "./conventions/strip";
+import { nearestManifestDir, projectCaps, type Cap } from "./nearest-manifest";
+
+/** File-derived signal: a definitive non-JS framework, or a JS-family hint. */
+interface FileSignal {
+  /** Definitive framework from extension/content (non-JS) — wins outright. */
+  definitive?: string;
+  /** JS-family hint needing project caps to confirm (react/nextjs/tanstack-start). */
+  jsHint?: "react" | "nextjs" | "tanstack-start";
+}
+
+/** react markers in a plain .ts/.js file (avoids TS-generic false positives). */
+const REACT_CONTENT = /from ['"]react['"]|\buse(State|Effect|Context|Ref|Memo|Callback|Reducer|LayoutEffect)\b|className=/;
+/** next.js markers in content. */
+const NEXT_CONTENT = /use client|use server|NextRequest|NextResponse|from ['"]next|getServerSideProps|getStaticProps/;
+/** next.js route-file conventions. */
+const NEXT_ROUTE = /(page|layout|loading|error|route|middleware)\.(ts|tsx|js|jsx)$/;
+/** TanStack Start markers (file routes, server fns, start/router imports). */
+const TANSTACK_CONTENT = /createFileRoute|createServerFn|from ['"]@tanstack\/react-(start|router)/;
+/**
+ * C7: Tailwind CSS-file signals, verified against official docs (v3 + v4) —
+ * `@tailwind` (v3 layer directive, removed in v4), `@apply` (both versions),
+ * `@config` (v3 native / v4 compat, JS config path), `@source` (v4 content
+ * globbing), `@theme` (v4 design-token block), `theme(` (the function, both
+ * versions' syntax). Deliberately NOT a bare utility-class-in-selector scan
+ * (e.g. `.flex{}`) — an ordinary hand-written class named `.flex` is exactly
+ * the false-positive shape this fix removes; only genuine Tailwind-specific
+ * at-rules/functions count.
+ */
+const TAILWIND_CSS_CONTENT = /@tailwind\b|@apply\b|@config\b|@source\b|@theme\b|\btheme\(/;
+
+/** Derive the raw signal an extension + content carry (no filesystem access). */
+function fileSignal(filePath: string, content: string): FileSignal {
+  if (/\.swift$/.test(filePath)) return { definitive: "swift" };
+  if (/\.php$/.test(filePath)) return { definitive: "laravel" };
+  if (/\.java$/.test(filePath)) return { definitive: "java" };
+  if (/\.go$/.test(filePath)) return { definitive: "go" };
+  if (/\.rb$/.test(filePath)) return { definitive: "ruby" };
+  if (/\.rs$/.test(filePath)) return { definitive: "rust" };
+  // C7: a .css file is "tailwind" only when its CONTENT shows it — bare
+  // extension used to classify EVERY .css as tailwind, forcing 6 unrelated
+  // skill reads on hand-written CSS. Empty content (file-size-scope.ts's
+  // caller) can never prove Tailwind usage, so it falls through to the
+  // JS-family checks below (all false for .css) and returns "generic" — the
+  // function's existing fail-open contract, not a special case. That caller
+  // never reaches here in practice: .css is already outside its
+  // FILE_SIZE_CODE_EXT scope, so this is inert there either way.
+  if (/\.css$/.test(filePath) && TAILWIND_CSS_CONTENT.test(content)) return { definitive: "tailwind" };
+  // JS branch: content signals ride MASKED content (a `// migrated from
+  // createServerFn pattern` comment must not flip nextjs → tanstack-start).
+  const masked = maskCommentsAndStrings(content, "c");
+  const isTs = TANSTACK_CONTENT.test(masked);
+  const isNext = !isTs && (NEXT_ROUTE.test(filePath) || NEXT_CONTENT.test(masked));
+  if (/\.(tsx|jsx)$/.test(filePath)) return { jsHint: isTs ? "tanstack-start" : isNext ? "nextjs" : "react" };
+  if (/\.(ts|js)$/.test(filePath)) {
+    if (isTs) return { jsHint: "tanstack-start" };
+    if (isNext) return { jsHint: "nextjs" };
+    if (REACT_CONTENT.test(masked)) return { jsHint: "react" };
+  }
+  return {};
+}
+
+/** Reconcile the JS signal against the project's REAL capabilities. */
+function reconcile(caps: Set<Cap>, hint: "react" | "nextjs" | "tanstack-start"): string {
+  const nextCap = caps.has("nextjs");
+  const reactCap = caps.has("react") || nextCap; // next always ships react at runtime
+  if (hint === "tanstack-start") {
+    return caps.has("tanstack-start") || caps.has("tanstack-router") ? "tanstack-start" : reactCap ? "react" : "generic";
+  }
+  if (hint === "nextjs") return nextCap ? "nextjs" : reactCap ? "react" : "generic";
+  return reactCap ? "react" : "generic";
+}
+
+/**
+ * Detect a file's framework as the intersection of the REAL project (its nearest
+ * manifest's capabilities) and the file's own extension/content signal. A
+ * backend `.ts` in a react project is `generic` (no react signal) — fixing the
+ * old extension-only default that flagged every `.ts` as react. Fail-open: any
+ * error yields `"generic"`, never throws. Return values stay within the label
+ * union ("react" | "nextjs" | "tanstack-start" | "laravel" | "swift" |
+ * "tailwind" | "java" | "go" | "ruby" | "rust" | "generic") — `tanstack-start`
+ * added 2026-07 (owner spec: first-class framework, Next.js-equivalent).
+ * @param filePath - Path of the file being written/edited.
+ * @param content - Its (incoming) content, for JS content signals.
+ * @param cwd - Root to resolve a relative `filePath` against (default cwd).
+ * @returns A framework label from the union.
+ */
+export function detectFramework(filePath: string, content: string, cwd: string = process.cwd()): string {
+  try {
+    const sig = fileSignal(filePath, content);
+    if (sig.definitive) return sig.definitive;
+    if (!sig.jsHint) return "generic";
+    const caps = projectCaps(nearestManifestDir(dirname(resolve(cwd, filePath))));
+    return reconcile(caps, sig.jsHint);
+  } catch {
+    return "generic";
+  }
+}