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:
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user