docs: propose Matrix Task Execution feature#253
Conversation
Adds `proposal.md`, `tasks.md`, and capability specifications under `openspec/changes/add-matrix-execution/` to formally propose the Matrix Task Execution feature, allowing parameterization and parallel task generation natively in the orchestrator. Co-authored-by: thalesraymond <32554150+thalesraymond@users.noreply.github.com>
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces Matrix Task Execution, enabling the task runner to automatically expand a single task definition into multiple parallel instances based on a parameterized matrix. The review feedback identifies several areas for improvement: the need to ensure the TaskGraphValidator is matrix-aware to catch issues post-expansion, potential naming collisions due to Mermaid sanitization, and the lack of specifications for empty matrix dimensions or matrix-to-matrix dependencies. A suggestion was also made to restrict matrix values to primitive types to ensure deterministic task naming.
| ## What Changes | ||
|
|
||
| - **Task Configuration**: Add an optional `matrix` property to the `TaskStep` interface, allowing users to define a set of parameters (arrays of values) that will multiply the task into multiple instances. | ||
| - **Workflow Executor**: Modify `TaskRunner` or `WorkflowExecutor` (and potentially `TaskGraphValidator`) to dynamically expand matrix steps into individual, parallel sub-tasks at runtime before execution. |
There was a problem hiding this comment.
The proposal suggests expanding matrix steps at runtime before execution. If this expansion occurs after the TaskGraphValidator.validate call in TaskRunner.execute, the validator will only check the unexpanded graph. This might miss issues like name collisions or cycles that only emerge after expansion. It is recommended to clarify if expansion should happen prior to validation or if the validator should be made 'matrix-aware'.
|
|
||
| - **Task Configuration**: Add an optional `matrix` property to the `TaskStep` interface, allowing users to define a set of parameters (arrays of values) that will multiply the task into multiple instances. | ||
| - **Workflow Executor**: Modify `TaskRunner` or `WorkflowExecutor` (and potentially `TaskGraphValidator`) to dynamically expand matrix steps into individual, parallel sub-tasks at runtime before execution. | ||
| - **Task Identity**: Extend task naming conventions or introduce run metadata to uniquely identify matrix sub-tasks (e.g., `TaskName[node=18,os=ubuntu]`). |
There was a problem hiding this comment.
The suggested naming convention TaskName[node=18,os=ubuntu] uses square brackets and equals signs, which are currently sanitized to underscores by TaskRunner.sanitizeMermaidId (line 161 of src/TaskRunner.ts). This could lead to name collisions in Mermaid visualizations (e.g., Task[a=1] and Task_a_1 both becoming Task_a_1_). Consider using a naming format that avoids characters filtered by the existing Mermaid sanitizer.
| #### Scenario: Multi-dimension matrix | ||
| - **WHEN** a `TaskStep` defines a `matrix` with multiple keys (e.g., `os: ["ubuntu", "macos"]`, `node: [18, 20]`) | ||
| - **THEN** the `TaskRunner` SHALL compute the cartesian product of the matrix values | ||
| - **AND** it SHALL dynamically generate and execute a task instance for each permutation (e.g., 4 instances). |
There was a problem hiding this comment.
The specification should define the expected behavior when a matrix dimension is an empty array (e.g., node: []). Common patterns include either throwing a validation error or treating the entire task as skipped (generating zero instances). Explicitly defining this edge case will prevent inconsistent implementations.
|
|
||
| #### Scenario: Matrix task dependency resolution | ||
| - **WHEN** a regular task depends on a task that defines a `matrix` | ||
| - **THEN** the dependent task SHALL wait for ALL generated matrix instances to complete successfully before executing. |
There was a problem hiding this comment.
This requirement defines a 'fan-in' behavior where a dependent task waits for all matrix instances. It would be beneficial to clarify the behavior when the dependent task is also a matrix. For example, if Task B (matrix) depends on Task A (matrix), does every instance of B wait for every instance of A, or is there a mechanism for parallel 1:1 mapping?
| @@ -0,0 +1,10 @@ | |||
| ## 1. Implementation | |||
|
|
|||
| - [ ] 1.1 Update `TaskStep` interface in `src/TaskStep.ts` to include an optional `matrix` configuration, which maps keys to arrays of values (e.g., `Record<string, unknown[]>`). | |||
There was a problem hiding this comment.
Defining the matrix as Record<string, unknown[]> is flexible but may complicate task name generation if complex objects are used as values. Restricting matrix values to primitives (string, number, boolean) ensures that task names are deterministic and readable.
| - [ ] 1.1 Update `TaskStep` interface in `src/TaskStep.ts` to include an optional `matrix` configuration, which maps keys to arrays of values (e.g., `Record<string, unknown[]>`). | |
| - [ ] 1.1 Update `TaskStep` interface in `src/TaskStep.ts` to include an optional `matrix` configuration, which maps keys to arrays of primitive values (e.g., `Record<string, (string | number | boolean)[]>`). |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
thalesraymond
deleted the
docs/add-matrix-execution-spec-11777673469843894919
branch
1 participant
Adds OpenSpec proposal documentation for introducing matrix-based task generation and execution to
@calmo/task-runner. The proposal includes the problem context, technical design, impact, and an actionable checklist for engineers, without modifying any runtime code.PR created automatically by Jules for task 11777673469843894919 started by @thalesraymond