QEP-0002 audit + consolidated design decisions (pre-merge)

[mmcky]

Consolidated decision record for QEP-0002, combining the pre-finalisation audit of #2 with the design decisions from follow-up discussion. The core label set already has team consensus (meta#324); the refinements below are to be folded into the PR draft and put to the team when we propose to merge — not a separate review round now.

Title

Rename the QEP from "Standard GitHub Label Set and Labelling Policy" to "QuantEcon GitHub Label Policy" — it is now a single, org-wide, unified policy rather than a lecture-scoped standard.

Scope — one unified, Living policy

(This supersedes the earlier "QEP-2 = lecture-only, software = separate QEP" framing.) QEP-0002 is a single QuantEcon-wide label policy covering every tier in one document, with the tier structure as its organizing spine:

• Core (18) — meaningful on any repo; also the org-level default for new repositories.
• Lecture extension (new-lecture, editor) — lecture repos only.
• Software extension (below) — library / tooling repos only.

Tooling applies the right slice per repo type. The lecture pilot can run during review (a pilot is an experiment, not a ratified standard), so unifying does not block the lecture rollout.

Software extension (minimal)

From a usage survey of QuantEcon.py, QuantEcon.jl, quantecon-book-theme, GameTheory.jl: most non-core labels already map onto the standard — CI→infrastructure (25 uses, validating the split), wishlist→low-priority, beginner→good first issue, status labels→native Draft/review, docs→documentation, and one-repo/event labels (python-compat, javascript, hacktoberfest, detailed-review)→prune-local. The genuinely homeless, orthogonal concepts — minimal set:

Label	Rationale (usage on QuantEcon.py)
performance	"Correct but too slow" — no home in bug/enhancement/maintenance; standard for any numerical library (8).
breaking-change	Semver / compatibility signal; matters for the versioned quantecon-book-theme dependency too (5).
upstream	"Blocked on a NumPy/JAX/SciPy upstream fix" — native issue-dependencies are intra-org and can't express this (5).

Colours TBD — distinct from the (now crowded) palette; do not reuse the repos' current values (performance is yellow=maintenance, upstream is grey=automation in our scheme).

tests (51) and refactor (40) — the swing labels. These are the highest-used non-core labels on QuantEcon.py, but unlike the three above they have a plausible home in maintenance. Decision: fold them into maintenance for the pilot; if the QuantEcon.py maintainers feel the loss, promote them — the pilot decides. (Same logic that split infrastructure back out: honour a distinction the team actively makes, but only once the pilot confirms it.)

Update mechanism — Living + versioned

• QEP-0002 is a Living standard, amended in place via PR.
• Versioned snapshots: QEP-0002-v1, QEP-0002-v2, … are immutable; QEP-0002 is the stable reference that always shows the latest. The published site gets a version dropdown, defaulting to latest. A qeps/qep-0002/ folder holds the version files — start simple (folder + version files + an index rendering latest); add an automatic switcher only if it earns its keep.
• Requires a small QEP-1 amendment to add an "Active / Living" status (current statuses: Draft / Accepted / Rejected / Withdrawn / Superseded). Versioning applies to Standard/Living QEPs only; reserve Superseded for a wholesale rethink.

Source of truth — self-contained document + normative machine block

• The QEP document is the sole, self-contained source of truth; tooling complies with QEP-0002. The cli does not keep a duplicate labels.yml — the earlier plan to edit cli/src/qe_cli/data/labels.yml is dropped; qe gh labels sync reads the schema from the QEP.
• Add a machine-readable Appendix (a fenced block) as the normative definition tooling consumes; the prose tables are the human view. If the two ever disagree, the Appendix block wins.
• Sync enforcement: a CLAUDE.md instruction to verify the table ↔ Appendix block on every edit, plus a tiny CI parity check in qeps (cheap and rarely fires, since the document is static) as the durable guarantee. (Zero-drift alternative, not needed now: generate the human table from the block at build time.)

QEP document edits (carried over from the audit)

• infrastructure colour #006b75 → #1d3c78 (slate-blue; clear of help wanted teal). Refine on sight.
• Clarify new-lecture under the "one Type label" rule (treated as a Type label — use instead of enhancement).
• State that the grey Automation/Meta family is intentionally near-identical (disambiguated by text, not colour).
• Add the Dependabot exemption sentence (dependencies alone, no automated).
• Rollout: pilot lecture-python-programming + QuantEcon.py (both tiers, during review), then widen to all lecture-* repos and the software repos.

Automation — a separate Living QEP

The label definitions (automated, broken-links, build-failure, dependencies) stay in QEP-0002. A separate Living automation QEP governs bot behaviour — operational, evolves with the tooling, with the actual label generation tracked by the tool itself. Convention: a bot tags automated + a diagnostic, and an origin label (the action's name) only where a consumer routes on it — today that is exactly translation: action-translation (origin) + sync (diagnostic) + automated. Not every bot gets an origin label by default (that would re-grow the namespace).

Implementation follow-ups (rollout, not document edits)

• action-check-warnings emits execution / python-warnings (which exist nowhere) → fix to automated + build-failure.
• action-link-checker is missing automated → fix to automated + broken-links.
• action-activity-report (tools/highlights.py): drop dead aliases (feature, priority: high, chore, docs), correct the now-false "infrastructure no longer exists" note, and decide discuss / low-priority handling.

Decisions captured

#	Decision
1	Unified policy — core + lecture + software in one Living QEP-0002, titled "QuantEcon GitHub Label Policy".
2	Software extension (minimal) = performance, breaking-change, upstream; tests/refactor → pilot decides.
3	Living + versioned — vN snapshots, QEP-0002 = latest reference, site dropdown; needs a QEP-1 "Active" status.
4	Source of truth = self-contained document + normative machine-readable Appendix; cli complies, no duplicate.
5	Separate Living automation QEP for bot behaviour; label definitions stay in QEP-0002.
6	Pilots = lecture-python-programming + QuantEcon.py, run during review.
7	infrastructure colour = #1d3c78 (refine on sight).

---

Core set: team consensus at meta#324. Next step (author): fold these into the PR draft (#2); broader team review at merge-proposal time.