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

@@ -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)