pi-crew 0.9.13 → 0.9.15

package/src/state/types.ts

@@ -201,6 +201,9 @@ export interface TeamRunManifest {
 	args?: unknown;
 	summary?: string;
 	policyDecisions?: PolicyDecision[];
+	/** #2 (assessment): goal-achievement verdict — kills the silent false-green. */
+	goalAchieved?: boolean | "unknown";
+	goalAchievementNote?: string;
 }
 
 export interface UsageState {

package/src/ui/widget/index.ts

@@ -42,7 +42,7 @@ export function getRenderWidth(width?: number): number {
 	if (Number.isFinite(stdoutCols) && stdoutCols! > 0) return Math.floor(stdoutCols!);
 	return DEFAULT_WIDGET_WIDTH;
 }
-export { notificationBadge } from "./widget-formatters.ts";
+export { notificationBadge, NOTIFICATION_BADGE_CAP } from "./widget-formatters.ts";
 
 // ── Constants ─────────────────────────────────────────────────────────
 

package/src/ui/widget/widget-formatters.ts

@@ -144,9 +144,22 @@ export function agentStats(agent: CrewAgentRecord, liveHandle?: LiveAgentHandle)
 
 // ── Notification badge ────────────────────────────────────────────────
 
+// Bug 021: the bell glyph 🔔 was misread as "queued messages" — users saw
+// `🔔227` and concluded there were 227 pending items, when the value is a
+// CUMULATIVE warning/error/critical count with zero actual queue behind it.
+// Fix: relabel to an explicit "alerts" segment (no bell) and cap the display
+// at 99+ (standard badge practice). The cumulative count stays accurate
+// internally (widgetState.notificationCount) and remains fully logged in
+// .crew/state/notifications/YYYY-MM-DD.jsonl — this bounds presentation only.
+// Deeper fixes (decay window, owner-scope, auto-reset on all-runs-terminal,
+// full deprecation) are product decisions documented in
+// docs/bugs/bug-021-notification-badge-counter-misleading.md.
+export const NOTIFICATION_BADGE_CAP = 99;
+
 export function notificationBadge(count: number | undefined, env: NodeJS.ProcessEnv = process.env): string {
 	if (!count || count <= 0) return "";
 	const term = `${env.TERM ?? ""} ${env.WT_SESSION ?? ""} ${env.TERM_PROGRAM ?? ""}`.toLowerCase();
 	const supportsEmoji = !term.includes("dumb") && env.NO_COLOR !== "1";
-	return supportsEmoji ? ` 🔔${count}` : ` [!${count}]`;
+	const label = count > NOTIFICATION_BADGE_CAP ? `${NOTIFICATION_BADGE_CAP}+ alerts` : `${count} alerts`;
+	return supportsEmoji ? ` · ${label}` : ` [${label}]`;
 }

package/src/ui/widget/widget-renderer.ts

@@ -15,6 +15,7 @@ import { computeLiveDurationMs } from "../live-duration.ts";
 import { getTaskUsage } from "../../runtime/usage-tracker.ts";
 import { agentActivity, agentStats, elapsed, formatTokensCompact, notificationBadge } from "./widget-formatters.ts";
 import { activeWidgetRuns, shortRunLabel } from "./widget-model.ts";
+import { isFinishedRunStatus } from "../../runtime/process-status.ts";
 import type { WidgetRun } from "./widget-types.ts";
 
 const MAX_AGENTS_DISPLAY = 3;
@@ -69,6 +70,7 @@ export function buildWidgetLines(cwd: string, frame = 0, maxLines = 8, providedR
 		});
 		const completed = agents.filter((a) => a.status === "completed").length;
 		const runGlyph = iconForStatus(run.status, { runningGlyph });
+		const isTerminal = isFinishedRunStatus(run.status);
 		// Run progress line. v1–v3 flickered on snapshot.tasks state, v4 was
 		// too minimal (`0/1 agents` only), v5 duplicated the worker activity
 		// line (tools/tokens/duration already shown one row below). v6 (this)
@@ -81,10 +83,19 @@ export function buildWidgetLines(cwd: string, frame = 0, maxLines = 8, providedR
 		// for a healthy run), and `run.createdAt` is immutable. The format
 		// shape `"X/Y agents · Ns"` is therefore truly invariant: same number
 		// of `·`-separated fields, same field meanings, every render tick.
+		//
+		// Bug 022 (timer-fix + label): for TERMINAL runs (failed/cancelled/
+		// completed) the elapsed counter previously kept ticking up forever
+		// from createdAt (a failed run showed `2028s` and climbing, read as
+		// "still running"). Now it FREEZES at updatedAt (when the run
+		// reached its terminal status). The status label is also surfaced
+		// explicitly so the row cannot be misread as an active run.
 		const agentCountText = `${completed}/${agents.length} agents`;
-		const runElapsedMs = Math.max(0, Date.now() - new Date(run.createdAt).getTime());
+		const runEndMs = isTerminal ? new Date(run.updatedAt).getTime() : Date.now();
+		const runElapsedMs = Math.max(0, Number.isFinite(runEndMs) ? runEndMs - new Date(run.createdAt).getTime() : 0);
 		const runElapsedText = `${Math.floor(runElapsedMs / 1000)}s`;
-		const progressPart = `${agentCountText} · ${runElapsedText}`;
+		const statusLabel = isTerminal ? ` · ${run.status}` : "";
+		const progressPart = `${agentCountText} · ${runElapsedText}${statusLabel}`;
 		lines.push(truncate(`├─ ${runGlyph} ${shortRunLabel(run)} · ${progressPart} · ${run.runId.slice(-8)}`, width));
 
 		const liveForRun = listLiveAgents().filter((a) => a.runId === run.runId);

package/src/utils/redaction.ts

@@ -19,6 +19,24 @@ export const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]
 // Full mitigation ladder: (1) redaction here + at artifact-write; (2) Phase 1.5
 // sanitized-env verification; (3) sandbox (deferred).
 
+// Exclusion list: LLM usage-count key names that contain "token" but are
+// observable metrics, NOT credentials. These must NEVER be redacted so that
+// token-usage observability in events.jsonl is preserved. The isSecretKey()
+// keyword-scan matches '_token' in 'prompt_tokens' (underscore + "token"),
+// falsely classifying usage counts as secrets. See performance/quality
+// assessment fix #5.
+const TOKEN_COUNT_KEYS = new Set([
+	"prompt_tokens",
+	"completion_tokens",
+	"total_tokens",
+	"cached_tokens",
+	"reasoning_tokens",
+	"cached_read_tokens",
+	"cached_write_tokens",
+	"input_tokens",
+	"output_tokens",
+]);
+
 // JWT — three base64url segments separated by dots, distinctive "eyJ" headers.
 // Linear: single + on [A-Za-z0-9_-] per segment, no nesting.
 export const JWT_PATTERN = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
@@ -43,6 +61,8 @@ export const STRIPE_KEY_PATTERN = /(?<![A-Za-z0-9_])sk_live_[0-9a-zA-Z]{24}(?![0
 // a more complex regex, catastrophic backtracking (ReDoS) could result.
 // Any modifications must preserve O(n) complexity where n = keyName.length.
 export function isSecretKey(keyName: string): boolean {
+	// Fast path: known token-count keys are never secrets.
+	if (TOKEN_COUNT_KEYS.has(keyName.toLowerCase())) return false;
 	// Fast path: common secret key names (safe anchored regex, no backtracking)
 	const lower = keyName.toLowerCase();
 	if (/^(token|apikey|api_key|password|secret|credential|authorization|privatekey|private_key)$/.test(lower)) {

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.`,
+	);
+}