feat(gds skill): teach graph-analyst to drive complex topology searches onto Neo4j GDS instead of naive Cypher

[colombod]

Summary

Adds a new, lean, graph-analyst-only skill skills/context-intelligence-gds/SKILL.md (v1.2.0) that teaches the graph-analyst to drive complex topology searches onto Neo4j GDS / APOC instead of naive Cypher. The skill covers:

• Centrality: PageRank, betweenness, degree via GDS algorithms
• Topological/structural similarity: Sessions with similar tool-usage or event-signatures, via gds.nodeSimilarity, gds.knn (Jaccard/cosine), and fastRP embeddings
• Similar event-paths/trajectories: With or without a time dimension (set-similarity of tool sequences vs. transition-signature matching)
• Pathfinding: Finding intermediate agents/sessions in delegation chains
• Non-lineage projections: Derived co-occurrence edges (e.g., "which agents work together") from shared parentage when edges don't exist in storage

Also adds a ~10-line load pointer in agents/graph-analyst.md. The skill is picked up only by the graph-analyst via that agent's whole-skills/-dir mount; it does not leak into the root session (not added to the analysis behavior's skill list). The existing context-intelligence-graph-query skill is untouched (no pollution).

Motivation: Earlier live analysis of the graph-analyst's own query history found ~37% of its 467 queries were GDS/APOC-improvable, yet it reached for those tools only ~4% of the time. This skill closes that gap by making the agent recognize where GDS wins and teaching it when to reach for each algorithm.

Scope / guardrails

This change is agent + skill wiring only — no Python library changes, no tool changes, no hook/config changes. The seam crossed is skill discovery/loading (graph-analyst mounts skills/ dir).

Deliberately untouched:

• The write-side hook fan-out (fanout.py / _DestinationDispatcher / logging_handler.py) — this is read-side only
• The existing context-intelligence-graph-query skill — not modified
• Bundle structure / behaviors — feat/ doesn't alter core composition
• Top-level bundle validation (run scripts/validate-full.sh to confirm)

Verification

• Module tests pass — N/A (no module changes)
• Top-level tests pass — N/A (no code changes)
• ruff check + ruff format --check clean — N/A (no Python/markup changes in modules)
• pyright clean — N/A (no Python code)
• Full bundle validation PASS — scripts/validate-full.sh ✅ (the lone mode-advertising FALSE POSITIVE documented in AGENTS.md applies; no new errors)

Real evidence on seams (not mock-only)

Seam crossed: skill discovery/loading + agent wiring — the graph-analyst mounts skills/ dir and calls load_skill() at runtime.

Validation: Digital Twin Universe before/after A/B against the live private-home-server graph (read-only, ~3,388 sessions, real Neo4j data). Two arms ran 5 trials each:

Signal	baseline (main, no skill)	treatment (this branch)
Skill loaded	0/5 trials	5/5 trials
GDS similarity algo (gds.knn/nodeSimilarity/fastRP) on topology-similarity task	0/5 trials	5/5 trials
Correctly identified similar sessions (by tool-usage signature)	baseline degraded to APOC set-Jaccard, then client-side O(n²) brute force over ~2.67M pairs	GDS similarity pipeline (project → knn → read results)
Correctness (both arms produced same correct answer)	✅ Same top hubs, same session clusters	✅ Identical
Read-only integrity	0 data-mutating clauses	0 data-mutating clauses; transient GDS projections only

Caveat 1 (scenario design): An earlier scenario (depth-3 delegation trees) showed no effect because naive Cypher was legitimately correct there — the skill's value only appears on genuinely hard topology tasks. The topology-similarity scenario was the "hard" case that forces the algorithm choice.

Caveat 2 (run truncation): 9/10 DTU runs were truncated at 1500s exec cap under parallel LLM contention. The tool-choice signal is complete/decisive (the agent picked GDS for similarity, Cypher for simple counts), but final answer completeness was not measured end-to-end. The queries executed cleanly; the run timeout was orchestration overhead.

Caveat 3 (v1.2.0 additions not yet validated): The skill's v1.1.0 (lineage + topology searching) was A/B tested. The v1.2.0 additions — TF-IDF weighting to defeat glue-tool dominance, read-only vector-property KNN fallback, co-occurrence projection recipe, and GDS-vs-intent boundary — were lifted from a real graph exploration (context-intelligence-exploration-example.md) and added post-evaluation. They are not yet DTU-validated as a set; only their component patterns have been exercised individually.

Docs & diagrams

• bundle.dot / bundle.png — N/A (no bundle structure change; skill is discovered dynamically)
• README / SKILL docs — skills/context-intelligence-gds/SKILL.md is complete (v1.2.0, 285 lines including full scenario index and worked recipes)
• Agent file (agents/graph-analyst.md) — updated with 10-line load pointer and no other changes
• Convention files — no changes needed; this change neither surfaced a new lesson nor requires AGENTS.md/template updates

Notes / follow-ups

• Next iteration: Run a full end-to-end scenario combining v1.2.0 features (TF-IDF + vector KNN + co-occurrence projection in a multi-hop query) in a DTU to validate the lifted patterns together.
• Graph-analyst adoption: The skill is live for the graph-analyst immediately; adoption does not require any user action or configuration.
• Bundle size: The new skill adds ~285 lines and is scoped to graph-analyst only; no impact on bundles that don't load this agent.