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

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