141 lines
13 KiB
Markdown
141 lines
13 KiB
Markdown
---
|
||
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`, заполняет архитектор.)
|