Files
cp1-agents/individual-agents/ALZ-F01: Discovery Workflow Agent/cp1-discovery-package-agent/app/scorecard.py
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

164 lines
8.5 KiB
Python

"""The value scorecard (ADR 0020): how far a Discovery run answers what its two consumers ask, counted in code.
- The Assessment workflow (F02) reads these fields for every inventory record. Each cell is `filled` (a value),
`declared_gap` (no value, and the planner declared the source that would give it as missing), `missing` (no value
and no declared reason) or `not_applicable` (the field does not apply to this record, such as a data class on a
server).
- The Engagement Lead needs the decisions the run leaves for a person, and every finding with an owner and an action.
The same function serves the package step's manifest and `scripts/evaluate_workflow_run.py`, so the scorecard a run
ships with is the scorecard its case is judged by. No model is involved.
"""
from __future__ import annotations
from collections import Counter
from typing import Any
VERSION = "2" # 2: application and owner read from the dependency step's grouping (ADR 0021)
EMPTY = (None, "", "unknown", "Unknown", [], {})
# F02 field -> the planner's source_gaps sources whose absence explains a missing value. The planner's sources are
# cmdb, itsm, netflow and schema: there is no source yet for lifecycle, cost or compliance, so those can only be
# filled or missing until a source is added (ADR 0020, phase 3).
F02_FIELDS = {
"application": ("cmdb",),
"owner": ("cmdb",),
"criticality": ("cmdb",),
"environment": (),
"support_status": (),
"end_of_support": (),
"compliance_scope": (),
"annual_cost": (),
"data_class": ("schema",),
}
STATES = ("filled", "declared_gap", "missing", "not_applicable")
def _facts(record: dict) -> dict:
return record.get("facts") if isinstance(record.get("facts"), dict) else {}
def _value(field: str, record: dict, stores: dict, grouping: dict) -> Any:
facts = _facts(record)
rid = record.get("canonical_id")
if field == "application":
return grouping["application"].get(rid) or facts.get("business_service") or facts.get("application")
if field == "owner":
return grouping["owner"].get(rid) or facts.get("owner")
if field == "environment":
return record.get("environment")
if field == "data_class":
store = stores.get(record.get("canonical_id"))
if store is None:
return "not_applicable"
return None if store.get("highest_class") in ("unclassified", "unknown", None) else store["highest_class"]
return facts.get(field)
def _cell(field: str, record: dict, stores: dict, gaps: set, grouping: dict) -> str:
value = _value(field, record, stores, grouping)
if value == "not_applicable":
return "not_applicable"
if value not in EMPTY:
return "filled"
if field == "data_class" and (stores.get(record.get("canonical_id")) or {}).get("reason"):
return "declared_gap" # unclassified with the reason the classification step gave
return "declared_gap" if gaps & set(F02_FIELDS[field]) else "missing"
def _share(part: int, whole: int) -> float:
return round(part / whole, 3) if whole else 0.0
def _grouping(applications: dict | None) -> dict:
"""Each record's application and owner from the dependency step's grouping (ADR 0021)."""
applications = applications or {}
return {"application": {m: a.get("name") for a in applications.get("applications") or [] for m in a.get("members") or []},
"owner": {o.get("canonical_id"): o.get("owner") for o in applications.get("asset_owners") or []}}
def f02_fields(records: list, stores: list, source_gaps: list, applications: dict | None = None) -> dict:
by_id = {s.get("canonical_id"): s for s in stores or [] if isinstance(s, dict)}
grouping = _grouping(applications)
gaps = {g.get("source") for g in source_gaps or [] if isinstance(g, dict)}
per_field = {field: dict.fromkeys(STATES, 0) for field in F02_FIELDS}
for record in records or []:
for field in F02_FIELDS:
per_field[field][_cell(field, record, by_id, gaps, grouping)] += 1
totals = Counter()
for counts in per_field.values():
totals.update(counts)
applicable = sum(totals[s] for s in ("filled", "declared_gap", "missing"))
return {"records": len(records or []), "cells": applicable,
"filled": _share(totals["filled"], applicable), "declared_gap": _share(totals["declared_gap"], applicable),
"missing": _share(totals["missing"], applicable),
"filled_or_declared": _share(totals["filled"] + totals["declared_gap"], applicable),
"per_field": per_field}
def f02_run(parts: dict) -> dict:
"""What F02's ASM-01 checks before it starts."""
gaps = {g.get("source") for g in (parts.get("plan") or {}).get("source_gaps") or [] if isinstance(g, dict)}
inventory = parts.get("inventory") or {}
deps = parts.get("dependencies") or {}
critic = parts.get("critic") or {}
cmdb = parts.get("cmdb") or {}
checks = {
"inventory_present": bool(inventory.get("records")),
"dependency_map_present": deps.get("edges") is not None and deps.get("nodes") is not None,
"critic_passed": critic.get("verdict") == "pass",
"classification_present": (parts.get("classification") or {}).get("stores") is not None,
"network_present": parts.get("network") is not None,
"itsm_signals_or_declared": bool(cmdb.get("itsm_signals")) or "itsm" in gaps,
"applications_listed": bool((parts.get("applications") or {}).get("applications")),
}
return {"checks": checks, "met": sum(checks.values()), "of": len(checks)}
def decisions(parts: dict) -> dict:
"""What the run leaves for a person to decide, by kind."""
kinds: Counter = Counter()
for item in (parts.get("cmdb") or {}).get("drift_items") or []:
kinds[f"cmdb_{item.get('type')}"] += 1
deps = parts.get("dependencies") or {}
kinds["edges_to_validate"] += len(deps.get("validation_queue") or [])
kinds["cmdb_relationships_dangling"] += len(deps.get("dangling") or [])
kinds["assets_for_sme_review"] += len((parts.get("inventory") or {}).get("sme_review_queue") or [])
grouped = parts.get("applications") or {}
kinds["applications_to_review"] += sum(1 for a in grouped.get("applications") or [] if a.get("review_required"))
kinds["assets_ungrouped"] += len(grouped.get("ungrouped_assets") or [])
kinds["coverage_gaps"] += len((parts.get("plan") or {}).get("coverage_gaps") or [])
critic = parts.get("critic") or {}
kinds["critic_issues"] += len(critic.get("unsupported_claims") or []) + len(critic.get("consistency_issues") or [])
kinds["well_architected_fails"] += sum(1 for c in (parts.get("well_architected") or {}).get("checks") or []
if isinstance(c, dict) and c.get("result") == "fail")
by_kind = {k: v for k, v in sorted(kinds.items()) if v}
return {"total": sum(by_kind.values()), "by_kind": by_kind}
def findings(parts: dict) -> dict:
"""Every finding a person acts on, and how many name an owner and an action."""
grouping = _grouping(parts.get("applications"))
owners = {r.get("canonical_id"): grouping["owner"].get(r.get("canonical_id")) or _facts(r).get("owner")
for r in (parts.get("inventory") or {}).get("records") or []}
rows = []
for item in (parts.get("cmdb") or {}).get("drift_items") or []:
rows.append((owners.get(item.get("canonical_id")), item.get("suggested_action")))
for item in (parts.get("network") or {}).get("findings") or []:
rows.append((None, item.get("recommended_action")))
for check in (parts.get("well_architected") or {}).get("checks") or []:
if isinstance(check, dict) and check.get("result") == "fail":
for asset in check.get("affected") or [None]:
rows.append((owners.get(asset), check.get("recommended_action")))
with_owner = sum(1 for owner, _ in rows if owner not in EMPTY)
with_action = sum(1 for _, action in rows if action not in EMPTY)
return {"total": len(rows), "with_owner": with_owner, "with_action": with_action,
"with_owner_share": _share(with_owner, len(rows)), "with_action_share": _share(with_action, len(rows))}
def score(parts: dict) -> dict:
inventory = parts.get("inventory") or {}
return {"version": VERSION,
"f02_fields": f02_fields(inventory.get("records"), (parts.get("classification") or {}).get("stores"),
(parts.get("plan") or {}).get("source_gaps"), parts.get("applications")),
"f02_run": f02_run(parts), "decisions": decisions(parts), "findings": findings(parts)}