fix(skill): name graphify affected in every always-on block (#3177)

graphify/always_on/agents-md.md

@@ -6,6 +6,7 @@ When the user types `/graphify`, use the installed graphify skill or instruction
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.

graphify/always_on/antigravity-rules.md

@@ -9,6 +9,7 @@ This project has a graphify knowledge graph at graphify-out/.
 
 Rules:
 - For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (CLI) or `query_graph` (MCP). Use `graphify path "<A>" "<B>"` / `shortest_path` for relationships and `graphify explain "<concept>"` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

graphify/always_on/claude-md.md

@@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
 - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

graphify/always_on/gemini-md.md

@@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
 - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

graphify/always_on/kiro-steering.md

@@ -2,4 +2,4 @@
 inclusion: always
 ---
 
-graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.
+graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. Before modifying a symbol, run `graphify affected "<symbol-or-file>"` for its blast radius (reverse dependencies).

graphify/always_on/vscode-instructions.md

@@ -4,7 +4,8 @@ For any question about this repo's architecture, structure, components, or how t
 code, your first action should be `graphify query "<question>"` when `graphify-out/graph.json`
 exists. Use `graphify path "<A>" "<B>"` for relationship questions and `graphify explain "<concept>"`
 for focused-concept questions. These return a scoped subgraph, usually much smaller than the full
-report or raw grep output.
+report or raw grep output. Before modifying a symbol or assessing a change's impact, run
+`graphify affected "<symbol-or-file>"` for its blast radius (reverse dependencies).
 
 Triggers: "how do I…", "where is…", "what does … do", "add/modify a <component>",
 "explain the architecture", or anything that depends on how files or classes relate.

tests/test_always_on_affected.py

@@ -0,0 +1,32 @@
+"""Every always-on block names `graphify affected` (#3177).
+
+The always-on text is what reaches the agent on every session — and none of
+the six templates mentioned `affected`, so in 262 measured sessions it was
+called zero times while the verbs the block does name (query/explain) were
+used daily. The block now names the blast-radius verb beside them.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+ALWAYS_ON = Path(__file__).resolve().parent.parent / "graphify" / "always_on"
+BLOCKS = sorted(p.name for p in ALWAYS_ON.glob("*.md"))
+
+
+def test_all_six_blocks_exist():
+    assert len(BLOCKS) == 6, BLOCKS
+
+
+@pytest.mark.parametrize("name", BLOCKS)
+def test_every_block_names_the_blast_radius_verb(name):
+    body = (ALWAYS_ON / name).read_text(encoding="utf-8")
+    assert "graphify affected" in body, f"{name} never names affected"
+    assert "blast radius" in body
+
+
+@pytest.mark.parametrize("name", BLOCKS)
+def test_the_existing_verbs_are_still_named(name):
+    body = (ALWAYS_ON / name).read_text(encoding="utf-8")
+    assert "graphify query" in body

tests/test_skillgen.py

@@ -750,15 +750,32 @@ def test_always_on_roundtrip_is_byte_faithful():
         "When the user types `/graphify`, use the installed graphify skill or instructions "
         "before doing anything else."
     )
-    # The sanctioned-edit registry holds exactly this single old->new substitution.
-    assert gen.ALWAYS_ON_SANCTIONED_EDITS["_AGENTS_MD_SECTION"] == (
-        (old_instruction, new_instruction),
+    # The sanctioned-edit registry still opens with the #1530 substitution...
+    assert gen.ALWAYS_ON_SANCTIONED_EDITS["_AGENTS_MD_SECTION"][0] == (
+        old_instruction, new_instruction,
     )
+    # ...and every constant now carries exactly one #3177 edit that adds the
+    # blast-radius verb without removing anything else (the new text embeds
+    # the old, so the substitution is purely additive).
+    for const_name in gen.ALWAYS_ON_BLOCKS.values():
+        pairs = gen.ALWAYS_ON_SANCTIONED_EDITS[const_name]
+        affected_pairs = [(o, n) for o, n in pairs if "graphify affected" in n]
+        assert len(affected_pairs) == 1, const_name
+        o, n = affected_pairs[0]
+        # Additive modulo line wrapping: the old text's words survive as the
+        # prefix of the new text's words.
+        assert n.split()[: len(o.split())] == o.split(), (
+            f"{const_name}: the #3177 edit must be additive"
+        )
     baseline_agents = gen._always_on_constants(gen.ALWAYS_ON_BASELINE_REF)["_AGENTS_MD_SECTION"]
-    # The ONLY divergence from the frozen baseline is the sanctioned sentence —
+    # The ONLY divergences from the frozen baseline are the sanctioned edits —
     # any other byte drift would have surfaced as a problem above.
     assert old_instruction in baseline_agents
-    assert baseline_agents.replace(old_instruction, new_instruction) == rendered_agents
+    expected_agents = baseline_agents
+    for o, n in gen.ALWAYS_ON_SANCTIONED_EDITS["_AGENTS_MD_SECTION"]:
+        assert o in expected_agents
+        expected_agents = expected_agents.replace(o, n)
+    assert expected_agents == rendered_agents
     assert "`skill` tool" not in rendered_agents
     assert 'skill: "graphify"' not in rendered_agents
 

tools/skillgen/expected/graphify__always_on__agents-md.md

@@ -6,6 +6,7 @@ When the user types `/graphify`, use the installed graphify skill or instruction
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.

tools/skillgen/expected/graphify__always_on__antigravity-rules.md

@@ -9,6 +9,7 @@ This project has a graphify knowledge graph at graphify-out/.
 
 Rules:
 - For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (CLI) or `query_graph` (MCP). Use `graphify path "<A>" "<B>"` / `shortest_path` for relationships and `graphify explain "<concept>"` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

tools/skillgen/expected/graphify__always_on__claude-md.md

@@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
 - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

tools/skillgen/expected/graphify__always_on__gemini-md.md

@@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
 - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

tools/skillgen/expected/graphify__always_on__kiro-steering.md

@@ -2,4 +2,4 @@
 inclusion: always
 ---
 
-graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.
+graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. Before modifying a symbol, run `graphify affected "<symbol-or-file>"` for its blast radius (reverse dependencies).

tools/skillgen/expected/graphify__always_on__vscode-instructions.md

@@ -4,7 +4,8 @@ For any question about this repo's architecture, structure, components, or how t
 code, your first action should be `graphify query "<question>"` when `graphify-out/graph.json`
 exists. Use `graphify path "<A>" "<B>"` for relationship questions and `graphify explain "<concept>"`
 for focused-concept questions. These return a scoped subgraph, usually much smaller than the full
-report or raw grep output.
+report or raw grep output. Before modifying a symbol or assessing a change's impact, run
+`graphify affected "<symbol-or-file>"` for its blast radius (reverse dependencies).
 
 Triggers: "how do I…", "where is…", "what does … do", "add/modify a <component>",
 "explain the architecture", or anything that depends on how files or classes relate.

tools/skillgen/fragments/always-on/agents-md.md

@@ -6,6 +6,7 @@ When the user types `/graphify`, use the installed graphify skill or instruction
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.

tools/skillgen/fragments/always-on/antigravity-rules.md

@@ -9,6 +9,7 @@ This project has a graphify knowledge graph at graphify-out/.
 
 Rules:
 - For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (CLI) or `query_graph` (MCP). Use `graphify path "<A>" "<B>"` / `shortest_path` for relationships and `graphify explain "<concept>"` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

tools/skillgen/fragments/always-on/claude-md.md

@@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
 - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

tools/skillgen/fragments/always-on/gemini-md.md

@@ -4,6 +4,7 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Before modifying a symbol or judging a change's impact, run `graphify affected "<symbol-or-file>"` — the blast radius (reverse dependencies), which query/path/explain do not show.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
 - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

tools/skillgen/fragments/always-on/kiro-steering.md

@@ -2,4 +2,4 @@
 inclusion: always
 ---
 
-graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.
+graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context. Before modifying a symbol, run `graphify affected "<symbol-or-file>"` for its blast radius (reverse dependencies).