Files
Jonathan Boniface 0f80cb642f
Some checks failed
validation / verify (push) Failing after 11s
feat: a stated choice must reach a requirement, and only pinned providers (iteration 9 step 3)
Case 08 named the customer's stated topology in its design and did not build
it; every Check passed because none asked for it.

- The catalogue marks the 26 fields that bind a design. The agreed scope lists
  the ones the customer stated; what was assumed for them does not bind.
- A requirement says what it comes from. A submission of requirements is
  refused when one of the customer's own requirements, or a stated binding
  field, is named by none, or when the requirement carrying a choice is not a
  constraint with a condition. The existing chain then owes it a Check.
- Generated code may use only the providers the bundle pins: a resource or a
  required_providers entry of any other is refused before Terraform runs.
- The guide opens with how much of the design the customer stated, how much
  was assumed and how much is unknown.

Not run with real models.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 19:36:12 +01:00

10 KiB

name, description, metadata
name description metadata
requirements-chain 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.
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.

[
  {"id": "FR-1", "kind": "functional", "text": "Accept signed webhooks over HTTPS."},
  {"id": "NFR-1", "kind": "non_functional", "text": "Raw events are encrypted at rest and retained for 30 days.",
   "conditions": ["Raw events are encrypted at rest.", "Raw events are kept for 30 days and then deleted."]},
  {"id": "NFR-2", "kind": "non_functional", "text": "The service is available 99.9% of each month, across two zones.",
   "conditions": ["The service runs in at least two zones."],
   "outside_code": ["Measured availability is at least 99.9% a month."]}
]

Every non-functional requirement lists its conditions: one entry for each separate thing that must be true for it to be met and that infrastructure configuration can show. What it asks for that configuration cannot show goes under outside_code: an outcome measured in operation, behaviour of the application's own code, a process people follow, or a property of a region or product that only its provider publishes, such as a region's carbon rating or a product's service level. For those, the condition is the choice that configuration can show: "every resource is in the one agreed region" is a condition, and "that region has a high carbon-free energy score" is outside_code. A requirement has at least one entry between the two; one that is entirely outside code has "conditions": []. Write each so it can be checked on its own, and so that together they say everything the text says. The Target architecture needs a Check for each one.

kind is functional or non_functional. Write one requirement per entry, so each can be checked on its own.

When the customer's scope is in your context, a requirement says what it comes from in from: the ids of the customer's own requirements, and the scope fields it carries.

{"id": "NFR-4", "kind": "non_functional",
 "text": "The network is a hub with spokes, joined to on-premises over a private 10Gbps connection.",
 "conditions": ["A hub network is connected to every spoke network.", "A dedicated 10Gbps connection joins the hub to on-premises."],
 "from": ["REQ-03", "networking.topology", "networking.hybrid_connectivity.type", "networking.hybrid_connectivity.bandwidth_gbps"]}
  • Every requirement the customer wrote (scope.stated.intent.requirements) is named in the from of the requirement that covers it.
  • Every field under scope.binding is a choice the customer stated that the design must honour. Each is named in the from of a non-functional requirement with at least one condition that shows it was honoured. Write the condition about what must exist or be set, in terms a Check can verify: "a hub network is connected to every spoke network", not "the topology is hub and spoke".
  • One requirement may carry several fields that belong together. A submission is refused while any is carried by none.

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.

[{"id": "C-1", "name": "Ingest endpoint", "requirements": ["FR-1"]}]

products.json (product selection)

One entry per component, naming the product selected for it.

[{"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.

[{"id": "DR-1", "pillar": "security", "text": "Encrypt the topic with a customer-managed key.", "components": ["C-2"],
  "conditions": ["The topic is encrypted with a customer-managed key.", "The messaging service's own identity may use that key."]}]

Every recommendation lists its conditions, and outside_code where it applies, as a non-functional requirement does. When it applies to several components, give a condition for each.

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)

{
  "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.
  • Coverage. Every entry in the conditions of a non-functional requirement or a recommendation needs a Check that verifies it, with that requirement or recommendation as its source. An entry under outside_code gets no Check, and a requirement or recommendation with nothing but outside_code needs none. A condition that applies to several Elements needs a Check on each: "processing scales to zero when idle" applies to every processing Element, not one of them.
  • 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.

A Check must name a setting its Element's resource type really has. Two similar resource types often differ: a setting of a long-running service may not exist on a batch job. A Check on a setting the resource type lacks is sent back to you.

The tables of Elements, Relationships and Checks, and the diagram, are written from this file when you submit. Write the graph once, here.

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.

[
  {"check": "K-1", "file": "terraform/main.tf", "address": "google_cloud_run_v2_service.ingest.ingress"},
  {"check": "K-7", "unimplementable": "google_cloud_run_v2_job has no startup_cpu_boost argument; it exists only on a service."}
]

When a module creates the resource, address is the module and the input that sets what the Check asks for, such as module.database.ip_configuration.ipv4_enabled.

When a Check names a setting its resource type does not have, give it an unimplementable entry in place of file and address, saying what the resource type lacks. Write no code for it. The Target architecture is revised before anything is validated.

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)

{
  "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.
  • Find every gap in one pass: go through each requirement and recommendation in turn and compare its conditions with the Checks that name it as source. Propose nothing for its outside_code.
  • 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.