fix(agent-core-v2): read AGENTS.override.md as per-directory instruction override

[haiyu614]

Requirement or Bug

Resolve #3566

Bug Reproduction Steps

1. In a git repository whose root is $REPOBASE, create $REPOBASE/AGENTS.override.md with distinctive content and no AGENTS.md.
2. Start Kimi Code CLI anywhere inside the repository (version 0.41.0 reproduces it; main at 21406fb4c reproduces it as well).
3. Run /status or inspect the injected system prompt: $REPOBASE/AGENTS.override.md is never loaded. Renaming the same file to AGENTS.md makes it load immediately.

The new tests in packages/agent-core-v2/test/agent/profile/context.test.ts (loadAgentsMd AGENTS.override.md) encode this scenario and failed before the fix.

Root Cause

loadAgentsMdForRoots in packages/agent-core-v2/src/agent/profile/context.ts enumerates the candidate instruction file names per directory from the AGENTS_MD_PLAIN_NAMES constant, which only contained AGENTS.md and agents.md. AGENTS.override.md was therefore never probed anywhere in the discovery chain (project root → cwd). This is a fundamental omission, not a workaround-level issue: the OpenAI Codex convention this feature mirrors (see codex-rs/core/src/agents_md.rs, LOCAL_AGENTS_MD_FILENAME = "AGENTS.override.md") probes the override name first in every directory and uses the first existing candidate, so an override replaces the plain AGENTS.md of the same directory.

Code Changes

All in packages/agent-core-v2:

1. src/agent/profile/context.ts
   • AGENTS_MD_PLAIN_NAMES is now ['AGENTS.override.md', 'AGENTS.md', 'agents.md']. Because every consumer probes the list in order and stops at the first hit (loadAgentsMdForRoots, findAgentsMdInDir, agentsMdCandidatePaths), the override shadows only the plain names of its own directory; .kimi-code/AGENTS.md keeps its existing additive behavior, and ancestor directories keep contributing their own files.
   • agentsMdWatchRoots previously re-listed the three project candidate names by hand; it now derives the per-directory list from AGENTS_MD_PLAIN_NAMES (plus dotKimiAgentsMdPath), so the file watcher reloads on AGENTS.override.md edits and cannot drift from the loader again.
2. test/agent/profile/context.test.ts — three tests: override-only root loads; override preferred over AGENTS.md within one directory; per-directory replacement while ancestors keep their own files.
3. .changeset/read-agents-override-md.md — patch changeset for @moonshot-ai/kimi-code.

Behavior Changes and Affected Users

Behavior	Before	After	Who relies on the old behavior	Escape hatch
Directory contains only AGENTS.override.md	File ignored	File loaded into the system prompt	None (the file was dead weight before)	Delete/rename the file
Directory contains both AGENTS.override.md and AGENTS.md/agents.md	Only the plain name loaded	Override replaces the plain name within that directory; other directories unchanged	Repositories that already ship an unrelated file literally named AGENTS.override.md and expect it ignored	Rename the file; .kimi-code/AGENTS.md still loads additively
Directory contains only AGENTS.md/agents.md	Loaded	Unchanged	Everyone	N/A
Editing AGENTS.override.md during a session	No watcher coverage, no reload	Watcher reloads and the change-reminder fires	None	Set watch.enabled = false

Affected modules: instruction discovery (agent/profile/context.ts), instruction watching (WorkspaceInstructionsService via agentsMdWatchRoots), the AGENTS.md discovery reminder (agentsMdReminderService.ts, which consumes the shared constants and now recognizes reads of AGENTS.override.md). Test coverage: the three new context.test.ts cases for discovery, and the existing agentsMdReminder.test.ts / workspaceInstructions suites confirming no regression.

Checklist

• I have read the CONTRIBUTING document.
• Conventional Commits title: fix(agent-core-v2): read AGENTS.override.md as per-directory instruction override
• Changeset included (.changeset/read-agents-override-md.md, @moonshot-ai/kimi-code: patch).
• Tests added; typecheck, lint (incl. check-no-comments) and the agent-core-v2 suites pass locally (2 pre-existing symlink tests fail on Windows both with and without this change).

[changeset-bot]

🦋 Changeset detected

Latest commit: 6245af3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@moonshot-ai/kimi-code	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR