admin/orchestrator
1
0
Fork 0
Code Issues Pull Requests 3 Actions 1 Packages Projects Releases Wiki Activity
Files
7a2c019964e8dc1485dced537bf651540fba9f5f
orchestrator/docs/_standards/PIPELINE_DOCS.md
claude-bot d6b495f156
All checks were successful
CI / test (push) Successful in 1m14s
Details
CI / test (pull_request) Successful in 1m11s
Details
fix(analysis): activate analyst open-questions -> Needs Input flow (ORCH-120) 
Activates and completes the previously dead "analyst asks BLOCKING questions ->
01-questions.md -> Needs Input" path. Four coordinated changes, additive, under
kill-switch, self-hosting scope, never-raise; STAGE_TRANSITIONS / QG_CHECKS /
check_* / machine-verdict keys / DB schema are byte-for-byte UNCHANGED (the flow
is a pre-gate engine branch, NOT a Quality Gate; 01-questions.md is a SIGNAL
artifact, NOT a machine-verdict).

- D1 contract + canon: analyst.md documents the 01-questions.md channel (blocking
  questions -> Needs Input, do NOT fabricate deliverables) + resume behaviour; new
  skeleton docs/_templates/01-questions.md; PIPELINE_DOCS.md manifest row + 01-
  prefix note.
- D2 freshness-supersede (DQ-2): pure offline mtime predicate questions_active in
  the new leaf src/analyst_questions.py (a full FRESH package supersedes a stale
  untouched 01-questions.md -> no Needs-Input loop, AC-6).
- D3 priority: questions take priority over "files ready" in
  _handle_analysis_approved_flow (_decide_analysis_outcome + _emit_analysis_*);
  off/out-of-scope runs the ORIGINAL byte-for-byte order (AC-9).
- D4 auto-park: set_task_paused on Needs Input via the ORCH-124 pause axis so the
  repo serial-gate FIFO is not wedged while waiting for a human (AC-4); D5 resume +
  unpark (clear_task_paused) in handle_status_start (analysis branch).

Flags (config.py, safe defaults): analyst_questions_gate_enabled /
analyst_questions_gate_repos (empty -> self-hosting only) /
analyst_needs_input_autopause_enabled.

Tests: test_orch120_analyst_needs_input.py (TC-01 regress + TC-02/03/06/09/10),
test_orch120_serial_gate_needs_input.py (TC-04), test_orch120_resume_unpark.py
(TC-05), test_orch120_questions_artifact_canon.py (TC-08), assert in
test_agent_prompts_canon.py (TC-07). Full suite green (2205 passed).

Refs: ORCH-120

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-17 13:15:27 +03:00

161 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`) | — |
| `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/`](../_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`.
Reference in New Issue View Git Blame Copy Permalink