archvillainetteandClaude Opus 5
335680889b
ci / ci (pull_request) Canceled after 2m21s
Mirrors ShadowsOverWestgate/sow-topdata@8c5f4d8 into this repo's copy of the shared agent docs. nixpkgs now ships tea 0.15.1, so `tea issues edit --add-labels` applies `Kind/*` and the rest of the org set. The 0.14 ceiling stays documented as history for anyone on a pinned older tea. Two things outlived the bump. `tea api` cannot write at all — any `--method POST`/`PATCH` returns `{"message":"token is required"}`, while GETs succeed anonymously because these repos are public. Both files prescribed a `tea api` labels endpoint for labelling an existing issue; that recipe has never worked. It now points at `tea issues edit`. The read-back rule stays, with its reasoning corrected. The note had grown a claim that `tea issues ls` returns stale labels for several seconds after a successful edit, and warned against concluding failure from an immediate read. That was the 0.14 silent no-op misread as replication lag — the read-back was accurate both before and after the bump, and waiting it out would convert a real failure into an assumed success. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
# 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` writes (`--method POST`, `PATCH`, ...) fail with
|
|
`{"message":"token is required"}`; only reads work anonymously. Label changes
|
|
go through `tea issues edit`.
|
|
|
|
## 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.
|