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