# 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.