@underactive/pi-topping-moa-fusion 0.1.0 → 0.3.0

package/src/moa/verification.ts

@@ -11,20 +11,26 @@
  * evidence — the implementer's own report is treated as an untrusted claim.
  *
  * A `complete` verdict with a clean script gate ends the phase. Anything less
- * offers the user a bounded repair round (up to MAX_VERIFICATION_REPAIRS): the
- * verifier's gaps and failing checks are shown inline in the repair/accept
- * dialog and sent back to the same in-session implementer via the existing
- * kickoff machinery. The result is then verified again. "Accept implementation
- * as-is" is always available.
+ * offers the user a bounded repair round (up to the `maxVerificationRepairs`
+ * setting, default 2; 0 disables the offer): the verifier's gaps and failing
+ * checks are shown inline in the repair/accept dialog and sent back to the same
+ * in-session implementer via the existing kickoff machinery. The result is then
+ * verified again. "Accept implementation as-is" is always available.
+ *
+ * Once that budget is spent (or when it is zero, or no UI can offer the choice),
+ * the phase writes a `<slug>__verification-handoff.md` next to the plan holding
+ * every criterion's status plus the whole frozen checklist, and names that file
+ * in the exhaustion notification so the fix/verification loop can be continued
+ * by hand.
  */
 
-import { CONFIG_DIR_NAME, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import { loadMoaConfig } from "../config/settings.ts";
 import { installShippedAgents, shippedAgentsDir, withAuthoritativeMoaAgents } from "../agents/authoritative.ts";
 import { discoverAgents } from "../agents/discovery.ts";
-import { readRepoPlanFile, saveRepoPlanFile } from "../planning/planFile.ts";
+import { readRepoPlanFile, repoPlanDisplayPath, saveRepoPlanFile } from "../planning/planFile.ts";
 import { CancelRun, type CancelSession } from "../runtime/cancelRun.ts";
 import { formatMutationWarning, MutationTripwire } from "../runtime/mutationTripwire.ts";
 import { getFinalOutput, getResultOutput, isFailedResult, type SingleResult } from "../runtime/results.ts";
@@ -42,9 +48,6 @@ import { parseVerificationCriteria, sectionBullets, type VerificationCriterion }
 import type { MoaRunHost } from "./runContext.ts";
 import { captureImplementationDiff, discoverVerifyScripts, runVerifyScript, type VerifyResult } from "./verifyGate.ts";
 
-/** How many verifier-driven repair rounds a single implementation may consume. */
-export const MAX_VERIFICATION_REPAIRS = 2;
-
 export type VerificationVerdictValue = "complete" | "partial" | "incomplete" | "cannot-verify";
 
 export interface CriterionVerdict {
@@ -349,6 +352,58 @@ export function formatVerificationReport(parsed: VerificationVerdict, failedScri
 	return sections.join("\n\n");
 }
 
+/** Markdown handoff written when automatic verifier repairs are exhausted or disabled. */
+export function buildVerificationExhaustionHandoff(input: {
+	repairsUsed: number;
+	maxRepairs: number;
+	parsed: VerificationVerdict;
+	criteria: VerificationCriterion[];
+	failedScripts: VerifyResult[];
+	planFilePath: string;
+	verificationReportPath?: string;
+	/** Frozen checklist on disk, referenced alongside the inlined criteria. */
+	criteriaFilePath?: string;
+}): string {
+	const { repairsUsed, maxRepairs, parsed, criteria, failedScripts, planFilePath, verificationReportPath, criteriaFilePath } = input;
+	const sections: string[] = [
+		"# Verification repair handoff",
+		"",
+		maxRepairs === 0
+			? "Automatic verifier repair rounds are disabled in settings (`maxVerificationRepairs: 0`)."
+			: `Verifier repair rounds are exhausted (${repairsUsed} of ${maxRepairs} used).`,
+		"",
+		"Use this file to continue the fix/verification loop manually: send the criteria status and gaps below to the implementer, apply fixes, then re-run verification (for example via `/mf-plan-implement` or by approving a follow-up turn).",
+		"",
+		`Approved plan: ${planFilePath}`,
+	];
+	if (verificationReportPath) sections.push(`Full verifier report: ${verificationReportPath}`);
+	if (criteriaFilePath) sections.push(`Frozen verification criteria: ${criteriaFilePath}`);
+	sections.push(
+		"",
+		"## Verification result",
+		`**Verdict:** ${parsed.verdict ?? "unknown"}`,
+		parsed.summary ? `**Summary:** ${parsed.summary}` : "**Summary:** (none)",
+	);
+	if (criteria.length > 0) {
+		const byId = new Map(parsed.criteria.map((criterion) => [criterion.id, criterion]));
+		const statusLines = criteria.map((criterion) => {
+			const verdict = byId.get(criterion.id);
+			if (!verdict) return `- **${criterion.id}:** not judged — ${criterion.text}`;
+			return `- **${criterion.id}:** ${verdict.status} — ${verdict.evidence || criterion.text}`;
+		});
+		sections.push("", "## Criteria status", ...statusLines, "", "## Full verification criteria", ...criteria.map((criterion) => `- **${criterion.id}:** ${criterion.text}`));
+	} else if (parsed.steps.length > 0) {
+		sections.push("", "## Step verdicts", ...parsed.steps.map((step) => `- ${step}`));
+	}
+	if (parsed.gaps.length > 0) {
+		sections.push("", "## Gaps", ...parsed.gaps.map((gap) => `- ${gap}`));
+	}
+	if (failedScripts.length > 0) {
+		sections.push("", "## Failing project checks", ...failedScripts.map((result) => `- \`${result.command}\` failed (exit ${result.exitCode})`));
+	}
+	return sections.join("\n");
+}
+
 function buildRepairNote(parsed: VerificationVerdict, failedScripts: VerifyResult[]): string {
 	const parts: string[] = [
 		"The verifier reviewed your implementation against the approved plan and found it did not fully land.",
@@ -434,7 +489,7 @@ export async function runVerificationDecision(deps: {
 			// Reactivate the Implement row for the repair round and leave the table
 			// mounted; the next settled turn re-enters this verification flow.
 			widget?.settleRoleRow("Verify", "done");
-			if (handoff.model) widget?.switchToImplementing(handoff.model, "addressing verifier findings…", handoff.thinking);
+			if (handoff.model) widget?.switchToImplementing(handoff.model, "addressing verifier findings", handoff.thinking);
 			host.markImplementationPending(ctx);
 			const repairNote = buildRepairNote(parsed, failedScripts);
 			await host.pi.sendUserMessage(
@@ -492,7 +547,7 @@ export async function runImplementationVerification(
 	widget?.setActivePhase("Verify");
 	// `activeVerifierThinking` is not declared yet; the initial project-checks
 	// activation carries the handoff's verifier level, which it is seeded from.
-	widget?.switchToVerifying(verifier, "running project checks…", handoff.verifierThinking);
+	widget?.switchToVerifying(verifier, "running project checks", handoff.verifierThinking);
 
 	// Diff and script gate run in the parent, BEFORE the verifier's mutation
 	// tripwire is armed: `npm test` may legitimately write snapshots/coverage,
@@ -532,7 +587,7 @@ export async function runImplementationVerification(
 
 	const runVerifierPreflight = async (): Promise<VerifierRunOutcome> => {
 		const verifier = activeVerifier;
-		widget?.switchToVerifying(verifier, "checking verifier…", activeVerifierThinking);
+		widget?.switchToVerifying(verifier, "checking verifier", activeVerifierThinking);
 		const result = await runVerifier(
 			ctx.cwd, agents, "moa-verifier", "Reply with the single word ok", undefined, undefined, undefined,
 			modelRefLabel(verifier), activeVerifierThinking, {
@@ -548,7 +603,7 @@ export async function runImplementationVerification(
 		const tripwire = new MutationTripwire();
 		await tripwire.arm(ctx.cwd);
 
-		widget?.switchToVerifying(verifier, "verifying implementation…", activeVerifierThinking);
+		widget?.switchToVerifying(verifier, "verifying implementation", activeVerifierThinking);
 		widget?.updateRoleTranscript("Verify", []);
 
 		const session: CancelSession = { title: "MoA verification", run: undefined, overlayOpen: false };
@@ -707,7 +762,7 @@ export async function runImplementationVerification(
 				: outcome.output;
 			try {
 				saveRepoPlanFile(verificationOutput, ctx.cwd, host.getPlanRepoSlug()!, "verification");
-				verificationReportPath = `${CONFIG_DIR_NAME}/mf-plan/${host.getPlanRepoSlug()!}__verification.md`;
+				verificationReportPath = repoPlanDisplayPath(host.getPlanRepoSlug()!, "verification");
 			} catch {
 				// Persisting the report is best-effort; verification proceeds regardless.
 			}
@@ -756,15 +811,17 @@ export async function runImplementationVerification(
 	const failedScripts = scriptResults.filter((r) => r.status === "fail");
 	if (verificationPassed(parsed.verdict, scriptResults)) {
 		const checksNote = scriptResults.length > 0 ? " and all project checks passed" : "";
-		ctx.ui.notify(criteria.length > 0
+		const message = criteria.length > 0
 			? `Verification passed — all ${criteria.length} criteria met${checksNote}.`
-			: `Verification passed — the implementation matches the approved plan${checksNote}.`);
+			: `Verification passed — the implementation matches the approved plan${checksNote}.`;
+		ctx.ui.notify(ctx.ui.theme.bg("toolSuccessBg", ctx.ui.theme.fg("success", message)));
 		finish("done");
 		return;
 	}
 
 	const repairsUsed = activeHandoff.verificationRepairs ?? 0;
-	if (ctx.hasUI && repairsUsed < MAX_VERIFICATION_REPAIRS) {
+	const maxRepairs = config.maxVerificationRepairs;
+	if (ctx.hasUI && maxRepairs > 0 && repairsUsed < maxRepairs) {
 		await runVerificationDecision({
 			ctx,
 			host,
@@ -785,7 +842,47 @@ export async function runImplementationVerification(
 
 	const summary = buildVerificationSummary(parsed, scriptResults).join("\n");
 	const report = formatVerificationReport(parsed, failedScripts);
-	const exhaustedNote = repairsUsed >= MAX_VERIFICATION_REPAIRS ? "\n\nRepair rounds are exhausted." : "";
-	ctx.ui.notify(`${summary}\n\n${report}${exhaustedNote}`, "warning");
+	let handoffPath: string | undefined;
+	// The run's own slug is authoritative, but a resumed implementation may have
+	// verified without one (e.g. /mf-plan-implement after a restart); the handoff
+	// carries the slug its plan was saved under, so fall back to it.
+	const repoPlanSlug = host.getPlanRepoSlug() ?? activeHandoff.repoPlanSlug;
+	if (repoPlanSlug) {
+		try {
+			saveRepoPlanFile(
+				buildVerificationExhaustionHandoff({
+					repairsUsed,
+					maxRepairs,
+					parsed,
+					criteria,
+					failedScripts,
+					planFilePath: activeHandoff.planFilePath,
+					verificationReportPath,
+					// Only point at the checklist file when one is actually on disk;
+					// criteria can come from the handoff alone.
+					criteriaFilePath: readRepoPlanFile(ctx.cwd, repoPlanSlug, "criteria")
+						? repoPlanDisplayPath(repoPlanSlug, "criteria")
+						: undefined,
+				}),
+				ctx.cwd,
+				repoPlanSlug,
+				"verification-handoff",
+			);
+			handoffPath = repoPlanDisplayPath(repoPlanSlug, "verification-handoff");
+		} catch {
+			// Persisting the handoff is best-effort; the exhaustion notification still fires.
+		}
+	}
+	// The notification is the only place the handoff is announced, so say plainly
+	// when it could not be written rather than silently dropping the location.
+	const handoffNote = handoffPath
+		? `\n\nContinue fix/verification using the handoff file:\n${handoffPath}`
+		: "\n\nThe verification handoff file could not be saved — the findings above are the only record.";
+	const exhaustedNote = maxRepairs === 0
+		? "\n\nAutomatic verifier repair rounds are disabled in settings."
+		: repairsUsed >= maxRepairs
+			? "\n\nRepair rounds are exhausted."
+			: "";
+	ctx.ui.notify(`${summary}\n\n${report}${exhaustedNote}${handoffNote}`, "warning");
 	finish("done");
 }

package/src/moa/verificationCriteria.ts

@@ -84,7 +84,7 @@ export async function runCriteriaGeneration(input: {
 	observe?: ObserveSession;
 }): Promise<{ criteria: VerificationCriterion[]; markdown: string } | undefined> {
 	const { ctx, agents, synthesizer, thinking, plan, session, widget } = input;
-	widget?.switchToSynthesizing(synthesizer, "writing verification criteria…", thinking);
+	widget?.switchToSynthesizing(synthesizer, "writing verification criteria", thinking);
 	const run = new CancelRun();
 	const slot = run.add(modelRefLabel(synthesizer));
 	if (session) {

package/src/opinion/opinionFanout.ts

@@ -27,6 +27,7 @@ export interface OpinionFanoutOptions {
 	session: CancelSession;
 	widget: MoaProgressWidget;
 	agents: AgentConfig[];
+	maxConcurrency: number;
 }
 
 export type OpinionFanoutResult =
@@ -34,9 +35,9 @@ export type OpinionFanoutResult =
 	| { status: "cancelled" };
 
 export async function runOpinionFanout(options: OpinionFanoutOptions): Promise<OpinionFanoutResult> {
-	const { host, ctx, question, models, thinking, session, widget, agents } = options;
+	const { host, ctx, question, models, thinking, session, widget, agents, maxConcurrency } = options;
 	const originalTask = buildOpinionTask(question);
-	widget.startFanout(models, thinking);
+	widget.startFanout(models, thinking, maxConcurrency);
 	const observe: ObserveSession = {
 		title: "MoA opinions",
 		phase: "fanout",
@@ -57,7 +58,7 @@ export async function runOpinionFanout(options: OpinionFanoutOptions): Promise<O
 			tasks: ModelParallelAgentTask[],
 			indexMap: (index: number) => number,
 			currentRun: CancelRun,
-		): Promise<SingleResult[]> => runWidgetFanout({ ctx, agents, tasks, run: currentRun, session, widget, observe, models, indexMap });
+		): Promise<SingleResult[]> => runWidgetFanout({ ctx, agents, tasks, run: currentRun, session, widget, observe, models, indexMap, maxConcurrency });
 
 		const run = new CancelRun();
 		session.title = "Opinion agents";
@@ -107,7 +108,7 @@ export async function runOpinionFanout(options: OpinionFanoutOptions): Promise<O
 				const ref = models[opinionIndex];
 				const label = modelRefLabel(ref);
 				const retryTask = buildOpinionRetryTask(originalTask, getFinalOutput(results[opinionIndex].messages));
-				widget.update(opinionIndex, "working", "retrying: no opinion produced");
+				widget.update(opinionIndex, "queued", "retrying: no opinion produced");
 				const observed = observe.agents[opinionIndex];
 				if (observed) {
 					observed.state = "working";

package/src/opinion/runOpinion.ts

@@ -1,18 +1,19 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { isKeyRelease, Key, matchesKey } from "@earendil-works/pi-tui";
 
 import { installShippedAgents, shippedAgentsDir, withAuthoritativeMoaAgents } from "../agents/authoritative.ts";
 import { discoverAgents } from "../agents/discovery.ts";
 import { summarizePlanPromptName } from "../config/planName.ts";
+import { slugifyPlanName } from "../planning/planFile.ts";
 import { loadMoaConfig, saveMoaConfig } from "../config/settings.ts";
 import { resolveContextWindow } from "../moa/modelRuntime.ts";
-import type { CancelSession } from "../runtime/cancelRun.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 { showOpinionModelPicker } from "../ui/opinionModelPicker.ts";
 import { showPromptEditor } from "../ui/promptEditor.ts";
+import { planNamingOverlay, withWorkingOverlay } from "../ui/workingOverlay.ts";
 import { runOpinionFanout } from "./opinionFanout.ts";
 import { repoOpinionDisplayPath, saveRepoOpinionFile } from "./opinionFile.ts";
 import { collectOpinionOutcomes, formatOpinionsMarkdown } from "./opinionResults.ts";
@@ -45,15 +46,7 @@ export async function runInteractiveOpinion(
 	installShippedAgents();
 	const session: CancelSession = { title: "Opinion agents", run: undefined, overlayOpen: false };
 	host.setActiveCancelSession(session);
-	const unsubscribeEsc = ctx.mode === "tui"
-		? ctx.ui.onTerminalInput((data) => {
-			if (isKeyRelease(data) || !matchesKey(data, Key.escape)) return undefined;
-			if (host.getActiveObserveSession()?.overlayOpen) return undefined;
-			if (session.overlayOpen) return undefined;
-			if (!session.run) return undefined;
-			return host.openCancelOverlayIfActive(ctx) ? { consume: true } : undefined;
-		})
-		: undefined;
+	const unsubscribeEsc = subscribeCancelOverlayOnEsc(ctx, host, session);
 
 	try {
 		let prefill = initialPrompt?.trim() ?? "";
@@ -83,7 +76,11 @@ export async function runInteractiveOpinion(
 				thinkingOverrides: { ...settings.thinkingOverrides, ...thinkingSelections },
 			});
 
-			const slug = await summarizePlanPromptName(ctx, question);
+			const slug = await withWorkingOverlay(
+				ctx,
+				planNamingOverlay("opinion", () => slugifyPlanName(question)),
+				(signal) => summarizePlanPromptName(ctx, question, { signal }),
+			);
 			try {
 				saveRepoOpinionFile(question, ctx.cwd, slug, "opinion-prompt");
 			} catch {
@@ -114,7 +111,7 @@ export async function runInteractiveOpinion(
 			host.setRunningProgressWidget(widget);
 			let outcome;
 			try {
-				outcome = await runOpinionFanout({ host, ctx, question, models, thinking, session, widget, agents });
+				outcome = await runOpinionFanout({ host, ctx, question, models, thinking, session, widget, agents, maxConcurrency: settings.maxConcurrentAgents });
 			} finally {
 				host.setRunningProgressWidget(undefined);
 				widget.stopWidget();
@@ -139,6 +136,10 @@ export async function runInteractiveOpinion(
 			} catch {
 				saved = false;
 			}
+			// `sendUserMessage` routes to prompt() and ignores triggerTurn (only
+			// sendCustomMessage honors it), so this report does start a model turn.
+			// Genuinely append-only delivery needs pi.sendMessage({ customType, … },
+			// { triggerTurn: false }) plus a message renderer — a UX change, not made here.
 			const appendOnly: SendUserMessageOptions = { triggerTurn: false };
 			await pi.sendUserMessage(markdown, appendOnly);
 			const completed = outcomes.filter((item) => item.status === "done").length;

package/src/planning/contextEdits.ts

@@ -0,0 +1,62 @@
+import type { ContextEditEntryDraft } from "@earendil-works/pi-coding-agent";
+
+import { PLAN_MODE_CONTEXT_TYPE, VERIFICATION_PENDING_CONTEXT_TYPE } from "./tools/shared.ts";
+
+/** Structural entry shape containing only fields read while scanning a branch. */
+export interface ScannedEntry {
+	id?: string;
+	type: string;
+	customType?: string;
+	message?: { role?: string; content?: unknown };
+	targetId?: string;
+	replacement?: unknown;
+}
+
+export function isPlanModeInstructionText(content: unknown): boolean {
+	const isInstruction = (text: string): boolean =>
+		text.startsWith("[PLAN MODE ACTIVE]") || text.startsWith("[PLAN MODE RE-ENTRY]");
+	if (typeof content === "string") return isInstruction(content);
+	if (!Array.isArray(content)) return false;
+	return content.some((part) =>
+		part !== null
+		&& typeof part === "object"
+		&& "type" in part
+		&& part.type === "text"
+		&& "text" in part
+		&& typeof part.text === "string"
+		&& isInstruction(part.text));
+}
+
+export function isPlanInstructionEntry(entry: ScannedEntry): boolean {
+	if (entry.type === "custom_message") return entry.customType === PLAN_MODE_CONTEXT_TYPE;
+	if (entry.type !== "message" || entry.message?.role !== "user") return false;
+	// The one-shot mf-plan-exit reminder remains governed by the per-request
+	// context filter; only reusable plan-mode instructions are omitted durably.
+	return isPlanModeInstructionText(entry.message.content);
+}
+
+export function isVerificationPendingEntry(entry: ScannedEntry): boolean {
+	return entry.type === "custom_message" && entry.customType === VERIFICATION_PENDING_CONTEXT_TYPE;
+}
+
+export function collectOmissionDrafts(
+	entries: readonly ScannedEntry[],
+	predicate: (entry: ScannedEntry) => boolean,
+	alreadyOmitted: ReadonlySet<string>,
+): ContextEditEntryDraft[] {
+	const omitted = new Set(alreadyOmitted);
+	for (const entry of entries) {
+		if (entry.type === "context_edit" && entry.replacement === null && typeof entry.targetId === "string") {
+			omitted.add(entry.targetId);
+		}
+	}
+	return entries.flatMap((entry): ContextEditEntryDraft[] => {
+		if (typeof entry.id !== "string" || omitted.has(entry.id) || !predicate(entry)) return [];
+		return [{ type: "context_edit", targetId: entry.id, replacement: null }];
+	});
+}
+
+export function buildVerificationPendingMessage(planFilePath: string | undefined): string {
+	const target = planFilePath ? ` for ${planFilePath}` : "";
+	return `The implementation turn for the approved plan${target} has finished. Independent read-only verification is pending and runs out of band. Treat the implementation as unverified until the verifier reports.`;
+}

package/src/planning/modeState.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import type { MfPlanInfo } from "../moa/planInfo.ts";
 import type { ImplementationHandoff } from "../moa/implementationRetry.ts";
+import { PLAN_ONLY_REGISTERED_TOOLS } from "./tools/shared.ts";
 
 export interface PlanModeState {
 	enabled: boolean;
@@ -10,10 +11,26 @@ export interface PlanModeState {
 	needsExitReminder?: boolean;
 	moaInfo?: MfPlanInfo;
 	implementationHandoff?: ImplementationHandoff;
+	/** Active loadout captured when plan mode was entered, so exit restores it. */
+	toolsBeforePlanMode?: string[];
 }
 
 export const MAX_PERSISTED_STATE_BYTES = 512 * 1024;
 
+/**
+ * A snapshot containing plan-only tools was taken while plan mode was already
+ * live (pre-fix sessions, or a transcript-restored loadout). Restoring it would
+ * re-apply the read-only set after approval, so reject it and let the caller
+ * fall back to the registered loadout.
+ */
+export function validateToolLoadoutSnapshot(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const names = value.filter((name): name is string => typeof name === "string" && name.length > 0);
+	if (names.length === 0) return undefined;
+	if (names.some((name) => PLAN_ONLY_REGISTERED_TOOLS.includes(name))) return undefined;
+	return [...new Set(names)];
+}
+
 export function serializePlanModeState(state: PlanModeState): { state: PlanModeState; serialized: string } {
 	let persisted = state.moaInfo?.proposerPlans
 		? { ...state, moaInfo: { ...state.moaInfo, proposerPlans: undefined } }

package/src/planning/planFile.ts

@@ -131,20 +131,38 @@ export function slugifyPlanName(text: string): string {
 	return trySlugifyPlanName(text) ?? generateWordSlug();
 }
 
-/** Fallback slug when LLM summarization is unavailable. */
-export function fallbackPlanName(): string {
-	return generateWordSlug();
+export type RepoPlanFileKind = "plan-prompt" | "plan" | "spec" | "verification" | "criteria" | "verification-handoff";
+
+function repoPlanSuffix(kind: RepoPlanFileKind): string {
+	return `__${kind}`;
 }
 
-export type RepoPlanFileKind = "plan-prompt" | "plan" | "verification" | "criteria";
+export function isApprovedRepoPlanFilename(file: string): boolean {
+	return file.endsWith("__plan.md");
+}
 
-function repoPlanSuffix(kind: RepoPlanFileKind): string {
-	// `__verification` and `__criteria` never collide with the `/mf-plan-implement`
-	// scan, which matches `__plan.md` while excluding `__plan-prompt.md`.
-	if (kind === "plan-prompt") return "__plan-prompt";
-	if (kind === "verification") return "__verification";
-	if (kind === "criteria") return "__criteria";
-	return "__plan";
+export function repoPlanDisplayPath(baseSlug: string, kind: RepoPlanFileKind): string {
+	if (!isValidPlanSlug(baseSlug)) throw new Error("Invalid repository plan slug");
+	return `${CONFIG_DIR_NAME}/mf-plan/${baseSlug}${repoPlanSuffix(kind)}.md`;
+}
+
+export function nextFreeRepoPlanSlug(repoCwd: string, baseSlug: string, kind: RepoPlanFileKind): string {
+	if (!isValidPlanSlug(baseSlug)) throw new Error("Invalid repository plan slug");
+	const planDir = getRepoPlanDirectory(repoCwd);
+	if (!fs.existsSync(path.join(planDir, `${baseSlug}${repoPlanSuffix(kind)}.md`))) return baseSlug;
+
+	for (let suffix = 2; suffix <= 20; suffix++) {
+		const suffixText = `-${suffix}`;
+		const trimmedBase = baseSlug
+			.slice(0, MAX_PLAN_SLUG_LENGTH - suffixText.length)
+			.replace(/-+$/g, "");
+		const candidate = `${trimmedBase}${suffixText}`;
+		if (
+			isValidPlanSlug(candidate)
+			&& !fs.existsSync(path.join(planDir, `${candidate}${repoPlanSuffix(kind)}.md`))
+		) return candidate;
+	}
+	return generateWordSlug();
 }
 
 /** Ensure `<CONFIG_DIR_NAME>/mf-plan/` exists in the given repo directory. */
@@ -158,7 +176,7 @@ export function getRepoPlanDirectory(repoCwd: string): string {
 	return planDir;
 }
 
-/** Save content to `<CONFIG_DIR_NAME>/mf-plan/<slug>__plan-prompt.md` or `<slug>__plan.md`. Returns the file path. */
+/** Save content to `<CONFIG_DIR_NAME>/mf-plan/<slug>__<kind>.md` for the given kind. Returns the file path. */
 export function saveRepoPlanFile(
 	content: string,
 	repoCwd: string,