Files
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

100 lines
6.0 KiB
Python

"""The Discovery package (ADR 0020): every step's output in one document, with a manifest F02 checks in code.
The step runs after the report's review point, so a package exists only for a run the Engagement Lead let through.
Parts are named by meaning, not step id (KAB renames step ids on import), and copied unchanged so their evidence
references still resolve. Each part's `sha256` is over its canonical JSON: `json.dumps(part, sort_keys=True,
separators=(",", ":"), ensure_ascii=False)` encoded as UTF-8. No model is involved.
"""
from __future__ import annotations
import hashlib
import json
from datetime import datetime, timezone
from typing import Any
from app import scorecard
PACKAGE_VERSION = "1.0"
# The step's input name -> (part, the producing agent's own field name). scripts/build_workflow.py wires each input
# from the step that produces it; this table and that wiring are checked against each other by tests/test_package.py.
INPUTS = {
"plan_id": ("plan", "plan_id"), "plan_summary": ("plan", "summary"), "coverage_gaps": ("plan", "coverage_gaps"),
"source_gaps": ("plan", "source_gaps"), "scope_accounting": ("plan", "scope_accounting"),
"scan_findings": ("scan", "findings"),
"records": ("inventory", "records"), "sme_review_queue": ("inventory", "sme_review_queue"),
"drift_items": ("cmdb", "drift_items"), "itsm_signals": ("cmdb", "itsm_signals"), "cmdb_summary": ("cmdb", "summary"),
"cmdb_cis": ("cmdb", "cis"), "cmdb_relationships": ("cmdb", "relationships"),
"cmdb_dangling": ("cmdb", "dangling_relationships"), "cmdb_sources": ("cmdb", "cmdb_sources"),
"cmdb_injections": ("cmdb", "injections_found"),
"stores": ("classification", "stores"),
"ranges": ("network", "ranges"), "flows": ("network", "flows"), "network_findings": ("network", "findings"),
"topology_summary": ("network", "topology_summary"),
"nodes": ("dependencies", "nodes"), "edges": ("dependencies", "edges"), "orphans": ("dependencies", "orphans"),
"validation_queue": ("dependencies", "validation_queue"),
"folded_dependencies": ("dependencies", "folded_dependencies"), "dangling": ("dependencies", "dangling"),
"graph_comparison": ("dependencies", "graph_comparison"),
"applications": ("applications", "applications"), "asset_owners": ("applications", "asset_owners"),
"ungrouped_assets": ("applications", "ungrouped_assets"), "applications_note": ("applications", "applications_note"),
"verdict": ("critic", "verdict"), "critic_note": ("critic", "note"),
"coverage_complete": ("critic", "coverage_complete"), "unsupported_claims": ("critic", "unsupported_claims"),
"consistency_issues": ("critic", "consistency_issues"), "obeyed_injection": ("critic", "obeyed_injection"),
"not_checked": ("critic", "not_checked"),
"waf_status": ("well_architected", "status"), "waf_pillars": ("well_architected", "pillars"),
"waf_checks": ("well_architected", "checks"), "waf_recommendations": ("well_architected", "recommendations"),
"waf_note": ("well_architected", "note"),
"report_counts": ("report", "counts"), "report_markdown": ("report", "report_markdown"),
}
PARTS = ("plan", "scan", "inventory", "cmdb", "classification", "network", "dependencies", "applications", "critic",
"well_architected", "report")
# What F02 cannot start without. The CMDB, the applications (none on the sample estate) and the Well-Architected
# review are optional: a run without a CMDB says so in source_gaps, and F02's ASM-05 reads the provider itself.
REQUIRED = ("plan", "inventory", "classification", "network", "dependencies", "critic", "report")
# How many items each part holds, for the manifest.
COUNTED = {"scan": "findings", "inventory": "records", "cmdb": "drift_items", "classification": "stores",
"network": "findings", "dependencies": "edges", "applications": "applications", "well_architected": "checks"}
def digest(part: Any) -> str:
text = json.dumps(part, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
def parts_from(payload: dict) -> dict:
"""The step's inputs, grouped into named parts. A part none of whose inputs arrived is absent (None)."""
parts: dict[str, dict] = {}
for name, (part, field) in INPUTS.items():
if payload.get(name) is not None:
parts.setdefault(part, {})[field] = payload[name]
return {part: parts.get(part) for part in PARTS}
def build(payload: dict, execution_id: str = "", now: datetime | None = None) -> dict:
parts = parts_from(payload)
present = [p for p in PARTS if parts[p] is not None]
missing = [p for p in REQUIRED if parts[p] is None]
verdict = (parts["critic"] or {}).get("verdict")
problems = [f"part missing: {p}" for p in missing]
if verdict != "pass":
problems.append(f"critic verdict is {verdict or 'absent'}, not pass")
manifest = {
"package_version": PACKAGE_VERSION,
"engagement_id": payload.get("engagement_id"),
"run_id": payload.get("run_id"),
"execution_id": execution_id or None,
"provider": payload.get("provider"),
"created_at": (now or datetime.now(timezone.utc)).strftime("%Y-%m-%dT%H:%M:%SZ"),
"critic_verdict": verdict,
"reviewed": "The package step runs only after the Engagement Lead continued past the report's review point.",
"agent_versions": payload.get("agent_versions") or {},
"source_gaps": [g.get("source") for g in (parts["plan"] or {}).get("source_gaps") or [] if isinstance(g, dict)],
"parts": {p: {"sha256": digest(parts[p]),
**({"items": len((parts[p] or {}).get(COUNTED[p]) or [])} if p in COUNTED else {})}
for p in present},
"absent_parts": [p for p in PARTS if parts[p] is None],
"complete": not problems,
"problems": problems,
"scorecard": scorecard.score(parts),
}
return {"engagement_id": payload.get("engagement_id"), "run_id": payload.get("run_id"),
"package_version": PACKAGE_VERSION, "manifest": manifest, **{p: parts[p] for p in present}}