integ: merge ORCH-066 plane status model
# Conflicts: # CHANGELOG.md # docs/architecture/README.md # src/plane_sync.py # src/webhooks/plane.py
This commit is contained in:
7
docs/work-items/ORCH-066/00-business-request.md
Normal file
7
docs/work-items/ORCH-066/00-business-request.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# Business Request: [высокий] Статусная модель Plane: осмысленные статусы этапов
|
||||
|
||||
Work Item ID: ORCH-066
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
110
docs/work-items/ORCH-066/01-brd.md
Normal file
110
docs/work-items/ORCH-066/01-brd.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# 01 — Business Requirements Document (BRD)
|
||||
|
||||
**Work Item:** ORCH-066
|
||||
**Заголовок:** [высокий] Статусная модель Plane: осмысленные статусы этапов
|
||||
**Стадия:** analysis
|
||||
**Автор:** Analyst
|
||||
**Дата:** 2026-06-07
|
||||
|
||||
---
|
||||
|
||||
## 1. Контекст и проблема
|
||||
|
||||
Статусная модель Plane оркестратора имеет **семантические перегрузки**: один и тот
|
||||
же Plane-статус используется для несовместимых смыслов, из-за чего:
|
||||
|
||||
- оператор не понимает, на каком реально этапе стоит задача (доска нечитаема);
|
||||
- повышается риск ошибки оператора (например, неверный ручной перевод статуса);
|
||||
- `In Progress` одновременно означает «человек запускает конвейер», «идёт анализ»,
|
||||
«идёт прод-деплой» и «возврат из Needs Input» — четыре разных смысла на одном статусе.
|
||||
|
||||
Уже частично исправлено: ORCH-059 ввёл отдельный статус для подтверждения деплоя
|
||||
(`Confirm Deploy`), разгрузив перегруженный `Approved`. ORCH-066 завершает наведение
|
||||
порядка по **утверждённой Owner** статусной модели.
|
||||
|
||||
### Два слоя (критично различать)
|
||||
|
||||
| Слой | Что это | Источник | Трогаем? |
|
||||
|------|---------|----------|----------|
|
||||
| **A** | `STAGE_TRANSITIONS` — внутренняя машина стадий (`created→analysis→…→done`) | `src/stages.py` | **НЕТ (инвариант)** |
|
||||
| **B** | Plane-статусы — индикация на доске | `src/plane_sync.py` + точки в `src/stage_engine.py` / `src/webhooks/plane.py` | **ДА** |
|
||||
|
||||
ORCH-066 меняет **только слой B** и точки, где код вручную проставляет Plane-статусы.
|
||||
|
||||
---
|
||||
|
||||
## 2. Целевая статусная модель (решение Owner)
|
||||
|
||||
```
|
||||
Backlog → Todo → [To Analyse] → Analysis → [In Review → Approved] → Architecture →
|
||||
Development → Code-Review → Testing → Awaiting Deploy → [Confirm Deploy] → Deploying →
|
||||
Monitoring after Deploy → Done
|
||||
```
|
||||
|
||||
- `[...]` = **действие человека** (вход-триггер).
|
||||
- Остальное ставит **орк** (индикация).
|
||||
|
||||
### Ветки (нелинейные исходы)
|
||||
- **Rejected** — откат на предыдущую стадию (человек).
|
||||
- **Needs Input** — ТОЛЬКО аналитик (НЕ расширять на других агентов).
|
||||
- **Blocked** — затык / фейл деплоя / деградация прода.
|
||||
- **Cancelled** — человек решил не делать задачу (валидный выход из In Review).
|
||||
|
||||
---
|
||||
|
||||
## 3. Бизнес-требования
|
||||
|
||||
| ID | Требование | Приоритет |
|
||||
|----|------------|-----------|
|
||||
| **BR-1** | Каждый этап конвейера показывается на доске Plane осмысленным статусом (To Analyse / Analysis / Code-Review / Awaiting Deploy / Deploying / Monitoring after Deploy). | Must |
|
||||
| **BR-2** | `To Analyse` — единый человеческий вход: (а) старт нового конвейера, (б) resume/relaunch аналитика при возврате из Needs Input. Заменяет роль `In Progress` как входа-триггера. | Must |
|
||||
| **BR-3** | Стадия `analysis` индицируется отдельным статусом `Analysis` (орк ставит при старте/relaunch аналитика), а не `In Progress`. | Must |
|
||||
| **BR-4** | Стадия `review` индицируется Plane-статусом `Code-Review` (переименование `Review`). | Must |
|
||||
| **BR-5** | Self-deploy Phase A (approval-pending) ставит `Awaiting Deploy` вместо `In Review`. | Must |
|
||||
| **BR-6** | Self-deploy Phase B (старт прод-деплоя) ставит `Deploying`. | Must |
|
||||
| **BR-7** | Self-deploy Phase C (health-OK финализация) ставит `Monitoring after Deploy` (НЕ `Done` сразу). | Must |
|
||||
| **BR-8** | Post-deploy monitor (ORCH-021): чистое закрытие окна (HEALTHY) → `Done`; UNHEALTHY/деградация → `Blocked`. | Must |
|
||||
| **BR-9** | `In Review` разгрузить: оставить ТОЛЬКО за approve-pending артефактов конвейера (BRD/ревью). Выходы: `Approved` (вперёд), `Rejected` (откат), `Cancelled` (человек отменил). | Must |
|
||||
| **BR-10** | `Needs Input` — БЕЗ ИЗМЕНЕНИЙ. Остаётся только у аналитика (`01-questions.md` → `set_issue_needs_input`). Механизм не трогать. | Must |
|
||||
| **BR-11** | Возврат аналитика из Needs Input выполняется через `To Analyse` (а НЕ через `In Progress`). Логика fork «старт vs resume» (по наличию task + active-job) сохраняется. | Must (грабли R1) |
|
||||
| **BR-12** | **Fail-closed:** отсутствие нового статуса в проекте (enduro / Plane API down / fallback `_DEFAULT_STATES`) НЕ приводит к падению; поведение остаётся backward-compatible (паттерн ORCH-059 AC-7). | Must |
|
||||
| **BR-13** | Reconciler не «оживляет» активные ожидания (`Awaiting Deploy` / `Deploying` / `Monitoring after Deploy`) как зависшие задачи (Guard 2 skip-list). | Must |
|
||||
| **BR-14** | Документация (golden source) обновлена в том же PR: `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`, ADR per-work-item. | Must |
|
||||
|
||||
---
|
||||
|
||||
## 4. Границы (Out of Scope / НЕ трогать)
|
||||
|
||||
- `STAGE_TRANSITIONS` (`src/stages.py`) — машина стадий, инвариант.
|
||||
- `QG_CHECKS`, `check_deploy_status`, exit-коды хука (0/1/2), merge-gate, схема БД.
|
||||
- `Confirm Deploy` (уже работает, ORCH-059).
|
||||
- Механизм `Needs Input` (analyst-only) — не расширять, не менять.
|
||||
- Поведение прод-деплоя **не-self** репозиториев (enduro-trails): для них терминальный
|
||||
переход остаётся `deploy → Done` как сейчас (Monitoring after Deploy не применяется —
|
||||
post-deploy monitor армится только для self-hosting).
|
||||
- Автоматический approve / авто-rollback self-hosting (ORCH-54 / ORCH-021 политика
|
||||
ALERT_ONLY) — не меняется.
|
||||
|
||||
---
|
||||
|
||||
## 5. Инфра-предусловие (вне кода, делает оператор)
|
||||
|
||||
Новые Plane-статусы в проекте **ORCH** создаёт оператор через Plane API **ДО** эксплуатации:
|
||||
`To Analyse`, `Analysis`, `Code-Review`, `Awaiting Deploy`, `Deploying`,
|
||||
`Monitoring after Deploy` (`Confirm Deploy` уже есть).
|
||||
|
||||
Резолвер (`_PLANE_NAME_TO_KEY` + `get_project_states`) подхватывает их **по имени** с
|
||||
**fail-closed fallback** на `_DEFAULT_STATES` (см. BR-12). Документируется в
|
||||
`07-infra-requirements.md` (создаёт архитектор) и в `docs/operations/`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Definition of Done
|
||||
|
||||
- Plane показывает осмысленные статусы на каждом этапе.
|
||||
- Возврат аналитика из Needs Input работает через `To Analyse`.
|
||||
- Phase A → `Awaiting Deploy`, Phase B → `Deploying`, Phase C → `Monitoring after Deploy`,
|
||||
окно HEALTHY → `Done`, фейл → `Blocked`.
|
||||
- `STAGE_TRANSITIONS` не изменён.
|
||||
- `pytest tests/ -q` — зелёный. Fail-closed покрыт тестами.
|
||||
- Документация обновлена.
|
||||
178
docs/work-items/ORCH-066/02-trz.md
Normal file
178
docs/work-items/ORCH-066/02-trz.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# 02 — Техническое задание (ТЗ)
|
||||
|
||||
**Work Item:** ORCH-066
|
||||
**Стадия:** analysis → (вход для architecture)
|
||||
**Автор:** Analyst
|
||||
|
||||
> ТЗ фиксирует ТРЕБУЕМОЕ ПОВЕДЕНИЕ и затронутые точки кода. Конкретную архитектуру
|
||||
> резолвера (точные имена ключей/функций) финализирует архитектор в ADR. Ниже —
|
||||
> опорный контракт, согласованный с бизнес-запросом Owner.
|
||||
|
||||
---
|
||||
|
||||
## 1. Задействованные модули `src/`
|
||||
|
||||
| Модуль | Роль в задаче |
|
||||
|--------|---------------|
|
||||
| `src/plane_sync.py` | **Ядро изменений (слой B):** реестр логических статусов (`_DEFAULT_STATES`), `_PLANE_NAME_TO_KEY`, маппинг стадия→статус (`_STAGE_TO_STATE_KEY`, `STAGE_VISIBILITY_STATE`), хелперы `set_issue_*`. |
|
||||
| `src/webhooks/plane.py` | Маршрутизация входящего статуса (`handle_issue_updated`): `To Analyse` → `handle_status_start` (старт **или** resume). |
|
||||
| `src/stage_engine.py` | Точки ручной простановки статуса: analyst-flow (`Analysis`/`Needs Input`/`In Review`), Phase A (`Awaiting Deploy`), Phase B (`Deploying`), Phase C → `Monitoring after Deploy`, post-deploy monitor → `Done`/`Blocked`. |
|
||||
| `src/reconciler.py` | F-2 запрос статусов (`To Analyse` в список), Guard 2 skip-list (активные ожидания). |
|
||||
| `src/stages.py` | **НЕ менять** (инвариант слоя A). Используется только для чтения переходов. |
|
||||
| `src/config.py` | (При необходимости) kill-switch для новой статусной модели — на усмотрение архитектора (см. §6). |
|
||||
|
||||
---
|
||||
|
||||
## 2. Изменения статусной модели (слой B)
|
||||
|
||||
### 2.1. Реестр логических статусов (`src/plane_sync.py`)
|
||||
|
||||
Ввести новые **логические ключи** и их имена в `_PLANE_NAME_TO_KEY`:
|
||||
|
||||
| Логический ключ | Plane name | Назначение |
|
||||
|-----------------|-----------|------------|
|
||||
| `to_analyse` | `To Analyse` | Вход-триггер (старт + resume аналитика). |
|
||||
| `analysis` | `Analysis` | Индикация стадии analysis (орк). |
|
||||
| `code_review` | `Code-Review` | Индикация стадии review (орк). Заменяет `review`. |
|
||||
| `awaiting_deploy` | `Awaiting Deploy` | Phase A approval-pending (орк). |
|
||||
| `deploying` | `Deploying` | Phase B прод-деплой идёт (орк). |
|
||||
| `monitoring` | `Monitoring after Deploy` | Phase C / post-deploy окно (орк). |
|
||||
|
||||
Сохранить существующие: `backlog`, `todo`, `in_progress` (backward-compat), `needs_input`,
|
||||
`in_review`, `blocked`, `done`, `cancelled`, `architecture`, `development`, `testing`,
|
||||
`approved`, `rejected`. `Cancelled` уже присутствует в `_PLANE_NAME_TO_KEY`.
|
||||
|
||||
### 2.2. Fail-closed резолюция (КРИТИЧНО — BR-12)
|
||||
|
||||
`get_project_states()` после резолва по API делает `setdefault(k, v)` из `_DEFAULT_STATES`.
|
||||
Чтобы отсутствие нового статуса в проекте (enduro / Plane down / частичная конфигурация)
|
||||
**не ломало** конвейер, новые логические ключи в `_DEFAULT_STATES` должны
|
||||
**алиаситься на существующие UUID** (degrade-to-current):
|
||||
|
||||
| Новый ключ | Default-алиас (UUID) | Деградированное поведение |
|
||||
|------------|----------------------|---------------------------|
|
||||
| `to_analyse` | = `in_progress` | enduro/старый проект: `In Progress` по-прежнему триггерит старт/resume. |
|
||||
| `analysis` | = `in_progress` | analysis показывается как `In Progress` (как сейчас). |
|
||||
| `code_review` | = `review` | review показывается как `Review` (как сейчас). |
|
||||
| `awaiting_deploy` | = `in_review` | Phase A показывается как `In Review` (как сейчас). |
|
||||
| `deploying` | = `in_progress` | Phase B показывается как `In Progress` (как сейчас). |
|
||||
| `monitoring` | = `done` | Phase C показывается как `Done` (как сейчас); монитор затем держит Done / флипает Blocked. |
|
||||
|
||||
> Эффект: если оператор НЕ создал новый статус — система работает строго как до ORCH-066
|
||||
> (никаких падений, никаких 404 от Plane PATCH). Если создал — резолвится по имени и
|
||||
> используется новый UUID. Это ровно паттерн ORCH-059 AC-7.
|
||||
|
||||
### 2.3. Маппинг стадия → статус
|
||||
|
||||
`src/plane_sync.py`:
|
||||
- `_STAGE_TO_STATE_KEY`: `analysis` → `analysis` (было `in_progress`); `review` → `code_review`
|
||||
(было `review`). `deploy` остаётся (управляется Phase A/B/C напрямую, не через
|
||||
`update_issue_state`). `created`/`architecture`/`development`/`testing`/`done` — без изменений.
|
||||
- `STAGE_VISIBILITY_STATE`: `review` → `code_review` (было `review`). Добавить
|
||||
`analysis` → `analysis`, если индикация analysis ставится через `set_issue_stage_state`
|
||||
(решает архитектор; альтернатива — отдельный хелпер `set_issue_analysis`).
|
||||
- Сохранить совместимость `STAGE_TO_STATE` / `PLANE_STATES` алиасов (импортируются тестами).
|
||||
|
||||
### 2.4. Точки простановки статуса
|
||||
|
||||
| Место (файл:симв.) | Сейчас | Должно стать |
|
||||
|--------------------|--------|--------------|
|
||||
| `webhooks/plane.py` `handle_issue_updated` | `new_state == in_progress` → `handle_status_start` | `new_state == to_analyse` (с fail-closed: при алиасе совпадает с `in_progress`) → `handle_status_start` |
|
||||
| `webhooks/plane.py` `start_pipeline` (старт) | статус остаётся `In Progress` | при старте/enqueue analyst орк ставит `Analysis` |
|
||||
| `webhooks/plane.py` `handle_status_start` (resume из Needs Input) | relaunch на `In Progress`-триггере | relaunch на `To Analyse`-триггере; при relaunch орк ставит `Analysis`. Fork «старт vs resume» (по `get_task_by_plane_id` + `has_active_job_for_task`) — **сохранить как есть.** |
|
||||
| `stage_engine.py` `_handle_analysis_approved_flow` (artifacts ready) | `set_issue_in_review` | оставить `In Review` (BR-9: In Review только за approve-pending конвейера) ✔ без изменений |
|
||||
| `stage_engine.py` `_handle_analysis_approved_flow` (questions) | `set_issue_needs_input` | **без изменений** (BR-10) |
|
||||
| `stage_engine.py` `_handle_self_deploy_phase_a` | `set_issue_in_review` | `Awaiting Deploy` (`set_issue_awaiting_deploy` или аналог) |
|
||||
| `stage_engine.py` `_handle_self_deploy_phase_b` | (статус не меняет) | `Deploying` |
|
||||
| `stage_engine.py` advance `deploy → done` (terminal-sync, строка ~338) | `set_issue_done` для всех | **self-hosting:** `Monitoring after Deploy` (перед/вместо арма монитора); **не-self:** `Done` как сейчас |
|
||||
| `stage_engine.py` `run_post_deploy_monitor` (HEALTHY, окно закрыто) | пишет лог + коммент, статус Plane НЕ трогает (остаётся Done) | `Done` (явно) |
|
||||
| `stage_engine.py` `run_post_deploy_monitor` (DEGRADED) | пишет лог + alert | `Blocked` |
|
||||
|
||||
> **Замечание по terminal-sync (важно для архитектора):** сейчас `advance_stage` на
|
||||
> `next_stage == "done"` вызывает `set_issue_done` безусловно (строка ~338), затем армит
|
||||
> post-deploy monitor для self-hosting (~361). Нужно развести: для репо, где
|
||||
> `post_deploy.post_deploy_applies(repo)` истинно (self-hosting) — ставить `Monitoring
|
||||
> after Deploy` вместо `Done`, и переложить простановку `Done`/`Blocked` на финал
|
||||
> монитора (`run_post_deploy_monitor`). Для прочих репо — `Done` как сейчас.
|
||||
|
||||
### 2.5. Новые хелперы `src/plane_sync.py`
|
||||
|
||||
Добавить тонкие обёртки по образцу `set_issue_in_review` (резолв per-project UUID +
|
||||
`_set_issue_state_direct`), never-raise при отсутствии issue:
|
||||
- `set_issue_analysis(work_item_id, project_id=None)`
|
||||
- `set_issue_code_review(...)` (или через `set_issue_stage_state("review")`)
|
||||
- `set_issue_awaiting_deploy(...)`
|
||||
- `set_issue_deploying(...)`
|
||||
- `set_issue_monitoring(...)`
|
||||
|
||||
(Точный набор/именование — на усмотрение архитектора; контракт: per-project резолв +
|
||||
fail-closed.)
|
||||
|
||||
---
|
||||
|
||||
## 3. Изменения reconciler (`src/reconciler.py`)
|
||||
|
||||
- **F-2** `_reconcile_plane_project`: добавить `to_analyse` в список запрашиваемых
|
||||
статусов (`list_issues_by_state([... , to_analyse])`) и в `_reconcile_plane_issue`
|
||||
маршрутизировать `new_state == to_analyse` → `handle_status_start` (старт при `task is
|
||||
None`, resume при существующем task без active-job — логика уже в `handle_status_start`).
|
||||
Сохранить обработку `approved`/`rejected`. При fail-closed алиасе `to_analyse==in_progress`
|
||||
поведение не дублируется (один и тот же UUID).
|
||||
- **Guard 2** `_is_blocked_or_needs_input` (F-1 skip): расширить skip-множество активными
|
||||
ожиданиями — `awaiting_deploy`, `deploying`, `monitoring` — чтобы реконсилер НЕ
|
||||
«оживлял» их как зависшие (BR-13). Имя метода/семантику можно обобщить
|
||||
(«human-or-active-wait»), флаг `reconcile_skip_blocked_enabled` продолжает управлять
|
||||
этим networked-чеком.
|
||||
|
||||
> Примечание: F-1 и так не тронет Phase A (`check_deploy_status` red → silent),
|
||||
> Deploying (active finalizer job), Monitoring (стадия `done`). Guard 2 — явная
|
||||
> defense-in-depth по требованию Owner.
|
||||
|
||||
---
|
||||
|
||||
## 4. Изменения API / эндпоинтов
|
||||
|
||||
**Нет** новых HTTP-эндпоинтов. `GET /queue` / `GET /status` — без изменений контракта
|
||||
(статусы Plane там не отражаются). Изменения только во внешней индикации Plane (PATCH
|
||||
issue state — существующий механизм).
|
||||
|
||||
---
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
|
||||
**Нет.** `tasks` не хранит Plane-статус (источник истины — стадия в БД + Plane API).
|
||||
Миграции не требуются.
|
||||
|
||||
---
|
||||
|
||||
## 6. Требования к новым QG checks
|
||||
|
||||
**Нет.** `QG_CHECKS` не расширяется. Статусы — индикация, не управление (канон:
|
||||
машинные вердикты читаются из YAML-frontmatter артефактов, не из Plane-статуса).
|
||||
|
||||
Опционально (на усмотрение архитектора): единый kill-switch новой статусной модели
|
||||
(env-флаг) для безопасного раската, по образцу `staging_infra_tolerance_enabled` /
|
||||
`reconcile_skip_blocked_enabled`. Не обязателен, т.к. fail-closed алиасинг (§2.2) уже даёт
|
||||
backward-compatible деградацию.
|
||||
|
||||
---
|
||||
|
||||
## 7. Артефакты pipeline, создаваемые/обновляемые
|
||||
|
||||
- `06-adr/ADR-001-plane-status-model.md` — архитектор (решение по резолверу,
|
||||
алиасингу, разводке terminal-sync).
|
||||
- `07-infra-requirements.md` — архитектор (список Plane-статусов для ручного создания
|
||||
оператором + Plane API инструкция).
|
||||
- Документация (golden source, тот же PR): `CLAUDE.md` (секция статусной модели),
|
||||
`docs/architecture/README.md` (секция статусов рядом с ORCH-036/ORCH-021),
|
||||
`CHANGELOG.md`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Инварианты (проверяемые)
|
||||
|
||||
- `src/stages.py` `STAGE_TRANSITIONS` — байт-в-байт без изменений.
|
||||
- `QG_CHECKS`, `check_deploy_status`/`_parse_deploy_status`, exit-коды хука, merge-gate,
|
||||
схема БД, `Confirm Deploy`, механизм `Needs Input` — без изменений.
|
||||
- Все новые `set_issue_*` / резолв — never-raise (Plane down ⇒ degrade, не crash).
|
||||
- Поведение enduro (не-self) и его терминальный `Done` — без регресса.
|
||||
71
docs/work-items/ORCH-066/03-acceptance-criteria.md
Normal file
71
docs/work-items/ORCH-066/03-acceptance-criteria.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# 03 — Критерии приёмки (Acceptance Criteria)
|
||||
|
||||
**Work Item:** ORCH-066
|
||||
|
||||
Каждый критерий — чёткое условие PASS/FAIL. Покрытие тестами — см. `04-test-plan.yaml`.
|
||||
|
||||
---
|
||||
|
||||
## Группа A — Вход и стадия анализа
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-1** | `To Analyse` запускает конвейер | Перевод issue без task в `To Analyse` → `handle_status_start` → `start_pipeline` (создаётся task, ветка, enqueue analyst). | Не запускается / запускается на другом статусе. |
|
||||
| **AC-2** | `To Analyse` делает resume аналитика из Needs Input | Существующий task без active-job + перевод в `To Analyse` → relaunch агента текущей стадии (analyst читает свежие комменты). Fork «старт vs resume» определяется по `get_task_by_plane_id` + `has_active_job_for_task` (как раньше). | Создаётся второй task / двойной запуск / resume не происходит. |
|
||||
| **AC-3** | Стадия `analysis` индицируется статусом `Analysis` | При старте/relaunch аналитика орк ставит `Analysis`. | Остаётся `In Progress` (при наличии статуса `Analysis` в проекте). |
|
||||
| **AC-4** | Busy-guard сохранён | `To Analyse` при существующем active-job для task → НЕ relaunch (no double launch). | Двойной запуск агента. |
|
||||
|
||||
## Группа B — Code-Review
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-5** | Стадия `review` индицируется `Code-Review` | Вход в стадию `review` → Plane-статус `Code-Review`. | Остаётся `Review` (при наличии нового статуса). |
|
||||
|
||||
## Группа C — Self-deploy фазы
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-6** | Phase A → `Awaiting Deploy` | `_handle_self_deploy_phase_a` ставит `Awaiting Deploy` (не `In Review`). | Ставит `In Review` (при наличии нового статуса). |
|
||||
| **AC-7** | Phase B → `Deploying` | `_handle_self_deploy_phase_b` при успешном `initiate_deploy` ставит `Deploying`. | Статус не меняется / иной. |
|
||||
| **AC-8** | Phase C → `Monitoring after Deploy` (self) | Финализатор SUCCESS для self-hosting → статус `Monitoring after Deploy`, НЕ `Done` сразу. | Ставит `Done` немедленно (для self-hosting). |
|
||||
| **AC-9** | Не-self deploy → `Done` без регресса | Для не-self репо (`post_deploy_applies==False`) терминальный `deploy → done` ставит `Done` как сейчас. | Не-self репо получает `Monitoring after Deploy` / иной регресс. |
|
||||
|
||||
## Группа D — Post-deploy monitor
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-10** | Чистое окно → `Done` | `run_post_deploy_monitor` HEALTHY + окно исчерпано → статус `Done`. | Остаётся `Monitoring after Deploy` / иной. |
|
||||
| **AC-11** | Деградация → `Blocked` | `run_post_deploy_monitor` DEGRADED → статус `Blocked` (+ существующий ALERT_ONLY для self). | Остаётся в Monitoring / ставит Done. |
|
||||
| **AC-12** | Self-hosting монитор не рестартит прод | Тик НИКОГДА не рестартит/откатывает прод-контейнер (ORCH-021 BR-5 сохранён). | Тик трогает прод-контейнер. |
|
||||
|
||||
## Группа E — In Review / Needs Input / ветки
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-13** | `In Review` только за approve-pending конвейера | `In Review` ставится лишь для approve артефактов (analyst BRD/ревью), не для Phase A. | Phase A / иные стадии ставят `In Review`. |
|
||||
| **AC-14** | `Needs Input` без изменений | Поведение `set_issue_needs_input` (analyst `01-questions.md`) идентично прежнему; не расширено на других агентов. | Механизм изменён / расширен. |
|
||||
| **AC-15** | `Cancelled` — валидный выход из In Review без действий конвейера | Перевод в `Cancelled` → орк не выполняет advance/rollback (индикация, не управление). | Орк совершает действие конвейера на `Cancelled`. |
|
||||
|
||||
## Группа F — Fail-closed (КРИТИЧНО)
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-16** | Отсутствие нового статуса не ломает конвейер | Проект без новых статусов (enduro/частичный/Plane down) → `get_project_states` отдаёт default-алиасы; все `set_issue_*`/триггеры работают backward-compatible, без исключений и без 404 PATCH. | Падение / необработанное исключение / зависание задачи. |
|
||||
| **AC-17** | enduro `In Progress` по-прежнему стартует конвейер | Через `to_analyse`-алиас (= `in_progress` UUID) перевод enduro-issue в `In Progress` запускает старт/resume. | enduro-старт сломан. |
|
||||
| **AC-18** | Резолв по имени | При наличии статуса в проекте по `name` (`_PLANE_NAME_TO_KEY`) используется его UUID, а не default-алиас. | Используется неверный UUID. |
|
||||
|
||||
## Группа G — Reconciler
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-19** | F-2 реконсилирует `To Analyse` | `_reconcile_plane_project` запрашивает `to_analyse` и маршрутизирует к `handle_status_start` (старт/resume при потерянном webhook). | `To Analyse`-старты не реконсилируются. |
|
||||
| **AC-20** | Guard 2 skip активных ожиданий | Задачи в `Awaiting Deploy` / `Deploying` / `Monitoring after Deploy` НЕ «оживляются» F-1 как зависшие. | Реконсилер advance'ит активное ожидание. |
|
||||
|
||||
## Группа H — Инварианты и документация
|
||||
|
||||
| ID | Критерий | PASS | FAIL |
|
||||
|----|----------|------|------|
|
||||
| **AC-21** | `STAGE_TRANSITIONS` не изменён | `src/stages.py` `STAGE_TRANSITIONS` идентичен (diff пуст). | Любое изменение слоя A. |
|
||||
| **AC-22** | Реестры/контракты не изменены | `QG_CHECKS`, `check_deploy_status`, exit-коды хука, merge-gate, схема БД, `Confirm Deploy` — без изменений. | Любое изменение перечисленного. |
|
||||
| **AC-23** | Тесты зелёные | `pytest tests/ -q` проходит полностью; новые fail-closed тесты присутствуют и зелёные. | Любой красный тест. |
|
||||
| **AC-24** | Документация обновлена (golden source) | `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md` обновлены; заведён `06-adr/ADR-001-*`. | Любой из артефактов не обновлён. |
|
||||
184
docs/work-items/ORCH-066/04-test-plan.yaml
Normal file
184
docs/work-items/ORCH-066/04-test-plan.yaml
Normal file
@@ -0,0 +1,184 @@
|
||||
work_item: ORCH-066
|
||||
description: >
|
||||
Тест-план статусной модели Plane (слой B). Покрывает осмысленные статусы этапов,
|
||||
возврат аналитика через To Analyse, фазы self-deploy, post-deploy monitor,
|
||||
fail-closed деградацию и reconciler. Слой A (STAGE_TRANSITIONS) проверяется на
|
||||
неизменность. Все тесты — pytest; Plane API мокается (httpx), как в существующих
|
||||
tests/test_plane_*.py / tests/test_orch10_states.py.
|
||||
|
||||
tests:
|
||||
# --- Группа A: вход и стадия анализа ---
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "To Analyse без существующего task -> handle_status_start -> start_pipeline (старт конвейера)."
|
||||
module: tests/test_status_trigger.py
|
||||
covers: [AC-1]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: integration
|
||||
description: "To Analyse при существующем task без active-job -> relaunch агента стадии (resume из Needs Input), новый task НЕ создаётся."
|
||||
module: tests/test_plane_to_analyse_resume.py
|
||||
covers: [AC-2, BR-11]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "Старт/relaunch аналитика ставит Plane-статус Analysis (а не In Progress) при наличии статуса в проекте."
|
||||
module: tests/test_plane_status_model.py
|
||||
covers: [AC-3]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "To Analyse при существующем task с active-job -> НЕ relaunch (busy-guard)."
|
||||
module: tests/test_plane_to_analyse_resume.py
|
||||
covers: [AC-4]
|
||||
expected: PASS
|
||||
|
||||
# --- Группа B: Code-Review ---
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "Вход в стадию review -> Plane-статус Code-Review (маппинг _STAGE_TO_STATE_KEY / STAGE_VISIBILITY_STATE)."
|
||||
module: tests/test_plane_status_model.py
|
||||
covers: [AC-5]
|
||||
expected: PASS
|
||||
|
||||
# --- Группа C: self-deploy фазы ---
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "_handle_self_deploy_phase_a ставит Awaiting Deploy (не In Review)."
|
||||
module: tests/test_deploy_approve.py
|
||||
covers: [AC-6, AC-13]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "_handle_self_deploy_phase_b при успешном initiate_deploy ставит Deploying."
|
||||
module: tests/test_deploy_approve.py
|
||||
covers: [AC-7]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: integration
|
||||
description: "Phase C (finalizer SUCCESS) для self-hosting ставит Monitoring after Deploy, НЕ Done; армит post-deploy monitor."
|
||||
module: tests/test_deploy_terminal_sync.py
|
||||
covers: [AC-8]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: integration
|
||||
description: "Не-self репо: deploy->done ставит Done (без регресса, Monitoring не применяется)."
|
||||
module: tests/test_deploy_terminal_sync.py
|
||||
covers: [AC-9]
|
||||
expected: PASS
|
||||
|
||||
# --- Группа D: post-deploy monitor ---
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: "run_post_deploy_monitor HEALTHY + окно исчерпано -> Plane-статус Done."
|
||||
module: tests/test_post_deploy.py
|
||||
covers: [AC-10]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: "run_post_deploy_monitor DEGRADED -> Plane-статус Blocked (+ ALERT_ONLY для self)."
|
||||
module: tests/test_post_deploy.py
|
||||
covers: [AC-11]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: "Self-hosting тик НЕ рестартит/не откатывает прод-контейнер (ORCH-021 BR-5 сохранён)."
|
||||
module: tests/test_post_deploy.py
|
||||
covers: [AC-12]
|
||||
expected: PASS
|
||||
|
||||
# --- Группа E: In Review / Needs Input / Cancelled ---
|
||||
- id: TC-13
|
||||
type: unit
|
||||
description: "In Review ставится только за approve-pending конвейера (analyst BRD ready), не Phase A."
|
||||
module: tests/test_analyst_status_only_regression.py
|
||||
covers: [AC-13]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: unit
|
||||
description: "set_issue_needs_input (analyst 01-questions.md) поведение идентично прежнему; не расширено на других агентов."
|
||||
module: tests/test_plane_status_model.py
|
||||
covers: [AC-14, BR-10]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-15
|
||||
type: unit
|
||||
description: "Перевод в Cancelled -> handle_issue_updated не выполняет advance/rollback (индикация, не управление)."
|
||||
module: tests/test_plane_webhook.py
|
||||
covers: [AC-15]
|
||||
expected: PASS
|
||||
|
||||
# --- Группа F: fail-closed (критично) ---
|
||||
- id: TC-16
|
||||
type: unit
|
||||
description: "Проект без новых статусов: get_project_states отдаёт default-алиасы (to_analyse=in_progress, code_review=review, awaiting_deploy=in_review, monitoring=done); исключений нет."
|
||||
module: tests/test_plane_status_failclosed.py
|
||||
covers: [AC-16, BR-12]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-17
|
||||
type: unit
|
||||
description: "Plane API down -> get_project_states fallback на _DEFAULT_STATES; set_issue_* never-raise."
|
||||
module: tests/test_plane_status_failclosed.py
|
||||
covers: [AC-16]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-18
|
||||
type: integration
|
||||
description: "enduro In Progress по-прежнему стартует конвейер через to_analyse-алиас."
|
||||
module: tests/test_plane_status_failclosed.py
|
||||
covers: [AC-17]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-19
|
||||
type: unit
|
||||
description: "Резолв по имени: при наличии статуса в проекте используется его UUID, а не default-алиас."
|
||||
module: tests/test_orch10_states.py
|
||||
covers: [AC-18]
|
||||
expected: PASS
|
||||
|
||||
# --- Группа G: reconciler ---
|
||||
- id: TC-20
|
||||
type: integration
|
||||
description: "F-2 _reconcile_plane_project запрашивает to_analyse и маршрутизирует к handle_status_start (потерянный webhook старта/resume)."
|
||||
module: tests/test_reconciler_plane.py
|
||||
covers: [AC-19]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-21
|
||||
type: unit
|
||||
description: "Guard 2: задачи в Awaiting Deploy / Deploying / Monitoring after Deploy НЕ оживляются F-1 как зависшие."
|
||||
module: tests/test_reconciler.py
|
||||
covers: [AC-20, BR-13]
|
||||
expected: PASS
|
||||
|
||||
# --- Группа H: инварианты ---
|
||||
- id: TC-22
|
||||
type: unit
|
||||
description: "STAGE_TRANSITIONS не изменён (явная проверка ключей/значений слоя A)."
|
||||
module: tests/test_plane_status_model.py
|
||||
covers: [AC-21]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-23
|
||||
type: unit
|
||||
description: "QG_CHECKS реестр и check_deploy_status контракты не изменены."
|
||||
module: tests/test_plane_status_model.py
|
||||
covers: [AC-22]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-24
|
||||
type: integration
|
||||
description: "Полный прогон pytest tests/ -q зелёный (регрессия)."
|
||||
module: tests/
|
||||
covers: [AC-23]
|
||||
expected: PASS
|
||||
287
docs/work-items/ORCH-066/06-adr/ADR-001-plane-status-model.md
Normal file
287
docs/work-items/ORCH-066/06-adr/ADR-001-plane-status-model.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# ADR-001: Осмысленная статусная модель Plane (слой B)
|
||||
|
||||
**Work Item:** ORCH-066
|
||||
**Стадия:** architecture
|
||||
**Автор:** Architect
|
||||
**Дата:** 2026-06-07
|
||||
**Статус:** Accepted
|
||||
|
||||
> Контракт резолвера, алиасинга и разводки точек простановки статуса. Опирается на
|
||||
> BRD (`01-brd.md`), ТЗ (`02-trz.md`), критерии приёмки (`03-acceptance-criteria.md`).
|
||||
> Инфра-предусловие (статусы, создаваемые оператором) — `07-infra-requirements.md`,
|
||||
> риски — `10-tech-risks.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Контекст
|
||||
|
||||
Plane-доска оркестратора семантически перегружена: `In Progress` одновременно
|
||||
означает «человек запускает конвейер», «идёт анализ», «идёт прод-деплой» и «возврат
|
||||
из Needs Input». Оператор не различает реальный этап задачи → риск ошибочного ручного
|
||||
перевода статуса. ORCH-059 уже разгрузил `Approved` отдельным `Confirm Deploy`;
|
||||
ORCH-066 завершает наведение порядка по утверждённой Owner модели.
|
||||
|
||||
**Жёсткое разделение двух слоёв (инвариант проекта):**
|
||||
|
||||
| Слой | Что | Источник | ORCH-066 |
|
||||
|------|-----|----------|----------|
|
||||
| **A** | `STAGE_TRANSITIONS` — машина стадий | `src/stages.py` | **НЕ трогаем** |
|
||||
| **B** | Plane-статусы — индикация на доске | `src/plane_sync.py` + точки простановки | **меняем только это** |
|
||||
|
||||
Статус — **индикация, не управление**. Машинные вердикты по-прежнему читаются только
|
||||
из YAML-frontmatter артефактов (канон гейтов). Конвейер движут гейты слоя A; смена
|
||||
Plane-статуса не может продвинуть/откатить задачу (кроме существующих человеческих
|
||||
триггеров `To Analyse`/`Approved`/`Rejected`, которые и раньше были входами).
|
||||
|
||||
Целевая модель Owner:
|
||||
|
||||
```
|
||||
Backlog → Todo → [To Analyse] → Analysis → [In Review → Approved] → Architecture →
|
||||
Development → Code-Review → Testing → Awaiting Deploy → [Confirm Deploy] → Deploying →
|
||||
Monitoring after Deploy → Done
|
||||
```
|
||||
`[...]` = действие человека (вход-триггер); остальное ставит орк (индикация).
|
||||
Ветки: **Rejected** (откат), **Needs Input** (только аналитик), **Blocked** (затык/фейл
|
||||
деплоя/деградация), **Cancelled** (человек отменил задачу).
|
||||
|
||||
---
|
||||
|
||||
## 2. Решение
|
||||
|
||||
### 2.1. Реестр логических статусов (`src/plane_sync.py`)
|
||||
|
||||
Вводим 6 новых **логических ключей**. Имена в `_PLANE_NAME_TO_KEY` (резолв по имени из
|
||||
Plane API):
|
||||
|
||||
| Логический ключ | Plane name | Назначение |
|
||||
|-----------------|-----------|------------|
|
||||
| `to_analyse` | `To Analyse` | Вход-триггер: старт нового конвейера **и** resume аналитика из Needs Input. |
|
||||
| `analysis` | `Analysis` | Индикация стадии analysis (орк). |
|
||||
| `code_review` | `Code-Review` | Индикация стадии review (орк). Заменяет `review` как видимый статус. |
|
||||
| `awaiting_deploy` | `Awaiting Deploy` | Phase A approval-pending (орк). |
|
||||
| `deploying` | `Deploying` | Phase B прод-деплой идёт (орк). |
|
||||
| `monitoring` | `Monitoring after Deploy` | Phase C / post-deploy окно (орк). |
|
||||
|
||||
Существующие ключи сохраняются: `backlog`, `todo`, `in_progress`, `needs_input`,
|
||||
`in_review`, `blocked`, `done`, `cancelled`, `architecture`, `development`, `review`,
|
||||
`testing`, `approved`, `rejected`. `Cancelled` уже присутствует.
|
||||
|
||||
### 2.2. Fail-closed резолюция — **project-relative alias-fallback** (КРИТИЧНО, BR-12)
|
||||
|
||||
ТЗ §2.2 предложил статические алиасы на enduro-UUID в `_DEFAULT_STATES`. Архитектурное
|
||||
уточнение: для **частично сконфигурированного** проекта (оператор создал не все новые
|
||||
статусы) статический enduro-UUID в orchestrator-проекте даст невалидный `state` → PATCH
|
||||
422/404. Поэтому деградация делается **относительно того же проекта**, а не на чужой
|
||||
UUID.
|
||||
|
||||
**Два уровня fallback в `get_project_states()` (success-path), строго в порядке:**
|
||||
|
||||
1. Резолв по имени из Plane API (как сейчас).
|
||||
2. **Alias-fallback (новый):** для каждого отсутствующего нового ключа — UUID его
|
||||
**базового ключа из этого же проекта**:
|
||||
|
||||
```python
|
||||
_STATE_ALIAS_FALLBACK = {
|
||||
"to_analyse": "in_progress",
|
||||
"analysis": "in_progress",
|
||||
"code_review": "review",
|
||||
"awaiting_deploy": "in_review",
|
||||
"deploying": "in_progress",
|
||||
"monitoring": "done",
|
||||
}
|
||||
# после резолва по имени, ДО _DEFAULT_STATES.setdefault:
|
||||
for new_key, base_key in _STATE_ALIAS_FALLBACK.items():
|
||||
if new_key not in resolved and resolved.get(base_key):
|
||||
resolved[new_key] = resolved[base_key]
|
||||
```
|
||||
3. `_DEFAULT_STATES.setdefault(...)` (как сейчас) — последний резерв для путей, где
|
||||
API недоступен целиком (`if not project_id: return _DEFAULT_STATES`, полный провал
|
||||
запроса). В `_DEFAULT_STATES` новые ключи ТОЖЕ добавляются (= enduro-UUID базового
|
||||
ключа), чтобы любой caller всегда получал полный словарь и `states[key]` не кидал
|
||||
`KeyError`.
|
||||
|
||||
**Эффект деградации:**
|
||||
|
||||
| Сценарий | Поведение |
|
||||
|----------|-----------|
|
||||
| Orchestrator: все новые статусы созданы | резолв по имени → новые UUID (целевая модель). |
|
||||
| Orchestrator: создана ЧАСТЬ новых статусов | отсутствующие → **собственный** базовый UUID проекта → индикация деградирует до текущего статуса, PATCH валиден. |
|
||||
| Enduro (новые статусы не создаются никогда) | alias-fallback → собственные enduro базовые UUID → строго прежнее поведение (`In Progress`/`Review`/`Done`). |
|
||||
| Plane API down целиком | `_DEFAULT_STATES` (enduro-UUID) — без регресса относительно сегодняшнего поведения. |
|
||||
|
||||
Это паттерн ORCH-059 AC-7, усиленный project-relative разрешением. Все `set_issue_*` и
|
||||
`_set_issue_state_direct` остаются **never-raise** (PATCH-исключение логируется, не
|
||||
пробрасывается) — индикация деградирует, слой A не затрагивается.
|
||||
|
||||
### 2.3. Маппинг стадия → статус
|
||||
|
||||
- `_STAGE_TO_STATE_KEY` (живой путь `update_issue_state`→`stage_to_state`):
|
||||
`analysis` → `analysis` (было `in_progress`); `review` → `code_review` (было `review`).
|
||||
`deploy` остаётся `in_progress` (управляется Phase A/B/C напрямую). Остальные — без
|
||||
изменений.
|
||||
- `STAGE_VISIBILITY_STATE`: `review` → `code_review`; добавить `analysis` → `analysis`
|
||||
(для консистентности; `set_issue_stage_state` сейчас dormant, но карта обновляется).
|
||||
- `STAGE_TO_STATE` (legacy/test-only) — обновить `analysis`→`_DEFAULT_STATES["analysis"]`,
|
||||
`review`→`_DEFAULT_STATES["code_review"]`. UUID-значения **байт-в-байт прежние** (это
|
||||
алиасы на те же in_progress/review UUID) → тесты на конкретные UUID не краснеют.
|
||||
|
||||
### 2.4. Новые хелперы `src/plane_sync.py`
|
||||
|
||||
Тонкие обёртки по образцу `set_issue_in_review` (per-project резолв + `_set_issue_state_direct`,
|
||||
never-raise):
|
||||
|
||||
- `set_issue_analysis(work_item_id, project_id=None)`
|
||||
- `set_issue_code_review(work_item_id, project_id=None)`
|
||||
- `set_issue_awaiting_deploy(work_item_id, project_id=None)`
|
||||
- `set_issue_deploying(work_item_id, project_id=None)`
|
||||
- `set_issue_monitoring(work_item_id, project_id=None)`
|
||||
|
||||
`get_project_states` всегда возвращает полный словарь (см. §2.2), поэтому `[key]` не
|
||||
кидает `KeyError`.
|
||||
|
||||
### 2.5. Точки простановки статуса (разводка)
|
||||
|
||||
| Файл:место | Сейчас | Должно стать | AC |
|
||||
|------------|--------|--------------|----|
|
||||
| `webhooks/plane.py` `handle_issue_updated` | `new_state == in_progress` → `handle_status_start` | `new_state == to_analyse` → `handle_status_start` (при алиасе совпадает с `in_progress`) | AC-1, AC-17 |
|
||||
| `webhooks/plane.py` `start_pipeline` (успешный старт) | статус остаётся `In Progress` | в конце старта орк ставит `set_issue_analysis` | AC-3 |
|
||||
| `webhooks/plane.py` `handle_status_start` (resume-ветка) | relaunch агента стадии | при relaunch орк ставит `set_issue_analysis`; fork «старт vs resume» (`get_task_by_plane_id` + `has_active_job_for_task`) — **без изменений** | AC-2, AC-4 |
|
||||
| `webhooks/plane.py` `_rollback_stage` (reject@analysis, ~583) | `set_issue_in_progress` | `set_issue_analysis` | AC-3 |
|
||||
| `stage_engine.py` `_handle_analysis_approved_flow` (artifacts ready) | `set_issue_in_review` | **без изменений** (BR-9) | AC-13 |
|
||||
| `stage_engine.py` `_handle_analysis_approved_flow` (questions) | `set_issue_needs_input` | **без изменений** (BR-10) | AC-14 |
|
||||
| `stage_engine.py` rollback@analysis (architect conflict, ~669) | `set_issue_in_progress` | `set_issue_analysis` | AC-3 |
|
||||
| `stage_engine.py` `_handle_self_deploy_phase_a` (~1012) | `set_issue_in_review` | `set_issue_awaiting_deploy` | AC-6, AC-13 |
|
||||
| `stage_engine.py` `_handle_self_deploy_phase_b` (после `INITIATED` marker) | статус не меняет | `set_issue_deploying` | AC-7 |
|
||||
| `stage_engine.py` terminal-sync `deploy → done` (~338) | `set_issue_done` для всех | **self (`post_deploy_applies`):** `set_issue_monitoring`; **не-self:** `set_issue_done` как сейчас | AC-8, AC-9 |
|
||||
| `stage_engine.py` `run_post_deploy_monitor` HEALTHY+окно закрыто (~1260) | статус не трогает | `set_issue_done` (явно) | AC-10 |
|
||||
| `stage_engine.py` `run_post_deploy_monitor` DEGRADED (~1273) | alert/log | `set_issue_blocked` (+ существующий ALERT_ONLY) | AC-11 |
|
||||
|
||||
**Разводка terminal-sync (детально, AC-8/AC-9).** Текущий код безусловно зовёт
|
||||
`set_issue_done` на `next_stage == "done"`, затем (для self) армит post-deploy monitor.
|
||||
Разводим по `post_deploy.post_deploy_applies(repo)`:
|
||||
|
||||
```python
|
||||
if next_stage == "done" and work_item_id:
|
||||
if post_deploy.post_deploy_applies(repo):
|
||||
set_issue_monitoring(work_item_id) # self: окно наблюдения, НЕ Done сразу
|
||||
else:
|
||||
set_issue_done(work_item_id) # не-self: терминальный Done как сейчас
|
||||
# арм монитора (существующий блок ~361) — без изменений
|
||||
```
|
||||
Финальный `Done`/`Blocked` для self-hosting перекладывается на `run_post_deploy_monitor`.
|
||||
При деградированном алиасе `monitoring==done` self-hosting показывает `Done` и затем
|
||||
монитор держит `Done`/флипает `Blocked` — поведение идентично сегодняшнему.
|
||||
|
||||
**AC-12 (инвариант ORCH-021):** добавление `set_issue_blocked` в DEGRADED-ветку —
|
||||
**только индикация**; тик по-прежнему НИКОГДА не рестартит/откатывает прод-контейнер
|
||||
(self-hosting остаётся `ALERT_ONLY`). `set_issue_blocked` — Plane-PATCH, не действие над
|
||||
контейнером.
|
||||
|
||||
**Cancelled (AC-15):** изменений кода НЕ требует. `handle_issue_updated` реагирует только
|
||||
на `to_analyse`/`approved`/`rejected`; `Cancelled` падает в `else` → «no pipeline action».
|
||||
Орк не делает advance/rollback — индикация, не управление. Критерий выполнен существующим
|
||||
кодом.
|
||||
|
||||
### 2.6. Reconciler (`src/reconciler.py`)
|
||||
|
||||
- **F-2 `_reconcile_plane_project`:** заменить триггер `in_progress` → `to_analyse` в
|
||||
списке запрашиваемых статусов (`list_issues_by_state([to_analyse, approved, rejected])`)
|
||||
и в `_reconcile_plane_issue` маршрутизировать `new_state == to_analyse` →
|
||||
`handle_status_start`. При алиасе `to_analyse == in_progress` (enduro) поведение
|
||||
идентично текущему (один UUID; `list_issues_by_state` дедуплицирует через `set`). AC-19.
|
||||
- **Guard 2 `_is_blocked_or_needs_input`:** расширить skip-множество активными ожиданиями
|
||||
`awaiting_deploy`/`deploying`/`monitoring` (BR-13, AC-20). **Анти-регресс enduro
|
||||
(КРИТИЧНО):** новые ключи алиасятся на `in_review`/`in_progress`/`done`; добавить их в
|
||||
skip «как есть» → на enduro `In Progress`/`Done`-задачи начнут ошибочно пропускаться
|
||||
F-1 (регресс ORCH-053/060). Поэтому активные ожидания включаются в skip **только когда
|
||||
они РАЗЛИЧНЫ от базовых рабочих статусов проекта** (т.е. реально созданы):
|
||||
|
||||
```python
|
||||
base_working = {states.get(k) for k in (
|
||||
"backlog","todo","in_progress","in_review","review",
|
||||
"architecture","development","testing","approved","rejected","done")}
|
||||
extra_waits = {states.get("awaiting_deploy"),
|
||||
states.get("deploying"),
|
||||
states.get("monitoring")} - base_working - {None}
|
||||
skip_set = {states.get("blocked"), states.get("needs_input")} | extra_waits
|
||||
return cur in skip_set
|
||||
```
|
||||
Enduro (алиасы схлопываются в base) → `extra_waits == {}` → нулевой регресс. Orchestrator
|
||||
(отдельные UUID) → три реальных статуса в skip → BR-13. Семантику метода обобщаем до
|
||||
«human-or-active-wait»; флаг `reconcile_skip_blocked_enabled` продолжает гасить этот
|
||||
networked-чек. F-1 и так структурно не оживляет эти состояния (Phase A: `check_deploy_status`
|
||||
red → silent; Deploying: active finalizer job → active-job guard; Monitoring: стадия
|
||||
`done` → не итерируется) — Guard 2 это defense-in-depth по требованию Owner.
|
||||
|
||||
### 2.7. Без kill-switch
|
||||
|
||||
Отдельный env-флаг новой модели **не вводится**. Раскат естественно гейтится
|
||||
**инфра-предусловием**: пока оператор не создал новые статусы — alias-fallback (§2.2)
|
||||
держит строго прежнее поведение; создал — резолв по имени включает новую модель. Это
|
||||
проще отдельного флага и соответствует принципу «минимум зависимостей». (ТЗ §6 допускает
|
||||
флаг как опциональный — сознательно отказываемся.)
|
||||
|
||||
---
|
||||
|
||||
## 3. Затронутые модули (карта изменений)
|
||||
|
||||
| Модуль | Изменение |
|
||||
|--------|-----------|
|
||||
| `src/plane_sync.py` | `_PLANE_NAME_TO_KEY` +6; `_DEFAULT_STATES` +6 (enduro-alias UUID); `_STATE_ALIAS_FALLBACK` (новое) + применение в `get_project_states`; `_STAGE_TO_STATE_KEY` (analysis/review); `STAGE_VISIBILITY_STATE`; `STAGE_TO_STATE` (legacy); 5 новых `set_issue_*`. |
|
||||
| `src/webhooks/plane.py` | триггер `in_progress`→`to_analyse` в `handle_issue_updated`; `set_issue_analysis` в `start_pipeline` и resume-ветке `handle_status_start`; `_rollback_stage` reject@analysis → `set_issue_analysis`. |
|
||||
| `src/stage_engine.py` | Phase A → `set_issue_awaiting_deploy`; Phase B → `set_issue_deploying`; terminal-sync split (`monitoring` vs `done`); post-deploy monitor HEALTHY→`set_issue_done`, DEGRADED→`set_issue_blocked`; rollback@analysis (architect conflict) `set_issue_in_progress`→`set_issue_analysis`. |
|
||||
| `src/reconciler.py` | F-2 триггер `to_analyse`; Guard 2 skip-set + анти-регресс subtraction. |
|
||||
| `src/stages.py` | **НЕ трогаем** (инвариант слоя A). |
|
||||
| `src/config.py` | Без изменений (kill-switch не вводится). |
|
||||
|
||||
---
|
||||
|
||||
## 4. Инварианты (проверяемые, AC-21/AC-22)
|
||||
|
||||
- `src/stages.py` `STAGE_TRANSITIONS` — diff пуст (байт-в-байт).
|
||||
- `QG_CHECKS`, `check_deploy_status`/`_parse_deploy_status`, exit-коды хука (0/1/2),
|
||||
merge-gate, `check_branch_mergeable`/`check_staging_image_fresh`, схема БД — без изменений.
|
||||
- `Confirm Deploy` (ORCH-059), механизм `Needs Input` (analyst-only) — без изменений.
|
||||
- Новых HTTP-эндпоинтов нет; `GET /queue`/`GET /status` контракт без изменений.
|
||||
- Миграций БД нет (`tasks` не хранит Plane-статус; источник истины — стадия в БД + Plane API).
|
||||
- Все новые `set_issue_*` / резолв — never-raise.
|
||||
- Не-self (enduro) терминальный `deploy → Done` — без регресса.
|
||||
|
||||
---
|
||||
|
||||
## 5. Последствия
|
||||
|
||||
**Плюсы**
|
||||
- Доска читаема: каждый этап = осмысленный статус; человеческие входы визуально отделены
|
||||
от индикации.
|
||||
- `In Progress` разгружен: больше не «всё подряд».
|
||||
- Fail-closed усилен (project-relative): частичная конфигурация не ломает ни индикацию,
|
||||
ни конвейер.
|
||||
- Слой A нетронут → нулевой риск для машины стадий и гейтов всех проектов (self-hosting).
|
||||
- Нет нового флага/таблицы → меньше движущихся частей.
|
||||
|
||||
**Минусы / ограничения**
|
||||
- Требуется ручное инфра-действие оператора (создать 6 статусов в проекте ORCH) — до
|
||||
этого orchestrator деградирует до старой индикации (см. `07-infra-requirements.md`).
|
||||
- Статусы кэшируются per-process (`_STATES_CACHE`): после создания статусов нужен
|
||||
`reload_project_states()` или рестарт **staging** (не прод — см. self-hosting риск).
|
||||
- Guard-2 subtraction добавляет немного логики; покрывается тестами (enduro-алиас → пустой
|
||||
extra; orchestrator → три статуса).
|
||||
|
||||
**Self-hosting (⚠️):** изменения — слой B (Plane-индикация) + reconciler-гварды; машина
|
||||
стадий и контракты деплоя нетронуты. Выкладка ОБЯЗАТЕЛЬНО через `deploy-staging` (8501)
|
||||
до прод-деплоя орка. Прод-контейнер не рестартить в рамках задачи вне штатного staging-гейта.
|
||||
|
||||
---
|
||||
|
||||
## 6. Альтернативы (отклонены)
|
||||
|
||||
- **Статический enduro-UUID алиас (ТЗ §2.2 буквально):** ломается на частичной
|
||||
конфигурации orchestrator-проекта (чужой UUID → PATCH 422). Заменён project-relative
|
||||
alias-fallback (§2.2).
|
||||
- **Глобальный env kill-switch новой модели:** избыточен — инфра-предусловие уже даёт
|
||||
естественный гейт раската (§2.7).
|
||||
- **Хранить Plane-статус в `tasks` (миграция БД):** не нужно; источник истины — стадия +
|
||||
живой Plane API. Нарушило бы инвариант «без лишних зависимостей».
|
||||
- **Менять `STAGE_TRANSITIONS` ради новых статусов:** запрещено (инвариант слоя A);
|
||||
статусы — индикация, отделены от машины стадий.
|
||||
96
docs/work-items/ORCH-066/07-infra-requirements.md
Normal file
96
docs/work-items/ORCH-066/07-infra-requirements.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 07 — Требования к инфраструктуре
|
||||
|
||||
**Work Item:** ORCH-066
|
||||
**Автор:** Architect
|
||||
**Дата:** 2026-06-07
|
||||
|
||||
> ORCH-066 не меняет топологию (контейнеры/порты/сеть — без изменений, см.
|
||||
> `docs/operations/INFRA.md`). Единственное инфра-действие — создание новых
|
||||
> Plane-статусов в проекте **ORCH** руками оператора через Plane API. Это
|
||||
> **предусловие эксплуатации**, не часть кодового PR.
|
||||
|
||||
---
|
||||
|
||||
## 1. Что нужно сделать оператору (ДО эксплуатации новой модели)
|
||||
|
||||
Создать в Plane-проекте **ORCH** следующие статусы (states) с точными именами —
|
||||
резолвер сопоставляет их по `name` (`_PLANE_NAME_TO_KEY`):
|
||||
|
||||
| Plane name (точно) | Логический ключ | Группа Plane (рекомендуемая) | Назначение |
|
||||
|--------------------|-----------------|------------------------------|------------|
|
||||
| `To Analyse` | `to_analyse` | unstarted / started | Человеческий вход: старт конвейера + resume аналитика из Needs Input. |
|
||||
| `Analysis` | `analysis` | started | Индикация стадии анализа. |
|
||||
| `Code-Review` | `code_review` | started | Индикация стадии review. |
|
||||
| `Awaiting Deploy` | `awaiting_deploy` | started | Phase A: ожидание ручного approve на прод-деплой. |
|
||||
| `Deploying` | `deploying` | started | Phase B: идёт прод-деплой. |
|
||||
| `Monitoring after Deploy` | `monitoring` | started | Phase C / окно пост-деплой наблюдения. |
|
||||
|
||||
`Confirm Deploy` (ORCH-059) и базовые статусы (`Backlog`, `Todo`, `In Progress`,
|
||||
`Architecture`, `Development`, `Review`, `Testing`, `Approved`, `Rejected`, `Done`,
|
||||
`Cancelled`, `Needs Input`, `In Review`, `Blocked`) уже существуют — **не трогать**.
|
||||
|
||||
> ⚠️ **Точность имён критична.** Резолв идёт по строковому `name`. Опечатка/иной регистр
|
||||
> → статус не сопоставится → ключ деградирует на собственный базовый UUID проекта
|
||||
> (alias-fallback, ADR §2.2): индикация откатится к старому статусу, но конвейер
|
||||
> продолжит работать. Дефис в `Code-Review` — обязателен.
|
||||
|
||||
---
|
||||
|
||||
## 2. Plane API — как создать статус
|
||||
|
||||
Эндпоинт (как в `src/plane_sync.py`, `PLANE_BASE = {plane_api_url}/api/v1`):
|
||||
|
||||
```
|
||||
POST {PLANE_BASE}/workspaces/{WORKSPACE}/projects/{ORCH_PROJECT_ID}/states/
|
||||
Headers: X-API-Key: <PLANE_API_TOKEN> (или соответствующий бот-токен с правами)
|
||||
Body (JSON):
|
||||
{ "name": "To Analyse", "group": "started", "color": "#3f76ff" }
|
||||
```
|
||||
|
||||
Повторить для каждого имени из таблицы §1. `group` влияет только на колонку доски;
|
||||
оркестратор `group` не читает (резолв строго по `name`). `color` — на вкус оператора.
|
||||
|
||||
Проверка после создания:
|
||||
|
||||
```
|
||||
GET {PLANE_BASE}/workspaces/{WORKSPACE}/projects/{ORCH_PROJECT_ID}/states/
|
||||
```
|
||||
В ответе должны присутствовать все 6 имён.
|
||||
|
||||
---
|
||||
|
||||
## 3. Сброс кэша статусов (важно)
|
||||
|
||||
`get_project_states` кэширует резолв per-process (`_STATES_CACHE`). После создания
|
||||
статусов оркестратор подхватит их **только** после сброса кэша:
|
||||
|
||||
- штатно — `plane_sync.reload_project_states(project_id)` (или рестарт процесса);
|
||||
- на **staging** (8501) — безопасный рестарт песочницы;
|
||||
- на **прод** (8500) — **НЕ рестартить контейнер ради этого** в рамках задачи
|
||||
(self-hosting: общий контейнер всех проектов). Кэш заполняется при первом обращении к
|
||||
проекту; если статусы созданы ДО первого PATCH в цикле новой версии — отдельный сброс не
|
||||
нужен. Если созданы позже — дождаться штатного цикла обновления/деплоя орка.
|
||||
|
||||
---
|
||||
|
||||
## 4. Порядок раската (рекомендация)
|
||||
|
||||
1. Слить кодовый PR ORCH-066 через `deploy-staging` (8501).
|
||||
2. Создать 6 статусов в проекте ORCH (§1–§2).
|
||||
3. Сбросить кэш / поднять staging, прогнать sandbox-задачу — убедиться, что доска
|
||||
показывает `Analysis` / `Code-Review` / `Awaiting Deploy` / `Deploying` /
|
||||
`Monitoring after Deploy` / `Done` на соответствующих этапах.
|
||||
4. Прод-деплой орка штатным self-deploy (Phase A → approve → Phase B/C).
|
||||
|
||||
**До шага 2** система работает строго как до ORCH-066 (alias-fallback) — раскат
|
||||
безопасно обратим: не создавать/удалить статусы = откат индикации к старой модели,
|
||||
без изменения кода.
|
||||
|
||||
---
|
||||
|
||||
## 5. Что НЕ требуется
|
||||
|
||||
- Никаких изменений docker-compose, портов, сети, томов, `.env`/`.env.staging`.
|
||||
- Никаких миграций БД (`tasks` не хранит Plane-статус).
|
||||
- Никаких изменений в проекте **enduro-trails** — там новые статусы не создаются;
|
||||
alias-fallback держит прежнюю индикацию (`In Progress`/`Review`/`Done`).
|
||||
31
docs/work-items/ORCH-066/10-tech-risks.md
Normal file
31
docs/work-items/ORCH-066/10-tech-risks.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 10 — Технические риски
|
||||
|
||||
**Work Item:** ORCH-066
|
||||
**Автор:** Architect
|
||||
**Дата:** 2026-06-07
|
||||
|
||||
Риски слоя B (Plane-индикация). Слой A (`STAGE_TRANSITIONS`/гейты) не затрагивается, поэтому
|
||||
класс «сломали конвейер» структурно исключён — худший исход любого риска ниже = неверная
|
||||
**индикация**, не остановка конвейера.
|
||||
|
||||
| ID | Риск | Вероятность | Влияние | Митигация |
|
||||
|----|------|-------------|---------|-----------|
|
||||
| **R1** | Частичная конфигурация: оператор создал не все 6 статусов в ORCH → отсутствующий ключ деградирует. Наивный статический enduro-UUID дал бы невалидный `state` (PATCH 422) на orchestrator-issue. | Средняя | Средн. | **Project-relative alias-fallback** (ADR §2.2): отсутствующий ключ → собственный базовый UUID проекта → PATCH валиден, индикация откатывается к текущему статусу. Покрыть тестом partial-config. |
|
||||
| **R2** | Enduro-регресс через Guard 2: новые ключи алиасятся на `in_progress`/`in_review`/`done`; наивное добавление в skip-set заставит F-1 пропускать enduro `In Progress`/`Done` → сломанная реконсиляция (ORCH-053/060). | Средняя | Высок. | **Subtraction базовых рабочих статусов** (ADR §2.6): `extra_waits -= base_working`. На enduro (алиасы схлопнуты) `extra_waits == {}` → нулевой регресс. Тест: enduro-алиас не добавляет skip, orchestrator-distinct добавляет. |
|
||||
| **R3** | Двойной триггер старта: F-2 reconciler и webhook оба маршрутизируют `to_analyse`; при алиасе `to_analyse == in_progress` возможен повтор. | Низкая | Низк. | `list_issues_by_state` дедуплицирует UUID через `set`; active-job guard + atomic create-claim в `handle_status_start` (`get_task_by_plane_id` + `has_active_job_for_task`) — без двойного старта (AC-4). Сохранить fork как есть. |
|
||||
| **R4** | Кэш статусов: после создания статусов `_STATES_CACHE` отдаёт старый резолв до сброса → доска не обновляется. | Средняя | Низк. | `reload_project_states()` / рестарт **staging**. Документировано в `07-infra-requirements.md §3`. Прод-рестарт ради кэша — запрещён (self-hosting). |
|
||||
| **R5** | Опечатка в имени статуса оператором (`Code Review` без дефиса и т.п.) → ключ не резолвится. | Средняя | Низк. | Резолв по точному `name`; при промахе — alias-fallback (деградация, не падение). Точные имена и проверка в `07-infra-requirements.md §1–2`. |
|
||||
| **R6** | Terminal-sync split: ошибка ветвления `post_deploy_applies` → enduro получает `Monitoring after Deploy` вместо `Done` (регресс AC-9) или self уходит в `Done` минуя окно (AC-8). | Низкая | Средн. | Единый источник условности — `post_deploy.post_deploy_applies(repo)` (та же функция, что армит монитор). Тесты AC-8 (self→monitoring) и AC-9 (не-self→done). |
|
||||
| **R7** | Phase B: `set_issue_deploying` поставлен до фактического старта детача → ложная индикация при провале `initiate_deploy`. | Низкая | Низк. | Ставить `set_issue_deploying` **после** успешного `initiate_deploy` и записи `INITIATED` marker (ADR §2.5); провал `initiate_deploy` оставляет `Awaiting Deploy` + просьбу повторить approve. |
|
||||
| **R8** | Post-deploy DEGRADED → `set_issue_blocked` ошибочно трактуется как «действие над продом». | Низкая | Высок.(если) | `set_issue_blocked` — только Plane-PATCH. Тик остаётся `ALERT_ONLY`, НИКОГДА не рестартит/откатывает прод-контейнер (AC-12, ORCH-021 BR-5). Явный тест: self DEGRADED не трогает контейнер. |
|
||||
| **R9** | Plane API недоступен в момент простановки статуса → PATCH падает. | Низкая | Низк. | Все `set_issue_*`/`_set_issue_state_direct` — never-raise (логируют, не пробрасывают). Индикация пропускается, слой A не затронут. |
|
||||
| **R10** | Регресс на тестах, читающих `STAGE_TO_STATE`/`PLANE_STATES` конкретные UUID. | Низкая | Низк. | Новые ключи в `_DEFAULT_STATES` = алиасы на те же in_progress/review/done UUID → значения байт-в-байт; `STAGE_TO_STATE` analysis/review остаются прежними UUID (ADR §2.3). |
|
||||
| **R11** | Self-hosting: выкладка орка минуя staging. | Низкая | Высок. | Обязательный `deploy-staging` гейт (8501); прод не рестартить вне штатного self-deploy. Раскат обратим (не создавать статусы = старое поведение). |
|
||||
|
||||
## Сводный вывод
|
||||
|
||||
Все риски снижаемы в рамках принятой архитектуры; ни один не способен остановить конвейер
|
||||
(слой A инвариантен). Два ключевых требуют аккуратной реализации и обязательных тестов:
|
||||
**R1** (project-relative alias-fallback) и **R2** (Guard-2 anti-regress subtraction) —
|
||||
оба зафиксированы в ADR §2.2 и §2.6 как явные контракты. Эскалации `arch:major-change` не
|
||||
требуется: изменение локализовано в слое B, без новых компонентов/стадий/QG/миграций.
|
||||
89
docs/work-items/ORCH-066/12-review.md
Normal file
89
docs/work-items/ORCH-066/12-review.md
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-066
|
||||
verdict: APPROVED
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-066
|
||||
|
||||
## Summary
|
||||
Осмысленная статусная модель Plane (слой B — индикация). Реализация затрагивает
|
||||
строго слой B (`src/plane_sync.py`, точки простановки в `src/stage_engine.py` /
|
||||
`src/webhooks/plane.py` / `src/reconciler.py`) и **не трогает слой A**
|
||||
(`src/stages.py::STAGE_TRANSITIONS` — diff пуст). Все 4 оси проверки (ТЗ, ADR,
|
||||
качество кода, тесты) и проверка документации — пройдены. `pytest tests/ -q`:
|
||||
**774 passed**. Вердикт — **APPROVED**.
|
||||
|
||||
## Соответствие ТЗ (02-trz.md)
|
||||
- §2.1 — 6 новых логических ключей в `_PLANE_NAME_TO_KEY` + `_DEFAULT_STATES`. ✔
|
||||
- §2.2 — fail-closed резолюция (BR-12). ✔ (реализована усиленная project-relative
|
||||
версия — см. ADR ниже).
|
||||
- §2.3 — `_STAGE_TO_STATE_KEY` (analysis→analysis, review→code_review),
|
||||
`STAGE_VISIBILITY_STATE`, legacy `STAGE_TO_STATE` (UUID байт-в-байт прежние). ✔
|
||||
- §2.4 — точки простановки разведены (handle_issue_updated триггер `to_analyse`,
|
||||
start_pipeline/resume → Analysis, Phase A → Awaiting Deploy, Phase B → Deploying,
|
||||
terminal-sync split, post-deploy HEALTHY→Done / DEGRADED→Blocked,
|
||||
rollback@analysis → Analysis). ✔
|
||||
- §2.5 — 5 новых never-raise хелперов `set_issue_*`. ✔
|
||||
- §3 — reconciler F-2 триггер `to_analyse` (+ resume-ветка), Guard 2 skip-set с
|
||||
вычитанием base_working. ✔
|
||||
- §4/§5/§6 — нет новых эндпоинтов, нет миграций БД, `QG_CHECKS` не расширен. ✔
|
||||
|
||||
## Соответствие ADR (06-adr/ADR-001)
|
||||
- §2.2 project-relative alias-fallback (`_STATE_ALIAS_FALLBACK`, применён ДО
|
||||
`_DEFAULT_STATES.setdefault`) — реализован точно по контракту, деградация на
|
||||
собственный базовый UUID проекта, PATCH остаётся валидным на частичной
|
||||
конфигурации. ✔
|
||||
- §2.5 terminal-sync split по `post_deploy.post_deploy_applies(repo)` — реализован
|
||||
как в ADR (self → Monitoring, не-self → Done). ✔
|
||||
- §2.6 Guard 2 анти-регресс (extra_waits − base_working − {None}) — реализован
|
||||
дословно, enduro-алиасы схлопываются → нулевой регресс. ✔
|
||||
- §2.7 без kill-switch — config.py не изменён (diff пуст). ✔
|
||||
|
||||
## Качество кода
|
||||
- Все новые `set_issue_*` следуют образцу `set_issue_in_review` (per-project резолв
|
||||
+ `_set_issue_state_direct`), контракт never-raise сохранён, есть docstrings. ✔
|
||||
- Post-deploy/terminal-sync простановки обёрнуты в try/except с warning-логом
|
||||
(never break the tick). ✔
|
||||
- Переменные в scope корректны (`work_item_id` определён до всех новых вызовов в
|
||||
`start_pipeline`/`handle_status_start`/stage_engine). ✔
|
||||
- AC-12 соблюдён: `set_issue_blocked` в DEGRADED-ветке — только индикация, тик
|
||||
прод-контейнер не трогает. ✔
|
||||
|
||||
## Качество тестов
|
||||
- Содержательные, не тривиальные: `test_plane_status_failclosed.py`
|
||||
(TC-16/17/18 — partial project, API down, never-raise сеттеров, enduro alias
|
||||
старт), `test_plane_to_analyse_resume.py`, `test_plane_status_model.py`,
|
||||
`test_deploy_terminal_sync.py` (self/не-self split), `test_post_deploy_integration.py`,
|
||||
`test_reconciler*.py` (F-2 to_analyse + Guard 2). ✔
|
||||
|
||||
## Инварианты (AC-21/AC-22)
|
||||
- `src/stages.py` — diff 0 строк (STAGE_TRANSITIONS байт-в-байт). ✔
|
||||
- `src/qg/checks.py` — diff 0 строк (QG_CHECKS, check_deploy_status). ✔
|
||||
- `src/config.py` — diff 0 строк. ✔
|
||||
- Схема БД — без миграций. ✔
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- нет
|
||||
|
||||
### P1 — Must fix
|
||||
- нет
|
||||
|
||||
### P2 — Should fix
|
||||
- нет
|
||||
|
||||
## Документация
|
||||
Обновлена в том же PR (golden source соблюдён):
|
||||
- `CLAUDE.md` — добавлена секция «Статусная модель Plane (ORCH-066)». ✔
|
||||
- `docs/architecture/README.md` — секция «Осмысленная статусная модель Plane
|
||||
(ORCH-066)» + обновлён статусный footer. ✔
|
||||
- `CHANGELOG.md` — подробная запись в [Unreleased]/Added. ✔
|
||||
- `06-adr/ADR-001-plane-status-model.md` — заведён. ✔
|
||||
- `07-infra-requirements.md` — присутствует (инфра-предусловие: 6 Plane-статусов
|
||||
создаёт оператор). ✔
|
||||
|
||||
Изменения `src/` полностью отражены в документации → требование
|
||||
«документация обновлена при изменении src/» выполнено.
|
||||
77
docs/work-items/ORCH-066/13-test-report.md
Normal file
77
docs/work-items/ORCH-066/13-test-report.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-066
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-066
|
||||
|
||||
Осмысленная статусная модель Plane (слой B — индикация). Прогон полного регресса +
|
||||
покрытие тест-плана `04-test-plan.yaml` + проверка инвариантов слоя A.
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Ветка: feature/ORCH-066-plane
|
||||
- Дата: 2026-06-07
|
||||
|
||||
## Результаты по тест-плану (04-test-plan.yaml)
|
||||
|
||||
| TC ID | Покрывает | Описание | Модуль | Результат |
|
||||
|-------|-----------|----------|--------|-----------|
|
||||
| TC-01 | AC-1 | To Analyse без task → start_pipeline | test_status_trigger.py | PASS |
|
||||
| TC-02 | AC-2,BR-11 | To Analyse resume аналитика, без двойного task | test_plane_to_analyse_resume.py | PASS |
|
||||
| TC-03 | AC-3 | Старт/relaunch → статус Analysis | test_plane_status_model.py | PASS |
|
||||
| TC-04 | AC-4 | Busy-guard: active-job → не relaunch | test_plane_to_analyse_resume.py | PASS |
|
||||
| TC-05 | AC-5 | review → статус Code-Review | test_plane_status_model.py | PASS |
|
||||
| TC-06 | AC-6,AC-13 | Phase A → Awaiting Deploy (не In Review) | test_deploy_approve.py | PASS |
|
||||
| TC-07 | AC-7 | Phase B → Deploying | test_deploy_approve.py | PASS |
|
||||
| TC-08 | AC-8 | Phase C self → Monitoring after Deploy | test_deploy_terminal_sync.py | PASS |
|
||||
| TC-09 | AC-9 | Не-self deploy→done → Done (без регресса) | test_deploy_terminal_sync.py | PASS |
|
||||
| TC-10 | AC-10 | Post-deploy HEALTHY → Done | test_post_deploy.py | PASS |
|
||||
| TC-11 | AC-11 | Post-deploy DEGRADED → Blocked | test_post_deploy.py | PASS |
|
||||
| TC-12 | AC-12 | Self-тик не рестартит прод | test_post_deploy.py | PASS |
|
||||
| TC-13 | AC-13 | In Review только за approve-pending | test_analyst_status_only_regression.py | PASS |
|
||||
| TC-14 | AC-14,BR-10 | Needs Input без изменений | test_plane_status_model.py | PASS |
|
||||
| TC-15 | AC-15 | Cancelled → нет действий конвейера | test_plane_webhook.py | PASS |
|
||||
| TC-16 | AC-16,BR-12 | Fail-closed default-алиасы, нет исключений | test_plane_status_failclosed.py | PASS |
|
||||
| TC-17 | AC-16 | Plane API down → fallback, never-raise | test_plane_status_failclosed.py | PASS |
|
||||
| TC-18 | AC-17 | enduro In Progress стартует через алиас | test_plane_status_failclosed.py | PASS |
|
||||
| TC-19 | AC-18 | Резолв по имени → корректный UUID | test_orch10_states.py | PASS |
|
||||
| TC-20 | AC-19 | F-2 реконсилирует To Analyse | test_reconciler_plane.py | PASS |
|
||||
| TC-21 | AC-20,BR-13 | Guard 2 skip активных ожиданий | test_reconciler.py | PASS |
|
||||
| TC-22 | AC-21 | STAGE_TRANSITIONS не изменён | test_plane_status_model.py | PASS |
|
||||
| TC-23 | AC-22 | QG_CHECKS/check_deploy_status не изменены | test_plane_status_model.py | PASS |
|
||||
| TC-24 | AC-23 | Полный регресс pytest зелёный | tests/ | PASS |
|
||||
|
||||
Все 24 тест-кейса — PASS.
|
||||
|
||||
## Инварианты слоя A (AC-21 / AC-22)
|
||||
Diff против `origin/main` (merge-base `4815e378`):
|
||||
- `src/stages.py` (STAGE_TRANSITIONS) — diff пуст ✔
|
||||
- `src/qg/checks.py` (QG_CHECKS, check_deploy_status) — diff пуст ✔
|
||||
- `src/config.py` (без kill-switch) — diff пуст ✔
|
||||
|
||||
## Smoke test API (TestClient — прод-контейнер 8500 не трогался)
|
||||
> `curl` в окружении недоступен; smoke прогнан через FastAPI TestClient (lifespan),
|
||||
> без рестарта/обращения к прод-контейнеру (self-hosting safety).
|
||||
|
||||
| Endpoint | Статус | Тело (фрагмент) |
|
||||
|----------|--------|-----------------|
|
||||
| GET /health | 200 | `{"status":"ok","service":"orchestrator"}` |
|
||||
| GET /status | 200 | `{"active_tasks":[...]}` |
|
||||
| GET /queue | 200 | `{"counts":{...},"max_concurrency":1,...}` |
|
||||
|
||||
## Вывод pytest
|
||||
```
|
||||
======================= 774 passed, 1 warning in 17.68s ========================
|
||||
```
|
||||
(единственный warning — PydanticDeprecatedSince20 в src/config.py, предсуществующий,
|
||||
не связан с ORCH-066)
|
||||
|
||||
Прогон по модулям тест-плана: `117 passed` (ORCH-066-специфичные файлы).
|
||||
|
||||
## Итог
|
||||
PASS — все тесты зелёные (774 passed), все 24 TC покрыты, инварианты слоя A
|
||||
сохранены (diff пуст), smoke-эндпоинты отвечают 200. Review-вердикт APPROVED.
|
||||
Задача готова к переходу на стадию deploy-staging.
|
||||
12
docs/work-items/ORCH-066/14-deploy-log.md
Normal file
12
docs/work-items/ORCH-066/14-deploy-log.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
work_item: ORCH-066
|
||||
hook_exit_code: 0
|
||||
deployed_by: deploy-finalizer
|
||||
---
|
||||
|
||||
# Deploy log — ORCH-036 executable self-deploy
|
||||
|
||||
Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
|
||||
|
||||
Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.
|
||||
14
docs/work-items/ORCH-066/16-post-deploy-log.md
Normal file
14
docs/work-items/ORCH-066/16-post-deploy-log.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
post_deploy_status: HEALTHY
|
||||
action_taken: NONE
|
||||
work_item: ORCH-066
|
||||
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.
|
||||
Reference in New Issue
Block a user