94 lines
7.0 KiB
Markdown
94 lines
7.0 KiB
Markdown
# Аудит документации оркестратора — 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*
|