fix: raise NodeTypeError on scalar traversal, remove broken spec reference

Author: nathanjmcdougall

doc/specs/2026-05-22-deep-merge-design.md

@@ -1,8 +1,7 @@
 # Design: Deep Merge (`merge()`)
 
 **Date:** 2026-05-22  
-**Status:** Approved  
-**Relates to:** `doc/todo/feature-deep-merge.md`
+**Status:** Approved
 
 ## Summary
 

src/yamltrip/document.py

@@ -562,7 +562,12 @@ def merge(self, *keys: KeyPart, value: Any) -> Document:
         if normalized:
             route = _make_route(normalized)
             if not self._core_doc.query_exists(route):
-                return self.upsert(*normalized, value=value)
+                try:
+                    return self.upsert(*normalized, value=value)
+                except PatchError as e:
+                    if "unexpected node" in str(e):
+                        raise NodeTypeError(str(e)) from None
+                    raise
 
         # Get current value and diff
         try:

tests/test_merge.py

@@ -2,7 +2,7 @@
 
 from yamltrip import edit
 from yamltrip.document import Document
-from yamltrip.errors import PatchError
+from yamltrip.errors import NodeTypeError
 
 
 class TestMergeMapping:
@@ -108,7 +108,7 @@ def test_editor_merge(self, tmp_path):
 
 class TestMergeErrors:
     def test_merge_through_scalar_raises(self):
-        """Merging through a scalar path raises PatchError."""
+        """Merging through a scalar path raises NodeTypeError."""
         doc = Document("a:\n  b: 1\n")
-        with pytest.raises(PatchError):
+        with pytest.raises(NodeTypeError):
             doc.merge("a", "b", "c", value={"x": 1})