BRD — ORCH-046: pass reviewer/tester findings text to developer (not just link)

Work Item ID: ORCH-046 Stage: analysis Author: analyst Date: 2026-06-06

1. Контекст и проблема

Оркестратор при заворотах задачи деву (откат на development) формирует описание задачи (task_desc), которое попадает в .task-dev.md запускаемого агента-разработчика. Сейчас в двух ветках отката этот текст содержит только ссылку на файл-артефакт, без сути замечаний:

Reviewer → REQUEST_CHANGES (src/stage_engine.py, ветка _handle_qg_failure_rollbacks, ~стр. 419): task_desc = "…Fix findings in docs/work-items/<id>/12-review.md".
Tester → FAIL (check_tests_passed, ~стр. 455): task_desc = "…Fix failures described in docs/work-items/<id>/13-test-report.md".

В результате developer-агент получает инструкцию «иди читай файл». Ключевые претензии (P0/P1 у ревьюера, причина падения у тестера) часто проскакивают — агент не открывает файл целиком или теряет фокус, повторяет ту же ошибку, и задача снова заворачивается. Это «испорченный телефон»: расход циклов retry (MAX_DEVELOPER_RETRIES = 3), деньги на токены, простой конвейера.

2. Бизнес-цель

Убрать «испорченный телефон» между reviewer/tester и developer при заворотах: встраивать дословный текст ключевых замечаний прямо в task_desc, чтобы developer-агент видел суть претензий сразу, а не только ссылку.

Это снижает число повторных заворотов и расход retry-бюджета на одну задачу.

3. Объём (вариант A — выбран Славой 06.06)

Минимальное, низкорисковое изменение ядра (stage_engine), которое:

Извлекает из 12-review.md блок findings и выносит must-fix (P0/P1) дословно в task_desc при reviewer REQUEST_CHANGES.
Извлекает из 13-test-report.md причину FAIL (reason из гейта + релевантный фрагмент тела отчёта) в task_desc при tester FAIL.
Во всех случаях сохраняет ссылку на полный файл как дополнительный контекст («полный контекст — см. файл»).
Извлечение выполняется новым отдельным хелпером-парсером (src/review_parse.py), который никогда не бросает исключение: при отсутствующем/битом файле возвращает пустой результат, и вызывающий код делает graceful fallback на прежнюю ссылку-строку.

4. Что НЕ входит в объём (out of scope)

НЕ трогать гейты check_* (в т. ч. ORCH-45 check_ci_green, ORCH-47 _parse_tests_verdict) — они в проде, поведение неизменно.
НЕ трогать реестр QG_CHECKS.
НЕ менять сигнатуры публичных функций (advance_stage, _run_qg, check_*).
НЕ менять webhook-пути.
НЕ менять retry-счётчик (_developer_retry_count, MAX_DEVELOPER_RETRIES) и rollback-логику (последовательность update_task_stage → notify_stage_change → plane_notify_stage → enqueue) — поведение идентично.
НЕ менять формат Plane-комментариев (build_status_comment).

5. Заинтересованные стороны

Owner (Слава) — заказчик, выбрал вариант A.
Developer-агенты — потребители task_desc: получают суть замечаний.
Конвейер всех проектов (self-hosting) — выигрывает за счёт меньшего числа заворотов.

6. Ограничения и риски (self-hosting)

Правка ядра stage_engine — компонент крутится в продакшене и обслуживает все проекты из общего инстанса/БД/очереди. Любая регрессия в формировании task_desc или (тем более) исключение в advance_stage останавливает конвейер всех проектов → парсер обязан быть полностью graceful.
Обязателен прогон deploy-staging (8501) перед прод-деплоем.
Это правка ядра → требуется ADR (per-work-item).

7. Критерий успеха (бизнес)

При заворотах в .task-dev.md есть дословный текст ключевых замечаний (P0/P1 ревьюера; reason+фрагмент тестера) плюс ссылка на полный файл.
Парсер устойчив к битым/отсутствующим артефактам (graceful fallback на старую ссылку-строку).
Существующие тесты зелёные; поведение retry/rollback не изменилось.

5.8 KiB Raw Permalink Blame History Unescape Escape