pi-crew 0.9.14 → 0.9.15

package/src/workflows/discover-workflows.ts

@@ -11,7 +11,24 @@ export interface WorkflowDiscoveryResult {
 	project: WorkflowConfig[];
 }
 
-const STEP_CONFIG_KEYS = new Set(["role", "dependsOn", "parallelGroup", "output", "reads", "model", "skills", "progress", "worktree", "verify", "task", "seedPaths", "preStepScript", "preStepArgs", "preStepTimeout", "preStepOptional"]);
+const STEP_CONFIG_KEYS = new Set([
+	"role",
+	"dependsOn",
+	"parallelGroup",
+	"output",
+	"reads",
+	"model",
+	"skills",
+	"progress",
+	"worktree",
+	"verify",
+	"task",
+	"seedPaths",
+	"preStepScript",
+	"preStepArgs",
+	"preStepTimeout",
+	"preStepOptional",
+]);
 
 function parseStepSection(id: string, body: string): WorkflowStep | undefined {
 	const lines = body.trim().split("\n");
@@ -47,24 +64,62 @@ function parseStepSection(id: string, body: string): WorkflowStep | undefined {
 		reads: config.reads === "false" ? false : parseCsv(config.reads),
 		model: config.model || undefined,
 		skills: config.skills === "false" ? false : parseCsv(config.skills),
-		progress: config.progress === "true" ? true : config.progress === "false" ? false : undefined,
-		worktree: config.worktree === "true" ? true : config.worktree === "false" ? false : undefined,
-		verify: config.verify === "true" ? true : config.verify === "false" ? false : undefined,
+		progress:
+			config.progress === "true"
+				? true
+				: config.progress === "false"
+					? false
+					: undefined,
+		worktree:
+			config.worktree === "true"
+				? true
+				: config.worktree === "false"
+					? false
+					: undefined,
+		verify:
+			config.verify === "true"
+				? true
+				: config.verify === "false"
+					? false
+					: undefined,
 		seedPaths: parseCsv(config.seedPaths) || undefined,
 		preStepScript: config.preStepScript || undefined,
 		preStepArgs: parseCsv(config.preStepArgs) || undefined,
-		preStepTimeout: parseOptionalInteger(config.preStepTimeout) ?? undefined,
-		preStepOptional: config.preStepOptional === "true" || config.preStepOptional === "1",
+		preStepTimeout:
+			parseOptionalInteger(config.preStepTimeout) ?? undefined,
+		preStepOptional:
+			config.preStepOptional === "true" || config.preStepOptional === "1",
 	};
 }
 
-const parseOptionalInteger = (value: string | undefined): number | undefined => {
+const parseOptionalInteger = (
+	value: string | undefined,
+): number | undefined => {
 	if (!value) return undefined;
 	const parsed = Number.parseInt(value, 10);
 	if (!Number.isFinite(parsed) || parsed < 1) return undefined;
 	return Math.trunc(parsed);
 };
 
+/** Parse frontmatter `topology:` field. Validates against allowed enum; bad values are silently
+ *  dropped (fall through to auto-classification in topology-analyzer). */
+const parseTopology = (
+	value: string | undefined,
+): WorkflowConfig["topology"] => {
+	if (!value) return undefined;
+	const v = value.trim().toLowerCase();
+	if (
+		v === "single" ||
+		v === "sequential" ||
+		v === "concurrent" ||
+		v === "complex-dag" ||
+		v === "dynamic"
+	) {
+		return v;
+	}
+	return undefined;
+};
+
 function hasSectionBoundary(body: string, match: RegExpMatchArray): boolean {
 	const index = match.index ?? 0;
 	if (index === 0 || body.slice(0, index).trim() === "") return true;
@@ -74,9 +129,15 @@ function hasSectionBoundary(body: string, match: RegExpMatchArray): boolean {
 }
 
 function isStepHeading(body: string, match: RegExpMatchArray): boolean {
-	const sectionStart = match.index! + match[0].length + (body[match.index! + match[0].length] === "\n" ? 1 : 0);
+	const sectionStart =
+		match.index! +
+		match[0].length +
+		(body[match.index! + match[0].length] === "\n" ? 1 : 0);
 	const nextHeading = body.slice(sectionStart).search(/^##\s+.+[^\S\n]*$/m);
-	const section = body.slice(sectionStart, nextHeading >= 0 ? sectionStart + nextHeading : body.length);
+	const section = body.slice(
+		sectionStart,
+		nextHeading >= 0 ? sectionStart + nextHeading : body.length,
+	);
 	for (const line of section.split("\n")) {
 		const trimmed = line.trim();
 		if (!trimmed) continue;
@@ -87,30 +148,58 @@ function isStepHeading(body: string, match: RegExpMatchArray): boolean {
 	return false;
 }
 
-function parseWorkflowFile(filePath: string, source: ResourceSource): WorkflowConfig | undefined {
+function parseWorkflowFile(
+	filePath: string,
+	source: ResourceSource,
+): WorkflowConfig | undefined {
 	try {
 		const content = fs.readFileSync(filePath, "utf-8");
 		const { frontmatter, body } = parseFrontmatter(content);
-		const name = frontmatter.name?.trim() || path.basename(filePath, ".workflow.md");
+		const name =
+			frontmatter.name?.trim() || path.basename(filePath, ".workflow.md");
 		const matches = [...body.matchAll(/^##\s+(.+)[^\S\n]*$/gm)];
-		const explicitStepIndexes = new Set(matches.map((match, index) => isStepHeading(body, match) ? index : undefined).filter((index): index is number => index !== undefined));
-		const effectiveMatches = matches.filter((match, index) => explicitStepIndexes.has(index) || (hasSectionBoundary(body, match) && /^[a-z][a-z0-9-]*$/.test(match[1]?.trim() ?? "")));
-		const parseMatches = explicitStepIndexes.size ? effectiveMatches : matches;
+		const explicitStepIndexes = new Set(
+			matches
+				.map((match, index) =>
+					isStepHeading(body, match) ? index : undefined,
+				)
+				.filter((index): index is number => index !== undefined),
+		);
+		const effectiveMatches = matches.filter(
+			(match, index) =>
+				explicitStepIndexes.has(index) ||
+				(hasSectionBoundary(body, match) &&
+					/^[a-z][a-z0-9-]*$/.test(match[1]?.trim() ?? "")),
+		);
+		const parseMatches = explicitStepIndexes.size
+			? effectiveMatches
+			: matches;
 		const steps: WorkflowStep[] = [];
 		for (let i = 0; i < parseMatches.length; i++) {
 			const match = parseMatches[i]!;
 			const id = match[1]!.trim();
-			const sectionStart = match.index! + match[0].length + (body[match.index! + match[0].length] === "\n" ? 1 : 0);
-			const sectionEnd = i + 1 < parseMatches.length ? parseMatches[i + 1]!.index! : body.length;
-			const step = parseStepSection(id, body.slice(sectionStart, sectionEnd));
+			const sectionStart =
+				match.index! +
+				match[0].length +
+				(body[match.index! + match[0].length] === "\n" ? 1 : 0);
+			const sectionEnd =
+				i + 1 < parseMatches.length
+					? parseMatches[i + 1]!.index!
+					: body.length;
+			const step = parseStepSection(
+				id,
+				body.slice(sectionStart, sectionEnd),
+			);
 			if (step) steps.push(step);
 		}
 		return {
 			name,
-			description: frontmatter.description?.trim() || "No description provided.",
+			description:
+				frontmatter.description?.trim() || "No description provided.",
 			source,
 			filePath,
 			maxConcurrency: parseOptionalInteger(frontmatter.maxConcurrency),
+			topology: parseTopology(frontmatter.topology),
 			steps,
 		};
 	} catch {
@@ -118,23 +207,37 @@ function parseWorkflowFile(filePath: string, source: ResourceSource): WorkflowCo
 	}
 }
 
-function readWorkflowDir(dir: string, source: ResourceSource): WorkflowConfig[] {
+function readWorkflowDir(
+	dir: string,
+	source: ResourceSource,
+): WorkflowConfig[] {
 	if (!fs.existsSync(dir)) return [];
-	const staticWorkflows = fs.readdirSync(dir)
+	const staticWorkflows = fs
+		.readdirSync(dir)
 		.filter((entry) => entry.endsWith(".workflow.md"))
 		.map((entry) => parseWorkflowFile(path.join(dir, entry), source))
-		.filter((workflow): workflow is WorkflowConfig => workflow !== undefined)
+		.filter(
+			(workflow): workflow is WorkflowConfig => workflow !== undefined,
+		)
 		.sort((a, b) => a.name.localeCompare(b.name));
 	// P2: also discover dynamic workflows (*.dwf.ts). A .dwf.ts's default export is a JS orchestrator.
-	const dynamicWorkflows = fs.readdirSync(dir)
+	const dynamicWorkflows = fs
+		.readdirSync(dir)
 		.filter((entry) => entry.endsWith(".dwf.ts"))
 		.map((entry) => parseDynamicWorkflowFile(path.join(dir, entry), source))
-		.filter((workflow): workflow is WorkflowConfig => workflow !== undefined);
-	return [...staticWorkflows, ...dynamicWorkflows].sort((a, b) => a.name.localeCompare(b.name));
+		.filter(
+			(workflow): workflow is WorkflowConfig => workflow !== undefined,
+		);
+	return [...staticWorkflows, ...dynamicWorkflows].sort((a, b) =>
+		a.name.localeCompare(b.name),
+	);
 }
 
 /** P2: a .dwf.ts is a dynamic workflow. Name = filename stem; script = the file itself. */
-function parseDynamicWorkflowFile(filePath: string, source: ResourceSource): WorkflowConfig | undefined {
+function parseDynamicWorkflowFile(
+	filePath: string,
+	source: ResourceSource,
+): WorkflowConfig | undefined {
 	try {
 		const basename = path.basename(filePath, ".dwf.ts");
 		return {
@@ -156,16 +259,28 @@ export function discoverWorkflows(cwd: string): WorkflowDiscoveryResult {
 		return { builtin: [], user: [], project: [] };
 	}
 	return {
-		builtin: readWorkflowDir(path.join(packageRoot(), "workflows"), "builtin"),
+		builtin: readWorkflowDir(
+			path.join(packageRoot(), "workflows"),
+			"builtin",
+		),
 		user: readWorkflowDir(path.join(userPiRoot(), "workflows"), "user"),
-		project: readWorkflowDir(path.join(projectCrewRoot(cwd), "workflows"), "project"),
+		project: readWorkflowDir(
+			path.join(projectCrewRoot(cwd), "workflows"),
+			"project",
+		),
 	};
 }
 
-export function allWorkflows(discovery: WorkflowDiscoveryResult | undefined): WorkflowConfig[] {
+export function allWorkflows(
+	discovery: WorkflowDiscoveryResult | undefined,
+): WorkflowConfig[] {
 	if (!discovery) return [];
 	const byName = new Map<string, WorkflowConfig>();
-	for (const workflow of [...discovery.project, ...discovery.builtin, ...discovery.user]) {
+	for (const workflow of [
+		...discovery.project,
+		...discovery.builtin,
+		...discovery.user,
+	]) {
 		byName.set(workflow.name, workflow);
 	}
 	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));

package/src/workflows/preflight-validator.ts

@@ -0,0 +1,195 @@
+// src/workflows/preflight-validator.ts
+//
+// Decision tree from .crew/knowledge.md "pi-crew USAGE THRESHOLD RULE"
+// (3-step refined rule, 2026-06-29). The validator runs synchronously
+// before executeTeamRun and returns a structured result; it NEVER throws.
+// Call sites decide whether to short-circuit (block) or just log (warn).
+//
+// The validator is a pure function: it accepts an optional eventAppender
+// in PreflightOptions for future telemetry wiring but does NOT call it
+// itself. Integration call sites (Phase 3) will fire telemetry from the
+// result they receive. This keeps the validator side-effect free and
+// trivially testable.
+
+import {
+	analyzeWorkflowTopology,
+	type WorkflowTopology,
+} from "./topology-analyzer.ts";
+import type { WorkflowConfig } from "./workflow-config.ts";
+
+export interface PreflightOptions {
+	/** When true, downgrade any block/warn to allow. Audit trail should log the override. */
+	force?: boolean;
+	/** Optional hook reserved for future telemetry wiring. Not invoked by the validator. */
+	eventAppender?: (eventsPath: string, event: object) => void;
+}
+
+export interface PreflightResult {
+	/**
+	 * Advisory severity. NEVER blocks execution — all levels log a note and proceed.
+	 * - `info`  — context-only, e.g. dynamic workflow, force-bypass acknowledged.
+	 * - `note`  — topology=`concurrent` or `complex-dag`: validated good use cases.
+	 * - `warn`  — potential misuse (single / sequential 2–3 / 4+ sequential). Provides
+	 *             the measured cost evidence (Run #3, Run #1) so the agent can decide
+	 *             whether to proceed or refactor into raw Agent calls.
+	 */
+	level: "info" | "note" | "warn";
+	message: string;
+	suggestion: string;
+	topology: WorkflowTopology;
+	/** Mirrored from TopologyAnalysis for telemetry — useful to scope warn events. */
+	stepCount: number;
+	/** Mirrored from TopologyAnalysis — what the analyzer recommends. */
+	recommendation: string;
+}
+
+function info(
+	topology: WorkflowTopology,
+	stepCount: number,
+	recommendation: string,
+	message: string,
+): PreflightResult {
+	return {
+		level: "info",
+		message,
+		suggestion: "",
+		topology,
+		stepCount,
+		recommendation,
+	};
+}
+
+function note(
+	topology: WorkflowTopology,
+	stepCount: number,
+	recommendation: string,
+	message: string,
+): PreflightResult {
+	return {
+		level: "note",
+		message,
+		suggestion: "Validated use case — proceeding.",
+		topology,
+		stepCount,
+		recommendation,
+	};
+}
+
+function warn(
+	topology: WorkflowTopology,
+	stepCount: number,
+	recommendation: string,
+	message: string,
+	suggestion: string,
+): PreflightResult {
+	return {
+		level: "warn",
+		message,
+		suggestion,
+		topology,
+		stepCount,
+		recommendation,
+	};
+}
+
+/**
+ * Validate workflow usage against the topology threshold rule.
+ *
+ * **Returns a PreflightResult. NEVER blocks the call.** The validator is advisory only —
+ * the agent (caller) decides whether to proceed, refactor, or override. This honors
+ * Pi's design philosophy: tooling provides information, agents exercise judgment.
+ *
+ * Severity levels:
+ * - `info`  — context-only (dynamic, force-bypass acknowledged).
+ * - `note`  — validated use case (`concurrent`, `complex-dag`). Proceed.
+ * - `warn`  — potential inefficiency. Provides measured cost evidence so the agent
+ *             can weigh the trade-off (e.g. audit-trail value vs. raw-call speed).
+ *
+ * No `block` level exists — there is no scenario where pi-crew hard-rejects a call.
+ * The agent always gets to decide.
+ */
+export function validateWorkflowUsage(
+	workflow: WorkflowConfig,
+	options: PreflightOptions = {},
+): PreflightResult {
+	const analysis = analyzeWorkflowTopology(workflow);
+	const { topology, stepCount, recommendation } = analysis;
+
+	// Rule 0: dynamic workflows are runtime-decided.
+	if (topology === "dynamic") {
+		return info(
+			topology,
+			stepCount,
+			recommendation,
+			"Dynamic workflow — runtime decides topology.",
+		);
+	}
+
+	// Rule 0b: explicit force-bypass acknowledged (still log it).
+	if (options.force === true) {
+		return info(
+			topology,
+			stepCount,
+			recommendation,
+			`Force-bypassed preflight acknowledged (topology=${topology}, stepCount=${stepCount}). Proceeding as requested.`,
+		);
+	}
+
+	// Rule 1: SINGLE — advisory note that raw Agent would be simpler.
+	if (topology === "single") {
+		return warn(
+			topology,
+			stepCount,
+			recommendation,
+			"Single-task workflow: pi-crew overhead exceeds benefit; raw Agent tool would be ~30× faster and ~5× cheaper. Proceeding anyway — proceed only if audit trail or team coordination matters here.",
+			"Consider using the raw Agent tool instead. If proceeding, no action needed — pi-crew will run the workflow as configured.",
+		);
+	}
+
+	// Rule 2: SEQUENTIAL — note per chain length with measured cost evidence.
+	if (topology === "sequential") {
+		if (stepCount === 2) {
+			return warn(
+				topology,
+				stepCount,
+				recommendation,
+				"2-step sequential chain: pi-crew adds overhead; 2 raw Agent calls would be faster. Proceeding anyway.",
+				"Consider 2 raw Agent calls in one turn if speed matters. Otherwise, no action needed.",
+			);
+		}
+		if (stepCount === 3) {
+			return warn(
+				topology,
+				stepCount,
+				recommendation,
+				"3-step sequential chain: measured 5.7× slower and 1.9× costlier than 3 raw Agent calls (Run #3 in .crew/state/runs/). Proceeding anyway.",
+				"Consider 3 raw Agent calls. If audit trail justifies overhead, proceed.",
+			);
+		}
+		return warn(
+			topology,
+			stepCount,
+			recommendation,
+			`${stepCount}-step sequential chain: longer chains may justify pi-crew for audit/dag-context reasons, but raw Agent calls remain faster. Proceeding anyway.`,
+			"Consider chaining raw Agent calls if speed matters. Otherwise, no action needed.",
+		);
+	}
+
+	// Rule 3: CONCURRENT — validated good use case, informational note.
+	if (topology === "concurrent") {
+		return note(
+			topology,
+			stepCount,
+			recommendation,
+			`Validated use case: ${analysis.fanOutDegree}-way parallel fan-out. pi-crew's parallelism wins here.`,
+		);
+	}
+
+	// Rule 4: COMPLEX_DAG — validated good use case, informational note.
+	return note(
+		topology,
+		stepCount,
+		recommendation,
+		`Validated use case: complex DAG with ${stepCount} steps, depth ${analysis.dagDepth}. pi-crew's dependency-context injection and adaptive-plan support wins here.`,
+	);
+}

package/src/workflows/topology-analyzer.ts

@@ -0,0 +1,219 @@
+// 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/workflow-config.ts

@@ -48,6 +48,17 @@ export interface WorkflowConfig {
 	/** 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";
 }
 
 /** A dynamic workflow (runtime === "dynamic"). steps is empty — the script is the source of truth. */