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>
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
# 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?
|
||||
Reference in New Issue
Block a user