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

7.0 KiB

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.