# ADR-006: Версионирование агентов

**Статус:** принято
**Дата:** 2026-05-10

---

## Контекст

11 системных агентов VoIdea самообучаются — их код, промпты и capabilities изменяются
автоматически через EvolutionAgent или вручную. Без контроля версий невозможно:

- Отследить, когда и какой агент изменился
- Понять, какие изменения были внесены
- Откатить агента до предыдущей версии при проблемах
- Синхронизировать версии агентов между окружениями (local → VPS)

Рассматривались:
- **Единая версия для всех** — не отражает индивидуальных изменений
- **Только git** — не покрывает runtime-эволюцию (изменение промптов без коммита)
- **A.B.C для каждого агента** — точный контроль, авто-детект изменений

---

## Решение

**A.B.C (SemVer) для каждого агента**, changelog в `CHANGELOG/agents/<name>.md`.

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

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

### Механика

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

EvolutionAgent
  → добавляет capability → bump_version("minor") → запись в changelog
  → обнаружил breaking change → bump_version("major") → запись в changelog
```

### Хранение

```
CHANGELOG/agents/
├── doc_agent.md
├── audit_agent.md
├── security_agent.md
├── spec_agent.md
├── observer_agent.md
├── qa_tester_agent.md
├── fix_agent.md
├── ui_test_agent.md
├── rollout_agent.md
├── evolution_agent.md
└── backlog_agent.md
```

Формат changelog агента:
```markdown
# audit_agent Changelog

## 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.json`, `CHANGELOG/v*.md` |
| Версия агента | EvolutionAgent | `AgentConfig.version` (БД) |
| Changelog проекта | SpecAgent | `CHANGELOG/v*.md` |
| Changelog агента | EvolutionAgent | `CHANGELOG/agents/<name>.md` |

---

## Архитектура

### Изменения в моделях БД

```python
class AgentConfig(SQLBase, UUIDMixin, TimestampMixin):
    __tablename__ = "agent_configs"

    agent_name: str        # unique
    is_enabled: bool
    version: str           # "1.0.0" — новое поле
    checksum: str          # SHA256 — новое поле
    config: str | None     # JSON
    last_run_at: datetime  # DateTime вместо String
```

### Изменения в BaseAgent

```python
class BaseAgent(ABC):
    name: str
    version: str = "1.0.0"
    CHANGELOG_DIR = "CHANGELOG/agents/"

    def compute_checksum(self) -> str:
        """SHA256 от __file__ агента"""
        ...

    def bump_version(self, version_type: str = "patch") -> str:
        """Увеличить A/B/C, обновить self.version"""
        ...

    def write_changelog(self, version: str, entries: list[str]) -> None:
        """Дописать запись в CHANGELOG/agents/<name>.md"""
        ...
```

---

## Последствия

### Положительные

- Полная traceability изменений каждого агента
- Автоматическое версионирование без участия человека
- Совместимо с git (checksum детектит и runtime-изменения)
- Единый формат changelog для всех агентов

### Отрицательные

- Дополнительная нагрузка на БД (чтение/запись checksum при каждом run)
- SHA256 файла не детектит изменения в импортируемых зависимостях
- Patch-версия может расти быстро при частых правках

---

## Ответственный

**Decision maker:** Owner
**Review date:** При изменении архитектуры агентов

---

*Создано: 2026-05-10*