wdi-method 0.3.0

package/kit/.constitution/document/templates/c4.md

@@ -0,0 +1,77 @@
+---
+type: c4
+level: 2                     # 1 (system context) · 2 (containers) · 3 (components)
+container: '{container}'     # level 3 only — one file per container
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+---
+
+# C4 L{n} — {title}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Three levels, three files, three different questions. All live in .how/_platform/.
+
+       L1  c4-l1-system-context.md   Who uses the system, and what it talks to. Once per product.
+                                     EXTERNAL SYSTEMS LIVE HERE, and nowhere else.
+       L2  c4-l2-containers.md       What runs and what stores, and how they communicate. OWNS the
+                                     container list, and carries the PC x container matrix.
+       L3  c4-l3-<container>.md      ONE FILE PER CONTAINER WE BUILD. The boxes are Product Components.
+                                     Only where a container holds more than one PC — the L2 matrix
+                                     already says which PC lives where, so a one-PC container needs no
+                                     file of its own.
+
+     ALL THREE LAND AT G3, and not one of them waits for a wave. Which container a PC lives in cannot
+     be discovered by a wave, because a wave picks its stories FROM that answer.
+
+     THE AXIS THAT CONFUSES PEOPLE: a container runs its own code or stores its own data; a Product
+     Component is a domain slice. They cross. One container holds several PC boxes, and one PC may
+     appear in more than one container — which is the whole reason the L2 matrix exists.
+
+     A container with `built: false` — a database, a web server, anything whose implementation is
+     someone else's — appears at L2 and gets NO L3: there are no boxes inside it that anyone here
+     authored. What IS ours about it, its configuration and the invariant it enforces, belongs in an
+     AD-N or in cross-cutting.md. A C4 note MUST NOT be that fact's only home.
+
+     Together, L1 and L2 are what a normal project calls the HLD. ARCHITECTURE-SPINE.md is NOT that
+     — it constrains rather than describes. Deployment topology belongs to the devops repository and
+     is referenced from L2, never drawn here. -->
+
+## Diagram
+
+<!-- Author as valid mermaid. A diagram that does not render is worse than a table. -->
+
+## Elements
+
+<!-- One row per box, with what it is and why it exists. At L2 include the technology; at L1 do not
+     — L1 is for people who do not care. -->
+
+| Element | What it is | Notes |
+| --- | --- | --- |
+
+## Relationships
+
+<!-- One row per arrow: who talks to whom, about what, over what. -->
+
+| From | To | Purpose | Over |
+| --- | --- | --- | --- |
+
+## Product Components per container
+
+<!-- L2 ONLY, and MANDATORY there — complete at G3, with no exceptions and no dependence on `mode`.
+
+     One row per container with `built: true`, listing every PC that lives in it. This table is a
+     RENDERING of each PC's `containers:` in components.yaml; that registry is the SSOT and V25 fails
+     when the two disagree.
+
+     A `built: false` container is NOT a row here. Every PC's data lives in the database by
+     definition, so a column for it would say the same thing seven times, and the data inventory
+     already records which PC owns which table. -->
+
+| Container | Product Components living in it |
+| --- | --- |
+
+## What is deliberately not shown
+
+<!-- Cut clutter on purpose and say what you cut. A diagram that shows everything shows nothing, and
+     the next reader needs to know an omission was a choice. -->

package/kit/.constitution/document/templates/contract.md

@@ -0,0 +1,52 @@
+---
+type: contract
+component: '{pc}'
+lc: LC-{NNN}                 # the gateway this contract belongs to
+direction: exposed           # exposed (we serve it) · consumed (a third party serves it)
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+---
+
+# Contract — {name}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Lives in .how/<pc>/02-contracts/ when we expose it, .how/<pc>/03-integrations/ when we consume
+     someone else's.
+
+     Where a machine-readable spec exists — OpenAPI, protobuf, a schema file — THAT is the source of
+     truth and this document MUST point at it rather than restate it. A restated schema drifts from
+     the generated one within a wave. Write here only what the machine spec cannot carry. -->
+
+## Source of truth
+
+<!-- Path or URL to the machine-readable spec, or `none` if this contract is prose-only. -->
+
+## Purpose
+
+<!-- Which UC this serves, and what the caller is trying to achieve. -->
+
+## Operations
+
+<!-- One row per operation. Keep it thin — detail belongs to the machine spec. -->
+
+| Operation | Purpose | Realizes |
+| --- | --- | --- |
+
+## Error behaviour
+
+<!-- What the caller sees when things go wrong, and which of those are expected rather than
+     exceptional. This is the part a generated spec carries worst and a caller needs most. -->
+
+| Condition | Response | Caller should |
+| --- | --- | --- |
+
+## Compatibility
+
+<!-- What counts as a breaking change here, and how it is announced. A contract with no stated
+     breaking-change policy will be broken by someone acting in good faith. -->
+
+## Constraints
+
+<!-- Rate limits, size limits, timeouts, idempotency, ordering guarantees. Anything the caller MUST
+     honour that the schema does not express. -->

package/kit/.constitution/document/templates/cross-cutting.md

@@ -0,0 +1,80 @@
+---
+type: cross-cutting
+scope: _platform
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+---
+
+# Cross-Cutting — {product}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Home: .how/_platform/cross-cutting.md. Blueprint output, born at G3 by wdi-blueprint intent
+     `platform`. It exists at every `mode`.
+
+     WHAT THIS FILE IS FOR: the things defined ONCE for the whole product and referenced everywhere
+     else. Without a fixed shape they grow into four error formats, each of which looked reasonable
+     on its own page — and that is not a hypothetical failure, it is the standard one.
+
+     WHAT IT IS NOT: a place for rules. A statement that FORBIDS something across components is an
+     AD-N and belongs in the spine. This file DESCRIBES what is shared. One fact, one home — a rule
+     written here as well as in the spine gives the reader two versions to choose between. -->
+
+## Error envelope
+
+<!-- The shape of an error response, defined once. Every contract in .how/<pc>/02-contracts/
+     REFERENCES this rather than restating it, and documents its 4xx and 5xx IN this envelope — never
+     as an ad-hoc { "message": "..." }.
+
+     Field names are English: they are machine-facing keys, and language-guide.md governs that. What
+     the user reads is not a field name. -->
+
+```json
+```
+
+| Field | Type | Means | Always present |
+| --- | --- | --- | --- |
+
+## Error catalogue
+
+<!-- The codes this envelope may carry, and what each means to the caller. A code with no row here is
+     a code nobody can handle. -->
+
+| Code | HTTP | Means | Caller should |
+| --- | --- | --- | --- |
+
+## Milik platform
+
+<!-- REQUIRED as soon as anything is owned by `_platform` — a `platform_owns` entity, an inventory row,
+     an LC. V21 checks it.
+
+     Something lands here only when NO Product Component's promise is the reason it exists AND more than
+     one component depends on it. corpus-guide.md owns that test, and it refuses the one use people
+     reach for: "the owner is hard to decide".
+
+     `Jenis` is data · endpoint · job · screen, and the list is open. What is not open is the test.
+
+     `_platform` has no `FR`, so there is no owner-FR for another component to point at. What replaces
+     "one writer" is ONE DOCUMENTED SHAPE — stated here, once. A component that wants it different is
+     proposing a change to this file, not making a local choice. -->
+
+| Apa | Jenis | Kenapa tidak ada komponen yang menjelaskannya | Siapa yang menyentuhnya | Bentuk yang setiap penyentuh patuhi |
+| --- | --- | --- | --- | --- |
+
+<!-- `Siapa yang menyentuhnya` menyebut komponen, dan menyebut lebih dari satu adalah keadaan NORMAL —
+     itu separuh alasan barisnya ada di sini. Satu penyentuh adalah sinyal ia milik komponen itu. -->
+
+## Other product-level agreements
+
+<!-- One subsection each, only for what genuinely crosses components. Candidates that earn a place:
+     identity and session shape · timestamp and timezone convention · pagination shape ·
+     idempotency key convention · logging fields · rate-limit response shape.
+
+     Each MUST state where it is enforced. An agreement nothing enforces is a preference, and
+     preferences belong in codebase/conventions-guide.md where nothing has to justify itself. -->
+
+### {agreement}
+
+**Applies to:** {which components or containers — `all` is a valid answer and MUST be written}
+**Enforced by:** {a middleware, a shared helper, a test name — not "convention"}

package/kit/.constitution/document/templates/decision.md

@@ -0,0 +1,64 @@
+---
+type: decision
+id: DEC-{NNN}                # allocated from .control/registry/decisions.yaml, globally
+status: draft                # draft · accepted · applied · superseded · rejected
+touches: []                  # empty until applied; then the files this decision actually changed
+supersedes: null
+superseded_by: null
+created: '{YYYY-MM-DD}'
+---
+
+# DEC-{NNN} — {the decision, stated as what now holds}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Three sections are required: Decision, Why, Cost. The three below them are required only when
+     this decision reaches a Product Component whose `risk_accepted` is `low`. Anywhere else, drop
+     the ones you have nothing to put under — a heading with nothing beneath it reads as an omission.
+
+     A `DEC-` records ONE event. It freezes when its status reaches `applied`, not when it is
+     accepted. A changed mind after that produces a new `DEC-`, and this one becomes `superseded`
+     with a pointer forward.
+
+     Do not confuse this with AD-N in the architecture spine, which is a living rule edited in place.
+
+     Add `type:` to the frontmatter when it is useful — `risk-acceptance`, `course-correction`. -->
+
+## Decision
+
+<!-- One sentence, present tense, quotable into a rule. Not "we will". -->
+
+## Why
+
+<!-- The context that forced it. A few lines, written so a reader in a year needs no other document.
+     The memlog is where the reasoning lives, and the memlog MUST NOT be quoted into the corpus.
+     If this came out of a third failed fix attempt, say so — that is the signal
+     wdi-systematic-debugging exists to raise. -->
+
+## Cost
+
+<!-- What becomes harder. A decision with only benefits was not thought through. -->
+
+## Alternatives
+
+<!-- Required only at `risk_accepted: low`. What else was considered, and why each lost.
+     "We considered X" with no reason is not an alternative. -->
+
+| Option | Why not |
+| --- | --- |
+
+## Reversal trigger
+
+<!-- Required only at `risk_accepted: low`. The observable condition that makes revisiting this
+     correct. A decision with no reversal condition is a belief. -->
+
+## Trace
+
+<!-- Required only at `risk_accepted: low`. Where this came from. What it landed in belongs in
+     `touches:` above, not here — one fact, one home. -->
+
+| | |
+| --- | --- |
+| Meeting note | `.control/meetings/{YYYY-MM-DD-slug}.md` — or `—` |
+| Open question | `OQ-{n}` — or `—` |
+| Source material | path, or `—` |

package/kit/.constitution/document/templates/design-system.md

@@ -0,0 +1,67 @@
+---
+type: design-system
+scope: _platform
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+---
+
+# Design System — {product}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Home: .how/_platform/design-system.md. Written by wdi-ux, and it is the ONE file in _platform/
+     that wdi-blueprint does not own. Optional, like the rest of UX: it exists when the interface is
+     a substantial part of what the PRD promises.
+
+     WHY IT IS NOT IN A COMPONENT: tokens and base elements cross Product Components by definition. A
+     colour scale living in one component's 01-ux/ is a colour scale the other six will each redefine.
+
+     WHY ux.md DOES NOT SERVE IT: ux.md is the shape of DESIGN.md and EXPERIENCE.md, which are per
+     component. This is the third file, at product level, and it had no template at all.
+
+     THE CODE IS THE SSOT FOR VALUES. Where this repo's web side states a token in tokens.css, this
+     file MUST reference it rather than repeat the value. Two homes for one hex code is two hex codes
+     within a month. Read web/README.md before writing anything here — it is the authority for the
+     web side, and it MUST NOT be contradicted from this file.
+
+     Token and element NAMES are English: they are machine-facing keys, per language-guide.md. -->
+
+## Where the values actually live
+
+<!-- One line per source of truth — the stylesheet, the config, the generated file — with its path.
+     This section is what stops the rest of the document becoming a stale copy. -->
+
+## Tokens
+
+<!-- One table per scale. Name, what it is for, and where it resolves. NOT the raw value, unless this
+     file is genuinely the only place it exists. -->
+
+| Token | For | Resolves in |
+| --- | --- | --- |
+
+## Base elements
+
+<!-- The LC type `ui-element`, registered in components.yaml. One row each: what it is, its states,
+     and where its implementation lives. A composite reused across screens is `ui-composite` and
+     belongs in .how/<pc>/01-ux/, not here. -->
+
+| Element | States it MUST support | Implementation |
+| --- | --- | --- |
+
+<!-- Every element MUST state its empty, loading, error, and disabled states where they apply. The
+     populated state is the one that always gets designed; the others are the ones that ship broken. -->
+
+## Rules that bind every screen
+
+<!-- Only what a screen cannot legitimately override. Each MUST state what it prevents — a rule with
+     no failure behind it is a preference, and preferences go to codebase/conventions-guide.md.
+
+     A rule here that also holds for non-UI code is an AD-N and belongs in the spine instead. -->
+
+| Rule | Prevents |
+| --- | --- |
+
+## What this system deliberately does not cover
+
+<!-- Where a component is free to choose for itself. Absent, every local choice reads as a violation. -->

package/kit/.constitution/document/templates/flow.md

@@ -0,0 +1,51 @@
+---
+type: flow
+component: '{pc}'
+realizes: []                 # UC ids this flow implements
+risky: false                 # true when money, irreversible state, or a third party is involved
+created: '{YYYY-MM-DD}'
+---
+
+# Flow — {name}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Lives in .how/<pc>/06-flows/. This is the TECHNICAL path — components calling components. The
+     behavioural path the user experiences belongs to the UC in .what/<pc>/04-usecases/, and the two
+     MUST NOT be merged: one is reviewed by the Product Owner, the other is not.
+
+     A sequence diagram is written ONLY when `risky: true`. Drawing one for every flow costs more
+     than it returns and buries the ones that matter. -->
+
+## Realizes
+
+<!-- The UC ids, and one line on which part of them this covers. -->
+
+## Participants
+
+<!-- The LC ids involved, in the order they enter. -->
+
+## Happy path
+
+<!-- Numbered, one hop per line: who calls whom, carrying what. -->
+
+1.
+
+## Sequence diagram
+
+<!-- ONLY when risky: true. Author as valid mermaid — never an empty graph. Cut this section
+     entirely otherwise. -->
+
+## Failure modes
+
+<!-- Per hop: what failure looks like, what the system does, and whether the operation can be
+     retried safely. The retry column is the one that gets skipped and the one that causes double
+     charges. -->
+
+| Hop | Failure | System does | Safe to retry |
+| --- | --- | --- | --- |
+
+## Guarantees
+
+<!-- Idempotency, ordering, at-least-once versus exactly-once, timeout budget. State what actually
+     holds, not what would be nice. -->

package/kit/.constitution/document/templates/integration.md

@@ -0,0 +1,69 @@
+---
+type: integration
+component: '{pc}'
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+provider: '{who owns it outside the team}'
+---
+
+# Integration — {third-party name}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Home: .how/<pc>/03-integrations/<name>.md. Written at G4, from mode: guarded up, and only when
+     the component actually consumes a third party.
+
+     WHY THIS IS NOT contract.md: contract.md is the shape of an endpoint WE publish, and we can
+     change it. This is something SOMEBODY ELSE owns. Two things have no column in contract.md and
+     are the whole reason this template exists — who owns it outside the team, and what happens when
+     they change it without telling anyone.
+
+     COMMERCIAL FACTS MUST NOT APPEAR HERE. A rate limit that exists because of what was negotiated
+     is written as the technical fact — "300 requests per minute" — and never as the negotiation.
+     repo-guide.md owns that boundary, and this file is the most common place it leaks. -->
+
+## Who owns it
+
+| | |
+| --- | --- |
+| Provider | {the organisation} |
+| Our contact | {a role, and where the person's name is recorded — not the name} |
+| Where credentials live | {the devops repo and path. NEVER the credential} |
+| Notice we get before a breaking change | {a period, or `none` — and `none` is the answer that changes the design} |
+
+## What we use it for
+
+<!-- Which FR or UC depends on it, by id. An integration no promise depends on is one we are
+     carrying for free. -->
+
+## What we send and receive
+
+<!-- Only the surface we actually touch. A full API description belongs to their documentation, cited
+     by URL, and copying it here creates a second version that goes stale silently. -->
+
+| Direction | Operation | Carries | Contains personal data |
+| --- | --- | --- | --- |
+
+## When it changes without telling us
+
+<!-- The section that earns this file. For each: how we would notice, how long we would run wrong
+     before noticing, and what happens meanwhile. "We would see errors" is not an answer unless
+     something is actually watching. -->
+
+| Change | How we notice | Blast radius | What we do |
+| --- | --- | --- | --- |
+
+## When it is slow, absent, or lying
+
+<!-- The same three failures the SDD's Failure Behaviour asks about, for this boundary. State the
+     timeout, the retry policy, what the user sees, and what gets logged. A retry policy with no cap
+     is an outage amplifier. -->
+
+| Failure | Timeout | Retry | What the user sees | What is logged |
+| --- | --- | --- | --- | --- |
+
+## What we would do without them
+
+<!-- One paragraph. Not a migration plan — the honest answer, which is sometimes "the feature stops".
+     Writing it is what makes the dependency visible before it has to be replaced in a hurry. -->

package/kit/.constitution/document/templates/inventory.md

@@ -0,0 +1,69 @@
+---
+type: inventory
+kind: db                 # db · api · screen · endpoint — decides the row shape below
+scope: _platform         # `_platform` for the three product-level inventories; `{pc}` for kind: endpoint
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+derived_from: plan       # plan · code — see the TEMPLATE GUIDE
+verified: ''             # commit SHA the derivation was read at; required when derived_from: code
+---
+
+# Inventory — {tables | endpoints | screens | endpoints of {pc}}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     ONE template, four kinds. Only the row shape differs; the rules are the same for all four.
+
+       kind: db      -> .how/_platform/inventory-db.md
+       kind: api     -> .how/_platform/inventory-api.md
+       kind: screen  -> .how/_platform/inventory-screen.md
+       kind: endpoint-> .how/<pc>/02-contracts/00-inventory.md, at mode: deep only
+
+     The first three are BLUEPRINT output, born at G3 by wdi-blueprint intent `platform`. They exist
+     at every `mode`, including catalog, and they are what makes catalog usable at all: the use case
+     list plus these three plus C4 is the whole record a builder gets there.
+
+     THE NUMBER IS STABLE. A new row takes the next `No`, never a renumber. Renumbering renames every
+     file after it and breaks every link pointing at them. A removed row keeps its number and its
+     status becomes `removed`; the number MUST NOT be reused.
+
+     TWO WAYS THIS FILE COMES TO EXIST, and derived_from says which:
+       plan  no code yet. Written as intent — the tables, endpoints, or screens planned. Nothing can
+             be derived, because there is no source.
+       code  code exists. Derived by .constitution/scripts/inventory.py — migrations for tables,
+             route registration for endpoints, pages for screens — and THEN compared with the plan.
+             The difference is a FINDING, reported. It MUST NOT be patched into agreement by hand.
+
+     MUST NOT be assembled from a README, from a route name that looks plausible, or from memory. -->
+
+## Rows
+
+<!-- kind: db -->
+
+| No | Table | Owning component | What it holds | Key columns | Status |
+| --- | --- | --- | --- | --- | --- |
+
+<!-- kind: api  — keep this block and delete the others
+| No | Method | Path | Owning component | Description | Status |
+| --- | --- | --- | --- | --- | --- |
+-->
+
+<!-- kind: screen
+| No | Screen | Route | Owning component | Actor | UC served |
+| --- | --- | --- | --- | --- | --- |
+-->
+
+<!-- kind: endpoint
+| No | Method | Path | Spec file | Status |
+| --- | --- | --- | --- | --- |
+-->
+
+<!-- Status values: draft · published · deprecated · removed. A row with no status reads as
+     published, which is the one reading that is never safe. -->
+
+## Findings
+
+<!-- Only when derived_from: code. Each difference between the plan and what the code actually does,
+     one line each, with which side is being reported — not which side was changed. Nothing here is
+     resolved by editing the other side; a finding routes to the skill that owns it. -->

package/kit/.constitution/document/templates/lc.md

@@ -0,0 +1,47 @@
+---
+type: lc
+id: LC-{NNN}                 # allocated from .control/registry/components.yaml
+name: '{name}'
+lc_type: service             # ui-screen · ui-composite · ui-element · gateway · service · job · store
+container: '{container}'     # the runnable/deployable unit it lives in
+component: '{pc}'            # the Product Component it belongs to
+owner: '{team or person}'
+area: '{area}'
+created: '{YYYY-MM-DD}'
+---
+
+# LC-{NNN} — {name}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     A Logical Component is ONE addressable unit of build. It is not a Product Component: a PC is a
+     domain slice and the box at C4 L3; an LC is something you can point at and change.
+
+     `lc_type` decides where this prose lives, and the mapping is not negotiable:
+       ui-screen · ui-composite → .how/<pc>/01-ux/
+       ui-element               → .how/_platform/design-system.md
+       gateway                  → .how/<pc>/02-contracts/ or 03-integrations/
+       service · job            → .how/<pc>/04-components/
+       store                    → .how/<pc>/05-model/
+
+     An LC MUST be registered by the time its wave CLOSES — V12 checks that
+     every `touches` entry resolves. -->
+
+## Responsibility
+
+<!-- One paragraph. What this unit is answerable for. If it needs "and" more than once, it is
+     probably two units. -->
+
+## Depends on
+
+<!-- Other LC ids, and the direction. Dependency direction is a rule carried by the spine, not a
+     preference — a dependency pointing the wrong way is a conflict to surface, not to document. -->
+
+## Interface
+
+<!-- What it exposes to the rest of the system. For a gateway this points at the contract in
+     02-contracts/ rather than restating it. -->
+
+## Notes
+
+<!-- Anything a builder cannot read off the code. Cut if there is nothing. -->

package/kit/.constitution/document/templates/lifecycle.md

@@ -0,0 +1,52 @@
+---
+type: lifecycle
+component: '{pc}'
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+entities: []             # the domain entities whose lifecycles this file carries
+---
+
+# State Lifecycle — {Product Component}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Home: .what/<pc>/03-domain/state-machines.md. Written at G4, at mode: deep ONLY. Below deep it
+     MUST NOT be written to fill a slot.
+
+     One section per entity that has more than one state. An entity with a single state has no
+     lifecycle and MUST NOT get a section.
+
+     WHY THIS HAS ITS OWN TEMPLATE: a transition table does not resemble an ERD, so it cannot be
+     lodged inside model.md. What it needs stated — who may move a thing, and what makes a state
+     terminal — has no column in an entity diagram.
+
+     THIS IS BEHAVIOUR, NOT SCHEMA. The state VALUES are English, because they are enum values and
+     language-guide.md governs that. Their LABELS — what a user reads — are not written here; they
+     belong to the screen. A value rendered straight to the screen is the known pitfall this repo
+     already records.
+
+     G3 asks whether there is a state that can be entered but not left. This file is where that is
+     answered, and an unreachable or inescapable state is a FINDING, not a documented fact. -->
+
+## {Entity}
+
+**States:** `{value}` · `{value}` · `{value}`
+**Initial:** `{value}` — and what creates it
+**Terminal:** `{value}` · `{value}` — and why nothing leaves them
+
+| From | To | Trigger | Who may | Guard | Side effect |
+| --- | --- | --- | --- | --- | --- |
+
+<!-- `Who may` names an actor from the SRS Actor Register, or `System` for an automatic transition.
+     `Guard` is the business rule that has to hold — cite the BR- id rather than restating it.
+     `Side effect` is what else changes; a transition with an invisible side effect is the one that
+     surprises someone while the code is being written.
+
+     Every state in the list above MUST appear at least once as a `To`, except the initial one, and
+     at least once as a `From`, except a terminal one. That is the check, and it is mechanical. -->
+
+### What is deliberately not modelled
+
+<!-- A state someone will look for and not find, and why. A schema value nothing uses — say so:
+     until the schema is cleaned, it has no label, no transition, and no meaning. -->