QEP-1 v1: version-defined living standards (amend in place, not supersede)

[mmcky]

Implements the design discussed and agreed with @jstac in #4.

What this does

Today QEP-1 freezes a QEP the moment it is Accepted — the only way to change it is to supersede the whole document with a new one. That suits a one-shot decision, but not a living standard (the label policy, a future style guide, this process itself) that evolves in small, frequent steps.

This PR lets an accepted QEP be amended in place under the same lazy-consensus review. The first substantive change after acceptance gives the QEP a version — v1, then v2, and so on — and routine evolution bumps that number instead of spawning a superseding document. A reader always sees one current standard rather than a chain of replacements.

What deliberately stays the same:

• status still answers only was this agreed? No new status word is added — living-ness rides on version instead. This sidesteps PEP's Active and the MEP clash where Active means the opposite (frozen for voting).
• Superseded is kept, but only for a genuine wholesale rethink — never routine maintenance.

Two supporting changes come along for the ride:

• type becomes a minimal content taxonomy: standard / process / informational.
• The change record is git itself — surfaced on the rendered site by the theme's git-history feature — rather than a hand-maintained changelog that would drift.

Adopting this is QEP-1's own first substantive amendment, so QEP-1 becomes v1: the document is a worked example of the mechanism it introduces.

How a revision is anchored

Each QEP's version is paired with a version-hash key in the frontmatter that pins the revision to an exact commit:

version: 1
version-hash: a1b2c3d  # stamped by CI; do not edit

version-hash is a real key, not a YAML comment, so a standard parser keeps it (a comment would be silently dropped). CI stamps it at merge — a commit cannot contain its own hash — so authors never write it by hand. Tooling that pins a standard reads version and verifies against version-hash.

Substantive vs editorial

This is an author/reviewer call — CI does not classify it — and it decides whether the number moves:

• Substantive — any change to normative content (a rule, a value, a table row, a machine-readable appendix) → bump version; commit QEP-N vM: ….
• Editorial — no change to normative content (typo, wording, formatting, link) → version unchanged; commit QEP-N: ….

Changes

Area	Change
qeps/qep-0001-purpose-and-process.md	The amendment itself: the version field (implicit v0) and its version-hash anchor, the substantive/editorial rule, amend-in-place vs supersede, squash-merge-only, QEP-N vM: commit subjects, the standard/process/informational type taxonomy, an Automation section, and git-as-history. Sets type: process, version: 1.
qeps/template.md	Lowercase type enum; a comment noting version (and its CI-stamped version-hash) appears on first amendment, while a new QEP stays unversioned (v0).
README.md	Type and Version columns added to the index; QEP-1 row → process / v1.
AGENTS.md	Author-side operational guidance: substantive vs editorial, the version bump, commit subjects, squash-merge, and what CI does vs what the author does.
.github/scripts/	qeps.mjs (frontmatter + README-table parsing), stamp.mjs (post-merge: write version-hash, sync README), check.mjs (per-PR checks). All version parsing is scoped to the frontmatter block, so a version: example in a QEP body is never mistaken for the real field.
.github/workflows/	stamp-version.yml (post-merge: stamp the merged hash, sync README) and qep-checks.yml (per-PR: version increments by at most one, README↔frontmatter parity).

⚠️ One manual step required

The model assumes squash-merge only (one amendment = one commit). That is a repository setting CI cannot apply. After this merges, please set in Settings → General → Pull Requests: enable Allow squash merging, and disable Allow merge commits and Allow rebase merging. I left the live repo settings untouched, as agreed.

Validation

• The per-PR check (check.mjs) passes locally, and both workflow YAMLs parse.
• The stamp/parse logic — including the new version-hash key — is covered by round-trip checks: first-stamp insertion, re-stamp replacement, idempotence, and confirming a version: / version-hash: example inside a QEP body is never rewritten.
• The original v1 design was put through an adversarial multi-agent review against Process: version-defined living standards for continuously-maintained QEPs #4 (faithfulness, cross-file consistency, CI/script correctness, rendering); confirmed findings are folded in.

Decision

Per QEP-1, this is decided by lazy consensus at a deadline. Suggested comment window: two weeks (by 2026-07-08) — adjust as you like.

[jstac]

I fully agree with this. Many thanks @mmcky , very good call.

My only complaint is that the "What this does" section reads as Claude mumbo-jumbo that a really clear sequence of rules / steps. Maybe Claude could have another go with the aim of improving clarity --- make it like an algorithm / proof, not a word salad.

[mmcky]

Thanks @jstac -- sorry this was supposed to be in DRAFT still (not ready for review). But I will tidy up the language, check the new automation code and then will merge based on the principle we want to capture.

[mmcky]

Addressed the review in 791af8c (and untracked the stray pr-5-review.md working notes):

• QEP-1: QEP Purpose and Process #1 — stamp.mjs detects a merge commit and diffs against the first parent (HEAD^1 HEAD), so stamping no longer silently no-ops if a QEP PR is merged as a merge commit instead of squashed.
• QEP-2: Standard GitHub Label Set and Labelling Policy #2 / QEP-1 v1: version-defined living standards (amend in place, not supersede) #5 — check.mjs now errors if a versioned QEP drops its version field, and requires a brand-new QEP to start unversioned (v0).
• QEP-0002 audit + consolidated design decisions (pre-merge) #3 — check.mjs validates type/status against their allowed values.
• #8 — a v0 README Version cell tolerates a hand-typed ASCII - / empty pre-merge (normalised to the en dash at stamp time), so it no longer blocks the PR with a look-alike parity error.
• #6b — the stamp workflow pushes explicitly with git push origin HEAD:main.
• #7 — the type/version pills and git-history-dropdown claims are now contingent on the QuantEcon theme (the site renders with book-theme today); the README columns remain the always-true part.

All eight check.mjs scenarios pass in an isolated synthetic repo, and check.mjs passes on the branch.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.