aw-spec-cli 0.1.7 → 0.1.9

package/assets/.appweaver/templates/spec-template.md

@@ -0,0 +1,309 @@
+# Specification: [AGGREGATE]
+
+**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
+
+**Spec home**: `specs/[Aggregate]/`
+
+**Version**: v1.0   <!-- living truth; every applied change request bumps this — see Change History -->
+
+**Status**: Draft
+
+**Input**: User description: "$ARGUMENTS"
+
+<!--
+  AGGREGATE = FEATURE. This spec covers ONE aggregate (e.g. Order) and is the
+  single LIVING source of truth for its whole lifecycle. Every operation on it
+  (CreateOrder, UpdateOrder, …) is a USER STORY below — NOT a separate feature.
+  A later requirement is a new US-n added here as a delta (see .appweaver/changes/
+  and delta-spec-template.md), never a new spec folder. One spec + one design.md
+  (specs/[Aggregate]/design.md) — the DESIGN derives from THIS document.
+
+  Section order is intentional: establish the business need and scope, then the
+  stable core the aggregate IS (requirements → rules → constraints → entities →
+  data classification → integration contracts → experience standards → edge cases),
+  then the prioritized user journeys that exercise it, then measurable success.
+
+  LIFTS (specify's job): four sections carry governance INTO the spec, because every
+  later phase authors from the spec ONLY and anything not captured here never reaches
+  it. Three lift the DOMAIN rules — Constraints & NFRs (CN-), Data Classification
+  (DC-), Integration Contracts (IC-). The fourth, Experience Standards (UX-), lifts
+  the frontend lane's constitution and its ux/ rules, and is what the UI lane authors
+  and verifies against. Fill each when its rules apply; keep it (empty → "None")
+  otherwise — the section is always present, only its content is conditional.
+-->
+
+## Business Need
+
+<!--
+  ACTION REQUIRED: Why this aggregate exists — the problem, the affected users,
+  and the value delivered. Business-facing; no implementation detail.
+-->
+
+[The problem this aggregate solves, who it serves, and the value it delivers.]
+
+## Scope & Assumptions
+
+### Aggregate Boundary
+
+<!--
+  The aggregate = the largest slice whose code no other feature owns. State what
+  it OWNS, what it only REFERENCES (by identifier, not owned), and what is out of
+  scope. This anchors the design's "dependencies point inward" and keeps commands
+  as deltas on THIS aggregate rather than new features.
+-->
+
+- **Owns**: [entities/behaviour inside this aggregate — e.g. Order, OrderLine]
+- **References (by id, not owned)**: [Customer, Product — read-only / by identifier]
+- **Out of scope / non-goals**: [explicitly excluded — e.g. payment settlement, shipping]
+
+### Assumptions
+
+<!--
+  Reasonable defaults chosen where the description was silent, plus dependencies
+  on existing systems/services.
+-->
+
+- [Assumption about target users, e.g., "Users have stable internet connectivity"]
+- [Assumption about scope, e.g., "Mobile support is out of scope for v1"]
+- [Dependency on an existing system/service, e.g., "Requires the existing user-profile API"]
+
+### Experience Scope
+
+<!--
+  The experience envelope this aggregate is specified against: WHO reaches it through a
+  UI, THROUGH WHAT, and the floor the frontend lane has to hold. Scope, not requirement —
+  it bounds what the Experience Standards and the prototype are held to, and it is the
+  only place the spec describes the delivery surface at all.
+
+  NOT SCREENS. No pages, layouts, navigation, components or visual design — those are
+  realisation decisions owned by the prototype and design.ui.md, and putting them here
+  would break the WHAT/HOW line the whole kit rests on.
+
+  Lifted with the Experience Standards below, from the frontend lane's constitution
+  (constitution.ui.md) and the mapped ux/ rules. A project with no frontend lane has no
+  surface to bound: write "None (as of vX.Y)" — never delete the section.
+-->
+
+- **Actors**: [the user roles that reach this aggregate through a UI — e.g. clinician, scheduler; distinct from a system/API caller]
+- **Channels**: [where the experience is delivered — e.g. responsive web; internal back-office only]
+- **Device / viewport floor**: [the smallest supported surface — e.g. 360 px wide]
+- **Browser / platform floor**: [the oldest supported targets — e.g. the last two major versions of evergreen browsers]
+- **Assistive-technology floor**: [the input modes and readers that MUST work — e.g. keyboard-only; NVDA + VoiceOver]
+
+## System Requirements *(mandatory)*
+
+<!--
+  Functional requirements in EARS notation (Easy Approach to Requirements Syntax):
+  atomic, testable, unambiguous. Choose the pattern that fits each requirement —
+
+    • Ubiquitous     THE SYSTEM SHALL <requirement>
+    • Event-driven   WHEN <trigger> THE SYSTEM SHALL <response>
+    • State-driven   WHILE <in a state> THE SYSTEM SHALL <response>
+    • Unwanted       IF <condition/error> THEN THE SYSTEM SHALL <response>
+    • Optional       WHERE <feature is present> THE SYSTEM SHALL <response>
+
+  Give each a STABLE id (FR-001, …) — design sections and code trace to these ids.
+  Mark genuine unknowns "[NEEDS CLARIFICATION: <question>]" (≤3; scope/UX/security
+  only, and only where no reasonable default exists).
+-->
+
+- **FR-001**: WHEN [a customer submits an order] THE SYSTEM SHALL [create it in Draft state].
+- **FR-002**: THE SYSTEM SHALL [persist every order under a unique identifier].
+- **FR-003**: IF [the order has no line items] THEN THE SYSTEM SHALL [reject the submission].
+- **FR-004**: WHILE [an order is in Draft] THE SYSTEM SHALL [allow line items to be added or removed].
+- **FR-005**: WHERE [tax calculation is enabled] THE SYSTEM SHALL [apply the regional tax rule].
+
+## Business Rules *(invariants — always true, technology-agnostic)*
+
+<!--
+  ACTION REQUIRED: Constraints that must ALWAYS hold for the aggregate, independent
+  of any single operation. These become the design's §Domain invariants and must be
+  enforceable and testable. Give each a STABLE id (BR-001, …).
+-->
+
+- **BR-001**: [An order's total MUST never be negative.]
+- **BR-002**: [A submitted order MUST always have at least one line item.]
+- **BR-003**: [An order's identifier is immutable once created.]
+
+## Constraints & Non-Functional Requirements *(domain lift — CN)*
+
+<!--
+  ACTION REQUIRED (when the domain applies; else "None (as of vX.Y)"). Constraints the
+  aggregate MUST satisfy that are NEITHER functional behaviour (those are FR) NOR
+  always-true business invariants (those are BR): the regulatory, retention,
+  immutability, audit-mandate, and performance-as-a-limit rules. Many are LIFTED here
+  by specify from the domain rule files (e.g. persistence.domain, auditing.domain,
+  data-classification.domain) so they survive into design — which reads the spec ONLY.
+  Give each a STABLE id (CN-001, …); design's §5 Cross-Cutting and the analyze gate
+  trace to these ids. State each as testable; where lifted, cite the source rule.
+-->
+
+- **CN-001**: [Retention — e.g. submitted orders + their audit trail are retained for [period] per [policy]; hard delete is forbidden once submitted (logical/retire only). — lifted from persistence.domain]
+- **CN-002**: [Audit immutability — e.g. every create/modify/cancel emits an append-only audit entry (User, Timestamp, Action, Previous, New). — lifted from auditing.domain]
+- **CN-003**: [Data integrity — e.g. records subject to [regime] satisfy [integrity standard].]
+- **CN-004**: [Performance-as-a-limit — e.g. P95 read latency < 200 ms at 200 RPS; not a behaviour, a bound.]
+
+## Key Entities *(the aggregate's conceptual model — no implementation detail)*
+
+<!--
+  The aggregate root and the entities/value objects inside its boundary: what each
+  represents, its key attributes, lifecycle/states, and relationships. Reference to
+  OTHER aggregates is by identifier only (see Aggregate Boundary).
+-->
+
+- **[Aggregate root — e.g. Order]**: [what it represents; key attributes; lifecycle/states, e.g. Draft → Submitted → Fulfilled]
+- **[Entity / value object — e.g. OrderLine]**: [what it represents; relationship to the root]
+
+## Data Classification *(domain lift — DC)*
+
+<!--
+  ACTION REQUIRED (when the aggregate handles sensitive data; else "None (as of vX.Y)").
+  The sensitivity taxonomy for this aggregate's data and the exposure rules that follow:
+  which categories exist, which Key-Entity fields fall in each, and where each category
+  MAY / MUST NOT appear (public API surface, logs, metrics, traces, external projections).
+  Lifted by specify from the domain data-classification rules. Design enforces these; the
+  analyze-design / analyze-slice gates check them. Give each a STABLE id (DC-001, …); reference fields by
+  the names used in Key Entities.
+-->
+
+| id | Category | Applies to (fields / entities) | Exposure rule |
+|---|---|---|---|
+| DC-001 | [Public] | [id, status, non-sensitive attributes] | [may appear on the public API + external projections] |
+| DC-002 | [Sensitive / restricted] | [PII, pre-release, commercially-sensitive fields] | [MUST NOT appear on the public surface, nor in logs / metrics / traces] |
+| DC-003 | [Externally-sourced] | [imported fields] | [carries provenance; [handling rule]] |
+
+## Integration Contracts *(domain lift — IC)*
+
+<!--
+  ACTION REQUIRED (when the aggregate interoperates; else "None (as of vX.Y)"). The
+  external contracts this aggregate MUST satisfy — interoperability obligations lifted by
+  specify from the domain interop rules (e.g. FHIR/HL7/DICOM projections, terminology
+  services, inbound feeds). State each at CONTRACT level: which standard, which resources,
+  direction (inbound/outbound), projection vs system-of-record — NOT the adapter design
+  (design realises these in its API / Infrastructure layers). Give each a STABLE id
+  (IC-001, …); design's §4.2 External Integrations traces to these ids.
+-->
+
+- **IC-001**: [Outbound projection — e.g. the aggregate SHALL project to [external standard / resources] as read-only projections (not the system of record); identifiers map to [external identifier]; coded fields to [coded type].]
+- **IC-002**: [Reference-data validation — e.g. coded values SHALL validate against [terminology / reference service]; no invented codes.]
+- **IC-003**: [Inbound feed — e.g. inbound [feed/standard] SHALL flow through an Interop adapter, never a direct write path to the aggregate.]
+
+## Experience Standards *(experience lift — UX)*
+
+<!--
+  ACTION REQUIRED (when the frontend lane's rules apply; else "None (as of vX.Y)").
+  The PROJECT-WIDE experience standards this aggregate's UI must satisfy, lifted here by
+  specify out of the frontend lane's constitution (constitution.ui.md — the UX-* principle
+  series) and the mapped ux/ rule files, exactly as CN-/DC-/IC- lift the domain rules.
+  The lift is what makes them binding: prototype, ui-design and ui-implement author from
+  the SPEC and never from the rule files, so a standard not carried here reaches no UI
+  phase and is gated by nothing.
+
+  HIGH-LEVEL AND PROJECT-WIDE ONLY. Each entry is a standard the whole product holds to,
+  stated so it can be checked on ANY surface — never a screen, page, layout, navigation
+  model, component or visual-design choice. Those are the prototype's and design.ui.md's
+  to settle. An entry that can be satisfied only one way has stopped being a standard and
+  has become a design decision in the wrong document.
+
+  Give each a STABLE id (UX-001, …). Its OWN id class on purpose: ui-design and the UI
+  code gate review and verify these separately from the service lane, so the two never
+  have to be untangled out of one list. The consequence to respect — the service-side
+  gates (analyze-design, analyze-slice) trace CN- and never read this section, so a bound
+  the SERVICE must meet stays a CN-. UX- covers what the UI lane realises; where one
+  obligation binds both lanes, state it in both and cross-reference the ids.
+
+  State each as CHECKABLE, and cite the rule or principle it was lifted from.
+-->
+
+- **UX-001**: [Accessibility conformance — e.g. every user-facing surface MUST meet [standard, level]; every task in the User Stories is completable keyboard-only. — lifted from UX-II, ux/accessibility-standards.md]
+- **UX-002**: [Interaction states — e.g. every asynchronous operation MUST present its loading, empty, partial-failure, recovery and success states; no state leaves the user without a next action. — lifted from UX-IV, ux/interaction-states.md]
+- **UX-003**: [Content and language — e.g. user-facing text uses the ubiquitous language of Key Entities; every error names what happened and what to do next; regulated wording is reproduced verbatim. — lifted from UX-V, ux/content-design.md]
+- **UX-004**: [Journey integrity — e.g. each US-n is completable without leaving this aggregate's surface; destructive actions are confirmed and reversible. — lifted from ux/journey-mapping.md]
+- **UX-005**: [Responsiveness-as-a-limit — e.g. an interaction acknowledges input within [n] ms and shows progress past [n] s. A front-end bound; the server-side budget it depends on is CN-nnn.]
+
+## Edge Cases & Exceptional Scenarios
+
+<!--
+  ACTION REQUIRED: Boundary conditions, error paths, and concurrency/consistency
+  cases. Each should map to a System Requirement (often an IF…THEN unwanted-behaviour
+  requirement) or a Business Rule.
+-->
+
+- What happens when [boundary condition, e.g., the same order is submitted twice]?
+- How does the system handle [error scenario, e.g., a referenced product no longer exists]?
+
+## User Stories *(prioritized)*
+
+<!--
+  Prioritized user journeys (P1 = most critical). Each MUST be INDEPENDENTLY
+  TESTABLE — implementing just one still yields a viable slice of value that can be
+  developed, tested, deployed, and demonstrated on its own.
+
+  Give each a STABLE id (US-1, US-2, …); design sections trace to these ids. Each
+  story exercises specific System Requirements / Business Rules — cite them so the
+  spine (US ↔ FR/BR ↔ design ↔ code) stays exact. On this living spec, note when a
+  story entered or changed: "Added: vX.Y (CR-…)" / "Modified: vX.Y (CR-…)".
+-->
+
+### US-1 - [Brief Title] (Priority: P1)   ·   _Added: v1.0_
+
+[Describe this user journey in plain language.]
+
+**Why this priority**: [The value and why it ranks here.]
+
+**Exercises**: [FR-001, FR-003, BR-001]
+
+**Acceptance Criteria**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+**Independent Test**: [How this story is verified on its own and the value it delivers.]
+
+---
+
+### US-2 - [Brief Title] (Priority: P2)   ·   _Added: v1.0_
+
+[Describe this user journey in plain language.]
+
+**Why this priority**: [The value and why it ranks here.]
+
+**Exercises**: [FR-…, BR-…]
+
+**Acceptance Criteria**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+**Independent Test**: [How this story is verified on its own.]
+
+---
+
+[Add more user stories as needed (US-3, US-4, …), each with a priority and a stable id.]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Measurable, technology-agnostic outcomes — verified at the
+  `analyze-slice` phase. Give each a STABLE id (SC-001, …).
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "A customer can place an order in under 2 minutes."]
+- **SC-002**: [Measurable metric, e.g., "The system sustains 1000 concurrent orders without degradation."]
+- **SC-003**: [User-satisfaction metric, e.g., "90% of first-time users complete an order without assistance."]
+- **SC-004**: [Business metric, e.g., "Reduce order-related support tickets by 50%."]
+
+## Change History
+
+<!--
+  The living-truth ledger. Every applied change request appends a row here, carrying
+  the version it ships as. finalize-delta writes the row when it merges the delta;
+  close-delta then archives the CR, bumps the minor version in active_version.json and
+  stamps that same number into this document's **Version** header — one mechanism, one
+  stage, so header, row and active_version.json never disagree. Newest last.
+-->
+
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial specification | US-1 | — |

package/assets/.appweaver/templates/ui-design-template.md

@@ -0,0 +1,273 @@
+# UI Design: [AGGREGATE]
+
+**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
+
+**Design home**: `specs/[Aggregate]/design.ui.md`
+
+**Source spec**: `specs/[Aggregate]/spec.md`
+
+**Lane**: `[lane id]` — the frontend lane declared in `.appweaver/stacks.json`
+
+**Version**: v1.0   <!-- moves in lockstep with spec.md and design.md; one change closes on ONE bump -->
+
+**Status**: Draft
+
+<!--
+  WHAT THIS DOCUMENT IS
+  =====================
+  The single, living High-Level Design for ONE feature's EXPERIENCE — the
+  frontend lane's twin of design.md. It is the MEDIATOR between spec.md
+  (WHAT/WHY, tech-agnostic) and the frontend code `implement-ui` generates.
+  It carries screens, navigation, client state, composition, interaction and
+  the service binding. It is NOT code, and it is NOT a visual comp.
+
+    spec.md  ──▶  design.ui.md  ──▶  frontend code (+ tests)
+    behaviour     structure &          generated by `implement-ui`
+    (UX/US/FR/SC) decisions            (framework bound at generation time)
+
+  ANCHORING RULES
+  - Every element traces UP to a spec id (UX-/US-/FR-/CN-/DC-/IC-/SC-) and the
+    spec's experience obligations are covered DOWN here (§7 Traceability). No
+    screen without a spec reason; no user story without a screen home.
+  - UX- LIVES HERE AND ONLY HERE. The spec's Experience Standards are this
+    document's to realise — design.md deliberately excludes them, so a UX- that
+    reaches neither design is a dropped requirement.
+  - THE SPEC IS THE ONLY DOMAIN INPUT — the same rule design.md keeps. This
+    document reads the spec + the lane's own standards, never the domain rule
+    files. A domain rule the spec omits is an §8 assumption, never an invention.
+  - THE SERVICE LANE ENTERS ONLY AT §5. Cite the operations this surface
+    consumes; never restate, re-derive or contradict the service design, and
+    never place server-side behaviour here.
+
+  ONE LANE, ONE DOCUMENT
+  - This document governs the frontend lane only, and the lane owns the subtree
+    `.appweaver/stacks.json` declares for it. The two lanes share the feature, the
+    spec, the version and the OKF concept — nothing else.
+
+  TECHNOLOGY-AGNOSTIC (mandatory)
+  - Name no framework, router, state library, component library or styling
+    approach. Describe a component by its RESPONSIBILITY, its INPUTS (props /
+    params as field shapes), the EVENTS it raises and the STATES it can be in.
+    The same design must be realisable on another frontend stack without edits.
+    The framework binds at `implement-ui` from constitution.ui.md + that
+    command's rule set.
+
+  WHAT LIVES ELSEWHERE (do NOT repeat it here — it is identical for every feature)
+  - The lane's folder structure, naming conventions, forbidden patterns and CI
+    gates are constitution.ui.md's. This document uses them; it does not restate
+    them.
+  - HOW to turn this design into components (file placement, one-component-per-
+    file, test pairing, client generation) is a solution-wide rule applied at
+    `implement-ui`.
+  - The app shell, global layout and the design system belong to no single
+    feature. Cite them; do not claim them here.
+
+  HOW TO AUTHOR
+  - Fill every [PLACEHOLDER]. Keep the section order.
+  - §4 Interaction & Flow and §6 Cross-Cutting are NEVER omitted, however thin
+    the feature. Loading, empty, error and permission-denied states are where
+    most UI defects live, and they are the two sections a backend-shaped process
+    silently drops.
+  - §8 Assumptions and §9 Workarounds are MANDATORY ledgers — an empty one reads
+    "None (as of vX.Y)", never a deletion.
+  - Delete these authoring comments as you fill each section.
+-->
+
+## 0. Design Overview
+
+<!--
+  One paragraph: the shape of this feature's experience and the 3–5 decisions
+  that matter most — the entry point, the primary flow, the hardest trade-off.
+  The lane's standing conventions are NOT restated here; they are the UI
+  constitution's.
+-->
+
+[The essence of this feature's experience in 3–6 sentences.]
+
+### Ubiquitous Language (design delta)
+
+<!-- Only the terms this design introduces or sharpens beyond the spec — a screen
+     name, a state name, a shared component concept. These become code
+     identifiers, so name them once here and use them verbatim everywhere. -->
+
+| Term | Meaning in this design |
+|---|---|
+| [Screen / component / state name] | [precise definition] |
+
+## 1. Navigation & Screen Structure
+
+<!-- The screen inventory and how a user moves between them. One row per screen
+     THIS feature owns. A screen belongs to the feature that owns the DECISION
+     the user makes there; a screen that merely reads another aggregate's data
+     declares a dependency rather than duplicating it. -->
+
+| Screen | Purpose | Entered from | Leads to | Serves |
+|---|---|---|---|---|
+| `[Screen]` | [the decision made here] | [entry point] | [next screens] | US-[n] · FR-[nnn] |
+
+**Route / navigation shape**: [how screens are addressed and nested, stated
+conceptually — a path pattern, a stack, a tab set — never named after a router.]
+
+**Access conditions**: [which screens require what — authentication state, a
+role, a record state — each citing the spec id that imposes it, or `None`.]
+
+**Screens this feature does NOT own**: [shared shell, navigation chrome, or
+another aggregate's screens this flow passes through — cited, not designed here.
+Or `None`.]
+
+## 2. Client State
+
+<!-- What the client holds, where it lives, and who may write it. Separate
+     server-derived data from local UI state: they have different owners,
+     different lifetimes and different failure modes. Invalidation is part of
+     the design — a stale-data defect is a design defect, not an implementation
+     one. -->
+
+| State | Kind | Owner / scope | Shape | Written by | Invalidated by |
+|---|---|---|---|---|---|
+| `[State]` | [server-derived / local UI / session] | [scope] | [field: type, …] | [screen / component] | [event] |
+
+**Derived state**: [what is computed rather than stored, and from what. A value
+that can be derived is not stored twice.]
+
+**What must NOT be held**: [fields the spec's DC- ids keep off the client, and
+anything the service alone may decide. Cite the DC-/CN- id.]
+
+## 3. Component Structure
+
+<!-- ONE `### 3.n` SUBSECTION PER COMPOSITION AXIS THIS FEATURE ACTUALLY NEEDS,
+     each titled with the lane's own name for it (screens, feature components,
+     shared compositions, forms, …). The slots below are illustrative positions,
+     not a required set: create the ones this feature has and stop.
+     In each: what lives there, what it is responsible for, its inputs as field
+     shapes, and the events it raises. -->
+
+### 3.1 [COMPOSITION AXIS NAME]
+
+<!-- [What this axis holds for this feature.] -->
+
+| Component | Responsibility | Inputs (field shape) | Events raised | Serves |
+|---|---|---|---|---|
+| `[Component]` | [single responsibility] | [field: type, …] | `[event]` | FR-[nnn] · US-[n] |
+
+### 3.n [COMPOSITION AXIS NAME]
+
+<!-- … one per axis this feature needs, then stop … -->
+
+**Reused from the design system**: [the shared components this feature composes
+rather than defines. Composing is the default; a new shared component is a
+decision recorded in §8.]
+
+## 4. Interaction & Flow
+
+<!-- MANDATORY — never omitted, never thinned to the happy path. For each
+     significant interaction: the states it passes through and what the user
+     sees in each. Cover loading, empty, error, permission-denied and
+     in-flight/disabled, plus validation timing and what happens on cancel or
+     navigate-away. Each unwanted-behaviour state the spec states as an FR- has
+     a row here; a state with no FR- is a spec gap routed to `specify`, never
+     invented in a component. -->
+
+| Interaction | States | What the user sees | Serves |
+|---|---|---|---|
+| `[interaction]` | [idle → in-flight → success / error / empty / denied] | [per-state behaviour] | US-[n] · FR-[nnn] |
+
+**Validation & feedback**: [when validation runs and how failures are surfaced,
+citing the BR-/FR- ids being echoed. A client-side check NEVER replaces the
+service-side rule — it restates it for feedback, and the service stays the
+authority.]
+
+**Keyboard, focus & announcement**: [focus placement on navigation and on error,
+keyboard reachability of every interaction above, and what is announced to
+assistive technology — citing the UX- standard that governs it.]
+
+**Concurrency & recovery**: [what happens on a double submit, a stale record, or
+a lost connection mid-flight.]
+
+## 5. Contract Binding
+
+<!-- THE LANE BOUNDARY. One row per service operation this feature's UI depends
+     on. Bind against the service's PUBLISHED SURFACE — the spec's IC- ids and
+     the API contracts design.md states — and never against the service's
+     internals: no table, no handler, no persistence assumption crosses this
+     line. An interface the experience needs and the service does not offer is a
+     CONTRACT DELTA raised back to the service lane, never a workaround in the
+     client. -->
+
+| Screen / component | Operation | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
+|---|---|---|---|---|---|
+| `[Screen]` | `[operation]` | [field: type, …] | [field: type, …] | [the §4 state it produces] | FR-[nnn] · IC-[nnn] |
+
+**Write semantics**: [per mutating operation — optimistic or pessimistic, what
+it invalidates, and how an optimistic update rolls back.]
+
+**Contract deltas needed**: [anything the experience requires that the service
+surface does not offer, raised back to the service lane. Or `None`.]
+
+## 6. Cross-Cutting
+
+<!-- MANDATORY — never omitted. One row per concern this feature's UI must
+     honour, each tracing to a spec id or, where the obligation comes from the UI
+     constitution rather than the spec, to an §8 DA-n citing that principle.
+     Keep the rows this feature genuinely carries; a concern that does not apply
+     says so and says why. -->
+
+| Concern | Design decision | Serves |
+|---|---|---|
+| Data exposure on the client | [what MUST NOT reach the client, its logs, its storage or its URLs] | DC-[nnn] |
+| Authorization surface | [what is hidden vs disabled vs enforced server-side] | CN-[nnn] |
+| Accessibility | [the conformance obligations this feature meets and how] | UX-[n] |
+| Internationalization | [what is localized and where the strings come from] | UX-[n] / DA-[n] |
+| Performance & responsiveness | [target + the structural choice that meets it] | SC-[nnn] |
+| Error & offline behaviour | [what the user gets when the service is unreachable] | FR-[nnn] |
+| Telemetry | [what is recorded, and what is deliberately not] | [spec id / DA-n] |
+
+## 7. Traceability (the spine)
+
+<!-- The two-way guarantee for the lane: every experience obligation in the spec
+     has a home here, and every UI element has a spec reason. The last column
+     names THIS document's own sections.
+     A US- with no screen is a coverage failure. A UX- with no row is a dropped
+     requirement — design.md does not carry them, so this is their only home. -->
+
+| Spec id | Type | UI element(s) | Section |
+|---|---|---|---|
+| UX-[n] | experience standard | [where realised] | [§] |
+| US-[n] | story | [screens + flow realising it] | [§ refs] |
+| FR-[nnn] | requirement | [screen / component / state] | [§] |
+| CN-[nnn] | constraint | [where honoured in the UI] | [§] |
+| DC-[nnn] | classification | [what is withheld from the client] | §6 |
+| IC-[nnn] | contract | [binding row] | §5 |
+| SC-[nnn] | success | [where met + how verified] | [§] |
+
+## 8. Assumptions (to clarify later)
+
+<!-- MANDATORY LEDGER. Every default or open interpretation this design commits
+     to so it can proceed without blocking — including any element
+     constitution.ui.md mandates that has no per-feature spec id (state the basis
+     as "per constitution.ui.md UX-<n>"). Empty → "None (as of vX.Y)". -->
+
+| id | Assumption | Why deferred | Impact if wrong | Owner / resolve-by |
+|---|---|---|---|---|
+| DA-1 | [what was assumed] | [why not clarified now] | [blast radius] | [role / phase] |
+
+## 9. Workarounds (to clear later)
+
+<!-- MANDATORY LEDGER. Experience debt KNOWINGLY taken — a screen that does too
+     much, a duplicated component, state held in the wrong place — with the
+     proper end-state and the trigger that forces the cleanup.
+     Empty → "None (as of vX.Y)". -->
+
+| id | Workaround taken | Proper end-state | Trigger to revisit | Serves / caused by |
+|---|---|---|---|---|
+| WA-1 | [the shortcut / coupling] | [the clean design] | [what forces it] | [FR / constraint] |
+
+## Change History
+
+<!-- In lockstep with spec.md and design.md — a change that touches both lanes
+     closes on ONE version bump. finalize-delta appends the row; close-delta
+     bumps the version and stamps it into the header. Newest last. -->
+
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial UI design | US-1 | — |