From 8b41440ad1edaf0159311bb6768c8785114bb247 Mon Sep 17 00:00:00 2001
From: saxster <119735920+saxster@users.noreply.github.com>
Date: Sat, 2 May 2026 18:44:49 +0530
Subject: [PATCH] =?UTF-8?q?docs(skill):=20clarify=20--update=20prune=20mes?=
 =?UTF-8?q?sage=20=E2=80=94=20split=20drift=20vs=20no-drift=20(#544)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #539.

The current prune message in the --update flow is ambiguous:

    Pruned 0 ghost nodes from 13 deleted file(s)

A reader can't tell whether (a) 13 files deleted, 0 of them had nodes
worth pruning (benign — graph already clean), or (b) 13 ghost nodes
still exist and only 0 got pruned (bug). The denominator is opaque.

Split into two messages so the semantics are explicit:

- Drift case: "Pruned N ghost node(s) from M deleted file(s) — drift
  detected and corrected."
- No-drift case: "M file(s) deleted since last run, but no ghost
  nodes were present in the graph — no drift."

Applied to both skill.md and skill-copilot.md (the only two skill
files carrying the --update merge step verbatim).
---
 graphify/skill-copilot.md | 5 ++++-
 graphify/skill.md         | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/graphify/skill-copilot.md b/graphify/skill-copilot.md
index 397669ae1..62992f977 100644
--- a/graphify/skill-copilot.md
+++ b/graphify/skill-copilot.md
@@ -819,7 +819,10 @@ deleted = set(incremental.get('deleted_files', []))
 if deleted:
     to_remove = [n for n, d in G_existing.nodes(data=True) if d.get('source_file') in deleted]
     G_existing.remove_nodes_from(to_remove)
-    print(f'Pruned {len(to_remove)} ghost nodes from {len(deleted)} deleted file(s)')
+    if to_remove:
+        print(f'Pruned {len(to_remove)} ghost node(s) from {len(deleted)} deleted file(s) — drift detected and corrected.')
+    else:
+        print(f'{len(deleted)} file(s) deleted since last run, but no ghost nodes were present in the graph — no drift.')
 
 # Merge: new nodes/edges into existing graph
 G_existing.update(G_new)
diff --git a/graphify/skill.md b/graphify/skill.md
index dde2fc386..f04d71ff6 100644
--- a/graphify/skill.md
+++ b/graphify/skill.md
@@ -923,7 +923,10 @@ deleted = set(incremental.get('deleted_files', []))
 if deleted:
     to_remove = [n for n, d in G_existing.nodes(data=True) if d.get('source_file') in deleted]
     G_existing.remove_nodes_from(to_remove)
-    print(f'Pruned {len(to_remove)} ghost nodes from {len(deleted)} deleted file(s)')
+    if to_remove:
+        print(f'Pruned {len(to_remove)} ghost node(s) from {len(deleted)} deleted file(s) — drift detected and corrected.')
+    else:
+        print(f'{len(deleted)} file(s) deleted since last run, but no ghost nodes were present in the graph — no drift.')
 
 # Merge: new nodes/edges into existing graph
 G_existing.update(G_new)