@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/domains/config/keybindings.ts

@@ -23,6 +23,8 @@ export interface ClioAppKeybindings {
 	"clio.status.toggle": true;
 	"clio.session.tree": true;
 	"clio.dispatchBoard.toggle": true;
+	"clio.tasks.open": true;
+	"clio.decisions.open": true;
 	"clio.dispatch.background": true;
 	"clio.model.select": true;
 	"clio.model.cycleForward": true;
@@ -34,6 +36,7 @@ export interface ClioAppKeybindings {
 	"clio.thinking.expandAll": true;
 	"clio.editor.external": true;
 	"clio.message.followUp": true;
+	"clio.message.interrupt": true;
 	"clio.message.dequeue": true;
 	"clio.notifications.dismiss": true;
 	"clio.leader": true;
@@ -59,10 +62,11 @@ declare module "@earendil-works/pi-tui" {
  * `ctrl+d`, and the portable `ctrl+g` leader retained because every terminal
  * already transmits them). `Alt + <letter>` decodes from the legacy
  * `ESC <letter>` sequence on meta-capable terminals. The chosen letters avoid
- * pi-tui's editor reserves (`alt+b/f/d/y`, and the `ESC n`/`ESC p` aliases for
- * `alt+down`/`alt+up`) and the readline/terminal line-editing reserves the
- * router relies on for editor behavior. The CSI-u/reserved-key detector in
- * `keybinding-manager.ts` stays as a safety net for user rebinds.
+ * pi-tui's editor reserves except for the approved `Alt+B` and `Alt+D`
+ * application-boundary overrides. They open the task and decision boards
+ * before the editor can interpret those chords as word-back or word-delete.
+ * The CSI-u/reserved-key detector in `keybinding-manager.ts` stays as a safety
+ * net for user rebinds.
  */
 export const CLIO_APP_KEYBINDINGS = {
 	"clio.thinking.cycle": {
@@ -85,6 +89,16 @@ export const CLIO_APP_KEYBINDINGS = {
 		defaultKeys: "alt+w",
 		description: "Toggle the dispatch (workers) board overlay",
 	},
+	"clio.tasks.open": {
+		// Approved application-boundary override of pi-tui editor word-back.
+		defaultKeys: "alt+b",
+		description: "Open the composite session and operator task board",
+	},
+	"clio.decisions.open": {
+		// Approved application-boundary override of pi-tui editor word-delete.
+		defaultKeys: "alt+d",
+		description: "Open the settled interview decision board",
+	},
 	"clio.dispatch.background": {
 		// Ctrl+B alone is pi-tui's editor cursor-left, so the Claude Code chord
 		// cannot be the primary here. Alt+S ("send to background") keeps the app
@@ -108,14 +122,14 @@ export const CLIO_APP_KEYBINDINGS = {
 	"clio.tool.expand": {
 		defaultKeys: "alt+o",
 		description:
-			"Fold or unfold the newest tool call or worker block between its one-line summary and full details (no effect while /output verbose pins them open)",
+			"Fold or unfold the newest tool call or worker block between its one-line summary and full details, overriding the /output level for that block",
 	},
 	"clio.tool.expandAll": {
 		// Alt+Shift+letter is commonly consumed by OS keyboard-layout switching.
 		// Keep it discoverable, but pair it with the legacy-safe Ctrl+Alt form.
 		defaultKeys: ["ctrl+alt+o", "alt+shift+o"],
 		description:
-			"Fold or unfold every tool call and worker block at once (no effect while /output verbose pins them open)",
+			"Fold or unfold every tool call and worker block at once, overriding the /output level; changing /output clears the overrides",
 	},
 	"clio.tool.liveOutput": {
 		defaultKeys: "alt+p",
@@ -131,7 +145,7 @@ export const CLIO_APP_KEYBINDINGS = {
 		// Alt+Shift+R as a distinct key event.
 		defaultKeys: ["ctrl+alt+r", "alt+shift+r"],
 		description:
-			"Toggle all thinking blocks between hidden markers and full bodies (no effect while /output verbose pins them open)",
+			"Toggle all thinking blocks between hidden markers and full bodies, overriding the /output level; changing /output clears the overrides",
 	},
 	"clio.editor.external": {
 		defaultKeys: "alt+g",
@@ -139,7 +153,16 @@ export const CLIO_APP_KEYBINDINGS = {
 	},
 	"clio.message.followUp": {
 		defaultKeys: "alt+enter",
-		description: "Queue the current input as a follow-up delivered after the active run (Enter steers the run live)",
+		description:
+			"End of turn: queue the current input for delivery when the active run settles (Enter delivers it at the next slot, between tool batches)",
+	},
+	"clio.message.interrupt": {
+		// Alt+I keeps the app scheme and earns the Ctrl+G leader fallback. A
+		// Ctrl+Enter chord was rejected because legacy terminals send it as a
+		// plain Enter, which would turn every send into a cancel.
+		defaultKeys: "alt+i",
+		description:
+			"Interrupt: cancel the active run and deliver the current input now (refused while an attached dispatch runs or a permission ask is parked; the input then queues for the next slot)",
 	},
 	"clio.message.dequeue": {
 		defaultKeys: "alt+up",
@@ -155,9 +178,22 @@ export const CLIO_APP_KEYBINDINGS = {
 	},
 } as const satisfies KeybindingDefinitions;
 
-/** Full definition table = pi-tui editor/select defaults + Clio app ids. */
+/**
+ * Full definition table = pi-tui editor/select defaults + Clio app ids.
+ * pi-tui 0.84 supplies dedicated prompt-history actions but leaves them
+ * unbound for applications to place. Clio uses the readline-style Ctrl+P and
+ * Ctrl+N pair because its model cycling already lives on Alt+J and Alt+K.
+ */
 export const CLIO_KEYBINDINGS = {
 	...TUI_KEYBINDINGS,
+	"tui.editor.historyPrevious": {
+		...TUI_KEYBINDINGS["tui.editor.historyPrevious"],
+		defaultKeys: "ctrl+p",
+	},
+	"tui.editor.historyNext": {
+		...TUI_KEYBINDINGS["tui.editor.historyNext"],
+		defaultKeys: "ctrl+n",
+	},
 	...CLIO_APP_KEYBINDINGS,
 } as const satisfies KeybindingDefinitions;
 

package/src/domains/context/bootstrap-prompt.ts

@@ -3,7 +3,7 @@ import type { ProjectType } from "../session/workspace/project-type.js";
 import type { AdoptionScanResult } from "./adoption.js";
 import type { BootstrapStructuredOutput } from "./bootstrap.js";
 import { renderCodewikiDigest } from "./codewiki/digest.js";
-import type { Codewiki } from "./codewiki/indexer.js";
+import type { Codewiki } from "./codewiki/schema.js";
 import type { SiblingContextFile } from "./sibling-files.js";
 
 export const BOOTSTRAP_PROMPT = `You are the clio-coder bootstrap agent. Your job is to write the custom sections of CLIO-CODER.md for the project at <cwd>. CLIO-CODER.md is a lean, project-specific handbook that the clio-coder coding agent loads on every session, so write for an experienced engineer who has never seen this repository and is about to change it.

package/src/domains/context/bootstrap.ts

@@ -12,9 +12,10 @@ import {
 	scanAgentConfigs,
 } from "./adoption.js";
 import { type ClioMdSection, type ParsedClioMd, parseClioMd, serializeClioMd, tryReadClioMd } from "./clio-md.js";
-import { buildCodewiki, type Codewiki, writeCodewiki } from "./codewiki/indexer.js";
-import { computeFingerprint } from "./fingerprint.js";
-import { type ProjectMetadata, readProjectMetadata } from "./project-metadata.js";
+import { buildCodewikiCandidate, coordinateCodewikiWrite } from "./codewiki/coordinator.js";
+import type { Codewiki } from "./codewiki/schema.js";
+import type { Fingerprint } from "./fingerprint.js";
+import { hasTomlTable, type ProjectMetadata, readProjectMetadata } from "./project-metadata.js";
 import { renderPromptContext } from "./prompt-context.js";
 import type { SiblingContextFile } from "./sibling-files.js";
 import {
@@ -454,6 +455,71 @@ export function packageManager(cwd: string): PackageManager {
 /** A script whose command rewrites the tree cannot serve as a verification gate. */
 const MUTATING_SCRIPT_RE = /(?:^|\s)--(?:fix|write)(?:\s|$)/;
 
+/**
+ * First preset a human could actually invoke: named and not hidden. Hidden
+ * presets exist only to be inherited from, so naming one in the handbook would
+ * hand the agent a command CMake refuses to run.
+ */
+function cmakePresetName(presets: unknown, key: string): string | null {
+	if (typeof presets !== "object" || presets === null || Array.isArray(presets)) return null;
+	const list = (presets as Record<string, unknown>)[key];
+	if (!Array.isArray(list)) return null;
+	for (const entry of list) {
+		if ((entry as Record<string, unknown> | null)?.hidden === true) continue;
+		const name = stringField(entry, "name");
+		if (name !== null) return name;
+	}
+	return null;
+}
+
+/**
+ * CMake presets are the project's own declared configure/build/test recipes,
+ * the same authority package.json scripts carry for Node. A CMake tree without
+ * presets stays silent: nothing there declares a runnable command, and a
+ * guessed `cmake -B build` fails on exactly the toolchain-file and MPI-wrapper
+ * projects this tool targets. Configure, build, and test are each named
+ * independently: a project can declare a visible build preset without a
+ * visible configure preset (e.g. the configure preset is the hidden base
+ * every build preset inherits from), and that build command is still one the
+ * agent can run.
+ */
+function cmakeVerificationLines(cwd: string): string[] {
+	const presets = readJsonFile(join(cwd, "CMakePresets.json"));
+	if (presets === null) return [];
+	const configure = cmakePresetName(presets, "configurePresets");
+	const build = cmakePresetName(presets, "buildPresets");
+	const test = cmakePresetName(presets, "testPresets");
+	const lines: string[] = [];
+	if (configure !== null) lines.push(`Configure with \`cmake --preset ${configure}\`.`);
+	if (build !== null) lines.push(`Build with \`cmake --build --preset ${build}\`.`);
+	if (test !== null) lines.push(`Run tests with \`ctest --preset ${test}\`.`);
+	return lines;
+}
+
+/**
+ * Python has no single scripts manifest, so this names a runner only where the
+ * project declares one: a tox configuration declares `tox`, and a declared
+ * pytest configuration declares `pytest`. An undeclared layout stays silent
+ * rather than guessing `python -m unittest` at a repository that tests some
+ * other way. Tox wins when both are declared because it typically wraps the
+ * pytest run.
+ */
+function pythonVerificationLines(cwd: string): string[] {
+	let pyproject = "";
+	try {
+		pyproject = readFileSync(join(cwd, "pyproject.toml"), "utf8");
+	} catch {
+		pyproject = "";
+	}
+	if (existsSync(join(cwd, "tox.ini")) || hasTomlTable(pyproject, "tool.tox")) {
+		return ["Run `tox` before handoff."];
+	}
+	if (existsSync(join(cwd, "pytest.ini")) || hasTomlTable(pyproject, "tool.pytest.ini_options")) {
+		return ["Run `pytest` before handoff."];
+	}
+	return [];
+}
+
 function verificationSection(cwd: string): ClioMdSection | null {
 	const scripts = packageScripts(cwd);
 	const pm = packageManager(cwd);
@@ -487,6 +553,20 @@ function verificationSection(cwd: string): ClioMdSection | null {
 	if (hasScript("ci")) {
 		lines.push(`Use ${command("ci")} for the full local gate before committing broad or shared behavior changes.`);
 	}
+	lines.push(...cmakeVerificationLines(cwd));
+	// Cargo's commands are defined by the toolchain, not by each project, so
+	// naming them for any Cargo workspace carries the same confidence as a
+	// declared package script.
+	if (existsSync(join(cwd, "Cargo.toml"))) {
+		lines.push("Run `cargo build` and `cargo test` before handoff.");
+	}
+	// Go's commands are defined by the toolchain, not by each project, so
+	// naming them for any module carries the same confidence as a declared
+	// package script.
+	if (existsSync(join(cwd, "go.mod"))) {
+		lines.push("Run `go build ./...` and `go test ./...` before handoff.");
+	}
+	lines.push(...pythonVerificationLines(cwd));
 	if (lines.length === 0) return null;
 	return { title: "Verification expectations", body: lines.join(" ") };
 }
@@ -684,20 +764,21 @@ function stabilizeGeneratedOutput(
 
 /**
  * The handbook sections whose every fact is read straight off the codewiki index:
- * how many files it holds, which modules anchor it, where the mass sits. They are
- * the only sections nothing but the index can author, and equally the only ones
- * that are wrong the moment the tree moves, so `context refresh` re-derives them
- * in place and leaves every other section to its human or model author.
+ * which modules anchor it and where the mass sits. They are the only sections
+ * nothing but the index can author, and equally the only ones that are wrong the
+ * moment the tree moves, so `context refresh` re-derives them in place and leaves
+ * every other section to its human or model author. An exact file count stays
+ * out: the handbook persists between refreshes while the tree keeps moving, so a
+ * precise number is falsified by any single added file and carries no
+ * navigational value the entry-point list does not.
  */
 export function codewikiSections(codewiki: Codewiki): ClioMdSection[] {
 	const sections: ClioMdSection[] = [];
 	const entryPoints = codewikiEntryPoints(codewiki, 8);
-	const indexedCount = indexedSourceFileCount(codewiki);
 	if (entryPoints.length > 0) {
 		sections.push({
 			title: "Context retrieval",
 			body: [
-				`The codewiki currently indexes ${indexedCount} source file${indexedCount === 1 ? "" : "s"}.`,
 				`Start orientation with these indexed entry points: ${entryPoints.map((entry) => `\`${entry}\``).join(", ")}.`,
 				"Use `code_nav` (modes: symbol, path, entries, outline, deps, dependents, wiki) before broad reads when the task is navigational.",
 			].join(" "),
@@ -1041,10 +1122,10 @@ function writeProjectState(
 	adoption: AdoptionScanResult,
 	recordAdoption: boolean,
 	codewikiVersion: number,
+	fingerprint: Fingerprint,
 	generation: BootstrapGenerationTelemetry,
 	generated: boolean,
 ): string {
-	const finalFingerprint = computeFingerprint(cwd);
 	const statePath = resolveStatePath(cwd);
 	const prev = readClioState(cwd);
 	// lastBootstrap describes how the CLIO-CODER.md on disk was produced, not what the
@@ -1059,7 +1140,7 @@ function writeProjectState(
 	writeClioState(cwd, {
 		version: 1,
 		projectType,
-		fingerprint: finalFingerprint,
+		fingerprint,
 		codewikiVersion,
 		lastInitAt: now.toISOString(),
 		lastSessionAt: now.toISOString(),
@@ -1082,13 +1163,13 @@ function persistCodewikiForGeneration(
 	projectType: ProjectType,
 	indexedAt: string,
 	codewiki: Codewiki,
+	fingerprint: Fingerprint,
 ): void {
-	writeCodewiki(cwd, codewiki);
 	const prev = readClioState(cwd);
 	writeClioState(cwd, {
 		version: 1,
 		projectType,
-		fingerprint: computeFingerprint(cwd, codewiki),
+		fingerprint,
 		codewikiVersion: codewiki.version,
 		...(prev?.contextSources ? { contextSources: prev.contextSources } : {}),
 		...(prev?.contextSourceHash ? { contextSourceHash: prev.contextSourceHash } : {}),
@@ -1176,7 +1257,22 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 	// Index the repository before generation so the generator can ground CLIO-CODER.md
 	// in the real structure (entry points, key modules), not just sibling prose.
 	progress(input, { phase: "codewiki", status: "started", message: "building codewiki index" });
-	const codewiki = await buildCodewiki({ cwd, language: projectType, generatedAt: indexedAt });
+	let codewiki: Codewiki;
+	let codewikiFingerprint: Fingerprint;
+	if (input.preview === true) {
+		const candidate = await buildCodewikiCandidate(cwd, projectType);
+		codewiki = candidate.codewiki;
+		codewikiFingerprint = candidate.fingerprint;
+	} else {
+		const coordinated = await coordinateCodewikiWrite(cwd, () => ({ kind: "build", cwd, language: projectType }), {
+			beforeCommit: (_result, workspace) => ensureGitignore(workspace, input),
+			afterCommit: ({ codewiki: committed, fingerprint }, workspace) =>
+				persistCodewikiForGeneration(workspace, projectType, indexedAt, committed, fingerprint),
+		});
+		if (!coordinated) throw new Error("codewiki bootstrap transaction did not commit");
+		codewiki = coordinated.codewiki;
+		codewikiFingerprint = coordinated.worker.fingerprint;
+	}
 	const codewikiEntryCount = indexedSourceFileCount(codewiki);
 	progress(input, {
 		phase: "codewiki",
@@ -1185,10 +1281,6 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 		current: codewikiEntryCount,
 		total: codewikiEntryCount,
 	});
-	if (input.preview !== true) {
-		await ensureGitignore(cwd, input);
-		persistCodewikiForGeneration(cwd, projectType, indexedAt, codewiki);
-	}
 	const hadClioMd = existsSync(join(cwd, "CLIO-CODER.md"));
 	const useExistingClioMdAsSource = hadClioMd && input.rewriteClioMd !== true;
 	const existingClioMdText = useExistingClioMdAsSource ? readExistingClioMdText(cwd) : null;
@@ -1362,6 +1454,7 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 		adoption,
 		adoptionApplied,
 		codewiki.version,
+		codewikiFingerprint,
 		generation,
 		shouldGenerate,
 	);

package/src/domains/context/clear.ts

@@ -2,6 +2,7 @@ import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 import type { BootstrapIo } from "./bootstrap.js";
+import { coordinateCodewikiExclusive } from "./codewiki/coordinator.js";
 
 export interface RunContextClearInput {
 	cwd?: string;
@@ -25,7 +26,7 @@ const ACCUMULATED_CONTEXT_PATHS = [
 ] as const;
 /**
  * Kept, and said to be kept. `.clio-coder/wiki` is Clio-written rather than
- * operator-authored, so it does not belong with the handbook and the overlay
+ * operator-authored, so it does not belong with the handbooks and the overlay
  * directories on merit; it is listed because the reset reports exactly two
  * categories and a reader takes anything absent from both to be gone. It is the
  * most expensive artifact in `.clio-coder` (one model dispatch per page), and leaving
@@ -33,6 +34,7 @@ const ACCUMULATED_CONTEXT_PATHS = [
  */
 const PRESERVED_CONTEXT_PATHS = [
 	"CLIO-CODER.md",
+	"CLIO-CODER.override.md",
 	".clio-coder/agents",
 	".clio-coder/skills",
 	".clio-coder/wiki",
@@ -61,18 +63,21 @@ export async function runContextClear(input: RunContextClearInput = {}): Promise
 		return { action: "cancelled", removed: [], preserved: [...PRESERVED_CONTEXT_PATHS] };
 	}
 
-	const removed: string[] = [];
-	for (const relPath of ACCUMULATED_CONTEXT_PATHS) removeIfPresent(cwd, relPath, removed);
+	const { removed, preserved } = await coordinateCodewikiExclusive(cwd, async (workspace) => {
+		const removed: string[] = [];
+		for (const relPath of ACCUMULATED_CONTEXT_PATHS) removeIfPresent(workspace, relPath, removed);
 
-	const preserved = [...PRESERVED_CONTEXT_PATHS];
-	if (input.all === true) {
-		const confirmedAll = await input.confirmAll?.();
-		if (confirmedAll === true) {
-			removeIfPresent(cwd, "CLIO-CODER.md", removed);
-			const index = preserved.indexOf("CLIO-CODER.md");
-			if (index !== -1) preserved.splice(index, 1);
+		const preserved = [...PRESERVED_CONTEXT_PATHS];
+		if (input.all === true) {
+			const confirmedAll = await input.confirmAll?.();
+			if (confirmedAll === true) {
+				removeIfPresent(workspace, "CLIO-CODER.md", removed);
+				const index = preserved.indexOf("CLIO-CODER.md");
+				if (index !== -1) preserved.splice(index, 1);
+			}
 		}
-	}
+		return { removed, preserved };
+	});
 
 	out(
 		input.io,

package/src/domains/context/clio-md.ts

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 
 export interface ClioMdFingerprintFooter {
 	initAt: string;
@@ -26,6 +26,25 @@ export interface ParsedClioMd {
 	warnings: string[];
 }
 
+export interface LoadedClioMdFile {
+	path: string;
+	value: ParsedClioMd;
+}
+
+export interface ClioMdLoadError {
+	path: string;
+	error: string;
+}
+
+export interface LoadedProjectClioMd {
+	/** Effective files in ancestor-to-descendant order. */
+	files: LoadedClioMdFile[];
+	/** Selected files that could not be read or parsed. */
+	errors: ClioMdLoadError[];
+	/** The layered effective handbook, or null when no selected file parsed. */
+	value: ParsedClioMd | null;
+}
+
 export type ClioMdParseResult = { ok: true; value: ParsedClioMd } | { ok: false; errors: string[]; warnings: string[] };
 
 export interface SerializeClioMdInput {
@@ -294,7 +313,11 @@ export function renderProjectTypeFragment(projectType: string): string {
 	return `<project-type>${projectType}</project-type>`;
 }
 
-export function renderProjectContextFragment(parsed: ParsedClioMd): string {
+function escapeXmlAttribute(value: string): string {
+	return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function renderProjectContextFragment(parsed: ParsedClioMd, sourcePath?: string): string {
 	const sections: string[] = [`# ${parsed.projectName}`, parsed.identity];
 	if (parsed.conventions.length > 0) {
 		sections.push("## Conventions", ...parsed.conventions.map((item) => `- ${item}`));
@@ -308,20 +331,99 @@ export function renderProjectContextFragment(parsed: ParsedClioMd): string {
 	if (parsed.importedAgentContext) {
 		sections.push("## Imported agent context", parsed.importedAgentContext);
 	}
-	return `<project-context>\n${sections.join("\n\n")}\n</project-context>`;
+	const source = sourcePath ? ` path="${escapeXmlAttribute(sourcePath)}"` : "";
+	return `<project-context${source}>\n${sections.join("\n\n")}\n</project-context>`;
 }
 
-export function tryReadClioMd(cwd: string): { ok: true; value: ParsedClioMd } | { ok: false; error: string } | null {
-	const filePath = join(cwd, "CLIO-CODER.md");
-	if (!existsSync(filePath)) return null;
+const PROJECT_CONTEXT_CANDIDATES = ["CLIO-CODER.override.md", "CLIO-CODER.md"] as const;
+
+function selectedClioMdPath(directory: string): string | null {
+	for (const filename of PROJECT_CONTEXT_CANDIDATES) {
+		const filePath = join(directory, filename);
+		if (!existsSync(filePath)) continue;
+		try {
+			if (statSync(filePath).isFile()) return filePath;
+		} catch {
+			// Preserve candidate precedence and let the read below own the
+			// actionable error instead of silently falling back to the base file.
+			return filePath;
+		}
+	}
+	return null;
+}
+
+function readClioMdPath(filePath: string): { ok: true; value: ParsedClioMd } | { ok: false; error: string } {
 	let content: string;
 	try {
 		content = readFileSync(filePath, "utf8");
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		return { ok: false, error: message };
+		return { ok: false, error: err instanceof Error ? err.message : String(err) };
 	}
 	const parsed = parseClioMd(content);
 	if (!parsed.ok) return { ok: false, error: parsed.errors.join("; ") };
 	return { ok: true, value: parsed.value };
 }
+
+function mergeClioMdFiles(files: ReadonlyArray<LoadedClioMdFile>): ParsedClioMd | null {
+	const nearest = files.at(-1)?.value;
+	if (!nearest) return null;
+	return {
+		projectName: nearest.projectName,
+		identity: files.map((file) => file.value.identity).join("\n\n"),
+		conventions: files.flatMap((file) => file.value.conventions),
+		invariants: files.flatMap((file) => file.value.invariants),
+		sections: files.flatMap((file) => file.value.sections),
+		importedAgentContext:
+			files
+				.map((file) => file.value.importedAgentContext)
+				.filter((value): value is string => value !== null)
+				.join("\n\n") || null,
+		fingerprint: nearest.fingerprint,
+		firstInit: nearest.firstInit,
+		warnings: files.flatMap((file) => file.value.warnings),
+	};
+}
+
+/**
+ * Load effective project handbooks from filesystem root through `cwd`.
+ * Candidate selection follows pi-coding-agent 0.84's
+ * `loadProjectContextFiles`: an override wins over the base file in the same
+ * directory. Clio's structured override additionally resets the inherited
+ * handbook chain for that subtree, as required by the project-context
+ * contract. Handbooks below the override may add new layers.
+ */
+export function loadProjectClioMd(cwd: string): LoadedProjectClioMd {
+	const directories: string[] = [];
+	let directory = resolve(cwd);
+	while (true) {
+		directories.unshift(directory);
+		const parent = dirname(directory);
+		if (parent === directory) break;
+		directory = parent;
+	}
+
+	const selectedPaths: string[] = [];
+	for (const current of directories) {
+		const selected = selectedClioMdPath(current);
+		if (!selected) continue;
+		if (basename(selected) === "CLIO-CODER.override.md") {
+			selectedPaths.length = 0;
+		}
+		selectedPaths.push(selected);
+	}
+
+	const files: LoadedClioMdFile[] = [];
+	const errors: ClioMdLoadError[] = [];
+	for (const filePath of selectedPaths) {
+		const read = readClioMdPath(filePath);
+		if (read.ok) files.push({ path: filePath, value: read.value });
+		else errors.push({ path: filePath, error: read.error });
+	}
+	return { files, errors, value: mergeClioMdFiles(files) };
+}
+
+export function tryReadClioMd(cwd: string): { ok: true; value: ParsedClioMd } | { ok: false; error: string } | null {
+	const filePath = join(cwd, "CLIO-CODER.md");
+	if (!existsSync(filePath)) return null;
+	return readClioMdPath(filePath);
+}