orchestrator/docs/architecture/adr/adr-0023-overview-docs-reviewer-axis-and-epic52-close.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-079	architecture	architect	proposed	2026-06-09	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.