Compare commits
1 Commits
feature/OR
...
docs/ORCH-
| Author | SHA1 | Date | |
|---|---|---|---|
| 8149eb7769 |
24
.env.example
24
.env.example
@@ -12,25 +12,11 @@ ORCH_GITEA_WEBHOOK_SECRET=
|
||||
ORCH_CLAUDE_BIN=/usr/bin/claude
|
||||
ORCH_REPOS_DIR=/home/slin/repos
|
||||
ORCH_DB_PATH=/app/data/orchestrator.db
|
||||
# ORCH-042/ORCH-067: live-tracker mode. bump (DEFAULT since ORCH-067) -> on every
|
||||
# update the old card is deleted and a fresh one is sent silently to the BOTTOM of
|
||||
# the chat (deleteMessage + sendMessage + repoint), so the current status is always
|
||||
# the last message in an active chat. edit -> the task card is edited in place
|
||||
# (editMessageText). One card per task in both modes. Any value other than "bump"
|
||||
# (incl. empty/garbage) -> edit.
|
||||
ORCH_TRACKER_MODE=bump
|
||||
# ORCH-067: best-effort live-overlay for the card status line. The offline core
|
||||
# (stage -> Plane status, In Review from the brd-clock) always works without network;
|
||||
# the overlay only fills in branches indistinguishable offline (Needs Input / Blocked /
|
||||
# Rejected / Cancelled / Deploying / Monitoring after Deploy) by reading the LIVE Plane
|
||||
# status with a short timeout + per-issue TTL cache. It NEVER blocks the pipeline and
|
||||
# NEVER raises.
|
||||
# LIVE_STATUS -> kill-switch (false -> offline core only).
|
||||
# LIVE_STATUS_TTL_S -> TTL (seconds) of the per-issue live-uuid cache (hot-path guard).
|
||||
# LIVE_STATUS_TIMEOUT_S -> timeout (seconds) of a single live-GET on the render path.
|
||||
ORCH_TRACKER_LIVE_STATUS=true
|
||||
ORCH_TRACKER_LIVE_STATUS_TTL_S=60
|
||||
ORCH_TRACKER_LIVE_STATUS_TIMEOUT_S=3
|
||||
# ORCH-042: live-tracker mode. edit (DEFAULT) -> the task card is edited in place
|
||||
# (editMessageText). bump -> on every update the old card is deleted and a fresh
|
||||
# one is sent silently to the BOTTOM of the chat (deleteMessage + sendMessage +
|
||||
# repoint). One card per task in both modes. Any value other than "bump" -> edit.
|
||||
ORCH_TRACKER_MODE=edit
|
||||
# ORCH-043: merge-gate (auto-rebase onto current origin/main + re-test + merge-lock)
|
||||
# on the deploy-staging -> deploy edge. Deterministic sub-gate (no LLM) that catches
|
||||
# the branch up to the CURRENT origin/main, re-tests it, and serialises merges so two
|
||||
|
||||
File diff suppressed because one or more lines are too long
16
CLAUDE.md
16
CLAUDE.md
@@ -41,22 +41,6 @@ created → analysis → architecture → development → review → testing →
|
||||
## Статусная модель Plane (ORCH-066) — индикация ≠ управление
|
||||
Статусы Plane — это **слой B (индикация)**, отдельный от **слоя A (машина стадий)** `src/stages.py::STAGE_TRANSITIONS`. Plane показывает наблюдателю осмысленную картину (`Backlog → Todo → Analysis → Architecture → Development → Code-Review → Testing → Awaiting Deploy → Deploying → Monitoring after Deploy → Done` + человеческие гейты `In Review/Approved`, `Confirm Deploy`), но НИКОГДА не управляет конвейером. Маппинг и сеттеры — `src/plane_sync.py` (6 новых ключей: `to_analyse/analysis/code_review/awaiting_deploy/deploying/monitoring`), с project-relative alias-fallback: на частично сконфигурированном проекте новый ключ деградирует на базовый UUID ТОГО ЖЕ проекта (нулевая регрессия для enduro-trails). Детали — `docs/architecture/README.md`.
|
||||
|
||||
## Нотификации / Telegram live-tracker (ORCH-042/066/067)
|
||||
Каждая задача = **одна карточка** в Telegram (`src/notifications.py`). Поведение карточки:
|
||||
- **Дефолт `tracker_mode` — `bump`** (ORCH-067; `edit` доступен через `ORCH_TRACKER_MODE=edit`).
|
||||
`bump` на каждом обновлении удаляет старую карточку и шлёт свежую вниз чата (тихо), `edit`
|
||||
редактирует на месте. Инвариант «одна карточка на задачу» — в обоих режимах.
|
||||
- **Статус-строка карточки** (`📍 <status_label>`) показывает текущий Plane-статус по модели
|
||||
ORCH-066 (`plane_status_label`). Оффлайн-ядро (`stage → статус`, In Review из brd-clock)
|
||||
работает всегда без сети; best-effort live-overlay (kill-switch `tracker_live_status`,
|
||||
TTL-кэш, короткий таймаут) лишь дорисовывает ветки, неотличимые offline (Needs Input /
|
||||
Blocked / Rejected / Cancelled / Deploying / Monitoring) и **никогда не блокирует конвейер**.
|
||||
- **Кликабельный номер задачи** (`plane_issue_link`) — `ORCH-NNN` в карточке И во всех
|
||||
уведомлениях (`notify_*`, alert'ы стадий) рендерится как `<a href=…>` на issue в Plane;
|
||||
fail-safe → просто `html.escape(номер)`, если ссылку построить нельзя. Никогда не падает.
|
||||
- Транспорт (`send_telegram`/`edit_telegram`/`delete_telegram`), `disable_notification`
|
||||
(карточка тихая, пингуют только alert-хелперы), схема БД — не трогаются.
|
||||
|
||||
## Конвенции
|
||||
- Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
|
||||
- Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug`
|
||||
|
||||
@@ -13,7 +13,6 @@
|
||||
- **Queue** (`src/queue_worker.py`, ORCH-1) — персистентная очередь задач (SQLite `jobs`), atomic claim, max_concurrency, ретраи, restart-safe.
|
||||
- **Job-reaper** (`src/job_reaper.py`, ORCH-065 — [adr-0011](adr/adr-0011-job-reaper-lease-reclaim.md)) — фоновый daemon-поток (каркас `reconciler`), стартует/останавливается в `main.lifespan` (после `reconciler.start()` / перед `worker.stop()`). Детектирует «мёртвый» `running`-job **без рестарта** процесса (Tier-1 мёртвый `jobs.pid` после `reaper_dead_ticks` тиков; Tier-2 `agent_runs.exit_code` записан, а job ещё `running`; Tier-3 backstop `reaper_max_running_s`) и приводит строку к корректному статусу через те же контракты (`_try_advance_stage`/`_finalize_job`, gate-driven; exit≠0/неизвестно → `attempts<max`→`queued`, иначе `failed`+Telegram). Атомарный reap-claim (guard `status='running'`) совместим со стартовым `requeue_running_jobs`. Тот же поток периодически делает проактивный реклейм stale/dead merge-lease (см. ниже). never-raise; kill-switch `ORCH_REAPER_ENABLED`; снимок в `GET /queue` (блок `reaper`).
|
||||
- **Reconciler** (`src/reconciler.py`, ORCH-053 — реализовано, [adr-0007](adr/adr-0007-reconciler.md)) — фоновый daemon-поток (паттерн `queue_worker`), стартует/останавливается в `main.lifespan` (после `worker.start()` / перед `worker.stop()`). Реконсилирует рассинхрон «источник истины ≠ стадия задачи» при потерянном webhook. F-1 gate-side (продвигает застрявшую стадию по локальной БД через штатный `advance_stage(..., finished_agent=None)`), F-2 plane-side (опрос Plane API → `handle_*` из `plane.py`), F-3 (БД-fallback `sha→branch` в `handle_ci_status`). Источник истины — гейт/Plane, не событие; идемпотентность (active-job guard + atomic-claim + grace); kill-switch `ORCH_RECONCILE_ENABLED`. `analysis` F-1 не трогает (человеческий гейт). F-1 также пропускает escalated (retry≥лимита) и Blocked/Needs-Input задачи (ORCH-060). Наблюдаемость — блок `reconcile` в `GET /queue`.
|
||||
- **Notifications / Live-tracker** (`src/notifications.py`, ORCH-042/ORCH-067) — ОДНА live-карточка на задачу (`update_task_tracker`), обновляется на каждом переходе. Режим `ORCH_TRACKER_MODE` (дефолт `bump` с ORCH-067: delete+silent send+repoint внизу чата; `edit` — правка на месте). Карточка несёт строку Plane-статуса `📍 …` (оффлайн-ядро `plane_status_label` + best-effort live-overlay `_live_plane_branch_override`, kill-switch `ORCH_TRACKER_LIVE_STATUS`) и кликабельный номер задачи (`plane_issue_link`/`link_for` → ссылка в Plane, fail-safe на сырой номер). Все алерты, упоминающие `work_item_id`, делают номер кликабельным. Контракт всего компонента — never raises; карточка всегда silent. Детали — [internals.md](internals.md) §7.
|
||||
- **Project Registry** (`src/projects.py`, ORCH-6) — Plane project id → repo + prefix; фильтрация вебхуков по проекту.
|
||||
- **Plane Sync** (`src/plane_sync.py`) — синхронизация статусов/комментариев в Plane. Резолв статусов проекта `get_project_states` (ORCH-10) кэширует `{logical_key→uuid}` per-project; **ORCH-068** добавляет в кэш-запись `{uuid→group}` (для терминал-исключения F-2) и **TTL** `ORCH_PLANE_STATES_TTL_S` (дефолт 300с; `0` → прежний lifetime-кэш) — устаревший набор статусов самозалечивается без рестарта процесса через существующий `reload_project_states()` (баг кэша после появления нового Plane-статуса). Форма возврата `get_project_states` неизменна (обратная совместимость).
|
||||
|
||||
|
||||
@@ -111,12 +111,12 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
|
||||
|
||||
Вместо ~15 отдельных сообщений на задачу оркестратор держит **ОДНУ** live-карточку на задачу (`update_task_tracker`), которая обновляется на каждом переходе стадии. Текст рендерится статически из БД (`render_task_tracker`: стадии, токены, стоимость, BRD-подтверждение, итоги). Карточка всегда тихая (`disable_notification=True`); отдельные пинги шлют только `notify_approve_requested` / `notify_error`. `message_id` хранится в `tasks.tracker_message_id`; helpers `get_tracker_message_id` / `set_tracker_message_id`. Контракт всего компонента — **never raises**.
|
||||
|
||||
**Режимы (ORCH-042, `ORCH_TRACKER_MODE` → `Settings.tracker_mode`; дефолт переключён `edit → bump` в ORCH-067).** Резолвится в `update_task_tracker` (case-insensitive, trim); всё, что ≠ `"bump"` (включая пустое/мусор/None), трактуется как `edit` → безопасный фолбэк. Инвариант «одна карточка на задачу» сохраняется в обоих режимах.
|
||||
**Режимы (ORCH-042, `ORCH_TRACKER_MODE` → `Settings.tracker_mode`).** Резолвится в `update_task_tracker` (case-insensitive, trim); всё, что ≠ `"bump"` (включая пустое/мусор/None), трактуется как `edit` → нулевая регрессия и безопасный фолбэк. Инвариант «одна карточка на задачу» сохраняется в обоих режимах.
|
||||
|
||||
| Режим | Поведение при обновлении |
|
||||
|-------|--------------------------|
|
||||
| `bump` (дефолт, ORCH-067) | карточка пересоздаётся внизу чата: best-effort `delete_telegram(старый_id)` → `send_telegram(text, disable_notification=True)` → `set_tracker_message_id(new_id)` **только** при успешном send (`new_mid is not None`). За один вызов — не более одного нового сообщения. Живая карточка всегда «догоняет» переписку. |
|
||||
| `edit` | первый вызов → `send_telegram` (тихо) + сохранение `message_id`; далее → `edit_telegram` на сохранённый id. Новое сообщение шлётся ТОЛЬКО при `EDIT_GONE` (удалено/старше 48ч/невалидный id). `EDIT_NOT_MODIFIED` / `EDIT_FAILED` → нового сообщения нет (анти-дубль). |
|
||||
| `edit` (дефолт) | первый вызов → `send_telegram` (тихо) + сохранение `message_id`; далее → `edit_telegram` на сохранённый id. Новое сообщение шлётся ТОЛЬКО при `EDIT_GONE` (удалено/старше 48ч/невалидный id). `EDIT_NOT_MODIFIED` / `EDIT_FAILED` → нового сообщения нет (анти-дубль). |
|
||||
| `bump` | карточка пересоздаётся внизу чата: best-effort `delete_telegram(старый_id)` → `send_telegram(text, disable_notification=True)` → `set_tracker_message_id(new_id)` **только** при успешном send (`new_mid is not None`). За один вызов — не более одного нового сообщения. |
|
||||
|
||||
**`delete_telegram(message_id) -> bool`** (low-level, never raises). Семантика возврата — «исчезло ли старое сообщение»:
|
||||
- `ok:true` → `True`;
|
||||
@@ -128,12 +128,6 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
|
||||
|
||||
**Текст карточки (оба режима, ORCH-042):** метка `Подтверждение BRD` (была «Ревью БРД»); после прохождения approve-gate строка BRD начинается с ✅ (ветка ожидания сохраняет ⏸️/⏳); русские display-labels стадий (`Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение`); финальная строка `📦 Внедрено` (было `deployed`). Меняются только отображаемые строки — ключи стадий и имена агентов (завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД) не трогаются.
|
||||
|
||||
**Строка Plane-статуса и кликабельный номер (ORCH-067, слой B — индикация).** Под заголовком карточка несёт строку `📍 <Plane-статус>` по модели ORCH-066. Источник — двухслойный, контракт **never raises**:
|
||||
- **Оффлайн-ядро** `plane_status_label(task_row)` — чистая функция БЕЗ сети: `stage → статус` (`created→To Analyse`, `analysis→Analysis`, `architecture→Architecture`, `development→Development`, `review→Code-Review`, `testing→Testing`, `deploy→⏸️ Awaiting Deploy`, `done→Done`) + `⏸️ In Review` из brd-часов (`brd_review_started_at` задан, `…_ended_at` пуст). Неизвестная/битая стадия → безопасный дефолт `To Analyse`.
|
||||
- **Live-overlay** `_live_plane_branch_override` — best-effort: дорисовывает ветви-статусы, неразличимые оффлайн (Needs Input / Blocked / Rejected / Cancelled / Deploying / Monitoring after Deploy), чтением живого Plane-статуса (`fetch_issue_state` с коротким `tracker_live_status_timeout_s`, TTL-кэш `tracker_live_status_ttl_s`, kill-switch `tracker_live_status`). Любой сбой / выключенный флаг / нехватка данных → оффлайн-метка; `⏸️ In Review` (авторитет brd-часов) overlay не консультирует. Анти-false-positive: `deploying/monitoring`, алиасящие базовый UUID на проекте без выделенного статуса (enduro), не вызывают override.
|
||||
|
||||
**Кликабельный номер задачи (ORCH-067).** Номер в заголовке карточки И во всех уведомлениях орка, где упоминается `work_item_id`, — HTML-ссылка на issue в Plane через общий `plane_issue_link` / `link_for` (URL строит `_plane_issue_url` с loopback/workspace/project-гардами, переиспользуя резолв ORCH-017). Fail-safe: при нехватке любого из (web-base/не-loopback, workspace, project_id, plane_issue_id) → `html.escape(work_item_id)` без `<a>`; динамические части экранируются, `<a>`-разметка валидна под `parse_mode=HTML`. Алерты `stage_engine`/`launcher`/`security_gate`/`reconciler` переведены на `link_for` (резолвит `repo`+`plane_issue_id` из БД по `task_id` или `work_item_id`).
|
||||
|
||||
## Database Schema
|
||||
|
||||
```sql
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: [высокий] Telegram tracker: bump + статусы Plane + кликабельный номер задачи
|
||||
|
||||
Work Item ID: ORCH-067
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,158 +0,0 @@
|
||||
# BRD — ORCH-067: Telegram tracker (bump + статусы Plane + кликабельный номер задачи)
|
||||
|
||||
Work Item: **ORCH-067**
|
||||
Тип: **Багфикс + enhancement**
|
||||
Приоритет: высокий
|
||||
Компонент: Telegram live-tracker и уведомления оркестратора (`src/notifications.py`)
|
||||
Расширяет: открытый баг seq=55 («bump не сработал, регресс ORCH-042»)
|
||||
|
||||
---
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
|
||||
Оркестратор ведёт по одной «живой карточке» (live-tracker) на каждую задачу в Telegram
|
||||
(`src/notifications.py`). Карточка тихо обновляется на каждом переходе стадии, а отдельными
|
||||
пингами шлются только события, требующие внимания владельца (approve-gate, деплой-фейл,
|
||||
падение агента, ошибка задачи).
|
||||
|
||||
Сейчас есть четыре боли:
|
||||
|
||||
1. **bump не работает в проде.** Диагностика оператора: код режима `bump` в
|
||||
`update_task_tracker` корректен (delete старого → sendMessage вниз → repoint
|
||||
`tracker_message_id`), НО в проде `tracker_mode="edit"` (дефолт `src/config.py:408`),
|
||||
а `ORCH_TRACKER_MODE=bump` не выставлен. Карточка обновляется edit-in-place и остаётся
|
||||
«вверху» ленты, тонет под новыми сообщениями — наблюдатель не видит актуального
|
||||
состояния без скролла.
|
||||
|
||||
2. **Карточка показывает внутренние названия стадий, а не Plane-статусы.** После ввода
|
||||
осмысленной статусной модели Plane (ORCH-066) карточка по-прежнему рендерит внутренние
|
||||
ярлыки стадий (Анализ/Архитектура/…), а текущий статус задачи в терминах, понятных
|
||||
наблюдателю в Plane (To Analyse → Analysis → In Review → … → Done), в шапке карточки
|
||||
не отражён. Особенно теряется состояние **ожидания согласования BRD** = Plane-статус
|
||||
`In Review`: сейчас это лишь строка «✅/⏸️ Подтверждение BRD … ⏳», не выраженная как
|
||||
полноценный статус.
|
||||
|
||||
3. **Номер задачи в карточке некликабелен.** `ORCH-066` в карточке — обычный текст;
|
||||
чтобы открыть задачу в Plane, наблюдателю приходится искать её вручную.
|
||||
|
||||
4. **Номер задачи некликабелен и во всех остальных уведомлениях орка** (approve-requested,
|
||||
QG-fail, deploy SUCCESS/FAIL, Needs Input, прод-деплой и т. п.) — везде, где упоминается
|
||||
`work_item_id`, это просто текст.
|
||||
|
||||
## 2. Цель
|
||||
|
||||
Сделать live-tracker и уведомления орка наблюдаемыми «из коробки»:
|
||||
- bump работает по умолчанию (карточка падает вниз свежим сообщением при каждом обновлении,
|
||||
ровно одна карточка на задачу, без спама и дублей);
|
||||
- карточка явно показывает текущий Plane-статус по модели ORCH-066, включая человеческие
|
||||
гейты (`⏸️ In Review` — согласование BRD, `⏸️ Awaiting Deploy` — ожидание Confirm Deploy,
|
||||
`❓ Needs Input` — нужны уточнения);
|
||||
- номер задачи кликабелен в карточке и во всех Telegram-уведомлениях орка и ведёт на
|
||||
страницу задачи в Plane.
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
|
||||
- **Owner (Слава)** — основной потребитель карточки и уведомлений; источник 4 требований.
|
||||
- **Агенты конвейера** — косвенно (карточка отражает их прогресс; поведение агентов не меняется).
|
||||
- **Другие проекты (enduro-trails)** — общий инстанс/БД; изменения не должны вызывать регресс.
|
||||
|
||||
## 4. Объём работ (scope)
|
||||
|
||||
### 4.1. Требование 1 — bump по умолчанию
|
||||
- Режим `bump` должен быть поведением по умолчанию: при каждом обновлении карточка
|
||||
удаляется и пересоздаётся внизу ленты, одна карточка на задачу, тихо
|
||||
(`disable_notification`), без дублей.
|
||||
- Инвариант «одна карточка на задачу» сохраняется в обоих режимах (`edit` остаётся как
|
||||
опция через env).
|
||||
- Транзиентный фейл `send` не должен обнулять `tracker_message_id` и плодить дубли
|
||||
(инвариант уже заложен в коде — сохранить).
|
||||
|
||||
### 4.2. Требование 2 — статусы карточки как в Plane (модель ORCH-066)
|
||||
- В шапке/верхней части карточки явно отображается **текущий Plane-статус** задачи по
|
||||
модели ORCH-066.
|
||||
- Полный маппинг состояний (имена — финальные из модели ORCH-066):
|
||||
```
|
||||
To Analyse → Analysis → In Review (⏸️ ожидание согласования BRD) → Architecture →
|
||||
Development → Code-Review → Testing → Awaiting Deploy (⏸️ ожидание Confirm Deploy) →
|
||||
Deploying → Monitoring after Deploy → Done
|
||||
```
|
||||
Ветки: `Needs Input` (аналитик задал вопросы), `Blocked`, `Rejected`, `Cancelled`.
|
||||
- Человеческие гейты отражаются как ПОЛНОЦЕННЫЕ статусы с паузой:
|
||||
- согласование BRD → «⏸️ In Review — ожидание согласования BRD»;
|
||||
- ожидание прод-деплоя → «⏸️ Awaiting Deploy — ожидание Confirm Deploy»;
|
||||
- вопросы аналитика → «❓ Needs Input — нужны уточнения».
|
||||
- Существующая семантика строки «Подтверждение BRD» сохраняется (время ожидания/«твоё
|
||||
время»), но статус карточки при этом явно показывает In Review (approve-pending).
|
||||
|
||||
### 4.3. Требование 3 — кликабельный номер задачи в карточке
|
||||
- `work_item_id` (напр. `ORCH-066`) в карточке — гиперссылка на страницу задачи Plane:
|
||||
`https://<PLANE_WEB_BASE>/<workspace_slug>/projects/<project_id>/issues/<issue_id>/`.
|
||||
- Источники частей URL:
|
||||
- `PLANE_WEB_BASE` — из конфигурации (env, поле `plane_web_url` / `ORCH_PLANE_WEB_URL`;
|
||||
значение прод — `plane.mva154.duckdns.org`); fail-safe: не задан → номер без ссылки;
|
||||
- `workspace_slug` — `plane_workspace_slug` (уже есть в settings, прод — `ag_proj`);
|
||||
- `project_id` — резолвится per-task по репозиторию задачи (ORCH / Sandbox);
|
||||
- `issue_id` (UUID) — из БД: колонка `tasks.plane_issue_id`.
|
||||
- Рендер через `<a href="...">ORCH-NNN</a>` (`parse_mode=HTML` уже включён);
|
||||
HTML в title/тексте экранируется, чтобы не сломать разметку.
|
||||
|
||||
### 4.4. Требование 4 — кликабельный номер во ВСЕХ уведомлениях орка
|
||||
- Единый хелпер (напр. `plane_issue_link(work_item_id, plane_issue_id, project_id) -> html`)
|
||||
строит кликабельный номер с fail-safe; применяется во всех точках `send_telegram`/
|
||||
`notify_*`, где упоминается `work_item_id` (approve-requested, QG-fail, deploy
|
||||
SUCCESS/FAIL, Needs Input, прод-деплой, alert'ы launcher/merge_gate/job_reaper/
|
||||
security_gate/reconciler/main).
|
||||
|
||||
## 5. Вне объёма (out of scope)
|
||||
|
||||
- Транспорт `send_telegram` / `edit_telegram` / `delete_telegram` (parse_mode HTML уже есть) — не трогать.
|
||||
- Инвариант «одна карточка на задачу» — не нарушать (не плодить дубли).
|
||||
- Логика `disable_notification` (карточка тихая; пингуют только alert-хелперы) — не трогать.
|
||||
- `STAGE_TRANSITIONS`, Quality Gates, схема БД — НЕ менять.
|
||||
- Изменение поведения агентов/конвейера.
|
||||
|
||||
## 6. Зависимости
|
||||
|
||||
- Маппинг статусов (требование 2) опирается на статусную модель ORCH-066. ORCH-066 уже в
|
||||
конвейере на стадии deploy. Эту задачу делать ПОСЛЕ прода ORCH-066, чтобы имена статусов
|
||||
совпали. Если ORCH-066 ещё не в проде на момент разработки — использовать согласованные
|
||||
финальные имена из модели: To Analyse, Analysis, Code-Review, Awaiting Deploy, Deploying,
|
||||
Monitoring after Deploy, In Review, Needs Input, Blocked, Cancelled, Done.
|
||||
- Конфигурация `plane_web_url` / `plane_workspace_slug` уже существует в `src/config.py`
|
||||
(ORCH-017); реестр проектов `src/projects.py` (`get_project_by_repo().plane_project_id`)
|
||||
уже даёт per-task project_id.
|
||||
|
||||
## 7. Fail-safe (обязательно)
|
||||
|
||||
- Нет `PLANE_WEB_BASE` / нет `plane_issue_id` / нет `project_id` / loopback-база →
|
||||
показывать номер БЕЗ ссылки, **не падать**.
|
||||
- HTML-экранирование пользовательского текста (title и пр.) во всех сообщениях с
|
||||
`parse_mode=HTML`.
|
||||
- Bump: транзиентный фейл `send` не обнуляет `tracker_message_id` и не плодит дубли.
|
||||
- Любая ошибка построения статуса/ссылки никогда не должна ронять рендер карточки или
|
||||
отправку уведомления (degrade gracefully).
|
||||
|
||||
## 8. Критерии успеха (Definition of Done)
|
||||
|
||||
- Bump работает из коробки: карточка падает вниз при обновлении, одна на задачу.
|
||||
- Карточка показывает Plane-статус новой модели, включая `⏸️ In Review` (согласование BRD),
|
||||
`⏸️ Awaiting Deploy`, `❓ Needs Input`.
|
||||
- Номер задачи кликабелен в карточке И во всех уведомлениях орка (ведёт на страницу Plane).
|
||||
- Fail-safe покрыт тестами (нет URL/plane_id/project → без ссылки, не падает;
|
||||
HTML-экранирование).
|
||||
- `pytest tests/ -q` зелёный.
|
||||
- Документация обновлена в том же PR: `CLAUDE.md` (раздел нотификаций/tracker),
|
||||
`CHANGELOG.md`, ADR per-work-item.
|
||||
|
||||
## 9. Риски
|
||||
|
||||
- **Регресс enduro-trails.** Смена дефолта `tracker_mode` на bump меняет поведение для всех
|
||||
проектов. Митигация: bump уже реализован и протестирован концептуально; инвариант «одна
|
||||
карточка» сохранён; env-переключатель `edit` остаётся.
|
||||
- **Поломка HTML-разметки** при неэкранированном title → сообщение не доставится. Митигация:
|
||||
обязательное `html.escape` + тесты.
|
||||
- **Источник «истинного» Plane-статуса** для веток, не выводимых из `tasks.stage`
|
||||
(Needs Input/Blocked/Rejected/Cancelled, Deploying/Monitoring), при запрете на изменение
|
||||
схемы БД — архитектурное решение (ADR), с обязательным fail-safe (без сети не падать).
|
||||
- **Self-hosting.** Орк правит сам себя; обязательна страховка через staging (8501) перед
|
||||
прод-деплоем; прод-контейнер не ронять в рамках задачи.
|
||||
@@ -1,205 +0,0 @@
|
||||
# ТЗ — ORCH-067: Telegram tracker (bump + статусы Plane + кликабельный номер задачи)
|
||||
|
||||
Work Item: **ORCH-067**
|
||||
Документ описывает КОНКРЕТНЫЕ изменения кода/конфигурации/тестов и документации.
|
||||
Архитектурные развилки помечены `[ARCH]` — решение принимает архитектор (ADR), здесь
|
||||
зафиксированы только требования и ограничения к ним.
|
||||
|
||||
---
|
||||
|
||||
## 0. Задействованные модули `src/`
|
||||
|
||||
| Модуль | Роль в задаче |
|
||||
|---|---|
|
||||
| `src/config.py` | Дефолт `tracker_mode`; поле `plane_web_url`/`plane_workspace_slug` (уже есть). |
|
||||
| `src/notifications.py` | Основные изменения: bump-дефолт, статус-строка карточки, хелпер ссылки, применение хелпера в `notify_*`. |
|
||||
| `src/plane_sync.py` | Источник имён статусов/маппинга ORCH-066 (`_PLANE_NAME_TO_KEY`, `_STAGE_TO_STATE_KEY`); при необходимости reverse-map UUID→имя `[ARCH]`. |
|
||||
| `src/projects.py` | `get_project_by_repo(repo).plane_project_id` — per-task project_id для ссылки. |
|
||||
| `src/db.py` | Чтение `tasks.plane_issue_id`, `tasks.repo` (без изменений схемы). |
|
||||
| `src/stage_engine.py`, `src/agents/launcher.py`, `src/merge_gate.py`, `src/job_reaper.py`, `src/security_gate.py`, `src/reconciler.py`, `src/main.py` | Точки `send_telegram`, где есть `work_item_id` — применить хелпер ссылки (требование 4). |
|
||||
|
||||
Изменения API (HTTP endpoints) — **нет**. Изменения схемы БД — **нет**. Новые QG checks — **нет**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Требование 1 — bump по умолчанию
|
||||
|
||||
### 1.1. Изменение
|
||||
- `src/config.py` (~стр. 408): сменить дефолт
|
||||
`tracker_mode: str = "edit"` → `tracker_mode: str = "bump"`.
|
||||
- Обновить docstring-комментарий рядом (ORCH-042): отметить, что **дефолт теперь `bump`**,
|
||||
`edit` остаётся доступен через `ORCH_TRACKER_MODE=edit`.
|
||||
|
||||
### 1.2. Без изменений (сохранить инвариант)
|
||||
- Логика `update_task_tracker` (`src/notifications.py`, ветка `if mode == "bump"`):
|
||||
`delete_telegram(old)` best-effort → `send_telegram(text, disable_notification=True)` →
|
||||
`set_tracker_message_id` ТОЛЬКО при `new_mid is not None`. Не менять.
|
||||
- `send_telegram`/`edit_telegram`/`delete_telegram` — не трогать.
|
||||
|
||||
### 1.3. Прод-аспект
|
||||
- Для прод-инстанса орка можно дополнительно выставить `ORCH_TRACKER_MODE=bump` в `.env`
|
||||
на хосте (как страховку), но код должен работать «из коробки» и без env. Канон env —
|
||||
`.env.example` (обновить, если там фигурирует tracker_mode).
|
||||
|
||||
---
|
||||
|
||||
## 2. Требование 2 — статус-строка карточки по модели ORCH-066
|
||||
|
||||
### 2.1. Новый чистый хелпер маппинга
|
||||
Добавить в `src/notifications.py` функцию, возвращающую отображаемый Plane-статус для
|
||||
карточки на основе доступных данных задачи. Сигнатура (ориентир):
|
||||
```python
|
||||
def plane_status_label(task_row) -> str:
|
||||
"""Вернуть строку текущего Plane-статуса для шапки карточки (с emoji).
|
||||
Никогда не падает: на неизвестном входе -> разумный дефолт по stage."""
|
||||
```
|
||||
Хелпер обязан быть чистым/детерминированным от входных данных и **никогда не бросать**
|
||||
исключения (любая ошибка → дефолт по `stage`, рендер карточки не ломается).
|
||||
|
||||
### 2.2. Маппинг внутреннее состояние → Plane-статус (обязательные строки)
|
||||
Имена статусов — финальные из модели ORCH-066 (см. `_PLANE_NAME_TO_KEY` в `plane_sync.py`).
|
||||
|
||||
| Источник (данные задачи в БД) | Plane-статус (отображение в карточке) |
|
||||
|---|---|
|
||||
| `stage == "created"` | `To Analyse` |
|
||||
| `stage == "analysis"`, BRD-clock не запущен | `Analysis` |
|
||||
| `stage == "analysis"`, `brd_review_started_at` есть, `brd_review_ended_at` пуст | `⏸️ In Review — ожидание согласования BRD` |
|
||||
| `stage == "architecture"` | `Architecture` |
|
||||
| `stage == "development"` | `Development` |
|
||||
| `stage == "review"` | `Code-Review` |
|
||||
| `stage == "testing"` | `Testing` |
|
||||
| `stage == "deploy"` (ожидание Confirm Deploy) | `⏸️ Awaiting Deploy — ожидание Confirm Deploy` |
|
||||
| `stage == "done"` | `Done` |
|
||||
|
||||
Ветки (Needs Input / Blocked / Rejected / Cancelled / Deploying / Monitoring after Deploy):
|
||||
- `❓ Needs Input — нужны уточнения` — состояние «аналитик задал вопросы»;
|
||||
- `Blocked`, `Rejected`, `Cancelled`, `Deploying`, `Monitoring after Deploy`.
|
||||
|
||||
`[ARCH]` **Источник сигнала для веток, не выводимых из `tasks.stage`** (Needs Input,
|
||||
Blocked, Rejected, Cancelled, Deploying, Monitoring after Deploy):
|
||||
- запрещено менять схему БД (нельзя добавлять колонку-флаг);
|
||||
- варианты для архитектора: (а) best-effort чтение живого Plane-статуса
|
||||
(`fetch_issue_state` + reverse-map UUID→имя через `get_project_states`/
|
||||
`_PLANE_NAME_TO_KEY`) с обязательным fail-safe (нет сети/ответа → деградация на
|
||||
stage-маппинг, без задержки, блокирующей конвейер); (б) только stage-выводимые статусы,
|
||||
а ветки — по уже имеющимся сигналам (например, In Review через brd-clock).
|
||||
- ОБЯЗАТЕЛЬНО к покрытию (DoD): `⏸️ In Review`, `⏸️ Awaiting Deploy`, `❓ Needs Input`.
|
||||
In Review полностью выводится из brd-clock (см. таблицу) и должен работать без сети.
|
||||
|
||||
### 2.3. Встраивание в `render_task_tracker`
|
||||
- В `render_task_tracker` (`src/notifications.py`) добавить в шапку/верх карточки отдельную
|
||||
СТРОКУ статуса (под заголовком `🛠️ ORCH-NNN · <title>` / над разделителем `bar`),
|
||||
напр.: `📍 <status_label>`.
|
||||
- Существующие строки по стадиям (`✅ done` / `🔄 active`), строка «Подтверждение BRD»,
|
||||
тоталы токенов/стоимости, done-строка с PR/⏱️ — СОХРАНИТЬ (семантику не ломать).
|
||||
- Семантика строки «Подтверждение BRD» (⏸️+⏳ при ожидании, ✅ при пройденном гейте)
|
||||
сохраняется; новая статус-строка дублирует её смысл в терминах Plane-статуса.
|
||||
|
||||
---
|
||||
|
||||
## 3. Требование 3 + 4 — кликабельный номер задачи
|
||||
|
||||
### 3.1. Единый хелпер
|
||||
Добавить в `src/notifications.py`:
|
||||
```python
|
||||
def plane_issue_link(work_item_id, plane_issue_id=None, project_id=None, repo=None) -> str:
|
||||
"""Вернуть HTML с кликабельным номером задачи (<a href=...>ORCH-NNN</a>),
|
||||
либо просто html.escape(work_item_id), если ссылку построить нельзя.
|
||||
Никогда не падает."""
|
||||
```
|
||||
Поведение:
|
||||
- База URL: `settings.plane_web_url` → fallback `settings.plane_api_url`; loopback-база
|
||||
(`localhost`/`127.0.0.1`/…) трактуется как «нет web URL» (переиспользовать
|
||||
`_is_loopback_base`).
|
||||
- `workspace_slug`: `settings.plane_workspace_slug`.
|
||||
- `project_id`: явный аргумент → иначе резолв по `repo` через
|
||||
`get_project_by_repo(repo).plane_project_id`.
|
||||
- `issue_id`: `plane_issue_id` (UUID из `tasks.plane_issue_id`).
|
||||
- URL-шаблон: `{web_base}/{workspace}/projects/{project_id}/issues/{issue_id}/`.
|
||||
- Текст ссылки = `html.escape(work_item_id)`; `href` = `html.escape(url, quote=True)`.
|
||||
- **Fail-safe:** если не хватает любого из (`web_base` валидный/не loopback, `workspace`,
|
||||
`project_id`, `plane_issue_id`) → вернуть `html.escape(work_item_id)` (номер без ссылки).
|
||||
- Логика построения URL уже существует в `_build_plane_issue_link` (ORCH-017) — допустимо
|
||||
переиспользовать/обобщить её, разнеся «текст-ссылки = номер» и «текст-ссылки = `✅ Задача
|
||||
в Plane`», чтобы не дублировать резолв проекта и loopback-guard.
|
||||
|
||||
### 3.2. Применение в карточке (требование 3)
|
||||
- В `render_task_tracker` заголовок строится из `work_item_id`. Заменить
|
||||
`html.escape(work_item_id)` в обоих вариантах заголовка (done / not-done) на
|
||||
`plane_issue_link(work_item_id, plane_issue_id, repo=repo)` — номер становится
|
||||
кликабельным.
|
||||
- Для этого `render_task_tracker` должен дополнительно выбрать из БД `repo` и
|
||||
`plane_issue_id` (расширить существующий `SELECT` по `tasks`). Схему НЕ менять — колонки
|
||||
уже есть.
|
||||
- `title` уже экранируется (`html.escape(title)`) — сохранить.
|
||||
|
||||
### 3.3. Применение во всех уведомлениях (требование 4)
|
||||
Во всех точках `send_telegram`/`notify_*`, где в тексте есть `work_item_id`, заменить
|
||||
«сырой» номер на `plane_issue_link(...)`. Перечень точек (из `src`):
|
||||
- `src/notifications.py`: `notify_approve_requested`, `notify_error`
|
||||
(и любые будущие notify_* с work_item_id);
|
||||
- `src/stage_engine.py`: все `send_telegram(...)` с `work_item_id`
|
||||
(≈ строки 613, 672, 719, 776, 820, 916, 971, 1057, 1134, 1192, 1228, 1257, 1355, 1367,
|
||||
1425, 1447, 1601 — проверить каждую: применять ТОЛЬКО где упоминается номер задачи);
|
||||
- `src/agents/launcher.py`: deploy-failed alert (≈685–686), agent-failed alert (≈698–699),
|
||||
alert ≈821–822;
|
||||
- `src/merge_gate.py` (≈431–432);
|
||||
- `src/job_reaper.py` (≈395–396);
|
||||
- `src/security_gate.py` (≈673–674);
|
||||
- `src/reconciler.py` (≈449);
|
||||
- `src/main.py` (≈45–47).
|
||||
|
||||
`[ARCH]` Способ доступа к `plane_issue_id`/`project_id` в каждой точке (часто там уже есть
|
||||
`work_item_id`, но не обязательно `plane_issue_id`): хелпер должен уметь резолвить
|
||||
недостающее по `repo`/БД, оставаясь fail-safe. Допустимо добавить тонкую обёртку, которая по
|
||||
`work_item_id`/`task_id` достаёт `repo`+`plane_issue_id` из БД и зовёт `plane_issue_link`
|
||||
(аналогично существующему `_get_task_link_fields`). Везде, где данных нет — деградация на
|
||||
просто номер, без падения.
|
||||
|
||||
### 3.4. HTML-экранирование
|
||||
- `parse_mode=HTML` уже стоит в `send_telegram`/`edit_telegram`. Любой пользовательский
|
||||
текст (title, описания, причины QG-fail, сообщения об ошибках), попадающий в сообщение с
|
||||
ссылками, должен экранироваться `html.escape`, чтобы не сломать `<a>`-разметку.
|
||||
|
||||
---
|
||||
|
||||
## 4. Конфигурация
|
||||
|
||||
- `plane_web_url` (env `ORCH_PLANE_WEB_URL`) — уже существует (`src/config.py`), значение
|
||||
прод — `plane.mva154.duckdns.org` (схему `https://` учесть при сборке URL).
|
||||
Дополнительных полей конфигурации не требуется.
|
||||
- `tracker_mode` — сменить дефолт на `bump` (раздел 1).
|
||||
- Обновить `.env.example`, если в нём фигурируют `ORCH_TRACKER_MODE` / `ORCH_PLANE_WEB_URL`
|
||||
(канон секретов/настроек — `.env.example`, не коммитить реальные секреты).
|
||||
|
||||
---
|
||||
|
||||
## 5. Артефакты pipeline, которые должны быть созданы/обновлены
|
||||
|
||||
- `docs/work-items/ORCH-067/06-adr/ADR-NNN-*.md` — архитектурное решение (минимум: источник
|
||||
«истинного» Plane-статуса для веток при запрете изменения схемы БД; дефолт bump; единый
|
||||
хелпер ссылки).
|
||||
- `CLAUDE.md` — раздел про нотификации/tracker (дефолт bump; статус-строка карточки;
|
||||
кликабельный номер в карточке и уведомлениях).
|
||||
- `CHANGELOG.md` — запись ORCH-067.
|
||||
- `docs/architecture/README.md` — при необходимости синхронизировать описание tracker'а.
|
||||
|
||||
---
|
||||
|
||||
## 6. Ограничения (что НЕ трогать)
|
||||
|
||||
- Транспорт `send_telegram`/`edit_telegram`/`delete_telegram`.
|
||||
- Инвариант «одна карточка на задачу».
|
||||
- Логику `disable_notification` (карточка тихая; пингуют только alert-хелперы).
|
||||
- `STAGE_TRANSITIONS`, Quality Gates, схему БД.
|
||||
- Поведение агентов/конвейера.
|
||||
|
||||
---
|
||||
|
||||
## 7. Замечания по самохостингу
|
||||
|
||||
Орк правит сам себя в проде (общий инстанс/БД с enduro-trails):
|
||||
- НЕ перезапускать прод-контейнер `orchestrator` в рамках задачи.
|
||||
- Обязательная страховка через `deploy-staging` (8501) до прод-деплоя.
|
||||
- Смена дефолта `tracker_mode` затрагивает ВСЕ проекты — проверить отсутствие регресса для
|
||||
enduro-trails (тесты + staging-наблюдение карточки).
|
||||
@@ -1,129 +0,0 @@
|
||||
# Acceptance Criteria — ORCH-067
|
||||
|
||||
Work Item: **ORCH-067**
|
||||
Каждый критерий формулирует чёткое условие PASS/FAIL. Привязка к тестам — в `04-test-plan.yaml`.
|
||||
|
||||
---
|
||||
|
||||
## Группа A — Bump по умолчанию (Требование 1)
|
||||
|
||||
### AC-1 — дефолт tracker_mode = bump
|
||||
- **PASS:** `Settings().tracker_mode == "bump"` без выставленного env `ORCH_TRACKER_MODE`.
|
||||
- **FAIL:** дефолт остался `"edit"` или иное.
|
||||
|
||||
### AC-2 — bump-поведение: одна карточка падает вниз
|
||||
- **PASS:** при втором (и последующем) вызове `update_task_tracker` для задачи с уже
|
||||
сохранённым `tracker_message_id` вызывается `delete_telegram(old_id)` (best-effort),
|
||||
затем `send_telegram(...)` с `disable_notification=True`, затем `set_tracker_message_id`
|
||||
на новый id. В чате остаётся ровно одна карточка на задачу.
|
||||
- **FAIL:** карточка редактируется на месте при дефолте; либо появляются дубли; либо новая
|
||||
карточка отправляется со звуком (`disable_notification` не True).
|
||||
|
||||
### AC-3 — bump fail-safe: транзиентный фейл send не обнуляет указатель
|
||||
- **PASS:** если `send_telegram` вернул `None` (нет креды/транзиентный фейл),
|
||||
`tracker_message_id` НЕ перезаписывается в `None` и дубликат в рамках вызова не создаётся.
|
||||
- **FAIL:** указатель обнулён или создан второй card-месседж в одном вызове.
|
||||
|
||||
### AC-4 — режим edit остаётся доступен через env
|
||||
- **PASS:** при `ORCH_TRACKER_MODE=edit` поведение прежнее (editMessageText, fallback на
|
||||
новый месседж только при EDIT_GONE).
|
||||
- **FAIL:** edit-режим сломан/недоступен.
|
||||
|
||||
---
|
||||
|
||||
## Группа B — Статус-строка карточки по модели ORCH-066 (Требование 2)
|
||||
|
||||
### AC-5 — статус-строка присутствует в карточке
|
||||
- **PASS:** `render_task_tracker(task_id)` содержит явную строку текущего Plane-статуса
|
||||
(напр. `📍 <status>`) в шапке/верхней части карточки.
|
||||
- **FAIL:** статус-строки нет.
|
||||
|
||||
### AC-6 — корректный маппинг stage → Plane-статус
|
||||
- **PASS:** для всех stage-выводимых состояний строка статуса соответствует таблице ТЗ §2.2:
|
||||
`created→To Analyse`, `analysis→Analysis`, `architecture→Architecture`,
|
||||
`development→Development`, `review→Code-Review`, `testing→Testing`,
|
||||
`deploy→Awaiting Deploy`, `done→Done`.
|
||||
- **FAIL:** хотя бы один stage маппится на неверное имя/внутренний ярлык.
|
||||
|
||||
### AC-7 — In Review (ожидание согласования BRD) как полноценный статус
|
||||
- **PASS:** при `stage == "analysis"`, `brd_review_started_at` задан и
|
||||
`brd_review_ended_at` пуст — статус-строка явно отражает `⏸️ In Review` с пометкой
|
||||
«ожидание согласования BRD»; при этом существующая строка «Подтверждение BRD …» с ⏸️/⏳
|
||||
сохранена. Работает без сетевых вызовов.
|
||||
- **FAIL:** In Review теряется/не показан как статус, либо строка «Подтверждение BRD» исчезла.
|
||||
|
||||
### AC-8 — Awaiting Deploy и Needs Input отражены
|
||||
- **PASS:** состояние ожидания Confirm Deploy показывается как
|
||||
`⏸️ Awaiting Deploy — ожидание Confirm Deploy`; состояние вопросов аналитика — как
|
||||
`❓ Needs Input — нужны уточнения`.
|
||||
- **FAIL:** любое из этих состояний не отражено в статус-строке.
|
||||
|
||||
### AC-9 — рендер карточки никогда не падает
|
||||
- **PASS:** при любой ошибке построения статуса (битые данные, недоступный источник)
|
||||
`render_task_tracker` возвращает корректную карточку (деградация на stage-маппинг или
|
||||
fallback-строку), исключение наружу не выходит.
|
||||
- **FAIL:** `render_task_tracker` бросает исключение.
|
||||
|
||||
---
|
||||
|
||||
## Группа C — Кликабельный номер в карточке (Требование 3)
|
||||
|
||||
### AC-10 — номер задачи в карточке — гиперссылка
|
||||
- **PASS:** при наличии `plane_web_url` (не loopback), `plane_workspace_slug`, `project_id`
|
||||
(резолв по repo) и `plane_issue_id` карточка содержит
|
||||
`<a href="https://<base>/<ws>/projects/<pid>/issues/<issue_id>/">ORCH-NNN</a>`.
|
||||
- **FAIL:** номер выводится сырым текстом при наличии всех данных, либо URL собран неверно.
|
||||
|
||||
### AC-11 — fail-safe ссылки в карточке
|
||||
- **PASS:** при отсутствии любого из (web_base/не-loopback, workspace, project_id,
|
||||
plane_issue_id) карточка показывает номер БЕЗ ссылки (`html.escape(work_item_id)`) и не
|
||||
падает.
|
||||
- **FAIL:** падение, пустая ссылка `<a href="">`, либо битый `<a>` тег.
|
||||
|
||||
---
|
||||
|
||||
## Группа D — Кликабельный номер во всех уведомлениях (Требование 4)
|
||||
|
||||
### AC-12 — единый хелпер ссылки
|
||||
- **PASS:** существует `plane_issue_link(...)`, возвращающий HTML-ссылку при достаточных
|
||||
данных и `html.escape(work_item_id)` при недостаточных; никогда не бросает.
|
||||
- **FAIL:** хелпера нет, либо он падает на неполных данных.
|
||||
|
||||
### AC-13 — хелпер применён во всех уведомлениях с work_item_id
|
||||
- **PASS:** во всех точках `send_telegram`/`notify_*` из ТЗ §3.3, где упоминается
|
||||
`work_item_id` (`notify_approve_requested`, `notify_error`, alert'ы stage_engine,
|
||||
launcher, merge_gate, job_reaper, security_gate, reconciler, main), номер задачи
|
||||
кликабелен (при наличии данных) и ведёт на ту же страницу Plane.
|
||||
- **FAIL:** хотя бы одна такая точка выводит номер сырым текстом при наличии данных.
|
||||
|
||||
### AC-14 — HTML-экранирование пользовательского текста
|
||||
- **PASS:** title/причины/сообщения с потенциальным HTML (`<`, `>`, `&`) экранируются
|
||||
`html.escape`; разметка `<a>` остаётся валидной; сообщение проходит `parse_mode=HTML`.
|
||||
- **FAIL:** неэкранированный текст ломает разметку (тест с title, содержащим `<b>`/`&`,
|
||||
обнаруживает поломку).
|
||||
|
||||
---
|
||||
|
||||
## Группа E — Нерегресс и качество
|
||||
|
||||
### AC-15 — инварианты транспорта/нотификаций сохранены
|
||||
- **PASS:** `send_telegram`/`edit_telegram`/`delete_telegram` не изменены по сигнатуре/
|
||||
семантике; карточка тихая (`disable_notification=True`); инвариант «одна карточка на
|
||||
задачу» соблюдён; `STAGE_TRANSITIONS`/QG/схема БД не тронуты.
|
||||
- **FAIL:** изменён транспорт, карточка пингует, появились дубли, тронута схема БД/QG.
|
||||
|
||||
### AC-16 — нет регресса для enduro-trails
|
||||
- **PASS:** существующие тесты нотификаций (`test_notify_approve_links.py`,
|
||||
`test_notify_done_regression.py` и др.) проходят; поведение карточки для не-ORCH проектов
|
||||
без новых Plane-статусов деградирует корректно (alias-fallback, без ссылки при нехватке
|
||||
данных).
|
||||
- **FAIL:** падение существующих тестов или сломанная карточка для enduro.
|
||||
|
||||
### AC-17 — весь набор тестов зелёный
|
||||
- **PASS:** `pytest tests/ -q` зелёный.
|
||||
- **FAIL:** любой упавший тест.
|
||||
|
||||
### AC-18 — документация обновлена в том же PR
|
||||
- **PASS:** обновлены `CLAUDE.md` (раздел нотификаций/tracker), `CHANGELOG.md`,
|
||||
создан ADR per-work-item.
|
||||
- **FAIL:** функционал изменён, документация — нет (reviewer → REQUEST_CHANGES).
|
||||
@@ -1,181 +0,0 @@
|
||||
work_item: ORCH-067
|
||||
description: >
|
||||
План тестов для ORCH-067 (Telegram tracker: bump по умолчанию, статус-строка
|
||||
карточки по модели Plane ORCH-066, кликабельный номер задачи в карточке и во
|
||||
всех уведомлениях орка). Сеть изолируется: send_telegram/edit_telegram/
|
||||
delete_telegram подменяются рекордерами (как в tests/conftest.py и
|
||||
tests/test_notify_approve_links.py); БД — временный SQLite, сидируемый фикстурой.
|
||||
|
||||
tests:
|
||||
# --- Группа A: bump по умолчанию (AC-1..AC-4) ---
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "Дефолт Settings().tracker_mode == 'bump' без env ORCH_TRACKER_MODE"
|
||||
module: tests/test_tracker_bump_default.py
|
||||
asserts: "AC-1"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: >
|
||||
bump-поведение: при повторном update_task_tracker с сохранённым
|
||||
tracker_message_id вызывается delete_telegram(old) -> send_telegram(...,
|
||||
disable_notification=True) -> set_tracker_message_id(new). Одна карточка.
|
||||
module: tests/test_tracker_bump_default.py
|
||||
asserts: "AC-2"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: >
|
||||
bump fail-safe: send_telegram вернул None (нет креды/транзиент) ->
|
||||
tracker_message_id не обнуляется, дубликат в вызове не создаётся.
|
||||
module: tests/test_tracker_bump_default.py
|
||||
asserts: "AC-3"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "ORCH_TRACKER_MODE=edit -> прежнее edit-поведение (editMessageText)"
|
||||
module: tests/test_tracker_bump_default.py
|
||||
asserts: "AC-4"
|
||||
expected: PASS
|
||||
|
||||
# --- Группа B: статус-строка карточки (AC-5..AC-9) ---
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "render_task_tracker содержит явную строку текущего Plane-статуса"
|
||||
module: tests/test_tracker_status_line.py
|
||||
asserts: "AC-5"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: >
|
||||
Маппинг stage -> Plane-статус по таблице ТЗ §2.2: created->To Analyse,
|
||||
analysis->Analysis, architecture->Architecture, development->Development,
|
||||
review->Code-Review, testing->Testing, deploy->Awaiting Deploy, done->Done
|
||||
(параметризованный тест по всем stage).
|
||||
module: tests/test_tracker_status_line.py
|
||||
asserts: "AC-6"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: >
|
||||
analysis + brd_review_started_at задан + brd_review_ended_at пуст ->
|
||||
статус '⏸️ In Review' (ожидание согласования BRD); строка 'Подтверждение
|
||||
BRD' с ⏸️/⏳ сохранена; без сетевых вызовов.
|
||||
module: tests/test_tracker_status_line.py
|
||||
asserts: "AC-7"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: >
|
||||
Awaiting Deploy ('ожидание Confirm Deploy') и Needs Input ('нужны
|
||||
уточнения') корректно отражаются в статус-строке.
|
||||
module: tests/test_tracker_status_line.py
|
||||
asserts: "AC-8"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: >
|
||||
render_task_tracker не падает при битых/недоступных данных статуса
|
||||
(деградация на stage-маппинг/fallback, исключение не наружу).
|
||||
module: tests/test_tracker_status_line.py
|
||||
asserts: "AC-9, AC-16"
|
||||
expected: PASS
|
||||
|
||||
# --- Группа C: кликабельный номер в карточке (AC-10..AC-11) ---
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: >
|
||||
При полных данных (plane_web_url не loopback, workspace, project_id по repo,
|
||||
plane_issue_id) карточка содержит <a href=".../issues/<id>/">ORCH-NNN</a>
|
||||
с корректным URL.
|
||||
module: tests/test_tracker_issue_link.py
|
||||
asserts: "AC-10"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: >
|
||||
Fail-safe ссылки в карточке: при отсутствии любого из (web_base/не-loopback,
|
||||
workspace, project_id, plane_issue_id) номер выводится html.escape без <a>,
|
||||
рендер не падает. Параметризовать по каждому отсутствующему полю.
|
||||
module: tests/test_tracker_issue_link.py
|
||||
asserts: "AC-11"
|
||||
expected: PASS
|
||||
|
||||
# --- Группа D: единый хелпер и уведомления (AC-12..AC-14) ---
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: >
|
||||
plane_issue_link(...) возвращает HTML-ссылку при достаточных данных и
|
||||
html.escape(work_item_id) при недостаточных; никогда не бросает (в т.ч. на
|
||||
None-аргументах и loopback-базе).
|
||||
module: tests/test_plane_issue_link.py
|
||||
asserts: "AC-12"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-13
|
||||
type: unit
|
||||
description: >
|
||||
notify_approve_requested: номер задачи кликабелен (ведёт на страницу Plane),
|
||||
сохранён call-to-action 'Approved', ровно одно notifying-сообщение.
|
||||
module: tests/test_notify_issue_links.py
|
||||
asserts: "AC-13"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: unit
|
||||
description: >
|
||||
notify_error: номер задачи кликабелен при наличии данных, деградирует на
|
||||
сырой номер без падения при их отсутствии.
|
||||
module: tests/test_notify_issue_links.py
|
||||
asserts: "AC-13, AC-12"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-15
|
||||
type: integration
|
||||
description: >
|
||||
Точки send_telegram в stage_engine/launcher/merge_gate/job_reaper/
|
||||
security_gate/reconciler/main, где есть work_item_id, используют
|
||||
plane_issue_link (или эквивалент) — номер кликабелен. Проверка рекордером
|
||||
send_telegram на представительных alert-путях (deploy fail, agent fail,
|
||||
QG fail, прод-деплой).
|
||||
module: tests/test_notify_issue_links.py
|
||||
asserts: "AC-13"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-16
|
||||
type: unit
|
||||
description: >
|
||||
HTML-экранирование: title с '<b>'/'&'/'>' экранируется, <a>-разметка
|
||||
остаётся валидной, сообщение не ломается под parse_mode=HTML (карточка и
|
||||
уведомления).
|
||||
module: tests/test_tracker_issue_link.py
|
||||
asserts: "AC-14"
|
||||
expected: PASS
|
||||
|
||||
# --- Группа E: нерегресс (AC-15..AC-18) ---
|
||||
- id: TC-17
|
||||
type: integration
|
||||
description: >
|
||||
Инварианты: карточка отправляется с disable_notification=True; одна карточка
|
||||
на задачу; транспорт send/edit/delete не изменён по семантике.
|
||||
module: tests/test_tracker_bump_default.py
|
||||
asserts: "AC-15"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-18
|
||||
type: integration
|
||||
description: >
|
||||
Нерегресс существующих тестов нотификаций (test_notify_approve_links.py,
|
||||
test_notify_done_regression.py) и корректная деградация карточки для
|
||||
enduro-trails без новых Plane-статусов.
|
||||
module: tests/test_notify_done_regression.py
|
||||
asserts: "AC-16, AC-17"
|
||||
expected: PASS
|
||||
@@ -1,224 +0,0 @@
|
||||
# ADR-001: Источник Plane-статуса для live-карточки и кликабельный номер задачи
|
||||
|
||||
- **Статус:** Proposed
|
||||
- **Дата:** 2026-06-08
|
||||
- **Задача:** ORCH-067
|
||||
- **Слой:** B (индикация), НЕ слой A (машина стадий) — см. CLAUDE.md / ORCH-066
|
||||
- **Связи:** ORCH-066 (статусная модель Plane, `_PLANE_NAME_TO_KEY` / `_STAGE_TO_STATE_KEY`),
|
||||
ORCH-042 (live-tracker, режимы `edit`/`bump`), ORCH-017 (`_build_plane_issue_link`,
|
||||
`plane_web_url`/`plane_workspace_slug`, loopback-guard), ORCH-059 (Confirm Deploy),
|
||||
ORCH-060 (`fetch_issue_state`), ORCH-010 (`get_project_states` per-project + кэш),
|
||||
adr-0001 (реестр проектов), adr-0010 (post-deploy monitor).
|
||||
|
||||
## Контекст
|
||||
|
||||
ТЗ ORCH-067 (`02-trz.md`) фиксирует объём изменений; данный ADR закрывает развилки,
|
||||
явно отданные архитектору метками `[ARCH]`:
|
||||
|
||||
1. **Источник «истинного» Plane-статуса для веток, не выводимых из `tasks.stage`**
|
||||
(Needs Input, Blocked, Rejected, Cancelled, Deploying, Monitoring after Deploy),
|
||||
при **запрете менять схему БД** (нельзя добавить колонку-флаг). TZ §2.2 предлагает
|
||||
два варианта: (а) best-effort чтение живого Plane-статуса с fail-safe;
|
||||
(б) только stage-выводимые статусы.
|
||||
2. **Способ доступа к `plane_issue_id`/`project_id`** в каждой точке `send_telegram`,
|
||||
где есть только `work_item_id` (требование 4), оставаясь fail-safe.
|
||||
3. Смена дефолта `tracker_mode` (`edit` → `bump`) для общего инстанса.
|
||||
|
||||
### Ключевая находка анализа (определяет развилку 1)
|
||||
|
||||
Когда аналитик задаёт вопросы, `stage_engine.start_pipeline` при наличии
|
||||
`01-questions.md` вызывает `set_issue_needs_input(work_item_id)` (Plane → Needs Input),
|
||||
но **DB-стадия остаётся `analysis`**, а BRD-часы (`brd_review_started_at`) **не
|
||||
запускаются** (они стартуют позже, в `notify_approve_requested`, когда BRD готов).
|
||||
Следовательно состояния **`Analysis` (аналитик работает)** и **`❓ Needs Input`
|
||||
(аналитик ждёт ответа)** **неразличимы** по offline-данным БД (`stage` + brd-clock).
|
||||
Единственный авторитетный источник этого различия — **живой Plane-статус**, который
|
||||
оркестратор сам выставил через `set_issue_needs_input`.
|
||||
|
||||
То же касается `Deploying` / `Monitoring after Deploy`: на стадии `deploy`/`done`
|
||||
конкретная фаза self-deploy видна только в Plane (ORCH-059/ORCH-066), не в `tasks.stage`.
|
||||
|
||||
Вывод: чисто-offline вариант (б) **не покрывает обязательный по DoD `❓ Needs Input`**
|
||||
(AC-8). Нужен гибрид.
|
||||
|
||||
## Решение
|
||||
|
||||
### Р-1. Гибрид: offline-first ядро + best-effort live-overlay
|
||||
|
||||
Статус карточки строится в два слоя; **offline-ядро авторитетно и всегда работает без
|
||||
сети**, live-overlay лишь дорисовывает ветки, неотличимые offline.
|
||||
|
||||
**Слой 1 — чистая offline-функция `plane_status_label(task_row) -> str`** в
|
||||
`src/notifications.py`. Детерминированная, **никогда не бросает**, **никогда не ходит в
|
||||
сеть**. Маппинг (имена статусов — финальные из ORCH-066 `_PLANE_NAME_TO_KEY`):
|
||||
|
||||
| Источник (DB) | Метка карточки |
|
||||
|---|---|
|
||||
| `stage == "created"` | `To Analyse` |
|
||||
| `stage == "analysis"`, brd-clock не запущен | `Analysis` |
|
||||
| `stage == "analysis"`, `brd_review_started_at` есть, `brd_review_ended_at` пуст | `⏸️ In Review — ожидание согласования BRD` |
|
||||
| `stage == "architecture"` | `Architecture` |
|
||||
| `stage == "development"` | `Development` |
|
||||
| `stage == "review"` | `Code-Review` |
|
||||
| `stage == "testing"` | `Testing` |
|
||||
| `stage == "deploy"` | `⏸️ Awaiting Deploy — ожидание Confirm Deploy` |
|
||||
| `stage == "done"` | `Done` |
|
||||
| неизвестный/битый `stage` | дефолт: `html`-безопасная строка по `stage` (или `To Analyse`) |
|
||||
|
||||
Этого слоя достаточно для **`⏸️ In Review`** и **`⏸️ Awaiting Deploy`** — оба
|
||||
обязательны по DoD и **работают без сети** (AC-7, AC-8). `In Review` выводится
|
||||
исключительно из brd-clock.
|
||||
|
||||
**Слой 2 — best-effort live-overlay** `_live_plane_branch_override(repo, plane_issue_id,
|
||||
base_label) -> str` для веток, неразличимых offline: **Needs Input, Blocked, Rejected,
|
||||
Cancelled, Deploying, Monitoring after Deploy**. Алгоритм:
|
||||
|
||||
1. Резолв `project_id` по `repo` (`get_project_by_repo(repo).plane_project_id`).
|
||||
2. `live_uuid = fetch_issue_state(plane_issue_id, project_id)` (ORCH-060) — **с коротким
|
||||
таймаутом** (см. Р-4), не дефолтным 10s.
|
||||
3. Сопоставление `live_uuid` с **конкретными** UUID веток из
|
||||
`get_project_states(project_id)` (кэш ORCH-010): `needs_input`, `blocked`,
|
||||
`cancelled`, `rejected`, `deploying`, `monitoring`.
|
||||
4. Override применяется **только** если `live_uuid` совпал с одним из этих ключей.
|
||||
Иначе возвращается `base_label` (offline-метка).
|
||||
|
||||
**Прецеденс (порядок приоритета):**
|
||||
1. Если offline-ядро дало **`⏸️ In Review`** (brd-clock) — overlay **не вызывается**:
|
||||
brd-clock авторитетнее возможно-устаревшего Plane-чтения для In Review.
|
||||
2. Иначе `base_label` = offline-метка, затем применяется overlay (если включён и удался).
|
||||
|
||||
**Анти-false-positive на enduro (важно):** на enduro-trails ключи `deploying`/
|
||||
`monitoring` алиасят UUID `in_progress`/`done` (`_STATE_ALIAS_FALLBACK`), поэтому прямое
|
||||
сравнение UUID дало бы ложный `Deploying` для любой `in_progress`-задачи. Поэтому для
|
||||
`deploying`/`monitoring` override применяется **только если** их UUID в
|
||||
`get_project_states` **отличается** от UUID базового ключа (т.е. проект реально завёл
|
||||
отдельный статус — это ORCH, не enduro). Ключи `needs_input/blocked/cancelled/rejected`
|
||||
имеют отдельные UUID и на enduro, и на ORCH (`_DEFAULT_STATES`), поэтому различимы всегда.
|
||||
|
||||
### Р-2. Fail-safe и невлияние на конвейер (overlay)
|
||||
|
||||
- `_live_plane_branch_override` обёрнут в `try/except` и **никогда не бросает**; любая
|
||||
ошибка/таймаут/нет сети/нет данных → возвращается `base_label`. Это удовлетворяет
|
||||
«без сети не падать» и AC-9 (рендер карточки никогда не падает).
|
||||
- Нет `plane_issue_id` / нет `project_id` / нет креды → overlay не вызывается, метка =
|
||||
offline-ядро.
|
||||
- **Kill-switch:** новый флаг конфигурации `tracker_live_status: bool = True`
|
||||
(env `ORCH_TRACKER_LIVE_STATUS`). При `False` overlay полностью отключён (никаких
|
||||
сетевых чтений в рендере) — карточка деградирует на offline-ядро. Это аварийный
|
||||
тумблер и страховка от регресса для не-ORCH проектов. **Дефолт `True`**, иначе
|
||||
обязательный по DoD `Needs Input` не отобразится из коробки.
|
||||
|
||||
### Р-3. Кэш live-статуса (защита hot-path)
|
||||
|
||||
`render_task_tracker` вызывается на КАЖДОМ обновлении трекера (старт/финиш агента,
|
||||
переход стадии), а в режиме `bump` — с delete+send каждый раз. Чтобы серия быстрых
|
||||
перерисовок не била по Plane:
|
||||
|
||||
- Добавить **TTL-кэш per-issue** для `live_uuid` (ключ — `plane_issue_id`, TTL
|
||||
`tracker_live_status_ttl_s: int = 60`). По образцу `_STATES_CACHE` в `plane_sync.py`.
|
||||
- На промахе кэша — один `fetch_issue_state` с коротким таймаутом; результат кладётся в
|
||||
кэш. На любой ошибке кэш не портится, возвращается offline-метка.
|
||||
|
||||
Это ограничивает сетевую нагрузку overlay ~одним GET в `TTL` на задачу.
|
||||
|
||||
### Р-4. Короткий таймаут live-чтения в рендере
|
||||
|
||||
`fetch_issue_state` (ORCH-060) хардкодит `timeout=10`. Для пути рендера это слишком
|
||||
долго (рендер синхронный, в линии переходов общего конвейера). Решение: добавить в
|
||||
`fetch_issue_state` **необязательный параметр `timeout`** (дефолт прежний `10` —
|
||||
обратная совместимость для reconciler), а overlay вызывает его с
|
||||
`settings.tracker_live_status_timeout_s` (дефолт **3** с). Поведение/сигнатуры
|
||||
существующих вызовов не меняются.
|
||||
|
||||
### Р-5. Единый хелпер кликабельного номера `plane_issue_link`
|
||||
|
||||
Добавить в `src/notifications.py`:
|
||||
|
||||
```python
|
||||
def plane_issue_link(work_item_id, plane_issue_id=None, project_id=None, repo=None) -> str:
|
||||
"""HTML с кликабельным номером (<a href=...>ORCH-NNN</a>) или html.escape(work_item_id).
|
||||
Никогда не падает."""
|
||||
```
|
||||
|
||||
- Переиспользовать логику и guard'ы `_build_plane_issue_link` (ORCH-017), **разнеся**
|
||||
«текст ссылки = номер задачи» и «текст ссылки = `✅ Задача в Plane`», чтобы не
|
||||
дублировать резолв проекта и loopback-guard. Рекомендуется выделить приватный
|
||||
`_plane_issue_url(repo, plane_issue_id, project_id) -> str | None` (сборка URL +
|
||||
loopback/workspace/project guard), который зовут оба: `plane_issue_link` (текст =
|
||||
номер) и `_build_plane_issue_link` (текст = «✅ Задача в Plane»).
|
||||
- База URL: `plane_web_url` → fallback `plane_api_url`; loopback → «нет web URL»
|
||||
(`_is_loopback_base`).
|
||||
- `project_id`: явный аргумент → иначе резолв по `repo`.
|
||||
- URL: `{web_base}/{workspace}/projects/{project_id}/issues/{plane_issue_id}/`.
|
||||
- Текст = `html.escape(work_item_id)`; `href` = `html.escape(url, quote=True)`.
|
||||
- **Fail-safe:** не хватает любого из (web_base/не-loopback, workspace, project_id,
|
||||
plane_issue_id) → вернуть `html.escape(work_item_id)` (номер без ссылки). Никогда не
|
||||
бросает (AC-11, AC-12).
|
||||
|
||||
### Р-6. Доступ к `plane_issue_id`/`project_id` в точках уведомлений (требование 4)
|
||||
|
||||
В большинстве точек `send_telegram` доступен только `work_item_id`. Решение —
|
||||
тонкая fail-safe обёртка по образцу `_get_task_link_fields`:
|
||||
|
||||
```python
|
||||
def link_for(work_item_id, task_id=None) -> str:
|
||||
"""По work_item_id (или task_id) достать repo+plane_issue_id из БД и вернуть
|
||||
plane_issue_link(...). На любой нехватке данных -> html.escape(work_item_id)."""
|
||||
```
|
||||
|
||||
- Если у точки есть `task_id` — читать `(repo, plane_issue_id)` напрямую из `tasks` по
|
||||
`id`. Если только `work_item_id` — `SELECT repo, plane_issue_id FROM tasks WHERE
|
||||
work_item_id=? ORDER BY id DESC LIMIT 1` (как в `_resolve_project_id`).
|
||||
- Везде, где данных нет — деградация на `html.escape(work_item_id)`, без падения.
|
||||
- Применить во всех точках из TZ §3.3 (`notify_approve_requested`, `notify_error`,
|
||||
`stage_engine`, `launcher`, `merge_gate`, `job_reaper`, `security_gate`, `reconciler`,
|
||||
`main`) — **только там, где упоминается номер задачи**.
|
||||
|
||||
### Р-7. `tracker_mode` дефолт → `bump`
|
||||
|
||||
`src/config.py`: `tracker_mode: str = "edit"` → `"bump"`. Инвариант «одна карточка на
|
||||
задачу» сохранён в обоих режимах (код `update_task_tracker` не меняется по сути).
|
||||
`edit` остаётся доступен через `ORCH_TRACKER_MODE=edit`. Транзиентный фейл `send` не
|
||||
обнуляет `tracker_message_id` (инвариант уже в коде — сохранить).
|
||||
|
||||
### Р-8. Чего НЕ делаем (границы)
|
||||
|
||||
- НЕ менять схему БД, `STAGE_TRANSITIONS`, Quality Gates, транспорт
|
||||
`send_telegram`/`edit_telegram`/`delete_telegram`, `disable_notification`-семантику.
|
||||
- НЕ менять поведение агентов/конвейера. Слой B (индикация) не управляет слоем A.
|
||||
- НЕ добавлять блокирующих сетевых ожиданий в линию переходов сверх одного короткого
|
||||
best-effort GET с кэшем (Р-3/Р-4).
|
||||
- НЕ создавать глобальный (сквозной) ADR: изменение локально для `notifications.py` +
|
||||
один config-дефолт, не вводит новую стадию/QG/компонент. Достаточно per-work-item ADR.
|
||||
|
||||
## Последствия
|
||||
|
||||
**Плюсы**
|
||||
- Обязательные по DoD `⏸️ In Review`, `⏸️ Awaiting Deploy` работают **без сети**
|
||||
(детерминированно, тестируемо offline — AC-6/AC-7).
|
||||
- `❓ Needs Input` (и Blocked/Rejected/Cancelled/Deploying/Monitoring) отражаются через
|
||||
авторитетный источник — живой Plane-статус, который иначе невосстановим из БД.
|
||||
- Единый хелпер ссылки убирает дублирование резолва проекта/loopback-guard (ORCH-017).
|
||||
- Kill-switch + кэш + короткий таймаут ограничивают риск для общего инстанса.
|
||||
|
||||
**Минусы / ограничения**
|
||||
- Overlay добавляет ≤1 короткий GET (3 с таймаут) на задачу в `TTL=60s` в путь рендера.
|
||||
Митигировано кэшем, таймаутом и kill-switch.
|
||||
- При недоступном Plane ветки `Needs Input`/`Blocked`/… деградируют на offline-метку
|
||||
(`Analysis`/stage). Это осознанный, безопасный компромисс (рендер важнее точности
|
||||
ветки; конвейер не блокируется).
|
||||
- На частично сконфигурированном проекте без отдельных статусов `Deploying`/`Monitoring`
|
||||
эти ветки не показываются (alias-guard) — корректная деградация, не баг.
|
||||
|
||||
**Риски** — см. `10-tech-risks.md`.
|
||||
|
||||
## Альтернативы (отклонены)
|
||||
|
||||
- **Только offline (вариант б TZ).** Отклонён: не отличает `Needs Input` от `Analysis`
|
||||
→ не покрывает обязательный AC-8.
|
||||
- **Чтение `01-questions.md` из worktree как offline-сигнал Needs Input.** Отклонён:
|
||||
хрупко (резолв пути worktree из `notifications.py`, файл может пережить ответ,
|
||||
гонки) — менее надёжно, чем авторитетный Plane-статус.
|
||||
- **Добавить DB-колонку-флаг для ветки.** Запрещено TZ (без изменения схемы).
|
||||
- **Асинхронный фон/демон для подтяжки статуса.** Избыточно для слоя индикации; кэш +
|
||||
короткий таймаут дешевле и проще, без нового компонента.
|
||||
@@ -1,46 +0,0 @@
|
||||
# Инфраструктурные требования — ORCH-067
|
||||
|
||||
Топология не меняется (никаких новых контейнеров/портов/сервисов). Изменения —
|
||||
**только конфигурация/env** и обязательный staging-гейт (self-hosting).
|
||||
|
||||
## 1. Изменения конфигурации (`src/config.py`)
|
||||
|
||||
| Поле | env | Старое | Новое | Назначение |
|
||||
|---|---|---|---|---|
|
||||
| `tracker_mode` | `ORCH_TRACKER_MODE` | `"edit"` | `"bump"` (дефолт) | Карточка падает вниз ленты при обновлении (ADR-001 Р-7). `edit` доступен через env. |
|
||||
| `tracker_live_status` | `ORCH_TRACKER_LIVE_STATUS` | — (нет) | `True` (дефолт) | Kill-switch live-overlay Plane-статуса (ADR-001 Р-2). `0/false` → только offline-метки, без сетевых чтений в рендере. |
|
||||
| `tracker_live_status_ttl_s` | `ORCH_TRACKER_LIVE_STATUS_TTL_S` | — | `60` | TTL per-issue кэша live-статуса (ADR-001 Р-3). |
|
||||
| `tracker_live_status_timeout_s` | `ORCH_TRACKER_LIVE_STATUS_TIMEOUT_S` | — | `3` | Короткий таймаут live-чтения в рендере (ADR-001 Р-4). |
|
||||
|
||||
Уже существующие (не менять, использовать): `plane_web_url`
|
||||
(`ORCH_PLANE_WEB_URL`, прод — `https://plane.mva154.duckdns.org`),
|
||||
`plane_workspace_slug` (прод — `ag_proj`), `plane_api_url`.
|
||||
|
||||
## 2. `.env` / `.env.example`
|
||||
|
||||
- Обновить `.env.example`: добавить `ORCH_TRACKER_MODE`, `ORCH_PLANE_WEB_URL`,
|
||||
`ORCH_TRACKER_LIVE_STATUS*` с дефолтами и комментариями (канон настроек —
|
||||
`.env.example`, реальные секреты не коммитить).
|
||||
- На прод-хосте допустимо явно выставить `ORCH_TRACKER_MODE=bump` как страховку, но код
|
||||
обязан работать «из коробки» и без env.
|
||||
- `ORCH_PLANE_WEB_URL` должен быть задан на проде (иначе номер задачи деградирует на
|
||||
текст без ссылки — fail-safe, не падение).
|
||||
|
||||
## 3. Self-hosting (обязательно)
|
||||
|
||||
- **НЕ перезапускать / не ронять** прод-контейнер `orchestrator` (8500) в рамках задачи —
|
||||
общий инстанс/БД с enduro-trails.
|
||||
- Обязательная страховка через `deploy-staging` (8501, изолированная БД) **до** прод-деплоя.
|
||||
На staging проверить:
|
||||
- режим `bump`: одна карточка на задачу, падает вниз, тихо (без звука), без дублей;
|
||||
- статус-строка: `⏸️ In Review`, `⏸️ Awaiting Deploy`, `❓ Needs Input` отображаются;
|
||||
- кликабельный номер ведёт на страницу Plane;
|
||||
- **нет регресса для enduro-trails** (карточка без новых статусов деградирует корректно).
|
||||
- Прод-деплой орка — только переводом задачи на стадии `deploy` в статус
|
||||
**«Confirm Deploy»** (ORCH-059), не `Approved`.
|
||||
|
||||
## 4. Сетевые требования
|
||||
|
||||
- Live-overlay требует доступности Plane API (`plane_api_url`) из контейнера — он уже
|
||||
есть (используется plane_sync). Недоступность Plane → graceful degrade на offline-метку,
|
||||
конвейер не блокируется (короткий таймаут + kill-switch).
|
||||
@@ -1,35 +0,0 @@
|
||||
# Требования к данным — ORCH-067
|
||||
|
||||
## Изменения схемы БД: НЕТ
|
||||
|
||||
`STAGE_TRANSITIONS`, таблицы и колонки `tasks`/`agent_runs` **не меняются**. Это жёсткое
|
||||
ограничение TZ §6 и предпосылка ADR-001 (запрет колонки-флага для веток статуса).
|
||||
|
||||
## Читаемые колонки `tasks` (существующие)
|
||||
|
||||
| Колонка | Использование в ORCH-067 |
|
||||
|---|---|
|
||||
| `id` | Ключ задачи. |
|
||||
| `work_item_id` | Текст номера (`ORCH-NNN`) + ключ резолва в `link_for`. |
|
||||
| `title` | Заголовок карточки (`html.escape`). |
|
||||
| `stage` | Offline-маппинг Plane-статуса (ADR-001 Р-1, слой 1). |
|
||||
| `brd_review_started_at`, `brd_review_ended_at` | Различение `Analysis` ↔ `⏸️ In Review` (offline, без сети). |
|
||||
| `repo` | Резолв `project_id` (`get_project_by_repo`) для ссылки и live-overlay. |
|
||||
| `plane_issue_id` (UUID) | `issue_id` в URL Plane + аргумент `fetch_issue_state` (live-overlay). |
|
||||
| `created_at`, `updated_at` | Тоталы времени в done-строке (без изменений). |
|
||||
|
||||
`render_task_tracker` **расширяет существующий `SELECT`** по `tasks`, добавляя `repo` и
|
||||
`plane_issue_id` к уже выбираемым полям. Схему это не трогает — колонки уже есть.
|
||||
|
||||
## Кэш в памяти (не БД)
|
||||
|
||||
Per-issue TTL-кэш live-статуса (ключ `plane_issue_id`, TTL
|
||||
`tracker_live_status_ttl_s=60`, ADR-001 Р-3) — **in-memory**, по образцу `_STATES_CACHE`
|
||||
в `plane_sync.py`. Не персистится, переживание рестарта не требуется (best-effort
|
||||
индикация). Очистка при рестарте — допустима.
|
||||
|
||||
## Источник имён статусов
|
||||
|
||||
Имена и логические ключи статусов берутся из существующих структур `src/plane_sync.py`
|
||||
(`_PLANE_NAME_TO_KEY`, `get_project_states`, `_DEFAULT_STATES`), вводимых ORCH-066.
|
||||
Новых статусов/ключей ORCH-067 **не добавляет**.
|
||||
@@ -1,21 +0,0 @@
|
||||
# Технические риски — ORCH-067
|
||||
|
||||
| # | Риск | Вероятность / Влияние | Митигация (ADR-001) | Остаточный риск |
|
||||
|---|---|---|---|---|
|
||||
| R-1 | **Регресс enduro-trails** при смене дефолта `tracker_mode` → `bump` (другое поведение карточки для всех проектов). | Сред / Сред | Инвариант «одна карточка на задачу» сохранён; `edit` доступен через env; проверка на staging + тесты нерегресса (AC-16). | Низкий |
|
||||
| R-2 | **Поломка HTML-разметки** неэкранированным `title`/причиной → сообщение с `parse_mode=HTML` не доставится. | Сред / Сред | Обязательный `html.escape` для всего пользовательского текста; `href` через `html.escape(url, quote=True)`; тест с `<b>`/`&` (AC-14). | Низкий |
|
||||
| R-3 | **Latency в hot-path конвейера**: live-overlay добавляет сетевой GET в синхронный рендер, вызываемый на каждом переходе/в bump. | Сред / Сред | Короткий таймаут 3 с (Р-4) + per-issue TTL-кэш 60 с (Р-3) + kill-switch `ORCH_TRACKER_LIVE_STATUS=0` (Р-2). ≤1 GET на задачу за TTL. | Низкий |
|
||||
| R-4 | **Рендер карточки падает** на битых данных/недоступном Plane. | Низк / Выс | `plane_status_label` чистая и never-raise; overlay в `try/except` → degrade на offline-метку; `render_task_tracker` уже never-raise (AC-9). | Очень низкий |
|
||||
| R-5 | **Ложный `Deploying`/`Monitoring` на enduro** (их UUID алиасит `in_progress`/`done`). | Сред / Низк | Override этих веток только если UUID статуса ≠ UUID базового ключа в `get_project_states` (Р-1, anti-false-positive). | Очень низкий |
|
||||
| R-6 | **Устаревший Plane-статус из кэша** показывает неактуальную ветку (например, `Needs Input` после ответа). | Сред / Низк | TTL 60 с самозаживает; offline-ядро авторитетно для In Review (brd-clock не оверрайдится). Индикация, не управление — расхождение косметическое. | Низкий |
|
||||
| R-7 | **Транзиентный фейл `send` плодит дубли / обнуляет указатель** в bump. | Низк / Сред | Инвариант уже в коде (`set_tracker_message_id` только при `new_mid is not None`); не менять; тест AC-3. | Низкий |
|
||||
| R-8 | **Self-hosting**: деплой орка ломает общий инстанс (enduro + ORCH, общая БД/очередь). | Низк / Выс | Обязательный staging-гейт (8501) до прода; прод-контейнер не ронять в задаче; прод-деплой только через «Confirm Deploy». | Низкий |
|
||||
| R-9 | **Пропущенная точка** уведомления с сырым номером (требование 4 — много call-sites). | Сред / Низк | Единый `link_for`/`plane_issue_link`; чек-лист точек из TZ §3.3; reviewer проверяет покрытие (AC-13). | Низкий |
|
||||
| R-10 | **Рассинхрон имён статусов** с ORCH-066, если та не в проде на момент разработки. | Низк / Низк | Имена берутся из `_PLANE_NAME_TO_KEY` (golden source); делать после прода ORCH-066 (BRD §6). | Низкий |
|
||||
|
||||
## Сводно
|
||||
|
||||
Все остаточные риски — низкие/очень низкие после митигаций. Главные защитные контуры:
|
||||
(1) offline-ядро статуса не требует сети и детерминировано; (2) live-overlay полностью
|
||||
best-effort с таймаутом+кэшем+kill-switch; (3) обязательный staging-гейт перед прод-деплоем
|
||||
общего инстанса (self-hosting).
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-067
|
||||
verdict: APPROVED
|
||||
version: 2
|
||||
---
|
||||
|
||||
# Review ORCH-067
|
||||
|
||||
## Summary
|
||||
|
||||
Повторное ревью после фикса документации (коммит `7a88f39`). Реализация полностью
|
||||
соответствует ТЗ (`02-trz.md`), ADR-001 и всем acceptance criteria (`03-acceptance-criteria.md`).
|
||||
|
||||
**Код** (`src/notifications.py` — ядро):
|
||||
- **Req 1 (bump):** дефолт `tracker_mode` сменён `edit → bump` (`src/config.py`); логика
|
||||
`update_task_tracker`, транспорт `send/edit/delete_telegram`, `disable_notification` и
|
||||
инвариант «одна карточка на задачу» не тронуты (AC-1..AC-4, AC-15 ✓).
|
||||
- **Req 2 (статус-строка):** чистый never-raise `plane_status_label(task_row)` (offline-ядро:
|
||||
stage→статус + `⏸️ In Review` из brd-clock + `⏸️ Awaiting Deploy`, всё без сети) +
|
||||
best-effort `_live_plane_branch_override` для ветвей, неотличимых offline (Needs Input /
|
||||
Blocked / Rejected / Cancelled / Deploying / Monitoring). Kill-switch
|
||||
(`tracker_live_status`), per-issue TTL-кэш (`_LIVE_STATE_CACHE`), короткий таймаут
|
||||
(`fetch_issue_state(..., timeout=)`, дефолт 10 сохранён → нет регресса reconciler).
|
||||
Anti-false-positive guard для enduro (`_LIVE_BRANCH_BASE`: deploying/monitoring override
|
||||
только при отдельном UUID). Прецеденс In Review > overlay соблюдён. `_card_status_label`
|
||||
обёрнут в try/except → рендер никогда не падает (AC-5..AC-9 ✓).
|
||||
- **Req 3+4 (кликабельный номер):** единый `_plane_issue_url` устраняет дублирование
|
||||
резолва проекта/loopback-guard (ORCH-017); `plane_issue_link` (текст=номер) и
|
||||
`_build_plane_issue_link` (текст=«✅ Задача в Plane») оба зовут его. `link_for` fail-safe
|
||||
достаёт `repo`/`plane_issue_id` из БД. Применено в заголовке карточки и во ВСЕХ точках
|
||||
§3.3 с номером задачи (AC-10..AC-14 ✓).
|
||||
|
||||
**Точки §3.3 проверены пофайлово:** `notify_approve_requested`, `notify_error`,
|
||||
`stage_engine.py` (все alert'ы с номером), `agents/launcher.py`, `security_gate.py`,
|
||||
`reconciler.py` — номер кликабелен. `merge_gate.py`/`job_reaper.py`/`main.py` оставлены без
|
||||
ссылки **осознанно и корректно**: их тексты ссылаются на repo/job/run_id, а НЕ на
|
||||
`work_item_id` (проверено: merge_gate:432 — lease/repo, job_reaper:396 — job/agent/repo,
|
||||
main:47 — orphaned run_ids).
|
||||
|
||||
**Инварианты/нерегресс:** схема БД, `STAGE_TRANSITIONS`, QG, транспорт — не тронуты
|
||||
(AC-15 ✓). `get_db()` возвращает новое соединение на вызов, поэтому `conn.close()` в
|
||||
`link_for` корректен. `pytest tests/ -q` → **907 passed** (AC-16, AC-17 ✓).
|
||||
|
||||
**Документация (блокеры v1 закрыты):** `CHANGELOG.md`, `CLAUDE.md`, `.env.example`
|
||||
обновлены в коммите `7a88f39`; ADR-001 присутствует и полон; `README.md`/`internals.md`
|
||||
синхронизированы (AC-18 ✓).
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- (нет)
|
||||
|
||||
### P1 — Must fix
|
||||
- (нет)
|
||||
|
||||
### P2 — Should fix
|
||||
- (нет)
|
||||
|
||||
### P3 — Nice to have (не блокирует)
|
||||
- [ ] Часть alert-сообщений в `stage_engine.py` (`_handle_self_deploy_phase_b`,
|
||||
`_handle_merge_verify`) встраивает «сырой» `{msg}`/`{e}`/`{reason}` рядом с новой
|
||||
`<a>`-ссылкой; под `parse_mode=HTML` редкий `<` в этих подстановках теоретически мог
|
||||
бы помешать рендеру. Это **пре-существующее поведение** (parse_mode=HTML стоял и
|
||||
раньше), не регресс данной задачи; `notify_error` свой `error` экранирует. Можно при
|
||||
случае обернуть прочие подстановки в `html.escape`.
|
||||
|
||||
## Документация
|
||||
|
||||
- `docs/architecture/README.md` — обновлён (компонент Notifications / live-tracker). ✓
|
||||
- `docs/architecture/internals.md` — обновлён (§7: bump/edit, Plane-статус, кликабельный номер). ✓
|
||||
- `06-adr/ADR-001-tracker-plane-status-and-link.md` — присутствует, полный, закрывает все `[ARCH]`. ✓
|
||||
- `CHANGELOG.md` — обновлён (запись ORCH-067). ✓
|
||||
- `CLAUDE.md` — обновлён (раздел «Нотификации / Telegram live-tracker»). ✓
|
||||
- `.env.example` — синхронизирован (`ORCH_TRACKER_MODE=bump` + новые флаги live-overlay). ✓
|
||||
|
||||
Документация = golden source: код и доку обновлены в одном PR. Блокеры предыдущего ревью
|
||||
(v1) закрыты. Замечаний уровня P0/P1/P2 нет → **APPROVED**.
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-067
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-067
|
||||
|
||||
Telegram tracker: bump по умолчанию, статус-строка карточки по модели Plane (ORCH-066),
|
||||
кликабельный номер задачи в карточке и во всех уведомлениях орка.
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Ветка: `feature/ORCH-067-telegram-tracker-bump-plane` (worktree)
|
||||
- Дата: 2026-06-08
|
||||
- Review-вердикт: APPROVED (`12-review.md`, version 2)
|
||||
|
||||
## Smoke test API (prod, :8500)
|
||||
| Endpoint | Результат |
|
||||
|----------|-----------|
|
||||
| `GET /health` | PASS — `{"status":"ok","service":"orchestrator"}` |
|
||||
| `GET /status` | PASS — отдаёт active_tasks (ORCH-067 на stage=testing) |
|
||||
| `GET /queue` | PASS — breaker closed, preflight_ok, counts корректны |
|
||||
|
||||
Прод-контейнер не перезапускался (self-hosting инвариант соблюдён).
|
||||
|
||||
## Результаты по тест-плану (04-test-plan.yaml)
|
||||
|
||||
| TC ID | Описание | Модуль | AC | Результат |
|
||||
|-------|----------|--------|----|-----------|
|
||||
| TC-01 | Дефолт `tracker_mode == "bump"` без env | test_tracker_bump_default.py | AC-1 | PASS |
|
||||
| TC-02 | bump: delete(old)→send(silent)→repoint, одна карточка | test_tracker_bump_default.py | AC-2 | PASS |
|
||||
| TC-03 | bump fail-safe: send=None не обнуляет указатель | test_tracker_bump_default.py | AC-3 | PASS |
|
||||
| TC-04 | `ORCH_TRACKER_MODE=edit` — прежнее поведение | test_tracker_bump_default.py | AC-4 | PASS |
|
||||
| TC-05 | Карточка содержит строку Plane-статуса | test_tracker_status_line.py | AC-5 | PASS |
|
||||
| TC-06 | Маппинг stage → Plane-статус (§2.2, параметризованный) | test_tracker_status_line.py | AC-6 | PASS |
|
||||
| TC-07 | In Review из brd-clock, без сети; строка «Подтверждение BRD» сохранена | test_tracker_status_line.py | AC-7 | PASS |
|
||||
| TC-08 | Awaiting Deploy + Needs Input отражены | test_tracker_status_line.py | AC-8 | PASS |
|
||||
| TC-09 | render_task_tracker не падает на битых данных | test_tracker_status_line.py | AC-9, AC-16 | PASS |
|
||||
| TC-10 | Кликабельный номер в карточке при полных данных | test_tracker_issue_link.py | AC-10 | PASS |
|
||||
| TC-11 | Fail-safe ссылки в карточке (параметризованный) | test_tracker_issue_link.py | AC-11 | PASS |
|
||||
| TC-12 | `plane_issue_link(...)` — ссылка/escape, никогда не бросает | test_plane_issue_link.py | AC-12 | PASS |
|
||||
| TC-13 | notify_approve_requested: номер кликабелен, одна нотификация | test_notify_issue_links.py | AC-13 | PASS |
|
||||
| TC-14 | notify_error: кликабелен/деградирует без падения | test_notify_issue_links.py | AC-13, AC-12 | PASS |
|
||||
| TC-15 | Точки send_telegram (stage_engine/launcher/merge_gate/job_reaper/security_gate/reconciler/main) используют хелпер | test_notify_issue_links.py | AC-13 | PASS |
|
||||
| TC-16 | HTML-экранирование title/`&`, валидность `<a>` | test_tracker_issue_link.py | AC-14 | PASS |
|
||||
| TC-17 | Инварианты транспорта: disable_notification, одна карточка | test_tracker_bump_default.py | AC-15 | PASS |
|
||||
| TC-18 | Нерегресс нотификаций + деградация для enduro-trails | test_notify_done_regression.py | AC-16, AC-17 | PASS |
|
||||
|
||||
Все 18 TC из тест-плана — PASS. Целевые модули: **57 passed**.
|
||||
|
||||
## Покрытие acceptance criteria
|
||||
AC-1..AC-18 — все покрыты соответствующими TC и зелёные. AC-17 (полный набор) подтверждён
|
||||
прогоном всего пакета.
|
||||
|
||||
## Вывод pytest (полный регресс)
|
||||
|
||||
```
|
||||
$ python -m pytest tests/ -v --tb=short
|
||||
...
|
||||
======================= 907 passed, 1 warning in 22.36s ========================
|
||||
```
|
||||
|
||||
Единственный warning — пре-существующий `PydanticDeprecatedSince20` в `src/config.py:4`
|
||||
(не относится к ORCH-067, не регресс).
|
||||
|
||||
Целевые модули задачи:
|
||||
```
|
||||
$ python -m pytest tests/test_tracker_bump_default.py tests/test_tracker_status_line.py \
|
||||
tests/test_tracker_issue_link.py tests/test_plane_issue_link.py \
|
||||
tests/test_notify_issue_links.py tests/test_notify_done_regression.py -q
|
||||
57 passed, 1 warning in 1.39s
|
||||
```
|
||||
|
||||
## Итог
|
||||
**PASS** — 907/907 тестов зелёные, все 18 TC и AC-1..AC-18 выполнены, smoke API OK,
|
||||
нерегресс для enduro-trails подтверждён. Задача готова к переходу на `deploy-staging`.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
work_item: ORCH-067
|
||||
hook_exit_code: 0
|
||||
deployed_by: deploy-finalizer
|
||||
---
|
||||
|
||||
# Deploy log — ORCH-036 executable self-deploy
|
||||
|
||||
Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
|
||||
|
||||
Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
post_deploy_status: HEALTHY
|
||||
action_taken: NONE
|
||||
work_item: ORCH-067
|
||||
window_s: 900
|
||||
checks_total: 30
|
||||
checks_failed: 0
|
||||
---
|
||||
|
||||
# Post-deploy log — ORCH-021 post-deploy monitor
|
||||
|
||||
Наблюдение прода завершено: `post_deploy_status: HEALTHY`, `action_taken: NONE`.
|
||||
|
||||
Окно наблюдения: 900s; опросов всего: 30, из них с провалом: 0.
|
||||
25
docs/work-items/ORCH-069/15-staging-log.md
Normal file
25
docs/work-items/ORCH-069/15-staging-log.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
timestamp: 2026-06-08T11:20:02+00:00
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite completed via `docker exec orchestrator-staging python3 /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub` (run through the Docker Engine API since the `docker` CLI is not installed on the host; equivalent in-container execution per ORCH-048/ADR-001).
|
||||
|
||||
**Result: 8/10 checks PASS — exit code 0 → SUCCESS.**
|
||||
|
||||
All REAL (pipeline) checks are green. The two failing checks are the known SANDBOX_INFRA checks (C9a/C9b), waived per ORCH-061 because every REAL check passed.
|
||||
|
||||
```
|
||||
INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
|
||||
VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
|
||||
```
|
||||
|
||||
## Block results
|
||||
- **[Block A] SMOKE** — A1 /health 200 ok ✓ · A2 /queue 200 with counts ✓ · A3 ORCH_STAGING=true ✓
|
||||
- **[Block B] ACCESS** — B4 Plane sandbox accessible ✓ · B5 Gitea orchestrator-sandbox push=true ✓ · B6 Registry isolation (sandbox present, prod ET/ORCH absent) ✓
|
||||
- **[Block C] E2E (stub)** — C7 Create issue in Plane SANDBOX ✓ · C8 Trigger pipeline via /webhook/plane ✓ · C9a Branch appears in orchestrator-sandbox ✗ (SANDBOX_INFRA, waived) · C9b Analyst job enqueued ✗ (SANDBOX_INFRA, waived)
|
||||
|
||||
REAL failed: none. SANDBOX_INFRA failed: C9a, C9b (waived). tolerance: staging_infra_tolerance_enabled=True.
|
||||
@@ -682,8 +682,8 @@ class AgentLauncher:
|
||||
"\u274c Deploy FAILED (smoke/healthcheck). Rolled back. Developer \u043d\u0443\u0436\u0435\u043d \u0434\u043b\u044f \u0444\u0438\u043a\u0441\u0430.",
|
||||
author="deployer",
|
||||
)
|
||||
from ..notifications import send_telegram, link_for
|
||||
send_telegram(f"\U0001f6a8 {link_for(_wid)}: Deploy failed! Rolled back. Needs fix.")
|
||||
from ..notifications import send_telegram
|
||||
send_telegram(f"\U0001f6a8 {_wid}: Deploy failed! Rolled back. Needs fix.")
|
||||
|
||||
# Notify on startup timeout (exit_code from kill = -9 or 137)
|
||||
if exit_code != 0 and exit_code not in (None,):
|
||||
@@ -695,8 +695,8 @@ class AgentLauncher:
|
||||
conn.close()
|
||||
if task_row and agent != "deployer": # deployer handled above
|
||||
_tid, _wid = task_row
|
||||
from ..notifications import send_telegram, link_for
|
||||
send_telegram(f"\u26a0\ufe0f {link_for(_wid, _tid)}: Agent {agent} failed (exit_code={exit_code}). Check logs: /app/data/runs/{run_id}.log")
|
||||
from ..notifications import send_telegram
|
||||
send_telegram(f"\u26a0\ufe0f {_wid}: Agent {agent} failed (exit_code={exit_code}). Check logs: /app/data/runs/{run_id}.log")
|
||||
|
||||
# Feature 4 + ORCH-016: post the unified per-agent status comment under
|
||||
# that agent's bot, threading the wall-clock duration we just measured
|
||||
|
||||
@@ -400,27 +400,12 @@ class Settings(BaseSettings):
|
||||
telegram_chat_id: str = ""
|
||||
|
||||
# ORCH-042: режим live-трекера задачи.
|
||||
# bump (ДЕФОЛТ с ORCH-067) -> при обновлении старое сообщение удаляется и
|
||||
# карточка отправляется заново вниз чата (deleteMessage + sendMessage
|
||||
# + repoint message_id), тихо (disable_notification).
|
||||
# edit -> карточка редактируется на месте (editMessageText); доступен через
|
||||
# ORCH_TRACKER_MODE=edit.
|
||||
# Одна карточка на задачу в обоих режимах. Неизвестное/пустое значение
|
||||
# трактуется как edit (см. notifications).
|
||||
tracker_mode: str = "bump"
|
||||
|
||||
# ORCH-067 (ADR Р-2/Р-3/Р-4): best-effort live-overlay для статус-строки
|
||||
# карточки. Дорисовывает ветки Plane-статуса, неотличимые offline по
|
||||
# tasks.stage (Needs Input / Blocked / Rejected / Cancelled / Deploying /
|
||||
# Monitoring after Deploy) — читая ЖИВОЙ Plane-статус с коротким таймаутом и
|
||||
# TTL-кэшем. Offline-ядро (stage -> статус, In Review из brd-clock) работает
|
||||
# всегда без сети; overlay лишь дополняет его и НИКОГДА не блокирует конвейер.
|
||||
# tracker_live_status -> kill-switch (False -> только offline-ядро).
|
||||
# tracker_live_status_ttl_s -> TTL per-issue кэша live-uuid (защита hot-path).
|
||||
# tracker_live_status_timeout_s -> таймаут одного live-GET в пути рендера.
|
||||
tracker_live_status: bool = True
|
||||
tracker_live_status_ttl_s: int = 60
|
||||
tracker_live_status_timeout_s: int = 3
|
||||
# edit -> карточка редактируется на месте (editMessageText), ДЕФОЛТ (как было).
|
||||
# bump -> при обновлении старое сообщение удаляется и карточка отправляется
|
||||
# заново вниз чата (deleteMessage + sendMessage + repoint message_id),
|
||||
# тихо (disable_notification). Одна карточка на задачу в обоих режимах.
|
||||
# Неизвестное/пустое значение трактуется как edit (см. notifications).
|
||||
tracker_mode: str = "edit"
|
||||
|
||||
class Config:
|
||||
env_prefix = "ORCH_"
|
||||
|
||||
@@ -307,7 +307,7 @@ def render_task_tracker(task_id: int) -> str:
|
||||
conn = get_db()
|
||||
task = conn.execute(
|
||||
"SELECT id, work_item_id, title, stage, created_at, updated_at, "
|
||||
"brd_review_started_at, brd_review_ended_at, repo, plane_issue_id "
|
||||
"brd_review_started_at, brd_review_ended_at "
|
||||
"FROM tasks WHERE id=?",
|
||||
(task_id,),
|
||||
).fetchone()
|
||||
@@ -358,27 +358,13 @@ def render_task_tracker(task_id: int) -> str:
|
||||
agent_seconds += d
|
||||
|
||||
esc_title = html.escape(title)
|
||||
# ORCH-067 (req 3): the issue number in the header is now a clickable link to
|
||||
# the Plane issue (degrades to the escaped number when no web URL \u2014 fail-safe).
|
||||
task_repo = _row_get(task, "repo")
|
||||
task_issue_id = _row_get(task, "plane_issue_id")
|
||||
num_html = plane_issue_link(work_item_id, plane_issue_id=task_issue_id, repo=task_repo)
|
||||
header = (
|
||||
f"\U0001f389 {num_html} \u00b7 {esc_title} \u2014 \u0413\u041e\u0422\u041e\u0412\u041e"
|
||||
f"\U0001f389 {html.escape(work_item_id)} \u00b7 {esc_title} \u2014 \u0413\u041e\u0422\u041e\u0412\u041e"
|
||||
if done
|
||||
else f"\U0001f6e0\ufe0f {num_html} \u00b7 {esc_title}"
|
||||
else f"\U0001f6e0\ufe0f {html.escape(work_item_id)} \u00b7 {esc_title}"
|
||||
)
|
||||
bar = "\u2501" * 22
|
||||
# ORCH-067 (req 2): a Plane-status line (model ORCH-066) under the header.
|
||||
# Built fail-safe: any error degrades to a stage default, never breaks render.
|
||||
try:
|
||||
status_label = _card_status_label(
|
||||
task, repo=task_repo, plane_issue_id=task_issue_id
|
||||
)
|
||||
except Exception:
|
||||
status_label = _DEFAULT_STATUS_LABEL
|
||||
status_line = f"\U0001f4cd {status_label}"
|
||||
lines = [header, status_line, bar]
|
||||
lines = [header, bar]
|
||||
|
||||
def _stage_line(label, run):
|
||||
usage = {
|
||||
@@ -718,276 +704,38 @@ def _build_brd_link(repo, branch, work_item_id) -> str | None:
|
||||
)
|
||||
|
||||
|
||||
def _plane_issue_url(repo, plane_issue_id, project_id=None) -> str | None:
|
||||
"""ORCH-067 (Р-5): build the Plane issue browser URL, or None if unbuildable.
|
||||
|
||||
Single source of the URL + guards, shared by ``plane_issue_link`` (link text =
|
||||
issue number) and ``_build_plane_issue_link`` (link text = '✅ Задача в Plane'),
|
||||
so the project resolution and loopback-guard live in ONE place (ORCH-017 Р-2).
|
||||
|
||||
Full path: ``{web_base}/{workspace}/projects/{project_id}/issues/{issue_id}/``.
|
||||
web_base = plane_web_url or plane_api_url; a loopback base counts as "no web
|
||||
URL" -> None. ``project_id`` is taken explicitly when given, else resolved from
|
||||
``repo``. Never raises.
|
||||
"""
|
||||
try:
|
||||
s = _get_settings()
|
||||
web_base = (
|
||||
getattr(s, "plane_web_url", "") or getattr(s, "plane_api_url", "")
|
||||
).rstrip("/")
|
||||
workspace = getattr(s, "plane_workspace_slug", "")
|
||||
if not (web_base and workspace and plane_issue_id) or _is_loopback_base(web_base):
|
||||
return None
|
||||
if not project_id:
|
||||
try:
|
||||
from .projects import get_project_by_repo
|
||||
project = get_project_by_repo(repo) if repo else None
|
||||
except Exception:
|
||||
project = None
|
||||
project_id = getattr(project, "plane_project_id", "") if project else ""
|
||||
if not project_id:
|
||||
return None
|
||||
return (
|
||||
f"{web_base}/{workspace}/projects/{project_id}/issues/{plane_issue_id}/"
|
||||
)
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
|
||||
def _build_plane_issue_link(repo, plane_issue_id) -> str | None:
|
||||
"""ORCH-017: '<a>' to the Plane issue browser page, or None if unusable.
|
||||
|
||||
Link text = '✅ Задача в Plane'. URL built by the shared ``_plane_issue_url``
|
||||
(loopback / workspace / project guards, ADR-001 Р-2 / ORCH-067 Р-5).
|
||||
Full path per ADR-001 Р-2:
|
||||
``{web_base}/{workspace_slug}/projects/{project_id}/issues/{issue_id}/``.
|
||||
web_base = plane_web_url or plane_api_url (AC-3); a loopback base is treated
|
||||
as "no web URL" and the link is omitted (loopback-guard, AC-2/AC-6).
|
||||
"""
|
||||
url = _plane_issue_url(repo, plane_issue_id)
|
||||
if not url:
|
||||
s = _get_settings()
|
||||
web_base = (
|
||||
getattr(s, "plane_web_url", "") or getattr(s, "plane_api_url", "")
|
||||
).rstrip("/")
|
||||
workspace = getattr(s, "plane_workspace_slug", "")
|
||||
if not (web_base and workspace and plane_issue_id) or _is_loopback_base(web_base):
|
||||
return None
|
||||
try:
|
||||
from .projects import get_project_by_repo
|
||||
project = get_project_by_repo(repo) if repo else None
|
||||
except Exception:
|
||||
project = None
|
||||
if not project or not getattr(project, "plane_project_id", ""):
|
||||
return None
|
||||
url = (
|
||||
f"{web_base}/{workspace}/projects/{project.plane_project_id}"
|
||||
f"/issues/{plane_issue_id}/"
|
||||
)
|
||||
return (
|
||||
f'<a href="{html.escape(url, quote=True)}">'
|
||||
f"✅ Задача в Plane</a>"
|
||||
)
|
||||
|
||||
|
||||
def plane_issue_link(work_item_id, plane_issue_id=None, project_id=None, repo=None) -> str:
|
||||
"""ORCH-067 (Р-5): clickable issue number for cards / alerts.
|
||||
|
||||
Returns ``<a href=...>ORCH-NNN</a>`` when a Plane web URL can be built, else
|
||||
``html.escape(work_item_id)`` (number without a link). Never raises.
|
||||
|
||||
Link text is always ``html.escape(work_item_id)``; the href is built by the
|
||||
shared ``_plane_issue_url`` (same loopback / workspace / project guards as the
|
||||
'✅ Задача в Plane' link). On any missing piece -> the escaped number.
|
||||
"""
|
||||
label = html.escape(str(work_item_id)) if work_item_id is not None else ""
|
||||
try:
|
||||
url = _plane_issue_url(repo, plane_issue_id, project_id)
|
||||
if not url:
|
||||
return label
|
||||
return f'<a href="{html.escape(url, quote=True)}">{label}</a>'
|
||||
except Exception:
|
||||
return label
|
||||
|
||||
|
||||
def link_for(work_item_id, task_id=None) -> str:
|
||||
"""ORCH-067 (Р-6): clickable issue number for alert points that hold only a
|
||||
``work_item_id`` (or ``task_id``).
|
||||
|
||||
Resolves ``(repo, plane_issue_id)`` from the DB (by ``task_id`` when given,
|
||||
else the latest task row for ``work_item_id``) and delegates to
|
||||
``plane_issue_link``. On any missing data -> ``html.escape(work_item_id)``.
|
||||
Never raises.
|
||||
"""
|
||||
if not work_item_id:
|
||||
return html.escape(str(work_item_id)) if work_item_id is not None else ""
|
||||
repo = None
|
||||
plane_issue_id = None
|
||||
try:
|
||||
from .db import get_db
|
||||
conn = get_db()
|
||||
if task_id is not None:
|
||||
row = conn.execute(
|
||||
"SELECT repo, plane_issue_id FROM tasks WHERE id=?", (task_id,)
|
||||
).fetchone()
|
||||
else:
|
||||
row = conn.execute(
|
||||
"SELECT repo, plane_issue_id FROM tasks WHERE work_item_id=? "
|
||||
"ORDER BY id DESC LIMIT 1",
|
||||
(work_item_id,),
|
||||
).fetchone()
|
||||
conn.close()
|
||||
if row:
|
||||
repo = row["repo"]
|
||||
plane_issue_id = row["plane_issue_id"]
|
||||
except Exception as e:
|
||||
logger.debug(f"link_for({work_item_id}) DB lookup failed: {e}")
|
||||
return plane_issue_link(work_item_id, plane_issue_id=plane_issue_id, repo=repo)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# ORCH-067: Plane status label for the live card (layer B indication, ADR Р-1)
|
||||
# --------------------------------------------------------------------------- #
|
||||
|
||||
# Offline stage -> Plane status label. Names are the final ORCH-066 status names
|
||||
# (_PLANE_NAME_TO_KEY). Pure / deterministic — derived entirely from tasks.stage
|
||||
# (+ the brd-clock for In Review), NEVER from the network.
|
||||
_STAGE_STATUS_LABEL = {
|
||||
"created": "To Analyse",
|
||||
"analysis": "Analysis",
|
||||
"architecture": "Architecture",
|
||||
"development": "Development",
|
||||
"review": "Code-Review",
|
||||
"testing": "Testing",
|
||||
"deploy": "⏸️ Awaiting Deploy — ожидание Confirm Deploy",
|
||||
"done": "Done",
|
||||
}
|
||||
_DEFAULT_STATUS_LABEL = "To Analyse"
|
||||
_IN_REVIEW_LABEL = (
|
||||
"⏸️ In Review — ожидание "
|
||||
"согласования BRD"
|
||||
)
|
||||
|
||||
# Live-overlay branch labels (keys not derivable offline from tasks.stage).
|
||||
_LIVE_BRANCH_LABELS = {
|
||||
"needs_input": "❓ Needs Input — нужны уточнения",
|
||||
"blocked": "Blocked",
|
||||
"rejected": "Rejected",
|
||||
"cancelled": "Cancelled",
|
||||
"deploying": "Deploying",
|
||||
"monitoring": "Monitoring after Deploy",
|
||||
}
|
||||
# ORCH-066 (Р-1 anti-false-positive): deploying/monitoring alias their BASE key's
|
||||
# UUID on a project without dedicated statuses (enduro). Override is applied ONLY
|
||||
# when the project really defined a SEPARATE UUID for the branch key.
|
||||
_LIVE_BRANCH_BASE = {
|
||||
"deploying": "in_progress",
|
||||
"monitoring": "done",
|
||||
}
|
||||
|
||||
|
||||
def _row_get(row, key, default=None):
|
||||
"""Safe sqlite3.Row / dict / object getter. Never raises."""
|
||||
try:
|
||||
return row[key]
|
||||
except Exception:
|
||||
try:
|
||||
return getattr(row, key, default)
|
||||
except Exception:
|
||||
return default
|
||||
|
||||
|
||||
def plane_status_label(task_row) -> str:
|
||||
"""ORCH-067 (Р-1, layer 1): current Plane status label for the card header.
|
||||
|
||||
Pure / deterministic from the task row, NEVER hits the network, NEVER raises.
|
||||
On unknown / broken input -> a safe stage default. ``⏸️ In Review`` and
|
||||
``⏸️ Awaiting Deploy`` are produced here (offline), so both work without a
|
||||
network connection (AC-7, AC-8). Branch statuses that are indistinguishable
|
||||
offline (Needs Input / Blocked / …) are drawn by ``_live_plane_branch_override``.
|
||||
"""
|
||||
try:
|
||||
stage = _row_get(task_row, "stage") or "created"
|
||||
except Exception:
|
||||
return _DEFAULT_STATUS_LABEL
|
||||
try:
|
||||
if stage == "analysis":
|
||||
started = _row_get(task_row, "brd_review_started_at")
|
||||
ended = _row_get(task_row, "brd_review_ended_at")
|
||||
if started and not ended:
|
||||
return _IN_REVIEW_LABEL
|
||||
return _STAGE_STATUS_LABEL.get(stage, _DEFAULT_STATUS_LABEL)
|
||||
except Exception:
|
||||
return _DEFAULT_STATUS_LABEL
|
||||
|
||||
|
||||
# ORCH-067 (Р-3): per-issue TTL cache of the live state uuid -> {issue_id: (ts, uuid)}.
|
||||
_LIVE_STATE_CACHE: dict[str, tuple] = {}
|
||||
|
||||
|
||||
def _live_state_uuid_cached(plane_issue_id, project_id):
|
||||
"""ORCH-067 (Р-3/Р-4): TTL-cached single live-state read for the render path.
|
||||
|
||||
At most one ``fetch_issue_state`` per issue per ``tracker_live_status_ttl_s``
|
||||
with a SHORT timeout. Never raises -> None on any failure.
|
||||
"""
|
||||
try:
|
||||
import time
|
||||
s = _get_settings()
|
||||
ttl = getattr(s, "tracker_live_status_ttl_s", 60)
|
||||
now = time.monotonic()
|
||||
hit = _LIVE_STATE_CACHE.get(plane_issue_id)
|
||||
if hit is not None and (now - hit[0]) <= ttl:
|
||||
return hit[1]
|
||||
from .plane_sync import fetch_issue_state
|
||||
timeout = getattr(s, "tracker_live_status_timeout_s", 3)
|
||||
uuid = fetch_issue_state(plane_issue_id, project_id, timeout=timeout)
|
||||
_LIVE_STATE_CACHE[plane_issue_id] = (now, uuid)
|
||||
return uuid
|
||||
except Exception as e:
|
||||
logger.debug(f"_live_state_uuid_cached({plane_issue_id}) failed: {e}")
|
||||
return None
|
||||
|
||||
|
||||
def _live_plane_branch_override(repo, plane_issue_id, base_label) -> str:
|
||||
"""ORCH-067 (Р-1 layer 2 / Р-2): best-effort live-status overlay.
|
||||
|
||||
Draws the branch statuses that are indistinguishable from ``tasks.stage``
|
||||
offline (Needs Input / Blocked / Rejected / Cancelled / Deploying / Monitoring
|
||||
after Deploy) by reading the LIVE Plane status (short timeout, TTL cache). Any
|
||||
failure / disabled kill-switch / missing data -> ``base_label`` (offline). The
|
||||
pipeline is NEVER blocked. Never raises.
|
||||
"""
|
||||
try:
|
||||
s = _get_settings()
|
||||
if not getattr(s, "tracker_live_status", True):
|
||||
return base_label
|
||||
if not plane_issue_id:
|
||||
return base_label
|
||||
try:
|
||||
from .projects import get_project_by_repo
|
||||
project = get_project_by_repo(repo) if repo else None
|
||||
except Exception:
|
||||
project = None
|
||||
project_id = getattr(project, "plane_project_id", "") if project else ""
|
||||
if not project_id:
|
||||
return base_label
|
||||
live_uuid = _live_state_uuid_cached(plane_issue_id, project_id)
|
||||
if not live_uuid:
|
||||
return base_label
|
||||
from .plane_sync import get_project_states
|
||||
states = get_project_states(project_id)
|
||||
for key, label in _LIVE_BRANCH_LABELS.items():
|
||||
uuid = states.get(key)
|
||||
if not uuid or uuid != live_uuid:
|
||||
continue
|
||||
base_key = _LIVE_BRANCH_BASE.get(key)
|
||||
if base_key and states.get(base_key) == uuid:
|
||||
# deploying/monitoring just alias their base key on this project
|
||||
# (enduro / no dedicated status) -> not a real branch, don't override.
|
||||
continue
|
||||
return label
|
||||
return base_label
|
||||
except Exception as e:
|
||||
logger.debug(f"_live_plane_branch_override failed: {e}")
|
||||
return base_label
|
||||
|
||||
|
||||
def _card_status_label(task_row, repo=None, plane_issue_id=None) -> str:
|
||||
"""ORCH-067: full status label for the card = offline core + live overlay.
|
||||
|
||||
Precedence (Р-1): if the offline core resolved ``⏸️ In Review`` (brd-clock,
|
||||
authoritative) the overlay is NOT consulted; otherwise the overlay may draw a
|
||||
branch status. Never raises (AC-9).
|
||||
"""
|
||||
try:
|
||||
base = plane_status_label(task_row)
|
||||
if base == _IN_REVIEW_LABEL:
|
||||
return base
|
||||
return _live_plane_branch_override(repo, plane_issue_id, base)
|
||||
except Exception:
|
||||
return _DEFAULT_STATUS_LABEL
|
||||
|
||||
|
||||
def notify_approve_requested(task_id: int):
|
||||
"""ALERT (separate, notifying): BRD/TZ/AC ready -> flip Plane to Approved.
|
||||
|
||||
@@ -1001,7 +749,7 @@ def notify_approve_requested(task_id: int):
|
||||
except Exception as e:
|
||||
logger.warning(f"notify_approve_requested: brd clock start failed: {e}")
|
||||
msg = (
|
||||
f"\U0001f4cb {link_for(work_item_id, task_id)}: BRD/\u0422\u0417/AC \u0433\u043e\u0442\u043e\u0432\u044b. "
|
||||
f"\U0001f4cb {html.escape(work_item_id)}: BRD/\u0422\u0417/AC \u0433\u043e\u0442\u043e\u0432\u044b. "
|
||||
f"\u041f\u0435\u0440\u0435\u0432\u0435\u0434\u0438\u0442\u0435 \u0437\u0430\u0434\u0430\u0447\u0443 \u0432 \u0441\u0442\u0430\u0442\u0443\u0441 Approved "
|
||||
f"\u0432 Plane \u0434\u043b\u044f \u043f\u0440\u043e\u0434\u043e\u043b\u0436\u0435\u043d\u0438\u044f."
|
||||
)
|
||||
@@ -1035,14 +783,8 @@ def notify_done(task_id: int):
|
||||
|
||||
|
||||
def notify_error(task_id: int, error: str):
|
||||
"""ALERT (separate, notifying): task error.
|
||||
|
||||
ORCH-067 (req 4): the issue number is a clickable Plane link (fail-safe ->
|
||||
raw number) and the error text is html-escaped so it cannot break the <a>
|
||||
markup under parse_mode=HTML (AC-14).
|
||||
"""
|
||||
"""ALERT (separate, notifying): task error."""
|
||||
work_item_id = _get_work_item_id(task_id) if task_id else "system"
|
||||
num = link_for(work_item_id, task_id) if task_id else html.escape(work_item_id)
|
||||
msg = f"\U0001f534 {num}: ERROR \u2014 {html.escape(str(error))}"
|
||||
msg = f"\U0001f534 {work_item_id}: ERROR \u2014 {error}"
|
||||
logger.error(msg)
|
||||
send_telegram(msg) # separate, notifying
|
||||
|
||||
@@ -402,7 +402,7 @@ def fetch_issue_sequence_id(issue_id: str, project_id: str) -> int | None:
|
||||
return None
|
||||
|
||||
|
||||
def fetch_issue_state(issue_id: str, project_id: str, timeout: int = 10) -> str | None:
|
||||
def fetch_issue_state(issue_id: str, project_id: str) -> str | None:
|
||||
"""ORCH-060 (F-1 Guard 2): GET the Plane issue and return its current state uuid.
|
||||
|
||||
Used by the reconciler to honour an explicit human gate: an issue a person
|
||||
@@ -413,16 +413,12 @@ def fetch_issue_state(issue_id: str, project_id: str, timeout: int = 10) -> str
|
||||
Plane returns ``state`` as a bare uuid string; older shapes may nest it as a
|
||||
``{"id": ...}`` dict — both are handled.
|
||||
|
||||
ORCH-067 (Р-4): ``timeout`` is optional (default 10s — unchanged for the
|
||||
reconciler) so the tracker live-overlay can read with a SHORT timeout
|
||||
(settings.tracker_live_status_timeout_s) on the synchronous render path.
|
||||
|
||||
Returns None on network error, non-2xx, or a missing field — never raises, so
|
||||
the caller can apply its conservative fallback (treat as "possibly blocked").
|
||||
"""
|
||||
url = f"{PLANE_BASE}/workspaces/{WORKSPACE}/projects/{project_id}/issues/{issue_id}/"
|
||||
try:
|
||||
resp = httpx.get(url, headers=PLANE_HEADERS, timeout=timeout)
|
||||
resp = httpx.get(url, headers=PLANE_HEADERS, timeout=10)
|
||||
resp.raise_for_status()
|
||||
state = resp.json().get("state")
|
||||
if isinstance(state, dict):
|
||||
|
||||
@@ -67,7 +67,7 @@ from .plane_sync import (
|
||||
list_issues_by_state,
|
||||
)
|
||||
from .webhooks.plane import handle_status_start, handle_verdict
|
||||
from .notifications import send_telegram, link_for
|
||||
from .notifications import send_telegram
|
||||
from . import projects
|
||||
|
||||
logger = logging.getLogger("orchestrator.reconciler")
|
||||
@@ -447,7 +447,7 @@ class Reconciler:
|
||||
if settings.reconcile_notify_unblock:
|
||||
try:
|
||||
send_telegram(
|
||||
f"\U0001f527 reconciler: {link_for(work_item_id)} {stage} "
|
||||
f"\U0001f527 reconciler: {work_item_id} {stage} "
|
||||
f"разблокирована (потерян webhook)"
|
||||
)
|
||||
except Exception as e: # noqa: BLE001 - never break the tick
|
||||
|
||||
@@ -670,9 +670,9 @@ def check_security_gate(repo: str, work_item_id: str, branch: str) -> tuple[bool
|
||||
dep_result.detail,
|
||||
)
|
||||
try:
|
||||
from .notifications import send_telegram, link_for
|
||||
from .notifications import send_telegram
|
||||
send_telegram(
|
||||
f"⚠️ {link_for(work_item_id)}: dep-audit недоступен фид CVE "
|
||||
f"⚠️ {work_item_id}: dep-audit недоступен фид CVE "
|
||||
f"({dep_result.detail}). "
|
||||
+ ("Гейт fail-closed → FAIL." if settings.security_dep_audit_fail_closed
|
||||
else "Гейт fail-open → warning (секреты проверены оффлайн).")
|
||||
|
||||
@@ -44,7 +44,6 @@ from .notifications import (
|
||||
notify_qg_failure,
|
||||
notify_approve_requested,
|
||||
send_telegram,
|
||||
link_for,
|
||||
)
|
||||
from .plane_sync import (
|
||||
notify_stage_change as plane_notify_stage,
|
||||
@@ -612,7 +611,7 @@ def _handle_analysis_approved_flow(
|
||||
author="analyst",
|
||||
)
|
||||
send_telegram(
|
||||
f"\u2753 {link_for(work_item_id)}: Analyst \u0437\u0430\u0434\u0430\u0451\u0442 \u0432\u043e\u043f\u0440\u043e\u0441\u044b. \u041e\u0442\u0432\u0435\u0442\u044c \u0432 Plane."
|
||||
f"\u2753 {work_item_id}: Analyst \u0437\u0430\u0434\u0430\u0451\u0442 \u0432\u043e\u043f\u0440\u043e\u0441\u044b. \u041e\u0442\u0432\u0435\u0442\u044c \u0432 Plane."
|
||||
)
|
||||
result.note = "analysis-needs-input"
|
||||
return
|
||||
@@ -671,7 +670,7 @@ def _handle_qg_failure_rollbacks(
|
||||
)
|
||||
else:
|
||||
send_telegram(
|
||||
f"\u26a0\ufe0f {link_for(work_item_id)}: Max developer retries (3) reached. "
|
||||
f"\u26a0\ufe0f {work_item_id}: Max developer retries (3) reached. "
|
||||
f"Manual intervention needed."
|
||||
)
|
||||
result.alerted = True
|
||||
@@ -718,7 +717,7 @@ def _handle_qg_failure_rollbacks(
|
||||
else:
|
||||
set_issue_blocked(work_item_id)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: Tests still failing after 3 developer "
|
||||
f"\U0001f6a8 {work_item_id}: Tests still failing after 3 developer "
|
||||
f"retries. Manual intervention needed."
|
||||
)
|
||||
result.alerted = True
|
||||
@@ -775,7 +774,7 @@ def _handle_qg_failure_rollbacks(
|
||||
author="deployer",
|
||||
)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: Staging FAILED ({reason}). "
|
||||
f"\U0001f6a8 {work_item_id}: Staging FAILED ({reason}). "
|
||||
f"Rolled back to development. Needs fix."
|
||||
)
|
||||
result.alerted = True
|
||||
@@ -819,7 +818,7 @@ def _handle_qg_failure_rollbacks(
|
||||
author="deployer",
|
||||
)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: Deploy FAILED ({reason}). "
|
||||
f"\U0001f6a8 {work_item_id}: Deploy FAILED ({reason}). "
|
||||
f"Rolled back to development. Needs fix."
|
||||
)
|
||||
result.alerted = True
|
||||
@@ -915,7 +914,7 @@ def _handle_merge_gate_defer(
|
||||
else:
|
||||
set_issue_blocked(work_item_id)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: merge-gate defer limit "
|
||||
f"\U0001f6a8 {work_item_id}: merge-gate defer limit "
|
||||
f"({settings.merge_defer_max_attempts}) reached (merge-lock busy). "
|
||||
f"Manual intervention needed."
|
||||
)
|
||||
@@ -970,7 +969,7 @@ def _handle_merge_gate_rollback(
|
||||
else:
|
||||
set_issue_blocked(work_item_id)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: Merge-gate still failing after "
|
||||
f"\U0001f6a8 {work_item_id}: Merge-gate still failing after "
|
||||
f"{MAX_DEVELOPER_RETRIES} developer retries ({reason}). "
|
||||
f"Manual intervention needed."
|
||||
)
|
||||
@@ -1056,7 +1055,7 @@ def _handle_security_gate(
|
||||
else:
|
||||
set_issue_blocked(work_item_id)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: Security-гейт still failing after "
|
||||
f"\U0001f6a8 {work_item_id}: Security-гейт still failing after "
|
||||
f"{MAX_DEVELOPER_RETRIES} developer retries ({reason}). "
|
||||
f"Manual intervention needed."
|
||||
)
|
||||
@@ -1133,7 +1132,7 @@ def _handle_image_freshness(
|
||||
else:
|
||||
set_issue_blocked(work_item_id)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: Staging image freshness still failing after "
|
||||
f"\U0001f6a8 {work_item_id}: Staging image freshness still failing after "
|
||||
f"{MAX_DEVELOPER_RETRIES} developer retries ({reason}). "
|
||||
f"Manual intervention needed."
|
||||
)
|
||||
@@ -1191,7 +1190,7 @@ def _handle_self_deploy_phase_a(
|
||||
author="deployer",
|
||||
)
|
||||
send_telegram(
|
||||
f"\U0001f7e1 {link_for(work_item_id)}: staging OK. Ждёт подтверждения ПРОД-деплоя "
|
||||
f"\U0001f7e1 {work_item_id}: staging OK. Ждёт подтверждения ПРОД-деплоя "
|
||||
f"(смените статус на «Confirm Deploy»)."
|
||||
)
|
||||
logger.info(
|
||||
@@ -1226,7 +1225,7 @@ def _handle_self_deploy_phase_b(task_id, repo, work_item_id, branch, result: Adv
|
||||
"Повторите approve после устранения причины.",
|
||||
author="deployer",
|
||||
)
|
||||
send_telegram(f"⚠️ {link_for(work_item_id)}: прод-деплой не запустился: {msg}")
|
||||
send_telegram(f"⚠️ {work_item_id}: прод-деплой не запустился: {msg}")
|
||||
logger.error(f"Task {task_id}: self-deploy initiate failed: {msg}")
|
||||
return
|
||||
|
||||
@@ -1255,7 +1254,7 @@ def _handle_self_deploy_phase_b(task_id, repo, work_item_id, branch, result: Adv
|
||||
"Вердикт будет зафиксирован после health-check.",
|
||||
author="deployer",
|
||||
)
|
||||
send_telegram(f"\U0001f680 {link_for(work_item_id)}: прод-деплой стартовал. Жду результат.")
|
||||
send_telegram(f"\U0001f680 {work_item_id}: прод-деплой стартовал. Жду результат.")
|
||||
logger.info(
|
||||
f"Task {task_id}: self-deploy Phase B — detached deploy initiated, "
|
||||
f"finalizer enqueued (job_id={new_job})"
|
||||
@@ -1366,7 +1365,7 @@ def _handle_merge_verify(task_id, repo, work_item_id, branch, result: AdvanceRes
|
||||
try:
|
||||
merge_gate.note_not_merged_alert(work_item_id)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: ошибка merge-verify ({e}). "
|
||||
f"\U0001f6a8 {work_item_id}: ошибка merge-verify ({e}). "
|
||||
f"Задача удержана на `deploy` (НЕ done)."
|
||||
)
|
||||
except Exception: # noqa: BLE001 - best-effort alert
|
||||
@@ -1424,7 +1423,7 @@ def run_deploy_finalizer(job: dict):
|
||||
if work_item_id:
|
||||
set_issue_blocked(work_item_id)
|
||||
send_telegram(
|
||||
f"\U0001f6a8 {link_for(work_item_id)}: deploy result не появился после "
|
||||
f"\U0001f6a8 {work_item_id}: deploy result не появился после "
|
||||
f"{settings.deploy_finalize_max_attempts} попыток. Нужно ручное вмешательство."
|
||||
)
|
||||
logger.error(
|
||||
@@ -1445,7 +1444,7 @@ def run_deploy_finalizer(job: dict):
|
||||
f"✅ Прод-деплой успешен (health-check OK, exit {code}).",
|
||||
author="deployer",
|
||||
)
|
||||
send_telegram(f"✅ {link_for(work_item_id)}: прод-деплой успешен (exit {code}).")
|
||||
send_telegram(f"✅ {work_item_id}: прод-деплой успешен (exit {code}).")
|
||||
|
||||
# Drive the EXISTING deploy contracts via the gate verdict we just wrote.
|
||||
advance_stage(
|
||||
|
||||
@@ -8,17 +8,9 @@ builds a FRESH Settings() (the process-wide singleton is not mutated).
|
||||
from src.config import Settings
|
||||
|
||||
|
||||
def test_tracker_mode_defaults_to_bump(monkeypatch):
|
||||
# ORCH-067 (TC-01 / AC-1): the default flipped edit -> bump. With no env var
|
||||
# the card now re-creates at the bottom of the chat out of the box; edit
|
||||
# stays available via ORCH_TRACKER_MODE=edit (see test below).
|
||||
def test_tracker_mode_defaults_to_edit(monkeypatch):
|
||||
# No env var -> default "edit" (TC-01 / AC-1).
|
||||
monkeypatch.delenv("ORCH_TRACKER_MODE", raising=False)
|
||||
assert Settings().tracker_mode == "bump"
|
||||
|
||||
|
||||
def test_tracker_mode_reads_env_edit(monkeypatch):
|
||||
# ORCH-067 (AC-4): edit mode is still available through the env var.
|
||||
monkeypatch.setenv("ORCH_TRACKER_MODE", "edit")
|
||||
assert Settings().tracker_mode == "edit"
|
||||
|
||||
|
||||
|
||||
@@ -1,206 +0,0 @@
|
||||
"""ORCH-067 — Group D: clickable issue number in ALL alerts (AC-13, AC-12).
|
||||
|
||||
Every orchestrator alert that mentions a work_item_id now renders it as a Plane
|
||||
hyperlink via the shared ``link_for`` / ``plane_issue_link`` helpers, and degrades
|
||||
fail-safe to the raw (escaped) number when data is missing. This covers the
|
||||
dedicated notify_* helpers (notify_approve_requested, notify_error) and asserts
|
||||
the engine/launcher/security_gate/reconciler alert sites are wired to ``link_for``
|
||||
— the single DB-resolving helper those sites call. Network is isolated:
|
||||
send_telegram is replaced with a recorder; the DB is a temp SQLite.
|
||||
|
||||
Test ids TC-13, TC-14, TC-15 from 04-test-plan.yaml.
|
||||
"""
|
||||
|
||||
import os
|
||||
import tempfile
|
||||
|
||||
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
|
||||
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
|
||||
|
||||
_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_notify_links.db")
|
||||
os.environ["ORCH_DB_PATH"] = _test_db
|
||||
|
||||
from types import SimpleNamespace # noqa: E402
|
||||
|
||||
import pytest # noqa: E402
|
||||
|
||||
import src.db as db_module # noqa: E402
|
||||
import src.projects as projects_mod # noqa: E402
|
||||
from src.db import init_db, get_db # noqa: E402
|
||||
from src import notifications as N # noqa: E402
|
||||
|
||||
_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def setup_db(monkeypatch):
|
||||
monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
init_db()
|
||||
# Pin repo->project resolution so cross-file registry reloads can't strip
|
||||
# 'orchestrator' and break the expected issue URL.
|
||||
monkeypatch.setattr(
|
||||
projects_mod, "get_project_by_repo",
|
||||
lambda repo: (SimpleNamespace(plane_project_id=_ORCH_PROJECT_ID)
|
||||
if repo == "orchestrator" else None),
|
||||
)
|
||||
yield
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
|
||||
|
||||
def _set(monkeypatch, **kw):
|
||||
s = N._get_settings()
|
||||
for k, v in kw.items():
|
||||
monkeypatch.setattr(s, k, v, raising=False)
|
||||
|
||||
|
||||
def _mk_task(wid="ORCH-067", repo="orchestrator", title="notify links",
|
||||
plane_issue_id="iss-1", stage="development"):
|
||||
conn = get_db()
|
||||
cur = conn.execute(
|
||||
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, "
|
||||
"plane_issue_id) VALUES (?, ?, ?, ?, ?, ?, ?)",
|
||||
("p1", wid, repo, "feature/ORCH-067-x", stage, title, plane_issue_id),
|
||||
)
|
||||
tid = cur.lastrowid
|
||||
conn.commit()
|
||||
conn.close()
|
||||
return tid
|
||||
|
||||
|
||||
def _record_send(monkeypatch):
|
||||
calls = []
|
||||
|
||||
def _fake(text, disable_notification=False):
|
||||
calls.append({"text": text, "silent": disable_notification})
|
||||
return 1
|
||||
|
||||
monkeypatch.setattr(N, "send_telegram", _fake)
|
||||
monkeypatch.setattr(N, "update_task_tracker", lambda task_id: None)
|
||||
return calls
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-13 / AC-13 — notify_approve_requested: number clickable, CTA + single ping
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc13_approve_requested_number_clickable(monkeypatch):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme", gitea_public_url="https://git.example.org",
|
||||
gitea_owner="orchteam")
|
||||
tid = _mk_task(plane_issue_id="iss-1")
|
||||
calls = _record_send(monkeypatch)
|
||||
|
||||
N.notify_approve_requested(tid)
|
||||
|
||||
assert len(calls) == 1 # exactly one notifying ping
|
||||
assert calls[0]["silent"] is not True
|
||||
text = calls[0]["text"]
|
||||
expected = (
|
||||
f"https://plane.example.org/acme/projects/{_ORCH_PROJECT_ID}"
|
||||
f"/issues/iss-1/"
|
||||
)
|
||||
assert f'<a href="{expected}">ORCH-067</a>' in text # clickable number
|
||||
assert "Approved" in text # call-to-action preserved
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-14 / AC-13, AC-12 — notify_error: clickable when data present, else raw
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc14_notify_error_clickable(monkeypatch):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
tid = _mk_task(plane_issue_id="iss-1")
|
||||
calls = _record_send(monkeypatch)
|
||||
|
||||
N.notify_error(tid, "boom happened")
|
||||
|
||||
assert len(calls) == 1
|
||||
text = calls[0]["text"]
|
||||
assert ">ORCH-067</a>" in text # number is a link
|
||||
assert "ERROR" in text and "boom happened" in text
|
||||
|
||||
|
||||
def test_tc14_notify_error_degrades_raw_number(monkeypatch):
|
||||
# No usable Plane base -> raw (unlinked) number, alert still sent, no crash.
|
||||
_set(monkeypatch, plane_web_url="", plane_api_url="")
|
||||
tid = _mk_task(plane_issue_id="iss-1")
|
||||
calls = _record_send(monkeypatch)
|
||||
|
||||
N.notify_error(tid, "boom")
|
||||
|
||||
text = calls[0]["text"]
|
||||
assert "ORCH-067" in text
|
||||
assert "<a href=" not in text
|
||||
|
||||
|
||||
def test_tc14_notify_error_escapes_error_text(monkeypatch):
|
||||
# The error string is html-escaped so it can't break the <a>/HTML markup.
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
tid = _mk_task(plane_issue_id="iss-1")
|
||||
calls = _record_send(monkeypatch)
|
||||
|
||||
N.notify_error(tid, "<script> & </script>")
|
||||
|
||||
text = calls[0]["text"]
|
||||
assert "<script>" not in text
|
||||
assert "<script>" in text and "&" in text
|
||||
# The clickable number's anchor is still well-formed.
|
||||
assert text.count("<a href=") == text.count("</a>")
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-15 / AC-13 — link_for is the DB-resolving helper the alert sites call
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc15_link_for_by_work_item_id(monkeypatch):
|
||||
# Sites holding only a work_item_id (launcher deploy-fail, security_gate,
|
||||
# reconciler, engine QG-fail) call link_for(wid) -> resolves repo + issue id
|
||||
# from the DB and returns a clickable number.
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
_mk_task(wid="ORCH-067", plane_issue_id="iss-1")
|
||||
|
||||
out = N.link_for("ORCH-067")
|
||||
expected = (
|
||||
f"https://plane.example.org/acme/projects/{_ORCH_PROJECT_ID}"
|
||||
f"/issues/iss-1/"
|
||||
)
|
||||
assert out == f'<a href="{expected}">ORCH-067</a>'
|
||||
|
||||
|
||||
def test_tc15_link_for_by_task_id(monkeypatch):
|
||||
# Sites holding a task_id (launcher agent-fail, engine) call link_for(wid, tid).
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
tid = _mk_task(wid="ORCH-067", plane_issue_id="iss-7")
|
||||
|
||||
out = N.link_for("ORCH-067", tid)
|
||||
assert ">ORCH-067</a>" in out and "/issues/iss-7/" in out
|
||||
|
||||
|
||||
def test_tc15_link_for_unknown_task_degrades(monkeypatch):
|
||||
# No matching DB row -> raw number, never raises.
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
out = N.link_for("ORCH-999")
|
||||
assert out == "ORCH-999"
|
||||
assert "<a href=" not in out
|
||||
|
||||
|
||||
@pytest.mark.parametrize("module_name", [
|
||||
"src.stage_engine",
|
||||
"src.agents.launcher",
|
||||
"src.security_gate",
|
||||
"src.reconciler",
|
||||
])
|
||||
def test_tc15_alert_modules_wire_link_for(module_name):
|
||||
"""The representative alert modules call the shared link_for helper, so their
|
||||
work_item_id alerts render a clickable number (not a bare string). Checked at
|
||||
source level since some sites import link_for function-locally."""
|
||||
import importlib
|
||||
import inspect
|
||||
mod = importlib.import_module(module_name)
|
||||
src = inspect.getsource(mod)
|
||||
assert "link_for(" in src, f"{module_name} must use link_for in its alerts"
|
||||
@@ -1,101 +0,0 @@
|
||||
"""ORCH-067 — Group D: the shared plane_issue_link helper (AC-12).
|
||||
|
||||
``plane_issue_link(work_item_id, plane_issue_id=None, project_id=None, repo=None)``
|
||||
is the single source of the clickable issue number for cards AND alerts. It
|
||||
returns ``<a href=...>ORCH-NNN</a>`` when a usable Plane browser URL can be built,
|
||||
and ``html.escape(work_item_id)`` otherwise. It must NEVER raise — including on
|
||||
None arguments and a loopback base. No DB and no network are touched by this unit
|
||||
(project_id is passed explicitly here), so these are pure settings-driven cases.
|
||||
|
||||
Test id TC-12 from 04-test-plan.yaml.
|
||||
"""
|
||||
|
||||
import os
|
||||
|
||||
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
|
||||
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
|
||||
|
||||
import pytest # noqa: E402
|
||||
|
||||
from src import notifications as N # noqa: E402
|
||||
|
||||
|
||||
def _set(monkeypatch, **kw):
|
||||
s = N._get_settings()
|
||||
for k, v in kw.items():
|
||||
monkeypatch.setattr(s, k, v, raising=False)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-12 / AC-12 — full data -> HTML link wrapping the number
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc12_full_data_returns_anchor(monkeypatch):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
out = N.plane_issue_link("ORCH-067", plane_issue_id="iss-1",
|
||||
project_id="proj-9")
|
||||
expected = "https://plane.example.org/acme/projects/proj-9/issues/iss-1/"
|
||||
assert out == f'<a href="{expected}">ORCH-067</a>'
|
||||
|
||||
|
||||
def test_tc12_web_url_fallbacks_to_api_url(monkeypatch):
|
||||
# plane_web_url empty -> non-loopback plane_api_url is used as the base.
|
||||
_set(monkeypatch, plane_web_url="",
|
||||
plane_api_url="https://plane-fallback.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
out = N.plane_issue_link("ORCH-067", plane_issue_id="iss-1",
|
||||
project_id="proj-9")
|
||||
assert 'href="https://plane-fallback.example.org/acme/' in out
|
||||
assert ">ORCH-067</a>" in out
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-12 / AC-12 — insufficient data -> escaped number, NEVER an anchor
|
||||
# --------------------------------------------------------------------------- #
|
||||
@pytest.mark.parametrize("settings_kw,call_kw,reason", [
|
||||
({"plane_web_url": "", "plane_api_url": ""},
|
||||
{"plane_issue_id": "iss-1", "project_id": "proj-9"}, "no web base"),
|
||||
({"plane_web_url": "http://localhost:8091", "plane_api_url": ""},
|
||||
{"plane_issue_id": "iss-1", "project_id": "proj-9"}, "loopback base"),
|
||||
({"plane_web_url": "https://plane.example.org", "plane_workspace_slug": ""},
|
||||
{"plane_issue_id": "iss-1", "project_id": "proj-9"}, "no workspace"),
|
||||
({"plane_web_url": "https://plane.example.org", "plane_workspace_slug": "acme"},
|
||||
{"plane_issue_id": None, "project_id": "proj-9"}, "no issue id"),
|
||||
({"plane_web_url": "https://plane.example.org", "plane_workspace_slug": "acme"},
|
||||
{"plane_issue_id": "iss-1", "project_id": ""}, "no project id"),
|
||||
])
|
||||
def test_tc12_insufficient_data_returns_plain_number(monkeypatch, settings_kw,
|
||||
call_kw, reason):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_api_url="http://localhost:8091", plane_workspace_slug="acme")
|
||||
_set(monkeypatch, **settings_kw)
|
||||
out = N.plane_issue_link("ORCH-067", repo=None, **call_kw)
|
||||
assert out == "ORCH-067", reason
|
||||
assert "<a href=" not in out
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-12 / AC-12 — html-escaping + never raises on hostile / None input
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc12_escapes_work_item_id_in_link(monkeypatch):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
out = N.plane_issue_link("ORCH&<67>", plane_issue_id="iss-1",
|
||||
project_id="proj-9")
|
||||
assert ">ORCH&<67></a>" in out # label escaped inside the anchor
|
||||
assert "<a href=" in out
|
||||
|
||||
|
||||
def test_tc12_escapes_work_item_id_unlinked(monkeypatch):
|
||||
_set(monkeypatch, plane_web_url="", plane_api_url="")
|
||||
out = N.plane_issue_link("ORCH&<67>", plane_issue_id="iss-1",
|
||||
project_id="proj-9")
|
||||
assert out == "ORCH&<67>" # escaped, no anchor
|
||||
|
||||
|
||||
def test_tc12_none_args_never_raise(monkeypatch):
|
||||
# All-None must not raise and must yield a (possibly empty) string.
|
||||
out = N.plane_issue_link(None)
|
||||
assert isinstance(out, str)
|
||||
# None work_item_id -> empty label, no anchor.
|
||||
assert "<a href=" not in out
|
||||
@@ -241,9 +241,6 @@ def test_first_call_sends_message_and_stores_id(monkeypatch):
|
||||
|
||||
|
||||
def test_second_call_edits_existing_message(monkeypatch):
|
||||
# ORCH-067: the default flipped to bump; this case asserts the edit-mode
|
||||
# contract, so pin edit mode explicitly.
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_mode", "edit", raising=False)
|
||||
tid = _mk_task(stage="development")
|
||||
_mk_run(tid, "analyst", "2026-06-04 09:00:00", "2026-06-04 09:10:00",
|
||||
in_tok=10, out_tok=5, cost=0.1)
|
||||
@@ -605,15 +602,9 @@ def test_render_stage_labels_are_russian():
|
||||
for ru in ("Анализ", "Архитектура", "Разработка", "Код ревью",
|
||||
"Тестирование", "Внедрение"):
|
||||
assert ru in text, f"missing russian label {ru!r}"
|
||||
# ORCH-067: the new '📍 <Plane-status>' line intentionally carries the ENGLISH
|
||||
# ORCH-066 Plane status name (e.g. 'Awaiting Deploy'); the russian-only rule
|
||||
# (BR-11) applies to the STAGE label lines, so exclude the status line here.
|
||||
stage_lines = "\n".join(
|
||||
ln for ln in text.splitlines() if not ln.startswith("\U0001f4cd")
|
||||
)
|
||||
for en in ("Analysis", "Architecture", "Development", "Review",
|
||||
"Testing", "Deploy"):
|
||||
assert en not in stage_lines, f"english label leaked: {en!r}"
|
||||
assert en not in text, f"english label leaked: {en!r}"
|
||||
|
||||
|
||||
def test_render_done_says_vnedreno_not_deployed():
|
||||
|
||||
@@ -1,159 +0,0 @@
|
||||
"""ORCH-067 — Group A: bump is the DEFAULT tracker mode (AC-1..AC-4, AC-15).
|
||||
|
||||
The default flipped edit -> bump: out of the box the live card is re-created at
|
||||
the BOTTOM of the chat (delete old + send new silent + repoint id), one card per
|
||||
task. edit stays available via ORCH_TRACKER_MODE=edit. Network is isolated: the
|
||||
low-level send/edit/delete helpers are patched per case; the DB is a temp SQLite.
|
||||
|
||||
Test ids TC-01..TC-04 + TC-17 from 04-test-plan.yaml.
|
||||
"""
|
||||
|
||||
import os
|
||||
import tempfile
|
||||
|
||||
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
|
||||
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
|
||||
|
||||
_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_bump_default.db")
|
||||
os.environ["ORCH_DB_PATH"] = _test_db
|
||||
|
||||
import pytest # noqa: E402
|
||||
|
||||
import src.db as db_module # noqa: E402
|
||||
from src.config import Settings # noqa: E402
|
||||
from src.db import ( # noqa: E402
|
||||
init_db, get_db, get_tracker_message_id, set_tracker_message_id,
|
||||
)
|
||||
from src import notifications as N # noqa: E402
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def setup_db(monkeypatch):
|
||||
monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
init_db()
|
||||
yield
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
|
||||
|
||||
def _mk_task(stage="development", wid="ORCH-067"):
|
||||
conn = get_db()
|
||||
cur = conn.execute(
|
||||
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title) "
|
||||
"VALUES (?, ?, ?, ?, ?, ?)",
|
||||
("p1", wid, "orchestrator", "feature/ORCH-067-x", stage, "bump default"),
|
||||
)
|
||||
tid = cur.lastrowid
|
||||
conn.commit()
|
||||
conn.close()
|
||||
return tid
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-01 / AC-1 — default tracker_mode == "bump"
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc01_default_tracker_mode_is_bump(monkeypatch):
|
||||
monkeypatch.delenv("ORCH_TRACKER_MODE", raising=False)
|
||||
assert Settings().tracker_mode == "bump"
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-02 / AC-2, AC-15 — repeat update: delete(old) -> send(silent) -> repoint
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc02_repeat_delete_send_silent_repoint(monkeypatch):
|
||||
# No env -> resolves to the new bump default (no explicit mode pin).
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_mode", "bump", raising=False)
|
||||
tid = _mk_task()
|
||||
set_tracker_message_id(tid, 100)
|
||||
|
||||
order = []
|
||||
monkeypatch.setattr(N, "delete_telegram",
|
||||
lambda mid: order.append(("delete", mid)) or True)
|
||||
monkeypatch.setattr(N, "send_telegram",
|
||||
lambda text, disable_notification=False:
|
||||
order.append(("send", disable_notification)) or 200)
|
||||
|
||||
N.update_task_tracker(tid)
|
||||
|
||||
# delete(old) strictly before send; the new card is SILENT (disable=True).
|
||||
assert order == [("delete", 100), ("send", True)]
|
||||
assert get_tracker_message_id(tid) == 200 # one card -> repointed
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-03 / AC-3 — transient send None must NOT wipe the pointer / duplicate
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc03_send_none_keeps_pointer_no_dupe(monkeypatch):
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_mode", "bump", raising=False)
|
||||
tid = _mk_task()
|
||||
set_tracker_message_id(tid, 100)
|
||||
|
||||
sends = []
|
||||
monkeypatch.setattr(N, "delete_telegram", lambda mid: True)
|
||||
monkeypatch.setattr(N, "send_telegram",
|
||||
lambda text, disable_notification=False:
|
||||
sends.append(1) or None)
|
||||
|
||||
N.update_task_tracker(tid) # must not raise
|
||||
|
||||
assert len(sends) == 1 # exactly one (failed) attempt, no retry
|
||||
assert get_tracker_message_id(tid) == 100 # pointer preserved, not None
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-04 / AC-4 — edit mode still reachable via env -> editMessageText path
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc04_edit_mode_still_available(monkeypatch):
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_mode", "edit", raising=False)
|
||||
tid = _mk_task()
|
||||
set_tracker_message_id(tid, 777)
|
||||
|
||||
edited = {}
|
||||
monkeypatch.setattr(N, "edit_telegram",
|
||||
lambda mid, text: edited.update(mid=mid) or N.EDIT_OK)
|
||||
monkeypatch.setattr(
|
||||
N, "send_telegram",
|
||||
lambda *a, **k: (_ for _ in ()).throw(
|
||||
AssertionError("edit mode must not send when edit succeeds")),
|
||||
)
|
||||
|
||||
N.update_task_tracker(tid)
|
||||
assert edited["mid"] == 777 # edited in place, no new card
|
||||
|
||||
|
||||
def test_tc04b_edit_mode_resolution_case_insensitive(monkeypatch):
|
||||
"""Anything other than 'bump' resolves to edit (e.g. 'EDIT')."""
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_mode", "EDIT", raising=False)
|
||||
tid = _mk_task()
|
||||
set_tracker_message_id(tid, 5)
|
||||
edited = {}
|
||||
monkeypatch.setattr(N, "edit_telegram",
|
||||
lambda mid, text: edited.update(mid=mid) or N.EDIT_OK)
|
||||
monkeypatch.setattr(N, "send_telegram",
|
||||
lambda *a, **k: (_ for _ in ()).throw(
|
||||
AssertionError("should edit, not send")))
|
||||
N.update_task_tracker(tid)
|
||||
assert edited["mid"] == 5
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-17 / AC-15 — first bump call: NO delete, silent send, id stored
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc17_first_call_silent_no_delete(monkeypatch):
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_mode", "bump", raising=False)
|
||||
tid = _mk_task(stage="analysis")
|
||||
|
||||
sends = []
|
||||
monkeypatch.setattr(N, "send_telegram",
|
||||
lambda text, disable_notification=False:
|
||||
sends.append(disable_notification) or 555)
|
||||
monkeypatch.setattr(N, "delete_telegram",
|
||||
lambda mid: (_ for _ in ()).throw(
|
||||
AssertionError("delete must not run on first call")))
|
||||
|
||||
N.update_task_tracker(tid)
|
||||
|
||||
assert sends == [True] # exactly one SILENT send
|
||||
assert get_tracker_message_id(tid) == 555 # id stored
|
||||
@@ -1,158 +0,0 @@
|
||||
"""ORCH-067 — Group C: clickable issue number in the live card (AC-10/AC-11/AC-14).
|
||||
|
||||
The issue number in the card header is now a Plane hyperlink
|
||||
(``<a href=".../issues/<id>/">ORCH-NNN</a>``) when a usable browser URL can be
|
||||
built, and degrades fail-safe to the html-escaped raw number when any piece is
|
||||
missing (web base / non-loopback / workspace / project_id / plane_issue_id). The
|
||||
card must NEVER break under parse_mode=HTML: a title with '<'/'&'/'>' stays
|
||||
escaped while the <a> markup stays valid. Network is isolated (no HTTP from the
|
||||
render path here); the DB is a temp SQLite.
|
||||
|
||||
Test ids TC-10, TC-11, TC-16 from 04-test-plan.yaml.
|
||||
"""
|
||||
|
||||
import os
|
||||
import tempfile
|
||||
|
||||
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
|
||||
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
|
||||
|
||||
_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_card_link.db")
|
||||
os.environ["ORCH_DB_PATH"] = _test_db
|
||||
|
||||
from types import SimpleNamespace # noqa: E402
|
||||
|
||||
import pytest # noqa: E402
|
||||
|
||||
import src.db as db_module # noqa: E402
|
||||
import src.projects as projects_mod # noqa: E402
|
||||
from src.db import init_db, get_db # noqa: E402
|
||||
from src import notifications as N # noqa: E402
|
||||
|
||||
# orchestrator repo -> default project registry uuid (src/projects.py).
|
||||
_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def setup_db(monkeypatch):
|
||||
monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
init_db()
|
||||
# Keep the render path fully offline (no live overlay HTTP).
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_live_status", False,
|
||||
raising=False)
|
||||
# Pin the repo->project resolution so cross-file tests that reload the
|
||||
# ORCH_PROJECTS_JSON registry can't strip 'orchestrator' out from under us.
|
||||
monkeypatch.setattr(
|
||||
projects_mod, "get_project_by_repo",
|
||||
lambda repo: (SimpleNamespace(plane_project_id=_ORCH_PROJECT_ID)
|
||||
if repo == "orchestrator" else None),
|
||||
)
|
||||
yield
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
|
||||
|
||||
def _set(monkeypatch, **kw):
|
||||
s = N._get_settings()
|
||||
for k, v in kw.items():
|
||||
monkeypatch.setattr(s, k, v, raising=False)
|
||||
|
||||
|
||||
def _mk_task(wid="ORCH-067", repo="orchestrator", title="card link",
|
||||
plane_issue_id="issue-uuid-1", stage="development"):
|
||||
conn = get_db()
|
||||
cur = conn.execute(
|
||||
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, "
|
||||
"plane_issue_id) VALUES (?, ?, ?, ?, ?, ?, ?)",
|
||||
("p1", wid, repo, "feature/ORCH-067-x", stage, title, plane_issue_id),
|
||||
)
|
||||
tid = cur.lastrowid
|
||||
conn.commit()
|
||||
conn.close()
|
||||
return tid
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-10 / AC-10 — full data -> clickable <a> wrapping the issue number
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc10_card_number_is_clickable(monkeypatch):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_api_url="http://localhost:8091", plane_workspace_slug="acme")
|
||||
tid = _mk_task(plane_issue_id="abcd-issue-uuid")
|
||||
|
||||
text = N.render_task_tracker(tid)
|
||||
expected_url = (
|
||||
f"https://plane.example.org/acme/projects/{_ORCH_PROJECT_ID}"
|
||||
f"/issues/abcd-issue-uuid/"
|
||||
)
|
||||
assert f'<a href="{expected_url}">ORCH-067</a>' in text
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-11 / AC-11 — fail-safe: any missing piece -> escaped number, no <a>, no crash
|
||||
# --------------------------------------------------------------------------- #
|
||||
@pytest.mark.parametrize("override,reason", [
|
||||
({"plane_web_url": "", "plane_api_url": ""}, "no web base"),
|
||||
({"plane_web_url": "http://localhost:8091", "plane_api_url": ""}, "loopback base"),
|
||||
({"plane_workspace_slug": ""}, "no workspace"),
|
||||
])
|
||||
def test_tc11_card_number_degrades_settings(monkeypatch, override, reason):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_api_url="http://localhost:8091", plane_workspace_slug="acme")
|
||||
_set(monkeypatch, **override)
|
||||
tid = _mk_task(plane_issue_id="abcd-issue-uuid")
|
||||
|
||||
text = N.render_task_tracker(tid)
|
||||
assert "ORCH-067" in text # raw number still shown
|
||||
assert "<a href=" not in text, reason # but NOT a link
|
||||
assert "localhost" not in text # never leak a loopback URL
|
||||
|
||||
|
||||
def test_tc11_card_number_degrades_no_issue_id(monkeypatch):
|
||||
# Missing plane_issue_id -> the number is shown unlinked, render survives.
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
tid = _mk_task(plane_issue_id=None)
|
||||
text = N.render_task_tracker(tid)
|
||||
assert "ORCH-067" in text
|
||||
assert "<a href=" not in text
|
||||
|
||||
|
||||
def test_tc11_card_number_degrades_unknown_repo(monkeypatch):
|
||||
# repo not in the registry -> no project_id -> number unlinked, no crash.
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
tid = _mk_task(repo="not-a-real-repo", plane_issue_id="abcd-issue-uuid")
|
||||
text = N.render_task_tracker(tid)
|
||||
assert "ORCH-067" in text
|
||||
assert "<a href=" not in text
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-16 / AC-14 — HTML escaping: title with '<b>'/'&'/'>' stays safe + valid <a>
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc16_title_escaped_link_valid(monkeypatch):
|
||||
_set(monkeypatch, plane_web_url="https://plane.example.org",
|
||||
plane_workspace_slug="acme")
|
||||
tid = _mk_task(title="<b>drop & </b> table >", plane_issue_id="iss-1")
|
||||
|
||||
text = N.render_task_tracker(tid)
|
||||
# Raw title markup is escaped -> cannot break parse_mode=HTML.
|
||||
assert "<b>" not in text
|
||||
assert "<b>" in text
|
||||
assert "&" in text
|
||||
# The card's own anchor markup stays well-formed (balanced tags).
|
||||
assert text.count("<a href=") == text.count("</a>")
|
||||
assert text.count("<a href=") >= 1 # the clickable number is present
|
||||
|
||||
|
||||
def test_tc16_ampersand_in_work_item_id_escaped(monkeypatch):
|
||||
# A '&' in the work_item_id is escaped in the (unlinked) fail-safe path too.
|
||||
_set(monkeypatch, plane_web_url="", plane_api_url="",
|
||||
plane_workspace_slug="acme")
|
||||
tid = _mk_task(wid="ORCH&67", plane_issue_id="iss-1")
|
||||
text = N.render_task_tracker(tid)
|
||||
assert "ORCH&67" in text
|
||||
assert "<a href=" not in text # no link (no web base)
|
||||
@@ -1,216 +0,0 @@
|
||||
"""ORCH-067 — Group B: the Plane-status line on the live card (AC-5..AC-9).
|
||||
|
||||
The card now carries an explicit '📍 <Plane status>' line under the header that
|
||||
follows the ORCH-066 status model. The OFFLINE core (stage->status + In Review
|
||||
from the brd-clock + Awaiting Deploy) is pure/deterministic and never touches the
|
||||
network; a best-effort LIVE overlay draws the branch statuses that are
|
||||
indistinguishable offline (Needs Input / Blocked / …). Everything degrades to the
|
||||
stage default and NEVER raises (AC-9). Network is isolated: the live-state read
|
||||
(`_live_state_uuid_cached`) and `get_project_states` are patched per case; the DB
|
||||
is a temp SQLite.
|
||||
|
||||
Test ids TC-05..TC-09 from 04-test-plan.yaml.
|
||||
"""
|
||||
|
||||
import os
|
||||
import tempfile
|
||||
|
||||
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
|
||||
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
|
||||
|
||||
_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_status_line.db")
|
||||
os.environ["ORCH_DB_PATH"] = _test_db
|
||||
|
||||
from types import SimpleNamespace # noqa: E402
|
||||
|
||||
import pytest # noqa: E402
|
||||
|
||||
import src.db as db_module # noqa: E402
|
||||
import src.projects as projects_mod # noqa: E402
|
||||
from src.db import init_db, get_db # noqa: E402
|
||||
from src import notifications as N # noqa: E402
|
||||
import src.plane_sync as plane_sync # noqa: E402
|
||||
|
||||
_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def setup_db(monkeypatch):
|
||||
monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
init_db()
|
||||
# Live overlay OFF by default for the offline-core tests; cases that need it
|
||||
# turn it back on explicitly. Keep the per-issue cache clean between cases.
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_live_status", False, raising=False)
|
||||
N._LIVE_STATE_CACHE.clear()
|
||||
# Pin repo->project resolution (cross-file ORCH_PROJECTS_JSON reloads must not
|
||||
# strip 'orchestrator' and disable the live overlay under us).
|
||||
monkeypatch.setattr(
|
||||
projects_mod, "get_project_by_repo",
|
||||
lambda repo: (SimpleNamespace(plane_project_id=_ORCH_PROJECT_ID)
|
||||
if repo == "orchestrator" else None),
|
||||
)
|
||||
yield
|
||||
if os.path.exists(_test_db):
|
||||
os.unlink(_test_db)
|
||||
|
||||
|
||||
def _mk_task(stage="development", wid="ORCH-067", repo="orchestrator",
|
||||
plane_issue_id="issue-uuid-1", brd_started=None, brd_ended=None,
|
||||
title="status line"):
|
||||
conn = get_db()
|
||||
cur = conn.execute(
|
||||
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, "
|
||||
"plane_issue_id, brd_review_started_at, brd_review_ended_at) "
|
||||
"VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
|
||||
("p1", wid, repo, "feature/ORCH-067-x", stage, title, plane_issue_id,
|
||||
brd_started, brd_ended),
|
||||
)
|
||||
tid = cur.lastrowid
|
||||
conn.commit()
|
||||
conn.close()
|
||||
return tid
|
||||
|
||||
|
||||
def _status_line(text):
|
||||
"""Extract the single '📍 ...' status line from rendered card text."""
|
||||
for ln in text.splitlines():
|
||||
if ln.startswith("\U0001f4cd"):
|
||||
return ln
|
||||
return None
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-05 / AC-5 — render carries an explicit Plane-status line
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc05_render_has_status_line():
|
||||
tid = _mk_task(stage="development")
|
||||
text = N.render_task_tracker(tid)
|
||||
line = _status_line(text)
|
||||
assert line is not None # '📍 ...' present
|
||||
assert line == "\U0001f4cd Development" # stage -> Plane status
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-06 / AC-6 — stage -> Plane status mapping (ТЗ §2.2), parametrized
|
||||
# --------------------------------------------------------------------------- #
|
||||
@pytest.mark.parametrize("stage,expected", [
|
||||
("created", "To Analyse"),
|
||||
("analysis", "Analysis"),
|
||||
("architecture", "Architecture"),
|
||||
("development", "Development"),
|
||||
("review", "Code-Review"),
|
||||
("testing", "Testing"),
|
||||
("deploy", "⏸️ Awaiting Deploy — ожидание Confirm Deploy"),
|
||||
("done", "Done"),
|
||||
])
|
||||
def test_tc06_stage_to_plane_status(stage, expected):
|
||||
# plane_status_label is pure/offline -> assert directly off a row-like dict.
|
||||
assert N.plane_status_label({"stage": stage}) == expected
|
||||
|
||||
|
||||
def test_tc06_unknown_stage_degrades_to_default():
|
||||
# Anything unknown -> the safe stage default (To Analyse), never an error.
|
||||
assert N.plane_status_label({"stage": "weird-stage"}) == "To Analyse"
|
||||
assert N.plane_status_label({}) == "To Analyse"
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-07 / AC-7 — In Review from the brd-clock, OFFLINE (no network)
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc07_in_review_from_brd_clock(monkeypatch):
|
||||
# analysis + brd started + not ended -> '⏸️ In Review' (waiting BRD approve).
|
||||
# Guard: any network read would fail this test -> prove it stays offline.
|
||||
def _boom(*a, **k):
|
||||
raise AssertionError("In Review must be resolved OFFLINE (no network)")
|
||||
monkeypatch.setattr(N, "_live_state_uuid_cached", _boom)
|
||||
|
||||
tid = _mk_task(stage="analysis", brd_started="2026-06-08 10:00:00",
|
||||
brd_ended=None)
|
||||
text = N.render_task_tracker(tid)
|
||||
|
||||
assert _status_line(text) == "\U0001f4cd " + N._IN_REVIEW_LABEL
|
||||
# The human-gate 'Подтверждение BRD' line with ⏸️/⏳ is still rendered.
|
||||
assert N._BRD_LABEL in text
|
||||
assert "⏳" in text # ⏳ still-waiting marker
|
||||
|
||||
|
||||
def test_tc07b_in_review_clears_once_brd_ended():
|
||||
# Once the BRD review ended, analysis is back to the plain 'Analysis' status.
|
||||
tid = _mk_task(stage="analysis", brd_started="2026-06-08 10:00:00",
|
||||
brd_ended="2026-06-08 10:30:00")
|
||||
assert _status_line(N.render_task_tracker(tid)) == "\U0001f4cd Analysis"
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-08 / AC-8 — Awaiting Deploy (offline) + Needs Input (live overlay)
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc08_awaiting_deploy_offline():
|
||||
# stage=deploy -> '⏸️ Awaiting Deploy' purely offline (no overlay needed).
|
||||
tid = _mk_task(stage="deploy")
|
||||
line = _status_line(N.render_task_tracker(tid))
|
||||
assert line == "\U0001f4cd ⏸️ Awaiting Deploy — ожидание Confirm Deploy"
|
||||
|
||||
|
||||
def test_tc08_needs_input_via_live_overlay(monkeypatch):
|
||||
# Needs Input is NOT derivable offline -> drawn by the best-effort overlay
|
||||
# reading the LIVE Plane status. Patch the live read + the state map.
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_live_status", True,
|
||||
raising=False)
|
||||
monkeypatch.setattr(N, "_live_state_uuid_cached",
|
||||
lambda issue_id, project_id: "uuid-needs-input")
|
||||
monkeypatch.setattr(
|
||||
plane_sync, "get_project_states",
|
||||
lambda project_id: {"needs_input": "uuid-needs-input"},
|
||||
)
|
||||
# repo='orchestrator' resolves to a real registry project_id -> overlay runs.
|
||||
tid = _mk_task(stage="development", repo="orchestrator")
|
||||
line = _status_line(N.render_task_tracker(tid))
|
||||
assert line == "\U0001f4cd ❓ Needs Input — нужны уточнения"
|
||||
|
||||
|
||||
def test_tc08b_overlay_no_match_keeps_offline_base(monkeypatch):
|
||||
# Live status maps to no branch key -> the offline stage base is kept.
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_live_status", True,
|
||||
raising=False)
|
||||
monkeypatch.setattr(N, "_live_state_uuid_cached",
|
||||
lambda issue_id, project_id: "uuid-in-progress")
|
||||
monkeypatch.setattr(
|
||||
plane_sync, "get_project_states",
|
||||
lambda project_id: {"in_progress": "uuid-in-progress",
|
||||
"needs_input": "uuid-needs-input"},
|
||||
)
|
||||
tid = _mk_task(stage="development", repo="orchestrator")
|
||||
assert _status_line(N.render_task_tracker(tid)) == "\U0001f4cd Development"
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# TC-09 / AC-9, AC-16 — render never raises on broken/unreachable status data
|
||||
# --------------------------------------------------------------------------- #
|
||||
def test_tc09_render_survives_overlay_exception(monkeypatch):
|
||||
# The live overlay blowing up must NOT escape render -> degrade to stage base.
|
||||
monkeypatch.setattr(N._get_settings(), "tracker_live_status", True,
|
||||
raising=False)
|
||||
|
||||
def _boom(*a, **k):
|
||||
raise RuntimeError("plane down")
|
||||
monkeypatch.setattr(N, "_live_state_uuid_cached", _boom)
|
||||
|
||||
tid = _mk_task(stage="development", repo="orchestrator")
|
||||
text = N.render_task_tracker(tid) # must not raise
|
||||
assert _status_line(text) == "\U0001f4cd Development"
|
||||
|
||||
|
||||
def test_tc09b_card_status_label_never_raises(monkeypatch):
|
||||
# _card_status_label swallows everything -> a usable default, never an error.
|
||||
def _boom(*a, **k):
|
||||
raise RuntimeError("boom")
|
||||
monkeypatch.setattr(N, "plane_status_label", _boom)
|
||||
assert N._card_status_label({"stage": "development"}) == "To Analyse"
|
||||
|
||||
|
||||
def test_tc09c_plane_status_label_never_raises():
|
||||
# Garbage row (None / object without keys) -> safe default, no exception.
|
||||
assert N.plane_status_label(None) == "To Analyse"
|
||||
assert N.plane_status_label(object()) == "To Analyse"
|
||||
Reference in New Issue
Block a user