121 lines
7.4 KiB
Markdown
121 lines
7.4 KiB
Markdown
---
|
||
type: review
|
||
work_item_id: ORCH-016
|
||
verdict: APPROVED
|
||
version: 1
|
||
---
|
||
|
||
# Review ORCH-016 — Единый status-коммент агентов в Plane
|
||
|
||
## Summary
|
||
|
||
PR реализует ТЗ ORCH-016 и ADR-001 полностью: вводится единый хелпер
|
||
`src/usage.build_status_comment(...)` для всех ролей (analyst…deployer),
|
||
строка `Длительность: …` с явным `duration_s` от launcher и DB-фоллбэком для
|
||
аналитика, defensive YAML-парсер `src/frontmatter.read_frontmatter_value`,
|
||
HTML-формат с эмодзи / Verdict / Документы / `<sub>` тех-хвостом. Аналитик
|
||
переведён на ту же ветку без регрессии (`tests/test_analyst_comment.py` +
|
||
`tests/test_analyst_status_only_regression.py` зелёные). `usage_comment` стал
|
||
deprecated-обёрткой, `artifact_links` теперь возвращает HTML-фрагменты
|
||
(breaking-change только для внутреннего вызова из удаляемого пути).
|
||
Документация обновлена: CHANGELOG.md (`Added` + `Changed`),
|
||
`docs/architecture/README.md` (новый подраздел «Plane Sync: единый
|
||
status-коммент агентов»), ADR-001 заведён в
|
||
`docs/work-items/ORCH-016/06-adr/`.
|
||
|
||
Прохождение тестов:
|
||
- 60 новых ORCH-016 тестов: PASS (TC-01…TC-23 покрывают AC-1…AC-14).
|
||
- TC-20 (`test_qg_registry_snapshot.py`) подтверждает: `QG_CHECKS` и
|
||
`STAGE_TRANSITIONS` бит-идентичны (AC-11).
|
||
- Полный прогон: 392 PASS, 4 FAIL (`tests/test_m6_sequence.py::*`,
|
||
`tests/test_plane_webhook.py::test_orchestrator_project_routes_to_orchestrator_repo`,
|
||
`tests/test_plane_webhook.py::test_prefixes_independent_per_project`).
|
||
Эти 4 фейла **предсуществуют на `main`** (проверено: `git checkout main --
|
||
src/ tests/` → те же 4 фейла; ORCH-016 их не индуцировал). AC-10 «no
|
||
regression» соблюдено.
|
||
|
||
Соответствие ТЗ (`02-trz.md`):
|
||
- §1 модули: тронуты строго заявленные (`usage.py`, `stage_engine.py`,
|
||
`agents/launcher.py`, новый `frontmatter.py`); `qg/checks.py` сознательно
|
||
не трогается (ADR-001 §5, alt-6).
|
||
- §2.1–§2.5 формат, описания, verdict, ссылки, duration — реализовано.
|
||
- §3 API не меняется; §4 БД не меняется; §5 новых QG нет — подтверждено
|
||
TC-20.
|
||
- §6 docstrings, graceful frontmatter / duration, `fmt_duration` — чистая,
|
||
AC-13 happy + edge кейсы зелёные.
|
||
- §7 артефакты: ADR заведён.
|
||
- §8 документация: README архитектуры и CHANGELOG обновлены, `CLAUDE.md`
|
||
не трогается (правила не меняются).
|
||
- §9 запреты: `QG_CHECKS` / `STAGE_TRANSITIONS` / `add_comment` /
|
||
`_headers_for` / `PLANE_BOT_TOKENS` не тронуты; `--no-verify` не
|
||
использован.
|
||
|
||
Соответствие ADR-001:
|
||
- §1 единственный публичный `build_status_comment(...)` с указанной
|
||
сигнатурой ✓
|
||
- §2 описания per-agent ✓
|
||
- §3 `<sub>` тех-хвост ✓
|
||
- §4 русская метка `Длительность:` ✓
|
||
- §5 `src/frontmatter.py` ✓
|
||
- §6 `get_agent_duration` с указанным SQL ✓
|
||
- §7 HTML-якоря, `<br>` разделители ✓
|
||
- §8 `fmt_duration` контракт ✓
|
||
|
||
Self-hosting (ADR-001 «Последствия»): хелперы — чистый код, без рестарта
|
||
прод-контейнера; пройдёт стандартный staging-гейт.
|
||
|
||
## Findings
|
||
|
||
### P0 — Blocker
|
||
- Нет.
|
||
|
||
### P1 — Must fix
|
||
- Нет.
|
||
|
||
### P2 — Should fix
|
||
- Нет.
|
||
|
||
### P3 — Nice to have
|
||
- `src/usage.py` `_AGENT_DESCRIPTIONS` и встроенные строки в
|
||
`build_status_comment` (например, `"Длительность: " f"{d_text}"` и
|
||
`"Завершил " "архитектурную " "проработку. " "См. ADR ниже."`) разбиты
|
||
на множественные смежные литералы. Python склеит их корректно, но
|
||
читаемость страдает — рассмотреть однострочный литерал в follow-up.
|
||
- `03-acceptance-criteria.md` AC-3 формулирует пример как
|
||
`verdict: APPROVE`, тогда как канонический QG (`check_reviewer_verdict`,
|
||
`src/qg/checks.py:306`) ожидает строго `verdict: APPROVED`. На
|
||
отображение коммента это не влияет (билдер показывает то, что лежит
|
||
во frontmatter), но в самом AC лучше было бы зафиксировать тот же
|
||
термин, что в QG. Чинить артефакт стадии analysis из стадии review —
|
||
out-of-scope (правило: «не править артефакты других этапов»);
|
||
оставляю как заметку на follow-up для аналитика.
|
||
- `_post_usage_comments` для `deployer` всегда (включая
|
||
`deploy-staging`) дополнительно постит `task_summary_comment`. ТЗ §2.6
|
||
и AC-7 явно это не запрещают (саммари не считается status-комментом),
|
||
и `tests/test_post_usage_comments_integration.py::test_deployer_staging_picks_15_log`
|
||
это поведение фиксирует. Поведение работает, но смысловой саммари
|
||
«Итого по задаче» на staging-стадии (задача не завершена) — слегка
|
||
ранний. Кандидат на уточнение требований в отдельной задаче.
|
||
|
||
## Документация
|
||
|
||
- `CHANGELOG.md` — раздел `Unreleased` дополнен записями `Added` и
|
||
`Changed` с упоминанием ORCH-016, `build_status_comment`,
|
||
`fmt_duration`, `get_agent_duration`, `src/frontmatter.py` и
|
||
ссылки на ADR. ✓
|
||
- `docs/architecture/README.md` — добавлен подраздел «Plane Sync:
|
||
единый status-коммент агентов (ORCH-016)» с описанием формата
|
||
HTML-блока, источниками длительности и вердиктов, явным указанием,
|
||
что реестр гейтов и стадий не меняется. ✓
|
||
- `docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md` —
|
||
заведён, статус `Accepted`, покрывает все 5 открытых вопросов ТЗ
|
||
и пять альтернатив. ✓
|
||
- `CLAUDE.md` — правки не требовались (правила агентов и канон
|
||
документации без изменений), что и заявлено в ADR-001.
|
||
- `docs/architecture/internals.md` — упоминания про `usage.py` /
|
||
комменты не имеет, обновление не требуется (как и оговорено
|
||
ADR-001 §1).
|
||
|
||
Документация = golden source соблюдён: изменения в `src/` сопровождены
|
||
синхронным обновлением документации в том же PR.
|