feat: Change requests against a Baseline (ADR-0006)
A caller restates a request to say how requirements have changed, naming a completed Execution of the same Customer case as the Baseline. - app/baseline.py reads a Baseline from its files and refuses one that does not exist, did not complete or belongs to another case, before anything runs or is recorded. A Baseline is never modified. - Requirements carry a change (unchanged, added, changed, removed) and a reason. Submission is refused when a Baseline requirement disappears, an id is reused, or an unchanged requirement's text differs. A removed requirement stays on record and asks nothing downstream. - Each Specialist starts from its delivered version; the graph and the code are its working copy, and the description is carried over when the design's shape is the same. - app/workflows/changes.py compares versions by id and traces what each changed requirement reaches; anything else that changed is listed as unrequested. Approvals show the change for their Phase, and changes.json is written with the full Deliverables. - Intake no longer starts a message read as a change: it names the Execution to give as the Baseline. - A fifth evaluation case runs a request and then a change to it, with four checks that the change is recorded, reaches Checks, stays contained and costs less than its Baseline. Tested with scripted agents only; no Change request has run with real models. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -5,8 +5,10 @@ Execution's prompt. Approvals and permissions count only as structured data part
|
||||
never as free text.
|
||||
|
||||
Before a new task starts anything its message is read (app/nodes/intake.py): a
|
||||
question is answered and starts nothing, and a change to delivered work is started
|
||||
as a new request with a note saying so, until Change requests are built.
|
||||
question is answered and starts nothing. A message that reads as a change to
|
||||
delivered work also starts nothing: the caller is told which Execution it would
|
||||
change and how to name it as the Baseline, because a Change request never starts
|
||||
from earlier work on a guess (ADR-0006).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -29,7 +31,7 @@ from google.protobuf import json_format
|
||||
|
||||
from app.agent import ExecutionEngine, Interaction
|
||||
from app.nodes.execution_nodes import GUIDE_FILENAME
|
||||
from app.nodes.intake import ABOUT, CHANGE_NOTE, CHANGE_REQUEST, QUESTION, Intake
|
||||
from app.nodes.intake import ABOUT, CHANGE_REQUEST, QUESTION, Intake, change_note
|
||||
from app.presentation import describe_prompt
|
||||
from app.workflows.deliverables import DeliverableKind
|
||||
|
||||
@@ -47,7 +49,6 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
task_id = context.task_id or ""
|
||||
updater = TaskUpdater(event_queue, task_id, context.context_id or "")
|
||||
new = context.current_task is None
|
||||
note: str | None = None
|
||||
try:
|
||||
if new:
|
||||
history = [context.message] if context.message is not None else []
|
||||
@@ -62,7 +63,12 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
await updater.start_work()
|
||||
options = _options(context)
|
||||
# A pre-approved caller is a batch job: it sends work, not questions.
|
||||
if self._intake and not options.get("pre_approved"):
|
||||
if (
|
||||
self._intake
|
||||
and not options.get("pre_approved")
|
||||
and not options.get("baseline")
|
||||
and not options.get("new_request")
|
||||
):
|
||||
reading = await self._intake.read(
|
||||
context.get_user_input(),
|
||||
options.get("customer_case"),
|
||||
@@ -80,12 +86,27 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
)
|
||||
)
|
||||
return
|
||||
if reading.kind == CHANGE_REQUEST:
|
||||
note = CHANGE_NOTE
|
||||
if reading.kind == CHANGE_REQUEST and reading.latest:
|
||||
await updater.complete(
|
||||
updater.new_agent_message(
|
||||
[
|
||||
new_text_part(change_note(reading.latest)),
|
||||
new_data_part(
|
||||
{
|
||||
"status": "answered",
|
||||
"intake": CHANGE_REQUEST,
|
||||
"baseline": reading.latest,
|
||||
}
|
||||
),
|
||||
]
|
||||
)
|
||||
)
|
||||
return
|
||||
interaction = await self._engine.start(
|
||||
context.get_user_input(),
|
||||
session_id=context.context_id,
|
||||
customer_case=options.get("customer_case"),
|
||||
baseline=options.get("baseline"),
|
||||
execution_id=task_id,
|
||||
pre_approved=bool(options.get("pre_approved", False)),
|
||||
allow_cloud_read=options.get("allow_cloud_read"),
|
||||
@@ -105,7 +126,7 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
)
|
||||
)
|
||||
return
|
||||
await self._publish(interaction, updater, note if new else None)
|
||||
await self._publish(interaction, updater)
|
||||
|
||||
async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
|
||||
# The checkpoint stays; cancelling only ends the A2A task.
|
||||
@@ -114,15 +135,12 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
)
|
||||
await updater.cancel()
|
||||
|
||||
async def _publish(
|
||||
self, interaction: Interaction, updater: TaskUpdater, note: str | None = None
|
||||
) -> None:
|
||||
async def _publish(self, interaction: Interaction, updater: TaskUpdater) -> None:
|
||||
if interaction.status == "awaiting_user" and interaction.prompt is not None:
|
||||
prompt = dict(interaction.prompt)
|
||||
await updater.requires_input(
|
||||
updater.new_agent_message(
|
||||
[
|
||||
*([new_text_part(note)] if note else []),
|
||||
new_text_part(describe_prompt(prompt)),
|
||||
new_data_part({"prompt": prompt}),
|
||||
]
|
||||
|
||||
18
app/agent.py
18
app/agent.py
@@ -32,6 +32,7 @@ from app.adk.runtime import (
|
||||
SubmissionReview,
|
||||
ToolFactory,
|
||||
)
|
||||
from app.baseline import load_baseline
|
||||
from app.checkpointing import open_checkpointer
|
||||
from app.config import Settings
|
||||
from app.customer_case import record_intent
|
||||
@@ -125,13 +126,25 @@ class ExecutionEngine:
|
||||
allow_cloud_read: bool | None = None,
|
||||
execution_id: str | None = None,
|
||||
scripted_answers: Sequence[Sequence[str]] = (),
|
||||
baseline: str | None = None,
|
||||
) -> Interaction:
|
||||
"""Start an Execution. `scripted_answers` are (regex, answer[, asker]) entries a
|
||||
pre-approved Execution uses to answer questions, for evaluation runs."""
|
||||
pre-approved Execution uses to answer questions, for evaluation runs.
|
||||
|
||||
`baseline` names a completed Execution of the same Customer case and makes
|
||||
this a Change request (ADR-0006): the request says what has changed, and the
|
||||
Execution starts from that Baseline's Deliverables. It is refused, before
|
||||
anything runs or is recorded, when the Baseline cannot be one.
|
||||
"""
|
||||
customer_case = check_customer_case(customer_case)
|
||||
execution_id = execution_id or str(uuid.uuid4())
|
||||
if await self._exists(execution_id):
|
||||
raise ValueError(f"Execution {execution_id} already exists")
|
||||
loaded = (
|
||||
load_baseline(self._output_root, customer_case, baseline)
|
||||
if baseline
|
||||
else None
|
||||
)
|
||||
if pre_approved and allow_cloud_read is None:
|
||||
allow_cloud_read = False
|
||||
session_id = session_id or str(uuid.uuid4())
|
||||
@@ -141,6 +154,7 @@ class ExecutionEngine:
|
||||
execution_id=execution_id,
|
||||
session_id=session_id,
|
||||
workflow_request=workflow_request,
|
||||
baseline=baseline or None,
|
||||
)
|
||||
initial: dict[str, Any] = {
|
||||
"execution_id": execution_id,
|
||||
@@ -148,6 +162,8 @@ class ExecutionEngine:
|
||||
"customer_case": customer_case,
|
||||
"intent_version": intent_version,
|
||||
"workflow_request": workflow_request,
|
||||
# The Baseline of a Change request, as read from its files; else None.
|
||||
"baseline": loaded,
|
||||
"pre_approved": pre_approved,
|
||||
"allow_cloud_read": allow_cloud_read,
|
||||
"ledger": Ledger(
|
||||
|
||||
95
app/baseline.py
Normal file
95
app/baseline.py
Normal file
@@ -0,0 +1,95 @@
|
||||
"""The Baseline of a Change request (ADR-0006).
|
||||
|
||||
A Change request is an Execution that starts from the Deliverables of a completed
|
||||
Execution of the same Customer case. That Execution is its Baseline. It is read from
|
||||
its files under the Customer case, through its manifest, so it does not depend on a
|
||||
checkpoint and survives a restart. It is only ever read: a Baseline is never modified.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from app.states.execution_state import UNASSIGNED_CASE, case_dir, execution_dir
|
||||
|
||||
MANIFEST_FILENAME = "execution.json"
|
||||
COMPLETED = "completed"
|
||||
_EXECUTION_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
|
||||
|
||||
|
||||
class BaselineError(ValueError):
|
||||
"""The Execution named as a Baseline cannot be one; the message says why."""
|
||||
|
||||
|
||||
def load_baseline(
|
||||
output_root: Path, customer_case: str, execution_id: str
|
||||
) -> dict[str, Any]:
|
||||
"""The Baseline as plain data: its id, its request and every Deliverable.
|
||||
|
||||
Raises BaselineError when the Execution does not exist, belongs to another
|
||||
Customer case, or did not complete.
|
||||
"""
|
||||
if not isinstance(execution_id, str) or not _EXECUTION_ID.match(execution_id):
|
||||
raise BaselineError(f"baseline {execution_id!r} is not an Execution id")
|
||||
if customer_case == UNASSIGNED_CASE:
|
||||
raise BaselineError(
|
||||
"a Change request needs a customer_case: a Baseline is a completed "
|
||||
"Execution of the same Customer case"
|
||||
)
|
||||
folder = execution_dir(output_root, execution_id, customer_case)
|
||||
manifest_path = folder / MANIFEST_FILENAME
|
||||
if not manifest_path.is_file():
|
||||
elsewhere = [
|
||||
path.parent.parent.parent.name
|
||||
for path in case_dir(output_root, "x").parent.glob(
|
||||
f"*/executions/{execution_id}/{MANIFEST_FILENAME}"
|
||||
)
|
||||
]
|
||||
if elsewhere:
|
||||
# Never say which: one case must learn nothing about another.
|
||||
raise BaselineError(
|
||||
f"baseline {execution_id} belongs to another Customer case"
|
||||
)
|
||||
raise BaselineError(
|
||||
f"baseline {execution_id} is not an Execution of Customer case "
|
||||
f"{customer_case} with files on record"
|
||||
)
|
||||
try:
|
||||
manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
|
||||
except ValueError as exc:
|
||||
raise BaselineError(f"baseline {execution_id} has no readable record") from exc
|
||||
if manifest.get("customer_case") not in (None, customer_case):
|
||||
raise BaselineError(f"baseline {execution_id} belongs to another Customer case")
|
||||
if manifest.get("status", COMPLETED) != COMPLETED:
|
||||
raise BaselineError(
|
||||
f"baseline {execution_id} did not complete ({manifest.get('status')}); "
|
||||
"a Change request starts from a completed Execution"
|
||||
)
|
||||
|
||||
deliverables: dict[str, dict[str, Any]] = {}
|
||||
for kind, entry in (manifest.get("deliverables") or {}).items():
|
||||
document = folder / str(entry.get("document", ""))
|
||||
if not document.is_file():
|
||||
raise BaselineError(f"baseline {execution_id} is missing its {kind} file")
|
||||
attachments = {}
|
||||
for name in entry.get("attachments") or ():
|
||||
path = folder / name
|
||||
if not path.is_file():
|
||||
raise BaselineError(f"baseline {execution_id} is missing {name}")
|
||||
attachments[name] = path.read_text(encoding="utf-8")
|
||||
deliverables[kind] = {
|
||||
"content": document.read_text(encoding="utf-8"),
|
||||
"attachments": attachments,
|
||||
}
|
||||
if not deliverables:
|
||||
raise BaselineError(f"baseline {execution_id} holds no Deliverables")
|
||||
return {
|
||||
"execution_id": execution_id,
|
||||
"customer_case": customer_case,
|
||||
"workflow_request": manifest.get("workflow_request", ""),
|
||||
"baseline": manifest.get("baseline"), # what it was itself changed from
|
||||
"deliverables": deliverables,
|
||||
}
|
||||
@@ -49,8 +49,13 @@ def record_intent(
|
||||
execution_id: str,
|
||||
session_id: str,
|
||||
workflow_request: str,
|
||||
baseline: str | None = None,
|
||||
) -> int:
|
||||
"""Record a new statement of the customer's intent and return its version."""
|
||||
"""Record a new statement of the customer's intent and return its version.
|
||||
|
||||
`baseline` is the Execution a Change request starts from; with it the history
|
||||
shows the case's line of versions.
|
||||
"""
|
||||
folder = intent_dir(output_root, customer_case)
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
history = read_history(output_root, customer_case)
|
||||
@@ -60,7 +65,9 @@ def record_intent(
|
||||
(folder / statement).write_text(
|
||||
f"# Intent {version}: {customer_case}\n\n"
|
||||
f"- Recorded: {recorded_at}\n"
|
||||
f"- Execution: `{execution_id}`\n\n"
|
||||
f"- Execution: `{execution_id}`\n"
|
||||
+ (f"- Changes: `{baseline}`\n" if baseline else "")
|
||||
+ "\n"
|
||||
f"## What the customer wants\n\n{workflow_request.strip()}\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
@@ -74,6 +81,7 @@ def record_intent(
|
||||
"session_id": session_id,
|
||||
"status": IN_PROGRESS,
|
||||
"execution": None,
|
||||
"baseline": baseline,
|
||||
}
|
||||
)
|
||||
_write_history(folder, history)
|
||||
|
||||
@@ -69,6 +69,7 @@ def create_app(
|
||||
workflow_request,
|
||||
session_id=body.get("session_id"),
|
||||
customer_case=body.get("customer_case"),
|
||||
baseline=body.get("baseline"),
|
||||
pre_approved=True,
|
||||
allow_cloud_read=bool(body.get("allow_cloud_read", False)),
|
||||
)
|
||||
|
||||
@@ -53,12 +53,14 @@ from app.workflows.chain import (
|
||||
unimplementable_checks,
|
||||
validation_outcome,
|
||||
)
|
||||
from app.workflows.changes import CHANGES_FILE, change_summary, is_empty
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
PHASE_ORDER,
|
||||
DeliverableKind,
|
||||
dependencies_for,
|
||||
)
|
||||
from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
@@ -260,7 +262,9 @@ def make_execution_nodes(
|
||||
)
|
||||
return finish_with("end_with_warnings", warnings=warnings)
|
||||
|
||||
toolbox = OrchestratorToolbox(ledger, deliverables, pending_questions)
|
||||
toolbox = OrchestratorToolbox(
|
||||
ledger, deliverables, pending_questions, state.get("baseline")
|
||||
)
|
||||
refusals = list(state.get("refusals", []))
|
||||
update["refusals"] = refusals
|
||||
view = TurnView(
|
||||
@@ -382,6 +386,11 @@ def make_execution_nodes(
|
||||
kind = DeliverableKind(task_input["kind"])
|
||||
working: dict[str, Any] = dict(task_input.get("working") or {})
|
||||
upstream = task_input["context"].get("dependencies") or {}
|
||||
before = task_input.get("baseline")
|
||||
if before and not working:
|
||||
# A Change request starts from the Baseline's version, not from nothing:
|
||||
# its graph, its files and its description are the working copy.
|
||||
_start_from(kind, before, working, task_input.get("baseline_basis"))
|
||||
source = DEPENDENCY_GRAPH[kind].working_copy
|
||||
if source and source is not kind:
|
||||
# The tools work on the files as they were last submitted.
|
||||
@@ -440,6 +449,7 @@ def make_execution_nodes(
|
||||
working=working,
|
||||
library=task_input.get("library"),
|
||||
review=review if submission_review else None,
|
||||
baseline=before,
|
||||
# With a user present, their first sight of a Deliverable comes
|
||||
# before it is submitted, whatever the Specialist intends.
|
||||
confirm_first=confirm_drafts
|
||||
@@ -707,6 +717,8 @@ def _specialist_input(
|
||||
) -> dict[str, Any]:
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
given = dependencies_for(kind, deliverables)
|
||||
baseline = state.get("baseline") or None
|
||||
before = (baseline or {}).get("deliverables", {}).get(kind.value)
|
||||
return {
|
||||
"execution_id": state["execution_id"],
|
||||
# The Deliverables given as data files alone, whole, for reading on demand.
|
||||
@@ -723,6 +735,12 @@ def _specialist_input(
|
||||
# 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.
|
||||
"shown": kind.value in state.get("drafts_shown", []),
|
||||
# The Baseline's version of this Deliverable, in a Change request.
|
||||
"baseline": before,
|
||||
# What the Baseline's version was written from, to tell whether it still stands.
|
||||
"baseline_basis": spec.written_from((baseline or {}).get("deliverables"))
|
||||
if baseline and spec.written_from
|
||||
else None,
|
||||
"context": {
|
||||
"workflow_request": state["workflow_request"],
|
||||
"pre_approved": bool(state.get("pre_approved")),
|
||||
@@ -736,10 +754,60 @@ def _specialist_input(
|
||||
state.get("working", {}).get(kind.value, {})
|
||||
),
|
||||
"attempt": attempt,
|
||||
# Set only in a Change request: what this Execution changes, and from what.
|
||||
"baseline": _baseline_context(kind, baseline, before, deliverables)
|
||||
if baseline
|
||||
else None,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
# The solution guide is assembled afresh from the revised Deliverables, so the
|
||||
# Baseline's guide, the longest document there is, is not handed back to its author.
|
||||
_NOT_HANDED_BACK = {DeliverableKind.SOLUTION_GUIDE}
|
||||
|
||||
|
||||
def _baseline_context(
|
||||
kind: DeliverableKind,
|
||||
baseline: Mapping[str, Any],
|
||||
before: Mapping[str, Any] | None,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
) -> dict[str, Any]:
|
||||
summary = change_summary(baseline.get("deliverables"), deliverables)
|
||||
return {
|
||||
"execution_id": baseline.get("execution_id"),
|
||||
"original_request": baseline.get("workflow_request"),
|
||||
"deliverable": dict(before)
|
||||
if before and kind not in _NOT_HANDED_BACK
|
||||
else None,
|
||||
# What has changed so far, upstream of this Deliverable.
|
||||
"changes": None if is_empty(summary) else summary,
|
||||
}
|
||||
|
||||
|
||||
def _start_from(
|
||||
kind: DeliverableKind,
|
||||
before: Mapping[str, Any],
|
||||
working: dict[str, Any],
|
||||
basis: str | None = None,
|
||||
) -> None:
|
||||
"""Make the Baseline's version of a Deliverable its working copy."""
|
||||
attachments = dict(before.get("attachments", {}))
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
if kind is DeliverableKind.TARGET_ARCHITECTURE and GRAPH_ATTACHMENT in attachments:
|
||||
workspace.keep_graph(working, attachments[GRAPH_ATTACHMENT])
|
||||
if spec.working_copy is kind:
|
||||
working[workspace.FILES] = attachments
|
||||
if basis:
|
||||
# Kept as it stands when what it was written from is the same as before.
|
||||
working[STANDING] = {
|
||||
"basis": basis,
|
||||
"feedback": [],
|
||||
"content": before.get("content", ""),
|
||||
"attachments": attachments,
|
||||
}
|
||||
|
||||
|
||||
def _outcome_record(
|
||||
role: str, kind: DeliverableKind, attempt: int, outcome: Outcome
|
||||
) -> dict[str, Any]:
|
||||
@@ -896,6 +964,15 @@ def _write_outputs(
|
||||
# submitted, or back in draft after something it depends on was reopened
|
||||
"status": ledger.status(DeliverableKind(kind)).value,
|
||||
}
|
||||
baseline = state.get("baseline") or None
|
||||
if baseline:
|
||||
# What this Change request changed against its Baseline, worked out from
|
||||
# the ids in the two versions' data files.
|
||||
files[CHANGES_FILE] = json.dumps(
|
||||
change_summary(baseline.get("deliverables"), deliverables),
|
||||
indent=2,
|
||||
ensure_ascii=False,
|
||||
)
|
||||
for name, content in files.items():
|
||||
path = out_dir / name
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
@@ -907,12 +984,15 @@ def _write_outputs(
|
||||
"session_id": state.get("session_id"),
|
||||
"intent_version": state.get("intent_version"),
|
||||
"workflow_request": state["workflow_request"],
|
||||
# The Execution this one changes, for a Change request.
|
||||
"baseline": (state.get("baseline") or {}).get("execution_id"),
|
||||
"status": status,
|
||||
"warnings": list(state.get("warnings", [])),
|
||||
"phases": {
|
||||
phase.value: ledger.phase_status(phase).value for phase in PHASE_ORDER
|
||||
},
|
||||
"solution_guide": GUIDE_FILENAME if guide else None,
|
||||
"changes": CHANGES_FILE if baseline else None,
|
||||
"deliverables": by_kind,
|
||||
}
|
||||
out_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
@@ -4,9 +4,13 @@ Inside an Execution the router reads the user's replies. This is the same readin
|
||||
one step earlier, for a message that arrives with no Execution in progress:
|
||||
|
||||
new request design this workload start an Execution
|
||||
change request change what was delivered (ADR-0006; not built yet)
|
||||
change request change what was delivered name the Baseline to change (ADR-0006)
|
||||
question what can you do, how long... answer; start nothing
|
||||
|
||||
A change is never started from earlier work on a guess: the caller chooses the
|
||||
Baseline. So a message read as a change is answered with the Execution it would
|
||||
change and how to name it, and starts nothing.
|
||||
|
||||
Without a decision, and whenever the reading is not confident, the message is taken
|
||||
as a new request: that is what every message was before, and starting work nobody
|
||||
asked for is cheaper to put right than refusing work somebody did.
|
||||
@@ -36,11 +40,18 @@ ABOUT = (
|
||||
"infrastructure code, validation and a packaged guide, asking for your approval "
|
||||
"at each Phase. Nothing was started for this message."
|
||||
)
|
||||
CHANGE_NOTE = (
|
||||
"This reads as a change to work already delivered for this Customer case. "
|
||||
"Changing an earlier architecture in place is not available yet, so this is "
|
||||
"being designed as a new request."
|
||||
)
|
||||
|
||||
|
||||
def change_note(baseline: str) -> str:
|
||||
"""What a caller is told when their message reads as a change to delivered work."""
|
||||
return (
|
||||
"This reads as a change to the architecture already delivered for this "
|
||||
f"Customer case, in Execution {baseline}. Nothing was started. To change "
|
||||
f'that architecture from where it stood, send this again with "baseline" '
|
||||
f'set to "{baseline}". To design it as new work instead, send it again '
|
||||
'with "new_request" set to true.'
|
||||
)
|
||||
|
||||
|
||||
_MESSAGE_LIMIT = 8_000
|
||||
_EARLIER_SHOWN = 5
|
||||
@@ -52,6 +63,7 @@ class IntakeReading:
|
||||
confidence: float = 0.0
|
||||
judged: bool = False # False when no decision was available
|
||||
earlier: int = 0 # finished Executions of the same Customer case
|
||||
latest: str | None = None # the most recent of them: what a change would change
|
||||
|
||||
|
||||
def finished_intents(output_root: Path, customer_case: str) -> list[Mapping[str, Any]]:
|
||||
@@ -110,7 +122,10 @@ class Intake:
|
||||
if kind == CHANGE_REQUEST and not earlier:
|
||||
kind = NEW_REQUEST # there is nothing delivered to change
|
||||
logger.info("[%s] intake: %s (%.2f)", scope, kind, confidence)
|
||||
return IntakeReading(kind, confidence, judged=True, earlier=len(earlier))
|
||||
latest = str(earlier[-1].get("execution_id")) if earlier else None
|
||||
return IntakeReading(
|
||||
kind, confidence, judged=True, earlier=len(earlier), latest=latest
|
||||
)
|
||||
|
||||
|
||||
def _state(message: str, earlier: Sequence[Mapping[str, Any]]) -> str:
|
||||
|
||||
@@ -27,6 +27,7 @@ def describe_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
return (
|
||||
f"Please review the {approval['phase']} Phase: {approval['summary']}\n\n"
|
||||
f"Deliverables: {', '.join(approval['deliverables'])}.\n\n"
|
||||
f"{_describe_changes(approval)}"
|
||||
f"{_describe_target_architecture(approval.get('target_architecture'))}"
|
||||
f"To approve, reply with the data {json.dumps(reply)}. "
|
||||
f"To request changes, reply with {json.dumps(changes)}. "
|
||||
@@ -47,6 +48,42 @@ def describe_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
return "\n".join(lines) + "\n\nReply in text; answer every question you can."
|
||||
|
||||
|
||||
_CHANGE_WORDS = {"added": "Added", "changed": "Changed", "removed": "Removed"}
|
||||
|
||||
|
||||
def _describe_changes(approval: Mapping[str, Any]) -> str:
|
||||
"""In a Change request: what this Phase changes against the Baseline. It comes
|
||||
from the ids in the two versions, not from an agent's account."""
|
||||
if "changes" not in approval:
|
||||
return ""
|
||||
changes = approval["changes"]
|
||||
lines = [f"This changes the architecture delivered in {approval.get('baseline')}."]
|
||||
if not changes:
|
||||
lines.append("Nothing in this Phase differs from it.")
|
||||
for item in changes.get("requirements", []):
|
||||
lines.append(
|
||||
f"- Requirement {item['id']} {item['change']}: {item['text']} "
|
||||
f"({item['reason']})"
|
||||
)
|
||||
for part in (
|
||||
"components",
|
||||
"recommendations",
|
||||
"elements",
|
||||
"relationships",
|
||||
"checks",
|
||||
):
|
||||
for change, word in _CHANGE_WORDS.items():
|
||||
ids = changes.get(part, {}).get(change)
|
||||
if ids:
|
||||
lines.append(f"- {word} {part}: {', '.join(ids)}")
|
||||
for part, ids in changes.get("unrequested", {}).items():
|
||||
lines.append(
|
||||
f"- Changed without being asked for ({part}): {', '.join(ids)}. No "
|
||||
"changed requirement reaches these."
|
||||
)
|
||||
return "\n".join(lines) + "\n\n"
|
||||
|
||||
|
||||
def _describe_target_architecture(summary: Mapping[str, Any] | None) -> str:
|
||||
"""What the design Approval commits to: no code is written until it is granted."""
|
||||
if not summary:
|
||||
|
||||
@@ -56,6 +56,7 @@ class ExecutionState(TypedDict, total=False):
|
||||
customer_case: str # the Customer case this Execution belongs to
|
||||
intent_version: int # which statement of the case's intent started this Execution
|
||||
workflow_request: str
|
||||
baseline: dict[str, Any] | None # a Change request's Baseline, read from its files
|
||||
pre_approved: bool
|
||||
allow_cloud_read: bool | None
|
||||
|
||||
|
||||
@@ -36,6 +36,7 @@ from app.tools.workspace import (
|
||||
working_verdicts,
|
||||
)
|
||||
from app.workflows.chain import VERDICTS_FILE, read_graph
|
||||
from app.workflows.changes import change_summary, changes_for
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
DeliverableKind,
|
||||
@@ -82,10 +83,13 @@ class OrchestratorToolbox:
|
||||
ledger: Ledger,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
pending_questions: Sequence[Mapping[str, Any]],
|
||||
baseline: Mapping[str, Any] | None = None,
|
||||
) -> None:
|
||||
self.ledger = ledger
|
||||
self._deliverables = deliverables
|
||||
self._pending_questions = pending_questions
|
||||
# A Change request's Baseline: with it, an Approval shows what changed.
|
||||
self._baseline = baseline
|
||||
self.started: dict[DeliverableKind, int] = {}
|
||||
self.questions: list[dict[str, str]] = []
|
||||
self.approval: dict[str, Any] | None = None
|
||||
@@ -213,6 +217,14 @@ class OrchestratorToolbox:
|
||||
"summary": summary,
|
||||
"deliverables": [kind.value for kind in deliverables_in(phase_id)],
|
||||
}
|
||||
if self._baseline:
|
||||
# Worked out from the ids, not written by an agent: what this Phase's
|
||||
# Deliverables add, change and remove against the Baseline.
|
||||
self.approval["baseline"] = self._baseline.get("execution_id")
|
||||
self.approval["changes"] = changes_for(
|
||||
change_summary(self._baseline.get("deliverables"), self._deliverables),
|
||||
self.approval["deliverables"],
|
||||
)
|
||||
graph = self._target_architecture()
|
||||
if graph and phase_id is DEPENDENCY_GRAPH[_TARGET].phase:
|
||||
# What the user is approving before any code is written.
|
||||
@@ -271,6 +283,7 @@ def specialist_tools(
|
||||
library: Mapping[str, Mapping[str, Any]] | None = None,
|
||||
review: Callable[[Mapping[str, str]], Awaitable[Sequence[str]]] | None = None,
|
||||
confirm_first: bool = False,
|
||||
baseline: Mapping[str, Any] | None = None,
|
||||
) -> list[ToolSpec]:
|
||||
"""A Specialist's tools: submit, ask, its working copy, and its role's tools with
|
||||
the cloud-read gate.
|
||||
@@ -284,6 +297,7 @@ def specialist_tools(
|
||||
`confirm_first` is set while a user is present and has not yet been asked about
|
||||
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.
|
||||
"""
|
||||
working = {} if working is None else working
|
||||
is_graph = kind is DeliverableKind.TARGET_ARCHITECTURE
|
||||
@@ -319,7 +333,9 @@ def specialist_tools(
|
||||
"attachment names must be relative paths without '..': "
|
||||
+ ", ".join(unsafe)
|
||||
)
|
||||
missing = check_submission(kind, content, attachments, upstream)
|
||||
missing = check_submission(
|
||||
kind, content, attachments, upstream, baseline=baseline
|
||||
)
|
||||
if missing:
|
||||
return ToolResult(
|
||||
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
|
||||
|
||||
@@ -42,14 +42,22 @@ Upstream = Mapping[str, Mapping[str, Any]]
|
||||
|
||||
|
||||
def read_list(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
|
||||
"""An upstream data file as a list of objects; empty when absent or unreadable."""
|
||||
"""An upstream data file as a list of objects; empty when absent or unreadable.
|
||||
|
||||
An entry a Change request marked removed is left out: it stays in the file as
|
||||
the record of what was dropped, and asks nothing of what follows.
|
||||
"""
|
||||
text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "")
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
return []
|
||||
return (
|
||||
[item for item in data if isinstance(item, dict)]
|
||||
[
|
||||
item
|
||||
for item in data
|
||||
if isinstance(item, dict) and item.get("change") != "removed"
|
||||
]
|
||||
if isinstance(data, list)
|
||||
else []
|
||||
)
|
||||
|
||||
326
app/workflows/changes.py
Normal file
326
app/workflows/changes.py
Normal file
@@ -0,0 +1,326 @@
|
||||
"""What a Change request changed against its Baseline (ADR-0006).
|
||||
|
||||
Ids are stable from one version of a Customer case's architecture to the next: a
|
||||
requirement, component, recommendation, Element, Relationship or Check that still
|
||||
holds keeps its id. That is what lets code, with no model, say what was added, what
|
||||
changed and what was removed; trace from each changed requirement to everything it
|
||||
reaches; and list apart anything that changed without being reached. Nobody asked
|
||||
for those, so a reader should see them as such.
|
||||
|
||||
This module is pure: data in, data out.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.workflows.chain import (
|
||||
COMPONENTS_FILE,
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
)
|
||||
from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
||||
|
||||
CHANGES_FILE = "changes.json"
|
||||
UNCHANGED, ADDED, CHANGED, REMOVED = "unchanged", "added", "changed", "removed"
|
||||
CHANGE_KINDS = (UNCHANGED, ADDED, CHANGED, REMOVED)
|
||||
|
||||
Deliverables = Mapping[str, Mapping[str, Any]]
|
||||
|
||||
|
||||
def _items(deliverables: Deliverables | None, kind: str, name: str) -> list[dict]:
|
||||
"""A data file as a list of objects, removed requirements included."""
|
||||
text = ((deliverables or {}).get(kind) or {}).get("attachments", {}).get(name, "")
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
return []
|
||||
return (
|
||||
[item for item in data if isinstance(item, dict)]
|
||||
if isinstance(data, list)
|
||||
else []
|
||||
)
|
||||
|
||||
|
||||
def _graph(deliverables: Deliverables | None) -> dict[str, list[dict]]:
|
||||
text = (
|
||||
((deliverables or {}).get("target_architecture") or {})
|
||||
.get("attachments", {})
|
||||
.get(GRAPH_ATTACHMENT, "")
|
||||
)
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
data = {}
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
return {
|
||||
key: [item for item in data.get(key, []) if isinstance(item, dict)]
|
||||
for key in ("elements", "relationships", "checks")
|
||||
}
|
||||
|
||||
|
||||
# --- the requirements say what changed --------------------------------------------------
|
||||
|
||||
|
||||
def check_requirement_changes(
|
||||
attachments: Mapping[str, str], baseline: Mapping[str, Any] | None
|
||||
) -> list[str]:
|
||||
"""What is wrong with a Change request's requirements.json against the Baseline's.
|
||||
|
||||
Every requirement carries a `change`. One that still holds keeps its id and is
|
||||
`unchanged`, with its text as it was. One that differs is `changed`; one no
|
||||
longer wanted stays in the list as `removed`; a new one takes a new id and is
|
||||
`added`. Everything but `unchanged` says why.
|
||||
"""
|
||||
name = REQUIREMENTS_FILE
|
||||
before = {
|
||||
item["id"]: item
|
||||
for item in _items({"requirements": baseline or {}}, "requirements", name)
|
||||
if isinstance(item.get("id"), str) and item.get("change") != REMOVED
|
||||
}
|
||||
revised = _items(
|
||||
{"requirements": {"attachments": attachments}}, "requirements", name
|
||||
)
|
||||
problems: list[str] = []
|
||||
seen = set()
|
||||
for item in revised:
|
||||
identifier = item.get("id")
|
||||
if not isinstance(identifier, str):
|
||||
continue
|
||||
seen.add(identifier)
|
||||
change = item.get("change")
|
||||
if change not in CHANGE_KINDS:
|
||||
problems.append(
|
||||
f"{name}: {identifier} needs a `change`: one of "
|
||||
f"{', '.join(CHANGE_KINDS)}"
|
||||
)
|
||||
continue
|
||||
reason = item.get("reason")
|
||||
if change != UNCHANGED and not (isinstance(reason, str) and reason.strip()):
|
||||
problems.append(f"{name}: {identifier} is {change} and needs a `reason`")
|
||||
if change == ADDED and identifier in before:
|
||||
problems.append(
|
||||
f"{name}: {identifier} is marked added, but the Baseline has that "
|
||||
"id; a new requirement takes a new id"
|
||||
)
|
||||
if change != ADDED and identifier not in before:
|
||||
problems.append(
|
||||
f"{name}: {identifier} is marked {change}, but the Baseline has no "
|
||||
"such requirement; mark a new one added"
|
||||
)
|
||||
if (
|
||||
change == UNCHANGED
|
||||
and identifier in before
|
||||
and _text(item) != _text(before[identifier])
|
||||
):
|
||||
problems.append(
|
||||
f"{name}: {identifier} is marked unchanged, but its text differs "
|
||||
"from the Baseline's; restore it or mark it changed"
|
||||
)
|
||||
problems += [
|
||||
f"{name}: Baseline requirement {identifier} is missing; keep it, or keep it "
|
||||
"marked removed with the reason"
|
||||
for identifier in before
|
||||
if identifier not in seen
|
||||
]
|
||||
if revised and all(item.get("change") == UNCHANGED for item in revised):
|
||||
problems.append(
|
||||
f"{name}: nothing is marked added, changed or removed; a Change request "
|
||||
"changes at least one requirement"
|
||||
)
|
||||
return problems
|
||||
|
||||
|
||||
def _text(item: Mapping[str, Any]) -> str:
|
||||
return " ".join(str(item.get("text", "")).split())
|
||||
|
||||
|
||||
def requirement_changes(deliverables: Deliverables | None) -> list[dict[str, str]]:
|
||||
"""The requirements a Change request added, changed or removed, with the reason."""
|
||||
return [
|
||||
{
|
||||
"id": str(item.get("id")),
|
||||
"change": str(item["change"]),
|
||||
"reason": str(item.get("reason", "")),
|
||||
"text": str(item.get("text", "")),
|
||||
}
|
||||
for item in _items(deliverables, "requirements", REQUIREMENTS_FILE)
|
||||
if item.get("change") in (ADDED, CHANGED, REMOVED)
|
||||
]
|
||||
|
||||
|
||||
# --- comparing two versions -------------------------------------------------------------
|
||||
|
||||
|
||||
def _compare(
|
||||
before: Sequence[Mapping[str, Any]],
|
||||
after: Sequence[Mapping[str, Any]] | None,
|
||||
key: str = "id",
|
||||
ignore: Sequence[str] = ("change", "reason"),
|
||||
) -> dict[str, list[str]]:
|
||||
"""Ids added, changed and removed between two lists of objects.
|
||||
|
||||
`after` is None while the revised Deliverable has not been produced: nothing
|
||||
has changed yet, which is not the same as everything having been removed.
|
||||
"""
|
||||
if after is None:
|
||||
return {ADDED: [], CHANGED: [], REMOVED: []}
|
||||
|
||||
def body(item: Mapping[str, Any]) -> dict[str, Any]:
|
||||
return {name: value for name, value in item.items() if name not in ignore}
|
||||
|
||||
old = {str(item.get(key)): body(item) for item in before if item.get(key)}
|
||||
new = {str(item.get(key)): body(item) for item in after if item.get(key)}
|
||||
return {
|
||||
ADDED: [identifier for identifier in new if identifier not in old],
|
||||
CHANGED: [
|
||||
identifier
|
||||
for identifier in new
|
||||
if identifier in old and new[identifier] != old[identifier]
|
||||
],
|
||||
REMOVED: [identifier for identifier in old if identifier not in new],
|
||||
}
|
||||
|
||||
|
||||
def reach(
|
||||
changed: Sequence[str],
|
||||
components: Sequence[Mapping[str, Any]],
|
||||
recommendations_changed: Sequence[str],
|
||||
graph: Mapping[str, Sequence[Mapping[str, Any]]],
|
||||
) -> set[str]:
|
||||
"""The Elements, Relationships and Checks a set of changed requirements reaches.
|
||||
|
||||
A changed requirement reaches the components that serve it, the Elements that
|
||||
realise those components, the Relationships at those Elements, and every Check
|
||||
on any of them or with the requirement as its source. A recommendation that
|
||||
changed reaches the Checks that come from it and what they apply to.
|
||||
"""
|
||||
sources = set(changed) | set(recommendations_changed)
|
||||
served = {
|
||||
str(component.get("id"))
|
||||
for component in components
|
||||
if set(component.get("requirements") or ()) & set(changed)
|
||||
}
|
||||
reached = {
|
||||
str(element.get("id"))
|
||||
for element in graph.get("elements", ())
|
||||
if element.get("component") in served
|
||||
}
|
||||
for check in graph.get("checks", ()):
|
||||
if check.get("source") in sources:
|
||||
reached.add(str(check.get("id")))
|
||||
reached.add(str(check.get("applies_to")))
|
||||
reached |= {
|
||||
str(relationship.get("id"))
|
||||
for relationship in graph.get("relationships", ())
|
||||
if relationship.get("from") in reached or relationship.get("to") in reached
|
||||
}
|
||||
reached |= {
|
||||
str(check.get("id"))
|
||||
for check in graph.get("checks", ())
|
||||
if check.get("applies_to") in reached
|
||||
}
|
||||
return reached
|
||||
|
||||
|
||||
def change_summary(
|
||||
baseline: Deliverables | None, current: Deliverables | None
|
||||
) -> dict[str, Any]:
|
||||
"""What a Change request changed, as changes.json holds it.
|
||||
|
||||
Requirements carry their own account. Everything else is compared by id. What
|
||||
changed inside the reach of the changed requirements is listed as requested;
|
||||
anything else that changed is listed apart as unrequested.
|
||||
"""
|
||||
requirements = requirement_changes(current)
|
||||
changed_ids = [item["id"] for item in requirements]
|
||||
produced = current or {}
|
||||
recommendations = _compare(
|
||||
_items(baseline, "design_recommendations", RECOMMENDATIONS_FILE),
|
||||
_items(current, "design_recommendations", RECOMMENDATIONS_FILE)
|
||||
if "design_recommendations" in produced
|
||||
else None,
|
||||
)
|
||||
components = _compare(
|
||||
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
|
||||
_items(current, "technical_decomposition", COMPONENTS_FILE)
|
||||
if "technical_decomposition" in produced
|
||||
else None,
|
||||
)
|
||||
old_graph, new_graph = _graph(baseline), _graph(current)
|
||||
designed = "target_architecture" in produced
|
||||
# Reach is traced through both versions: what a requirement used to touch can
|
||||
# change or go, as well as what it touches now.
|
||||
touched_recommendations = recommendations[ADDED] + recommendations[CHANGED]
|
||||
reached = reach(
|
||||
changed_ids,
|
||||
_items(current, "technical_decomposition", COMPONENTS_FILE),
|
||||
touched_recommendations,
|
||||
new_graph,
|
||||
) | reach(
|
||||
changed_ids,
|
||||
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
|
||||
touched_recommendations + recommendations[REMOVED],
|
||||
old_graph,
|
||||
)
|
||||
graph: dict[str, dict[str, list[str]]] = {}
|
||||
unrequested: dict[str, list[str]] = {}
|
||||
for part in ("elements", "relationships", "checks"):
|
||||
compared = _compare(old_graph[part], new_graph[part] if designed else None)
|
||||
graph[part] = compared
|
||||
outside = [
|
||||
identifier
|
||||
for change in (ADDED, CHANGED, REMOVED)
|
||||
for identifier in compared[change]
|
||||
if identifier not in reached
|
||||
]
|
||||
if outside:
|
||||
unrequested[part] = outside
|
||||
return {
|
||||
"requirements": requirements,
|
||||
"components": components,
|
||||
"recommendations": recommendations,
|
||||
**graph,
|
||||
# Changed without being reached by any changed requirement.
|
||||
"unrequested": unrequested,
|
||||
}
|
||||
|
||||
|
||||
def is_empty(summary: Mapping[str, Any]) -> bool:
|
||||
return not summary.get("requirements") and not any(
|
||||
summary.get(part, {}).get(change)
|
||||
for part in (
|
||||
"components",
|
||||
"recommendations",
|
||||
"elements",
|
||||
"relationships",
|
||||
"checks",
|
||||
)
|
||||
for change in (ADDED, CHANGED, REMOVED)
|
||||
)
|
||||
|
||||
|
||||
# What an Approval of each kind of Deliverable shows of the change.
|
||||
_SHOWN_WITH = {
|
||||
"requirements": ("requirements",),
|
||||
"technical_decomposition": ("components",),
|
||||
"design_recommendations": ("recommendations",),
|
||||
"target_architecture": ("elements", "relationships", "checks", "unrequested"),
|
||||
}
|
||||
|
||||
|
||||
def changes_for(summary: Mapping[str, Any], kinds: Sequence[str]) -> dict[str, Any]:
|
||||
"""The part of a change summary that belongs to the Deliverables being approved,
|
||||
with the parts that hold nothing left out."""
|
||||
shown: dict[str, Any] = {}
|
||||
for kind in kinds:
|
||||
for part in _SHOWN_WITH.get(kind, ()):
|
||||
value = summary.get(part)
|
||||
if isinstance(value, Mapping):
|
||||
value = {name: ids for name, ids in value.items() if ids}
|
||||
if value:
|
||||
shown[part] = value
|
||||
return shown
|
||||
@@ -30,6 +30,7 @@ from app.workflows.chain import (
|
||||
check_verdicts,
|
||||
graph_structure,
|
||||
)
|
||||
from app.workflows.changes import check_requirement_changes
|
||||
from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
||||
|
||||
|
||||
@@ -286,11 +287,14 @@ def check_submission(
|
||||
content: str,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Upstream | None = None,
|
||||
baseline: Mapping[str, object] | None = None,
|
||||
) -> tuple[str, ...]:
|
||||
"""Return what a submission lacks against its contract; empty means it's complete.
|
||||
|
||||
`upstream` is the Deliverables this one builds on, by kind. With it, the links
|
||||
along the Requirements chain are checked too.
|
||||
along the Requirements chain are checked too. `baseline` is the Baseline's
|
||||
version of this Deliverable in a Change request; with it, the account of what
|
||||
changed is checked.
|
||||
"""
|
||||
if not content.strip():
|
||||
return ("content: must not be empty",)
|
||||
@@ -311,4 +315,11 @@ def check_submission(
|
||||
name, check = DATA_CHECKS[kind]
|
||||
if attachments.get(name, "").strip():
|
||||
missing.extend(check(attachments, upstream))
|
||||
if (
|
||||
baseline is not None
|
||||
and kind is DeliverableKind.REQUIREMENTS
|
||||
and attachments.get(REQUIREMENTS_FILE, "").strip()
|
||||
and not missing
|
||||
):
|
||||
missing.extend(check_requirement_changes(attachments, baseline))
|
||||
return tuple(missing)
|
||||
|
||||
Reference in New Issue
Block a user