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