@calmo/task-runner 2.0.0 → 3.0.0

package/dist/TaskStateManager.js

@@ -0,0 +1,130 @@
+/**
+ * Manages the state of the task execution, including results, pending steps, and running tasks.
+ * Handles dependency resolution and event emission for state changes.
+ */
+export class TaskStateManager {
+    eventBus;
+    results = new Map();
+    pendingSteps = new Set();
+    running = new Set();
+    constructor(eventBus) {
+        this.eventBus = eventBus;
+    }
+    /**
+     * Initializes the state with the given steps.
+     * @param steps The steps to execute.
+     */
+    initialize(steps) {
+        this.pendingSteps = new Set(steps);
+        this.results.clear();
+        this.running.clear();
+    }
+    /**
+     * Processes the pending steps to identify tasks that can be started or must be skipped.
+     * Emits `taskSkipped` for skipped tasks.
+     * @returns An array of tasks that are ready to run.
+     */
+    processDependencies() {
+        const toRemove = [];
+        const toRun = [];
+        for (const step of this.pendingSteps) {
+            const deps = step.dependencies ?? [];
+            let blocked = false;
+            let failedDep;
+            for (const dep of deps) {
+                const depResult = this.results.get(dep);
+                if (!depResult) {
+                    // Dependency not finished yet
+                    blocked = true;
+                }
+                else if (depResult.status !== "success") {
+                    failedDep = dep;
+                    break;
+                }
+            }
+            if (failedDep) {
+                const depResult = this.results.get(failedDep);
+                const depError = depResult?.error ? `: ${depResult.error}` : "";
+                const result = {
+                    status: "skipped",
+                    message: `Skipped because dependency '${failedDep}' failed${depError}`,
+                };
+                this.results.set(step.name, result);
+                this.eventBus.emit("taskSkipped", { step, result });
+                toRemove.push(step);
+            }
+            else if (!blocked) {
+                toRun.push(step);
+                toRemove.push(step);
+            }
+        }
+        // Cleanup pending set
+        for (const step of toRemove) {
+            this.pendingSteps.delete(step);
+        }
+        return toRun;
+    }
+    /**
+     * Marks a task as running and emits `taskStart`.
+     * @param step The task that is starting.
+     */
+    markRunning(step) {
+        this.running.add(step.name);
+        this.eventBus.emit("taskStart", { step });
+    }
+    /**
+     * Marks a task as completed (success, failure, or cancelled during execution)
+     * and emits `taskEnd`.
+     * @param step The task that completed.
+     * @param result The result of the task.
+     */
+    markCompleted(step, result) {
+        this.running.delete(step.name);
+        this.results.set(step.name, result);
+        this.eventBus.emit("taskEnd", { step, result });
+    }
+    /**
+     * Cancels all pending tasks that haven't started yet.
+     * @param message The cancellation message.
+     */
+    cancelAllPending(message) {
+        // Iterate over pendingSteps to cancel them
+        for (const step of this.pendingSteps) {
+            // Also check running? No, running tasks are handled by AbortSignal in Executor.
+            // We only cancel what is pending and hasn't started.
+            /* v8 ignore next 1 */
+            if (!this.results.has(step.name) && !this.running.has(step.name)) {
+                const result = {
+                    status: "cancelled",
+                    message,
+                };
+                this.results.set(step.name, result);
+            }
+        }
+        // Clear pending set as they are now "done" (cancelled)
+        // Wait, if we clear pending steps, processDependencies won't pick them up.
+        // The loop in Executor relies on results.size or pendingSteps.
+        // The previous implementation iterated `steps` (all steps) to cancel.
+        // Here we iterate `pendingSteps`.
+        this.pendingSteps.clear();
+    }
+    /**
+     * Returns the current results map.
+     */
+    getResults() {
+        return this.results;
+    }
+    /**
+     * Checks if there are any tasks currently running.
+     */
+    hasRunningTasks() {
+        return this.running.size > 0;
+    }
+    /**
+     * Checks if there are any pending tasks.
+     */
+    hasPendingTasks() {
+        return this.pendingSteps.size > 0;
+    }
+}
+//# sourceMappingURL=TaskStateManager.js.map

package/dist/TaskStateManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskStateManager.js","sourceRoot":"","sources":["../src/TaskStateManager.ts"],"names":[],"mappings":"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"}

package/dist/TaskStatus.d.ts

@@ -1,4 +1,4 @@
 /**
  * Represents the completion status of a task.
  */
-export type TaskStatus = "success" | "failure" | "skipped";
+export type TaskStatus = "success" | "failure" | "skipped" | "cancelled";

package/dist/TaskStep.d.ts

@@ -11,7 +11,8 @@ export interface TaskStep<TContext> {
     /**
      * The core logic of the task.
      * @param context The shared context object, allowing for state to be passed between tasks.
+     * @param signal An optional AbortSignal to listen for cancellation.
      * @returns A Promise that resolves to a TaskResult.
      */
-    run(context: TContext): Promise<TaskResult>;
+    run(context: TContext, signal?: AbortSignal): Promise<TaskResult>;
 }

package/dist/WorkflowExecutor.d.ts

@@ -1,6 +1,8 @@
 import { TaskStep } from "./TaskStep.js";
 import { TaskResult } from "./TaskResult.js";
 import { EventBus } from "./EventBus.js";
+import { TaskStateManager } from "./TaskStateManager.js";
+import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 /**
  * Handles the execution of the workflow steps.
  * @template TContext The shape of the shared context object.
@@ -8,32 +10,24 @@ import { EventBus } from "./EventBus.js";
 export declare class WorkflowExecutor<TContext> {
     private context;
     private eventBus;
-    private running;
+    private stateManager;
+    private strategy;
     /**
      * @param context The shared context object.
      * @param eventBus The event bus to emit events.
+     * @param stateManager Manages execution state.
+     * @param strategy Execution strategy.
      */
-    constructor(context: TContext, eventBus: EventBus<TContext>);
+    constructor(context: TContext, eventBus: EventBus<TContext>, stateManager: TaskStateManager<TContext>, strategy: IExecutionStrategy<TContext>);
     /**
      * Executes the given steps.
      * @param steps The list of steps to execute.
+     * @param signal Optional AbortSignal for cancellation.
      * @returns A Promise that resolves to a map of task results.
      */
-    execute(steps: TaskStep<TContext>[]): Promise<Map<string, TaskResult>>;
+    execute(steps: TaskStep<TContext>[], signal?: AbortSignal): Promise<Map<string, TaskResult>>;
     /**
-     * Logic to identify tasks that can be started or must be skipped.
+     * Logic to identify tasks that can be started and run them.
      */
-    private processQueue;
-    /**
-     * Identifies steps that cannot run because a dependency failed.
-     */
-    private handleSkippedTasks;
-    /**
-     * Returns steps where all dependencies have finished successfully.
-     */
-    private getReadySteps;
-    /**
-     * Handles the lifecycle of a single task execution.
-     */
-    private runStep;
+    private processLoop;
 }

package/dist/WorkflowExecutor.js

@@ -5,97 +5,95 @@
 export class WorkflowExecutor {
     context;
     eventBus;
-    running = new Set();
+    stateManager;
+    strategy;
     /**
      * @param context The shared context object.
      * @param eventBus The event bus to emit events.
+     * @param stateManager Manages execution state.
+     * @param strategy Execution strategy.
      */
-    constructor(context, eventBus) {
+    constructor(context, eventBus, stateManager, strategy) {
         this.context = context;
         this.eventBus = eventBus;
+        this.stateManager = stateManager;
+        this.strategy = strategy;
     }
     /**
      * Executes the given steps.
      * @param steps The list of steps to execute.
+     * @param signal Optional AbortSignal for cancellation.
      * @returns A Promise that resolves to a map of task results.
      */
-    async execute(steps) {
+    async execute(steps, signal) {
         this.eventBus.emit("workflowStart", { context: this.context, steps });
-        const results = new Map();
+        this.stateManager.initialize(steps);
+        // Check if already aborted
+        if (signal?.aborted) {
+            this.stateManager.cancelAllPending("Workflow cancelled before execution started.");
+            const results = this.stateManager.getResults();
+            this.eventBus.emit("workflowEnd", { context: this.context, results });
+            return results;
+        }
         const executingPromises = new Set();
-        // Initial pass
-        this.processQueue(steps, results, executingPromises);
-        while (results.size < steps.length && executingPromises.size > 0) {
-            // Wait for the next task to finish
-            await Promise.race(executingPromises);
-            // After a task finishes, check for new work
-            this.processQueue(steps, results, executingPromises);
+        const onAbort = () => {
+            // Mark all pending tasks as cancelled
+            this.stateManager.cancelAllPending("Workflow cancelled.");
+        };
+        if (signal) {
+            signal.addEventListener("abort", onAbort);
         }
-        this.eventBus.emit("workflowEnd", { context: this.context, results });
-        return results;
-    }
-    /**
-     * Logic to identify tasks that can be started or must be skipped.
-     */
-    processQueue(steps, results, executingPromises) {
-        this.handleSkippedTasks(steps, results);
-        const readySteps = this.getReadySteps(steps, results);
-        for (const step of readySteps) {
-            const taskPromise = this.runStep(step, results).then(() => {
-                executingPromises.delete(taskPromise);
-            });
-            executingPromises.add(taskPromise);
+        try {
+            // Initial pass
+            this.processLoop(executingPromises, signal);
+            while (this.stateManager.hasPendingTasks() ||
+                this.stateManager.hasRunningTasks()) {
+                // Safety check: if no tasks are running and we still have pending tasks,
+                // it means we are stuck (e.g. cycle or unhandled dependency).
+                // Since valid graphs shouldn't have this, we break to avoid infinite loop.
+                if (executingPromises.size === 0) {
+                    break;
+                }
+                else {
+                    // Wait for the next task to finish
+                    await Promise.race(executingPromises);
+                }
+                if (signal?.aborted) {
+                    this.stateManager.cancelAllPending("Workflow cancelled.");
+                }
+                else {
+                    // After a task finishes, check for new work
+                    this.processLoop(executingPromises, signal);
+                }
+            }
+            // Ensure everything is accounted for (e.g. if loop exited early)
+            this.stateManager.cancelAllPending("Workflow cancelled.");
+            const results = this.stateManager.getResults();
+            this.eventBus.emit("workflowEnd", { context: this.context, results });
+            return results;
         }
-    }
-    /**
-     * Identifies steps that cannot run because a dependency failed.
-     */
-    handleSkippedTasks(steps, results) {
-        const pendingSteps = steps.filter((step) => !results.has(step.name) && !this.running.has(step.name));
-        for (const step of pendingSteps) {
-            const deps = step.dependencies ?? [];
-            const failedDep = deps.find((dep) => results.has(dep) && results.get(dep)?.status !== "success");
-            if (failedDep) {
-                const result = {
-                    status: "skipped",
-                    message: `Skipped due to failed dependency: ${failedDep}`,
-                };
-                results.set(step.name, result);
-                this.eventBus.emit("taskSkipped", { step, result });
+        finally {
+            if (signal) {
+                signal.removeEventListener("abort", onAbort);
             }
         }
     }
     /**
-     * Returns steps where all dependencies have finished successfully.
-     */
-    getReadySteps(steps, results) {
-        return steps.filter((step) => {
-            if (results.has(step.name) || this.running.has(step.name))
-                return false;
-            const deps = step.dependencies ?? [];
-            return deps.every((dep) => results.has(dep) && results.get(dep)?.status === "success");
-        });
-    }
-    /**
-     * Handles the lifecycle of a single task execution.
+     * Logic to identify tasks that can be started and run them.
      */
-    async runStep(step, results) {
-        this.running.add(step.name);
-        this.eventBus.emit("taskStart", { step });
-        try {
-            const result = await step.run(this.context);
-            results.set(step.name, result);
-        }
-        catch (e) {
-            results.set(step.name, {
-                status: "failure",
-                error: e instanceof Error ? e.message : String(e),
+    processLoop(executingPromises, signal) {
+        const toRun = this.stateManager.processDependencies();
+        // Execute ready tasks
+        for (const step of toRun) {
+            this.stateManager.markRunning(step);
+            const taskPromise = this.strategy.execute(step, this.context, signal)
+                .then((result) => {
+                this.stateManager.markCompleted(step, result);
+            })
+                .finally(() => {
+                executingPromises.delete(taskPromise);
             });
-        }
-        finally {
-            this.running.delete(step.name);
-            const result = results.get(step.name);
-            this.eventBus.emit("taskEnd", { step, result });
+            executingPromises.add(taskPromise);
         }
     }
 }

package/dist/WorkflowExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowExecutor.js","sourceRoot":"","sources":["../src/WorkflowExecutor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"WorkflowExecutor.js","sourceRoot":"","sources":["../src/WorkflowExecutor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { TaskRunner } from "./TaskRunner.js";
+export { TaskRunnerBuilder } from "./TaskRunnerBuilder.js";
+export { TaskStateManager } from "./TaskStateManager.js";
+export { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
+export type { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 export type { TaskStep } from "./TaskStep.js";
 export type { TaskResult } from "./TaskResult.js";
 export type { TaskStatus } from "./TaskStatus.js";

package/dist/index.js

@@ -1,2 +1,5 @@
 export { TaskRunner } from "./TaskRunner.js";
+export { TaskRunnerBuilder } from "./TaskRunnerBuilder.js";
+export { TaskStateManager } from "./TaskStateManager.js";
+export { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/strategies/IExecutionStrategy.d.ts

@@ -0,0 +1,16 @@
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Interface for task execution strategies.
+ * Allows different execution behaviors (e.g., standard, dry-run, debugging).
+ */
+export interface IExecutionStrategy<TContext> {
+    /**
+     * Executes a single task step.
+     * @param step The task step to execute.
+     * @param context The shared context.
+     * @param signal Optional abort signal.
+     * @returns A promise resolving to the task result.
+     */
+    execute(step: TaskStep<TContext>, context: TContext, signal?: AbortSignal): Promise<TaskResult>;
+}

package/dist/strategies/IExecutionStrategy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IExecutionStrategy.js.map

package/dist/strategies/IExecutionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/IExecutionStrategy.ts"],"names":[],"mappings":""}

package/dist/strategies/StandardExecutionStrategy.d.ts

@@ -0,0 +1,9 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Standard execution strategy that runs the task's run method.
+ */
+export declare class StandardExecutionStrategy<TContext> implements IExecutionStrategy<TContext> {
+    execute(step: TaskStep<TContext>, context: TContext, signal?: AbortSignal): Promise<TaskResult>;
+}

package/dist/strategies/StandardExecutionStrategy.js

@@ -0,0 +1,25 @@
+/**
+ * Standard execution strategy that runs the task's run method.
+ */
+export class StandardExecutionStrategy {
+    async execute(step, context, signal) {
+        try {
+            return await step.run(context, signal);
+        }
+        catch (e) {
+            // Check if error is due to abort
+            if (signal?.aborted &&
+                (e instanceof Error && e.name === "AbortError" || signal.reason === e)) {
+                return {
+                    status: "cancelled",
+                    message: "Task cancelled during execution",
+                };
+            }
+            return {
+                status: "failure",
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+}
+//# sourceMappingURL=StandardExecutionStrategy.js.map

package/dist/strategies/StandardExecutionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StandardExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/StandardExecutionStrategy.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,OAAO,yBAAyB;IAGpC,KAAK,CAAC,OAAO,CACX,IAAwB,EACxB,OAAiB,EACjB,MAAoB;QAEpB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,iCAAiC;YACjC,IACE,MAAM,EAAE,OAAO;gBACf,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,EACtE,CAAC;gBACD,OAAO;oBACL,MAAM,EAAE,WAAW;oBACnB,OAAO,EAAE,iCAAiC;iBAC3C,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,MAAM,EAAE,SAAS;gBACjB,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;aAClD,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/openspec/changes/add-concurrency-control/proposal.md

@@ -0,0 +1,14 @@
+# Change: Add Concurrency Control
+
+## Why
+The current implementation executes *all* independent tasks in parallel. In large graphs with many independent nodes, this could overwhelm system resources (CPU, memory) or trigger external API rate limits.
+
+## What Changes
+- Add a concurrency control mechanism to the `TaskRunner`.
+- Add `concurrency: number` to the `TaskRunnerExecutionConfig`.
+- Implement a task queue to hold tasks that are ready but waiting for a free slot.
+- Update `WorkflowExecutor` to respect the concurrency limit.
+
+## Impact
+- Affected specs: `task-runner`
+- Affected code: `src/TaskRunner.ts`, `src/WorkflowExecutor.ts`, `src/TaskRunnerExecutionConfig.ts`

package/openspec/changes/add-concurrency-control/tasks.md

@@ -0,0 +1,9 @@
+## Implementation
+- [ ] 1.1 Update `TaskRunnerExecutionConfig` to include an optional `concurrency` property.
+- [ ] 1.2 Update `WorkflowExecutor` to accept the `concurrency` limit.
+- [ ] 1.3 Implement a task queueing mechanism in `WorkflowExecutor` to manage pending tasks.
+- [ ] 1.4 Update execution logic to check available concurrency slots before starting a task.
+- [ ] 1.5 Ensure task completion triggers the execution of queued tasks.
+- [ ] 1.6 Verify that unlimited concurrency (default behavior) is preserved when no limit is set.
+- [ ] 1.7 Add unit tests for concurrency limits (e.g., ensure no more than N tasks run at once).
+- [ ] 1.8 Add integration tests with mixed dependencies and concurrency limits.

package/openspec/changes/add-task-retry-policy/proposal.md

@@ -0,0 +1,13 @@
+# Change: Add Task Retry Policy
+
+## Why
+Tasks currently run once and fail immediately if they throw an error or return a failure status. Network glitches or transient issues can therefore cause an entire workflow to fail unnecessarily.
+
+## What Changes
+- Allow tasks to define a retry policy.
+- Update `TaskStep` interface to include optional `retry` configuration.
+- Implement logic in `TaskRunner` (or `WorkflowExecutor`) to catch failures, check the retry policy, and re-execute the task after the specified delay.
+
+## Impact
+- Affected specs: `task-runner`
+- Affected code: `src/TaskStep.ts`, `src/WorkflowExecutor.ts` (or `TaskRunner.ts`), `src/contracts/TaskRetryConfig.ts`

package/openspec/changes/add-task-retry-policy/tasks.md

@@ -0,0 +1,10 @@
+## Implementation
+- [ ] 1.1 Create `TaskRetryConfig` interface with `attempts`, `delay`, and `backoff`.
+- [ ] 1.2 Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
+- [ ] 1.3 Update execution logic to catch task failures.
+- [ ] 1.4 Implement retry loop/recursion checking `attempts` count.
+- [ ] 1.5 Implement delay logic with support for `fixed` and `exponential` backoff.
+- [ ] 1.6 Ensure `TaskResult` reflects the final status after retries (success if eventually succeeds, failure if all attempts fail).
+- [ ] 1.7 Add unit tests for successful retry after failure.
+- [ ] 1.8 Add unit tests for exhaustion of retry attempts (final failure).
+- [ ] 1.9 Add unit tests for backoff timing (mock timers).

package/openspec/changes/add-workflow-preview/proposal.md

@@ -0,0 +1,12 @@
+# Change: Add Workflow Preview
+
+## Why
+It can be difficult to understand the execution flow of complex dependency graphs just by looking at the code. Users also currently cannot easily verify the execution plan without running the side effects, which carries risk.
+
+## What Changes
+- Add a `dryRun` execution mode to `TaskRunner`.
+- Add a helper method `getMermaidGraph(steps)` to generate a Mermaid.js diagram of the dependency graph.
+
+## Impact
+- Affected specs: `task-runner`
+- Affected code: `src/TaskRunner.ts`, `src/TaskRunnerExecutionConfig.ts`

package/openspec/changes/add-workflow-preview/tasks.md

@@ -0,0 +1,7 @@
+## Implementation
+- [ ] 1.1 Update `TaskRunnerExecutionConfig` to include an optional `dryRun: boolean` property.
+- [ ] 1.2 Implement `dryRun` logic in `WorkflowExecutor` (traverse graph, validate order, skip `step.run()`, return `skipped` or `success` pseudo-status).
+- [ ] 1.3 Implement `getMermaidGraph(steps: TaskStep[])` method (can be static or instance method on `TaskRunner`).
+- [ ] 1.4 Ensure `dryRun` respects other configs like `concurrency` (if applicable) to simulate actual timing/order if possible, or just strict topological order.
+- [ ] 1.5 Add unit tests for `dryRun` ensuring no side effects occur.
+- [ ] 1.6 Add unit tests for `getMermaidGraph` output correctness (nodes and edges).

package/openspec/changes/archive/2026-01-18-add-external-task-cancellation/tasks.md

@@ -0,0 +1,10 @@
+## Implementation
+- [x] 1.1 Update `TaskRunner.execute` signature to accept an optional config object.
+- [x] 1.2 Implement logic within `TaskRunner` to listen for `AbortSignal` and initiate cancellation.
+- [x] 1.3 Implement global timeout mechanism using `AbortController` and `setTimeout`.
+- [x] 1.4 Propagate `AbortSignal` to individual `TaskStep` executions.
+- [x] 1.5 Ensure `TaskRunner` correctly handles tasks that are already aborted before execution.
+- [x] 1.6 Update `TaskResult` and `RunnerEvents` to reflect cancellation status.
+- [x] 1.7 Add unit tests for `AbortSignal` cancellation scenarios.
+- [x] 1.8 Add unit tests for global timeout scenarios.
+- [x] 1.9 Add integration tests covering both `AbortSignal` and timeout interactions.

package/openspec/changes/archive/2026-01-18-add-integration-tests/proposal.md

@@ -0,0 +1,18 @@
+# Change: Add Comprehensive Integration Tests
+
+## Why
+The current test suite relies heavily on unit tests and mocks. To ensure robust behavior in real-world scenarios, we need comprehensive integration tests that execute full task graphs without mocks, validating complex configurations and interactions.
+
+## What Changes
+- Create a dedicated `tests/integration-tests/` directory.
+- Implement 10-20 integration test scenarios covering:
+  - Linear and branching dependencies.
+  - Failure handling and propagation.
+  - Context mutation and sharing.
+  - Timing and concurrency (real execution).
+  - Cancellation and timeouts.
+  - Error recovery (if retry policy is implemented, otherwise standard error states).
+
+## Impact
+- Affected specs: `task-runner` (no functional changes to the runtime, but validates existing specs)
+- Affected code: `tests/integration-tests/*`

package/openspec/changes/archive/2026-01-18-add-integration-tests/tasks.md

@@ -0,0 +1,17 @@
+## Implementation
+- [x] 1.1 Setup `tests/integration-tests/` directory and test runner config if needed.
+- [x] 1.2 Implement Scenario 1: Basic linear workflow (A -> B -> C) success.
+- [x] 1.3 Implement Scenario 2: Branching workflow (A -> [B, C] -> D) success.
+- [x] 1.4 Implement Scenario 3: Task failure and downstream skipping (A -> B(fail) -> C(skip)).
+- [x] 1.5 Implement Scenario 4: Shared context mutation (A writes, B reads).
+- [x] 1.6 Implement Scenario 5: Large graph execution (e.g., 20+ nodes).
+- [x] 1.7 Implement Scenario 6: Mixed duration tasks (verifying parallel efficiency).
+- [x] 1.8 Implement Scenario 7: Cancellation via AbortSignal in mid-execution.
+- [x] 1.9 Implement Scenario 8: Global timeout interrupting long tasks.
+- [x] 1.10 Implement Scenario 9: Dynamic context validation (tasks validating context state).
+- [x] 1.11 Implement Scenario 10: Circular dependency detection (at runtime validation).
+- [x] 1.12 Implement Scenario 11: Missing dependency handling.
+- [x] 1.13 Implement Scenario 12: Complex "Diamond" dependency graph.
+- [x] 1.14 Implement Scenario 13: Tasks with side-effects (e.g., file I/O or simulated network).
+- [x] 1.15 Implement Scenario 14: Zero-dependency parallel burst (all run at once).
+- [x] 1.16 Verification: Ensure all integration tests pass consistently.

package/openspec/changes/archive/2026-01-18-refactor-core-architecture/proposal.md

@@ -0,0 +1,14 @@
+# Change: Refactor Core Architecture
+
+## Why
+When multiple developers work on the project, conflicts arise due to tight coupling and poor separation of concerns. Large classes like `WorkflowExecutor` are taking on too many responsibilities, and there is duplicated logic around graph traversal and state management.
+
+## What Changes
+- Decouple `WorkflowExecutor` from `EventBus` (pass a listener interface or use a mediating controller).
+- Extract `TaskExecutionStrategy` to allow pluggable execution modes (e.g., standard, dry-run, debug).
+- Centralize state management for task results and context, moving it out of the executor loop.
+- Standardize error handling and logging (QoL improvements).
+
+## Impact
+- Affected specs: `task-runner` (no behavior change, but structural refactor)
+- Affected code: `src/WorkflowExecutor.ts`, `src/TaskRunner.ts`, new files for extracted logic.