@lemoncode/lemony 0.5.0 → 0.6.0

package/dist/cli.mjs

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 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 { basename, delimiter, dirname, extname, join, posix, 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 { isMap, isPair, isScalar, parse, parseDocument, visit } from "yaml";
+import { constants } from "node:fs";
 import { z } from "zod";
 import { createHash, randomBytes } from "node:crypto";
-import { constants } from "node:fs";
+import MarkdownIt from "markdown-it";
 //#region src/events/append.ts
 const appendEvent = async (eventsPath, event) => {
 	await mkdir(dirname(eventsPath), { recursive: true });
@@ -17,6 +18,8 @@ const appendEvent = async (eventsPath, event) => {
 //#endregion
 //#region src/config/config.constant.ts
 const HARNESS_CONFIG_FILENAME = "harness.config.yml";
+const CONFIG_MALFORMED_MESSAGE = `${HARNESS_CONFIG_FILENAME} is empty or malformed.`;
+const NULL_BLOCK_SENTINEL = "lemony-null-block-comment-";
 const DEPRECATED_CONFIG_KEYS = ["profile", "agents"];
 const DEPRECATED_PATHS_KEYS = [
 	"state",
@@ -28,7 +31,8 @@ const HARNESS_CONFIG_SCHEMA_FILENAME = "harness.config.schema.json";
 const CONFIG_KEY_SINCE = {
 	gates: "0.3.0",
 	"implementation.auto_commit": "0.4.0",
-	"design_tokens.verify": "0.5.0"
+	"design_tokens.verify": "0.5.0",
+	"design_tokens.file": "0.6.0"
 };
 const TASK_STORAGE_REPO_PLACEHOLDER = "OWNER/REPO";
 const TARGETS = ["claude-code"];
@@ -47,6 +51,236 @@ 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) {
+		if (error.code !== "EEXIST") throw error;
+		if ((await lstat(path).catch(() => void 0))?.isSymbolicLink()) throw new Error(DANGLING_WRITE_REFUSAL, { cause: error });
+	}
+	return await open(path, WRITE);
+};
+//#endregion
+//#region src/fs/symlink-guard.ts
+const assertNoSymlinkTraversal = async (root, relPaths) => {
+	const offenders = await findSymlinkTraversals(root, relPaths);
+	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"));
+};
+const findSymlinkTraversals = 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);
+		}
+	}
+	return (await Promise.all([...components].map(async (rel) => {
+		try {
+			return (await lstat(join(root, rel))).isSymbolicLink() ? rel : null;
+		} catch {
+			return null;
+		}
+	}))).filter((rel) => rel !== null);
+};
+//#endregion
+//#region src/paths/claude-paths.constant.ts
+const CLAUDE_DIR = ".claude";
+const STATE_DIR = join(CLAUDE_DIR, "state");
+const TASKS_DIR = join(STATE_DIR, "tasks");
+const SKILLS_DIR = join(CLAUDE_DIR, "skills");
+const AGENTS_DIR = join(CLAUDE_DIR, "agents");
+const HOOKS_DIR = join(CLAUDE_DIR, "hooks");
+const COMMANDS_DIR = join(CLAUDE_DIR, "commands");
+const SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
+const HARNESS_DIR = join(CLAUDE_DIR, ".harness");
+const BASELINE_ROOT_REL = join(HARNESS_DIR, "baseline");
+const SNAPSHOTS_ROOT_REL = join(HARNESS_DIR, "snapshots");
+const EVENTS_RELPATH = join(STATE_DIR, "events.jsonl");
+//#endregion
+//#region src/config/classify-config-link.ts
+const LINK_FAULTS = /* @__PURE__ */ new Map([
+	["ENOENT", "target-missing"],
+	["ENOTDIR", "target-missing"],
+	["ENAMETOOLONG", "target-missing"],
+	["ELOOP", "loop"],
+	["EACCES", "target-unreadable"]
+]);
+const classifyConfigLinkFault = async (configPath, readError) => {
+	const code = readError?.code;
+	const fault = code === void 0 ? void 0 : LINK_FAULTS.get(code);
+	if (fault === void 0) return void 0;
+	return await lstat(configPath).then((entry) => entry.isSymbolicLink(), () => false) ? fault : void 0;
+};
+//#endregion
+//#region src/baseline/baseline.ts
+const STAGING_DIR$1 = ".staging";
+const isENOENT$1 = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+const baselineRootDir = (repoRoot) => join(repoRoot, BASELINE_ROOT_REL);
+const baselineVersionDir = (repoRoot, version) => join(baselineRootDir(repoRoot), version);
+const writeBaseline = async (repoRoot, version, files) => {
+	const root = baselineRootDir(repoRoot);
+	const staging = join(root, STAGING_DIR$1);
+	await rm(staging, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(staging, { recursive: true });
+	await Promise.all(files.map(async ({ relPath, content }) => {
+		const dest = join(staging, relPath);
+		await mkdir(dirname(dest), { recursive: true });
+		await writeFile(dest, content);
+	}));
+	const versionDir = baselineVersionDir(repoRoot, version);
+	await rm(versionDir, {
+		recursive: true,
+		force: true
+	});
+	await rename(staging, versionDir);
+	await pruneOtherVersions(root, version);
+};
+const pruneOtherVersions = async (root, keep) => {
+	const entries = await readdir(root, { withFileTypes: true });
+	await Promise.all(entries.filter((entry) => entry.isDirectory() && entry.name !== keep).map((entry) => rm(join(root, entry.name), {
+		recursive: true,
+		force: true
+	})));
+};
+const readBaseline = async (repoRoot, version) => {
+	const versionDir = baselineVersionDir(repoRoot, version);
+	let relPaths;
+	try {
+		relPaths = await listFiles(versionDir);
+	} catch (error) {
+		if (isENOENT$1(error)) return /* @__PURE__ */ new Map();
+		throw error;
+	}
+	const entries = await Promise.all(relPaths.map(async (relPath) => [relPath, await readFile(join(versionDir, relPath), "utf8")]));
+	return new Map(entries);
+};
+const findBaselineVersion = async (repoRoot) => {
+	const root = baselineRootDir(repoRoot);
+	let entries;
+	try {
+		entries = await readdir(root, { withFileTypes: true });
+	} catch (error) {
+		if (isENOENT$1(error)) return null;
+		throw error;
+	}
+	const versions = entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name);
+	if (versions.length <= 1) return versions[0] ?? null;
+	const withMtime = await Promise.all(versions.map(async (version) => ({
+		version,
+		mtimeMs: (await stat(join(root, version))).mtimeMs
+	})));
+	withMtime.sort((a, b) => a.mtimeMs - b.mtimeMs || a.version.localeCompare(b.version, void 0, { numeric: true }));
+	return withMtime.at(-1)?.version ?? null;
+};
+//#endregion
+//#region src/config/has-install-baseline.ts
+const hasInstallBaseline = async (repoRoot) => findBaselineVersion(repoRoot).then((version) => version !== null, (error) => PERMISSION_CODES.has(error.code ?? ""));
+const PERMISSION_CODES = /* @__PURE__ */ new Set(["EACCES", "EPERM"]);
+//#endregion
 //#region src/config/config-error.ts
 const formatConfigError = (schema, error) => {
 	return error.issues.flatMap((issue) => formatIssue(schema, issue)).join("\n");
@@ -110,6 +344,16 @@ const levenshtein = (a, b) => {
 	return prev[b.length] ?? 0;
 };
 //#endregion
+//#region src/config/repo-relative-path.ts
+const repoRelativePathIssue = (value) => {
+	if (value.includes("\\")) return `must use "/" as the separator, got "${value}".`;
+	if (posix.isAbsolute(value) || /^[A-Za-z]:/.test(value)) return `must be relative to the repository root, got the absolute path "${value}".`;
+	const normalized = posix.normalize(value);
+	if (normalized === ".." || normalized.startsWith("../")) return `must stay inside the repository, got "${value}", which leads out of it.`;
+	if (normalized === "." || normalized === "./") return `must name a file inside the repository, got "${value}", which is the repository root.`;
+	if (value.endsWith("/") || posix.basename(value) === ".") return `must name a file, got "${value}", which names a directory.`;
+};
+//#endregion
 //#region src/config/config.schema.ts
 const pathsSchema = z.object({
 	playbooks: z.string().default(PATHS_DEFAULTS.playbooks),
@@ -123,7 +367,15 @@ const rollbackSchema = z.object({ keep_snapshots: z.union([z.int().positive(), z
 const telemetrySchema = z.object({ enabled: z.boolean().default(true) }).strict().prefault({});
 const designTokensSchema = z.object({
 	scan_extensions: z.array(z.string()).default([]),
-	verify: z.string().trim().min(1).optional()
+	verify: z.string().trim().min(1).optional(),
+	file: z.string().trim().min(1, "must name the token file, relative to the repository root.").superRefine((value, ctx) => {
+		if (value.length === 0) return;
+		const issue = repoRelativePathIssue(value);
+		if (issue !== void 0) ctx.addIssue({
+			code: "custom",
+			message: issue
+		});
+	}).optional()
 }).strict().prefault({});
 const mergeSchema = z.object({
 	checks_timeout_secs: z.int().positive().default(600),
@@ -145,24 +397,31 @@ const harnessConfigSchema = z.object({
 }).strict();
 //#endregion
 //#region src/config/config.ts
+const OPTIONAL_CONFIG_KEYS = Object.entries(harnessConfigSchema.shape).filter(([, schema]) => schema.safeParse(void 0).success).map(([key]) => key);
 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 });
+		const linkFault = await classifyConfigLinkFault(configPath, cause);
+		if (linkFault !== void 0) throw new Error(configLinkMessage(repoRoot, linkFault), { cause });
+		if (cause.code === "ENOENT") {
+			if (await hasInstallBaseline(repoRoot)) throw new Error(missingBesideBaselineMessage(repoRoot), { cause });
+			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 });
 	}
 	let parsed;
 	try {
 		parsed = parse(raw);
 	} catch (cause) {
-		throw new Error(`${HARNESS_CONFIG_FILENAME} is empty or malformed.`, { cause });
+		throw new Error(CONFIG_MALFORMED_MESSAGE, { cause });
 	}
-	if (!parsed || typeof parsed !== "object") throw new Error(`${HARNESS_CONFIG_FILENAME} is empty or malformed.`);
+	if (typeof parsed !== "object" || parsed === null || Object.getPrototypeOf(parsed) !== Object.prototype) throw new Error(CONFIG_MALFORMED_MESSAGE);
 	const candidate = { ...parsed };
 	for (const key of DEPRECATED_CONFIG_KEYS) delete candidate[key];
+	for (const key of OPTIONAL_CONFIG_KEYS) if (candidate[key] === null) delete candidate[key];
 	const paths = candidate.paths;
 	if (paths && typeof paths === "object" && !Array.isArray(paths)) {
 		const pathsCandidate = { ...paths };
@@ -179,6 +438,26 @@ const readHarnessConfig = async (repoRoot) => {
 	if (!result.success) throw new Error(`${HARNESS_CONFIG_FILENAME} is invalid:\n${formatConfigError(harnessConfigSchema, result.error)}`);
 	return result.data;
 };
+const missingBesideBaselineMessage = (repoRoot) => `${HARNESS_CONFIG_FILENAME} not found at ${repoRoot}, but ${BASELINE_ROOT_REL} exists: the harness was installed here, or an install did not finish. If a \`lemony install\` did not finish here, re-run it; otherwise restore ${HARNESS_CONFIG_FILENAME} from git history or a backup (\`lemony install\` would, with no TTY, replace the files you edited with the vendor copy).`;
+const REPOINT_CONFIG_LINK = `Repoint it at the config file, or replace it with a copy of the config (from git history or a backup); remove it and run \`lemony install\` only in a repo that was never installed.`;
+const configLinkMessage = (repoRoot, fault) => {
+	const prefix = `Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}:`;
+	switch (fault) {
+		case "target-missing": return `${prefix} the entry is there but its target is missing (a broken symlink?). ${REPOINT_CONFIG_LINK}`;
+		case "loop": return `${prefix} it is a symlink that loops or runs through too many links (following it never reaches a file). ${REPOINT_CONFIG_LINK}`;
+		case "target-unreadable": return `${prefix} it is a symlink whose target cannot be read (permission denied). Give your user read access to the target and search access to each directory on its path, or repoint the link at a config file you can read.`;
+	}
+};
+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 && !await hasInstallBaseline(repoRoot)) return void 0;
+	return readHarnessConfig(repoRoot);
+};
 //#endregion
 //#region src/config/compare-version.ts
 const PRERELEASE_RANK = {
@@ -235,6 +514,34 @@ const setConfigValues = (rawYaml, updates) => {
 	for (const key of DEPRECATED_CONFIG_KEYS) if (doc.has(key)) doc.delete(key);
 	for (const key of DEPRECATED_PATHS_KEYS) if (doc.hasIn(["paths", key])) doc.deleteIn(["paths", key]);
 	for (const key of DEPRECATED_IMPLEMENTATION_KEYS) if (doc.hasIn(["implementation", key])) doc.deleteIn(["implementation", key]);
+	return restoreNullBlockComments(rawYaml, doc);
+};
+const restoreNullBlockComments = (rawYaml, doc) => {
+	const restored = [];
+	visit(doc, { Pair(index, pair, path) {
+		const { key, value } = pair;
+		const parent = path.at(-1);
+		if (!isMap(parent) || parent.flow || !isScalar(key) || !key.range) return;
+		if (!isScalar(value) || value.value !== null || !value.range) return;
+		if (value.range[0] !== value.range[1] || value.anchor || value.tag) return;
+		if (value.comment === void 0 || value.comment === null) return;
+		const colon = rawYaml.indexOf(":", key.range[1]) + 1;
+		if (!/^[ \t]*$/.test(rawYaml.slice(key.range[1], colon - 1))) return;
+		const source = rawYaml.slice(colon, value.range[2]).replace(/[ \t]+$/, "");
+		restored.push({
+			value,
+			comment: value.comment,
+			source: source.replaceAll("\r\n", "\n")
+		});
+		value.comment = `${NULL_BLOCK_SENTINEL}${restored.length - 1}`;
+		const commentEnd = colon + source.trimEnd().length;
+		const gap = /^\s*/.exec(rawYaml.slice(commentEnd))?.[0] ?? "";
+		const next = parent.items[index + 1];
+		if (isPair(next) && isScalar(next.key) && next.key.range?.[0] === commentEnd + gap.length && !/\n[ \t\r]*\n/.test(gap)) next.key.spaceBefore = false;
+	} });
+	const text = restored.reduce((current, { source }, index) => current.replace(`: #${NULL_BLOCK_SENTINEL}${index}\n`, `:${source.endsWith("\n") ? source : `${source}\n`}`), doc.toString());
+	if (!text.includes("lemony-null-block-comment-")) return text;
+	for (const { value, comment } of restored) value.comment = comment;
 	return doc.toString();
 };
 const writeConfigValues = async (repoRoot, updates) => {
@@ -266,20 +573,6 @@ const pointerFrontmatterSchema = z.object({
 });
 Object.keys(pointerFrontmatterSchema.shape);
 //#endregion
-//#region src/paths/claude-paths.constant.ts
-const CLAUDE_DIR = ".claude";
-const STATE_DIR = join(CLAUDE_DIR, "state");
-const TASKS_DIR = join(STATE_DIR, "tasks");
-const SKILLS_DIR = join(CLAUDE_DIR, "skills");
-const AGENTS_DIR = join(CLAUDE_DIR, "agents");
-const HOOKS_DIR = join(CLAUDE_DIR, "hooks");
-const COMMANDS_DIR = join(CLAUDE_DIR, "commands");
-const SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
-const HARNESS_DIR = join(CLAUDE_DIR, ".harness");
-const BASELINE_ROOT_REL = join(HARNESS_DIR, "baseline");
-const SNAPSHOTS_ROOT_REL = join(HARNESS_DIR, "snapshots");
-const EVENTS_RELPATH = join(STATE_DIR, "events.jsonl");
-//#endregion
 //#region src/events/envelope.ts
 const buildEnvelope = (input) => {
 	const ts = (input.now ?? /* @__PURE__ */ new Date()).toISOString();
@@ -392,7 +685,8 @@ const taskDoneSchema = envelopeBase.extend({
 	cycle_time_h: z.number().nonnegative().finite(),
 	review_rejections: z.number().int().nonnegative(),
 	mode: z.enum(IMPLEMENTATION_MODES).optional(),
-	steps: z.number().int().positive().optional()
+	steps: z.number().int().positive().optional(),
+	checkpoints: z.number().int().positive().optional()
 }).strict();
 const reviewRejectedSchema = envelopeBase.extend({
 	type: z.literal("review_rejected"),
@@ -439,6 +733,16 @@ const eventSchema = z.discriminatedUnion("type", [
 	stepCompletedSchema
 ]);
 //#endregion
+//#region src/events/task-done-count-issues.ts
+const taskDoneCountIssues = (event) => {
+	const { mode, steps, checkpoints } = event;
+	const issues = [];
+	if ((steps !== void 0 || checkpoints !== void 0) && mode !== "step_by_step") issues.push(`steps/checkpoints: only sent when mode is step_by_step (got mode ${mode ?? "absent"})`);
+	if (checkpoints !== void 0 && steps === void 0) issues.push("checkpoints: sent without steps — pass both");
+	if (steps !== void 0 && checkpoints !== void 0 && checkpoints < steps) issues.push(`checkpoints: ${checkpoints} is fewer than steps ${steps} — every step resolves at least one checkpoint`);
+	return issues;
+};
+//#endregion
 //#region src/events/emit.ts
 const NUMERIC_FIELDS = /* @__PURE__ */ new Set([
 	"session_active_h",
@@ -450,6 +754,7 @@ const NUMERIC_FIELDS = /* @__PURE__ */ new Set([
 	"discovered_h",
 	"step",
 	"steps",
+	"checkpoints",
 	"review_iterations"
 ]);
 const BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["auto_close"]);
@@ -480,7 +785,7 @@ const parseFlags = (args) => {
 	}
 	return result;
 };
-const runEmit = async (options) => {
+const prepareEmit = async (options) => {
 	const { repoRoot, harnessVersion, args } = options;
 	const [rawType, ...rest] = args;
 	if (!rawType) throw new Error(`Usage: lemony emit <type> [--field=value …]. Types: ${EVENT_TYPES.join(", ")}.`);
@@ -507,11 +812,217 @@ const runEmit = async (options) => {
 		const issues = parsed.error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
 		throw new Error(`Event validation failed for type "${rawType}":\n${issues}`);
 	}
-	const eventsPath = join(repoRoot, EVENTS_RELPATH);
-	await appendEvent(eventsPath, parsed.data);
+	const countIssues = parsed.data.type === "task_done" ? taskDoneCountIssues(parsed.data) : [];
+	if (countIssues.length > 0) throw new Error(`Event validation failed for type "${rawType}":\n${countIssues.map((issue) => `  - ${issue}`).join("\n")}`);
 	return {
 		event: parsed.data,
-		eventsPath
+		eventsPath: join(repoRoot, EVENTS_RELPATH)
+	};
+};
+const runEmit = async (options) => {
+	const prepared = await prepareEmit(options);
+	await appendEvent(prepared.eventsPath, prepared.event);
+	return prepared;
+};
+//#endregion
+//#region src/checkpoint/checkpoint.constant.ts
+const CHECKPOINT_TRAILER = "Lemony-Checkpoint";
+const CHECKPOINT_LAUNCHER = ".claude/hooks/lib/lemony.sh";
+const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const POSITIVE_INTEGER_PATTERN = /^[1-9]\d*$/;
+//#endregion
+//#region src/checkpoint/checkpoint.model.ts
+const CHECKPOINT_AUTO_COMMIT = ["on", "off"];
+//#endregion
+//#region src/checkpoint/checkpoint.ts
+const USAGE = "lemony checkpoint <ok|changes|ok_downgrade> --task-id=<id> --auto-commit=<on|off> [--step=<N> --review-iterations=<K>]";
+const isAnswer = (value) => CHECKPOINT_RESULTS.includes(value);
+const isAutoCommit = (value) => CHECKPOINT_AUTO_COMMIT.includes(value);
+const parseCall = (inputs) => {
+	const fail = (message) => {
+		throw new Error(`checkpoint: ${message}\nUsage: ${USAGE}`);
+	};
+	const { answer, taskId, autoCommit, step, reviewIterations } = inputs;
+	if (answer === void 0 || !isAnswer(answer)) return fail(`the answer must be one of ${CHECKPOINT_RESULTS.join(", ")}${answer === void 0 ? "." : `, got "${answer}".`}`);
+	if (taskId === void 0) return fail("--task-id is required.");
+	if (!TASK_ID_PATTERN.test(taskId)) return fail(`--task-id "${taskId}" is not a task id.`);
+	if (autoCommit === void 0 || !isAutoCommit(autoCommit)) return fail(`--auto-commit must be on or off${autoCommit === void 0 ? " (the value progress.md records)." : `, got "${autoCommit}".`}`);
+	if (step === void 0) {
+		if (answer === "ok_downgrade") return fail("ok_downgrade needs --step: the downgrade is offered only at a step-by-step checkpoint.");
+		if (autoCommit === "on") return fail("without --step this is the all-at-once gate, which only auto-commit OFF has.");
+		const stepOnly = [
+			["review-iterations", reviewIterations],
+			["attributed-kind", inputs.attributedKind],
+			["attributed-name", inputs.attributedName]
+		].find(([, value]) => value !== void 0);
+		if (stepOnly) return fail(`--${stepOnly[0]} goes with --step: the all-at-once gate emits no step_completed.`);
+		return {
+			answer,
+			taskId,
+			autoCommit,
+			step: void 0
+		};
+	}
+	if (!POSITIVE_INTEGER_PATTERN.test(step)) return fail(`--step must be a positive integer, got "${step}".`);
+	if (reviewIterations === void 0) return fail("--review-iterations is required with --step.");
+	if (!POSITIVE_INTEGER_PATTERN.test(reviewIterations)) return fail(`--review-iterations must be a positive integer, got "${reviewIterations}".`);
+	return {
+		answer,
+		taskId,
+		autoCommit,
+		step: {
+			number: step,
+			reviewIterations
+		}
+	};
+};
+const buildCheckpointCall = (call) => [
+	CHECKPOINT_LAUNCHER,
+	"checkpoint",
+	call.answer,
+	`--task-id=${call.taskId}`,
+	`--auto-commit=${call.autoCommit}`,
+	...call.step ? [`--step=${call.step.number}`, `--review-iterations=${call.step.reviewIterations}`] : []
+].join(" ");
+const commitSubjects = (call) => call.step ? {
+	code: `step(${call.taskId}): step ${call.step.number}`,
+	state: `step(${call.taskId}): step ${call.step.number} checkpoint OK`
+} : {
+	code: `task(${call.taskId}): implementation`,
+	state: `task(${call.taskId}): implementation checkpoint OK`
+};
+const firstLine = (text) => text.trim().split("\n")[0] ?? "";
+const bindGit = (run, top) => (...args) => run("git", [
+	"--no-literal-pathspecs",
+	"-C",
+	top,
+	...args
+]);
+const resolveTopLevel = async (run, repoRoot) => {
+	const result = await run("git", [
+		"-C",
+		repoRoot,
+		"rev-parse",
+		"--show-toplevel"
+	]);
+	if (result.code !== 0) throw new Error(`checkpoint: not inside a git work tree (${firstLine(result.stderr)}).`);
+	return result.stdout.trim();
+};
+const IN_PROGRESS = [
+	"MERGE_HEAD",
+	"CHERRY_PICK_HEAD",
+	"REVERT_HEAD",
+	"rebase-merge",
+	"rebase-apply"
+];
+const checkRepoState = async (git, top, call) => {
+	const taskState = join(TASKS_DIR, call.taskId);
+	if (!await pathExists(join(top, taskState))) throw new Error(`checkpoint: no task state at ${taskState} — check --task-id.`);
+	if ((await git("symbolic-ref", "--quiet", "HEAD")).code !== 0) throw new Error("checkpoint: HEAD is detached — check out the task branch first.");
+	for (const entry of IN_PROGRESS) {
+		const path = (await git("rev-parse", "--git-path", entry)).stdout.trim();
+		if (path && await pathExists(resolve(top, path))) throw new Error(`checkpoint: ${entry} is present — finish or abort that merge, rebase, cherry-pick or revert first.`);
+	}
+	if ((await git("ls-files", "--unmerged")).stdout.trim() !== "") throw new Error("checkpoint: the index has unmerged paths — resolve them first.");
+	if (call.answer === "changes") return;
+	const changed = await git("status", "--porcelain", "--untracked-files=all", "--", join(taskState, "progress.md"));
+	if (changed.code !== 0) throw new Error(`checkpoint: git status failed (${firstLine(changed.stderr)}).`);
+	if (changed.stdout.trim() !== "") return;
+	const ownCall = (await git("log", "-1", "--format=%B")).stdout.split("\n").some((line) => line.trim() === `${CHECKPOINT_TRAILER}: ${buildCheckpointCall(call)}`);
+	const touchesState = (await git("diff-tree", "--quiet", "--root", "--no-commit-id", "-r", "HEAD", "--", taskState)).code === 1;
+	if (ownCall && touchesState) return;
+	throw new Error(`checkpoint: nothing changed in ${join(taskState, "progress.md")} — write the resolved progress.md line first (the state commit carries it), then run this call. If this answer's commits were already made without it, emit step_completed by hand instead.`);
+};
+const guardedCommit = async (git, subject, trailer, pathspec) => {
+	const staged = await git("diff", "--cached", "--quiet", "--", ...pathspec);
+	if (staged.code === 0) return "empty";
+	if (staged.code !== 1) return {
+		failedStep: `commit "${subject}"`,
+		reason: firstLine(staged.stderr) || `git diff exited ${staged.code}`
+	};
+	const commit = await git("commit", "-m", subject, "-m", `${CHECKPOINT_TRAILER}: ${trailer}`, "--", ...pathspec);
+	if (commit.code !== 0) return {
+		failedStep: `commit "${subject}"`,
+		reason: commit.stderr.trim() || commit.stdout.trim() || `git commit exited ${commit.code}`
+	};
+	return { oid: (await git("rev-parse", "--short", "HEAD")).stdout.trim() };
+};
+const isFailure = (value) => typeof value === "object" && value !== null && "failedStep" in value;
+const runCheckpoint = async (inputs) => {
+	const call = parseCall(inputs);
+	const top = await resolveTopLevel(inputs.runCommand, inputs.repoRoot);
+	const git = bindGit(inputs.runCommand, top);
+	await checkRepoState(git, top, call);
+	const prepared = call.step ? await prepareEmit({
+		repoRoot: top,
+		harnessVersion: inputs.harnessVersion,
+		args: [
+			"step_completed",
+			`--task-id=${call.taskId}`,
+			`--step=${call.step.number}`,
+			`--review-iterations=${call.step.reviewIterations}`,
+			`--checkpoint-result=${call.answer}`,
+			...inputs.attributedKind === void 0 ? [] : [`--attributed-kind=${inputs.attributedKind}`],
+			...inputs.attributedName === void 0 ? [] : [`--attributed-name=${inputs.attributedName}`]
+		]
+	}) : void 0;
+	const done = [];
+	const warnings = [];
+	const stop = (failure) => ({
+		ok: false,
+		done,
+		warnings,
+		...failure
+	});
+	if (call.autoCommit === "off") {
+		const add = await git("add", "-A");
+		if (add.code !== 0) return stop({
+			failedStep: "git add -A",
+			reason: firstLine(add.stderr) || `git add exited ${add.code}`
+		});
+		done.push(call.answer === "changes" ? "staged the worktree (the human delta)" : "staged the worktree");
+	}
+	if (call.answer !== "changes") {
+		const trailer = buildCheckpointCall(call);
+		const subjects = commitSubjects(call);
+		const taskState = join(TASKS_DIR, call.taskId);
+		if (call.autoCommit === "off") {
+			const code = await guardedCommit(git, subjects.code, trailer, [".", `:(exclude)${STATE_DIR}`]);
+			if (isFailure(code)) return stop(code);
+			done.push(code === "empty" ? "no code change to commit" : `committed ${code.oid} ${subjects.code}`);
+		} else {
+			const add = await git("add", "--", taskState);
+			if (add.code !== 0) return stop({
+				failedStep: `git add ${taskState}`,
+				reason: firstLine(add.stderr) || `git add exited ${add.code}`
+			});
+		}
+		const state = await guardedCommit(git, subjects.state, trailer, [taskState]);
+		if (isFailure(state)) return stop(state);
+		done.push(state === "empty" ? `"${subjects.state}" already on the branch` : `committed ${state.oid} ${subjects.state}`);
+		if (call.autoCommit === "off") {
+			const paths = (await git("diff", "--cached", "--name-only", "--", STATE_DIR)).stdout.trim();
+			if (paths !== "") warnings.push(`left staged, not committed (task state outside ${taskState}): ${paths.split("\n").join(", ")}.`);
+		}
+		const push = await git("push");
+		if (push.code === 0) done.push("pushed");
+		else warnings.push(`push failed (${firstLine(push.stderr) || `exit ${push.code}`}); the next push carries it.`);
+	}
+	if (prepared) {
+		try {
+			await appendEvent(prepared.eventsPath, prepared.event);
+		} catch (error) {
+			return stop({
+				failedStep: "emit step_completed",
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+		done.push(`emitted step_completed → ${EVENTS_RELPATH}`);
+	}
+	return {
+		ok: true,
+		done,
+		warnings
 	};
 };
 //#endregion
@@ -995,72 +1506,17 @@ const failureReason$1 = (result) => {
 	return `\`gh\` failed (exit ${result.code})${suffix}${detail ? `: ${detail}` : ""}`;
 };
 //#endregion
-//#region src/fs/exists.ts
-const pathExists = async (path) => {
+//#region src/design-tokens/read-token-file.ts
+const readOptionalTokenFile = async (repoRoot, tokenFile) => {
+	const tokenPath = join(repoRoot, tokenFile);
 	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);
-		}
+		if (!await entryExists(tokenPath)) return void 0;
+		return await readRegularFile(tokenPath);
+	} catch (error) {
+		if (error.code === "ENOENT") throw new Error(`Cannot read ${tokenFile} at ${repoRoot}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
+		throw new Error(`Cannot read ${tokenFile} at ${repoRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
-	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 = [
 	".css",
 	".scss",
@@ -1109,6 +1565,47 @@ 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 nestedTooDeeply = (tokenFile) => `${tokenFile} nests deeper than 64 levels, the most Lemony reads.`;
+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, tokenFile) => nonFiniteNumbers(value, []).map(({ path, number }) => `${tokenFile} 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,18 +1614,35 @@ const aliasTarget = (value) => {
 };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 //#endregion
+//#region src/design-tokens/resolve-token-file.ts
+const resolveTokenFile = (declared) => declared ?? "docs/design-tokens.json";
+//#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 {
+	const tokenFile = resolveTokenFile(inputs.tokenFile);
+	let raw;
+	try {
+		raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
+	} 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);
+	const fileCheck = validateTokenFile(raw, tokenFile);
 	if (!fileCheck.ok) return {
 		ok: false,
 		tokensFound: true,
@@ -1137,8 +1651,21 @@ 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);
+	const sourceViolations = await scanSource(inputs.repoRoot, scanRoot, extensions, tokenFile);
 	return {
 		ok: sourceViolations.violations.length === 0,
 		tokensFound: true,
@@ -1147,7 +1674,15 @@ const runValidate = async (inputs) => {
 		violations: sourceViolations.violations
 	};
 };
-const validateTokenFile = (raw) => {
+const summarizeTokenFileViolations = (raw, tokenFile) => summarizeMessages(tokenFileViolationMessages(raw, tokenFile));
+const tokenFileViolations = (raw, tokenFile) => validateTokenFile(raw, tokenFile).violations;
+const tokenFileViolationMessages = (raw, tokenFile) => tokenFileViolations(raw, tokenFile).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, tokenFile) => {
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
@@ -1157,7 +1692,7 @@ const validateTokenFile = (raw) => {
 			tokenCount: 0,
 			violations: [{
 				kind: "invalid-json",
-				message: `${DESIGN_TOKENS_FILE} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+				message: `${tokenFile} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
 			}]
 		};
 	}
@@ -1166,10 +1701,22 @@ const validateTokenFile = (raw) => {
 		tokenCount: 0,
 		violations: [{
 			kind: "malformed-token-file",
-			message: `${DESIGN_TOKENS_FILE} must be a JSON object with primitive/semantic/component tiers.`
+			message: `${tokenFile} must be a JSON object with primitive/semantic/component tiers.`
+		}]
+	};
+	if (exceedsNestingLimit(parsed)) return {
+		ok: false,
+		tokenCount: 0,
+		violations: [{
+			kind: "malformed-token-file",
+			message: nestedTooDeeply(tokenFile)
 		}]
 	};
 	const violations = [];
+	for (const message of nonFiniteNumberFaults(parsed, tokenFile)) 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({
@@ -1197,6 +1744,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;
@@ -1211,7 +1762,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({
@@ -1223,41 +1775,162 @@ 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 && token.tier === "primitive") {
+			violations.push({
+				kind: "primitive-not-literal",
+				message: `primitive token "${path}" must hold a literal value in mode "${mode}", not the alias "{${alias}}".`
+			});
+			continue;
+		}
+		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 values = [[void 0, token.value], ...Object.entries(token.modes)];
+		for (const [mode, value] of values) {
+			const where = mode === void 0 ? "" : ` in mode "${mode}"`;
+			for (const { at, alias } of compositeAliases(value)) if (token.tier === "primitive") violations.push({
+				kind: "primitive-not-literal",
+				message: `primitive token "${path}" must hold a literal value${where}, not the alias "{${alias}}" at "${at}".`
+			});
+			else if (!tokens.has(alias)) violations.push({
+				kind: "unresolved-alias",
+				message: `token "${path}" references "{${alias}}" at "${at}" in its value${where}, which does not exist.`
+			});
+		}
+	}
+	const loopsInBase = tokensReachingACycle(tokens, [...tokens.keys()]);
 	for (const [path, token] of tokens) {
 		const alias = aliasTarget(token.value);
-		if (alias === void 0) continue;
-		if (token.tier === "primitive") {
+		if (alias !== void 0 && token.tier === "primitive") {
 			violations.push({
 				kind: "primitive-not-literal",
 				message: `primitive token "${path}" must hold a literal value, not the alias "{${alias}}".`
 			});
 			continue;
 		}
-		if (!tokens.has(alias)) {
+		if (alias !== void 0 && !tokens.has(alias)) {
 			violations.push({
 				kind: "unresolved-alias",
 				message: `token "${path}" references "{${alias}}", which does not exist.`
 			});
 			continue;
 		}
-		if (aliasChainCycles(path, tokens)) violations.push({
+		if (token.tier === "primitive") continue;
+		if (loopsInBase.has(path)) violations.push({
 			kind: "cyclic-alias",
 			message: `token "${path}" has an alias chain that never resolves to a literal value (alias cycle).`
 		});
 	}
+	const owners = /* @__PURE__ */ new Map();
+	for (const [path, token] of tokens) for (const mode of Object.keys(token.modes)) {
+		const owning = owners.get(mode);
+		if (owning === void 0) owners.set(mode, [path]);
+		else owning.push(path);
+	}
+	const baseReferrers = /* @__PURE__ */ new Map();
+	for (const [path, token] of tokens) {
+		if (loopsInBase.has(path)) continue;
+		for (const target of aliasReferences(token.value)) {
+			const referring = baseReferrers.get(target);
+			if (referring === void 0) baseReferrers.set(target, [path]);
+			else referring.push(path);
+		}
+	}
+	const loopsInMode = /* @__PURE__ */ new Map();
+	const loopsWithoutOverride = /* @__PURE__ */ new Map();
+	for (const [mode, owning] of owners) {
+		const loops = tokensReachingACycle(tokens, owning, mode);
+		loopsInMode.set(mode, loops);
+		const feeding = tokensFeedingInto(tokens, baseReferrers, loops, mode);
+		for (const path of [...loops, ...feeding]) {
+			const token = tokens.get(path);
+			if (token === void 0 || Object.hasOwn(token.modes, mode)) continue;
+			if (loopsInBase.has(path)) continue;
+			const looping = loopsWithoutOverride.get(path);
+			if (looping === void 0) loopsWithoutOverride.set(path, [mode]);
+			else looping.push(mode);
+		}
+	}
+	for (const [path, token] of tokens) {
+		if (token.tier === "primitive") continue;
+		const looping = [...Object.keys(token.modes).filter((mode) => loopsInMode.get(mode)?.has(path)), ...loopsWithoutOverride.get(path) ?? []];
+		for (const mode of looping) 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 seen = /* @__PURE__ */ new Set();
-	let current = start;
-	while (current !== void 0) {
-		if (seen.has(current)) return true;
-		seen.add(current);
-		const token = tokens.get(current);
-		if (token === void 0) return false;
-		current = aliasTarget(token.value);
+const tokensFeedingInto = (tokens, baseReferrers, loops, mode) => {
+	const found = /* @__PURE__ */ new Set();
+	const queue = [...loops];
+	for (let path = queue.pop(); path !== void 0; path = queue.pop()) for (const referrer of baseReferrers.get(path) ?? []) {
+		if (Object.hasOwn(tokens.get(referrer)?.modes ?? {}, mode)) continue;
+		if (loops.has(referrer) || found.has(referrer)) continue;
+		found.add(referrer);
+		queue.push(referrer);
 	}
-	return false;
+	return found;
+};
+const compositeAliases = (value, at = []) => {
+	if (typeof value !== "object" || value === null) {
+		const alias = at.length === 0 ? void 0 : aliasTarget(value);
+		return alias === void 0 ? [] : [{
+			at: at.join("."),
+			alias
+		}];
+	}
+	return Object.entries(value).flatMap(([key, child]) => compositeAliases(child, [...at, key]));
+};
+const aliasReferences = (value) => {
+	const alias = aliasTarget(value);
+	return alias === void 0 ? compositeAliases(value).map((leaf) => leaf.alias) : [alias];
+};
+const tokensReachingACycle = (tokens, starts, mode) => {
+	const references = (path) => {
+		const token = tokens.get(path);
+		if (token === void 0) return [];
+		return aliasReferences(mode !== void 0 && Object.hasOwn(token.modes, mode) ? token.modes[mode] : token.value);
+	};
+	const onPath = /* @__PURE__ */ new Set();
+	const settled = /* @__PURE__ */ new Map();
+	for (const start of starts) {
+		if (settled.has(start)) continue;
+		const stack = [{
+			path: start,
+			next: references(start),
+			loops: false
+		}];
+		onPath.add(start);
+		for (let frame = stack.at(-1); frame !== void 0; frame = stack.at(-1)) {
+			const target = frame.next.pop();
+			if (target === void 0) {
+				stack.pop();
+				onPath.delete(frame.path);
+				settled.set(frame.path, frame.loops);
+				const parent = stack.at(-1);
+				if (parent !== void 0 && frame.loops) parent.loops = true;
+				continue;
+			}
+			if (onPath.has(target)) frame.loops = true;
+			else if (settled.has(target)) {
+				if (settled.get(target)) frame.loops = true;
+			} else {
+				stack.push({
+					path: target,
+					next: references(target),
+					loops: false
+				});
+				onPath.add(target);
+			}
+		}
+	}
+	return new Set([...settled].filter(([, loops]) => loops).map(([path]) => path));
 };
 const mergeExtensions = (extra) => {
 	const set = new Set(SCANNED_EXTENSIONS);
@@ -1268,33 +1941,64 @@ const mergeExtensions = (extra) => {
 	}
 	return set;
 };
-const scanSource = async (repoRoot, scanRoot, extensions) => {
+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, tokenFile) => {
 	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("/");
-		violations.push(...scanFile(relPath, extname(file).toLowerCase(), content));
+		violations.push(...scanFile(relPath, extname(file).toLowerCase(), content, tokenFile));
 	}
 	return {
 		filesScanned,
 		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();
@@ -1303,7 +2007,7 @@ const HEX_COLOR = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{
 const FUNCTIONAL_COLOR = /\b(?:rgb|rgba|hsl|hsla)\s*\(/i;
 const PX_DIMENSION = /\b(\d*\.?\d+)px\b/g;
 const EXEMPT_DIMENSIONS = /* @__PURE__ */ new Set(["0", "1"]);
-const scanFile = (relPath, ext, content) => {
+const scanFile = (relPath, ext, content, tokenFile) => {
 	const isStylesheet = STYLESHEET_EXTENSIONS.includes(ext);
 	const violations = [];
 	content.split("\n").forEach((line, index) => {
@@ -1311,13 +2015,13 @@ const scanFile = (relPath, ext, content) => {
 		const lineNo = index + 1;
 		if (HEX_COLOR.test(line) || FUNCTIONAL_COLOR.test(line)) violations.push({
 			kind: "hardcoded-color",
-			message: `raw color literal — reference a token from ${DESIGN_TOKENS_FILE} instead.`,
+			message: `raw color literal — reference a token from ${tokenFile} instead.`,
 			file: relPath,
 			line: lineNo
 		});
 		if (isStylesheet && hasRawDimension(line)) violations.push({
 			kind: "hardcoded-dimension",
-			message: `raw dimension literal — reference a token from ${DESIGN_TOKENS_FILE} instead.`,
+			message: `raw dimension literal — reference a token from ${tokenFile} instead.`,
 			file: relPath,
 			line: lineNo
 		});
@@ -1465,18 +2169,11 @@ const contrastRatio = (foreground, background) => {
 	const l2 = relativeLuminance(bg);
 	const light = Math.max(l1, l2);
 	const dark = Math.min(l1, l2);
-	return Math.round((light + .05) / (dark + .05) * 100) / 100;
+	return (light + .05) / (dark + .05);
 };
-//#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
+const truncateRatio = (ratio) => {
+	const hundredths = Math.floor(ratio * 100);
+	return hundredths / 100 > ratio ? (hundredths - 1) / 100 : hundredths / 100;
 };
 //#endregion
 //#region src/design-tokens/contrast.model.ts
@@ -1488,38 +2185,58 @@ 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");
+	const tokenFile = resolveTokenFile(inputs.tokenFile);
+	let raw;
+	let unreadable;
+	try {
+		raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
+	} 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.`]
-		};
+			problems: [`${tokenFile} 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.`]
-	};
+		problems: [`${tokenFile} must be a JSON object — run \`design-tokens validate\` first.`]
+	});
+	if (exceedsNestingLimit(parsed)) return withVerify({
+		...emptyResult$1(true),
+		ok: false,
+		problems: [`${nestedTooDeeply(tokenFile)} Run \`design-tokens validate\` first.`]
+	});
 	const tokens = collectTokens(parsed);
 	const problems = [];
 	const modes = declaredModes(tokens);
 	const specs = discoverPairs(tokens, modes, problems);
 	const pairs = measurePairs(specs, modes, tokens);
-	const verify = inputs.verify ? await runVerifier(inputs.verify) : void 0;
-	return {
-		ok: problems.length === 0 && pairs.every((pair) => pair.passes) && (verify === void 0 || verify.code === 0),
+	return withVerify({
+		ok: problems.length === 0 && pairs.every((pair) => pair.passes),
 		tokensFound: true,
 		pairsChecked: pairs.length,
 		pairs,
-		problems,
-		...verify === void 0 ? {} : { verify }
-	};
+		problems
+	});
 };
 const emptyResult$1 = (tokensFound) => ({
 	ok: true,
@@ -1564,12 +2281,12 @@ const declaredModes = (tokens) => {
 };
 const pairKey = (spec) => `${spec.foreground}|${spec.background}`;
 const discoverPairs = (tokens, modes, problems) => {
-	const convention = new Map(conventionPairs(tokens).map((spec) => [pairKey(spec), spec]));
+	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;
@@ -1580,6 +2297,21 @@ 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,
@@ -1773,7 +2505,7 @@ const makeRow = (spec, mode, foreground, background) => {
 		...spec.over === void 0 ? {} : { over: spec.over },
 		mode,
 		level: spec.level,
-		ratio,
+		ratio: truncateRatio(ratio),
 		floor,
 		passes: ratio >= floor,
 		source: spec.source
@@ -1788,12 +2520,26 @@ const resolveColor = (path, mode, tokens, seen = /* @__PURE__ */ new Set()) => {
 	let value = token.value;
 	if (mode !== "base") {
 		const modes = readExtension(token.node, MODES_EXTENSION);
-		if (isRecord(modes) && modes[mode] !== void 0) value = modes[mode];
+		if (isRecord(modes) && Object.hasOwn(modes, mode)) value = modes[mode];
 	}
 	const alias = aliasTarget(value);
 	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 {
@@ -1804,32 +2550,105 @@ const runVerifier = async (hook) => {
 //#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_FAULT_CLAUSE = "Fix the variables named above in the design tool, or leave them out with `--only`";
+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$1(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$1 = (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,
@@ -1846,37 +2665,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$1(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 || Object.values(variable.modes ?? {}).some((modeValue) => aliasTarget(modeValue) !== void 0) ? "semantic" : "primitive"}.${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,
@@ -1891,41 +2737,83 @@ 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 ownMode = (modes, mode) => Object.hasOwn(modes, mode) ? modes[mode] : void 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) => ownMode(before, mode) !== ownMode(after, mode)).map((mode) => {
+		const was = ownMode(before, mode);
+		const is = ownMode(after, mode);
+		return {
+			mode,
+			...was !== void 0 ? { before: was } : {},
+			...is !== void 0 ? { after: is } : {}
+		};
+	});
+	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;
@@ -1948,17 +2836,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)
 	});
@@ -1967,53 +2882,87 @@ 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 readJsonObject = (raw) => {
+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, tokenFile) => {
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch (error) {
-		throw new Error(`${DESIGN_TOKENS_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)}) — run \`design-tokens validate\` first.`, { cause: error });
+		throw new Error(`${tokenFile} 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 (!isRecord(parsed)) throw new Error(`${tokenFile} must be a JSON object — run \`design-tokens validate\` first.`);
+	if (exceedsNestingLimit(parsed)) throw new Error(`${nestedTooDeeply(tokenFile)} Run \`design-tokens validate\` first.`);
 	return parsed;
 };
 const writeJsonFile = (value) => `${JSON.stringify(value, null, 2)}\n`;
@@ -2025,17 +2974,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,
@@ -2046,39 +2994,92 @@ 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);
+	const tokenFile = resolveTokenFile(inputs.tokenFile);
+	let tokensFound = false;
+	let raw;
 	let parsed;
 	try {
-		parsed = tokensFound ? readJsonObject(await readFile(tokenPath, "utf8")) : {};
+		raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
+		tokensFound = raw !== void 0;
+		parsed = raw === void 0 ? {} : readJsonObject(raw, tokenFile);
 	} 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, tokenFile));
+		return {
+			...empty,
+			tokensFound,
+			changes,
+			warnings: faults === void 0 ? [] : [`${tokenFile} 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, ${tokenFile} would fail validation: ${nestedTooDeeply(tokenFile)} ${IMPORT_TOO_DEEP_HINT}`]
+	};
+	const text = writeJsonFile(merged);
+	const mergedViolations = tokenFileViolations(text, tokenFile);
+	const mergedFaults = [...nonFiniteNumberFaults(merged, tokenFile), ...mergedViolations.map((violation) => violation.message)];
+	if (mergedFaults.length > 0) {
+		const onDisk = new Set(raw === void 0 ? [] : tokenFileViolationMessages(raw, tokenFile));
+		const introduced = mergedFaults.filter((fault) => !onDisk.has(fault));
+		const landings = new Set(changes.map((change) => change.path));
+		const dangling = danglingAliasTargets(merged, written.filter((path) => !path.startsWith("primitive.")));
+		const leftBehind = dangling.filter((target) => landings.has(target));
+		const notCarried = dangling.filter((target) => !landings.has(target));
+		const danglingFaults = new Set(mergedViolations.filter((violation) => violation.kind === "unresolved-alias").map((violation) => violation.message));
+		const hint = importRefusalHint(leftBehind, notCarried, introduced.some((fault) => !danglingFaults.has(fault)), tokenFile);
+		return {
+			...empty,
+			tokensFound,
+			changes,
+			refused: true,
+			problems: [introduced.length > 0 ? `not applied — with this import, ${tokenFile} would fail validation: ${summarizeMessages(introduced)} ${hint}` : `not applied — ${tokenFile} already fails validation and this import does not repair it: ${summarizeMessages(mergedFaults)} ${VALIDATE_HINT}`]
+		};
+	}
+	if (written.length > 0) {
+		const tokenPath = join(inputs.repoRoot, tokenFile);
+		await mkdir(dirname(tokenPath), { recursive: true });
+		await writeFile(tokenPath, text);
+	}
 	return {
 		tokensFound,
 		changes,
 		applied: true,
+		refused: false,
 		written,
 		skipped,
-		problems: []
+		unsynced,
+		problems: [],
+		warnings: []
 	};
 };
+const importRefusalHint = (leftBehind, notCarried, otherFault, tokenFile) => {
+	if (notCarried.length === 0 && !otherFault) return IMPORT_INVALID_HINT;
+	return `${[
+		...leftBehind.length > 0 ? [`Add ${leftBehind.join(", ")} to the \`--only\` slice`] : [],
+		...notCarried.length > 0 ? [`The neutral file carries no variable that lands at ${notCarried.join(", ")}, so no \`--only\` slice can supply ${notCarried.length === 1 ? "it" : "them"}: add the token in the design tool (or in ${tokenFile}) first, or leave out what references it`] : [],
+		...otherFault ? [IMPORT_FAULT_CLAUSE] : []
+	].join(". ")}; nothing was written.`;
+};
 const asMessage$1 = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
 //#region src/design-tokens/drift.ts
@@ -2130,15 +3131,23 @@ 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;
+	const tokenFile = resolveTokenFile(inputs.tokenFile);
 	let parsed;
 	try {
-		parsed = readJsonObject(await readFile(tokenPath, "utf8"));
+		const raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
+		if (raw === void 0) return empty;
+		parsed = readJsonObject(raw, tokenFile);
+		const invalid = summarizeTokenFileViolations(raw, tokenFile);
+		if (invalid !== void 0) return {
+			...empty,
+			tokensFound: true,
+			problems: [`${tokenFile} fails validation: ${invalid} ${VALIDATE_HINT}`]
+		};
 	} catch (error) {
 		return {
 			...empty,
@@ -2150,39 +3159,50 @@ const runExport = async (inputs) => {
 	if (!binding) return {
 		...empty,
 		tokensFound: true,
-		problems: [`no design tool is declared — add a "${DESIGN_TOOL_EXTENSION}" provider to ${DESIGN_TOKENS_FILE} before exporting.`]
+		problems: [`no design tool is declared — add a "${DESIGN_TOOL_EXTENSION}" provider to ${tokenFile} before exporting.`]
 	};
 	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, tokenFile))) return {
 			...empty,
 			tokensFound: true,
 			hash,
-			problems: [`tool-state file not found: ${inputs.toolStatePath}`]
+			problems: [`Cannot write the projection to ${inputs.outPath}: it is ${tokenFile} 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, tokenFile);
+		await writeFile(tokenPath, stamped);
 		return {
 			tokensFound: true,
 			plan,
+			unprojected,
 			hash,
 			recorded: true,
 			problems: []
@@ -2191,13 +3211,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;
@@ -2205,8 +3226,57 @@ 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/parse-markdown-blocks.ts
+const MAX_NESTING = 200;
+const MARKDOWN = new MarkdownIt("commonmark", { maxNesting: MAX_NESTING });
+const OPEN_SUFFIX = /_open$/;
+const parseMarkdownBlocks = (lines) => {
+	const root = {
+		type: "root",
+		start: 0,
+		end: lines.length,
+		markup: "",
+		text: "",
+		content: "",
+		children: []
+	};
+	const stack = [root];
+	const tokens = MARKDOWN.parse(lines.join("\n"), {});
+	const cut = tokens.find((token) => token.nesting === 1 && token.level >= 199);
+	if (cut) throw new Error(`line ${(cut.map?.[0] ?? 0) + 1}: the markdown nests deeper than ${MAX_NESTING} parser levels (a nested list costs two, a quote one), so what it holds was not read.`);
+	for (const token of tokens) {
+		const parent = stack[stack.length - 1] ?? root;
+		if (token.nesting === -1) {
+			stack.pop();
+			continue;
+		}
+		if (token.type === "inline") {
+			parent.text = plainText(token.children ?? []);
+			continue;
+		}
+		const [start, end] = token.map ?? [parent.start, parent.start];
+		const block = {
+			type: token.type.replace(OPEN_SUFFIX, ""),
+			start,
+			end,
+			markup: token.markup,
+			text: "",
+			content: token.content,
+			children: []
+		};
+		parent.children.push(block);
+		if (token.nesting === 1) stack.push(block);
+	}
+	return root.children;
+};
+const plainText = (children) => children.filter((child) => child.type === "text" || child.type === "code_inline").map((child) => child.content).join("");
+//#endregion
 //#region src/review-ledger/review-ledger.constant.ts
 const REVIEW_LEDGER_DIRNAME = "review-ledger";
 const FULL_PASS_FILENAME = "full-pass.json";
@@ -2217,18 +3287,29 @@ const SPEC_SIDE_KINDS = [
 	"group-missing",
 	"group-empty",
 	"duplicate-group-index",
+	"duplicate-task-id",
 	"orphan-task",
 	"malformed-risk-marker",
 	"malformed-task-refs",
+	"malformed-task-line",
+	"malformed-group-header",
 	"unknown-risk-class",
 	"dangling-requirement-ref",
 	"unticked-completed-task"
 ];
 const GROUP_HEADER = /^##\s+Group\s+(\d+)\b/;
+const GROUP_HEADER_LOOKALIKE = /^ {0,3}#+\s*group(?:\s*\d|\s+\S+\s*(?:—|$))/i;
+const GROUP_SHAPED_HEADING = /^ {0,3}##\s+[^\s\d]\S*\s+\d.*(?:[_*]\(.*\)[_*]|\[\s*risks?\s*:)/i;
+const LINE_CONTAINER_MARKERS = /^(?:\s*(?:>|[-+*](?=\s)|\d{1,9}[.)](?=\s)))+\s*/;
 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(?![.-]\w)/;
+const TASK_LINE_LOOKALIKE = /^\s*(?:[-*+]|\d+[.)])\s*\[[^\]]*\]\s*[*_`]*\s*T\d/;
+const BOXLESS_TASK_LINE = /^\s*(?:[-*+]|\d+[.)])\s+[*_`]*\s*T\d/;
+const TASK_BOX = /\[([^\]]*)\]/;
+const TASK_LOOKALIKE_ID = /\]\s*[*_`]*\s*(T\d+(?:[.-]?\w)*)/;
+const LINE_BOM = /^\uFEFF/;
 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*(\*\*|__)/;
@@ -2254,42 +3335,66 @@ const NOT_APPLICABLE_REASONS = [
 ];
 //#endregion
 //#region src/review-ledger/parse-spec.ts
+const VERBATIM_BLOCKS = /* @__PURE__ */ new Set([
+	"fence",
+	"code_block",
+	"html_block"
+]);
+const CODE_BLOCKS = /* @__PURE__ */ new Set(["fence", "code_block"]);
+const HIDDEN_HTML_SPAN = /<!--[\s\S]*?(?:-->|$)|<(script|style|textarea)(?=[\s/>]|$)[\s\S]*?(?:<\/\1\s*>|$)/gi;
+const HANGING_INDENT = /^ {4}/;
+const LEADING_WHITESPACE = /^[ \t]*/;
+const LINE_BREAK = /\r\n?|\n/;
+const LEADING_SPACES = /^ */;
 const parseTasksSpec = (text) => {
-	const lines = text.split(/\r?\n/);
-	const grouped = lines.some((line) => GROUP_HEADER.test(line));
+	const { lines, blocks } = withHangingIndentsRead(text.split(LINE_BREAK).map((line) => line.replace(LINE_BOM, "")));
+	const malformedTaskLines = [];
+	const malformedGroupHeaders = [];
+	const entries = readSpecEntries(lines, blocks, malformedTaskLines, malformedGroupHeaders);
+	const grouped = entries.some((entry) => entry.kind !== "task");
 	const groups = [];
 	const orphanTaskIds = [];
 	const malformedRiskHeaders = [];
 	const malformedTaskRefs = [];
+	const taskIdGroups = /* @__PURE__ */ new Map();
+	const record = (id, group) => {
+		taskIdGroups.set(id, [...taskIdGroups.get(id) ?? [], group]);
+	};
 	let current;
-	for (let index = 0; index < lines.length; index += 1) {
-		const line = lines[index] ?? "";
-		const header = GROUP_HEADER.exec(line);
-		if (header) {
-			const risk = parseRiskMarker(line);
-			if (risk.malformed) malformedRiskHeaders.push(line.trim());
+	let quarantined = false;
+	for (const entry of entries) {
+		if (entry.kind === "group") {
+			const risk = parseRiskMarker(entry.line);
+			if (risk.malformed) malformedRiskHeaders.push(entry.line.trim());
 			current = {
-				index: Number(header[1]),
-				header: line.trim(),
+				index: Number(GROUP_HEADER.exec(entry.line)?.[1]),
+				header: entry.line.trim(),
 				riskClasses: risk.riskClasses,
 				unknownRiskClasses: risk.unknownRiskClasses,
 				tasks: []
 			};
 			groups.push(current);
+			quarantined = false;
+			continue;
+		}
+		if (entry.kind === "not-a-group") {
+			quarantined = true;
+			continue;
+		}
+		const { id } = entry;
+		if (quarantined) {
+			record(id, null);
 			continue;
 		}
-		const match = TASK_LINE.exec(line);
-		if (!match) continue;
-		const blockEnd = taskBlockEnd(lines, index);
-		const parts = lines.slice(index, blockEnd).map((part) => part.trim());
-		index = blockEnd - 1;
-		const task = parseTaskBlock(match[2] ?? "", (match[1] ?? " ") !== " ", parts);
+		const task = parseTaskBlock(id, entry.ticked, entry.parts, entry.refInCode);
 		if (task.malformedRefs) malformedTaskRefs.push(task.id);
 		if (current) {
+			record(id, current.index);
 			current.tasks.push(task.task);
 			continue;
 		}
 		if (grouped) {
+			record(id, null);
 			orphanTaskIds.push(task.id);
 			continue;
 		}
@@ -2300,6 +3405,7 @@ const parseTasksSpec = (text) => {
 			unknownRiskClasses: [],
 			tasks: [task.task]
 		});
+		record(id, groups.length);
 	}
 	const seen = /* @__PURE__ */ new Set();
 	const duplicateIndexes = [];
@@ -2311,20 +3417,282 @@ const parseTasksSpec = (text) => {
 		groups,
 		orphanTaskIds,
 		duplicateIndexes,
+		duplicateTaskIds: [...taskIdGroups].filter(([, copies]) => copies.length > 1).map(([id, copies]) => ({
+			id,
+			groups: copies
+		})),
 		malformedRiskHeaders,
-		malformedTaskRefs
+		malformedTaskRefs,
+		malformedTaskLines,
+		malformedGroupHeaders
+	};
+};
+const readSpecEntries = (lines, blocks, malformedTaskLines, malformedGroupHeaders) => {
+	const entries = [];
+	const lineAt = (index) => lines[index] ?? "";
+	const samples = quotedSampleLines(lines, blocks);
+	const notAGroup = (header, zero) => {
+		malformedGroupHeaders.push({
+			header: header.trim(),
+			defect: zero ? "zero" : "lookalike"
+		});
+		entries.push({ kind: "not-a-group" });
+	};
+	const notATask = (line, owner) => {
+		if (owner !== void 0) {
+			malformedTaskLines.push({
+				line: line.trim(),
+				defect: "nested",
+				parentId: owner
+			});
+			return;
+		}
+		malformedTaskLines.push({
+			line: line.trim(),
+			defect: taskLineDefect(line, writtenIdOf(line))
+		});
 	};
-};
-const taskBlockEnd = (lines, start) => {
-	let end = start + 1;
-	while (end < lines.length) {
-		const line = lines[end] ?? "";
-		if (line.trim() === "" || !/^\s/.test(line) || TASK_LINE.test(line) || GROUP_HEADER.test(line)) break;
-		end += 1;
+	const readVerbatim = (block) => {
+		const shown = hidesHtml(block) ? shownPastHiddenHtml(block.content) : [];
+		block.content.split("\n").forEach((line, offset) => {
+			const text = (shown[offset] ?? "").trimStart();
+			if (TASK_LINE_LOOKALIKE.test(line)) malformedTaskLines.push({
+				line: line.trim(),
+				defect: "fenced"
+			});
+			else if (isGroupShaped(line)) malformedGroupHeaders.push({
+				header: line.trim(),
+				defect: "fenced"
+			});
+			else if (TASK_LINE_LOOKALIKE.test(text)) malformedTaskLines.push({
+				line: text.trim(),
+				defect: "shape"
+			});
+			else if (isGroupShaped(text)) malformedGroupHeaders.push({
+				header: text.trim(),
+				defect: "lookalike"
+			});
+		});
+	};
+	const readHeading = (block) => {
+		const line = lineAt(block.start);
+		const header = GROUP_HEADER.exec(line);
+		if (header && Number(header[1]) > 0) {
+			entries.push({
+				kind: "group",
+				line
+			});
+			return;
+		}
+		const shown = `${headingMarks(block.markup)} ${block.text}`;
+		const own = line.replace(LINE_CONTAINER_MARKERS, "");
+		if (![
+			line,
+			shown,
+			block.markup.startsWith("#") ? own : `${headingMarks(block.markup)} ${own}`
+		].some(isGroupShaped)) return;
+		notAGroup(line, isGroupZero(shown));
+	};
+	const readParagraph = (block, owner, itemLine) => {
+		for (let index = block.start; index < block.end; index += 1) {
+			if (index === itemLine) continue;
+			const line = lineAt(index);
+			if (isGroupShaped(line)) notAGroup(line, false);
+			else if (TASK_LINE_LOOKALIKE.test(line)) notATask(line, owner);
+			else if (samples.has(index) && TASK_LINE_LOOKALIKE.test(unquoted(line))) malformedTaskLines.push({
+				line: line.trim(),
+				defect: "shape"
+			});
+			else if (owner === void 0 && BOXLESS_TASK_LINE.test(line)) malformedTaskLines.push({
+				line: line.trim(),
+				defect: "shape"
+			});
+		}
+	};
+	const readItem = (block, owner) => {
+		const line = lineAt(block.start);
+		if (TASK_LINE_LOOKALIKE.test(line)) {
+			const writtenId = writtenIdOf(line);
+			const match = TASK_LINE.exec(line);
+			const id = match?.[2];
+			if (owner !== void 0 || !match || id === void 0) notATask(line, owner);
+			else entries.push({
+				kind: "task",
+				id,
+				ticked: (match[1] ?? " ") !== " ",
+				...taskText(lines, block)
+			});
+			readBlocks(block.children, owner ?? writtenId, block.start);
+			return;
+		}
+		if (isQuotedTask(lines, block)) {
+			malformedTaskLines.push({
+				line: line.trim(),
+				defect: "shape"
+			});
+			readBlocks(block.children, owner, block.start);
+			return;
+		}
+		if (owner === void 0 && BOXLESS_TASK_LINE.test(line)) malformedTaskLines.push({
+			line: line.trim(),
+			defect: "shape"
+		});
+		readBlocks(block.children, owner, block.start);
+	};
+	const readBlocks = (siblings, owner, itemLine) => {
+		for (const block of siblings) if (VERBATIM_BLOCKS.has(block.type)) readVerbatim(block);
+		else if (block.type === "heading") readHeading(block);
+		else if (block.type === "paragraph") readParagraph(block, owner, itemLine);
+		else if (block.type === "list_item") readItem(block, owner);
+		else readBlocks(block.children, owner, -1);
+	};
+	readBlocks(blocks, void 0, -1);
+	return entries;
+};
+const withHangingIndentsRead = (source) => {
+	const lines = source.map(withLeadingTabsExpanded);
+	for (;;) {
+		const blocks = parseMarkdownBlocks(lines);
+		const shifting = codeInTasks(lines, blocks, void 0).filter(({ block, task }) => !(block.end >= task.end && continuesParagraph(lines[block.end]))).filter(({ block }) => canShift(lines, block)).map(({ block }) => block);
+		if (shifting.length === 0) return {
+			lines,
+			blocks
+		};
+		const rounds = shifting.reduce((fewest, block) => Math.min(fewest, shiftsLeavingItCode(lines, block)), Number.POSITIVE_INFINITY);
+		let shifted = false;
+		for (const block of shifting) for (let index = block.start; index < block.end; index += 1) {
+			let line = lines[index] ?? "";
+			for (let n = 0; n < rounds && HANGING_INDENT.test(line); n += 1) {
+				line = line.replace(HANGING_INDENT, "");
+				shifted = true;
+			}
+			lines[index] = line;
+		}
+		if (!shifted) return {
+			lines,
+			blocks
+		};
 	}
-	return end;
 };
-const parseTaskBlock = (id, ticked, parts) => {
+const canShift = (lines, block) => {
+	const content = block.content.split("\n");
+	return lines.slice(block.start, block.end).every((line, offset) => line.trim() === "" || line.replace(/\0/g, "�").trimStart() === (content[offset] ?? "").trimStart());
+};
+const shiftsLeavingItCode = (lines, block) => {
+	const content = block.content.split("\n");
+	let threshold;
+	let least = Number.POSITIVE_INFINITY;
+	for (let index = block.start; index < block.end; index += 1) {
+		const line = lines[index] ?? "";
+		if (line.trim() === "") continue;
+		const code = content[index - block.start] ?? "";
+		const indent = LEADING_SPACES.exec(line)?.[0].length ?? 0;
+		if (line.slice(indent) !== code.trimStart()) return 1;
+		threshold = indent - (LEADING_SPACES.exec(code)?.[0].length ?? 0);
+		least = Math.min(least, indent);
+	}
+	if (threshold === void 0) return 1;
+	return Math.floor((least - threshold) / 4) + 1;
+};
+const withLeadingTabsExpanded = (line) => {
+	const [lead = ""] = LEADING_WHITESPACE.exec(line) ?? [];
+	if (!lead.includes("	")) return line;
+	let column = 0;
+	for (const char of lead) column = char === "	" ? column + 4 - column % 4 : column + 1;
+	return " ".repeat(column) + line.slice(lead.length);
+};
+const codeInTasks = (lines, blocks, task) => blocks.flatMap((block) => {
+	if (block.type === "code_block") return task ? [{
+		block,
+		task
+	}] : [];
+	const opens = block.type === "list_item" && TASK_LINE_LOOKALIKE.test(lines[block.start] ?? "");
+	return codeInTasks(lines, block.children, task ?? (opens ? block : void 0));
+});
+const taskText = (lines, item) => {
+	const nested = /* @__PURE__ */ new Set();
+	const code = /* @__PURE__ */ new Set();
+	const shown = /* @__PURE__ */ new Map();
+	const exclude = (blocks) => {
+		for (const block of blocks) {
+			const hidden = hidesHtml(block);
+			if (hidden) shownPastHiddenHtml(block.content).forEach((text, offset) => {
+				if (text.trim() !== "") shown.set(block.start + offset, text);
+			});
+			const into = CODE_BLOCKS.has(block.type) || hidden ? code : block.type === "list_item" && (TASK_LINE_LOOKALIKE.test(lines[block.start] ?? "") || isQuotedTask(lines, block)) ? nested : void 0;
+			if (!into) {
+				exclude(block.children);
+				continue;
+			}
+			for (let index = block.start; index < block.end; index += 1) into.add(index);
+		}
+	};
+	exclude(item.children);
+	const samples = quotedSampleLines(lines, item.children);
+	const parts = [(lines[item.start] ?? "").trim()];
+	let refInCode = false;
+	for (let index = item.start + 1; index < item.end; index += 1) {
+		const line = lines[index] ?? "";
+		if (nested.has(index) || line.trim() === "") continue;
+		if (code.has(index)) {
+			refInCode ||= hasRefLookalike([line]);
+			const text = shown.get(index);
+			if (text !== void 0 && !isTaskOrHeaderShaped(text.trimStart())) parts.push(text.trim());
+			continue;
+		}
+		if (isTaskOrHeaderShaped(line) || samples.has(index)) continue;
+		parts.push(line.trim());
+	}
+	return {
+		parts,
+		refInCode
+	};
+};
+const hidesHtml = (block) => block.type === "html_block" && shownPastHiddenHtml(block.content).join("\n") !== block.content;
+const shownPastHiddenHtml = (content) => content.replace(HIDDEN_HTML_SPAN, (span) => span.replace(/[^\n]/g, "")).split("\n");
+const isTaskOrHeaderShaped = (line) => TASK_LINE_LOOKALIKE.test(line) || isGroupShaped(line);
+const isQuotedTask = (lines, item) => {
+	const line = lines[item.start] ?? "";
+	return !TASK_LINE_LOOKALIKE.test(line) && TASK_LINE_LOOKALIKE.test(unquoted(line)) && !opensItemOn(item.children, item.start);
+};
+const quotedSampleLines = (lines, blocks) => {
+	const sample = /* @__PURE__ */ new Set();
+	const visit = (siblings, inQuote) => {
+		for (const block of siblings) {
+			if (inQuote && block.type === "paragraph") {
+				let folded = false;
+				for (let index = block.start; index < block.end; index += 1) {
+					const line = lines[index] ?? "";
+					folded ||= TASK_LINE_LOOKALIKE.test(unquoted(line));
+					if (folded) sample.add(index);
+				}
+			}
+			visit(block.children, inQuote || block.type === "blockquote");
+		}
+	};
+	visit(blocks, false);
+	return sample;
+};
+const opensItemOn = (blocks, start) => blocks.some((block) => block.type === "list_item" && block.start === start || opensItemOn(block.children, start));
+const unquoted = (line) => {
+	const markers = LINE_CONTAINER_MARKERS.exec(line)?.[0] ?? "";
+	return line.slice(markers.lastIndexOf(">") + 1);
+};
+const continuesParagraph = (line) => {
+	if (line === void 0 || line.trim() === "") return false;
+	const [only, ...rest] = parseMarkdownBlocks(["text", line]);
+	return rest.length === 0 && (only?.type === "paragraph" || only?.type === "heading" && only.markup.startsWith("=")) && only.end === 2;
+};
+const headingMarks = (markup) => markup.startsWith("#") ? markup : markup.startsWith("=") ? "#" : "##";
+const isGroupShaped = (line) => GROUP_HEADER.test(line) || GROUP_HEADER_LOOKALIKE.test(line) || GROUP_SHAPED_HEADING.test(line);
+const isGroupZero = (line) => Number(GROUP_HEADER.exec(line)?.[1] ?? NaN) === 0;
+const writtenIdOf = (line) => TASK_LOOKALIKE_ID.exec(line)?.[1] ?? "";
+const taskLineDefect = (line, writtenId) => {
+	if (!/^[ xX]$/.test(TASK_BOX.exec(line)?.[1] ?? "")) return "checkbox";
+	if (!/^T\d+$/.test(writtenId)) return "id";
+	return "shape";
+};
+const parseTaskBlock = (id, ticked, parts, refInCode) => {
 	const block = parts.join(" ");
 	const opener = refsOpener(parts, block);
 	const refs = opener === void 0 ? null : declarationAt(parts, block, opener);
@@ -2336,7 +3704,7 @@ const parseTaskBlock = (id, ticked, parts) => {
 			ticked,
 			requirementRefs: [...new Set(requirementRefs)]
 		},
-		malformedRefs: refs === null && hasRefLookalike(parts)
+		malformedRefs: refs === null && (refInCode || hasRefLookalike(parts))
 	};
 };
 const declarationAt = (parts, block, opener) => {
@@ -2418,9 +3786,11 @@ const parseRiskMarker = (line) => {
 	};
 };
 const parseRequirementIds = (text) => {
+	const lines = text.split(LINE_BREAK).map((line) => line.replace(LINE_BOM, ""));
 	const ids = [];
-	for (const line of text.split(/\r?\n/)) {
-		const id = REQUIREMENT_LINE.exec(line)?.[1];
+	for (const list of parseMarkdownBlocks(lines)) for (const item of list.children) {
+		if (item.type !== "list_item") continue;
+		const id = REQUIREMENT_LINE.exec(lines[item.start] ?? "")?.[1];
 		if (id && !ids.includes(id)) ids.push(id);
 	}
 	return ids;
@@ -2514,7 +3884,7 @@ const runLedgerValidate = async (inputs) => {
 		});
 		return result;
 	}
-	const spec = parseTasksSpec(await readFile(join(inputs.repoRoot, tasksRel), "utf8"));
+	const spec = parsedFrom(tasksRel, await readFile(join(inputs.repoRoot, tasksRel), "utf8"), parseTasksSpec);
 	for (const index of spec.duplicateIndexes) problems.push({
 		kind: "duplicate-group-index",
 		message: `tasks.md declares "## Group ${index}" more than once. A step resolves to the first, so every later group of that number is never reviewed.`,
@@ -2524,14 +3894,32 @@ const runLedgerValidate = async (inputs) => {
 		kind: "orphan-task",
 		message: `${spec.orphanTaskIds.join(", ")} sit above the first group header, so they belong to no step and no review covers them.`
 	});
+	for (const duplicate of spec.duplicateTaskIds) {
+		const where = duplicate.groups.map((group) => group === null ? "no group" : `Group ${group}`).join(", ");
+		problems.push({
+			kind: "duplicate-task-id",
+			message: `${duplicate.id} is written ${duplicate.groups.length} times in tasks.md (${where}). A task id names the task in the ledger's criteria (a task declaring no ref is its own criterion) and in every report, so the copies cannot be told apart and one can pass on the other's evidence. Give each copy its own id — the next free "T<n>" in tasks.md.`,
+			subject: duplicate.id
+		});
+	}
 	for (const header of spec.malformedRiskHeaders) problems.push({
 		kind: "malformed-risk-marker",
 		message: `"${header}" carries a risk token that is not a parseable "[risk: <class>]" marker at end of line. Left as-is it reads as no declared risk.`,
 		subject: header
 	});
+	for (const malformed of spec.malformedGroupHeaders) problems.push({
+		kind: "malformed-group-header",
+		message: malformedGroupHeaderMessage(malformed),
+		subject: malformed.header
+	});
+	for (const malformed of spec.malformedTaskLines) problems.push({
+		kind: "malformed-task-line",
+		message: malformedTaskLineMessage(malformed),
+		subject: malformed.line
+	});
 	for (const id of spec.malformedTaskRefs) problems.push({
 		kind: "malformed-task-refs",
-		message: `${id} carries a "(R<n>"-shaped ref list that is not a declaration: a declaration is one comma-separated "(R1, R2)" group that ends a line — no ranges ("R1–R3"), nothing after the closing paren on that line — at the end of the task's first line, right after the title's bold close, or the only group ending a continuation line. Left as-is it reads as a task that references no requirement, and its slice shrinks to itself.`,
+		message: `${id} carries a "(R<n>"-shaped ref list that is not a declaration: a declaration is one comma-separated "(R1, R2)" group that ends a line — no ranges ("R1–R3"), nothing after the closing paren on that line — at the end of the task's first line, right after the title's bold close, or the only group ending a continuation line. If the group is a prose aside rather than the list, open it with "per" ("(per R42, …)"): a bare aside falls under the same rules as the declaration, so only the real list may be declaration-shaped. Left as-is it reads as a task that references no requirement, and its slice shrinks to itself.`,
 		subject: id
 	});
 	const groups = resolveGroups(spec.groups, address, problems);
@@ -2572,6 +3960,23 @@ const runLedgerValidate = async (inputs) => {
 	return result;
 };
 const reviewLedgerPath = (taskId, address) => join(TASKS_DIR, taskId, REVIEW_LEDGER_DIRNAME, address.kind === "full-pass" ? FULL_PASS_FILENAME : `step-${address.step}.json`);
+const malformedGroupHeaderMessage = (malformed) => {
+	switch (malformed.defect) {
+		case "zero": return `"${malformed.header}" — group numbers start at 1 and no --step addresses 0, so the tasks under it are read into no group. Renumber the groups from 1.`;
+		case "lookalike": return `"${malformed.header}" looks like a group header but is not a top-level "## Group <n>" (two # at the start of the line, "Group" capitalized and in English whatever the spec's language, a bare number, outside any list or quote), so the tasks under it are read into no group — not even the one above. Write it as "## Group <n> — …" at the start of a line of its own; a line underlined with "---" or "===" is a heading too, so put a blank line above a rule that is not one; if it is not a group, reword it so it no longer reads "Group <word>", or "<word> <n>" with a "_(…)_" or "*(…)*" rationale or a "[risk: …]" tag.`;
+		case "fenced": return `"${malformed.header}" is a group header inside a code block (a fence, four-space-indented code, raw HTML) — a quoted sample and a real header under a fence that never closed cannot be told apart, so it is not read as a group. If it is a sample, reword it so it no longer reads "Group <n>", or "<word> <n>" with a "_(…)_" or "*(…)*" rationale or a "[risk: …]" tag; if it is a group, close the fence above it or remove the indentation, and write it as "## Group <n> — …".`;
+	}
+};
+const malformedTaskLineMessage = (malformed) => {
+	const left = "so it is not read as a task — it leaves its group's slice and tick check, and its refs with it";
+	switch (malformed.defect) {
+		case "checkbox": return `"${malformed.line}" has a checkbox that is neither "[ ]" nor "[x]" (an in-progress "[-]", a padded "[  ]"), ${left}. Write "[ ]", or "[x]" once the task is green.`;
+		case "id": return `"${malformed.line}" has a task id that is not a bare "T<n>" (a suffixed "T12b", a sub-numbered "T1.1"), ${left}. Give it the next free "T<n>" in tasks.md instead.`;
+		case "shape": return `"${malformed.line}" is not written as a task line "- [ ] T<n>" (a bullet with no checkbox, a numbered "1. [ ]" item, an id in single "*" or "_", a task inside a ">" quote), ${left}. Write it "- [ ] T<n> — …" outside any quote (a bold "**T<n> — …**" title is fine); if it is a note, not a task, reword it so it does not open with "T<n>".`;
+		case "nested": return `"${malformed.line}" is a task line nested inside ${malformed.parentId}'s list item — a sub-step of it and a task of its own cannot be told apart, ${left}. Outdent it to the task list if it is a task; drop its "T<n>" id if it is a sub-step.`;
+		case "fenced": return `"${malformed.line}" is a task line inside a code block (a fence, four-space-indented code, raw HTML) — a quoted sample and a task under a fence that never closed cannot be told apart, ${left}. If it is a sample, drop its "T<n>" id; if it is a task, close the fence above it or remove the indentation.`;
+	}
+};
 const resolveGroups = (groups, address, problems) => {
 	if (address.kind === "full-pass") {
 		if (groups.length > 0) return groups;
@@ -2609,7 +4014,7 @@ const collectDanglingRefs = async (requirementsPath, sliceIds, problems) => {
 		});
 		return referenced;
 	}
-	const declared = parseRequirementIds(await readFile(requirementsPath, "utf8"));
+	const declared = parsedFrom(requirementsPath, await readFile(requirementsPath, "utf8"), parseRequirementIds);
 	const dangling = referenced.filter((id) => !declared.includes(id));
 	for (const id of dangling) problems.push({
 		kind: "dangling-requirement-ref",
@@ -2710,19 +4115,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 ?? [])],
@@ -2782,6 +4175,13 @@ const checkCriteria = (required, dangling, ledger, problems) => {
 		present
 	};
 };
+const parsedFrom = (path, text, parse) => {
+	try {
+		return parse(text);
+	} catch (error) {
+		throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+};
 //#endregion
 //#region src/spinoff/spinoff.constant.ts
 const MANAGED_LABEL = "harness:managed";
@@ -2917,7 +4317,8 @@ const FIELD_AXIS = {
 		cycle_time_h: "metric",
 		review_rejections: "metric",
 		mode: "internal-enum",
-		steps: "metric"
+		steps: "metric",
+		checkpoints: "metric"
 	},
 	review_rejected: {
 		...ENVELOPE_AXIS,
@@ -3549,7 +4950,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";
@@ -3708,93 +5109,390 @@ const renderRoleSkills = (selected, role) => {
 	return groups.length > 0 ? groups.join("\n\n") : "_None._";
 };
 //#endregion
-//#region src/doctor/cli-bin.constant.ts
-const LEMONY_BIN = "lemony";
+//#region src/merge/conflict-markers.constant.ts
+const CONFLICT_MARKER_CLIENT = "<<<<<<< client";
+const CONFLICT_MARKER_SEPARATOR = "=======";
+const CONFLICT_MARKER_VENDOR = ">>>>>>> vendor";
 //#endregion
-//#region src/doctor/resolve-cli.ts
-const isExecutable = async (path) => {
-	try {
-		await access(path, constants.X_OK);
-		return true;
-	} catch {
-		return false;
-	}
-};
-const isCliOnPath = async (pathEnv = process.env.PATH, isExe = isExecutable) => {
-	if (!pathEnv) return false;
-	for (const dir of pathEnv.split(delimiter)) {
-		if (dir === "") continue;
-		if (await isExe(join(dir, "lemony"))) return true;
-	}
-	return false;
-};
+//#region src/merge/conflict-markers.ts
+const CONFLICT_FENCE = new RegExp(`^(?:${CONFLICT_MARKER_CLIENT}|${CONFLICT_MARKER_VENDOR})$`, "m");
+const hasConflictMarkers = (content) => CONFLICT_FENCE.test(content);
 //#endregion
-//#region src/doctor/doctor.ts
-const VENDOR_HOOK_COMMANDS = [
-	".claude/hooks/init.sh",
-	".claude/hooks/session-close.sh",
-	".claude/hooks/require-playbook.sh",
-	".claude/hooks/suggest-playbook.sh"
-];
-const runDoctor = async (deps) => {
-	const { repoRoot } = deps;
-	const checks = [];
-	let config = null;
-	try {
-		config = await readHarnessConfig(repoRoot);
-		checks.push({
-			name: "config",
-			status: "ok",
-			detail: `${HARNESS_CONFIG_FILENAME} is valid.`
-		});
-	} catch (error) {
-		checks.push({
-			name: "config",
-			status: "fail",
-			detail: error.message,
-			remediation: `Fix ${HARNESS_CONFIG_FILENAME} (the error above names the key), then re-run \`lemony doctor\`.`
-		});
+//#region src/merge/three-way-merge.ts
+const threeWayMerge = (base, client, vendor) => {
+	const baseLines = base.split("\n");
+	const clientLines = client.split("\n");
+	const vendorLines = vendor.split("\n");
+	const regions = diff3Regions(baseLines, clientLines, vendorLines);
+	const out = [];
+	let conflicted = false;
+	for (const region of regions) {
+		if (region.stable) {
+			out.push(...region.lines);
+			continue;
+		}
+		if (linesEqual(region.client, region.vendor)) out.push(...region.client);
+		else {
+			conflicted = true;
+			out.push(CONFLICT_MARKER_CLIENT, ...region.client, CONFLICT_MARKER_SEPARATOR, ...region.vendor, CONFLICT_MARKER_VENDOR);
+		}
 	}
-	checks.push(await checkLabels(deps, config));
-	checks.push(await checkHooks(repoRoot));
-	checks.push(await checkGitUser(deps));
-	checks.push(await checkGhAuth(deps, config));
-	checks.push(checkVersionPin(deps, config));
-	checks.push(await checkCliResolution(deps));
-	checks.push(await checkCapabilities(deps, config));
-	checks.push(await checkDesignToolDrift(deps));
-	checks.push(await checkHookLib(deps));
 	return {
-		checks,
-		ok: checks.every((check) => check.status !== "fail")
+		merged: out.join("\n"),
+		conflicted
 	};
 };
-const checkLabels = async (deps, config) => {
-	const name = "labels";
-	if (!config) return {
-		name,
-		status: "warn",
-		detail: "Skipped — config did not validate."
-	};
-	const slug = config.task_storage.repo;
-	if (slug === "OWNER/REPO") return {
-		name,
-		status: "warn",
-		detail: `task_storage.repo is the ${TASK_STORAGE_REPO_PLACEHOLDER} placeholder — set a real slug to manage labels.`,
-		remediation: `Set task_storage.repo in ${HARNESS_CONFIG_FILENAME}, then run \`lemony repair\`.`
-	};
-	const list = await createTaskTrackerProvider(config.task_storage.type, deps.runCommand).listLabels(slug);
-	if (list.code !== 0) return {
-		name,
-		status: "warn",
-		detail: `Could not list labels via \`gh\` (exit ${list.code}). Is gh installed and authenticated?`
+const linesEqual = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
+const diff3Regions = (base, client, vendor) => {
+	const hunks = [...diffRegions(base, client).map((d) => ({
+		...d,
+		side: "client"
+	})), ...diffRegions(base, vendor).map((d) => ({
+		...d,
+		side: "vendor"
+	}))].toSorted((a, b) => a.baseStart - b.baseStart || a.baseEnd - b.baseEnd);
+	const regions = [];
+	let baseCursor = 0;
+	let i = 0;
+	const emitStable = (until) => {
+		if (until > baseCursor) {
+			regions.push({
+				stable: true,
+				lines: base.slice(baseCursor, until)
+			});
+			baseCursor = until;
+		}
 	};
-	let existing;
-	try {
-		existing = JSON.parse(list.stdout || "[]");
-	} catch {
-		return {
-			name,
+	while (i < hunks.length) {
+		const first = hunks[i];
+		if (first === void 0) break;
+		let regionBaseStart = first.baseStart;
+		let regionBaseEnd = first.baseEnd;
+		const group = [first];
+		i += 1;
+		while (i < hunks.length) {
+			const next = hunks[i];
+			if (next === void 0 || next.baseStart > regionBaseEnd) break;
+			regionBaseEnd = Math.max(regionBaseEnd, next.baseEnd);
+			group.push(next);
+			i += 1;
+		}
+		emitStable(regionBaseStart);
+		const touchedByClient = group.some((h) => h.side === "client");
+		const touchedByVendor = group.some((h) => h.side === "vendor");
+		if (touchedByClient && touchedByVendor) regions.push({
+			stable: false,
+			client: projectSide(group, "client", client, regionBaseStart, regionBaseEnd),
+			vendor: projectSide(group, "vendor", vendor, regionBaseStart, regionBaseEnd)
+		});
+		else {
+			const side = touchedByClient ? "client" : "vendor";
+			regions.push({
+				stable: true,
+				lines: projectSide(group, side, side === "client" ? client : vendor, regionBaseStart, regionBaseEnd)
+			});
+		}
+		baseCursor = regionBaseEnd;
+	}
+	emitStable(base.length);
+	return regions;
+};
+const projectSide = (group, side, sideLines, regionBaseStart, regionBaseEnd) => {
+	const own = group.filter((h) => h.side === side);
+	let sideStart = Number.POSITIVE_INFINITY;
+	let sideEnd = Number.NEGATIVE_INFINITY;
+	let baseStart = Number.POSITIVE_INFINITY;
+	let baseEnd = Number.NEGATIVE_INFINITY;
+	for (const h of own) {
+		sideStart = Math.min(sideStart, h.sideStart);
+		sideEnd = Math.max(sideEnd, h.sideEnd);
+		baseStart = Math.min(baseStart, h.baseStart);
+		baseEnd = Math.max(baseEnd, h.baseEnd);
+	}
+	const start = sideStart - (baseStart - regionBaseStart);
+	const end = sideEnd + (regionBaseEnd - baseEnd);
+	return sideLines.slice(start, end);
+};
+const diffRegions = (base, other) => {
+	const matches = lcsMatches(base, other);
+	const diffs = [];
+	let baseTail = 0;
+	let otherTail = 0;
+	for (const [baseIdx, otherIdx] of matches) {
+		if (baseIdx > baseTail || otherIdx > otherTail) diffs.push({
+			baseStart: baseTail,
+			baseEnd: baseIdx,
+			sideStart: otherTail,
+			sideEnd: otherIdx
+		});
+		baseTail = baseIdx + 1;
+		otherTail = otherIdx + 1;
+	}
+	if (base.length > baseTail || other.length > otherTail) diffs.push({
+		baseStart: baseTail,
+		baseEnd: base.length,
+		sideStart: otherTail,
+		sideEnd: other.length
+	});
+	return diffs;
+};
+const lcsMatches = (base, other) => {
+	const n = base.length;
+	const m = other.length;
+	const width = m + 1;
+	const dp = new Int32Array((n + 1) * width);
+	const at = (i, j) => dp[i * width + j] ?? 0;
+	for (let i = n - 1; i >= 0; i -= 1) for (let j = m - 1; j >= 0; j -= 1) dp[i * width + j] = base[i] === other[j] ? at(i + 1, j + 1) + 1 : Math.max(at(i + 1, j), at(i, j + 1));
+	const matches = [];
+	let i = 0;
+	let j = 0;
+	while (i < n && j < m) if (base[i] === other[j]) {
+		matches.push([i, j]);
+		i += 1;
+		j += 1;
+	} else if (at(i + 1, j) >= at(i, j + 1)) i += 1;
+	else j += 1;
+	return matches;
+};
+//#endregion
+//#region src/doctor/agent-frontmatter.ts
+const CLAUDE_CODE_FRONTMATTER = /^---\s*\n([\s\S]*?)---\s*\n?/;
+const PLAIN_KEY_LINE = /^(?![-?:](?:[ \t]|$))([^\s#'"{}[\],&*!|>%@`].*?):(?:[ \t]|$)/;
+const DOUBLE_QUOTED_KEY_LINE = /^"((?:[^"\\]|\\.)*)"[ \t]*:(?:[ \t]|$)/;
+const SINGLE_QUOTED_KEY_LINE = /^'((?:[^']|'')*)'[ \t]*:(?:[ \t]|$)/;
+const topLevelKey = (line) => {
+	const double = DOUBLE_QUOTED_KEY_LINE.exec(line)?.[1];
+	if (double !== void 0) try {
+		return JSON.parse(`"${double}"`);
+	} catch {
+		return double;
+	}
+	const single = SINGLE_QUOTED_KEY_LINE.exec(line)?.[1];
+	if (single !== void 0) return single.replaceAll("''", "'");
+	return PLAIN_KEY_LINE.exec(line)?.[1]?.replace(/[ \t]+$/, "") ?? null;
+};
+const inspectAgentFrontmatter = (content) => {
+	if (hasConflictMarkers(content)) return { kind: "conflict-markers" };
+	const block = CLAUDE_CODE_FRONTMATTER.exec(content.replace(/^\uFEFF/, ""))?.[1];
+	if (block === void 0) return null;
+	const seen = /* @__PURE__ */ new Set();
+	const duplicated = /* @__PURE__ */ new Set();
+	for (const line of block.split(/\r?\n/)) {
+		const key = topLevelKey(line);
+		if (key === null) continue;
+		if (seen.has(key)) duplicated.add(key);
+		seen.add(key);
+	}
+	return duplicated.size > 0 ? {
+		kind: "duplicate-keys",
+		keys: [...duplicated]
+	} : null;
+};
+//#endregion
+//#region src/doctor/cli-bin.constant.ts
+const LEMONY_BIN = "lemony";
+//#endregion
+//#region src/doctor/hook-lib.constant.ts
+const HOOK_LIB_CONSEQUENCES = {
+	"lemony.sh": {
+		consequence: "agent and hook calls through the `lemony` CLI launcher fail (event emits, spinoff, discovery resume)",
+		sourced: false
+	},
+	"live-branch.sh": {
+		consequence: "init.sh and session-close.sh read the task branch from HEAD only (a rebase in progress reads as no branch)",
+		sourced: true
+	},
+	"merge-pr.sh": {
+		consequence: "agent-executed merge paths (merge gate, closeout, hotfix) fail at runtime",
+		sourced: false
+	},
+	"playbook-scan.sh": {
+		consequence: "require-playbook.sh and suggest-playbook.sh error out, so playbook enforcement is off",
+		sourced: true
+	},
+	"transcript-grep.sh": {
+		consequence: "require-playbook.sh blocks matching writes even after the playbook was read",
+		sourced: true
+	}
+};
+const HOOK_LIB_UNKNOWN_CONSEQUENCE = "the hooks and agents that use it fail at runtime";
+const HOOK_LIB_SOURCED_EXEC_BIT_CONSEQUENCE = "the hooks `source` it, which needs only the read bit, so nothing breaks yet";
+//#endregion
+//#region src/doctor/resolve-cli.ts
+const isExecutable = async (path) => {
+	try {
+		await access(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const isCliOnPath = async (pathEnv = process.env.PATH, isExe = isExecutable) => {
+	if (!pathEnv) return false;
+	for (const dir of pathEnv.split(delimiter)) {
+		if (dir === "") continue;
+		if (await isExe(join(dir, "lemony"))) return true;
+	}
+	return false;
+};
+//#endregion
+//#region src/doctor/doctor.ts
+const VENDOR_HOOK_COMMANDS = [
+	".claude/hooks/init.sh",
+	".claude/hooks/session-close.sh",
+	".claude/hooks/require-playbook.sh",
+	".claude/hooks/suggest-playbook.sh"
+];
+const runDoctor = async (deps) => {
+	const { repoRoot } = deps;
+	const checks = [];
+	let config = null;
+	let configSkip = "";
+	let configState = "loaded";
+	try {
+		config = await readHarnessConfig(repoRoot);
+		checks.push({
+			name: "config",
+			status: "ok",
+			detail: `${HARNESS_CONFIG_FILENAME} is valid.`
+		});
+	} catch (error) {
+		const fault = await configLoadFault(repoRoot, error);
+		configSkip = fault.skip;
+		configState = fault.state;
+		checks.push({
+			name: "config",
+			status: "fail",
+			detail: error.message,
+			remediation: fault.remediation
+		});
+	}
+	checks.push(await checkLabels(deps, config, configSkip));
+	const restore = await planRestore(deps, configState);
+	const configCheck = checks.find((check) => check.name === "config");
+	if (configState === "absent" && configCheck !== void 0) configCheck.remediation = `${capitalize(verbStep(restore))}, then re-run \`lemony doctor\`.`;
+	checks.push(await checkHooks(repoRoot, restore));
+	checks.push(await checkGitUser(deps));
+	checks.push(await checkGhAuth(deps, config));
+	checks.push(checkVersionPin(deps, config, configSkip));
+	checks.push(await checkCliResolution(deps));
+	checks.push(await checkCapabilities(deps, config, configSkip));
+	checks.push(await checkDesignToolDrift(deps, config, configSkip));
+	checks.push(await checkHookLib(deps, restore));
+	checks.push(await checkAgentFrontmatter(repoRoot));
+	return {
+		checks,
+		ok: checks.every((check) => check.status !== "fail")
+	};
+};
+const configLoadFault = async (repoRoot, loadError) => {
+	const configPath = join(repoRoot, HARNESS_CONFIG_FILENAME);
+	const readError = await readRegularFile(configPath).then(() => void 0, (error) => error);
+	switch (await classifyConfigLinkFault(configPath, readError)) {
+		case "target-missing": return {
+			skip: `Skipped — ${HARNESS_CONFIG_FILENAME} is a symlink whose target is missing.`,
+			remediation: "Fix the symlink as the error above says, then re-run `lemony doctor`.",
+			state: "broken"
+		};
+		case "loop": return {
+			skip: `Skipped — ${HARNESS_CONFIG_FILENAME} is a symlink that loops or runs through too many links.`,
+			remediation: "Fix the symlink as the error above says, then re-run `lemony doctor`.",
+			state: "broken"
+		};
+		case "target-unreadable": return {
+			skip: `Skipped — ${HARNESS_CONFIG_FILENAME} is a symlink whose target cannot be read.`,
+			remediation: "Fix the permissions or the symlink as the error above says, then re-run `lemony doctor`.",
+			state: "broken"
+		};
+		case void 0:
+	}
+	if (readError?.code === "ENOENT") {
+		if (await hasInstallBaseline(repoRoot)) return {
+			skip: `Skipped — no ${HARNESS_CONFIG_FILENAME}.`,
+			remediation: "Do what the error above says for your case, then re-run `lemony doctor`.",
+			state: "broken"
+		};
+		return {
+			skip: `Skipped — no ${HARNESS_CONFIG_FILENAME}.`,
+			remediation: "Run `lemony install`, then re-run `lemony doctor`.",
+			state: "absent"
+		};
+	}
+	if (readError !== void 0) return {
+		skip: `Skipped — ${HARNESS_CONFIG_FILENAME} could not be read.`,
+		remediation: "Fix what the error above names, then re-run `lemony doctor`.",
+		state: "broken"
+	};
+	if (loadError.message === CONFIG_MALFORMED_MESSAGE) return {
+		skip: "Skipped — config did not validate.",
+		remediation: `Make ${HARNESS_CONFIG_FILENAME} a YAML mapping of config keys (fix the syntax, or restore its content), then re-run \`lemony doctor\`.`,
+		state: "broken"
+	};
+	return {
+		skip: "Skipped — config did not validate.",
+		remediation: `Fix ${HARNESS_CONFIG_FILENAME} (the error above names the key), then re-run \`lemony doctor\`.`,
+		state: "broken"
+	};
+};
+const FIX_CONFIG_FIRST = `Fix ${HARNESS_CONFIG_FILENAME} first (the config check says how), then re-run \`lemony doctor\``;
+const restoreVerb = (state) => state === "absent" ? "install" : "repair";
+const planRestore = async (deps, state) => {
+	const helpers = await listFiles(join(deps.vendorRoot, "hooks", "lib")).then((files) => files.filter((rel) => rel.endsWith(".sh")), () => []);
+	const leaves = [
+		SETTINGS_FILE,
+		".gitignore",
+		...helpers.map((helper) => join(HOOKS_DIR, "lib", helper))
+	];
+	const links = await findSymlinkTraversals(deps.repoRoot, leaves);
+	const copyable = await Promise.all(links.map((rel) => stat(join(deps.repoRoot, rel)).then((target) => !leaves.includes(rel) || target.isFile(), (error) => !NOWHERE_CODES.has(error.code ?? ""))));
+	return {
+		state,
+		linked: links.filter((_, index) => copyable[index]),
+		dangling: links.filter((_, index) => !copyable[index])
+	};
+};
+const NOWHERE_CODES = /* @__PURE__ */ new Set([
+	"ENOENT",
+	"ENOTDIR",
+	"ELOOP"
+]);
+const verbStep = (restore, removed = []) => {
+	const verb = restoreVerb(restore.state);
+	const kept = (rels) => rels.filter((rel) => !removed.includes(rel));
+	const linked = kept(restore.linked);
+	const dangling = kept(restore.dangling);
+	const steps = [];
+	if (dangling.length > 0) steps.push(dangling.length === 1 ? `remove the symlink ${dangling[0]}, which leads to no file` : `remove the symlinks ${dangling.join(" ")}, which lead to no file`);
+	if (linked.length > 0) steps.push(linked.length === 1 ? `replace the symlink ${linked[0]} with a regular copy of its target` : `replace the symlinks ${linked.join(" ")} with regular copies of their targets`);
+	if (steps.length === 0) return `run \`lemony ${verb}\``;
+	return `${steps.join(", ")} (\`${verb}\` refuses to write through a symlink), then run \`lemony ${verb}\``;
+};
+const checkLabels = async (deps, config, configSkip) => {
+	const name = "labels";
+	if (!config) return {
+		name,
+		status: "warn",
+		detail: configSkip
+	};
+	const slug = config.task_storage.repo;
+	if (slug === "OWNER/REPO") return {
+		name,
+		status: "warn",
+		detail: `task_storage.repo is the ${TASK_STORAGE_REPO_PLACEHOLDER} placeholder — set a real slug to manage labels.`,
+		remediation: `Set task_storage.repo in ${HARNESS_CONFIG_FILENAME}, then run \`lemony repair\`.`
+	};
+	const list = await createTaskTrackerProvider(config.task_storage.type, deps.runCommand).listLabels(slug);
+	if (list.code !== 0) return {
+		name,
+		status: "warn",
+		detail: `Could not list labels via \`gh\` (exit ${list.code}). Is gh installed and authenticated?`
+	};
+	let existing;
+	try {
+		existing = JSON.parse(list.stdout || "[]");
+	} catch {
+		return {
+			name,
 			status: "warn",
 			detail: "Could not parse `gh label list` output."
 		};
@@ -3815,18 +5513,32 @@ const checkLabels = async (deps, config) => {
 		remediation: "Run `lemony repair` to reconcile the labels."
 	};
 };
-const checkHooks = async (repoRoot) => {
+const checkHooks = async (repoRoot, restore) => {
 	const name = "hooks";
+	const remedy = (steps) => restore.state === "broken" ? `${FIX_CONFIG_FIRST}.` : `${capitalize(steps)}.`;
 	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: remedy(`remove the symlink, then ${verbStep(restore, [SETTINGS_FILE])}`)
+		};
+		if (code === "ENOENT") return {
 			name,
 			status: "fail",
 			detail: ".claude/settings.json not found.",
-			remediation: "Run `lemony repair`."
+			remediation: remedy(verbStep(restore))
+		};
+		return {
+			name,
+			status: "fail",
+			detail: `Cannot read .claude/settings.json: ${code === void 0 ? error.message : `${code}.`}`,
+			remediation: remedy(`replace it with a regular, readable file (or remove it), then ${verbStep(restore, [SETTINGS_FILE])}`)
 		};
 	}
 	let commands;
@@ -3838,7 +5550,7 @@ const checkHooks = async (repoRoot) => {
 			name,
 			status: "fail",
 			detail: ".claude/settings.json is not valid JSON.",
-			remediation: "Run `lemony repair`."
+			remediation: remedy(`fix the JSON or delete the file, then ${verbStep(restore)}`)
 		};
 	}
 	const missing = VENDOR_HOOK_COMMANDS.filter((want) => !commands.some((cmd) => cmd === want || cmd.endsWith(`/${want}`)));
@@ -3851,7 +5563,7 @@ const checkHooks = async (repoRoot) => {
 		name,
 		status: "warn",
 		detail: `Missing vendor hook wiring: ${missing.join(", ")}.`,
-		remediation: "Run `lemony repair`."
+		remediation: remedy(verbStep(restore))
 	};
 };
 const checkGitUser = async (deps) => {
@@ -3888,12 +5600,12 @@ const checkGhAuth = async (deps, config) => {
 		remediation: "Run `gh auth login`."
 	};
 };
-const checkVersionPin = (deps, config) => {
+const checkVersionPin = (deps, config, configSkip) => {
 	const name = "version-pin";
 	if (!config) return {
 		name,
 		status: "warn",
-		detail: "Skipped — config did not validate."
+		detail: configSkip
 	};
 	if (config.vendor_version === deps.installedVersion) return {
 		name,
@@ -3950,12 +5662,12 @@ const checkCliResolution = async (deps) => {
 		remediation: `Install \`${LEMONY_BIN}\` globally and keep it on PATH (this repo has no package.json to pin a devDependency).`
 	};
 };
-const checkCapabilities = async (deps, config) => {
+const checkCapabilities = async (deps, config, configSkip) => {
 	const name = "capabilities";
 	if (!config) return {
 		name,
 		status: "warn",
-		detail: "Skipped — config did not validate."
+		detail: configSkip
 	};
 	let latent;
 	try {
@@ -3982,29 +5694,52 @@ const checkCapabilities = async (deps, config) => {
 		remediation: "Run /add-capability in Claude Code to activate one — the Architect authors the artifact, then `repair` installs the skill (opt-in, never imposed)."
 	};
 };
-const checkDesignToolDrift = async (deps) => {
+const checkDesignToolDrift = async (deps, config, configSkip) => {
 	const name = "design-tool-drift";
-	const tokenPath = join(deps.repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return {
+	if (!config) return {
+		name,
+		status: "warn",
+		detail: configSkip
+	};
+	const tokenFile = resolveTokenFile(config.design_tokens.file);
+	let raw;
+	try {
+		raw = await readOptionalTokenFile(deps.repoRoot, tokenFile);
+	} 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.`
+		detail: `No ${tokenFile} — 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: `${tokenFile} 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",
-		detail: `${DESIGN_TOKENS_FILE} is not a JSON object.`,
+		status: "fail",
+		detail: `${tokenFile} is not a JSON object.`,
+		remediation: "Run `lemony design-tokens validate` to find the problem."
+	};
+	const invalid = summarizeTokenFileViolations(raw, tokenFile);
+	if (invalid !== void 0) return {
+		name,
+		status: "fail",
+		detail: `${tokenFile} fails validation: ${invalid}`,
 		remediation: "Run `lemony design-tokens validate` to find the problem."
 	};
 	const report = driftReport(parsed);
@@ -4033,7 +5768,7 @@ const checkDesignToolDrift = async (deps) => {
 		};
 	}
 };
-const checkHookLib = async (deps) => {
+const checkHookLib = async (deps, restore) => {
 	const name = "hook-lib";
 	let helpers;
 	try {
@@ -4083,7 +5818,8 @@ const checkHookLib = async (deps) => {
 		if (!await isExecutable(installed)) return {
 			helper,
 			kind: "mode",
-			description: `${helper} is not executable`
+			description: `${helper} is not executable`,
+			execBitOnly: await isReadable(installed)
 		};
 		if (!await isReadable(installed)) return {
 			helper,
@@ -4099,15 +5835,104 @@ const checkHookLib = async (deps) => {
 	};
 	const pathsOf = (kind) => problems.filter((problem) => problem.kind === kind).map((problem) => `${HOOKS_DIR}/lib/${problem.helper}`).join(" ");
 	const remediations = [];
-	if (problems.some((problem) => problem.kind === "missing")) remediations.push("Run `lemony repair` to restore the missing helpers");
-	if (problems.some((problem) => problem.kind === "obstructed")) remediations.push(`remove ${pathsOf("obstructed")} (\`repair\` cannot fix a non-file entry), then run \`lemony repair\``);
+	const verb = restoreVerb(restore.state);
+	const missing = problems.some((problem) => problem.kind === "missing");
+	const obstructed = problems.some((problem) => problem.kind === "obstructed");
+	const obstructedPaths = problems.filter((problem) => problem.kind === "obstructed").map((problem) => join(HOOKS_DIR, "lib", problem.helper));
+	if ((missing || obstructed) && restore.state === "broken") remediations.push(FIX_CONFIG_FIRST);
+	else if (obstructed) remediations.push(`remove ${pathsOf("obstructed")} (\`${verb}\` cannot fix a non-file entry), then ${verbStep(restore, obstructedPaths)}${missing ? " to restore them and the missing helpers" : ""}`);
+	else if (missing) remediations.push(`${verbStep(restore)} to restore the missing helpers`);
 	if (problems.some((problem) => problem.kind === "mode")) remediations.push(`run \`chmod +rx ${pathsOf("mode")}\` to restore the read/exec bits (\`repair\` only rewrites changed content, so it cannot)`);
 	if (problems.some((problem) => problem.kind === "unreadable")) remediations.push(`fix permissions so ${HOOKS_DIR}/lib and its entries are readable, then re-run \`lemony doctor\``);
 	return {
 		name,
 		status: "warn",
-		detail: `${HOOKS_DIR}/lib: ${problems.map((problem) => problem.description).join("; ")} — agent-executed merge paths (merge gate, closeout, hotfix) fail at runtime.`,
-		remediation: `${remediations.join("; ")}.`
+		detail: `${HOOKS_DIR}/lib: ${problems.map((problem) => `${problem.description} — ${hookLibConsequence(problem.helper, "execBitOnly" in problem && problem.execBitOnly === true)}`).join("; ")}.`,
+		remediation: `${capitalize(remediations.join("; "))}.`
+	};
+};
+const hookLibConsequence = (helper, execBitOnly) => {
+	const entry = HOOK_LIB_CONSEQUENCES[helper];
+	if (entry === void 0) return HOOK_LIB_UNKNOWN_CONSEQUENCE;
+	return entry.sourced && execBitOnly ? HOOK_LIB_SOURCED_EXEC_BIT_CONSEQUENCE : entry.consequence;
+};
+const checkAgentFrontmatter = async (repoRoot) => {
+	const name = "agent-frontmatter";
+	let files;
+	try {
+		files = (await readdir(join(repoRoot, AGENTS_DIR), { withFileTypes: true })).filter((entry) => !entry.isDirectory() && entry.name.endsWith(".md")).map((entry) => entry.name).toSorted();
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT") return {
+			name,
+			status: "ok",
+			detail: `No ${AGENTS_DIR} directory — no agent file to check.`
+		};
+		return {
+			name,
+			status: "warn",
+			detail: `Cannot read ${AGENTS_DIR}: ${code ?? error.message}.`,
+			remediation: `Make ${AGENTS_DIR} a readable directory (fix its permissions, or remove what stands in its place), then re-run \`lemony doctor\`.`
+		};
+	}
+	const checked = (await Promise.all(files.map(async (file) => {
+		const path = `${AGENTS_DIR}/${file}`;
+		try {
+			const problem = inspectAgentFrontmatter(await readRegularFile(join(repoRoot, AGENTS_DIR, file)));
+			return problem === null ? null : {
+				path,
+				problem
+			};
+		} catch (error) {
+			const code = error.code;
+			if (await stat(join(repoRoot, AGENTS_DIR, file)).then((target) => target.isDirectory(), () => false)) return "skipped";
+			return {
+				path,
+				problem: {
+					kind: "unreadable",
+					reason: error.message === "the entry is not a regular file (a FIFO, a socket or a device), so it was not read." ? "not a regular file" : code ?? error.message
+				}
+			};
+		}
+	}))).filter((finding) => finding !== "skipped");
+	const conflicted = [];
+	const duplicated = [];
+	const unreadable = [];
+	const descriptions = [];
+	for (const finding of checked) {
+		if (finding === null) continue;
+		const { path, problem } = finding;
+		if (problem.kind === "conflict-markers") {
+			conflicted.push(path);
+			descriptions.push(`${path} has unresolved conflict markers`);
+		} else if (problem.kind === "duplicate-keys") {
+			duplicated.push(path);
+			descriptions.push(`${path} declares ${problem.keys.map((key) => `\`${key}\``).join(", ")} more than once in its frontmatter`);
+		} else {
+			unreadable.push(path);
+			descriptions.push(`${path} is unreadable (${problem.reason})`);
+		}
+	}
+	if (checked.length === 0) return {
+		name,
+		status: "ok",
+		detail: `No agent file in ${AGENTS_DIR} to check.`
+	};
+	if (descriptions.length === 0) return {
+		name,
+		status: "ok",
+		detail: `All ${checked.length} agent files in ${AGENTS_DIR} are free of conflict markers and duplicate frontmatter keys.`
+	};
+	const remediations = [];
+	if (conflicted.length > 0) remediations.push(`resolve the conflict in ${conflicted.join(" ")} by hand — keep the side you want and delete the \`<<<<<<< client\` / \`=======\` / \`>>>>>>> vendor\` lines (\`update\` and \`repair\` refuse to run while any remain)`);
+	if (duplicated.length > 0) remediations.push(`edit ${duplicated.join(" ")} so each frontmatter key is declared once (merge the values if both matter — only one of them applies)`);
+	if (unreadable.length > 0) remediations.push(`make ${unreadable.join(" ")} ${unreadable.length === 1 ? "a readable file" : "readable files"} (fix the permissions, repoint a broken symlink, or remove what is not a file), then re-run \`lemony doctor\``);
+	const remediation = remediations.join("; ");
+	return {
+		name,
+		status: conflicted.length + duplicated.length > 0 ? "fail" : "warn",
+		detail: `${descriptions.join("; ")}.`,
+		remediation: `${remediation.charAt(0).toUpperCase()}${remediation.slice(1)}.`
 	};
 };
 const isReadable = async (path) => {
@@ -4118,10 +5943,89 @@ const isReadable = async (path) => {
 		return false;
 	}
 };
+const capitalize = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+//#endregion
+//#region src/status/live-branch.ts
+const REBASE_HEAD_NAME_FILES = [join("rebase-merge", "head-name"), join("rebase-apply", "head-name")];
+const REFS_HEADS = "refs/heads/";
+const stripRefsHeads = (text) => text.split("\n").filter((line) => line.startsWith(REFS_HEADS)).map((line) => line.slice(11)).join("\n");
+const readLiveBranch = async (repoRoot, run) => {
+	const head = await run("git", [
+		"-C",
+		repoRoot,
+		"symbolic-ref",
+		"--quiet",
+		"HEAD"
+	]);
+	const attached = head.code === 0 ? stripRefsHeads(head.stdout.trim()) : "";
+	if (attached !== "") return attached;
+	const gitDir = await run("git", [
+		"-C",
+		repoRoot,
+		"rev-parse",
+		"--absolute-git-dir"
+	]);
+	const dir = gitDir.code === 0 ? gitDir.stdout.trim() : "";
+	if (dir === "") return null;
+	const recorded = (await Promise.all(REBASE_HEAD_NAME_FILES.map(async (file) => {
+		const path = join(dir, file);
+		return (await stat(path).catch(() => void 0))?.isFile() ? readRegularFile(path).catch(() => "") : void 0;
+	}))).find((content) => content !== void 0);
+	return recorded === void 0 ? null : stripRefsHeads(recorded.trim()) || null;
+};
+//#endregion
+//#region src/status/git-behind.ts
+const readGitBehind = async (repoRoot, run) => {
+	const branch = await readLiveBranch(repoRoot, run);
+	if ((await run("git", [
+		"-C",
+		repoRoot,
+		"symbolic-ref",
+		"--quiet",
+		"HEAD"
+	])).code !== 0) return {
+		branch,
+		behind: null
+	};
+	const headRef = await run("git", [
+		"-C",
+		repoRoot,
+		"symbolic-ref",
+		"--quiet",
+		"refs/remotes/origin/HEAD"
+	]);
+	if (headRef.code !== 0) return {
+		branch,
+		behind: null
+	};
+	const count = await run("git", [
+		"-C",
+		repoRoot,
+		"rev-list",
+		"--count",
+		`HEAD..${headRef.stdout.trim().replace(/^refs\/remotes\//, "")}`
+	]);
+	if (count.code !== 0) return {
+		branch,
+		behind: null
+	};
+	const parsed = Number.parseInt(count.stdout.trim(), 10);
+	return {
+		branch,
+		behind: Number.isNaN(parsed) ? null : parsed
+	};
+};
 //#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;
+const TASK_BRANCHES = [/^harness\/(\d+)-.+$/, /^harness\/closeout-(\d+)$/];
+const parseTaskBranch = (branch) => {
+	if (branch === null) return null;
+	for (const shape of TASK_BRANCHES) {
+		const id = shape.exec(branch)?.[1];
+		if (id !== void 0) return id;
+	}
+	return null;
+};
 //#endregion
 //#region src/status/status.ts
 const PAUSED_LABEL = "harness:status:paused-for-clarification";
@@ -4130,8 +6034,7 @@ const runStatus = async (deps) => {
 	const config = await readHarnessConfig(repoRoot);
 	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);
+	const openDiscoveries = deps.local === true ? null : await countOpenDiscoveries(createTaskTrackerProvider(config.task_storage.type, deps.runCommand), config.task_storage.repo);
 	return {
 		vendorVersion: config.vendor_version,
 		taskStorageRepo: config.task_storage.repo,
@@ -4140,15 +6043,16 @@ const runStatus = async (deps) => {
 		behind,
 		lastSession,
 		openDiscoveries,
-		designToolDrift: await readDriftState(repoRoot)
+		designToolDrift: await readDriftState(repoRoot, resolveTokenFile(config.design_tokens.file))
 	};
 };
-const readDriftState = async (repoRoot) => {
-	const tokenPath = join(repoRoot, DESIGN_TOKENS_FILE);
-	if (!await pathExists(tokenPath)) return null;
+const readDriftState = async (repoRoot, tokenFile) => {
 	try {
-		const parsed = JSON.parse(await readFile(tokenPath, "utf8"));
+		const raw = await readOptionalTokenFile(repoRoot, tokenFile);
+		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, tokenFile) !== void 0) return null;
 		return driftReport(parsed).state;
 	} catch {
 		return null;
@@ -4163,7 +6067,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;
 	}
@@ -4223,8 +6127,8 @@ const COMMANDS = [
 	},
 	{
 		name: "status",
-		summary: "Show installed version, branch drift, and open tasks.",
-		usage: "lemony status"
+		summary: "Show installed version, branch drift, and open tasks (`--local`: no network call).",
+		usage: "lemony status [--local]"
 	},
 	{
 		name: "emit",
@@ -4236,9 +6140,14 @@ const COMMANDS = [
 		summary: "Reflect a raised/resolved discovery onto its issue (label flip; `pause` also comments); used by the Orchestrator's resolve-discovery skill.",
 		usage: "lemony discovery <pause|resume> --task-id=<id> --tier=<T1..T6> --status=<spec-in-progress|in-progress|in-review> [--note=<text>]"
 	},
+	{
+		name: "checkpoint",
+		summary: "Resolve a human checkpoint answer in one call: the commits (each with a Lemony-Checkpoint trailer), a best-effort push and the step_completed emit, emit last; used by the Orchestrator.",
+		usage: "lemony checkpoint <ok|changes|ok_downgrade> --task-id=<id> --auto-commit=<on|off> [--step=<N> --review-iterations=<K>] [--attributed-kind=<agent|skill|playbook> --attributed-name=<name>]"
+	},
 	{
 		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]>"
 	},
 	{
@@ -4292,70 +6201,6 @@ const renderTemplate = (template, vars) => template.replace(PLACEHOLDER, (_match
 	return vars[key];
 });
 //#endregion
-//#region src/baseline/baseline.ts
-const STAGING_DIR$1 = ".staging";
-const isENOENT$1 = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-const baselineRootDir = (repoRoot) => join(repoRoot, BASELINE_ROOT_REL);
-const baselineVersionDir = (repoRoot, version) => join(baselineRootDir(repoRoot), version);
-const writeBaseline = async (repoRoot, version, files) => {
-	const root = baselineRootDir(repoRoot);
-	const staging = join(root, STAGING_DIR$1);
-	await rm(staging, {
-		recursive: true,
-		force: true
-	});
-	await mkdir(staging, { recursive: true });
-	await Promise.all(files.map(async ({ relPath, content }) => {
-		const dest = join(staging, relPath);
-		await mkdir(dirname(dest), { recursive: true });
-		await writeFile(dest, content);
-	}));
-	const versionDir = baselineVersionDir(repoRoot, version);
-	await rm(versionDir, {
-		recursive: true,
-		force: true
-	});
-	await rename(staging, versionDir);
-	await pruneOtherVersions(root, version);
-};
-const pruneOtherVersions = async (root, keep) => {
-	const entries = await readdir(root, { withFileTypes: true });
-	await Promise.all(entries.filter((entry) => entry.isDirectory() && entry.name !== keep).map((entry) => rm(join(root, entry.name), {
-		recursive: true,
-		force: true
-	})));
-};
-const readBaseline = async (repoRoot, version) => {
-	const versionDir = baselineVersionDir(repoRoot, version);
-	let relPaths;
-	try {
-		relPaths = await listFiles(versionDir);
-	} catch (error) {
-		if (isENOENT$1(error)) return /* @__PURE__ */ new Map();
-		throw error;
-	}
-	const entries = await Promise.all(relPaths.map(async (relPath) => [relPath, await readFile(join(versionDir, relPath), "utf8")]));
-	return new Map(entries);
-};
-const findBaselineVersion = async (repoRoot) => {
-	const root = baselineRootDir(repoRoot);
-	let entries;
-	try {
-		entries = await readdir(root, { withFileTypes: true });
-	} catch (error) {
-		if (isENOENT$1(error)) return null;
-		throw error;
-	}
-	const versions = entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name);
-	if (versions.length <= 1) return versions[0] ?? null;
-	const withMtime = await Promise.all(versions.map(async (version) => ({
-		version,
-		mtimeMs: (await stat(join(root, version))).mtimeMs
-	})));
-	withMtime.sort((a, b) => a.mtimeMs - b.mtimeMs || a.version.localeCompare(b.version, void 0, { numeric: true }));
-	return withMtime.at(-1)?.version ?? null;
-};
-//#endregion
 //#region src/snapshot/snapshot.ts
 const STAGING_DIR = ".staging";
 const WORKING_SUBDIR = "working";
@@ -4440,183 +6285,37 @@ const readSnapshot = async (repoRoot, version) => {
 		const filePath = join(workingRoot, relPath);
 		const [content, info] = await Promise.all([readFile(filePath, "utf8"), stat(filePath)]);
 		return {
-			relPath,
-			content,
-			executable: (info.mode & 73) !== 0
-		};
-	}));
-	const baselineRoot = join(dir, BASELINE_SUBDIR);
-	const baselinePaths = await listFiles(baselineRoot);
-	const baselineEntries = await Promise.all(baselinePaths.map(async (relPath) => [relPath, await readFile(join(baselineRoot, relPath), "utf8")]));
-	return {
-		working,
-		baseline: new Map(baselineEntries)
-	};
-};
-const rotateSnapshots = async (repoRoot, keep) => {
-	if (keep === "unlimited") return [];
-	const toRemove = (await listSnapshots(repoRoot)).slice(keep);
-	await assertNoSymlinkTraversal(repoRoot, toRemove.map((version) => join(SNAPSHOTS_ROOT_REL, version)));
-	await Promise.all(toRemove.map((version) => rm(snapshotDir(repoRoot, version), {
-		recursive: true,
-		force: true
-	})));
-	return toRemove;
-};
-const cleanupSnapshots = async (repoRoot) => {
-	const versions = await listSnapshots(repoRoot);
-	await assertNoSymlinkTraversal(repoRoot, [SNAPSHOTS_ROOT_REL]);
-	await rm(snapshotsRootDir(repoRoot), {
-		recursive: true,
-		force: true
-	});
-	return versions;
-};
-//#endregion
-//#region src/merge/conflict-markers.constant.ts
-const CONFLICT_MARKER_CLIENT = "<<<<<<< client";
-const CONFLICT_MARKER_SEPARATOR = "=======";
-const CONFLICT_MARKER_VENDOR = ">>>>>>> vendor";
-//#endregion
-//#region src/merge/conflict-markers.ts
-const CONFLICT_FENCE = new RegExp(`^(?:${CONFLICT_MARKER_CLIENT}|${CONFLICT_MARKER_VENDOR})$`, "m");
-const hasConflictMarkers = (content) => CONFLICT_FENCE.test(content);
-//#endregion
-//#region src/merge/three-way-merge.ts
-const threeWayMerge = (base, client, vendor) => {
-	const baseLines = base.split("\n");
-	const clientLines = client.split("\n");
-	const vendorLines = vendor.split("\n");
-	const regions = diff3Regions(baseLines, clientLines, vendorLines);
-	const out = [];
-	let conflicted = false;
-	for (const region of regions) {
-		if (region.stable) {
-			out.push(...region.lines);
-			continue;
-		}
-		if (linesEqual(region.client, region.vendor)) out.push(...region.client);
-		else {
-			conflicted = true;
-			out.push(CONFLICT_MARKER_CLIENT, ...region.client, CONFLICT_MARKER_SEPARATOR, ...region.vendor, CONFLICT_MARKER_VENDOR);
-		}
-	}
-	return {
-		merged: out.join("\n"),
-		conflicted
-	};
-};
-const linesEqual = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
-const diff3Regions = (base, client, vendor) => {
-	const hunks = [...diffRegions(base, client).map((d) => ({
-		...d,
-		side: "client"
-	})), ...diffRegions(base, vendor).map((d) => ({
-		...d,
-		side: "vendor"
-	}))].toSorted((a, b) => a.baseStart - b.baseStart || a.baseEnd - b.baseEnd);
-	const regions = [];
-	let baseCursor = 0;
-	let i = 0;
-	const emitStable = (until) => {
-		if (until > baseCursor) {
-			regions.push({
-				stable: true,
-				lines: base.slice(baseCursor, until)
-			});
-			baseCursor = until;
-		}
-	};
-	while (i < hunks.length) {
-		const first = hunks[i];
-		if (first === void 0) break;
-		let regionBaseStart = first.baseStart;
-		let regionBaseEnd = first.baseEnd;
-		const group = [first];
-		i += 1;
-		while (i < hunks.length) {
-			const next = hunks[i];
-			if (next === void 0 || next.baseStart > regionBaseEnd) break;
-			regionBaseEnd = Math.max(regionBaseEnd, next.baseEnd);
-			group.push(next);
-			i += 1;
-		}
-		emitStable(regionBaseStart);
-		const touchedByClient = group.some((h) => h.side === "client");
-		const touchedByVendor = group.some((h) => h.side === "vendor");
-		if (touchedByClient && touchedByVendor) regions.push({
-			stable: false,
-			client: projectSide(group, "client", client, regionBaseStart, regionBaseEnd),
-			vendor: projectSide(group, "vendor", vendor, regionBaseStart, regionBaseEnd)
-		});
-		else {
-			const side = touchedByClient ? "client" : "vendor";
-			regions.push({
-				stable: true,
-				lines: projectSide(group, side, side === "client" ? client : vendor, regionBaseStart, regionBaseEnd)
-			});
-		}
-		baseCursor = regionBaseEnd;
-	}
-	emitStable(base.length);
-	return regions;
+			relPath,
+			content,
+			executable: (info.mode & 73) !== 0
+		};
+	}));
+	const baselineRoot = join(dir, BASELINE_SUBDIR);
+	const baselinePaths = await listFiles(baselineRoot);
+	const baselineEntries = await Promise.all(baselinePaths.map(async (relPath) => [relPath, await readFile(join(baselineRoot, relPath), "utf8")]));
+	return {
+		working,
+		baseline: new Map(baselineEntries)
+	};
 };
-const projectSide = (group, side, sideLines, regionBaseStart, regionBaseEnd) => {
-	const own = group.filter((h) => h.side === side);
-	let sideStart = Number.POSITIVE_INFINITY;
-	let sideEnd = Number.NEGATIVE_INFINITY;
-	let baseStart = Number.POSITIVE_INFINITY;
-	let baseEnd = Number.NEGATIVE_INFINITY;
-	for (const h of own) {
-		sideStart = Math.min(sideStart, h.sideStart);
-		sideEnd = Math.max(sideEnd, h.sideEnd);
-		baseStart = Math.min(baseStart, h.baseStart);
-		baseEnd = Math.max(baseEnd, h.baseEnd);
-	}
-	const start = sideStart - (baseStart - regionBaseStart);
-	const end = sideEnd + (regionBaseEnd - baseEnd);
-	return sideLines.slice(start, end);
+const rotateSnapshots = async (repoRoot, keep) => {
+	if (keep === "unlimited") return [];
+	const toRemove = (await listSnapshots(repoRoot)).slice(keep);
+	await assertNoSymlinkTraversal(repoRoot, toRemove.map((version) => join(SNAPSHOTS_ROOT_REL, version)));
+	await Promise.all(toRemove.map((version) => rm(snapshotDir(repoRoot, version), {
+		recursive: true,
+		force: true
+	})));
+	return toRemove;
 };
-const diffRegions = (base, other) => {
-	const matches = lcsMatches(base, other);
-	const diffs = [];
-	let baseTail = 0;
-	let otherTail = 0;
-	for (const [baseIdx, otherIdx] of matches) {
-		if (baseIdx > baseTail || otherIdx > otherTail) diffs.push({
-			baseStart: baseTail,
-			baseEnd: baseIdx,
-			sideStart: otherTail,
-			sideEnd: otherIdx
-		});
-		baseTail = baseIdx + 1;
-		otherTail = otherIdx + 1;
-	}
-	if (base.length > baseTail || other.length > otherTail) diffs.push({
-		baseStart: baseTail,
-		baseEnd: base.length,
-		sideStart: otherTail,
-		sideEnd: other.length
+const cleanupSnapshots = async (repoRoot) => {
+	const versions = await listSnapshots(repoRoot);
+	await assertNoSymlinkTraversal(repoRoot, [SNAPSHOTS_ROOT_REL]);
+	await rm(snapshotsRootDir(repoRoot), {
+		recursive: true,
+		force: true
 	});
-	return diffs;
-};
-const lcsMatches = (base, other) => {
-	const n = base.length;
-	const m = other.length;
-	const width = m + 1;
-	const dp = new Int32Array((n + 1) * width);
-	const at = (i, j) => dp[i * width + j] ?? 0;
-	for (let i = n - 1; i >= 0; i -= 1) for (let j = m - 1; j >= 0; j -= 1) dp[i * width + j] = base[i] === other[j] ? at(i + 1, j + 1) + 1 : Math.max(at(i + 1, j), at(i, j + 1));
-	const matches = [];
-	let i = 0;
-	let j = 0;
-	while (i < n && j < m) if (base[i] === other[j]) {
-		matches.push([i, j]);
-		i += 1;
-		j += 1;
-	} else if (at(i + 1, j) >= at(i, j + 1)) i += 1;
-	else j += 1;
-	return matches;
+	return versions;
 };
 //#endregion
 //#region src/update/engine.ts
@@ -4808,54 +6507,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");
@@ -4863,7 +6514,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) {
@@ -4881,7 +6532,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 {
@@ -4898,6 +6549,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;
@@ -4922,6 +6591,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));
@@ -4978,6 +6695,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;
@@ -5126,6 +6844,7 @@ const runReconcile = async (inputs) => {
 		SETTINGS_FILE,
 		".gitignore"
 	]);
+	await assertSettingsNotSpecial(join(repoRoot, SETTINGS_FILE), "merge");
 	const actions = await runEngine({
 		baseline,
 		vendorNew,
@@ -5270,7 +6989,7 @@ const runRepair = async (options) => {
 const DOCS_PREFIX = `docs${sep}`;
 const runUninstall = async (options) => {
 	const { repoRoot } = options;
-	if (!await pathExists(join(repoRoot, "harness.config.yml"))) throw new Error(`Lemony is not installed here (${HARNESS_CONFIG_FILENAME} not found).`);
+	if (!await entryExists(join(repoRoot, "harness.config.yml")) && !await hasInstallBaseline(repoRoot)) throw new Error(`Lemony is not installed here (${HARNESS_CONFIG_FILENAME} not found).`);
 	const baselineVersion = await findBaselineVersion(repoRoot);
 	if (baselineVersion === null) throw new Error("Refusing to uninstall — no baseline registry under .claude/.harness/baseline/. The baseline is the record of which files are vendor-managed; without it uninstall cannot distinguish vendor files from your own. Run `lemony repair` to restore it, or remove the harness files manually.");
 	const config = await readHarnessConfig(repoRoot);
@@ -5282,6 +7001,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));
@@ -5493,8 +7213,32 @@ 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 rejectStrayArgs = (verb, args, valued) => {
+	const seen = /* @__PURE__ */ new Set();
+	let positionals = 0;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (!arg.startsWith("--")) {
+			positionals += 1;
+			if (positionals > 1) throw new Error(`${verb}: unexpected argument "${arg}".`);
+			continue;
+		}
+		const name = arg.slice(2).split("=")[0];
+		if (!valued.includes(name)) throw new Error(`${verb}: unknown flag --${name}.`);
+		if (seen.has(name)) throw new Error(`${verb}: --${name} was given more than once.`);
+		seen.add(name);
+		const next = args[i + 1];
+		if (!arg.includes("=") && next !== void 0 && !next.startsWith("--")) i += 1;
+	}
 };
 const readHarnessVersion = async () => {
 	const raw = await readFile(PACKAGE_JSON_PATH, "utf8");
@@ -5545,7 +7289,8 @@ const makeVerifierRunCommand = () => (cmd, args) => new Promise((resolveResult)
 		resolveResult({
 			code: code ?? 1,
 			stdout: Buffer.concat(out).toString("utf8"),
-			stderr: `${Buffer.concat(err).toString("utf8")}${signal ? `killed by ${signal}\n` : ""}`
+			stderr: Buffer.concat(err).toString("utf8"),
+			...signal === null ? {} : { signal }
 		});
 	});
 });
@@ -5566,45 +7311,6 @@ const buildResolveDeps = () => {
 		close: () => rl.close()
 	};
 };
-const gitBehind = async (repoRoot) => {
-	const run = makeRunCommand();
-	const branchResult = await run("git", [
-		"-C",
-		repoRoot,
-		"symbolic-ref",
-		"--quiet",
-		"HEAD"
-	]);
-	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,
-		"symbolic-ref",
-		"--quiet",
-		"refs/remotes/origin/HEAD"
-	]);
-	if (headRef.code !== 0) return {
-		branch,
-		behind: null
-	};
-	const count = await run("git", [
-		"-C",
-		repoRoot,
-		"rev-list",
-		"--count",
-		`HEAD..${headRef.stdout.trim().replace(/^refs\/remotes\//, "")}`
-	]);
-	if (count.code !== 0) return {
-		branch,
-		behind: null
-	};
-	const parsed = Number.parseInt(count.stdout.trim(), 10);
-	return {
-		branch,
-		behind: Number.isNaN(parsed) ? null : parsed
-	};
-};
 const install = async (args) => {
 	const repoRoot = cwd();
 	if (await pathExists(join(repoRoot, "harness.config.yml"))) {
@@ -5929,6 +7635,42 @@ const discovery = async (args) => {
 	if (result.applied.length > 0) console.error(`  Applied before failure: ${result.applied.join(", ")}.`);
 	exit(1);
 };
+const checkpoint = async (args) => {
+	const valued = [
+		"task-id",
+		"auto-commit",
+		"step",
+		"review-iterations",
+		"attributed-kind",
+		"attributed-name"
+	];
+	rejectValuelessFlags("checkpoint", args, valued);
+	rejectStrayArgs("checkpoint", args, valued);
+	const result = await runCheckpoint({
+		repoRoot: cwd(),
+		answer: args[0]?.startsWith("--") ? void 0 : args[0],
+		taskId: parseFlag(args, "task-id"),
+		autoCommit: parseFlag(args, "auto-commit"),
+		step: parseFlag(args, "step"),
+		reviewIterations: parseFlag(args, "review-iterations"),
+		attributedKind: parseFlag(args, "attributed-kind"),
+		attributedName: parseFlag(args, "attributed-name"),
+		harnessVersion: await readHarnessVersion(),
+		runCommand: makeRunCommand()
+	});
+	if (result.ok) {
+		console.log(`Checkpoint ${args[0]} resolved:`);
+		for (const line of result.done) console.log(`  ${line}`);
+		for (const warning of result.warnings) console.error(`  Warning: ${warning}`);
+		return;
+	}
+	console.error(`checkpoint ${args[0]} failed at ${result.failedStep}: ${result.reason}`);
+	for (const line of result.done) console.error(`  Done before failure: ${line}`);
+	for (const warning of result.warnings) console.error(`  Warning: ${warning}`);
+	console.error("  Fix the cause and run the same command again: what already landed is skipped, and the emit runs once, last.");
+	exit(1);
+};
+const tokenFileOf = (config) => resolveTokenFile(config?.design_tokens.file);
 const designTokens = async (args) => {
 	const action = args[0] ?? "validate";
 	if (action === "validate") return designTokensValidate(args);
@@ -5938,18 +7680,20 @@ 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 tokenFile = tokenFileOf(config);
 	const result = await runValidate({
 		repoRoot: cwd(),
+		tokenFile,
 		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 ${tokenFile} — 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):`);
@@ -5959,19 +7703,32 @@ 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 verify = (await pathExists(join(cwd(), "harness.config.yml")) ? await readHarnessConfig(cwd()) : void 0)?.design_tokens.verify;
+	const config = await readOptionalHarnessConfig(cwd());
+	const verify = config?.design_tokens.verify;
+	const tokenFile = tokenFileOf(config);
 	const result = await runContrast({
 		repoRoot: cwd(),
+		tokenFile,
 		...verify === void 0 ? {} : { verify: {
 			command: verify,
 			run: makeVerifierRunCommand()
 		} }
 	});
-	if (!result.tokensFound) {
-		console.log(`No docs/design-tokens.json — design-tokens contrast skipped (consume-if-exists; the harness never creates it).`);
-		return;
-	}
 	const failures = result.pairs.filter((pair) => !pair.passes);
 	const forwardVerifier = () => {
 		if (result.verify === void 0) return;
@@ -5979,13 +7736,28 @@ const designTokensContrast = async () => {
 		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(result.verify === void 0 ? `No ${tokenFile} — design-tokens contrast skipped (consume-if-exists; the gates never create it).` : `No ${tokenFile} — 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 ${tokenFile})`, failedVerifier));
+			process.exitCode = 1;
+			return;
+		}
+		console.log(`design-tokens verify OK: ${quotedCommand(result.verify.command)} exited 0.`);
+		return;
+	}
 	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: \`${result.verify.command}\` exited 0.`);
+		if (result.verify !== void 0) console.log(`design-tokens verify OK: ${quotedCommand(result.verify.command)} exited 0.`);
 		return;
 	}
-	const failedVerifier = result.verify !== void 0 && result.verify.code !== 0 ? result.verify : void 0;
 	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}`;
@@ -5993,54 +7765,80 @@ const designTokensContrast = async () => {
 	}
 	for (const problem of result.problems) console.error(`  ${problem}`);
 	forwardVerifier();
-	if (failedVerifier) console.error(`  design_tokens.verify \`${failedVerifier.command}\` exited ${failedVerifier.code}.`);
+	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 tokenFile = tokenFileOf(await readOptionalHarnessConfig(cwd()));
 	const result = await runImport({
 		repoRoot: cwd(),
+		tokenFile,
 		neutralPath: resolve(cwd(), from),
 		apply: args.includes("--apply"),
 		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}.`);
+		console.log(`design-tokens import applied: wrote ${result.written.length} token(s) to ${tokenFile}.`);
 		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")) {
 		console.error("design-tokens export: --out and --record are mutually exclusive — preview/push with --out, then --record only after the push succeeds.");
 		exit(1);
 	}
+	const tokenFile = tokenFileOf(await readOptionalHarnessConfig(cwd()));
 	const result = await runExport({
 		repoRoot: cwd(),
+		tokenFile,
 		...toolState ? { toolStatePath: resolve(cwd(), toolState) } : {},
 		...out ? { outPath: resolve(cwd(), out) } : {},
 		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 ${tokenFile} — design-tokens export skipped (consume-if-exists; export never creates it).`);
 		return;
 	}
 	if (result.problems.length > 0) {
@@ -6055,6 +7853,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).";
@@ -6128,12 +7927,14 @@ const spinoff = async (args) => {
 	console.error(`spinoff failed at "${result.failedStep}": ${result.reason}`);
 	exit(1);
 };
-const status = async () => {
+const status = async (args) => {
+	const local = args.includes("--local");
 	const report = await runStatus({
 		repoRoot: cwd(),
 		readGitUserEmail,
-		gitBehind,
-		runCommand: makeRunCommand()
+		gitBehind: (root) => readGitBehind(root, makeRunCommand()),
+		runCommand: makeRunCommand(),
+		local
 	});
 	const behindText = report.behind === null ? "behind unknown" : report.behind === 0 ? "up to date" : `${report.behind} behind`;
 	const discoveries = report.openDiscoveries === null ? "unknown" : String(report.openDiscoveries);
@@ -6143,7 +7944,7 @@ const status = async () => {
 	console.log(`  Active task:  ${report.activeTask ?? "(none)"}`);
 	console.log(`  Branch:       ${report.branch ?? "(unknown)"} (${behindText})`);
 	console.log(`  Last session: ${report.lastSession ?? "(none)"}`);
-	console.log(`  Open discoveries: ${discoveries}`);
+	if (!local) console.log(`  Open discoveries: ${discoveries}`);
 	if (report.designToolDrift !== null) console.log(`  Design tool:  ${DESIGN_TOOL_STATUS[report.designToolDrift]}`);
 };
 const DESIGN_TOOL_STATUS = {
@@ -6230,6 +8031,9 @@ const main = async () => {
 		case "discovery":
 			await discovery(args);
 			return;
+		case "checkpoint":
+			await checkpoint(args);
+			return;
 		case "design-tokens":
 			await designTokens(args);
 			return;
@@ -6243,7 +8047,7 @@ const main = async () => {
 			await runTelemetry(args);
 			return;
 		case "status":
-			await status();
+			await status(args);
 			return;
 		case "doctor":
 			await doctor();