fix(mcp): carry the index-drift guardrail into the per-project instructions - #1851
Open
AllanStepps wants to merge 1 commit into
Open
fix(mcp): carry the index-drift guardrail into the per-project instructions#1851AllanStepps wants to merge 1 commit into
AllanStepps wants to merge 1 commit into
Conversation
…ctions SERVER_INSTRUCTIONS_NO_ROOT_INDEX omitted the "changed on disk after the last index sync" anti-pattern. That bullet's own parenthetical names projects queried via `projectPath` — "which have no live watcher" — as the audience most exposed to drift, and a server whose root has no index serves nothing but `projectPath` queries. The guidance was therefore missing from the only audience that always hits the condition it describes. An agent that meets the flag without having been told what it means can read a flagged response as a normal one, so this is a correctness gap rather than an efficiency one. The bullet moves into one INDEX_DRIFT_GUARDRAIL constant that both variants interpolate, so a later edit cannot reach one and miss the other. SERVER_INSTRUCTIONS is byte-identical before and after; the per-project variant grows by 581 characters and stays well short of the full playbook, which the existing "not the full playbook" assertion still pins.
AllanStepps
force-pushed
the
fix/no-root-index-drift-guardrail
branch
from
September 12, 2026 17:05
896bb31 to
476553f
Compare
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The gap
SERVER_INSTRUCTIONS_NO_ROOT_INDEXomits the index-drift anti-pattern:That parenthetical names
projectPath-reached projects as the audience most exposed to drift. A server whose root has no index serves nothing butprojectPathqueries — the variant says so itself ("pass its path asprojectPath… for as many projects as you like in one session"). So the guidance is absent from the only audience that always meets the condition it describes.An agent that receives the
⚠ changed on diskflag without ever having been told what it means can read a flagged response as a normal one. That makes this a correctness gap rather than an efficiency one: the flag exists precisely because codegraph declined to serve a possibly-mis-sliced body, and the agent is supposed toReadthat file instead.This deliberately does not re-send the playbook
__tests__/mcp-unindexed.test.tspins that the per-project variant is not the full playbook, and the comment gives the reason ("keeps the common case tight"). I agree with that decision, so this PR does not touch it:expect(instructions).not.toMatch(/## How to query/)still passes, unchanged.SERVER_INSTRUCTIONSis byte-identical before and after — verified by extracting both constants pre- and post-change and comparing.Only the one bullet whose own text points at this audience moves, into a shared
INDEX_DRIFT_GUARDRAILconstant that both variants interpolate, so a later wording edit cannot reach one variant and miss the other.Tests
Three assertions added to the existing
mcp-unindexedsuite: both variants carry the guardrail, and the per-project one still is not the full playbook.npm run build(tscincluded) passes.__tests__/installer-targets.test.tsshows 2 failures on my machine under theCLAUDE_CONFIG_DIRdescribe — I verified those are pre-existing: identical on a clean checkout with my changes stashed. Node 22.23.2 (the suite needsnode:sqlite, so ≥22.5 as documented; on Node 20 the DB-backed tests fail before reaching any of this).How I ran into it
A global
codegraph install, then work across several repos — so the server starts outside any index and every project is reached byprojectPath.src/mcp/tools.ts:1643already records a prior case where this variant's prose was not enough on its own and "the reporter had to add anAGENTS.mdnote"; I had written the same kind of note before tracking it to this constant.Happy to narrow or reword if you would rather keep the variant leaner still.