feat: start an Execution from a scope spec (ADR-0008, iteration 9 step 1)
Some checks failed
validation / verify (push) Failing after 10s
Some checks failed
validation / verify (push) Failing after 10s
A scope spec is a YAML file of what the customer wants and the facts a design depends on, complete or partly filled. It sits beside the Intent, which stays in the customer's words. - skills/scoping holds a provider-neutral catalogue of 63 fields; the Cloud provider's bundle supplies the values it allows for the fields left to it. - app/scope.py reads a spec against the catalogue with no model: it refuses an unknown field or a value of the wrong type, and yields what is stated, what is left to the agent, what is unknown and how pressing each gap is. A field may say ask, decide or not_applicable. - ExecutionEngine.start(scope=...), /generate, A2A metadata and evaluation cases accept one. Its statement is the request, its engagement reference names the Customer case, and its run options apply. A pre-approved start is refused when an essential field is not settled. - The spec as supplied is kept unaltered beside a completed copy with assumptions, gaps, provenance, readiness and a status. - Every Specialist is shown the spec and given the Skill: a stated choice binds, exclusions are out of scope. - Covers workloads and platform foundations; case-08-landing-zone starts from a benchmark spec. Plans for scoping (iteration 9) and the work breakdown structure (iteration 10, nothing built), and the design spec they come from. Not run with real models. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -130,8 +130,9 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
baseline=options.get("baseline"),
|
||||
overlay_skills=options.get("overlay_skills") or (),
|
||||
terraform_modules=options.get("terraform_modules"),
|
||||
scope=options.get("scope"),
|
||||
execution_id=task_id,
|
||||
pre_approved=bool(options.get("pre_approved", False)),
|
||||
pre_approved=options.get("pre_approved"),
|
||||
allow_cloud_read=options.get("allow_cloud_read"),
|
||||
)
|
||||
else:
|
||||
|
||||
76
app/agent.py
76
app/agent.py
@@ -46,6 +46,7 @@ from app.nodes.router import (
|
||||
)
|
||||
from app.providers import ProviderBundle, load_provider
|
||||
from app.recorder import DatabaseRecorder, ExecutionRecorder
|
||||
from app.scope import ESSENTIAL, Catalogue, Scope, read_scope, slug
|
||||
from app.skills.agent_skills import discover_skills, skill_version
|
||||
from app.states.execution_state import check_customer_case
|
||||
from app.states.ledger import Ledger
|
||||
@@ -106,6 +107,9 @@ class ExecutionEngine:
|
||||
assess_at_end: bool = False,
|
||||
modules_available: bool = False,
|
||||
default_modules: bool = False,
|
||||
scope_catalogue: Catalogue | None = None,
|
||||
scope_values: Mapping[str, Sequence[str]] | None = None,
|
||||
scope_skill: str | None = None,
|
||||
) -> None:
|
||||
required = {
|
||||
ORCHESTRATOR,
|
||||
@@ -115,6 +119,11 @@ class ExecutionEngine:
|
||||
if missing:
|
||||
raise ValueError(f"Missing roles: {', '.join(missing)}")
|
||||
self._max_revisions = max_revisions
|
||||
# The catalogue a scope spec is read against (ADR-0008); None when this
|
||||
# deployment's Cloud provider has none.
|
||||
self._scope_catalogue = scope_catalogue
|
||||
self._scope_values = dict(scope_values or {})
|
||||
self._scope_skill = scope_skill
|
||||
# Whether the Cloud provider approves any module sources, and whether an
|
||||
# Execution uses them when its caller does not say.
|
||||
self._modules_available = modules_available
|
||||
@@ -154,13 +163,14 @@ class ExecutionEngine:
|
||||
*,
|
||||
session_id: str | None = None,
|
||||
customer_case: str | None = None,
|
||||
pre_approved: bool = False,
|
||||
pre_approved: bool | None = None,
|
||||
allow_cloud_read: bool | None = None,
|
||||
execution_id: str | None = None,
|
||||
scripted_answers: Sequence[Sequence[str]] = (),
|
||||
baseline: str | None = None,
|
||||
overlay_skills: Sequence[str] = (),
|
||||
terraform_modules: bool | None = None,
|
||||
scope: str | Mapping[str, Any] | None = None,
|
||||
) -> Interaction:
|
||||
"""Start an Execution. `scripted_answers` are (regex, answer[, asker]) entries a
|
||||
pre-approved Execution uses to answer questions, for evaluation runs.
|
||||
@@ -180,7 +190,50 @@ class ExecutionEngine:
|
||||
does as its Baseline did and any other Execution takes the deployment's
|
||||
default, which is plain resources. Opting in is refused when the provider
|
||||
approves no sources.
|
||||
|
||||
`scope` is a scope spec (ADR-0008), as YAML text or already parsed. It may
|
||||
be complete or partly filled. The start is refused when it names a field
|
||||
the catalogue does not have or holds a value of the wrong type, and, for a
|
||||
pre-approved Execution, when an essential field is not settled: nobody is
|
||||
there to ask. What the spec states under `run` applies where the caller
|
||||
gave no value of their own. Its statement of intent is the request when
|
||||
none is given.
|
||||
"""
|
||||
read = self._read_scope(scope) if scope is not None else None
|
||||
if read is not None:
|
||||
run = read.values
|
||||
if pre_approved is None:
|
||||
pre_approved = bool(run.get("run.pre_approved", False))
|
||||
if allow_cloud_read is None and "run.allow_cloud_read" in run:
|
||||
allow_cloud_read = bool(run["run.allow_cloud_read"])
|
||||
if terraform_modules is None and "run.terraform_modules" in run:
|
||||
terraform_modules = bool(run["run.terraform_modules"])
|
||||
overlay_skills = [*overlay_skills, *run.get("run.overlay_skills", [])]
|
||||
if (
|
||||
customer_case
|
||||
and read.customer_case
|
||||
and slug(customer_case) != (read.customer_case)
|
||||
):
|
||||
raise ValueError(
|
||||
f"The scope spec is for {read.customer_case}, and this was "
|
||||
f"started for {customer_case}."
|
||||
)
|
||||
customer_case = customer_case or read.customer_case
|
||||
# The spec's statement is the customer's; it is what gets recorded.
|
||||
workflow_request = read.statement or workflow_request
|
||||
missing = read.gaps(ESSENTIAL)
|
||||
if pre_approved and missing:
|
||||
raise ValueError(
|
||||
"The scope spec leaves essential fields unsettled, and a "
|
||||
"pre-approved Execution has nobody to ask: "
|
||||
+ ", ".join(gap["field"] for gap in missing)
|
||||
+ ". Give each a value, or `decide` to leave it to the agent."
|
||||
)
|
||||
pre_approved = bool(pre_approved)
|
||||
if not workflow_request.strip():
|
||||
raise ValueError(
|
||||
"A request is needed: text, or a scope spec with a statement."
|
||||
)
|
||||
customer_case = check_customer_case(customer_case)
|
||||
execution_id = execution_id or str(uuid.uuid4())
|
||||
if await self._exists(execution_id):
|
||||
@@ -224,6 +277,8 @@ class ExecutionEngine:
|
||||
session_id=session_id,
|
||||
workflow_request=workflow_request,
|
||||
baseline=baseline or None,
|
||||
scope_supplied=scope if isinstance(scope, str) else None,
|
||||
scope_completed=read.completed(read.status(pre_approved)) if read else None,
|
||||
)
|
||||
initial: dict[str, Any] = {
|
||||
"execution_id": execution_id,
|
||||
@@ -236,6 +291,15 @@ class ExecutionEngine:
|
||||
# Overlay Skills this Execution loads, each with the version it had.
|
||||
"overlay_skills": {name: self._overlays[name] for name in chosen},
|
||||
"terraform_modules": terraform_modules,
|
||||
# What the customer's scope spec settles and leaves open; None without one.
|
||||
"scope": {
|
||||
"skill": self._scope_skill,
|
||||
"status": read.status(pre_approved),
|
||||
"readiness": read.readiness(),
|
||||
"context": read.for_context(),
|
||||
}
|
||||
if read
|
||||
else None,
|
||||
"risks": [],
|
||||
"pre_approved": pre_approved,
|
||||
"allow_cloud_read": allow_cloud_read,
|
||||
@@ -274,6 +338,13 @@ class ExecutionEngine:
|
||||
await self._graph.ainvoke(initial, self._config(execution_id))
|
||||
return await self.interaction(execution_id)
|
||||
|
||||
def _read_scope(self, supplied: str | Mapping[str, Any]) -> Scope:
|
||||
if self._scope_catalogue is None:
|
||||
raise ValueError("This deployment has no scope spec catalogue.")
|
||||
return read_scope(
|
||||
supplied, self._scope_catalogue, provider_values=self._scope_values
|
||||
)
|
||||
|
||||
async def resume(self, execution_id: str, reply: Mapping[str, Any]) -> Interaction:
|
||||
"""Answer the Execution's current prompt: {"reply"} | {"approval"} | {"permission"}."""
|
||||
current = await self.interaction(execution_id)
|
||||
@@ -517,6 +588,9 @@ async def open_assembly(
|
||||
else None,
|
||||
skill_threshold=settings.JEV_SKILL_THRESHOLD,
|
||||
assess_at_end=settings.JEV_ASSESS_EXECUTIONS,
|
||||
scope_catalogue=bundle.scope_catalogue() if bundle.scope_skill else None,
|
||||
scope_values=bundle.scope_values,
|
||||
scope_skill=bundle.scope_skill,
|
||||
modules_available=bool(bundle.terraform_module_namespaces),
|
||||
default_modules=settings.TERRAFORM_MODULES,
|
||||
overlays={
|
||||
|
||||
@@ -14,15 +14,20 @@ nothing was delivered for it. history.json is the index of the case.
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.states.execution_state import case_dir
|
||||
|
||||
INTENT_DIR = "intent"
|
||||
HISTORY_FILENAME = "history.json"
|
||||
IN_PROGRESS = "in_progress"
|
||||
SCOPE_SUPPLIED = ".scope.yaml"
|
||||
SCOPE_COMPLETED = ".scope.completed.yaml"
|
||||
|
||||
|
||||
def intent_dir(output_root: Path, customer_case: str) -> Path:
|
||||
@@ -50,6 +55,8 @@ def record_intent(
|
||||
session_id: str,
|
||||
workflow_request: str,
|
||||
baseline: str | None = None,
|
||||
scope_supplied: str | None = None,
|
||||
scope_completed: Mapping[str, Any] | None = None,
|
||||
) -> int:
|
||||
"""Record a new statement of the customer's intent and return its version.
|
||||
|
||||
@@ -71,6 +78,19 @@ def record_intent(
|
||||
f"## What the customer wants\n\n{workflow_request.strip()}\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
scope_files = None
|
||||
if scope_completed is not None:
|
||||
# The spec as supplied, unaltered, and the completed copy beside it.
|
||||
scope_files = {"completed": f"{INTENT_DIR}/{version:03d}{SCOPE_COMPLETED}"}
|
||||
(folder / f"{version:03d}{SCOPE_COMPLETED}").write_text(
|
||||
yaml.safe_dump(dict(scope_completed), sort_keys=False, allow_unicode=True),
|
||||
encoding="utf-8",
|
||||
)
|
||||
if scope_supplied:
|
||||
scope_files["supplied"] = f"{INTENT_DIR}/{version:03d}{SCOPE_SUPPLIED}"
|
||||
(folder / f"{version:03d}{SCOPE_SUPPLIED}").write_text(
|
||||
scope_supplied, encoding="utf-8"
|
||||
)
|
||||
history["intents"].append(
|
||||
{
|
||||
"version": version,
|
||||
@@ -82,6 +102,7 @@ def record_intent(
|
||||
"status": IN_PROGRESS,
|
||||
"execution": None,
|
||||
"baseline": baseline,
|
||||
"scope": scope_files,
|
||||
}
|
||||
)
|
||||
_write_history(folder, history)
|
||||
|
||||
@@ -62,8 +62,10 @@ def create_app(
|
||||
except ValueError:
|
||||
body = {}
|
||||
workflow_request = str(body.get("request") or "").strip()
|
||||
if not workflow_request:
|
||||
return JSONResponse({"error": "'request' is required"}, status_code=400)
|
||||
if not workflow_request and not body.get("scope"):
|
||||
return JSONResponse(
|
||||
{"error": "'request' or a 'scope' spec is required"}, status_code=400
|
||||
)
|
||||
try:
|
||||
interaction = await assembly.engine.start(
|
||||
workflow_request,
|
||||
@@ -72,6 +74,7 @@ def create_app(
|
||||
baseline=body.get("baseline"),
|
||||
overlay_skills=body.get("overlay_skills") or (),
|
||||
terraform_modules=body.get("terraform_modules"),
|
||||
scope=body.get("scope"),
|
||||
pre_approved=True,
|
||||
allow_cloud_read=bool(body.get("allow_cloud_read", False)),
|
||||
)
|
||||
|
||||
@@ -481,6 +481,10 @@ def make_execution_nodes(
|
||||
role = dataclasses.replace(
|
||||
role, skills=(*role.skills, *(n for n in named if n not in role.skills))
|
||||
)
|
||||
scope_skill = task_input.get("scope_skill")
|
||||
if scope_skill and scope_skill not in role.skills:
|
||||
# An Execution with a scope spec: every Specialist can read what it means.
|
||||
role = dataclasses.replace(role, skills=(*role.skills, scope_skill))
|
||||
opted_in = bool(task_input.get("terraform_modules"))
|
||||
MODULES_OPTED_IN.set(opted_in)
|
||||
if opted_in and role.modules_skill:
|
||||
@@ -908,6 +912,7 @@ def _specialist_input(
|
||||
"allow_cloud_read": state.get("allow_cloud_read"),
|
||||
# Whether this Execution opted into published Terraform modules.
|
||||
"terraform_modules": bool(state.get("terraform_modules")),
|
||||
"scope_skill": (state.get("scope") or {}).get("skill"),
|
||||
"working": dict(state.get("working", {}).get(kind.value, {})),
|
||||
# Whether the user has been shown a draft of this Deliverable. Answering some
|
||||
# other question about it, such as what to do after it stopped, is not that.
|
||||
@@ -937,6 +942,9 @@ def _specialist_input(
|
||||
# Skills carrying the organisation's standards or this engagement's
|
||||
# constraints. Where one disagrees with general guidance, it wins.
|
||||
"overlay_skills": sorted(state.get("overlay_skills") or {}),
|
||||
# What the customer's scope spec states, leaves to the agent, and
|
||||
# leaves unknown. None when no spec was supplied.
|
||||
"scope": (state.get("scope") or {}).get("context"),
|
||||
# False: infrastructure code is plain resources. True: a published
|
||||
# module may be used where the modules Skill says one fits.
|
||||
"terraform_modules": bool(state.get("terraform_modules")),
|
||||
@@ -1357,6 +1365,12 @@ def _write_outputs(
|
||||
"overlay_skills": dict(state.get("overlay_skills") or {}),
|
||||
# Whether its infrastructure code was allowed published modules.
|
||||
"terraform_modules": bool(state.get("terraform_modules")),
|
||||
# How much of the scope spec the customer supplied; None without a spec.
|
||||
"scope": {
|
||||
key: (state.get("scope") or {}).get(key) for key in ("status", "readiness")
|
||||
}
|
||||
if state.get("scope")
|
||||
else None,
|
||||
"status": status,
|
||||
"warnings": list(state.get("warnings", [])),
|
||||
# Flags a person should look at; nothing was done about them.
|
||||
|
||||
@@ -14,6 +14,7 @@ from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.scope import Catalogue, load_catalogue
|
||||
from app.skills.agent_skills import SkillFormatError, SkillMeta, discover_skills
|
||||
|
||||
TIERS = ("general", "cloud_read")
|
||||
@@ -85,6 +86,17 @@ class ProviderBundle:
|
||||
# The Skill approved lessons are published in (ADR-0004); None when the provider
|
||||
# has none. A Specialist is given it once it holds lessons for its Deliverable.
|
||||
lessons_skill: str | None = None
|
||||
# The Skill that holds the scope spec's catalogue (ADR-0008), and the values
|
||||
# this provider allows for the fields the catalogue leaves to a provider.
|
||||
scope_skill: str | None = None
|
||||
scope_values: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
|
||||
|
||||
def scope_catalogue(self) -> Catalogue:
|
||||
if not self.scope_skill:
|
||||
raise ProviderConfigError(f"The {self.name} bundle names no scope Skill.")
|
||||
return load_catalogue(
|
||||
self.skills[self.scope_skill].path / "assets" / "catalogue.yaml"
|
||||
)
|
||||
|
||||
def mcp_servers_for_role(
|
||||
self, role: str, include_preview: bool = True
|
||||
@@ -233,6 +245,15 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
|
||||
if lessons_skill is not None and lessons_skill not in skills:
|
||||
raise fail(f"'lessons_skill' references unknown skill {lessons_skill!r}")
|
||||
|
||||
scope = config.get("scope") or {}
|
||||
scope_skill = scope.get("skill") or None
|
||||
if scope_skill is not None and scope_skill not in skills:
|
||||
raise fail(f"'scope.skill' references unknown skill {scope_skill!r}")
|
||||
scope_values = {
|
||||
str(path): tuple(str(value) for value in values or ())
|
||||
for path, values in (scope.get("values") or {}).items()
|
||||
}
|
||||
|
||||
return ProviderBundle(
|
||||
name=name,
|
||||
skills_dirs=skills_dirs,
|
||||
@@ -256,4 +277,6 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
|
||||
or ()
|
||||
),
|
||||
lessons_skill=lessons_skill,
|
||||
scope_skill=scope_skill,
|
||||
scope_values=scope_values,
|
||||
)
|
||||
|
||||
460
app/scope.py
Normal file
460
app/scope.py
Normal file
@@ -0,0 +1,460 @@
|
||||
"""The scope spec: what the customer wants and the facts a design depends on, as a
|
||||
file (ADR-0008).
|
||||
|
||||
A spec may arrive complete, partly filled or not at all. This reads one against the
|
||||
catalogue of fields a Skill holds, and says exactly what is settled and what is not.
|
||||
No model is involved: whether a field is filled is a fact.
|
||||
|
||||
a value the customer states it supplied
|
||||
ask, or absent not known yet a gap, with its question
|
||||
decide the customer leaves the choice to the agent an assumption
|
||||
not_applicable does not apply nothing asked or assumed
|
||||
|
||||
The file supplied is never altered. `Scope.completed()` is the copy written beside
|
||||
it, with the sections the agent writes: assumptions, gaps, where each value came
|
||||
from, and a count of each.
|
||||
|
||||
.venv/bin/python -m app.scope check <spec.yaml> [provider]
|
||||
.venv/bin/python -m app.scope template [kind]
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import re
|
||||
import sys
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
ASK, DECIDE, NOT_APPLICABLE = "ask", "decide", "not_applicable"
|
||||
MARKERS = (ASK, DECIDE, NOT_APPLICABLE)
|
||||
SUPPLIED, ASSUMED, UNKNOWN = "supplied", "assumed", "unknown"
|
||||
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, ...] = ()
|
||||
|
||||
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 ()),
|
||||
)
|
||||
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 = ""
|
||||
|
||||
@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, state in self.states.items():
|
||||
if state != DECIDE:
|
||||
continue
|
||||
spec = self.catalogue.fields[path]
|
||||
found.append(
|
||||
{
|
||||
"id": f"ASSUMP-{len(found) + 1:02d}",
|
||||
"field": path,
|
||||
"statement": f"The customer left {path} to the agent. "
|
||||
f"Default: {spec.default if spec.default is not None else 'the agent chooses'}.",
|
||||
"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())
|
||||
return {
|
||||
SUPPLIED: len(self.values),
|
||||
ASSUMED: states.count(DECIDE),
|
||||
UNKNOWN: states.count(ASK),
|
||||
NOT_APPLICABLE: states.count(NOT_APPLICABLE),
|
||||
}
|
||||
|
||||
def status(self, pre_approved: bool = False) -> str:
|
||||
"""Where the spec stands. With nobody to ask, what is important and unknown
|
||||
is defaulted and listed, so only an essential gap keeps it a draft."""
|
||||
if pre_approved:
|
||||
return DRAFT if self.gaps(ESSENTIAL) else APPROVED
|
||||
return DRAFT if self.gaps(ESSENTIAL, IMPORTANT) else UNDER_REVIEW
|
||||
|
||||
def completed(self, status: str) -> dict[str, Any]:
|
||||
"""The completed copy: every field of the catalogue, and the agent's
|
||||
sections."""
|
||||
document: dict[str, Any] = {"schema_version": self.catalogue.schema_version}
|
||||
for path in self.catalogue.fields:
|
||||
value = self.values.get(path, self.states.get(path, ASK))
|
||||
_put(document, path, value)
|
||||
_put(document, "metadata.status", status)
|
||||
provenance = {path: SUPPLIED 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 not path.startswith(("run.", "metadata.")):
|
||||
_put(stated, path, value)
|
||||
return {
|
||||
"kind": self.kind,
|
||||
"stated": stated,
|
||||
"to_decide": [
|
||||
{
|
||||
"field": path,
|
||||
"default": self.catalogue.fields[path].default,
|
||||
"affects": self.catalogue.fields[path].affects,
|
||||
}
|
||||
for path, state in self.states.items()
|
||||
if state == DECIDE and not path.startswith("run.")
|
||||
],
|
||||
"to_ask": [
|
||||
gap for gap in self.gaps() if not gap["field"].startswith("run.")
|
||||
],
|
||||
"not_applicable": sorted(
|
||||
path for path, state in self.states.items() if state == NOT_APPLICABLE
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def _put(document: dict[str, Any], path: str, value: Any) -> None:
|
||||
*parents, last = path.split(".")
|
||||
node = document
|
||||
for part in parents:
|
||||
node = node.setdefault(part, {})
|
||||
node[last] = value
|
||||
|
||||
|
||||
def slug(reference: str) -> str:
|
||||
"""A Customer case id from an engagement reference: `ENG-2026-UK-084` and
|
||||
`eng-2026-uk-084` name the same case."""
|
||||
return _SLUG.sub("-", reference.strip().lower()).strip("-")[:64]
|
||||
|
||||
|
||||
def read_scope(
|
||||
supplied: str | Mapping[str, Any],
|
||||
catalogue: Catalogue,
|
||||
*,
|
||||
provider_values: Mapping[str, Sequence[str]] | None = None,
|
||||
) -> Scope:
|
||||
"""Read a scope spec. Raises ScopeError naming every problem: YAML that does not
|
||||
parse, a field the catalogue does not have, a value of the wrong type."""
|
||||
text = supplied if isinstance(supplied, str) else yaml.safe_dump(dict(supplied))
|
||||
try:
|
||||
data = yaml.safe_load(text) if isinstance(supplied, str) else dict(supplied)
|
||||
except yaml.YAMLError as exc:
|
||||
raise ScopeError([f"not valid YAML ({exc})"]) from exc
|
||||
if not isinstance(data, Mapping):
|
||||
raise ScopeError(["the spec must be a mapping of sections"])
|
||||
|
||||
problems: list[str] = []
|
||||
leaves: dict[str, Any] = {}
|
||||
aliases = catalogue.aliases()
|
||||
prefixes = {
|
||||
".".join(path.split(".")[:depth])
|
||||
for path in catalogue.fields
|
||||
for depth in range(1, len(path.split(".")))
|
||||
}
|
||||
|
||||
def walk(node: Any, path: str) -> None:
|
||||
target = aliases.get(path, path)
|
||||
if path in _AGENT_FIELDS or path in _AGENT_WRITTEN:
|
||||
return
|
||||
if target in catalogue.fields:
|
||||
if target in leaves and leaves[target] != node and path != target:
|
||||
problems.append(f"{path} and {target} name the same thing and differ")
|
||||
leaves[target] = node
|
||||
return
|
||||
if path in prefixes:
|
||||
if isinstance(node, Mapping):
|
||||
for key, value in node.items():
|
||||
walk(value, f"{path}.{key}")
|
||||
elif node in MARKERS or node is None:
|
||||
# A whole section marked at once applies to every field in it.
|
||||
for name in catalogue.fields:
|
||||
if name.startswith(path + "."):
|
||||
leaves.setdefault(name, node)
|
||||
else:
|
||||
problems.append(f"{path} is a section, not a value")
|
||||
return
|
||||
problems.append(f"{path} is not a field of the scope spec")
|
||||
|
||||
for key, value in data.items():
|
||||
walk(value, str(key))
|
||||
|
||||
kind = leaves.get(KIND_FIELD)
|
||||
kind = str(kind) if kind in catalogue.kinds else None
|
||||
scope = Scope(catalogue, kind, supplied_text=text)
|
||||
extra = dict(provider_values or {})
|
||||
for path, spec in catalogue.fields.items():
|
||||
value = leaves.get(path)
|
||||
if value is None or value == ASK:
|
||||
scope.states[path] = ASK
|
||||
elif value in (DECIDE, NOT_APPLICABLE):
|
||||
scope.states[path] = value
|
||||
else:
|
||||
fault = _fault(spec, value, extra.get(path, ()))
|
||||
if fault:
|
||||
problems.append(f"{path}: {fault}")
|
||||
else:
|
||||
scope.values[path] = _plain(value)
|
||||
case = scope.values.get(CASE_FIELD)
|
||||
if case is not None:
|
||||
scope.values[CASE_FIELD] = slug(str(case))
|
||||
if not scope.values[CASE_FIELD]:
|
||||
problems.append(f"{CASE_FIELD}: needs letters or digits")
|
||||
if problems:
|
||||
raise ScopeError(problems)
|
||||
return scope
|
||||
|
||||
|
||||
def _plain(value: Any) -> Any:
|
||||
"""A value as plain data: YAML reads a date as a date, and state must be JSON."""
|
||||
if isinstance(value, (dt.date, dt.datetime)):
|
||||
return value.isoformat()
|
||||
if isinstance(value, Mapping):
|
||||
return {str(k): _plain(v) for k, v in value.items()}
|
||||
if isinstance(value, (list, tuple)):
|
||||
return [_plain(item) for item in value]
|
||||
return value
|
||||
|
||||
|
||||
def _fault(spec: FieldSpec, value: Any, provider_values: Sequence[str]) -> str:
|
||||
"""Why a value does not fit its field; "" when it does."""
|
||||
kind = spec.type
|
||||
if kind in ("string", "text"):
|
||||
return "" if isinstance(value, (str, int, float)) else "must be text"
|
||||
if kind == "integer":
|
||||
ok = isinstance(value, int) and not isinstance(value, bool)
|
||||
return "" if ok else "must be a whole number"
|
||||
if kind == "number":
|
||||
ok = isinstance(value, (int, float)) and not isinstance(value, bool)
|
||||
return "" if ok else "must be a number"
|
||||
if kind == "boolean":
|
||||
return "" if isinstance(value, bool) else "must be true or false"
|
||||
if kind == "date":
|
||||
if isinstance(value, (dt.date, dt.datetime)):
|
||||
return ""
|
||||
try:
|
||||
dt.date.fromisoformat(str(value))
|
||||
except ValueError:
|
||||
return "must be a date, as YYYY-MM-DD"
|
||||
return ""
|
||||
if kind == "enum":
|
||||
allowed = (*spec.values, *provider_values)
|
||||
if not allowed or str(value) in allowed:
|
||||
return ""
|
||||
return f"must be one of {', '.join(allowed)}"
|
||||
if kind == "list":
|
||||
return "" if isinstance(value, list) else "must be a list"
|
||||
if kind == "records":
|
||||
if not isinstance(value, list):
|
||||
return "must be a list of entries"
|
||||
known = {*spec.keys, *spec.optional_keys}
|
||||
for number, entry in enumerate(value, start=1):
|
||||
if not isinstance(entry, Mapping):
|
||||
return f"entry {number} must have named fields"
|
||||
missing = [key for key in spec.keys if not entry.get(key)]
|
||||
if missing:
|
||||
return f"entry {number} needs {', '.join(missing)}"
|
||||
unknown = sorted(set(map(str, entry)) - known)
|
||||
if unknown:
|
||||
return f"entry {number} has unknown fields {', '.join(unknown)}"
|
||||
return ""
|
||||
return f"has an unknown type {kind} in the catalogue"
|
||||
|
||||
|
||||
def render_template(catalogue: Catalogue, kind: str | None = None) -> str:
|
||||
"""A scope spec with every field set to ask, to fill in."""
|
||||
document: dict[str, Any] = {}
|
||||
for path, spec in catalogue.fields.items():
|
||||
if path == KIND_FIELD and kind:
|
||||
_put(document, path, kind)
|
||||
elif spec.tier_for(kind) != OPTIONAL or kind is None:
|
||||
_put(document, path, ASK)
|
||||
header = (
|
||||
"# Scope spec. Give each field a value, or: ask (not known yet), decide\n"
|
||||
"# (you choose), not_applicable. A field left out is read as ask.\n"
|
||||
)
|
||||
return header + yaml.safe_dump(document, sort_keys=False, allow_unicode=True)
|
||||
|
||||
|
||||
def render_reading(scope: Scope) -> str:
|
||||
"""What a spec settles and what it leaves open, for a person."""
|
||||
counts = scope.readiness()
|
||||
lines = [
|
||||
f"Engagement kind: {scope.kind or 'not stated'}",
|
||||
(
|
||||
f"{counts[SUPPLIED]} supplied, {counts[ASSUMED]} left to the agent, "
|
||||
f"{counts[UNKNOWN]} unknown, {counts[NOT_APPLICABLE]} not applicable."
|
||||
),
|
||||
]
|
||||
for severity, title in (
|
||||
("HIGH", "Essential, needed before work can start"),
|
||||
("MEDIUM", "Important, asked when someone is present"),
|
||||
):
|
||||
gaps = [gap for gap in scope.gaps() if gap["severity"] == severity]
|
||||
if gaps:
|
||||
lines += ["", f"{title}:"]
|
||||
lines += [f" {gap['field']}: {gap['prompt']}" for gap in gaps]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def main(arguments: Sequence[str]) -> int:
|
||||
from app.config import get_settings
|
||||
from app.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:]))
|
||||
@@ -59,6 +59,9 @@ class ExecutionState(TypedDict, total=False):
|
||||
risks: list[dict[str, Any]] # flags on what the user wrote, for a person to see
|
||||
overlay_skills: dict[str, str] # overlay Skills this Execution loads -> version
|
||||
terraform_modules: bool # opted into published Terraform modules
|
||||
# The customer's scope spec as read at the start: its Skill, status, readiness
|
||||
# and what a Specialist is shown of it. None when no spec was supplied.
|
||||
scope: dict[str, Any] | None
|
||||
baseline: dict[str, Any] | None # a Change request's Baseline, read from its files
|
||||
pre_approved: bool
|
||||
allow_cloud_read: bool | None
|
||||
|
||||
Reference in New Issue
Block a user