feat: scoping is the first Phase, completed in conversation (iteration 9 step 2)
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:
2026-10-11 18:17:32 +01:00
parent afe78640f8
commit 545097530b
38 changed files with 1054 additions and 123 deletions

View File

@@ -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."},

View File

@@ -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,

View File

@@ -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.

View File

@@ -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(

View File

@@ -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,

View File

@@ -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
View 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",
),
]

View File

@@ -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]:

View File

@@ -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),

View File

@@ -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)