@calmo/task-runner 4.0.4 → 4.2.0

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

@@ -20,7 +20,7 @@ jobs:
                   token: ${{ secrets.GITHUB_TOKEN }}
                   target-branch: main
 
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
               if: ${{ steps.release.outputs.release_created }}
 
             - name: Setup pnpm
@@ -29,7 +29,7 @@ jobs:
                   version: 10.28.0
               if: ${{ steps.release.outputs.release_created }}
 
-            - uses: actions/setup-node@v4
+            - uses: actions/setup-node@v6
               with:
                   node-version: "lts/*"
                   registry-url: "https://registry.npmjs.org"

package/.jules/nexus.md

@@ -14,3 +14,13 @@
 
 **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.
+
+## 2026-01-24 - The Cleanup Paradox
+
+**Insight:** "Continue On Error" is often misused for Cleanup logic. Users mark critical tasks as "Optional" just to ensure subsequent cleanup tasks run, which incorrectly allows *other* dependents to run too. True "Teardown" requires the *dependent* to assert its resilience, not the *dependency* to declare its weakness.
+**Action:** Invert the control. Instead of the failing task saying "I don't matter" (`continueOnError`), the cleanup task should say "I run anyway" (`runCondition: 'always'`). This preserves the criticality of the workflow while ensuring resource hygiene.

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.0.4"
+  ".": "4.2.0"
 }

package/AGENTS.md

@@ -25,6 +25,9 @@ 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.
+- **Map Lookups:** Avoid double lookups in Maps (e.g., `has()` followed by `get()`). Check the result of `get()` against `undefined` to perform the check in a single operation.
+- **String Replacement:** Always favor `String.prototype.replaceAll` over `String.prototype.replace` with global regex for clarity.
 
 ## Operational Protocols
 

package/CHANGELOG.md

@@ -18,6 +18,52 @@
 * 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.2.0](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.1.0...task-runner-v4.2.0) (2026-02-15)
+
+
+### Features
+
+* 🎸 mvp for plugin system ([7d85610](https://github.com/thalesraymond/task-runner/commit/7d856103651416826bdf6b440d9aa613ab2ac997))
+* add middleware support proposal ([#123](https://github.com/thalesraymond/task-runner/issues/123)) ([e93c2f1](https://github.com/thalesraymond/task-runner/commit/e93c2f1bd34764dbb084ff9645836ec20fdef026))
+* **spec:** add task loop proposal ([#157](https://github.com/thalesraymond/task-runner/issues/157)) ([a89a846](https://github.com/thalesraymond/task-runner/commit/a89a8462cd7ff2a54625805e30ee0c14eae95fa2))
+
+
+### Bug Fixes
+
+* 🛰️ Sonar Specialist: Fix issues in `src/TaskRunner.ts` ([#128](https://github.com/thalesraymond/task-runner/issues/128)) ([fd87799](https://github.com/thalesraymond/task-runner/commit/fd877993497539728b6c7ba55d1a34ea7e1d7737))
+
+
+### Performance Improvements
+
+* ⚡ Optimize Mermaid graph generation performance ([#155](https://github.com/thalesraymond/task-runner/issues/155)) ([18d3e93](https://github.com/thalesraymond/task-runner/commit/18d3e934631907a2c41ceb2c60942d3ec50b9dc5))
+* ⚡ Optimize WorkflowExecutor loop performance ([#153](https://github.com/thalesraymond/task-runner/issues/153)) ([c0457f0](https://github.com/thalesraymond/task-runner/commit/c0457f00f9a1315f7b23829fec08d3bceba37a14))
+* optimize cascadeFailure to O(N) using index pointer ([#135](https://github.com/thalesraymond/task-runner/issues/135)) ([1ecd7b8](https://github.com/thalesraymond/task-runner/commit/1ecd7b8fe1c72ebc7f97aaaa6bc9aeacdb830ae2))
+* optimize EventBus scheduling with queueMicrotask ([#154](https://github.com/thalesraymond/task-runner/issues/154)) ([4d74788](https://github.com/thalesraymond/task-runner/commit/4d74788aa689da0f296986dc15fe8a4fd080bbc7))
+* optimize Mermaid graph generation by removing redundant ID loop ([#158](https://github.com/thalesraymond/task-runner/issues/158)) ([940bdc5](https://github.com/thalesraymond/task-runner/commit/940bdc5c377a0b54567f73e968202f8c7e5c5020))
+* optimize mermaid graph generation deduplication ([#150](https://github.com/thalesraymond/task-runner/issues/150)) ([ff5db6d](https://github.com/thalesraymond/task-runner/commit/ff5db6d7a8ac22c414f260d04e13e06ec894b30c))
+* optimize TaskStateManager initialization to avoid double map lookups ([#132](https://github.com/thalesraymond/task-runner/issues/132)) ([02c516c](https://github.com/thalesraymond/task-runner/commit/02c516cc030b27b4c3bb143107e25c91503b0dd8))
+* remove redundant processLoop call in WorkflowExecutor ([#151](https://github.com/thalesraymond/task-runner/issues/151)) ([8286223](https://github.com/thalesraymond/task-runner/commit/8286223c6e28f5a60414a554b877792f73e1b147))
+* **validator:** optimize graph validation (3x speedup) ([#127](https://github.com/thalesraymond/task-runner/issues/127)) ([66f97e7](https://github.com/thalesraymond/task-runner/commit/66f97e7bc3999d38b78640e29cd47b086532a97a))
+
+## [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)
 
 

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

@@ -21,6 +21,7 @@ Try the [Showcase App](https://task-runner-mu.vercel.app/) to see the runner in
 - **Event System**: Subscribe to lifecycle events for logging or monitoring.
 - **Runtime Validation**: Automatically detects circular dependencies and missing dependencies.
 - **Conditional Execution**: Skip tasks dynamically based on context state.
+- **Plugin System**: Extend functionality with custom logic and event listeners.
 
 ## Usage Example
 
@@ -139,6 +140,39 @@ console.log(graph);
 // Output: graph TD; A-->B; ...
 ```
 
+## Plugin System
+
+You can extend the `TaskRunner` with plugins to inject custom logic or listen to events without modifying the core.
+
+### Creating a Plugin
+
+A plugin is an object with a `name`, `version`, and an `install` method.
+
+```typescript
+import { Plugin, PluginContext } from "@calmo/task-runner";
+
+const MyLoggerPlugin: Plugin<MyContext> = {
+  name: "my-logger-plugin",
+  version: "1.0.0",
+  install: (context: PluginContext<MyContext>) => {
+    context.events.on("taskStart", ({ step }) => {
+      console.log(`[Plugin] Starting task: ${step.name}`);
+    });
+  },
+};
+```
+
+### Using a Plugin
+
+Register the plugin using the `use()` method on the `TaskRunner` instance.
+
+```typescript
+const runner = new TaskRunner(context);
+runner.use(MyLoggerPlugin);
+
+await runner.execute(steps);
+```
+
 ## Skip Propagation
 
 If a task fails or is skipped, the `TaskRunner` automatically marks all subsequent tasks that depend on it as `skipped`. This ensures that your pipeline doesn't attempt to run steps with missing prerequisites.

package/conductor/code_styleguides/general.md

@@ -0,0 +1,23 @@
+# General Code Style Principles
+
+This document outlines general coding principles that apply across all languages and frameworks used in this project.
+
+## Readability
+- Code should be easy to read and understand by humans.
+- Avoid overly clever or obscure constructs.
+
+## Consistency
+- Follow existing patterns in the codebase.
+- Maintain consistent formatting, naming, and structure.
+
+## Simplicity
+- Prefer simple solutions over complex ones.
+- Break down complex problems into smaller, manageable parts.
+
+## Maintainability
+- Write code that is easy to modify and extend.
+- Minimize dependencies and coupling.
+
+## Documentation
+- Document *why* something is done, not just *what*.
+- Keep documentation up-to-date with code changes.

package/conductor/code_styleguides/javascript.md

@@ -0,0 +1,51 @@
+# Google JavaScript Style Guide Summary
+
+This document summarizes key rules and best practices from the Google JavaScript Style Guide.
+
+## 1. Source File Basics
+- **File Naming:** All lowercase, with underscores (`_`) or dashes (`-`). Extension must be `.js`.
+- **File Encoding:** UTF-8.
+- **Whitespace:** Use only ASCII horizontal spaces (0x20). Tabs are forbidden for indentation.
+
+## 2. Source File Structure
+- New files should be ES modules (`import`/`export`).
+- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
+- **Imports:** Do not use line-wrapped imports. The `.js` extension in import paths is mandatory.
+
+## 3. Formatting
+- **Braces:** Required for all control structures (`if`, `for`, `while`, etc.), even single-line blocks. Use K&R style ("Egyptian brackets").
+- **Indentation:** +2 spaces for each new block.
+- **Semicolons:** Every statement must be terminated with a semicolon.
+- **Column Limit:** 80 characters.
+- **Line-wrapping:** Indent continuation lines at least +4 spaces.
+- **Whitespace:** Use single blank lines between methods. No trailing whitespace.
+
+## 4. Language Features
+- **Variable Declarations:** Use `const` by default, `let` if reassignment is needed. **`var` is forbidden.**
+- **Array Literals:** Use trailing commas. Do not use the `Array` constructor.
+- **Object Literals:** Use trailing commas and shorthand properties. Do not use the `Object` constructor.
+- **Classes:** Do not use JavaScript getter/setter properties (`get name()`). Provide ordinary methods instead.
+- **Functions:** Prefer arrow functions for nested functions to preserve `this` context.
+- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for multi-line strings or complex interpolation.
+- **Control Structures:** Prefer `for-of` loops. `for-in` loops should only be used on dict-style objects.
+- **`this`:** Only use `this` in class constructors, methods, or in arrow functions defined within them.
+- **Equality Checks:** Always use identity operators (`===` / `!==`).
+
+## 5. Disallowed Features
+- `with` keyword.
+- `eval()` or `Function(...string)`.
+- Automatic Semicolon Insertion.
+- Modifying builtin objects (`Array.prototype.foo = ...`).
+
+## 6. Naming
+- **Classes:** `UpperCamelCase`.
+- **Methods & Functions:** `lowerCamelCase`.
+- **Constants:** `CONSTANT_CASE` (all uppercase with underscores).
+- **Non-constant Fields & Variables:** `lowerCamelCase`.
+
+## 7. JSDoc
+- JSDoc is used on all classes, fields, and methods.
+- Use `@param`, `@return`, `@override`, `@deprecated`.
+- Type annotations are enclosed in braces (e.g., `/** @param {string} userName */`).
+
+*Source: [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)*

package/conductor/code_styleguides/typescript.md

@@ -0,0 +1,43 @@
+# Google TypeScript Style Guide Summary
+
+This document summarizes key rules and best practices from the Google TypeScript Style Guide, which is enforced by the `gts` tool.
+
+## 1. Language Features
+- **Variable Declarations:** Always use `const` or `let`. **`var` is forbidden.** Use `const` by default.
+- **Modules:** Use ES6 modules (`import`/`export`). **Do not use `namespace`.**
+- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
+- **Classes:**
+  - **Do not use `#private` fields.** Use TypeScript's `private` visibility modifier.
+  - Mark properties never reassigned outside the constructor with `readonly`.
+  - **Never use the `public` modifier** (it's the default). Restrict visibility with `private` or `protected` where possible.
+- **Functions:** Prefer function declarations for named functions. Use arrow functions for anonymous functions/callbacks.
+- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for interpolation and multi-line strings.
+- **Equality Checks:** Always use triple equals (`===`) and not equals (`!==`).
+- **Type Assertions:** **Avoid type assertions (`x as SomeType`) and non-nullability assertions (`y!`)**. If you must use them, provide a clear justification.
+
+## 2. Disallowed Features
+- **`any` Type:** **Avoid `any`**. Prefer `unknown` or a more specific type.
+- **Wrapper Objects:** Do not instantiate `String`, `Boolean`, or `Number` wrapper classes.
+- **Automatic Semicolon Insertion (ASI):** Do not rely on it. **Explicitly end all statements with a semicolon.**
+- **`const enum`:** Do not use `const enum`. Use plain `enum` instead.
+- **`eval()` and `Function(...string)`:** Forbidden.
+
+## 3. Naming
+- **`UpperCamelCase`:** For classes, interfaces, types, enums, and decorators.
+- **`lowerCamelCase`:** For variables, parameters, functions, methods, and properties.
+- **`CONSTANT_CASE`:** For global constant values, including enum values.
+- **`_` Prefix/Suffix:** **Do not use `_` as a prefix or suffix** for identifiers, including for private properties.
+
+## 4. Type System
+- **Type Inference:** Rely on type inference for simple, obvious types. Be explicit for complex types.
+- **`undefined` and `null`:** Both are supported. Be consistent within your project.
+- **Optional vs. `|undefined`:** Prefer optional parameters and fields (`?`) over adding `|undefined` to the type.
+- **`Array<T>` Type:** Use `T[]` for simple types. Use `Array<T>` for more complex union types (e.g., `Array<string | number>`).
+- **`{}` Type:** **Do not use `{}`**. Prefer `unknown`, `Record<string, unknown>`, or `object`.
+
+## 5. Comments and Documentation
+- **JSDoc:** Use `/** JSDoc */` for documentation, `//` for implementation comments.
+- **Redundancy:** **Do not declare types in `@param` or `@return` blocks** (e.g., `/** @param {string} user */`). This is redundant in TypeScript.
+- **Add Information:** Comments must add information, not just restate the code.
+
+*Source: [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)*

package/conductor/product-guidelines.md

@@ -0,0 +1,14 @@
+# Product Guidelines
+
+## Documentation Style
+- Tone: Professional, technical, and friendly.
+- Style: Clear, concise, and focused on accuracy, while remaining approachable with instructional examples.
+- Examples: Focused, bite-sized code snippets illustrating specific features for quick comprehension.
+
+## Brand Messaging & Visual Identity
+- Core Value: Stability and Reliability.
+- Focus: Emphasize robust testing, production-readiness, and the "engine-like" nature of the orchestrator.
+
+## Quality Standards
+- Clarity over brevity in technical explanations.
+- Prioritize accuracy and reliability in all user-facing communications.

package/conductor/product.md

@@ -0,0 +1,16 @@
+# Initial Concept
+A lightweight, type-safe, and domain-agnostic task orchestration engine. It resolves a Directed Acyclic Graph (DAG) of steps, executes independent tasks in parallel, and manages a shared context across the pipeline.
+
+## Target Users
+- Developers building complex CI/CD pipelines.
+- Engineers creating automated data processing workflows.
+
+## Goals
+- Provide a simple and intuitive API for defining and running task graphs.
+
+## Key Features
+- Enhanced observability and logging for complex task graphs.
+- Support for persistent state to allow resuming long-running workflows.
+
+## Complexity & Architecture
+- Provide a hybrid approach with optional plugins for advanced features like persistence.

package/conductor/setup_state.json

@@ -0,0 +1 @@
+{"last_successful_step": "2.5_workflow"}

package/conductor/tech-stack.md

@@ -0,0 +1,19 @@
+# Technology Stack
+
+## Core
+- **Programming Language:** TypeScript
+- **Runtime:** Node.js
+
+## Development Tools
+- **Package Manager:** pnpm
+- **Build Tool:** tsc (TypeScript Compiler)
+
+## Quality Assurance
+- **Test Framework:** Vitest
+- **Code Coverage:** @vitest/coverage-v8
+- **Linting:** ESLint (typescript-eslint)
+- **Formatting:** Prettier
+
+## Infrastructure & Release
+- **Release Management:** release-please
+- **Static Analysis:** SonarCloud