Files
gcp_solution_architecture_a…/.agents/plans/iter-06-target-architecture-graph/MAP.md
Jonathan Boniface f1f6f1b83a feat: load the env file at start-up, trim schema lookups, remove legacy samples
Start-up
- Export the env file's variables for other libraries (the Cloud provider's
  client) into the process environment; the app's own settings and secrets
  are never exported, and a value already in the environment wins.
- Use GOOGLE_GENAI_USE_ENTERPRISE in place of the deprecated
  GOOGLE_GENAI_USE_VERTEXAI.

Target architect
- Look each distinct resource type up once instead of once per setting: in
  the run of 2026-10-07 it made 39 lookups for 8 types and exhausted its
  budget. terraform_schema's find takes several names; budget 30 to 45.
- A cut-off schema outline says so.

Removed, as leftovers of the original pipeline that nothing read
- terraform/ (no longer passed terraform validate), scripts/validate.sh,
  tests/test_package.py and the CI steps that ran on them.
- The sample outputs under docs/ and requirements.yaml.
- CI now pins Terraform 1.14.3, as the container image does.

Plans record the case 01 run: completed at 100% in 18 minutes with no
Revision, against 60 minutes and warnings before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:06:58 +01:00

90 lines
4.8 KiB
Markdown

# Plan Map
**Iteration:** 6, the Target architecture graph
**Intent:** Establish the Target architecture as one explicit graph of Elements, Relationships and Checks before any infrastructure code is written, and derive and check every later Deliverable from it, so that the outcome is understood before code exists and validation has a fixed bar.
**Status:** steps 1 to 10 built and covered by the deterministic suite; case 01 completed at 100% with no Revision on 2026-10-07 (`steps/step-11.md`); cases 02 to 04 have not run on this build
**This directory covers:** steps 1 to 11
## Order of work
Build this iteration before the remaining steps of iteration 4 (10 to 14) and before iteration 5. It changes Deliverables, Phases and the validation format that those steps build on. The effects on them are listed at the end of this file.
## Sources of truth
- `docs/adr/0005-the-target-architecture-is-an-explicit-graph.md`: the decision, its three points to confirm, and the rejected alternatives. Status `proposed`.
- `CONTEXT.md`: Target architecture, Element, Relationship, Check, Requirements chain. Use these words; "Dependency" stays the link between Deliverables.
- `iter-04-learning-and-skills/steps/step-8.md`, "The evaluation run of 2026-10-06": the evidence. Three validation passes gave 4, 7, then 5 different findings on the same Terraform.
- `docs/adr/0002-*.md`: the graph's format and how to write it are behaviour, so they live in a Skill; the engine only checks the result.
## The flow this iteration builds
```mermaid
flowchart TD
REQ([Workflow request]) --> R[Requirements]
R --> D[Technical decomposition]
D --> A1{{Approval: requirements discovery}}
A1 --> PS[Product selection]
PS --> DR[Design recommendations]
R --> DR
PS --> TA
DR --> TA[Target architecture: Elements, Relationships, Checks]
TA --> A2{{Approval: design}}
A2 --> DESC[Architecture description]
A2 --> IAC[Deployment guidance]
TA -.rendered by code.-> DIA[Architecture diagram]
IAC --> A3{{Approval: implementation}}
DESC --> A3
A3 --> VAL[Validation: a verdict per Check]
VAL -->|a Check fails| IAC
VAL -->|the graph is missing something| TA
VAL -->|every Check passes| A4{{Approval: validation}}
A4 --> G[Solution guide]
G --> A5{{Approval: packaging}}
```
## Status
| Step | What | Size | Status |
|---|---|---|---|
| 1 | Accept ADR-0005 | S | complete: accepted 2026-10-07 |
| 2 | Identify requirements, components and recommendations by id | M | complete |
| 3 | The graph: format, parsing and structural rules | M | complete |
| 4 | The Target architecture Deliverable, its Specialist and its Skill | M | complete; unproven with a real model |
| 5 | Completeness: the Requirements chain is a submission rule | M | complete |
| 6 | Split the solution architecture Phase: design, then implementation | M | complete |
| 7 | The diagram is rendered from the graph | S | complete |
| 8 | Deployment guidance implements the graph | M | complete |
| 9 | Validation gives a verdict per Check | M | complete |
| 10 | Revision routing: the code or the graph | S | complete; routing unproven with a real model |
| 11 | Evaluation: prove the loop converges | M | case 01 passes (100%, no Revision); cases 02 to 04 and the thresholds outstanding |
Size: S under a day, M a few days.
## Dependency graph
- Step 1: no dependencies
- Step 2: depends on step 1
- Step 3: depends on step 1
- Step 4: depends on step 3
- Step 5: depends on step 2, step 4
- Step 6: depends on step 4
- Step 7: depends on step 4
- Step 8: depends on step 5
- Step 9: depends on step 8
- Step 10: depends on step 6, step 9
- Step 11: depends on step 7, step 10
Steps 2 and 3 can be built side by side, as can 6 and 7.
## Effects on other iterations
- **Iteration 4 step 1** (`findings.json`): replaced by the verdicts of step 9 here. The free-form finding list goes.
- **Iteration 4 step 4** (contracts): the diagram's contract goes with the diagrammer; the decomposition's component table becomes data in step 2 here.
- **Iteration 4 step 6** (Orchestrator step order): rewritten by step 10 here.
- **Iteration 4 step 7** (lesson candidates): `finding` candidates become failed Checks and proposed additions.
- **Iteration 4 step 8** (evaluation): `no_blocking_findings` is rewritten against verdicts; the unset thresholds are set by step 11 here.
- **Iteration 4 step 11** (IaC patterns Skill): its patterns should be keyed by the product of an Element.
- **Iteration 4 step 13** (trim Specialist context): mostly achieved here, since later Specialists work from the graph. Re-scope it after step 11.
- **Iteration 5 step 5** (finding-to-Deliverable routing): no longer needed; a failed Check already names what it applies to.
- **Iteration 5 step 4** (semantic checks at submission): can judge whether each Check is verifiable as written.