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

80
tests/scoped.py Normal file
View File

@@ -0,0 +1,80 @@
"""Helpers for tests about what comes after scoping.
Every Execution now begins with the scoping Phase (ADR-0008). A test about
requirements, design or validation is not about that, so these run scoping ahead
of the test's own script and leave the test where it always started: requirements
ready, nothing recorded of how the scope was agreed.
"""
from __future__ import annotations
from typing import Any
from app.adk.fake_runtime import FakeAgentRuntime, sample_submission
from app.adk.runtime import Submitted
from app.agent import ExecutionEngine, Interaction
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind, PhaseId
SCOPE_ANALYST = DEPENDENCY_GRAPH[DeliverableKind.SCOPE].specialist
ORCHESTRATOR = "orchestrator"
class ScopedRuntime(FakeAgentRuntime):
"""A scripted runtime that first has the scope produced and its Approval asked
for, outside the script and outside `runs`."""
def __init__(self, turns: Any) -> None:
super().__init__(turns)
self._next = "delegate"
async def run(self, role, task, tools): # type: ignore[no-untyped-def]
by_name = {tool.name: tool for tool in tools}
if role.name == SCOPE_ANALYST and not self.remaining(SCOPE_ANALYST):
# Submitted as it stands: a test about a later Deliverable's draft is
# not asking whether the scope's draft was shown first.
call = sample_submission(DeliverableKind.SCOPE)
return Submitted(call.args["content"], call.args["attachments"])
if role.name == ORCHESTRATOR and self._next == "delegate":
self._next = "approve"
asked = await by_name["delegate"].handler(
kinds=[DeliverableKind.SCOPE.value]
)
return asked.outcome
if role.name == ORCHESTRATOR and self._next == "approve":
self._next = "done"
asked = await by_name["request_approval"].handler(
phase=PhaseId.SCOPING.value, summary="The scope is ready."
)
if asked.outcome is not None:
return asked.outcome # a user is present: their Approval is awaited
return await super().run(role, task, tools)
class ScopedEngine(ExecutionEngine):
"""An engine whose `start` grants the scoping Approval when it is asked for, so
an interactive test meets the first prompt it was written about."""
async def start(self, *args: Any, **kwargs: Any) -> Interaction:
interaction = await super().start(*args, **kwargs)
approval = (interaction.prompt or {}).get("approval") or {}
if approval.get("phase") == PhaseId.SCOPING.value:
interaction = await self.resume(
interaction.execution_id,
{"approval": {"phase": PhaseId.SCOPING.value, "decision": "approve"}},
)
return interaction
def scoped_ledger(**options: Any): # type: ignore[no-untyped-def]
"""A Ledger whose scope is agreed: where requirements discovery begins."""
from app.states.ledger import Ledger, PhaseStatus
ledger = Ledger(**options)
attempt = ledger.start([DeliverableKind.SCOPE], actor=ORCHESTRATOR)
ledger.submit(
DeliverableKind.SCOPE, attempt[DeliverableKind.SCOPE], actor=SCOPE_ANALYST
)
ledger.request_approval(PhaseId.SCOPING, actor=ORCHESTRATOR)
if ledger.phase_status(PhaseId.SCOPING) is PhaseStatus.AWAITING_APPROVAL:
ledger.approve(PhaseId.SCOPING, actor="user")
return ledger