From 335680889bd35acd8f8f2dcbe96caf8602a9dd98 Mon Sep 17 00:00:00 2001 From: vickydotbat Date: Wed, 5 Aug 2026 17:46:34 +0200 Subject: [PATCH] docs(agents): tea 0.15 applies org labels; tea api still cannot write MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/agents/issue-tracker.md | 43 ++++++++++++++++++------------------ docs/agents/triage-labels.md | 12 +++++++--- 2 files changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 1ae498c..6313d66 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -57,28 +57,27 @@ preference — move it. so any non-interactive shell (every agent) hangs forever without `/labels` endpoints. -- **Org-level labels (`Kind/*`, `Priority/*`, `Reviewed/*`, `Status/*`)**: `tea - issues edit --add-labels` / `--remove-labels` do **not** apply these on tea - 0.14.0, the version nixpkgs pins. Name resolution searches only this repo's - own label set, so an org label matches nothing and the command exits 0, - prints the issue, and changes nothing — no error, no warning. Repo-local - labels (`wayfinder:*`, `ready-for-agent`) are unaffected. PRs no-op the same - way. Upstream fixed it in v0.15 (`modules/task/labels.go` now also queries - `ListOrgLabels`), so this expires when tea is bumped; until then apply org - labels in the web UI. Note `tea labels` lists repo labels only, so it will - not show you the org set either — `tea api orgs/ShadowsOverWestgate/labels` - does. -- **Verify every label change by re-reading it.** `tea issues ls -o json` has a - `labels` field; use it. A label command exiting 0 is not evidence it applied, - and assuming otherwise has already cost one investigation several wrong turns. - `tea issues edit --add-labels` works too, org-level labels (`Kind/*`, - `Priority/*`) included, but a read-back straight afterwards can still show - the old set — `tea issues ls` has returned stale labels for several seconds - after an edit that succeeded. Never conclude an edit failed from a single - immediate list; re-read after a pause, or use the `labels` endpoints above, - whose response *is* the resulting label set and needs no second call. +- **Apply / remove labels**: `tea issues edit --add-labels "Kind/Bug"` + (and `--remove-labels`). This handles org-level labels (`Kind/*`, + `Priority/*`, `Reviewed/*`, `Status/*`) from tea 0.15 onwards. On 0.14 it did + not: name resolution searched only this repo's own label set, so an org label + matched nothing and the command exited 0, printed the issue, and changed + nothing. Upstream fixed it in v0.15 (`modules/task/labels.go` also queries + `ListOrgLabels`). Note `tea labels` lists repo labels only and will not show + you the org set — `tea api orgs/ShadowsOverWestgate/labels` does. +- **`tea api` can read but not write.** Writing methods (`--method POST`, + `PATCH`, ...) return `{"message":"token is required"}`. GETs against these + public repos succeed anonymously, which makes the gap easy to miss: reads + work, writes do not. Use the `tea issues` / `tea pr` subcommands for anything + that changes state. +- **Verify every label change by re-reading it.** A label command exiting 0 is + not evidence it applied — that is exactly how the 0.14 silent no-op above hid + for so long, and assuming otherwise has already cost one investigation + several wrong turns. Read the resulting set back with + `tea api repos/ShadowsOverWestgate/sow-tools/issues/` and check its + `labels` field, or `tea issues ls -o json`. The read-back reflects the write + immediately; if it comes back empty, the write genuinely failed. Do not + explain an empty read-back away as replication lag. - **Close**: `tea issues close ` `tea` infers the repo from the git remote when run inside the clone. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index f5408bc..195268a 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -24,11 +24,17 @@ this. tea issues create --title "..." --description "..." --labels "Kind/Bug" /issues//labels" \ - --data '{"labels":["Kind/Bug","Priority/High"]}' +# add a label to something that already exists (needs tea >= 0.15 for org labels) +tea issues edit --add-labels "Kind/Bug,Priority/High" + +# read the result back — exit 0 is not evidence the label applied +tea api "repos/ShadowsOverWestgate//issues/" ``` +`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 |