pi-plans 0.5.7 → 0.7.0

package/tools/execute-plan.ts

@@ -1,6 +1,9 @@
 /**
- * `execute_plan` tool — the execution handoff. On explicit user approval (no
- * Auto-complete) the extension enters execution mode with checklist tracking.
+ * `execute_plan` tool — the execution handoff (v0.6.1). On explicit user
+ * approval (no Auto-complete) the extension enters task-tree execution mode:
+ * progress flows through `plans_update_task`, the dashboard tracks every
+ * task, and the completion auditor gates the final pass. Legacy I-### plans
+ * parse through the fallback with an upgrade notice.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -15,9 +18,11 @@ import {
 } from "../src/exec.ts";
 import { disableAutoComplete } from "../src/autocomplete.ts";
 import { isAutoApproveEnabled } from "../src/auto-approve.ts";
-import { latestPlanVersion, parseChecklist, parseImplItems } from "../src/plan.ts";
-import { normalizeWorkdir, readActive } from "../src/state.ts";
-import { resolveActiveRun } from "../src/run-context.ts";
+import { checklistHeaderName, latestPlanVersion, lintPlanTasks, parseChecklist, parsePlanTasks } from "../src/plan.ts";
+import { normalizeWorkdir, type RunSummary } from "../src/state.ts";
+import { bindRun } from "../src/run-context.ts";
+import { executionCandidates, resolveCommandRun } from "../src/run-picker.ts";
+import { resolveUiLanguage } from "../src/ui-language.ts";
 
 
 const ExecutePlanParams = Type.Object({
@@ -39,23 +44,30 @@ export async function executeHandoff(
 	ctx: ExtensionContext,
 	planPathArg?: string,
 	workdirArg?: string,
+	_signal?: AbortSignal,
 ): Promise<HandoffOutcome> {
 	const workdir = normalizeWorkdir(workdirArg ?? ctx.cwd);
 
 	let planPath: string | null = null;
+	let chosenRun: RunSummary | null = null;
 	if (planPathArg) {
 		planPath = path.resolve(workdir, planPathArg.replace(/^@/, ""));
 	} else {
-		const active = resolveActiveRun(ctx.sessionManager, workdir);
-		if (!active) {
+		// v0.6.0 (R-3): pick the run explicitly when several execution
+		// candidates coexist; binding-first, single candidate stays direct.
+		chosenRun = await resolveCommandRun(
+			{ cwd: workdir, sessionManager: ctx.sessionManager, ui: ctx.ui },
+			{ candidates: executionCandidates(workdir), title: "Execute which run?" },
+		);
+		if (!chosenRun) {
 			return {
 				status: "error",
-				message: "No plan path given and no active planning run found. Pass planPath or start a run first.",
+				message: "No plan path given and no executable planning run found. Pass planPath or start a run first.",
 			};
 		}
-		const latest = latestPlanVersion(active.artifact_dir);
+		const latest = latestPlanVersion(chosenRun.artifact_dir);
 		if (!latest) {
-			return { status: "error", message: `No PLAN_vN.md found in ${active.artifact_dir}` };
+			return { status: "error", message: `No PLAN_vN.md found in ${chosenRun.artifact_dir}` };
 		}
 		planPath = latest.path;
 	}
@@ -68,10 +80,28 @@ export async function executeHandoff(
 	if (items.length === 0) {
 		return {
 			status: "error",
-			message: `${planPath} has no parsable \`## Verifier Checklist\` with \`- [ ] \`VC-###\` ...\` items. Fix the plan before execution.`,
+			message: `${planPath} has no parsable \`## Verification Checks\` (or legacy \`## Verifier Checklist\`) with \`- [ ] \`VC-###\` ...\` items. Fix the plan before execution.`,
+		};
+	}
+	const planTasks = parsePlanTasks(planText);
+	if (planTasks.tasks.length === 0) {
+		return {
+			status: "error",
+			message: `${planPath} has no parsable tasks: add a \`## Tasks\` section (\`- \`Task-1\`: title — deps: …; files: …; wave: 1\`).`,
 		};
 	}
-	const implItems = parseImplItems(planText);
+	// I-001/R-001: task-tree consistency is advisory while planning and
+	// hard-rejected at this gate. Legacy I-### fallback plans are exempt
+	// (their shape predates the microsyntax).
+	if (!planTasks.legacy) {
+		const lint = lintPlanTasks(planText);
+		if (lint !== null) {
+			return {
+				status: "error",
+				message: `${planPath} failed the task-tree consistency gate; fix these before execution:\n${lint}`,
+			};
+		}
+	}
 
 	disableAutoComplete(ctx, "execution handoff");
 	// I-004/D-019: PI_PLANS_AUTO_APPROVE=1 short-circuits the confirm BEFORE
@@ -85,28 +115,40 @@ export async function executeHandoff(
 		};
 	}
 
+	const legacyPlan = planTasks.legacy || checklistHeaderName(planText) === "Verifier Checklist";
+
 	let approved: boolean;
 	if (autoApprove) {
 		approved = true;
 	} else {
+		const lang = resolveUiLanguage(workdir);
 		const preview = items.map((item) => `- ${item.done ? "☑" : "☐"} ${item.id}`).join("\n");
+		const legacyNote = legacyPlan
+			? (lang === "zh"
+				? "\n\n注意：该计划使用旧版 I-### 格式，将以兼容映射执行；建议在下次修订时升级为 ## Tasks 新格式。"
+				: "\n\nNote: this plan uses the legacy I-### format and executes through the compatibility mapping; upgrade it to the ## Tasks format at the next revision.")
+			: "";
 		approved = await ctx.ui.confirm(
 			"Execute this plan now?",
-			`${planPath}\n${items.length} verifier item(s):\n${preview}\n\nExecution mode enables write access and tracks [DONE:VC-xxx] progress.`,
+			`${planPath}\n${items.length} verification check(s) over ${planTasks.tasks.length} task(s):\n${preview}${legacyNote}\n\nExecution mode enables write access; task progress is reported with the plans_update_task tool and gated by the completion auditor.`,
 		);
 	}
 	if (!approved) {
 		return { status: "declined", message: "User declined execution. Stay in planning; ask how to proceed.", planPath };
 	}
 
-	await startExecution(getCurrentApi(), ctx, planPath, items, implItems);
-	const scopeNote = implItems.length ? ` Tracking ${implItems.length} implementation item(s).` : "";
+	// Attribute the handoff to the picked run before any state transition so
+	// the approval checkpoint and status flip land on the run the user chose.
+	if (chosenRun) bindRun(ctx.sessionManager, workdir, chosenRun.run_id);
+
+	await startExecution(ctx, { planPath, planTasks, items });
 	const autoNote = autoApprove ? "[auto-approve] " : "";
+	const legacyNote = legacyPlan ? " Legacy I-### mapping active; upgrade the plan at the next revision." : "";
 	return {
 		status: "executing",
 		planPath,
 		itemCount: items.length,
-		message: `${autoNote}Execution approved. ${items.length} verifier item(s) queued; implement in dependency order and mark verified items with [DONE:VC-xxx].${scopeNote}`,
+		message: `${autoNote}Execution approved. ${planTasks.tasks.length} task(s) queued in wave order; report progress with the plans_update_task tool (status + evidence); the completion auditor verifies every check before the run completes.${legacyNote}`,
 	};
 }
 
@@ -115,35 +157,23 @@ export async function executeCommand(ctx: ExtensionContext, planPathArg?: string
 	const activeExecution = getExecution();
 	const planPath = planPathArg ? path.resolve(ctx.cwd, planPathArg.replace(/^@/, "")) : activeExecution?.planPath;
 	if (activeExecution && planPath && path.resolve(activeExecution.planPath) === path.resolve(planPath)) {
-		const resumed = resumeActiveExecution(getCurrentApi(), ctx);
+		const resumed = resumeActiveExecution(ctx);
 		return {
 			status: "executing",
 			planPath,
 			itemCount: activeExecution.items.length,
-			message: resumed ? "Execution resumed; verified progress preserved." : "This plan is already executing.",
+			message: resumed ? "Execution resumed; task progress preserved." : "This plan is already executing.",
 		};
 	}
 	return executeHandoff(ctx, planPathArg);
 }
 
-// The tool registers with the ExtensionAPI in scope; keep a module-level
-// reference so the shared handoff helper can reach appendEntry/sendMessage.
-let currentApi: ExtensionAPI | null = null;
-export function setCurrentApi(api: ExtensionAPI): void {
-	currentApi = api;
-}
-function getCurrentApi(): ExtensionAPI {
-	if (!currentApi) throw new Error("execute_plan used before extension initialization");
-	return currentApi;
-}
-
-export function registerExecutePlanTool(pi: ExtensionAPI): void {
-	setCurrentApi(pi);
-	pi.registerTool({
+export function registerExecutePlanTool(ext: ExtensionAPI): void {
+	ext.registerTool({
 		name: "execute_plan",
 		label: "Execute Plan",
 		description:
-			"Execution handoff for an accepted plan. Asks the user for explicit approval (never auto-completed), then enters plan-execution mode: the extension injects the remaining Verifier Checklist every turn, tracks [DONE:VC-xxx] markers, and completes when every item passes. Only call after the user chose 'Execute this plan now' at the handoff question.",
+			"Execution handoff for an accepted plan. Asks the user for explicit approval (never auto-completed), then enters task-tree execution mode: every task's progress is reported via the plans_update_task tool (status + evidence), the task dashboard tracks the tree (Ctrl+Shift+T expands it), and an independent completion auditor verifies the verification checks before the run completes. Legacy I-### plans parse through the compatibility mapping with an upgrade notice. When several runs with plans exist, a run-picker form selects the target run first. Only call after the user chose 'Execute this plan now' at the handoff question.",
 		promptSnippet: "Hand an accepted plan off to the tracked execution loop",
 		parameters: ExecutePlanParams,
 

package/tools/graph-aware-file-tools.ts

@@ -326,6 +326,7 @@ function createGraphWriteTool(cwd: string) {
 				};
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			// Delegated executor children bypass DB-first staging (see read tool).
 			if (mode === "off") return stage(null);
 			if (mode === "config-unavailable") return stage("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);
@@ -375,6 +376,7 @@ function createGraphEditTool(cwd: string) {
 				};
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			// Delegated executor children bypass DB-first staging (see read tool).
 			if (mode === "off") return stage(null);
 			if (mode === "config-unavailable") return stage("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);
@@ -445,9 +447,9 @@ export function createGraphAwareFileTools(cwd: string) {
 	return tools;
 }
 
-export function registerGraphAwareFileTools(pi: ExtensionAPI, cwd = process.cwd()): void {
+export function registerGraphAwareFileTools(ext: ExtensionAPI, cwd = process.cwd()): void {
 	const tools = createGraphAwareFileTools(cwd);
-	pi.registerTool(tools.read);
-	pi.registerTool(tools.write);
-	pi.registerTool(tools.edit);
+	ext.registerTool(tools.read);
+	ext.registerTool(tools.write);
+	ext.registerTool(tools.edit);
 }

package/tools/plans.ts

@@ -8,9 +8,6 @@ import { lintPlanIntoNotices } from "../src/state.ts";
 import { getExecution, markPrePlanCompactPending, refreshUiLanguage } from "../src/exec.ts";
 import { loadVccSettings, scaffoldVccSettings } from "../src/compaction.ts";
 import {
-	applyCompleted,
-	applyImplementationReviewConfigured,
-	applyImplementationRoundFinished,
 	applyPlanWritten,
 	applyReviewConsolidated,
 	createCheckpoint,
@@ -43,11 +40,12 @@ import {
 	setRefsRoot,
 	setRunStatus,
 	setRole,
-	showConfig,
+	showStateView,
 	startRun,
 	StateError,
 	VALID_RUN_STATUSES,
 } from "../src/state.ts";
+import { messaging } from "../src/messaging.ts";
 
 const PlansParams = Type.Object({
 	action: StringEnum(
@@ -77,19 +75,25 @@ const PlansParams = Type.Object({
 	requestText: Type.Optional(Type.String({ description: "start-run: original user request text" })),
 	tag: Type.Optional(Type.String({ description: "set-language: BCP47 tag, e.g. zh-Hans, en" })),
 	languageSource: Type.Optional(StringEnum(["user", "auto"] as const)),
-	artifactRoot: Type.Optional(Type.String({ description: "set-artifact-root: planning docs root, e.g. ./docs/pi-plans" })),
+	artifactRoot: Type.Optional(Type.String({ description: "set-artifact-root: planning docs root, e.g. ./.git/pi-plans/plans" })),
 	artifactRootSource: Type.Optional(StringEnum(["user", "auto"] as const)),
 	refsRoot: Type.Optional(Type.String({ description: "set-refs-root: reference downloads root, e.g. .git/pi-plans/refs" })),
 	refsRootSource: Type.Optional(StringEnum(["user", "auto"] as const)),
 	enabled: Type.Optional(Type.Boolean({ description: "set-graph-enabled: enable/disable the code graph" })),
 	message: Type.Optional(Type.String({ description: "final-commit: commit message body" })),
-	role: Type.Optional(StringEnum(["reviewer", "criticizer"] as const)),
+	role: Type.Optional(StringEnum(["reviewer"] as const)),
 	mode: Type.Optional(StringEnum(["delegated-subagent", "current-session"] as const)),
 	modelSelector: Type.Optional(
-		Type.String({ description: "set-role: exact provider/model selector, or 'inherit' to reset to inherited" }),
+		Type.String({ description: "set-role: exact provider/model selector; 'inherit' resets BOTH the selector and the confirmation" }),
+	),
+	thinkingLevel: Type.Optional(
+		StringEnum(["default", "off", "minimal", "low", "medium", "high", "xhigh", "max"] as const, {
+			description:
+				"set-role: reviewer subagent thinking level in the GLOBAL config; 'default' (null) omits --thinking so the child pi resolves its own default chain; changing modelSelector without this resets the level",
+		}),
 	),
 	confirmed: Type.Optional(
-		Type.Boolean({ description: "set-role: stamp confirmed_at=now (used by the first-use confirmation flow)" }),
+		Type.Boolean({ description: "set-role: stamp confirmed_at=now; requires an exact selector for delegated-subagent" }),
 	),
 	resetConfirmation: Type.Optional(Type.Boolean({ description: "set-role: clear confirmed_at to re-ask" })),
 	runId: Type.Optional(Type.String()),
@@ -121,7 +125,7 @@ const PlansParams = Type.Object({
 	),
 	subagent: Type.Optional(
 		Type.Object({
-			role: StringEnum(["reviewer", "criticizer", "ref-analyst"] as const),
+			role: StringEnum(["reviewer", "ref-analyst"] as const),
 			name: Type.String(),
 			model: Type.Optional(Type.String()),
 			sessionDir: Type.Optional(Type.String()),
@@ -130,41 +134,16 @@ const PlansParams = Type.Object({
 	checkpoint: Type.Optional(
 		Type.Object({
 			/** Whitelisted semantic transition (I-003). State-machine validated; approval cannot be forged here. */
-			transition: StringEnum(
-				[
-					"plan-written",
-					"review-consolidated",
-					"implementation-review-configured",
-					"implementation-round-finished",
-					"completed",
-				] as const,
-			),
+			transition: StringEnum(["plan-written", "review-consolidated"] as const),
 			/** plan-written: absolute or workdir-relative PLAN_vN.md path. */
 			planPath: Type.Optional(Type.String()),
 			/** review-consolidated: round id + optional disposition artifact (run-dir relative). */
 			roundId: Type.Optional(Type.String()),
 			dispositionArtifact: Type.Optional(Type.String()),
-			/** implementation-review-configured: the serialized termination condition chosen by the user. */
-			terminationCondition: Type.Optional(Type.String()),
-			/** implementation-review-configured: concurrent reviewers per round (1-3);
-			 * omit to keep the skill-level default (plan-big / plan-with-refs → 3, others → 1). */
-			reviewerCount: Type.Optional(Type.Integer({ minimum: 1, maximum: 3 })),
-			/** completed: non-empty evidence that the termination condition is satisfied. */
-			evidence: Type.Optional(Type.String()),
 		}),
 	),
 });
 
-// Module-level reference so the start-run action can append a session entry
-// (pi-plans-run-start) at the moment the planning run begins. The ExtensionAPI
-// itself is not in scope for `startRun`, mirroring `setCurrentApi` in
-// tools/execute-plan.ts.
-let runStartAppender: ((runId: string, artifactDir: string) => void) | null = null;
-
-export function setRunStartAppender(appender: ((runId: string, artifactDir: string) => void) | null): void {
-	runStartAppender = appender;
-}
-
 /** plans action final-commit: gate on code-graph drift (zero pending +
  *  invariants (a)/(b) clean), then `git add -A` and commit the plan delivery.
  *  A clean tree is a safe no-op. Returns a machine-readable result. */
@@ -238,13 +217,10 @@ export function recordCheckpointTransition(
 	workdir: string,
 	runIdArg: string | undefined,
 	checkpoint: {
-		transition: "plan-written" | "review-consolidated" | "implementation-review-configured" | "implementation-round-finished" | "completed";
+		transition: "plan-written" | "review-consolidated";
 		planPath?: string;
 		roundId?: string;
 		dispositionArtifact?: string;
-		terminationCondition?: string;
-		reviewerCount?: number;
-		evidence?: string;
 	},
 ): WorkflowCheckpoint {
 	const runId =
@@ -270,33 +246,15 @@ export function recordCheckpointTransition(
 				applyReviewConsolidated(cp, checkpoint.roundId!, checkpoint.dispositionArtifact),
 			);
 		}
-		case "implementation-review-configured": {
-			if (!checkpoint.terminationCondition) {
-				throw new StateError("implementation-review-configured requires terminationCondition");
-			}
-			return mutateCheckpoint(workdir, runId, (cp) =>
-				applyImplementationReviewConfigured(cp, checkpoint.terminationCondition!, checkpoint.reviewerCount),
-			);
-		}
-		case "implementation-round-finished": {
-			return mutateCheckpoint(workdir, runId, (cp) => applyImplementationRoundFinished(cp));
-		}
-		case "completed": {
-			if (!checkpoint.evidence) throw new StateError("completed requires evidence");
-			return mutateCheckpoint(workdir, runId, (cp) => applyCompleted(cp, checkpoint.evidence!));
-		}
 	}
 }
 
-export function registerPlansTool(pi: ExtensionAPI): void {
-	setRunStartAppender((runId, artifactDir) => {
-		pi.appendEntry("pi-plans-run-start", { runId, artifactDir });
-	});
-	pi.registerTool({
+export function registerPlansTool(ext: ExtensionAPI): void {
+	ext.registerTool({
 		name: "plans",
 		label: "Plans",
 		description:
-			"Manage pi-plans planning state in the target workspace: init/show config, set language and planning docs root plus reviewer/criticizer roles and the code-graph enabled flag, start planning runs, record decisions/refs/subagents, and update run status. State lives in .git/pi_plans/ inside the resolved git common dir. Actions: init, show, set-language, set-artifact-root, set-refs-root, set-graph-enabled, set-role, start-run, set-status, final-commit, record-decision, record-ref, record-subagent.",
+			"Manage pi-plans planning state in the target workspace: init/show config, set language and planning docs root plus the reviewer role and the code-graph enabled flag, start planning runs, record decisions/refs/subagents, and update run status. Multiple concurrent runs per workdir are supported (registry-derived from runs/; sessions bind to their run). State lives in .git/pi-plans/ inside the resolved git common dir. Actions: init, show, set-language, set-artifact-root, set-refs-root, set-graph-enabled, set-role, start-run, set-status, final-commit, record-decision, record-ref, record-subagent.",
 		promptSnippet: "Manage pi-plans planning state, runs, and ledgers",
 		parameters: PlansParams,
 
@@ -317,10 +275,15 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 						break;
 					}
 					case "show": {
-						const config = showConfig(workdir);
-						const stateRoot = resolveStateRootOrNull(workdir);
-						result = { config, stateRoot };
-						if (config.graph_enabled === null) {
+						const view = showStateView(workdir);
+						result = {
+							config: view.config,
+							stateRoot: view.stateRoot,
+							reviewer: view.reviewer,
+							globalConfigPath: view.globalConfigPath,
+							notices: view.notices,
+						};
+						if (view.config.graph_enabled === null) {
 							result = {
 								...(result as Record<string, unknown>),
 								hint: "graph_enabled is null (never asked). Ask the user once via ask_choice, then persist with plans (action: set-graph-enabled, enabled: true|false).",
@@ -369,10 +332,17 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 							role: params.role,
 							mode: params.mode,
 							modelSelector: params.modelSelector,
+							thinkingLevel: params.thinkingLevel,
 							confirmed: params.confirmed,
 							resetConfirmation: params.resetConfirmation,
 						});
-						result = { config: updated.config, stateRoot: updated.stateRoot, notices: updated.notices };
+						result = {
+							global: updated.global,
+							globalRoot: updated.globalRoot,
+							notices: updated.notices,
+							config: updated.config,
+							stateRoot: updated.stateRoot,
+						};
 						break;
 					}
 					case "start-run": {
@@ -383,8 +353,11 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 							topic: params.topic,
 							skill: params.skill,
 							requestText: params.requestText,
+							// Append the run-start session entry with this call's ctx —
+							// never a registration-time capture (stale after session
+							// replacement).
 							onStart: (run) => {
-								runStartAppender?.(run.run_id, run.artifact_dir);
+								messaging().appendEntry("pi-plans-run-start", { runId: run.run_id, artifactDir: run.artifact_dir });
 							},
 						});
 						// I-002: attribute this session's work to the run it started.
@@ -454,3 +427,4 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 		},
 	});
 }
+