142 lines
14 KiB
Markdown
142 lines
14 KiB
Markdown
# 02 — ТЗ (TRZ): ORCH-075 — ORCH-52b: стандарт документов
|
||
|
||
Work Item: **ORCH-075** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
> ТЗ описывает **конкретные артефакты к созданию** (манифест + шаблоны + раздел ADR-naming) и
|
||
> их обязательное содержимое, выведенное из фактических `STAGE_TRANSITIONS`/`QG_CHECKS` и
|
||
> эталонных доков. Это **docs-only** изменение: исходный код, гейты, схема БД, промпты —
|
||
> НЕ затрагиваются (см. §7). Архитектурное обоснование/решения — задача архитектора (06-adr).
|
||
|
||
## 1. Сводка изменения
|
||
Создать каталоги `docs/_standards/` и `docs/_templates/`, наполнить их манифестом
|
||
«стадия→документ», каноническими скелетами номерных доков и зафиксировать ADR-naming.
|
||
Обновить точки-ссылки (`CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`).
|
||
|
||
## 2. Задействованные модули / пути
|
||
| Путь | Действие |
|
||
|------|----------|
|
||
| `docs/_standards/PIPELINE_DOCS.md` | **создать** — манифест стадия→документ + раздел ADR-naming |
|
||
| `docs/_templates/00-business-request.md` | **создать** — шаблон |
|
||
| `docs/_templates/01-brd.md` | **создать** |
|
||
| `docs/_templates/02-trz.md` | **создать** |
|
||
| `docs/_templates/03-acceptance-criteria.md` | **создать** |
|
||
| `docs/_templates/04-test-plan.yaml` | **создать** |
|
||
| `docs/_templates/06-adr-ADR-NNN-slug.md` | **создать** — шаблон ADR (имя файла шаблона без коллизии с реальной нумерацией) |
|
||
| `docs/_templates/07-infra-requirements.md` | **создать** (when-applicable) |
|
||
| `docs/_templates/08-data-requirements.md` | **создать** (when-applicable) |
|
||
| `docs/_templates/10-tech-risks.md` | **создать** |
|
||
| `docs/_templates/12-review.md` | **создать** (frontmatter `verdict:`) |
|
||
| `docs/_templates/13-test-report.md` | **создать** (frontmatter `result:`) |
|
||
| `docs/_templates/14-deploy-log.md` | **создать** (frontmatter `deploy_status:`) |
|
||
| `docs/_templates/15-staging-log.md` | **создать** (frontmatter `staging_status:`) |
|
||
| `docs/_templates/16-post-deploy-log.md` | **создать** (frontmatter `post_deploy_status:`) |
|
||
| `docs/_templates/17-security-report.md` | **создать** (frontmatter `security_status:`) |
|
||
| `CLAUDE.md` | **изменить** — ссылка на стандарт в разделе «Артефакты задачи» / «Правила для агентов» |
|
||
| `docs/architecture/README.md` | **изменить** — ссылка на стандарт |
|
||
| `CHANGELOG.md` | **изменить** — запись в `## [Unreleased]` |
|
||
|
||
> Точное имя файла-шаблона ADR оставлено на усмотрение разработчика/архитектора при условии,
|
||
> что **внутри** шаблона и в манифесте зафиксирован реальный целевой формат
|
||
> `06-adr/ADR-NNN-<kebab-slug>.md` (см. §3, FR-3).
|
||
|
||
## 3. Функциональные требования
|
||
|
||
### FR-1 — Манифест `docs/_standards/PIPELINE_DOCS.md`
|
||
Содержит таблицу-манифест, покрывающую **все** номерные доки реального набора. Для каждого —
|
||
колонки: `Документ`, `Владелец-агент`, `Категория`, `Стадия написания`, `Гейт/механизм
|
||
проверки`, `Frontmatter machine-key (если есть)`. Манифест ДОЛЖЕН соответствовать
|
||
ground-truth ниже (сверено по `src/`):
|
||
|
||
| Документ | Владелец-агент | Категория | Стадия написания | Гейт / проверка | 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` (наличие) | — |
|
||
| `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` (наличие каталога/ADR) | — |
|
||
| `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` | `result:`/`verdict:`/`status:` (PASS\|FAIL\|BLOCKED) |
|
||
| `14-deploy-log.md` | deployer / deploy-finalizer | required | `deploy` | `check_deploy_status` | `deploy_status:` (SUCCESS\|FAILED) |
|
||
| `15-staging-log.md` | deployer | required (self-hosting) | `deploy-staging` | `check_staging_status` (self-hosting; иначе N/A) | `staging_status:` (SUCCESS\|FAILED) |
|
||
| `16-post-deploy-log.md` | post-deploy-monitor | when-applicable | пост-`done` наблюдение (ORCH-021, не ребро `STAGE_TRANSITIONS`) | информационный (гейтом не парсится) | `post_deploy_status:` |
|
||
| `17-security-report.md` | security-гейт (детерминированный, ORCH-022) | when-applicable | под-гейт ребра `deploy-staging→deploy` | `check_security_gate` | `security_status:` (PASS\|FAIL) |
|
||
|
||
Примечания манифеста (обязательны):
|
||
- Под-гейты ребра `deploy-staging→deploy` (`check_security_gate` → `check_branch_mergeable` →
|
||
`check_staging_image_fresh`) — **не** строки `STAGE_TRANSITIONS`, а врезки в `advance_stage`.
|
||
- `09-review.md` — legacy fallback; канон — `12-review.md` (упомянуть примечанием, в основную
|
||
таблицу как канон не вносить).
|
||
- Категория `when-applicable` = пишется при наличии соответствующего предмета (инфра/данные/
|
||
security/post-deploy); её отсутствие — не нарушение.
|
||
|
||
### FR-2 — Шаблоны `docs/_templates/*`
|
||
Каждый шаблон — копируемый скелет. Обязательные элементы по типам (выведено из эталонов
|
||
ORCH-088/073/089/071):
|
||
|
||
- **Документы БЕЗ frontmatter** (`00`,`01`,`02`,`03`,`06-adr`,`07`,`08`,`10`): заголовок `#`,
|
||
строка метаданных `Work Item / Repo / Стадия`, и фиксированные `##`-секции (ниже §FR-2.1).
|
||
- **YAML-only**: `04-test-plan.yaml` — корневые ключи + список `tests:` (ниже §FR-2.2).
|
||
- **Документы С YAML-frontmatter** (`12`,`13`,`14`,`15`,`16`,`17`): блок `---…---` с
|
||
machine-key из таблицы FR-1 + body-секции.
|
||
|
||
#### FR-2.1 Обязательные секции по документу (минимальный канон)
|
||
- `00-business-request.md`: `# Business Request: <subject>`; строка `Work Item ID:`; `## Description`.
|
||
- `01-brd.md`: `## 1. Бизнес-контекст и проблема`, `## 2. Объём (scope)` (с `### В объёме`/`### Вне объёма`), `## 3. Заинтересованные стороны`, `## 4. Бизнес-требования (BR)`, `## 5. Нефункциональные требования (NFR)`, `## 6. Допущения и ограничения`, `## 7. Критерии успеха`, `## 8. Риски`.
|
||
- `02-trz.md`: `## 1. Сводка изменения`, `## 2. Задействованные модули`, `## 3. Функциональные требования`, `## 4. Изменения API`, `## 5. Изменения схемы БД`, `## 6. Требования к QG checks`, `## 7. Совместимость / регресс`.
|
||
- `03-acceptance-criteria.md`: преамбула формата; повторяемый блок `## AC-N — <title>` с `**Условие:**`, `- **PASS:**`, `- **FAIL:**`; опц. `## Сводная матрица AC ↔ FR/BR`.
|
||
- `06-adr (шаблон)`: `# ADR-NNN: <title>`, метаданные (`Work Item`,`Стадия: architecture`,`Сквозная регистрация:`), `## Статус`, `## Контекст`, `## Решение` (с `### Сводка` и `### D1 — …`), `## Альтернативы`, `## Последствия`, `## Ссылки`.
|
||
- `07-infra-requirements.md`: `# 07 — Инфра-требования`, нумерованные `## I-N. <topic>`.
|
||
- `08-data-requirements.md`: `# 08 — Требования к данным`, секции по таблицам/колонкам/миграциям.
|
||
- `10-tech-risks.md`: `# 10 — Технические риски`, таблица `| ID | Риск | Вер. | Влия. | Митигейшн |`, `## Сводный вывод`.
|
||
- `12-review.md`: frontmatter `type: review` / `work_item_id:` / `verdict:` / `version:`; body `## Summary`, `## Оси проверки`, `## Findings` (`### P0`/`### P1`/`### P2`), `## Документация`.
|
||
- `13-test-report.md`: frontmatter `type: test-report` / `work_item_id:` / `result:`; body `## Окружение`, `## Результаты` (`### Полный регресс`, `### Профильные сюиты`, `### Сопоставление с тест-планом`, `### Сопоставление с критериями приёмки`).
|
||
- `14-deploy-log.md`: frontmatter `deploy_status:` / `work_item:` / `hook_exit_code:` / `deployed_by:`; body — краткое описание деплоя.
|
||
- `15-staging-log.md`: frontmatter `staging_status:` / `timestamp:` / `base_url:`; body — `# Staging Gate Log` + результаты проверок.
|
||
- `16-post-deploy-log.md`: frontmatter `post_deploy_status:` / `action_taken:` / `work_item:`; body — окно наблюдения/серия/решение.
|
||
- `17-security-report.md`: frontmatter `security_status:` / `work_item:`; body — secret-scan + dependency-audit результаты.
|
||
|
||
#### FR-2.2 `04-test-plan.yaml`
|
||
Корень: `work_item:`, `title:`, `framework: pytest`, опц. `scope:`/`notes:`. Список `tests:`
|
||
с элементами `{ id: TC-NN, type: unit|integration, description, module: tests/…, expected: PASS }`.
|
||
|
||
### FR-3 — Конвенция ADR-naming
|
||
Зафиксировать в `PIPELINE_DOCS.md` отдельным разделом:
|
||
- Путь: `docs/work-items/<plane-id>/06-adr/`.
|
||
- Имя: `ADR-NNN-<kebab-slug>.md`, `NNN` с `001`, инкремент при нескольких ADR в одной задаче.
|
||
- `slug` — kebab-case (нижний регистр, дефисы), отражает суть решения.
|
||
- Сквозные (cross-cutting) решения дублируются в `docs/architecture/adr/adr-NNNN-<slug>.md`
|
||
(4-значная глобальная нумерация) — это уже существующая конвенция, лишь зафиксировать.
|
||
- Примеры из репо: `ADR-001-serial-gate`, `ADR-001-auto-label-gates`, `ADR-001-merge-verify-gate`.
|
||
|
||
### FR-4 — Точки-ссылки
|
||
- `CLAUDE.md`: в разделе «Артефакты задачи» и/или «Правила для агентов» добавить ссылку на
|
||
`docs/_standards/PIPELINE_DOCS.md` и `docs/_templates/` как golden source структуры доков.
|
||
- `docs/architecture/README.md`: добавить ссылку/абзац о стандарте документов.
|
||
- `CHANGELOG.md`: запись в `## [Unreleased]` (`docs:` тип).
|
||
|
||
## 4. Изменения API
|
||
Нет. Эндпоинты не добавляются и не меняются.
|
||
|
||
## 5. Изменения схемы БД
|
||
Нет. Таблицы/миграции не затрагиваются.
|
||
|
||
## 6. Требования к новым/изменённым QG checks
|
||
Нет. `QG_CHECKS` и `check_*` **не трогаются** (это ORCH-52c). Манифест лишь **документирует**
|
||
текущее поведение гейтов.
|
||
|
||
## 7. Совместимость / регресс
|
||
- Изменения только под `docs/` + `CLAUDE.md` + `CHANGELOG.md`. Поведение рантайма неизменно.
|
||
- Существующие доки прошлых задач не модифицируются (нет ретро-фита).
|
||
- `09-review.md` (legacy) сохраняется как fallback; манифест канонизирует `12-review.md`.
|
||
- Удаление новых файлов → полный откат без следов (NFR-5).
|
||
|
||
## 8. Артефакты, создаваемые/обновляемые по pipeline
|
||
Создаются: `docs/_standards/PIPELINE_DOCS.md`, `docs/_templates/*` (15 шаблонов).
|
||
Обновляются: `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`.
|
||
Downstream-доки самой задачи ORCH-075 (`06-adr`, `10-tech-risks`, `12-review`, `13-test-report`,
|
||
`14-deploy-log`, `15-staging-log`) — по штатному конвейеру.
|