AGENTS.md: record the cross-QEP amendment convention as practice - #32
Merged
Conversation
The convention tracked in #9 — a QEP under review is never forward- referenced by the standard it extends; the downstream QEP's own PR carries the upstream edits — stays author-side practice rather than QEP-1 text. QEP-1 already says amend in place and bump `version`; which PR carries the edit is the mechanical consequence, and it is judgement of the kind the Automation section already delegates here. Also records the ruling of 2026-09-09 (#23): a QEP is the source of truth and is independent of every repository, so the convention stops at this repo's boundary. A QEP states the rule; a consuming repo owns how and when it conforms, and no precedence clause, handover obligation, or foreign tracking-issue reference belongs in a QEP. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The change is a straightforward documentation update that cleanly records existing practice without introducing behavioral/code risk.
Pull request overview
Updates contributor guidance in AGENTS.md to record the established cross-QEP amendment convention as author-side practice, clarifying how to avoid dangling references and how to scope the convention to this repository.
Changes:
- Document that a downstream QEP should carry any necessary edits to upstream QEPs in the same PR (avoiding forward-references from accepted QEPs to drafts).
- Clarify that this convention does not apply to standards/practices outside this repository (avoid cross-repo precedence/handovers/tracking-issue references inside QEP text).
File summaries
| File | Description |
|---|---|
| AGENTS.md | Adds explicit guidance on cross-QEP amendments (in-repo) and excludes cross-repo standards from this convention. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
A description of an external repo goes stale the same way a pointer does, and without any signal. QEP-6's Adoption item 5 said the projects dashboard re-sorts children by issue number and prescribed the remedy; status-projects had already removed the sort on its own reasoning two days earlier, so the QEP shipped a stale claim and an obligation that had been discharged before it was written. The rule that survives is the principle with its reason attached. QEP-6 §3 now says a consumer that republishes a tracker presents the structure the tracker expresses, because a consumer that re-sorts or re-groups makes a conformant tracker and a non-conformant one publish identically. That holds whatever any consumer does next, and applies to consumers the author has never heard of. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Records the cross-QEP amendment convention in
AGENTS.mdas author-side practice, rather than folding it into QEP-1 as #23 originally proposed. Ruled 2026-09-09; the reasoning is on #9, which this retires.Why here and not in QEP-1
QEP-1 already says amend in place and bump
version— "put the edit in the PR that needs it" is the mechanical consequence, not a separate rule. It is author-side judgement of exactly the kind QEP-1's Automation section already delegates toAGENTS.md, alongside substantive-vs-editorial and the commit subject. AndAGENTS.mdis the document an author actually reads before drafting a QEP, which is where the convention needs to be to change anything.The second-instance rule that #9 was waiting on never fired, either: QEP-2 ↔ QEP-4 is intra-repo and QEP-6 ↔ status-projects is cross-repo — two problems with one instance each, not two instances of one problem.
Three paragraphs
The first is the original convention from #9: don't forward-reference a draft from an accepted QEP, and put the upstream edits in the downstream QEP's own branch so reference and target land in one commit. Unchanged in substance — it is how QEP-2 ↔ QEP-4 already works, with the removed hook wording preserved in the
qep-0004branch's Amendments to QEP-2 section.The second records the ruling that the convention stops at this repo's boundary. A QEP is the source of truth and is independent of every repository: it states the rule, and a consuming repo owns how and when it conforms. Precedence clauses, handover obligations and tracking-issue references for another repository do not belong in a QEP — an issue number in a repo this one does not own is a status pointer that rots, and a QEP states rules rather than tracking their adoption elsewhere.
The third extends that from pointers to descriptions, added after QEP-6 supplied the worked example. Its Adoption item 5 said the projects dashboard re-sorts children by issue number and prescribed the remedy — a one-row contract change, a sort removal, and the test to verify it. status-projects had already removed the sort on its own reasoning two days earlier, and for a better-stated reason than the QEP gave. So the QEP shipped a stale claim and an obligation discharged before it was written, and nothing would have signalled either. What survives instead is the principle with its reason attached: §3 now says a consumer that republishes a tracker presents the structure the tracker expresses, because a consumer that re-sorts or re-groups makes a conformant tracker and a non-conformant one publish identically. That holds whatever any consumer does next.
Already applied
🤖 Generated with Claude Code