feat: establish the Target architecture as a graph before code

Design is now approved before any infrastructure code is written (ADR-0005).
A new target-architect Specialist produces one graph of Elements,
Relationships and Checks; the diagram is rendered from it, deployment
guidance must account for every Check, and validation gives a verdict per
Check. Requirements, components, products and recommendations carry ids in
data files, and a submission with a gap in the Requirements chain is refused.

Also in this commit:
- Customer cases group Executions, with an intent history per case
- lesson candidates are captured when an Execution ends
- evaluation gains chain, verdict, judged and interactive checks, and
  per-case thresholds
- Terraform providers are cached between checks
- the requirements analyst proposes defaults instead of asking
- the legacy-baseline case and the checks that only read it are removed
- ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed
- plans for iterations 4 to 7 under .agents/plans/

Unproven with a real model: no evaluation run has completed on this design.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-07 13:59:09 +01:00
parent 7ee49ab352
commit e9246828b3
586 changed files with 5166 additions and 22432 deletions

View File

@@ -28,8 +28,17 @@ from app.workflows.deliverables import (
check_submission,
deliverables_in,
)
from app.workflows.target_architecture import (
DIAGRAM_ATTACHMENT,
GRAPH_ATTACHMENT,
GraphError,
TargetArchitecture,
parse_graph,
render_mermaid,
)
ORCHESTRATOR = "orchestrator"
_TARGET = DeliverableKind.TARGET_ARCHITECTURE
CLOUD_READ = "cloud_read"
_NO_ARGS: Mapping[str, Any] = {"type": "object", "properties": {}}
@@ -186,10 +195,23 @@ class OrchestratorToolbox:
"summary": summary,
"deliverables": [kind.value for kind in deliverables_in(phase_id)],
}
graph = self._target_architecture()
if graph and phase_id is DEPENDENCY_GRAPH[_TARGET].phase:
# What the user is approving before any code is written.
self.approval["target_architecture"] = graph.summary()
return ToolResult(
f"Asked the user to approve {phase_id}.", TurnEnded("request_approval")
)
def _target_architecture(self) -> TargetArchitecture | None:
deliverable = self._deliverables.get(_TARGET.value)
if not deliverable:
return None
try:
return parse_graph(deliverable.get("attachments", {})[GRAPH_ATTACHMENT])
except (KeyError, GraphError):
return None
async def reopen(self, kind: str, reason: str) -> ToolResult:
try:
result = self.ledger.reopen(
@@ -231,8 +253,13 @@ def specialist_tools(
kind: DeliverableKind,
extra: Sequence[ToolSpec],
allow_cloud_read: bool | None,
upstream: Mapping[str, Mapping[str, Any]] | None = None,
) -> list[ToolSpec]:
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate."""
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate.
`upstream` is the Deliverables this one builds on; with it, a submission's links
along the Requirements chain are checked.
"""
async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult:
try:
@@ -245,18 +272,34 @@ def specialist_tools(
"attachment names must be relative paths without '..': "
+ ", ".join(unsafe)
)
missing = check_submission(kind, content, attachments)
missing = check_submission(kind, content, attachments, upstream)
if missing:
return ToolResult(
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
)
if kind is DeliverableKind.TARGET_ARCHITECTURE:
# The diagram is a view of the graph, so the engine draws it.
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(
parse_graph(attachments[GRAPH_ATTACHMENT])
)
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
async def needs_input(questions: Sequence[str]) -> ToolResult:
async def needs_input(
questions: Sequence[str], draft: str | None = None, attachments: Any = None
) -> ToolResult:
questions = tuple(q for q in questions if q)
if not questions:
return _refused("ask at least one question")
return ToolResult("Questions sent to the user.", NeedsInput(questions))
try:
draft_attachments = files_from_argument(attachments)
except TypeError as exc:
return _refused(f"attachments: {exc}")
return ToolResult(
"Questions sent to the user.",
NeedsInput(
questions, draft=draft or None, draft_attachments=draft_attachments
),
)
return [
ToolSpec(
@@ -274,9 +317,15 @@ def specialist_tools(
),
ToolSpec(
"needs_input",
"Ask the user questions you can't proceed without. Ends your turn.",
"Ask the user questions you can't proceed without. Ends your turn. When "
"you are asking them to confirm a draft, pass it as `draft` (with its "
"`attachments`): it is returned to you with their answers.",
_schema(
{"questions": {"type": "array", "items": {"type": "string"}}},
{
"questions": {"type": "array", "items": {"type": "string"}},
"draft": {"type": "string"},
"attachments": FILES_SCHEMA,
},
["questions"],
),
needs_input,

View File

@@ -11,7 +11,7 @@ import os
import re
import tempfile
from collections.abc import Awaitable, Callable, Iterable, Mapping
from dataclasses import dataclass
from dataclasses import dataclass, field
from pathlib import Path, PurePosixPath
from typing import Any
@@ -76,7 +76,11 @@ async def mermaid_check(diagram: str) -> ToolResult:
class TerraformRunner:
binary: str = "terraform"
timeout_seconds: float = 300
# Providers are downloaded here once and reused by every later check. Without it,
# each validate or plan downloads its providers again into a scratch directory.
plugin_cache_dir: str | None = None
# Terraform's plugin cache is not safe for concurrent installs.
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
refusal = _check_files(files)
@@ -147,9 +151,12 @@ class TerraformRunner:
)
async def _init(self, root: Path) -> ToolResult | None:
code, output = await self._run(
[self.binary, "init", "-backend=false", "-input=false", "-no-color"], root
)
command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"]
if self.plugin_cache_dir:
async with self._init_lock:
code, output = await self._run(command, root)
else:
code, output = await self._run(command, root)
if code != 0:
return ToolResult(_clip(f"terraform init failed:\n{output}"))
return None
@@ -159,7 +166,12 @@ class TerraformRunner:
) -> tuple[int, str]:
environment = {**os.environ, "TF_IN_AUTOMATION": "1", **(env or {})}
if self.plugin_cache_dir:
environment["TF_PLUGIN_CACHE_DIR"] = self.plugin_cache_dir
cache = Path(self.plugin_cache_dir).expanduser().resolve()
cache.mkdir(parents=True, exist_ok=True)
environment["TF_PLUGIN_CACHE_DIR"] = str(cache)
# Each check runs in a scratch directory with no dependency lock file.
# Without this, Terraform downloads a cached provider again to verify it.
environment["TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE"] = "true"
try:
process = await asyncio.create_subprocess_exec(
*args,

View File

@@ -1,25 +1,31 @@
"""The design advisor's fan-out to one advisor per architecture-framework pillar.
Pillar advice is working material for the design recommendations Deliverable, not a
Deliverable itself, so it never touches the Ledger.
Deliverable itself, so it never touches the Ledger. It is kept in that Deliverable's
working memory, so a Revision re-consults only the pillars its feedback touches.
"""
from __future__ import annotations
import asyncio
import dataclasses
from collections.abc import Mapping, Sequence
from collections.abc import Mapping, MutableMapping, Sequence
from contextlib import AsyncExitStack
from typing import Any
from app.adk.runtime import (
AgentRuntime,
AgentTask,
RoleSpec,
RunLimiter,
Submitted,
ToolResult,
ToolSpec,
)
CONSULT_TOOL = "consult_pillar_advisors"
NO_GUIDANCE = "No guidance"
ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given
def pillar_consultation_tool(
@@ -27,8 +33,22 @@ def pillar_consultation_tool(
advisor: RoleSpec,
pillar_skills: Mapping[str, str],
extra_tools: Sequence[ToolSpec] = (),
memory: MutableMapping[str, Any] | None = None,
limiter: RunLimiter | None = None,
) -> ToolSpec:
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill."""
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill.
With `memory`, advice is remembered: naming `pillars` re-consults only those and
returns the remembered advice for the rest.
"""
async def advise(pillar: str, brief: str) -> str:
async with AsyncExitStack() as stack:
if limiter:
await stack.enter_async_context(limiter.slot())
return await _advise(
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
)
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
chosen = list(pillars) if pillars else list(pillar_skills)
@@ -38,20 +58,41 @@ def pillar_consultation_tool(
f"Refused: unknown pillars {', '.join(unknown)}; "
f"choose from {', '.join(pillar_skills)}"
)
results = await asyncio.gather(
*(
_advise(
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
async with AsyncExitStack() as stack:
if limiter:
# The calling Specialist only waits here, so its slot goes to advisors.
await stack.enter_async_context(limiter.lend())
fresh = dict(
zip(
chosen,
await asyncio.gather(*(advise(pillar, brief) for pillar in chosen)),
)
for pillar in chosen
)
remembered: dict[str, str] = (
dict(memory.get(ADVICE_KEY, {})) if memory is not None else {}
)
return ToolResult("\n\n".join(results))
sections = []
for pillar in pillar_skills:
if pillar in fresh:
advice = fresh[pillar]
if not advice.startswith(NO_GUIDANCE):
remembered[pillar] = advice
sections.append(f"## {pillar}\n\n{advice}")
elif pillar in remembered:
sections.append(
f"## {pillar} (from your earlier consultation)\n\n"
f"{remembered[pillar]}"
)
if memory is not None:
memory[ADVICE_KEY] = remembered
return ToolResult("\n\n".join(sections))
return ToolSpec(
CONSULT_TOOL,
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
"Give a brief with the workload, its requirements and the selected products.",
"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.",
{
"type": "object",
"properties": {
@@ -84,12 +125,10 @@ async def _advise(
try:
outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools])
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})."
return f"{NO_GUIDANCE}: the advisor failed ({exc})."
if isinstance(outcome, Submitted):
return f"## {pillar}\n\n{outcome.content.strip()}"
return (
f"## {pillar}\n\nNo guidance: the advisor ended with {type(outcome).__name__}."
)
return outcome.content.strip()
return f"{NO_GUIDANCE}: the advisor ended with {type(outcome).__name__}."
def _submit_advice_tool() -> ToolSpec:

View File

@@ -7,10 +7,11 @@ Cloud-read gating is applied later, per Execution, by `specialist_tools`.
from __future__ import annotations
from collections.abc import Mapping, Sequence
from collections.abc import Mapping, MutableMapping, Sequence
from typing import Any
from app.adk.roles import PILLAR_ADVISOR
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory, ToolSpec
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory, ToolSpec
from app.tools.mcp import McpCatalog
from app.tools.pillars import pillar_consultation_tool
from app.workflows.deliverables import DeliverableKind
@@ -23,26 +24,41 @@ def make_tool_factory(
*,
local_tools: Sequence[ToolSpec] = (),
catalog: McpCatalog | None = None,
limiter: RunLimiter | None = None,
) -> ToolFactory:
local_by_name = {tool.name: tool for tool in local_tools}
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
return catalog.tools_for(role.mcp_servers) if catalog else []
consult = None
advisor = roles.get(PILLAR_ADVISOR)
if pillar_skills and advisor:
# Pillar advisors can't ask for permission, so they get general-tier tools only.
advisor_tools = [tool for tool in mcp_tools(advisor) if tool.tier == "general"]
consult = pillar_consultation_tool(
runtime, advisor, pillar_skills, extra_tools=advisor_tools
)
# Pillar advisors can't ask for permission, so they get general-tier tools only.
advisor_tools = (
[tool for tool in mcp_tools(advisor) if tool.tier == "general"]
if advisor
else []
)
def tools_for(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
def tools_for(
role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any]
) -> Sequence[ToolSpec]:
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
tools += mcp_tools(role)
if consult and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value:
tools.append(consult)
if (
pillar_skills
and advisor
and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value
):
tools.append(
pillar_consultation_tool(
runtime,
advisor,
pillar_skills,
extra_tools=advisor_tools,
memory=working,
limiter=limiter,
)
)
return tools
return tools_for