pi-plans 0.2.0 → 0.3.1

package/tools/plans.ts

@@ -6,6 +6,11 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { computeDrift } from "../src/code-graph/commands.ts";
+import { gitAddAllAndCommit } from "../src/code-graph/git.ts";
+import { loadGraphRuntime } from "../src/code-graph/runtime.ts";
+import { resolveCanonicalWorktree } from "../src/code-graph/paths.ts";
+import { Store } from "../src/code-graph/store.ts";
 import {
 	initState,
 	loadConfig,
@@ -15,7 +20,9 @@ import {
 	recordSubagent,
 	resolveStateRootOrNull,
 	setArtifactRoot,
+	setGraphEnabled,
 	setLanguage,
+	setRefsRoot,
 	setRunStatus,
 	setRole,
 	showConfig,
@@ -31,9 +38,12 @@ const PlansParams = Type.Object({
 			"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",
@@ -50,6 +60,10 @@ const PlansParams = Type.Object({
 	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" })),
 	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)),
 	mode: Type.Optional(StringEnum(["delegated-subagent", "current-session"] as const)),
 	modelSelector: Type.Optional(
@@ -88,7 +102,7 @@ const PlansParams = Type.Object({
 	),
 	subagent: Type.Optional(
 		Type.Object({
-			role: StringEnum(["reviewer", "criticizer"] as const),
+			role: StringEnum(["reviewer", "criticizer", "ref-analyst"] as const),
 			name: Type.String(),
 			model: Type.Optional(Type.String()),
 			sessionDir: Type.Optional(Type.String()),
@@ -106,6 +120,54 @@ export function setRunStartAppender(appender: ((runId: string, artifactDir: stri
 	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. */
+export async function finalCommit(
+	workdir: string,
+	message: string,
+): Promise<{
+	ok: boolean;
+	committed: string | null;
+	noop: boolean;
+	reason?: string;
+	drift?: unknown;
+}> {
+	const paths = resolveCanonicalWorktree(workdir);
+	const runtime = await loadGraphRuntime();
+	if (!runtime.status.sqliteAvailable) {
+		throw new StateError("final-commit requires node:sqlite (code graph unavailable)");
+	}
+	const store = new Store(
+		{ dbPath: paths.codeGraphDb, worktreeRoot: paths.worktreeRoot, gitCommonDir: paths.gitCommonDir },
+		runtime.runtime.sqlite,
+	);
+	try {
+		let drift: ReturnType<typeof computeDrift> | null = null;
+		try {
+			drift = computeDrift(store, paths.worktreeRoot);
+		} catch {
+			drift = null; // graph never initialized: fall through to plain commit
+		}
+		if (drift && (drift.pending.length > 0 || !drift.ok)) {
+			return {
+				ok: false,
+				committed: null,
+				noop: false,
+				reason: `graph drift dirty: ${drift.recommendation}`,
+				drift,
+			};
+		}
+		const head = gitAddAllAndCommit(paths.worktreeRoot, message);
+		if (!head) {
+			return { ok: true, committed: null, noop: true, reason: "nothing to commit — tree already clean" };
+		}
+		return { ok: true, committed: head, noop: false };
+	} finally {
+		store.close();
+	}
+}
+
 export function registerPlansTool(pi: ExtensionAPI): void {
 	setRunStartAppender((runId, artifactDir) => {
 		pi.appendEntry("pi-plans-run-start", { runId, artifactDir });
@@ -114,7 +176,7 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 		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, 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-role, start-run, set-status, 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 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.",
 		promptSnippet: "Manage pi-plans planning state, runs, and ledgers",
 		parameters: PlansParams,
 
@@ -126,12 +188,32 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 					case "init": {
 						const ensured = initState(workdir);
 						result = { config: ensured.config, stateRoot: ensured.stateRoot, notices: ensured.notices };
+						if (ensured.config.graph_enabled === null) {
+							result = {
+								...(result as Record<string, unknown>),
+								hint: "graph_enabled is null (never asked). Ask the user once via ask_choice whether to enable the code graph (recommended: yes for repos with an initialized graph; see references/state-and-config.md), then persist with plans (action: set-graph-enabled, enabled: true|false). This question does not count against the planning-question limit.",
+							};
+						}
 						break;
 					}
 					case "show": {
 						const config = showConfig(workdir);
 						const stateRoot = resolveStateRootOrNull(workdir);
 						result = { config, stateRoot };
+						if (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).",
+							};
+						}
+						break;
+					}
+					case "set-graph-enabled": {
+						if (typeof params.enabled !== "boolean") {
+							throw new StateError("set-graph-enabled requires enabled (boolean)");
+						}
+						const updated = setGraphEnabled(workdir, params.enabled);
+						result = { config: updated.config, stateRoot: updated.stateRoot, notices: updated.notices };
 						break;
 					}
 					case "set-language": {
@@ -150,6 +232,14 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 						result = { config: updated.config, stateRoot: updated.stateRoot, notices: updated.notices };
 						break;
 					}
+					case "set-refs-root": {
+						if (!params.refsRoot || !params.refsRootSource) {
+							throw new StateError("set-refs-root requires refsRoot and refsRootSource");
+						}
+						const updated = setRefsRoot(workdir, params.refsRoot, params.refsRootSource);
+						result = { config: updated.config, stateRoot: updated.stateRoot, notices: updated.notices };
+						break;
+					}
 					case "set-role": {
 						if (!params.role) throw new StateError("set-role requires role");
 						const updated = setRole(workdir, {
@@ -181,6 +271,11 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 						result = setRunStatus(workdir, params.runId, params.status);
 						break;
 					}
+					case "final-commit": {
+						if (!params.message) throw new StateError("final-commit requires message");
+						result = await finalCommit(workdir, params.message);
+						break;
+					}
 					case "record-decision": {
 						if (!params.runId || !params.decision) {
 							throw new StateError("record-decision requires runId and decision");

package/tools/refine.ts

@@ -15,13 +15,21 @@ import { Type } from "typebox";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadConfig, normalizeWorkdir, readActive, recordSubagent, resolveStateRootOrNull, StateError, type RoleConfig } from "../src/state.ts";
-import { buildCriticizerTask, buildReviewerTask, reviewerLanes } from "../src/refine-prompts.ts";
+import { buildCriticizerTask, buildImplementationCriticizerTask, buildImplementationReviewerTask, buildReviewerTask, reviewerLanes } from "../src/refine-prompts.ts";
+import { graphBlockForRefiner } from "../src/code-graph/prompts.ts";
 import { runPiSubagent, stripFrontmatter } from "../src/subagent.ts";
 import { RefineOverlayController, refineOverlayContext } from "../src/refine-ui.ts";
 
+
 const RefineParams = Type.Object({
 	role: StringEnum(["reviewer", "criticizer"] as const, { description: "Refinement role to run" }),
 	planPath: Type.String({ description: "Path to the PLAN_vN.md to review (absolute or relative to workdir)" }),
+	target: Type.Optional(
+		StringEnum(["plan", "implementation"] as const, {
+			description:
+				'Review target: "plan" (default) reviews the plan text; "implementation" reviews the implemented worktree against the plan\'s goals and acceptance criteria (post-execution amelioration).',
+		}),
+	),
 	focus: Type.Optional(Type.String({ description: "Specific concerns to direct the pass at" })),
 	reviewers: Type.Optional(
 		Type.Integer({
@@ -52,6 +60,7 @@ function setupRefinementExecution(
 	parentSignal: AbortSignal | undefined,
 	role: "reviewer" | "criticizer",
 	lanes: Array<{ id: string; label?: string }>,
+	modelLabel?: string,
 ) {
 	const controller = new AbortController();
 	const relayAbort = () => controller.abort();
@@ -59,7 +68,7 @@ function setupRefinementExecution(
 	else parentSignal?.addEventListener("abort", relayAbort, { once: true });
 
 	const overlay = ctx.mode === "tui" ? new RefineOverlayController(role, lanes, relayAbort) : undefined;
-	overlay?.open(refineOverlayContext(ctx));
+	overlay?.open(refineOverlayContext(ctx), modelLabel);
 
 	return {
 		signal: controller.signal,
@@ -83,7 +92,7 @@ export function registerRefineTool(pi: ExtensionAPI, baseDir: string): void {
 		name: "refine",
 		label: "Refine",
 		description:
-			"Run a reviewer or criticizer refinement round on a PLAN_vN.md via read-only Pi subagents. Reviewer: findings with IDs, severity, evidence, impact, fix, disposition. Criticizer: up to five adaptive questions. Use reviewers: 3 for the big-plan concurrent reviewer round. Refuses to spawn until the role's mode and model are confirmed in .git/pi_plans/config.json (ask via ask_choice, persist via the plans tool).",
+			"Run a reviewer or criticizer refinement round on a PLAN_vN.md (target=\"plan\", default) or on the implemented worktree (target=\"implementation\", post-execution amelioration) via read-only Pi subagents. Reviewer: findings with IDs, severity, evidence, impact, fix, disposition. Criticizer: up to five adaptive questions. Use reviewers: 3 for the big-plan concurrent reviewer round. Refuses to spawn until the role's mode and model are confirmed in .git/pi_plans/config.json (ask via ask_choice, persist via the plans tool).",
 		promptSnippet: "Run reviewer/criticizer plan-refinement rounds",
 		parameters: RefineParams,
 
@@ -120,15 +129,28 @@ export function registerRefineTool(pi: ExtensionAPI, baseDir: string): void {
 				}
 			};
 
+			const target = params.target ?? "plan";
+			const pickTask = (role: "reviewer" | "criticizer", lens: string | null): string => {
+				if (role === "reviewer") {
+					return target === "implementation"
+						? buildImplementationReviewerTask({ planText, planPath, lens, focus: params.focus, context: params.context })
+						: buildReviewerTask({ planText, planPath, lens, focus: params.focus, context: params.context });
+				}
+				return target === "implementation"
+					? buildImplementationCriticizerTask({ planText, planPath, focus: params.focus, context: params.context })
+					: buildCriticizerTask({ planText, planPath, focus: params.focus, context: params.context });
+			};
+
 			const systemPrompt = loadAgentPrompt(params.role);
+			const graphEnabled = config.graph_enabled === true;
+			const subagentTools = graphEnabled ? ["read", "grep", "find", "ls", "code_graph"] : undefined;
+			const graphPrompt = graphBlockForRefiner(graphEnabled);
 			const inheritModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
 			const model = roleConfig.model_selector ?? inheritModel;
+			const modelLabel = model ?? "inherit";
 
 			if (roleConfig.mode === "current-session") {
-				const task =
-					params.role === "reviewer"
-						? buildReviewerTask({ planText, planPath, lens: null, focus: params.focus, context: params.context })
-						: buildCriticizerTask({ planText, planPath, focus: params.focus, context: params.context });
+				const task = pickTask(params.role, null);
 				return {
 					content: [
 						{
@@ -136,19 +158,20 @@ export function registerRefineTool(pi: ExtensionAPI, baseDir: string): void {
 							text: `Role mode is current-session: perform the read-only ${params.role} pass yourself, in this session, following this brief. Do not spawn anything.\n\n${task}`,
 						},
 					],
-					details: { mode: "current-session", role: params.role, planPath },
+					details: { mode: "current-session", role: params.role, planPath, target },
 				};
 			}
 
 			if (params.role === "criticizer") {
 				const name = `${roleConfig.name_prefix}-criticizer-${Date.now().toString(36)}`;
-				const execution = setupRefinementExecution(ctx, signal, "criticizer", [{ id: name, label: "criticizer" }]);
+				const execution = setupRefinementExecution(ctx, signal, "criticizer", [{ id: name, label: "criticizer" }], modelLabel);
 				try {
 					const result = await runPiSubagent({
-						systemPrompt,
-						task: buildCriticizerTask({ planText, planPath, focus: params.focus, context: params.context }),
+						systemPrompt: `${systemPrompt}\n\n${graphPrompt}`,
+						task: pickTask("criticizer", null),
 						cwd: workdir,
 						model,
+						tools: subagentTools,
 						signal: execution.signal,
 						onProgress: (event) => execution.overlay?.update(name, event),
 					});
@@ -166,42 +189,64 @@ export function registerRefineTool(pi: ExtensionAPI, baseDir: string): void {
 								text: `${result.output}\n\n---\nAsk each criticizer question with ask_choice (one call per question, in the configured language), record every answer, then revise the plan only after every question has an answer.`,
 							},
 						],
-						details: { mode: "delegated-subagent", role: params.role, planPath, model: result.model ?? model },
+						details: { mode: "delegated-subagent", role: params.role, planPath, target, model: result.model ?? model },
 					};
 				} finally {
 					await execution.close();
 				}
 			}
 
-			// Reviewer round: 1 by default, 3 for the big-plan concurrent round.
 			const count = Math.min(3, Math.max(1, params.reviewers ?? 1));
 			const lanes = reviewerLanes(count);
 			const jobs = lanes.map((lane) => {
 				const name = `${roleConfig.name_prefix}-${active?.run_id ?? "adhoc"}-${lane.id}`;
-				const task = buildReviewerTask({ planText, planPath, lens: lane.lens, focus: params.focus, context: params.context });
+				const task = pickTask("reviewer", lane.lens);
 				return { lane, name, task };
 			});
 
+			// Per-plan amelioration round counter (post-execution loop auditability).
+			const roundsSlot = ctx.sessionManager as unknown as { __ameliorateRounds?: Map<string, number> };
+			const nextRound = (planPath: string): number => {
+				roundsSlot.__ameliorateRounds ??= new Map();
+				const round = (roundsSlot.__ameliorateRounds.get(planPath) ?? 0) + 1;
+				roundsSlot.__ameliorateRounds.set(planPath, round);
+				return round;
+			};
+
 			const execution = setupRefinementExecution(
 				ctx,
 				signal,
 				"reviewer",
 				jobs.map((job) => ({ id: job.lane.id, label: job.lane.id })),
+				modelLabel,
 			);
 			try {
 				const results = await Promise.all(
 					jobs.map(async (job) => {
 						try {
 							const result = await runPiSubagent({
-								systemPrompt,
+								systemPrompt: `${systemPrompt}\n\n${graphPrompt}`,
 								task: job.task,
 								cwd: workdir,
 								model,
+								tools: subagentTools,
 								signal: execution.signal,
 								onProgress: (event) => execution.overlay?.update(job.lane.id, event),
 							});
 							execution.overlay?.complete(job.lane.id, result);
 							record(job.name, result.ok ? result.model ?? model : null);
+							if (target === "implementation" && result.ok) {
+								try {
+									pi.appendEntry("pi-plans-ameliorate", {
+										planPath,
+										phase: "round",
+										currentRound: nextRound(planPath),
+										lane: job.lane.id,
+									});
+								} catch {
+									/* appendEntry is best-effort; audit trail survives in subagents.jsonl */
+								}
+							}
 							return { job, result };
 						} catch (error) {
 							record(job.name, null);
@@ -272,6 +317,7 @@ export function registerRefineTool(pi: ExtensionAPI, baseDir: string): void {
 				theme.fg("muted", count > 1 ? ` ×${count}` : "");
 			const short = args.planPath ? args.planPath.split("/").pop() : "";
 			if (short) text += theme.fg("dim", ` ${short}`);
+			if (args.target === "implementation") text += theme.fg("dim", "  (implementation)");
 			if (args.focus) text += `\n${theme.fg("dim", `  focus: ${args.focus.slice(0, 80)}`)}`;
 			return new Text(text, 0, 0);
 		},