fix(overlays): detect ancestor-conflict anchors in merge_steps

When two overlay edits target anchors that share a parent/descendant
relationship (e.g. remove an if-step + insert_after a nested child),
merge_steps processed them independently and in dict-insertion order,
making the outcome non-deterministic.

Add two private helpers to merge.py:
- _descendant_ids(step): returns all step IDs nested inside a step dict
  by delegating to the existing _all_base_step_ids helper on children.
- _check_anchor_conflicts(anchors, base_steps): for each targeted anchor
  finds its descendants and checks whether any other targeted anchor is
  among them; returns human-readable error strings.

Wire _check_anchor_conflicts into merge_steps immediately after
edits_by_anchor is built, before any tree mutation occurs. Raises
ValueError listing the conflicting anchor pair(s) so overlay authors
know exactly what to fix.

Add TestMergeStepsAncestorConflicts (6 cases):
- remove parent + insert_after child raises ValueError
- replace parent + remove child raises ValueError
- conflict across multiple overlays raises ValueError
- sibling anchors (not ancestor/descendant) pass
- single anchor passes
- parent targeted but child not targeted passes

Closes review comment r3596368746 (PR #3557, round 2, cluster 3).

Assisted-by: GitHub Copilot (model: claude-sonnet-4.6, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Markus

src/specify_cli/workflows/overlays/merge.py

@@ -81,6 +81,49 @@ def _all_base_step_ids(steps: list[dict[str, Any]]) -> set[str]:
     return ids
 
 
+def _descendant_ids(step: dict[str, Any]) -> set[str]:
+    """Return all step IDs nested inside *step* (not including *step* itself)."""
+    ids: set[str] = set()
+    for key in _NESTED_LIST_KEYS:
+        nested = step.get(key)
+        if isinstance(nested, list):
+            ids.update(_all_base_step_ids(nested))
+    cases = step.get("cases")
+    if isinstance(cases, dict):
+        for case_steps in cases.values():
+            if isinstance(case_steps, list):
+                ids.update(_all_base_step_ids(case_steps))
+    return ids
+
+
+def _check_anchor_conflicts(
+    anchors: set[str],
+    base_steps: list[dict[str, Any]],
+) -> list[str]:
+    """Return error messages for anchor pairs where one is an ancestor of the other.
+
+    When two targeted anchors share a parent/descendant relationship the edit
+    processing order determines success or failure, producing non-deterministic
+    results.  Callers should raise on any returned errors before mutating the
+    step tree.
+    """
+    errors: list[str] = []
+    for anchor in sorted(anchors):  # sorted for deterministic error order
+        location = find_step(base_steps, anchor)
+        if location is None:
+            continue  # missing anchors are reported by validate_edits
+        parent_list, idx = location
+        step = parent_list[idx]
+        conflicting = anchors & _descendant_ids(step)
+        for child_anchor in sorted(conflicting):
+            errors.append(
+                f"Anchor conflict: '{anchor}' is an ancestor of '{child_anchor}'. "
+                "Targeting both anchors in the same overlay set produces "
+                "order-dependent results; restructure edits to avoid nesting."
+            )
+    return errors
+
+
 def _init_sources_recursively(
     steps: list[dict[str, Any]], sources: dict[str, str]
 ) -> None:
@@ -252,6 +295,14 @@ def merge_steps(
         for edit in layer.overlay.edits:
             edits_by_anchor.setdefault(edit.anchor, []).append((layer, edit))
 
+    # Reject edits that target anchors with a parent/descendant relationship —
+    # processing such pairs independently produces order-dependent results.
+    anchor_conflicts = _check_anchor_conflicts(set(edits_by_anchor.keys()), base_steps)
+    if anchor_conflicts:
+        raise ValueError(
+            "Overlay anchor conflict(s) detected:\n  - " + "\n  - ".join(anchor_conflicts)
+        )
+
     for anchor, edits in edits_by_anchor.items():
         # Highest-priority edit is last because *overlays* is already sorted.
         _, winning_edit = edits[-1]

tests/workflows/test_overlay_merge.py

@@ -579,3 +579,131 @@ def test_remove_requires_no_step(self):
         edits = [OverlayEdit("remove", "a", _step("extra"))]
         errors = validate_edits(edits, {"a"})
         assert len(errors) > 0
+
+
+class TestMergeStepsAncestorConflicts:
+    """merge_steps raises when two targeted anchors are in a parent/descendant relationship."""
+
+    def _if_step(self, parent_id: str, child_id: str) -> dict[str, Any]:
+        return {
+            "id": parent_id,
+            "type": "if",
+            "condition": "true",
+            "then": [_step(child_id)],
+        }
+
+    def test_remove_parent_and_insert_after_child_raises(self):
+        """Removing a parent while inserting after its nested child is an anchor conflict."""
+        parent_id = "if-step"
+        child_id = "then-child"
+        base = [self._if_step(parent_id, child_id)]
+        overlay = Overlay(
+            id="ov",
+            extends="wf",
+            priority=10,
+            edits=[
+                OverlayEdit("remove", parent_id),
+                OverlayEdit("insert_after", child_id, _step("new-step")),
+            ],
+        )
+        with pytest.raises(ValueError, match="ancestor"):
+            merge_steps(base, [_layer(overlay, "project:ov")])
+
+    def test_replace_parent_and_remove_child_raises(self):
+        """Replacing a parent while also removing a nested child is an anchor conflict."""
+        parent_id = "if-step"
+        child_id = "then-child"
+        base = [self._if_step(parent_id, child_id)]
+        overlay = Overlay(
+            id="ov",
+            extends="wf",
+            priority=10,
+            edits=[
+                OverlayEdit("replace", parent_id, _step("new-parent")),
+                OverlayEdit("remove", child_id),
+            ],
+        )
+        with pytest.raises(ValueError, match="ancestor"):
+            merge_steps(base, [_layer(overlay, "project:ov")])
+
+    def test_conflict_across_multiple_overlays_raises(self):
+        """Conflict is detected even when conflicting anchors come from different overlays."""
+        parent_id = "if-step"
+        child_id = "then-child"
+        base = [self._if_step(parent_id, child_id)]
+        overlay_a = Overlay(
+            id="ov-a",
+            extends="wf",
+            priority=5,
+            edits=[OverlayEdit("remove", parent_id)],
+        )
+        overlay_b = Overlay(
+            id="ov-b",
+            extends="wf",
+            priority=10,
+            edits=[OverlayEdit("insert_after", child_id, _step("new-step"))],
+        )
+        with pytest.raises(ValueError, match="ancestor"):
+            merge_steps(
+                base,
+                [_layer(overlay_a, "project:ov-a"), _layer(overlay_b, "project:ov-b")],
+            )
+
+    def test_sibling_anchors_not_conflicting(self):
+        """Anchors in sibling branches (not ancestor/descendant) are allowed."""
+        base = [
+            {
+                "id": "if-step",
+                "type": "if",
+                "condition": "true",
+                "then": [_step("then-child")],
+                "else": [_step("else-child")],
+            }
+        ]
+        overlay = Overlay(
+            id="ov",
+            extends="wf",
+            priority=10,
+            edits=[
+                OverlayEdit("insert_after", "then-child", _step("after-then")),
+                OverlayEdit("insert_after", "else-child", _step("after-else")),
+            ],
+        )
+        # Should not raise — the two anchors are siblings, not ancestor/descendant.
+        steps, _ = merge_steps(base, [_layer(overlay, "project:ov")])
+        step_ids = [s.get("id") for s in steps[0]["then"]] + [s.get("id") for s in steps[0]["else"]]
+        assert "after-then" in step_ids
+        assert "after-else" in step_ids
+
+    def test_single_anchor_not_conflicting(self):
+        """A single anchor is never in conflict with itself."""
+        parent_id = "if-step"
+        child_id = "then-child"
+        base = [self._if_step(parent_id, child_id)]
+        overlay = Overlay(
+            id="ov",
+            extends="wf",
+            priority=10,
+            edits=[OverlayEdit("remove", parent_id)],
+        )
+        steps, _ = merge_steps(base, [_layer(overlay, "project:ov")])
+        assert steps == []
+
+    def test_child_not_targeted_no_conflict(self):
+        """Targeting a parent alone (child not in any edit) is allowed."""
+        parent_id = "if-step"
+        child_id = "then-child"
+        base = [self._if_step(parent_id, child_id), _step("other")]
+        overlay = Overlay(
+            id="ov",
+            extends="wf",
+            priority=10,
+            edits=[
+                OverlayEdit("remove", parent_id),
+                OverlayEdit("insert_after", "other", _step("new-step")),
+            ],
+        )
+        # "other" is not inside "if-step", so no ancestor conflict.
+        steps, _ = merge_steps(base, [_layer(overlay, "project:ov")])
+        assert [s["id"] for s in steps] == ["other", "new-step"]
+