taskplane 0.23.13 → 0.23.15

package/extensions/taskplane/agent-bridge-extension.ts

@@ -24,8 +24,9 @@
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@mariozechner/pi-ai";
-import { writeFileSync, mkdirSync, renameSync } from "fs";
-import { join } from "path";
+import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } from "fs";
+import { join, dirname } from "path";
+import { spawn as nodeSpawn } from "child_process";
 import { randomBytes } from "crypto";
 
 /**
@@ -156,4 +157,265 @@ export default function (pi: ExtensionAPI) {
 			}
 		},
 	});
+
+	// ── review_step Tool (TP-117) ─────────────────────────────────────
+	// Spawns a reviewer subprocess to evaluate work at step boundaries.
+	// The reviewer runs as a separate Pi process, writes feedback to
+	// .reviews/, and this tool returns the verdict to the worker.
+
+	/**
+	 * Resolve the Pi CLI entrypoint path (same logic as agent-host.ts).
+	 */
+	function resolvePiCli(): string {
+		const relPath = join("node_modules", "@mariozechner", "pi-coding-agent", "dist", "cli.js");
+		const candidates: string[] = [];
+		if (process.env.APPDATA) candidates.push(join(process.env.APPDATA, "npm", relPath));
+		const home = process.env.HOME || process.env.USERPROFILE || "";
+		if (home) {
+			candidates.push(join(home, "AppData", "Roaming", "npm", relPath));
+			candidates.push(join(home, ".npm-global", "lib", relPath));
+		}
+		candidates.push(join("/usr", "local", "lib", relPath));
+		for (const c of candidates) {
+			if (existsSync(c)) return c;
+		}
+		throw new Error("Cannot find Pi CLI entrypoint");
+	}
+
+	/**
+	 * Load the reviewer system prompt from base template + local override.
+	 */
+	function loadReviewerPrompt(): string {
+		const basePaths = [
+			process.env.APPDATA ? join(process.env.APPDATA, "npm", "node_modules", "taskplane", "templates", "agents", "task-reviewer.md") : "",
+			(process.env.HOME || process.env.USERPROFILE || "") ? join(process.env.HOME || process.env.USERPROFILE || "", "AppData", "Roaming", "npm", "node_modules", "taskplane", "templates", "agents", "task-reviewer.md") : "",
+		].filter(Boolean);
+		let basePrompt = "You are a code reviewer. Read the request and write your review to the specified output file.";
+		for (const p of basePaths) {
+			try {
+				if (!existsSync(p)) continue;
+				const raw = readFileSync(p, "utf-8");
+				const fmEnd = raw.indexOf("---", 4);
+				if (fmEnd > 0) { basePrompt = raw.slice(fmEnd + 3).trim(); break; }
+			} catch { continue; }
+		}
+		// Local override
+		const localPaths = [join(process.cwd(), ".pi", "agents", "task-reviewer.md"), join(process.cwd(), "agents", "task-reviewer.md")];
+		for (const p of localPaths) {
+			try {
+				if (!existsSync(p)) continue;
+				const raw = readFileSync(p, "utf-8");
+				const fmEnd = raw.indexOf("---", 4);
+				if (fmEnd > 0) {
+					const localBody = raw.slice(fmEnd + 3).trim();
+					if (localBody) basePrompt += "\n\n---\n\n## Project-Specific Guidance\n\n" + localBody;
+				}
+				break;
+			} catch { continue; }
+		}
+		return basePrompt;
+	}
+
+	/**
+	 * Spawn a reviewer Pi subprocess and wait for it to complete.
+	 * Returns the process exit code.
+	 */
+	function spawnReviewer(prompt: string, systemPrompt: string, cwd: string): Promise<number> {
+		return new Promise((resolve) => {
+			const cliPath = resolvePiCli();
+			const args = [
+				cliPath, "--mode", "rpc", "--no-session", "--no-extensions", "--no-skills",
+				"--tools", "read,write,edit,bash,grep,find,ls",
+				"--system-prompt", systemPrompt,
+			];
+			const proc = nodeSpawn(process.execPath, args, {
+				shell: false,
+				cwd,
+				stdio: ["pipe", "pipe", "pipe"],
+				env: { ...process.env },
+			});
+
+			// Send prompt and close stdin after delay
+			proc.stdin?.write(JSON.stringify({ type: "prompt", message: prompt }) + "\n");
+
+			// Watch for agent_end event to close stdin
+			let buf = "";
+			proc.stdout?.on("data", (chunk: Buffer) => {
+				buf += chunk.toString();
+				if (buf.includes('"agent_end"')) {
+					setTimeout(() => { try { proc.stdin?.end(); } catch {} }, 100);
+				}
+			});
+
+			proc.on("close", (code) => resolve(code ?? 1));
+			proc.on("error", () => resolve(1));
+
+			// Timeout: 10 minutes
+			setTimeout(() => { try { proc.kill("SIGTERM"); } catch {} }, 10 * 60 * 1000);
+		});
+	}
+
+	pi.registerTool({
+		name: "review_step",
+		label: "Review Step",
+		description:
+			"Spawn a reviewer agent to evaluate your work on a step. " +
+			"Returns APPROVE, REVISE, RETHINK, or UNAVAILABLE. " +
+			"Use at step boundaries based on the task's review level.",
+		promptSnippet: "review_step(step, type, baseline?) — spawn reviewer for a step",
+		promptGuidelines: [
+			"Call review_step at step boundaries based on the task's Review Level (from STATUS.md header).",
+			"Review Level 0: skip all reviews. Level 1: plan review. Level 2: plan + code review. Level 3: plan + code + test.",
+			"Skip reviews for Step 0 (Preflight) and the final documentation step.",
+			"For code reviews: capture HEAD commit before starting a step with `git rev-parse HEAD` and pass as baseline.",
+			"On REVISE: read the review file in .reviews/ for feedback, fix issues, then proceed.",
+			"On RETHINK: reconsider your approach.",
+		],
+		parameters: Type.Object({
+			step: Type.Number({ description: "Step number to review" }),
+			type: Type.Union(
+				[Type.Literal("plan"), Type.Literal("code")],
+				{ description: 'Review type: "plan" or "code"' },
+			),
+			baseline: Type.Optional(Type.String({
+				description: "Git commit SHA for code review diff baseline",
+			})),
+		}),
+		async execute(_toolCallId, params) {
+			const { step: stepNum, type: reviewType, baseline } = params;
+			const cwd = process.cwd();
+
+			// Find task folder and paths
+			const taskFolder = process.env.TASKPLANE_TASK_FOLDER || cwd;
+			const statusPath = join(taskFolder, "STATUS.md");
+			const reviewsDir = join(taskFolder, ".reviews");
+			if (!existsSync(reviewsDir)) mkdirSync(reviewsDir, { recursive: true });
+
+			// Read review counter from STATUS.md
+			let reviewCounter = 0;
+			try {
+				const statusContent = readFileSync(statusPath, "utf-8");
+				const rcMatch = statusContent.match(/\*\*Review Counter:\*\*\s*(\d+)/);
+				if (rcMatch) reviewCounter = parseInt(rcMatch[1]);
+			} catch { /* default 0 */ }
+
+			reviewCounter++;
+			const num = String(reviewCounter).padStart(3, "0");
+			const outputPath = join(reviewsDir, `R${num}-${reviewType}-step${stepNum}.md`);
+
+			// Find step name from PROMPT.md
+			let stepName = `Step ${stepNum}`;
+			try {
+				const promptFiles = [join(taskFolder, "PROMPT.md")];
+				for (const pf of promptFiles) {
+					if (!existsSync(pf)) continue;
+					const content = readFileSync(pf, "utf-8");
+					const stepMatch = content.match(new RegExp(`###\\s+Step\\s+${stepNum}[:\\s]+(.+)`));
+					if (stepMatch) { stepName = stepMatch[1].trim(); break; }
+				}
+			} catch { /* use default */ }
+
+			// Generate review request prompt
+			const promptPath = join(taskFolder, "PROMPT.md");
+			const projectName = process.env.TASKPLANE_PROJECT_NAME || "project";
+			const diffCmd = baseline ? `git diff ${baseline}..HEAD` : `git diff`;
+			const diffNamesCmd = baseline ? `git diff ${baseline}..HEAD --name-only` : `git diff --name-only`;
+
+			let reviewPrompt: string;
+			if (reviewType === "plan") {
+				reviewPrompt = [
+					`# Review Request: Plan Review`,
+					``,
+					`You are reviewing an implementation plan for a ${projectName} task.`,
+					`You have full tool access — use \`read\` to examine files and \`bash\` to run commands.`,
+					``,
+					`## Task Context`,
+					`- **Task PROMPT:** ${promptPath}`,
+					`- **Task STATUS:** ${statusPath}`,
+					`- **Step being planned:** Step ${stepNum}: ${stepName}`,
+					``,
+					`## Instructions`,
+					`1. Read the PROMPT.md for full requirements`,
+					`2. Read STATUS.md for progress so far`,
+					`3. Evaluate the plan for this step`,
+					``,
+					`## Output`,
+					`Write your review to: \`${outputPath}\``,
+				].join("\n");
+			} else {
+				reviewPrompt = [
+					`# Review Request: Code Review`,
+					``,
+					`You are reviewing code changes for a ${projectName} task.`,
+					`You have full tool access — use \`read\` to examine files and \`bash\` to run commands.`,
+					``,
+					`## Task Context`,
+					`- **Task PROMPT:** ${promptPath}`,
+					`- **Task STATUS:** ${statusPath}`,
+					`- **Step reviewed:** Step ${stepNum}: ${stepName}`,
+					...(baseline ? [`- **Baseline commit:** ${baseline}`] : []),
+					``,
+					`## Instructions`,
+					`1. Run \`${diffNamesCmd}\` to see changed files`,
+					`2. Run \`${diffCmd}\` for the full diff`,
+					`3. Read changed files for context`,
+					``,
+					`## Output`,
+					`Write your review to: \`${outputPath}\``,
+				].join("\n");
+			}
+
+			try {
+				const systemPrompt = loadReviewerPrompt();
+				const exitCode = await spawnReviewer(reviewPrompt, systemPrompt, cwd);
+
+				// Update review counter in STATUS.md
+				try {
+					const status = readFileSync(statusPath, "utf-8");
+					const updated = status.replace(/\*\*Review Counter:\*\*\s*\d+/, `**Review Counter:** ${reviewCounter}`);
+					writeFileSync(statusPath, updated);
+				} catch { /* best effort */ }
+
+				// Read review output and extract verdict
+				if (existsSync(outputPath)) {
+					const reviewContent = readFileSync(outputPath, "utf-8");
+					const verdictMatch = reviewContent.match(/###?\s*Verdict[:\s]*(APPROVE|REVISE|RETHINK)/i);
+					let verdict = verdictMatch ? verdictMatch[1].toUpperCase() : "UNKNOWN";
+					if (verdict === "UNKNOWN") {
+						const lower = reviewContent.toLowerCase();
+						if (lower.includes("approve") && !lower.includes("do not approve")) verdict = "APPROVE";
+						else if (lower.includes("revise") || lower.includes("changes requested")) verdict = "REVISE";
+						else if (lower.includes("rethink")) verdict = "RETHINK";
+					}
+
+					// Log review in STATUS.md execution log
+					try {
+						const status = readFileSync(statusPath, "utf-8");
+						const logEntry = `| ${new Date().toISOString().slice(0, 16).replace("T", " ")} | Review R${num} | ${reviewType} Step ${stepNum}: ${verdict} |\n`;
+						writeFileSync(statusPath, status.trimEnd() + "\n" + logEntry);
+					} catch { /* best effort */ }
+
+					const reviewFile = `.reviews/R${num}-${reviewType}-step${stepNum}.md`;
+					if (verdict === "APPROVE") {
+						return { content: [{ type: "text" as const, text: `APPROVE` }], details: undefined };
+					} else if (verdict === "REVISE") {
+						const summaryMatch = reviewContent.match(/###?\s*Summary[:\s]*([\s\S]*?)(?=###|$)/i);
+						const details = summaryMatch ? summaryMatch[1].trim().slice(0, 500) : "See review file.";
+						return { content: [{ type: "text" as const, text: `REVISE: ${details}\n\nFull review: ${reviewFile}` }], details: undefined };
+					} else if (verdict === "RETHINK") {
+						return { content: [{ type: "text" as const, text: `RETHINK — reconsider approach. See ${reviewFile}` }], details: undefined };
+					} else {
+						return { content: [{ type: "text" as const, text: `Review complete (verdict unclear). See ${reviewFile}` }], details: undefined };
+					}
+				} else {
+					return { content: [{ type: "text" as const, text: `UNAVAILABLE — reviewer exited (code ${exitCode}) but produced no output.` }], details: undefined };
+				}
+			} catch (err) {
+				return {
+					content: [{ type: "text" as const, text: `UNAVAILABLE — reviewer failed: ${err instanceof Error ? err.message : String(err)}` }],
+					details: undefined,
+				};
+			}
+		},
+	});
 }

package/extensions/taskplane/execution.ts

@@ -2938,6 +2938,83 @@ export function buildAgentIdFromLane(
  *
  * @since TP-102
  */
+/**
+ * Parse an agent .md file: extract frontmatter and body.
+ * Returns null if file doesn't exist or is malformed.
+ * @since TP-117
+ */
+function parseAgentFile(filePath: string): { fm: Record<string, string>; body: string } | null {
+	try {
+		if (!existsSync(filePath)) return null;
+		const raw = readFileSync(filePath, "utf-8");
+		const fmEnd = raw.indexOf("---", 4);
+		if (fmEnd < 0) return { fm: {}, body: raw.trim() };
+		const fmBlock = raw.slice(4, fmEnd).trim();
+		const fm: Record<string, string> = {};
+		for (const line of fmBlock.split("\n")) {
+			const m = line.match(/^([\w-]+)\s*:\s*(.+)/);
+			if (m) fm[m[1]] = m[2].trim();
+		}
+		return { fm, body: raw.slice(fmEnd + 3).trim() };
+	} catch { return null; }
+}
+
+/**
+ * Load the base agent prompt from the taskplane package's templates/ directory.
+ * Resolves the package root via well-known npm global paths.
+ * @since TP-117
+ */
+function loadBaseAgentPrompt(agentName: string): string {
+	const relPath = join("node_modules", "taskplane", "templates", "agents", `${agentName}.md`);
+	const candidates: string[] = [];
+
+	// Global npm paths
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (process.env.APPDATA) candidates.push(join(process.env.APPDATA, "npm", relPath));
+	if (home) {
+		candidates.push(join(home, "AppData", "Roaming", "npm", relPath));
+		candidates.push(join(home, ".npm-global", "lib", relPath));
+	}
+	candidates.push(join("/usr", "local", "lib", relPath));
+	candidates.push(join("/opt", "homebrew", "lib", relPath));
+
+	// Dynamic: npm root -g
+	try {
+		const result = spawnSync("npm", ["root", "-g"], { encoding: "utf-8", timeout: 5000, shell: true });
+		if (result.stdout?.trim()) {
+			candidates.push(join(result.stdout.trim(), "taskplane", "templates", "agents", `${agentName}.md`));
+		}
+	} catch { /* ignore */ }
+
+	for (const p of candidates) {
+		const def = parseAgentFile(p);
+		if (def?.body) return def.body;
+	}
+	return "";
+}
+
+/**
+ * Load local project agent prompt from .pi/agents/ or agents/ directory.
+ * Supports standalone mode (local replaces base entirely).
+ * @since TP-117
+ */
+function loadLocalAgentPrompt(stateRoot: string, agentName: string): string {
+	const paths = [
+		join(stateRoot, ".pi", "agents", `${agentName}.md`),
+		join(stateRoot, "agents", `${agentName}.md`),
+	];
+	for (const p of paths) {
+		const def = parseAgentFile(p);
+		if (def) {
+			// standalone: true → use local as-is (body only, replaces base)
+			if (def.fm.standalone === "true") return def.body;
+			// Otherwise return body as project-specific guidance to append
+			if (def.body) return def.body;
+		}
+	}
+	return "";
+}
+
 export function resolveRuntimeStateRoot(
 	repoRoot: string,
 	workspaceRoot?: string,
@@ -2987,16 +3064,20 @@ export async function executeLaneV2(
 	const opId = resolveOperatorId(config);
 	const agentIdPrefix = `${tmuxPrefix}-${opId}`;
 
-	// Load worker agent definition for system prompt
+	// Load worker agent definition: compose base template + local project guidance.
+	// The base template (templates/agents/task-worker.md) contains critical behavioral
+	// rules: checkpoint discipline, STATUS.md resume algorithm, review_step instructions.
+	// The local file (.pi/agents/task-worker.md) adds project-specific guidance.
 	let workerSystemPrompt = "You are a task execution agent. Read STATUS.md first, find unchecked items, work on them, checkpoint after each.";
 	try {
-		const agentPath = join(stateRoot, ".pi", "agents", "task-worker.md");
-		if (existsSync(agentPath)) {
-			const raw = readFileSync(agentPath, "utf-8");
-			const fmEnd = raw.indexOf("---", 4);
-			if (fmEnd > 0) {
-				workerSystemPrompt = raw.slice(fmEnd + 3).trim();
-			}
+		const basePrompt = loadBaseAgentPrompt("task-worker");
+		const localPrompt = loadLocalAgentPrompt(stateRoot, "task-worker");
+		if (basePrompt && localPrompt) {
+			workerSystemPrompt = basePrompt + "\n\n---\n\n## Project-Specific Guidance\n\n" + localPrompt;
+		} else if (basePrompt) {
+			workerSystemPrompt = basePrompt;
+		} else if (localPrompt) {
+			workerSystemPrompt = localPrompt;
 		}
 	} catch { /* use default */ }
 
@@ -3036,6 +3117,7 @@ export async function executeLaneV2(
 			workerTools: "read,write,edit,bash,grep,find,ls",
 			workerThinking: "",
 			workerSystemPrompt,
+			projectName: config.project?.name || "project",
 			maxIterations: 20,
 			noProgressLimit: 3,
 			maxWorkerMinutes: config.failure?.maxWorkerMinutes || 30,

package/extensions/taskplane/lane-runner.ts

@@ -92,6 +92,8 @@ export interface LaneRunnerConfig {
 	workerThinking: string;
 	/** Worker system prompt */
 	workerSystemPrompt: string;
+	/** Project name (for review request context) */
+	projectName?: string;
 	/** Max worker iterations before giving up */
 	maxIterations: number;
 	/** No-progress stall limit */
@@ -273,6 +275,8 @@ export async function executeTaskV2(
 			env: {
 				TASKPLANE_OUTBOX_DIR: outboxDir,
 				TASKPLANE_AGENT_ID: workerAgentId,
+				TASKPLANE_TASK_FOLDER: taskFolder,
+				TASKPLANE_PROJECT_NAME: config.projectName || "project",
 				ORCH_BATCH_ID: config.batchId,
 			},
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.23.13",
+  "version": "0.23.15",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",