From e6cf17c17131f1293c1a0657634a7f6d5e9427a9 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. --- 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 6511cd1dd5..144d578f22 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 417efeb27e..00a8858fd8 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 417efeb27e..00a8858fd8 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 ab6f94474c..c1f36feb58 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 6511cd1dd5..144d578f22 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 417efeb27e..00a8858fd8 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 417efeb27e..00a8858fd8 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 6511cd1dd5..144d578f22 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 417efeb27e..00a8858fd8 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 417efeb27e..00a8858fd8 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 d3fa134593..cb3695d53f 100644 --- a/tools/skillgen/gen.py +++ b/tools/skillgen/gen.py @@ -99,6 +99,16 @@ def _v8_baseline_ref(platform_key: str) -> str: # 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 @@ def _v8_baseline_ref(platform_key: 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