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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user