pi-plans 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,7 @@
-<h1 align="center">pi-plans</h1>
+<h1 align="center">π-plans</h1>
 
 <p align="center">
-  <img src="docs/assets/pi-plans-logo.svg?v=3" alt="pi-plans: Plan. Review. Execute." width="640" />
+  <img src="docs/assets/pi-plans-logo.svg?v=4" alt="pi-plans: Plan. Review. Execute." width="640" />
 </p>
 
 <h2 align="center"><b>Plan. Review. Execute.</b></h2>
@@ -13,9 +13,11 @@
 <p align="center">
   <a href="https://github.com/MaxInGaussian/pi-plans/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/MaxInGaussian/pi-plans?style=square" /></a>
   <a href="https://hits.sh/github.com/MaxInGaussian/pi-plans/"><img alt="Repo views" src="https://hits.sh/github.com/MaxInGaussian/pi-plans.svg?label=repo%20views" /></a>
-  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=square" /></a>
-  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-TS-3178C6?style=square&logo=typescript&logoColor=white" />
-  <img alt="pi-package" src="https://img.shields.io/badge/pi--package-ready-7c3aed?style=square" />
+  <a href="https://www.npmjs.com/package/pi-plans"><img alt="npm downloads" src="https://img.shields.io/npm/dt/pi-plans?color=38bdf8" /></a>
+  <a href="https://www.npmjs.com/package/pi-plans"><img alt="npm version" src="https://img.shields.io/npm/v/pi-plans?color=60a5fa" /></a>
+  <a href="https://github.com/earendil-works/pi"><img alt="Pi package" src="https://img.shields.io/badge/Pi-package-fbbf24" /></a>
+  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/pi-plans?color=22c55e" /></a>
+  <a href="https://github.com/MaxInGaussian/pi-plans/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/MaxInGaussian/pi-plans/actions/workflows/ci.yml/badge.svg" /></a>
 </p>
 
 ---
@@ -58,8 +60,9 @@ A rough change request becomes a versioned Markdown plan instead of a surprise d
    =============================================== write guard OFF
                  |
         tracked execution loop
+   fused AGENTS.md × Ponytail executor rules
    checklist injected each turn, [DONE:VC-xxx]
-   markers tracked with a footer widget
+   markers tracked via bottom status bar + detail panel
                  |
                  v
            run status: done
@@ -93,17 +96,13 @@ Pi:  Wrote ./docs/pi-plans/2026-08-26-split-execution-loop/PLAN_v1.md
      - [ ] `VC-001` covers `I-001`; pass condition: `npm test` passes;
        evidence: test output; metric: zero failing tests.
 
-Pi:  Next step for refining the plan?
-     1. Reviewer round (recommended)
-     2. Criticizer round
-     3. Accept plan for tracked execution
+Pi:  Accept the plan and execute it now?
+     1. ✓ Accept plan and execute now (recommended)
+     2. Accept plan, don't execute yet
+     3. Run another round: Reviewer
      ...
 
-You: Accept plan for tracked execution.
-
-Pi:  Execute this plan now?
-     1. Execute this plan now (recommended)
-     2. Stop after planning
+You: 1 — accept and execute.
 ```
 
 Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (public, committed). Prefer `.git/pi_plans/plans` if you want them private to the repository.
@@ -116,22 +115,44 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | Choice prompts | `ask_choice`: recommended option first, answers auto-recorded per run |
 | Refinement rounds | Read-only reviewer/criticizer Pi subagents consolidate findings into the next plan version |
 | Workspace state | Config, runs, decisions, refs, and subagent ledgers in `.git/pi_plans/` (git common dir) |
-| Tracked execution | Checklist injected each turn; `[DONE:VC-xxx]` markers drive progress |
+| Tracked execution | Checklist injected each turn; `[DONE:VC-xxx]` markers drive completion; implementation items report progress with `[I-xxx:implemented]` / `[I-xxx:validating]` markers; `plans-list` groups work by I-item with `[Pending/Implementing/Implemented/Validating/VC passed]` states (passed items struck through); the collapsed footer and expanded panel share the same progress projection, so `x/y` updates in real time in both views |
+| Execution model | With `plans set-execution-model <provider/model[:thinking]>`, the main session switches to it at handoff and restores the planning model + thinking level on stop/complete/abandon; when unset, the first execution handoff prompts for one and recommends inheriting the current session model |
+| Execution-phase compaction | Pi core owns threshold, overflow, and manual compaction scheduling; pi-plans only supplies a plan-aware `session_before_compact` summary and queues one hidden continuation when Pi reports `willRetry: false`, while preserving the raw execution tail and `previousSummary` chaining |
+| Planning-phase auto compaction | In active planning runs (run.status=planning, no execution), context usage >=100% triggers a plan-aware compaction too: pre-plan history compresses, Q&A during planning stays in a dedicated section, the latest `PLAN_vN.md` and later conversation stay raw; cooldown + resume guard prevent ping-pong, and manual `/compact` follows the same rules |
+| Efficient executor prompt | Each turn, the executor is steered by a fused rule set — Marcos Hernanz's AGENTS.md principles × Ponytail minimalism: layered growth, simplest implementation, long-term architecture (no stopgaps), library discipline — so plans finish in fewer tokens and fewer detours |
 | Write guard | `edit`/`write` blocked outside planning artifacts while a run is active |
 
 ## Interface overview
 
 | Tool / Command | Purpose |
 |---|---|
-| `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-root`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent` |
-| `ask_choice` | Numbered choice prompt; `autoComplete: false` for execution handoff / external-state questions |
+| `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-root`, `set-execution-model`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent` |
+| `ask_choice` | Numbered choice prompt; `autoComplete: false` for the merged accept/execute question and external-state questions |
 | `refine` | Reviewer/criticizer round via read-only subagents (`--tools read,grep,find,ls`); `reviewers: 3` for big plans; enforces role/model confirmation gates |
-| `execute_plan` | Execution handoff: re-confirms with the user, enters extension-managed execution mode |
-| `/plans` | Show config, active run, execution progress |
-| `/plans-execute [plan.md]` | Manual execution handoff (defaults to highest `PLAN_vN.md`) |
+| `execute_plan` | Execution handoff: re-confirms with the user, prompts for an execution model if needed, and enters extension-managed execution mode |
+| `/plans` | Show config, active run, and execution progress |
+| `/plans-list` | Toggle the execution checklist panel |
+| `/plans-execute [plan.md]` | Manual execution handoff (defaults to highest `PLAN_vN.md`; prompts for an execution model if unset) |
 | `/update-plan [plan.md] [reason…]` | Interrupt-and-refine: stops execution (if any), returns the run to planning, and directs the agent to revise the plan into `PLAN_vN+1.md` while preserving verified work |
 | `/plans-stop` | Stop execution mode |
 | `/plans-abandon` | Abandon the active run (lifts the write guard; artifacts stay) |
+| Status bar (lifecycle) | 💬 Q&A → 📝 draft written (planning sub-phases) → ⌛ executing `x/y · spent · in/out-toks` in the collapsed footer or expanded panel → ⛔ stopped / 🎯 done / 🚫 abandoned |
+
+## The execution rules
+
+Once you approve the handoff, every turn injects a compact rule set that fuses Marcos Hernanz's AGENTS.md seven principles with Ponytail minimalism — so the executor finishes plans in fewer tokens and fewer detours:
+
+<details>
+<summary>The four fused rules (click to expand)</summary>
+
+1. **Grow in layers** — smallest end-to-end slice first, then stack each new capability on top of what already works.
+2. **Simplest implementation** — no speculative abstractions, configuration, or indirection; modular components with clearly separated concerns.
+3. **Long-term architecture, no stopgaps** — no backward-compatibility layers, fallbacks, or migrations; remove the obsolete paths a change obsoletes.
+4. **Library discipline** — prefer established, well-maintained libraries; check the project's existing dependencies (docs and types) before writing your own or adding a package.
+
+</details>
+
+The rules cost four lines per turn and buy back far more: fewer wrong turns, shorter implementation paths, plans that finish in fewer tokens.
 
 ## Skills
 
@@ -198,7 +219,7 @@ Both run on Node ≥ 22.6 via `--experimental-strip-types`; no npm dependencies.
 
 **Why do I have to approve before any code changes?**
 
-The plan is the contract. Refinement converges on scope while nothing is writable yet; the execution handoff is a separate explicit approval that also lifts the write guard. You always see — and can veto — what will happen before it happens.
+The plan is the contract. Refinement converges on scope while nothing is writable yet; the merged accept/execute question is an explicit, never-auto-completed approval that also lifts the write guard. You always see — and can veto — what will happen before it happens.
 
 **What can Auto-complete decide on my behalf?**
 
@@ -212,6 +233,10 @@ Preferences and run ledgers in `.git/pi_plans/` inside your workspace's git dire
 
 Prompts produce one-shot diffs with no recorded reasoning. pi-plans produces versioned artifacts — decisions, references, reviewer findings, dispositions, a verifier checklist — that are auditable, resumable across sessions, and enforced by tooling rather than goodwill.
 
+**Doesn't injecting execution rules every turn cost extra tokens?**
+
+The injected rule set is four compressed lines. It buys back more than it costs: the executor stops re-deriving discipline (no speculative abstractions, no compatibility detours, no reinvented helpers), so finished items converge in fewer turns and fewer tokens overall.
+
 ## License
 
 MIT.

package/docs/assets/pi-plans-logo.svg

@@ -32,8 +32,8 @@
   </g>
 
   <!-- wordmark -->
-  <text x="150" y="96" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="60" font-weight="700" fill="#ffffff">pi-plans</text>
-  <rect x="153" y="110" width="236" height="6" rx="3" fill="url(#bar)"/>
+  <text x="150" y="96" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="60" font-weight="700" fill="#ffffff">π-plans</text>
+  <rect x="153" y="110" width="210" height="6" rx="3" fill="url(#bar)"/>
   <text x="151" y="147" font-family="'SF Mono',Menlo,Consolas,monospace" font-size="16" letter-spacing="4" fill="#ddd6fe">PLAN·REVIEW·EXECUTE</text>
 
   <!-- pipeline: plan -> review -> execute -->

package/index.ts

@@ -19,19 +19,31 @@ import * as path from "node:path";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-	applyDoneMarkers,
-	completeExecution,
 	consumePendingPanelSync,
+	consumePlanningCompactionResumeGuard,
+	drainExecutionFlush,
 	executionContextMessage,
+	filterExecutionResumeMessages,
+	filterPlanningResumeMessages,
 	getExecution,
-	isExecutionComplete,
-	recordExecutionCompletion,
+	handleExecutionBeforeCompact,
+	handleExecutionCompact,
+	handleExecutionCompactFailed,
+	handlePlanningBeforeCompact,
+	handlePlanningCompact,
+	handlePlanningCompactFailed,
+	PLANNING_PLAN_WRITTEN_CUSTOM_TYPE,
+	registerExecutionTurnHandlers,
 	recordTouchedPaths,
+	refreshPlanningCompactionCooldown,
+	requestPlanningCompaction,
 	restoreFromSession,
+	ensureExecutionModelActive,
 	stopExecution,
 	syncExecutionPanel,
 	toggleExecutionPanelView,
 	updateStatusWidget,
+	shouldTriggerPlanningCompaction,
 } from "./src/exec.ts";
 import { planningWriteBlockReason } from "./src/guard.ts";
 import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
@@ -43,6 +55,31 @@ import { registerRefineTool } from "./tools/refine.ts";
 
 const baseDir = dirname(fileURLToPath(import.meta.url));
 
+// When THIS copy of the extension was imported into the running pi process.
+// /plans compares it against the newest source-file mtime so a stale instance
+// (code on disk newer than the loaded copy) is immediately visible.
+const extensionLoadedAt = new Date();
+
+function extensionStalenessLine(): string {
+	try {
+		const dirs = [baseDir, path.join(baseDir, "src"), path.join(baseDir, "tools")];
+		let newest = 0;
+		for (const dir of dirs) {
+			for (const name of fs.readdirSync(dir)) {
+				if (!name.endsWith(".ts")) continue;
+				const mtime = fs.statSync(path.join(dir, name)).mtimeMs;
+				if (mtime > newest) newest = mtime;
+			}
+		}
+		if (newest > extensionLoadedAt.getTime() + 2000) {
+			return `⚠ extension code on disk is newer than the loaded copy (loaded ${extensionLoadedAt.toISOString()}); run /reload to pick it up`;
+		}
+		return `Extension loaded: ${extensionLoadedAt.toISOString()} (up to date)`;
+	} catch {
+		return `Extension loaded: ${extensionLoadedAt.toISOString()}`;
+	}
+}
+
 function extractPathsFromBash(command: string): string[] {
 	const values = new Set<string>();
 	for (const token of command.split(/\s+/)) {
@@ -120,16 +157,67 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		const rawPath = String((event.input as { path?: string }).path ?? "");
 		if (!rawPath) return;
 		const reason = planningWriteBlockReason({ workdir: ctx.cwd, toolName: event.toolName, rawPath });
-		if (!reason) return;
-		return { block: true, reason };
+		if (reason) return { block: true, reason };
+		// Allowed write: if it lands exactly on the run's latest plan file, drop a
+		// marker entry so planning-phase compaction can anchor its cut point there.
+		if (event.toolName === "write") {
+			const active = readActive(ctx.cwd);
+			if (active) {
+				const latest = latestPlanVersion(active.artifact_dir);
+				if (latest && path.resolve(ctx.cwd, rawPath) === path.resolve(ctx.cwd, latest.path)) {
+					pi.appendEntry(PLANNING_PLAN_WRITTEN_CUSTOM_TYPE, {
+						runId: active.run_id,
+						planPath: latest.path,
+					});
+				}
+			}
+		}
+		return;
+	});
+
+	pi.on("context", (event) => {
+		const filteredExecution = filterExecutionResumeMessages(event.messages as Array<{ customType?: string }>);
+		const messages = filterPlanningResumeMessages(filteredExecution);
+		if (messages.length !== event.messages.length) {
+			return { messages };
+		}
+	});
+
+	pi.on("session_before_compact", async (event, ctx) => {
+		const executionResult = await handleExecutionBeforeCompact(pi, ctx, event);
+		if (executionResult) return executionResult;
+		return handlePlanningBeforeCompact(pi, ctx, event);
+	});
+	pi.on("session_compact", async (event, ctx) => {
+		handleExecutionCompact(pi, ctx, event);
+		handlePlanningCompact(pi, ctx, event);
+	});
+	pi.on("session_compact_failed", async (event, ctx) => {
+		handleExecutionCompactFailed(pi, ctx, event);
+		handlePlanningCompactFailed(pi, ctx, event);
+	});
+
+	// Flush points for deferred execution-loop writes: primary drain when the
+	// agent run fully settles, backstop drain at the next run's start (covers
+	// continuation paths that might not emit agent_settled), plus the forced
+	// synchronous flush inside stop/complete.
+	pi.on("agent_settled", async (_event, ctx) => {
+		drainExecutionFlush(pi, ctx);
 	});
 
 	// -----------------------------------------------------------------------
 	// Execution loop: inject remaining checklist each turn, track markers.
 	// -----------------------------------------------------------------------
-	pi.on("before_agent_start", async () => {
+	pi.on("before_agent_start", async (_event, ctx) => {
+		drainExecutionFlush(pi, ctx);
+		await ensureExecutionModelActive(pi, ctx);
 		const content = executionContextMessage();
-		if (!content) return;
+		if (!content) {
+			if (!getExecution() && shouldTriggerPlanningCompaction(ctx)) {
+				requestPlanningCompaction(ctx);
+			}
+			return;
+		}
 		return {
 			message: {
 				customType: "pi-plans-exec-context",
@@ -139,22 +227,17 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		};
 	});
 
-	pi.on("turn_end", async (event, ctx) => {
-		const message = event.message as { role?: string; content?: Array<{ type: string; text?: string }> };
-		if (!message || message.role !== "assistant") {
-			updateStatusWidget(ctx);
-			return;
-		}
-		const text = (message.content ?? [])
-			.filter((part) => part.type === "text")
-			.map((part) => part.text ?? "")
-			.join("\n");
-		const changedIds = applyDoneMarkers(text);
-		if (changedIds.length > 0) {
-			recordExecutionCompletion(pi, ctx, changedIds);
-		}
-		if (getExecution() && isExecutionComplete()) {
-			completeExecution(pi, ctx);
+	registerExecutionTurnHandlers(pi, async (ctx) => {
+		if (!getExecution()) {
+			refreshPlanningCompactionCooldown(ctx);
+			if (consumePlanningCompactionResumeGuard(ctx)) {
+				if (consumePendingPanelSync()) syncExecutionPanel(ctx);
+				updateStatusWidget(ctx);
+				return;
+			}
+			if (shouldTriggerPlanningCompaction(ctx)) {
+				requestPlanningCompaction(ctx);
+			}
 		}
 		// A busy-toggle during the previous turn deferred its re-render; the
 		// turn just ended, so this is the safe point to apply it.
@@ -200,6 +283,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 					lines.push(`  ${item.done ? "☑" : "☐"} ${item.id}`);
 				}
 			}
+			lines.push(extensionStalenessLine());
 			ctx.ui.notify(lines.join("\n"), "info");
 		},
 	});
@@ -277,7 +361,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 					`${doneIds.length}/${execution.items.length} verifier item(s) already verified; their work stays. Remaining items return to planning.`,
 				);
 				if (!ok) return;
-				stopExecution(pi, ctx, "interrupted by /update-plan");
+				await stopExecution(pi, ctx, "interrupted by /update-plan");
 			}
 
 			// Return the run to planning so refinement rules and guards apply again.
@@ -322,7 +406,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 			if (focus) lines.push(`User-reported problems / refocus: ${focus}`);
 			lines.push(
 				"",
-				"Follow the original planning-skill contract for revisions: collect needed clarifications via ask_choice (one question at a time, recorded), apply evidence-based revisions only, then ask the next refinement-mode question, and finish with the execution handoff (ask_choice with autoComplete: false → execute_plan pointing at the new version).",
+				"Follow the original planning-skill contract for revisions: collect needed clarifications via ask_choice (one question at a time, recorded), apply evidence-based revisions only, then ask the next merged accept/execute question (autoComplete: false — ✓ Accept & execute now / Accept, don't execute yet / another round) and call execute_plan pointing at the new version on accept.",
 			);
 
 			await pi.sendUserMessage(lines.join("\n"));
@@ -338,7 +422,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 			}
 			const ok = await ctx.ui.confirm("Stop execution?", "Remaining verifier items will be left unfinished.");
 			if (!ok) return;
-			stopExecution(pi, ctx, "stopped by user via /plans-stop");
+			await stopExecution(pi, ctx, "stopped by user via /plans-stop");
 			ctx.ui.notify("Execution stopped.", "info");
 		},
 	});
@@ -356,6 +440,10 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 				`${active.run_id}\nThe read-only guard lifts; committed artifacts stay in place.`,
 			);
 			if (!ok) return;
+			// Abandon must end execution first so the planning model is restored.
+			if (getExecution()) {
+				await stopExecution(pi, ctx, "run abandoned via /plans-abandon");
+			}
 			try {
 				setRunStatus(ctx.cwd, active.run_id, "abandoned");
 				ctx.ui.notify(`Run ${active.run_id} abandoned.`, "info");
@@ -370,6 +458,6 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// Session lifecycle
 	// -----------------------------------------------------------------------
 	pi.on("session_start", async (_event, ctx) => {
-		restoreFromSession(pi, ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreFromSession>[2]);
+		await restoreFromSession(pi, ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreFromSession>[2]);
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-plans",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Human-in-the-loop planning extension for the Pi coding agent: researched, refined Markdown plans before any code changes.",
   "license": "MIT",
   "type": "module",

package/references/pi-planning-workflow.md

@@ -59,7 +59,7 @@ Every user-facing planning or refinement question goes through the `ask_choice`
 
 - `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with the tradeoff that matters in `description`;
 - do not add `Other` or `Auto-complete` yourself — the tool appends `Other…` second-last and `Auto-complete` last;
-- pass `autoComplete: false` for the execution handoff and for any install waiver, publishing, deployment, merge, push, credential, or external-state question. Auto-complete may choose the recommended planning or refinement option only.
+- pass `autoComplete: false` for the merged accept/execute question — it contains the execution approval, so Auto-complete never appears there — and for any install waiver, publishing, deployment, merge, push, credential, or external-state question. Auto-complete may choose the recommended planning or refinement option only.
 
 Answers are recorded automatically in the active run's `decisions.jsonl`. You must still maintain `DECISIONS.md` in the artifact directory (summary table of questions, options, answers, answer sources, open assumptions).
 
@@ -100,13 +100,13 @@ The execution loop parses `- [ ] \`VC-###\`` items and tracks `[DONE:VC-###]` ma
 
 ## Refinement
 
-After each plan version, ask one refinement-mode question via `ask_choice`. The recommended (first) option follows the skill level's default sequence; the user may always pick a different mode or keep refining:
+After each plan version, ask one merged accept/execute question via `ask_choice` with `autoComplete: false` — it contains the execution approval, so Auto-complete never appears. Options:
 
-- `plan-small`: recommend `Criticizer` for the first (and only default) round; afterwards recommend `Accept plan for tracked execution`.
-- `plan-normal`: recommend `Reviewer` first, then `Criticizer`; afterwards recommend `Accept plan for tracked execution`.
-- `plan-big`: recommend `Reviewer` first as three concurrent independent reviewers (`refine` with `reviewers: 3`), then `Criticizer`; afterwards recommend `Accept plan for tracked execution`.
+1. `✓ Accept PLAN_vN and execute it now` — mark the plan accepted (`plans set-status accepted`), then call the `execute_plan` tool.
+2. `Accept PLAN_vN, don't execute yet` — mark accepted; resume later via `/plans-execute`.
+3. `Run another round: <the level's default next refine mode>` — only while the level's default sequence is unfinished.
 
-Option list for the question: the recommended next step; the other refinement modes with their tradeoffs; `Accept plan for tracked execution`; `Other`; `Auto-complete`.
+The recommended option follows the skill level's default sequence: while the default rounds are unfinished it is option 3's default next mode (`plan-small`: `Criticizer`; `plan-normal`: `Reviewer` then `Criticizer`; `plan-big`: three concurrent reviewers (`refine` with `reviewers: 3`) then `Criticizer`); once the default sequence is complete it is option 1.
 
 If the user selects `Reviewer` or `Criticizer`, run the `refine` tool with the plan path and any focus. Reviewer output consolidates into `PLAN_vN_reviewer_comments.md` with findings IDs, severity, affected plan IDs, evidence, impact, recommended fix, and disposition. Revise the next plan only for findings accepted on evidence.
 
@@ -120,19 +120,13 @@ Present each criticizer question with `ask_choice` (one call per question, in th
 
 ### Round Lifecycle
 
-A refinement round is complete when all reviewer outputs have returned or all criticizer questions have answers. In the same turn: consolidate, accept or reject each finding on evidence (the user may override any disposition), revise to `PLAN_v(N+1).md` when accepted items require it (copy, edit only the new version, update the revision ledger and verifier checklist), then immediately ask the next refinement-mode question. Never end a turn merely because a round completed.
+A refinement round is complete when all reviewer outputs have returned or all criticizer questions have answers. In the same turn: consolidate, accept or reject each finding on evidence (the user may override any disposition), revise to `PLAN_v(N+1).md` when accepted items require it (copy, edit only the new version, update the revision ledger and verifier checklist), then immediately ask the next merged accept/execute question. Never end a turn merely because a round completed.
 
 ## Execution Handoff
 
-After the plan is accepted or refinement converges, ask the explicit execution-handoff question via `ask_choice` with `autoComplete: false`:
+When the user picks `✓ Accept PLAN_vN and execute it now` in the merged question, mark the plan accepted and call the `execute_plan` tool (or the user runs `/plans-execute`). It re-confirms with the user, then the extension enters execution mode:
 
-1. `Execute this plan now` — enter the tracked execution loop (recommended once refinement converged).
-2. `Stop after planning` — keep the plan artifact only.
-3. `Other`.
-
-On approval, call the `execute_plan` tool (or the user runs `/plans-execute`). It re-confirms with the user, then the extension enters execution mode:
-
-- every agent turn is injected with the remaining verifier checklist and execution rules (ponytail discipline, minimum tests);
+- every agent turn is injected with the remaining verifier checklist and execution rules (layered simplest implementation, no stopgaps, dependency and library discipline, minimum tests);
 - the read-only guard lifts: full write access returns;
 - the run status moves to `executing`, then `done` when the last `[DONE:VC-xxx]` marker lands;
 - `/plans-stop` stops execution; `/plans` shows progress.
@@ -144,8 +138,8 @@ If the user declines, stay in planning (or stop, per their choice). Never start
 Stop and return to the workflow if any of these happen:
 
 - implementing before the approved execution handoff;
-- running `refine` without first asking the refinement-mode question, or before the role gates pass;
-- ending a turn after a completed refinement round without asking the next refinement-mode question;
+- running `refine` without first asking the merged accept/execute question, or before the role gates pass;
+- ending a turn after a completed refinement round without asking the next merged accept/execute question;
 - storing planning settings outside the target workspace's `.git/pi_plans/` state directory;
 - asking multiple planning questions in one message, or asking them outside `ask_choice`;
 - writing `PLAN_v1.md` before final scope confirmation;

package/references/plan-artifact-template.md

@@ -70,7 +70,7 @@ Summarize the user's request in one paragraph.
 
 ## Execution Handoff Notes
 
-State anything the executor should know, including order of work, files to avoid, and verification commands. The execution handoff still requires explicit user approval (ask_choice with `autoComplete: false`, then the `execute_plan` tool) and must never be auto-completed. Once approved, the extension-managed execution loop injects the remaining checklist every turn and completes when every `[DONE:VC-xxx]` marker has landed — keep this section concise enough to serve as the executor's brief.
+State anything the executor should know, including order of work, files to avoid, and verification commands. The merged accept/execute question still requires explicit user approval (ask_choice with `autoComplete: false`, then the `execute_plan` tool) and must never be auto-completed. Once approved, the extension-managed execution loop injects the remaining checklist every turn and completes when every `[DONE:VC-xxx]` marker has landed — keep this section concise enough to serve as the executor's brief.
 
 ## Revision Ledger
 

package/references/state-and-config.md

@@ -126,7 +126,7 @@ When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` s
 - receives the full plan text and a review/criticism brief;
 - returns its findings as the tool result (recorded in `subagents.jsonl` with name and model).
 
-The main agent consolidates the results, records dispositions, revises the plan, and asks the next refinement-mode question — all in the same turn.
+The main agent consolidates the results, records dispositions, revises the plan, and asks the next merged accept/execute question — all in the same turn.
 
 ## Run State
 

package/skills/debug-and-plan/SKILL.md

@@ -20,7 +20,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
    2. `Stop after RCA` — keep the diagnosis only.
    3. `Other` / 4. `Auto-complete` are added by the tool.
 4. On opt-out, stop after the summary; do not write `PROBLEM_ANALYSIS.md`.
-5. On opt-in (or `Auto-complete` choosing the recommendation), select the smallest fitting planning skill and follow that skill exactly: first-turn planning question, final scope confirmation, `PLAN_v1.md`, refinement, and the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+5. On opt-in (or `Auto-complete` choosing the recommendation), select the smallest fitting planning skill and follow that skill exactly: first-turn planning question, final scope confirmation, `PLAN_v1.md`, refinement, and the merged accept/execute question (ask_choice with `autoComplete: false`) before calling the `execute_plan` tool.
 
 ## Level Selection
 

package/skills/plan-big/SKILL.md

@@ -17,7 +17,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 - Ask at least 10 planning questions, one at a time; no maximum — stop only when the decision tree is genuinely resolved. Each via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last).
 - Use web research during both brainstorming and refinement when outside facts, patterns, or ecosystem constraints matter, and cite sources in the plan.
 - Ask the final scope confirmation, then write `PLAN_v1.md` per `../../references/plan-artifact-template.md`.
-- After each plan version, ask the refinement-mode question via `ask_choice` — never run `refine` unless the user or `Auto-complete` selected it at that question. Default sequence: one `Reviewer` round as three concurrent independent reviewers (`refine` with `reviewers: 3`, consolidated by the main agent per the shared workflow), then one `Criticizer` round; afterwards the recommended option is `Accept plan for tracked execution`. Beyond the default sequence, refine until convergence on high-priority findings, unresolved questions, or evidence gaps; surface at most five per round. Then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default sequence: one `Reviewer` round as three concurrent independent reviewers (`refine` with `reviewers: 3`, consolidated by the main agent per the shared workflow), then one `Criticizer` round; afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question. Beyond the default sequence, refine until convergence on high-priority findings, unresolved questions, or evidence gaps; surface at most five per round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 
 ## Fit
 

package/skills/plan-normal/SKILL.md

@@ -17,7 +17,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 - Ask 5 to 10 planning questions, one at a time, each via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last).
 - Use web research whenever outside library behavior, ecosystem precedent, UX convention, protocol semantics, or compatibility affects the recommendation (websearch skill when installed; otherwise `curl`/`gh` via bash), and cite sources in the plan.
 - Ask the final scope confirmation, then write `PLAN_v1.md` per `../../references/plan-artifact-template.md`.
-- After each plan version, ask the refinement-mode question via `ask_choice` — never run `refine` unless the user or `Auto-complete` selected it at that question. Default sequence: one `Reviewer` round, then one `Criticizer` round; afterwards the recommended option is `Accept plan for tracked execution`. Up to five rounds total, continuing only for high-priority findings or unresolved criticizer questions; surface at most five per round. Then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default sequence: one `Reviewer` round, then one `Criticizer` round; afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question. Up to five rounds total, continuing only for high-priority findings or unresolved criticizer questions; surface at most five per round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 
 ## Fit
 

package/skills/plan-small/SKILL.md

@@ -16,7 +16,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 - Inspect the target Git repo read-only before the first product question.
 - Ask 1 to 3 planning questions, one at a time, each via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last).
 - Ask the final scope confirmation, then write `PLAN_v1.md` under the artifact root (normally the configured workspace root, default `./docs/pi-plans/YYYY-MM-DD-topic/`) per `../../references/plan-artifact-template.md`.
-- After each plan version, ask the refinement-mode question via `ask_choice` — never run `refine` unless the user or `Auto-complete` selected it at that question. Default: exactly one round, recommended mode `Criticizer`; afterwards the recommended option is `Accept plan for tracked execution`, then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default: exactly one round, recommended mode `Criticizer`; afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round), then the `execute_plan` tool.
 
 ## Fit
 

package/skills/plan-with-refs/SKILL.md

@@ -21,7 +21,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 6. For every reference, produce a structured analysis artifact (manual structured read recorded in `REF_ANALYSIS.md`) before asking adoption questions.
 7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both).
 8. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum. `Auto-complete` cannot grant this waiver.
-9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round, then a criticizer round), no refinement limit, at most five high-priority comments or questions per refinement round. Then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round, then a criticizer round), no refinement limit, at most five high-priority comments or questions per refinement round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 
 ## REF_ANALYSIS.md