copilot-instructions.md links to AGENTS.md sections not in the verbatim-carry contract

[ptr727]

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):

1. 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
2. Make copilot-instructions.md not depend on non-mandated AGENTS.md anchors — link to ../AGENTS.md generally, 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.

[ptr727]

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.md embeds template-specific assumptions and carry-time meta that don't hold once carried. The Copilot reviewer flagged each in successive rounds:

1. 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.

2. 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.

[ptr727]

Fixed via #156 (merged to develop), adopting Option 2 — decouple: .github/copilot-instructions.md is now self-contained and survives a verbatim carry into a conforming derived repo.

• Removed the pre-carry <owner>/<repo>/<N> blockquote and the template-specific versioning paragraph.
• Every remaining local ../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.
• Dropped the overstated "what NOT to touch" / "files you must not touch" claims (the intro and "When in Doubt" now describe only what a conforming derived AGENTS.md carries).

This also resolves both follow-up instances from the comment thread (the overstated prose and the stale carry-time blockquote). The change will reach main on the next develop -> main promotion.