@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/domains/agents/result-contract.ts

@@ -7,10 +7,21 @@ export type ResultContract =
 	| { kind: "architect-plan"; path: string }
 	| { kind: "scout-report" }
 	| { kind: "verifier-report" }
+	| { kind: "council-report" }
 	| { kind: "debugger-report" }
 	| { kind: "research-report" }
 	| { kind: "mutation-report" }
 	| { kind: "provenance-report" }
+	| { kind: "delegation-plan" }
+	/**
+	 * The advisory answer `/oracle` asks for. It exists as its own kind because
+	 * the answer shape is the whole point of the command: a verdict, the
+	 * strongest challenge the advisor can mount, the evidence that would change
+	 * its mind, and the prior decisions it read. Folding it onto
+	 * `research-report` would ask for claims and evidence instead, and the
+	 * challenge and the reversal condition would have nowhere to go.
+	 */
+	| { kind: "oracle-report" }
 	| { kind: "external-delegation" }
 	/**
 	 * The run's postcondition is the artifact it left on disk, so its terminal
@@ -58,6 +69,7 @@ export interface ResultContractValidation {
 	scout?: ScoutResult;
 	/** Parsed Verifier data for the dispatch review-gate projection. */
 	verifier?: VerifierResult;
+	delegationPlan?: DelegationPlanResult;
 	reason?: string;
 }
 
@@ -211,6 +223,159 @@ export interface VerifierResult {
 	checks: ReadonlyArray<VerifierCheck>;
 }
 
+export interface DelegationPlanResultTask {
+	id: string;
+	agent: string;
+	description: string;
+	depends_on: ReadonlyArray<string>;
+	writes: ReadonlyArray<string>;
+	mode?: "sequential" | "parallel";
+}
+
+export interface DelegationPlanResult {
+	tasks: ReadonlyArray<DelegationPlanResultTask>;
+}
+
+export function parseDelegationPlanResult(output: string | null): DelegationPlanResult | null {
+	const parsed = parseJson(output);
+	if (
+		!parsed.ok ||
+		!hasOnlyKeys(parsed.value, ["tasks"]) ||
+		!Array.isArray(parsed.value.tasks) ||
+		parsed.value.tasks.length === 0
+	)
+		return null;
+	const tasks: DelegationPlanResultTask[] = [];
+	for (const raw of parsed.value.tasks) {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+		const task = raw as Record<string, unknown>;
+		if (
+			!hasOnlyKeys(task, ["id", "agent", "description", "depends_on", "writes", "mode"]) ||
+			!string(task.id) ||
+			!string(task.agent) ||
+			!string(task.description) ||
+			!Array.isArray(task.depends_on) ||
+			task.depends_on.some((entry) => !string(entry)) ||
+			!Array.isArray(task.writes) ||
+			task.writes.some((entry) => !string(entry)) ||
+			(task.mode !== undefined && task.mode !== "sequential" && task.mode !== "parallel")
+		)
+			return null;
+		tasks.push({
+			id: task.id,
+			agent: task.agent,
+			description: task.description,
+			depends_on: [...task.depends_on] as string[],
+			writes: [...task.writes] as string[],
+			...(task.mode !== undefined ? { mode: task.mode as "sequential" | "parallel" } : {}),
+		});
+	}
+	return { tasks };
+}
+
+export interface CouncilReportMember {
+	label: string;
+	runId: string;
+	round: number;
+	answer: string;
+	verdict?: string;
+	failed?: { reason: string };
+}
+
+export interface CouncilReport {
+	members: CouncilReportMember[];
+	synthesis: {
+		kind: "none" | "judge" | "vote";
+		text?: string;
+		verdict?: string;
+		tally?: Record<string, number>;
+		judgeRunId?: string;
+	};
+}
+
+export function parseCouncilReport(output: string | null): CouncilReport | null {
+	if (output === null) return null;
+	const parsed = parseJsonObjectPayload(output);
+	if (!parsed.ok) return null;
+	const value = parsed.value;
+	if (!hasOnlyKeys(value, ["members", "synthesis"]) || !Array.isArray(value.members) || value.members.length === 0) {
+		return null;
+	}
+	const members: CouncilReportMember[] = [];
+	for (const raw of value.members) {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+		const member = raw as Record<string, unknown>;
+		if (
+			!hasOnlyKeys(member, ["label", "runId", "round", "answer", "verdict", "failed"]) ||
+			!string(member.label) ||
+			!string(member.runId) ||
+			!Number.isInteger(member.round) ||
+			Number(member.round) < 1 ||
+			typeof member.answer !== "string" ||
+			(member.verdict !== undefined && !string(member.verdict))
+		)
+			return null;
+		let failed: { reason: string } | undefined;
+		if (member.failed !== undefined) {
+			if (
+				member.failed === null ||
+				typeof member.failed !== "object" ||
+				Array.isArray(member.failed) ||
+				!hasOnlyKeys(member.failed as Record<string, unknown>, ["reason"]) ||
+				!string((member.failed as Record<string, unknown>).reason)
+			)
+				return null;
+			failed = { reason: (member.failed as { reason: string }).reason };
+		}
+		members.push({
+			label: member.label,
+			runId: member.runId,
+			round: Number(member.round),
+			answer: member.answer,
+			...(member.verdict !== undefined ? { verdict: member.verdict as string } : {}),
+			...(failed !== undefined ? { failed } : {}),
+		});
+	}
+	if (value.synthesis === null || typeof value.synthesis !== "object" || Array.isArray(value.synthesis)) return null;
+	const rawSynthesis = value.synthesis as Record<string, unknown>;
+	if (!hasOnlyKeys(rawSynthesis, ["kind", "text", "verdict", "tally", "judgeRunId"])) return null;
+	if (rawSynthesis.kind !== "none" && rawSynthesis.kind !== "judge" && rawSynthesis.kind !== "vote") return null;
+	for (const key of ["text", "verdict", "judgeRunId"] as const) {
+		if (rawSynthesis[key] !== undefined && !string(rawSynthesis[key])) return null;
+	}
+	let tally: Record<string, number> | undefined;
+	if (rawSynthesis.tally !== undefined) {
+		if (rawSynthesis.tally === null || typeof rawSynthesis.tally !== "object" || Array.isArray(rawSynthesis.tally))
+			return null;
+		tally = {};
+		for (const [key, count] of Object.entries(rawSynthesis.tally as Record<string, unknown>)) {
+			if (!key || !Number.isInteger(count) || Number(count) < 0) return null;
+			tally[key] = Number(count);
+		}
+	}
+	return {
+		members,
+		synthesis: {
+			kind: rawSynthesis.kind,
+			...(rawSynthesis.text !== undefined ? { text: rawSynthesis.text as string } : {}),
+			...(rawSynthesis.verdict !== undefined ? { verdict: rawSynthesis.verdict as string } : {}),
+			...(tally !== undefined ? { tally } : {}),
+			...(rawSynthesis.judgeRunId !== undefined ? { judgeRunId: rawSynthesis.judgeRunId as string } : {}),
+		},
+	};
+}
+
+/**
+ * Parsed `oracle-report` payload. `/oracle` renders these four fields into the
+ * operator note it hands the main agent, so the shape is the answer shape.
+ */
+export interface OracleResult {
+	verdict: string;
+	challenge: string;
+	changesMyMind: string;
+	citedDecisions: ReadonlyArray<string>;
+}
+
 /**
  * Parsed `code-report` payload. `passed` restates `exitCode === 0` so a
  * downstream reader never has to know a runner's exit conventions, and
@@ -269,7 +434,7 @@ function success(
 	contract: ResultContract,
 	quality: ResultContractQuality,
 	value: unknown,
-	extra: Pick<ResultContractValidation, "scout" | "verifier" | "reason"> = {},
+	extra: Pick<ResultContractValidation, "scout" | "verifier" | "delegationPlan" | "reason"> = {},
 ): ResultContractValidation {
 	return {
 		conformance: "pass",
@@ -335,6 +500,7 @@ const RESULT_CONTRACT_KINDS: ReadonlyArray<ResultContract["kind"]> = [
 	"architect-plan",
 	"scout-report",
 	"verifier-report",
+	"council-report",
 	"debugger-report",
 	"research-report",
 	"mutation-report",
@@ -664,6 +830,47 @@ export function parseVerifierResult(output: string | null): VerifierResult | nul
 	return validation.verifier ?? null;
 }
 
+/**
+ * An advisory opinion is never a correctness signal about the route that
+ * produced it, so conformance is judged on the shape alone and quality stays
+ * `unmeasured`. `citedDecisions` may be empty: an honest advisor that found no
+ * settled decision bearing on the question must be able to say so.
+ */
+function validateOracle(contract: ResultContract, output: string | null): ResultContractValidation {
+	const parsed = parseJson(output);
+	if (!parsed.ok) return failure(contract, "unmeasured", parsed.reason);
+	const value = parsed.value;
+	if (
+		!hasOnlyKeys(value, ["verdict", "challenge", "changesMyMind", "citedDecisions"]) ||
+		!string(value.verdict) ||
+		!string(value.challenge) ||
+		!string(value.changesMyMind) ||
+		!Array.isArray(value.citedDecisions) ||
+		value.citedDecisions.some((entry) => !string(entry))
+	) {
+		return failure(
+			contract,
+			"unmeasured",
+			'Oracle result must carry verdict, challenge, changesMyMind, and a citedDecisions array of strings, for example {"verdict":"consistent with decision routing.target","challenge":"...","changesMyMind":"...","citedDecisions":["routing.target"]}',
+		);
+	}
+	return success(contract, "unmeasured", value);
+}
+
+/** Parse an oracle answer under the same schema its recipe contract enforces. */
+export function parseOracleResult(output: string | null): OracleResult | null {
+	const validation = validateOracle({ kind: "oracle-report" }, output);
+	if (validation.conformance !== "pass") return null;
+	const parsed = parseJson(output);
+	if (!parsed.ok) return null;
+	return {
+		verdict: String(parsed.value.verdict),
+		challenge: String(parsed.value.challenge),
+		changesMyMind: String(parsed.value.changesMyMind),
+		citedDecisions: (parsed.value.citedDecisions as ReadonlyArray<string>).map((entry) => String(entry)),
+	};
+}
+
 /**
  * A code step's result is always `unmeasured` for routing quality. A red suite
  * is evidence about the repository, not about the route that ran the command,
@@ -1036,6 +1243,12 @@ export function validateResultContract(input: ResultContractValidationInput): Re
 		}
 		case "verifier-report":
 			return validateVerifier(input.contract, input.output);
+		case "council-report": {
+			const report = parseCouncilReport(input.output);
+			return report === null
+				? failure(input.contract, "fail", "council-report is malformed")
+				: success(input.contract, "unmeasured", { council: report });
+		}
 		case "debugger-report":
 			return validateDebugger(input.contract, input.output);
 		case "research-report":
@@ -1044,6 +1257,18 @@ export function validateResultContract(input: ResultContractValidationInput): Re
 			return validateMutation(input.contract, input);
 		case "provenance-report":
 			return validateProvenance(input.contract, input.output);
+		case "delegation-plan": {
+			const plan = parseDelegationPlanResult(input.output);
+			return plan === null
+				? failure(
+						input.contract,
+						"fail",
+						"delegation-plan must carry tasks with id, agent, description, depends_on, writes, and optional mode",
+					)
+				: success(input.contract, "unmeasured", plan, { delegationPlan: plan });
+		}
+		case "oracle-report":
+			return validateOracle(input.contract, input.output);
 		case "external-delegation":
 			return success(input.contract, "unmeasured", { external: true });
 		case "artifact-report":
@@ -1120,6 +1345,8 @@ function resultContractShape(contract: ResultContract): string {
 			return '{"findings":[{"claim":"what you observed","path":"src/file.ts","line":1}],"needsSplit":false,"proposedSubtasks":[]} or {"findings":[],"needsSplit":true,"proposedSubtasks":[{"id":"inspect","task":"Inspect the boundary","dependencies":[],"expectedResultContract":"scout-report","requestedAuthority":"read-only"}]} or, if you cannot produce a citation you are sure of, at least {"findings":[{"claim":"what you observed"}]}, which is accepted as an ungrounded lead rather than losing the run';
 		case "verifier-report":
 			return '{"verdict":"pass","checks":[{"name":"npm run typecheck","passed":true,"evidence":"exit 0"}]}';
+		case "council-report":
+			return '{"members":[{"label":"alpha","runId":"run-1","round":1,"answer":"..."}],"synthesis":{"kind":"none"}}';
 		case "debugger-report":
 			return '{"diagnosis":"...","reproduction":"reproduced","evidence":["..."]}';
 		case "research-report":
@@ -1128,6 +1355,10 @@ function resultContractShape(contract: ResultContract): string {
 			return '{"mutatedPaths":["src/file.ts"],"validations":[{"name":"npm test","passed":true,"evidence":"exit 0"}],"commitMessage":"optional: the commit message for this change","summary":"optional: one line"}';
 		case "provenance-report":
 			return '{"confirmedFacts":["..."],"missingEvidence":["..."],"nextInspections":["..."]}';
+		case "delegation-plan":
+			return '{"tasks":[{"id":"build","agent":"coder","description":"Implement the change","depends_on":[],"writes":["src"],"mode":"parallel"}]}';
+		case "oracle-report":
+			return '{"verdict":"one line","challenge":"the strongest objection you can mount","changesMyMind":"the evidence that would reverse the verdict","citedDecisions":["decision key or task id you relied on"]}';
 		case "external-delegation":
 			return "any final text";
 		case "artifact-report":
@@ -1147,12 +1378,13 @@ export interface ResultContractRepairInput {
 	attempt: number;
 	/** `path:line` anchors from reads that succeeded in this run. */
 	anchors: ReadonlyArray<string>;
+	/** True only when admission preauthorized a larger tool-call revision phase. */
+	toolsAvailable?: boolean;
 }
 
 /**
- * One repair directive. It states the validator's reason, the exact shape, and
- * that tool use is over, so the model's only remaining move is to emit the
- * terminal document from evidence it already has.
+ * One repair directive. It states the validator's reason and exact shape. Tool
+ * use remains closed unless dispatch preauthorized a larger revision phase.
  */
 export function resultContractRepairMessage(input: ResultContractRepairInput): string {
 	const last = input.attempt >= RESULT_CONTRACT_REPAIR_LIMIT;
@@ -1161,7 +1393,9 @@ export function resultContractRepairMessage(input: ResultContractRepairInput): s
 			? "FINAL RESULT REQUIRED IN THIS RESPONSE. Your previous response still did not satisfy this run's result contract."
 			: "Your previous response did not satisfy this run's result contract.",
 		`Validator reason: ${input.reason}`,
-		"Tool use is over. Answer from the evidence you already gathered.",
+		input.toolsAvailable === true
+			? "You may use the admitted tools to repair this validator failure, then emit the required terminal result."
+			: "Tool use is over. Answer from the evidence you already gathered.",
 		`Emit exactly this shape and nothing else: ${resultContractShape(input.contract)}`,
 		"Do not add prose, code fences, or commentary around it. Do not describe work you intend to do next.",
 	];
@@ -1250,13 +1484,16 @@ export function parseResultContract(value: unknown, sourcePath: string): ResultC
 	const kinds = [
 		"scout-report",
 		"verifier-report",
+		"council-report",
 		"debugger-report",
 		"research-report",
 		"mutation-report",
 		"provenance-report",
+		"oracle-report",
 		"external-delegation",
 		"artifact-report",
 		"context-handbook",
+		"delegation-plan",
 	] as const;
 	if (!(kinds as ReadonlyArray<string>).includes(record.kind) || !only("kind")) {
 		throw new Error(`agent recipe: ${sourcePath}: resultContract.kind is unsupported or has unknown keys`);

package/src/domains/config/classify.ts

@@ -28,6 +28,10 @@ const HOT_RELOAD_FIELDS = new Set<string>([
 	"modelSelector",
 	"terminal.smoothStreaming",
 	"attribution.gitCommits",
+	// The watchdog registration reads its settings live on every trigger, so
+	// enabling it, retargeting it, or changing its cadence takes effect on the
+	// next turn boundary without a restart or a session-routing patch.
+	"watchdog",
 ]);
 
 const NEXT_TURN_FIELDS = new Set<string>([

package/src/domains/context/bootstrap.ts

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, parse } from "node:path";
 import type { ContextActivityPayload } from "../../core/bus-events.js";
+import { createTomlFileReader, type TomlFileReader, tomlTableAt } from "../../core/toml.js";
 import { classifyProjectPreload, type ProjectPreloadClass } from "../prompts/preload.js";
 import { detectProjectType, type ProjectType } from "../session/workspace/project-type.js";
 import {
@@ -15,7 +16,7 @@ import { type ClioMdSection, type ParsedClioMd, parseClioMd, serializeClioMd, tr
 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 { type ProjectMetadata, readProjectMetadata } from "./project-metadata.js";
 import { renderPromptContext } from "./prompt-context.js";
 import type { SiblingContextFile } from "./sibling-files.js";
 import {
@@ -49,6 +50,8 @@ export interface BootstrapIo {
 export interface BootstrapGenerateInput {
 	cwd: string;
 	expectedProjectName?: string;
+	/** Operation-scoped parsed TOML documents shared by bootstrap consumers. */
+	tomlFiles?: TomlFileReader;
 	projectType: ProjectType;
 	siblingFiles: ReadonlyArray<SiblingContextFile>;
 	adoption: AdoptionScanResult;
@@ -211,8 +214,8 @@ function projectNameFrom(metadata: ProjectMetadata, cwd: string): string {
 	return titleFromPackageName(parse(cwd).base || "Project");
 }
 
-function projectName(cwd: string): string {
-	return projectNameFrom(readProjectMetadata(cwd), cwd);
+function projectName(cwd: string, tomlFiles: TomlFileReader): string {
+	return projectNameFrom(readProjectMetadata(cwd, tomlFiles), cwd);
 }
 
 function projectTypeLabel(projectType: ProjectType): string {
@@ -270,8 +273,9 @@ function resolveDefaultIdentity(
 	cwd: string,
 	projectType: ProjectType,
 	files: ReadonlyArray<SiblingContextFile>,
+	tomlFiles: TomlFileReader,
 ): DeterministicIdentity {
-	const metadata = readProjectMetadata(cwd);
+	const metadata = readProjectMetadata(cwd, tomlFiles);
 	const name = projectNameFrom(metadata, cwd);
 	const context = allContextText(files);
 	if (/Clio owns the agent loop/i.test(context) && /pi-(?:ai|SDK)/i.test(context)) {
@@ -303,8 +307,8 @@ function resolveDefaultIdentity(
  * which tells a reader nothing the directory name did not. A model sentence is
  * strictly better than that, and only than that.
  */
-function stabilizedIdentity(input: BootstrapGenerateInput, modelIdentity: unknown): string {
-	const deterministic = resolveDefaultIdentity(input.cwd, input.projectType, input.siblingFiles);
+function stabilizedIdentity(input: BootstrapGenerateInput, modelIdentity: unknown, tomlFiles: TomlFileReader): string {
+	const deterministic = resolveDefaultIdentity(input.cwd, input.projectType, input.siblingFiles, tomlFiles);
 	const model = typeof modelIdentity === "string" ? modelIdentity.trim() : "";
 	if (deterministic.bare && model.length > 0) return model;
 	return deterministic.text;
@@ -504,23 +508,21 @@ function cmakeVerificationLines(cwd: string): string[] {
  * 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")) {
+function pythonVerificationLines(cwd: string, tomlFiles: TomlFileReader): string[] {
+	const pyproject = tomlFiles.read("pyproject.toml");
+	if (existsSync(join(cwd, "tox.ini")) || (pyproject !== null && tomlTableAt(pyproject, ["tool", "tox"]))) {
 		return ["Run `tox` before handoff."];
 	}
-	if (existsSync(join(cwd, "pytest.ini")) || hasTomlTable(pyproject, "tool.pytest.ini_options")) {
+	if (
+		existsSync(join(cwd, "pytest.ini")) ||
+		(pyproject !== null && tomlTableAt(pyproject, ["tool", "pytest", "ini_options"]))
+	) {
 		return ["Run `pytest` before handoff."];
 	}
 	return [];
 }
 
-function verificationSection(cwd: string): ClioMdSection | null {
+function verificationSection(cwd: string, tomlFiles: TomlFileReader): ClioMdSection | null {
 	const scripts = packageScripts(cwd);
 	const pm = packageManager(cwd);
 	const hasScript = (name: string) => typeof scripts[name] === "string";
@@ -557,7 +559,8 @@ function verificationSection(cwd: string): ClioMdSection | null {
 	// 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"))) {
+	const cargo = tomlFiles.read("Cargo.toml");
+	if (cargo !== null && (tomlTableAt(cargo, ["package"]) || tomlTableAt(cargo, ["workspace"]))) {
 		lines.push("Run `cargo build` and `cargo test` before handoff.");
 	}
 	// Go's commands are defined by the toolchain, not by each project, so
@@ -566,7 +569,7 @@ function verificationSection(cwd: string): ClioMdSection | null {
 	if (existsSync(join(cwd, "go.mod"))) {
 		lines.push("Run `go build ./...` and `go test ./...` before handoff.");
 	}
-	lines.push(...pythonVerificationLines(cwd));
+	lines.push(...pythonVerificationLines(cwd, tomlFiles));
 	if (lines.length === 0) return null;
 	return { title: "Verification expectations", body: lines.join(" ") };
 }
@@ -717,6 +720,7 @@ function stabilizeGeneratedOutput(
 	onModelSectionRetained?: () => void,
 	groundModelOutput = false,
 ): BootstrapStructuredOutput {
+	const tomlFiles = input.tomlFiles ?? createTomlFileReader(input.cwd);
 	const existing = input.existingClioMd;
 	const conventions: string[] = [];
 	for (const convention of existing?.conventions ?? []) pushUnique(conventions, convention);
@@ -727,7 +731,7 @@ function stabilizeGeneratedOutput(
 	for (const invariant of existing?.invariants ?? []) pushUnique(invariants, invariant);
 	for (const invariant of inferInvariants(input.siblingFiles)) pushUnique(invariants, invariant);
 
-	const verification = verificationSection(input.cwd);
+	const verification = verificationSection(input.cwd, tomlFiles);
 	const inferredSections = inferHeuristicSections(input);
 	const existingSections = existing?.sections ?? [];
 	const ordinarySections: ClioMdSection[] = [];
@@ -754,8 +758,8 @@ function stabilizeGeneratedOutput(
 	}
 	return {
 		...base,
-		projectName: existing?.projectName ?? projectName(input.cwd),
-		identity: existing?.identity ?? stabilizedIdentity(input, base.identity),
+		projectName: existing?.projectName ?? projectName(input.cwd, tomlFiles),
+		identity: existing?.identity ?? stabilizedIdentity(input, base.identity, tomlFiles),
 		conventions: conventions.slice(0, 6),
 		invariants: invariants.slice(0, 3),
 		sections: [...retainedOrdinarySections, ...(verification ? [verification] : [])],
@@ -819,9 +823,11 @@ function inferHeuristicSections(input: BootstrapGenerateInput): ClioMdSection[]
  * unavailable or fails.
  */
 function heuristicBootstrapOutputSync(input: BootstrapGenerateInput): BootstrapStructuredOutput {
-	return stabilizeGeneratedOutput(input, {
-		projectName: projectName(input.cwd),
-		identity: resolveDefaultIdentity(input.cwd, input.projectType, input.siblingFiles).text,
+	const tomlFiles = input.tomlFiles ?? createTomlFileReader(input.cwd);
+	const sharedInput = input.tomlFiles ? input : { ...input, tomlFiles };
+	return stabilizeGeneratedOutput(sharedInput, {
+		projectName: projectName(input.cwd, tomlFiles),
+		identity: resolveDefaultIdentity(input.cwd, input.projectType, input.siblingFiles, tomlFiles).text,
 		conventions: inferConventions(input.cwd, input.siblingFiles, input.codewiki),
 		invariants: inferInvariants(input.siblingFiles),
 		sections: inferHeuristicSections(input),
@@ -1229,6 +1235,7 @@ function codewikiEntryPoints(codewiki: Codewiki, limit = 6): string[] {
 
 export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBootstrapResult> {
 	const cwd = input.cwd ?? process.cwd();
+	const tomlFiles = createTomlFileReader(cwd);
 	const projectType = detectProjectType(cwd);
 	progress(input, {
 		phase: "scan",
@@ -1327,7 +1334,8 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 		});
 		output = await (input.generate ?? heuristicBootstrapOutput)({
 			cwd,
-			expectedProjectName: projectName(cwd),
+			expectedProjectName: projectName(cwd, tomlFiles),
+			tomlFiles,
 			projectType,
 			siblingFiles,
 			adoption,
@@ -1342,7 +1350,8 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 		output = stabilizeGeneratedOutput(
 			{
 				cwd,
-				expectedProjectName: projectName(cwd),
+				expectedProjectName: projectName(cwd, tomlFiles),
+				tomlFiles,
 				projectType,
 				siblingFiles,
 				adoption,
@@ -1372,7 +1381,7 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 	} else {
 		output = existingParsed
 			? bootstrapOutputFromParsed(existingParsed)
-			: await heuristicBootstrapOutput({ cwd, projectType, siblingFiles, adoption, codewiki });
+			: await heuristicBootstrapOutput({ cwd, tomlFiles, projectType, siblingFiles, adoption, codewiki });
 		progress(input, {
 			phase: "generate",
 			status: "completed",

package/src/domains/context/project-metadata.ts

@@ -19,6 +19,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { createTomlFileReader, type TomlFileReader, tomlTableAt } from "../../core/toml.js";
 
 /** Longest description worth carrying into a one-sentence identity line. */
 const MAX_DESCRIPTION_CHARS = 400;
@@ -39,7 +40,7 @@ interface MetadataFragment {
 	description?: string | null;
 }
 
-type MetadataReader = (cwd: string) => { file: string; fragment: MetadataFragment } | null;
+type MetadataReader = (cwd: string, tomlFiles: TomlFileReader) => { file: string; fragment: MetadataFragment } | null;
 
 function readText(cwd: string, relative: string): string | null {
 	try {
@@ -83,54 +84,6 @@ function jsonRecord(cwd: string, relative: string): Record<string, unknown> | nu
 	}
 }
 
-/**
- * One key from one TOML table, without a TOML parser.
- *
- * Deliberately narrow: it reads `key = "value"` (single-line, single- or
- * double-quoted) from the named top-level table and understands nothing else.
- * That is the entire shape `description` and `name` take in `pyproject.toml`
- * and `Cargo.toml`. A multi-line or otherwise exotic value reads as absent,
- * which costs a description and never produces a wrong one.
- */
-function tomlTableValue(raw: string, table: string, key: string): string | null {
-	const lines = raw.split(/\r?\n/u);
-	let inTable = false;
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (trimmed.startsWith("[")) {
-			inTable = trimmed === `[${table}]`;
-			continue;
-		}
-		if (!inTable) continue;
-		const match = /^([A-Za-z0-9_-]+)\s*=\s*(.*)$/u.exec(trimmed);
-		if (!match || match[1] !== key) continue;
-		const value = (match[2] ?? "").trim();
-		const quoted = /^"((?:[^"\\]|\\.)*)"$/u.exec(value) ?? /^'([^']*)'$/u.exec(value);
-		if (!quoted) return null;
-		return (quoted[1] ?? "").replace(/\\"/gu, '"');
-	}
-	return null;
-}
-
-/**
- * Whether a TOML file declares the named top-level table, e.g. `tool.tox`.
- * A trimmed line must start with `[table]` and carry nothing after it but an
- * optional `# comment`, the only content TOML itself allows there. A raw
- * `raw.includes("[table]")` check would also fire on a comment mentioning the
- * table or a string value that happens to contain the same bracketed text;
- * anchoring to the start of the line rules both out without a TOML parser,
- * while still accepting the valid `[table] # comment` form that a plain
- * equality check would have missed.
- */
-export function hasTomlTable(raw: string, table: string): boolean {
-	const header = `[${table}]`;
-	return raw.split(/\r?\n/u).some((line) => {
-		const trimmed = line.trim();
-		if (!trimmed.startsWith(header)) return false;
-		return /^\s*(?:#.*)?$/u.test(trimmed.slice(header.length));
-	});
-}
-
 /** One `KEY = value` line from a Doxyfile or an INI-shaped config. */
 function keyEqualsValue(raw: string, key: string): string | null {
 	const match = new RegExp(`^[ \\t]*${key}[ \\t]*(?:\\+?=)[ \\t]*(.+)$`, "mu").exec(raw);
@@ -182,27 +135,30 @@ const packageJson: MetadataReader = (cwd) => {
 	return { file: "package.json", fragment: { name: name(record.name), description: description(record.description) } };
 };
 
-const pyprojectToml: MetadataReader = (cwd) => {
-	const raw = readText(cwd, "pyproject.toml");
-	if (raw === null) return null;
+const pyprojectToml: MetadataReader = (_cwd, tomlFiles) => {
+	const document = tomlFiles.read("pyproject.toml");
+	if (document === null) return null;
+	const project = tomlTableAt(document, ["project"]);
+	const poetry = tomlTableAt(document, ["tool", "poetry"]);
 	// PEP 621 `[project]` first, then Poetry's older table.
-	const projectName = tomlTableValue(raw, "project", "name") ?? tomlTableValue(raw, "tool.poetry", "name");
-	const projectDescription =
-		tomlTableValue(raw, "project", "description") ?? tomlTableValue(raw, "tool.poetry", "description");
 	return {
 		file: "pyproject.toml",
-		fragment: { name: name(projectName), description: description(projectDescription) },
+		fragment: {
+			name: name(project?.name) ?? name(poetry?.name),
+			description: description(project?.description) ?? description(poetry?.description),
+		},
 	};
 };
 
-const cargoToml: MetadataReader = (cwd) => {
-	const raw = readText(cwd, "Cargo.toml");
-	if (raw === null) return null;
+const cargoToml: MetadataReader = (_cwd, tomlFiles) => {
+	const document = tomlFiles.read("Cargo.toml");
+	if (document === null) return null;
+	const packageTable = tomlTableAt(document, ["package"]);
 	return {
 		file: "Cargo.toml",
 		fragment: {
-			name: name(tomlTableValue(raw, "package", "name")),
-			description: description(tomlTableValue(raw, "package", "description")),
+			name: name(packageTable?.name),
+			description: description(packageTable?.description),
 		},
 	};
 };
@@ -488,13 +444,13 @@ function readmeTitle(content: string): string | null {
  * a CMake project that names itself but describes itself only in its README
  * should get both, not one or neither.
  */
-export function readProjectMetadata(cwd: string): ProjectMetadata {
+export function readProjectMetadata(cwd: string, tomlFiles = createTomlFileReader(cwd)): ProjectMetadata {
 	const out: ProjectMetadata = { name: null, description: null, nameSource: null, descriptionSource: null };
 	for (const reader of METADATA_READERS) {
 		if (out.name !== null && out.description !== null) break;
 		let read: ReturnType<MetadataReader>;
 		try {
-			read = reader(cwd);
+			read = reader(cwd, tomlFiles);
 		} catch {
 			continue;
 		}