aw-spec-cli 0.1.32 → 0.1.34

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

@@ -19,9 +19,11 @@
 #
 # This stage AUTHORS nothing and generates NO code — no model is invoked. It moves
 # changes/<id>/ into changes/archive/, bumps the minor version, clears active_change, and
-# STAMPS that version into the `**Version**:` header of spec.md + backend-plan.md and into
-# the change's own Change History row, which finalize-delta left reading `(pending)` — the
-# single irreversible act of the CR loop, deliberately isolated in a stage of its own.
+# STAMPS that version into the `**Version**:` header of spec.md, backend-plan.md and
+# api-plan.md and into the change's own Change History rows — spec.md's, and api-plan.md's
+# where finalize-delta merged the change's API into it — which finalize-delta left reading
+# `(pending)`: the single irreversible act of the CR loop, deliberately isolated in a stage
+# of its own.
 #
 # TWO SPINES, NOT ONE. The feature's version records what THIS feature shipped. The
 # bounded context's version records the shared domain-model.md, which every feature in the
@@ -36,24 +38,29 @@
 # deterministic except the summary, which needs a sentence about the change — and this
 # stage invokes no model by design. Left unwritten rather than half-filled.
 #
-# THE VERSION SPINE LIVES HERE, AND ONLY HERE. The number has FOUR carriers — spec.md's
-# header, backend-plan.md's header, spec.md's Change History row, and active_version.json —
-# and all four move in this one step by one deterministic mechanism. Before, backend-plan.md's
+# THE VERSION SPINE LIVES HERE, AND ONLY HERE. The number's carriers — the `**Version**:`
+# headers of spec.md and of the feature's plans (backend-plan.md, api-plan.md and
+# frontend-plan.md, whichever it has), the change's Change History rows in spec.md and
+# api-plan.md, and active_version.json — all move in this one step by one deterministic
+# mechanism. Before, backend-plan.md's
 # header was bumped by the MODEL at finalize-delta (a stage early, and guessing the target
 # since the number was never passed into the merge prompt) while spec.md's header was bumped
 # by nobody at all, leaving the "living truth" document permanently at v1.0.
 #
-# THE CHANGE HISTORY ROW IS THE FOURTH CARRIER, and it joined the spine for the same reason
+# THE CHANGE HISTORY ROW IS A CARRIER TOO, and it joined the spine for the same reason
 # the headers did. finalize-delta appends the row when it MERGES — a stage before this number
 # exists — and used to write version-read's `next_version` into it: a PREDICTION of the bump.
 # A change that merged and never closed (an abandoned run, a red analyze-slice) then left
 # spec.md asserting a version nothing ever issued. The merge now writes `(pending)` and
 # version-stamp --cr-id fills it here, so the row and its number land together. That is the
-# rule domain-model.md was always held to, and spec.md was the document breaking it.
+# rule domain-model.md was always held to, and spec.md was the document breaking it. The
+# API plan's row, which finalize-delta's API merge writes the same way, is filled by the
+# same call.
 #
 # This stage no longer merges the lane plans at all (they are derived from spec.md +
 # domain-model.md), so a plan header stamped here is stating the version the slice ships as,
-# not that the plan was re-derived for it.
+# not that the plan was re-derived for it. api-plan.md is different: it is a master, merged at
+# finalize-delta, so its header states the version its content ships as.
 #
 # NOTE: nothing MECHANICALLY proves analyze-slice ran green before this point — the
 # stage boundary is operator-driven, as everywhere else in this pipeline. And nothing
@@ -63,6 +70,14 @@
 # back — it is found by `cr-list` (every stage that asks which change shows it), not by
 # the next command refusing.
 #
+# THE CHANGE'S API IS MERGED BEFORE IT IS ARCHIVED. finalize-delta merges the change's API
+# into api-plan.md and stops when it cannot, naming the command that finishes the merge. The
+# archive takes the change out of the set contract-combine applies over the feature's draft,
+# so a change archived with its API unmerged takes its endpoints out of the frontend lane's
+# document for good, and api-plan.md never gets them. Step 2c asks `contract-merge --check`
+# before anything moves, and stops when the change carries an API delta that api-plan.md has
+# no Change History row for — every merge writes one. A change with no API delta passes.
+#
 # WHICH CHANGE IS CLOSED 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 a bare
@@ -78,8 +93,8 @@
 # =============================================================================
 
 name: aw-spec-close-delta
-description: Close ONE chosen open change — archive changes/<id>/ into changes/archive/, bump the minor version, clear active_change, and stamp that version into the feature's master headers (spec.md, backend-plan.md, and frontend-plan.md where the feature has a UI half), then anchor the close in the OKF freshness log. ASKS which change (a bare CR id as the argument skips the prompt) and confirms even a lone one, rather than taking whichever was last opened. The final CR stage, run after finalize-delta merged the delta and analyze-slice verified the slice. The sole owner of the version spine; invokes no model and generates no code.
-version: 1.4.0
+description: Close ONE chosen open change — archive changes/<id>/ into changes/archive/, bump the minor version, clear active_change, and stamp that version into the feature's master headers (spec.md, backend-plan.md, api-plan.md, and frontend-plan.md where the feature has a UI half) and into the change's Change History rows in spec.md and api-plan.md, then anchor the close in the OKF freshness log. ASKS which change (a bare CR id as the argument skips the prompt) and confirms even a lone one, rather than taking whichever was last opened. Stops before the archive when the change carries an API delta that is not merged into api-plan.md. The final CR stage, run after finalize-delta merged the delta and analyze-slice verified the slice. The sole owner of the version spine; invokes no model and generates no code.
+version: 1.6.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -99,7 +114,7 @@ scripts:
 
 # No standards seed and no domain/tech rule selection: this stage authors nothing, so it
 # has no prompt to govern. It is pure bookkeeping over active_version.json + changes/ +
-# the two version headers.
+# the masters' version headers.
 standards: []
 
 vars:
@@ -110,6 +125,8 @@ vars:
   stamped_docs: ""      # which master headers version-stamp actually rewrote
   stamped_count: "0"
   history_filled: "false"   # whether the merge's `(pending)` Change History row was completed here
+  history_rows: ""          # every document whose pending row was completed: spec.md, api-plan.md
+  api_merged_ok: "true"     # false unless contract-merge --check answers that nothing is still to merge
   # The CONTEXT's spine, moved only when the closing change carried a model delta.
   # Defaulted so the outputs read a real value on a behaviour-only close, where the step
   # runs and correctly declines to bump.
@@ -209,6 +226,31 @@ workflow:
       - { name: delta_model_exists, from: "$.delta_model_exists" }
       - { name: context_dir,        from: "$.context_dir" }
 
+  # 2c. IS THE CHANGE'S API MERGED? Asked before the archive, which takes the change out of
+  #     the set contract-combine applies: a change archived with its API unmerged takes its
+  #     endpoints out of the frontend lane's document for good. Read-only. The change's API
+  #     delta is read as the merge reads it (its delta API plan, or its delta backend plan's
+  #     API section); api-plan.md's Change History row naming the change is the record of the
+  #     merge. No on_error, and only an explicit `needed: false` passes: a check that does
+  #     not answer stops the stage before anything irreversible runs.
+  - id: api_merge_check
+    action: execute_script
+    script: { ref: actions }
+    subcommand: contract-merge
+    args: ["--feature-dir", "{{feature_dir}}", "--cr", "{{active_change}}", "--check"]
+    outputs:
+      - { name: api_merge_needed, from: "$.needed" }
+      - { name: api_merge_reason, from: "$.reason" }
+  - id: api_merge_pending_flag
+    condition: "{{api_merge_needed}} != false"
+    action: set
+    vars: { api_merged_ok: "false" }
+  - id: require_api_merged
+    action: verify_context
+    require_true: api_merged_ok
+    on_false: stop
+    on_false_message: "close-delta STOPPED before archiving — nothing was archived and the version did not move. Change {{active_change}} carries an API delta that is not merged into the feature's api-plan.md ({{api_merge_reason}}). Archiving it now would take its endpoints out of the frontend lane's document for good, and spend a version number on an API the master does not carry. If finalize-delta stopped at its API merge, finish that merge — `.appweaver/scripts/bash/aw-spec-actions.sh contract-merge --feature-dir {{feature_dir}} --cr {{active_change}}` (PowerShell: `.appweaver/scripts/powershell/aw-spec-actions.ps1 contract-merge --feature-dir {{feature_dir}} --cr {{active_change}}`); it merges by whole endpoint block and a second run changes nothing. If finalize-delta has not run for this change, run /appweaver finalize-delta instead — it merges the spec, the model and the API together — then /appweaver analyze-slice. Then re-run /appweaver close-delta."
+
   # 3. Pre-execution hooks.
   - id: resolve_pre_hooks
     action: execute_script
@@ -236,9 +278,11 @@ workflow:
       - { name: previous_version, from: "$.previous" }
       - { name: archived_dir,     from: "$.archived_dir" }
 
-  # 4b. STAMP the number just computed into the two master headers AND into this change's
-  #     Change History row, so spec.md, backend-plan.md, the row and active_version.json all
-  #     carry it from the same instant by the same mechanism. Previously backend-plan.md's
+  # 4b. STAMP the number just computed into the master headers AND into this change's
+  #     Change History rows, so spec.md, backend-plan.md, api-plan.md, the rows and
+  #     active_version.json all carry it from the same instant by the same mechanism. The
+  #     API plan's row is the one finalize-delta's API merge wrote; a change with no API
+  #     wrote none, and only spec.md's is filled. Previously backend-plan.md's
   #     header was bumped by the MODEL back at finalize-delta (guessing the target — the
   #     number was never passed to it) and spec.md's header was bumped by nobody, so it sat
   #     at v1.0 for the life of the feature.
@@ -259,6 +303,7 @@ workflow:
       - { name: stamped_docs,   from: "$.stamped" }
       - { name: stamped_count,  from: "$.count" }
       - { name: history_filled, from: "$.history_row_filled" }
+      - { name: history_rows,   from: "$.history_rows_filled" }
 
   # 4c. THE CONTEXT'S OWN VERSION, which is a DIFFERENT spine from the feature's. The
   #     feature version says what this feature shipped; domain-model.md is shared by every
@@ -316,6 +361,7 @@ outputs:
   previous_version: "{{previous_version}}"
   archived_dir: "{{archived_dir}}"
   stamped_docs: "{{stamped_docs}}"
+  history_rows: "{{history_rows}}"
   # The bounded context's own spine — a DIFFERENT number from the feature's, moved only
   # when this change carried a model delta. context_bumped=false on a behaviour-only
   # change is the correct outcome, not a skipped step.
@@ -323,4 +369,4 @@ outputs:
   context_version: "{{context_version}}"
   context_version_bumped: "{{context_bumped}}"
   model_touched: "{{delta_model_exists}}"
-  next: "Change {{active_change}} CLOSED — archived to {{archived_dir}}, version {{previous_version}} -> {{version}}, stamped into {{stamped_count}} master header(s) ({{stamped_docs}}) and into this change's Change History row (row completed={{history_filled}} — it read `(pending)` from the moment finalize-delta merged, because the number did not exist until now; false means it was already filled, which is the ordinary outcome of a re-run). spec.md, backend-plan.md, that row and active_version.json now all read {{version}} — and frontend-plan.md too where the feature has a UI half ({{stamped_docs}} names what was actually rewritten); the masters describe the shipped state and the feature is free to take a new change. Bounded context `{{bounded_context}}`: context version moved={{context_bumped}} ({{context_version_before}} -> {{context_version}}) — {{context_bump_reason}}. That number is the CONTEXT's, not this feature's: domain-model.md is shared by every feature in it, so only a change that merged a model delta moves it. THE LANE PLANS STILL STAND WHERE THEY WERE AUTHORED: finalize-delta merged this change into spec.md and domain-model.md only, because backend-plan.md / frontend-plan.md are DERIVED from those two and nothing derives them again on its own. Re-derive with /appweaver plan main (it carries DA-n / WA-n forward and asks before rewriting), then /appweaver analyze-plan re-anchors the spec↔plan gate — it repairs and stops only once NO change is open, and runs read-only until then. Next: /appweaver run → deploy, or start the next change with /appweaver specify."
+  next: "Change {{active_change}} CLOSED — archived to {{archived_dir}}, version {{previous_version}} -> {{version}}, stamped into {{stamped_count}} master header(s) ({{stamped_docs}}) and into this change's Change History row (row completed={{history_filled}} — it read `(pending)` from the moment finalize-delta merged, because the number did not exist until now; false means it was already filled, which is the ordinary outcome of a re-run). Rows completed: {{history_rows}} — api-plan.md's is there when finalize-delta merged the change's API into it. spec.md, backend-plan.md, api-plan.md, those rows and active_version.json now all read {{version}} — and frontend-plan.md too where the feature has a UI half ({{stamped_docs}} names what was actually rewritten); the masters describe the shipped state and the feature is free to take a new change. Bounded context `{{bounded_context}}`: context version moved={{context_bumped}} ({{context_version_before}} -> {{context_version}}) — {{context_bump_reason}}. That number is the CONTEXT's, not this feature's: domain-model.md is shared by every feature in it, so only a change that merged a model delta moves it. THE LANE PLANS STILL STAND WHERE THEY WERE AUTHORED: finalize-delta merged this change into spec.md, domain-model.md and api-plan.md only, because backend-plan.md / frontend-plan.md are DERIVED from those and nothing derives them again on its own. Re-derive with /appweaver plan main (it carries DA-n / WA-n forward and asks before rewriting), then /appweaver analyze-plan re-anchors the spec↔plan gate — it repairs and stops only once NO change is open, and runs read-only until then. Next: /appweaver run → deploy, or start the next change with /appweaver specify."

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

@@ -2,7 +2,8 @@
 # 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 into the two documents that
-# DEFINE the slice — the feature's spec.md and the bounded context's domain-model.md — then
+# DEFINE the slice — the feature's spec.md and the bounded context's domain-model.md — and its
+# API delta into the feature's api-plan.md, the API contract the frontend lane binds to; then
 # refresh the OKF knowledge layer. After this the masters describe the shipped-plus-change
 # state, but THE CHANGE REMAINS OPEN.
 #
@@ -14,6 +15,18 @@
 # 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 API PLAN IS THE THIRD MASTER, MERGED BY SCRIPT AFTER THE TWO:
+#   • specs/<Feature>/api-plan.md      ← changes/<id>/delta-api-plan.md
+# The endpoints the service publishes are agreed between the lanes, not derived from the
+# spec, so api-plan.md is a master like spec.md and is merged, not re-derived. `contract-merge`
+# merges whole endpoint blocks, keyed by operation id, with no model involved, and redraws the
+# feature's api-draft.json from the result. It runs once the spec and model merge has landed
+# and is not part of that transaction: the script is deterministic, a second run changes
+# nothing, and a run that did not answer stops this stage naming the command that finishes it.
+# A change planned before delta API plans existed keeps its API in its delta backend plan, and
+# the script reads it there; a feature planned before API plans existed keeps its endpoints in
+# its backend plan, and its first merge moves them into a new api-plan.md (api-split) first.
+#
 # 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
@@ -73,7 +86,9 @@
 # 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.
+# finalize-delta edits ONLY spec.md and domain-model.md, and by script api-plan.md and the
+# api-draft.json drawn from it — plus, on a feature whose endpoints were still in its backend
+# plan, that plan, to move them out. It generates no code.
 #
 # 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
@@ -138,8 +153,8 @@
 # =============================================================================
 
 name: aw-spec-finalize-delta
-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 regression fence over the whole blast radius (fence_green) — the transitive REFERRER closure and the features that CO-OWN the aggregates this delta touches, which hold no edge to it but whose code is in the same files — writing a triage report and asking 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.5.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; then merge its delta API plan into the feature's api-plan.md by script — whole endpoint blocks keyed by operation id, the answered frontend requests and a Change History row — and redraw api-draft.json from it. 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 regression fence over the whole blast radius (fence_green) — the transitive REFERRER closure and the features that CO-OWN the aggregates this delta touches, which hold no edge to it but whose code is in the same files — writing a triage report and asking Abort/Override on red. Snapshots the masters, the backend plan and the API draft 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.6.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -230,6 +245,27 @@ vars:
   overview_reason: ""
   backend_plan: ""            # READ, never written here — the OKF edges are parsed out of it
   backend_plan_exists: "false"
+  delta_api_plan: ""          # changes/<id>/delta-api-plan.md — the change's API half
+  # THE API MERGE (contract-merge). api_merge_ok defaults DOWN and is raised only by a run
+  # that answered, so a script that failed leaves the stop after it to say so.
+  api_merge_ok: "false"
+  api_merged: "false"         # false with a reason: the change has no API to merge
+  api_merge_written: "false"
+  api_split: "false"          # the feature's endpoints were moved out of its backend plan first
+  api_plan: ""
+  api_delta: ""               # the document the change's API was read from
+  api_added: ""
+  api_changed: ""
+  api_removed: ""
+  api_requests: ""            # the frontend requests whose answers joined the API plan
+  api_history_row: "false"
+  api_draft: ""
+  api_draft_operations: "0"
+  api_dropped_text: "none"    # operations the redraw dropped that the change does not remove
+  api_merge_warning: ""
+  api_merge_reason: ""
+  api_merge_clean: "true"
+  api_draft_kept: "true"
 
 workflow:
 
@@ -336,6 +372,7 @@ workflow:
       - { name: delta_model,         from: "$.delta_model" }
       - { name: delta_model_exists,  from: "$.delta_model_exists" }
       - { name: delta_backend_plan,  from: "$.delta_backend_plan" }
+      - { name: delta_api_plan,      from: "$.delta_api_plan" }
       - { name: domain_model,        from: "$.domain_model" }
       - { name: domain_model_exists, from: "$.domain_model_exists" }
 
@@ -595,9 +632,11 @@ workflow:
     context:
       - { path: "{{spec_file}}" }
       - { 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.
+      # The delta plans are how the change was BUILT — the most direct account of what could
+      # have broken a dependent, and the delta API plan of a broken contract between slices.
+      # Optional: a frontend-only change never has them.
       - { path: "{{delta_backend_plan}}", optional: true }
+      - { path: "{{delta_api_plan}}", optional: true }
   - id: write_broken_downstream
     action: agent_author
     condition: "{{blast_any}}"
@@ -755,6 +794,8 @@ workflow:
       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.
+      api-plan.md is not yours either: the change's API is merged into it by script once
+      this merge has landed, so do not open or edit it.
       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
@@ -819,8 +860,8 @@ workflow:
       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.
+      delta documents (close-delta archives them later), do NOT open or edit any lane plan
+      or the API plan, and do NOT touch any source code. Report the files you changed.
     outputs:
       - { name: merged_docs, from: "$.files" }
 
@@ -957,6 +998,81 @@ workflow:
     outputs:
       - { name: xref_log, from: "$.log" }
 
+  # 4d. THE API MERGE — the change's delta API plan into the feature's api-plan.md, by script.
+  #     Whole endpoint blocks, keyed by operation id (by verb and route for a block without
+  #     one, which keeps the id its row or the block it replaces gives that route): a changed
+  #     block replaces the API plan's, an added one goes after the last, a
+  #     removed one is deleted, and a Contract deltas row with no block is written from the
+  #     row and reported — never over a block the change wrote on the same route. The requests the change answers replace or join the requests table,
+  #     and a Change History row is written with `(pending)` in its Version cell for
+  #     close-delta to stamp. api-draft.json is redrawn from the result in the same call.
+  #     A change with no API delta merges nothing, which is the whole outcome for a
+  #     behaviour-only or frontend-only change. One planned before delta API plans existed
+  #     is read from its delta backend plan's API section; a feature with no api-plan.md yet
+  #     has its endpoints moved out of its backend plan into one first (api-split).
+  #     After the spec and model merge, so the API never moves when the merge above wrote
+  #     nothing; after the OKF refresh, so a run that fails here still leaves the knowledge
+  #     layer current. on_error: continue, so a failure reaches the stop below, which names
+  #     the command that finishes the merge.
+  - id: merge_api
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-merge
+    args: ["--feature-dir", "{{feature_dir}}", "--cr", "{{active_change}}"]
+    outputs:
+      - { name: api_merge_ok,         from: "$.ok" }
+      - { name: api_merged,           from: "$.merged" }
+      - { name: api_merge_written,    from: "$.written" }
+      - { name: api_split,            from: "$.split" }
+      - { name: api_plan,             from: "$.path" }
+      - { name: api_delta,            from: "$.delta" }
+      - { name: api_added,            from: "$.added" }
+      - { name: api_changed,          from: "$.changed" }
+      - { name: api_removed,          from: "$.removed" }
+      - { name: api_requests,         from: "$.requests" }
+      - { name: api_history_row,      from: "$.history_row" }
+      - { name: api_draft,            from: "$.draft" }
+      - { name: api_draft_operations, from: "$.draft_operations" }
+      - { name: api_dropped_text,     from: "$.dropped_text" }
+      - { name: api_merge_warning,    from: "$.warning" }
+      - { name: api_merge_reason,     from: "$.reason" }
+
+  # spec.md and domain-model.md already carry the change when this fires. Re-running
+  # finalize-delta would merge them a second time and retake the pre-merge snapshot from the
+  # merged masters, so the message names the script instead, which a second run leaves as it
+  # is. Stopping here keeps the post hooks from taking a half-merged change for a merged one,
+  # and keeps the change from reaching close-delta, whose archive would take its endpoints out
+  # of the frontend lane's document for good.
+  - id: require_api_merged
+    action: verify_context
+    require_true: api_merge_ok
+    on_false: stop
+    on_false_message: "finalize-delta STOPPED after the merge — change {{active_change}} IS merged into spec.md and the context's domain-model.md, but merging its API into the feature's api-plan.md did not complete: the contract-merge script did not answer. Run it to see why and, once the cause is fixed, to finish the merge — `.appweaver/scripts/bash/aw-spec-actions.sh contract-merge --feature-dir {{feature_dir}} --cr {{active_change}}` (PowerShell: `.appweaver/scripts/powershell/aw-spec-actions.ps1 contract-merge --feature-dir {{feature_dir}} --cr {{active_change}}`). It merges by whole endpoint block and a second run changes nothing. Do NOT re-run /appweaver finalize-delta: it would merge spec.md and domain-model.md a second time. Then continue with /appweaver analyze-slice; do not run /appweaver close-delta until the API is merged, because archiving the change takes its endpoints out of the frontend lane's document."
+
+  # What the merge could not do exactly as the change says: an endpoint written from its
+  # Contract deltas row because the change wrote no block for it, a row whose route the
+  # change's block took under another id, or a changed endpoint the API plan did not have.
+  # Reported, not blocking — the change is merged either way.
+  - id: api_merge_clean_flag
+    condition: "{{api_merge_warning}} != "
+    action: set
+    vars: { api_merge_clean: "false" }
+  - id: warn_api_merge
+    action: verify_context
+    require_true: api_merge_clean
+    on_false: continue
+    on_false_message: "{{api_merge_warning}}"
+  - id: api_draft_dropped_flag
+    condition: "{{api_dropped_text}} != none"
+    action: set
+    vars: { api_draft_kept: "false" }
+  - id: warn_api_draft_dropped
+    action: verify_context
+    require_true: api_draft_kept
+    on_false: continue
+    on_false_message: "API DRAFT — after the merge, {{api_draft}} no longer has operation(s) the previous draft had and change {{active_change}} does not remove: {{api_dropped_text}}. The frontend lane may still bind to them. If they were dropped on purpose, remove them through a change; if not, restore their blocks in {{api_plan}}."
+
   # 5. NO ARCHIVE, NO VERSION BUMP HERE. Both moved to close-delta, which runs after
   #    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
@@ -996,4 +1112,11 @@ outputs:
   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, 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 aggregate the feature answers for). 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 spec's Acts on aggregate(s) line names an 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."
+  # The API plan, the third master: whether the change's API was merged into it, and the
+  # draft redrawn from it. api_split=true ⇒ the feature's endpoints were moved out of its
+  # backend plan into a new api-plan.md first.
+  api_plan: "{{api_plan}}"
+  api_merged: "{{api_merged}}"
+  api_split: "{{api_split}}"
+  api_draft: "{{api_draft}}"
+  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 API: merged={{api_merged}} into {{api_plan}} from {{api_delta}} — added {{api_added}}, changed {{api_changed}}, removed {{api_removed}}, requests answered {{api_requests}}, Change History row written={{api_history_row}} (its version reads `(pending)` until close-delta stamps it); {{api_draft}} redrawn with {{api_draft_operations}} operation(s). merged=false means the change has no API to merge: {{api_merge_reason}}. api_split={{api_split}} — true means the feature's endpoints and requests table were first moved out of its backend plan into api-plan.md, the only edit this stage makes to a lane plan. The lane plans were NOT merged — they are DERIVED from these 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 aggregate the feature answers for). 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 spec's Acts on aggregate(s) line names an 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."