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>
266 lines
9.0 KiB
Python
266 lines
9.0 KiB
Python
"""The dependency graph of Deliverables, grouped into Phases.
|
|
|
|
This is the only place Phases, Deliverables and Dependencies are declared. Section
|
|
names are provider-neutral; they match the numbered headings of a Cloud provider's
|
|
solution-guide template by suffix (e.g. "Products and features mapping" matches
|
|
"4.1. Google Cloud products and features mapping").
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
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"
|
|
|
|
|
|
PHASE_ORDER: tuple[PhaseId, ...] = tuple(PhaseId)
|
|
|
|
|
|
class DeliverableKind(StrEnum):
|
|
REQUIREMENTS = "requirements"
|
|
TECHNICAL_DECOMPOSITION = "technical_decomposition"
|
|
PRODUCT_SELECTION = "product_selection"
|
|
DESIGN_RECOMMENDATIONS = "design_recommendations"
|
|
TARGET_ARCHITECTURE = "target_architecture"
|
|
ARCHITECTURE_DESCRIPTION = "architecture_description"
|
|
DEPLOYMENT_GUIDANCE = "deployment_guidance"
|
|
VALIDATION_RESULTS = "validation_results"
|
|
SOLUTION_GUIDE = "solution_guide"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class DeliverableSpec:
|
|
kind: DeliverableKind
|
|
phase: PhaseId
|
|
specialist: str
|
|
depends_on: tuple[DeliverableKind, ...] = ()
|
|
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
|
|
|
|
DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
|
spec.kind: spec
|
|
for spec in (
|
|
DeliverableSpec(
|
|
_K.REQUIREMENTS,
|
|
PhaseId.REQUIREMENTS_DISCOVERY,
|
|
"requirements-analyst",
|
|
sections=(
|
|
"Functional requirements",
|
|
"Non-functional requirements",
|
|
"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,
|
|
PhaseId.SOLUTION_ARCHITECTURE,
|
|
"product-selector",
|
|
depends_on=(_K.TECHNICAL_DECOMPOSITION,),
|
|
sections=("Products and features mapping",),
|
|
attachments=(PRODUCTS_FILE,),
|
|
),
|
|
DeliverableSpec(
|
|
_K.DESIGN_RECOMMENDATIONS,
|
|
PhaseId.SOLUTION_ARCHITECTURE,
|
|
"design-advisor",
|
|
depends_on=(_K.PRODUCT_SELECTION, _K.REQUIREMENTS),
|
|
sections=(
|
|
"Security, privacy, and compliance",
|
|
"Reliability",
|
|
"Operational excellence",
|
|
"Cost optimization",
|
|
"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_IMPLEMENTATION,
|
|
"iac-author",
|
|
depends_on=(_K.TARGET_ARCHITECTURE,),
|
|
sections=(
|
|
"Deployment prerequisites",
|
|
"Step-by-step deployment instructions",
|
|
),
|
|
attachments=(
|
|
"terraform/main.tf",
|
|
"terraform/variables.tf",
|
|
IMPLEMENTATION_FILE,
|
|
),
|
|
),
|
|
DeliverableSpec(
|
|
_K.VALIDATION_RESULTS,
|
|
PhaseId.SOLUTION_VALIDATION,
|
|
"validator",
|
|
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
|
|
sections=("Deployment dry-run", "Architecture and policy analysis"),
|
|
attachments=(VERDICTS_FILE,),
|
|
),
|
|
DeliverableSpec(
|
|
_K.SOLUTION_GUIDE,
|
|
PhaseId.PACKAGING,
|
|
"packager",
|
|
depends_on=(_K.VALIDATION_RESULTS,),
|
|
sections=(
|
|
"Executive summary and workload overview",
|
|
"Requirements and current state",
|
|
"Technical decomposition of the workload",
|
|
"Proposed solution architecture",
|
|
"Design and configuration recommendations",
|
|
"Deployment guidance",
|
|
"Validation plan",
|
|
"References",
|
|
),
|
|
),
|
|
)
|
|
}
|
|
|
|
# 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.
|
|
|
|
Every Deliverable in an earlier Phase (all approved by the time `kind` is ready),
|
|
plus everything `kind` depends on, directly or not, within its own Phase.
|
|
"""
|
|
spec = DEPENDENCY_GRAPH[kind]
|
|
earlier_phases = PHASE_ORDER[: PHASE_ORDER.index(spec.phase)]
|
|
upstream: set[DeliverableKind] = set()
|
|
frontier = set(DEPENDENCY_GRAPH[kind].depends_on)
|
|
while frontier:
|
|
upstream |= frontier
|
|
frontier = {
|
|
dependency
|
|
for item in frontier
|
|
for dependency in DEPENDENCY_GRAPH[item].depends_on
|
|
} - upstream
|
|
return tuple(
|
|
candidate
|
|
for candidate, candidate_spec in DEPENDENCY_GRAPH.items()
|
|
if candidate in upstream or candidate_spec.phase in earlier_phases
|
|
)
|
|
|
|
|
|
def deliverables_in(phase: PhaseId) -> tuple[DeliverableKind, ...]:
|
|
return tuple(kind for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase is phase)
|
|
|
|
|
|
_HEADING = re.compile(r"^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$", re.MULTILINE)
|
|
_NUMBERING = re.compile(r"^\d+(?:\.\d+)*\.?\s+")
|
|
_TRAILING = re.compile(r"[\s:.\-–—]+$")
|
|
|
|
|
|
def _normalise(text: str) -> str:
|
|
text = _NUMBERING.sub("", text.strip().lower())
|
|
return " ".join(_TRAILING.sub("", text).split())
|
|
|
|
|
|
def check_submission(
|
|
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.
|
|
|
|
`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",)
|
|
|
|
spec = DEPENDENCY_GRAPH[kind]
|
|
headings = [_normalise(match) for match in _HEADING.findall(content)]
|
|
missing = []
|
|
for section in spec.sections:
|
|
required = _normalise(section)
|
|
if not any(h == required or h.endswith(" " + required) for h in headings):
|
|
missing.append(f"section: {section}")
|
|
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)
|