feat: consult only the pillars a change affects directly (iteration 5 step 3)

A graded question per pillar (not at all, only indirectly, directly) picks
the pillar advisors to consult again on a Revision or a Change request; the
design advisor is told which, and keeps its earlier advice for the rest. As
a yes or no the answer was yes for nearly every pillar of every change.

A completed Execution now writes working.json with each pillar's advice
and checklist review, and a Change request starts from its Baseline's, so
only the pillars a change touches are consulted afresh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-09 15:22:57 +01:00
parent a7bc5310f3
commit 844987587c
10 changed files with 290 additions and 4 deletions

View File

@@ -92,6 +92,8 @@ class ExecutionEngine:
orchestrator: OrchestratorPolicy | None = None,
submission_review: SubmissionReview | None = None,
confirm_drafts: bool = False,
decider: Decider | None = None,
pillar_threshold: float = 1.5,
) -> None:
required = {
ORCHESTRATOR,
@@ -114,6 +116,8 @@ class ExecutionEngine:
orchestrator=orchestrator,
submission_review=submission_review,
confirm_drafts=confirm_drafts,
decider=decider,
pillar_threshold=pillar_threshold,
).compile(checkpointer=checkpointer)
async def start(
@@ -381,6 +385,8 @@ async def open_assembly(
orchestrator=orchestrator,
submission_review=Reviews(reviews) if reviews else None,
confirm_drafts=settings.CONFIRM_DRAFTS,
decider=decider,
pillar_threshold=settings.JEV_PILLAR_THRESHOLD,
)
try:
yield Assembly(

View File

@@ -17,6 +17,7 @@ from app.states.execution_state import UNASSIGNED_CASE, case_dir, execution_dir
MANIFEST_FILENAME = "execution.json"
COMPLETED = "completed"
WORKING_FILENAME = "working.json"
_EXECUTION_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
@@ -86,10 +87,21 @@ def load_baseline(
}
if not deliverables:
raise BaselineError(f"baseline {execution_id} holds no Deliverables")
working_path = folder / WORKING_FILENAME
working: dict[str, Any] = {}
if working_path.is_file():
try:
loaded = json.loads(working_path.read_text(encoding="utf-8"))
except ValueError:
loaded = {}
if isinstance(loaded, dict):
working = loaded
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,
# Working material worth starting from again, such as pillar advice.
"working": working,
}

View File

@@ -97,6 +97,9 @@ class Settings(BaseSettings):
# until a full case has run with it.
JEV_REQUIREMENTS_REVIEW: bool = False
JEV_REQUIREMENTS_THRESHOLD: float = 0.3
# How directly a change must affect a pillar for its advisor to be consulted
# again: 0 not at all, 1 only indirectly, 2 directly.
JEV_PILLAR_THRESHOLD: float = 1.5
# Paths
BASE_DIR: Path = Path(__file__).resolve().parent.parent

View File

@@ -23,6 +23,7 @@ from app.adk.runtime import (
AgentRuntime,
AgentTask,
BudgetExhausted,
Decider,
NeedsInput,
Outcome,
RoleSpec,
@@ -34,6 +35,7 @@ from app.adk.runtime import (
ToolSpec,
TurnEnded,
)
from app.baseline import WORKING_FILENAME
from app.customer_case import close_intent
from app.nodes.router import ModelOrchestrator, OrchestratorPolicy, TurnView
from app.recorder import ExecutionRecorder
@@ -47,6 +49,7 @@ from app.states.ledger import DeliverableStatus, Ledger, LedgerRefusal
from app.states.lessons import collect_lesson_candidates, refusal
from app.tools import workspace
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
from app.tools.pillars import ADVICE_KEY, KEPT_FOR_CHANGES, pillars_touched
from app.workflows.chain import (
IMPLEMENTATION_FILE,
VERDICTS_FILE,
@@ -108,6 +111,8 @@ def make_execution_nodes(
orchestrator: OrchestratorPolicy | None = None,
submission_review: SubmissionReview | None = None,
confirm_drafts: bool = False,
decider: Decider | None = None,
pillar_threshold: float = 1.5,
) -> ExecutionNodes:
tool_factory = tool_factory or _no_tools
# How an Orchestrator turn is decided. The default drives the tools from the
@@ -315,11 +320,14 @@ def make_execution_nodes(
)
if isinstance(outcome, TurnEnded) and outcome.tool == "delegate":
hints = await _pillar_hints(
state, ledger, deliverables, toolbox.started, decider, pillar_threshold
)
sends = [
Send(
"specialist_task",
_specialist_input(
state, ledger, deliverables, drafts, kind, attempt
state, ledger, deliverables, drafts, kind, attempt, hints
),
)
for kind, attempt in toolbox.started.items()
@@ -391,6 +399,8 @@ def make_execution_nodes(
# 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"))
# And from its working material: the advice it was written from.
working.update(task_input.get("baseline_working") or {})
source = DEPENDENCY_GRAPH[kind].working_copy
if source and source is not kind:
# The tools work on the files as they were last submitted.
@@ -714,6 +724,7 @@ def _specialist_input(
drafts: Mapping[str, Mapping[str, Any]],
kind: DeliverableKind,
attempt: int,
hints: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
spec = DEPENDENCY_GRAPH[kind]
given = dependencies_for(kind, deliverables)
@@ -737,6 +748,9 @@ def _specialist_input(
"shown": kind.value in state.get("drafts_shown", []),
# The Baseline's version of this Deliverable, in a Change request.
"baseline": before,
"baseline_working": dict(
(baseline or {}).get("working", {}).get(kind.value, {})
),
# 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
@@ -754,6 +768,9 @@ def _specialist_input(
state.get("working", {}).get(kind.value, {})
),
"attempt": attempt,
# The pillars a change touches, when that could be judged: the design
# advisor consults those and keeps its earlier advice for the rest.
"pillars_to_consult": (hints or {}).get(kind.value),
# Set only in a Change request: what this Execution changes, and from what.
"baseline": _baseline_context(kind, baseline, before, deliverables)
if baseline
@@ -762,6 +779,44 @@ def _specialist_input(
}
async def _pillar_hints(
state: ExecutionState,
ledger: Ledger,
deliverables: Mapping[str, Mapping[str, Any]],
started: Mapping[DeliverableKind, int],
decider: Decider | None,
threshold: float,
) -> dict[str, list[str]]:
"""Which pillars the design advisor should consult again, when it is being
started on a Revision or a Change request and advice from before exists."""
kind = DeliverableKind.DESIGN_RECOMMENDATIONS
if decider is None or kind not in started:
return {}
baseline = state.get("baseline") or {}
remembered = state.get("working", {}).get(kind.value, {}).get(
ADVICE_KEY
) or baseline.get("working", {}).get(kind.value, {}).get(ADVICE_KEY)
if not remembered:
return {} # a first consultation: every pillar
change = "\n".join(ledger.feedback(kind))
if not change and baseline:
summary = change_summary(baseline.get("deliverables"), deliverables)
change = "\n".join(
f"Requirement {item['id']} {item['change']}: {item['text']} "
f"({item['reason']})"
for item in summary["requirements"]
)
chosen = await pillars_touched(
decider,
list(remembered),
change,
threshold=threshold,
scope=state["execution_id"],
)
# None: no decision, so no hint and every pillar. An empty list is an answer.
return {} if chosen is None else {kind.value: chosen}
# 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}
@@ -964,6 +1019,14 @@ def _write_outputs(
# submitted, or back in draft after something it depends on was reopened
"status": ledger.status(DeliverableKind(kind)).value,
}
kept = {
kind: {key: memory[key] for key in KEPT_FOR_CHANGES if memory.get(key)}
for kind, memory in state.get("working", {}).items()
}
kept = {kind: memory for kind, memory in kept.items() if memory}
if kept:
# Working material a Change request starts from, such as each pillar's advice.
files[WORKING_FILENAME] = json.dumps(kept, indent=2, ensure_ascii=False)
baseline = state.get("baseline") or None
if baseline:
# What this Change request changed against its Baseline, worked out from

View File

@@ -22,6 +22,8 @@ from typing import Any
from app.adk.runtime import (
AgentRuntime,
AgentTask,
Decider,
Question,
RoleSpec,
RunLimiter,
Submitted,
@@ -34,6 +36,9 @@ NO_GUIDANCE = "No guidance"
ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given
CHECKLIST_KEY = "pillar_checklists" # working memory: pillar -> its checklist review
REVIEW_HEADING = "Architecture framework checklist review"
# What a Change request carries over from its Baseline's working memory.
KEPT_FOR_CHANGES = (ADVICE_KEY, CHECKLIST_KEY)
_CHANGE_LIMIT = 6_000
STATUSES = ("addressed", "not_applicable", "not_addressed")
_STATUS_WORDS = {
"addressed": "Addressed",
@@ -42,6 +47,53 @@ _STATUS_WORDS = {
}
AFFECTED = ("not at all", "only indirectly", "directly")
async def pillars_touched(
decider: Decider,
pillars: Sequence[str],
change: str,
*,
threshold: float = 1.5,
scope: str = "",
) -> list[str] | None:
"""The pillars whose recommendations a change affects directly (ADR-0007).
One graded question per pillar: not at all, only indirectly, directly. A pillar
at `threshold` or above, on that scale of 0 to 2, is consulted again. An empty
list means the change touches none of them. None means no decision was
available, and every pillar is consulted.
Asked as a yes or no ("does this change call for revisiting ...?") the answer
was yes for nearly every pillar of every change; measured on 2026-10-09.
"""
if not change.strip() or not pillars:
return None
answers = await decider.decide(
f"A change to a cloud solution architecture:\n{change[:_CHANGE_LIMIT]}",
{
pillar: Question(
"score",
f"How directly does this change affect the {pillar} "
"recommendations for the workload?",
AFFECTED,
)
for pillar in pillars
},
scope=scope,
)
if not answers:
return None
return [
pillar
for pillar in pillars
if (answer := answers.get(pillar)) is not None
and isinstance(answer.value, (int, float))
and answer.value >= threshold
]
def pillar_consultation_tool(
runtime: AgentRuntime,
advisor: RoleSpec,
@@ -65,7 +117,9 @@ def pillar_consultation_tool(
)
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
chosen = list(pillars) if pillars else list(pillar_skills)
# No `pillars` consults them all; an empty list consults none, and returns
# what was said before.
chosen = list(pillar_skills) if pillars is None else list(pillars)
unknown = [pillar for pillar in chosen if pillar not in pillar_skills]
if unknown:
return ToolResult(
@@ -111,7 +165,8 @@ def pillar_consultation_tool(
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
"Give a brief with the workload, its requirements and the selected products. "
"Omit `pillars` to consult every pillar afresh. Name `pillars` to re-consult "
"only those; advice already given for the others is returned unchanged.",
"only those; advice already given for the others is returned unchanged. An "
"empty list consults none and returns the advice already given.",
{
"type": "object",
"properties": {

View File

@@ -20,6 +20,7 @@ from langgraph.graph import END, START, StateGraph
from app.adk.runtime import (
AgentRuntime,
Decider,
RoleSpec,
RunLimiter,
SubmissionReview,
@@ -44,6 +45,8 @@ def build_execution_graph(
orchestrator: OrchestratorPolicy | None = None,
submission_review: SubmissionReview | None = None,
confirm_drafts: bool = False,
decider: Decider | None = None,
pillar_threshold: float = 1.5,
) -> StateGraph:
nodes = make_execution_nodes(
runtime=runtime,
@@ -57,6 +60,8 @@ def build_execution_graph(
orchestrator=orchestrator,
submission_review=submission_review,
confirm_drafts=confirm_drafts,
decider=decider,
pillar_threshold=pillar_threshold,
)
graph = StateGraph(ExecutionState)