From 9d74409547ef18d969f81960017f2c9e5e136939 Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Wed, 9 Sep 2026 09:26:38 +1000 Subject: [PATCH 1/2] AGENTS.md: record the cross-QEP amendment convention as practice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 (QuantEcon/qeps#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) --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a0d730c..ac894a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,6 +55,18 @@ standard is a normal PR against the QEP under lazy-consensus that **bumps its `version`**; a *different* decision that replaces it wholesale is a **new** QEP that marks the old one `Superseded`. Don't supersede for routine maintenance. +**A QEP that changes another QEP carries the edit itself.** Don't add a forward +reference from an accepted QEP to one still in draft: the link dangles on `main`, and +the draft's review can still reshape what the reference promised. Put the upstream edits +in the downstream QEP's own branch — an *Amendments to QEP-N* section until acceptance, +applied as file edits at landing — so reference and target land in one commit, and a +reviewer sees the whole change as one diff. + +Standards **outside** this repo are not covered by that. 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. Don't write precedence clauses, handover obligations, or +tracking-issue references for another repository into a QEP. + **Does `version` move?** — the author/reviewer call, not CI's: - **Substantive** (any change to normative content — a rule, a value, a table row, a From 6dcfbe33b5c278ca7818dd81372e37d51ad813f9 Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Wed, 9 Sep 2026 09:56:29 +1000 Subject: [PATCH 2/2] AGENTS.md: don't record what another repository does today MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ac894a8..f2dd8c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,6 +67,13 @@ and is independent of every repository: it states the rule, and a consuming repo how and when it conforms. Don't write precedence clauses, handover obligations, or tracking-issue references for another repository into a QEP. +Nor what another repository **does today**. A description goes stale the same way a +pointer does, and silently: QEP-6 said the projects dashboard re-sorts children by issue +number and prescribed the fix, when that repo had already removed the sort on its own +two days earlier. State the **principle and the reason for it**, never the instance — a +rule that explains itself outlives any one consumer's behaviour, and a reader can apply +it to consumers you have never heard of. + **Does `version` move?** — the author/reviewer call, not CI's: - **Substantive** (any change to normative content — a rule, a value, a table row, a