QEP-2 appendix implies version-hash pinning exists at v0 — clarify the prose, or amend QEP-1 to stamp from v0

[mmcky]

Found during the 2026-08-27 planning pass on QuantEcon/cli#20 (the QEP-2 label-migration tracker).

QEP-2's Machine-readable appendix section says: "under QEP-1's versioning rule, a change to a machine-readable appendix is a substantive amendment that bumps this QEP's version, and version-hash (a commit hash) pins both files at once." Per QEP-1 (v2), an accepted-but-never-amended QEP is implicitly v0 and carries no version-hash — the field is stamped only from v1. So today nothing in QEP-2's frontmatter pins the pair, and tooling (qe, see QuantEcon/cli#12) pins by a plain commit SHA of this repository chosen on the consumer side. The sentence describes machinery that does not exist yet at v0.

Two resolutions, either of which settles it:

A. Editorial clarification only (keep current semantics)

Add one sentence to the appendix section: at v0 the anchor is a plain commit SHA of this repository, chosen and recorded by the consuming tool; version-hash names the substantive revision from v1 onward. Editorial under QEP-1's substantive/editorial rule — no version bump, and no change to QEP-1.

B. Stamp from v0 (recommended)

Amend QEP-1 (substantive, v2 → v3) so every accepted QEP is stamped version: 0 + version-hash at acceptance, with the hash moving on every later commit that touches the QEP — exactly the behaviour v1+ already has. QEP-2's sentence then becomes true as written, and every QEP carries a machine-verifiable reference from day one.

For: the tooling contract becomes uniform (consumers always read version + version-hash, no absent-means-v0 special case); documents are self-describing (a migration report can cite "QEP-2 v0 @ abc1234" from the document itself, and a consumer can cross-check that the revision it fetched matches the revision the document claims to be); editorial changes at v0 become visible to machines (the hash moves — the "something changed, re-check" signal a machine-consumed appendix wants); and the stamp machinery already exists — the change is removing the v0 — no version to stamp skip in stamp.mjs, inverting one qep-checks rule ("starts unversioned" → "starts at v0"), and updating the README/pill rendering.

Against: absent-means-never-amended currently carries information for free, and one-off decision QEPs that will stay v0 forever gain a stamp line and a v0 pill that some will read as noise; acceptance merges now always trail a bot stamp commit; and it does not remove the consumer-side pin — qe must still choose a SHA to fetch, so the v0 hash adds cross-check value rather than replacing anything. It is also worth stating plainly in the amendment that version-hash is a historical anchor, not a file checksum — the stamp commit itself post-dates the hash it writes, so the field names the revision, it does not hash the bytes (true at v1+ today; v0 stamping widens the audience that might misread it).

Decisions the amendment would need to make: the backfill rule for already-accepted v0 QEPs — recommend stamping each with the most recent commit that touched it at the time the policy lands, which is mechanical and consistent with the existing rule that editorial commits move the hash; and presentation — recommend showing v0 honestly in the README column and pill rather than –, since it now names an anchored revision.

Either way, the CLI is unaffected: QuantEcon/cli#12 pins by repository SHA regardless. Under B the migration report additionally records the standard's self-declared version/version-hash and flags any mismatch with the fetch pin.

If B is adopted, the QEP-2 appendix section still wants a one-line editorial touch ("from acceptance, version-hash anchors…") — folded into the same round.

---

Generated by Claude Code

[mmcky]

Resolution B adopted pending review: the QEP-1 v3 amendment is drafted at #23 (one-week comment window, decision deadline 2026-09-03 — the same amendment makes one week the default window). The machinery follow-up — stamp action, checks, backfill of merged v0 QEPs, README note, AGENTS.md — and QEP-2's one-line editorial touch land after acceptance, per adoption entry v3. This issue stays open until that follow-up completes.