@lemoncode/lemony 0.5.1 → 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 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"];
@@ -150,14 +154,18 @@ const openForWrite = async (path) => {
 	try {
 		return await open(path, WRITE | constants.O_CREAT | constants.O_EXCL);
 	} catch (error) {
-		const link = await lstat(path).catch(() => void 0);
-		if (error.code === "EEXIST" && link?.isSymbolicLink()) throw new Error(DANGLING_WRITE_REFUSAL, { cause: error });
-		throw error;
+		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 = "";
@@ -167,16 +175,112 @@ const assertNoSymlinkTraversal = async (root, relPaths) => {
 			components.add(current);
 		}
 	}
-	const offenders = (await Promise.all([...components].map(async (rel) => {
+	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);
-	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/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");
@@ -240,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),
@@ -253,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),
@@ -275,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 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 };
@@ -309,6 +438,16 @@ 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 {
@@ -316,13 +455,8 @@ const readOptionalHarnessConfig = async (repoRoot) => {
 	} catch (error) {
 		throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
-	if (!present) return void 0;
-	try {
-		return await readHarnessConfig(repoRoot);
-	} catch (error) {
-		if (error.cause?.code === "ENOENT") throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
-		throw error;
-	}
+	if (!present && !await hasInstallBaseline(repoRoot)) return void 0;
+	return readHarnessConfig(repoRoot);
 };
 //#endregion
 //#region src/config/compare-version.ts
@@ -380,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) => {
@@ -411,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();
@@ -537,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"),
@@ -584,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",
@@ -595,6 +754,7 @@ const NUMERIC_FIELDS = /* @__PURE__ */ new Set([
 	"discovered_h",
 	"step",
 	"steps",
+	"checkpoints",
 	"review_iterations"
 ]);
 const BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["auto_close"]);
@@ -625,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(", ")}.`);
@@ -652,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
@@ -1140,8 +1506,17 @@ const failureReason$1 = (result) => {
 	return `\`gh\` failed (exit ${result.code})${suffix}${detail ? `: ${detail}` : ""}`;
 };
 //#endregion
-//#region src/design-tokens/design-tokens.constant.ts
-const DESIGN_TOKENS_FILE = "docs/design-tokens.json";
+//#region src/design-tokens/read-token-file.ts
+const readOptionalTokenFile = async (repoRoot, tokenFile) => {
+	const tokenPath = join(repoRoot, tokenFile);
+	try {
+		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 SCANNED_EXTENSIONS = [
 	".css",
 	".scss",
@@ -1182,19 +1557,6 @@ const IGNORED_DIRS = /* @__PURE__ */ new Set([
 	".cache",
 	".claude"
 ]);
-const NESTED_TOO_DEEPLY = `${DESIGN_TOKENS_FILE} nests deeper than 64 levels, the most Lemony reads.`;
-//#endregion
-//#region src/design-tokens/read-token-file.ts
-const readOptionalTokenFile = async (repoRoot) => {
-	const tokenPath = join(repoRoot, DESIGN_TOKENS_FILE);
-	try {
-		if (!await entryExists(tokenPath)) return void 0;
-		return await readRegularFile(tokenPath);
-	} catch (error) {
-		if (error.code === "ENOENT") throw new Error(`Cannot read ${DESIGN_TOKENS_FILE} at ${repoRoot}: the entry is there but its target is missing (a broken symlink?).`, { cause: error });
-		throw new Error(`Cannot read ${DESIGN_TOKENS_FILE} at ${repoRoot}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-	}
-};
 //#endregion
 //#region src/design-tokens/design-tokens.model.ts
 const TOKEN_TIERS = [
@@ -1215,6 +1577,7 @@ const WCAG_FLOORS = {
 };
 //#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,
@@ -1233,7 +1596,7 @@ const exceedsNestingLimit = (value, limit = 64) => {
 };
 //#endregion
 //#region src/design-tokens/non-finite-number.ts
-const nonFiniteNumberFaults = (value) => nonFiniteNumbers(value, []).map(({ path, number }) => `${DESIGN_TOKENS_FILE} has a number at "${path}" too large for JSON to carry: it reads as ${number}, and rewriting the file would turn it into null.`);
+const 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("."),
@@ -1251,11 +1614,15 @@ 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 tokenFile = resolveTokenFile(inputs.tokenFile);
 	let raw;
 	try {
-		raw = await readOptionalTokenFile(inputs.repoRoot);
+		raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
 	} catch (error) {
 		return {
 			ok: false,
@@ -1275,7 +1642,7 @@ const runValidate = async (inputs) => {
 		filesScanned: 0,
 		violations: []
 	};
-	const fileCheck = validateTokenFile(raw);
+	const fileCheck = validateTokenFile(raw, tokenFile);
 	if (!fileCheck.ok) return {
 		ok: false,
 		tokensFound: true,
@@ -1298,7 +1665,7 @@ const runValidate = async (inputs) => {
 		};
 	}
 	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,
@@ -1307,14 +1674,15 @@ const runValidate = async (inputs) => {
 		violations: sourceViolations.violations
 	};
 };
-const summarizeTokenFileViolations = (raw) => summarizeMessages(tokenFileViolationMessages(raw));
-const tokenFileViolationMessages = (raw) => validateTokenFile(raw).violations.map((violation) => violation.message);
+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) => {
+const validateTokenFile = (raw, tokenFile) => {
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
@@ -1324,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)}`
 			}]
 		};
 	}
@@ -1333,7 +1701,7 @@ 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 {
@@ -1341,11 +1709,11 @@ const validateTokenFile = (raw) => {
 		tokenCount: 0,
 		violations: [{
 			kind: "malformed-token-file",
-			message: NESTED_TOO_DEEPLY
+			message: nestedTooDeeply(tokenFile)
 		}]
 	};
 	const violations = [];
-	for (const message of nonFiniteNumberFaults(parsed)) violations.push({
+	for (const message of nonFiniteNumberFaults(parsed, tokenFile)) violations.push({
 		kind: "malformed-token-file",
 		message
 	});
@@ -1409,53 +1777,160 @@ 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).`
 		});
 	}
-	for (const [path, token] of tokens) for (const [mode, value] of Object.entries(token.modes)) {
-		if (aliasTarget(value) === void 0) continue;
-		if (aliasChainCycles(path, tokens, mode)) violations.push({
+	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, mode) => {
-	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(mode !== void 0 && Object.hasOwn(token.modes, mode) ? token.modes[mode] : 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);
@@ -1483,7 +1958,7 @@ const describeUnreadableDir = async (dir) => {
 		return `can be listed but not searched (${codeOf(error)})`;
 	}
 };
-const scanSource = async (repoRoot, scanRoot, extensions) => {
+const scanSource = async (repoRoot, scanRoot, extensions, tokenFile) => {
 	if (!await pathExists(scanRoot)) return {
 		filesScanned: 0,
 		violations: []
@@ -1501,7 +1976,7 @@ const scanSource = async (repoRoot, scanRoot, extensions) => {
 		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,
@@ -1532,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) => {
@@ -1540,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
 		});
@@ -1694,7 +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);
+};
+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
@@ -1706,10 +2185,11 @@ const CONTRAST_LEVELS = [
 //#endregion
 //#region src/design-tokens/contrast.ts
 const runContrast = async (inputs) => {
+	const tokenFile = resolveTokenFile(inputs.tokenFile);
 	let raw;
 	let unreadable;
 	try {
-		raw = await readOptionalTokenFile(inputs.repoRoot);
+		raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
 	} catch (error) {
 		unreadable = error instanceof Error ? error.message : String(error);
 	}
@@ -1732,18 +2212,18 @@ const runContrast = async (inputs) => {
 		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 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: [`${NESTED_TOO_DEEPLY} Run \`design-tokens validate\` first.`]
+		problems: [`${nestedTooDeeply(tokenFile)} Run \`design-tokens validate\` first.`]
 	});
 	const tokens = collectTokens(parsed);
 	const problems = [];
@@ -2025,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
@@ -2040,7 +2520,7 @@ 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);
@@ -2076,7 +2556,7 @@ const NEUTRAL_VALUE_OR_REF = "Each variable carries a string \"value\" (a litera
 const NEUTRAL_NAME_SHAPE = "A name is dot-separated segments, like \"primitive.color.brand\" — fix the adapter that wrote the file.";
 const VALIDATE_HINT = "Run `lemony design-tokens validate` for the full list.";
 const IMPORT_INVALID_HINT = "Change the `--only` slice (add what it references), or fix the file first; nothing was written.";
-const IMPORT_NOT_CARRIED_HINT = "add the token in the design tool (or in docs/design-tokens.json) first, or leave out what references it; nothing was written.";
+const IMPORT_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
@@ -2152,7 +2632,7 @@ const ownUnsyncedReason = (node) => {
 	for (const [name, value] of Object.entries(modes)) {
 		if (name.trim().length === 0) return "a mode with a blank name";
 		if (name === "__proto__") return "a mode named \"__proto__\"";
-		if (!isScalar(value)) return `mode "${name}" holding neither text, a number nor a boolean`;
+		if (!isScalar$1(value)) return `mode "${name}" holding neither text, a number nor a boolean`;
 	}
 };
 const aliasTargetsOf = (node) => {
@@ -2164,7 +2644,7 @@ const modesExtension = (node) => {
 	return isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
 };
 const isCompositeValue = (value) => typeof value === "object" && value !== null;
-const isScalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+const 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"] : "";
@@ -2189,7 +2669,7 @@ 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 (isScalar(value)) out[name] = String(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 landingPath = (variable, known) => {
@@ -2197,7 +2677,7 @@ const landingPath = (variable, known) => {
 	if (KNOWN_TIERS.has(first)) return variable.name;
 	const existing = existingTierPath(variable.name, known);
 	if (existing !== void 0) return existing;
-	return `${variable.ref === void 0 ? "primitive" : "semantic"}.${variable.name}`;
+	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));
@@ -2286,6 +2766,7 @@ const diffNeutralAgainstJson = (neutral, parsed) => {
 	}
 	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 = {
@@ -2294,11 +2775,15 @@ const changeDetail = (existing, incoming) => {
 	};
 	const before = existing.modes ?? {};
 	const after = incoming.modes ?? {};
-	const modeChanges = [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].toSorted().filter((mode) => before[mode] !== after[mode]).map((mode) => ({
-		mode,
-		...before[mode] !== void 0 ? { before: before[mode] } : {},
-		...after[mode] !== void 0 ? { after: after[mode] } : {}
-	}));
+	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;
 };
@@ -2469,15 +2954,15 @@ const jsonKind = (value) => {
 	const kind = typeof value;
 	return kind === "object" ? "an object" : `a ${kind}`;
 };
-const readJsonObject = (raw) => {
+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 (exceedsNestingLimit(parsed)) throw new Error(`${NESTED_TOO_DEEPLY} 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`;
@@ -2509,13 +2994,14 @@ const runImport = async (inputs) => {
 		...empty,
 		problems: [`neutral file schemaVersion ${neutral.schemaVersion} is not supported (expected 1).`]
 	};
+	const tokenFile = resolveTokenFile(inputs.tokenFile);
 	let tokensFound = false;
 	let raw;
 	let parsed;
 	try {
-		raw = await readOptionalTokenFile(inputs.repoRoot);
+		raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
 		tokensFound = raw !== void 0;
-		parsed = raw === void 0 ? {} : readJsonObject(raw);
+		parsed = raw === void 0 ? {} : readJsonObject(raw, tokenFile);
 	} catch (error) {
 		return {
 			...empty,
@@ -2525,12 +3011,12 @@ const runImport = async (inputs) => {
 	}
 	const changes = diffNeutralAgainstJson(neutral, parsed);
 	if (!inputs.apply) {
-		const faults = summarizeMessages(raw === void 0 ? [] : tokenFileViolationMessages(raw));
+		const faults = summarizeMessages(raw === void 0 ? [] : tokenFileViolationMessages(raw, tokenFile));
 		return {
 			...empty,
 			tokensFound,
 			changes,
-			warnings: faults === void 0 ? [] : [`${DESIGN_TOKENS_FILE} already fails validation: ${faults} ${IMPORT_PREVIEW_INVALID_HINT} ${VALIDATE_HINT}`]
+			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));
@@ -2547,28 +3033,30 @@ const runImport = async (inputs) => {
 		tokensFound,
 		changes,
 		refused: true,
-		problems: [`not applied — with this import, ${DESIGN_TOKENS_FILE} would fail validation: ${NESTED_TOO_DEEPLY} ${IMPORT_TOO_DEEP_HINT}`]
+		problems: [`not applied — with this import, ${tokenFile} would fail validation: ${nestedTooDeeply(tokenFile)} ${IMPORT_TOO_DEEP_HINT}`]
 	};
 	const text = writeJsonFile(merged);
-	const mergedFaults = [...nonFiniteNumberFaults(merged), ...tokenFileViolationMessages(text)];
+	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));
+		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);
+		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 hint = notCarried.length === 0 ? IMPORT_INVALID_HINT : `${leftBehind.length > 0 ? `Add ${leftBehind.join(", ")} to the \`--only\` slice. ` : ""}The neutral file carries no variable that lands at ${notCarried.join(", ")}, so no \`--only\` slice can supply ${notCarried.length === 1 ? "it" : "them"}: ${IMPORT_NOT_CARRIED_HINT}`;
+		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, ${DESIGN_TOKENS_FILE} would fail validation: ${summarizeMessages(introduced)} ${hint}` : `not applied — ${DESIGN_TOKENS_FILE} already fails validation and this import does not repair it: ${summarizeMessages(mergedFaults)} ${VALIDATE_HINT}`]
+			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, DESIGN_TOKENS_FILE);
+		const tokenPath = join(inputs.repoRoot, tokenFile);
 		await mkdir(dirname(tokenPath), { recursive: true });
 		await writeFile(tokenPath, text);
 	}
@@ -2584,6 +3072,14 @@ const runImport = async (inputs) => {
 		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
@@ -2640,16 +3136,17 @@ const runExport = async (inputs) => {
 		recorded: false,
 		problems: []
 	};
+	const tokenFile = resolveTokenFile(inputs.tokenFile);
 	let parsed;
 	try {
-		const raw = await readOptionalTokenFile(inputs.repoRoot);
+		const raw = await readOptionalTokenFile(inputs.repoRoot, tokenFile);
 		if (raw === void 0) return empty;
-		parsed = readJsonObject(raw);
-		const invalid = summarizeTokenFileViolations(raw);
+		parsed = readJsonObject(raw, tokenFile);
+		const invalid = summarizeTokenFileViolations(raw, tokenFile);
 		if (invalid !== void 0) return {
 			...empty,
 			tokensFound: true,
-			problems: [`${DESIGN_TOKENS_FILE} fails validation: ${invalid} ${VALIDATE_HINT}`]
+			problems: [`${tokenFile} fails validation: ${invalid} ${VALIDATE_HINT}`]
 		};
 	} catch (error) {
 		return {
@@ -2662,7 +3159,7 @@ 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;
@@ -2681,11 +3178,11 @@ const runExport = async (inputs) => {
 	if (inputs.outPath !== void 0) {
 		const projection = dtcgToNeutral(parsed);
 		projection.provider = binding.provider;
-		if (await sameEntry(inputs.outPath, join(inputs.repoRoot, "docs/design-tokens.json"))) return {
+		if (await sameEntry(inputs.outPath, join(inputs.repoRoot, tokenFile))) return {
 			...empty,
 			tokensFound: true,
 			hash,
-			problems: [`Cannot write the projection to ${inputs.outPath}: it is ${DESIGN_TOKENS_FILE} itself, which the projection would replace. Name another path.`]
+			problems: [`Cannot write the projection to ${inputs.outPath}: it is ${tokenFile} itself, which the projection would replace. Name another path.`]
 		};
 		try {
 			await writeRegularFile(inputs.outPath, writeNeutralFile(projection));
@@ -2700,7 +3197,7 @@ const runExport = async (inputs) => {
 	}
 	if (inputs.record) {
 		const stamped = writeJsonFile(stampBaseline(parsed, hash));
-		const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+		const tokenPath = join(inputs.repoRoot, tokenFile);
 		await writeFile(tokenPath, stamped);
 		return {
 			tokensFound: true,
@@ -2735,6 +3232,51 @@ const sameEntry = async (a, b) => {
 };
 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";
@@ -2745,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*(\*\*|__)/;
@@ -2782,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;
 		}
@@ -2828,6 +3405,7 @@ const parseTasksSpec = (text) => {
 			unknownRiskClasses: [],
 			tasks: [task.task]
 		});
+		record(id, groups.length);
 	}
 	const seen = /* @__PURE__ */ new Set();
 	const duplicateIndexes = [];
@@ -2839,36 +3417,298 @@ 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;
-	}
-	return end;
-};
-const parseTaskBlock = (id, ticked, parts) => {
-	const block = parts.join(" ");
-	const opener = refsOpener(parts, block);
-	const refs = opener === void 0 ? null : declarationAt(parts, block, opener);
-	const requirementRefs = refs ? (refs[1] ?? "").split(",").map((ref) => ref.trim()).filter(Boolean) : [];
-	return {
-		id,
-		task: {
-			id,
-			ticked,
-			requirementRefs: [...new Set(requirementRefs)]
-		},
-		malformedRefs: refs === null && hasRefLookalike(parts)
+	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 declarationAt = (parts, block, opener) => {
-	const candidate = TASK_REFS.exec(block.slice(opener));
+	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
+		};
+	}
+};
+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);
+	const requirementRefs = refs ? (refs[1] ?? "").split(",").map((ref) => ref.trim()).filter(Boolean) : [];
+	return {
+		id,
+		task: {
+			id,
+			ticked,
+			requirementRefs: [...new Set(requirementRefs)]
+		},
+		malformedRefs: refs === null && (refInCode || hasRefLookalike(parts))
+	};
+};
+const declarationAt = (parts, block, opener) => {
+	const candidate = TASK_REFS.exec(block.slice(opener));
 	if (!candidate) return null;
 	return declarationClosesLine(parts, opener + candidate[0].length) ? candidate : null;
 };
@@ -2946,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;
@@ -3042,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.`,
@@ -3052,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);
@@ -3100,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;
@@ -3137,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",
@@ -3298,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";
@@ -3433,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,
@@ -4224,9 +5109,215 @@ const renderRoleSkills = (selected, role) => {
 	return groups.length > 0 ? groups.join("\n\n") : "_None._";
 };
 //#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;
+};
+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 {
@@ -4256,6 +5347,8 @@ const runDoctor = async (deps) => {
 	const { repoRoot } = deps;
 	const checks = [];
 	let config = null;
+	let configSkip = "";
+	let configState = "loaded";
 	try {
 		config = await readHarnessConfig(repoRoot);
 		checks.push({
@@ -4264,33 +5357,122 @@ const runDoctor = async (deps) => {
 			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: `Fix ${HARNESS_CONFIG_FILENAME} (the error above names the key), then re-run \`lemony doctor\`.`
+			remediation: fault.remediation
 		});
 	}
-	checks.push(await checkLabels(deps, config));
-	checks.push(await checkHooks(repoRoot));
+	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));
+	checks.push(checkVersionPin(deps, config, configSkip));
 	checks.push(await checkCliResolution(deps));
-	checks.push(await checkCapabilities(deps, config));
-	checks.push(await checkDesignToolDrift(deps));
-	checks.push(await checkHookLib(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 checkLabels = async (deps, config) => {
+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: "Skipped — config did not validate."
+		detail: configSkip
 	};
 	const slug = config.task_storage.repo;
 	if (slug === "OWNER/REPO") return {
@@ -4331,8 +5513,9 @@ 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 {
@@ -4343,19 +5526,19 @@ const checkHooks = async (repoRoot) => {
 			name,
 			status: "fail",
 			detail: ".claude/settings.json is a symlink whose target is missing.",
-			remediation: "Remove the symlink, then run `lemony repair`."
+			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: "Replace it with a readable file (or remove it), then run `lemony repair`."
+			remediation: remedy(`replace it with a regular, readable file (or remove it), then ${verbStep(restore, [SETTINGS_FILE])}`)
 		};
 	}
 	let commands;
@@ -4367,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}`)));
@@ -4380,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) => {
@@ -4417,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,
@@ -4479,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 {
@@ -4511,11 +5694,17 @@ 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";
+	if (!config) return {
+		name,
+		status: "warn",
+		detail: configSkip
+	};
+	const tokenFile = resolveTokenFile(config.design_tokens.file);
 	let raw;
 	try {
-		raw = await readOptionalTokenFile(deps.repoRoot);
+		raw = await readOptionalTokenFile(deps.repoRoot, tokenFile);
 	} catch (error) {
 		return {
 			name,
@@ -4527,7 +5716,7 @@ const checkDesignToolDrift = async (deps) => {
 	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 {
@@ -4536,21 +5725,21 @@ const checkDesignToolDrift = async (deps) => {
 		return {
 			name,
 			status: "fail",
-			detail: `${DESIGN_TOKENS_FILE} is not valid JSON: ${error.message}`,
+			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: "fail",
-		detail: `${DESIGN_TOKENS_FILE} is not a JSON object.`,
+		detail: `${tokenFile} is not a JSON object.`,
 		remediation: "Run `lemony design-tokens validate` to find the problem."
 	};
-	const invalid = summarizeTokenFileViolations(raw);
+	const invalid = summarizeTokenFileViolations(raw, tokenFile);
 	if (invalid !== void 0) return {
 		name,
 		status: "fail",
-		detail: `${DESIGN_TOKENS_FILE} fails validation: ${invalid}`,
+		detail: `${tokenFile} fails validation: ${invalid}`,
 		remediation: "Run `lemony design-tokens validate` to find the problem."
 	};
 	const report = driftReport(parsed);
@@ -4579,7 +5768,7 @@ const checkDesignToolDrift = async (deps) => {
 		};
 	}
 };
-const checkHookLib = async (deps) => {
+const checkHookLib = async (deps, restore) => {
 	const name = "hook-lib";
 	let helpers;
 	try {
@@ -4629,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,
@@ -4645,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) => {
@@ -4664,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";
@@ -4676,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,
@@ -4686,16 +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 readDriftState = async (repoRoot, tokenFile) => {
 	try {
-		const raw = await readOptionalTokenFile(repoRoot);
+		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) !== void 0) return null;
+		if (summarizeTokenFileViolations(raw, tokenFile) !== void 0) return null;
 		return driftReport(parsed).state;
 	} catch {
 		return null;
@@ -4770,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",
@@ -4783,6 +6140,11 @@ 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: the gates never create the file; `import --apply` bootstraps it).",
@@ -4801,107 +6163,43 @@ const COMMANDS = [
 	{
 		name: "telemetry",
 		summary: "Inspect and control anonymous telemetry (on by default): show what is sent, force a send, opt out, opt back in.",
-		usage: "lemony telemetry <status|show|flush|enable|disable [--purge-local]>"
-	}
-];
-//#endregion
-//#region src/help/help.ts
-const pad = (text, width) => text + " ".repeat(Math.max(0, width - text.length));
-const topLevelHelp = () => {
-	const width = Math.max(...COMMANDS.map((c) => c.name.length));
-	return [
-		"Lemony — the SDD harness for AI coding (vendor CLI).",
-		"",
-		"Usage: lemony <command> [flags]",
-		"",
-		"Commands:",
-		...COMMANDS.map((c) => `  ${pad(c.name, width)}  ${c.summary}`),
-		"",
-		"Run `lemony <command> --help` (or `-h`) for command-specific usage.",
-		"`lemony version` (or `--version` / `-v`) prints the installed CLI version."
-	].join("\n");
-};
-const commandHelp = (name) => {
-	const command = COMMANDS.find((c) => c.name === name);
-	if (!command) return void 0;
-	return [
-		`Usage: ${command.usage}`,
-		"",
-		command.summary
-	].join("\n");
-};
-const unknownCommand = (name) => `Unknown command "${name ?? ""}". Run \`lemony --help\` to see available commands.`;
-//#endregion
-//#region src/render/render.ts
-const PLACEHOLDER = /\{\{\s*([\w.]+)\s*\}\}/g;
-const renderTemplate = (template, vars) => template.replace(PLACEHOLDER, (_match, key) => {
-	if (!Object.hasOwn(vars, key)) throw new Error(`renderTemplate: no value provided for "${key}"`);
-	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;
+		usage: "lemony telemetry <status|show|flush|enable|disable [--purge-local]>"
 	}
-	const entries = await Promise.all(relPaths.map(async (relPath) => [relPath, await readFile(join(versionDir, relPath), "utf8")]));
-	return new Map(entries);
+];
+//#endregion
+//#region src/help/help.ts
+const pad = (text, width) => text + " ".repeat(Math.max(0, width - text.length));
+const topLevelHelp = () => {
+	const width = Math.max(...COMMANDS.map((c) => c.name.length));
+	return [
+		"Lemony — the SDD harness for AI coding (vendor CLI).",
+		"",
+		"Usage: lemony <command> [flags]",
+		"",
+		"Commands:",
+		...COMMANDS.map((c) => `  ${pad(c.name, width)}  ${c.summary}`),
+		"",
+		"Run `lemony <command> --help` (or `-h`) for command-specific usage.",
+		"`lemony version` (or `--version` / `-v`) prints the installed CLI version."
+	].join("\n");
 };
-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;
+const commandHelp = (name) => {
+	const command = COMMANDS.find((c) => c.name === name);
+	if (!command) return void 0;
+	return [
+		`Usage: ${command.usage}`,
+		"",
+		command.summary
+	].join("\n");
 };
+const unknownCommand = (name) => `Unknown command "${name ?? ""}". Run \`lemony --help\` to see available commands.`;
+//#endregion
+//#region src/render/render.ts
+const PLACEHOLDER = /\{\{\s*([\w.]+)\s*\}\}/g;
+const renderTemplate = (template, vars) => template.replace(PLACEHOLDER, (_match, key) => {
+	if (!Object.hasOwn(vars, key)) throw new Error(`renderTemplate: no value provided for "${key}"`);
+	return vars[key];
+});
 //#endregion
 //#region src/snapshot/snapshot.ts
 const STAGING_DIR = ".staging";
@@ -5020,152 +6318,6 @@ const cleanupSnapshots = async (repoRoot) => {
 	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;
-};
-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/update/engine.ts
 const cohesionKey = (relPath) => {
 	const prefix = SKILLS_DIR + sep;
@@ -5837,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);
@@ -6070,6 +7222,24 @@ const parseFlag = (args, name) => {
 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");
 	const parsed = JSON.parse(raw);
@@ -6141,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"))) {
@@ -6504,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);
@@ -6514,13 +7681,15 @@ const designTokens = async (args) => {
 };
 const designTokensValidate = async (args) => {
 	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 gates never create it).`);
+		console.log(`No ${tokenFile} — design-tokens validate skipped (consume-if-exists; the gates never create it).`);
 		return;
 	}
 	if (result.ok) {
@@ -6549,9 +7718,12 @@ const contrastFailedLine = (pairCheck, verify) => {
 	return `design-tokens contrast failed: ${pairCheck}; design_tokens.verify ${quotedCommand(verify.command)} ${outcome}.`;
 };
 const designTokensContrast = async () => {
-	const verify = (await readOptionalHarnessConfig(cwd()))?.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()
@@ -6566,14 +7738,14 @@ const designTokensContrast = async () => {
 	};
 	const failedVerifier = result.verify !== void 0 && result.verify.code !== 0 ? result.verify : void 0;
 	if (!result.tokensFound) {
-		console.log(result.verify === void 0 ? `No docs/design-tokens.json — design-tokens contrast skipped (consume-if-exists; the gates never create it).` : `No docs/design-tokens.json — design-tokens contrast pair check skipped (consume-if-exists; the gates never create it); running the declared design_tokens.verify.`);
+		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 docs/design-tokens.json)", failedVerifier));
+			console.error(contrastFailedLine(`pair check skipped (no ${tokenFile})`, failedVerifier));
 			process.exitCode = 1;
 			return;
 		}
@@ -6605,8 +7777,10 @@ const designTokensImport = async (args) => {
 	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
@@ -6619,7 +7793,7 @@ const designTokensImport = async (args) => {
 		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;
@@ -6655,14 +7829,16 @@ const designTokensExport = async (args) => {
 		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; export never creates it).`);
+		console.log(`No ${tokenFile} — design-tokens export skipped (consume-if-exists; export never creates it).`);
 		return;
 	}
 	if (result.problems.length > 0) {
@@ -6751,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);
@@ -6766,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 = {
@@ -6853,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;
@@ -6866,7 +8047,7 @@ const main = async () => {
 			await runTelemetry(args);
 			return;
 		case "status":
-			await status();
+			await status(args);
 			return;
 		case "doctor":
 			await doctor();