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

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