@calmo/task-runner 4.1.0 → 4.3.0

package/openspec/changes/feat-task-caching/design.md

@@ -0,0 +1,34 @@
+## Context
+
+Currently, the task runner always re-executes tasks, even if inputs (context) have not changed. This is inefficient for workflows with expensive steps like builds or data processing.
+
+## Goals / Non-Goals
+
+- **Goals**:
+    - Avoid redundant execution of expensive tasks.
+    - Support pluggable caching mechanisms (defaulting to in-memory).
+    - Allow restoration of context side effects when skipping execution.
+- **Non-Goals**:
+    - Distributed caching (out of scope for now).
+    - Automatic dependency hashing (cache key must be provided by the user).
+    - Persistent file system caching (can be added later via plugin or custom provider).
+
+## Decisions
+
+- **Decision**: Use `ICacheProvider` interface.
+    - **Rationale**: Allows users to swap the caching backend (e.g., Redis, FS) without changing core logic.
+- **Decision**: Explicit `restore` callback.
+    - **Rationale**: Since context is mutable and side-effect driven, simply returning a cached result is insufficient. The task must explicitly define how to re-apply its changes to the context based on the cached result.
+- **Decision**: Wrap execution strategy.
+    - **Rationale**: Follows the existing decorator pattern (like `RetryingExecutionStrategy`), keeping concerns separated.
+
+## Risks / Trade-offs
+
+- **Risk**: Stale cache data if keys are not unique enough.
+    - **Mitigation**: Documentation must emphasize the importance of including all relevant inputs in the cache key.
+- **Risk**: Context inconsistency if `restore` is implemented incorrectly.
+    - **Mitigation**: Provide clear examples and potentially validate context changes in debug mode.
+
+## Migration Plan
+
+- This is an additive change. Existing tasks without `cache` config will work as before. No migration required.

package/openspec/changes/feat-task-caching/proposal.md

@@ -0,0 +1,18 @@
+# Change: Task Output Caching
+
+## Why
+
+Currently, the task runner executes every task on every run, regardless of whether inputs or context have changed. For complex workflows involving expensive operations (e.g., builds, data processing), this leads to redundant execution and slower feedback loops. Implementing a caching mechanism will significantly improve performance by skipping tasks that have already been successfully executed with the same inputs.
+
+## What Changes
+
+- **Task Configuration**: Add `cache` configuration to `TaskStep` interface, allowing tasks to define a cache key and a restoration logic.
+- **Execution Strategy**: Introduce `CachingExecutionStrategy` that wraps other strategies. It checks for a cached result before execution and stores the result after successful execution.
+- **Cache Provider**: Define an `ICacheProvider` interface with a default in-memory implementation (`MemoryCacheProvider`), allowing for future extension (e.g., file system or remote cache).
+- **Task Result**: Ensure `TaskResult` is serializable and contains necessary metadata for caching.
+
+## Impact
+
+- **Affected specs**: `task-runner`
+- **Affected code**: `TaskStep.ts`, `TaskRunner.ts`, new strategy `CachingExecutionStrategy.ts`, new contract `ICacheProvider.ts`.
+- **Performance**: Significant reduction in execution time for repeated workflows.

package/openspec/changes/feat-task-caching/specs/task-runner/spec.md

@@ -0,0 +1,58 @@
+## ADDED Requirements
+
+### Requirement: Task Caching Configuration
+
+The `TaskStep` interface SHALL support an optional `cache` property of type `TaskCacheConfig`.
+
+#### Scenario: Cache Config Structure
+
+- **GIVEN** a `TaskCacheConfig` object
+- **THEN** it SHALL support:
+  - `key`: A function returning a unique string key based on the context.
+  - `ttl`: Optional time-to-live in milliseconds.
+  - `restore`: Optional function to restore context side effects from a cached result.
+
+### Requirement: Caching Execution Strategy
+
+The system SHALL provide a `CachingExecutionStrategy` that implements `IExecutionStrategy` and wraps another `IExecutionStrategy`.
+
+#### Scenario: Cache Miss Execution
+
+- **WHEN** the `CachingExecutionStrategy` executes a task with a cache key that is NOT present in the cache provider
+- **THEN** it SHALL execute the task using the inner strategy.
+- **AND** it SHALL store the result in the cache provider if execution is successful.
+- **AND** it SHALL return the result.
+
+#### Scenario: Cache Hit Execution
+
+- **WHEN** the `CachingExecutionStrategy` executes a task with a cache key that IS present in the cache provider
+- **THEN** it SHALL NOT execute the inner strategy.
+- **AND** it SHALL invoke the `restore` function (if provided) with the current context and the cached result.
+- **AND** it SHALL return the cached result.
+
+#### Scenario: Cache Expiration
+
+- **WHEN** a cached item's TTL has expired
+- **THEN** the cache provider SHALL NOT return the item.
+- **AND** the strategy SHALL proceed as a cache miss.
+
+### Requirement: Cache Provider Interface
+
+The system SHALL define an `ICacheProvider` interface for pluggable caching backends.
+
+#### Scenario: Interface Methods
+
+- **GIVEN** an `ICacheProvider` implementation
+- **THEN** it SHALL support:
+  - `get(key: string): Promise<TaskResult | undefined>`
+  - `set(key: string, value: TaskResult, ttl?: number): Promise<void>`
+  - `delete(key: string): Promise<void>`
+
+### Requirement: Default Memory Cache
+
+The system SHALL provide a `MemoryCacheProvider` as the default implementation of `ICacheProvider`.
+
+#### Scenario: In-Memory Storage
+
+- **WHEN** items are set in `MemoryCacheProvider`
+- **THEN** they are stored in memory and retrieved correctly until process termination or expiration.

package/openspec/changes/feat-task-caching/tasks.md

@@ -0,0 +1,24 @@
+## 1. Implementation
+
+- [ ] 1.1 Define `ICacheProvider` interface in `src/contracts/ICacheProvider.ts` with `get(key)`, `set(key, result, ttl)`, and `delete(key)` methods.
+- [ ] 1.2 Implement `MemoryCacheProvider` in `src/utils/MemoryCacheProvider.ts` as the default in-memory cache implementation.
+- [ ] 1.3 Update `TaskStep` interface in `src/TaskStep.ts` to include optional `cache` configuration:
+    - `key`: `(context: TContext) => string | Promise<string>`
+    - `ttl`: `number` (optional, default to infinite)
+    - `restore`: `(context: TContext, cachedResult: TaskResult) => void | Promise<void>` (optional, to re-apply context side effects)
+- [ ] 1.4 Create `CachingExecutionStrategy` in `src/strategies/CachingExecutionStrategy.ts`.
+    - It should implement `IExecutionStrategy`.
+    - It should accept an inner `IExecutionStrategy` and an `ICacheProvider`.
+    - In `execute`:
+        - Calculate cache key using `step.cache.key(context)`.
+        - Check cache provider. If hit:
+            - Execute `step.cache.restore(context, result)` if provided.
+            - Return cached result with status `skipped` (or a new status `cached`).
+        - If miss:
+            - Execute inner strategy.
+            - If successful, store result in cache provider using `ttl`.
+            - Return result.
+- [ ] 1.5 Update `TaskRunner.ts` to support configuring the cache provider and wrapping the execution strategy with `CachingExecutionStrategy` if caching is enabled.
+- [ ] 1.6 Add unit tests for `MemoryCacheProvider`.
+- [ ] 1.7 Add unit tests for `CachingExecutionStrategy`, verifying cache hits, misses, and restoration of context.
+- [ ] 1.8 Add integration tests in `tests/TaskRunnerCaching.test.ts` to verify end-to-end caching behavior with context updates.

package/openspec/changes/feat-task-loop/proposal.md

@@ -0,0 +1,22 @@
+# Change: feat-task-loop
+
+## Why
+
+Users often need to orchestrate tasks that involve waiting for a condition to be met, such as polling an API for a deployment status or waiting for a database to be healthy. Currently, this logic must be implemented imperatively within the `run` method of a task, which obscures the intent and mixes orchestration concerns with business logic.
+
+## What Changes
+
+- Add a `loop` configuration to the `TaskStep` interface.
+- Introduce a `LoopingExecutionStrategy` that wraps other strategies to handle conditional re-execution.
+- The `loop` configuration will support:
+    - `interval`: Time in milliseconds to wait between iterations.
+    - `maxIterations`: Maximum number of times to run the task.
+    - `until`: A predicate function `(context, result) => boolean` that determines when the loop should stop.
+
+## Impact
+
+- **Affected Specs**: `task-runner`
+- **Affected Code**:
+    - `src/TaskStep.ts`: Update interface.
+    - `src/strategies/LoopingExecutionStrategy.ts`: New file.
+    - `src/TaskRunnerBuilder.ts`: Integrate the new strategy.

package/openspec/changes/feat-task-loop/specs/task-runner/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Task Looping
+
+The `TaskStep` interface SHALL support an optional `loop` property of type `TaskLoopConfig` to enable conditional re-execution of a task (polling).
+
+#### Scenario: Loop until condition met
+
+- **GIVEN** a task with a `loop` configuration
+- **AND** the `loop.until` predicate returns `false`
+- **THEN** the task SHALL re-execute after the specified `interval`.
+- **WHEN** the `loop.until` predicate returns `true`
+- **THEN** the task SHALL complete successfully with the last result.
+
+#### Scenario: Max iterations reached
+
+- **GIVEN** a task with a `loop` configuration
+- **AND** the task has re-executed `maxIterations` times without the predicate returning `true`
+- **THEN** the task SHALL fail with an error indicating the loop limit was reached.
+
+#### Scenario: Integration with Retries
+
+- **GIVEN** a task with both `retry` and `loop` configurations
+- **WHEN** the task fails (throws an error)
+- **THEN** the `RetryingExecutionStrategy` SHALL handle the retry logic first.
+- **AND** the loop iteration SHALL only count once the task executes successfully (or fails after retries).
+
+#### Scenario: Loop Config Structure
+
+- **GIVEN** a `TaskLoopConfig` object
+- **THEN** it SHALL support:
+  - `interval`: Time in milliseconds to wait between iterations (default: 0).
+  - `maxIterations`: Maximum number of iterations (default: 1).
+  - `until`: A predicate function `(context: TContext, result: TaskResult) => boolean`.

package/openspec/changes/feat-task-loop/tasks.md

@@ -0,0 +1,8 @@
+## 1. Implementation
+
+- [ ] 1.1 Define `TaskLoopConfig` interface in `src/contracts/TaskLoopConfig.ts`.
+- [ ] 1.2 Update `TaskStep` interface in `src/TaskStep.ts` to include optional `loop: TaskLoopConfig`.
+- [ ] 1.3 Implement `LoopingExecutionStrategy` in `src/strategies/LoopingExecutionStrategy.ts`.
+- [ ] 1.4 Update `TaskRunnerBuilder` in `src/TaskRunnerBuilder.ts` to include `LoopingExecutionStrategy`.
+- [ ] 1.5 Add unit tests for `LoopingExecutionStrategy`.
+- [ ] 1.6 Verify integration with `RetryingExecutionStrategy` (looping should happen outside retries).

package/openspec/proposals/feat-matrix-execution/proposal.md

@@ -0,0 +1,23 @@
+# Change: Add Matrix Execution Support
+
+## Why
+
+Task orchestration tools in the industry (such as Nx, GitHub Actions, GitLab CI, and Turborepo) commonly support Matrix Execution. This allows a single task definition to run multiple times automatically across a set of variable combinations. In `task-runner`, defining identical tasks to process multiple permutations manually increases boilerplate and violates the DRY (Don't Repeat Yourself) principle. Introducing `matrix` configurations directly on the `TaskStep` allows developers to run a task concurrently across different configurations (e.g., Node.js versions, OS platforms, target environments) efficiently.
+
+## What Changes
+
+- Introduce a `matrix` property to the `TaskStep` configuration.
+- The `matrix` property should support defining variables as an object of arrays (e.g., `matrix: { node: [18, 20], os: ['ubuntu', 'windows'] }`).
+- The engine will dynamically generate and execute independent child tasks for each permutation of the matrix.
+- Ensure the `MermaidGraph` utility correctly visualizes these dynamic nodes.
+- Expose the current permutation variables to the execution context of each child task.
+
+## Impact
+
+- Affected specs: `task-runner` (Task Configuration, Core Orchestration)
+- Affected code:
+  - `src/core/TaskStep.ts`
+  - `src/core/TaskRunner.ts`
+  - `src/core/TaskGraph.ts`
+  - `src/core/TaskStateManager.ts`
+  - `src/core/WorkflowExecutor.ts`

package/openspec/proposals/feat-matrix-execution/specs/task-runner/spec.md

@@ -0,0 +1,47 @@
+## ADDED Requirements
+
+### Requirement: Matrix Execution Configuration
+
+The `TaskStep` interface SHALL support an optional `matrix` configuration property to enable parameterized execution.
+
+#### Scenario: Matrix configuration structure
+
+- **GIVEN** a `TaskStep` definition
+- **THEN** it SHALL support a `matrix` property defined as a mapping of variable names to arrays of values (e.g., `Record<string, any[]>`).
+
+### Requirement: Matrix Permutation Expansion
+
+The `TaskRunner` engine SHALL dynamically expand a task with a `matrix` configuration into multiple independent task instances.
+
+#### Scenario: Single dimension matrix
+
+- **WHEN** a task defines a single dimension matrix (e.g., `matrix: { env: ['dev', 'prod'] }`)
+- **THEN** the engine SHALL generate independent task instances for each value.
+
+#### Scenario: Multi-dimensional matrix
+
+- **WHEN** a task defines a multi-dimensional matrix (e.g., `matrix: { os: ['linux', 'windows'], node: [18, 20] }`)
+- **THEN** the engine SHALL generate independent task instances for every combination (Cartesian product) of the matrix dimensions.
+
+### Requirement: Contextual Matrix Variables
+
+The `TaskRunner` SHALL provide the matrix permutation values to the execution context of the generated child tasks.
+
+#### Scenario: Accessing matrix variables
+
+- **WHEN** a child matrix task is executed for a permutation like `{ os: 'linux', node: 18 }`
+- **THEN** its `run` function SHALL be able to access the permutation values via the context (e.g., `context.matrix.os` would be `'linux'` and `context.matrix.node` would be `18`).
+
+### Requirement: Matrix Dependency Resolution
+
+The `TaskRunner` SHALL correctly resolve dependencies involving matrix tasks.
+
+#### Scenario: Depending on a matrix task
+
+- **WHEN** a standard task depends on a matrix task
+- **THEN** the standard task SHALL wait for all child tasks of the matrix to complete successfully before executing.
+
+#### Scenario: Matrix task dependencies
+
+- **WHEN** a matrix task depends on another task
+- **THEN** all generated child tasks of the matrix SHALL wait for the parent task to complete before executing.

package/openspec/proposals/feat-matrix-execution/tasks.md

@@ -0,0 +1,11 @@
+## 1. Implementation
+
+- [ ] 1.1 Update `TaskStep.ts` interface to include an optional `matrix` property (e.g., `Record<string, unknown[]>`).
+- [ ] 1.2 Update the `TaskRunnerBuilder` and `TaskGraph` validation to accept and validate the `matrix` property.
+- [ ] 1.3 Implement a matrix permutation generator utility to compute Cartesian products of matrix dimensions.
+- [ ] 1.4 Update `TaskStateManager.ts` or `TaskGraph.ts` to dynamically expand matrix steps into individual nodes during initialization, resolving dependencies appropriately.
+- [ ] 1.5 Update the task execution context to provide the current matrix permutation variables to the `run` function.
+- [ ] 1.6 Update the Mermaid Graph utility in `TaskRunner.ts` to correctly output nodes and edges for the dynamically generated matrix steps.
+- [ ] 1.7 Add unit tests covering matrix generation, execution, failure handling, and context passing.
+- [ ] 1.8 Add benchmarks for graph generation and state initialization with large matrix sets to ensure performance targets are met.
+- [ ] 1.9 Add user-facing documentation for the `matrix` feature, including examples.

package/openspec/proposals/feat-task-observability/proposal.md

@@ -0,0 +1,16 @@
+# Change: Workflow Observability and Logging Enhancements
+
+## Why
+
+As workflows scale in complexity and run in diverse environments (CI/CD, containerized workers, local development), tracking their execution becomes difficult. Currently, users have to manually hook into the `EventBus` to build their own loggers or metrics exporters. Providing built-in, standardized observability tools (like a structured logger or CLI output formatter) will significantly improve the Developer Experience (DX) and reduce boilerplate for debugging complex task graphs.
+
+## What Changes
+
+- Introduce a standardized `LoggerPlugin` (or similar logging abstraction) that hooks into the existing `EventBus`.
+- Support multiple output formats: `text` (human-readable for CLI) and `json` (structured logging for ingestion by tools like Datadog, ELK, CloudWatch).
+- Capture and format key metrics automatically: task duration, error stack traces, and workflow summaries.
+
+## Impact
+
+- Affected specs: `task-runner` (adding observability capabilities)
+- Affected code: `src/plugins/LoggerPlugin.ts` (new), `TaskRunnerBuilder` (optional `.withLogger()` integration).

package/openspec/proposals/feat-task-observability/specs/task-runner/spec.md

@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Built-in Observability Logging
+
+The system SHALL provide a standardized mechanism to log workflow and task execution events in both human-readable and structured formats.
+
+#### Scenario: CLI Text Logging
+- **WHEN** a workflow is executed with the text logger enabled
+- **THEN** it SHALL output human-readable lifecycle events (start, success, failure, skip) to the console.
+
+#### Scenario: Structured JSON Logging
+- **WHEN** a workflow is executed with the JSON logger enabled
+- **THEN** it SHALL output structured JSON objects for each lifecycle event, suitable for machine ingestion.
+- **AND** the JSON object SHALL contain task name, timestamp, duration, and status.

package/openspec/proposals/feat-task-observability/tasks.md

@@ -0,0 +1,7 @@
+## 1. Implementation
+
+- [ ] 1.1 Create `LoggerPlugin` implementing the `Plugin` interface.
+- [ ] 1.2 Implement human-readable text formatting for CLI.
+- [ ] 1.3 Implement structured JSON formatting for log ingestion.
+- [ ] 1.4 Add a fluent method to `TaskRunnerBuilder` (e.g., `.withLogger()`) to easily attach the plugin.
+- [ ] 1.5 Write unit tests for the logging outputs and integration.

package/openspec/specs/plugin-context/spec.md

@@ -0,0 +1,19 @@
+# plugin-context Specification
+
+## Purpose
+TBD - created by archiving change implement-plugin-system. Update Purpose after archive.
+## Requirements
+### Requirement: Expose EventBus to plugins
+
+The `PluginContext` passed to `install` MUST expose the `EventBus` (or equivalent API) to allow listening to events.
+
+#### Scenario: Listening to task events
+Given a plugin is being installed
+When it accesses `context.events`
+Then it can subscribe to `taskStart` and `taskEnd` events
+
+#### Scenario: Emitting custom events (Future)
+Given a plugin
+When it has access to the event bus
+Then it should be able to emit events (if allowed by design)
+

package/openspec/specs/plugin-loading/spec.md

@@ -0,0 +1,29 @@
+# plugin-loading Specification
+
+## Purpose
+TBD - created by archiving change implement-plugin-system. Update Purpose after archive.
+## Requirements
+### Requirement: Support registering plugins
+
+The `TaskRunner` MUST allow registering plugins via a `use` method or configuration.
+
+#### Scenario: Registering a valid plugin
+Given a `TaskRunner` instance
+When I call `use` with a valid plugin object
+Then the plugin is added to the internal plugin list
+
+#### Scenario: Registering an invalid plugin
+Given a `TaskRunner` instance
+When I call `use` with an invalid object (missing install method)
+Then it should throw an error or reject the plugin
+
+### Requirement: Initialize plugins before execution
+
+Plugins MUST be initialized (have their `install` method called) before the workflow starts.
+
+#### Scenario: Plugin initialization
+Given a registered plugin
+When `execute` is called on the `TaskRunner`
+Then the plugin's `install` method is called with the plugin context
+And the workflow execution proceeds only after `install` completes
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "A lightweight, type-safe, and domain-agnostic task orchestration engine. It resolves a Directed Acyclic Graph (DAG) of steps, executes independent tasks in parallel, and manages a shared context across the pipeline.",
   "repository": {
     "type": "git",

package/src/EventBus.ts

@@ -40,10 +40,9 @@ export class EventBus<TContext> {
     event: K,
     callback: RunnerEventListener<TContext, K>
   ): void {
-    if (this.listeners[event]) {
-      (this.listeners[event] as Set<RunnerEventListener<TContext, K>>).delete(
-        callback
-      );
+    const listeners = this.listeners[event];
+    if (listeners) {
+      listeners.delete(callback);
     }
   }
 
@@ -56,16 +55,13 @@ export class EventBus<TContext> {
     event: K,
     data: RunnerEventPayloads<TContext>[K]
   ): void {
-    const listeners = this.listeners[event] as
-      | Set<RunnerEventListener<TContext, K>>
-      | undefined;
+    const listeners = this.listeners[event];
     if (listeners) {
       for (const listener of listeners) {
-        // We use Promise.resolve().then() to schedule the listener on the microtask queue,
+        // We use queueMicrotask() to schedule the listener on the microtask queue,
         // ensuring the emit method remains non-blocking.
-        // The final .catch() ensures that any errors in the promise infrastructure itself are logged.
-        Promise.resolve()
-          .then(() => {
+        queueMicrotask(() => {
+          try {
             try {
               const result = listener(data);
               if (result instanceof Promise) {
@@ -84,14 +80,14 @@ export class EventBus<TContext> {
                 error
               );
             }
-          })
-          .catch((error) => {
-            // detailed handling for the promise chain itself
+          } catch (error) {
+            // detailed handling for the microtask execution itself
             console.error(
               `Unexpected error in event bus execution for ${String(event)}:`,
               error
             );
-          });
+          }
+        });
       }
     }
   }

package/src/PluginManager.ts

@@ -0,0 +1,43 @@
+import { Plugin, PluginContext } from "./contracts/Plugin.js";
+
+/**
+ * Manages the lifecycle of plugins.
+ */
+export class PluginManager<TContext> {
+  private plugins: Plugin<TContext>[] = [];
+
+  constructor(private context: PluginContext<TContext>) {}
+
+  /**
+   * Registers a plugin.
+   * @param plugin The plugin to register.
+   */
+  public use(plugin: Plugin<TContext>): void {
+    // Check if plugin is already registered
+    if (this.plugins.some((p) => p.name === plugin.name)) {
+      // For now, we allow overwriting or just warn?
+      // Let's just allow it but maybe log it if we had a logger.
+      // Strict check: don't allow duplicate names.
+      throw new Error(`Plugin with name '${plugin.name}' is already registered.`);
+    }
+    this.plugins.push(plugin);
+  }
+
+  /**
+   * Initializes all registered plugins in parallel.
+   */
+  public async initialize(): Promise<void> {
+    const installPromises = this.plugins
+      .map((plugin) => plugin.install(this.context))
+      .filter((result): result is Promise<void> => result instanceof Promise);
+
+    await Promise.all(installPromises);
+  }
+
+  /**
+   * Returns the list of registered plugins.
+   */
+  public getPlugins(): ReadonlyArray<Plugin<TContext>> {
+    return this.plugins;
+  }
+}

package/src/TaskGraphValidator.ts

@@ -1,7 +1,7 @@
 import { ITaskGraphValidator } from "./contracts/ITaskGraphValidator.js";
 import { ValidationResult } from "./contracts/ValidationResult.js";
 import { ValidationError } from "./contracts/ValidationError.js";
-import { TaskGraph } from "./TaskGraph.js";
+import { TaskGraph, Task } from "./TaskGraph.js";
 import {
   ERROR_CYCLE,
   ERROR_DUPLICATE_TASK,
@@ -22,11 +22,11 @@ export class TaskGraphValidator implements ITaskGraphValidator {
   validate(taskGraph: TaskGraph): ValidationResult {
     const errors: ValidationError[] = [];
 
-    // 1. Check for duplicate tasks
-    const taskIds = this.checkDuplicateTasks(taskGraph, errors);
+    // 1. Build Map and Check Duplicates (Single Pass)
+    const taskMap = this.buildTaskMapAndCheckDuplicates(taskGraph, errors);
 
     // 2. Check for missing dependencies
-    this.checkMissingDependencies(taskGraph, taskIds, errors);
+    this.checkMissingDependencies(taskGraph, taskMap, errors);
 
     // 3. Check for cycles
     // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
@@ -35,7 +35,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     );
 
     if (!hasMissingDependencies) {
-      this.checkCycles(taskGraph, errors);
+      this.checkCycles(taskGraph, taskMap, errors);
     }
 
     return {
@@ -54,33 +54,33 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     return `Task graph validation failed: ${errorDetails.join("; ")}`;
   }
 
-  private checkDuplicateTasks(
+  private buildTaskMapAndCheckDuplicates(
     taskGraph: TaskGraph,
     errors: ValidationError[]
-  ): Set<string> {
-    const taskIds = new Set<string>();
+  ): Map<string, Task> {
+    const taskMap = new Map<string, Task>();
     for (const task of taskGraph.tasks) {
-      if (taskIds.has(task.id)) {
+      if (taskMap.has(task.id)) {
         errors.push({
           type: ERROR_DUPLICATE_TASK,
           message: `Duplicate task detected with ID: ${task.id}`,
           details: { taskId: task.id },
         });
       } else {
-        taskIds.add(task.id);
+        taskMap.set(task.id, task);
       }
     }
-    return taskIds;
+    return taskMap;
   }
 
   private checkMissingDependencies(
     taskGraph: TaskGraph,
-    taskIds: Set<string>,
+    taskMap: Map<string, Task>,
     errors: ValidationError[]
   ): void {
     for (const task of taskGraph.tasks) {
       for (const dependenceId of task.dependencies) {
-        if (!taskIds.has(dependenceId)) {
+        if (!taskMap.has(dependenceId)) {
           errors.push({
             type: ERROR_MISSING_DEPENDENCY,
             message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
@@ -91,13 +91,11 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     }
   }
 
-  private checkCycles(taskGraph: TaskGraph, errors: ValidationError[]): void {
-    // Build adjacency list
-    const adjacencyList = new Map<string, string[]>();
-    for (const task of taskGraph.tasks) {
-      adjacencyList.set(task.id, task.dependencies);
-    }
-
+  private checkCycles(
+    taskGraph: TaskGraph,
+    taskMap: Map<string, Task>,
+    errors: ValidationError[]
+  ): void {
     const visited = new Set<string>();
     const recursionStack = new Set<string>();
 
@@ -108,7 +106,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
 
       const path: string[] = [];
       if (
-        this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)
+        this.detectCycle(task.id, path, visited, recursionStack, taskMap)
       ) {
         // Extract the actual cycle from the path
         // The path might look like A -> B -> C -> B (if we started at A and found cycle B-C-B)
@@ -132,7 +130,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     path: string[],
     visited: Set<string>,
     recursionStack: Set<string>,
-    adjacencyList: Map<string, string[]>
+    taskMap: Map<string, Task>
   ): boolean {
     // Use an explicit stack to avoid maximum call stack size exceeded errors
     const stack: { taskId: string; index: number; dependencies: string[] }[] =
@@ -145,7 +143,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     stack.push({
       taskId: startTaskId,
       index: 0,
-      dependencies: adjacencyList.get(startTaskId)!,
+      dependencies: taskMap.get(startTaskId)!.dependencies,
     });
 
     while (stack.length > 0) {
@@ -170,7 +168,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
           stack.push({
             taskId: dependenceId,
             index: 0,
-            dependencies: adjacencyList.get(dependenceId)!,
+            dependencies: taskMap.get(dependenceId)!.dependencies,
           });
         }
       } else {