@fusengine/harness 0.1.81 → 0.1.84

package/dist/{handle-J5r2f_O_.mjs → handle-DsP67KZ4.mjs}

@@ -2,6 +2,7 @@ import { a as resolveMaxLines, l as parseEnvInt, s as splitTarget } from "./limi
 import { s as resolveTtlSec } from "./dotenv-DoqNlALG.mjs";
 import { r as projectLayout } from "./layout-KWoE_Mqn.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
+import { t as detectHarness } from "./harness-BMuLJ9lm.mjs";
 import { D as isVendorPath, G as isFileSizeScoped, K as resolveSolidRefFramework, W as computeEditResultLines, b as interfaceDeclLevel, et as detectFramework, g as conventionsMode, lt as requiredArchSkill, n as FAIL_CLOSED, ot as detectModularArchitecture, rt as maskCommentsAndStrings, st as detectProjectType$1, t as evaluate } from "./evaluate-B4-MhOy_.mjs";
 import { a as sanitizeSessionId, c as sessionsDir, d as countFrameworkCodeLines, f as countLines, i as loadSessionState, l as PLUGINS_DIR, n as fuseHarnessHome, o as saveSessionState, p as evaluateFileSize, r as fusengineCache, t as claudeHome } from "./home-state-oUGFB4ds.mjs";
 import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
@@ -12,13 +13,13 @@ import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { a as nowStamp, l as throttleMs, n as readRoots, o as readState, s as setStateField, t as addRoot } from "./registry-IhHk2KlT.mjs";
 import { d as loadIndex, i as cacheLookupMeta, n as webfetchCacheWrite, o as cacheLookupSubstringMeta, t as mcpCacheWrite, u as extractText } from "./mcp-store-BkBDmuxN.mjs";
 import { t as loadRefs } from "./loader-AGz4nK7d.mjs";
-import { _ as trivialCount, a as LOCK_TTL_MS, c as writeLastNonce, d as recordAgent, f as recordBrainstormRequired, g as recordTrivialEdit, h as recordTarget, i as LOCK_FAILED, l as agentsFresh, m as recordRefRead, o as signTrack, p as recordDoc, r as withTrack, s as verifyTrack, t as loadTrack, u as emptyTrack, v as apexAuthorizationGate } from "./store-yr_QFsZY.mjs";
+import { C as apexAuthorizationGate, S as trivialCount, _ as recordBrainstormRequired, a as journalLogPath, b as recordTarget, c as appendEvent, d as signTrack, f as verifyTrack, g as recordAgent, h as emptyTrack, i as withTrack, l as withTrackLockSync, m as agentsFresh, o as readTrackSync, p as writeLastNonce, r as trackJournalEnabled, s as diffTrackEvents, t as loadTrack, u as LOCK_FAILED, v as recordDoc, x as recordTrivialEdit, y as recordRefRead } from "./store-Dw08Amqh.mjs";
 import { n as parseApplyPatch, t as isBypassPermissions } from "./permission-mode-BN3MNgbm.mjs";
 import { _ as commandToString, d as collectFiles, f as pathExists, g as writeText, h as spawnCapture, i as denyResponse, l as systemMessage, m as sleep, n as blockResponse, p as readText$1, r as contextResponse, s as informResponse, t as attachSystemMessage } from "./claude-D93HY8dq.mjs";
 import { i as toKimiResponse, n as kimiDenyResponse } from "./kimi-ChbcU2uI.mjs";
 import { r as toHermesResponse } from "./hermes-1PUEoY8q.mjs";
-import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
-import { appendFileSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { mkdir, rmdir } from "node:fs/promises";
 import { createHash } from "node:crypto";
@@ -170,86 +171,39 @@ function trackFile(sessionId, baseDir) {
 	return join(baseDir ?? defaultStateDir(), `track-${sessionId.replace(/[^A-Za-z0-9_-]/g, "_") || "default"}.json`);
 }
 //#endregion
-//#region src/policy/design/transitions.ts
-/** Infer the pipeline mode from the launch prompt + whether a design-system.md already exists. */
-function detectMode(prompt, designSystemExists) {
-	const p = prompt.toLowerCase();
-	if ([
-		"component",
-		"composant",
-		"snippet"
-	].some((k) => p.includes(k))) return "component";
-	return designSystemExists ? "page" : "full";
-}
-/** Record a screenshot: bump the count and advance to phase 2 once the quota is met. */
-function recordScreenshot(state, needed) {
-	const screenshotsCount = state.screenshotsCount + 1;
-	const next = {
-		...state,
-		screenshotsCount
-	};
-	if (screenshotsCount >= needed && state.currentPhase < 2) {
-		next.currentPhase = 2;
-		next.phasesCompleted = [.../* @__PURE__ */ new Set([
-			...state.phasesCompleted,
-			"identity",
-			"research"
-		])];
-	}
-	return next;
-}
-/** Record a fuse-browser navigate (resets the scroll-before-screenshot guard). */
-function recordNavigate(state) {
-	return {
-		...state,
-		scrolledSinceNav: false
-	};
-}
-/** Record a fuse-browser scroll (satisfies the scroll-before-screenshot guard). */
-function recordScroll(state) {
-	return {
-		...state,
-		scrolledSinceNav: true
-	};
-}
-/** Mark the design system validated and advance to phase 3 (after a passing create_frontend check). */
-function recordValidDesignSystem(state) {
-	return {
-		...state,
-		designSystemExists: true,
-		designSystemValid: true,
-		currentPhase: Math.max(state.currentPhase, 3),
-		phasesCompleted: [.../* @__PURE__ */ new Set([...state.phasesCompleted, "design-system"])]
-	};
-}
-/**
-* Record a skill-file Read: reading the identity templates enters phase 1 (browsing
-* allowed); reading the inspiration catalog satisfies the browse prerequisite.
-*/
-function recordRead(state, filePath) {
-	const next = { ...state };
-	if (filePath.includes("design-system/SKILL.md")) {
-		next.currentPhase = Math.max(state.currentPhase, 1);
-		next.phasesCompleted = [.../* @__PURE__ */ new Set([...state.phasesCompleted, "identity"])];
-	}
-	if (filePath.includes("design-inspiration")) next.inspirationRead = true;
-	return next;
-}
-//#endregion
 //#region src/policy/design/state.ts
-/** Minimum fuse-browser screenshots required before writing design-system.md, per mode. */
+/** Minimum fuse-browser screenshots required before writing design-system.md, per mode (corpus present). */
 const MIN_SCREENSHOTS = {
+	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.
+*/
+const MIN_SCREENSHOTS_NO_CORPUS = {
 	full: 4,
 	page: 2,
-	component: 0
+	component: 1
 };
+/** Screenshot quota for `mode` — the SINGLE choice point between the two tables, driven by corpus availability. */
+function quotaFor(mode, corpusRequired) {
+	return (corpusRequired ? MIN_SCREENSHOTS : MIN_SCREENSHOTS_NO_CORPUS)[mode];
+}
 const stateFile = (cacheDir, agentId) => join(cacheDir, `.design-state-${agentId}.json`);
 /** Load the design state for `agentId`, or null when absent/corrupt (fail-open). */
 function loadDesignState(cacheDir, agentId) {
 	const path = stateFile(cacheDir, agentId);
 	if (!existsSync(path)) return null;
 	try {
-		return JSON.parse(readFileSync(path, "utf8"));
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		return {
+			...parsed,
+			corpusReads: parsed.corpusReads ?? []
+		};
 	} catch {
 		return null;
 	}
@@ -268,6 +222,7 @@ function initDesignState(agentId, mode, designSystemExists) {
 		inspirationRead: false,
 		scrolledSinceNav: false,
 		screenshotsCount: 0,
+		corpusReads: [],
 		designSystemExists,
 		designSystemValid: false,
 		geminiCalls: 0
@@ -295,6 +250,264 @@ function cleanupDesignStates(cacheDir, agentId, stamp, now) {
 	}
 }
 //#endregion
+//#region src/util/semver.ts
+/**
+* Dependency-free semver ordering. `Array.prototype.sort()` compares strings
+* lexicographically — `"1.0.9" > "1.0.23"` — so versioned directories (plugin
+* caches) must be ordered with a numeric, segment-by-segment comparison.
+*/
+/**
+* Compare two dotted version strings numerically, segment by segment
+* (shorter version wins when a prefix is equal: `1.0` < `1.0.1`). A segment
+* that is not a plain integer (prerelease tag like `0-beta`) falls back to
+* lexicographic comparison of that segment — never NaN, so `sort()` stays
+* defined; identical strings compare 0.
+* @returns Negative when `a < b`, positive when `a > b`, 0 when equal.
+*/
+function compareSemver(a, b) {
+	const pa = a.split("."), pb = b.split(".");
+	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+		const sa = pa[i] ?? "0", sb = pb[i] ?? "0";
+		if (sa === sb) continue;
+		const na = Number(sa), nb = Number(sb);
+		if (Number.isInteger(na) && Number.isInteger(nb) && na !== nb) return na - nb;
+		return sa < sb ? -1 : 1;
+	}
+	return 0;
+}
+/** The highest version of the list, or null when empty. */
+function maxSemver(versions) {
+	return versions.length === 0 ? null : versions.reduce((a, b) => compareSemver(a, b) >= 0 ? a : b);
+}
+//#endregion
+//#region src/policy/design/corpus-resolve.ts
+/**
+* Corpus/plugins root resolution (fs) and the write guard over it. Resolution
+* is PER RUNTIME (Claude marketplaces, Codex versioned plugin cache — same
+* pattern as rules-root.ts); runtimes without a plugin structure (kimi today)
+* resolve to "" and the corpus gates stay dormant. There is NO cwd fallback
+* anywhere: an agent-controlled directory can never become its own taste
+* reference (self-attested proof — the failure this gate exists to prevent).
+*/
+const CORPUS_SUFFIX = join("skills", "design-web", "references", "refs-design");
+/** Immediate child dir names of `dir`, or [] when unreadable. */
+function children$2(dir) {
+	try {
+		return readdirSync(dir).sort();
+	} catch {
+		return [];
+	}
+}
+/** Claude: `<home>/.claude/plugins/marketplaces/<mkt>/plugins/design-expert` ("" when absent). */
+function probeClaude$1(home) {
+	const markets = join(home, ".claude", "plugins", "marketplaces");
+	for (const m of children$2(markets)) {
+		const de = join(markets, m, "plugins", "design-expert");
+		if (existsSync(de)) return de;
+	}
+	return "";
+}
+/** Codex: `<CODEX_HOME|~/.codex>/plugins/cache/<mkt>/design-expert/<highest STABLE semver>` ("" when absent). */
+function probeCodex$1(env, home) {
+	const cache = join(env.CODEX_HOME ?? join(home, ".codex"), "plugins", "cache");
+	for (const m of children$2(cache)) {
+		const de = join(cache, m, "design-expert");
+		const latest = maxSemver(children$2(de).filter((v) => /^\d+\.\d+(\.\d+)?$/.test(v) && existsSync(join(de, v, "skills"))));
+		if (latest) return join(de, latest);
+	}
+	return "";
+}
+/**
+* The design-expert plugin root for the ACTIVE runtime ("" = not installed).
+* `pluginsDirOverride` short-circuits resolution (tests): a PLUGINS dir whose
+* `design-expert` child is used when present, else itself.
+*/
+function resolvePluginsRoot(pluginsDirOverride, home = homedir(), id = detectHarness().id, env = process.env) {
+	if (pluginsDirOverride) {
+		const de = join(pluginsDirOverride, "design-expert");
+		return existsSync(de) ? de : pluginsDirOverride;
+	}
+	if (id === "claude-code") return probeClaude$1(home);
+	if (id === "codex") return probeCodex$1(env, home);
+	return "";
+}
+/** Resolve the delivered refs-design/ root, or "" when absent/unusable (the fail-open signal). */
+function resolveCorpusRoot(pluginsDirOverride, home = homedir(), id = detectHarness().id, env = process.env) {
+	const root = resolvePluginsRoot(pluginsDirOverride, home, id, env);
+	if (!root) return "";
+	const corpus = join(root, CORPUS_SUFFIX);
+	return existsSync(corpus) ? corpus : "";
+}
+/**
+* Deny Write/Edit/apply_patch-file under the resolved plugins root: the corpus
+* is the artefact the pipeline checks reads against, so it must stay
+* agent-proof — including while refs-design/ is still absent. Relative paths
+* (the normal form of Codex patches) are resolved against `cwd` first. SCOPE:
+* no Bash, no symlinks, no sibling marketplace — the gate protects against
+* oversight, not an adversary (the mandatory screenshot stays the unforgeable
+* proof; forging the corpus only lowers a quota).
+*/
+function pluginsWriteGuard(filePath, pluginsRoot, cwd = "") {
+	const abs = isAbsolute(filePath) ? filePath : cwd ? normalize(join(cwd, filePath)) : filePath;
+	if (!pluginsRoot || !abs.startsWith(`${pluginsRoot}/`)) return null;
+	return {
+		kind: "block",
+		title: "Design pipeline",
+		reason: "BLOCKED: the design-expert plugin dir (refs-design corpus) is read-only — it is the taste reference your reads are checked against. Never create or modify files there.",
+		actions: ["Read the corpus with the Read tool; write your own files in the project"]
+	};
+}
+//#endregion
+//#region src/policy/design/corpus.ts
+/**
+* Corpus anchoring for the design pipeline: refs-design/ read classification,
+* per-mode readiness, citation form, citation↔read jointure. Nothing about
+* the corpus content (slugs, section titles, count) is hardcoded — everything
+* is matched by shape or discovered on disk, so a new reference or a renamed
+* section never requires reopening the harness. Pure string logic only; root
+* resolution and the write guard live in `corpus-resolve.ts`.
+*/
+const TOKENS_RE = /^tokens-.+\.md$/;
+const CORPUS_LINE_RE = /^[-*]\s*Corpus:\s*(.+)$/gim;
+/** Classify a read path against the DELIVERED corpus root (null = not a corpus read). */
+function classifyCorpusRead(filePath, corpusRoot) {
+	if (!corpusRoot) return null;
+	if (filePath === join(corpusRoot, "README.md")) return "index";
+	if (filePath.startsWith(`${corpusRoot}/`) && TOKENS_RE.test(basename(filePath))) return "tokens";
+	return null;
+}
+/** Per-mode corpus-read threshold (component >= 1 file, page >= 2 files, full = index + 2 tokens). */
+function corpusReady(reads, mode) {
+	if (mode === "component") return reads.length >= 1;
+	if (mode === "page") return reads.length >= 2;
+	return reads.includes("README.md") && reads.filter((r) => TOKENS_RE.test(basename(r))).length >= 2;
+}
+/** True when the content carries a `- Corpus: ref/section` citation line (form only). */
+function hasCorpusCitation(content) {
+	return citedCorpusRefs(content).length > 0;
+}
+/**
+* Extract the reference slugs cited on EVERY `- Corpus:` line (token before
+* `/`, or a bare slug). Anchored at line start with NO indentation
+* (fail-closed: a citation inside a code block does not count — an indented
+* match would also recognize the examples inside the doctrine doc itself).
+* The regex is fence-blind, documented: a `- Corpus:` line at column 0 inside
+* a fenced block WILL be matched — its refs must join like any other.
+*/
+function citedCorpusRefs(content) {
+	const refs = [];
+	for (const m of content.matchAll(CORPUS_LINE_RE)) {
+		const line = m[1] ?? "";
+		refs.push(...line.split(",").map((item) => item.trim().match(/^([\w][\w-]*)(?:\/|\s|$)/)?.[1] ?? "").filter(Boolean));
+	}
+	return refs;
+}
+/**
+* True when the cited ref names a REFERENCE in a recorded corpus read, in
+* either naming convention (`reve` README-style ↔ `reve-recode/` on disk —
+* the `-recode` suffix is normalized away on BOTH sides) and either layout
+* (per-reference directories, or flat `tokens-<ref>.md` files). Comparison is
+* exact after normalization: no prefix matching, so `acme` never joins
+* `acme-corp`, `tokens` never joins every tokens file, and `README` names no
+* reference.
+*/
+function citationJoinsReads(ref, reads) {
+	const norm = (s) => s.replace(/\.md$/, "").replace(/-recode$/, "");
+	const target = norm(ref);
+	return reads.some((r) => {
+		const segs = r.split("/");
+		const file = segs[segs.length - 1] ?? "";
+		const names = segs.slice(0, -1).map(norm);
+		if (file.startsWith("tokens-")) names.push(norm(file.slice(7)));
+		return names.includes(target);
+	});
+}
+//#endregion
+//#region src/policy/design/transitions.ts
+/** Infer the pipeline mode from the launch prompt + whether a design-system.md already exists. */
+function detectMode(prompt, designSystemExists) {
+	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, corpusRequired) {
+	if (state.currentPhase >= 2) return state;
+	if (!(!corpusRequired || corpusReady(state.corpusReads, state.mode)) || state.screenshotsCount < quotaFor(state.mode, corpusRequired)) return state;
+	return {
+		...state,
+		currentPhase: 2,
+		phasesCompleted: [.../* @__PURE__ */ new Set([
+			...state.phasesCompleted,
+			"identity",
+			"research"
+		])]
+	};
+}
+/** Record a screenshot: bump the count, then re-evaluate the phase-2 conjunction. */
+function recordScreenshot(state, corpusRequired) {
+	return maybePhase2({
+		...state,
+		screenshotsCount: state.screenshotsCount + 1
+	}, corpusRequired);
+}
+/** Record a fuse-browser navigate (resets the scroll-before-screenshot guard). */
+function recordNavigate(state) {
+	return {
+		...state,
+		scrolledSinceNav: false
+	};
+}
+/** Record a fuse-browser scroll (satisfies the scroll-before-screenshot guard). */
+function recordScroll(state) {
+	return {
+		...state,
+		scrolledSinceNav: true
+	};
+}
+/** Mark the design system validated and advance to phase 3 (after a passing create_frontend check). */
+function recordValidDesignSystem(state) {
+	return {
+		...state,
+		designSystemExists: true,
+		designSystemValid: true,
+		currentPhase: Math.max(state.currentPhase, 3),
+		phasesCompleted: [.../* @__PURE__ */ 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.
+*/
+function recordCorpusRead(state, relPath, corpusRequired) {
+	return maybePhase2({
+		...state,
+		corpusReads: [.../* @__PURE__ */ 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.
+*/
+function recordRead(state, filePath, corpusRequired = false) {
+	const next = { ...state };
+	if (filePath.includes("design-system/SKILL.md")) {
+		next.currentPhase = Math.max(state.currentPhase, 1);
+		next.phasesCompleted = [.../* @__PURE__ */ new Set([...state.phasesCompleted, "identity"])];
+	}
+	if (filePath.includes("design-inspiration")) next.inspirationRead = true;
+	return maybePhase2(next, corpusRequired);
+}
+//#endregion
 //#region src/policy/design/flag.ts
 const flagPath = (cacheDir) => join(cacheDir, "design-agent-active");
 /** The active design agent id (the flag), or "" when no design agent is running. */
@@ -1248,15 +1461,13 @@ function freshPassingReceipt(track, windowMs, now) {
 	return hits.length ? hits.reduce((a, b) => b.ts > a.ts ? b : a) : null;
 }
 /**
-* Sync variant reading the signed track file directly — for the sync gates
-* (TaskCompleted / SubagentStop). Returns the newest passing receipt, or `null`
-* on any read/verify failure (fail-closed: no proof ⇒ treated as unverified).
+* Sync variant reading the track directly (snapshot ⊕ journal) — for the sync
+* gates (TaskCompleted / SubagentStop). Returns the newest passing receipt, or
+* `null` on any read/verify failure (fail-closed: no proof ⇒ unverified).
 */
 function freshReceiptFromFile(file, windowMs, now) {
 	try {
-		if (!existsSync(file)) return null;
-		const track = verifyTrack(JSON.parse(readFileSync(file, "utf-8")));
-		return track ? freshPassingReceipt(track, windowMs, now) : null;
+		return freshPassingReceipt(readTrackSync(file, trackJournalEnabled()), windowMs, now);
 	} catch {
 		return null;
 	}
@@ -1754,36 +1965,6 @@ function postEditTypescript(filePath) {
 	return contextResponse("PostToolUse", `Lint issues in ${basename(filePath)}: ${issues.join(" | ")}`);
 }
 //#endregion
-//#region src/util/semver.ts
-/**
-* Dependency-free semver ordering. `Array.prototype.sort()` compares strings
-* lexicographically — `"1.0.9" > "1.0.23"` — so versioned directories (plugin
-* caches) must be ordered with a numeric, segment-by-segment comparison.
-*/
-/**
-* Compare two dotted version strings numerically, segment by segment
-* (shorter version wins when a prefix is equal: `1.0` < `1.0.1`). A segment
-* that is not a plain integer (prerelease tag like `0-beta`) falls back to
-* lexicographic comparison of that segment — never NaN, so `sort()` stays
-* defined; identical strings compare 0.
-* @returns Negative when `a < b`, positive when `a > b`, 0 when equal.
-*/
-function compareSemver(a, b) {
-	const pa = a.split("."), pb = b.split(".");
-	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-		const sa = pa[i] ?? "0", sb = pb[i] ?? "0";
-		if (sa === sb) continue;
-		const na = Number(sa), nb = Number(sb);
-		if (Number.isInteger(na) && Number.isInteger(nb) && na !== nb) return na - nb;
-		return sa < sb ? -1 : 1;
-	}
-	return 0;
-}
-/** The highest version of the list, or null when empty. */
-function maxSemver(versions) {
-	return versions.length === 0 ? null : versions.reduce((a, b) => compareSemver(a, b) >= 0 ? a : b);
-}
-//#endregion
 //#region src/runtime/lifecycle/rules-root.ts
 /**
 * Dynamic rules-plugin root resolution. The historical `CLAUDE_PLUGIN_ROOT ??
@@ -2115,62 +2296,6 @@ function harvestAgentEvidence(transcriptPath, track, now) {
 	return uses.reduce((acc, u) => applyToolUse(acc, u, now), track);
 }
 //#endregion
-//#region src/tracking/track-lock-sync.ts
-/**
-* Synchronous twin of {@link withTrackLock} for lifecycle paths that CANNOT
-* float async work (the SubagentStop dispatch runs synchronously in a
-* short-lived hook process — an async write could be dropped before exit,
-* see `evidence-harvest-io.ts`). Same semantics: `wx` lockfile, bounded total
-* retry, named skipped write on contention, stale reclamation. The wait uses
-* `Atomics.wait` (allowed on the main thread in both Node and Bun).
-*/
-/** Block the thread for `ms` (bounded by the caller's total budget). */
-function sleepSync(ms) {
-	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-/** True when the lockfile is older than the TTL (orphaned by a dead process). */
-function isStale(lock) {
-	try {
-		return Date.now() - statSync(lock).mtimeMs > LOCK_TTL_MS;
-	} catch {
-		return false;
-	}
-}
-/**
-* Run `fn` under the track lock of `dir`, synchronously.
-* @param dir - The track state directory (lockfile lives inside).
-* @param fn - The protected read-modify-write.
-* @returns `fn`'s result, or {@link LOCK_FAILED} when the lock stayed busy.
-*/
-function withTrackLockSync(dir, fn) {
-	mkdirSync(dir, { recursive: true });
-	const lock = join(dir, "track.lock");
-	const deadline = Date.now() + 400;
-	for (;;) try {
-		closeSync(openSync(lock, "wx"));
-		break;
-	} catch {
-		if (isStale(lock)) {
-			try {
-				unlinkSync(lock);
-			} catch {}
-			continue;
-		}
-		if (Date.now() >= deadline) {
-			process.stderr.write(`harness: track lock busy, write skipped (${lock})\n`);
-			return LOCK_FAILED;
-		}
-		sleepSync(8);
-	}
-	try {
-		return fn();
-	} finally {
-		try {
-			unlinkSync(lock);
-		} catch {}
-	}
-}
-//#endregion
 //#region src/freshness/evidence-harvest-io.ts
 /**
 * SubagentStop wiring for {@link harvestAgentEvidence}. The core SubagentStop
@@ -2204,6 +2329,14 @@ function harvestSubagentTrack(payload, cwd, now, baseDir = defaultStateDir(cwd))
 	const transcriptPath = typeof payload.agent_transcript_path === "string" ? payload.agent_transcript_path : void 0;
 	if (!transcriptPath) return;
 	const file = trackFile(typeof payload.session_id === "string" ? payload.session_id : "unknown", baseDir);
+	if (trackJournalEnabled()) {
+		const track = readTrackSync(file, true);
+		const next = harvestAgentEvidence(transcriptPath, track, now);
+		if (next === track) return;
+		const log = journalLogPath(file);
+		for (const ev of diffTrackEvents(track, next, now)) appendEvent(log, ev.field, ev.op, ev.value, ev.ts);
+		return;
+	}
 	if (withTrackLockSync(dirname(file), () => {
 		const track = loadTrackSync(file);
 		const next = harvestAgentEvidence(transcriptPath, track, now);
@@ -7752,15 +7885,9 @@ function uiDesignSkillGate(tool, filePath, content, ev) {
 //#endregion
 //#region src/policy/design/skill-evidence.ts
 /**
-* @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
-*/
-/**
-* Read the verified session track and derive {@link DesignEvidence}. Fail-closed
-* on a missing/corrupt/tampered track (no evidence → the gate blocks).
+* 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.
@@ -7768,7 +7895,7 @@ function uiDesignSkillGate(tool, filePath, content, ev) {
 function collectDesignEvidence(sessionId, cwd, baseDir = defaultStateDir(cwd)) {
 	let track = null;
 	try {
-		track = verifyTrack(JSON.parse(readFileSync(trackFile(sessionId, baseDir), "utf8")));
+		track = readTrackSync(trackFile(sessionId, baseDir), trackJournalEnabled());
 	} catch {
 		track = null;
 	}
@@ -7778,45 +7905,39 @@ function collectDesignEvidence(sessionId, cwd, baseDir = defaultStateDir(cwd)) {
 	};
 }
 //#endregion
-//#region src/runtime/design-helpers.ts
+//#region src/policy/design/design-system-rules.ts
 /**
-* @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
+* 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.
 */
-const NAV$2 = "mcp__fuse-browser__browser_navigate";
-const SHOT$2 = "mcp__fuse-browser__browser_screenshot";
-const SCROLL = "mcp__fuse-browser__browser_scroll";
-const GEMINI$2 = "mcp__gemini-design__create_frontend";
-/** Read design-system.md walking up to 6 parents from `cwd` ("" if absent/unreadable). */
-function findDesignSystem(cwd) {
-	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. */
-function recordPost(event, cacheDir, state) {
-	if (event.tool === SHOT$2) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
-	else if (event.tool === NAV$2) saveDesignState(cacheDir, recordNavigate(state));
-	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
-	else if (event.tool === GEMINI$2) saveDesignState(cacheDir, {
-		...state,
-		geminiCalls: state.geminiCalls + 1
-	});
-	else if (event.tool === "Read") saveDesignState(cacheDir, recordRead(state, event.filePath ?? ""));
-	else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) saveDesignState(cacheDir, recordValidDesignSystem(state));
+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 (`--*font*`/`--*ff*`/`--*type*`), `@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.
+*/
+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*\|/;
+/**
+* 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).
+*/
+function validateDesignSystem(content, corpusCitationOk = false) {
+	const missing = [];
+	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)) missing.push("forbidden font (Inter/Roboto/Arial/Open Sans)");
+	return missing;
 }
 //#endregion
 //#region src/policy/design/gates.ts
@@ -7827,16 +7948,9 @@ const EXEMPT_DIRS = [
 	"build/",
 	".claude/"
 ];
-const FORBIDDEN_FONTS = [
-	"Inter",
-	"Roboto",
-	"Arial",
-	"Open Sans"
-];
-const OKLCH_RE = /oklch\(\s*[\d.]+%?\s+0\.0*[1-9]/;
-const NAV$1 = "mcp__fuse-browser__browser_navigate";
-const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
-const GEMINI$1 = "mcp__gemini-design__create_frontend";
+const NAV$2 = "mcp__fuse-browser__browser_navigate";
+const SHOT$2 = "mcp__fuse-browser__browser_screenshot";
+const GEMINI$2 = "mcp__gemini-design__create_frontend";
 const deny = (reason) => ({
 	kind: "block",
 	title: "Design pipeline",
@@ -7852,15 +7966,6 @@ function htmlCssOnlyGate(filePath) {
 function stateFileGate(filePath) {
 	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;
 }
-/** Return the requirements missing from a design-system.md (empty = valid). */
-function validateDesignSystem(content) {
-	const missing = [];
-	if (!content.includes("## Design Reference")) missing.push("## Design Reference section");
-	if (!/https?:\/\//.test(content)) missing.push("reference URL (https://…)");
-	if (!OKLCH_RE.test(content)) missing.push("oklch() color with chroma > 0");
-	if (FORBIDDEN_FONTS.some((f) => content.includes(f))) missing.push("forbidden font (Inter/Roboto/Arial/Open Sans)");
-	return missing;
-}
 /** Gate a screenshot: require a scroll since the last navigate (lazy-load content). */
 function screenshotScrollGate(state) {
 	return state.scrolledSinceNav ? null : deny("BLOCKED: scroll the page before a screenshot — browser_scroll to:'end', wait, scroll back, then fullPage screenshot.");
@@ -7888,10 +7993,11 @@ function designPassNotice(i, cacheDir) {
 	}
 	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$1) lines.push(`check-inspiration-read: pass (${i.url})`);
-		if (i.tool === GEMINI$1 && geminiEnabled()) lines.push("validate-design-system: design-system.md ok");
-		if (isWrite || i.tool === NAV$1 || i.tool === SHOT$1 || i.tool === GEMINI$1) lines.push(`pipeline-gate: phase ${state.currentPhase} ok`);
+		if (i.tool === NAV$2) lines.push(`check-inspiration-read: pass (${i.url})`);
+		if (i.tool === GEMINI$2 && geminiEnabled()) lines.push("validate-design-system: design-system.md ok");
+		if (isWrite || i.tool === NAV$2 || i.tool === SHOT$2 || i.tool === GEMINI$2) 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");
@@ -7905,41 +8011,292 @@ function designPassNotice(i, cacheDir) {
 	} : null;
 }
 //#endregion
+//#region src/policy/design/template-urls.ts
+/**
+* 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 = [
+	"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 = [
+	"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) {
+	return (/^https?:\/\/(?:[^@/?#]*@)?([^/:?#]+)/i.exec(url)?.[1] ?? "").replace(/\.$/, "").toLowerCase();
+}
+const under = (host, domain) => host === domain || host.endsWith(`.${domain}`);
+/** True when `url` points at a banned template source (host rule, then platform path rule). */
+function isTemplateUrl(url) {
+	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);
+}
+//#endregion
 //#region src/policy/design/gates-pipeline.ts
 const SKILLS = `${PLUGINS_DIR}/design-expert/skills`;
-const KNOWN_DOMAINS = [
-	"framer.website",
-	"webflow.io",
-	"awwwards.com",
-	"godly.website",
-	"lapa.ninja",
-	"onepagelove.com",
-	"saasframe.io",
-	"bestwebsite.gallery",
-	"landingfolio.com"
-];
 /** Gate writing design-system.md: requires phase >= 2 and the per-mode screenshot quota. */
-function designSystemWriteGate(filePath, state) {
+function designSystemWriteGate(filePath, state, corpusRequired = false) {
 	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) Browse sites and take a screenshot with mcp__fuse-browser__browser_screenshot on a LIVE session (note: browser_shots_batch/browser_site_shots do NOT advance the phase) 4) Then write design-system.md`);
-	const needed = MIN_SCREENSHOTS[state.mode];
-	if (state.screenshotsCount < needed) return deny(`BLOCKED: ${state.screenshotsCount}/${needed} screenshots for mode '${state.mode}'. RECOVERY: 1) Take ${needed - state.screenshotsCount} more screenshots with mcp__fuse-browser__browser_screenshot (browser_shots_batch/browser_site_shots do NOT count) 2) Use browser_open + browser_navigate + browser_screenshot fullPage:true 3) Then write design-system.md`);
+	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 (note: browser_shots_batch/browser_site_shots do NOT advance the phase) 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 do NOT count) 3) Use browser_open + browser_navigate + browser_screenshot fullPage:true 4) Then write design-system.md`);
 	return null;
 }
 /** Gate Gemini create_frontend: requires phase >= 3 and a validated design system. */
 function geminiCreateGate(state) {
-	if (state.currentPhase < 3) return deny("BLOCKED: Cannot call Gemini create_frontend before phase 3. RECOVERY: 1) Complete screenshot browsing phase 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 2) Then retry mcp__gemini-design__create_frontend");
+	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, URL in the catalog. */
+/**
+* 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".
+*/
 function browserNavigateGate(state, url) {
 	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 inspiration catalog first. READ: ${SKILLS}/design-web/references/design-inspiration.md + design-inspiration-urls.md`);
-	if (state.currentPhase === 1 && url && !KNOWN_DOMAINS.some((d) => url.includes(d))) return deny(`BLOCKED: '${url}' not in catalog. Use URLs from design-inspiration-urls.md. Domains: ${KNOWN_DOMAINS.join(", ")}`);
+	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;
+}
+//#endregion
+//#region src/runtime/design-files-gate.ts
+/**
+* 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.
+*/
+function substituteLiteral(s, from, to, all) {
+	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. */
+function designFilesGate(files, state, pluginsRoot, corpusRoot, corpusRequired, cwd) {
+	for (const f of files) {
+		const hit = pluginsWriteGuard(f.filePath, pluginsRoot, cwd) ?? stateFileGate(f.filePath);
+		if (hit) return hit;
+		if (f.op === "delete") continue;
+		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: void 0,
+			replaceAll: false,
+			state,
+			corpusRoot,
+			corpusRequired
+		}) : null);
+		if (gate) return gate;
+	}
 	return null;
 }
 //#endregion
+//#region src/runtime/design-content-gate.ts
+/**
+* @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
+*/
+/**
+* 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.
+*/
+function designSystemProblems(content, reads, corpusRequired) {
+	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). */
+function checkDesignSystemContent(content, reads, corpusRequired) {
+	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) {
+	if (i.tool !== "Edit") {
+		let original = null;
+		try {
+			if (existsSync(i.filePath)) original = readFileSync(i.filePath, "utf8");
+		} catch {
+			original = null;
+		}
+		return {
+			result: i.content,
+			original
+		};
+	}
+	let disk;
+	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.
+*/
+function designSystemContentGate(i) {
+	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.`);
+}
+//#endregion
+//#region src/runtime/design-helpers.ts
+/**
+* @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
+*/
+const NAV$1 = "mcp__fuse-browser__browser_navigate";
+const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
+const SCROLL = "mcp__fuse-browser__browser_scroll";
+const GEMINI$1 = "mcp__gemini-design__create_frontend";
+/** Read design-system.md walking up to 6 parents from `cwd` ("" if absent/unreadable). */
+function findDesignSystem(cwd) {
+	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. */
+function recordPost(event, cacheDir, state, corpusRoot = "", corpusRequired = false, cwd = "") {
+	if (event.tool === SHOT$1) saveDesignState(cacheDir, recordScreenshot(state, corpusRequired));
+	else if (event.tool === NAV$1) saveDesignState(cacheDir, recordNavigate(state));
+	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
+	else if (event.tool === GEMINI$1) saveDesignState(cacheDir, {
+		...state,
+		geminiCalls: state.geminiCalls + 1
+	});
+	else if (event.tool === "Read") {
+		const fp = event.filePath ?? "";
+		if (classifyCorpusRead(fp, corpusRoot) && existsSync(fp)) saveDesignState(cacheDir, recordCorpusRead(state, fp.slice(corpusRoot.length + 1), corpusRequired));
+		else saveDesignState(cacheDir, recordRead(state, fp, corpusRequired));
+	} else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) {
+		const fp = event.filePath ?? "";
+		let content;
+		try {
+			content = readFileSync(fp, "utf8");
+		} catch {
+			return;
+		}
+		const problems = designSystemProblems(content, state.corpusReads, corpusRequired);
+		if (!problems.length) {
+			saveDesignState(cacheDir, recordValidDesignSystem(state));
+			return;
+		}
+		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);
+			if (problems.filter((p) => !designSystemProblems(original, state.corpusReads, corpusRequired).includes(p)).length) saveDesignState(cacheDir, {
+				...state,
+				designSystemValid: false
+			});
+		}
+	} else if (event.files) {
+		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;
+			try {
+				content = readFileSync(abs, "utf8");
+			} catch {
+				return;
+			}
+			if (!designSystemProblems(content, state.corpusReads, corpusRequired).length) saveDesignState(cacheDir, recordValidDesignSystem(state));
+		}
+	}
+}
+//#endregion
 //#region src/runtime/design.ts
 const NAV = "mcp__fuse-browser__browser_navigate";
 const SHOT = "mcp__fuse-browser__browser_screenshot";
@@ -7948,7 +8305,7 @@ 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.
 */
-function designGate(payload, event, cacheDir, cwd) {
+function designGate(payload, event, cacheDir, cwd, corpusRootOverride, pluginsRootOverride) {
 	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;
@@ -7965,8 +8322,11 @@ function designGate(payload, event, cacheDir, cwd) {
 		state = initDesignState(id, dsExists ? "page" : "full", dsExists);
 		saveDesignState(cacheDir, state);
 	}
+	const corpusRoot = corpusRootOverride ?? resolveCorpusRoot();
+	const corpusRequired = corpusRoot !== "";
+	const pluginsRoot = pluginsRootOverride ?? resolvePluginsRoot();
 	if (event.phase === "post") {
-		recordPost(event, cacheDir, state);
+		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 {
@@ -7980,7 +8340,16 @@ function designGate(payload, event, cacheDir, cwd) {
 	}
 	if (event.tool === "Write" || event.tool === "Edit") {
 		const fp = event.filePath ?? "";
-		const base = stateFileGate(fp) ?? htmlCssOnlyGate(fp) ?? designSystemWriteGate(fp, state);
+		const base = pluginsWriteGuard(fp, pluginsRoot) ?? stateFileGate(fp) ?? htmlCssOnlyGate(fp) ?? 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",
@@ -7990,6 +8359,7 @@ function designGate(payload, event, cacheDir, cwd) {
 		};
 		return null;
 	}
+	if (event.files && event.files.length > 0) return designFilesGate(event.files, state, pluginsRoot, corpusRoot, corpusRequired, 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) {
@@ -8000,16 +8370,11 @@ function designGate(payload, event, cacheDir, cwd) {
 		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) Browse 4 reference sites 4) Write design-system.md, then retry create_frontend.",
+			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"]
 		};
-		const missing = validateDesignSystem(ds);
-		if (missing.length) return {
-			kind: "block",
-			title: "Design pipeline",
-			reason: `BLOCKED: design-system.md too generic. Missing: ${missing.join(", ")}.`,
-			actions: ["Fix design-system.md, then retry create_frontend"]
-		};
+		const contentBlock = checkDesignSystemContent(ds, state.corpusReads, corpusRequired);
+		if (contentBlock) return contentBlock;
 		saveDesignState(cacheDir, recordValidDesignSystem(state));
 	}
 	return null;
@@ -8252,14 +8617,16 @@ async function freshEvidenceNotice(event, evidence, cwd) {
 * @param evidence - Session track + clock for the "evidence fresh" notice (omit to disable it).
 * @returns The native hook outcome (empty stdout when nothing to emit).
 */
-async function allowOutcome(id, event, payload, mcpDir, cwd, evidence) {
+async function allowOutcome(id, event, payload, mcpDir, cwd, evidence, corpusRoot) {
+	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
 	const notice = designPassNotice({
-		agentId: typeof payload.agent_id === "string" ? payload.agent_id : "",
+		agentId,
 		tool: event.tool,
 		filePath: event.filePath ?? "",
 		content: event.content ?? "",
 		url: typeof event.input.url === "string" ? event.input.url : "",
-		phase: "pre"
+		phase: "pre",
+		corpusMissing: agentId !== "" && (corpusRoot ?? resolveCorpusRoot()) === ""
 	}, mcpDir);
 	const lesson = lessonFor(event.tool, event.input, {
 		file: lessonsFileFor(projectRoot(cwd)),
@@ -8359,7 +8726,7 @@ async function handlePre(ctx) {
 			exit: 0
 		};
 	}
-	const designBlock = designGate(payload, event, mcpDir, opts.cwd);
+	const designBlock = designGate(payload, event, mcpDir, opts.cwd, opts.corpusRoot);
 	if (designBlock) return {
 		stdout: withDenyNotice(id, respond(id, designBlock), designBlock, event.sessionId, dirname(file), opts.now),
 		exit: 0
@@ -8410,7 +8777,7 @@ async function handlePre(ctx) {
 		trackFile: file,
 		windowMs: opts.windowMs,
 		now: opts.now
-	});
+	}, opts.corpusRoot);
 }
 //#endregion
 //#region src/freshness/query-framework.ts
@@ -8918,7 +9285,7 @@ async function handlePost(ctx) {
 	const { id, payload, event, framework, mcpDir, file, opts } = ctx;
 	const response = payload.tool_response ?? payload.tool_output;
 	mcpPostStore(event.tool, event.input, response, mcpDir);
-	const designWarn = designGate(payload, event, mcpDir, opts.cwd);
+	const designWarn = designGate(payload, event, mcpDir, opts.cwd, opts.corpusRoot);
 	const activities = activityFor({
 		tool: event.tool,
 		input: event.input,