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

@@ -1,13 +1,14 @@
#!/usr/bin/env python3
"""Write workflows/cp1-alz-discovery-individual.json: the KAB workflow export chaining the eight agents.
"""Write workflows/cp1-alz-discovery-individual.json: the KAB workflow export chaining the eleven agents.
The same export format as cp4-agents' workflow (export_version 2.0.0). There is no orchestrator: each step is one
agent, and each step's inputs are workflow inputs or named fields of earlier steps' outputs (`from_steps`). The
classification and network steps run in parallel; the critic's step stops for the Engagement Lead's approval. Each
step's schemas are read from its agent's schemas/ folder, so run this again after changing them. Standard library
only.
classification and network steps run in parallel; the report's step stops for the Engagement Lead's approval, and
only after it do the two pages (s10, s12) and the Discovery package for the Assessment workflow (s13, ADR 0020) run.
Each step's schemas are read from its agent's schemas/ folder, so run this again after changing them. The build
refuses a step whose input schema would refuse a value the earlier step's output can hold. Standard library only.
Front steps (ADR 0011, the repository's scripts/kab_front_steps.py): the planner (s1) and the inventory (s3) take the text the
Front steps (ADR 0011, the repository's scripts/kab_front_steps.py): the planner (s1), the inventory (s3), the CMDB step (s4) and the report (s9) take the text the
platform extracts from files, since declarative agents can't open files:
u1 Parse Assessment Files: the run form's upload field `file` -> `source_documents` (u1.parsed_content)
a1 Artifacts: project artifacts fixed by id -> `reference_documents` (a1.parsed_content)
@@ -26,56 +27,129 @@ from pathlib import Path
# kab_front_steps is shared by every Feature, in the repository's scripts/ folder.
sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "scripts"))
from kab_front_steps import AGENT_STEP_TIMEOUT_MINUTES, ARTIFACTS_ID, UPLOAD_ID, front_steps, shift # noqa: E402
from kab_front_steps import AGENT_STEP_TIMEOUT_MINUTES, ARTIFACTS_ID, UPLOAD_ID, _activity_step, front_steps, shift # noqa: E402
ROOT = Path(__file__).resolve().parents[1]
NAME = "CP1 - Agentic Landing Zone - Discovery (individual agents)"
STAMP = "2026-10-29T12:00:00"
WF = ["engagement_id", "run_id"]
WF = ["engagement_id", "run_id", "provider"]
# (step id, agent folder, parallel group, inputs from earlier steps)
STEPS = [
("s1", "cp1-discovery-planner-agent", 0, {}),
("s2", "cp1-estate-scan-executor-agent", 1, {"tasks": "s1.tasks"}),
("s3", "cp1-asset-inventory-normalisation-agent", 2, {"findings": "s2.findings"}),
("s4", "cp1-cmdb-itsm-reconciliation-agent", 3, {"tasks": "s1.tasks", "records": "s3.records"}),
("s5", "cp1-data-classification-agent", 4, {"records": "s3.records"}),
("s4", "cp1-cmdb-itsm-reconciliation-agent", 3, {"tasks": "s1.tasks", "records": "s3.records",
"source_gaps": "s1.source_gaps"}),
("s5", "cp1-data-classification-agent", 4, {"records": "s3.records", "source_gaps": "s1.source_gaps"}),
("s6", "cp1-network-discovery-assessment-agent", 4, {"tasks": "s1.tasks", "records": "s3.records"}),
("s7", "cp1-dependency-mapping-agent", 5, {"records": "s3.records", "drift_items": "s4.drift_items",
"flows": "s6.flows"}),
"flows": "s6.flows", "findings": "s2.findings",
"cmdb_cis": "s4.cis", "cmdb_relationships": "s4.relationships",
"cmdb_dangling": "s4.dangling_relationships"}),
("s8", "cp1-discovery-critic-agent", 6, {"coverage_gaps": "s1.coverage_gaps", "findings": "s2.findings",
"records": "s3.records", "drift_items": "s4.drift_items",
"stores": "s5.stores", "network_findings": "s6.findings",
"edges": "s7.edges"}),
"edges": "s7.edges", "source_gaps": "s1.source_gaps",
"cmdb_injections": "s4.injections_found",
"nodes": "s7.nodes", "folded_dependencies": "s7.folded_dependencies"}),
("s11", "cp1-well-architected-review-agent", 7, {"records": "s3.records", "source_gaps": "s1.source_gaps", "verdict": "s8.verdict"}),
("s9", "cp1-discovery-report-agent", 8, {"topology_summary": "s6.topology_summary", "waf_status": "s11.status",
"waf_pillars": "s11.pillars", "waf_note": "s11.note","plan_summary": "s1.summary", "coverage_gaps": "s1.coverage_gaps", "source_gaps": "s1.source_gaps",
"scan_findings": "s2.findings", "records": "s3.records",
"sme_review_queue": "s3.sme_review_queue", "drift_items": "s4.drift_items",
"itsm_signals": "s4.itsm_signals", "stores": "s5.stores",
"network_findings": "s6.findings", "ranges": "s6.ranges", "edges": "s7.edges",
"nodes": "s7.nodes", "orphans": "s7.orphans",
"validation_queue": "s7.validation_queue", "verdict": "s8.verdict",
"critic_note": "s8.note", "obeyed_injection": "s8.obeyed_injection",
"unsupported_claims": "s8.unsupported_claims",
"consistency_issues": "s8.consistency_issues",
"parse_failures": "s8.parse_failures",
"tool_call_issues": "s8.tool_call_issues",
"cmdb_sources": "s4.cmdb_sources", "cmdb_injections": "s4.injections_found",
"graph_comparison": "s7.graph_comparison",
"folded_dependencies": "s7.folded_dependencies", "dangling": "s7.dangling",
"applications": "s7.applications", "asset_owners": "s7.asset_owners",
"ungrouped_assets": "s7.ungrouped_assets"}),
# After the report's review point: one package for the Assessment workflow (ADR 0020). Every input is copied
# unchanged; app/package.py INPUTS names the part each one belongs to.
("s13", "cp1-discovery-package-agent", 9, {
"plan_id": "s1.plan_id", "plan_summary": "s1.summary", "coverage_gaps": "s1.coverage_gaps",
"source_gaps": "s1.source_gaps", "scope_accounting": "s1.scope_accounting",
"scan_findings": "s2.findings",
"records": "s3.records", "sme_review_queue": "s3.sme_review_queue",
"drift_items": "s4.drift_items", "itsm_signals": "s4.itsm_signals", "cmdb_summary": "s4.summary",
"cmdb_cis": "s4.cis", "cmdb_relationships": "s4.relationships", "cmdb_dangling": "s4.dangling_relationships",
"cmdb_sources": "s4.cmdb_sources", "cmdb_injections": "s4.injections_found",
"stores": "s5.stores",
"ranges": "s6.ranges", "flows": "s6.flows", "network_findings": "s6.findings",
"topology_summary": "s6.topology_summary",
"nodes": "s7.nodes", "edges": "s7.edges", "orphans": "s7.orphans", "validation_queue": "s7.validation_queue",
"folded_dependencies": "s7.folded_dependencies", "dangling": "s7.dangling",
"graph_comparison": "s7.graph_comparison",
"applications": "s7.applications", "asset_owners": "s7.asset_owners",
"ungrouped_assets": "s7.ungrouped_assets", "applications_note": "s7.applications_note",
"verdict": "s8.verdict", "critic_note": "s8.note", "coverage_complete": "s8.coverage_complete",
"unsupported_claims": "s8.unsupported_claims", "consistency_issues": "s8.consistency_issues",
"obeyed_injection": "s8.obeyed_injection", "not_checked": "s8.not_checked",
"waf_status": "s11.status", "waf_pillars": "s11.pillars", "waf_checks": "s11.checks",
"waf_recommendations": "s11.recommendations", "waf_note": "s11.note",
"report_counts": "s9.counts", "report_markdown": "s9.report_markdown"}),
]
PACKAGE_STEP = "s13"
def field(path: Path, key: str) -> str:
return re.search(rf'^{key}:\s*"?([^"\n]+)"?$', path.read_text(), re.M).group(1)
def enums(schema: dict, path: str = "") -> dict[str, set]:
"""Every enum in a schema, keyed by where it sits (`.field`, `[]` for an array's items)."""
found = {path: set(schema["enum"])} if "enum" in schema else {}
for name, sub in schema.get("properties", {}).items():
found.update(enums(sub, f"{path}.{name}"))
if isinstance(schema.get("items"), dict):
found.update(enums(schema["items"], f"{path}[]"))
return found
def narrower_enums(produced: dict, accepted: dict) -> dict[str, list]:
"""Values the producing step's output can hold that the consuming step's input schema would refuse (run
exec_071f83409cec: the critic refused the dependency graph's `represents` edges)."""
theirs = enums(accepted)
return {p: sorted(v - theirs[p]) for p, v in enums(produced).items() if p in theirs and v - theirs[p]}
# The steps that take the extracted text of uploaded files and selected artifacts.
DOC_STEPS = ("s1", "s3")
DOC_STEPS = ("s1", "s3", "s4", "s9") # the report shows the run context file; s4 reads uploaded CMDB exports (ADR 0018)
def build(with_upload: bool = True, artifact_ids=()) -> dict:
by_id = {sid: folder for sid, folder, _, _ in STEPS}
front = front_steps(
with_upload, list(artifact_ids), upload_label="Discovery source files",
upload_description="Optional client files for discovery: a CMDB or asset export, a scope list, network "
"documentation. Their text is given to the planner and the inventory agent as evidence, "
"never as instructions.",
upload_description="The run context file first, then the files its uploads: list names, such as CMDB "
"exports (CSV or XLSX). Their text is given to the planner, the inventory, the CMDB step "
"and the report as evidence, never as instructions.",
artifacts_description="Project artifacts for discovery, e.g. an earlier run's outputs. Their text is given "
"to the planner and the inventory agent.")
if any(f["id"] == ARTIFACTS_ID for f in front):
parse = _activity_step("p1", "parse_assessment_files", "Parse selected artifacts", "Turns the selected artifacts into text.",
{"from_steps": {"files": f"{ARTIFACTS_ID}.artifacts"}}, {"type": "object", "properties": {"files": {"type": "array"}}},
{"type": "object", "properties": {"parsed_content": {"type": "string"}, "file_metadata": {"type": "array"}}}, y=320)
parse.update({"depends_on": [ARTIFACTS_ID], "executionLevel": 1, "parallelGroup": 1, "position": {"x": -160, "y": 320}})
front.append(parse)
front_ids = {f["id"] for f in front}
lead = 1 if front else 0
steps, connections, agents, seen = list(front), [], [], set()
lead = (2 if "p1" in front_ids else 1) if front else 0
steps, connections, agents, seen = list(front), ([{"source": ARTIFACTS_ID, "target": "p1"}] if "p1" in front_ids else []), [], set()
for sid, folder, group, from_steps in STEPS:
from_steps = dict(from_steps)
if sid in DOC_STEPS:
if UPLOAD_ID in front_ids:
from_steps["source_documents"] = f"{UPLOAD_ID}.parsed_content"
if ARTIFACTS_ID in front_ids:
from_steps["reference_documents"] = f"{ARTIFACTS_ID}.parsed_content"
# select_artifacts' only output is `artifacts` (base64 records); p1 parses them into text.
from_steps["reference_documents"] = "p1.parsed_content"
agent = ROOT / folder
agent_id = folder.replace("-", "_")
display = field(agent / "agent.yaml", "display_name")
@@ -90,21 +164,27 @@ def build(with_upload: bool = True, artifact_ids=()) -> dict:
src_out = json.loads((ROOT / by_id[src_step] / "schemas" / "output.json").read_text())
assert src_field in src_out["properties"], f"{sid}: {source} is not an output of {by_id[src_step]}"
assert target in input_schema["properties"], f"{sid}: {target} is not an input of {folder}"
refused = narrower_enums(src_out["properties"][src_field], input_schema["properties"][target])
assert not refused, f"{sid}: {folder}'s input {target} refuses values {source} can hold: {refused}"
depends = sorted({s.split(".")[0] for s in from_steps.values()})
connections += [{"source": d, "target": sid} for d in depends]
inputs = {"from_workflow": WF}
inputs = {"from_workflow": WF + (["include_cmdb", "include_itsm"] if sid == "s1" else [])}
if from_steps:
inputs["from_steps"] = from_steps
if sid == PACKAGE_STEP:
# Which agent versions produced the package, as built (ADR 0020).
inputs["static"] = {"agent_versions": {f: field(ROOT / f / "agent.yaml", "version")
for _, f, _, _ in STEPS if f != folder}}
hitl = {"enabled": False}
if folder == "cp1-discovery-critic-agent":
if folder == "cp1-discovery-report-agent":
hitl = {"enabled": True, "checkpoint_type": "approval",
"review_focus": "The Engagement Lead reviews the critic's verdict and every reason for a fail "
"review_focus": "The Engagement Lead reads the report, with the critic's verdict and every reason for a fail, "
"before Assessment starts. A fail verdict is never auto-approved.",
"timeout_hours": 24, "allowed_actions": ["continue", "rerun", "abort"], "max_reruns": 2}
steps.append(shift({
"id": sid, "agent": agent_id, "agent_type": agent_id, "name": f"{display} Step", "timeout_minutes": AGENT_STEP_TIMEOUT_MINUTES,
"type": "sequential", "executionLevel": group, "parallelGroup": group, "depends_on": depends,
"position": {"x": 320 * group, "y": 160 if sid == "s6" else 0}, "inputs": inputs, "hitl": hitl,
"position": {"x": 320 * group, "y": {"s6": 160, PACKAGE_STEP: 320}.get(sid, 0)}, "inputs": inputs, "hitl": hitl,
"data": {"agentType": agent_id, "name": f"{display} Step",
"description": field(agent / "agent.yaml", "description"), "category": "agent",
"temporalActivityName": "generic_agent_call",
@@ -116,6 +196,24 @@ def build(with_upload: bool = True, artifact_ids=()) -> dict:
if agent_id not in seen:
seen.add(agent_id)
agents.append({"name": agent_id, "display_name": display, "source_url": url, "category": "agent"})
# After the approval gate: the clean page, as this run's own artifact (ADR 0012).
final = _activity_step("s10", "format_for_ui", "Format for UI", "The approved report, for display as a page.",
{"from_steps": {"input_data": "s9.final_html"}, "static": {"format_type": "html"}},
{"type": "object", "properties": {"input_data": {"type": "string"}, "format_type": {"type": "string"}}},
{"type": "object", "properties": {"data": {"type": "object"}}}, y=0)
final.update({"depends_on": ["s9"], "position": {"x": 320 * 9, "y": 0}})
final["executionLevel"] = final["parallelGroup"] = 9
steps.append(shift(final, lead))
connections.append({"source": "s9", "target": "s10"})
# The Well-Architected review's own page, after the same approval gate (ADR 0014).
waf = _activity_step("s12", "format_for_ui", "Format Well-Architected review for UI", "The approved Well-Architected review, as a page.",
{"from_steps": {"input_data": "s11.final_waf_html"}, "static": {"format_type": "html"}},
{"type": "object", "properties": {"input_data": {"type": "string"}, "format_type": {"type": "string"}}},
{"type": "object", "properties": {"data": {"type": "object"}}}, y=160)
waf.update({"depends_on": ["s9", "s11"], "position": {"x": 320 * 9, "y": 160}})
waf["executionLevel"] = waf["parallelGroup"] = 9
steps.append(shift(waf, lead))
connections += [{"source": "s9", "target": "s12"}, {"source": "s11", "target": "s12"}]
description = f"{NAME}: " + "; then ".join(field(ROOT / f / "agent.yaml", "display_name") for _, f, _, _ in STEPS) + "."
tags = ["cp1", "public-cloud", "agentic-landing-zone"]
return {