QEP-4: Automation Registry and Label Coordination (Draft)

[mmcky]

QEP-4: Automation Registry and Label Coordination

Status: Draft · Type: standard · Discussion: grew out of the QEP-2 field reports

QEP-2 standardises the human label vocabulary and a closed set of bot diagnostics, but field use surfaced a second kind of bot label it can't describe: labels automations use to coordinate — action-translation routing the Translation-Sync rollup, status-report letting the weekly-reports workflow find its own issues. These contracts evolve with the tooling, so they shouldn't be baked into a QEP label-by-label. This QEP resolves that with a registrar model: the QEP allocates the boundary, the automation owns the interior.

What it defines

• The registry — one entry per automation: a durable origin label (full name, e.g. action-translation, on every artifact it creates), an optional task prefix (short, capability-named, /-separated, e.g. translate/), a family grey from the #ededed–#bdbdbd band, a service area, and a contract link. Registration requires a documented consumer you can point at; adding/removing an entry is a substantive amendment, while everything inside a namespace never touches a QEP.
• Three label tiers — automated (org-wide union query) and the origin label are durable; task labels are transient. Origin marks authorship, not participation.
• Mailbox coordination semantics — worker-owns: apply = enqueue (open to org automations and maintainers by default), owner-removes = complete, human-removes = cancel, dead-letter on can't-act, and completion is inert (the anti-loop rule). Owners provision and garbage-collect their zones.
• The token gate — GITHUB_TOKEN events don't cascade, so bot→bot enqueueing requires a deliberately provisioned App/PAT: the human decision sits exactly where coordination power is granted. Humans trigger via the UI freely, floored by triage permission.
• Tooling rules — sync never touches a registered zone; prune skips registered zones mechanically instead of relying on a human recognising a routing key.

Founding registrations

Automation	Origin label	Task prefix	Family grey
action-translation	action-translation	translate/	#e5e5e5
reports-activity (weekly reports)	status-report	—	#d5d5d5

Relationship to QEP-2

QEP-2 keeps automated + the three diagnostics as core vocabulary and is now fully self-contained: under the cross-QEP convention adopted in #9, an in-review QEP is never forward-referenced by the standards it extends — instead this QEP carries the amendments to QEP-2. The draft's new Amendments to QEP-2 section preserves, verbatim, the registry hooks originally drafted inside QEP-2 during co-development (the related:/Related pairing, the origin/task-label policy sentences, the prune skip-rule, the grey-band registration clause); the acceptance PR re-applies them in their review-settled form, bumping QEP-2's version if it is Accepted by then (Rollout step 2). The machine-readable registry (qep-0004-automations.yml, following QEP-2's companion-file pattern) ships at acceptance per the Rollout — the appendix CI check needs a small extension for the registry schema first.

Decision deadline

To be set by the author once the draft has had a round of review.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds QEP-4 as a new Draft standard proposal defining a registry model for automation-owned coordination labels (origin labels + optional task namespaces), and registers it in the README index so it becomes part of the QEP registry.

Changes:

• Add QEP-4 document (Draft, standard) describing registry fields, label tiers, and coordination semantics (“mailbox model”).
• Add QEP-4 entry to the README index table.

Reviewed changes

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

File	Description
README.md	Adds QEP-4 to the registry index with Draft status and unversioned –.
qeps/qep-0004-automation-registry-and-label-coordination.md	Introduces the QEP-4 draft content, including founding registrations and tooling implications.

Comments suppressed due to low confidence (1)

qeps/qep-0004-automation-registry-and-label-coordination.md:105

• This reference to QEP-2 uses the same non-existent qep-0002-standard-github-labels.md relative link, which will be broken when rendered. Update it to a valid target (e.g., the QEP-2 PR) to avoid dead links in the table.

| Family marker | `automated` | "was this made by a machine?" (org-wide union query) | Durable — every bot artifact ([QEP-2](qep-0002-standard-github-labels.md)) |

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mmcky]

One boundary question for this QEP's review, surfaced while auditing the CLI issues against the now-accepted QEP-2 (QuantEcon/meta#358).

QEP-2's automation contract opens "Every bot-opened issue or PR carries automated, plus at most one diagnostic". Applied literally that pulls in Dependabot, which labels its own PRs dependencies alone. We settled it on 2026-08-08 as: the contract binds automations we own; a third-party bot labelling its own output is outside it, and QEP-2's authority there stops at defining the label dependencies — name, colour, description. So labels: [dependencies] in .github/dependabot.yml is correct as-is (QuantEcon/cli#4, QuantEcon/cli#5).

That is a working decision, not something QEP-2 says. Since this QEP owns bot behaviour and the registrar model, it is the right place to make the boundary explicit — who registers, and what the contract asks of automations nobody here can configure beyond a labels: key. Worth settling here rather than as a QEP-2 amendment, given the same line decides how origin labels apply to third-party emitters.