Files
gcp_solution_architecture_a…/app/workflows/deliverables.py
Jonathan Boniface 545097530b
Some checks failed
validation / verify (push) Failing after 10s
feat: scoping is the first Phase, completed in conversation (iteration 9 step 2)
Every Execution now begins by agreeing the scope, before requirements.

- A new Phase and Deliverable, produced by a scope analyst with two tools:
  scope_read shows what is settled and what is not; scope_set records fields
  with where each value came from (the request, the customer's answer, or an
  assumption with its reason). Code checks each value against the catalogue.
- With someone present the analyst asks for what is missing; with nobody
  present it assumes it, visibly. With no spec it drafts one from the request.
  A value the customer stated in the file is changed only by their own answer.
- A submission cannot leave an essential field unknown. Code writes the
  completed spec, the data every later Specialist reads, and the information
  register, from what was recorded.
- The spec's status follows the Execution: under review, approved, then
  locked as a Baseline. A Change request starts from the delivered scope.
- The requirements analyst derives from the agreed scope and no longer asks
  for what it settles.

About 80 tests assumed requirements came first; tests/scoped.py runs scoping
ahead of a test's own script, and tests about order and counts are updated.
Not run with real models.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 18:17:32 +01:00

344 lines
13 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,
SCOPE_DATA_FILE,
SCOPE_FILE,
VERDICTS_FILE,
Upstream,
check_components,
check_implementation,
check_products,
check_recommendations,
check_requirements,
check_scope,
check_target_architecture,
check_verdicts,
graph_structure,
)
from app.workflows.changes import check_requirement_changes
from app.workflows.target_architecture import GRAPH_ATTACHMENT
class PhaseId(StrEnum):
# Scoping: what the customer wants and the facts a design depends on, agreed
# before requirements are derived from it (ADR-0008).
SCOPING = "scoping"
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):
SCOPE = "scope"
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, ...] = ()
# Which earlier Deliverables the Specialist reads whole. None means the ones it
# depends on. Every other input arrives as its data file alone: the ids the
# Requirements chain runs through, without the prose written around them.
reads_in_full: tuple[DeliverableKind, ...] | None = None
# The Deliverable whose files this Specialist's tools work on. Its own kind: the
# files are its working copy, kept across attempts and attached on submission.
# Another kind: a fresh copy of that Deliverable's files on every attempt.
working_copy: DeliverableKind | None = None
# What the Deliverable is written from, as one comparable value. When a Revision
# upstream leaves that value as it was, the last submission still stands and the
# Specialist is not run again.
written_from: Callable[[Upstream | None], str | None] | None = None
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.SCOPE,
PhaseId.SCOPING,
"scope-analyst",
sections=("Scope statement",),
# The completed scope spec, for people and for reuse; and what every
# later Specialist reads of it.
attachments=(SCOPE_FILE, SCOPE_DATA_FILE),
),
DeliverableSpec(
_K.REQUIREMENTS,
PhaseId.REQUIREMENTS_DISCOVERY,
"requirements-analyst",
depends_on=(_K.SCOPE,),
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),
# The Specialist writes the reasoning and the graph. On submission the
# engine adds the Elements, Relationships and Checks tables to the content
# and architecture.mmd to the attachments, both rendered from the graph.
sections=("Design rationale",),
attachments=(GRAPH_ATTACHMENT,),
),
DeliverableSpec(
_K.ARCHITECTURE_DESCRIPTION,
PhaseId.SOLUTION_IMPLEMENTATION,
"describer",
depends_on=(_K.TARGET_ARCHITECTURE,),
sections=("Components", "Flow"),
# It describes the Elements and how they connect. A Revision that only
# adds or rewords Checks leaves it true.
written_from=graph_structure,
),
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,
),
# The graph is all the code is written from.
reads_in_full=(),
working_copy=_K.DEPLOYMENT_GUIDANCE,
),
DeliverableSpec(
_K.VALIDATION_RESULTS,
PhaseId.SOLUTION_VALIDATION,
"validator",
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
sections=("Deployment dry-run", "Architecture and policy analysis"),
attachments=(VERDICTS_FILE,),
working_copy=_K.DEPLOYMENT_GUIDANCE,
),
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",
),
# The guide is assembled from every Deliverable's prose.
reads_in_full=tuple(_K)[:-1],
),
)
}
# 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.SCOPE: (SCOPE_DATA_FILE, check_scope),
_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 dependencies_for(
kind: DeliverableKind, deliverables: Mapping[str, Mapping[str, object]]
) -> dict[str, dict[str, object]]:
"""What a Specialist is given of each Deliverable it works from.
A Deliverable read in full arrives as submitted. Any other arrives as its data
file alone, which is all the Requirements chain needs of it.
"""
spec = DEPENDENCY_GRAPH[kind]
in_full = spec.depends_on if spec.reads_in_full is None else spec.reads_in_full
given: dict[str, dict[str, object]] = {}
for dependency in inputs_of(kind):
deliverable = deliverables[dependency.value]
if dependency in in_full or dependency not in DATA_CHECKS:
given[dependency.value] = dict(deliverable)
continue
name = DATA_CHECKS[dependency][0]
attachments = deliverable.get("attachments")
files = attachments if isinstance(attachments, Mapping) else {}
given[dependency.value] = {
"attachments": {name: files[name]} if name in files else {}
}
return given
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,
baseline: Mapping[str, object] | 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. `baseline` is the Baseline's
version of this Deliverable in a Change request; with it, the account of what
changed is checked.
"""
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))
if (
baseline is not None
and kind is DeliverableKind.REQUIREMENTS
and attachments.get(REQUIREMENTS_FILE, "").strip()
and not missing
):
missing.extend(check_requirement_changes(attachments, baseline))
return tuple(missing)