--- work_item: ORCH-079 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-09 model_used: claude-opus-4-8 --- # 02 — ТЗ (TRZ): ORCH-079 — ORCH-52f: синхронизация README/доков с кодом + reviewer-гейт обзорных доков Work Item: **ORCH-079** · Repo: **orchestrator** · Стадия: analysis > ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода. > Архитектурное обоснование/решения — задача архитектора (`06-adr/`). Это **docs + prompt-only** > изменение: `src/**` не трогается. ## 1. Сводка изменения Три блока правок, все вне `src/`: 1. **`README.md`** — починить нумерацию секции «Известные ограничения»; снять/пометить закрытыми решённые пункты с явной ORCH-ссылкой; оставить только реально открытые ограничения; точечно сверить остальной текст (стадии/гейты/env) с кодом. 2. **`docs/architecture/README.md`** — сверить таблицу стадий/гейтов, реестр `QG_CHECKS`, таблицу моделей/эффортов и перечень компонентов с фактическим `src/`; устранить найденный рассинхрон. 3. **`.openclaw/agents/reviewer.md`** — точечно расширить ось «Документация»: обзорные доки (README «Известные ограничения») включаются в обязательную проверку; решение пункта без обновления README → finding. XML-канон 52d и `verdict:`-контракт сохраняются. Плюс сопроводительные: `CLAUDE.md` (при необходимости), `CHANGELOG.md`, ADR, структурный тест. ## 2. Задействованные модули / пути | Путь | Действие | |------|----------| | `README.md` | **изменить** — секция «Известные ограничения» (нумерация + содержимое); точечная сверка стадий/env | | `docs/architecture/README.md` | **изменить** — сверить стадии/гейты/`QG_CHECKS`/модели/компоненты с кодом | | `.openclaw/agents/reviewer.md` | **изменить** — точечная врезка про обзорные доки в ось «Документация» (`` ось 4 + ``) | | `CLAUDE.md` | **изменить** (при необходимости) — упоминание правила обзорных доков / финала эпика 52 | | `CHANGELOG.md` | **изменить** — запись в `## [Unreleased]` (merge=union по `.gitattributes`) | | `docs/work-items/ORCH-079/06-adr/ADR-001-*.md` | **создать** — решение «синхронизация README + reviewer-правило обзорных доков» | | `docs/architecture/adr/adr-00NN-*.md` | **создать** (на усмотрение архитектора) — сквозной ADR, замыкающий эпик 52 | | `tests/test_agent_prompts_canon.py` | **изменить** — добавить структурный assert «reviewer.md покрывает обзорные доки/README-ограничения» (анти-регресс правила) | | Только для чтения (сверка, НЕ менять): `src/stages.py`, `src/qg/checks.py`, `src/queue_worker.py`, `src/agents/launcher.py`, `src/config.py` | сверка истины | > Точные источники истины для сверки (read-only): `src/stages.py::STAGE_TRANSITIONS`, > `src/qg/checks.py::QG_CHECKS` + `check_ci_green` (стр. 82) + `check_tests_local` DEPRECATED > (стр. 379–381), `src/queue_worker.py` (backoff/breaker), `src/agents/launcher.py` (`ensure_worktree`, > `resolve_agent_model`/`resolve_agent_effort`). ## 3. Функциональные требования ### FR-1 — Починка нумерации «Известные ограничения» (BR-1) В `README.md` секция «Известные ограничения» обязана иметь **строго последовательную** нумерацию `1, 2, 3, …` без повторов. Текущее состояние `1,2,3,4,3,4` (строки 236–242) исправляется как часть переработки содержимого (FR-2): после удаления/пометки решённых пунктов список перенумеровывается сквозно. ### FR-2 — Снятие/пометка решённых пунктов с ORCH-ссылкой (BR-2, BR-3, NFR-3) Для каждого пункта определить статус **по коду** и применить действие: | Текущий пункт | Статус | Подтверждение в коде/задаче | Действие | |---------------|--------|------------------------------|----------| | Single-task / shared `/repos` checkout (worktree S-4) | РЕШЕНО | `launcher.py` `ensure_worktree` (worktree per task) + serial-gate ORCH-088 + deps ORCH-026 | убрать из «открытых»; при желании — строка «Закрыто: ORCH-026/088» | | In-process daemon-потоки (целевое — очередь F-2b) | РЕШЕНО | `src/queue_worker.py`, таблица `jobs`, restart-safe (ORCH-1) | убрать; при желании — «Закрыто: ORCH-1» | | Gitea CI не настроен | УСТАРЕЛО | `check_ci_green` (`qg/checks.py:82`) — активный гейт `development`; `check_tests_local` `DEPRECATED` | убрать | | No retry on API errors | УСТАРЕЛО | `queue_worker.py` exp-backoff + breaker (`ORCH_BACKOFF_*`/`ORCH_BREAKER_*`/`ORCH_TRANSIENT_MAX_ATTEMPTS`); retry-loop в `check_ci_green` | убрать | | Plane sync — маппинг issue ID (P3, в работе) | СВЕРИТЬ | `src/plane_sync.py` после ORCH-066/068 | подтвердить открытость по коду → оставить с корректной формулировкой ИЛИ снять/переформулировать | | Tester timeout — Playwright e2e >25 мин | СВЕРИТЬ | watchdog 30 мин (`launcher`); Playwright для orchestrator неактуален | подтвердить → оставить/переформулировать; не оставлять как «открыто» без основания | **Контракт FR-2:** ни один пункт не помечается решённым без подтверждения кодом/задачей (NFR-3); оставшиеся в списке — только реально открытые (BR-3). Допустимы оба формата снятия: полное удаление ИЛИ перенос в строку «Закрыто (ORCH-NNN)» — на усмотрение исполнителя, лишь бы открытыми остались только открытые. ### FR-3 — Сверка `README.md` с кодом (точечно) (BR-4) Сверить и при расхождении поправить: блок «Стадии пайплайна» (таблица стадий/гейтов/триггеров), таблицу env-переменных (наличие описанных флагов в `src/config.py`), описание очереди. Минимально инвазивно — править только подтверждённые расхождения. ### FR-4 — Сверка `docs/architecture/README.md` с кодом (BR-4) Сверить с фактическим `src/`: - таблица «Стадия → Агент → Quality Gate → Артефакт» ↔ `STAGE_TRANSITIONS`; - реестр `QG_CHECKS` ↔ `src/qg/checks.py::QG_CHECKS` (полный список ключей); - таблица «Модель и эффорт по ролям» ↔ `resolve_agent_model`/`resolve_agent_effort` (все 6 ролей, `claude-opus-4-8`; эффорты developer=`xhigh`, tester/deployer=`medium`, прочие=`high`); - перечень компонентов ↔ реально присутствующие модули `src/`. Расхождения — устранить; совпадающее — не трогать. ### FR-5 — Reviewer покрывает обзорные доки (BR-5, NFR-2, NFR-4) В `.openclaw/agents/reviewer.md` **ось 4 «Документация»** (``) и соответствующий пункт `` дополняются явным требованием: **если PR решает пункт из README «Известные ограничения» (обзорные доки), reviewer обязан проверить, что README обновлён; необновление → finding.** Severity: рекомендуется ≥ P1 (по образцу оси трассировки ORCH-078); при изменении `src/`, закрывающем ограничение, без обновления README — согласуется с существующим P0 «`src/` изменён, документация не обновлена». Формулировка — в формате «❌ X → ✅ Y» (канон 52d), точечно, без переписывания промпта. `verdict:`/значения, 6 полей схемы 52c, 5 XML-секций — без изменений. ### FR-6 — Анти-регресс правила структурным тестом (BR-5, NFR-1) В `tests/test_agent_prompts_canon.py` добавить assert: `reviewer.md` содержит маркер покрытия обзорных доков / README-ограничений (напр. подстрока «Известные ограничения» или «README» в контексте оси «Документация»). Тест фиксирует наличие правила (анти-дрейф), как существующие `test_reviewer_carries_traceability_control_axis` и `test_machine_verdict_keys_preserved_exact_case`. ## 4. Изменения API Нет. Эндпоинты (`/health`, `/status`, `/queue`, `/webhook/*`) не затрагиваются. ## 5. Изменения схемы БД Нет. Таблицы/миграции/индексы не затрагиваются. ## 6. Требования к новым/изменённым QG checks Нет. `QG_CHECKS`, `check_*`, `STAGE_TRANSITIONS`, `_parse_*` — без изменений (NFR-1). Reviewer-правило обзорных доков — **нормативно-описательное** в промпте (как ось трассировки ORCH-078), машинный enforcement не вводится. ## 7. Совместимость / регресс - **Обратная совместимость:** изменения — только Markdown-доки + один промпт + один тест; runtime-код не затронут → нулевая функциональная регрессия для всех проектов (enduro-trails не задет). - **machine-verdict контракт:** `verdict: APPROVED|REQUEST_CHANGES` в `reviewer.md` — байт-в-байт; 6 полей схемы 52c и 5 XML-секций сохранены → гейт `check_reviewer_verdict` читает вердикт как прежде. Структурные тесты `test_agent_prompts_canon.py` остаются зелёными (+ новый assert FR-6). - **Loading-model / self-hosting:** новый `reviewer.md` подхватывается launcher'ом (`cat` `.openclaw/agents/reviewer.md`) на следующем worktree от `main` — **прод НЕ перезапускается**. - **Артефакты pipeline:** задача создаёт/обновляет `docs/work-items/ORCH-079/01..04`, `06-adr/`, `12-review.md`, `13-test-report.md`, `14/15-*` по ходу конвейера; обновляет `README.md`, `docs/architecture/README.md`, `CLAUDE.md`, `CHANGELOG.md`. Обновлять только doc-артефакты — чужие work item не трогать. - **Обратимость:** kill-switch не требуется (нет рантайм-поведения); откат = revert PR.