QEP-2: the labels lockstep stops short of the `qe` manifest — four labels have already drifted

[quantecon-services]

Closed 2026-09-08 as already solved — this issue was filed on stale evidence. The mechanism it asks for exists, is more careful than what it proposed, and the drift it reported is closed. The original text is kept below the line for the record.

What is actually in place

QuantEcon/cli vendors the appendix rather than keeping its own manifest:

• src/qe_cli/data/qep-0002-labels.yml — the companion, verbatim.
• src/qe_cli/data/qep-0002.pin — the qeps revision it was taken from.
• src/qe_cli/schema_pin.py + .github/workflows/schema-freshness.yml — a weekly job that compares the vendored copy against QuantEcon/qeps and fails when it falls behind (cli#38, cli#48).

All four labels this issue says were skipped are present in the vendored copy: infrastructure, discuss, security, refactor — 22 labels in total. The gap was the plugin-era manifest, and vendoring is what closed it. My evidence came from a status-projects migration note describing qe 0.2.0 and I did not check whether it still held. It does not.

Verified on 2026-09-08 by blob hash, the same comparison the check itself makes:

vendored : 161cd74627dede8f8b3e6912cb84c1745d1e01e0
upstream : 161cd74627dede8f8b3e6912cb84c1745d1e01e0
at pin   : 161cd74627dede8f8b3e6912cb84c1745d1e01e0
pin      : cfbc00ea8f8255a7d2c107b7f0a1d1b5c1855852

All three agree, so diagnose() returns no findings.

Two things the implementation gets right that this issue got wrong

It compares content, not commits. I would have compared the pinned revision against main and been wrong. schema_pin.py says why:

"qeps main moves whenever any QEP is edited, so a commit comparison would fail on changes that have nothing to do with labels, and a check that cries wolf gets muted — which is how a freshness guard dies."

Note the consequence for this repository: the pin above sits at cfbc00ea, which predates QEP-3's merge, and that is correct and quiet — QEP-3 did not touch the appendix, so the blobs still agree. A commit-based check would be red right now for no reason.

It diagnoses a three-way relation, not two comparisons. diagnose() takes vendored, upstream and at-pin, because the remedies differ and pairwise branching gets the common case backwards — a file re-vendored without a pin bump looks like a local hand-edit, and the fix for a hand-edit (restore from the pin) would undo the update. My proposal had a single diff check and would have prescribed exactly that wrong remedy.

And the freshness check is deliberately out of the PR loop, so the test matrix stays offline and fork-safe — network-dependent by nature, weekly by design, with a comment explaining why there is no concurrency block (a cancelled run is grey and notifies no one, so the week's verdict would vanish rather than fail).

Closed as not planned, and the consumer-side half is done separately

Nothing to build. The one real residue was on the consumer side and is fixed in QuantEcon/skills#79: qe/references/audit/quantecon-context.md still told agents QEP-2 was a Draft and to withhold non-canonical labels post-acceptance, which suppressed correct recommendations. That passage now names the companion as the authority and records how the CLI tracks it. (An earlier revision of that PR repeated this issue's stale drift claim; it has been corrected.)

---

Original text, as filed

Summary

QEP-2's lockstep check keeps qep-0002-labels.yml honest against QEP-2's own tables. It stops one link short: the qe CLI's label manifest is a third copy of the same set, and it has already drifted from the companion file with nothing to catch it.

Motivation

.github/scripts/check-labels.mjs keeps the companion in lockstep with the QEP's tables — name, colour, description, scope — and refuses a change to the companion on an Accepted QEP without a version bump. That is a genuinely good pattern and the model for every machine-readable appendix in the repo (QEP-4 proposes the second instance, qep-0004-automations.yml).

But the chain has a third link nobody checks. Field evidence from the projects dashboard's label migration: qe gh labels sync --profile software --prune brought 16 of 20 labels, and four had to be created by hand from qep-0002-labels.yml — infrastructure, discuss, security and refactor — because qe 0.2.0's manifest skips them. QEP↔companion agree; companion↔implementation silently do not, and the failure surfaces as a human noticing four missing labels in a downstream repository.

This is distinct from #21 (this repo's own labels predate QEP-2 and are unmigrated), which is about the standard's home repo rather than the tool that applies it.

Why does this need a QEP?

Affects more than one repository — the label set is org-wide and its implementation lives in QuantEcon/skills.

Proposed change

1. Make the companion file the only manifest. The qe labels command reads qep-0002-labels.yml directly rather than carrying its own copy — the file is in a public repository and the tool already knows the QEP. This removes the third copy rather than checking it, which is the same instinct QEP-2's own appendix section applies to the QEP-vs-companion pair.
2. Failing that, check the drift. A check in QuantEcon/skills that diffs its manifest against the companion, so a skipped label is a red build rather than four hand-created labels in a downstream repo.
3. Note it in QEP-2's appendix section either way: a consumer pins version and verifies against the anchor, and the appendix is the authority over any consumer-side copy. (QEP-2 appendix implies version-hash pinning exists at v0 — clarify the prose, or amend QEP-1 to stamp from v0 #22 is settling what the anchor is at v0; this is about which file wins, not which hash.)

No amendment to the label set itself is proposed here, so nothing in this depends on #16.