orchestrator/docs/work-items/ORCH-068/12-review.md

type, work_item_id, verdict, version

type	work_item_id	verdict	version
review	ORCH-068	APPROVED	1

Review ORCH-068

Summary

Фикс livelock reconciler F-2 (спам _note_unblock по синхронизированной done-задаче после ORCH-066) реализован чисто и полностью по ТЗ/ADR. Два независимых слоя (D1 терминал-исключение по группе состояния + D2 подтверждённый state change) плюс TR-3 дедуп и TR-4 TTL кэша. Правки строго локальны в src/reconciler.py (F-2), src/plane_sync.py, src/config.py. Запрещённые ТЗ артефакты (STAGE_TRANSITIONS, QG_CHECKS, схема БД, контракты handle_*, F-1, F-3) не тронуты — diff не выходит за 3 файла src/. pytest tests/ -q — 764 passed.

Соответствие ТЗ

• TR-1 (исключить терминалы) ✅ — _is_terminal_state по state.group ∈ {completed, cancelled} с fallback на логические ключи done/cancelled; проверка per-issue (а не сужением wanted), что корректно для UUID-алиасинга.
• TR-2 (_note_unblock только при реальном change) ✅ — _stage_changed (сравнение стадии до/после _dispatch), для in_progress-старта подтверждение = задача появилась; контракты handle_* не менялись.
• TR-3 (дедуп) ✅ — in-memory guard {issue_id → state_uuid}, best-effort, сброс при рестарте (как unblocked_total).
• TR-4 (TTL кэша) ✅ — plane_states_ttl_s (дефолт 300, 0=lifetime), переиспользует reload_project_states; форма возврата get_project_states неизменна; при сбое перезапроса отдаётся stale-but-correct набор.

Соответствие ADR

ADR-001 (terminal-exclusion-and-cache-ttl) реализован 1:1: группа как primary-дискриминатор, allowlist-fallback, before/after-сравнение на стороне reconciler, TTL с инвалидацией через существующий примитив. Сквозной adr-0007 дополнен корректной ссылкой. Все инварианты INV-1…INV-7 сохранены (источник истины Plane, never-raise per-issue, kill-switch'и, F-1/F-3 нетронуты, self-hosting не рестартит прод).

Критерии приёмки

AC-1…AC-15 — все PASS. Покрытие тестами адресное: TC-01 (synced Done silence), TC-02 (aliased terminal по группе — ядро D1), TC-03 (Cancelled), TC-04 (no-op silence), TC-05 (дедуп), TC-06/TC-07 (легитимный unblock ×1), TC-08 (never-raise изоляция), TC-09 (kill-switch), TC-10 (enduro И orchestrator — headline-регресс), TC-11/TC-12 (TTL self-heal + back-compat + stale-on-failure).

Findings

P0 — Blocker

• нет

P1 — Must fix

• нет

P2 — Should fix

• нет

P3 — Nice-to-have

• Дедуп-guard ключуется по issue_id → state_uuid без сброса при смене состояния. Теоретический edge-case: задача legitимно проходит approved(uuid_X)→…→снова approved(тот же uuid_X) — повторное (но легитимное) уведомление будет подавлено. Функционального ущерба нет (advance выполняется в _dispatch независимо от нотификации), это потеря только уведомления, и D2 — основной гард. Best-effort по контракту ТЗ. Можно при желании чистить запись при детекте смены состояния away-and-back. Не блокирует.

Документация

Обновлена полно и в том же PR (AC-14 PASS):

• docs/architecture/README.md — компонент Plane Sync (TTL + {uuid→group}) и секция Reconciler/F-2/F-4 (терминал-исключение, дедуп, счётчики skipped_terminal_total/deduped_total); футер «обновлять при изменении» расширен записью ORCH-068.
• docs/architecture/adr/adr-0007-reconciler.md — добавлена кросс-ссылка на per-WI ADR.
• docs/work-items/ORCH-068/06-adr/ADR-001-… — детальный ADR (Accepted).
• CHANGELOG.md — запись ### Fixed (D1/D2/TR-3/TR-4, инварианты, тесты).
• .env.example — ORCH_PLANE_STATES_TTL_S=300 с комментарием.

Изменение src/ сопровождено соответствующим обновлением документации — требование golden-source выполнено.