"""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 [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:]))