Summary
This repo carries two always-loaded agent-instruction surfaces covering the same ground: AGENTS.md (with CLAUDE.md as a symlink to it) and .github/copilot-instructions.md. Both describe build commands, architecture, and conventions. Nothing states which one wins, so they drift independently - and they already have.
The drift is not hypothetical
The CI Node matrix is currently stated in three places, and two of the three are wrong:
| Source |
Says |
.github/workflows/node-checks.yml (the owner) |
[22, 24] |
.github/copilot-instructions.md |
"Node 20 and 22" |
README.md:19 |
"node@16, node@18 and node@20" |
An agent or contributor reading either prose copy gets a wrong answer about what CI actually runs, and the README copy is wrong by two major versions.
#1780 fixes those two prose copies by reducing them to a pointer at the workflow, which is the pattern AGENTS.md already prescribes for itself ("Do not repeat what the codebase already shows; point to the authoritative file or command instead"). That closes the immediate factual error but not the structural one.
The structural question
AGENTS.md has a ## Maintaining this file section setting a deliberate bar: keep it to knowledge useful to almost every session, point at authoritative sources rather than restating them, prefer rewriting over appending. .github/copilot-instructions.md has no equivalent governance and no stated relationship to AGENTS.md, so:
- a maintainer updating one has no signal that the other exists;
- an agent loading both gets the same territory twice, with no precedence rule for conflicts;
- every fact restated in both is a future drift like the one above.
What to decide
One of:
- Retire
copilot-instructions.md, or reduce it to a short pointer at AGENTS.md. Copilot reads whatever is at that path; a stub that redirects costs nothing and removes the second copy.
- Keep it, and give it a scope that does not overlap - Copilot-specific mechanics only, with everything shared living in
AGENTS.md.
- Keep both as-is and accept the duplication, in which case say so explicitly in both files so the next maintainer knows the redundancy is intentional and updates both.
Whichever is chosen, the outcome should be written down in AGENTS.md's ## Maintaining this file section, since that is the file that currently claims to govern agent knowledge in this repo.
Raised from the schema-consumer audit in #1780, which found the Node-matrix discrepancy while checking whether the change had invalidated any documented fact. Deliberately not resolved there - fixing the wrong facts is in scope for that PR; deciding whether the second instruction surface should exist is not.
Summary
This repo carries two always-loaded agent-instruction surfaces covering the same ground:
AGENTS.md(withCLAUDE.mdas a symlink to it) and.github/copilot-instructions.md. Both describe build commands, architecture, and conventions. Nothing states which one wins, so they drift independently - and they already have.The drift is not hypothetical
The CI Node matrix is currently stated in three places, and two of the three are wrong:
.github/workflows/node-checks.yml(the owner)[22, 24].github/copilot-instructions.mdREADME.md:19An agent or contributor reading either prose copy gets a wrong answer about what CI actually runs, and the
READMEcopy is wrong by two major versions.#1780 fixes those two prose copies by reducing them to a pointer at the workflow, which is the pattern
AGENTS.mdalready prescribes for itself ("Do not repeat what the codebase already shows; point to the authoritative file or command instead"). That closes the immediate factual error but not the structural one.The structural question
AGENTS.mdhas a## Maintaining this filesection setting a deliberate bar: keep it to knowledge useful to almost every session, point at authoritative sources rather than restating them, prefer rewriting over appending..github/copilot-instructions.mdhas no equivalent governance and no stated relationship toAGENTS.md, so:What to decide
One of:
copilot-instructions.md, or reduce it to a short pointer atAGENTS.md. Copilot reads whatever is at that path; a stub that redirects costs nothing and removes the second copy.AGENTS.md.Whichever is chosen, the outcome should be written down in
AGENTS.md's## Maintaining this filesection, since that is the file that currently claims to govern agent knowledge in this repo.Raised from the schema-consumer audit in #1780, which found the Node-matrix discrepancy while checking whether the change had invalidated any documented fact. Deliberately not resolved there - fixing the wrong facts is in scope for that PR; deciding whether the second instruction surface should exist is not.