# Блок 2. Конвейер: стадии, гейты, маршруты

> Источник истины — карта переходов `STAGE_TRANSITIONS` в `src/stages.py` и реестр гейтов
> `QG_CHECKS` в `src/qg/checks.py`; перечень ниже сверяется с кодом структурным тестом
> (`tests/test_system_docs.py`). Норматив структуры доков конвейера —
> [PIPELINE_DOCS](../_standards/PIPELINE_DOCS.md).

## Схема конвейера

```
created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
                          ↑                          │
                          └──── REQUEST_CHANGES ─────┘   (откат на доработку, max 3)
```

Плюс системный сток **`cancelled`** — терминальное состояние отменённой задачи (кнопка STOP,
см. ниже). Это не ребро конвейера, а равноправный `done` сток: попасть в него можно с любой
стадии, выйти — нельзя.

## Стадии и гейты выхода

Гейт выхода (exit-гейт) — машинная проверка, без которой задача не покидает стадию:

| Стадия | Кто работает | Гейт выхода (имя в реестре) | Что проверяет |
|--------|--------------|------------------------------|----------------|
| `created` | — | — | вход конвейера (вебхук Plane) |
| `analysis` | analyst | `check_analysis_approved` | пакет аналитики полон И постановка одобрена человеком |
| `architecture` | architect | `check_architecture_done` | ADR / инфра-требования зафиксированы |
| `development` | developer | `check_ci_green` | CI на ветке задачи зелёный |
| `review` | reviewer | `check_reviewer_verdict` | машинный вердикт ревью: APPROVED |
| `testing` | tester | `check_tests_passed` | машинный вердикт тестера: PASS |
| `deploy-staging` | deployer | `check_staging_status` | репетиция выкладки на песочнице успешна |
| `deploy` | deployer / finalizer | `check_deploy_status` | прод-выкладка реально успешна |
| `done` | — | — | терминал |
| `cancelled` | — | — | терминал (сток отмены) |

## Под-гейты деплойного ребра — врезки, не стадии

На переходе `deploy-staging → deploy` исполняются четыре под-гейта в нормативном порядке
(security → merge → coverage → image-freshness):

1. `check_security_gate` — секреты/зависимости, вердикт из security-отчёта;
2. `check_branch_mergeable` — merge-gate: ветка догнана до свежего `main` (под merge-lease)
   и мержабельна;
3. `check_coverage_gate` — покрытие тестами не ниже базовой линии/порога (baseline-ratchet);
4. `check_staging_image_fresh` — staging-образ собран из актуального кода.

Это **врезки в переход, а не стадии**: они не появляются в карте `STAGE_TRANSITIONS`, а
исполняются stage engine'ом внутри ребра. Провал любого из них — откат на доработку. На ребре
`deploy → done` аналогичная врезка merge-verify подтверждает, что код задачи реально слит в
`main` (слияние — только через PR-API Gitea, см. [интеграции](tech-integrations.md)).

## Откаты

`REQUEST_CHANGES` от ревьюера, проваленные тесты или красный под-гейт возвращают задачу на
стадию разработки с дословным перечнем замечаний. Лимит — 3 попытки подряд, дальше задача
останавливается и требует человека (анти-петля).

## Человеческие гейты и их снятие авто-лейблами

В штатном прогоне человек принимает ровно два решения:

- **Одобрение постановки** (на `analysis`): перевод задачи в статус Approved пропускает её
  дальше;
- **Подтверждение прод-выкладки** (на `deploy`): отдельный статус **Confirm Deploy** — чтобы
  привычный «approve» не выкатывал прод случайным кликом.

Оба решения можно снять декларативно — лейблами **autoApprove** / **autoDeploy** на задаче
(пакетный авто-режим). Снимается только ожидание человеческого сигнала: ни одна техническая
проверка не пропускается, autoDeploy физически не может выкатить непрошедшее под-гейты.

## Багфикс-маршрут

Задача с меткой **Bug** едет коротким путём: облегчённая аналитика (но полный пакет
документов) и пропуск стадии `architecture` — из аналитики сразу в разработку. Срезается
только аналитика/проектирование: **все гейты исполняются без изменений**. Сложный баг
эскалируется обратно в полный цикл.

## Последовательность внутри репозитория (serial gate)

Новая задача репозитория не входит в работу, пока не завершена более ранняя (FIFO): ветка
каждой задачи срезается от свежего `main`, уже содержащего код предшественника. Деградация
прода после выкладки замораживает репозиторий (freeze) до ручного разбора — следующие задачи
ждут.

## Отмена: STOP → `cancelled`

Перевод задачи в статус **STOP** останавливает агента, снимает job'ы с очереди, удаляет
рабочую ветку и worktree и переводит задачу в `cancelled`. Если задача в необратимой фазе
(идёт слияние/выкладка) — отмена откладывается и применяется после честного завершения шага.
STOP никогда не трогает `main` и прод-контейнер.

## Статусная модель Plane: индикация ≠ управление

Статусы в Plane — слой **индикации**: они показывают человеку осмысленную картину хода задачи,
но никогда не управляют конвейером (машина стадий — только `STAGE_TRANSITIONS`). Управляющих
статусов ровно три: запуск в работу, Approved/Confirm Deploy (человеческие гейты) и STOP
(отмена). Полная карта статусов — в [инженерном справочнике](../architecture/README.md).

---

*Кто работает на каждой стадии и что сдаёт — [агенты](tech-agents.md); как гейты читают
вердикты — [качество и безопасность](tech-quality-security.md).*