@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/deny-notice.ts

@@ -0,0 +1,52 @@
+/**
+ * @module deny-notice
+ * Attach a user-visible notice to a deny/ask hook response — the owner-reported
+ * gap where `permissionDecision: deny/ask` (the agent-only channel) left the
+ * human staring at a silent terminal. Mirrors {@link module:notices}'s
+ * compliance notices but for the BLOCKING outcomes those never covered.
+ * @packageDocumentation
+ */
+import figures from "figures";
+import type { Prompt } from "../prompt/types";
+import { attachSystemMessage } from "../adapters/claude";
+import { onceExclusive } from "./inject-dedup";
+import { BURST_DEDUP_MS } from "./burst-window";
+
+/**
+ * The human-facing line for a block/ask outcome: the gate's own
+ * {@link Prompt.userMessage} when it set one, else a generic symbol + title —
+ * text-presentation Unicode only (`figures.cross`/`?`), never emoji: terminal-safe,
+ * single-cell width, with the Windows fallbacks `figures` already resolves, matching
+ * the existing notice family (`notices.ts`'s `✓`/`⚠`, left untouched by this module).
+ * Null for `inform` ({@link module:respond}'s own `userMessage` path already
+ * covers it) or when neither applies.
+ */
+export function denyAskNotice(prompt: Prompt): string | null {
+  if (prompt.kind === "block") return prompt.userMessage ?? `${figures.cross} ${prompt.title}`;
+  if (prompt.kind === "ask") return prompt.userMessage ?? `? ${prompt.title}`;
+  return null;
+}
+
+/**
+ * Attach {@link denyAskNotice} onto an already-rendered deny/ask `stdout`, for
+ * the harnesses whose human channel is `systemMessage` (claude-code/codex —
+ * `permissionDecision`/`permissionDecisionReason` stay byte-intact, only the
+ * top-level field is added). Every other harness passes `stdout` through
+ * unchanged: Cursor already emits `user_message` natively (respond.ts), Hermes
+ * and cline have no human channel. Deduped via {@link onceExclusive} against
+ * the ~11 sibling-plugin fan-out for one real event (same window as the
+ * sniper reminder / compliance notices).
+ * @param id - Harness id (`ctx.id` from `PreContext`).
+ * @param stdout - The rendered hook response (from {@link module:respond.respond}).
+ * @param prompt - The {@link Prompt} that produced `stdout`.
+ * @param sessionId - Current session id (dedup scope).
+ * @param dir - State-dir for the dedup marker (per-project state dir).
+ * @param now - Event clock (tests pass a fake one).
+ */
+export function withDenyNotice(id: string, stdout: string, prompt: Prompt, sessionId: string, dir: string, now?: number): string {
+  if (id !== "claude-code" && id !== "codex") return stdout;
+  const notice = denyAskNotice(prompt);
+  if (!notice) return stdout;
+  if (!onceExclusive(`deny-notice:${sessionId}:${prompt.title}`, BURST_DEDUP_MS, { now, dir })) return stdout;
+  return attachSystemMessage(stdout, notice);
+}

package/src/runtime/design-cache-resolve.ts

@@ -0,0 +1,51 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fuseHarnessHome, sanitizeSessionId } from "./home-state";
+
+/** `~/.fuse-harness/design-sessions/<sid>` — session-anchored design-state dir. */
+function sessionCacheDir(sid: string, home?: string): string {
+  return join(fuseHarnessHome(home), "design-sessions", sid);
+}
+
+/** True when `dir` already holds the design-agent flag or a `.design-state-*.json` snapshot. */
+function hasDesignState(dir: string): boolean {
+  if (existsSync(join(dir, "design-agent-active"))) return true;
+  try {
+    return readdirSync(dir).some((name) => name.startsWith(".design-state-"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the cache dir the design pipeline (active-agent flag +
+ * `.design-state-<agentId>.json`) should read AND write for this hook call.
+ *
+ * Anchored on the session id, not the invoking process's `cwd`: a design
+ * agent's `SubagentStart` and its later tool writes can run with different
+ * `process.cwd()` values, and a cwd-keyed cache dir then silently misses the
+ * flag/state — every design gate fails open (see MEMORY/LESSON.md).
+ *
+ * Contract (non-regression): `resolved = sessionDirIfPopulated ??
+ * cwdDirIfPopulated ?? sessionDirDefault`. Before this fix the session-keyed
+ * dir never existed, so for every session whose state already lives under
+ * `cwdCacheDir` the FIRST branch is always empty and resolution falls through
+ * to `cwdCacheDir` — byte-identical to the pre-fix value. Only a session with
+ * NO state anywhere (today's silent-fail-open case, e.g. cwd drifted between
+ * `SubagentStart` and the write) diverges, anchoring on the session dir
+ * instead of silently missing the flag. Read and write always resolve through
+ * this same function against the same two inputs, so they can never target
+ * different locations mid-session.
+ * @param sessionId - The hook event's session id (`NormalizedEvent.sessionId`).
+ * @param cwdCacheDir - The legacy, cwd-derived cache dir (`projectLayout(cwd).cacheDir`).
+ * @param home - OS home override (tests only).
+ * @returns The cache dir to pass to the design flag/state/gate functions.
+ */
+export function resolveDesignCacheDir(sessionId: string, cwdCacheDir: string, home?: string): string {
+  const sid = sanitizeSessionId(sessionId);
+  if (!sid) return cwdCacheDir; // no stable session id -> unchanged legacy behavior
+  const sessDir = sessionCacheDir(sid, home);
+  if (hasDesignState(sessDir)) return sessDir;
+  if (hasDesignState(cwdCacheDir)) return cwdCacheDir;
+  return sessDir;
+}

package/src/runtime/design-content-gate.ts

@@ -0,0 +1,95 @@
+/**
+ * @module design-content-gate
+ * PRE content gate for design-system.md — the nominal path (validateDesignSystem
+ * used to run only behind the opt-in Gemini branch, so designSystemValid meant
+ * "a write happened", not "the content is valid"). Split out of
+ * `design-helpers.ts` to keep both files within the SOLID size budget (SRP).
+ * @packageDocumentation
+ */
+import { readFileSync, existsSync } from "node:fs";
+import type { Prompt } from "../prompt/types";
+import type { DesignState } from "../policy/design/state";
+import { deny, validateDesignSystem } from "../policy/design/gates";
+import { citedCorpusRefs, citationJoinsReads } from "../policy/design/corpus";
+import { substituteLiteral } from "./design-files-gate";
+
+/** Inputs for {@link designSystemContentGate} — the PRE write event plus resolved corpus context. */
+interface ContentGateInput {
+  filePath: string;
+  tool: string;
+  content: string;
+  oldString?: string;
+  replaceAll: boolean;
+  state: DesignState;
+  corpusRoot: string;
+  corpusRequired: boolean;
+}
+
+/**
+ * Every content violation of a design-system.md text, GRANULAR (one entry per
+ * unmet requirement and per unread cited reference — so a worsening check can
+ * diff two violation sets): the four hard requirements, plus the citation↔read
+ * jointure when the corpus is delivered.
+ */
+export function designSystemProblems(content: string, reads: readonly string[], corpusRequired: boolean): string[] {
+  const problems = validateDesignSystem(content, corpusRequired);
+  if (corpusRequired) {
+    for (const ref of citedCorpusRefs(content)) {
+      if (!citationJoinsReads(ref, reads)) problems.push(`cited corpus reference never read: ${ref}`);
+    }
+  }
+  return problems;
+}
+
+/** Content check for a design-system.md already on disk (the Gemini create_frontend path). */
+export function checkDesignSystemContent(content: string, reads: readonly string[], corpusRequired: boolean): Prompt | null {
+  const problems = designSystemProblems(content, reads, corpusRequired);
+  return problems.length ? deny(`BLOCKED: design-system.md too generic. Missing: ${problems.join(", ")}.`) : null;
+}
+
+/**
+ * The content a Write/Edit would LEAVE in design-system.md, and the on-disk
+ * original when the file exists (for BOTH tools). Edit reconstructs via
+ * literal substitution (first occurrence, or all under replace_all — the Edit
+ * tool's own semantics, mirroring edit-outcome.ts). Null when unverifiable
+ * (unreadable file or stale old_string) — fail-closed, such an Edit fails at
+ * tool level anyway.
+ */
+function effectiveContents(i: ContentGateInput): { result: string; original: string | null } | null {
+  if (i.tool !== "Edit") {
+    let original: string | null = null;
+    try {
+      if (existsSync(i.filePath)) original = readFileSync(i.filePath, "utf8");
+    } catch {
+      original = null;
+    }
+    return { result: i.content, original };
+  }
+  let disk: string;
+  try {
+    disk = readFileSync(i.filePath, "utf8");
+  } catch {
+    return null;
+  }
+  if (!i.oldString || !disk.includes(i.oldString)) return null;
+  return { result: substituteLiteral(disk, i.oldString, i.content, i.replaceAll), original: disk };
+}
+
+/**
+ * Block only the violations the change INTRODUCES (`problems(result) ⊄
+ * problems(original)`): a legacy design-system.md that predates the doctrine
+ * stays editable — and rewritable — including byte-identically or toward
+ * conformance; a change that adds a NEW problem (or writes an invalid file
+ * from scratch) is blocked.
+ */
+export function designSystemContentGate(i: ContentGateInput): Prompt | null {
+  if (!i.filePath.endsWith("design-system.md")) return null;
+  const pair = effectiveContents(i);
+  if (pair === null) return deny("BLOCKED: cannot verify the edit result (unreadable file or stale old_string). RECOVERY: re-read design-system.md, then retry.");
+  const result = designSystemProblems(pair.result, i.state.corpusReads, i.corpusRequired);
+  if (!result.length) return null;
+  const original = pair.original !== null ? designSystemProblems(pair.original, i.state.corpusReads, i.corpusRequired) : [];
+  const introduced = result.filter((p) => !original.includes(p));
+  if (!introduced.length) return null;
+  return deny(`BLOCKED: design-system.md too generic. Missing: ${introduced.join(", ")}. RECOVERY: fix the content (read cited refs-design references with the Read tool), then retry.`);
+}

package/src/runtime/design-files-gate.ts

@@ -0,0 +1,114 @@
+/**
+ * @module design-files-gate
+ * Gates for multi-file write primitives (Codex `apply_patch`, fanned into
+ * `event.files` by normalize.ts): apply_patch IS the Write tool under Codex,
+ * so the design pipeline must see it. Per op, because `content` means
+ * different things (apply-patch.ts:10-15):
+ *  - add:    content IS the full new document — content-gated like a Write;
+ *  - update: content is the hunk's new side, APPROXIMATE, never the document —
+ *            only content-independent gates run (path, state-file, phase/quota).
+ *            No BLOCKING or DEGRADING validation on this path — promote-only:
+ *            the POST re-reads the real file, a clean content promotes to
+ *            phase 3, a dirty one changes nothing. And it would not bite
+ *            anyway: designSystemValid is consumed ONLY under
+ *            FUSE_DESIGN_GEMINI=1 (off by default — an informational flag),
+ *            and designSystemExists is never read after init;
+ *  - delete: skipped (parity with the sibling applyPatchGate).
+ * One violating file blocks the whole envelope. `htmlCssOnlyGate` NOW applies
+ * here too (owner D2 revised): the two write paths must not diverge on what
+ * the design agent may write — an `apply_patch` `.tsx`/`.astro`/etc. add or
+ * update is just as much a framework-file write as the same content via
+ * `Write`/`Edit`, and letting it through only on this path was an unintended
+ * apply_patch-shaped bypass, not a deliberate relaxation. `uiDesignSkillGate`
+ * and the Gemini create_frontend precondition NO LONGER bypass apply_patch
+ * (fixed): the skill gate is wired in `design.ts` on `event.files` (same
+ * any-agent scope as its Write/Edit call site, before the agentId
+ * early-return); the Gemini precondition is ported into this function,
+ * right below `htmlCssOnlyGate`, gated the same way (opt-in,
+ * FUSE_DESIGN_GEMINI, state.geminiCalls === 0). REMAINING KNOWN GAPS
+ * (documented, still out of scope):
+ * `Design-System.md` (case) escapes every endsWith check, here and on
+ * Write — a real bypass on case-insensitive macOS, not widened now; and
+ * `*** Move to:` (apply-patch.ts:76-79) unconditionally OVERWRITES `cur.path`
+ * on ANY preceding op (`Add File`/`Update File`), so a `*** Update File: a.css`
+ * + `Move to: a.tsx` sequence surfaces here as `filePath` ending in `.tsx`
+ * (correctly blocked — NOT a bypass, verified against the parser). The
+ * un-verified direction is the reverse: `Add File: a.tsx` + `Move to: a.css`
+ * would surface only the PERMITTED destination extension while `f.content`
+ * is real framework code — the source path is never preserved anywhere, and
+ * this gate (like Write's htmlCssOnlyGate) checks only the extension, never
+ * the content's actual syntax. Whether Codex's real grammar allows Move-to
+ * after an Add (vs. Update-only) is unconfirmed; flagged, not fixed here.
+ * Also: the POST side still does NOT run `runDesignChecks` (tsx/jsx/css
+ * warnings) on an `apply_patch` file — `handle-post.ts` keeps `designGate` on
+ * the RAW, un-fanned envelope there (recordPost's apply_patch branch is
+ * promote-only and resolves `design-system.md` via `join(cwd, …)`; routing a
+ * fanned Write/Edit-shaped event through it instead would read `filePath`
+ * UNRESOLVED and risk degrading the state — a real regression, not a
+ * hypothetical one). Restoring the tsx/jsx/css warning would require
+ * resolving relative apply_patch paths AND preserving the promote-only
+ * doctrine inside `recordPost` at the same time — out of scope here, owner
+ * decision.
+ * @packageDocumentation
+ */
+import type { Prompt } from "../prompt/types";
+import type { NormalizedFile } from "./normalize";
+import type { DesignState } from "../policy/design/state";
+import { pluginsWriteGuard } from "../policy/design/corpus";
+import { htmlCssOnlyGate, stateFileGate, geminiEnabled } from "../policy/design/gates";
+import { designSystemWriteGate, htmlCssPipelineGate } from "../policy/design/gates-pipeline";
+import { designSystemContentGate } from "./design-content-gate";
+
+/**
+ * Literal substitution, first occurrence or all — NEVER String.replace's
+ * replacement-string semantics: an agent-controlled new_string of `$&`, `` $` ``,
+ * `$'` or `$$` must be written (and validated) literally, not interpreted as
+ * the matched text (that made the gate validate a document the tool would
+ * never write — the `$&` bypass). Used on both sides: PRE reconstruction and
+ * POST reverse-reconstruction.
+ */
+export function substituteLiteral(s: string, from: string, to: string, all: boolean): string {
+  return all ? s.split(from).join(to) : s.replace(from, () => to);
+}
+
+/**
+ * Gate every file of a multi-file write primitive; the first violation blocks
+ * the envelope. `designSystemFileExists` is caller-computed (`findDesignSystem`
+ * lives in `design-helpers.ts`, which itself imports `substituteLiteral` from
+ * THIS module — importing it back here would cycle) so both write paths
+ * (Write/Edit in `design.ts`, apply_patch here) consume the SAME disk read.
+ */
+export function designFilesGate(
+  files: readonly NormalizedFile[],
+  state: DesignState,
+  pluginsRoot: string,
+  corpusRoot: string,
+  corpusRequired: boolean,
+  cwd: string,
+  designSystemFileExists: boolean,
+): Prompt | null {
+  for (const f of files) {
+    const hit = pluginsWriteGuard(f.filePath, pluginsRoot, cwd) ?? stateFileGate(f.filePath);
+    if (hit) return hit;
+    if (f.op === "delete") continue;
+    const htmlCssHit = htmlCssOnlyGate(f.filePath);
+    if (htmlCssHit) return htmlCssHit;
+    // Parity with design.ts's htmlCssPipelineGate call: SAME verdict for the
+    // SAME file+state on both write paths (Write/Edit vs apply_patch).
+    const pipelineHit = htmlCssPipelineGate(f.filePath, state, designSystemFileExists);
+    if (pipelineHit) return pipelineHit;
+    // apply_patch parity for the Gemini precondition (design.ts:72-74, D2 gap):
+    // same condition, same Prompt shape as the Write/Edit branch — opt-in via
+    // FUSE_DESIGN_GEMINI (OFF by default), so a no-op when Gemini is disabled.
+    if (geminiEnabled() && state.geminiCalls === 0 && /\.(html|css)$/.test(f.filePath)) {
+      return { kind: "block", title: "Design pipeline", reason: "BLOCKED: generate the frontend via create_frontend before hand-writing HTML/CSS.", actions: ["Call mcp__gemini-design__create_frontend first"] };
+    }
+    if (!f.filePath.endsWith("design-system.md")) continue;
+    const gate = designSystemWriteGate(f.filePath, state, corpusRequired)
+      ?? (f.op === "add"
+        ? designSystemContentGate({ filePath: f.filePath, tool: "Write", content: f.content, oldString: undefined, replaceAll: false, state, corpusRoot, corpusRequired })
+        : null);
+    if (gate) return gate;
+  }
+  return null;
+}

package/src/runtime/design-helpers.ts

@@ -0,0 +1,93 @@
+/**
+ * @module design-helpers
+ * Effectful helpers for the design pipeline gate: locate design-system.md and
+ * apply PostToolUse fuse-browser transitions to the design state. Split out of
+ * `design.ts` to keep that file within the SOLID size budget (SRP).
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import type { NormalizedEvent } from "./normalize";
+import { type DesignState, saveDesignState } from "../policy/design/state";
+import { recordNavigate, recordScroll, recordScreenshot, recordValidDesignSystem } from "../policy/design/transitions";
+import { SHOT_TOOLS } from "../policy/design/screenshot-tools";
+import { designSystemProblems } from "./design-content-gate";
+import { substituteLiteral } from "./design-files-gate";
+import { creditRead, creditShellReads } from "./design-read-credit";
+
+export { designSystemContentGate } from "./design-content-gate";
+
+const NAV = "mcp__fuse-browser__browser_navigate";
+const SCROLL = "mcp__fuse-browser__browser_scroll";
+const GEMINI = "mcp__gemini-design__create_frontend";
+
+/** Read design-system.md walking up to 6 parents from `cwd` ("" if absent/unreadable). */
+export function findDesignSystem(cwd: string): string {
+  let dir = cwd;
+  for (let i = 0; i < 6; i++) {
+    const p = join(dir, "design-system.md");
+    if (existsSync(p)) {
+      try {
+        return readFileSync(p, "utf8");
+      } catch {
+        return "";
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "";
+}
+
+/** Apply a PostToolUse fuse-browser transition to the design state. */
+export function recordPost(event: NormalizedEvent, cacheDir: string, state: DesignState, corpusRoot = "", corpusRequired = false, cwd = ""): void {
+  if (SHOT_TOOLS.has(event.tool)) saveDesignState(cacheDir, recordScreenshot(state, corpusRequired));
+  else if (event.tool === NAV) saveDesignState(cacheDir, recordNavigate(state));
+  else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
+  else if (event.tool === GEMINI) saveDesignState(cacheDir, { ...state, geminiCalls: state.geminiCalls + 1 });
+  else if (event.tool === "Read") creditRead(cacheDir, state, corpusRoot, corpusRequired, event.filePath ?? "");
+  // Codex Code Mode exec (`exec_command`, canonicalized to "Bash" by codex-shell-tool.ts).
+  else if (event.tool === "Bash" && event.command) creditShellReads(cacheDir, state, corpusRoot, corpusRequired, event.command);
+  else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) {
+    // Write access ≠ validity, same rule both sides: POST validates only a
+    // zero-problem content and DEGRADES only what PRE would have blocked.
+    const fp = event.filePath ?? "";
+    let content: string;
+    try {
+      content = readFileSync(fp, "utf8");
+    } catch {
+      return;
+    }
+    const problems = designSystemProblems(content, state.corpusReads, corpusRequired);
+    if (!problems.length) {
+      saveDesignState(cacheDir, recordValidDesignSystem(state));
+      return;
+    }
+    // Edit: degrade only on problems the edit INTRODUCED (original reverse-rebuilt
+    // with LITERAL substitution; a deletion edit is not reconstructable — D5).
+    if (event.tool === "Edit" && event.oldString && event.content && content.includes(event.content)) {
+      const original = substituteLiteral(content, event.content, event.oldString, event.input.replace_all === true);
+      const introduced = problems.filter((p) => !designSystemProblems(original, state.corpusReads, corpusRequired).includes(p));
+      if (introduced.length) saveDesignState(cacheDir, { ...state, designSystemValid: false });
+    }
+    // Write / unreconstructable Edit: the PRE gate enforced not-worsening — never degrade here.
+  } else if (event.files) {
+    // Codex apply_patch: PROMOTE-ONLY, never blocking nor degrading — the POST
+    // re-reads the REAL file (the hunk is never the document): clean → phase 3,
+    // dirty → nothing. designSystemValid is only consumed under FUSE_DESIGN_GEMINI.
+    const ds = event.files.find((f) => f.op !== "delete" && f.filePath.endsWith("design-system.md"));
+    if (ds) {
+      const abs = isAbsolute(ds.filePath) ? ds.filePath : join(cwd, ds.filePath);
+      let content: string;
+      try {
+        content = readFileSync(abs, "utf8");
+      } catch {
+        return;
+      }
+      if (!designSystemProblems(content, state.corpusReads, corpusRequired).length) {
+        saveDesignState(cacheDir, recordValidDesignSystem(state));
+      }
+    }
+  }
+}

package/src/runtime/design-lifecycle.ts

@@ -0,0 +1,39 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { detectMode } from "../policy/design/transitions";
+import { initDesignState, saveDesignState, cleanupDesignStates } from "../policy/design/state";
+import { setActiveDesignAgent, clearActiveDesignAgent, activeDesignAgent } from "../policy/design/flag";
+import { promptText } from "./prompt-text";
+
+/**
+ * Handle the design-agent SubagentStart/Stop lifecycle: init the pipeline state +
+ * raise the active flag on start, archive/cleanup + clear the flag on stop.
+ * Returns true when it handled the event (caller should respond and stop).
+ *
+ * `SubagentStop` clears the flag whenever `agent_id` matches the currently
+ * active one, INDEPENDENTLY of `agent_type` on the stop payload — a stop event
+ * is not guaranteed to echo the same `agent_type` string the start event used,
+ * and gating the clear on it left the flag stuck (blocking every subsequent
+ * top-level Write/Edit in the session — see MEMORY/LESSON.md).
+ */
+export function designLifecycle(payload: Record<string, unknown>, cacheDir: string, cwd: string, stamp: string, now: number): boolean {
+  const event = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+  if (event === "SubagentStop") {
+    if (!agentId || agentId !== activeDesignAgent(cacheDir)) return false;
+    cleanupDesignStates(cacheDir, agentId, stamp, now);
+    clearActiveDesignAgent(cacheDir);
+    return true;
+  }
+  const agentType = typeof payload.agent_type === "string" ? payload.agent_type : "";
+  if (!agentType.includes("design")) return false;
+  if (event === "SubagentStart") {
+    if (!agentId) return false;
+    const dsExists = existsSync(join(cwd, "design-system.md"));
+    const prompt = promptText(payload.prompt);
+    saveDesignState(cacheDir, initDesignState(agentId, detectMode(prompt, dsExists), dsExists));
+    setActiveDesignAgent(cacheDir, agentId);
+    return true;
+  }
+  return false;
+}

package/src/runtime/design-read-credit.ts

@@ -0,0 +1,28 @@
+/**
+ * @module design-read-credit
+ * Shared credit path for a design-corpus/ref read, reused by both the native
+ * `Read` branch and the shell-read branch (Codex Code Mode `exec_command`,
+ * canonicalized to `"Bash"` by `codex-shell-tool.ts`) in
+ * `design-helpers.ts::recordPost`. Split out to keep that file within the
+ * SOLID size budget — zero new parser, zero new store: both callers hit the
+ * SAME `recordCorpusRead`/`recordRead` transitions.
+ * @packageDocumentation
+ */
+import { existsSync } from "node:fs";
+import type { DesignState } from "../policy/design/state";
+import { saveDesignState } from "../policy/design/state";
+import { recordCorpusRead, recordRead } from "../policy/design/transitions";
+import { classifyCorpusRead } from "../policy/design/corpus";
+import { shellReadRefPaths } from "../policy/shell-read-refs";
+
+/** Credit one read path as a corpus read (anchored + on-disk) or a plain ref read. */
+export function creditRead(cacheDir: string, state: DesignState, corpusRoot: string, corpusRequired: boolean, fp: string): void {
+  if (classifyCorpusRead(fp, corpusRoot) && existsSync(fp)) {
+    saveDesignState(cacheDir, recordCorpusRead(state, fp.slice(corpusRoot.length + 1), corpusRequired));
+  } else saveDesignState(cacheDir, recordRead(state, fp, corpusRequired));
+}
+
+/** Credit every `.md` path a read-only shell `command` targets, same path as {@link creditRead}. */
+export function creditShellReads(cacheDir: string, state: DesignState, corpusRoot: string, corpusRequired: boolean, command: string): void {
+  for (const fp of shellReadRefPaths(command)) creditRead(cacheDir, state, corpusRoot, corpusRequired, fp);
+}

package/src/runtime/design.ts

@@ -0,0 +1,116 @@
+import type { Prompt } from "../prompt/types";
+import type { NormalizedEvent } from "./normalize";
+import { loadDesignState, saveDesignState, initDesignState } from "../policy/design/state";
+import { recordValidDesignSystem } from "../policy/design/transitions";
+import { activeDesignAgent } from "../policy/design/flag";
+import { runDesignChecks } from "../policy/design/content-checks";
+import { uiDesignSkillGate } from "../policy/design/skill-gate";
+import { collectDesignEvidence } from "../policy/design/skill-evidence";
+import { findDesignSystem, recordPost, designSystemContentGate } from "./design-helpers";
+import { checkDesignSystemContent } from "./design-content-gate";
+import { designFilesGate } from "./design-files-gate";
+import { resolveCorpusRoot, resolvePluginsRoot, pluginsWriteGuard } from "../policy/design/corpus";
+import {
+  htmlCssOnlyGate, stateFileGate, screenshotScrollGate,
+  geminiEnabled,
+} from "../policy/design/gates";
+import { designSystemWriteGate, geminiCreateGate, browserNavigateGate, htmlCssPipelineGate } from "../policy/design/gates-pipeline";
+
+const NAV = "mcp__fuse-browser__browser_navigate";
+const SHOT = "mcp__fuse-browser__browser_screenshot";
+const GEMINI = "mcp__gemini-design__create_frontend";
+
+/**
+ * Design-pipeline gate (effectful: reads/writes the design state + design-system.md).
+ * Returns a Prompt to block, or null when this isn't a design-agent context / nothing fires.
+ */
+export function designGate(payload: Record<string, unknown>, event: NormalizedEvent, cacheDir: string, cwd: string, corpusRootOverride?: string, pluginsRootOverride?: string): Prompt | null {
+  // UI design-skill gate (ports check-design-skill.py): fires for ANY agent on a
+  // UI write — requires a design-skill read + ANY doc source (Context7/Exa/web).
+  // Gemini is NEVER required. Runs before the design-agent pipeline state logic.
+  if (event.phase !== "post" && (event.tool === "Write" || event.tool === "Edit")) {
+    const skillBlock = uiDesignSkillGate(event.tool, event.filePath ?? "", event.content ?? "", collectDesignEvidence(event.sessionId, cwd));
+    if (skillBlock) return skillBlock;
+  }
+  // Codex apply_patch parity (D2 gap, docstring design-files-gate.ts:17-24): the
+  // same UI write can arrive fanned into event.files instead of a single
+  // Write/Edit. Map each non-delete file to its Write/Edit-equivalent tool
+  // ("add" -> Write, "update" -> Edit) and run the SAME gate, so the skill
+  // requirement cannot be bypassed just by routing the write through apply_patch.
+  // Scope matches the Write/Edit block above: ANY agent, before the agentId
+  // early-return — never narrowed to design-agent-only.
+  if (event.phase !== "post" && event.files && event.files.length > 0) {
+    const evidence = collectDesignEvidence(event.sessionId, cwd);
+    for (const f of event.files) {
+      if (f.op === "delete") continue;
+      const skillBlock = uiDesignSkillGate(f.op === "add" ? "Write" : "Edit", f.filePath, f.content, evidence);
+      if (skillBlock) return skillBlock;
+    }
+  }
+
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+  if (!agentId) return null; // top-level (lead) calls are never design-agent-scoped
+  const active = activeDesignAgent(cacheDir);
+  if (active && agentId !== active) return null;
+  const id = agentId;
+  // P5 fail-open fix: when the design flag is active but the state file is missing
+  // (e.g. teammate context), auto-init a fresh state instead of disabling all
+  // gating (parity with pipeline-gate.py:38-60). Without the flag, stay inert.
+  let state = loadDesignState(cacheDir, id);
+  if (!state) {
+    if (!active) return null;
+    const dsExists = findDesignSystem(cwd) !== "";
+    state = initDesignState(id, dsExists ? "page" : "full", dsExists);
+    saveDesignState(cacheDir, state);
+  }
+  // Corpus + plugin roots, resolved INDEPENDENTLY (corpusRoot never decides
+  // pluginsRoot — F4). Corpus absent ⇒ requirement waived (pre-doctrine quotas);
+  // the plugin-root write guard stays active against refs-design fabrication.
+  const corpusRoot = corpusRootOverride ?? resolveCorpusRoot();
+  const corpusRequired = corpusRoot !== "";
+  const pluginsRoot = pluginsRootOverride ?? resolvePluginsRoot();
+
+  if (event.phase === "post") {
+    recordPost(event, cacheDir, state, corpusRoot, corpusRequired, cwd);
+    if ((event.tool === "Write" || event.tool === "Edit") && /\.(tsx|jsx|css)$/.test(event.filePath ?? "")) {
+      const warnings = runDesignChecks(event.content ?? "");
+      if (warnings.length) return { kind: "inform", title: "Design review", reason: warnings.join(" "), actions: [] };
+    }
+    return null;
+  }
+  if (event.tool === "Write" || event.tool === "Edit") {
+    const fp = event.filePath ?? "";
+    // Parity: only design-system.md is screenshot-quota-gated (designSystemWriteGate).
+    const base = pluginsWriteGuard(fp, pluginsRoot) ?? stateFileGate(fp) ?? htmlCssOnlyGate(fp)
+      ?? htmlCssPipelineGate(fp, state, findDesignSystem(cwd) !== "") ?? designSystemWriteGate(fp, state, corpusRequired)
+      ?? designSystemContentGate({ filePath: fp, tool: event.tool, content: event.content ?? "", oldString: event.oldString, replaceAll: event.input.replace_all === true, state, corpusRoot, corpusRequired });
+    if (base) return base;
+    if (geminiEnabled() && state.geminiCalls === 0 && /\.(html|css)$/.test(fp)) {
+      return { kind: "block", title: "Design pipeline", reason: "BLOCKED: generate the frontend via create_frontend before hand-writing HTML/CSS.", actions: ["Call mcp__gemini-design__create_frontend first"] };
+    }
+    return null;
+  }
+  // Codex apply_patch (D2): gate each fanned-out file like a Write.
+  if (event.files && event.files.length > 0) return designFilesGate(event.files, state, pluginsRoot, corpusRoot, corpusRequired, cwd, findDesignSystem(cwd) !== "");
+  if (event.tool === NAV) {
+    return browserNavigateGate(state, typeof event.input.url === "string" ? event.input.url : "");
+  }
+  if (event.tool === SHOT) return screenshotScrollGate(state);
+  if (event.tool === GEMINI) {
+    if (!geminiEnabled()) return null;
+    const block = geminiCreateGate(state);
+    if (block) return block;
+    const ds = findDesignSystem(cwd);
+    // Parity validate-design-system.py DENY_NOT_FOUND: a MISSING file gets its own
+    // recovery message, distinct from the "too generic" message for a present-but-thin one.
+    if (ds === "") {
+      return { kind: "block", title: "Design pipeline", reason: "BLOCKED: design-system.md not found. RECOVERY: 1) Read the identity templates 2) Read design-inspiration.md 3) Read the refs-design corpus (README.md + relevant tokens-*.md) 4) Screenshot 1-2 real sector sites 5) Write design-system.md, then retry create_frontend.", actions: ["Create design-system.md via the pipeline, then retry create_frontend"] };
+    }
+    // Same content rules as the nominal write path (jointure included): the
+    // Gemini branch must not be weaker than the gate the Write just went through.
+    const contentBlock = checkDesignSystemContent(ds, state.corpusReads, corpusRequired);
+    if (contentBlock) return contentBlock;
+    saveDesignState(cacheDir, recordValidDesignSystem(state));
+  }
+  return null;
+}

package/src/runtime/dev-context.ts

@@ -0,0 +1,43 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { capFragment } from "./inject-budget";
+
+/** Run a git subcommand in `cwd`, returning trimmed stdout or "" on error. */
+function git(cwd: string, args: string[]): string {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: "pipe", timeout: 5000 }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Build the git portion of the dev context (branch + up to 5 changed files). */
+export function gitContext(cwd: string): string[] {
+  if (!existsSync(join(cwd, ".git"))) return [];
+  const parts = [`Git branch: ${git(cwd, ["branch", "--show-current"]) || "unknown"}`];
+  const status = git(cwd, ["status", "--porcelain"]);
+  if (status) parts.push("Modified files:\n" + status.split("\n").slice(0, 5).join("\n"));
+  return parts;
+}
+
+/** Build the project-type portion (mirrors load-dev-context.py exactly). */
+export function projectContext(cwd: string): string[] {
+  const parts: string[] = [];
+  const has = (f: string): boolean => existsSync(join(cwd, f));
+  if (["next.config.js", "next.config.ts", "next.config.mjs"].some(has)) parts.push("Project: Next.js");
+  else if (has("package.json")) parts.push("Project: Node.js");
+  if (has("composer.json") && has("artisan")) parts.push("Project: Laravel");
+  if (has("Package.swift")) parts.push("Project: Swift");
+  return parts;
+}
+
+/**
+ * Build the SessionStart dev-context block (git + project type), or "" when
+ * nothing applies. Ports `core-guards/scripts/session-start/load-dev-context.py`.
+ * @param cwd - Project root to inspect.
+ * @returns The joined additionalContext text (possibly empty).
+ */
+export function devContext(cwd: string): string {
+  return capFragment("dev-context", [...gitContext(cwd), ...projectContext(cwd)].join("\n"));
+}