@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/context/wiki/meta.ts

@@ -0,0 +1,221 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../../core/safe-resource-write.js";
+import { type WikiPage, wikiDir, wikiMarkdownFilesInDir } from "./layout.js";
+import type { ResolvedWikiDepth, WikiDepth, WikiPlan } from "./plan.js";
+import { sanitizeWikiPlan } from "./plan-store.js";
+
+/**
+ * What the generator observed and chose for this artifact. Page and section
+ * counts are outcomes, not targets: they record what the repository produced
+ * at the resolved depth so an operator can see whether a run finished.
+ */
+export interface WikiMetaGeneration {
+	requestedDepth: WikiDepth;
+	depth: ResolvedWikiDepth;
+	sourceFiles: number;
+	sourceLines: number;
+	/** Pages the plan calls for. */
+	pagesPlanned: number;
+	/** Pages the plan records as written. Below `pagesPlanned` means work remains. */
+	pagesWritten: number;
+}
+
+export interface WikiMeta {
+	version: 1;
+	updatedAt: string;
+	gitHead: string | null;
+	sourceTreeHash?: string;
+	model: string;
+	contentHash: string;
+	pages: WikiPage[];
+	generation?: WikiMetaGeneration;
+	/**
+	 * The page plan this wiki was built from. Carrying it here is what lets a
+	 * later run resume: it knows the intended structure and which pages are
+	 * still owed without re-deriving either.
+	 */
+	plan?: WikiPlan;
+}
+
+export type WikiMetaValidation = { ok: true; value: WikiMeta } | { ok: false; problems: string[] };
+
+function compareStrings(a: string, b: string): number {
+	return a.localeCompare(b);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringValue(value: unknown): string | null {
+	return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function nonNegativeSafeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+const REQUESTED_DEPTHS: ReadonlyArray<WikiDepth> = ["auto", "simple", "medium", "detailed"];
+const RESOLVED_DEPTHS: ReadonlyArray<ResolvedWikiDepth> = ["simple", "medium", "detailed"];
+
+/**
+ * Parse the generation block, or drop it. It is a diagnostic record, so a
+ * shape this version of Clio does not recognize costs an operator a status
+ * line; treating it as corruption would instead discard a usable wiki and
+ * silently regenerate it from scratch.
+ */
+function parseGeneration(value: unknown): WikiMetaGeneration | undefined {
+	if (!isRecord(value)) return undefined;
+	const { requestedDepth, depth, sourceFiles, sourceLines, pagesPlanned, pagesWritten } = value;
+	if (
+		!REQUESTED_DEPTHS.includes(requestedDepth as WikiDepth) ||
+		!RESOLVED_DEPTHS.includes(depth as ResolvedWikiDepth) ||
+		!nonNegativeSafeInteger(sourceFiles) ||
+		!nonNegativeSafeInteger(sourceLines) ||
+		!nonNegativeSafeInteger(pagesPlanned) ||
+		!nonNegativeSafeInteger(pagesWritten)
+	) {
+		return undefined;
+	}
+	return {
+		requestedDepth: requestedDepth as WikiDepth,
+		depth: depth as ResolvedWikiDepth,
+		sourceFiles,
+		sourceLines,
+		pagesPlanned,
+		pagesWritten,
+	};
+}
+
+function normalizePages(pages: ReadonlyArray<WikiPage>): WikiPage[] {
+	return pages
+		.map((page) => ({ path: page.path, title: page.title, ...(page.summary ? { summary: page.summary } : {}) }))
+		.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function wikiMetaPath(cwd: string): string {
+	return join(wikiDir(cwd), "meta.json");
+}
+
+export function currentWikiGitHead(cwd: string): string | null {
+	try {
+		return execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+			cwd,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+
+export function validateWikiMeta(value: unknown): WikiMetaValidation {
+	const problems: string[] = [];
+	if (!isRecord(value)) {
+		return { ok: false, problems: ["meta must be a JSON object"] };
+	}
+	if (value.version !== 1) problems.push("version must be 1");
+	const updatedAt = stringValue(value.updatedAt);
+	if (!updatedAt) problems.push("updatedAt must be a non-empty string");
+	const gitHead = value.gitHead;
+	if (gitHead !== null && typeof gitHead !== "string") problems.push("gitHead must be a string or null");
+	const sourceTreeHash = value.sourceTreeHash;
+	if (sourceTreeHash !== undefined && (typeof sourceTreeHash !== "string" || !/^[a-f0-9]{64}$/.test(sourceTreeHash))) {
+		problems.push("sourceTreeHash must be a sha256 hex string when present");
+	}
+	const model = stringValue(value.model);
+	if (!model) problems.push("model must be a non-empty string");
+	const contentHash = stringValue(value.contentHash);
+	if (!contentHash || !/^[a-f0-9]{64}$/.test(contentHash)) {
+		problems.push("contentHash must be a sha256 hex string");
+	}
+	if (!Array.isArray(value.pages)) {
+		problems.push("pages must be an array");
+	} else {
+		for (const [index, page] of value.pages.entries()) {
+			if (!isRecord(page)) {
+				problems.push(`pages[${index}] must be an object`);
+				continue;
+			}
+			if (!stringValue(page.path)) problems.push(`pages[${index}].path must be a non-empty string`);
+			if (!stringValue(page.title)) problems.push(`pages[${index}].title must be a non-empty string`);
+		}
+	}
+	if (problems.length > 0) return { ok: false, problems };
+	const generation = parseGeneration(value.generation);
+	const plan = sanitizeWikiPlan(value.plan, undefined, { trustStatus: true });
+	return {
+		ok: true,
+		value: {
+			version: 1,
+			updatedAt: updatedAt as string,
+			gitHead: gitHead as string | null,
+			...(sourceTreeHash !== undefined ? { sourceTreeHash: sourceTreeHash as string } : {}),
+			model: model as string,
+			contentHash: contentHash as string,
+			pages: normalizePages(value.pages as WikiPage[]),
+			...(generation !== undefined ? { generation } : {}),
+			...(plan !== null ? { plan } : {}),
+		},
+	};
+}
+
+export function isWikiMeta(value: unknown): value is WikiMeta {
+	return validateWikiMeta(value).ok;
+}
+
+export function readWikiMeta(cwd: string): WikiMeta | null {
+	const filePath = wikiMetaPath(cwd);
+	if (!existsSync(filePath)) return null;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(readFileSync(filePath, "utf8"));
+	} catch {
+		return null;
+	}
+	const validation = validateWikiMeta(parsed);
+	return validation.ok ? validation.value : null;
+}
+
+export function writeWikiMeta(cwd: string, meta: WikiMeta): void {
+	const normalized: WikiMeta = {
+		version: 1,
+		updatedAt: meta.updatedAt,
+		gitHead: meta.gitHead,
+		...(meta.sourceTreeHash ? { sourceTreeHash: meta.sourceTreeHash } : {}),
+		model: meta.model,
+		contentHash: meta.contentHash,
+		pages: normalizePages(meta.pages),
+		...(meta.generation !== undefined ? { generation: { ...meta.generation } } : {}),
+		...(meta.plan !== undefined ? { plan: meta.plan } : {}),
+	};
+	safeResourceWrite(wikiMetaPath(cwd), `${JSON.stringify(normalized)}\n`, { encoding: "utf8" });
+}
+
+/**
+ * Content hash over the whole page tree. Nested sections mean the walk has to
+ * recurse; the relative path is folded in so moving a page between sections
+ * changes the hash even when its bytes do not.
+ */
+export function computeWikiContentHashOfDir(dir: string): string {
+	const hash = createHash("sha256");
+	for (const relPath of wikiMarkdownFilesInDir(dir).sort(compareStrings)) {
+		let text = "";
+		try {
+			text = readFileSync(join(dir, relPath), "utf8");
+		} catch {
+			text = "";
+		}
+		hash.update(`${relPath}\0${text.length}\0`);
+		hash.update(text);
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+
+export function computeWikiContentHash(cwd: string): string {
+	return computeWikiContentHashOfDir(wikiDir(cwd));
+}

package/src/domains/context/wiki/plan-store.ts

@@ -0,0 +1,217 @@
+/**
+ * Reading, sanitizing, and checkpointing the page plan.
+ *
+ * The plan file is the one piece of state that survives an interrupted run, so
+ * every function here is total: a plan that cannot be parsed, or an authored
+ * rewrite that is malformed, degrades to the deterministic candidate instead of
+ * ending the run. Progress is harness-owned: it is believed when read back from
+ * the harness's own checkpoint and discarded when read from a document a model
+ * just rewrote, so a planning pass cannot mark its own pages finished.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../../core/safe-resource-write.js";
+import { isGeneratedWikiFile, WIKI_PLAN_FILE } from "./layout.js";
+import type { WikiPageStatus, WikiPlan, WikiPlanPage } from "./plan.js";
+
+/** Dispatches one page may receive across all runs before it is left alone. */
+export const MAX_PAGE_ATTEMPTS = 3;
+
+/** Longest authored intent kept, so one bad entry cannot bloat a page prompt. */
+const MAX_INTENT_CHARS = 600;
+
+/** Most pages a plan may carry, bounding an authored rewrite's blast radius. */
+const MAX_PLAN_PAGES = 200;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function usableString(value: unknown): string | null {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function stringList(value: unknown, limit: number): string[] {
+	if (!Array.isArray(value)) return [];
+	const out: string[] = [];
+	for (const entry of value) {
+		const usable = usableString(entry);
+		if (usable && !out.includes(usable)) out.push(usable);
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+
+/**
+ * A page path a writer may be pointed at: relative, Markdown, inside the wiki
+ * root, and not one of the generated navigation files. Returns null for
+ * anything else, which drops the entry rather than failing the plan.
+ */
+export function sanitizePagePath(value: unknown): string | null {
+	const raw = usableString(value);
+	if (raw === null) return null;
+	const normalized = raw.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+	if (!normalized.endsWith(".md") || normalized.length > 200) return null;
+	const segments = normalized.split("/");
+	if (
+		segments.some((segment) => segment.length === 0 || segment === "." || segment === ".." || segment.startsWith("."))
+	) {
+		return null;
+	}
+	if (isGeneratedWikiFile(normalized)) return null;
+	return normalized;
+}
+
+function wikiPlanPath(dir: string): string {
+	return join(dir, WIKI_PLAN_FILE);
+}
+
+function parsedStatus(value: unknown): WikiPageStatus | null {
+	return value === "written" || value === "pending" ? value : null;
+}
+
+function parsedAttempts(value: unknown): number | null {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+export interface SanitizeWikiPlanOptions {
+	/**
+	 * Whether the recorded progress in this document may be believed.
+	 *
+	 * True for the harness's own checkpoint and for the plan stored in metadata:
+	 * that is where progress is written, so reading it back is how a run resumes.
+	 * False for a document a model just rewrote, because a planning pass that
+	 * marked its pages finished would skip every one of them. Progress the
+	 * harness already knows, passed as `previous`, always wins over both.
+	 */
+	trustStatus: boolean;
+}
+
+/**
+ * Parse a plan, preferring harness-owned progress from `previous` for any page
+ * whose path survived. Returns null when nothing usable is left, so the caller
+ * falls back to the candidate plan.
+ */
+export function sanitizeWikiPlan(
+	value: unknown,
+	previous?: WikiPlan,
+	options: SanitizeWikiPlanOptions = { trustStatus: true },
+): WikiPlan | null {
+	if (!isRecord(value) || !Array.isArray(value.pages)) return null;
+	const priorByPath = new Map((previous?.pages ?? []).map((page) => [page.path, page] as const));
+	const pages: WikiPlanPage[] = [];
+	const seen = new Set<string>();
+	for (const entry of value.pages) {
+		if (pages.length >= MAX_PLAN_PAGES) break;
+		if (!isRecord(entry)) continue;
+		const path = sanitizePagePath(entry.path);
+		if (path === null || seen.has(path)) continue;
+		const intent = usableString(entry.intent);
+		const prior = priorByPath.get(path);
+		const recorded = options.trustStatus ? parsedStatus(entry.status) : null;
+		const recordedAttempts = options.trustStatus ? parsedAttempts(entry.attempts) : null;
+		seen.add(path);
+		pages.push({
+			path,
+			title: usableString(entry.title) ?? path.replace(/\.md$/, ""),
+			intent: intent === null ? "" : intent.slice(0, MAX_INTENT_CHARS),
+			sources: stringList(entry.sources, 16),
+			status: prior?.status ?? recorded ?? "pending",
+			attempts: prior?.attempts ?? recordedAttempts ?? 0,
+		});
+	}
+	if (pages.length === 0) return null;
+	return { version: 1, overview: usableString(value.overview) ?? previous?.overview ?? "", pages };
+}
+
+function readPlanDocument(dir: string): unknown {
+	const filePath = wikiPlanPath(dir);
+	if (!existsSync(filePath)) return undefined;
+	try {
+		return JSON.parse(readFileSync(filePath, "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Read the harness's checkpoint. Returns null when absent, unreadable, or
+ * unusable.
+ */
+export function readWikiPlanFile(dir: string, previous?: WikiPlan): WikiPlan | null {
+	const document = readPlanDocument(dir);
+	return document === undefined ? null : sanitizeWikiPlan(document, previous, { trustStatus: true });
+}
+
+/**
+ * Read the plan file as a document a planning pass just rewrote: its structure
+ * is taken, its progress is not.
+ */
+export function readAuthoredWikiPlan(dir: string, previous: WikiPlan): WikiPlan | null {
+	const document = readPlanDocument(dir);
+	return document === undefined ? null : sanitizeWikiPlan(document, previous, { trustStatus: false });
+}
+
+export function writeWikiPlanFile(dir: string, plan: WikiPlan): void {
+	safeResourceWrite(wikiPlanPath(dir), `${JSON.stringify(plan, null, 2)}\n`, { encoding: "utf8" });
+}
+
+/**
+ * Candidate pages for areas no existing page covers.
+ *
+ * These are offered to a planning pass, never appended to a settled plan. The
+ * index proposes paths derived from directory names; a planner routinely
+ * renames and regroups them, so appending by path would grow a second, machine-
+ * named copy of coverage that already exists. An area counts as covered when
+ * some page claims one of its sources, whatever that page ended up being called.
+ */
+export function unclaimedCandidates(
+	plan: WikiPlan,
+	candidate: WikiPlan,
+	pageSources: ReadonlyMap<string, ReadonlyArray<string>> = new Map(),
+): WikiPlanPage[] {
+	const knownPaths = new Set(plan.pages.map((page) => page.path));
+	const claimed = new Set<string>();
+	for (const page of plan.pages) {
+		for (const source of [...page.sources, ...(pageSources.get(page.path) ?? [])]) claimed.add(source);
+	}
+	return candidate.pages.filter(
+		(page) => !knownPaths.has(page.path) && !page.sources.some((source) => claimed.has(source)),
+	);
+}
+
+export interface ScopeUpdateInput {
+	plan: WikiPlan;
+	/** Repository-relative paths that changed since the wiki was last written. */
+	changedPaths: ReadonlySet<string>;
+	/** Wiki-relative page paths that exist on disk right now. */
+	existingPages: ReadonlySet<string>;
+	/** Per-page source paths drawn from each page's front matter. */
+	pageSources: ReadonlyMap<string, ReadonlyArray<string>>;
+}
+
+/**
+ * Decide what an update run owes. A page is rewritten when a source it claims
+ * has changed or when its file is missing; everything else is already current
+ * and is skipped. This is what replaces asking a model to guess which pages a
+ * diff invalidates: the answer is computed from the sources each page recorded
+ * in its own front matter.
+ */
+export function scopePlanForUpdate(input: ScopeUpdateInput): WikiPlan {
+	const changedPrefixes = [...input.changedPaths];
+	const pages = input.plan.pages.map((page): WikiPlanPage => {
+		if (!input.existingPages.has(page.path)) return { ...page, status: "pending", attempts: 0 };
+		const claimed = [...(input.pageSources.get(page.path) ?? []), ...page.sources];
+		const touched = claimed.some((source) =>
+			changedPrefixes.some((changed) => changed === source || changed.startsWith(`${source}/`)),
+		);
+		return touched ? { ...page, status: "pending", attempts: 0 } : { ...page, status: "written" };
+	});
+	return { ...input.plan, pages };
+}
+
+/** Pages this run still owes, in plan order, excluding ones already exhausted. */
+export function pendingPages(plan: WikiPlan): WikiPlanPage[] {
+	return plan.pages.filter((page) => page.status !== "written" && page.attempts < MAX_PAGE_ATTEMPTS);
+}

package/src/domains/context/wiki/plan.ts

@@ -0,0 +1,250 @@
+/**
+ * The page plan: the wiki's skeleton, as an artifact rather than a prompt
+ * sentence.
+ *
+ * A plan names every page the wiki will contain, what each page must document,
+ * and the source files that ground it. It is built deterministically from the
+ * codewiki index, so a usable plan exists before any model runs; a planning
+ * dispatch may then merge, split, rename, drop, or re-anchor entries by
+ * rewriting `_plan.json` in the staging tree. A malformed rewrite falls back to
+ * the candidate rather than failing the run.
+ *
+ * The plan is also the run's checkpoint. Each entry carries its own status, so
+ * a run that ends early leaves a record of exactly which pages are still owed,
+ * and the next run writes only those. Nothing here targets a page count: how
+ * many pages a repository gets follows from how many substantial areas the
+ * index finds at the requested depth.
+ */
+
+import type { Codewiki, CodewikiFile } from "../codewiki/indexer.js";
+
+export type WikiDepth = "auto" | "simple" | "medium" | "detailed";
+export type ResolvedWikiDepth = Exclude<WikiDepth, "auto">;
+
+export type WikiPageStatus = "pending" | "written";
+
+export interface WikiPlanPage {
+	/** POSIX-relative page path inside the wiki root. */
+	path: string;
+	title: string;
+	/** What this page must document, in one or two sentences. */
+	intent: string;
+	/** Repository-relative source files that ground the page. */
+	sources: string[];
+	/** Harness-owned: whether this page has been written in a completed dispatch. */
+	status: WikiPageStatus;
+	/** Harness-owned: how many dispatches have tried to write this page. */
+	attempts: number;
+}
+
+export interface WikiPlan {
+	version: 1;
+	/** One paragraph describing what this repository is; opens the generated quickstart. */
+	overview: string;
+	pages: WikiPlanPage[];
+}
+
+export interface WikiGenerationPlan {
+	requestedDepth: WikiDepth;
+	depth: ResolvedWikiDepth;
+	sourceFiles: number;
+	sourceLines: number;
+	/** The candidate skeleton derived from the index at this depth. */
+	plan: WikiPlan;
+}
+
+/**
+ * How finely a repository is decomposed at each depth.
+ *
+ * `areaDepth` is how many directory segments make an area, so depth changes the
+ * granularity of the decomposition itself: at 1 the whole of `src` is one area,
+ * at 3 each `src/domains/<name>` is. `areaShare` and `minAreaLines` then drop
+ * areas too small to carry a page, folding them into the nearest ancestor.
+ *
+ * Both are decomposition thresholds, not page targets. Granularity is what
+ * scales with repository size; the resulting page count is whatever the
+ * repository's shape produces at that granularity, and is never something a
+ * writer is told to hit.
+ */
+export const WIKI_DEPTH_STRATEGY: Record<ResolvedWikiDepth, DepthStrategy> = {
+	simple: { areaDepth: 1, areaShare: 0.08, minAreaLines: 400 },
+	medium: { areaDepth: 2, areaShare: 0.03, minAreaLines: 250 },
+	detailed: { areaDepth: 3, areaShare: 0.008, minAreaLines: 150 },
+};
+
+export interface DepthStrategy {
+	areaDepth: number;
+	areaShare: number;
+	minAreaLines: number;
+}
+
+/** Most source files named on one page's prompt. Keeps a page dispatch small. */
+const MAX_PAGE_SOURCES = 8;
+
+interface Area {
+	key: string;
+	files: CodewikiFile[];
+	lines: number;
+}
+
+/**
+ * The area a file belongs to: its first `maxDepth` directory segments. The
+ * filename is dropped first, so a file sitting directly in `src` joins the
+ * `src` area instead of becoming an area of its own named after itself.
+ */
+function areaForPath(path: string, maxDepth: number): string {
+	const directories = path.split("/").filter(Boolean).slice(0, -1);
+	if (directories.length === 0) return ".";
+	return directories.slice(0, Math.max(1, maxDepth)).join("/");
+}
+
+function classifyDepth(sourceFiles: number, sourceLines: number): ResolvedWikiDepth {
+	if (sourceFiles <= 150 && sourceLines <= 30_000) return "simple";
+	if (sourceFiles <= 800 && sourceLines <= 150_000) return "medium";
+	return "detailed";
+}
+
+function slugSegment(segment: string): string {
+	const slug = segment
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return slug.length > 0 ? slug : "section";
+}
+
+/**
+ * Meaningful segments of an area: the ones that name a documentation section.
+ * A leading `src/` describes the language's layout rather than a section, so it
+ * is dropped and `src/domains/dispatch` becomes `domains/dispatch`. An area
+ * that is only `src`, or the repository root, has no such segments and gets a
+ * name of its own.
+ */
+function areaSegments(area: string): string[] {
+	const parts = area.split("/").filter((part) => part.length > 0 && part !== ".");
+	if (parts.length === 0) return ["root"];
+	if (parts[0] !== "src") return parts;
+	return parts.length === 1 ? ["source"] : parts.slice(1);
+}
+
+/** Turn an index area into a page path; nesting follows the repository's. */
+export function pagePathForArea(area: string): string {
+	return `${areaSegments(area).map(slugSegment).join("/")}.md`;
+}
+
+function titleForArea(area: string): string {
+	const name = areaSegments(area).join(" ").replace(/[-_]+/g, " ").trim();
+	return name.length > 0 ? name.charAt(0).toUpperCase() + name.slice(1) : "Overview";
+}
+
+/** Rank an area's files so the ones a writer must read appear first. */
+function rankedSources(files: ReadonlyArray<CodewikiFile>): string[] {
+	return [...files]
+		.sort((a, b) => {
+			const roleRank = (file: CodewikiFile): number => (file.role === "entry" ? 0 : file.role === "test" ? 2 : 1);
+			return roleRank(a) - roleRank(b) || b.loc - a.loc || a.path.localeCompare(b.path);
+		})
+		.slice(0, MAX_PAGE_SOURCES)
+		.map((file) => file.path);
+}
+
+function collectAreas(source: ReadonlyArray<CodewikiFile>, areaDepth: number): Area[] {
+	const byKey = new Map<string, Area>();
+	for (const file of source) {
+		const key = areaForPath(file.path, areaDepth);
+		const area = byKey.get(key) ?? { key, files: [], lines: 0 };
+		area.files.push(file);
+		area.lines += Math.max(0, file.loc);
+		byKey.set(key, area);
+	}
+	return [...byKey.values()].sort((a, b) => b.lines - a.lines || a.key.localeCompare(b.key));
+}
+
+/**
+ * The architecture page every wiki gets. It is the one page whose subject is
+ * the repository rather than a directory, so it is anchored on indexed entry
+ * points instead of an area.
+ */
+function overviewPage(source: ReadonlyArray<CodewikiFile>): WikiPlanPage {
+	const entries = source.filter((file) => file.role === "entry");
+	return {
+		path: "architecture.md",
+		title: "Architecture",
+		intent:
+			"Explain what this repository is, its top-level composition, how a request or command flows through it, " +
+			"and where the boundaries between its major areas are.",
+		sources: rankedSources(entries.length > 0 ? entries : source),
+		status: "pending",
+		attempts: 0,
+	};
+}
+
+/**
+ * Build the candidate skeleton from the index. Areas above the depth threshold
+ * become pages; the rest fold their files into the closest ancestor page that
+ * did, so a small directory is documented somewhere rather than dropped.
+ */
+export function buildCandidatePlan(codewiki: Codewiki, depth: ResolvedWikiDepth): WikiPlan {
+	const source = codewiki.files.filter((file) => file.lang !== "config");
+	const totalLines = source.reduce((total, file) => total + Math.max(0, file.loc), 0);
+	const { areaDepth, areaShare, minAreaLines } = WIKI_DEPTH_STRATEGY[depth];
+	const threshold = Math.max(minAreaLines, Math.floor(totalLines * areaShare));
+	const areas = collectAreas(source, areaDepth);
+	const included = areas.filter((area) => area.lines >= threshold);
+	// A repository whose areas are all below threshold still gets pages: the
+	// largest area always earns one, so a small repo is never reduced to a
+	// single architecture page with nothing under it.
+	const selected = included.length > 0 ? included : areas.slice(0, 1);
+	const selectedKeys = new Set(selected.map((area) => area.key));
+	const extras = new Map<string, CodewikiFile[]>();
+	for (const area of areas) {
+		if (selectedKeys.has(area.key)) continue;
+		const ancestor = selected.find((candidate) => area.key.startsWith(`${candidate.key}/`));
+		const host = ancestor?.key ?? selected[0]?.key;
+		if (host === undefined) continue;
+		extras.set(host, [...(extras.get(host) ?? []), ...area.files]);
+	}
+	const pages = selected.map((area): WikiPlanPage => {
+		const files = [...area.files, ...(extras.get(area.key) ?? [])];
+		return {
+			path: pagePathForArea(area.key),
+			title: titleForArea(area.key),
+			intent:
+				`Document ${area.key} (${area.files.length} indexed files, ${area.lines} lines): what it owns, its entry ` +
+				"points and important symbols, the state and lifecycle invariants it enforces, an upstream caller and a " +
+				"downstream dependency, the focused tests that prove its behavior, and what to watch when editing it.",
+			sources: rankedSources(files),
+			status: "pending",
+			attempts: 0,
+		};
+	});
+	return dedupePagePaths({
+		version: 1,
+		overview: "",
+		pages: [overviewPage(source), ...pages],
+	});
+}
+
+/** Two areas can slug to one path; keep the first and suffix the rest. */
+function dedupePagePaths(plan: WikiPlan): WikiPlan {
+	const seen = new Set<string>();
+	const pages: WikiPlanPage[] = [];
+	for (const page of plan.pages) {
+		let path = page.path;
+		let suffix = 2;
+		while (seen.has(path)) {
+			path = page.path.replace(/\.md$/, `-${suffix}.md`);
+			suffix += 1;
+		}
+		seen.add(path);
+		pages.push({ ...page, path });
+	}
+	return { ...plan, pages };
+}
+
+export function planWikiGeneration(codewiki: Codewiki, requestedDepth: WikiDepth = "auto"): WikiGenerationPlan {
+	const source = codewiki.files.filter((file) => file.lang !== "config");
+	const sourceFiles = source.length;
+	const sourceLines = source.reduce((total, file) => total + Math.max(0, file.loc), 0);
+	const depth = requestedDepth === "auto" ? classifyDepth(sourceFiles, sourceLines) : requestedDepth;
+	return { requestedDepth, depth, sourceFiles, sourceLines, plan: buildCandidatePlan(codewiki, depth) };
+}