orchestrator/docs/work-items/ORCH-075/02-trz.md

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) — по штатному конвейеру.