---
name: maintainer-label-system
description: >
  Maintain iccDEV repository labels, path labeler rules, issue triage labels,
  PR CI status labels, and label workflow governance.
allowed-tools:
  - bash
  - read
  - grep
  - glob
  - shell(git:*)
---

# Maintainer Label System

Use this skill when adding, removing, or auditing labels and label automation.

## Required Inputs

1. The branch or PR being changed.
2. Whether the change is taxonomy-only, path-label automation, issue triage,
   PR status labeling, or CodeQL label routing.
3. Any labels that must remain stable for existing issues, PRs, or workflows.

## Workflow

1. Read `../../../docs/label-system.md`.
2. Audit the managed manifest against live labels before changing taxonomy.
   `.github/labels.yml` is not destructive: classify undeclared live labels as
   legacy or migrate them deliberately.
3. Update `.github/labels.yml` before changing workflow or labeler behavior.
4. Add `.github/labeler.yml` rules only for deterministic file paths or branch
   names. Do not classify severity, exploitability, or maintainer judgment from
   PR text.
5. Keep privileged label workflows on trusted metadata:
   - no checkout of PR head code in `pull_request_target`;
   - explicit `zizmor` rationale for any retained `pull_request_target` labeler;
   - least-privilege job permissions;
   - pinned third-party actions;
   - no direct `${{ }}` expressions inside shell.
6. Keep issue triage and PR-status labeling independent of taxonomy
   synchronization; neither may issue manifest-wide label writes for every
   issue or PR event.
7. If issue triage logic changes, keep it conservative and make labels easy for
   maintainers to override.
8. If PR status labels change, preserve mutual exclusion among `passed`,
   `failed`, and `pending`.
9. If PR CI control labels change, keep them maintainer-only, one-shot, and
   restricted to same-repository pull requests.
10. Update docs, prompts, agents, and the inventory artifact when policy or
    maintainer workflow changes.
11. For a new scope label, add its canonical `.github/labels.yml` entry before
   issue-text or path automation. Keep deletion manual after checking all active
   label consumers.

## Validation

```bash
bash -n .github/scripts/sync-labels.sh
GH_REPOSITORY=InternationalColorConsortium/iccDEV \
  .github/scripts/sync-labels.sh --dry-run
yamllint -d '{extends: default, rules: {document-start: disable, truthy: disable, line-length: {max: 120}}}' .github/labels.yml .github/labeler.yml
actionlint -no-color .github/workflows/pr-labeler.yml .github/workflows/sync-labels.yml .github/workflows/label.yml .github/workflows/update-labels.yml
zizmor .github/workflows/pr-labeler.yml .github/workflows/sync-labels.yml .github/workflows/label.yml .github/workflows/update-labels.yml
git diff --check
```

For workflow governance changes, also run:

```bash
.github/scripts/preflight-safety-checks.sh
```

## Review Checklist

- `.github/labels.yml` contains every automated label.
- Managed labels are reconciled with the live inventory without deleting legacy
  labels or rewriting unchanged metadata.
- `.github/labeler.yml` paths are specific enough to avoid noisy labels.
- Large PR safeguards still exist.
- Label workflows do not execute untrusted PR content.
- Status labels remain machine-managed and mutually exclusive.
- PR CI control labels are documented, canonical in `.github/labels.yml`, and
  unavailable to fork PR fast lanes.
- `bump-sha-pins` is documented as a maintainer follow-up label for pinned
  GitHub Action, Docker, or container SHA refreshes.
- `codeql-ready` still routes to the full CodeQL workflow.
- Documentation, skills, and prompts point to the same canonical files.
- The label-triage agent and inventory artifact match the managed manifest.

## References

- `../../../docs/label-system.md`
- `../../labeler.yml`
- `../../labels.yml`
- `../../workflows/pr-labeler.yml`
- `../../workflows/sync-labels.yml`
- `../../workflows/label.yml`
- `../../workflows/update-labels.yml`
- `../../instructions/workflow-governance.instructions.md`
- `../../prompts/maintainer-label-triage.prompt.md`