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

@@ -36,4 +36,8 @@ Every check runs on a scratch copy of the files you pass. Nothing is applied, an
terraform plan -lock=false -var-file=<your.tfvars>
```
## Reporting verdicts
Give a verdict on every Check in the Target architecture and attach them as `verdicts.json`, in the format the requirements-chain Skill gives. The dry-run's result goes in its `dry_run` entry: `pass` when `terraform_validate` passes, `fail` with the error when it does not, and `not_run` when the tool could not run.
Never suggest `terraform apply` as part of validation.

View File

@@ -0,0 +1,122 @@
---
name: requirements-chain
description: >-
Defines the data files that carry requirements through to code and validation:
requirements, components, products, recommendations, the Target architecture
graph, the implementation map and the verdicts. Use when producing or checking
any Deliverable of a solution-architecture Execution, to write its data file
in the right format and keep every id traceable.
metadata:
scope: every Deliverable
---
# Requirements chain
Every requirement must be traceable, by id, to the components that serve it, to the Elements and Checks that realise it, to the code that implements them, and to a validation verdict. Each Deliverable attaches one data file that carries its part of that chain. A submission is refused when a link is missing, and the refusal names it.
Ids are short and stable: reuse an id exactly as the earlier Deliverable wrote it, and never renumber.
## The files
### `requirements.json` (requirements)
A list. Number functional requirements `FR-1`, `FR-2` and non-functional ones `NFR-1`, `NFR-2`.
```json
[
{"id": "FR-1", "kind": "functional", "text": "Accept signed webhooks over HTTPS."},
{"id": "NFR-1", "kind": "non_functional", "text": "Raw events are retained for 30 days."}
]
```
`kind` is `functional` or `non_functional`. Write one requirement per entry, so each can be checked on its own.
### `components.json` (technical decomposition)
A list of components and the requirement ids each serves. Every functional requirement must be served by at least one component.
```json
[{"id": "C-1", "name": "Ingest endpoint", "requirements": ["FR-1"]}]
```
### `products.json` (product selection)
One entry per component, naming the product selected for it.
```json
[{"component": "C-1", "product": "Cloud Run"}]
```
### `recommendations.json` (design recommendations)
A list. Each recommendation names its pillar and the components it applies to; use an empty list for one that applies to the whole workload.
```json
[{"id": "DR-1", "pillar": "security", "text": "Encrypt the topic with a customer-managed key.", "components": ["C-2"]}]
```
Write one configurable decision per recommendation. "Harden the service" cannot become a Check; "disable public ingress on the worker service" can.
### `target-architecture.json` (Target architecture)
```json
{
"elements": [
{"id": "E-1", "name": "Ingest service", "component": "C-1", "product": "Cloud Run", "resource_type": "google_cloud_run_v2_service"},
{"id": "E-2", "name": "Ingest identity", "product": "IAM", "resource_type": "google_service_account"}
],
"relationships": [
{"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"}
],
"checks": [
{"id": "K-1", "applies_to": "E-1", "statement": "ingress is INGRESS_TRAFFIC_ALL and roles/run.invoker is granted to allUsers", "source": "FR-1"},
{"id": "K-2", "applies_to": "E-2", "statement": "the account is attached to E-1 only", "source": "DR-3"}
],
"not_applicable": [
{"recommendation": "DR-9", "reason": "Single region by requirement NFR-2."}
]
}
```
- **Elements.** One per resource to be created. `component` is the component it realises; leave it out for a supporting Element such as an identity, a key or a network. `product` for a component's Element is exactly the product selected for that component.
- **Relationships.** `from` and `to` are Element ids. `kind` says what the connection is: calls, publishes to, reads from, runs as, is granted access to.
- **Checks.** `applies_to` is an Element or Relationship id. `source` is the requirement or recommendation id the Check comes from. Every Element has at least one Check.
- **Completeness.** Every component has an Element. Every non-functional requirement and every recommendation is the `source` of at least one Check, unless the recommendation is listed under `not_applicable` with a reason. Every selected product appears on its component's Element.
#### Writing a Check
A Check is a statement that is true or false of the infrastructure code. Name the argument and the value.
- Verifiable: "`kms_key_name` is set on the topic", "`min_instance_count` is at least 2", "the subscription has a `dead_letter_policy` pointing at E-6".
- Not verifiable: "the service is secure", "follows least privilege", "scales well".
Split a broad recommendation into several Checks, one per setting. A Check that the validator cannot verify from the code is sent back to you.
### `implementation.json` (deployment guidance)
One entry per Check in the Target architecture, saying where the code satisfies it. `file` is an attached file; `address` is the resource address and argument.
```json
[{"check": "K-1", "file": "terraform/main.tf", "address": "google_cloud_run_v2_service.ingest.ingress"}]
```
Implement every Element, Relationship and Check, and nothing the Target architecture does not ask for. When you believe the Target architecture is wrong or incomplete, say so with `needs_input`; do not quietly build something else.
### `verdicts.json` (validation results)
```json
{
"dry_run": {"verdict": "pass", "evidence": "terraform validate: Success! The configuration is valid."},
"checks": [
{"check": "K-1", "verdict": "pass", "evidence": "main.tf: ingress = \"INGRESS_TRAFFIC_ALL\"; google_cloud_run_v2_service_iam_member.public"},
{"check": "K-2", "verdict": "fail", "evidence": "google_service_account.ingest is also attached to the worker service"}
],
"proposed_additions": [
{"statement": "the bucket has a retention_policy of 30 days", "applies_to": "E-5", "reason": "NFR-1 has no Check on retention"}
]
}
```
- Give every Check exactly one verdict: `pass`, `fail` or `not_verifiable`, with the evidence you read in the code.
- `dry_run.verdict` is `pass`, `fail`, or `not_run` when the tool could not run.
- Judge the code against the Checks and nothing else. Something the Target architecture lacks is a `proposed_additions` entry, with the requirement or recommendation id it serves in `reason`. It is never a failed Check.