@underactive/pi-topping-moa-fusion 0.2.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [0.4.1]
+
+### Added
+
+- `write_plan`, `enter_plan_mode`, `exit_plan_mode`, and `mf_plan_subagent` now declare a pi 0.99 `outputSchema` and return matching `structuredContent` for RPC/JSON consumers, `tool_result` handlers, and codemode scripts: per-agent status, exit code, stop reason, usage, and capped output for subagent runs, and the approval outcome and kickoff route for plan exit. Model-facing text is unchanged.
+- The same four tools now declare MCP-style `annotations`, so permission extensions see accurate destructive and idempotent hints. None claims to be read-only.
+
+### Changed
+
+- Updated all four pi development dependencies from 0.87.0 to 0.99.2.
+- Plan-only tools stay out of normal mode by being removed from the active tool set, not through pi 0.99's `prepareLoadout`, which leaves hidden tools active and callable.
+
+### Fixed
+
+- Plan-only tools are now also removed on the first turn after leaving plan mode. Previously the exit-reminder turn skipped the leak repair, so a leaked `write_plan`, `exit_plan_mode`, or `mf_plan_subagent` stayed declared for that turn.
+
+## [0.3.0]
+
+### Added
+
+- Added `/mf-spec`, an in-process requirements-clarification flow that asks up to five focused questions, reviews and saves approved `__spec.md` planning briefs, and prepares a `/mf-plan` handoff without exposing specs to `/mf-plan-implement`.
+- A hidden `mf-plan-verification-pending` session marker now records when an approved implementation is expected to enter independent verification. Resuming before a verifier result is recorded warns that the implementation is still unverified.
+
+### Changed
+
+- Updated all four pi development dependencies from 0.86.0 to 0.87.0.
+- The pi 0.87 settle-boundary context-edit and verification-marker integrations are capability-gated and remain inert on older hosts, which retain the existing request-time filtering and verification dispatch behavior.
+
+### Fixed
+
+- An assigned slot in the MoA Fusion Pre-flight overview can now be cleared back to `(none)` with Backspace or Delete. Previously a slot could only be reassigned to another model, never emptied.
+- Reusable `[PLAN MODE ACTIVE]` and `[PLAN MODE RE-ENTRY]` instruction entries are now durably omitted with settle-boundary null context edits after plan-mode exit, preventing later compaction from carrying stale plan instructions into implementation.
+- Custom OpenAI-compatible endpoints used by proposers and verifiers now benefit from pi 0.87's upstream strict-schema capability fix: unknown endpoints no longer receive strict tool schemas unless they explicitly advertise support.
+- Saving or deleting an agent roster now takes effect immediately, without requiring a second save from the main settings overlay.
+- A failed agent's error is now readable in full without widening the terminal. Provider failures were cut to 80 characters before reaching the progress table and then truncated again at the ACTIVITY column edge, hiding the part naming the cause. The message is now kept whole and word-wrapped beneath its row — breaking the JSON payload mid-token when it has no spaces to break on — while a short error stays inline as before.
+
 ## [0.2.0]
 
 ### Added

package/README.md

@@ -16,6 +16,7 @@ A Pi extension built around **Mixture of Agents (MoA)** planning: several models
   - [The MoA Fusion table](#the-moa-fusion-table)
   - [Opinions (`/mf-opinion`)](#opinions-mf-opinion)
   - [Debates (`/mf-debate`)](#debates-mf-debate)
+  - [Specs (`/mf-spec`)](#specs-mf-spec)
 - [Commands](#commands)
   - [Cancelling running subagents](#cancelling-running-subagents)
 - [Plan Mode](#plan-mode)
@@ -74,7 +75,7 @@ Fanning out a coding task and merging the resulting token streams does not work
 ### How a run works
 
 1. After you submit your plan prompt, a picker opens on a mode screen (**Mixture of Agents** or **Single model**). Single model — or Esc — runs the 5-phase workflow on the current model.
-2. MoA opens the **MoA Fusion Pre-flight** overview with all eight slots — five proposer slots plus a synthesizer, an implementer, and a verifier — starting empty at `(none)`, plus a **Load Roster** row above **Start fan-out** that applies a saved agent roster to every slot at once (see [Agent rosters](#agent-rosters)). Selecting any slot row opens a two-pane model/thinking picker for that one slot and returns to the overview; cancelling leaves the slot unchanged. **Start fan-out** stays disabled until you assign at least two proposer slots and all three required roles (the minimum roster; the same model may fill several slots, and the extra proposer slots are optional). Thinking levels come from the model's pi registry metadata, which is authoritative for every model the registry lists; the generic `off`/`low`/`medium`/`high` list applies only to models it doesn't. Your saved choices and active model only pre-highlight a slot's picker — they never count as assignments until you confirm them — and confirmed selections are remembered in `~/.pi/agent/mf-plan/settings.json`.
+2. MoA opens the **MoA Fusion Pre-flight** overview with all eight slots — five proposer slots plus a synthesizer, an implementer, and a verifier — starting empty at `(none)`, plus a **Load Roster** row above **Start fan-out** that applies a saved agent roster to every slot at once (see [Agent rosters](#agent-rosters)). Selecting any slot row opens a two-pane model/thinking picker for that one slot and returns to the overview; cancelling leaves the slot unchanged, and Backspace (or Delete) on a slot row clears it back to `(none)`. **Start fan-out** stays disabled until you assign at least two proposer slots and all three required roles (the minimum roster; the same model may fill several slots, and the extra proposer slots are optional). Thinking levels come from the model's pi registry metadata, which is authoritative for every model the registry lists; the generic `off`/`low`/`medium`/`high` list applies only to models it doesn't. Your saved choices and active model only pre-highlight a slot's picker — they never count as assignments until you confirm them — and confirmed selections are remembered in `~/.pi/agent/mf-plan/settings.json`.
 3. Proposers run in parallel as isolated `moa-proposer` subprocesses. Each ends with an "Open Questions / Assumptions" section rather than pausing — proposers never block waiting on input.
 4. `moa-synthesizer` reads every successful proposal (at least 1 must succeed) plus the original request, and writes one merged plan.
 5. If the proposers substantively disagreed, a conflict-review overlay opens first: one tab per conflict, plain-language options, the synthesized pick tagged **(Recommended)**, and a **Chat about this** box for free-text feedback. Your resolutions are fed back for re-synthesis. Esc cancels the whole run.
@@ -152,6 +153,19 @@ During the run, `F3` opens the live observer and `Esc` or `F4` opens cancellatio
 
 During the run, `F3` opens the live observer and `Esc` or `F4` opens cancellation controls. The prompt and combined transcript are saved under `.pi/mf-debate/` as `<slug>__debate-prompt.md` and `<slug>__debate.md`.
 
+### Specs (`/mf-spec`)
+
+`/mf-spec` follows a separate requirements workflow: rough request → clarification → approved planning brief → a user-started `/mf-plan`.
+
+1. Enter a request directly (`/mf-spec add dark mode`) or use the prompt editor.
+2. It asks up to five adaptive clarifying questions, stopping early when it has enough context. Each question names the area it affects: scope, UX, architecture, acceptance criteria, or testing.
+3. Press **Esc** during clarification to choose whether to draft from the answers so far or cancel; cancelling saves nothing.
+4. Review the draft and approve and save it, edit it directly, or revise it with feedback. Nothing is written before approval.
+5. The approved brief is saved as `.pi/mf-plan/<slug>__spec.md`. `/mf-plan-implement` ignores these files because they are specifications, not approved `__plan.md` implementation plans.
+6. After saving, a ready-to-run `/mf-plan …` handoff is placed in the input box when it is empty; review it and press Enter to start planning. Existing input is never overwritten, and `/mf-spec` refuses to run while plan mode is active.
+
+Clarification and drafting run in-process on the active session model with no tools or repository access. Repo-grounded planning begins only when you run the prepared `/mf-plan` command.
+
 ## Commands
 
 | Command | Shortcut | Description |
@@ -159,6 +173,7 @@ During the run, `F3` opens the live observer and `Esc` or `F4` opens cancellatio
 | `/mf-plan` | — | Toggle plan mode on/off |
 | `/mf-opinion` | — | Ask 1–5 models for independent read-only opinions about the repository |
 | `/mf-debate` | — | Run a read-only multi-round debate between up to 5 models |
+| `/mf-spec` | — | Clarify a rough request into an approved planning brief and prepare a `/mf-plan` handoff |
 | `/mf-preview` | — | Toggle the inline/live preview of streamed agent output |
 | `/mf-plan-settings` | — | Configure the explore and cheap/fast agents, named agent rosters for the MoA roles, plan options, and max concurrent agents |
 | `/mf-plan-implement` | — | Retry implementation of the last approved MoA plan, optionally with a different model |
@@ -215,6 +230,8 @@ Outside plan mode, one additional tool is exposed:
 |------|-------------|
 | `enter_plan_mode` | Lets the agent enter plan mode itself when asked for a design or plan. Takes the single-model path on the current session model — no pickers, no MoA. Exit and approval work exactly as if the user had invoked `/mf-plan`. |
 
+All four tools declare pi 0.99 `annotations`, and none claims to be read-only: `write_plan` is `destructiveHint: true, idempotentHint: true`, `exit_plan_mode` is `destructiveHint: true, idempotentHint: false`, `mf_plan_subagent` is `idempotentHint: false`, and `enter_plan_mode` sets only `readOnlyHint: false`. Under the example permission policy in pi's extension docs they are confirmed exactly as before. Each also declares an `outputSchema` and returns matching `structuredContent` for programmatic consumers (RPC/JSON `tool_execution_end` events, `tool_result` handlers, and codemode scripts); for `mf_plan_subagent` that is each agent's status, exit code, stop reason, usage, and output capped at 50 KB. The model-facing text is unchanged, and pi does not save structured values in the session.
+
 ## Subagents
 
 Seven agent definitions are auto-installed to `~/.pi/agent/agents/` on first run (won't overwrite existing files). Two belong to the single-model workflow, three to MoA planning, one to the independent opinion flow, and one to the debate flow:
@@ -272,7 +289,7 @@ Rosters persist in `~/.pi/agent/mf-plan/settings.json`:
 }
 ```
 
-Names are 1–24 alphanumeric characters, unique case-insensitively, up to 20 rosters. The roster manager stages every edit in memory — nothing is written until the settings overlay's **Save and Close**.
+Names are 1–24 alphanumeric characters, unique case-insensitively, up to 20 rosters. Slot edits remain drafts until **Save roster** is selected; that action persists the completed roster immediately, without requiring **Save and Close** in the parent settings overlay.
 
 #### Max concurrent agents
 
@@ -328,7 +345,7 @@ The slug is a generated adjective-adjective-noun triple (e.g. `happy-mellifluous
 
 ## Non-Interactive Behavior
 
-In non-interactive modes (`pi -p`, `--mode json`), `exit_plan_mode` is rejected unless `MOA_PLAN_AUTO_APPROVE=1` is set. With that explicit opt-in, it exits plan mode and hands the plan back without prompting. The plan file is still written to disk.
+In non-interactive modes (`pi -p`, `--mode json`), `exit_plan_mode` is rejected unless `MOA_PLAN_AUTO_APPROVE=1` is set. With that explicit opt-in, it exits plan mode and hands the plan back without prompting. The plan file is still written to disk. `/mf-spec <request>` likewise requires `MOA_PLAN_AUTO_APPROVE=1`; with it, the command skips questions and review, generates and saves the brief, and prints the `/mf-plan` handoff, while without it no model call or file write occurs.
 
 ## How It Works (Architecture)
 
@@ -370,6 +387,9 @@ src/
 │   ├── debateRounds.ts      # Survivor/early-stop/next-round bookkeeping
 │   ├── debateResults.ts     # Outcome collection and debate transcript markdown
 │   └── debateFile.ts        # Repo-local debate artifacts
+├── spec/
+│   ├── specContract.ts      # Clarification/brief contracts, parsing, and handoff helpers
+│   └── runSpec.ts           # Interactive/headless /mf-spec state machine
 ├── planning/
 │   ├── planMode.ts          # Plan-mode state transitions and lifecycle handlers
 │   ├── modeState.ts         # Persisted state shape, byte cap, append deduplication
@@ -437,7 +457,7 @@ agents/                      # Shipped agent definitions
 - **Custom `write_plan` tool** instead of path-guarded `edit`/`write` — guarantees the single-writable-file invariant.
 - **Subprocess subagents** (not in-process) — each agent runs in an isolated `pi --mode json -p --no-session` subprocess with an enforced read-only tool allowlist.
 - **State via `appendEntry`** — plan mode state (enabled, slug, tools snapshot) persists in the session for `/resume` and `/reload`.
-- **Context injection via `before_agent_start`** — the 5-phase instructions are injected as a user message every turn while plan mode is active; the `context` hook strips stale plan-mode messages once it is off.
+- **Context injection and lifecycle cleanup via `before_agent_start` + `context`** — the 5-phase instructions are injected as a user message every turn while plan mode is active, and the `context` hook strips stale plan-mode messages once it is off. On pi 0.87+, the settle boundary also persists null context edits for reusable plan-instruction entries once plan mode is off, so later compaction cannot carry those instructions forward. When an approved implementation is expected to enter verification, the same boundary persists a hidden `mf-plan-verification-pending` marker so a resumed session can warn that verification is still outstanding.
 - **MoA proposers never pause mid-run** — subprocess subagents are one-shot, so a proposer that hits an ambiguity records it as an assumption and keeps going. Only the synthesizer, which sees every proposal, asks the user anything — keeping fan-out fully parallel.
 
 ## Porting Notes
@@ -453,6 +473,7 @@ Ported from Claude Code's plan mode, adapted to pi's extension primitives:
 | `FileEditTool`/`FileWriteTool` guarded | Custom `write_plan` tool | Safer single-writable-file invariant |
 | Subscription-tier agent counts | Hardcoded constants (3/1) | Bumpable via code change |
 | Plan-length A/B experiment | Standard Phase 4 | Experiment noise skipped |
+| Spec Kit / brainstorming | `/mf-spec` | Requirements clarification only |
 | Interview phase variant | Standard 5-phase workflow | Variant skipped |
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@underactive/pi-topping-moa-fusion",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Pi extension implementing /mf-plan — Claude Code-style 5-phase plan mode with a Mixture-of-Agents proposer/synthesizer pipeline.",
   "keywords": [
     "pi-package",
@@ -50,10 +50,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.86.0",
-    "@earendil-works/pi-ai": "0.86.0",
-    "@earendil-works/pi-coding-agent": "0.86.0",
-    "@earendil-works/pi-tui": "0.86.0",
+    "@earendil-works/pi-agent-core": "0.99.2",
+    "@earendil-works/pi-ai": "0.99.2",
+    "@earendil-works/pi-coding-agent": "0.99.2",
+    "@earendil-works/pi-tui": "0.99.2",
     "@types/node": "^24.0.0",
     "typebox": "^1.3.3",
     "typescript": "^5.8.0"

package/src/debate/debateFanout.ts

@@ -4,7 +4,7 @@ import type { AgentConfig } from "../agents/discovery.ts";
 import { modelExtensionOptions, resolveContextWindow, resolveModelCost } from "../moa/modelRuntime.ts";
 import type { CancelSession } from "../runtime/cancelRun.ts";
 import { CancelRun } from "../runtime/cancelRun.ts";
-import { getFinalOutput, getResultOutput, isFailedResult, type SingleResult } from "../runtime/results.ts";
+import { getFinalOutput, getResultOutput, isFailedResult, statusDetail, type SingleResult } from "../runtime/results.ts";
 import { runParallelAgentsWithModels, type ModelParallelAgentTask } from "../runtime/runner.ts";
 import { modelRefLabel, type ModelRef, type ThinkingLevel } from "../shared/modelRefs.ts";
 import { activityLoopCount } from "../ui/agentStatus.ts";
@@ -117,7 +117,7 @@ export async function runDebateRounds(options: DebateFanoutOptions): Promise<Deb
 							if (observed) observed.state = "cancelled";
 						} else if (isFailedResult(result)) {
 							currentRun.settle(batchIndex, "error");
-							widget.update(debateIndex, "error", getResultOutput(result).slice(0, 80));
+							widget.update(debateIndex, "error", statusDetail(getResultOutput(result)));
 							if (observed) observed.state = "error";
 						} else {
 							currentRun.settle(batchIndex, "done");

package/src/index.ts

@@ -12,7 +12,7 @@ import {
 } 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 { getPlanFilePath, getRepoPlanDirectory, isApprovedRepoPlanFilename, 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";
@@ -20,6 +20,7 @@ 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 { createSpecRunner } from "./spec/runSpec.ts";
 import { createPlanModeController } from "./planning/planMode.ts";
 import { registerEnterPlanModeTool, runInteractivePlanMode } from "./planning/tools/enterPlanMode.ts";
 import { registerExitPlanModeTool } from "./planning/tools/exitPlanMode.ts";
@@ -38,6 +39,7 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 		setRunningProgressWidget: controller.moaRunHost.setRunningProgressWidget,
 	};
 	const debateHost = opinionHost;
+	const runSpec = createSpecRunner(controller);
 	const togglePlanMode = async (ctx: Parameters<typeof controller.exitPlanMode>[0], prompt?: string): Promise<void> => {
 		if (controller.questionnaireBusy(ctx)) return;
 		if (controller.getActiveCancelSession()?.run) {
@@ -69,6 +71,10 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 		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-spec", {
+		description: "Clarify a rough request into an approved planning brief for /mf-plan — append the request (e.g. /mf-spec add dark mode) to skip the editor",
+		handler: async (args, ctx) => runSpec(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); },
@@ -104,7 +110,7 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 					if (fs.existsSync(repoDir)) {
 						const entries = fs.readdirSync(repoDir);
 						planFiles = entries
-							.filter((file) => file.endsWith("__plan.md") && !file.endsWith("__plan-prompt.md"))
+							.filter(isApprovedRepoPlanFilename)
 							.map((file) => {
 								const slug = file.slice(0, -"__plan.md".length);
 								const fullPath = path.join(repoDir, file);
@@ -270,6 +276,10 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 	registerMfPlanSubagentTool(pi, controller);
 	registerExitPlanModeTool(pi, controller);
 
+	// Deliberately not context_with_system (pi 0.87.0): its result is sent
+	// verbatim, so a filtering mistake could drop pi's prompt and tool declarations.
+	// Keep injection in before_agent_start, filtering in context, and durable
+	// omissions in agent_before_settle so pi continues to own prompt/tool state.
 	pi.on("context", controller.onContext);
 	pi.on("before_agent_start", controller.onBeforeAgentStart);
 	pi.on("agent_start", controller.onAgentStart);
@@ -277,6 +287,7 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 	pi.on("message_update", controller.onMessageUpdate);
 	pi.on("tool_execution_start", controller.onToolExecutionStart);
 	pi.on("message_end", controller.onMessageEnd);
+	pi.on("agent_before_settle", controller.onAgentBeforeSettle);
 	pi.on("agent_settled", controller.onAgentSettled);
 	pi.on("session_start", controller.onSessionStart);
 	pi.on("session_shutdown", controller.onSessionShutdown);

package/src/moa/fanoutWiring.ts

@@ -2,7 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { AgentConfig } from "../agents/discovery.ts";
 import type { CancelRun, CancelSession } from "../runtime/cancelRun.ts";
-import { getResultOutput, isFailedResult, type SingleResult } from "../runtime/results.ts";
+import { getResultOutput, isFailedResult, statusDetail, type SingleResult } from "../runtime/results.ts";
 import { runParallelAgentsWithModels, type ModelParallelAgentTask } from "../runtime/runner.ts";
 import type { ModelRef } from "../shared/modelRefs.ts";
 import type { MoaProgressWidget } from "../ui/moaProgressWidget.ts";
@@ -55,7 +55,7 @@ export async function runWidgetFanout(options: WidgetFanoutOptions): Promise<Sin
 					if (observed) observed.state = "cancelled";
 				} else if (isFailedResult(result)) {
 					run.settle(index, "error");
-					widget.update(widgetIndex, "error", getResultOutput(result).slice(0, 80));
+					widget.update(widgetIndex, "error", statusDetail(getResultOutput(result)));
 					if (observed) observed.state = "error";
 				} else {
 					run.settle(index, "done");

package/src/moa/verification.ts

@@ -24,13 +24,13 @@
  * 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";
@@ -762,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.
 			}
@@ -861,14 +861,14 @@ export async function runImplementationVerification(
 					// 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")
-						? `${CONFIG_DIR_NAME}/mf-plan/${repoPlanSlug}__criteria.md`
+						? repoPlanDisplayPath(repoPlanSlug, "criteria")
 						: undefined,
 				}),
 				ctx.cwd,
 				repoPlanSlug,
 				"verification-handoff",
 			);
-			handoffPath = `${CONFIG_DIR_NAME}/mf-plan/${repoPlanSlug}__verification-handoff.md`;
+			handoffPath = repoPlanDisplayPath(repoPlanSlug, "verification-handoff");
 		} catch {
 			// Persisting the handoff is best-effort; the exhaustion notification still fires.
 		}

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/planFile.ts

@@ -131,21 +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" | "verification-handoff";
+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";
-	if (kind === "verification-handoff") return "__verification-handoff";
-	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. */
@@ -159,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,