@lemoncode/lemony 0.4.1 → 0.5.1

package/dist/cli.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { access, appendFile, chmod, lstat, mkdir, open, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { basename, delimiter, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { argv, cwd, env, exit, stderr, stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
 import { parse, parseDocument } from "yaml";
+import { constants } from "node:fs";
 import { z } from "zod";
 import { createHash, randomBytes } from "node:crypto";
-import { constants } from "node:fs";
 //#region src/events/append.ts
 const appendEvent = async (eventsPath, event) => {
 	await mkdir(dirname(eventsPath), { recursive: true });
@@ -27,7 +27,8 @@ const DEPRECATED_IMPLEMENTATION_KEYS = ["pre_commit_review"];
 const HARNESS_CONFIG_SCHEMA_FILENAME = "harness.config.schema.json";
 const CONFIG_KEY_SINCE = {
 	gates: "0.3.0",
-	"implementation.auto_commit": "0.4.0"
+	"implementation.auto_commit": "0.4.0",
+	"design_tokens.verify": "0.5.0"
 };
 const TASK_STORAGE_REPO_PLACEHOLDER = "OWNER/REPO";
 const TARGETS = ["claude-code"];
@@ -46,6 +47,136 @@ const PATHS_DEFAULTS = {
 	playbooks_global: "~/.claude/playbooks"
 };
 //#endregion
+//#region src/fs/exists.ts
+const pathExists = async (path) => {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const entryExists = async (path) => {
+	try {
+		await lstat(path);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+};
+//#endregion
+//#region src/fs/list-files.ts
+const listFiles = async (dir) => {
+	const entries = await readdir(dir, { withFileTypes: true });
+	return (await Promise.all(entries.map(async (entry) => {
+		if (entry.isDirectory()) return (await listFiles(join(dir, entry.name))).map((rel) => join(entry.name, rel));
+		return [entry.name];
+	}))).flat();
+};
+//#endregion
+//#region src/fs/prune-empty-dirs.ts
+const pruneEmptyDirs = async (repoRoot, removedFiles) => {
+	const dirs = /* @__PURE__ */ new Set();
+	for (const relPath of removedFiles) {
+		let dir = dirname(relPath);
+		while (dir !== "." && dir !== sep) {
+			dirs.add(dir);
+			dir = dirname(dir);
+		}
+	}
+	const ordered = [...dirs].toSorted((a, b) => b.length - a.length);
+	for (const dir of ordered) try {
+		await rmdir(join(repoRoot, dir));
+	} catch {}
+};
+//#endregion
+//#region src/fs/fs.constant.ts
+const SPECIAL_FILE_REFUSAL = "the entry is not a regular file (a FIFO, a socket or a device), so it was not read.";
+const DANGLING_WRITE_REFUSAL = "the entry is a symlink whose target is missing, so it was not written (writing through it would create the file it points at).";
+const SPECIAL_FILE_WRITE_REFUSAL = "the entry is not a regular file (a FIFO, a socket or a device), so it was not written.";
+//#endregion
+//#region src/fs/read-regular-file.ts
+const readRegularFile = async (path) => {
+	let handle;
+	try {
+		handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	} catch (error) {
+		const target = await stat(path).catch(() => void 0);
+		if (target && !target.isFile() && !target.isDirectory()) throw new Error(SPECIAL_FILE_REFUSAL, { cause: error });
+		throw error;
+	}
+	try {
+		const target = await handle.stat();
+		if (!target.isFile() && !target.isDirectory()) throw new Error(SPECIAL_FILE_REFUSAL);
+		return await handle.readFile("utf8");
+	} finally {
+		await handle.close();
+	}
+};
+//#endregion
+//#region src/fs/write-managed.ts
+const writeManaged = async (root, relPath, content, executable) => {
+	const dest = join(root, relPath);
+	await mkdir(dirname(dest), { recursive: true });
+	await writeFile(dest, content);
+	await chmod(dest, executable ? 493 : 420);
+};
+//#endregion
+//#region src/fs/write-regular-file.ts
+const writeRegularFile = async (path, text) => {
+	let handle;
+	try {
+		handle = await openForWrite(path);
+	} catch (error) {
+		const target = await stat(path).catch(() => void 0);
+		if (target && !target.isFile() && !target.isDirectory()) throw new Error(SPECIAL_FILE_WRITE_REFUSAL, { cause: error });
+		throw error;
+	}
+	try {
+		if (!(await handle.stat()).isFile()) throw new Error(SPECIAL_FILE_WRITE_REFUSAL);
+		await handle.writeFile(text, "utf8");
+	} finally {
+		await handle.close();
+	}
+};
+const WRITE = constants.O_WRONLY | constants.O_TRUNC | constants.O_NONBLOCK;
+const openForWrite = async (path) => {
+	try {
+		return await open(path, WRITE);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	try {
+		return await open(path, WRITE | constants.O_CREAT | constants.O_EXCL);
+	} catch (error) {
+		const link = await lstat(path).catch(() => void 0);
+		if (error.code === "EEXIST" && link?.isSymbolicLink()) throw new Error(DANGLING_WRITE_REFUSAL, { cause: error });
+		throw error;
+	}
+};
+//#endregion
+//#region src/fs/symlink-guard.ts
+const assertNoSymlinkTraversal = async (root, relPaths) => {
+	const components = /* @__PURE__ */ new Set();
+	for (const relPath of relPaths) {
+		let current = "";
+		for (const part of relPath.split(sep)) {
+			if (part.length === 0) continue;
+			current = current ? join(current, part) : part;
+			components.add(current);
+		}
+	}
+	const offenders = (await Promise.all([...components].map(async (rel) => {
+		try {
+			return (await lstat(join(root, rel))).isSymbolicLink() ? rel : null;
+		} catch {
+			return null;
+		}
+	}))).filter((rel) => rel !== null);
+	if (offenders.length > 0) throw new Error("Refusing to write — a managed path traverses a symlink (a redirect could land outside the repo):\n" + offenders.map((rel) => `  ${rel}`).join("\n"));
+};
+//#endregion
 //#region src/config/config-error.ts
 const formatConfigError = (schema, error) => {
 	return error.issues.flatMap((issue) => formatIssue(schema, issue)).join("\n");
@@ -120,7 +251,10 @@ const taskStorageSchema = z.object({
 }).strict();
 const rollbackSchema = z.object({ keep_snapshots: z.union([z.int().positive(), z.literal("unlimited")]).default(3) }).strict().prefault({});
 const telemetrySchema = z.object({ enabled: z.boolean().default(true) }).strict().prefault({});
-const designTokensSchema = z.object({ scan_extensions: z.array(z.string()).default([]) }).strict().prefault({});
+const designTokensSchema = z.object({
+	scan_extensions: z.array(z.string()).default([]),
+	verify: z.string().trim().min(1).optional()
+}).strict().prefault({});
 const mergeSchema = z.object({
 	checks_timeout_secs: z.int().positive().default(600),
 	allow_no_checks: z.boolean().default(false)
@@ -145,7 +279,7 @@ const readHarnessConfig = async (repoRoot) => {
 	const configPath = join(repoRoot, HARNESS_CONFIG_FILENAME);
 	let raw;
 	try {
-		raw = await readFile(configPath, "utf8");
+		raw = await readRegularFile(configPath);
 	} catch (cause) {
 		if (cause.code === "ENOENT") throw new Error(`${HARNESS_CONFIG_FILENAME} not found at ${repoRoot}. Run \`lemony install\` first.`, { cause });
 		throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
@@ -175,6 +309,21 @@ const readHarnessConfig = async (repoRoot) => {
 	if (!result.success) throw new Error(`${HARNESS_CONFIG_FILENAME} is invalid:\n${formatConfigError(harnessConfigSchema, result.error)}`);
 	return result.data;
 };
+const readOptionalHarnessConfig = async (repoRoot) => {
+	let present;
+	try {
+		present = await entryExists(join(repoRoot, HARNESS_CONFIG_FILENAME));
+	} catch (error) {
+		throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	if (!present) return void 0;
+	try {
+		return await readHarnessConfig(repoRoot);
+	} catch (error) {
+		if (error.cause?.code === "ENOENT") throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
+		throw error;
+	}
+};
 //#endregion
 //#region src/config/compare-version.ts
 const PRERELEASE_RANK = {
@@ -257,8 +406,6 @@ const pointerScalar = z.union([
 	z.null()
 ]).optional();
 const pointerFrontmatterSchema = z.object({
-	active_task: pointerScalar,
-	branch: pointerScalar,
 	session_start_ts: pointerScalar,
 	last_close_ts: pointerScalar
 });
@@ -993,70 +1140,6 @@ const failureReason$1 = (result) => {
 	return `\`gh\` failed (exit ${result.code})${suffix}${detail ? `: ${detail}` : ""}`;
 };
 //#endregion
-//#region src/fs/exists.ts
-const pathExists = async (path) => {
-	try {
-		await stat(path);
-		return true;
-	} catch {
-		return false;
-	}
-};
-//#endregion
-//#region src/fs/list-files.ts
-const listFiles = async (dir) => {
-	const entries = await readdir(dir, { withFileTypes: true });
-	return (await Promise.all(entries.map(async (entry) => {
-		if (entry.isDirectory()) return (await listFiles(join(dir, entry.name))).map((rel) => join(entry.name, rel));
-		return [entry.name];
-	}))).flat();
-};
-//#endregion
-//#region src/fs/prune-empty-dirs.ts
-const pruneEmptyDirs = async (repoRoot, removedFiles) => {
-	const dirs = /* @__PURE__ */ new Set();
-	for (const relPath of removedFiles) {
-		let dir = dirname(relPath);
-		while (dir !== "." && dir !== sep) {
-			dirs.add(dir);
-			dir = dirname(dir);
-		}
-	}
-	const ordered = [...dirs].toSorted((a, b) => b.length - a.length);
-	for (const dir of ordered) try {
-		await rmdir(join(repoRoot, dir));
-	} catch {}
-};
-//#endregion
-//#region src/fs/write-managed.ts
-const writeManaged = async (root, relPath, content, executable) => {
-	const dest = join(root, relPath);
-	await mkdir(dirname(dest), { recursive: true });
-	await writeFile(dest, content);
-	await chmod(dest, executable ? 493 : 420);
-};
-//#endregion
-//#region src/fs/symlink-guard.ts
-const assertNoSymlinkTraversal = async (root, relPaths) => {
-	const components = /* @__PURE__ */ new Set();
-	for (const relPath of relPaths) {
-		let current = "";
-		for (const part of relPath.split(sep)) {
-			if (part.length === 0) continue;
-			current = current ? join(current, part) : part;
-			components.add(current);
-		}
-	}
-	const offenders = (await Promise.all([...components].map(async (rel) => {
-		try {
-			return (await lstat(join(root, rel))).isSymbolicLink() ? rel : null;
-		} catch {
-			return null;
-		}
-	}))).filter((rel) => rel !== null);
-	if (offenders.length > 0) throw new Error("Refusing to write — a managed path traverses a symlink (a redirect could land outside the repo):\n" + offenders.map((rel) => `  ${rel}`).join("\n"));
-};
-//#endregion
 //#region src/design-tokens/design-tokens.constant.ts
 const DESIGN_TOKENS_FILE = "docs/design-tokens.json";
 const SCANNED_EXTENSIONS = [
@@ -1099,6 +1182,19 @@ const IGNORED_DIRS = /* @__PURE__ */ new Set([
 	".cache",
 	".claude"
 ]);
+const NESTED_TOO_DEEPLY = `${DESIGN_TOKENS_FILE} nests deeper than 64 levels, the most Lemony reads.`;
+//#endregion
+//#region src/design-tokens/read-token-file.ts
+const readOptionalTokenFile = async (repoRoot) => {
+	const tokenPath = join(repoRoot, DESIGN_TOKENS_FILE);
+	try {
+		if (!await entryExists(tokenPath)) return void 0;
+		return await readRegularFile(tokenPath);
+	} catch (error) {
+		if (error.code === "ENOENT") throw new Error(`Cannot read ${DESIGN_TOKENS_FILE} at ${repoRoot}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
+		throw new Error(`Cannot read ${DESIGN_TOKENS_FILE} at ${repoRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+};
 //#endregion
 //#region src/design-tokens/design-tokens.model.ts
 const TOKEN_TIERS = [
@@ -1107,6 +1203,46 @@ const TOKEN_TIERS = [
 	"component"
 ];
 //#endregion
+//#region src/design-tokens/contrast.constant.ts
+const CONTRAST_EXTENSION = "com.lemony.contrast";
+const MODES_EXTENSION = "com.lemony.modes";
+const BASE_MODE = "base";
+const DEFAULT_LEVEL = "text";
+const WCAG_FLOORS = {
+	text: 4.5,
+	large: 3,
+	"non-text": 3
+};
+//#endregion
+//#region src/design-tokens/nesting-depth.ts
+const exceedsNestingLimit = (value, limit = 64) => {
+	const pending = [{
+		node: value,
+		depth: 1
+	}];
+	for (let next = pending.pop(); next !== void 0; next = pending.pop()) {
+		const { node, depth } = next;
+		if (typeof node !== "object" || node === null) continue;
+		if (depth > limit) return true;
+		for (const child of Object.values(node)) pending.push({
+			node: child,
+			depth: depth + 1
+		});
+	}
+	return false;
+};
+//#endregion
+//#region src/design-tokens/non-finite-number.ts
+const nonFiniteNumberFaults = (value) => nonFiniteNumbers(value, []).map(({ path, number }) => `${DESIGN_TOKENS_FILE} has a number at "${path}" too large for JSON to carry: it reads as ${number}, and rewriting the file would turn it into null.`);
+const nonFiniteNumbers = (value, path) => {
+	if (typeof value === "number") return Number.isFinite(value) ? [] : [{
+		path: path.join("."),
+		number: value
+	}];
+	if (typeof value !== "object" || value === null) return [];
+	return Object.entries(value).flatMap(([key, child]) => nonFiniteNumbers(child, [...path, key]));
+};
+//#endregion
 //#region src/design-tokens/token-parse.ts
 const aliasTarget = (value) => {
 	if (typeof value !== "string") return void 0;
@@ -1117,15 +1253,28 @@ const isRecord = (value) => typeof value === "object" && value !== null && !Arra
 //#endregion
 //#region src/design-tokens/design-tokens.ts
 const runValidate = async (inputs) => {
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return {
+	let raw;
+	try {
+		raw = await readOptionalTokenFile(inputs.repoRoot);
+	} catch (error) {
+		return {
+			ok: false,
+			tokensFound: true,
+			tokenCount: 0,
+			filesScanned: 0,
+			violations: [{
+				kind: "unreadable-token-file",
+				message: error instanceof Error ? error.message : String(error)
+			}]
+		};
+	}
+	if (raw === void 0) return {
 		ok: true,
 		tokensFound: false,
 		tokenCount: 0,
 		filesScanned: 0,
 		violations: []
 	};
-	const raw = await readFile(tokenPath, "utf8");
 	const fileCheck = validateTokenFile(raw);
 	if (!fileCheck.ok) return {
 		ok: false,
@@ -1135,6 +1284,19 @@ const runValidate = async (inputs) => {
 		violations: fileCheck.violations
 	};
 	const scanRoot = inputs.scanDir ? join(inputs.repoRoot, inputs.scanDir) : inputs.repoRoot;
+	if (inputs.scanDir) {
+		const unreadable = await describeUnreadableDir(scanRoot);
+		if (unreadable !== void 0) return {
+			ok: false,
+			tokensFound: true,
+			tokenCount: fileCheck.tokenCount,
+			filesScanned: 0,
+			violations: [{
+				kind: "unreadable-scan-root",
+				message: `--scan=${inputs.scanDir} ${unreadable} — nothing was scanned.`
+			}]
+		};
+	}
 	const extensions = mergeExtensions(inputs.extraExtensions);
 	const sourceViolations = await scanSource(inputs.repoRoot, scanRoot, extensions);
 	return {
@@ -1145,6 +1307,13 @@ const runValidate = async (inputs) => {
 		violations: sourceViolations.violations
 	};
 };
+const summarizeTokenFileViolations = (raw) => summarizeMessages(tokenFileViolationMessages(raw));
+const tokenFileViolationMessages = (raw) => validateTokenFile(raw).violations.map((violation) => violation.message);
+const summarizeMessages = (messages) => {
+	const [first, ...more] = messages;
+	if (first === void 0) return void 0;
+	return `${first}${more.length > 0 ? ` (and ${more.length} more)` : ""}`;
+};
 const validateTokenFile = (raw) => {
 	let parsed;
 	try {
@@ -1167,7 +1336,19 @@ const validateTokenFile = (raw) => {
 			message: `${DESIGN_TOKENS_FILE} must be a JSON object with primitive/semantic/component tiers.`
 		}]
 	};
+	if (exceedsNestingLimit(parsed)) return {
+		ok: false,
+		tokenCount: 0,
+		violations: [{
+			kind: "malformed-token-file",
+			message: NESTED_TOO_DEEPLY
+		}]
+	};
 	const violations = [];
+	for (const message of nonFiniteNumberFaults(parsed)) violations.push({
+		kind: "malformed-token-file",
+		message
+	});
 	for (const key of Object.keys(parsed)) {
 		if (key.startsWith("$")) continue;
 		if (!TOKEN_TIERS.includes(key)) violations.push({
@@ -1195,6 +1376,10 @@ const validateTokenFile = (raw) => {
 		violations
 	};
 };
+const modeValues = (extensions) => {
+	const modes = isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
+	return isRecord(modes) ? modes : {};
+};
 const collectTokens$1 = (node, tier, path, out, violations) => {
 	for (const [key, child] of Object.entries(node)) {
 		if (key.startsWith("$")) continue;
@@ -1209,7 +1394,8 @@ const collectTokens$1 = (node, tier, path, out, violations) => {
 		if ("$value" in child) {
 			out.set(childPath, {
 				tier,
-				value: child.$value
+				value: child.$value,
+				modes: modeValues(child["$extensions"])
 			});
 			const stray = Object.keys(child).filter((k) => !k.startsWith("$"));
 			if (stray.length > 0) violations.push({
@@ -1221,6 +1407,13 @@ const collectTokens$1 = (node, tier, path, out, violations) => {
 };
 const collectAliasViolations = (tokens) => {
 	const violations = [];
+	for (const [path, token] of tokens) for (const [mode, value] of Object.entries(token.modes)) {
+		const alias = aliasTarget(value);
+		if (alias !== void 0 && !tokens.has(alias)) violations.push({
+			kind: "unresolved-alias",
+			message: `token "${path}" references "{${alias}}" in mode "${mode}", which does not exist.`
+		});
+	}
 	for (const [path, token] of tokens) {
 		const alias = aliasTarget(token.value);
 		if (alias === void 0) continue;
@@ -1243,9 +1436,16 @@ const collectAliasViolations = (tokens) => {
 			message: `token "${path}" has an alias chain that never resolves to a literal value (alias cycle).`
 		});
 	}
+	for (const [path, token] of tokens) for (const [mode, value] of Object.entries(token.modes)) {
+		if (aliasTarget(value) === void 0) continue;
+		if (aliasChainCycles(path, tokens, mode)) violations.push({
+			kind: "cyclic-alias",
+			message: `token "${path}" has an alias chain in mode "${mode}" that never resolves to a literal value (alias cycle).`
+		});
+	}
 	return violations;
 };
-const aliasChainCycles = (start, tokens) => {
+const aliasChainCycles = (start, tokens, mode) => {
 	const seen = /* @__PURE__ */ new Set();
 	let current = start;
 	while (current !== void 0) {
@@ -1253,7 +1453,7 @@ const aliasChainCycles = (start, tokens) => {
 		seen.add(current);
 		const token = tokens.get(current);
 		if (token === void 0) return false;
-		current = aliasTarget(token.value);
+		current = aliasTarget(mode !== void 0 && Object.hasOwn(token.modes, mode) ? token.modes[mode] : token.value);
 	}
 	return false;
 };
@@ -1266,16 +1466,38 @@ const mergeExtensions = (extra) => {
 	}
 	return set;
 };
+const codeOf = (error) => error.code ?? String(error);
+const describeUnreadableDir = async (dir) => {
+	try {
+		await readdir(dir);
+	} catch (error) {
+		const code = codeOf(error);
+		if (code === "ENOENT") return "does not exist";
+		if (code === "ENOTDIR") return "is not a directory";
+		return `cannot be listed (${code})`;
+	}
+	try {
+		await access(dir, constants.R_OK | constants.X_OK);
+		return;
+	} catch (error) {
+		return `can be listed but not searched (${codeOf(error)})`;
+	}
+};
 const scanSource = async (repoRoot, scanRoot, extensions) => {
 	if (!await pathExists(scanRoot)) return {
 		filesScanned: 0,
 		violations: []
 	};
-	const files = (await collectSourceFiles(scanRoot, extensions)).toSorted();
-	const violations = [];
+	const unlistable = [];
+	const files = (await collectSourceFiles(scanRoot, extensions, unlistable)).toSorted();
+	const violations = unlistable.map(({ dir, code }) => ({
+		kind: "unreadable-source-dir",
+		message: `directory cannot be listed (${code}) — nothing under it was scanned.`,
+		file: relative(repoRoot, dir).split(sep).join("/") || "."
+	})).toSorted((a, b) => a.file.localeCompare(b.file));
 	let filesScanned = 0;
 	for (const file of files) {
-		const content = await readFile(file, "utf8").catch(() => void 0);
+		const content = await readRegularFile(file).catch(() => void 0);
 		if (content === void 0) continue;
 		filesScanned += 1;
 		const relPath = relative(repoRoot, file).split(sep).join("/");
@@ -1286,13 +1508,22 @@ const scanSource = async (repoRoot, scanRoot, extensions) => {
 		violations
 	};
 };
-const collectSourceFiles = async (dir, extensions) => {
-	const entries = await readdir(dir, { withFileTypes: true });
+const collectSourceFiles = async (dir, extensions, unlistable) => {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch (error) {
+		unlistable.push({
+			dir,
+			code: codeOf(error)
+		});
+		return [];
+	}
 	return (await Promise.all(entries.map(async (entry) => {
 		const full = join(dir, entry.name);
 		if (entry.isDirectory()) {
 			if (IGNORED_DIRS.has(entry.name)) return [];
-			return collectSourceFiles(full, extensions);
+			return collectSourceFiles(full, extensions, unlistable);
 		}
 		return extensions.has(extname(entry.name).toLowerCase()) ? [full] : [];
 	}))).flat();
@@ -1450,6 +1681,7 @@ const flatten = (color, backdrop) => ({
 	b: color.b * color.a + backdrop.b * (1 - color.a),
 	a: 1
 });
+const compositeOver = (color, ground) => flatten(color, ground.a < 1 ? flatten(ground, WHITE) : ground);
 const linearizeChannel = (channel) => {
 	const s = channel / 255;
 	return s <= .03928 ? s / 12.92 : ((s + .055) / 1.055) ** 2.4;
@@ -1465,17 +1697,6 @@ const contrastRatio = (foreground, background) => {
 	return Math.round((light + .05) / (dark + .05) * 100) / 100;
 };
 //#endregion
-//#region src/design-tokens/contrast.constant.ts
-const CONTRAST_EXTENSION = "com.lemony.contrast";
-const MODES_EXTENSION = "com.lemony.modes";
-const BASE_MODE = "base";
-const DEFAULT_LEVEL = "text";
-const WCAG_FLOORS = {
-	text: 4.5,
-	large: 3,
-	"non-text": 3
-};
-//#endregion
 //#region src/design-tokens/contrast.model.ts
 const CONTRAST_LEVELS = [
 	"text",
@@ -1485,36 +1706,57 @@ const CONTRAST_LEVELS = [
 //#endregion
 //#region src/design-tokens/contrast.ts
 const runContrast = async (inputs) => {
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return emptyResult$1(false);
-	const raw = await readFile(tokenPath, "utf8");
+	let raw;
+	let unreadable;
+	try {
+		raw = await readOptionalTokenFile(inputs.repoRoot);
+	} catch (error) {
+		unreadable = error instanceof Error ? error.message : String(error);
+	}
+	const verify = inputs.verify ? await runVerifier(inputs.verify) : void 0;
+	const withVerify = (result) => ({
+		...result,
+		ok: result.ok && (verify === void 0 || verify.code === 0),
+		...verify === void 0 ? {} : { verify }
+	});
+	if (unreadable !== void 0) return withVerify({
+		...emptyResult$1(true),
+		ok: false,
+		problems: [unreadable]
+	});
+	if (raw === void 0) return withVerify(emptyResult$1(false));
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch (error) {
-		return {
+		return withVerify({
 			...emptyResult$1(true),
 			ok: false,
 			problems: [`${DESIGN_TOKENS_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)}) — run \`design-tokens validate\` first.`]
-		};
+		});
 	}
-	if (!isRecord(parsed)) return {
+	if (!isRecord(parsed)) return withVerify({
 		...emptyResult$1(true),
 		ok: false,
 		problems: [`${DESIGN_TOKENS_FILE} must be a JSON object — run \`design-tokens validate\` first.`]
-	};
+	});
+	if (exceedsNestingLimit(parsed)) return withVerify({
+		...emptyResult$1(true),
+		ok: false,
+		problems: [`${NESTED_TOO_DEEPLY} Run \`design-tokens validate\` first.`]
+	});
 	const tokens = collectTokens(parsed);
 	const problems = [];
-	const specs = discoverPairs(tokens, problems);
 	const modes = declaredModes(tokens);
+	const specs = discoverPairs(tokens, modes, problems);
 	const pairs = measurePairs(specs, modes, tokens);
-	return {
+	return withVerify({
 		ok: problems.length === 0 && pairs.every((pair) => pair.passes),
 		tokensFound: true,
 		pairsChecked: pairs.length,
 		pairs,
 		problems
-	};
+	});
 };
 const emptyResult$1 = (tokensFound) => ({
 	ok: true,
@@ -1552,21 +1794,19 @@ const declaredModes = (tokens) => {
 	for (const token of tokens.values()) {
 		const modes = readExtension(token.node, MODES_EXTENSION);
 		if (isRecord(modes)) {
-			for (const name of Object.keys(modes)) if (name.trim().length > 0) names.add(name);
+			for (const name of Object.keys(modes)) if (name.trim().length > 0 && name !== "base") names.add(name);
 		}
 	}
 	return [...names].toSorted();
 };
-const discoverPairs = (tokens, problems) => {
-	const merged = /* @__PURE__ */ new Map();
-	const add = (spec) => {
-		merged.set(`${spec.foreground}|${spec.background}`, spec);
-	};
-	for (const spec of conventionPairs(tokens)) add(spec);
-	for (const spec of extensionPairs(tokens, problems)) add(spec);
-	return [...merged.values()];
+const pairKey = (spec) => `${spec.foreground}|${spec.background}`;
+const discoverPairs = (tokens, modes, problems) => {
+	const convention = new Map(conventionPairs(tokens, modes, problems).map((spec) => [pairKey(spec), spec]));
+	const explicit = extensionPairs(tokens, modes, problems);
+	for (const spec of explicit) convention.delete(pairKey(spec));
+	return [...convention.values(), ...explicit];
 };
-const conventionPairs = (tokens) => {
+const conventionPairs = (tokens, modes, problems) => {
 	const pairs = [];
 	for (const [path, token] of tokens) {
 		if (token.tier !== "semantic") continue;
@@ -1577,81 +1817,212 @@ const conventionPairs = (tokens) => {
 		if (!tokens.has(basePath)) continue;
 		if (!resolveColor(path, "base", tokens)) continue;
 		if (!resolveColor(basePath, "base", tokens)) continue;
+		const broken = [{
+			end: path,
+			other: basePath
+		}, {
+			end: basePath,
+			other: path
+		}].flatMap(({ end, other }) => modes.flatMap((mode) => {
+			const fault = modeAliasBreak(end, mode, tokens);
+			if (fault === void 0) return [];
+			return fault === "too-deep" ? [`token "${end}" has a "${mode}" mode alias chain of 64 hops or more, which contrast does not follow, so its convention pair with "${other}" is not measured — shorten the chain.`] : [`token "${end}" has a "${mode}" mode alias that does not resolve (a missing token or an alias cycle), so its convention pair with "${other}" is not measured — run \`design-tokens validate\`.`];
+		}));
+		if (broken.length > 0) {
+			problems.push(...broken);
+			continue;
+		}
 		pairs.push({
 			foreground: path,
 			background: basePath,
 			level: DEFAULT_LEVEL,
+			floors: {},
 			source: "convention"
 		});
 	}
 	return pairs;
 };
-const extensionPairs = (tokens, problems) => {
+const DECLARATION_SHAPE = "{ against: \"{token.path}\" | [\"{token.path}\", …], level?, floors?, modes?, over? }";
+const DECLARATION_KEYS = /* @__PURE__ */ new Set([
+	"against",
+	"level",
+	"floors",
+	"modes",
+	"over"
+]);
+const extensionPairs = (tokens, modes, problems) => {
 	const pairs = [];
 	for (const [path, token] of tokens) {
 		const declaration = readExtension(token.node, CONTRAST_EXTENSION);
 		if (declaration === void 0) continue;
 		const entries = Array.isArray(declaration) ? declaration : [declaration];
+		const declared = /* @__PURE__ */ new Set();
 		for (const entry of entries) {
-			if (!isRecord(entry) || typeof entry["against"] !== "string") {
-				problems.push(`token "${path}" has a malformed ${CONTRAST_EXTENSION} declaration — expected { against: "{token.path}", level? }.`);
-				continue;
-			}
-			const against = aliasTarget(entry["against"]) ?? entry["against"];
-			if (against === path) {
-				problems.push(`token "${path}" declares contrast against itself — a pair needs two different tokens.`);
+			if (!isRecord(entry)) {
+				problems.push(`token "${path}" has a malformed ${CONTRAST_EXTENSION} declaration — expected ${DECLARATION_SHAPE}.`);
 				continue;
 			}
-			if (!tokens.has(against)) {
-				problems.push(`token "${path}" contrast-against "${entry["against"]}" does not resolve to a known token.`);
-				continue;
-			}
-			if (!resolveColor(against, "base", tokens)) {
-				problems.push(`token "${path}" contrast-against "${entry["against"]}" is not a colour token.`);
+			const unknownKeys = Object.keys(entry).filter((key) => !DECLARATION_KEYS.has(key));
+			if (unknownKeys.length > 0) {
+				problems.push(`token "${path}" has unknown ${CONTRAST_EXTENSION} key(s) ${unknownKeys.map((key) => `"${key}"`).join(", ")} — expected ${DECLARATION_SHAPE}.`);
 				continue;
 			}
+			const before = problems.length;
+			const backgrounds = tokenPathList(entry["against"], path, "against", problems);
+			if (backgrounds.length === 0) continue;
 			if (!resolveColor(path, "base", tokens)) {
 				problems.push(`token "${path}" declares a contrast pair but is not itself a colour token.`);
 				continue;
 			}
-			pairs.push({
-				foreground: path,
-				background: against,
-				level: normalizeLevel(entry["level"], path, problems),
-				source: "extension"
-			});
+			const level = normalizeLevel(entry["level"], path, problems);
+			const floors = normalizeFloors(entry["floors"], path, modes, problems);
+			const ruleModes = normalizeModes(entry["modes"], path, modes, problems);
+			const measuredModes = (ruleModes ?? modes).filter((mode) => mode !== BASE_MODE);
+			const ownDefects = unresolvedModes(path, measuredModes, tokens);
+			for (const mode of ownDefects) {
+				const problem = `token "${path}" declares a contrast pair but its "${mode}" mode override does not resolve to a colour.`;
+				if (!problems.includes(problem)) problems.push(problem);
+			}
+			if (ruleModes !== void 0) {
+				for (const mode of Object.keys(floors)) if (mode !== "base" && !ruleModes.includes(mode)) problems.push(`token "${path}" sets a contrast floor for mode "${mode}" but restricts the rule to ${ruleModes.map((name) => `"${name}"`).join("/")} — the floor would never apply.`);
+			}
+			const grounds = entry["over"] === void 0 ? [] : tokenPathList(entry["over"], path, "over", problems);
+			const colourGrounds = [];
+			for (const ground of grounds) if (ground === path || backgrounds.includes(ground)) problems.push(`token "${path}" composites over "${ground}", which is an end of the pair itself — \`over\` names the opaque ground beneath the background.`);
+			else if (isColourTarget(ground, path, "over", measuredModes, tokens, problems)) colourGrounds.push(ground);
+			const colourBackgrounds = [];
+			for (const against of backgrounds) if (against === path) problems.push(`token "${path}" declares contrast against itself — a pair needs two different tokens.`);
+			else if (isColourTarget(against, path, "against", measuredModes, tokens, problems)) colourBackgrounds.push(against);
+			if (ownDefects.length > 0 || problems.length > before) continue;
+			for (const background of colourBackgrounds) for (const over of colourGrounds.length === 0 ? [void 0] : colourGrounds) {
+				const key = `${background}|${over ?? ""}`;
+				if (declared.has(key)) problems.push(`token "${path}" declares contrast against "${background}"${over === void 0 ? "" : ` over "${over}"`} more than once — one declaration per pair.`);
+				declared.add(key);
+			}
+			if (ownDefects.length > 0 || problems.length > before) continue;
+			for (const background of colourBackgrounds) {
+				const base = {
+					foreground: path,
+					background,
+					level,
+					floors,
+					source: "extension"
+				};
+				const withModes = ruleModes === void 0 ? base : {
+					...base,
+					modes: ruleModes
+				};
+				if (colourGrounds.length === 0) pairs.push(withModes);
+				else for (const over of colourGrounds) pairs.push({
+					...withModes,
+					over
+				});
+			}
 		}
 	}
 	return pairs;
 };
+const tokenPathList = (raw, path, field, problems) => {
+	const list = Array.isArray(raw) ? raw : [raw];
+	if (list.length === 0 || !list.every((item) => typeof item === "string")) {
+		problems.push(`token "${path}" has a malformed ${CONTRAST_EXTENSION} declaration — \`${field}\` must be a token path or a non-empty array of them (expected ${DECLARATION_SHAPE}).`);
+		return [];
+	}
+	return list.map((item) => aliasTarget(item) ?? item);
+};
+const isColourTarget = (target, path, field, modes, tokens, problems) => {
+	if (!tokens.has(target)) {
+		problems.push(`token "${path}" contrast-${field} "${target}" does not resolve to a known token.`);
+		return false;
+	}
+	if (!resolveColor(target, "base", tokens)) {
+		problems.push(`token "${path}" contrast-${field} "${target}" is not a colour token.`);
+		return false;
+	}
+	const unresolved = unresolvedModes(target, modes, tokens);
+	for (const mode of unresolved) problems.push(`token "${path}" contrast-${field} "${target}" has a "${mode}" mode override that does not resolve to a colour.`);
+	return unresolved.length === 0;
+};
+const unresolvedModes = (target, modes, tokens) => modes.filter((mode) => resolveColor(target, mode, tokens) === void 0);
 const normalizeLevel = (raw, path, problems) => {
 	if (raw === void 0) return DEFAULT_LEVEL;
 	if (typeof raw === "string" && CONTRAST_LEVELS.includes(raw)) return raw;
 	problems.push(`token "${path}" has an unknown contrast level "${String(raw)}" — use ${CONTRAST_LEVELS.join("/")}.`);
 	return DEFAULT_LEVEL;
 };
+const normalizeFloors = (raw, path, modes, problems) => {
+	if (raw === void 0) return {};
+	if (!isRecord(raw)) {
+		problems.push(`token "${path}" has malformed contrast floors — expected { base?: number, <mode>?: number }.`);
+		return {};
+	}
+	const floors = Object.create(null);
+	for (const [mode, value] of Object.entries(raw)) {
+		if (mode !== "base" && !modes.includes(mode)) {
+			problems.push(`token "${path}" sets a contrast floor for mode "${mode}", which no ${MODES_EXTENSION} block declares — use ${[BASE_MODE, ...modes].join("/")}.`);
+			continue;
+		}
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 1 || value > 21) {
+			problems.push(`token "${path}" has an invalid contrast floor for mode "${mode}" (${String(value)}) — a WCAG ratio is a number between 1 and 21.`);
+			continue;
+		}
+		floors[mode] = value;
+	}
+	return floors;
+};
+const normalizeModes = (raw, path, modes, problems) => {
+	if (raw === void 0) return void 0;
+	if (!Array.isArray(raw) || raw.length === 0 || !raw.every((item) => typeof item === "string")) {
+		problems.push(`token "${path}" has malformed contrast modes — expected a non-empty array of mode names.`);
+		return;
+	}
+	const unknown = raw.filter((mode) => mode !== "base" && !modes.includes(mode));
+	if (unknown.length > 0) {
+		problems.push(`token "${path}" restricts contrast to mode(s) ${unknown.map((mode) => `"${mode}"`).join(", ")}, which no ${MODES_EXTENSION} block declares — use ${[BASE_MODE, ...modes].join("/")}.`);
+		return;
+	}
+	return [...new Set(raw)];
+};
+const floorFor = (spec, mode) => ownFloor(spec.floors, mode) ?? ownFloor(spec.floors, "base") ?? WCAG_FLOORS[spec.level];
+const ownFloor = (floors, mode) => Object.hasOwn(floors, mode) ? floors[mode] : void 0;
 const measurePairs = (specs, modes, tokens) => {
 	const rows = [];
 	for (const spec of specs) {
-		const baseFg = resolveColor(spec.foreground, BASE_MODE, tokens);
-		const baseBg = resolveColor(spec.background, BASE_MODE, tokens);
-		if (!baseFg || !baseBg) continue;
-		rows.push(makeRow(spec, BASE_MODE, baseFg, baseBg));
-		for (const mode of modes) {
-			const fg = resolveColor(spec.foreground, mode, tokens) ?? baseFg;
-			const bg = resolveColor(spec.background, mode, tokens) ?? baseBg;
-			if (sameColor(fg, baseFg) && sameColor(bg, baseBg)) continue;
-			rows.push(makeRow(spec, mode, fg, bg));
+		const base = resolvePair(spec, BASE_MODE, tokens);
+		if (!base) continue;
+		const explicit = spec.modes !== void 0;
+		const rowModes = spec.modes ?? ["base", ...modes];
+		for (const mode of rowModes) {
+			const colours = mode === "base" ? base : resolvePair(spec, mode, tokens) ?? base;
+			if (!explicit && mode !== "base" && sameColor(colours.fg, base.fg) && sameColor(colours.bg, base.bg) && floorFor(spec, mode) === floorFor(spec, "base")) continue;
+			rows.push(makeRow(spec, mode, colours.fg, colours.bg));
 		}
 	}
 	return rows;
 };
+const resolvePair = (spec, mode, tokens) => {
+	const resolveEnd = (path) => resolveColor(path, mode, tokens) ?? (mode === "base" ? void 0 : resolveColor(path, "base", tokens));
+	const fg = resolveEnd(spec.foreground);
+	const against = resolveEnd(spec.background);
+	if (!fg || !against) return void 0;
+	if (spec.over === void 0) return {
+		fg,
+		bg: against
+	};
+	const ground = resolveEnd(spec.over);
+	if (!ground) return void 0;
+	return {
+		fg,
+		bg: compositeOver(against, ground)
+	};
+};
 const makeRow = (spec, mode, foreground, background) => {
 	const ratio = contrastRatio(foreground, background);
-	const floor = WCAG_FLOORS[spec.level];
+	const floor = floorFor(spec, mode);
 	return {
 		foreground: spec.foreground,
 		background: spec.background,
+		...spec.over === void 0 ? {} : { over: spec.over },
 		mode,
 		level: spec.level,
 		ratio,
@@ -1675,35 +2046,129 @@ const resolveColor = (path, mode, tokens, seen = /* @__PURE__ */ new Set()) => {
 	if (alias !== void 0) return resolveColor(alias, mode, tokens, seen);
 	return typeof value === "string" ? parseColor(value) : void 0;
 };
+const modeAliasBreak = (path, mode, tokens) => {
+	const seen = /* @__PURE__ */ new Set();
+	let current = path;
+	while (current !== void 0) {
+		if (seen.has(current)) return "unresolved";
+		seen.add(current);
+		const token = tokens.get(current);
+		if (!token) return "unresolved";
+		const modes = readExtension(token.node, MODES_EXTENSION);
+		const value = isRecord(modes) && Object.hasOwn(modes, mode) ? modes[mode] : token.value;
+		current = aliasTarget(value);
+	}
+	return seen.size > 64 ? "too-deep" : void 0;
+};
+const runVerifier = async (hook) => {
+	const result = await hook.run("sh", ["-c", hook.command]);
+	return {
+		command: hook.command,
+		...result
+	};
+};
 //#endregion
 //#region src/design-tokens/design-sync.constant.ts
 const DESIGN_TOOL_EXTENSION = "com.lemony.design-tool";
+const NEUTRAL_STRING_VALUES = "The neutral format carries every value as a string (e.g. \"1024\", \"#3b82f6\") — fix the adapter that wrote the file.";
+const NEUTRAL_MODES_OBJECT = "It maps each mode name to that mode's value (e.g. {\"dark\": \"#000000\"}) — fix the adapter that wrote the file.";
+const NEUTRAL_VALUE_OR_REF = "Each variable carries a string \"value\" (a literal) or a non-empty string \"ref\" (the name of the variable it aliases) — fix the adapter that wrote the file.";
+const NEUTRAL_NAME_SHAPE = "A name is dot-separated segments, like \"primitive.color.brand\" — fix the adapter that wrote the file.";
+const VALIDATE_HINT = "Run `lemony design-tokens validate` for the full list.";
+const IMPORT_INVALID_HINT = "Change the `--only` slice (add what it references), or fix the file first; nothing was written.";
+const IMPORT_NOT_CARRIED_HINT = "add the token in the design tool (or in docs/design-tokens.json) first, or leave out what references it; nothing was written.";
+const IMPORT_PREVIEW_INVALID_HINT = "`--apply` refuses any slice that leaves it failing: include what repairs it, or fix the file first.";
+const IMPORT_TOO_DEEP_HINT = "Shorten the dotted names of the variables that land that deep, or leave them out with `--only`; nothing was written.";
+//#endregion
+//#region src/design-tokens/read-required-file.ts
+const readRequiredFile = async (path, label) => {
+	try {
+		return await readRegularFile(path);
+	} catch (error) {
+		if (error.code === "ENOENT") {
+			if (!await entryExists(path)) throw new Error(`${label} file not found: ${path}`, { cause: error });
+			throw new Error(`Cannot read ${label} file at ${path}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
+		}
+		throw new Error(`Cannot read ${label} file at ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+};
 //#endregion
 //#region src/design-tokens/neutral-mapping.ts
 const KNOWN_TIERS = new Set(TOKEN_TIERS);
 const dtcgToNeutral = (parsed) => {
+	const nodes = tokenNodes(parsed);
+	const unsynced = unsyncedReasons(nodes);
 	const variables = [];
-	for (const tier of TOKEN_TIERS) {
-		const group = parsed[tier];
-		if (isRecord(group)) walk(group, tier, variables);
-	}
+	for (const [path, node] of nodes) if (!unsynced.has(path)) variables.push(toVariable$1(path, node));
 	return {
 		schemaVersion: 1,
 		variables: variables.toSorted(byName)
 	};
 };
-const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+const unsyncedTokens = (parsed) => [...unsyncedReasons(tokenNodes(parsed))].map(([path, reason]) => ({
+	path,
+	reason
+})).toSorted((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+const tokenNodes = (parsed) => {
+	const nodes = /* @__PURE__ */ new Map();
+	for (const tier of TOKEN_TIERS) {
+		const group = parsed[tier];
+		if (isRecord(group)) walk(group, tier, nodes);
+	}
+	return nodes;
+};
 const walk = (node, path, out) => {
 	for (const [key, child] of Object.entries(node)) {
 		if (key.startsWith("$") || !isRecord(child)) continue;
 		const childPath = `${path}.${key}`;
-		if ("$value" in child) out.push(toVariable$1(childPath, child));
+		if ("$value" in child) out.set(childPath, child);
 		else walk(child, childPath, out);
 	}
 };
+const unsyncedReasons = (nodes) => {
+	const reasons = /* @__PURE__ */ new Map();
+	for (const [path, node] of nodes) {
+		const reason = ownUnsyncedReason(node);
+		if (reason !== void 0) reasons.set(path, reason);
+	}
+	let grew = true;
+	while (grew) {
+		grew = false;
+		for (const [path, node] of nodes) {
+			if (reasons.has(path)) continue;
+			const target = aliasTargetsOf(node).find((name) => reasons.has(name));
+			if (target === void 0) continue;
+			reasons.set(path, `an alias to ${target}`);
+			grew = true;
+		}
+	}
+	return reasons;
+};
+const ownUnsyncedReason = (node) => {
+	if (isCompositeValue(node["$value"])) return "a composite value";
+	const modes = modesExtension(node);
+	if (modes === void 0) return void 0;
+	if (!isRecord(modes)) return "a modes extension that is not an object";
+	for (const [name, value] of Object.entries(modes)) {
+		if (name.trim().length === 0) return "a mode with a blank name";
+		if (name === "__proto__") return "a mode named \"__proto__\"";
+		if (!isScalar(value)) return `mode "${name}" holding neither text, a number nor a boolean`;
+	}
+};
+const aliasTargetsOf = (node) => {
+	const modes = modesExtension(node);
+	return [node["$value"], ...isRecord(modes) ? Object.values(modes) : []].map(aliasTarget).filter((target) => target !== void 0);
+};
+const modesExtension = (node) => {
+	const extensions = node["$extensions"];
+	return isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
+};
+const isCompositeValue = (value) => typeof value === "object" && value !== null;
+const isScalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 const toVariable$1 = (name, node) => {
 	const type = typeof node["$type"] === "string" ? node["$type"] : "";
-	const modes = readModes(node);
+	const modes = readModes$1(node);
 	const alias = aliasTarget(node["$value"]);
 	const base = {
 		name,
@@ -1720,37 +2185,64 @@ const toVariable$1 = (name, node) => {
 	};
 };
 const stringifyValue = (value) => value === void 0 || value === null ? "" : String(value);
-const readModes = (node) => {
-	const extensions = node["$extensions"];
-	const modes = isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
+const readModes$1 = (node) => {
+	const modes = modesExtension(node);
 	if (!isRecord(modes)) return void 0;
 	const out = {};
-	for (const [name, value] of Object.entries(modes)) if (name.trim().length > 0 && typeof value === "string") out[name] = value;
+	for (const [name, value] of Object.entries(modes)) if (isScalar(value)) out[name] = String(value);
 	return Object.keys(out).length > 0 ? out : void 0;
 };
-const toIncoming = (variable) => {
-	const isAlias = variable.ref !== void 0;
-	const value = isAlias ? `{${variable.ref}}` : variable.value ?? "";
-	const type = variable.type;
+const landingPath = (variable, known) => {
 	const first = variable.name.split(".")[0] ?? "";
-	if (KNOWN_TIERS.has(first)) return withModes({
-		path: variable.name,
-		tier: first,
-		type,
-		value
-	}, variable);
-	const tier = isAlias ? "semantic" : "primitive";
-	return withModes({
-		path: `${tier}.${variable.name}`,
-		tier,
-		type,
+	if (KNOWN_TIERS.has(first)) return variable.name;
+	const existing = existingTierPath(variable.name, known);
+	if (existing !== void 0) return existing;
+	return `${variable.ref === void 0 ? "primitive" : "semantic"}.${variable.name}`;
+};
+const existingTierPath = (bare, known) => {
+	const matches = TOKEN_TIERS.map((tier) => `${tier}.${bare}`).filter((path) => known.has(path));
+	return matches.length === 1 ? matches[0] : void 0;
+};
+const refResolver = (neutral, known) => {
+	const landings = /* @__PURE__ */ new Map();
+	for (const variable of neutral.variables) landings.set(variable.name, landingPath(variable, known));
+	return (ref) => {
+		const first = ref.split(".")[0] ?? "";
+		if (KNOWN_TIERS.has(first)) return ref;
+		return landings.get(ref) ?? existingTierPath(ref, known) ?? ref;
+	};
+};
+const toIncoming = (variable, resolveRef, known) => {
+	const value = variable.ref === void 0 ? variable.value ?? "" : `{${resolveRef(variable.ref)}}`;
+	const path = landingPath(variable, known);
+	const token = {
+		path,
+		tier: path.split(".")[0],
+		type: variable.type,
 		value
-	}, variable);
+	};
+	if (!variable.modes) return token;
+	const modes = {};
+	for (const [mode, modeValue] of Object.entries(variable.modes)) {
+		const alias = aliasTarget(modeValue);
+		modes[mode] = alias === void 0 ? modeValue : `{${resolveRef(alias)}}`;
+	}
+	return {
+		...token,
+		modes
+	};
+};
+const incomingByPath = (neutral, known) => {
+	const resolveRef = refResolver(neutral, known);
+	const tokens = neutral.variables.map((variable) => ({
+		exact: KNOWN_TIERS.has(variable.name.split(".")[0] ?? ""),
+		token: toIncoming(variable, resolveRef, known)
+	}));
+	const byPath = /* @__PURE__ */ new Map();
+	for (const { exact, token } of tokens) if (exact) byPath.set(token.path, token);
+	for (const { exact, token } of tokens) if (!exact && !byPath.has(token.path)) byPath.set(token.path, token);
+	return byPath;
 };
-const withModes = (token, variable) => variable.modes ? {
-	...token,
-	modes: variable.modes
-} : token;
 const comparisonKey = (type, value, modes) => JSON.stringify({
 	type,
 	value,
@@ -1765,41 +2257,78 @@ const sortedModes = (modes) => {
 const diffNeutralAgainstJson = (neutral, parsed) => {
 	const current = /* @__PURE__ */ new Map();
 	for (const variable of dtcgToNeutral(parsed).variables) current.set(variable.name, variable);
+	const unsynced = new Map(unsyncedTokens(parsed).map(({ path, reason }) => [path, reason]));
 	const changes = [];
-	for (const variable of neutral.variables) {
-		const incoming = toIncoming(variable);
+	for (const incoming of incomingByPath(neutral, /* @__PURE__ */ new Set([...current.keys(), ...unsynced.keys()])).values()) {
+		const reason = unsynced.get(incoming.path);
+		if (reason !== void 0) {
+			changes.push({
+				path: incoming.path,
+				tier: incoming.tier,
+				kind: "changed",
+				before: `(outside the sync: ${reason})`,
+				after: incoming.value
+			});
+			continue;
+		}
 		const existing = current.get(incoming.path);
 		const after = incoming.value;
 		const before = existing ? neutralValue(existing) : void 0;
+		const kind = classifyImport(existing, incoming);
 		changes.push({
 			path: incoming.path,
 			tier: incoming.tier,
-			kind: classifyImport(existing, incoming, variable),
+			kind,
 			...before !== void 0 ? { before } : {},
-			after
+			after,
+			...existing && kind === "changed" ? changeDetail(existing, incoming) : {}
 		});
 	}
 	return changes.toSorted((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
 };
+const changeDetail = (existing, incoming) => {
+	const detail = {};
+	if (existing.type !== incoming.type) detail.typeChange = {
+		before: existing.type,
+		after: incoming.type
+	};
+	const before = existing.modes ?? {};
+	const after = incoming.modes ?? {};
+	const modeChanges = [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].toSorted().filter((mode) => before[mode] !== after[mode]).map((mode) => ({
+		mode,
+		...before[mode] !== void 0 ? { before: before[mode] } : {},
+		...after[mode] !== void 0 ? { after: after[mode] } : {}
+	}));
+	if (modeChanges.length > 0) detail.modeChanges = modeChanges;
+	return detail;
+};
 const neutralValue = (variable) => variable.ref !== void 0 ? `{${variable.ref}}` : variable.value ?? "";
-const classifyImport = (existing, incoming, variable) => {
+const classifyImport = (existing, incoming) => {
 	if (!existing) return "new";
-	return comparisonKey(existing.type, neutralValue(existing), existing.modes) === comparisonKey(incoming.type, incoming.value, variable.modes) ? "unchanged" : "changed";
+	return comparisonKey(existing.type, neutralValue(existing), existing.modes) === comparisonKey(incoming.type, incoming.value, incoming.modes) ? "unchanged" : "changed";
 };
 const mergeNeutralIntoJson = (neutral, parsed, only) => {
 	const merged = structuredClone(parsed);
 	const onlySet = only ? new Set(only) : void 0;
 	const written = [];
 	const skipped = [];
-	for (const variable of neutral.variables) {
-		const incoming = toIncoming(variable);
+	const unsyncedLanded = [];
+	const current = new Map(dtcgToNeutral(parsed).variables.map((variable) => [variable.name, variable]));
+	const unsynced = new Set(unsyncedTokens(parsed).map(({ path }) => path));
+	for (const incoming of incomingByPath(neutral, /* @__PURE__ */ new Set([...current.keys(), ...unsynced])).values()) {
 		if (onlySet && !onlySet.has(incoming.path)) continue;
+		if (unsynced.has(incoming.path)) {
+			unsyncedLanded.push(incoming.path);
+			continue;
+		}
+		if (classifyImport(current.get(incoming.path), incoming) === "unchanged") continue;
 		(setToken(merged, incoming) ? written : skipped).push(incoming.path);
 	}
 	return {
 		merged,
 		written: written.toSorted(),
-		skipped: skipped.toSorted()
+		skipped: skipped.toSorted(),
+		unsynced: unsyncedLanded.toSorted()
 	};
 };
 const isTokenNode = (value) => isRecord(value) && "$value" in value;
@@ -1822,17 +2351,44 @@ const setToken = (root, incoming) => {
 		if (!isRecord(next)) node[segment] = {};
 		node = node[segment];
 	}
-	const leaf = { $value: incoming.value };
+	const existing = node[leafKey];
+	const leaf = isRecord(existing) ? { ...existing } : {};
+	const typeBefore = typeof leaf["$type"] === "string" ? leaf["$type"] : "";
+	const sameType = incoming.type === typeBefore;
+	const keep = (before, text) => sameType ? keptScalar(before, text) : text;
+	leaf["$value"] = keep(leaf["$value"], incoming.value);
 	if (incoming.type.length > 0) leaf["$type"] = incoming.type;
-	if (incoming.modes) leaf["$extensions"] = { [MODES_EXTENSION]: incoming.modes };
+	else delete leaf["$type"];
+	const extensions = isRecord(leaf["$extensions"]) ? { ...leaf["$extensions"] } : {};
+	if (incoming.modes) {
+		const before = extensions[MODES_EXTENSION];
+		const modes = {};
+		for (const [mode, value] of Object.entries(incoming.modes)) modes[mode] = keep(isRecord(before) && Object.hasOwn(before, mode) ? before[mode] : void 0, value);
+		extensions[MODES_EXTENSION] = modes;
+	} else delete extensions[MODES_EXTENSION];
+	if (Object.keys(extensions).length > 0) leaf["$extensions"] = extensions;
+	else delete leaf["$extensions"];
 	node[leafKey] = leaf;
 	return true;
 };
+const keptScalar = (before, incoming) => (typeof before === "number" || typeof before === "boolean") && String(before) === incoming ? before : incoming;
+const danglingAliasTargets = (parsed, paths) => {
+	const { variables } = dtcgToNeutral(parsed);
+	const names = new Set(variables.map((variable) => variable.name));
+	const wanted = new Set(paths);
+	const dangling = /* @__PURE__ */ new Set();
+	for (const variable of variables) {
+		if (!wanted.has(variable.name)) continue;
+		const targets = [variable.ref, ...Object.values(variable.modes ?? {}).map(aliasTarget)];
+		for (const target of targets) if (target !== void 0 && !names.has(target)) dangling.add(target);
+	}
+	return [...dangling].toSorted();
+};
 const upsertPlan = (parsed, toolState) => {
-	const current = /* @__PURE__ */ new Map();
-	for (const variable of toolState?.variables ?? []) current.set(variable.name, variable);
+	const { variables } = dtcgToNeutral(parsed);
+	const current = toolState ? incomingByPath(toolState, /* @__PURE__ */ new Set([...variables.map((variable) => variable.name), ...unsyncedTokens(parsed).map(({ path }) => path)])) : /* @__PURE__ */ new Map();
 	const plan = [];
-	for (const variable of dtcgToNeutral(parsed).variables) plan.push({
+	for (const variable of variables) plan.push({
 		name: variable.name,
 		kind: classifyExport(variable, current)
 	});
@@ -1841,45 +2397,78 @@ const upsertPlan = (parsed, toolState) => {
 const classifyExport = (projected, current) => {
 	const existing = current.get(projected.name);
 	if (!existing) return "create";
-	return comparisonKey(projected.type, neutralValue(projected), projected.modes) === comparisonKey(existing.type, neutralValue(existing), existing.modes) ? "unchanged" : "update";
+	return comparisonKey(projected.type, neutralValue(projected), projected.modes) === comparisonKey(existing.type, existing.value, existing.modes) ? "unchanged" : "update";
 };
 //#endregion
 //#region src/design-tokens/sync-io.ts
-const parseNeutralFile = (raw) => {
+const parseNeutralFile = (raw, label) => {
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch (error) {
-		throw new Error(`neutral file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		throw new Error(`${label} file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
-	if (!isRecord(parsed) || !Array.isArray(parsed["variables"])) throw new Error("neutral file must be a JSON object with a \"variables\" array.");
+	if (!isRecord(parsed) || !Array.isArray(parsed["variables"])) throw new Error(`${label} file must be a JSON object with a "variables" array.`);
 	const schemaVersion = typeof parsed["schemaVersion"] === "number" ? parsed["schemaVersion"] : 0;
 	const provider = typeof parsed["provider"] === "string" ? parsed["provider"] : void 0;
+	const variables = parsed["variables"].flatMap((entry) => toVariable(entry, label));
+	const seen = /* @__PURE__ */ new Set();
+	for (const { name } of variables) {
+		if (seen.has(name)) throw new Error(`${label} file: variable "${name}" appears more than once — fix the adapter that wrote the file.`);
+		seen.add(name);
+	}
 	return {
 		schemaVersion,
 		...provider ? { provider } : {},
-		variables: parsed["variables"].flatMap(toVariable)
+		variables
 	};
 };
-const toVariable = (raw) => {
+const toVariable = (raw, label) => {
 	if (!isRecord(raw) || typeof raw["name"] !== "string" || raw["name"].trim().length === 0) return [];
-	const type = typeof raw["type"] === "string" ? raw["type"] : "";
+	const name = raw["name"];
 	const variable = {
-		name: raw["name"],
-		type
-	};
-	if (typeof raw["ref"] === "string") variable.ref = raw["ref"];
-	else if (typeof raw["value"] === "string") variable.value = raw["value"];
-	const modes = readStringMap(raw["modes"]);
+		name,
+		type: typeof raw["type"] === "string" ? raw["type"] : ""
+	};
+	const refuse = (fault, hint) => /* @__PURE__ */ new Error(`${label} file: variable "${name}" ${fault}. ${hint}`);
+	const nameFault = tokenNameFault(name);
+	if (nameFault !== void 0) throw refuse(nameFault, NEUTRAL_NAME_SHAPE);
+	if (raw["ref"] !== void 0) {
+		if (typeof raw["ref"] !== "string") throw refuse(`has ${jsonKind(raw["ref"])} ref`, NEUTRAL_VALUE_OR_REF);
+		if (raw["ref"].trim().length === 0) throw refuse("has an empty ref", NEUTRAL_VALUE_OR_REF);
+		variable.ref = raw["ref"];
+	} else if (typeof raw["value"] === "string") variable.value = raw["value"];
+	else if (raw["value"] !== void 0) throw refuse(`has ${jsonKind(raw["value"])} value`, NEUTRAL_STRING_VALUES);
+	else throw refuse("has neither a value nor a ref", NEUTRAL_VALUE_OR_REF);
+	const modes = readModes(raw["modes"], name, label);
 	if (modes) variable.modes = modes;
 	return [variable];
 };
-const readStringMap = (raw) => {
-	if (!isRecord(raw)) return void 0;
+const readModes = (raw, name, label) => {
+	if (raw === void 0) return void 0;
+	if (!isRecord(raw)) throw new Error(`${label} file: variable "${name}" has ${jsonKind(raw)} "modes". ${NEUTRAL_MODES_OBJECT}`);
 	const out = {};
-	for (const [key, value] of Object.entries(raw)) if (key.trim().length > 0 && typeof value === "string") out[key] = value;
+	for (const [mode, value] of Object.entries(raw)) {
+		if (mode.trim().length === 0 || mode === "__proto__") throw new Error(`${label} file: variable "${name}" has a mode named ${JSON.stringify(mode)}, which no mode can be named. ${NEUTRAL_MODES_OBJECT}`);
+		if (typeof value !== "string") throw new Error(`${label} file: variable "${name}" has ${jsonKind(value)} value in mode "${mode}". ${NEUTRAL_STRING_VALUES}`);
+		out[mode] = value;
+	}
 	return Object.keys(out).length > 0 ? out : void 0;
 };
+const tokenNameFault = (name) => {
+	const segments = name.split(".");
+	if (segments.some((segment) => segment.trim().length === 0)) return "has an empty segment in its name";
+	if (segments.some((segment) => segment.startsWith("$"))) return "has a segment starting with \"$\", which DTCG keeps for its own keys";
+	if (segments.includes("__proto__")) return "has a \"__proto__\" segment, which no token can be named";
+	if (segments.length === 1 && TIERS.has(name)) return `names only the tier "${name}", with no token under it`;
+};
+const TIERS = new Set(TOKEN_TIERS);
+const jsonKind = (value) => {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	const kind = typeof value;
+	return kind === "object" ? "an object" : `a ${kind}`;
+};
 const readJsonObject = (raw) => {
 	let parsed;
 	try {
@@ -1888,6 +2477,7 @@ const readJsonObject = (raw) => {
 		throw new Error(`${DESIGN_TOKENS_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)}) — run \`design-tokens validate\` first.`, { cause: error });
 	}
 	if (!isRecord(parsed)) throw new Error(`${DESIGN_TOKENS_FILE} must be a JSON object — run \`design-tokens validate\` first.`);
+	if (exceedsNestingLimit(parsed)) throw new Error(`${NESTED_TOO_DEEPLY} Run \`design-tokens validate\` first.`);
 	return parsed;
 };
 const writeJsonFile = (value) => `${JSON.stringify(value, null, 2)}\n`;
@@ -1899,17 +2489,16 @@ const runImport = async (inputs) => {
 		tokensFound: false,
 		changes: [],
 		applied: false,
+		refused: false,
 		written: [],
 		skipped: [],
-		problems: []
-	};
-	if (!await pathExists(inputs.neutralPath)) return {
-		...empty,
-		problems: [`neutral file not found: ${inputs.neutralPath}`]
+		unsynced: [],
+		problems: [],
+		warnings: []
 	};
 	let neutral;
 	try {
-		neutral = parseNeutralFile(await readFile(inputs.neutralPath, "utf8"));
+		neutral = parseNeutralFile(await readRequiredFile(inputs.neutralPath, "neutral"), "neutral");
 	} catch (error) {
 		return {
 			...empty,
@@ -1920,37 +2509,79 @@ const runImport = async (inputs) => {
 		...empty,
 		problems: [`neutral file schemaVersion ${neutral.schemaVersion} is not supported (expected 1).`]
 	};
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	const tokensFound = await pathExists(tokenPath);
+	let tokensFound = false;
+	let raw;
 	let parsed;
 	try {
-		parsed = tokensFound ? readJsonObject(await readFile(tokenPath, "utf8")) : {};
+		raw = await readOptionalTokenFile(inputs.repoRoot);
+		tokensFound = raw !== void 0;
+		parsed = raw === void 0 ? {} : readJsonObject(raw);
 	} catch (error) {
 		return {
 			...empty,
-			tokensFound,
+			tokensFound: true,
 			problems: [asMessage$1(error)]
 		};
 	}
 	const changes = diffNeutralAgainstJson(neutral, parsed);
-	if (!inputs.apply) return {
+	if (!inputs.apply) {
+		const faults = summarizeMessages(raw === void 0 ? [] : tokenFileViolationMessages(raw));
+		return {
+			...empty,
+			tokensFound,
+			changes,
+			warnings: faults === void 0 ? [] : [`${DESIGN_TOKENS_FILE} already fails validation: ${faults} ${IMPORT_PREVIEW_INVALID_HINT} ${VALIDATE_HINT}`]
+		};
+	}
+	const unmatched = (inputs.only ?? []).filter((path) => !changes.some((change) => change.path === path));
+	if (unmatched.length > 0) return {
+		...empty,
 		tokensFound,
 		changes,
-		applied: false,
-		written: [],
-		skipped: [],
-		problems: []
+		refused: true,
+		problems: [`--only names ${unmatched.length === 1 ? "a path" : "paths"} no variable in the neutral file lands at: ${unmatched.join(", ")}. Use the tiered paths the preview prints; nothing was written.`]
 	};
-	const { merged, written, skipped } = mergeNeutralIntoJson(neutral, parsed, inputs.only);
-	await mkdir(dirname(tokenPath), { recursive: true });
-	await writeFile(tokenPath, writeJsonFile(merged));
+	const { merged, written, skipped, unsynced } = mergeNeutralIntoJson(neutral, parsed, inputs.only);
+	if (exceedsNestingLimit(merged)) return {
+		...empty,
+		tokensFound,
+		changes,
+		refused: true,
+		problems: [`not applied — with this import, ${DESIGN_TOKENS_FILE} would fail validation: ${NESTED_TOO_DEEPLY} ${IMPORT_TOO_DEEP_HINT}`]
+	};
+	const text = writeJsonFile(merged);
+	const mergedFaults = [...nonFiniteNumberFaults(merged), ...tokenFileViolationMessages(text)];
+	if (mergedFaults.length > 0) {
+		const onDisk = new Set(raw === void 0 ? [] : tokenFileViolationMessages(raw));
+		const introduced = mergedFaults.filter((fault) => !onDisk.has(fault));
+		const landings = new Set(changes.map((change) => change.path));
+		const dangling = danglingAliasTargets(merged, written);
+		const leftBehind = dangling.filter((target) => landings.has(target));
+		const notCarried = dangling.filter((target) => !landings.has(target));
+		const hint = notCarried.length === 0 ? IMPORT_INVALID_HINT : `${leftBehind.length > 0 ? `Add ${leftBehind.join(", ")} to the \`--only\` slice. ` : ""}The neutral file carries no variable that lands at ${notCarried.join(", ")}, so no \`--only\` slice can supply ${notCarried.length === 1 ? "it" : "them"}: ${IMPORT_NOT_CARRIED_HINT}`;
+		return {
+			...empty,
+			tokensFound,
+			changes,
+			refused: true,
+			problems: [introduced.length > 0 ? `not applied — with this import, ${DESIGN_TOKENS_FILE} would fail validation: ${summarizeMessages(introduced)} ${hint}` : `not applied — ${DESIGN_TOKENS_FILE} already fails validation and this import does not repair it: ${summarizeMessages(mergedFaults)} ${VALIDATE_HINT}`]
+		};
+	}
+	if (written.length > 0) {
+		const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+		await mkdir(dirname(tokenPath), { recursive: true });
+		await writeFile(tokenPath, text);
+	}
 	return {
 		tokensFound,
 		changes,
 		applied: true,
+		refused: false,
 		written,
 		skipped,
-		problems: []
+		unsynced,
+		problems: [],
+		warnings: []
 	};
 };
 const asMessage$1 = (error) => error instanceof Error ? error.message : String(error);
@@ -2004,15 +2635,22 @@ const runExport = async (inputs) => {
 	const empty = {
 		tokensFound: false,
 		plan: [],
+		unprojected: [],
 		hash: "",
 		recorded: false,
 		problems: []
 	};
-	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return empty;
 	let parsed;
 	try {
-		parsed = readJsonObject(await readFile(tokenPath, "utf8"));
+		const raw = await readOptionalTokenFile(inputs.repoRoot);
+		if (raw === void 0) return empty;
+		parsed = readJsonObject(raw);
+		const invalid = summarizeTokenFileViolations(raw);
+		if (invalid !== void 0) return {
+			...empty,
+			tokensFound: true,
+			problems: [`${DESIGN_TOKENS_FILE} fails validation: ${invalid} ${VALIDATE_HINT}`]
+		};
 	} catch (error) {
 		return {
 			...empty,
@@ -2028,35 +2666,46 @@ const runExport = async (inputs) => {
 	};
 	const hash = projectionHash(parsed);
 	let toolState;
-	if (inputs.toolStatePath !== void 0) {
-		if (!await pathExists(inputs.toolStatePath)) return {
+	if (inputs.toolStatePath !== void 0) try {
+		toolState = parseNeutralFile(await readRequiredFile(inputs.toolStatePath, "tool-state"), "tool-state");
+	} catch (error) {
+		return {
+			...empty,
+			tokensFound: true,
+			hash,
+			problems: [asMessage(error)]
+		};
+	}
+	const plan = upsertPlan(parsed, toolState);
+	const unprojected = unsyncedTokens(parsed);
+	if (inputs.outPath !== void 0) {
+		const projection = dtcgToNeutral(parsed);
+		projection.provider = binding.provider;
+		if (await sameEntry(inputs.outPath, join(inputs.repoRoot, "docs/design-tokens.json"))) return {
 			...empty,
 			tokensFound: true,
 			hash,
-			problems: [`tool-state file not found: ${inputs.toolStatePath}`]
+			problems: [`Cannot write the projection to ${inputs.outPath}: it is ${DESIGN_TOKENS_FILE} itself, which the projection would replace. Name another path.`]
 		};
 		try {
-			toolState = parseNeutralFile(await readFile(inputs.toolStatePath, "utf8"));
+			await writeRegularFile(inputs.outPath, writeNeutralFile(projection));
 		} catch (error) {
 			return {
 				...empty,
 				tokensFound: true,
 				hash,
-				problems: [asMessage(error)]
+				problems: [`Cannot write the projection to ${inputs.outPath}: ${asMessage(error)}`]
 			};
 		}
 	}
-	const plan = upsertPlan(parsed, toolState);
-	if (inputs.outPath !== void 0) {
-		const projection = dtcgToNeutral(parsed);
-		projection.provider = binding.provider;
-		await writeFile(inputs.outPath, writeNeutralFile(projection));
-	}
 	if (inputs.record) {
-		await writeFile(tokenPath, writeJsonFile(stampBaseline(parsed, hash)));
+		const stamped = writeJsonFile(stampBaseline(parsed, hash));
+		const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+		await writeFile(tokenPath, stamped);
 		return {
 			tokensFound: true,
 			plan,
+			unprojected,
 			hash,
 			recorded: true,
 			problems: []
@@ -2065,13 +2714,14 @@ const runExport = async (inputs) => {
 	return {
 		tokensFound: true,
 		plan,
+		unprojected,
 		hash,
 		recorded: false,
 		problems: []
 	};
 };
 const stampBaseline = (parsed, hash) => {
-	const clone = structuredClone(parsed);
+	const clone = { ...parsed };
 	const extensions = isRecord(clone["$extensions"]) ? { ...clone["$extensions"] } : {};
 	const binding = isRecord(extensions["com.lemony.design-tool"]) ? { ...extensions[DESIGN_TOOL_EXTENSION] } : {};
 	binding["lastProjected"] = hash;
@@ -2079,6 +2729,10 @@ const stampBaseline = (parsed, hash) => {
 	clone["$extensions"] = extensions;
 	return clone;
 };
+const sameEntry = async (a, b) => {
+	const [left, right] = await Promise.all([a, b].map((path) => stat(path).catch(() => void 0)));
+	return left !== void 0 && right !== void 0 && left.dev === right.dev && left.ino === right.ino;
+};
 const asMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
 //#region src/review-ledger/review-ledger.constant.ts
@@ -2095,13 +2749,14 @@ const SPEC_SIDE_KINDS = [
 	"malformed-risk-marker",
 	"malformed-task-refs",
 	"unknown-risk-class",
-	"dangling-requirement-ref"
+	"dangling-requirement-ref",
+	"unticked-completed-task"
 ];
 const GROUP_HEADER = /^##\s+Group\s+(\d+)\b/;
 const RISK_MARKER = /\[risk:\s*([^\]]*)\]\s*$/;
 const RISK_MARKER_ALL = /\[risk:/gi;
 const RISK_MARKER_LOOKALIKE = /\[\s*risks?\s*:/i;
-const TASK_LINE = /^\s*[-*+]\s*\[[ xX]\]\s*(?:\*\*|__|`)?\s*(T\d+)\b/;
+const TASK_LINE = /^\s*[-*+]\s*\[([ xX])\]\s*(?:\*\*|__|`)?\s*(T\d+)\b/;
 const TASK_REFS = /^\(((?:R\d+)(?:\s*,\s*R\d+)*)\)/;
 const TASK_REFS_LOOKALIKE_ALL = /\(\s*R\d+/g;
 const TASK_TITLE_WRAPPER = /^\s*[-*+]\s*\[[ xX]\]\s*(\*\*|__)/;
@@ -2156,7 +2811,7 @@ const parseTasksSpec = (text) => {
 		const blockEnd = taskBlockEnd(lines, index);
 		const parts = lines.slice(index, blockEnd).map((part) => part.trim());
 		index = blockEnd - 1;
-		const task = parseTaskBlock(match[1] ?? "", parts);
+		const task = parseTaskBlock(match[2] ?? "", (match[1] ?? " ") !== " ", parts);
 		if (task.malformedRefs) malformedTaskRefs.push(task.id);
 		if (current) {
 			current.tasks.push(task.task);
@@ -2197,7 +2852,7 @@ const taskBlockEnd = (lines, start) => {
 	}
 	return end;
 };
-const parseTaskBlock = (id, parts) => {
+const parseTaskBlock = (id, ticked, parts) => {
 	const block = parts.join(" ");
 	const opener = refsOpener(parts, block);
 	const refs = opener === void 0 ? null : declarationAt(parts, block, opener);
@@ -2206,6 +2861,7 @@ const parseTaskBlock = (id, parts) => {
 		id,
 		task: {
 			id,
+			ticked,
 			requirementRefs: [...new Set(requirementRefs)]
 		},
 		malformedRefs: refs === null && hasRefLookalike(parts)
@@ -2424,6 +3080,7 @@ const runLedgerValidate = async (inputs) => {
 			});
 		}
 	}
+	checkTicks(spec.groups, address, problems);
 	const slice = sliceForGroups(groups);
 	result.basis = slice.basis;
 	const dangling = await collectDanglingRefs(requirementsPath, slice.ids, problems);
@@ -2459,6 +3116,17 @@ const resolveGroups = (groups, address, problems) => {
 		message: `tasks.md declares ${groups.length} group(s); step ${address.step} has none. One step is one group.`
 	});
 };
+const checkTicks = (groups, address, problems) => {
+	const passed = address.kind === "full-pass" ? groups : groups.filter((group) => group.index <= address.step);
+	for (const group of passed) for (const task of group.tasks) {
+		if (task.ticked) continue;
+		problems.push({
+			kind: "unticked-completed-task",
+			message: `${task.id} (Group ${group.index}) is still "[ ]" in tasks.md, in a group the loop has passed. The Implementer ticks a task when it reaches green; an unticked task here is a forgotten mark or work that was never done — the human decides which.`,
+			subject: task.id
+		});
+	}
+};
 const collectDanglingRefs = async (requirementsPath, sliceIds, problems) => {
 	const referenced = sliceIds.filter((id) => id.startsWith("R"));
 	if (referenced.length === 0) return [];
@@ -2570,19 +3238,7 @@ const checkMutantsFloor = (ledger, owedFiles, anchor, problems) => {
 		});
 	}
 };
-const collectDeclaredGates = async (repoRoot) => {
-	if (!await configEntryExists(join(repoRoot, "harness.config.yml"))) return;
-	return (await readHarnessConfig(repoRoot)).gates;
-};
-const configEntryExists = async (path) => {
-	try {
-		await lstat(path);
-		return true;
-	} catch (error) {
-		if (error.code === "ENOENT") return false;
-		throw error;
-	}
-};
+const collectDeclaredGates = async (repoRoot) => (await readOptionalHarnessConfig(repoRoot))?.gates;
 const owedGates = (declared) => ({
 	basis: declared === void 0 ? "undeclared" : "config",
 	required: [...new Set(declared ?? [])],
@@ -3409,7 +4065,7 @@ const inspectDevDependency = async (repoRoot) => {
 	const pkgPath = join(repoRoot, "package.json");
 	if (!await pathExists(pkgPath)) return "no-package-json";
 	try {
-		const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+		const pkg = JSON.parse(await readRegularFile(pkgPath));
 		return Object.hasOwn(pkg.dependencies ?? {}, "@lemoncode/lemony") || Object.hasOwn(pkg.devDependencies ?? {}, "@lemoncode/lemony") ? "declared" : "missing";
 	} catch {
 		return "no-package-json";
@@ -3680,14 +4336,27 @@ const checkHooks = async (repoRoot) => {
 	const settingsPath = join(repoRoot, SETTINGS_FILE);
 	let raw;
 	try {
-		raw = await readFile(settingsPath, "utf8");
-	} catch {
-		return {
+		raw = await readRegularFile(settingsPath);
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT" && await lstat(settingsPath).then(() => true, () => false)) return {
+			name,
+			status: "fail",
+			detail: ".claude/settings.json is a symlink whose target is missing.",
+			remediation: "Remove the symlink, then run `lemony repair`."
+		};
+		if (code === "ENOENT") return {
 			name,
 			status: "fail",
 			detail: ".claude/settings.json not found.",
 			remediation: "Run `lemony repair`."
 		};
+		return {
+			name,
+			status: "fail",
+			detail: `Cannot read .claude/settings.json: ${code === void 0 ? error.message : `${code}.`}`,
+			remediation: "Replace it with a readable file (or remove it), then run `lemony repair`."
+		};
 	}
 	let commands;
 	try {
@@ -3844,29 +4513,46 @@ const checkCapabilities = async (deps, config) => {
 };
 const checkDesignToolDrift = async (deps) => {
 	const name = "design-tool-drift";
-	const tokenPath = join(deps.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return {
+	let raw;
+	try {
+		raw = await readOptionalTokenFile(deps.repoRoot);
+	} catch (error) {
+		return {
+			name,
+			status: "fail",
+			detail: error.message,
+			remediation: "Run `lemony design-tokens validate` to find the problem."
+		};
+	}
+	if (raw === void 0) return {
 		name,
 		status: "info",
 		detail: `No ${DESIGN_TOKENS_FILE} — token sync not in use.`
 	};
 	let parsed;
 	try {
-		parsed = JSON.parse(await readFile(tokenPath, "utf8"));
+		parsed = JSON.parse(raw);
 	} catch (error) {
 		return {
 			name,
-			status: "warn",
-			detail: `Could not read ${DESIGN_TOKENS_FILE}: ${error.message}`,
+			status: "fail",
+			detail: `${DESIGN_TOKENS_FILE} is not valid JSON: ${error.message}`,
 			remediation: "Run `lemony design-tokens validate` to find the problem."
 		};
 	}
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
 		name,
-		status: "warn",
+		status: "fail",
 		detail: `${DESIGN_TOKENS_FILE} is not a JSON object.`,
 		remediation: "Run `lemony design-tokens validate` to find the problem."
 	};
+	const invalid = summarizeTokenFileViolations(raw);
+	if (invalid !== void 0) return {
+		name,
+		status: "fail",
+		detail: `${DESIGN_TOKENS_FILE} fails validation: ${invalid}`,
+		remediation: "Run `lemony design-tokens validate` to find the problem."
+	};
 	const report = driftReport(parsed);
 	switch (report.state) {
 		case "n/a": return {
@@ -3979,43 +4665,44 @@ const isReadable = async (path) => {
 	}
 };
 //#endregion
+//#region src/status/parse-task-branch.ts
+const TASK_BRANCH = /^harness\/(\d+)-.+$/;
+const parseTaskBranch = (branch) => branch === null ? null : TASK_BRANCH.exec(branch)?.[1] ?? null;
+//#endregion
 //#region src/status/status.ts
 const PAUSED_LABEL = "harness:status:paused-for-clarification";
 const runStatus = async (deps) => {
 	const { repoRoot } = deps;
 	const config = await readHarnessConfig(repoRoot);
-	const pointer = await readPointer(repoRoot, deps.readGitUserEmail);
+	const lastSession = await readPointer(repoRoot, deps.readGitUserEmail);
 	const { branch, behind } = await deps.gitBehind(repoRoot);
 	const provider = createTaskTrackerProvider(config.task_storage.type, deps.runCommand);
 	const openDiscoveries = await countOpenDiscoveries(provider, config.task_storage.repo);
 	return {
 		vendorVersion: config.vendor_version,
 		taskStorageRepo: config.task_storage.repo,
-		activeTask: pointer.activeTask,
-		branch: branch ?? pointer.branch,
+		activeTask: parseTaskBranch(branch),
+		branch,
 		behind,
-		lastSession: pointer.lastSession,
+		lastSession,
 		openDiscoveries,
 		designToolDrift: await readDriftState(repoRoot)
 	};
 };
 const readDriftState = async (repoRoot) => {
-	const tokenPath = join(repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return null;
 	try {
-		const parsed = JSON.parse(await readFile(tokenPath, "utf8"));
+		const raw = await readOptionalTokenFile(repoRoot);
+		if (raw === void 0) return null;
+		const parsed = JSON.parse(raw);
 		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+		if (summarizeTokenFileViolations(raw) !== void 0) return null;
 		return driftReport(parsed).state;
 	} catch {
 		return null;
 	}
 };
 const readPointer = async (repoRoot, readGitUserEmail) => {
-	const empty = {
-		activeTask: null,
-		branch: null,
-		lastSession: null
-	};
+	const empty = null;
 	const email = await readGitUserEmail(repoRoot);
 	if (!email) return empty;
 	const slug = email.split("@")[0] ?? "";
@@ -4023,7 +4710,7 @@ const readPointer = async (repoRoot, readGitUserEmail) => {
 	const pointerPath = join(repoRoot, STATE_DIR, `current-${slug}.md`);
 	let raw;
 	try {
-		raw = await readFile(pointerPath, "utf8");
+		raw = await readRegularFile(pointerPath);
 	} catch {
 		return empty;
 	}
@@ -4031,12 +4718,7 @@ const readPointer = async (repoRoot, readGitUserEmail) => {
 	if (!match) return empty;
 	const parsed = pointerFrontmatterSchema.safeParse(parse(match[1] ?? ""));
 	if (!parsed.success) return empty;
-	const front = parsed.data;
-	return {
-		activeTask: normalize(front.active_task),
-		branch: normalize(front.branch),
-		lastSession: normalize(front.last_close_ts)
-	};
+	return normalize(parsed.data.last_close_ts);
 };
 const normalize = (value) => {
 	if (value === null || value === void 0) return null;
@@ -4103,12 +4785,12 @@ const COMMANDS = [
 	},
 	{
 		name: "design-tokens",
-		summary: "Validate the 3-tier design-token file (and gate UI source against hardcoded values), check WCAG contrast of token pairs, or sync tokens with a design tool (consume-if-exists; never created).",
+		summary: "Validate the 3-tier design-token file (and gate UI source against hardcoded values), check WCAG contrast of token pairs, or sync tokens with a design tool (consume-if-exists: the gates never create the file; `import --apply` bootstraps it).",
 		usage: "lemony design-tokens <validate [--scan=<dir>] | contrast | import --from=<file> [--apply] [--only=<paths>] | export [--tool-state=<file>] [--out=<file>] [--record]>"
 	},
 	{
 		name: "review-ledger",
-		summary: "Validate the Reviewer's evidence ledger (the JSON sidecar under the task's state) against the spec's groups, the anchored diff and the declared gates: shape, criteria-vs-slice, unknown risk classes, the mutant floor, the gates floor (deterministic, agent-free; exits non-zero on an invalid ledger).",
+		summary: "Validate the Reviewer's evidence ledger (the JSON sidecar under the task's state) against the spec's groups, the anchored diff and the declared gates: shape, criteria-vs-slice, unknown risk classes, the mutant floor, the gates floor, the tick check on passed groups (deterministic, agent-free; exits non-zero on an invalid ledger).",
 		usage: "lemony review-ledger validate --task-id=<id> --anchor=<oid> (--step=<N> | --full-pass)"
 	},
 	{
@@ -4673,54 +5355,6 @@ const materializeVendorFiles = async (ctx) => {
 	];
 };
 //#endregion
-//#region src/install/gitignore.ts
-const GITIGNORE_BEGIN = "# BEGIN lemony";
-const GITIGNORE_END = "# END lemony";
-const GITIGNORE_BLOCK = [
-	GITIGNORE_BEGIN,
-	".claude/state/current-*.md",
-	".claude/state/.ptr.*",
-	".claude/state/sessions/",
-	".claude/state/events.jsonl",
-	".claude/state/telemetry-cursor.json",
-	".claude/state/telemetry-consent.json",
-	".claude/state/.telemetry-notice-shown",
-	".claude/state/telemetry-rejected.jsonl",
-	".claude/.harness/snapshots/",
-	GITIGNORE_END
-].join("\n");
-const appendGitignoreBlock = async (repoRoot) => {
-	const gitignorePath = join(repoRoot, ".gitignore");
-	const current = await pathExists(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
-	const beginIdx = current.indexOf(GITIGNORE_BEGIN);
-	const endIdx = current.indexOf(GITIGNORE_END, beginIdx);
-	if (beginIdx !== -1 && endIdx !== -1) {
-		const next = current.slice(0, beginIdx) + GITIGNORE_BLOCK + current.slice(endIdx + 12);
-		if (next === current) return null;
-		await writeFile(gitignorePath, next);
-		return ".gitignore";
-	}
-	const prefix = current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n";
-	await writeFile(gitignorePath, `${current}${prefix}${GITIGNORE_BLOCK}\n`);
-	return ".gitignore";
-};
-const removeGitignoreBlock = async (repoRoot) => {
-	const relPath = ".gitignore";
-	const gitignorePath = join(repoRoot, relPath);
-	if (!await pathExists(gitignorePath)) return null;
-	const lines = (await readFile(gitignorePath, "utf8")).split("\n");
-	const startLine = lines.findIndex((line) => line.trim() === GITIGNORE_BEGIN);
-	const endLine = startLine === -1 ? -1 : lines.findIndex((line, index) => index > startLine && line.trim() === GITIGNORE_END);
-	if (startLine === -1 || endLine === -1) return null;
-	const result = [...lines.slice(0, startLine), ...lines.slice(endLine + 1)].join("\n").replace(/\n+$/, "\n");
-	if (result.trim() === "") {
-		await rm(gitignorePath, { force: true });
-		return relPath;
-	}
-	await writeFile(gitignorePath, result);
-	return relPath;
-};
-//#endregion
 //#region src/install/merge-settings.ts
 const mergeSettingsHooks = async (templatePath, destPath) => {
 	const templateRaw = await readFile(templatePath, "utf8");
@@ -4728,7 +5362,7 @@ const mergeSettingsHooks = async (templatePath, destPath) => {
 	if (template.hooks === void 0) throw new Error(`settings template at ${templatePath} has no "hooks" key — vendor authority is the hooks block.`);
 	let existing = {};
 	if (await pathExists(destPath)) {
-		const existingRaw = await readFile(destPath, "utf8");
+		const existingRaw = await readSettings(destPath, mergeContext(destPath));
 		if (existingRaw.trim().length > 0) try {
 			existing = JSON.parse(existingRaw);
 		} catch (cause) {
@@ -4746,7 +5380,7 @@ const mergeSettingsHooks = async (templatePath, destPath) => {
 };
 const removeSettingsHooks = async (settingsPath) => {
 	if (!await pathExists(settingsPath)) return "absent";
-	const raw = await readFile(settingsPath, "utf8");
+	const raw = await readSettings(settingsPath, removeContext(settingsPath));
 	if (raw.trim().length === 0) return "absent";
 	let parsed;
 	try {
@@ -4763,6 +5397,24 @@ const removeSettingsHooks = async (settingsPath) => {
 	await writeFile(settingsPath, `${JSON.stringify(rest, null, 2)}\n`);
 	return "stripped";
 };
+const mergeContext = (path) => `Cannot merge the harness hooks into ${path}`;
+const removeContext = (path) => `Cannot remove the harness hooks from ${path}`;
+const assertSettingsNotSpecial = async (path, action) => {
+	const target = await stat(path).catch(() => void 0);
+	if (target === void 0 || target.isFile()) return;
+	const context = action === "merge" ? mergeContext(path) : removeContext(path);
+	const reason = target.isDirectory() ? "the entry is a directory." : SPECIAL_FILE_REFUSAL;
+	throw new Error(`${context}: ${reason} ${REMOVE_IT}`);
+};
+const REMOVE_IT = "Remove it before re-running.";
+const readSettings = async (path, context) => {
+	try {
+		return await readRegularFile(path);
+	} catch (error) {
+		if (error.code !== void 0) throw error;
+		throw new Error(`${context}: ${error.message} ${REMOVE_IT}`, { cause: error });
+	}
+};
 const collectCommands = (hooks) => {
 	const result = /* @__PURE__ */ new Set();
 	if (!hooks || typeof hooks !== "object") return result;
@@ -4787,6 +5439,54 @@ const diffLostCommands = (existingHooks, templateHooks) => {
 	return lost.toSorted();
 };
 //#endregion
+//#region src/install/gitignore.ts
+const GITIGNORE_BEGIN = "# BEGIN lemony";
+const GITIGNORE_END = "# END lemony";
+const GITIGNORE_BLOCK = [
+	GITIGNORE_BEGIN,
+	".claude/state/current-*.md",
+	".claude/state/.ptr.*",
+	".claude/state/sessions/",
+	".claude/state/events.jsonl",
+	".claude/state/telemetry-cursor.json",
+	".claude/state/telemetry-consent.json",
+	".claude/state/.telemetry-notice-shown",
+	".claude/state/telemetry-rejected.jsonl",
+	".claude/.harness/snapshots/",
+	GITIGNORE_END
+].join("\n");
+const appendGitignoreBlock = async (repoRoot) => {
+	const gitignorePath = join(repoRoot, ".gitignore");
+	const current = await pathExists(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+	const beginIdx = current.indexOf(GITIGNORE_BEGIN);
+	const endIdx = current.indexOf(GITIGNORE_END, beginIdx);
+	if (beginIdx !== -1 && endIdx !== -1) {
+		const next = current.slice(0, beginIdx) + GITIGNORE_BLOCK + current.slice(endIdx + 12);
+		if (next === current) return null;
+		await writeFile(gitignorePath, next);
+		return ".gitignore";
+	}
+	const prefix = current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+	await writeFile(gitignorePath, `${current}${prefix}${GITIGNORE_BLOCK}\n`);
+	return ".gitignore";
+};
+const removeGitignoreBlock = async (repoRoot) => {
+	const relPath = ".gitignore";
+	const gitignorePath = join(repoRoot, relPath);
+	if (!await pathExists(gitignorePath)) return null;
+	const lines = (await readFile(gitignorePath, "utf8")).split("\n");
+	const startLine = lines.findIndex((line) => line.trim() === GITIGNORE_BEGIN);
+	const endLine = startLine === -1 ? -1 : lines.findIndex((line, index) => index > startLine && line.trim() === GITIGNORE_END);
+	if (startLine === -1 || endLine === -1) return null;
+	const result = [...lines.slice(0, startLine), ...lines.slice(endLine + 1)].join("\n").replace(/\n+$/, "\n");
+	if (result.trim() === "") {
+		await rm(gitignorePath, { force: true });
+		return relPath;
+	}
+	await writeFile(gitignorePath, result);
+	return relPath;
+};
+//#endregion
 //#region src/install/resync.ts
 const resyncSpecialCased = async (repoRoot, templateRoot) => {
 	const { lostCommands } = await mergeSettingsHooks(join(templateRoot, CLAUDE_DIR, "settings.json.tpl"), join(repoRoot, SETTINGS_FILE));
@@ -4843,6 +5543,7 @@ const runInstall = async (options) => {
 		...COMMITTED_STATE_DIRS.map((dir) => join(STATE_DIR, dir, ".gitkeep")),
 		HARNESS_CONFIG_FILENAME
 	]);
+	await assertSettingsNotSpecial(join(repoRoot, SETTINGS_FILE), "merge");
 	const readClient = async (relPath) => {
 		const filePath = join(repoRoot, relPath);
 		if (!await pathExists(filePath)) return null;
@@ -4991,6 +5692,7 @@ const runReconcile = async (inputs) => {
 		SETTINGS_FILE,
 		".gitignore"
 	]);
+	await assertSettingsNotSpecial(join(repoRoot, SETTINGS_FILE), "merge");
 	const actions = await runEngine({
 		baseline,
 		vendorNew,
@@ -5147,6 +5849,7 @@ const runUninstall = async (options) => {
 		HARNESS_DIR,
 		HARNESS_CONFIG_FILENAME
 	]);
+	await assertSettingsNotSpecial(join(repoRoot, SETTINGS_FILE), "remove");
 	await Promise.all(removedFiles.map((relPath) => rm(join(repoRoot, relPath), { force: true })));
 	await pruneEmptyDirs(repoRoot, removedFiles);
 	const settings = await removeSettingsHooks(join(repoRoot, SETTINGS_FILE));
@@ -5358,8 +6061,14 @@ const PACKAGE_JSON_PATH = join(PACKAGE_ROOT, "package.json");
 const execFileAsync = promisify(execFile);
 const parseFlag = (args, name) => {
 	const prefix = `--${name}=`;
-	const value = args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
-	return value ? value : void 0;
+	const joined = args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+	if (joined !== void 0) return joined ? joined : void 0;
+	const at = args.indexOf(`--${name}`);
+	const next = at === -1 ? void 0 : args[at + 1];
+	return next !== void 0 && next !== "" && !next.startsWith("--") ? next : void 0;
+};
+const rejectValuelessFlags = (verb, args, names) => {
+	for (const name of names) if (args.some((arg) => arg === `--${name}` || arg.startsWith(`--${name}=`)) && parseFlag(args, name) === void 0) throw new Error(`${verb}: --${name} was given without a value.`);
 };
 const readHarnessVersion = async () => {
 	const raw = await readFile(PACKAGE_JSON_PATH, "utf8");
@@ -5389,6 +6098,32 @@ const makeRunCommand = () => async (cmd, args) => {
 		};
 	}
 };
+const makeVerifierRunCommand = () => (cmd, args) => new Promise((resolveResult) => {
+	const child = spawn(cmd, args, { stdio: [
+		"ignore",
+		"pipe",
+		"pipe"
+	] });
+	const out = [];
+	const err = [];
+	child.stdout.on("data", (chunk) => out.push(chunk));
+	child.stderr.on("data", (chunk) => err.push(chunk));
+	child.on("error", (error) => {
+		resolveResult({
+			code: error.code === "ENOENT" ? 127 : 1,
+			stdout: Buffer.concat(out).toString("utf8"),
+			stderr: `${Buffer.concat(err).toString("utf8")}${error.message}\n`
+		});
+	});
+	child.on("close", (code, signal) => {
+		resolveResult({
+			code: code ?? 1,
+			stdout: Buffer.concat(out).toString("utf8"),
+			stderr: Buffer.concat(err).toString("utf8"),
+			...signal === null ? {} : { signal }
+		});
+	});
+});
 const buildResolveDeps = () => {
 	const rl = createInterface({
 		input: stdin,
@@ -5413,10 +6148,10 @@ const gitBehind = async (repoRoot) => {
 		repoRoot,
 		"symbolic-ref",
 		"--quiet",
-		"--short",
 		"HEAD"
 	]);
-	const branch = branchResult.code === 0 ? branchResult.stdout.trim() || null : null;
+	const ref = branchResult.code === 0 ? branchResult.stdout.trim() : "";
+	const branch = ref.startsWith("refs/heads/") ? ref.slice(11) || null : null;
 	const headRef = await run("git", [
 		"-C",
 		repoRoot,
@@ -5778,18 +6513,18 @@ const designTokens = async (args) => {
 	throw new Error(`Usage: lemony design-tokens <validate [--scan=<dir>] | contrast | import --from=<file> [--apply] [--only=<paths>] | export [--tool-state=<file>] [--out=<file>] [--record]>. Unknown action "${action}".`);
 };
 const designTokensValidate = async (args) => {
-	const config = await readHarnessConfig(cwd()).catch(() => void 0);
+	const config = await readOptionalHarnessConfig(cwd());
 	const result = await runValidate({
 		repoRoot: cwd(),
 		scanDir: parseFlag(args, "scan"),
 		extraExtensions: config?.design_tokens.scan_extensions
 	});
 	if (!result.tokensFound) {
-		console.log(`No docs/design-tokens.json — design-tokens validate skipped (consume-if-exists; the harness never creates it).`);
+		console.log(`No docs/design-tokens.json — design-tokens validate skipped (consume-if-exists; the gates never create it).`);
 		return;
 	}
 	if (result.ok) {
-		console.log(`design-tokens valid: ${result.tokenCount} token(s), ${result.filesScanned} file(s) scanned, no hardcoded values.`);
+		console.log(result.filesScanned === 0 ? `design-tokens valid: ${result.tokenCount} token(s), but 0 file(s) scanned — no readable source with a scanned extension was found, so nothing was checked for hardcoded values.` : `design-tokens valid: ${result.tokenCount} token(s), ${result.filesScanned} file(s) scanned, no hardcoded values.`);
 		return;
 	}
 	console.error(`design-tokens validate found ${result.violations.length} violation(s):`);
@@ -5799,26 +6534,77 @@ const designTokensValidate = async (args) => {
 	}
 	exit(1);
 };
+const verifierEnding = (outcome) => outcome.signal === void 0 ? `exited ${outcome.code}` : `was killed by ${outcome.signal}`;
+const quotedCommand = (command) => {
+	const lines = command.trimEnd().split("\n");
+	return lines.length > 1 ? `\`${lines[0]} …\`` : `\`${command}\``;
+};
+const drained = (stream) => new Promise((resolve) => {
+	stream.once("error", () => resolve());
+	stream.write("", () => resolve());
+});
+const contrastFailedLine = (pairCheck, verify) => {
+	if (verify === void 0) return `design-tokens contrast failed: ${pairCheck}.`;
+	const outcome = verify.code === 0 && verify.signal === void 0 ? "passed (exited 0)" : verifierEnding(verify);
+	return `design-tokens contrast failed: ${pairCheck}; design_tokens.verify ${quotedCommand(verify.command)} ${outcome}.`;
+};
 const designTokensContrast = async () => {
-	const result = await runContrast({ repoRoot: cwd() });
+	const verify = (await readOptionalHarnessConfig(cwd()))?.design_tokens.verify;
+	const result = await runContrast({
+		repoRoot: cwd(),
+		...verify === void 0 ? {} : { verify: {
+			command: verify,
+			run: makeVerifierRunCommand()
+		} }
+	});
+	const failures = result.pairs.filter((pair) => !pair.passes);
+	const forwardVerifier = () => {
+		if (result.verify === void 0) return;
+		const { stdout: out, stderr: err } = result.verify;
+		if (out.length > 0) stdout.write(out.endsWith("\n") ? out : `${out}\n`);
+		if (err.length > 0) stderr.write(err.endsWith("\n") ? err : `${err}\n`);
+	};
+	const failedVerifier = result.verify !== void 0 && result.verify.code !== 0 ? result.verify : void 0;
 	if (!result.tokensFound) {
-		console.log(`No docs/design-tokens.json — design-tokens contrast skipped (consume-if-exists; the harness never creates it).`);
+		console.log(result.verify === void 0 ? `No docs/design-tokens.json — design-tokens contrast skipped (consume-if-exists; the gates never create it).` : `No docs/design-tokens.json — design-tokens contrast pair check skipped (consume-if-exists; the gates never create it); running the declared design_tokens.verify.`);
+		if (result.verify === void 0) return;
+		if (failedVerifier) console.error(`design-tokens contrast found 1 issue(s):`);
+		forwardVerifier();
+		await Promise.all([drained(stdout), drained(stderr)]);
+		if (failedVerifier) {
+			console.error(`  design_tokens.verify ${quotedCommand(failedVerifier.command)} ${verifierEnding(failedVerifier)}.`);
+			console.error(contrastFailedLine("pair check skipped (no docs/design-tokens.json)", failedVerifier));
+			process.exitCode = 1;
+			return;
+		}
+		console.log(`design-tokens verify OK: ${quotedCommand(result.verify.command)} exited 0.`);
 		return;
 	}
-	const failures = result.pairs.filter((pair) => !pair.passes);
 	if (result.ok) {
 		console.log(result.pairsChecked === 0 ? `design-tokens contrast: no foreground/background pairs found (use the on-* convention or $extensions["com.lemony.contrast"]).` : `design-tokens contrast OK: ${result.pairsChecked} pair(s) meet their WCAG floor.`);
+		forwardVerifier();
+		if (result.verify !== void 0) console.log(`design-tokens verify OK: ${quotedCommand(result.verify.command)} exited 0.`);
 		return;
 	}
-	console.error(`design-tokens contrast found ${failures.length + result.problems.length} issue(s):`);
-	for (const pair of failures) console.error(`  ${pair.foreground} on ${pair.background} (${pair.mode}, ${pair.level}): ${pair.ratio}:1 < ${pair.floor}:1`);
+	console.error(`design-tokens contrast found ${failures.length + result.problems.length + (failedVerifier ? 1 : 0)} issue(s):`);
+	for (const pair of failures) {
+		const over = pair.over === void 0 ? "" : ` over ${pair.over}`;
+		console.error(`  ${pair.foreground} on ${pair.background}${over} (${pair.mode}, ${pair.level}): ${pair.ratio}:1 < ${pair.floor}:1`);
+	}
 	for (const problem of result.problems) console.error(`  ${problem}`);
-	exit(1);
+	forwardVerifier();
+	await Promise.all([drained(stdout), drained(stderr)]);
+	if (failedVerifier) console.error(`  design_tokens.verify ${quotedCommand(failedVerifier.command)} ${verifierEnding(failedVerifier)}.`);
+	const pairIssues = failures.length + result.problems.length;
+	console.error(contrastFailedLine(pairIssues > 0 ? result.pairsChecked === 0 ? `pair check measured no pair (${pairIssues} issue(s) above)` : `pair check found ${pairIssues} issue(s)` : result.pairsChecked === 0 ? "pair check found no pairs" : "pair check passed", result.verify));
+	process.exitCode = 1;
 };
 const designTokensImport = async (args) => {
 	const from = parseFlag(args, "from");
 	if (from === void 0) throw new Error("Usage: lemony design-tokens import --from=<neutral-file> [--apply] [--only=<dotted,paths>]");
+	rejectValuelessFlags("design-tokens import", args, ["only"]);
 	const only = parseFlag(args, "only")?.split(",").map((path) => path.trim()).filter((path) => path.length > 0);
+	if (only?.length === 0) throw new Error("design-tokens import: --only names no path.");
 	const result = await runImport({
 		repoRoot: cwd(),
 		neutralPath: resolve(cwd(), from),
@@ -5826,26 +6612,43 @@ const designTokensImport = async (args) => {
 		only
 	});
 	if (result.problems.length > 0) {
-		console.error("design-tokens import could not run:");
+		console.error(result.refused ? "design-tokens import --apply refused:" : "design-tokens import could not run:");
 		for (const problem of result.problems) console.error(`  ${problem}`);
-		exit(1);
+		if (result.changes.length > 0) printImportPreview(result);
+		process.exitCode = 1;
+		return;
 	}
 	if (result.applied) {
 		console.log(`design-tokens import applied: wrote ${result.written.length} token(s) to ${DESIGN_TOKENS_FILE}.`);
 		if (result.skipped.length > 0) console.log(`  skipped ${result.skipped.length} path(s) that would clobber an existing group or token — resolve by hand: ${result.skipped.join(", ")}`);
+		if (result.unsynced.length > 0) console.log(`  not applied: ${result.unsynced.length} token(s) outside the design-tool sync, which one tool value cannot replace: ${result.unsynced.join(", ")}`);
 		return;
 	}
+	const landing = printImportPreview(result);
+	for (const warning of result.warnings) console.error(`  Warning: ${warning}`);
+	if (landing > 0) console.log(`Curate the slice, then: lemony design-tokens import --from=${from} --apply --only=<paths>`);
+};
+const printImportPreview = (result) => {
 	const landing = result.changes.filter((change) => change.kind !== "unchanged");
 	const news = landing.filter((change) => change.kind === "new").length;
 	const changed = landing.length - news;
 	console.log(`design-tokens import preview: ${news} new, ${changed} changed, ${result.changes.length - landing.length} unchanged.`);
 	for (const change of landing) {
-		const detail = change.kind === "changed" ? `${change.before} → ${change.after}` : change.after;
+		const detail = change.kind === "changed" ? changedDetail(change) : change.after;
 		console.log(`  [${change.kind}] ${change.path} (${change.tier}): ${detail}`);
 	}
-	if (landing.length > 0) console.log(`Curate the slice, then: lemony design-tokens import --from=${from} --apply --only=<paths>`);
+	return landing.length;
+};
+const changedDetail = (change) => {
+	const parts = [];
+	if (change.before !== change.after) parts.push(`${shown(change.before)} → ${shown(change.after)}`);
+	if (change.typeChange) parts.push(`$type ${shown(change.typeChange.before)} → ${shown(change.typeChange.after)}`);
+	for (const mode of change.modeChanges ?? []) parts.push(`${mode.mode}: ${shown(mode.before)} → ${shown(mode.after)}`);
+	return parts.join("; ");
 };
+const shown = (value) => value === void 0 || value === "" ? "(none)" : value;
 const designTokensExport = async (args) => {
+	rejectValuelessFlags("design-tokens export", args, ["tool-state", "out"]);
 	const toolState = parseFlag(args, "tool-state");
 	const out = parseFlag(args, "out");
 	if (out !== void 0 && args.includes("--record")) {
@@ -5859,7 +6662,7 @@ const designTokensExport = async (args) => {
 		record: args.includes("--record")
 	});
 	if (!result.tokensFound) {
-		console.log(`No ${DESIGN_TOKENS_FILE} — design-tokens export skipped (consume-if-exists; the harness never creates it).`);
+		console.log(`No ${DESIGN_TOKENS_FILE} — design-tokens export skipped (consume-if-exists; export never creates it).`);
 		return;
 	}
 	if (result.problems.length > 0) {
@@ -5874,6 +6677,7 @@ const designTokensExport = async (args) => {
 	const creates = result.plan.filter((entry) => entry.kind === "create").length;
 	const updates = result.plan.filter((entry) => entry.kind === "update").length;
 	console.log(`design-tokens export plan: ${creates} to create, ${updates} to update (tool-only variables are never deleted).`);
+	if (result.unprojected.length > 0) console.log(`  not projected: ${result.unprojected.length} token(s) a design tool variable cannot hold: ${result.unprojected.map(({ path, reason }) => `${path} (${reason})`).join(", ")}`);
 	if (out !== void 0) console.log(`  projection written to ${out}`);
 };
 const REVIEW_LEDGER_USAGE = "Usage: lemony review-ledger validate --task-id=<id> --anchor=<oid> (--step=<N> | --full-pass).";