- 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>
89 lines
6.0 KiB
Markdown
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?
|