metaagent integration

2026-07-22 01:33:28 +03:00
parent 09069047a6
commit fdb1b318a5
25 changed files with 2680 additions and 0 deletions
@@ -0,0 +1,145 @@
+# Протокол 00: Конфигурация сессии (CONFIG)
+
+## Цель
+
+Определить параметры сессии MetaAgent: глубину проработки, набор функций, тип проекта. Выполняется на фазе INIT.
+
+## Вход
+
+- `VERSION` — текущая версия MetaAgent
+- Запрос пользователя (цель)
+- Опционально: `.agent/metaagent-request.md` (в директории `.agent/` целевого репозитория)
+
+## Шаги
+
+### 0.1. Проверить наличие .agent/metaagent-request.md
+
+Если файл существует — распарсить, провалидировать и использовать.
+Если нет — перейти к интервью (шаг 0.2).
+
+### 0.2. Интервью с пользователем
+
+Задать пользователю серию вопросов для сбора конфигурации.
+
+**Сценарий интервью:**
+
+```
+MetaAgent: .agent/metaagent-request.md не найден. Давайте настроим сессию.
+           (или ответьте "default" — я выберу depth=4, light)
+
+Q1: Это новый проект (greenfield) или работа с существующим кодом (existing)?
+    Варианты: new / existing / scaffold / default
+
+Q2: Глубина проработки?
+    1-2: Scaffold — только структура, пустые модули
+    3-4: Light — быстрый дизайн + задачи, без расширений (рекомендуется default)
+    5-6: Standard — полный цикл с acceptance criteria
+    7-8: Deep — + ADR, risk register, alternative architecture
+    9-10: Maximum — + Red Team review, executable invariants
+    Варианты: число 1-10 / default
+
+Q3 (если глубина >= 7): Нужны ADR (Architecture Decision Records)?
+    Варианты: yes / no / default
+
+Q4 (если глубина >= 7): Нужен Risk Register?
+    Варианты: yes / no / default
+
+Q5 (если глубина >= 9): Нужен Red Team Review?
+    Варианты: yes / no / default
+```
+
+**Правила обработки ответов:**
+- Если пользователь ответил `default` или не ответил — применить значение по умолчанию для этого поля
+- Если пользователь ответил `new` — `project_type = greenfield`
+- Если `existing` — `project_type = existing`
+
+### 0.3. Default config
+
+```json
+{
+  "depth": 4,
+  "design": {
+    "adr": false,
+    "alternative_arch": false
+  },
+  "red_team": false,
+  "risk_register": false,
+  "decomposition": {
+    "invariant_tests": false
+  },
+  "handoff": {
+    "layer_structure": false
+  }
+}
+```
+
+Depth=4 (Light) означает:
+- ANALYSIS — полный (определение типа проекта, извлечение требований)
+- DESIGN — выполняется (если greenfield), но **без** ADR, Alternative Architecture, Risk Register
+- DECOMPOSITION — задачи с acceptance criteria, **без** invariant-тестов
+- SETUP — полный
+- HANDOFF — плоский `.agent/` (без layer-структуры)
+
+### 0.4. Запись .agent/metaagent-request.md
+
+Если файла не было, создать его по результатам интервью с пометкой `Auto-generated`:
+
+```markdown
+# MetaAgent Request
+# Auto-generated from user interview on {{ date }}
+
+## Параметры сессии
+
+| Функция | Вкл | Аргументы |
+|---|---|---|
+| ANALYSIS | ✓ | — |
+| DESIGN | ✓ | adr={{ adr }}, alternative_arch={{ alt_arch }} |
+| RED_TEAM | {{ red_team }} | — |
+| RISK_REGISTER | {{ risk_register }} | — |
+| DECOMPOSITION | ✓ | invariant_tests={{ invariant_tests }} |
+| SETUP | ✓ | — |
+| HANDOFF | ✓ | layer_structure={{ layer_structure }} |
+
+## Глубина проработки
+
+**Значение:** {{ depth }}
+
+## Цель
+
+{{ goal }}
+```
+
+### 0.5. Создание .agent/rules/
+
+Создать директорию `.agent/rules/` в корне целевого проекта (если не существует).
+Если `.agent/rules/project-rules.md` не существует — создать из шаблона `.agent/src/TEMPLATES/project-rules.md`:
+
+```markdown
+# Project Rules
+
+Добавляйте сюда правила, которым агент обязан следовать во всех фазах.
+```
+
+### 0.6. Валидация config
+
+Проверить совместимость параметров с depth:
+
+```
+depth < 3 → DESIGN пропускается (даже для greenfield)
+depth < 7 → adr=false, alternative_arch=false, risk_register=false, invariant_tests=false
+depth < 9 → red_team=false
+```
+
+Если depth несовместим с включёнными функциями — понизить функции до максимума, разрешённого depth.
+
+## Выход
+
+- `.agent/metaagent-request.md` (создан или подтверждён)
+- config — словарь параметров для записи в checkpoints.json
+
+## Критерии завершения
+
+- [ ] `.agent/metaagent-request.md` существует (создан или найден)
+- [ ] Config содержит depth, design.*, red_team, risk_register, decomposition.*, handoff.*
+- [ ] Config совместим с depth (доп. функции отключены для малых depth)
+- [ ] При отсутствии файла — проведено интервью, файл создан
@@ -0,0 +1,124 @@
+# Протокол 00b: Миграция артефактов (MIGRATE)
+
+## Цель
+
+Обеспечить совместимость артефактов `.agent/` при изменении версии MetaAgent.
+Позволяет обновлять проекты, созданные старой версией, без потери данных.
+
+## Вход
+
+- `VERSION` — текущая версия MetaAgent
+- `.agent/checkpoints.json` — артефакты целевого проекта
+- `.agent/` — остальные артефакты
+
+## Шаги
+
+### M1. Определить версию артефактов
+
+Прочитать `.agent/checkpoints.json`:
+
+```python
+stored_version = checkpoints.get("metaagent_version", None)
+current_version = read("VERSION").strip()
+```
+
+- Если `metaagent_version` отсутствует → артефакт создан **v0.x** (доверсионный)
+- Если `metaagent_version` == `current_version` → пропустить миграцию
+- Если `metaagent_version` < `current_version` → требуется миграция
+
+### M2. Сравнение версий (SemVer)
+
+Версии сравниваются по семантическому версионированию (`MAJOR.MINOR.PATCH`).
+
+```python
+def needs_migration(stored, current):
+    if stored is None:
+        return True
+    return parse_semver(stored) < parse_semver(current)
+```
+
+### M3. Матрица миграций
+
+Каждая строка — набор шагов для перехода с одной версии на следующую.
+
+| Из версии | В версию | Шаги миграции |
+|---|---|---|
+| v0.x (нет поля) | v1.0.0 | M3.1 — M3.4 |
+| v1.0.0 | v1.1.0 | M3.5 — M3.6 (см. ниже) |
+
+### M4. Шаги миграции v0.x → v1.0.0
+
+... (шаги миграции остаются без изменений)
+
+### M5. Шаги миграции v1.0.0 → v1.1.0
+
+M3.5: Создать `.agent/rules/` с шаблоном `project-rules.md` (если не существует).
+M3.6: Создать `.agent/archive/` (если не существует).
+
+#### M3.1. Добавить metaagent_version
+
+Записать в checkpoints.json:
+
+```json
+"metaagent_version": "1.1.0"
+```
+
+#### M3.2. Добавить config (default)
+
+Если поля `config` нет в checkpoints.json — добавить config по умолчанию:
+
+```json
+"config": {
+  "depth": 4,
+  "design": { "adr": false, "alternative_arch": false },
+  "red_team": false,
+  "risk_register": false,
+  "decomposition": { "invariant_tests": false },
+  "handoff": { "layer_structure": false }
+}
+```
+
+#### M3.3. Добавить фазу red_team
+
+Если в `phases` нет ключа `red_team`:
+
+```json
+"red_team": "skipped"
+```
+
+#### M3.4. Создать layer-1/ (опционально, только если config.handoff.layer_structure)
+
+Если включена layer_structure:
+
+```bash
+mkdir -p .agent/layer-1/adr
+touch .agent/layer-1/adr/.gitkeep
+```
+
+Если `risk-register.md` уже существует на верхнем уровне — переместить в `.agent/layer-1/risk-register.md`.
+
+### M4. После миграции — резюме
+
+Записать в `.agent/migration-report.log`:
+
+```
+[MIGRATE] {{ timestamp }}
+  From: {{ from_version }}
+  To: {{ to_version }}
+  Steps applied: {{ step_list }}
+  Status: OK
+```
+
+## Выход
+
+- Обновлённый `.agent/checkpoints.json` (metaagent_version + config)
+- Опционально: `.agent/layer-1/` структура
+- `.agent/migration-report.log`
+
+## Критерии завершения
+
+- [ ] metaagent_version в checkpoints.json == текущей версии из VERSION
+- [ ] config присутствует в checkpoints.json
+- [ ] phases.red_team присутствует (skipped, если не нужен)
+- [ ] migration-report.log создан
+- [ ] Все старые данные сохранены (ничего не удалено)
@@ -0,0 +1,139 @@
+# Протокол 01: Анализ репозитория (ANALYSIS)
+
+## Цель
+
+Составить полную картину целевого репозитория: тип проекта, архитектура, стек, конвенции, состояние тестов, требования.
+
+## Вход
+
+- Целевой репозиторий (локальная копия)
+- `.agent/metaagent-request.md` (конфигурация сессии: глубина, функции) — или auto-generated
+- `.agent/checkpoints.json` (фаза analysis: pending)
+
+## Шаги
+
+### 0.0. Чтение конфигурации сессии
+
+Прочитать config из checkpoints.json (установлен на фазе INIT через `00_CONFIG.md`).
+
+Если config отсутствует или неполный — применить default:
+
+```json
+{
+  "depth": 4,
+  "design": { "adr": false, "alternative_arch": false },
+  "red_team": false,
+  "risk_register": false,
+  "decomposition": { "invariant_tests": false },
+  "handoff": { "layer_structure": false }
+}
+```
+
+Записать (или подтвердить) конфигурацию в checkpoints.json:
+```json
+"config": {
+  "depth": 6,
+  "design": { "adr": true, "alternative_arch": true },
+  "red_team": false,
+  "risk_register": false,
+  "decomposition": { "invariant_tests": true },
+  "handoff": { "layer_structure": true }
+}
+```
+
+Если `.agent/metaagent-request.md` не найден — использовать значения по умолчанию (depth=6, все базовые функции=true, расширенные=false).
+
+### 1.0. Определение типа проекта
+
+Просканировать корень репозитория и определить:
+
+- **`existing`** — есть исходный код, тесты, система сборки (файлы `.py`, `.js`, `.ts`, `.rs`, `.go` и т.д. помимо конфигов и README)
+- **`greenfield`** — репозиторий пуст или содержит только README, LICENSE, .gitignore
+- **`scaffold`** — есть базовая структура (pyproject.toml/package.json), но нет значимого кода
+
+Записать тип в analysis-report.md.
+
+**Правило:** если проект `existing` — разделы 1.1–1.6 выполняются полностью. Если `greenfield` — разделы 1.2–1.5 заменяются на 1.7 (извлечение требований из README).
+
+### 1.1. Общая информация
+
+Прочитать и зафиксировать:
+- **README** — описание проекта, how to build/test/run
+- **Лицензия** — какой LICENSE
+- **CI/CD** — `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `Makefile` и т.д.
+- **Главные точки входа** — `main.py`, `index.js`, `cmd/` и т.д.
+- **Система сборки** — `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `CMakeLists.txt`
+
+### 1.2. Стек технологий (только для existing/scaffold)
+
+Определить:
+- **Язык(и)** — Python, TypeScript, Go, Rust и т.д.
+- **Фреймворк** — FastAPI, Next.js, React, Actix и т.д.
+- **База данных** — PostgreSQL, SQLite, MongoDB и т.д.
+- **Тестовый раннер** — pytest, jest, vitest, go test
+- **Пакетный менеджер** — pip/poetry, npm/yarn/pnpm, cargo, go modules
+- **Линтер/форматтер** — ruff, eslint, prettier, rustfmt, gofmt
+
+### 1.3. Архитектура (только для existing/scaffold)
+
+- **Структура директорий** — записать схему (можно `tree /F`, но не более 3 уровней глубины)
+- **Архитектурный паттерн** — MVC, Clean Architecture, модульный монолит, микросервисы
+- **Ключевые модули/пакеты** — перечислить с кратким описанием
+- **Внешние зависимости** — основные библиотеки
+
+### 1.4. Конвенции кода (только для existing/scaffold)
+
+- **Стиль кода** — судя по линтеру и примерам: именование, импорты, типизация
+- **Паттерны** — как организованы роуты, хендлеры, модели, тесты
+- **Обработка ошибок** — как принято обрабатывать ошибки в проекте
+- **Логирование** — используется ли логгер, какой уровень
+
+### 1.5. Тесты (только для existing/scaffold)
+
+- **Какие тесты есть** — unit, integration, e2e
+- **Где лежат** — `tests/`, `__tests__/`, рядом с модулями
+- **Запуск** — команда для запуска всех тестов
+- **Текущее состояние** — запустить тесты, записать результат (сколько всего, сколько пройдено/упало)
+- **Покрытие** — есть ли метрики покрытия
+
+### 1.6. Базовая проверка (только для existing/scaffold)
+
+- **Собирается ли проект?** — запустить сборку
+- **Запускается ли проект?** — если возможно, проверить старт
+- **Чистый ли git status?** — нет ли незакоммиченных изменений
+
+### 1.7. Извлечение требований (только для greenfield/scaffold)
+
+Если README содержит описание будущего проекта — извлечь и структурировать:
+
+**Функциональные требования:**
+- Пользовательские истории (user stories)
+- Основные сценарии использования
+- Входные/выходные данные системы
+
+**Нефункциональные требования:**
+- Технологические предпочтения (язык, фреймворк, БД)
+- Требования к производительности, безопасности
+- Ограничения (сроки, платформа, окружение)
+
+**Бизнес-контекст:**
+- Цель системы (зачем)
+- Целевая аудитория
+- Ключевые метрики успеха
+
+**Сомнительные/неясные требования:**
+- Вопросы, которые нужно задать пользователю перед проектированием
+- Противоречия в README
+
+## Выход
+
+`.agent/analysis-report.md` по шаблону `TEMPLATES/analysis-report.md`.
+
+Обновить checkpoints.json: `phases.analysis = "completed"`. Если проект `greenfield`, также установить `project_type = "greenfield"`.
+
+## Критерии завершения фазы
+
+- [ ] Тип проекта определён (existing / greenfield / scaffold)
+- [ ] Все соответствующие разделы (1.1–1.7) выполнены
+- [ ] `.agent/analysis-report.md` создан и заполнен
+- [ ] checkpoints.json обновлён
@@ -0,0 +1,173 @@
+# Протокол 02: Архитектурное проектирование (DESIGN)
+
+## Цель
+
+Спроектировать архитектуру, модули, данные и интерфейсы для greenfield/scaffold-проекта на основе требований из analysis-report.
+
+## Вход
+
+- `.agent/analysis-report.md` (project_type: greenfield или scaffold)
+- `.agent/metaagent-request.md` (конфигурация сессии: adr, alternative_arch, risk_register)
+- `.agent/checkpoints.json` (фаза design: pending)
+
+## Правила
+
+1. **Реалистичность** — архитектура должна быть реализуема исполнительным агентом за 1 сессию (до 10 задач)
+2. **Документируемость** — каждый модуль, модель и интерфейс описывается в design-report.md
+3. **Тестируемость** — каждый компонент проектируется с учётом того, как его тестировать
+4. **Итеративность** — первая версия должна быть минимально рабочей (MVP), расширения — отдельными задачами
+
+## Шаги
+
+### 2.1. Технологический стек
+
+Если стек не указан в README — предложить обоснованный выбор. Если указан — зафиксировать.
+
+Для каждого компонента указать:
+- Язык и версия
+- Фреймворк / библиотека
+- База данных (движок, схема)
+- Инфраструктура (Docker, CI/CD, хостинг)
+
+### 2.2. High-level архитектура
+
+Описать общую структуру системы:
+
+- **Архитектурный паттерн** — монолит, модульный монолит, микросервисы, слоистая, луковая и т.д.
+- **Компоненты и их ответственность** — что делает каждый модуль/сервис
+- **Схема взаимодействия** — текстовое описание потоков данных
+
+Формат (text diagram):
+
+```
+[Client] → HTTP → [API Gateway] → [Auth Service]
+                                         ↓
+                              [Core Service] → [Database]
+                                         ↓
+                              [External API] → [3rd Party]
+```
+
+### 2.3. Модули проекта
+
+Разбить систему на модули/пакеты. Для каждого:
+
+| Поле | Описание |
+|---|---|
+| **Имя модуля** | `app/services/cashflow.py` |
+| **Ответственность** | Что делает |
+| **Ключевые классы/функции** | Только сигнатуры (без реализации) |
+| **Зависимости** | Какие модули нужны этому |
+| **Контракт** | Что экспортирует/предоставляет |
+
+### 2.4. Модели данных
+
+Описать основные сущности, их поля и связи:
+
+```json
+{
+  "entity": "Transaction",
+  "fields": [
+    {"name": "id", "type": "UUID", "pk": true},
+    {"name": "amount", "type": "Decimal"},
+    {"name": "date", "type": "datetime"},
+    {"name": "category_id", "type": "UUID", "fk": "Category"}
+  ]
+}
+```
+
+Если используется ORM — указать аннотации/декораторы.
+Если БД — схему таблиц, индексы, ключи.
+
+### 2.5. API интерфейсы
+
+Если проектируется API — описать эндпоинты:
+
+| Метод | Путь | Описание | Request | Response | Статусы |
+|---|---|---|---|---|---|
+| GET | /transactions | Список транзакций | ?page, ?limit | [Transaction] | 200 |
+| POST | /transactions | Создать транзакцию | CreateTransactionDTO | Transaction | 201, 400 |
+
+Если GUI — описать ключевые страницы/экраны.
+Если CLI — описать команды.
+
+### 2.6. Обработка ошибок
+
+- Стратегия ошибок: исключения, Result-тип, коды ошибок
+- Формат ошибок в API: `{ "error": "...", "code": "...", "details": {} }`
+- Логирование: какой уровень для каких событий
+
+### 2.7. Стратегия тестирования
+
+- Какие тесты нужны (unit, integration, e2e)
+- Как изолировать зависимости (mocks, fakes, testcontainers)
+- Команда запуска тестов
+
+### 2.8. Alternative Architecture (если config.alternative_arch = yes)
+
+Описать **минимум одну принципиально иную архитектуру** и причину отказа:
+
+| Критерий | Выбранная архитектура | Альтернатива |
+|---|---|---|
+| Название | Модульный монолит | Микросервисы / Событийная / и т.д. |
+| Сложность реализации | Низкая | Высокая (3+ сервиса) |
+| Масштабирование | Вертикальное | Горизонтальное |
+| Почему не выбрана | — | Избыточно для MVP |
+
+Это снижает риск архитектурной инерции: решение становится осознанным, а не единственным возможным.
+
+### 2.9. ADR (если config.adr = yes)
+
+Для каждого ключевого архитектурного решения (стек, БД, паттерн, структура модулей) создать отдельный ADR-файл:
+
+```
+.agent/layer-1/adr/001-технологический-стек.md
+.agent/layer-1/adr/002-модульный-монолит.md
+.agent/layer-1/adr/003-json-хранение.md
+```
+
+Формат — по шаблону `TEMPLATES/adr-NNNN.md`.
+
+### 2.10. Risk Register (если config.risk_register = yes)
+
+Создать `.agent/layer-1/risk-register.md` по шаблону `TEMPLATES/risk-register.md`:
+
+| # | Assumption | Impact if wrong | Mitigation | Review trigger |
+|---|---|---|---|---|
+
+Задокументировать **неявные допущения**, на которых держится архитектура. Это даёт future-агентам знать, что можно пересматривать в первую очередь.
+
+### 2.11. Группировка в задачи
+
+На основе спроектированных модулей и моделей предварительно наметить группировку в задачи (по модулям). Это будет входом для DECOMPOSITION.
+
+```
+T1: Инициализация проекта + зависимости
+T2: Модель данных (сущности, миграции)
+T3: Cashflow Service (core logic)
+T4: API endpoints
+...и т.д.
+```
+
+## Выход
+
+- `.agent/design-report.md` по шаблону `TEMPLATES/design-report.md`
+- `.agent/layer-1/adr/*.md` (если adr=yes)
+- `.agent/layer-1/risk-register.md` (если risk_register=yes)
+- Предварительная группировка задач (для передачи в DECOMPOSITION)
+
+Обновить checkpoints.json: `phases.design = "completed"`.
+
+## Критерии завершения фазы
+
+- [ ] Технологический стек определён
+- [ ] High-level архитектура описана
+- [ ] Модули и их ответственность описаны
+- [ ] Модели данных спроектированы
+- [ ] API/интерфейсы описаны (если применимо)
+- [ ] Стратегия тестирования определена
+- [ ] Alternative Architecture описана (если config требует)
+- [ ] ADR созданы (если config требует)
+- [ ] Risk Register создан (если config требует)
+- [ ] Задачи предварительно сгруппированы
+- [ ] `.agent/design-report.md` создан
+- [ ] checkpoints.json обновлён
@@ -0,0 +1,80 @@
+# Протокол 02b: Red Team Review (опционально)
+
+## Цель
+
+Преднамеренно попытаться разрушить спроектированную архитектуру, чтобы найти скрытые проблемы до начала реализации.
+
+## Вход
+
+- `.agent/design-report.md`
+- `.agent/layer-1/adr/*.md` (если созданы)
+- `.agent/metaagent-request.md` (глубина проработки >= 9)
+
+## Когда выполняется
+
+Только если `config.red_team = yes` (глубина 9-10). Выполняется **после** DESIGN, **до** DECOMPOSITION.
+
+## Шаги
+
+### RT1. Поиск скрытых зависимостей
+
+Проверить каждый модуль на наличие неявных связей:
+
+- Есть ли циклические зависимости между модулями?
+- Есть ли модуль, который знает слишком много о других?
+- Есть ли скрытый vendor lock-in (БД, облачный провайдер, внешний API)?
+
+### RT2. Точки отказа
+
+Для каждого внешнего интерфейса (API, БД, файловая система):
+
+- Что произойдёт при отказе компонента?
+- Есть ли fallback?
+- Что произойдёт при невалидных входных данных?
+
+### RT3. Масштабирование
+
+Оценить поведение системы при:
+
+- 10x рост данных
+- 100x рост данных
+- Добавлении нового пользователя / клиента
+
+### RT4. Security (если применимо)
+
+- Какие данные передаются по сети?
+- Есть ли аутентификация?
+- Хранятся ли секреты в коде?
+
+### RT5. Consistency
+
+Проверить design-report и ADR на противоречия:
+
+- Одна сущность описана по-разному в двух местах?
+- API-контракт не соответствует модели данных?
+- Технологический стек противоречит нефункциональным требованиям?
+
+## Выход
+
+`.agent/layer-1/red-team-report.md` с секциями:
+
+```
+## Найденные проблемы
+
+| # | Проблема | Серьёзность | Рекомендация |
+|---|---|---|---|
+
+## Отклонённые атаки (что пытались сломать — но не сломалось)
+
+| # | Гипотеза | Почему не подтвердилась |
+|---|---|---|
+```
+
+Обновить risk-register.md (если существует) новыми рисками.
+
+## Критерии завершения
+
+- [ ] Все 5 секций (RT1-RT5) проверены
+- [ ] Найденные проблемы записаны в red-team-report.md
+- [ ] Если найдены критические проблемы — design-report должен быть исправлен
+- [ ] Risk Register дополнен (если существует)
@@ -0,0 +1,133 @@
+# Протокол 03: Декомпозиция задач (DECOMPOSITION)
+
+## Цель
+
+Разбить цель пользователя (и архитектурный план, если есть) на атомарные, независимо выполнимые задачи и записать их в манифест.
+
+## Вход
+
+- `.agent/analysis-report.md`
+- `.agent/design-report.md` (опционально — для greenfield/scaffold)
+- `.agent/layer-1/adr/*.md` (опционально)
+- `.agent/layer-1/risk-register.md` (опционально)
+- `.agent/metaagent-request.md` (конфигурация сессии)
+- Цель пользователя (из checkpoints.json)
+- `.agent/checkpoints.json` (фаза decomposition: pending)
+
+## Правила декомпозиции
+
+### 3.1. Принципы
+
+1. **Атомарность** — одна задача = одна логическая единица работы, которую можно выполнить и проверить за один подход
+2. **Независимость (макс.)** — минимизировать зависимости между задачами
+3. **Тестируемость** — каждая задача имеет измеримые acceptance criteria
+4. **Границы** — задача не должна выходить за пределы, указанные в `BOUNDARIES.md`
+5. **Порядок** — задачи с зависимостями выполняются строго последовательно
+
+### 3.2. Размер задачи
+
+Задача должна укладываться в **1-2 часа работы исполнительного агента**. Если задача крупнее — разбить на подзадачи.
+
+Признак слишком крупной задачи:
+- Нельзя сформулировать acceptance criteria одной строкой
+- Затрагивает 5+ файлов
+- Содержит союзы "и", "а также", "после чего"
+
+### 3.3. Структура задачи
+
+Каждая задача содержит:
+
+| Поле | Описание | Пример |
+|---|---|---|
+| `id` | Уникальный идентификатор | `T1`, `T2` |
+| `title` | Заголовок (что сделать) | "Добавить модель User" |
+| `description` | Описание (как и зачем) | "Создать SQLAlchemy модель..." |
+| `type` | Тип задачи | `feature`, `refactor`, `test`, `fix`, `config`, `design`, `docs` |
+| `status` | Статус задачи | `pending`, `in_progress`, `completed`, `failed`, `archived` |
+| `files` | Список файлов, которые нужно создать/изменить | `["app/models/user.py"]` |
+| `depends_on` | ID задач, от которых зависит | `[]` или `["T0"]` |
+| `acceptance_criteria` | Список критериев приёмки (3-5 пунктов) | `["Модель проходит миграцию"]` |
+| `context` | Доп. информация (ссылки на доки, примеры, релевантные секции из design-report) | `"Смотри app/models/base.py"` |
+
+### 3.4. Типы задач
+
+| Тип | Описание |
+|---|---|
+| `config` | Настройка окружения, зависимостей, CI, инициализация проекта |
+| `design` | Архитектурное/дизайнерское решение без кода |
+| `feature` | Новая функциональность |
+| `refactor` | Изменение структуры без изменения поведения |
+| `test` | Добавление/исправление тестов |
+| `fix` | Исправление бага |
+| `docs` | Документация |
+| `invariant` | Тест, проверяющий архитектурный инвариант (см. 3.7) |
+
+### 3.5. Зелёная декомпозиция (для greenfield/scaffold)
+
+Если есть `.agent/design-report.md` — задачи формируются на основе группировки из дизайна:
+
+1. **T1: init** — инициализация проекта, зависимости, конфиги, scaffold
+2. **T2..Tn: features** — модули/функциональность по одному
+3. **Tn+1: tests** — тесты на каждый модуль (можно в составе feature-задачи)
+4. **Tn+2: polish** — документация, форматирование, финальная проверка
+
+### 3.6. Сортировка
+
+Задачи в манифесте располагаются в порядке выполнения:
+1. Сначала задачи без зависимостей
+2. Потом те, чьи зависимости уже выполнены
+3. Последними — задачи с наибольшим числом зависимостей
+
+### 3.7. Executable Invariants (если config.invariant_tests = yes)
+
+Для каждого ADR (из layer-1/adr/) создать задачу типа `invariant` — тест, проверяющий архитектурное правило.
+
+**Правила превращения ADR в инварианты:**
+
+| ADR | Инвариант-тест |
+|---|---|
+| "Модуль X не зависит от Y" | `test_x_does_not_import_y.py` — import test |
+| "Слой Model не знает о CLI" | `test_model_layer_imports.py` — проверка import graph |
+| "Все исключения кастомные" | `test_custom_exceptions.py` — проверка hierarchy |
+| "Интерфейс репозитория не泄漏 implementation details" | `test_repository_interface.py` — ABC check |
+
+**Формат задачи-инварианта:**
+
+```json
+{
+  "id": "I1",
+  "title": "Инвариант: model не импортирует cli",
+  "type": "invariant",
+  "files": ["tests/invariants/test_layer_imports.py"],
+  "depends_on": ["T2"],
+  "acceptance_criteria": [
+    "Тест проверяет, что cashflow_model не импортирует cli, sync, engine",
+    "Тест проходит на пустом проекте (до реализации функциональности)"
+  ]
+}
+```
+
+Инварианты размещаются в `tests/invariants/` и запускаются вместе с основными тестами.
+
+## Выход
+
+- `.agent/task-manifest.json` — по схеме `TEMPLATES/task-manifest.json`
+- `.agent/task-manifest.md` — по шаблону `TEMPLATES/task-manifest.md`
+
+Обновить checkpoints.json:
+- `phases.decomposition = "completed"`
+- `tasks` = полный массив задач со статусом `pending`
+
+> **Примечание:** после HANDOFF завершённые задачи будут архивированы —
+> полное описание уходит в `.agent/archive/tasks/`, в манифесте остаётся
+> one-liner с `"status": "archived"`.
+
+## Критерии завершения фазы
+
+- [ ] Цель разбита на атомарные задачи
+- [ ] Для каждой задачи указаны acceptance criteria
+- [ ] Для каждой задачи указаны affected files
+- [ ] Зависимости между задачами корректны (нет циклов)
+- [ ] Invariant-задачи созданы для каждого ADR (если config требует)
+- [ ] `.agent/task-manifest.json` и `.agent/task-manifest.md` созданы
+- [ ] checkpoints.json обновлён
@@ -0,0 +1,126 @@
+# Протокол 04: Настройка окружения (SETUP)
+
+## Цель
+
+Обеспечить рабочее окружение, в котором исполнительный агент может сразу выполнять задачи.
+
+## Вход
+
+- `.agent/analysis-report.md`
+- `.agent/design-report.md` (опционально, для greenfield)
+- `.agent/task-manifest.json`
+- `.agent/checkpoints.json` (фаза environment: pending)
+
+## Поведение в зависимости от типа проекта
+
+Фаза SETUP работает по-разному для `existing` и `greenfield/scaffold` проектов.
+
+---
+
+## Ветка A: existing/scaffold проект
+
+### 4A.1. Зависимости
+
+- Установить все зависимости согласно документации проекта
+- Если есть `requirements.txt`, `pyproject.toml`, `package.json`, `Cargo.toml` и т.д. — выполнить установку
+- Если в проекте используется виртуальное окружение (venv, .venv, conda) — активировать или создать
+- Если в проекте используется Docker — проверить, что образ собирается
+
+**Правило:** если установка зависимостей требует нестандартных шагов, описанных в README — строго следовать им. Если шаги не описаны — запросить у пользователя.
+
+### 4A.2. Конфигурация
+
+- Проверить наличие конфигурационных файлов (`.env.example`, `.env`, `config.yaml`)
+- Если есть `.env.example`, скопировать в `.env` с настройками по умолчанию
+- Если проекту требуется БД — проверить строку подключения, при необходимости создать БД или использовать SQLite для разработки
+- Настроить pre-commit хуки, если они есть в проекте
+
+### 4A.3. Линтеры и форматтеры
+
+- Запустить линтер на всём проекте: записать результат
+- Если линтер выдаёт ошибки — не исправлять, только зафиксировать в отчёте
+- Убедиться, что исполнительный агент может запускать линтер (записать команду)
+
+### 4A.4. Baseline-тесты
+
+- Запустить все тесты проекта
+- Записать в `.agent/baseline-test-report.log`:
+  - Команда запуска
+  - Общее количество тестов
+  - Пройдено / упало / пропущено
+  - Время выполнения
+  - Список упавших тестов (если есть)
+- Если тесты не проходят — указать это в отчёте, но **не исправлять**
+
+### 4A.5. Сборка проекта
+
+- Выполнить полную сборку/компиляцию проекта
+- Записать результат (успех/ошибка с логом)
+- Сборка должна проходить без ошибок. Если не собирается — остановиться, сообщить пользователю.
+
+---
+
+## Ветка B: greenfield проект
+
+### 4B.1. Инициализация проекта
+
+- Создать базовую структуру директорий согласно design-report.md
+- Инициализировать пакетный менеджер:
+  - Python: `pyproject.toml` (poetry, pdm, hatch) или `requirements.txt`
+  - Node: `package.json` и `npm init` / `yarn init`
+  - Go: `go mod init`
+  - Rust: `cargo init`
+- Настроить базовый конфиг: `.env.example`, `config/` и т.д.
+- Настроить линтер/форматтер: `ruff`, `eslint`, `gofmt` и т.д.
+
+### 4B.2. Scaffold-код
+
+Создать пустые заглушки для модулей, описанных в design-report:
+
+```python
+# app/services/cashflow.py — заглушка
+class CashflowService:
+    """TBD — реализация в задаче T3"""
+    pass
+```
+
+Назначение: фиксировать структуру, чтобы исполнительный агент не думал о ней, а сразу писал реализацию.
+
+### 4B.3. Установка зависимостей
+
+- Установить базовые зависимости согласно стеку из design-report
+- Если проект использует БД — установить драйвер/ORM
+- Если проект использует API — установить фреймворк (FastAPI, Express и т.д.)
+- Установить dev-зависимости: линтер, тестовый раннер, type stubs
+
+### 4B.4. Базовые тесты (scaffold)
+
+- Создать пустой тестовый файл для каждого модуля
+- Настроить тестовый раннер (pytest, jest и т.д.)
+- Записать в `.agent/baseline-test-report.log`: "0 tests — greenfield, scaffold готов"
+
+### 4B.5. Проверка сборки
+
+- Убедиться, что проект импортируется без ошибок
+- Убедиться, что линтер проходит (без кода он должен проходить)
+- Убедиться, что тестовый раннер запускается (0 tests, exit code 0)
+
+---
+
+## Выход
+
+- Работоспособное окружение / инициализированный проект
+- `.agent/baseline-test-report.log` — результат прогона тестов
+- `.agent/setup-report.log` — лог установки зависимостей и сборки
+
+Обновить checkpoints.json: `phases.environment = "completed"`.
+
+## Критерии завершения фазы
+
+- [ ] Зависимости установлены / проект инициализирован
+- [ ] Проект собирается / импортируется без ошибок
+- [ ] Baseline-тесты запущены, результат записан
+- [ ] `.agent/baseline-test-report.log` и `.agent/setup-report.log` созданы
+- [ ] checkpoints.json обновлён
+
+Если проект не собирается — **фаза считается проваленной**, checkpoints.json отмечает `phases.environment = "failed"`, управление возвращается пользователю.
@@ -0,0 +1,188 @@
+# Протокол 05: Передача исполнительному агенту (HANDOFF)
+
+## Цель
+
+Подготовить и передать исполнительному агенту полный контекст для работы: задачи, окружение, правила.
+
+## Вход
+
+- `.agent/analysis-report.md`
+- `.agent/design-report.md` (опционально, для greenfield)
+- `.agent/layer-1/adr/*.md` (опционально)
+- `.agent/layer-1/risk-register.md` (опционально)
+- `.agent/layer-1/red-team-report.md` (опционально)
+- `.agent/task-manifest.json`
+- `.agent/task-manifest.md`
+- `.agent/baseline-test-report.log`
+- `.agent/checkpoints.json` (все предыдущие фазы: completed)
+
+## Шаги
+
+### 5.1. Архивация завершённых артефактов
+
+Перед валидацией и передачей выполнить архивирование.
+
+**Архивировать завершённые задачи:**
+
+Для каждой задачи в `task-manifest.json` со статусом `completed`:
+1. Создать `.agent/archive/tasks/<id>.json` — перенести полное описание задачи (все поля)
+2. В `task-manifest.json` заменить задачу на one-liner:
+   ```json
+   { "id": "<id>", "title": "<title>", "status": "archived" }
+   ```
+
+**Архивировать чекпоинты:**
+
+Если `checkpoints.json` уже существует — сохранить предыдущую версию в `.agent/archive/checkpoints/<last_updated>.json`.
+
+**Создать индекс архива:**
+
+```json
+{
+  "version": "1.1.0",
+  "archived_at": "<timestamp>",
+  "tasks": [
+    { "id": "T1", "title": "...", "archived_at": "<timestamp>" }
+  ],
+  "checkpoints": [
+    { "file": "checkpoints/2026-07-15T10-00-00.json", "archived_at": "<timestamp>" }
+  ]
+}
+```
+
+### 5.2. Валидация
+
+Перед передачей проверить:
+
+- [ ] Все фазы отмечены как `completed` в checkpoints.json
+- [ ] `.agent/` содержит все обязательные файлы:
+  - `checkpoints.json`
+  - `analysis-report.md`
+  - `task-manifest.json` + `task-manifest.md`
+  - `baseline-test-report.log`
+  - `setup-report.log`
+  - `src/META_AGENT_GUIDE.md`
+  - `src/BOUNDARIES.md`
+  - `src/VERSION`
+  - `src/PROTOCOLS/`
+  - `src/TEMPLATES/`
+  - `rules/project-rules.md`
+  - `archive/index.json`
+- [ ] Для greenfield: `design-report.md` присутствует
+- [ ] В task-manifest.json нет циклических зависимостей
+- [ ] Все acceptance criteria сформулированы измеримо
+- [ ] Для каждой задачи указаны affected files
+- [ ] В репозитории нет незакоммиченных изменений (кроме `.agent/`)
+- [ ] `.agent/src/` содержит актуальные исходники MetaAgent (META_AGENT_GUIDE.md, PROTOCOLS/, TEMPLATES/, BOUNDARIES.md, VERSION)
+- [ ] `AGENTS.md` присутствует в корне репозитория
+- [ ] `.agent/rules/` содержит `project-rules.md`
+
+**Дополнительные проверки (если config включает):**
+- [ ] ADR присутствуют (если adr=yes)
+- [ ] Risk Register заполнен (если risk_register=yes)
+- [ ] Red Team Report есть (если red_team=yes)
+- [ ] Invariant-задачи в манифесте (если invariant_tests=yes)
+
+### 5.3. Layer-структура .agent/
+
+Если `config.layer_structure = yes`, организовать артефакты по слоям:
+
+```
+.agent/
+  layer-0/
+    checkpoints.json          # всегда (ядро)
+    session-summary.md        # краткая сводка сессии (создаётся здесь)
+  layer-1/
+    adr/                      # ADR (опционально)
+    risk-register.md          # (опционально)
+    red-team-report.md        # (опционально)
+  layer-2/
+    analysis-report.md
+    design-report.md
+    design-report.md
+  layer-3/
+    handoff-summary.md
+    task-manifest.json
+    task-manifest.md
+    baseline-test-report.log
+    setup-report.log
+```
+
+Если `layer_structure = no` — артефакты остаются плоскими в `.agent/`, как раньше.
+
+### 5.4. Создать handoff-summary.md
+
+Заполнить по шаблону `TEMPLATES/handoff-summary.md`:
+
+- **Session Info** — ID, цель, дата
+- **Configuration** — какие функции были включены, глубина
+- **Repo Summary** — краткая выжимка из analysis-report
+- **Environment Status** — результат сборки и тестов
+- **Design Summary** (если есть design-report) — ключевые архитектурные решения
+- **ADR Summary** (если adr=yes) — какие решения задокументированы
+- **Risk Register** (если risk_register=yes) — основные допущения
+- **Task Overview** — количество задач, типы, список
+- **Next Steps** — с какой задачи начинать исполнительному агенту
+- **Project Rules** — ссылка на `.agent/rules/project-rules.md` (передаётся exec-агенту)
+- **Archive** — ссылка на `.agent/archive/index.json` (история завершённых задач)
+- **Caveats** — известные проблемы, ограничения, неясные моменты
+- **Checkpoints** — актуальное состояние чекпоинтов
+
+### 5.5. Финализировать checkpoints
+
+- Отметить `phases.handoff = "completed"`
+- Записать финальный `last_updated`
+
+### 5.6. Сигнал
+
+Сообщить пользователю/оркестратору:
+
+```
+HANDOFF COMPLETE
+
+Session: <session_id>
+Target: <target_repo>
+Type: <existing | greenfield | scaffold>
+Config: depth=<N>, adr=<yes|no>, red_team=<yes|no>, ...
+Tasks: <count> tasks ready
+
+Исполнительный агент может начинать с задачи <T1>.
+Контекст: .agent/handoff-summary.md
+Манифест: .agent/task-manifest.json
+```
+
+## Что получает исполнительный агент
+
+1. **Целевой репозиторий** — полностью настроенный, с установленными зависимостями
+2. **`.agent/`** — директория со всеми артефактами (layer-структура или плоская)
+3. **`task-manifest.json`** — машиночитаемый список задач
+4. **`task-manifest.md`** — человекочитаемый список задач
+5. **`handoff-summary.md`** — итоговая сводка
+6. **`checkpoints.json`** — актуальное состояние (исполнительный агент будет его обновлять)
+7. **`layer-1/adr/*.md`** (опционально) — ключевые решения
+8. **`layer-1/risk-register.md`** (опционально) — допущения
+9. **`layer-2/analysis-report.md`** — полный анализ репозитория (справочно)
+10. **`layer-2/design-report.md`** (только для greenfield) — архитектурный план
+11. **`layer-3/baseline-test-report.log`** — baseline тестов (чтобы не сломать существующее)
+12. **`.agent/src/`** — полные исходники MetaAgent (справочно, всегда присутствуют)
+13. **`.agent/rules/`** — пользовательские правила проекта
+14. **`AGENTS.md`** — инструкция для AI-агента в корне проекта (всегда присутствует)
+15. **`.agent/archive/`** — архив завершённых задач, чекпоинтов и устаревших артефактов
+
+## Выход
+
+- `.agent/layer-0/session-summary.md` (если layer_structure=yes)
+- `.agent/layer-3/handoff-summary.md`
+- `.agent/layer-0/checkpoints.json` (финальный)
+- `.agent/archive/index.json` (создаётся при архивации)
+
+## Критерии завершения
+
+- [ ] Все артефакты на месте (с учётом layer-структуры)
+- [ ] `.agent/src/` содержит актуальные исходники MetaAgent
+- [ ] `.agent/rules/` содержит `project-rules.md`
+- [ ] `AGENTS.md` присутствует в корне репозитория
+- [ ] `.agent/archive/index.json` создан, завершённые задачи архивированы
+- [ ] handoff-summary.md заполнен (включая config, design summary, ADR summary, archive)
+- [ ] checkpoints.json финализирован
+- [ ] Сигнал отправлен пользователю/оркестратору