@iowarp/clio-coder 0.4.3 → 0.4.5

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

@@ -14,21 +14,26 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ContextActivityPayload } from "../../../core/bus-events.js";
+import type { DecisionLedgerEntry } from "../../session/entries.js";
 import { detectProjectType } from "../../session/workspace/project-type.js";
 import type { BootstrapProgressSink } from "../bootstrap.js";
 import { coordinateCodewikiWrite } from "../codewiki/coordinator.js";
 import type { Codewiki } from "../codewiki/schema.js";
 import type { Fingerprint } from "../fingerprint.js";
 import { readClioState, writeClioState } from "../state.js";
-import { assembleWikiTree, normalizeRepoPath, pageSourceIndex } from "./assemble.js";
+import { assembleWikiTree, pageSourceIndex } from "./assemble.js";
+import { inspectWikiPageEvidence } from "./evidence.js";
 import { isGeneratedWikiFile, listWikiPagesInDir, WIKI_PLAN_FILE, wikiDir, wikiMarkdownFilesInDir } from "./layout.js";
 import {
 	computeWikiContentHash,
 	computeWikiContentHashOfDir,
 	currentWikiGitHead,
 	readWikiMeta,
+	readWikiMetaInDir,
+	type WikiMeta,
 	wikiMetaPath,
 	writeWikiMeta,
+	writeWikiMetaInDir,
 } from "./meta.js";
 import {
 	planWikiGeneration,
@@ -37,13 +42,16 @@ import {
 	type WikiPlan,
 	type WikiPlanPage,
 } from "./plan.js";
-import { readWikiPlanFile, scopePlanForUpdate, unclaimedCandidates, writeWikiPlanFile } from "./plan-store.js";
+import { readWikiPlanFile, unclaimedCandidates, writeWikiPlanFile } from "./plan-store.js";
 import type { WikiGenerateMode } from "./prompts.js";
+import { captureWikiSourceContent, type WikiSourceContent, wikiSourcesMatch } from "./source-content.js";
 import { changedPathsSince } from "./staleness.js";
 
 export type { WikiDepth, WikiGenerateMode };
 
 export interface WikiGenerateInput {
+	/** The current session board, already scoped to its active branch. */
+	decisions?: ReadonlyArray<DecisionLedgerEntry>;
 	cwd: string;
 	mode: WikiGenerateMode;
 	/**
@@ -67,6 +75,8 @@ export interface WikiGenerateInput {
 	 * paths.
 	 */
 	resumed: boolean;
+	/** Operator-requested retry of pending work, including exhausted writers, once this run. */
+	retryPending?: boolean;
 	/** Indexed areas no existing page covers, offered to a planning pass. */
 	unclaimedAreas: ReadonlyArray<WikiPlanPage>;
 	gitHead?: string | null;
@@ -76,10 +86,14 @@ export interface WikiGenerateInput {
 export type WikiGenerate = (input: WikiGenerateInput) => void | Promise<void>;
 
 export interface RunWikiGenerateInput {
+	/** The current session board, already scoped to its active branch. */
+	decisions?: ReadonlyArray<DecisionLedgerEntry>;
 	cwd?: string;
 	mode?: WikiGenerateMode;
 	/** Repository-detail policy. Auto scales decomposition from indexed files and lines. */
 	depth?: WikiDepth;
+	/** Resume the existing plan, allowing exhausted pending writers one more attempt. */
+	retryPending?: boolean;
 	model: string;
 	generate?: WikiGenerate;
 	onProgress?: BootstrapProgressSink;
@@ -294,13 +308,29 @@ function adoptOrCreateStaging(cwd: string): { dir: string; adopted: boolean } {
 
 type PromoteResult = { ok: true } | { ok: false; problems: string[] };
 
-/**
- * Atomically swap staging into place: move the current wiki aside to
- * .clio-coder/wiki-prev, rename staging to .clio-coder/wiki, then write meta.json. On any
- * failure after the old wiki is moved aside, restore it; if the restore fails,
- * the recovered content is left at wiki-prev and its path is surfaced.
- */
-function promoteStaging(cwd: string, stagingDir: string, writeMeta: () => void): PromoteResult {
+/** Resolve a previous process crash before reading metadata or cleaning staging. */
+function recoverPublication(cwd: string): void {
+	const wiki = wikiDir(cwd);
+	const prev = join(clioDir(cwd), WIKI_PREV_DIR);
+	if (!existsSync(prev)) return;
+	const valid = (dir: string): boolean => {
+		const meta = readWikiMetaInDir(dir);
+		return meta !== null && meta.contentHash === computeWikiContentHashOfDir(dir);
+	};
+	if (valid(wiki)) {
+		removeDir(prev);
+		return;
+	}
+	if (!valid(prev)) throw new Error(`wiki recovery requires a valid publication; preserved ${wiki} and ${prev}`);
+	if (existsSync(wiki)) {
+		const interrupted = mkdtempSync(join(clioDir(cwd), "wiki-interrupted-"));
+		renameSync(wiki, join(interrupted, "wiki"));
+	}
+	renameSync(prev, wiki);
+}
+
+/** Promote a prepared content/metadata pair; restore the old pair on rename failure. */
+function promoteStaging(cwd: string, stagingDir: string): PromoteResult {
 	const wiki = wikiDir(cwd);
 	const prev = join(clioDir(cwd), WIKI_PREV_DIR);
 	removeDir(prev);
@@ -308,7 +338,6 @@ function promoteStaging(cwd: string, stagingDir: string, writeMeta: () => void):
 	if (hadWiki) renameSync(wiki, prev);
 	try {
 		renameSync(stagingDir, wiki);
-		writeMeta();
 	} catch (err) {
 		const problems = [`wiki promotion failed: ${err instanceof Error ? err.message : String(err)}`];
 		removeDir(stagingDir);
@@ -332,9 +361,9 @@ function promoteStaging(cwd: string, stagingDir: string, writeMeta: () => void):
  * interrupted run, then the plan the last promoted wiki recorded, then the
  * candidate skeleton the index just produced.
  *
- * A resumed plan is used exactly as it was left. It was settled when the wiki
- * was planned, and the pages already written link to its paths, so changing it
- * mid-flight would strand those links. Areas the index has since found that no
+ * A resumed plan retains its structure because finished pages link to its
+ * paths. Completed dispatches are reusable only when the checkpoint source
+ * content matches; missing or changed evidence requeues the pages. Areas the index has since found that no
  * page covers are carried separately and offered to a planning pass, which is
  * the only thing allowed to change a plan's shape.
  */
@@ -345,24 +374,60 @@ function resolvePlan(input: {
 	mode: WikiGenerateMode;
 	candidate: WikiPlan;
 	previousPlan: WikiPlan | undefined;
+	sourceContent: WikiSourceContent;
 	gitHead: string | null;
 }): { plan: WikiPlan; resumed: boolean; unclaimedAreas: WikiPlanPage[] } {
 	const staged = input.adopted ? readWikiPlanFile(input.stagingDir) : null;
-	if (staged !== null) return { plan: staged, resumed: true, unclaimedAreas: [] };
-	if (input.mode === "update" && input.previousPlan !== undefined) {
+	const previous = staged ?? (input.mode === "update" ? input.previousPlan : undefined);
+	if (previous) {
 		const pageSources = pageSourceIndex(input.stagingDir, input.cwd);
-		const changed = new Set(
-			changedPathsSince(input.cwd, input.gitHead).map((path) => normalizeRepoPath(input.cwd, path)),
-		);
-		return {
-			plan: scopePlanForUpdate({
-				plan: input.previousPlan,
-				changedPaths: changed,
-				existingPages: new Set(wikiMarkdownFilesInDir(input.stagingDir)),
-				pageSources,
+		// A partial first publication has no whole-wiki Git certification yet.
+		// Its completed pages still have the harness-captured plan baseline.
+		const partialHead =
+			input.gitHead === null && previous.pages.some((page) => page.status !== "written")
+				? previous.sourceGitHead
+				: undefined;
+		const gitAvailable = changedPathsSince(input.cwd, staged?.sourceGitHead ?? partialHead ?? input.gitHead) !== null;
+		const existing = new Set(wikiMarkdownFilesInDir(input.stagingDir));
+		const plan = {
+			...previous,
+			pages: previous.pages.map((page) => {
+				if (page.status !== "written") return page;
+				const evidence = inspectWikiPageEvidence({
+					pagePath: page.path,
+					outputDir: input.stagingDir,
+					sourceRoot: input.cwd,
+				});
+				const sources = [
+					...page.sources,
+					...(page.dependencies ?? []),
+					...(pageSources.get(page.path) ?? []),
+					...(evidence.dependencies ?? []),
+				];
+				return gitAvailable &&
+					existing.has(page.path) &&
+					evidence.ok &&
+					wikiSourcesMatch(previous.sourceContent, input.sourceContent, sources)
+					? { ...page, dependencies: evidence.dependencies ?? [] }
+					: {
+							...page,
+							status: "pending" as const,
+							attempts: 0,
+							...(!evidence.ok
+								? {
+										lastFailure: {
+											phase: "validation" as const,
+											detail: `saved page evidence check failed: ${evidence.reasons.join("; ")}`.slice(0, 500),
+										},
+									}
+								: {}),
+						};
 			}),
-			resumed: false,
-			unclaimedAreas: unclaimedCandidates(input.previousPlan, input.candidate, pageSources),
+		};
+		return {
+			plan,
+			resumed: staged !== null,
+			unclaimedAreas: staged ? [] : unclaimedCandidates(previous, input.candidate, pageSources),
 		};
 	}
 	return { plan: input.candidate, resumed: false, unclaimedAreas: [] };
@@ -371,9 +436,9 @@ function resolvePlan(input: {
 /**
  * Reconcile the plan against the tree that actually exists. A page whose file
  * the assembly pass dropped, or that was never written, is owed again; a page
- * on disk is recorded as written whatever the writer reported. A page that
- * exists without a plan entry is adopted, because a page on disk is a page: the
- * alternative is a plan that keeps re-dispatching a subject already covered.
+ * on disk retains its recorded dispatch outcome. A page
+ * created by a writer without a plan entry remains available and is adopted
+ * pending: its own completed dispatch has not yet been recorded.
  */
 function reconcilePlan(plan: WikiPlan, stagingDir: string): WikiPlan {
 	const contentFiles = wikiMarkdownFilesInDir(stagingDir).filter((relPath) => !isGeneratedWikiFile(relPath));
@@ -386,15 +451,13 @@ function reconcilePlan(plan: WikiPlan, stagingDir: string): WikiPlan {
 			title: relPath.replace(/\.md$/, ""),
 			intent: "",
 			sources: [],
-			status: "written" as const,
-			attempts: 1,
+			status: "pending" as const,
+			attempts: 0,
 		}));
 	return {
 		...plan,
 		pages: [
-			...plan.pages.map((page) =>
-				onDisk.has(page.path) ? { ...page, status: "written" as const } : { ...page, status: "pending" as const },
-			),
+			...plan.pages.map((page) => (onDisk.has(page.path) ? page : { ...page, status: "pending" as const })),
 			...adopted,
 		],
 	};
@@ -404,8 +467,6 @@ export async function runWikiGenerate(
 	input: RunWikiGenerateInput = { model: "configured-clio-target" },
 ): Promise<RunWikiGenerateResult> {
 	const cwd = input.cwd ?? process.cwd();
-	const existingMeta = readWikiMeta(cwd);
-	const mode = input.mode ?? (existingMeta ? "update" : "init");
 
 	const lock = acquireWikiLock(cwd);
 	if (!lock.ok) {
@@ -415,10 +476,12 @@ export async function runWikiGenerate(
 	}
 
 	try {
+		recoverPublication(cwd);
+		const existingMeta = readWikiMeta(cwd);
+		const mode = input.mode ?? (existingMeta ? "update" : "init");
 		progress(input, { phase: "codewiki", status: "started", message: "loading codewiki for wiki generation" });
 		const { codewiki, fingerprint } = await loadOrBuildCodewiki(cwd);
 		const sourceTreeHash = fingerprint.treeHash;
-		const generation = planWikiGeneration(codewiki, input.depth ?? "auto");
 		progress(input, {
 			phase: "codewiki",
 			status: "completed",
@@ -428,6 +491,27 @@ export async function runWikiGenerate(
 		});
 
 		const staging = adoptOrCreateStaging(cwd);
+		const stagedPlan = staging.adopted ? readWikiPlanFile(staging.dir) : null;
+		const savedPlan = stagedPlan ?? (mode === "update" ? existingMeta?.plan : undefined);
+		const savedDepth = savedPlan?.depth ?? existingMeta?.generation?.depth;
+		const continuing = Boolean(
+			stagedPlan || input.retryPending || savedPlan?.pages.some((page) => page.status !== "written"),
+		);
+		const requestedDepth = input.depth ?? savedPlan?.requestedDepth ?? existingMeta?.generation?.requestedDepth ?? "auto";
+		const generation = planWikiGeneration(
+			codewiki,
+			continuing && (input.depth === undefined || input.depth === "auto") && savedDepth ? savedDepth : requestedDepth,
+		);
+		// Keep the policy separate from its resolved coverage so a completed auto wiki can grow.
+		generation.requestedDepth =
+			continuing && (input.depth === undefined || input.depth === "auto")
+				? (savedPlan?.requestedDepth ?? existingMeta?.generation?.requestedDepth ?? savedDepth ?? requestedDepth)
+				: requestedDepth;
+		const depthChanged = Boolean(
+			savedPlan && (savedDepth ? savedDepth !== generation.depth : input.depth !== undefined && input.depth !== "auto"),
+		);
+		const sourceGitHead = currentWikiGitHead(cwd) ?? undefined;
+		const sourceContent = captureWikiSourceContent(cwd);
 		const resolved = resolvePlan({
 			cwd,
 			stagingDir: staging.dir,
@@ -435,8 +519,25 @@ export async function runWikiGenerate(
 			mode,
 			candidate: generation.plan,
 			previousPlan: existingMeta?.plan,
+			sourceContent,
 			gitHead: existingMeta?.gitHead ?? null,
 		});
+		if (input.retryPending && !resolved.resumed && !existingMeta?.plan) {
+			if (!staging.adopted) removeDir(staging.dir);
+			return failed(
+				["no saved wiki plan to retry; run `clio-coder context wiki` first"],
+				listWikiPagesInDir(wikiDir(cwd)).length,
+			);
+		}
+		if (depthChanged) {
+			resolved.plan = {
+				...resolved.plan,
+				pages: resolved.plan.pages.map((page) => ({ ...page, status: "pending", attempts: 0 })),
+			};
+			resolved.resumed = false;
+		}
+		resolved.plan.depth = generation.depth;
+		resolved.plan.requestedDepth = generation.requestedDepth;
 		const owed = resolved.plan.pages.filter((page) => page.status !== "written").length;
 		progress(input, {
 			phase: "codewiki",
@@ -445,8 +546,14 @@ export async function runWikiGenerate(
 			detail:
 				`${generation.sourceFiles} source files; ${generation.sourceLines} lines; ` +
 				`${resolved.plan.pages.length} pages planned; ${owed} to write` +
-				(resolved.resumed ? "; resuming an interrupted run" : ""),
+				(resolved.resumed ? "; resuming an interrupted run" : "") +
+				(depthChanged
+					? `; coverage changed from ${savedDepth ?? "legacy unspecified"} to ${generation.depth}; prior pages requeued with prose retained`
+					: ""),
 		});
+		resolved.plan = { ...resolved.plan, sourceTreeHash, sourceContent };
+		if (sourceGitHead) resolved.plan.sourceGitHead = sourceGitHead;
+		else delete resolved.plan.sourceGitHead;
 		writeWikiPlanFile(staging.dir, resolved.plan);
 
 		const beforeHash = computeWikiContentHash(cwd);
@@ -471,8 +578,10 @@ export async function runWikiGenerate(
 				codewiki,
 				generation,
 				plan: resolved.plan,
-				resumed: resolved.resumed,
+				resumed: resolved.resumed || (input.retryPending === true && !depthChanged),
+				...(input.retryPending ? { retryPending: true } : {}),
 				unclaimedAreas: resolved.unclaimedAreas,
+				...(input.decisions ? { decisions: input.decisions } : {}),
 				gitHead: existingMeta?.gitHead ?? null,
 				...(input.onProgress ? { progress: input.onProgress } : {}),
 			});
@@ -495,9 +604,33 @@ export async function runWikiGenerate(
 		}
 		progress(input, { phase: "generate", status: "completed", message: "wiki generator completed" });
 
-		const workedPlan = readWikiPlanFile(staging.dir, resolved.plan) ?? resolved.plan;
+		const checkpoint = readWikiPlanFile(staging.dir) ?? resolved.plan;
+		// Replanning explicitly retires old planned publications. Other writer
+		// additions remain available, including pages linked by completed work.
+		for (const path of checkpoint.retiredPages ?? []) rmSync(join(staging.dir, path), { force: true });
+		// Capture citation evidence before assembly removes missing paths from
+		// routing metadata. Failed refreshes and no-op runs must retain it.
+		const citedSources = pageSourceIndex(staging.dir, cwd);
+		const currentContent = captureWikiSourceContent(cwd);
+		const workedPlan: WikiPlan = {
+			...checkpoint,
+			sourceTreeHash,
+			sourceContent,
+			pages: checkpoint.pages.map((page) => {
+				const dependencies = [...new Set([...(page.dependencies ?? []), ...(citedSources.get(page.path) ?? [])])];
+				const stable = wikiSourcesMatch(sourceContent, currentContent, [...page.sources, ...dependencies]);
+				return {
+					...page,
+					dependencies,
+					...(page.status === "written" && !stable ? { status: "pending" as const, attempts: 0 } : {}),
+				};
+			}),
+		};
+		if (sourceGitHead) workedPlan.sourceGitHead = sourceGitHead;
+		else delete workedPlan.sourceGitHead;
 		const report = assembleWikiTree({ dir: staging.dir, sourceRoot: cwd, plan: workedPlan });
 		const finalPlan = reconcilePlan(workedPlan, staging.dir);
+		delete finalPlan.retiredPages;
 		const pendingCount = finalPlan.pages.filter((page) => page.status !== "written").length;
 		progress(input, {
 			phase: "state",
@@ -509,9 +642,6 @@ export async function runWikiGenerate(
 				(pendingCount > 0 ? `; ${pendingCount} page${pendingCount === 1 ? "" : "s"} still to write` : ""),
 		});
 
-		// The plan lives on in meta.json, so the staged working copy must not be
-		// promoted into the wiki tree alongside the pages.
-		rmSync(join(staging.dir, WIKI_PLAN_FILE), { force: true });
 		const afterHash = computeWikiContentHashOfDir(staging.dir);
 		const stagedPages = listWikiPagesInDir(staging.dir);
 		// Unresolved references are reported, not fatal. They are repaired in the
@@ -519,25 +649,31 @@ export async function runWikiGenerate(
 		// reach the operator and the next update run without costing this one.
 		const problems = report.issues.map((issue) => `${issue.page} has an unresolved ${issue.kind}: ${issue.reference}`);
 
-		const writeMeta = (): void => {
-			writeWikiMeta(cwd, {
-				version: 1,
-				updatedAt: new Date().toISOString(),
-				gitHead: currentWikiGitHead(cwd),
-				sourceTreeHash,
-				model: input.model,
-				contentHash: afterHash,
-				pages: stagedPages,
-				generation: {
-					requestedDepth: generation.requestedDepth,
-					depth: generation.depth,
-					sourceFiles: generation.sourceFiles,
-					sourceLines: generation.sourceLines,
-					pagesPlanned: finalPlan.pages.length,
-					pagesWritten: finalPlan.pages.length - pendingCount,
-				},
-				plan: finalPlan,
-			});
+		const unchanged = afterHash === beforeHash && existingMeta !== null;
+		const pendingPublishedPage = finalPlan.pages.some(
+			(page) => page.status !== "written" && stagedPages.some((available) => available.path === page.path),
+		);
+		const meta: WikiMeta = {
+			version: 1,
+			updatedAt: unchanged ? existingMeta.updatedAt : new Date().toISOString(),
+			gitHead: pendingPublishedPage ? (existingMeta?.gitHead ?? null) : currentWikiGitHead(cwd),
+			...(pendingPublishedPage
+				? existingMeta?.sourceTreeHash
+					? { sourceTreeHash: existingMeta.sourceTreeHash }
+					: {}
+				: { sourceTreeHash }),
+			model: unchanged ? existingMeta.model : input.model,
+			contentHash: afterHash,
+			pages: stagedPages,
+			generation: {
+				requestedDepth: generation.requestedDepth,
+				depth: generation.depth,
+				sourceFiles: generation.sourceFiles,
+				sourceLines: generation.sourceLines,
+				pagesPlanned: finalPlan.pages.length,
+				pagesWritten: finalPlan.pages.length - pendingCount,
+			},
+			plan: finalPlan,
 		};
 
 		const done = (status: "generated" | "noop"): RunWikiGenerateResult => ({
@@ -552,22 +688,25 @@ export async function runWikiGenerate(
 		// the assembled tree matches the live wiki byte for byte there is nothing
 		// to swap, so metadata is refreshed in place.
 		if (afterHash === beforeHash && computeWikiContentHash(cwd) === beforeHash && existingMeta) {
+			writeWikiMeta(cwd, meta);
+			rmSync(join(wikiDir(cwd), WIKI_PLAN_FILE), { force: true });
 			removeDir(staging.dir);
-			// Metadata is left exactly as it was. Rewriting it would churn
-			// `updatedAt` and `model` on a run that changed nothing, which makes
-			// every no-op look like a regeneration to anything reading the file.
 			progress(input, {
 				phase: "state",
 				status: "completed",
-				message: "wiki unchanged; metadata preserved",
+				message: "wiki unchanged; progress recorded",
 				detail: wikiMetaPath(cwd),
 			});
 			progress(input, { phase: "done", status: "completed", message: "wiki unchanged" });
 			return done("noop");
 		}
 
+		// Keep the checkpoint until the complete publication is prepared. A crash
+		// during either rename can then recover the last good content/metadata pair.
+		writeWikiPlanFile(staging.dir, finalPlan);
+		writeWikiMetaInDir(staging.dir, meta);
 		progress(input, { phase: "state", status: "running", message: "promoting wiki" });
-		const promoted = promoteStaging(cwd, staging.dir, writeMeta);
+		const promoted = promoteStaging(cwd, staging.dir);
 		if (!promoted.ok) {
 			progress(input, {
 				phase: "done",
@@ -577,6 +716,7 @@ export async function runWikiGenerate(
 			});
 			return failed(promoted.problems, listWikiPagesInDir(wikiDir(cwd)).length);
 		}
+		rmSync(join(wikiDir(cwd), WIKI_PLAN_FILE), { force: true });
 		progress(input, { phase: "state", status: "completed", message: "wiki metadata written" });
 		progress(input, {
 			phase: "done",

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

@@ -168,7 +168,11 @@ export function isWikiMeta(value: unknown): value is WikiMeta {
 }
 
 export function readWikiMeta(cwd: string): WikiMeta | null {
-	const filePath = wikiMetaPath(cwd);
+	return readWikiMetaInDir(wikiDir(cwd));
+}
+
+export function readWikiMetaInDir(dir: string): WikiMeta | null {
+	const filePath = join(dir, "meta.json");
 	if (!existsSync(filePath)) return null;
 	let parsed: unknown;
 	try {
@@ -181,6 +185,10 @@ export function readWikiMeta(cwd: string): WikiMeta | null {
 }
 
 export function writeWikiMeta(cwd: string, meta: WikiMeta): void {
+	writeWikiMetaInDir(wikiDir(cwd), meta);
+}
+
+export function writeWikiMetaInDir(dir: string, meta: WikiMeta): void {
 	const normalized: WikiMeta = {
 		version: 1,
 		updatedAt: meta.updatedAt,
@@ -192,7 +200,7 @@ export function writeWikiMeta(cwd: string, meta: WikiMeta): void {
 		...(meta.generation !== undefined ? { generation: { ...meta.generation } } : {}),
 		...(meta.plan !== undefined ? { plan: meta.plan } : {}),
 	};
-	safeResourceWrite(wikiMetaPath(cwd), `${JSON.stringify(normalized)}\n`, { encoding: "utf8" });
+	safeResourceWrite(join(dir, "meta.json"), `${JSON.stringify(normalized)}\n`, { encoding: "utf8" });
 }
 
 /**

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

@@ -13,7 +13,8 @@ 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";
+import type { WikiPageFailure, WikiPageStatus, WikiPlan, WikiPlanPage } from "./plan.js";
+import { parseWikiSourceContent } from "./source-content.js";
 
 /** Dispatches one page may receive across all runs before it is left alone. */
 export const MAX_PAGE_ATTEMPTS = 3;
@@ -75,6 +76,16 @@ function parsedAttempts(value: unknown): number | null {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
 }
 
+function parsedFailure(value: unknown): WikiPageFailure | undefined {
+	if (!isRecord(value)) return undefined;
+	const phase = value.phase;
+	if (phase !== "admission" && phase !== "writer" && phase !== "validation") return undefined;
+	const detail = usableString(value.detail)?.replace(/\s+/gu, " ").slice(0, 500);
+	if (!detail) return undefined;
+	const runId = usableString(value.runId)?.slice(0, 120);
+	return { phase, detail, ...(runId ? { runId } : {}) };
+}
+
 export interface SanitizeWikiPlanOptions {
 	/**
 	 * Whether the recorded progress in this document may be believed.
@@ -90,7 +101,7 @@ export interface SanitizeWikiPlanOptions {
 
 /**
  * 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
+ * whose path and specification survived. Returns null when nothing usable is left, so the caller
  * falls back to the candidate plan.
  */
 export function sanitizeWikiPlan(
@@ -107,22 +118,65 @@ export function sanitizeWikiPlan(
 		if (!isRecord(entry)) continue;
 		const path = sanitizePagePath(entry.path);
 		if (path === null || seen.has(path)) continue;
-		const intent = usableString(entry.intent);
+		const intent = (usableString(entry.intent) ?? "").slice(0, MAX_INTENT_CHARS);
+		const title = usableString(entry.title) ?? path.replace(/\.md$/, "");
+		const sources = stringList(entry.sources, 16);
 		const prior = priorByPath.get(path);
+		const changedSpec =
+			prior !== undefined &&
+			(prior.title !== title ||
+				prior.intent !== intent ||
+				JSON.stringify([...prior.sources].sort()) !== JSON.stringify([...sources].sort()));
 		const recorded = options.trustStatus ? parsedStatus(entry.status) : null;
 		const recordedAttempts = options.trustStatus ? parsedAttempts(entry.attempts) : null;
+		const lastFailure = prior?.lastFailure ?? (options.trustStatus ? parsedFailure(entry.lastFailure) : undefined);
+		const dependencies =
+			prior?.dependencies ?? (options.trustStatus ? stringList(entry.dependencies, Number.POSITIVE_INFINITY) : []);
 		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,
+			title,
+			intent,
+			sources,
+			...(dependencies.length > 0 ? { dependencies } : {}),
+			status: changedSpec ? "pending" : (prior?.status ?? recorded ?? "pending"),
+			attempts: changedSpec ? 0 : (prior?.attempts ?? recordedAttempts ?? 0),
+			...(!changedSpec && (prior?.status ?? recorded) !== "written" && lastFailure ? { lastFailure } : {}),
 		});
 	}
 	if (pages.length === 0) return null;
-	return { version: 1, overview: usableString(value.overview) ?? previous?.overview ?? "", pages };
+	const retiredPages = [
+		...new Set([
+			...(previous?.retiredPages ?? (options.trustStatus ? stringList(value.retiredPages, MAX_PLAN_PAGES) : [])),
+			...(previous?.pages.filter((page) => !seen.has(page.path)).map((page) => page.path) ?? []),
+		]),
+	]
+		.map(sanitizePagePath)
+		.filter((path): path is string => path !== null && !seen.has(path));
+	const sourceContent =
+		previous?.sourceContent ?? (options.trustStatus ? parseWikiSourceContent(value.sourceContent) : undefined);
+	const sourceTreeHash = previous?.sourceTreeHash ?? (options.trustStatus ? value.sourceTreeHash : undefined);
+	const sourceGitHead = previous?.sourceGitHead ?? (options.trustStatus ? value.sourceGitHead : undefined);
+	const depth = previous?.depth ?? (options.trustStatus ? value.depth : undefined);
+	const requestedDepth = previous?.requestedDepth ?? (options.trustStatus ? value.requestedDepth : undefined);
+	return {
+		version: 1,
+		...(depth === "simple" || depth === "medium" || depth === "detailed" ? { depth } : {}),
+		...(requestedDepth === "auto" ||
+		requestedDepth === "simple" ||
+		requestedDepth === "medium" ||
+		requestedDepth === "detailed"
+			? { requestedDepth }
+			: {}),
+		...(sourceContent ? { sourceContent } : {}),
+		...(retiredPages.length ? { retiredPages } : {}),
+		...(typeof sourceTreeHash === "string" && /^[a-f0-9]{64}$/.test(sourceTreeHash) ? { sourceTreeHash } : {}),
+		...(typeof sourceGitHead === "string" && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(sourceGitHead)
+			? { sourceGitHead }
+			: {}),
+		overview: usableString(value.overview) ?? previous?.overview ?? "",
+		pages,
+	};
 }
 
 function readPlanDocument(dir: string): unknown {
@@ -174,7 +228,8 @@ export function unclaimedCandidates(
 	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);
+		for (const source of [...page.sources, ...(page.dependencies ?? []), ...(pageSources.get(page.path) ?? [])])
+			claimed.add(source);
 	}
 	return candidate.pages.filter(
 		(page) => !knownPaths.has(page.path) && !page.sources.some((source) => claimed.has(source)),
@@ -201,8 +256,9 @@ export interface ScopeUpdateInput {
 export function scopePlanForUpdate(input: ScopeUpdateInput): WikiPlan {
 	const changedPrefixes = [...input.changedPaths];
 	const pages = input.plan.pages.map((page): WikiPlanPage => {
+		if (page.status !== "written") return page;
 		if (!input.existingPages.has(page.path)) return { ...page, status: "pending", attempts: 0 };
-		const claimed = [...(input.pageSources.get(page.path) ?? []), ...page.sources];
+		const claimed = [...(input.pageSources.get(page.path) ?? []), ...page.sources, ...(page.dependencies ?? [])];
 		const touched = claimed.some((source) =>
 			changedPrefixes.some((changed) => changed === source || changed.startsWith(`${source}/`)),
 		);
@@ -211,7 +267,7 @@ export function scopePlanForUpdate(input: ScopeUpdateInput): WikiPlan {
 	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);
+/** An explicit operator retry includes exhausted pages without erasing their attempt history. */
+export function pendingPages(plan: WikiPlan, retryExhausted = false): WikiPlanPage[] {
+	return plan.pages.filter((page) => page.status !== "written" && (retryExhausted || page.attempts < MAX_PAGE_ATTEMPTS));
 }