---
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` | **изменить** — точечная врезка про обзорные доки в ось «Документация» (`<task>` ось 4 + `<constraints>`) |
| `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 «Документация»** (`<task>`) и соответствующий пункт
`<constraints>` дополняются явным требованием: **если 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.
