orchestrator/docs/work-items/ORCH-016/02-trz.md

ТЗ: Единообразные коммент-артефакты в Plane от всех агентов

Work Item ID: ORCH-016 Стадия: analysis → architecture → development Автор: analyst Дата: 2026-06-05

Контракт: что именно меняем в коде / какие модули задействованы / какие проверки появятся. Архитектурные решения принимает архитектор; здесь — границы изменения.

---

1. Задействованные модули

Модуль	Роль в изменении
src/usage.py	Главная точка изменения. Здесь сейчас живут usage_comment(), artifact_links(), AGENT_ARTIFACT, AGENT_DISPLAY, AGENT_ICON — основа форматирования. Нужно расширить/добавить хелпер построения единого status-коммента.
src/stage_engine.py	Эталонная функция аналитика _build_analyst_ready_comment(). По возможности — переиспользовать новый общий хелпер (или хотя бы выровнять формат: emoji + заголовок + описание + список ссылок).
src/agents/launcher.py	_post_usage_comments() — точка, где постится коммент по завершении агента (architect/developer/reviewer/tester/deployer). Должен звать новый хелпер.
src/plane_sync.py	add_comment() — без изменений (используется как транспорт).
src/qg/checks.py	Только для чтения: модели парсинга frontmatter verdict: / deploy_status: / staging_status: — переиспользуем эту логику (вынести в отдельную утилитку, либо импортировать там, где она уже есть).
src/config.py	settings.gitea_public_url, settings.gitea_owner, settings.gitea_url — без изменений, переиспользуются.

2. Контракт нового коммент-формата

2.1 Структура (одинакова для всех агентов)

{ICON} {RoleName} — {one-line human description of stage result}

[Verdict / Status: <VALUE>]            # опционально, см. 2.3
<b>Документы:</b>
  • <a href="…">{label}</a>            # одна или несколько ссылок

Поля:

• {ICON} — берётся из AGENT_ICON (уже есть в usage.py).
• {RoleName} — из AGENT_DISPLAY (уже есть).
• {description} — фиксированная строка на роль, см. 2.2.
• Verdict / Status — см. 2.3, опускается если не извлекается.
• Ссылки — см. 2.4.

2.2 Описания стадий (per-agent text)

Агент	Описание (рус.)
analyst	«Подготовил BRD / ТЗ / Acceptance Criteria. Для продвижения переведите задачу в статус Approved.» (как сейчас в _build_analyst_ready_comment)
architect	«Завершил архитектурную проработку. См. ADR ниже.»
developer	«Завершил разработку. См. PR / branch ниже.»
reviewer	«Завершил ревью изменений.»
tester	«Завершил прогон тестов.»
deployer	«Завершил деплой.»

Точные формулировки финализирует architect; аналитик фиксирует факт наличия 1-предложного описания на каждую роль.

2.3 Verdict / Status строка

Печатается отдельной строкой над списком документов. Источник — frontmatter артефакта; парсить идемпотентно (если файл недоступен — строку пропустить):

Агент	Поле	Где парсим	Возможные значения	Формат строки
analyst	—	—	—	не печатается
architect	—	—	—	не печатается
developer	—	—	—	не печатается (CI-статус — отдельный гейт)
reviewer	verdict:	docs/work-items/<wid>/12-review.md (YAML-frontmatter)	APPROVE / REQUEST_CHANGES	Verdict: APPROVE
tester	verdict: (или эквивалентный фронт-кей)	docs/work-items/<wid>/13-test-report.md	PASS / FAIL	Verdict: PASS
deployer	staging_status: (для deploy-staging) / deploy_status: (для deploy)	15-staging-log.md / 14-deploy-log.md	SUCCESS / FAILED	Status: SUCCESS

Если значение в frontmatter отсутствует или не распознано → строка Verdict / Status НЕ выводится (вердикт-парсинг гейтов и сама логика гейтов не меняется).

2.4 Ссылки на артефакты

Базовый URL: (settings.gitea_public_url or settings.gitea_url).rstrip('/'). Префикс: /{owner}/{repo}/src/branch/{branch}/.

Агент	Артефакты (label → путь)
analyst	BRD 01-brd.md, ТЗ 02-trz.md, AC 03-acceptance-criteria.md, Test Plan 04-test-plan.yaml (уже есть)
architect	ADR-папка docs/work-items/<wid>/06-adr/ (уже есть)
developer	Branch …/src/branch/<branch>, PR …/pulls/<num> (уже есть)
reviewer	Review docs/work-items/<wid>/12-review.md (уже есть)
tester	Test report docs/work-items/<wid>/13-test-report.md (уже есть)
deployer	Deploy log docs/work-items/<wid>/14-deploy-log.md; staging-лог 15-staging-log.md (если применимо к стадии)

Несуществующий файл в worktree → ссылка опускается (как сейчас в _build_analyst_ready_comment).

2.5 Один коммент на агента за стадию

Текущий триггер — _post_usage_comments() вызывается один раз в успешном auto-advance пути после агента. Никаких новых триггеров не добавляем. Дубликаты исключены текущей логикой (одно завершение агента → один коммент).

2.6 Usage-метрики (токены / стоимость)

Текущий usage_comment() встраивает «8.5M in / 45.8k out · $7.29» в первый строкой. По требованиям Славы это «без раздувания», но не запрещено явно. Решение:

• Сохранить usage-метрику как последнюю строку коммента (мелким техническим хвостом, например <sub>8.5M in / 45.8k out · $7.29</sub>), либо
• Перенести в task_summary_comment (только для финального deployer-summary).

Финальный выбор — за архитектором (см. вопрос Q-1 в 10-tech-risks.md).

2.7 Бот-авторство

plane_add_comment(..., author=<role>) — сохраняется. Все агенты комментируют под своим bot-токеном (PLANE_BOT_TOKENS). Изменения формата текста на это не влияют.

3. Изменения API

Нет. Внешние webhooks (/webhook/plane, /webhook/gitea), /health, /status, /queue — не меняются.

4. Изменения схемы БД

Нет. Используются существующие таблицы tasks, agent_runs, jobs.

5. Новые Quality Gate checks

Нет. Гейты не меняются. Парсинг verdict: / deploy_status: / staging_status: в коммент — отдельная утилитка, не QG.

6. Требования к коду

• Все новые функции — с docstring (зачем нужны, какие инварианты сохраняют).
• Парсинг frontmatter артефакта — graceful: исключение → строка вердикта опускается, лог в logger.debug.
• Никаких новых внешних зависимостей: использовать pyyaml (уже в проекте) или существующий парсер frontmatter из src/qg/checks.py.
• Поведение для проектов без артефактов (например, ENDURO-* до запуска агента) — graceful no-op: коммент с описанием и без ссылок (минимум — заголовок).
• HTML (как у аналитика) предпочтительнее markdown — Plane корректно рендерит <ul><li><a> и <b>.

7. Артефакты по pipeline

• 06-adr/ — не требуется (нет архитектурного сдвига; обсуждается локально архитектором, в случае спорного решения по 2.6 — заводим ADR ADR-001-status-comment-format.md).
• 07-infra-requirements.md — не требуется (нет новой инфраструктуры).
• 08-data-requirements.md — не требуется (БД не меняется).
• 12-review.md / 13-test-report.md / 14-deploy-log.md — формируются на соответствующих стадиях по канону.
• CHANGELOG.md — обновить в том же PR (раздел Unreleased).

8. Документация

В том же PR обновить:

• docs/architecture/README.md — короткое упоминание единого формата комментов (можно в раздел «Plane Sync»).
• docs/architecture/internals.md — если там есть раздел про usage.py/комменты — обновить.
• CLAUDE.md — без изменений (правила не меняются).

9. Чего НЕ делать

• Не менять реестр QG_CHECKS.
• Не менять STAGE_TRANSITIONS.
• Не менять add_comment / _headers_for / PLANE_BOT_TOKENS.
• Не «комментировать» комменты других стадий задним числом.
• Не использовать --no-verify при коммитах.