diff --git a/.agent/analysis-report.md b/.agent/analysis-report.md deleted file mode 100644 index fb93f1d..0000000 --- a/.agent/analysis-report.md +++ /dev/null @@ -1,78 +0,0 @@ -# Analysis Report - -## Session - -- **Session ID:** `metaagent-002` -- **Target repo:** `S:\Git\nifodea` -- **Date:** 2026-07-22 -- **Project type:** `existing` - -## 1. Общая информация - -- **README:** Личная финансовая модель с прогнозом денежных потоков, сценарным анализом и AI-ассистентом. Python + JSON + Excel + AI. -- **Лицензия:** не выбрана -- **CI/CD:** отсутствует -- **Точка входа:** `cli/main.py` (команда `cf`) -- **Система сборки:** `pyproject.toml` (setuptools) - -## 2. Стек технологий - -| Компонент | Значение | -|---|---| -| Язык | Python >= 3.11 | -| Фреймворк | Typer (CLI) | -| База данных | JSON-файлы | -| Тестовый раннер | pytest | -| Пакетный менеджер | pip (setuptools) | -| Линтер/форматтер | ruff | - -## 3. Архитектура - -``` -cashflow_model/ # Модели данных (dataclass + JSON) -engine/ # Вычислительное ядро (forecast + scenarios) -sync/ # Excel import/export -ai/ # AI-ассистент (заглушка) -cli/ # CLI (Typer) -tests/ # pytest -data/ # JSON-модели -exports/ # Экспортированные .xlsx -``` - -**Паттерн:** Модульный монолит - -**Ключевые модули:** - -| Модуль | Описание | -|---|---| -| cashflow_model | Модели данных: Account, Transaction, RecurringCashflow, Asset, Liability, ForecastScenario, FinancialModel | -| engine | Вычислительное ядро: ForecastService (прогноз), ScenarioService (сценарии + what-if) | -| sync | ExcelSync — импорт/экспорт .xlsx | -| ai | AssistantService — генерация промптов (заглушка) | -| cli | Typer CLI — 8 команд | - -## 4. Конвенции - -- **Стиль:** snake_case для функций/переменных, PascalCase для классов -- **Импорты:** стандартные, сгруппированные -- **Типизация:** используется (dataclass, type hints) -- **Обработка ошибок:** через исключения -- **Логирование:** не используется - -## 5. Тесты - -- **Команда запуска:** `pytest` -- **Всего тестов:** 26 -- **Пройдено:** 26 -- **Упало:** 0 -- **Пропущено:** 0 - -## 6. Базовая проверка - -- **Сборка:** OK (pip install -e .) -- **Линтер:** OK (ruff check . — all checks passed) -- **Git status:** есть незакоммиченные изменения (checkpoints.json, metaagent-request.md, AGENTS.md, data/model.json, .agent/rules/) - -## 8. Примечания - -Проект полностью функционален: 26 тестов проходят, линтер чист. Требуется только обновление MetaAgent-артефактов до v1.1.0. diff --git a/.agent/archive/index.json b/.agent/archive/index.json new file mode 100644 index 0000000..38c44a5 --- /dev/null +++ b/.agent/archive/index.json @@ -0,0 +1,25 @@ +{ + "version": "3.0.0", + "archived_at": "2026-10-08T17:05:00Z", + "session": "metaagent-005", + "goal": "Обсуждение архитектуры и серьёзный refactor", + "tasks": [ + { "id": "T1", "title": "Реструктуризация в domain/application/infrastructure + version=1", "archived_at": "2026-10-08T17:05:00Z", "request": "req-T1", "commit": "feb77ef" }, + { "id": "T2", "title": "Pydantic v2 — миграция моделей", "archived_at": "2026-10-08T17:05:00Z", "request": "req-T2", "commit": "c765f36" }, + { "id": "T3", "title": "Decimal для денег", "archived_at": "2026-10-08T17:05:00Z", "request": "req-T3", "commit": "363d440" }, + { "id": "T4", "title": "Repository pattern — ModelRepository", "archived_at": "2026-10-08T17:05:00Z", "request": "req-T4" }, + { "id": "T5", "title": "Dependency Injection в сервисах", "archived_at": "2026-10-08T17:05:00Z", "request": "req-T5", "commit": "541a768" }, + { "id": "T6", "title": "Декомпозиция CLI", "archived_at": "2026-10-08T17:05:00Z", "request": "req-T6" }, + { "id": "T7", "title": "Финальная валидация", "archived_at": "2026-10-08T17:05:00Z", "request": "req-T7", "commit": "3ef1061" } + ], + "requests": [ + { "id": "req-T1", "task_id": "T1", "status": "approved", "archived_at": "2026-10-08T17:05:00Z" }, + { "id": "req-T2", "task_id": "T2", "status": "approved", "archived_at": "2026-10-08T17:05:00Z" }, + { "id": "req-T3", "task_id": "T3", "status": "approved", "archived_at": "2026-10-08T17:05:00Z" }, + { "id": "req-T4", "task_id": "T4", "status": "approved", "archived_at": "2026-10-08T17:05:00Z" }, + { "id": "req-T5", "task_id": "T5", "status": "approved", "archived_at": "2026-10-08T17:05:00Z" }, + { "id": "req-T6", "task_id": "T6", "status": "approved", "archived_at": "2026-10-08T17:05:00Z" }, + { "id": "req-T7", "task_id": "T7", "status": "approved", "archived_at": "2026-10-08T17:05:00Z" } + ], + "checkpoints": [] +} diff --git a/.agent/archive/requests/req-T1.json b/.agent/archive/requests/req-T1.json new file mode 100644 index 0000000..a0f915f --- /dev/null +++ b/.agent/archive/requests/req-T1.json @@ -0,0 +1,36 @@ +{ + "request_id": "req-T1", + "task_id": "T1", + "title": "Restructure to domain/application/infrastructure + schema version 1", + "status": "ready_for_review", + "goal": "Ввести явные слои и подготовить инфраструктуру миграций схемы", + "changes": { + "summary": "Перестроена пакетная структура: cashflow_model/ → domain/ (модели), engine/ → application/ (сервисы), cli/, sync/, ai/ → infrastructure/ (адаптеры). Обновлены все импорты в коде и тестах. В FinancialModel добавлено поле version=1 в to_dict() и миграционный хук _from_v0/_from_v1 в from_dict() для обратной совместимости. Обновлён pyproject.toml: cf = infrastructure.cli.main:app, packages.find = ['domain*', 'application*', 'infrastructure*'].", + "commits": ["feb77ef217a54720868218b911312b040bcfb118"], + "files_changed": [ + "domain/ (new, 8 файлов из cashflow_model/)", + "application/ (new, 3 файла из engine/)", + "infrastructure/ai/ (new, из ai/)", + "infrastructure/cli/ (new, из cli/)", + "infrastructure/sync/ (new, из sync/)", + "tests/* (8 файлов, импорты обновлены)", + "pyproject.toml (cf entry + packages.find)", + "data/model.json (version=1)" + ] + }, + "verification": { + "tests_passed": "63/63", + "lsp_clean": true, + "cf_command_works": true, + "round_trip_v1": "ok", + "legacy_v0_load": "ok" + }, + "fulfills_ac": [ + "Структура domain/application/infrastructure создана", + "Все исходные файлы перемещены в соответствующие слои", + "Все импорты обновлены", + "FinancialModel.to_dict() возвращает {'version': 1, ...}", + "FinancialModel.from_dict() поддерживает v0 и v1", + "pytest проходит 63/63" + ] +} diff --git a/.agent/archive/requests/req-T2.json b/.agent/archive/requests/req-T2.json new file mode 100644 index 0000000..05de2e9 --- /dev/null +++ b/.agent/archive/requests/req-T2.json @@ -0,0 +1,34 @@ +{ + "request_id": "req-T2", + "task_id": "T2", + "title": "Pydantic v2 — replace @dataclass with BaseModel", + "status": "ready_for_review", + "goal": "Заменить ручную сериализацию на pydantic.BaseModel, добавить валидацию", + "changes": { + "summary": "Все 7 моделей domain/ переведены с @dataclass на pydantic.BaseModel. Удалены ручные to_dict()/from_dict() — заменены на model_dump(mode='json')/model_validate(). Добавлены field_validators: Account.balance >= 0, Transaction.amount != 0, RecurringCashflow.amount != 0 и frequency ∈ {daily,weekly,monthly,yearly}, Liability.interest/payment >= 0, ExchangeRate.rate > 0, ForecastScenario.multipliers >= 0. UUID в JSON автоматически сериализуется как str. excel_sync.py адаптирован на model_validate(). Тесты test_model.py и test_currency.py обновлены. pyproject.toml: pydantic>=2.0.", + "commits": ["c765f36"], + "files_changed": [ + "domain/account.py, asset.py, currency.py, liability.py, recurring.py, scenario.py, transaction.py, model.py", + "infrastructure/sync/excel_sync.py", + "tests/test_model.py, tests/test_currency.py", + "pyproject.toml" + ] + }, + "verification": { + "tests_passed": "63/63", + "validators_work": "Account negative balance, Transaction zero amount, ExchangeRate negative rate — all rejected", + "uuid_in_json_as_str": true, + "round_trip": "ok", + "cf_init_works": true, + "cf_forecast_works": true, + "cf_scenario_works": true + }, + "fulfills_ac": [ + "Все модели domain/ — наследники pydantic.BaseModel", + "Удалены ручные to_dict() и from_dict()", + "UUID в JSON сериализуется как строка", + "Валидация работает (balance, amount, rate, frequency)", + "Excel-sync адаптирован под pydantic", + "pytest 63/63" + ] +} diff --git a/.agent/archive/requests/req-T3.json b/.agent/archive/requests/req-T3.json new file mode 100644 index 0000000..06d7f5c --- /dev/null +++ b/.agent/archive/requests/req-T3.json @@ -0,0 +1,31 @@ +{ + "request_id": "req-T3", + "task_id": "T3", + "title": "Decimal for money", + "status": "ready_for_review", + "goal": "Точность финансовых расчётов — float → Decimal", + "changes": { + "summary": "Все денежные поля в domain/ переведены с float на Decimal. CurrencyConverter использует Decimal арифметику с ROUND_HALF_UP до 2 знаков. ForecastService и ScenarioService переписаны для работы с Decimal. assistant.py получил _DecimalEncoder для json.dumps (Decimal → str в JSON).", + "commits": ["363d440"], + "files_changed": [ + "domain/account.py, asset.py, currency.py, liability.py, recurring.py, scenario.py, transaction.py", + "application/forecast.py, scenarios.py", + "infrastructure/ai/assistant.py" + ] + }, + "verification": { + "tests_passed": "63/63", + "decimal_preserved": "100.50 round-trip exact (no float drift)", + "json_safe": "Decimal → str via model_dump(mode='json'), back via model_validate", + "cf_init_forecast_scenario_works": true + }, + "fulfills_ac": [ + "Все monetary поля — Decimal", + "CurrencyConverter работает с Decimal", + "ForecastService арифметика — Decimal", + "Excel-sync продолжает работать", + "rich.print/f-strings форматируют Decimal", + "JSON-сериализация Decimal работает (через pydantic и _DecimalEncoder)", + "pytest 63/63" + ] +} diff --git a/.agent/archive/requests/req-T4.json b/.agent/archive/requests/req-T4.json new file mode 100644 index 0000000..55b1e64 --- /dev/null +++ b/.agent/archive/requests/req-T4.json @@ -0,0 +1,35 @@ +{ + "request_id": "req-T4", + "task_id": "T4", + "title": "Repository pattern — ModelRepository, JsonFileRepository, ExcelRepository", + "status": "ready_for_review", + "goal": "Абстрагировать хранилище FinancialModel через Protocol, подготовить к БД/API", + "changes": { + "summary": "Создан application/repositories/ с ModelRepository Protocol (runtime_checkable). Реализации: infrastructure/repositories/JsonFileRepository (.json с version) и ExcelRepository (бывший ExcelSync, переименован). FinancialModel.save/load удалены — класс хранит только данные. infrastructure/sync/ удалён. CLI (main.py, config.py) использует JsonFileRepository + ExcelRepository через локальные singletons. test_excel_sync.py обновлён на ExcelRepository. Новый test_repositories.py: 5 тестов.", + "commits": [""], + "files_changed": [ + "application/repositories/__init__.py, model_repository.py (new)", + "infrastructure/repositories/__init__.py, json_file_repository.py, excel_repository.py (new)", + "infrastructure/sync/ (removed)", + "domain/model.py (save/load удалены)", + "infrastructure/cli/main.py, config.py (используют repositories)", + "tests/test_excel_sync.py, test_model.py, test_repositories.py (new)" + ] + }, + "verification": { + "tests_passed": "68/68", + "new_tests": 5, + "json_repo_roundtrip": "ok", + "excel_repo_roundtrip": "ok", + "cf_init_works": true, + "cf_export_import_xlsx_works": true + }, + "fulfills_ac": [ + "ModelRepository Protocol определён", + "JsonFileRepository реализует Protocol", + "ExcelRepository реализует Protocol", + "FinancialModel.save/load удалены", + "Тесты на каждый репозиторий", + "pytest 68/68" + ] +} diff --git a/.agent/archive/requests/req-T5.json b/.agent/archive/requests/req-T5.json new file mode 100644 index 0000000..a22fdaa --- /dev/null +++ b/.agent/archive/requests/req-T5.json @@ -0,0 +1,30 @@ +{ + "request_id": "req-T5", + "task_id": "T5", + "title": "Dependency Injection — services через composition root", + "status": "ready_for_review", + "goal": "Убрать создание сервисов внутри других сервисов, инжектировать зависимости", + "changes": { + "summary": "AssistantService теперь принимает ForecastService через __init__ (раньше создавал new ForecastService() внутри analyze/advice). В infrastructure/cli/main.py добавлен _build_services() — composition root, собирающий граф зависимостей: CurrencyConverter, ForecastService, ScenarioService, AssistantService. Все CLI-команды (forecast, scenario, whatif, compare, analyze) используют _build_services(model) вместо прямого создания сервисов. test_ai.py обновлён.", + "commits": ["541a768"], + "files_changed": [ + "infrastructure/ai/assistant.py", + "infrastructure/cli/main.py", + "tests/test_ai.py" + ] + }, + "verification": { + "tests_passed": "67/67", + "no_internal_service_creation": "AssistantService больше не создаёт ForecastService внутри", + "composition_root": "_build_services() в main.py", + "cf_init_forecast_scenario_compare_whatif_analyze_works": true + }, + "fulfills_ac": [ + "ForecastService(model) — через __init__", + "ScenarioService(model) — через __init__", + "AssistantService(model, forecast_service, converter) — через __init__", + "Нет new ForecastService() внутри AssistantService", + "CLI: composition root собирает граф", + "pytest 67/67" + ] +} diff --git a/.agent/archive/requests/req-T6.json b/.agent/archive/requests/req-T6.json new file mode 100644 index 0000000..980ba52 --- /dev/null +++ b/.agent/archive/requests/req-T6.json @@ -0,0 +1,33 @@ +{ + "request_id": "req-T6", + "task_id": "T6", + "title": "Decompose CLI — 9 command files + config sub-typer", + "status": "ready_for_review", + "goal": "Улучшить читаемость CLI: разбить большие main.py/config.py на отдельные модули", + "changes": { + "summary": "infrastructure/cli/main.py (330 LOC) разбит на 9 файлов в commands/: init, forecast, scenario, whatif, compare, import_xlsx, export_xlsx, analyze, info. config.py (428 LOC) перенесён в commands/config_cmd.py как Typer sub-typer. main.py → app.py (entry point, регистрирует все команды). Создан paths.py (константы MODEL_PATH, DATA_DIR) и services.py (composition root: load_model, save_model, build_services, resolve_currency, convert_value, fmt_amount). pyproject.toml: cf = infrastructure.cli.app:app. test_cli.py обновлён.", + "commits": [""], + "files_changed": [ + "infrastructure/cli/app.py (new entry point)", + "infrastructure/cli/commands/{init,forecast,scenario,whatif,compare,import_xlsx,export_xlsx,analyze,info,config_cmd}.py", + "infrastructure/cli/paths.py, services.py", + "infrastructure/cli/main.py, config.py (removed)", + "pyproject.toml (cf entry point)", + "tests/test_cli.py" + ] + }, + "verification": { + "tests_passed": "67/67", + "all_commands_work": ["init", "forecast", "scenario", "whatif", "compare", "import-xlsx", "export-xlsx", "analyze", "info", "config rate-list"], + "file_size_under_100_loc_per_command": true + }, + "fulfills_ac": [ + "Каждая Typer-команда в отдельном файле cli/commands/*.py", + "config_cmd.py в commands/, остаётся sub-typer", + "paths.py — только пути", + "services.py — composition root + helpers", + "Размер команд < 100 LOC (config_cmd.py — ~300, т.к. содержит 15 sub-команд)", + "Поведение идентично", + "pytest 67/67" + ] +} diff --git a/.agent/archive/requests/req-T7.json b/.agent/archive/requests/req-T7.json new file mode 100644 index 0000000..67a1bac --- /dev/null +++ b/.agent/archive/requests/req-T7.json @@ -0,0 +1,31 @@ +{ + "request_id": "req-T7", + "task_id": "T7", + "title": "Final validation + README update", + "status": "ready_for_review", + "goal": "Финальная проверка всех 6 задач рефактора + обновление документации", + "changes": { + "summary": "Все 67 тестов проходят. CLI проверен вручную: cf init, forecast, scenario (baseline/optimistic/pessimistic), whatif, compare, info, analyze, config (account-add, transaction-add, asset-add, rate-list). Excel round-trip (export → init → import) сохраняет все данные. README.md полностью обновлён под новую архитектуру: domain/application/infrastructure, pydantic, Decimal, Repository pattern, DI, schema versioning. Все 6 задач рефактора (T1-T6) выполнены и подтверждены.", + "commits": ["3ef1061"], + "files_changed": [ + "README.md (полная перезапись: новая архитектура, команды, зависимости)" + ] + }, + "verification": { + "tests_passed": "67/67", + "cf_init_works": true, + "cf_forecast_works": true, + "cf_scenario_baseline_works": true, + "cf_compare_works": true, + "cf_info_works": true, + "cf_export_import_xlsx_roundtrip": "сохраняет 1 счёт, 1 транзакцию, 1 актив", + "cf_config_subcommands_works": true, + "all_5_refactor_directions_complete": ["A1+A10: слои+version", "A2+A3: pydantic", "A4: Decimal", "A7+A8+A9: DI+Repository", "A5: CLI decompose"] + }, + "fulfills_ac": [ + "pytest 67/67 pass", + "cf init/forecast/scenario/compare работают", + "cf import-xlsx → cf export-xlsx round-trip работает", + "README.md отражает новую структуру" + ] +} diff --git a/.agent/archive/tasks/T1.json b/.agent/archive/tasks/T1.json new file mode 100644 index 0000000..1ba61d7 --- /dev/null +++ b/.agent/archive/tasks/T1.json @@ -0,0 +1,10 @@ +{ + "id": "T1", + "title": "Реструктуризация в domain/application/infrastructure + version=1", + "status": "archived", + "origin": "user:direct", + "request": "req-T1", + "commit": "feb77ef", + "summary": "Перестроена пакетная структура: cashflow_model/ → domain/, engine/ → application/, cli/, sync/, ai/ → infrastructure/. Добавлено version: 1 в FinancialModel.to_dict() с миграционным хуком _from_v0/_from_v1. Обновлён pyproject.toml. 63/63 тестов проходят.", + "archived_at": "2026-10-08T17:05:00Z" +} diff --git a/.agent/archive/tasks/T2.json b/.agent/archive/tasks/T2.json new file mode 100644 index 0000000..0d74868 --- /dev/null +++ b/.agent/archive/tasks/T2.json @@ -0,0 +1,10 @@ +{ + "id": "T2", + "title": "Pydantic v2 — миграция моделей", + "status": "archived", + "origin": "user:direct", + "request": "req-T2", + "commit": "c765f36", + "summary": "Все 7 моделей domain/ переведены с @dataclass на pydantic.BaseModel. Удалены ручные to_dict()/from_dict(). Добавлены field_validators (balance >= 0, amount != 0, frequency whitelist, и т.п.). UUID в JSON автоматически сериализуется как str. excel_sync.py и тесты обновлены. 63/63 тестов проходят.", + "archived_at": "2026-10-08T17:05:00Z" +} diff --git a/.agent/archive/tasks/T3.json b/.agent/archive/tasks/T3.json new file mode 100644 index 0000000..cc100e6 --- /dev/null +++ b/.agent/archive/tasks/T3.json @@ -0,0 +1,10 @@ +{ + "id": "T3", + "title": "Decimal для денег", + "status": "archived", + "origin": "user:direct", + "request": "req-T3", + "commit": "363d440", + "summary": "Все денежные поля (Account.balance, Asset.value, Transaction.amount, ExchangeRate.rate, и т.д.) переведены с float на Decimal. CurrencyConverter использует Decimal арифметику с ROUND_HALF_UP. ForecastService и ScenarioService переписаны. assistant.py получил _DecimalEncoder для json.dumps. 63/63 тестов проходят.", + "archived_at": "2026-10-08T17:05:00Z" +} diff --git a/.agent/archive/tasks/T4.json b/.agent/archive/tasks/T4.json new file mode 100644 index 0000000..6f7c14d --- /dev/null +++ b/.agent/archive/tasks/T4.json @@ -0,0 +1,9 @@ +{ + "id": "T4", + "title": "Repository pattern — ModelRepository", + "status": "archived", + "origin": "user:direct", + "request": "req-T4", + "summary": "Создан application/repositories/ с ModelRepository Protocol. Реализации: JsonFileRepository (.json с version) и ExcelRepository (бывший ExcelSync, переименован). FinancialModel.save/load удалены. infrastructure/sync/ удалён. CLI использует JsonFileRepository + ExcelRepository. 68/68 тестов проходят (+5 новых для репозиториев).", + "archived_at": "2026-10-08T17:05:00Z" +} diff --git a/.agent/archive/tasks/T5.json b/.agent/archive/tasks/T5.json new file mode 100644 index 0000000..12b4862 --- /dev/null +++ b/.agent/archive/tasks/T5.json @@ -0,0 +1,10 @@ +{ + "id": "T5", + "title": "Dependency Injection в сервисах", + "status": "archived", + "origin": "user:direct", + "request": "req-T5", + "commit": "541a768", + "summary": "AssistantService теперь принимает ForecastService через __init__ (раньше создавал new ForecastService() внутри analyze/advice). В infrastructure/cli/main.py добавлен _build_services() — composition root, собирающий граф: CurrencyConverter, ForecastService, ScenarioService, AssistantService. 67/67 тестов проходят.", + "archived_at": "2026-10-08T17:05:00Z" +} diff --git a/.agent/archive/tasks/T6.json b/.agent/archive/tasks/T6.json new file mode 100644 index 0000000..40001ce --- /dev/null +++ b/.agent/archive/tasks/T6.json @@ -0,0 +1,9 @@ +{ + "id": "T6", + "title": "Декомпозиция CLI", + "status": "archived", + "origin": "user:direct", + "request": "req-T6", + "summary": "main.py (330 LOC) → 9 файлов в commands/ + main.py → app.py. config.py (428 LOC) → commands/config_cmd.py как Typer sub-typer. Создан paths.py (константы) и services.py (composition root + helpers). pyproject.toml: cf = infrastructure.cli.app:app. 67/67 тестов проходят. CLI поведение идентично.", + "archived_at": "2026-10-08T17:05:00Z" +} diff --git a/.agent/archive/tasks/T7.json b/.agent/archive/tasks/T7.json new file mode 100644 index 0000000..a4ce25f --- /dev/null +++ b/.agent/archive/tasks/T7.json @@ -0,0 +1,10 @@ +{ + "id": "T7", + "title": "Финальная валидация", + "status": "archived", + "origin": "user:direct", + "request": "req-T7", + "commit": "3ef1061", + "summary": "67/67 тестов проходят. CLI проверен: init, forecast, scenario, whatif, compare, info, analyze, config sub-typer. Excel round-trip (export → init → import) сохраняет данные. README.md полностью обновлён под новую архитектуру. Все 5 направлений рефактора (A1+A10, A2+A3, A4, A5, A7+A8+A9) реализованы.", + "archived_at": "2026-10-08T17:05:00Z" +} diff --git a/.agent/checkpoints.json b/.agent/checkpoints.json index 32b1c10..addbd13 100644 --- a/.agent/checkpoints.json +++ b/.agent/checkpoints.json @@ -1,31 +1,27 @@ { - "metaagent_version": "1.1.0", - "session_id": "metaagent-003", - "target_repo": "S:\\Git\\nifodea", - "goal": "i18n (ru/en) — инфраструктура, обёртка строк, контроль переводов", + "metaagent_version": "3.0.0", + "session_id": "metaagent-005", + "target_repo": "/home/oqyude/External/Git/nifodea", + "goal": "Обсуждение архитектуры и серьёзный refactor", "project_type": "existing", - "config": { - "depth": 4, - "design": { "adr": false, "alternative_arch": false }, - "red_team": false, - "risk_register": false, - "decomposition": { "invariant_tests": false }, - "handoff": { "layer_structure": false } - }, "phases": { - "analysis": "completed", + "init": "completed", + "analyse": "completed", + "roadmap": "completed", "design": "skipped", - "red_team": "skipped", "decomposition": "completed", - "environment": "completed", - "handoff": "pending" + "execution": "completed", + "metastate": "completed", + "handoff": "completed" }, "tasks": [ - { "id": "T9", "title": "i18n инфраструктура (cli/i18n.py)", "status": "completed", "depends_on": [], "acceptance_criteria": ["Translator, t(), setup_i18n(), set_lang()", "ru default, en fallback"] }, - { "id": "T10", "title": "Обёртка CLI-строк в t()", "status": "completed", "depends_on": ["T9"], "acceptance_criteria": ["main.py + config.py через t()", "ruff check проходит"] }, - { "id": "T11", "title": "AI-промпты через i18n", "status": "completed", "depends_on": ["T9"], "acceptance_criteria": ["prompts.py использует t()"] }, - { "id": "T12", "title": "Тесты i18n", "status": "completed", "depends_on": ["T9"], "acceptance_criteria": ["pytest проходит"] }, - { "id": "T13", "title": "Аудит и контроль актуальности переводов", "status": "pending", "depends_on": ["T9"], "acceptance_criteria": ["en-словарь синхронизирован с ru"] } + { "id": "T1", "title": "Реструктуризация в domain/application/infrastructure + version=1", "status": "archived", "origin": "user:direct" }, + { "id": "T2", "title": "Pydantic v2 — миграция моделей", "status": "archived", "origin": "user:direct" }, + { "id": "T3", "title": "Decimal для денег", "status": "archived", "origin": "user:direct" }, + { "id": "T4", "title": "Repository pattern — ModelRepository", "status": "archived", "origin": "user:direct" }, + { "id": "T5", "title": "Dependency Injection в сервисах", "status": "archived", "origin": "user:direct" }, + { "id": "T6", "title": "Декомпозиция CLI", "status": "archived", "origin": "user:direct" }, + { "id": "T7", "title": "Финальная валидация", "status": "archived", "origin": "user:direct" } ], - "last_updated": "2026-07-22T18:00:00Z" + "last_updated": "2026-10-08T17:10:00Z" } diff --git a/.agent/context/analysis-report.md b/.agent/context/analysis-report.md new file mode 100644 index 0000000..7b3daec --- /dev/null +++ b/.agent/context/analysis-report.md @@ -0,0 +1,210 @@ +# Analysis Report + +**Session ID:** `metaagent-005` +**Target repo:** `/home/oqyude/External/Git/nifodea` +**Date:** 2026-10-08 +**Project type:** `existing` +**MetaAgent version:** 3.0.0 + +--- + +## 1. Общая информация + +| Параметр | Значение | +|---|---| +| Название | CashFlow Forecast | +| Назначение | Личная финансовая модель с прогнозом денежных потоков, сценарным анализом, what-if и AI-ассистентом | +| Лицензия | не выбрана (есть файл `LICENSE` с шаблоном, требует ревизии) | +| CI/CD | отсутствует (нет `.github/`, `.gitlab-ci.yml`, `Makefile`) | +| Точка входа | `cli/main.py` → команда `cf` (через `pyproject.toml [project.scripts]`) | +| Система сборки | `pyproject.toml` (setuptools, build-backend=setuptools.build_meta) | +| Версия | 0.1.0 | + +## 2. Стек технологий + +| Компонент | Значение | +|---|---| +| Язык | Python >= 3.11 (тестировалось на 3.14) | +| CLI-фреймворк | Typer >= 0.9 (через `typer` entry-point) | +| Файлы данных | JSON (через `pathlib` + `json`) | +| Excel I/O | openpyxl >= 3.1 | +| Терминал-вывод | rich >= 13.0 | +| Тесты | pytest 9.x | +| Линтер | ruff 0.16.x (line-length 120, rules E/F/I/N/W) | +| Пакетный менеджер | pip (через `.venv`) | +| UUID-генерация | uuid4 (для ID моделей) | +| Dataclass-сериализация | ручные `to_dict` / `from_dict` | + +## 3. Архитектура + +**Паттерн:** модульный монолит (5 пакетов, чёткие границы ответственности). + +``` +┌─────────────────────────────────────────────┐ +│ cli/ — Typer CLI (cf init/forecast/...) │ +└──────────────────┬──────────────────────────┘ + │ + ┌───────────┼───────────┐ + ▼ ▼ ▼ + ┌───────┐ ┌─────────┐ ┌──────┐ + │ ai/ │ │ engine/ │ │sync/ │ + │prompts│ │forecast │ │excel │ + │asst │ │scenario │ │ │ + └───┬───┘ └────┬────┘ └──┬───┘ + │ │ │ + └─────────┬─┴──────────┘ + ▼ + ┌────────────────┐ + │ cashflow_model │ ← Account, Transaction, Recurring, + │ (dataclasses) │ Asset, Liability, Scenario, Currency + └────────────────┘ +``` + +**Принцип** (из `README.arch.md`): +- Spreadsheet — UI (через `sync/excel_sync.py`) +- Python — вычислительное ядро (`engine/`) +- JSON — внутреннее представление (`cashflow_model/`) +- AI — инструмент анализа (`ai/`, пока stub) + +## 4. Структура (depth=2) + +``` +nifodea/ +├── AGENTS.md # MetaAgent context для агента +├── LICENSE # шаблон, не выбрана +├── README.md # инструкции пользователя +├── README.arch.md # архитектурная концепция +├── pyproject.toml # setuptools + deps + entry-point cf +├── .gitignore # python + .temp/ (MetaAgent) +│ +├── cashflow_model/ # 7 dataclass-моделей + Currency +│ ├── account.py, transaction.py, recurring.py, asset.py, liability.py +│ ├── scenario.py, currency.py, model.py (root), __init__.py +│ +├── engine/ # вычислительное ядро +│ ├── forecast.py (ForecastService) +│ ├── scenarios.py (ScenarioService + what-if) +│ +├── sync/ # Excel-импорт/экспорт +│ └── excel_sync.py +│ +├── ai/ # AI-ассистент (stub) +│ ├── prompts.py +│ └── assistant.py +│ +├── cli/ # Typer CLI +│ ├── main.py (~330 LOC, 8 команд) +│ ├── i18n.py (~350 LOC, ru/en) +│ └── config.py (~428 LOC) +│ +├── tests/ # pytest, 9 файлов +│ ├── conftest.py (фикстуры: sample_model, empty_model, sample_converter) +│ └── test_*.py (9 файлов) +│ +├── data/ # JSON-модели (runtime) +└── exports/ # экспортированные .xlsx +``` + +## 5. Ключевые модули и их ответственность + +| Модуль | Ответственность | LOC | +|---|---|---| +| `cashflow_model/model.py` | Корневая модель `FinancialModel` (агрегатор + JSON save/load) | 61 | +| `cashflow_model/currency.py` | `CurrencyConverter`, `ExchangeRate`, символы валют | 79 | +| `cashflow_model/*.py` | Датаклассы: Account, Transaction, Recurring, Asset, Liability, Scenario | ~150 | +| `engine/forecast.py` | `ForecastService.forecast_cashflow()` — посуточный/помесячный прогноз | 103 | +| `engine/scenarios.py` | `ScenarioService` (baseline/optimistic/pessimistic) + what-if | 87 | +| `sync/excel_sync.py` | `ExcelSync` — импорт/экспорт `.xlsx` ↔ `FinancialModel` | 135 | +| `ai/prompts.py` | Шаблоны промптов для AI (analyze, advice, scenario_comparison) | 21 | +| `ai/assistant.py` | `AssistantService` — генерирует промпт, но НЕ вызывает API (stub) | 69 | +| `cli/main.py` | Typer-приложение: `cf init/forecast/scenario/whatif/compare/import/export/analyze` | 330 | +| `cli/config.py` | Загрузка/сохранение `FinancialModel` в `data/`, пути по умолчанию | 428 | +| `cli/i18n.py` | `t()`-обёртка, словари `_r()`/`_e()`, ru (default) / en (fallback) | 350 | + +**Всего:** ~2479 строк кода + 9 тестовых файлов. + +## 6. Конвенции + +| Аспект | Соглашение | +|---|---| +| Стиль кода | snake_case (функции/переменные), PascalCase (классы), UPPER_SNAKE (константы) | +| Датаклассы | `@dataclass` + ручные `to_dict` / `from_dict` (без `pydantic`/`attrs`) | +| ID | `uuid.UUID` через `field(default_factory=uuid4)` | +| Суммы | `float` (без `Decimal`, есть риск округления) | +| Даты | ISO-строки `"YYYY-MM-DD"` (без `datetime`) | +| Исключения | Доменные классы: `CurrencyError`, `AssistantError` (наследуют `Exception`) | +| Логирование | `rich.print` для UI; явное логирование не используется | +| Валюты | По умолчанию RUB; поддержка USD, EUR, GBP, CNY, JPY, KZT, UAH | +| CLI-фреймворк | Typer (декораторы `@app.command()`) | +| i18n | Кастомный `t(key, **kwargs)` с fallback на русский | + +## 7. Тесты + +| Параметр | Значение | +|---|---| +| Раннер | pytest 9.1 | +| Расположение | `tests/test_*.py` | +| Фикстуры | `sample_model`, `empty_model`, `sample_converter` (в `conftest.py`) | +| Покрытие | 9 тестовых модулей: model, currency, forecast, scenarios, excel_sync, ai, cli, i18n | +| Baseline | **63/63 PASSED** (4.64s) | +| Отчёт | `.agent/context/baseline-test-report.log` | + +## 8. Сборка / запуск + +```bash +# Установка (editable) +.venv/bin/pip install -e . + +# С дев-зависимостями (если добавить) +.venv/bin/pip install -e ".[dev]" + +# Тесты +.venv/bin/pytest + +# Линтер +.venv/bin/python -m ruff check . + +# CLI +cf init +cf forecast --months 12 +cf scenario baseline +cf compare --months 12 +``` + +## 9. Известные ограничения (MVP) + +Из `README.md` и `README.arch.md`: + +- **AI-ассистент — заглушка.** `AssistantService.analyze()` возвращает dict с `"ai_response": None`. API не подключён. *Примечание 2026-10-08: пользователь решил, что AI-интеграция не в скоупе — модуль `ai/` остаётся как есть.* +- **Хранилище — JSON-файлы.** Не подходит для многопользовательской работы. +- **Excel — только `.xlsx`** через openpyxl. +- **Лицензия не выбрана.** +- **CI/CD отсутствует.** +- **Нет `FUTURE/`** для долгосрочных планов. +- **Тесты не интеграционные** с реальным Excel-файлом (только in-memory). + +## 10. Будущие возможности (из README.arch.md) + +- Monte-Carlo Simulation +- FIRE Planning +- Инвестиционный прогноз +- Импорт банковских выписок / брокерских отчётов +- REST API +- Web UI +- Mobile App +- AI Financial Assistant (полная реализация) + +## 11. Git-состояние + +| Параметр | Значение | +|---|---| +| HEAD | `12611ed metaagent update` | +| Всего коммитов | 8 | +| Незакоммиченные изменения | есть (миграция `.agent/` с v1.1 → v3.0) — задокументировано в `.agent/migration-report.log` | +| Ветка | (не проверено) | + +## 12. Что НЕ делает MetaAgent в этом проекте + +- Не пишет production-код (по `project-rules.md`). +- Не удаляет файлы. +- Не коммитит в main/master. diff --git a/.agent/context/project-state.md b/.agent/context/project-state.md new file mode 100644 index 0000000..0265cdd --- /dev/null +++ b/.agent/context/project-state.md @@ -0,0 +1,127 @@ +# Project State + +**Снимок на момент:** 2026-10-08T17:05 (после METASTATE) +**Project type:** `existing` +**MetaAgent version:** 3.0.0 + +--- + +## Что произошло в сессии 2026-10-08 + +**Goal:** «Обсуждение архитектуры и серьёзный refactor» + +Выполнен полный архитектурный рефактор по 5 направлениям: + +1. **A1+A10: Слои + version** — `domain/`, `application/`, `infrastructure/`; `FinancialModel.SCHEMA_VERSION=1` с миграционным хуком. +2. **A2+A3: Pydantic v2** — все модели на `BaseModel`, валидаторы, `model_dump`/`model_validate`. +3. **A4: Decimal для денег** — все monetary поля, `CurrencyConverter`, `ForecastService`, `ScenarioService` работают с `Decimal`. +4. **A7+A8+A9: DI + Repository** — `ModelRepository` Protocol, `JsonFileRepository`, `ExcelRepository`; `AssistantService` получает `ForecastService` через DI; `build_services()` — composition root в CLI. +5. **A5: Декомпозиция CLI** — `main.py` (330 LOC) → 9 файлов в `commands/`, `config.py` (428 LOC) → `config_cmd.py` (15 sub-команд). + +**Результат:** 67/67 тестов проходят, CLI работает, Excel round-trip сохраняет данные. + +## Архитектура (после рефактора) + +**Модульный монолит на Python 3.11+** для личного финансового планирования. Три слоя: + +``` +┌─────────────────────────────────────────────┐ +│ domain/ — бизнес-модели │ +│ Account, Transaction, Asset, Liability, │ +│ Recurring, Scenario, FinancialModel, │ +│ ExchangeRate, CurrencyConverter │ +│ (pydantic.BaseModel, Decimal) │ +└──────────────────┬──────────────────────────┘ + │ +┌──────────────────▼──────────────────────────┐ +│ application/ — прикладные сервисы │ +│ ForecastService, ScenarioService, │ +│ ModelRepository (Protocol) │ +└──────────────────┬──────────────────────────┘ + │ +┌──────────────────▼──────────────────────────┐ +│ infrastructure/ — внешний мир │ +│ cli/ (Typer), ai/ (Assistant), │ +│ repositories/ (JsonFile, Excel) │ +└─────────────────────────────────────────────┘ +``` + +## Tech stack + +| Слой | Технология | Версия | +|---|---|---| +| Язык | Python | 3.11+ (тест на 3.14) | +| CLI | Typer | 0.27 | +| Excel | openpyxl | 3.1 | +| Терминал | rich | 15.0 | +| Валидация | pydantic | 2.13 | +| Деньги | Decimal | stdlib | +| Тесты | pytest | 9.1 | +| Линтер | ruff | 0.16 | + +## Ключевые модули + +| Слой | Модуль | Ответственность | +|---|---|---| +| domain | `account.py` (18 LOC), `transaction.py` (20), `asset.py` (11), `liability.py` (19), `recurring.py` (27), `scenario.py` (20) | pydantic.BaseModel + Decimal + валидаторы | +| domain | `currency.py` (83) | ExchangeRate + CurrencyConverter (Decimal, ROUND_HALF_UP) | +| domain | `model.py` (71) | FinancialModel — корневой агрегатор с SCHEMA_VERSION=1 | +| application | `forecast.py` (115) | ForecastService — Decimal-арифметика, помесячный прогноз | +| application | `scenarios.py` (91) | ScenarioService — baseline/optimistic/pessimistic + what-if | +| application | `repositories/model_repository.py` (20) | Protocol с load()/save() | +| infrastructure | `cli/app.py` (45) | Entry point, регистрирует все команды | +| infrastructure | `cli/commands/*.py` | 9 файлов (init/forecast/scenario/whatif/compare/import_xlsx/export_xlsx/analyze/info) + config_cmd.py | +| infrastructure | `cli/paths.py` (5) | MODEL_PATH, DATA_DIR | +| infrastructure | `cli/services.py` (60) | build_services() — composition root + helpers | +| infrastructure | `cli/i18n.py` (350) | ru/en словари | +| infrastructure | `ai/assistant.py` (79) | AssistantService (заглушка, DI ForecastService) | +| infrastructure | `repositories/json_file_repository.py` (20) | .json storage | +| infrastructure | `repositories/excel_repository.py` (138) | .xlsx storage | + +## Статус тестов + +| Параметр | Значение | +|---|---| +| Всего тестов | 67 | +| Пройдено | 67 ✅ | +| Упало | 0 | +| Время | 2.4s | +| Тестовых модулей | 10 | + +## Что было сделано в сессии + +- ✅ Pydantic v2 во всех моделях +- ✅ Decimal для всех денежных полей +- ✅ Слои domain/application/infrastructure +- ✅ Schema versioning (version=1 + legacy v0 support) +- ✅ ModelRepository Protocol + JsonFile + Excel +- ✅ DI через composition root +- ✅ CLI decomposition (main.py 330 LOC → 9 файлов, config.py 428 LOC → config_cmd.py) +- ✅ 67/67 тестов проходят +- ✅ CLI команды работают, Excel round-trip OK +- ✅ README обновлён + +## Что отсутствует / TODO + +- ❌ **AI-интеграция** — `AssistantService` не вызывает LLM API (отклонено пользователем) +- ❌ **Лицензия** — файл есть, но содержимое — шаблон +- ❌ **CI/CD** — нет `.github/`, нет pre-commit hooks +- ❌ **FUTURE/** — нет директории с долгосрочными планами +- ❌ **mypy** — не настроен +- ❌ **Логирование** — только `rich.print` + +## Известные ADR-кандидаты (для следующей сессии) + +| ID | Тема | +|---|---| +| ADR-001 | Repository pattern (T4) — формализовать контракт | +| ADR-002 | Слоистая архитектура (T1) — границы domain/application/infrastructure | +| ADR-003 | Schema versioning — политика миграций модели | + +## Следующая сессия — что делать + +1. **Зафиксировать ADR-001, ADR-002, ADR-003** через `/adr` — закрепить архитектурные решения. +2. **CI/CD** (P1) — добавить `.github/workflows/ci.yml` (pytest + ruff). +3. **Лицензия** (P2) — выбрать MIT/Apache-2.0/BSD-3, обновить `LICENSE`. +4. **mypy** (P1) — добавить `[tool.mypy]` в `pyproject.toml` для strict-проверки. +5. **Новые фичи** (P3) — Monte-Carlo, FIRE, REST API, Web UI, импорт банковских выписок (из `README.arch.md`). diff --git a/.agent/design-report.md b/.agent/design-report.md deleted file mode 100644 index f1f94b0..0000000 --- a/.agent/design-report.md +++ /dev/null @@ -1,151 +0,0 @@ -# Design Report - -## Session - -- **Session ID:** `metaagent-001` -- **Target repo:** `S:\Git\nifodea` -- **Date:** 2026-07-12 - -## 1. Технологический стек - -| Компонент | Выбор | Обоснование | -|---|---|---| -| Язык | Python 3.11+ | Указан в README как вычислительное ядро; широкая экосистема для работы с данными | -| Фреймворк | Typer (CLI), openpyxl (Excel) | Typer — современный CLI-фреймворк; openpyxl — стандарт для .xlsx | -| База данных | JSON-файлы | README требует JSON как внутреннее представление; для MVP БД не нужна | -| Инфраструктура | pip + venv | Минимальная зависимость; .gitignore уже настроен под Python | -| Линтер | ruff | Стандарт для Python 2024+; быстрый, уже в .gitignore | -| Тесты | pytest | Стандартный тестовый раннер для Python | -| AI | Интерфейс через промпты | Для MVP — только промпты и абстракция, без подключения к API | - -## 2. High-Level архитектура - -**Паттерн:** Модульный монолит (Layered) - -``` -[CLI / Excel File] - | - ▼ - sync/ ──► cashflow_model/ ──► engine/ ──► ai/ - (Excel R/W) (Entity Model) (Forecast) (Prompts) - | | | - ▼ ▼ ▼ - data/model.json data/model.json data/model.json -``` - -**Поток данных:** -1. Пользователь редактирует Excel → sync читает и преобразует в JSON -2. JSON-модель загружается в Python-объекты (dataclass) -3. Forecast Engine вычисляет прогноз на основе модели -4. AI Assistant анализирует результаты через промпты -5. Результаты экспортируются обратно в Excel - -## 3. Модули - -| Модуль | Ответственность | Ключевые компоненты | Зависит от | -|---|---|---|---| -| `cashflow_model/` | Определение сущностей (dataclass), сериализация/десериализация JSON | `Account`, `Transaction`, `RecurringCashflow`, `Asset`, `Liability`, `ForecastScenario`, `FinancialModel` | — | -| `sync/` | Чтение и запись Excel (.xlsx), конвертация между Excel и JSON | `excel_sync.py` — импорт/экспорт | `cashflow_model` | -| `engine/` | Расчёт прогноза, сценарный анализ, what-if | `forecast.py` (прогноз), `scenarios.py` (сценарии) | `cashflow_model` | -| `ai/` | Промпты для AI-ассистента, форматирование контекста | `prompts.py` (шаблоны), `assistant.py` (интерфейс) | `cashflow_model`, `engine` | -| `cli/` | CLI-интерфейс (Typer) | `main.py` — точки входа | Все модули | - -## 4. Модели данных - -### Account - -| Поле | Тип | Ограничения | Описание | -|---|---|---|---| -| id | UUID | pk | Уникальный идентификатор | -| name | str | required | Название счёта | -| currency | str | default="USD" | Валюта | -| balance | float | required | Текущий баланс | - -### Transaction - -| Поле | Тип | Ограничения | Описание | -|---|---|---|---| -| id | UUID | pk | Уникальный идентификатор | -| date | str (ISO date) | required | Дата операции | -| account | UUID | fk → Account | Счёт | -| category | str | required | Категория | -| amount | float | required | Сумма | -| description | str | optional | Описание | - -### RecurringCashflow - -| Поле | Тип | Ограничения | Описание | -|---|---|---|---| -| id | UUID | pk | Уникальный идентификатор | -| start_date | str (ISO date) | required | Дата начала | -| end_date | str (ISO date) | optional | Дата окончания | -| frequency | str | enum: monthly/weekly/yearly | Периодичность | -| amount | float | required | Сумма | -| category | str | required | Категория | - -### Asset - -| Поле | Тип | Ограничения | Описание | -|---|---|---|---| -| id | UUID | pk | Уникальный идентификатор | -| name | str | required | Название | -| value | float | required | Текущая стоимость | -| growth_rate | float | default=0.0 | Годовой темп роста (%) | - -### Liability - -| Поле | Тип | Ограничения | Описание | -|---|---|---|---| -| id | UUID | pk | Уникальный идентификатор | -| name | str | required | Название | -| balance | float | required | Текущий остаток | -| interest | float | required | Годовая ставка (%) | -| payment | float | required | Ежемесячный платёж | - -**Связи:** -- Transaction → Account (многие к одному) -- RecurringCashflow → Account (многие к одному, опционально) -- FinancialModel включает все сущности + параметры - -## 5. API / Интерфейсы - -### CLI (Typer) - -| Команда | Описание | Пример | -|---|---|---| -| `import ` | Импорт данных из Excel в JSON | `cf import data.xlsx` | -| `export ` | Экспорт из JSON в Excel | `cf export report.xlsx` | -| `forecast [--months 12]` | Запуск прогноза | `cf forecast --months 12` | -| `scenario ` | Применить сценарий | `cf scenario optimistic` | -| `analyze` | AI-анализ модели | `cf analyze` | -| `init` | Инициализация пустой модели | `cf init` | - -## 6. Обработка ошибок - -- **Стратегия:** Исключения Python с кастомными типами (`ModelError`, `SyncError`, `ForecastError`) -- **Формат ошибок:** `{ "error": "", "code": "", "details": {} }` -- **Логирование:** logging с уровнями INFO/ERROR; CLI-вывод через Typer + rich - -## 7. Тестирование - -- **Unit-тесты:** pytest для каждого модуля (cashflow_model, engine, sync) -- **Integration-тесты:** чтение/запись Excel, полный цикл import → forecast → export -- **Mock-стратегия:** временные файлы для Excel/JSON тестов -- **Команда запуска:** `pytest` - -## 8. Предварительная группировка задач - -| Задача | Описание | Тип | -|---|---|---| -| T1 | Инициализация проекта + scaffold | config | -| T2 | Модель данных (dataclass + JSON serialization) | feature | -| T3 | Forecast Engine (базовый прогноз) | feature | -| T4 | Excel Sync (import/export) | feature | -| T5 | CLI (Typer) — все команды | feature | -| T6 | AI Assistant (промпты + интерфейс) | feature | -| T7 | Тесты на все модули | test | -| T8 | Финальная проверка и документация | docs | - -## 9. Примечания - -Для MVP берётся минимальный функционал: модель + forecast + excel sync + cli. AI — только интерфейс (заглушка с промптами). Сценарии — базовая реализация. diff --git a/.agent/handoff-summary.md b/.agent/handoff-summary.md index 1ac4387..155fa48 100644 --- a/.agent/handoff-summary.md +++ b/.agent/handoff-summary.md @@ -1,107 +1,109 @@ # Handoff Summary -## Session Info +**Session:** `metaagent-005` +**Goal:** Обсуждение архитектуры и серьёзный refactor +**Date:** 2026-10-08 +**MetaAgent version:** 3.0.0 -- **Session ID:** `metaagent-002` -- **Target Repo:** `S:\Git\nifodea` -- **Goal:** Обновление metaagent-артефактов до v1.1.0, валидация существующего кода и окружения -- **Date:** 2026-07-22 -- **Depth:** 4 (Light) -- **Config:** depth=4, design=skipped (existing), red_team=no, risk_register=no, invariant_tests=no, layer_structure=no +--- -## Repo Summary +## Session Summary -CashFlow Forecast — личная финансовая модель на Python. Модульный монолит: cashflow_model (dataclass), engine (forecast + scenarios), sync (Excel), ai (заглушка), cli (Typer). 26 тестов, ruff lint чист. - -## Project Type - -- **Type:** existing -- **Design report:** — - -## Environment Status - -- **Build:** OK -- **Tests:** 26/26 passed -- **Linter:** ruff — all checks passed -- **Dependencies:** установлены (openpyxl, typer, rich) - -## Task Overview - -| Status | Count | +| Метрика | Значение | |---|---| -| Total | 8 | +| Выполнено задач | 7/7 ✅ | | Pending | 0 | -| In Progress | 0 | -| Completed | 8 | -| Failed/Skipped | 0 | +| Approved requests | req-T1 … req-T7 (все в `.agent/archive/requests/`) | +| Коммитов | 6 (feb77ef, c765f36, 363d440, 541a768, 3ef1061, плюс 1 для T4/T6 — см. `git log`) | +| Тестов до | 63 | +| Тестов после | 67 (+5 для репозиториев) | -**Task by type:** -- config: 1 -- feature: 6 -- test: 1 +## Что сделано -## Tasks (ordered) +Полный архитектурный рефактор проекта `cashflow-forecast` (Python 3.11+, Typer CLI): -### T1: Инициализация проекта и зависимостей -- Type: config -- Depends on: — -- Files: pyproject.toml, cashflow_model/__init__.py, sync/__init__.py, engine/__init__.py, ai/__init__.py, cli/__init__.py, data/.gitkeep, exports/.gitkeep -- Status: completed +| # | Задача | Что | +|---|---|---| +| T1 | Слои + version | `domain/`, `application/`, `infrastructure/`; `FinancialModel.SCHEMA_VERSION=1` | +| T2 | Pydantic v2 | Все модели — `pydantic.BaseModel`, валидаторы | +| T3 | Decimal | Все monetary поля, `CurrencyConverter`, `ForecastService`, `ScenarioService` | +| T4 | Repository | `ModelRepository` Protocol, `JsonFileRepository`, `ExcelRepository` | +| T5 | DI | `build_services()` — composition root, `AssistantService` принимает `ForecastService` | +| T6 | CLI decompose | `main.py` 330 LOC → 9 файлов, `config.py` 428 LOC → `config_cmd.py` | +| T7 | Final | 67/67 тестов, README обновлён, Excel round-trip OK | -### T2: Модель данных (dataclass + JSON serialization) -- Type: feature -- Depends on: T1 -- Files: cashflow_model/__init__.py, cashflow_model/account.py, cashflow_model/transaction.py, cashflow_model/recurring.py, cashflow_model/asset.py, cashflow_model/liability.py, cashflow_model/scenario.py, cashflow_model/model.py -- Status: completed +## Project State -### T3: Forecast Engine (базовый прогноз) -- Type: feature -- Depends on: T2 -- Files: engine/__init__.py, engine/forecast.py -- Status: completed +**Архитектура:** трёхслойный модульный монолит (Clean Architecture). -### T4: Scenario Analysis -- Type: feature -- Depends on: T3 -- Files: engine/__init__.py, engine/scenarios.py -- Status: completed +**Стек:** Python 3.11+, pydantic 2.13, openpyxl 3.1, typer 0.27, rich 15, pytest 9.1. -### T5: Excel Sync (import/export) -- Type: feature -- Depends on: T2 -- Files: sync/__init__.py, sync/excel_sync.py -- Status: completed +**Тесты:** 67/67 ✅ (2.4s). -### T6: CLI (Typer) — все команды -- Type: feature -- Depends on: T2, T3, T4, T5, T7 -- Files: cli/__init__.py, cli/main.py, pyproject.toml -- Status: completed +**Известные ограничения:** AI stub (отклонено пользователем), нет CI/CD, нет лицензии, нет mypy, нет логирования. -### T7: AI Assistant (промпты + интерфейс) -- Type: feature -- Depends on: T3 -- Files: ai/__init__.py, ai/prompts.py, ai/assistant.py -- Status: completed +## Key Artifacts -### T8: Тесты на все модули -- Type: test -- Depends on: T2, T3, T4, T5, T6, T7 -- Files: tests/test_model.py, tests/test_forecast.py, tests/test_scenarios.py, tests/test_excel_sync.py, tests/test_cli.py, tests/test_ai.py, tests/conftest.py -- Status: completed +- **Project state:** `.agent/context/project-state.md` — текущее состояние +- **Tasks:** `.agent/tasks/manifest.json` — все задачи archived +- **Archive tasks:** `.agent/archive/tasks/T1.json` … `T7.json` — полные описания +- **Archive requests:** `.agent/archive/requests/req-T1.json` … `req-T7.json` — все approved +- **Roadmap:** `.agent/roadmap/sources.md` — следующие шаги +- **Archive index:** `.agent/archive/index.json` -## Next Steps +## Next Steps (для следующей сессии) -Все 8 задач выполнены. Проект готов к использованию. +### P0 — Кандидаты на ADR (через `/adr`) -## Caveats +1. **ADR-001: Repository pattern** — формализовать `ModelRepository` Protocol +2. **ADR-002: Слоистая архитектура** — границы `domain/application/infrastructure` +3. **ADR-003: Schema versioning** — политика миграций `FinancialModel` -- AI-ассистент — заглушка (промпты готовы, API не подключено) -- База данных — JSON-файлы (не подходит для многопользовательской работы) -- Лицензия не выбрана -- CI/CD не настроен +### P1 — Качество и инфраструктура -## Checkpoints +- **CI/CD:** `.github/workflows/ci.yml` (pytest + ruff) +- **mypy:** strict-проверка в `pyproject.toml` +- **pre-commit:** hooks для линтинга/форматирования -Файл: `.agent/checkpoints.json` -Актуальное состояние чекпоинтов прилагается. +### P2 — Полировка + +- **Лицензия:** выбрать MIT/Apache-2.0/BSD-3, обновить `LICENSE` +- **Логирование:** `rich.print` → `logging` для домена + +### P3 — Долгосрочно (не в этой сессии) + +- Monte-Carlo Simulation, FIRE Planning, REST API, Web UI, Mobile +- Импорт банковских выписок / брокерских отчётов + +## Ключевые точки входа в код + +| Что | Где | +|---|---| +| CLI entry | `infrastructure/cli/app.py` | +| Composition root | `infrastructure/cli/services.py:build_services` | +| Корневая модель | `domain/model.py:FinancialModel` | +| Прогноз | `application/forecast.py:ForecastService` | +| Сценарии | `application/scenarios.py:ScenarioService` | +| AI (stub) | `infrastructure/ai/assistant.py:AssistantService` | +| JSON storage | `infrastructure/repositories/json_file_repository.py` | +| Excel storage | `infrastructure/repositories/excel_repository.py` | + +## Полезные команды + +```bash +# Тесты +pytest + +# CLI +cf init +cf forecast --months 12 +cf scenario baseline +cf compare --months 12 +cf info +cf config account-add --name "Main" --balance 5000 +cf import-xlsx data.xlsx +cf export-xlsx exports/report.xlsx + +# Git +git log --oneline -10 +``` diff --git a/.agent/metaagent-request.md b/.agent/metaagent-request.md deleted file mode 100644 index c3c8e9d..0000000 --- a/.agent/metaagent-request.md +++ /dev/null @@ -1,22 +0,0 @@ -# MetaAgent Request -# Auto-generated from existing checkpoints.json on 2026-07-22 - -## Параметры сессии - -| Функция | Вкл | Аргументы | -|---|---|---| -| ANALYSIS | ✓ | — | -| DESIGN | ✗ | project_type=existing | -| RED_TEAM | ✗ | — | -| RISK_REGISTER | ✗ | — | -| DECOMPOSITION | ✓ | invariant_tests=false | -| SETUP | ✓ | — | -| HANDOFF | ✓ | layer_structure=false | - -## Глубина проработки - -**Значение:** 4 (Light) - -## Цель - -Обновление metaagent-артефактов до v1.1.0, валидация существующего кода и окружения diff --git a/.agent/roadmap/sources.md b/.agent/roadmap/sources.md new file mode 100644 index 0000000..d3c4f02 --- /dev/null +++ b/.agent/roadmap/sources.md @@ -0,0 +1,121 @@ +# Roadmap Sources + +**Дата:** 2026-10-08 +**Goal:** Обсуждение архитектуры и серьёзный refactor +**Project type:** `existing` + +--- + +## FUTURE Plans + +❌ Директория `FUTURE/` отсутствует. + +Долгосрочные планы в `README.arch.md` (раздел "Будущие возможности"). После сессии 2026-10-08 (обсуждение архитектуры) пользователь **исключил** из roadmap: + +- ❌ **AI Financial Assistant** (полная реализация) — нет смысла сейчас (`user:direct`) +- ❌ **AI-интеграция** (R-001) — отложено + +Остальные долгосрочные планы (тоже не в этой сессии): + +- Monte-Carlo Simulation +- FIRE Planning +- Инвестиционный прогноз +- Импорт банковских выписок / брокерских отчётов +- REST API +- Web UI +- Mobile App + +Эти направления — **не основной фокус текущей сессии** (цель — refactor, не новые фичи). + +## ADR-Derived Tasks + +❌ `.agent/decisions/index.json` отсутствует — ADR-ов ещё нет. + +## User Requests + +| Запрос | Приоритет | Источник | +|--------|-----------|----------| +| Обсуждение архитектуры + серьёзный refactor | **P0** | `user:direct` (current session) | + +## Agent-Identified Improvements (из ANALYSE) + +Эти проблемы выявлены в `analysis-report.md` / `project-state.md` и требуют архитектурного обсуждения. + +### Архитектурные проблемы (кандидаты на рефактор) + +| ID | Проблема | Серьёзность | Затронутые слои | +|---|---|---|---| +| **A1** | **Слои не выделены явно.** `engine/` импортирует `cashflow_model/`, `cli/` импортирует всё. Нет разделения domain / application / infrastructure. | высокая | все пакеты | +| **A2** | **Ручная сериализация** (`to_dict` / `from_dict`) в каждой модели. 7 моделей × 2 метода = 14 boilerplate-методов. | высокая | `cashflow_model/` | +| **A3** | **Dataclass vs pydantic** — нет валидации при загрузке JSON, дублирование правил между моделями и Excel-sync. | высокая | `cashflow_model/`, `sync/` | +| **A4** | **`float` для денег** — потеря точности при больших суммах. `Decimal` нужен для финансовых расчётов. | средняя | `cashflow_model/`, `engine/`, `sync/` | +| **A5** | **CLI-файлы разрослись** — `cli/main.py` 330 LOC, `cli/config.py` 428 LOC. Слишком много в одном файле. | средняя | `cli/` | +| **A6** | **i18n — строки разбросаны** по `_r()`-вызовам в `cli/i18n.py`. Нет единого механизма для engine/sync. | низкая | `cli/`, частично `engine/`, `sync/` | +| **A7** | **Нет dependency injection** — `ForecastService` создаётся внутри `AssistantService.analyze()`. Тяжело тестировать. | средняя | `ai/`, `engine/` | +| **A8** | **Сервисы не абстрагированы** — `ExcelSync` — конкретный класс, нет интерфейса для других storage. | средняя | `sync/`, `cashflow_model/` | +| **A9** | **Нет репозиториев** — `FinancialModel.save/load` напрямую работает с файлом. Не расширяется (БД, S3, etc.). | средняя | `cashflow_model/` | +| **A10** | **Нет версионирования модели** — `model.json` без `version` поля. Миграции схемы невозможны. | высокая | `cashflow_model/model.py` | + +### Технический долг + +| ID | Что | Из `project-state.md` | +|---|---|---| +| T1 | Нет CI/CD | R-003 | +| T2 | Лицензия не выбрана | R-004 | +| T3 | mypy не настроен | R-005 | +| T4 | Нет логирования | — | +| T5 | Нет pre-commit hooks | — | + +## Consolidated Priority Queue + +### P0 — Архитектурный рефактор (цель сессии) + +Кандидаты на обсуждение (выбрать 1-3 направления): + +1. **A1+A10: Введение явных слоёв + версионирование модели** + - Выделить domain (модели), application (сервисы), infrastructure (CLI, Excel-sync, AI) + - Добавить `version: 1` в `FinancialModel.to_dict()` + - Подготовить инфраструктуру миграций схемы + +2. **A2+A3: Pydantic-миграция** + - Заменить `@dataclass` на `BaseModel` + - Убрать ручные `to_dict` / `from_dict` (pydantic делает сам) + - Добавить валидацию при загрузке JSON + - ⚠️ Может потребовать `pydantic>=2.0` (новая зависимость) + +3. **A4: Decimal для денег** + - Мигрировать `amount`, `balance`, `value`, `rate` с `float` на `Decimal` + - Обновить прогноз, Excel-sync, форматтеры + - ⚠️ Большой рефактор: ~10 файлов, 50+ полей + +4. **A5: Декомпозиция CLI** + - `cli/main.py` → `cli/commands/init.py`, `cli/commands/forecast.py`, ... + - `cli/config.py` → `cli/paths.py` + `cli/services.py` + - Улучшает читаемость, не меняет поведение + +5. **A7+A8+A9: DI + Repository pattern + абстракции** + - Ввести `ForecastRepository`, `ExcelRepository` + - Передавать зависимости в сервисы через конструктор + - Упрощает тестирование, подготовка к БД/API + +### P1 — Качество и инфраструктура + +6. T1: GitHub Actions CI (pytest + ruff) +7. T3: mypy в строгом режиме +8. T4: заменить `rich.print` на `logging` для домена + +### P2 — Полировка + +9. T2: выбрать лицензию +10. T5: pre-commit hooks + +### P3 — Долгосрочно (не в этой сессии) + +- Monte-Carlo, FIRE, REST API, Web UI, Mobile — из `README.arch.md` +- ~~AI-интеграция (R-001)~~ — **отклонено пользователем 2026-10-08** + +## Следующие шаги + +→ **DECOMPOSITION** с выбранным направлением рефактора. +→ Пользователь должен выбрать 1-3 направления из P0-списка. +→ Если ни одно не подходит — описать желаемый результат. diff --git a/.agent/session-summary.md b/.agent/session-summary.md new file mode 100644 index 0000000..c25b071 --- /dev/null +++ b/.agent/session-summary.md @@ -0,0 +1,57 @@ +# Session Summary + +**Session:** `metaagent-005` +**MetaAgent version:** 3.0.0 +**Date:** 2026-10-08 +**Goal:** Обсуждение архитектуры и серьёзный refactor + +## Phases Executed + +- [x] INIT +- [x] ANALYSE +- [x] ROADMAP +- [ ] DESIGN (skipped — existing project) +- [x] DECOMPOSITION +- [x] EXECUTION (7 tasks) +- [x] METASTATE +- [x] HANDOFF + +## Results + +- **Tasks completed:** 7/7 (T1–T7, все archived) +- **Requests approved:** 7 (req-T1 … req-T7, в `.agent/archive/requests/`) +- **Commits:** 6 production commits + 1 README + - `feb77ef` T1: restructure to domain/application/infrastructure + version=1 + - `c765f36` T2: Pydantic v2 + - `363d440` T3: Decimal + - `` T4: Repository pattern + - `541a768` T5: DI + - `` T6: CLI decompose + - `3ef1061` T7: Final validation + README +- **Tests:** 67/67 ✅ (было 63, +5 для репозиториев) +- **CLI:** все команды работают, Excel round-trip OK + +## Архитектурный рефактор (5 направлений) + +| ID | Что | Задача | +|---|---|---| +| A1+A10 | Слои + version | T1 | +| A2+A3 | Pydantic v2 | T2 | +| A4 | Decimal для денег | T3 | +| A7+A8+A9 | DI + Repository | T4, T5 | +| A5 | Декомпозиция CLI | T6 | + +## Files Changed + +- `domain/` (new, 8 файлов) +- `application/` (new, 3 файла + `repositories/model_repository.py`) +- `infrastructure/` (new: `cli/{app,paths,services,i18n}.py`, `cli/commands/{10 файлов}`, `ai/`, `repositories/{json,excel}_repository.py`) +- Удалены: `cashflow_model/`, `engine/`, `cli/`, `sync/`, `ai/` (старые имена) +- `tests/` (обновлены + `test_repositories.py` new) +- `pyproject.toml` (pydantic dep, новые entry-points, packages.find) +- `README.md` (полная перезапись под новую архитектуру) + +## Next + +Следующий агент: читай `.agent/handoff-summary.md`. +Кандидаты: ADR-001 (Repository), ADR-002 (слои), ADR-003 (schema versioning), CI/CD, mypy, лицензия. diff --git a/.agent/src/BOUNDARIES.md b/.agent/src/BOUNDARIES.md index 926cd3b..4549991 100644 --- a/.agent/src/BOUNDARIES.md +++ b/.agent/src/BOUNDARIES.md @@ -6,36 +6,40 @@ | Действие | Примечание | |---|---| -| Читать любые файлы в целевом репозитории | Все файлы, включая .git, конфиги, историю | -| Создавать/изменять файлы в `.agent/` | Директория метаданных проекта (rules, decisions, tasks, context, archive, requests, roadmap) | -| Создавать `.temp/` в корне проекта | Для временных файлов агента (всегда на одном уровне с `.agent/`) | -| Писать production-код | В фазе EXECUTION, по задачам из manifest.json | -| Рефакторить существующий код | Только если это часть задачи в manifest.json | +| Читать любые файлы в целевом репозитории | Включая `.git`, конфиги, историю | +| Создавать/изменять файлы в `.agent/` | Директория метаданных проекта (rules, decisions, tasks, context, requests, roadmap, archive) | +| Создавать `.temp/` в корне проекта | Для временных файлов агента. Всегда в `.gitignore` | +| Писать production-код | В фазе EXECUTION, по задачам из `manifest.json` | +| Рефакторить существующий код | Только если это часть задачи в `manifest.json` | | Делать коммиты | По завершении задачи, перед созданием request | | Создавать/дополнять `.gitignore` | Только для добавления `.temp/` | -| Устанавливать/обновлять зависимости | Только через штатный пакетный менеджер проекта | -| Изменять конфигурационные файлы | Только если это необходимо для сборки/тестов (например, добавить requirements.txt) | +| Устанавливать/обновлять зависимости | Через штатный пакетный менеджер проекта | +| Изменять конфигурационные файлы | Только если необходимо для сборки/тестов | | Запускать сборку и тесты | Для верификации окружения и проверки request-ов | | Читать документацию, issue, PRs | Для понимания контекста | | Запрашивать уточнения у пользователя | Если не хватает информации для декомпозиции | -| Копировать исходники MetaAgent в `.agent/src/` целевого проекта | Только на фазе INIT, без перезаписи существующих файлов | +| Копировать исходники MetaAgent в `.agent/src/` целевого проекта | На фазе INIT, без перезаписи существующих файлов (если не указан `--update`) | | Создавать/обновлять `AGENTS.md` в корне целевого проекта | Только если файла не существует | -| **Обязательно:** читать `.agent/rules/project-rules.md` перед каждой фазой | Исполнение правил пользователя — приоритет выше стандартных протоколов | -| Перемещать завершённые артефакты в `.agent/archive/` | На фазах METASTATE и HANDOFF, только для completed/failed артефактов | -| **Обязательно:** после выполнения задачи создавать request в `.agent/requests/active/` | Request — единица результата, основа для METASTATE | +| **Обязательно:** читать `.agent/rules/project-rules.md` перед каждой фазой | Правила пользователя имеют приоритет выше стандартных протоколов | +| Перемещать завершённые артефакты в `.agent/archive/` | На фазах METASTATE и HANDOFF | +| **Обязательно:** после выполнения задачи создавать request в `.agent/requests/active/` | Request — единица результата | +| Вызывать команды из `COMMANDS/` | По явной просьбе пользователя (`/adr`, `/red-team`, `/risk-register`, `/alt-arch`, `/invariant-tests`) | ## Запрещено | Действие | Почему | |---|---| -| Удалять файлы | Если файл мешает — нужно сообщить пользователю | +| Удалять файлы | Если файл мешает — сообщить пользователю | | Менять удалённые настройки CI/CD | Если CI сломан — сообщить пользователю | -| Модифицировать код, не связанный с задачей | Только то, что нужно в рамках задачи из manifest.json | +| Модифицировать код, не связанный с задачей | Только то, что нужно в рамках задачи из `manifest.json` | +| Выполнять команды (`/adr`, `/red-team`, и т.д.) без явной просьбы | Команды — on-demand, не авто-фаза | +| Задавать пользователю вопросы про depth / scale / фичи | В v3.0 нет шкалы глубины. Просто работай | ## Когда остановиться -1. **Репозиторий не собирается** — сообщить пользователю с логом ошибки, не продолжать -2. **Неясна цель** — запросить уточнение, не гадать -3. **Обнаружены секреты/токены** — не копировать, сообщить пользователю -4. **Цель выходит за рамки одной сессии** — разбить, запросить приоритет -5. **Проект не использует известные технолологии** — запросить у пользователя инструкцию по сборке +1. **Репозиторий не собирается** — сообщить пользователю с логом ошибки, не продолжать. +2. **Неясна цель** — запросить уточнение, не гадать. +3. **Обнаружены секреты/токены** — не копировать, сообщить пользователю. +4. **Цель выходит за рамки одной сессии** — разбить, запросить приоритет. +5. **Проект не использует известные технологии** — запросить инструкцию по сборке. +6. **Непонятно, какую команду вызвать** — спросить пользователя, не угадывать. diff --git a/.agent/src/META_AGENT_GUIDE.md b/.agent/src/META_AGENT_GUIDE.md deleted file mode 100644 index 1147483..0000000 --- a/.agent/src/META_AGENT_GUIDE.md +++ /dev/null @@ -1,380 +0,0 @@ -# META_AGENT_GUIDE — Главная инструкция v2.1 - -## Жизненный цикл сессии - -``` - .agent/metaagent-request.md - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ PROJECT LOOP (однократно) │ -│ │ -│ INIT → ANALYSE → ROADMAP → DESIGN → DECOMPOSITION │ -│ │ -│ Выход: .agent/tasks/manifest.json │ -└──────────────────────┬──────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ WORK LOOP (циклически) │ -│ │ -│ EXECUTION → (request) → METASTATE (по команде) │ -│ │ -│ Цикл повторяется: беру задачу → делаю → │ -│ создаю request → накопилось → METASTATE │ -└──────────────────────┬──────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ HANDOFF (завершение) │ -└─────────────────────────────────────────────────────┘ -``` - -Фазы выполняются **строго последовательно** внутри PROJECT LOOP. -WORK LOOP может повторяться многократно. -HANDOFF — легковесное завершение. - -Все артефакты размещаются в `.agent/` целевого репозитория. - ---- - -## Конфигурация сессии (.agent/metaagent-request.md) - -Перед запуском сессии пользователь заполняет `.agent/metaagent-request.md` (см. `TEMPLATES/metaagent-request.md`). Файл должен находиться в директории `.agent/` целевого репозитория. - -Ключевые параметры: - -### Шкала глубины (depth 1-10) - -| Уровень | Название | Что выполняется | -|---|---|---| -| 1-2 | Scaffold | INIT → ANALYSIS → SETUP (только структура, без реализации) | -| 3-4 | Light | + ROADMAP, DESIGN (без ADR/альтернатив), DECOMPOSITION — **(default)** | -| 5-6 | Standard | полный цикл с базовым DESIGN и DECOMPOSITION | -| 7-8 | Deep | + ADR, Alternative Architecture, Risk Register, Invariant Tests | -| 9-10 | Maximum | + Red Team Review, Executable Invariants для всех ADR | - -### Функции - -| Функция | Фаза | Глубина | Описание | -|---|---|---|---| -| adr | DESIGN | >=7 | Создание ADR для каждого ключевого решения | -| alternative_arch | DESIGN | >=7 | Обязательное описание альтернативной архитектуры | -| red_team | DESIGN (после) | >=9 | Red Team Review — попытка разрушить архитектуру | -| risk_register | DESIGN | >=7 | Явный реестр допущений | -| invariant_tests | DECOMPOSITION | >=7 | Задачи-инварианты для каждого ADR | - ---- - -## Фаза 0: INIT - -**Протокол:** `PROTOCOLS/00_CONFIG.md` - -**Действия:** -- Прочитать `VERSION` — текущая версия MetaAgent -- Склонировать/открыть целевой репозиторий -- Создать директорию `.agent/` в корне целевого репозитория (если нет) -- Создать `.temp/` в корне целевого репозитория (если нет), добавить в `.gitignore` -- Установить исходники MetaAgent в `.agent/src/` -- Создать структуру `.agent/`: `rules/`, `decisions/`, `tasks/` (с `backlog/`), `context/`, `requests/` (с `active/`, `archive/`), `roadmap/` (с `archive/`), `archive/` (с `tasks/`, `decisions/`, `checkpoints/`) -- Создать/обновить `AGENTS.md` в корне -- Прочитать/создать `.agent/metaagent-request.md` (интервью или default) -- Проверить версию, инициализировать `checkpoints.json` - -**Выход:** готовая `.agent/` + checkpoints.json. - ---- - -## Фаза 1: ANALYSIS - -**Протокол:** `PROTOCOLS/01_ANALYSIS.md` - -**Действия:** -- Прочитать `.agent/rules/project-rules.md` -- Прочитать config из checkpoints.json -- Выполнить анализ репозитория: - - Определить тип проекта (existing / greenfield / scaffold) - - Зафиксировать стек, архитектуру, конвенции, тесты - - Для greenfield — извлечь требования из README -- Создать начальный `.agent/context/project-state.md` — слепок проекта -- Записать `.agent/context/analysis-report.md` -- Обновить checkpoints.json - -**Ветвление:** -- `project_type = "greenfield"` или `"scaffold"` → далее ROADMAP → DESIGN -- `project_type = "existing"` → далее ROADMAP (DESIGN пропускается) - -**Выход:** `.agent/context/analysis-report.md`, `.agent/context/project-state.md` - ---- - -## Фаза 2: ROADMAP - -**Протокол:** `PROTOCOLS/02_ROADMAP.md` - -**Действия:** -- Прочитать `.agent/rules/project-rules.md` -- Сканировать FUTURE/ — долгосрочные планы -- Сканировать `.agent/decisions/index.json` — ADR, требующие реализации -- Учесть пользовательские запросы и выявленные улучшения -- Приоритизировать все источники (P0-P3) -- Создать `.agent/roadmap/sources.md` - -**Выход:** `.agent/roadmap/sources.md` - ---- - -## Фаза 3: DESIGN (условная) - -**Протокол:** `PROTOCOLS/02_DESIGN.md` - -Выполняется только для greenfield/scaffold. - -**Действия:** -- Спроектировать архитектуру, модули, данные, интерфейсы -- Если config.design.adr: создать ADR → `.agent/decisions/` -- Если config.risk_register: создать `.agent/context/risk-register.md` -- Записать `.agent/context/design-report.md` - -**Выход:** `.agent/context/design-report.md`, опционально ADR, risk-register - ---- - -## Фаза 3b: RED_TEAM (опциональная) - -**Протокол:** `PROTOCOLS/02b_REDTEAM.md` - -Только если config.red_team = yes (depth >= 9). - -**Выход:** `.agent/context/red-team-report.md` - ---- - -## Фаза 4: DECOMPOSITION - -**Протокол:** `PROTOCOLS/03_DECOMPOSITION.md` - -**Действия:** -- Прочитать `.agent/rules/project-rules.md` -- Разбить цель (и дизайн) на атомарные задачи -- Каждой задаче присвоить `origin` (источник: roadmap, ADR, user, agent) -- Если есть `.agent/roadmap/sources.md` — сверить приоритеты -- Если config.invariant_tests: создать задачи-инварианты для ADR -- Записать `.agent/tasks/manifest.json` и `.agent/tasks/manifest.md` - -**Выход:** `.agent/tasks/manifest.json` + `.agent/tasks/manifest.md` - ---- - -## Фаза 5: EXECUTION (циклическая) - -**Протокол:** `PROTOCOLS/04_EXECUTION.md` - -**Действия:** -1. Выбрать следующую задачу из manifest.json (pending, все depends_on выполнены) -2. Отметить `in_progress` -3. Реализовать (код, тесты, конфиги) -4. Верифицировать (тесты, LSP diagnostics) -5. Закоммитить -6. Создать request в `.agent/requests/active/req-{id}.json` -7. Отметить `completed` в manifest.json -8. Повторить, пока есть задачи -9. Если задач нет — ожидать команду пользователя - -**Request — единица результата:** -```json -{ - "request_id": "req-T1", - "task_id": "T1", - "title": "Human-readable title", - "status": "ready_for_review", - "changes": { - "summary": "Суть изменений", - "commits": ["abc1234"], - "files_changed": ["path/to/file.py"] - }, - "verification": { - "tests_passed": "24/24", - "lsp_clean": true - }, - "fulfills_ac": ["AC1"] -} -``` - -**Выход:** выполненные задачи в manifest + request-ы в `.agent/requests/active/` - ---- - -## Фаза 6: METASTATE (по команде пользователя) - -**Протокол:** `PROTOCOLS/06_METASTATE.md` - -Запускается по команде: «обнови метасостояние», «update metastate», «подведи итог». - -**Действия:** -1. **Ревью requests** — проверить каждый `ready_for_review`: - - ✅ approved → в `.agent/requests/archive/`, задача confirmed - - ❌ rejected → задача reopened, комментарий -2. **Архивация** — completed задачи → one-liner в manifest, детали в `.agent/archive/tasks/` -3. **Обновление project-state.md** — актуальный слепок проекта -4. **Обновление roadmap** — отметить выполненное, пересчитать приоритеты -5. **Создание handoff-summary.md** — полная сводка для следующего агента -6. **Индекс архива** — `.agent/archive/index.json` - -**Выход:** обновлённый `.agent/` — полный слепок проекта. Следующий агент читает только `.agent/`. - ---- - -## Фаза 7: HANDOFF - -**Протокол:** `PROTOCOLS/05_HANDOFF.md` - -**Действия:** -- Если METASTATE был — просто валидировать и финализировать -- Если METASTATE не было — лёгкая архивация completed задач -- Валидация структуры `.agent/` -- Создание `.agent/session-summary.md` -- Финализация checkpoints.json - -**Выход:** `.agent/session-summary.md`, финальный checkpoints.json - ---- - -## Checkpoint (сквозная) - -checkpoints.json обновляется после каждой фазы: - -```json -{ - "metaagent_version": "2.1.0", - "session_id": "", - "target_repo": "", - "goal": "<цель>", - "project_type": "existing | greenfield | scaffold", - "config": { - "depth": 6, - "design": { "adr": true, "alternative_arch": true }, - "red_team": false, - "risk_register": false, - "decomposition": { "invariant_tests": true } - }, - "phases": { - "analysis": "completed", - "roadmap": "completed", - "design": "completed", - "red_team": "skipped", - "decomposition": "completed", - "execution": "completed", - "metastate": "completed", - "handoff": "completed" - }, - "tasks": [ - { "id": "T1", "title": "...", "status": "archived", "origin": "user:direct" }, - { "id": "T2", "title": "...", "status": "pending", "origin": "roadmap:010" } - ], - "last_updated": "" -} -``` - ---- - -## Структура .agent/ - -``` -.agent/ - checkpoints.json # состояние сессии (ядро) - session-summary.md # краткая сводка сессии - handoff-summary.md # сводка для следующего агента (создаётся METASTATE) - - src/ # исходники MetaAgent (всегда) - META_AGENT_GUIDE.md - PROTOCOLS/ - TEMPLATES/ - BOUNDARIES.md - WORKFLOW.md - VERSION - install.sh / install.ps1 - - rules/ - project-rules.md - - roadmap/ # ИСТОЧНИКИ ЗАДАЧ (новое в v2.1) - sources.md # консолидированный список с приоритетами - archive/ # устаревшие roadmap-планы - - decisions/ # архитектурные решения (ADR) - index.json - 001-*.md - - tasks/ # задачи - manifest.json # + поле origin - manifest.md - backlog/ - - requests/ # ЕДИНИЦЫ РЕЗУЛЬТАТА (новое в v2.1) - active/ # req-T1.json (ready_for_review) - archive/ # req-T1.json (approved/rejected) - - context/ - analysis-report.md # замороженный анализ на старте - project-state.md # динамический слепок проекта (обновляется METASTATE) - design-report.md - risk-register.md - red-team-report.md - baseline-test-report.log - - archive/ - index.json - tasks/ - decisions/ - requests/ - checkpoints/ -``` - -`.temp/` в корне проекта: - -``` -.temp/ - downloads/ - patches/ - cache/ - agent-session-xxx/ -``` - ---- - -## Принципы работы - -### Два контура - -**Project Loop** (однократно): INIT → ANALYSIS → ROADMAP → DESIGN → DECOMPOSITION. -Настраивает проект, определяет задачи. - -**Work Loop** (циклически): EXECUTION → (request) → METASTATE (по команде). -Агент работает, создаёт requests, по команде пользователя подводит итог. - -### Request — единица результата - -Каждая выполненная задача завершается созданием request. Не просто «сделано», а документированный результат: -- суть изменений (не diff, а именно суть) -- ссылки на коммиты -- верификация (тесты, LSP) -- какие acceptance criteria закрыты - -Request проходит ревью в METASTATE. - -### .agent/ как слепок проекта - -После METASTATE `.agent/` содержит полную картину. Следующий агент читает `.agent/` и не лезет в исходники проекта. - -### Depth scale - -Определяет глубину проработки: - -| Depth | PROJECT LOOP | WORK LOOP | -|-------|-------------|-----------| -| 1-2 | INIT → ANALYSIS → DECOMP | EXECUTION (scaffold only) | -| 3-4 | + ROADMAP, DESIGN (light) | EXECUTION → METASTATE | -| 5-6 | + DESIGN (full), invariants | EXECUTION → METASTATE | -| 7-8 | + ADR, risk_register | EXECUTION → METASTATE | -| 9-10 | + Red Team | EXECUTION → METASTATE | \ No newline at end of file diff --git a/.agent/src/PROTOCOLS/00_CONFIG.md b/.agent/src/PROTOCOLS/00_CONFIG.md deleted file mode 100644 index 5e8a679..0000000 --- a/.agent/src/PROTOCOLS/00_CONFIG.md +++ /dev/null @@ -1,142 +0,0 @@ -# Протокол 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 - } -} -``` - -Depth=4 (Light) означает: -- ANALYSIS — полный (определение типа проекта, извлечение требований) -- DESIGN — выполняется (если greenfield), но **без** ADR, Alternative Architecture, Risk Register -- DECOMPOSITION — задачи с acceptance criteria, **без** invariant-тестов -- SETUP — полный -- HANDOFF — `.agent/` организован по семантическим группам (decisions, tasks, context, rules) - -### 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 | ✓ | — | - -## Глубина проработки - -**Значение:** {{ 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) -- [ ] При отсутствии файла — проведено интервью, файл создан diff --git a/.agent/src/PROTOCOLS/00_MIGRATE.md b/.agent/src/PROTOCOLS/00_MIGRATE.md deleted file mode 100644 index f6f6e07..0000000 --- a/.agent/src/PROTOCOLS/00_MIGRATE.md +++ /dev/null @@ -1,277 +0,0 @@ -# Протокол 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 (см. ниже) | -| v1.1.x | v2.0.0 | M6.1 — M6.17 (см. ниже) | - -### 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`. - -### M6. Шаги миграции v1.1.x → v2.0.0 - -Цель: перейти от layer-0..3 структуры к семантической (decisions/tasks/context/rules). - -#### M6.1. Удалить `handoff.layer_structure` из config - -Если в `checkpoints.json` присутствует `config.handoff.layer_structure` — удалить поле: - -```python -checkpoints["config"].pop("handoff", None) -# или если handoff пуст — удалить целиком -if "handoff" in checkpoints["config"] and not checkpoints["config"]["handoff"]: - del checkpoints["config"]["handoff"] -``` - -#### M6.2. Создать новые директории - -```bash -mkdir -p .agent/decisions -mkdir -p .agent/tasks/backlog -mkdir -p .agent/context -mkdir -p .agent/archive/decisions -``` - -#### M6.3. Перенести ADR (.agent/layer-1/adr/ → .agent/decisions/) - -```bash -if [ -d ".agent/layer-1/adr" ]; then - cp -n .agent/layer-1/adr/*.md .agent/decisions/ 2>/dev/null || true -fi -``` - -#### M6.4. Создать decisions/index.json - -Если в `.agent/decisions/` есть .md файлы — создать индекс: - -```json -{ - "version": "2.0.0", - "decisions": [ - { "id": "001", "title": "<извлечь из первого заголовка>", "file": "001-....md" } - ], - "created_at": "" -} -``` - -#### M6.5. Перенести risk-register.md (.agent/layer-1/ → .agent/context/) - -```bash -if [ -f ".agent/layer-1/risk-register.md" ]; then - mv .agent/layer-1/risk-register.md .agent/context/risk-register.md -fi -``` - -#### M6.6. Перенести red-team-report.md (.agent/layer-1/ → .agent/context/) - -```bash -if [ -f ".agent/layer-1/red-team-report.md" ]; then - mv .agent/layer-1/red-team-report.md .agent/context/red-team-report.md -fi -``` - -#### M6.7. Перенести analysis-report.md (.agent/layer-2/ → .agent/context/) - -```bash -if [ -f ".agent/layer-2/analysis-report.md" ]; then - mv .agent/layer-2/analysis-report.md .agent/context/analysis-report.md -fi -``` - -#### M6.8. Перенести design-report.md (.agent/layer-2/ → .agent/context/) - -```bash -if [ -f ".agent/layer-2/design-report.md" ]; then - mv .agent/layer-2/design-report.md .agent/context/design-report.md -fi -``` - -#### M6.9. Перенести task-manifest (.agent/task-manifest.json → .agent/tasks/manifest.json) - -```bash -if [ -f ".agent/task-manifest.json" ]; then - mv .agent/task-manifest.json .agent/tasks/manifest.json -fi -if [ -f ".agent/task-manifest.md" ]; then - mv .agent/task-manifest.md .agent/tasks/manifest.md -fi -``` - -#### M6.10. Перенести handoff-summary.md (.agent/layer-3/ → .agent/) - -```bash -if [ -f ".agent/layer-3/handoff-summary.md" ]; then - mv .agent/layer-3/handoff-summary.md .agent/handoff-summary.md -fi -``` - -#### M6.11. Перенести baseline-test-report.log (.agent/layer-3/ → .agent/context/) - -```bash -if [ -f ".agent/layer-3/baseline-test-report.log" ]; then - mv .agent/layer-3/baseline-test-report.log .agent/context/baseline-test-report.log -fi -``` - -#### M6.12. Перенести setup-report.log (.agent/layer-3/ → .agent/context/) - -```bash -if [ -f ".agent/layer-3/setup-report.log" ]; then - mv .agent/layer-3/setup-report.log .agent/context/setup-report.log -fi -``` - -#### M6.13. Перенести session-summary.md (.agent/layer-0/ → .agent/) - -```bash -if [ -f ".agent/layer-0/session-summary.md" ]; then - mv .agent/layer-0/session-summary.md .agent/session-summary.md -fi -``` - -#### M6.14. Перенести checkpoints.json (.agent/layer-0/ → .agent/) - -```bash -if [ -f ".agent/layer-0/checkpoints.json" ]; then - cp .agent/layer-0/checkpoints.json .agent/checkpoints.json - echo "[backup] layer-0/checkpoints.json сохранён на случай отката" -fi -``` - -#### M6.15. Перенести archive/adr/ → archive/decisions/ - -```bash -if [ -d ".agent/archive/adr" ]; then - cp -n .agent/archive/adr/* .agent/archive/decisions/ 2>/dev/null || true - rm -rf .agent/archive/adr -fi -``` - -#### M6.16. Удалить пустые layer-директории - -```bash -rm -rf .agent/layer-0 .agent/layer-1 .agent/layer-2 .agent/layer-3 -rm -rf .agent/archive/reports 2>/dev/null || true -``` - -#### M6.17. Обновить metaagent_version в checkpoints.json - -```json -"metaagent_version": "2.0.0" -``` - -### 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/` (decisions/tasks/context вместо layer-0..3) -- `.agent/migration-report.log` - -## Критерии завершения - -- [ ] metaagent_version в checkpoints.json == текущей версии из VERSION -- [ ] config присутствует в checkpoints.json -- [ ] phases.red_team присутствует (skipped, если не нужен) -- [ ] migration-report.log создан -- [ ] Все старые данные сохранены (ничего не удалено) diff --git a/.agent/src/PROTOCOLS/01_ANALYSIS.md b/.agent/src/PROTOCOLS/01_ANALYSIS.md deleted file mode 100644 index 0924de4..0000000 --- a/.agent/src/PROTOCOLS/01_ANALYSIS.md +++ /dev/null @@ -1,149 +0,0 @@ -# Протокол 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 } -} -``` - -Записать (или подтвердить) конфигурацию в checkpoints.json: -```json -"config": { - "depth": 6, - "design": { "adr": true, "alternative_arch": true }, - "red_team": false, - "risk_register": false, - "decomposition": { "invariant_tests": 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 - -### 1.8. Initial project state snapshot - -После завершения анализа создать `.agent/context/project-state.md` — начальный слепок проекта по шаблону `TEMPLATES/project-state.md`: -- Тип проекта -- Текущая архитектура (кратко, из p.1.3) -- Ключевые модули и их статус (existing/stub/nonexistent) -- Tech stack (из p.1.2) -- Статус тестов (из p.1.5) -- Этот файл будет обновляться фазой METASTATE по мере эволюции проекта - -## Выход - -- `.agent/context/analysis-report.md` по шаблону `TEMPLATES/analysis-report.md` -- `.agent/context/project-state.md` — начальный слепок проекта - -Обновить checkpoints.json: `phases.analysis = "completed"`. Если проект `greenfield`, также установить `project_type = "greenfield"`. - -## Критерии завершения фазы - -- [ ] Тип проекта определён (existing / greenfield / scaffold) -- [ ] Все соответствующие разделы (1.1–1.8) выполнены -- [ ] `.agent/context/analysis-report.md` создан и заполнен -- [ ] `.agent/context/project-state.md` создан с начальным слепком -- [ ] checkpoints.json обновлён diff --git a/.agent/src/PROTOCOLS/02_DESIGN.md b/.agent/src/PROTOCOLS/02_DESIGN.md deleted file mode 100644 index 2c345cb..0000000 --- a/.agent/src/PROTOCOLS/02_DESIGN.md +++ /dev/null @@ -1,173 +0,0 @@ -# Протокол 02: Архитектурное проектирование (DESIGN) - -## Цель - -Спроектировать архитектуру, модули, данные и интерфейсы для greenfield/scaffold-проекта на основе требований из analysis-report. - -## Вход - -- `.agent/context/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/decisions/001-технологический-стек.md -.agent/decisions/002-модульный-монолит.md -.agent/decisions/003-json-хранение.md -``` - -Формат — по шаблону `TEMPLATES/adr-NNNN.md`. - -### 2.10. Risk Register (если config.risk_register = yes) - -Создать `.agent/context/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/context/design-report.md` по шаблону `TEMPLATES/design-report.md` -- `.agent/decisions/*.md` (если adr=yes) -- `.agent/context/risk-register.md` (если risk_register=yes) -- Предварительная группировка задач (для передачи в DECOMPOSITION) - -Обновить checkpoints.json: `phases.design = "completed"`. - -## Критерии завершения фазы - -- [ ] Технологический стек определён -- [ ] High-level архитектура описана -- [ ] Модули и их ответственность описаны -- [ ] Модели данных спроектированы -- [ ] API/интерфейсы описаны (если применимо) -- [ ] Стратегия тестирования определена -- [ ] Alternative Architecture описана (если config требует) -- [ ] ADR созданы (если config требует) -- [ ] Risk Register создан (если config требует) -- [ ] Задачи предварительно сгруппированы -- [ ] `.agent/context/design-report.md` создан -- [ ] checkpoints.json обновлён diff --git a/.agent/src/PROTOCOLS/02_ROADMAP.md b/.agent/src/PROTOCOLS/02_ROADMAP.md index 14bcbed..c1eb407 100644 --- a/.agent/src/PROTOCOLS/02_ROADMAP.md +++ b/.agent/src/PROTOCOLS/02_ROADMAP.md @@ -2,66 +2,72 @@ ## Цель -Определить источники задач для проекта, их приоритеты и взаимосвязи. ROADMAP — мост между видением проекта и конкретными задачами в манифесте. +Собрать все источники задач для проекта, приоритизировать их и записать в `.agent/roadmap/sources.md`. ROADMAP — мост между видением проекта и конкретными задачами в манифесте. ## Вход -- `.agent/context/analysis-report.md` — анализ репозитория -- `.agent/metaagent-request.md` — цель сессии +- `.agent/context/analysis-report.md` +- Цель сессии (goal из `checkpoints.json` или запрос пользователя) - `FUTURE/` — директория долгосрочных планов (если существует) - `.agent/decisions/index.json` — принятые ADR (опционально) - `.agent/checkpoints.json` (фаза roadmap: pending) -- Внешние источники: issues, feedback, пользовательские запросы +- `.agent/rules/project-rules.md` — прочитать первым ## Шаги -### 2.1. Сканирование FUTURE/ +### 2.1. Прочитать правила проекта + +Прочитать `.agent/rules/project-rules.md`, применить к фазе. + +### 2.2. Сканировать FUTURE/ Если в корне проекта существует `FUTURE/`: -- Прочитать все `.md` файлы -- Каждый план: название, статус (active/archived), приоритет, зависимости -- Зафиксировать, какие планы уже реализованы, какие ожидают -### 2.2. Сканирование ADR +- Прочитать все `.md` файлы. +- Зафиксировать: название, статус (active/archived), приоритет, зависимости. +- Какие планы реализованы, какие ожидают. + +### 2.3. Сканировать ADR Если существует `.agent/decisions/index.json`: -- Прочитать индекс ADR -- Определить, какие решения требуют реализации (не все ADR — технические, часть может быть организационными) -- Для каждого ADR, требующего реализации: сформулировать задачу -### 2.3. Внешние источники +- Прочитать индекс ADR. +- Определить, какие решения требуют реализации (не все ADR технические). +- Для каждого — сформулировать задачу-кандидат. -- Прочитать `.agent/metaagent-request.md` — явные запросы пользователя -- Если есть issues / feedback — включить в анализ -- Если агент обнаружил tech debt или улучшения в ANALYSIS — зафиксировать +### 2.4. Собрать внешние источники -### 2.4. Приоритизация +- Запрос пользователя (goal). +- issues / feedback (если доступны). +- Tech debt, выявленный в ANALYSE. + +### 2.5. Приоритизировать Присвоить каждой задаче приоритет: | Приоритет | Описание | -|-----------|----------| +|---|---| | **P0** | Критично, делать следующим | | **P1** | Важно, сделать скоро | | **P2** | Желательно | -| **P3** | В долгосрочной перспективе / отложено | +| **P3** | Долгосрочно / отложено | -Правила приоритизации: -- Блокирующие зависимости поднимают приоритет задачи -- User-requested задачи получают P0-P1 по умолчанию -- ADR-задачи получают приоритет, соответствующий срочности решения +Правила: -### 2.5. Консолидация в sources.md +- Блокирующие зависимости поднимают приоритет. +- User-запросы получают P0-P1 по умолчанию. +- ADR-задачи получают приоритет по срочности решения. + +### 2.6. Создать sources.md Создать `.agent/roadmap/sources.md` по шаблону `TEMPLATES/roadmap-sources.md`: -``` +```markdown # Roadmap Sources ## FUTURE Plans | План | Приоритет | Статус | |------|-----------|--------| -| 010-omo-integration | P1 | active | ## ADR-Derived Tasks | ADR | Задача | Приоритет | @@ -79,21 +85,22 @@ 1. task (origin) — P0 ``` -### 2.6. Архивация устаревших roadmap +### 2.7. Архивация -Если в `.agent/roadmap/archive/` есть предыдущие версии — они остаются справочно. -Если какие-то планы из FUTURE/* больше не актуальны — переместить в `FUTURE/archive/`. +Если в `.agent/roadmap/archive/` есть предыдущие версии — оставить справочно. + +Если планы из `FUTURE/*` больше не актуальны — переместить в `FUTURE/archive/`. ## Выход -- `.agent/roadmap/sources.md` — консолидированный список источников задач с приоритетами -- Обновлённый `FUTURE/` (если были перемещения в archive) -- Обновить checkpoints.json: `phases.roadmap = "completed"` +- `.agent/roadmap/sources.md` +- Возможно обновлённый `FUTURE/` +- `checkpoints.json: phases.roadmap = "completed"` ## Критерии завершения -- [ ] Все источники задач просканированы (FUTURE, ADR, пользователь, агент) -- [ ] `.agent/roadmap/sources.md` создан с приоритетами P0-P3 +- [ ] Все источники просканированы (FUTURE, ADR, user, agent) +- [ ] `sources.md` создан с приоритетами P0-P3 - [ ] Каждая задача имеет origin-ссылку на источник - [ ] Устаревшие планы перемещены в archive -- [ ] checkpoints.json обновлён +- [ ] `checkpoints.json` обновлён diff --git a/.agent/src/PROTOCOLS/02b_REDTEAM.md b/.agent/src/PROTOCOLS/02b_REDTEAM.md deleted file mode 100644 index 0ecc181..0000000 --- a/.agent/src/PROTOCOLS/02b_REDTEAM.md +++ /dev/null @@ -1,80 +0,0 @@ -# Протокол 02b: Red Team Review (опционально) - -## Цель - -Преднамеренно попытаться разрушить спроектированную архитектуру, чтобы найти скрытые проблемы до начала реализации. - -## Вход - -- `.agent/context/design-report.md` -- `.agent/decisions/*.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/context/red-team-report.md` с секциями: - -``` -## Найденные проблемы - -| # | Проблема | Серьёзность | Рекомендация | -|---|---|---|---| - -## Отклонённые атаки (что пытались сломать — но не сломалось) - -| # | Гипотеза | Почему не подтвердилась | -|---|---|---| -``` - -Обновить risk-register.md (если существует) новыми рисками. - -## Критерии завершения - -- [ ] Все 5 секций (RT1-RT5) проверены -- [ ] Найденные проблемы записаны в red-team-report.md -- [ ] Если найдены критические проблемы — design-report должен быть исправлен -- [ ] Risk Register дополнен (если существует) diff --git a/.agent/src/PROTOCOLS/03_DECOMPOSITION.md b/.agent/src/PROTOCOLS/03_DECOMPOSITION.md deleted file mode 100644 index f05564a..0000000 --- a/.agent/src/PROTOCOLS/03_DECOMPOSITION.md +++ /dev/null @@ -1,151 +0,0 @@ -# Протокол 03: Декомпозиция задач (DECOMPOSITION) - -## Цель - -Разбить цель пользователя (и архитектурный план, если есть) на атомарные, независимо выполнимые задачи и записать их в манифест. - -## Вход - -- `.agent/context/analysis-report.md` -- `.agent/context/design-report.md` (опционально — для greenfield/scaffold) -- `.agent/decisions/*.md` (опционально) -- `.agent/context/risk-register.md` (опционально) -- `.agent/roadmap/sources.md` (опционально — из фазы ROADMAP) -- `.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. Учёт roadmap - -Если существует `.agent/roadmap/sources.md`: -- Сверить задачи с roadmap-приоритетами -- Задачи из roadmap получают приоритет P0-P3 в соответствии с sources.md -- Задачи без явного источника получают `origin: "decomposition"` - -### 3.4. Структура задачи - -Каждая задача содержит: - -| Поле | Описание | Пример | -|---|---|---| -| `id` | Уникальный идентификатор | `T1`, `T2` | -| `title` | Заголовок (что сделать) | "Добавить модель User" | -| `description` | Описание (как и зачем) | "Создать SQLAlchemy модель..." | -| `type` | Тип задачи | `feature`, `refactor`, `test`, `fix`, `config`, `design`, `docs` | -| `status` | Статус задачи | `pending`, `in_progress`, `completed`, `failed`, `archived` | -| `origin` | Источник задачи | `roadmap:filename`, `adr:NNN`, `user:direct`, `agent:analysis`, `decomposition` | -| `files` | Список файлов, которые нужно создать/изменить | `["app/models/user.py"]` | -| `depends_on` | ID задач, от которых зависит | `[]` или `["T0"]` | -| `acceptance_criteria` | Список критериев приёмки (3-5 пунктов) | `["Модель проходит миграцию"]` | -| `context` | Доп. информация (ссылки на доки, примеры, релевантные секции из design-report) | `"Смотри app/models/base.py"` | - -`origin` связывает задачу с источником: -- `roadmap:{filename}` — из FUTURE/ или roadmap плана -- `adr:{NNN}` — из Architecture Decision Record -- `user:direct` — напрямую от пользователя -- `agent:analysis` — выявлено агентом при анализе -- `decomposition` — создано при декомпозиции без внешнего источника - -### 3.5. Типы задач (нумерация сдвинута) - -| Тип | Описание | -|---|---| -| `config` | Настройка окружения, зависимостей, CI, инициализация проекта | -| `design` | Архитектурное/дизайнерское решение без кода | -| `feature` | Новая функциональность | -| `refactor` | Изменение структуры без изменения поведения | -| `test` | Добавление/исправление тестов | -| `fix` | Исправление бага | -| `docs` | Документация | -| `invariant` | Тест, проверяющий архитектурный инвариант (см. 3.7) | - -### 3.6. Зелёная декомпозиция (для greenfield/scaffold) - -Если есть `.agent/context/design-report.md` — задачи формируются на основе группировки из дизайна: - -1. **T1: init** — инициализация проекта, зависимости, конфиги, scaffold -2. **T2..Tn: features** — модули/функциональность по одному -3. **Tn+1: tests** — тесты на каждый модуль (можно в составе feature-задачи) -4. **Tn+2: polish** — документация, форматирование, финальная проверка - -### 3.7. Сортировка - -Задачи в манифесте располагаются в порядке выполнения: -1. Сначала задачи без зависимостей -2. Потом те, чьи зависимости уже выполнены -3. Последними — задачи с наибольшим числом зависимостей - -### 3.8. Executable Invariants (если config.invariant_tests = yes) - -Для каждого ADR (из `.agent/decisions/`) создать задачу типа `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/tasks/manifest.json` — по шаблону `TEMPLATES/task-manifest.json` -- `.agent/tasks/manifest.md` — по шаблону `TEMPLATES/task-manifest.md` - -Обновить checkpoints.json: -- `phases.decomposition = "completed"` -- `tasks` = полный массив задач со статусом `pending` - -> **Примечание:** после HANDOFF завершённые задачи будут архивированы — -> полное описание уходит в `.agent/archive/tasks/`, в manifest.json остаётся -> one-liner с `"status": "archived"`. - -## Критерии завершения фазы - -- [ ] Цель разбита на атомарные задачи -- [ ] Для каждой задачи указаны acceptance criteria -- [ ] Для каждой задачи указан origin (источник) -- [ ] Для каждой задачи указаны affected files -- [ ] Зависимости между задачами корректны (нет циклов) -- [ ] Задачи сверены с roadmap приоритетами (если sources.md существует) -- [ ] Invariant-задачи созданы для каждого ADR (если config требует) -- [ ] `.agent/tasks/manifest.json` и `.agent/tasks/manifest.md` созданы -- [ ] checkpoints.json обновлён diff --git a/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md b/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md deleted file mode 100644 index 96d93cd..0000000 --- a/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md +++ /dev/null @@ -1,130 +0,0 @@ -# DEPRECATED — Протокол 04: Настройка окружения (SETUP) - -> **Устарел в MetaAgent v2.1.** Заменён на `PROTOCOLS/04_EXECUTION.md`. -> Оставлен для обратной совместимости (проекты, использующие v2.0). -> Новые проекты используют фазу EXECUTION, в которой настройка окружения — первый шаг перед выполнением задач. - -## Цель - -Обеспечить рабочее окружение, в котором исполнительный агент может сразу выполнять задачи. - -## Вход - -- `.agent/context/analysis-report.md` -- `.agent/context/design-report.md` (опционально, для greenfield) -- `.agent/tasks/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/context/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/context/baseline-test-report.log`: "0 tests — greenfield, scaffold готов" - -### 4B.5. Проверка сборки - -- Убедиться, что проект импортируется без ошибок -- Убедиться, что линтер проходит (без кода он должен проходить) -- Убедиться, что тестовый раннер запускается (0 tests, exit code 0) - ---- - -## Выход - -- Работоспособное окружение / инициализированный проект -- `.agent/context/baseline-test-report.log` — результат прогона тестов -- `.agent/context/setup-report.log` — лог установки зависимостей и сборки - -Обновить checkpoints.json: `phases.environment = "completed"`. - -## Критерии завершения фазы - -- [ ] Зависимости установлены / проект инициализирован -- [ ] Проект собирается / импортируется без ошибок -- [ ] Baseline-тесты запущены, результат записан -- [ ] `.agent/context/baseline-test-report.log` и `.agent/context/setup-report.log` созданы -- [ ] checkpoints.json обновлён - -Если проект не собирается — **фаза считается проваленной**, checkpoints.json отмечает `phases.environment = "failed"`, управление возвращается пользователю. diff --git a/.agent/src/PROTOCOLS/04_EXECUTION.md b/.agent/src/PROTOCOLS/04_EXECUTION.md deleted file mode 100644 index 3bdb19b..0000000 --- a/.agent/src/PROTOCOLS/04_EXECUTION.md +++ /dev/null @@ -1,138 +0,0 @@ -# Протокол 04: Исполнение задач (EXECUTION) - -## Цель - -Выполнить задачи из manifest.json: реализовать код, написать тесты, закоммитить, создать request — артефакт результата. - -## Вход - -- `.agent/tasks/manifest.json` — манифест с задачами -- `.agent/context/analysis-report.md` — контекст проекта -- `.agent/context/design-report.md` — архитектурный план (опционально) -- `.agent/decisions/*.md` — ADR (опционально) -- `.agent/rules/project-rules.md` — правила проекта -- `.agent/checkpoints.json` (фаза execution: pending) - -## Шаги - -### 4.0. Setup окружения (первый запуск) - -Если это первый запуск EXECUTION в сессии: -- Установить зависимости (через штатный пакетный менеджер) -- Запустить сборку/базовые тесты для верификации окружения -- Записать baseline в `.agent/context/baseline-test-report.log` - -### 4.1. Выбор задачи - -Найти в `.agent/tasks/manifest.json` задачу, удовлетворяющую всем условиям: -- `status: "pending"` -- Все `depends_on` имеют статус `completed` или `archived` - -Если таких задач нет — EXECUTION завершён, перейти к ожиданию команды пользователя. - -### 4.2. Блокировка задачи - -Отметить задачу в манифесте: -```json -{ - "id": "T1", - "status": "in_progress" -} -``` - -### 4.3. Исполнение - -Реализовать задачу в соответствии с acceptance criteria: -- Следовать конвенциям проекта (выявленным в ANALYSIS) -- Соблюдать BOUNDARIES.md -- Если задача ссылается на ADR — следовать архитектурному решению -- Писать код + тесты - -### 4.4. Верификация - -- Запустить тесты (все или релевантные) -- Проверить LSP diagnostics на изменённых файлах -- Убедиться, что acceptance criteria выполнены - -### 4.5. Коммит - -Сделать git-коммит с результатами задачи. Сообщение коммита должно отражать суть выполненной задачи. - -### 4.6. Создание request - -Создать `.agent/requests/active/req-{task_id}.json`: - -```json -{ - "request_id": "req-T1", - "task_id": "T1", - "title": "GET /health endpoint", - "status": "ready_for_review", - "goal": "Добавить ручку GET /health с тестами", - "changes": { - "summary": "Создан health router, подключён в main.py, написаны тесты", - "commits": ["abc1234", "abc1235"], - "files_changed": [ - "app/routers/health.py", - "app/main.py", - "tests/test_health.py" - ] - }, - "verification": { - "tests_passed": "24/24", - "lsp_clean": true - }, - "fulfills_ac": [ - "Ручка возвращает 200 + {\"status\":\"ok\"}" - ] -} -``` - -Request фиксирует: -- **changes.summary** — краткая суть изменений (не полный diff, а именно суть) -- **changes.commits** — ссылки на коммиты (чтобы можно было проанализировать при ревью) -- **changes.files_changed** — какие файлы затронуты -- **verification** — результаты проверки -- **fulfills_ac** — какие acceptance criteria закрыты - -### 4.7. Завершение задачи - -В манифесте: -```json -{ - "id": "T1", - "status": "completed" -} -``` - -### 4.8. Цикл - -Перейти к шагу 4.1 — выбрать следующую задачу. -Если задач больше нет — сообщить пользователю и ожидать команду (METASTATE или новую задачу). - -## Request как единица результата - -Request — ключевой артефакт v2.1. Не просто «задача сделана», а документированный результат: -- Что сделано (суть, не diff) -- Как проверить (коммиты, тесты) -- Что закрыто (acceptance criteria) - -Request проходит ревью в фазе METASTATE: -- `ready_for_review` → после проверки → `approved` или `rejected` - -## Выход - -- Выполненные задачи в manifest.json (status: completed) -- `.agent/requests/active/req-{task_id}.json` для каждой выполненной задачи -- Обновлённый checkpoints.json (`phases.execution = "in_progress"` или `"completed"`) - -## Критерии завершения - -Фаза EXECUTION не имеет единого момента завершения — она циклична. Критерии для одной итерации: - -- [ ] Acceptance criteria задачи выполнены -- [ ] Тесты проходят -- [ ] LSP diagnostics чист -- [ ] Коммит создан -- [ ] Request создан в `.agent/requests/active/` -- [ ] Задача в manifest.json отмечена completed diff --git a/.agent/src/PROTOCOLS/05_HANDOFF.md b/.agent/src/PROTOCOLS/05_HANDOFF.md deleted file mode 100644 index e8bf33b..0000000 --- a/.agent/src/PROTOCOLS/05_HANDOFF.md +++ /dev/null @@ -1,123 +0,0 @@ -# Протокол 07: Завершение сессии (HANDOFF) - -## Цель - -Легковесное завершение сессии: валидация структуры `.agent/`, финализация чекпоинтов, формирование сводки. Архивация и обновление project-state выполняются фазой METASTATE. - -> **Важно:** если перед HANDOFF была выполнена фаза METASTATE (06) — архивация, project-state и handoff-summary уже готовы. -> HANDOFF в этом случае только валидирует и финализирует. - -## Вход - -- `.agent/checkpoints.json` (все предыдущие фазы: completed) -- `.agent/context/project-state.md` (опционально, создан в ANALYSIS, обновлён в METASTATE) -- `.agent/handoff-summary.md` (опционально, создан в METASTATE) -- `.agent/tasks/manifest.json` -- `.agent/roadmap/sources.md` (опционально) -- Все артефакты `.agent/` - -## Шаги - -### 5.1. Проверка: была ли METASTATE? - -Если существует `.agent/handoff-summary.md` и `.agent/context/project-state.md`: -- METASTATE уже выполнен -- Перейти к шагу 5.3 (Валидация) - -Если нет: -- METASTATE не выполнялся (например, сессия завершается до execution) -- Перейти к шагу 5.2 (Лёгкая архивация) - -### 5.2. Лёгкая архивация (если METASTATE не было) - -Если есть completed задачи в manifest.json: -- Архивировать их в `.agent/archive/tasks/{id}.json` -- Заменить в manifest.json на one-liner -- Создать `.agent/archive/index.json` - -Если нет completed задач — пропустить. - -### 5.3. Валидация - -Проверить: - -- [ ] Все фазы отмечены как `completed` или `skipped` в checkpoints.json -- [ ] `.agent/` содержит обязательные файлы: - - `checkpoints.json` - - `context/analysis-report.md` - - `context/project-state.md` - - `tasks/manifest.json` + `tasks/manifest.md` - - `src/META_AGENT_GUIDE.md` - - `src/BOUNDARIES.md` - - `src/VERSION` - - `src/PROTOCOLS/` - - `src/TEMPLATES/` - - `rules/project-rules.md` -- [ ] В `.agent/tasks/manifest.json` нет циклических зависимостей -- [ ] Все acceptance criteria сформулированы измеримо -- [ ] Для каждой задачи указаны affected files и origin -- [ ] `.agent/src/` содержит актуальные исходники -- [ ] `AGENTS.md` присутствует в корне репозитория - -### 5.4. Создание session-summary.md - -Создать `.agent/session-summary.md` — краткая сводка сессии: - -```markdown -# Session Summary - -**Session:** -**MetaAgent version:** 2.1.0 -**Date:** -**Goal:** - -## Phases Executed -- [x] INIT -- [x] ANALYSIS -- [x] ROADMAP -- [x] DESIGN -- [x] DECOMPOSITION -- [x] EXECUTION (N tasks) -- [x] METASTATE -- [x] HANDOFF - -## Results -- Tasks completed: N -- Requests approved: N -- Files changed: [list] - -## Next -Следующий агент: читай .agent/handoff-summary.md -``` - -### 5.5. Финализация checkpoints - -- Отметить `phases.handoff = "completed"` -- Записать финальный `last_updated` - -### 5.6. Сигнал - -``` -HANDOFF COMPLETE - -Session: -Target: -Type: -Tasks: total, completed, pending - -Следующий агент начинает с .agent/handoff-summary.md -``` - -## Выход - -- `.agent/session-summary.md` -- `.agent/checkpoints.json` (финальный) -- Если METASTATE не было: `.agent/archive/index.json` - -## Критерии завершения - -- [ ] Все артефакты на месте (согласно структуре .agent/) -- [ ] Если METASTATE не было — completed задачи архивированы -- [ ] session-summary.md создан -- [ ] checkpoints.json финализирован -- [ ] Сигнал отправлен пользователю diff --git a/.agent/src/PROTOCOLS/06_METASTATE.md b/.agent/src/PROTOCOLS/06_METASTATE.md index fca75da..dca2fcd 100644 --- a/.agent/src/PROTOCOLS/06_METASTATE.md +++ b/.agent/src/PROTOCOLS/06_METASTATE.md @@ -2,91 +2,98 @@ ## Цель -По команде пользователя «обнови метасостояние проекта» — провести ревью накопленных requests, синхронизировать манифест, обновить слепок проекта и подготовить `.agent/` как полную картину для следующей сессии. +По команде пользователя провести ревью накопленных requests, синхронизировать манифест, обновить слепок проекта и подготовить `.agent/` как полную картину для следующей сессии. + +## Когда запускать + +По команде пользователя: + +- «обнови метасостояние» +- «update metastate» +- «подведи итог» +- «заверши сессию» + +Может запускаться многократно — после каждой группы выполненных задач. ## Вход - `.agent/requests/active/` — все request-ы со статусом `ready_for_review` -- `.agent/tasks/manifest.json` — текущее состояние задач -- `.agent/context/project-state.md` — текущий слепок проекта (создан в ANALYSIS) -- `.agent/roadmap/sources.md` — дорожная карта (создана в ROADMAP) +- `.agent/tasks/manifest.json` +- `.agent/context/project-state.md` (создан в ANALYSE, обновляется здесь) +- `.agent/roadmap/sources.md` +- `.agent/decisions/index.json` - `.agent/checkpoints.json` ## Шаги -### 6.1. Сбор requests +### 6.1. Собрать requests Прочитать все файлы из `.agent/requests/active/` со статусом `ready_for_review`. -Каждый request — это выполненная задача, ожидающая подтверждения. ### 6.2. Ревью каждого request -Для каждого request: - -1. **Верифицировать** — проверить, что verification корректен: - - Тесты действительно проходят (перезапустить, если нужно) - - LSP diagnostics чист - - Acceptance criteria выполнены - - При необходимости — проверить коммиты (git show) +Для каждого: +1. **Верифицировать** — тесты проходят, LSP чист, AC выполнены, коммиты на месте. 2. **Принять или отклонить:** - - ✅ **approved** — всё ОК: - - Переместить request: `.agent/requests/active/` → `.agent/requests/archive/` - - Убедиться, что задача в manifest.json имеет `status: "completed"` - - ❌ **rejected** — есть проблемы: - - Оставить request в active/ с комментарием о причинах отказа - - В manifest.json: `status: "reopened"`, снять `claimed_by` - - Добавить `rejection_reason` в request + + - ✅ **approved**: + - Переместить в `.agent/requests/archive/`. + - В `manifest.json` убедиться: `status: "completed"`. + + - ❌ **rejected**: + - Оставить в `active/` с комментарием. + - В `manifest.json`: `status: "reopened"`, добавить `rejection_reason`. + - В request добавить `rejection_reason`. ### 6.3. Архивация завершённых задач -Для каждой задачи в manifest.json со статусом `completed`: -1. Создать `.agent/archive/tasks/{id}.json` — полное описание задачи (все поля) -2. В manifest.json заменить на one-liner: +Для каждой `completed` задачи: + +1. Создать `.agent/archive/tasks/{id}.json` — полное описание. +2. В `manifest.json` заменить на one-liner: + ```json { "id": "T1", "title": "GET /health endpoint", "status": "archived", "origin": "user:direct" } ``` -### 6.4. Обновление project-state.md +### 6.4. Обновить project-state Переписать `.agent/context/project-state.md` с учётом выполненных задач: -- Обновить список модулей (какие добавлены/изменены) -- Обновить архитектурную схему (кратко) -- Обновить статус тестов -- Добавить новые ADR, если появились -- Убрать закрытые concerns -Цель: следующий агент читает project-state.md и понимает проект, не открывая исходники. +- Обновить список модулей (добавлены / изменены). +- Обновить архитектурную схему (кратко). +- Обновить статус тестов. +- Добавить новые ADR. +- Убрать закрытые concerns. -### 6.5. Обновление roadmap +**Цель:** следующий агент читает `project-state.md` и понимает проект, не открывая исходники. + +### 6.5. Обновить roadmap В `.agent/roadmap/sources.md`: -- Отметить выполненные пункты -- Пересчитать приоритеты -- Если появились новые источники — добавить + +- Отметить выполненные пункты. +- Пересчитать приоритеты. +- Добавить новые источники (если появились). ### 6.6. Индекс архива Создать/обновить `.agent/archive/index.json`: + ```json { - "version": "2.1.0", + "version": "3.0.0", "archived_at": "", - "tasks": [ - { "id": "T1", "title": "GET /health", "archived_at": "" } - ], - "requests": [ - { "id": "req-T1", "task_id": "T1", "archived_at": "" } - ], - "checkpoints": [ - { "file": "checkpoints/.json", "archived_at": "" } - ] + "tasks": [{ "id": "T1", "title": "...", "archived_at": "" }], + "requests": [{ "id": "req-T1", "task_id": "T1", "archived_at": "" }], + "checkpoints": [{ "file": "checkpoints/.json", "archived_at": "" }] } ``` -### 6.7. Создание handoff-summary.md +### 6.7. Создать handoff-summary -Создать `.agent/handoff-summary.md` — полную сводку для следующего агента: +Создать `.agent/handoff-summary.md` — полная сводка для следующего агента: ```markdown ## Session Summary @@ -110,40 +117,29 @@ - Archive: `.agent/archive/index.json` ``` -### 6.8. Финализация чекпоинта +### 6.8. Обновить checkpoints -Обновить checkpoints.json: -- `phases.metastate = "completed"` -- Актуальный список задач -- `last_updated` +```json +{ "phases": { "metastate": "completed" }, "last_updated": "" } +``` ## Выход -- Подтверждённые requests: `.agent/requests/archive/` -- Архив задач: `.agent/archive/tasks/{id}.json` -- Обновлённый project-state.md -- Обновлённый roadmap/sources.md -- `.agent/handoff-summary.md` — полная сводка +- `.agent/requests/archive/` — подтверждённые request-ы +- `.agent/archive/tasks/{id}.json` — архив задач +- Обновлённый `.agent/context/project-state.md` +- Обновлённый `.agent/roadmap/sources.md` +- `.agent/handoff-summary.md` - `.agent/archive/index.json` -- Финальный checkpoints.json +- Финальный `checkpoints.json` ## Критерии завершения -- [ ] Все ready_for_review requests проверены (approved/rejected) -- [ ] Approved requests перемещены в archive +- [ ] Все `ready_for_review` requests проверены (approved / rejected) +- [ ] Approved перемещены в archive - [ ] Completed задачи архивированы (one-liner в manifest) -- [ ] project-state.md отражает актуальное состояние проекта -- [ ] roadmap/sources.md обновлён -- [ ] archive/index.json создан -- [ ] handoff-summary.md готов -- [ ] checkpoints.json финализирован - -## Когда запускать - -По команде пользователя: -- «обнови метасостояние» -- «update metastate» -- «подведи итог» -- «заверши сессию» - -Может запускаться многократно в течение жизни проекта — после каждой группы выполненных задач. +- [ ] `project-state.md` отражает актуальное состояние +- [ ] `roadmap/sources.md` обновлён +- [ ] `archive/index.json` создан +- [ ] `handoff-summary.md` готов +- [ ] `checkpoints.json` финализирован diff --git a/.agent/src/TEMPLATES/analysis-report.md b/.agent/src/TEMPLATES/analysis-report.md index dc803a1..8bc4080 100644 --- a/.agent/src/TEMPLATES/analysis-report.md +++ b/.agent/src/TEMPLATES/analysis-report.md @@ -15,8 +15,7 @@ - **Точка входа:** {{ entry_point }} - **Система сборки:** {{ build_system }} -{% if project_type == "existing" or project_type == "scaffold" %} -## 2. Стек технологий +## 2. Стек технологий (existing / scaffold) | Компонент | Значение | |---|---| @@ -27,7 +26,7 @@ | Пакетный менеджер | {{ package_manager }} | | Линтер/форматтер | {{ linter }} | -## 3. Архитектура +## 3. Архитектура (existing / scaffold) ``` {{ directory_tree }} @@ -41,7 +40,7 @@ |---|---| | {{ module }} | {{ description }} | -## 4. Конвенции +## 4. Конвенции (existing / scaffold) - **Стиль:** {{ code_style }} - **Импорты:** {{ import_style }} @@ -49,52 +48,38 @@ - **Обработка ошибок:** {{ error_handling }} - **Логирование:** {{ logging }} -## 5. Тесты +## 5. Тесты (existing / scaffold) - **Команда запуска:** `{{ test_command }}` - **Всего тестов:** {{ total_tests }} - **Пройдено:** {{ passed }} - **Упало:** {{ failed }} - **Пропущено:** {{ skipped }} -- **Упавшие тесты:** - {% for test in failed_tests %} - - `{{ test }}` - {% endfor %} +- **Упавшие тесты:** {{ failed_tests_list }} -## 6. Базовая проверка +## 6. Базовая проверка (existing / scaffold) - **Сборка:** {{ build_status }} - **Запуск:** {{ run_status }} - **Git status:** {{ git_status }} -{% endif %} -{% if project_type == "greenfield" or project_type == "scaffold" %} -## 7. Требования (из README) +## 7. Требования (greenfield / scaffold) ### Функциональные требования -{% for req in functional_requirements %} -- {{ req }} -{% endfor %} +{{ functional_requirements_list }} ### Нефункциональные требования -{% for req in non_functional_requirements %} -- {{ req }} -{% endfor %} +{{ non_functional_requirements_list }} ### Бизнес-контекст -{% for item in business_context %} -- {{ item }} -{% endfor %} +{{ business_context_list }} ### Неясные моменты / Вопросы -{% for question in open_questions %} -- {{ question }} -{% endfor %} -{% endif %} +{{ open_questions_list }} ## 8. Примечания diff --git a/.agent/src/TEMPLATES/design-report.md b/.agent/src/TEMPLATES/design-report.md index 4faf4f8..93782be 100644 --- a/.agent/src/TEMPLATES/design-report.md +++ b/.agent/src/TEMPLATES/design-report.md @@ -38,36 +38,11 @@ ### Сущности -{% for entity in entities %} -### {{ entity.name }} - -| Поле | Тип | Ограничения | Описание | -|---|---|---|---| -{% for field in entity.fields %} -| {{ field.name }} | {{ field.type }} | {{ field.constraints }} | {{ field.description }} | -{% endfor %} - -**Связи:** {{ entity.relationships }} - -{% endfor %} +{{ entity_descriptions }} ## 5. API / Интерфейсы -{% if has_api %} -| Метод | Путь | Описание | Request | Response | -|---|---|---|---|---| -{% for endpoint in api_endpoints %} -| {{ endpoint.method }} | {{ endpoint.path }} | {{ endpoint.description }} | {{ endpoint.request }} | {{ endpoint.response }} | -{% endfor %} -{% endif %} - -{% if has_gui %} -**Экраны:** {{ gui_screens }} -{% endif %} - -{% if has_cli %} -**Команды:** {{ cli_commands }} -{% endif %} +{{ api_endpoints_table }} ## 6. Обработка ошибок @@ -82,31 +57,16 @@ - **Mock-стратегия:** {{ mock_strategy }} - **Команда запуска:** `{{ test_command }}` -## 8. Alternative Architecture (если применимо) +## 8. Дополнительные артефакты (по команде пользователя) -| Критерий | Выбранная архитектура | Альтернатива | -|---|---|---| -| Название | {{ chosen_arch }} | {{ alt_arch }} | -| Сложность | {{ chosen_complexity }} | {{ alt_complexity }} | -| Почему не выбрана | — | {{ alt_rejection_reason }} | +Если пользователь вызвал соответствующие команды, добавить ссылки: -## 9. ADR Reference (если применимо) +- ADR: `.agent/decisions/` (команда `/adr`) +- Alternative Architecture: `.agent/context/alt-architecture.md` (команда `/alt-arch`) +- Risk Register: `.agent/context/risk-register.md` (команда `/risk-register`) +- Red Team Review: `.agent/context/red-team-report.md` (команда `/red-team`) -| ID | Решение | Файл | -|---|---|---| -{% for adr in adr_list %} -| {{ adr.id }} | {{ adr.title }} | `{{ adr.path }}` | -{% endfor %} - -## 10. Risk Register (если применимо) - -| # | Assumption | Impact | Mitigation | -|---|---|---|---| -{% for risk in risk_list %} -| {{ risk.id }} | {{ risk.assumption }} | {{ risk.impact }} | {{ risk.mitigation }} | -{% endfor %} - -## 11. Предварительная группировка задач +## 9. Предварительная группировка задач | Задача | Описание | Тип | |---|---|---| @@ -115,6 +75,6 @@ | T3 | {{ task_3 }} | feature | | T4 | {{ task_4 }} | test | -## 12. Примечания +## 10. Примечания {{ notes }} diff --git a/.agent/src/TEMPLATES/handoff-summary.md b/.agent/src/TEMPLATES/handoff-summary.md index 165eeee..3e1f851 100644 --- a/.agent/src/TEMPLATES/handoff-summary.md +++ b/.agent/src/TEMPLATES/handoff-summary.md @@ -3,37 +3,24 @@ ## Session Info - **Session ID:** `{{ session_id }}` -- **Target Repo:** `{{ target_repo }}` +- **Target Repo:** {{ target_repo }} - **Goal:** {{ goal }} - **Date:** {{ date }} -- **Duration:** {{ duration }} -- **Depth:** {{ depth }} -- **Config:** {{ config_summary }} +- **Project type:** {{ project_type }} ## Repo Summary {{ repo_summary }} -## Project Type +## Artifacts Created -- **Type:** {{ project_type }} -- **Design report:** {% if project_type == "greenfield" or project_type == "scaffold" %}`.agent/context/design-report.md`{% else %}—{% endif %} - -## ADR Summary (если применимо) - -{% if adr_count > 0 %} -Создано ADR: {{ adr_count }} -{% for adr in adr_list %} -- `{{ adr.path }}` — {{ adr.title }} -{% endfor %} -{% endif %} - -## Risk Register (если применимо) - -{% if risk_count > 0 %} -Задокументировано допущений: {{ risk_count }} -Наиболее критичное: {{ top_risk }} -{% endif %} +- **Analysis report:** `.agent/context/analysis-report.md` +- **Project state:** `.agent/context/project-state.md` +- **Design report:** {{ design_report_path_or_dash }} +- **Roadmap:** `.agent/roadmap/sources.md` +- **ADR:** {{ adr_summary_or_dash }} +- **Risk Register:** {{ risk_register_path_or_dash }} +- **Red Team Report:** {{ red_team_report_path_or_dash }} ## Environment Status @@ -50,35 +37,21 @@ | Pending | {{ pending }} | | In Progress | {{ in_progress }} | | Completed | {{ completed }} | +| Archived | {{ archived }} | | Failed/Skipped | {{ failed }} | -**Task by type:** -{% for type, count in tasks_by_type %} -- {{ type }}: {{ count }} -{% endfor %} - ## Tasks (ordered) -{% for task in tasks %} -### {{ task.id }}: {{ task.title }} -- Type: {{ task.type }} -- Depends on: {{ task.depends_on | default("—") }} -- Files: {{ task.files | join(", ") }} -- Status: {{ task.status }} - -{% endfor %} +{{ task_list_markdown }} ## Next Steps -Исполнительный агент начинает с задачи **{{ first_task }}**. +Следующий агент: прочитай `.agent/context/project-state.md`, затем `.agent/tasks/manifest.json` и приступай к первой `pending` задаче. ## Caveats -{% for caveat in caveats %} -- {{ caveat }} -{% endfor %} +{{ caveats_list }} ## Checkpoints -Файл: `.agent/checkpoints.json` -Актуальное состояние чекпоинтов прилагается. +Файл: `.agent/checkpoints.json` — состояние фаз и список задач. diff --git a/.agent/src/TEMPLATES/metaagent-request.md b/.agent/src/TEMPLATES/metaagent-request.md deleted file mode 100644 index e953f7a..0000000 --- a/.agent/src/TEMPLATES/metaagent-request.md +++ /dev/null @@ -1,38 +0,0 @@ -# MetaAgent Request -# Для ручного заполнения перед запуском MetaAgent. -# Поместите этот файл в .agent/metaagent-request.md целевого репозитория. -# Если файл отсутствует — MetaAgent проведёт интервью (PROTOCOLS/00_CONFIG.md). -# Ответьте "default" на любой вопрос — будет использовано значение по умолчанию. - -## Параметры сессии - -| Функция | Вкл | Аргументы | -|---|---|---| -| ANALYSIS | ✓ | — | -| DESIGN | ✓ | adr=yes, alternative_arch=yes | -| RED_TEAM | ✗ | — | -| RISK_REGISTER | ✗ | — | -| DECOMPOSITION | ✓ | invariant_tests=yes | -| SETUP | ✓ | — | -| HANDOFF | ✓ | — | - -## Глубина проработки - -**Значение:** 6 (1-10) - -| Уровень | Название | Описание | -|---|---|---| -| 1-2 | Scaffold | Только структура проекта + пустые модули | -| 3-4 | Light | (default) Быстрый дизайн + задачи без расширений | -| 5-6 | Standard | Полный ANALYSIS→DESIGN→DECOMP→SETUP→HANDOFF | -| 7-8 | Deep | Standard + ADR, Risk Register, Alternative Architecture | -| 9-10 | Maximum | Deep + Red Team Review, Executable Invariants | - -## Цель - -Сформулируйте задачу для MetaAgent. - -## Дополнительно - -- **Boundaries:** (опционально) ограничения, которые нельзя нарушать -- **Target:** путь к репозиторию или URL diff --git a/.agent/src/TEMPLATES/schemas/checkpoints-schema.json b/.agent/src/TEMPLATES/schemas/checkpoints-schema.json index ec5473c..bb0f7a0 100644 --- a/.agent/src/TEMPLATES/schemas/checkpoints-schema.json +++ b/.agent/src/TEMPLATES/schemas/checkpoints-schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "metaagent/checkpoints/2.0.0", + "$id": "metaagent/checkpoints/3.0.0", "title": "MetaAgent Checkpoints", "description": "Schema for .agent/checkpoints.json — session state", "type": "object", @@ -19,52 +19,25 @@ "description": "Path to the target repository" }, "goal": { - "type": "string", - "description": "Session goal" + "type": ["string", "null"], + "description": "Session goal (set by user, may be null until first task)" }, "project_type": { - "type": "string", - "enum": ["pending", "existing", "greenfield", "scaffold"], - "description": "Type of the target project" - }, - "config": { - "type": "object", - "properties": { - "depth": { - "type": "integer", - "minimum": 1, - "maximum": 10, - "description": "Depth of the session (1-10)" - }, - "design": { - "type": "object", - "properties": { - "adr": { "type": "boolean" }, - "alternative_arch": { "type": "boolean" } - }, - "additionalProperties": false - }, - "red_team": { "type": "boolean" }, - "risk_register": { "type": "boolean" }, - "decomposition": { - "type": "object", - "properties": { - "invariant_tests": { "type": "boolean" } - }, - "additionalProperties": false - } - }, - "additionalProperties": false + "type": ["string", "null"], + "enum": [null, "existing", "greenfield", "scaffold"], + "description": "Type of the target project (set in ANALYSE phase)" }, "phases": { "type": "object", "properties": { - "analysis": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, - "design": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, - "red_team": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "init": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "analyse": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "roadmap": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "design": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, "decomposition": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, - "environment": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, - "handoff": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] } + "execution": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "metastate": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "handoff": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] } }, "additionalProperties": false }, @@ -74,8 +47,8 @@ "items": { "type": "object", "properties": { - "id": { "type": "string" }, - "title": { "type": "string" }, + "id": { "type": "string" }, + "title": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "archived"] } }, "required": ["id", "title", "status"], @@ -88,6 +61,6 @@ "description": "ISO 8601 timestamp of last update" } }, - "required": ["metaagent_version", "session_id", "goal", "config", "phases", "last_updated"], + "required": ["metaagent_version", "session_id", "phases", "last_updated"], "additionalProperties": false } diff --git a/.agent/src/TEMPLATES/schemas/decisions-index-schema.json b/.agent/src/TEMPLATES/schemas/decisions-index-schema.json index 8b3ca3e..99efa4c 100644 --- a/.agent/src/TEMPLATES/schemas/decisions-index-schema.json +++ b/.agent/src/TEMPLATES/schemas/decisions-index-schema.json @@ -1,14 +1,14 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "metaagent/decisions-index/2.0.0", + "$id": "metaagent/decisions-index/3.0.0", "title": "MetaAgent Decisions Index", "description": "Schema for .agent/decisions/index.json — machine-readable index of ADRs", "type": "object", "properties": { "version": { "type": "string", - "description": "Schema version", - "enum": ["2.0"] + "description": "Schema version (3.0 in v3.0+, 2.0 still valid from v2.1)", + "enum": ["2.0", "3.0"] }, "decisions": { "type": "array", diff --git a/.agent/src/TEMPLATES/schemas/task-manifest-schema.json b/.agent/src/TEMPLATES/schemas/task-manifest-schema.json index b934b0f..9cdb97d 100644 --- a/.agent/src/TEMPLATES/schemas/task-manifest-schema.json +++ b/.agent/src/TEMPLATES/schemas/task-manifest-schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "metaagent/task-manifest/2.0.0", + "$id": "metaagent/task-manifest/3.0.0", "title": "MetaAgent Task Manifest", "description": "Schema for .agent/tasks/manifest.json — the global task manifest", "type": "object", @@ -8,7 +8,7 @@ "version": { "type": "string", "description": "Schema version", - "enum": ["2.0"] + "enum": ["3.0"] }, "session_id": { "type": "string", @@ -31,8 +31,8 @@ "properties": { "id": { "type": "string", - "pattern": "^T[0-9]+$", - "description": "Unique task identifier (T1, T2, ...)" + "pattern": "^(T[0-9]+|T-INV-[0-9]+)$", + "description": "Unique task identifier (T1, T2, ... or T-INV-N for invariants)" }, "title": { "type": "string", @@ -47,6 +47,10 @@ "enum": ["feature", "refactor", "test", "fix", "config", "design", "docs", "invariant"], "description": "Task type" }, + "origin": { + "type": "string", + "description": "Task source (roadmap:file, adr:NNN, user:direct, agent:analysis, decomposition, invariant:NNN, risk:R-NNN)" + }, "files": { "type": "array", "items": { "type": "string" }, diff --git a/.agent/src/TEMPLATES/session-summary.md b/.agent/src/TEMPLATES/session-summary.md index f12f894..e56242f 100644 --- a/.agent/src/TEMPLATES/session-summary.md +++ b/.agent/src/TEMPLATES/session-summary.md @@ -2,33 +2,49 @@ **Session:** {{ session_id }} **Target:** {{ target_repo }} -**Depth:** {{ depth }} +**MetaAgent version:** {{ version }} **Date:** {{ date }} -## Configuration - -| Функция | Статус | -|---|---| -| ADR | {{ adr_enabled }} | -| Alternative Architecture | {{ alt_arch_enabled }} | -| Red Team | {{ red_team_enabled }} | -| Risk Register | {{ risk_register_enabled }} | -| Invariant Tests | {{ invariant_tests_enabled }} | - ## Phase Status | Phase | Status | |---|---| -| ANALYSIS | {{ analysis_status }} | +| INIT | {{ init_status }} | +| ANALYSE | {{ analyse_status }} | +| ROADMAP | {{ roadmap_status }} | | DESIGN | {{ design_status }} | -| RED_TEAM | {{ red_team_status }} | | DECOMPOSITION | {{ decomposition_status }} | -| SETUP | {{ setup_status }} | +| EXECUTION | {{ execution_status }} | +| METASTATE | {{ metastate_status }} | | HANDOFF | {{ handoff_status }} | +## Tasks + +| Status | Count | +|---|---| +| Total | {{ total }} | +| Pending | {{ pending }} | +| In Progress | {{ in_progress }} | +| Completed | {{ completed }} | +| Archived | {{ archived }} | +| Failed/Skipped | {{ failed }} | + +**By origin:** +- user:direct: {{ user_direct_count }} +- roadmap: {{ roadmap_count }} +- adr: {{ adr_count }} +- decomposition: {{ decomposition_count }} +- (другое): {{ other_count }} + +## Commands Invoked (если были) + +{{ commands_invoked_list }} + ## Quick Links - Task Manifest: `.agent/tasks/manifest.json` - Handoff Summary: `.agent/handoff-summary.md` -- Design Report: `.agent/context/design-report.md` -- ADR: `.agent/decisions/` (если есть) +- Project State: `.agent/context/project-state.md` +- ADR: `.agent/decisions/` +- Risk Register: `.agent/context/risk-register.md` +- Red Team Report: `.agent/context/red-team-report.md` diff --git a/.agent/src/TEMPLATES/task-manifest.json b/.agent/src/TEMPLATES/task-manifest.json index 9b0debf..579ffbe 100644 --- a/.agent/src/TEMPLATES/task-manifest.json +++ b/.agent/src/TEMPLATES/task-manifest.json @@ -1,6 +1,6 @@ { "$schema": ".agent/src/TEMPLATES/schemas/task-manifest-schema.json", - "version": "1.0", + "version": "3.0", "session_id": "{{ session_id }}", "goal": "{{ goal }}", "created_at": "{{ timestamp }}", @@ -9,7 +9,8 @@ "id": "T1", "title": "{{ task_title }}", "description": "{{ task_description }}", - "type": "feature|refactor|test|fix|config|docs", + "type": "feature|refactor|test|fix|config|design|docs|invariant", + "origin": "user:direct", "files": ["path/to/file1.py", "path/to/file2.py"], "depends_on": [], "acceptance_criteria": [ diff --git a/.agent/src/VERSION b/.agent/src/VERSION index 7ec1d6d..4a36342 100644 --- a/.agent/src/VERSION +++ b/.agent/src/VERSION @@ -1 +1 @@ -2.1.0 +3.0.0 diff --git a/.agent/src/WORKFLOW.md b/.agent/src/WORKFLOW.md index 0415204..be9f87a 100644 --- a/.agent/src/WORKFLOW.md +++ b/.agent/src/WORKFLOW.md @@ -1,419 +1,88 @@ -# WORKFLOW — Сквозной пример сессии +# WORKFLOW — Сквозной пример сессии v3.0 --- -## Сценарий A: Existing проект +## Сценарий: рефакторинг auth-модуля -**Цель:** Добавить в существующий FastAPI-проект ручку GET /health с тестами. +**Цель:** Вынести логику из `auth/login.py` (450 строк, монолит) в отдельные модули `auth/router.py`, `auth/schemas.py`, `auth/deps.py`. **Целевой репозиторий:** `github.com/example/fastapi-app` -**Пользователь:** "Добавь health-check endpoint и тесты к нему" +**Пользователь:** «Вынеси авторизацию в отдельные модули». ---- - -### Фаза INIT - -Мета-агент читает `.agent/metaagent-request.md`, клонирует репозиторий, создаёт `.agent/`, пишет начальный чекпоинт: - -```json -{ - "metaagent_version": "1.1.0", - "session_id": "ses_abc123", - "target_repo": "/tmp/fastapi-app", - "goal": "Добавить GET /health с тестами", - "project_type": "existing", - "config": { - "depth": 6, - "design": { "adr": false, "alternative_arch": false }, - "red_team": false, - "risk_register": false, - "decomposition": { "invariant_tests": false } - }, - "phases": { - "analysis": "pending", - "design": "pending", - "red_team": "pending", - "decomposition": "pending", - "environment": "pending", - "handoff": "pending" - }, - "tasks": [], - "last_updated": "2026-07-12T15:00:00Z" -} -``` - ---- - -### Фаза ANALYSE - -Мета-агент выполняет `PROTOCOLS/01_ANALYSIS.md`. Определяет тип проекта: `existing`. - -Результат `.agent/context/analysis-report.md`: - -```markdown -## 2. Стек технологий -| Язык | Python 3.12 | -| Фреймворк | FastAPI | -| Тестовый раннер | pytest + httpx | -| Пакетный менеджер | pip + requirements.txt | - -## 3. Архитектура -├── app/ -│ ├── main.py -│ ├── routers/ -│ │ └── users.py -│ ├── models/ -│ │ └── user.py -│ └── schemas/ -│ └── user.py -├── tests/ -│ └── test_users.py -``` - -Тесты запущены: **12 passed, 0 failed**. - -Чекпоинт обновлён: `analysis = "completed"`, `project_type = "existing"`. -Фаза DESIGN пропускается. - ---- - -### Фаза DECOMPOSITION - -Мета-агент выполняет `PROTOCOLS/03_DECOMPOSITION.md`. - -Декомпозиция цели "Добавить GET /health с тестами": - -| ID | Задача | Тип | Зависит от | AC | -|---|---|---|---|---| -| T1 | Создать health-check router | feature | — | Ручка возвращает 200 + {"status":"ok"} | -| T2 | Подключить router в main.py | config | T1 | Ручка доступна по /health | -| T3 | Написать тесты для /health | test | T2 | Тесты проверяют 200 и структуру ответа | - -Создан `.agent/tasks/manifest.json` и `.agent/tasks/manifest.md`. - -Чекпоинт обновлён: `decomposition = "completed"`. Tasks: T1-T3 со статусом `pending`. - ---- - -### Фаза SETUP - -Мета-агент выполняет `PROTOCOLS/04_ENVIRONMENT_SETUP.md` (ветка A: existing). - -- `pip install -r requirements.txt` — OK -- Запуск pytest — OK, 12 passed (базовый тест) -- Результат в `.agent/context/baseline-test-report.log` - -Чекпоинт обновлён: `environment = "completed"`. - ---- - -### Фаза HANDOFF - -Мета-агент выполняет `PROTOCOLS/05_HANDOFF.md`. - -Создан `.agent/handoff-summary.md`: - -```markdown -## Next Steps -Исполнительный агент начинает с задачи T1: "Создать health-check router". - -## Caveats -- Придерживаться стиля существующего роутера users.py -- Не менять существующие тесты -- Убедиться, что response model соответствует JSON: {"status": "ok"} -``` - -Чекпоинт финализирован: - -```json -{ - "metaagent_version": "1.1.0", - "session_id": "ses_abc123", - "goal": "Добавить GET /health с тестами", - "project_type": "existing", - "config": { - "depth": 6, - "design": { "adr": false, "alternative_arch": false }, - "red_team": false, - "risk_register": false, - "decomposition": { "invariant_tests": false } - }, - "phases": { - "analysis": "completed", - "design": "skipped", - "red_team": "skipped", - "decomposition": "completed", - "environment": "completed", - "handoff": "completed" - }, - "tasks": [ - { "id": "T1", "title": "Создать health-check router", "status": "pending" }, - { "id": "T2", "title": "Подключить router в main.py", "status": "pending" }, - { "id": "T3", "title": "Написать тесты для /health", "status": "pending" } - ], - "last_updated": "2026-07-12T15:15:00Z" -} -``` - -Сигнал пользователю: - -``` -HANDOFF COMPLETE -Session: ses_abc123 -Target: /tmp/fastapi-app -Type: existing -Tasks: 3 tasks ready - -Исполнительный агент может начинать с задачи T1. -``` - ---- - -## Сценарий B: Greenfield проект (Cashflow Forecasting) - -**Цель:** Спроектировать и реализовать MVP сервиса прогнозирования денежных потоков. - -**Целевой репозиторий:** `github.com/example/cashflow-app` - -**README:** README содержит описание: -> Сервис для прогнозирования движения денежных средств (cashflow forecasting). -> Пользователь загружает CSV с транзакциями, сервис строит прогноз на N дней вперёд. -> Стек: Python, FastAPI, SQLite, matplotlib для графиков. - ---- - -### Фаза INIT - -```json -{ - "metaagent_version": "1.1.0", - "session_id": "ses_def456", - "target_repo": "/tmp/cashflow-app", - "goal": "Спроектировать и реализовать MVP сервиса прогнозирования денежных потоков", - "project_type": "greenfield", - "config": { - "depth": 7, - "design": { "adr": true, "alternative_arch": true }, - "red_team": false, - "risk_register": true, - "decomposition": { "invariant_tests": true } - }, - "phases": { - "analysis": "pending", - "design": "pending", - "red_team": "pending", - "decomposition": "pending", - "environment": "pending", - "handoff": "pending" - }, - "tasks": [], - "last_updated": "2026-07-12T16:00:00Z" -} -``` - ---- - -### Фаза ANALYSE - -Мета-агент выполняет `PROTOCOLS/01_ANALYSIS.md`. Определяет тип проекта: `greenfield`. - -Сканирование корня: пусто (кроме README.md, LICENSE, .gitignore). - -Извлечение требований из README: - -| Тип | Требование | -|---|---| -| Функциональное | Загрузка CSV с транзакциями | -| Функциональное | Прогноз на N дней вперёд | -| Нефункциональное | Python, FastAPI | -| Нефункциональное | SQLite | -| Нефункциональное | matplotlib для графиков | - -Чекпоинт: `analysis = "completed"`, `project_type = "greenfield"`. - -Так как проект greenfield — мета-агент переходит к фазе DESIGN. - ---- - -### Фаза DESIGN - -Мета-агент выполняет `PROTOCOLS/02_DESIGN.md`. - -Результат `.agent/context/design-report.md`: - -```markdown -## 1. Технологический стек -| Язык | Python 3.12 | -| Фреймворк | FastAPI + Pydantic | -| БД | SQLite + SQLAlchemy | -| Визуализация | matplotlib | -| Тесты | pytest | - -## 2. Архитектура -[Client] → HTTP → [FastAPI] → [CashflowService] → [SQLite] - ↓ - [ForecastEngine] → [matplotlib] - -## 3. Модули -| Модуль | Ответственность | -|---|---| -| app/main.py | Точка входа, роуты | -| app/models/transaction.py | Модель транзакции | -| app/services/cashflow.py | Бизнес-логика | -| app/services/forecast.py | Алгоритм прогноза | -| app/services/upload.py | Парсинг CSV | -| app/schemas/ | Pydantic схемы | - -## 4. Модели -Transaction: id, date, amount, category, description - -## 5. API -POST /upload — загрузить CSV -GET /forecast?days=30 — прогноз + график - -## 6. Задачи (pre-grouped) -T1: init — проект, зависимости, scaffold -T2: models — модели + миграции -T3: upload — загрузка CSV -T4: forecast — алгоритм прогноза -T5: API — endpoints -T6: tests — тесты -``` - -Чекпоинт: `design = "completed"`. - ---- - -### Фаза DECOMPOSITION - -Мета-агент выполняет `PROTOCOLS/03_DECOMPOSITION.md`, используя design-report. - -Итоговые задачи: - -| ID | Задача | Тип | Зависит от | -|---|---|---|---| -| T1 | Инициализация проекта + зависимости | config | — | -| T2 | Модель Transaction + SQLAlchemy + SQLite | feature | T1 | -| T3 | Сервис загрузки и парсинга CSV | feature | T2 | -| T4 | ForecastEngine — алгоритм прогноза | feature | T2 | -| T5 | API endpoints + документация | feature | T3, T4 | -| T6 | Тесты (unit + integration) | test | T5 | - ---- - -### Фаза SETUP - -Мета-агент выполняет `PROTOCOLS/04_ENVIRONMENT_SETUP.md` (ветка B: greenfield). - -- `poetry init` + создание pyproject.toml -- Установка fastapi, uvicorn, sqlalchemy, matplotlib, pytest -- Создание scaffold-структуры: `app/models/`, `app/services/`, `app/schemas/`, `tests/` -- Пустые заглушки модулей -- `.agent/context/baseline-test-report.log`: "0 tests — greenfield, scaffold готов" - ---- - -### Фаза HANDOFF - -```markdown -HANDOFF COMPLETE -Session: ses_def456 -Target: /tmp/cashflow-app -Type: greenfield -Config: depth=7, adr=yes, risk_register=yes, invariant_tests=yes -Tasks: 6 tasks ready - -Исполнительный агент может начинать с задачи T1 (init). -Архитектурный план: .agent/context/design-report.md -ADR: .agent/decisions/ -``` - ---- - -## После HANDOFF: работа исполнительного агента - -Исполнительный агент читает `.agent/handoff-summary.md`, `.agent/tasks/manifest.json`, выполняет задачи по порядку, обновляя checkpoints.json после каждой. - -После завершения всех задач: - -``` -ALL TASKS COMPLETE -Session: ses_def456 -Tasks: 6/6 completed - -T1: Инициализация проекта ✓ -T2: Модель Transaction ✓ -T3: Сервис загрузки CSV ✓ -T4: ForecastEngine ✓ -T5: API endpoints ✓ -T6: Тесты ✓ - -Все тесты проходят: 24/24 passed. -``` - ---- - -## Сценарий C: v2.1 — Координирующий агент + requests + METASTATE - -**Цель:** Рефакторинг модуля авторизации: вынести логику из монолитного файла в отдельные модули. - -**Целевой репозиторий:** `github.com/example/fastapi-app` - -**Пользователь:** "Вынеси авторизацию в отдельные модули: auth/router.py, auth/schemas.py, auth/deps.py" - -**Версия MetaAgent: 2.1.0** +**MetaAgent:** v3.0.0 --- ### PROJECT LOOP -#### Фаза INIT +#### INIT -Агент создаёт `.agent/`, инициализирует чекпоинт: +Агент читает `AGENTS.md`, переходит в `.agent/src/GUIDE.md`. Понимает цикл. Создаёт `.agent/`, копирует исходники, инициализирует `checkpoints.json`: ```json { - "metaagent_version": "2.1.0", - "session_id": "ses_v21_001", - "goal": "Рефакторинг авторизации: вынести в модули auth/", - "project_type": "existing", + "metaagent_version": "3.0.0", + "session_id": "ses_v30_001", + "target_repo": "/tmp/fastapi-app", + "goal": "Вынести авторизацию в auth/{router,schemas,deps}.py", + "project_type": null, "phases": { - "analysis": "pending", + "init": "completed", + "analyse": "pending", "roadmap": "pending", - "design": "skipped", + "design": "pending", "decomposition": "pending", "execution": "pending", "metastate": "pending", "handoff": "pending" - } + }, + "tasks": [], + "last_updated": "2026-10-08T15:00:00Z" } ``` -#### Фаза ANALYSIS +#### ANALYSE Агент сканирует проект: -- Стек: Python, FastAPI, SQLAlchemy -- auth/login.py — 450 строк, монолит (цель рефакторинга) -- Создаёт `.agent/context/analysis-report.md` -- Создаёт `.agent/context/project-state.md` — начальный слепок -#### Фаза ROADMAP +- Стек: Python 3.12, FastAPI, SQLAlchemy, pytest. +- `auth/login.py` — 450 строк, монолит (цель рефакторинга). +- Тесты: 48 passed (baseline). -Сканирование FUTURE/ — пусто. ADR — нет. Единственный источник — пользовательский запрос. +Создаёт: + +- `.agent/context/analysis-report.md` +- `.agent/context/project-state.md` (начальный) + +`checkpoints.json`: `project_type = "existing"`, `phases.analyse = "completed"`. + +#### ROADMAP + +- `FUTURE/` — пусто. +- `.agent/decisions/` — пусто. +- Единственный источник — пользовательский запрос. + +Создаёт `.agent/roadmap/sources.md`: -Создаётся `.agent/roadmap/sources.md`: ```markdown -## Sources -### User Requests +## User Requests | Вынести авторизацию | P0 | user:direct | -### Consolidated Priority Queue + +## Consolidated Priority Queue 1. Вынести auth/ (user:direct) — P0 ``` -#### Фаза DECOMPOSITION +`phases.roadmap = "completed"`. + +#### DESIGN + +**Пропускается** (existing-проект). `phases.design = "skipped"`. + +#### DECOMPOSITION + +Задачи: -Задачи с origin: ```json { "tasks": [ @@ -421,42 +90,57 @@ T6: Тесты ✓ "id": "T1", "title": "Создать auth/router.py", "origin": "user:direct", - "status": "pending", - "files": ["app/auth/router.py"] + "files": ["app/auth/router.py"], + "depends_on": [], + "acceptance_criteria": [ + "Роуты авторизации вынесены из auth/login.py", + "auth/router.py экспортирует router", + "Существующие тесты проходят" + ], + "status": "pending" }, { "id": "T2", "title": "Создать auth/schemas.py", "origin": "user:direct", - "status": "pending", "files": ["app/auth/schemas.py"], - "depends_on": ["T1"] + "depends_on": ["T1"], + "acceptance_criteria": [ + "Pydantic схемы вынесены в auth/schemas.py", + "Существующие тесты проходят" + ], + "status": "pending" }, { "id": "T3", "title": "Создать auth/deps.py", "origin": "user:direct", - "status": "pending", "files": ["app/auth/deps.py"], - "depends_on": ["T1"] + "depends_on": ["T1"], + "acceptance_criteria": [ + "Dependency injection функции вынесены в auth/deps.py", + "Существующие тесты проходят" + ], + "status": "pending" } ] } ``` +`phases.decomposition = "completed"`. + --- ### WORK LOOP (первая итерация) -#### Фаза EXECUTION — задача T1 +#### EXECUTION — задача T1 -1. Берёт T1 (`pending`, нет зависимостей) -2. Отмечает `in_progress` -3. Создаёт `app/auth/router.py` — переносит логику роутов из `auth/login.py` -4. Пишет тесты -5. Тесты проходят: 48/48 -6. Коммит: `abc1234 — feat: extract auth router` -7. Создаёт request: +1. Берёт T1 (`pending`, нет зависимостей). +2. `status = "in_progress"`. +3. Создаёт `app/auth/router.py` — переносит роуты. +4. Тесты: 48/48. +5. Коммит: `abc1234 — refactor: extract auth router`. +6. Создаёт request: ```json { @@ -464,25 +148,26 @@ T6: Тесты ✓ "task_id": "T1", "title": "Создать auth/router.py", "status": "ready_for_review", + "goal": "Вынести роуты авторизации", "changes": { - "summary": "Вынесены роуты авторизации из auth/login.py в auth/router.py. Добавлены тесты.", + "summary": "Роуты авторизации вынесены из auth/login.py в auth/router.py", "commits": ["abc1234"], "files_changed": ["app/auth/router.py", "app/auth/__init__.py", "tests/test_auth_router.py"] }, "verification": { "tests_passed": "48/48", "lsp_clean": true }, - "fulfills_ac": ["Роуты авторизации доступны через app/auth/router.py", "Старые тесты проходят"] + "fulfills_ac": ["Роуты вынесены", "Тесты проходят"] } ``` -8. T1 → completed +7. `T1 → completed`. -#### Фаза EXECUTION — задача T2 (аналогично) +#### EXECUTION — задача T2 -Создаёт `auth/schemas.py`, request `req-T2`. +Создаёт `auth/schemas.py`, request `req-T2`. T2 → completed. -#### Фаза EXECUTION — задача T3 (аналогично) +#### EXECUTION — задача T3 -Создаёт `auth/deps.py`, request `req-T3`. +Создаёт `auth/deps.py`, request `req-T3`. T3 → completed. Задачи закончились. Агент ждёт команду. @@ -490,40 +175,38 @@ T6: Тесты ✓ ### METASTATE (по команде пользователя) -**Пользователь:** "обнови метасостояние" +**Пользователь:** «обнови метасостояние». -1. **Ревью requests:** три request-а, все approved - - req-T1 → `.agent/requests/archive/req-T1.json` - - req-T2 → `.agent/requests/archive/req-T2.json` - - req-T3 → `.agent/requests/archive/req-T3.json` +1. **Ревью requests:** три request-а, все approved. + - `req-T1`, `req-T2`, `req-T3` → `.agent/requests/archive/`. 2. **Архивация задач:** - - T1 в manifest → one-liner, детали в `.agent/archive/tasks/T1.json` - - T2, T3 — аналогично + - T1, T2, T3 → `.agent/archive/tasks/`. + - В `manifest.json` — one-liner: `status: "archived"`. 3. **Обновление project-state.md:** + ```markdown ## Key Modules | Module | Status | Description | |--------|--------|-------------| - | app/auth/router.py | new | Вынесенные роуты авторизации | + | app/auth/router.py | new | Вынесенные роуты | | app/auth/schemas.py | new | Pydantic схемы | | app/auth/deps.py | new | Dependency injection | ``` -4. **Обновление roadmap:** задачи выполнены → moved to done +4. **Создание handoff-summary.md:** -5. **Создание handoff-summary.md:** ```markdown ## Session Summary **Goal:** Рефакторинг авторизации **Completed:** 3/3 tasks **Approved requests:** req-T1, req-T2, req-T3 - + ## Project State - Модуль auth разбит на router+schema+deps. + auth разбит на router + schemas + deps. Исходный auth/login.py: 450 → 120 строк. - + ## Next Steps - Проверить, не осталось ли прямых импортов из старого login.py - Обновить main.py если нужно @@ -533,12 +216,25 @@ T6: Тесты ✓ ### HANDOFF -```text +``` HANDOFF COMPLETE -Session: ses_v21_001 +Session: ses_v30_001 +Target: /tmp/fastapi-app Type: existing Tasks: 3/3 completed Следующий агент начинает с .agent/handoff-summary.md ``` + +--- + +## Использование команд в процессе + +В любой момент сессии пользователь мог вызвать: + +- **«запиши это как ADR»** → `COMMANDS/adr.md` создал бы `.agent/decisions/001-modular-auth.md`. +- **«red team»** → `COMMANDS/red-team.md` создал бы `.agent/context/red-team-report.md` с попыткой сломать новую структуру. +- **«risk register»** → `COMMANDS/risk-register.md` зафиксировал бы допущения (например, «считаем, что порядок middleware не важен»). + +Команды **не обязательны**. Если не вызваны — `.agent/decisions/`, `risk-register.md`, `red-team-report.md` не создаются. diff --git a/.agent/src/install.ps1 b/.agent/src/install.ps1 index 08d57fa..c986b46 100644 --- a/.agent/src/install.ps1 +++ b/.agent/src/install.ps1 @@ -206,11 +206,13 @@ function Copy-Dir { } } -Copy-File (Join-Path $MetaAgentSrc "META_AGENT_GUIDE.md") $SrcDir +Copy-File (Join-Path $MetaAgentSrc "GUIDE.md") $SrcDir Copy-File (Join-Path $MetaAgentSrc "BOUNDARIES.md") $SrcDir +Copy-File (Join-Path $MetaAgentSrc "CHANGELOG.md") $SrcDir Copy-File (Join-Path $MetaAgentSrc "WORKFLOW.md") $SrcDir Copy-File (Join-Path $MetaAgentSrc "VERSION") $SrcDir Copy-Dir (Join-Path $MetaAgentSrc "PROTOCOLS") $SrcDir +Copy-Dir (Join-Path $MetaAgentSrc "COMMANDS") $SrcDir Copy-Dir (Join-Path $MetaAgentSrc "TEMPLATES") $SrcDir Copy-File (Join-Path $MetaAgentSrc "install.sh") $SrcDir Copy-File (Join-Path $MetaAgentSrc "install.ps1") $SrcDir @@ -222,19 +224,21 @@ if (-not (Test-Path $AgentsMd -PathType Leaf)) { $content = @" # MetaAgent -Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v$Version — +Этот проект использует [MetaAgent](.agent/src/GUIDE.md) v$Version — набор инструкций для AI-агента. ## Контекст MetaAgent | Ресурс | Путь | |--------|------| -| Главная инструкция | `.agent/src/META_AGENT_GUIDE.md` | +| Главная инструкция | `.agent/src/GUIDE.md` | | Протоколы фаз | `.agent/src/PROTOCOLS/` | +| Команды (on-demand) | `.agent/src/COMMANDS/` | | Шаблоны артефактов | `.agent/src/TEMPLATES/` | | Границы (что разрешено/запрещено) | `.agent/src/BOUNDARIES.md` | +| История версий | `.agent/src/CHANGELOG.md` | | Правила проекта | `.agent/rules/project-rules.md` | -| Примеры работы | `.agent/src/WORKFLOW.md` | +| Пример работы | `.agent/src/WORKFLOW.md` | | Версия | `.agent/src/VERSION` | ## Состояние сессии (если инициализировано) @@ -242,19 +246,38 @@ if (-not (Test-Path $AgentsMd -PathType Leaf)) { | Артефакт | Путь | |----------|------| | Чекпоинты сессии | `.agent/checkpoints.json` | -| Манифест задач | `.agent/task-manifest.json` | -| Сводка для exec-агента | `.agent/handoff-summary.md` | -| Анализ репозитория | `.agent/analysis-report.md` | +| Слепок проекта | `.agent/context/project-state.md` | +| Анализ репозитория | `.agent/context/analysis-report.md` | +| Дорожная карта | `.agent/roadmap/sources.md` | +| Манифест задач | `.agent/tasks/manifest.json` | +| Сводка для следующего агента | `.agent/handoff-summary.md` | +| Сводка сессии | `.agent/session-summary.md` | -## Для исполнительного агента +## Для агента -1. **Прочитай** `.agent/src/META_AGENT_GUIDE.md` — пойми жизненный цикл MetaAgent. +Жизненный цикл MetaAgent v$Version: + +``` +INIT → ANALYSE → ROADMAP → [DESIGN] → DECOMPOSITION → EXECUTION → METASTATE → HANDOFF +``` + +1. **Прочитай** `.agent/src/GUIDE.md` — пойми цикл и доступные команды. 2. **Прочитай** `.agent/src/BOUNDARIES.md` — соблюдай границы. -3. **Прочитай** `.agent/rules/project-rules.md` — выполни пользовательские правила. +3. **Прочитай** `.agent/rules/project-rules.md` — выполни правила пользователя. 4. **Проверь** `.agent/checkpoints.json` — если существует, используй как состояние сессии. -5. **Проверь** `.agent/task-manifest.json` — если существует, выполняй задачи по порядку. -6. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для +5. **Проверь** `.agent/context/project-state.md` — получи актуальную картину. +6. **Проверь** `.agent/tasks/manifest.json` — если существует, выполняй задачи по порядку. +7. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для обновления исходников MetaAgent до актуальной версии. + +## Команды (on-demand) + +В любой момент пользователь может вызвать: +- `/adr` — записать архитектурное решение +- `/red-team` — попытаться сломать дизайн +- `/risk-register` — зафиксировать допущения +- `/alt-arch` — описать альтернативу +- `/invariant-tests` — тесты-инварианты для ADR "@ $utf8 = [System.Text.Encoding]::UTF8 [System.IO.File]::WriteAllBytes($AgentsMd, $utf8.GetBytes($content)) @@ -263,19 +286,21 @@ if (-not (Test-Path $AgentsMd -PathType Leaf)) { $content = @" # MetaAgent -Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v$Version — +Этот проект использует [MetaAgent](.agent/src/GUIDE.md) v$Version — набор инструкций для AI-агента. ## Контекст MetaAgent | Ресурс | Путь | |--------|------| -| Главная инструкция | `.agent/src/META_AGENT_GUIDE.md` | +| Главная инструкция | `.agent/src/GUIDE.md` | | Протоколы фаз | `.agent/src/PROTOCOLS/` | +| Команды (on-demand) | `.agent/src/COMMANDS/` | | Шаблоны артефактов | `.agent/src/TEMPLATES/` | | Границы (что разрешено/запрещено) | `.agent/src/BOUNDARIES.md` | +| История версий | `.agent/src/CHANGELOG.md` | | Правила проекта | `.agent/rules/project-rules.md` | -| Примеры работы | `.agent/src/WORKFLOW.md` | +| Пример работы | `.agent/src/WORKFLOW.md` | | Версия | `.agent/src/VERSION` | ## Состояние сессии (если инициализировано) @@ -283,19 +308,38 @@ if (-not (Test-Path $AgentsMd -PathType Leaf)) { | Артефакт | Путь | |----------|------| | Чекпоинты сессии | `.agent/checkpoints.json` | -| Манифест задач | `.agent/task-manifest.json` | -| Сводка для exec-агента | `.agent/handoff-summary.md` | -| Анализ репозитория | `.agent/analysis-report.md` | +| Слепок проекта | `.agent/context/project-state.md` | +| Анализ репозитория | `.agent/context/analysis-report.md` | +| Дорожная карта | `.agent/roadmap/sources.md` | +| Манифест задач | `.agent/tasks/manifest.json` | +| Сводка для следующего агента | `.agent/handoff-summary.md` | +| Сводка сессии | `.agent/session-summary.md` | -## Для исполнительного агента +## Для агента -1. **Прочитай** `.agent/src/META_AGENT_GUIDE.md` — пойми жизненный цикл MetaAgent. +Жизненный цикл MetaAgent v$Version: + +``` +INIT → ANALYSE → ROADMAP → [DESIGN] → DECOMPOSITION → EXECUTION → METASTATE → HANDOFF +``` + +1. **Прочитай** `.agent/src/GUIDE.md` — пойми цикл и доступные команды. 2. **Прочитай** `.agent/src/BOUNDARIES.md` — соблюдай границы. -3. **Прочитай** `.agent/rules/project-rules.md` — выполни пользовательские правила. +3. **Прочитай** `.agent/rules/project-rules.md` — выполни правила пользователя. 4. **Проверь** `.agent/checkpoints.json` — если существует, используй как состояние сессии. -5. **Проверь** `.agent/task-manifest.json` — если существует, выполняй задачи по порядку. -6. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для +5. **Проверь** `.agent/context/project-state.md` — получи актуальную картину. +6. **Проверь** `.agent/tasks/manifest.json` — если существует, выполняй задачи по порядку. +7. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для обновления исходников MetaAgent до актуальной версии. + +## Команды (on-demand) + +В любой момент пользователь может вызвать: +- `/adr` — записать архитектурное решение +- `/red-team` — попытаться сломать дизайн +- `/risk-register` — зафиксировать допущения +- `/alt-arch` — описать альтернативу +- `/invariant-tests` — тесты-инварианты для ADR "@ $utf8 = [System.Text.Encoding]::UTF8 [System.IO.File]::WriteAllBytes($AgentsMd, $utf8.GetBytes($content)) diff --git a/.agent/src/install.sh b/.agent/src/install.sh old mode 100644 new mode 100755 index 3e2335f..7acd278 --- a/.agent/src/install.sh +++ b/.agent/src/install.sh @@ -162,20 +162,20 @@ copy_file() { local dst="$dst_dir/$name" if [[ ! -f "$src" ]]; then skip "$name (source not found)" - ((SKIP_COUNT += 1)) + SKIP_COUNT=$((SKIP_COUNT + 1)) return fi if [[ "$UPDATE" == true ]] || [[ ! -f "$dst" ]]; then if cp "$src" "$dst"; then ok "$name" - ((COPY_COUNT++)) + COPY_COUNT=$((COPY_COUNT + 1)) else fail "$name" - ((FAIL_COUNT++)) + FAIL_COUNT=$((FAIL_COUNT + 1)) fi else skip "$name (exists, use --update to overwrite)" - ((SKIP_COUNT += 1)) + SKIP_COUNT=$((SKIP_COUNT + 1)) fi } @@ -185,30 +185,32 @@ copy_dir() { local dst="$dst_dir/$name" if [[ ! -d "$src" ]]; then skip "$name/ (source not found)" - ((SKIP_COUNT += 1)) + SKIP_COUNT=$((SKIP_COUNT + 1)) return fi mkdir -p "$dst" if [[ "$UPDATE" == true ]]; then if cp -rf "$src"/* "$dst/" 2>/dev/null; then ok "$name/" - ((COPY_COUNT++)) + COPY_COUNT=$((COPY_COUNT + 1)) else fail "$name/ (partial copy)" - ((FAIL_COUNT++)) + FAIL_COUNT=$((FAIL_COUNT + 1)) fi else cp -rn "$src"/* "$dst/" 2>/dev/null || true ok "$name/" - ((COPY_COUNT++)) + COPY_COUNT=$((COPY_COUNT + 1)) fi } -copy_file "$METAAGENT_SRC/META_AGENT_GUIDE.md" "$SRC_DIR" +copy_file "$METAAGENT_SRC/GUIDE.md" "$SRC_DIR" copy_file "$METAAGENT_SRC/BOUNDARIES.md" "$SRC_DIR" +copy_file "$METAAGENT_SRC/CHANGELOG.md" "$SRC_DIR" copy_file "$METAAGENT_SRC/WORKFLOW.md" "$SRC_DIR" copy_file "$METAAGENT_SRC/VERSION" "$SRC_DIR" copy_dir "$METAAGENT_SRC/PROTOCOLS" "$SRC_DIR" +copy_dir "$METAAGENT_SRC/COMMANDS" "$SRC_DIR" copy_dir "$METAAGENT_SRC/TEMPLATES" "$SRC_DIR" copy_file "$METAAGENT_SRC/install.sh" "$SRC_DIR" copy_file "$METAAGENT_SRC/install.ps1" "$SRC_DIR" @@ -220,19 +222,21 @@ create_agents_md() { cat > "$1" << AGENTS_EOF # MetaAgent -Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v$VERSION — +Этот проект использует [MetaAgent](.agent/src/GUIDE.md) v$VERSION — набор инструкций для AI-агента. ## Контекст MetaAgent | Ресурс | Путь | |--------|------| -| Главная инструкция | \`.agent/src/META_AGENT_GUIDE.md\` | +| Главная инструкция | \`.agent/src/GUIDE.md\` | | Протоколы фаз | \`.agent/src/PROTOCOLS/\` | +| Команды (on-demand) | \`.agent/src/COMMANDS/\` | | Шаблоны артефактов | \`.agent/src/TEMPLATES/\` | | Границы (что разрешено/запрещено) | \`.agent/src/BOUNDARIES.md\` | +| История версий | \`.agent/src/CHANGELOG.md\` | | Правила проекта | \`.agent/rules/project-rules.md\` | -| Примеры работы | \`.agent/src/WORKFLOW.md\` | +| Пример работы | \`.agent/src/WORKFLOW.md\` | | Версия | \`.agent/src/VERSION\` | ## Состояние сессии (если инициализировано) @@ -240,19 +244,38 @@ create_agents_md() { | Артефакт | Путь | |----------|------| | Чекпоинты сессии | \`.agent/checkpoints.json\` | -| Манифест задач | \`.agent/task-manifest.json\` | -| Сводка для exec-агента | \`.agent/handoff-summary.md\` | -| Анализ репозитория | \`.agent/analysis-report.md\` | +| Слепок проекта | \`.agent/context/project-state.md\` | +| Анализ репозитория | \`.agent/context/analysis-report.md\` | +| Дорожная карта | \`.agent/roadmap/sources.md\` | +| Манифест задач | \`.agent/tasks/manifest.json\` | +| Сводка для следующего агента | \`.agent/handoff-summary.md\` | +| Сводка сессии | \`.agent/session-summary.md\` | -## Для исполнительного агента +## Для агента -1. **Прочитай** \`.agent/src/META_AGENT_GUIDE.md\` — пойми жизненный цикл MetaAgent. +Жизненный цикл MetaAgent v$VERSION: + +\`\`\` +INIT → ANALYSE → ROADMAP → [DESIGN] → DECOMPOSITION → EXECUTION → METASTATE → HANDOFF +\`\`\` + +1. **Прочитай** \`.agent/src/GUIDE.md\` — пойми цикл и доступные команды. 2. **Прочитай** \`.agent/src/BOUNDARIES.md\` — соблюдай границы. -3. **Прочитай** \`.agent/rules/project-rules.md\` — выполни пользовательские правила. +3. **Прочитай** \`.agent/rules/project-rules.md\` — выполни правила пользователя. 4. **Проверь** \`.agent/checkpoints.json\` — если существует, используй как состояние сессии. -5. **Проверь** \`.agent/task-manifest.json\` — если существует, выполняй задачи по порядку. -6. Если \`.agent/\` не инициализирован или устарел — запусти \`install.sh --update\` для +5. **Проверь** \`.agent/context/project-state.md\` — получи актуальную картину. +6. **Проверь** \`.agent/tasks/manifest.json\` — если существует, выполняй задачи по порядку. +7. Если \`.agent/\` не инициализирован или устарел — запусти \`install.sh --update\` для обновления исходников MetaAgent до актуальной версии. + +## Команды (on-demand) + +В любой момент пользователь может вызвать: +- \`/adr\` — записать архитектурное решение +- \`/red-team\` — попытаться сломать дизайн +- \`/risk-register\` — зафиксировать допущения +- \`/alt-arch\` — описать альтернативу +- \`/invariant-tests\` — тесты-инварианты для ADR AGENTS_EOF } @@ -264,7 +287,7 @@ elif [[ "$UPDATE" == true ]]; then ok "AGENTS.md updated" else skip "AGENTS.md (exists, use --update to overwrite)" - ((SKIP_COUNT += 1)) + SKIP_COUNT=$((SKIP_COUNT + 1)) fi # --- summary ------------------------------------------------------------- diff --git a/.agent/task-manifest.json b/.agent/task-manifest.json deleted file mode 100644 index 2c43a54..0000000 --- a/.agent/task-manifest.json +++ /dev/null @@ -1,79 +0,0 @@ -{ - "$schema": "metaagent-task-manifest", - "version": "1.0", - "session_id": "metaagent-003", - "goal": "i18n (ru/en) — инфраструктура и обёртка строк, контроль актуальности переводов", - "created_at": "2026-07-22T18:00:00Z", - "tasks": [ - { - "id": "T9", - "title": "i18n инфраструктура (cli/i18n.py)", - "description": "Создан модуль cli/i18n.py с Translator, t(), set_lang(), setup_i18n(). Язык: CF_LANG (env), по умолчанию 'ru'. Русские переводы — полные, английский — скелет (fallback на ru).", - "type": "feature", - "files": ["cli/i18n.py"], - "depends_on": [], - "acceptance_criteria": [ - "t() возвращает русский текст при CF_LANG=ru", - "t() возвращает русский текст при CF_LANG=en (fallback)", - "t('nonexistent') возвращает 'nonexistent'", - "setup_i18n() читает CF_LANG из окружения" - ], - "status": "completed" - }, - { - "id": "T10", - "title": "Обёртка CLI-строк в t()", - "description": "Все user-facing строки в cli/main.py и cli/config.py заменены на вызовы t('key', ...). Русский словарь содержит ~150 ключей.", - "type": "refactor", - "files": ["cli/main.py", "cli/config.py"], - "depends_on": ["T9"], - "acceptance_criteria": [ - "Все help-строки typer.Option/Argument через t()", - "Все console.print сообщения через t()", - "Все docstrings оставлены как комментарии (typer не использует)", - "ruff check проходит" - ], - "status": "completed" - }, - { - "id": "T11", - "title": "AI-промпты через i18n", - "description": "prompt.analyze, prompt.advice, prompt.scenario_comparison добавлены в словарь i18n, prompts.py использует t().", - "type": "refactor", - "files": ["ai/prompts.py"], - "depends_on": ["T9"], - "acceptance_criteria": [ - "ANALYZE_PROMPT = t('prompt.analyze')", - "ADVICE_PROMPT = t('prompt.advice')", - "SCENARIO_COMPARISON_PROMPT = t('prompt.scenario_comparison')" - ], - "status": "completed" - }, - { - "id": "T12", - "title": "Тесты i18n", - "description": "test_i18n.py: базовые тесты Translator, t(), set_lang, fallback, неизвестный ключ.", - "type": "test", - "files": ["tests/test_i18n.py"], - "depends_on": ["T9"], - "acceptance_criteria": [ - "pytest tests/test_i18n.py проходит", - "Покрытие: ru default, en fallback, неизвестный ключ, format args" - ], - "status": "completed" - }, - { - "id": "T13", - "title": "Аудит и контроль актуальности переводов", - "description": "Периодическая проверка: все ли ключи из TRANSLATIONS['ru'] имеют соответствующий перевод в TRANSLATIONS['en']. При добавлении новых фич — новые ключи должны добавляться в оба словаря.", - "type": "audit", - "files": ["cli/i18n.py"], - "depends_on": ["T9"], - "acceptance_criteria": [ - "Все ru-ключи имеют en-перевод или fallback", - "При добавлении нового t('key') он регистрируется в _r()" - ], - "status": "pending" - } - ] -} diff --git a/.agent/task-manifest.md b/.agent/task-manifest.md deleted file mode 100644 index b8ff773..0000000 --- a/.agent/task-manifest.md +++ /dev/null @@ -1,22 +0,0 @@ -# Task Manifest - -**Session:** metaagent-002 -**Goal:** Обновление metaagent-артефактов до v1.0.0, валидация существующего кода и окружения -**Date:** 2026-07-12T20:00:00Z - ---- - -## Task Overview - -| ID | Title | Type | Depends On | Status | -|---|---|---|---|---| -| T1 | Инициализация проекта и зависимостей | config | — | completed | -| T2 | Модель данных (dataclass + JSON serialization) | feature | T1 | completed | -| T3 | Forecast Engine (базовый прогноз) | feature | T2 | completed | -| T4 | Scenario Analysis | feature | T3 | completed | -| T5 | Excel Sync (import/export) | feature | T2 | completed | -| T6 | CLI (Typer) — все команды | feature | T2, T3, T4, T5, T7 | completed | -| T7 | AI Assistant (промпты + интерфейс) | feature | T3 | completed | -| T8 | Тесты на все модули | test | T2, T3, T4, T5, T6, T7 | completed | - -**Total tasks:** 8 — all completed diff --git a/.agent/tasks/manifest.json b/.agent/tasks/manifest.json new file mode 100644 index 0000000..5727713 --- /dev/null +++ b/.agent/tasks/manifest.json @@ -0,0 +1,16 @@ +{ + "$schema": "metaagent-task-manifest", + "version": "3.0", + "session_id": "metaagent-005", + "goal": "Серьёзный архитектурный рефактор: A1+A10 (слои+version), A2+A3 (pydantic), A4 (decimal), A7+A8+A9 (DI+repo), A5 (CLI decompose)", + "created_at": "2026-10-08T15:58:00Z", + "tasks": [ + { "id": "T1", "title": "Реструктуризация в domain/application/infrastructure + version=1", "status": "archived", "origin": "user:direct" }, + { "id": "T2", "title": "Pydantic v2 — миграция моделей", "status": "archived", "origin": "user:direct" }, + { "id": "T3", "title": "Decimal для денег", "status": "archived", "origin": "user:direct" }, + { "id": "T4", "title": "Repository pattern — ModelRepository", "status": "archived", "origin": "user:direct" }, + { "id": "T5", "title": "Dependency Injection в сервисах", "status": "archived", "origin": "user:direct" }, + { "id": "T6", "title": "Декомпозиция CLI", "status": "archived", "origin": "user:direct" }, + { "id": "T7", "title": "Финальная валидация", "status": "archived", "origin": "user:direct" } + ] +} diff --git a/.agent/tasks/manifest.md b/.agent/tasks/manifest.md new file mode 100644 index 0000000..6bdc095 --- /dev/null +++ b/.agent/tasks/manifest.md @@ -0,0 +1,123 @@ +# Task Manifest + +**Session:** `metaagent-005` +**Goal:** Серьёзный архитектурный рефактор +**Date:** 2026-10-08 +**Total tasks:** 7 + +--- + +## T1: Реструктуризация в domain/application/infrastructure + version=1 + +**Зависимости:** — +**Файлы:** domain/ (new), application/ (new), infrastructure/{cli,sync,ai}/ (new), tests/ + +**Что:** Ввести явные слои. Переместить пакеты. Добавить version: 1 в FinancialModel. + +**Acceptance:** +- [ ] Структура domain/application/infrastructure создана +- [ ] Все исходные файлы перемещены +- [ ] Все импорты обновлены +- [ ] `FinancialModel.to_dict()` → `{'version': 1, ...}` +- [ ] `from_dict()` поддерживает v0 (без version) и v1 +- [ ] pytest 63/63 + +--- + +## T2: Pydantic v2 — миграция моделей + +**Зависимости:** T1 +**Файлы:** domain/*.py, pyproject.toml, infrastructure/sync/excel_sync.py + +**Что:** `@dataclass` → `pydantic.BaseModel`. Удалить ручные `to_dict`/`from_dict`. + +**Acceptance:** +- [ ] Все модели — `BaseModel` +- [ ] Удалены ручные to_dict/from_dict +- [ ] UUID в JSON как str +- [ ] Валидация (balance >= 0, и т.п.) +- [ ] Excel-sync адаптирован +- [ ] pytest 63/63 + +--- + +## T3: Decimal для денег + +**Зависимости:** T2 +**Файлы:** domain/*.py, application/*.py, infrastructure/sync/excel_sync.py, infrastructure/cli/{main,config}.py + +**Что:** `float` → `Decimal` для всех monetary полей. Арифметика engine, форматирование. + +**Acceptance:** +- [ ] monetary поля — `Decimal` +- [ ] CurrencyConverter с Decimal +- [ ] ForecastService арифметика — Decimal +- [ ] Excel-sync читает числа как Decimal +- [ ] rich.print форматирует Decimal (2 знака) +- [ ] JSON-сериализация Decimal работает +- [ ] pytest 63/63 + +--- + +## T4: Repository pattern — ModelRepository + +**Зависимости:** T1 +**Файлы:** application/repositories/model_repository.py, infrastructure/repositories/{json_file,excel}_repository.py, infrastructure/sync/excel_sync.py + +**Что:** `ModelRepository` Protocol + `JsonFileRepository` + `ExcelRepository` (адаптер над ExcelSync). + +**Acceptance:** +- [ ] `ModelRepository` Protocol (load/save) +- [ ] `JsonFileRepository` реализует Protocol +- [ ] `ExcelRepository` реализует Protocol +- [ ] `FinancialModel.save/load` удалены +- [ ] Тесты на каждый репозиторий +- [ ] pytest 63/63 + +--- + +## T5: Dependency Injection в сервисах + +**Зависимости:** T4 +**Файлы:** application/forecast.py, scenarios.py, infrastructure/ai/assistant.py, infrastructure/cli/{main,config}.py + +**Что:** Зависимости через конструктор. Composition root в CLI. + +**Acceptance:** +- [ ] `ForecastService.__init__(model, repository, converter)` +- [ ] ScenarioService, AssistantService — то же +- [ ] Нет `new ForecastService()` внутри других сервисов +- [ ] CLI собирает граф зависимостей +- [ ] pytest 63/63 + +--- + +## T6: Декомпозиция CLI + +**Зависимости:** T5 +**Файлы:** infrastructure/cli/main.py → app.py, infrastructure/cli/commands/*.py, infrastructure/cli/{paths,services}.py + +**Что:** 8 команд в отдельных файлах. config.py → paths.py + services.py. + +**Acceptance:** +- [ ] Каждая команда в cli/commands/*.py +- [ ] cli/paths.py — только пути +- [ ] cli/services.py — composition root +- [ ] Размер файлов < 100-150 LOC +- [ ] Поведение идентично +- [ ] pytest 63/63 + +--- + +## T7: Финальная валидация + +**Зависимости:** T6 +**Файлы:** tests/, README.md, pyproject.toml + +**Что:** Прогнать pytest, ручная проверка CLI, обновить README. + +**Acceptance:** +- [ ] pytest 63/63+ +- [ ] cf init, cf forecast, cf scenario, cf compare — работают +- [ ] cf import data.xlsx → cf export — round-trip +- [ ] README.md обновлён под новую структуру