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.