fix(hook): nudge when wiki/ predates graph.json#2024
Conversation
wiki/ is only ever written by the explicit `export wiki` subcommand — never by `update` or watch — so it can silently go stale relative to graph.json with no signal anywhere in the loop. Extend the existing PreToolUse staleness check (which already compares graph.json's mtime against the target file) to also compare wiki/index.md's mtime against graph.json's when a wiki file is read, and nudge back to source/query when wiki is the older of the two. Also updates AGENTS.md and the always_on/ prose variants that unconditionally told agents to trust the wiki, so they point at this new signal instead of assuming wiki/ is always current.
There was a problem hiding this comment.
Pull request overview
This PR adds a “stale wiki” signal to the existing hook-guard read path so agents don’t silently rely on an out-of-date graphify-out/wiki/ when it predates graphify-out/graph.json, and updates agent-facing instructions to reference that signal.
Changes:
- Extend
_run_hook_guard("read", ...)to emit a new PreToolUse nudge whenwiki/index.mdis older thangraph.json. - Add focused tests covering stale wiki, fresh wiki, and missing
graph.jsonbehaviors. - Update
AGENTS.mdand always-on agent instruction variants to conditionally trust the wiki unless the nudge indicates staleness.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
graphify/cli.py |
Adds wiki-vs-graph.json mtime check and emits a new read nudge when wiki is stale. |
tests/test_hook_guard.py |
Adds regression tests for stale/fresh/missing-graph wiki read behavior. |
AGENTS.md |
Updates agent guidance to fall back when the hook flags wiki as stale. |
graphify/always_on/agents-md.md |
Same guidance update for always-on agents instructions. |
graphify/always_on/antigravity-rules.md |
Same guidance update for always-on antigravity rules. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "hookSpecificOutput": { | ||
| "hookEventName": "PreToolUse", | ||
| "additionalContext": ( | ||
| 'graphify-out/wiki/ predates the current graph.json. Unlike graph.json, ' |
…en fragment drift Two fixes on top of the wiki-staleness nudge: 1. Both _READ_NUDGE_STALE and the new _READ_NUDGE_WIKI_STALE hardcoded 'graphify-out/' in their message text, even though the hook-guard's detection logic already honors a custom GRAPHIFY_OUT_NAME. A project using a custom output dir would get a nudge pointing at a path that doesn't exist. Both are now functions parameterized by the actual configured out_name (flagged by Copilot's PR review on Graphify-Labs#2024). 2. The previous commit hand-edited the *generated* graphify/always_on/ agents-md.md and antigravity-rules.md directly instead of their fragment sources under tools/skillgen/fragments/always-on/, which test_always_on_files_are_guarded_by_check (correctly) flagged as drift. Fixed by editing the fragments and regenerating, then registering the wording change in gen.ALWAYS_ON_SANCTIONED_EDITS (alongside the existing Graphify-Labs#1530 entry) so the byte-for-byte roundtrip guard treats it as an intentional, reviewable edit rather than silent baseline drift. Adds 2 tests for the dynamic output-dir naming and updates test_always_on_roundtrip_is_byte_faithful's fixed expectations to cover both new sanctioned edits.
|
Pushed a follow-up commit addressing the review comment above: both Also caught and fixed a self-inflicted issue while doing that: my first commit hand-edited the generated Full suite is back to the same 13 pre-existing, unrelated failures (tree_sitter_hcl/ollama/manifest/wheel-packaging) with all 3241 other tests passing. |
Fixes #2006
Problem
to_wikihas exactly one call site (export wikisubcommand). It's never reached fromupdate,watch, or the rebuild hook path, sographify-out/wiki/freezes the moment it's generated. MeanwhileAGENTS.mdand thealways_on/prose variants tell agents to navigate the wiki unconditionally instead of reading source — an agent can silently answer architecture questions from a wiki that's months stale, with no signal anywhere in the loop.graph.jsonalready has this kind of staleness handling: the PreToolUse hook incli.pycomparesgraph.json's mtime against the target file's mtime (plus aneeds_updatesentinel) and softens to a nudge instead of blocking.wiki/had no equivalent.Fix
_run_hook_guard("read", ...)staleness check: when the read target is underwiki/, comparewiki/index.md's mtime againstgraph.json's. If wiki is older, emit a new_READ_NUDGE_WIKI_STALEnudge pointing the agent back tographify query/source, and tographify export wikito refresh it.AGENTS.md,always_on/agents-md.md, andalways_on/antigravity-rules.md— all three told agents to trust the wiki unconditionally — to reference this new signal instead.Docs-only fix, no change to when/how
wiki/is generated (that's the bigger option the issue also names — wiringto_wikiintoupdate/watch— left for a separate PR if wanted).Test plan
tests/test_hook_guard.py: nudges when wiki predates graph.json, silent when wiki is fresh, silent (fail-open) when graph.json doesn't existcli.pychange (keeping the new tests) —test_read_wiki_nudges_when_stalefails as expected (assert 'predates the current graph.json' in ''). Restored the fix — passes.pytest tests/test_hook_guard.py tests/test_hook_strict.py -q— 89 passed, no regressionspytest tests/ -q— full suite: 3239 passed, 167 skipped, 13 pre-existing failures unrelated to this change (tree_sitter_hclnot installed, ollama SDK version mismatch, wheel-packaging test — all intest_terraform.py/test_ollama_retry_cap.py/test_manifest_ingest.py/test_install_references.py, none touchingcli.pyor hook logic)