129 lines
12 KiB
Markdown
129 lines
12 KiB
Markdown
---
|
||
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.
|