wdi-method 0.6.30 → 0.6.32

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

@@ -1,66 +1,96 @@
----
-type: design-system
-scope: _platform
-status: draft            # draft · reviewed · locked · superseded
-created: '{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 ../../../project/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. -->
+---
+type: design-system
+scope: _platform
+landed_from: []          # the run file(s) in _bmad-output/ux/ this landed from — provenance, kept after the run is gone
+status: draft            # draft · reviewed · locked · superseded
+created: '{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 product-level DESIGN — tokens, base elements, and every build pattern
+     that holds for all components.
+
+     WHAT DOES NOT BELONG HERE: a promise. Information architecture, voice and tone, the flow map,
+     journeys that cross components, and shared edge cases are still true after a redesign, so they
+     are experience and live in .what/experience.md (templates/experience.md). A section that holds
+     both is split at the sentence — ux-guide.md § Product level.
+
+     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/ of the component that holds its implementation, not here — unless
+     nearly every component uses it, and then it is a base element. -->
+
+| 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. -->
+
+## State patterns
+
+<!-- How empty, loading, error, offline, and disabled are BUILT everywhere. The promise a state keeps
+     is in .what/experience.md; this section is how it is met. -->
+
+| State | Built as | Used by |
+| --- | --- | --- |
+
+## Interaction primitives
+
+<!-- Gestures, feedback, confirmation, undo — the few moves every screen shares. -->
+
+## Accessibility — how it is met
+
+<!-- The standard met is a promise and lives in .what/experience.md. Here: contrast pairs, target
+     sizes, focus order, motion — each resolving to a token or an element above. -->
+
+## Surfaces that are not screens
+
+<!-- Notifications, widgets, share sheets: how each looks and is built. What the user is told, and
+     when, is in .what/experience.md. -->
+
+## 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 ../../../project/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/method/document/templates/experience.md

@@ -0,0 +1,62 @@
+---
+type: experience
+scope: product
+landed_from: []          # the run file(s) in _bmad-output/ux/ this landed from — provenance, kept after the run is gone
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+---
+
+# Experience — {product}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Home: .what/experience.md. Written by wdi-ux, landed from a bmad-ux run at G2 — its path has no
+     <pc>, so it does not wait for components. Optional, like the rest of UX.
+
+     WHAT IT IS: the product-level half of EXPERIENCE. What holds for EVERY component, in the promise
+     layer. One component's own journeys stay in .what/<pc>/04-usecases/EXPERIENCE.md.
+
+     THE TEST, per sentence: still true after a full redesign → here. Names a layout, a component,
+     or a token → .how/_platform/design-system.md. ux-guide.md § Product level maps bmad-ux's sections
+     onto the two files.
+
+     A cross-component rule the SYSTEM enforces — not what the user perceives — is a business rule,
+     and belongs in .what/business-rules.md instead. -->
+
+## Foundation
+
+<!-- Who it is for, and the few principles every surface keeps. Each principle MUST be checkable: a
+     principle no screen could violate is a slogan. -->
+
+## Information architecture
+
+<!-- The product's surfaces and how someone moves between them. A component's inner surfaces belong to
+     that component's EXPERIENCE.md. -->
+
+## Voice and tone
+
+<!-- How the product speaks. User-facing nouns MUST match .control/product-glossary.md where an entry
+     exists. -->
+
+## Flow map
+
+<!-- The whole map, across components. Each zoom-in lives with the component that owns the screens in
+     it — ux-guide.md § Product level. Reference UJ-N and UC-N by id. -->
+
+## Cross-component journeys
+
+<!-- A journey that crosses components — onboarding is the usual one — told once, here, with the
+     components it passes through named in order. -->
+
+## Promises every surface keeps
+
+<!-- The promise side of state patterns, accessibility, and surfaces that are not screens: what the
+     user can count on everywhere. HOW each is met is design-system.md. -->
+
+| Promise | Holds for |
+| --- | --- |
+
+## Shared edge cases
+
+<!-- Failure moments that are not one component's: offline, a lost session, an interrupted sync. What
+     the user does next. -->

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

@@ -1,129 +1,131 @@
----
-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/method/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.
+---
+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/method/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. The headings are exactly the `built: true`
+     containers WITHOUT `repo:` — `container-built` checks it. A container whose code is in another
+     repository carries `repo:` in components.yaml and gets its subsection in THAT repo's map; one
+     that is ours but has no code yet still gets a subsection, one line saying so. 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.