# 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/`](../_templates/):
> «скопировал → заполнил → не угадываешь структуру/ключ».

Введён задачей **ORCH-075** (ORCH-52b — слой 1 эпика ORCH-52). Сквозной ADR:
[`docs/architecture/adr/adr-0019-pipeline-docs-standard.md`](../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. Как пользоваться шаблонами

1. Скопируй нужный скелет из [`docs/_templates/`](../_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`](../../src/frontmatter.py)
> и формальная спека handoff [`HANDOFF_PROTOCOL.md`](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`](HANDOFF_PROTOCOL.md)
(набор документов/ключей/гейтов согласован 1:1 с §2–§3 этого манифеста). Машинный источник
обязательной схемы — `frontmatter.REQUIRED_FIELDS`.