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:
46
README.md
46
README.md
@@ -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
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user