feat: keep an unchanged description, list conditions, review coverage with Jev

After case 02 (completed at 100%, but with two Revisions of the Target
architecture for gaps validation found one pass at a time):

- A Deliverable stands while what it was written from is unchanged. The
  architecture description is written from the Elements and Relationships,
  so a Revision that only adds or rewords Checks no longer runs the describer.
- Non-functional requirements and recommendations list their conditions,
  one entry per separate thing that must be true; submission requires them.
- A coverage review at submission (JEV_COVERAGE_REVIEW, off by default):
  for each condition, Jev chooses which Check verifies it, or none. Asked as
  one broad yes-or-no per requirement it could not tell a complete design
  from one with known gaps; asked as a choice per condition it raised all
  four known gaps of case 02 and nothing on the complete graph. An opt-in
  live test (LIVE_JEV=1) repeats that.
- The validator is told to report every gap in its first pass.

Plans record the case 02 run and both forms of the review with figures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-07 20:58:38 +01:00
parent f1f6f1b83a
commit 5adc911a82
29 changed files with 1687 additions and 16 deletions

View File

@@ -25,10 +25,13 @@ A list. Number functional requirements `FR-1`, `FR-2` and non-functional ones `N
```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."}
{"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."]}
]
```
Every non-functional requirement lists its `conditions`: one entry for each separate thing that must be true for it to be met. 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.
### `components.json` (technical decomposition)
@@ -52,9 +55,12 @@ One entry per component, naming the product selected for it.
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"]}]
[{"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`, 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)
@@ -81,6 +87,7 @@ Write one configurable decision per recommendation. "Harden the service" cannot
- **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`. 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
@@ -128,4 +135,5 @@ Implement every Element, Relationship and Check, and nothing the Target architec
- 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 what its text asks with the Checks that name it as `source`.
- 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.