pi-crew 0.9.50 → 0.9.52

package/src/workflows/topology-analyzer.ts

@@ -1,203 +0,0 @@
-// src/workflows/topology-analyzer.ts
-//
-// Workflow topology classifier. Given a WorkflowConfig, returns a TopologyAnalysis
-// describing the structural shape (single / sequential / concurrent / complex-dag
-// / dynamic). The shape is used by the preflight validator to enforce the
-// "don't use pi-crew for sequential independent agents" rule from .crew/knowledge.md.
-//
-// Algorithm (high level):
-//   1. runtime === "dynamic"  →  DYNAMIC  (chain/script workflows decide at runtime)
-//   2. stepCount === 1        →  SINGLE   (one step: no concurrency, no DAG)
-//   3. parallelGroupCount >= 1 AND max-fanout >= 3  →  CONCURRENT
-//   4. stepCount >= 4 AND has-multi-deps  →  COMPLEX_DAG
-//   5. else                   →  SEQUENTIAL
-//
-// "Has-multi-deps" = at least one step lists 2+ dependsOn. This is the
-// unambiguous signal of a branching DAG (diamond patterns, fan-in joins).
-// Plain linear chains with high depth are still SEQUENTIAL — Run #3 fast-fix
-// (3 steps linear, depth 3) and the default workflow (4 steps linear, depth 4)
-// are both sequential by this rule; raw Agent calls are faster for both.
-
-import type { WorkflowConfig, WorkflowStep } from "./workflow-config.ts";
-
-export type WorkflowTopology = "single" | "sequential" | "concurrent" | "complex-dag" | "dynamic";
-
-export type TopologyRecommendation = "raw_agent" | "fast_fix" | "parallel_research" | "implementation_adaptive" | "any";
-
-export interface TopologyAnalysis {
-	topology: WorkflowTopology;
-	stepCount: number;
-	parallelGroupCount: number;
-	fanOutDegree: number;
-	dagDepth: number;
-	recommendation: TopologyRecommendation;
-	reason: string;
-}
-
-/** Distinct parallelGroup values across all steps. Empty if no step sets a group. */
-export function parallelGroupsFromSteps(steps: WorkflowStep[]): Set<string> {
-	const out = new Set<string>();
-	for (const step of steps) {
-		if (step.parallelGroup !== undefined) out.add(step.parallelGroup);
-	}
-	return out;
-}
-
-/** Max group size across all parallelGroup values. 0 if no step sets a group. */
-export function fanOutDegreeFromSteps(steps: WorkflowStep[]): number {
-	const counts = new Map<string, number>();
-	for (const step of steps) {
-		if (step.parallelGroup === undefined) continue;
-		counts.set(step.parallelGroup, (counts.get(step.parallelGroup) ?? 0) + 1);
-	}
-	let max = 0;
-	for (const count of counts.values()) if (count > max) max = count;
-	return max;
-}
-
-/**
- * Longest-path DAG depth from roots. A root is a step with no dependsOn.
- * Returns 0 for an empty list, 1 for a list of roots only with no inter-step deps.
- *
- * Defensive: a step depending on an unknown id is treated as a root
- * (validate-workflow.ts catches real cycles before this runs; this is
- * belt-and-suspenders against malformed inputs).
- */
-export function dagDepthFromSteps(steps: WorkflowStep[]): number {
-	if (steps.length === 0) return 0;
-	const ids = new Set(steps.map((s) => s.id));
-	// Build adjacency and indegree. Unknown deps are dropped to avoid phantom edges.
-	const indeg = new Map<string, number>();
-	const adj = new Map<string, string[]>();
-	for (const step of steps) {
-		const deps = (step.dependsOn ?? []).filter((d) => ids.has(d));
-		indeg.set(step.id, deps.length);
-		// step.id's parents are deps; deps's children include step.id.
-		adj.set(step.id, adj.get(step.id) ?? []);
-		for (const dep of deps) {
-			const children = adj.get(dep) ?? [];
-			children.push(step.id);
-			adj.set(dep, children);
-		}
-	}
-	// Kahn-style BFS. depth[v] = max(depth[parent]) + 1, roots = 1.
-	const depth = new Map<string, number>();
-	const queue: string[] = [];
-	for (const [id, n] of indeg) {
-		if (n === 0) {
-			depth.set(id, 1);
-			queue.push(id);
-		}
-	}
-	let maxDepth = 0;
-	while (queue.length > 0) {
-		const v = queue.shift()!;
-		const dv = depth.get(v) ?? 0;
-		if (dv > maxDepth) maxDepth = dv;
-		for (const child of adj.get(v) ?? []) {
-			const cand = dv + 1;
-			if (cand > (depth.get(child) ?? 0)) depth.set(child, cand);
-			indeg.set(child, (indeg.get(child) ?? 0) - 1);
-			if ((indeg.get(child) ?? 0) === 0) queue.push(child);
-		}
-	}
-	return maxDepth;
-}
-
-/** True if at least one step lists 2+ dependsOn entries. */
-function hasMultiDeps(steps: WorkflowStep[]): boolean {
-	for (const step of steps) {
-		if ((step.dependsOn?.length ?? 0) >= 2) return true;
-	}
-	return false;
-}
-
-/**
- * Classify a workflow's topology. See file header for the rule order.
- * Pure function — no I/O, no side effects, no exceptions.
- */
-export function analyzeWorkflowTopology(workflow: WorkflowConfig): TopologyAnalysis {
-	// Chain/dynamic workflows: runtime decides the topology at execution time.
-	// Don't try to classify the empty `steps: []` (DynamicWorkflowConfig forces
-	// it to be empty).
-	if (workflow.runtime === "dynamic") {
-		return {
-			topology: "dynamic",
-			stepCount: 0,
-			parallelGroupCount: 0,
-			fanOutDegree: 0,
-			dagDepth: 0,
-			recommendation: "any",
-			reason: "Chain/dynamic workflow — runtime decides topology",
-		};
-	}
-
-	const steps = workflow.steps;
-	const stepCount = steps.length;
-	const parallelGroupCount = parallelGroupsFromSteps(steps).size;
-	const fanOutDegree = fanOutDegreeFromSteps(steps);
-	const dagDepth = dagDepthFromSteps(steps);
-
-	// Explicit topology override from frontmatter `topology:` field.
-	// When set, the author has already classified the workflow — respect that.
-	// We still compute structural metrics so telemetry can show the delta.
-	if (workflow.topology !== undefined && workflow.topology !== "dynamic") {
-		const recommendation: TopologyRecommendation =
-			workflow.topology === "single" || workflow.topology === "sequential"
-				? "raw_agent"
-				: workflow.topology === "concurrent"
-					? "parallel_research"
-					: workflow.topology === "complex-dag"
-						? "implementation_adaptive"
-						: "any";
-		return {
-			topology: workflow.topology,
-			stepCount,
-			parallelGroupCount,
-			fanOutDegree,
-			dagDepth,
-			recommendation,
-			reason: `Explicit topology from frontmatter: '${workflow.topology}'`,
-		};
-	}
-
-	let topology: WorkflowTopology;
-	let recommendation: TopologyRecommendation;
-	let reason: string;
-
-	// Note: explicit `workflow.topology` override is handled BEFORE the variable
-	// declarations below (in the block above). If we reach here, auto-classify.
-
-	if (stepCount === 1) {
-		topology = "single";
-		recommendation = "raw_agent";
-		reason = "Single-task workflow: no concurrency or DAG structure to justify pi-crew overhead.";
-	} else if (parallelGroupCount >= 1 && fanOutDegree >= 3) {
-		topology = "concurrent";
-		recommendation = "parallel_research";
-		reason = `Concurrent fan-out: ${fanOutDegree} steps in parallel group(s) of size ≥3.`;
-	} else if (stepCount >= 4 && hasMultiDeps(steps)) {
-		topology = "complex-dag";
-		recommendation = "implementation_adaptive";
-		reason = `Complex DAG: ${stepCount} steps with branching (≥2 deps on ≥1 node), depth ${dagDepth}.`;
-	} else {
-		topology = "sequential";
-		if (stepCount <= 3) {
-			recommendation = "raw_agent";
-			reason = `Sequential chain of ${stepCount} steps — raw Agent calls are faster.`;
-		} else {
-			recommendation = "fast_fix";
-			reason = `Sequential chain of ${stepCount} steps — audit-trail-justified, but raw calls remain faster.`;
-		}
-	}
-
-	return {
-		topology,
-		stepCount,
-		parallelGroupCount,
-		fanOutDegree,
-		dagDepth,
-		recommendation,
-		reason,
-	};
-}

package/src/workflows/validate-workflow.ts

@@ -1,50 +0,0 @@
-import type { TeamConfig } from "../teams/team-config.ts";
-import type { WorkflowConfig } from "./workflow-config.ts";
-
-export function validateWorkflowForTeam(workflow: WorkflowConfig, team: TeamConfig): string[] {
-	const errors: string[] = [];
-	const roles = new Set(team.roles.map((role) => role.name));
-	const stepIds = new Set<string>();
-
-	for (const step of workflow.steps) {
-		if (stepIds.has(step.id)) errors.push(`Duplicate workflow step id '${step.id}'.`);
-		stepIds.add(step.id);
-		if (!roles.has(step.role)) errors.push(`Step '${step.id}' references unknown team role '${step.role}'.`);
-	}
-
-	for (const step of workflow.steps) {
-		for (const dep of step.dependsOn ?? []) {
-			if (!stepIds.has(dep)) errors.push(`Step '${step.id}' depends on unknown step '${dep}'.`);
-		}
-	}
-
-	// Validate output field types
-	for (const step of workflow.steps) {
-		if (step.output !== undefined && step.output !== false && typeof step.output !== "string") {
-			errors.push(`Step '${step.id}' has invalid 'output' field: expected string or false, got ${typeof step.output}.`);
-		}
-		if (typeof step.output === "string" && step.output.trim() === "") {
-			errors.push(`Step '${step.id}' has empty 'output' string.`);
-		}
-	}
-
-	const visiting = new Set<string>();
-	const visited = new Set<string>();
-	const byId = new Map(workflow.steps.map((step) => [step.id, step]));
-
-	function visit(id: string, trail: string[]): void {
-		if (visited.has(id)) return;
-		if (visiting.has(id)) {
-			errors.push(`Workflow dependency cycle detected: ${[...trail, id].join(" -> ")}.`);
-			return;
-		}
-		visiting.add(id);
-		const step = byId.get(id);
-		for (const dep of step?.dependsOn ?? []) visit(dep, [...trail, id]);
-		visiting.delete(id);
-		visited.add(id);
-	}
-
-	for (const step of workflow.steps) visit(step.id, []);
-	return [...new Set(errors)];
-}

package/src/workflows/workflow-config.ts

@@ -1,70 +0,0 @@
-import type { ResourceSource } from "../agents/agent-config.ts";
-
-export interface WorkflowStep {
-	id: string;
-	role: string;
-	task: string;
-	dependsOn?: string[];
-	parallelGroup?: string;
-	output?: string | false;
-	reads?: string[] | false;
-	model?: string;
-	/** Additional skills for this step; false disables role-default injected skills for this step. */
-	skills?: string[] | false;
-	progress?: boolean;
-	worktree?: boolean;
-	verify?: boolean;
-	/** Per-step files to overlay into the worktree (in addition to global worktree.seedPaths).
-	 * Useful when only certain steps need access to local drafts or scripts. */
-	seedPaths?: string[];
-	/** Path to a deterministic script to run before dispatching the LLM worker.
-	 * Script stdout is injected into the worker's prompt as context.
-	 * Pattern origin: Understand-Anything deterministic pre-step pattern. */
-	preStepScript?: string;
-	/** Arguments for preStepScript. Passed as positional args. */
-	preStepArgs?: string[];
-	/** Timeout in ms for preStepScript. Default: 30000. */
-	preStepTimeout?: number;
-	/** Round 21 (E4): if true, a failing preStepScript does NOT abort the task.
-	 * The failure is logged as a warning and the task proceeds without the
-	 * pre-step output. Use for advisory hooks (e.g. optional test runs) whose
-	 * failure shouldn't block the workflow. Default: false (fail-fast). */
-	preStepOptional?: boolean;
-}
-
-export interface WorkflowConfig {
-	name: string;
-	description: string;
-	source: ResourceSource;
-	filePath: string;
-	steps: WorkflowStep[];
-	maxConcurrency?: number;
-	/** P2 dynamic-workflow discriminator. Default "static" (the .workflow.md step-list model).
-	 *  "dynamic" = the workflow is a JS/TS script (.dwf.ts) run via dynamic-workflow-runner.
-	 *  Backward-compatible: absent = "static". */
-	runtime?: "static" | "dynamic";
-	/** For runtime:"dynamic" — relative/absolute path to the .dwf.ts script. Unused for static. */
-	dynamicScript?: string;
-	/** For runtime:"dynamic" — per-workflow token budget. When set, ctx.agent() auto-rejects with
-	 *  ok:false once exhausted. Accumulated from each agent run's reported usage. */
-	maxTokenBudget?: number;
-	/** Explicit topology classification from frontmatter `topology:` field.
-	 *  When set, overrides the auto-classified topology in analyzeWorkflowTopology().
-	 *  Used by preflight-validator to enforce "don't use pi-crew for sequential chains".
-	 *  Valid values: 'single' | 'sequential' | 'concurrent' | 'complex-dag' | 'dynamic'.
-	 *  Absent = auto-classify from step structure (default). */
-	topology?: "single" | "sequential" | "concurrent" | "complex-dag" | "dynamic";
-	/** Round 25 (M6): coalesce micro-tasks. Default false (off). When true,
-	 *  multiple ready tasks sharing role + cwd are grouped into a single
-	 *  multi-task worker prompt to reduce per-task cold-start cost. Disabled
-	 *  in v0.9.17 unless the workflow author opts in. See
-	 *  src/runtime/coalesce-tasks.ts. */
-	coalesceMicroTasks?: boolean;
-}
-
-/** A dynamic workflow (runtime === "dynamic"). steps is empty — the script is the source of truth. */
-export interface DynamicWorkflowConfig extends WorkflowConfig {
-	runtime: "dynamic";
-	dynamicScript: string;
-	steps: [];
-}

package/src/workflows/workflow-serializer.ts

@@ -1,32 +0,0 @@
-import type { WorkflowConfig, WorkflowStep } from "./workflow-config.ts";
-
-function serializeStep(step: WorkflowStep): string[] {
-	const lines = [`## ${step.id}`, `role: ${step.role}`];
-	if (step.dependsOn?.length) lines.push(`dependsOn: ${step.dependsOn.join(", ")}`);
-	if (step.parallelGroup) lines.push(`parallelGroup: ${step.parallelGroup}`);
-	if (step.output === false) lines.push("output: false");
-	else if (step.output) lines.push(`output: ${step.output}`);
-	if (step.reads === false) lines.push("reads: false");
-	else if (Array.isArray(step.reads) && step.reads.length > 0) lines.push(`reads: ${step.reads.join(", ")}`);
-	if (step.model) lines.push(`model: ${step.model}`);
-	if (step.skills === false) lines.push("skills: false");
-	else if (Array.isArray(step.skills) && step.skills.length > 0) lines.push(`skills: ${step.skills.join(", ")}`);
-	if (step.progress !== undefined) lines.push(`progress: ${step.progress ? "true" : "false"}`);
-	if (step.worktree !== undefined) lines.push(`worktree: ${step.worktree ? "true" : "false"}`);
-	if (step.verify !== undefined) lines.push(`verify: ${step.verify ? "true" : "false"}`);
-	lines.push("", step.task.trim(), "");
-	return lines;
-}
-
-export function serializeWorkflow(workflow: WorkflowConfig): string {
-	const lines = [
-		"---",
-		`name: ${workflow.name}`,
-		`description: ${workflow.description}`,
-		...(workflow.maxConcurrency !== undefined ? [`maxConcurrency: ${workflow.maxConcurrency}`] : []),
-		"---",
-		"",
-		...workflow.steps.flatMap(serializeStep),
-	];
-	return lines.join("\n");
-}

package/src/worktree/branch-freshness.ts

@@ -1,112 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
-import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
-
-// Read-only git operations only (rev-list, rev-parse, log). Sanitize env to
-// avoid leaking API keys/tokens to any git hook/alias/credential-helper.
-// C-1 fix (code-review 2026-06-23): previously inherited the full parent env.
-const GIT_SAFE_ENV = sanitizeEnvSecrets(process.env, {
-	allowList: [
-		"PATH",
-		"HOME",
-		"USER",
-		...WINDOWS_ESSENTIAL_ENV_VARS,
-		"SHELL",
-		"TERM",
-		"LANG",
-		"LC_ALL",
-		"GIT_CONFIG_GLOBAL",
-		"GIT_CONFIG_SYSTEM",
-		"GIT_EXEC_PATH",
-	],
-});
-
-export type BranchFreshnessStatus = "fresh" | "stale" | "diverged" | "unknown";
-export type StaleBranchPolicy = "warn" | "block" | "auto_rebase" | "auto_merge_forward";
-
-export interface BranchFreshness {
-	status: BranchFreshnessStatus;
-	branch?: string;
-	mainRef: string;
-	ahead: number;
-	behind: number;
-	missingFixes: string[];
-	message: string;
-	error?: string;
-}
-
-function git(cwd: string, args: string[]): string {
-	return execFileSync("git", args, {
-		cwd,
-		encoding: "utf-8",
-		stdio: ["ignore", "pipe", "pipe"],
-		env: GIT_SAFE_ENV,
-		windowsHide: true,
-	}).trim();
-}
-
-function count(cwd: string, range: string): number {
-	const raw = git(cwd, ["rev-list", "--count", range]);
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) ? parsed : 0;
-}
-
-export function checkBranchFreshness(cwd: string, mainRef = "main"): BranchFreshness {
-	try {
-		git(cwd, ["rev-parse", "--is-inside-work-tree"]);
-		const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
-		const behind = count(cwd, `${branch}..${mainRef}`);
-		const ahead = count(cwd, `${mainRef}..${branch}`);
-		const missingFixes =
-			behind > 0
-				? git(cwd, ["log", "--format=%s", `${branch}..${mainRef}`])
-						.split("\n")
-						.map((line) => line.trim())
-						.filter(Boolean)
-				: [];
-		if (behind === 0)
-			return {
-				status: "fresh",
-				branch,
-				mainRef,
-				ahead,
-				behind,
-				missingFixes,
-				message: `Branch '${branch}' is fresh against ${mainRef}.`,
-			};
-		if (ahead > 0)
-			return {
-				status: "diverged",
-				branch,
-				mainRef,
-				ahead,
-				behind,
-				missingFixes,
-				message: `Branch '${branch}' diverged from ${mainRef}: ahead=${ahead}, behind=${behind}.`,
-			};
-		return {
-			status: "stale",
-			branch,
-			mainRef,
-			ahead,
-			behind,
-			missingFixes,
-			message: `Branch '${branch}' is ${behind} commit(s) behind ${mainRef}.`,
-		};
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		return {
-			status: "unknown",
-			mainRef,
-			ahead: 0,
-			behind: 0,
-			missingFixes: [],
-			message: "Branch freshness could not be determined.",
-			error: message,
-		};
-	}
-}
-
-export function shouldBlockForBranchFreshness(freshness: BranchFreshness, policy: StaleBranchPolicy = "warn"): boolean {
-	return policy === "block" && (freshness.status === "stale" || freshness.status === "diverged");
-}