# Аудит документации оркестратора — 2026-06-02

Проверка всех доков `orchestrator/docs/` + `README.md` + агентских промптов на старьё и неактуальность.

## Сводка

| Документ | Дата | Статус | Вердикт |
|----------|------|--------|---------|
| `README.md` | — | ⚠️ Частично устарел | Правка (QG-таблица врёт) |
| `docs/ARCHITECTURE.md` | 31.05 | ⚠️ Частично устарел | Правка (QG, docker-запись) |
| `docs/BACKLOG_PIPELINE.md` | 23.05 | ✅ Актуален | Оставить (открытые вопросы валидны) |
| `docs/BUGFIXES_2026-05-21.md` | 22.05 | ✅ Исторический | Оставить как есть (лог) |
| `docs/LESSONS_ET006.md` | 22.05 | 🔴 Критично актуален | Баг P1 НЕ починен — эскалировать |
| `docs/SETUP_WEBHOOKS.md` | 21.05 | ✅ Актуален | Оставить (инструкция рабочая) |

---

## 🔴 Главная находка: P1 zombie из ET-006 жив до сих пор

`LESSONS_ET006.md` (22 мая) раздел **P1. Zombie processes**:
> Monitor threads умирают при `docker compose up --build`, agent процессы остаются zombie.
> Daemon threads в Python не переживают restart, child processes (claude.exe) наследуются init.

**Это ТОЧНО тот же баг B-2 из моего аудита 02.06.** Предложены 3 решения (A: safe.directory, B: orphan recovery, C: tini). Применены только частично:
- ✅ Решение B (orphan recovery) — есть в `main.py`, но грубый (M-1)
- ✅ tini — есть в compose (`tini -s -- node`... но это для node, не для orchestrator-контейнера; **проверить**)
- 🔴 Корневой PIPE-deadlock + daemon-поток — НЕ устранён

**Вывод:** lessons-док зафиксировал баг 11 дней назад, но фикс не довели. Урок не выучен → повторился на ET-008 и ET-009. Это системная проблема: **lessons пишутся, но не конвертируются в задачи.**

Аналогично:
- **P2 stale reviews** — workaround «ручной re-approve», корня (отключить dismiss_stale_approvals) не сделали → ручник повторяется.
- **P3 Plane sync 404** — помечен LOW, до сих пор сломан (в моём аудите M-6).
- **P6 tester timeout** — actual на ET-009 (collector 25 мин).

---

## Постраничный разбор

### README.md — ⚠️ правка
**Устарело:**
- Таблица «Стадии пайплайна»: `development | developer | CI green` — на деле CI в Gitea нет, QG не отрабатывает. После фикса S-1 будет `local tests`.
- `review | reviewer | PR approved (no stale)` — но код использует `check_reviewer_verdict` (файловый), не `check_review_approved` (PR-based). **Расхождение код↔док.**
- Структура `src/` описана верно.

**Действие:** входит в Task 8 Dev-ТЗ (Dev обновит QG-таблицу).

### docs/ARCHITECTURE.md — ⚠️ правка
**Устарело:**
- Таблица QG: `check_review_approved` для review — но в `stages.py` стоит `check_reviewer_verdict`. Док отстал от кода.
- Не упоминает, что `.task` пишется через docker (и что это сломано).
- Описывает «идеальный» автономный pipeline, который из-за B-1/B-2 не работает.

**Действие:** Dev обновляет в Task 8. Добавить раздел «Известные ограничения».

### docs/BACKLOG_PIPELINE.md — ✅ актуален
BL-001 (аудит вне work item) и BL-002 (управление бэклогом) — открытые архитектурные вопросы, всё ещё валидны. BL-002 даже отмечает «Plane sync сломан» — подтверждает M-6.
**Действие:** оставить. Можно добавить отметку, что Plane sync — кандидат на фикс.

### docs/BUGFIXES_2026-05-21.md — ✅ исторический лог
5 багов ET-005, все помечены исправленными. Это лог-запись, трогать не надо. Полезен как история.
**Действие:** оставить как есть.

### docs/LESSONS_ET006.md — 🔴 критично актуален
См. выше. Документ ОТЛИЧНЫЙ по содержанию, но его выводы не реализованы.
**Действие:** НЕ удалять. Наоборот — использовать как доказательство, что фиксы назрели. После Dev-фиксов добавить пометку «P1 устранён в BUGFIXES_2026-06-02».

### docs/SETUP_WEBHOOKS.md — ✅ актуален
Инструкция по настройке webhook'ов Gitea/Plane. URL, события, секреты — соответствуют конфигу. Рабочий референс.
**Действие:** оставить.

---

## Расхождения код ↔ документация (для исправления)

| # | Док говорит | Код делает | Где править |
|---|-------------|-----------|-------------|
| 1 | review QG = `check_review_approved` | `check_reviewer_verdict` | README, ARCHITECTURE |
| 2 | development QG = CI green | CI нет, не работает | README, ARCHITECTURE (после S-1) |
| 3 | `.task` запись (не описано) | через docker (сломано) | ARCHITECTURE |
| 4 | pipeline автономен | ручной запуск из-за B-1/B-2 | ARCHITECTURE «Известные ограничения» |

---

## Рекомендации по процессу (мета)

1. **Lessons → задачи.** `LESSONS_ET006` зафиксировал баги, но их не конвертировали в трекаемые задачи → повтор на ET-008/009. Завести правило: каждый P0/P1 из lessons → задача в бэклоге с дедлайном.
2. **Один changelog фиксов.** `BUGFIXES_2026-05-21` + будущий `BUGFIXES_2026-06-02` — ок, но нужен сводный индекс «что починено / что висит».
3. **Doc-as-code QG.** В идеале — тест, проверяющий что таблица QG в README совпадает с `stages.py`. Чтобы доки не расходились с кодом.

---

*Аудитор: Стрим | Дата: 2026-06-02 | Связан с: AUDIT_2026-06-02.md, DEV_TASK_ORCHESTRATOR_FIXES.md*