claude-bot
e6fb3682d3
Создан golden source структуры номерных документов work item (ORCH-52b, слой 1 эпика ORCH-52). Docs-only: STAGE_TRANSITIONS / QG_CHECKS / check_* / схема БД не трогаются (AC-6). - docs/_standards/PIPELINE_DOCS.md — манифест «стадия→агент→документ→категория→ гейт→frontmatter machine-key» (сверен с src/stages.py и src/qg/checks.py) + раздел ADR-naming. Манифест документирует поведение гейтов, источник истины остаётся код (ADR-001 §D2); честно различает machine-verdict (12/13/14/15/17) и информационные (00/08/10/16) доки; под-гейты ребра deploy-staging→deploy отмечены как врезки в advance_stage. - docs/_templates/* — 15 копируемых скелетов; машинные доки несут точный frontmatter-ключ из _parse_* (verdict/result/deploy_status/staging_status/ security_status/post_deploy_status). - Точки-ссылки: CLAUDE.md, docs/architecture/README.md; запись CHANGELOG. - tests/test_orch_52b_docs_standard.py — TC-01..TC-20 структурные проверки; полный pytest tests/ зелёный (1177 passed). Refs: ORCH-075 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
139 lines
11 KiB
Markdown
139 lines
11 KiB
Markdown
# PIPELINE_DOCS — стандарт документов конвейера (golden source структуры)
|
||
|
||
> **Назначение.** Единая карта «стадия → агент → документ → категория → гейт/механизм →
|
||
> frontmatter machine-key» + конвенция ADR-naming. Это **golden source структуры** номерных
|
||
> документов work item (`00-business-request.md` … `17-security-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`) |
|
||
|
||
### Примечания манифеста (нормативные)
|
||
|
||
- **Под-гейты ребра `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` → откат |
|
||
|
||
**Информационные доки** — гейтом НЕ парсятся (структура ничего не блокирует):
|
||
`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). Машинная проверка соответствия шаблонам/frontmatter —
|
||
> отдельная задача ORCH-52c; до неё соблюдение — на ответственности агента и reviewer'а
|
||
> (правило CLAUDE.md «обновлена ли документация»).
|