Add Design Intent Governance

AGENTS.md

@@ -14,12 +14,15 @@ Read in this order before making decisions:
 6. `guide/intent-specification-layer.md`
 7. `guide/spec-review-loop.md`
 8. `guide/spec-to-test-bridge.md`
-9. The relevant template or example for the task
+9. `guide/intent-to-ui-translation.md` (when the task touches user-facing surfaces)
+10. The relevant template or example for the task
 
 For a compact workflow after this file, use
 `guide/agent-operating-protocol.md`.
 For method updates or upstream rule propagation, also read
 `guide/method-update-propagation.md`.
+For user-facing surfaces and design translations, also read
+`spec/features/design-intent-governance/spec.md`.
 
 ## Non-Negotiable Rules
 

CHANGELOG.md

@@ -2,6 +2,38 @@
 
 This project follows the spirit of Keep a Changelog.
 
+## [Unreleased]
+
+### Added
+
+- New `spec/features/design-intent-governance/spec.md` defining
+  `REQ-DESIGN-GOV-001..007` — story-class classification (`user` / `system` /
+  `mixed` / `method`), intent-to-UI design translation, `governingSpec`
+  frontmatter, trail vs authority for design references, and design-spec
+  coupling enforcement.
+- New `guide/intent-to-ui-translation.md` explaining the UI object tree (region
+  → element → variant → property), fit judgments (`fit` / `weak` / `drift` /
+  `violation` / `not_applicable`), and drift sources (`wrong_intent` /
+  `missing_intent` / `weak_translation` / `wrong_implementation` /
+  `missing_evidence` / `decision_gap`).
+- New `templates/user-design-translation.md` for hand-authored design
+  translations.
+- New `examples/design-intent-translation/` worked example (checkout review
+  surface) showing file-level `storyClass`, per-REQ override, paired translation
+  with `governingSpec`, and property fit matrix.
+- New `scripts/check-design-spec-coupling.mjs` enforcing that a design
+  translation change is paired with a change in at least one declared
+  `governingSpec` file or carries `noIntentChange: true` in a commit message.
+- AGENTS.md load order extended with `intent-to-ui-translation.md` for
+  user-facing surface tasks.
+
+### Changed
+
+- README.md and `spec/README.md` indexed the new design intent governance
+  surfaces.
+- ROADMAP.md 0.3 milestone records the Design Intent Governance addition,
+  field-validated by a real-world adoption in 2026-05.
+
 ## [0.2.4] - 2026-05-15
 
 ### Changed

README.md

@@ -148,6 +148,7 @@ agent is unsure whether to update the spec, code, tests, or review ledger.
 - [Adoption playbook](guide/adoption.md)
 - [Spec review loop](guide/spec-review-loop.md)
 - [Spec-to-test bridge](guide/spec-to-test-bridge.md)
+- [Intent to UI translation](guide/intent-to-ui-translation.md)
 - [Naming and structure decision](guide/naming-and-structure.md)
 - [Research notes](research/method-comparison.md)
 - [References](references.md)

ROADMAP.md

@@ -15,6 +15,10 @@
 
 ## 0.3
 
+- Land Design Intent Governance (`spec/features/design-intent-governance/`,
+  `guide/intent-to-ui-translation.md`, `templates/user-design-translation.md`,
+  `examples/design-intent-translation/`, `scripts/check-design-spec-coupling.mjs`)
+  validated by real-world adoption in 2026-05.
 - Add real-world adoption reports.
 - Add negative examples showing over-specification.
 - Add translations after the English canonical text stabilizes.

examples/design-intent-translation/README.md

@@ -0,0 +1,51 @@
+# Design Intent Translation Example
+
+This small example shows how to bridge an L2 spec to a concrete UI property
+translation using the method defined in
+[`spec/features/design-intent-governance/`](../../spec/features/design-intent-governance/).
+
+It deliberately uses a generic, non-Buzyrun domain (a coupon order checkout
+review surface) so the pattern transfers to other projects.
+
+## Files
+
+| File | Role |
+|---|---|
+| [`feature-spec.md`](feature-spec.md) | Minimal L2 feature spec with `storyClass: user` and one `mixed` REQ override |
+| [`translations/checkout.review.design.md`](translations/checkout.review.design.md) | Hand-authored property-level design translation paired with the spec |
+
+## What this example demonstrates
+
+1. **File-level `storyClass`** in the feature spec frontmatter sets the
+   default for all REQs in the file.
+2. **Per-REQ `storyClass:` override** for one system-side REQ (`REQ-CHK-002`,
+   inventory recheck) inside an otherwise `user` file.
+3. **`governingSpec:` in the translation frontmatter** points back to the
+   spec files that authorize the translation.
+4. **UI object tree → property fit matrix** records concrete `fit`/`weak`/
+   `drift` judgments per UI leaf — not the surface as a whole.
+5. **Residual gaps** are tagged with a drift source so the fix target is
+   unambiguous (`spec`, `design`, `code`, or `evidence`).
+
+## What this example does NOT do
+
+- Define a design system (tokens, components). Projects supply their own.
+- Mandate a per-route ledger format. The Buzyrun project layers a generated
+  `surface-ledgers/` set on top of the same governance; that is a project
+  choice, not a method requirement.
+- Provide screenshots or evidence files. Evidence is project-local.
+
+## How a real project layers on top
+
+The Buzyrun Flutter project (the real-world adoption that validated this
+governance in 2026-05) extends this example with:
+
+- A per-route authority registry that generates one Design Visual ledger per
+  route as a *coverage* artifact (`docs/design/v3/governance/surface-ledgers/`).
+- Hand-authored translations for high-priority surfaces (~10 surfaces) that
+  carry property-level `fit` judgments.
+- A coupling check (`scripts/check-design-spec-coupling.mjs`) registered in
+  the project's `check:spec` aggregate.
+
+Other projects can adopt any subset. The minimum is the `governingSpec:`
+frontmatter and one translation per accepted user-facing L2 scope.

examples/design-intent-translation/feature-spec.md

@@ -0,0 +1,71 @@
+---
+id: SPEC-CHECKOUT-REVIEW
+title: Checkout Review Surface (example)
+status: active
+owners: [example]
+updated: 2026-05-27
+layers: [L2]
+storyClass: user
+---
+
+# Checkout Review Surface Spec (example)
+
+A small example feature spec used by
+[`examples/design-intent-translation/`](README.md). It governs the order
+review surface a shopper sees after applying a coupon, before final payment.
+
+## Scope
+
+User-facing review surface only. Coupon application logic, payment
+authorization, and inventory persistence live in other specs.
+
+## Layer 2: Behavior Spec
+
+- [REQ-CHK-001][State-driven] While the order is in `draft` state with at
+  least one line item, the system shall display the order total, the applied
+  coupon (if any), each line item's name and price, and a primary action that
+  proceeds to payment.
+- [REQ-CHK-002][Ubiquitous] The system shall re-fetch inventory state for
+  each line item when the review surface opens, before computing the displayed
+  total.
+
+  ```yaml
+  id: REQ-CHK-002
+  type: ubiquitous
+  storyClass: system
+  ```
+
+- [REQ-CHK-003][Event-driven] When the shopper changes the coupon while in
+  `draft`, the system shall recompute and re-render the total without
+  resetting other review state.
+- [REQ-CHK-004][Unwanted] If the order total computation fails (network or
+  service error), then the system shall preserve the entered review state and
+  surface an actionable retry — it shall not silently replace the displayed
+  total with stale or zero values.
+- [REQ-CHK-005][Unwanted] If a line item's inventory has dropped to zero
+  between cart and review, then the system shall mark that line item with an
+  out-of-stock visual treatment, exclude it from the total, and require the
+  shopper to remove or replace it before the primary action becomes
+  available.
+
+## Verification Map
+
+| Requirement / statement | Verification type | Evidence target | Execution / record | Status |
+|---|---|---|---|---|
+| REQ-CHK-001:S1 | unit + widget | review surface render in `draft` | project tests | unverified (example) |
+| REQ-CHK-002:S1 | integration | inventory recheck on open | project tests | unverified (example) |
+| REQ-CHK-003:S1 | widget | coupon change recompute | project tests | unverified (example) |
+| REQ-CHK-004:S1 | widget | actionable retry on total failure | project tests | unverified (example) |
+| REQ-CHK-005:S1 | widget + integration | out-of-stock visual + gated CTA | project tests | unverified (example) |
+
+## Notes for example readers
+
+- The file declares `storyClass: user` in frontmatter — most REQs in this
+  file render on the user-facing review surface.
+- `REQ-CHK-002` (inventory recheck) is server-side work with no user-visible
+  surface of its own. It overrides the file default with
+  `storyClass: system`, so the design translation does not need to map a UI
+  property for it. Its *effect* (out-of-stock state) appears in `REQ-CHK-005`
+  and is translated there.
+- The translation file (`translations/checkout.review.design.md`) lists this
+  spec in `governingSpec` so the coupling check links them.

examples/design-intent-translation/translations/checkout.review.design.md

@@ -0,0 +1,126 @@
+---
+id: EXAMPLE-DESIGN-TRANSLATION-CHECKOUT-REVIEW
+title: Design Translation — checkout.review (example)
+status: example
+owners: [example]
+updated: 2026-05-27
+governingSpec: [examples/design-intent-translation/feature-spec.md]
+---
+
+# Design Translation: checkout.review (example)
+
+A minimal hand-authored design translation paired with
+[`feature-spec.md`](../feature-spec.md). See the upstream
+[`templates/user-design-translation.md`](../../../templates/user-design-translation.md).
+
+## 1. Authority
+
+| Field | Value |
+|---|---|
+| Story class | `user` |
+| Governing L0 | The project's value statement against silent failure during checkout (project-local). |
+| Governing L1 | `order.state = draft`, `line_item`, `coupon`, `total_amount` |
+| Governing L2 | `REQ-CHK-001`, `REQ-CHK-003`, `REQ-CHK-004`, `REQ-CHK-005` |
+| Governing L3 | none for this example |
+| Surface / story | `checkout.review` |
+| Route / screen | `/checkout/review`, `screens/checkout/ReviewScreen` (project-local) |
+
+`REQ-CHK-002` is declared `storyClass: system` in the spec and intentionally
+absent from this translation — it has no UI property of its own.
+
+## 2. User outcome
+
+```text
+The shopper understands what they are about to pay for and why, can adjust
+the coupon without losing context, and is never silently routed past an
+out-of-stock line item or a failed total computation.
+```
+
+## 3. Design obligations
+
+| Obligation ID | Source intent | UI obligation |
+|---|---|---|
+| `OBL-CHK-CLARITY` | `REQ-CHK-001` | The total, the applied coupon (if any), each line item's name and price, and the primary action must be visible without scrolling on a standard-height viewport. |
+| `OBL-CHK-COUPON-CHANGE-PRESERVE` | `REQ-CHK-003` | Changing the coupon must recompute the total in place and leave other review state intact (selected delivery option, gift note, etc.). |
+| `OBL-CHK-FAIL-RECOVER` | `REQ-CHK-004` | A failed total computation must show an actionable retry on the surface — never a silent zero or stale total. |
+| `OBL-CHK-OOS-VISIBLE` | `REQ-CHK-005` | Out-of-stock line items must carry a distinct visual treatment, must be excluded from the total, and must gate the primary action until removed or replaced. |
+
+## 4. UI object tree
+
+```text
+checkout.review
+  header
+    title.copy
+  line_items
+    line_item
+      name.copy
+      price.copy
+      qty.copy
+      oos_badge (variant)
+        copy
+        colorToken
+        position
+      remove.action
+      replace.action
+  coupon_block
+    applied_state (variant)
+      label.copy
+      change.action
+    none_state (variant)
+      apply.action
+  total
+    label.copy
+    amount.copy
+    fail_state (variant)
+      detail.copy
+      retry.action
+  primary_action
+    label.copy
+    enabled_state (variant)
+    disabled_state (variant)
+      reason.copy
+```
+
+## 5. Domain state to UI property mapping
+
+| Domain state | Expected copy | Expected color token | Expected position | Expected action | Current fit |
+|---|---|---|---|---|---|
+| `draft + all_in_stock + total_ok` | total amount + "Pay now" label | primary | bottom | proceed to payment | `fit` |
+| `draft + any_oos` | "Remove or replace to continue" reason copy | warning | inline on the line item | remove / replace | `weak` |
+| `draft + total_fail` | "We couldn't compute your total" + actionable detail | error | inline above primary action | retry | `weak` |
+| `coupon_applied` | coupon label + change action | accent | next to total | change coupon | `fit` |
+| `coupon_none` | "Have a coupon?" prompt | neutral | next to total | apply coupon | `fit` |
+
+## 6. Interaction and recovery mapping
+
+| EARS statement | Trigger / state | UI feedback | Recovery | Evidence |
+|---|---|---|---|---|
+| `REQ-CHK-001:S1` | Surface open | render full review | back navigates to cart | project widget test |
+| `REQ-CHK-003:S1` | Coupon change | recompute + re-render total only | other state preserved | project widget test |
+| `REQ-CHK-004:S1` | Total fetch fails | `fail_state` variant visible | retry action triggers refetch; total area is never silently zero | project widget test |
+| `REQ-CHK-005:S1` | Line item OOS | `oos_badge` visible + primary action disabled with reason | shopper removes or replaces | project integration test |
+
+## 7. UI property fit matrix
+
+| UI node | Property | Expected from intent | Current actual (example) | Fit | Fix target |
+|---|---|---|---|---|---|
+| `line_items.line_item.oos_badge` | colorToken | distinct from neutral and accent (warning family) | uses generic neutral badge | `weak` | design |
+| `total.fail_state.retry` | label | result-naming verb ("Try again", not "OK") | "Retry" generic | `weak` | design |
+| `primary_action.disabled_state.reason` | copy | explains which line item is blocking | absent (generic disabled) | `drift` | design + code |
+| `coupon_block.applied_state.change` | action target | opens coupon picker without resetting other review state | unknown without project audit | `missing_evidence` | evidence |
+
+## 8. Evidence
+
+| Evidence type | Path or record | Status |
+|---|---|---|
+| widget test | project-local | `absent` (example only) |
+| visual audit | project-local | `absent` (example only) |
+| accessibility | project-local | `absent` (example only) |
+
+## 9. Residual gaps
+
+| Gap ID | Label | Cause (drift source) | Next action |
+|---|---|---|---|
+| `GAP-CHK-001` | OOS badge tonal weight unclear | `weak_translation` | Define a warning-family token in the project design system |
+| `GAP-CHK-002` | Primary action's disabled reason missing | `drift` due to `wrong_implementation` | Wire the reason copy from the spec's OOS state into the disabled tooltip |
+| `GAP-CHK-003` | No coupon-picker re-entry audit | `missing_evidence` | Add a widget test that asserts non-coupon review state is preserved across coupon change |