@iowarp/clio-coder 0.4.0 → 0.4.1

package/src/cli/auth.ts

@@ -104,8 +104,8 @@ function renderStatusRows(rows: ReadonlyArray<ConnectableProviderRow>): string {
 
 function defaultAuthTarget(rows: ReadonlyArray<ConnectableProviderRow>): string | undefined {
 	const settings = readSettings();
-	const activeTarget = settings.orchestrator.target
-		? settings.targets.find((entry) => entry.id === settings.orchestrator.target)
+	const activeTarget = settings.chat.target
+		? settings.targets.find((entry) => entry.id === settings.chat.target)
 		: undefined;
 	if (activeTarget && rows.some((row) => row.entry.runtimeId === activeTarget.runtime)) {
 		return activeTarget.runtime;

package/src/cli/bootstrap-generate.ts

@@ -79,9 +79,9 @@ export interface BootstrapRoute {
  */
 export function resolveBootstrapRoute(settings: Readonly<ClioSettings>): BootstrapRoute {
 	for (const agentId of [CONTEXT_BOOTSTRAP_AGENT_ID, "scout"]) {
-		const profileName = settings.workers.agentBindings[agentId];
+		const profileName = settings.fleet.agentProfiles[agentId];
 		if (!profileName) continue;
-		const profile = settings.workers.profiles[profileName];
+		const profile = settings.fleet.profiles[profileName];
 		if (!profile) throw new Error(`bootstrap profile '${profileName}' is not configured (bound to '${agentId}')`);
 		if (!profile.target) throw new Error(`bootstrap profile '${profileName}' has no target (bound to '${agentId}')`);
 		return {
@@ -90,7 +90,7 @@ export function resolveBootstrapRoute(settings: Readonly<ClioSettings>): Bootstr
 			...(profile.thinkingLevel ? { thinkingLevel: profile.thinkingLevel } : {}),
 		};
 	}
-	const fallback = settings.workers.default;
+	const fallback = settings.fleet.default;
 	if (!fallback?.target) {
 		throw new Error(
 			`bootstrap has no route: workers.agentBindings.${CONTEXT_BOOTSTRAP_AGENT_ID} is unbound and ` +
@@ -233,7 +233,7 @@ async function collectDispatchAssistantText(
 				message: "bootstrap agent started repository exploration",
 			});
 		}
-		if (isRecord(event) && event.type === "clio_tool_start") {
+		if (isRecord(event) && event.type === "clio_coder_tool_start") {
 			const tool = toolNameFromEvent(event);
 			if (tool) {
 				input.progress?.({
@@ -244,7 +244,7 @@ async function collectDispatchAssistantText(
 				});
 			}
 		}
-		if (isRecord(event) && event.type === "clio_tool_finish") {
+		if (isRecord(event) && event.type === "clio_coder_tool_finish") {
 			const tool = toolNameFromEvent(event);
 			const outcome = toolOutcomeFromEvent(event) ?? "done";
 			if (tool) {

package/src/cli/clio.ts

@@ -6,7 +6,7 @@ import { classifyDefaultTarget, describeVerdict } from "./default-target.js";
 
 /** Headless and ACP keep their established non-TUI transports even when an
  * embedding process leaves the interactive marker in the environment. */
-export function terminalLeaseEligible(
+function terminalLeaseEligible(
 	options: Pick<BootOptions, "headless" | "acp">,
 	env: Readonly<Record<string, string | undefined>> = process.env,
 ): boolean {
@@ -44,6 +44,11 @@ export async function runClioCommand(options: BootOptions = {}): Promise<number>
 			const configured = await runConfigureCommand([]);
 			if (configured !== 0) return configured;
 			startupSettings = readStrictLayeredSettings(process.cwd()).settings;
+			const configuredVerdict = classifyDefaultTarget(startupSettings);
+			if (configuredVerdict.kind !== "usable" && configuredVerdict.kind !== "missing-credential") {
+				process.stderr.write(`${describeVerdict(configuredVerdict)} Configuration did not complete; startup cancelled.\n`);
+				return 2;
+			}
 		}
 	}
 	let terminalLease: import("../interactive/terminal-lease.js").TerminalLease | undefined;

package/src/cli/config-inspect.ts

@@ -317,12 +317,12 @@ function inspectSafetyAndMemory(cwd: string, graph: CustomizationGraph): void {
 		const layered = readLayeredSettings(cwd);
 		graph.entries.push({
 			category: "safety",
-			id: "autonomy",
-			scope: settingsSourceFor(layered.sources, "autonomy"),
+			id: "safety.autonomy",
+			scope: settingsSourceFor(layered.sources, "safety.autonomy"),
 			reloadClass: "hot",
 			trust: "n/a",
 			precedence: "single",
-			detail: { autonomy: layered.settings.autonomy ?? "auto-edit" },
+			detail: { autonomy: layered.settings.safety.autonomy ?? "auto-edit" },
 		});
 	} catch (err) {
 		graph.issues.push(`safety: ${err instanceof Error ? err.message : String(err)}`);

package/src/cli/configure-interop.ts

@@ -22,7 +22,7 @@ function describe(proposal: InteropProposal): string {
 		renderProposalEntry(proposal),
 		"",
 		`projectContext stays ${INHERITED_PROJECT_CONTEXT}: this agent receives your task text, never the project projection.`,
-		`toolGovernance is clio-policy: its tool calls are gated by Clio safety.`,
+		`toolGovernance is clio-coder-policy: its tool calls are gated by Clio safety.`,
 	];
 	if (proposal.needsNetworkInstall) {
 		lines.push(`The ACP adapter is not installed locally; npx fetches it the first time you delegate.`);

package/src/cli/configure.ts

@@ -80,7 +80,7 @@ Non-interactive flags:
   --force                          save a model outside the runtime catalog, or one the
                                    target does not advertise, without refusing
   --gateway                        mark the target as a gateway
-  --lifecycle <user-managed|clio-managed>
+  --lifecycle <user-managed|clio-coder-managed>
                                   resident model lifecycle policy
   --set-orchestrator               use this target for chat
   --set-background                 use this target for proactive task memory
@@ -225,8 +225,8 @@ function parseSetupArgs(argv: ReadonlyArray<string>): ParsedArgs {
 				break;
 			case "--lifecycle": {
 				const v = need();
-				if (v !== "user-managed" && v !== "clio-managed") {
-					throw new Error("--lifecycle must be user-managed or clio-managed");
+				if (v !== "user-managed" && v !== "clio-coder-managed") {
+					throw new Error("--lifecycle must be user-managed or clio-coder-managed");
 				}
 				out.lifecycle = v;
 				break;
@@ -485,13 +485,13 @@ function setOrchestratorPointer(settings: ClioSettings, descriptor: TargetDescri
 			`cannot use target '${descriptor.id}' as orchestrator target because runtime '${runtime.id}' is not an HTTP/native runtime`,
 		);
 	}
-	settings.orchestrator.target = descriptor.id;
-	settings.orchestrator.model = model ?? descriptor.defaultModel ?? null;
+	settings.chat.target = descriptor.id;
+	settings.chat.model = model ?? descriptor.defaultModel ?? null;
 }
 
 function setWorkerDefaultPointer(settings: ClioSettings, descriptor: TargetDescriptor, model?: string | null): void {
-	settings.workers.default.target = descriptor.id;
-	settings.workers.default.model = model ?? descriptor.defaultModel ?? null;
+	settings.fleet.default.target = descriptor.id;
+	settings.fleet.default.model = model ?? descriptor.defaultModel ?? null;
 }
 
 function setBackgroundPointer(settings: ClioSettings, descriptor: TargetDescriptor, model?: string | null): void {
@@ -501,13 +501,13 @@ function setBackgroundPointer(settings: ClioSettings, descriptor: TargetDescript
 			`cannot use target '${descriptor.id}' as background target because runtime '${descriptor.runtime}' is not an HTTP/native runtime`,
 		);
 	}
-	settings.background.target = descriptor.id;
-	settings.background.model = model ?? descriptor.defaultModel ?? null;
+	settings.context.memory.target = descriptor.id;
+	settings.context.memory.model = model ?? descriptor.defaultModel ?? null;
 }
 
 function assertOrchestratorReplacementEligible(settings: ClioSettings, descriptor: TargetDescriptor): void {
-	if (settings.orchestrator.target !== descriptor.id && settings.background.target !== descriptor.id) return;
-	const role = settings.orchestrator.target === descriptor.id ? "orchestrator" : "background";
+	if (settings.chat.target !== descriptor.id && settings.context.memory.target !== descriptor.id) return;
+	const role = settings.chat.target === descriptor.id ? "orchestrator" : "background";
 	const runtime = getRuntimeRegistry().get(descriptor.runtime);
 	if (!runtime) {
 		throw new Error(
@@ -527,7 +527,7 @@ function setWorkerProfilePointer(
 ): void {
 	const trimmed = name.trim();
 	if (trimmed.length === 0) throw new Error("fleet profile name must be non-empty");
-	settings.workers.profiles[trimmed] = {
+	settings.fleet.profiles[trimmed] = {
 		target: descriptor.id,
 		model: model ?? descriptor.defaultModel ?? null,
 		thinkingLevel: "off",
@@ -607,10 +607,10 @@ function printSummary(settings: ClioSettings, descriptor: TargetDescriptor, prob
 		for (const line of probeLines(descriptor, probe)) process.stdout.write(`  ${line}\n`);
 	}
 	warnUndiscoveredContextWindow(descriptor, probe);
-	if (settings.orchestrator.target === descriptor.id) process.stdout.write("  orchestrator target\n");
-	if (settings.background.target === descriptor.id) process.stdout.write("  background memory target\n");
-	if (settings.workers.default.target === descriptor.id) process.stdout.write("  fleet default\n");
-	for (const [name, profile] of Object.entries(settings.workers.profiles)) {
+	if (settings.chat.target === descriptor.id) process.stdout.write("  orchestrator target\n");
+	if (settings.context.memory.target === descriptor.id) process.stdout.write("  background memory target\n");
+	if (settings.fleet.default.target === descriptor.id) process.stdout.write("  fleet default\n");
+	for (const [name, profile] of Object.entries(settings.fleet.profiles)) {
 		if (profile.target === descriptor.id) process.stdout.write(`  fleet profile ${name}\n`);
 	}
 	process.stdout.write(`\nsettings written to ${settingsPath()}\n`);
@@ -1155,7 +1155,7 @@ async function runInteractive(
 	let runtime = preselectedRuntime ?? (await pickRuntimeViaCategory(rl));
 	if (!runtime) {
 		printError("configuration cancelled");
-		return 0;
+		return 130;
 	}
 	const auth = openAuthStorage();
 	const settings = readSettings();
@@ -1413,10 +1413,10 @@ async function runInteractive(
 		? false
 		: defaults.setOrchestrator
 			? true
-			: await askYesNo(rl, "use as orchestrator (chat) target?", !settings.orchestrator.target);
+			: await askYesNo(rl, "use as orchestrator (chat) target?", !settings.chat.target);
 	const setWorkerDefault = defaults.setWorkerDefault
 		? true
-		: await askYesNo(rl, "use as fleet default?", !settings.workers.default.target);
+		: await askYesNo(rl, "use as fleet default?", !settings.fleet.default.target);
 	const setBackground = !isOrchestratorEligibleRuntime(runtime)
 		? false
 		: defaults.setBackground
@@ -1428,7 +1428,7 @@ async function runInteractive(
 				rl,
 				"Orchestrator model",
 				wireModels,
-				settings.orchestrator.target === targetId ? (settings.orchestrator.model ?? model) : model,
+				settings.chat.target === targetId ? (settings.chat.model ?? model) : model,
 			)))
 		: undefined;
 	if (orchestratorModel === null) return 0;
@@ -1438,7 +1438,7 @@ async function runInteractive(
 				rl,
 				"Fleet model",
 				wireModels,
-				settings.workers.default.target === targetId ? (settings.workers.default.model ?? model) : model,
+				settings.fleet.default.target === targetId ? (settings.fleet.default.model ?? model) : model,
 			)))
 		: undefined;
 	if (workerModel === null) return 0;
@@ -1448,7 +1448,7 @@ async function runInteractive(
 				rl,
 				"Background memory model",
 				wireModels,
-				settings.background.target === targetId ? (settings.background.model ?? model) : model,
+				settings.context.memory.target === targetId ? (settings.context.memory.model ?? model) : model,
 			)))
 		: undefined;
 	if (backgroundModel === null) return 0;
@@ -1498,13 +1498,13 @@ export function runTargetRename(oldId: string, newId: string): number {
 		const target = settings.targets.find((e) => e.id === oldId);
 		if (!target) return;
 		target.id = newId;
-		if (settings.orchestrator.target === oldId) settings.orchestrator.target = newId;
-		if (settings.background.target === oldId) settings.background.target = newId;
-		if (settings.workers.default.target === oldId) settings.workers.default.target = newId;
-		for (const profile of Object.values(settings.workers.profiles)) {
+		if (settings.chat.target === oldId) settings.chat.target = newId;
+		if (settings.context.memory.target === oldId) settings.context.memory.target = newId;
+		if (settings.fleet.default.target === oldId) settings.fleet.default.target = newId;
+		for (const profile of Object.values(settings.fleet.profiles)) {
 			if (profile.target === oldId) profile.target = newId;
 		}
-		settings.scope = settings.scope.map((entry) => {
+		settings.chat.modelPicker.cycleSet = settings.chat.modelPicker.cycleSet.map((entry) => {
 			const [head, ...rest] = entry.split("/");
 			if (head !== oldId) return entry;
 			return rest.length === 0 ? newId : `${newId}/${rest.join("/")}`;

package/src/cli/default-target.ts

@@ -24,7 +24,7 @@ export type DefaultTargetVerdict =
 	| { kind: "missing-credential"; targetId: string; store: string };
 
 export function classifyDefaultTarget(settings: Readonly<ClioSettings> = readSettings()): DefaultTargetVerdict {
-	const targetId = settings.orchestrator.target;
+	const targetId = settings.chat.target;
 	if (!targetId) return { kind: "no-target" };
 	// A chat target naming an id that is not in `targets` cannot arrive here:
 	// the schema normalizes dangling routing references to null so that

package/src/cli/docs.ts

@@ -65,12 +65,12 @@ export interface DocsMenuEntry {
 }
 
 /** Resolve docs/html from the package root; present in a source checkout, absent from the npm package. */
-export function resolveDocsHtmlDir(): string {
+function resolveDocsHtmlDir(): string {
 	return resolve(resolvePackageRoot(), "docs", "html");
 }
 
 /** Content-type for a file path by extension. Pure. Defaults to octet-stream. */
-export function contentTypeFor(filePath: string): string {
+function contentTypeFor(filePath: string): string {
 	const dot = filePath.lastIndexOf(".");
 	if (dot === -1) return "application/octet-stream";
 	return CONTENT_TYPES[filePath.slice(dot).toLowerCase()] ?? "application/octet-stream";
@@ -82,7 +82,7 @@ export function contentTypeFor(filePath: string): string {
  * to `index.html`, and rejects any traversal segment so a request can never
  * escape the served directory.
  */
-export function resolveRequestPath(rawUrl: string): { ok: true; relative: string } | { ok: false; reason: string } {
+function resolveRequestPath(rawUrl: string): { ok: true; relative: string } | { ok: false; reason: string } {
 	const pathPart = (rawUrl.split(/[?#]/, 1)[0] ?? "").trim();
 	let decoded: string;
 	try {
@@ -112,7 +112,7 @@ function titleize(topic: string): string {
  * the file-name list, not the directory. `index.html` is the menu itself and is
  * excluded; a trailing `_blueprint` is stripped from the topic key.
  */
-export function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[] {
+function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[] {
 	const entries: DocsMenuEntry[] = [];
 	for (const name of fileNames) {
 		if (!name.toLowerCase().endsWith(".html")) continue;
@@ -129,7 +129,7 @@ export function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[
  * topic (`safety`), the blueprint file stem (`safety_blueprint`), or a full
  * `.html` name, case-insensitively. Returns null when nothing matches.
  */
-export function topicToFile(topic: string, fileNames: ReadonlyArray<string>): string | null {
+function topicToFile(topic: string, fileNames: ReadonlyArray<string>): string | null {
 	const wanted = topic
 		.trim()
 		.toLowerCase()
@@ -227,7 +227,7 @@ export interface StartDocsServerOptions {
 }
 
 /** Start the viewer bound to 127.0.0.1 on an ephemeral port. */
-export async function startDocsServer(options: StartDocsServerOptions): Promise<DocsServerHandle> {
+async function startDocsServer(options: StartDocsServerOptions): Promise<DocsServerHandle> {
 	const host = options.host ?? HOST;
 	const server = createServer(createDocsRequestHandler(options.htmlDir));
 	await new Promise<void>((resolveListen, rejectListen) => {

package/src/cli/doctor-naming.ts

@@ -0,0 +1,323 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+import { withSettingsLock } from "../core/config.js";
+import { resolveClioDirs } from "../core/xdg.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import {
+	migrateNamingSettingsFile,
+	transformNamingSettingsDocument,
+} from "../domains/lifecycle/migrations/2026-09-01-clio-coder-naming.js";
+import { inspectNamingHistory } from "../domains/lifecycle/naming-history.js";
+import {
+	inspectInstalledNamingResources,
+	inspectModelOverlayNaming,
+	inspectSkillMetadataNaming,
+} from "../domains/lifecycle/naming-resources.js";
+import { inspectToolMarkerNaming } from "../domains/lifecycle/naming-tool-markers.js";
+import { inspectYaziNaming, regenerateYaziNamingProfile } from "../domains/lifecycle/naming-yazi.js";
+
+export interface NamingDoctorOptions {
+	fix?: boolean;
+	cwd?: string;
+	yaziEnabled?: boolean;
+}
+
+interface SettingsNamingInspection {
+	path: string;
+	legacy: number;
+	conflicts: number;
+	error: string | null;
+}
+
+const LEGACY_ENVIRONMENT_NAMES = [
+	["CLIO_EVAL_RUNNER_STDOUT_FILE", "CLIO_CODER_EVAL_RUNNER_STDOUT_FILE"],
+	["CLIO_YAZI_PICK_TOKEN", "CLIO_CODER_YAZI_PICK_TOKEN"],
+] as const;
+
+function namingEnvironmentFindings(
+	yaziEnabled: boolean,
+	environment: NodeJS.ProcessEnv = process.env,
+): DoctorFinding[] {
+	const present = LEGACY_ENVIRONMENT_NAMES.filter(
+		([legacy]) => (yaziEnabled || legacy !== "CLIO_YAZI_PICK_TOKEN") && Boolean(environment[legacy]?.trim()),
+	);
+	if (present.length === 0) {
+		return [{ ok: true, name: "naming environment", detail: "no legacy Clio Coder environment variables are set" }];
+	}
+	return present.map(([legacy, canonical]) => ({
+		ok: true,
+		level: "warn",
+		name: "naming environment",
+		detail: `${legacy} is deprecated; use ${canonical} (compatibility ends in v0.7.0)`,
+	}));
+}
+
+function namingResourceFindings(options: NamingDoctorOptions): DoctorFinding[] {
+	try {
+		const resourceOptions = {
+			...(options.cwd ? { cwd: options.cwd } : {}),
+			...(options.fix !== undefined ? { fix: options.fix } : {}),
+		};
+		const resources = inspectInstalledNamingResources(resourceOptions);
+		const legacyResources = resources.filter((entry) => entry.status !== "absent");
+		const rootOptions = options.cwd ? { cwd: options.cwd } : {};
+		const skillMetadata = inspectSkillMetadataNaming(rootOptions).filter((entry) => entry.legacyMetadataKey);
+		const overlays = inspectModelOverlayNaming(rootOptions).filter(
+			(entry) => entry.legacyFile || entry.legacyMetadataKeys > 0,
+		);
+		if (legacyResources.length === 0 && skillMetadata.length === 0 && overlays.length === 0) {
+			return [{ ok: true, name: "naming resources", detail: "installed skills and model overlays use canonical names" }];
+		}
+		const renamed = legacyResources.filter((entry) => entry.status === "renamed").length;
+		const renamable = legacyResources.filter((entry) => entry.status === "renamable").length;
+		const conflicts = legacyResources.filter(
+			(entry) => entry.status === "modified" || entry.status === "canonical-present",
+		).length;
+		return [
+			{
+				ok: true,
+				level:
+					renamed > 0 && renamable === 0 && conflicts === 0 && skillMetadata.length === 0 && overlays.length === 0
+						? "ok"
+						: "warn",
+				name: "naming resources",
+				detail: [
+					`${renamed} proven skills renamed`,
+					`${renamable} proven skills await doctor --fix`,
+					`${conflicts} modified/conflicting skills left untouched`,
+					`${skillMetadata.length} legacy skill metadata keys`,
+					`${overlays.length} legacy model overlay files/metadata (manual migration required)`,
+				].join("; "),
+			},
+		];
+	} catch (error) {
+		return [
+			{
+				ok: false,
+				name: "naming resources",
+				detail: `resource naming inspection failed: ${error instanceof Error ? error.message : String(error)}`,
+			},
+		];
+	}
+}
+
+function inspectSettingsNaming(path: string): SettingsNamingInspection {
+	if (!existsSync(path)) return { path, legacy: 0, conflicts: 0, error: null };
+	try {
+		const transformed = transformNamingSettingsDocument(parseYaml(readFileSync(path, "utf8")));
+		return {
+			path,
+			legacy: transformed.replacements.length,
+			conflicts: transformed.conflicts.length,
+			error: null,
+		};
+	} catch (error) {
+		return { path, legacy: 0, conflicts: 0, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function settingsFinding(label: string, inspection: SettingsNamingInspection, fixed: boolean): DoctorFinding {
+	if (inspection.error !== null) {
+		return {
+			ok: false,
+			name: `naming ${label}`,
+			detail: `${inspection.path} could not be inspected: ${inspection.error}`,
+		};
+	}
+	const count = inspection.legacy + inspection.conflicts;
+	if (count === 0) {
+		return { ok: true, name: `naming ${label}`, detail: `${inspection.path} has canonical settings identifiers` };
+	}
+	return {
+		ok: fixed,
+		level: fixed ? "ok" : "warn",
+		name: `naming ${label}`,
+		detail: fixed
+			? `${inspection.path}: migrated ${inspection.legacy} aliases and resolved ${inspection.conflicts} canonical collisions; backup written beside the file`
+			: `${inspection.path}: ${inspection.legacy} legacy aliases and ${inspection.conflicts} canonical collisions (run \`clio-coder doctor --fix\`)`,
+	};
+}
+
+function yaziNamingFinding(fix: boolean, enabled: boolean): DoctorFinding {
+	if (!enabled) {
+		return {
+			ok: true,
+			name: "naming yazi profile",
+			detail: "disabled by settings",
+		};
+	}
+	const inspection = inspectYaziNaming();
+	const legacy = inspection.legacyEvents + inspection.legacyEnvironmentNames;
+	if (legacy === 0) {
+		return {
+			ok: true,
+			name: "naming yazi profile",
+			detail: inspection.present
+				? `${inspection.profileDir} uses canonical event and environment identifiers`
+				: `${inspection.profileDir} is absent; the next managed open will generate canonical identifiers`,
+		};
+	}
+	if (!fix) {
+		return {
+			ok: true,
+			level: "warn",
+			name: "naming yazi profile",
+			detail: `${inspection.profileDir}: ${inspection.legacyEvents} legacy events and ${inspection.legacyEnvironmentNames} legacy environment names (run \`clio-coder doctor --fix\`)`,
+		};
+	}
+	const report = regenerateYaziNamingProfile();
+	return {
+		ok: report.status !== "regeneration-failed",
+		...(report.status === "regeneration-failed" ? {} : { level: "ok" as const }),
+		name: "naming yazi profile",
+		detail: report.detail,
+	};
+}
+
+function toolMarkerNamingFinding(fix: boolean): DoctorFinding {
+	try {
+		const reports = inspectToolMarkerNaming({ fix });
+		if (reports.length === 0) {
+			return { ok: true, name: "naming tool markers", detail: "known tool versions use canonical install markers" };
+		}
+		const fixed = reports.filter((entry) => entry.status === "renamed" || entry.status === "duplicate-removed").length;
+		const fixable = reports.filter(
+			(entry) => entry.status === "renamable" || entry.status === "agreeing-duplicate",
+		).length;
+		const manual = reports.length - fixed - fixable;
+		return {
+			ok: true,
+			level: fixed > 0 && fixable === 0 && manual === 0 ? "ok" : "warn",
+			name: "naming tool markers",
+			detail: `${fixed} validated markers fixed; ${fixable} await doctor --fix; ${manual} invalid/conflicting markers left untouched`,
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			name: "naming tool markers",
+			detail: `tool marker inspection failed: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+}
+
+function immutableHistoryNamingFinding(): DoctorFinding {
+	const dirs = resolveClioDirs();
+	const counts = inspectNamingHistory({ stateDir: dirs.state, dataDir: dirs.data });
+	const errors = counts.filter((entry) => entry.error !== null);
+	if (errors.length > 0) {
+		return {
+			ok: false,
+			name: "naming immutable history",
+			detail: errors.map((entry) => `${entry.area}: ${entry.error}`).join("; "),
+		};
+	}
+	const legacy = counts.reduce((sum, entry) => sum + entry.legacyIdentifiers, 0);
+	return {
+		ok: true,
+		...(legacy > 0 ? { level: "warn" as const } : {}),
+		name: "naming immutable history",
+		detail: `${counts.map((entry) => `${entry.area}=${entry.legacyIdentifiers}`).join("; ")} legacy identifiers; read-only retention, no rewrite`,
+	};
+}
+
+function legacyGitRefsFinding(cwd: string): DoctorFinding {
+	let refs: string[];
+	try {
+		refs = execFileSync(
+			"git",
+			["-C", cwd, "for-each-ref", "--format=%(refname:short)", "refs/heads/clio/task", "refs/heads/clio/compete"],
+			{ encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000 },
+		)
+			.split("\n")
+			.map((entry) => entry.trim())
+			.filter((entry) => /^clio\/(?:task|compete)\//u.test(entry))
+			.sort();
+	} catch {
+		refs = [];
+	}
+	if (refs.length === 0) {
+		return { ok: true, name: "naming git refs", detail: "no legacy Clio Coder task or compete refs found" };
+	}
+	const shown = refs.slice(0, 20);
+	return {
+		ok: true,
+		level: "warn",
+		name: "naming git refs",
+		detail: `${refs.length} legacy refs retained (never auto-renamed): ${shown.join(", ")}${refs.length > shown.length ? ", …" : ""}`,
+	};
+}
+
+function legacyWorktreeMarkerFinding(cwd: string): DoctorFinding {
+	const root = join(cwd, ".clio-coder", "worktrees");
+	let legacy = 0;
+	try {
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			const candidates = entry.isFile()
+				? entry.name.endsWith(".task-owner.json")
+					? [join(root, entry.name)]
+					: []
+				: entry.isDirectory()
+					? [join(root, entry.name, ".clio-coder-compete-owner.json")]
+					: [];
+			for (const path of candidates) {
+				if (!existsSync(path)) continue;
+				const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+				if (parsed.kind === "clio-task-worktree" || parsed.kind === "clio-compete-group") legacy += 1;
+			}
+		}
+	} catch {
+		// An absent or partially unreadable project-local worktree root is not a
+		// repair target. Proven markers remain the lifecycle readers' authority.
+	}
+	return {
+		ok: true,
+		...(legacy > 0 ? { level: "warn" as const } : {}),
+		name: "naming worktree markers",
+		detail:
+			legacy === 0
+				? "active worktree markers use canonical identifiers"
+				: `${legacy} active legacy worktree markers retained for cleanup compatibility; no automatic rewrite`,
+	};
+}
+
+/** Read-only naming-footprint settings sweep plus the sanctioned deterministic fixes. */
+export function namingFootprintFindings(options: NamingDoctorOptions = {}): DoctorFinding[] {
+	const cwd = options.cwd ?? process.cwd();
+	const userSettingsPath = join(resolveClioDirs().config, "settings.yaml");
+	const candidates = [
+		{ label: "settings user", path: userSettingsPath, lock: true },
+		{ label: "settings project", path: join(cwd, ".clio-coder", "settings.yaml"), lock: false },
+		{ label: "settings local", path: join(cwd, ".clio-coder", "settings.local.yaml"), lock: false },
+	] as const;
+	const findings: DoctorFinding[] = [];
+	for (const candidate of candidates) {
+		const before = inspectSettingsNaming(candidate.path);
+		let fixed = false;
+		if (options.fix && before.error === null && before.legacy + before.conflicts > 0) {
+			try {
+				if (candidate.lock) withSettingsLock(() => migrateNamingSettingsFile(candidate.path));
+				else migrateNamingSettingsFile(candidate.path);
+				fixed = true;
+			} catch (error) {
+				findings.push({
+					ok: false,
+					name: `naming ${candidate.label}`,
+					detail: `--fix could not migrate ${candidate.path}: ${error instanceof Error ? error.message : String(error)}`,
+				});
+				continue;
+			}
+		}
+		findings.push(settingsFinding(candidate.label, before, fixed));
+	}
+	findings.push(...namingEnvironmentFindings(options.yaziEnabled ?? true));
+	findings.push(...namingResourceFindings({ ...options, cwd }));
+	findings.push(yaziNamingFinding(Boolean(options.fix), options.yaziEnabled ?? true));
+	findings.push(toolMarkerNamingFinding(Boolean(options.fix)));
+	findings.push(immutableHistoryNamingFinding());
+	findings.push(legacyGitRefsFinding(cwd));
+	findings.push(legacyWorktreeMarkerFinding(cwd));
+	return findings;
+}