Feature request: let the git-hook/watch rebuild honor a persisted clustering config (exclude-hubs)

[jerp86]

Context

--exclude-hubs (shipped in v0.8.11 via #919) works great as a cluster-only flag. On our TS/React graph (2091 nodes), cluster-only --exclude-hubs 99.5 dramatically improves community↔subsystem alignment: core/style/ consolidates from 10 communities (53% top-share) to 4 (85%), core/layout/ top-share 15%→43%, core/dsl/ 17%→43% — reproducing the pattern reported in #919.

Problem

The flag cannot be adopted as the graph's official clustering when the post-commit/post-checkout hooks are installed: the hook rebuild path (watch.py) re-clusters with defaults and has no way to pick the setting up (no flag, no env var — checked v0.9.12: cli.py knows exclude_hubs, watch.py doesn't). So an exclude-hubs clustering is overwritten on the next commit, and each flip-flop renumbers communities and invalidates labels (.graphify_labels.json is keyed by community number).

Proposal

Persist clustering parameters chosen at cluster-only/build time (e.g. an exclude_hubs_percentile field in manifest.json or a small graphify-out/.graphify_cluster.json) and have the watch/hook rebuild reuse them, so hooks preserve rather than revert the operator's clustering choice. An env var (e.g. GRAPHIFY_EXCLUDE_HUBS) read by watch.py would also work as a minimal version.

Environment

graphify 0.9.12, macOS, hooks installed via graphify hook install.

Workaround we're using meanwhile: keep the official graph on default clustering and run exclude-hubs analyses on a copy (cluster-only --graph <copy> — the #1747 fix in 0.9.12 makes this clean, outputs land beside the copy).

[jerp86]

Additional evidence: even trivial incremental changes trigger full recluster instability

Follow-up from our side after filing this. We observed the flip-flop/instability problem play out again, but from an even smaller trigger than deliberately setting --exclude-hubs: two ordinary commits that only added a single new (~4-5 node) document file to the corpus, unrelated to the actual application code.

Each commit's post-commit hook ran the ordinary incremental watch.py rebuild (no manual clustering flags involved at all), and each time the community structure shifted:

• Commit 1: total community count unchanged (107→107), but community 107 (a real, stable 4-node community, "Moldura do Grupo de Problemas") disappeared and a brand-new community 92 appeared in its place — a straight renumbering, not a content change.
• Commit 2: community count dropped (107→106) — community 98 ("Passagem de Tempo", also a stable 4-node community) was silently merged away with no replacement ID.

Both times, graph.json and graph.html diffed ~90k lines even though only a handful of nodes/edges actually changed — consistent with a full recluster-from-scratch rather than an incremental community assignment for just the new nodes.

This reinforces the FR's core ask (persist clustering config across watch/hook reruns) but also broadens the stakes a bit: it's not only that a deliberately-set --exclude-hubs gets silently reverted — any topology change at all, however small and unrelated to the communities in question, can renumber or merge existing communities and invalidate their saved labels. A config-persistence fix would presumably need to be paired with (or benefit from) more stable community IDs/labels across incremental reruns, not just carrying the --exclude-hubs value forward.

Happy to share the two graph.json/.graphify_labels.json diffs if useful for reproduction.