pi-plans 0.5.7 → 0.7.0

package/index.ts

@@ -1,16 +1,16 @@
 /**
  * pi-plans — human-in-the-loop planning for the Pi coding agent.
  *
- * Researched, refined Markdown plans before any code changes. The five
+ * Researched, refined Markdown plans before any code changes. The six
  * planning skills are contributed via resources_discover; the extension
  * provides the supporting machinery:
  *
- *   - `plans` tool      — workspace state (config, runs, ledgers) in .git/pi_plans/
+ *   - `plans` tool      — workspace state (config, runs, ledgers) in .git/pi-plans/
  *   - `ask_choice` tool — the choice-prompt contract (Other / Auto-complete rules)
- *   - `refine` tool     — reviewer/criticizer rounds via read-only pi subagents
+ *   - `refine` tool     — reviewer rounds (findings + questions) via read-only pi subagents
  *   - `execute_plan`    — execution handoff into the tracked execution loop
  *   - write guard       — planning runs may only write planning artifacts
- *   - execution loop    — checklist injection, [DONE:VC-xxx] tracking, progress status
+ *   - execution loop    — task-tree injection, plans_update_task tracking, dashboard, audit
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -44,6 +44,7 @@ import {
 	requestPlanningCompaction,
 	restoreFromSession,
 	stopExecution,
+	toggleDashboardExpanded,
 	updateStatusWidget,
 	shouldTriggerPlanningCompaction,
 } from "./src/exec.ts";
@@ -75,14 +76,18 @@ import { restartWatcherIfEnabled, stopGraphWatcher, disableWatcher } from "./src
 import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
 import { configPiPlansCommand } from "./src/config-command.ts";
 import { resumePlansCommand } from "./src/resume-command.ts";
-import { getRun, loadConfig, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
+import { getRun, listRuns, loadConfig, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
 import { boundRunId, resolveActiveRun, restoreRunBindingFromSession } from "./src/run-context.ts";
+import { abandonCandidates, resolveCommandRun } from "./src/run-picker.ts";
 import { applyPlanWritten, mutateCheckpoint, planIdentityOf } from "./src/workflow-state.ts";
 import { registerAskChoiceTool } from "./tools/ask-choice.ts";
 import { executeCommand, registerExecutePlanTool } from "./tools/execute-plan.ts";
+import { registerTaskStatusTool } from "./src/task-tool.ts";
+import { flattenTaskViews, taskIsTerminal, taskProgress } from "./src/tasks.ts";
 import { registerPlansTool } from "./tools/plans.ts";
 import { registerRefineTool } from "./tools/refine.ts";
 import { registerAnalyzeRefsTool } from "./tools/analyze-refs.ts";
+import { messaging, setMessagingApi } from "./src/messaging.ts";
 
 const baseDir = dirname(fileURLToPath(import.meta.url));
 
@@ -125,11 +130,17 @@ function hasActivePlanningWorkflow(ctx: Parameters<typeof updateStatusWidget>[0]
 }
 
 export default function piPlansExtension(pi: ExtensionAPI): void {
+	setMessagingApi(pi);
 	registerPlansTool(pi);
 	registerAskChoiceTool(pi);
 	registerRefineTool(pi, baseDir);
 	registerAnalyzeRefsTool(pi, baseDir);
 	registerExecutePlanTool(pi);
+	registerTaskStatusTool(pi);
+	pi.registerShortcut("ctrl+shift+t", {
+		description: "Expand/collapse the pi-plans task dashboard",
+		handler: (ctx) => toggleDashboardExpanded(ctx),
+	});
 	registerQueryInterviewHooks(pi, hasActivePlanningWorkflow);
 	registerCodeGraphTool(pi);
 	registerGraphAwareFileTools(pi);
@@ -176,7 +187,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 			handler: async (args, ctx) => {
 				const invocation = args.trim() ? `/skill:${name} ${args.trim()}` : `/skill:${name}`;
 				try {
-					pi.sendUserMessage(invocation, { expandPromptTemplates: true });
+					messaging().sendUserMessage(invocation, { expandPromptTemplates: true });
 				} catch {
 					ctx.ui.notify("Agent is busy; try again once the current turn finishes.", "error");
 				}
@@ -206,7 +217,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 			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, {
+					messaging().appendEntry(PLANNING_PLAN_WRITTEN_CUSTOM_TYPE, {
 						runId: active.run_id,
 						planPath: latest.path,
 					});
@@ -252,14 +263,14 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		if (event.toolName !== "plans") return;
 		if (!consumePrePlanCompactPending(ctx)) return;
 		if (typeof ctx.compact !== "function") {
-			sendPrePlanCompactResume(pi);
+			sendPrePlanCompactResume(ctx);
 			return;
 		}
 		let resumed = false;
 		const resumeOnce = () => {
 			if (resumed) return;
 			resumed = true;
-			sendPrePlanCompactResume(pi);
+			sendPrePlanCompactResume(ctx);
 		};
 		ctx.compact({
 			customInstructions: PLANNING_PREPLAN_COMPACT_HINT,
@@ -311,18 +322,18 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_before_compact", async (event, ctx) => {
 		noteCompactionStarted(ctx, event.customInstructions);
-		const executionResult = await handleExecutionBeforeCompact(pi, ctx, event);
+		const executionResult = await handleExecutionBeforeCompact(ctx, event);
 		if (executionResult) return executionResult;
-		return handlePlanningBeforeCompact(pi, ctx, event);
+		return handlePlanningBeforeCompact(ctx, event);
 	});
 	pi.on("session_compact", async (event, ctx) => {
-		await handleExecutionCompact(pi, ctx, event);
-		await handlePlanningCompact(pi, ctx, event);
+		await handleExecutionCompact(ctx, event);
+		await handlePlanningCompact(ctx, event);
 		noteCompactionEnded(ctx, event.customInstructions);
 	});
 	pi.on("session_compact_failed", async (event, ctx) => {
-		handleExecutionCompactFailed(pi, ctx, event);
-		handlePlanningCompactFailed(pi, ctx, event);
+		handleExecutionCompactFailed(ctx, event);
+		handlePlanningCompactFailed(ctx, event);
 		noteCompactionEnded(ctx, event.customInstructions);
 	});
 
@@ -330,7 +341,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// Execution loop: inject remaining checklist each turn, track markers.
 	// -----------------------------------------------------------------------
 	pi.on("before_agent_start", async (_event, ctx) => {
-		drainExecutionFlush(pi, ctx);
+		drainExecutionFlush(ctx);
 		const content = executionContextMessage(ctx);
 		if (!content) {
 			if (!getExecution() && shouldTriggerPlanningCompaction(ctx)) {
@@ -370,7 +381,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// -----------------------------------------------------------------------
 
 	pi.registerCommand("init-graph", {
-		description: "Index the worktree into .git/pi_plans/code_graph.db. If a graph DB already exists, prompt to rebuild or sync changed paths via /update-graph; `--reindex` and non-interactive runs stay on the rebuild path.",
+		description: "Index the worktree into .git/pi-plans/code_graph.db. If a graph DB already exists, prompt to rebuild or sync changed paths via /update-graph; `--reindex` and non-interactive runs stay on the rebuild path.",
 		handler: async (args, ctx) => {
 			await initGraphCommand(args, ctx);
 		},
@@ -436,23 +447,38 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		description: "Show pi-plans state: config, active run, and execution progress",
 		handler: async (_args, ctx) => {
 			const lines: string[] = [];
+			// v0.6.0: list ALL runs (newest first, bound marked, cap 50) instead of
+			// only the shared active one — multi-run workdirs stay legible.
+			const runs = listRuns(ctx.cwd).slice(0, 50);
+			const bound = boundRunId(ctx.sessionManager, ctx.cwd);
+			if (runs.length === 0) {
+				lines.push("No planning runs recorded in this workdir.");
+			} else {
+				lines.push(`Runs (${runs.length} shown, newest first):`);
+				for (const run of runs) {
+					lines.push(`  ${run.run_id === bound ? "★" : " "} ${run.topic} · ${run.status} · ${run.skill} · ${run.updated_at}`);
+				}
+			}
 			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 			const run = active ? getRun(ctx.cwd, active.run_id) : null;
-			if (!run) {
-				lines.push("No active planning run.");
-			} else {
-				lines.push(`Active run: ${run.run_id}`);
+			if (run) {
+				lines.push(`Session run: ${run.run_id}`);
 				lines.push(`Skill: ${run.skill}  Status: ${run.status}`);
 				lines.push(`Artifacts: ${run.artifact_dir}`);
 				lines.push(`Language: ${run.language_tag ?? "(unset)"}`);
 				lines.push(`State: ${resolveStateRootOrNull(ctx.cwd) ?? "(no repo)"}`);
 			}
+			// One-time active.json deprecation note (v0.6.0 registry migration).
+			if (fs.existsSync(path.join(resolveStateRootOrNull(ctx.cwd) ?? ".git/pi-plans", "active.json"))) {
+				lines.push("Note: active.json is deprecated — the run registry now derives from runs/*/run.json; the legacy file is ignored.");
+			}
 			const execution = getExecution();
 			if (execution) {
-				const done = execution.items.filter((item) => item.done).length;
-				lines.push(`Execution: ${execution.planPath} — ${done}/${execution.items.length} verifier items done`);
-				for (const item of execution.items) {
-					lines.push(`  ${item.done ? "☑" : "☐"} ${item.id}`);
+				const progress = taskProgress(execution.tasks);
+				const vcDone = execution.items.filter((item) => item.done).length;
+				lines.push(`Execution: ${execution.planPath} — tasks ${progress.done}/${progress.total} · VC ${vcDone}/${execution.items.length}`);
+				for (const task of flattenTaskViews(execution.tasks)) {
+					lines.push(`  ${taskIsTerminal(task) ? (task.status === "skipped" ? "~" : "☑") : "☐"} ${task.id}`);
 				}
 			}
 			lines.push(`Auto-complete: ${autoCompleteStatus(ctx)}`);
@@ -462,7 +488,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.registerCommand("config-pi-plans", {
-		description: "Re-ask and update pi-plans workspace config: language, artifact root, graph, reviewer, and criticizer defaults",
+		description: "Re-ask and update pi-plans workspace config: language, artifact root, graph, and reviewer defaults",
 		handler: async (args, ctx) => {
 			await configPiPlansCommand(args, ctx);
 		},
@@ -538,7 +564,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;
-				await stopExecution(pi, ctx, "interrupted by /update-plan");
+				await stopExecution(ctx, "interrupted by /update-plan");
 			}
 
 			// Return the run to planning so refinement rules and guards apply again.
@@ -586,7 +612,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 				"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"));
+			await messaging().sendUserMessage(lines.join("\n"));
 		},
 	});
 
@@ -597,9 +623,9 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 				ctx.ui.notify("No execution in progress.", "info");
 				return;
 			}
-			const ok = await ctx.ui.confirm("Stop execution?", "Remaining verifier items will be left unfinished.");
+			const ok = await ctx.ui.confirm("Stop execution?", "Open tasks will be left unfinished.");
 			if (!ok) return;
-			await stopExecution(pi, ctx, "stopped by user via /plans-stop");
+			await stopExecution(ctx, "stopped by user via /plans-stop");
 			ctx.ui.notify("Execution stopped.", "info");
 		},
 	});
@@ -608,31 +634,38 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		description:
 			"Resume the working plan in this repository: unfinished planning / reviewing / execution / implementation review, across sessions and linked worktrees, in the current session.",
 		handler: async (_args, ctx) => {
-			await resumePlansCommand(pi, ctx, baseDir);
+			await resumePlansCommand(ctx, baseDir);
 		},
 	});
 
 	pi.registerCommand("plans-abandon", {
 		description: "Abandon the active planning run (lifts the read-only guard; artifacts are kept)",
 		handler: async (_args, ctx) => {
-			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
-			if (!active) {
+			// v0.6.0 (R-3): pick the run to abandon when several candidates exist;
+			// binding-first, single candidate stays direct (0.5.7 parity).
+			const chosen = await resolveCommandRun(
+				{ cwd: ctx.cwd, sessionManager: ctx.sessionManager, ui: ctx.ui },
+				{ candidates: abandonCandidates(ctx.cwd), title: "Abandon which run?" },
+			);
+			if (!chosen) {
 				ctx.ui.notify("No active planning run.", "info");
 				return;
 			}
+			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
+			const abandoningBound = active?.run_id === chosen.run_id;
 			const ok = await ctx.ui.confirm(
 				"Abandon planning run?",
-				`${active.run_id}\nThe read-only guard lifts; committed artifacts stay in place.`,
+				`${chosen.run_id} (${chosen.topic} · ${chosen.status})\nThe read-only guard lifts; committed artifacts stay in place.`,
 			);
 			if (!ok) return;
 			// Abandon must end execution first so the planning model is restored.
 			disableAutoComplete(ctx, "run abandoned");
-			if (getExecution()) {
-				await stopExecution(pi, ctx, "run abandoned via /plans-abandon");
+			if (abandoningBound && getExecution()) {
+				await stopExecution(ctx, "run abandoned via /plans-abandon");
 			}
 			try {
-				setRunStatus(ctx.cwd, active.run_id, "abandoned");
-				ctx.ui.notify(`Run ${active.run_id} abandoned.`, "info");
+				setRunStatus(ctx.cwd, chosen.run_id, "abandoned");
+			ctx.ui.notify(`Run ${chosen.run_id} abandoned.`, "info");
 			} catch (error) {
 				ctx.ui.notify(`Failed: ${(error as Error).message}`, "error");
 			}
@@ -644,7 +677,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// Session lifecycle
 	// -----------------------------------------------------------------------
 	pi.on("session_tree", async (_event, ctx) => {
-		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
+		await restoreFromSession(ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[1]);
 		restoreRunBindingFromSession(
 			ctx.sessionManager,
 			ctx.cwd,
@@ -652,7 +685,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		);
 	});
 	pi.on("session_start", async (_event, ctx) => {
-		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
+		await restoreFromSession(ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[1]);
 		restoreAutoCompleteFromSession(ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreAutoCompleteFromSession>[1]);
 		restoreRunBindingFromSession(
 			ctx.sessionManager,
@@ -661,3 +694,4 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		);
 	});
 }
+

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-plans",
-	"version": "0.5.7",
+	"version": "0.7.0",
 	"description": "Human-in-the-loop planning extension for the Pi coding agent: researched, refined Markdown plans before any code changes.",
 	"license": "MIT",
 	"type": "module",
@@ -40,6 +40,7 @@
 	"files": [
 		"README.md",
 		"LICENSE",
+		"CONTRIBUTING.md",
 		"index.ts",
 		"agents/",
 		"docs/assets",

package/references/pi-planning-workflow.md

@@ -9,17 +9,17 @@ This skill set is written for the Pi coding agent's documented behavior:
 - the five skills are contributed by the pi-plans extension and loaded as Pi skills (also invokable as `/skill:<name>`);
 - skill references and helper sources are resolved relative to the directory containing `SKILL.md`;
 - Planning and reference analysis run with the extension tools `plans`, `ask_choice`, `refine`, `analyze_refs`, and `execute_plan`;
-- `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` for both roles when workspace `graph_enabled` is true) with isolated context; delegated Reviewer/Criticizer runs show a standalone aggregate overlay titled `Reviewer` or `Criticizer` (78% × 78% top-center, ≥72 cols, no input row), stream assistant/thinking/tool events into per-lane transcripts with follow-bottom scroll, dismiss on `Esc` (close-only — the refiner child keeps running and its result still flows back as tool output), replace any retained finished overlay when a new round begins, and return conclusions to the main session as tool output; `analyze_refs` spawns one read-only subagent per downloaded reference (cwd = that ref's directory) reusing the reviewer role gates, shows the same overlay titled `Refs` in batches of at most 3 lanes, and returns structured per-reference sections for `REF_ANALYSIS.md`;
+- `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` when workspace `graph_enabled` is true) with isolated context; delegated reviewer runs show a standalone aggregate overlay titled `Reviewer` (78% × 78% top-center, ≥72 cols, no input row), stream assistant/thinking/tool events into per-lane transcripts with follow-bottom scroll, dismiss on `Esc` (close-only — the refiner child keeps running and its result still flows back as tool output), replace any retained finished overlay when a new round begins, and return conclusions to the main session as tool output; `analyze_refs` spawns one read-only subagent per downloaded reference (cwd = that ref's directory) reusing the reviewer role gates, shows the same overlay titled `Refs` in batches of at most 3 lanes, and returns structured per-reference sections for `REF_ANALYSIS.md`;
 - when graph mode is enabled, graph-aware `read`/`edit` overrides are active for indexed source files: `read` returns a capped function digest (≤50 lines, synthetic anonymous entries folded) by default — drill in via `offset/limit` or `code_graph get-function`, and `full: true` is the only whole-file exit (small/zero-function files return full text; safety truncation matches native read); `write`/`edit` stage DB-first mutations until materialized via the `code_graph` tool's `apply` action (same planning/accepted gate as /apply-graph; refused for read-only refiner subagents via the PI_PLANS_REFINER marker; returns a per-file report with counts and a post-apply drift summary, and never changes run status); unexpected fallbacks (`not indexed` / `runtime unavailable` / `config read failed`) are marked at the top of the result while flag-off fallbacks stay unmarked;
-- the execution loop is extension-managed: remaining verifier items are injected each turn, implementation items emit `[I-###:current]`/`[I-###:implemented|validating]`, and `[DONE:VC-xxx]` markers are tracked with a bottom status bar;
+- the execution loop is extension-managed and task-tree driven: the current wave and remaining tasks are injected each turn, progress is reported exclusively through the `plans_update_task` tool (status + evidence / skipReason), the task dashboard tracks every task (compact widget; Ctrl+Shift+T expands the tree), and an independent completion auditor verifies the verification checks before the run completes;
 - execution and planning compaction keep Pi's SessionManager as the history owner; during active pi-plans runs, `session_before_compact` uses a deterministic no-LLM VCC-style summary with `[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, `[User Preferences]`, and a ranked brief transcript; Pi core owns manual `/compact`, threshold, and overflow scheduling, while pi-plans handles smart tail keep, `keep:N`, stats, and phase-specific run/plan/current-I/checklist context; in addition, creating a new planning run (`plans start-run`) proactively requests one pre-plan VCC compaction before the first planning question and resumes the planning turn with a hidden message (default on, `prePlanCompact` in `pi-vcc-config.json`);
 
 ## Planning Boundary
 
 - Treat the user's request as a planning target, not as write authorization.
-- Before the execution handoff, do not edit target source files, docs, configs, package metadata, generated assets, or tests outside the planning artifact directory and the pi-plans state under `.git/pi_plans/`. The extension enforces this for `edit` and `write` while a run is active: only `.git/pi_plans/`, the run's artifact directory, `~/.cache/pi-plans/`, and the configured refs root are writable. Bash is not machine-guarded — keep it read-only by discipline (inspection, `git init`, downloads into the cache).
-- The normal pre-handoff writes are `.git/pi_plans/` state plus planning artifacts under the configured artifact root (default `./docs/pi-plans/...`).
-- Downloaded references go to the workspace's configured refs root (`refs_root` in `.git/pi_plans/config.json`; unset → ask once via `ask_choice`, recommended `.git/pi-plans/refs/`, second `./refs/`, third `~/.cache/pi-plans/refs/`; persist with the `plans` tool, `set-refs-root`) and their paths and evidence are recorded in `REF_ANALYSIS.md`.
+- Before the execution handoff, do not edit target source files, docs, configs, package metadata, generated assets, or tests outside the planning artifact directory and the pi-plans state under `.git/pi-plans/`. The extension enforces this for `edit` and `write` while a run is active: only `.git/pi-plans/`, the run's artifact directory, `~/.cache/pi-plans/`, and the configured refs root are writable. Bash is not machine-guarded — keep it read-only by discipline (inspection, `git init`, downloads into the cache).
+- The normal pre-handoff writes are `.git/pi-plans/` state plus planning artifacts under the configured artifact root (default `./.git/pi-plans/plans/...`).
+- Downloaded references go to the workspace's configured refs root (`refs_root` in `.git/pi-plans/config.json`; unset → ask once via `ask_choice`, recommended `.git/pi-plans/refs/`, second `./refs/`, third `~/.cache/pi-plans/refs/`; persist with the `plans` tool, `set-refs-root`) and their paths and evidence are recorded in `REF_ANALYSIS.md`. References are not limited to GitHub repositories: papers (arXiv etc.), engineering blogs, and documentation sites are first-class, with per-medium qualified downloads (repo = clone; paper = full text — abstracts never qualify; blog/docs = full-article markdown) and one directory per reference; theoretical references count exactly as much as implementation references. plan-normal and plan-big may optionally cite 1–2 search-found references (URLs in the plan's Evidence section) without downloading them.
 - After the user explicitly approves the execution handoff, leave this planning workflow and execute in the extension-managed loop (see Execution Handoff).
 
 ## State And Settings
@@ -30,13 +30,13 @@ Before the first planning question, read `references/state-and-config.md` and in
 { "action": "init", "workdir": "<target-workdir>" }
 ```
 
-State lives under the workspace's resolved git common dir as `.git/pi_plans/` (auto-ignored, no `.gitignore` entries; the tool auto-runs `git init` when the workdir safely has no repository). The target workspace is the current working directory unless the user explicitly names another repository.
+State lives under the workspace's resolved git common dir as `.git/pi-plans/` (auto-ignored, no `.gitignore` entries; the tool auto-runs `git init` when the workdir safely has no repository). The target workspace is the current working directory unless the user explicitly names another repository.
 
-If `language.tag` is missing from `.git/pi_plans/config.json`, ask the language setting question (via `ask_choice`) before any product question. Persist it with `plans` (`set-language`); this question does not count against the planning-question limit.
+If `language.tag` is missing from `.git/pi-plans/config.json`, ask the language setting question (via `ask_choice`) before any product question. Persist it with `plans` (`set-language`); this question does not count against the planning-question limit.
 
-If `artifact_root_source` is missing from `.git/pi_plans/config.json` or is `unset`, ask the planning docs location question (via `ask_choice`) before any product question. Persist it with `plans` (`set-artifact-root`); this question does not count against the planning-question limit.
+If `artifact_root_source` is missing from `.git/pi-plans/config.json` or is `unset`, ask the planning docs location question (via `ask_choice`) before any product question. Persist it with `plans` (`set-artifact-root`); this question does not count against the planning-question limit.
 
-Reviewer and criticizer settings also live in `config.json`. If a role's mode is missing/invalid or its `confirmed_at` is `null` when the role is about to run, ask the matching role-setting or model-confirmation question (via `ask_choice`), persist with `plans` (`set-role`), and then run the `refine` tool. The `refine` tool refuses to spawn until the gates pass.
+The reviewer role lives in the GLOBAL config (`~/.pi/pi-plans/config.json`, `PI_PLANS_GLOBAL_DIR` override — one confirmation for every workspace). If its mode is missing/invalid when a round is about to run, ask the role-setting question via `ask_choice` and persist with `plans` (`set-role`). The model + thinking level are confirmed at first use through NATIVE panels, not ask_choice: in TUI the `refine` gate itself pops a searchable model panel followed by an effort panel (Default row = no `--thinking` flag; other rows follow the chosen model's `thinkingLevelMap`) and continues the same invocation on completion; hasUI non-TUI sessions get native menus; UI-less sessions get text guidance embedding the available selectors. Esc cancels the whole gate (nothing persisted; do NOT re-ask via ask_choice — suggest `/config-pi-plans`). The `refine` tool refuses to spawn until `reviewerReady` passes (current-session, or delegated with a confirmed concrete `provider/model`). (v0.6.1: the criticizer role is gone — the reviewer emits findings AND questions in one round.)
 
 ## First-Turn Contract
 
@@ -59,7 +59,7 @@ When the recommended option depends on a web-verifiable claim, search first (web
 
 Every user-facing planning or refinement question goes through the `ask_choice` tool:
 
-- `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with the tradeoff that matters in `description`;
+- `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with a `description` of the form `✓ <advantage> / ✗ <drawback>` — **every option you author states both what it gains and what it costs**, in the configured language, tersely (≈8 words per half; write `—` when a side is genuinely absent). Both halves live in the single `description` string; there are no separate `pros`/`cons` fields. This rule covers every AI-written option, including the scope confirmation and the merged accept/execute handoff; only the tool-appended `Other…` / `Auto-complete` rows are exempt;
 - do not add `Other` or `Auto-complete` yourself — the tool appends `Other…` second-last and `Auto-complete` last;
 - 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.
 - When the user selects Auto-complete, it remains active for the current planning run: later eligible questions use their recommended options automatically, and the extension queues one deduplicated follow-up if the model stops after an auto-completed answer. `/plans-autocomplete-stop` disables it; session restore may reactivate it only for the same active run while its status is `planning`.
@@ -74,9 +74,9 @@ Create a run only after initial read-only inspection makes the topic clear:
 { "action": "start-run", "workdir": "<target-workdir>", "topic": "<short topic>", "skill": "<skill-name>", "requestText": "<original request>" }
 ```
 
-The tool creates the configured artifact directory root (default `./docs/pi-plans/YYYY-MM-DD-<topic>/`) and the private run state `.git/pi_plans/runs/<run-id>/`, and stores the active run pointer. Use a short lowercase slug for the topic. Keep paths stable once written.
+The tool creates the configured artifact directory root (default `./.git/pi-plans/plans/YYYY-MM-DD-<topic>/`) and the private run state `.git/pi-plans/runs/<run-id>/`, and stores the active run pointer. Use a short lowercase slug for the topic. Keep paths stable once written.
 
-`DECISIONS.md` records: original request; repository evidence inspected; each question, options, selected answer, and whether it came from the user or Auto-complete; assumptions still open; external sources consulted; language, reviewer, and criticizer settings used.
+`DECISIONS.md` records: original request; repository evidence inspected; each question, options, selected answer, and whether it came from the user or Auto-complete; assumptions still open; external sources consulted; language and reviewer settings used.
 
 ## Final Scope Confirmation
 
@@ -91,93 +91,80 @@ If the user adds requirements, resolve only the necessary follow-up questions, t
 
 ## Plan Artifact Requirements
 
-Every `PLAN_vN.md` must include stable IDs that are never recycled across revisions: goals and non-goals; requirements and constraints; implementation items; affected paths; dependencies and sequencing; risks and mitigations; acceptance criteria; verification steps; repo and external evidence; resolved decisions; revision ledger.
+Every `PLAN_vN.md` must include stable IDs that are never recycled across revisions: `Task-N` tasks (with deps/files/wave and one subtask level), `VC-###` verification checks, and the revision ledger. Everything else the workflow needs lives in the run state (decisions ledger, review rounds, refs), not in the plan file.
 
-Every plan version must include a dedicated `## Verifier Checklist` section. Each item is a Markdown checkbox of the exact shape:
+Every plan version's body is exactly two sections — `## Tasks` and `## Verification Checks` — plus the metadata header (see `references/plan-artifact-template.md` for the full microsyntax: `Task-N` ids, one subtask level, inline `deps:`/`files:`/`wave:` fields, the `### Execution Waves` subsection, and lint rules). Each verification check is a Markdown checkbox of the exact shape:
 
 ```markdown
-- [ ] `VC-001` covers `I-001`; pass condition: ...; evidence: ...; metric: <threshold or reason not quantified>.
+- [ ] `VC-001` covers `Task-1`; pass condition: ...; evidence: ...; metric: <threshold or reason not quantified>.
 ```
 
-The execution loop parses `- [ ] \`VC-###\`` items and tracks `[DONE:VC-###]` markers, so keep IDs on the checkbox line. Use `references/plan-artifact-template.md` when drafting.
+The execution loop parses `- [ ] \`VC-###\`` checks and the task tree, so keep IDs on the checkbox line and the task grammar exact; task progress flows through `plans_update_task` and the completion auditor reads these checks. Use `references/plan-artifact-template.md` when drafting.
 
 ## Refinement
 
-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:
+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. Each of the three options below carries the usual `✓ <advantage> / ✗ <drawback>` description (executing now versus deferring versus another refine round are real trade-offs — say what each wins and costs). Options:
 
 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.
 
-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.
+The recommended option follows the skill level's default sequence: while the default round is unfinished it is option 3 (`plan-small` / `plan-normal`: one reviewer round; `plan-big` / `plan-with-refs`: three concurrent reviewers via `refine` with `reviewers: 3`); once the default round is complete it is option 1. Every round returns findings (`F-###`) and up to five questions (`Q-1..Q-5`) in the same output.
 
-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.
+If the user selects another round, 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.
 
 ### Concurrent Reviewers (big plans)
 
 A big-plan reviewer round runs three independent reviewer subagents (`reviewers: 3`); each gets its own emphasis lens but forms its own priorities. After they return, merge and dedupe their findings into one consolidated `PLAN_vN_reviewer_comments.md`, keeping each finding's source reviewer, severity, evidence, and disposition, and surface at most five high-priority comments to the user. Treat agreement between independent reviewers as stronger evidence, not as authority; every accepted finding still needs repo or reference evidence.
 
-### Criticizer Rounds
+### Reviewer Questions
 
-Present each criticizer question with `ask_choice` (one call per question, in the configured language). Before each question, summarize the original criticism in at most three sentences and highlight the most important point. Do not revise the plan until every criticizer question has a recorded answer.
+Merge the rounds' `Questions` sections into one deduped list and ask EVERY question with `ask_choice` (one batched `questions: [...]` form or one call per question, in the configured language, stable questionIds). Do not revise the plan until every reviewer question has a recorded answer.
 
 ### 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 merged accept/execute question. Never end a turn merely because a round completed.
+A refinement round is complete when all reviewer lanes have returned; each lane's output carries findings (`F-###`) and up to five questions (`Q-1..Q-5`). 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
 
-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:
+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 (never auto-completed), then the extension enters task-tree execution mode:
 
-- every agent turn is injected with the remaining verifier checklist and execution rules (layered simplest implementation, waiting for subprocess-backed verification with backoff 5s -> 10s -> 20s -> 40s -> 80s, then keep polling at 80s and restart at 5s for each new subprocess, no stopgaps, dependency and library discipline, minimum tests);
-- execution-phase compaction is handled only when Pi core emits manual `/compact`, threshold, or overflow events; summaries are deterministic VCC-style summaries, include session-derived plan/current-I/checklist context, use smart tail keep and `keep:N`, and never call a model or request proactive current-I compaction;
+- every agent turn is injected with the current wave's open tasks, the remaining task list, verification-check summary, and execution rules (wave order, `plans_update_task` reporting with status + evidence / skipReason, subprocess polling backoff 5s -> 10s -> 20s -> 40s -> 80s then keep polling at 80s, no stopgaps, dependency and library discipline, minimum tests);
+- task progress flows exclusively through the `plans_update_task` tool: one call per task closing it as `complete` (with evidence) or `skipped` (with skipReason); closed statuses are immutable outside the audit-authorized rollback channel; subtasks close before their parent;
+- the task dashboard tracks the whole tree live: a compact aboveEditor widget (current task ▸, progress bar, ✓/· counts, VC pass count, wave indicator, pause state, audit-failure line) and the Ctrl+Shift+T expanded tree view (✓/▸/~/· markers, current-task anchor, VC list with audit state, width-adaptive layout);
+- a stall watchdog pauses execution after three consecutive settled rounds without any task-status change (genuine user input or `/plans-execute` resumes without losing progress);
+- when every task reaches a terminal state, an independent read-only completion auditor verifies each check against the worktree: failed checks roll their covered tasks (children cascade, skipped tasks reopen) back to pending and inject the audit report; the audit re-runs as tasks re-close; after three failed rounds the run pauses for the user — under auto-approve/headless it terminates as `stopped` with the audit report so pipelines never hang; checks whose covered tasks are all skipped pass as skipped-pass; checks covering no task never enter the audit;
+- execution-phase compaction is handled only when Pi core emits manual `/compact`, threshold, or overflow events; summaries are deterministic VCC-style summaries, include session-derived plan/current-task/checklist context, use smart tail keep and `keep:N`, and never call a model;
 - 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;
+- the run status moves to `executing`, then `done` when the completion audit passes;
 - `/plans-stop` stops execution; `/plans` shows progress.
 
 If the user declines, stay in planning (or stop, per their choice). Never start implementation without the approved handoff.
 
-### Execution Goal-Wait
+### Continuation Between Turns
 
-In TUI/RPC, automatic goal-wait is evaluated only at `agent_settled`, after
+In TUI/RPC, automatic continuation is evaluated only at `agent_settled`, after
 Pi has finished natural tool continuation, retries, and compaction. The
-extension rechecks that the same execution is active and incomplete, the
+extension rechecks that the same execution is active with open tasks, the
 session is idle, and neither pending input nor compaction owns continuation.
 Each eligible settled cycle can send at most one hidden custom message with
-the current execution rules and remaining VC checklist. Tool `turn_end`
-events only update progress; they never prequeue goal-wait reminders.
-
-No-progress and literal `waiting for` counters advance only on eligible
-settled cycles. Real marker progress resets both; thresholds remain 3 and 6.
-User interruption and final model errors also pause continuation. Genuine
-interactive/RPC user input or `/plans-execute` can resume a paused active
-execution without losing verified VCs; extension input cannot unpause it.
-New-plan handoffs and the `execute_plan` tool still require explicit approval.
-Completion, stop, and session replacement invalidate the extension's wake
-identity without clearing user or other-extension queues. Print/JSON
-single-shot sessions keep VC tracking and completion but never auto-wake;
+the current execution rules. Tool `turn_end` events only update usage; they
+never prequeue continuation reminders. The stall watchdog counts settled
+cycles without task-state change (threshold 3) and pauses instead of waking;
+user interruption and final model errors pause too. Genuine interactive/RPC
+user input or `/plans-execute` resumes a paused active execution without
+losing task progress; extension input cannot unpause it. New-plan handoffs
+and the `execute_plan` tool still require explicit approval. Print/JSON
+single-shot sessions keep task tracking and completion but never auto-wake;
 use RPC for persistent headless execution.
 
-### Post-Execution Continuation
-
-When execution completes in an interactive session, the completion message attaches a goal-running continuation block and triggers a new agent turn so the model can enter the implementation-review loop immediately. The interactive-only trigger keeps headless sessions silent (no unconsented subagent cost). The same behavior applies on both completion call sites (the normal `turn_end` completion and the `restoreFromSession` recovery path).
-
-The agent then asks two `ask_choice` questions (each single-question, `autoComplete: false`) to configure the implementation-review loop:
-
-1. **Termination condition** (questionId `termination-condition`, recommended first: goal wait) — options: 1. goal wait: continue until no unpassed VCs remain (auto-continue each round) 2. until no high-severity finding (hard cap 5 rounds) 3. 1 round 4. 2 rounds 5. 3 rounds.
-2. **Reviewer count** (questionId `impl-review-reviewer-count`, `allowOther: false`, pure digit labels `1`/`2`/`3`, recommended first): "How many concurrent reviewers should each implementation-review round use?" The recommended default follows the run's skill: `plan-big` / `plan-with-refs` → 3, others → 1.
-
-Both answers persist TOGETHER in one `plans record-checkpoint` (`transition: "implementation-review-configured"`, `terminationCondition` + `reviewerCount`). Each refinement round calls `refine` with `role: "reviewer", target: "implementation", reviewers: <configured reviewerCount>`; an omitted `reviewers` falls back to the run's configured `reviewerCount` from the checkpoint, so restarts and worktree migrations never silently revert 2/3 to 1. Each round accepts findings on evidence, applies fixes, re-runs relevant tests, and records progress. The hard cap is 5 rounds regardless of the chosen termination condition. Multi-reviewer rounds (2 or 3) consolidate like big-plan rounds: merge and dedupe findings into one `PLAN_vN_reviewer_comments.md`, keep each finding's source reviewer, severity, evidence, and disposition, and surface at most five high-priority findings. Crash recovery: if the process dies after one or both answers were recorded in `decisions.jsonl` but before the combined write, `/resume-plans` rebuilds the answered configuration from the ledger, asks only the missing question(s), and then performs the single combined write (the re-ask guard rejects duplicate configuration writes while the fields are already set).
-- Round audit trail: `decisions.jsonl`, `subagents.jsonl`, and `pi-plans-ameliorate` entries (one at goal start, then one per round) carry `currentRound` for post-hoc verification.
-- Headless sessions skip the prompt entirely; no `pi-plans-ameliorate` entry is appended.
-
 `refine` records each round and lane outcome durably (successful outputs are persisted to run-state files before the tool result returns) and accepts `resumeRoundId` to resume an interrupted round lane-by-lane: completed lanes are reused from their persisted outputs and never re-run; a round id is never reused across plan versions.
 
 ## Resuming (`/resume-plans`)
 
-After a restart or in a fresh session, `/resume-plans` (interactive only) restores the repository's working plan in the current session: the unfinished active run wins; otherwise a unique candidate resumes directly and multiple candidates get a chooser. It resumes unfinished planning (re-asks the pending question with the same `questionId`, never re-asks answered decisions), reviewing (resumes interrupted rounds via `refine resumeRoundId`, consolidates completed ones), execution (durable approval: unchanged plan digest keeps the authorization — a changed HEAD re-verifies old VCs first; legacy runs without checkpoints must re-approve), and the implementation-review loop (asks the termination condition and reviewer count only when they were never chosen — answered decisions are rebuilt from the ledger, never re-asked). While the loop is live, the pi-plans panel stays alive as a compact impl-review box (round count, reviewer count or "config pending", termination condition) and the status line mirrors it; once the checkpoint phase flips to `completed` the panel unregisters and the status line shows `(done)`. Linked worktrees share candidates; cross-worktree resumes confirm, copy artifacts without overwriting, reset approval and VC validity, and restart round counts. Record semantic boundaries with `plans record-checkpoint` (`plan-written`, `review-consolidated`, `implementation-review-configured`, `implementation-round-finished`, `completed` with evidence).
+After a restart or in a fresh session, `/resume-plans` (interactive only) restores the repository's working plan in the current session: the unfinished active run wins; otherwise a unique candidate resumes directly and multiple candidates get a chooser. It resumes unfinished planning (re-asks the pending question with the same `questionId`, never re-asks answered decisions), reviewing (resumes interrupted rounds via `refine resumeRoundId`, consolidates completed ones), and execution (durable approval: unchanged plan digest keeps the authorization — a changed HEAD re-opens previously closed tasks for re-verification; an unverifiable approval HEAD behaves the same; legacy runs without checkpoints must re-approve; v0.6.0 delegated-executor orphans require a fresh handoff approval; a legacy `implementation-review` phase maps to done — its historical acceptance stands). Linked worktrees share candidates; cross-worktree resumes confirm, copy artifacts without overwriting, reset approval and VC validity, and restart round counts. Record semantic boundaries with `plans record-checkpoint` (`plan-written`, `review-consolidated`, `completed` with evidence).
 
-`refine` accepts a `target` parameter (`"plan"` default, `"implementation"` for the post-execution loop). The implementation brief anchors findings to the plan's goals and acceptance criteria, explicitly assesses delivery maturity (MVP-only vs. long-term refinement: stopgaps, missing tests, technical debt, production readiness), and tags out-of-scope improvements as low severity.
+`refine` reviews the plan text (the v0.6.0 `target: "implementation"` post-execution loop is gone; the independent completion auditor now gates delivery).
 
 ## Red Flags
 
@@ -186,9 +173,9 @@ Stop and return to the workflow if any of these happen:
 - implementing before the approved execution handoff;
 - 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;
+- 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;
 - accepting vague answers that contradict repo or reference evidence;
-- treating a reviewer or criticizer as authority instead of evidence;
+- treating a reviewer as authority instead of evidence;
 - offering Auto-complete for execution, install, deploy, merge, push, or destructive cleanup approval.