You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
upgrade must not rewrite agent instruction files, MCP entries or hooks by default #332
codegraph-vba upgrade silently modifies files it does not own. In src/upgrade/index.ts:
selfHealInstalledSurfaces() (~line 592) spawns codegraph install --refresh, which rewrites the marker-fenced instruction sections in CLAUDE.md, AGENTS.md and GEMINI.md, and the MCP entries, for every configured agent. It is on by default; the only opt-out is CODEGRAPH_NO_INSTALL_REFRESH=1.
selfHealPromptHook() (~line 610) wires the Claude UserPromptSubmit hook (codegraph prompt-hook). It is on by default; the only opt-outs are CODEGRAPH_NO_PROMPT_HOOK=1 / CODEGRAPH_PROMPT_HOOK=0.
Observed on 2026-10-24 (upgrade 1.15.0 -> 2.1.1): the upgrade output Refreshing agent instruction sections and config written by previous versions… and refreshed ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.config/opencode/AGENTS.md, Hermes and Gemini. It appended a second <!-- CODEGRAPH_START --> block to the three instruction files ("if there is no .codegraph/ directory, skip CodeGraph entirely — indexing is the user's decision"). Those files already carry gentle-ai's <!-- gentle-ai:codegraph-guidance --> block, which says the opposite (initialise immediately). The two blocks contradict each other and agents lose time resolving them.
gentle-ai owns CodeGraph guidance on these machines. The fork must not compete with it.
Expected
upgrade never touches agent instruction files, MCP entries or hooks unless the user asks for it explicitly (opt-in, e.g. --refresh-agents), instead of opt-out environment variables.
When an agent file already contains a <!-- gentle-ai: marker, install and install --refresh leave that file's instruction section alone and say so.
The upgrade summary lists any agent surface it did not touch, so the behaviour is visible.
README and CHANGELOG document that the fork does not write guidance when gentle-ai manages it.
Acceptance
Test: an upgrade run against a fixture home with a gentle-ai block in CLAUDE.md leaves every agent file byte-identical.
Test: install --refresh on a file with a gentle-ai marker does not add a CODEGRAPH_START block.
Test: the explicit opt-in still refreshes configured agents.
Scope note: the fork must never write, refresh or remove skills in any agent directory. It does not today (no skills references in src/); add a test that install, install --refresh and upgrade leave every skills directory untouched, so it cannot regress. Skills reach projects through the fleet propagator, not through tool installers.
Activity
ardelperal commentedon Oct 24, 2026
Scope note: the fork must never write, refresh or remove skills in any agent directory. It does not today (no skills references in
src/); add a test thatinstall,install --refreshandupgradeleave every skills directory untouched, so it cannot regress. Skills reach projects through the fleet propagator, not through tool installers.