---
work_item: ORCH-079
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-09
model_used: claude-opus-4-8
---

# adr-0023: Reviewer-ось «обзорные доки» (README-ограничения) + закрытие эпика ORCH-52

- **Статус:** proposed
- **Дата:** 2026-06-09
- **Источник:** ORCH-079 (эпик ORCH-52, слой 52f — обзорные доки, слой 5/финал)
- **Связи:** замыкает цепочку стандартов эпика 52 — adr-0019 (52b, `PIPELINE_DOCS.md`),
  adr-0020 (52c, frontmatter-контракт), adr-0021 (52d, канон промптов), adr-0022 (52e,
  трассировка маркеров). Детально — `docs/work-items/ORCH-079/06-adr/ADR-001-readme-sync-and-reviewer-overview-docs-axis.md`.

## Контекст

Эпик ORCH-52 строит сквозной контракт «документация = golden source наравне с кодом» слоями:
**52b** (adr-0019) — описательный стандарт документов + скелеты; **52c** (adr-0020) — машинный
frontmatter-контракт + `HANDOFF_PROTOCOL.md`; **52d** (adr-0021) — 6 промптов в каноне Anthropic +
добровольная эмиссия 52c-схемы; **52e** (adr-0022) — стандарт трассировки маркеров + reviewer-ось
«соответствие ADR». Закрыты слои структуры, машинного вердикта, формы промптов и трассировки кода —
но **обзорная витрина проекта (корневой `README.md`) не охвачена**.

Факты, сверенные с кодом `main`:
- Секция `README.md` «Известные ограничения» (`:236–241`) имеет битую нумерацию (`1,2,3,4,3,4`) и
  **выдаёт решённое за открытое**: worktree-гонки (закрыто `ensure_worktree` + ORCH-026/088),
  in-process daemon (закрыто очередью ORCH-1), «Gitea CI не настроен» (опровергнуто `check_ci_green`,
  `src/qg/checks.py:82`), «no retry» (опровергнуто backoff/breaker в `queue_worker.py`), плюс
  устаревшие issue-ID (зрелый `plane_sync` ORCH-010/066/068) и Playwright-timeout (неприменим к
  pytest-сервису; реальный механизм — watchdog ORCH-7).
- **Процессный пробел:** reviewer (ось «Документация») проверяет обновление *конвейерных* доков, но
  **обзорные** разделы (README «Известные ограничения») в правиле не названы → витрина копит
  рассинхрон, т.к. закрытие ограничения не обязывает автора снять пункт.

## Решение

Закрыть слой 5 (финал) эпика 52: **синхронизировать обзорные доки с кодом по факту** и добавить
reviewer'у **нормативную под-ось «обзорные доки»** (по образцу оси трассировки 52e). Это **docs +
prompt-only**, нулевое касание кода; правило — описательно-нормативное, **не машинный гейт**.

1. **Reviewer-ось «обзорные доки» (cross-cutting).** В `.openclaw/agents/reviewer.md` ось 4
   «Документация» + `<constraints>` несут точечную врезку «❌→✅»: *PR закрыл пункт README «Известные
   ограничения», README не обновлён → finding*. Severity **≥ P1**; при закрытии ограничения правкой
   `src/` без обновления README — совпадает с существующим **P0** «`src/` изменён, доки не обновлены».
   Канон 52d (5 секций, формат запретов, `<thinking>`), 6 полей схемы 52c и ключ
   `verdict: APPROVED|REQUEST_CHANGES` — байт-в-байт.
2. **Витрина приведена к коду (NFR-3).** Все 6 устаревших пунктов сняты/перенесены в «Закрыто
   (история)» с ORCH-ссылками; в «открытых» остаются ТОЛЬКО реально открытые, верифицированные
   кодом/задачей; нумерация сквозная. Запрет на изобретение ограничений (только уже
   задокументированные known-limitations — анти-scope-creep).
3. **Точечная сверка** `README.md` / `docs/architecture/README.md` с `src/` (стадии/`QG_CHECKS`/
   модели-эффорты/компоненты), минимально инвазивно.
4. **Анти-регресс машинно:** расширение `tests/test_agent_prompts_canon.py` (tests-only) — assert
   присутствия оси обзорных доков; проверки 52d и `test_agent_frontmatter_no_model.py` зелёные.

**Границы:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, `_parse_*`, `src/frontmatter.py`,
схема БД — **не трогаются**. `frontmatter_validation_strict` остаётся `False`; новый QG не вводится.

### Эпик ORCH-52 — закрыт (карта слоёв)

| Слой | Задача | Глобальный ADR | Артефакт |
|------|--------|----------------|----------|
| 52b — структура доков | ORCH-075 | adr-0019 | `docs/_standards/PIPELINE_DOCS.md` + `_templates/` |
| 52c — машинный frontmatter | ORCH-076 | adr-0020 | `src/frontmatter.py` + `HANDOFF_PROTOCOL.md` |
| 52d — канон промптов | ORCH-077 | adr-0021 | 6 промптов `.openclaw/agents/*.md` |
| 52e — трассировка маркеров | ORCH-078 | adr-0022 | `docs/_standards/TRACEABILITY.md` |
| **52f — обзорные доки** (финал) | **ORCH-079** | **adr-0023** | `README.md` + reviewer-ось |

## Альтернативы
- **Машинный enforcement (новый QG «README актуален»).** Отвергнуто: вне scope; для self-hosting
  ложный fail валит конвейер всех проектов; правило остаётся нормативным, как 52e. Enforcement —
  возможная будущая задача (как hard-fail схемы 52c).
- **Отдельный `docs/_standards/` для правила обзорных доков.** Отвергнуто: одно правило, один
  артефакт (README) — врезки в промпт достаточно; новый стандарт-файл избыточен.
- **Только per-work-item ADR.** Отвергнуто: рвёт цепочку эпика 52 (52b–e имеют глобальный ADR); нет
  явной точки «эпик 52 закрыт».

## Последствия
- **+** Витрина проекта честна; самоподдерживающаяся синхронность (reviewer-ось).
- **+** Эпик 52 формально закрыт сквозным ADR — единая точка входа для будущих агентов.
- **+** Self-hosting без рестарта: промпт `cat`-ается из worktree → правило с следующего worktree
  от `main` без рестарта 8500.
- **+** Полная обратимость: чисто текстовое изменение, нет миграций/состояния/kill-switch.
- **−** Правило нормативно, не enforced машинно → дисциплина + ревью (осознанный компромисс).
- **−** Рост `reviewer.md` на короткую врезку (митигейшн: точечность, без переписывания).
- **Откат:** `git revert` PR — доки/промпт/тест откатываются, поведение кода/гейтов идентично.

## Связи
- Замыкает: adr-0019 (52b), adr-0020 (52c), adr-0021 (52d), adr-0022 (52e).
- Per-work-item: `docs/work-items/ORCH-079/06-adr/ADR-001-readme-sync-and-reviewer-overview-docs-axis.md`.
- Сверено по коду: `src/agents/launcher.py` (`ensure_worktree`, `_resolve_timeout`),
  `src/queue_worker.py` (backoff/breaker), `src/qg/checks.py:82,381`, `src/plane_sync.py:451,541`,
  `README.md:236–241`, `.openclaw/agents/reviewer.md`, `tests/test_agent_prompts_canon.py`.
</content>
