Build `qe` CLI with a `gh` module for label management

[mmcky]

Summary

Build a qe command-line tool with a gh module to manage GitHub
configuration for QuantEcon repositories — starting with labels. The tool
should hold a schema of the labels we use as a single source of truth, and
provide tooling to apply that schema to a given repo (and across repos).

The label set below is a starting point only. We will run team-focused
surveys to decide the best set before treating any of it as final.

Motivation

Labels have drifted badly across our lecture repos — roughly 70 distinct label
names across six repos (lecture-python-intro, lecture-python-programming,
lecture-python.myst, lecture-python-advanced.myst, lecture-dp,
lecture-jax), with only bug, in-work, and ready present in all six. There
are near-duplicate variants (automated issue / automated-issue / automated,
linkchecker / broken-links, high-priority / high priority), redundant
triple-tagging by bots, and stale one-off project labels.

We want one shared, consistent vocabulary and a repeatable way to apply and
audit it, owned by a first-party tool rather than ad-hoc scripts or a
third-party action.

Proposal: qe gh labels

A standalone Python CLI that shells out to gh for all GitHub calls, so
it inherits existing gh auth (no PAT to store or rotate) and keeps GitHub's own
CLI doing the API work.

qe gh labels sync     # apply the schema to one/many repos  (--repos --prune --dry-run)
qe gh labels check    # read-only drift report; non-zero exit if a repo diverges (CI-friendly)
qe gh labels export   # dump a repo's current labels to a schema file (bootstrap / backup)

1. A label schema (single source of truth)

A version-controlled manifest — list of labels with name, color,
description, and optional aliases (old names to rename from, preserving
the issue/PR tags on existing items). Example shape:

- name: "enhancement"
  color: "a2eeef"
  description: "New content or an improvement to existing material"
  aliases: ["improve", "new lecture", "lecture"]

2. Tooling to apply it to a repo

Per label, per repo: update if the canonical name exists; else rename the first
existing alias (history-preserving); else create. With --prune, labels not in
the schema (and not consumed as an alias) are removed, so a repo converges to
exactly the schema. --dry-run previews every change.

Starting-point label set (PROVISIONAL — pending team surveys)

A 16-label set proposed as a discussion starting point, grouped by dimension.
Colour conveys meaning where useful (priority = heat scale, automation = grey);
the PR lifecycle (WIP → ready → in review) is left to native GitHub PR
features (Draft → Ready for review → review state) rather than labels.

Group	Labels
Type	bug, enhancement, documentation, maintenance, question
Community	good first issue, help wanted
Priority	high-priority, low-priority (unlabelled = normal)
Workflow	do-not-merge
Automation/CI	automated, broken-links, build-failure, dependencies
Meta	duplicate, wontfix

This is a conversation starter, not a decision. The point of the schema +
tooling is that whatever the team lands on becomes trivial to apply everywhere.

Open questions for the team

• What is the right label set? Run a short survey of maintainers across the
  lecture repos. Which dimensions matter (type / priority / area / status)? Do we
  want an area:* split (content vs code)? Keep a ready label, or rely on the
  native Review-requested dashboard?
• Scope of the schema — one global set for all lecture repos, or a base set
  plus per-repo extensions?
• Automation contract — our label-applying actions (action-link-checker,
  action-check-warnings, action-style-guide) should emit only canonical
  labels; fold this check into qe gh bots check later.
• Distribution — uv tool install / pipx from a new QuantEcon/qe-cli?

Suggested next steps

• Agree this direction and create QuantEcon/qe-cli.
• Define the schema format and commit a first labels.yml (the provisional
  set above, explicitly marked draft).
• Implement qe gh labels sync / check / export with --dry-run.
• Run a maintainer survey to finalise the label set.
• Apply the agreed schema across all lecture repos; wire check into CI as a
  drift guard.

---

Context: this consolidates a label-unification audit + proposal already drafted
(full inventory, migration map, and a working reference implementation of the
sync engine). Happy to attach those to the qe-cli repo once it exists.

[mmcky]

Extending the scope: repo settings and profiles

Labels are really one instance of a more general need — keeping a class of repos
configured consistently. Two additions worth designing for from the start:

1. Manage repo settings too, not just labels. Things we want uniform across
lecture repos but currently set by hand (and forget on new repos):

• Automatically delete head branches on merge (delete-branch-on-merge)
• Allowed merge types (e.g. squash-only vs merge commits)
• Issues / Wiki / Projects enabled
• Allow auto-merge, allow update branch
• Default branch, branch-protection on main
• Dependabot / security alerts

Most of these are one gh repo edit flag away (--delete-branch-on-merge,
--enable-squash-merge, --enable-merge-commit, --enable-issues, …), and the
rest are gh api calls — so they fit the same "shell out to gh" design as the
label tooling.

2. A "QuantEcon profile" per repo type. Rather than configure each repo
individually, define named presets keyed to repo type and apply them:

qe gh profile apply lectures   QuantEcon/lecture-jax
qe gh profile apply software   QuantEcon/qe-cli
qe gh profile check  lectures  QuantEcon/lecture-python.myst   # drift report

A profile is just a composition of the building blocks: a label schema +
repo settings (+ later: dependabot config, standard workflows, branch
protection). For example:

	lectures	software
Label schema	the lecture set (this issue)	a dev set (adds e.g. breaking, semver:*, review labels)
Delete branch on merge	✅	✅
Merge strategy	squash	squash + merge
Branch protection on main	required checks (build)	required checks + review
Dependabot label	dependencies	dependencies

Candidate types: lectures, software, maybe book and translation.

How it composes. The label schema we're defining here becomes the
labels: section of the lectures profile — nothing is thrown away, it just
gains a home alongside the other settings. Profiles live in qe-cli as
version-controlled YAML, so "what does a QuantEcon lecture repo look like" is a
single reviewable file, and qe gh profile apply makes onboarding a new repo (or
re-aligning an old one) a one-liner.

Suggested command surface, building on the qe gh labels commands above:

qe gh settings sync   <repo> [--profile lectures]   # apply repo settings
qe gh profile apply   <type> <repo>                 # labels + settings (+ more)
qe gh profile check   <type> <repo>                 # read-only drift report
qe gh repo onboard    <type> <repo>                 # profile + first-time setup

Same caveats as labels apply: --dry-run first, profiles are the agreed team
standard (subject to the same surveys), and per-type so we don't force one shape
on every repo.

[mmcky]

Complete catalogue: label-related resources across QuantEcon

An audit of the whole organisation (issues, PRs, org settings, docs, code) so
this issue can act as the single consolidation point — we resolve once, then
tidy everything against the decision.

1. Issues & PRs — the discussion history

Ref	State	Date	What it is
#178	OPEN	Aug 2025	GitHub Org – Unified Labels. First proposal (status / priority / type / skill groups). Approved in discussion. Outcome: the org-level default labels were updated (see §2) — but org defaults only apply to new repos, so a sync script was needed (#183).
#182	closed (completed)	Aug 2025	Asked Copilot to survey lecture repos and suggest labels → spawned PR #183.
#183	closed, not merged	Aug 2025	Copilot PR: 36-label / 8-category spec, scripts/apply-unified-labels.py, implementation guide. Branch deleted; files only on PR head commit e14896f. Nothing landed on main.
#290	OPEN	Feb 2026	Standardized Labels for QuantEcon Repositories. Refined ≤15 set building on #178 (status: / priority: / skill: prefixes, content type), wider repo scope (incl. lecture-julia.myst, lecture-datascience.myst, QuantEcon.py, QuantEcon.jl, themes, action repos), 3-phase rollout plan.
#323	OPEN	Jun 2026	This issue — qe CLI with schema + tooling, plus the repo-settings / profiles extension in the comment above.
QuantEcon/QuantEcon.manual#90	OPEN	Jun 2026	Reset/standardize default labels; tracks updating the operations-manual team/tags page figure (quantecon-github-tags.png) once the set is final.

Four open issues currently cover overlapping ground: #178, #290, #323, manual#90.

2. Live org-level configuration

• GitHub organization default labels were updated in Aug 2025 (per GitHub Org - Unified Labels #178).
  They auto-apply to new repos only. Evidence of the current set:
  lecture-dp (created 2026-01-14) inherited exactly these 13:
  blocked, bug, duplicate, editor, good first issue, help wanted,
  high priority, in-work, maintenance, question, ready, testing, wontfix.
• ⚠️ These include variants a recent 6-repo audit flagged as drift sources
  (high priority with a space; status labels). Whatever set we decide, the
  org defaults must be updated to match — otherwise every new repo
  reintroduces drift on day one.

3. Tooling that APPLIES labels (must conform to the final set)

Tool	Labels it applies today
action-link-checker	bug, documentation, broken-links (older configs: report, automated issue, linkchecker)
action-check-warnings	bug, execution, python-warnings
action-style-guide	automated, style-guide, review
Dependabot configs (per lecture repo)	dependencies, github_actions, conda

4. Tooling with its OWN label namespace (suggest: leave project-owned)

Tool	Namespace
action-translation	translate, translate:{category}, translate:{language}, translation-sync-failure, auto-merged, … (targets translation fork repos)
contractor-payments	timesheet, milestone-invoice, reimbursement, pending-review, parse-error, submit, submission, processed (scripts/setup_labels.py). Its onboarding script also sets delete_branch_on_merge=true — existing prior art for the "profiles" idea above.

5. Tooling that READS labels (benefits from standardization)

• action-weekly-report —
  merged PR QuantEcon/action-weekly-report#2 groups merged PRs by label in
  its highlights template (the motivating automation case in Standardized Labels for QuantEcon Repositories #290).

6. Sync implementations — three generations exist

Implementation	Where	Status
apply-unified-labels.py (36-label set)	#183, commit e14896f	unmerged, orphaned
apply-labels.sh + a composite-action prototype (manifest with aliases for history-preserving renames, --prune, --dry-run)	drafted locally alongside this issue	working, dry-run tested against live repos; not yet pushed
qe gh labels sync / check / export (Python/Typer)	local qe CLI v0	implemented with tests; not yet pushed — the natural home per this issue

7. The substantive decision the team survey must settle

#290 and this issue's starting set disagree on exactly two things (everything
else is reconcilable naming):

	#290 (Feb 2026)	#323 starting set (Jun 2026)
PR lifecycle	labels: status: in-work / ready / blocked / testing	native GitHub (Draft → Ready for review → review state); only do-not-merge
Skill labels	skill: editor, skill: domain	none
Prefixes	status: priority: skill:	none — colour carries meaning
Automation labels	out of scope ("managed by the actions")	in scope: automated, broken-links, build-failure, dependencies

8. Suggested tidy-up once a decision lands

1. Consolidate: make this issue the canonical one; close GitHub Org - Unified Labels #178 and Standardized Labels for QuantEcon Repositories #290 with
   a pointer here; keep manual#90 as the docs-update task.
2. Decide the set (team survey), then in order:
   1. update org-level default labels to match (stops day-one drift);
   2. apply to repos via qe gh labels sync;
   3. update the label-emitting tools (§3) + Dependabot configs;
   4. update the manual tags page + quantecon-github-tags.png (closes manual#90).
3. Retire duplicates: note on Set up unified GitHub labels for QuantEcon lecture repositories #183 that its artifacts are superseded; fold
   the drafted sync tooling into qe-cli.

[mmcky]

Proposed QuantEcon label set — 18 labels, with rationale

Distilled from all the resources catalogued above (the 6-repo audit, #178, #290,
the Aug-2025 org defaults, and this issue). The three points where earlier
proposals disagreed are resolved as follows:

• Editorial stage: keep a single editor label (the QuantEcon-specific
  final editor sign-off queue — already in the org defaults). Ordinary review
  uses native Draft → Ready for review → review requests.
• Status labels (in-work, blocked, testing): dropped in favour of
  native GitHub features (Draft PRs, linked blocking issues, do-not-merge).
• Skill labels (skill: domain): dropped — help wanted plus a comment
  naming the expertise covers it.

Design principles: small enough to memorise; unlabelled = "needs triage, normal
priority"; one concept one label; colour carries meaning (priority = heat
scale, automation = quiet grey, editor = action green, do-not-merge = stop
red, type/community keep GitHub-conventional colours); bots follow the same
vocabulary (automated + exactly one diagnostic).

Scope — where these labels apply

The 18 decompose into a universal core (16) plus a lecture extension (2)
(new-lecture, editor — meaningful only where the lecture editorial workflow
runs):

Tier	Repos	What applies
1 — Lecture repos (synced + pruned)	lecture-python-intro, lecture-python-programming, lecture-python.myst, lecture-python-advanced.myst, lecture-dp, lecture-jax; candidates to confirm: lecture-julia.myst, lecture-datascience.myst, lecture-stats, continuous_time_mcs, lecture-wasm	all 18 (= the lectures profile)
2 — Software / tooling (later phase, via profiles)	QuantEcon.py, QuantEcon.jl, quantecon-book-theme, action-*, qe-cli, …	core 16 baseline
3 — Project-owned (never synced)	meta (discuss/project/education stay), translation forks (translate:*), contractor-payments, action-activity-report	own namespaces; share core names where concepts overlap
Out of scope	*.notebooks (build artifacts), *.theme, dormant repos	none

Org-level default labels = the core 16 (they seed every new repo regardless
of type); the lecture pair is added by the lecture-profile sync. meta keeps
its coordination labels but gets two cleanups: align inherited variants
(high priority → high-priority, drop in-work/ready) and retire legacy
weekly-report/monthly-report.

Type — what kind of work is this? (apply one at triage)

Label	Colour	Description	Rationale — when to apply
bug	🟥 #d73a4a	Something is wrong or broken in a lecture or build	The lecture says or does something incorrect: wrong maths, erroring code, broken rendering. Not "could be better" (→ enhancement), not bot-found link/build issues (→ automation labels).
enhancement	🟦 #a2eeef	Improvement to existing material	Anything that makes existing lectures better without something being broken: new exercise, clearer exposition, better figures. The most common human-opened item.
new-lecture	🟦 #0537E9	A new lecture (the marquee outcome)	A brand-new lecture — proposed, in progress, or shipped. Separate from enhancement because new lectures are QuantEcon's headline outcome: gives activity reports and year-in-review queries a deterministic signal, and it was the most human-applied content label in the historical audit. Apply instead of enhancement, not alongside.
documentation	🟦 #0075ca	Repo docs and contributor meta (not lecture content)	READMEs, CONTRIBUTING, templates — about the repo. Deliberately narrow: the lectures themselves are not "documentation"; changes to them are enhancement or bug.
maintenance	🟨 #fbca04	Housekeeping: refactors, tooling, infra, style, environments	Work a reader never sees: CI, environment upkeep, refactors, style/theme conformance. Rule of thumb: if the rendered lectures look identical afterwards, it's maintenance.
question	🟪 #d876e3	A question or discussion thread	Raised for discussion rather than action. When it turns into agreed work, swap for the work's type.

Priority — how urgent? (heat scale; unlabelled = normal)

Label	Colour	Description	Rationale — when to apply
high-priority	🟧 #d93f0b	Address soon — needs attention within days	Visibly broken published content, a build/deploy blocker, anything to pick up before the routine queue. Label only the outliers — if everything is high-priority, nothing is.
low-priority	🟩 #c2e0c6	Nice to have, no time pressure	Agreed to be worth doing, explicitly fine to sit. Also home for "future / someday" ideas. Two levels only — no medium (everything migrates to the middle).

Editorial — the QuantEcon review stage

Label	Colour	Description	Rationale — when to apply
editor	🟩 #0e8a16	Requires editor review — final sign-off stage	Apply at the handoff: team review done, series editor gives final sign-off — the one stage GitHub can't express natively. The editor's cross-repo queue is org:QuantEcon is:open label:editor. Remove on sign-off. Don't apply before team review completes (that's what review requests are for).

Workflow guard

Label	Colour	Description	Rationale — when to apply
do-not-merge	🟥 #b60205	Must not be merged yet (hold, pin, experiment)	The one PR state with no native equivalent: may look mergeable — even approved — but must be held (cross-repo coordination, pinned experiment, awaiting external release, test-only). Reviewers review normally but never merge; remove when the hold lifts.

Community — invitations to contribute (GitHub-canonical names)

Label	Colour	Description	Rationale — when to apply
good first issue	🟪 #7057ff	Self-contained and friendly to newcomers	Only when genuinely self-contained: clear acceptance criteria, no deep context, a pointer to the right file. Mislabelled "first issues" burn newcomers. Feeds GitHub's contribution-discovery surfaces — keep exact name.
help wanted	🟩 #008672	Maintainers would welcome outside help	The team would value outside help, including experienced contributors. Also the signal for work needing domain (econ/math) expertise — pair with a comment naming what's needed.

Automation — raised or managed by machines (quiet grey; applied by bots, not humans)

Label	Colour	Description	Rationale — when to apply
automated	⬜ #ededed	Opened by a bot or scheduled workflow	The bot stamp. Every bot-created issue carries this plus exactly one diagnostic — replacing the historical triple-tagging (report + linkchecker + automated issue). Filter label:automated = "everything the robots raised".
broken-links	⬜ #dddddd	Link checker found dead links	Applied by action-link-checker alongside automated.
build-failure	⬜ #cccccc	Notebook execution, build, or warnings failure	Applied by action-check-warnings (and execution/build checks) alongside automated. The failing CI job name identifies the tool — no per-tool labels.
dependencies	⬜ #bdbdbd	Dependency or environment update (pip, conda, actions)	The single label on every Dependabot PR regardless of ecosystem (replaces github_actions / conda). One filter shows the whole upkeep queue.

Tools with purpose-built namespaces keep them on their own repos (action-translation's translate:*, contractor-payments' workflow labels, action-activity-report's status-report) — the rule: a label belongs to the repo it lands on.

Meta — triage outcomes (apply when closing)

Label	Colour	Description	Rationale — when to apply
duplicate	⬜ #cfd3d7	Already tracked elsewhere	Apply when closing; link the surviving issue in a comment.
wontfix	⬜ #ffffff	Decided not to act	Apply when closing with one sentence on why (out of scope, by design, superseded) — the paper trail for "we considered this". Absorbs invalid.

---

What we deliberately don't label

You might reach for…	Use instead
in-work / WIP	Draft PR
ready / in-review	Native Ready for review + review requests
blocked / on-hold	Draft + link the blocking issue ("Blocked by #N")
testing	Draft + do-not-merge
medium-priority / urgent	no label / high-priority
skill: editor / skill: domain	editor / help wanted + comment
project labels (reading-group-2024, jax-conversion, …)	Milestone or Project
per-tool labels (colab, jupyterbook-latex, …)	build-failure

The one behavioural ask: open work-in-progress PRs as Drafts.

Adoption order (once agreed)

1. Freeze this set and the Tier-1 repo list (team review of this comment).
2. Update the org-level default labels to the core 16 — org defaults seed every new repo regardless of type; without this, every new repo reintroduces drift on day one.
3. Sync the Tier-1 lecture repos to the full 18 via the schema tooling (qe gh labels sync), renaming historical variants in place so issue/PR history is preserved.
4. Update the label-emitting actions + Dependabot configs to the contract above. Also the label-reading action-activity-report: its notability heuristic (NOTABLE_LABELS in tools/highlights.py) currently keys on infrastructure and priority: high, which cease to exist after migration — update to {enhancement, new-lecture, high-priority}. (Its noise rollup and status-report labels are unaffected; reporting actually gets more reliable from the unified dependencies.)
5. Publish the full guide (per-label rationale + worked examples) in the operations manual — closes QuantEcon/QuantEcon.manual#90.

A complete style-guide version of this (with worked examples and reviewer dashboard queries) is drafted and ready to go into the manual / a qe-cli repo once the set is agreed.

[mmcky]

qe as the standard entry point for QuantEcon tooling

A scope note as the CLI takes shape: the intent is for qe to become the
single operator entry point for QuantEcon work — new tooling lands as a
qe command group (qe <domain> <command>), not as another standalone tool
(e.g. a future style CLI would be qe style check, not qestyle).

What every group inherits by living under qe:

• one install (uv tool install from GitHub source) and one auth
  story (shells out to gh, no PAT);
• one config, including the profile → repo mapping — exactly one
  definition of "what is a QuantEcon lecture repo", shared by every domain;
• uniform conventions: --dry-run everywhere, --repos/--profile
  everywhere, CI-friendly exit codes;
• discoverability: qe --help is the catalogue of QuantEcon operations.

Reserved command map (only gh exists today):

Group	Status	Scope
qe gh	shipped (labels v0)	GitHub configuration: labels now; settings, profiles, onboarding next
qe style	candidate	Operator entry point for the style-guide checker (engine shared with action-style-guide)
qe report	candidate	Activity digests (could absorb action-activity-report queries)
qe lecture	candidate	Lecture/new-repo scaffolding and content tasks
qe build	candidate	Local lecture build helpers (jupyter-book)

Ground rules so this stays a toolbox, not a framework:

1. No command without a real, repeated manual task behind it — the
   namespace above is reserved, but a group is only built when the task
   shows up.
2. Keep the core install light — the core stays typer + pyyaml + gh;
   heavy-dependency domains land as optional extras (quantecon-cli[style])
   or entry-point plugins if their dependencies/release cadence diverge.
3. One engine, two entry points — CI actions (action-*) remain the CI
   surface but become thin wrappers calling qe, never a second
   implementation of the same logic.

[mmcky]

Decision phase split out → #324.

To keep the team review focused, the proposal has been distilled into a
decision-only issue: #324 (the 18 labels in compact form + three questions:
the set, the Tier-1 repo list, and the Draft-PR convention).

This issue stays open as the engineering record and implementation tracker.
Once #324 is decided, the rollout proceeds here:

1. Org-level default labels → core 16 (manual settings change, no API)
2. Sync Tier-1 repos via qe gh labels sync (QuantEcon/cli) — history-preserving renames
3. Update label-emitting tooling: action-link-checker, action-check-warnings,
   action-style-guide, per-repo Dependabot configs; and the label-reading
   action-activity-report (NOTABLE_LABELS → {enhancement, new-lecture, high-priority})
4. Update the operations-manual tags page + figure (closes QuantEcon/QuantEcon.manual#90)
5. Close GitHub Org - Unified Labels #178 / Standardized Labels for QuantEcon Repositories #290 against the decision in Decision: standard GitHub label set for QuantEcon lecture repositories #324