aw-spec-cli 0.1.18 → 0.1.20

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

@@ -1,6 +1,6 @@
 # Delta Backend Plan — [CR-ID]: [TITLE]
 
-**Feature (aggregate slice)**: `[Feature]`
+**Feature**: `[Feature]`
 
 **Lane**: backend — the service lane declared in `.appweaver/stacks.json`
 

package/assets/.appweaver/templates/delta-domain-model-template.md

@@ -2,7 +2,7 @@
 
 **Bounded context**: `[Context]`
 
-**Feature (aggregate slice)**: `[Feature]`
+**Feature**: `[Feature]`   <!-- the feature whose change this is; the aggregates it changes are listed under "Aggregates touched" -->
 
 **Wave**: [N]   <!-- script-stamped; same wave = developable in parallel, higher wave = after -->
 

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

@@ -1,6 +1,6 @@
 # Delta Spec — [CR-ID]: [TITLE]
 
-**Feature (aggregate)**: [Aggregate]
+**Feature**: [Feature]
 
 **Change type**: [new-requirement | changed-requirement | defect | refactor]
 
@@ -21,8 +21,9 @@
   Standards (UX-n). A CR that changes a retention/audit rule, a data-exposure rule, an
   interop obligation or a project-wide experience standard is a CN-/DC-/IC-/UX- delta, not
   a smuggled code change. A UX- delta states the standard only — never a screen, page or
-  component, which the prototype and frontend-plan.md settle. Adding a command (e.g.
-  UpdateOrder to the Order aggregate) is a new user story (US-n), NOT a new feature.
+  component, which the prototype and frontend-plan.md settle. Adding a command to THIS
+  feature (e.g. UpdateOrder to Order) is a new user story (US-n). Whether a capability is
+  a feature of its own is the developer's decision, made when they select the feature.
 
   MODEL CHANGES DO NOT BELONG HERE. A new entity, a changed aggregate boundary or a new
   or amended invariant (BR-n) goes in this change's domain-model delta — the "Model delta"

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

@@ -1,10 +1,12 @@
-# Backend Plan: [AGGREGATE]
+# Backend Plan: [FEATURE]
 
-**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
+**Feature**: `[Feature]`  <!-- the capability scope the developer chose; the aggregate(s) it acts on are the spec's "Acts on aggregate(s)" line -->
 
-**Plan home**: `specs/[Aggregate]/backend-plan.md`
+**Plan home**: `specs/[Context]/[Feature]/backend-plan.md`
 
-**Source spec**: `specs/[Aggregate]/spec.md`
+**Source spec**: `specs/[Context]/[Feature]/spec.md`   <!-- behaviour: what the system must DO -->
+
+**Source model**: `specs/[Context]/domain-model.md`   <!-- structure: what the domain IS -->
 
 **Version**: v1.0   <!-- moves in lockstep with the spec; every applied change request bumps this — see Change History -->
 
@@ -13,29 +15,40 @@
 <!--
   WHAT THIS DOCUMENT IS
   =====================
-  The single, living High-Level Design (HLD) for ONE aggregate. It is the
+  The single, living High-Level Design (HLD) for ONE feature — the capability scope
+  the developer chose, over the aggregate(s) its spec says it acts on. It is the
   MEDIATOR between spec.md (WHAT/WHY, tech-agnostic) and the generated code
   (HOW, tech-specific). It is NOT code: it carries structure, contracts,
   behaviour, and decisions — enough for ANY capable LLM to generate correct,
   spec-satisfying code on ANY target stack, but no complete method bodies.
 
-    spec.md  ──▶  backend-plan.md  ──▶  code (+ tests)
-    behaviour     structure &       generated by `implement`
-    (FR/BR/US/SC) decisions (HLD)    (stack-bound at generation time)
+    domain-model.md ─┐
+    structure        ├─▶  backend-plan.md  ──▶  code (+ tests)
+    (BR-nnn)         │    structure &          generated by `implement`
+    spec.md        ──┘    decisions (HLD)       (stack-bound at generation time)
+    behaviour
+    (FR/US/SC/CN/DC/IC)
 
   ANCHORING RULES
-  - Every design element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/US-/SC-) and
-    the whole spec is covered DOWN here (see §6 Traceability). No design element
-    without a spec reason; no spec requirement without a design home.
-  - THE SPEC IS THE ONLY DOMAIN INPUT. Design reads the spec + the technical/
-    architecture standards — NOT the domain rule files. The domain reached this doc
-    only as spec ids: business invariants (BR-), domain-derived constraints (CN- —
-    retention/immutability/audit/limits), data classification (DC-), and interop
-    obligations (IC-). Realise each of those; invent no domain rule the spec omits
-    (if one seems missing, record it as an Assumption in §7, never smuggle it in).
-  - Feature = aggregate. Commands (CreateOrder, UpdateOrder…) are USER STORIES,
-    not features. One aggregate = one backend-plan.md = one owning design for its code
-    files. A later requirement is a delta on THIS doc, never a new one.
+  - Every design element traces UP to an id — behaviour ids (FR-/US-/SC-/CN-/DC-/IC-)
+    from the spec, invariant ids (BR-) from the context's domain-model.md — and the
+    whole spec is covered DOWN here (see §6 Traceability). No design element without
+    a reason in one of those two; no spec requirement without a design home.
+  - TWO AUTHORITIES, NOT ONE. Structure comes from the MODEL, behaviour from the SPEC.
+    domain-model.md fixes the aggregate's entities, value objects, boundary and
+    invariants; spec.md says what the system must DO with them and cites each invariant
+    by id. Design reads BOTH, plus the technical/architecture standards — but NOT the
+    domain rule files: a domain rule reaches this doc only as an id already lifted into
+    one of the two (BR- in the model; CN-/DC-/IC- in the spec). Realise each of those;
+    invent no entity, value object or rule that neither states (if one seems missing,
+    record it as an Assumption in §7, never smuggle it in).
+  - One feature = one backend-plan.md. A feature is the capability scope the developer
+    chose: it may act on several aggregates, and several features may act on one. Its
+    operations (CreateOrder, UpdateOrder…) are USER STORIES here, and a later requirement
+    on this feature is a delta on THIS doc, never a new one. An aggregate's shared code
+    (its root, entities, value objects, repository) is realised by every plan whose
+    feature acts on it: each plan names only the members its feature needs, and the
+    code extends the shared file instead of regenerating it.
 
   WHAT LIVES ELSEWHERE (do NOT repeat it here — it is identical for every feature)
   - The clean-architecture layering + dependency rule (API → Application → Domain
@@ -68,13 +81,13 @@
 ## 0. Design Overview
 
 <!--
-  One paragraph: the architectural shape of this aggregate and the 3–5 decisions
+  One paragraph: the architectural shape of this feature and the 3–5 decisions
   that matter most (why this boundary, the lifecycle model, the hardest trade-off).
   This is the orientation a reviewer or an LLM reads first. The standing layering /
   dependency rule is NOT restated here — it is the project architecture standard.
 -->
 
-[The architectural essence of this aggregate in 3–6 sentences: its purpose, its
+[The architectural essence of this feature in 3–6 sentences: its purpose, its
 lifecycle spine, the key structural choices specific to it, and the single biggest
 trade-off. Layering follows the project architecture standard (constitution).]
 
@@ -111,9 +124,11 @@ trade-off. Layering follows the project architecture standard (constitution).]
                                   performance-as-a-limit land in §4 Infra / §5 Cross-Cutting.)
   You MAY add design-level structure — domain events, state machines, behaviour
   signatures — but ONLY to REALISE spec behaviour. Do NOT invent an entity, value
-  object, or rule the spec does not state, and do NOT contradict it. If a genuinely
-  new concept is unavoidable, record it as an Assumption (§7, DA-n) and flag it —
-  never smuggle it in. Pure business model: no framework, no persistence, no I/O.
+  object, or invariant THE MODEL does not define, do NOT invent behaviour THE SPEC
+  does not state, and do NOT contradict either. If a genuinely new concept is
+  unavoidable, record it as an Assumption (§7, DA-n) and flag it — never smuggle it
+  in: a missing entity or invariant is a gap in the model, which /appweaver specify
+  owns and this document may not close. Pure business model: no framework, no persistence, no I/O.
   Model this section on a rich DDD reference (entities, VOs, events, state machines,
   invariants, behaviours). Repeat the blocks as the aggregate needs.
 -->
@@ -138,7 +153,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
 <!--
   Per entity: attributes (conceptual types), lifecycle state machine if it has one,
   behaviours as SIGNATURE + pre/post/invariant/raises pseudocode (the most LLM-guidable,
-  stack-neutral form), and the invariants it enforces (each = a spec BR-nnn).
+  stack-neutral form), and the invariants it enforces (each = a BR-nnn THE MODEL defines).
 -->
 
 #### `[Entity]` [(Aggregate Root)]
@@ -162,13 +177,14 @@ trade-off. Layering follows the project architecture standard (constitution).]
 ```
 [Entity].[Behaviour]([params])
   Pre-condition:  [required state / inputs]
-  Invariant:      [what must hold — maps to a spec BR-nnn]
+  Invariant:      [what must hold — maps to a BR-nnn in the domain model]
   Post-condition: [resulting state / outputs]
   Raises:         [DomainEvent]
   Serves:         FR-00X · US-Y · BR-00Z
 ```
 
-**Invariants** *(always-true; each maps to a spec BR-nnn — do not add rules absent from the spec)*
+**Invariants** *(always-true; each cites a BR-nnn the domain model defines — never restate its
+text, and do not add a rule the model does not carry)*
 
 - [Invariant statement] — **BR-00X**
 
@@ -287,7 +303,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
 
 ### 4.3 Wiring & migrations
 
-- **Composition**: bind `[Port] → [Adapter]` for this aggregate.
+- **Composition**: bind `[Port] → [Adapter]` for this feature.
 - **Migrations needed**: [yes → what changes conceptually / no]. The Run phase applies them.
 
 ## 5. Cross-Cutting Concerns
@@ -320,22 +336,22 @@ trade-off. Layering follows the project architecture standard (constitution).]
 
 <!--
   The two-way guarantee: every FR/BR/CN/DC/IC/US/SC has a design home, and every
-  design element has a spec reason. This is what makes impact analysis exact and lets
-  the analyze gate verify coverage. Keep it complete — EVERY CN-/DC-/IC- in the spec
+  design element has a reason in one of the two authorities. This is what makes impact
+  analysis exact and lets the analyze gate verify coverage. Keep it complete — EVERY CN-/DC-/IC- in the spec
   MUST appear as a row here (that is how the analyze gate proves no lifted constraint
   was dropped). The Domain rows MUST match the domain model's entities and BR-nnn
   invariants exactly.
 -->
 
-| Spec id | Type | Design element(s) | Layer |
-|---|---|---|---|
-| FR-001 | requirement | `[Root].[Behaviour]`, `[Command]`, `[VERB /route]` | Domain·App·API |
-| BR-001 | invariant | `[Root]` invariant / `[VO]` validation | Domain |
-| CN-001 | constraint | [where realised — §1 invariant / §4 persistence / §5 cross-cutting] | [layer] |
-| DC-001 | classification | [exposure enforcement — §2 projection / §5 data-protection] | App·Infra |
-| IC-001 | contract | [adapter/port realising it — §4.2] | Infra |
-| US-1 | story | [end-to-end elements realising it] | all |
-| SC-001 | success | [where it is met + how verified] | [layer] |
+| Id | Source | Type | Design element(s) | Layer |
+|---|---|---|---|---|
+| FR-001 | spec | requirement | `[Root].[Behaviour]`, `[Command]`, `[VERB /route]` | Domain·App·API |
+| BR-001 | model | invariant | `[Root]` invariant / `[VO]` validation | Domain |
+| CN-001 | spec | constraint | [where realised — §1 invariant / §4 persistence / §5 cross-cutting] | [layer] |
+| DC-001 | spec | classification | [exposure enforcement — §2 projection / §5 data-protection] | App·Infra |
+| IC-001 | spec | contract | [adapter/port realising it — §4.2] | Infra |
+| US-1 | spec | story | [end-to-end elements realising it] | all |
+| SC-001 | spec | success | [where it is met + how verified] | [layer] |
 
 ## 7. Assumptions (to clarify later)
 

package/assets/.appweaver/templates/okf-concept-template.md

@@ -3,6 +3,8 @@ type: aggregate
 title: [Aggregate]
 description: [one line — what this aggregate is and the invariant/boundary it guards]
 origin: greenfield
+bounded_context:
+features:
 source_files:
 ui_source_files:
 ---
@@ -17,8 +19,16 @@ ui_source_files:
       as it generates the aggregate's code;
     • brownfield — `inventory` seeds it and `adopt` enriches it.
 
+  A CONCEPT IS AN AGGREGATE, NEVER A FEATURE. A feature is a capability scope the
+  developer chose; it may act on several aggregates, and several features may act on
+  one. `features:` lists every feature known to act on this aggregate — implement and
+  adopt add their feature, and a feature is never removed from it by a later write.
+  `bounded_context:` names the context the aggregate belongs to.
+
   WHO WRITES WHAT (do not cross these lanes):
-    • Frontmatter, Overview, Depends-On   → THIS aggregate's implement/adopt.
+    • Frontmatter, Overview, Depends-On   → the implement/adopt of every feature that
+                                             acts on this aggregate. Depends-On is the
+                                             union over all of them.
     • Cross-References                     → the OTHER aggregates that USE this one; each
                                              writes its own row (never hand-edit them here).
   One addition inside the first lane: `analyze-slice` MERGES (never replaces) the files its

package/assets/.appweaver/templates/proposed-inventory-template.md

@@ -0,0 +1,127 @@
+# Proposed Inventory
+
+<!-- TEMPLATE-NOTE
+     This is the TEMPLATE for the document `/appweaver inventory` generates at
+     specs/proposed-inventory.md. Every TEMPLATE-NOTE block is stripped on generation,
+     so nothing in here reaches the produced file.
+
+     UNLIKE EVERY OTHER TEMPLATE IN THIS DIRECTORY, THIS ONE IS FILLED BY A SCRIPT,
+     NOT BY AN AGENT. aw-inventory.py substitutes each token below with the result of
+     its scan. There are no [PLACEHOLDER] tokens for an author to complete — a token
+     left in the output is a bug, not an unfinished section.
+
+     Override it per project at
+     .appweaver/templates/overrides/proposed-inventory-template.md to change the
+     wording, the ordering or the guidance. Keep every token you want filled; drop
+     one and that section simply does not appear.
+
+     Tokens, each written in single braces:
+       root · head · date · strategy · reason · files · code · coverage
+       probe_table · context_table · feature_table
+       splits_section · cycles_section
+-->
+<!-- Generated by `/appweaver inventory`. Edit freely, then run
+     `/appweaver inventory apply`. -->
+
+**Repository:** `{root}`  ·  **Commit:** `{head}`  ·  **Generated:** {date}
+**Pass A strategy:** `{strategy}` — {reason}
+**Scanned:** {files} files, {code} source files  ·  **Coverage:** {coverage}%
+
+This file is the **boundary map for this codebase, and it is yours to change.** Nothing
+below was decided by a person yet — it is what a deterministic scan of the source
+proposes. Read it, correct it, then run `/appweaver inventory apply`, which validates
+your edits and regenerates the machine map that `/appweaver onboard` reads.
+
+## How to edit this file
+
+- **Rename** a feature or a bounded context by editing its cell. Names are the
+  identity — renaming a feature here renames the slice onboard will create.
+- **Move** a feature to another context by editing its Bounded Context cell.
+  A feature lives in exactly one context.
+- **Merge** two features by giving them the same name; their files combine, and the
+  merged feature acts on every aggregate its rows name — that is how one feature spans
+  several aggregates. Keep those rows in the same Bounded Context.
+- **Split** a feature by adding a row with the same Aggregate and a different
+  Feature name. Name the split from the capability, not the noun —
+  `PatientRegistration`, not a second `Patient`.
+- **Reorder** by editing Depends On. Waves are recomputed on apply, so you do
+  not maintain wave numbers by hand.
+- Rows you delete are dropped from the map and never onboarded.
+
+The Aggregate column must name an aggregate the scan found; everything else is
+yours. `apply` reports anything it cannot resolve rather than guessing.
+
+## How these boundaries were found
+
+Three passes over the source. None of them reads a specification, a rule file or an
+exemplar from another project — the code is the only evidence.
+
+**Pass A — what must stay consistent together.** Groups the source into candidate
+aggregates. Three strategies can do this, and only those the evidence supports are
+offered:
+
+| strategy | the evidence it reads | available when |
+|---|---|---|
+| `structure` | the repo's own organising axis — a vertical slice, a layer folder under a module, a layer carried as a project-name suffix, or a layer at the top with the module repeated as a noun | always |
+| `reference` | the `using` / `import` / `require` graph, clustered after removing the high-fan-in nodes that are shared kernel rather than features | enough import-parseable source |
+| `persistence` | the schema itself — `DbSet<T>`, `[Table]`, JPA `@Entity`, `schema.prisma`, `CREATE TABLE` — with roots derived by ownership: an entity that owns others' lifecycles and is referenced from outside by id | ORM / schema / migration evidence found |
+
+`structure` always runs whichever strategy is chosen, because the other two produce
+unnamed clusters and need it to give each one a directory and a human name.
+
+**Pass B — what can be cut over together.** Reads the application, API and UI surface
+only, and emits *signals*, never decisions: route families (`[Route("orders")]`,
+`@RequestMapping`, `app.get('/orders/…')`), command/handler groups, UI router segments,
+and rates of change from git history. **Two distinct route families on one aggregate is
+a split candidate** — proposed below, never applied.
+
+Three of the five tests for a feature boundary are computable — one cutover seam,
+stable file ownership, one bounded context — and two are not: whether it serves one
+business need, and whether it can be demonstrated independently. Those two are why this
+file is editable.
+
+**Pass C — the proposal.** One aggregate becomes one feature with the same name. That
+is the default and not a failure. A split is proposed only where Pass B found the
+evidence, and is shown with that evidence for you to accept or ignore. One endpoint is
+never a feature; neither is one whole bounded context.
+
+**Bounded contexts** are derived above Pass A and voted from where each candidate's
+files actually live. A feature belongs to exactly one context — the context of the
+primary aggregate it acts on. A feature that needs another context's aggregate
+references it by id and stays a separate feature over there.
+
+## Strategy probe
+
+The clustering each available strategy produced on this tree. The chosen one is
+marked; re-run with `--strategy <name>` to pick another.
+
+{probe_table}
+
+## Bounded Contexts
+
+Onboard one context at a time, in this order. A context is ready when every context it
+depends on has been onboarded.
+
+{context_table}
+
+## Features
+
+Dependency order. **Wave 0 depends on nothing** and can be onboarded first; a feature in
+wave N depends only on features in earlier waves. Edit any cell except Wave, which is
+recomputed.
+
+{feature_table}
+{splits_section}{cycles_section}
+## What happens after you apply this
+
+```
+/appweaver inventory apply          validates these edits, regenerates the machine map
+/appweaver onboard <Context>        once per context, in the order above:
+                                    reverse-engineers the governance and creates
+                                    specs/<Context>/<Feature>/ for each feature
+/appweaver adopt <Feature>          just-in-time, per feature: reverse-engineers its
+                                    spec, plans and domain-model section
+```
+
+Re-running `/appweaver inventory` re-derives this file from the code and **discards
+your edits** — apply them first. Re-running `apply` is safe and idempotent.

package/assets/.appweaver/templates/source-map-template.md

@@ -1,8 +1,10 @@
-# Source Map: [AGGREGATE]
+# Source Map: [FEATURE]
 
-**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. MedicinalProduct -->
+**Feature**: `[Feature]`  <!-- the capability scope confirmed in the boundary map, e.g. MedicinalProduct or PatientRegistration -->
 
-**Source home**: `specs/[Aggregate]/source-map.md`
+**Acts on aggregate(s)**: `[Aggregate]`  <!-- the same names the spec's Domain Model Reference gives -->
+
+**Source home**: `specs/[Context]/[Feature]/source-map.md`
 
 **Origin**: `reverse-engineered`   <!-- greenfield | reverse-engineered | migrated -->
 

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

@@ -1,8 +1,8 @@
-# Specification: [AGGREGATE]
+# Specification: [FEATURE]
 
-**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
+**Feature**: `[Feature]`  <!-- the capability scope the developer chose, e.g. Order or PatientRegistration; the aggregate(s) it acts on are named under Domain Model Reference -->
 
-**Spec home**: `specs/[Aggregate]/`
+**Spec home**: `specs/[Context]/[Feature]/`
 
 **Version**: v1.0   <!-- living truth; every applied change request bumps this — see Change History -->
 
@@ -17,13 +17,13 @@
   and is referenced from here by name and id. That split is what lets one aggregate be
   acted on by several specs without any of them owning its definition.
 
-  Every operation on the aggregate (CreateOrder, UpdateOrder, …) is a USER STORY below —
-  NOT a separate feature. A later requirement is a new US-n added as a delta (see
+  Every operation within this feature's scope (CreateOrder, UpdateOrder, …) is a USER
+  STORY below. A later requirement on this feature is a new US-n added as a delta (see
   delta-spec-template.md), never a new spec folder. One spec + one plan per declared
   lane — the PLAN derives from this document and the domain model together.
 
   Section order is intentional: establish the business need and scope, then the stable
-  core the aggregate's BEHAVIOUR is (requirements → constraints → data classification →
+  core the feature's BEHAVIOUR is (requirements → constraints → data classification →
   integration contracts → experience standards → edge cases), then the prioritized user
   journeys that exercise it, then measurable success.
 
@@ -39,11 +39,11 @@
 ## Business Need
 
 <!--
-  ACTION REQUIRED: Why this aggregate exists — the problem, the affected users,
+  ACTION REQUIRED: Why this feature 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.]
+[The problem this feature solves, who it serves, and the value it delivers.]
 
 ## Scope & Assumptions
 
@@ -83,7 +83,7 @@
 ### Experience Scope
 
 <!--
-  The experience envelope this aggregate is specified against: WHO reaches it through a
+  The experience envelope this feature 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.
@@ -97,7 +97,7 @@
   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]
+- **Actors**: [the user roles that reach this feature 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]
@@ -130,7 +130,7 @@
 
 <!--
   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
+  feature 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,
@@ -147,8 +147,8 @@
 ## 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:
+  ACTION REQUIRED (when the feature handles sensitive data; else "None (as of vX.Y)").
+  The sensitivity taxonomy for this feature'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
@@ -165,8 +165,8 @@
 ## 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
+  ACTION REQUIRED (when the feature interoperates; else "None (as of vX.Y)"). The
+  external contracts this feature 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
@@ -182,7 +182,7 @@
 
 <!--
   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
+  The PROJECT-WIDE experience standards this feature'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: the prototype phase and the FRONTEND LANES of plan
@@ -208,7 +208,7 @@
 - **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 context's ubiquitous language; 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-004**: [Journey integrity — e.g. each US-n is completable without leaving this feature'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
@@ -289,10 +289,13 @@
 
 <!--
   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.
+  the version it ships as. finalize-delta writes the row when it MERGES the delta, with
+  the CR id and `(pending)` in the Version cell — at that point the number does not exist
+  yet. 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 AND into the pending
+  cell — one mechanism, one stage, so header, row and active_version.json never disagree.
+  A row still reading `(pending)` is a change that merged and has not closed. The model
+  never writes a version here or anywhere; scripts stamp it. Newest last.
 -->
 
 | Version | Date | Change | User stories | CR |

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

@@ -1,6 +1,6 @@
 # Delta Frontend Plan — [CR-ID]: [TITLE]
 
-**Feature (aggregate slice)**: `[Feature]`
+**Feature**: `[Feature]`
 
 **Lane**: `[lane id]` — the frontend lane declared in `.appweaver/stacks.json`
 

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

@@ -1,10 +1,10 @@
-# Frontend Plan: [AGGREGATE]
+# Frontend Plan: [FEATURE]
 
-**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
+**Feature**: `[Feature]`  <!-- the capability scope the developer chose; the aggregate(s) it acts on are the spec's "Acts on aggregate(s)" line -->
 
-**Plan home**: `specs/[Aggregate]/frontend-plan.md`
+**Plan home**: `specs/[Context]/[Feature]/frontend-plan.md`
 
-**Source spec**: `specs/[Aggregate]/spec.md`
+**Source spec**: `specs/[Context]/[Feature]/spec.md`
 
 **Lane**: `[lane id]` — the frontend lane declared in `.appweaver/stacks.json`
 
@@ -32,9 +32,13 @@
   - UX- LIVES HERE AND ONLY HERE. The spec's Experience Standards are this
     document's to realise — backend-plan.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 backend-plan.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 SPEC IS THE ONLY DOMAIN INPUT for this lane. 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 reads a
+    second authority, the context's domain-model.md, because it realises the
+    aggregate's structure. This lane does not: it consumes the published surface
+    at §5, not the domain, so the model is not in its context and an entity or
+    invariant is never this document's to state.)
   - 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.