@underactive/pi-topping-moa-fusion 0.1.0

package/src/debate/runDebate.ts

@@ -0,0 +1,143 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { installShippedAgents, shippedAgentsDir, withAuthoritativeMoaAgents } from "../agents/authoritative.ts";
+import { discoverAgents } from "../agents/discovery.ts";
+import { summarizePlanPromptName } from "../config/planName.ts";
+import { loadMoaConfig, saveMoaConfig } from "../config/settings.ts";
+import type { OpinionHost } from "../opinion/runOpinion.ts";
+import { resolveContextWindow } from "../moa/modelRuntime.ts";
+import { type CancelSession, subscribeCancelOverlayOnEsc } from "../runtime/cancelRun.ts";
+import { formatMutationWarning, MutationTripwire } from "../runtime/mutationTripwire.ts";
+import { type SendUserMessageOptions, type ThinkingLevel } from "../shared/modelRefs.ts";
+import { MoaProgressWidget } from "../ui/moaProgressWidget.ts";
+import type { ObserveSession } from "../ui/observeOverlay.ts";
+import { showDebateModelPicker } from "../ui/debateModelPicker.ts";
+import { showPromptEditor } from "../ui/promptEditor.ts";
+import { repoDebateDisplayPath, saveRepoDebateFile } from "./debateFile.ts";
+import { runDebateRounds } from "./debateFanout.ts";
+import { collectDebateOutcomes, formatDebateMarkdown } from "./debateResults.ts";
+
+/** Same host surface as the opinion flow — all three MoA flows share the controller. */
+export type DebateHost = OpinionHost;
+
+export async function runInteractiveDebate(
+	pi: ExtensionAPI,
+	host: DebateHost,
+	ctx: ExtensionContext,
+	initialPrompt?: string,
+): Promise<void> {
+	if (host.getActiveCancelSession()?.run) {
+		ctx.ui.notify("A plan, opinion, or debate run is already in progress.", "warning");
+		return;
+	}
+	if (!ctx.hasUI) {
+		ctx.ui.notify("/mf-debate requires an interactive session.", "warning");
+		return;
+	}
+
+	installShippedAgents();
+	const session: CancelSession = { title: "Debate agents", run: undefined, overlayOpen: false };
+	host.setActiveCancelSession(session);
+	const unsubscribeEsc = subscribeCancelOverlayOnEsc(ctx, host, session);
+
+	try {
+		let prefill = initialPrompt?.trim() ?? "";
+		let skipEditorOnce = Boolean(prefill);
+		while (true) {
+			let topic: string | undefined;
+			if (skipEditorOnce) {
+				topic = prefill;
+				skipEditorOnce = false;
+			} else {
+				topic = await showPromptEditor(ctx, "Debate — pick a topic to argue about this repo", prefill);
+			}
+			if (!topic?.trim()) {
+				ctx.ui.notify("Debate cancelled.");
+				return;
+			}
+			topic = topic.trim();
+			prefill = topic;
+
+			const selection = await showDebateModelPicker(ctx, host.currentThinkingLevel());
+			if (!selection) return;
+			const { models, thinking, thinkingSelections, rounds } = selection;
+			const settings = loadMoaConfig();
+			saveMoaConfig({
+				...settings,
+				debateModels: models,
+				debateRounds: rounds,
+				thinkingOverrides: { ...settings.thinkingOverrides, ...thinkingSelections },
+			});
+
+			const slug = await summarizePlanPromptName(ctx, topic);
+			try {
+				saveRepoDebateFile(topic, ctx.cwd, slug, "debate-prompt");
+			} catch {
+				ctx.ui.notify("Could not save the debate prompt artifact.", "warning");
+			}
+
+			const closeStacked = () => {
+				session.closeOverlay?.();
+				host.getActiveObserveSession()?.closeOverlay?.();
+			};
+			const widget = new MoaProgressWidget(
+				ctx,
+				(ref) => resolveContextWindow(ctx, ref),
+				{
+					closeStacked,
+					title: "MoA Debate",
+					phaseLabels: { Plan: "Debate" },
+					fanoutWorkingText: "round 1 · forming positions",
+				},
+				slug,
+			);
+			widget.setPhaseModels({ Plan: models });
+			const agents = withAuthoritativeMoaAgents(
+				discoverAgents(ctx.cwd, "user").agents,
+				shippedAgentsDir(),
+			);
+			const tripwire = new MutationTripwire();
+			await tripwire.arm(ctx.cwd);
+			host.setRunningProgressWidget(widget);
+			let outcome;
+			try {
+				outcome = await runDebateRounds({ host, ctx, topic, models, thinking, rounds, session, widget, agents });
+			} finally {
+				host.setRunningProgressWidget(undefined);
+				widget.stopWidget();
+				const changed = await tripwire.check(ctx.cwd);
+				if (changed.length > 0) {
+					ctx.ui.notify(formatMutationWarning("MoA debate rounds", changed), "warning");
+				}
+			}
+
+			if (outcome.status === "cancelled") {
+				session.closeOverlay?.();
+				ctx.ui.notify("Debate run cancelled.");
+				continue;
+			}
+
+			const outcomes = collectDebateOutcomes(models, thinking, outcome.rounds);
+			const markdown = formatDebateMarkdown(topic, outcomes, outcome.rounds, slug, outcome.stoppedEarly, rounds);
+			const displayPath = repoDebateDisplayPath(slug, "debate");
+			let saved = true;
+			try {
+				saveRepoDebateFile(markdown, ctx.cwd, slug, "debate");
+			} catch {
+				saved = false;
+			}
+			const appendOnly: SendUserMessageOptions = { triggerTurn: false };
+			await pi.sendUserMessage(markdown, appendOnly);
+			const active = outcomes.filter((item) => item.finalStatus === "active-at-close").length;
+			const suffix = saved ? ` · saved to ${displayPath}` : " · artifact save failed";
+			ctx.ui.notify(
+				`${outcome.rounds.length} round${outcome.rounds.length === 1 ? "" : "s"} · ${active} of ${outcomes.length} debaters completed${suffix}`,
+				active === 0 ? "error" : saved ? "info" : "warning",
+			);
+			return;
+		}
+	} finally {
+		unsubscribeEsc?.();
+		host.setActiveCancelSession(undefined);
+	}
+}

package/src/index.ts

@@ -0,0 +1,283 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+
+import { installShippedAgents, shippedAgentsDir, withAuthoritativeMoaAgents } from "./agents/authoritative.ts";
+import { discoverAgents } from "./agents/discovery.ts";
+import {
+	buildImplementationKickoffMessage,
+	resolveHandoffPlan,
+	type ImplementationHandoff,
+} from "./moa/implementationRetry.ts";
+import { modelRefLabel, TRIGGER_TURN } from "./shared/modelRefs.ts";
+import { loadMoaConfig } from "./config/settings.ts";
+import { getPlanFilePath, getRepoPlanDirectory, isValidPlanSlug, readRepoPlanFile, saveRepoPlanFile } from "./planning/planFile.ts";
+import { showImplementingModelPicker } from "./ui/moaModelPicker.ts";
+import { showPlanReview } from "./ui/planReviewOverlay.ts";
+import { showMoaSetup } from "./ui/moaSetupOverlay.ts";
+import { runCriteriaGeneration } from "./moa/verificationCriteria.ts";
+import { stripSynthSections } from "./moa/verdicts.ts";
+import { runInteractiveOpinion, type OpinionHost } from "./opinion/runOpinion.ts";
+import { runInteractiveDebate } from "./debate/runDebate.ts";
+import { createPlanModeController } from "./planning/planMode.ts";
+import { registerEnterPlanModeTool, runInteractivePlanMode } from "./planning/tools/enterPlanMode.ts";
+import { registerExitPlanModeTool } from "./planning/tools/exitPlanMode.ts";
+import { registerMfPlanSubagentTool } from "./planning/tools/mfPlanSubagent.ts";
+import { registerWritePlanTool } from "./planning/tools/writePlan.ts";
+
+export default function mfPlanExtension(pi: ExtensionAPI): void {
+	const controller = createPlanModeController(pi);
+	const opinionHost: OpinionHost = {
+		currentThinkingLevel: controller.currentThinkingLevel,
+		getActiveCancelSession: controller.getActiveCancelSession,
+		setActiveCancelSession: controller.setActiveCancelSession,
+		openCancelOverlayIfActive: controller.openCancelOverlayIfActive,
+		getActiveObserveSession: controller.getActiveObserveSession,
+		setActiveObserveSession: (session) => { controller.moaRunHost.setActiveObserveSession(session); },
+		setRunningProgressWidget: controller.moaRunHost.setRunningProgressWidget,
+	};
+	const debateHost = opinionHost;
+	const togglePlanMode = async (ctx: Parameters<typeof controller.exitPlanMode>[0], prompt?: string): Promise<void> => {
+		if (controller.questionnaireBusy(ctx)) return;
+		if (controller.getActiveCancelSession()?.run) {
+			ctx.ui.notify("An MoA run is in progress.", "warning");
+			return;
+		}
+		if (controller.isEnabled()) controller.exitPlanMode(ctx);
+		else await runInteractivePlanMode(pi, controller, ctx, prompt);
+	};
+
+	pi.registerFlag("mf-plan", {
+		description: "Start in MoA Fusion plan mode (read-only with 5-phase workflow)",
+		type: "boolean",
+		default: false,
+	});
+	pi.registerCommand("mf-plan", {
+		description: "Toggle 'Mixture of Agents' plan mode — append a prompt (e.g. /mf-plan add dark mode) to skip the editor",
+		handler: async (args, ctx) => togglePlanMode(ctx, args.trim() || undefined),
+	});
+	pi.registerCommand("mf-preview", {
+		description: "Toggle the MoA live preview under the agent table in the active run",
+		handler: async (_args, ctx) => { controller.toggleLivePreview(ctx); },
+	});
+	pi.registerCommand("mf-opinion", {
+		description: "Ask up to 5 models for independent read-only opinions — append a question (e.g. /mf-opinion is X sound?) to skip the editor",
+		handler: async (args, ctx) => { if (controller.questionnaireBusy(ctx)) return; await runInteractiveOpinion(pi, opinionHost, ctx, args.trim() || undefined); },
+	});
+	pi.registerCommand("mf-debate", {
+		description: "Run a read-only multi-round debate between up to 5 models — append a topic (e.g. /mf-debate is X sound?) to skip the editor",
+		handler: async (args, ctx) => { if (controller.questionnaireBusy(ctx)) return; await runInteractiveDebate(pi, debateHost, ctx, args.trim() || undefined); },
+	});
+	pi.registerCommand("mf-plan-clear", {
+		description: "Clear the completed plan state so /mf-plan starts a fresh planning round (approved plans stay in .pi/mf-plan/)",
+		handler: async (_args, ctx) => { if (controller.questionnaireBusy(ctx)) return; await controller.clearCompletedPlan(ctx); },
+	});
+	pi.registerCommand("mf-plan-settings", {
+		description: "Configure the explore and cheap/fast agents, agent rosters for MoA roles, and plan options",
+		handler: async (_args, ctx) => {
+			if (controller.questionnaireBusy(ctx)) return;
+			installShippedAgents();
+			const saved = await showMoaSetup(ctx, controller.currentThinkingLevel());
+			if (saved) ctx.ui.notify("MoA Fusion Settings saved.");
+		},
+	});
+	pi.registerCommand("mf-plan-implement", {
+		description: "Retry implementation of the last approved MoA plan, optionally with a different model",
+		handler: async (_args, ctx) => {
+			if (controller.questionnaireBusy(ctx)) return;
+			if (controller.isEnabled()) controller.exitPlanMode(ctx);
+			let handoff = controller.getImplementationHandoff();
+			let plan: string | null = null;
+			let filePath = getPlanFilePath();
+
+			if (handoff) {
+				plan = resolveHandoffPlan(handoff, ctx.cwd);
+				filePath = handoff.planFilePath || filePath;
+			}
+
+			if (!plan) {
+				// Fall back to scanning repo plan directory for saved plans
+				const repoDir = getRepoPlanDirectory(ctx.cwd);
+				let planFiles: { filename: string; fullPath: string; mtime: number; slug: string }[] = [];
+				try {
+					if (fs.existsSync(repoDir)) {
+						const entries = fs.readdirSync(repoDir);
+						planFiles = entries
+							.filter((file) => file.endsWith("__plan.md") && !file.endsWith("__plan-prompt.md"))
+							.map((file) => {
+								const slug = file.slice(0, -"__plan.md".length);
+								const fullPath = path.join(repoDir, file);
+								const stat = fs.statSync(fullPath);
+								return { filename: file, fullPath, mtime: stat.mtimeMs, slug };
+							})
+							.filter((file) => isValidPlanSlug(file.slug))
+							.sort((a, b) => b.mtime - a.mtime);
+					}
+				} catch {
+					// Fall through if reading directory fails
+				}
+
+				if (planFiles.length === 0) {
+					ctx.ui.notify("No approved plan found — run /mf-plan first.", "warning");
+					return;
+				}
+
+				if (!ctx.hasUI) {
+					ctx.ui.notify("No in-session approved plan found — run /mf-plan in an interactive session first.", "warning");
+					return;
+				}
+
+				const options = planFiles.map((f) => f.slug);
+				const selectedSlug = await ctx.ui.select("Select plan found on disk to review:", options);
+				if (!selectedSlug) return;
+				const chosenFile = planFiles.find((f) => f.slug === selectedSlug);
+				if (!chosenFile) {
+					ctx.ui.notify("Selected plan could not be resolved.", "error");
+					return;
+				}
+
+				let diskPlan: string;
+				try {
+					diskPlan = fs.readFileSync(chosenFile.fullPath, "utf8");
+				} catch {
+					ctx.ui.notify(`Failed to read plan from ${chosenFile.fullPath}.`, "error");
+					return;
+				}
+
+				// Plans found on disk are repo artifacts, not something this session's user
+				// necessarily authored or has seen — require an explicit content review
+				// before treating one as approved, unlike the in-session handoff above.
+				let approved = false;
+				if (ctx.mode === "tui") {
+					while (true) {
+						const decision = await showPlanReview(ctx, diskPlan, undefined, chosenFile.slug, false);
+						if (decision === "edit") {
+							const edited = await ctx.ui.editor("Edit Plan", diskPlan);
+							if (edited?.trim()) diskPlan = stripSynthSections(edited.trim());
+							continue;
+						}
+						approved = decision === "approve";
+						break;
+					}
+				} else {
+					approved = await ctx.ui.confirm(
+						`Approve plan found on disk: ${chosenFile.slug}?`,
+						`This plan was found in .pi/mf-plan/ and may not have been written in this session. Review before approving:\n\n${diskPlan}`,
+					);
+				}
+
+				if (!approved) {
+					ctx.ui.notify("Plan not approved — implementation not started.", "warning");
+					return;
+				}
+
+				plan = diskPlan;
+				filePath = chosenFile.fullPath;
+				handoff = {
+					plan,
+					planFilePath: filePath,
+					repoPlanSlug: chosenFile.slug,
+					model: ctx.model,
+					timestamp: Date.now(),
+				};
+			}
+
+			const selection = await showImplementingModelPicker(
+				ctx,
+				controller.currentThinkingLevel(),
+				"Resume implementation — choose a model and thinking level",
+			);
+
+			if (ctx.hasUI && !selection) {
+				ctx.ui.notify("Implementation resume cancelled.", "warning");
+				return;
+			}
+
+			if (selection) {
+				await controller.applyImplementingSelection(
+					ctx,
+					selection,
+					`Switched to ${modelRefLabel(selection.ref)} for implementation.`,
+				);
+			}
+
+			// Verify a resumed implementation too: prefer the handoff's own verifier,
+			// else fall back to the configured verifier so /mf-plan-implement after a
+			// restart (or on a plan that predates the verifier role) is still checked.
+			const config = loadMoaConfig();
+			const resolvedVerifier = handoff?.verifier ?? config.verifier;
+			const resolvedVerifierThinking = handoff?.verifierThinking
+				?? (resolvedVerifier ? config.thinkingOverrides[modelRefLabel(resolvedVerifier)] : undefined);
+			let resolvedCriteria = handoff?.verificationCriteria
+				?? (handoff?.repoPlanSlug ? readRepoPlanFile(ctx.cwd, handoff.repoPlanSlug, "criteria") : undefined);
+			if (!resolvedCriteria && resolvedVerifier && config.synthesizer) {
+				installShippedAgents();
+				const generated = await runCriteriaGeneration({
+					ctx,
+					agents: withAuthoritativeMoaAgents(discoverAgents(ctx.cwd, "user").agents, shippedAgentsDir()),
+					synthesizer: config.synthesizer,
+					thinking: config.thinkingOverrides[modelRefLabel(config.synthesizer)],
+					plan,
+				});
+				if (generated) {
+					resolvedCriteria = generated.markdown;
+					if (handoff?.repoPlanSlug) saveRepoPlanFile(resolvedCriteria, ctx.cwd, handoff.repoPlanSlug, "criteria");
+				} else {
+					ctx.ui.notify("Verification criteria could not be generated; the verifier will judge plan steps directly.", "warning");
+				}
+			}
+			const updatedHandoff: ImplementationHandoff = {
+				...handoff,
+				plan,
+				planFilePath: filePath,
+				model: selection?.ref ?? handoff?.model ?? ctx.model,
+				thinking: selection?.thinking ?? handoff?.thinking ?? controller.currentThinkingLevel(),
+				verifier: resolvedVerifier,
+				verifierThinking: resolvedVerifierThinking,
+				verificationCriteria: resolvedCriteria,
+				verificationRepairs: handoff?.verificationRepairs ?? 0,
+				timestamp: Date.now(),
+			};
+			controller.setImplementationHandoff(updatedHandoff);
+			controller.markImplementationPending(ctx);
+
+			const note = "This is a manual resume of the approved plan.";
+			await pi.sendUserMessage(
+				buildImplementationKickoffMessage(plan, filePath, note),
+				TRIGGER_TURN,
+			);
+		},
+	});
+	// Secondary cancel trigger, and the only one in the mf_plan_subagent
+	// tool path — there the main agent is streaming, so plain ESC must keep
+	// pi's default abort-the-whole-turn behavior.
+	pi.registerShortcut(Key.f4, {
+		description: "Cancel running plan subagents",
+		handler: async (ctx) => { if (controller.questionnaireBusy(ctx)) return; controller.openCancelOverlayIfActive(ctx); },
+	});
+	pi.registerShortcut(Key.f3, {
+		description: "Observe running plan agents",
+		handler: async (ctx) => { if (controller.questionnaireBusy(ctx)) return; controller.openObserveOverlayIfActive(ctx); },
+	});
+	pi.registerShortcut(Key.f2, {
+		description: "Toggle the live preview under tool activity",
+		handler: async (ctx) => { controller.toggleLivePreview(ctx); },
+	});
+
+	registerEnterPlanModeTool(pi, controller);
+	registerWritePlanTool(pi, controller.isEnabled);
+	registerMfPlanSubagentTool(pi, controller);
+	registerExitPlanModeTool(pi, controller);
+
+	pi.on("context", controller.onContext);
+	pi.on("before_agent_start", controller.onBeforeAgentStart);
+	pi.on("agent_start", controller.onAgentStart);
+	pi.on("message_start", controller.onMessageStart);
+	pi.on("message_update", controller.onMessageUpdate);
+	pi.on("tool_execution_start", controller.onToolExecutionStart);
+	pi.on("message_end", controller.onMessageEnd);
+	pi.on("agent_settled", controller.onAgentSettled);
+	pi.on("session_start", controller.onSessionStart);
+	pi.on("session_shutdown", controller.onSessionShutdown);
+}

package/src/moa/conflictContract.ts

@@ -0,0 +1,49 @@
+/**
+ * Conflict-surfacing contract for the MoA synthesizer.
+ *
+ * The `## Conflicts` / `## Open Question` protocol lives in the
+ * moa-synthesizer agent prompt — but provider bridges replace that system
+ * prompt with their own harness (see planlessRetry.ts), so a bridged
+ * synthesizer silently plans solo: it resolves every disagreement in prose
+ * and never emits the markup the orchestrator's `## Conflicts` parser and
+ * conflict-review overlay need. Like the verdict contract (verdicts.ts),
+ * this block rides the task text — the only channel guaranteed to survive a
+ * bridge's prompt override.
+ *
+ * The embedded worked example is exported so tests can prove it parses into
+ * exactly the structure conflictOverlay.ts expects; if you change the markup
+ * here, conflictOverlay.ts, agents/moa-synthesizer.md, and that test must
+ * move in lockstep.
+ */
+
+/** Parser-matched worked example embedded in the contract. */
+export const CONFLICT_CONTRACT_EXAMPLE = [
+	"## Conflicts",
+	"",
+	"### Conflict: Auth storage",
+	"",
+	"- **Decision:** Choose where sign-in information is stored; this affects both security and how much of the existing sign-in flow can stay unchanged.",
+	"- **Recommended:** Keep the current sign-in experience",
+	"- **Details:** Store session IDs in `Secure`, `HttpOnly` cookies so the existing middleware stays compatible and page scripts cannot read them.",
+	"- **Alternative** (Proposer 2): Make sign-in data available to browser code",
+	"- **Details:** Store JWTs in `localStorage`; this can simplify cross-service access but lets an injected page script read the token.",
+].join("\n");
+
+/** Task-text block demanding one `### Conflict:` block per substantive proposer disagreement. */
+export function buildConflictContract(labels: string[]): string {
+	return [
+		"Conflict-surfacing requirement: when two or more proposers substantively disagree on one or more decision points, every full plan you emit MUST also include a `## Conflicts` section, placed after `## Proposer Verdicts`, with one `### Conflict:` block per disagreement. Use exactly this parser-matched markup:",
+		"",
+		CONFLICT_CONTRACT_EXAMPLE,
+		"",
+		"Rules:",
+		"- Write the full plan body first using your recommended choices in place, so the plan reads as final even before user confirmation; append `## Conflicts` AFTER all other sections — it is never your entire output.",
+		"- Omit the section entirely when the proposers agree on all decision points or when only one proposer covered a point — never include a conflict the user has no realistic alternative for, and never invent a disagreement to comply with this requirement.",
+		"- Exactly one `**Decision:**` line per conflict, placed before its options. Exactly one `**Recommended:**` line per conflict, immediately followed by exactly one `**Details:**` line. One `**Alternative** (Proposer N)` line per other distinct approach worth surfacing, each immediately followed by its own `**Details:**` line.",
+		`- Attribute alternatives only to blinded slot labels already present in your input. Blinded proposer slots in this run: ${labels.join(", ")}. Never invent or rename labels, and never output any model name, family, provider, or version anywhere.`,
+		"- Write each Recommended/Alternative summary as an outcome the person can choose, understandable without code syntax, type names, or file paths; put technical specifics and tradeoffs in `**Details:**`, kept to one line.",
+		"- Supersession rule: if your input contains user conflict resolutions (a \"User reviewed your conflict recommendations\" block) or post-review user feedback, those directives override this requirement — honor every selection, resolve any free-form chat feedback, drop the `## Conflicts` section entirely from your revised output, and emit the complete final plan without it.",
+		"",
+		"Clarifying-question option: only when a disagreement is a genuine ambiguity in user intent that you cannot resolve from the plans alone, output a section titled exactly `## Open Question` containing only that one question, as your ENTIRE output — write nothing else in that reply, and none of the sections above. You will be re-invoked with the user's answer appended. Prefer resolving ambiguities yourself and noting the resolution in the final plan; if your input already contains an answer to an earlier question, incorporate it and do not emit `## Open Question` again.",
+	].join("\n");
+}

package/src/moa/conflicts.ts

@@ -0,0 +1,153 @@
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+
+export const CHAT_VALUE = "__chat__";
+
+export interface ConflictOption {
+	value: string;
+	/** Short, plain-language outcome shown on the primary selectable line. */
+	label: string;
+	/** Technical implementation details and tradeoffs shown dimmed below the label. */
+	description: string;
+	proposerLabel?: string;
+	recommended: boolean;
+}
+
+export interface Conflict {
+	id: string;
+	label: string;
+	prompt: string;
+	/** Already ordered: [recommended, ...alternatives, chat option]. */
+	options: ConflictOption[];
+}
+
+export interface ConflictAnswer {
+	optionValue: string;
+	kind: "recommended" | "alternative" | "chat";
+	chatText?: string;
+}
+
+export function chatOption(): ConflictOption {
+	return {
+		value: CHAT_VALUE,
+		label: "Chat about this",
+		description: "Ask a question or explain what you'd prefer instead.",
+		recommended: false,
+	};
+}
+
+const CONFLICTS_SECTION_RE = /^##\s*Conflicts\s*$/m;
+const CONFLICT_HEADER_RE = /^###\s*Conflict:\s*(.+)$/gm;
+const DECISION_RE = /^-\s*\*\*Decision:\*\*\s*(.+)$/;
+// Legacy em-dash reasons require whitespace around the separator so hyphenated
+// summaries such as “sign-in” remain intact.
+const RECOMMENDED_RE = /^-\s*\*\*Recommended:\*\*\s*(.+?)(?:\s+[—-]\s+(.+))?$/;
+const ALTERNATIVE_RE = /^-\s*\*\*Alternative\*\*\s*\((Proposer \d+)\):\s*(.+?)(?:\s+[—-]\s+(.+))?$/;
+const DETAILS_RE = /^-\s*\*\*Details:\*\*\s*(.*)$/;
+
+function slugify(label: string): string {
+	return (
+		label
+			.toLowerCase()
+			.trim()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "") || "option"
+	);
+}
+
+/**
+ * Extracts a `## Conflicts` section (if present) from synthesizer output,
+ * parsing it into structured `Conflict` records and returning the plan body
+ * with that section stripped out (so it never lands in the written plan
+ * file or the approval overlay). Malformed markup degrades gracefully to
+ * `{ conflicts: [], remainingPlan: output }`.
+ */
+export function parseConflicts(output: string): { conflicts: Conflict[]; remainingPlan: string } {
+	const startMatch = CONFLICTS_SECTION_RE.exec(output);
+	if (!startMatch) return { conflicts: [], remainingPlan: output };
+
+	const sectionStart = startMatch.index;
+	const afterHeader = sectionStart + startMatch[0].length;
+	let sectionEnd = output.length;
+	const rest = output.slice(afterHeader);
+	const nextMatch = /^##\s+/m.exec(rest);
+	if (nextMatch) sectionEnd = afterHeader + nextMatch.index;
+
+	const block = output.slice(afterHeader, sectionEnd);
+	const remainingPlan = (output.slice(0, sectionStart) + output.slice(sectionEnd)).replace(/\n{3,}/g, "\n\n").trim();
+
+	const headerMatches = [...block.matchAll(CONFLICT_HEADER_RE)];
+	const conflicts: Conflict[] = [];
+
+	for (let i = 0; i < headerMatches.length; i++) {
+		const match = headerMatches[i];
+		const label = stripTerminalSequences(match[1].trim());
+		const start = match.index! + match[0].length;
+		const end = i + 1 < headerMatches.length ? headerMatches[i + 1].index! : block.length;
+		const body = block.slice(start, end);
+		const bodyLines = body.split("\n").map((l) => l.trim()).filter(Boolean);
+
+		const options: ConflictOption[] = [];
+		let decision: string | undefined;
+		let precedingOption: ConflictOption | undefined;
+		for (const line of bodyLines) {
+			const decisionMatch = DECISION_RE.exec(line);
+			if (decisionMatch) {
+				decision = stripTerminalSequences(decisionMatch[1].trim());
+				precedingOption = undefined;
+				continue;
+			}
+			const detailsMatch = DETAILS_RE.exec(line);
+			if (detailsMatch) {
+				// The protocol puts Details immediately after its option. Explicit details
+				// replace an em-dash reason, which remains only for legacy output.
+				if (precedingOption) precedingOption.description = stripTerminalSequences(detailsMatch[1].trim());
+				precedingOption = undefined;
+				continue;
+			}
+			const recMatch = RECOMMENDED_RE.exec(line);
+			if (recMatch) {
+				const summary = stripTerminalSequences(recMatch[1].trim());
+				const legacyReason = stripTerminalSequences(recMatch[2]?.trim() ?? "");
+				const option: ConflictOption = {
+					value: `${slugify(summary)}-${options.length}`,
+					label: `${summary} (Recommended)`,
+					description: legacyReason,
+					recommended: true,
+				};
+				options.push(option);
+				precedingOption = option;
+				continue;
+			}
+			const altMatch = ALTERNATIVE_RE.exec(line);
+			if (altMatch) {
+				const proposerLabel = altMatch[1].trim();
+				const summary = stripTerminalSequences(altMatch[2].trim());
+				const legacyReason = stripTerminalSequences(altMatch[3]?.trim() ?? "");
+				const option: ConflictOption = {
+					value: `${slugify(`${proposerLabel}-${summary}`)}-${options.length}`,
+					label: summary,
+					description: legacyReason,
+					proposerLabel,
+					recommended: false,
+				};
+				options.push(option);
+				precedingOption = option;
+				continue;
+			}
+			precedingOption = undefined;
+		}
+
+		if (options.length === 0) continue;
+		// Ensure the recommended option (if any) leads.
+		options.sort((a, b) => (b.recommended ? 1 : 0) - (a.recommended ? 1 : 0));
+
+		conflicts.push({
+			id: `conflict-${i}-${slugify(label)}`,
+			label,
+			prompt: decision ?? `Choose how to handle “${label}”.`,
+			options: [...options, chatOption()],
+		});
+	}
+
+	return { conflicts, remainingPlan };
+}

package/src/moa/contextContract.ts

@@ -0,0 +1,52 @@
+/**
+ * Auditable-reasoning contract for the MoA synthesizer.
+ *
+ * The moa-synthesizer prompt requires the plan's Context section to carry
+ * three subsections — `### Evaluation dimensions`, `### Proposer alignment`,
+ * and `### Synthesis decisions` — but models skip them under output pressure,
+ * collapsing the MoA reconciliation into ordinary prose (recent plan files
+ * show exactly that drift). Like the verdict contract (verdicts.ts), the
+ * orchestrator knows what a complete synthesis looks like, so it validates
+ * presence and rejects (one corrective retry) a first full plan that omits
+ * any of the three. The requirement rides the task text because provider
+ * bridges drop the agent system prompt (see planlessRetry.ts).
+ */
+
+/** Exact H3 headings the synthesizer must place under `## Context`. */
+export const CONTEXT_SUBSECTION_HEADINGS = [
+	"Evaluation dimensions",
+	"Proposer alignment",
+	"Synthesis decisions",
+] as const;
+
+/** Task-text block demanding the three Context subsections in every full plan. */
+export function buildContextSubsectionsContract(): string {
+	return [
+		"Auditable-reasoning requirement: every full plan you emit MUST open with a `## Context` section containing these three subsections, in this order, directly after the normal Context content:",
+		"",
+		...CONTEXT_SUBSECTION_HEADINGS.map((heading) => `- \`### ${heading}\``),
+		"",
+		"- `### Evaluation dimensions` — reason separately about correctness, completeness, feasibility & effort, risk, and simplicity; never collapse them into one impression.",
+		"- `### Proposer alignment` — where proposers unanimously agreed, what they unanimously rejected, and where they differed, with shared assumptions sanity-checked.",
+		"- `### Synthesis decisions` — what you recombined, added, or dropped, and one-line decisions for each disagreement using blinded slot labels.",
+		"",
+		"All MoA reconciliation commentary belongs inside `## Context` — nowhere else. A plan missing any of these three subsections will be rejected and sent back to you. They are required in every full-plan output, including revisions after conflict resolutions or user feedback.",
+	].join("\n");
+}
+
+/**
+ * Required headings absent from the output. Matching is case-insensitive
+ * with flexible whitespace so casing drift does not burn a corrective retry;
+ * the contract text still demands the exact headings.
+ */
+export function missingContextSubsections(output: string): string[] {
+	return CONTEXT_SUBSECTION_HEADINGS.filter((heading) => {
+		const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		return !new RegExp(`^#{3}\\s*${escaped}\\s*$`, "im").test(output);
+	});
+}
+
+export function buildContextRetryHeader(missing: string[]): string {
+	const list = missing.map((heading) => `\`### ${heading}\``).join(", ");
+	return `IMPORTANT: Your previous output (quoted below) is rejected because its \`## Context\` section is missing required subsection(s): ${list}. Re-emit the COMPLETE plan with \`## Context\` opening on the normal context content followed by all three subsections — \`### Evaluation dimensions\`, \`### Proposer alignment\`, \`### Synthesis decisions\` — carrying your MoA reconciliation reasoning. Do not drop or alter the rest of the plan.`;
+}