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:
@@ -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.
|
||||
|
||||
122
skills/requirements-chain/SKILL.md
Normal file
122
skills/requirements-chain/SKILL.md
Normal 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.
|
||||
Reference in New Issue
Block a user