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:
2026-10-07 13:59:09 +01:00
parent 7ee49ab352
commit e9246828b3
586 changed files with 5166 additions and 22432 deletions

View 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"