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:
@@ -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(
|
||||
|
||||
@@ -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,
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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": {
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user