fix(kg): rebuild the knowledge graph when the builder changes, not just the graph (#1592)

* fix(kg): rebuild the knowledge graph when the builder changes, not just the graph

`compute_kg_fingerprint` measures the input graph — node count, edge count,
community count, first 100 community keys — and `should_skip_kg_rebuild` keeps
the stored artifact whenever those four hold still. They hold still when the
*builder* changes, and this release changed it twice.

`_EDGE_TYPE_MAP` gained six types (framework, the three dynamic_* kinds, reads,
method_implements) and the export drops every unmapped type outright, so the
knowledge graph now carries edge classes it used to discard. `_curate_entry_points`
also re-ranks `project.entry_points`, which reaches get_overview, the C4
architecture view and CLAUDE.md through `entry_points_json`. Neither moves a node
or an edge count, so an existing store would serve the old artifact until some
unrelated commit happened to shift one.

KG_BUILDER_VERSION is folded into the fingerprint: one bump is one rebuild per
store, on the next ordinary `repowise update`. That rebuild is the deterministic
skeleton and curation passes over a graph the run already holds — no model, no
re-index, nothing for the user to do. Not a loop either: the new value is stored
as the artifact's fingerprint, so the following run matches and skips.

* fix(kg): say what the rebuild actually costs, and pin the version as a literal

Adversarial review of the previous commit found three claims in it that the
code does not support.

"On the next ordinary `repowise update`" is not true for a repo with no new
commits: that run returns NOOP (command.py:908) before the refresh is reached,
and the renderer-staleness gate beside it fingerprints only the file-page and
spotlight templates, so a builder bump does not retire the shortcut. A quiet
repo stays on its old artifact until something changes. That is the right trade
— the alternative is every idle repo in the world re-curating on a version bump
— but the docstring stated it as a guarantee.

"No model" is only true off the docs path. A non-None refresh result feeds
enrich_knowledge_graph (command.py:1770), one LLM call per five layers, and the
comment above that call still claimed an unchanged KG never pays it. Both now
say what happens and why it is worth paying: the layers moved, so the names the
carry-forward restored were written against the old ones.

The stability test asserted only that the constant is a non-empty str, which a
value derived from the module's own bytes — the exact failure its docstring
named — would have passed. Replaced with the literal, so bumping it is a line
somebody edits and a reviewer sees.

Not applied from the review: stamping the fingerprint into state when the disk
export fails. should_skip_kg_rebuild also requires kg_path.exists(), so a failed
export rebuilds on the next run regardless of the stored value; stamping it
would instead assert the artifact matches the current builder when the write
that would have made that true is the one that failed.

Verified end to end on a fresh microdot index: a comment-only commit at the same
version does not rebuild (fingerprint held at 2cf47159), the same commit with the
version bumped does (0630f7fd), and the commit after that does not.

Author: swati510

packages/cli/src/repowise/cli/commands/update_cmd/command.py

@@ -1764,9 +1764,13 @@ async def _generate_with_checkpoint() -> list:
     flush_cost_tracker(cost_tracker)
 
     # LLM re-enrichment of the refreshed KG (layer naming + summary backfill
-    # from this run's regenerated pages), mirroring the init pipeline. Only
-    # runs when the graph shape changed — carry-forward already preserved the
-    # prior names, so an unchanged KG never pays an enrichment call.
+    # from this run's regenerated pages), mirroring the init pipeline. Runs
+    # whenever the refresh returned a result, which is the graph shape moving
+    # *or* KG_BUILDER_VERSION being bumped by a release — the second is a graph
+    # that did not change, and it still pays here. That is deliberate and it is
+    # the one cost of the version bump: a wider edge map or a new entry-point
+    # ranking changes the layers, and layer names the carry-forward restored
+    # were written against the old ones.
     if knowledge_graph_result is not None:
         try:
             from repowise.core.generation.knowledge_graph import enrich_knowledge_graph

packages/core/src/repowise/core/analysis/knowledge_graph.py

@@ -205,6 +205,16 @@ def _slugify(text: str) -> str:
 # Edge type mapping
 # ---------------------------------------------------------------------------
 
+# Bump when the builder or the curation pass changes what it emits from an
+# unchanged graph — a wider `_EDGE_TYPE_MAP`, a different entry-point ranking,
+# a new node field. Folded into `compute_kg_fingerprint`, which otherwise only
+# measures the input graph and would let an existing store serve the old
+# artifact indefinitely. See that function for why one bump is one rebuild.
+#
+# "2": `_EDGE_TYPE_MAP` gained six types and `_curate_entry_points` changed its
+# ranking, neither of which moves a node or edge count.
+KG_BUILDER_VERSION = "2"
+
 # An unmapped type is dropped from the export entirely (see the
 # `if not kg_type: continue` below), which is silent. Six real types used to be
 # missing — framework, the three dynamic_* kinds, reads and method_implements —
@@ -410,10 +420,41 @@ def build_knowledge_graph_skeleton(
 
 
 def compute_kg_fingerprint(graph_builder: Any) -> str:
-    """Compute a fingerprint from the graph state for incremental skip logic."""
+    """Compute a fingerprint from the graph state for incremental skip logic.
+
+    The four graph measures describe the *input* graph. They cannot see a
+    change in how this module turns that graph into an export, and the export
+    is not total: :data:`_EDGE_TYPE_MAP` drops every unmapped edge type. So
+    widening that map — six types in 0.43.0 — changes what the knowledge graph
+    contains while all four measures hold still, and the stored artifact would
+    keep the narrower edge set until some unrelated commit happened to move a
+    node or edge count. Same for the ordering the curation pass applies to
+    ``project.entry_points``, which every orientation surface reads.
+
+    :data:`KG_BUILDER_VERSION` closes that: bump it in the same commit as a
+    change to what the builder or the curation pass emits, and every existing
+    store rebuilds its knowledge graph once, on its next ``repowise update``
+    that has work to do. Two limits on that sentence, both deliberate:
+
+    * An update with nothing to do returns ``NOOP`` before the refresh is
+      reached, so a repo with no new commits stays on its old artifact until
+      something changes. That is the right trade — the alternative is making
+      every quiet repo in the world re-curate on a version bump — but it does
+      mean this is not a hard guarantee of "everyone, once".
+    * The rebuild itself is deterministic and model-free (skeleton plus
+      curation over a graph the run already holds, betweenness served from its
+      disk cache). On a **docs** update the non-``None`` result then also
+      triggers one KG layer-enrichment LLM call per five layers, which is real
+      spend the caller pays for a graph whose shape did not change. Index-only
+      and keyless runs never reach it.
+
+    One rebuild and not a loop: the new value is stored as the artifact's
+    fingerprint, so the next run matches and skips.
+    """
     g = graph_builder.graph()
     cd = graph_builder.community_detection()
     parts = [
+        KG_BUILDER_VERSION,
         str(g.number_of_nodes()),
         str(g.number_of_edges()),
         str(len(set(cd.values()))),

tests/unit/analysis/test_kg_skip_logic.py

@@ -7,6 +7,7 @@
 
 import pytest
 
+from repowise.core.analysis import knowledge_graph
 from repowise.core.analysis.knowledge_graph import (
     _KG_SCHEMA_VERSION,
     KnowledgeGraphResult,
@@ -181,6 +182,36 @@ def test_different_communities_different_fingerprint(self):
         )
         assert compute_kg_fingerprint(gb1) != compute_kg_fingerprint(gb2)
 
+    def test_builder_version_changes_the_fingerprint(self, monkeypatch):
+        """The one input that is not a measurement of the graph.
+
+        Every other test here varies the graph and expects the fingerprint to
+        follow. This is the opposite case, and the one the skip logic could not
+        express before: the graph is identical and the *builder* changed, which
+        is what a release does when it widens ``_EDGE_TYPE_MAP`` or re-ranks
+        entry points. Without this fold an existing store keeps the artifact a
+        narrower builder wrote, for as long as its node and edge counts happen
+        to hold still.
+        """
+        gb = self._make_graph_builder(["a.py", "b.py"], [("a.py", "b.py")], {"a.py": 0, "b.py": 0})
+        before = compute_kg_fingerprint(gb)
+
+        monkeypatch.setattr(knowledge_graph, "KG_BUILDER_VERSION", "test-next")
+        assert compute_kg_fingerprint(gb) != before
+
+    def test_builder_version_is_a_hand_edited_literal(self):
+        """The bump is a decision, so it has to be visible in a diff.
+
+        Deliberately asserts the literal. The first cut of this test asserted
+        only ``isinstance(..., str)`` and non-emptiness, which a value derived
+        from the module's own bytes — the exact failure it claimed to guard —
+        would have passed unchanged. There is no way to check "somebody chose
+        this" other than to pin what they chose, and the cost is the honest
+        one: whoever bumps the constant updates this line and sees, in the
+        diff, that they are asking every existing store to re-curate.
+        """
+        assert knowledge_graph.KG_BUILDER_VERSION == "2"
+
 
 # ---------------------------------------------------------------------------
 # Skip logic integration (unit-level)