pi-crew 0.2.3 → 0.2.4

package/src/workflows/discover-workflows.ts

@@ -1,139 +1,139 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ResourceSource } from "../agents/agent-config.ts";
-import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
-import { packageRoot, projectCrewRoot, userPiRoot } from "../utils/paths.ts";
-import type { WorkflowConfig, WorkflowStep } from "./workflow-config.ts";
-
-export interface WorkflowDiscoveryResult {
-	builtin: WorkflowConfig[];
-	user: WorkflowConfig[];
-	project: WorkflowConfig[];
-}
-
-const STEP_CONFIG_KEYS = new Set(["role", "dependsOn", "parallelGroup", "output", "reads", "model", "skills", "progress", "worktree", "verify", "task"]);
-
-function parseStepSection(id: string, body: string): WorkflowStep | undefined {
-	const lines = body.trim().split("\n");
-	const config: Record<string, string> = {};
-	const taskLines: string[] = [];
-	let inTask = false;
-	let sawConfig = false;
-	for (const line of lines) {
-		if (!inTask) {
-			if (line.trim() === "") {
-				if (!sawConfig) continue;
-				inTask = true;
-				continue;
-			}
-			const match = line.match(/^([\w-]+):\s*(.*)$/);
-			if (match) {
-				config[match[1]!.trim()] = match[2]!.trim();
-				sawConfig = true;
-				continue;
-			}
-			inTask = true;
-		}
-		taskLines.push(line);
-	}
-	const role = config.role || id;
-	return {
-		id,
-		role,
-		task: taskLines.join("\n").trim() || config.task || "{goal}",
-		dependsOn: parseCsv(config.dependsOn),
-		parallelGroup: config.parallelGroup || undefined,
-		output: config.output === "false" ? false : config.output || 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,
-	};
-}
-
-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);
-};
-
-function hasSectionBoundary(body: string, match: RegExpMatchArray): boolean {
-	const index = match.index ?? 0;
-	if (index === 0 || body.slice(0, index).trim() === "") return true;
-	const prev = body.slice(Math.max(0, index - 2), index);
-	// Accept blank line or single newline before heading.
-	return prev === "\n\n" || prev.endsWith("\n");
-}
-
-function isStepHeading(body: string, match: RegExpMatchArray): boolean {
-	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);
-	for (const line of section.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		const config = trimmed.match(/^([\w-]+):\s*(.*)$/);
-		if (config && STEP_CONFIG_KEYS.has(config[1]!)) return true;
-		return false;
-	}
-	return false;
-}
-
-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 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 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));
-			if (step) steps.push(step);
-		}
-		return {
-			name,
-			description: frontmatter.description?.trim() || "No description provided.",
-			source,
-			filePath,
-			maxConcurrency: parseOptionalInteger(frontmatter.maxConcurrency),
-			steps,
-		};
-	} catch {
-		return undefined;
-	}
-}
-
-function readWorkflowDir(dir: string, source: ResourceSource): WorkflowConfig[] {
-	if (!fs.existsSync(dir)) return [];
-	return fs.readdirSync(dir)
-		.filter((entry) => entry.endsWith(".workflow.md"))
-		.map((entry) => parseWorkflowFile(path.join(dir, entry), source))
-		.filter((workflow): workflow is WorkflowConfig => workflow !== undefined)
-		.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-export function discoverWorkflows(cwd: string): WorkflowDiscoveryResult {
-	return {
-		builtin: readWorkflowDir(path.join(packageRoot(), "workflows"), "builtin"),
-		user: readWorkflowDir(path.join(userPiRoot(), "workflows"), "user"),
-		project: readWorkflowDir(path.join(projectCrewRoot(cwd), "workflows"), "project"),
-	};
-}
-
-export function allWorkflows(discovery: WorkflowDiscoveryResult): WorkflowConfig[] {
-	const byName = new Map<string, WorkflowConfig>();
-	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));
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ResourceSource } from "../agents/agent-config.ts";
+import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
+import { packageRoot, projectCrewRoot, userPiRoot } from "../utils/paths.ts";
+import type { WorkflowConfig, WorkflowStep } from "./workflow-config.ts";
+
+export interface WorkflowDiscoveryResult {
+	builtin: WorkflowConfig[];
+	user: WorkflowConfig[];
+	project: WorkflowConfig[];
+}
+
+const STEP_CONFIG_KEYS = new Set(["role", "dependsOn", "parallelGroup", "output", "reads", "model", "skills", "progress", "worktree", "verify", "task"]);
+
+function parseStepSection(id: string, body: string): WorkflowStep | undefined {
+	const lines = body.trim().split("\n");
+	const config: Record<string, string> = {};
+	const taskLines: string[] = [];
+	let inTask = false;
+	let sawConfig = false;
+	for (const line of lines) {
+		if (!inTask) {
+			if (line.trim() === "") {
+				if (!sawConfig) continue;
+				inTask = true;
+				continue;
+			}
+			const match = line.match(/^([\w-]+):\s*(.*)$/);
+			if (match) {
+				config[match[1]!.trim()] = match[2]!.trim();
+				sawConfig = true;
+				continue;
+			}
+			inTask = true;
+		}
+		taskLines.push(line);
+	}
+	const role = config.role || id;
+	return {
+		id,
+		role,
+		task: taskLines.join("\n").trim() || config.task || "{goal}",
+		dependsOn: parseCsv(config.dependsOn),
+		parallelGroup: config.parallelGroup || undefined,
+		output: config.output === "false" ? false : config.output || 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,
+	};
+}
+
+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);
+};
+
+function hasSectionBoundary(body: string, match: RegExpMatchArray): boolean {
+	const index = match.index ?? 0;
+	if (index === 0 || body.slice(0, index).trim() === "") return true;
+	const prev = body.slice(Math.max(0, index - 2), index);
+	// Accept blank line or single newline before heading.
+	return prev === "\n\n" || prev.endsWith("\n");
+}
+
+function isStepHeading(body: string, match: RegExpMatchArray): boolean {
+	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);
+	for (const line of section.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const config = trimmed.match(/^([\w-]+):\s*(.*)$/);
+		if (config && STEP_CONFIG_KEYS.has(config[1]!)) return true;
+		return false;
+	}
+	return false;
+}
+
+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 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 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));
+			if (step) steps.push(step);
+		}
+		return {
+			name,
+			description: frontmatter.description?.trim() || "No description provided.",
+			source,
+			filePath,
+			maxConcurrency: parseOptionalInteger(frontmatter.maxConcurrency),
+			steps,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function readWorkflowDir(dir: string, source: ResourceSource): WorkflowConfig[] {
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir)
+		.filter((entry) => entry.endsWith(".workflow.md"))
+		.map((entry) => parseWorkflowFile(path.join(dir, entry), source))
+		.filter((workflow): workflow is WorkflowConfig => workflow !== undefined)
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function discoverWorkflows(cwd: string): WorkflowDiscoveryResult {
+	return {
+		builtin: readWorkflowDir(path.join(packageRoot(), "workflows"), "builtin"),
+		user: readWorkflowDir(path.join(userPiRoot(), "workflows"), "user"),
+		project: readWorkflowDir(path.join(projectCrewRoot(cwd), "workflows"), "project"),
+	};
+}
+
+export function allWorkflows(discovery: WorkflowDiscoveryResult): WorkflowConfig[] {
+	const byName = new Map<string, WorkflowConfig>();
+	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/validate-workflow.ts

@@ -1,40 +1,40 @@
-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}'.`);
-		}
-	}
-
-	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)];
-}
+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}'.`);
+		}
+	}
+
+	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,26 +1,26 @@
-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;
-}
-
-export interface WorkflowConfig {
-	name: string;
-	description: string;
-	source: ResourceSource;
-	filePath: string;
-	steps: WorkflowStep[];
-	maxConcurrency?: number;
-}
+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;
+}
+
+export interface WorkflowConfig {
+	name: string;
+	description: string;
+	source: ResourceSource;
+	filePath: string;
+	steps: WorkflowStep[];
+	maxConcurrency?: number;
+}

package/src/workflows/workflow-serializer.ts

@@ -1,32 +1,32 @@
-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");
-}
+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,45 +1,45 @@
-import { execFileSync } from "node:child_process";
-
-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"] }).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");
-}
+import { execFileSync } from "node:child_process";
+
+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"] }).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");
+}