wdi-method 0.3.0

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

@@ -0,0 +1,146 @@
+---
+type: sdd
+component: '{pc}'
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+realizes: []             # UC ids this design realizes, from usecases.yaml
+binds: []                # AD ids from the spine that bind here
+reviewed:                # V13. Diisi hanya setelah bmad-review benar-benar dijalankan
+  date: ''               # '{YYYY-MM-DD}'
+  sha: ''                # commit it was reviewed at; without the SHA, staleness cannot be measured
+  lenses: []             # the set risk_accepted names — NOT a fixed list
+---
+
+# SDD — {Product Component}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them. Never emit a comment in a finished
+     SDD. Headings stay English; prose is Bahasa Indonesia with technical terms left in English. -->
+
+<!-- NOT an HLD, and NOT a one-shot LLD. What the system consists of belongs to C4 L1-L2; architecture
+     constraints belong to ARCHITECTURE-SPINE.md; deployment topology belongs to the devops repository.
+     This document is LIVING: one per Product Component, amended every wave. -->
+
+<!-- EVERY SECTION MARKS THE MINIMUM `mode` THAT DEMANDS IT. Below that minimum it MUST NOT be written
+     to fill a slot; above it, it is required. Read the component's mode from its row in
+     components.yaml, falling back to `mode:` in index.yaml.
+
+     At mode: catalog this file is a SKELETON — this frontmatter and these headings, and nothing else.
+     That is a FINISHED state, not an unfinished one: G4 is skipped at catalog, and the code is written
+     from the use case catalogue, the three inventories, and C4.
+
+     `reviewed.lenses` MUST match what risk_accepted names, NOT what `mode` says. One component MAY sit
+     at catalog and still be reviewed the hardest. -->
+
+## Decision Summary · [outline]
+
+<!-- <=1 page, business language. What this component is built as, and the one or two choices that cost
+     the most to reverse. This is what the Product Owner reads at G4. -->
+
+## Structure · [outline]
+
+<!-- The Logical Components and how they depend on each other. Carry the dependency direction — it IS a
+     rule, not decoration.
+
+     Every LC named here MUST be registered in .control/registry/components.yaml, and the registration
+     is checked WHEN THE WAVE CLOSES — V12 — not before a story is ready-for-dev. The old timing
+     demanded the answer at the moment the information was thinnest. -->
+
+| LC | type | Responsibility |
+| --- | --- | --- |
+
+## Inherited Constraints · [guarded]
+
+<!-- Every AD-N from ARCHITECTURE-SPINE.md that reaches this component, QUOTED VERBATIM under its
+     ORIGINAL id. A paraphrase drifts, and the drift is invisible because both texts read reasonably.
+
+     A local choice contradicting one is a conflict to surface through wdi-decision, never an override
+     made here. Below `guarded` this section is absent and the AD-N still binds — an invariant does not
+     stop holding because a document is thin. -->
+
+| AD | Quoted rule | How it lands here |
+| --- | --- | --- |
+
+## Failure Behaviour · [guarded]
+
+<!-- PER BOUNDARY, and every boundary. This section STANDS WITHOUT the ABCE pass below, and that is
+     what makes `guarded` worth having: the boundary list already exists in
+     .how/_platform/inventory-api.md and inventory-screen.md, each with an owning-component column.
+     Do not derive it again.
+
+     For each: what happens when the thing on the other side is slow, absent, or lying. "Returns an
+     error" is not an answer. G4 asks this as a starred question from guarded up.
+
+     A failure mode that turns out to be a PROMISE — a refund path, a partial save — goes to the SRS
+     first, and becomes a scenario on the .what side. -->
+
+| Boundary | Slow | Absent | Lying | What the user sees | What is logged |
+| --- | --- | --- | --- | --- | --- |
+
+## Robustness Analysis · [deep]
+
+<!-- The ABCE pass, in order: Boundary -> Control -> Entity -> Behaviour. For every UC marked
+     `critical` in the paired SRS.
+
+     It MUST NOT have appeared in the SRS, and below `deep` it MUST NOT be written at all. Failure
+     Behaviour above does not need it. -->
+
+## Design Notes
+
+<!-- Only what a builder cannot read off compliant code. Rationale lives in the memlog and in DEC-;
+     restating it here creates a second version that drifts. Cut this section when it is empty. -->
+
+## Evidence
+
+<!-- Required whenever this document describes code that ALREADY EXISTS — brownfield, and equally when
+     a component's `mode` was raised after its code was running. What is written then is an AS-BUILT
+     RECORD, not a design.
+
+     Every technical claim MUST name the file that proves it. Four labels, and they are mandatory:
+       [ASSUMED]              we decided to believe it; nothing was read that confirms it
+       [PARTIAL]             verified for part of the surface — and it MUST say which part is not
+       [NEEDS CONFIRMATION]  a question with an owner, filed through wdi-question
+       [MISSING]           checked, and the thing described is NOT there
+
+     An unlabelled claim is read as verified. A claim MUST NOT be raised because it survived several
+     readings — familiarity is not evidence.
+
+     [MISSING] MUST NOT be deleted. It is the only surviving evidence that somebody once believed the
+     thing existed. Each is dispositioned as a BUG-, a correction, or planned work, and an unresolved
+     one MUST NOT pass G4. -->
+
+| Claim | Label | Read to decide | Disposition |
+| --- | --- | --- | --- |
+
+---
+
+## Slots
+
+<!-- The numbers are ABCE CLASSIFICATION — Boundary, Control, Entity, behaviour — NOT reading order.
+     This is the opposite of .what/<pc>/. The two MUST NOT be conflated.
+
+     Content SHOULD stay in this kernel until the file grows past roughly 400 lines — a suggestion, not
+     a threshold.
+
+     01-ux/            [deep], or earlier through wdi-ux. Screens and composites; LC types ui-screen,
+                       ui-composite. This slot belongs to wdi-ux, not to wdi-component.
+                       Base tokens and elements do NOT land here — .how/_platform/design-system.md
+     02-contracts/     [deep]. 00-inventory.md FIRST, then one spec per endpoint carrying its stable
+                       number. Every spec answers all five lanes — auth, validation, error, rate
+                       limiting, idempotency — with `none` and a reason where one does not apply.
+                       Error responses reference the envelope in _platform/cross-cutting.md, never
+                       restate it. LC type gateway
+     03-integrations/  [guarded], when the component consumes a third party. From templates/
+                       integration.md. LC type gateway
+     04-components/    [deep]. Services and jobs. LC types service, job
+     05-model/         [deep]. Schema and storage, INCLUDING the data dictionary per column — a diagram
+                       alone does not say what a column means. LC type store
+     06-flows/         [deep]. Sequence diagrams ONLY for flows involving money, irreversible state, or
+                       a third party. Lane order is fixed once for the project in
+                       codebase/conventions-guide.md; the No-op lane rule is REPEALED
+
+     supplements/ is REPEALED along with the ANX- concept it existed for. -->
+
+## Open Items
+
+<!-- Unresolved design questions, each pointing at its row in .control/questions/. -->

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

@@ -0,0 +1,149 @@
+---
+type: srs
+component: '{pc}'
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+satisfies: []            # FR / NFR ids this component carries, from requirements.yaml
+reviewed:                # V13. Diisi hanya setelah bmad-review benar-benar dijalankan
+  date: ''               # '{YYYY-MM-DD}'
+  sha: ''                # commit it was reviewed at; without the SHA, staleness cannot be measured
+  lenses: []             # the set risk_accepted names — NOT a fixed list
+---
+
+# SRS — {Product Component}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them. Never emit a comment in a finished
+     SRS. Section headings stay English; the prose inside is Bahasa Indonesia, with technical terms
+     left in English per the controlled vocabulary. -->
+
+<!-- NOT a one-shot document. Despite the IEEE name, this SRS is LIVING: one per Product Component,
+     amended every wave, never signed off and frozen. -->
+
+<!-- TWO SKILLS WRITE IT, AT TWO GATES, and every section below says which:
+       [G3]  wdi-blueprint intent `catalog`. Exists at EVERY mode, including catalog
+       [G4]  wdi-component intent `behaviour`, only as deep as the component's mode
+
+     So this file EXISTS at mode: catalog. It carries the actor list and the use case catalogue, and
+     what is absent there is 04-usecases/UC-<n>-<slug>.md — the step-by-step flows.
+
+     `reviewed.lenses` MUST match what this component's risk_accepted names in components.yaml —
+     edge-case-hunter at low and medium, structure + prose at high. It is NOT read off `mode`. -->
+
+## Decision Summary · [G3]
+
+<!-- <=1 page, business language, no jargon lacking a Glossary entry. What the Product Owner reads.
+     A summary that cannot be read inside the gate's time budget IS the finding. -->
+
+## Why · [G3]
+
+<!-- Why this component exists as a separate thing. One paragraph. If it reads the same as another
+     component's Why, the boundary is wrong. -->
+
+## Actor Register · [G3]
+
+<!-- SSOT for actors, referenced by the SDD. MUST stay in this kernel, never split into a slot. Two
+     actors that turn out to be the same person MUST be merged, and G3 asks exactly this.
+
+     A variant of one actor that differs only in what is shown to them is NOT a second actor. -->
+
+| Actor | Who they are | What they may do |
+| --- | --- | --- |
+
+## UC Catalogue · [G3]
+
+<!-- THE use case list, and at mode: catalog it is the whole use-case record. One line each, and the
+     line is the artifact — not a placeholder waiting for a file.
+
+     A title MUST be a sentence a user would say, never a system term. G3 asks this as a starred
+     question.
+
+     `critical` is yes ONLY when the use case touches money, personal data, or an irreversible action.
+     Nothing else. If more than a third of this component's use cases are marked, the definition was
+     misapplied — derive it again rather than negotiating it.
+
+     `critical` decides something only at mode: deep, where every critical UC gets a full flow. -->
+
+| id | Use case | Actor | Satisfies | critical |
+| --- | --- | --- | --- | --- |
+| UC-{n} | {a sentence a user would say} | {from the Actor Register} | {FR-n} | tidak |
+
+## Constraints · [G3]
+
+<!-- What this component MUST work within, and where each comes from — a business rule, a regulation,
+     an external system, an applied DEC-, an AD-N. A constraint with no source is an assumption in
+     disguise; file it through wdi-question instead. -->
+
+## Non-Goals · [G3]
+
+<!-- What this component explicitly does NOT do, and which component does it instead. This does more
+     work than it looks: it is what stops the next builder adding a nearby thing here. -->
+
+## Prerequisite · [G3]
+
+<!-- What MUST already exist before this component can behave as described — another component, an
+     external system, a dataset, a credential. A prerequisite waiting on somebody outside belongs in
+     .control/questions/external.md, and that file holds go-live only, never a design gate. -->
+
+## Success Signal · [G3]
+
+<!-- How we will know this component works — observable, not aspirational. Scales with stakes: a
+     sentence for a small component, a measure with a target for one touching money or personal data. -->
+
+## Assumptions, Risks, and To Be Confirmed · [G3]
+
+<!-- THREE separate lists, and collapsing them loses the owner. An assumption is something we decided
+     to believe; a risk is something that may go wrong; a to-be-confirmed is a question with an owner.
+
+     Every to-be-confirmed MUST be filed through wdi-question before the gate opens — into
+     assumptions.md by default, blocking.md only through the three tests that file states. -->
+
+### Assumptions
+
+### Risks
+
+### To Be Confirmed
+
+## Gate Checklist · [G3]
+
+<!-- The gate questions as they apply to THIS component, answered ya / tidak / ubah. The full list
+     lives in delivery-flow-guide.md and MUST NOT be copied here. At mode: catalog only the starred
+     questions are asked. -->
+
+## Design Reference · [G3]
+
+<!-- One line pointing at the paired SDD, plus any AD-N or applied DEC- that binds this component.
+     Nothing else — solution shape MUST NOT appear in this document: no framework, no table, no
+     endpoint, no class, no queue, no file path. -->
+
+---
+
+## Slots
+
+<!-- All slot content is [G4], written by wdi-component intent `behaviour` and only as deep as the
+     component's mode. At catalog every slot stays empty, and that is a finished state.
+
+     Content SHOULD stay in this kernel until the file grows past roughly 400 lines — a suggestion,
+     not a threshold. When it must split, the FIRST slot broken out SHOULD be 04-usecases/.
+
+     The numbers are READING ORDER, not classification. This is the opposite of .how/<pc>/, where
+     01-06 classify by ABCE. The two MUST NOT be conflated.
+
+     02-rules/       rules-<pc>.md — business rules binding ONLY this component. From mode: outline.
+                     A rule that turns out to bind a second component is PROMOTED to
+                     .what/business-rules.md through wdi-blueprint, never copied
+     03-domain/      domain-model.md — entities, relations, columns. [G3], exists at every mode.
+                     state-machines.md — from mode: deep only.
+                     NOT a database schema; column types MUST NOT appear here
+     04-usecases/    UC-<n>-<slug>.md, one file per full flow. At most 3 at outline and guarded;
+                     every critical UC at deep. At most EIGHT steps each — a flow needing more is
+                     either two use cases or has started describing implementation
+     05-scenarios/   SCN-<nn>-<slug>.md, long branches hanging off one UC. From mode: deep only
+
+     01-requirements/ and supplements/ are REPEALED. The first was permanently empty — FR live in the
+     PRD and this document cites them by id. The second existed for the ANX- concept, which is gone. -->
+
+## Open Items
+
+<!-- Anything still unresolved, each pointing at its row in .control/questions/. An assumption left
+     here with no id is the failure wdi-question exists to prevent. -->

package/kit/.constitution/document/templates/structure-codebase.md

@@ -0,0 +1,129 @@
+---
+type: structure
+scope: codebase
+verified: '{YYYY-MM-DD}'      # the day the tree was actually read
+commit: '{sha}'               # the commit it was read at — staleness is measured against this
+---
+
+# Codebase Structure
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     This file is DESCRIPTIVE. It states what the code tree looks like today. It MUST NOT carry
+     naming rules (conventions-guide.md), versions (stack-guide.md), or ratified legacy shapes
+     (brownfield-guide.md) — reference them instead.
+
+     Written and refreshed only by `wdi-init` intent `structure`, never by hand. Rules for both maps live in
+     .constitution/structure-guide.md.
+
+     THE SHAPE: annotated trees, not prose. Folders are complete; files are marked ★ inline and only
+     when they earn it. A tree that lists every file is unmaintainable, and an unmaintainable map
+     stops being read — that is how every source-tree document before this one died.
+
+     THREE SECTIONS, and the split is by DEPLOYABILITY, not by size or importance:
+       Top level   every base folder in the repo root
+       Container   runs or deploys on its own — the same word C4 L2 and components.yaml use
+       Library     an includable artifact — compiled or imported into something else, never run
+
+     "Container" is the kit's word, defined in templates/c4.md and carried by every LC's `container`
+     field. It MUST NOT be swapped for "application", "service", or "app" here — a synonym for a
+     term that already has a glossary entry is drift, and `wdi-reconcile` hunts for it. It does not
+     mean a Docker image; packaging is a separate question.
+
+     A unit that is neither is not a unit; it stays a line in Top level. When a unit stops being
+     separately deployable, it MUST move sections rather than keep its old heading. -->
+
+## Verified
+
+<!-- One line: date, commit SHA, and how the tree was read. If the commit is no longer an ancestor
+     of HEAD, this map is stale and MUST be refreshed before a gate reads it. -->
+
+## Top level
+
+<!-- Every base folder in the repo root, COMPLETE — including the dull ones. An unlisted folder is
+     the one people misuse, because nothing told them what it was for. Tag each entry so the two
+     sections below are predictable: [container] · [lib] · [docs] · [tooling] · [generated]. One
+     line of purpose per entry; no second line. -->
+
+```text
+{repo-root}/
+├── {unit}/                   # [container] what it is answerable for
+├── {unit}/                   # [lib] ...
+└── {folder}/                 # [docs] ...
+```
+
+## Containers
+
+<!-- One subsection per unit that runs or deploys on its own. Repeat the block below verbatim per
+     unit; if there is only one, there is still a subsection — a repo grows a second container
+     without warning.
+
+     Heading names MUST match the `container` values used in components.yaml, so an LC's container
+     can be checked against this map instead of trusted. A container with no code in this repo MUST
+     NOT get a subsection — it belongs to c4-l2-containers.md. A folder that builds more than one
+     container MUST say which. -->
+
+### {container}
+
+<!-- One line: what it is, and how it ships. Then the tree: folder convention first, ★ on the files
+     that earn it. Descend only until directories stop carrying distinct roles, and describe a
+     repeating shape ONCE with a placeholder such as <feature>/ rather than per instance. -->
+
+```text
+{container}/
+├── {entry-file}              # ★ ENTRY: what execution actually does first
+├── {folder}/                 # convention: what belongs here
+│   └── {file}                # ★ why this one is key
+└── {folder}/<feature>/       # the shape every feature repeats
+    ├── {sub}/                #   what goes in it
+    └── {sub}/                #   ...
+```
+
+<!-- One line, only when the unit has one: the authoritative call direction through those folders.
+     A builder who gets this wrong writes code that works and is still wrong. Cut if there is none;
+     do not invent one to fill the slot. -->
+
+**Flow:** {layer} → {layer} → {layer}
+
+## Libraries
+
+<!-- One subsection per includable artifact — compiled into or imported by something else, never
+     deployed on its own. A library is deliberately NOT a container, and MUST NOT appear at C4 L2.
+
+     Same block shape as a container, minus the entry point: a library that has one is a container
+     wearing the wrong label. -->
+
+### {library}
+
+<!-- One line: what it holds, and who consumes it. Then the annotated tree. -->
+
+```text
+{library}/
+├── {folder}/                 # convention: what belongs here
+│   └── {file}                # ★ why this one is key
+└── {folder}/
+```
+
+**Consumed by:** {units}
+
+## Generated
+
+<!-- Anything not written by hand, with its generator: codegen output, vendored trees, migration
+     snapshots. A generated folder edited by hand is a defect, so it MUST be named here even when it
+     looks like ordinary source. Cut the section if there is none. -->
+
+| Path | Generated by |
+| --- | --- |
+
+## Unclaimed
+
+<!-- Folders that exist but no one can state a purpose for. These are findings, not layout. Leave
+     them here, named, until they are claimed or deleted — inventing a purpose to empty this section
+     is the failure mode it exists to catch. Cut the section only when it is genuinely empty. -->
+
+---
+
+<!-- Keep this legend last, and keep it one line. -->
+
+★ = key file: entry point, wiring root, the single place a rule is enforced, or a file that must be
+opened before behaviour in its folder can be changed.

package/kit/.constitution/document/templates/structure-document.md

@@ -0,0 +1,90 @@
+---
+type: structure
+scope: document
+verified: '{YYYY-MM-DD}'      # the day the tree was actually read
+commit: '{sha}'               # the commit it was read at — staleness is measured against this
+---
+
+# Document Structure
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     This file is DESCRIPTIVE. It states which parts of the corpus actually carry content today.
+     The layers themselves, the placement test, the naming scheme, and slot numbering all belong to
+     corpus-guide.md and MUST NOT be restated here.
+
+     Written and refreshed only by `wdi-init` intent `structure`, never by hand. Rules for both maps live in
+     .constitution/structure-guide.md.
+
+     Same shape as the codebase map: annotated trees, folders complete, ★ inline on the documents
+     that earn it. What differs is the split — the codebase map splits by deployability, this one
+     splits by LAYER, because that is the axis a reader is lost on.
+
+     The five roots are fixed, so the top-level tree is not a discovery. Which sub-folders carry
+     content, which Product Component folders exist, and which slots have been split out of a kernel
+     ARE, and that is what this map is for. -->
+
+## Verified
+
+<!-- One line: date, commit SHA, and how the tree was read. If the commit is no longer an ancestor
+     of HEAD, this map is stale and MUST be refreshed before a gate reads it. -->
+
+## Top level
+
+<!-- The five roots, one line each, with the state of each: populated, or still empty. Mark an empty
+     root as empty rather than dropping it — a dropped root reads as a root that does not exist. -->
+
+```text
+.constitution/                # how we work — {state}
+.control/                     # what currently holds — {state}
+.what/                        # what was promised — {state}
+.how/                         # how it is built — {state}
+_bmad-output/                 # work in progress, not curated — {state}
+```
+
+## Per layer
+
+<!-- One subsection per root that carries content. Annotated tree: sub-folders complete, ★ on the
+     single-copy documents a reader must find first. Per-Product-Component folders are NOT expanded
+     here — the table below owns them, and expanding both means maintaining both. -->
+
+### {layer}
+
+```text
+{layer}/
+├── {folder}/                 # what belongs here
+│   └── {file}                # ★ why this one is key
+└── {folder}/                 # {state}
+```
+
+## Product Components
+
+<!-- One row per PC that actually exists. Both sides are expected: a PC with an SRS and no SDD, or
+     the reverse, is drift and MUST be listed under Findings rather than normalised here. List only
+     the slots that have been split out of a kernel; empty slots stay unlisted. -->
+
+| Product Component | `.what/<pc>/` | `.how/<pc>/` | Slots split out |
+| --- | --- | --- | --- |
+
+## Registries and generated
+
+<!-- Which registry files carry entries and which are still empty skeletons, and which generated
+     tables have been produced. Generated output is never written by hand; naming it here is what
+     makes a hand edit visible. -->
+
+| File | State |
+| --- | --- |
+
+## Findings
+
+<!-- Drift this map surfaced while being derived: a PC on one side only, a supplement with no
+     citation, a folder outside the five roots, a document whose home contradicts corpus-guide.md.
+     Findings are reported, never fixed here — fixing them is `wdi-reconcile` work, or the owning
+     skill's.
+     Cut the section only when it is genuinely empty. -->
+
+---
+
+<!-- Keep this legend last, and keep it one line. -->
+
+★ = key document: single-copy, referenced from elsewhere, or the first thing a reader must find.

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

@@ -0,0 +1,69 @@
+---
+type: uc
+id: UC-{NN}                  # allocated from .control/registry/usecases.yaml
+component: '{pc}'
+satisfies: []                # FR ids — V2 checks every FR has at least one UC
+critical: false              # true ONLY when it touches money, personal data, or an irreversible
+                             # action. Nothing else — the two elastic criteria are repealed
+created: '{YYYY-MM-DD}'
+---
+
+# UC-{NN} — {a sentence the user would say}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     THE TITLE RULE, and G3 asks it as a starred question: the title MUST be a sentence a user would
+     actually say — "Mendaftar lewat tautan sponsor" — and MUST NOT be a system term — "Referral
+     attribution handler". A system-shaped title means the functional analysis has already leaked
+     into design.
+
+     WHICH USE CASES GET ONE OF THESE FILES IS DECIDED BY `mode`, NOT BY `critical`:
+       catalog            none. The catalogue line in the SRS is the whole record
+       outline · guarded  the use cases the component exists for, AT MOST 3
+       deep               every UC marked `critical`
+     `critical` therefore decides something only at `deep`. Everywhere else it is a label the estimate
+     and the review read, and it MUST NOT be used to justify writing a file the mode does not ask for.
+
+     At most EIGHT steps in the Basic Flow. A flow needing more is either two use cases, or it has
+     started describing implementation. -->
+
+## Trigger
+
+<!-- What starts this. An actor doing something, a schedule, or an external event. -->
+
+## Precondition
+
+<!-- What MUST already be true. Authentication state, prior data, prior status. -->
+
+## Main Flow
+
+<!-- Numbered, one step per line, alternating actor and system. Keep to the happy path — branches
+     go below or, if long, into a SCN- file in 05-scenarios/. No screen names, no endpoints, no
+     table names: this is behaviour, not design. -->
+
+1.
+2.
+
+## Alternate Flows
+
+<!-- Branches that still end in success. Reference the main-flow step they leave from. -->
+
+| From step | Condition | What happens |
+| --- | --- | --- |
+
+## Failure Flows
+
+<!-- Branches that end without the goal. For a `critical` UC this section MUST answer "what happens
+     if it fails halfway" — the paired SDD carries the technical side of the same question. -->
+
+| From step | Failure | What the system does | What the user is left with |
+| --- | --- | --- | --- |
+
+## Outcome
+
+<!-- The state the system and the user are left in when the main flow completes. -->
+
+## Business Rules
+
+<!-- BR ids that govern this use case, referenced not restated. The rules themselves live in
+     02-rules/. -->

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

@@ -0,0 +1,77 @@
+---
+type: ux
+component: '{pc}'
+document: design             # design (.how/<pc>/01-ux/) · experience (.what/<pc>/04-usecases/)
+created: '{YYYY-MM-DD}'
+updated: '{YYYY-MM-DD}'
+---
+
+# {DESIGN | EXPERIENCE} — {Product Component}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     bmad-ux produces TWO documents, and they fall in two different layers. This template covers
+     both; set `document` and keep only that half.
+
+       DESIGN.md      → .how/<pc>/01-ux/          visual: tokens, components, layout
+       EXPERIENCE.md  → .what/<pc>/04-usecases/   behaviour: IA, states, journeys, accessibility
+
+     Keeping them in one file — as most projects do — makes a button-colour change and a flow change
+     look equally weighty. They are not.
+
+     Neither lands by itself. bmad-ux writes to _bmad-output/ux/ and wdi-ux lands it. Base
+     tokens and shared elements do NOT stay per-component; they go to
+     .how/_platform/design-system.md. -->
+
+## DESIGN — visual
+
+<!-- Keep only when document: design. -->
+
+### Tokens
+
+<!-- What is component-specific. Anything reusable MUST be promoted to design-system.md instead —
+     a token defined twice is a token that will diverge. -->
+
+### Screens
+
+<!-- One row per screen. Each MUST be registered as an LC of type ui-screen in components.yaml —
+     wdi-ux does this in the same act as landing the screen, and V12 checks it at wave close. -->
+
+| Screen | LC | Purpose |
+| --- | --- | --- |
+
+### Layout and states
+
+<!-- Per screen: the states it can be in — empty, loading, error, populated. The empty and error
+     states are the ones that get skipped and the ones users hit first. -->
+
+---
+
+## EXPERIENCE — behaviour
+
+<!-- Keep only when document: experience. This half is WHAT, not HOW: it says what the user can do
+     and what the system answers, in human language, with no visual detail. -->
+
+### Information architecture
+
+<!-- Top-level surfaces and how someone moves between them. -->
+
+### Journeys
+
+<!-- Reference UJ-N from the PRD rather than restating them; add only what the PRD left implicit —
+     screen order, entry state, what tells the user the value landed. -->
+
+### Behaviour per surface
+
+| Surface | User can | System answers |
+| --- | --- | --- |
+
+### Accessibility
+
+<!-- What MUST hold: contrast, focus order, target size, screen-reader labelling, motion. State the
+     standard being met, not the intention to meet one. -->
+
+### Edge cases
+
+<!-- Real failure moments and what the user does next. One per row; the ones worth writing are the
+     ones a designer would rather not think about. -->