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