From ff8260536f3b6e6900dd77ba700646e53c50efb4 Mon Sep 17 00:00:00 2001 From: domverse Date: Wed, 15 Jul 2026 22:03:58 +0200 Subject: [PATCH] docs: explain why work-item cannot move Gitea board cards work-item tracks story stage via status/* labels and issue open/close (the board), not Gitea project-board columns. Gitea's REST API exposes no project endpoints and its web move-endpoints need a logged-in session; an API token only authenticates /api/*. Document the label-as-board approach and the limitation in the README and AGENTS.md. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 5 +++++ work_item/README.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2f4e6a6..dbf9e0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,11 @@ repository intentionally keeps its configuration inside `work_item/.work-item.ym Do not change its repository identity, required tests, allow list, deny list, size limit, or CI policy merely to bypass a workflow failure. +Story stage is tracked by `status/*` labels and issue open/close, which serve as the +board; `work-item` does not move cards between Gitea project-board columns (Gitea's API +cannot move cards). Use label-filtered issue views instead — see +`work_item/README.md` → "Kanban / project board position". + Workflow state is local at `.git/work-item-state.json` and must never be committed. `claim` is resume-aware: diff --git a/work_item/README.md b/work_item/README.md index 687fd6c..74448b2 100644 --- a/work_item/README.md +++ b/work_item/README.md @@ -187,6 +187,37 @@ shown above. `--test` is repeatable. Configured `required_tests` are always included, and duplicate commands are run only once. +## Kanban / project board position + +`work-item` tracks each story's stage with the `status/*` **labels** +(`status/backlog` → `status/in-progress` → `status/review` → `status/done`, plus +`status/blocked`) and by opening/closing the issue. **These labels are the board.** + +It does **not** move cards between columns of a Gitea *project* (Kanban) board, and +this is a Gitea limitation rather than a gap in the helper: + +- Gitea's REST API (checked against 1.25) exposes **no** project/column/board + endpoints — the swagger spec has none, and `tea` has no project command. +- Card movement uses Gitea's internal *web* endpoints, which require a logged-in + browser session (session cookie + CSRF). An **API token authenticates only + `/api/*`, not web routes** (a token request to a web page redirects to + `/user/login`), so the helper — which is token-only by design — cannot reach them. +- Gitea does not auto-move a closed issue into a "Done" column either. A closed story + keeps whichever column it was in. + +**Recommended: use the labels as the board.** Filter the issue list by label to get an +equivalent view without touching the unreachable board, e.g.: + +```text +/domverse/photoanalyzer/issues?labels=status/in-progress +/domverse/photoanalyzer/issues?labels=status/review +/domverse/photoanalyzer/issues?q=&type=all&labels=status/done&state=closed +``` + +If a project board must show card positions, move the cards manually in the web UI, or +drive the web endpoints from a real browser session (out of scope for this token-only +helper). Do not store web login credentials in the helper to work around this. + ## Safety model Before submission, the helper: -- 2.49.1