---
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 секций, формат «❌→✅», `<thinking>`) сохранён.
- **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`, заполняет архитектор.)
