chore: prepare area and topic labels for migration #5151

User Story

As an OpenShell maintainer, I need repository label definitions, routing support, and migration guidance prepared so that the shared labeling workflow can safely align current and potentially reopened work with the agreed taxonomy.

Description

#4863 merged on 2026-11-04 (UTC). Use the landed REVIEWERS.md as the baseline taxonomy: 5 areas and 20 topics, including topic:authnz and topic:ux. The agreed migration adds four SDK language topics (topic:sdk:go, topic:sdk:python, topic:sdk:rust, topic:sdk:typescript), and removes the broad topic:sdk, for 5 areas and 23 topics in the intended taxonomy. Prepare repository label definitions, retirement rules, routing support, and migration guidance for that taxonomy. Develop and review the mapping against actual affected items. This issue owns preparation; item-level migration belongs to the shared labeling/reconciliation path discussed below. The mapping is guidance for contextual examination, not an approved bulk transformation.

Include items regardless of open or closed state. Leave merged PRs and resolved issues unchanged where possible. An issue is resolved if any of the following applies:

• It is closed as completed.
• It has an attached merged PR that closed it.
• Its author commented that they are closing it, including abandonment or displacement by another issue.
• A maintainer commented that the project is not accepting the work.
• A maintainer deliberately closed it as not_planned or duplicate, even without an explanatory comment.

Verify closure actor and reason. Deliberate maintainer not_planned/duplicate closure counts as resolution; stale-bot closure remains eligible unless other resolution evidence applies. Review author-only and unclear closures separately; do not silently guess when evidence is ambiguous. Record uncertain cases for human disposition. Treat PRs as merged based on their merge status, including merged PRs later reverted.

Delivery split and proposed faster path

• chore: prepare area and topic labels for migration #5151 owns preparation: settle definitions/colors, establish the intended repository labels and retirement names after prerequisites pass, correct networking scope wording, support nested SDK topics in routing, verify automation compatibility, and hand off the agreed rules and review inventory. Preparation does not authorize changing label assignments on issues or PRs.
• Proposed first delivery in PR feat(review): automatically label new PRs for accepted work #5260: consider extending its existing review-readiness workflow with a separate, reusable per-item label reconciler and an explicit invocation path for issues and PRs. Keep accepted_work.py read-only; label writes belong to the reconciler. Preview and review the initial results before application. This is a proposed scope extension, not a claim that feat(review): automatically label new PRs for accepted work #5260 already implements migration.
• Backlog execution: after preparation and the initial reconciler land, invoke the same reconciler for each eligible backlog item. Enforce the shared accepted-work gate as well as this issue's resolved/merged exclusions. Items lacking acceptance remain deferred; force does not grant acceptance. Do not build a second bulk classification implementation. Re-read item contents, lifecycle state, and current labels; preserve unrelated labels and human-owned dispositions, record before/after results, and account for reviewer-routing notifications.
• chore: create an invocable agent for workflow and topic labeling #5276 owns agent extraction and ongoing reconciliation: move classification/examination into an invocable labeling agent that the existing workflow can call, alongside authorized human/triager invocation. Retain the deterministic acceptance checks and safe application boundary as shared code. Use the migration inventory as a baseline and source of eval cases, not an unchecked execution manifest.

Keep classification/evidence collection separate from validation and label application in the initial implementation so extraction can replace the classifier without duplicating policy or mutation logic. Routine touches can invoke the reconciler through triagers or approved workflows; this does not authorize firing it on every edit or label change. New-issue invocation through intake/triage and the exact explicit-dispatch mechanism remain implementation details to settle in the receiving work.

Landed taxonomy

Areas represent OpenShell components or system boundaries; topics represent technical concerns across areas. Current #5276 classification policy requires exactly one primary area and any supported topics on both issues and PRs. Select the primary area for cross-component work; record ambiguous choices for review.

These concise descriptions are proposed GitHub label definitions derived from the landed roster, plus the agreed SDK language topics. Use the roster for full scopes; add support for the language topics through reviewed routing/roster changes before creating or applying them. Language topics route independently and do not require topic:sdk. Seed each language roster with the existing broad SDK reviewers; refine individual subscriptions in follow-on work. The broad topic:sdk is removed. For cross-SDK work, select each language topic supported by the contents.

Initial mapping for discussion

These are review rules based on the landed taxonomy and the prepared per-item inventory, not an approved bulk transformation. Preserve existing intended labels and unrelated labels. Select a single primary area on PRs; do not accumulate every candidate area or topic.

Per-item migration review

Google Sheet: OpenShell #5151 — Label migration review

The paginated inventory contains 4,801 issues and PRs across open and closed states; 647 carry area/topic labels. The sheet contains full current label sets and proposed final label sets, with unrelated labels preserved.

• 127 proposed changes: require review before execution.
• 1 item needing a decision: VM/contianer manage through nixos module via microVM #1869 was closed by its author without a qualifying closure explanation. Keep it separate under the author-resolution rule. The maintainer-closure rule resolved 70 former holds; SDK language topics and routine compatibility mapping resolved the other eight.
• 519 skipped or already matching items: retain associations; reasons and evidence are recorded.
• 499 global rename effects: retirement would change displayed label names on these items, including resolved issues and merged PRs, without changing their label associations.

The sheet also contains label definitions, mapping decisions, retirement-only intermediate states, additions/removals relative to retirement, evidence links, review status, and a snapshot timestamp. Closure context was retrieved for all 139 closed, non-completed issues in the classified inventory. Deliberate maintainer not_planned/duplicate closures count as resolution without comments; author-only or unclear closures remain separate. Stale-bot closure alone is not resolution. Items without area/topic labels are counted but are outside this migration inventory.

This is a draft for review, not an execution manifest. Closure policy and SDK language discovery are settled in the sheet's Decision clusters tab. Remaining work includes colors, external automation, review of individual proposals, the author-only closure exception #1869, the networking wording correction, and nested SDK-topic routing/roster support. Re-read status and complete labels before any later execution; concurrent changes invalidate the row until reviewed again. No labels or reviewer requests were changed to prepare the sheet. No Google sharing permissions were changed.

Label preparation and retirement plan

Current phase: resolve inconsistencies and check automation before creating/updating label definitions or retiring labels. Do not change label assignments on any issue or PR.

Reconcile live definitions against the 28 intended active labels using a fresh preview from the fork-only tools branch; create missing definitions and update existing definitions in the later label-definition phase. Do not create the removed broad topic:sdk label. Do not migrate issue/PR label assignments in that phase.

Proposed colors, pending discussion: areas #6699CC (current area:docs blue), topics #B3D1EB (lighter related blue), retired labels #EDEDED (current test-label grey). No project color convention was found. Some other label families already use blue; prefixes remain the reliable category identifier.

Proposed retirement list (18 labels): prepend retired: to each full current name and set color to #EDEDED.

• area:cli → retired:area:cli
• area:cluster → retired:area:cluster
• area:compute → retired:area:compute
• area:docs → retired:area:docs
• area:gateway → retired:area:gateway
• area:inference → retired:area:inference
• area:policy → retired:area:policy
• area:providers → retired:area:providers
• area:sandbox → retired:area:sandbox
• area:sdk → retired:area:sdk
• area:sdk:go → retired:area:sdk:go
• area:sdk:python → retired:area:sdk:python
• area:sdk:rust → retired:area:sdk:rust
• area:sdk:typescript → retired:area:sdk:typescript
• area:supervisor → retired:area:supervisor
• area:tui → retired:area:tui
• topic:compatibility → retired:topic:compatibility
• topic:l7 → retired:topic:l7

Proposed retired description: “Retired; do not apply. See #5151 for item-specific migration to the current taxonomy.” Renaming preserves label associations but changes the displayed names/colors on historical issues and PRs too; explicitly account for that exception to leaving resolved/merged history unchanged. Review links and automation references before retirement. Renaming discourages reuse but does not prohibit it.

Do not delete labels during preparation. The earlier comment's suggestion to delete unused obsolete labels remains a discussion point; the current proposed plan renames all obsolete area/topic labels.

Context

• feat(review): add area and topic reviewer rosters and routing #4863 has landed; use its baseline taxonomy plus the agreed SDK language topics. Do not introduce other taxonomy changes implicitly.
• Agreed networking clarification: remove the L7 exclusion and reference from the roster description. The resulting topic:networking description is “General network transport, connectivity, and proxy behavior.” L7 is not excluded. Keep the existing per-item mapping of topic:l7 to topic:networking, topic:policy, or both; do not add a new topic.
• Reviewer-routing automation may react to label changes on ready PRs. Assess and plan for notifications and review requests during migration.
• Include a dry run or reviewable inventory showing proposed additions and removals, ambiguous cases, and skipped resolved/merged items. Keep a record sufficient to audit and reverse changes if needed. Recheck item status before applying changes to account for concurrent updates.

Comment follow-ups for discussion

• Taxonomy, retirement, and migration spreadsheet: prepare a determinate per-item spreadsheet for issues and PRs before execution. Suggested columns: URL, item type/status, current labels, resolution evidence, proposed area/topics, additions/removals, rationale, ambiguity/disposition, reviewer signoff, and skipped reason. Agreed: language topics work independently, each initially carrying a copy of the broad SDK reviewers; individual subscriptions will be refined afterward.
• User experience versus developer experience: incorporated the landed topic:ux into the taxonomy and CLI/TUI mapping. topic:dx concerns contributing; topic:operability concerns running installations. Inspect first-run issues for overlap rather than applying all three automatically.
• Missing label descriptions: audit definitions across all label families, including state:validated. Propose descriptions from documented semantics and maintainer intent before editing them; this does not authorize state/disposition changes or expand the area/topic item migration.

Automation audit before label-definition changes

Audited upstream main at d7da0c7da and a live snapshot of all open PRs on 2026-11-04 (UTC). This was read-only: no issue/PR label assignments, reviewer requests, or repository labels were changed.

Repository automation

• Searched the tracked repository, including GitHub workflows/actions, scripts, templates, public skills, and contributor skills, for literal/URL-encoded area/topic references. No retiring label names are hard-coded in active automation.
• Reviewer routing selects labels by the area: and topic: prefixes, requires exactly one recognized area, and rejects unknown area/topic labels. retired:area:... and retired:topic:... are ignored. Retirement therefore does not supply a replacement primary area.
• The routing workflow listens for PR opening/ready-for-review and area/topic application/removal. It does not subscribe to repository label: edited events. Do not rely on label-definition edits to reconcile reviewer requests. GitHub documents repository label events separately from label assignment events.
• Required CI/E2E gates use test:*; intake uses state:triage-needed; acceptance uses state:accepted; stale handling uses state/lifecycle/roadmap labels. These names are unchanged. Copy-pr-bot and Dependabot repository configuration contain no area/topic dependency.
• The effective main rules inspected require Branch Checks, Helm Lint, E2E, and GPU E2E; Review Readiness is not in that required-status-check list. Routing failures still matter for reviewer assignment.
• Current upstream includes fix(review): route reviewers without requiring write access #5257: reviewers no longer need repository write access. Account for the current routing behavior when planning migration notifications.

Offline rename simulation

Read all 243 open PRs, including 196 ready PRs. Sixteen open PRs carry retiring labels; 15 are ready for review. Applied only the proposed name substitutions in memory and called the upstream routing selector before/after.

• No ready PR transitions from valid routing to invalid routing in this snapshot.
• No affected ready PR becomes valid merely through retirement.
• All 15 affected ready PRs already fail the selector. Example: refactor(credentials): move embedded refresh execution into issuer #5283 has area:gateway, which currently fails as an unknown area; after retirement it would fail for having no active area.
• This is selector validation, not a live workflow run or API request simulation. Recheck the inventory immediately before retirement. Old labels and missing areas remain a migration concern even without a newly introduced failure.

SDK language topic routing prerequisite

Agreed topic names: topic:sdk:go, topic:sdk:python, topic:sdk:rust, and topic:sdk:typescript, independently of topic:sdk. These are intended classification/subscription labels; no repository labels have been created.

The current roster parser accepts only one colon in a category name. An offline check confirmed topic:sdk:go fails that grammar and reviewer selection reports unknown area/topic labels: topic:sdk:go, even alongside area:platform and topic:sdk. Add reviewed parser/routing and roster support, with appropriate validation and coverage, before creating or applying these labels. Seed each language section with a copy of the existing broad SDK reviewers as explicitly requested; solicit individual subscriptions as follow-on work.

Outstanding prerequisites

• Networking scope decision resolved: remove “not covered by the more specialized L7 category” from REVIEWERS.md, leaving “General network transport, connectivity, and proxy behavior.” The proposed label definition above already matches. Apply the roster wording correction through a reviewed PR; the existing topic:l7 mapping remains unchanged.
• Land nested SDK-topic routing/roster support before creating or applying the language labels.
• Repository webhook enumeration returned HTTP 403 (Resource not accessible by personal access token). External bots, installed-app configuration, organization automation, and saved project-view filters have not been verified. Do not claim whole-project compatibility until those dependencies are checked.
• Label-definition creation/description/color work is authorized after inconsistencies are resolved; retirement remains gated on automation compatibility. Do not change label assignments on issues or PRs in this phase.

Preparation implementation and current blockers

Repository-side prerequisites are implemented in PR #5503, closing preparation subtask #5502. This parent remains open until live definitions and external-automation verification are complete.

The PR now contains only permanent changes: nested topic routing, four independent language rosters copied from the existing SDK roster, the networking wording correction, SDK guidance, and regression tests. Its diff is limited to REVIEWERS.md, CONTRIBUTING.md, and the routing helper/tests. All 68 local routing/accepted-work tests pass; the fork-only tooling has 5 additional passing tests.

Fresh read-only preparation at 86acdf985 finds 20 creates, 9 updates, and 18 retirements. The original-definition backup and live preview are saved locally as /tmp/openshell-5151-live-definition-plan.json; regenerate the preview immediately before any live edits. Tracked workflows/scripts/templates/skills contain no hard-coded retiring names. A current snapshot contains 227 open PRs, 176 ready, and 9 ready PRs carrying retiring labels; simulated renames introduce no newly invalid routing states. This does not fix already-invalid classifications or prove external compatibility.

Outstanding prerequisites for live definition edits:

• Merge the reviewed routing/roster support in chore(review): support independent SDK language reviewer topics #5503; do not apply nested SDK topics against the old routing code.
• Verify external webhook/app/project-filter compatibility. Repository webhook enumeration still returns HTTP 403 (Resource not accessible by personal access token); the repository code audit cannot substitute for that check.
• Review the catalog and refresh the preview before global edits. Preserve label IDs with in-place retirement, retain the original definitions, and verify final definitions and historical display effects. No repository labels or existing item assignments have been changed by this implementation.
• The description audit also reports undefined non-classification labels: Feature, Improvement, feature request, gator:merge-ready, needs-rfc, rfc, roadmap, spike, state:community-review, state:in-review, state:validated, tech-debt, test-label, and tmp:migrate. These require reviewed meanings; the planner does not invent workflow-state definitions.

The older spreadsheet is a historical baseline, not a current execution manifest. #5276 now requires exactly one area on issues as well as PRs. The current labeling skill also requires verified stale-closure evidence; older unmarked bot closures may be held under the shared lifecycle rules. Refresh eligibility and proposed labels through the current shared helper before any later item-level migration.

Fork-only migration tooling and permanent PR boundary

The one-time migration catalog, preview script/tests, and runbook are on purp/label-migration-tools in purp/OpenShell. Fetch that branch locally to run the read-only definition preview. The helper still has no apply mode. Do not merge these tools upstream and do not plan a merge-then-remove cleanup cycle.

Draft PR #5503 now includes only enduring pre-migration changes: reviewer routing/parser support and regression tests, the networking scope correction and copied language reviewer rosters, and permanent SDK guidance. Tool-only CODEOWNERS entries, CI wiring, and the contributor runbook link have been removed from the PR.

The broad topic:sdk category is removed entirely in favor of SDK language labels. Each language section starts with the same four reviewers as the broad SDK section; individual subscriptions are follow-on work. #5276 and the classifier validation in #5355 must follow this independent-topic rule, replacing the earlier broad-plus-language requirement. The historical spreadsheet proposals require refresh under this rule before execution.

SDK language-only taxonomy decision

The broad topic:sdk is removed from the intended taxonomy, REVIEWERS.md, and CONTRIBUTING.md. The active SDK topics are Go, Python, Rust, and TypeScript; cross-SDK work receives the relevant language topics supported by the item contents. Each language roster retains the four copied reviewers; individual subscriptions follow separately.

The fork-only catalog now contains 28 active definitions and 19 retirement candidates, including topic:sdk if it exists live. An absent retired label is not created. Previous audit counts and spreadsheet proposals predate this decision; regenerate the definition preview and refresh item proposals before application. #5355/#5276 must remove the parent-topic validation requirement and must not introduce a broad SDK label.

Definition of Done

• Reconcile the intended taxonomy and initial mapping with the landed feat(review): add area and topic reviewer rosters and routing #4863, including topic:authnz and topic:ux.
• Agree to remove the obsolete L7 exclusion/reference from the networking description; preserve the existing per-item L7 mapping.
• Apply the agreed networking wording correction to REVIEWERS.md through a reviewed PR.
• Agree that deliberate maintainer not_planned/duplicate closure is resolution without a comment; stale-bot closure stays eligible absent other resolution evidence, with author-only/unclear closures checked separately.
• Agree to independent SDK language topics, each initially seeded with the broad SDK reviewers; the parent topic is not required.
• Add reviewed nested SDK-topic routing/roster support before label creation or application.
• Review proposed definitions, colors, retirement list, and remaining mapping ambiguities.
• Audit missing/unclear descriptions across label families and review proposed definitions.
• Establish the intended labels and prevent further use of retired labels without inadvertently stripping labels from historical items.
• Hand off the inventory, resolution rules, acceptance-gate requirement, and remaining exceptions to the shared reconciler delivery work.
• Document the required preview/review, status/label rechecks, audit record, and reviewer-routing side effects for the receiving implementation.
• Link the receiving workflow/reconciler delivery and chore: create an invocable agent for workflow and topic labeling #5276 extraction work; item-level migration is executed through that shared path, not in this preparation issue.
• Report preparation completion and outstanding blockers; transfer coverage, skips, exceptions, and execution tracking to the receiving reconciliation work.