--- work_item: ORCH-079 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-09 model_used: claude-opus-4-8 --- # 01 — BRD (бизнес-требования): ORCH-079 — ORCH-52f: синхронизация README/доков с кодом + reviewer-гейт обзорных доков Work Item: **ORCH-079** · Repo: **orchestrator** · Стадия: analysis ## 1. Бизнес-контекст и проблема ORCH-079 — **слой 5 (финал) эпика ORCH-52** «доки = golden source наравне с кодом». Предыдущие слои привели в порядок *структуру* конвейерных доков (52b — `PIPELINE_DOCS.md`), *машинный frontmatter-контракт* (52c — `src/frontmatter.py`), *канон промптов* (52d — ORCH-077) и *стандарт трассировки* (52e — ORCH-078). Незакрытым остался **корневой `README.md` и `docs/architecture/README.md`** — обзорная документация, которую читатель воспринимает как «паспорт состояния проекта». **Установленный факт (проверено в `main`, `README.md`, секция «Известные ограничения», строки 234–242):** 1. **Битая нумерация** списка: `1, 2, 3, 4, 3, 4` — номера `3` и `4` повторяются дважды (строки 238–242). Список визуально некорректен. 2. **Устаревшие пункты помечают РЕШЁННОЕ как открытое** — обзорный док лжёт о состоянии системы. Подтверждено сверкой с кодом: - п.1 «Single-task / shared `/repos` checkout … гонки при параллельных … исправление — git worktree per task (S-4, отдельно)» → **РЕШЕНО**: `src/agents/launcher.py` импортирует и использует `ensure_worktree` (git worktree per task), плюс serial-gate ORCH-088 и зависимости задач ORCH-026 — оба в проде (см. `CLAUDE.md`, `docs/architecture/README.md`). - п.3 «In-process daemon-потоки … целевое — очередь задач (F-2b)» → **РЕШЕНО**: персистентная очередь `jobs` (ORCH-1, `src/queue_worker.py`), restart-safe; описана в самом `README.md` («Очередь задач (ORCH-1 / F-2b)»). - п.4 «Gitea CI не настроен — тесты гоняет сам оркестратор локально» → **УСТАРЕЛО**: гейт стадии `development` — `check_ci_green` (`src/qg/checks.py:82`, реальные обращения к Gitea status API с ретраями); `check_tests_local` помечен `DEPRECATED: replaced by check_ci_green` (`src/qg/checks.py:381`). - «No retry on API errors — httpx вызовы … без retry logic» → **УСТАРЕЛО**: queue-слой несёт exp-backoff + circuit breaker (`ORCH_BACKOFF_*`, `ORCH_TRANSIENT_MAX_ATTEMPTS`, `ORCH_BREAKER_*`, `src/queue_worker.py`), а `check_ci_green` содержит явный retry-loop (`src/qg/checks.py:128–137`). Дополнительно отсутствует **процессный контроль**: когда PR решает один из пунктов «Известные ограничения», ничто не заставляет автора снять/обновить соответствующий пункт README — поэтому обзорные доки и копят рассинхрон. Reviewer сегодня обязан проверять обновление *конвейерной* документации (`docs/architecture/README.md`, `internals.md`, env-таблица), но **обзорные** разделы (README «Известные ограничения») в его правиле не названы явно. Боль: читатель (Owner, новый агент, внешний наблюдатель) принимает решения по неверной картине; эпик 52 не может считаться закрытым, пока витрина проекта противоречит коду. ## 2. Объём (scope) ### В объёме - Починка нумерации и содержимого секции **«Известные ограничения»** корневого `README.md`: решённые пункты убрать/пометить закрытыми с явной ссылкой на ORCH-решение; оставить **только реально открытые** ограничения (каждое — сверено с кодом/закрытыми задачами). - Сверка остального содержимого `README.md` и **`docs/architecture/README.md`** с фактическим кодом (стадии, гейты, модели/эффорты, env, компоненты) — устранение точечного рассинхрона. - **Точечное** дополнение `.openclaw/agents/reviewer.md`: ось «Документация» должна явно покрывать **обзорные доки** (README «Известные ограничения») — если PR решает пункт из «ограничений», reviewer требует обновить README (finding). XML-канон 52d сохраняется (правка точечная, не переписывание промпта). - Обновление `CLAUDE.md` (при необходимости), `CHANGELOG.md`, ADR. ### Вне объёма - ❌ Любые изменения `src/**` (`STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД) — задача чисто документная + одно точечное правило в промпте reviewer. - ❌ Переписывание промпта reviewer целиком (52d уже зафиксировала канон) или иных 5 промптов. - ❌ Изменение имён/регистра/значений machine-verdict ключей (`verdict:` и др.). - ❌ Машинный enforcement reviewer-правила (новый QG/код-проверка) — правило остаётся нормативно-описательным в промпте, как и ось трассировки ORCH-078. - ❌ Массовая ревизия `docs/operations/**`, `internals.md` сверх обнаруженного рассинхрона по стадиям/гейтам/моделям. ## 3. Заинтересованные стороны - **Заказчик / приёмка:** Owner (Слава) — BRD-гейт ручной; финал эпика 52. - **Затрагиваются:** все агенты (читают `README.md` / `docs/architecture/README.md` как контекст); reviewer (новое правило обзорных доков); будущие задачи (получают честную витрину состояния). - **Источник истины:** код (`src/`) и закрытые ORCH-задачи — каждый снятый пункт обязан быть подтверждён кодом/решением, «решено» не выдумывается. ## 4. Бизнес-требования (BR) - **BR-1** — Секция «Известные ограничения» корневого `README.md` имеет **последовательную нумерацию** (без повторов `3`/`4`). - **BR-2** — Каждый решённый пункт (single-task/worktree, daemon-потоки, Gitea CI, no-retry) **убран или явно помечен закрытым** с указанием ORCH-решения, которым закрыт (worktree per task — ORCH-026/088; очередь — ORCH-1; CI — `check_ci_green`; retry/breaker — ORCH-1 resilience). - **BR-3** — Каждое **оставшееся** в списке ограничение **реально открыто** — подтверждено сверкой с кодом/задачами; неподтверждённые/неверифицируемые пункты не остаются в формулировке «открыто». - **BR-4** — `docs/architecture/README.md` **согласован с фактическим кодом** в части, затронутой задачей: таблица стадий/гейтов, реестр `QG_CHECKS`, таблица моделей/эффортов, перечень компонентов — без расхождений с `src/`. - **BR-5** — `.openclaw/agents/reviewer.md` **обязывает** проверять обновление **обзорных** доков: если PR решает пункт из README «Известные ограничения», отсутствие обновления README — **finding** (ось «Документация»). XML-канон 52d (5 секций, формат «❌→✅», ``) сохранён. - **BR-6** — `CLAUDE.md` (если затронуто), `CHANGELOG.md` и ADR (per-work-item `06-adr/` + при необходимости сквозной) обновлены в том же PR. ## 5. Нефункциональные требования (NFR) - **NFR-1 (анти-регресс кода)** — `src/**` не изменяется; `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД — байт-в-байт; полный регресс `pytest tests/` остаётся зелёным. - **NFR-2 (сохранность machine-verdict контракта)** — в `reviewer.md` ключ `verdict:` и его значения `APPROVED|REQUEST_CHANGES` — байт-в-байт; 6-польная frontmatter-схема 52c и 5 XML-секций сохранены (структурные тесты `tests/test_agent_prompts_canon.py` зелёные). - **NFR-3 (истинность)** — ни один пункт не объявляется «решённым» без подтверждения кодом или закрытой ORCH-задачей; источник истины — код. - **NFR-4 (минимальность правки промпта)** — дополнение reviewer.md точечное (врезка в существующую ось «Документация»), без переписывания и без дрейфа канона. - **NFR-5 (loading-model совместимость)** — правка `reviewer.md` вступает в силу на следующем worktree от `main` без прод-рестарта (промпт `cat`-ается launcher'ом); рестарт прод-контейнера не требуется (self-hosting, общий прод). ## 6. Допущения и ограничения - Self-hosting: прод-контейнер общий для всех проектов; задача — docs + промпт, прод НЕ перезапускается ради неё (промпт подхватится со следующего worktree). - Источник истины о «решённости» — текущий код в `main` и закрытые задачи (ORCH-1/026/088 и пр.), а не память/устные договорённости. - Пункты с неочевидным статусом (например, «Plane sync — маппинг issue ID», «Tester timeout — Playwright e2e») требуют отдельной сверки: либо подтвердить, что реально открыты (оставить с корректной формулировкой), либо переформулировать/убрать — решение принимается по коду, а не переносится «как было». - Лейбл `autoDeploy` на задаче: орк сам деплоит после staging; BRD-гейт ручной (Слава). ## 7. Критерии успеха Нумерация в «Известные ограничения» последовательна; решённые пункты сняты/помечены закрытыми с ORCH-ссылкой; оставшиеся — реально открыты (сверено с кодом); `docs/architecture/README.md` согласован с кодом; `reviewer.md` требует обновлять обзорные доки при решении пункта; `src/` не тронут, verdict-ключи и XML-канон 52d сохранены, регресс зелёный; `CLAUDE.md`/`CHANGELOG`/ADR обновлены. Детальные PASS/FAIL — в `03-acceptance-criteria.md`. ## 8. Риски - Ложное объявление «решено» для пункта, который частично открыт (напр. Plane sync) → митигировать сверкой с кодом и сохранением реально открытых пунктов. - Дрейф канона 52d при правке `reviewer.md` → митигировать точечной врезкой и структурными тестами. - Случайное затрагивание verdict-ключа/схемы 52c → митигировать NFR-2 и `test_agent_prompts_canon`. - (Детальный разбор — `10-tech-risks.md`, заполняет архитектор.)