A caller restates a request to say how requirements have changed, naming a completed Execution of the same Customer case as the Baseline. - app/baseline.py reads a Baseline from its files and refuses one that does not exist, did not complete or belongs to another case, before anything runs or is recorded. A Baseline is never modified. - Requirements carry a change (unchanged, added, changed, removed) and a reason. Submission is refused when a Baseline requirement disappears, an id is reused, or an unchanged requirement's text differs. A removed requirement stays on record and asks nothing downstream. - Each Specialist starts from its delivered version; the graph and the code are its working copy, and the description is carried over when the design's shape is the same. - app/workflows/changes.py compares versions by id and traces what each changed requirement reaches; anything else that changed is listed as unrequested. Approvals show the change for their Phase, and changes.json is written with the full Deliverables. - Intake no longer starts a message read as a change: it names the Execution to give as the Baseline. - A fifth evaluation case runs a request and then a change to it, with four checks that the change is recorded, reaches Checks, stays contained and costs less than its Baseline. Tested with scripted agents only; no Change request has run with real models. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
326 lines
12 KiB
Python
326 lines
12 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,
|
|
graph_structure,
|
|
)
|
|
from app.workflows.changes import check_requirement_changes
|
|
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, ...] = ()
|
|
# 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.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),
|
|
# 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.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)
|