Шаблоны контрибьюта — design, задача, отчёт

Заполнители к CONTRIBUTING.md. Каждый <…> заменяется текстом, NNN — номером строки из прочитанного кода. Пустой раздел не оставляется: если раздел к изменению не относится, пишется «не затрагивается — потому что <причина, проверенная командой>». Формат квитанции ревью здесь не повторяется — он в docs/operations/design-review-gate.md §«Квитанция».

design.md

## Context

<Что есть сейчас: файлы и строки, которые изменение затрагивает. Метод
исследования — команды, которыми это установлено, с результатами.>

## Goals / Non-Goals

- Цель: <проверяемый признак успеха>
- Не входит: <что заведомо не делается и почему>

## Модель данных

| Сущность | Что меняется | Единственный писатель | Миграция |
|---|---|---|---|
| `<таблица.колонка>` | <создаётся/меняется/удаляется> | `<Тип::метод>` (`<файл>:NNN`) | <версия контракта, файл миграции либо «нет»> |

Проверено: `rg -n '<таблица>' crates/pm-engine/src --glob '!*_tests.rs' --glob '!**/tests/**'` → <список файлов>.

## Интерфейсы

| Порт/метод | Новый или меняется | Вызывающие (`файл:строка`) | Реализует | Default-тело |
|---|---|---|---|---|
| `<Порт::метод(сигнатура)>` | <новый/меняется> | `<файл>:NNN` | `<тип адаптера>` | нет |

Проверено: `rg -n '\.<метод>\(' crates/pm-engine/src --glob '!*_tests.rs' --glob '!**/tests/**'` → <N совпадений>.

## Место в жизненном цикле

Участник: `<компонент>`. Фаза: <запуск/прогрев/работа/остановка/завершение>.
Стартует: `<кто>` (`<файл>:NNN`). Останавливает: `<кто>` (`<файл>:NNN`).
При остановке ждём: <что именно, или «ничего — потому что …»>.

## Поток данных

<Откуда → куда.> Строки `events` в той же транзакции: <перечень или «нет»>.
Публикация на `EventBus` после `commit()`: `<файл>:NNN`. Исполняется в
задаче: <тракт стратегии / отдельная фоновая задача / приёмник наблюдений>.

## Контекст

Вход: `<тип>` (`event_id`, ревизия, стадия — <какие>). Выход: `<тип>`.
Разрыв «текущее ≠ цель» по `docs/target/event-context.md`: <назван или «нет»>.

## Конфликты

| Сценарий | Что делает код | Где |
|---|---|---|
| конкурентная запись | <…> | `<файл>:NNN` |
| повтор / дубликат | <…> | `<файл>:NNN` |
| сбой посередине операции | <…> | `<файл>:NNN` |
| отказ внешней системы | <…> | `<файл>:NNN` |
| деньги и округление | <инвариант и точка синхронной проверки> | `<файл>:NNN` |

## Скорость

На горячем пути: <да/нет, что именно>. Добавляется: аллокаций <N>, копий <N>,
vtable-диспетчей <N> — по коду `<файл>:NNN`. В фоновую задачу уходит: <что>.

## Тесты

| Требование | Положительный тест | Отрицательный тест | Двойники |
|---|---|---|---|
| <формулировка из spec> | `<файл>::<тест>` | `<файл>::<тест>` | `support::<…>` / `crate::testing::<…>` |

Проверено: `rg -n 'impl <Порт> for' crates/pm-engine/tests crates/pm-engine/src` → новых копий нет.

## Дублирование

| Что нужно | Уже есть | Решение |
|---|---|---|
| `<функция/тип>` | `<крейт>::<путь>` (`<файл>:NNN`) либо «нет — `rg -n '<имя>' crates/` → 0» | используем / выносим в `<общий модуль>` ДО реализации |

## Decisions

### D1. <Название решения>

Контекст: <…>. Варианты: (а) <…>; (б) <…>. Компромиссы: <…>. Риски: <…>.
Рекомендация: <вариант> — потому что <…>. Проверка: <команда → ожидаемый вывод>.

## Risks / Trade-offs

- <риск> → <чем ограничен>

## Migration Plan

1. <шаг> — проверка: <команда → вывод>

## Open Questions

- <вопрос оператору, без которого меняется поведение> — либо «нет»

Строка задачи в tasks.md

- [ ] 2.1 <Что сделать — одно наблюдаемое изменение>. Проверка: `<команда>` → `<ожидаемый вывод>`.

Закрытие задачи — только - [ ] → - [x]. Наблюдение (фактический вывод команды-проверки, отклонения) записывается в отчёт, а не дописывается в текст задачи: дописанный текст меняет слепок квитанции и обесценивает вердикт круга 2.

Строка CHANGELOG.md

2026-09-01 | Claude Code | <описание ≤100 знаков: что изменилось, не «обновил документацию»> | ????????

???????? заменяет хешем координатор после вливания в main.

Отчёт

## Задача
<одна строка: что требовалось; дерево — вывод `git rev-parse --show-toplevel`>

## Что сделано
- `<файл>:NNN` — <что изменено и зачем>
- прочитаны AGENTS.md: `<путь>`, `<путь>`
- отклонения от design: <нет / что и где записано>

## Как проверяли
| Команда | Вывод |
|---|---|
| `cargo fmt --all -- --check` | пусто, код 0 |
| `cargo clippy --locked -p <крейт> --all-targets -- -D warnings` | `Finished`, 0 предупреждений |
| тесты `<крейт>` | `binaries=<n> passed=<p> failed=0 ignored=<i>` |
| `bash scripts/arch-gate.sh` | все `OK` |
| `bash scripts/design-review-gate.sh check` | `Ревью замысла пройдено` |

Не прогонялось: <перечень с причиной, либо «ничего»>.

## Примечания
- гипотезы (не проверены): <…, чем проверить>
- вопросы оператору: <…>
- незавершённое: <…, либо «нет»>

## Состояние дерева
`git -C <дерево> status --short`:
<вывод дословно>

Временные файлы: <«не создавались» / «созданы и удалены: <пути>»>.

Отчёт о проблеме

Когда работа не может быть завершена: вместо оговорки в общем отчёте — четыре раздела, каждый заполнен.

## Проблема
<Что именно нарушено или не выполнено — одним предложением.>

## Факты
- `<файл>:NNN` — <что там написано>
- `<команда>` → `<вывод дословно>`

## Влияние
<Почему это важно: деньги, контракт, боевой процесс, ворота.>

## Требуемое действие
<Что нужно сделать до завершения и кто решает — оператор или исполнитель.>