Walkthrough

This PR introduces support for nested parallel tasks—allowing parallel tasks to reference other parallel tasks with automatic flattening. It includes cycle detection to prevent circular references, modifies the CLI to use flattened task lists, enhances dry-run visualization to show task expansion, and adds comprehensive documentation and tests.

Changes

Sequence Diagram

sequenceDiagram
    actor User
    participant CLI
    participant Validator
    participant Executor
    
    User->>CLI: Execute parallel task (nested refs)
    CLI->>Validator: ValidateParallelTasks() + detectParallelCycle()
    Validator->>Validator: DFS cycle detection
    alt Cycle detected
        Validator-->>CLI: Error (circular reference)
        CLI-->>User: Fail with guidance
    else Valid config
        Validator-->>CLI: ✓ Validation passed
        CLI->>Validator: FlattenParallelTasks(task)
        Validator->>Validator: Recursively expand nested refs
        Validator->>Validator: Deduplicate expanded list
        Validator-->>CLI: Flattened task list
        CLI->>CLI: Build TaskInfo from flattened tasks
        alt Dry-run mode
            CLI->>CLI: Render expansion details<br/>(original refs + nested subtasks)
            CLI-->>User: Display expansion preview
        else Execute
            CLI->>Executor: Execute flattened tasks in parallel
            Executor->>Executor: Run all expanded tasks
            Executor-->>User: Results
        end
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

The changes introduce substantial new logic in the validation layer (cycle detection via DFS, recursive flattening with deduplication), modify CLI execution flow to integrate flattened results, and affect both happy-path and error-handling routes. While well-tested, the cycle detection algorithm and flattening correctness require careful verification, especially around edge cases like diamond dependencies and circular references.

Possibly related PRs

• feat: parallel task execution across multiple hosts #89: Adds parallel-task execution and validation; this PR extends that foundation by enabling nested references and adding the FlattenParallelTasks() API used by the CLI.
• fix: track parallel tasks by index to handle duplicate task names #112: Modifies TaskInfo construction and index handling in parallel execution; this PR changes how TaskInfo entries are built from flattened subtasks, so coordination on parallel execution semantics may be needed.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}