aw-spec-cli 0.1.7 → 0.1.9

package/assets/.appweaver/orchestrator/rev-templates/tech-rule-bindings.skeleton.md

@@ -0,0 +1,116 @@
+<!--
+  rev-templates/tech-rule-bindings.skeleton.md — SHAPE-ONLY reference for the
+  project's tech-rule-bindings.md (resolve-tech reads it by that exact name — the
+  TECHNICAL twin of domain-rule-bindings.md, which resolve-domain reads). It shows the
+  per-command headings, the TECHNICAL RULE PARTITION, the bullet shape, and the
+  quick-reference table. It lists NO real rule files — every bullet is a
+  placeholder for a service/ file the author actually generated from THIS
+  project's CODE.
+
+  Wire ONLY files you generated (all under guardrails/projects/[project]/service/).
+  Never list a file you did not write. Never list a path belonging to another
+  project (guardrails/projects/<other>/**) — that one is another project's
+  rules, not this one's.
+-->
+# [PROJECT_NAME] — Command → Technical-Rule-File Map (as-built)
+
+Per-command list of the **[PROJECT_NAME] technical** rule files loaded (via `resolve-tech` +
+the `tech-select` module, into the sticky standards set) for the spec-anchored orchestrator
+pipeline. This is the technical counterpart of `domain-rule-bindings.md` (which maps the DOMAIN rule
+files), and the CODE-DERIVED replacement for the greenfield technical map.
+
+**The model:** the technical rule files (this project's own architecture / persistence /
+concurrency / testing / security-posture set, reverse-engineered from the code into
+`guardrails/projects/[project]/service/`) are CONFIGURATION — tune this map, not the workflows. The
+technology base itself (`constitution.technical.md`) is NOT listed here — every consumer still
+refers to it directly, as-is.
+
+- All paths are workspace-relative and live in `guardrails/projects/[project]/service/`.
+- `resolve-tech --command <name>` collects the `- ` bullets under `## /<name>`.
+- **`## /aw-spec-specify` is the MODELLING-METHODOLOGY slot** — exactly one file,
+  `service/domain-modelling.md`: HOW this code expresses a domain model. Never an architecture /
+  persistence / codegen / security file; those would break specify's domain purity. Every other
+  heading below feeds the HOW phases.
+- A command with no heading here loads no mapped technical file (only the workflow's universal
+  `ai-rules.md` seed + `constitution.technical.md`, referred to directly).
+
+---
+
+## /aw-spec-specify
+<!-- MODELLING METHODOLOGY ONLY — exactly one file. HOW this codebase expresses a domain model
+     (what marks an aggregate root, entity vs value object, where invariants live, the context
+     boundary), NOT what the model is (that is the domain set's domain-driven-design.domain.md,
+     wired via domain-rule-bindings). No technology rule may appear under this heading. -->
+- guardrails/projects/[project]/service/domain-modelling.md
+
+## /aw-spec-design
+<!-- The as-built architecture / cross-cutting technical rules the design author mediates the spec
+     against. NO domain file here — domain reaches design only as spec ids. -->
+- guardrails/projects/[project]/service/[as-built-architecture].md
+- guardrails/projects/[project]/service/[each generated architecture/cross-cutting rule].md
+
+## /aw-spec-implement
+<!-- The framework / code-generation rule set the generator builds against (from design.md). -->
+- guardrails/projects/[project]/service/[each generated codegen/convention rule].md
+
+## /aw-spec-implement-delta
+<!-- The CR analog of implement — same code-generation set, scoped to the delta-design. -->
+- guardrails/projects/[project]/service/[each generated codegen/convention rule].md
+
+## /aw-spec-build
+<!-- The layering + convention rules the compile-fixer respects. -->
+- guardrails/projects/[project]/service/[as-built-architecture].md
+
+## /aw-spec-analyze-slice
+<!-- The design↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
+- guardrails/projects/[project]/service/[testing/convention rule to validate against].md
+
+## /aw-spec-adopt
+<!-- Brownfield reverse-engineering: the technical REFERENCE set the reversed design mediates the
+     reversed spec ↔ existing code against — the CODE wins, these are reference only. -->
+- guardrails/projects/[project]/service/[architecture/cross-cutting reference rule].md
+
+## /aw-spec-constitution
+<!-- The set the TECHNICAL half of the split constitution is RE-ratified from when /appweaver
+     constitution is run again on this repo — the same code-derived rules the HOW phases build
+     against, so a ratified principle can cite the rule it governs. onboard authored the first
+     constitution from code evidence directly, before these files existed; this heading is what
+     keeps a later re-run authoring from THIS project's rules instead of from nothing. List the
+     service/ files that carry a ratifiable standard, NOT every generated file, and NO worked examples/
+     sample (the ratified half is one declarative line per principle). NO domain file — the domain
+     half's sources are the DOMAIN map's ## /aw-spec-constitution. -->
+- guardrails/projects/[project]/service/[ratifiable technical standard].md
+
+## /aw-spec-run
+<!-- The runtime / execution conventions the app-run step honors — add ONLY if the code evidences
+     a runtime/hosting concern file. NOT data-migration (migration is the deferred later phase). -->
+- guardrails/projects/[project]/service/[runtime/hosting rule].md
+
+<!-- ## /aw-spec-ui-constitution — the FRONTEND LANE's heading. It is NOT written by the step
+     that authors this map; onboard's frontend rule-set step APPENDS it here, after the technical
+     headings and before the quick-reference table, but only where the scan found a UI in the
+     code. It maps the generated frontend/ lane rules (frontend/ui-constitution.md first), and
+     it is also the authoritative signal that this project HAS a frontend lane — a later
+     /appweaver constitution reads it to decide whether to author constitution.ui.md at all.
+     A backend-only repo simply never gets the heading.
+
+     Do NOT add /aw-spec-characterize or /aw-spec-parity in the DEV flow — characterize is
+     opt-on-touch and parity is deferred to the migration phase. Add any other heading later
+     ONLY if that phase is entered AND you generated a file it should load — an absent heading
+     soft-continues (loads nothing). -->
+
+---
+
+## Quick reference (command → technical file count)
+
+| Command | Technical rule files | Role |
+|---|---|---|
+| /aw-spec-specify | 1 | the as-built modelling methodology the domain model is expressed in — no technology |
+| /aw-spec-design | [n] | as-built architecture the design author mediates the spec against |
+| /aw-spec-implement | [n] | code-generation set the generator builds against (from design.md) |
+| /aw-spec-implement-delta | [n] | same code-generation set, scoped to the open change's delta-design |
+| /aw-spec-build | [n] | layering + convention rules the compile-fixer respects |
+| /aw-spec-analyze-slice | [n] | conformance rules the design↔code gate validates against |
+| /aw-spec-adopt | [n] | technical reference set for the reversed design (brownfield) |
+| /aw-spec-constitution | [n] | the standards the technical constitution half is re-ratified from |
+| /aw-spec-run | [n] | runtime/execution conventions the app-run step honors (only if evidenced) |

package/assets/.appweaver/orchestrator/rev-templates/technical-constitution.skeleton.md

@@ -0,0 +1,106 @@
+<!--
+  ═══════════════════════════════════════════════════════════════════════════
+  rev-templates/technical-constitution.skeleton.md — SHAPE-ONLY reference.
+
+  This file is the FORMAT + VOCABULARY reference for the reverse-engineered
+  TECHNICAL half (constitution.technical.md). It is loaded as a `standards:`
+  entry for the technical-half author (include_standards:true). It carries the
+  AppWeaver principle-heading style, the Sync-Impact-Report shape, the
+  evidence-line pattern, and the section skeleton — and NOTHING ELSE.
+
+  IT DELIBERATELY CONTAINS NO PRINCIPLE SET. There is no fixed I–XV list to
+  inherit. Every [BRACKET] token below is a slot the author fills from evidence
+  — never a value to copy. Copy the SHAPE, discover the CONTENT from the code.
+
+  DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
+  here to leak):
+    • EVIDENCE-FIRST — author a principle ONLY for a technology trait the
+      adopted design.md files + the OKF overview/platform note actually
+      evidence. If the code does not show it, it is not a principle.
+    • CITE inline — every principle ends with an `(evidence: …)` line naming a
+      design section, a concrete type / port / persistence context / config, or
+      an OKF stack line. A principle with no groundable evidence does not belong.
+    • AS-BUILT LEVEL — state a partial / stubbed / optional trait at the level
+      the code actually reaches; never the aspirational ideal.
+    • OMIT pure aspiration — a trait the code shows zero of is not softened into
+      a principle; it is left out.
+    • ROUTE gaps — an unmet ideal / stub / inactive-optional concern goes into
+      the "As-Built Debt → migration backlog" list below, never asserted.
+    • VARIABLE LENGTH — number sequentially from I with no gaps and no padding
+      to a fixed count. The final numeral is the domain half's continuation
+      point.
+  ═══════════════════════════════════════════════════════════════════════════
+-->
+<!--
+Sync Impact Report
+- Version: [OLD] -> [NEW]   (reverse-engineered technical baseline)
+- Project: [PROJECT_NAME]
+- Discovered technical principles: I–[N] (domain half continues at [N+1])
+- Principle set (as-built):
+  I   [PRINCIPLE_TITLE]
+  II  [PRINCIPLE_TITLE]
+  …   (only traits the code evidences — no fixed count)
+- Template ideals DELIBERATELY OMITTED (lack of as-built evidence):
+  - [IDEAL] — [why the code does not evidence it]
+  - …
+- As-Built Debt → migration backlog (see knowledge/migration-backlog.md; do not restate the table):
+  - [gap / stub / inactive-optional concern] — [where it is tracked]
+  - …
+- Dependent artifacts:
+  - constitution.domain.md — ⚠ authored next; continues at [N+1]
+  - guardrails/projects/[project]/domain/domain-constitution.md — [✅/⚠] domain charter source
+  - guardrails/projects/[project]/service/ — [✅/⚠] technical rule set
+- TODOs: [none mechanical | …]
+-->
+# [PROJECT_NAME] Constitution — Technical Base
+
+> Reverse-engineered, **as-built**, domain-agnostic technical half. Authority for DESIGN and
+> IMPLEMENT. Domain principles live in `constitution.domain.md` (continues at **[N+1]**).
+> This file asserts only technology traits evidenced by the adopted designs + OKF overview/platform.
+
+## Core Principles
+
+<!-- One block PER EVIDENCED TRAIT. Tag (NON-NEGOTIABLE) only where the code enforces it as such.
+     Replace the bracketed text; keep the `### <numeral>. <title>` + rule + `(evidence: …)` shape. -->
+
+### I. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
+[One declarative, testable rule the adopted designs actually evidence. State it at the level the
+code reaches — partial/stubbed/optional traits are stated as partial, not as the ideal.]
+(evidence: [design §X.Y named type / port / persistence context / config; or OKF overview Tech-stack line])
+
+### II. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
+[…]
+(evidence: […])
+
+<!-- … continue with only the principles the code evidences … -->
+
+> **Domain half continues at principle [N+1]** in `constitution.domain.md`.
+
+## Mandatory Folder Structure (base)
+
+- [Solution projects / module layout AS INVENTORIED — from the OKF overview + designs, not an ideal.]
+- [Cross-cutting host files that stay at their template levels.]
+- Domain-specific folder additions (if any) are declared only in the domain constitution half.
+
+## Conventions, Forbidden Patterns, AI Rules & Quality Gates (base)
+
+- [Prefer the framework abstractions ALREADY in use — name them from evidence.]
+- [Forbidden patterns the code's structure implies — e.g. no cross-aggregate write, endpoints do not touch persistence.]
+- Base AI operating rules: [pointer to the operating-rules reference].
+- Any pre-existing greenfield standards docs are **reference only** until reverse-engineered against
+  this codebase — where they conflict with the as-built evidence above, **this constitution wins**.
+
+## Governance
+
+- This technical half + the paired domain half supersede README / agent-context files where they
+  disagree on engineering rules.
+- Amendments via PR that updates the affected half (+ the mapped rule set if needed), includes a migration
+  plan for non-compliant code, and bumps SemVer:
+  - **MAJOR** — remove/weaken a NON-NEGOTIABLE principle or break mandatory structure
+  - **MINOR** — add a principle or mandatory section
+  - **PATCH** — clarifications
+- Reviewers cite principle numbers. Domain change-authority overrides live in the domain half.
+- Runtime agent guidance MUST point at the composed constitution and MUST NOT restate these
+  principles at length.
+
+**Version**: [X.Y.Z] | **Ratified**: [YYYY-MM-DD] | **Last Amended**: [YYYY-MM-DD]

package/assets/.appweaver/orchestrator/rev-templates/technical-rule-file.skeleton.md

@@ -0,0 +1,54 @@
+---
+origin: reverse-engineered
+generated_by: aw-spec-onboard/[VERSION]
+concern: "[concern-slug]"
+---
+<!--
+  rev-templates/technical-rule-file.skeleton.md — SHAPE-ONLY reference for ONE
+  generated technical rule file in the project's service/ folder
+  (guardrails/projects/[project]/service/<concern>.md). It is the TECHNICAL twin of
+  domain-rule-file.skeleton.md. Write one such file per TECHNOLOGY concern the
+  CODE ACTUALLY exhibits (evidenced-only, lean) — e.g. as-built-architecture,
+  persistence, concurrency, testing, security-posture, api-surface, eventing,
+  observability, hosting — NOT per domain concern (those are the *.domain.md
+  overlays), NOT per greenfield ideal.
+
+  ONE concern in this set is not a technology concern and is still written here:
+  `domain-modelling` — the as-built modelling METHODOLOGY (what marks an aggregate
+  root, entity vs value object, where invariants live, the context boundary). It is
+  the only file wired under `## /aw-spec-specify`, and it carries NO business
+  vocabulary: HOW this code models, never WHAT it models (that is the domain set's
+  domain-driven-design.domain.md). Same shape as below — cite code coordinates.
+
+  Every rule below MUST cite a CODE COORDINATE (a real file/folder path or named
+  type) and, where it maps, the technical-constitution principle numeral it
+  details. This is the DETAIL layer under constitution.technical.md — the thin
+  ratified principle points here; here is the enforceable rule. State what the
+  code DOES (quirks, stubs, partials included), never a greenfield assumption.
+  Keep the frontmatter (origin + generated_by + concern). Copy the SHAPE only —
+  this file carries NO real technology, path, or framework name.
+-->
+# [Concern] — [PROJECT_NAME] Technical Rule (as-built)
+
+> Ratified by: constitution.technical.md principle [N] ([short principle title]).
+> Commands: [the technical commands this file feeds, per the partition — e.g. design · implement · build].
+
+> [One-line framing of what this concern IS in this codebase — from the code, not an ideal.]
+
+## [Section — e.g. Structure / Layering / Rules / Contracts]
+
+- [As-built rule the code follows.] (code: [real file/folder path or named type]; principle [N])
+- [As-built rule.] (code: […])
+
+## [Section — e.g. Dependency direction / Constraints / Conventions]
+
+- [As-built rule.] (code: […])
+
+<!-- Where the code's behaviour is a stub / partial / permissive / inactive, STATE IT AS-BUILT at the
+     level the code reaches, and mark it so — do NOT upgrade a stub into a satisfied greenfield ideal,
+     and do NOT invent a rule the code does not evidence. An unmet ideal is simply omitted here
+     (migration/modernization is a separate later phase, not this set's concern). -->
+
+## Related
+
+- [[<sibling generated tech rule>]] · constitution.technical.md principle [N]

package/assets/.appweaver/orchestrator/rev-templates/ui-constitution.skeleton.md

@@ -0,0 +1,125 @@
+<!--
+  ═══════════════════════════════════════════════════════════════════════════
+  rev-templates/ui-constitution.skeleton.md — SHAPE-ONLY reference.
+
+  This file is the FORMAT + VOCABULARY reference for the reverse-engineered UI
+  half (constitution.ui.md) — the FRONTEND LANE's base, authored by onboard from
+  an EXISTING codebase. It is the lane's counterpart to
+  technical-constitution.skeleton.md, and it carries the AppWeaver principle-
+  heading style, the Sync-Impact-Report shape, the evidence-line pattern and the
+  section skeleton — and NOTHING ELSE.
+
+  IT DELIBERATELY CONTAINS NO PRINCIPLE SET, and it names no framework, router,
+  component library, design system, styling approach or conformance standard.
+  A named example in a skeleton becomes ratified law in a lane it does not fit,
+  and the frontend is where that risk is highest — every stack has a house style
+  and none of them is the kit's to assume. Every [BRACKET] token below is a slot
+  filled FROM THE CODE, never a value to copy.
+
+  WHERE THE CONTENT COMES FROM — the forward direction is INVERTED here. In a
+  greenfield project this half ratifies the project's mapped frontend rule files;
+  at onboard those files DO NOT EXIST YET. The evidence is therefore the UI
+  SOURCE ITSELF, read through the scan substrate's `frontend_signals` (candidate
+  roots, their kind, their component/route/store files) plus the OKF as-built
+  frontend note. The project's frontend/ rule files are generated AFTERWARDS, as
+  the detail layer under whatever this half ratifies — the same order the
+  technical tier already uses.
+
+  DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
+  here to leak):
+    • EVIDENCE-FIRST — author a UX principle ONLY for an experience trait the UI
+      code actually exhibits. If the code does not show it, it is not a principle.
+    • CITE inline — every principle ends with an `(evidence: …)` line naming a
+      real component / route / store / stylesheet / config path. A principle with
+      no groundable evidence does not belong.
+    • AS-BUILT LEVEL — state a partial / inconsistent / absent trait at the level
+      the code actually reaches. An app with no accessibility attributes does not
+      get an accessibility principle written as though it were met; it gets one
+      that says what IS enforced, or none at all.
+    • OMIT pure aspiration — a trait the UI shows zero of is not softened into a
+      principle. A short honest half a later run can extend is correct.
+    • UX-* SERIES — number UX-I, UX-II, … This half is PARALLEL to the technical
+      base, never a continuation of it, so its numbering is unaffected by how many
+      principles that base carries and it never resumes the domain half's.
+    • ONE LANE ONLY — this half governs the frontend lane and stands alone. It
+      does not restate service-lane principles, does not cite them by number, and
+      carries NO domain principle, identifier, terminology or regulatory rule.
+  ═══════════════════════════════════════════════════════════════════════════
+-->
+<!--
+Sync Impact Report
+- Version: [OLD] -> [NEW]   (reverse-engineered frontend baseline)
+- Project: [PROJECT_NAME]
+- Lane: [LANE_ID] ([KIND]) at [ROOT] — [separable | rendered inside the service tree]
+- Discovered experience principles: UX-I–UX-[N]
+- Principle set (as-built):
+  UX-I   [PRINCIPLE_TITLE]
+  UX-II  [PRINCIPLE_TITLE]
+  …      (only traits the UI code evidences — no fixed count)
+- Experience concerns DELIBERATELY OMITTED (lack of as-built evidence):
+  - [CONCERN] — [what the code shows instead, or that it shows nothing]
+- Dependent artifacts:
+  - guardrails/projects/[project]/frontend/ — [✅/⚠] generated lane rule set
+  - guardrails/projects/[project]/tech-rule-bindings.md — [✅/⚠] `## /aw-spec-ui-constitution`
+- TODOs: [none mechanical | …]
+-->
+# [PROJECT_NAME] Constitution — User Experience Base
+
+> Reverse-engineered, **as-built**, domain-agnostic frontend-lane half. Authority for the
+> UI lane. Service-lane principles live in `constitution.technical.md` and domain principles
+> in `constitution.domain.md`; this half neither restates nor renumbers either.
+> It asserts only experience traits evidenced by the UI code itself.
+
+## Declared Lane
+
+[UI_LANE_DECLARATION]
+<!-- Form: one line naming the lane, what it is built with, and the root directory it owns —
+     all three READ FROM THE CODE (the scan's candidate root, its detected kind, the framework
+     markers), never invented and never taken from a stack profile. Where the UI is rendered
+     inside the service tree and owns no root of its own, SAY SO: that is a legitimate as-built
+     lane, reversed in place. Where .appweaver/stacks.json exists and disagrees with the code,
+     the disagreement is reported, not silently resolved — a declaration is a human's statement
+     of intent and the code is what shipped. -->
+
+## Experience Principles
+
+<!-- One block PER EVIDENCED TRAIT. Tag (NON-NEGOTIABLE) only where the UI code enforces it
+     as such. Replace the bracketed text; keep the `### UX-<numeral>. <title>` + rule +
+     `(evidence: …)` shape. -->
+
+### UX-I. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
+[One declarative, testable rule the UI code actually evidences, stated at the level it reaches.]
+(evidence: [real component / route / store / stylesheet / config path])
+
+### UX-II. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
+[…]
+(evidence: […])
+
+<!-- … continue with only the principles the UI code evidences, then stop … -->
+
+## [UI_STRUCTURE_SECTION_NAME]
+
+[UI_STRUCTURE_CONTENT]
+<!-- Form: the lane's AS-BUILT layout under its own root — where components, screens/pages,
+     routing, client state, styling and assets actually live, named as THIS code names them.
+     Do not impose a folder taxonomy the code does not use. This layout sits entirely under
+     the lane's root and never adds to the service lane's structure. -->
+
+## [UI_CONVENTIONS_SECTION_NAME]
+
+[UI_CONVENTIONS_CONTENT]
+<!-- Form: the naming, state-management, data-fetching and styling conventions the code
+     visibly follows, plus the lane's existing quality gates (its test setup, lint/format
+     config, CI steps) — each a thin adopted line pointing at the generated frontend rule
+     file that carries the detail. Where the codebase is inconsistent, state the DOMINANT
+     convention and record the divergence rather than picking a winner. -->
+
+## Governance
+
+[UI_GOVERNANCE_RULES]
+<!-- Form: this half versions independently of the other two. State only the lane's own
+     overrides. Mark the whole half PROVISIONAL where onboard authored it from the scan
+     alone — a later adopt/constitution run reconciles it against per-slice evidence. -->
+
+**Version**: [X.Y.Z] | **Ratified**: [YYYY-MM-DD] | **Last Amended**: [YYYY-MM-DD]
+<!-- ISO YYYY-MM-DD dates. Versions INDEPENDENTLY of the other two halves. -->

package/assets/.appweaver/orchestrator/rev-templates/ui-delta-design-template.skeleton.md

@@ -0,0 +1,123 @@
+<!--
+  ═══════════════════════════════════════════════════════════════════════════
+  rev-templates/ui-delta-design-template.skeleton.md — SHAPE-ONLY reference.
+
+  This file is the FORMAT reference for the reverse-engineered UI DELTA-design
+  TEMPLATE that onboard installs at
+  .appweaver/templates/overrides/ui-delta-design-template.md — the frontend lane's
+  twin of delta-design-template.skeleton.md, written only where the CODE has a
+  lane. It carries the classification triple, the impact and regression
+  sections, the two ledgers and the close contract, and NOTHING ELSE.
+
+  IT NAMES NO FRAMEWORK AND NO FIXED UI TAXONOMY. The "Section" column is a
+  SLOT, filled with the ACTUAL sections of the UI design template generated
+  alongside this one — including whatever composition axes §3 turned out to
+  carry. A change is classified against the document it amends.
+
+  ONE CHANGE, TWO LANES, ONE VERSION. A change request that touches both lanes
+  produces a service delta AND this one; `finalize-delta` merges the three
+  masters (spec.md, design.md, design.ui.md) and the change closes on ONE
+  version bump. This record never opens a second UI design document, and it
+  never restates the service delta — where the change starts in the service
+  contract, this document records only what the EXPERIENCE does with it.
+
+  DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
+  here to leak):
+    • ADDED / MODIFIED / REMOVED — the complete classification. A shared
+      component is MODIFIED in place, never duplicated into the change.
+    • EVERY ROW SERVES A SPEC ID — the delta reads the delta-spec, never the
+      domain rule files. A change's experience is stated in the spec first.
+    • STATES ARE PART OF THE CHANGE — a new interaction that ships without its
+      loading, empty, error and permission-denied states is an incomplete delta,
+      not a later refinement.
+    • TECHNOLOGY-AGNOSTIC — responsibilities, field shapes and events, no code.
+  ═══════════════════════════════════════════════════════════════════════════
+-->
+# UI Delta Design — [CR-ID]: [TITLE]
+
+**Feature (aggregate)**: [Aggregate]
+
+**Base version**: [vX.Y]
+
+**Service delta**: [the companion delta-design for this CR, or `None — experience-only change`]
+
+<!--
+  This delta applies to the SINGLE master UI design at
+  specs/[Aggregate]/design.ui.md — never a new document. Classify every change
+  ADDED / MODIFIED / REMOVED against the current master, per the MASTER'S OWN
+  SECTIONS, in the same technology-agnostic form: responsibilities, inputs as
+  field shapes, events and states — no code. After this delta is applied,
+  ⌛ `ui-implement-delta` regenerates the touched UI and regression re-verifies
+  every screen that shares a changed component or state.
+-->
+
+## Change summary
+
+[One paragraph: what the experience change is and which user story / spec delta
+it serves.]
+
+## ADDED — new UI elements
+
+<!-- New screens, components, state, interactions or contract bindings.
+     "Section" names a section of THIS project's master UI design — the same
+     section titles the generated UI design template carries. -->
+
+| Section (§ in design.ui.md) | Element | Kind | Serves |
+|---|---|---|---|
+| [§ of the master's own structure] | `[element]` | [screen / component / state / binding] | US-[n] · FR-[nnn] |
+
+## MODIFIED — existing UI elements
+
+<!-- Edits to elements the master already defines. A shared component or a
+     shared state container is modified here, in place — never copied. -->
+
+| Section (§ in design.ui.md) | Element | What changes | Why |
+|---|---|---|---|
+| [§ of the master's own structure] | `[element]` | [the edit] | US-[n] |
+
+## REMOVED
+
+- [UI element removed + why, including where its users now go] — or `None`
+
+## Interaction states touched
+
+<!-- Every state the change adds or alters — loading, empty, error,
+     permission-denied, in-flight. A new interaction lists its full state set
+     here; an unlisted state reads as unchanged, not as absent. -->
+
+| Interaction | States added / changed | What the user sees | Serves |
+|---|---|---|---|
+| `[interaction]` | [states] | [per-state behaviour] | US-[n] |
+
+## Contract impact
+
+[What this change needs from the service lane, taken from the change's contract
+projection: bindings added, changed or no longer used. Anything the experience
+requires that the contract does not offer is raised back to the service lane —
+never worked around in the client. Or `None`.]
+
+## Cross-section impact
+
+[Which of the master's sections ripple; shared components or state containers
+touched; navigation edges added or removed; any screen in ANOTHER feature that
+depends on a changed shared element.]
+
+## Regression targets
+
+[Existing user stories / screens to re-verify because a shared component, a
+shared state container or a navigation edge changed.]
+
+## New assumptions / deviations (from this change)
+
+<!-- Anything this change defers — folds into the master's DA-n / WA-n ledgers
+     on apply. -->
+
+- **DA-[n]**: [assumption to clarify later] — or `None`
+- **WA-[n]**: [deviation to clear later] — or `None`
+
+## On close
+
+`finalize-delta` merges this record into the master design.ui.md alongside the
+spec and service-design merges, and appends the Change History row;
+`close-delta` bumps the ONE version both lanes share and archives the change
+under `changes/archive/`.