reviewer(ET): auto-commit from reviewer run_id=117

docs/work-items/ORCH-017/12-review.md

@@ -0,0 +1,72 @@
+---
+type: review
+work_item_id: ORCH-017
+verdict: APPROVED
+version: 1
+---
+
+# Review ORCH-017
+
+## Summary
+PR добавляет в пингующее уведомление об апруве BRD (`notify_approve_requested`) две
+кликабельные HTML-ссылки — на `01-brd.md` в Gitea (branch-view) и на issue в Plane.
+Реализация полностью соответствует ТЗ (`02-trz.md`), всем 10 критериям приёмки
+(`03-acceptance-criteria.md`) и принятому ADR-001. Все 434 теста зелёные, документация
+обновлена в этом же PR. Блокеров и must-fix findings нет.
+
+## Соответствие ТЗ и AC
+- **AC-1 / AC-2** — BRD- и Plane-ссылки строятся (`_build_brd_link`, `_build_plane_issue_link`),
+  встроены в текст того же сообщения (TC-01/TC-02). ✔
+- **AC-3** — фолбэки `gitea_public_url→gitea_url` и `plane_web_url→plane_api_url` соблюдены (TC-03). ✔
+- **AC-4** — призыв «Переведите задачу в статус Approved …» сохранён (TC-04). ✔
+- **AC-5** — ровно одно пингующее (не silent) сообщение; `send_telegram` не дублируется,
+  трекер обновляется как раньше (TC-05). ✔
+- **AC-6** — graceful degradation: SELECT полей в try/except, каждая ссылка строится
+  независимо и опускается при нехватке данных; loopback-guard выкидывает localhost-URL
+  (TC-06/07/07b). Исключения не пробрасываются. ✔
+- **AC-7** — `parse_mode=HTML` сохранён, динамические подписи через `html.escape`,
+  корректная `<a>`-разметка (TC-08/08b). ✔
+- **AC-8** — логика апрува не тронута: в `src/` изменены только `config.py` и
+  `notifications.py`; `qg/checks.py`, `stages.py`, `:approved:`-handler без изменений. ✔
+- **AC-10** — `pytest tests/ -q` → 434 passed. ✔
+
+## Соответствие ADR
+- **Р-1** — HTML-ссылки в тексте, сигнатура `send_telegram` НЕ изменена (inline-кнопки
+  отклонены) — blast radius минимальный, безопасно для self-hosting. ✔
+- **Р-2** — полный путь Plane по uuid `{web_base}/{workspace}/projects/{project_id}/issues/{issue_id}/`. ✔
+- **Р-3** — новая настройка `ORCH_PLANE_WEB_URL` + loopback-guard (`_is_loopback_base`,
+  набор `localhost/127.0.0.1/0.0.0.0/::1`, пустой URL = unusable). ✔
+- **Р-4 / Р-5** — graceful degradation как контракт; порядок действий
+  `mark_brd_review_started → update_task_tracker → send_telegram` сохранён. ✔
+
+## Качество кода
+- Публичные/вспомогательные функции снабжены содержательными docstrings со ссылками на AC/ADR.
+- Защитные try/except вокруг I/O (БД, projects), логирование без падения потока.
+- Тесты содержательные, замаплены на TC-01…TC-08 из `04-test-plan.yaml`, сеть и БД изолированы.
+
+## Findings
+
+### P0 — Blocker
+- нет
+
+### P1 — Must fix
+- нет
+
+### P2 — Should fix
+- нет
+
+### P3 — Nice-to-have
+- [ ] `docs/architecture/README.md` не обновлён — но и не требует обновления: API,
+  стадии, реестр QG и компоненты не менялись (правка — отображение, не управление).
+  Env-карта обновлена в `docs/operations/INFRA.md`, что корректно. Замечание косметическое.
+
+## Документация
+Обновлена корректно и в этом же PR:
+- `CHANGELOG.md` — запись о фиче (раздел Unreleased/Added). ✔
+- `.env.example` — новая `ORCH_PLANE_WEB_URL` с описанием фолбэка и loopback-семантики. ✔
+- `docs/operations/INFRA.md` — env-карта дополнена `ORCH_PLANE_WEB_URL`. ✔
+- `src/config.py` — поле документировано inline-комментарием. ✔
+- ADR `docs/work-items/ORCH-017/06-adr/ADR-001-telegram-approve-links.md` — фиксирует выбор
+  формата (HTML vs кнопки) и формат Plane-URL. ✔
+
+Требование «изменён src/ → обновлена документация» выполнено.