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

@@ -11,12 +11,15 @@ Vocabulary is defined in [CONTEXT.md](CONTEXT.md), decisions in [docs/adr/](docs
### 1. Orchestrator and Specialists (`agents/`)
One Orchestrator coordinates an Execution and is the only agent that talks to the user. It delegates each Deliverable to one Specialist, and independent Deliverables run in parallel:
- **Requirements discovery:** `requirements-analyst`, `decomposer`.
- **Solution architecture:** `product-selector`, `diagrammer`, `describer`, `design-advisor` (which consults one `pillar-advisor` per architecture-framework pillar), `iac-author`.
- **Solution architecture (design):** `product-selector`, `design-advisor` (which consults one `pillar-advisor` per architecture-framework pillar), `target-architect`.
- **Solution implementation:** `describer`, `iac-author`.
- **Solution validation:** `validator`.
- **Packaging:** `packager`.
Each Phase needs the user's explicit Approval before work that depends on it starts. A pre-approved mode serves batch and evaluation runs.
The design Phase ends with the **Target architecture**: one explicit graph of Elements, Relationships and Checks ([ADR-0005](docs/adr/0005-the-target-architecture-is-an-explicit-graph.md)). The user approves it before any infrastructure code is written. The diagram is drawn from it by code, the Terraform must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations each carry ids in a data file, so every requirement can be traced through to its verdict; a submission with a missing link is refused.
### 2. LangGraph state, ADK agents (`app/`)
Per [ADR-0003](docs/adr/0003-langgraph-holds-state-adk-agents-reason.md):
- A LangGraph `StateGraph` holds the Execution: the dependency graph of Deliverables (`app/workflows/deliverables.py`), the Ledger of their states (`app/states/ledger.py`), checkpoints, and `interrupt()` whenever the user must answer or approve.
@@ -38,7 +41,7 @@ The container starts the hierarchical Execution engine (ADR-0003) behind an A2A
- `POST /a2a`: A2A JSON-RPC for interactive, multi-turn Executions with Approvals.
- `GET /.well-known/agent-card.json`: A2A agent card.
- `GET /health`: Health signal, the Cloud provider and any MCP discovery gaps.
- `POST /generate`: One-shot, pre-approved Execution for batch and evaluation callers.
- `POST /generate`: One-shot, pre-approved Execution for batch and evaluation callers. Pass `customer_case` to group it with the case's other Executions; over A2A, send `customer_case` in the message metadata.
The original linear pipeline and its REST routes (`/card`, `/validate`, `/sessions/{session_id}`) were removed on 2026-10-06; see `.agents/plans/iter-03-kab-layout/`.
@@ -59,9 +62,6 @@ pytest -q
# Real-model evaluation of the engine (costs model usage; see eval/solution_eval.py)
python3 -m eval.solution_eval
# Run static artifact validation
python3 scripts/validate_artifacts.py
```
### Start the A2A Server
@@ -77,7 +77,7 @@ podman build -t gcp-solution-architecture-agent:latest .
```
#### 2. Run Container with Host Deliverables Volume Mount
To ensure execution deliverables (`deliverables/executions/{execution_id}/*`) are written directly to your host machine's workspace:
To ensure Execution outputs (`deliverables/cases/{customer_case}/executions/{execution_id}/*`) are written directly to your host machine's workspace:
```bash
podman run -d --name gcp-agent \
@@ -115,7 +115,7 @@ curl http://localhost:8080/.well-known/agent-card.json
# Run a pre-approved Execution
curl -X POST http://localhost:8080/generate \
-H "Content-Type: application/json" \
-d '{"request": "Event-driven regional HTTP application in Podman"}'
-d '{"request": "Event-driven regional HTTP application in Podman", "customer_case": "acme-webhooks"}'
```
---
@@ -147,23 +147,25 @@ gcp_solution_architecture_agent/
│ ├── solution_eval.py # Real-model evaluation of the Execution engine
│ ├── scoring.py # Checks applied to a finished Execution
│ └── datasets/ # Benchmark cases (JSON)
├── deliverables/ # Scalable deliverable repository (categorized & versioned)
│ ├── as-is/ # Pre-emptive Source Environment Deliverables (Before State)
│ │ ├── source-architecture.md
│ │ └── source-architecture.mmd
│ ├── target/ # Target Architecture Deliverables (After State)
│ │ ├── requirements.md
│ │ ├── architecture.md
│ │ └── architecture.mmd
│ ├── validation/ # Pre-deployment Validation Reports
│ │ └── validation-results.md
│ ├── guides/ # Consolidate Solution Architecture Guides
│ │ └── solution-architecture-guide.md
│ └── executions/ # Per-Execution Versioned Snapshots ({execution_id}/*)
├── deliverables/
│ └── cases/ # Everything generated, grouped by Customer case
│ └── <customer_case>/
│ ├── intent/ # What the customer asked for, and how it has changed
│ │ ├── 001.md, 002.md # Each request as the customer stated it, in order
│ │ └── history.json # Every request, the Execution it started and how it ended
│ └── executions/<execution_id>/
│ ├── execution.json # Request, status and files of this Execution
│ ├── solution-architecture-guide.md
│ ├── deliverables/<kind>.md # One per Deliverable
│ ├── requirements.json, components.json, products.json, recommendations.json
│ ├── target-architecture.json # Elements, Relationships and Checks
│ ├── architecture.mmd # Drawn from the graph
│ ├── terraform/, implementation.json # The code, and which part meets each Check
│ └── verdicts.json # Validation's verdict on each Check
├── lessons/candidates/<customer_case>/ # Lesson candidates per Execution (gitignored)
├── docs/ # Specifications, audit notes & verification records
├── terraform/ # Deployable GCP Terraform IaC blueprint
├── scripts/
│ └── validate_artifacts.py # Static artifact validation script
├── scripts/ # Vendored-Skill sync, MCP tool listing, Terraform checks
└── tests/ # Unit & integration test suite
```