auto-sync: 2026-06-03 10:50:01

tasks/orchestrator/DEV_TASK_PLANE_PER_AGENT_AUTHOR.md

@@ -0,0 +1,81 @@
+# DEV TASK — Plane: комментарии от имени агента-бота (per-agent authorship)
+
+**Проект:** orchestrator | **Сервер:** slin@82.22.50.71 | **Репо:** /home/slin/repos/orchestrator | **Контейнер:** orchestrator (8500)
+**Ветка:** `feature/plane-per-agent-author` из свежего main.
+
+⚠️ **ГРАБЛЯ push (ORCH-7):** после push `git log origin/main..origin/feature/plane-per-agent-author` ДОЛЖЕН показать коммиты ДО отчёта «PR готов».
+
+## Контекст (инфра УЖЕ готова — НЕ трогай БД/Plane)
+Слава хочет видеть в Plane, КТО написал комментарий (analyst/architect/dev/reviewer/tester/deployer/Стрим), а не единый `mva154`. В Plane автор = владелец токена.
+
+**Уже сделано (НЕ переделывай):** в Plane созданы 7 сервис-ботов с токенами, добавлены в воркспейс `ag_proj`. Токены лежат в `.env`:
+```
+ORCH_PLANE_BOT_ANALYST, ORCH_PLANE_BOT_ARCHITECT, ORCH_PLANE_BOT_DEVELOPER,
+ORCH_PLANE_BOT_REVIEWER, ORCH_PLANE_BOT_TESTER, ORCH_PLANE_BOT_DEPLOYER, ORCH_PLANE_BOT_STREAM
+```
+Дисплей-имена ботов в Plane: 🧠 Analyst / 🏗️ Architect / 💻 Developer / 🔍 Reviewer / 🧪 Tester / 🚀 Deployer / 🌊 Стрим.
+
+## Задача: `add_comment` постит ПОД ТОКЕНОМ АГЕНТА
+
+### 1. config (`src/config.py`)
+Добавить поля для 7 bot-токенов (env-имена выше, дефолт `""`). По образцу существующих `plane_*` полей.
+
+### 2. `src/plane_sync.py` — выбор токена по роли
+- Маппинг роль→токен, напр.:
+```python
+PLANE_BOT_TOKENS = {
+    "analyst":   settings.plane_bot_analyst,
+    "architect": settings.plane_bot_architect,
+    "developer": settings.plane_bot_developer,
+    "reviewer":  settings.plane_bot_reviewer,
+    "tester":    settings.plane_bot_tester,
+    "deployer":  settings.plane_bot_deployer,
+    "stream":    settings.plane_bot_stream,
+}
+def _headers_for(author: str | None) -> dict:
+    """X-API-Key headers for the given agent role; falls back to the default
+    orchestrator token (settings.plane_api_token) if role unknown/empty/token missing."""
+    tok = PLANE_BOT_TOKENS.get(author or "") if author else None
+    return {"X-API-Key": tok} if tok else PLANE_HEADERS
+```
+- `add_comment(work_item_id, text, project_id=None, author=None)` — НОВЫЙ необязательный параметр `author`. Внутри POST использовать `_headers_for(author)` ВМЕСТО глобального `PLANE_HEADERS`.
+- ⚠️ **GET/PATCH (find_issue_id, set_state) НЕ менять** — они служебные, пусть остаются под общим токеном. Меняем авторство ТОЛЬКО у комментариев (`add_comment` POST).
+- ⚠️ Если bot-токен пустой (не сконфигурён) → fallback на общий токен (автономность: комментарий всё равно постится, просто под orchestrator).
+
+### 3. Точки вызова — прокинуть author по роли стадии
+Для каждого `add_comment`/`plane_add_comment`/`_plane_comment`/`_add_comment`/`_pc` передать author = роль того агента, чьё это сообщение. Маппинг бери из `STAGE_TRANSITIONS` (`get_agent_for_stage`) или по смыслу текста:
+- **`src/stage_engine.py`** (284, 305, 316 — Analyst; 369 — после тестов rollback это Tester; 409 — Architect). Смотри по тексту сообщения, кто его «автор».
+- **`src/agents/launcher.py:472`** — автор = агент, который сейчас запускался (роль уже известна в этом контексте, см. сигнатуру launch).
+- **`src/webhooks/plane.py`** (212 «Analyst запущен» → analyst; 255 «Analyst перезапущен» → analyst; 267 «Откат» → агент целевой стадии; 310 и др. — по смыслу).
+- **`src/plane_sync.py`** сами хелперы: `notify_stage_change`/строка 255 (🔄 Stage) → author=`"stream"` (это голос оркестратора/мой); 260 (QG failed) → author соответствующего агента стадии; 267 (✅ Task completed) → author=`"deployer"` (деплой завершён) или `"stream"` — выбери deployer.
+- 🌊 **Стадии-переходы и общие уведомления оркестратора** (🔄 Stage, ✅ Completed) — author=`"stream"` (это я).
+
+Если для конкретной точки роль неочевидна — ставь `"stream"` (оркестратор) и отметь в отчёте. Лучше явный «Стрим», чем немой `mva154`.
+
+## Ограничения
+- 🚫 НЕ трогай: БД Plane, токены в .env (уже прописаны — только ЧИТАЙ через config), nginx, openclaw.json, deploy-хук, HMAC, очередь, stage_engine-логику переходов (только добавь author= в вызовы add_comment), STAGE_TRANSITIONS, get_next_work_item_id, M-6 код.
+- GET/PATCH остаются под общим токеном — меняем ТОЛЬКО авторство комментариев.
+- Baseline: **158 passed**, 9 pre-existing 401 — не чинить/не ломать.
+- Conventional Commits: `feat(plane): per-agent bot authorship for comments`, при желании отдельный `refactor` для config.
+
+## Тесты `tests/test_plane_author.py`
+- `_headers_for("analyst")` → `{"X-API-Key": <analyst token>}` (мок settings).
+- `_headers_for(None)` / неизвестная роль / пустой токен → fallback на `PLANE_HEADERS` (общий).
+- `add_comment(..., author="developer")` → httpx.post вызван с developer-заголовком (мок httpx, assert headers).
+- `add_comment(...)` без author → общий токен (обратная совместимость).
+- Тесты в контейнере: `IMG=$(docker inspect orchestrator --format '{{.Config.Image}}'); docker run --rm -v /home/slin/repos/orchestrator:/code -w /code --entrypoint python3 $IMG -m pytest tests/ -q`
+
+## Проверка (Стрим проверит вживую + реальным комментарием от каждого бота)
+| # | Что | Критерий |
+|---|-----|----------|
+| 1 | _headers_for | роль→bot-токен; неизвестно/пусто → fallback общий |
+| 2 | add_comment | author прокидывается в POST headers; без author → совместимость |
+| 3 | точки вызова | каждая передаёт осмысленный author (или stream) |
+| 4 | GET/PATCH | НЕ тронуты, под общим токеном |
+| 5 | тесты | 158 → 158+новые passed, 9 pre-existing не тронуты |
+| 6 | git | PR в main, remote содержит коммиты |
+
+## Отчёт
+- НЕ деплоить, НЕ мержить (мерж — Стрим). Токен Gitea для PR — рабочий из env контейнера (`docker exec orchestrator printenv | grep -i gitea`), .env-токен может быть 401.
+- Запушь ветку (ПРОВЕРЬ remote!), открой PR в main. В отчёте: таблица «точка вызова → выбранный author».
+- Если расходится с кодом — отчитайся, не выдумывай. Один исполнитель.