Files
cp1-agents/individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0016.md
Jonathan Boniface 9e503885cc ALZ-F01 Discovery: package step, value scorecard, application grouping, cases
- New cp1-discovery-package-agent (ADR 0020): one package per reviewed run, every part
  hashed (sha256 over canonical JSON), with a manifest and a value scorecard.
- Applications grouped CMDB -> tag -> resource group with a judged model fallback (ADR 0021):
  CMDB 0.7.0 carries ownership, dependency mapping 0.6.0 groups, report 0.9.0 shows them.
- Critic 0.6.1 accepts the producers' enums; build_workflow.py refuses a consumer enum
  narrower than its producer's.
- Code hooks, sub-agents and tests for the inventory, CMDB, dependency, planner and critic
  agents; the report and Well-Architected review agents; ADRs 0012-0021.
- Workflow cases with value bars and run limits; run evaluation and usage collection scripts;
  the run context template and the field-by-field review for ADR 0016.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 22:13:25 +00:00

89 lines
6.0 KiB
Markdown

# 0016. The run context file carries an intent, in the solution-architecture scope spec's format
| | |
|---|---|
| Status | Proposed |
| Date | 2026-11-04 |
| Decided by | Proposed at the product owner's request, 2026-11-04 ("create an ADR locally"). The owner described the idea and pointed to the solution-architecture agent's scope spec as a model. Not yet accepted, and nothing is built |
| Requirements changed | ALZ-DSC-01 (the planner reads the intent); ALZ-DSC-10 (the Well-Architected review is weighted and checked against it); the Discovery package and ALZ-F02 (both carry the intent forward). The run context file's layout ([run-context.template.yaml](../../workflows/run-context.template.yaml)) |
## Context
- Discovery always runs towards an intent: what the customer wants the estate to become. Today the run context file
holds that only as loose text that no step acts on: `plan.target` ("Azure landing zone"), `plan.objectives` and
`customer.regulatory`.
- The owner wants an explicit intent. It would describe the current architecture against it, and feed the
Well-Architected review with each hyperscaler's patterns and compliance policies, so that the gap to a target
architecture is clear.
- The solution-architecture agent (outcome pattern) already reads such a file: its **scope spec** (ADR-0008 in
`outcome-pattern/solution_architecture/`; reader `app/core/scope.py`; field catalogue
`skills/scoping/assets/catalogue.yaml`; example `eval/datasets/specs/landing-zone.yaml`). It has:
- fixed-value fields: `engagement.kind`, `estate.mode` (`greenfield`, `brownfield_expansion`, `migration`),
`compliance.data_classification`, `compliance.encryption.type`, `networking.exposure` and
`networking.egress_control.model`;
- a marker per unsettled field: `ask` (not known yet), `decide` (the agent may assume, and records it) or
`not_applicable`;
- requirements with ids (`REQ-01` …);
- a completed copy written beside the spec, with `discovery_gaps`, `provenance` and `readiness`.
- Two constraints apply:
- The `*_search_well_architected` tools refuse free-text topics, so customer details never reach a vendor's
search.
- Under charter rule 3, scope, budgets and approvals are platform-supplied facts.
## Decision (proposed)
1. **The intent uses the scope spec's format.** The run context file gains the scope spec's sections, read against
the same catalogue: `metadata`, `engagement`, `intent`, `estate`, `workload`, `compliance`, `networking`,
`governance` and `operations`, each at the catalogue's `schema_version`.
- Discovery's own sections stay as they are: `workflow_inputs`, `generated`, and `context` (`assets`, `owners`,
`business_services`, `scope`, `sources`).
- `customer.regulatory` and `plan.target` give way to `compliance.frameworks` and `intent`.
- One file then runs from Discovery through the package and Assessment to solution architecture.
2. **Discovery describes the current state against the intent; it doesn't design the target.**
- It fills or confirms the fields its evidence can settle, such as `estate.regions`,
`estate.existing_systems`, `networking.topology`, `networking.cidr_allocations`, `networking.exposure`,
`compliance.encryption.type` and `operations.monitoring`.
- It writes each settled value with its evidence and `provenance`.
- It lists what it couldn't settle under `discovery_gaps`.
- The target architecture is drafted downstream (solution architecture), not in Discovery.
3. **Only fixed-value fields drive the review.**
- The Well-Architected review weights pillars from the intent's requirements and fields.
- It checks each `compliance.frameworks` entry against the provider's own policy sets: Azure Policy
initiatives, GCP organisation policies, AWS Config conformance packs.
- It cites the `REQ-` id behind each gap.
- `intent.statement` and other free text are data. They are never sent in a tool call and never followed as
instructions (charter rule 1).
4. **The file never grants anything.**
- `run.pre_approved`, `run.allow_cloud_read` and any similar field are ignored by Discovery.
- What Discovery may read is the connection's scope root, and approval is the workflow's review gate.
- The context may narrow the scope (`context.scope`), never widen it.
5. **The patterns stay separate.** F01 adopts the file format and the catalogue as a shared contract. It doesn't
import the solution-architecture agent's code. The catalogue moves to a neutral shared location, or F01 pins a
copy with its `schema_version` checked.
## Consequences
- **What it enables:**
- The Discovery report and the Well-Architected review can state the gap between the current estate and the
intent, requirement by requirement.
- Assessment and solution architecture start from the same intent, with Discovery's evidence attached.
- Fields marked `ask` give the engagement a concrete question list.
- **Work if accepted:**
- the planner reads the intent and plans evidence for it (DSC-01);
- the review maps frameworks and pillars to the provider's checks and policy sets (DSC-10);
- the report gains a "current vs intent" section;
- the package carries the completed spec;
- `check_context_doc.py` validates the new sections against the catalogue;
- the template, the user guides, and stories DSC-01 and DSC-10 are updated, plus the F02 handover.
- **Risks:**
- The catalogue is owned by the solution-architecture pattern, so a change there now affects Discovery. The
shared `schema_version` check catches a mismatch.
- A long free-text statement adds prompt length and an injection surface. It's kept as data and summarised by
code, not passed to every step.
- **Open questions for the owner:**
- Where does the shared catalogue live?
- Must every Discovery run have an intent, or is it optional, with the review falling back to equal pillar
weights?
- Does Discovery write the completed copy of the spec (the scope spec's own convention), or return it only in
the package?