aw-spec-cli 0.1.17 → 0.1.19

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

@@ -30,14 +30,23 @@
 # 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.
+# THE RE-DERIVATION IS `plan main`. After this merge the masters carry the change and the
+# lane plans do not, so the next step for the plans is to be derived again from the two
+# documents this stage just moved: `/appweaver plan main` asks to re-derive them, carries
+# the recorded architectural decisions and workarounds forward, and rewrites whatever the
+# spec and model no longer support. Until that is run the master plans stand at their last
+# authored content while spec.md and domain-model.md have moved 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.
+#
+# ✅ THE DETECTION IS BUILT (2026-09-14). analyze-plan leaves `.aw-plan-gate.json` when it
+# PASSES — the sha256 of spec.md, the context's domain-model.md and each lane plan it read —
+# and `implement` reads it through plan-gate-check before any lane generates, refusing a
+# master run whose plans are no longer the ones the gate passed. So after this merge the
+# plans are not merely "visibly behind": the next `implement` on the master path says so and
+# stops, naming `plan main`. A feature with no receipt has never been gated since the receipt
+# existed and is reported, never refused.
 #
 #   specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta
 #       → finalize-delta   ← you are here
@@ -65,16 +74,64 @@
 # that describes an intention.
 # finalize-delta edits ONLY spec.md and domain-model.md; it generates no code.
 #
-# Launch:  /appweaver finalize-delta [strategy]
+# WHICH CHANGE IS MERGED IS ASKED, NEVER INFERRED. MANY changes may be open at once, and
+# active_version.json's `active_change` is only the most recently opened or activated — every
+# /appweaver specify overwrites it. Taking that field as "the" change is how the delta built
+# by implement stays open while a freshly-opened stub is merged into spec.md: cr-setup
+# scaffolds delta-spec.md from the template the moment it opens a change, so an empty stub
+# passes an exists check. This stage therefore opens with the same list → pick → activate
+# sequence as plan, implement, analyze-plan-delta and recall-delta, and the argument doubles
+# as the answer (`finalize-delta CR-…` skips the prompt).
+#
+# THE DIRECTORY IS THE AUTHORITY for what is open — cr-list reads changes/<id>/ and reports
+# `tracked` separately, so a change whose ledger row was lost is still offered. cr-activate
+# then REFUSES it, which is the outcome that belongs here: a change the ledger does not carry
+# is one close-delta could never archive, so it must not reach the masters.
+#
+# THE MERGE FENCE — THREE REFUSALS, read off disk in one cr-merge-check call and placed
+# before the downstream fence, because they are free while that one runs a test suite:
+#
+#   REBASE. The delta carries the master version it was authored against (`**Base version**:`,
+#   stamped by cr-setup). If the master has moved, the delta's MODIFIED items name a BEFORE
+#   spec.md no longer says, and merging them is last-writer-wins over work that landed.
+#
+#   MERGED-NOT-CLOSED. The masters can move WITHOUT the version moving, because this stage
+#   merges and close-delta bumps. In that window spec.md carries a change the number does not
+#   reflect, so a sibling sharing the same base_version compares EQUAL and would merge onto
+#   masters that had already shifted. The version alone is not a proxy for "the masters
+#   moved"; the id appearing in spec.md is the other half of the answer.
+#
+#   PREDECESSOR. A lower wave is committed to landing first, and `plan` put exactly those
+#   deltas in this one's context as the base it was planned on top of. `depends_on` is
+#   stamped nowhere, so the wave is the only dependency signal that exists — and it is the
+#   conservative one, since same-wave changes are independent by definition.
+#
+# All three are RAISE-then-VERIFY and fail-closed: each flag is raised only by the good
+# state, so a check that did not run leaves the merge refused rather than waved through.
+#
+# NO LOCK. A lock guards CONCURRENT runs; this pipeline is operator-driven and sequential,
+# and the three refusals above cover the sequential case completely. A lockfile would add a
+# stale-lock failure mode to guard a scenario the kit does not have.
+#
+# THE MASTERS ARE SNAPSHOTTED to changes/<id>/pre-merge/ immediately before the rewrite —
+# the pipeline's own record of what they said beforehand, archived with the change.
+#
+# Launch:  /appweaver finalize-delta [CR-id]   (a bare id skips the prompt)
 # Prereq:  an OPEN change whose delta was implemented.
 # =============================================================================
 
 name: aw-spec-finalize-delta
-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
+description: Merge ONE chosen 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. ASKS which change (a bare CR id as the argument skips the prompt) and activates it, rather than taking whichever was last opened. Fenced by three hard refusals read off disk before anything is written — a moved base_version (rebase first), another change merged but not yet closed, and an open LOWER-wave predecessor — then by a SCOPED downstream fence over the transitive blast radius (fence_green), which writes a triage report and asks Abort/Override on red. Snapshots both masters to changes/<id>/pre-merge/ immediately before the rewrite. 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. Leaves the change OPEN — analyze-slice runs next against the merged masters, and close-delta archives the change and bumps the version.
+version: 2.4.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
+inputs:
+  user_input:
+    description: "Optional CR id of the change to merge. A bare id selects it and skips the prompt; anything else is ignored and the menu is shown."
+    required: false
+    bind: USER_INPUT
+
 scripts:
   actions:
     sh:  .appweaver/scripts/bash/aw-spec-actions.sh
@@ -88,7 +145,8 @@ standards:
 
 vars:
   active_change: ""
-  has_change: "false"
+  cr_choice: ""         # the LABEL the pick returns ("CR-… · wave 2 · title"); scripts take its first token
+  has_changes: "false"  # from cr-list — the DIRECTORY's answer to "is anything open", not the ledger's
   version: ""           # the CURRENT version — unchanged by this stage
   next_version: ""      # what close-delta will bump to; the number the Change History rows carry
   downstream_count: "0"    # transitive + placeholder-filtered dependents (blast radius); drives the gate
@@ -101,6 +159,33 @@ vars:
   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
+  # THE MERGE FENCE. All three flags default DOWN and are raised only by the good state, so
+  # a cr-merge-check that errored or a field that was renamed leaves the merge refused.
+  # Fail-closed is the only safe default in front of an in-place edit of the masters.
+  rebase_ok: "false"
+  merged_open_ok: "false"
+  no_blockers: "false"
+  rebase_needed: "true"       # the raw readings, defaulted to the blocking value for the
+  has_merged_open: "true"     # same reason — an unanswered question is not a clean answer
+  has_blockers: "true"
+  base_version: ""
+  current_version: ""
+  blocker_ids: ""
+  blocker_count: "0"
+  merged_open_ids: ""
+  merge_wave: "1"
+  snapshot_dir: ""            # changes/<id>/pre-merge/ — the before-image recall-delta restores
+  snapshot_count: "0"
+  # THE OKF OVERVIEW'S SUBJECT. The kit's working assumption is feature == aggregate; the
+  # Overview step is the one place it is load-bearing rather than cosmetic, because it
+  # selects a `## Aggregate:` section BY NAME. delta_aggregates is what the change's own
+  # model delta declares, so the common case is exact rather than assumed; it is empty for
+  # a behaviour-only change, which falls back to the feature name.
+  delta_aggregates: ""
+  overview_scope: ""
+  overview_section_ok: "false"
+  overview_written: "false"
+  overview_reason: ""
   backend_plan: ""            # READ, never written here — the OKF edges are parsed out of it
   backend_plan_exists: "false"
 
@@ -134,24 +219,64 @@ workflow:
     on_false: stop
     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.
+  # 1b. WHICH CHANGE IS BEING MERGED. The evidence is changes/<CR-id>/ on disk; a closed
+  #     change has moved to changes/archive/. No synthetic rows: `main` is not a change and
+  #     there is nothing to open here, so the menu is the real open changes and nothing else.
+  #     `matched_label` resolves a CR id passed as the argument to the whole option string,
+  #     which is how a bare `finalize-delta CR-…` skips the prompt.
+  - id: cr_list
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-list
+    args: ["--feature-dir", "{{feature_dir}}", "--preselect", "{{USER_INPUT}}"]
+    outputs:
+      - { name: change_options, from: "$.select_options" }
+      - { name: matched_label,  from: "$.matched_label" }
+      - { name: has_changes,    from: "$.has_changes" }
+      - { name: change_count,   from: "$.count" }
+
+  - id: require_changes
+    action: verify_context
+    require_true: has_changes
+    on_false: stop
+    on_false_message: "No open change on this feature — nothing to finalize. Run /appweaver specify → plan → analyze-plan-delta → implement first. A change that already shipped was archived by /appweaver close-delta and is under changes/archive/, where a merge does not reach it."
+
+  # single_option_confirm so a feature with exactly one open change still confirms the id
+  # out loud. This stage edits the two documents that DEFINE the slice, and picking
+  # silently is how the wrong change is merged on a feature that has two open.
+  - id: pick_change
+    action: user_select
+    prompt: "Which open change is being MERGED into spec.md and the context's domain-model.md? Merge the change that was implemented and passed analyze-slice-delta — a change opened but never authored carries an empty delta-spec, and merging it writes nothing while consuming the stage. Deltas sharing a wave are independent; a higher wave is built on top of the lower ones, so merge those first."
+    options_from_variable: change_options
+    preselect_from: matched_label
+    single_option_confirm: true
+    outputs:
+      - { name: cr_choice, from: selection }
+
+  # Make the chosen change the ACTIVE one — analyze-slice and close-delta still read
+  # active_change, so the stages after this one must follow the same delta. The activate
+  # also VALIDATES: it refuses an id the ledger does not carry and stops the run, which is
+  # the right outcome for a merge target close-delta could never archive.
+  - id: activate
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-activate
+    args: ["--cr-id", "{{cr_choice}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: active_change, from: "$.active_change" }
+
+  # 1b-i. The VERSION spine, read after the pick and used for the Change History row only.
+  #     This call is no longer the selector — `active_change` comes from the pick above —
+  #     and version-read moves nothing, so what comes back is the current number.
   - id: read_change
     action: execute_script
     script: { ref: actions }
     subcommand: version-read
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: active_change, from: "$.active_change" }
-      - { name: has_change,    from: "$.has_change" }
       - { name: version,       from: "$.version" }
       - { name: next_version,  from: "$.next_version" }
 
-  - id: require_change
-    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 → 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
@@ -179,7 +304,7 @@ workflow:
     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."
+    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 {{active_change}} to withdraw it (its documents are archived, the version does not move, and code implement already generated is left alone)."
 
   # 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
@@ -204,6 +329,74 @@ workflow:
     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."
 
+  # 1b-iii. THE MERGE FENCE — the three refusals that make a parallel merge safe, all read
+  #     off disk in ONE call, and all placed BEFORE the downstream fence because they are
+  #     free while that one runs a test suite. Refusing cheaply first is the whole ordering.
+  #
+  #     REBASE: the delta carries the master version it was authored against (cr-setup stamps
+  #     `**Base version**:` when the change opens). If the master has moved since, the
+  #     delta's MODIFIED items name a BEFORE the master no longer says, and merging them is
+  #     last-writer-wins over work that already landed.
+  #
+  #     MERGED-NOT-CLOSED: the masters can move WITHOUT the version moving, because this
+  #     stage merges and close-delta bumps. Between the two, spec.md carries a change the
+  #     number does not yet reflect — so a sibling delta sharing the same base_version would
+  #     compare EQUAL and merge onto masters that had already shifted. The id in spec.md is
+  #     the proof, the same evidence recall-delta's merged-refusal reads.
+  #
+  #     PREDECESSOR: a lower wave is committed to landing first, and `plan` put exactly those
+  #     deltas in this one's context as the base it was planned on top of. Merging out of
+  #     wave order folds in behaviour assuming a predecessor the masters do not carry.
+  #
+  #     NO on_error: continue. A gate that cannot run must not be a gate that passes, and the
+  #     raise-then-verify below is fail-closed for the same reason: each flag is raised ONLY
+  #     by the good state, so a field that never arrived leaves it down and the merge refuses.
+  - id: merge_check
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-merge-check
+    args: ["--cr-id", "{{active_change}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: rebase_needed,    from: "$.rebase_needed" }
+      - { name: base_version,     from: "$.base_version" }
+      - { name: current_version,  from: "$.current_version" }
+      - { name: has_blockers,     from: "$.has_blockers" }
+      - { name: blocker_ids,      from: "$.blocker_ids" }
+      - { name: blocker_count,    from: "$.blocker_count" }
+      - { name: has_merged_open,  from: "$.has_merged_open" }
+      - { name: merged_open_ids,  from: "$.merged_open_ids" }
+      - { name: merge_wave,       from: "$.wave" }
+
+  - id: rebase_ok_raise
+    condition: "{{rebase_needed}} == false"
+    action: set
+    vars: { rebase_ok: "true" }
+  - id: require_rebase
+    action: verify_context
+    require_true: rebase_ok
+    on_false: stop
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} needs a REBASE. It was authored against master version {{base_version}}, and the feature now stands at {{current_version}}: another change finalized and closed while this one was open. Its MODIFIED items name a BEFORE that spec.md no longer says, so merging now would overwrite work that already landed. Rebase: run /appweaver analyze-plan-delta {{active_change}} against the current master, fix what it reports, re-stamp the delta's `**Base version**:` to {{current_version}}, then re-run /appweaver finalize-delta {{active_change}}."
+
+  - id: merged_open_ok_raise
+    condition: "{{has_merged_open}} == false"
+    action: set
+    vars: { merged_open_ok: "true" }
+  - id: require_no_merged_open
+    action: verify_context
+    require_true: merged_open_ok
+    on_false: stop
+    on_false_message: "finalize-delta REFUSED — {{merged_open_ids}} has already been MERGED into spec.md but not yet CLOSED, so the masters carry it while the version still reads {{current_version}}. Change {{active_change}} was authored against those pre-merge masters and the version comparison cannot see the difference. Finish the merged change first: /appweaver analyze-slice then /appweaver close-delta {{merged_open_ids}}, which bumps the version — then rebase this one against the new number and re-run /appweaver finalize-delta {{active_change}}."
+
+  - id: no_blockers_raise
+    condition: "{{has_blockers}} == false"
+    action: set
+    vars: { no_blockers: "true" }
+  - id: require_no_blockers
+    action: verify_context
+    require_true: no_blockers
+    on_false: stop
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} is at wave {{merge_wave}} and {{blocker_count}} open change(s) sit at a LOWER wave: {{blocker_ids}}. A lower wave is committed to landing FIRST, and this delta was planned with those in its context as the base it builds on — merging it now folds in behaviour that assumes a predecessor the masters do not yet carry. Merge and close the lower-wave change(s) first (/appweaver finalize-delta <CR-id> → analyze-slice → close-delta), then rebase and re-run this one. Same-wave changes are independent and are not counted here; if this delta does NOT in fact build on them, /appweaver cr-wave can correct its wave."
+
   # 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
   #     (the "_(none observed)_" row is NOT a dependent) = the real blast radius. If any
@@ -347,6 +540,29 @@ workflow:
     action: dispatch_hooks
     hooks_from_variable: before_hooks
 
+  # 2b. SNAPSHOT THE MASTERS — the last thing before they are rewritten, and after every
+  #     gate including the downstream override, so the copy is taken only by the attempt
+  #     that actually merges. finalize-delta may be attempted more than once (a red fence
+  #     aborts it), and a snapshot from an aborted attempt would claim to be the before-image
+  #     of a merge that never happened.
+  #
+  #     This is the ONLY record of what the masters said beforehand that belongs to the
+  #     pipeline rather than to git, and it travels with the change: changes/<id>/ is what
+  #     cr-archive moves, so a closed change carries the before-image of the documents it
+  #     moved, in the archive, for as long as the repo exists.
+  #
+  #     ⌛ The RESTORE is not built. recall-delta still refuses a merged change outright
+  #     rather than un-merging from this copy — the snapshot is what makes that buildable,
+  #     and the rebase gate above is what will answer whether restoring is still safe.
+  - id: snapshot_masters
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-snapshot
+    args: ["--cr-id", "{{active_change}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: snapshot_dir,   from: "$.dir" }
+      - { name: snapshot_count, from: "$.count" }
+
   # 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).
@@ -399,8 +615,13 @@ workflow:
         that placeholder; a section the delta does not touch keeps its "None" verbatim.
       - Apply every MODIFIED item as an in-place edit of the existing item; apply every
         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.
+      - Append a Change History row for {{active_change}} (date + one-line summary), with
+        the CR id in its CR cell. Its Version cell is the literal text `(pending)` — write
+        that, not a number. THE VERSION DOES NOT EXIST YET: close-delta issues it, and it
+        stamps this cell at the same instant it stamps the headers. A number written here
+        would be a prediction, and a change that merged but never closed — an abandoned
+        run, a red analyze-slice — would leave spec.md asserting a version nothing issued.
+        Do not invent a version anywhere, including in this cell.
       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
@@ -434,9 +655,9 @@ workflow:
         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.
+      {{version}} and does not move here. close-delta stamps it, and the Change History
+      row's `(pending)` cell, 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.
@@ -478,6 +699,35 @@ workflow:
   #     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.
+  # WHICH AGGREGATE SECTION(S) THIS CHANGE ACTUALLY TOUCHED, read off the model delta's
+  # own `## Aggregate:` headings rather than assumed from the feature name. The kit's
+  # working assumption is feature == aggregate, and it holds today — but the Overview step
+  # below is the one place that assumption is LOAD-BEARING rather than cosmetic: it selects
+  # a section by name, and a feature whose name is not an aggregate name selects nothing,
+  # producing an empty answer that the writer then declines. Driving it off the delta's
+  # declared aggregates makes the common case exact and the uncommon case visible.
+  #
+  # A BEHAVIOUR-ONLY CHANGE HAS NO MODEL DELTA, so this reports none and the step falls
+  # back to the feature name — which is correct, not a degradation: there is no model
+  # change to distil and the concept's existing Overview stands.
+  - id: cr_aggregates
+    action: execute_script
+    on_error: continue        # informational — a missing model delta is the ordinary case
+    script: { ref: actions }
+    subcommand: cr-overlap
+    args: ["--cr-id", "{{active_change}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: delta_aggregates,     from: "$.aggregates_csv" }
+      - { name: delta_aggregate_list, from: "$.aggregates" }
+
+  - id: overview_scope_feature
+    action: set
+    vars: { overview_scope: "{{feature}}" }
+  - id: overview_scope_delta
+    condition: "{{delta_aggregates}} != "
+    action: set
+    vars: { overview_scope: "{{delta_aggregates}}" }
+
   # 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
@@ -491,13 +741,20 @@ workflow:
     condition: "{{domain_model_exists}} == true"
     action: agent_query
     include_standards: false
-    schema: { overview: "<2-4 sentences of prose>" }
-    mock: { overview: "" }
+    schema: { overview: "<2-4 sentences of prose>", section_found: true }
+    mock: { overview: "", section_found: false }
     task: |
-      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.
+      Write the OKF knowledge-concept Overview for the aggregate `{{overview_scope}}`, from
+      the merged domain-model.md in context. That document models the WHOLE bounded context
+      — read ONLY the `## Aggregate: {{overview_scope}}` section (and any `## Cross-Aggregate
+      Invariants` naming it); the other aggregates belong to other concepts. Where more than
+      one aggregate is named above, this change touched several: write the Overview for the
+      FIRST one, which is the concept this feature owns.
+
+      Set section_found=false if domain-model.md has no `## Aggregate:` section under that
+      name, and answer with an empty overview. Do NOT substitute a different section: the
+      name is how the concept and the model are keyed to each other, and describing the
+      wrong aggregate is worse than describing none.
       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,
@@ -505,7 +762,8 @@ workflow:
       (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" }
+      - { name: okf_overview,       from: "$.overview" }
+      - { name: overview_section_ok, from: "$.section_found" }
 
   - id: okf_overview_write
     condition: "{{domain_model_exists}} == true"
@@ -514,6 +772,9 @@ workflow:
     script: { ref: xref }
     subcommand: concept-overview
     args: ["--feature-dir", "{{feature_dir}}", "--text", "{{okf_overview}}"]
+    outputs:
+      - { name: overview_written, from: "$.written" }
+      - { name: overview_reason,  from: "$.reason" }
 
   # 4c. Anchor the OKF bundle's freshness journal to the current commit (log.md, OKF §7).
   #     Best-effort + git-aware: a no-op when there is no bundle or no commit, so it never
@@ -555,7 +816,11 @@ outputs:
   gate_decision: "{{gate_decision}}"
   xref_edge_count: "{{xref_edge_count}}"
   domain_model: "{{domain_model}}"
+  # The before-image of both masters, taken immediately before the rewrite and archived with
+  # the change by close-delta. What an un-merge would restore from.
+  pre_merge_snapshot: "{{snapshot_dir}}"
+  base_version: "{{base_version}}"
   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."
+  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, so backend-plan.md / frontend-plan.md now stand BEHIND the spec and model at their last authored content. That drift starts here and lasts until /appweaver plan main re-derives them, carrying the recorded decisions (DA-n) and workarounds (WA-n) forward and rewriting what the spec and model no longer support. analyze-plan is not what closes it and cannot repair it while this change is open: with a change open it runs READ-ONLY, reporting the drift into plan-analyze-report.md without rewriting either plan. The full gate — check, repair, stop — comes back once the last change is closed, so the order is close-delta, then plan main, then analyze-plan. OKF edges reconciled ({{xref_edge_count}} dep(s)), {{downstream_count}} downstream slice(s) fenced (gate: {{gate_decision}}). The concept Overview was distilled for aggregate(s) `{{overview_scope}}` — taken from what this change's model delta DECLARES it touched, not assumed from the feature name (empty on a behaviour-only change, which falls back to the feature). section_found={{overview_section_ok}}, written={{overview_written}}{{overview_reason}} — written=false is normal for a behaviour-only change (nothing to distil, the existing Overview stands), but section_found=false means domain-model.md has no `## Aggregate:` section under that name and the concept's Overview was left as it was: check that the feature name matches the aggregate the model defines. 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."