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`)	—
`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 номера, в текущем каноне не используются.

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. Как пользоваться шаблонами

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

13 KiB Raw Blame History Unescape Escape