pi-harness-runtime 0.10.11 → 0.10.13

package/packages/write-review/src/gate.ts

@@ -0,0 +1,169 @@
+/**
+ * No-Build Gate
+ *
+ * Blocks build commands until review is approved.
+ */
+
+import type { WriteReviewBlackboard } from "./blackboard.js";
+import type { WriteReviewStatus } from "./types.js";
+
+/**
+ * Commands that trigger build gate
+ */
+const BUILD_COMMANDS = [
+	"bench build",
+	"npm run build",
+	"yarn build",
+	"pnpm build",
+	"bun run build",
+	"npm run dev",
+	"yarn dev",
+	"pnpm dev",
+	"./build",
+	"make build",
+	"gradle build",
+	"mvn package",
+	"dotnet build",
+	"cargo build",
+	"go build",
+	"python manage.py migrate",
+	"bench migrate",
+	"bench --site",
+];
+
+/**
+ * Check if a command is a build command
+ */
+export function isBuildCommand(command: string): boolean {
+	const lower = command.toLowerCase().trim();
+	return BUILD_COMMANDS.some((cmd) => lower.includes(cmd.toLowerCase()));
+}
+
+/**
+ * Gate result
+ */
+export interface GateResult {
+	allowed: boolean;
+	reason?: string;
+	currentPhase?: string;
+	message?: string;
+}
+
+/**
+ * Check if build is allowed
+ */
+export function checkBuildGate(
+	command: string,
+	blackboard: WriteReviewBlackboard,
+): GateResult {
+	if (!isBuildCommand(command)) {
+		return { allowed: true };
+	}
+
+	const status = blackboard.load();
+	if (!status) {
+		// No review session - allow build
+		return { allowed: true };
+	}
+
+	if (status.phase === "approved") {
+		return {
+			allowed: true,
+			currentPhase: status.phase,
+			message: "Build allowed - review approved.",
+		};
+	}
+
+	return {
+		allowed: false,
+		reason: "REVIEW_NOT_APPROVED",
+		currentPhase: status.phase,
+		message: `Build blocked. Current review phase: ${status.phase}. Wait for "APPROVED" verdict.`,
+	};
+}
+
+/**
+ * Format gate rejection message
+ */
+export function formatGateRejection(result: GateResult): string {
+	if (result.allowed) {
+		return "";
+	}
+
+	const lines = [
+		"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+		"⚠️  BUILD BLOCKED",
+		"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+		"",
+		`Current Phase: ${result.currentPhase}`,
+		"",
+		"The code is under review. Build is only allowed after APPROVED verdict.",
+		"",
+		"To check status:",
+		`  cat {project}/.write-review/status.json`,
+		"",
+		"To wait for approval, do nothing. The reviewer will post the verdict.",
+		"",
+	];
+
+	if (result.currentPhase === "changes_requested") {
+		lines.push(
+			"Reviewer requested changes. Writer agent should update the code.",
+		);
+	} else if (result.currentPhase === "reviewing") {
+		lines.push("Review is in progress. Please wait...");
+	} else if (result.currentPhase === "pending_review") {
+		lines.push("Review not started yet. Waiting for reviewer...");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Get phase emoji
+ */
+export function getPhaseEmoji(phase: string): string {
+	const emojis: Record<string, string> = {
+		idle: "💤",
+		writing: "✍️",
+		pending_review: "⏳",
+		reviewing: "🔍",
+		approved: "✅",
+		blocked: "🚫",
+		changes_requested: "🔄",
+	};
+	return emojis[phase] ?? "❓";
+}
+
+/**
+ * Format status for display
+ */
+export function formatStatusDisplay(status: WriteReviewStatus): string {
+	const emoji = getPhaseEmoji(status.phase);
+	const lines = [
+		`${emoji} Write-Review Status`,
+		"",
+		`Phase: ${status.phase}`,
+		`Iteration: ${status.iteration}`,
+	];
+
+	if (status.verdict) {
+		lines.push(`Verdict: ${status.verdict}`);
+	}
+
+	if (status.verdictMessage) {
+		lines.push("");
+		lines.push("Message:");
+		lines.push(status.verdictMessage);
+	}
+
+	if (status.codeFiles && status.codeFiles.length > 0) {
+		lines.push("");
+		lines.push("Code Files:");
+		for (const file of status.codeFiles) {
+			lines.push(`  - ${file}`);
+		}
+	}
+
+	return lines.join("\n");
+}

package/packages/write-review/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * write-review - Two-agent code writing with review loop
+ *
+ * Integrates with pi-harness-runtime via:
+ * - Smart trigger detection (prompt files in wiki/)
+ * - System prompt injection for writer agent
+ * - Subagent integration for reviewer agent
+ *
+ * Directory structure: {project}/.write-review/
+ */
+
+// Re-export all public APIs
+export * from "./types.js";
+export * from "./blackboard.js";
+export * from "./trigger.js";
+export * from "./injection.js";
+export * from "./gate.js";
+export * from "./review.js";

package/packages/write-review/src/injection.ts

@@ -0,0 +1,170 @@
+/**
+ * System Prompt Injection
+ *
+ * Adds write-review hints to the agent's system prompt.
+ */
+
+/**
+ * Write-review hint for system prompt
+ */
+export const WRITE_REVIEW_HINT = `
+
+## Write-Review Loop
+
+When reading a prompt from {project}/wiki/*:
+
+1. You are the **WRITER** agent (Minimax). Read the wiki prompt and write code.
+2. After writing code, write "## WRITER_DONE" to signal completion.
+3. Do NOT build or commit until you receive "APPROVED" verdict.
+4. If you receive "CHANGES_REQUESTED", update the code accordingly.
+5. Acknowledge each verdict in your response.
+
+### Blackboard Path
+{p}/.write-review/status.json
+
+### Verdict Types
+- **APPROVED**: Code is ready. You may build/commit.
+- **CHANGES_REQUESTED**: Reviewer found issues. Update code.
+- **BLOCKED**: Critical issues. Human intervention needed.
+`;
+
+/**
+ * Helper agent hint (for worker agent)
+ */
+export const HELPER_HINT = `
+
+## Helper Agent Task
+
+The writer agent is busy or needs assistance. Your task:
+
+1. Note any pending tasks to the Todos list using the todo tool.
+2. Review the changes requested and prepare notes for the writer.
+3. Do NOT write code directly - that's the writer's job.
+4. Write a summary of pending tasks to the blackboard.
+`;
+
+/**
+ * Review reminder hint
+ */
+export const REVIEW_REMINDER_HINT = `
+
+## Review Reminder
+
+Before committing or building, ALWAYS check the write-review status:
+
+\`\`\`bash
+cat {project}/.write-review/status.json
+\`\`\`
+
+Only build/commit if the status shows "approved" or "phase": "approved".
+`;
+
+/**
+ * Format hint with project path
+ */
+export function formatWriteReviewHint(projectPath: string): string {
+	return WRITE_REVIEW_HINT.replace("{project}", projectPath).replace(
+		"{p}",
+		projectPath,
+	);
+}
+
+/**
+ * Format review reminder with project path
+ */
+export function formatReviewReminder(projectPath: string): string {
+	return REVIEW_REMINDER_HINT.replace("{project}", projectPath);
+}
+
+/**
+ * Get all hints to inject
+ */
+export function getWriteReviewHints(projectPath: string): {
+	writeHint: string;
+	reminderHint: string;
+} {
+	return {
+		writeHint: formatWriteReviewHint(projectPath),
+		reminderHint: formatReviewReminder(projectPath),
+	};
+}
+
+/**
+ * Register write-review extension with pi
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBlackboard } from "./blackboard.js";
+
+export function injectWriterInstructions(
+	pi: ExtensionAPI,
+	config?: { debug?: boolean },
+): void {
+	let currentProject: string | null = null;
+	let blackboard: ReturnType<typeof createBlackboard> | null = null;
+	let hintsInjected = false;
+
+	// System prompt injection
+	pi.on("before_agent_start", async (event) => {
+		const cwd = process.cwd?.() ?? "/";
+		if (cwd !== currentProject) {
+			currentProject = cwd;
+			blackboard = createBlackboard(cwd);
+			hintsInjected = false;
+		}
+
+		if (!hintsInjected && blackboard) {
+			const status = blackboard.load();
+			if (status && status.phase !== "idle") {
+				event.systemPrompt += formatWriteReviewHint(cwd);
+				if (status.phase !== "approved") {
+					event.systemPrompt += formatReviewReminder(cwd);
+				}
+				hintsInjected = true;
+				if (config?.debug) {
+					console.log(
+						`[write-review] Hints injected for ${cwd}, phase: ${status.phase}`,
+					);
+				}
+			}
+		}
+	});
+
+	// Build gate
+	pi.on("tool_execution_end", async (event) => {
+		const toolName = (event as { tool?: { name?: string } }).tool?.name ?? "";
+		if (toolName !== "bash") return;
+
+		const result = event as { result?: { content?: string } };
+		const content = result.result?.content ?? "";
+
+		// Check for build commands
+		const buildCommands = [
+			"bench build",
+			"npm run build",
+			"yarn build",
+			"pnpm build",
+			"bun run build",
+			"make build",
+			"gradle build",
+			"dotnet build",
+			"cargo build",
+		];
+		const isBuild = buildCommands.some((cmd) => content.includes(cmd));
+
+		if (isBuild && blackboard) {
+			const status = blackboard.load();
+			if (status && status.phase !== "approved") {
+				result.result!.content =
+					content +
+					"\n\n" +
+					"⚠️ BUILD BLOCKED - Review not approved yet.\n" +
+					`Current phase: ${status.phase}\n` +
+					"Wait for APPROVED verdict before building.";
+			}
+		}
+	});
+
+	if (config?.debug) {
+		console.log("[write-review] Extension registered");
+	}
+}

package/packages/write-review/src/review.ts

@@ -0,0 +1,206 @@
+/**
+ * Review Integration
+ *
+ * Uses pi-subagents review-loop for multi-round code review.
+ */
+
+import type { WriteReviewStatus } from "./types.js";
+
+/**
+ * Review round result
+ */
+export interface ReviewResult {
+	verdict: "approved" | "changes_requested" | "blocked";
+	iteration: number;
+	message: string;
+	changesNeeded?: string[];
+	issues?: ReviewIssue[];
+}
+
+/**
+ * Issue found during review
+ */
+export interface ReviewIssue {
+	severity: "blocker" | "major" | "minor" | "suggestion";
+	type: "correctness" | "security" | "performance" | "style" | "test" | "docs";
+	location: string;
+	description: string;
+	suggestion?: string;
+}
+
+/**
+ * Build review task for pi-subagents
+ */
+export function buildReviewTask(
+	status: WriteReviewStatus,
+	projectPath: string,
+): string {
+	const codeFiles = status.codeFiles ?? [];
+	const iteration = status.iteration;
+
+	const task = `## Review Task - Iteration ${iteration}
+
+Review the code written in this iteration.
+
+### Code Files to Review:
+${codeFiles.map((f) => `- ${f}`).join("\n") || "No files recorded yet."}
+
+### Project Path: ${projectPath}
+
+### Review Instructions:
+1. Read the code files listed above.
+2. Run the review-loop workflow using pi-subagents.
+3. Focus on: correctness, security, performance, tests, and code style.
+4. Return a verdict: APPROVED, CHANGES_REQUESTED, or BLOCKED.
+
+### Verdict Format:
+\`\`\`
+## Verdict: [APPROVED|CHANGES_REQUESTED|BLOCKED]
+[Your detailed review message]
+\`\`\`
+
+For CHANGES_REQUESTED, list specific changes needed:
+\`\`\`
+## Changes Needed:
+1. [Issue description] - [File:Line]
+2. [Issue description] - [File:Line]
+\`\`\`
+`;
+
+	return task;
+}
+
+/**
+ * Parse verdict from review output
+ */
+export function parseVerdict(output: string): {
+	verdict: "approved" | "changes_requested" | "blocked";
+	message: string;
+	changes?: string[];
+} | null {
+	const lines = output.split("\n");
+	let verdict: "approved" | "changes_requested" | "blocked" | null = null;
+	let message = "";
+	const changes: string[] = [];
+	let inChanges = false;
+
+	for (const line of lines) {
+		const lower = line.toLowerCase();
+
+		if (lower.includes("## verdict:")) {
+			if (lower.includes("approved")) {
+				verdict = "approved";
+			} else if (
+				lower.includes("changes_requested") ||
+				lower.includes("changes requested")
+			) {
+				verdict = "changes_requested";
+			} else if (lower.includes("blocked")) {
+				verdict = "blocked";
+			}
+			continue;
+		}
+
+		if (lower.includes("## changes needed:") || lower.includes("changes:")) {
+			inChanges = true;
+			continue;
+		}
+
+		if (inChanges && line.trim().match(/^\d+\./)) {
+			changes.push(line.trim());
+			continue;
+		}
+
+		if (verdict && line.trim()) {
+			message += line + "\n";
+		}
+	}
+
+	if (!verdict) return null;
+
+	return {
+		verdict,
+		message: message.trim(),
+		changes: changes.length > 0 ? changes : undefined,
+	};
+}
+
+/**
+ * Review angles for parallel review
+ */
+export const REVIEW_ANGLES = [
+	{
+		name: "correctness",
+		description:
+			"Verify implementation matches requirements and handles edge cases",
+	},
+	{
+		name: "tests",
+		description: "Check test coverage and validity",
+	},
+	{
+		name: "complexity",
+		description:
+			"Look for unnecessary complexity and opportunities to simplify",
+	},
+];
+
+/**
+ * Build parallel review prompt
+ */
+export function buildParallelReviewPrompt(
+	codeFiles: string[],
+	projectPath: string,
+): string {
+	return `Run parallel reviewers on this code:
+
+1. **correctness** - Verify implementation matches requirements and handles edge cases
+2. **tests** - Check test coverage and validity
+3. **complexity** - Look for unnecessary complexity
+
+Files: ${codeFiles.join(", ")}
+Project: ${projectPath}
+
+Use pi-subagents to spawn 3 parallel reviewers. Wait for all results, then synthesize into a final verdict.`;
+}
+
+/**
+ * Format review summary for blackboard
+ */
+export function formatReviewSummary(result: ReviewResult): string {
+	const lines = [
+		`## Review Result - Iteration ${result.iteration}`,
+		"",
+		`**Verdict:** ${result.verdict.toUpperCase()}`,
+		"",
+	];
+
+	if (result.message) {
+		lines.push("### Message");
+		lines.push(result.message);
+		lines.push("");
+	}
+
+	if (result.changesNeeded && result.changesNeeded.length > 0) {
+		lines.push("### Changes Needed");
+		for (const change of result.changesNeeded) {
+			lines.push(`- ${change}`);
+		}
+		lines.push("");
+	}
+
+	if (result.issues && result.issues.length > 0) {
+		lines.push("### Issues Found");
+		for (const issue of result.issues) {
+			lines.push(`- [${issue.severity}] ${issue.type}: ${issue.description}`);
+			if (issue.location) {
+				lines.push(`  Location: ${issue.location}`);
+			}
+			if (issue.suggestion) {
+				lines.push(`  Suggestion: ${issue.suggestion}`);
+			}
+		}
+	}
+
+	return lines.join("\n");
+}

package/packages/write-review/src/trigger.ts

@@ -0,0 +1,133 @@
+/**
+ * Wiki Prompt Trigger
+ *
+ * Detects when an agent reads a prompt from {project}/wiki/*
+ * This triggers the write-review loop.
+ */
+
+import { existsSync } from "fs";
+import { join, relative } from "path";
+import type { ReviewTriggerContext } from "./types.js";
+
+const DEFAULT_WIKI_DIR = "wiki";
+
+/**
+ * Detect if a file path is a wiki prompt
+ */
+export function isWikiPrompt(filePath: string, projectPath: string): boolean {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+	const normalizedPath = filePath.replace(/\\/g, "/");
+	const normalizedWiki = wikiDir.replace(/\\/g, "/");
+
+	return (
+		normalizedPath.startsWith(normalizedWiki + "/") ||
+		normalizedPath.startsWith(normalizedWiki + "\\")
+	);
+}
+
+/**
+ * Extract prompt metadata from wiki path
+ */
+export function parseWikiPrompt(
+	filePath: string,
+	projectPath: string,
+): { category: string; filename: string } | null {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+	const rel = relative(wikiDir, filePath).replace(/\\/g, "/");
+
+	if (!rel || rel.startsWith("..")) return null;
+
+	const parts = rel.split("/");
+	if (parts.length >= 2) {
+		return {
+			category: parts[0],
+			filename: parts.slice(1).join("/"),
+		};
+	}
+	return {
+		category: "root",
+		filename: parts[0],
+	};
+}
+
+/**
+ * Get all wiki prompt files in a project
+ */
+export function getWikiPrompts(
+	projectPath: string,
+): { path: string; category: string; filename: string }[] {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+
+	if (!existsSync(wikiDir)) {
+		return [];
+	}
+
+	const prompts: { path: string; category: string; filename: string }[] = [];
+
+	function scanDir(dir: string): void {
+		const { readdirSync, statSync } = require("fs");
+		try {
+			for (const entry of readdirSync(dir)) {
+				const fullPath = join(dir, entry);
+				const stat = statSync(fullPath);
+				if (stat.isDirectory()) {
+					scanDir(fullPath);
+				} else if (
+					stat.isFile() &&
+					(entry.endsWith(".md") || entry.endsWith(".txt"))
+				) {
+					const relPath = relative(wikiDir, fullPath).replace(/\\/g, "/");
+					const parts = relPath.split("/");
+					prompts.push({
+						path: fullPath,
+						category: parts[0],
+						filename: parts.slice(1).join("/"),
+					});
+				}
+			}
+		} catch {
+			// Ignore permission errors
+		}
+	}
+
+	scanDir(wikiDir);
+	return prompts;
+}
+
+/**
+ * Create trigger context from a wiki read event
+ */
+export function createTriggerContext(
+	filePath: string,
+	projectPath: string,
+	triggerType: ReviewTriggerContext["triggerType"] = "wiki_read",
+): ReviewTriggerContext | null {
+	if (!isWikiPrompt(filePath, projectPath)) {
+		return null;
+	}
+
+	const parsed = parseWikiPrompt(filePath, projectPath);
+	if (!parsed) return null;
+
+	return {
+		projectPath,
+		promptFile: filePath,
+		promptContent: "", // Will be filled by caller
+		triggerType,
+	};
+}
+
+/**
+ * Check if current working directory has wiki prompts
+ */
+export function hasWikiPrompts(projectPath: string): boolean {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+	return existsSync(wikiDir);
+}
+
+/**
+ * Get wiki directory path
+ */
+export function getWikiDir(projectPath: string): string {
+	return join(projectPath, DEFAULT_WIKI_DIR);
+}