aw-spec-cli 0.1.16 → 0.1.18

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

@@ -11,27 +11,21 @@
 **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 REQUIREMENT below (FR-n) — NOT a separate
-  feature and NOT a user story. A later requirement is a new FR-n added here,
-  never a new spec folder. One spec, and one PLAN per lane that derives from it:
-  specs/[Aggregate]/backend-plan.md (/appweaver plan) and, where a frontend lane is
-  declared, specs/[Aggregate]/frontend-plan.md (/appweaver plan-ui). Both move FORWARD
-  with this document and never write back to it.
-
-  THIS DOCUMENT HOLDS NO USER STORIES. A story is an execution SLICE over this
-  spec and lives beside it in stories/, citing the FR-/BR- ids it delivers. This
-  spec is authored ONCE and stories never merge back into it: when a story needs
-  the contract itself to change, update-spec folds it back through specify's
-  validate loop and appends a Change History row. Design and code trace to the
-  FR-/BR- ids here, never to a story id — which is what lets the backlog churn
-  without disturbing the design.
-
-  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.
+  THIS SPEC IS BEHAVIOUR, NOT STRUCTURE. It states what the system must DO and WHY.
+  What the domain IS — aggregate boundaries, entities, value objects, events and
+  invariants — lives in the bounded context's domain model, specs/[Context]/domain-model.md,
+  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
+  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 →
+  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
@@ -53,17 +47,26 @@
 
 ## Scope & Assumptions
 
-### Aggregate Boundary
+### Domain Model Reference
 
 <!--
-  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.
+  THE AGGREGATE IS NOT DEFINED HERE. Its boundary, entities, value objects, events and
+  invariants live in the bounded context's domain model —
+  specs/[Context]/domain-model.md — which is the single canonical definition every spec
+  in this context shares.
+
+  Name the aggregate(s) this spec's requirements act on and CITE the invariants they
+  rely on by id (BR-nnn). Never restate what an aggregate owns or what an invariant
+  says: a per-spec copy drifts, and once two specs assert different rules for one
+  aggregate nothing arbitrates between them.
+
+  If a requirement below needs an aggregate, entity or invariant the model does not
+  have yet, that is a MODEL change — it belongs in the same specify run's domain-model
+  delta, not in prose here.
 -->
 
-- **Owns**: [entities/behaviour inside this aggregate — e.g. Order, OrderLine]
-- **References (by id, not owned)**: [Customer, Product — read-only / by identifier]
+- **Acts on aggregate(s)**: `[Root]` — see `specs/[Context]/domain-model.md`
+- **Relies on invariants**: [BR-001, BR-002]
 - **Out of scope / non-goals**: [explicitly excluded — e.g. payment settlement, shipping]
 
 ### Assumptions
@@ -86,7 +89,7 @@
   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 frontend-plan.md, and putting them here
+  realisation decisions owned by the prototype and the frontend plan, 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
@@ -123,18 +126,6 @@
 - **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)*
 
 <!--
@@ -153,17 +144,6 @@
 - **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)*
 
 <!--
@@ -172,8 +152,8 @@
   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.
+  analyze-plan / analyze-slice gates check them. Give each a STABLE id (DC-001, …); reference fields by
+  the names the context's domain model defines.
 -->
 
 | id | Category | Applies to (fields / entities) | Exposure rule |
@@ -205,30 +185,30 @@
   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, plan-ui and implement-ui 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.
+  The lift is what makes them binding: the prototype phase and the FRONTEND LANES of plan
+  and 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 frontend-plan.md's
+  model, component or visual-design choice. Those are the prototype's and the frontend plan'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: plan-ui and the UI
+  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
+  gates (analyze-plan, 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 the requirements above describe is completable keyboard-only. — lifted from UX-II, ux/accessibility-standards.md]
+- **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 FR-n is completable without leaving this aggregate's surface; destructive actions are confirmed and reversible. — lifted from ux/journey-mapping.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-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
@@ -242,6 +222,55 @@
 - 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 and invariants (BR-n, defined in the
+  domain model) — 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)*
 
 <!--
@@ -256,67 +285,16 @@
 - **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%."]
 
-## Story Coverage
-
-<!--
-  GENERATED — DO NOT HAND-EDIT. Everything between the two AW:COVERAGE markers is
-  rewritten wholesale from the stories/ directory, which is the source of truth: each
-  story's `exercises:` frontmatter says which requirements it delivers, and this table is
-  that relation read the other way round. Hand-edit it and your edit is gone at the next
-  write; change who delivers what by editing the story.
-
-  It answers the question the contract cannot answer about itself — who is building this,
-  and what is nobody building. A requirement with no story is a requirement nobody has
-  started; a requirement whose stories are all closed is DELIVERED, which is the rule
-  analyze-code and the pre-deploy gate key on. "Delivered" is never "a story closed" —
-  a follow-on may still carry the remainder.
-
-  Scoped to FR- and BR-, because those are the ids a story cites. The lifted sections
-  (CN-/DC-/IC-/UX-) are constraints the design and the gates trace, not slices of work.
-
-  Fenced out of the ledger ON PURPOSE. The sha256 that guards this document covers the
-  CONTRACT, and this section is not contract — it is a projection of the backlog. Were it
-  inside the hash, creating a story would look like an unledgered spec edit and refuse the
-  next sync-stories; were it visible to the diff, adding a story would read as a
-  requirement change and mint a version row. So spec-check, spec-diff and ledger-append
-  all cut this block out before they look at anything.
--->
-
-<!-- AW:COVERAGE:BEGIN -->
-| Requirement | Open stories | Closed / cancelled |
-|-------------|--------------|--------------------|
-| _(none yet — run /appweaver sync-stories to raise the backlog)_ | | |
-<!-- AW:COVERAGE:END -->
-
 ## Change History
 
 <!--
-  The living-truth ledger, and the sync anchor between this spec and its story backlog.
-
-  Each row names the requirement ids that version touched. Every story records the spec
-  version it last synced at (spec_version: in its frontmatter), so a story is stale when
-  some row above its version names an id that story cites — one version comparison, no
-  per-requirement content hashing. sync-stories reads the rows to refresh the backlog;
-  update-spec appends one when it folds a hand-edited story back into this document.
-
-  The ledger is hand-written, so it is guarded. active_version.json carries a sha256 of
-  this whole file as of the last ledger-aware write. A body that has changed while the
-  version stands still is a hand edit that skipped the ledger: sync-stories and
-  check-stories refuse until a row is added, because otherwise every affected story goes
-  quietly stale and nothing says so.
-
-  Version numbers have a single writer, so the header, the newest row and
-  active_version.json never disagree: close-delta bumps the minor version in
-  active_version.json and stamps that same number into this document's **Version**
-  header. Newest last.
-
-  THE "Requirements changed" CELL IS GENERATED. specify computes it from a diff of the
-  document it just wrote — including the v1.0 row below, whose placeholder ids are
-  replaced with the ones the finished spec actually carries. A row that names the ids
-  somebody believed it changed is worth nothing to a story trying to find out whether it
-  is stale; only a row derived from the document is.
+  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 | Requirements changed | Stories |
-|---------|------|--------|----------------------|---------|
-| v1.0 | [DATE] | Initial specification | FR-001…FR-00n, BR-001…BR-00n | — |
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial specification | US-1 | — |

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

@@ -0,0 +1,159 @@
+# Delta Frontend Plan — [CR-ID]: [TITLE]
+
+**Feature (aggregate slice)**: `[Feature]`
+
+**Lane**: `[lane id]` — the frontend 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`
+
+**Service delta**: `changes/[CR-ID]/delta-backend-plan.md`   <!-- "none — experience-only change" when this change has no service half -->
+
+<!--
+  ONE CHANGE'S PLAN FOR THE FRONTEND LANE. It applies to the feature's master plan at
+  specs/[Context]/[Feature]/frontend-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
+  frontend 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 frontend-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. A UX- item of this change reaches the master through the SPEC's
+  Experience Standards, which is where finalize-delta merges it.
+
+  ONE CHANGE, TWO LANES, ONE VERSION. A change that touches both lanes produces this
+  document AND its service twin; the spec and model merge once for both and the
+  change closes on ONE version bump. This record never restates the service delta —
+  where a change starts in the service contract, this document records only what the
+  EXPERIENCE does with it.
+
+  THE LANE BOUNDARY IS THE PUBLISHED SURFACE. Bind against the delta-spec's IC- ids and
+  the service delta's "Contract deltas for the frontend lane" table — CITE those
+  contracts, never re-derive or contradict them, and introduce no server-side behaviour,
+  persistence assumption or handler detail. Anything the experience needs that the surface
+  does not offer is a CONTRACT DELTA raised back to the service lane, never a workaround
+  in the client.
+
+  STRUCTURE IS NOT PLANNED HERE. Entities, value objects and invariants (BR-n) belong to
+  the context's domain model; this document plans what the user SEES and DOES. Cite the
+  ids; never restate them. The ubiquitous language the model defines is the language this
+  plan's labels, states and messages use.
+
+  Classify every change ADDED / MODIFIED / REMOVED against the master, per the MASTER'S
+  OWN sections, in the same technology-agnostic form: responsibilities, inputs as field
+  shapes, events and states — no framework, no router, no state library, no component
+  library, no code. The stack binds at implement time.
+-->
+
+## Change summary
+
+[One paragraph: what the experience change is, and which delta-spec items (UX-/US-/FR-/
+CN-/DC-/IC-) it realises. "Realisation only — no spec delta" for a plan-only change.]
+
+## 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.
+  "None — stands alone" is the common and preferred answer.
+-->
+
+- `[CR-ID]` (wave [N-1]) — [what this plan assumes from it]
+
+## ADDED — new experience elements
+
+<!-- New screens, components, client state, interactions or contract bindings.
+     "Section" names a section of THIS feature's master frontend plan. -->
+
+| Section (§) | Element | Kind | Serves |
+|---|---|---|---|
+| Navigation & Screens (§1) | `[screen]` | screen | US-[n] |
+| Component Structure (§3) | `[component]` | component | US-[n] · FR-[nnn] |
+| Client State (§2) | `[state]` | state | FR-[nnn] · DC-[nnn] |
+| Contract Binding (§5) | `[VERB] [/route]` | binding | IC-[nnn] |
+
+## MODIFIED — existing experience elements
+
+<!-- Edits to elements the master already defines. A shared component or a shared state
+     container is modified here, IN PLACE — never copied into the change. -->
+
+| Section (§) | Element | What changes | Why |
+|---|---|---|---|
+| Component Structure (§3) | `[component]` | [the edit] | US-[n] |
+
+## REMOVED
+
+- [experience 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. A state the UI can reach that the delta-spec does not describe
+  is a SPEC gap: log it as a DA-n that routes back to specify, never invent the
+  requirement here.
+-->
+
+| Interaction | States added / changed | What the user sees | Serves |
+|---|---|---|---|
+| `[interaction]` | [states] | [per-state behaviour] | US-[n] · FR-[nnn] |
+
+## Contract impact
+
+<!--
+  What this change consumes from the service lane, taken from the service delta's
+  contract table: bindings added, changed, or no longer used. Anything the experience
+  requires that the surface does not offer goes under "Contract deltas needed" and is
+  raised back to the service lane. `None` when the binding surface is unchanged.
+-->
+
+| Contract | Consumed as | From |
+|---|---|---|
+| `[VERB] [/route]` | [what the screen does with it] | service delta / IC-[nnn] |
+
+**Contract deltas needed**: [what the service must add for this experience to work] — or `None`
+
+## Other open deltas
+
+<!--
+  Which OTHER open changes touch the same screens, shared components or state containers.
+  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.
+-->
+
+- `[CR-ID]` (wave [N]) — [what overlaps, and how this plan stays clear of it]
+
+## 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. The app shell, global layout and design system belong to no feature —
+cite them, never claim or redesign them here.]
+
+## Regression targets
+
+[Existing user stories / screens to re-verify because a shared component, a shared state
+container or a navigation edge changed.]
+
+## New assumptions / workarounds (from this change)
+
+<!-- Anything this change defers. It stays this document's record — the master's DA-n / WA-n
+     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]**: [deviation to clear later] — or `None`
+
+## On merge
+
+`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 and bumps the ONE version both
+lanes share. None of it is this document's job — it records the change, it does not apply it.