From 6511ddadbb7e54b5f98544029a6f212d6bda4f50 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 12:44:10 +0300 Subject: [PATCH] analyst(ET): auto-commit from analyst run_id=447 --- docs/work-items/ORCH-075/01-brd.md | 111 ++++++++++++++ docs/work-items/ORCH-075/02-trz.md | 141 ++++++++++++++++++ .../ORCH-075/03-acceptance-criteria.md | 104 +++++++++++++ docs/work-items/ORCH-075/04-test-plan.yaml | 136 +++++++++++++++++ 4 files changed, 492 insertions(+) create mode 100644 docs/work-items/ORCH-075/01-brd.md create mode 100644 docs/work-items/ORCH-075/02-trz.md create mode 100644 docs/work-items/ORCH-075/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-075/04-test-plan.yaml diff --git a/docs/work-items/ORCH-075/01-brd.md b/docs/work-items/ORCH-075/01-brd.md new file mode 100644 index 0000000..019af35 --- /dev/null +++ b/docs/work-items/ORCH-075/01-brd.md @@ -0,0 +1,111 @@ +# 01 — BRD: ORCH-075 — ORCH-52b: стандарт документов (docs/_templates + манифест стадий + ADR-naming) + +Work Item: **ORCH-075** +Repo: **orchestrator** (self-hosting) +Стадия: analysis +Заказчик: Owner / команда агентов оркестратора +Тип: documentation-standard (слой 1 эпика ORCH-52) + +> Документ фиксирует **бизнес-требования** к созданию стандарта документов пайплайна. +> ORCH-52b — слой 1 («стандарт»): только документация (манифест + канонические шаблоны + +> конвенция ADR-naming). Любая принудительная проверка/валидатор/правка кода и промптов — +> вне scope (это ORCH-52c/52d). Источник истины для манифеста — фактические +> `STAGE_TRANSITIONS` / `QG_CHECKS` и реальные эталонные доки в репозитории, а не вымысел. + +--- + +## 1. Бизнес-контекст и проблема + +### 1.1. Текущее состояние (проверено в репо) +- Каталоги `docs/_templates/` и `docs/_standards/` **не существуют**. +- Агенты (`analyst` → `architect` → … → `deployer`) пишут номерные доки work item + (`00-business-request.md` … `17-security-report.md`) «с нуля по памяти». +- Конвенция ADR-naming `06-adr/ADR-NNN-.md` фактически уже сложилась в репо, + но **нигде не зафиксирована** как стандарт. + +### 1.2. Боль +- **Разнобой структуры** между задачами: набор и порядок секций одного и того же дока + плавает от work item к work item (видно при сравнении BRD/ТЗ разных задач). +- Машинные доки-вердикты (`12-review.md`, `13-test-report.md`, `14-deploy-log.md`, + `15-staging-log.md`, `17-security-report.md`) держат критичный frontmatter-ключ + (`verdict:` / `deploy_status:` / `staging_status:` / `security_status:`), читаемый + гейтом — но единого канонического скелета с этим ключом нет → риск рассинхрона. +- Нет единой карты «какая стадия / какой агент пишет какой документ и на каком гейте он + проверяется» — онбординг новых агентских ролей и аудит покрытия затруднён. + +### 1.3. Почему именно стандарт (а не сразу валидатор) +Эпик ORCH-52 разбит на слои, чтобы **сначала зафиксировать договорённость (golden source +документации)**, а уже потом, отдельной задачей (52c), навешивать машинную проверку +frontmatter/шаблонов на гейте. Стандарт без кода — обратимый, низкорисковый, не трогает +работающий прод-конвейер (self-hosting). Это снижает групповой риск. + +## 2. Объём (scope) + +### 2.1. В объёме (ORCH-52b) +1. **Манифест** `docs/_standards/PIPELINE_DOCS.md`: таблица «стадия → документ» с + владельцем-агентом, категорией (`required` / `when-applicable` / `optional`), стадией + написания и гейтом/механизмом проверки — **сверенная с фактическими `QG_CHECKS` и + `stage_engine`**. +2. **Канонические шаблоны** `docs/_templates/*` — скелеты (frontmatter при необходимости + + обязательные секции) для всех номерных доков из реального набора. +3. **Конвенция ADR-naming** — зафиксировать сложившийся формат `06-adr/ADR-NNN-.md` + (нумерация с `001`, где живёт, как формируется slug); раздел в манифесте/стандарте. +4. Ссылки на новый стандарт в `CLAUDE.md` и `docs/architecture/README.md`; запись в + `CHANGELOG.md`. + +### 2.2. Вне объёма (явно — это ORCH-52c / 52d) +- Frontmatter-валидатор в коде; writer-контракт; принудительная проверка наличия/структуры + шаблонов на Quality Gate. +- Любые изменения `QG_CHECKS` / `STAGE_TRANSITIONS` / `check_*` / `src/stage_engine.py` / + схемы БД. +- Правка системных промптов агентов (`.openclaw/agents/*`) — это слой 52d. +- Массовое приведение **уже существующих** доков прошлых задач к новому шаблону (ретро-фит). + +## 3. Заинтересованные стороны +| Роль | Интерес | +|------|---------| +| Owner | Единообразие и аудитопригодность документации проекта | +| Агенты analyst/architect | Готовый скелет → меньше расхождений, быстрее старт | +| Агенты reviewer/tester/deployer | Предсказуемый frontmatter машинных доков | +| ORCH-52c (downstream) | Стандарт = база для frontmatter-валидатора/writer-контракта | + +## 4. Бизнес-требования (BR) +| ID | Требование | +|----|------------| +| BR-1 | Создан `docs/_standards/PIPELINE_DOCS.md` — манифест, покрывающий **все** номерные доки реального набора (00,01,02,03,04,06,07,08,10,12,13,14,15,16,17) с владельцем-агентом и категорией. | +| BR-2 | Каждому `required` и `when-applicable` доку соответствует канонический шаблон в `docs/_templates/` (frontmatter при необходимости + обязательные секции). | +| BR-3 | Формат ADR-naming `06-adr/ADR-NNN-.md` зафиксирован в стандарте и совпадает с реальными ADR в репо. | +| BR-4 | Манифест и шаблоны **согласованы с фактическими эталонными доками** (ORCH-088/073/089/071): нет секций, которых никто не пишет, и наоборот; frontmatter-ключи машинных доков совпадают с тем, что реально парсят гейты. | +| BR-5 | Обновлены `CLAUDE.md` и `docs/architecture/README.md` со ссылкой на стандарт; добавлена запись в `CHANGELOG.md`. | +| BR-6 | Манифест отражает категорию проверки документа фактическим механизмом: какие доки несут machine-verdict frontmatter, читаемый гейтом, а какие информационные (не гейтятся). | + +## 5. Нефункциональные требования (NFR) +| ID | Требование | +|----|------------| +| NFR-1 | **Нулевой риск для прода:** изменения — только под `docs/` (+ `CLAUDE.md`/`CHANGELOG.md`). Ни строки кода/гейтов. | +| NFR-2 | **Достоверность:** все утверждения манифеста о стадии/агенте/гейте проверяемы по `src/stages.py` / `src/qg/checks.py` / `src/stage_engine.py`. | +| NFR-3 | **Не изобретать:** шаблоны выведены из существующих эталонов, не из фантазии; новые секции не вводятся. | +| NFR-4 | **Читаемость:** манифест — на русском, в стиле существующей документации проекта; таблицы машиночитаемо-аккуратные. | +| NFR-5 | **Обратимость:** удаление новых файлов полностью откатывает изменение без следов в поведении системы. | + +## 6. Допущения и ограничения +- Реальный набор номерных доков и их частота взяты из `docs/work-items/` (факты в описании + задачи); считаем его авторитетным на момент задачи. +- Эталонные («golden») задачи для извлечения скелетов — ORCH-088, ORCH-073, ORCH-089, ORCH-071. +- `09-review.md` — legacy fallback (канон — `12-review.md`); в манифест как канон **не** + вводится, при необходимости упоминается примечанием. +- Стадия `monitoring` для `16-post-deploy-log.md` — пост-`done` наблюдение (ORCH-021), не + ребро `STAGE_TRANSITIONS`; манифест это отражает явно. + +## 7. Критерии успеха +- Любой агент, открыв `docs/_standards/PIPELINE_DOCS.md`, понимает: какой документ он пишет + на своей стадии, в какой категории, с каким frontmatter и где он проверяется. +- Для каждого `required`/`when-applicable` дока существует шаблон, который можно скопировать + и заполнить без догадок о структуре. +- ADR-naming больше не «устная традиция», а записанная конвенция. +- Полный набор уточняющих PASS/FAIL — в `03-acceptance-criteria.md`. + +## 8. Риски +Технические риски и митигейшн ведёт архитектор в `10-tech-risks.md`. Ключевой бизнес-риск — +**рассинхрон стандарта с кодом** (манифест описал гейт, которого нет, или наоборот): митигируется +NFR-2 (сверка с `src/`) и AC-1/AC-4. diff --git a/docs/work-items/ORCH-075/02-trz.md b/docs/work-items/ORCH-075/02-trz.md new file mode 100644 index 0000000..263c31f --- /dev/null +++ b/docs/work-items/ORCH-075/02-trz.md @@ -0,0 +1,141 @@ +# 02 — ТЗ (TRZ): ORCH-075 — ORCH-52b: стандарт документов + +Work Item: **ORCH-075** · Repo: **orchestrator** · Стадия: analysis + +> ТЗ описывает **конкретные артефакты к созданию** (манифест + шаблоны + раздел ADR-naming) и +> их обязательное содержимое, выведенное из фактических `STAGE_TRANSITIONS`/`QG_CHECKS` и +> эталонных доков. Это **docs-only** изменение: исходный код, гейты, схема БД, промпты — +> НЕ затрагиваются (см. §7). Архитектурное обоснование/решения — задача архитектора (06-adr). + +## 1. Сводка изменения +Создать каталоги `docs/_standards/` и `docs/_templates/`, наполнить их манифестом +«стадия→документ», каноническими скелетами номерных доков и зафиксировать ADR-naming. +Обновить точки-ссылки (`CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`). + +## 2. Задействованные модули / пути +| Путь | Действие | +|------|----------| +| `docs/_standards/PIPELINE_DOCS.md` | **создать** — манифест стадия→документ + раздел ADR-naming | +| `docs/_templates/00-business-request.md` | **создать** — шаблон | +| `docs/_templates/01-brd.md` | **создать** | +| `docs/_templates/02-trz.md` | **создать** | +| `docs/_templates/03-acceptance-criteria.md` | **создать** | +| `docs/_templates/04-test-plan.yaml` | **создать** | +| `docs/_templates/06-adr-ADR-NNN-slug.md` | **создать** — шаблон ADR (имя файла шаблона без коллизии с реальной нумерацией) | +| `docs/_templates/07-infra-requirements.md` | **создать** (when-applicable) | +| `docs/_templates/08-data-requirements.md` | **создать** (when-applicable) | +| `docs/_templates/10-tech-risks.md` | **создать** | +| `docs/_templates/12-review.md` | **создать** (frontmatter `verdict:`) | +| `docs/_templates/13-test-report.md` | **создать** (frontmatter `result:`) | +| `docs/_templates/14-deploy-log.md` | **создать** (frontmatter `deploy_status:`) | +| `docs/_templates/15-staging-log.md` | **создать** (frontmatter `staging_status:`) | +| `docs/_templates/16-post-deploy-log.md` | **создать** (frontmatter `post_deploy_status:`) | +| `docs/_templates/17-security-report.md` | **создать** (frontmatter `security_status:`) | +| `CLAUDE.md` | **изменить** — ссылка на стандарт в разделе «Артефакты задачи» / «Правила для агентов» | +| `docs/architecture/README.md` | **изменить** — ссылка на стандарт | +| `CHANGELOG.md` | **изменить** — запись в `## [Unreleased]` | + +> Точное имя файла-шаблона ADR оставлено на усмотрение разработчика/архитектора при условии, +> что **внутри** шаблона и в манифесте зафиксирован реальный целевой формат +> `06-adr/ADR-NNN-.md` (см. §3, FR-3). + +## 3. Функциональные требования + +### FR-1 — Манифест `docs/_standards/PIPELINE_DOCS.md` +Содержит таблицу-манифест, покрывающую **все** номерные доки реального набора. Для каждого — +колонки: `Документ`, `Владелец-агент`, `Категория`, `Стадия написания`, `Гейт/механизм +проверки`, `Frontmatter machine-key (если есть)`. Манифест ДОЛЖЕН соответствовать +ground-truth ниже (сверено по `src/`): + +| Документ | Владелец-агент | Категория | Стадия написания | Гейт / проверка | Machine-key | +|----------|----------------|-----------|------------------|-----------------|-------------| +| `00-business-request.md` | система (Plane webhook `_create_initial_docs`) / заказчик | required | `created` (инициализация) | не гейтится (вход) | — | +| `01-brd.md` | analyst | required | `analysis` | exit-гейт `analysis→architecture` = `check_analysis_approved` (Approved + полнота файлов); helper `check_analysis_complete` (наличие) | — | +| `02-trz.md` | analyst | required | `analysis` | то же | — | +| `03-acceptance-criteria.md` | analyst | required | `analysis` | то же | — | +| `04-test-plan.yaml` | analyst | required | `analysis` | то же | — | +| `06-adr/ADR-NNN-.md` | architect | required | `architecture` | `check_architecture_done` (наличие каталога/ADR) | — | +| `07-infra-requirements.md` | architect | when-applicable | `architecture` | `check_architecture_done` (учитывается при наличии) | — | +| `08-data-requirements.md` | architect | when-applicable | `architecture` | информационный (гейтом не парсится) | — | +| `10-tech-risks.md` | architect | required | `architecture` | информационный (гейтом не парсится) | — | +| `12-review.md` | reviewer | required | `review` | `check_reviewer_verdict` | `verdict:` (APPROVED\|REQUEST_CHANGES) | +| `13-test-report.md` | tester | required | `testing` | `check_tests_passed` | `result:`/`verdict:`/`status:` (PASS\|FAIL\|BLOCKED) | +| `14-deploy-log.md` | deployer / deploy-finalizer | required | `deploy` | `check_deploy_status` | `deploy_status:` (SUCCESS\|FAILED) | +| `15-staging-log.md` | deployer | required (self-hosting) | `deploy-staging` | `check_staging_status` (self-hosting; иначе N/A) | `staging_status:` (SUCCESS\|FAILED) | +| `16-post-deploy-log.md` | post-deploy-monitor | when-applicable | пост-`done` наблюдение (ORCH-021, не ребро `STAGE_TRANSITIONS`) | информационный (гейтом не парсится) | `post_deploy_status:` | +| `17-security-report.md` | security-гейт (детерминированный, ORCH-022) | when-applicable | под-гейт ребра `deploy-staging→deploy` | `check_security_gate` | `security_status:` (PASS\|FAIL) | + +Примечания манифеста (обязательны): +- Под-гейты ребра `deploy-staging→deploy` (`check_security_gate` → `check_branch_mergeable` → + `check_staging_image_fresh`) — **не** строки `STAGE_TRANSITIONS`, а врезки в `advance_stage`. +- `09-review.md` — legacy fallback; канон — `12-review.md` (упомянуть примечанием, в основную + таблицу как канон не вносить). +- Категория `when-applicable` = пишется при наличии соответствующего предмета (инфра/данные/ + security/post-deploy); её отсутствие — не нарушение. + +### FR-2 — Шаблоны `docs/_templates/*` +Каждый шаблон — копируемый скелет. Обязательные элементы по типам (выведено из эталонов +ORCH-088/073/089/071): + +- **Документы БЕЗ frontmatter** (`00`,`01`,`02`,`03`,`06-adr`,`07`,`08`,`10`): заголовок `#`, + строка метаданных `Work Item / Repo / Стадия`, и фиксированные `##`-секции (ниже §FR-2.1). +- **YAML-only**: `04-test-plan.yaml` — корневые ключи + список `tests:` (ниже §FR-2.2). +- **Документы С YAML-frontmatter** (`12`,`13`,`14`,`15`,`16`,`17`): блок `---…---` с + machine-key из таблицы FR-1 + body-секции. + +#### FR-2.1 Обязательные секции по документу (минимальный канон) +- `00-business-request.md`: `# Business Request: `; строка `Work Item ID:`; `## Description`. +- `01-brd.md`: `## 1. Бизнес-контекст и проблема`, `## 2. Объём (scope)` (с `### В объёме`/`### Вне объёма`), `## 3. Заинтересованные стороны`, `## 4. Бизнес-требования (BR)`, `## 5. Нефункциональные требования (NFR)`, `## 6. Допущения и ограничения`, `## 7. Критерии успеха`, `## 8. Риски`. +- `02-trz.md`: `## 1. Сводка изменения`, `## 2. Задействованные модули`, `## 3. Функциональные требования`, `## 4. Изменения API`, `## 5. Изменения схемы БД`, `## 6. Требования к QG checks`, `## 7. Совместимость / регресс`. +- `03-acceptance-criteria.md`: преамбула формата; повторяемый блок `## AC-N — ` с `**Условие:**`, `- **PASS:**`, `- **FAIL:**`; опц. `## Сводная матрица AC ↔ FR/BR`. +- `06-adr (шаблон)`: `# ADR-NNN: <title>`, метаданные (`Work Item`,`Стадия: architecture`,`Сквозная регистрация:`), `## Статус`, `## Контекст`, `## Решение` (с `### Сводка` и `### D1 — …`), `## Альтернативы`, `## Последствия`, `## Ссылки`. +- `07-infra-requirements.md`: `# 07 — Инфра-требования`, нумерованные `## I-N. <topic>`. +- `08-data-requirements.md`: `# 08 — Требования к данным`, секции по таблицам/колонкам/миграциям. +- `10-tech-risks.md`: `# 10 — Технические риски`, таблица `| ID | Риск | Вер. | Влия. | Митигейшн |`, `## Сводный вывод`. +- `12-review.md`: frontmatter `type: review` / `work_item_id:` / `verdict:` / `version:`; body `## Summary`, `## Оси проверки`, `## Findings` (`### P0`/`### P1`/`### P2`), `## Документация`. +- `13-test-report.md`: frontmatter `type: test-report` / `work_item_id:` / `result:`; body `## Окружение`, `## Результаты` (`### Полный регресс`, `### Профильные сюиты`, `### Сопоставление с тест-планом`, `### Сопоставление с критериями приёмки`). +- `14-deploy-log.md`: frontmatter `deploy_status:` / `work_item:` / `hook_exit_code:` / `deployed_by:`; body — краткое описание деплоя. +- `15-staging-log.md`: frontmatter `staging_status:` / `timestamp:` / `base_url:`; body — `# Staging Gate Log` + результаты проверок. +- `16-post-deploy-log.md`: frontmatter `post_deploy_status:` / `action_taken:` / `work_item:`; body — окно наблюдения/серия/решение. +- `17-security-report.md`: frontmatter `security_status:` / `work_item:`; body — secret-scan + dependency-audit результаты. + +#### FR-2.2 `04-test-plan.yaml` +Корень: `work_item:`, `title:`, `framework: pytest`, опц. `scope:`/`notes:`. Список `tests:` +с элементами `{ id: TC-NN, type: unit|integration, description, module: tests/…, expected: PASS }`. + +### FR-3 — Конвенция ADR-naming +Зафиксировать в `PIPELINE_DOCS.md` отдельным разделом: +- Путь: `docs/work-items/<plane-id>/06-adr/`. +- Имя: `ADR-NNN-<kebab-slug>.md`, `NNN` с `001`, инкремент при нескольких ADR в одной задаче. +- `slug` — kebab-case (нижний регистр, дефисы), отражает суть решения. +- Сквозные (cross-cutting) решения дублируются в `docs/architecture/adr/adr-NNNN-<slug>.md` + (4-значная глобальная нумерация) — это уже существующая конвенция, лишь зафиксировать. +- Примеры из репо: `ADR-001-serial-gate`, `ADR-001-auto-label-gates`, `ADR-001-merge-verify-gate`. + +### FR-4 — Точки-ссылки +- `CLAUDE.md`: в разделе «Артефакты задачи» и/или «Правила для агентов» добавить ссылку на + `docs/_standards/PIPELINE_DOCS.md` и `docs/_templates/` как golden source структуры доков. +- `docs/architecture/README.md`: добавить ссылку/абзац о стандарте документов. +- `CHANGELOG.md`: запись в `## [Unreleased]` (`docs:` тип). + +## 4. Изменения API +Нет. Эндпоинты не добавляются и не меняются. + +## 5. Изменения схемы БД +Нет. Таблицы/миграции не затрагиваются. + +## 6. Требования к новым/изменённым QG checks +Нет. `QG_CHECKS` и `check_*` **не трогаются** (это ORCH-52c). Манифест лишь **документирует** +текущее поведение гейтов. + +## 7. Совместимость / регресс +- Изменения только под `docs/` + `CLAUDE.md` + `CHANGELOG.md`. Поведение рантайма неизменно. +- Существующие доки прошлых задач не модифицируются (нет ретро-фита). +- `09-review.md` (legacy) сохраняется как fallback; манифест канонизирует `12-review.md`. +- Удаление новых файлов → полный откат без следов (NFR-5). + +## 8. Артефакты, создаваемые/обновляемые по pipeline +Создаются: `docs/_standards/PIPELINE_DOCS.md`, `docs/_templates/*` (15 шаблонов). +Обновляются: `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`. +Downstream-доки самой задачи ORCH-075 (`06-adr`, `10-tech-risks`, `12-review`, `13-test-report`, +`14-deploy-log`, `15-staging-log`) — по штатному конвейеру. diff --git a/docs/work-items/ORCH-075/03-acceptance-criteria.md b/docs/work-items/ORCH-075/03-acceptance-criteria.md new file mode 100644 index 0000000..a22543d --- /dev/null +++ b/docs/work-items/ORCH-075/03-acceptance-criteria.md @@ -0,0 +1,104 @@ +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-075 — ORCH-52b: стандарт документов + +Work Item: **ORCH-075** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** +(что считается провалом). Скоп — только создание стандарта/шаблонов/манифеста (docs-only). + +> Критерии унаследованы из AC задачи и расширены проверяемыми условиями. Любой машинный/ручной +> reviewer проверяет их буквально по файлам репозитория. + +--- + +## AC-1 — Манифест создан и покрывает весь реальный набор + +**Условие:** существует `docs/_standards/PIPELINE_DOCS.md` с таблицей-манифестом. +- **PASS:** файл существует; манифест содержит строки для **всех** номерных доков реального + набора — `00, 01, 02, 03, 04, 06, 07, 08, 10, 12, 13, 14, 15, 16, 17`; для каждого указаны + владелец-агент (analyst/architect/developer/reviewer/tester/deployer/система) и категория + (`required` / `when-applicable` / `optional`). +- **FAIL:** файла нет; пропущен хотя бы один документ набора; у дока отсутствует владелец или + категория. + +--- + +## AC-2 — Шаблоны созданы для каждого required/when-applicable дока + +**Условие:** существует `docs/_templates/` с каноническими скелетами. +- **PASS:** для каждого `required` и `when-applicable` дока есть файл-шаблон; в шаблоне + присутствуют (а) frontmatter с machine-key там, где он требуется по FR-1 (`12`→`verdict:`, + `13`→`result:`, `14`→`deploy_status:`, `15`→`staging_status:`, `16`→`post_deploy_status:`, + `17`→`security_status:`), и (б) обязательные `##`-секции из ТЗ §FR-2.1. +- **FAIL:** отсутствует шаблон для какого-либо required/when-applicable дока; в шаблоне + машинного дока нет требуемого frontmatter-ключа; набор секций произвольный, не из ТЗ. + +--- + +## AC-3 — ADR-naming зафиксирован + +**Условие:** в стандарте есть раздел про ADR-naming. +- **PASS:** зафиксирован формат `06-adr/ADR-NNN-<kebab-slug>.md` (NNN с `001`), путь + (`docs/work-items/<plane-id>/06-adr/`), правило формирования slug (kebab-case) и связь со + сквозным реестром `docs/architecture/adr/adr-NNNN-<slug>.md`; приведён ≥1 реальный пример. +- **FAIL:** ADR-naming не описан, либо описанный формат не совпадает с реальными ADR в репо + (напр. указана нумерация не с `001`, неверный путь, неверный регистр slug). + +--- + +## AC-4 — Согласованность с фактическими эталонами + +**Условие:** манифест и шаблоны соответствуют реальным эталонным докам (ORCH-088/073/089/071) +и фактическому коду. +- **PASS:** в шаблонах нет секций, которых никто не пишет в эталонах; все секции эталонов, + входящие в общий канон, присутствуют; frontmatter-ключи машинных доков совпадают с тем, что + реально парсят `src/qg/checks.py` (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/ + `security_status:`); привязка «документ→стадия→гейт» совпадает с `src/stages.py` + (`STAGE_TRANSITIONS`). +- **FAIL:** шаблон вводит выдуманную секцию; манифест приписывает доку неверную стадию/гейт/ + агента; frontmatter-ключ в шаблоне не тот, что читает гейт. + +--- + +## AC-5 — Ссылки и CHANGELOG обновлены + +**Условие:** точки-ссылки и журнал изменений отражают новый стандарт. +- **PASS:** `CLAUDE.md` и `docs/architecture/README.md` содержат ссылку на + `docs/_standards/PIPELINE_DOCS.md` (и/или `docs/_templates/`); в `CHANGELOG.md` добавлена + запись в `## [Unreleased]` типа `docs:`. +- **FAIL:** хотя бы одна из трёх точек не обновлена. + +--- + +## AC-6 — Код гейтов НЕ изменён + +**Условие:** изменение строго docs-only. +- **PASS:** `git diff` не содержит изменений в `src/qg/checks.py` (`QG_CHECKS`/`check_*`), + `src/stages.py` (`STAGE_TRANSITIONS`), `src/stage_engine.py`, схеме БД и любом коде гейтов; + затронуты только `docs/**`, `CLAUDE.md`, `CHANGELOG.md` (+ опционально новые файлы тестов). +- **FAIL:** изменён любой из перечисленных кодовых модулей/гейтов/схемы. + +--- + +## AC-7 — Манифест различает machine-verdict и информационные доки + +**Условие:** манифест честно отражает механизм проверки. +- **PASS:** документы, чей frontmatter читает гейт (`12,13,14,15,17`), помечены своим + machine-key и гейтом; информационные (`00,08,10,16`) явно помечены как не гейтящиеся; + под-гейты ребра `deploy-staging→deploy` (security/merge/image-freshness) отмечены как врезки + в `advance_stage`, а не строки `STAGE_TRANSITIONS`. +- **FAIL:** информационный док представлен как гейтящийся (или наоборот); под-гейты выданы за + стадии. + +--- + +## Сводная матрица AC ↔ BR + +| AC | Покрывает BR | +|----|--------------| +| AC-1 | BR-1 | +| AC-2 | BR-2 | +| AC-3 | BR-3 | +| AC-4 | BR-4, BR-6 | +| AC-5 | BR-5 | +| AC-6 | NFR-1, NFR-5 | +| AC-7 | BR-6, NFR-2 | diff --git a/docs/work-items/ORCH-075/04-test-plan.yaml b/docs/work-items/ORCH-075/04-test-plan.yaml new file mode 100644 index 0000000..fcc8c0a --- /dev/null +++ b/docs/work-items/ORCH-075/04-test-plan.yaml @@ -0,0 +1,136 @@ +work_item: ORCH-075 +title: "ORCH-52b — стандарт документов (docs/_standards + docs/_templates + ADR-naming)" +scope: "docs-only: проверяется НАЛИЧИЕ и СТРУКТУРА новых файлов-стандартов/шаблонов; код гейтов не трогается" +framework: pytest +notes: > + Изменение документационное. Тесты — лёгкие структурные проверки (existence + наличие + обязательных секций/frontmatter-ключей), новый файл tests/test_orch_52b_docs_standard.py. + Тесты НЕ меняют QG_CHECKS/STAGE_TRANSITIONS и не вводят новый гейт (это ORCH-52c). Полный + регресс tests/ должен остаться зелёным (отсутствие регресса от docs-изменения). + +tests: + - id: TC-01 + type: integration + description: "docs/_standards/PIPELINE_DOCS.md существует и непустой" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-02 + type: integration + description: "Манифест PIPELINE_DOCS.md упоминает все номерные доки набора: 00,01,02,03,04,06,07,08,10,12,13,14,15,16,17" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-03 + type: integration + description: "Манифест указывает владельца-агента для каждого дока (analyst/architect/reviewer/tester/deployer/система упомянуты)" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-04 + type: integration + description: "Манифест содержит категории required / when-applicable / optional" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-05 + type: integration + description: "Каталог docs/_templates/ существует и содержит шаблоны для всех required/when-applicable доков" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-06 + type: integration + description: "Шаблон 12-review содержит frontmatter-ключ verdict:" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-07 + type: integration + description: "Шаблон 13-test-report содержит frontmatter-ключ result:" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-08 + type: integration + description: "Шаблон 14-deploy-log содержит frontmatter-ключ deploy_status:" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-09 + type: integration + description: "Шаблон 15-staging-log содержит frontmatter-ключ staging_status:" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-10 + type: integration + description: "Шаблон 17-security-report содержит frontmatter-ключ security_status:" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-11 + type: integration + description: "Шаблон 16-post-deploy-log содержит frontmatter-ключ post_deploy_status:" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-12 + type: integration + description: "Шаблон 01-brd содержит обязательные секции: Бизнес-контекст, Объём, Бизнес-требования, NFR" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-13 + type: integration + description: "Шаблон 02-trz содержит обязательные секции: Задействованные модули, Изменения API, Изменения схемы БД, QG checks" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-14 + type: integration + description: "Шаблон 03-acceptance-criteria содержит блок AC-N с метками PASS и FAIL" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-15 + type: integration + description: "Шаблон 04-test-plan.yaml — валидный YAML с ключами work_item и tests (список с id/type/description/module/expected)" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-16 + type: integration + description: "Раздел ADR-naming присутствует и фиксирует формат ADR-NNN-<slug>.md с нумерацией с 001 и kebab-slug" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-17 + type: integration + description: "ADR-naming в стандарте совпадает с реальными ADR в репо (напр. существует docs/work-items/ORCH-088/06-adr/ADR-001-*.md)" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-18 + type: integration + description: "CLAUDE.md содержит ссылку на docs/_standards/PIPELINE_DOCS.md" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-19 + type: integration + description: "docs/architecture/README.md содержит ссылку на стандарт документов" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-20 + type: integration + description: "CHANGELOG.md содержит запись об ORCH-52b/ORCH-075 в разделе Unreleased" + module: tests/test_orch_52b_docs_standard.py + expected: PASS + + - id: TC-21 + type: integration + description: "Регресс: полный прогон pytest tests/ зелёный (docs-изменение не ломает существующие тесты)" + module: tests/ + expected: PASS