# Версионирование агентов

---

## Принцип

Каждый агент версионируется **независимо** от проекта и от других агентов по A.B.C (SemVer).

---

## Правила бампа

| Компонент | Когда | Кто |
|-----------|-------|-----|
| **A (major)** | Breaking change в публичном интерфейсе (сигнатура `run()`, публичные методы) | EvolutionAgent |
| **B (minor)** | Новая capability (новый метод, новый prompt, новая роль) | EvolutionAgent |
| **C (patch)** | Внутренние правки без изменения поведения | Сам агент (авто) |

---

## Механика

```
Каждый Agent.run()
  → compute_checksum() — SHA256 от __file__ агента
  → сравнивает с AgentConfig.checksum в БД
  → не совпал → bump_version("patch") → запись в changelog → обновление БД
  → совпал → ничего

EvolutionAgent
  → анализирует код агента
  → нашёл новую capability → bump_version("minor")
  → нашёл breaking change → bump_version("major")
```

---

## Хранение checksum

Checksum хранится в двух местах:
1. **В БД** (`AgentConfig.checksum`) — для быстрого сравнения
2. **В changelog файле** (`<!-- checksum: ... -->`) — для git history

---

## Changelog

Файл: `CHANGELOG/agents/<agent_name>.md`

```markdown
# audit_agent Changelog
<!-- checksum: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890 -->

## 1.0.2 (2026-05-10)
- Fixed: ruff output parsing for Windows paths

## 1.0.1 (2026-05-09)
- Fixed: missing error handling in health_check

## 1.0.0 (2026-05-08)
- Initial version
```

---

## Разделение ответственности

| Аспект | Владелец | Где хранится |
|--------|----------|--------------|
| Версия проекта | SpecAgent / человек | `project.yaml`, `CHANGELOG/v*.md` |
| Версия агента | EvolutionAgent | `AgentConfig.version` (БД) |
| Changelog проекта | SpecAgent / человек | `CHANGELOG/v*.md` |
| Changelog агента | EvolutionAgent | `CHANGELOG/agents/<name>.md` |

---

## [ASK] Вопросы по версионированию

- Версионировать агентов с первого коммита? (да — привычка, потом не внедрить)
- Допустим ли ручной бамп версии? (да, EvolutionAgent — автоматизация, но человек может и вручную)
- Нужна ли блокировка бампа (если checksum не совпал — не запускать)? (нет, только предупреждение)