always_on: none of the six templates name `affected`, and it went uncalled in 262 sessions

[HectorBernstorff]

Summary

None of the six always-on templates mention affected. All six name query, path and explain:

graphify/always_on/  (0.9.50)
  agents-md.md            affected=0   "graphify query"=1
  antigravity-rules.md    affected=0   "graphify query"=1
  claude-md.md            affected=0   "graphify query"=1
  gemini-md.md            affected=0   "graphify query"=1
  kiro-steering.md        affected=0   "graphify query"=1
  vscode-instructions.md  affected=0   "graphify query"=1

This is a different layer from #2535, which reports affected missing from SKILL.md and references/. The skill is loaded on demand; the always-on block is the text that reaches the agent on every session and is what it actually reaches for. Same file family as #2006, which reports the opposite inaccuracy in the same block (it points at a wiki/ that export wiki alone ever writes).

Field measurement

A ~1k-page Next.js monorepo, graph of 32 MB, graphify installed since 2026-08-11, claude install block byte-identical to always_on/claude-md.md.

affected was called zero times in 262 sessions. Counting tool_use blocks in agent transcripts, not grepping text — the always-on block contains the literal string graphify query, so a text grep reports ~100% of sessions and is worthless here.

It is not that the graph went unused. The opt-in query ledger (GRAPHIFY_QUERY_LOG_ENABLE=1), counted per day:

Day	Traversals	Verbs
2026-08-20 … 08-25	0	—
2026-08-26	5	query 4, explain 1
2026-08-27	9	query 7, explain 2
2026-08-28	9	query 5, explain 4

Only the verbs the block names. 08-26 is the day the PreToolUse guard was reinstalled here after a period without it; the guard changed whether the graph was consulted, and the block determined how. affected was never reached for, because nothing ever named it.

Why it is the notable omission

affected answers the question an agent is asked immediately before every edit — what depends on this, what breaks if I change it. The guard covers search (Bash/Grep) and read (Read/Glob); neither fires on an edit tool, so that moment has no mechanism at all, and the block is the only thing that could point at one.

Measured on the same repo: editing packages/seo/src/breadcrumbs/buildBreadcrumbTrail.ts, affected returns 197 dependants with file and line in 0.08-0.12s warm (1.3-2.2s cold, dominated by reading graph.json). Reproducing that with grep takes several calls and misses re-exports.

Suggested change

One clause in each of the six templates, alongside the existing path / explain sentence. For claude-md.md:

-Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts.
+Use `graphify path "<A>" "<B>"` for relationships, `graphify explain "<concept>"` for focused concepts,
+and `graphify affected "<path-or-symbol>"` before changing something, to list what depends on it.

Two notes from using it, in case they shape the wording:

• Pass a path, not a basename. This repo has 75 index.ts, 72 page.tsx, 60 loading.tsx; graphify affected "index.ts" answers No unique node match, while packages/seo/src/index.ts returns 157. A bare-basename example in the docs would fail on most files of any app-router codebase. (Related: affected silently returns nothing when the path is spelled differently (./ or absolute) #2706.)
• Repo-relative, not absolute. From a git worktree, the absolute path carries a .worktrees/<slug>/ segment and matches nothing. Worth naming, since worktrees are where a lot of agent work happens.

Happy to send the six-file PR if the wording above is close to what you want.

Environment

graphify 0.9.50, uv tool install, macOS 15.5 (Darwin 25.5.0), Claude Code.

Not filing the strict-stamp half of this: #3053 already covers affected and god-nodes skipping _touch_query_stamp and the query ledger, and I can confirm it still reproduces on 0.9.50 — the three _touch_query_stamp call sites are query (cli.py:1187), path (:1565) and explain (:1699), and stat'ing the stamp across five invocations shows affected and god-nodes leaving it untouched.