@calmo/task-runner 3.3.0 → 3.4.1

package/openspec/AGENTS.md

@@ -15,14 +15,17 @@ Instructions for AI coding assistants using OpenSpec for spec-driven development
 ## Three-Stage Workflow
 
 ### Stage 1: Creating Changes
+
 Create proposal when you need to:
+
 - Add features or functionality
 - Make breaking changes (API, schema)
-- Change architecture or patterns  
+- Change architecture or patterns
 - Optimize performance (changes behavior)
 - Update security patterns
 
 Triggers (examples):
+
 - "Help me create a change proposal"
 - "Help me plan a change"
 - "Help me create a proposal"
@@ -30,10 +33,12 @@ Triggers (examples):
 - "I want to create a spec"
 
 Loose matching guidance:
+
 - Contains one of: `proposal`, `change`, `spec`
 - With one of: `create`, `plan`, `make`, `start`, `help`
 
 Skip proposal for:
+
 - Bug fixes (restore intended behavior)
 - Typos, formatting, comments
 - Dependency updates (non-breaking)
@@ -41,13 +46,16 @@ Skip proposal for:
 - Tests for existing behavior
 
 **Workflow**
+
 1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
 2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
 3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
 4. Run `openspec validate <id> --strict --no-interactive` and resolve any issues before sharing the proposal.
 
 ### Stage 2: Implementing Changes
+
 Track these steps as TODOs and complete them one by one.
+
 1. **Read proposal.md** - Understand what's being built
 2. **Read design.md** (if exists) - Review technical decisions
 3. **Read tasks.md** - Get implementation checklist
@@ -57,7 +65,9 @@ Track these steps as TODOs and complete them one by one.
 7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
 
 ### Stage 3: Archiving Changes
+
 After deployment, create separate PR to:
+
 - Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
 - Update `specs/` if capabilities changed
 - Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
@@ -66,6 +76,7 @@ After deployment, create separate PR to:
 ## Before Any Task
 
 **Context Checklist:**
+
 - [ ] Read relevant specs in `specs/[capability]/spec.md`
 - [ ] Check pending changes in `changes/` for conflicts
 - [ ] Read `openspec/project.md` for conventions
@@ -73,12 +84,14 @@ After deployment, create separate PR to:
 - [ ] Run `openspec list --specs` to see existing capabilities
 
 **Before Creating Specs:**
+
 - Always check if capability already exists
 - Prefer modifying existing specs over creating duplicates
 - Use `openspec show [spec]` to review current state
 - If request is ambiguous, ask 1–2 clarifying questions before scaffolding
 
 ### Search Guidance
+
 - Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
 - Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
 - Show details:
@@ -147,7 +160,7 @@ openspec/
 ```
 New request?
 ├─ Bug fix restoring spec behavior? → Fix directly
-├─ Typo/format/comment? → Fix directly  
+├─ Typo/format/comment? → Fix directly
 ├─ New feature/capability? → Create proposal
 ├─ Breaking change? → Create proposal
 ├─ Architecture change? → Create proposal
@@ -159,45 +172,60 @@ New request?
 1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
 
 2. **Write proposal.md:**
+
 ```markdown
 # Change: [Brief description of change]
 
 ## Why
+
 [1-2 sentences on problem/opportunity]
 
 ## What Changes
+
 - [Bullet list of changes]
 - [Mark breaking changes with **BREAKING**]
 
 ## Impact
+
 - Affected specs: [list capabilities]
 - Affected code: [key files/systems]
 ```
 
 3. **Create spec deltas:** `specs/[capability]/spec.md`
+
 ```markdown
 ## ADDED Requirements
+
 ### Requirement: New Feature
+
 The system SHALL provide...
 
 #### Scenario: Success case
+
 - **WHEN** user performs action
 - **THEN** expected result
 
 ## MODIFIED Requirements
+
 ### Requirement: Existing Feature
+
 [Complete modified requirement]
 
 ## REMOVED Requirements
+
 ### Requirement: Old Feature
+
 **Reason**: [Why removing]
 **Migration**: [How to handle]
 ```
+
 If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
 
 4. **Create tasks.md:**
+
 ```markdown
 ## 1. Implementation
+
 - [ ] 1.1 Create database schema
 - [ ] 1.2 Implement API endpoint
 - [ ] 1.3 Add frontend component
@@ -205,32 +233,40 @@ If multiple capabilities are affected, create multiple delta files under `change
 ```
 
 5. **Create design.md when needed:**
-Create `design.md` if any of the following apply; otherwise omit it:
+   Create `design.md` if any of the following apply; otherwise omit it:
+
 - Cross-cutting change (multiple services/modules) or a new architectural pattern
 - New external dependency or significant data model changes
 - Security, performance, or migration complexity
 - Ambiguity that benefits from technical decisions before coding
 
 Minimal `design.md` skeleton:
+
 ```markdown
 ## Context
+
 [Background, constraints, stakeholders]
 
 ## Goals / Non-Goals
+
 - Goals: [...]
 - Non-Goals: [...]
 
 ## Decisions
+
 - Decision: [What and why]
 - Alternatives considered: [Options + rationale]
 
 ## Risks / Trade-offs
+
 - [Risk] → Mitigation
 
 ## Migration Plan
+
 [Steps, rollback]
 
 ## Open Questions
+
 - [...]
 ```
 
@@ -239,22 +275,27 @@ Minimal `design.md` skeleton:
 ### Critical: Scenario Formatting
 
 **CORRECT** (use #### headers):
+
 ```markdown
 #### Scenario: User login success
+
 - **WHEN** valid credentials provided
 - **THEN** return JWT token
 ```
 
 **WRONG** (don't use bullets or bold):
+
 ```markdown
-- **Scenario: User login**  ❌
-**Scenario**: User login     ❌
-### Scenario: User login      ❌
+- **Scenario: User login** ❌
+  **Scenario**: User login ❌
+
+### Scenario: User login ❌
 ```
 
 Every requirement MUST have at least one scenario.
 
 ### Requirement Wording
+
 - Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
 
 ### Delta Operations
@@ -267,6 +308,7 @@ Every requirement MUST have at least one scenario.
 Headers matched with `trim(header)` - whitespace ignored.
 
 #### When to use ADDED vs MODIFIED
+
 - ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
 - MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
 - RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
@@ -274,14 +316,17 @@ Headers matched with `trim(header)` - whitespace ignored.
 Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
 
 Authoring a MODIFIED requirement correctly:
-1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
-2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
-3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
-4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
+
+1. Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
+2. Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
+3. Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
+4. Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
 
 Example for RENAMED:
+
 ```markdown
 ## RENAMED Requirements
+
 - FROM: `### Requirement: Login`
 - TO: `### Requirement: User Authentication`
 ```
@@ -291,14 +336,17 @@ Example for RENAMED:
 ### Common Errors
 
 **"Change must have at least one delta"**
+
 - Check `changes/[name]/specs/` exists with .md files
 - Verify files have operation prefixes (## ADDED Requirements)
 
 **"Requirement must have at least one scenario"**
+
 - Check scenarios use `#### Scenario:` format (4 hashtags)
 - Don't use bullet points or bold for scenario headers
 
 **Silent scenario parsing failures**
+
 - Exact format required: `#### Scenario: Name`
 - Debug with: `openspec show [change] --json --deltas-only`
 
@@ -360,73 +408,88 @@ openspec/changes/add-2fa-notify/
 ```
 
 auth/spec.md
+
 ```markdown
 ## ADDED Requirements
+
 ### Requirement: Two-Factor Authentication
+
 ...
 ```
 
 notifications/spec.md
+
 ```markdown
 ## ADDED Requirements
+
 ### Requirement: OTP Email Notification
+
 ...
 ```
 
 ## Best Practices
 
 ### Simplicity First
+
 - Default to <100 lines of new code
 - Single-file implementations until proven insufficient
 - Avoid frameworks without clear justification
 - Choose boring, proven patterns
 
 ### Complexity Triggers
+
 Only add complexity with:
+
 - Performance data showing current solution too slow
 - Concrete scale requirements (>1000 users, >100MB data)
 - Multiple proven use cases requiring abstraction
 
 ### Clear References
+
 - Use `file.ts:42` format for code locations
 - Reference specs as `specs/auth/spec.md`
 - Link related changes and PRs
 
 ### Capability Naming
+
 - Use verb-noun: `user-auth`, `payment-capture`
 - Single purpose per capability
 - 10-minute understandability rule
 - Split if description needs "AND"
 
 ### Change ID Naming
+
 - Use kebab-case, short and descriptive: `add-two-factor-auth`
 - Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
 - Ensure uniqueness; if taken, append `-2`, `-3`, etc.
 
 ## Tool Selection Guide
 
-| Task | Tool | Why |
-|------|------|-----|
-| Find files by pattern | Glob | Fast pattern matching |
-| Search code content | Grep | Optimized regex search |
-| Read specific files | Read | Direct file access |
+| Task                  | Tool | Why                      |
+| --------------------- | ---- | ------------------------ |
+| Find files by pattern | Glob | Fast pattern matching    |
+| Search code content   | Grep | Optimized regex search   |
+| Read specific files   | Read | Direct file access       |
 | Explore unknown scope | Task | Multi-step investigation |
 
 ## Error Recovery
 
 ### Change Conflicts
+
 1. Run `openspec list` to see active changes
 2. Check for overlapping specs
 3. Coordinate with change owners
 4. Consider combining proposals
 
 ### Validation Failures
+
 1. Run with `--strict` flag
 2. Check JSON output for details
 3. Verify spec file format
 4. Ensure scenarios properly formatted
 
 ### Missing Context
+
 1. Read project.md first
 2. Check related specs
 3. Review recent archives
@@ -435,17 +498,20 @@ Only add complexity with:
 ## Quick Reference
 
 ### Stage Indicators
+
 - `changes/` - Proposed, not yet built
 - `specs/` - Built and deployed
 - `archive/` - Completed changes
 
 ### File Purposes
+
 - `proposal.md` - Why and what
 - `tasks.md` - Implementation steps
 - `design.md` - Technical decisions
 - `spec.md` - Requirements and behavior
 
 ### CLI Essentials
+
 ```bash
 openspec list              # What's in progress?
 openspec show [item]       # View details

package/openspec/changes/{add-concurrency-control → archive/2026-01-18-add-concurrency-control}/proposal.md

@@ -1,14 +1,17 @@
 # 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.
+
+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 `concurrency: number` optional property to `WorkflowExecutor`.
 - Modify `WorkflowExecutor.processLoop` to respect the concurrency limit.
-    - Track the active promise count.
-    - Only start new tasks from the ready queue if `active < concurrency`.
-    - Continue to defer ready tasks until slots open up.
+  - Track the active promise count.
+  - Only start new tasks from the ready queue if `active < concurrency`.
+  - Continue to defer ready tasks until slots open up.
 
 ## Impact
+
 - **Affected Components**: `WorkflowExecutor`

package/openspec/changes/archive/2026-01-18-add-concurrency-control/tasks.md

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

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

@@ -1,14 +1,17 @@
 # Change: Add External Task Cancellation
 
 ## Why
+
 Once `TaskRunner.execute()` is called, there is no way to cancel the operation externally. If a task hangs or if the user wants to abort the workflow (e.g., in a CLI or UI context), the runner continues until completion or failure. This limits the responsiveness and control users have over long-running operations.
 
 ## What Changes
+
 - The `TaskRunner.execute()` method will be updated to accept an optional configuration object.
 - This configuration object will support an `AbortSignal` for external cancellation.
 - The configuration object will also support a global timeout for the entire workflow.
 - Tasks will be able to respond to cancellation signals and report their status accordingly.
 
 ## Impact
+
 - Affected specs: `001-generic-task-runner` (specifically the `TaskRunner`'s `execute` method behavior)
-- Affected code: `src/TaskRunner.ts`, `src/contracts/RunnerEvents.ts` (for cancellation events), potentially `src/TaskStep.ts` (to propagate `AbortSignal` to individual steps).
+- Affected code: `src/TaskRunner.ts`, `src/contracts/RunnerEvents.ts` (for cancellation events), potentially `src/TaskStep.ts` (to propagate `AbortSignal` to individual steps).

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

@@ -1,4 +1,5 @@
 ## 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`.
@@ -7,4 +8,4 @@
 - [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.
+- [x] 1.9 Add integration tests covering both `AbortSignal` and timeout interactions.

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

@@ -1,9 +1,11 @@
 # 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.
@@ -14,5 +16,6 @@ The current test suite relies heavily on unit tests and mocks. To ensure robust
   - 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

@@ -1,4 +1,5 @@
 ## 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.

package/openspec/changes/archive/2026-01-18-add-task-retry-policy/proposal.md

@@ -1,9 +1,11 @@
 # 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
+
 - Add `TaskRetryConfig` interface to define retry behavior (attempts, delay, backoff).
 - Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
 - Implement `RetryingExecutionStrategy` which decorates any `IExecutionStrategy`.
@@ -12,5 +14,6 @@ Tasks currently run once and fail immediately if they throw an error or return a
   - It waits and re-executes the step if applicable.
 
 ## Impact
+
 - **New Components**: `RetryingExecutionStrategy`, `TaskRetryConfig`
 - **Affected Components**: `TaskStep` (interface update)

package/openspec/changes/archive/2026-01-18-add-task-retry-policy/tasks.md

@@ -1,4 +1,5 @@
 ## Implementation
+
 - [x] 1.1 Create `TaskRetryConfig` interface with `attempts`, `delay`, and `backoff`.
 - [x] 1.2 Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
 - [x] 1.3 Update execution logic to catch task failures.

package/openspec/changes/archive/2026-01-18-add-workflow-preview/proposal.md

@@ -1,13 +1,16 @@
 # 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 `DryRunExecutionStrategy` which implements `IExecutionStrategy`. This allows `WorkflowExecutor` to simulate execution without side effects.
 - Add a standalone utility `generateMermaidGraph(steps: TaskStep[])` to generate a Mermaid.js diagram of the dependency graph.
 - Expose these features via the main `TaskRunner` facade if applicable, or as separate utilities.
 
 ## Impact
+
 - **New Components**: `DryRunExecutionStrategy`, `generateMermaidGraph`
 - **Affected Components**: `WorkflowExecutor` (indirectly, via strategy injection)

package/openspec/changes/archive/2026-01-18-add-workflow-preview/tasks.md

@@ -1,4 +1,5 @@
 ## Implementation
+
 - [x] 1.1 Update `TaskRunnerExecutionConfig` to include an optional `dryRun: boolean` property.
 - [x] 1.2 Implement `dryRun` logic in `WorkflowExecutor` (traverse graph, validate order, skip `step.run()`, return `skipped` or `success` pseudo-status).
 - [x] 1.3 Implement `getMermaidGraph(steps: TaskStep[])` method (can be static or instance method on `TaskRunner`).

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

@@ -1,14 +1,17 @@
 # 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.

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

@@ -1,4 +1,5 @@
 ## Implementation
+
 - [x] 1.1 Extract `TaskStateManager` to handle `TaskResult` storage, updates, and context mutations.
 - [x] 1.2 Define `IExecutionStrategy` interface for running tasks (Strategy Pattern).
 - [x] 1.3 Refactor `WorkflowExecutor` to use `TaskStateManager` and `IExecutionStrategy`.

package/openspec/changes/feat-per-task-timeout/proposal.md

@@ -1,25 +1,30 @@
 # Feature: Per-Task Timeout
 
 ## 🎯 User Story
+
 "As a developer, I want to define a maximum execution time for specific tasks so that a single hung task (e.g., a stalled network request) fails fast without blocking the rest of the independent tasks or waiting for the global workflow timeout."
 
 ## ❓ Why
+
 Currently, the `TaskRunner` allows a **global** timeout for the entire `execute()` call. However, this is insufficient for granular control:
+
 1.  **Varying Latency**: Some tasks are expected to be fast (local validation), others slow (data fetching). A global timeout of 30s is too loose for the fast ones.
 2.  **Boilerplate**: Developers currently have to manually implement `setTimeout`, `Promise.race`, and `AbortController` logic inside every `run()` method to handle timeouts properly.
 3.  **Resilience**: A single "zombie" task can hold up the entire pipeline until the global timeout kills everything. Per-task timeouts allow failing that specific task (and skipping its dependents) while letting other independent tasks continue.
 
 ## 🛠️ What Changes
+
 1.  **Interface Update**: Update `TaskStep<T>` to accept an optional `timeout` property (in milliseconds).
 2.  **Execution Strategy**: Update `StandardExecutionStrategy` to:
-    -   Create a local timeout timer for the task.
-    -   Create a combined `AbortSignal` (merging the workflow's signal and the local timeout).
-    -   Race the task execution against the timer.
-    -   Return a specific failure result if the timeout wins.
+    - Create a local timeout timer for the task.
+    - Create a combined `AbortSignal` (merging the workflow's signal and the local timeout).
+    - Race the task execution against the timer.
+    - Return a specific failure result if the timeout wins.
 
 ## ✅ Acceptance Criteria
+
 - [ ] A task with `timeout: 100` must fail if the `run` method takes > 100ms.
 - [ ] The error message for a timed-out task should clearly state "Task timed out after 100ms".
 - [ ] The `AbortSignal` passed to the task's `run` method must be triggered when the timeout occurs.
-- [ ] If the Global Workflow is cancelled *before* the task times out, the task should receive the cancellation signal immediately.
-- [ ] A task completing *before* the timeout should clear the timer to prevent open handles.
+- [ ] If the Global Workflow is cancelled _before_ the task times out, the task should receive the cancellation signal immediately.
+- [ ] A task completing _before_ the timeout should clear the timer to prevent open handles.

package/openspec/changes/feat-per-task-timeout/tasks.md

@@ -11,7 +11,7 @@
     - If yes, create an `AbortController`.
     - Set a `setTimeout` to trigger the controller.
     - Use `Promise.race` (or simply pass the new signal and wait) to handle the timeout.
-    - **Crucial**: Ensure the new signal respects the *parent* `signal` (if global cancel happens, local signal must also abort).
+    - **Crucial**: Ensure the new signal respects the _parent_ `signal` (if global cancel happens, local signal must also abort).
     - **Crucial**: Clean up the timer (`clearTimeout`) in a `finally` block.
 
 - [ ] **Task 3: Unit Tests**

package/openspec/project.md

@@ -1,32 +1,38 @@
 # Project: Task Runner
 
 ## Overview
+
 The 'task-runner' project is a TypeScript-based utility designed to manage and execute tasks. It incorporates features such as task cancellation, pre-execution validation, and concurrency control, providing a robust framework for workflow automation.
 
 ## Tech Stack
+
 - **Languages:** TypeScript 5.9.3
 - **Testing:** Vitest 4.0.17
 - **Core APIs:** AbortSignal/AbortController (Standard Web APIs for cancellation)
 - **Package Manager:** pnpm
 
 ## Architecture
+
 The project follows a modular architecture with distinct components for managing different aspects of task execution:
--   `EventBus.ts`: Handles event propagation within the system.
--   `TaskGraph.ts`: Represents the structure and dependencies of tasks.
--   `TaskGraphValidator.ts`: Ensures the validity of task graphs before execution.
--   `TaskRunner.ts`: Orchestrates the execution of tasks.
--   `WorkflowExecutor.ts`: Manages the overall workflow.
--   `contracts/`: Defines interfaces and types for various components, promoting loose coupling and clear API boundaries.
+
+- `EventBus.ts`: Handles event propagation within the system.
+- `TaskGraph.ts`: Represents the structure and dependencies of tasks.
+- `TaskGraphValidator.ts`: Ensures the validity of task graphs before execution.
+- `TaskRunner.ts`: Orchestrates the execution of tasks.
+- `WorkflowExecutor.ts`: Manages the overall workflow.
+- `contracts/`: Defines interfaces and types for various components, promoting loose coupling and clear API boundaries.
 
 ## Conventions
--   **Coding Style:** Adheres to standard TypeScript conventions, enforced by ESLint and Prettier.
--   **Commit Messages:** Follows conventional commits enforced by Commitlint.
--   **Git Hooks:** Utilizes Husky for pre-commit and commit-msg hooks.
--   **Testing:** Uses Vitest for unit and integration testing.
--   **Atomic Commits:** When working on complex multi-task features, commit after each distinct task, ensuring build, lint, and test success to establish safe rollback points.
+
+- **Coding Style:** Adheres to standard TypeScript conventions, enforced by ESLint and Prettier.
+- **Commit Messages:** Follows conventional commits enforced by Commitlint.
+- **Git Hooks:** Utilizes Husky for pre-commit and commit-msg hooks.
+- **Testing:** Uses Vitest for unit and integration testing.
+- **Atomic Commits:** When working on complex multi-task features, commit after each distinct task, ensuring build, lint, and test success to establish safe rollback points.
 
 ## Build/Test/Run Commands
--   **Install Dependencies:** `pnpm install`
--   **Build Project:** `pnpm build`
--   **Run Tests:** `pnpm test`
--   **Lint Code:** `pnpm lint`
+
+- **Install Dependencies:** `pnpm install`
+- **Build Project:** `pnpm build`
+- **Run Tests:** `pnpm test`
+- **Lint Code:** `pnpm lint`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "",
   "repository": {
     "type": "git",