fix: continue manual merge workflow after commit

Author: rossant

design/merge-view-architecture.md

@@ -152,9 +152,12 @@ The refactor should establish the following invariants:
    before and after states.
 8. Cancellation restores the exact entry snapshot.
 9. Undoing a Merge-mode merge restores the exact pre-commit workspace.
-10. Workspace edits do not enter the curation undo stack.
-11. Public selection and plugin APIs remain compatible.
-12. Selection transitions operate on cluster IDs and do no work proportional to
+10. A successful manual merge remains in Merge mode with its result as the sole
+    blue reference; its cancellation snapshot is the corresponding settled
+    Normal-mode result selection.
+11. Workspace edits do not enter the curation undo stack.
+12. Public selection and plugin APIs remain compatible.
+13. Selection transitions operate on cluster IDs and do no work proportional to
     every spike.
 
 ## 4. Proposed domain model
@@ -210,6 +213,8 @@ class MergeSession:
     reference_id: int
     ordered_ids: tuple[int, ...]
     entry_snapshot: NormalWorkflowSnapshot
+    proposition_id: str | None = None
+    is_post_merge: bool = False
 ```
 
 `ordered_ids[0]` is always `reference_id`. The reference cannot be removed or
@@ -221,6 +226,13 @@ not arbitrary application state. It includes selections, reference,
 presentation order, and any table filter, sort, scroll, or navigation state that
 entering or editing Merge mode changes.
 
+`is_post_merge` distinguishes the automatically retained singleton workspace
+from a manually entered, uncommitted workspace. This allows `Undo` to target the
+commit directly without allowing a fresh temporary workspace to undo an older
+curation action. Workspace edits preserve this marker; exiting and manually
+re-entering Merge mode clears it. Proposition workspaces use their own provenance
+and automatic-advancement contract and are never post-merge continuations.
+
 ### 4.4 Selection change
 
 ```python
@@ -402,11 +414,17 @@ For a Merge-mode merge:
 
 1. capture the complete pre-commit Merge state;
 2. execute the clustering merge;
-3. capture the resulting Normal-mode state;
+3. capture the resulting Normal-mode state and wrap it as the entry snapshot of
+   a singleton post-merge continuation workspace;
 4. store both on the global action entry;
 5. on undo, undo controllers and restore `selection_before` transactionally; and
 6. on redo, redo controllers and restore `selection_after` transactionally.
 
+The continuation keeps Merge View visible, makes the result the sole staged blue
+reference, clears Similarity selection, and recomputes Similarity rows. Exiting
+with `V` restores its settled Normal-mode result snapshot. Group and metadata
+actions remain disabled until that exit.
+
 The existing `request_undo_state` mechanism may be used as a compatibility step,
 but the final ownership of Merge workflow context belongs to the global curation
 action, not the `Clustering` model.
@@ -529,6 +547,8 @@ The initial Merge-mode action policy is:
 - reject unsafe direct or plugin calls explicitly without partially mutating the
   workspace;
 - do not let an uncommitted Merge session undo an earlier curation action;
+- keep a successful manual merge in a marked singleton continuation workspace
+  whose Undo action targets that commit directly;
 - after undoing a Merge-mode merge, allow redo to reapply it; and
 - truncate that redo branch normally if the restored workspace is edited and a
   different curation action is committed.

design/merge-view-dock-stability.md

@@ -104,7 +104,9 @@ Automatic advancement after a successful proposition merge is slightly
 different because the clustering has changed. It should construct the settled
 post-merge Normal state, use that as the next proposition's entry snapshot, and
 then project the next Merge workspace without hiding or recreating the dock.
-Failed and manual merges retain their existing no-advancement behavior.
+Failed merges retain their workspace unchanged. Successful manual merges do not
+advance proposition review; they reuse the dock for a singleton continuation
+workspace containing the merged result as its blue reference.
 
 Reject-and-advance and shortcut navigation use the same in-place replacement
 path. Selecting a nonactionable proposition still cancels to Normal mode and
@@ -201,8 +203,9 @@ intermittent Qt shutdown crash.
 - `P1 -> P2` preserves `id(merge_view)` and `id(merge_view.dock)`.
 - Manual Merge to proposition review preserves those identities.
 - Shortcut navigation and reject-and-advance do not hide or recreate the dock.
-- Successful auto-advance updates the existing view; failed and manual merges
-  do not advance.
+- Successful auto-advance updates the existing view; successful manual merges
+  project the result into the same view without advancing, and failed merges
+  leave it unchanged.
 - All unrelated dock geometries remain unchanged across proposition switches.
 - Cancel/hide/reopen restores the Merge dock area and docked extent.
 - A floating Merge dock retains its exact position and size.

design/merge-view-workflow.md

@@ -147,31 +147,48 @@ GUI reports that another candidate is required.
 
 After a successful merge:
 
-- Merge mode ends;
-- Merge View is cleared and hidden while its dataset-scoped dock is retained;
-- Cluster View is re-enabled;
-- the new merged cluster becomes the blue Cluster View selection; and
-- Similarity View is recomputed for the new cluster using the normal post-merge
-  workflow.
+- Merge mode remains active;
+- Merge View replaces the committed inputs with the new merged cluster as its
+  sole staged row and blue reference;
+- Similarity View clears its selection and is recomputed for the new cluster;
+- the curator may stage or select more candidates and press `G` again; and
+- the dock control changes from **Cancel Merge Mode** to **Exit Merge Mode**;
+  `V`, that control, or closing Merge View exits to Normal mode with the merged
+  cluster selected in Cluster View.
+
+Group and metadata changes remain unavailable while Merge mode is active. The
+curator must exit with `V`, **Exit Merge Mode**, or the Merge View close control
+before classifying the merged cluster as `good`, `mua`, `noise`, or another
+quality.
+
+Successful proposition merges keep their separate review contract: they open
+the next pending proposition when one exists, rather than pausing on the merged
+result.
 
 If the merge fails, the complete Merge-mode state remains unchanged.
 
-## Cancelling Merge mode
+## Cancelling or exiting Merge mode
 
-All of the following cancel Merge mode:
+All of the following leave Merge mode:
 
 - pressing `V` while Merge mode is active;
-- activating a prominent **Cancel Merge Mode** control; or
+- activating the prominent **Cancel Merge Mode** control, renamed **Exit Merge
+  Mode** after a successful manual commit; or
 - closing Merge View.
 
-Cancellation performs no clustering action. It restores the exact snapshot from
-immediately before Merge mode was entered, regardless of additions, removals, or
-reordering performed in Merge mode. In other words:
+Cancellation performs no clustering action. Before the first commit, it restores
+the exact snapshot from immediately before Merge mode was entered, regardless of
+additions, removals, or reordering performed in Merge mode. In other words:
 
 ```text
 state A -> enter Merge mode -> edit workspace -> cancel -> state A
 ```
 
+After a successful manual merge, the continuation workspace receives a new
+Normal-mode entry snapshot containing the merged cluster. Cancelling that
+workspace therefore exits with the committed merged cluster selected; it never
+tries to restore source clusters that no longer exist.
+
 Closing Merge View must visibly communicate that it cancels the mode. Merge mode
 must also be unmistakable while active: Merge View is labelled **MERGE MODE**,
 Cluster View is dimmed or overlaid with an explanation, and the status area shows
@@ -195,8 +212,12 @@ before `G`, including:
 
 Undoing that merge restores both the original clusters and the complete Merge
 workspace as it existed immediately before `G`. Redoing it reapplies the merge
-and exits Merge mode again. This special restoration applies only to merges
-initiated from Merge mode; ordinary merge undo behavior remains unchanged.
+and restores the singleton post-merge continuation workspace. `Undo` is
+available in that continuation workspace and targets the committed merge
+directly. A manually entered workspace that has not committed a merge still
+cannot undo an earlier curation action. This special restoration applies only
+to merges initiated from Merge mode; ordinary merge undo behavior remains
+unchanged.
 
 Workspace transfers and reordering are temporary UI operations and do not create
 entries in the clustering undo stack.
@@ -210,10 +231,10 @@ entries in the clustering undo stack.
 | Merge | Ctrl+right-click removable Merge row | Transfer candidate to Similarity |
 | Merge | Ctrl+Space | Select the next Similarity candidates |
 | Merge | Backspace | Clear only the Similarity selection |
-| Merge | `G` | Merge Merge contents plus selected Similarity candidates |
+| Merge | `G` | Commit the selection and continue with its result as the blue Merge reference |
 | Merge | `V`, Cancel, or close Merge View | Restore the entry snapshot exactly |
 | After Merge-mode merge | Undo | Restore clusters and pre-commit Merge workspace |
-| Restored after undo | Redo | Reapply merge and return to normal mode |
+| Restored after undo | Redo | Reapply merge and restore the singleton continuation workspace |
 
 ## Extension
 

docs/changelog.md

@@ -40,7 +40,9 @@ behavior they verify rather than listed separately.
   size; proposition navigation updates that dock without moving neighboring
   views. The dimmed Cluster View remains scrollable. Scientific views follow Merge View order and then
   selected Similarity rows in visible table order. Cancellation restores the entry state, and
-  undo restores the full pre-merge workspace.
+  undo restores the full pre-merge workspace. After a successful manual merge,
+  the result remains as the sole blue Merge View reference for inspection or a
+  further merge; press `V` to return to Normal mode before assigning quality.
 - Review AIND/SpikeInterface format-version 2 merge propositions from
   dataset-local `curation.json` in a persistent **Merge Propositions** view.
   Its compact rows have no action buttons and carry stable source-order display

docs/clustering.md

@@ -31,12 +31,20 @@ order-dependent views, while each cluster keeps the same color across tables and
 for the entire Merge session. Press `Backspace` to clear only the Similarity View selection when the
 merge should contain only the staged rows.
 
-Press `G` to commit the staged clusters plus the selected Similarity candidates. Press `V` again,
-use **Cancel Merge Mode**, or close Merge View to cancel and restore the exact state from before
-entry. Undoing a committed Merge-mode merge restores the complete workspace as it appeared just
-before `G`; Redo reapplies the merge and returns to the normal workflow. The Merge View dock is
-reused throughout the dataset session: proposition changes do not move it, and reopening restores
-its previous docked extent or floating position and size without resetting neighboring docks.
+Press `G` to commit the staged clusters plus the selected Similarity candidates. The resulting
+unit remains in Merge View as the sole staged row and blue reference, with Similarity View
+recomputed around it. Add more candidates to continue merging, or press `V` to return to Normal
+mode with the result selected before assigning its quality. Group and metadata changes remain
+unavailable in Merge mode.
+
+Before a merge is committed, pressing `V`, using **Cancel Merge Mode**, or closing Merge View
+cancels and restores the exact state from before entry. After a commit, the dock control becomes
+**Exit Merge Mode** and those controls exit with the latest merged result selected. Undoing a
+committed Merge-mode merge directly restores the complete workspace as it appeared just before
+`G`; Redo reapplies the merge and restores its singleton continuation workspace. The Merge View
+dock is reused throughout the dataset session:
+proposition changes do not move it, and reopening restores its previous docked extent or floating
+position and size without resetting neighboring docks.
 
 ### Reviewing merge propositions
 

docs/quickstart.md

@@ -117,8 +117,12 @@ clusters and press `G` to merge. phy gives the result a new cluster ID. Press
 
 For a longer comparison, press `V` first. Merge View keeps the candidates staged while you
 continue exploring Similarity View. Its status shows exactly how many clusters `G` will merge.
-Press `V` again or close Merge View to cancel without changing the clustering. Reopening uses the
-same dock and restores its previous placement and size.
+After `G`, the merged result stays in Merge View as the blue reference so you can inspect it or
+add candidates for another merge. Press `V` to return to Normal mode before assigning the result
+to `good`, `mua`, or `noise`. Before the first commit, `V` or closing Merge View cancels without
+changing the clustering; afterward it exits with the latest merged result selected. Reopening uses
+the same dock and restores its previous placement and size. `Ctrl+Z` directly undoes the latest
+commit and restores its pre-merge workspace.
 
 If the Template GUI dataset includes an AIND/SpikeInterface format-version 2
 `curation.json` with merge suggestions, use the persistent **Merge Propositions**

phy/cluster/_selection.py

@@ -43,13 +43,16 @@ class MergeSession:
     ordered_ids: tuple[int, ...]
     entry_snapshot: NormalWorkflowSnapshot
     proposition_id: str | None = None
+    is_post_merge: bool = False
 
     def __post_init__(self):
         ordered = _as_unique_ids(self.ordered_ids)
         if not ordered or ordered[0] != self.reference_id:
             raise ValueError('The merge reference must be the first staged cluster.')
         if self.proposition_id is not None and not self.proposition_id:
             raise ValueError('The merge proposition ID cannot be empty.')
+        if self.proposition_id is not None and self.is_post_merge:
+            raise ValueError('A proposition workspace cannot be a post-merge continuation.')
         object.__setattr__(self, 'ordered_ids', ordered)
 
 
@@ -350,6 +353,26 @@ def enter_merge_proposition(self, proposition_id, ordered_ids, workflow_context=
             )
         )
 
+    def continue_after_merge(self, cluster_id, workflow_context=None):
+        """Continue manual Merge mode with a committed result as the new reference."""
+        self._require_merge_mode()
+        if self._state.merge.proposition_id is not None:
+            raise ValueError('Proposition merges advance through the proposition workflow.')
+        normal = CurationSelectionState(cluster_ids=(cluster_id,))
+        merge = MergeSession(
+            cluster_id,
+            (cluster_id,),
+            NormalWorkflowSnapshot(normal, workflow_context),
+            is_post_merge=True,
+        )
+        return self._apply(
+            CurationSelectionState(
+                mode=WorkflowMode.MERGE,
+                reference_id=cluster_id,
+                merge=merge,
+            )
+        )
+
     def switch_merge_proposition(self, proposition_id, ordered_ids):
         """Replace the active Merge workspace while preserving its Normal entry snapshot."""
         self._require_merge_mode()
@@ -395,6 +418,7 @@ def add_to_merge(self, cluster_ids, insertion=None):
             tuple(ids),
             current.merge.entry_snapshot,
             proposition_id=current.merge.proposition_id,
+            is_post_merge=current.merge.is_post_merge,
         )
         similar = tuple(cluster_id for cluster_id in current.similar_ids if cluster_id not in new)
         effective = _ordered_union(merge.ordered_ids, similar)
@@ -421,6 +445,7 @@ def remove_from_merge(self, cluster_ids):
             tuple(i for i in current.merge_ids if i not in removed),
             current.merge.entry_snapshot,
             proposition_id=current.merge.proposition_id,
+            is_post_merge=current.merge.is_post_merge,
         )
         similar = _ordered_union(current.similar_ids, removed)
         effective = _ordered_union(merge.ordered_ids, similar)
@@ -452,6 +477,7 @@ def deselect_from_merge(self, cluster_ids):
             merge_ids,
             current.merge.entry_snapshot,
             proposition_id=current.merge.proposition_id,
+            is_post_merge=current.merge.is_post_merge,
         )
         slots = list(current.color_slots)
         if reference != current.reference_id:
@@ -484,6 +510,7 @@ def reorder_merge(self, cluster_ids, insertion):
             tuple(remain),
             current.merge.entry_snapshot,
             proposition_id=current.merge.proposition_id,
+            is_post_merge=current.merge.is_post_merge,
         )
         return self._apply(
             CurationSelectionState(