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:
2026-11-05 22:13:25 +00:00
parent f659564208
commit 9e503885cc
211 changed files with 18170 additions and 158 deletions

View File

@@ -0,0 +1,14 @@
"""A live run's coverage is computed in code from the critic's own listing (ADR 0017); the model judges the rest."""
from typing import Any, Optional
from kyndryl_agent_runtime.tools import call_tool
from app import coverage
def pre_process(payload: dict) -> Optional[Any]:
if payload.get("provider", "sample") not in ("azure", "gcp"):
return None # the Meridian sample estate: alz-scope is the authoritative scope, unchanged
payload["live_scope"] = coverage.live_scope(payload, call_tool)
payload["live_dependencies"] = coverage.live_dependencies(payload) # ADR 0019
return payload

View File

@@ -0,0 +1,65 @@
"""A live run's coverage, computed in code from the critic's own listing of every resource in scope (ADR 0017).
The critic doesn't trust the planner's list: it lists the scope root again, with the same rules (app/scope.py), and
compares that with the findings and the planner's declared gaps. Only counts and the uncovered ids go to the model,
so a large estate doesn't fill its prompt.
"""
from __future__ import annotations
from typing import Any, Dict
from app import scope as sc
MAX_IDS = 200 # uncovered ids passed to the model; the count is always exact
def live_scope(payload: Dict[str, Any], call: sc.Call) -> Dict[str, Any]:
provider = payload["provider"]
items, refs, issues = sc.list_all(provider, call)
accounting = sc.account(provider, items)
key = (lambda i: i.lower()) if provider == "azure" else (lambda i: i) # ARM ids are case-insensitive
found = {key(str(f.get("scope_entry_id") or "")) for f in payload.get("findings") or []}
declared = {key(str(g.get("scope_entry_id") or "")) for g in payload.get("coverage_gaps") or []}
uncovered = [e["id"] for e in accounting["entries"] if key(e["id"]) not in found | declared]
return {
"listed": accounting["listed"],
"scope_entries": len(accounting["entries"]),
"folded": len(accounting["folded"]),
"structure": len(accounting["structure"]),
"covered": len(accounting["entries"]) - len(uncovered),
"coverage_gaps": uncovered[:MAX_IDS],
"coverage_gap_count": len(uncovered),
"listing_issues": issues,
"evidence_refs": refs,
}
def live_dependencies(payload: Dict[str, Any]) -> Dict[str, Any]:
"""Every dependency a finding records, against the graph (ADR 0019): an edge from the finding's record to the
target's record (or to the target itself, an external node), or a folded dependency. Computed in code, so the
model never re-derives it."""
provider = payload["provider"]
key = (lambda i: str(i or "").strip().rstrip("/").lower()) if provider == "azure" else \
(lambda i: str(i or "").strip().rstrip("/"))
records = {key(r.get("scope_entry_id")): r.get("canonical_id") for r in payload.get("records") or []}
edges = {(key(e.get("source")), key(e.get("target"))) for e in payload.get("edges") or []}
folded = {(key(f.get("source")), key(f.get("target"))) for f in payload.get("folded_dependencies") or []}
external = {key(n.get("id")) for n in payload.get("nodes") or [] if n.get("kind") == "external"}
recorded, as_edges, to_external, as_folded, missing = 0, 0, 0, 0, []
for finding in payload.get("findings") or []:
source = records.get(key(finding.get("scope_entry_id")))
for dep in finding.get("dependencies") or []:
rid = dep.get("id") if isinstance(dep, dict) else dep
if not rid or key(rid) == key(finding.get("scope_entry_id")):
continue
recorded += 1
target = records.get(key(rid)) or rid
if source and (key(source), key(target)) in edges:
as_edges += 1
to_external += key(target) in external
elif source and (key(source), key(rid)) in folded:
as_folded += 1
else:
missing.append(f"{finding.get('scope_entry_id')} -> {rid}")
return {"recorded": recorded, "edges": as_edges, "to_external_nodes": to_external, "folded": as_folded,
"missing": missing[:MAX_IDS], "missing_count": len(missing)}

View File

@@ -0,0 +1,111 @@
"""A live run's scope: every resource under the connection's scope root (ADR 0017).
The planner plans from this listing and the critic checks coverage against its own run of it, so both copies of
this file must stay identical (tests/test_scope.py in each agent compares them). No runtime imports.
Every resource listed ends in exactly one place:
- a scope entry: an asset the run scans, inventories and reports;
- folded: a child component recorded with its parent's rule (a disk, a network interface, a node pool), never
dropped;
- structure: the estate's subscriptions, resource groups, projects and folders, which are not assets.
"""
from __future__ import annotations
from typing import Any, Callable, Dict, List, Optional, Tuple
PAGE_SIZE = 200 # the servers' maximum page
MAX_PAGES = 100 # 20,000 resources bounds a runaway; the largest estate seen so far is about 650
STRUCTURE = {
"azure": ("microsoft.resources/subscriptions", "microsoft.resources/subscriptions/resourcegroups",
"microsoft.management/managementgroups"),
"gcp": ("cloudresourcemanager.googleapis.com/project", "cloudresourcemanager.googleapis.com/folder",
"cloudresourcemanager.googleapis.com/organization"),
}
FOLDED = {
"azure": {
"microsoft.compute/disks": "a disk is part of the VM it is attached to",
"microsoft.network/networkinterfaces": "a network interface is part of the resource it is attached to",
"microsoft.compute/virtualmachines/extensions": "an extension is part of its VM",
"microsoft.compute/virtualmachinescalesets/virtualmachines": "an instance is part of its scale set",
},
"gcp": {
"compute.googleapis.com/disk": "a disk is part of the instance it is attached to",
"container.googleapis.com/nodepool": "a node pool is part of its cluster",
},
}
DATA_STORES = { # the types the servers' list_data_stores kinds cover; each gets a classify_data task
"azure": ("microsoft.sql/servers", "microsoft.sql/servers/databases", "microsoft.documentdb/databaseaccounts",
"microsoft.storage/storageaccounts", "microsoft.dbforpostgresql/flexibleservers",
"microsoft.dbforpostgresql/servers", "microsoft.dbformysql/flexibleservers",
"microsoft.dbformysql/servers", "microsoft.cache/redis", "microsoft.cache/redisenterprise"),
"gcp": ("sqladmin.googleapis.com/instance", "firestore.googleapis.com/database", "storage.googleapis.com/bucket"),
}
Call = Callable[[str, Dict[str, Any]], Any]
def identity(provider: str, item: Dict[str, Any]) -> Tuple[str, str, str]:
"""(id, type in lower case, location) of one listed resource."""
if provider == "gcp":
return str(item.get("name") or ""), str(item.get("assetType") or "").lower(), str(item.get("location") or "")
return str(item.get("id") or ""), str(item.get("type") or "").lower(), str(item.get("location") or "")
def _data(result: Any) -> Dict[str, Any]:
if isinstance(result, str):
import json
result = json.loads(result)
if not isinstance(result, dict) or result.get("success") is False:
error = (result or {}).get("error") if isinstance(result, dict) else None
raise RuntimeError((error or {}).get("message") or "the tool refused the call")
return result.get("data") or {}
def list_all(provider: str, call: Call) -> Tuple[List[Dict[str, Any]], List[str], List[str]]:
"""(every resource listed, evidence refs, issues). An issue means the listing is incomplete."""
tool = f"{provider}_list_resources"
items: List[Dict[str, Any]] = []
refs: List[str] = []
token: Optional[str] = None
for _ in range(MAX_PAGES):
args: Dict[str, Any] = {"page_size": PAGE_SIZE}
if token:
args["page_token"] = token
try:
data = _data(call(tool, args))
except Exception as error: # noqa: BLE001 - a refused or failed page is an incomplete listing
return items, refs, [f"{tool}: {str(error)[:200]}"]
items += list(data.get("items") or [])
if data.get("evidence_ref"):
refs.append(data["evidence_ref"])
token = data.get("next_page_token")
if not token:
return items, refs, []
return items, refs, [f"{tool}: stopped after {MAX_PAGES} pages"]
def account(provider: str, items: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Every listed resource in exactly one place: entries, folded or structure. Repeats are counted once."""
entries, folded, structure, seen = [], [], [], set()
for item in items:
rid, rtype, location = identity(provider, item)
if not rid or rid in seen:
continue
seen.add(rid)
if rtype in STRUCTURE.get(provider, ()):
structure.append(rid)
elif rtype in FOLDED.get(provider, {}):
folded.append({"id": rid, "type": rtype, "reason": FOLDED[provider][rtype]})
else:
entries.append({"id": rid, "type": rtype, "location": location})
entries.sort(key=lambda e: e["id"].lower())
return {"listed": len(seen), "entries": entries, "folded": folded, "structure": structure}
def region(location: str) -> str:
"""A GCP zone such as europe-west2-b is its region europe-west2; anything else is used as it is."""
parts = location.split("-")
if len(parts) == 3 and len(parts[2]) == 1 and parts[2].isalpha():
return "-".join(parts[:2])
return location