From 7d1346d90f02a8a881f2712d2b916b77fed68a58 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 16:09:15 +0300 Subject: [PATCH] analyst(ET): auto-commit from analyst run_id=471 --- docs/work-items/ORCH-079/01-brd.md | 140 ++++++++++++++++++ docs/work-items/ORCH-079/02-trz.md | 128 ++++++++++++++++ .../ORCH-079/03-acceptance-criteria.md | 109 ++++++++++++++ docs/work-items/ORCH-079/04-test-plan.yaml | 56 +++++++ 4 files changed, 433 insertions(+) create mode 100644 docs/work-items/ORCH-079/01-brd.md create mode 100644 docs/work-items/ORCH-079/02-trz.md create mode 100644 docs/work-items/ORCH-079/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-079/04-test-plan.yaml diff --git a/docs/work-items/ORCH-079/01-brd.md b/docs/work-items/ORCH-079/01-brd.md new file mode 100644 index 0000000..97f3058 --- /dev/null +++ b/docs/work-items/ORCH-079/01-brd.md @@ -0,0 +1,140 @@ +--- +work_item: ORCH-079 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 01 — BRD (бизнес-требования): ORCH-079 — ORCH-52f: синхронизация README/доков с кодом + reviewer-гейт обзорных доков + +Work Item: **ORCH-079** · Repo: **orchestrator** · Стадия: analysis + +## 1. Бизнес-контекст и проблема + +ORCH-079 — **слой 5 (финал) эпика ORCH-52** «доки = golden source наравне с кодом». +Предыдущие слои привели в порядок *структуру* конвейерных доков (52b — `PIPELINE_DOCS.md`), +*машинный frontmatter-контракт* (52c — `src/frontmatter.py`), *канон промптов* (52d — ORCH-077) +и *стандарт трассировки* (52e — ORCH-078). Незакрытым остался **корневой `README.md` и +`docs/architecture/README.md`** — обзорная документация, которую читатель воспринимает как +«паспорт состояния проекта». + +**Установленный факт (проверено в `main`, `README.md`, секция «Известные ограничения», +строки 234–242):** + +1. **Битая нумерация** списка: `1, 2, 3, 4, 3, 4` — номера `3` и `4` повторяются дважды + (строки 238–242). Список визуально некорректен. +2. **Устаревшие пункты помечают РЕШЁННОЕ как открытое** — обзорный док лжёт о состоянии + системы. Подтверждено сверкой с кодом: + - п.1 «Single-task / shared `/repos` checkout … гонки при параллельных … исправление — + git worktree per task (S-4, отдельно)» → **РЕШЕНО**: `src/agents/launcher.py` импортирует + и использует `ensure_worktree` (git worktree per task), плюс serial-gate ORCH-088 и + зависимости задач ORCH-026 — оба в проде (см. `CLAUDE.md`, `docs/architecture/README.md`). + - п.3 «In-process daemon-потоки … целевое — очередь задач (F-2b)» → **РЕШЕНО**: персистентная + очередь `jobs` (ORCH-1, `src/queue_worker.py`), restart-safe; описана в самом `README.md` + («Очередь задач (ORCH-1 / F-2b)»). + - п.4 «Gitea CI не настроен — тесты гоняет сам оркестратор локально» → **УСТАРЕЛО**: гейт + стадии `development` — `check_ci_green` (`src/qg/checks.py:82`, реальные обращения к Gitea + status API с ретраями); `check_tests_local` помечен `DEPRECATED: replaced by check_ci_green` + (`src/qg/checks.py:381`). + - «No retry on API errors — httpx вызовы … без retry logic» → **УСТАРЕЛО**: queue-слой несёт + exp-backoff + circuit breaker (`ORCH_BACKOFF_*`, `ORCH_TRANSIENT_MAX_ATTEMPTS`, + `ORCH_BREAKER_*`, `src/queue_worker.py`), а `check_ci_green` содержит явный retry-loop + (`src/qg/checks.py:128–137`). + +Дополнительно отсутствует **процессный контроль**: когда PR решает один из пунктов «Известные +ограничения», ничто не заставляет автора снять/обновить соответствующий пункт README — поэтому +обзорные доки и копят рассинхрон. Reviewer сегодня обязан проверять обновление *конвейерной* +документации (`docs/architecture/README.md`, `internals.md`, env-таблица), но **обзорные** +разделы (README «Известные ограничения») в его правиле не названы явно. + +Боль: читатель (Owner, новый агент, внешний наблюдатель) принимает решения по неверной картине; +эпик 52 не может считаться закрытым, пока витрина проекта противоречит коду. + +## 2. Объём (scope) + +### В объёме +- Починка нумерации и содержимого секции **«Известные ограничения»** корневого `README.md`: + решённые пункты убрать/пометить закрытыми с явной ссылкой на ORCH-решение; оставить **только + реально открытые** ограничения (каждое — сверено с кодом/закрытыми задачами). +- Сверка остального содержимого `README.md` и **`docs/architecture/README.md`** с фактическим + кодом (стадии, гейты, модели/эффорты, env, компоненты) — устранение точечного рассинхрона. +- **Точечное** дополнение `.openclaw/agents/reviewer.md`: ось «Документация» должна явно покрывать + **обзорные доки** (README «Известные ограничения») — если PR решает пункт из «ограничений», + reviewer требует обновить README (finding). XML-канон 52d сохраняется (правка точечная, не + переписывание промпта). +- Обновление `CLAUDE.md` (при необходимости), `CHANGELOG.md`, ADR. + +### Вне объёма +- ❌ Любые изменения `src/**` (`STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД) — задача + чисто документная + одно точечное правило в промпте reviewer. +- ❌ Переписывание промпта reviewer целиком (52d уже зафиксировала канон) или иных 5 промптов. +- ❌ Изменение имён/регистра/значений machine-verdict ключей (`verdict:` и др.). +- ❌ Машинный enforcement reviewer-правила (новый QG/код-проверка) — правило остаётся + нормативно-описательным в промпте, как и ось трассировки ORCH-078. +- ❌ Массовая ревизия `docs/operations/**`, `internals.md` сверх обнаруженного рассинхрона + по стадиям/гейтам/моделям. + +## 3. Заинтересованные стороны +- **Заказчик / приёмка:** Owner (Слава) — BRD-гейт ручной; финал эпика 52. +- **Затрагиваются:** все агенты (читают `README.md` / `docs/architecture/README.md` как контекст); + reviewer (новое правило обзорных доков); будущие задачи (получают честную витрину состояния). +- **Источник истины:** код (`src/`) и закрытые ORCH-задачи — каждый снятый пункт обязан быть + подтверждён кодом/решением, «решено» не выдумывается. + +## 4. Бизнес-требования (BR) +- **BR-1** — Секция «Известные ограничения» корневого `README.md` имеет **последовательную + нумерацию** (без повторов `3`/`4`). +- **BR-2** — Каждый решённый пункт (single-task/worktree, daemon-потоки, Gitea CI, no-retry) + **убран или явно помечен закрытым** с указанием ORCH-решения, которым закрыт (worktree per task — + ORCH-026/088; очередь — ORCH-1; CI — `check_ci_green`; retry/breaker — ORCH-1 resilience). +- **BR-3** — Каждое **оставшееся** в списке ограничение **реально открыто** — подтверждено сверкой + с кодом/задачами; неподтверждённые/неверифицируемые пункты не остаются в формулировке «открыто». +- **BR-4** — `docs/architecture/README.md` **согласован с фактическим кодом** в части, затронутой + задачей: таблица стадий/гейтов, реестр `QG_CHECKS`, таблица моделей/эффортов, перечень + компонентов — без расхождений с `src/`. +- **BR-5** — `.openclaw/agents/reviewer.md` **обязывает** проверять обновление **обзорных** доков: + если PR решает пункт из README «Известные ограничения», отсутствие обновления README — **finding** + (ось «Документация»). XML-канон 52d (5 секций, формат «❌→✅», ``) сохранён. +- **BR-6** — `CLAUDE.md` (если затронуто), `CHANGELOG.md` и ADR (per-work-item `06-adr/` + + при необходимости сквозной) обновлены в том же PR. + +## 5. Нефункциональные требования (NFR) +- **NFR-1 (анти-регресс кода)** — `src/**` не изменяется; `STAGE_TRANSITIONS`, `QG_CHECKS`, + `check_*`, схема БД — байт-в-байт; полный регресс `pytest tests/` остаётся зелёным. +- **NFR-2 (сохранность machine-verdict контракта)** — в `reviewer.md` ключ `verdict:` и его + значения `APPROVED|REQUEST_CHANGES` — байт-в-байт; 6-польная frontmatter-схема 52c и 5 XML-секций + сохранены (структурные тесты `tests/test_agent_prompts_canon.py` зелёные). +- **NFR-3 (истинность)** — ни один пункт не объявляется «решённым» без подтверждения кодом или + закрытой ORCH-задачей; источник истины — код. +- **NFR-4 (минимальность правки промпта)** — дополнение reviewer.md точечное (врезка в существующую + ось «Документация»), без переписывания и без дрейфа канона. +- **NFR-5 (loading-model совместимость)** — правка `reviewer.md` вступает в силу на следующем + worktree от `main` без прод-рестарта (промпт `cat`-ается launcher'ом); рестарт прод-контейнера + не требуется (self-hosting, общий прод). + +## 6. Допущения и ограничения +- Self-hosting: прод-контейнер общий для всех проектов; задача — docs + промпт, прод НЕ + перезапускается ради неё (промпт подхватится со следующего worktree). +- Источник истины о «решённости» — текущий код в `main` и закрытые задачи (ORCH-1/026/088 и пр.), + а не память/устные договорённости. +- Пункты с неочевидным статусом (например, «Plane sync — маппинг issue ID», «Tester timeout — + Playwright e2e») требуют отдельной сверки: либо подтвердить, что реально открыты (оставить с + корректной формулировкой), либо переформулировать/убрать — решение принимается по коду, а не + переносится «как было». +- Лейбл `autoDeploy` на задаче: орк сам деплоит после staging; BRD-гейт ручной (Слава). + +## 7. Критерии успеха +Нумерация в «Известные ограничения» последовательна; решённые пункты сняты/помечены закрытыми с +ORCH-ссылкой; оставшиеся — реально открыты (сверено с кодом); `docs/architecture/README.md` +согласован с кодом; `reviewer.md` требует обновлять обзорные доки при решении пункта; `src/` не +тронут, verdict-ключи и XML-канон 52d сохранены, регресс зелёный; `CLAUDE.md`/`CHANGELOG`/ADR +обновлены. Детальные PASS/FAIL — в `03-acceptance-criteria.md`. + +## 8. Риски +- Ложное объявление «решено» для пункта, который частично открыт (напр. Plane sync) → митигировать + сверкой с кодом и сохранением реально открытых пунктов. +- Дрейф канона 52d при правке `reviewer.md` → митигировать точечной врезкой и структурными тестами. +- Случайное затрагивание verdict-ключа/схемы 52c → митигировать NFR-2 и `test_agent_prompts_canon`. +- (Детальный разбор — `10-tech-risks.md`, заполняет архитектор.) diff --git a/docs/work-items/ORCH-079/02-trz.md b/docs/work-items/ORCH-079/02-trz.md new file mode 100644 index 0000000..fec005f --- /dev/null +++ b/docs/work-items/ORCH-079/02-trz.md @@ -0,0 +1,128 @@ +--- +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` | **изменить** — точечная врезка про обзорные доки в ось «Документация» (`` ось 4 + ``) | +| `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 «Документация»** (``) и соответствующий пункт +`` дополняются явным требованием: **если 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. diff --git a/docs/work-items/ORCH-079/03-acceptance-criteria.md b/docs/work-items/ORCH-079/03-acceptance-criteria.md new file mode 100644 index 0000000..cb38a96 --- /dev/null +++ b/docs/work-items/ORCH-079/03-acceptance-criteria.md @@ -0,0 +1,109 @@ +--- +work_item: ORCH-079 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-079 — ORCH-52f: синхронизация README/доков с кодом + reviewer-гейт обзорных доков + +Work Item: **ORCH-079** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** +(что считается провалом). Reviewer/tester проверяет их буквально по файлам репозитория и коду. + +--- + +## AC-1 — Последовательная нумерация «Известные ограничения» + +**Условие:** Секция «Известные ограничения» в корневом `README.md` пронумерована сквозно без +повторов. +- **PASS:** номера в списке идут `1, 2, 3, …` строго по возрастанию без дубликатов; повторов `3`/`4` + (текущее `1,2,3,4,3,4`) нет. +- **FAIL:** есть повторяющиеся номера, пропуски или не-последовательная нумерация. + +--- + +## AC-2 — Решённые пункты сняты/помечены закрытыми с ORCH-ссылкой + +**Условие:** Четыре решённых/устаревших пункта (single-task/worktree, in-process daemon-потоки, +Gitea CI, no-retry) не присутствуют как **открытые** ограничения; если упомянуты — то как +закрытые, с указанием ORCH-решения. +- **PASS:** ни один из этих пунктов не стоит в списке открытых ограничений; для каждого упоминания + (если оставлено) указана закрывшая задача/механизм (worktree — ORCH-026/088; очередь — ORCH-1; + CI — `check_ci_green`; retry/breaker — ORCH-1 resilience). +- **FAIL:** хотя бы один из четырёх пунктов остался в формулировке «открыто/не настроено/в работе» + без пометки закрытия и без ORCH-ссылки. + +--- + +## AC-3 — Оставшиеся ограничения реально открыты (сверено с кодом) + +**Условие:** Каждый пункт, оставшийся в списке открытых ограничений, подтверждён открытым по коду +или закрытой/незакрытой задаче. +- **PASS:** для каждого оставшегося пункта в `02-trz.md`/`12-review.md` прослеживается подтверждение + открытости (ссылка на код/задачу); ни один открытый пункт не противоречит фактическому коду. +- **FAIL:** в списке открытых остаётся пункт, который по коду уже решён, либо пункт без какого-либо + подтверждения открытости. + +--- + +## AC-4 — `docs/architecture/README.md` согласован с кодом + +**Условие:** В части, затронутой задачей, `docs/architecture/README.md` не противоречит `src/`. +- **PASS:** таблица стадий/гейтов соответствует `STAGE_TRANSITIONS`; реестр `QG_CHECKS` + соответствует `src/qg/checks.py::QG_CHECKS`; таблица моделей/эффортов соответствует резолву + (`claude-opus-4-8`; developer=`xhigh`, tester/deployer=`medium`, прочие=`high`); перечень + компонентов соответствует модулям `src/`. +- **FAIL:** найдено хотя бы одно фактическое расхождение в перечисленных таблицах, оставшееся + непоправленным. + +--- + +## AC-5 — Reviewer требует обновлять обзорные доки (README limitations) + +**Условие:** `.openclaw/agents/reviewer.md` явно обязывает: при решении пункта из README «Известные +ограничения» необновление README — finding. +- **PASS:** в оси «Документация» (``) и/или `` `reviewer.md` присутствует явное + упоминание обзорных доков / README «Известные ограничения» с трактовкой «не обновлено → finding»; + формулировка в каноне 52d («❌→✅»). +- **FAIL:** правило отсутствует, упоминает только конвейерные доки, или внесено вне канона + (сломаны 5 XML-секций / формат запретов). + +--- + +## AC-6 — Анти-регресс: код не тронут, verdict-ключи и канон 52d сохранены, тесты зелёные + +**Условие:** Изменения не затрагивают рантайм; контракт reviewer сохранён; регресс зелёный. +- **PASS:** `git diff` не содержит изменений в `src/**` (особенно `STAGE_TRANSITIONS`, `QG_CHECKS`, + `check_*`, схема БД); в `reviewer.md` ключ `verdict:` и значения `APPROVED|REQUEST_CHANGES` — + байт-в-байт, 6 полей схемы 52c и 5 XML-секций на месте; `pytest tests/ -q` зелёный, включая + `tests/test_agent_prompts_canon.py` и `tests/test_agent_frontmatter_no_model.py`. +- **FAIL:** есть правка `src/**`; изменён `verdict:`/его значения; сломан XML-канон/схема 52c; + любой тест регресса красный. + +--- + +## AC-7 — `CLAUDE.md` / `CHANGELOG` / ADR обновлены + +**Условие:** Сопроводительная документация обновлена в том же PR. +- **PASS:** `CHANGELOG.md` содержит запись об ORCH-079 в `## [Unreleased]`; создан + `docs/work-items/ORCH-079/06-adr/ADR-001-*.md`; `CLAUDE.md` обновлён, если правило/финал эпика + его затрагивает (иначе — обоснованно не затронут). +- **FAIL:** отсутствует запись в `CHANGELOG.md`, либо нет ADR задачи, либо `CLAUDE.md` устарел + относительно внесённого правила. + +--- + +## Сводная матрица AC ↔ FR/BR +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1 / FR-1 | +| AC-2 | BR-2 / FR-2 | +| AC-3 | BR-3 / FR-2 | +| AC-4 | BR-4 / FR-3, FR-4 | +| AC-5 | BR-5 / FR-5 | +| AC-6 | NFR-1, NFR-2 / FR-6 | +| AC-7 | BR-6 | diff --git a/docs/work-items/ORCH-079/04-test-plan.yaml b/docs/work-items/ORCH-079/04-test-plan.yaml new file mode 100644 index 0000000..d34e5ad --- /dev/null +++ b/docs/work-items/ORCH-079/04-test-plan.yaml @@ -0,0 +1,56 @@ +work_item: ORCH-079 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +title: "ORCH-52f: синхронизация README/доков с кодом + reviewer-гейт обзорных доков" +framework: pytest +scope: > + Покрывается: структурная валидность секции README «Известные ограничения» (нумерация, + отсутствие решённых пунктов), наличие reviewer-правила про обзорные доки в каноне 52d, + анти-регресс machine-verdict ключей и схемы 52c, согласованность docs/architecture/README.md + с кодом по гейтам/моделям. Вне покрытия: рантайм-поведение (src/ не меняется), машинный + enforcement reviewer-правила (его нет — правило нормативно-описательное). +notes: > + Это docs + prompt-only задача — основной анти-регресс структурный (Markdown/промпт), а не + поведенческий. Новые проверки добавляются в tests/test_agent_prompts_canon.py (структурный + анти-дрейф промптов) и при необходимости в отдельный tests/test_readme_limitations.py. + Полный регресс pytest tests/ должен оставаться зелёным; src/ не тронут. + +tests: + - id: TC-01 + type: unit + description: "reviewer.md покрывает обзорные доки: содержит явное упоминание README «Известные ограничения» / обзорных доков в оси «Документация» (анти-дрейф правила FR-5/AC-5)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-02 + type: unit + description: "Анти-регресс reviewer machine-verdict: ключ `verdict:` и значения APPROVED|REQUEST_CHANGES присутствуют байт-в-байт (существующий test_machine_verdict_keys_preserved_exact_case остаётся зелёным, AC-6/NFR-2)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-03 + type: unit + description: "Анти-регресс канона 52d: reviewer.md (и все 6 промптов) сохраняют 5 обязательных XML-секций и 6 полей схемы 52c (существующие test_five_xml_sections_present / test_six_schema_field_names_present зелёные, AC-6)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-04 + type: unit + description: "frontmatter agent-промптов без мёртвого `model:` остаётся валидным (test_agent_frontmatter_no_model.py зелёный после правки reviewer.md, AC-6)." + module: tests/test_agent_frontmatter_no_model.py + expected: PASS + + - id: TC-05 + type: unit + description: "README «Известные ограничения»: нумерация строго последовательна без повторов (AC-1) и не содержит решённых пунктов как открытых — single-task/worktree, in-process daemon, Gitea CI, no-retry (AC-2). Реализуется как новый структурный тест README." + module: tests/test_readme_limitations.py + expected: PASS + + - id: TC-06 + type: integration + description: "Полный регресс pytest tests/ зелёный; git diff не содержит изменений в src/** (STAGE_TRANSITIONS/QG_CHECKS/check_*/схема БД) — проверяется ревьюером/тестером на стадии review/testing (AC-6/NFR-1)." + module: tests/ + expected: PASS