orchestrator/docs/_standards/PIPELINE_DOCS.md

PIPELINE_DOCS — стандарт документов конвейера (golden source структуры)

Назначение. Единая карта «стадия → агент → документ → категория → гейт/механизм → frontmatter machine-key» + конвенция ADR-naming. Это golden source структуры номерных документов work item (00-business-request.md … 18-coverage-report.md), который каждая агентская роль пишет на своей стадии.

Статус истины (важно). Манифест документирует текущее поведение гейтов, но НЕ является их источником истины. Источник истины — код: src/stages.py (STAGE_TRANSITIONS), src/qg/checks.py (QG_CHECKS / check_* / _parse_*), src/stage_engine.py. При будущей правке гейта первична правка кода, манифест обновляется следом (ORCH-075 / ADR-001 §D2).

Копируемые скелеты каждого документа — в каталоге docs/_templates/: «скопировал → заполнил → не угадываешь структуру/ключ».

Введён задачей ORCH-075 (ORCH-52b — слой 1 эпика ORCH-52). Сквозной ADR: docs/architecture/adr/adr-0019-pipeline-docs-standard.md; детально — docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md.

---

1. Конвейер стадий (ground-truth STAGE_TRANSITIONS)

created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
                          ↑                          │
                          └──── REQUEST_CHANGES ──────┘  (откат на development, max 3 retries)

Каждое ребро несёт ровно один exit-гейт (src/stages.py): check_analysis_approved → check_architecture_done → check_ci_green → check_reviewer_verdict → check_tests_passed → check_staging_status → check_deploy_status.

Под-гейты ребра deploy-staging → deploy (check_security_gate → check_branch_mergeable → check_staging_image_fresh) — это врезки в advance_stage, а НЕ строки STAGE_TRANSITIONS. Аналогично под-гейт ребра deploy → done (_handle_merge_verify, ORCH-071/073) — врезка, не зарегистрированный QG. Карта стадий о них не «лжёт»: они не являются стадиями.

---

2. Манифест: документ → агент → категория → стадия → гейт → machine-key

Категории: required (пишется всегда), when-applicable (пишется при наличии предмета: инфра / данные / security / post-deploy — отсутствие не нарушение), optional / legacy.

Документ	Владелец-агент	Категория	Стадия написания	Гейт / механизм проверки	Frontmatter 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 (наличие 01/02/03/04)	—
01-questions.md	analyst	when-applicable	analysis	сигнальный (гейтом НЕ парсится); механизм — ветка Needs Input в _handle_analysis_approved_flow (ORCH-120, adr-0053): активные блокирующие вопросы → set_issue_needs_input (приоритет над «файлы готовы»)	— (не machine-verdict)
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 (наличие каталога 06-adr/ ≥1 файл ИЛИ 07-infra-requirements.md)	—
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 (_parse_tests_verdict)	result: / verdict: / status: (PASS | FAIL | BLOCKED; три равноранговых, ORCH-047)
14-deploy-log.md	deployer / deploy-finalizer	required	deploy	check_deploy_status (_parse_deploy_status)	deploy_status: (SUCCESS | FAILED)
15-staging-log.md	deployer	required (self-hosting)	deploy-staging	check_staging_status (self-hosting; иначе N/A — ORCH-35)	staging_status: (SUCCESS | FAILED)
16-post-deploy-log.md	post-deploy-monitor	when-applicable	пост-done наблюдение (ORCH-021; не ребро STAGE_TRANSITIONS)	информационный (гейтом не парсится)	post_deploy_status: (HEALTHY | DEGRADED)
17-security-report.md	security-гейт (детерминированный, ORCH-022)	when-applicable	под-гейт ребра deploy-staging→deploy	check_security_gate (врезка в advance_stage)	security_status: (PASS | FAIL)
18-coverage-report.md	coverage-гейт (детерминированный, ORCH-027)	when-applicable	под-гейт ребра deploy-staging→deploy (ПОСЛЕ merge-gate, ДО image-freshness)	check_coverage_gate (врезка в advance_stage)	coverage_status: (PASS | FAIL)

Примечания манифеста (нормативные)

• Под-гейты ребра deploy-staging→deploy (check_security_gate → check_branch_mergeable → check_staging_image_fresh) исполняются как врезки в advance_stage, а НЕ строки STAGE_TRANSITIONS. Не путать с exit-гейтами рёбер.
• 09-review.md — legacy fallback от старой нумерации; канон — 12-review.md. В основную таблицу как канон не вносится; reviewer пишет 12-review.md.
• Категория when-applicable = документ пишется при наличии соответствующего предмета (инфра / данные / security / post-deploy). Его отсутствие — не нарушение приёмки.
• 05-… / 09-… / 11-… — зарезервированные/legacy номера, в текущем каноне не используются.
• Префикс 01- (DQ-4 ORCH-120) — общий для артефактов стадии analysis владельца analyst: 01-brd.md — обязательный deliverable (гейтится check_analysis_complete), 01-questions.md — сигнальный when-applicable артефакт того же владельца/стадии. Коллизии нет: файлы разноимённые, check_analysis_complete проверяет ровно 01-brd.md/02/03/04 (01-questions.md им не парсится).

---

3. Machine-verdict доки vs информационные (честный механизм проверки)

Machine-verdict доки — гейт читает ТОЛЬКО YAML-frontmatter (никогда прозу), маппит ключ в вердикт. Имя ключа чувствительно к регистру; значение парсер приводит к верхнему регистру.

Документ	Machine-key	Парсер (src/qg/checks.py)	Эффект вердикта
12-review.md	verdict:	check_reviewer_verdict	APPROVED → дальше; REQUEST_CHANGES → откат на development
13-test-report.md	result: / verdict: / status:	_parse_tests_verdict	PASS → дальше; FAIL/BLOCKED → откат
14-deploy-log.md	deploy_status:	_parse_deploy_status	SUCCESS → done; FAILED → откат (БАГ-8)
15-staging-log.md	staging_status:	_parse_staging_status	SUCCESS → дальше; FAILED → откат (self-hosting; иначе N/A)
17-security-report.md	security_status:	check_security_gate	PASS → дальше; FAIL → откат
18-coverage-report.md	coverage_status:	check_coverage_gate	PASS → дальше; FAIL → откат на development

Информационные доки — гейтом НЕ парсятся (структура ничего не блокирует): 00-business-request.md (вход), 08-data-requirements.md, 10-tech-risks.md, 16-post-deploy-log.md (несёт post_deploy_status:, но это телеметрия петли уроков ORCH-8 / наблюдаемость, не гейт).

---

4. Конвенция ADR-naming

Per-work-item ADR (основное)

• Путь: docs/work-items/<plane-id>/06-adr/
• Имя файла: ADR-NNN-<kebab-slug>.md
  • NNN — 3-значный, начинается с 001; инкремент при нескольких ADR в одной задаче (ADR-001-…, ADR-002-…).
  • <kebab-slug> — kebab-case (нижний регистр, слова через дефис), отражает суть решения.
• Стадия: пишет architect на стадии architecture; гейтится check_architecture_done (наличие каталога 06-adr/ ≥ 1 файла).

Сквозной (cross-cutting) ADR

Решения, затрагивающие несколько компонентов/ролей или поведение всего конвейера, дублируются в глобальный реестр:

• Путь: docs/architecture/adr/
• Имя файла: adr-NNNN-<kebab-slug>.md (4-значная сквозная нумерация, последовательная по всему репозиторию; на момент ORCH-075 реестр доходит до adr-0019).

Примеры из репозитория (реальные, проверенные)

• docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md
• docs/work-items/ORCH-089/06-adr/ADR-001-auto-label-gates.md
• docs/work-items/ORCH-071/06-adr/ADR-001-merge-verify-gate.md
• Сквозные: docs/architecture/adr/adr-0017-serial-gate.md, docs/architecture/adr/adr-0018-auto-label-gates.md.

---

5. Как пользоваться шаблонами

1. Скопируй нужный скелет из docs/_templates/ в docs/work-items/<plane-id>/ под канонным именем (для ADR — 06-adr/ADR-001-<slug>.md).
2. Заполни секции; не удаляй machine-key frontmatter у machine-verdict доков и не меняй имя ключа (регистр чувствителен — иначе гейт упадёт ложно).
3. Сверяйся с манифестом (§2–§3): какой агент, на какой стадии, какой гейт читает документ.

Стандарт описательный (слой 1). Машинный слой реализован в ORCH-52c (ORCH-076): единый frontmatter-контракт (reader + writer + валидатор) в src/frontmatter.py и формальная спека handoff HANDOFF_PROTOCOL.md («стадия → обязательный выход» + обязательная frontmatter-схема REQUIRED_FIELDS). Пять вердикт-парсеров (check_reviewer_verdict, _parse_tests_verdict, _parse_deploy_status, _parse_staging_status, parse_security_status) читают вердикт через ОДНУ точку парсинга (parse_frontmatter); семантика вердиктов 1:1. Валидатор обязательной схемы по умолчанию warning-only (kill-switch frontmatter_validation_strict, дефолт False) — соблюдение схемы пока на ответственности агента и reviewer'а, enforcement придёт с ORCH-52d.

---

6. Спека handoff (машинный контракт, ORCH-52c)

Вертикальный срез «стадия → обязательные документы + frontmatter-ключи на выходе» и обязательная frontmatter-схема вынесены в отдельную нормативную спеку HANDOFF_PROTOCOL.md (набор документов/ключей/гейтов согласован 1:1 с §2–§3 этого манифеста). Машинный источник обязательной схемы — frontmatter.REQUIRED_FIELDS.