@calmo/task-runner 4.0.4 → 4.2.0

package/dist/strategies/DryRunExecutionStrategy.d.ts

@@ -12,5 +12,5 @@ export declare class DryRunExecutionStrategy<TContext> implements IExecutionStra
      * @param signal Optional abort signal (ignored).
      * @returns A promise resolving to a success result.
      */
-    execute(_step: TaskStep<TContext>, _context: TContext, _signal?: AbortSignal): Promise<TaskResult>;
+    execute(step: TaskStep<TContext>, _context: TContext, _signal?: AbortSignal): Promise<TaskResult>;
 }

package/dist/strategies/DryRunExecutionStrategy.js

@@ -9,16 +9,14 @@ export class DryRunExecutionStrategy {
      * @param signal Optional abort signal (ignored).
      * @returns A promise resolving to a success result.
      */
-    async execute(
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    _step, 
+    async execute(step, 
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _context, 
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _signal) {
         return Promise.resolve({
             status: "success",
-            message: "Dry run: simulated success",
+            message: "Dry run: simulated success " + step.name,
         });
     }
 }

package/dist/strategies/DryRunExecutionStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"DryRunExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/DryRunExecutionStrategy.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAGlC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO;IACX,6DAA6D;IAC7D,KAAyB;IACzB,6DAA6D;IAC7D,QAAkB;IAClB,6DAA6D;IAC7D,OAAqB;QAErB,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,4BAA4B;SACtC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"DryRunExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/DryRunExecutionStrategy.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAGlC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CACX,IAAwB;IACxB,6DAA6D;IAC7D,QAAkB;IAClB,6DAA6D;IAC7D,OAAqB;QAErB,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,6BAA6B,GAAG,IAAI,CAAC,IAAI;SACnD,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/utils/PriorityQueue.d.ts

@@ -0,0 +1,13 @@
+export declare class PriorityQueue<T> {
+    private heap;
+    private sequenceCounter;
+    push(item: T, priority: number): void;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    size(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    private bubbleUp;
+    private sinkDown;
+    private compare;
+}

package/dist/utils/PriorityQueue.js

@@ -0,0 +1,82 @@
+export class PriorityQueue {
+    heap = [];
+    sequenceCounter = 0;
+    push(item, priority) {
+        const node = { item, priority, sequenceId: this.sequenceCounter++ };
+        this.heap.push(node);
+        this.bubbleUp();
+    }
+    pop() {
+        if (this.heap.length === 0)
+            return undefined;
+        if (this.heap.length === 1)
+            return this.heap.pop().item;
+        const top = this.heap[0];
+        this.heap[0] = this.heap.pop();
+        this.sinkDown();
+        return top.item;
+    }
+    peek() {
+        return this.heap[0]?.item;
+    }
+    size() {
+        return this.heap.length;
+    }
+    isEmpty() {
+        return this.heap.length === 0;
+    }
+    clear() {
+        this.heap = [];
+        this.sequenceCounter = 0;
+    }
+    bubbleUp() {
+        let index = this.heap.length - 1;
+        const element = this.heap[index];
+        while (index > 0) {
+            const parentIndex = Math.floor((index - 1) / 2);
+            const parent = this.heap[parentIndex];
+            if (this.compare(element, parent) <= 0)
+                break;
+            this.heap[index] = parent;
+            this.heap[parentIndex] = element;
+            index = parentIndex;
+        }
+    }
+    sinkDown() {
+        let index = 0;
+        const length = this.heap.length;
+        const element = this.heap[0];
+        while (true) {
+            const leftChildIndex = 2 * index + 1;
+            const rightChildIndex = 2 * index + 2;
+            let swapIndex = null;
+            if (leftChildIndex < length) {
+                if (this.compare(this.heap[leftChildIndex], element) > 0) {
+                    swapIndex = leftChildIndex;
+                }
+            }
+            if (rightChildIndex < length) {
+                const rightChild = this.heap[rightChildIndex];
+                const leftChild = this.heap[leftChildIndex];
+                if ((swapIndex === null && this.compare(rightChild, element) > 0) ||
+                    (swapIndex !== null && this.compare(rightChild, leftChild) > 0)) {
+                    swapIndex = rightChildIndex;
+                }
+            }
+            if (swapIndex === null)
+                break;
+            this.heap[index] = this.heap[swapIndex];
+            this.heap[swapIndex] = element;
+            index = swapIndex;
+        }
+    }
+    // Returns positive if a > b (a should come before b)
+    compare(a, b) {
+        if (a.priority !== b.priority) {
+            return a.priority - b.priority;
+        }
+        // Lower sequenceId means earlier insertion, so it has higher priority
+        return b.sequenceId - a.sequenceId;
+    }
+}
+//# sourceMappingURL=PriorityQueue.js.map

package/dist/utils/PriorityQueue.js.map

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

package/openspec/changes/add-middleware-support/proposal.md

@@ -0,0 +1,19 @@
+# Change: Add Middleware Support
+
+## Why
+
+Developers currently duplicate code for cross-cutting concerns like logging, error handling policies, context validation, and metrics across every task definition. This leads to code duplication, inconsistent behavior, and maintenance burden. There is no standard way to inject logic "around" task execution globally.
+
+## What Changes
+
+- **Middleware Interface**: Introduce a `Middleware<T>` type representing a function that wraps task execution.
+- **TaskRunnerBuilder**: Add a `.use(middleware)` method to register middleware functions.
+- **TaskRunner**:
+    - Store the chain of middleware.
+    - During execution, wrap the `Strategy.execute` call with the middleware chain (onion model).
+    - Ensure middleware runs *before* the task starts and *after* it finishes (or fails).
+
+## Impact
+
+- Affected specs: `task-runner`
+- Affected code: `TaskRunner.ts`, `TaskRunnerBuilder.ts`, `WorkflowExecutor.ts`, `contracts/Middleware.ts`

package/openspec/changes/add-middleware-support/specs/task-runner/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Global Middleware Support
+
+The system SHALL support registering global middleware functions that intercept and wrap the execution of every `TaskStep`.
+
+#### Scenario: Middleware Execution Order
+
+- **GIVEN** a `TaskRunner` with two middleware functions: `A` (outer) and `B` (inner)
+- **WHEN** a task is executed
+- **THEN** `A` runs before `B`
+- **AND** `B` runs before the task strategy
+- **AND** the task strategy runs
+- **AND** `B` runs after the task strategy
+- **AND** `A` runs after `B`.
+
+#### Scenario: Modifying Task Result
+
+- **GIVEN** a middleware that modifies the returned result
+- **WHEN** a task completes successfully
+- **THEN** the final result stored in the runner MUST match the result returned by the middleware.
+
+#### Scenario: Blocking Execution
+
+- **GIVEN** a middleware that returns a result *without* calling `next()`
+- **WHEN** the task is scheduled
+- **THEN** the task strategy SHALL NOT be executed
+- **AND** the task result SHALL be the one returned by the middleware.
+
+#### Scenario: Context Access
+
+- **GIVEN** a middleware function
+- **WHEN** it is invoked
+- **THEN** it SHALL have access to the current `TaskStep` and shared `context`.

package/openspec/changes/add-middleware-support/tasks.md

@@ -0,0 +1,9 @@
+## 1. Implementation
+
+- [ ] 1.1 Define `Middleware` and `MiddlewareNext` types in `src/contracts/Middleware.ts`.
+- [ ] 1.2 Update `TaskRunner` class to store a list of middleware functions.
+- [ ] 1.3 Implement `composeMiddleware` utility to create the onion chain.
+- [ ] 1.4 Update `WorkflowExecutor` or `TaskRunner` (wherever strategy is invoked) to wrap the strategy execution with composed middleware.
+- [ ] 1.5 Update `TaskRunnerBuilder` to expose `.use(middleware)` method.
+- [ ] 1.6 Add unit tests for Middleware composition and execution order.
+- [ ] 1.7 Add integration test demonstrating a Logging Middleware and a Policy Middleware (skipping task).

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

@@ -0,0 +1,18 @@
+# Change: Add Resource-Based Concurrency Control
+
+## Why
+
+Global concurrency limits (`concurrency: 5`) are too blunt for workflows accessing heterogeneous resources. A workflow might bottleneck on a slow API (e.g., Jira) while underutilizing a fast one (e.g., Redis). Users need to define concurrency limits *per resource type* (e.g., "max 2 Jira requests", "max 50 DB writes") to optimize throughput without overloading specific downstream services.
+
+## What Changes
+
+- **TaskStep Interface**: Add `resources` property (e.g., `{ cpu: 1, github_api: 1 }`).
+- **TaskRunnerExecutionConfig**: Add `resourceLimits` property (e.g., `{ github_api: 5 }`).
+- **WorkflowExecutor**: Update the `processLoop` to check if *both* global concurrency AND specific resource limits are satisfied before starting a task.
+- **State Management**: Track currently consumed resources in `WorkflowExecutor`.
+
+## Impact
+
+- **Affected Specs**: `task-runner`
+- **Affected Code**: `src/TaskStep.ts`, `src/TaskRunnerExecutionConfig.ts`, `src/WorkflowExecutor.ts`.
+- **Breaking Changes**: None. Optional properties added.

package/openspec/changes/add-resource-concurrency/specs/task-runner/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: Resource-Based Concurrency Control
+
+The system SHALL support limiting concurrency based on abstract resources defined by tasks.
+
+#### Scenario: Task defines resource usage
+- **GIVEN** a `TaskStep` with `resources: { "api_call": 1 }`
+- **WHEN** the task is executed
+- **THEN** the system SHALL account for 1 unit of "api_call" consumption.
+
+#### Scenario: Execution limited by resource availability
+- **GIVEN** `resourceLimits` is configured with `{ "db_connection": 2 }`
+- **AND** 3 tasks are ready, each requiring 1 "db_connection"
+- **WHEN** execution proceeds
+- **THEN** only 2 tasks SHALL execute concurrently.
+- **AND** the 3rd task SHALL wait until resources are released.
+
+#### Scenario: Global and Resource limits combined
+- **GIVEN** `concurrency` is set to 5
+- **AND** `resourceLimits` is `{ "heavy_job": 2 }`
+- **AND** 10 tasks are ready: 5 "heavy_job" tasks and 5 "light" tasks (no resources)
+- **WHEN** execution proceeds
+- **THEN** at most 2 "heavy_job" tasks SHALL run.
+- **AND** up to 3 "light" tasks MAY run concurrently (totaling 5).

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

@@ -0,0 +1,10 @@
+## 1. Implementation
+
+- [ ] 1.1 Update `TaskStep` interface in `src/TaskStep.ts` to include `resources?: Record<string, number>`.
+- [ ] 1.2 Update `TaskRunnerExecutionConfig` in `src/TaskRunnerExecutionConfig.ts` to include `resourceLimits?: Record<string, number>`.
+- [ ] 1.3 Update `WorkflowExecutor` to track active resource usage.
+- [ ] 1.4 Update `WorkflowExecutor.processLoop` to validate resource availability before scheduling tasks.
+- [ ] 1.5 Update `WorkflowExecutor.executeTaskStep` (or equivalent completion logic) to release resources when a task finishes.
+- [ ] 1.6 Add unit tests for resource limiting in `tests/WorkflowExecutor.test.ts`.
+- [ ] 1.7 Add integration test for mixed resource usage in `tests/integration/resource-concurrency.test.ts`.
+- [ ] 1.8 Update README.md to include docs and examples on resource concurrency configuration

package/openspec/changes/allow-plugin-hooks/design.md

@@ -0,0 +1,51 @@
+# Plugin Hooks Design
+
+## Architecture
+
+We will extend the `PluginManager` to manage a list of hooks. The `WorkflowExecutor` will call these hooks at appropriate times.
+
+### Hook Interfaces
+
+```typescript
+export type PreTaskHookResult<TContext> =
+  | { action: "continue" }
+  | { action: "skip"; message?: string }
+  | { action: "fail"; error: Error };
+
+export type PreTaskHook<TContext> = (
+  step: TaskStep<TContext>,
+  context: TContext
+) => Promise<PreTaskHookResult<TContext> | void> | void; // void implies continue
+
+export type PostTaskHook<TContext> = (
+  step: TaskStep<TContext>,
+  context: TContext,
+  result: TaskResult
+) => Promise<TaskResult | void> | void; // void implies return original result
+```
+
+### PluginContext Extension
+
+```typescript
+export interface PluginContext<TContext> {
+    events: EventBus<TContext>;
+    preTask(hook: PreTaskHook<TContext>): void;
+    postTask(hook: PostTaskHook<TContext>): void;
+}
+```
+
+### Execution Flow
+
+**In `WorkflowExecutor.executeTaskStep`:**
+
+1.  **Run Pre-Hooks (Sequential)**
+    -   Iterate through registered pre-hooks.
+    -   If any returns `skip`, mark task skipped and return.
+    -   If any returns `fail`, mark task failed and return.
+    -   (Future: allow modifying context contextually? Context is mutable so yes).
+
+2.  **Execute Task** (Original logic)
+
+3.  **Run Post-Hooks (Sequential)**
+    -   Pass the result to hooks.
+    -   Hooks can return a new `TaskResult` to overwrite the current one.

package/openspec/changes/allow-plugin-hooks/proposal.md

@@ -0,0 +1,12 @@
+# Allow Plugin hooks
+
+## Summary
+Introduce pre-task and post-task hooks to the Plugin System, allowing plugins to intercept task execution, modify behavior, or transform results.
+
+## Motivation
+Current plugins are limited to "observation" via read-only events. To enable advanced use cases like caching, validation, or policy enforcement, plugins need to be able to intervene in the execution flow.
+
+## Scope
+-   **Pre-Task Hooks**: Runs before a task. Can skip, fail, or modify task/context.
+-   **Post-Task Hooks**: Runs after a task. Can modify the result.
+-   **Hook Registration**: Add `registerPreHook` and `registerPostHook` to `PluginContext`.

package/openspec/changes/allow-plugin-hooks/specs/post-task/spec.md

@@ -0,0 +1,21 @@
+# Post-Task Hooks Requirements
+
+## ADDED Requirements
+
+### Requirement: Execute Post-Task Hooks after task execution
+
+The `WorkflowExecutor` MUST execute all registered post-task hooks after a task completes (success or failure).
+
+#### Scenario: Running post hooks
+Given registered post-task hooks
+When a task finishes execution
+Then hooks are executed sequentially with access to the task result
+
+### Requirement: Modify result via hook
+
+The runner MUST allow post-task hooks to modify the task result.
+
+#### Scenario: Modifying result status
+Given a post-task hook that returns a new `TaskResult`
+When a task finishes
+Then the final result of the task is updated to the one returned by the hook

package/openspec/changes/allow-plugin-hooks/specs/pre-task/spec.md

@@ -0,0 +1,32 @@
+# Pre-Task Hooks Requirements
+
+## ADDED Requirements
+
+### Requirement: Execute Pre-Task Hooks before task execution
+
+The `WorkflowExecutor` MUST execute all registered pre-task hooks before running a task.
+
+#### Scenario: Running multiple hooks
+Given multiple registered pre-task hooks
+When a task is about to run
+Then hooks are executed sequentially in registration order
+
+### Requirement: Skip task execution via hook
+
+The runner MUST skip task execution if a pre-task hook returns a skip action.
+
+#### Scenario: Skipping task
+Given a pre-task hook that returns `{ action: "skip" }`
+When a task is about to run
+Then the task is marked as skipped
+And execution proceeds to the next task
+
+### Requirement: Fail task execution via hook
+
+The runner MUST fail task execution if a pre-task hook returns a fail action.
+
+#### Scenario: Failing task
+Given a pre-task hook that returns `{ action: "fail", error: Error("Reason") }`
+When a task is about to run
+Then the task is marked as failed with the provided error
+And failure cascades to dependent tasks

package/openspec/changes/allow-plugin-hooks/tasks.md

@@ -0,0 +1,7 @@
+- [-] Implement Plugin Hooks
+  - [ ] Define Hook Types and Interfaces <!-- id: 0 -->
+  - [ ] Update `PluginContext` to include `preTask` and `postTask` <!-- id: 1 -->
+  - [ ] Implement Hook Registry in `PluginManager` <!-- id: 2 -->
+  - [ ] Integrate Pre-Task Hooks in `WorkflowExecutor` <!-- id: 3 -->
+  - [ ] Integrate Post-Task Hooks in `WorkflowExecutor` <!-- id: 4 -->
+  - [ ] Add tests for hook execution and interruption <!-- id: 5 -->

package/openspec/changes/{feat-task-metrics → archive/2026-01-22-feat-task-metrics}/proposal.md

@@ -7,7 +7,7 @@ Users currently lack visibility into the performance of individual tasks within
 ## What Changes
 
 - Update `TaskResult` interface to include an optional `metrics` property containing `startTime`, `endTime`, and `duration`.
-- Update `WorkflowExecutor` to capture these timestamps during task execution and populate the `metrics` property.
+- Update `WorkflowExecutor` to capture these timestamps using `performance.now()` for high-precision timing during task execution and populate the `metrics` property.
 - Ensure these metrics are available in the final `TaskResult` map returned by `TaskRunner.execute`.
 
 ## Impact

package/openspec/changes/archive/2026-01-22-feat-task-metrics/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+
+- [x] 1.1 Update `TaskResult` interface in `src/TaskResult.ts` to include `metrics`.
+- [x] 1.2 Update `WorkflowExecutor.ts` to capture start/end times using `performance.now()` and calculate duration.
+- [x] 1.3 Update `WorkflowExecutor.ts` to inject metrics into the `TaskResult`.
+- [x] 1.4 Add unit tests in `tests/TaskMetrics.test.ts` to verify metrics are present and correct.

package/openspec/changes/archive/2026-02-15-implement-plugin-system/design.md

@@ -0,0 +1,45 @@
+# Plugin System Design
+
+## Architecture
+
+The plugin system will resolve around a `PluginManager` that is owned by the `TaskRunner`.
+
+### Plugin Interface
+
+A plugin is defined as:
+
+```typescript
+export interface Plugin<TContext> {
+  name: string;
+  version: string;
+  install(context: PluginContext<TContext>): void | Promise<void>;
+}
+```
+
+### Plugin Context
+
+The `install` method receives a `PluginContext`, which exposes capabilities to the plugin:
+
+```typescript
+export interface PluginContext<TContext> {
+  events: EventBus<TContext>; // Access to listen/emit events
+  // Potentially other APIs in the future, e.g., registerTask, logger, etc.
+}
+```
+
+### Lifecycle
+
+1. **Registration**: Plugins are registered via `taskRunner.use(plugin)`.
+2. **Installation**: When `taskRunner.execute()` is called (or explicitly before), the `PluginManager` iterates over registered plugins and calls `install()`.
+3. **Execution**: Plugins listen to events or hooks during execution.
+
+### Error Handling
+
+- Implementation should handle plugin failures during `install` gracefully (fail fast or log and continue, defined by config).
+- Runtime errors in listeners should be caught to avoid crashing the runner, though `EventBus` current implementation might need review.
+
+## Components
+
+- `src/contracts/Plugin.ts`: Interface definition.
+- `src/PluginManager.ts`: Manages the list of plugins and their initialization.
+- `src/TaskRunner.ts`: Modified to include `use()` method and delegate to `PluginManager`.

package/openspec/changes/archive/2026-02-15-implement-plugin-system/proposal.md

@@ -0,0 +1,13 @@
+# Propose Plugin System
+
+## Summary
+Introduce a plugin system to the `task-runner` that allows external modules to alter behavior, listen to events, and interact with the execution context via a defined API.
+
+## Motivation
+Currently, extending the `task-runner` requires modifying the core codebase. To enable a more collaborative and decentralized development model, we need a way for developers to inject custom logic, middleware, or event listeners without touching the core.
+
+## Scope
+- Define a strict `Plugin` interface.
+- Implement a `PluginManager` to handle plugin lifecycle (registration, initialization).
+- Expose an `EventBus` and `PluginContext` to plugins.
+- Ensure plugins can intercept or react to workflow lifecycle events (`workflowStart`, `taskStart`, etc.).

package/openspec/changes/archive/2026-02-15-implement-plugin-system/specs/plugin-context/spec.md

@@ -0,0 +1,17 @@
+# Plugin Context Requirements
+
+## ADDED 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/changes/archive/2026-02-15-implement-plugin-system/specs/plugin-loading/spec.md

@@ -0,0 +1,27 @@
+# Plugin Loading Requirements
+
+## ADDED 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/openspec/changes/archive/2026-02-15-implement-plugin-system/tasks.md

@@ -0,0 +1,7 @@
+- [x] Implement Plugin System
+  - [x] Define `Plugin` and `PluginContext` interfaces <!-- id: 0 -->
+  - [x] Implement `PluginManager` class <!-- id: 1 -->
+  - [x] Update `TaskRunner` to support `use()` method <!-- id: 2 -->
+  - [x] Integrate `PluginManager` into `TaskRunner` lifecycle <!-- id: 3 -->
+  - [x] Verify `EventBus` exposure to plugins <!-- id: 4 -->
+  - [x] Add integration tests for a sample plugin <!-- id: 5 -->

package/openspec/changes/feat-completion-dependencies/proposal.md

@@ -0,0 +1,58 @@
+# Feature: Completion Dependencies (Finally Tasks)
+
+## User Story
+"As a developer, I want to define tasks that run even if their dependencies fail (e.g., cleanup/teardown), so that I can ensure resources are released and the system is left in a clean state regardless of workflow success."
+
+## The "Why"
+Currently, the `TaskRunner` strictly propagates failures: if Task A fails, all tasks depending on A are automatically skipped. This behavior is correct for logical dependencies (e.g., "Build" -> "Deploy"), but strictly prohibits "Teardown" or "Compensation" patterns (e.g., "Provision" -> "Test" -> "Deprovision").
+
+If "Test" fails, "Deprovision" is skipped, leaving expensive resources running.
+
+While a `continueOnError` proposal exists, it marks a task as "Optional" (allowing *all* dependents to proceed). It does not support the case where:
+1. "Test" is CRITICAL (if it fails, the workflow should eventually fail).
+2. "Deprovision" MUST run after "Test".
+3. "Publish Results" (dependent on "Test") MUST skip if "Test" fails.
+
+We need a way to define **Dependency Behavior** at the edge level.
+
+## The "What"
+We will extend the `dependencies` property in `TaskStep` to support granular configuration.
+
+### Current
+```typescript
+dependencies: ["TaskA", "TaskB"]
+```
+
+### Proposed
+```typescript
+dependencies: [
+  "TaskA",
+  { step: "TaskB", runCondition: "always" } // or 'complete'
+]
+```
+
+The `runCondition` determines when the dependent becomes ready:
+- `success` (Default): Ready only if dependency succeeds.
+- `always`: Ready if dependency succeeds OR fails. (If dependency is *skipped*, the dependent is still skipped, as the parent never ran).
+
+## Acceptance Criteria
+- [ ] Support `dependencies` as an array of `string | DependencyConfig`.
+- [ ] `DependencyConfig` schema: `{ step: string; runCondition?: 'success' | 'always' }`.
+- [ ] **Scenario 1 (Success):** A -> B(always). A succeeds. B runs.
+- [ ] **Scenario 2 (Failure):** A -> B(always). A fails. B runs.
+- [ ] **Scenario 3 (Skip):** X(fail) -> A -> B(always). X fails, A skips. B skips (because A never ran).
+- [ ] **Scenario 4 (Hybrid):** A(fail) -> B(always) -> C(standard).
+    - A fails.
+    - B runs (cleanup).
+    - C skips (because B succeeded, but C implicitly depends on the *chain*? No, standard DAG. C depends on B. If B succeeds, C runs. Wait.)
+
+**Refining Scenario 4:**
+If C depends on B, and B runs (cleaning up A), C runs.
+This might not be desired if C assumes A succeeded.
+*Constraint:* If C depends on B, it only cares about B. If C cares about A, it must depend on A explicitly.
+*User Responsibility:* Users must ensure that if C depends on B (cleanup), C can handle the fact that A might have failed. Or, C should also depend on A (standard) if it needs A's success.
+
+## Constraints
+- **Backward Compatibility:** Existing `string[]` syntax must work exactly as before.
+- **Cycle Detection:** The validator must treat `{ step: "A" }` identical to `"A"` for cycle checks.
+- **Type Safety:** The context passed to the task remains `TContext`. The task must safeguard against missing data if a dependency failed (e.g., checking `ctx.data` before use).

package/openspec/changes/feat-completion-dependencies/tasks.md

@@ -0,0 +1,46 @@
+# Engineering Tasks: Completion Dependencies
+
+## 1. Contracts & Types
+- [ ] **Modify `src/TaskStep.ts`**
+    - Define `export type TaskRunCondition = 'success' | 'always';`
+    - Define `export interface TaskDependencyConfig { step: string; runCondition?: TaskRunCondition; }`
+    - Update `TaskStep` interface: `dependencies?: (string | TaskDependencyConfig)[];`
+
+## 2. Validation Logic
+- [ ] **Update `src/TaskGraphValidator.ts`**
+    - Update `validate` method to handle mixed string/object arrays.
+    - Extract the dependency name correctly for cycle detection and adjacency lists.
+    - Ensure `checkMissingDependencies` checks the `step` property of config objects.
+
+## 3. Core Logic (TaskStateManager)
+- [ ] **Update `src/TaskStateManager.ts`**
+    - **Data Structures**:
+        - Change `dependencyGraph` to store metadata: `Map<string, { step: TaskStep<TContext>, condition: TaskRunCondition }[]>`.
+    - **Initialization**:
+        - Parse the mixed `dependencies` array during `initialize`.
+        - Store the `runCondition` (default 'success') in the graph.
+    - **Failure Handling (`cascadeFailure`)**:
+        - When a task fails (or is skipped? No, only Failures trigger 'always'. Skips should still cascade Skips):
+        - Iterate dependents.
+        - If dependent has `condition === 'always'`:
+            - Treat as "success" (call `handleSuccess` logic or equivalent: decrement count).
+            - Do NOT add to `cascade` queue.
+        - If dependent has `condition === 'success'`:
+            - Mark skipped (existing logic).
+            - Add to `cascade` queue.
+    - **Skip Handling**:
+        - If a task is SKIPPED, dependents with `runCondition: 'always'` should ALSO be skipped (because the parent never ran).
+        - Ensure `cascadeFailure` distinguishes between "Failed" vs "Skipped" when checking the condition.
+
+## 4. Testing
+- [ ] **Unit Tests (`tests/TaskStateManager.test.ts`)**
+    - Test initialization with mixed types.
+    - Test failure propagation with 'always' condition (dependent runs).
+    - Test skip propagation with 'always' condition (dependent skips).
+- [ ] **Integration Tests (`tests/TaskRunner.test.ts`)**
+    - Create a "Teardown" scenario:
+        - Step 1: Setup (Success)
+        - Step 2: Work (Failure) -> Depends on 1
+        - Step 3: Cleanup (Success) -> Depends on 2 (Always)
+    - Verify Step 3 runs.
+    - Verify final Workflow status (should be Failure because Step 2 failed).

package/openspec/changes/feat-conditional-retries/proposal.md

@@ -0,0 +1,18 @@
+# Change: Conditional Retries
+
+## Why
+
+Currently, the `RetryingExecutionStrategy` treats all task failures equally. If a task has retry attempts configured, it will blindly retry even if the error is permanent (e.g., syntax error, invalid configuration) or logic-based (e.g., validation failure). This wastes resources and execution time. Users need a way to specify *which* errors should trigger a retry, allowing them to fail fast on critical errors while retrying on transient ones (e.g., network timeouts).
+
+## What Changes
+
+- Update `TaskRetryConfig` interface in `src/contracts/TaskRetryConfig.ts` to include an optional `shouldRetry` predicate.
+- Update `RetryingExecutionStrategy` in `src/strategies/RetryingExecutionStrategy.ts` to evaluate this predicate (if present) before deciding to retry.
+- If `shouldRetry` returns `false`, the retry loop is broken immediately, and the failure result is returned.
+- If `shouldRetry` is undefined, the existing behavior (retry on any failure) is preserved.
+
+## Impact
+
+- **Affected specs**: `001-generic-task-runner` (or simply `task-runner`)
+- **Affected code**: `src/contracts/TaskRetryConfig.ts`, `src/strategies/RetryingExecutionStrategy.ts`
+- **Non-breaking change**: The `shouldRetry` property is optional. Existing retry configurations will continue to work as before.