aw-spec-cli 0.1.16 → 0.1.18

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

@@ -1,69 +1,159 @@
-# Delta Design — [CR-ID]: [TITLE]
+# Delta Backend Plan — [CR-ID]: [TITLE]
 
-**Feature (aggregate)**: [Aggregate]
+**Feature (aggregate slice)**: `[Feature]`
 
-**Base version**: [vX.Y]   <!-- the current master design version; the design phase bumps the minor on close -->
+**Lane**: backend — the service lane declared in `.appweaver/stacks.json`
+
+**Wave**: [N]   <!-- script-stamped from the delta-spec; same wave = developable in parallel, higher wave = after -->
+
+**Base version**: [vX.Y]   <!-- the master plan's version when this delta opened; close-delta bumps the minor at the end of the chain -->
+
+**Delta spec**: `changes/[CR-ID]/delta-spec.md`
+
+**Model delta**: `specs/[Context]/domain-model.[CR-ID].delta.md`   <!-- "none" when this change is behaviour-only -->
 
 <!--
-  This delta applies to the SINGLE master design at specs/[Aggregate]/design.md —
-  never a new design doc. Classify every design change ADDED / MODIFIED / REMOVED
-  against the current master, per LAYER section (Domain · Application · API · Infra),
-  in the SAME technology-agnostic form as the master: behaviour as signatures +
-  pre/post/invariant/raises, contracts as field shapes — NO code. A new command
-  (e.g. UpdateOrder) is a new USER STORY realised as delta design elements, NOT a
-  new feature/aggregate. After this delta is applied to design.md, `implement`
-  regenerates the touched slice; regression re-tests the shared-element dependents.
+  ONE CHANGE'S PLAN FOR THE SERVICE LANE. It applies to the feature's master plan at
+  specs/[Context]/[Feature]/backend-plan.md — never a new plan document. It is authored in
+  the change's own directory beside its delta-spec, and it is what `implement` generates the
+  service lane's code from when this change is the one it is answered with; close-delta
+  archives it as the record of how the change was built.
+
+  IT DOES NOT TOUCH backend-plan.md, AND NEITHER DOES finalize-delta. Many changes may be
+  open at once, so a delta that edited the master would move the baseline every other open
+  delta is authored against. The master plan is DERIVED from spec.md and domain-model.md —
+  the two documents finalize-delta does merge — so it is re-derived from them rather than
+  patched from this file.
+
+  WHAT IT PLANS AGAINST — the EFFECTIVE MODEL, not the bare master:
+    • specs/[Context]/domain-model.md              — the master model, what the domain IS today
+    • this change's own domain-model.[CR-ID].delta.md — what this change makes it
+    • the PREDECESSOR deltas — the open model deltas in a LOWER wave, which are committed
+      to landing first and may therefore be built on
+  Same-wave deltas are VISIBLE but are not predecessors: nothing orders them against this
+  one, so their proposals are read to avoid a collision, never assumed to be there. Say
+  so under "Other open deltas" when one touches the same aggregate.
+
+  STRUCTURE IS NOT PLANNED HERE. Entities, value objects, domain events and invariants
+  (BR-n) belong to the domain model; this document plans where each is ENFORCED and how
+  it is REALISED — which use-case, which endpoint, which port, which adapter. Cite
+  BR-n / FR-n / CN-n / DC-n / IC-n by id; never restate what an invariant says.
+
+  Classify every plan change ADDED / MODIFIED / REMOVED against the master, per the
+  master's OWN section structure (whatever sections it actually has — do not assume a
+  fixed layering), in the SAME technology-agnostic form: behaviour as signatures +
+  pre/post/invariant/raises, contracts as field shapes — NO code. A new command (e.g.
+  UpdateOrder) is a new USER STORY realised as delta plan elements, NOT a new feature.
+  `implement` generates the touched slice from this document and regression re-tests the
+  shared-element dependents.
 -->
 
 ## Change summary
 
-[One paragraph: what the design change is and which user story / spec delta it serves.]
+[One paragraph: what the plan change is, and which delta-spec items (FR-/US-/CN-/DC-/IC-)
+it realises. "Realisation only — no spec delta" for a plan-only change.]
+
+## Model changes this plan realises
+
+<!--
+  The bridge from the model delta to the code. One row per item the domain-model delta
+  ADDED / MODIFIED / REMOVED, saying WHERE the change lands in the service. An item in
+  the model delta with no row here is a structural change nothing implements — which is
+  either a missed realisation or a model change that was never needed.
+  "None — behaviour only" when this change does not move the model.
+-->
+
+| Model item (from the model delta) | Kind | Realised in | Enforced at |
+|---|---|---|---|
+| `[Entity/VO/Event]` | added | `[element]` | `[where the invariant is checked]` |
+| **BR-[nnn]** | amended | `[element]` | `[guard / handler / constraint]` |
+
+## Depends on
+
+<!--
+  Other OPEN changes whose plans this one builds on. Every entry MUST be in a LOWER wave
+  than this delta — that is what a wave IS. Reading another delta is not depending on it;
+  only assuming its changes are in place is. A declared dependency orders the finalizes
+  and blocks a recall of the change depended on.
+  "None — stands alone" is the common and preferred answer.
+-->
+
+- `[CR-ID]` (wave [N-1]) — [what this plan assumes from it]
 
-## ADDED — new design elements
+## ADDED — new plan elements
 
-<!-- New entities/VOs/events, use-cases/handlers, endpoints, ports, adapters, and the
-     realisation of any new spec constraint/classification/contract. Serves = a spec id
-     (FR-/BR-/CN-/DC-/IC-/US-); design reads the spec, never the domain rule files. -->
+<!-- New use-cases/handlers, endpoints, ports, adapters, and the realisation of any new
+     spec constraint / classification / contract. Serves = a spec id (FR-/BR-/CN-/DC-/IC-/US-);
+     the plan reads the spec and the domain model, never the domain rule files. -->
 
-| Layer (§) | Element | Kind | Serves |
+| Section (§) | Element | Kind | Serves |
 |---|---|---|---|
 | Application (§2) | `[Command/Query]` + handler | use-case | US-[n] · FR-[nnn] |
 | API (§3) | `[VERB] [/route]` | endpoint | US-[n] · FR-[nnn] |
-| Domain (§1) | `[Event]` / `[VO]` | event / value object | BR-[nnn] · CN-[nnn] |
+| Domain (§1) | `[Event]` handling / `[VO]` mapping | model realisation | BR-[nnn] · CN-[nnn] |
 | Infrastructure (§4.2) | `I[External]` adapter | contract realisation | IC-[nnn] |
 | Cross-cutting (§5) | [audit / retention / exposure decision] | constraint realisation | CN-[nnn] · DC-[nnn] |
 
-## MODIFIED — existing design elements
+## MODIFIED — existing plan elements
 
 <!-- Edits to elements the master already defines (add a behaviour, change a contract). -->
 
-| Layer (§) | Element | What changes | Why |
+| Section (§) | Element | What changes | Why |
 |---|---|---|---|
-| Domain (§1) | `[Root].[Behaviour]` | add [method] + invariant | US-[n] |
+| Domain (§1) | `[Root].[Behaviour]` | add [operation] enforcing BR-[nnn] | US-[n] |
 | Infrastructure (§4) | `I[Aggregate]Repository` | add [operation] | US-[n] |
 
 ## REMOVED
 
-- [design element removed + why] — or `None`
+- [plan element removed + why] — or `None`
+
+## Cross-section impact
+
+[Which sections of the master ripple; shared elements touched (e.g. the aggregate root's
+realisation); new migration needed? (yes/no); any contract change other systems couple to.]
 
-## Cross-layer impact
+## Contract deltas for the frontend lane
+
+<!--
+  What this change adds to or alters in the service's PUBLISHED surface — the only part
+  of this document the frontend lane may bind against. One row per contract; the frontend
+  delta plan cites these rather than re-deriving them. "None" when the surface is
+  unchanged, which is what a purely internal refactor should say.
+-->
+
+| Contract | Change | Shape | Serves |
+|---|---|---|---|
+| `[VERB] [/route]` | added / changed | [request → response field shapes] | IC-[nnn] · FR-[nnn] |
+
+## Other open deltas
+
+<!--
+  Which OTHER open changes touch the same aggregates, endpoints or shared elements —
+  read from their model deltas, which sit beside the master model. Naming an overlap here
+  is what turns a merge-time conflict into a planning decision. "None" when this change
+  stands clear of everything in flight.
+-->
 
-[Which layer sections ripple; shared elements touched (e.g. the aggregate root);
-new migration needed? (yes/no); any contract change other systems couple to.]
+- `[CR-ID]` (wave [N]) — [what overlaps, and how this plan stays clear of it]
 
 ## Regression targets
 
 [Existing user stories / behaviours to re-verify because a shared element changed —
-e.g. re-test CreateOrder when the Order root or its repository is MODIFIED.]
+e.g. re-test CreateOrder when the Order root's realisation or its repository is MODIFIED.]
 
 ## New assumptions / workarounds (from this change)
 
-<!-- Anything this change defers — folds into the master's §7 / §8 ledgers on apply. -->
+<!-- Anything this change defers. It stays this document's record — the master's ledgers
+     are re-derived with the rest of the master plan, not patched from here. -->
 
 - **DA-[n]**: [assumption to clarify later] — or `None`
 - **WA-[n]**: [structural workaround to clear later] — or `None`
 
-## On close
+## On merge
 
-The design phase amends the master design.md doc-first, appends the Change History
-row, bumps the version (minor), and archives this record under `changes/archive/`.
+`finalize-delta` merges the change's SPEC half into `spec.md` and its MODEL half into the
+context's `domain-model.md`, in one transaction, and leaves the change OPEN. It does NOT
+merge this document: the master plan is derived from those two, so it is re-derived rather
+than patched. `close-delta` archives this file with the change, bumps the minor version and
+writes the Change History rows. None of it is this document's job — it records the change,
+it does not apply it.

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

@@ -0,0 +1,81 @@
+# Delta Domain Model — [CR-ID]: [TITLE]
+
+**Bounded context**: `[Context]`
+
+**Feature (aggregate slice)**: `[Feature]`
+
+**Wave**: [N]   <!-- script-stamped; same wave = developable in parallel, higher wave = after -->
+
+**Base context version**: [vX.Y]   <!-- the model version this delta was authored against -->
+
+**Created**: [DATE]
+
+**Aggregates touched**: `[Root]`   <!-- the `## Aggregate:` sections finalize-delta will merge -->
+
+<!--
+  ONE OPEN DELTA'S CHANGE TO THE CONTEXT'S DOMAIN MODEL. It sits BESIDE the master —
+  specs/[Context]/domain-model.<CR-id>.delta.md — deliberately, so every other open
+  delta can see it while planning and design around it instead of discovering the
+  overlap at merge time.
+
+  IT DOES NOT TOUCH domain-model.md. The master is merged by finalize-delta, one
+  `## Aggregate:` section at a time, and only the sections named in "Aggregates touched".
+
+  READING ANOTHER DELTA IS NOT DEPENDING ON IT. If this delta's content assumes a change
+  that another OPEN delta introduces, that is a dependency and it MUST be expressed as a
+  higher Wave than that delta (and named under "Depends on" below). Otherwise a delta
+  merged out of order silently invalidates this one.
+
+  WAVE — the parallel-development dependency level:
+    • Deltas sharing a wave are independent and may be developed at the same time.
+    • A delta in wave N+1 is implemented only after every wave-N delta has landed.
+    • Default is the wave of the currently open deltas (parallel by default); raise it
+      only when this delta genuinely builds on one of them.
+  Scripts stamp the wave — never edit the header by hand; use `cr-wave` to change it.
+-->
+
+## Change summary
+
+[One paragraph: what changes in the MODEL and why. Behaviour changes belong in the delta-spec.]
+
+## Depends on
+
+<!--
+  Other OPEN deltas whose model changes this one builds on, by CR id, with the wave each
+  sits in. Every entry here MUST sit in a LOWER wave than this delta. "None" when this
+  delta stands alone — which is the common case and what keeps waves flat.
+-->
+
+None
+
+## ADDED
+
+<!-- New aggregates, entities, value objects, events, invariants (BR-n) or cross-aggregate invariants (XBR-n). Give the aggregate each belongs to. -->
+
+- **Aggregate `[Root]` · entity**: [NewEntity — what it represents]
+- **Aggregate `[Root]` · invariant BR-00X**: [the rule, always-true, technology-agnostic]
+
+## MODIFIED
+
+<!-- Existing model elements whose definition changes. State the BEFORE and the AFTER — the merge needs both to be unambiguous. -->
+
+- **Aggregate `[Root]` · invariant BR-002**: was "[old rule]" → now "[new rule]"
+
+## REMOVED
+
+<!-- Model elements retired by this change, and what (if anything) replaces them. A removal that other specs reference is a breaking change — say so in Impact. -->
+
+None
+
+## Impact
+
+<!--
+  Which specs in this context reference the aggregates touched — those are the specs whose
+  requirements may need to move with this model change. Also state any OPEN delta that
+  touches the same aggregate: that is a merge conflict waiting to happen and is what the
+  wave ordering exists to sequence.
+-->
+
+- **Specs referencing `[Root]`**: [Feature, OtherFeature]
+- **Open deltas on the same aggregate**: [CR-ID (wave N) — or "none"]
+- **Breaking**: [yes/no — and what breaks]

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

@@ -6,20 +6,32 @@
 
 **Created**: [DATE]
 
+**Wave**: [N]   <!-- script-stamped; same wave = developable in parallel, higher wave = after -->
+
 **Base version**: [vX.Y]   <!-- the current master version; close-delta bumps the minor at the end of the chain -->
 
+**Model delta**: `specs/[Context]/domain-model.[CR-ID].delta.md`   <!-- "none" when this change is behaviour-only -->
+
 <!--
   A change request is a DELTA on the feature's existing spec.md — never a new spec.
   Classify every item ADDED / MODIFIED / REMOVED against the current master, using
-  the SAME vocabulary as the master spec: System Requirements in EARS, Business
-  Rules (BR-n) as invariants, User Stories with Given/When/Then acceptance criteria,
-  and — where their rules apply — Constraints & NFRs (CN-n), Data Classification
-  (DC-n), Integration Contracts (IC-n) and Experience 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
-  design.ui.md settle. Adding a command (e.g. UpdateOrder to the Order aggregate) is a new
-  user story (US-n), NOT a new feature. Feature = aggregate (see spec-template.md).
+  the SAME vocabulary as the master spec: System Requirements in EARS, User Stories with
+  Given/When/Then acceptance criteria, and — where their rules apply — Constraints & NFRs
+  (CN-n), Data Classification (DC-n), Integration Contracts (IC-n) and Experience
+  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.
+
+  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"
+  file named above, authored by the SAME specify run. Cite invariants here by id; state
+  behaviour here, structure there.
+
+  WAVE — the parallel-development dependency level. Deltas sharing a wave are independent
+  and may be developed at the same time; a wave-N+1 delta is implemented only after every
+  wave-N delta has landed. Scripts stamp it — use `cr-wave` to change it, never a hand edit.
 -->
 
 ## Change summary
@@ -28,7 +40,7 @@
 
 ## ADDED
 
-<!-- New user stories, system requirements, business rules, entities, or lifted items (CN/DC/IC/UX). -->
+<!-- New user stories, system requirements, or lifted items (CN/DC/IC/UX). A new entity or invariant is a MODEL change — put it in the domain-model delta and cite it here by id. -->
 
 - **US-[n] — [title]** (Priority: P?)
   - **Why this priority**: [the value and why it ranks here]
@@ -36,28 +48,42 @@
   - **Acceptance**: Given [state], When [action], Then [outcome]
   - **Independent test**: [how this story is verified on its own]
 - **FR-[nnn]**: WHEN [trigger] THE SYSTEM SHALL [response]   <!-- EARS — pick the fitting pattern -->
-- **BR-[nnn]**: [a new invariant that must always hold] — or `None`
 - **CN-[nnn]**: [new constraint / NFR — retention, immutability, audit, performance-as-a-limit; cite lifted source] — or `None`
 - **DC-[nnn]**: [new data-classification category or exposure rule] — or `None`
 - **IC-[nnn]**: [new integration contract / interop obligation] — or `None`
 - **UX-[nnn]**: [new project-wide experience standard — accessibility, interaction states, content, journey integrity, responsiveness-as-a-limit; cite lifted source] — or `None`
-- **Entity**: [new entity / value object + what it represents] — or `None`
 
 ## MODIFIED
 
 - **FR-[nnn]**: was [old] → now [new]   <!-- keep EARS form -->
-- **BR-[nnn]**: was [old] → now [new]
 - **CN-[nnn]** / **DC-[nnn]** / **IC-[nnn]** / **UX-[nnn]**: was [old] → now [new]
 - **US-[n]**: [what changes and why]
 
 ## REMOVED
 
-- [FR / BR / CN / DC / IC / UX / US / entity removed and why] — or `None`
+- [FR / CN / DC / IC / UX / US removed and why] — or `None`
+
+## Model changes *(summary — the authority is the domain-model delta)*
+
+<!--
+  A one-line pointer per model element this change touches, so a reader of the delta-spec
+  can see at a glance whether the model moves with it. The ACTUAL definitions live in the
+  "Model delta" file named in the header, and finalize-delta merges them into
+  specs/[Context]/domain-model.md. "None — behaviour only" is a common, valid answer.
+-->
+
+- **Aggregates touched**: [Root] — or `None — behaviour only`
+- **New / changed invariants**: [BR-nnn] — defined in the model delta, cited here
+- **Wave rationale**: [why this wave — "independent" or "builds on CR-xxx (wave N-1)"]
 
 ## Impact
 
-- **Affected FR / BR / CN / DC / IC / UX / US / SC**: [ids]
+- **Affected FR / CN / DC / IC / UX / US / SC**: [ids]
 - **Regression risk**: [existing behaviour that must still hold — e.g. CreateOrder must still pass]
+- **Other open deltas**: [CR-ID (wave N) touching the same FRs or the same aggregate — or `none`]
 - **On merge**: the new US-[n] is tagged `Added: (this CR)` in the master; finalize-delta
-  merges this delta into spec.md + design.md and appends the Change History row, and
-  close-delta (after analyze-slice) archives the change and bumps the minor version.
+  merges this delta into spec.md and its model delta into domain-model.md — the two
+  documents that DEFINE the slice, in one transaction — and appends the spec's Change
+  History row. The lane plans are not merged: they are derived from those two and are
+  re-derived from them. close-delta (after analyze-slice) archives the change and bumps
+  the minor version.