@calmo/task-runner 3.8.4 → 4.1.0

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,9 @@
+## 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`.

package/openspec/changes/archive/2026-01-18-add-concurrency-control/specs/task-runner/spec.md

@@ -0,0 +1,26 @@
+## ADDED Requirements
+
+### Requirement: Concurrency Limit
+
+The `WorkflowExecutor` SHALL limit the number of concurrently executing tasks if a `concurrency` limit is provided.
+
+#### Scenario: Concurrency limit applied
+
+- **GIVEN** a `WorkflowExecutor` configured with `concurrency: N`
+- **WHEN** multiple independent tasks become ready
+- **THEN** no more than N tasks SHALL be in the 'running' state simultaneously.
+
+#### Scenario: Queueing ready tasks
+
+- **WHEN** the number of running tasks equals the `concurrency` limit
+- **THEN** any additional tasks that become ready SHALL remain in the 'ready' state until a slot becomes available.
+
+#### Scenario: Slot release
+
+- **WHEN** a running task completes or fails
+- **THEN** the loop SHALL immediately check for ready tasks and start them up to the limit.
+
+#### Scenario: Default unlimited concurrency
+
+- **WHEN** `WorkflowExecutor` is initialized without a `concurrency` option (or 0/undefined)
+- **THEN** it SHALL execute all ready tasks immediately (unlimited concurrency).

package/openspec/changes/archive/2026-01-18-add-external-task-cancellation/specs/task-runner/spec.md

@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: TaskRunner Execution
+
+The `TaskRunner` SHALL execute a sequence of `TaskStep`s based on their dependencies, processing inputs and producing outputs.
+
+#### Scenario: Successful execution
+
+- **WHEN** all `TaskStep`s complete successfully
+- **THEN** the `TaskRunner` returns a successful workflow result.
+
+#### Scenario: Execution with AbortSignal
+
+- **WHEN** `TaskRunner.execute` is called with an `AbortSignal`
+- **THEN** the `TaskRunner` monitors the `AbortSignal` for cancellation requests.
+
+#### Scenario: Execution with Global Timeout
+
+- **WHEN** `TaskRunner.execute` is called with a `timeout` option
+- **THEN** the `TaskRunner` monitors the elapsed time for the workflow.
+
+### Requirement: External Workflow Cancellation
+
+The `TaskRunner` SHALL allow external cancellation of an ongoing workflow.
+
+#### Scenario: Workflow cancelled by AbortSignal
+
+- **WHEN** an `AbortSignal` provided to `TaskRunner.execute` is triggered
+- **THEN** the `TaskRunner` immediately attempts to stop execution of current and pending tasks.
+
+#### Scenario: Workflow cancelled by Global Timeout
+
+- **WHEN** the specified global `timeout` for `TaskRunner.execute` is reached
+- **THEN** the `TaskRunner` immediately attempts to stop execution of current and pending tasks.
+
+#### Scenario: Tasks marked as cancelled
+
+- **WHEN** a workflow is cancelled (by `AbortSignal` or `timeout`)
+- **THEN** all unexecuted `TaskStep`s SHALL be marked with a 'cancelled' status in the final result.
+
+#### Scenario: Pre-aborted workflow
+
+- **WHEN** `TaskRunner.execute` is called with an `AbortSignal` that is already aborted
+- **THEN** the `TaskRunner` SHALL return immediately with all tasks marked as cancelled, without executing any steps.
+
+#### Scenario: Graceful interruption of current task
+
+- **WHEN** a workflow is cancelled and a `TaskStep` is currently executing
+- **THEN** the `TaskStep` SHALL receive the cancellation signal (e.g., via `AbortSignal` context) to allow for graceful interruption.
+
+### Requirement: Cancellation Conflict Resolution
+
+The `TaskRunner` SHALL handle scenarios where both `AbortSignal` and global `timeout` are provided.
+
+#### Scenario: AbortSignal precedes Timeout
+
+- **WHEN** both `AbortSignal` and `timeout` are provided, and `AbortSignal` is triggered first
+- **THEN** the `TaskRunner` SHALL cancel the workflow based on the `AbortSignal`, ignoring the `timeout`.
+
+#### Scenario: Timeout precedes AbortSignal
+
+- **WHEN** both `AbortSignal` and `timeout` are provided, and `timeout` is reached first
+- **THEN** the `TaskRunner` SHALL cancel the workflow based on the `timeout`, ignoring the `AbortSignal`.

package/openspec/changes/archive/2026-01-18-add-integration-tests/specs/task-runner/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Integration Verification
+
+The system's integrity SHALL be verified through comprehensive integration scenarios executed against the real runtime environment without mocks.
+
+#### Scenario: Complex Graph Execution
+
+- **WHEN** a complex task graph (diamonds, sequences, parallel branches) is executed
+- **THEN** the system SHALL respect all dependency constraints and execution orders.
+- **AND** the final state MUST reflect the cumulative side effects of all successful tasks.
+
+#### Scenario: Failure Propagation
+
+- **WHEN** a task fails in a complex graph
+- **THEN** ONLY dependent tasks SHALL be skipped
+- **AND** independent branches SHALL continue to execute to completion.
+
+#### Scenario: Context Integrity
+
+- **WHEN** multiple tasks mutate the shared context
+- **THEN** state changes MUST be propagated correctly to downstream tasks.

package/openspec/changes/archive/2026-01-18-add-task-retry-policy/specs/task-runner/spec.md

@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Task Retry Configuration
+
+The `TaskStep` interface SHALL support an optional `retry` property of type `TaskRetryConfig`.
+
+#### Scenario: Retry Config Structure
+
+- **GIVEN** a `TaskRetryConfig` object
+- **THEN** it SHALL support:
+  - `attempts`: Number of retry attempts (default: 0).
+  - `delay`: Base delay in milliseconds (default: 0).
+  - `backoff`: Backoff strategy ('fixed' | 'exponential') (default: 'fixed').
+
+### Requirement: Retrying Execution Strategy
+
+The system SHALL provide a `RetryingExecutionStrategy` that implements `IExecutionStrategy` and wraps another `IExecutionStrategy`.
+
+#### Scenario: Successful execution
+
+- **WHEN** the inner strategy returns a successful `TaskResult`
+- **THEN** `RetryingExecutionStrategy` SHALL return that result immediately.
+
+#### Scenario: Retry on failure
+
+- **WHEN** the inner strategy throws or returns a failed `TaskResult`
+- **AND** the task has `retry.attempts > 0`
+- **THEN** it SHALL wait for the configured `delay`.
+- **AND** it SHALL re-execute the task using the inner strategy.
+- **AND** it SHALL decrement the remaining attempts.
+
+#### Scenario: Max attempts reached
+
+- **WHEN** the task fails and no attempts remain
+- **THEN** it SHALL return the failed result (or throw).
+
+#### Scenario: Exponential Backoff
+
+- **WHEN** `retry.backoff` is 'exponential'
+- **THEN** the delay SHALL increase for each attempt (e.g., `delay * 2^attempt`).

package/openspec/changes/archive/2026-01-18-add-workflow-preview/specs/task-runner/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: Dry Run Execution Strategy
+
+The system SHALL provide a `DryRunExecutionStrategy` that implements `IExecutionStrategy`.
+
+#### Scenario: Simulating execution
+
+- **WHEN** `WorkflowExecutor` is configured with `DryRunExecutionStrategy`
+- **AND** `execute` is called
+- **THEN** it SHALL traverse the dependency graph respecting order
+- **AND** it SHALL NOT execute the actual work of the `TaskStep`.
+- **AND** it SHALL return `TaskResult`s with a status indicating successful simulation (e.g., `simulated` or `success`).
+
+### Requirement: Mermaid Visualization
+
+The system SHALL provide a utility to generate a Mermaid.js graph from task steps.
+
+#### Scenario: Generate Mermaid Graph
+
+- **GIVEN** a list of `TaskStep`s with dependencies
+- **WHEN** `generateMermaidGraph` is called
+- **THEN** it SHALL return a valid Mermaid flowchart syntax string.
+- **AND** dependencies SHALL be represented as arrows (`-->`).
+- **AND** independent tasks SHALL appear as nodes.

package/openspec/changes/archive/2026-01-18-refactor-core-architecture/specs/task-runner/spec.md

@@ -0,0 +1,31 @@
+## MODIFIED Requirements
+
+### Requirement: TaskRunner Execution
+
+The `TaskRunner` SHALL execute a sequence of `TaskStep`s based on their dependencies, processing inputs and producing outputs.
+
+#### Scenario: Successful execution
+
+- **WHEN** all `TaskStep`s complete successfully
+- **THEN** the `TaskRunner` returns a successful workflow result.
+
+#### Scenario: Execution with AbortSignal
+
+- **WHEN** `TaskRunner.execute` is called with an `AbortSignal`
+- **THEN** the `TaskRunner` monitors the `AbortSignal` for cancellation requests.
+
+#### Scenario: Execution with Global Timeout
+
+- **WHEN** `TaskRunner.execute` is called with a `timeout` option
+- **THEN** the `TaskRunner` monitors the elapsed time for the workflow.
+
+## ADDED Requirements
+
+### Requirement: Modular Execution Architecture
+
+The system SHALL support pluggable execution strategies and decoupled state management.
+
+#### Scenario: Pluggable Strategy
+
+- **WHEN** configured with a custom execution strategy
+- **THEN** the `TaskRunner` SHALL delegate the execution logic to that strategy.

package/openspec/changes/archive/2026-01-22-adopt-release-pr/design.md

@@ -0,0 +1,40 @@
+# Design: Release PR Pattern
+
+## Context
+The current system uses `semantic-release` within a GitHub Actions workflow (`release.yml`). This workflow triggers on every push to `main`, executing an immediate release (version bump, changelog, git tag, npm publish, github release). This leads to high frequency "version explosion" in a trunk-based high-velocity environment.
+
+## Solution
+We will adopt the **Release PR Pattern** using **Release Please**.
+
+### Architecture
+- **Tool**: `googleapis/release-please-action`.
+- **Trigger**: Pushes to `main`.
+- **Mechanism**:
+    1.  **Analysis**: The action analyzes commits since the last tagged version.
+    2.  **PR Creation**: It creates (or updates) a special Pull Request containing:
+        -   The proposed next version numbers.
+        -   The generated CHANGELOG entry.
+    3.  **Release**:
+        -   When the Release PR is **merged**, the action runs again.
+        -   It detects the accidental merge of the release commit.
+        -   It creates the GitHub Release and Tags.
+        -   It outputs a `release_created` boolean.
+    4.  **Publish**:
+        -   A downstream step in the same workflow listens for `if: ${{ steps.release.outputs.release_created }}`.
+        -   If true, it executes the build and publish commands (e.g., `pnpm publish`).
+
+### Migration Strategy
+1.  **Cleanup**: Completely remove `semantic-release` configuration and workflow to prevent dual-release mechanisms or conflicts.
+2.  **Configuration**:
+    -   `release-please-config.json`: Defines the release type (`node`), packages (for monorepo support, though this is seemingly a single package config, using the root as the package is standard).
+    -   `.release-please-manifest.json`: Stores the current version (source of truth for Release Please). We will initialize it with the current version from `package.json`.
+3.  **Workflow**:
+    -   Replace `.github/workflows/release.yml` with `.github/workflows/release-please.yml`.
+
+### Key Differences
+| Feature       | Old (Semantic Release) | New (Release Please)                |
+| :------------ | :--------------------- | :---------------------------------- |
+| **Trigger**   | Every push to `main`   | Merge of Release PR                 |
+| **Changelog** | Generated on commit    | Previewed in PR, committed on merge |
+| **Version**   | Bumped on commit       | Bumped in PR, committed on merge    |
+| **Control**   | Automated              | Manual approval via Merge           |

package/openspec/changes/archive/2026-01-22-adopt-release-pr/proposal.md

@@ -0,0 +1,47 @@
+# Proposal: Adopt Release PR Pattern
+
+## Goal
+Switch from "continuous deployment on every commit" to the **Release PR Pattern** (Google Style) using [Release Please](https://github.com/google-github-actions/release-please-action).
+This ensures that releases are batched, version explosion is prevented, and human control is restored via PR merges, while maintaining automation.
+
+## User Review Required
+> [!IMPORTANT]
+> This is a breaking change to the release process.
+> - **Current Behavior**: Every commit to `main` triggers a release/publish.
+> - **New Behavior**: Commits to `main` update a "Release PR". A release only happens when you **merge** that PR.
+
+## Proposed Changes
+
+### Configuration
+#### [DELETE] [.releaserc.json](file:///home/thales/projects/task-runner/.releaserc.json)
+- Remove Semantic Release configuration.
+
+#### [NEW] [release-please-config.json](file:///home/thales/projects/task-runner/release-please-config.json)
+- Configuration for Release Please (monorepo-friendly structure, standard conventional commits).
+
+#### [NEW] [.release-please-manifest.json](file:///home/thales/projects/task-runner/.release-please-manifest.json)
+- Tracks versions (required for Release Please).
+
+### Infra / CI
+#### [DELETE] [.github/workflows/release.yml](file:///home/thales/projects/task-runner/.github/workflows/release.yml)
+- Remove successful `semantic-release` workflow.
+
+#### [NEW] [.github/workflows/release-please.yml](file:///home/thales/projects/task-runner/.github/workflows/release-please.yml)
+- New GitHub Action workflow that:
+    1. Runs `release-please` to update the PR.
+    2. If a release is created (PR merged), runs build/publish steps.
+
+## Verification Plan
+
+### Automated Tests
+- **Dry Run**: We cannot easily "test" the GitHub Action without merging, but we can verify the configuration files are valid JSON.
+- **Lint**: Ensure new workflow file syntax is valid (tools like `action-validator` if available, otherwise manual review).
+
+### Manual Verification
+- **Post-Merge**:
+    1. Push a `fix: test` commit to `main`.
+    2. Verify `release-please` bot creates a PR "chore: release 1.0.1".
+    3. Push another `feat: cool` commit.
+    4. Verify PR updates to includes the feature.
+    5. Merge the PR.
+    6. Verify GitHub Release created and NPM publish (if configured).

package/openspec/changes/archive/2026-01-22-adopt-release-pr/specs/release-pr/spec.md

@@ -0,0 +1,34 @@
+# Spec: Release PR Pattern
+
+## ADDED Requirements
+
+### Requirement: Release PR Generation
+The system MUST automatically maintain a "Release PR" that targets the `main` branch. This PR must accumulate all conventional changes since the last release, calculating the next semantic version and generating a corresponding changelog entry.
+
+#### Scenario: Feature commit triggers PR update
+Given the latest release is `v1.0.0`
+And a developer merges a commit with message `feat: add awesome feature` to `main`
+Then the system should create or update the Release PR
+And the PR title should be `chore: release 1.1.0`
+And the PR body should contain the changelog entry for "add awesome feature"
+And the `package.json` version in the PR should be `1.1.0`
+
+#### Scenario: Fix commit triggers patch update
+Given the latest release is `v1.0.0`
+And a developer merges a commit `fix: urgent bug` to `main`
+Then the Release PR should be updated to target version `1.0.1`
+
+### Requirement: Release Publication
+The system MUST execute the release process (git tag, GitHub Release, npm publish) ONLY when the Release PR is merged into `main`.
+
+#### Scenario: Merge triggers publish
+Given the Release PR for `v1.1.0` exists
+When a maintainer merges the PR into `main`
+Then the system should create a GitHub Release `v1.1.0`
+And the system should publish the package to the configured registry (NPM)
+And the system should NOT publish any other commits merged to `main` until the next Release PR merge
+
+## REMOVED Requirements
+
+### Requirement: Immediate Release
+The system MUST NOT trigger a release or publish artifacts on every commit to `main`, unless that commit is the merge of a Release PR.

package/openspec/changes/archive/2026-01-22-adopt-release-pr/tasks.md

@@ -0,0 +1,14 @@
+- [x] Remove Semantic Release configuration <!-- id: 0 -->
+    - Delete `.releaserc.json`
+    - Remove `release.yml`
+    - Uninstall `semantic-release` and its plugins
+- [x] Initialize Release Please configuration <!-- id: 1 -->
+    - Create `release-please-config.json` (root package type: node)
+    - Create `.release-please-manifest.json` (synced with current package.json version)
+- [x] Create Release Workflow <!-- id: 2 -->
+    - Create `.github/workflows/release-please.yml`
+    - Step 1: `googleapis/release-please-action`
+    - Step 2: `pnpm publish` (conditional on release creation)
+- [x] Verification <!-- id: 3 -->
+    - Validate CI YAML syntax
+    - Verify JSON config validity

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/specs/001-generic-task-runner/spec.md

@@ -0,0 +1,13 @@
+## ADDED Requirements
+
+### Requirement: Task Execution Metrics
+
+The system SHALL record timing metrics for each executed task, including start time, end time, and duration.
+
+#### Scenario: Successful execution
+- **WHEN** a task completes successfully
+- **THEN** the task result contains the start timestamp, end timestamp, and duration in milliseconds
+
+#### Scenario: Failed execution
+- **WHEN** a task fails
+- **THEN** the task result contains the start timestamp, end timestamp, and duration in milliseconds

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/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.

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

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Conditional Retries
+
+The system SHALL support conditional retries where a user-defined predicate determines if a task failure warrants a retry attempt.
+
+#### Scenario: Retry allowed by predicate
+- **GIVEN** a task configured with retries and a `shouldRetry` predicate
+- **WHEN** the task fails with an error
+- **AND** the `shouldRetry` predicate returns `true` for that error
+- **THEN** the system SHALL proceed with the retry logic (respecting attempt limits and delays).
+
+#### Scenario: Retry denied by predicate
+- **GIVEN** a task configured with retries and a `shouldRetry` predicate
+- **WHEN** the task fails with an error
+- **AND** the `shouldRetry` predicate returns `false` for that error
+- **THEN** the system SHALL NOT retry the task.
+- **AND** the task status SHALL be immediately marked as 'failure'.
+
+#### Scenario: Default retry behavior
+- **GIVEN** a task configured with retries but NO `shouldRetry` predicate
+- **WHEN** the task fails with an error
+- **THEN** the system SHALL retry the task (respecting attempt limits and delays), preserving backward compatibility.

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

@@ -0,0 +1,37 @@
+# Engineering Tasks
+
+- [ ] **Task 1: Update TaskRetryConfig Interface**
+  - Modify `src/contracts/TaskRetryConfig.ts`.
+  - Add `shouldRetry?: (error: unknown) => boolean;` to the `TaskRetryConfig` interface.
+  - Document the property with JSDoc explaining its purpose (return true to retry, false to abort).
+
+- [ ] **Task 2: Update RetryingExecutionStrategy Logic**
+  - Modify `src/strategies/RetryingExecutionStrategy.ts`.
+  - Inside the `execute` loop, after receiving a "failure" result:
+    - Check if `config.shouldRetry` is defined.
+    - If defined, call it with `result.error`.
+    - If it returns `false`, break the loop and return the failure result immediately.
+    - If it returns `true` (or is undefined), proceed with the existing retry logic (check attempts, delay).
+
+- [ ] **Task 3: Unit Tests**
+  - Create `tests/strategies/RetryingExecutionStrategy.conditional.test.ts` (or add to existing test file if small).
+  - **Scenario 1**: `shouldRetry` returns `true`.
+    - Setup a task that fails 2 times then succeeds.
+    - Configure `shouldRetry: () => true`.
+    - Verify it retries and eventually succeeds.
+  - **Scenario 2**: `shouldRetry` returns `false`.
+    - Setup a task that fails with a specific error "FatalError".
+    - Configure `shouldRetry: (err) => err !== "FatalError"`.
+    - Verify it does *not* retry and returns failure immediately after the first attempt.
+  - **Scenario 3**: `shouldRetry` is undefined (Legacy behavior).
+    - Setup a failing task.
+    - Verify it retries up to max attempts.
+
+- [ ] **Task 4: Integration Test**
+  - Create `tests/integration-tests/conditional-retries.test.ts`.
+  - Define a workflow with two tasks:
+    - Task A: Fails with "Transient" error (retries allowed).
+    - Task B: Fails with "Permanent" error (retries blocked by predicate).
+  - Execute workflow.
+  - Verify Task A consumed its retries (or succeeded).
+  - Verify Task B failed immediately (did not consume retries).

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

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Per-Task Timeout
+
+The `TaskStep` interface SHALL support an optional `timeout` property, and the `StandardExecutionStrategy` SHALL enforce this timeout.
+
+#### Scenario: Task completes within timeout
+
+- **GIVEN** a task with `timeout: 100` (ms)
+- **WHEN** the task execution takes 50ms
+- **THEN** the task SHALL complete successfully.
+- **AND** the timeout timer SHALL be cleared immediately.
+
+#### Scenario: Task exceeds timeout
+
+- **GIVEN** a task with `timeout: 100` (ms)
+- **WHEN** the task execution attempts to run longer than 100ms
+- **THEN** the task execution SHALL be aborted with an error indicating a timeout.
+- **AND** the `TaskResult` status SHALL be 'failure' (or 'cancelled' if appropriate, but typically 'failure' due to timeout error).
+- **AND** the `AbortSignal` passed to the task's `run` method SHALL be triggered.
+
+#### Scenario: Global cancellation overrides task timeout
+
+- **GIVEN** a task with `timeout: 5000` (ms)
+- **WHEN** the workflow's global `AbortSignal` is triggered at 100ms
+- **THEN** the task SHALL receive the abort signal immediately (at 100ms).
+- **AND** the task SHALL NOT wait for the 5000ms timeout.
+- **AND** the `TaskResult` status SHALL be 'cancelled'.
+
+#### Scenario: Task without timeout
+
+- **GIVEN** a task without a `timeout` property
+- **WHEN** it executes
+- **THEN** it SHALL NOT be subject to any local timeout constraints (only global workflow timeout).

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

@@ -0,0 +1,47 @@
+# Workflow State Persistence Specification
+
+## Purpose
+
+Enables the `TaskRunner` to save its execution state and resume from that state later, allowing for recovery from failures or pausing long-running workflows without re-executing completed tasks.
+
+## Requirements
+
+### Requirement: State Snapshot Exposure
+
+The system SHALL provide a mechanism to retrieve the current execution state of a workflow.
+
+#### Scenario: Retrieving state from TaskRunner 
+- **WHEN** a workflow is running or completed
+- **THEN** the `TaskRunner` (or its underlying `TaskStateManager`) SHALL expose a method to retrieve a snapshot of the current state.
+- **AND** the snapshot SHALL contain the `results` of all executed tasks.
+- **AND** the snapshot SHALL be serializable (e.g., to JSON).
+
+### Requirement: Hydrated Initialization
+
+The system SHALL allow initializing a `TaskRunner` with a pre-existing state snapshot.
+
+#### Scenario: Initializing with a snapshot
+- **GIVEN** a valid state snapshot from a previous execution
+- **WHEN** the `TaskRunner` is built using `TaskRunnerBuilder`
+- **THEN** the builder SHALL accept the snapshot as an initial state.
+- **AND** the `TaskRunner` SHALL start with the internal state reflecting the snapshot (i.e., known task results).
+
+### Requirement: Resumable Execution Logic
+
+The `WorkflowExecutor` SHALL respect the initial hydrated state during execution, skipping already completed tasks.
+
+#### Scenario: Skipping successful tasks
+- **GIVEN** a `TaskRunner` initialized with a snapshot where Task A is marked as `success`
+- **WHEN** `execute()` is called
+- **THEN** Task A SHALL NOT be executed again.
+- **AND** Task A SHALL be considered completed for the purpose of checking dependencies of downstream tasks.
+
+#### Scenario: Re-running non-successful tasks
+- **GIVEN** a `TaskRunner` initialized with a snapshot where Task B is marked as `failure`, `cancelled`, or `skipped`
+- **WHEN** `execute()` is called
+- **THEN** Task B SHOULD be evaluated for execution (subject to dependency checks).
+
+#### Scenario: Handling Context
+- **GIVEN** a resumed workflow
+- **THEN** it is the caller's responsibility to provide the necessary `Context` for task execution.
+- **AND** the `TaskRunner` SHALL NOT attempt to automatically restore the context object from the state snapshot (as it may contain non-serializable data).

package/openspec/specs/release-pr/spec.md

@@ -0,0 +1,31 @@
+# release-pr Specification
+
+## Purpose
+TBD - created by archiving change adopt-release-pr. Update Purpose after archive.
+## Requirements
+### Requirement: Release PR Generation
+The system MUST automatically maintain a "Release PR" that targets the `main` branch. This PR must accumulate all conventional changes since the last release, calculating the next semantic version and generating a corresponding changelog entry.
+
+#### Scenario: Feature commit triggers PR update
+Given the latest release is `v1.0.0`
+And a developer merges a commit with message `feat: add awesome feature` to `main`
+Then the system should create or update the Release PR
+And the PR title should be `chore: release 1.1.0`
+And the PR body should contain the changelog entry for "add awesome feature"
+And the `package.json` version in the PR should be `1.1.0`
+
+#### Scenario: Fix commit triggers patch update
+Given the latest release is `v1.0.0`
+And a developer merges a commit `fix: urgent bug` to `main`
+Then the Release PR should be updated to target version `1.0.1`
+
+### Requirement: Release Publication
+The system MUST execute the release process (git tag, GitHub Release, npm publish) ONLY when the Release PR is merged into `main`.
+
+#### Scenario: Merge triggers publish
+Given the Release PR for `v1.1.0` exists
+When a maintainer merges the PR into `main`
+Then the system should create a GitHub Release `v1.1.0`
+And the system should publish the package to the configured registry (NPM)
+And the system should NOT publish any other commits merged to `main` until the next Release PR merge
+