feat: scoping is the first Phase, completed in conversation (iteration 9 step 2)
Some checks failed
validation / verify (push) Failing after 10s
Some checks failed
validation / verify (push) Failing after 10s
Every Execution now begins by agreeing the scope, before requirements. - A new Phase and Deliverable, produced by a scope analyst with two tools: scope_read shows what is settled and what is not; scope_set records fields with where each value came from (the request, the customer's answer, or an assumption with its reason). Code checks each value against the catalogue. - With someone present the analyst asks for what is missing; with nobody present it assumes it, visibly. With no spec it drafts one from the request. A value the customer stated in the file is changed only by their own answer. - A submission cannot leave an essential field unknown. Code writes the completed spec, the data every later Specialist reads, and the information register, from what was recorded. - The spec's status follows the Execution: under review, approved, then locked as a Baseline. A Change request starts from the delivered scope. - The requirements analyst derives from the agreed scope and no longer asks for what it settles. About 80 tests assumed requirements came first; tests/scoped.py runs scoping ahead of a test's own script, and tests about order and counts are updated. Not run with real models. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -37,6 +37,16 @@ Turn = Sequence[Call] | Callable[[AgentTask], Sequence[Call]]
|
||||
|
||||
# One small, coherent Requirements chain, so sample submissions pass every link.
|
||||
SAMPLE_DATA: dict[str, str] = {
|
||||
"scope.yaml": "engagement:\n kind: workload\nintent:\n statement: Accept events.\n",
|
||||
"scope.json": json.dumps(
|
||||
{
|
||||
"kind": "workload",
|
||||
"stated": {"intent": {"statement": "Accept events."}},
|
||||
"to_decide": [],
|
||||
"to_ask": [],
|
||||
"not_applicable": [],
|
||||
}
|
||||
),
|
||||
"requirements.json": json.dumps(
|
||||
[
|
||||
{"id": "FR-1", "kind": "functional", "text": "Accept events."},
|
||||
|
||||
@@ -58,6 +58,7 @@ from app.tools.local import TerraformRunner, local_tools
|
||||
from app.tools.mcp import McpCatalog, auth_from_config
|
||||
from app.tools.requirements_review import RequirementsReview
|
||||
from app.tools.schema_review import Reviews, SchemaReview
|
||||
from app.tools.scoping import Scoping, to_working
|
||||
from app.tools.skill_routing import routable
|
||||
from app.tools.toolkit import make_tool_factory
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH
|
||||
@@ -155,6 +156,9 @@ class ExecutionEngine:
|
||||
skill_references=skill_references,
|
||||
skill_threshold=skill_threshold,
|
||||
assess_at_end=assess_at_end,
|
||||
scoping=Scoping(scope_catalogue, dict(scope_values or {}), scope_skill)
|
||||
if scope_catalogue is not None
|
||||
else None,
|
||||
).compile(checkpointer=checkpointer)
|
||||
|
||||
async def start(
|
||||
@@ -297,6 +301,8 @@ class ExecutionEngine:
|
||||
"status": read.status(pre_approved),
|
||||
"readiness": read.readiness(),
|
||||
"context": read.for_context(),
|
||||
# What the scope analyst starts from and completes.
|
||||
"working": to_working(read),
|
||||
}
|
||||
if read
|
||||
else None,
|
||||
|
||||
@@ -7,6 +7,7 @@ append outcomes that the next Orchestrator turn applies in order.
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import copy
|
||||
import dataclasses
|
||||
import json
|
||||
import logging
|
||||
@@ -17,6 +18,7 @@ from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any, cast
|
||||
|
||||
import yaml
|
||||
from langgraph.types import Command, Send, interrupt
|
||||
|
||||
from app.adk.runtime import (
|
||||
@@ -37,16 +39,22 @@ from app.adk.runtime import (
|
||||
TurnEnded,
|
||||
)
|
||||
from app.baseline import WORKING_FILENAME
|
||||
from app.customer_case import IN_PROGRESS, close_intent
|
||||
from app.customer_case import (
|
||||
IN_PROGRESS,
|
||||
SCOPE_COMPLETED,
|
||||
close_intent,
|
||||
intent_dir,
|
||||
)
|
||||
from app.nodes.router import ModelOrchestrator, OrchestratorPolicy, TurnView
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.scope import APPROVED, CASE_FIELD, LOCKED, UNDER_REVIEW
|
||||
from app.states.execution_state import (
|
||||
UNASSIGNED_CASE,
|
||||
ExecutionState,
|
||||
execution_dir,
|
||||
lessons_file,
|
||||
)
|
||||
from app.states.ledger import DeliverableStatus, Ledger, LedgerRefusal
|
||||
from app.states.ledger import DeliverableStatus, Ledger, LedgerRefusal, PhaseStatus
|
||||
from app.states.lessons import collect_lesson_candidates, refusal
|
||||
from app.tools import workspace
|
||||
from app.tools.assessment import assess
|
||||
@@ -61,9 +69,12 @@ from app.tools.pillars import (
|
||||
customer_questions,
|
||||
pillars_touched,
|
||||
)
|
||||
from app.tools.scoping import SCOPE_KEY, Scoping, working_from_completed
|
||||
from app.tools.skill_routing import read_first
|
||||
from app.workflows.chain import (
|
||||
IMPLEMENTATION_FILE,
|
||||
SCOPE_DATA_FILE,
|
||||
SCOPE_FILE,
|
||||
VERDICTS_FILE,
|
||||
unimplementable_checks,
|
||||
validation_outcome,
|
||||
@@ -73,6 +84,7 @@ from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
PHASE_ORDER,
|
||||
DeliverableKind,
|
||||
PhaseId,
|
||||
dependencies_for,
|
||||
)
|
||||
from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
||||
@@ -132,6 +144,7 @@ def make_execution_nodes(
|
||||
skill_references: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None,
|
||||
skill_threshold: float = 1.25,
|
||||
assess_at_end: bool = False,
|
||||
scoping: Scoping | None = None,
|
||||
) -> ExecutionNodes:
|
||||
tool_factory = tool_factory or _no_tools
|
||||
# How an Orchestrator turn is decided. The default drives the tools from the
|
||||
@@ -481,7 +494,7 @@ 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")
|
||||
scope_skill = scoping.skill if scoping else 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))
|
||||
@@ -512,6 +525,16 @@ def make_execution_nodes(
|
||||
_start_from(kind, before, working, task_input.get("baseline_basis"))
|
||||
# And from its working material: the advice it was written from.
|
||||
working.update(task_input.get("baseline_working") or {})
|
||||
if kind is DeliverableKind.SCOPE and scoping and SCOPE_KEY not in working:
|
||||
# The spec the customer supplied, or an empty one to draft into.
|
||||
delivered = ((before or {}).get("attachments") or {}).get(SCOPE_FILE)
|
||||
working[SCOPE_KEY] = (
|
||||
# A Change request starts from the scope that was delivered.
|
||||
(working_from_completed(delivered, scoping) if delivered else None)
|
||||
or copy.deepcopy(
|
||||
task_input.get("scope_working") or {"values": {}, "states": {}}
|
||||
)
|
||||
)
|
||||
source = DEPENDENCY_GRAPH[kind].working_copy
|
||||
if source and source is not kind:
|
||||
# The tools work on the files as they were last submitted.
|
||||
@@ -571,6 +594,7 @@ def make_execution_nodes(
|
||||
library=task_input.get("library"),
|
||||
review=review if submission_review else None,
|
||||
baseline=before,
|
||||
scoping=scoping,
|
||||
# With a user present, their first sight of a Deliverable comes
|
||||
# before it is submitted, whatever the Specialist intends.
|
||||
confirm_first=confirm_drafts
|
||||
@@ -913,6 +937,9 @@ def _specialist_input(
|
||||
# Whether this Execution opted into published Terraform modules.
|
||||
"terraform_modules": bool(state.get("terraform_modules")),
|
||||
"scope_skill": (state.get("scope") or {}).get("skill"),
|
||||
# The spec as supplied, for the scope analyst to complete; with the Customer
|
||||
# case the Execution belongs to, which is not the customer's to restate.
|
||||
"scope_working": _scope_seed(state) if kind is DeliverableKind.SCOPE else None,
|
||||
"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.
|
||||
@@ -944,7 +971,8 @@ def _specialist_input(
|
||||
"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"),
|
||||
"scope": _agreed_scope(deliverables)
|
||||
or (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")),
|
||||
@@ -1008,6 +1036,32 @@ def _requirement_changes(
|
||||
)
|
||||
|
||||
|
||||
def _scope_seed(state: ExecutionState) -> dict[str, Any]:
|
||||
"""The scope spec the analyst starts from: what was supplied, and the Customer
|
||||
case this Execution already belongs to."""
|
||||
seed = copy.deepcopy(
|
||||
(state.get("scope") or {}).get("working") or {"values": {}, "states": {}}
|
||||
)
|
||||
seed.setdefault("values", {}).setdefault(CASE_FIELD, _case(state))
|
||||
return seed
|
||||
|
||||
|
||||
def _agreed_scope(
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
) -> dict[str, Any] | None:
|
||||
"""The scope every later Specialist reads: the scope Deliverable's data file."""
|
||||
text = (
|
||||
(deliverables.get(DeliverableKind.SCOPE.value) or {})
|
||||
.get("attachments", {})
|
||||
.get(SCOPE_DATA_FILE, "")
|
||||
)
|
||||
try:
|
||||
data = json.loads(text) if text else None
|
||||
except ValueError:
|
||||
return None
|
||||
return data if isinstance(data, dict) else None
|
||||
|
||||
|
||||
async def _reading_hints(
|
||||
state: ExecutionState,
|
||||
ledger: Ledger,
|
||||
@@ -1244,6 +1298,22 @@ def _case(state: ExecutionState) -> str:
|
||||
return state.get("customer_case") or UNASSIGNED_CASE
|
||||
|
||||
|
||||
def _scope_with_status(text: str, status: str) -> tuple[str, dict[str, Any] | None]:
|
||||
"""A completed scope spec with its status set, and what the Execution's record
|
||||
says of it. Unchanged, with no record, when it cannot be read."""
|
||||
try:
|
||||
document = yaml.safe_load(text)
|
||||
except yaml.YAMLError:
|
||||
return text, None
|
||||
if not isinstance(document, dict):
|
||||
return text, None
|
||||
document.setdefault("metadata", {})["status"] = status
|
||||
return (
|
||||
yaml.safe_dump(document, sort_keys=False, allow_unicode=True),
|
||||
{"status": status, "readiness": document.get("readiness")},
|
||||
)
|
||||
|
||||
|
||||
def _written_before(out_dir: Path) -> set[str]:
|
||||
"""The files an earlier write of this Execution's folder recorded."""
|
||||
try:
|
||||
@@ -1343,6 +1413,22 @@ def _write_outputs(
|
||||
indent=2,
|
||||
ensure_ascii=False,
|
||||
)
|
||||
scope_record: dict[str, Any] | None = None
|
||||
if SCOPE_FILE in files:
|
||||
# The completed scope spec says where it stands, here and beside the Intent.
|
||||
approved = ledger.phase_status(PhaseId.SCOPING) is PhaseStatus.APPROVED
|
||||
files[SCOPE_FILE], scope_record = _scope_with_status(
|
||||
files[SCOPE_FILE],
|
||||
LOCKED if status == "completed" else APPROVED if approved else UNDER_REVIEW,
|
||||
)
|
||||
version = state.get("intent_version")
|
||||
if version:
|
||||
copy_path = (
|
||||
intent_dir(output_root, customer_case)
|
||||
/ f"{int(version):03d}{SCOPE_COMPLETED}"
|
||||
)
|
||||
copy_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
copy_path.write_text(files[SCOPE_FILE], encoding="utf-8")
|
||||
# The folder is written more than once as an Execution goes. A file an earlier
|
||||
# write left that this one does not have, such as a Terraform file removed in a
|
||||
# Revision, must not stay beside the files that replaced it.
|
||||
@@ -1365,12 +1451,8 @@ 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,
|
||||
# Where the agreed scope stands and how much of it the customer stated.
|
||||
"scope": scope_record,
|
||||
"status": status,
|
||||
"warnings": list(state.get("warnings", [])),
|
||||
# Flags a person should look at; nothing was done about them.
|
||||
|
||||
@@ -14,6 +14,7 @@ tools, so the Ledger refuses anything that is not allowed, whatever was decided.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
||||
@@ -37,6 +38,7 @@ from app.workflows.chain import (
|
||||
IMPLEMENTATION_FILE,
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
SCOPE_DATA_FILE,
|
||||
VERDICTS_FILE,
|
||||
read_graph,
|
||||
read_list,
|
||||
@@ -741,6 +743,24 @@ def approval_facts(phase: PhaseId, view: TurnView, r: Readings) -> dict[str, Any
|
||||
),
|
||||
}
|
||||
facts["counts"] = {name: count for name, count in counts.items() if count}
|
||||
scope = (view.deliverables.get(DeliverableKind.SCOPE.value) or {}).get(
|
||||
"attachments", {}
|
||||
)
|
||||
if phase is PhaseId.SCOPING and scope.get(SCOPE_DATA_FILE):
|
||||
# What approving the scope commits to: how much the customer stated, how
|
||||
# much was assumed for them, and what is still unknown.
|
||||
try:
|
||||
agreed = json.loads(scope[SCOPE_DATA_FILE])
|
||||
except ValueError:
|
||||
agreed = {}
|
||||
facts["scope"] = {
|
||||
"kind": agreed.get("kind"),
|
||||
"assumed": [item.get("field") for item in agreed.get("assumed", [])],
|
||||
"left_to_decide": [
|
||||
item.get("field") for item in agreed.get("to_decide", [])
|
||||
],
|
||||
"unknown": [item.get("field") for item in agreed.get("to_ask", [])],
|
||||
}
|
||||
graph = read_graph(view.deliverables)
|
||||
if graph is not None:
|
||||
facts["target_architecture"] = graph.summary()
|
||||
@@ -776,6 +796,14 @@ def assembled_summary(phase: PhaseId, facts: Mapping[str, Any]) -> str:
|
||||
lines.append(
|
||||
", ".join(f"{count} {name}" for name, count in counts.items()) + "."
|
||||
)
|
||||
scope = facts.get("scope")
|
||||
if scope:
|
||||
lines.append(
|
||||
f"Scope of a {scope.get('kind') or 'workload'}: "
|
||||
f"{len(scope['assumed'])} fields assumed, "
|
||||
f"{len(scope['unknown'])} still unknown. Requirements are derived "
|
||||
"from it once you approve."
|
||||
)
|
||||
graph = facts.get("target_architecture")
|
||||
if graph:
|
||||
lines.append(
|
||||
|
||||
48
app/scope.py
48
app/scope.py
@@ -33,6 +33,10 @@ import yaml
|
||||
ASK, DECIDE, NOT_APPLICABLE = "ask", "decide", "not_applicable"
|
||||
MARKERS = (ASK, DECIDE, NOT_APPLICABLE)
|
||||
SUPPLIED, ASSUMED, UNKNOWN = "supplied", "assumed", "unknown"
|
||||
# Where a settled value came from: the spec file, the customer's request in prose,
|
||||
# an answer they gave in conversation, or the agent's own choice.
|
||||
REQUEST, ANSWERED = "request", "answered"
|
||||
SOURCES = (SUPPLIED, REQUEST, ANSWERED, ASSUMED)
|
||||
ESSENTIAL, IMPORTANT, OPTIONAL = "essential", "important", "optional"
|
||||
_SEVERITY = {ESSENTIAL: "HIGH", IMPORTANT: "MEDIUM", OPTIONAL: "LOW"}
|
||||
DRAFT, UNDER_REVIEW, APPROVED, LOCKED = (
|
||||
@@ -131,6 +135,13 @@ class Scope:
|
||||
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:
|
||||
@@ -163,16 +174,25 @@ class Scope:
|
||||
"""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:
|
||||
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": f"The customer left {path} to the agent. "
|
||||
f"Default: {spec.default if spec.default is not None else 'the agent chooses'}.",
|
||||
"statement": statement,
|
||||
"impact_if_invalid": f"Changes {spec.affects}."
|
||||
if spec.affects
|
||||
else "Local to this field.",
|
||||
@@ -182,9 +202,11 @@ class Scope:
|
||||
|
||||
def readiness(self) -> dict[str, int]:
|
||||
states = list(self.states.values())
|
||||
came = [self.source(path) for path in self.values]
|
||||
return {
|
||||
SUPPLIED: len(self.values),
|
||||
ASSUMED: states.count(DECIDE),
|
||||
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),
|
||||
}
|
||||
@@ -204,7 +226,7 @@ class Scope:
|
||||
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: 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()
|
||||
@@ -220,11 +242,19 @@ class Scope:
|
||||
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)
|
||||
if path.startswith(("run.", "metadata.")) or self.source(path) == ASSUMED:
|
||||
continue
|
||||
_put(stated, path, value)
|
||||
return {
|
||||
"kind": self.kind,
|
||||
"stated": stated,
|
||||
# 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,
|
||||
|
||||
@@ -22,6 +22,14 @@ from app.adk.runtime import (
|
||||
)
|
||||
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
|
||||
from app.tools.pillars import REVIEW_HEADING, render_checklist_review
|
||||
from app.tools.scoping import (
|
||||
REGISTER_HEADING,
|
||||
Scoping,
|
||||
render_register,
|
||||
scope_tools,
|
||||
unsettled,
|
||||
)
|
||||
from app.tools.scoping import attachments as scope_attachments
|
||||
from app.tools.workspace import (
|
||||
FILES,
|
||||
basis_of,
|
||||
@@ -284,6 +292,7 @@ def specialist_tools(
|
||||
review: Callable[[Mapping[str, str]], Awaitable[Sequence[str]]] | None = None,
|
||||
confirm_first: bool = False,
|
||||
baseline: Mapping[str, Any] | None = None,
|
||||
scoping: Scoping | None = None,
|
||||
) -> list[ToolSpec]:
|
||||
"""A Specialist's tools: submit, ask, its working copy, and its role's tools with
|
||||
the cloud-read gate.
|
||||
@@ -298,6 +307,8 @@ def specialist_tools(
|
||||
this Deliverable: a submission is then refused until the Specialist has put its
|
||||
draft to them. A rule, because an instruction alone was not always followed.
|
||||
`baseline` is the Baseline's version of this Deliverable in a Change request.
|
||||
`scoping` is the scope spec's catalogue; with it the scope Deliverable's two
|
||||
files and its information register are written from what was recorded.
|
||||
"""
|
||||
working = {} if working is None else working
|
||||
is_graph = kind is DeliverableKind.TARGET_ARCHITECTURE
|
||||
@@ -310,12 +321,30 @@ def specialist_tools(
|
||||
if is_validation:
|
||||
working_verdicts(working, basis) # drops verdicts given on other code
|
||||
graph_now = read_graph(upstream)
|
||||
is_scope = kind is DeliverableKind.SCOPE and scoping is not None
|
||||
|
||||
async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult:
|
||||
try:
|
||||
attachments = files_from_argument(attachments)
|
||||
except TypeError as exc:
|
||||
return _refused(f"attachments: {exc}")
|
||||
if is_scope and scoping is not None:
|
||||
# Nothing essential may be left unknown, and the files are written
|
||||
# from what was recorded: they cannot disagree with it.
|
||||
missing_fields = unsettled(working, scoping)
|
||||
if missing_fields:
|
||||
return ToolResult(
|
||||
"Not submitted. Essential fields of the scope spec are not "
|
||||
"settled: " + ", ".join(missing_fields) + ". Ask the user for "
|
||||
"each with `needs_input`; when you may not ask, choose a value "
|
||||
"and record it with `source` assumed and a note."
|
||||
)
|
||||
attachments = scope_attachments(working, scoping)
|
||||
content = (
|
||||
content.split(f"\n## {REGISTER_HEADING}")[0].rstrip()
|
||||
+ "\n\n"
|
||||
+ render_register(working, scoping)
|
||||
)
|
||||
# The working copy is the submission; a file passed here replaces its copy.
|
||||
if own_files:
|
||||
attachments = {**working_files(working), **attachments}
|
||||
@@ -455,6 +484,7 @@ def specialist_tools(
|
||||
if library
|
||||
else ()
|
||||
),
|
||||
*(scope_tools(working, scoping) if is_scope and scoping else ()),
|
||||
*(graph_tools(working) if is_graph else ()),
|
||||
*(
|
||||
verdict_tools(working, basis, graph_now.check_ids if graph_now else ())
|
||||
|
||||
322
app/tools/scoping.py
Normal file
322
app/tools/scoping.py
Normal file
@@ -0,0 +1,322 @@
|
||||
"""The scope analyst's tools: completing the scope spec (ADR-0008).
|
||||
|
||||
The spec is kept in the scope Deliverable's working memory as plain data, seeded
|
||||
from what the customer supplied. The analyst reads what is settled and what is
|
||||
not, and records each value it settles with where the value came from. Code checks
|
||||
every value against the catalogue as it is recorded, and writes the completed copy
|
||||
and the information register from what is there when the Deliverable is submitted:
|
||||
the spec the customer approves cannot disagree with what was recorded.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, MutableMapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.adk.runtime import ToolResult, ToolSpec
|
||||
from app.scope import (
|
||||
ANSWERED,
|
||||
ASK,
|
||||
ASSUMED,
|
||||
DECIDE,
|
||||
ESSENTIAL,
|
||||
IMPORTANT,
|
||||
MARKERS,
|
||||
NOT_APPLICABLE,
|
||||
REQUEST,
|
||||
SOURCES,
|
||||
SUPPLIED,
|
||||
UNDER_REVIEW,
|
||||
Catalogue,
|
||||
Scope,
|
||||
ScopeError,
|
||||
_fault,
|
||||
_plain,
|
||||
read_scope,
|
||||
)
|
||||
from app.workflows.chain import SCOPE_DATA_FILE, SCOPE_FILE
|
||||
|
||||
SCOPE_KEY = "scope_spec" # working memory: the spec as it is being completed
|
||||
REGISTER_HEADING = "Information register"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Scoping:
|
||||
"""What reading and completing a scope spec needs."""
|
||||
|
||||
catalogue: Catalogue
|
||||
provider_values: Mapping[str, Sequence[str]] = field(default_factory=dict)
|
||||
skill: str | None = None
|
||||
|
||||
|
||||
def to_working(scope: Scope) -> dict[str, Any]:
|
||||
"""A spec as working memory: plain data that survives a checkpoint."""
|
||||
return {
|
||||
"kind": scope.kind,
|
||||
"values": dict(scope.values),
|
||||
"states": dict(scope.states),
|
||||
"sources": dict(scope.sources),
|
||||
"notes": dict(scope.notes),
|
||||
}
|
||||
|
||||
|
||||
def from_working(memory: Mapping[str, Any], catalogue: Catalogue) -> Scope:
|
||||
values = dict(memory.get("values") or {})
|
||||
states = {
|
||||
path: (memory.get("states") or {}).get(path, ASK)
|
||||
for path in catalogue.fields
|
||||
if path not in values
|
||||
}
|
||||
kind = values.get("engagement.kind")
|
||||
return Scope(
|
||||
catalogue,
|
||||
str(kind) if kind in catalogue.kinds else None,
|
||||
values=values,
|
||||
states=states,
|
||||
sources=dict(memory.get("sources") or {}),
|
||||
notes=dict(memory.get("notes") or {}),
|
||||
)
|
||||
|
||||
|
||||
def working_from_completed(text: str, scoping: Scoping) -> dict[str, Any] | None:
|
||||
"""A completed scope spec as working memory, with where each value came from.
|
||||
None when it cannot be read: a Change request then drafts the scope afresh."""
|
||||
try:
|
||||
scope = read_scope(
|
||||
text, scoping.catalogue, provider_values=scoping.provider_values
|
||||
)
|
||||
document = yaml.safe_load(text) or {}
|
||||
except (ScopeError, yaml.YAMLError):
|
||||
return None
|
||||
recorded = document.get("provenance") if isinstance(document, Mapping) else None
|
||||
scope.sources = {
|
||||
path: str(source)
|
||||
for path, source in (recorded or {}).items()
|
||||
if path in scope.values and source in SOURCES
|
||||
}
|
||||
return to_working(scope)
|
||||
|
||||
|
||||
def working_scope(working: MutableMapping[str, Any]) -> dict[str, Any]:
|
||||
return working.setdefault(SCOPE_KEY, {"values": {}, "states": {}})
|
||||
|
||||
|
||||
def unsettled(working: Mapping[str, Any], scoping: Scoping) -> list[str]:
|
||||
"""The essential fields a submission may not leave unknown."""
|
||||
scope = from_working(working.get(SCOPE_KEY) or {}, scoping.catalogue)
|
||||
return [gap["field"] for gap in scope.gaps(ESSENTIAL)]
|
||||
|
||||
|
||||
def attachments(working: Mapping[str, Any], scoping: Scoping) -> dict[str, str]:
|
||||
"""The Deliverable's two files, written from what was recorded."""
|
||||
scope = from_working(working.get(SCOPE_KEY) or {}, scoping.catalogue)
|
||||
return {
|
||||
SCOPE_FILE: yaml.safe_dump(
|
||||
scope.completed(UNDER_REVIEW), sort_keys=False, allow_unicode=True
|
||||
),
|
||||
SCOPE_DATA_FILE: json.dumps(scope.for_context(), indent=2, ensure_ascii=False),
|
||||
}
|
||||
|
||||
|
||||
_FROM = {
|
||||
SUPPLIED: "the scope spec",
|
||||
REQUEST: "the request",
|
||||
ANSWERED: "the customer's answer",
|
||||
ASSUMED: "assumed",
|
||||
}
|
||||
|
||||
|
||||
def render_register(working: Mapping[str, Any], scoping: Scoping) -> str:
|
||||
"""The information register, readiness and open questions, as markdown written
|
||||
by code from what was recorded."""
|
||||
scope = from_working(working.get(SCOPE_KEY) or {}, scoping.catalogue)
|
||||
counts = scope.readiness()
|
||||
lines = [
|
||||
f"## {REGISTER_HEADING}",
|
||||
"",
|
||||
(
|
||||
f"{counts[SUPPLIED]} stated by the customer, {counts[ANSWERED]} answered "
|
||||
f"in conversation, {counts[ASSUMED]} assumed, {counts['unknown']} "
|
||||
f"unknown, {counts[NOT_APPLICABLE]} not applicable."
|
||||
),
|
||||
"",
|
||||
"| Field | Value | From |",
|
||||
"| --- | --- | --- |",
|
||||
]
|
||||
for path, value in scope.values.items():
|
||||
if path.startswith(("run.", "metadata.")):
|
||||
continue
|
||||
shown = (
|
||||
json.dumps(value, ensure_ascii=False)
|
||||
if isinstance(value, (list, dict))
|
||||
else str(value)
|
||||
)
|
||||
shown = " ".join(shown.split()).replace("|", "\\|")
|
||||
lines.append(f"| {path} | {shown[:200]} | {_FROM[scope.source(path)]} |")
|
||||
assumed = scope.assumptions()
|
||||
if assumed:
|
||||
lines += [
|
||||
"",
|
||||
"### Assumptions",
|
||||
"",
|
||||
"| Id | Assumption | If it is wrong |",
|
||||
"| --- | --- | --- |",
|
||||
]
|
||||
lines += [
|
||||
f"| {item['id']} | {item['statement']} | {item['impact_if_invalid']} |"
|
||||
for item in assumed
|
||||
]
|
||||
gaps = scope.gaps(ESSENTIAL, IMPORTANT)
|
||||
if gaps:
|
||||
lines += [
|
||||
"",
|
||||
"### Still to confirm with the customer",
|
||||
"",
|
||||
"| Field | Question | Severity |",
|
||||
"| --- | --- | --- |",
|
||||
]
|
||||
lines += [
|
||||
f"| {gap['field']} | {gap['prompt']} | {gap['severity']} |" for gap in gaps
|
||||
]
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
def scope_tools(working: MutableMapping[str, Any], scoping: Scoping) -> list[ToolSpec]:
|
||||
catalogue = scoping.catalogue
|
||||
|
||||
async def scope_read() -> ToolResult:
|
||||
scope = from_working(working_scope(working), catalogue)
|
||||
counts = scope.readiness()
|
||||
lines = [
|
||||
f"Kind of engagement: {scope.kind or 'not settled'}",
|
||||
(
|
||||
f"{counts[SUPPLIED]} stated, {counts[ANSWERED]} answered, "
|
||||
f"{counts[ASSUMED]} assumed, {counts['unknown']} unknown."
|
||||
),
|
||||
]
|
||||
for severity, title in (("HIGH", "Essential"), ("MEDIUM", "Important")):
|
||||
gaps = [gap for gap in scope.gaps() if gap["severity"] == severity]
|
||||
if gaps:
|
||||
lines.append(f"{title}, not settled:")
|
||||
lines += [f" {gap['field']}: {gap['prompt']}" for gap in gaps]
|
||||
left = [
|
||||
path
|
||||
for path, state in scope.states.items()
|
||||
if state == DECIDE and not path.startswith("run.")
|
||||
]
|
||||
if left:
|
||||
lines.append("Left to you to decide: " + ", ".join(left))
|
||||
lines.append("Settled: " + (", ".join(scope.values) or "nothing yet"))
|
||||
return ToolResult("\n".join(lines))
|
||||
|
||||
async def scope_set(entries: Any = None) -> ToolResult:
|
||||
if not isinstance(entries, list) or not entries:
|
||||
return ToolResult("Refused: `entries` is a list of fields to record.")
|
||||
memory = working_scope(working)
|
||||
values, states = (
|
||||
memory.setdefault("values", {}),
|
||||
memory.setdefault("states", {}),
|
||||
)
|
||||
sources, notes = (
|
||||
memory.setdefault("sources", {}),
|
||||
memory.setdefault("notes", {}),
|
||||
)
|
||||
problems, done = [], []
|
||||
for entry in entries:
|
||||
if not isinstance(entry, Mapping):
|
||||
problems.append("each entry needs a field")
|
||||
continue
|
||||
path = str(entry.get("field", ""))
|
||||
spec = catalogue.fields.get(path)
|
||||
if spec is None:
|
||||
problems.append(f"{path} is not a field of the scope spec")
|
||||
continue
|
||||
source, value = str(entry.get("source", "")), entry.get("value")
|
||||
note = " ".join(str(entry.get("note") or "").split())
|
||||
if value in MARKERS:
|
||||
if path in values and sources.get(path, SUPPLIED) == SUPPLIED:
|
||||
problems.append(f"{path} was stated in the scope spec; it stays")
|
||||
continue
|
||||
values.pop(path, None)
|
||||
states[path] = value
|
||||
done.append(path)
|
||||
continue
|
||||
if source not in SOURCES or source == SUPPLIED:
|
||||
problems.append(
|
||||
f"{path}: `source` is request (the customer's request says it), "
|
||||
"answered (they told you) or assumed (you chose)"
|
||||
)
|
||||
continue
|
||||
if (
|
||||
path in values
|
||||
and sources.get(path, SUPPLIED) == SUPPLIED
|
||||
and source != ANSWERED
|
||||
):
|
||||
problems.append(
|
||||
f"{path} was stated in the scope spec; only the customer's own "
|
||||
"answer changes it"
|
||||
)
|
||||
continue
|
||||
if source == ASSUMED and not note:
|
||||
problems.append(f"{path}: an assumption needs a note saying why")
|
||||
continue
|
||||
fault = _fault(spec, value, scoping.provider_values.get(path, ()))
|
||||
if fault:
|
||||
problems.append(f"{path}: {fault}")
|
||||
continue
|
||||
values[path] = _plain(value)
|
||||
states.pop(path, None)
|
||||
sources[path] = source
|
||||
if note:
|
||||
notes[path] = note
|
||||
done.append(path)
|
||||
message = f"Recorded {len(done)}: {', '.join(done) or 'none'}."
|
||||
if problems:
|
||||
message += " Not recorded: " + "; ".join(problems) + "."
|
||||
return ToolResult(message)
|
||||
|
||||
return [
|
||||
ToolSpec(
|
||||
"scope_read",
|
||||
"What the scope spec settles so far, and what is not settled, with the "
|
||||
"question to ask for each.",
|
||||
{"type": "object", "properties": {}, "required": []},
|
||||
scope_read,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"scope_set",
|
||||
"Record fields of the scope spec. Each entry has `field`, `value`, "
|
||||
"`source` (request, answered or assumed) and, for an assumption, a "
|
||||
"`note` saying why. A `value` of ask, decide or not_applicable marks the "
|
||||
"field instead. Record several fields in one call.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"entries": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"field": {"type": "string"},
|
||||
"value": {},
|
||||
"source": {
|
||||
"type": "string",
|
||||
"enum": [REQUEST, ANSWERED, ASSUMED],
|
||||
},
|
||||
"note": {"type": "string"},
|
||||
},
|
||||
"required": ["field", "value"],
|
||||
},
|
||||
}
|
||||
},
|
||||
"required": ["entries"],
|
||||
},
|
||||
scope_set,
|
||||
tier="execution",
|
||||
),
|
||||
]
|
||||
@@ -33,6 +33,8 @@ PRODUCTS_FILE = "products.json"
|
||||
RECOMMENDATIONS_FILE = "recommendations.json"
|
||||
IMPLEMENTATION_FILE = "implementation.json"
|
||||
VERDICTS_FILE = "verdicts.json"
|
||||
SCOPE_FILE = "scope.yaml" # the completed scope spec
|
||||
SCOPE_DATA_FILE = "scope.json" # what every Specialist reads of it
|
||||
|
||||
REQUIREMENT_KINDS = ("functional", "non_functional")
|
||||
VERDICTS = ("pass", "fail", "not_verifiable")
|
||||
@@ -343,6 +345,19 @@ def _split_implementation(text: str, name: str) -> tuple[str, str]:
|
||||
return json.dumps(met), json.dumps(cannot)
|
||||
|
||||
|
||||
def check_scope(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
|
||||
"""The scope a Specialist reads: what the customer stated, what was left to the
|
||||
agent, and what is unknown."""
|
||||
name = SCOPE_DATA_FILE
|
||||
try:
|
||||
data = json.loads(attachments[name])
|
||||
except ValueError as exc:
|
||||
return [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, dict) or not isinstance(data.get("stated"), dict):
|
||||
return [f"{name}: must be an object with what the customer stated"]
|
||||
return []
|
||||
|
||||
|
||||
def check_implementation(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
|
||||
@@ -19,6 +19,8 @@ from app.workflows.chain import (
|
||||
PRODUCTS_FILE,
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
SCOPE_DATA_FILE,
|
||||
SCOPE_FILE,
|
||||
VERDICTS_FILE,
|
||||
Upstream,
|
||||
check_components,
|
||||
@@ -26,6 +28,7 @@ from app.workflows.chain import (
|
||||
check_products,
|
||||
check_recommendations,
|
||||
check_requirements,
|
||||
check_scope,
|
||||
check_target_architecture,
|
||||
check_verdicts,
|
||||
graph_structure,
|
||||
@@ -35,6 +38,9 @@ from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
||||
|
||||
|
||||
class PhaseId(StrEnum):
|
||||
# Scoping: what the customer wants and the facts a design depends on, agreed
|
||||
# before requirements are derived from it (ADR-0008).
|
||||
SCOPING = "scoping"
|
||||
REQUIREMENTS_DISCOVERY = "requirements_discovery"
|
||||
# Design: ends with the Target architecture, approved before any code is written.
|
||||
SOLUTION_ARCHITECTURE = "solution_architecture"
|
||||
@@ -47,6 +53,7 @@ PHASE_ORDER: tuple[PhaseId, ...] = tuple(PhaseId)
|
||||
|
||||
|
||||
class DeliverableKind(StrEnum):
|
||||
SCOPE = "scope"
|
||||
REQUIREMENTS = "requirements"
|
||||
TECHNICAL_DECOMPOSITION = "technical_decomposition"
|
||||
PRODUCT_SELECTION = "product_selection"
|
||||
@@ -92,10 +99,20 @@ _K = DeliverableKind
|
||||
DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
spec.kind: spec
|
||||
for spec in (
|
||||
DeliverableSpec(
|
||||
_K.SCOPE,
|
||||
PhaseId.SCOPING,
|
||||
"scope-analyst",
|
||||
sections=("Scope statement",),
|
||||
# The completed scope spec, for people and for reuse; and what every
|
||||
# later Specialist reads of it.
|
||||
attachments=(SCOPE_FILE, SCOPE_DATA_FILE),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.REQUIREMENTS,
|
||||
PhaseId.REQUIREMENTS_DISCOVERY,
|
||||
"requirements-analyst",
|
||||
depends_on=(_K.SCOPE,),
|
||||
sections=(
|
||||
"Functional requirements",
|
||||
"Non-functional requirements",
|
||||
@@ -209,6 +226,7 @@ DATA_CHECKS: Mapping[
|
||||
DeliverableKind,
|
||||
tuple[str, Callable[[Mapping[str, str], Upstream | None], list[str]]],
|
||||
] = {
|
||||
_K.SCOPE: (SCOPE_DATA_FILE, check_scope),
|
||||
_K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements),
|
||||
_K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components),
|
||||
_K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products),
|
||||
|
||||
@@ -30,6 +30,7 @@ from app.nodes.execution_nodes import make_execution_nodes
|
||||
from app.nodes.router import OrchestratorPolicy
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import ExecutionState
|
||||
from app.tools.scoping import Scoping
|
||||
|
||||
|
||||
def build_execution_graph(
|
||||
@@ -53,6 +54,7 @@ def build_execution_graph(
|
||||
skill_references: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None,
|
||||
skill_threshold: float = 1.25,
|
||||
assess_at_end: bool = False,
|
||||
scoping: Scoping | None = None,
|
||||
) -> StateGraph:
|
||||
nodes = make_execution_nodes(
|
||||
runtime=runtime,
|
||||
@@ -74,6 +76,7 @@ def build_execution_graph(
|
||||
skill_references=skill_references,
|
||||
skill_threshold=skill_threshold,
|
||||
assess_at_end=assess_at_end,
|
||||
scoping=scoping,
|
||||
)
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
|
||||
Reference in New Issue
Block a user