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:
336
app/workflows/chain.py
Normal file
336
app/workflows/chain.py
Normal file
@@ -0,0 +1,336 @@
|
||||
"""The data files along the Requirements chain, and what each must hold (ADR-0005).
|
||||
|
||||
requirements.json requirements with ids
|
||||
components.json components, and the requirements each serves
|
||||
products.json the product selected for each component
|
||||
recommendations.json design recommendations with ids
|
||||
target-architecture.json the graph (see target_architecture.py)
|
||||
implementation.json which code satisfies each Check
|
||||
verdicts.json the validation verdict on each Check
|
||||
|
||||
Each checker returns what is wrong, one entry per fault, so a Specialist can fix it
|
||||
and submit again. `upstream` is the Deliverables a submission builds on, by kind; a
|
||||
link to one of them is checked only when it is there.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.workflows.target_architecture import (
|
||||
GRAPH_ATTACHMENT,
|
||||
GraphError,
|
||||
TargetArchitecture,
|
||||
chain_gaps,
|
||||
parse_graph,
|
||||
)
|
||||
|
||||
REQUIREMENTS_FILE = "requirements.json"
|
||||
COMPONENTS_FILE = "components.json"
|
||||
PRODUCTS_FILE = "products.json"
|
||||
RECOMMENDATIONS_FILE = "recommendations.json"
|
||||
IMPLEMENTATION_FILE = "implementation.json"
|
||||
VERDICTS_FILE = "verdicts.json"
|
||||
|
||||
REQUIREMENT_KINDS = ("functional", "non_functional")
|
||||
VERDICTS = ("pass", "fail", "not_verifiable")
|
||||
DRY_RUN_VERDICTS = ("pass", "fail", "not_run")
|
||||
|
||||
Upstream = Mapping[str, Mapping[str, Any]]
|
||||
|
||||
|
||||
def read_list(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
|
||||
"""An upstream data file as a list of objects; empty when absent or unreadable."""
|
||||
text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "")
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
return []
|
||||
return (
|
||||
[item for item in data if isinstance(item, dict)]
|
||||
if isinstance(data, list)
|
||||
else []
|
||||
)
|
||||
|
||||
|
||||
def read_graph(upstream: Upstream | None) -> TargetArchitecture | None:
|
||||
text = (
|
||||
((upstream or {}).get("target_architecture") or {})
|
||||
.get("attachments", {})
|
||||
.get(GRAPH_ATTACHMENT, "")
|
||||
)
|
||||
try:
|
||||
return parse_graph(text)
|
||||
except GraphError:
|
||||
return None
|
||||
|
||||
|
||||
def _objects(
|
||||
text: str, name: str, strings: Sequence[str], lists: Sequence[str] = ()
|
||||
) -> tuple[list[dict[str, Any]], list[str]]:
|
||||
"""The file's objects that have every required field, and what is wrong with it."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
return [], [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, list):
|
||||
return [], [f"{name}: must be a JSON list"]
|
||||
accepted, problems = [], []
|
||||
for index, item in enumerate(data):
|
||||
where = f"{name}[{index}]"
|
||||
if not isinstance(item, dict):
|
||||
problems.append(f"{where}: must be an object")
|
||||
continue
|
||||
missing = [
|
||||
field
|
||||
for field in strings
|
||||
if not isinstance(item.get(field), str) or not item[field].strip()
|
||||
]
|
||||
missing += [
|
||||
field
|
||||
for field in lists
|
||||
if not isinstance(item.get(field), list)
|
||||
or not all(isinstance(value, str) for value in item[field])
|
||||
]
|
||||
if missing:
|
||||
problems.append(f"{where}: needs {', '.join(missing)}")
|
||||
continue
|
||||
accepted.append(item)
|
||||
return accepted, problems
|
||||
|
||||
|
||||
def _repeated(
|
||||
items: Sequence[Mapping[str, Any]], name: str, key: str = "id"
|
||||
) -> list[str]:
|
||||
seen: set[str] = set()
|
||||
problems = []
|
||||
for item in items:
|
||||
if item[key] in seen:
|
||||
problems.append(f"{name}: {key} {item[key]} is used more than once")
|
||||
seen.add(item[key])
|
||||
return problems
|
||||
|
||||
|
||||
def check_requirements(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = REQUIREMENTS_FILE
|
||||
items, problems = _objects(attachments[name], name, ("id", "kind", "text"))
|
||||
problems += _repeated(items, name)
|
||||
problems += [
|
||||
f"{name}: {item['id']} kind must be one of {', '.join(REQUIREMENT_KINDS)}"
|
||||
for item in items
|
||||
if item["kind"] not in REQUIREMENT_KINDS
|
||||
]
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no requirements")
|
||||
return problems
|
||||
|
||||
|
||||
def check_components(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = COMPONENTS_FILE
|
||||
items, problems = _objects(
|
||||
attachments[name], name, ("id", "name"), ("requirements",)
|
||||
)
|
||||
problems += _repeated(items, name)
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no components")
|
||||
requirements = read_list(upstream, "requirements", REQUIREMENTS_FILE)
|
||||
if requirements:
|
||||
known = {item["id"] for item in requirements}
|
||||
served: set[str] = set()
|
||||
for item in items:
|
||||
served.update(item["requirements"])
|
||||
problems += [
|
||||
f"{name}: {item['id']} serves {reference}, which is not a requirement"
|
||||
for reference in item["requirements"]
|
||||
if reference not in known
|
||||
]
|
||||
problems += [
|
||||
f"{name}: functional requirement {item['id']} is served by no component"
|
||||
for item in requirements
|
||||
if item.get("kind") == "functional" and item["id"] not in served
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_products(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = PRODUCTS_FILE
|
||||
items, problems = _objects(attachments[name], name, ("component", "product"))
|
||||
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
|
||||
if components:
|
||||
known = {item["id"] for item in components}
|
||||
chosen = {item["component"] for item in items}
|
||||
problems += [
|
||||
f"{name}: {item['component']} is not a component"
|
||||
for item in items
|
||||
if item["component"] not in known
|
||||
]
|
||||
problems += [
|
||||
f"{name}: component {identifier} has no product selected"
|
||||
for identifier in sorted(known - chosen)
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_recommendations(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = RECOMMENDATIONS_FILE
|
||||
items, problems = _objects(
|
||||
attachments[name], name, ("id", "pillar", "text"), ("components",)
|
||||
)
|
||||
problems += _repeated(items, name)
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no recommendations")
|
||||
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
|
||||
if components:
|
||||
known = {item["id"] for item in components}
|
||||
problems += [
|
||||
f"{name}: {item['id']} names {reference}, which is not a component"
|
||||
for item in items
|
||||
for reference in item["components"]
|
||||
if reference not in known
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_target_architecture(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
try:
|
||||
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
|
||||
except GraphError as exc:
|
||||
return list(exc.problems)
|
||||
if upstream is None:
|
||||
return []
|
||||
return list(
|
||||
chain_gaps(
|
||||
graph,
|
||||
requirements=read_list(upstream, "requirements", REQUIREMENTS_FILE),
|
||||
components=read_list(upstream, "technical_decomposition", COMPONENTS_FILE),
|
||||
products=read_list(upstream, "product_selection", PRODUCTS_FILE),
|
||||
recommendations=read_list(
|
||||
upstream, "design_recommendations", RECOMMENDATIONS_FILE
|
||||
),
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def _covers_every_check(
|
||||
items: Sequence[Mapping[str, Any]], name: str, graph: TargetArchitecture | None
|
||||
) -> list[str]:
|
||||
problems = _repeated(items, name, "check")
|
||||
if graph is None:
|
||||
return problems
|
||||
given = {item["check"] for item in items}
|
||||
problems += [
|
||||
f"{name}: {identifier} is not a Check in the Target architecture"
|
||||
for identifier in sorted(given - set(graph.check_ids))
|
||||
]
|
||||
problems += [
|
||||
f"{name}: Check {identifier} is not accounted for"
|
||||
for identifier in graph.check_ids
|
||||
if identifier not in given
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_implementation(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = IMPLEMENTATION_FILE
|
||||
items, problems = _objects(attachments[name], name, ("check", "file", "address"))
|
||||
problems += _covers_every_check(items, name, read_graph(upstream))
|
||||
problems += [
|
||||
f"{name}: {item['check']} names {item['file']}, which is not attached"
|
||||
for item in items
|
||||
if item["file"] not in attachments
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_verdicts(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = VERDICTS_FILE
|
||||
try:
|
||||
data = json.loads(attachments[name])
|
||||
except ValueError as exc:
|
||||
return [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, dict):
|
||||
return [
|
||||
f"{name}: must be an object with dry_run, checks and proposed_additions"
|
||||
]
|
||||
problems: list[str] = []
|
||||
dry_run = data.get("dry_run")
|
||||
if (
|
||||
not isinstance(dry_run, dict)
|
||||
or dry_run.get("verdict") not in DRY_RUN_VERDICTS
|
||||
or not isinstance(dry_run.get("evidence"), str)
|
||||
or not dry_run["evidence"].strip()
|
||||
):
|
||||
problems.append(
|
||||
f"{name}.dry_run: needs a verdict ({', '.join(DRY_RUN_VERDICTS)}) and evidence"
|
||||
)
|
||||
items, faults = _objects(
|
||||
json.dumps(data.get("checks", [])),
|
||||
f"{name}.checks",
|
||||
("check", "verdict", "evidence"),
|
||||
)
|
||||
problems += faults
|
||||
problems += [
|
||||
f"{name}.checks: {item['check']} verdict must be one of {', '.join(VERDICTS)}"
|
||||
for item in items
|
||||
if item["verdict"] not in VERDICTS
|
||||
]
|
||||
problems += _covers_every_check(items, f"{name}.checks", read_graph(upstream))
|
||||
_, faults = _objects(
|
||||
json.dumps(data.get("proposed_additions", [])),
|
||||
f"{name}.proposed_additions",
|
||||
("statement", "applies_to", "reason"),
|
||||
)
|
||||
return problems + faults
|
||||
|
||||
|
||||
def validation_outcome(verdicts_text: str) -> dict[str, Any]:
|
||||
"""What a validation decided, for routing a Revision and for scoring.
|
||||
|
||||
Failed Checks are faults in the code. A Check that could not be verified and a
|
||||
proposed addition are gaps in the Target architecture.
|
||||
"""
|
||||
try:
|
||||
data = json.loads(verdicts_text)
|
||||
except ValueError:
|
||||
data = {}
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
checks = [item for item in data.get("checks", []) if isinstance(item, dict)]
|
||||
|
||||
def with_verdict(verdict: str) -> list[dict[str, Any]]:
|
||||
return [
|
||||
{"check": item.get("check"), "evidence": item.get("evidence")}
|
||||
for item in checks
|
||||
if item.get("verdict") == verdict
|
||||
]
|
||||
|
||||
dry_run = data.get("dry_run") if isinstance(data.get("dry_run"), dict) else {}
|
||||
return {
|
||||
"dry_run": dry_run,
|
||||
"passed": [
|
||||
item.get("check") for item in checks if item.get("verdict") == "pass"
|
||||
],
|
||||
"failed": with_verdict("fail"),
|
||||
"not_verifiable": with_verdict("not_verifiable"),
|
||||
"proposed_additions": [
|
||||
item
|
||||
for item in data.get("proposed_additions", [])
|
||||
if isinstance(item, dict)
|
||||
],
|
||||
}
|
||||
@@ -9,14 +9,34 @@ solution-guide template by suffix (e.g. "Products and features mapping" matches
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Mapping
|
||||
from collections.abc import Callable, Mapping
|
||||
from dataclasses import dataclass
|
||||
from enum import StrEnum
|
||||
|
||||
from app.workflows.chain import (
|
||||
COMPONENTS_FILE,
|
||||
IMPLEMENTATION_FILE,
|
||||
PRODUCTS_FILE,
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
VERDICTS_FILE,
|
||||
Upstream,
|
||||
check_components,
|
||||
check_implementation,
|
||||
check_products,
|
||||
check_recommendations,
|
||||
check_requirements,
|
||||
check_target_architecture,
|
||||
check_verdicts,
|
||||
)
|
||||
from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
||||
|
||||
|
||||
class PhaseId(StrEnum):
|
||||
REQUIREMENTS_DISCOVERY = "requirements_discovery"
|
||||
# Design: ends with the Target architecture, approved before any code is written.
|
||||
SOLUTION_ARCHITECTURE = "solution_architecture"
|
||||
SOLUTION_IMPLEMENTATION = "solution_implementation"
|
||||
SOLUTION_VALIDATION = "solution_validation"
|
||||
PACKAGING = "packaging"
|
||||
|
||||
@@ -28,9 +48,9 @@ class DeliverableKind(StrEnum):
|
||||
REQUIREMENTS = "requirements"
|
||||
TECHNICAL_DECOMPOSITION = "technical_decomposition"
|
||||
PRODUCT_SELECTION = "product_selection"
|
||||
ARCHITECTURE_DIAGRAM = "architecture_diagram"
|
||||
ARCHITECTURE_DESCRIPTION = "architecture_description"
|
||||
DESIGN_RECOMMENDATIONS = "design_recommendations"
|
||||
TARGET_ARCHITECTURE = "target_architecture"
|
||||
ARCHITECTURE_DESCRIPTION = "architecture_description"
|
||||
DEPLOYMENT_GUIDANCE = "deployment_guidance"
|
||||
VALIDATION_RESULTS = "validation_results"
|
||||
SOLUTION_GUIDE = "solution_guide"
|
||||
@@ -45,6 +65,13 @@ class DeliverableSpec:
|
||||
sections: tuple[str, ...] = ()
|
||||
attachments: tuple[str, ...] = ()
|
||||
|
||||
def contract(self) -> dict[str, list[str]]:
|
||||
"""What a submission must contain, as plain data for the Specialist's context."""
|
||||
return {
|
||||
"sections": list(self.sections),
|
||||
"attachments": list(self.attachments),
|
||||
}
|
||||
|
||||
|
||||
_K = DeliverableKind
|
||||
|
||||
@@ -61,12 +88,15 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"Current state",
|
||||
"Dependencies",
|
||||
),
|
||||
attachments=(REQUIREMENTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.TECHNICAL_DECOMPOSITION,
|
||||
PhaseId.REQUIREMENTS_DISCOVERY,
|
||||
"decomposer",
|
||||
depends_on=(_K.REQUIREMENTS,),
|
||||
sections=("Components",),
|
||||
attachments=(COMPONENTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.PRODUCT_SELECTION,
|
||||
@@ -74,19 +104,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"product-selector",
|
||||
depends_on=(_K.TECHNICAL_DECOMPOSITION,),
|
||||
sections=("Products and features mapping",),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DIAGRAM,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"diagrammer",
|
||||
depends_on=(_K.PRODUCT_SELECTION,),
|
||||
attachments=("architecture.mmd",),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DESCRIPTION,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"describer",
|
||||
depends_on=(_K.ARCHITECTURE_DIAGRAM, _K.PRODUCT_SELECTION),
|
||||
attachments=(PRODUCTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.DESIGN_RECOMMENDATIONS,
|
||||
@@ -101,17 +119,38 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"Performance efficiency",
|
||||
"Sustainability",
|
||||
),
|
||||
attachments=(RECOMMENDATIONS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.TARGET_ARCHITECTURE,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"target-architect",
|
||||
depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS),
|
||||
sections=("Elements", "Relationships", "Checks"),
|
||||
# The engine adds architecture.mmd, rendered from the graph, on submission.
|
||||
attachments=(GRAPH_ATTACHMENT,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DESCRIPTION,
|
||||
PhaseId.SOLUTION_IMPLEMENTATION,
|
||||
"describer",
|
||||
depends_on=(_K.TARGET_ARCHITECTURE,),
|
||||
sections=("Components", "Flow"),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.DEPLOYMENT_GUIDANCE,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
PhaseId.SOLUTION_IMPLEMENTATION,
|
||||
"iac-author",
|
||||
depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS),
|
||||
depends_on=(_K.TARGET_ARCHITECTURE,),
|
||||
sections=(
|
||||
"Deployment prerequisites",
|
||||
"Step-by-step deployment instructions",
|
||||
),
|
||||
attachments=("terraform/main.tf", "terraform/variables.tf"),
|
||||
attachments=(
|
||||
"terraform/main.tf",
|
||||
"terraform/variables.tf",
|
||||
IMPLEMENTATION_FILE,
|
||||
),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.VALIDATION_RESULTS,
|
||||
@@ -119,6 +158,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"validator",
|
||||
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
|
||||
sections=("Deployment dry-run", "Architecture and policy analysis"),
|
||||
attachments=(VERDICTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.SOLUTION_GUIDE,
|
||||
@@ -139,6 +179,20 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
)
|
||||
}
|
||||
|
||||
# What each data file along the Requirements chain must hold, checked at submission.
|
||||
DATA_CHECKS: Mapping[
|
||||
DeliverableKind,
|
||||
tuple[str, Callable[[Mapping[str, str], Upstream | None], list[str]]],
|
||||
] = {
|
||||
_K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements),
|
||||
_K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components),
|
||||
_K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products),
|
||||
_K.DESIGN_RECOMMENDATIONS: (RECOMMENDATIONS_FILE, check_recommendations),
|
||||
_K.TARGET_ARCHITECTURE: (GRAPH_ATTACHMENT, check_target_architecture),
|
||||
_K.DEPLOYMENT_GUIDANCE: (IMPLEMENTATION_FILE, check_implementation),
|
||||
_K.VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts),
|
||||
}
|
||||
|
||||
|
||||
def inputs_of(kind: DeliverableKind) -> tuple[DeliverableKind, ...]:
|
||||
"""The Deliverables a Specialist works from, in graph order.
|
||||
@@ -179,9 +233,16 @@ def _normalise(text: str) -> str:
|
||||
|
||||
|
||||
def check_submission(
|
||||
kind: DeliverableKind, content: str, attachments: Mapping[str, str]
|
||||
kind: DeliverableKind,
|
||||
content: str,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Upstream | None = None,
|
||||
) -> tuple[str, ...]:
|
||||
"""Return what a submission lacks against its contract; empty means it's complete."""
|
||||
"""Return what a submission lacks against its contract; empty means it's complete.
|
||||
|
||||
`upstream` is the Deliverables this one builds on, by kind. With it, the links
|
||||
along the Requirements chain are checked too.
|
||||
"""
|
||||
if not content.strip():
|
||||
return ("content: must not be empty",)
|
||||
|
||||
@@ -195,4 +256,10 @@ def check_submission(
|
||||
for name in spec.attachments:
|
||||
if name not in attachments:
|
||||
missing.append(f"attachment: {name}")
|
||||
elif not attachments[name].strip():
|
||||
missing.append(f"attachment: {name} must not be empty")
|
||||
if kind in DATA_CHECKS:
|
||||
name, check = DATA_CHECKS[kind]
|
||||
if attachments.get(name, "").strip():
|
||||
missing.extend(check(attachments, upstream))
|
||||
return tuple(missing)
|
||||
|
||||
@@ -18,7 +18,7 @@ from typing import Any, cast
|
||||
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
|
||||
from app.nodes.execution_nodes import make_execution_nodes
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import ExecutionState
|
||||
@@ -32,6 +32,8 @@ def build_execution_graph(
|
||||
output_root: Path,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
) -> StateGraph:
|
||||
nodes = make_execution_nodes(
|
||||
runtime=runtime,
|
||||
@@ -40,6 +42,8 @@ def build_execution_graph(
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
limiter=limiter,
|
||||
skill_versions=skill_versions,
|
||||
)
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
|
||||
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