architect(ET): auto-commit from architect run_id=448

This commit is contained in:
2026-06-09 13:08:12 +03:00
committed by orchestrator-deployer
parent 6511ddadbb
commit 3251c8c4ed
5 changed files with 290 additions and 0 deletions

View File

@@ -0,0 +1,49 @@
# adr-0019: Стандарт документов пайплайна (docs/_standards + docs/_templates + ADR-naming)
Статус: **proposed** · Дата: 2026-06-09 · Источник: **ORCH-075** (ORCH-52b, слой 1 эпика ORCH-52)
Детально: `docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md`.
## Контекст
Агенты всех ролей пишут номерные доки work item (`00…17`) «по памяти»; каталогов
`docs/_standards/` и `docs/_templates/` нет. Следствия: разнобой структуры между задачами; риск
рассинхрона критичных frontmatter-ключей машинных доков (`verdict:` / `result:` / `deploy_status:` /
`staging_status:` / `security_status:`), которые читает гейт; отсутствует целостная карта «стадия →
агент → документ → гейт». Эпик ORCH-52 слоист: слой 1 (52b) фиксирует **договорённость**, машинная
проверка/валидатор — отдельный слой 52c.
## Решение
**Документационный стандарт, docs-only, выведенный из фактического кода и эталонных доков:**
1. `docs/_standards/PIPELINE_DOCS.md` — манифест-карта «стадия → документ → владелец-агент →
категория (`required`/`when-applicable`/`optional`) → гейт/механизм → frontmatter machine-key».
Манифест **документирует** поведение гейтов (источник истины остаётся `src/`), честно различает
machine-verdict доки (`12,13,14,15,17`) и информационные (`00,08,10,16`), и помечает под-гейты
ребра `deploy-staging→deploy` (security/merge/image-freshness) как врезки в `advance_stage`, а не
строки `STAGE_TRANSITIONS`.
2. `docs/_templates/*` — копируемые скелеты для каждого `required`/`when-applicable` дока; секции
выведены из эталонов (ORCH-088/073/089/071), новые не изобретаются; машинные доки несут точный
frontmatter-ключ из ground-truth.
3. **ADR-naming** канонизирован: `docs/work-items/<plane-id>/06-adr/ADR-NNN-<kebab-slug>.md` (NNN с
`001`); кросс-каттинговые решения дублируются в этот глобальный реестр `adr-NNNN-<slug>.md`.
Подключение — ссылки из `CLAUDE.md` и `docs/architecture/README.md` + запись в `CHANGELOG.md`.
## Альтернативы
- Сразу валидатор на гейте — отвергнуто (ORCH-52c; нарушил бы docs-only/NFR-1, групповой риск).
- Манифест как источник истины гейтов — отвергнуто (дубль-истина «манифест ≠ код»).
- Шаблоны в `docs/work-items/_template/` — отвергнуто (риск для сканеров/гейтов наличия файлов).
- Ретро-фит истории доков — отвергнуто (вне scope, отдельный риск).
## Последствия
- **+** Единый golden source структуры доков; меньше ложных падений гейтов из-за неверного
frontmatter-ключа; ADR-naming записан; база для ORCH-52c.
- **+ Нулевой рантайм-риск:** только `docs/**` + `CLAUDE.md` + `CHANGELOG.md`; `STAGE_TRANSITIONS` /
`QG_CHECKS` / `check_*` / `src/stage_engine.py` / схема БД — без изменений; полностью обратимо.
- **** Манифест — снимок поведения гейтов, дрейфует до ORCH-52c (митигейшн: источник истины — код,
reviewer-правило, привязка к именам `check_*`); стандарт описательный, не принуждающий.
## Связи
- Источник: ORCH-075 (`docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md`).
- Документирует (не меняет): adr-0003/0006/0008/0012/0013/0014/0016 (гейты и под-гейты ребра),
`STAGE_TRANSITIONS` (`src/stages.py`), `QG_CHECKS` (`src/qg/checks.py`).
- Downstream: ORCH-52c (frontmatter-валидатор / writer-контракт), ORCH-52d (правка промптов).

View File

@@ -0,0 +1,160 @@
# ADR-001: Стандарт документов пайплайна (docs/_standards + docs/_templates + ADR-naming)
Work Item: **ORCH-075** (ORCH-52b — слой 1 эпика ORCH-52)
Стадия: **architecture**
Сквозная регистрация: **`docs/architecture/adr/adr-0019-pipeline-docs-standard.md`** (решение
кросс-каттинговое — задаёт правила доко-письма для ВСЕХ агентских ролей).
## Статус
Proposed
## Контекст
Агенты конвейера (`analyst → architect → developer → reviewer → tester → deployer` + системные
акторы deploy-finalizer / post-deploy-monitor / security-гейт) пишут номерные документы work item
(`00-business-request.md``17-security-report.md`) «с нуля по памяти». Каталогов
`docs/_standards/` и `docs/_templates/` не существует (проверено в репо). Следствия:
- **Разнобой структуры** одного и того же документа от задачи к задаче (набор/порядок секций
плавает) — затрудняет ревью и онбординг новых ролей.
- **Риск рассинхрона машинных вердиктов.** Доки `12-review.md` / `13-test-report.md` /
`14-deploy-log.md` / `15-staging-log.md` / `17-security-report.md` несут frontmatter-ключ,
который читает гейт (`verdict:` / `result:` / `deploy_status:` / `staging_status:` /
`security_status:`), но единого канонического скелета с этим ключом нет → агент может выдать
ключ не того имени/регистра и уронить гейт ложно.
- **Нет карты «стадия → агент → документ → гейт».** Какая роль пишет какой документ и где он
проверяется — нигде не зафиксировано целостно.
Эпик ORCH-52 намеренно разбит на слои: **сначала зафиксировать договорённость** (golden source
структуры доков), и лишь потом, отдельной задачей (52c), навесить машинную проверку
frontmatter/шаблонов на гейте. Слой 1 (эта задача) — **только документация**: манифест,
канонические шаблоны, конвенция ADR-naming. Любой валидатор/правка кода/правка промптов — вне
scope. Ключевое архитектурное ограничение задачи (NFR-1): **ни строки кода/гейтов** — изменения
строго под `docs/**` (+ `CLAUDE.md` / `CHANGELOG.md`).
Ground-truth для манифеста — **фактические** `STAGE_TRANSITIONS` (`src/stages.py`), `QG_CHECKS` /
`check_*` (`src/qg/checks.py`), `src/stage_engine.py` и реальные эталонные доки (ORCH-088/073/089/071),
а не вымысел. Сверка проведена на стадии architecture (см. §Решение D5).
## Решение
### Сводка
Создать **документационный стандарт** из трёх артефактов, выведенный из фактического кода и
эталонных доков, и подключить его ссылками из точек-онбординга. Никаких рантайм-изменений.
- `docs/_standards/PIPELINE_DOCS.md` — манифест-карта «стадия → документ → агент → категория →
гейт/механизм → frontmatter machine-key» + раздел ADR-naming.
- `docs/_templates/*` — копируемые скелеты для каждого `required` / `when-applicable` дока.
- Ссылки из `CLAUDE.md` и `docs/architecture/README.md`; запись в `CHANGELOG.md`.
### D1 — Местоположение и разделение «стандарт» vs «шаблон»
Два каталога с раздельной ответственностью: `docs/_standards/`**описательный** golden source
(манифест, конвенции, человекочитаемая карта); `docs/_templates/`**копируемые** скелеты для
заполнения. Префикс `_` выводит служебные каталоги наверх листинга и визуально отделяет их от
`docs/work-items/` / `docs/architecture/` / `docs/operations/`. Шаблоны — НЕ work item, не имеют
`<plane-id>`, не парсятся гейтами (живут вне `docs/work-items/`), поэтому не влияют на
`check_architecture_done` / `check_analysis_complete` и не попадают под ретро-фит.
### D2 — Манифест как производная от кода, а не параллельный источник истины
`PIPELINE_DOCS.md` **документирует** текущее поведение гейтов, но НЕ становится их источником
истины (источник остаётся `src/`). Это устраняет класс «манифест разошёлся с кодом»: при будущем
изменении гейта (ORCH-52c+) правка кода первична, манифест — следом. Манифест честно различает:
- **machine-verdict доки** (`12,13,14,15,17`) — несут frontmatter-ключ, читаемый гейтом; в
манифесте помечены ключом и именем `check_*`;
- **информационные доки** (`00,08,10,16`) — гейтом не парсятся; помечены явно как не-гейтящиеся
(чтобы не возникало ложного ожидания, что их структура что-то блокирует).
Под-гейты ребра `deploy-staging → deploy` (`check_security_gate``check_branch_mergeable`
`check_staging_image_fresh`) в манифесте отмечаются как **врезки в `advance_stage`**, а НЕ строки
`STAGE_TRANSITIONS` — иначе карта соврёт о топологии машины стадий (AC-7).
### D3 — Шаблоны выведены из эталонов, новые секции не изобретаются
Скелеты извлекаются из реальных «golden» задач (ORCH-088/073/089/071) и текущей задачи ORCH-075.
Инвариант (NFR-3): **в шаблоне нет секции, которой никто не пишет в эталонах**, и наоборот — общий
канон секций эталона присутствует. Минимальный обязательный набор секций по каждому документу
зафиксирован в TRZ §FR-2.1 и является контрактом приёмки (AC-2/AC-4). Документы с машинным
вердиктом несут в шаблоне точный frontmatter-ключ из ground-truth таблицы (D5), чтобы скопированный
скелет проходил гейт без догадок.
### D4 — ADR-naming: канонизация сложившейся традиции, не новый формат
Зафиксировать **уже существующий** формат, не вводя нового:
- Путь: `docs/work-items/<plane-id>/06-adr/`.
- Имя: `ADR-NNN-<kebab-slug>.md`; `NNN` с `001`, инкремент при нескольких ADR в одной задаче.
- `slug` — kebab-case (нижний регистр, дефисы), отражает суть решения.
- Кросс-каттинговые решения **дублируются** в глобальном реестре
`docs/architecture/adr/adr-NNNN-<slug>.md` (4-значная сквозная нумерация) — это уже действующая
конвенция (подтверждено: реестр идёт до `adr-0018`), лишь записывается.
- Примеры из репо (проверены): `ADR-001-serial-gate`, `ADR-001-auto-label-gates`,
`ADR-001-merge-verify-gate`.
Сам этот ADR следует конвенции и дублируется как `adr-0019` — стандарт демонстрирует себя.
### D5 — Достоверность: сверка манифеста с `src/` на стадии architecture (NFR-2)
Перед фиксацией манифеста ground-truth сверен с кодом. Подтверждено:
| Документ | Гейт / механизм | Machine-key | Подтверждено в |
|----------|-----------------|-------------|----------------|
| `0104` | `check_analysis_approved` (exit `analysis→architecture`); helper `check_analysis_complete` (наличие `01/02/03/04`) | — | `stages.py`, `qg/checks.py:check_analysis_complete` |
| `06-adr/` | `check_architecture_done` (наличие каталога `06-adr/` ≥1 файл ИЛИ `07-infra-requirements.md`) | — | `qg/checks.py:check_architecture_done` |
| `12-review.md` | `check_reviewer_verdict` | `verdict:` | `qg/checks.py` |
| `13-test-report.md` | `check_tests_passed` | `result:`/`verdict:`/`status:` (три равноранговых, ORCH-047) | `qg/checks.py:_parse_tests_verdict` |
| `14-deploy-log.md` | `check_deploy_status` | `deploy_status:` | `qg/checks.py:_parse_deploy_status` |
| `15-staging-log.md` | `check_staging_status` (self-hosting; иначе N/A — ORCH-35) | `staging_status:` | `qg/checks.py:_parse_staging_status` |
| `17-security-report.md` | `check_security_gate` (под-гейт ребра `deploy-staging→deploy`) | `security_status:` | `qg/checks.py` |
| `16-post-deploy-log.md` | информационный (пост-`done` наблюдение ORCH-021, не ребро) | `post_deploy_status:` (не гейтится) | `stage_engine.run_post_deploy_monitor` |
| `00/08/10` | не гейтятся (вход / информационные) | — | — |
`STAGE_TRANSITIONS` (проверено): `analysis→architecture→development→review→testing→deploy-staging
→deploy→done`; рёбра несут ровно `check_analysis_approved / check_architecture_done / check_ci_green
/ check_reviewer_verdict / check_tests_passed / check_staging_status / check_deploy_status`.
Под-гейты `security/merge/image-freshness` в `STAGE_TRANSITIONS` **отсутствуют** (врезки в
`advance_stage`) — подтверждает D2.
### D6 — Разграничение ответственности стадий (что пишет архитектор vs разработчик)
Эта стадия (architecture) производит **только** ADR + tech-risks (+ N/A infra/data). Сами артефакты
стандарта (`PIPELINE_DOCS.md`, `docs/_templates/*`) и правки точек-ссылок
(`CLAUDE.md` / `docs/architecture/README.md` / `CHANGELOG.md`) создаёт стадия development по TRZ §2 —
чтобы не было двойного авторства и конфликтов. Архитектор фиксирует **контракт** (что и где должно
появиться, по каким инвариантам), разработчик его **реализует**.
## Альтернативы
- **Один файл-стандарт без каталога шаблонов** — отвергнуто: шаблон должен быть копируемым
отдельным файлом (UX «скопировал и заполнил», AC-2), а не вырезкой из прозы манифеста.
- **Сразу валидатор frontmatter на гейте** — отвергнуто намеренно (это ORCH-52c): нарушило бы
NFR-1 (правка кода/гейтов) и подняло бы групповой self-hosting риск без предварительной фиксации
договорённости. Слой «стандарт» обязан предшествовать слою «проверка».
- **Манифест как источник истины для гейтов** — отвергнуто: породило бы дубль-истину и класс
«манифест ≠ код». Источник остаётся `src/`; манифест — производная (D2).
- **Положить шаблоны в `docs/work-items/_template/`** — отвергнуто: попадание под `docs/work-items/`
с `<plane-id>`-семантикой риск-фактор для гейтов наличия файлов и сканеров; служебный каталог
должен быть вне дерева work item (D1).
- **Ретро-фит существующих доков под новый шаблон** — отвергнуто (вне scope, BRD §2.2): массовая
правка истории — отдельный риск и шум; стандарт применяется к новым задачам вперёд.
- **Не заводить глобальный `adr-0019`** — отвергнуто: решение кросс-каттинговое (правила
доко-письма для всех ролей), а FR-3 сам канонизирует дублирование сквозных решений в глобальный
реестр — стандарт обязан следовать собственному правилу.
## Последствия
- **+** Единая карта «стадия → агент → документ → гейт → machine-key»; копируемые скелеты →
меньше разнобоя и ложных падений гейтов из-за неверного frontmatter-ключа; ADR-naming перестаёт
быть устной традицией; готовая база для ORCH-52c (валидатор).
- **+ Нулевой рантайм-риск (NFR-1/NFR-5):** изменения только под `docs/**` + `CLAUDE.md` +
`CHANGELOG.md`. `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / `src/stage_engine.py` / схема БД —
**не трогаются**. Удаление новых файлов полностью откатывает изменение без следов в поведении
системы (обратимость).
- ** Дрейф во времени:** манифест — снимок поведения гейтов; при будущей правке гейта его нужно
обновлять вручную (до ORCH-52c, где появится проверка). Митигейшн: D2 (источник истины — код) +
reviewer-правило «обновлена ли документация» + явная привязка манифеста к именам `check_*`.
- **** Стандарт описательный, не принуждающий: агент может его проигнорировать (форсинг — 52c).
Осознанно принято как цена слоистого подхода.
- **Откат:** удалить `docs/_standards/PIPELINE_DOCS.md`, `docs/_templates/*`, снять ссылки и запись
CHANGELOG — система ведёт себя в точности как до ORCH-075.
## Ссылки
- BRD: `docs/work-items/ORCH-075/01-brd.md`
- TRZ: `docs/work-items/ORCH-075/02-trz.md` (ground-truth таблица FR-1, секции FR-2.1)
- Acceptance: `docs/work-items/ORCH-075/03-acceptance-criteria.md`
- Tech-risks: `docs/work-items/ORCH-075/10-tech-risks.md`
- Глобальный реестр: `docs/architecture/adr/adr-0019-pipeline-docs-standard.md`
- Эталоны скелетов: ORCH-088 / ORCH-073 / ORCH-089 / ORCH-071 (`docs/work-items/*/`)
- Сверено по коду: `src/stages.py` (`STAGE_TRANSITIONS`), `src/qg/checks.py` (`QG_CHECKS`,
`_parse_*`), `src/stage_engine.py`.

View File

@@ -0,0 +1,25 @@
# 07 — Инфра-требования: ORCH-075 (ORCH-52b — стандарт документов)
Work Item: **ORCH-075** · Repo: **orchestrator** · Стадия: architecture
## I-1. Топология / окружения
**N/A.** Изменение docs-only: создаются `docs/_standards/PIPELINE_DOCS.md`, `docs/_templates/*` и
правятся `CLAUDE.md` / `docs/architecture/README.md` / `CHANGELOG.md`. Контейнеры (`orchestrator`
8500, `orchestrator-staging` 8501), Docker Compose, сеть, тома, хост mva154 — **не затрагиваются**.
## I-2. Переменные окружения / секреты
**N/A.** Новые env-переменные не вводятся; `.env` / `.env.staging` / `.env.example` не меняются;
секретов не добавляется.
## I-3. Деплой / рестарт
**N/A.** Рантайм-поведение не меняется → прод-рестарт не требуется. Изменение проходит штатный
self-hosting путь (`deploy-staging` 8501 → `deploy` 8500) как обычный PR, но эффект деплоя — лишь
появление новых docs-файлов в образе; функциональной нагрузки на рестарт нет. Self-hosting инвариант
соблюдён: **не ронять / не рестартить прод вне staging-гейта** — здесь это и не нужно.
## I-4. CI/CD
Без изменений в `.gitea/workflows/`. Добавляется один тестовый файл
`tests/test_orch_52b_docs_standard.py` (структурные проверки), исполняемый существующим pytest-шагом.
> Вывод: инфраструктурных требований нет. Файл создан для аудитопригодности (явное N/A), а не из-за
> изменения топологии.

View File

@@ -0,0 +1,28 @@
# 08 — Требования к данным: ORCH-075 (ORCH-52b — стандарт документов)
Work Item: **ORCH-075** · Repo: **orchestrator** · Стадия: architecture
## Изменения схемы БД
**N/A.** Изменение docs-only. Таблицы SQLite (`jobs`, `tasks`, `job_deps`, `repo_freeze`,
`agent_runs`, `tracker_messages`, …), индексы, миграции (`init_db`) — **не затрагиваются**.
## Новые/изменённые сущности
**Нет.** Манифест и шаблоны — статические Markdown/YAML-файлы под `docs/`, вне модели данных
рантайма. Гейты наличия файлов (`check_analysis_complete` / `check_architecture_done`) сканируют
только `docs/work-items/<plane-id>/` и служебные каталоги `docs/_standards/` / `docs/_templates/` не
видят (см. ADR-001 §D1, риск TR-6).
## Frontmatter machine-keys (документируются, не вводятся)
Стандарт лишь **фиксирует** уже существующие машиночитаемые ключи, которые парсят гейты — это НЕ
новые поля данных и не изменение хранения:
| Документ | Ключ | Парсер (`src/qg/checks.py`) |
|----------|------|-----------------------------|
| `12-review.md` | `verdict:` | `check_reviewer_verdict` |
| `13-test-report.md` | `result:` / `verdict:` / `status:` | `_parse_tests_verdict` |
| `14-deploy-log.md` | `deploy_status:` | `_parse_deploy_status` |
| `15-staging-log.md` | `staging_status:` | `_parse_staging_status` |
| `17-security-report.md` | `security_status:` | `check_security_gate` |
| `16-post-deploy-log.md` | `post_deploy_status:` | информационный (не гейтится) |
> Вывод: требований к данным/схеме нет. Файл создан для аудитопригодности (явное N/A).

View File

@@ -0,0 +1,28 @@
# 10 — Технические риски: ORCH-075 (ORCH-52b — стандарт документов)
Work Item: **ORCH-075** · Repo: **orchestrator** · Стадия: architecture
> Изменение docs-only (NFR-1): только `docs/**` + `CLAUDE.md` + `CHANGELOG.md`. Рантайм-рисков
> деградации прода нет по построению. Основные риски — **достоверность** манифеста и **дрейф**
> стандарта относительно кода.
## Реестр рисков
| ID | Риск | Вер. | Влия. | Митигейшн |
|----|------|------|-------|-----------|
| TR-1 | **Рассинхрон манифеста с кодом** — манифест приписывает доку неверную стадию/гейт/агента или неверный frontmatter-ключ (напр. `12-review` → не `verdict:`). | Сред. | Сред. (вводит агентов в заблуждение, ложные ожидания) | NFR-2: ground-truth сверен с `src/stages.py` / `src/qg/checks.py` / `src/stage_engine.py` на стадии architecture (ADR-001 §D5, таблица сверки). AC-4 проверяет привязку буквально по файлам. Источник истины остаётся код (D2). |
| TR-2 | **Дрейф во времени** — будущая правка гейта (ORCH-52c+) не отражается в манифесте, т.к. форсинга нет. | Сред. | Низ. (до 52c — описательный документ) | D2 (источник истины — код, манифест производный); reviewer-правило «обновлена ли документация»; явная привязка строк манифеста к именам `check_*`; ORCH-52c добавит машинную проверку. |
| TR-3 | **Шаблон вводит выдуманную секцию** или, наоборот, упускает секцию общего канона эталонов. | Сред. | Низ. | NFR-3: скелеты выведены строго из эталонов ORCH-088/073/089/071 + ORCH-075; TRZ §FR-2.1 фиксирует минимальный обязательный набор секций; AC-2/AC-4 проверяют. |
| TR-4 | **Неверный machine-key в шаблоне машинного дока** — скопированный скелет уронит гейт ложно (напр. `deploy_status` написан `Deploy-Status`/иной регистр). | Низ. | Выс. (если бы дошло до прода — ложный откат БАГ-8) | Ключи в шаблонах берутся ДОСЛОВНО из `_parse_*` (`deploy_status`/`staging_status`/`security_status`/`verdict`/`result`); парсеры делают `.upper()` на значении, но имя ключа чувствительно — шаблон фиксирует точное имя. AC-2 проверяет наличие ключа. Гейты при этом **не трогаются** (docs-only). |
| TR-5 | **Коллизия имени файла-шаблона ADR** с реальной нумерацией (`06-adr/ADR-NNN-…`). | Низ. | Низ. | TRZ §2: имя шаблона ADR без `<plane-id>`-контекста и вне `docs/work-items/` (напр. `docs/_templates/06-adr-ADR-NNN-slug.md`); внутри фиксируется реальный целевой путь/формат. |
| TR-6 | **Шаблоны парсятся гейтами наличия файлов** (`check_architecture_done` / `check_analysis_complete` ловят `docs/_templates/*`). | Оч.низ. | Сред. | D1: служебные каталоги `docs/_standards/` / `docs/_templates/` лежат ВНЕ `docs/work-items/<plane-id>/`; гейты сканируют только путь work item → шаблоны структурно невидимы гейтам. |
| TR-7 | **Регресс существующих тестов** от docs-изменения. | Оч.низ. | Сред. | Изменения не трогают `src/`; новый тест `tests/test_orch_52b_docs_standard.py` — только структурные проверки наличия/секций; TC-21 требует зелёного полного `pytest tests/`. |
| TR-8 | **CHANGELOG-конфликт при merge** (`## [Unreleased]` правят параллельные задачи). | Низ. | Низ. | Корневой `.gitattributes` `CHANGELOG.md merge=union` (ORCH-073 FR-4) авто-сливает append-правки без конфликта. |
## Сводный вывод
Риск для прод-конвейера (self-hosting) — **отсутствует по построению**: изменение docs-only,
полностью обратимо (NFR-5), `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / схема БД не затрагиваются
(AC-6). Доминирующий класс рисков — **достоверность и дрейф** манифеста (TR-1/TR-2); закрыт сверкой
с `src/` на стадии architecture (ADR-001 §D5) и принципом «источник истины — код, манифест —
производная». Эскалация `arch:major-change` не требуется (нет новой стадии/QG/компонента/смены БД).
Возврат в анализ не требуется — ТЗ удовлетворяется без нарушения принципов архитектуры.