Solution architecture outcome pattern: agent and its MCP servers
Some checks failed
check agents / check (push) Failing after 13s

The cp1-solution-architecture-agent and the sa-aws/azure/gcp-cloud MCP servers, a separate
stream from the individual and sub-agent patterns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-05 22:13:25 +00:00
parent 8bb62a4a42
commit bc84ee4df6
267 changed files with 44287 additions and 45 deletions

View File

@@ -0,0 +1,546 @@
"""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.core.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"
SCOPE_FILE = "scope.yaml" # the completed scope spec
SCOPE_DATA_FILE = "scope.json" # what every Specialist reads of it
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.
An entry a Change request marked removed is left out: it stays in the file as
the record of what was dropped, and asks nothing of what follows.
"""
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) and item.get("change") != "removed"
]
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 graph_structure(upstream: Upstream | None) -> str | None:
"""The Target architecture's Elements and Relationships, as one comparable value.
What a Deliverable written from the shape of the design, and not from its
Checks, was written from. None when there is no readable graph.
"""
graph = read_graph(upstream)
if graph is None:
return None
return json.dumps(
{
"elements": [
[e.id, e.name, e.product, e.resource_type, e.component]
for e in graph.elements
],
"relationships": [
[r.id, r.source, r.target, r.kind] for r in graph.relationships
],
},
sort_keys=True,
)
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 conditions_of(item: Mapping[str, Any]) -> tuple[str, ...]:
"""The separate things a requirement or recommendation asks for.
Each is one statement that a Check can verify on its own. An item written before
conditions were listed is read as one condition: its whole text.
"""
listed = item.get("conditions")
if isinstance(listed, list):
conditions = tuple(
c.strip() for c in listed if isinstance(c, str) and c.strip()
)
if conditions:
return conditions
text = item.get("text")
return (text.strip(),) if isinstance(text, str) and text.strip() else ()
OUTSIDE_CODE = "outside_code"
def outside_code_of(item: Mapping[str, Any]) -> tuple[str, ...]:
"""What a requirement asks for that infrastructure code cannot show: an outcome
measured in operation, application behaviour, or a process people follow."""
listed = item.get(OUTSIDE_CODE)
if not isinstance(listed, list):
return ()
return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip())
def _lacking_conditions(items: Sequence[Mapping[str, Any]], name: str) -> list[str]:
"""A constraint must say, one by one, what would have to be true for it to be met:
under `conditions` what infrastructure code can show, under `outside_code` what
it cannot. At least one of the two has an entry."""
problems = []
for item in items:
listed = item.get("conditions")
outside = item.get(OUTSIDE_CODE, [])
well_formed = all(
isinstance(group, list)
and all(isinstance(c, str) and c.strip() for c in group)
for group in (listed, outside)
)
if not well_formed or not (listed or outside):
problems.append(
f"{name}: {item['id']} needs `conditions`: a list with one entry "
"for each separate thing it asks for that infrastructure code can "
f"show (and `{OUTSIDE_CODE}` for what it cannot)"
)
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")
problems += _lacking_conditions(
[item for item in items if item["kind"] == "non_functional"], name
)
problems += _carries_the_scope(items, name, upstream)
return problems
def agreed_scope(upstream: Upstream | None) -> dict[str, Any]:
"""The agreed scope, as every Specialist reads it; empty when there is none."""
text = (
((upstream or {}).get("scope") or {})
.get("attachments", {})
.get(SCOPE_DATA_FILE, "")
)
try:
data = json.loads(text) if text else {}
except ValueError:
return {}
return data if isinstance(data, dict) else {}
def sources_of(item: Mapping[str, Any]) -> tuple[str, ...]:
"""What a requirement comes from: the customer's own requirement ids and the
scope spec's fields, as its `from` lists them."""
listed = item.get("from")
return tuple(str(s) for s in listed) if isinstance(listed, list) else ()
def _carries_the_scope(
items: Sequence[Mapping[str, Any]], name: str, upstream: Upstream | None
) -> list[str]:
"""What the customer stated has to reach the requirements, by name (ADR-0008).
Each requirement the customer wrote, and each choice they stated that a design
must honour, is named in the `from` of a requirement. A choice is carried by a
non-functional requirement with a condition, so the Target architecture owes it
a Check. Before this a stated topology could be named in a design and not built:
case 08 on 2026-10-11 passed all 101 Checks with no Check asking for it.
"""
scope = agreed_scope(upstream)
if not scope:
return []
stated = scope.get("stated") or {}
theirs = [
str(entry.get("id"))
for entry in ((stated.get("intent") or {}).get("requirements") or [])
if isinstance(entry, Mapping) and entry.get("id")
]
binding = [str(path) for path in scope.get("binding") or []]
cited = {source for item in items for source in sources_of(item)}
problems = [
f"{name}: the customer's requirement {reference} is covered by no "
"requirement; name it in the `from` of the one that covers it"
for reference in theirs
if reference not in cited
]
problems += [
f"{name}: the customer stated {path} and no requirement carries it; add a "
f"non-functional requirement whose `from` names {path}, with the condition "
"that shows it was honoured"
for path in binding
if path not in cited
]
for item in items:
carried = [source for source in sources_of(item) if source in binding]
if carried and (
item.get("kind") != "non_functional" or not conditions_of_listed(item)
):
problems.append(
f"{name}: {item.get('id')} carries {', '.join(carried)}, a choice "
"the customer stated; it must be non_functional with at least one "
"entry in `conditions`, so the design is checked against it"
)
return problems
def conditions_of_listed(item: Mapping[str, Any]) -> tuple[str, ...]:
"""The conditions a requirement lists outright, with no fallback to its text."""
listed = item.get("conditions")
if not isinstance(listed, list):
return ()
return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip())
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")
problems += _lacking_conditions(items, name)
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 _split_implementation(text: str, name: str) -> tuple[str, str]:
"""The entries that say where a Check is met, and those that say it cannot be."""
try:
data = json.loads(text)
except ValueError:
return text, "[]"
if not isinstance(data, list):
return text, "[]"
cannot = [
item for item in data if isinstance(item, dict) and "unimplementable" in item
]
met = [item for item in data if item not in cannot]
return json.dumps(met), json.dumps(cannot)
def check_scope(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
"""The scope a Specialist reads: what the customer stated, what was left to the
agent, and what is unknown."""
name = SCOPE_DATA_FILE
try:
data = json.loads(attachments[name])
except ValueError as exc:
return [f"{name}: not valid JSON ({exc})"]
if not isinstance(data, dict) or not isinstance(data.get("stated"), dict):
return [f"{name}: must be an object with what the customer stated"]
return []
def check_implementation(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = IMPLEMENTATION_FILE
met_text, cannot_text = _split_implementation(attachments[name], name)
met, problems = _objects(met_text, name, ("check", "file", "address"))
cannot, faults = _objects(cannot_text, name, ("check", "unimplementable"))
problems += faults
problems += _covers_every_check([*met, *cannot], name, read_graph(upstream))
problems += [
f"{name}: {item['check']} names {item['file']}, which is not attached"
for item in met
if item["file"] not in attachments
]
return problems
def unimplementable_checks(implementation_text: str) -> list[dict[str, str]]:
"""The Checks the code's author found cannot be met as written, with the reason.
Each is a fault in the Target architecture, not in the code: the Check names
something the resource does not have.
"""
_, cannot_text = _split_implementation(implementation_text, IMPLEMENTATION_FILE)
cannot, _ = _objects(cannot_text, IMPLEMENTATION_FILE, ("check", "unimplementable"))
return [
{"check": item["check"], "reason": item["unimplementable"]} for item in cannot
]
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)
],
}

View File

@@ -0,0 +1,326 @@
"""What a Change request changed against its Baseline (ADR-0006).
Ids are stable from one version of a Customer case's architecture to the next: a
requirement, component, recommendation, Element, Relationship or Check that still
holds keeps its id. That is what lets code, with no model, say what was added, what
changed and what was removed; trace from each changed requirement to everything it
reaches; and list apart anything that changed without being reached. Nobody asked
for those, so a reader should see them as such.
This module is pure: data in, data out.
"""
from __future__ import annotations
import json
from collections.abc import Mapping, Sequence
from typing import Any
from app.core.chain import (
COMPONENTS_FILE,
RECOMMENDATIONS_FILE,
REQUIREMENTS_FILE,
)
from app.core.target_architecture import GRAPH_ATTACHMENT
CHANGES_FILE = "changes.json"
UNCHANGED, ADDED, CHANGED, REMOVED = "unchanged", "added", "changed", "removed"
CHANGE_KINDS = (UNCHANGED, ADDED, CHANGED, REMOVED)
Deliverables = Mapping[str, Mapping[str, Any]]
def _items(deliverables: Deliverables | None, kind: str, name: str) -> list[dict]:
"""A data file as a list of objects, removed requirements included."""
text = ((deliverables 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 _graph(deliverables: Deliverables | None) -> dict[str, list[dict]]:
text = (
((deliverables or {}).get("target_architecture") or {})
.get("attachments", {})
.get(GRAPH_ATTACHMENT, "")
)
try:
data = json.loads(text)
except ValueError:
data = {}
if not isinstance(data, dict):
data = {}
return {
key: [item for item in data.get(key, []) if isinstance(item, dict)]
for key in ("elements", "relationships", "checks")
}
# --- the requirements say what changed --------------------------------------------------
def check_requirement_changes(
attachments: Mapping[str, str], baseline: Mapping[str, Any] | None
) -> list[str]:
"""What is wrong with a Change request's requirements.json against the Baseline's.
Every requirement carries a `change`. One that still holds keeps its id and is
`unchanged`, with its text as it was. One that differs is `changed`; one no
longer wanted stays in the list as `removed`; a new one takes a new id and is
`added`. Everything but `unchanged` says why.
"""
name = REQUIREMENTS_FILE
before = {
item["id"]: item
for item in _items({"requirements": baseline or {}}, "requirements", name)
if isinstance(item.get("id"), str) and item.get("change") != REMOVED
}
revised = _items(
{"requirements": {"attachments": attachments}}, "requirements", name
)
problems: list[str] = []
seen = set()
for item in revised:
identifier = item.get("id")
if not isinstance(identifier, str):
continue
seen.add(identifier)
change = item.get("change")
if change not in CHANGE_KINDS:
problems.append(
f"{name}: {identifier} needs a `change`: one of "
f"{', '.join(CHANGE_KINDS)}"
)
continue
reason = item.get("reason")
if change != UNCHANGED and not (isinstance(reason, str) and reason.strip()):
problems.append(f"{name}: {identifier} is {change} and needs a `reason`")
if change == ADDED and identifier in before:
problems.append(
f"{name}: {identifier} is marked added, but the Baseline has that "
"id; a new requirement takes a new id"
)
if change != ADDED and identifier not in before:
problems.append(
f"{name}: {identifier} is marked {change}, but the Baseline has no "
"such requirement; mark a new one added"
)
if (
change == UNCHANGED
and identifier in before
and _text(item) != _text(before[identifier])
):
problems.append(
f"{name}: {identifier} is marked unchanged, but its text differs "
"from the Baseline's; restore it or mark it changed"
)
problems += [
f"{name}: Baseline requirement {identifier} is missing; keep it, or keep it "
"marked removed with the reason"
for identifier in before
if identifier not in seen
]
if revised and all(item.get("change") == UNCHANGED for item in revised):
problems.append(
f"{name}: nothing is marked added, changed or removed; a Change request "
"changes at least one requirement"
)
return problems
def _text(item: Mapping[str, Any]) -> str:
return " ".join(str(item.get("text", "")).split())
def requirement_changes(deliverables: Deliverables | None) -> list[dict[str, str]]:
"""The requirements a Change request added, changed or removed, with the reason."""
return [
{
"id": str(item.get("id")),
"change": str(item["change"]),
"reason": str(item.get("reason", "")),
"text": str(item.get("text", "")),
}
for item in _items(deliverables, "requirements", REQUIREMENTS_FILE)
if item.get("change") in (ADDED, CHANGED, REMOVED)
]
# --- comparing two versions -------------------------------------------------------------
def _compare(
before: Sequence[Mapping[str, Any]],
after: Sequence[Mapping[str, Any]] | None,
key: str = "id",
ignore: Sequence[str] = ("change", "reason"),
) -> dict[str, list[str]]:
"""Ids added, changed and removed between two lists of objects.
`after` is None while the revised Deliverable has not been produced: nothing
has changed yet, which is not the same as everything having been removed.
"""
if after is None:
return {ADDED: [], CHANGED: [], REMOVED: []}
def body(item: Mapping[str, Any]) -> dict[str, Any]:
return {name: value for name, value in item.items() if name not in ignore}
old = {str(item.get(key)): body(item) for item in before if item.get(key)}
new = {str(item.get(key)): body(item) for item in after if item.get(key)}
return {
ADDED: [identifier for identifier in new if identifier not in old],
CHANGED: [
identifier
for identifier in new
if identifier in old and new[identifier] != old[identifier]
],
REMOVED: [identifier for identifier in old if identifier not in new],
}
def reach(
changed: Sequence[str],
components: Sequence[Mapping[str, Any]],
recommendations_changed: Sequence[str],
graph: Mapping[str, Sequence[Mapping[str, Any]]],
) -> set[str]:
"""The Elements, Relationships and Checks a set of changed requirements reaches.
A changed requirement reaches the components that serve it, the Elements that
realise those components, the Relationships at those Elements, and every Check
on any of them or with the requirement as its source. A recommendation that
changed reaches the Checks that come from it and what they apply to.
"""
sources = set(changed) | set(recommendations_changed)
served = {
str(component.get("id"))
for component in components
if set(component.get("requirements") or ()) & set(changed)
}
reached = {
str(element.get("id"))
for element in graph.get("elements", ())
if element.get("component") in served
}
for check in graph.get("checks", ()):
if check.get("source") in sources:
reached.add(str(check.get("id")))
reached.add(str(check.get("applies_to")))
reached |= {
str(relationship.get("id"))
for relationship in graph.get("relationships", ())
if relationship.get("from") in reached or relationship.get("to") in reached
}
reached |= {
str(check.get("id"))
for check in graph.get("checks", ())
if check.get("applies_to") in reached
}
return reached
def change_summary(
baseline: Deliverables | None, current: Deliverables | None
) -> dict[str, Any]:
"""What a Change request changed, as changes.json holds it.
Requirements carry their own account. Everything else is compared by id. What
changed inside the reach of the changed requirements is listed as requested;
anything else that changed is listed apart as unrequested.
"""
requirements = requirement_changes(current)
changed_ids = [item["id"] for item in requirements]
produced = current or {}
recommendations = _compare(
_items(baseline, "design_recommendations", RECOMMENDATIONS_FILE),
_items(current, "design_recommendations", RECOMMENDATIONS_FILE)
if "design_recommendations" in produced
else None,
)
components = _compare(
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
_items(current, "technical_decomposition", COMPONENTS_FILE)
if "technical_decomposition" in produced
else None,
)
old_graph, new_graph = _graph(baseline), _graph(current)
designed = "target_architecture" in produced
# Reach is traced through both versions: what a requirement used to touch can
# change or go, as well as what it touches now.
touched_recommendations = recommendations[ADDED] + recommendations[CHANGED]
reached = reach(
changed_ids,
_items(current, "technical_decomposition", COMPONENTS_FILE),
touched_recommendations,
new_graph,
) | reach(
changed_ids,
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
touched_recommendations + recommendations[REMOVED],
old_graph,
)
graph: dict[str, dict[str, list[str]]] = {}
unrequested: dict[str, list[str]] = {}
for part in ("elements", "relationships", "checks"):
compared = _compare(old_graph[part], new_graph[part] if designed else None)
graph[part] = compared
outside = [
identifier
for change in (ADDED, CHANGED, REMOVED)
for identifier in compared[change]
if identifier not in reached
]
if outside:
unrequested[part] = outside
return {
"requirements": requirements,
"components": components,
"recommendations": recommendations,
**graph,
# Changed without being reached by any changed requirement.
"unrequested": unrequested,
}
def is_empty(summary: Mapping[str, Any]) -> bool:
return not summary.get("requirements") and not any(
summary.get(part, {}).get(change)
for part in (
"components",
"recommendations",
"elements",
"relationships",
"checks",
)
for change in (ADDED, CHANGED, REMOVED)
)
# What an Approval of each kind of Deliverable shows of the change.
_SHOWN_WITH = {
"requirements": ("requirements",),
"technical_decomposition": ("components",),
"design_recommendations": ("recommendations",),
"target_architecture": ("elements", "relationships", "checks", "unrequested"),
}
def changes_for(summary: Mapping[str, Any], kinds: Sequence[str]) -> dict[str, Any]:
"""The part of a change summary that belongs to the Deliverables being approved,
with the parts that hold nothing left out."""
shown: dict[str, Any] = {}
for kind in kinds:
for part in _SHOWN_WITH.get(kind, ()):
value = summary.get(part)
if isinstance(value, Mapping):
value = {name: ids for name, ids in value.items() if ids}
if value:
shown[part] = value
return shown

View File

@@ -0,0 +1,427 @@
"""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. 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.core.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.core.changes import check_requirement_changes
from app.core.target_architecture import GRAPH_ATTACHMENT
from app.core.work_breakdown import WORK_BREAKDOWN_FILE, check_work_breakdown
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"
# The plan for building what was designed and validated (iteration 10).
WORK_BREAKDOWN = "work_breakdown"
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
# Earlier Deliverables this Specialist is not shown. They are still held for
# the checks its submission is put through, and it can read any of them on
# request. What a Specialist is given at the start is sent again with every
# request it makes, so what it does not use is paid for many times over: in a
# run measured on 2026-10-12 the earlier Deliverables were 48% of everything
# sent to the models.
not_shown: tuple[DeliverableKind, ...] = ()
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),
# The pillars are the Cloud provider's: see ProviderContract.
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=(
# The code files are the Cloud provider's: see ProviderContract.
IMPLEMENTATION_FILE,
),
# The graph is all the code is written from.
reads_in_full=(),
not_shown=(
_K.REQUIREMENTS,
_K.TECHNICAL_DECOMPOSITION,
_K.PRODUCT_SELECTION,
_K.DESIGN_RECOMMENDATIONS,
),
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,),
# It judges the code against the Checks; the prose describing the
# design is not what it judges.
not_shown=(_K.ARCHITECTURE_DESCRIPTION,),
working_copy=_K.DEPLOYMENT_GUIDANCE,
),
DeliverableSpec(
_K.WORK_BREAKDOWN,
PhaseId.PACKAGING,
"delivery-planner",
depends_on=(_K.VALIDATION_RESULTS,),
sections=("Approach",),
attachments=(WORK_BREAKDOWN_FILE,),
# A plan covers the design and how it is built: the graph and the code.
reads_in_full=(_K.TARGET_ARCHITECTURE, _K.DEPLOYMENT_GUIDANCE),
not_shown=(
_K.REQUIREMENTS,
_K.DESIGN_RECOMMENDATIONS,
_K.ARCHITECTURE_DESCRIPTION,
),
),
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),
_K.WORK_BREAKDOWN: (WORK_BREAKDOWN_FILE, check_work_breakdown),
}
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
@dataclass(frozen=True)
class ProviderContract:
"""What a Cloud provider's bundle adds to the Deliverables: its framework's pillars
as sections of the design recommendations, and the files of its infrastructure code."""
pillar_sections: tuple[str, ...] = ()
iac_files: tuple[str, ...] = ()
def sections(self, kind: DeliverableKind) -> tuple[str, ...]:
added = self.pillar_sections if kind is _K.DESIGN_RECOMMENDATIONS else ()
return (*DEPENDENCY_GRAPH[kind].sections, *added)
def attachments(self, kind: DeliverableKind) -> tuple[str, ...]:
added = self.iac_files if kind is _K.DEPLOYMENT_GUIDANCE else ()
return (*added, *DEPENDENCY_GRAPH[kind].attachments)
NO_CONTRACT = ProviderContract()
# Sections code appends to a Deliverable for the person reading it. A Specialist
# working from that Deliverable has the same facts as data, and is not shown them.
FOR_READERS: Mapping[DeliverableKind, str] = {
_K.DESIGN_RECOMMENDATIONS: "Architecture framework checklist review",
}
def shown(
kind: DeliverableKind, given: Mapping[str, Mapping[str, object]]
) -> dict[str, dict[str, object]]:
"""What of `given` a Specialist is shown. Nothing it uses is left out.
- A Deliverable its spec lists under `not_shown` is omitted.
- The scope is in every Specialist's context as data, so it is not shown again
as a dependency; a Specialist that reads it whole sees its prose.
- A section written for a reader is left off, except for the packager, which
assembles the guide those sections belong in.
"""
spec = DEPENDENCY_GRAPH[kind]
view: dict[str, dict[str, object]] = {}
for name, deliverable in given.items():
dependency = DeliverableKind(name)
if dependency in spec.not_shown:
continue
entry = dict(deliverable)
if dependency is _K.SCOPE:
if dependency not in (*spec.depends_on, *(spec.reads_in_full or ())):
continue
entry = {"content": entry.get("content", "")}
heading = FOR_READERS.get(dependency)
content = entry.get("content")
if heading and isinstance(content, str) and kind is not _K.SOLUTION_GUIDE:
entry["content"] = content.split(f"\n## {heading}")[0].rstrip() + "\n"
view[name] = entry
return view
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,
contract: ProviderContract = NO_CONTRACT,
) -> 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",)
headings = [_normalise(match) for match in _HEADING.findall(content)]
missing = []
for section in contract.sections(kind):
required = _normalise(section)
if not any(h == required or h.endswith(" " + required) for h in headings):
missing.append(f"section: {section}")
for name in contract.attachments(kind):
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)

View File

@@ -0,0 +1,317 @@
"""The Ledger: every rule code owns about Deliverable progress, Approvals and Revisions.
Pure and synchronous: no I/O, no framework types. Invalid requests raise
LedgerRefusal and leave the Ledger unchanged; tools turn refusals into messages
the agent can act on.
"""
from __future__ import annotations
from collections.abc import Iterable
from dataclasses import asdict, dataclass, field
from enum import StrEnum
from typing import Any
from app.core.deliverables import (
DEPENDENCY_GRAPH,
PHASE_ORDER,
DeliverableKind,
PhaseId,
deliverables_in,
)
PRE_APPROVED_ACTOR = "pre-approved"
class DeliverableStatus(StrEnum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
SUBMITTED = "submitted"
class PhaseStatus(StrEnum):
OPEN = "open"
AWAITING_APPROVAL = "awaiting_approval"
APPROVED = "approved"
class LedgerRefusal(Exception):
"""A request the Ledger's rules don't allow. Nothing was changed."""
@dataclass(frozen=True)
class LedgerEvent:
sequence: int
type: str # started | released | submitted | approval_requested | approved |
# changes_requested | reopened | reset | approval_withdrawn | escalated
subject: str # a DeliverableKind or PhaseId value
actor: str
detail: str = ""
@dataclass(frozen=True)
class ReopenResult:
reset: tuple[DeliverableKind, ...]
withdrawn_approvals: tuple[PhaseId, ...]
escalation: str | None = None
@dataclass
class _DeliverableRecord:
status: DeliverableStatus = DeliverableStatus.PENDING
attempt: int = 0
revisions: int = 0
feedback: list[str] = field(default_factory=list)
class Ledger:
def __init__(self, pre_approved: bool = False, max_revisions: int = 3) -> None:
self.pre_approved = pre_approved
self.max_revisions = max_revisions
self._deliverables = {kind: _DeliverableRecord() for kind in DEPENDENCY_GRAPH}
self._phases = {phase: PhaseStatus.OPEN for phase in PHASE_ORDER}
self._events: list[LedgerEvent] = []
# --- queries -----------------------------------------------------------------
@property
def events(self) -> tuple[LedgerEvent, ...]:
return tuple(self._events)
def status(self, kind: DeliverableKind) -> DeliverableStatus:
return self._deliverables[kind].status
def phase_status(self, phase: PhaseId) -> PhaseStatus:
return self._phases[phase]
def revisions(self, kind: DeliverableKind) -> int:
return self._deliverables[kind].revisions
def feedback(self, kind: DeliverableKind) -> tuple[str, ...]:
return tuple(self._deliverables[kind].feedback)
def dependencies_met(self, kind: DeliverableKind) -> bool:
spec = DEPENDENCY_GRAPH[kind]
for dependency in spec.depends_on:
dependency_phase = DEPENDENCY_GRAPH[dependency].phase
if dependency_phase is spec.phase:
if self.status(dependency) is not DeliverableStatus.SUBMITTED:
return False
elif self._phases[dependency_phase] is not PhaseStatus.APPROVED:
return False
return True
def ready_work(self) -> tuple[DeliverableKind, ...]:
return tuple(
kind
for kind in DEPENDENCY_GRAPH
if self.status(kind) is DeliverableStatus.PENDING
and self.dependencies_met(kind)
)
def phases_ready_for_approval(self) -> tuple[PhaseId, ...]:
return tuple(
phase
for phase in PHASE_ORDER
if self._phases[phase] is PhaseStatus.OPEN and not self._unsubmitted(phase)
)
def can_finish(self) -> bool:
return self._phases[PHASE_ORDER[-1]] is PhaseStatus.APPROVED
# --- delegation and submission -----------------------------------------------
def start(
self, kinds: Iterable[DeliverableKind], actor: str
) -> dict[DeliverableKind, int]:
"""Move ready Deliverables in progress; returns the attempt number for each."""
kinds = list(dict.fromkeys(kinds))
ready = set(self.ready_work())
not_ready = [kind for kind in kinds if kind not in ready]
if not_ready:
raise LedgerRefusal(
"Not ready to start: "
+ ", ".join(self._describe_unready(k) for k in not_ready)
)
attempts = {}
for kind in kinds:
record = self._deliverables[kind]
record.status = DeliverableStatus.IN_PROGRESS
record.attempt += 1
attempts[kind] = record.attempt
self._record("started", kind, actor, f"attempt {record.attempt}")
return attempts
def submit(self, kind: DeliverableKind, attempt: int, actor: str) -> None:
"""Accept the current attempt. Any later start, release or reopen supersedes it."""
self._require_current_attempt(kind, attempt)
self._deliverables[kind].status = DeliverableStatus.SUBMITTED
self._record("submitted", kind, actor, f"attempt {attempt}")
def release(self, kind: DeliverableKind, attempt: int, reason: str) -> None:
"""Return in-progress work to pending (e.g. the Specialist needs input)."""
self._require_current_attempt(kind, attempt)
record = self._deliverables[kind]
record.status = DeliverableStatus.PENDING
self._record("released", kind, DEPENDENCY_GRAPH[kind].specialist, reason)
# --- approvals ---------------------------------------------------------------
def request_approval(self, phase: PhaseId, actor: str) -> None:
if self._phases[phase] is not PhaseStatus.OPEN:
raise LedgerRefusal(f"Phase {phase} is {self._phases[phase]}, not open")
unsubmitted = self._unsubmitted(phase)
if unsubmitted:
raise LedgerRefusal(
f"Phase {phase} has unsubmitted Deliverables: {', '.join(unsubmitted)}"
)
self._phases[phase] = PhaseStatus.AWAITING_APPROVAL
self._record("approval_requested", phase, actor)
if self.pre_approved:
self.approve(phase, actor=PRE_APPROVED_ACTOR)
def approve(self, phase: PhaseId, actor: str) -> None:
self._require_awaiting(phase)
self._phases[phase] = PhaseStatus.APPROVED
self._record("approved", phase, actor)
def request_changes(self, phase: PhaseId, feedback: str, actor: str) -> None:
self._require_awaiting(phase)
self._phases[phase] = PhaseStatus.OPEN
self._record("changes_requested", phase, actor, feedback)
# --- revisions ---------------------------------------------------------------
def reopen(
self,
kind: DeliverableKind,
reason: str,
actor: str,
override_cap: bool = False,
) -> ReopenResult:
record = self._deliverables[kind]
if record.status is not DeliverableStatus.SUBMITTED:
raise LedgerRefusal(
f"Only submitted Deliverables can be reopened; {kind} is {record.status}"
)
if record.revisions >= self.max_revisions and not override_cap:
escalation = (
f"{kind} has reached its revision limit ({self.max_revisions}). "
f"Requested change: {reason}. Ask the user whether to revise it again "
"or accept it as it stands."
)
self._record("escalated", kind, actor, reason)
return ReopenResult(reset=(), withdrawn_approvals=(), escalation=escalation)
record.status = DeliverableStatus.PENDING
record.revisions += 1
record.feedback.append(reason)
self._record("reopened", kind, actor, reason)
reset = [kind]
for dependent in self._dependents_of(kind):
dependent_record = self._deliverables[dependent]
if dependent_record.status is DeliverableStatus.PENDING:
continue
dependent_record.status = DeliverableStatus.PENDING
dependent_record.feedback.append(f"Dependency {kind} was revised: {reason}")
self._record("reset", dependent, actor, f"dependency {kind} reopened")
reset.append(dependent)
withdrawn = []
for phase in PHASE_ORDER:
affected = any(DEPENDENCY_GRAPH[k].phase is phase for k in reset)
if affected and self._phases[phase] is not PhaseStatus.OPEN:
self._phases[phase] = PhaseStatus.OPEN
self._record("approval_withdrawn", phase, actor, f"{kind} reopened")
withdrawn.append(phase)
return ReopenResult(reset=tuple(reset), withdrawn_approvals=tuple(withdrawn))
# --- persistence -------------------------------------------------------------
def to_dict(self) -> dict[str, Any]:
return {
"pre_approved": self.pre_approved,
"max_revisions": self.max_revisions,
"deliverables": {
kind.value: {
"status": record.status.value,
"attempt": record.attempt,
"revisions": record.revisions,
"feedback": list(record.feedback),
}
for kind, record in self._deliverables.items()
},
"phases": {
phase.value: status.value for phase, status in self._phases.items()
},
"events": [asdict(event) for event in self._events],
}
@classmethod
def from_dict(cls, data: dict[str, Any]) -> Ledger:
ledger = cls(
pre_approved=data["pre_approved"], max_revisions=data["max_revisions"]
)
for kind_value, record in data["deliverables"].items():
ledger._deliverables[DeliverableKind(kind_value)] = _DeliverableRecord(
status=DeliverableStatus(record["status"]),
attempt=record["attempt"],
revisions=record["revisions"],
feedback=list(record["feedback"]),
)
for phase_value, status in data["phases"].items():
ledger._phases[PhaseId(phase_value)] = PhaseStatus(status)
ledger._events = [LedgerEvent(**event) for event in data["events"]]
return ledger
# --- internals ---------------------------------------------------------------
def _record(self, type_: str, subject: str, actor: str, detail: str = "") -> None:
self._events.append(
LedgerEvent(len(self._events) + 1, type_, str(subject), actor, detail)
)
def _unsubmitted(self, phase: PhaseId) -> list[DeliverableKind]:
return [
kind
for kind in deliverables_in(phase)
if self.status(kind) is not DeliverableStatus.SUBMITTED
]
def _dependents_of(self, kind: DeliverableKind) -> list[DeliverableKind]:
"""Every Deliverable that depends on `kind`, directly or not, in graph order."""
dependents: set[DeliverableKind] = set()
frontier = {kind}
while frontier:
frontier = {
candidate
for candidate, spec in DEPENDENCY_GRAPH.items()
if candidate not in dependents and frontier & set(spec.depends_on)
}
dependents |= frontier
return [candidate for candidate in DEPENDENCY_GRAPH if candidate in dependents]
def _describe_unready(self, kind: DeliverableKind) -> str:
status = self.status(kind)
if status is not DeliverableStatus.PENDING:
return f"{kind} ({status})"
return f"{kind} (dependencies not met)"
def _require_current_attempt(self, kind: DeliverableKind, attempt: int) -> None:
record = self._deliverables[kind]
if (
record.status is not DeliverableStatus.IN_PROGRESS
or attempt != record.attempt
):
raise LedgerRefusal(
f"{kind} is {record.status}, not in_progress with attempt {attempt}; "
"this attempt is not current"
)
def _require_awaiting(self, phase: PhaseId) -> None:
if self._phases[phase] is not PhaseStatus.AWAITING_APPROVAL:
raise LedgerRefusal(
f"Phase {phase} is {self._phases[phase]}, not awaiting_approval"
)

View File

@@ -0,0 +1,302 @@
"""Cloud provider bundles.
A Cloud provider is configuration, not code (ADR-0002): providers/<name>.yaml lists
the Skills, local tools, remote MCP servers and default models that one Cloud
provider brings. Nothing outside this module names a provider.
"""
from __future__ import annotations
from collections.abc import Mapping
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
import yaml
from app.core.deliverables import ProviderContract
from app.core.scope import Catalogue, load_catalogue
from app.skills.agent_skills import SkillFormatError, SkillMeta, discover_skills
TIERS = ("general", "cloud_read")
_REPO_ROOT = Path(__file__).resolve().parent.parent.parent
class ProviderConfigError(ValueError):
"""A provider bundle is missing or invalid."""
@dataclass(frozen=True)
class McpServerSpec:
"""A remote MCP server hosted by the Cloud provider.
Only tools named in `allow` are ever exposed; an empty `allow` exposes nothing.
"""
id: str
url: str
tier: str
allow: tuple[str, ...]
preview: bool = False
@dataclass(frozen=True)
class ModelConfig:
default: str
roles: Mapping[str, str] = field(default_factory=dict)
# Seconds one model request may take, for the roles whose replies are long. A
# role not named here gets the runtime's default.
timeouts: Mapping[str, float] = field(default_factory=dict)
# A lighter model for a role's first attempt at a Deliverable. Only for a role
# whose work something else checks; an attempt after feedback takes its own.
first_attempt: Mapping[str, str] = field(default_factory=dict)
def for_role(self, role: str) -> str:
return self.roles.get(role, self.default)
def timeout_for(self, role: str) -> float | None:
return self.timeouts.get(role)
@dataclass(frozen=True)
class ProviderBundle:
name: str
contract: ProviderContract
skills_dirs: tuple[Path, ...]
skills: Mapping[str, SkillMeta]
output_template: Path
models: ModelConfig
tools: Mapping[str, tuple[str, ...]]
mcp_auth: Mapping[str, Any]
mcp_servers: Mapping[str, McpServerSpec]
role_mcp_servers: Mapping[str, tuple[str, ...]]
role_skills: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
pillar_skills: Mapping[str, str] = field(default_factory=dict)
# The Terraform providers generated code is written for, pinned so the schema
# lookup, the patterns and validation agree: {name: {source, version}}.
terraform_providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
# Registry namespaces generated code may take a Terraform module from. Empty
# means no module is accepted.
terraform_module_namespaces: tuple[str, ...] = ()
# The Skill that says which modules to use and when. It reaches a Specialist
# only in an Execution that opted into modules.
terraform_modules_skill: str | None = None
# Modules that could not be used with the pinned providers when last looked
# at, as <namespace>/<name>/<provider>. scripts/check-terraform-modules.py
# says when one can.
terraform_modules_watch: tuple[str, ...] = ()
# The Skill approved lessons are published in (ADR-0004); None when the provider
# has none. A Specialist is given it once it holds lessons for its Deliverable.
lessons_skill: str | None = None
# The Skill that holds the scope spec's catalogue (ADR-0008), and the values
# this provider allows for the fields the catalogue leaves to a provider.
scope_skill: str | None = None
scope_values: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
# The agent's MCP server for this provider, and how its tools are named.
mcp_server: str = ""
mcp_tool_format: str = "{tool}"
mcp_describe_tool: str = ""
def mcp_tool_name(self, server: str, tool: str) -> str:
"""The tool's name on this provider's MCP server, under agent.yaml's `mcp:`."""
return self.mcp_tool_format.format(server=server, tool=tool)
def scope_catalogue(self) -> Catalogue:
if not self.scope_skill:
raise ProviderConfigError(f"The {self.name} bundle names no scope Skill.")
return load_catalogue(
self.skills[self.scope_skill].path / "assets" / "catalogue.yaml"
)
def mcp_servers_for_role(
self, role: str, include_preview: bool = True
) -> tuple[McpServerSpec, ...]:
servers = (
self.mcp_servers[server_id]
for server_id in self.role_mcp_servers.get(role, ())
)
return tuple(
server for server in servers if include_preview or not server.preview
)
def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
"""Load and validate providers/<name>.yaml; relative paths resolve against `root`."""
root = root or _REPO_ROOT
config_path = root / "providers" / f"{name}.yaml"
if not config_path.is_file():
raise ProviderConfigError(f"No provider bundle for {name!r} at {config_path}")
config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
if not isinstance(config, dict):
raise ProviderConfigError(f"{config_path}: must be a mapping")
def fail(message: str) -> ProviderConfigError:
return ProviderConfigError(f"{config_path}: {message}")
if config.get("name") != name:
raise fail(f"'name' must be {name!r}")
skills_dirs = tuple(root / entry for entry in config.get("skills_dirs") or ())
if not skills_dirs:
raise fail("'skills_dirs' must list at least one directory")
for directory in skills_dirs:
if not directory.is_dir():
raise fail(f"'skills_dirs' entry {directory} is not a directory")
try:
skills = discover_skills(skills_dirs)
except SkillFormatError as exc:
raise fail(str(exc)) from exc
output_template = root / str(config.get("output_template", ""))
if not config.get("output_template") or not output_template.is_file():
raise fail(f"'output_template' {output_template} does not exist")
models = config.get("models") or {}
if not isinstance(models.get("default"), str) or not models["default"]:
raise fail("'models.default' is required")
timeouts = {}
for role, seconds in (models.get("timeout_seconds") or {}).items():
if isinstance(seconds, bool) or not isinstance(seconds, (int, float)):
raise fail(f"'models.timeout_seconds' for {role!r} must be a number")
if seconds <= 0:
raise fail(f"'models.timeout_seconds' for {role!r} must be positive")
timeouts[str(role)] = float(seconds)
model_config = ModelConfig(
default=models["default"],
roles=dict(models.get("roles") or {}),
timeouts=timeouts,
first_attempt={
str(role): str(model)
for role, model in (models.get("first_attempt") or {}).items()
},
)
terraform_providers = {}
pins = (config.get("terraform") or {}).get("required_providers") or {}
for provider, pin in pins.items():
if not isinstance(pin, dict) or not all(
isinstance(pin.get(key), str) and pin[key] for key in ("source", "version")
):
raise fail(
f"terraform provider {provider!r} needs a 'source' and an exact "
"'version', both strings"
)
terraform_providers[str(provider)] = {
"source": pin["source"],
"version": pin["version"],
}
module_namespaces = ((config.get("terraform") or {}).get("modules") or {}).get(
"namespaces"
) or []
if not isinstance(module_namespaces, list) or not all(
isinstance(item, str) and item for item in module_namespaces
):
raise fail("'terraform.modules.namespaces' must be a list of names")
modules_skill = ((config.get("terraform") or {}).get("modules") or {}).get(
"skill"
) or None
if modules_skill is not None and modules_skill not in skills:
raise fail(
f"'terraform.modules.skill' references unknown skill {modules_skill!r}"
)
tools = {}
for tier, tool_names in (config.get("tools") or {}).items():
if tier not in TIERS:
raise fail(f"'tools' tier {tier!r} must be one of {TIERS}")
tools[tier] = tuple(tool_names or ())
mcp_servers = {}
for server_id, spec in (config.get("mcp_servers") or {}).items():
url = spec.get("url", "")
if not url.startswith("https://"):
raise fail(f"MCP server {server_id!r} url must use https")
if spec.get("tier") not in TIERS:
raise fail(f"MCP server {server_id!r} tier must be one of {TIERS}")
if not isinstance(spec.get("allow"), list):
raise fail(
f"MCP server {server_id!r} needs an 'allow' list (empty exposes no tools)"
)
mcp_servers[server_id] = McpServerSpec(
id=server_id,
url=url,
tier=spec["tier"],
allow=tuple(spec["allow"]),
preview=bool(spec.get("preview", False)),
)
role_mcp_servers = {}
for role, server_ids in (config.get("role_mcp_servers") or {}).items():
unknown = [
server_id for server_id in server_ids or () if server_id not in mcp_servers
]
if unknown:
raise fail(
f"role {role!r} references unknown MCP servers: {', '.join(unknown)}"
)
role_mcp_servers[role] = tuple(server_ids or ())
role_skills = {}
for role, skill_names in (config.get("role_skills") or {}).items():
unknown = [skill for skill in skill_names or () if skill not in skills]
if unknown:
raise fail(f"role {role!r} references unknown skills: {', '.join(unknown)}")
role_skills[role] = tuple(skill_names or ())
pillar_skills = {}
for pillar, skill_name in (config.get("pillar_skills") or {}).items():
if skill_name not in skills:
raise fail(f"pillar {pillar!r} references unknown skill {skill_name!r}")
pillar_skills[str(pillar)] = skill_name
lessons_skill = config.get("lessons_skill") or None
if lessons_skill is not None and lessons_skill not in skills:
raise fail(f"'lessons_skill' references unknown skill {lessons_skill!r}")
scope = config.get("scope") or {}
scope_skill = scope.get("skill") or None
if scope_skill is not None and scope_skill not in skills:
raise fail(f"'scope.skill' references unknown skill {scope_skill!r}")
scope_values = {
str(path): tuple(str(value) for value in values or ())
for path, values in (scope.get("values") or {}).items()
}
deliverables = config.get("deliverables") or {}
pillar_sections = tuple(str(item) for item in deliverables.get("pillar_sections") or ())
iac_files = tuple(str(item) for item in deliverables.get("iac_files") or ())
if not pillar_sections or not iac_files:
raise fail("'deliverables' needs pillar_sections and iac_files")
return ProviderBundle(
name=name,
contract=ProviderContract(pillar_sections, iac_files),
mcp_server=str((config.get("mcp") or {}).get("server", "")),
mcp_tool_format=str((config.get("mcp") or {}).get("tool_format", "{tool}")),
mcp_describe_tool=str((config.get("mcp") or {}).get("describe_tool", "")),
skills_dirs=skills_dirs,
skills=skills,
output_template=output_template,
models=model_config,
tools=tools,
mcp_auth=dict(config.get("mcp_auth") or {}),
mcp_servers=mcp_servers,
role_mcp_servers=role_mcp_servers,
role_skills=role_skills,
pillar_skills=pillar_skills,
terraform_providers=terraform_providers,
terraform_module_namespaces=tuple(module_namespaces),
terraform_modules_skill=modules_skill,
terraform_modules_watch=tuple(
str(item)
for item in ((config.get("terraform") or {}).get("modules") or {}).get(
"watch"
)
or ()
),
lessons_skill=lessons_skill,
scope_skill=scope_skill,
scope_values=scope_values,
)

View File

@@ -0,0 +1,501 @@
"""The scope spec: what the customer wants and the facts a design depends on, as a
file (ADR-0008).
A spec may arrive complete, partly filled or not at all. This reads one against the
catalogue of fields a Skill holds, and says exactly what is settled and what is not.
No model is involved: whether a field is filled is a fact.
a value the customer states it supplied
ask, or absent not known yet a gap, with its question
decide the customer leaves the choice to the agent an assumption
not_applicable does not apply nothing asked or assumed
The file supplied is never altered. `Scope.completed()` is the copy written beside
it, with the sections the agent writes: assumptions, gaps, where each value came
from, and a count of each.
.venv/bin/python -m app.scope check <spec.yaml> [provider]
.venv/bin/python -m app.scope template [kind]
"""
from __future__ import annotations
import datetime as dt
import re
import sys
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
import yaml
ASK, DECIDE, NOT_APPLICABLE = "ask", "decide", "not_applicable"
MARKERS = (ASK, DECIDE, NOT_APPLICABLE)
SUPPLIED, ASSUMED, UNKNOWN = "supplied", "assumed", "unknown"
# Where a settled value came from: the spec file, the customer's request in prose,
# an answer they gave in conversation, or the agent's own choice.
REQUEST, ANSWERED = "request", "answered"
SOURCES = (SUPPLIED, REQUEST, ANSWERED, ASSUMED)
ESSENTIAL, IMPORTANT, OPTIONAL = "essential", "important", "optional"
_SEVERITY = {ESSENTIAL: "HIGH", IMPORTANT: "MEDIUM", OPTIONAL: "LOW"}
DRAFT, UNDER_REVIEW, APPROVED, LOCKED = (
"DRAFT",
"UNDER_REVIEW",
"APPROVED",
"BASELINE_LOCKED",
)
KIND_FIELD = "engagement.kind"
CASE_FIELD = "metadata.customer_case"
STATEMENT_FIELD = "intent.statement"
# What the agent writes into the completed copy. A supplied file may still carry
# them from an earlier run; they are read as that run's and replaced.
_AGENT_WRITTEN = (
"schema_version",
"inferred_assumptions",
"discovery_gaps",
"provenance",
"readiness",
)
_AGENT_FIELDS = ("metadata.status",)
_SLUG = re.compile(r"[^a-z0-9]+")
class ScopeError(ValueError):
"""A scope spec that cannot be used, with every problem found in it."""
def __init__(self, problems: Sequence[str]) -> None:
self.problems = list(problems)
super().__init__("scope spec: " + "; ".join(self.problems))
@dataclass(frozen=True)
class FieldSpec:
path: str
type: str = "string"
tier: Any = OPTIONAL # a tier, or {kind: tier}
question: str = ""
default: Any = None
affects: str = ""
values: tuple[str, ...] = ()
provider_values: bool = False
keys: tuple[str, ...] = ()
optional_keys: tuple[str, ...] = ()
aliases: tuple[str, ...] = ()
# A choice a design must honour. Stated by the customer, it has to be carried
# by a requirement, and so by a Check on the Target architecture.
binds: bool = False
def tier_for(self, kind: str | None) -> str:
if isinstance(self.tier, Mapping):
return str(self.tier.get(kind, OPTIONAL))
return str(self.tier)
@dataclass(frozen=True)
class Catalogue:
schema_version: int
kinds: tuple[str, ...]
fields: Mapping[str, FieldSpec]
def aliases(self) -> dict[str, str]:
return {
alias: spec.path for spec in self.fields.values() for alias in spec.aliases
}
def load_catalogue(path: Path) -> Catalogue:
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
fields = {}
for name, raw in (data.get("fields") or {}).items():
raw = raw or {}
fields[name] = FieldSpec(
path=name,
type=str(raw.get("type", "string")),
tier=raw.get("tier", OPTIONAL),
question=" ".join(str(raw.get("question", "")).split()),
default=raw.get("default"),
affects=str(raw.get("affects", "")),
values=tuple(str(v) for v in raw.get("values") or ()),
provider_values=bool(raw.get("provider_values")),
keys=tuple(raw.get("keys") or ()),
optional_keys=tuple(raw.get("optional_keys") or ()),
aliases=tuple(raw.get("aliases") or ()),
binds=bool(raw.get("binds")),
)
return Catalogue(
schema_version=int(data.get("schema_version", 1)),
kinds=tuple(data.get("kinds") or ()),
fields=fields,
)
@dataclass
class Scope:
"""A scope spec read against the catalogue."""
catalogue: Catalogue
kind: str | None
values: dict[str, Any] = field(default_factory=dict) # field -> stated value
states: dict[str, str] = field(default_factory=dict) # field -> marker
supplied_text: str = ""
# Where each value came from, when it was not the spec file; and what was said
# about it: the reason for an assumption, the question an answer was given to.
sources: dict[str, str] = field(default_factory=dict)
notes: dict[str, str] = field(default_factory=dict)
def source(self, path: str) -> str:
return self.sources.get(path, SUPPLIED)
@property
def customer_case(self) -> str | None:
value = self.values.get(CASE_FIELD)
return str(value) if value else None
@property
def statement(self) -> str:
return str(self.values.get(STATEMENT_FIELD) or "").strip()
def tier(self, path: str) -> str:
return self.catalogue.fields[path].tier_for(self.kind)
def gaps(self, *tiers: str) -> list[dict[str, str]]:
"""What is not known, most pressing first: each with the question to ask."""
wanted = tiers or (ESSENTIAL, IMPORTANT, OPTIONAL)
found = [
{
"field": path,
"prompt": self.catalogue.fields[path].question or f"What is {path}?",
"severity": _SEVERITY[self.tier(path)],
}
for path, state in self.states.items()
if state == ASK and self.tier(path) in wanted
]
order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
return sorted(found, key=lambda gap: order[gap["severity"]])
def assumptions(self) -> list[dict[str, str]]:
"""What the customer left to the agent, each with the default to take and
what a wrong choice would change."""
found: list[dict[str, str]] = []
for path in self.catalogue.fields:
chosen = path in self.values and self.source(path) == ASSUMED
if not chosen and self.states.get(path) != DECIDE:
continue
spec = self.catalogue.fields[path]
if chosen:
statement = f"Assumed {path} is {self.values[path]}."
if self.notes.get(path):
statement += f" {self.notes[path]}"
else:
default = spec.default if spec.default is not None else "its choice"
statement = (
f"The customer left {path} to the agent. Default: {default}."
)
found.append(
{
"id": f"ASSUMP-{len(found) + 1:02d}",
"field": path,
"statement": statement,
"impact_if_invalid": f"Changes {spec.affects}."
if spec.affects
else "Local to this field.",
}
)
return found
def readiness(self) -> dict[str, int]:
states = list(self.states.values())
came = [self.source(path) for path in self.values]
return {
SUPPLIED: came.count(SUPPLIED) + came.count(REQUEST),
ANSWERED: came.count(ANSWERED),
ASSUMED: came.count(ASSUMED) + states.count(DECIDE),
UNKNOWN: states.count(ASK),
NOT_APPLICABLE: states.count(NOT_APPLICABLE),
}
def status(self, pre_approved: bool = False) -> str:
"""Where the spec stands. With nobody to ask, what is important and unknown
is defaulted and listed, so only an essential gap keeps it a draft."""
if pre_approved:
return DRAFT if self.gaps(ESSENTIAL) else APPROVED
return DRAFT if self.gaps(ESSENTIAL, IMPORTANT) else UNDER_REVIEW
def completed(self, status: str) -> dict[str, Any]:
"""The completed copy: every field of the catalogue, and the agent's
sections."""
document: dict[str, Any] = {"schema_version": self.catalogue.schema_version}
for path in self.catalogue.fields:
value = self.values.get(path, self.states.get(path, ASK))
_put(document, path, value)
_put(document, "metadata.status", status)
provenance = {path: self.source(path) for path in self.values}
provenance |= {
path: {DECIDE: ASSUMED, ASK: UNKNOWN, NOT_APPLICABLE: NOT_APPLICABLE}[state]
for path, state in self.states.items()
}
document["inferred_assumptions"] = self.assumptions()
document["discovery_gaps"] = self.gaps()
document["provenance"] = dict(sorted(provenance.items()))
document["readiness"] = self.readiness()
return document
def for_context(self) -> dict[str, Any]:
"""What a Specialist is shown: what the customer stated, what is theirs to
choose, and what is unknown."""
stated: dict[str, Any] = {}
for path, value in self.values.items():
if path.startswith(("run.", "metadata.")) or self.source(path) == ASSUMED:
continue
_put(stated, path, value)
return {
"kind": self.kind,
"stated": stated,
# The stated fields a design must honour: each has to be carried by a
# requirement, which the requirements are checked for.
"binding": [
path
for path in self.values
if self.catalogue.fields[path].binds and self.source(path) != ASSUMED
],
# What the agent chose where the customer did not say. Not the
# customer's decision: it may be revisited when they answer.
"assumed": [
{"field": path, "value": value, "why": self.notes.get(path, "")}
for path, value in self.values.items()
if self.source(path) == ASSUMED and not path.startswith("run.")
],
"to_decide": [
{
"field": path,
"default": self.catalogue.fields[path].default,
"affects": self.catalogue.fields[path].affects,
}
for path, state in self.states.items()
if state == DECIDE and not path.startswith("run.")
],
"to_ask": [
gap for gap in self.gaps() if not gap["field"].startswith("run.")
],
"not_applicable": sorted(
path for path, state in self.states.items() if state == NOT_APPLICABLE
),
}
def _put(document: dict[str, Any], path: str, value: Any) -> None:
*parents, last = path.split(".")
node = document
for part in parents:
node = node.setdefault(part, {})
node[last] = value
def slug(reference: str) -> str:
"""A Customer case id from an engagement reference: `ENG-2026-UK-084` and
`eng-2026-uk-084` name the same case."""
return _SLUG.sub("-", reference.strip().lower()).strip("-")[:64]
def read_scope(
supplied: str | Mapping[str, Any],
catalogue: Catalogue,
*,
provider_values: Mapping[str, Sequence[str]] | None = None,
) -> Scope:
"""Read a scope spec. Raises ScopeError naming every problem: YAML that does not
parse, a field the catalogue does not have, a value of the wrong type."""
text = supplied if isinstance(supplied, str) else yaml.safe_dump(dict(supplied))
try:
data = yaml.safe_load(text) if isinstance(supplied, str) else dict(supplied)
except yaml.YAMLError as exc:
raise ScopeError([f"not valid YAML ({exc})"]) from exc
if not isinstance(data, Mapping):
raise ScopeError(["the spec must be a mapping of sections"])
problems: list[str] = []
leaves: dict[str, Any] = {}
aliases = catalogue.aliases()
prefixes = {
".".join(path.split(".")[:depth])
for path in catalogue.fields
for depth in range(1, len(path.split(".")))
}
def walk(node: Any, path: str) -> None:
target = aliases.get(path, path)
if path in _AGENT_FIELDS or path in _AGENT_WRITTEN:
return
if target in catalogue.fields:
if target in leaves and leaves[target] != node and path != target:
problems.append(f"{path} and {target} name the same thing and differ")
leaves[target] = node
return
if path in prefixes:
if isinstance(node, Mapping):
for key, value in node.items():
walk(value, f"{path}.{key}")
elif node in MARKERS or node is None:
# A whole section marked at once applies to every field in it.
for name in catalogue.fields:
if name.startswith(path + "."):
leaves.setdefault(name, node)
else:
problems.append(f"{path} is a section, not a value")
return
problems.append(f"{path} is not a field of the scope spec")
for key, value in data.items():
walk(value, str(key))
kind = leaves.get(KIND_FIELD)
kind = str(kind) if kind in catalogue.kinds else None
scope = Scope(catalogue, kind, supplied_text=text)
extra = dict(provider_values or {})
for path, spec in catalogue.fields.items():
value = leaves.get(path)
if value is None or value == ASK:
scope.states[path] = ASK
elif value in (DECIDE, NOT_APPLICABLE):
scope.states[path] = value
else:
fault = _fault(spec, value, extra.get(path, ()))
if fault:
problems.append(f"{path}: {fault}")
else:
scope.values[path] = _plain(value)
case = scope.values.get(CASE_FIELD)
if case is not None:
scope.values[CASE_FIELD] = slug(str(case))
if not scope.values[CASE_FIELD]:
problems.append(f"{CASE_FIELD}: needs letters or digits")
if problems:
raise ScopeError(problems)
return scope
def _plain(value: Any) -> Any:
"""A value as plain data: YAML reads a date as a date, and state must be JSON."""
if isinstance(value, (dt.date, dt.datetime)):
return value.isoformat()
if isinstance(value, Mapping):
return {str(k): _plain(v) for k, v in value.items()}
if isinstance(value, (list, tuple)):
return [_plain(item) for item in value]
return value
def _fault(spec: FieldSpec, value: Any, provider_values: Sequence[str]) -> str:
"""Why a value does not fit its field; "" when it does."""
kind = spec.type
if kind in ("string", "text"):
return "" if isinstance(value, (str, int, float)) else "must be text"
if kind == "integer":
ok = isinstance(value, int) and not isinstance(value, bool)
return "" if ok else "must be a whole number"
if kind == "number":
ok = isinstance(value, (int, float)) and not isinstance(value, bool)
return "" if ok else "must be a number"
if kind == "boolean":
return "" if isinstance(value, bool) else "must be true or false"
if kind == "date":
if isinstance(value, (dt.date, dt.datetime)):
return ""
try:
dt.date.fromisoformat(str(value))
except ValueError:
return "must be a date, as YYYY-MM-DD"
return ""
if kind == "enum":
allowed = (*spec.values, *provider_values)
if not allowed or str(value) in allowed:
return ""
return f"must be one of {', '.join(allowed)}"
if kind == "list":
return "" if isinstance(value, list) else "must be a list"
if kind == "records":
if not isinstance(value, list):
return "must be a list of entries"
known = {*spec.keys, *spec.optional_keys}
for number, entry in enumerate(value, start=1):
if not isinstance(entry, Mapping):
return f"entry {number} must have named fields"
missing = [key for key in spec.keys if not entry.get(key)]
if missing:
return f"entry {number} needs {', '.join(missing)}"
unknown = sorted(set(map(str, entry)) - known)
if unknown:
return f"entry {number} has unknown fields {', '.join(unknown)}"
return ""
return f"has an unknown type {kind} in the catalogue"
def render_template(catalogue: Catalogue, kind: str | None = None) -> str:
"""A scope spec with every field set to ask, to fill in."""
document: dict[str, Any] = {}
for path, spec in catalogue.fields.items():
if path == KIND_FIELD and kind:
_put(document, path, kind)
elif spec.tier_for(kind) != OPTIONAL or kind is None:
_put(document, path, ASK)
header = (
"# Scope spec. Give each field a value, or: ask (not known yet), decide\n"
"# (you choose), not_applicable. A field left out is read as ask.\n"
)
return header + yaml.safe_dump(document, sort_keys=False, allow_unicode=True)
def render_reading(scope: Scope) -> str:
"""What a spec settles and what it leaves open, for a person."""
counts = scope.readiness()
lines = [
f"Engagement kind: {scope.kind or 'not stated'}",
(
f"{counts[SUPPLIED]} supplied, {counts[ASSUMED]} left to the agent, "
f"{counts[UNKNOWN]} unknown, {counts[NOT_APPLICABLE]} not applicable."
),
]
for severity, title in (
("HIGH", "Essential, needed before work can start"),
("MEDIUM", "Important, asked when someone is present"),
):
gaps = [gap for gap in scope.gaps() if gap["severity"] == severity]
if gaps:
lines += ["", f"{title}:"]
lines += [f" {gap['field']}: {gap['prompt']}" for gap in gaps]
return "\n".join(lines)
def main(arguments: Sequence[str]) -> int:
from app.config import get_settings
from app.core.providers import load_provider
command, rest = (arguments[0], arguments[1:]) if arguments else ("", [])
if command == "template":
bundle = load_provider(get_settings().CLOUD_PROVIDER)
print(render_template(bundle.scope_catalogue(), rest[0] if rest else None))
return 0
if command == "check" and rest:
bundle = load_provider(
rest[1] if len(rest) > 1 else get_settings().CLOUD_PROVIDER
)
try:
scope = read_scope(
Path(rest[0]).read_text(encoding="utf-8"),
bundle.scope_catalogue(),
provider_values=bundle.scope_values,
)
except ScopeError as refused:
print("This spec cannot be used:")
for problem in refused.problems:
print(f" {problem}")
return 1
print(render_reading(scope))
return 0
print(__doc__, file=sys.stderr)
return 2
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))

View File

@@ -0,0 +1,356 @@
"""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 as tables a person can review, 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). A constraint that lists
nothing infrastructure code can show, only what lies outside it, needs none.
"""
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
if _only_outside_code(requirement):
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 and not _only_outside_code(
recommendation
):
gaps.append(f"Recommendation {recommendation['id']} has no Check")
return tuple(gaps)
def _only_outside_code(item: Mapping[str, Any]) -> bool:
"""Whether a constraint says, explicitly, that nothing it asks for can be shown
by infrastructure code."""
return item.get("conditions") == [] and bool(item.get("outside_code"))
# --- 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"
# --- so are the tables a person reviews ----------------------------------------------
def _cell(text: str | None) -> str:
return " ".join((text or "").replace("|", "\\|").split())
def _table(
heading: str, columns: Sequence[str], rows: Iterable[Sequence[str | None]]
) -> str:
lines = [
f"## {heading}",
"",
"| " + " | ".join(columns) + " |",
"|" + "|".join(" --- " for _ in columns) + "|",
]
lines += ["| " + " | ".join(_cell(value) for value in row) + " |" for row in rows]
return "\n".join(lines)
def render_tables(graph: TargetArchitecture) -> str:
"""The graph as markdown tables: what a person approving the design reads.
Written by code, so the tables cannot disagree with the graph and no model spends
output repeating it.
"""
names = {element.id: element.name for element in graph.elements}
parts = [
_table(
"Elements",
("Id", "Name", "Product", "Resource type", "Component"),
(
(e.id, e.name, e.product, e.resource_type, e.component)
for e in graph.elements
),
),
_table(
"Relationships",
("Id", "From", "Kind", "To"),
(
(r.id, names[r.source], r.kind, names[r.target])
for r in graph.relationships
),
),
_table(
"Checks",
("Id", "Applies to", "Statement", "Source"),
((c.id, c.applies_to, c.statement, c.source) for c in graph.checks),
),
]
if graph.not_applicable:
parts.append(
_table(
"Not applicable",
("Recommendation", "Reason"),
((n.recommendation, n.reason) for n in graph.not_applicable),
)
)
return "\n\n".join(parts) + "\n"

View File

@@ -0,0 +1,559 @@
"""The work breakdown structure: a plan for building the Target architecture.
A Specialist divides the build into work packages and activities and estimates each
activity's days. Everything after that is code, as it is for the architecture
diagram: the plan is checked against the design, the schedule is computed from the
days and the dependencies, and the three views a reader sees are written from the
result. So the timeline cannot disagree with the plan, and no part of the design can
be left out of it.
work packages a hierarchy; each delivers named Elements, and is done when the
Checks on those Elements pass
activities what is done, in which work package, for how many days, after
which other activities, and by whom
schedule each activity's start and finish day, on a relative axis from
Day 0, with no more of the team's activities at once than the
team has people; and the critical path
"""
from __future__ import annotations
import datetime as dt
import json
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from typing import Any
from app.core.chain import Upstream, agreed_scope, read_graph
WORK_BREAKDOWN_FILE = "work-breakdown.json"
TIMELINE_FILE = "timeline.mmd"
DICTIONARY_HEADING = "WBS dictionary"
TEAM, CUSTOMER = "team", "customer"
OWNERS = (TEAM, CUSTOMER)
DEFAULT_TEAM_SIZE = 2
DEFAULT_WEEK = 5
MAX_DAYS = 120 # one activity; anything longer is a work package, not an activity
_CHART_WIDTH = 60
@dataclass(frozen=True)
class Scheduled:
id: str
start: float
finish: float
critical: bool
def _text(value: Any) -> str:
return " ".join(str(value or "").split())
def _list(value: Any) -> list[str]:
return [str(item) for item in value] if isinstance(value, list) else []
def parse(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str]]:
"""(work packages, activities, problems) from the data file."""
name = WORK_BREAKDOWN_FILE
try:
data = json.loads(text)
except ValueError as exc:
return [], [], [f"{name}: not valid JSON ({exc})"]
if not isinstance(data, Mapping):
return [], [], [f"{name}: must be an object with work_packages and activities"]
packages = [p for p in data.get("work_packages") or [] if isinstance(p, Mapping)]
activities = [a for a in data.get("activities") or [] if isinstance(a, Mapping)]
return [dict(p) for p in packages], [dict(a) for a in activities], []
def check_work_breakdown(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = WORK_BREAKDOWN_FILE
packages, activities, problems = parse(attachments.get(name, ""))
if problems:
return problems
if not packages:
return [f"{name}: lists no work packages"]
if not activities:
return [f"{name}: lists no activities"]
ids = [str(p.get("id", "")) for p in packages]
problems += [f"{name}: a work package has no id"] if "" in ids else []
problems += [
f"{name}: work package id {dup} is used more than once"
for dup in sorted({i for i in ids if i and ids.count(i) > 1})
]
known = set(ids)
parents = {str(p.get("id")): p.get("parent") for p in packages}
for package in packages:
ident, parent = str(package.get("id")), package.get("parent")
if not _text(package.get("name")):
problems.append(f"{name}: {ident} has no name")
if parent is not None and str(parent) not in known:
problems.append(
f"{name}: {ident} has parent {parent}, which does not exist"
)
seen, node = {ident}, parent
while node is not None and str(node) in parents:
if str(node) in seen:
problems.append(f"{name}: {ident} is its own ancestor")
break
seen.add(str(node))
node = parents[str(node)]
graph = read_graph(upstream)
if graph is not None:
elements = {element.id for element in graph.elements}
covered: set[str] = set()
for package in packages:
listed = _list(package.get("elements"))
covered.update(listed)
problems += [
f"{name}: {package.get('id')} delivers {element}, which is not an "
"Element of the Target architecture"
for element in listed
if element not in elements
]
left = sorted(elements - covered)
if left:
problems.append(
f"{name}: no work package delivers {', '.join(left)}; every Element "
"of the Target architecture belongs to one"
)
activity_ids = [str(a.get("id", "")) for a in activities]
problems += [
f"{name}: activity id {dup} is used more than once"
for dup in sorted({i for i in activity_ids if i and activity_ids.count(i) > 1})
]
known_activities = set(activity_ids)
with_work = set()
for activity in activities:
ident = str(activity.get("id", ""))
if not ident or not _text(activity.get("name")):
problems.append(f"{name}: an activity needs an id and a name")
continue
within = str(activity.get("work_package", ""))
if within not in known:
problems.append(f"{name}: {ident} is in {within}, not a work package")
with_work.add(within)
days = activity.get("days")
if isinstance(days, bool) or not isinstance(days, (int, float)) or days <= 0:
problems.append(f"{name}: {ident} needs `days`, a number above 0")
elif days > MAX_DAYS:
problems.append(
f"{name}: {ident} is {days} days; split anything over {MAX_DAYS}"
)
problems += [
f"{name}: {ident} comes after {before}, which is not an activity"
for before in _list(activity.get("after"))
if before not in known_activities
]
if activity.get("owner", TEAM) not in OWNERS:
problems.append(f"{name}: {ident} owner must be one of {', '.join(OWNERS)}")
has_children = {str(parent) for parent in parents.values() if parent is not None}
problems += [
f"{name}: {ident} has no activity and no work package beneath it"
for ident in ids
if ident and ident not in with_work and ident not in has_children
]
if not problems and _cycle(activities):
problems.append(
f"{name}: activities depend on each other in a circle: "
+ " -> ".join(_cycle(activities))
)
return problems
def _cycle(activities: Sequence[Mapping[str, Any]]) -> list[str]:
"""Activities that depend on each other in a circle; empty when none do."""
after = {str(a["id"]): _list(a.get("after")) for a in activities}
state: dict[str, int] = {}
def visit(node: str, path: list[str]) -> list[str]:
state[node] = 1
for before in after.get(node, ()):
if state.get(before) == 1:
return (
[*path[path.index(before) :], before]
if before in path
else [before, node]
)
if state.get(before, 0) == 0:
found = visit(before, [*path, before])
if found:
return found
state[node] = 2
return []
for node in after:
if state.get(node, 0) == 0:
found = visit(node, [node])
if found:
return found
return []
def schedule(
activities: Sequence[Mapping[str, Any]], team_size: int = DEFAULT_TEAM_SIZE
) -> dict[str, Scheduled]:
"""Each activity's start and finish day, from Day 0.
An activity starts when everything it comes after has finished. The team's own
activities also wait for a free person: no more run at once than `team_size`.
What the customer owns, such as a supplier's lead time, takes nobody from the
team. The critical path is every activity with no slack: delay it and the end
moves.
"""
team_size = max(1, int(team_size))
by_id = {str(a["id"]): a for a in activities}
after = {ident: _list(a.get("after")) for ident, a in by_id.items()}
days = {ident: float(a["days"]) for ident, a in by_id.items()}
# The longest chain of work that follows an activity: what to start first when
# people are short.
followers: dict[str, list[str]] = {ident: [] for ident in by_id}
for ident, befores in after.items():
for before in befores:
followers[before].append(ident)
tail: dict[str, float] = {}
def remaining(ident: str) -> float:
if ident not in tail:
tail[ident] = days[ident] + max(
(remaining(f) for f in followers[ident]), default=0.0
)
return tail[ident]
start: dict[str, float] = {}
finish: dict[str, float] = {}
busy: list[tuple[float, float]] = [] # the team's activities already placed
pending = set(by_id)
while pending:
ready = [i for i in pending if all(b in finish for b in after[i])]
ready.sort(key=lambda i: (-remaining(i), i))
ident = min(
ready,
key=lambda i: (
max((finish[b] for b in after[i]), default=0.0),
-remaining(i),
i,
),
)
earliest = max((finish[b] for b in after[ident]), default=0.0)
if by_id[ident].get("owner", TEAM) == TEAM:
candidates = sorted({earliest, *(end for _, end in busy if end > earliest)})
for moment in candidates:
overlapping = sum(
1 for s, e in busy if s < moment + days[ident] and e > moment
)
if overlapping < team_size:
earliest = moment
break
busy.append((earliest, earliest + days[ident]))
start[ident], finish[ident] = earliest, earliest + days[ident]
pending.discard(ident)
end = max(finish.values(), default=0.0)
latest: dict[str, float] = {}
def latest_finish(ident: str) -> float:
if ident not in latest:
latest[ident] = min(
(latest_finish(f) - days[f] for f in followers[ident]), default=end
)
return latest[ident]
return {
ident: Scheduled(
ident,
start[ident],
finish[ident],
critical=latest_finish(ident) - finish[ident] < 1e-6,
)
for ident in by_id
}
# --- what the plan is checked against, from the agreed scope ----------------------------
def _scoped(scope: Mapping[str, Any], path: str) -> Any:
"""A field of the agreed scope, stated or assumed; None when it is neither."""
node: Any = scope.get("stated") or {}
for part in path.split("."):
node = node.get(part) if isinstance(node, Mapping) else None
if node is not None:
return node
for item in scope.get("assumed") or []:
if isinstance(item, Mapping) and item.get("field") == path:
return item.get("value")
return None
def delivery_terms(upstream: Upstream | None) -> dict[str, Any]:
"""Team size, working week, window and start date, from the agreed scope."""
scope = agreed_scope(upstream)
def number(path: str, default: int) -> int:
value = _scoped(scope, path)
ok = (
isinstance(value, (int, float))
and not isinstance(value, bool)
and value > 0
)
return int(value) if ok else default
window = _scoped(scope, "delivery.window_weeks")
start = _scoped(scope, "delivery.target_start_date")
try:
start_date = dt.date.fromisoformat(str(start)) if start else None
except ValueError:
start_date = None
return {
"team_size": number("delivery.team_size", DEFAULT_TEAM_SIZE),
"team_size_stated": _scoped(scope, "delivery.team_size") is not None,
"week": number("delivery.working_days_per_week", DEFAULT_WEEK),
"window_weeks": window if isinstance(window, (int, float)) else None,
"start": start_date,
}
# --- the three views --------------------------------------------------------------------
def _day(value: float) -> str:
return str(int(value)) if float(value).is_integer() else f"{value:.1f}"
def _calendar(start: dt.date, day: float, week: int) -> dt.date:
"""The calendar date of a working day counted from `start`."""
weeks, days = divmod(math.floor(day), week)
return start + dt.timedelta(days=weeks * 7 + days)
def render(attachments: Mapping[str, str], upstream: Upstream | None) -> str:
"""The WBS dictionary, the activity sequence and the timeline, as markdown
written from the data file. "" when the file cannot be read."""
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
if problems or not packages or not activities:
return ""
terms = delivery_terms(upstream)
plan = schedule(activities, terms["team_size"])
graph = read_graph(upstream)
checks: dict[str, list[str]] = {}
for check in graph.checks if graph else ():
checks.setdefault(check.applies_to, []).append(check.id)
parents = {str(p["id"]): p.get("parent") for p in packages}
def depth(ident: str) -> int:
level, node = 0, parents.get(ident)
while node is not None and str(node) in parents and level < 10:
level, node = level + 1, parents.get(str(node))
return level
effort: dict[str, float] = {}
for activity in activities:
effort[str(activity["work_package"])] = effort.get(
str(activity["work_package"]), 0.0
) + float(activity["days"])
def cell(value: Any) -> str:
return _text(value).replace("|", "\\|") or "-"
lines = [
f"## {DICTIONARY_HEADING}",
"",
"Each work package, what it delivers, and the Checks that say it is done.",
"",
"| Id | Work package | Scope | Produces | Elements | Done when these pass | Skills | Days |",
"| --- | --- | --- | --- | --- | --- | --- | --- |",
]
for package in packages:
ident = str(package["id"])
elements = _list(package.get("elements"))
accepted = [c for element in elements for c in checks.get(element, [])]
lines.append(
"| "
+ " | ".join(
[
ident,
("&nbsp;&nbsp;" * depth(ident)) + cell(package.get("name")),
cell(package.get("scope")),
cell("; ".join(_list(package.get("produces")))),
cell(", ".join(elements)),
cell(", ".join(accepted)),
cell(", ".join(_list(package.get("skills")))),
_day(effort[ident]) if ident in effort else "-",
]
)
+ " |"
)
ordered = sorted(activities, key=lambda a: (plan[str(a["id"])].start, str(a["id"])))
dated = terms["start"] is not None
lines += [
"",
"## Activity sequence",
"",
"| Id | Activity | Work package | Days | After | Start | Finish |"
+ (" Dates |" if dated else "")
+ " Owner | Critical |",
"| --- | --- | --- | --- | --- | --- | --- |"
+ (" --- |" if dated else "")
+ " --- | --- |",
]
for activity in ordered:
item = plan[str(activity["id"])]
row = [
str(activity["id"]),
cell(activity.get("name")),
str(activity.get("work_package")),
_day(float(activity["days"])),
cell(", ".join(_list(activity.get("after")))),
f"Day {_day(item.start)}",
f"Day {_day(item.finish)}",
]
if dated:
begins = _calendar(terms["start"], item.start, terms["week"])
ends = _calendar(terms["start"], max(item.finish - 1e-9, 0), terms["week"])
row.append(f"{begins.isoformat()} to {ends.isoformat()}")
row += [str(activity.get("owner", TEAM)), "yes" if item.critical else ""]
lines.append("| " + " | ".join(row) + " |")
total = max(item.finish for item in plan.values())
weeks = total / terms["week"]
lines += [
"",
"## Timeline",
"",
"```text",
*_chart(ordered, plan, total),
"```",
"",
]
summary = (
f"{_day(total)} working days, about {weeks:.1f} weeks, with a team of "
f"{terms['team_size']}"
+ (
""
if terms["team_size_stated"]
else " (assumed; the scope gives no team size)"
)
+ f" and a {terms['week']}-day week."
)
lines.append(summary)
window = terms["window_weeks"]
if window is not None:
if weeks <= window + 1e-9:
lines.append(
f"That is inside the {window}-week delivery window, with "
f"{window - weeks:.1f} weeks to spare."
)
else:
path = [str(a["id"]) for a in ordered if plan[str(a["id"])].critical]
lines.append(
f"**That is {weeks - window:.1f} weeks over the {window}-week delivery "
f"window.** The critical path is {' -> '.join(path)}: only shortening "
"or removing work on it, or adding people where it waits for them, "
"brings the end in."
)
theirs = [a for a in ordered if a.get("owner", TEAM) == CUSTOMER]
if theirs:
lines += ["", "The customer owns these, and the plan waits on them:"]
lines += [
f"- {a['id']} {_text(a.get('name'))}: {_day(float(a['days']))} days"
+ (f". {_text(a.get('assumption'))}" if _text(a.get("assumption")) else "")
for a in theirs
]
lines += [
"",
(
"Durations are estimates made without knowing the team, and are "
"indicative. Days are working days counted from Day 0, the day work "
"starts; each of the team's activities takes one person."
),
]
return "\n".join(lines) + "\n"
def _chart(
ordered: Sequence[Mapping[str, Any]], plan: Mapping[str, Scheduled], total: float
) -> list[str]:
"""The timeline as text: one row per activity along a relative day axis."""
scale = min(1.0, _CHART_WIDTH / total) if total else 1.0
labels = [f"{a['id']} {_text(a.get('name'))}"[:38] for a in ordered]
width = max(len(label) for label in labels) + 2
step = max(1, math.ceil(total / 6 / 5.0) * 5)
axis = [" "] * (int(total * scale) + 8)
for day in range(0, int(total) + 1, step):
mark = str(day)
at = int(day * scale)
axis[at : at + len(mark)] = mark
rows = [" " * width + "Day " + "".join(axis).rstrip()]
for label, activity in zip(labels, ordered, strict=True):
item = plan[str(activity["id"])]
begin = round(item.start * scale)
length = max(1, round((item.finish - item.start) * scale))
block = "░" if activity.get("owner", TEAM) == CUSTOMER else "█"
flag = " *" if item.critical else ""
rows.append(f"{label.ljust(width)} {' ' * begin}{block * length}{flag}")
rows += ["", "█ the team ░ the customer * on the critical path"]
return rows
def mermaid(attachments: Mapping[str, str], upstream: Upstream | None) -> str:
"""A Mermaid Gantt chart on calendar dates, when the scope gives a start date.
"" otherwise: a relative plan has no dates to draw."""
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
terms = delivery_terms(upstream)
if problems or not activities or terms["start"] is None:
return ""
plan = schedule(activities, terms["team_size"])
names = {str(p["id"]): _text(p.get("name")) for p in packages}
lines = ["gantt", " dateFormat YYYY-MM-DD", " excludes weekends"]
for package in packages:
own = [
a for a in activities if str(a.get("work_package")) == str(package["id"])
]
if not own:
continue
lines.append(f" section {names[str(package['id'])].replace(':', ' ')}")
for activity in sorted(own, key=lambda a: plan[str(a["id"])].start):
item = plan[str(activity["id"])]
begins = _calendar(terms["start"], item.start, terms["week"])
tag = "crit, " if item.critical else ""
label = _text(activity.get("name")).replace(":", " ")
lines.append(
f" {label} :{tag}{activity['id']}, {begins.isoformat()}, "
f"{max(1, math.ceil(float(activity['days'])))}d"
)
return "\n".join(lines) + "\n"
def summary(
attachments: Mapping[str, str], upstream: Upstream | None
) -> dict[str, Any]:
"""The plan in a few numbers, for an Approval and for the Execution's record."""
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
if problems or not activities:
return {}
terms = delivery_terms(upstream)
plan = schedule(activities, terms["team_size"])
total = max(item.finish for item in plan.values())
weeks = round(total / terms["week"], 1)
return {
"work_packages": len(packages),
"activities": len(activities),
"working_days": round(total, 1),
"weeks": weeks,
"team_size": terms["team_size"],
"window_weeks": terms["window_weeks"],
"within_window": None
if terms["window_weeks"] is None
else weeks <= terms["window_weeks"],
"critical_path": [i for i, item in plan.items() if item.critical],
}