Task: Define and enforce the orchestration contract
Table of Contents
This page documents a task in the Implement the full report pipeline story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
A report run coordinates four services through ores.workflow, and the contract between the coordinator and a stage is implicit today. State it: the participant interface, the idempotency every stage owes because dispatch is at-least-once with no timeout, what compensation undoes in each mode, and which of the two state machines is authoritative. Then make the engine's known silent failures loud.
2. Status
| Field | Value |
|---|---|
| State | BACKLOG |
| Parent story | Implement the full report pipeline |
| Now | Not yet started. |
| Waiting on | Nothing. |
| Next | Begin implementation. |
| Last touched | 2026-09-27 |
3. Acceptance
- Every stage is idempotent under a re-dispatch, demonstrated by restarting mid-run.
- A stage that cannot answer fails the run within a stated budget instead of leaving it in progress for ever.
- An unknown or mis-selected step chain fails the trigger rather than answering success.
- The relationship between the workflow instance and the report instance is stated, and the terminal transition is enforced through the FSM guard.
4. Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
5. Measurements
Every number this task claims about a tree, with the command that produced it
and the commit it was measured at. A number without both is not a measurement,
because a clean-up record describes a tree and trunk moves under a branch: a
consumer count, a gate's component count and a suite's size all change with no
code changing, and the reader of a bare number cannot tell which tree it came
from. Where the raw output matters, put it in an evidence/ file beside the
task and name that file in the Command column.
| What | Value | Command | Commit |
|---|---|---|---|
6. Notes
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
9. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|