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

6.0 KiB

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)

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?