@lemoncode/lemony 0.1.2 → 0.3.0

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execFile } from "node:child_process";
 import { access, appendFile, chmod, lstat, mkdir, open, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
-import { delimiter, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { basename, delimiter, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { argv, cwd, env, exit, stderr, stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
@@ -24,10 +24,17 @@ const DEPRECATED_PATHS_KEYS = [
 	"agents"
 ];
 const HARNESS_CONFIG_SCHEMA_FILENAME = "harness.config.schema.json";
+const CONFIG_KEY_SINCE = { gates: "0.3.0" };
 const TASK_STORAGE_REPO_PLACEHOLDER = "OWNER/REPO";
 const TARGETS = ["claude-code"];
 const TASK_STORAGE_TYPES = ["github"];
 const TASK_STORAGE_REPO_PATTERN = /^[^\s/]+\/[^\s/]+$/;
+const PRE_COMMIT_REVIEW_MODES = [
+	"human",
+	"on",
+	"off"
+];
+const PRE_COMMIT_REVIEW_DEFAULT = "human";
 const VENDOR_VERSION_REGEX = /^\d+\.\d+\.\d+(-(alpha|beta|rc)\.\d+)?$/;
 const VENDOR_VERSION_EXAMPLE = "0.1.0-alpha.0";
 const PATHS_DEFAULTS = {
@@ -110,6 +117,12 @@ const taskStorageSchema = z.object({
 const rollbackSchema = z.object({ keep_snapshots: z.union([z.int().positive(), z.literal("unlimited")]).default(3) }).strict().prefault({});
 const telemetrySchema = z.object({ enabled: z.boolean().default(true) }).strict().prefault({});
 const designTokensSchema = z.object({ scan_extensions: z.array(z.string()).default([]) }).strict().prefault({});
+const mergeSchema = z.object({
+	checks_timeout_secs: z.int().positive().default(600),
+	allow_no_checks: z.boolean().default(false)
+}).strict().prefault({});
+const implementationSchema = z.object({ pre_commit_review: z.enum(PRE_COMMIT_REVIEW_MODES).default(PRE_COMMIT_REVIEW_DEFAULT) }).strict().prefault({});
+const gatesSchema = z.array(z.string().trim().min(1)).optional();
 const harnessConfigSchema = z.object({
 	vendor_version: z.string().regex(VENDOR_VERSION_REGEX),
 	target: z.enum(TARGETS),
@@ -117,7 +130,10 @@ const harnessConfigSchema = z.object({
 	paths: pathsSchema,
 	rollback: rollbackSchema,
 	telemetry: telemetrySchema,
-	design_tokens: designTokensSchema
+	design_tokens: designTokensSchema,
+	merge: mergeSchema,
+	implementation: implementationSchema,
+	gates: gatesSchema
 }).strict();
 //#endregion
 //#region src/config/config.ts
@@ -128,7 +144,7 @@ const readHarnessConfig = async (repoRoot) => {
 		raw = await readFile(configPath, "utf8");
 	} catch (cause) {
 		if (cause.code === "ENOENT") throw new Error(`${HARNESS_CONFIG_FILENAME} not found at ${repoRoot}. Run \`lemony install\` first.`, { cause });
-		throw cause;
+		throw new Error(`Cannot read ${HARNESS_CONFIG_FILENAME} at ${repoRoot}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
 	}
 	let parsed;
 	try {
@@ -198,7 +214,10 @@ const compareVendorVersion = (a, b) => {
 //#region src/config/write-config.ts
 const setConfigValues = (rawYaml, updates) => {
 	const doc = parseDocument(rawYaml);
-	for (const [key, value] of Object.entries(updates)) if (doc.has(key)) doc.set(key, value);
+	for (const [key, value] of Object.entries(updates)) {
+		if (!doc.has(key)) throw new Error(`Cannot write config key "${key}": it does not exist in harness.config.yml. The writer never adds structure (value-bumps only) — add the key by hand first; the template's commented docs show the shape.`);
+		doc.set(key, value);
+	}
 	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]);
 	const pathsNode = doc.get("paths", true);
@@ -211,6 +230,16 @@ const writeConfigValues = async (repoRoot, updates) => {
 	await writeFile(configPath, setConfigValues(raw, updates));
 };
 //#endregion
+//#region src/config/find-predated-keys.ts
+const findPredatedKeys = (rawYaml, fromVersion, toVersion, sinceMap) => {
+	const doc = parseDocument(rawYaml);
+	return Object.entries(sinceMap).filter(([, since]) => compareVendorVersion(since, fromVersion) === 1 && compareVendorVersion(since, toVersion) !== 1 && compareVendorVersion(since, toVersion) !== null).filter(([path]) => !doc.hasIn(path.split("."))).map(([path, since]) => ({
+		path,
+		since
+	})).toSorted((a, b) => a.path.localeCompare(b.path));
+};
+const formatPredatedKeyLine = ({ path, since }) => `  new config key \`${path}\` (added in ${since}) — your config predates it; defaults apply until you add it by hand (the template's commented docs show the shape).`;
+//#endregion
 //#region src/config/pointer.schema.ts
 const pointerScalar = z.union([
 	z.string(),
@@ -229,6 +258,7 @@ Object.keys(pointerFrontmatterSchema.shape);
 //#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");
@@ -542,6 +572,11 @@ const FLAG_LABELS = [
 		name: "harness:needs-design",
 		color: "d4548d",
 		description: "Task touches UI; a design handoff (ui-handoff.md) is owed before spec-ready."
+	},
+	{
+		name: "harness:partition-plan",
+		color: "b4a8ff",
+		description: "Partition plan of a feature: the approved cut + status of its parts. Never a task itself."
 	}
 ];
 const DISCOVERY_LABELS = [
@@ -2037,6 +2072,544 @@ const stampBaseline = (parsed, hash) => {
 };
 const asMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
+//#region src/review-ledger/review-ledger.constant.ts
+const REVIEW_LEDGER_DIRNAME = "review-ledger";
+const FULL_PASS_FILENAME = "full-pass.json";
+const FULL_PASS_STEP = "full-pass";
+const CRITERION_ID = /^[RT]\d+$/;
+const SPEC_SIDE_KINDS = [
+	"spec-missing",
+	"group-missing",
+	"group-empty",
+	"duplicate-group-index",
+	"orphan-task",
+	"malformed-risk-marker",
+	"malformed-task-refs",
+	"unknown-risk-class",
+	"dangling-requirement-ref"
+];
+const GROUP_HEADER = /^##\s+Group\s+(\d+)\b/;
+const RISK_MARKER = /\[risk:\s*([^\]]*)\]\s*$/;
+const RISK_MARKER_ALL = /\[risk:/gi;
+const RISK_MARKER_LOOKALIKE = /\[\s*risks?\s*:/i;
+const TASK_LINE = /^\s*[-*+]\s*\[[ xX]\]\s*(?:\*\*|__|`)?\s*(T\d+)\b/;
+const TASK_REFS = /^\(((?:R\d+)(?:\s*,\s*R\d+)*)\)/;
+const TASK_REFS_LOOKALIKE = /\(\s*R\d+/;
+const TASK_REFS_AFTER_TITLE = /(?:\*\*|__)\s*(\(\s*R\d+)/;
+const REQUIREMENT_LINE = /^\s*-\s*\*\*(R\d+)\*\*/;
+const TEST_FILE = /(^|\/)__tests__\/|\.(spec|test)\.[cm]?[jt]sx?$/;
+//#endregion
+//#region src/review-ledger/review-ledger.model.ts
+const RISK_CLASSES = [
+	"auth",
+	"payments",
+	"shell-process",
+	"data-loss",
+	"secrets",
+	"executable-mode"
+];
+const MUTANT_OUTCOMES = ["killed", "survived"];
+const NOT_APPLICABLE_REASONS = [
+	"no-mutable-logic",
+	"change-without-logic",
+	"generated",
+	"outside-declared-risk"
+];
+//#endregion
+//#region src/review-ledger/parse-spec.ts
+const parseTasksSpec = (text) => {
+	const lines = text.split(/\r?\n/);
+	const grouped = lines.some((line) => GROUP_HEADER.test(line));
+	const groups = [];
+	const orphanTaskIds = [];
+	const malformedRiskHeaders = [];
+	const malformedTaskRefs = [];
+	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());
+			current = {
+				index: Number(header[1]),
+				header: line.trim(),
+				riskClasses: risk.riskClasses,
+				unknownRiskClasses: risk.unknownRiskClasses,
+				tasks: []
+			};
+			groups.push(current);
+			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[1] ?? "", parts);
+		if (task.malformedRefs) malformedTaskRefs.push(task.id);
+		if (current) {
+			current.tasks.push(task.task);
+			continue;
+		}
+		if (grouped) {
+			orphanTaskIds.push(task.id);
+			continue;
+		}
+		groups.push({
+			index: groups.length + 1,
+			header: `(ungrouped) ${task.id}`,
+			riskClasses: [],
+			unknownRiskClasses: [],
+			tasks: [task.task]
+		});
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const duplicateIndexes = [];
+	for (const group of groups) {
+		if (seen.has(group.index) && !duplicateIndexes.includes(group.index)) duplicateIndexes.push(group.index);
+		seen.add(group.index);
+	}
+	return {
+		groups,
+		orphanTaskIds,
+		duplicateIndexes,
+		malformedRiskHeaders,
+		malformedTaskRefs
+	};
+};
+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, 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,
+			requirementRefs: [...new Set(requirementRefs)]
+		},
+		malformedRefs: refs === null && TASK_REFS_LOOKALIKE.test(block)
+	};
+};
+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;
+};
+const declarationClosesLine = (parts, end) => {
+	const lineEnds = /* @__PURE__ */ new Set();
+	let offset = 0;
+	for (const part of parts) {
+		offset += part.length;
+		lineEnds.add(offset);
+		offset += 1;
+	}
+	if (lineEnds.has(end)) return true;
+	const tail = parts.join(" ").slice(end);
+	return /^(?:\*\*|__)/.test(tail) && lineEnds.has(end + 2);
+};
+const refsOpener = (parts, block) => {
+	const candidates = [];
+	const onFirstLine = TASK_REFS_LOOKALIKE.exec(parts[0] ?? "")?.index;
+	if (onFirstLine !== void 0) candidates.push(onFirstLine);
+	const afterTitle = TASK_REFS_AFTER_TITLE.exec(block);
+	if (afterTitle) candidates.push(afterTitle.index + afterTitle[0].lastIndexOf("("));
+	let offset = (parts[0] ?? "").length + 1;
+	for (const part of parts.slice(1)) {
+		if (/^\(\s*R\d+/.test(part)) candidates.push(offset);
+		offset += part.length + 1;
+	}
+	return candidates.length === 0 ? void 0 : Math.min(...candidates);
+};
+const parseRiskMarker = (line) => {
+	const marker = RISK_MARKER.exec(line);
+	const markerCount = (line.match(RISK_MARKER_ALL) ?? []).length;
+	if (!marker) return {
+		riskClasses: [],
+		unknownRiskClasses: [],
+		malformed: RISK_MARKER_LOOKALIKE.test(line)
+	};
+	const riskClasses = [];
+	const unknownRiskClasses = [];
+	for (const raw of (marker[1] ?? "").split(",")) {
+		const tag = raw.trim();
+		if (tag === "") continue;
+		if (RISK_CLASSES.includes(tag)) {
+			if (!riskClasses.includes(tag)) riskClasses.push(tag);
+			continue;
+		}
+		if (!unknownRiskClasses.includes(tag)) unknownRiskClasses.push(tag);
+	}
+	return {
+		riskClasses,
+		unknownRiskClasses,
+		malformed: riskClasses.length === 0 && unknownRiskClasses.length === 0 || markerCount > 1
+	};
+};
+const parseRequirementIds = (text) => {
+	const ids = [];
+	for (const line of text.split(/\r?\n/)) {
+		const id = REQUIREMENT_LINE.exec(line)?.[1];
+		if (id && !ids.includes(id)) ids.push(id);
+	}
+	return ids;
+};
+const sliceForGroups = (groups) => {
+	const requirementIds = [];
+	const unreferencedTaskIds = [];
+	for (const group of groups) for (const task of group.tasks) {
+		if (task.requirementRefs.length === 0) {
+			if (!unreferencedTaskIds.includes(task.id)) unreferencedTaskIds.push(task.id);
+			continue;
+		}
+		for (const ref of task.requirementRefs) if (!requirementIds.includes(ref)) requirementIds.push(ref);
+	}
+	const basis = requirementIds.length > 0 && unreferencedTaskIds.length > 0 ? "mixed" : requirementIds.length > 0 ? "requirements" : "tasks";
+	return {
+		ids: [...requirementIds, ...unreferencedTaskIds],
+		basis
+	};
+};
+//#endregion
+//#region src/review-ledger/review-ledger.schema.ts
+const prose = z.string().trim().min(1);
+const criterionId = z.string().regex(CRITERION_ID);
+const criterionSchema = z.object({
+	id: criterionId,
+	evidence: prose
+}).strict();
+const gateSchema = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("script"),
+	script: prose,
+	evidence: prose
+}).strict(), z.object({
+	kind: z.literal("real-run"),
+	evidence: prose
+}).strict()]);
+const probeSchema = z.object({
+	mutation: prose,
+	outcome: z.enum(MUTANT_OUTCOMES),
+	killedBy: prose.optional()
+}).strict();
+const mutantFileSchema = z.discriminatedUnion("status", [z.object({
+	file: prose,
+	status: z.literal("probed"),
+	probes: z.array(probeSchema).min(1)
+}).strict(), z.object({
+	file: prose,
+	status: z.literal("not-applicable"),
+	reason: z.enum(NOT_APPLICABLE_REASONS),
+	note: prose
+}).strict()]);
+const mutantsSchema = z.discriminatedUnion("basis", [z.object({ basis: z.literal("no-declared-risk") }).strict(), z.object({
+	basis: z.literal("declared-risk"),
+	files: z.array(mutantFileSchema)
+}).strict()]);
+const ledgerStepSchema = z.union([z.int().min(1), z.literal(FULL_PASS_STEP)]);
+const reviewLedgerSchema = z.object({
+	version: z.literal(1),
+	step: ledgerStepSchema,
+	criteria: z.array(criterionSchema),
+	gates: z.array(gateSchema),
+	mutants: mutantsSchema
+}).strict();
+//#endregion
+//#region src/review-ledger/validate-ledger.ts
+const runLedgerValidate = async (inputs) => {
+	const { address } = inputs;
+	const problems = [];
+	const taskRel = join(TASKS_DIR, inputs.taskId);
+	const tasksRel = join(taskRel, "spec", "tasks.md");
+	const requirementsPath = join(inputs.repoRoot, taskRel, "spec", "requirements.md");
+	const ledgerPath = reviewLedgerPath(inputs.taskId, address);
+	const owedFiles = await collectOwedFiles(inputs);
+	const declaredGates = await collectDeclaredGates(inputs.repoRoot);
+	const result = {
+		ok: false,
+		address,
+		ledgerPath,
+		criteria: {
+			required: [],
+			present: []
+		},
+		gates: owedGates(declaredGates),
+		unknownRiskClasses: [],
+		problems
+	};
+	if (!await pathExists(join(inputs.repoRoot, tasksRel))) {
+		problems.push({
+			kind: "spec-missing",
+			message: `No ${tasksRel} — the criteria class is enumerated from the spec's groups, so there is nothing to validate against.`
+		});
+		return result;
+	}
+	const spec = parseTasksSpec(await readFile(join(inputs.repoRoot, tasksRel), "utf8"));
+	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.`,
+		subject: String(index)
+	});
+	if (spec.orphanTaskIds.length > 0) problems.push({
+		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 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 id of spec.malformedTaskRefs) problems.push({
+		kind: "malformed-task-refs",
+		message: `${id} carries a "(R<n>"-shaped tail that is not a well-formed "(R1, R2)" ref list. 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);
+	if (groups === void 0) return result;
+	if (address.kind === "step") result.groupHeader = groups[0]?.header;
+	for (const group of groups) {
+		if (group.tasks.length === 0) problems.push({
+			kind: "group-empty",
+			message: `Group ${group.index} carries no tasks — an empty group is a broken spec, not a trivial step.`,
+			subject: group.header
+		});
+		for (const unknown of group.unknownRiskClasses) {
+			if (!result.unknownRiskClasses.includes(unknown)) result.unknownRiskClasses.push(unknown);
+			problems.push({
+				kind: "unknown-risk-class",
+				message: `Group ${group.index} declares risk class "${unknown}", which is not in the vocabulary. A class outside it is either a typo or a surface that has not earned a name yet — both are spec defects, and neither is the Reviewer's to fix.`,
+				subject: unknown
+			});
+		}
+	}
+	const slice = sliceForGroups(groups);
+	result.basis = slice.basis;
+	const dangling = await collectDanglingRefs(requirementsPath, slice.ids, problems);
+	const required = slice.ids.filter((id) => !dangling.includes(id));
+	result.criteria = {
+		required,
+		present: []
+	};
+	const ledger = await readLedger(join(inputs.repoRoot, ledgerPath), ledgerPath, problems);
+	if (ledger === void 0) return result;
+	checkAddress(ledger, address, ledgerPath, problems);
+	result.criteria = checkCriteria(required, dangling, ledger, problems);
+	result.gates = checkGates(ledger, result.gates, problems);
+	checkMutantsBasis(ledger, groups, ledgerPath, problems);
+	checkMutantsFloor(ledger, owedFiles, inputs.anchor, problems);
+	result.ok = problems.length === 0;
+	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 resolveGroups = (groups, address, problems) => {
+	if (address.kind === "full-pass") {
+		if (groups.length > 0) return groups;
+		problems.push({
+			kind: "group-missing",
+			message: `tasks.md declares no group and no task, so the full pass has no slice to validate against.`
+		});
+		return;
+	}
+	const group = groups.find((candidate) => candidate.index === address.step);
+	if (group) return [group];
+	problems.push({
+		kind: "group-missing",
+		message: `tasks.md declares ${groups.length} group(s); step ${address.step} has none. One step is one group.`
+	});
+};
+const collectDanglingRefs = async (requirementsPath, sliceIds, problems) => {
+	const referenced = sliceIds.filter((id) => id.startsWith("R"));
+	if (referenced.length === 0) return [];
+	if (!await pathExists(requirementsPath)) {
+		problems.push({
+			kind: "dangling-requirement-ref",
+			message: `The slice references ${referenced.join(", ")} but there is no requirements.md to resolve them against.`
+		});
+		return referenced;
+	}
+	const declared = parseRequirementIds(await readFile(requirementsPath, "utf8"));
+	const dangling = referenced.filter((id) => !declared.includes(id));
+	for (const id of dangling) problems.push({
+		kind: "dangling-requirement-ref",
+		message: `The slice references ${id}, which requirements.md does not declare.`,
+		subject: id
+	});
+	return dangling;
+};
+const readLedger = async (absolutePath, ledgerPath, problems) => {
+	if (!await pathExists(absolutePath)) {
+		problems.push({
+			kind: "ledger-missing",
+			message: `No ${ledgerPath} — the Reviewer writes it beside its verdict; an APPROVE without a ledger is structurally invalid.`
+		});
+		return;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(absolutePath, "utf8"));
+	} catch (error) {
+		problems.push({
+			kind: "ledger-unparseable",
+			message: `${ledgerPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}.`
+		});
+		return;
+	}
+	const checked = reviewLedgerSchema.safeParse(parsed);
+	if (checked.success) return checked.data;
+	for (const issue of checked.error.issues) {
+		const at = formatPath(issue.path);
+		problems.push({
+			kind: "ledger-shape",
+			message: `${ledgerPath} does not match the schema at ${at || "<root>"}: ${issue.message}.`,
+			subject: at || void 0
+		});
+	}
+};
+const formatPath = (path) => path.map((segment) => typeof segment === "number" ? `[${segment}]` : `.${String(segment)}`).join("").replace(/^\./, "");
+const checkAddress = (ledger, address, ledgerPath, problems) => {
+	const expected = address.kind === "full-pass" ? FULL_PASS_STEP : address.step;
+	if (ledger.step === expected) return;
+	problems.push({
+		kind: "ledger-address-mismatch",
+		message: `${ledgerPath} declares "step": ${JSON.stringify(ledger.step)} but was addressed as ${JSON.stringify(expected)}.`,
+		subject: String(ledger.step)
+	});
+};
+const checkMutantsBasis = (ledger, groups, ledgerPath, problems) => {
+	const declared = groups.filter((group) => group.riskClasses.length > 0);
+	if (declared.length === 0 || ledger.mutants.basis === "declared-risk") return;
+	problems.push({
+		kind: "mutants-basis-mismatch",
+		message: `${ledgerPath} says "mutants": {"basis": "no-declared-risk"} but ${declared.map((group) => `Group ${group.index}`).join(", ")} declares [risk: ${[...new Set(declared.flatMap((group) => group.riskClasses))].join(", ")}] — the record must carry "basis": "declared-risk" with its files.`,
+		subject: ledger.mutants.basis
+	});
+};
+const gitFailureDetail = (result, verb) => result.stderr.trim().split("\n")[0] || `git ${verb} exited ${result.code}`;
+const collectOwedFiles = async (inputs) => {
+	const resolved = await inputs.runCommand("git", [
+		"-C",
+		inputs.repoRoot,
+		"rev-parse",
+		"--verify",
+		"--end-of-options",
+		`${inputs.anchor}^{commit}`
+	]);
+	if (resolved.code !== 0) throw new Error(`Invalid --anchor="${inputs.anchor}": ${gitFailureDetail(resolved, "rev-parse")}`);
+	const oid = resolved.stdout.trim();
+	const listChanged = async (cached) => {
+		const diff = await inputs.runCommand("git", [
+			"-C",
+			inputs.repoRoot,
+			"diff",
+			...cached ? ["--cached"] : [],
+			"--name-only",
+			"-z",
+			"--diff-filter=d",
+			oid,
+			"--",
+			":(exclude).claude/state"
+		]);
+		if (diff.code !== 0) throw new Error(`git diff against --anchor="${inputs.anchor}" failed: ${gitFailureDetail(diff, "diff")}`);
+		return diff.stdout.split("\0").filter((file) => file.length > 0);
+	};
+	const worktree = await listChanged(false);
+	const staged = await listChanged(true);
+	return [.../* @__PURE__ */ new Set([...worktree, ...staged])].filter((file) => !TEST_FILE.test(file));
+};
+const checkMutantsFloor = (ledger, owedFiles, anchor, problems) => {
+	if (ledger.mutants.basis !== "declared-risk") return;
+	const recorded = new Set(ledger.mutants.files.map((entry) => entry.file));
+	for (const file of owedFiles) {
+		if (recorded.has(file)) continue;
+		problems.push({
+			kind: "unaccounted-file",
+			message: `${file} changed in the diff against ${anchor} and has no "mutants"."files" entry — probe it, or record it as "not-applicable" with its reason and note.`,
+			subject: file
+		});
+	}
+};
+const collectDeclaredGates = async (repoRoot) => {
+	if (!await configEntryExists(join(repoRoot, "harness.config.yml"))) return;
+	return (await readHarnessConfig(repoRoot)).gates;
+};
+const configEntryExists = async (path) => {
+	try {
+		await lstat(path);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+};
+const owedGates = (declared) => ({
+	basis: declared === void 0 ? "undeclared" : "config",
+	required: [...new Set(declared ?? [])],
+	present: []
+});
+const checkGates = (ledger, owed, problems) => {
+	const attested = new Set(ledger.gates.filter((gate) => gate.kind === "script").map((gate) => gate.script));
+	for (const name of owed.required) {
+		if (attested.has(name)) continue;
+		problems.push({
+			kind: "gate-unattested",
+			message: `${HARNESS_CONFIG_FILENAME} declares gate "${name}" and the ledger has no {"kind": "script", "script": "${name}"} entry — run it and record what came out (a gate that failed, or no longer exists, is still attested, with evidence saying so).`,
+			subject: name
+		});
+	}
+	if (!ledger.gates.some((gate) => gate.kind === "real-run")) problems.push({
+		kind: "real-run-missing",
+		message: `The ledger has no {"kind": "real-run"} entry — the real run is the floor every review owes, declared gates or none.`
+	});
+	return {
+		...owed,
+		present: owed.required.filter((name) => attested.has(name))
+	};
+};
+const checkCriteria = (required, dangling, ledger, problems) => {
+	const present = [];
+	for (const entry of ledger.criteria) {
+		if (dangling.includes(entry.id)) continue;
+		if (!required.includes(entry.id)) {
+			problems.push({
+				kind: "criteria-unexpected",
+				message: `"${entry.id}" is not in the slice (${required.join(", ") || "empty"}). An entry for something the review does not cover is not evidence.`,
+				subject: entry.id
+			});
+			continue;
+		}
+		if (present.includes(entry.id)) {
+			problems.push({
+				kind: "criteria-duplicated",
+				message: `${entry.id} has more than one entry; one criterion, one entry.`,
+				subject: entry.id
+			});
+			continue;
+		}
+		present.push(entry.id);
+	}
+	for (const id of required) {
+		if (present.includes(id)) continue;
+		problems.push({
+			kind: "criteria-missing",
+			message: `${id} is in the slice and has no criteria entry.`,
+			subject: id
+		});
+	}
+	return {
+		required,
+		present
+	};
+};
+//#endregion
 //#region src/spinoff/spinoff.constant.ts
 const MANAGED_LABEL = "harness:managed";
 const PENDING_STATUS_LABEL = "harness:status:pending";
@@ -2810,7 +3383,6 @@ const inspectDevDependency = async (repoRoot) => {
 //#endregion
 //#region src/scan/scan.constant.ts
 const ARCHITECTURE_DOC_PATH = "docs/architecture.md";
-const MUTATION_SCRIPT_NAME = "test:mutation";
 //#endregion
 //#region src/scan/scan.ts
 const ORIGIN_URL = /\[remote "origin"\][^[]*?url\s*=\s*(\S+)/;
@@ -2831,23 +3403,14 @@ const readOriginSlug = async (root) => {
 		return null;
 	}
 };
-const hasMutationScript = async (root) => {
-	try {
-		const script = JSON.parse(await readFile(join(root, "package.json"), "utf8")).scripts?.[MUTATION_SCRIPT_NAME];
-		return typeof script === "string" && script.trim().length > 0;
-	} catch {
-		return false;
-	}
-};
 const scanRepo = async (root) => {
-	const [isGitRepo, hasClaudeMd, hasContextMd, hasDocs, hasPackageJson, hasArchitectureDoc, hasMutationTesting] = await Promise.all([
+	const [isGitRepo, hasClaudeMd, hasContextMd, hasDocs, hasPackageJson, hasArchitectureDoc] = await Promise.all([
 		pathExists(join(root, ".git")),
 		pathExists(join(root, "CLAUDE.md")),
 		pathExists(join(root, "CONTEXT.md")),
 		pathExists(join(root, "docs")),
 		pathExists(join(root, "package.json")),
-		pathExists(join(root, ARCHITECTURE_DOC_PATH)),
-		hasMutationScript(root)
+		pathExists(join(root, ARCHITECTURE_DOC_PATH))
 	]);
 	return {
 		isGitRepo,
@@ -2856,8 +3419,7 @@ const scanRepo = async (root) => {
 		hasContextMd,
 		hasDocs,
 		hasPackageJson,
-		hasArchitectureDoc,
-		hasMutationTesting
+		hasArchitectureDoc
 	};
 };
 //#endregion
@@ -2899,18 +3461,11 @@ const PHASES = [
 ];
 //#endregion
 //#region src/skills/skills.ts
-const CAPABILITY_REGISTRY = {
-	"has-architecture-doc": {
-		predicate: (caps) => caps.hasArchitectureDoc,
-		trigger: ARCHITECTURE_DOC_PATH,
-		label: "keep your architecture map current"
-	},
-	"has-mutation-testing": {
-		predicate: (caps) => caps.hasMutationTesting,
-		trigger: `a \`${MUTATION_SCRIPT_NAME}\` package.json script`,
-		label: "check test strength with mutation testing in review"
-	}
-};
+const CAPABILITY_REGISTRY = { "has-architecture-doc": {
+	predicate: (caps) => caps.hasArchitectureDoc,
+	trigger: ARCHITECTURE_DOC_PATH,
+	label: "keep your architecture map current"
+} };
 const capabilityHolds = (key, caps) => {
 	const entry = CAPABILITY_REGISTRY[key];
 	if (!entry) throw new Error(`unknown applies-when capability key "${key}"`);
@@ -3033,6 +3588,7 @@ const runDoctor = async (deps) => {
 	checks.push(await checkCliResolution(deps));
 	checks.push(await checkCapabilities(deps, config));
 	checks.push(await checkDesignToolDrift(deps));
+	checks.push(await checkHookLib(deps));
 	return {
 		checks,
 		ok: checks.every((check) => check.status !== "fail")
@@ -3301,6 +3857,91 @@ const checkDesignToolDrift = async (deps) => {
 		};
 	}
 };
+const checkHookLib = async (deps) => {
+	const name = "hook-lib";
+	let helpers;
+	try {
+		helpers = (await listFiles(join(deps.vendorRoot, "hooks", "lib"))).filter((rel) => rel.endsWith(".sh")).toSorted();
+	} catch (error) {
+		return {
+			name,
+			status: "warn",
+			detail: `Could not read the vendor catalog's hook lib helpers: ${error.message}`,
+			remediation: "Reinstall the harness package, then re-run `lemony doctor`."
+		};
+	}
+	if (helpers.length === 0) return {
+		name,
+		status: "warn",
+		detail: "The vendor catalog ships no hook lib helpers — the installed package looks damaged.",
+		remediation: "Reinstall the harness package, then re-run `lemony doctor`."
+	};
+	const problems = (await Promise.all(helpers.map(async (helper) => {
+		const installed = join(deps.repoRoot, HOOKS_DIR, "lib", helper);
+		let installedStat;
+		try {
+			installedStat = await stat(installed);
+		} catch (error) {
+			const code = error.code;
+			if (await lstat(installed).then(() => true, () => false)) return {
+				helper,
+				kind: "obstructed",
+				description: `${helper} is an unresolvable symlink (${code ?? "unknown error"})`
+			};
+			if (code === "ENOENT" || code === "ENOTDIR") return {
+				helper,
+				kind: "missing",
+				description: `${helper} is missing`
+			};
+			return {
+				helper,
+				kind: "unreadable",
+				description: `${helper} is unreadable (${code ?? "unknown error"})`
+			};
+		}
+		if (!installedStat.isFile()) return {
+			helper,
+			kind: "obstructed",
+			description: `${helper} is not a regular file`
+		};
+		if (!await isExecutable(installed)) return {
+			helper,
+			kind: "mode",
+			description: `${helper} is not executable`
+		};
+		if (!await isReadable(installed)) return {
+			helper,
+			kind: "mode",
+			description: `${helper} is not readable`
+		};
+		return null;
+	}))).filter((problem) => problem !== null);
+	if (problems.length === 0) return {
+		name,
+		status: "ok",
+		detail: `All ${helpers.length} hook lib helpers installed with read+exec permission in ${HOOKS_DIR}/lib.`
+	};
+	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\``);
+	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("; ")}.`
+	};
+};
+const isReadable = async (path) => {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
 //#endregion
 //#region src/status/status.ts
 const PAUSED_LABEL = "harness:status:paused-for-clarification";
@@ -3421,7 +4062,7 @@ const COMMANDS = [
 	},
 	{
 		name: "discovery",
-		summary: "Reflect a raised/resolved discovery onto its issue (label flip + comment); used by the Orchestrator's resolve-discovery skill.",
+		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>]"
 	},
 	{
@@ -3429,6 +4070,11 @@ const COMMANDS = [
 		summary: "Validate the 3-tier design-token file (and gate UI source against hardcoded values), check WCAG contrast of token pairs, or sync tokens with a design tool (consume-if-exists; never created).",
 		usage: "lemony design-tokens <validate [--scan=<dir>] | contrast | import --from=<file> [--apply] [--only=<paths>] | export [--tool-state=<file>] [--out=<file>] [--record]>"
 	},
+	{
+		name: "review-ledger",
+		summary: "Validate the Reviewer's evidence ledger (the JSON sidecar under the task's state) against the spec's groups, the anchored diff and the declared gates: shape, criteria-vs-slice, unknown risk classes, the mutant floor, the gates floor (deterministic, agent-free; exits non-zero on an invalid ledger).",
+		usage: "lemony review-ledger validate --task-id=<id> --anchor=<oid> (--step=<N> | --full-pass)"
+	},
 	{
 		name: "spinoff",
 		summary: "Capture a non-blocking defect found mid-task as a pending stub (+ followup_captured event); used by the /spinoff command.",
@@ -3437,7 +4083,7 @@ 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|disable|enable> [--purge-local]"
+		usage: "lemony telemetry <status|show|flush|enable|disable [--purge-local]>"
 	}
 ];
 //#endregion
@@ -3930,6 +4576,13 @@ const CORE_AGENTS = [
 	"architect",
 	"ui-designer"
 ];
+const COMPANION_DOCS = [
+	"fit-assessment",
+	"triage",
+	"spinoff",
+	"ui-design",
+	"partition"
+];
 const renderFile = async (templatePath, relPath, vars) => {
 	return {
 		relPath,
@@ -3955,7 +4608,7 @@ const materializeVendorFiles = async (ctx) => {
 		SKILLS: renderRoleSkills(skills, role),
 		vendor_version: vendorVersion
 	}), vendorVersion)));
-	const fitAssessment = await copyFileEntry(join(vendorRoot, "agents", "fit-assessment.md"), join(AGENTS_DIR, "fit-assessment.md"));
+	const companionFiles = await Promise.all(COMPANION_DOCS.map((doc) => copyFileEntry(join(vendorRoot, "agents", `${doc}.md`), join(AGENTS_DIR, `${doc}.md`))));
 	const skillFiles = (await Promise.all(skills.map(async (skill) => {
 		const skillDir = join(vendorRoot, "skills", skill.name);
 		const rels = await listFiles(skillDir);
@@ -3972,7 +4625,7 @@ const materializeVendorFiles = async (ctx) => {
 	return [
 		entryProtocol,
 		...agentFiles,
-		fitAssessment,
+		...companionFiles,
 		...skillFiles,
 		playbooksReadme,
 		...hookFiles,
@@ -4268,6 +4921,7 @@ const runReconcile = async (inputs) => {
 	const fromVersion = config.vendor_version;
 	const target = config.target;
 	const taskStorageRepo = config.task_storage.repo;
+	const predatedKeys = findPredatedKeys(await readFile(join(repoRoot, HARNESS_CONFIG_FILENAME), "utf8"), fromVersion, toVersion, inputs.configKeySince ?? CONFIG_KEY_SINCE);
 	const baselineVersion = await findBaselineVersion(repoRoot);
 	const baseline = baselineVersion ? await readBaseline(repoRoot, baselineVersion) : /* @__PURE__ */ new Map();
 	const hadBaseline = baseline.size > 0;
@@ -4304,7 +4958,8 @@ const runReconcile = async (inputs) => {
 		hadBaseline,
 		...summarize(actions),
 		labelSync: null,
-		lostHookCommands: []
+		lostHookCommands: [],
+		predatedKeys
 	};
 	if (hadBaseline) {
 		await writeSnapshot(repoRoot, fromVersion, {
@@ -4322,7 +4977,8 @@ const runReconcile = async (inputs) => {
 		hadBaseline,
 		...summarize(actions),
 		labelSync,
-		lostHookCommands
+		lostHookCommands,
+		predatedKeys
 	};
 };
 const refuseOnResidualMarkers = async (relPaths, readClient) => {
@@ -4848,6 +5504,7 @@ const update = async (args) => {
 	const versionLine = result.fromVersion === result.toVersion ? `Lemony ${verb("re-synced", "would re-sync")} at ${result.toVersion}` : `Lemony ${verb("updated", "would update")} ${result.fromVersion} → ${result.toVersion}`;
 	console.log(`${versionLine}${result.hadBaseline ? "" : " (no baseline — pick-one degrade)"}${suffix}.`);
 	console.log(`  ${verb("merged", "would merge")} ${result.mergedFiles.length}, ${verb("added", "would add")} ${result.addedFiles.length}, ${verb("pruned", "would prune")} ${result.prunedFiles.length}, ${verb("adopted", "would adopt")} ${result.adoptedFiles.length}.`);
+	for (const key of result.predatedKeys) console.log(formatPredatedKeyLine(key));
 	for (const { relPath, winner } of result.pickedFiles) console.log(`  ${verb("picked", "would pick")} ${winner} for ${relPath} (no baseline).`);
 	reportAdoptions(result.adoptedFiles, verb("adopted", "would adopt"));
 	reportConflicts(result.conflictedFiles, dryRun ? "Run `lemony update` without --dry-run to write them; resolve the <<<<<<< / ======= / >>>>>>> markers afterward." : "Resolve the <<<<<<< / ======= / >>>>>>> markers; the next update refuses until they are gone.");
@@ -4997,7 +5654,7 @@ const runTelemetry = async (args) => {
 		case "send":
 			await telemetrySend(repoRoot);
 			return;
-		default: throw new Error(`Usage: lemony telemetry <status|show|flush|disable|enable>. Unknown action "${action}".`);
+		default: throw new Error(`Usage: lemony telemetry <status|show|flush|enable|disable [--purge-local]>. Unknown action "${action}".`);
 	}
 };
 const telemetryStatus = async (repoRoot) => {
@@ -5172,6 +5829,53 @@ const designTokensExport = async (args) => {
 	console.log(`design-tokens export plan: ${creates} to create, ${updates} to update (tool-only variables are never deleted).`);
 	if (out !== void 0) console.log(`  projection written to ${out}`);
 };
+const REVIEW_LEDGER_USAGE = "Usage: lemony review-ledger validate --task-id=<id> --anchor=<oid> (--step=<N> | --full-pass).";
+const reviewLedger = async (args) => {
+	const action = args[0] ?? "validate";
+	if (action === "validate") return reviewLedgerValidate(args);
+	throw new Error(`${REVIEW_LEDGER_USAGE} Unknown action "${action}".`);
+};
+const reviewLedgerValidate = async (args) => {
+	const taskId = parseFlag(args, "task-id");
+	if (taskId === void 0) throw new Error(`${REVIEW_LEDGER_USAGE} --task-id is required.`);
+	if (taskId !== basename(taskId) || taskId === "." || taskId === "..") throw new Error(`Invalid --task-id="${taskId}": a task id names one directory under the task state, never a path.`);
+	const anchor = parseFlag(args, "anchor");
+	if (anchor === void 0) throw new Error(`${REVIEW_LEDGER_USAGE} --anchor is required — the group's recorded head OID on a step, the fingerprint merge-base on a full pass (pre-commit review ON's pre-gate pass anchors at the recorded group anchor instead); the owed set of the mutant floor is the diff from it.`);
+	const address = parseLedgerAddress(args);
+	const result = await runLedgerValidate({
+		repoRoot: cwd(),
+		taskId,
+		address,
+		anchor,
+		runCommand: makeRunCommand()
+	});
+	const where = address.kind === "full-pass" ? "full pass" : `step ${address.step}`;
+	const counts = `${result.basis === void 0 ? "no slice enumerated" : `criteria ${result.criteria.present.length}/${result.criteria.required.length} (basis: ${result.basis})`}, gates ${result.gates.present.length}/${result.gates.required.length} (basis: ${result.gates.basis})`;
+	if (address.kind === "step" && result.groupHeader !== void 0) console.log(`Step ${address.step} → ${result.groupHeader}`);
+	if (result.ok) {
+		console.log(`Ledger valid for ${where} (${result.ledgerPath}). ${counts}`);
+		return;
+	}
+	console.error(`Ledger invalid for ${where} (${result.ledgerPath}): ${result.problems.length} problem(s). ${counts}`);
+	for (const problem of result.problems) console.error(`  [${problem.kind}] ${problem.message}`);
+	const specSide = result.problems.filter((problem) => SPEC_SIDE_KINDS.includes(problem.kind)).length;
+	if (specSide > 0) console.error(`  ${specSide} spec-side problem(s) (tasks.md / requirements.md / the address) — not the Reviewer's to fix; do not retry the Reviewer while any of these stands.`);
+	exit(1);
+};
+const parseLedgerAddress = (args) => {
+	const step = parseFlag(args, "step");
+	const fullPass = args.includes("--full-pass");
+	if (args.some((arg) => arg.startsWith("--full-pass="))) throw new Error(`${REVIEW_LEDGER_USAGE} --full-pass takes no value.`);
+	if (fullPass && step !== void 0) throw new Error(`${REVIEW_LEDGER_USAGE} --step and --full-pass are mutually exclusive.`);
+	if (fullPass) return { kind: "full-pass" };
+	if (step === void 0) throw new Error(`${REVIEW_LEDGER_USAGE} One of --step or --full-pass is required.`);
+	const stepNumber = Number(step);
+	if (!/^[1-9]\d*$/.test(step) || !Number.isSafeInteger(stepNumber)) throw new Error(`Invalid --step="${step}": a step is the 1-based index of a tasks.md group.`);
+	return {
+		kind: "step",
+		step: stepNumber
+	};
+};
 const spinoff = async (args) => {
 	const harnessVersion = await readHarnessVersion();
 	const result = await runSpinoff({
@@ -5301,6 +6005,9 @@ const main = async () => {
 		case "design-tokens":
 			await designTokens(args);
 			return;
+		case "review-ledger":
+			await reviewLedger(args);
+			return;
 		case "spinoff":
 			await spinoff(args);
 			return;