Repository navigation
copilot-instructions.md links to AGENTS.md sections not in the verbatim-carry contract #155
Description
Found while re-syncing a derived repo (ptr727/NxWitness, see ptr727/NxWitness#439) against the template.
.github/copilot-instructions.md is a whole-file verbatim carry, but it links to AGENTS.md sections that the verbatim-carry contract does not require derived repos to carry:
../AGENTS.md#release-model../AGENTS.md#files-and-sections-derived-repos-must-carry-verbatim../AGENTS.md#staying-in-sync-and-reporting-drift-upstream
The contract ("Files and Sections Derived Repos Must Carry Verbatim") mandates only the AGENTS.md "PR Review Etiquette" section (plus the copilot-instructions file itself, .markdownlint-cli2.jsonc, .editorconfig, .gitattributes). A derived repo whose AGENTS.md legitimately omits "Release Model" / the carry-contract section / "Staying in Sync" (or names them differently — e.g. NxWitness uses a "Versioning" section) ends up with dangling anchors after carrying copilot-instructions.md verbatim.
So the verbatim-carry file has cross-references that only resolve in the template itself, not in conforming derived repos.
Possible fixes (maintainer's call):
- Add "Release Model", "Files…Must Carry Verbatim", and "Staying in Sync and Reporting Drift Upstream" to the AGENTS.md verbatim-carry contract (so every derived repo has those exact sections/anchors), or
- Make copilot-instructions.md not depend on non-mandated AGENTS.md anchors — link to
../AGENTS.mdgenerally, or point those specific references at the template repo's AGENTS.md.
In NxWitness#439 I adapted locally per option 2 (retargeted #release-model → the repo's #versioning, and pointed the carry-contract / staying-in-sync links upstream), but the template should define the canonical fix so the next derived repo doesn't hit this.
Activity
ptr727 commentedon Jun 20, 2026
Update: carrying this file into a derived repo (ptr727/NxWitness#439) surfaced two more instances of the same root cause — the verbatim-carry
.github/copilot-instructions.mdembeds template-specific assumptions and carry-time meta that don't hold once carried. The Copilot reviewer flagged each in successive rounds:Prose overstates what a derived AGENTS.md covers. The intro ("It covers project layout, branch flow, … and what NOT to touch") and the "When in Doubt" line ("release flow, files you must not touch, branching, …") assert AGENTS.md documents protected/untouchable files. That's true for the template's own AGENTS.md, but a conforming derived repo (only the "PR Review Etiquette" section is mandated verbatim) need not have any "what not to touch" guidance — so the claim is inaccurate there. I reworded both locally to list only topics the repo's AGENTS.md actually covers.
The carry-instruction blockquote goes stale after carry. The runbook's opening blockquote ("Carry this runbook verbatim into every derived repo. … change only the
<owner>/<repo>/<N>placeholders in the snippets below …") is template-author-facing and becomes misleading in a derived repo where<owner>/<repo>are already filled (only<N>remains). I dropped the blockquote locally (it's carry guidance, not runbook mechanics).Both reinforce fix option 2 from the issue body: keep the verbatim-carried file free of (a) cross-refs/claims that assume non-mandated AGENTS.md sections, and (b) carry-time meta that only makes sense pre-carry. If the template instead prefers option 1 (expand the verbatim-carry contract so every derived repo has the matching AGENTS.md sections), the prose in #1 would become accurate, but the stale-placeholder blockquote in #2 would still need rephrasing to survive the carry.
Decouple verbatim-carry runbook, clarify versioning, list downstreams (…
ptr727 commentedon Jun 20, 2026
Fixed via #156 (merged to
develop), adopting Option 2 — decouple:.github/copilot-instructions.mdis now self-contained and survives a verbatim carry into a conforming derived repo.<owner>/<repo>/<N>blockquote and the template-specific versioning paragraph.../AGENTS.md#cross-ref now resolves only to the mandated#pr-review-etiquette; the staying-in-sync reference points at an explicit upstream-template URL.This also resolves both follow-up instances from the comment thread (the overstated prose and the stale carry-time blockquote). The change will reach
mainon the nextdevelop -> mainpromotion.