Files
orchestration_engine/.agents/plans/iter-01-execution-engine/steps/step-3.md

70 lines
7.0 KiB
Markdown

# Steps 3 and 5: the Workflow, and the Reference's workflow as its first user
Built 2026-10-13, from the Reference at `8b397cd`. The owner has not yet accepted ADR-0001, which this step builds.
## What was built
**The Workflow value** (`execution_engine/workflows/workflow.py`, new) and the generic Deliverable graph (`workflows/deliverables.py`, rewritten from the Reference's). The engine takes a Workflow as a value everywhere it used the Reference's graph: `Ledger(workflow, ...)`, `Ledger.from_dict(workflow, data)`, `specialist_tools(workflow, kind, ...)`, `make_tool_factory(workflow, runtime, roles, ...)`, `load_roles(agents_dir, bundle, workflow, ...)`, `sample_submission(workflow, kind)`, `ExecutionEngine(workflow=...)`, `open_assembly(settings, workflow, root=...)`, `create_app(workflow, ...)`.
What a Workflow supplies, beyond its Phases and Deliverables:
| Part | What it replaces in the Reference |
| --- | --- |
| `data_checks`, `baseline_checks`, `for_readers`, `spec_deliverable`, `final`, `final_file` | `app/workflows/deliverables.py` |
| `validation` (`ValidationPolicy`: the kind, its file, what a failure reopens, `check_ids`, `unimplementable`, `known_ids`) | The router's validation group and `_gap_by_rule` |
| `on_submit` | The three branches at the end of `submit_deliverable` |
| `GraphShape` on a Deliverable | `graph_tools` and the hard-coded list names in `tools/workspace.py` |
| `approval_details`, `approval_facts`, `summary_lines`, `describe_approval` | `request_approval`, `approval_facts`, `assembled_summary`, `describe_prompt` |
| `agreed`, `describe_design`, `subject` | The requirements shown to the decider; the reading hints |
| `changes` (`ChangePolicy`) | `change_summary`, `is_empty`, `settle_meaning`, `changes.json` |
| `role_tools`, `roles`, `optional_roles`, `adjust_roles`, `prepare_role` | Pillar consultation; the pillar advisor and coverage reviewer; the modules Skill |
| `task_entries`, `task_hints` | `terraform_modules` and `pillars_to_consult` in a Specialist's task |
| `options` (`OptionSpec`) | `terraform_modules` on `start`, in state, in the manifest and in a Baseline |
| `kept_for_changes`, `outputs`, `assess` | `working.json`, the customer questions file, the plan appended to the guide, the manifest's own entries, the assessment |
| `local_tools`, `reviews` (given an `Assembling`) | The Terraform runner and the reviews in `open_assembly` |
| `card`, `done`, `response`, `about` | The agent card, the completion message, `/generate`'s reply |
**The example** (`tests/reference_workflow/`): the Reference's own subject as a Workflow. `workflow.py` is the value, `kinds.py` its enums, `hooks.py` and `assembly.py` its code at the points above, and fourteen of the Reference's modules brought unchanged (`chain`, `target_architecture`, `changes`, `work_breakdown`, `pillars`, `modules`, `meaning`, `local`, `coverage`, `design_review`, `requirements_review`, `schema_review`, `assessment`, `presentation`).
**Two scripts.** `scripts/bring.py` now sends the Reference's subject modules to the example. `scripts/repoint.py` points a brought test at the example Workflow.
## Differed from the plan
- **Steps 3 and 5 were built as one, and before the toy Workflow.** With the Reference's workflow as a Workflow, its tests come across almost unchanged, which is a far stronger check of the seam than a toy. Step 4 remains: it shows the engine needs nothing of the Reference's subject.
- **Kinds and Phases are plain strings inside the engine.** A Workflow may declare them as a `StrEnum`; the Workflow turns them into strings when it is built, because they go into checkpointed state. A review therefore receives a string, and one brought test compares with `==` where it used `is`.
- **The manifest changed.** `execution.json` gains `final_document`, `options` and `files`; the Reference's `solution_guide`, `terraform_modules`, `delivery_plan` and `customer_questions` are written by the example's `outputs` hook. Stale files are found from `files`, not from named keys.
- **`tools/meaning.py` went to the example,** not the engine: it reads the Reference's graph.
- **The spec's two file names are the engine's** (`tools/scoping.py`), no longer the Reference's chain module's.
## Tests
454 pass. Brought in this step: `tests/scoped.py` and 21 files under `tests/execution/` and `tests/tools/`, among them `test_engine` (whole Executions on the scripted runtime), `test_router`, `test_change_requests`, `test_working_copy`, `test_requirements_chain`, `test_work_breakdown` and `test_pillars`.
Changed after bringing, beyond what `repoint.py` does:
| File | Change |
| --- | --- |
| `tests/scoped.py` | `ScopedEngine` defaults to the example Workflow |
| `tests/execution/test_pillars.py`, `test_working_copy.py`, `tools/test_guardrail.py` | `make_tool_factory` is given a Workflow carrying the pillar Skills; `graph_tools` is given the shape |
| `tests/execution/test_coverage_review.py` | `kind ==` where it was `kind is` |
| `tests/execution/test_deliverables.py`, `test_engine.py`, `test_working_copy.py` | Three annotations and one dict key take `str` |
## Not brought, and why
Six test files need the Reference's own role files, provider bundle and Skills, which this repository does not hold: `execution/test_overlay_skills`, `test_design_review`, `test_scope_spec`, `test_model_tiers`, `test_terraform_modules`, and `a2a/test_server`. So `adk/roles.load_roles`, `open_assembly`, `card`, `a2a_server` and `main` are converted and type-check but have no test here. The same holds for `tests/agents/test_roles`, `test_adk_engine`, `tests/test_lessons_loop`, `test_providers` and `test_assembly`, and for the four tests removed in step 2.
They need a small agent root under `tests/`: role files, a bundle and stand-in Skills. That is the first thing to build next.
## Left in the engine from the Reference's subject
No engine module names a Deliverable or imports the example. What remains is wording and a few fields:
- `providers.py` (26 lines) still parses `terraform` and `pillar_skills`; `config.py` (18) still holds the Terraform and review settings; `adk/runtime.RoleSpec` still has `modules_skill`. These are read only by the example. They should move to where a Workflow reads its own sections of a bundle and its own settings.
- `config.BASE_DIR` and `providers._REPO_ROOT` still resolve from the package's own location. `open_assembly` no longer uses them; `scope.py`'s command line still does.
- The router's action names (`revise_code`, `revise_target_architecture`) and some messages ("the deployment dry-run failed", "Scope of a workload") are the Reference's words. `nodes/intake.py` still speaks of "the architecture" and reads the Baseline's `solution_guide`.
- `workflows/work_breakdown.py` is whole in the example; its scheduler has not been separated for the engine.
## Verified
`pytest -q`: 454 passed. `ruff check .`, `ruff format --check .`, `mypy .` (103 files): clean. `grep` finds no import of `tests` and no `DeliverableKind`, `PhaseId`, `DEPENDENCY_GRAPH` or `PHASE_ORDER` in `execution_engine/`. `git status` in the Reference shows the same nine modified files as before this work began.