From 271060dcb7057474a28a90eb20784daf04d46e18 Mon Sep 17 00:00:00 2001
From: Chummy <chumyin0912@gmail.com>
Date: Tue, 17 Feb 2026 16:12:52 +0800
Subject: [PATCH] feat(labels): add manual audit/repair dispatch for managed
 labels

---
 .github/workflows/labeler.yml         | 87 ++++++++++++++++++++++++++-
 .github/workflows/workflow-sanity.yml | 44 ++++++++++++++
 docs/ci-map.md                        |  1 +
 docs/pr-workflow.md                   |  1 +
 4 files changed, 132 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml
index 44371e5..d629a1f 100644
--- a/.github/workflows/labeler.yml
+++ b/.github/workflows/labeler.yml
@@ -3,9 +3,19 @@ name: PR Labeler
 on:
     pull_request_target:
         types: [opened, reopened, synchronize, edited, labeled, unlabeled]
+    workflow_dispatch:
+        inputs:
+            mode:
+                description: "Run mode for managed-label governance"
+                required: true
+                default: "audit"
+                type: choice
+                options:
+                    - audit
+                    - repair
 
 concurrency:
-    group: pr-labeler-${{ github.event.pull_request.number }}
+    group: pr-labeler-${{ github.event.pull_request.number || github.run_id }}
     cancel-in-progress: true
 
 permissions:
@@ -19,6 +29,7 @@ jobs:
         timeout-minutes: 10
         steps:
             - name: Apply path labels
+              if: github.event_name == 'pull_request_target'
               uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5
               continue-on-error: true
               with:
@@ -497,6 +508,80 @@ jobs:
                         return matchedTier ? matchedTier.label : null;
                       }
 
+                      if (context.eventName === "workflow_dispatch") {
+                        const mode = (context.payload.inputs?.mode || "audit").toLowerCase();
+                        const shouldRepair = mode === "repair";
+                        const repoLabels = await github.paginate(github.rest.issues.listLabelsForRepo, {
+                          owner,
+                          repo,
+                          per_page: 100,
+                        });
+
+                        let managedScanned = 0;
+                        const drifts = [];
+
+                        for (const existingLabel of repoLabels) {
+                          const labelName = existingLabel.name || "";
+                          if (!isManagedLabel(labelName)) continue;
+                          managedScanned += 1;
+
+                          const expectedColor = colorForLabel(labelName);
+                          const expectedDescription = descriptionForLabel(labelName);
+                          const currentColor = (existingLabel.color || "").toUpperCase();
+                          const currentDescription = (existingLabel.description || "").trim();
+                          if (currentColor !== expectedColor || currentDescription !== expectedDescription) {
+                            drifts.push({
+                              name: labelName,
+                              currentColor,
+                              expectedColor,
+                              currentDescription,
+                              expectedDescription,
+                            });
+                            if (shouldRepair) {
+                              await ensureLabel(labelName, existingLabel);
+                            }
+                          }
+                        }
+
+                        core.summary
+                          .addHeading("Managed Label Governance", 2)
+                          .addRaw(`Mode: ${shouldRepair ? "repair" : "audit"}`)
+                          .addEOL()
+                          .addRaw(`Managed labels scanned: ${managedScanned}`)
+                          .addEOL()
+                          .addRaw(`Drifts found: ${drifts.length}`)
+                          .addEOL();
+
+                        if (drifts.length > 0) {
+                          const sample = drifts.slice(0, 30).map((entry) => [
+                            entry.name,
+                            `${entry.currentColor} -> ${entry.expectedColor}`,
+                            `${entry.currentDescription || "(blank)"} -> ${entry.expectedDescription}`,
+                          ]);
+                          core.summary.addTable([
+                            [{ data: "Label", header: true }, { data: "Color", header: true }, { data: "Description", header: true }],
+                            ...sample,
+                          ]);
+                          if (drifts.length > sample.length) {
+                            core.summary
+                              .addRaw(`Additional drifts not shown: ${drifts.length - sample.length}`)
+                              .addEOL();
+                          }
+                        }
+
+                        await core.summary.write();
+
+                        if (!shouldRepair && drifts.length > 0) {
+                          core.info(`Managed-label metadata drifts detected: ${drifts.length}. Re-run with mode=repair to auto-fix.`);
+                        } else if (shouldRepair) {
+                          core.info(`Managed-label metadata repair applied to ${drifts.length} labels.`);
+                        } else {
+                          core.info("No managed-label metadata drift detected.");
+                        }
+
+                        return;
+                      }
+
                       const files = await github.paginate(github.rest.pulls.listFiles, {
                         owner,
                         repo,
diff --git a/.github/workflows/workflow-sanity.yml b/.github/workflows/workflow-sanity.yml
index 82117c7..abad363 100644
--- a/.github/workflows/workflow-sanity.yml
+++ b/.github/workflows/workflow-sanity.yml
@@ -63,3 +63,47 @@ jobs:
 
             - name: Lint GitHub workflows
               uses: rhysd/actionlint@393031adb9afb225ee52ae2ccd7a5af5525e03e8 # v1.7.11
+
+    contributor-tier-consistency:
+        runs-on: blacksmith-2vcpu-ubuntu-2404
+        timeout-minutes: 10
+        steps:
+            - name: Checkout
+              uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+            - name: Verify contributor-tier parity across workflows
+              shell: bash
+              run: |
+                  set -euo pipefail
+                  python3 - <<'PY'
+                  import re
+                  from pathlib import Path
+
+                  files = [
+                    Path('.github/workflows/labeler.yml'),
+                    Path('.github/workflows/auto-response.yml'),
+                  ]
+
+                  parsed = {}
+                  for path in files:
+                    text = path.read_text(encoding='utf-8')
+                    rules = re.findall(r'\{ label: "([^"]+ contributor)", minMergedPRs: (\d+) \}', text)
+                    color_match = re.search(r'const contributorTierColor = "([0-9A-Fa-f]{6})"', text)
+                    if not color_match:
+                      raise SystemExit(f'failed to parse contributorTierColor in {path}')
+                    parsed[str(path)] = {
+                      'rules': rules,
+                      'color': color_match.group(1).upper(),
+                    }
+
+                  baseline = parsed[str(files[0])]
+                  for path in files[1:]:
+                    entry = parsed[str(path)]
+                    if entry != baseline:
+                      raise SystemExit(
+                        'contributor-tier mismatch between workflows: '
+                        f'{files[0]}={baseline} vs {path}={entry}'
+                      )
+
+                  print('contributor tier rules/color are consistent across label workflows')
+                  PY
diff --git a/docs/ci-map.md b/docs/ci-map.md
index 356f5c0..108a9d0 100644
--- a/docs/ci-map.md
+++ b/docs/ci-map.md
@@ -35,6 +35,7 @@ Merge-blocking checks should stay small and deterministic. Optional checks are u
     - Additional behavior: applies contributor tiers on PRs by merged PR count (`trusted` >=5, `experienced` >=10, `principal` >=20, `distinguished` >=50)
     - Additional behavior: final label set is priority-sorted (`risk:*` first, then `size:*`, then contributor tier, then module/path labels)
     - Additional behavior: managed label colors follow display order to produce a smooth left-to-right gradient when many labels are present
+    - Manual governance: supports `workflow_dispatch` with `mode=audit|repair` to inspect/fix managed label metadata drift across the whole repository
     - Additional behavior: risk + size labels are auto-corrected on manual PR label edits (`labeled`/`unlabeled` events); apply `risk: manual` when maintainers intentionally override automated risk selection
     - High-risk heuristic paths: `src/security/**`, `src/runtime/**`, `src/gateway/**`, `src/tools/**`, `.github/workflows/**`
     - Guardrail: maintainers can apply `risk: manual` to freeze automated risk recalculation
diff --git a/docs/pr-workflow.md b/docs/pr-workflow.md
index 0838498..3c62711 100644
--- a/docs/pr-workflow.md
+++ b/docs/pr-workflow.md
@@ -52,6 +52,7 @@ Maintain these branch protection rules on `main`:
 - `PR Labeler` applies scope/path labels + size labels + risk labels + module labels (for example `channel:telegram`, `provider:kimi`, `tool:shell`) and contributor tiers by merged PR count (`trusted` >=5, `experienced` >=10, `principal` >=20, `distinguished` >=50), while de-duplicating less-specific scope labels when a more specific module label is present.
 - For all module prefixes, module labels are compacted to reduce noise: one specific module keeps `prefix:component`, but multiple specifics collapse to the base scope label `prefix`.
 - Label ordering is priority-first: `risk:*` -> `size:*` -> contributor tier -> module/path labels.
+- Maintainers can run `PR Labeler` manually (`workflow_dispatch`) in `audit` mode for drift visibility or `repair` mode to normalize managed label metadata repository-wide.
 - Hovering a label in GitHub shows its auto-managed description (rule/threshold summary).
 - Managed label colors are arranged by display order to create a smooth gradient across long label rows.
 - `Auto Response` posts first-time guidance, handles label-driven routing for low-signal items, and auto-applies issue contributor tiers using the same thresholds as `PR Labeler` (`trusted` >=5, `experienced` >=10, `principal` >=20, `distinguished` >=50).