aw-spec-cli 0.1.16 → 0.1.18

package/assets/.appweaver/orchestrator/workflows/aw-spec-finalize-delta.orch.yaml

@@ -1,30 +1,45 @@
 # =============================================================================
 # aw-spec-finalize-delta (orchestrator) — MERGE the delta into the master docs
 #
-# The fourth of the five CR stages. Fold the open change's delta docs into the feature's
-# masters (doc-first merge) and refresh the cross-slice edges from the now-merged design.
-# After this the master docs describe the shipped-plus-change state — but THE CHANGE
-# REMAINS OPEN.
+# The fourth of the five CR stages. Fold the open change's delta into the two documents that
+# DEFINE the slice — the feature's spec.md and the bounded context's domain-model.md — then
+# refresh the OKF knowledge layer. After this the masters describe the shipped-plus-change
+# state, but THE CHANGE REMAINS OPEN.
 #
-# HOW MANY MASTERS. Two always — spec.md + design.md. THREE where the feature holds a UI
-# half (design.ui.md). This stage is the ONLY writer of the masters, so every document the
-# change can move has to move here: a UI delta left in the change dir is lost the moment
-# close-delta archives it, and a UX- merged into the spec that reaches no design is a
-# standard nothing implements.
+# TWO MERGE TARGETS, ONE TRANSACTION:
+#   • specs/<Feature>/spec.md          ← changes/<id>/delta-spec.md
+#   • specs/<Context>/domain-model.md  ← specs/<Context>/domain-model.<id>.delta.md
+# Behaviour and model land together or neither lands. A requirement merged citing a BR- the
+# model never gained references an invariant that does not exist; an invariant merged that no
+# requirement reached is a rule nothing asks for. ONE agent step writes both, so there is no
+# window in which one is in and the other is not.
 #
-# THE UI LANE HAS ITS OWN COMMANDS — ⌛ design-ui / delta-design-ui author design.ui.md and
-# delta-design.ui.md, exactly as design / delta-design author the service pair. This stage
-# does not author either one; it MERGES whichever of them the feature has. The two UI paths
-# it must handle are therefore different, and both are normal:
-#   • MASTER + DELTA — the change has an experience half. Merge it, then append the row.
-#   • MASTER, NO DELTA — the change never reached the UI, or ⌛ delta-design-ui has not run.
-#     Append the Change History row and touch nothing else. The row is not bookkeeping
-#     for its own sake: close-delta stamps design.ui.md to the new version alongside its
-#     siblings (version-stamp covers all three), so a header carrying a version that no
-#     row explains is indistinguishable from a merge that silently dropped one.
-# A feature with no design.ui.md at all has no UI half and merges two documents, unchanged.
+# THE MODEL MERGES ONE `## Aggregate:` SECTION AT A TIME — the section is the merge unit, and
+# only the sections the delta's "Aggregates touched" header names are opened. Two open deltas
+# on DIFFERENT aggregates therefore never collide; two on the SAME one are a real semantic
+# conflict, which analyze-plan-delta's overlap finding surfaces before the merge rather than
+# leaving it to be discovered here.
 #
-#   specify → design → analyze-delta-design → implement-delta → build
+# THE LANE PLANS ARE NOT MERGED HERE. backend-plan.md and frontend-plan.md are DERIVED from
+# the spec and the model — that is what the lane split made them — so they are re-derived from
+# the merged masters, not patched from a delta. Merging a delta plan would fork the
+# derivation: the master would carry an edit no run of `plan` produced, and the next `plan`
+# would silently overwrite it. The delta plans stay in changes/<id>/, where `implement`
+# generated from them, and close-delta archives them as the record of how the change was
+# built. A UX-
+# item merged into the spec is carried by the spec until the frontend plan is re-derived from
+# it — not dropped, re-derived.
+#
+# ⌛ THE RE-DERIVATION IS NOT BUILT YET, and this stage is where that shows. `plan`
+# self-detects on plan-EXISTS, so a run against a merged master authors another DELTA plan
+# rather than refreshing the master ("to regenerate a master, delete it first"). Until a
+# refresh mode lands, the master plans stand at their bootstrap content while spec.md and
+# domain-model.md move ahead of them — visible, because analyze-plan gates the masters against
+# exactly these two documents and reports the drift. What this stage must NOT do is hide that
+# by merging a delta plan: the plan would then agree with the spec without any run of `plan`
+# ever having derived it.
+#
+#   specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta
 #       → finalize-delta   ← you are here
 #       → analyze-slice → close-delta
 #
@@ -39,17 +54,24 @@
 # The downstream fence below still guards the MERGE (a change that breaks a dependent
 # must not reach the master docs); close-delta guards nothing — it is the bookkeeping.
 #
-# Prereqs: run /appweaver implement-delta then build first (the delta's code is
-# generated and compiles), so after the merge the master docs and the code agree.
-# finalize-delta edits ONLY the master docs; it does not generate code.
+# Prereqs: run /appweaver implement (answering it with THIS change), then build, then
+# /appweaver analyze-slice-delta — the delta's code is generated, compiles, and has been
+# VERIFIED to contain what the delta plans said it would, so after the merge the masters
+# and the code agree. That last gate is the one that matters here: this stage writes the
+# change into spec.md and domain-model.md, and merging a change that was never fully
+# implemented is how a master ends up asserting behaviour no code has. Nothing MECHANICALLY
+# proves it ran — the stage boundary is operator-driven, as everywhere else in this
+# pipeline — but it is the difference between a master that describes the system and one
+# that describes an intention.
+# finalize-delta edits ONLY spec.md and domain-model.md; it generates no code.
 #
 # Launch:  /appweaver finalize-delta [strategy]
 # Prereq:  an OPEN change whose delta was implemented.
 # =============================================================================
 
 name: aw-spec-finalize-delta
-description: Merge the open change's delta-spec into spec.md, delta-design into design.md and — where the feature has a UI half — delta-design.ui.md into design.ui.md (doc-first), append the Change History to each in lockstep, and refresh the cross-slice edges from the merged design. Gated first by a SCOPED downstream fence over the transitive blast radius (fence_green), which writes a triage report and asks Abort/Override on red. Leaves the change OPEN — analyze-slice runs next against the merged master, and close-delta archives the change and bumps the version.
-version: 1.3.0
+description: Merge the open change's delta-spec into the feature's spec.md and its model delta into the bounded context's domain-model.md — one aggregate section at a time, only the aggregates the delta names — in a single transaction, and append the spec's Change History row. The lane plans are NOT merged — backend-plan.md and frontend-plan.md are derived from these two documents and are re-derived by /appweaver plan main. Gated first by a SCOPED downstream fence over the transitive blast radius (fence_green), which writes a triage report and asks Abort/Override on red. Leaves the change OPEN — analyze-slice runs next against the merged masters, and close-delta archives the change and bumps the version.
+version: 2.0.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -73,10 +95,14 @@ vars:
   downstream_csv: ""       # the blast-radius names, fed to the scoped fence's --also and shown to the human
   fence_ok: "true"         # default green so the gate is a no-op when nothing downstream
   gate_decision: "clean"   # audit: 'clean' unless a RED fence was deliberately overridden
-  ui_design_exists: "false"  # the feature holds a design.ui.md master ⇒ this merge has a THIRD target.
-                             # feature_paths runs on_error:continue, so this default is what a failed
-                             # readback falls back to: the two-master merge, unchanged.
-  ui_design_doc: ""          # specs/<Feature>/design.ui.md — the UI merge target
+  domain_model: ""            # specs/<Context>/domain-model.md — the second merge target
+  domain_model_exists: "false"
+  delta_model: ""             # specs/<Context>/domain-model.<id>.delta.md — the model half of the change
+  delta_model_exists: "false" # false ⇒ a behaviour-only change: the spec merge is the whole merge
+  model_orphan: "false"       # a model delta whose context has no master to merge it into
+  model_master_ok: "true"     # lowered by model_orphan_raise; the gate reads only this
+  backend_plan: ""            # READ, never written here — the OKF edges are parsed out of it
+  backend_plan_exists: "false"
 
 workflow:
 
@@ -87,11 +113,14 @@ workflow:
     script: { ref: actions }
     subcommand: feature-paths
     outputs:
+      - { name: feature,     from: "$.feature" }
       - { name: feature_dir, from: "$.feature_dir" }
       - { name: spec_file,   from: "$.spec_file" }
       - { name: spec_exists, from: "$.spec_exists" }
-      - { name: ui_design_exists, from: "$.ui_design_exists" }   # ⇒ a third master to merge into
-      - { name: ui_design_doc,    from: "$.ui_design_file" }
+      # The backend plan is a READER's input here, not a merge target: the OKF cross-slice
+      # edges are parsed out of it, so this stage needs its path and whether it exists.
+      - { name: backend_plan,        from: "$.backend_plan" }
+      - { name: backend_plan_exists, from: "$.backend_plan_exists" }
 
   - id: require_feature
     action: verify_context
@@ -103,7 +132,7 @@ workflow:
     action: verify_context
     require_true: spec_exists
     on_false: stop
-    on_false_message: "No spec.md for the current feature. Run /appweaver specify + design first."
+    on_false_message: "No spec.md for the current feature — there is no master to merge into. Run /appweaver specify first."
 
   # 1b. Read the OPEN change (opened by cr). finalize-delta needs a change to close.
   - id: read_change
@@ -121,7 +150,59 @@ workflow:
     action: verify_context
     require_true: has_change
     on_false: stop
-    on_false_message: "No open change on this feature — nothing to finalize. Run /appweaver specify → design → analyze-delta-design → implement-delta first."
+    on_false_message: "No open change on this feature — nothing to finalize. Run /appweaver specify → plan → analyze-plan-delta → implement first."
+
+  # 1b-ii. The change's own documents, from the ONE resolver that knows the layout: the
+  #     delta-spec sits at FEATURE level (changes/<id>/) and the model delta at CONTEXT
+  #     level (specs/<Context>/domain-model.<id>.delta.md), beside the master it merges
+  #     into. Both merge targets and both sources come from here, so this stage never
+  #     rebuilds a path by hand.
+  - id: cr_paths
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-paths
+    args: ["--cr-id", "{{active_change}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: cr_dir,              from: "$.cr_dir" }
+      - { name: delta_spec,          from: "$.delta_spec" }
+      - { name: delta_spec_exists,   from: "$.delta_spec_exists" }
+      - { name: delta_model,         from: "$.delta_model" }
+      - { name: delta_model_exists,  from: "$.delta_model_exists" }
+      - { name: delta_backend_plan,  from: "$.delta_backend_plan" }
+      - { name: domain_model,        from: "$.domain_model" }
+      - { name: domain_model_exists, from: "$.domain_model_exists" }
+
+  # The delta-spec is the merge's source of truth. A missing one would still reach the
+  # agent step as an announced-missing context file rather than a stop, and merging from
+  # nothing is how a master acquires content no change ever asked for.
+  - id: require_delta_spec
+    action: verify_context
+    require_true: delta_spec_exists
+    on_false: stop
+    on_false_message: "Change {{active_change}} has no delta-spec.md at {{delta_spec}} — nothing to merge into spec.md. Run /appweaver specify to author the change, or /appweaver recall-delta to withdraw it."
+
+  # A model delta with no master to merge it into. specify creates domain-model.md the
+  # first time it models a context, so this is a context whose master was moved or
+  # deleted after the change was opened. Stop rather than merge the spec half alone:
+  # close-delta archives the model delta, so a silently skipped model change is a
+  # change that is gone. Two ordered assignments, because the engine takes no compound
+  # condition: the probe runs only where the master is ABSENT and carries the delta's
+  # own presence, so the flag it raises means "a model delta with nothing to merge into".
+  # A feature outside any bounded context has neither file and passes both, which is
+  # the legacy layout and not an error.
+  - id: model_orphan_probe
+    condition: "{{domain_model_exists}} == false"
+    action: set
+    vars: { model_orphan: "{{delta_model_exists}}" }
+  - id: model_orphan_raise
+    condition: "{{model_orphan}} == true"
+    action: set
+    vars: { model_master_ok: "false" }
+  - id: require_model_master
+    action: verify_context
+    require_true: model_master_ok
+    on_false: stop
+    on_false_message: "Change {{active_change}} carries a model delta ({{delta_model}}) but its bounded context has no domain-model.md master at {{domain_model}}. Spec and model merge in one transaction, so this stage will not merge the spec half alone. Restore the context's domain-model.md (it is what specify creates when it first models the context) and re-run /appweaver finalize-delta."
 
   # 1c. DOWNSTREAM GATE (hard, with a REVIEWED override). Who depends on this aggregate —
   #     its OKF Cross-References, TRANSITIVELY (C→B→A all count) and placeholder-filtered
@@ -175,7 +256,10 @@ workflow:
       fence_log: "{{fence_log}}"
     context:
       - { path: "{{spec_file}}" }
-      - { path: "{{feature_dir}}/changes/{{active_change}}/delta-design.md" }
+      - { path: "{{delta_spec}}" }
+      # The delta plan is how the change was BUILT — the most direct account of what could
+      # have broken a dependent. Optional: a frontend-only change never has one.
+      - { path: "{{delta_backend_plan}}", optional: true }
   - id: write_broken_downstream
     action: agent_author
     condition: "{{downstream_count}} != 0"
@@ -251,16 +335,7 @@ workflow:
     on_mismatch: stop
     on_mismatch_message: "finalize-delta ABORTED — downstream fence RED after change {{active_change}} and the override was declined. {{downstream_count}} slice(s) depend on this aggregate ({{downstream_csv}}): the change would break a slice that USES this one. Triage: {{feature_dir}}/changes/{{active_change}}/broken-downstream.md. Fix the downstream break; or, if the behaviour change is intended, open a CR on the affected slice to re-baseline its golden-master. Then re-run /appweaver finalize-delta. Last log: {{fence_log}}"
 
-  # 2. Ensure the master design.md exists (idempotent) — the second merge target.
-  - id: design_scaffold
-    action: execute_script
-    script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: design_doc, from: "$.design_doc" }
-
-  # 3. Pre-execution hooks.
+  # 2. Pre-execution hooks.
   - id: resolve_pre_hooks
     action: execute_script
     script: { ref: actions }
@@ -272,43 +347,53 @@ workflow:
     action: dispatch_hooks
     hooks_from_variable: before_hooks
 
-  # 4. DOC-FIRST merge: fold the two delta docs into the two master docs in place.
+  # 3. THE MERGE: the change's two halves into the two masters, in place.
   # Context is fed via build_context — agent_generate reads the ENVELOPE, not a
   # step-level context: key (unlike agent_author/agent_query which read both).
+  # FOUR documents at most, and NO PLAN AMONG THEM. A plan in context is a plan the
+  # merge could quote from, and everything it would quote is a derivation of these
+  # two masters rather than a source for them — the delta plan's wording is how the
+  # change was BUILT, not what was agreed. The two model documents are independently
+  # optional — the gate above has already refused the one combination that would be a
+  # mistake — so a behaviour-only change still gets the master model in context, which
+  # is what lets the merge check that the BR- ids the spec cites actually exist.
   - id: ctx_merge
     action: build_context
     context:
-      - { path: "{{feature_dir}}/changes/{{active_change}}/delta-spec.md" }
-      - { path: "{{feature_dir}}/changes/{{active_change}}/delta-design.md" }
+      - { path: "{{delta_spec}}" }
       - { path: "{{spec_file}}" }
-      - { path: "{{design_doc}}" }
-      # THE UI LANE's pair, INDEPENDENTLY optional — the merge task reads which of them
-      # arrived as its instruction. Neither: a backend-only feature, and a two-master
-      # merge is the complete outcome. Master only: the change did not reach the UI, or
-      # ⌛ delta-design-ui has not run — Change History row only. Both: a full third merge.
-      # Optional rather than gated because a missing UI document is an ordinary state
-      # here, not a misconfiguration worth stopping the merge over.
-      - { path: "{{ui_design_doc}}", optional: true }
-      - { path: "{{feature_dir}}/changes/{{active_change}}/delta-design.ui.md", optional: true }
+      - { path: "{{delta_model}}",  optional: true }
+      - { path: "{{domain_model}}", optional: true }
   - id: merge_delta
     action: agent_generate
     tools: "Read,Write,Edit"
     permission_mode: acceptEdits
     task: |
-      Merge the open change {{active_change}} into this feature's MASTER docs (all in
-      context), DOC-FIRST. The delta docs (in context) are the source of the change;
-      apply them and change nothing else.
-      HOW MANY MASTERS: spec.md and design.md always. design.ui.md — the FRONTEND lane's
-      master — only where it is in context (ui_design_exists={{ui_design_exists}}); its
-      delta, delta-design.ui.md, may or may not be there beside it. Absent both, the
-      feature has no UI half and merging two documents is the COMPLETE outcome, not a
-      step you skipped.
+      Merge the open change {{active_change}} into the two MASTER documents in context.
+      The delta documents are the source of the change; apply them and change nothing else.
+      THE MASTERS: spec.md (this feature's behaviour) and, where it is in context,
+      domain-model.md (the bounded context's model — delta_model_exists={{delta_model_exists}}).
+      A change with no model delta merges the spec alone and that is the COMPLETE outcome,
+      not a step you skipped.
+      NO LANE PLAN IS A TARGET HERE. backend-plan.md and frontend-plan.md are DERIVED from
+      these two documents and are re-derived by /appweaver plan main after this merge; neither is
+      in context and neither is to be opened, read or edited. Do not restate a plan's
+      wording in a master: the plan is how the change was built, not what was agreed.
+      BOTH MASTERS MOVE TOGETHER. Where there is a model delta, edit spec.md and
+      domain-model.md in the same pass — a merged requirement citing a BR- the model never
+      gained, or a merged invariant no requirement reached, is exactly the split state this
+      stage exists to prevent.
       To spec.md:
       - Add each ADDED user story as a US-n tagged `Added: {{active_change}}`, and fold
-        the ADDED / MODIFIED / REMOVED FR / BR / CN- / DC- / IC- / UX- items into their
-        sections using the master's vocabulary (EARS FR, BR invariants, etc.). Every class
-        the delta authored is merged, including UX- into Experience Standards: that section
-        is the UI lane's only carrier, so a UX- item left behind reaches no UI phase.
+        the ADDED / MODIFIED / REMOVED FR / CN- / DC- / IC- / UX- items into their
+        sections using the master's vocabulary (EARS FR, etc.). Every class the delta
+        authored is merged, including UX- into Experience Standards: that section is what
+        the frontend plan is re-derived from, so a UX- item left behind reaches no UI.
+      - A BR- in the delta-spec is a CITATION, never a definition — the invariant itself
+        belongs to the model. Merge the citations (an FR's "Exercises", the
+        "Relies on invariants" line, a story's exercised ids) and merge the RULE only into
+        domain-model.md. A BR- whose text lands in spec.md is the restatement the model
+        exists to prevent, and it drifts the moment the model moves.
       - Where a lift section (Constraints & NFRs, Data Classification, Integration
         Contracts, Experience Standards) still reads "None", its first merged item REPLACES
         that placeholder; a section the delta does not touch keeps its "None" verbatim.
@@ -316,52 +401,45 @@ workflow:
         REMOVED item by removing it. Keep the rest of spec.md VERBATIM.
       - Append a Change History row for {{active_change}} (date + one-line summary).
         Its Version cell is {{next_version}} — the version this change ships as.
-      To design.md:
-      - ADD each new design element in its own structural section; apply each MODIFIED
-        element as an in-place edit of the existing element; remove each REMOVED element.
-      - Fold the delta's new DA-n / WA-n into the design's two deferral ledgers, and keep
-        the Traceability section in sync — every new FR / BR / CN- / DC- / IC- / US- / SC-
-        gets a design home. UX- is NOT among them: the service design realises no
-        experience standard, so a Traceability row for one is a fabrication. Keep the rest
-        of design.md VERBATIM.
-      - Append a Change History row for {{active_change}} (date + one-line summary),
-        Version cell {{next_version}}, in lockstep with the spec's row.
-      To design.ui.md — ONLY where it is in context. TWO CASES, decided by whether
-      delta-design.ui.md came with it:
-      - NO delta-design.ui.md in context (or one whose Change summary reads "No UI
-        consequence", its ADDED / MODIFIED / REMOVED sections all None): merge NOTHING
-        into the body. The change was server-side, or the UI lane's own delta command
-        has not run for it. Append ONLY a Change History row for {{active_change}} (date,
-        Version cell {{next_version}}, summary stating the change carried no UI content)
-        and change nothing else — close-delta stamps this document to {{next_version}} alongside
-        its siblings, so a header carrying a version that no row explains is
-        indistinguishable from a merge that dropped one. Do NOT invent UI content to
-        justify the row, and do NOT infer the experience change from the service delta:
-        design.md is not this document's source.
-      With delta-design.ui.md in context:
-      - ADD each new screen, component, state, interaction or contract binding into the
-        master's OWN section — the delta's "Section (§ in design.ui.md)" column names it.
-        Apply each MODIFIED element as an in-place edit of that element and remove each
-        REMOVED one. A shared component or shared state container is edited ONCE, where
-        the master defines it, never duplicated into a second place.
-      - Fold the delta's interaction states into the states the master already records
-        for those interactions, and its new DA-n / WA-n into the master's two ledgers.
-      - Keep the Traceability section — the lane's spine — in sync: every UX- the delta
-        realises and every new US- it serves gets a row naming its UI home. UX- BELONGS
-        HERE AND ONLY HERE: design.md must never carry a UX- row (the service design
-        realises no experience standard) and design.ui.md is the sole document that
-        does, so a UX- merged into the spec and into neither design has been dropped.
-      - Where a mandatory ledger still reads "None (as of vX.Y)", its first merged item
-        REPLACES that placeholder; a ledger the delta does not touch keeps it verbatim.
-      - Append a Change History row for {{active_change}} (date + one-line summary),
-        Version cell {{next_version}}, in lockstep with the other two.
-      Leave the `**Version**:` HEADER of EVERY document in context exactly as it is — it
-      still reads {{version}} and does not move here. close-delta stamps the headers to
-      {{next_version}} at the moment it bumps active_version.json, so every carrier of
-      the number changes in one step by one mechanism. Do not invent a version anywhere.
-      Preserve every unrelated section of EVERY doc byte-for-byte. Do NOT touch the
-      delta docs (close-delta archives them later) and do NOT touch any source code.
-      Report the files you changed.
+      To domain-model.md — ONLY where it and a model delta are both in context:
+      - THE MERGE UNIT IS ONE `## Aggregate: <Name>` SECTION, and the ONLY sections you may
+        open are the ones the model delta's "Aggregates touched" header names. Every other
+        aggregate section stays byte-for-byte, whatever the delta says elsewhere — another
+        open change may be merging into one of them, and the section boundary is what keeps
+        the two merges from colliding.
+      - ADDED: put each new entity, value object, domain event, invariant (BR-n) or
+        cross-aggregate invariant (XBR-n) into the sub-section it belongs to (### Entities,
+        ### Value objects, ### Domain events, ### Invariants) of the aggregate the delta
+        names for it. A BR-n is added with its RULE TEXT — this document is where the rule
+        lives. An XBR-n goes in `## Cross-Aggregate Invariants`, not inside an aggregate.
+      - A wholly NEW aggregate gets a whole new `## Aggregate: <Root>` section in the
+        master's own shape (Serving specs, Last changed, ### Boundary, ### Entities,
+        ### Value objects, ### Domain events, ### Invariants), placed after the existing
+        aggregate sections and before `## Cross-Aggregate Invariants`. Its
+        **Serving specs** is `{{feature}}`.
+      - MODIFIED: the delta states a BEFORE and an AFTER — verify the BEFORE is what the
+        master actually says, then replace it with the AFTER in place. If the master does
+        not say the BEFORE, do NOT guess: leave it and report the mismatch, because the
+        master has moved since the delta was authored and the change needs a rebase.
+      - REMOVED: remove the named element. Where the delta says what replaces it, the
+        replacement is in ADDED and merges there.
+      - Fold new terms into `## Ubiquitous Language` and new context relationships into
+        `## Context Map`, both only where the delta introduces them.
+      - On each aggregate section you touched, set **Last changed** to
+        `<the version token already on that line> · {{active_change}}` — replace the CR half
+        only. The version half is a CONTEXT version, stamped by script, and this stage is
+        not its author.
+      - Do NOT append a Change History row to domain-model.md and do NOT touch its
+        `**Context version**:` header. That ledger is close-delta's, written with the
+        version it bumps to — the model's row and its version land together or the row
+        carries a number nothing else agrees with.
+      Leave the `**Version**:` HEADER of spec.md exactly as it is — it still reads
+      {{version}} and does not move here. close-delta stamps it to {{next_version}} at the
+      moment it bumps active_version.json, so every carrier of the number changes in one
+      step by one mechanism. Do not invent a version anywhere.
+      Preserve every unrelated section of BOTH masters byte-for-byte. Do NOT touch the
+      delta documents (close-delta archives them later), do NOT open or edit any lane plan,
+      and do NOT touch any source code. Report the files you changed.
     outputs:
       - { name: merged_docs, from: "$.files" }
 
@@ -369,47 +447,68 @@ workflow:
     action: verify_context
     require_non_empty: merged_docs
     on_empty: stop
-    on_empty_message: "The merge produced no changes — expected edits to spec.md and design.md (and design.ui.md where the feature has a UI half). Ensure the delta docs are filled (not the empty template) and re-run."
+    on_empty_message: "The merge produced no changes — expected an edit to spec.md, and to domain-model.md where the change carries a model delta. Ensure the delta documents are filled (not the empty template) and re-run."
 
-  # 4b. Refresh the cross-slice EDGES from the NOW-MERGED master design.md — the delta's
-  #     added / removed references have just landed, so this is the first point they are
-  #     authoritative. Reconcile-on-write: new deps appear in the used slices'
-  #     Cross-References, dropped deps are pruned. `--origin auto` keeps the slice's
-  #     provenance (greenfield vs reverse-engineered) from its design.md, so this works
-  #     identically for a greenfield CR and a brownfield CR. Best-effort (never blocks close).
+  # 4b. Reconcile the cross-slice EDGES. They are parsed out of the master backend-plan.md
+  #     (§1's References-by-id + its External integrations table) — the plan is not a merge
+  #     target here, so this run neither adds nor prunes an edge on its own account; it
+  #     re-asserts the index against the plan as it stands, which is what keeps a
+  #     concept stub created by another slice's merge from lingering. The delta's own new
+  #     dependencies reach the index when /appweaver plan main re-derives the plan from the
+  #     masters this stage just merged. Skipped where the feature has no plan yet: parsing
+  #     an absent document yields zero edges, and reconcile-on-write would read that as
+  #     "every dependency was dropped" and prune the slice's real edges.
+  #     `--origin auto` keeps the slice's provenance (greenfield vs reverse-engineered)
+  #     from the plan itself. Best-effort (never blocks the merge).
   - id: xref_record
+    condition: "{{backend_plan_exists}} == true"
     action: execute_script
     on_error: continue
     script: { ref: xref }
     subcommand: record
-    args: ["--feature-dir", "{{feature_dir}}", "--design", "{{design_doc}}", "--origin", "auto"]
+    args: ["--feature-dir", "{{feature_dir}}", "--design", "{{backend_plan}}", "--origin", "auto"]
     outputs:
       - { name: xref_edge_count, from: "$.edge_count" }
       - { name: xref_origin,     from: "$.origin" }
 
-  # 4b-ii. Re-author the concept's Overview from the NOW-MERGED master design.md — the
-  #     change may have moved the aggregate's boundary or invariants, and this is the
-  #     first point the master states them. Section-scoped splice (the Cross-References
-  #     rows other slices own are untouched). Best-effort; an empty answer is a no-op.
+  # 4b-ii. Re-author the concept's Overview from the NOW-MERGED domain-model.md. What the
+  #     Overview states — the root, its invariants, its transaction boundary — is the
+  #     model's own content, and the model is what this stage just moved, so this is both
+  #     the authoritative source and the first point the change is in it. Section-scoped
+  #     splice (the Cross-References rows other slices own are untouched). Skipped where
+  #     the context has no model: there would be nothing in context to distil, and a
+  #     query with no source invents one. Best-effort; an empty answer is a no-op.
+  # Re-scope the envelope first. build_context REPLACES it and it PERSISTS across the
+  # steps that follow, so without this the Overview query would still be holding the
+  # merge's payload — the delta-spec and the model delta among it — and would distil the
+  # concept's prose from a pending change as readily as from the merged master.
+  - id: ctx_overview
+    condition: "{{domain_model_exists}} == true"
+    action: build_context
+    context:
+      - { path: "{{domain_model}}" }
   - id: okf_overview
+    condition: "{{domain_model_exists}} == true"
     action: agent_query
-    context: ["{{design_doc}}"]
     include_standards: false
     schema: { overview: "<2-4 sentences of prose>" }
     mock: { overview: "" }
     task: |
-      Write the OKF knowledge-concept Overview for the aggregate that the merged
-      design.md (in context) describes. 2-4 sentences of PROSE, distilled from §1
-      Domain Model: name the aggregate ROOT and what the aggregate IS; state the
-      INVARIANTS it guards; state its TRANSACTION BOUNDARY — what it OWNS inside the
-      boundary vs what it only REFERENCES by id. Plain prose only: no headings, no
-      bullets, no code fences, no file paths, and no restating of the dependency edges
-      (those live in the Depends-On / Cross-References tables). Describe only what the
-      design states — invent nothing.
+      Write the OKF knowledge-concept Overview for the aggregate `{{feature}}`, from the
+      merged domain-model.md in context. That document models the WHOLE bounded context —
+      read ONLY the `## Aggregate: {{feature}}` section (and any `## Cross-Aggregate
+      Invariants` naming it); the other aggregates belong to other concepts.
+      2-4 sentences of PROSE: name the aggregate ROOT and what the aggregate IS; state the
+      INVARIANTS it guards (its BR-n rules); state its TRANSACTION BOUNDARY — what it OWNS
+      inside the boundary vs what it only REFERENCES by id. Plain prose only: no headings,
+      no bullets, no code fences, no file paths, and no restating of the dependency edges
+      (those live in the Depends-On / Cross-References tables). Describe only what the model
+      states — invent nothing. If the section is absent, answer with an empty string.
     outputs:
       - { name: okf_overview, from: "$.overview" }
 
   - id: okf_overview_write
+    condition: "{{domain_model_exists}} == true"
     action: execute_script
     on_error: continue
     script: { ref: xref }
@@ -424,7 +523,7 @@ workflow:
     on_error: continue
     script: { ref: xref }
     subcommand: log
-    args: ["--note", "CR {{active_change}} merged (downstream gate: {{gate_decision}}) — OKF cross-references refreshed"]
+    args: ["--note", "CR {{active_change}} merged into spec.md + domain-model.md (downstream gate: {{gate_decision}}) — OKF cross-references refreshed"]
     outputs:
       - { name: xref_log, from: "$.log" }
 
@@ -432,8 +531,8 @@ workflow:
   #    analyze-slice — see the header. The change stays OPEN past this stage on purpose:
   #    it is what keeps a red analyze-slice recoverable ("fix and re-run") instead of
   #    landing on an already-shipped version. The delta docs therefore remain in
-  #    changes/{{active_change}}/ even though their content is now merged; close-delta
-  #    moves them to changes/archive/.
+  #    changes/{{active_change}}/ and the model delta beside domain-model.md even though
+  #    their content is now merged; close-delta moves both to changes/archive/.
 
   # 6. Post-execution hooks.
   - id: resolve_post_hooks
@@ -455,8 +554,8 @@ outputs:
   downstream_count: "{{downstream_count}}"
   gate_decision: "{{gate_decision}}"
   xref_edge_count: "{{xref_edge_count}}"
-  ui_design_updated: "{{ui_design_exists}}"   # true ⇒ design.ui.md was a target of this stage. It reports
-                                              # the MASTER's presence, not how much moved: a change with no
-                                              # UI delta still takes its Change History row, because
-                                              # close-delta stamps the header either way.
-  next: "Delta MERGED into spec.md + design.md, and into design.ui.md where the feature has a UI half (ui_design_updated={{ui_design_exists}} — with a UI delta present that is a full merge, without one it is the Change History row that keeps the header close-delta stamps explainable); OKF edges refreshed ({{xref_edge_count}} dep(s)), {{downstream_count}} downstream slice(s) fenced (gate: {{gate_decision}}). Change {{active_change}} is STILL OPEN and the version is still {{version}}. Next: /appweaver analyze-slice — it now reads a master spec that carries this change, and a red result is still recoverable because nothing has been archived. Then /appweaver close-delta archives the change and bumps the version."
+  domain_model: "{{domain_model}}"
+  model_merged: "{{delta_model_exists}}"      # true ⇒ domain-model.md was the second target of this merge.
+                                              # false = a behaviour-only change: the spec merge was the
+                                              # whole merge, not a half of one.
+  next: "Delta MERGED into spec.md, and into the context's domain-model.md one aggregate section at a time where the change carried a model delta (model_merged={{delta_model_exists}} — false means a behaviour-only change, so the spec merge was the whole merge). The lane plans were NOT touched — they are derived from these two masters, and ⌛ re-deriving a MASTER plan is not built yet (plan self-detects on plan-exists and would author another delta), so backend-plan.md / frontend-plan.md stand at their last authored content and analyze-plan will report the drift against the merged spec and model. OKF edges reconciled ({{xref_edge_count}} dep(s)), {{downstream_count}} downstream slice(s) fenced (gate: {{gate_decision}}). Change {{active_change}} is STILL OPEN and the version is still {{version}}. Next: /appweaver analyze-slice — it now reads masters that carry this change, and a red result is still recoverable because nothing has been archived. Then /appweaver close-delta archives the change and bumps the version."