feat: establish the Target architecture as a graph before code
Design is now approved before any infrastructure code is written (ADR-0005). A new target-architect Specialist produces one graph of Elements, Relationships and Checks; the diagram is rendered from it, deployment guidance must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations carry ids in data files, and a submission with a gap in the Requirements chain is refused. Also in this commit: - Customer cases group Executions, with an intent history per case - lesson candidates are captured when an Execution ends - evaluation gains chain, verdict, judged and interactive checks, and per-case thresholds - Terraform providers are cached between checks - the requirements analyst proposes defaults instead of asking - the legacy-baseline case and the checks that only read it are removed - ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed - plans for iterations 4 to 7 under .agents/plans/ Unproven with a real model: no evaluation run has completed on this design. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
283
app/workflows/target_architecture.py
Normal file
283
app/workflows/target_architecture.py
Normal file
@@ -0,0 +1,283 @@
|
||||
"""The Target architecture: one explicit graph, established before code (ADR-0005).
|
||||
|
||||
Elements every component and the resource that realises it
|
||||
Relationships how Elements connect
|
||||
Checks the numbered, verifiable conditions each must meet, each traced
|
||||
to the requirement or design recommendation it comes from
|
||||
|
||||
This module is pure: it parses the graph, states what is wrong with it, renders it as
|
||||
a diagram, and says whether the Requirements chain through it is complete.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterable, Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
GRAPH_ATTACHMENT = "target-architecture.json"
|
||||
DIAGRAM_ATTACHMENT = "architecture.mmd"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Element:
|
||||
id: str
|
||||
name: str
|
||||
product: str
|
||||
resource_type: str
|
||||
component: str | None = None # None for a supporting Element, e.g. an identity
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Relationship:
|
||||
id: str
|
||||
source: str # "from" in the data
|
||||
target: str # "to" in the data
|
||||
kind: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Check:
|
||||
id: str
|
||||
applies_to: str # an Element or Relationship id
|
||||
statement: str
|
||||
source: str # a requirement or design recommendation id
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class NotApplicable:
|
||||
recommendation: str
|
||||
reason: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TargetArchitecture:
|
||||
elements: tuple[Element, ...]
|
||||
relationships: tuple[Relationship, ...]
|
||||
checks: tuple[Check, ...]
|
||||
not_applicable: tuple[NotApplicable, ...] = ()
|
||||
|
||||
@property
|
||||
def check_ids(self) -> tuple[str, ...]:
|
||||
return tuple(check.id for check in self.checks)
|
||||
|
||||
def summary(self) -> dict[str, Any]:
|
||||
"""What a user approving the design is told about the graph."""
|
||||
return {
|
||||
"elements": len(self.elements),
|
||||
"relationships": len(self.relationships),
|
||||
"checks": len(self.checks),
|
||||
"not_applicable": [
|
||||
{"recommendation": item.recommendation, "reason": item.reason}
|
||||
for item in self.not_applicable
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
class GraphError(ValueError):
|
||||
"""The graph is not well-formed; `problems` says how, one entry per fault."""
|
||||
|
||||
def __init__(self, problems: Sequence[str]) -> None:
|
||||
super().__init__("; ".join(problems))
|
||||
self.problems = tuple(problems)
|
||||
|
||||
|
||||
def parse_graph(text: str) -> TargetArchitecture:
|
||||
"""Parse target-architecture.json, or raise GraphError naming every fault."""
|
||||
name = GRAPH_ATTACHMENT
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
raise GraphError([f"{name}: not valid JSON ({exc})"]) from exc
|
||||
if not isinstance(data, dict):
|
||||
raise GraphError(
|
||||
[f"{name}: must be an object with elements, relationships and checks"]
|
||||
)
|
||||
|
||||
problems: list[str] = []
|
||||
|
||||
def items(key: str, required: Sequence[str]) -> list[dict[str, str]]:
|
||||
raw = data.get(key, [])
|
||||
if not isinstance(raw, list):
|
||||
problems.append(f"{name}.{key}: must be a list")
|
||||
return []
|
||||
accepted = []
|
||||
for index, item in enumerate(raw):
|
||||
where = f"{name}.{key}[{index}]"
|
||||
if not isinstance(item, dict):
|
||||
problems.append(f"{where}: must be an object")
|
||||
continue
|
||||
missing = [
|
||||
field
|
||||
for field in required
|
||||
if not isinstance(item.get(field), str) or not item[field].strip()
|
||||
]
|
||||
if missing:
|
||||
problems.append(f"{where}: needs a non-empty {', '.join(missing)}")
|
||||
continue
|
||||
accepted.append(item)
|
||||
return accepted
|
||||
|
||||
elements = tuple(
|
||||
Element(
|
||||
id=item["id"],
|
||||
name=item["name"],
|
||||
product=item["product"],
|
||||
resource_type=item["resource_type"],
|
||||
component=item.get("component") or None,
|
||||
)
|
||||
for item in items("elements", ("id", "name", "product", "resource_type"))
|
||||
)
|
||||
relationships = tuple(
|
||||
Relationship(item["id"], item["from"], item["to"], item["kind"])
|
||||
for item in items("relationships", ("id", "from", "to", "kind"))
|
||||
)
|
||||
checks = tuple(
|
||||
Check(item["id"], item["applies_to"], item["statement"], item["source"])
|
||||
for item in items("checks", ("id", "applies_to", "statement", "source"))
|
||||
)
|
||||
not_applicable = tuple(
|
||||
NotApplicable(item["recommendation"], item["reason"])
|
||||
for item in items("not_applicable", ("recommendation", "reason"))
|
||||
)
|
||||
|
||||
if not elements and not problems:
|
||||
problems.append(f"{name}.elements: the graph has no Elements")
|
||||
|
||||
seen: set[str] = set()
|
||||
ids = [thing.id for group in (elements, relationships, checks) for thing in group]
|
||||
for identifier in ids:
|
||||
if identifier in seen:
|
||||
problems.append(f"{name}: id {identifier} is used more than once")
|
||||
seen.add(identifier)
|
||||
|
||||
element_ids = {element.id for element in elements}
|
||||
for relationship in relationships:
|
||||
for end, value in (("from", relationship.source), ("to", relationship.target)):
|
||||
if value not in element_ids:
|
||||
problems.append(
|
||||
f"{name}: Relationship {relationship.id} {end} {value}, "
|
||||
"which is not an Element"
|
||||
)
|
||||
targets = element_ids | {relationship.id for relationship in relationships}
|
||||
for check in checks:
|
||||
if check.applies_to not in targets:
|
||||
problems.append(
|
||||
f"{name}: Check {check.id} applies to {check.applies_to}, "
|
||||
"which is not an Element or Relationship"
|
||||
)
|
||||
checked = {check.applies_to for check in checks}
|
||||
for element in elements:
|
||||
if element.id not in checked:
|
||||
problems.append(f"{name}: Element {element.id} has no Check")
|
||||
|
||||
if problems:
|
||||
raise GraphError(problems)
|
||||
return TargetArchitecture(elements, relationships, checks, not_applicable)
|
||||
|
||||
|
||||
# --- the Requirements chain through the graph ----------------------------------------
|
||||
|
||||
|
||||
def chain_gaps(
|
||||
graph: TargetArchitecture,
|
||||
*,
|
||||
requirements: Sequence[Mapping[str, Any]],
|
||||
components: Sequence[Mapping[str, Any]],
|
||||
products: Sequence[Mapping[str, Any]],
|
||||
recommendations: Sequence[Mapping[str, Any]],
|
||||
) -> tuple[str, ...]:
|
||||
"""Every place the Requirements chain stops before reaching a Check.
|
||||
|
||||
A functional requirement is carried by a component that has an Element, or by a
|
||||
Check of its own. A non-functional requirement and a design recommendation are
|
||||
each a constraint, so each must be the source of a Check (a recommendation may
|
||||
instead be marked not applicable, with a reason).
|
||||
"""
|
||||
gaps: list[str] = []
|
||||
requirement_ids = {item["id"] for item in requirements}
|
||||
recommendation_ids = {item["id"] for item in recommendations}
|
||||
sources = {check.source for check in graph.checks}
|
||||
realised = {element.component for element in graph.elements if element.component}
|
||||
|
||||
for check in graph.checks:
|
||||
if check.source not in requirement_ids | recommendation_ids:
|
||||
gaps.append(
|
||||
f"Check {check.id} has source {check.source}, which is not a "
|
||||
"requirement or design recommendation"
|
||||
)
|
||||
for element in graph.elements:
|
||||
if element.component and element.component not in {c["id"] for c in components}:
|
||||
gaps.append(
|
||||
f"Element {element.id} realises {element.component}, "
|
||||
"which is not a component"
|
||||
)
|
||||
|
||||
for component in components:
|
||||
if component["id"] not in realised:
|
||||
gaps.append(f"Component {component['id']} has no Element")
|
||||
for requirement in requirements:
|
||||
if requirement["id"] in sources:
|
||||
continue
|
||||
served = any(
|
||||
requirement["id"] in component.get("requirements", ())
|
||||
and component["id"] in realised
|
||||
for component in components
|
||||
)
|
||||
if requirement.get("kind") == "functional" and served:
|
||||
continue
|
||||
gaps.append(f"Requirement {requirement['id']} has no Check")
|
||||
for selection in products:
|
||||
used = any(
|
||||
element.component == selection["component"]
|
||||
and element.product == selection["product"]
|
||||
for element in graph.elements
|
||||
)
|
||||
if not used:
|
||||
gaps.append(
|
||||
f"Product {selection['product']} selected for "
|
||||
f"{selection['component']} appears on no Element"
|
||||
)
|
||||
excused = {item.recommendation for item in graph.not_applicable}
|
||||
for item in graph.not_applicable:
|
||||
if item.recommendation not in recommendation_ids:
|
||||
gaps.append(
|
||||
f"not_applicable names {item.recommendation}, "
|
||||
"which is not a design recommendation"
|
||||
)
|
||||
for recommendation in recommendations:
|
||||
if recommendation["id"] not in sources | excused:
|
||||
gaps.append(f"Recommendation {recommendation['id']} has no Check")
|
||||
return tuple(gaps)
|
||||
|
||||
|
||||
# --- the diagram is a view of the graph ----------------------------------------------
|
||||
|
||||
_UNSAFE = re.compile(r'["\[\]{}()<>|`#;]')
|
||||
|
||||
|
||||
def _label(*parts: str) -> str:
|
||||
return "<br/>".join(_UNSAFE.sub(" ", part).strip() for part in parts if part)
|
||||
|
||||
|
||||
def _node_ids(ids: Iterable[str]) -> dict[str, str]:
|
||||
"""Mermaid-safe node ids; the graph's own ids may hold characters Mermaid rejects."""
|
||||
return {identifier: f"n{index}" for index, identifier in enumerate(ids)}
|
||||
|
||||
|
||||
def render_mermaid(graph: TargetArchitecture) -> str:
|
||||
"""The architecture diagram: every Element and Relationship, exactly once."""
|
||||
nodes = _node_ids(element.id for element in graph.elements)
|
||||
lines = ["flowchart LR"]
|
||||
for element in graph.elements:
|
||||
lines.append(
|
||||
f' {nodes[element.id]}["{_label(element.name, element.product)}"]'
|
||||
)
|
||||
for relationship in graph.relationships:
|
||||
lines.append(
|
||||
f" {nodes[relationship.source]} -->|{_label(relationship.kind)}| "
|
||||
f"{nodes[relationship.target]}"
|
||||
)
|
||||
return "\n".join(lines) + "\n"
|
||||
Reference in New Issue
Block a user