Standardize org label taxonomy for triage and tracker workflows

[ss-o]

Summary

The new AGENTS.md and runbooks/triage.md establish a cleaner triage model based on work type, area, and severity, but the current org label set in .github/lib/labels.yml still mixes legacy names, overlapping concepts, and inconsistent prefixes.

Scope

• review the current labels in .github/lib/labels.yml
• define the target taxonomy for type, area, severity, and workflow modifiers
• decide which legacy labels stay, which are aliased temporarily, and which are retired
• document how tracker fields map to the triage model
• define the gh/API-based rollout process for updating labels across org repositories

Why this is separate

This should not be changed piecemeal inside unrelated doc or workflow work. It affects org-wide issue hygiene and should be reviewed as an explicit maintenance task.

Completed

Completed via the existing label taxonomy/runbook work plus follow-up fix in #431.

Evidence:

• lib/labels.yml defines the canonical taxonomy: 31 labels across work type, area, severity/workflow modifiers, tracker automation, and retained automation labels.
• lib/labels.yml defines 30 legacy migrations and sync policy guardrails.
• runbooks/labels.md documents canonical groups, legacy retirement, safe cleanup order, dry-run commands, and apply-mode pilot guardrails.
• runbooks/triage.md maps work type, area, severity/modifier labels, and tracker fields.
• scripts/labels-sync.rb implements read-only dry-run, JSON output, pilot-gated apply preview/apply, and no-delete behavior for legacy/unknown labels.
• fix(labels): support older Ruby hash iteration #431 fixed Ruby compatibility in the label sync script so the documented dry-run works in the maintainer environment.

Verification after #431:

• ruby -c scripts/labels-sync.rb
• YAML shape check: 31 canonical labels and 30 legacy migrations, no duplicate canonical label names.
• scripts/labels-sync.rb --repo z-shell/.github --include-clean
  • read-only dry-run
  • repos scanned: 1
  • repos with drift: 0
  • z-shell/.github clean

Org-wide rollout remains intentionally pilot-gated by runbooks/labels.md and scripts/labels-sync.rb; this issue covered defining and verifying the taxonomy and process, not mutating every repository label set.

[ss-o]

Agent handoff / draft findings:

• Confirmed the target taxonomy in runbooks/labels.md and runbooks/triage.md.
• Found drift: both runbooks reference .github/lib/labels.yml, but the initialized z-shell/.github checkout does not contain that file. Recommend resolving this source-of-truth gap before rollout.
• Sampled labels across selected repos; many child repos still carry legacy emoji/spaced/plain labels and are missing canonical namespace labels (type:*, area:*, status:*, meta:org-tracked).
• Recommended next step: add/restore the canonical labels file plus a dry-run label sync script, then pilot on low-risk repos before migrating zi/wiki/src.

No labels or issues were changed.

[ss-o]

Label dry-run follow-up update:

• Synced .github after PR chore(labels): restore canonical label source file #422 and chore(labels): add dry-run label audit script #423 merged.
• Ran the new scripts/labels-dry-run.rb --all-repos audit across the org.
• Generated local conductor artifacts:
  • Markdown report: /mnt/ef69bf55-1bed-43ad-a9c5-bfe40024bb1c/z-shell/management/conductor/2026-05-23-label-dry-run-org-report.md
  • JSON report: /mnt/ef69bf55-1bed-43ad-a9c5-bfe40024bb1c/z-shell/management/conductor/2026-05-23-label-dry-run-org-report.json
  • Summary: /mnt/ef69bf55-1bed-43ad-a9c5-bfe40024bb1c/z-shell/management/conductor/2026-05-23-label-dry-run-org-summary.md

Read-only results:

• Repos scanned: 93
• Repos with drift: 92
• Clean repos: 1 (z-shell/.github)
• Missing canonical label entries across repos: 2574
• Label metadata updates across repos: 252
• Legacy labels present across repos: 1489
• Unknown labels across repos: 1755

Important note: the first run exposed a compatibility bug in the merged dry-run script on this local gh version: the Go-template json function is unavailable. I opened a small follow-up PR to replace that with gh api --jq '.[]' while keeping paginated reads newline-delimited:

• fix(labels): use gh jq for paginated label reads #424

Recommended next step after #424 merges:

1. Re-run the org dry-run from main.
2. Pick a very small pilot batch that only creates/updates canonical labels, with no deletion.
3. Keep delete_unknown_labels: false.
4. Treat legacy and unknown labels as review/migration work, not bulk-delete work.