feat: working TOM agent

This commit is contained in:
2026-10-21 19:47:12 +01:00
commit efe543e6e2
83 changed files with 11779 additions and 0 deletions

View File

View File

@@ -0,0 +1,153 @@
"""The capability catalogue and the register of frameworks it cites.
Both are files of the `operating-capabilities` Skill. Code reads them to check that
every entry cites a registered framework, to propose the entries that apply to an
operating spec, and to check that a Capability names an entry that exists.
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import yaml
from app.operating_model import spec
SKILL = "operating-capabilities"
class CatalogueError(ValueError):
"""A catalogue or register that cannot be used; the message lists every fault."""
@dataclass(frozen=True)
class Entry:
id: str
name: str
domain: str
purpose: str
applies_when: Mapping[str, Any]
follows_support_hours: bool
typical_checks: tuple[str, ...]
sources: tuple[Mapping[str, str], ...]
@dataclass(frozen=True)
class Catalogue:
entries: Mapping[str, Entry]
frameworks: Mapping[str, Mapping[str, Any]]
verified: bool # whether a person has checked the references
def applicable(self, scope: Mapping[str, Any]) -> list[str]:
"""The entries that apply to an operating spec, in the catalogue's order.
A proposal: the Specialist decides, and says why one it leaves out does
not apply.
"""
kinds = {str(item.get("kind")) for item in spec.items(scope)}
frameworks = {
str(name) for name in spec.value(scope, "compliance.frameworks") or []
}
sourcing = spec.value(scope, "sourcing.model")
engagement = scope.get("kind") or spec.value(scope, "engagement.kind")
found = []
for entry in self.entries.values():
when = entry.applies_when
if (
when.get("always")
or kinds & set(when.get("item_kinds") or ())
or frameworks & set(when.get("compliance") or ())
or sourcing in (when.get("sourcing") or ())
or engagement in (when.get("engagement_kinds") or ())
):
found.append(entry.id)
return found
def _mapping(path: Path) -> dict[str, Any]:
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
if not isinstance(data, dict):
raise CatalogueError(f"{path.name}: must be a mapping")
return data
def load(skill_dir: Path) -> Catalogue:
"""Read the catalogue and its register from the Skill's folder, and check them."""
register = _mapping(skill_dir / "assets" / "sources.yaml")
frameworks = register.get("frameworks") or {}
problems = [
f"sources.yaml: {name} needs {field}"
for name, framework in frameworks.items()
for field in ("name", "publisher", "licence")
if not (framework or {}).get(field)
]
raw = _mapping(skill_dir / "assets" / "catalogue.yaml").get("capabilities") or []
entries: dict[str, Entry] = {}
for index, item in enumerate(raw):
where = f"catalogue.yaml[{index}]"
if not isinstance(item, Mapping) or not item.get("id"):
problems.append(f"{where}: needs an id")
continue
identifier = str(item["id"])
where = f"catalogue.yaml: {identifier}"
if identifier in entries:
problems.append(f"{where} is listed more than once")
problems += [
f"{where} needs {field}"
for field in ("name", "domain", "purpose", "applies_when")
if not item.get(field)
]
sources = [s for s in item.get("sources") or [] if isinstance(s, Mapping)]
if not sources:
problems.append(f"{where} cites no source")
for source in sources:
if source.get("framework") not in frameworks:
problems.append(
f"{where} cites {source.get('framework')!r}, which is not in "
"the register"
)
if not source.get("reference"):
problems.append(
f"{where} cites {source.get('framework')} with no reference"
)
entries[identifier] = Entry(
id=identifier,
name=str(item.get("name", "")),
domain=str(item.get("domain", "")),
purpose=str(item.get("purpose", "")),
applies_when=dict(item.get("applies_when") or {}),
follows_support_hours=bool(item.get("follows_support_hours")),
typical_checks=tuple(str(c) for c in item.get("typical_checks") or ()),
sources=tuple(
{
"framework": str(s.get("framework")),
"reference": str(s.get("reference")),
}
for s in sources
),
)
if problems:
raise CatalogueError("; ".join(problems))
return Catalogue(
entries=entries,
frameworks=dict(frameworks),
verified=register.get("status") == "verified",
)
def cited(catalogue: Catalogue, entry_ids: Sequence[str]) -> list[str]:
"""How the entries' sources are cited, one line a framework, for a reader."""
by_framework: dict[str, list[str]] = {}
for identifier in entry_ids:
entry = catalogue.entries.get(identifier)
for source in entry.sources if entry else ():
references = by_framework.setdefault(source["framework"], [])
if source["reference"] not in references:
references.append(source["reference"])
return [
f"{catalogue.frameworks[name]['name']}: {'; '.join(references)}"
for name, references in by_framework.items()
]

View File

@@ -0,0 +1,240 @@
"""The data files along the chain, and what each must hold.
operational-requirements.json what running the solution must achieve, each
traced to what the customer stated
capabilities.json what the operating organisation must be able to
do, each serving requirements and covering Items
target-operating-model.json who does it (see graph.py)
verdicts.json the 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.
"""
from __future__ import annotations
import json
from collections.abc import Callable, Mapping, Sequence
from typing import Any
from app.operating_model import spec
from app.operating_model.catalogue import Catalogue
from app.operating_model.names import (
CAPABILITIES_FILE,
CAPABILITY_MODEL,
CUSTOM,
HOURS,
OPERATIONAL_REQUIREMENTS,
REQUIREMENTS_FILE,
wider,
)
from app.operating_model.spec import Upstream
REQUIREMENT_KINDS = (
"service_level",
"process",
"organisation",
"tooling",
"compliance",
)
DataCheck = Callable[[Mapping[str, str], Upstream | None], list[str]]
def objects(text: str, name: str) -> tuple[list[dict[str, Any]], list[str]]:
"""The file's entries, and what is wrong with it as a list of objects with ids."""
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"]
problems = [
f"{name}[{index}]: must be an object with an id"
for index, item in enumerate(data)
if not isinstance(item, dict) or not str(item.get("id") or "").strip()
]
accepted = [
item
for item in data
if isinstance(item, dict) and str(item.get("id") or "").strip()
]
seen = [str(item["id"]) for item in accepted]
problems += [
f"{name}: id {identifier} is used more than once"
for identifier in sorted({i for i in seen if seen.count(i) > 1})
]
return accepted, problems
def read(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
"""An upstream data file's entries; none when it is absent or unreadable."""
text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "")
return objects(text, name)[0] if text else []
def requirements(upstream: Upstream | None) -> list[dict[str, Any]]:
return read(upstream, OPERATIONAL_REQUIREMENTS, REQUIREMENTS_FILE)
def capabilities(upstream: Upstream | None) -> list[dict[str, Any]]:
return read(upstream, CAPABILITY_MODEL, CAPABILITIES_FILE)
def _strings(item: Mapping[str, Any], field: str) -> list[str]:
found = item.get(field)
return [str(entry) for entry in found] if isinstance(found, list) else []
def check_requirements(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
"""Every Operational requirement is traced to what the customer stated, and
everything they stated that binds is carried by one."""
name = REQUIREMENTS_FILE
entries, problems = objects(attachments[name], name)
if not entries and not problems:
return [f"{name}: lists no Operational requirements"]
scope = spec.agreed(upstream)
stated = set(spec.ids(spec.stated_requirements(scope)))
# A business outcome may be what a requirement comes from. It need not be: what
# shows each outcome is served is a Measure, checked on the operating model.
outcomes = set(spec.ids(spec.business_outcomes(scope)))
kept_true = set(spec.ids(spec.conditions(scope)))
named: set[str] = set()
for entry in entries:
where = f"{name}: {entry['id']}"
if not str(entry.get("statement") or "").strip():
problems.append(f"{where} needs a statement")
if entry.get("kind") not in REQUIREMENT_KINDS:
problems.append(
f"{where}: kind must be one of {', '.join(REQUIREMENT_KINDS)}"
)
sources = _strings(entry, "source")
if not sources:
problems.append(
f"{where} has no source: name the stated requirement, the Condition "
"or the field of the operating spec it comes from"
)
for source in sources:
named.add(source)
known = (
source in stated
or source in outcomes
or source in kept_true
or spec.settled(scope, source)
)
if scope and not known:
problems.append(
f"{where}: source {source} is not a stated requirement, a "
"Condition or a settled field of the operating spec"
)
if scope:
problems += [
f"{name}: the customer's requirement {identifier} is carried by no "
"Operational requirement"
for identifier in sorted(stated - named)
]
problems += [
f"{name}: the customer stated {path}, and no Operational requirement "
"names it as a source"
for path in spec.binding(scope)
if path not in named
]
return problems
def check_capabilities(catalogue: Catalogue) -> DataCheck:
"""Every Capability comes from the catalogue, serves a requirement and covers
Items; every Item is covered and every requirement served."""
def check(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
name = CAPABILITIES_FILE
entries, problems = objects(attachments[name], name)
if not entries and not problems:
return [f"{name}: lists no Capabilities"]
scope = spec.agreed(upstream)
known_items = set(spec.ids(spec.items(scope)))
known_requirements = {str(r["id"]) for r in requirements(upstream)}
support = spec.value(scope, "operations.support_hours")
covered: set[str] = set()
served: set[str] = set()
for entry in entries:
where = f"{name}: {entry['id']}"
entry_id = entry.get("catalogue")
listed = catalogue.entries.get(str(entry_id))
if entry_id == CUSTOM:
if not str(entry.get("reason") or "").strip():
problems.append(f"{where} is custom and gives no reason")
if not str(entry.get("name") or "").strip():
problems.append(f"{where} is custom and needs a name")
elif listed is None:
problems.append(
f"{where}: {entry_id!r} is not in the capability catalogue; "
f"use an entry's id, or {CUSTOM} with a reason"
)
serves, on = _strings(entry, "serves"), _strings(entry, "items")
if not serves:
problems.append(f"{where} serves no Operational requirement")
served.update(serves)
covered.update(on)
if upstream is not None:
problems += [
f"{where} serves {identifier}, which is not an Operational requirement"
for identifier in serves
if identifier not in known_requirements
]
problems += [
f"{where} covers {identifier}, which is not an Item of the operating spec"
for identifier in on
if identifier not in known_items
]
hours = entry.get("hours")
if hours not in HOURS:
problems.append(f"{where}: hours must be one of {', '.join(HOURS)}")
elif (
listed is not None
and listed.follows_support_hours
and support in HOURS
and wider(str(support), str(hours))
):
problems.append(
f"{where}: faults are responded to {support}, and {listed.name} "
f"is staffed only {hours}"
)
effort = entry.get("effort_hours_per_month")
if (
isinstance(effort, bool)
or not isinstance(effort, (int, float))
or effort <= 0
):
problems.append(
f"{where}: effort_hours_per_month must be a number above zero"
)
if not str(entry.get("basis") or "").strip():
problems.append(f"{where} needs a basis for its effort")
if upstream is not None:
problems += [
f"{name}: Item {identifier} is covered by no Capability"
for identifier in sorted(known_items - covered)
]
problems += [
f"{name}: Operational requirement {identifier} is served by no Capability"
for identifier in sorted(known_requirements - served)
]
return problems
return check
def names_of(
capabilities_list: Sequence[Mapping[str, Any]], catalogue: Catalogue
) -> dict[str, str]:
"""Each Capability's name: its catalogue entry's, or its own when it is custom."""
return {
str(entry["id"]): (
catalogue.entries[str(entry.get("catalogue"))].name
if str(entry.get("catalogue")) in catalogue.entries
else str(entry.get("name") or entry["id"])
)
for entry in capabilities_list
}

View File

@@ -0,0 +1,413 @@
"""Digesting a solution architecture into an operating spec, in code.
The solution architecture agent delivers its design as data files. This reads the
ones an operating model depends on and writes the operating spec's fields from
them: nothing is summarised and nothing is guessed, so what is digested can be
counted against what was delivered.
components.json, products.json each component becomes an Item to be operated,
target-architecture.json with the Elements that realise it
requirements.json, what each says can only be shown in operation
recommendations.json (`outside_code`) becomes a Condition
verdicts.json a Check that failed or could not be verified
becomes an inherited risk
scope.json what the customer stated of operations, and of
the solution, is carried across as stated
work-breakdown.json, how long the build takes, and what the customer
execution.json owns of it
An Item is a component, not a resource: an organisation operates a hybrid
connectivity gateway, not each of its six routers and attachments. A Condition is
what the architecture itself says infrastructure code cannot verify: an
availability measured in operation, a recovery rehearsed. The settings its Checks
verified at build are kept true by configuration management, and are not Conditions.
Only what the customer stated in the architecture's scope is carried across as
stated. What that agent assumed for them is left to be asked again.
"""
from __future__ import annotations
import json
import math
import re
import sys
from collections.abc import Mapping, Sequence
from pathlib import Path
from typing import Any
import yaml
from execution_engine.workflows.workflow import Digested
GRAPH = "target-architecture.json"
COMPONENTS = "components.json"
PRODUCTS = "products.json"
REQUIREMENTS = "requirements.json"
RECOMMENDATIONS = "recommendations.json"
VERDICTS = "verdicts.json"
SCOPE = "scope.json"
PLAN = "work-breakdown.json"
MANIFEST = "execution.json"
# Every file the digest reads. A folder is read for these and nothing else.
FILES = (
MANIFEST,
SCOPE,
REQUIREMENTS,
RECOMMENDATIONS,
COMPONENTS,
PRODUCTS,
GRAPH,
VERDICTS,
PLAN,
)
DEFAULT_KIND = "service"
SOURCE_PREFIX = "architecture:"
_HOURS = {"business_hours": "business", "extended": "extended", "always": "24x7"}
_NUMBER = re.compile(r"\d+(?:\.\d+)?")
def _load(sources: Mapping[str, str], name: str) -> Any:
if name not in sources:
return None
try:
return json.loads(sources[name])
except ValueError as exc:
raise ValueError(f"{name}: not valid JSON ({exc})") from exc
def _records(data: Any) -> list[dict[str, Any]]:
return (
[item for item in data if isinstance(item, dict)]
if isinstance(data, list)
else []
)
def _within(document: Any, path: str) -> Any:
for part in path.split("."):
if not isinstance(document, Mapping) or part not in document:
return None
document = document[part]
return document
def kind_of(product: str, item_kinds: Mapping[str, Sequence[str]]) -> str:
"""What kind of thing a product is, by the words the provider bundle lists."""
lowered = product.lower()
for kind, words in item_kinds.items():
if any(str(word).lower() in lowered for word in words):
return kind
return DEFAULT_KIND
def item_kinds(root: Path, provider: str) -> dict[str, list[str]]:
"""The provider bundle's table of what kind of thing each product is."""
path = root / "providers" / f"{provider}.yaml"
data = yaml.safe_load(path.read_text(encoding="utf-8")) if path.is_file() else {}
kinds = ((data or {}).get("operating") or {}).get("item_kinds") or {}
return {
str(kind): [str(word) for word in words or []] for kind, words in kinds.items()
}
def architecture(
sources: Mapping[str, str], kinds: Mapping[str, Sequence[str]] | None = None
) -> Digested:
"""The operating spec's fields, read from a solution architecture's data files.
Returns nothing digested when the sources are not a solution architecture.
Raises ValueError, saying what is wrong, when they are one that cannot be used.
"""
if GRAPH not in sources:
return Digested({})
graph = _load(sources, GRAPH)
if not isinstance(graph, dict) or not isinstance(graph.get("elements"), list):
# A ValueError is what the engine turns into a refused start.
raise ValueError( # noqa: TRY004
f"{GRAPH}: must be an object with a list of elements"
)
manifest = _load(sources, MANIFEST) or {}
if manifest and manifest.get("status", "completed") != "completed":
raise ValueError(
f"{MANIFEST}: the Execution did not complete ({manifest.get('status')}); "
"an operating model is designed for an architecture that was approved"
)
elements = _records(graph["elements"])
components = _records(_load(sources, COMPONENTS))
product_of = {
str(item.get("component")): str(item.get("product"))
for item in _records(_load(sources, PRODUCTS))
}
kinds = kinds or {}
notes: dict[str, str] = {}
# --- Items: one a component, with the Elements that realise it -------------------
realised: dict[str, list[dict[str, Any]]] = {}
for element in elements:
realised.setdefault(str(element.get("component") or ""), []).append(element)
if not components:
components = [
{"id": identifier, "name": identifier, "requirements": []}
for identifier in realised
if identifier
]
items: list[dict[str, Any]] = []
item_of: dict[str, str] = {}
for component in components:
component_id = str(component.get("id"))
own = realised.get(component_id, [])
products = [str(e.get("product")) for e in own if e.get("product")]
product = product_of.get(component_id) or (
max(set(products), key=products.count) if products else ""
)
item_id = f"S-{len(items) + 1}"
item_of[component_id] = item_id
items.append(
{
"id": item_id,
"name": str(component.get("name") or component_id),
"kind": kind_of(product, kinds),
**({"product": product} if product else {}),
"source_ref": component_id,
"elements": [str(e.get("id")) for e in own],
}
)
loose = realised.get("", [])
if loose:
# Elements the architecture filed under no component are still operated.
item_id = f"S-{len(items) + 1}"
item_of[""] = item_id
items.append(
{
"id": item_id,
"name": "Resources outside any component",
"kind": DEFAULT_KIND,
"elements": [str(e.get("id")) for e in loose],
}
)
if not items:
raise ValueError(f"{GRAPH}: lists no Elements to operate")
placed = sum(len(item["elements"]) for item in items)
if placed != len(elements):
unplaced = sorted(
str(e.get("id"))
for e in elements
if str(e.get("component") or "") not in item_of
)
raise ValueError(
f"{GRAPH}: these Elements name a component that {COMPONENTS} does not "
f"have: {', '.join(unplaced)}"
)
notes["solution.items"] = (
f"{len(items)} components of the solution architecture, standing for "
f"{len(elements)} Elements"
)
# --- Conditions: what can only be shown to hold in operation --------------------
serving: dict[str, list[str]] = {}
for component in components:
for requirement in component.get("requirements") or []:
serving.setdefault(str(requirement), []).append(str(component.get("id")))
conditions: list[dict[str, Any]] = []
stated = 0
for name in (REQUIREMENTS, RECOMMENDATIONS):
for entry in _records(_load(sources, name)):
if entry.get("change") == "removed":
continue
entry_id = str(entry.get("id"))
behind = [str(c) for c in entry.get("components") or []] or serving.get(
entry_id, []
)
on = [item_of[c] for c in behind if c in item_of] or [
str(i["id"]) for i in items
]
for statement in entry.get("outside_code") or []:
stated += 1
conditions.append(
{
"id": f"K-{len(conditions) + 1}",
"on": on,
"condition": " ".join(str(statement).split()),
"source_ref": entry_id,
}
)
if len(conditions) != stated:
raise ValueError(
"a condition the architecture leaves to operation was not placed"
)
if conditions:
notes["solution.conditions"] = (
f"{len(conditions)} conditions the solution architecture says cannot be "
"verified from infrastructure code"
)
# --- Inherited risks: Checks that did not pass ------------------------------------
element_item = {
str(e.get("id")): item_of.get(str(e.get("component") or ""), items[0]["id"])
for e in elements
}
check_on = {
str(check.get("id")): element_item.get(
str(check.get("applies_to")), items[0]["id"]
)
for check in _records(graph.get("checks"))
}
statement_of = {
str(check.get("id")): str(check.get("statement") or "")
for check in _records(graph.get("checks"))
}
verdicts = _load(sources, VERDICTS) or {}
risks = [
{
"on": check_on.get(str(item.get("check")), items[0]["id"]),
"risk": (
f"Check {item.get('check')} "
+ (
"failed"
if item.get("verdict") == "fail"
else "could not be verified"
)
+ f" in validation: {statement_of.get(str(item.get('check')), '')} "
f"({' '.join(str(item.get('evidence') or '').split())})"
).strip(),
"source_ref": str(item.get("check")),
}
for item in _records(
verdicts.get("checks") if isinstance(verdicts, dict) else None
)
if item.get("verdict") in ("fail", "not_verifiable")
]
# --- What the customer stated, carried across as stated --------------------------
scope = _load(sources, SCOPE) or {}
said = scope.get("stated") if isinstance(scope, dict) else {}
spec: dict[str, Any] = {
"solution": {
"items": items,
**({"conditions": conditions} if conditions else {}),
}
}
def put(path: str, value: Any, note: str = "") -> None:
if value in (None, "", [], {}):
return
node = spec
*parents, last = path.split(".")
for part in parents:
node = node.setdefault(part, {})
node[last] = value
if note:
notes[path] = note
if risks:
put("solution.inherited_risks", risks, f"{VERDICTS}: Checks that did not pass")
execution_id = manifest.get("execution_id")
put("metadata.customer_case", manifest.get("customer_case"))
put(
"metadata.source",
f"{SOURCE_PREFIX}{execution_id}"
if execution_id
else f"{SOURCE_PREFIX}unverified",
"the Execution these files are of"
if execution_id
else f"no {MANIFEST} came with the files, so they are not known to be one "
"completed Execution",
)
put("engagement.kind", scope.get("kind") if isinstance(scope, dict) else None)
put(
"intent.statement",
manifest.get("workflow_request") or _within(said, "intent.statement"),
"the request the solution architecture was designed for",
)
criteria = _within(said, "intent.success_criteria")
put(
"intent.business_outcomes",
[
{"id": f"BO-{n}", "outcome": " ".join(str(text).split())}
for n, text in enumerate(criteria or [], start=1)
if str(text).strip()
]
if isinstance(criteria, list)
else None,
f"{SCOPE}: the success criteria the customer stated",
)
put("solution.cloud_provider", _within(said, "estate.cloud_provider"))
hours = _within(said, "operations.support_hours")
put("operations.support_hours", _HOURS.get(str(hours)), f"{SCOPE}: {hours}")
available = _within(said, "workload.availability.hours")
put(
"operations.availability_hours",
_HOURS.get(str(available)),
f"{SCOPE}: {available}",
)
put("operations.change_process", _within(said, "operations.change_process"))
put("operations.monitoring", _within(said, "operations.monitoring"))
put("compliance.frameworks", _within(said, "compliance.frameworks"))
recovery = _NUMBER.search(
str(_within(said, "workload.availability.recovery_time") or "")
)
put(
"service_levels.recovery_time_hours",
float(recovery.group()) if recovery else None,
)
currency = _within(said, "cost.currency")
put("commercial.currency", currency if isinstance(currency, str) else None)
plan = manifest.get("delivery_plan") if isinstance(manifest, dict) else None
days = (plan or {}).get("working_days")
if isinstance(days, (int, float)) and not isinstance(days, bool):
put(
"solution.build.duration_days",
math.ceil(days),
"the build's computed length, in working days",
)
activities = _records((_load(sources, PLAN) or {}).get("activities"))
put(
"solution.build.customer_owned",
[str(a.get("name")) for a in activities if a.get("owner") == "customer"],
f"{PLAN}: the activities the customer owns",
)
return Digested(
spec=spec, used=tuple(n for n in FILES if n in sources), notes=notes
)
def read_folder(folder: Path) -> dict[str, str]:
"""The data files of an architecture Execution's folder that the digest reads."""
return {
name: (folder / name).read_text(encoding="utf-8")
for name in FILES
if (folder / name).is_file()
}
def main(arguments: Sequence[str]) -> int:
"""`python -m app.operating_model.digest <folder> [provider]`: print the operating
spec digested from an architecture Execution's folder, and what is left to settle."""
from app.operating_model.workflow import ROOT
if not arguments:
print(main.__doc__, file=sys.stderr)
return 2
folder = Path(arguments[0])
provider = arguments[1] if len(arguments) > 1 else "gcp"
sources = read_folder(folder)
try:
digested = architecture(sources, item_kinds(ROOT, provider))
except ValueError as exc:
print(f"Cannot digest {folder}: {exc}", file=sys.stderr)
return 1
if not digested.spec:
print(
f"{folder} holds no {GRAPH}: it is not a solution architecture.",
file=sys.stderr,
)
return 1
print(yaml.safe_dump(dict(digested.spec), sort_keys=False, allow_unicode=True))
for path, note in digested.notes.items():
print(f"# {path}: {note}", file=sys.stderr)
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))

View File

@@ -0,0 +1,719 @@
"""The Target operating model: one explicit graph, checked before anything is derived.
parties the organisations with a part in operating the solution
teams optional: the teams within a Party, each of one of Team
Topologies' four kinds
roles positions in a Party, each in a country and at a level, and
in a team when there are teams
interactions optional: how two teams work together, in one of Team
Topologies' three modes; a collaboration says when it ends
measures what is measured to show each business outcome the customer
stated is being served, at which layer, and by which
Capability
responsibilities a Role's part in a Capability: accountable, responsible,
consulted or informed
checks numbered, verifiable conditions on a Capability, a Role or a
Responsibility, each traced to what it comes from
The Capabilities are the capability model's, by id. A submission is refused while
the graph does not hold together, so what the customer approves is complete: every
Capability has one Role answerable for it and someone to do it at the hours it is
needed, and everything the customer said must be kept true is carried by a Check.
The responsibility matrix, the organisation chart and the staffing and cost are
written from the graph by code, as views of it.
"""
from __future__ import annotations
import json
from collections.abc import Callable, Collection, Mapping, Sequence
from typing import Any
from execution_engine.workflows.deliverables import GraphShape, ListShape
from app.operating_model import chain, spec, staffing
from app.operating_model.catalogue import Catalogue
from app.operating_model.names import (
ACCOUNTABLE,
COLLABORATION,
DEVELOPER_LAYERS,
FINDINGS_FILE,
GRAPH_FILE,
HOURS,
INTERACTION_MODES,
MEASURE_LAYERS,
MEASUREMENT_ENTRY,
PARTY_KINDS,
RESPONSIBILITY_KINDS,
RESPONSIBLE,
TARGET_OPERATING_MODEL,
TEAM_TYPES,
wider,
)
from app.operating_model.spec import Upstream
from app.operating_model.staffing import RateCard
LISTS = (
"parties",
"teams",
"roles",
"responsibilities",
"interactions",
"measures",
"checks",
)
OUTCOMES_HEADING = "Business outcomes"
MATRIX_HEADING = "Responsibility matrix"
STAFFING_HEADING = "Staffing and cost"
FINDINGS_HEADING = "Findings"
_LETTER = {"accountable": "A", "responsible": "R", "consulted": "C", "informed": "I"}
# The graph as the operating-model architect builds it, a few items at a time.
SHAPE = GraphShape(
attachment=GRAPH_FILE,
lists={
"parties": ListShape(("id", "name", "kind"), label="Parties"),
"teams": ListShape(
("id", "party", "name", "type"), optional=("purpose",), label="Teams"
),
"roles": ListShape(
("id", "party", "name", "country", "level", "hours"),
optional=("skills", "team"),
label="Roles",
),
"interactions": ListShape(
("id", "from", "to", "mode"),
optional=("purpose", "until"),
label="Interactions",
),
"measures": ListShape(
("id", "name", "layer", "outcome", "measured_by"),
optional=("framework", "target"),
label="Measures",
),
"responsibilities": ListShape(
("id", "capability", "role", "kind"),
optional=("share",),
label="Responsibilities",
),
"checks": ListShape(
("id", "on", "condition", "source"),
optional=("depends_on_finding",),
label="Checks",
),
},
)
def parse(text: str) -> tuple[dict[str, list[dict[str, Any]]], list[str]]:
"""The graph's four lists, and what is wrong with the file's shape."""
try:
data = json.loads(text)
except ValueError as exc:
return {name: [] for name in LISTS}, [f"{GRAPH_FILE}: not valid JSON ({exc})"]
if not isinstance(data, dict):
return {name: [] for name in LISTS}, [
f"{GRAPH_FILE}: must be an object with {', '.join(LISTS)}"
]
graph: dict[str, list[dict[str, Any]]] = {}
problems = []
for name in LISTS:
entries = data.get(name) or []
if not isinstance(entries, list):
problems.append(f"{GRAPH_FILE}: {name} must be a list")
entries = []
graph[name] = [dict(item) for item in entries if isinstance(item, dict)]
for index, item in enumerate(entries):
where = f"{GRAPH_FILE}: {name}[{index}]"
if not isinstance(item, dict):
problems.append(f"{where} must be an object")
continue
missing = [
field
for field in SHAPE.lists[name].required
if not str(item.get(field) or "").strip()
]
if missing:
problems.append(
f"{where} ({item.get('id', 'no id')}) needs {', '.join(missing)}"
)
seen = [str(item.get("id")) for item in graph[name] if item.get("id")]
problems += [
f"{GRAPH_FILE}: id {identifier} is used more than once in {name}"
for identifier in sorted({i for i in seen if seen.count(i) > 1})
]
return graph, problems
def read(upstream: Upstream | None) -> dict[str, list[dict[str, Any]]] | None:
"""The submitted graph from the Deliverables a submission builds on."""
text = (
((upstream or {}).get(TARGET_OPERATING_MODEL) or {})
.get("attachments", {})
.get(GRAPH_FILE, "")
)
return parse(text)[0] if text else None
def findings(attachments: Mapping[str, str]) -> list[dict[str, Any]]:
text = attachments.get(FINDINGS_FILE, "")
return chain.objects(text, FINDINGS_FILE)[0] if text.strip() else []
def check(card: RateCard, frameworks: Collection[str] = ()) -> chain.DataCheck:
"""What is wrong with a Target operating model, against the capability model,
the operating spec and the rate card. `frameworks` are the register's, which a
Measure may name."""
def checked(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
graph, problems = parse(attachments[GRAPH_FILE])
if problems:
return problems
name = GRAPH_FILE
scope = spec.agreed(upstream)
capabilities = chain.capabilities(upstream)
capability_ids = {str(c["id"]) for c in capabilities}
requirement_ids = {str(r["id"]) for r in chain.requirements(upstream)}
conditions = spec.ids(spec.conditions(scope))
parties = {str(p["id"]): p for p in graph["parties"]}
roles = {str(r["id"]): r for r in graph["roles"]}
for party in graph["parties"]:
if party.get("kind") not in PARTY_KINDS:
problems.append(
f"{name}: Party {party['id']}: kind must be one of "
f"{', '.join(PARTY_KINDS)}"
)
allowed = [
str(c) for c in spec.value(scope, "sourcing.delivery_countries") or []
]
for role in graph["roles"]:
where = f"{name}: Role {role['id']}"
if role.get("party") not in parties:
problems.append(
f"{where} is in {role.get('party')}, which is not a Party"
)
if role.get("hours") not in HOURS:
problems.append(f"{where}: hours must be one of {', '.join(HOURS)}")
country = str(role.get("country"))
if country not in card.countries:
problems.append(
f"{where} sits in {country}, which the rate card does not have: "
f"{', '.join(sorted(card.countries))}"
)
elif allowed and country not in allowed:
problems.append(
f"{where} sits in {country}; the customer allows only "
f"{', '.join(allowed)}"
)
if str(role.get("level")) not in card.levels:
problems.append(
f"{where} is at level {role.get('level')}, which the rate card "
f"does not have: {', '.join(card.levels)}"
)
problems += check_teams(graph, parties, name)
by_capability: dict[str, list[dict[str, Any]]] = {}
for item in graph["responsibilities"]:
where = f"{name}: Responsibility {item['id']}"
if item.get("kind") not in RESPONSIBILITY_KINDS:
problems.append(
f"{where}: kind must be one of {', '.join(RESPONSIBILITY_KINDS)}"
)
if item.get("role") not in roles:
problems.append(
f"{where} names {item.get('role')}, which is not a Role"
)
if upstream is not None and item.get("capability") not in capability_ids:
problems.append(
f"{where} names {item.get('capability')}, which is not a "
"Capability of the capability model"
)
by_capability.setdefault(str(item.get("capability")), []).append(item)
for capability in capabilities:
identifier = str(capability["id"])
held = by_capability.get(identifier, [])
accountable = [r for r in held if r.get("kind") == ACCOUNTABLE]
responsible = [r for r in held if r.get("kind") == RESPONSIBLE]
if len(accountable) != 1:
problems.append(
f"{name}: Capability {identifier} has {len(accountable)} "
"accountable Roles; it needs exactly one"
)
if not responsible:
problems.append(
f"{name}: Capability {identifier} has no responsible Role"
)
continue
needed = str(capability.get("hours"))
worked = [
str(roles[str(r["role"])].get("hours"))
for r in responsible
if r.get("role") in roles
]
if (
needed in HOURS
and worked
and all(hours in HOURS and wider(needed, hours) for hours in worked)
):
problems.append(
f"{name}: Capability {identifier} is needed {needed}, and no "
"Role responsible for it works those hours"
)
problems += [
f"{name}: {fault}"
for fault in staffing.shares(graph["responsibilities"])[1]
]
found = findings(attachments)
finding_ids = {str(item["id"]) for item in found}
on = (
capability_ids
| set(roles)
| {str(r["id"]) for r in graph["responsibilities"]}
| {str(team["id"]) for team in graph["teams"]}
| {str(i["id"]) for i in graph["interactions"]}
| {str(m["id"]) for m in graph["measures"]}
)
carried: set[str] = set()
for item in graph["checks"]:
where = f"{name}: Check {item['id']}"
source = str(item.get("source"))
carried.add(source)
if upstream is not None and item.get("on") not in on:
problems.append(
f"{where} is on {item.get('on')}, which is not a Capability, a "
"Role or a Responsibility"
)
if upstream is not None and source not in requirement_ids | set(conditions):
problems.append(
f"{where}: source {source} is not an Operational requirement "
"or a Condition"
)
depends = item.get("depends_on_finding")
if depends and depends not in finding_ids:
problems.append(f"{where} depends on {depends}, which is not a finding")
problems += [
f"{name}: Condition {identifier} is carried by no Check"
for identifier in conditions
if identifier not in carried
]
problems += check_measures(
graph, scope, capabilities, by_capability, roles, frameworks, name
)
problems += check_findings(
attachments,
scope,
on | {str(c["id"]) for c in graph["checks"]} | requirement_ids,
)
return problems
return checked
def check_teams(
graph: Mapping[str, Sequence[Mapping[str, Any]]],
parties: Mapping[str, Any],
name: str,
) -> list[str]:
"""What is wrong with the teams and how they work together.
Teams are optional. When there are any, each is of one of Team Topologies' four
kinds, a Role in a team belongs to that team's Party, and two teams work
together in one of its three modes. A collaboration is a stage, not a standing
arrangement: it says when it ends.
"""
problems = []
teams = {str(team["id"]): team for team in graph["teams"]}
for team in graph["teams"]:
where = f"{name}: Team {team['id']}"
if team.get("type") not in TEAM_TYPES:
problems.append(f"{where}: type must be one of {', '.join(TEAM_TYPES)}")
if team.get("party") not in parties:
problems.append(f"{where} is in {team.get('party')}, which is not a Party")
for role in graph["roles"]:
team_id = role.get("team")
if not team_id:
continue
found = teams.get(str(team_id))
if found is None:
problems.append(
f"{name}: Role {role['id']} is in {team_id}, which is not a Team"
)
elif found.get("party") != role.get("party"):
problems.append(
f"{name}: Role {role['id']} is in {role.get('party')}, and its team "
f"{team_id} is in {found.get('party')}"
)
for item in graph["interactions"]:
where = f"{name}: Interaction {item['id']}"
if item.get("mode") not in INTERACTION_MODES:
problems.append(
f"{where}: mode must be one of {', '.join(INTERACTION_MODES)}"
)
for end in ("from", "to"):
if item.get(end) not in teams:
problems.append(f"{where}: {end} {item.get(end)} is not a Team")
if item.get("from") == item.get("to"):
problems.append(f"{where} is between a team and itself")
if (
item.get("mode") == COLLABORATION
and not str(item.get("until") or "").strip()
):
problems.append(
f"{where} is a collaboration and does not say when it ends: give "
"`until`, and what the teams work in after"
)
return problems
def check_measures(
graph: Mapping[str, Sequence[Mapping[str, Any]]],
scope: Mapping[str, Any],
capabilities: Sequence[Mapping[str, Any]],
by_capability: Mapping[str, Sequence[Mapping[str, Any]]],
roles: Mapping[str, Any],
frameworks: Collection[str],
name: str,
) -> list[str]:
"""Every business outcome the customer stated is shown by something measured,
and everything measured shows one: nothing is measured for its own sake.
A Measure is taken by a Capability someone is responsible for. Where the model
measures how work flows, it measures all three layers: delivery outcomes,
sustainable productivity and friction. No one of them stands in for the others.
"""
problems = []
outcomes = {str(o["id"]): o for o in spec.business_outcomes(scope)}
capability_ids = {str(c["id"]) for c in capabilities}
measured: set[str] = set()
for item in graph["measures"]:
where = f"{name}: Measure {item['id']}"
if item.get("layer") not in MEASURE_LAYERS:
problems.append(
f"{where}: layer must be one of {', '.join(MEASURE_LAYERS)}"
)
outcome = str(item.get("outcome"))
measured.add(outcome)
if outcome not in outcomes:
problems.append(
f"{where} shows {outcome}, which is not a business outcome the "
"customer stated"
+ (f": {', '.join(outcomes)}" if outcomes else "; none were stated")
)
taker = str(item.get("measured_by"))
if taker not in capability_ids:
problems.append(
f"{where} is measured by {taker}, which is not a Capability"
)
elif not any(
r.get("kind") == "responsible" and r.get("role") in roles
for r in by_capability.get(taker, ())
):
problems.append(
f"{where} is measured by {taker}, and nobody is responsible for it"
)
if item.get("framework") and frameworks and item["framework"] not in frameworks:
problems.append(
f"{where} names framework {item['framework']}, which is not in the register"
)
problems += [
f"{name}: business outcome {identifier} ({outcomes[identifier].get('outcome')}) "
"is shown by no Measure"
for identifier in outcomes
if identifier not in measured
]
measurers = {
str(c["id"]) for c in capabilities if c.get("catalogue") == MEASUREMENT_ENTRY
}
# Only once there is an outcome to tie Measures to: with none, no Measure can
# be accepted, and asking for three of them could never be met.
if measurers and outcomes:
layers = {
str(m.get("layer"))
for m in graph["measures"]
if m.get("measured_by") in measurers
}
missing = [layer for layer in DEVELOPER_LAYERS if layer not in layers]
if missing:
problems.append(
f"{name}: {', '.join(sorted(measurers))} measures how work flows and has "
f"no Measure at the {', '.join(missing)} layer; each layer answers a "
"different question and none stands in for another"
)
return problems
def render_outcomes(
graph: Mapping[str, Sequence[Mapping[str, Any]]],
scope: Mapping[str, Any],
names: Mapping[str, str],
) -> str:
"""Each business outcome, with what shows it is served and who answers for it."""
outcomes = spec.business_outcomes(scope)
if not outcomes:
return (
"The customer stated no business outcomes, so nothing in this operating "
"model is tied to one. Ask what the business wants from the solution, "
"and how it would know."
)
roles = {str(r["id"]): r for r in graph["roles"]}
answerable: dict[str, str] = {}
for item in graph["responsibilities"]:
if item.get("kind") == "accountable" and item.get("role") in roles:
answerable[str(item.get("capability"))] = str(
roles[str(item["role"])].get("name")
)
lines = []
for outcome in outcomes:
target = f" Target: {outcome['target']}." if outcome.get("target") else ""
lines += [f"**{outcome['id']}: {outcome.get('outcome')}**{target}", ""]
shown = [m for m in graph["measures"] if m.get("outcome") == outcome["id"]]
if not shown:
lines += ["Nothing measured shows this outcome.", ""]
continue
lines += [
"| Measure | Layer | Framework | Target | Measured by | Answerable |",
"| --- | --- | --- | --- | --- | --- |",
]
lines += [
f"| {m.get('name')} | {str(m.get('layer', '')).replace('_', ' ')} | "
f"{m.get('framework') or ''} | {m.get('target') or ''} | "
f"{names.get(str(m.get('measured_by')), m.get('measured_by'))} | "
f"{answerable.get(str(m.get('measured_by')), '')} |"
for m in shown
]
lines.append("")
return "\n".join(lines).rstrip()
def check_findings(
attachments: Mapping[str, str], scope: Mapping[str, Any], known: set[str]
) -> list[str]:
"""What is wrong with findings.json. It may be an empty list."""
text = attachments.get(FINDINGS_FILE, "")
if not text.strip():
return []
entries, problems = chain.objects(text, FINDINGS_FILE)
item_ids = set(spec.ids(spec.items(scope)))
for entry in entries:
where = f"{FINDINGS_FILE}: {entry['id']}"
for field in ("lacks", "proposed"):
if not str(entry.get(field) or "").strip():
problems.append(f"{where} needs {field}")
about = [str(i) for i in entry.get("about") or []]
needed_by = [str(i) for i in entry.get("needed_by") or []]
if not about:
# A finding is about the solution: it names what in it is lacking.
problems.append(
f"{where} names no Item of the solution under about. What the "
"operating model can provide itself, such as staffing, hours, a Role, "
"a process or a tool, is not a finding: design it"
)
if not needed_by:
problems.append(f"{where} must say what needs it, under needed_by")
problems += [
f"{where} is about {identifier}, which is not an Item of the operating spec"
for identifier in about
if scope and identifier not in item_ids
]
problems += [
f"{where} is needed by {identifier}, which is not in the operating model"
for identifier in needed_by
if identifier not in known
]
return problems
# --- the views code writes -----------------------------------------------------------
def render_matrix(
graph: Mapping[str, Sequence[Mapping[str, Any]]], names: Mapping[str, str]
) -> str:
"""Who is accountable, responsible, consulted and informed for each Capability."""
roles = list(graph["roles"])
# A Role may hold more than one part in a Capability: answerable for it and
# doing it. Both are shown.
held: dict[tuple[str, str], str] = {}
for item in graph["responsibilities"]:
key = (str(item.get("capability")), str(item.get("role")))
letter = _LETTER.get(str(item.get("kind")), "?")
held[key] = f"{held[key]}/{letter}" if key in held else letter
header = "| Capability | " + " | ".join(str(r.get("name")) for r in roles) + " |"
rule = "| --- | " + " | ".join("---" for _ in roles) + " |"
rows = [
f"| {name} ({identifier}) | "
+ " | ".join(held.get((identifier, str(r["id"])), "") for r in roles)
+ " |"
for identifier, name in names.items()
]
legend = "A accountable, R responsible, C consulted, I informed."
return "\n".join([f"## {MATRIX_HEADING}", "", header, rule, *rows, "", legend, ""])
def _node(identifier: Any) -> str:
return str(identifier).replace("-", "_")
def _role_node(role: Mapping[str, Any], indent: str) -> str:
return (
f'{indent}{_node(role["id"])}["{role.get("name")}<br/>{role.get("country")}, '
f'{role.get("level")}, {role.get("hours")}"]'
)
def render_organisation(graph: Mapping[str, Sequence[Mapping[str, Any]]]) -> str:
"""The Parties, their teams and the Roles in each, and how the teams work
together, as a Mermaid chart."""
teams = graph.get("teams") or []
lines = ["flowchart TB"]
for party in graph["parties"]:
lines.append(
f' subgraph {_node(party["id"])}["{party.get("name")} ({party.get("kind")})"]'
)
for team in teams:
if team.get("party") != party["id"]:
continue
kind = str(team.get("type", "")).replace("_", "-")
lines.append(
f' subgraph {_node(team["id"])}["{team.get("name")} ({kind} team)"]'
)
lines += [
_role_node(role, " ")
for role in graph["roles"]
if role.get("team") == team["id"]
]
lines.append(" end")
lines += [
_role_node(role, " ")
for role in graph["roles"]
if role.get("party") == party["id"] and not role.get("team")
]
lines.append(" end")
for item in graph.get("interactions") or []:
mode = str(item.get("mode", "")).replace("_", "-")
label = mode + (f" until {item['until']}" if item.get("until") else "")
lines.append(f' {_node(item["from"])} -- "{label}" --> {_node(item["to"])}')
return "\n".join(lines) + "\n"
def _money(amount: Any, currency: str) -> str:
return "not priced" if amount is None else f"{amount:,} {currency}"
def render_staffing(result: Mapping[str, Any], budget: Any = None) -> str:
"""People and cost per Role and in total, with the prices they were worked from."""
currency = str(result["currency"])
card = result["rate_card"]
conversion = result["conversion"]
lines = [
f"## {STAFFING_HEADING}",
"",
"| Role | Party | Country | Level | Hours | Effort a month | People | Cost a month |",
"| --- | --- | --- | --- | --- | --- | --- | --- |",
]
lines += [
f"| {row['name']} | {row.get('party_name', row['party'])} | "
f"{row['country']} | {row['level']} | "
f"{row['hours']} | {row['effort_hours_per_month']} h | {row['people']} | "
f"{_money(row['cost_per_month'], currency)} |"
for row in result["roles"]
]
lines += [
"",
(
f"{result['people']} people in all. Cost a month: "
f"{_money(result['cost_per_month'], currency)}."
),
]
if isinstance(budget, (int, float)) and not isinstance(budget, bool):
over = result["cost_per_month"] - budget
lines.append(
f"The monthly budget is {_money(round(budget), currency)}: "
+ (
f"this is over it by {_money(round(over), currency)}."
if over > 0
else "this is within it."
)
)
lines += [
"",
f"Worked from rate card `{card['name']}`, version `{card['version']}`"
+ (
". **Its figures are placeholders: no price has been set, and this cost "
"is an illustration.**"
if card["draft"]
else "."
),
]
if conversion["from"] != currency:
lines.append(
f"Converted from {conversion['from']} at {conversion['rate']}, a rate "
f"set on {conversion['as_of']}."
)
lines += [
(
"The customer's own staff are counted and not priced. A Role that covers "
"hours wider than a working day is never smaller than the team that can "
"cover them."
),
"",
]
return "\n".join(lines)
def render_findings(found: Sequence[Mapping[str, Any]]) -> str:
if not found:
return ""
lines = [
f"## {FINDINGS_HEADING}",
"",
(
"What operating this solution needs that the solution, as described, does "
"not provide. Nothing here was designed around: each is for whoever owns "
"the design."
),
"",
]
lines += [
f"- **{item['id']}** ({', '.join(str(i) for i in item.get('about') or []) or 'the solution'}): "
f"{item.get('lacks')} Proposed: {item.get('proposed')}"
for item in found
]
return "\n".join(lines) + "\n"
Views = Callable[[str, dict[str, str], Upstream | None], tuple[str, dict[str, str]]]
def views(catalogue: Catalogue, card: RateCard) -> Views:
"""Add the matrix, the staffing and the findings to an accepted submission."""
from app.operating_model.names import ORGANISATION_FILE, STAFFING_FILE
def add(
content: str, attachments: dict[str, str], upstream: Upstream | None
) -> tuple[str, dict[str, str]]:
graph, _ = parse(attachments[GRAPH_FILE])
scope = spec.agreed(upstream)
capabilities = chain.capabilities(upstream)
currency = str(spec.value(scope, "commercial.currency") or card.currency)
result = staffing.compute(graph, capabilities, card, currency)
found = findings(attachments)
# A Revision replaces these sections, never stacks a second copy.
content = content.split(f"\n## {MATRIX_HEADING}")[0].rstrip()
parts = [
content,
render_matrix(graph, chain.names_of(capabilities, catalogue)),
render_staffing(result, spec.value(scope, "commercial.monthly_run_budget")),
render_findings(found),
]
attachments[ORGANISATION_FILE] = render_organisation(graph)
attachments[STAFFING_FILE] = json.dumps(result, indent=2, ensure_ascii=False)
attachments.setdefault(FINDINGS_FILE, "[]")
return "\n\n".join(part.rstrip() for part in parts if part) + "\n", attachments
return add

View File

@@ -0,0 +1,387 @@
"""The operating model guide: one document, assembled from every other Deliverable.
The packager writes the summary. Every other section is written here, from the data
the other Deliverables carry: the Items and Conditions, the requirements, the
Capabilities, who does what, staffing and cost, the verdicts and the findings. A
table or a figure copied by a model can be copied wrongly; one written from the data
cannot disagree with it.
"""
from __future__ import annotations
import json
import re
from collections.abc import Mapping, Sequence
from typing import Any
from app.operating_model import catalogue as capability_catalogue
from app.operating_model import chain, graph, scenarios, spec
from app.operating_model.catalogue import Catalogue
from app.operating_model.names import (
SCENARIOS_FILE,
STAFFING_FILE,
TARGET_OPERATING_MODEL,
VALIDATION_RESULTS,
VERDICTS_FILE,
)
from app.operating_model.spec import Upstream
SUMMARY = "Summary"
KEY_FIGURES = "Key figures"
# The sections of the guide, in order. The packager writes the first; code writes
# the rest.
SECTIONS = (
SUMMARY,
"Business outcomes",
"What is operated",
"Operational requirements",
"Capabilities",
"Who does what",
"Staffing and cost",
"Validation",
"Findings and open questions",
"Sources",
)
_HEADING = re.compile(r"^##\s+(?:\d+(?:\.\d+)*\.?\s+)?(.+?)\s*#*\s*$", re.MULTILINE)
def _json(deliverables: Upstream, kind: str, name: str) -> Any:
text = (deliverables.get(kind) or {}).get("attachments", {}).get(name, "")
try:
return json.loads(text) if text else None
except ValueError:
return None
def _cell(value: Any) -> str:
"""A value as one cell of a table."""
if isinstance(value, (list, tuple)):
value = ", ".join(str(item) for item in value)
return " ".join(str(value if value is not None else "").split()).replace("|", "\\|")
def _table(headers: Sequence[str], rows: Sequence[Sequence[Any]]) -> list[str]:
return [
"| " + " | ".join(headers) + " |",
"| " + " | ".join("---" for _ in headers) + " |",
*("| " + " | ".join(_cell(value) for value in row) + " |" for row in rows),
]
def _body(rendered: str) -> str:
"""A rendered view without its own heading."""
return (
rendered.split("\n", 1)[1].strip() if rendered.startswith("## ") else rendered
)
def business_outcomes(deliverables: Upstream, catalogue: Catalogue) -> str:
model = graph.read(deliverables) or {
"roles": [],
"responsibilities": [],
"measures": [],
}
names = chain.names_of(chain.capabilities(deliverables), catalogue)
return graph.render_outcomes(model, spec.agreed(deliverables), names)
def what_is_operated(scope: Mapping[str, Any]) -> str:
lines = _table(
("Item", "What it is", "Kind", "Product", "From"),
[
(
i["id"],
i.get("name"),
i.get("kind"),
i.get("product"),
i.get("source_ref"),
)
for i in spec.items(scope)
],
)
conditions = spec.conditions(scope)
if conditions:
lines += ["", "What must be kept true while it is run:", ""]
lines += _table(
("Condition", "On", "What must hold", "From"),
[
(c["id"], c.get("on"), c.get("condition"), c.get("source_ref"))
for c in conditions
],
)
risks = spec.records(scope, "solution.inherited_risks")
if risks:
lines += ["", "Known to be unverified or at risk when operations begin:", ""]
lines += [f"- {r.get('on')}: {r.get('risk')}" for r in risks]
return "\n".join(lines)
def requirements(deliverables: Upstream) -> str:
return "\n".join(
_table(
("Requirement", "Kind", "What must be achieved", "From"),
[
(r["id"], r.get("kind"), r.get("statement"), r.get("source"))
for r in chain.requirements(deliverables)
],
)
)
def capabilities(deliverables: Upstream, catalogue: Catalogue) -> str:
listed = chain.capabilities(deliverables)
names = chain.names_of(listed, catalogue)
return "\n".join(
_table(
("Capability", "What it is", "Serves", "Covers", "Hours", "Effort a month"),
[
(
c["id"],
names[str(c["id"])],
c.get("serves"),
c.get("items"),
c.get("hours"),
f"{c.get('effort_hours_per_month')} h",
)
for c in listed
],
)
)
def who_does_what(deliverables: Upstream, catalogue: Catalogue) -> str:
model = graph.read(deliverables)
if model is None:
return ""
party = {str(p["id"]): p for p in model["parties"]}
lines = _table(
("Role", "Party", "Country", "Level", "Hours"),
[
(
r.get("name"),
(
f"{party.get(str(r.get('party')), {}).get('name')} "
f"({party.get(str(r.get('party')), {}).get('kind')})"
),
r.get("country"),
r.get("level"),
r.get("hours"),
)
for r in model["roles"]
],
)
teams = model.get("teams") or []
if teams:
lines += ["", "The teams, as Team Topologies names their kinds:", ""]
lines += _table(
("Team", "Kind", "Party", "Roles", "Purpose"),
[
(
team.get("name"),
str(team.get("type", "")).replace("_", "-"),
party.get(str(team.get("party")), {}).get("name"),
[
r.get("name")
for r in model["roles"]
if r.get("team") == team["id"]
],
team.get("purpose"),
)
for team in teams
],
)
interactions = model.get("interactions") or []
if interactions:
named = {str(team["id"]): team.get("name") for team in teams}
lines += ["", "How the teams work together:", ""]
lines += _table(
("From", "To", "Mode", "Until", "Purpose"),
[
(
named.get(str(i.get("from")), i.get("from")),
named.get(str(i.get("to")), i.get("to")),
str(i.get("mode", "")).replace("_", "-"),
i.get("until") or "",
i.get("purpose"),
)
for i in interactions
],
)
names = chain.names_of(chain.capabilities(deliverables), catalogue)
return "\n".join([*lines, "", _body(graph.render_matrix(model, names))])
def staffing_and_cost(deliverables: Upstream) -> str:
result = _json(deliverables, TARGET_OPERATING_MODEL, STAFFING_FILE)
if not isinstance(result, dict):
return ""
budget = spec.value(spec.agreed(deliverables), "commercial.monthly_run_budget")
return _body(graph.render_staffing(result, budget))
def validation(deliverables: Upstream) -> str:
verdicts = _json(deliverables, VALIDATION_RESULTS, VERDICTS_FILE) or {}
model = graph.read(deliverables) or {"checks": []}
condition = {str(c["id"]): c.get("condition") for c in model["checks"]}
own = [
item
for item in verdicts.get("checks") or []
if isinstance(item, dict)
and not str(item.get("check", "")).startswith(scenarios.PREFIX)
]
lines = _table(
("Check", "What must hold", "Verdict", "Evidence"),
[
(
v.get("check"),
condition.get(str(v.get("check"))),
str(v.get("verdict")).replace("_", " ")
+ (f" ({v['finding']})" if v.get("finding") else ""),
v.get("evidence"),
)
for v in own
],
)
walked = _json(deliverables, VALIDATION_RESULTS, SCENARIOS_FILE)
if isinstance(walked, list) and walked:
lines += ["", _body(scenarios.render(walked))]
return "\n".join(lines)
def findings_and_questions(deliverables: Upstream) -> str:
scope = spec.agreed(deliverables)
found = graph.findings(
(deliverables.get(TARGET_OPERATING_MODEL) or {}).get("attachments", {})
)
lines = []
if found:
lines += [_body(graph.render_findings(found)), ""]
else:
lines += ["No findings: the solution provides what operating it needs.", ""]
assumed = [a for a in scope.get("assumed") or [] if isinstance(a, Mapping)]
if assumed:
lines += ["Assumed for the customer, and open to change when they answer:", ""]
lines += [
f"- `{a.get('field')}`: {_cell(a.get('value'))}. {a.get('why') or ''}".rstrip()
for a in assumed
]
lines.append("")
undecided = [d for d in scope.get("to_decide") or [] if isinstance(d, Mapping)]
if undecided:
lines += ["Left to the agent by the customer, and not yet settled:", ""]
lines += [
f"- `{d.get('field')}`: affects {d.get('affects') or 'the operating model'}."
for d in undecided
]
lines.append("")
# What matters to an operating model and is not known. The optional fields
# nobody was asked for are not open questions.
unknown = [
g
for g in scope.get("to_ask") or []
if isinstance(g, Mapping) and g.get("severity") in ("HIGH", "MEDIUM")
]
if unknown:
lines += ["Still unknown:", ""]
lines += [
f"- `{g.get('field')}`: {g.get('prompt') or ''}".rstrip() for g in unknown
]
return "\n".join(lines).rstrip()
def sources(deliverables: Upstream, catalogue: Catalogue) -> str:
entries = [str(c.get("catalogue")) for c in chain.capabilities(deliverables)]
lines = [
(
"The Capabilities are from our own capability catalogue, which draws on "
"these frameworks. It cites them and certifies nothing against them."
),
"",
*(f"- {line}" for line in capability_catalogue.cited(catalogue, entries)),
]
if not catalogue.verified:
lines += [
"",
(
"**These references have not been checked against the frameworks by a "
"person.** Treat each as a pointer to where to look."
),
]
return "\n".join(lines)
def key_figures(deliverables: Upstream) -> str:
"""The figures a reader takes from the summary, written from the data."""
scope = spec.agreed(deliverables)
cost = _json(deliverables, TARGET_OPERATING_MODEL, STAFFING_FILE)
walked = _json(deliverables, VALIDATION_RESULTS, SCENARIOS_FILE) or []
found = graph.findings(
(deliverables.get(TARGET_OPERATING_MODEL) or {}).get("attachments", {})
)
lines = [
(
f"- Operated: {len(spec.items(scope))} Items, with "
f"{len(spec.conditions(scope))} Conditions to keep true."
),
f"- Faults responded to: {spec.value(scope, 'operations.support_hours')} hours.",
f"- Capabilities: {len(chain.capabilities(deliverables))}.",
]
if isinstance(cost, dict):
card = cost["rate_card"]
lines.append(
f"- People: {cost['people']}. Cost a month: {cost['cost_per_month']:,} "
f"{cost['currency']}, from rate card version `{card['version']}`"
+ (" (placeholder prices: an illustration)." if card["draft"] else ".")
)
if walked:
passed = sum(1 for item in walked if item.get("passes"))
lines.append(f"- Scenario walk-throughs: {passed} of {len(walked)} pass.")
outcomes = spec.business_outcomes(scope)
model = graph.read(deliverables)
if outcomes:
shown = {str(m.get("outcome")) for m in (model or {}).get("measures", [])}
lines.append(
f"- Business outcomes: {len(outcomes)}, "
f"{sum(1 for o in outcomes if str(o['id']) in shown)} shown by a Measure."
)
else:
lines.append("- Business outcomes: none stated.")
lines.append(f"- Findings for whoever owns the design: {len(found)}.")
return "\n".join(lines)
def assemble(content: str, deliverables: Upstream, catalogue: Catalogue) -> str:
"""The guide, with every section but the summary written from the data.
The packager's summary is kept as written, and the key figures are set under it.
Whatever it wrote under another heading is replaced.
"""
written = {
"Business outcomes": business_outcomes(deliverables, catalogue),
"What is operated": what_is_operated(spec.agreed(deliverables)),
"Operational requirements": requirements(deliverables),
"Capabilities": capabilities(deliverables, catalogue),
"Who does what": who_does_what(deliverables, catalogue),
"Staffing and cost": staffing_and_cost(deliverables),
"Validation": validation(deliverables),
"Findings and open questions": findings_and_questions(deliverables),
"Sources": sources(deliverables, catalogue),
}
headings = list(_HEADING.finditer(content))
title = content[: headings[0].start()].rstrip() if headings else content.rstrip()
summary = ""
for index, match in enumerate(headings):
if match.group(1).strip().lower() == SUMMARY.lower():
end = (
headings[index + 1].start()
if index + 1 < len(headings)
else len(content)
)
summary = content[match.end() : end].strip()
summary = summary.split(f"\n### {KEY_FIGURES}")[0].rstrip()
parts = [
title,
f"## {SUMMARY}\n\n{summary}\n\n### {KEY_FIGURES}\n\n{key_figures(deliverables)}",
*(f"## {heading}\n\n{written[heading]}" for heading in SECTIONS[1:]),
]
return "\n\n".join(part.rstrip() for part in parts if part.strip()) + "\n"

View File

@@ -0,0 +1,66 @@
"""The names this Workflow is written in: its Phases, its Deliverables and its files."""
from __future__ import annotations
# Phases, in order.
SCOPING = "scoping"
REQUIREMENTS = "operational_requirements"
DESIGN = "operating_model_design"
VALIDATION = "validation"
PACKAGING = "packaging"
PHASES = (SCOPING, REQUIREMENTS, DESIGN, VALIDATION, PACKAGING)
# Deliverable kinds.
OPERATING_SCOPE = "operating_scope"
OPERATIONAL_REQUIREMENTS = "operational_requirements"
CAPABILITY_MODEL = "capability_model"
TARGET_OPERATING_MODEL = "target_operating_model"
VALIDATION_RESULTS = "validation_results"
GUIDE = "operating_model_guide"
# Data files.
SCOPE_DATA_FILE = "scope.json" # the engine's: what every Specialist reads of the spec
REQUIREMENTS_FILE = "operational-requirements.json"
CAPABILITIES_FILE = "capabilities.json"
GRAPH_FILE = "target-operating-model.json"
FINDINGS_FILE = "findings.json"
STAFFING_FILE = "staffing.json"
ORGANISATION_FILE = "organisation.mmd"
VERDICTS_FILE = "verdicts.json"
SCENARIOS_FILE = "scenarios.json"
CHANGES_FILE = "changes.json"
GUIDE_FILE = "operating-model-guide.md"
CHANGE_REQUEST_FILE = "architecture-change-request.md"
# Hours a Capability must be staffed for and a Role works, narrowest first.
HOURS = ("business", "extended", "24x7")
PARTY_KINDS = ("customer", "provider", "supplier", "cloud_provider")
CUSTOMER = "customer"
ACCOUNTABLE, RESPONSIBLE, CONSULTED, INFORMED = (
"accountable",
"responsible",
"consulted",
"informed",
)
RESPONSIBILITY_KINDS = (ACCOUNTABLE, RESPONSIBLE, CONSULTED, INFORMED)
CUSTOM = "custom" # a Capability the catalogue does not have
# Team Topologies: the four kinds of team, and the three ways two teams work together.
TEAM_TYPES = ("stream_aligned", "platform", "enabling", "complicated_subsystem")
COLLABORATION, X_AS_A_SERVICE, FACILITATING = (
"collaboration",
"x_as_a_service",
"facilitating",
)
INTERACTION_MODES = (COLLABORATION, X_AS_A_SERVICE, FACILITATING)
# What a Measure tells about a business outcome. The first three are the layers of
# measuring how work flows (DORA, SPACE, DevEx); none stands in for another.
OUTCOME_LAYER, GUARDRAIL_LAYER, LEADING_LAYER = "outcome", "guardrail", "leading"
DEVELOPER_LAYERS = (OUTCOME_LAYER, GUARDRAIL_LAYER, LEADING_LAYER)
MEASURE_LAYERS = (*DEVELOPER_LAYERS, "service_level", "cost")
# The catalogue entry whose measures must cover all three developer layers.
MEASUREMENT_ENTRY = "delivery-and-developer-experience-measurement"
def wider(first: str, second: str) -> bool:
"""Whether `first` hours are wider than `second`."""
return HOURS.index(first) > HOURS.index(second)

View File

@@ -0,0 +1,346 @@
"""Scenario walk-throughs: events the operating model must be able to handle.
Infrastructure code can be validated by running it. An operating model cannot, so
each scenario is generated from the graph and the operating spec and traced through
the graph by code: is there a Capability for it, is someone responsible at the hours
it happens, is one Role answerable. A broken path is a failed Check. No model writes
a scenario or judges one.
"""
from __future__ import annotations
import json
from collections.abc import Mapping, Sequence
from typing import Any
from app.operating_model import spec
from app.operating_model.catalogue import Catalogue
from app.operating_model.names import (
ACCOUNTABLE,
CONSULTED,
CUSTOMER,
HOURS,
RESPONSIBLE,
wider,
)
PREFIX = "SC-" # a scenario's id; the validator gives no verdict under it
# The verdict on a Check that cannot hold until a finding is met. It is neither a
# failure of the model nor a gap in it: nothing is revised for it, and it is
# reported with the finding it waits on.
WAITING = "waits_on_finding"
HEADING = "Scenario walk-throughs"
CHANGE_DOMAIN = "change"
def _scenario(
identifier: str, scenario: str, about: str, fault: str | None, path: str
) -> dict[str, Any]:
return {
"id": f"{PREFIX}{identifier}",
"scenario": scenario,
"about": about,
"passes": fault is None,
"path": fault or path,
}
def walk(
graph: Mapping[str, Sequence[Mapping[str, Any]]],
capabilities: Sequence[Mapping[str, Any]],
scope: Mapping[str, Any],
catalogue: Catalogue,
staffing: Mapping[str, Any] | None = None,
) -> list[dict[str, Any]]:
"""Every scenario for this operating model, traced."""
roles = {str(r["id"]): r for r in graph["roles"]}
parties = {str(p["id"]): p for p in graph["parties"]}
by_capability: dict[str, list[Mapping[str, Any]]] = {}
for item in graph["responsibilities"]:
by_capability.setdefault(str(item.get("capability")), []).append(item)
def holders(capability: str, kind: str) -> list[Mapping[str, Any]]:
return [
roles[str(r["role"])]
for r in by_capability.get(capability, [])
if r.get("kind") == kind and str(r.get("role")) in roles
]
def entry_of(capability: Mapping[str, Any]) -> Any:
return catalogue.entries.get(str(capability.get("catalogue")))
def covering(item: str) -> list[Mapping[str, Any]]:
return [c for c in capabilities if item in (c.get("items") or [])]
support = str(spec.value(scope, "operations.support_hours") or HOURS[0])
found = []
for item in spec.items(scope):
item_id, label = str(item["id"]), f"{item.get('name')} ({item['id']})"
responders = [
c
for c in covering(item_id)
if entry_of(c) and entry_of(c).follows_support_hours
]
fault = None
if not responders:
fault = "No Capability that responds to faults covers it."
else:
on_hours = [
(c, role)
for c in responders
for role in holders(str(c["id"]), RESPONSIBLE)
if str(role.get("hours")) in HOURS
and not wider(support, str(role.get("hours")))
]
answerable = [c for c, _ in on_hours if holders(str(c["id"]), ACCOUNTABLE)]
if not on_hours:
fault = f"No Role responsible for responding works {support} hours."
elif not answerable:
fault = "The Capability that responds has no accountable Role."
chosen = None if fault else on_hours[0]
found.append(
_scenario(
f"fault-{item_id}",
f"{label} fails at an hour faults are responded to ({support}).",
item_id,
fault,
""
if chosen is None
else f"{chosen[1].get('name')} responds under {chosen[0]['id']}, and "
f"{holders(str(chosen[0]['id']), ACCOUNTABLE)[0].get('name')} is "
"answerable.",
)
)
changers = [
c
for c in covering(item_id)
if entry_of(c)
and entry_of(c).domain == CHANGE_DOMAIN
and holders(str(c["id"]), RESPONSIBLE)
]
found.append(
_scenario(
f"change-{item_id}",
f"{label} must be changed.",
item_id,
None
if changers
else "No Capability for making changes covers it with a responsible Role.",
""
if not changers
else f"{holders(str(changers[0]['id']), RESPONSIBLE)[0].get('name')} "
f"makes the change under {changers[0]['id']}.",
)
)
capability_ids = {str(c["id"]) for c in capabilities}
for condition in spec.conditions(scope):
condition_id = str(condition["id"])
carrying = [k for k in graph["checks"] if k.get("source") == condition_id]
kept = [
k
for k in carrying
if str(k.get("on")) not in capability_ids
or holders(str(k.get("on")), RESPONSIBLE)
]
found.append(
_scenario(
f"condition-{condition_id}",
f"Condition {condition_id} must be shown to hold: "
f"{condition.get('condition')}",
condition_id,
None
if kept
else (
"No Check carries it."
if not carrying
else "The Check that carries it is on a Capability nobody is responsible for."
),
""
if not kept
else f"Check {kept[0]['id']} on {kept[0].get('on')} keeps it true.",
)
)
for party in graph["parties"]:
if party.get("kind") == CUSTOMER:
continue
party_id = str(party["id"])
stranded = [
str(c["id"])
for c in capabilities
if any(
a.get("party") == party_id for a in holders(str(c["id"]), ACCOUNTABLE)
)
and not any(
parties.get(str(role.get("party")), {}).get("id") != party_id
for kind in (RESPONSIBLE, CONSULTED)
for role in holders(str(c["id"]), kind)
)
]
found.append(
_scenario(
f"party-{party_id}",
f"{party.get('name')} cannot be reached.",
party_id,
None
if not stranded
else "No Role in another Party is responsible or consulted for "
+ ", ".join(stranded)
+ ".",
"Every Capability it is answerable for has a Role in another Party to turn to.",
)
)
budget = spec.value(scope, "commercial.monthly_run_budget")
if (
staffing is not None
and isinstance(budget, (int, float))
and not isinstance(budget, bool)
):
cost, currency = staffing["cost_per_month"], staffing["currency"]
found.append(
_scenario(
"budget",
f"A month's cost of operating is compared with the budget of {round(budget):,} {currency}.",
"commercial.monthly_run_budget",
None
if cost <= budget
else f"The cost is {cost:,} {currency}, over the budget.",
f"The cost is {cost:,} {currency}, within the budget.",
)
)
return found
def as_verdicts(scenarios: Sequence[Mapping[str, Any]]) -> list[dict[str, str]]:
return [
{
"check": str(item["id"]),
"verdict": "pass" if item["passes"] else "fail",
"evidence": f"{item['scenario']} {item['path']}",
}
for item in scenarios
]
def merge(
verdicts_text: str,
scenarios: Sequence[Mapping[str, Any]],
waiting: Mapping[str, str] | None = None,
) -> str:
"""verdicts.json with the scenarios' verdicts in it, written by code.
The validator's verdicts on the Checks are kept as given, but for one thing:
a Check in `waiting`, which names the finding it depends on, is recorded as
waiting on that finding. The overall run is the walk-through: it passes when
every scenario does.
"""
try:
data = json.loads(verdicts_text)
except ValueError:
data = {}
if not isinstance(data, dict):
data = {}
given = [
(
{**item, "verdict": WAITING, "finding": waiting[str(item.get("check"))]}
# Only where the validator found the finding stands. One it failed is
# something the operating model can provide itself, and is a fault in it.
if waiting
and str(item.get("check")) in waiting
and item.get("verdict") in ("not_verifiable", WAITING)
else item
)
for item in data.get("checks") or []
if isinstance(item, dict) and not str(item.get("check", "")).startswith(PREFIX)
]
failed = [item for item in scenarios if not item["passes"]]
return json.dumps(
{
"dry_run": {
"verdict": "fail" if failed else "pass",
"evidence": f"{len(scenarios) - len(failed)} of {len(scenarios)} "
"scenario walk-throughs pass.",
},
"checks": [*given, *as_verdicts(scenarios)],
"proposed_additions": data.get("proposed_additions") or [],
},
indent=2,
ensure_ascii=False,
)
def render(scenarios: Sequence[Mapping[str, Any]]) -> str:
lines = [
f"## {HEADING}",
"",
(
"Each scenario is generated from the operating model and traced through "
"it by code."
),
"",
"| Scenario | Result | Path |",
"| --- | --- | --- |",
]
lines += [
f"| {item['scenario']} | {'pass' if item['passes'] else '**fail**'} | {item['path']} |"
for item in scenarios
]
return "\n".join(lines) + "\n"
def check_verdicts(
attachments: Mapping[str, str],
graph: Mapping[str, Sequence[Mapping[str, Any]]] | None,
name: str,
) -> list[str]:
"""What is wrong with the validator's verdicts: one on every Check, none on a
scenario, and never a pass on a Check that depends on a finding."""
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("checks"), list):
return [f"{name}: must be an object with a list of checks"]
problems = []
given: dict[str, str] = {}
for index, item in enumerate(data["checks"]):
where = f"{name}: checks[{index}]"
if not isinstance(item, dict) or not item.get("check"):
problems.append(f"{where} needs a check")
continue
identifier = str(item["check"])
if identifier.startswith(PREFIX):
continue # the walk-throughs' own, written by code on an earlier attempt
if item.get("verdict") == WAITING:
# Recorded by code on an earlier attempt; the validator's own verdict
# on such a Check is not_verifiable.
item = {**item, "verdict": "not_verifiable"}
if item.get("verdict") not in ("pass", "fail", "not_verifiable"):
problems.append(
f"{where} ({identifier}): verdict must be pass, fail or not_verifiable"
)
if not str(item.get("evidence") or "").strip():
problems.append(f"{where} ({identifier}) needs evidence")
given[identifier] = str(item.get("verdict"))
for check in (graph or {}).get("checks", []):
identifier = str(check["id"])
if identifier not in given:
problems.append(f"{name}: Check {identifier} has no verdict")
elif check.get("depends_on_finding") and given[identifier] == "pass":
problems.append(
f"{name}: Check {identifier} depends on finding "
f"{check['depends_on_finding']}. It is not_verifiable while the finding "
"stands, or fail when the operating model could meet it itself"
)
known = {str(check["id"]) for check in (graph or {}).get("checks", [])}
if graph is not None:
problems += [
f"{name}: {identifier} is not a Check of the Target operating model"
for identifier in given
if identifier not in known
]
return problems

View File

@@ -0,0 +1,89 @@
"""Reading the agreed operating spec, as every Specialist is given it.
The engine writes the spec's data file from what the scope analyst recorded: what
the customer stated, nested by field; what was assumed for them, as a list; and
which stated fields bind. Code that checks a Deliverable against the spec reads it
here, and a value counts whichever of the two it came from.
"""
from __future__ import annotations
import json
from collections.abc import Mapping
from typing import Any
from app.operating_model.names import OPERATING_SCOPE, SCOPE_DATA_FILE
Upstream = Mapping[str, Mapping[str, Any]]
def agreed(upstream: Upstream | None) -> dict[str, Any]:
"""The agreed spec from the Deliverables a submission builds on; {} without one."""
text = (
((upstream or {}).get(OPERATING_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 value(scope: Mapping[str, Any], path: str, default: Any = None) -> Any:
"""A field's value, stated or assumed; `default` when it is neither."""
node: Any = scope.get("stated") or {}
for part in path.split("."):
if not isinstance(node, Mapping) or part not in node:
node = None
break
node = node[part]
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", default)
return default
def settled(scope: Mapping[str, Any], path: str) -> bool:
return value(scope, path) is not None
def records(scope: Mapping[str, Any], path: str) -> list[dict[str, Any]]:
found = value(scope, path)
return (
[dict(item) for item in found if isinstance(item, Mapping)]
if isinstance(found, list)
else []
)
def items(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
"""What is to be operated."""
return records(scope, "solution.items")
def conditions(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
"""What must be kept true of an Item while it is run."""
return records(scope, "solution.conditions")
def business_outcomes(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
"""What the customer's business wants from the solution, in their words: what
every measure of operations is ultimately for."""
return records(scope, "intent.business_outcomes")
def stated_requirements(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
return records(scope, "intent.requirements")
def binding(scope: Mapping[str, Any]) -> list[str]:
"""The stated fields an operating model must honour."""
return [str(path) for path in scope.get("binding") or []]
def ids(entries: list[dict[str, Any]]) -> list[str]:
return [str(entry["id"]) for entry in entries if entry.get("id")]

View File

@@ -0,0 +1,280 @@
"""Staffing and cost, computed from the Target operating model and the rate card.
No agent writes a number of people or a cost. A Specialist says what each Capability
takes in hours a month, which Roles are responsible for it, and where each Role sits
and at what level. Everything else is arithmetic on the service provider's rate card,
so the figures cannot disagree with the model they are about.
effort the hours a month of the Capabilities a Role is responsible for
people effort over the productive hours of its country; and, where the
Role covers hours wider than a working day, never fewer than the
smallest team that can cover them
cost a month people, at the day rate for its country and level, for the
productive days in a month, with the uplift for its hours, in
the currency the operating spec states
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import yaml
from app.operating_model.names import CUSTOMER, HOURS, RESPONSIBLE, wider
SKILL = "rate-card"
BUSINESS = HOURS[0]
class RateCardError(ValueError):
"""A rate card that cannot be used; the message lists every fault."""
@dataclass(frozen=True)
class Country:
name: str
productive_days: float
hours_per_day: float
day_rate: Mapping[str, float]
@property
def productive_hours_a_month(self) -> float:
return self.productive_days * self.hours_per_day / 12
@dataclass(frozen=True)
class RateCard:
name: str
version: str
currency: str # what its rates are written in
conversion: Mapping[str, float] # units of a currency for one of `currency`
conversion_as_of: str
prices: tuple[str, ...] # the kinds of Party it prices
levels: Mapping[str, str]
cover: Mapping[str, Mapping[str, float]] # hours -> minimum_roster, uplift
countries: Mapping[str, Country]
@property
def is_draft(self) -> bool:
return self.version.startswith("draft")
def currencies(self) -> list[str]:
return sorted(self.conversion)
def _number(value: Any) -> bool:
return isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0
def load(skill_dir: Path) -> RateCard:
"""Read the rate card from the Skill's folder, and check it holds together."""
path = skill_dir / "assets" / "rates.yaml"
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
if not isinstance(data, dict):
raise RateCardError("rates.yaml: must be a mapping")
problems = [
f"rates.yaml: needs {field}"
for field in ("name", "version", "currency", "levels", "cover", "countries")
if not data.get(field)
]
if problems:
raise RateCardError("; ".join(problems))
levels = {str(name): str(text) for name, text in data["levels"].items()}
conversion_data = data.get("conversion") or {}
rates = {str(k): v for k, v in (conversion_data.get("rates") or {}).items()}
rates.setdefault(str(data["currency"]), 1.0)
problems += [
f"rates.yaml: the conversion rate for {name} must be a number above zero"
for name, rate in rates.items()
if not _number(rate)
]
prices = tuple(str(kind) for kind in data.get("prices") or ())
if CUSTOMER in prices:
problems.append(
"rates.yaml: `prices` lists customer; the customer's own staff are "
"never priced"
)
cover = {str(name): dict(entry or {}) for name, entry in data["cover"].items()}
for hours in HOURS:
entry = cover.get(hours) or {}
if not _number(entry.get("minimum_roster")) or not _number(entry.get("uplift")):
problems.append(
f"rates.yaml: cover for {hours} needs a minimum_roster and an "
"uplift, both above zero"
)
countries = {}
for code, entry in data["countries"].items():
entry = entry or {}
where = f"rates.yaml: {code}"
if not _number(entry.get("productive_days")) or not _number(
entry.get("hours_per_day")
):
problems.append(f"{where} needs productive_days and hours_per_day")
continue
day_rate = entry.get("day_rate") or {}
problems += [
f"{where} has no day rate for level {level}"
for level in levels
if not _number(day_rate.get(level))
]
countries[str(code)] = Country(
name=str(entry.get("name") or code),
productive_days=float(entry["productive_days"]),
hours_per_day=float(entry["hours_per_day"]),
day_rate={str(k): float(v) for k, v in day_rate.items() if _number(v)},
)
if problems:
raise RateCardError("; ".join(problems))
return RateCard(
name=str(data["name"]),
version=str(data["version"]),
currency=str(data["currency"]),
conversion={name: float(rate) for name, rate in rates.items()},
conversion_as_of=str(conversion_data.get("as_of") or ""),
prices=prices,
levels=levels,
cover={
name: {
"minimum_roster": float(entry["minimum_roster"]),
"uplift": float(entry["uplift"]),
}
for name, entry in cover.items()
if name in HOURS
},
countries=countries,
)
def shares(
responsibilities: Sequence[Mapping[str, Any]],
) -> tuple[dict[tuple[str, str], float], list[str]]:
"""Each responsible Role's share of each Capability's effort, and what is wrong
with how shares were stated.
The Roles responsible for a Capability divide its effort equally, unless every
one of them states a `share`, and the shares add up to 1.
"""
by_capability: dict[str, list[Mapping[str, Any]]] = {}
for item in responsibilities:
if item.get("kind") == RESPONSIBLE:
by_capability.setdefault(str(item.get("capability")), []).append(item)
result: dict[tuple[str, str], float] = {}
problems = []
for capability, entries in by_capability.items():
stated = [e.get("share") for e in entries if e.get("share") is not None]
if not stated:
for entry in entries:
result[(capability, str(entry.get("role")))] = 1 / len(entries)
continue
valid = all(
isinstance(s, (int, float)) and not isinstance(s, bool) and 0 < s <= 1
for s in stated
)
if len(stated) != len(entries) or not valid:
problems.append(
f"the Roles responsible for {capability} must all state a share "
"between 0 and 1, or none of them"
)
continue
total = sum(float(entry["share"]) for entry in entries)
if abs(total - 1) > 0.001:
problems.append(f"the shares of {capability} do not add up to 1")
continue
for entry in entries:
result[(capability, str(entry.get("role")))] = float(entry["share"])
return result, problems
def compute(
graph: Mapping[str, Any],
capabilities: Sequence[Mapping[str, Any]],
card: RateCard,
currency: str,
) -> dict[str, Any]:
"""People and cost per Role, and the totals. The graph is taken to be sound:
`graph.check` refuses one whose Roles the card cannot price."""
parties = {str(p.get("id")): p for p in graph.get("parties") or []}
effort_of = {
str(c["id"]): float(c.get("effort_hours_per_month") or 0) for c in capabilities
}
hours_of = {str(c["id"]): str(c.get("hours") or BUSINESS) for c in capabilities}
share_of, _ = shares(graph.get("responsibilities") or [])
rate = card.conversion[currency]
rows: list[dict[str, Any]] = []
by_capability: dict[str, float] = {}
for role in graph.get("roles") or []:
role_id = str(role.get("id"))
country = card.countries[str(role.get("country"))]
own = {cap: share for (cap, who), share in share_of.items() if who == role_id}
effort = float(
sum(effort_of.get(cap, 0.0) * share for cap, share in own.items())
)
hours = BUSINESS
for cap in own:
if wider(hours_of.get(cap, BUSINESS), hours):
hours = hours_of[cap]
people = effort / country.productive_hours_a_month
if hours != BUSINESS:
# A rota is sized by the hours it must fill, not by the work done in them.
people = max(people, card.cover[hours]["minimum_roster"])
party = parties.get(str(role.get("party")), {})
priced = party.get("kind") != CUSTOMER and party.get("kind") in card.prices
cost = (
people
* country.day_rate[str(role.get("level"))]
* country.productive_days
/ 12
* card.cover[hours]["uplift"]
* rate
if priced
else None
)
if cost is not None and effort:
for cap, share in own.items():
portion = effort_of.get(cap, 0.0) * share / effort
by_capability[cap] = by_capability.get(cap, 0.0) + cost * portion
rows.append(
{
"role": role_id,
"name": str(role.get("name") or role_id),
"party": str(role.get("party")),
"party_name": str(party.get("name") or role.get("party")),
"country": str(role.get("country")),
"level": str(role.get("level")),
"hours": hours,
"effort_hours_per_month": round(effort, 1),
"people": round(people, 1),
"cost_per_month": None if cost is None else round(cost),
}
)
def total(key: str) -> dict[str, int]:
sums: dict[str, float] = {}
for row in rows:
if row["cost_per_month"] is not None:
sums[row[key]] = sums.get(row[key], 0.0) + row["cost_per_month"]
return {name: round(amount) for name, amount in sums.items()}
return {
"currency": currency,
"rate_card": {
"name": card.name,
"version": card.version,
"draft": card.is_draft,
},
"conversion": {
"from": card.currency,
"rate": rate,
"as_of": card.conversion_as_of,
},
"roles": rows,
"people": round(sum(row["people"] for row in rows), 1),
"cost_per_month": round(sum(row["cost_per_month"] or 0 for row in rows)),
"by_party": total("party"),
"by_country": total("country"),
"by_capability": {cap: round(amount) for cap, amount in by_capability.items()},
}

View File

@@ -0,0 +1,572 @@
"""The target operating model, as a Workflow for the Execution engine.
`build(root)` reads the capability catalogue and the rate card from the agent's
Skills and returns the one value that makes the engine about this subject: the
Phases and Deliverables, the checks along the chain, the graph and its views, the
scenario walk-throughs that stand in for a dry run, and what a Change request
changed.
"""
from __future__ import annotations
import json
from collections.abc import Mapping
from pathlib import Path
from typing import Any
from execution_engine.workflows.deliverables import DeliverableSpec
from execution_engine.workflows.workflow import (
Bench,
CardText,
ChangePolicy,
ValidationPolicy,
Workflow,
)
from app.operating_model import catalogue as capability_catalogue
from app.operating_model import chain, digest, graph, guide, scenarios, spec, staffing
from app.operating_model.catalogue import Catalogue
from app.operating_model.names import (
CAPABILITIES_FILE,
CAPABILITY_MODEL,
CHANGE_REQUEST_FILE,
CHANGES_FILE,
DESIGN,
FINDINGS_FILE,
GRAPH_FILE,
GUIDE,
GUIDE_FILE,
OPERATING_SCOPE,
OPERATIONAL_REQUIREMENTS,
PACKAGING,
PHASES,
REQUIREMENTS,
REQUIREMENTS_FILE,
SCENARIOS_FILE,
SCOPE_DATA_FILE,
SCOPING,
STAFFING_FILE,
TARGET_OPERATING_MODEL,
VALIDATION,
VALIDATION_RESULTS,
VERDICTS_FILE,
)
from app.operating_model.spec import Upstream
from app.operating_model.staffing import RateCard
ROOT = Path(__file__).resolve().parents[2] # the agent's own folder
SCOPE_FILE = "scope.yaml" # the engine's: the completed operating spec
ABOUT = (
"I design target operating models. Give me the solution to be operated, as an "
"operating spec or as a solution architecture to digest into one, and I will "
"work through operational requirements, the Capabilities needed, who is "
"accountable and responsible for each, staffing and cost, and a validation of "
"the model against the events it must handle, asking for your approval at each "
"Phase. Nothing was started for this message."
)
def _staffing(deliverables: Upstream) -> dict[str, Any] | None:
text = (
(deliverables.get(TARGET_OPERATING_MODEL) or {})
.get("attachments", {})
.get(STAFFING_FILE, "")
)
try:
data = json.loads(text) if text else None
except ValueError:
return None
return data if isinstance(data, dict) else None
def _findings(deliverables: Upstream) -> list[dict[str, Any]]:
return graph.findings(
(deliverables.get(TARGET_OPERATING_MODEL) or {}).get("attachments", {})
)
def _waiting(deliverables: Upstream) -> dict[str, str]:
"""The Checks that cannot hold until a finding is met, with the finding."""
text = (
(deliverables.get(VALIDATION_RESULTS) or {})
.get("attachments", {})
.get(VERDICTS_FILE, "")
)
try:
data = json.loads(text) if text else {}
except ValueError:
return {}
return {
str(item.get("check")): str(item.get("finding"))
for item in (data.get("checks") or [] if isinstance(data, dict) else [])
if isinstance(item, dict) and item.get("verdict") == scenarios.WAITING
}
def approval_facts(phase: str, deliverables: Upstream) -> dict[str, Any]:
"""This Workflow's own facts for an Approval summary: counts and cost, as data."""
scope = spec.agreed(deliverables)
model = graph.read(deliverables)
facts: dict[str, Any] = {
"counts": {
name: count
for name, count in (
("items", len(spec.items(scope))),
("conditions", len(spec.conditions(scope))),
("business_outcomes", len(spec.business_outcomes(scope))),
("operational_requirements", len(chain.requirements(deliverables))),
("capabilities", len(chain.capabilities(deliverables))),
("roles", len(model["roles"]) if model else 0),
("checks", len(model["checks"]) if model else 0),
("measures", len(model["measures"]) if model else 0),
)
if count
}
}
cost = _staffing(deliverables)
if cost:
facts["staffing"] = {
"people": cost["people"],
"cost_per_month": cost["cost_per_month"],
"currency": cost["currency"],
"rate_card": cost["rate_card"],
}
found = _findings(deliverables)
if found:
facts["findings"] = [f"{item['id']}: {item.get('lacks')}" for item in found]
waiting = _waiting(deliverables)
if waiting:
facts["checks_waiting_on_findings"] = waiting
return facts
def summary_lines(phase: str, facts: Mapping[str, Any]) -> list[str]:
lines = []
counts = facts.get("counts") or {}
if counts:
lines.append(
", ".join(
f"{count} {name.replace('_', ' ')}" for name, count in counts.items()
)
+ "."
)
cost = facts.get("staffing")
if cost:
lines.append(
f"{cost['people']} people, {cost['cost_per_month']:,} {cost['currency']} "
"a month"
+ (
", from placeholder prices."
if cost["rate_card"]["draft"]
else f", from rate card version {cost['rate_card']['version']}."
)
)
found = facts.get("findings")
if found:
lines.append(
f"{len(found)} findings for whoever owns the design: " + "; ".join(found)
)
waiting = facts.get("checks_waiting_on_findings")
if waiting:
lines.append(
"Waiting on a finding, and so not yet shown to hold: "
+ ", ".join(f"{check} ({finding})" for check, finding in waiting.items())
+ "."
)
return lines
def describe_approval(approval: Mapping[str, Any]) -> str:
changes = approval.get("changes")
if not changes:
return ""
lines = [
f"This changes the operating model delivered in {approval.get('baseline')}."
]
lines += [
f"- {word} {part.replace('_', ' ')}: {', '.join(ids)}"
for part, by_change in changes.items()
for word, ids in (
("Added", by_change.get("added")),
("Removed", by_change.get("removed")),
("Changed", by_change.get("changed")),
)
if ids
]
return "\n".join(lines) + "\n\n"
# --- what a Change request changed -----------------------------------------------------
_PARTS = {
"operational_requirements": (OPERATIONAL_REQUIREMENTS, REQUIREMENTS_FILE, None),
"capabilities": (CAPABILITY_MODEL, CAPABILITIES_FILE, None),
"roles": (TARGET_OPERATING_MODEL, GRAPH_FILE, "roles"),
"responsibilities": (TARGET_OPERATING_MODEL, GRAPH_FILE, "responsibilities"),
"checks": (TARGET_OPERATING_MODEL, GRAPH_FILE, "checks"),
}
def _entries(deliverables: Upstream | None, part: str) -> dict[str, dict[str, Any]]:
kind, name, within = _PARTS[part]
text = ((deliverables or {}).get(kind) or {}).get("attachments", {}).get(name, "")
if not text:
return {}
listed = graph.parse(text)[0][within] if within else chain.objects(text, name)[0]
return {str(item["id"]): item for item in listed if item.get("id")}
def change_summary(before: Upstream | None, after: Upstream) -> dict[str, Any]:
"""What was added, removed and changed against the Baseline, by id."""
summary = {}
for part in _PARTS:
was, now = _entries(before, part), _entries(after, part)
summary[part] = {
"added": sorted(set(now) - set(was)),
"removed": sorted(set(was) - set(now)),
"changed": sorted(k for k in set(was) & set(now) if was[k] != now[k]),
}
return summary
def changes_empty(summary: Mapping[str, Any]) -> bool:
return not any(ids for part in summary.values() for ids in part.values())
def changes_in_words(summary: Mapping[str, Any]) -> str:
part = summary.get("operational_requirements") or {}
return "\n".join(
f"Operational requirement {identifier} was {word}."
for word in ("added", "changed", "removed")
for identifier in part.get(word) or []
)
def changes_for(phase_kinds: list[str], summary: Mapping[str, Any]) -> dict[str, Any]:
"""The parts of the summary that belong to a Phase's Deliverables."""
return {
part: change
for part, change in summary.items()
if _PARTS[part][0] in phase_kinds and any(change.values())
}
# --- the Workflow ----------------------------------------------------------------------
def build(root: Path = ROOT) -> Workflow:
"""The Workflow, for the capability catalogue and the rate card under `root`."""
catalogue: Catalogue = capability_catalogue.load(
root / "skills" / capability_catalogue.SKILL
)
card: RateCard = staffing.load(root / "skills" / staffing.SKILL)
add_views = graph.views(catalogue, card)
# Every provider's table of what kind of thing each product is, as one: the
# digest names an Item's kind before the operating spec says which provider.
kinds: dict[str, list[str]] = {}
for bundle in sorted((root / "providers").glob("*.yaml")):
for kind, words in digest.item_kinds(root, bundle.stem).items():
kinds.setdefault(kind, []).extend(words)
def with_graph_views(
bench: Bench, content: str, attachments: dict[str, str]
) -> tuple[str, dict[str, str]]:
return add_views(content, attachments, bench.upstream)
def check_verdicts(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
return scenarios.check_verdicts(
attachments, graph.read(upstream), VERDICTS_FILE
)
def with_scenarios(
bench: Bench, content: str, attachments: dict[str, str]
) -> tuple[str, dict[str, str]]:
# The walk-throughs are generated and traced here, and their verdicts
# written into the validator's file: no model judges one.
upstream = bench.upstream or {}
model = graph.read(upstream)
if model is None:
return content, attachments
walked = scenarios.walk(
model,
chain.capabilities(upstream),
spec.agreed(upstream),
catalogue,
_staffing(upstream),
)
attachments[SCENARIOS_FILE] = json.dumps(walked, indent=2, ensure_ascii=False)
waiting = {
str(check["id"]): str(check["depends_on_finding"])
for check in model["checks"]
if check.get("depends_on_finding")
}
attachments[VERDICTS_FILE] = scenarios.merge(
attachments[VERDICTS_FILE], walked, waiting
)
content = content.split(f"\n## {scenarios.HEADING}")[0].rstrip()
return content + "\n\n" + scenarios.render(walked), attachments
def with_guide_sections(
bench: Bench, content: str, attachments: dict[str, str]
) -> tuple[str, dict[str, str]]:
return guide.assemble(content, bench.upstream or {}, catalogue), attachments
def check_ids(upstream: Upstream | None) -> list[str]:
model = graph.read(upstream)
return [str(item["id"]) for item in model["checks"]] if model else []
def known_ids(deliverables: Upstream) -> set[str]:
return {str(r["id"]) for r in chain.requirements(deliverables)} | set(
spec.ids(spec.conditions(spec.agreed(deliverables)))
)
def approval_details(
phase: str, deliverables: Upstream, baseline: Mapping[str, Any] | None
) -> dict[str, Any]:
if not baseline:
return {}
in_phase = [
kind for kind, each in deliverable_specs.items() if each.phase == phase
]
return {
"changes": changes_for(
in_phase, change_summary(baseline.get("deliverables"), deliverables)
)
}
def task_entries(
state: Mapping[str, Any], kind: str
) -> tuple[dict[str, Any], dict[str, Any]]:
context: dict[str, Any] = {
# Which rate card the cost is worked from; its figures are placeholders
# while its version is a draft.
"rate_card": {"version": card.version, "draft": card.is_draft},
}
if kind == CAPABILITY_MODEL:
# The catalogue's entries that apply to this operating spec, found by
# code. Where to start: take each, or say why it does not apply.
scope = spec.agreed(state.get("deliverables") or {})
context["capabilities_proposed"] = catalogue.applicable(scope)
if kind == TARGET_OPERATING_MODEL:
context["rate_card"].update(
countries=sorted(card.countries), levels=dict(card.levels)
)
return {}, context
def outputs(
state: Mapping[str, Any], deliverables: Upstream, files: dict[str, str]
) -> dict[str, Any]:
cost = _staffing(deliverables)
found = _findings(deliverables)
if found:
files[CHANGE_REQUEST_FILE] = change_request(state, found)
return {
"staffing": None
if cost is None
else {
"people": cost["people"],
"cost_per_month": cost["cost_per_month"],
"currency": cost["currency"],
"rate_card": cost["rate_card"],
},
"findings": [str(item["id"]) for item in found],
"change_request": CHANGE_REQUEST_FILE if found else None,
"capability_sources_verified": catalogue.verified,
}
deliverable_specs = {
each.kind: each
for each in (
DeliverableSpec(
OPERATING_SCOPE,
SCOPING,
"scope-analyst",
sections=("Scope statement",),
attachments=(SCOPE_FILE, SCOPE_DATA_FILE),
),
DeliverableSpec(
OPERATIONAL_REQUIREMENTS,
REQUIREMENTS,
"operations-analyst",
depends_on=(OPERATING_SCOPE,),
sections=("Operational requirements", "What was not stated"),
attachments=(REQUIREMENTS_FILE,),
),
DeliverableSpec(
CAPABILITY_MODEL,
DESIGN,
"capability-modeller",
depends_on=(OPERATIONAL_REQUIREMENTS,),
sections=("Capabilities", "Sources"),
attachments=(CAPABILITIES_FILE,),
),
DeliverableSpec(
TARGET_OPERATING_MODEL,
DESIGN,
"operating-model-architect",
depends_on=(CAPABILITY_MODEL,),
# The Specialist writes the reasoning and the graph. On submission
# code adds the responsibility matrix, the staffing and cost and
# the findings to the content, and the organisation chart and the
# staffing figures to the attachments.
sections=("Design rationale",),
attachments=(GRAPH_FILE,),
graph=graph.SHAPE,
),
DeliverableSpec(
VALIDATION_RESULTS,
VALIDATION,
"validator",
depends_on=(TARGET_OPERATING_MODEL,),
sections=("Check verdicts",),
attachments=(VERDICTS_FILE,),
),
DeliverableSpec(
GUIDE,
PACKAGING,
"packager",
depends_on=(VALIDATION_RESULTS,),
# The packager writes the summary; code writes every other
# section from the data when the guide is submitted.
sections=guide.SECTIONS,
reads_in_full=(
OPERATING_SCOPE,
OPERATIONAL_REQUIREMENTS,
CAPABILITY_MODEL,
TARGET_OPERATING_MODEL,
VALIDATION_RESULTS,
),
),
)
}
return Workflow(
name="target-operating-model",
about=ABOUT,
phases=PHASES,
deliverables=deliverable_specs,
final=GUIDE,
final_file=GUIDE_FILE,
data_checks={
OPERATIONAL_REQUIREMENTS: (REQUIREMENTS_FILE, chain.check_requirements),
CAPABILITY_MODEL: (CAPABILITIES_FILE, chain.check_capabilities(catalogue)),
TARGET_OPERATING_MODEL: (
GRAPH_FILE,
graph.check(card, catalogue.frameworks),
),
VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts),
},
for_readers={
TARGET_OPERATING_MODEL: graph.MATRIX_HEADING,
VALIDATION_RESULTS: scenarios.HEADING,
},
spec_deliverable=OPERATING_SCOPE,
validation=ValidationPolicy(
kind=VALIDATION_RESULTS,
data_file=VERDICTS_FILE,
# A failed Check is a fault in who does what: the graph is revised. One
# that fails twice running is a fault in what the organisation must be
# able to do: the capability model is.
implementation=TARGET_OPERATING_MODEL,
design=CAPABILITY_MODEL,
check_ids=check_ids,
known_ids=known_ids,
),
on_submit={
TARGET_OPERATING_MODEL: with_graph_views,
VALIDATION_RESULTS: with_scenarios,
GUIDE: with_guide_sections,
},
approval_details=approval_details,
approval_facts=approval_facts,
summary_lines=summary_lines,
describe_approval=describe_approval,
agreed=lambda deliverables: json.dumps(chain.requirements(deliverables)),
changes=ChangePolicy(
file=CHANGES_FILE,
summary=change_summary,
is_empty=changes_empty,
in_words=changes_in_words,
),
subject="a target operating model",
describe_design=lambda deliverables: "\n".join(
f"- {item.get('name')} ({item.get('kind')}, {item.get('product', '')})"
for item in spec.items(spec.agreed(deliverables))
),
task_entries=task_entries,
outputs=outputs,
# A solution architecture's data files are read in code. Anything else a
# caller supplies is a document for the scope analyst to read.
digest=lambda sources: digest.architecture(sources, kinds),
card=CardText(
description=(
"Designs a target operating model with you for a solution: "
"operational requirements, the Capabilities needed, who is "
"accountable and responsible, staffing and cost from a rate card, "
"and a validation against the events it must handle."
),
skill_id="target-operating-model",
skill_name="Target operating model",
tags=("operations", "operating-model"),
examples=(
"Design the operating model for this landing zone, run as a managed service.",
"Who runs this platform, at what cost, from which countries?",
),
),
done="The target operating model is complete and approved.",
)
def change_request(state: Mapping[str, Any], found: list[dict[str, Any]]) -> str:
"""The findings, as a request to whoever owns the design to change it.
Written by code from the findings. Where the operating spec was digested from a
solution architecture, it is in the form that agent accepts as a Change request
against the Execution it came from.
"""
values = ((state.get("scope") or {}).get("working") or {}).get("values") or {}
source = str(values.get("metadata.source") or "")
lines = ["# Changes operations needs to the solution", ""]
if source:
lines += [
(
f"The operating spec was digested from `{source}`. Send what follows to "
"the solution architecture agent as a Change request against that "
"Execution: the `baseline` is its id, in the same Customer case."
),
"",
]
else:
lines += [
(
"The operating spec did not come from a solution architecture this "
"agent can name. What follows is for whoever owns the design."
),
"",
]
lines += [
(
"Operating the solution as designed needs these changes to it. Each was "
"found while designing its operating model; none was designed around."
),
"",
]
for item in found:
about = ", ".join(
str(i) for i in item.get("source_ref") or item.get("about") or []
)
lines += [
f"## {item['id']}" + (f": {about}" if about else ""),
"",
f"**What is missing.** {item.get('lacks')}",
"",
f"**What is asked for.** {item.get('proposed')}",
"",
]
return "\n".join(lines)
__all__ = ["FINDINGS_FILE", "ROOT", "build", "change_request", "change_summary"]