bump

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikefreno/ralpi",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Execute tasks from task files/PRD's using DAG-based dependency resolution with persistent progress tracking",
   "keywords": [
     "pi-package",

src/dag.ts

@@ -1,4 +1,10 @@
-import type { Task, ExecutionBatch, ExecutionPlan, Project } from "./types";
+import type {
+	Task,
+	ExecutionBatch,
+	ExecutionPlan,
+	Project,
+	ParallelGroup,
+} from "./types";
 
 // ─── Blocked Tasks ───────────────────────────────────────────────────────────
 
@@ -42,13 +48,28 @@ export function buildExecutionPlan(
 ): ExecutionPlan {
 	// Filter out already completed tasks
 	const pendingTasks = project.tasks.filter((t) => !completed.has(t.id));
+	const skippedTasks = project.tasks.filter((t) => completed.has(t.id));
 
-  // If parallel_group is explicitly set, use group-based batching
+	// With explicitly declared parallel groups, all groups are independent.
+	// Since there are no cross-group dependencies by definition, standard
+	// Kahn's algorithm produces the correct plan — tasks ready in any group
+	// appear in the same batch, and intra-group dependencies (e.g. "21 must
+	// be done before 22, 23, 24") are respected automatically.
+	// The parallel groups are preserved as metadata for display/documentation.
+	if (project.parallelGroups && project.parallelGroups.length > 0) {
+		return {
+			batches: buildGroupAwareBatches(project, pendingTasks, failedTaskIds),
+			totalTasks: pendingTasks.length,
+			skippedTasks,
+		};
+	}
+
+	// If parallel_group is explicitly set (legacy config flag), use group-based batching
 	if (parallelGroup !== undefined) {
 		return {
-      batches: buildParallelGroupBatches(pendingTasks, failedTaskIds),
+			batches: buildParallelGroupBatchesLegacy(pendingTasks, failedTaskIds),
 			totalTasks: pendingTasks.length,
-      skippedTasks: project.tasks.filter((t) => completed.has(t.id)),
+			skippedTasks,
 		};
 	}
 
@@ -56,7 +77,7 @@ export function buildExecutionPlan(
 	return {
 		batches: buildBatches(pendingTasks, failedTaskIds),
 		totalTasks: pendingTasks.length,
-    skippedTasks: project.tasks.filter((t) => completed.has(t.id)),
+		skippedTasks,
 	};
 }
 
@@ -139,13 +160,72 @@ function buildBatches(
 	return batches;
 }
 
-// ─── Parallel Group Batching ─────────────────────────────────────────────────
+// ─── Group-Aware Batching ────────────────────────────────────────────────────
 
 /**
- * Build batches from explicit parallel_group values.
+ * Build batches respecting both explicit parallel groups and intra-group
- * Groups execute in ascending order; tasks within a group run concurrently.
+ * dependencies. Since parallel group declarations imply no cross-group
+ * dependencies, all tasks whose dependencies are satisfied — across any
+ * group — can run concurrently in the same batch. This means groups
+ * "proceed independently" as the user specified: tasks from different
+ * groups can appear in the same batch when ready.
+ *
+ * Intra-group dependencies (e.g., "21 must be done before 22, 23, 24")
+ * are handled by Kahn's algorithm: if 21 has deps satisfied but 22 doesn't,
+ * only 21 appears in the current batch.
  */
-function buildParallelGroupBatches(
+function buildGroupAwareBatches(
+	_project: Project,
+	pendingTasks: Task[],
+	failedTaskIds: Set<string>,
+): ExecutionBatch[] {
+	const blocked = getBlockedTasks(pendingTasks, failedTaskIds);
+	const activeTasks = pendingTasks.filter((t) => !blocked.has(t.id));
+
+	// Standard Kahn's algorithm across ALL tasks — parallel groups are
+	// metadata for display, not scheduling constraints.
+	const pendingSet = new Set(pendingTasks.map((t) => t.id));
+	const done = new Set<string>();
+	const remaining = new Set(activeTasks.map((t) => t.id));
+	const batches: ExecutionBatch[] = [];
+
+	while (remaining.size > 0) {
+		const ready: Task[] = [];
+		for (const task of activeTasks) {
+			if (!remaining.has(task.id)) continue;
+			const deps = task.dependencies || [];
+			const depsSatisfied = deps.every(
+				(dep) => done.has(dep) || !pendingSet.has(dep),
+			);
+			if (depsSatisfied) {
+				ready.push(task);
+			}
+		}
+
+		if (ready.length === 0) {
+			throw new Error(
+				`Dependency cycle detected: ${Array.from(remaining).join(", ")}`,
+			);
+		}
+
+		batches.push({ tasks: ready, batchIndex: batches.length });
+		for (const task of ready) {
+			done.add(task.id);
+			remaining.delete(task.id);
+		}
+	}
+
+	return batches;
+}
+
+// ─── Legacy Parallel Group Batching ─────────────────────────────────────────
+
+/**
+ * Legacy: build batches from explicit parallel_group values only.
+ * Groups execute in ascending order; tasks within a group run concurrently.
+ * Does NOT respect intra-group dependencies.
+ */
+function buildParallelGroupBatchesLegacy(
 	pendingTasks: Task[],
 	failedTaskIds: Set<string>,
 ): ExecutionBatch[] {
@@ -403,13 +483,31 @@ export function formatDependencyChain(project: Project): string {
 /**
  * Format the execution plan for display
  */
-export function formatExecutionPlan(plan: ExecutionPlan): string {
+/**
+ * Format the execution plan for display, optionally with parallel group annotations
+ */
+export function formatExecutionPlan(
+	plan: ExecutionPlan,
+	parallelGroups?: ParallelGroup[],
+): string {
 	const lines: string[] = [];
 	lines.push("## Execution Plan");
 	lines.push("");
 	lines.push(`Total tasks: ${plan.totalTasks}`);
 	lines.push(`Batches: ${plan.batches.length}`);
 
+	// Build a lookup: taskId → group label
+	const groupLabel = new Map<string, string>();
+	if (parallelGroups) {
+		for (const g of parallelGroups) {
+			for (const id of g.taskIds) {
+				if (g.label) {
+					groupLabel.set(id, g.label);
+				}
+			}
+		}
+	}
+
 	if (plan.skippedTasks.length > 0) {
 		lines.push(
 			`Already completed: ${plan.skippedTasks.map((t) => t.id).join(", ")}`,
@@ -420,7 +518,14 @@ export function formatExecutionPlan(plan: ExecutionPlan): string {
 	for (const batch of plan.batches) {
 		lines.push(`### Batch ${batch.batchIndex + 1}`);
 		for (const task of batch.tasks) {
-      lines.push(`- ${task.id}: ${task.title}`);
+			const annotation = groupLabel.has(task.id)
+				? `  _(${groupLabel.get(task.id)})_`
+				: "";
+			const deps =
+				task.dependencies.length > 0
+					? `  ← needs ${task.dependencies.join(", ")}`
+					: "";
+			lines.push(`- ${task.id}: ${task.title}${annotation}${deps}`);
 		}
 		lines.push("");
 	}

src/parser.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { Task, Project } from "./types";
+import type { Task, Project, ParallelGroup } from "./types";
 
 // Lazy-loaded yaml package
 let YAML_module: typeof import("yaml") | undefined;
@@ -56,6 +56,7 @@ function parseFioFormat(
 	const lines = content.split("\n");
 	const tasks: Task[] = [];
 	const dependencies: Record<string, string[]> = {};
+	const parallelGroups: ParallelGroup[] = [];
 	let inTasks = false;
 	let inDeps = false;
 
@@ -151,8 +152,9 @@ function parseFioFormat(
 
 			// Format 1: Natural language "X depends on A, B, C"
 			// Supports optional markdown list prefix: "- 13 depends on 17, 18, 19"
+			// Also handles "also depends on": "- 08 also depends on 05, 06"
 			const dependsMatch = line.match(
-				/^(?:\s*[-*]\s+)?(\d+)\s+depends\s+on\s+([\d,\s]+)/i,
+				/^(?:\s*[-*]\s+)?(\d+)\s+(?:also\s+)?depends\s+on\s+([\d,\s]+)/i,
 			);
 			if (dependsMatch) {
 				const [, taskId, depsList] = dependsMatch;
@@ -164,7 +166,11 @@ function parseFioFormat(
 					.map((t) => t.padStart(2, "0"));
 
 				if (!dependencies[taskIdPadded]) dependencies[taskIdPadded] = [];
-				dependencies[taskIdPadded].push(...depIds);
+				for (const depId of depIds) {
+					if (!dependencies[taskIdPadded].includes(depId)) {
+						dependencies[taskIdPadded].push(depId);
+					}
+				}
 			}
 
 			// Parse meta blocks for task configuration (timeout, etc.)
@@ -178,6 +184,91 @@ function parseFioFormat(
 					task.timeoutMs = parseTimeoutValue(Number(value), unit);
 				}
 			}
+
+			// Format 2: "X, Y, Z can be done in parallel (label)"
+			// "- 01, 02, 03, 04 can be done in parallel (Play Store prep)"
+			const parallelMatch = line.match(
+				/^(?:\s*[-*]\s+)?((?:0?\d+\s*,\s*)*0?\d+)\s+can\s+be\s+done\s+in\s+parallel(?:\s+\(([^)]+)\))?$/i,
+			);
+			if (parallelMatch) {
+				const [, idsStr, label] = parallelMatch;
+				const taskIds = idsStr
+					.split(",")
+					.map((t) => t.trim())
+					.filter((t) => /^\d+$/.test(t))
+					.map((t) => t.padStart(2, "0"));
+
+				if (taskIds.length > 0) {
+					parallelGroups.push({
+						index: parallelGroups.length,
+						label: label ? label.trim() : undefined,
+						taskIds,
+					});
+				}
+			}
+
+			// Format 3: "A must be done before B, C" or "A, B must be done before C"
+			// "- 21 must be done before 22, 23, 24 (backend integration foundation)"
+			// "- 02, 03 must be done before 04"
+			const mustBeforeMatch = line.match(
+				/^(?:\s*[-*]\s+)?((?:0?\d+\s*,\s*)*0?\d+)\s+must\s+be\s+done\s+before\s+((?:0?\d+\s*,\s*)*0?\d+)(?:\s+\(([^)]+)\))?$/i,
+			);
+			if (mustBeforeMatch) {
+				const [, fromIdsStr, toIdsStr] = mustBeforeMatch;
+				const fromIds = fromIdsStr
+					.split(",")
+					.map((t) => t.trim())
+					.filter((t) => /^\d+$/.test(t))
+					.map((t) => t.padStart(2, "0"));
+				const toIds = toIdsStr
+					.split(",")
+					.map((t) => t.trim())
+					.filter((t) => /^\d+$/.test(t))
+					.map((t) => t.padStart(2, "0"));
+
+				// Each "to" task depends on ALL "from" tasks
+				for (const toId of toIds) {
+					if (!dependencies[toId]) dependencies[toId] = [];
+					for (const fromId of fromIds) {
+						if (!dependencies[toId].includes(fromId)) {
+							dependencies[toId].push(fromId);
+						}
+					}
+				}
+			}
+
+			// Format 4: "X, Y, Z depend on A" or "X depends on A, B, C"
+			// "- 22, 23, 24 depend on 21"
+			// "- 05, 06 depend on 02, 03, 04"
+			// "- 08 also depends on 05, 06"  ("also" is ignored)
+			// Strip optional "also" before matching
+			const cleanedLine = line.replace(/\balso\b/i, "");
+			const dependOnMatch = cleanedLine.match(
+				/^(?:\s*[-*]\s+)?((?:0?\d+\s*,\s*)*0?\d+)\s+depend(?:s)?\s+on\s+((?:0?\d+\s*,\s*)*0?\d+)(?:\s+\(([^)]+)\))?$/i,
+			);
+			if (dependOnMatch) {
+				const [, fromIdsStr, toIdsStr] = dependOnMatch;
+				const fromIds = fromIdsStr
+					.split(",")
+					.map((t) => t.trim())
+					.filter((t) => /^\d+$/.test(t))
+					.map((t) => t.padStart(2, "0"));
+				const toIds = toIdsStr
+					.split(",")
+					.map((t) => t.trim())
+					.filter((t) => /^\d+$/.test(t))
+					.map((t) => t.padStart(2, "0"));
+
+				// Each "from" task depends on ALL "to" tasks
+				for (const fromId of fromIds) {
+					if (!dependencies[fromId]) dependencies[fromId] = [];
+					for (const toId of toIds) {
+						if (!dependencies[fromId].includes(toId)) {
+							dependencies[fromId].push(toId);
+						}
+					}
+				}
+			}
 		}
 	}
 
@@ -203,9 +294,20 @@ function parseFioFormat(
 		}
 	}
 
+	// Apply parallelGroup to tasks
+	for (const group of parallelGroups) {
+		for (const taskId of group.taskIds) {
+			const task = tasks.find((t) => t.id === taskId);
+			if (task) {
+				task.parallelGroup = group.index;
+			}
+		}
+	}
+
 	return {
 		tasks,
 		dependencies,
+		parallelGroups: parallelGroups.length > 0 ? parallelGroups : undefined,
 		sourcePath,
 		sourceDir,
 		exitCriteria,

src/types.ts

@@ -29,6 +29,15 @@ export interface Task {
 	index?: number;
 }
 
+export interface ParallelGroup {
+	/** Group index (0-based, determines execution order) */
+	index: number;
+	/** Human-readable label for the group (e.g. "Play Store prep") */
+	label?: string;
+	/** Task IDs in this group — all can run concurrently */
+	taskIds: string[];
+}
+
 export interface Project {
 	/** Project-level objective / goal */
 	objective?: string;
@@ -36,6 +45,8 @@ export interface Project {
 	tasks: Task[];
 	/** Explicit dependency map: taskId → [dependency taskIds] */
 	dependencies: Record<string, string[]>;
+	/** Explicit parallel groups from "can be done in parallel" declarations */
+	parallelGroups?: ParallelGroup[];
 	/** Exit criteria (from README ## Exit Criteria section) */
 	exitCriteria?: string[];
 	/** Path to the source task file */