# Issue and PR labels

Labels are **org-wide**. They are defined once, for the whole
`ShadowsOverWestgate` org, at
<https://git.westgate.pw/org/ShadowsOverWestgate/settings/labels>, and every
repo in the org can use them. Never create a per-repo copy of a label that
already exists at org level.

## The rule

**Every issue and every pull request gets exactly one `Kind/*` label, at the
moment it is created.** Not later, not "when someone triages it". If you open
it, you label it.

An issue with no `Kind/*` label is untriaged. That is the only meaning of
"untriaged" here — there is no `needs-triage` label.

The other groups are optional, and each one is *exclusive*: an issue can carry
at most one `Priority/*`, one `Status/*`, and one `Reviewed/*`. Gitea enforces
this.

```sh
# always from inside the owning repo's clone
tea issues create --title "..." --description "..." --labels "Kind/Bug" </dev/null
tea pr create --title "..." --description "..." --labels "Kind/Feature" </dev/null

# add a label to something that already exists (needs tea >= 0.15 for org labels)
tea issues edit <n> --add-labels "Kind/Bug,Priority/High"

# read the result back — exit 0 is not evidence the label applied
tea api "repos/ShadowsOverWestgate/<repo>/issues/<n>"
```

`tea api` sends only the login's `token:` and never your SSH key, so on an
SSH-only login every authenticated call fails with
`{"message":"token is required"}` while anonymous reads still work. Add a token
to `~/.config/tea/config.yml` if you want the raw endpoints. `tea issues edit`
needs no token.

## Kind — what this is (pick exactly one)

| Label                | Use it when                                                     |
| -------------------- | --------------------------------------------------------------- |
| `Kind/Bug`           | Something that used to work, or is documented to work, does not |
| `Kind/Feature`       | New functionality that does not exist yet                       |
| `Kind/Enhancement`   | Existing functionality gets better, faster, or nicer            |
| `Kind/Documentation` | Docs, ADRs, runbooks, agent guides                              |
| `Kind/Testing`       | Tests, CI checks, contract scripts                              |
| `Kind/Security`      | Secrets, auth, permissions, hardening, a vulnerability          |

Bug vs Enhancement, when it is unclear: if the current behaviour is wrong, it
is a bug. If the current behaviour is right but weak, it is an enhancement.

## Priority — how urgent (optional, at most one)

`Priority/Critical`, `Priority/High`, `Priority/Medium`, `Priority/Low`.

Leave it off if you do not know. A wrong priority is worse than none.

## Status — why it is not moving (optional, at most one)

| Label                   | Meaning                                      |
| ----------------------- | -------------------------------------------- |
| `Status/Blocked`        | Waiting on another issue, PR, or decision    |
| `Status/Need More Info` | Waiting on the reporter or on a human answer |
| `Status/Abandoned`      | Work started and stopped; nobody is on it    |

## Reviewed — the verdict (optional, at most one)

`Reviewed/Confirmed`, `Reviewed/Duplicate`, `Reviewed/Invalid`,
`Reviewed/Won't Fix`. Apply one of these when closing without a fix, so the
reason survives.

## Compat

`Compat/Breaking` — add it on top of the `Kind/*` label when the change breaks
something that already works for a player, an operator, or another repo.

## Workflow labels (repo-level, not org-level)

These live in the repo, not the org, and are orthogonal to the groups above:

- `ready-for-agent` — the spec is complete; an AFK agent may pick this up.
  No label means it needs a human.
- `wayfinder:map`, `wayfinder:task`, `wayfinder:research`,
  `wayfinder:prototype`, `wayfinder:grilling` — set by `/wayfinder`. Leave
  them alone unless you are running a wayfinder operation.
- `sow-nodebb` also has `package/*` labels naming the plugin or theme a ticket
  touches.

## When a skill names a label we do not have

Skills written elsewhere (mattpocock/skills and friends) use a different
vocabulary. Translate it:

| Skill says        | Do this here                                      |
| ----------------- | ------------------------------------------------- |
| `needs-triage`    | Nothing — no `Kind/*` label already means this    |
| `needs-info`      | `Status/Need More Info`                           |
| `ready-for-agent` | `ready-for-agent`                                 |
| `ready-for-human` | Nothing — absence of `ready-for-agent` means this |
| `wontfix`         | `Reviewed/Won't Fix`                              |

## Drift check

`ops/checks/check-labels.sh` in `sow-platform` runs nightly. It compares the
live org labels to `ops/policy/labels.yml` and lists every open issue and PR in
the org that does not have exactly one `Kind/*` label. That check is the
enforcement; this file is the rule.