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

@@ -31,6 +31,7 @@ from google.adk.tools.tool_context import ToolContext
from google.genai import types
from app.adk.runtime import (
REJECTION_PREFIXES,
AgentTask,
BudgetExhausted,
Outcome,
@@ -52,13 +53,6 @@ TIMED_OUT = (
"Your last model request timed out, so its reply was lost. Continue the task, "
"and finish by calling the tool your instructions name for ending your turn."
)
# Tool replies that mean the call did nothing, logged so stuck agents can be diagnosed.
REJECTION_PREFIXES = (
"Not submitted",
"Refused",
"Discovery gap",
"terraform validate failed",
)
# Client-side timeouts from either HTTP stack google-genai may use (httpx or aiohttp,
# whose timeout errors subclass TimeoutError).
MODEL_TIMEOUTS = (TimeoutError, httpx.TimeoutException)

View File

@@ -7,6 +7,7 @@ enforce is exercised exactly as a model would meet it.
from __future__ import annotations
import json
from collections import deque
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass, field
@@ -20,6 +21,7 @@ from app.adk.runtime import (
Stopped,
ToolSpec,
)
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
@dataclass(frozen=True)
@@ -31,6 +33,97 @@ class Call:
Turn = Sequence[Call] | Callable[[AgentTask], Sequence[Call]]
# One small, coherent Requirements chain, so sample submissions pass every link.
SAMPLE_DATA: dict[str, str] = {
"requirements.json": json.dumps(
[
{"id": "FR-1", "kind": "functional", "text": "Accept events."},
{"id": "NFR-1", "kind": "non_functional", "text": "99.9% availability."},
]
),
"components.json": json.dumps(
[{"id": "C-1", "name": "Ingress", "requirements": ["FR-1", "NFR-1"]}]
),
"products.json": json.dumps([{"component": "C-1", "product": "Example Run"}]),
"recommendations.json": json.dumps(
[
{
"id": "DR-1",
"pillar": "security",
"text": "Use a dedicated identity.",
"components": ["C-1"],
}
]
),
"target-architecture.json": json.dumps(
{
"elements": [
{
"id": "E-1",
"name": "Ingress service",
"component": "C-1",
"product": "Example Run",
"resource_type": "example_run_service",
},
{
"id": "E-2",
"name": "Ingress identity",
"product": "Example IAM",
"resource_type": "example_service_account",
},
],
"relationships": [
{"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"}
],
"checks": [
{
"id": "K-1",
"applies_to": "E-1",
"statement": "The service runs at least two instances.",
"source": "NFR-1",
},
{
"id": "K-2",
"applies_to": "E-2",
"statement": "The identity is used by this service only.",
"source": "DR-1",
},
],
}
),
"implementation.json": json.dumps(
[
{"check": "K-1", "file": "terraform/main.tf", "address": "example.run"},
{"check": "K-2", "file": "terraform/main.tf", "address": "example.sa"},
]
),
"verdicts.json": json.dumps(
{
"dry_run": {"verdict": "pass", "evidence": "terraform validate passed."},
"checks": [
{"check": "K-1", "verdict": "pass", "evidence": "min instances is 2."},
{"check": "K-2", "verdict": "pass", "evidence": "One binding."},
],
"proposed_additions": [],
}
),
}
def sample_submission(kind: DeliverableKind, note: str = "") -> Call:
"""A `submit_deliverable` call that meets the Deliverable's contract."""
spec = DEPENDENCY_GRAPH[kind]
parts = [f"# {kind}", note or "Summary."]
parts += [f"## {section}\n{note or 'Details.'}" for section in spec.sections]
attachments = {
name: SAMPLE_DATA.get(name, f"# {name}\n") for name in spec.attachments
}
return Call(
"submit_deliverable",
{"content": "\n".join(parts) + "\n", "attachments": attachments},
)
@dataclass(frozen=True)
class RunRecord:
role: str

View File

@@ -6,7 +6,17 @@ a RoleSpec, an AgentTask and ToolSpecs in; an Outcome back. No framework types.
from __future__ import annotations
from collections.abc import Awaitable, Callable, Mapping, Sequence
import asyncio
import contextvars
from collections.abc import (
AsyncIterator,
Awaitable,
Callable,
Mapping,
MutableMapping,
Sequence,
)
from contextlib import asynccontextmanager
from dataclasses import dataclass, field
from typing import Any, Protocol
@@ -47,10 +57,15 @@ class Submitted:
@dataclass(frozen=True)
class NeedsInput:
"""The agent can't continue without the user. `permission` names a tool tier to grant."""
"""The agent can't continue without the user. `permission` names a tool tier to grant.
`draft` is work the agent wants back when it is started again with the answers.
"""
questions: tuple[str, ...]
permission: str | None = None
draft: str | None = None
draft_attachments: Mapping[str, str] = field(default_factory=dict)
@dataclass(frozen=True)
@@ -127,8 +142,62 @@ class ToolSpec:
tier: str = "general" # general | cloud_read | execution
# The tools a role gets beyond the Execution tools, given the Deliverable it is producing.
ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]]
# The tools a role gets beyond the Execution tools, given the Deliverable it is producing
# and that Deliverable's working memory: JSON-compatible data a tool may read and write,
# kept with the Execution across attempts.
ToolFactory = Callable[
[RoleSpec, str | None, MutableMapping[str, Any]], Sequence[ToolSpec]
]
class RunLimiter:
"""Caps how many agent runs are in flight at once.
A run that fans out to further runs lends its slot while it waits, so the cap
holds across the whole hierarchy and a cap of 1 cannot deadlock.
"""
def __init__(self, limit: int) -> None:
if limit < 1:
raise ValueError("limit must be at least 1")
self.limit = limit
self._semaphore = asyncio.Semaphore(limit)
self._holding: contextvars.ContextVar[bool] = contextvars.ContextVar(
"run_limiter_holding", default=False
)
@asynccontextmanager
async def slot(self) -> AsyncIterator[None]:
async with self._semaphore:
token = self._holding.set(True)
try:
yield
finally:
self._holding.reset(token)
@asynccontextmanager
async def lend(self) -> AsyncIterator[None]:
"""Give up the caller's slot, if it holds one, while its own fan-out runs."""
if not self._holding.get():
yield
return
self._semaphore.release()
token = self._holding.set(False)
try:
yield
finally:
self._holding.reset(token)
await self._semaphore.acquire()
# Tool replies that mean the call did nothing. Runtimes log them, and the Execution
# keeps them as lesson candidates.
REJECTION_PREFIXES = (
"Not submitted",
"Refused",
"Discovery gap",
"terraform validate failed",
)
class AgentRuntime(Protocol):