orchestrator/docs/work-items/ORCH-079/02-trz.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-079	analysis	analyst	ready-for-review	2026-06-09	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.