diff --git a/docs/work-items/ORCH-078/01-brd.md b/docs/work-items/ORCH-078/01-brd.md new file mode 100644 index 0000000..e7fe1c3 --- /dev/null +++ b/docs/work-items/ORCH-078/01-brd.md @@ -0,0 +1,142 @@ +--- +work_item: ORCH-078 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 01 — BRD (бизнес-требования): ORCH-078 — ORCH-52e: трассировка ORCH-NNN (маркеры-стандарт + правило чтения) + +Work Item: **ORCH-078** · Repo: **orchestrator** (self-hosting) · Стадия: analysis + +## 1. Бизнес-контекст и проблема + +Эпик **ORCH-52** формализует «golden source» документации конвейера слоями: +- **52b** (ORCH-075) — стандарт структуры документов `docs/_standards/PIPELINE_DOCS.md` + скелеты `docs/_templates/`. +- **52c** (ORCH-076) — машинный frontmatter-контракт `src/frontmatter.py` + спека handoff `docs/_standards/HANDOFF_PROTOCOL.md`. +- **52d** (ORCH-077) — 6 системных промптов переписаны в каноне Anthropic + эмиссия 52c-схемы. + +**52e — слой 4 (трассировка).** В коде `src/` де-факто живёт **51 уникальный маркер** `ORCH-NNN` +(проверено `grep -rhoE 'ORCH-[0-9]+' src/ | sort -u | wc -l`), привязывающий нетривиальные строки/ +инварианты к work item, который их ввёл (напр. `src/serial_gate.py` несёт `t2.id < jobs.task_id` +с маркером ORCH-088; `src/merge_gate.py` — ORCH-043/065/071/073). Это **сложившаяся практика без +формального стандарта**: `docs/_standards/` содержит только `PIPELINE_DOCS.md` и +`HANDOFF_PROTOCOL.md` — стандарта маркеров-трассировки НЕТ. + +**Боль, которую закрывает 52e:** +1. **Нет правила чтения.** Агент (developer/architect), правя маркированную строку, не обязан + прочитать ADR work item, который её ввёл, → риск молча сломать зафиксированный инвариант + (класс ошибки «фантомный merge», постмортем `docs/history/LESSONS_2026-06-08_phantom-merge.md`, + из-за которого появились ORCH-071/073). Маркер должен означать «здесь есть зафиксированное + решение — прочти его прежде, чем менять». +2. **Reviewer не проверяет соблюдение.** Reviewer-промпт проверяет ADR-соответствие *текущей* + задачи, но не контролирует, что правка чужого маркированного кода свелась с его ADR. +3. **Анти-археология.** Файлы с высокой плотностью маркеров (`config.py`=60, `stage_engine.py`=55, + `launcher.py`=49, `plane_sync.py`=47, `merge_gate.py`=26 вхождений) превращают понимание блока + в раскопки по 4+ work item. Нужна конвенция: блок с 3+ маркерами ссылается на **один сквозной + ADR** (`docs/architecture/adr/`) вместо перечисления всех. +4. **Доступ к чужому work item.** Папка `docs/work-items/ORCH-NNN/06-adr/` может отсутствовать в + текущей ветке (срезана от `main` без неё) — нужен задокументированный fallback + `git show origin/main:docs/work-items/ORCH-NNN/06-adr/...`. + +**⚠️ Что УЖЕ сделано в 52d (анти-дубль, проверено в `main`):** промпты `developer.md`/`architect.md` +упоминают `ORCH-NNN`/`06-adr`, но **только** как (а) ADR *текущей* задачи («реализуй по `06-adr/`»), +(б) именование веток `feature/ORCH-NNN-slug`, (в) поля frontmatter-схемы. **Правила «правишь +маркированный код → читай его ADR перед изменением» среди них НЕТ** (проверено +`grep -nE 'ORCH-NNN|06-adr|маркер'`). Поэтому 52e **не переписывает промпты** и **не дублирует** +52d — он добавляет именно отсутствующее правило, точечно, сохраняя XML-канон 52d. + +## 2. Объём (scope) + +### В объёме +- Формальный **стандарт маркеров-трассировки** `docs/_standards/TRACEABILITY.md`: что такое маркер, + формат, где ставится, как читать историю (с реальным примером из кода), fallback-доступ, + анти-археология. +- **Правило чтения** «правишь код с маркером `ORCH-NNN` → прочитай его `06-adr` ПЕРЕД правкой, не + сломай инвариант» — точечно добавить в `developer.md` и `architect.md` (где 52d его не покрыла). +- **Контроль соблюдения** — точечно добавить в `reviewer.md` ось «правка маркированного кода + сверена с его ADR». +- **Fallback-доступ** `git show origin/main:docs/work-items/ORCH-NNN/...` — задокументировать в + стандарте и в developer-промпте. +- **Анти-археология** «3+ маркеров в блоке → сводная ссылка на сквозной ADR» — зафиксировать в + стандарте и в architect/reviewer-промптах. +- Обновление `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`; анти-регресс-тест промптов. + +### Вне объёма +- **Массовый ретро-фит маркеров** в существующий код (≥51 маркер уже есть — не трогаем; стандарт + действует «на будущее»). +- **Любое изменение `src/**`**, в т.ч. гейтов, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, + `_parse_*`, схемы БД. +- **Полная перезапись промптов** — 52d уже дал канон; 52e лишь точечно дополняет. +- Включение `frontmatter_validation_strict` / любого enforcement. + +## 3. Заинтересованные стороны +- **Owner (Слава)** — заказчик эпика ORCH-52; ручной BRD-гейт (Approved) этой задачи. Лейбл + `autoDeploy` (орк сам деплоит после staging), BRD-гейт — ручной. +- **Агенты developer/architect** — потребители правила чтения (получают защиту от слома инвариантов). +- **Агент reviewer** — получает явную ось контроля соблюдения трассировки. +- **Self-hosting** — промпты `cat`-аются из worktree в момент запуска → правило вступает в силу на + следующем worktree от `main` без прод-рестарта (групповой риск не возникает). + +## 4. Бизнес-требования (BR) + +- **BR-1** — В `docs/_standards/` создан формальный стандарт маркеров-трассировки (`TRACEABILITY.md`): + определение маркера `ORCH-NNN`, формат, правило размещения (рядом с нетривиальным инвариантом, не + на тривиальном коде), способ чтения истории — с **реальным, проверяемым примером из кода** + (маркер в `src/` → конкретный `docs/work-items/ORCH-NNN/06-adr/...`). +- **BR-2** — Правило «правишь код с маркером `ORCH-NNN` → прочитай `docs/work-items/ORCH-NNN/06-adr` + ПЕРЕД изменением, не сломай инвариант» присутствует в `developer.md` и `architect.md`. Если 52d + частично покрыла смежное — **ссылаться/усилить, не повторять** (BR-5). +- **BR-3** — Reviewer-промпт **проверяет соблюдение** правила: правка чужого маркированного кода без + сверки с его ADR / со сломом инварианта → finding с severity. +- **BR-4** — Задокументирован fallback-доступ к чужому work item: + `git show origin/main:docs/work-items/ORCH-NNN/06-adr/...` (когда папки нет в текущей ветке). +- **BR-5** — Анти-археология: конвенция «функция/блок несёт 3+ маркеров → сводная ссылка на сквозной + ADR (`docs/architecture/adr/`) вместо раскопок по каждому» зафиксирована в стандарте. +- **BR-6 (АНТИ-ДУБЛЬ)** — 52e НЕ дублирует уже сделанное 52d. Там, где 52d уже задаёт смежное + поведение, 52e ссылается/усиливает. XML-структура 52d (5 секций) и эмиссия 52c-схемы сохраняются. +- **BR-7** — Сопутствующая документация обновлена: `CLAUDE.md` (правила для агентов), `docs/ + architecture/README.md` (упоминание стандарта как слоя 4 эпика 52), `CHANGELOG.md`; архитектор + заводит ADR. + +## 5. Нефункциональные требования (NFR) + +- **NFR-1 (нулевое касание кода)** — Изменяются ТОЛЬКО `docs/**` и `.openclaw/agents/*.md` + (+ структурный тест промптов в `tests/`). `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, + `_parse_*`, схема БД — **не трогаются**. +- **NFR-2 (анти-регресс промптов, как 52d)** — Не потеряны: 5 обязательных XML-секций + (``/``/``/``/``), 6 полей 52c-схемы, + и machine-verdict ключи **байт-в-байт** (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/ + `security_status:` с точным регистром и наборами значений). Существующие + `tests/test_agent_prompts_canon.py` и `tests/test_agent_frontmatter_no_model.py` остаются + зелёными; полный `pytest tests/ -q` зелёный. +- **NFR-3 (только на будущее)** — Стандарт описательно-нормативный для нового/изменяемого кода; + существующие 51 маркер не переразмечаются. +- **NFR-4 (self-hosting, без рестарта)** — Промпт `cat`-ается из git-worktree агента в момент + запуска → правка вступает в силу на следующем worktree от `main` без прод-рестарта контейнера + `orchestrator` (8500). +- **NFR-5 (обратимость)** — Чисто текстовое изменение: `git revert` PR полностью откатывает; нет + миграций/состояния/kill-switch (нечего гейтить — поведение кода идентично). + +## 6. Допущения и ограничения +- Промпты 52d в `main` — стабильная база; 52e накладывается на неё (XML-канон не меняем). +- Стандарт `PIPELINE_DOCS.md`/`HANDOFF_PROTOCOL.md` — соседи нового `TRACEABILITY.md` в + `docs/_standards/`; формат и тон выдерживаются в том же стиле. +- Реальный пример в стандарте ссылается на существующие в `main` файл `src/` + ADR (проверяемость). +- Архитектурное обоснование (нужен ли сквозной ADR, точные формулировки правок промптов) — + зона архитектора (`06-adr`), не аналитика. + +## 7. Критерии успеха +Создан стандарт маркеров с реальным примером; правило чтения есть в developer/architect, reviewer +его проверяет; fallback-доступ и анти-археология задокументированы; 52d не продублирована; код не +изменён, анти-регресс промптов держится, регресс зелёный; доки обновлены. Детальные PASS/FAIL — +`03-acceptance-criteria.md`. + +## 8. Риски +- **Дублирование 52d** (правило уже частично есть) → митигируется явной сверкой (см. §1, BR-6) и + ссылками вместо повтора. +- **Расползание в ретро-фит** (соблазн расставить маркеры по коду) → жёсткая граница «вне объёма». +- **Регресс промптов** (потеря verdict-ключа/запрета при точечной правке) → анти-регресс-тест (NFR-2). +- Детальный разбор технических рисков — `10-tech-risks.md` (заполняет архитектор). diff --git a/docs/work-items/ORCH-078/02-trz.md b/docs/work-items/ORCH-078/02-trz.md new file mode 100644 index 0000000..60254ac --- /dev/null +++ b/docs/work-items/ORCH-078/02-trz.md @@ -0,0 +1,156 @@ +--- +work_item: ORCH-078 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 02 — ТЗ (TRZ): ORCH-078 — ORCH-52e: трассировка ORCH-NNN (маркеры-стандарт + правило чтения) + +Work Item: **ORCH-078** · Repo: **orchestrator** (self-hosting) · Стадия: analysis + +> ТЗ описывает **конкретные изменения** (выведенные из BRD и фактического содержимого репозитория). +> Архитектурное обоснование (нужен ли сквозной ADR, точные формулировки врезок в промпты, форма +> стандарта) — задача архитектора (`06-adr`). Это **docs + prompts-only** задача: `src/**` не меняется. + +## 1. Сводка изменения + +Ввести формальный стандарт маркеров-трассировки `docs/_standards/TRACEABILITY.md` и **точечно** +(не переписывая) дополнить 3 системных промпта правилом чтения ADR перед правкой маркированного +кода (developer/architect) и контролем его соблюдения (reviewer). Задокументировать fallback-доступ +к чужому work item и анти-археологию (3+ маркеров → сводный сквозной ADR). Сопутствующе обновить +`CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`; расширить структурный анти-регресс-тест +промптов. **Существующие 51 маркер в `src/` не переразмечаются.** + +## 2. Задействованные модули / пути + +| Путь | Действие | +|------|----------| +| `docs/_standards/TRACEABILITY.md` | **создать** (новый стандарт; см. FR-1) | +| `.openclaw/agents/developer.md` | **точечно дополнить** — правило чтения + fallback-доступ (FR-2, FR-5); ссылка на стандарт | +| `.openclaw/agents/architect.md` | **точечно дополнить** — правило чтения + анти-археология (FR-3, FR-6); ссылка на стандарт | +| `.openclaw/agents/reviewer.md` | **точечно дополнить** — ось контроля соблюдения трассировки (FR-4); ссылка на стандарт | +| `CLAUDE.md` | обновить — раздел «Правила для агентов» / «Конвенции»: правило трассировки + ссылка на `TRACEABILITY.md` (FR-7) | +| `docs/architecture/README.md` | обновить — упоминание стандарта как слоя 4 эпика 52 (FR-7) | +| `CHANGELOG.md` | добавить запись `## [Unreleased]` | +| `tests/test_agent_prompts_canon.py` | **расширить** (tests-only) — анти-регресс reading-rule маркеров (FR-8); НЕ трогает `src/` | +| `docs/work-items/ORCH-078/06-adr/ADR-001-*.md` | создать (архитектор) | +| `docs/architecture/adr/adr-NNNN-*.md` | создать при необходимости (архитектор, если решение сквозное) | +| **НЕ трогать** | `src/**` (любой), `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, `_parse_*`, `src/frontmatter.py`, схема БД; XML-канон и 52c-эмиссия промптов 52d | + +## 3. Функциональные требования + +### FR-1 — Стандарт `docs/_standards/TRACEABILITY.md` (BR-1, BR-4, BR-5) + +Новый нормативный документ в стиле соседей (`PIPELINE_DOCS.md`/`HANDOFF_PROTOCOL.md`). Обязательные +смысловые блоки: + +1. **Назначение и определение.** Маркер `ORCH-NNN` (и `ET-NNN`) в коде = обязательный стандарт + трассировки: привязка нетривиальной строки/блока/инварианта к work item, который его ввёл, и к + его ADR. (Зафиксировать существующий факт: ~51 уникальный маркер в `src/`.) +2. **Формат маркера.** Inline-комментарий, содержащий `ORCH-NNN` (например, в docstring модуля + и/или у строки инварианта); рекомендуется указывать ссылку на решение + (`ORCH-088, ADR-001 D1`). Не вводить нового синтаксиса — кодифицировать сложившийся. +3. **Где ставится.** Рядом с **нетривиальным инвариантом** (fail-open/fail-closed выбор, точное + условие сериализации, идемпотентность, обходимая дыра конвейера), а **не** на тривиальном/ + самоочевидном коде. Правило для нового кода: вводишь значимый инвариант → ставь маркер своей + задачи рядом. +4. **Как читать историю — с РЕАЛЬНЫМ примером (AC-1).** Пошагово: маркер в коде → `docs/work-items/ + ORCH-NNN/06-adr/`. Обязателен ≥1 проверяемый пример из существующего кода, например: + `src/serial_gate.py` строка `t2.id < jobs.task_id` несёт маркер **ORCH-088** (ADR-001 D1 / FR-2, + FIFO-уточнение) → читать `docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md`. Пример обязан + ссылаться на реально существующие в `main` файл и ADR. +5. **Fallback-доступ (BR-4).** Если папки `docs/work-items/ORCH-NNN/` нет в текущей ветке (срезана + от `main` без неё) — читать из `origin/main`: + `git show origin/main:docs/work-items/ORCH-NNN/06-adr/ADR-001-.md` + (при необходимости `git fetch origin` заранее; листинг — `git ls-tree origin/main:docs/work-items/ORCH-NNN/06-adr/`). +6. **Анти-археология (BR-5).** Если функция/блок несёт **3+ маркеров** `ORCH-NNN` — вместо раскопок + по каждому work item ставится **сводная ссылка на один сквозной ADR** (`docs/architecture/adr/ + adr-NNNN-*`), агрегирующий эволюцию. Пример из кода: `src/merge_gate.py` несёт ORCH-043/065/071/073 + → сводные сквозные `adr-0006`/`adr-0013`/`adr-0014`/`adr-0016`. +7. **Правило чтения (нормативная формулировка).** «Правишь код с маркером `ORCH-NNN` → прочитай его + `06-adr` ПЕРЕД изменением; не сломай зафиксированный инвариант; не можешь — эскалируй/верни в + анализ» — каноничный текст, на который ссылаются промпты (BR-6: единый источник, без повтора). + +### FR-2 — Правило чтения в `developer.md` (BR-2) + +Точечная врезка (НЕ перезапись), сохраняющая 5 XML-секций и 52c-эмиссию. В `` (и/или +`` списком «что прочесть») добавить пункт в формате «❌ X → ✅ Y»: +- ❌ Не правь строку/блок с маркером `ORCH-NNN` вслепую → ✅ перед изменением прочитай + `docs/work-items/ORCH-NNN/06-adr/` и не сломай зафиксированный инвариант; стандарт — + `docs/_standards/TRACEABILITY.md`. +- Включить fallback-доступ (FR-5). +Существующее 52d-упоминание «реализуй по `06-adr/`» относится к ADR *текущей* задачи — НЕ дублировать, +а **дополнить** правилом для *чужих* маркеров. + +### FR-3 — Правило чтения + анти-археология в `architect.md` (BR-2, BR-5) + +Точечная врезка: при изменении маркированного компонента архитектор обязан свериться с ADR work +item(ов), породивших инвариант; при введении/правке блока с 3+ маркерами — оформить/обновить +**сводный сквозной ADR** (`docs/architecture/adr/`) согласно `TRACEABILITY.md` §анти-археология. +Ссылка на стандарт; без перезаписи существующих секций. + +### FR-4 — Контроль соблюдения в `reviewer.md` (BR-3) + +Точечная врезка в ось «Соответствие ADR» (или новый под-пункт): reviewer проверяет, что правка +кода, несущего чужой маркер `ORCH-NNN`, **сверена** с его `06-adr` и не ломает инвариант; нарушение +(правка маркированного инварианта без обоснования / со сломом) → finding. Рекомендуемая severity — +**P1** (must-fix); слом критического инварианта конвейера может быть P0 на усмотрение reviewer. +Ссылка на `TRACEABILITY.md`. НЕ дублировать существующую общую ADR-ось — усилить её этим под-пунктом. + +### FR-5 — Fallback-доступ задокументирован (BR-4) + +Команда `git show origin/main:docs/work-items/ORCH-NNN/06-adr/...` присутствует и в `TRACEABILITY.md` +(FR-1.5), и в `developer.md` (рядом с правилом чтения), чтобы агент, у которого нет папки в ветке, +знал штатный способ прочитать чужой ADR. + +### FR-6 — Анти-археология зафиксирована (BR-5) + +Конвенция «3+ маркеров → сводный сквозной ADR» присутствует в `TRACEABILITY.md` (FR-1.6) и в +`architect.md` (FR-3). Reviewer может опираться на неё при ревью (FR-4). + +### FR-7 — Сопутствующая документация (BR-7) + +- `CLAUDE.md` — в «Правила для агентов» и/или «Конвенции» добавить правило трассировки одной строкой + + ссылку на `docs/_standards/TRACEABILITY.md` (по образцу того, как там уже ссылаются на + `PIPELINE_DOCS.md`/`HANDOFF_PROTOCOL.md`). +- `docs/architecture/README.md` — в разделе про стандарты документов конвейера (ORCH-075/077) + упомянуть `TRACEABILITY.md` как **слой 4 (трассировка)** эпика ORCH-52 со ссылкой. +- `CHANGELOG.md` — запись под `## [Unreleased]` (`docs:`). + +### FR-8 — Анти-регресс промптов (NFR-2) + +Расширить `tests/test_agent_prompts_canon.py` (tests-only, `src/` не трогается) так, чтобы он +утверждал присутствие reading-rule маркеров в developer/architect/reviewer (напр. строка +`TRACEABILITY` и/или паттерн правила чтения у маркированного кода) — аналогично существующим +`_ANTI_REGRESS`-проверкам. Существующие проверки 52d (5 XML-секций, 6 полей схемы, точный регистр +verdict-ключей, self-hosting-маркеры deployer) остаются и зелёные; +`tests/test_agent_frontmatter_no_model.py` остаётся зелёным. + +## 4. Изменения API +Нет. Эндпоинты не добавляются/не меняются. + +## 5. Изменения схемы БД +Нет. Таблицы/миграции/индексы не трогаются. + +## 6. Требования к новым/изменённым QG checks +Нет. `QG_CHECKS`, `check_*`, `_parse_*`, `STAGE_TRANSITIONS` — без изменений. +`frontmatter_validation_strict` остаётся `False`; enforcement не вводится. Новый QG не добавляется +(стандарт трассировки — нормативный документ + анти-регресс-тест промптов, не машинный гейт +конвейера). + +## 7. Совместимость / регресс +- **Нулевое касание кода (NFR-1):** меняются только `docs/**` и `.openclaw/agents/*.md` (+ tests-only + расширение структурного теста). Поведение `src/` идентично → нулевая функциональная регрессия, + enduro-trails не затронут. +- **Анти-регресс промптов (NFR-2):** точечные врезки сохраняют 5 XML-секций, 52c-эмиссию и + machine-verdict ключи байт-в-байт; гарантируется расширенным `test_agent_prompts_canon.py`. +- **Self-hosting (NFR-4):** промпт `cat`-ается из worktree при запуске → новое правило действует на + следующем worktree от `main` без прод-рестарта (8500). +- **Обратимость (NFR-5):** чисто текстовое изменение; `git revert` PR — полный откат; kill-switch + не нужен (нет машинного поведения); нет миграций/состояния. +- **Анти-дубль (BR-6):** промпты ссылаются на единый текст правила в `TRACEABILITY.md`, а не + повторяют его; 52d-канон не переписывается. +- **Тесты:** полный `pytest tests/ -q` — зелёный. diff --git a/docs/work-items/ORCH-078/03-acceptance-criteria.md b/docs/work-items/ORCH-078/03-acceptance-criteria.md new file mode 100644 index 0000000..17baf4a --- /dev/null +++ b/docs/work-items/ORCH-078/03-acceptance-criteria.md @@ -0,0 +1,120 @@ +--- +work_item: ORCH-078 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-078 — ORCH-52e: трассировка ORCH-NNN + +Work Item: **ORCH-078** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что +считается провалом). Reviewer проверяет их буквально по файлам репозитория. + +--- + +## AC-1 — Стандарт маркеров создан с реальным примером из кода + +**Условие:** в `docs/_standards/` существует `TRACEABILITY.md` с форматом маркера, правилом +размещения и проверяемым примером из реального кода. +- **PASS:** файл `docs/_standards/TRACEABILITY.md` существует; описывает формат `ORCH-NNN`, где + ставится (рядом с нетривиальным инвариантом), как читать историю; содержит ≥1 пример, ссылающийся + на **реально существующие** в `main` файл `src/...` + маркер `ORCH-NNN` + путь + `docs/work-items/ORCH-NNN/06-adr/...` (напр. `src/serial_gate.py` → ORCH-088 → `ADR-001-serial-gate.md`). +- **FAIL:** файла нет; нет формата/правила размещения; пример отсутствует или ссылается на + несуществующие файл/ADR (нерабочая трассировка). + +--- + +## AC-2 — Правило чтения присутствует в developer и architect + +**Условие:** правило «правишь код с маркером `ORCH-NNN` → прочитай его `06-adr` ПЕРЕД изменением, +не сломай инвариант» присутствует в `developer.md` и `architect.md`. +- **PASS:** оба промпта содержат правило (со ссылкой на `TRACEABILITY.md`), сформулированное как + правило для **чужих** маркеров в правимом коде (не просто «реализуй по `06-adr/` текущей задачи»); + developer-формулировка соблюдает формат «❌ X → ✅ Y». +- **FAIL:** правило отсутствует в одном из промптов; либо лишь повторяет 52d-упоминание ADR текущей + задачи без сути «читай ADR чужого маркера перед правкой». + +--- + +## AC-3 — Reviewer проверяет соблюдение трассировки + +**Условие:** `reviewer.md` содержит ось/под-пункт контроля: правка маркированного кода без сверки с +его ADR / со сломом инварианта → finding. +- **PASS:** reviewer-промпт явно требует проверять сверку правок маркированного (`ORCH-NNN`) кода с + его `06-adr`; нарушение даёт finding с severity (≥P1); есть ссылка на `TRACEABILITY.md`. +- **FAIL:** reviewer не проверяет соблюдение трассировки (правило есть у автора, но никто не + контролирует) либо проверка не привязана к severity/finding. + +--- + +## AC-4 — Fallback-доступ задокументирован + +**Условие:** способ `git show origin/main:docs/work-items/ORCH-NNN/06-adr/...` задокументирован. +- **PASS:** команда присутствует в `TRACEABILITY.md` и в `developer.md` (рядом с правилом чтения), + с пояснением «когда папки нет в текущей ветке». +- **FAIL:** fallback не задокументирован нигде, либо приведён без контекста применения. + +--- + +## AC-5 — Анти-археология зафиксирована + +**Условие:** конвенция «3+ маркеров в блоке → сводная ссылка на сквозной ADR (`docs/architecture/ +adr/`)» зафиксирована. +- **PASS:** правило присутствует в `TRACEABILITY.md` (с примером, напр. `src/merge_gate.py` → + ORCH-043/065/071/073 → сквозные `adr-0006/0013/0014/0016`) и в `architect.md`. +- **FAIL:** правило отсутствует либо сформулировано без числового порога/без указания на сквозной ADR. + +--- + +## AC-6 — Анти-дубль: 52e не повторяет 52d + +**Условие:** 52e не дублирует уже сделанное в 52d; где смежное поведение есть — ссылается/усиливает. +- **PASS:** промпты ссылаются на единый текст правила в `TRACEABILITY.md` (а не копируют его в + каждый); XML-канон 52d (5 секций) и 52c-эмиссия сохранены; нет дословного повтора уже имевшихся + 52d-формулировок. +- **FAIL:** правило скопировано дословно в несколько промптов вместо ссылки; либо промпты переписаны + целиком (нарушен канон 52d). + +--- + +## AC-7 — Код не изменён; анти-регресс промптов держится; регресс зелёный + +**Условие:** изменены только `docs/**` и `.openclaw/agents/*.md` (+ tests-only расширение +структурного теста); `src/**` не тронут; анти-регресс промптов сохранён. +- **PASS:** `git diff --name-only origin/main` показывает изменения только в `docs/**`, + `.openclaw/agents/*.md`, `tests/test_agent_prompts_canon.py`, `CLAUDE.md`, `CHANGELOG.md` (нет + `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `_parse_*`, схемы БД); `tests/test_agent_prompts_canon.py` + и `tests/test_agent_frontmatter_no_model.py` зелёные; machine-verdict ключи + (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`) сохранены байт-в-байт; + полный `pytest tests/ -q` зелёный. +- **FAIL:** любой файл `src/**` изменён; потерян verdict-ключ/XML-секция/запрет; красный тест. + +--- + +## AC-8 — Сопутствующая документация обновлена + +**Условие:** `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md` обновлены; есть ADR задачи. +- **PASS:** `CLAUDE.md` и `docs/architecture/README.md` ссылаются на `TRACEABILITY.md` (слой 4 эпика + 52); в `CHANGELOG.md` есть запись `## [Unreleased]`; создан `docs/work-items/ORCH-078/06-adr/ + ADR-001-*.md`. +- **FAIL:** любой из перечисленных документов не обновлён/не создан (для reviewer: необновлённая + документация при изменении репозитория → `REQUEST_CHANGES`). + +--- + +## Сводная матрица AC ↔ FR/BR +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1 / FR-1 | +| AC-2 | BR-2 / FR-2, FR-3 | +| AC-3 | BR-3 / FR-4 | +| AC-4 | BR-4 / FR-1, FR-5 | +| AC-5 | BR-5 / FR-1, FR-6 | +| AC-6 | BR-6 / FR-1..FR-4 | +| AC-7 | NFR-1, NFR-2 / FR-8 | +| AC-8 | BR-7 / FR-7 | diff --git a/docs/work-items/ORCH-078/04-test-plan.yaml b/docs/work-items/ORCH-078/04-test-plan.yaml new file mode 100644 index 0000000..0304d08 --- /dev/null +++ b/docs/work-items/ORCH-078/04-test-plan.yaml @@ -0,0 +1,98 @@ +work_item: ORCH-078 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +title: "ORCH-52e: трассировка ORCH-NNN — стандарт маркеров + правило чтения" +framework: pytest +scope: > + Покрытие — структурные текстовые проверки (без запуска агентов, без импорта src/): + наличие и содержание docs/_standards/TRACEABILITY.md, присутствие правила чтения в + developer/architect, контроль соблюдения в reviewer, fallback-доступ, анти-археология, + анти-регресс промптов 52d. Вне покрытия — массовый ретро-фит маркеров в src/ и любое + поведение кода (src/** не меняется). +notes: > + Тесты — расширение существующего tests/test_agent_prompts_canon.py (tests-only; src/ не + трогается, что согласуется с AC-7). Проверки текстовые (open()+read() по файлам репозитория), + как и канон 52d. test_agent_frontmatter_no_model.py остаётся зелёным. Полный регресс + pytest tests/ -q должен оставаться зелёным. + +tests: + - id: TC-01 + type: unit + description: "docs/_standards/TRACEABILITY.md существует и непустой (AC-1)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-02 + type: unit + description: "TRACEABILITY.md описывает формат маркера ORCH-NNN и правило размещения рядом с нетривиальным инвариантом (AC-1)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-03 + type: unit + description: "TRACEABILITY.md содержит реальный пример: ссылается на существующий путь src/...py и на существующий docs/work-items/ORCH-NNN/06-adr/...md (AC-1)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-04 + type: unit + description: "TRACEABILITY.md документирует fallback-доступ git show origin/main:docs/work-items/... (AC-4)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-05 + type: unit + description: "TRACEABILITY.md документирует анти-археологию: порог 3+ маркеров → сводная ссылка на сквозной ADR docs/architecture/adr/ (AC-5)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-06 + type: unit + description: "developer.md несёт правило чтения чужого маркера + ссылку на TRACEABILITY.md + fallback git show origin/main: (AC-2, AC-4)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-07 + type: unit + description: "architect.md несёт правило чтения маркированного кода + анти-археологию (3+ → сквозной ADR) + ссылку на TRACEABILITY.md (AC-2, AC-5)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-08 + type: unit + description: "reviewer.md несёт ось контроля: правка маркированного кода без сверки с ADR → finding (AC-3)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-09 + type: unit + description: "АНТИ-РЕГРЕСС 52d: 5 XML-секций и 6 полей 52c-схемы присутствуют во всех 6 промптах (NFR-2)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-10 + type: unit + description: "АНТИ-РЕГРЕСС 52d: machine-verdict ключи сохранены байт-в-байт (verdict:/result:/staging_status:/deploy_status:/security_status:, точный регистр и наборы значений) (NFR-2)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-11 + type: unit + description: "frontmatter промптов остаётся валидным без ключа model: (повторно зелёный) (NFR-2)." + module: tests/test_agent_frontmatter_no_model.py + expected: PASS + + - id: TC-12 + type: unit + description: "CLAUDE.md и docs/architecture/README.md ссылаются на docs/_standards/TRACEABILITY.md как слой 4 эпика 52 (AC-8)." + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-13 + type: integration + description: "Полный регресс pytest tests/ -q зелёный; src/ не изменён (поведение кода идентично) (AC-7)." + module: tests/ + expected: PASS