architect(ET): auto-commit from architect run_id=448
This commit is contained in:
49
docs/architecture/adr/adr-0019-pipeline-docs-standard.md
Normal file
49
docs/architecture/adr/adr-0019-pipeline-docs-standard.md
Normal 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 (правка промптов).
|
||||
@@ -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 | Подтверждено в |
|
||||
|----------|-----------------|-------------|----------------|
|
||||
| `01–04` | `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`.
|
||||
25
docs/work-items/ORCH-075/07-infra-requirements.md
Normal file
25
docs/work-items/ORCH-075/07-infra-requirements.md
Normal 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), а не из-за
|
||||
> изменения топологии.
|
||||
28
docs/work-items/ORCH-075/08-data-requirements.md
Normal file
28
docs/work-items/ORCH-075/08-data-requirements.md
Normal 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).
|
||||
28
docs/work-items/ORCH-075/10-tech-risks.md
Normal file
28
docs/work-items/ORCH-075/10-tech-risks.md
Normal 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/компонента/смены БД).
|
||||
Возврат в анализ не требуется — ТЗ удовлетворяется без нарушения принципов архитектуры.
|
||||
Reference in New Issue
Block a user