aw-spec-cli 0.1.16 → 0.1.18

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

@@ -1,57 +1,41 @@
-# Design: [AGGREGATE]
+# Backend Plan: [AGGREGATE]
 
 **Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
 
-**Design home**: `specs/[Aggregate]/backend-plan.md`  <!-- the service lane; the frontend twin is frontend-plan.md, owned by /appweaver plan-ui -->
+**Plan home**: `specs/[Aggregate]/backend-plan.md`
 
 **Source spec**: `specs/[Aggregate]/spec.md`
 
-**Version**: v1.0   <!-- SCRIPT-OWNED: plan-stamp sets this to the spec version this plan derives from. Never edit it by hand. -->
+**Version**: v1.0   <!-- moves in lockstep with the spec; every applied change request bumps this — see Change History -->
 
 **Status**: Draft
 
 <!--
   WHAT THIS DOCUMENT IS
   =====================
-  The single, living High-Level Design (HLD) for ONE aggregate — the FEATURE-LEVEL
-  ARCHITECTURAL CONFIRMATION. 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.
+  The single, living High-Level Design (HLD) for ONE aggregate. 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  ──▶  story-backend-plan.md  ──▶  code (+ tests)
-    behaviour     structure &          the story's slice          generated by `implement`
-    (FR/BR/CN/SC) decisions (HLD)      (concrete, ephemeral)
-
-  It is LONG-LIVED and moves FORWARD with the spec: /appweaver plan authors it, and
-  conforms it whenever the spec's Change History says something it realises has moved.
-  Story designs READ it and never write back — nothing merges into this document.
+    spec.md  ──▶  backend-plan.md  ──▶  code (+ tests)
+    behaviour     structure &       generated by `implement`
+    (FR/BR/US/SC) decisions (HLD)    (stack-bound at generation time)
 
   ANCHORING RULES
-  - Every design element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/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.
+  - 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).
-  - THE CODE IS THE WHAT-EXISTS INPUT, and it is a different authority from the spec.
-    Where code already realises this feature, the plan describes and ADJUSTS TO the
-    structure that is actually there rather than an idealised one, and names any
-    deliberate divergence as a §8 WA-n. The code never overrides the spec on
-    BEHAVIOUR, and it may not introduce a domain rule the spec omits — code that
-    contradicts the spec is a finding to report, not a design to bless.
-  - NO STORY IDS ANYWHERE IN THIS DOCUMENT. Stories live in stories/ and cite the
-    requirement ids they deliver; this design traces to FR-/BR-, which is what keeps
-    it stable while the backlog churns, is reprioritised and is re-raised.
-  - Feature = aggregate. Commands (CreateOrder, UpdateOrder…) are REQUIREMENTS
-    (FR-n) in the spec, not features and not stories. One aggregate = one
-    backend-plan.md = one owning design for its code files. A later requirement is
-    CONFORMED into this document by /appweaver plan's update mode — never a new
-    design doc, and never a delta document.
+  - 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.
 
   WHAT LIVES ELSEWHERE (do NOT repeat it here — it is identical for every feature)
   - The clean-architecture layering + dependency rule (API → Application → Domain
@@ -63,13 +47,6 @@
   - Physical persistence (PKs/FKs, columns, indexes, JSON shapes, migration SQL)
     belongs to a technical-data-model. This doc states WHAT is stored and WHICH
     port persists it, not the schema.
-  - THE PUBLISHED SURFACE belongs to `interfaces.md`, this feature's APPEND-ONLY
-    interface log — the anchor the frontend lane designs against. /appweaver plan
-    publishes each entry there (the script assigns IF-nnn, the date and
-    status: proposed); /appweaver plan-ui and the FE story designs READ the latest
-    entry per id. §3 here is the INDEX that cites those ids, never a second copy of
-    the contract: two copies drift, and only the log has a lifecycle and a
-    supersedes: chain.
 
   TECHNOLOGY-AGNOSTIC (mandatory)
   - Express behaviour as SIGNATURES + pre/post/invariant/raises pseudocode and
@@ -117,13 +94,16 @@ trade-off. Layering follows the project architecture standard (constitution).]
 ## 1. Domain Layer
 
 <!--
-  FOLLOW spec.md EXACTLY. This is not a fresh model — it is the DDD elaboration of
-  what the spec already fixes:
-    • Entities & value objects  = the spec's "Key Entities" (SAME names).
-    • Invariants                = the spec's "Business Rules" (BR-nnn) — cite each.
-    • Aggregate boundary        = the spec's "Scope & Assumptions → Aggregate Boundary"
+  FOLLOW THE CONTEXT'S DOMAIN MODEL EXACTLY — specs/[Context]/domain-model.md. This is
+  not a fresh model; it is the DDD elaboration of what the model already fixes, and the
+  model is the canonical definition every spec in the context cites:
+    • Entities & value objects  = the model's `## Aggregate: <Root>` entities (SAME names).
+    • Invariants                = the model's Invariants (BR-nnn) — cite each, never restate.
+    • Aggregate boundary        = the model's "Boundary" block
                                   (owns vs references-by-id vs out-of-scope).
-    • Lifecycle / states        = the states the spec describes.
+    • Lifecycle / states        = the states the model describes.
+  The SPEC supplies behaviour — requirements, stories, lifted CN-/DC-/IC-/UX- items —
+  and cites the invariants by id. Structure comes from the model, behaviour from the spec.
     • Domain-derived constraints = the spec's "Constraints & NFRs" (CN-nnn) that are
                                   structural here — e.g. immutability, append-only audit,
                                   no-hard-delete → realised as VO immutability, a domain
@@ -138,7 +118,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
   invariants, behaviours). Repeat the blocks as the aggregate needs.
 -->
 
-### 1.1 Aggregate structure *(from the spec's Aggregate Boundary — verbatim)*
+### 1.1 Aggregate structure *(from the domain model's Boundary — cite, never restate)*
 
 - **Aggregate root**: `[Root]` — [what it guards; the transaction boundary]
 - **Entities (owned)**: `[Entity]` — [role]; …
@@ -151,7 +131,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
 
 | Event | Raised by | Trigger | Key payload | Serves |
 |---|---|---|---|---|
-| `[EntityStateChanged]` | `[Root/Entity]` | [what causes it] | `[id, key fields]` | FR-00X · BR-00Z |
+| `[EntityStateChanged]` | `[Root/Entity]` | [what causes it] | `[id, key fields]` | FR-00X · US-Y |
 
 ### 1.3 Entities
 
@@ -185,7 +165,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
   Invariant:      [what must hold — maps to a spec BR-nnn]
   Post-condition: [resulting state / outputs]
   Raises:         [DomainEvent]
-  Serves:         FR-00X · BR-00Z
+  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)*
@@ -205,13 +185,13 @@ trade-off. Layering follows the project architecture standard (constitution).]
   Purpose:  [why this can't live on one entity]
   Steps:    1. … 2. … 3. …
   Touches:  [aggregates/ports coordinated]
-  Serves:   FR-00X
+  Serves:   FR-00X · US-Y
 ```
 
 ## 2. Application Layer
 
 <!--
-  Use-cases: one command/query per requirement action (FR-n), its handler's orchestration,
+  Use-cases: one command/query per user-story action, its handler's orchestration,
   the ports it depends on, application-level rules (authorization, input validation,
   transaction + event publication), and the request/response DTO shapes. Consumes
   Domain types and the PORTS the Domain/Application defines; NEVER touches
@@ -229,9 +209,9 @@ trade-off. Layering follows the project architecture standard (constitution).]
 
 ### 2.2 Use-cases (commands / queries)
 
-<!-- One block per use-case = one requirement action. This is the LLM's unit of work. -->
+<!-- One block per use-case = one user-story action. This is the LLM's unit of work. -->
 
-#### `[Command/Query]` — Serves FR-00X
+#### `[Command/Query]` — Serves US-Y · FR-00X
 
 - **Type**: command (writes) | query (reads)
 - **Request (DTO)**: `{ [field]: [type], … }`
@@ -247,41 +227,33 @@ trade-off. Layering follows the project architecture standard (constitution).]
     4. [persist via port]  (single transaction boundary)
     5. [publish domain events]
     6. return [Response]
-    On failure: [which error → which published-interface status; the contract is the
-                 IF- entry cited in §3]
+    On failure: [which error → which API status in §3]
   ```
 - **Emits**: `[DomainEvent]` (from §1.2)
 
-## 3. API Layer — the published surface (INDEX; the wording lives in `interfaces.md`)
+## 3. API Layer
 
 <!--
-  The contract other systems and the frontend couple to. Describe it at PROTOCOL level
-  (REST assumed per the constitution — adapt for gRPC/GraphQL/CLI if the stack differs),
-  NEVER as controller code. Delegates to an Application use-case; no business logic here.
-
-  WHERE IT LIVES. Each published interface is an entry in `specs/[Aggregate]/interfaces.md`,
-  the append-only interface log: route/verb, auth, request and response shapes, status
-  codes and the error contract. `plan` publishes those entries — the script assigns the
-  IF-nnn id, the date and status: proposed — and `plan-ui`, the FE story designs and any
-  consuming feature read the LATEST entry per id. This section is the INDEX only.
-
-  HOW TO FILL IT
-  - An interface that ALREADY has an entry in the log (it is in context on an update
-    run): cite its IF- id here, and describe nothing.
-  - An interface being published for the FIRST TIME in this run: describe it in the
-    "Interface" cell in one line and leave the IF- id cell as `(this run)` — the log
-    assigns the real id after this document is written, and the next update run cites
-    it. Never invent an IF- number: the script is the only id authority.
-  - CHANGING a published interface is a NEW entry that supersedes the old one, never
-    an edit to the existing entry and never a change to this table alone.
-  - Every row cites the spec ids it serves and the use-case that implements it, so
-    §6 Traceability and the analyze gate can follow the chain both ways.
+  The contract other systems couple to. Describe it at PROTOCOL level (REST assumed
+  per the constitution — adapt for gRPC/GraphQL/CLI if the stack differs), NOT as
+  controller code. Pin route, verb, auth, request/response shape, status codes, and
+  the error contract. Delegates to an Application use-case; no business logic here.
 -->
 
-| Interface | IF- id | Serves | Implemented by |
-|---|---|---|---|
-| `[VERB] [/route]` — [purpose] | IF-00n | FR-00X | `[Command/Query]` (§2.2) |
-| `[DomainEvent]` published outside this feature | (this run) | FR-00X · BR-00X | §2.2 emits, §1.2 |
+### `[VERB] [/route]` — [purpose] · Serves US-Y · FR-00X
+
+- **Auth**: [required role/scope]
+- **Request**: `[path/query params]` + body `{ [field]: [type], … }`
+- **Success**: `2xx` → `{ [response shape] }`
+- **Errors** *(the error contract)*:
+
+  | Status | When | Body shape |
+  |---|---|---|
+  | 400 | [validation failure] | `{ errors: [{ field, message }] }` |
+  | 403 | [unauthorized] | `{ error }` |
+  | 409 | [conflict / duplicate — maps to a BR] | `{ error }` |
+
+- **Maps to**: `[Command/Query]` (§2.2)
 
 ## 4. Infrastructure Layer
 
@@ -347,12 +319,12 @@ trade-off. Layering follows the project architecture standard (constitution).]
 ## 6. Traceability (the spine)
 
 <!--
-  The two-way guarantee: every FR/BR/CN/DC/IC/SC has a design home, and every
+  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
   MUST appear as a row here (that is how the analyze gate proves no lifted constraint
-  was dropped). The Domain rows MUST match the spec's Key Entities and Business Rules
-  exactly.
+  was dropped). The Domain rows MUST match the domain model's entities and BR-nnn
+  invariants exactly.
 -->
 
 | Spec id | Type | Design element(s) | Layer |
@@ -362,6 +334,7 @@ trade-off. Layering follows the project architecture standard (constitution).]
 | 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] |
 
 ## 7. Assumptions (to clarify later)
@@ -399,19 +372,16 @@ trade-off. Layering follows the project architecture standard (constitution).]
 ## 9. Change History
 
 <!--
-  The living-truth ledger, in lockstep with spec.md — MANDATORY, and the one section
-  whose loss is refused rather than absorbed: plan-stamp writes no baseline at all if
-  this section went missing, so a dropped ledger can never be silently stamped over.
-
-  SCRIPT-OWNED. `plan-stamp` is the only writer: it appends one row per update naming
-  the requirement ids conformed, and moves the **Version** header to the spec version
-  this plan now derives from. The model writes NO version and NO row, ever — not here,
-  not in the header. Newest last.
-
-  Three columns, matching exactly what the stamp writes: the derived spec version, the
-  date, and what changed (the conformed ids are carried in that cell).
+  The living-truth ledger. A row is appended when this plan is RE-DERIVED to carry a
+  change — this document is derived from spec.md and the context's domain-model.md, and
+  finalize-delta merges a change into those two, never into this one. close-delta archives
+  the CR, bumps the minor version in active_version.json and stamps that number into this
+  document's **Version** header, so a header ahead of the newest row below means exactly
+  what it says: the plan has not been re-derived since that version. A change to this
+  aggregate is planned as a DELTA (delta-design: ADDED / MODIFIED / REMOVED sections) in
+  the change's own directory, never as a new design doc. Newest last.
 -->
 
-| Version | Date | Change |
-|---------|------|--------|
-| v1.0 | [DATE] | Initial design |
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial design | US-1 | — |

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

@@ -0,0 +1,130 @@
+# Domain Model — [BOUNDED CONTEXT]
+
+**Bounded context**: `[Context]`
+
+**Model home**: `specs/[Context]/domain-model.md`
+
+**Context version**: v1.0   <!-- script-stamped; close-delta bumps it when a closing delta touched the model -->
+
+<!--
+  THE CANONICAL DOMAIN MODEL FOR THIS BOUNDED CONTEXT. The aggregate root lives HERE
+  and nowhere else — not in any spec.md. Every spec in specs/[Context]/ REFERENCES the
+  aggregates, entities and invariants below by name and id, and never restates them.
+
+  Why here and not in the spec: an aggregate root is a fact about the CONTEXT, not about
+  one feature. Aggregates are referenced across specs, and a per-spec copy of the same
+  root drifts — two specs end up asserting different invariants for one aggregate and
+  nothing arbitrates. One home means there is nothing to arbitrate.
+
+  This document is AUTHORED, not derived. It legitimately holds things no single spec
+  states: cross-aggregate invariants, the context map, and aggregates that exist for
+  consistency reasons alone.
+
+  WRITERS, in order:
+    • specify (first run in this context) — creates it and models the first aggregate(s).
+    • specify (later runs) — writes specs/[Context]/domain-model.<CR-id>.delta.md instead;
+      the master is untouched while a change is open.
+    • finalize-delta — merges a delta into this file, ONE `## Aggregate:` SECTION AT A TIME.
+    • close-delta — stamps the context version and appends the Change History row.
+  plan / implement READ this file and never write it. It is technology-agnostic: no
+  language, no persistence, no framework. Where an invariant is ENFORCED is a plan
+  concern and is recorded in backend-plan.md, never here.
+
+  MERGE UNIT = one `## Aggregate: <Name>` section. Two open deltas touching DIFFERENT
+  aggregates never collide; two touching the SAME one are a real semantic conflict and
+  are gated rather than silently merged.
+-->
+
+## Ubiquitous Language
+
+<!--
+  ACTION REQUIRED: the terms this context uses, and what each means HERE. The same word
+  can mean something different in another context — that is the point of the boundary.
+  Every spec, plan and test in specs/[Context]/ uses these terms and no synonyms.
+-->
+
+| Term | Means in this context | Not to be confused with |
+|---|---|---|
+| [Order] | [a customer's committed request for goods] | [Cart — uncommitted, in the Sales context] |
+
+## Aggregate: [Root]
+
+<!--
+  ONE SECTION PER AGGREGATE ROOT. This is the merge unit — repeat the whole block for
+  each root. `Serving specs` lists the features whose spec.md references this aggregate;
+  it is what makes a cross-spec aggregate visible from the model side.
+-->
+
+**Serving specs**: `[Feature]`, `[OtherFeature]`   <!-- features that reference this aggregate -->
+
+**Last changed**: v1.0 · [CR-ID or "initial"]
+
+### Boundary
+
+- **Owns**: [entities/behaviour inside the consistency boundary — e.g. Order, OrderLine]
+- **References (by id, not owned)**: [CustomerId, ProductId — no navigable link]
+- **Out of scope / non-goals**: [explicitly excluded — e.g. payment settlement]
+
+### Entities
+
+- **[Root — e.g. Order]** *(aggregate root)*: [what it represents; key attributes; lifecycle/states, e.g. Draft → Submitted → Fulfilled]
+- **[Entity — e.g. OrderLine]**: [what it represents; relationship to the root]
+
+### Value objects
+
+- **[VO — e.g. Money]**: [what it represents; why it has no identity]
+
+### Domain events
+
+| Event | Raised by | Trigger | Key payload |
+|---|---|---|---|
+| `[OrderSubmitted]` | `[Order]` | [what causes it] | `[orderId, total]` |
+
+### Invariants
+
+<!--
+  ACTION REQUIRED: constraints that must ALWAYS hold for this aggregate, independent of
+  any single operation. STABLE ids (BR-nnn) — specs cite these ids and never restate the
+  rule. An invariant belongs to the aggregate, and the aggregate belongs to the context,
+  which is why it is defined here rather than in any one spec.
+-->
+
+- **BR-001**: [An order's total MUST never be negative.]
+- **BR-002**: [A submitted order MUST always have at least one line item.]
+
+## Cross-Aggregate Invariants
+
+<!--
+  Rules that span two or more aggregates in this context, and therefore belong to no
+  single spec and no single aggregate section. Eventually-consistent by nature — an
+  aggregate is the transaction boundary, so a rule crossing one cannot be enforced
+  atomically. State the rule and how convergence is expected, never the mechanism.
+  "None (as of v1.0)" when there are none — never delete the section.
+-->
+
+- **XBR-001**: [A Customer's credit exposure across all open Orders MUST NOT exceed their limit. Converges on OrderSubmitted.]
+
+## Context Map
+
+<!--
+  This context's relationships to OTHER bounded contexts: upstream/downstream direction,
+  and the pattern (customer-supplier, conformist, anti-corruption layer, shared kernel,
+  published language). References across a context boundary are ALWAYS by id.
+  "None (as of v1.0)" while this is the only context.
+-->
+
+| Other context | Direction | Pattern | What crosses |
+|---|---|---|---|
+| [Billing] | downstream | [customer-supplier] | [OrderSubmitted event; OrderId] |
+
+## Change History
+
+<!--
+  The model's living-truth ledger. close-delta appends a row when a closing delta touched
+  this model, carrying the context version it ships as and the aggregate it changed.
+  The model never writes its own version — scripts stamp it. Newest last.
+-->
+
+| Context version | Date | Aggregate | Change | Feature | CR |
+|---|---|---|---|---|---|
+| v1.0 | [DATE] | [Root] | Initial model | [Feature] | — |

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

@@ -76,7 +76,7 @@ ui_source_files:
 
 <!--
   2–4 sentences: the aggregate root, what it guards, its transaction boundary.
-  Greenfield: distilled from design.md §1 (Domain Model). Brownfield: from the
+  Greenfield: distilled from the context's domain-model.md. Brownfield: from the
   reverse-engineered spec/design. Prose only — the edges live in the two tables below.
 -->
 
@@ -86,7 +86,7 @@ ui_source_files:
 
 <!--
   FORWARD edges — the sibling aggregates THIS one references. Derived DETERMINISTICALLY
-  from design.md §1 — the model section, "References (by id, not owned)" — plus its
+  from domain-model.md — the aggregate's Boundary block, "References (by id, not owned)" — plus its
   External integrations table (Integration Contracts), kept
   to targets that are real project aggregates (a specs/<Target>/ or an existing concept).
   This is the PRUNE INDEX: reconcile-on-write reads it to find where this slice wrote, so

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

@@ -6,7 +6,7 @@
 
 **Origin**: `reverse-engineered`   <!-- greenfield | reverse-engineered | migrated -->
 
-**Version**: v1.0   <!-- moves in lockstep with spec.md / design.md -->
+**Version**: v1.0   <!-- moves in lockstep with spec.md / backend-plan.md -->
 
 **Baseline commit**: `[short-sha]`   <!-- the inventory HEAD this slice was adopted from -->
 
@@ -23,10 +23,10 @@
 
     LegacyArtefact ↔ FR/BR/US ↔ Spec-section ↔ Design-element ↔ Code ↔ Commit
 
-  This is a SIDECAR: spec.md and design.md stay clean, forward-loop documents
+  This is a SIDECAR: spec.md and backend-plan.md stay clean, forward-loop documents
   (the CR delta loop + forward pipeline consume them unchanged). The brownfield
   provenance lives HERE and in the `origin:` frontmatter — never as extra
-  structure inside spec.md / design.md.
+  structure inside spec.md / backend-plan.md.
 
   CONFIDENCE travels with each row: `certain` (the code states it outright) vs
   `inferred` (reverse-engineering had to reason). Inferred rows are the Adopt