Incremental update: SKILL.md instructs writing batch-existing.json, but merge-batch-graphs.py silently drops it (all carried-over nodes lost)

[bnowain]

Summary

In the understand skill's incremental update path (v2.7.5), SKILL.md Phase 2 instructs the orchestrator:

3. Write the pruned existing nodes/edges as batch-existing.json in the intermediate directory
4. Run the same merge script — it will combine batch-existing.json with the fresh batch-*.json files

But merge-batch-graphs.py only accepts filenames matching batch-(\d+)(?:-part-(\d+))?\.json — batch-existing.json doesn't match, so the entire carried-over graph is silently dropped (it does emit a stderr warning about unrecognized filenames, but the merge still succeeds and writes an assembled graph missing every unchanged file's nodes).

Observed impact

Running an incremental update on a ~500-file project with a 173-file diff: the assembled graph contained only the 170 re-analyzed files' nodes; all 709 carried-over nodes and 869 edges from unchanged files were excluded. Without a review step diffing against the prior graph, this ships a knowledge-graph.json that silently lost two-thirds of its nodes.

Workaround

Name the carry-over file batch-0.json instead — index 0 is never produced by compute-batches.mjs, so it merges cleanly with no collisions. Verified: all carried-over nodes present after the rename.

Suggested fix (either)

1. Add batch-existing.json to the merge script's accepted filenames, or
2. Change SKILL.md's incremental instructions to use batch-0.json (documenting that index 0 is reserved for the carry-over).

Also worth promoting the existing stderr 'unrecognized filenames' warning to a hard error when the unrecognized file is non-empty — silent-ish data loss in a merge is the worst failure shape.

Version: 2.7.5 (Claude Code plugin install).