fix(skill): scope fresh semantic chunks before update merges

graphify/skill-agents.md

@@ -298,12 +298,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-amp.md

@@ -298,12 +298,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-claw.md

@@ -301,12 +301,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-codex.md

@@ -298,12 +298,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-copilot.md

@@ -301,12 +301,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-droid.md

@@ -298,12 +298,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-kilo.md

@@ -301,12 +301,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-kiro.md

@@ -301,12 +301,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-opencode.md

@@ -293,12 +293,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-pi.md

@@ -301,12 +301,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-trae.md

@@ -299,12 +299,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-vscode.md

@@ -297,12 +297,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill-windows.md

@@ -329,12 +329,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 @'
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding="utf-8").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding="utf-8"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skill.md

@@ -301,12 +301,19 @@ Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent cal
 $(cat graphify-out/.graphify_python) -c "
 import json, glob
 from pathlib import Path
+from graphify.cache import scope_semantic_result
 
 chunks = sorted(glob.glob('graphify-out/.graphify_chunk_*.json'))
+uncached = [line for line in Path('graphify-out/.graphify_uncached.txt').read_text(encoding=\"utf-8\").splitlines() if line]
 all_nodes, all_edges, all_hyperedges = [], [], []
 total_in, total_out = 0, 0
 for c in chunks:
     d = json.loads(Path(c).read_text(encoding=\"utf-8\"))
+    # source_file is a destructive replacement key during --update. Scope the
+    # fresh result BEFORE both cache writes and assembly with cached/AST nodes.
+    dropped_files, dropped_count = scope_semantic_result(d, root=Path('INPUT_PATH'), allowed_source_files=uncached)
+    if dropped_count:
+        print(f'[graphify scope] {c}: dropped {dropped_count} out-of-scope items from {sorted(dropped_files)}')
     all_nodes += d.get('nodes', [])
     all_edges += d.get('edges', [])
     all_hyperedges += d.get('hyperedges', [])

graphify/skills/agents/references/extraction-spec.md

@@ -65,6 +65,11 @@ Generate the extraction JSON matching this schema exactly:
 
 source_file RULE (every node, edge, and hyperedge): set source_file to the path of the originating file EXACTLY as it appears in FILE_LIST — verbatim and absolute. Do NOT shorten to a basename, do NOT re-relativize, do NOT strip any directory prefix, and do NOT change separators (the engine canonicalizes separators and relativizes against the build root downstream). Copy the FILE_LIST entry character-for-character. This keeps the full build and incremental --update on the same base, so build_merge's replace-on-re-extract matches the existing node instead of accumulating a duplicate.
 
+Never create a stub node for a file outside FILE_LIST. Express a reference to an
+external entity as an edge attributed to the originating FILE_LIST file, using
+the complete known target ID. A stem or ID prefix alone is never a valid target
+ID; do not guess one or invent a node to make a reference resolve.
+
 Then write the JSON to disk using the Write tool at this exact absolute path (no relative paths — Write resolves relative paths against an undefined cwd and the file will be silently lost):
 CHUNK_PATH
 ```

graphify/skills/agents/references/update.md

@@ -82,6 +82,12 @@ fi
 
 Then:
 
+For semantic changes, Step B3's collection commands apply the existing
+`scope_semantic_result` guard to fresh semantic chunks using the files dispatched
+from `.graphify_uncached.txt`, before caching or mixing them with cached/AST
+results. `source_file` is a destructive replacement key: an undispatched file's
+stub must never reach `build_merge` and replace that file's existing contribution.
+
 ```bash
 $(cat graphify-out/.graphify_python) -c "
 import json

graphify/skills/amp/references/extraction-spec.md

@@ -65,6 +65,11 @@ Generate the extraction JSON matching this schema exactly:
 
 source_file RULE (every node, edge, and hyperedge): set source_file to the path of the originating file EXACTLY as it appears in FILE_LIST — verbatim and absolute. Do NOT shorten to a basename, do NOT re-relativize, do NOT strip any directory prefix, and do NOT change separators (the engine canonicalizes separators and relativizes against the build root downstream). Copy the FILE_LIST entry character-for-character. This keeps the full build and incremental --update on the same base, so build_merge's replace-on-re-extract matches the existing node instead of accumulating a duplicate.
 
+Never create a stub node for a file outside FILE_LIST. Express a reference to an
+external entity as an edge attributed to the originating FILE_LIST file, using
+the complete known target ID. A stem or ID prefix alone is never a valid target
+ID; do not guess one or invent a node to make a reference resolve.
+
 Then write the JSON to disk using the Write tool at this exact absolute path (no relative paths — Write resolves relative paths against an undefined cwd and the file will be silently lost):
 CHUNK_PATH
 ```

graphify/skills/amp/references/update.md

@@ -82,6 +82,12 @@ fi
 
 Then:
 
+For semantic changes, Step B3's collection commands apply the existing
+`scope_semantic_result` guard to fresh semantic chunks using the files dispatched
+from `.graphify_uncached.txt`, before caching or mixing them with cached/AST
+results. `source_file` is a destructive replacement key: an undispatched file's
+stub must never reach `build_merge` and replace that file's existing contribution.
+
 ```bash
 $(cat graphify-out/.graphify_python) -c "
 import json

graphify/skills/claude/references/extraction-spec.md

@@ -65,6 +65,11 @@ Generate the extraction JSON matching this schema exactly:
 
 source_file RULE (every node, edge, and hyperedge): set source_file to the path of the originating file EXACTLY as it appears in FILE_LIST — verbatim and absolute. Do NOT shorten to a basename, do NOT re-relativize, do NOT strip any directory prefix, and do NOT change separators (the engine canonicalizes separators and relativizes against the build root downstream). Copy the FILE_LIST entry character-for-character. This keeps the full build and incremental --update on the same base, so build_merge's replace-on-re-extract matches the existing node instead of accumulating a duplicate.
 
+Never create a stub node for a file outside FILE_LIST. Express a reference to an
+external entity as an edge attributed to the originating FILE_LIST file, using
+the complete known target ID. A stem or ID prefix alone is never a valid target
+ID; do not guess one or invent a node to make a reference resolve.
+
 Then write the JSON to disk using the Write tool at this exact absolute path (no relative paths — Write resolves relative paths against an undefined cwd and the file will be silently lost):
 CHUNK_PATH
 ```