orchestrator/docs/work-items/ORCH-079/01-brd.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-079	analysis	analyst	ready-for-review	2026-06-09	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, заполняет архитектор.)