aw-spec-cli 0.1.14 → 0.1.16

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

@@ -2,13 +2,13 @@
 
 **Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
 
-**Design home**: `specs/[Aggregate]/design.ui.md`
+**Design home**: `specs/[Aggregate]/frontend-plan.md`  <!-- the frontend lane; the service twin is backend-plan.md, owned by /appweaver plan -->
 
 **Source spec**: `specs/[Aggregate]/spec.md`
 
 **Lane**: `[lane id]` — the frontend lane declared in `.appweaver/stacks.json`
 
-**Version**: v1.0   <!-- moves in lockstep with spec.md and design.md; one change closes on ONE bump -->
+**Version**: v1.0   <!-- SCRIPT-OWNED: plan-stamp sets this to the spec version this plan derives from. Never edit it by hand. -->
 
 **Status**: Draft
 
@@ -16,23 +16,36 @@
   WHAT THIS DOCUMENT IS
   =====================
   The single, living High-Level Design for ONE feature's EXPERIENCE — the
-  frontend lane's twin of design.md. It is the MEDIATOR between spec.md
-  (WHAT/WHY, tech-agnostic) and the frontend code `implement-ui` generates.
-  It carries screens, navigation, client state, composition, interaction and
-  the service binding. It is NOT code, and it is NOT a visual comp.
+  FEATURE-LEVEL ARCHITECTURAL CONFIRMATION for the frontend lane, twin of
+  backend-plan.md. It is the MEDIATOR between spec.md (WHAT/WHY, tech-agnostic)
+  and the frontend code `implement-ui` generates. It carries screens, navigation,
+  client state, composition, interaction and the service binding. It is NOT code,
+  and it is NOT a visual comp.
 
-    spec.md  ──▶  design.ui.md  ──▶  frontend code (+ tests)
-    behaviour     structure &          generated by `implement-ui`
-    (UX/US/FR/SC) decisions            (framework bound at generation time)
+    spec.md  ──▶  frontend-plan.md  ──▶  story-frontend-plan.md  ──▶  frontend code (+ tests)
+    behaviour     structure &           the story's slice           generated by `implement-ui`
+    (UX/FR/CN/SC) decisions             (concrete, ephemeral)
+
+  It is LONG-LIVED and moves FORWARD with the spec: /appweaver plan-ui 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 it.
 
   ANCHORING RULES
-  - Every element traces UP to a spec id (UX-/US-/FR-/CN-/DC-/IC-/SC-) and the
-    spec's experience obligations are covered DOWN here (§7 Traceability). No
-    screen without a spec reason; no user story without a screen home.
+  - Every element traces UP to a spec id (UX-/FR-/CN-/DC-/IC-/SC-) and the spec's
+    experience obligations are covered DOWN here (§7 Traceability). No screen
+    without a spec reason; no requirement without a screen home.
+  - NO STORY IDS ANYWHERE IN THIS DOCUMENT. Stories live in stories/ and cite the
+    requirement ids they deliver; this plan traces to UX-/FR-, which is what keeps
+    it stable while the backlog churns.
+  - THE CODE IS THE WHAT-EXISTS INPUT, and it is a different authority from the
+    spec. Where a frontend already realises this feature, ADJUST to the composition,
+    naming and state handling that are actually there rather than to an idealised
+    shape. The code never overrides the spec on required behaviour; a deliberate
+    divergence is a §9 WA-n.
   - UX- LIVES HERE AND ONLY HERE. The spec's Experience Standards are this
-    document's to realise — design.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 design.md keeps. This
+    document's to realise — backend-plan.md deliberately excludes them, so a UX-
+    that reaches neither plan 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 SERVICE LANE ENTERS ONLY AT §5. Cite the operations this surface
@@ -103,7 +116,7 @@
 
 | Screen | Purpose | Entered from | Leads to | Serves |
 |---|---|---|---|---|
-| `[Screen]` | [the decision made here] | [entry point] | [next screens] | US-[n] · FR-[nnn] |
+| `[Screen]` | [the decision made here] | [entry point] | [next screens] | FR-[nnn] · UX-[n] |
 
 **Route / navigation shape**: [how screens are addressed and nested, stated
 conceptually — a path pattern, a stack, a tab set — never named after a router.]
@@ -148,7 +161,7 @@ anything the service alone may decide. Cite the DC-/CN- id.]
 
 | Component | Responsibility | Inputs (field shape) | Events raised | Serves |
 |---|---|---|---|---|
-| `[Component]` | [single responsibility] | [field: type, …] | `[event]` | FR-[nnn] · US-[n] |
+| `[Component]` | [single responsibility] | [field: type, …] | `[event]` | FR-[nnn] · UX-[n] |
 
 ### 3.n [COMPOSITION AXIS NAME]
 
@@ -170,7 +183,7 @@ decision recorded in §8.]
 
 | Interaction | States | What the user sees | Serves |
 |---|---|---|---|
-| `[interaction]` | [idle → in-flight → success / error / empty / denied] | [per-state behaviour] | US-[n] · FR-[nnn] |
+| `[interaction]` | [idle → in-flight → success / error / empty / denied] | [per-state behaviour] | FR-[nnn] · UX-[n] |
 
 **Validation & feedback**: [when validation runs and how failures are surfaced,
 citing the BR-/FR- ids being echoed. A client-side check NEVER replaces the
@@ -187,22 +200,33 @@ a lost connection mid-flight.]
 ## 5. Contract Binding
 
 <!-- THE LANE BOUNDARY. One row per service operation this feature's UI depends
-     on. Bind against the service's PUBLISHED SURFACE — the spec's IC- ids and
-     the API contracts design.md states — and never against the service's
-     internals: no table, no handler, no persistence assumption crosses this
-     line. An interface the experience needs and the service does not offer is a
-     CONTRACT DELTA raised back to the service lane, never a workaround in the
-     client. -->
-
-| Screen / component | Operation | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
-|---|---|---|---|---|---|
-| `[Screen]` | `[operation]` | [field: type, …] | [field: type, …] | [the §4 state it produces] | FR-[nnn] · IC-[nnn] |
+     on. Bind against the service's PUBLISHED SURFACE — the entries in
+     `interfaces.md` (cited by IF- id) and the spec's IC- ids — and never against
+     the service's internals: no table, no handler, no persistence assumption
+     crosses this line. An interface the experience needs and the service does not
+     publish is raised back to the service lane, never worked around in the client. -->
+
+| Screen / component | Operation | IF- id | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
+|---|---|---|---|---|---|---|
+| `[Screen]` | `[operation]` | IF-00n | [field: type, …] | [field: type, …] | [the §4 state it produces] | FR-[nnn] · IC-[nnn] |
+| `[Screen]` | `[operation]` | (unpublished) | [field: type, …] | [field: type, …] | [the §4 state it produces] | FR-[nnn] |
 
 **Write semantics**: [per mutating operation — optimistic or pessimistic, what
 it invalidates, and how an optimistic update rolls back.]
 
-**Contract deltas needed**: [anything the experience requires that the service
-surface does not offer, raised back to the service lane. Or `None`.]
+**Contract gaps to raise**: [every row above whose IF- id reads `(unpublished)` —
+what the experience needs that `interfaces.md` does not yet carry. These are raised
+back to the service lane, which publishes them by running /appweaver plan; this lane
+never writes the log. Or `None`.]
+
+<!-- WHERE THE CONTRACT LIVES. The service lane's published surface is
+     `specs/[Aggregate]/interfaces.md` — the APPEND-ONLY interface log /appweaver plan
+     publishes. Bind to the LATEST entry per interface (an entry naming an earlier id
+     in `supersedes:` replaces it) and CITE IT BY IF- id in the rows above; never
+     restate the contract here, and NEVER write to the log — this lane consumes it.
+     An entry at `status: proposed` is the designed contract and is bindable. Where
+     the log does not exist yet (the service lane has not planned this feature), bind
+     from the spec's IC- ids and record a §8 DA-n saying so. -->
 
 ## 6. Cross-Cutting
 
@@ -227,13 +251,13 @@ surface does not offer, raised back to the service lane. Or `None`.]
 <!-- The two-way guarantee for the lane: every experience obligation in the spec
      has a home here, and every UI element has a spec reason. The last column
      names THIS document's own sections.
-     A US- with no screen is a coverage failure. A UX- with no row is a dropped
-     requirement — design.md does not carry them, so this is their only home. -->
+     An FR- with a UI surface and no screen is a coverage failure. A UX- with no row
+     is a dropped requirement — backend-plan.md does not carry them, so this is their
+     only home. -->
 
 | Spec id | Type | UI element(s) | Section |
 |---|---|---|---|
 | UX-[n] | experience standard | [where realised] | [§] |
-| US-[n] | story | [screens + flow realising it] | [§ refs] |
 | FR-[nnn] | requirement | [screen / component / state] | [§] |
 | CN-[nnn] | constraint | [where honoured in the UI] | [§] |
 | DC-[nnn] | classification | [what is withheld from the client] | §6 |
@@ -264,10 +288,18 @@ surface does not offer, raised back to the service lane. Or `None`.]
 
 ## Change History
 
-<!-- In lockstep with spec.md and design.md — a change that touches both lanes
-     closes on ONE version bump. finalize-delta appends the row; close-delta
-     bumps the version and stamps it into the header. Newest last. -->
+<!-- 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 it went missing, so a dropped ledger can never be silently stamped over.
+
+     SCRIPT-OWNED. `plan-stamp` is the only writer: one row per update naming the
+     requirement ids conformed, and the **Version** header moved to the spec version
+     this plan now derives from. The model writes NO version and NO row, ever.
+     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). -->
 
-| Version | Date | Change | User stories | CR |
-|---------|------|--------|--------------|-----|
-| v1.0 | [DATE] | Initial UI design | US-1 | — |
+| Version | Date | Change |
+|---------|------|--------|
+| v1.0 | [DATE] | Initial UI design |

package/assets/guardrails/projects/dotnet-default-project/domain-rule-bindings.md

@@ -70,11 +70,18 @@ through the spec/design (as CN-/DC-/IC- ids).
 - guardrails/domain/healthcare/api-versioning.domain.md
 - guardrails/domain/healthcare/vertical-slices.domain.md
 
-## /aw-spec-design
-_None — design loads no domain file. Domain reaches design only through the spec (BR-/CN-/DC-/IC-)._
+## /aw-spec-plan
+_None — the service lane's design loads no domain file. Domain reaches it only through the spec
+(BR-/CN-/DC-/IC-)._
+
+## /aw-spec-plan-ui
+_None — the frontend lane's design loads no domain file either, for the same reason: domain
+reaches frontend-plan.md as spec ids (UX-/CN-/DC-/IC-). Stated rather than left absent, because
+an absent heading and an empty one behave identically and only one of them is a decision._
 
 ## /aw-spec-implement
-_None — implement loads no domain file. Domain reaches implement only through design.md. Framework
+_None — implement loads no domain file. Domain reaches implement only through backend-plan.md and
+the story's design pass. Framework
 components are added separately via `/appweaver add-component`._
 
 ## /aw-spec-gate
@@ -104,10 +111,15 @@ components are added separately via `/appweaver add-component`._
 |---|---|---|
 | /aw-spec-constitution | 14 | domain principles (XVI+) — the industry constitution + standard industry rules + the project's own requirements |
 | /aw-spec-specify | 19 | author into spec (lift → CN-/DC-/IC-) |
-| /aw-spec-design | 0 | none — spec is the only domain input |
+| /aw-spec-plan | 0 | none — spec is the only domain input |
+| /aw-spec-plan-ui | 0 | none — spec is the only domain input |
 | /aw-spec-implement | 0 | none — design is the only domain input |
 | /aw-spec-gate | 14 | conformance checklist (validate, don't author) |
 
-> Retired in the orchestrator pipeline: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-taskplan`,
-> `/aw-spec-clarify`, `/aw-spec-analyze` (clarify folds into specify; plan/tasks into design). The
-> collapsed tiers `/aw-spec-fast-implement` and `/aw-spec-minimal-implementation` are pending a ruling.
+> Retired in the orchestrator pipeline: `/aw-spec-tasks`, `/aw-spec-taskplan`, `/aw-spec-clarify`,
+> `/aw-spec-analyze` (clarify folds into specify; tasks into the design phase). The collapsed tiers
+> `/aw-spec-fast-implement` and `/aw-spec-minimal-implementation` are pending a ruling.
+>
+> `/aw-spec-plan` is NOT retired. The name was once a dead phase and is now the LIVE service-lane
+> design command (`design` was renamed to `plan`, `design-ui` to `plan-ui`); its heading above is
+> current, and `/appweaver story-plan` reads the same slot.

package/assets/guardrails/projects/dotnet-default-project/tech-rule-bindings.md

@@ -15,7 +15,7 @@ NOT listed here — every consumer refers to it directly, as-is.
   `guardrails/technology/nextjs/` (the frontend lane). Both are **standard rules shared by
   every project that maps them**, and neither is domain-specific. The frontend corpus is
   read by three headings — `## /aw-spec-ui-constitution` ratifies the lane's base, and
-  `## /aw-spec-design-ui` / `## /aw-spec-implement-ui` carry the detail rules under it.
+  `## /aw-spec-plan-ui` / `## /aw-spec-implement-ui` carry the detail rules under it.
 - The two files this project authors — `service/technical-requirements.md` and
   `frontend/ui-requirements.md` — live beside this map. They are the only mapped technical
   files expected to differ between two projects on the same stacks.
@@ -64,7 +64,7 @@ NOT listed here — every consumer refers to it directly, as-is.
 
      ⚠ The ux/ files sit in a DOMAIN corpus folder but are TECHNICAL-tier inputs: a file's
      tier is the map that lists it, not the folder it lives in. guardrails/domain/healthcare/
-     ihe-conformance.md under ## /aw-spec-design is the same pattern. Unmapping them does not
+     ihe-conformance.md under ## /aw-spec-plan is the same pattern. Unmapping them does not
      make the spec's Experience Standards section disappear — the section is unconditional and
      resolves to "None" — it removes the methodology specify fills it from. -->
 - guardrails/technology/dotnet-webapi/domain-driven-design.md
@@ -74,10 +74,17 @@ NOT listed here — every consumer refers to it directly, as-is.
 - guardrails/domain/healthcare/ux/accessibility-standards.md
 - guardrails/domain/healthcare/ux/content-design.md
 
-## /aw-spec-design
+## /aw-spec-plan
 <!-- The technical/architecture rule files the design author works from (alongside the
-     spec and constitution.technical.md), each followed by its worked example. NO domain file
-     here — domain reaches design only as spec ids (BR-/CN-/DC-/IC-). -->
+     spec and constitution.technical.md), each followed by its worked example. Also read by
+     /appweaver story-plan, which reuses this slot deliberately: a story's execution design
+     answers to the same HOW rules as the feature plan it derives from.
+
+     NO DOMAIN-TIER FILE HERE — the domain reaches design only as spec ids (BR-/CN-/DC-/IC-).
+     The one bullet under guardrails/domain/ is not an exception to that: TIER IS DECIDED BY
+     THE MAP THAT LISTS A FILE, NOT BY THE FOLDER IT SITS IN, so ihe-conformance.md is bound
+     here as a TECHNICAL interop rule (the wire-level conformance the design must realise),
+     not as domain authoring input. Nothing from domain-rule-bindings reaches this phase. -->
 - guardrails/technology/dotnet-webapi/clean-architecture.md
 - guardrails/technology/dotnet-webapi/cqrs.md
 - guardrails/technology/dotnet-webapi/eventing.md
@@ -103,13 +110,13 @@ NOT listed here — every consumer refers to it directly, as-is.
 - guardrails/technology/dotnet-webapi/examples/authorization.md
 - guardrails/technology/dotnet-webapi/examples/auditing.md
 
-## /aw-spec-design-ui
-<!-- The FRONTEND LANE's design phase. Its own heading, not a branch of ## /aw-spec-design:
-     the two lanes are governed by different constitution halves and own disjoint source
-     paths, so keying the map on this command name gives the lane its own rule set for zero
-     mechanism change. NO domain file here — the domain reaches design.ui.md as spec ids,
-     exactly as it reaches design.md. The lane's ratified base (constitution.ui.md) is
-     referred to directly and is NOT mapped.
+## /aw-spec-plan-ui
+<!-- The FRONTEND LANE's design phase — /appweaver plan-ui, authoring frontend-plan.md. Its
+     own heading, not a branch of ## /aw-spec-plan: the two lanes are governed by different
+     constitution halves and own disjoint source paths, so keying the map on this command name
+     gives the lane its own rule set for zero mechanism change. NO domain file here — the
+     domain reaches frontend-plan.md as spec ids, exactly as it reaches backend-plan.md. The
+     lane's ratified base (constitution.ui.md) is referred to directly and is NOT mapped.
 
      THE SERVICE LANE ENTERS THROUGH ONE FILE. api-integration.{{backend_stack}}.md is the
      CROSS-LANE pairing rule set — what the service guarantees (paging shape, concurrency
@@ -119,8 +126,10 @@ NOT listed here — every consumer refers to it directly, as-is.
      api-integration.java-spring.md in a Spring repo — both authored — and to a REPORTED
      missing file for a backend whose pairing nobody has written yet, rather than silently
      loading one stack's assumptions into another. A repo with no backend lane skips the
-     bullet entirely. No other service-lane file is mapped here: design.ui.md consumes the
-     published surface, never the service's internals. -->
+     bullet entirely. No other service-lane file is mapped here, and none is needed: the
+     service's published surface reaches this lane as DATA, not as rules — specs/<F>/
+     interfaces.md, the append-only interface log /appweaver plan publishes, which
+     frontend-plan.md §5 binds to by IF- id. Never the service's internals. -->
 - guardrails/technology/nextjs/component-architecture.md
 - guardrails/technology/nextjs/routing-navigation.md
 - guardrails/technology/nextjs/state-management.md
@@ -135,8 +144,8 @@ NOT listed here — every consumer refers to it directly, as-is.
 
 ## /aw-spec-implement
 <!-- The FRAMEWORK / code-generation rule files the code generator builds against
-     (alongside design.md and constitution.technical.md). NO domain file — domain
-     reaches implement only through design.md. clean-architecture/cqrs are design
+     (alongside backend-plan.md, the story's design pass and constitution.technical.md).
+     NO domain file — domain reaches implement only through those. clean-architecture/cqrs are design
      concerns; component wiring is a separate /appweaver add-component step. -->
 - guardrails/technology/dotnet-webapi/coding-standards.md
 - guardrails/technology/dotnet-webapi/dependency-policy.md
@@ -146,9 +155,9 @@ NOT listed here — every consumer refers to it directly, as-is.
 
 ## /aw-spec-implement-ui
 <!-- The FRONTEND LANE's code-generation set — the HOW the UI generator builds against,
-     alongside design.ui.md and constitution.ui.md. NO domain file: domain reached the lane
-     through spec -> design.ui.md. NO service-lane file beyond the pairing rules below —
-     this phase never writes outside the lane's declared source path.
+     alongside frontend-plan.md and constitution.ui.md. NO domain file: domain reached the
+     lane through spec -> frontend-plan.md. NO service-lane file beyond the pairing rules
+     below — this phase never writes outside the lane's declared source path.
 
      EIGHT FILES ARE MAPPED FOR BOTH LANE PHASES on purpose. error-handling,
      forms-and-validation, auth-session, design-system, accessibility-implementation, i18n,
@@ -172,7 +181,7 @@ NOT listed here — every consumer refers to it directly, as-is.
 
 ## /aw-spec-implement-delta
 <!-- The CR analog of implement — same FRAMEWORK / code-generation set (HOW to build).
-     The delta's code is generated against the master design.md + delta-design.md; no
+     The delta's code is generated against the master backend-plan.md + delta-design.md; no
      domain file (domain reached the delta via delta-spec → delta-design). -->
 - guardrails/technology/dotnet-webapi/coding-standards.md
 - guardrails/technology/dotnet-webapi/dependency-policy.md
@@ -190,7 +199,7 @@ NOT listed here — every consumer refers to it directly, as-is.
 - guardrails/technology/dotnet-webapi/examples/clean-architecture.md
 
 ## /aw-spec-analyze-slice
-<!-- The design↔code conformance gate's TECHNICAL checklist: the code + tests are
+<!-- The spec↔code conformance gate's TECHNICAL checklist: the code + tests are
      validated against these (alongside the DOMAIN gate overlays, loaded separately via
      resolve-domain `## /aw-spec-gate`). Validation input only — never authoring. -->
 - guardrails/technology/dotnet-webapi/testing.md
@@ -246,13 +255,13 @@ NOT listed here — every consumer refers to it directly, as-is.
 | Command | Technical rule files | Role |
 |---|---|---|
 | /aw-spec-specify | 6 | the modelling methodology the spec is expressed in: DDD for the domain model (+ its example), and the four ux/ rules for the experience model it lifts as UX- ids — no technology |
-| /aw-spec-design | 24 | architecture/security/interop the design author mediates the spec against, each with its example |
-| /aw-spec-design-ui | 11 | the frontend lane's design set — composition, routing, client state, interaction states, forms, auth surface, design system, accessibility, i18n, performance, and the cross-lane API pairing the UI design author works from (from spec.md) |
-| /aw-spec-implement | 5 | governance/architecture the code generator builds against (from design.md) |
-| /aw-spec-implement-ui | 13 | the frontend lane's code-generation set the UI generator builds against (from design.ui.md) — conventions, the generated client + its service pairing, auth, client security, states, forms, design system, accessibility, i18n, performance, observability and testing |
+| /aw-spec-plan | 24 | architecture/security/interop the design author mediates the spec against, each with its example (also read by story-plan) |
+| /aw-spec-plan-ui | 11 | the frontend lane's design set — composition, routing, client state, interaction states, forms, auth surface, design system, accessibility, i18n, performance, and the cross-lane API pairing the UI design author works from (from spec.md + interfaces.md) |
+| /aw-spec-implement | 5 | governance/architecture the code generator builds against (from backend-plan.md + the story's design pass) |
+| /aw-spec-implement-ui | 13 | the frontend lane's code-generation set the UI generator builds against (from frontend-plan.md) — conventions, the generated client + its service pairing, auth, client security, states, forms, design system, accessibility, i18n, performance, observability and testing |
 | /aw-spec-implement-delta | 5 | same code-generation set, scoped to the open change's delta-design |
 | /aw-spec-build | 3 | layering + coding rules the compile-fixer respects, + the layering example |
-| /aw-spec-analyze-slice | 2 | testing + coding rules the design↔code gate validates against |
+| /aw-spec-analyze-slice | 2 | testing + coding rules the spec↔code gate validates against |
 | /aw-spec-constitution | 17 | what the technical half ratifies — the technology base, the standard technical rules, and the project team's technical-requirements.md |
 | /aw-spec-ui-constitution | 2 | what the frontend lane's half ratifies — the UI base + the project team's ui-requirements.md — and the signal that the lane exists |
 | /aw-spec-run | 2 | persistence rules the execution / data-migration step generates against, + its example |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aw-spec-cli",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "AppWeaver Spec-Driven Development CLI - scaffolds projects with vertical slices, DDD, CQRS, and agent skills",
   "type": "module",
   "main": "dist/index.js",