@calmo/task-runner 3.8.4 → 4.1.0

package/.agent/workflows/openspec-apply.md

@@ -0,0 +1,20 @@
+---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

package/.agent/workflows/openspec-archive.md

@@ -0,0 +1,24 @@
+---
+description: Archive a deployed OpenSpec change and update specs.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict --no-interactive` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

package/.agent/workflows/openspec-proposal.md

@@ -0,0 +1,25 @@
+---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict --no-interactive` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

package/.github/workflows/codeql.yml

@@ -57,7 +57,7 @@ jobs:
         # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     # Add any setup steps before running the `github/codeql-action/init` action.
     # This includes steps like installing compilers or runtimes (`actions/setup-node`

package/.github/workflows/release-please.yml

@@ -0,0 +1,46 @@
+name: release-please
+
+on:
+    push:
+        branches:
+            - main
+
+permissions:
+    contents: write
+    pull-requests: write
+    id-token: write
+
+jobs:
+    release-please:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: googleapis/release-please-action@v4
+              id: release
+              with:
+                  token: ${{ secrets.GITHUB_TOKEN }}
+                  target-branch: main
+
+            - uses: actions/checkout@v6
+              if: ${{ steps.release.outputs.release_created }}
+
+            - name: Setup pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  version: 10.28.0
+              if: ${{ steps.release.outputs.release_created }}
+
+            - uses: actions/setup-node@v6
+              with:
+                  node-version: "lts/*"
+                  registry-url: "https://registry.npmjs.org"
+                  cache: "pnpm"
+              if: ${{ steps.release.outputs.release_created }}
+
+            - run: pnpm install --frozen-lockfile
+              if: ${{ steps.release.outputs.release_created }}
+
+            - run: pnpm build
+              if: ${{ steps.release.outputs.release_created }}
+
+            - run: pnpm publish --no-git-checks
+              if: ${{ steps.release.outputs.release_created }}

package/.jules/nexus.md

@@ -14,3 +14,8 @@
 
 **Insight:** Users' optimization efforts are blind without granular metrics. Users often don't know *which* task is slow, only that the workflow is slow.
 **Action:** Always include telemetry requirements (like start/end times and duration) in execution engine specs to enable data-driven optimization.
+
+## 2026-01-20 - The "All or Nothing" Retry Trap
+
+**Insight:** Blindly retrying failing tasks is a "Product Anti-pattern". Retrying a `SyntaxError` or invalid user input 3 times (with exponential backoff!) is annoying and wasteful.
+**Action:** We must distinguish between "Transient" (network, resource lock) and "Permanent" (logic, validation) failures. Exposing a `shouldRetry` predicate gives the user control without complicating the core runner logic.

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "4.1.0"
+}

package/AGENTS.md

@@ -1,21 +1,17 @@
 <!-- OPENSPEC:START -->
-
 # OpenSpec Instructions
 
 These instructions are for AI assistants working in this project.
 
 Always open `@/openspec/AGENTS.md` when the request:
-
 - Mentions planning or proposals (words like proposal, spec, change, plan)
 - Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
 - Sounds ambiguous and you need the authoritative spec before coding
 
 Use `@/openspec/AGENTS.md` to learn:
-
 - How to create and apply change proposals
 - Spec format and conventions
 - Project structure and guidelines
-- When creating specs or docs, add a prefix "docs:" to your commit to avoid triggering a new module version
 
 Keep this managed block so 'openspec update' can refresh the instructions.
 
@@ -29,6 +25,7 @@ Keep this managed block so 'openspec update' can refresh the instructions.
 - Its forbidden to have coverage drop below 100%, thats non negotiable.
 - **Strict Null Safety:** Do not use `??` or optional chaining `?.` when you can guarantee existence via prior validation. Use non-null assertions `!` only when the invariant is locally provable or enforced by a validator.
 - **Dead Code Elimination:** Avoid `v8 ignore` comments. If code is unreachable, restructure the logic to prove it is unreachable to the compiler, or remove the branch if the invariant is guaranteed.
+- **Signal Combination:** Prefer `AbortSignal.any()` over manual event listeners when combining multiple `AbortSignal`s to simplify logic and avoid memory leaks.
 
 ## Operational Protocols
 

package/CHANGELOG.md

@@ -18,6 +18,129 @@
 * refactor: Refactor TaskRunner to reduce cognitive complexity (#89) ([95c67d9](https://github.com/thalesraymond/task-runner/commit/95c67d9)), closes [#89](https://github.com/thalesraymond/task-runner/issues/89)
 * Refactor TaskGraphValidator to address SonarCloud issues (#88) ([77c1538](https://github.com/thalesraymond/task-runner/commit/77c1538)), closes [#88](https://github.com/thalesraymond/task-runner/issues/88)
 
+## [4.1.0](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.0.4...task-runner-v4.1.0) (2026-01-24)
+
+
+### Features
+
+* 🎸 Add task name to sucess message on dry run ([5b9fcd0](https://github.com/thalesraymond/task-runner/commit/5b9fcd0ddd61172687e464cf6a3b5fb65df20cdf))
+* 🎸 metrics per task ([#103](https://github.com/thalesraymond/task-runner/issues/103)) ([c824c56](https://github.com/thalesraymond/task-runner/commit/c824c56dce6d958de8946e1fb9af598bd7e10e5e))
+
+
+### Bug Fixes
+
+* 🐛 getMermaidGraph ID collision for similar task names ([#100](https://github.com/thalesraymond/task-runner/issues/100)) ([0d3af0d](https://github.com/thalesraymond/task-runner/commit/0d3af0d1663346d31c4d05bfd0eb498456221b2f))
+* 🛰️ Sonar Specialist: Refactor signal combination in TaskRunner ([#107](https://github.com/thalesraymond/task-runner/issues/107)) ([9c383cc](https://github.com/thalesraymond/task-runner/commit/9c383cc7a6657133136945cec01ccc50d30f752d))
+
+
+### Performance Improvements
+
+* optimize Mermaid graph ID generation ([#112](https://github.com/thalesraymond/task-runner/issues/112)) ([59e78b1](https://github.com/thalesraymond/task-runner/commit/59e78b1b975e89120d27d827127fbd813a399e36))
+
+## [4.0.4](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.0.3...task-runner-v4.0.4) (2026-01-22)
+
+
+### Bug Fixes
+
+* 🐛 id-token: writ ([39fbc2b](https://github.com/thalesraymond/task-runner/commit/39fbc2bc83d448cd2385a2c71089832f61f4b3e3))
+
+## [4.0.3](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.0.2...task-runner-v4.0.3) (2026-01-22)
+
+
+### Bug Fixes
+
+* 🐛 remove npm token (depoys is based on trust setting) ([872d42a](https://github.com/thalesraymond/task-runner/commit/872d42ad35524757f0974e5b46b54b9abf10d7c8))
+
+## [4.0.2](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.0.1...task-runner-v4.0.2) (2026-01-22)
+
+
+### Bug Fixes
+
+* 🐛 using new action (remove deprecated warning) ([6238bbd](https://github.com/thalesraymond/task-runner/commit/6238bbdfd7689468e4eb650c427848fae8f2d674))
+
+## [4.0.1](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.0.0...task-runner-v4.0.1) (2026-01-22)
+
+
+### Bug Fixes
+
+* 🐛 test ci ([0137225](https://github.com/thalesraymond/task-runner/commit/013722547a31d5429f3024ba21eeefba0fbfc426))
+
+## [4.0.0](https://github.com/thalesraymond/task-runner/compare/task-runner-v3.8.4...task-runner-v4.0.0) (2026-01-22)
+
+
+### ⚠ BREAKING CHANGES
+
+* 🧨 Major refactor in the engine, added strategy pattern support
+* **security:** none
+* **security:** none
+* **security:** none
+
+### Features
+
+* 🎸 Generating 3.0.0 since automation wrongly skiped ([c545f25](https://github.com/thalesraymond/task-runner/commit/c545f25be8c689d4a0b518f71635d5b6303b2c64))
+* 🎸 new conditional execution feature ([e936ad7](https://github.com/thalesraymond/task-runner/commit/e936ad71acf5fa3c744b4fa7984f6c7665f75e32))
+* add CI workflow and restore dependabot ([57ae940](https://github.com/thalesraymond/task-runner/commit/57ae940d3dde2adf2de362a48b635def7de2fa7a))
+* add CI workflow and restore dependabot ([48ec98b](https://github.com/thalesraymond/task-runner/commit/48ec98b075feb4bb7e8d339105afdbcb0b5f0fa3))
+* add CI workflow and restore dependabot ([9263c43](https://github.com/thalesraymond/task-runner/commit/9263c43466ee43dd5e07a4edbd9f2ca0b49015e6))
+* add CI workflow for build, lint, and test ([6f97dc0](https://github.com/thalesraymond/task-runner/commit/6f97dc0ee6d1f09de5ddedc64aca73d257e4bc65))
+* add CI workflow for build, lint, and test ([a03422e](https://github.com/thalesraymond/task-runner/commit/a03422ea9ab18cb9f38d8fde58a64c4ce982ff7f))
+* add concurrency control to TaskRunner ([90c2b6f](https://github.com/thalesraymond/task-runner/commit/90c2b6fc7466d9b63820c190e73cc4e96f557335))
+* add concurrency control to TaskRunner ([2a8dfd2](https://github.com/thalesraymond/task-runner/commit/2a8dfd2e825f4802030723c26cf83a51037b99c7))
+* add issue templates ([6ff97f1](https://github.com/thalesraymond/task-runner/commit/6ff97f1140f4de2f3c4a02bd98579474af0893fe))
+* add task priority for concurrency scheduling ([#87](https://github.com/thalesraymond/task-runner/issues/87)) ([43bb6b4](https://github.com/thalesraymond/task-runner/commit/43bb6b4e381dd822358f0e573bfd414a5356d8a5))
+* add task retry policy ([81d4bd3](https://github.com/thalesraymond/task-runner/commit/81d4bd3567a7c4542ba35e311a1a19dd7da7b904))
+* add workflow preview and dry-run capabilities ([e1ccda9](https://github.com/thalesraymond/task-runner/commit/e1ccda9f23e13befd4221cd95b7acfd5500d0e66))
+* add workflow preview and dry-run capabilities ([138f4ae](https://github.com/thalesraymond/task-runner/commit/138f4ae2761d992f111cc108612f4d81b06f6a41))
+* add workflow state persistence proposal ([b62769e](https://github.com/thalesraymond/task-runner/commit/b62769ed128f3c77efb88532c2d2a5d971f0f751))
+* configure semantic-release for automated releases ([fa13bf5](https://github.com/thalesraymond/task-runner/commit/fa13bf5a42f9eb4a4c65aebca28c1b11ff36b618))
+* Implement generic task runner with dependency management and parallel execution ([e0c8bf9](https://github.com/thalesraymond/task-runner/commit/e0c8bf9d3fe8bd7aa14ebb442752e02600c7332e))
+* implement Observer Pattern event system in TaskRunner ([d682983](https://github.com/thalesraymond/task-runner/commit/d682983ebb2aa72eefb05ec06382b206f35473cc))
+* implement Observer Pattern event system in TaskRunner ([48bd3d0](https://github.com/thalesraymond/task-runner/commit/48bd3d0c83bf76dacceee4bb105beb0365816f1c))
+* **implement:** complete file structure refactor ([7764e43](https://github.com/thalesraymond/task-runner/commit/7764e4336effdb8098d4c29c7df5ab10df3d0997))
+* **implement:** complete file structure refactor and cleanup ([372ca8b](https://github.com/thalesraymond/task-runner/commit/372ca8b3703f5e4b3aa14754165ab0fff9451c05))
+* initialize project with TypeScript, Vitest, and basic sum function ([02dd759](https://github.com/thalesraymond/task-runner/commit/02dd75989bfc7a4e9d1f1360fe334284dafd021a))
+* **plan:** create technical plan for file refactor ([29d2a97](https://github.com/thalesraymond/task-runner/commit/29d2a97e0b8b1d98caa27467bf4e865c987e5371))
+* pre-validation of task graph for cycles and missing deps ([4680c1b](https://github.com/thalesraymond/task-runner/commit/4680c1b076abcbd5349129b2ac5db19b4585eec7)), closes [#004](https://github.com/thalesraymond/task-runner/issues/004)
+* **specs:** add spec for file structure refactor ([884c551](https://github.com/thalesraymond/task-runner/commit/884c5512cf9267b4c10a42053019a72abf624650))
+* **tasks:** create tasks for file structure refactor ([3b99e22](https://github.com/thalesraymond/task-runner/commit/3b99e2269220d740ca552733c4bcb41b74bc8108))
+* throw TaskGraphValidationError on validation failure ([35a4e91](https://github.com/thalesraymond/task-runner/commit/35a4e91e66beb7d0660b4059740f4067ab4f2af2))
+
+
+### Bug Fixes
+
+* 🐛 fix sanitization of mermaid function ([b09db63](https://github.com/thalesraymond/task-runner/commit/b09db63b2fdad55c5cfb197ce6009cb81a8604f5))
+* 🐛 fixing commit script and adding a fix to test auto relea ([97cedf4](https://github.com/thalesraymond/task-runner/commit/97cedf4acda6c84db02be4549bf0eb7cbc3a4c16))
+* 🐛 trigger ci ([27f6121](https://github.com/thalesraymond/task-runner/commit/27f61216f6aad326409ac4ded114e79c8b9fbd61))
+* 🛡️ Sentinel: Fix Mermaid graph identifier sanitization ([#81](https://github.com/thalesraymond/task-runner/issues/81)) ([a8bebe3](https://github.com/thalesraymond/task-runner/commit/a8bebe3577e2b3f96aaa759bc6eff91b173b5785))
+* 🛰️ Sonar Specialist: Fix dead code in `TaskGraphValidator` ([#93](https://github.com/thalesraymond/task-runner/issues/93)) ([b760765](https://github.com/thalesraymond/task-runner/commit/b76076593cb80f414868872248fad4a8e503f8bd))
+* add file extensions and types to test file to fix CI errors ([54b186f](https://github.com/thalesraymond/task-runner/commit/54b186f7e1bce6e79e2e8ef3b7a501d1be28b467))
+* address PR comments on sonar config ([6eab0b5](https://github.com/thalesraymond/task-runner/commit/6eab0b52fa420bcb26f64737f2915fe20867603d))
+* address PR comments on sonar config ([156eea0](https://github.com/thalesraymond/task-runner/commit/156eea041a1713de20cea3f0e4bac132e4f81649))
+* address pr feedback ([4a23576](https://github.com/thalesraymond/task-runner/commit/4a2357650012fe9e48baa98222576346a2ce1f79))
+* address pr feedback ([97cf83f](https://github.com/thalesraymond/task-runner/commit/97cf83ffa22dba3972a275f99b7eb4da4c012878))
+* change singleQuote option to false in Prettier configuration ([94625a3](https://github.com/thalesraymond/task-runner/commit/94625a3084ee1d6ae218990bf3e9bb5138002415))
+* correct syntax errors in README.md examples and improve context hydration explanation ([98e3a5a](https://github.com/thalesraymond/task-runner/commit/98e3a5abd25e8856aa0c4458e8b7c8555b01a887))
+* **EventBus:** fix lint errors in test file ([86b3ad8](https://github.com/thalesraymond/task-runner/commit/86b3ad86584372552c757ecaf9e47b8ffdec3cb5))
+* **EventBus:** handle floating promises ([#90](https://github.com/thalesraymond/task-runner/issues/90)) ([9872c37](https://github.com/thalesraymond/task-runner/commit/9872c376b912014a73ef180e426d2de5ca771c76))
+* **EventBus:** handle unhandled promise rejections in event listeners ([5f5235a](https://github.com/thalesraymond/task-runner/commit/5f5235adde48f4ce738fe89cad27ddc1023a4445))
+* Fix missing event emission on task cancellation ([#92](https://github.com/thalesraymond/task-runner/issues/92)) ([3d7e7aa](https://github.com/thalesraymond/task-runner/commit/3d7e7aa191686520f0f6d2e721cf1ec2bf7ac983))
+* remove any type usage in TaskRunner to satisfy linter ([b0a21a7](https://github.com/thalesraymond/task-runner/commit/b0a21a748bdf8fb71e14f7ea3a83937b5a36cb2f))
+* remove unreachable code and verify single execution in concurrency logic ([7255cee](https://github.com/thalesraymond/task-runner/commit/7255cee7c686431a4cac0db5e26f2f12e85ea849))
+* resolve linting errors and verify concurrency control ([9ed2585](https://github.com/thalesraymond/task-runner/commit/9ed2585fb2f712c7210fae84dba70152b9ab7169))
+* revert unauthorized changes to package.json and tsconfig.test.json ([cd44f9e](https://github.com/thalesraymond/task-runner/commit/cd44f9e38451a608a73d201624e675612e7b93af))
+* **security:** replace recursive cycle detection with iterative DFS ([2d2e395](https://github.com/thalesraymond/task-runner/commit/2d2e395aab9306610af03ba4b1305ad448d69d63))
+* **security:** replace recursive cycle detection with iterative DFS ([1e2d7ca](https://github.com/thalesraymond/task-runner/commit/1e2d7ca1704ae288fc54258df698621ecab2eceb))
+* **security:** replace recursive cycle detection with iterative DFS ([292947f](https://github.com/thalesraymond/task-runner/commit/292947f67aa8e64adf62bd23c56f1ce06766c16f))
+* standardize quotes and formatting in dependabot configuration ([ab2d7fa](https://github.com/thalesraymond/task-runner/commit/ab2d7fa2bb14c17b300bca64d0c29711bcc0d5f5))
+
+
+### Performance Improvements
+
+* **executor:** optimize processQueue loop using pending set ([2924700](https://github.com/thalesraymond/task-runner/commit/2924700cfc161af1500190395d5043a9249388f8))
+* Make event listeners async to prevent blocking ([1f8728f](https://github.com/thalesraymond/task-runner/commit/1f8728f4bd9735868c942223548f13ffc9fb98d5))
+* Make event listeners async to prevent blocking ([a52f8d0](https://github.com/thalesraymond/task-runner/commit/a52f8d09827c27b78a07f342a56c392460f89668))
+* optimize task scheduling to prevent pipeline stalls ([37c52f7](https://github.com/thalesraymond/task-runner/commit/37c52f7ce78b1ee1d8483d4b2c33bd73e585850f))
+
 ## 3.8.0 (2026-01-21)
 
 * feat: add task priority for concurrency scheduling (#87) ([43bb6b4](https://github.com/thalesraymond/task-runner/commit/43bb6b4)), closes [#87](https://github.com/thalesraymond/task-runner/issues/87) [#74](https://github.com/thalesraymond/task-runner/issues/74)

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement by contacting the project maintainers.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to task-runner
+
+First off, thanks for taking the time to contribute!
+
+The following is a set of guidelines for contributing to `@calmo/task-runner`. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## Getting Started
+
+1.  **Fork the repository** on GitHub.
+2.  **Clone your fork** locally.
+    ```bash
+    git clone https://github.com/your-username/task-runner.git
+    cd task-runner
+    ```
+3.  **Install dependencies** using `pnpm`.
+    ```bash
+    pnpm install
+    ```
+    *Note: This project uses `pnpm` for package management. Please do not use `npm` or `yarn`.*
+
+## Development Workflow
+
+1.  **Create a branch** for your feature or fix.
+    ```bash
+    git checkout -b feature/my-new-feature
+    ```
+2.  **Make your changes**.
+3.  **Run checks** locally to ensure your changes are valid.
+
+### Scripts & Commands
+
+The project uses several `pnpm` scripts to maintain code quality:
+
+*   **Build**: Compile the project.
+    ```bash
+    pnpm build
+    ```
+*   **Test**: Run tests with coverage.
+    ```bash
+    pnpm test
+    ```
+    **Important**: We enforce **100% code coverage**. If your changes lower the coverage, the CI will fail.
+*   **Lint**: Check for linting errors.
+    ```bash
+    pnpm lint
+    ```
+*   **Format**: Format the code using Prettier.
+    ```bash
+    pnpm format
+    ```
+
+## Coding Standards
+
+Please strictly adhere to the following rules:
+
+*   **No `any`**: The use of `any` type is strictly forbidden. Use `unknown` or proper types.
+*   **Strict Null Safety**: Do not use `??` or optional chaining `?.` when you can guarantee existence via prior validation. Use non-null assertions `!` only when the invariant is locally provable or enforced by a validator.
+*   **Dead Code Elimination**: Avoid `v8 ignore` comments. Logic should be structured to prove unreachability.
+*   **Atomic Commits**: For complex features, commit after completing distinct tasks. Ensure `pnpm build`, `pnpm lint`, and `pnpm test` pass before each commit.
+
+For more detailed agent-specific instructions (which are also good for humans), refer to `AGENTS.md`.
+
+## Commit Messages
+
+We follow the **Conventional Commits** specification.
+
+You can use the built-in helper to format your commit messages:
+```bash
+pnpm commit
+```
+Or format them manually:
+*   `feat(scope): add new feature`
+*   `fix(scope): fix bug`
+*   `docs: update documentation`
+*   `test: add tests`
+*   `refactor: refactor code`
+
+## Submitting a Pull Request
+
+1.  Push your changes to your fork.
+2.  Open a Pull Request against the `main` branch.
+3.  Ensure the PR description clearly describes the problem and solution.
+4.  Make sure all CI checks pass.
+
+Thank you for your contributions!

package/README.md

@@ -120,7 +120,7 @@ When calling `execute`, you can provide a configuration object:
 - **signal**: Accepts an `AbortSignal` to cancel the workflow programmatically.
 - **dryRun**: Overrides the current strategy with `DryRunExecutionStrategy` for this execution.
 
-```typescript
+```typescript 
 await runner.execute(steps, {
     concurrency: 2,
     dryRun: true

package/dist/TaskResult.d.ts

@@ -11,4 +11,13 @@ export interface TaskResult {
     error?: string;
     /** Optional data produced by the step for later inspection. */
     data?: unknown;
+    /** Optional execution metrics for the task. */
+    metrics?: {
+        /** Start time in milliseconds (performance.now). */
+        startTime: number;
+        /** End time in milliseconds (performance.now). */
+        endTime: number;
+        /** Duration in milliseconds. */
+        duration: number;
+    };
 }