@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/commands/doctor.ts

@@ -0,0 +1,1113 @@
+import { existsSync } from "node:fs";
+import { writeFile as fsWriteFile, readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getRegistry, type TypeDefinition } from "../registry/type-registry.ts";
+import { type LoamConfig, validateAnchorValidityConfig } from "../schemas/config.ts";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import {
+	getExpertiseDir,
+	getExpertisePath,
+	getLoamDir,
+	readConfig,
+	writeConfig,
+} from "../utils/config.ts";
+import {
+	findIncompatibleRequiredFields,
+	findMissingDomainFields,
+	getAllowedTypes,
+	getRequiredFields,
+} from "../utils/domain-rules.ts";
+import {
+	applyAliases,
+	createExpertiseFile,
+	findDuplicate,
+	readExpertiseFile,
+	writeExpertiseFile,
+} from "../utils/expertise.ts";
+import { outputJson } from "../utils/json-output.ts";
+import { withFileLock } from "../utils/lock.ts";
+import { brand, icons, isQuiet } from "../utils/palette.ts";
+import { compareSemver, getCurrentVersion, getLatestVersion } from "../utils/version.ts";
+import { isStale } from "./prune.ts";
+
+interface DoctorCheck {
+	name: string;
+	status: "pass" | "warn" | "fail";
+	message: string;
+	fixable: boolean;
+	details: string[];
+}
+
+async function checkConfig(cwd?: string): Promise<DoctorCheck> {
+	try {
+		const loamDir = getLoamDir(cwd);
+		if (!existsSync(loamDir)) {
+			return {
+				name: "config",
+				status: "fail",
+				message: "No .loam/ directory found",
+				fixable: false,
+				details: [],
+			};
+		}
+		await readConfig(cwd);
+		return {
+			name: "config",
+			status: "pass",
+			message: "Config is valid",
+			fixable: false,
+			details: [],
+		};
+	} catch (err) {
+		return {
+			name: "config",
+			status: "fail",
+			message: `Config error: ${(err as Error).message}`,
+			fixable: false,
+			details: [],
+		};
+	}
+}
+
+async function checkJsonlIntegrity(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const details: string[] = [];
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		let content: string;
+		try {
+			content = await readFile(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const lines = content.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const line = (lines[i] ?? "").trim();
+			if (line.length === 0) continue;
+			try {
+				JSON.parse(line);
+			} catch {
+				details.push(`${domain}:${i + 1} - Invalid JSON`);
+			}
+		}
+	}
+	if (details.length > 0) {
+		return {
+			name: "jsonl-integrity",
+			status: "fail",
+			message: `${details.length} invalid JSON line(s) found`,
+			fixable: true,
+			details,
+		};
+	}
+	return {
+		name: "jsonl-integrity",
+		status: "pass",
+		message: "All JSONL lines are valid JSON",
+		fixable: true,
+		details: [],
+	};
+}
+
+async function checkSchemaValidation(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const registry = getRegistry();
+	const validate = registry.validator;
+	const details: string[] = [];
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		let content: string;
+		try {
+			content = await readFile(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const lines = content.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const line = (lines[i] ?? "").trim();
+			if (line.length === 0) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				continue; // Already caught by integrity check
+			}
+			// Skip records of unregistered types — checkUnknownTypes flags those
+			// with a clearer message. Otherwise Ajv reports a noisy "no oneOf
+			// matched" for the same record. Apply aliases before Ajv so a
+			// record with a legacy field name (post-rename) validates cleanly.
+			if (parsed && typeof parsed === "object" && "type" in parsed) {
+				const t = (parsed as { type: unknown }).type;
+				if (typeof t === "string") {
+					const def = registry.get(t);
+					if (!def) continue;
+					if (def.aliases) applyAliases(parsed as Record<string, unknown>, def.aliases);
+				}
+			}
+			if (!validate(parsed)) {
+				const errors = (validate.errors ?? [])
+					.map((e) => `${e.instancePath} ${e.message}`)
+					.join("; ");
+				details.push(`${domain}:${i + 1} - ${errors}`);
+			}
+		}
+	}
+	if (details.length > 0) {
+		return {
+			name: "schema-validation",
+			status: "fail",
+			message: `${details.length} record(s) failed schema validation`,
+			fixable: true,
+			details,
+		};
+	}
+	return {
+		name: "schema-validation",
+		status: "pass",
+		message: "All records pass schema validation",
+		fixable: true,
+		details: [],
+	};
+}
+
+async function checkStaleRecords(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const now = new Date();
+	const shelfLife = config.classification_defaults.shelf_life;
+	const details: string[] = [];
+	let staleCount = 0;
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+		for (const record of records) {
+			if (isStale(record, now, shelfLife)) {
+				staleCount++;
+				details.push(`${domain}: stale ${record.type} (${record.classification})`);
+			}
+		}
+	}
+	if (staleCount > 0) {
+		return {
+			name: "stale-records",
+			status: "warn",
+			message: `${staleCount} stale record(s) found`,
+			fixable: true,
+			details,
+		};
+	}
+	return {
+		name: "stale-records",
+		status: "pass",
+		message: "No stale records",
+		fixable: true,
+		details: [],
+	};
+}
+
+async function checkTypeRegistry(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const registry = getRegistry();
+	const builtinDefs = registry.builtinDefs();
+	const customDefs = registry.customDefs();
+	const disabledNames = new Set(registry.disabledNames());
+
+	// Bucket records by type across all domains.
+	const counts: Record<string, number> = {};
+	for (const def of registry.enabled()) counts[def.name] = 0;
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		// allowUnknownTypes here so this informational check never throws on
+		// pre-existing unknown types (checkUnknownTypes flags them separately).
+		const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+		for (const r of records) {
+			if (counts[r.type] !== undefined) counts[r.type] = (counts[r.type] ?? 0) + 1;
+		}
+	}
+
+	const fmt = (def: TypeDefinition): string => {
+		const labels: string[] = [def.kind === "builtin" ? "built-in" : "custom"];
+		if (disabledNames.has(def.name)) labels.push("disabled");
+		const count = counts[def.name] ?? 0;
+		return `${def.name} (${labels.join(", ")}): ${count} record${count === 1 ? "" : "s"}`;
+	};
+
+	const details = [...builtinDefs.map(fmt), ...customDefs.map(fmt)];
+	const total = builtinDefs.length + customDefs.length;
+	const disabledCount = disabledNames.size;
+	const message =
+		`${total} type(s) registered: ${builtinDefs.length} built-in, ${customDefs.length} custom` +
+		(disabledCount > 0 ? `, ${disabledCount} disabled` : "");
+
+	return {
+		name: "type-registry",
+		status: "pass",
+		message,
+		fixable: false,
+		details,
+	};
+}
+
+async function checkUnknownTypes(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const registry = getRegistry();
+	const details: string[] = [];
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		let content: string;
+		try {
+			content = await readFile(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const lines = content.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const line = (lines[i] ?? "").trim();
+			if (line.length === 0) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				continue; // covered by jsonl-integrity check
+			}
+			if (parsed && typeof parsed === "object" && "type" in parsed) {
+				const t = (parsed as { type: unknown }).type;
+				if (typeof t === "string" && !registry.get(t)) {
+					const id = (parsed as { id?: unknown }).id;
+					const idPart = typeof id === "string" ? ` [${id}]` : "";
+					details.push(`${domain}:${i + 1}${idPart} - unknown type "${t}"`);
+				}
+			}
+		}
+	}
+
+	if (details.length > 0) {
+		return {
+			name: "unknown-types",
+			status: "fail",
+			message: `${details.length} record(s) with unregistered types`,
+			fixable: false,
+			details,
+		};
+	}
+	return {
+		name: "unknown-types",
+		status: "pass",
+		message: "All record types are registered",
+		fixable: false,
+		details: [],
+	};
+}
+
+async function checkOrphanedDomains(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const expertiseDir = getExpertiseDir(cwd);
+	const details: string[] = [];
+
+	// Check for JSONL files not in config
+	try {
+		const files = await readdir(expertiseDir);
+		for (const file of files) {
+			if (file.endsWith(".jsonl")) {
+				const domain = file.replace(".jsonl", "");
+				if (!(domain in config.domains)) {
+					details.push(`File "${file}" exists but domain "${domain}" is not in config`);
+				}
+			}
+		}
+	} catch {
+		// expertise dir doesn't exist
+	}
+
+	// Check for config domains without JSONL files
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		if (!existsSync(filePath)) {
+			details.push(`Domain "${domain}" in config but no JSONL file exists`);
+		}
+	}
+
+	if (details.length > 0) {
+		return {
+			name: "orphaned-domains",
+			status: "warn",
+			message: `${details.length} orphaned domain issue(s)`,
+			fixable: true,
+			details,
+		};
+	}
+	return {
+		name: "orphaned-domains",
+		status: "pass",
+		message: "No orphaned domains",
+		fixable: true,
+		details: [],
+	};
+}
+
+async function checkDuplicates(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const details: string[] = [];
+	let dupCount = 0;
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+		for (let i = 1; i < records.length; i++) {
+			const rec = records[i];
+			if (!rec) continue;
+			const dup = findDuplicate(records.slice(0, i), rec);
+			if (dup) {
+				dupCount++;
+				details.push(
+					`${domain}: duplicate ${rec.type} at index ${i + 1} (matches #${dup.index + 1})`,
+				);
+			}
+		}
+	}
+	if (dupCount > 0) {
+		return {
+			name: "duplicates",
+			status: "warn",
+			message: `${dupCount} duplicate record(s) found`,
+			fixable: false,
+			details,
+		};
+	}
+	return {
+		name: "duplicates",
+		status: "pass",
+		message: "No duplicates",
+		fixable: false,
+		details: [],
+	};
+}
+
+async function checkLegacyOutcome(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const details: string[] = [];
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		let content: string;
+		try {
+			content = await readFile(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const lines = content.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const line = (lines[i] ?? "").trim();
+			if (line.length === 0) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (
+				parsed !== null &&
+				typeof parsed === "object" &&
+				"outcome" in parsed &&
+				!("outcomes" in parsed)
+			) {
+				details.push(
+					`${domain}:${i + 1} - legacy "outcome" field (singular); should be "outcomes[]"`,
+				);
+			}
+		}
+	}
+
+	if (details.length > 0) {
+		return {
+			name: "legacy-outcome",
+			status: "warn",
+			message: `${details.length} record(s) with legacy "outcome" field on disk`,
+			fixable: true,
+			details,
+		};
+	}
+	return {
+		name: "legacy-outcome",
+		status: "pass",
+		message: 'No legacy "outcome" fields on disk',
+		fixable: true,
+		details: [],
+	};
+}
+
+async function checkFileAnchors(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const projectRoot = cwd ?? process.cwd();
+	const details: string[] = [];
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+		for (const record of records) {
+			const id = record.id ? `[${record.id}]` : "";
+			if ("files" in record && Array.isArray(record.files)) {
+				for (const f of record.files) {
+					if (!existsSync(resolve(projectRoot, f))) {
+						details.push(`${domain}${id}: files[] path not found: ${f}`);
+					}
+				}
+			}
+			if (Array.isArray(record.dir_anchors)) {
+				for (const d of record.dir_anchors) {
+					if (!existsSync(resolve(projectRoot, d))) {
+						details.push(`${domain}${id}: dir_anchors[] path not found: ${d}`);
+					}
+				}
+			}
+			if (record.evidence?.file && !existsSync(resolve(projectRoot, record.evidence.file))) {
+				details.push(`${domain}${id}: evidence.file not found: ${record.evidence.file}`);
+			}
+		}
+	}
+
+	if (details.length > 0) {
+		return {
+			name: "file-anchors",
+			status: "warn",
+			message: `${details.length} broken file anchor(s) found`,
+			fixable: true,
+			details,
+		};
+	}
+	return {
+		name: "file-anchors",
+		status: "pass",
+		message: "All file anchors resolve to existing paths",
+		fixable: true,
+		details: [],
+	};
+}
+
+async function checkGovernance(config: LoamConfig, cwd?: string): Promise<DoctorCheck> {
+	const details: string[] = [];
+	let worstStatus: "pass" | "warn" | "fail" = "pass";
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+		const count = records.length;
+
+		if (count >= config.governance.hard_limit) {
+			details.push(
+				`${domain}: ${count} records (over hard limit of ${config.governance.hard_limit})`,
+			);
+			worstStatus = "fail";
+		} else if (count >= config.governance.warn_entries) {
+			details.push(
+				`${domain}: ${count} records (over warn threshold of ${config.governance.warn_entries})`,
+			);
+			if (worstStatus !== "fail") worstStatus = "warn";
+		} else if (count >= config.governance.max_entries) {
+			details.push(
+				`${domain}: ${count} records (approaching limit of ${config.governance.max_entries})`,
+			);
+			if (worstStatus !== "fail") worstStatus = "warn";
+		}
+	}
+
+	if (details.length > 0) {
+		return {
+			name: "governance",
+			status: worstStatus,
+			message: `${details.length} domain(s) over governance thresholds`,
+			fixable: false,
+			details,
+		};
+	}
+	return {
+		name: "governance",
+		status: "pass",
+		message: "All domains within governance limits",
+		fixable: false,
+		details: [],
+	};
+}
+
+// Informational: report whether `lm compact` runs the mechanical merge (no
+// `pre-compact` hook registered) vs. a semantic summarizer (one or more
+// scripts configured). Always passes; the message tells the user which mode
+// they're in.
+function checkCompactSummarizer(config: LoamConfig): DoctorCheck {
+	const scripts = (config.hooks?.["pre-compact"] ?? []).filter(
+		(s) => typeof s === "string" && s.trim().length > 0,
+	);
+	if (scripts.length === 0) {
+		return {
+			name: "compact-summarizer",
+			status: "pass",
+			message: "compact-summarizer: not configured (mechanical merge in use)",
+			fixable: false,
+			details: [],
+		};
+	}
+	return {
+		name: "compact-summarizer",
+		status: "pass",
+		message: `compact-summarizer: ${scripts.length} pre-compact hook${scripts.length === 1 ? "" : "s"} registered`,
+		fixable: false,
+		details: scripts,
+	};
+}
+
+function checkDecayConfig(config: LoamConfig): DoctorCheck {
+	const cfg = config.decay?.anchor_validity;
+	if (!cfg) {
+		return {
+			name: "decay-config",
+			status: "pass",
+			message: "decay.anchor_validity uses defaults",
+			fixable: false,
+			details: [],
+		};
+	}
+	const errors = validateAnchorValidityConfig(cfg);
+	if (errors.length > 0) {
+		return {
+			name: "decay-config",
+			status: "fail",
+			message: `decay.anchor_validity is invalid (${errors.length} issue${errors.length === 1 ? "" : "s"})`,
+			fixable: false,
+			details: errors,
+		};
+	}
+	return {
+		name: "decay-config",
+		status: "pass",
+		message: "decay.anchor_validity is valid",
+		fixable: false,
+		details: [],
+	};
+}
+
+// Walk every domain's records and bucket them as conforming or violating
+// domain-level rules (allowed_types / required_fields). Used by both the
+// informational and failing checks so we read+parse JSONL once.
+async function collectDomainConformance(
+	config: LoamConfig,
+	cwd?: string,
+): Promise<{
+	perDomain: Array<{
+		domain: string;
+		total: number;
+		conforming: number;
+		violations: number;
+		hasRules: boolean;
+	}>;
+	violations: string[];
+}> {
+	const perDomain: Array<{
+		domain: string;
+		total: number;
+		conforming: number;
+		violations: number;
+		hasRules: boolean;
+	}> = [];
+	const violations: string[] = [];
+
+	for (const domain of Object.keys(config.domains)) {
+		const allowedTypes = getAllowedTypes(config, domain);
+		const requiredFields = getRequiredFields(config, domain);
+		const hasRules = allowedTypes !== null || requiredFields !== null;
+
+		const filePath = getExpertisePath(domain, cwd);
+		let content: string;
+		try {
+			content = await readFile(filePath, "utf-8");
+		} catch {
+			perDomain.push({ domain, total: 0, conforming: 0, violations: 0, hasRules });
+			continue;
+		}
+
+		const lines = content.split("\n");
+		let total = 0;
+		let badCount = 0;
+
+		for (let i = 0; i < lines.length; i++) {
+			const line = (lines[i] ?? "").trim();
+			if (line.length === 0) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				continue; // jsonl-integrity reports parse errors
+			}
+			if (!parsed || typeof parsed !== "object") continue;
+			total++;
+
+			const record = parsed as Record<string, unknown>;
+			const recordType = typeof record.type === "string" ? record.type : "<unknown>";
+			const id = typeof record.id === "string" ? record.id : "<no-id>";
+			const lineNumber = i + 1;
+			let recordViolated = false;
+
+			if (allowedTypes && !allowedTypes.includes(recordType)) {
+				recordViolated = true;
+				violations.push(
+					`${domain}:${lineNumber} [${id}] type "${recordType}" not in allowed_types [${allowedTypes.join(", ")}]`,
+				);
+			}
+
+			if (requiredFields) {
+				const missing = findMissingDomainFields(record, requiredFields);
+				if (missing.length > 0) {
+					recordViolated = true;
+					violations.push(
+						`${domain}:${lineNumber} [${id}] (${recordType}) missing required field(s): ${missing.join(", ")}`,
+					);
+				}
+			}
+
+			if (recordViolated) badCount++;
+		}
+
+		perDomain.push({
+			domain,
+			total,
+			conforming: total - badCount,
+			violations: badCount,
+			hasRules,
+		});
+	}
+
+	return { perDomain, violations };
+}
+
+// Static compatibility check: a domain's required_fields can name a field that
+// no allowed type accepts. Built-in/custom schemas are closed
+// (additionalProperties: false), so writes silently fail with a confusing AJV
+// error. Surfacing this at doctor time tells the user to either declare a
+// custom_type that holds the field or drop it from required_fields.
+async function checkDomainRulesCompatibility(config: LoamConfig): Promise<DoctorCheck> {
+	const registry = getRegistry();
+	const details: string[] = [];
+	let count = 0;
+
+	for (const domain of Object.keys(config.domains)) {
+		const incompatible = findIncompatibleRequiredFields(config, domain, registry);
+		for (const { field, allowedTypes } of incompatible) {
+			count++;
+			details.push(
+				`domain "${domain}" requires field "${field}", but no allowed type accepts it (allowed: ${allowedTypes.join(", ")}). Declare a custom_type with "${field}" in required/optional, or remove "${field}" from required_fields.`,
+			);
+		}
+	}
+
+	if (count > 0) {
+		return {
+			name: "domain-rules-compatibility",
+			status: "fail",
+			message: `${count} domain required_field(s) incompatible with allowed types`,
+			fixable: false,
+			details,
+		};
+	}
+	return {
+		name: "domain-rules-compatibility",
+		status: "pass",
+		message: "All domain required_fields are compatible with allowed types",
+		fixable: false,
+		details: [],
+	};
+}
+
+async function checkDomainConformance(
+	config: LoamConfig,
+	cwd?: string,
+): Promise<{ info: DoctorCheck; violations: DoctorCheck }> {
+	const { perDomain, violations } = await collectDomainConformance(config, cwd);
+
+	const infoDetails = perDomain.map((d) => {
+		const rulesLabel = d.hasRules ? "rules" : "no rules";
+		return `${d.domain} (${rulesLabel}): ${d.conforming}/${d.total} conforming, ${d.violations} violation${d.violations === 1 ? "" : "s"}`;
+	});
+	const totalRecords = perDomain.reduce((s, d) => s + d.total, 0);
+	const totalViolations = perDomain.reduce((s, d) => s + d.violations, 0);
+	const info: DoctorCheck = {
+		name: "domain-conformance",
+		status: "pass",
+		message: `${totalRecords - totalViolations}/${totalRecords} record(s) conform to domain rules`,
+		fixable: false,
+		details: infoDetails,
+	};
+
+	const violationsCheck: DoctorCheck =
+		violations.length > 0
+			? {
+					name: "domain-violations",
+					status: "fail",
+					message: `${totalViolations} record(s) violate domain rules (allowed_types / required_fields)`,
+					fixable: false,
+					details: violations,
+				}
+			: {
+					name: "domain-violations",
+					status: "pass",
+					message: "All records conform to domain rules",
+					fixable: false,
+					details: [],
+				};
+
+	return { info, violations: violationsCheck };
+}
+
+async function checkUpdateAvailable(): Promise<DoctorCheck> {
+	const current = getCurrentVersion();
+	const latest = getLatestVersion();
+
+	if (latest === null) {
+		return {
+			name: "upgrade",
+			status: "pass",
+			message: `Version ${current} (unable to check registry)`,
+			fixable: false,
+			details: [],
+		};
+	}
+
+	const cmp = compareSemver(current, latest);
+	if (cmp >= 0) {
+		return {
+			name: "upgrade",
+			status: "pass",
+			message: `Version ${current} is up to date`,
+			fixable: false,
+			details: [],
+		};
+	}
+
+	return {
+		name: "upgrade",
+		status: "warn",
+		message: `Update available: ${current} → ${latest}`,
+		fixable: false,
+		details: ["Run `loam upgrade` to upgrade"],
+	};
+}
+
+async function applyFixes(
+	checks: DoctorCheck[],
+	config: LoamConfig,
+	cwd?: string,
+): Promise<string[]> {
+	const fixed: string[] = [];
+
+	for (const check of checks) {
+		if (check.status === "pass" || !check.fixable) continue;
+
+		switch (check.name) {
+			case "jsonl-integrity": {
+				// Remove invalid JSON lines
+				for (const domain of Object.keys(config.domains)) {
+					const filePath = getExpertisePath(domain, cwd);
+					await withFileLock(filePath, async () => {
+						let content: string;
+						try {
+							content = await readFile(filePath, "utf-8");
+						} catch {
+							return;
+						}
+						const lines = content.split("\n");
+						const valid: string[] = [];
+						let removed = 0;
+						for (const line of lines) {
+							const trimmed = line.trim();
+							if (trimmed.length === 0) continue;
+							try {
+								JSON.parse(trimmed);
+								valid.push(trimmed);
+							} catch {
+								removed++;
+							}
+						}
+						if (removed > 0) {
+							await fsWriteFile(
+								filePath,
+								valid.map((l) => l).join("\n") + (valid.length > 0 ? "\n" : ""),
+								"utf-8",
+							);
+							fixed.push(`Removed ${removed} invalid JSON line(s) from ${domain}`);
+						}
+					});
+				}
+				break;
+			}
+
+			case "schema-validation": {
+				const registry = getRegistry();
+				const validate = registry.validator;
+				for (const domain of Object.keys(config.domains)) {
+					const filePath = getExpertisePath(domain, cwd);
+					await withFileLock(filePath, async () => {
+						const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+						// Keep unknown-type records — they're flagged separately by
+						// checkUnknownTypes and shouldn't be silently deleted.
+						const valid = records.filter((r) => !registry.get(r.type) || validate(r));
+						const removed = records.length - valid.length;
+						if (removed > 0) {
+							await writeExpertiseFile(filePath, valid);
+							fixed.push(`Removed ${removed} invalid record(s) from ${domain}`);
+						}
+					});
+				}
+				break;
+			}
+
+			case "stale-records": {
+				const now = new Date();
+				const shelfLife = config.classification_defaults.shelf_life;
+				for (const domain of Object.keys(config.domains)) {
+					const filePath = getExpertisePath(domain, cwd);
+					await withFileLock(filePath, async () => {
+						const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+						const kept = records.filter((r) => !isStale(r, now, shelfLife));
+						const pruned = records.length - kept.length;
+						if (pruned > 0) {
+							await writeExpertiseFile(filePath, kept);
+							fixed.push(`Pruned ${pruned} stale record(s) from ${domain}`);
+						}
+					});
+				}
+				break;
+			}
+
+			case "legacy-outcome": {
+				for (const domain of Object.keys(config.domains)) {
+					const filePath = getExpertisePath(domain, cwd);
+					await withFileLock(filePath, async () => {
+						let content: string;
+						try {
+							content = await readFile(filePath, "utf-8");
+						} catch {
+							return;
+						}
+						const lines = content.split("\n");
+						const migrated: string[] = [];
+						let count = 0;
+						for (const line of lines) {
+							const trimmed = line.trim();
+							if (trimmed.length === 0) continue;
+							let raw: Record<string, unknown>;
+							try {
+								raw = JSON.parse(trimmed) as Record<string, unknown>;
+							} catch {
+								migrated.push(trimmed);
+								continue;
+							}
+							if (
+								"outcome" in raw &&
+								raw.outcome !== null &&
+								raw.outcome !== undefined &&
+								!("outcomes" in raw)
+							) {
+								const legacy = raw.outcome as Record<string, unknown>;
+								const rewritten: Record<string, unknown> = { ...raw };
+								rewritten.outcome = undefined;
+								rewritten.outcomes = [
+									{
+										status: legacy.status,
+										...(legacy.duration !== undefined ? { duration: legacy.duration } : {}),
+										...(legacy.test_results !== undefined
+											? { test_results: legacy.test_results }
+											: {}),
+										...(legacy.agent !== undefined ? { agent: legacy.agent } : {}),
+									},
+								];
+								migrated.push(JSON.stringify(rewritten));
+								count++;
+							} else {
+								migrated.push(trimmed);
+							}
+						}
+						if (count > 0) {
+							await fsWriteFile(
+								filePath,
+								migrated.join("\n") + (migrated.length > 0 ? "\n" : ""),
+								"utf-8",
+							);
+							fixed.push(
+								`Migrated ${count} legacy "outcome" field(s) to "outcomes[]" in ${domain}`,
+							);
+						}
+					});
+				}
+				break;
+			}
+
+			case "file-anchors": {
+				const projectRoot = cwd ?? process.cwd();
+				for (const domain of Object.keys(config.domains)) {
+					const filePath = getExpertisePath(domain, cwd);
+					await withFileLock(filePath, async () => {
+						const records = await readExpertiseFile(filePath, { allowUnknownTypes: true });
+						let removedCount = 0;
+						const updated: ExpertiseRecord[] = records.map((record) => {
+							let r: ExpertiseRecord = record;
+							if ("files" in r && Array.isArray(r.files)) {
+								const before = r.files.length;
+								const kept = r.files.filter((f) => existsSync(resolve(projectRoot, f)));
+								if (kept.length < before) {
+									removedCount += before - kept.length;
+									r = { ...r, files: kept.length > 0 ? kept : undefined } as ExpertiseRecord;
+								}
+							}
+							if (Array.isArray(r.dir_anchors)) {
+								const before = r.dir_anchors.length;
+								const kept = r.dir_anchors.filter((d) => existsSync(resolve(projectRoot, d)));
+								if (kept.length < before) {
+									removedCount += before - kept.length;
+									r = { ...r, dir_anchors: kept.length > 0 ? kept : undefined };
+								}
+							}
+							if (r.evidence?.file && !existsSync(resolve(projectRoot, r.evidence.file))) {
+								removedCount++;
+								r = { ...r, evidence: { ...r.evidence, file: undefined } };
+							}
+							return r;
+						});
+						if (removedCount > 0) {
+							await writeExpertiseFile(filePath, updated);
+							fixed.push(`Removed ${removedCount} broken file anchor(s) from ${domain}`);
+						}
+					});
+				}
+				break;
+			}
+
+			case "orphaned-domains": {
+				const expertiseDir = getExpertiseDir(cwd);
+				// Add missing domains to config
+				try {
+					const files = await readdir(expertiseDir);
+					for (const file of files) {
+						if (file.endsWith(".jsonl")) {
+							const domain = file.replace(".jsonl", "");
+							if (!(domain in config.domains)) {
+								config.domains[domain] = {};
+								fixed.push(`Added orphaned domain "${domain}" to config`);
+							}
+						}
+					}
+				} catch {
+					// expertise dir doesn't exist
+				}
+				// Create missing JSONL files
+				for (const domain of Object.keys(config.domains)) {
+					const filePath = getExpertisePath(domain, cwd);
+					if (!existsSync(filePath)) {
+						await createExpertiseFile(filePath);
+						fixed.push(`Created missing JSONL file for domain "${domain}"`);
+					}
+				}
+				if (fixed.length > 0) {
+					await writeConfig(config, cwd);
+				}
+				break;
+			}
+		}
+	}
+
+	return fixed;
+}
+
+export function registerDoctorCommand(program: Command): void {
+	program
+		.command("doctor")
+		.description("Run health checks on expertise records")
+		.option("--fix", "auto-fix fixable issues")
+		.action(async (options: { fix?: boolean }) => {
+			const jsonMode = program.opts().json === true;
+
+			// Check config first — if it fails, we can't run other checks
+			const configCheck = await checkConfig();
+			if (configCheck.status === "fail") {
+				const checks = [configCheck];
+				const summary = { pass: 0, warn: 0, fail: 1 };
+				if (jsonMode) {
+					outputJson({ success: false, command: "doctor", checks, summary });
+				} else {
+					if (!isQuiet()) console.log("Loam Doctor");
+					console.error(`  ${icons.fail} ${chalk.red(configCheck.message)}`);
+					if (!isQuiet()) console.log("\n0 passed, 0 warnings, 1 failed");
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			const config = await readConfig();
+
+			const checks: DoctorCheck[] = [configCheck];
+			checks.push(await checkJsonlIntegrity(config));
+			checks.push(await checkLegacyOutcome(config));
+			checks.push(await checkSchemaValidation(config));
+			checks.push(await checkUnknownTypes(config));
+			checks.push(await checkTypeRegistry(config));
+			checks.push(await checkDomainRulesCompatibility(config));
+			const domainConformance = await checkDomainConformance(config);
+			checks.push(domainConformance.info);
+			checks.push(domainConformance.violations);
+			checks.push(await checkStaleRecords(config));
+			checks.push(await checkOrphanedDomains(config));
+			checks.push(await checkDuplicates(config));
+			checks.push(await checkFileAnchors(config));
+			checks.push(await checkGovernance(config));
+			checks.push(checkDecayConfig(config));
+			checks.push(checkCompactSummarizer(config));
+			checks.push(await checkUpdateAvailable());
+
+			const summary = {
+				pass: checks.filter((c) => c.status === "pass").length,
+				warn: checks.filter((c) => c.status === "warn").length,
+				fail: checks.filter((c) => c.status === "fail").length,
+			};
+
+			let fixed: string[] = [];
+			if (options.fix) {
+				fixed = await applyFixes(checks, config);
+			}
+
+			if (jsonMode) {
+				outputJson({
+					success: summary.fail === 0,
+					command: "doctor",
+					checks,
+					summary,
+					...(options.fix && { fixed }),
+				});
+			} else {
+				if (!isQuiet()) console.log("Loam Doctor");
+				for (const check of checks) {
+					const icon =
+						check.status === "pass"
+							? icons.pass
+							: check.status === "warn"
+								? icons.warn
+								: icons.fail;
+					const msg = check.status === "pass" ? check.message : `${check.message}`;
+					if (!isQuiet()) console.log(`  ${icon} ${msg}`);
+
+					// Print details for non-pass checks
+					if (check.status !== "pass" && check.details.length > 0) {
+						for (const detail of check.details) {
+							if (!isQuiet()) console.log(`      ${detail}`);
+						}
+					}
+				}
+				if (!isQuiet())
+					console.log(
+						`\n${summary.pass} passed, ${summary.warn} warning(s), ${summary.fail} failed`,
+					);
+
+				if (fixed.length > 0) {
+					if (!isQuiet()) console.log(`\n${brand("Fixed:")}`);
+					for (const f of fixed) {
+						if (!isQuiet()) console.log(`  ${icons.pass} ${f}`);
+					}
+				}
+			}
+
+			if (summary.fail > 0) {
+				process.exitCode = 1;
+			}
+		});
+}