docs/agents/issue-tracker.md

@@ -46,6 +46,45 @@
   уже с сохранённым токеном, например
   `tea api repos/ddmitry/clickstream-data-platform/issues/18`.
 
+## Правка тела issue — только через API
+
+Тикнуть чекбокс в критериях приёмки нужно при закрытии каждой задачи, и `tea`
+для этого не годится. `tea issues edit --description` принимает тело **целиком
+строкой**, а взять эту строку неоткуда: `tea issues <номер>` печатает текст
+обёрнутым и разрисованным для терминала, обратно его не скормишь.
+
+Рабочий путь — забрать сырое тело из API, поправить и вернуть:
+
+```sh
+# 1. сырой JSON тикета; тело — в поле body
+tea api repos/{owner}/{repo}/issues/<n> > issue.json
+
+# 2. правка тела любым удобным способом, например все чекбоксы разом
+python3 -c "
+import json
+d = json.load(open('issue.json'))
+json.dump({'body': d['body'].replace('- [ ]', '- [x]')},
+          open('patch.json', 'w'), ensure_ascii=False)
+"
+
+# 3. вернуть
+tea api -X PATCH -d @patch.json repos/{owner}/{repo}/issues/<n>
+```
+
+Флаги `tea api`: `-X` — метод, `-d` — сырое тело JSON (`@файл` читает из файла,
+`@-` из потока ввода), `-f` и `-F` — отдельные поля строкой и с типом. Флага
+`--input` нет, хотя рука тянется написать именно его.
+
+Тот же приём — для чек-листа родительской карты: пункт `- [ ] #NN` тикается
+правкой её тела, автоматически Gitea этого не делает.
+
+**Отсюда общее правило.** `tea` удобен там, где команда создаёт объект или
+меняет его свойство: создать issue, добавить комментарий, повесить метку,
+назначить исполнителя, закрыть. Как только нужно **изменить уже написанный
+текст** — тело issue, тело PR, — CLI мешает: он умеет только заменить всё
+целиком, а прочитать это «всё» в пригодном для правки виде не даёт. Такие
+операции идут прямо в API.
+
 ## Слияние PR не закрывает issue
 
 Gitea понимает только английские ключевые слова автозакрытия: `closes`,
@@ -59,7 +98,8 @@ PR #17, где issue #13 пришлось закрывать руками.
 
 Если ключевого слова не было, порядок после слияния: закрыть задачу
 (`tea issues close <номер>`) и тикнуть её пункт в чек-листе родительского
-issue этапа — Gitea чек-листы сама не обновляет.
+issue этапа — Gitea чек-листы сама не обновляет. Чем тикать — выше, в разделе
+про правку тела.
 
 ## Спека — источник истины
 
@@ -119,6 +159,11 @@ issue этапа — Gitea чек-листы сама не обновляет.
 
 ## Что проверено и когда
 
+2026-08-06: правка тела issue через `tea api -X PATCH -d @файл` снята живыми
+запросами при закрытии #37 — так проставлены чекбоксы самого тикета и пункт
+в чек-листе карты #4. Тогда же проверено, что `tea issues edit --description`
+для этого непригоден, а флага `--input` у `tea api` нет.
+
 2026-07-31: Gitea 1.27.0 (`tea api version`), `tea` 0.15.0. Живыми запросами по
 этому репозиторию проверены `tea labels list` и `tea issues list`. Остальной
 набор команд, флагов и приёмы с `tea api` перенесены из доки