orchestrator/docs/work-items/ORCH-021/03-acceptance-criteria.md

Критерии приёмки — ORCH-021

Work Item: ORCH-021 Формат: каждый критерий имеет чёткое условие PASS/FAIL и проверяется тестом из 04-test-plan.yaml.

Наблюдение и сигналы

AC-1 — наблюдение армится после deploy→done

• PASS: для применимого репозитория после терминального перехода deploy → done пост-деплой наблюдение инициируется (создаётся sentinel/отложенный job/запись в watcher).
• FAIL: переход deploy → done не приводит к старту наблюдения.

AC-2 — наблюдение НЕ армится для неприменимых репо

• PASS: для репозитория вне области (не self-hosting и не в post_deploy_repos) post_deploy_applies(repo) → False; наблюдение не стартует; конвейер не меняется.
• FAIL: наблюдение стартует для неприменимого репо.

AC-3 — классификация HEALTHY

• PASS: серия опросов без провалов (или провалов меньше post_deploy_fail_threshold и доля 5xx ниже post_deploy_5xx_threshold) → вердикт HEALTHY.
• FAIL: при здоровых сигналах возвращается DEGRADED.

AC-4 — классификация DEGRADED по порогу провалов health

• PASS: ≥ post_deploy_fail_threshold ПОСЛЕДОВАТЕЛЬНЫХ провалов health → DEGRADED.
• FAIL: порог достигнут, но вердикт не DEGRADED.

AC-5 — классификация DEGRADED по доле 5xx

• PASS: доля 5xx на окне выше post_deploy_5xx_threshold → DEGRADED, даже если /health отвечает 200.
• FAIL: превышение порога 5xx не даёт DEGRADED.

AC-6 — устойчивость к разовому глюку (нет ложного срабатывания)

• PASS: одиночный провал (1 < post_deploy_fail_threshold) с последующим восстановлением → итог HEALTHY, реакции нет.
• FAIL: одиночный разовый провал приводит к DEGRADED/откату.

Реакция

AC-7 — авто-rollback для не-self репо при политике auto

• PASS: при post_deploy_auto_rollback=True и НЕ-self репо вердикт DEGRADED приводит к вызову отката (хук --rollback с прод-параметрами); action_taken фиксируется как ROLLBACK_OK/ROLLBACK_FAILED по exit-code.
• FAIL: откат не вызывается, либо вызывается с staging-дефолтами, либо роняет прод напрямую.

AC-8 — self-hosting НЕ откатывается автоматически (safety)

• PASS: для orchestrator вердикт DEGRADED НЕ приводит к автоматическому откату/рестарту прод-контейнера в тике наблюдения; вместо этого формируется громкий алерт + запрос ручного approve (action_taken: ALERT_ONLY).
• FAIL: тик наблюдения автоматически откатывает/рестартит прод-орк.

AC-9 — откат-провал эскалируется

• PASS: если откат вызван и вернул код 1/2 (нет prev-образа / откат тоже упал) → action_taken: ROLLBACK_FAILED + громкий Telegram-алерт о необходимости ручного вмешательства.
• FAIL: провал отката проглатывается тихо.

Конфигурация и совместимость

AC-10 — kill-switch выключает фичу

• PASS: post_deploy_monitor_enabled=False → наблюдение не армится ни для кого; поведение конвейера 1:1 как до ORCH-021.
• FAIL: при выключенном флаге наблюдение всё равно работает.

AC-11 — пороги/окно конфигурируемы через env

• PASS: post_deploy_window_s, post_deploy_interval_s, post_deploy_fail_threshold, post_deploy_5xx_threshold читаются из Settings (env ORCH_*) и влияют на поведение.
• FAIL: значения захардкожены.

AC-12 — реестры и схема БД не изменены

• PASS: STAGE_TRANSITIONS, QG_CHECKS, контракт check_deploy_status и схема таблиц БД не изменены (если архитектор не вводит явно новую стадию — тогда это отражено в ADR и тестах). Существующие тесты deploy/staging/merge-gate зелёные.
• FAIL: молча сломан какой-либо существующий контракт/тест.

Наблюдаемость, артефакт, идемпотентность

AC-13 — артефакт 16-post-deploy-log.md с машиночитаемым frontmatter

• PASS: по итогу наблюдения пишется 16-post-deploy-log.md с валидным YAML-frontmatter (post_deploy_status, action_taken); запись best-effort (её отсутствие ничего не роняет).
• FAIL: артефакт не пишется или frontmatter невалиден/непарсится.

AC-14 — наблюдаемость в /queue

• PASS: GET /queue содержит блок post_deploy со снимком состояния (enabled, window, активные/последний исход).
• FAIL: состояние наблюдения нигде не видно.

AC-15 — идемпотентность / restart-safe

• PASS: повторный арм для той же задачи (двойной webhook / рестарт оркестратора) не создаёт второе параллельное наблюдение и не теряет уже идущее.
• FAIL: дублируется наблюдение или теряется при рестарте.

AC-16 — never-raise

• PASS: любая ошибка опроса/сети/файлов/классификации логируется и НЕ роняет worker / lifespan / конвейер других проектов.
• FAIL: исключение из наблюдения всплывает и ломает обслуживание других проектов.

AC-17 — уведомления

• PASS: ключевые события (наблюдение начато, DEGRADED, откат/алерт, чистое завершение окна) уведомляются в Telegram и/или Plane-комментарием.
• FAIL: деградация/откат происходят молча.

AC-18 — документация обновлена (golden-source)

• PASS: в том же PR обновлены CLAUDE.md (артефакт 16-post-deploy-log.md), docs/architecture/README.md (описание пост-деплой наблюдения), CHANGELOG.md, и заведён ADR work-item.
• FAIL: функционал есть, документация не обновлена (reviewer → REQUEST_CHANGES).