Issue Label Taxonomy
Provider-neutral tracker label roles and workflow semantics
Issue Label Taxonomy
AIWG issue workflows resolve tracker labels from `.aiwg/aiwg.config`. Semantic roles remain stable while Gitea, GitHub, and the local issue store may use different label strings.
{
"remotes": {
"issue_tracker": "origin"
},
"issues": {
"labels": {
"human_required": {
"name": "hitl",
"provider_names": {
"github": "human-required",
"local": "needs-human"
},
"category": "human-interaction",
"description": "Work cannot continue until a human responds",
"requires_human": true,
"blocks_automation": true,
"resume_when": "requested human input is recorded"
},
"feature": {
"name": "feature",
"category": "type",
"description": "Feature work",
"requires_human": false,
"blocks_automation": false
}
}
}
}
The supported categories are `type`, `area`, `priority`, `lifecycle`, `blocked-reason`, `review-approval`, `ownership`, `automation-eligibility`, and `human-interaction`. Keys such as `human_required` are project-owned stable roles. Workflows filter and mutate by role, then resolve the tracker-native name.
When `blocks_automation` is true, `resume_when` is required. A workflow applying the label must also post a concise comment saying what human action is needed and quoting the resume condition. After that condition is satisfied, the workflow removes the transient label or applies `transition_to`, while preserving every unrelated label.
Before issue processing, validation reports:
- missing required semantic fields;
- duplicate tracker names;
- conflicting blocking or transition rules; and
- configured names unavailable in the selected tracker.
Validation is read-only. Missing labels are never silently created, renamed, or deleted. Provisioning must be a separate explicit operator action.
Validate structural semantics with:
aiwg config validate --project --provider gitea
When a workflow has fetched the tracker label catalog, it can pass the native names to the same diagnostic surface:
aiwg config validate --project --provider gitea \
--available-label hitl \
--available-label feature
Any configured label absent from that catalog is reported as unavailable and the command fails without mutating the tracker.
Projects without `issues.labels` keep legacy behavior for compatibility. Workflows must emit a fallback warning before using a conventional name such as `question`; they must not silently invent or provision a label. Configure the taxonomy to make search, audit, batching, selection, and workflow transitions portable across trackers.