Skip to content

upgrade must not rewrite agent instruction files, MCP entries or hooks by default #332

Open

Description

@ardelperal

Problem

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

  1. 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.
  2. When an agent file already contains a <!-- gentle-ai: marker, install and install --refresh leave that file's instruction section alone and say so.
  3. The upgrade summary lists any agent surface it did not touch, so the behaviour is visible.
  4. 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.

Activity

  1. ardelperal commented on Oct 24, 2026

    @ardelperal
    OwnerAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions