From 51bd59731aece8c8c43dc6b8fd9c94a5fa05bdfe Mon Sep 17 00:00:00 2001 From: Andre Brait Date: Sun, 11 Oct 2026 10:26:36 +0000 Subject: [PATCH] docs(always-on): say large graph.json diffs in pull requests are expected A committed graphify-out/graph.json is rewritten whole on every build, so its pull-request diffs are large by design. Assistants reviewing such PRs flagged them as churn and proposed skipping the rebuild or its hooks. The Claude, AGENTS.md and Gemini blocks now say the diff is expected. (cherry picked from commit e6cf17c17131f1293c1a0657634a7f6d5e9427a9) --- graphify/always_on/agents-md.md | 1 + graphify/always_on/claude-md.md | 1 + graphify/always_on/gemini-md.md | 1 + tests/test_skillgen.py | 8 +++++--- .../expected/graphify__always_on__agents-md.md | 1 + .../expected/graphify__always_on__claude-md.md | 1 + .../expected/graphify__always_on__gemini-md.md | 1 + tools/skillgen/fragments/always-on/agents-md.md | 1 + tools/skillgen/fragments/always-on/claude-md.md | 1 + tools/skillgen/fragments/always-on/gemini-md.md | 1 + tools/skillgen/gen.py | 13 +++++++++++++ 11 files changed, 27 insertions(+), 3 deletions(-) diff --git a/graphify/always_on/agents-md.md b/graphify/always_on/agents-md.md index 6511cd1dd..144d578f2 100644 --- a/graphify/always_on/agents-md.md +++ b/graphify/always_on/agents-md.md @@ -10,3 +10,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/graphify/always_on/claude-md.md b/graphify/always_on/claude-md.md index 417efeb27..00a8858fd 100644 --- a/graphify/always_on/claude-md.md +++ b/graphify/always_on/claude-md.md @@ -7,3 +7,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/graphify/always_on/gemini-md.md b/graphify/always_on/gemini-md.md index 417efeb27..00a8858fd 100644 --- a/graphify/always_on/gemini-md.md +++ b/graphify/always_on/gemini-md.md @@ -7,3 +7,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/tests/test_skillgen.py b/tests/test_skillgen.py index 7284b397e..0a4c62c15 100644 --- a/tests/test_skillgen.py +++ b/tests/test_skillgen.py @@ -750,15 +750,17 @@ 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. + # The registry holds exactly the #1530 substitution plus the graph-diff rule. assert gen.ALWAYS_ON_SANCTIONED_EDITS["_AGENTS_MD_SECTION"] == ( (old_instruction, new_instruction), + gen._GRAPH_DIFF_EDIT, ) 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 + old_rule, new_rule = gen._GRAPH_DIFF_EDIT + assert baseline_agents.replace(old_instruction, new_instruction).replace(old_rule, new_rule) == rendered_agents assert "`skill` tool" not in rendered_agents assert 'skill: "graphify"' not in rendered_agents diff --git a/tools/skillgen/expected/graphify__always_on__agents-md.md b/tools/skillgen/expected/graphify__always_on__agents-md.md index 6511cd1dd..144d578f2 100644 --- a/tools/skillgen/expected/graphify__always_on__agents-md.md +++ b/tools/skillgen/expected/graphify__always_on__agents-md.md @@ -10,3 +10,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/tools/skillgen/expected/graphify__always_on__claude-md.md b/tools/skillgen/expected/graphify__always_on__claude-md.md index 417efeb27..00a8858fd 100644 --- a/tools/skillgen/expected/graphify__always_on__claude-md.md +++ b/tools/skillgen/expected/graphify__always_on__claude-md.md @@ -7,3 +7,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/tools/skillgen/expected/graphify__always_on__gemini-md.md b/tools/skillgen/expected/graphify__always_on__gemini-md.md index 417efeb27..00a8858fd 100644 --- a/tools/skillgen/expected/graphify__always_on__gemini-md.md +++ b/tools/skillgen/expected/graphify__always_on__gemini-md.md @@ -7,3 +7,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/tools/skillgen/fragments/always-on/agents-md.md b/tools/skillgen/fragments/always-on/agents-md.md index 6511cd1dd..144d578f2 100644 --- a/tools/skillgen/fragments/always-on/agents-md.md +++ b/tools/skillgen/fragments/always-on/agents-md.md @@ -10,3 +10,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/tools/skillgen/fragments/always-on/claude-md.md b/tools/skillgen/fragments/always-on/claude-md.md index 417efeb27..00a8858fd 100644 --- a/tools/skillgen/fragments/always-on/claude-md.md +++ b/tools/skillgen/fragments/always-on/claude-md.md @@ -7,3 +7,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/tools/skillgen/fragments/always-on/gemini-md.md b/tools/skillgen/fragments/always-on/gemini-md.md index 417efeb27..00a8858fd 100644 --- a/tools/skillgen/fragments/always-on/gemini-md.md +++ b/tools/skillgen/fragments/always-on/gemini-md.md @@ -7,3 +7,4 @@ Rules: - 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). +- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks. diff --git a/tools/skillgen/gen.py b/tools/skillgen/gen.py index d3fa13459..cb3695d53 100644 --- a/tools/skillgen/gen.py +++ b/tools/skillgen/gen.py @@ -99,6 +99,16 @@ ALWAYS_ON_BLOCKS = { # to the baseline before the byte-for-byte comparison; anything not covered here # still fails the guard, so unrelated drift cannot slip through. Each entry is a # one-time, audited edit to the otherwise-immutable v8 baseline. +_UPDATE_RULE = "run `graphify update .` to keep the graph current (AST-only, no API cost)." +# A committed graph.json is rewritten whole on every build, so reviewers kept +# flagging its large PR diffs as churn and proposing to skip the rebuild hooks. +_GRAPH_DIFF_EDIT = ( + _UPDATE_RULE, + _UPDATE_RULE + + "\n- A committed graphify-out/graph.json is rewritten whole on every build, so a large diff" + " to it in a pull request is expected. Do not flag it as churn or suggest skipping the" + " graph rebuild or its hooks.", +) ALWAYS_ON_SANCTIONED_EDITS: dict[str, tuple[tuple[str, str], ...]] = { # #1530: install guidance must stay host-generic — do not tell agents to # invoke a literal `skill` tool with `skill: "graphify"`, which is @@ -110,7 +120,10 @@ ALWAYS_ON_SANCTIONED_EDITS: dict[str, tuple[tuple[str, str], ...]] = { "When the user types `/graphify`, use the installed graphify skill or instructions " "before doing anything else.", ), + _GRAPH_DIFF_EDIT, ), + "_CLAUDE_MD_SECTION": (_GRAPH_DIFF_EDIT,), + "_GEMINI_MD_SECTION": (_GRAPH_DIFF_EDIT,), } # The full six-value file_type enum (Decision A). Every rendered platform — split