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:
2026-10-09 11:38:15 +01:00
parent db28d02f56
commit 5ef434d00e
32 changed files with 1824 additions and 40 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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