Process: downstream QEPs carry their amendments to upstream standards (QEP-1 amendment, deferred to second instance)

[mmcky]

Context

While finalising QEP-2 (#2) alongside the in-development QEP-4 (#8), the QEP-2 draft initially forward-referenced QEP-4: relative links to a file not yet on main, plus restated mechanics (origin labels, task /-namespaces, the prune skip-rule) whose final shape is exactly what #8's review is deciding. That coupling has two failure modes: dangling links on main until the downstream QEP merges, and the risk that its review reshapes the mechanics after the upstream standard is Accepted, forcing an immediate version-bump amendment.

Convention adopted in practice

The QEP that creates a dependency ships the amendments to the standards it touches, in its own acceptance PR. QEP-2 is now self-contained (forward references removed in 091eeea); the qep-0004 branch preserves the removed hook wording in an Amendments to QEP-2 section and re-applies it — in whatever form #8's review settles — when it lands, bumping QEP-2's version if QEP-2 is Accepted by then.

This is QEP-1's amend-in-place model with the dependency arrow pointing the right way: reference and target land atomically, main never holds a dangling cross-QEP link, and reviewers of the downstream QEP see its full blast radius (including the upstream edits) as one diff. The existing related: / Related-row CI lockstep check validates the pairing in the landing PR, where both files exist, so even its in-flight warning path goes quiet.

Proposed QEP-1 amendment

One sentence in QEP-1's process section, roughly: a QEP that depends on or extends an existing QEP is not forward-referenced by it while in development; instead the new QEP's acceptance PR carries the amendments to the standards it touches (version-bumped per the amendment rule), so cross-references land atomically.

When to act

Per the second-instance rule (as applied to the companion-appendix convention), this stays practice until a second dependent-QEP pair appears. QEP-2 ↔ QEP-4 is the first instance; fold the sentence into QEP-1 (with a version bump) when the next pair shows up, and close this issue against that amendment.

[quantecon-services]

A candidate second instance — and it points outside the QEP set

This issue's When to act says the convention stays practice "until a second dependent-QEP pair appears. QEP-2 ↔ QEP-4 is the first instance; fold the sentence into QEP-1 (with a version bump) when the next pair shows up, and close this issue against that amendment." Two candidates have appeared, and neither is quite the shape the sentence anticipates.

Candidate 1 — QEP-6 ↔ QEP-2, where the convention was not needed but the lockstep is inert

QEP-6 (#18) reasons about QEP-2 explicitly and in both directions. §2 asserts the boundary — "a work item whose content is a bug is Task plus the bug label, never a Bug type" — and its Alternatives section rejects a tracking type label "in favour of the native Project issue type: QEP-2's one-type-per-issue label rule stays untouched".

So QEP-6 carries no amendment to QEP-2, and correctly: it claims to leave QEP-2 alone rather than to extend it. That is a dependency without an amendment, which this issue's sentence does not describe — it assumes a downstream QEP that touches an upstream standard's content.

But there is a real gap underneath. QEP-6 carries no related: frontmatter and no Related header-table row. The pairing check this issue names as the validator — "The existing related: / Related-row CI lockstep check validates the pairing in the landing PR" — enforces consistency if related: is present and nothing at all if it is absent. So on the one QEP that most explicitly reasons about another, the mechanism is inert. That is cheap to close: check.mjs already validates the pairing, so requiring related: where a QEP names another QEP normatively is a one-condition change.

Candidate 2 — QEP-6 ↔ an external contract, which the sentence does not cover at all

The stronger instance is not a QEP pair. QEP-6's Adoption clause (labelled 3. in source, rendered as 4 — see #26 item 4) makes QEP-6 authoritative over the projects dashboard's C2 tracker contract:

"The skills currently cite the dashboard's tracker contract, which permits body constructs this QEP forbids; until that contract's planned handover to this QEP, this QEP is authoritative for tracker structure wherever the two disagree."

That is exactly this issue's pattern — a downstream document carrying the amendment obligation for something it supersedes — with two differences that matter. The superseded document is an external contract in another repository, not a QEP; and the handover has no deadline. The qe skills already depend on that sentence at runtime: they name the disagreement (a body roster is C2-conformant and QEP-6-forbidden) and point at the clause rather than resolving it, which was the fix #19's finding 9 asked for.

So the org now has a QEP whose blast radius includes a non-QEP contract, and the only thing coordinating them is one prose sentence with no date.

Suggested disposition

Two options, and the choice is about how wide QEP-1's sentence should be:

(a) Treat this as the second instance and fold the sentence in now, widened. The amendment becomes roughly: a QEP that depends on, extends or supersedes an existing standard is not forward-referenced by it while in development; instead the new QEP's acceptance PR carries the amendments to the standards it touches, version-bumped per the amendment rule. Where the superseded standard is not itself a QEP, the Adoption section names the contract, the obligation, and a date by which the handover completes. That closes this issue and gives QEP-6's C2 clause a deadline it currently lacks.

(b) Hold for a genuine QEP-to-QEP amendment pair, on the grounds that neither candidate above is one — and meanwhile take the one-condition fix: require related: where a QEP names another QEP normatively, so the lockstep this issue relies on is not inert.

Worth noting for whichever is chosen: the first instance is still unresolved for a reason that belongs to #26 rather than here. QEP-4's decision deadline was never set (#8, open since 2026-07-23), and its Amendments to QEP-2 section re-applies "bumping QEP-2's version if QEP-2 is Accepted by then" — so QEP-2 cannot reach v1 until QEP-4 decides, and QEP-4 has no date on which it will. The convention is sound; the coupling only bites because one end has no clock.

---

Generated by Claude Code

[mmcky]

Not codified — the convention stays practice, and the external half is dropped outright

Ruled 2026-09-09 while reviewing #23, which had folded this issue's sentence into QEP-1 as change 4 of the v3 amendment. That change is withdrawn and this issue stays open. Two separate reasons, because the sentence had grown two halves.

The external half is wrong, not merely premature

The version in #23 widened this issue's sentence to cover the case where the touched standard is not a QEP — an external contract in another repository — and required the downstream QEP's Adoption section to name the contract, the obligation, and a tracking issue in that repo that discharges the handover. QEP-6 (#18) was the motivating case: it asserts precedence over docs/contracts/tracker.md in QuantEcon/status-projects and names QuantEcon/status-projects#114 as the discharging item.

That framing has the dependency arrow backwards. A QEP is the source of truth and is independent of every repository. A downstream consumer adapts to a QEP; the QEP owes it nothing in return. docs/contracts/tracker.md is not a peer standard being superseded — it is a consumer that must conform. So a QEP has no cause to assert precedence over it, and no cause to carry a pointer to another repository's issue. Conformance work belongs to the consuming repo, tracked in its own tracker, on its own schedule.

There is a second problem with naming the issue. QEP-1's own position — taken on #23 against a suggestion to hedge its prose with current implementation status — is that a QEP states the rule and is not a status report. An issue number in another repo is a status pointer that rots: it can be closed, renumbered, or moved, and the QEP is then wrong about a repo it does not own. The mechanism that actually makes "QEP is the source of truth" real is the other direction entirely: a downstream repo pins the QEP version / version-hash it conforms to, which is what #23's stamping change exists to enable.

The intra-repo half is real but does not need QEP-1 text

The original convention — a QEP under review is never forward-referenced by the standard it extends; the downstream QEP's own acceptance PR carries the upstream edits, version-bumped, so cross-references land atomically — still holds and is still how we work. It just does not earn a paragraph 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, and this is ordinary maintainer judgement of the kind the Automation section already delegates to AGENTS.md rather than legislating.

The second-instance rule also has not actually fired. QEP-2 ↔ QEP-4 is intra-repo; QEP-6 ↔ status-projects is cross-repo. Those are two different problems with one instance each, not two instances of one problem — and on the only cross-repo instance, the gap was spotted and QuantEcon/status-projects#114 was filed by maintainer judgement, without any rule existing to require it. The evidence offered for codifying is evidence that codifying was not needed.

Where that leaves things

• The convention stays practice. Revisit only if it actually fails — a dangling cross-QEP reference reaching main, or a downstream repo left silently non-conforming with nobody noticing.
• This issue stays open as the record of that, no longer targeting a QEP-1 amendment.
• QEP-6: Project Tracker Structure and Order (Draft) #18 needs an edit. Its Adoption item 4 currently cites "QEP-1's rule that a QEP touching another standard carries the amendment itself" — a rule that will not exist. The precedence sentence and the reference to QuantEcon/status-projects#114 should both go; QEP-6 should simply define tracker structure and leave conformance to the consumers. QuantEcon/status-projects#114 stays open as that repo's own work.
• QEP-1 v3: stamp from v0; drop the decision deadline; generate the index #23 is now three changes: stamp from v0, drop the decision deadline, generate the README index.

[mmcky]

Retired — the convention is recorded in AGENTS.md, not QEP-1

#32 adds it to AGENTS.md under Amending an accepted QEP, in two paragraphs matching the two halves this issue's sentence had grown: the original convention (don't forward-reference a draft from an accepted QEP; the downstream QEP's own branch carries the upstream edits), and the 2026-09-09 ruling that it stops at this repo's boundary (a QEP states the rule; a consuming repo owns how and when it conforms).

That is the whole of what was left here. The QEP-1 amendment this issue was holding open for is not happening — the reasoning is in the note above, and the short version is that QEP-1 already implies the intra-repo half and has no business legislating the cross-repo one.

Closing rather than leaving it open as a tripwire: nobody re-reads an open issue at the moment a dangling reference lands, and an open issue with no action is the drift this repo has just finished ruling against elsewhere. The thread stays searchable, and the convention now lives where an author will actually meet it.

Applied across the three places it reached: #23 (QEP-1 v3 is three changes), #18 (QEP-6's precedence clause and cross-repo handover item removed), QuantEcon/status-projects#140 (ownership recorded from the consuming side).