aw-spec-cli 0.1.18 → 0.1.19

package/assets/.appweaver/DESIGN-FORMAT.md

@@ -8,21 +8,32 @@ design document — not the engine. The authoring template is
 
 ## The contract
 
-A feature's design is **one document**, living beside its spec:
+A feature's design is **one document**, living beside its spec — and the domain it
+elaborates lives one level up, at the bounded context:
 
 ```
-specs/<Aggregate>/
-  spec.md      # behaviour (tech-agnostic) — WHAT / WHY — the source of truth
-  backend-plan.md    # structure & decisions (tech-agnostic HLD) — the MEDIATOR
-  changes/     # open + archived change records (delta-spec + delta-design)
+specs/<Context>/
+  domain-model.md        # STRUCTURE — aggregates, entities, invariants (BR-nnn) — shared
+  <Aggregate>/
+    spec.md              # BEHAVIOUR (tech-agnostic) — WHAT / WHY
+    backend-plan.md      # structure & decisions (tech-agnostic HLD) — the MEDIATOR
+    changes/             # open + archived change records (delta-spec + delta plans)
 ```
 
-`backend-plan.md` is the **mediator** between the spec and the generated code:
+**TWO AUTHORITIES, NOT ONE.** `domain-model.md` is the canonical definition of what the
+domain *is*; `spec.md` is the canonical definition of what the system must *do*. They are
+separate files because several specs in a context act on one aggregate, so a per-spec copy
+of an invariant drifts. The spec cites invariants by id (`BR-nnn`) and never restates them.
+
+`backend-plan.md` is the **mediator** between those two and the generated code:
 
 ```
-spec.md  ──▶  backend-plan.md  ──▶  code (+ tests)
-behaviour     structure &       generated by `implement`
-FR/BR/US/SC   decisions (HLD)    (stack bound at generation time)
+domain-model.md ─┐
+structure        ├─▶  backend-plan.md  ──▶  code (+ tests)
+BR-nnn           │    structure &          generated by `implement`
+spec.md        ──┘    decisions (HLD)       (stack bound at generation time)
+behaviour
+FR/US/SC/CN/DC/IC
 ```
 
 - **One design per aggregate.** The four clean-architecture layers (Domain,
@@ -34,8 +45,10 @@ FR/BR/US/SC   decisions (HLD)    (stack bound at generation time)
   **signatures + pre/post/invariant/raises**, use-cases, endpoint contracts, ports,
   and the significant technical decisions with rationale — but **no complete method
   bodies**. See `design-template.md` for the section structure (§0–§9). The domain
-  layer (§1) follows spec.md exactly — its entities/value-objects are the spec's Key
-  Entities and its invariants are the spec's Business Rules.
+  layer (§1) follows the context's `domain-model.md` exactly — its entities and
+  value-objects carry the model's names, its aggregate boundary is the model's Boundary
+  block, and its invariants **cite** the model's `BR-nnn` rather than restating them.
+  Behaviour comes from the spec, structure from the model.
 - **Technology-agnostic.** Behaviour and contracts use conceptual types, never a
   language. The SAME backend-plan.md must be generatable on a different stack. The target
   language/framework/persistence is bound only at `implement` time from the
@@ -145,12 +158,15 @@ The design document and the code are **not** a byte-for-byte copy of each other.
 ## The traceability spine
 
 ```
-FR/BR/US/SC ↔ design section (element / decision) ↔ code (+ tests) ↔ commit
+FR/US/SC/CN/DC/IC (spec)  ↔  design section (element / decision)  ↔  code (+ tests)  ↔  commit
+BR-nnn (domain model)     ↗
 ```
 
-Every design element traces **up** to a spec id, and the whole spec traces **down**
-into a design section (§6 Traceability). This is what makes the analyze gate and the
-review able to check coverage, and what keeps CR impact analysis exact.
+Every design element traces **up** to an id, and the whole spec traces **down** into a
+design section (§6 Traceability). The ids come from the two authorities: behaviour ids
+from `spec.md`, invariant ids (`BR-nnn`) from the context's `domain-model.md`. An element
+that traces to neither is an invention and the analyze gate raises it. This is what makes
+the gate and the review able to check coverage, and what keeps CR impact analysis exact.
 
 ## Feature granularity (why a command is a delta, not a new feature)
 
@@ -161,12 +177,20 @@ with a shared entity, **feature = the aggregate** (`Order`), and individual comm
 (`CreateOrder`, `UpdateOrder`, …) are **user stories / deltas** on the same backend-plan.md:
 
 - `CreateOrder` = US-1; `UpdateOrder` = US-2.
-- Adding `UpdateOrder` is an additive CR: a Delta Spec (`+US-2`) and a Delta Design
-  (`ADDED` new use-case/endpoint sections, `MODIFIED` the shared Order/root and
-  repository sections — see `delta-design-template.md`). The design phase amends
-  backend-plan.md doc-first, bumps the feature version (`v1.0 → v1.1`), and archives the CR;
-  `implement` regenerates the touched slice; regression re-tests the shared-file
-  dependents.
+- Adding `UpdateOrder` is an additive CR: a **delta-spec** (`+US-2`), the change's own
+  **model delta** where the domain moves, and **delta lane plans** (`ADDED` new
+  use-case/endpoint sections, `MODIFIED` the shared Order/root and repository sections —
+  see `delta-design-template.md`). All three live inside `changes/<CR-id>/`, and the
+  MASTERS are not touched while the change is open: `plan` writes
+  `delta-backend-plan.md` / `delta-frontend-plan.md` beside the delta-spec, never
+  `backend-plan.md`. `implement` generates only what the delta marks ADDED or MODIFIED;
+  regression re-tests the shared-file dependents.
+- **Nothing in the plan phase bumps a version or archives a change.** `finalize-delta`
+  MERGES the delta into `spec.md` and the context's `domain-model.md` (not the lane
+  plans — they are derived from those two and are re-derived by `/appweaver plan main`),
+  and `close-delta` is the sole stage that archives `changes/<CR-id>/` and moves the
+  version (`v1.0 → v1.1`). The two are deliberately separate so a red `analyze-slice`
+  between them is still "fix and re-run" rather than a change that already shipped.
 
 Two command-level features would both claim `src/Domain/Order.cs` and collide —
 which is exactly why the aggregate is the boundary.

package/assets/.appweaver/orchestrator/modules/delta-plan.orch.yaml

@@ -28,6 +28,12 @@
 #     wave means "after those land". So a lower-wave delta is committed to landing first
 #     and may be built on; a same-wave one is visible but is never assumed, because
 #     nothing orders the two against each other.
+#   • the SIBLING deltas — every open model delta at the SAME or a higher wave. VISIBLE
+#     is the operative word and the reason they are in context at all: this module tells
+#     the planner to name any sibling touching the same aggregate or component, and a
+#     planner that was never shown them can only stay silent — which the gate one stage
+#     later reads as a missed overlap. Their model deltas only, since the aggregate a
+#     sibling touches is what makes it an overlap.
 #
 # IT READS THE CODE. The feature's real source files arrive from its OKF concept
 # (concept-paths, resolved by the caller) as a PATH LIST, and the authoring steps declare
@@ -39,7 +45,8 @@
 # EXPECTS caller vars: feature_dir, spec_file, backend_plan, frontend_plan, domain_model,
 #   be_existing, fe_existing, fe_lane_id, source_files, source_count, USER_INPUT,
 #   and — resolved by the caller from the change it chose and activated — cr_id, cr_dir,
-#   delta_spec, delta_model, wave, predecessor_files, predecessor_count, sibling_count.
+#   delta_spec, delta_model, wave, predecessor_files, predecessor_count, predecessor_ids,
+#   sibling_count, sibling_ids, related_docs.
 # PRODUCES: delta_backend_plan, delta_frontend_plan, downstream_count, impact_report.
 # =============================================================================
 
@@ -66,7 +73,13 @@ vars:
   wave: "1"
   predecessor_files: []     # every open model delta in a LOWER wave — this delta's predecessors
   predecessor_count: "0"
+  predecessor_ids: ""
   sibling_count: "0"
+  sibling_ids: ""
+  # What actually goes into the authoring context: the predecessors' two halves AND the
+  # siblings' model deltas. Both kinds are SHOWN; the prompts say which ids carry which
+  # licence, because a planner asked to name an overlap has to be able to see one.
+  related_docs: []
   delta_backend_plan: ""
   delta_frontend_plan: ""
 
@@ -97,9 +110,13 @@ workflow:
   - id: ctx_backend_delta
     condition: "{{be_existing}} == true"
     action: build_context
-    context_from: predecessor_files          # the open model deltas in LOWER waves — committed
-                                             # to landing first, so this plan may build on them.
-                                             # Empty for a wave-1 delta, which is the common case.
+    context_from: related_docs               # every other open change's model delta, plus each
+                                             # PREDECESSOR's delta-spec. Two kinds, opposite
+                                             # licence: a LOWER-wave predecessor is committed to
+                                             # landing first and may be built on; a SAME-wave
+                                             # sibling may only be designed around. The prompt
+                                             # names which ids are which. Empty when this is the
+                                             # only open change, the common case.
     context:
       - "{{delta_backend_plan}}"             # the delta plan template to fill
       - "{{delta_spec}}"                     # the spec-side change (from specify)
@@ -144,11 +161,17 @@ workflow:
         invariant is ENFORCED. Cite ids; never restate what an invariant says. An item in
         the model delta with no row here is a structural change nothing implements.
       - THE EFFECTIVE MODEL IS master + this change's delta + the PREDECESSOR deltas in
-        context (open changes in a LOWER wave, committed to landing first). You MAY build
-        on a predecessor — record it under "## Depends on", which is what orders the
-        finalizes. You may NOT assume a same-wave delta: nothing orders it against this
-        one. Where one touches the same aggregate or element, say so under "Other open
-        deltas" and plan around it. Until merged, every one of them is a proposal.
+        context. {{predecessor_count}} predecessor(s) — open changes in a LOWER wave,
+        committed to landing first: {{predecessor_ids}}. You MAY build on one; record it
+        under "## Depends on", which is what orders the finalizes.
+      - {{sibling_count}} SIBLING change(s) are open at the same or a higher wave:
+        {{sibling_ids}}. Their model deltas are in context too, and the licence over them
+        is the opposite one — nothing orders them against this change, so you may NOT
+        assume any of them lands. Read each one and, where it touches an aggregate or an
+        element this plan also touches, say so by id under "Other open deltas" and plan so
+        that either order of merging works. If consuming one is genuinely unavoidable,
+        that is a dependency, not an overlap: record it under "## Depends on" and say the
+        wave must be raised. Until merged, every one of them is a proposal.
       - PUBLISH WHAT THE FRONTEND LANE NEEDS. Fill "## Contract deltas for the frontend
         lane" with every addition or change to this feature's published surface, as field
         shapes. That table is the only part of this document the frontend delta plan may
@@ -168,12 +191,33 @@ workflow:
         stamp those.
       Guidance: {{USER_INPUT}}
 
+  # ══════════ THE LANE SWAP — the frontend's rules replace the backend's ═══════
+  # The delta twin of the swap `plan` performs before its own master frontend sections.
+  # Sticky standards only accumulate, and the caller loaded BOTH lanes' rule sets before
+  # including this module, so without this the service delta plan is authored with the UI
+  # rules in its envelope and the experience delta plan with the service rules. `replace`
+  # resets to the workflow's declared seed and loads `## /aw-spec-plan-ui`, so the backend
+  # delta above kept the service set and everything below this line is the frontend's.
+  #
+  # Conditioned on the same flag as the lane it precedes: a change with no frontend half
+  # authors nothing here and must not have its envelope swapped out from under the
+  # xref step that follows.
+  - id: tech_select_ui_delta
+    condition: "{{fe_existing}} == true"
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-plan-ui, replace: "true" }
+
   # ═════════════════════ FRONTEND LANE — the experience delta plan ═════════════
   - id: ctx_frontend_delta
     condition: "{{fe_existing}} == true"
     action: build_context
-    context_from: predecessor_files          # the same lower-wave model deltas — the ubiquitous
-                                             # language and the aggregates this change assumes
+    context_from: related_docs               # the same two kinds as the service lane: lower-wave
+                                             # predecessors (the ubiquitous language and the
+                                             # aggregates this change may assume) and same-wave
+                                             # siblings (visible, never assumed — this lane shares
+                                             # screens and components, so an unseen sibling is an
+                                             # unseen collision). The prompt names which is which.
     context:
       - "{{delta_frontend_plan}}"            # the delta plan template to fill
       - "{{delta_spec}}"                     # the spec-side change (UX-/US-/FR- items)
@@ -225,9 +269,13 @@ workflow:
         labels, states and messages — the same terms, no synonyms — and cite BR-nnn rather
         than restating a rule.
       - THE EFFECTIVE MODEL IS master + this change's delta + the PREDECESSOR deltas in
-        context (open changes in a LOWER wave). You MAY build on a predecessor — record it
-        under "## Depends on". You may NOT assume a same-wave delta; where one touches the
-        same screens or shared components, say so under "Other open deltas".
+        context. {{predecessor_count}} predecessor(s) — open changes in a LOWER wave:
+        {{predecessor_ids}}. You MAY build on one; record it under "## Depends on".
+      - {{sibling_count}} SIBLING change(s) are open at the same or a higher wave:
+        {{sibling_ids}}. Their model deltas are in context and nothing orders them against
+        this change, so you may NOT assume any of them lands. Where one touches the same
+        screens, shared components or contract surface, say so by id under "Other open
+        deltas" and plan so that either order of merging works.
       - TECHNOLOGY-AGNOSTIC: no framework, router, state library, component library or
         styling approach — responsibilities, field shapes, events and states only. The
         header's Lane field is `{{fe_lane_id}}`.

package/assets/.appweaver/orchestrator/modules/delta-spec.orch.yaml

@@ -48,10 +48,12 @@ scripts:
 
 workflow:
 
-  # Open the change + scaffold its THREE documents: delta-spec and delta-design under
-  # changes/<cr-id>/, and the model delta BESIDE the context's master model. Many
-  # changes may be open at once — every specify call on an established feature opens
-  # its own, and the wave is what orders them.
+  # Open the change + scaffold its TWO documents: the delta-spec under changes/<cr-id>/,
+  # and the model delta BESIDE the context's master model. The delta PLANS are not
+  # scaffolded here — `plan` owns them and creates them with delta-plan-scaffold when it
+  # is run for this change, because a change that is never planned should not leave empty
+  # plan files behind. Many changes may be open at once — every specify call on an
+  # established feature opens its own, and the wave is what orders them.
   - id: cr_setup
     action: execute_script
     script: { ref: actions }

package/assets/.appweaver/orchestrator/modules/lane-gate.orch.yaml

@@ -22,7 +22,15 @@
 # never asked about a UI lane it declined.
 #
 # Inputs (via include `with`):
-#   require  — the lane kind this phase cannot run without: backend | frontend
+#   require  — the lane kind this phase cannot run without: backend | frontend, or an
+#              EMPTY string for "any lane will do". Empty is what a phase passes when it
+#              needs a declaration to work from but no particular kind of one — `build`
+#              compiles every declared lane, so a frontend-only project is as buildable
+#              as a backend-only one. It narrows nothing else: no lane declared at all, a
+#              lane with no source path, a source path that is not on disk and two lanes
+#              claiming overlapping subtrees all still stop the run. The required kind's
+#              fields below then bind from the backend block, which an empty-require
+#              caller reads none of.
 #   command  — the phase being gated, quoted back in the failure message
 #
 # Produces, for the required kind: WHERE it lives (lane_root / lane_source_path),

package/assets/.appweaver/orchestrator/modules/tech-select.orch.yaml

@@ -110,6 +110,27 @@ workflow:
     multi: true
     answer_var: tg_subset
 
+  # 2b. SWAP, don't stack — `replace` (passed by the caller through `with:`).
+  #
+  # A phase that generates for two lanes includes this module twice, and standards only
+  # ever ACCUMULATE: the second lane inherited the first's rule set, so a full-stack run
+  # showed the frontend generator the service rules and the backend generator the UI
+  # rules, and each prompt had to argue against its own envelope. The caller's FIRST
+  # include leaves `replace` unset — that lane's rules simply join the declared seed —
+  # and the second passes replace: "true" immediately before its own lane's steps.
+  #
+  # IT IS ITS OWN STEP, not a flag on the loads below, because the loads are conditional
+  # and the reset must not be. A lane whose map resolves nothing fires NO load step at all
+  # (no map ⇒ no candidates ⇒ the selection box never runs), and on that path a flag
+  # attached to the loads would leave the OTHER lane's rules standing — "no rules
+  # configured for this lane" silently meaning "keep the other lane's", which is the exact
+  # confusion this exists to remove. load_standards with no files is a pure reset.
+  - id: swap_lane_rules
+    action: load_standards
+    condition: "{{replace}} == true"
+    files: []
+    replace: "true"
+
   # 3. Load the selection into the sticky standards set (system block, D3).
   - id: load_all
     action: load_standards

package/assets/.appweaver/orchestrator/orchestrator.py

@@ -183,6 +183,14 @@ class Orchestrator:
         # system prefix stays byte-stable across steps (prompt-cache lever)
         # while build_context keeps declaring only the per-request delta.
         self.standards = list(wf.get("standards", []) or [])
+        # The workflow's DECLARED seed, kept apart from what steps load later. A phase
+        # that generates for two lanes needs each lane's rule set and NOT the other's,
+        # but standards only ever accumulate — so the second lane inherited the first's
+        # rules and both prompts had to argue their way out of an envelope that
+        # contradicted them. `load_standards: replace` resets to this seed and then
+        # appends, which swaps the lane rules while leaving the always-on set (ai-rules
+        # and anything else the workflow declared up front) exactly where it was.
+        self.standards_seed = list(self.standards)
         # F1: top-level scripts ref map {ref: {sh: path, ps1: path}} (decl shape)
         self.scripts = dict(wf.get("scripts", {}) or {})
         # every file that has entered any payload (verify_context required_files)
@@ -960,8 +968,22 @@ class Orchestrator:
     def act_load_standards(self, step):
         """F4 — append files to the sticky standards set (dedup; `optional:`
         tolerated). _assemble_system prepends the set to EVERY payload, so a
-        skill loads its standards once (decl load_context → system per D3)."""
+        skill loads its standards once (decl load_context → system per D3).
+
+        `replace: true` first resets the set to the workflow's DECLARED seed,
+        dropping everything steps have loaded since. That is how a phase serving
+        two lanes gives each one its own rule set instead of the union: the
+        second lane replaces the first's rules rather than stacking on them.
+        The seed survives, so the always-on standards are never dropped."""
         p = step.get("parameters") or step
+        # Through _cond, so a rendered "{{flag}}" that resolves to "false" is FALSE.
+        # Plain truthiness would read that non-empty string as true and silently drop
+        # every loaded standard on the path meant to keep them.
+        if self._cond(str(p.get("replace", ""))):
+            dropped = len(self.standards) - len(self.standards_seed)
+            self.standards = list(self.standards_seed)
+            self.emit(f"[load_standards] replace — reset to the declared seed "
+                      f"({len(self.standards_seed)} file(s), {max(dropped, 0)} dropped)")
         files = p.get("files") or []
         if p.get("files_from_variable"):
             files = [{"path": x} for x in (self.vars.get(p["files_from_variable"]) or [])]

package/assets/.appweaver/orchestrator/rev-templates/design-template.skeleton.md

@@ -71,12 +71,16 @@
   contracts, behaviour and decisions; it is not code.
 
   ANCHORING RULES
-  - Every design element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/US-/SC-)
-    and the whole spec is covered DOWN here (§4). No element without a spec
-    reason; no requirement without a design home.
-  - THE SPEC IS THE ONLY DOMAIN INPUT. Design reads the spec + the technical
-    standards, never the domain rule files. A domain rule the spec omits is
-    recorded as a §5 assumption, never smuggled in.
+  - Every design element traces UP to an id (FR-/BR-/CN-/DC-/IC-/US-/SC-) and the
+    whole spec is covered DOWN here (§4). No element without a reason in an
+    authority; no requirement without a design home.
+  - THE AUTHORITIES ARE THE SPEC AND, WHERE THE CONTEXT HAS ONE, ITS
+    domain-model.md — never the domain rule files. The spec is always the
+    behaviour authority. Where specs/[Context]/domain-model.md exists it is the
+    STRUCTURE authority and outranks the spec on entities, value objects, the
+    aggregate boundary and the BR-nnn invariants; where it does not, the spec
+    carries that structure alone. A domain rule neither states is recorded as a
+    §5 assumption, never smuggled in.
   - Feature = aggregate. A later requirement is a DELTA on this document.
 
   STRUCTURE FOLLOWS THIS PROJECT'S CODE
@@ -134,11 +138,14 @@
 
 ### 1.2 Domain / Data Model
 
-<!-- PINNED ANCHOR — follow spec.md exactly. Entities & value objects are the
-     spec's Key Entities (SAME names); invariants are its Business Rules
-     (BR-nnn, cite each); the boundary is its Aggregate Boundary; states are its
-     lifecycle. Cross-slice references are BY ID and live here — the
-     cross-reference tool reads this section for those edges. -->
+<!-- PINNED ANCHOR — follow the STRUCTURE authority exactly. Where the context has
+     a specs/[Context]/domain-model.md, that is it: entities & value objects carry
+     the model's names, invariants cite its BR-nnn (never restate them), the
+     boundary is its Boundary block, states are the lifecycle it describes. Where
+     the context has no model yet, the same four come from spec.md's Key Entities,
+     Business Rules, Aggregate Boundary and lifecycle. Cross-slice references are
+     BY ID and live here either way — the cross-reference tool reads this section
+     for those edges. -->
 
 | Element | Kind | Fields / shape | Invariants (BR-) |
 |---|---|---|---|

package/assets/.appweaver/orchestrator/rev-templates/ui-design-template.skeleton.md

@@ -83,9 +83,11 @@
   - Every element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/US-/SC-) and the
     experience obligations of the spec are covered DOWN here (§7). No screen
     without a spec reason; no user story without a screen home.
-  - THE SPEC IS THE ONLY DOMAIN INPUT — the same rule the service design keeps.
-    This document reads the spec + the lane's own standards, never the domain
-    rule files.
+  - THE SPEC IS THE ONLY DOMAIN INPUT for this lane. This document reads the spec
+    + the lane's own standards, never the domain rule files. (The service lane
+    reads a second authority, the context's domain-model.md, because it realises
+    the aggregate's structure. This lane consumes the published surface at §5, not
+    the domain, so the model is not in its context.)
   - THE CONTRACT IS THE ONLY SERVICE INPUT (§5). Read the design contract, never
     the service design.