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

2.8 KiB

0014. A Well-Architected review step in Discovery, judged in code

Status Accepted
Date 2026-11-03
Decided by Product owner, 2026-11-03: expand Discovery to support the Well-Architected Framework (advised to place it in ALZ-F02; chose Discovery)
Requirements changed New story ALZ-DSC-10 (to be created); the Discovery report's content for live runs

Context

The first live GCP run produced a thin report, and the owner wants a Well-Architected review of the provider as a file of its own. Discovery's agents collected inventory, metadata and topology, but no policies or recommendations. Azure's subscription has about 1,776 Advisor recommendations (3.2 MB), more than a model step can take.

Decision

  • A new step, cp1-well-architected-review-agent (ALZ-DSC-10), after the critic and before the report. It answers from code in pre_process (app/waf.py), like the report agent (ADR 0012):
    • It reads the in-scope resources, firewall or NSG rules, organisation policies, Azure resource locks and every page of the provider's recommendations, through read-only tools on the existing servers.
    • It applies fixed checks per pillar, rolls up recommendations by pillar and impact, and adds a guidance reference per pillar from the provider's own server (<provider>_search_well_architected; changed on 2026-11-04, when cloud-knowledge was retired).
    • It renders waf_markdown, waf_html and final_waf_html.
    • No model is involved. A pillar with no evidence is "not assessed", never a pass.
    • With provider sample, it's "not applicable" and calls nothing.
  • Its page is released by the existing approval gate, through its own Format for UI step (s12). The report shows a pillar summary.
  • The report gains live sections: estate overview, asset details from a new provider_attributes field (scan, then inventory, which also fills Site), network topology from the network agent's topology_summary, the Well-Architected summary, and a Mermaid dependency diagram. Sections empty only because their source was missing collapse into one "Not examined" list.

Consequences

  • The individual pattern has a second agent with code. Its checks are unit-tested (tests/test_waf.py), and a check change needs a test.
  • Judgement in Discovery. This review judges configuration, which ALZ-F02's ALZ-ASM-05 also does for security. ALZ-ASM-05 should take this review as input rather than repeat it.
  • Partial pillars. Performance and sustainability rest on configuration and recommendations only: there's no utilisation telemetry.
  • No automatic .md file. The platform registers step outputs as output.json, so the Markdown is uploaded after approval with scripts/kab_publish_report.py until the platform can save a field as a file.