Solution architecture outcome pattern: agent and its MCP servers
Some checks failed
check agents / check (push) Failing after 13s
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:
@@ -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)
|
||||
],
|
||||
}
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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"
|
||||
)
|
||||
@@ -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,
|
||||
)
|
||||
@@ -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:]))
|
||||
@@ -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"
|
||||
@@ -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,
|
||||
(" " * 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],
|
||||
}
|
||||
Reference in New Issue
Block a user