Files
cp1-agents/individual-agents/ALZ-F01: Discovery Workflow Agent/docs/adr/0017.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

3.7 KiB

0017. A live run's scope is every resource under the scope root, planned and checked in code

Status Accepted
Date 2026-11-04
Decided by Product owner, 2026-11-04: "that scope needs to be extend to all resources"
Requirements changed ALZ-DSC-01 (ADO 3214451): what a live run's scope entries are, and how the plan is made. ALZ-DSC-08 (ADO 3214458): what live coverage is measured against

Context

Azure run exec_29ec31ba92ab (2026-11-04) was scoped to the resource group crucible-kab-dev. That group holds 11 resources, but the run scanned, inventoried and reported 3: the AKS cluster, a storage account and a PostgreSQL server.

  • The planner built a live scope only from list_servers, list_workloads, list_kubernetes_clusters and list_data_stores. Two Key Vaults, two managed identities, a DNS zone, an Event Grid topic, a private endpoint and a network interface were never scope entries. They weren't declared as gaps either.
  • The critic measured coverage with the same four tools, so it reported "coverage complete" and passed the run.

Decision

  • Every resource under the connection's scope root is accounted for. The planner's code lists the scope with <provider>_list_resources, every page at 200 a page, and puts each resource in exactly one place (app/scope.py):

    • a scope entry: any resource that isn't structure or a child component;
    • folded into its parent, with the rule recorded:
      • Azure: disks, network interfaces, VM extensions, scale-set instances;
      • GCP: disks, GKE node pools;
    • structure: subscriptions, resource groups, management groups, projects, folders and organisations, which are counted but aren't assets.
  • A live plan is built in code, with no model call (app/plan.py, pre_process):

    • one scan_target per scope entry, in batches of 10;
    • a classify_data per data store;
    • one collect_network and one trace_dependencies;
    • source_gaps set by the same rules as before.

    The run context still only narrows (context.scope.regions, context.scope.exclude), as declared gaps. The new scope_accounting output gives listed, scope_entries, folded (each with its rule) and structure. The sample estate keeps its model and prompt unchanged.

  • An incomplete listing fails the planner step. A refused or failed page, or more than 100 pages, means no plan is made, rather than a plan of part of the estate.

  • The critic counts coverage itself. Its code lists the scope again with the same rules: app/scope.py is identical in both agents, and a test compares the two files. It compares that listing with the findings and the planner's declared gaps, and gives the model live_scope: counts, the uncovered ids (up to 200, with the exact count) and any listing issues. The model copies it into coverage_gaps and coverage_complete. A listing issue fails coverage.

Consequences

  • Supporting services are discovered, inventoried and reported: Key Vault, identities, DNS, messaging, private endpoints, registries, monitoring and so on. The Well-Architected review and Assessment (ALZ-ASM-05) see the same estate.
  • The critic can't pass a run that skipped a resource type.
  • Scale:
    • At subscription scope, about 650 resources become about 600 scan tasks. The planner handles that in code.
    • The scan executor (ALZ-DSC-02) still has a model call each resource's metadata in one request. That fits a resource group, but not a large subscription.
    • Batching the scan in code, as ADR 0015 did for the inventory, is the next change before a subscription-wide run.
  • Folding is a fixed list. A new child-component type shows up as a scope entry until it's added, which over-counts but never drops anything.