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

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

@@ -0,0 +1,265 @@
+/**
+ * Task Compiler - Requirement Decomposition
+ *
+ * Breaks a compiled requirement into candidate tasks following
+ * the standard engineering flow and decomposition policy.
+ */
+
+import type {
+	CompiledRequirement,
+	ComplexityEstimate,
+	ProjectProfile,
+	TaskCandidate,
+	TaskCompileInput,
+} from "./types.js";
+
+/**
+ * Decompose a compiled requirement into task candidates.
+ *
+ * Policy: split when different capabilities needed, unrelated modules,
+ * incoherent test set, destructive+edit mix, >maxComplexity, or
+ * independently-proceeding outputs. Do NOT split to inflate count.
+ */
+export function decomposeRequirement(input: TaskCompileInput): TaskCandidate[] {
+	const { requirement, project, maxComplexity = 5 } = input;
+
+	const candidates: TaskCandidate[] = [];
+	let priority = 1;
+
+	// ─── Stage detection ────────────────────────────────────────────────
+
+	const needsAnalysis =
+		requirement.problemStatement.length > 200 || requirement.goals.length > 3;
+	const needsDesign = requirement.problemStatement.length > 100;
+	const hasTests = requirement.acceptanceCriteria.length > 0;
+	const hasBrowserWorkflow = detectBrowserWorkflow(project);
+	const needsRepair = requirement.riskTags.some(
+		(r) => r.risk === "destructive_operation",
+	);
+
+	// ─── Analysis ──────────────────────────────────────────────────────
+
+	if (needsAnalysis) {
+		candidates.push({
+			id: "analysis-0",
+			title: `Analyze: ${truncate(requirement.title, 40)}`,
+			objective: `Analyze the requirement "${requirement.title}": ${requirement.problemStatement}. Identify affected modules, detect dependencies, and outline implementation approach.`,
+			type: "analysis",
+			roughDependencies: [],
+			criteria: [],
+			estimatedComplexity: estimateComplexity(requirement.problemStatement),
+			priority: priority++,
+		});
+	}
+
+	// ─── Design ────────────────────────────────────────────────────────
+
+	if (needsDesign) {
+		candidates.push({
+			id: "design-0",
+			title: `Design: ${truncate(requirement.title, 40)}`,
+			objective: `Design the architecture for: ${requirement.problemStatement}. Produce a schema or design document capturing the component model, API contracts, and data flow.`,
+			type: "design",
+			roughDependencies: needsAnalysis ? ["analysis-0"] : [],
+			criteria: [],
+			estimatedComplexity: 3,
+			priority: priority++,
+		});
+	}
+
+	// ─── Implementation ────────────────────────────────────────────────
+
+	for (let i = 0; i < requirement.goals.length; i++) {
+		const goal = requirement.goals[i];
+		const implDeps: string[] = [];
+		if (needsDesign) implDeps.push("design-0");
+		else if (needsAnalysis) implDeps.push("analysis-0");
+
+		candidates.push({
+			id: `impl-${i}`,
+			title: `Implement: ${truncate(goal.description, 45)}`,
+			objective: goal.description,
+			type: "implementation",
+			roughDependencies: implDeps,
+			criteria: mapGoalToCriteria(goal.id, requirement),
+			estimatedComplexity: estimateComplexity(goal.description),
+			priority: priority++,
+		});
+	}
+
+	// Blocking constraints as an implementation concern
+	const blockingConstraints = requirement.constraints.filter((c) => c.blocking);
+	if (blockingConstraints.length > 0) {
+		const firstImplId = requirement.goals.length > 0 ? "impl-0" : undefined;
+		candidates.push({
+			id: "impl-constraints",
+			title: `Implement constraints: ${truncate(blockingConstraints[0].description, 40)}`,
+			objective: blockingConstraints.map((c) => c.description).join("; "),
+			type: "implementation",
+			roughDependencies: firstImplId ? [firstImplId] : [],
+			criteria: [],
+			estimatedComplexity: 3,
+			priority: priority++,
+		});
+	}
+
+	// ─── Unit tests ───────────────────────────────────────────────────
+
+	if (hasTests) {
+		candidates.push({
+			id: "test-0",
+			title: `Write unit tests for: ${truncate(requirement.title, 35)}`,
+			objective: `Write unit tests that verify the acceptance criteria for: ${requirement.problemStatement}. Each test must map to at least one acceptance criterion.`,
+			type: "test",
+			roughDependencies: requirement.goals.length > 0 ? ["impl-0"] : [],
+			criteria: requirement.acceptanceCriteria.map((c) => c.id),
+			estimatedComplexity: 3,
+			priority: priority++,
+		});
+	}
+
+	// ─── E2E tests ───────────────────────────────────────────────────
+
+	if (hasBrowserWorkflow && input.insertE2E !== false) {
+		candidates.push({
+			id: "e2e-0",
+			title: `Write E2E tests for: ${truncate(requirement.title, 35)}`,
+			objective: `Write end-to-end browser tests for: ${requirement.problemStatement}. Cover the critical user flows identified in the requirements.`,
+			type: "e2e_test",
+			roughDependencies: hasTests
+				? ["test-0"]
+				: requirement.goals.length > 0
+					? ["impl-0"]
+					: [],
+			criteria: [],
+			estimatedComplexity: 5,
+			priority: priority++,
+		});
+	}
+
+	// ─── Review ────────────────────────────────────────────────────────
+
+	const reviewDeps: string[] = [];
+	if (hasTests) reviewDeps.push("test-0");
+	if (hasBrowserWorkflow && input.insertE2E !== false) reviewDeps.push("e2e-0");
+	if (reviewDeps.length === 0 && requirement.goals.length > 0)
+		reviewDeps.push("impl-0");
+
+	candidates.push({
+		id: "review-0",
+		title: `Review changes for: ${truncate(requirement.title, 35)}`,
+		objective: `Review all code changes for: ${requirement.problemStatement}. Verify code quality, test coverage, and alignment with acceptance criteria.`,
+		type: "review",
+		roughDependencies: reviewDeps,
+		criteria: requirement.acceptanceCriteria.map((c) => c.id),
+		estimatedComplexity: 2,
+		priority: priority++,
+	});
+
+	// ─── Repair ────────────────────────────────────────────────────────
+
+	if (needsRepair) {
+		candidates.push({
+			id: "repair-0",
+			title: `Repair / verify: ${truncate(requirement.title, 35)}`,
+			objective: `Address review findings and verify that destructive operations in: ${requirement.problemStatement} have proper approval and rollback plans.`,
+			type: "repair",
+			roughDependencies: ["review-0"],
+			criteria: [],
+			estimatedComplexity: 3,
+			priority: priority++,
+		});
+	}
+
+	// ─── Documentation ────────────────────────────────────────────────
+
+	candidates.push({
+		id: "docs-0",
+		title: `Document: ${truncate(requirement.title, 40)}`,
+		objective: `Document the implementation of: ${requirement.title}. ${requirement.problemStatement}. Include usage examples, API documentation, and any relevant diagrams.`,
+		type: "documentation",
+		roughDependencies: needsRepair ? ["repair-0"] : ["review-0"],
+		criteria: [],
+		estimatedComplexity: 2,
+		priority: priority++,
+	});
+
+	// ─── Enforce complexity threshold ─────────────────────────────────
+
+	const result: TaskCandidate[] = [];
+	for (const c of candidates) {
+		if (c.estimatedComplexity > maxComplexity) {
+			result.push(...splitByComplexity(c, maxComplexity));
+		} else {
+			result.push(c);
+		}
+	}
+
+	return result;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function estimateComplexity(text: string): ComplexityEstimate {
+	const words = text.split(/\s+/).length;
+	if (words < 20) return 1;
+	if (words < 50) return 2;
+	if (words < 100) return 3;
+	if (words < 200) return 5;
+	return 8;
+}
+
+function splitByComplexity(
+	task: TaskCandidate,
+	_maxComplexity: number,
+): TaskCandidate[] {
+	const half = Math.ceil(task.estimatedComplexity / 2) as ComplexityEstimate;
+	return [
+		{
+			...task,
+			id: `${task.id}-a`,
+			estimatedComplexity: half,
+			title: `${task.title} [Part 1]`,
+			objective: `${task.objective} (Part 1)`,
+		},
+		{
+			...task,
+			id: `${task.id}-b`,
+			estimatedComplexity: half,
+			title: `${task.title} [Part 2]`,
+			objective: `${task.objective} (Part 2)`,
+			roughDependencies: [...task.roughDependencies, `${task.id}-a`],
+		},
+	];
+}
+
+function mapGoalToCriteria(
+	goalId: string,
+	requirement: CompiledRequirement,
+): string[] {
+	const acs = requirement.acceptanceCriteria;
+	const goalIndex = requirement.goals.findIndex((g) => g.id === goalId);
+	if (goalIndex < 0) return acs.map((c) => c.id);
+	// Distribute criteria round-robin across goals
+	return acs
+		.filter((_, i) => i % requirement.goals.length === goalIndex)
+		.map((c) => c.id);
+}
+
+function detectBrowserWorkflow(project: ProjectProfile): boolean {
+	const frameworks = project.frameworks ?? [];
+	const testCapabilities = project.testCapabilities ?? [];
+	return (
+		frameworks.some((f) =>
+			/playwright|cypress|selenium|nightwatch/i.test(f.name),
+		) ||
+		testCapabilities.some((t) =>
+			/playwright|cypress|selenium|e2e|browser/i.test(t.runner),
+		)
+	);
+}
+
+function truncate(text: string, maxLen: number): string {
+	if (text.length <= maxLen) return text;
+	return `${text.slice(0, maxLen - 1)}…`;
+}

package/packages/task-compiler/src/file-scope.ts

@@ -0,0 +1,240 @@
+/**
+ * Task Compiler - File Scope Assignment
+ *
+ * Assigns filesInScope and FileOwnership to each compiled task
+ * based on the project structure and task type.
+ */
+
+import type {
+	CompiledTask,
+	FileOwnership,
+	FileOwnershipMode,
+	ProjectProfile,
+	TaskCandidate,
+	TaskType,
+} from "./types.js";
+
+/**
+ * Assign file scope and ownership to each task candidate.
+ *
+ * File scope is determined by:
+ * - Task type (implementation → source files, test → test files)
+ * - Project structure (detected by Project Analyzer)
+ * - Requirement goals and constraints
+ */
+export function assignFileScope(
+	candidates: TaskCandidate[],
+	project: ProjectProfile,
+): CompiledTask[] {
+	const __projectPath = project.projectPath;
+	const sourceExts = detectSourceExtensions(project);
+	const testExts = detectTestExtensions(project);
+
+	return candidates.map((candidate) => {
+		const filesInScope = inferFiles(candidate, project, sourceExts, testExts);
+		const mode = getOwnershipMode(candidate.type);
+		const ownership: FileOwnership = {
+			taskId: candidate.id,
+			include: filesInScope,
+			exclude: getExclusions(candidate.type, project),
+			mode,
+		};
+
+		return {
+			id: candidate.id,
+			jobId: "", // Set by compiler
+			title: candidate.title,
+			objective: candidate.objective,
+			type: candidate.type,
+			dependencies: candidate.roughDependencies,
+			filesInScope,
+			filesExclude: ownership.exclude,
+			expectedOutputs: [], // Set by verification.ts
+			acceptanceCriteria: candidate.criteria,
+			requiredCapabilities: inferCapabilities(candidate.type),
+			permittedCommands: [], // Set by command-policy.ts
+			prohibitedCommands: [], // Set by command-policy.ts
+			preferredProvider: undefined, // Set by compiler.ts
+			estimatedComplexity: candidate.estimatedComplexity,
+			fileOwnership: ownership,
+			priority: candidate.priority,
+		};
+	});
+}
+
+// ─── File inference by task type ───────────────────────────────────────
+
+function inferFiles(
+	candidate: TaskCandidate,
+	project: ProjectProfile,
+	_sourceExts: string[],
+	testExts: string[],
+): string[] {
+	const { type, objective } = candidate;
+	const base = project.projectPath;
+
+	switch (type) {
+		case "analysis": {
+			return [`${base}/src/**`];
+		}
+
+		case "design": {
+			return [`${base}/src/**/*.ts`, `${base}/docs/**`];
+		}
+
+		case "implementation": {
+			// Default to all source files; narrow by extracting file mentions from objective
+			const mentions = extractFileMentions(objective);
+			if (mentions.length > 0) return mentions;
+			return [`${base}/src/**`];
+		}
+
+		case "test": {
+			if (testExts.length > 0)
+				return [`${base}/test/**`, `${base}/**/*.test.*`];
+			return [`${base}/**/*.test.*`, `${base}/**/*.spec.*`];
+		}
+
+		case "e2e_test": {
+			return [`${base}/**/*.e2e.*`, `${base}/e2e/**`];
+		}
+
+		case "review": {
+			// Review reads everything that's been modified
+			return [`${base}/src/**`];
+		}
+
+		case "repair": {
+			// Repair targets whatever the review flagged
+			const mentions = extractFileMentions(objective);
+			return mentions.length > 0 ? mentions : [`${base}/src/**`];
+		}
+
+		case "documentation": {
+			return [`${base}/README.md`, `${base}/docs/**`, `${base}/src/**/*.md`];
+		}
+
+		default: {
+			return [`${base}/src/**`];
+		}
+	}
+}
+
+// ─── Extract file mentions from objective text ──────────────────────────
+
+function extractFileMentions(text: string): string[] {
+	// Match common file/directory patterns in natural language:
+	// - "src/components/Button.tsx"
+	// - "packages/foo/src/"
+	// - "test/user.test.ts"
+	const pattern =
+		/(?:src|test|packages?|apps?|lib|components?|hooks?|utils|docs?)[/\\][^\s"']+/gi;
+	const matches = text.match(pattern);
+	if (!matches) return [];
+	// Deduplicate and return
+	return [...new Set(matches)];
+}
+
+// ─── Ownership mode ────────────────────────────────────────────────────
+
+function getOwnershipMode(type: TaskType): FileOwnershipMode {
+	// Parallel tasks with "exclusive" mode cannot modify the same files
+	switch (type) {
+		case "implementation":
+		case "test":
+		case "e2e_test":
+		case "repair":
+			return "exclusive";
+		case "analysis":
+		case "design":
+		case "review":
+		case "documentation":
+			return "shared_read";
+		default:
+			return "shared_read";
+	}
+}
+
+// ─── Exclusions ────────────────────────────────────────────────────────
+
+function getExclusions(_type: TaskType, project: ProjectProfile): string[] {
+	const exclusions: string[] = [
+		// Never touch these regardless of task type
+		"**/node_modules/**",
+		"**/dist/**",
+		"**/.git/**",
+		"**/coverage/**",
+		"**/build/**",
+	];
+
+	// Add project-specific exclusions from rules
+	if (project.rules) {
+		for (const rule of project.rules) {
+			if (rule.section === "scope" || rule.section === "files") {
+				// Rules may specify excluded patterns
+			}
+		}
+	}
+
+	return exclusions;
+}
+
+// ─── Capability inference ───────────────────────────────────────────────
+
+function inferCapabilities(type: TaskType): string[] {
+	const caps: Record<TaskType, string[]> = {
+		analysis: ["plan", "analysis"],
+		design: ["plan", "analysis"],
+		implementation: ["code"],
+		test: ["code", "test"],
+		e2e_test: ["code", "e2e"],
+		review: ["review"],
+		repair: ["code", "debug"],
+		documentation: ["code"],
+	};
+	return caps[type] ?? ["code"];
+}
+
+// ─── Extension detection ─────────────────────────────────────────────────
+
+function detectSourceExtensions(project: ProjectProfile): string[] {
+	const frameworks = project.frameworks ?? [];
+	const exts = new Set<string>(["ts", "tsx", "js", "jsx"]);
+
+	if (frameworks.some((f) => /typescript|ts|tsx/i.test(f.name))) {
+		exts.add("ts");
+		exts.add("tsx");
+	}
+	if (frameworks.some((f) => /react|next\.?js|vue|svelte/i.test(f.name))) {
+		exts.add("jsx");
+		exts.add("tsx");
+	}
+	if (frameworks.some((f) => /python|flask|django|fastapi/i.test(f.name))) {
+		exts.add("py");
+	}
+	if (frameworks.some((f) => /frappe|erpnext/i.test(f.name))) {
+		exts.add("py");
+		exts.add("js");
+	}
+
+	return [...exts];
+}
+
+function detectTestExtensions(project: ProjectProfile): string[] {
+	const frameworks = project.frameworks ?? [];
+	const testCaps = project.testCapabilities ?? [];
+	const exts = new Set<string>();
+
+	if (
+		frameworks.some((f) =>
+			/playwright|cypress|selenium|nightwatch/i.test(f.name),
+		) ||
+		testCaps.some((t) =>
+			/playwright|cypress|selenium|nightwatch/i.test(t.runner),
+		)
+	) {
+		exts.add("e2e.ts");
+	}
+
+	return [...exts];
+}

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

@@ -0,0 +1,144 @@
+/**
+ * Task Compiler - Task Graph Builder
+ *
+ * Builds the deterministic DAG from compiled tasks,
+ * performs topological sort, and detects root/terminal nodes.
+ */
+
+import type { CompiledTask, TaskGraph } from "./types.js";
+
+/**
+ * Build a TaskGraph from compiled tasks.
+ *
+ * The graph is built from task dependencies and includes:
+ * - Roots: tasks with no incoming dependencies
+ * - Terminals: tasks with no outgoing dependencies
+ * - Deterministic topological order
+ */
+export function buildGraph(tasks: CompiledTask[]): TaskGraph {
+	const taskMap = new Map<string, CompiledTask>();
+	for (const task of tasks) {
+		taskMap.set(task.id, task);
+	}
+
+	// ─── Compute dependents ────────────────────────────────────────────
+
+	const dependents = new Map<string, string[]>();
+	for (const task of tasks) {
+		dependents.set(task.id, []);
+	}
+	for (const task of tasks) {
+		for (const depId of task.dependencies) {
+			const list = dependents.get(depId);
+			if (list) list.push(task.id);
+		}
+	}
+
+	// ─── Find roots and terminals ─────────────────────────────────────
+
+	const roots = tasks
+		.filter((t) => t.dependencies.length === 0)
+		.map((t) => t.id);
+
+	const terminals = tasks
+		.filter((t) => (dependents.get(t.id)?.length ?? 0) === 0)
+		.map((t) => t.id);
+
+	// ─── Deterministic topological sort ────────────────────────────────
+
+	const order = topologicalSort([...tasks], taskMap);
+
+	return {
+		jobId: tasks[0]?.jobId ?? "",
+		tasks,
+		roots,
+		terminalTasks: terminals,
+		topologicalOrder: order,
+	};
+}
+
+// ─── Kahn's topological sort with deterministic tiebreaking ─────────────────
+
+function topologicalSort(
+	tasks: CompiledTask[],
+	taskMap: Map<string, CompiledTask>,
+): string[] {
+	const result: string[] = [];
+
+	// in-degree for each task
+	const inDegree = new Map<string, number>();
+	for (const task of tasks) {
+		inDegree.set(task.id, 0);
+	}
+	for (const task of tasks) {
+		for (const dep of task.dependencies) {
+			inDegree.set(dep, inDegree.get(dep) ?? 0);
+		}
+	}
+
+	// Tasks with no incoming edges
+	const ready: string[] = [];
+	for (const [id, degree] of inDegree.entries()) {
+		if (degree === 0) ready.push(id);
+	}
+
+	// Sort ready queue deterministically: by explicit priority first,
+	// then by dependency depth, then by task ID
+	const taskById = new Map(tasks.map((t) => [t.id, t]));
+
+	while (ready.length > 0) {
+		// Sort ready queue deterministically
+		ready.sort((a, b) => {
+			const ta = taskById.get(a);
+			const tb = taskById.get(b);
+			if (!ta || !tb) return a.localeCompare(b);
+			// Priority: lower number = higher priority
+			const pa = ta.priority ?? 999;
+			const pb = tb.priority ?? 999;
+			if (pa !== pb) return pa - pb;
+			// Dependency depth: tasks with more deps should come later
+			const depthA = countDepth(a, taskMap);
+			const depthB = countDepth(b, taskMap);
+			if (depthA !== depthB) return depthA - depthB;
+			// Finally, task ID string order for determinism
+			return a.localeCompare(b);
+		});
+
+		const next = ready.shift();
+		if (!next) break;
+		result.push(next);
+
+		// Reduce in-degree for dependents
+		for (const dependent of dependents.get(next ?? "") ?? []) {
+			const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+			inDegree.set(dependent, newDegree);
+			if (newDegree === 0) {
+				ready.push(dependent);
+			}
+		}
+	}
+
+	return result;
+}
+
+// ─── Dependency depth helper ───────────────────────────────────────────────
+
+function countDepth(
+	taskId: string,
+	taskMap: Map<string, CompiledTask>,
+): number {
+	const task = taskMap.get(taskId);
+	if (!task || task.dependencies.length === 0) return 0;
+	let max = 0;
+	for (const dep of task.dependencies) {
+		const d = countDepth(dep, taskMap);
+		if (d > max) max = d;
+	}
+	return max + 1;
+}
+
+// ─── Dependency map (for use by topologicalSort) ───────────────────────────
+
+const dependents = new Map<string, string[]>();
+
+export { dependents };

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

@@ -0,0 +1,38 @@
+/**
+ * Task Compiler
+ *
+ * Compiles requirements into executable, dependency-aware task graphs.
+ *
+ * @example
+ * import { compileTasks } from "@pi-harness/task-compiler";
+ *
+ * const graph = await compileTasks({
+ *   requirement: compiledRequirement,
+ *   project: projectProfile,
+ *   jobId: "job-001",
+ * });
+ */
+
+// ─── SDK Version ───────────────────────────────────────────────────────
+
+export { SDK_VERSION } from "./types.js";
+
+// ─── Main API ─────────────────────────────────────────────────────────
+
+export { compileTasks } from "./compiler.js";
+
+// ─── Exported types (for consumers) ────────────────────────────────────
+
+export type {
+	CompiledTask,
+	ComplexityEstimate,
+	DependencyInfo,
+	FileOwnership,
+	FileOwnershipMode,
+	TaskCompileInput,
+	TaskCompilerConfig,
+	TaskGraph,
+	TaskOutput,
+	TaskType,
+} from "./types.js";
+export { TaskCompilerError, TaskCompilerErrorCode } from "./types.js";