# 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-<kebab-slug>.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-<slug>.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: <subject>`; строка `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 — <title>` с `**Условие:**`, `- **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`) — по штатному конвейеру.