@calmo/task-runner 3.4.0 → 3.5.0

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

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

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-feat-conditional-execution/proposal.md

@@ -0,0 +1,35 @@
+# Feature: Conditional Task Execution
+
+## 🎯 User Story
+
+"As a developer, I want to define a condition for a task so that it only executes when specific criteria are met (e.g., only on CI, or only if a previous task generated a specific output), avoiding unnecessary execution and manual checks inside the task logic."
+
+## ❓ Why
+
+Currently, to skip a task based on context, a developer must implement the check inside the `run` method and return `{ status: 'skipped' }`. This has downsides:
+
+1.  **Late Binding**: The task is already "started" (event emitted) before it decides to skip itself.
+2.  **Boilerplate**: Every task needs `if (!shouldRun) return { status: 'skipped' }`.
+3.  **Clarity**: Examining the task definition (e.g. `TaskStep` object) doesn't reveal *when* it runs, only *what* it does. A declarative `condition` property makes the workflow logic more transparent.
+4.  **Dry Run Accuracy**: In a dry run, we might want to know if a task *would* run. If the logic is inside `run`, strictly disjoint from the runner, a dry run (which skips `run`) cannot predict if the task would be skipped.
+
+## 🛠️ What Changes
+
+1.  **Interface Update**: Update `TaskStep<T>` to accept an optional `condition` property:
+    ```typescript
+    condition?: (context: T) => boolean | Promise<boolean>;
+    ```
+2.  **State Manager/Workflow Executor Update**:
+    - Before marking a task as `running`, evaluate `condition(context)`.
+    - If `false`, mark the task as `skipped` immediately without calling `run()`.
+    - Emit `taskSkipped` event.
+    - Consistency: Ensure that skipping a task triggers the standard skip propagation for dependent tasks (as currently documented in README).
+
+## ✅ Acceptance Criteria
+
+- [ ] A task with `condition: () => false` must result in a `skipped` status.
+- [ ] The `run` method of a conditionally skipped task must **not** be called.
+- [ ] A task with `condition: () => true` (or undefined) must execute normally.
+- [ ] The `condition` function receives the current `context`.
+- [ ] Async `condition` functions are awaited.
+- [ ] `taskSkipped` event is emitted when condition fails.

package/openspec/changes/archive/2026-01-18-feat-conditional-execution/tasks.md

@@ -0,0 +1,32 @@
+# Engineering Tasks
+
+- [ ] **Task 1: Update Interface**
+  - Modify `src/TaskStep.ts` to add `condition?: (context: T) => boolean | Promise<boolean>;` to the `TaskStep` interface.
+  - Add JSDoc to explain that if condition returns false, the task is skipped.
+
+- [ ] **Task 2: Implement Conditional Logic in TaskStateManager**
+  - Analyze `src/TaskStateManager.ts` and `src/WorkflowExecutor.ts`.
+  - Determine the best place to evaluate the condition. Likely in `WorkflowExecutor` before calling `strategy.execute`, OR in `TaskStateManager` when processing dependencies?
+  - Actually, `WorkflowExecutor.processLoop` calls `stateManager.markRunning(step)`.
+  - It should probably be:
+    ```typescript
+    const shouldRun = await evaluateCondition(step, context);
+    if (!shouldRun) {
+        stateManager.markResult(step, { status: 'skipped' });
+        // emit skipped event
+        return;
+    }
+    stateManager.markRunning(step);
+    strategy.execute(...)
+    ```
+  - Note: `evaluateCondition` needs to handle both sync and async results.
+
+- [ ] **Task 3: Unit Tests**
+  - Create `tests/conditional.test.ts` (or add to `tests/TaskRunner.test.ts`).
+  - Test: Task with condition `() => false` is skipped.
+  - Test: Task with condition `() => true` runs.
+  - Test: Task with async condition skipping.
+  - Test: Dependent tasks are also skipped (or handle skip propagation correctly).
+
+- [ ] **Task 4: Verify Dry Run Behavior**
+  - Ensure Dry Run strategy still respects condition if possible, OR clarify in spec that condition is evaluated normally even in dry run (since it's a predicate, not side-effect).

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**