pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/task-compiler/src/types.ts

@@ -0,0 +1,225 @@
+/**
+ * Task Compiler - Type Definitions
+ *
+ * Core types for task decomposition, DAG construction, and verification.
+ */
+
+// ─── SDK Version ───────────────────────────────────────────────────────
+
+export const SDK_VERSION = "1.0.0" as const;
+
+// ─── Task Types ────────────────────────────────────────────────────────
+
+export type TaskType =
+	| "analysis"
+	| "design"
+	| "implementation"
+	| "test"
+	| "e2e_test"
+	| "review"
+	| "repair"
+	| "documentation";
+
+export type ComplexityEstimate = 1 | 2 | 3 | 5 | 8;
+
+// ─── Task Output ────────────────────────────────────────────────────────
+
+export interface TaskOutput {
+	kind: "file" | "test_result" | "report" | "schema" | "diff" | "verification";
+	path?: string;
+	description: string;
+	required: boolean;
+}
+
+// ─── Compiled Task ─────────────────────────────────────────────────────
+
+export interface CompiledTask {
+	id: string;
+	jobId: string;
+	title: string;
+	objective: string;
+	type: TaskType;
+	dependencies: string[];
+	filesInScope: string[];
+	filesExclude?: string[];
+	expectedOutputs: TaskOutput[];
+	acceptanceCriteria: string[];
+	requiredCapabilities: string[];
+	permittedCommands: string[];
+	prohibitedCommands: string[];
+	preferredProvider?: string;
+	estimatedComplexity: ComplexityEstimate;
+	fileOwnership: FileOwnership;
+	priority?: number;
+}
+
+// ─── File Ownership ────────────────────────────────────────────────────
+
+export type FileOwnershipMode = "exclusive" | "shared_read";
+
+export interface FileOwnership {
+	taskId: string;
+	include: string[];
+	exclude: string[];
+	mode: FileOwnershipMode;
+}
+
+// ─── Task Graph ────────────────────────────────────────────────────────
+
+export interface TaskGraph {
+	jobId: string;
+	tasks: CompiledTask[];
+	roots: string[];
+	terminalTasks: string[];
+	topologicalOrder: string[];
+}
+
+// ─── Standard Engineering Flow ────────────────────────────────────────
+
+export const STANDARD_FLOW: TaskType[] = [
+	"analysis",
+	"design",
+	"implementation",
+	"test",
+	"e2e_test",
+	"review",
+	"repair",
+	"documentation",
+];
+
+// ─── Provider Hints ───────────────────────────────────────────────────
+
+export const PROVIDER_HINTS: Partial<Record<TaskType, string[]>> = {
+	analysis: ["codex", "gpt", "glm"],
+	design: ["codex", "gpt", "glm"],
+	implementation: ["minimax", "claude", "glm"],
+	test: ["minimax", "claude"],
+	e2e_test: ["playwright"],
+	review: ["claude", "glm"],
+	repair: ["glm", "claude"],
+	documentation: ["codex", "gpt"],
+};
+
+// ─── Default Command Policy ─────────────────────────────────────────────
+
+export const PROHIBITED_BY_DEFAULT: string[] = [
+	"git commit",
+	"git push",
+	"bench build",
+	"bench migrate",
+	"bench install-app",
+	"bench restart",
+	"npm run build",
+	"yarn build",
+	"pnpm build",
+	"python manage.py migrate",
+	"docker compose up",
+	"docker compose down",
+	"rm -rf",
+	"DROP DATABASE",
+	"TRUNCATE",
+];
+
+// ─── Forward-declared types (from other workspace packages) ─────────────
+// In production these are imported from @pi-harness/requirement-compiler and @pi/project-analyzer.
+// Declaring them as interfaces here allows the type checker to resolve without building those packages first.
+
+export interface CompiledRequirement {
+	id: string;
+	title: string;
+	problemStatement: string;
+	goals: Array<{ id: string; description: string }>;
+	constraints: Array<{ id: string; description: string; blocking: boolean }>;
+	nonGoals?: string[];
+	acceptanceCriteria: Array<{ id: string; outcome: string[] }>;
+	riskTags: Array<{ risk: string; affectedId: string }>;
+}
+
+export interface ProjectProfile {
+	projectPath: string;
+	projectName?: string;
+	frameworks?: Array<{ name: string; confidence: number }>;
+	testCapabilities?: Array<{ runner: string; supported: boolean }>;
+	commands?: Record<string, string>;
+	rules?: Array<{
+		id: string;
+		section: string;
+		permittedCommands?: string[];
+		prohibitedCommands?: string[];
+	}>;
+}
+
+// ─── Compiler Input ────────────────────────────────────────────────────
+
+export interface TaskCompileInput {
+	requirement: CompiledRequirement;
+	project: ProjectProfile;
+	dependencies?: DependencyInfo[];
+	jobId: string;
+	clock?: () => Date;
+	insertE2E?: boolean;
+	maxComplexity?: ComplexityEstimate;
+}
+
+export interface DependencyInfo {
+	requirementId: string;
+	dependsOn: string[];
+	files: string[];
+}
+
+// ─── Candidate Task ───────────────────────────────────────────────────
+
+export interface TaskCandidate {
+	id: string;
+	title: string;
+	objective: string;
+	type: TaskType;
+	roughDependencies: string[];
+	criteria: string[];
+	estimatedComplexity: ComplexityEstimate;
+	priority?: number;
+}
+
+// ─── Compiler Configuration ──────────────────────────────────────────────
+
+export interface TaskCompilerConfig {
+	insertE2E: boolean;
+	maxComplexity: ComplexityEstimate;
+	extraProhibitedCommands: string[];
+	clock: () => Date;
+}
+
+export const DEFAULT_TASK_COMPILER_CONFIG: TaskCompilerConfig = {
+	insertE2E: true,
+	maxComplexity: 5,
+	extraProhibitedCommands: [],
+	clock: () => new Date(),
+};
+
+// ─── Compiler Errors ─────────────────────────────────────────────────────
+
+export enum TaskCompilerErrorCode {
+	CYCLIC_DEPENDENCY = "CYCLIC_DEPENDENCY",
+	EMPTY_OBJECTIVE = "EMPTY_OBJECTIVE",
+	NO_VERIFICATION = "NO_VERIFICATION",
+	FILE_OVERLAP_CONFLICT = "FILE_OVERLAP_CONFLICT",
+	UNSATISFIED_CRITERION = "UNSATISFIED_CRITERION",
+	MISSING_CAPABILITY = "MISSING_CAPILITY",
+	DESTRUCTIVE_COMMAND_APPROVAL = "DESTRUCTIVE_COMMAND_APPROVAL",
+}
+
+export class TaskCompilerError extends Error {
+	readonly code: TaskCompilerErrorCode;
+	readonly details?: Record<string, unknown>;
+
+	constructor(
+		code: TaskCompilerErrorCode,
+		message: string,
+		details?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = "TaskCompilerError";
+		this.code = code;
+		this.details = details;
+	}
+}

package/packages/task-compiler/src/validate.ts

@@ -0,0 +1,218 @@
+/**
+ * Task Compiler - Validation
+ *
+ * Validates the task graph: cycle detection, file overlap, verification, etc.
+ */
+
+import type { TaskGraph } from "./types.js";
+import { TaskCompilerError, TaskCompilerErrorCode } from "./types.js";
+
+/**
+ * Assert the graph has no cycles.
+ * Uses Kahn's algorithm to verify all tasks are reachable in topological order.
+ */
+export function assertNoCycles(graph: TaskGraph): void {
+	// Compute in-degrees: how many dependencies each task has
+	const inDegree = new Map<string, number>();
+	for (const task of graph.tasks) {
+		inDegree.set(task.id, task.dependencies.length);
+	}
+
+	// Kahn's algorithm
+	const queue: string[] = [];
+	for (const [id, degree] of inDegree.entries()) {
+		if (degree === 0) queue.push(id);
+	}
+	const visited: string[] = [];
+
+	while (queue.length > 0) {
+		const id = queue.shift();
+		if (!id) break;
+		visited.push(id);
+
+		// Reduce in-degree of tasks that depend on `id`
+		for (const task of graph.tasks) {
+			if (task.dependencies.includes(id)) {
+				const newDegree = (inDegree.get(task.id) ?? 1) - 1;
+				inDegree.set(task.id, newDegree);
+				if (newDegree === 0) {
+					queue.push(task.id);
+				}
+			}
+		}
+	}
+
+	if (visited.length !== graph.tasks.length) {
+		const unvisited = graph.tasks
+			.filter((t) => !visited.includes(t.id))
+			.map((t) => t.id);
+		throw new TaskCompilerError(
+			TaskCompilerErrorCode.CYCLIC_DEPENDENCY,
+			`Cyclic dependency detected. Tasks in cycle: ${unvisited.join(", ")}`,
+			{ cyclicTasks: unvisited },
+		);
+	}
+}
+
+/**
+ * Assert no exclusive file overlap between parallel tasks.
+ * Two exclusive tasks cannot modify the same files unless one depends on the other.
+ */
+export function assertNoExclusiveFileOverlap(graph: TaskGraph): void {
+	const exclusiveTasks = graph.tasks.filter(
+		(t) => t.fileOwnership.mode === "exclusive",
+	);
+
+	const overlaps: Array<{ taskA: string; taskB: string; files: string[] }> = [];
+
+	for (let i = 0; i < exclusiveTasks.length; i++) {
+		for (let j = i + 1; j < exclusiveTasks.length; j++) {
+			const a = exclusiveTasks[i];
+			const b = exclusiveTasks[j];
+
+			// Sequential: skip if one depends on the other
+			if (a.dependencies.includes(b.id) || b.dependencies.includes(a.id)) {
+				continue;
+			}
+
+			// Both wait for same parent: not truly parallel
+			const aRoots = getAllDependencies(a.id, graph);
+			const bRoots = getAllDependencies(b.id, graph);
+			if (Array.from(aRoots).some((d) => bRoots.has(d))) {
+				continue;
+			}
+
+			const conflictFiles = findFileOverlap(a.fileOwnership, b.fileOwnership);
+			if (conflictFiles.length > 0) {
+				overlaps.push({
+					taskA: a.id,
+					taskB: b.id,
+					files: conflictFiles,
+				});
+			}
+		}
+	}
+
+	if (overlaps.length > 0) {
+		const details = overlaps.map(
+			(o) => `${o.taskA} ↔ ${o.taskB}: ${o.files.join(", ")}`,
+		);
+		throw new TaskCompilerError(
+			TaskCompilerErrorCode.FILE_OVERLAP_CONFLICT,
+			`Exclusive file overlap detected between parallel tasks: ${details.join("; ")}`,
+			{ overlaps },
+		);
+	}
+}
+
+/**
+ * Assert every task has at least one required verification output.
+ */
+export function assertEveryTaskHasVerification(graph: TaskGraph): void {
+	const missing: string[] = [];
+	for (const task of graph.tasks) {
+		const requiredOutputs = task.expectedOutputs.filter((o) => o.required);
+		if (requiredOutputs.length === 0) {
+			missing.push(task.id);
+		}
+	}
+	if (missing.length > 0) {
+		throw new TaskCompilerError(
+			TaskCompilerErrorCode.NO_VERIFICATION,
+			`Tasks without required verification outputs: ${missing.join(", ")}`,
+			{ taskIds: missing },
+		);
+	}
+}
+
+/**
+ * Assert no task has an empty objective.
+ */
+export function assertNoEmptyObjectives(graph: TaskGraph): void {
+	const empty: string[] = [];
+	for (const task of graph.tasks) {
+		if (!task.objective.trim()) {
+			empty.push(task.id);
+		}
+	}
+	if (empty.length > 0) {
+		throw new TaskCompilerError(
+			TaskCompilerErrorCode.EMPTY_OBJECTIVE,
+			`Tasks with empty objectives: ${empty.join(", ")}`,
+			{ taskIds: empty },
+		);
+	}
+}
+
+/**
+ * Assert every acceptance criterion is assigned to at least one task.
+ */
+export function assertEveryCriterionAssigned(
+	graph: TaskGraph,
+	criterionIds: string[],
+): void {
+	const assigned = new Set<string>();
+	for (const task of graph.tasks) {
+		for (const cid of task.acceptanceCriteria) {
+			assigned.add(cid);
+		}
+	}
+	const unassigned = criterionIds.filter((c) => !assigned.has(c));
+	if (unassigned.length > 0) {
+		throw new TaskCompilerError(
+			TaskCompilerErrorCode.UNSATISFIED_CRITERION,
+			`Acceptance criteria not assigned to any task: ${unassigned.join(", ")}`,
+			{ unassignedCriteria: unassigned },
+		);
+	}
+}
+
+// ─── File overlap detection ──────────────────────────────────────────
+
+function findFileOverlap(
+	a: import("./types.js").FileOwnership,
+	b: import("./types.js").FileOwnership,
+): string[] {
+	const conflicts: string[] = [];
+
+	for (const patternA of a.include) {
+		for (const patternB of b.include) {
+			if (patternA === patternB) {
+				conflicts.push(patternA);
+			} else if (patternSubsumes(patternA, patternB)) {
+				conflicts.push(patternB);
+			} else if (patternSubsumes(patternB, patternA)) {
+				conflicts.push(patternA);
+			}
+		}
+	}
+
+	return [...new Set(conflicts)];
+}
+
+function patternSubsumes(parent: string, child: string): boolean {
+	const p = parent.replace(/\/\*\*$/, "");
+	return child.startsWith(`${p}/`) || child.startsWith(p);
+}
+
+// ─── Dependency helpers ────────────────────────────────────────────────
+
+function getAllDependencies(taskId: string, graph: TaskGraph): Set<string> {
+	const taskMap = new Map(graph.tasks.map((t) => [t.id, t]));
+	const visited = new Set<string>();
+
+	function walk(id: string) {
+		if (visited.has(id)) return;
+		const task = taskMap.get(id);
+		if (task) {
+			visited.add(id);
+			for (const dep of task.dependencies) {
+				walk(dep);
+			}
+		}
+	}
+
+	walk(taskId);
+	visited.delete(taskId);
+	return visited;
+}

package/packages/task-compiler/src/verification.ts

@@ -0,0 +1,248 @@
+/**
+ * Task Compiler - Verification Assignment
+ *
+ * Assigns TaskOutput (expectedOutputs) to each compiled task
+ * so completion can be measured objectively.
+ */
+
+import type { CompiledRequirement, CompiledTask, TaskOutput } from "./types.js";
+
+/**
+ * Assign verification outputs to each task based on its type
+ * and the requirement's acceptance criteria.
+ */
+export function assignVerification(
+	tasks: CompiledTask[],
+	requirement: CompiledRequirement,
+): CompiledTask[] {
+	return tasks.map((task) => {
+		const outputs = buildOutputs(task, requirement);
+		return { ...task, expectedOutputs: outputs };
+	});
+}
+
+// ─── Output builders by task type ─────────────────────────────────────
+
+function buildOutputs(
+	task: CompiledTask,
+	requirement: CompiledRequirement,
+): TaskOutput[] {
+	switch (task.type) {
+		case "implementation": {
+			return buildImplementationOutputs(task, requirement);
+		}
+		case "test": {
+			return buildTestOutputs(task);
+		}
+		case "e2e_test": {
+			return buildE2EOutputs(task);
+		}
+		case "review": {
+			return buildReviewOutputs(task);
+		}
+		case "analysis": {
+			return buildAnalysisOutputs(task);
+		}
+		case "design": {
+			return buildDesignOutputs(task);
+		}
+		case "repair": {
+			return buildRepairOutputs(task);
+		}
+		case "documentation": {
+			return buildDocumentationOutputs(task);
+		}
+		default: {
+			return [
+				{
+					kind: "verification",
+					description: `Task "${task.title}" completed as expected.`,
+					required: true,
+				},
+			];
+		}
+	}
+}
+
+// ─── Type-specific output builders ───────────────────────────────────
+
+function buildImplementationOutputs(
+	task: CompiledTask,
+	requirement: CompiledRequirement,
+): TaskOutput[] {
+	const outputs: TaskOutput[] = [];
+
+	// Required: at least one file was modified
+	outputs.push({
+		kind: "diff",
+		description: `Implementation of "${task.title}" produces code changes`,
+		required: true,
+	});
+
+	// Required: acceptance criteria are addressed
+	if (task.acceptanceCriteria.length > 0) {
+		outputs.push({
+			kind: "verification",
+			description: `All assigned acceptance criteria (${task.acceptanceCriteria.length}) are addressed`,
+			required: true,
+		});
+	}
+
+	// Optional: affected files mentioned in goal
+	const goal = requirement.goals.find((g) =>
+		task.objective.includes(g.description.slice(0, 30)),
+	);
+	if (goal) {
+		outputs.push({
+			kind: "verification",
+			description: `Goal "${goal.description.slice(0, 60)}" is implemented`,
+			required: true,
+		});
+	}
+
+	// Risk verification for destructive operations
+	const hasDestructive = requirement.riskTags.some(
+		(r) => r.risk === "destructive_operation",
+	);
+	if (hasDestructive) {
+		outputs.push({
+			kind: "verification",
+			description: "Destructive operations have rollback plan and approval",
+			required: true,
+		});
+	}
+
+	return outputs;
+}
+
+function buildTestOutputs(task: CompiledTask): TaskOutput[] {
+	const outputs: TaskOutput[] = [
+		{
+			kind: "test_result",
+			description: `Unit tests for "${task.title}" pass`,
+			required: true,
+		},
+		{
+			kind: "verification",
+			description: "Test coverage is maintained above configured threshold",
+			required: false,
+		},
+	];
+
+	// All acceptance criteria must be tested
+	if (task.acceptanceCriteria.length > 0) {
+		outputs.push({
+			kind: "verification",
+			description: `All ${task.acceptanceCriteria.length} acceptance criteria have at least one test`,
+			required: true,
+		});
+	}
+
+	return outputs;
+}
+
+function buildE2EOutputs(task: CompiledTask): TaskOutput[] {
+	return [
+		{
+			kind: "test_result",
+			description: `E2E tests for "${task.title}" pass`,
+			required: true,
+		},
+		{
+			kind: "verification",
+			description: "E2E test scenarios cover all critical user flows",
+			required: true,
+		},
+	];
+}
+
+function buildReviewOutputs(task: CompiledTask): TaskOutput[] {
+	const outputs: TaskOutput[] = [
+		{
+			kind: "report",
+			description: `Review report for "${task.title}" is produced`,
+			required: true,
+		},
+		{
+			kind: "verification",
+			description: "All review findings are addressed or explicitly accepted",
+			required: true,
+		},
+	];
+
+	if (task.acceptanceCriteria.length > 0) {
+		outputs.push({
+			kind: "verification",
+			description: `${task.acceptanceCriteria.length} acceptance criteria are verified`,
+			required: true,
+		});
+	}
+
+	return outputs;
+}
+
+function buildAnalysisOutputs(task: CompiledTask): TaskOutput[] {
+	return [
+		{
+			kind: "report",
+			description: `Analysis report for "${task.title}" is produced`,
+			required: true,
+		},
+		{
+			kind: "schema",
+			description: "Affected modules and dependencies are identified",
+			required: true,
+		},
+	];
+}
+
+function buildDesignOutputs(task: CompiledTask): TaskOutput[] {
+	return [
+		{
+			kind: "schema",
+			description: `Design document/schema for "${task.title}" is produced`,
+			required: true,
+		},
+		{
+			kind: "file",
+			description: "Architecture diagram or component model is included",
+			required: false,
+		},
+	];
+}
+
+function buildRepairOutputs(task: CompiledTask): TaskOutput[] {
+	return [
+		{
+			kind: "verification",
+			description: `All review findings for "${task.title}" are resolved`,
+			required: true,
+		},
+		{
+			kind: "diff",
+			description: "Repair changes are applied and verified",
+			required: true,
+		},
+	];
+}
+
+function buildDocumentationOutputs(task: CompiledTask): TaskOutput[] {
+	return [
+		{
+			kind: "file",
+			path: "README.md",
+			description: "README or user-facing documentation is updated",
+			required: false,
+		},
+		{
+			kind: "file",
+			description: "API documentation reflects implementation",
+			required: true,
+		},
+		{
+			kind: "verification",
+			description: `Documentation for "${task.title}" is complete`,
+			required: true,
+		},
+	];
+}