diff --git a/README.md b/README.md index bf3496f..a076717 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,23 @@ - [ADR и Sequence Diagrams](docs/ADR_AND_SEQUENCES.md) - [Roadmap](docs/ROADMAP.md) +### Серия спецификации (внешний аудит) +- [Executive Summary](docs/spec-series/01_Executive_Summary.md) +- [Vision & Scope](docs/spec-series/02_Vision_and_Scope.md) +- [Functional Requirements](docs/spec-series/03_Functional_Requirements.md) +- [Non-Functional Requirements](docs/spec-series/04_Non_Functional_Requirements.md) +- [Domain Model (серия)](docs/spec-series/05_Domain_Model.md) +- [Architecture C4](docs/spec-series/06_Architecture_C4.md) +- [Database Design](docs/spec-series/07_Database_Design.md) +- [API Specification](docs/spec-series/08_API_Specification.md) +- [Event Bus](docs/spec-series/09_Event_Bus.md) +- [Agent Protocol](docs/spec-series/10_Agent_Protocol.md) +- [Connector SDK](docs/spec-series/11_Connector_SDK.md) +- [Security](docs/spec-series/12_Security.md) +- [Observability](docs/spec-series/13_Observability.md) +- [ADR Drafts](docs/spec-series/ADR-DRAFTS.md) +- [Improvement Proposals (рецензия)](docs/spec-series/IMPROVEMENT-PROPOSALS.md) + ### Участие - [Правила участия](CONTRIBUTING.md) diff --git a/docs/spec-series/01_Executive_Summary.md b/docs/spec-series/01_Executive_Summary.md new file mode 100644 index 0000000..b46095c --- /dev/null +++ b/docs/spec-series/01_Executive_Summary.md @@ -0,0 +1,39 @@ +# Документ 01. Executive Summary + +> Это первый документ из серии архитектурной спецификации Agent Control +> Center. + +## Назначение + +Данный документ открывает полную архитектурную спецификацию проекта и +определяет: - цели продукта; - границы системы; - основные принципы; - +ключевые заинтересованные стороны; - критерии успеха; - обзор +архитектуры верхнего уровня. + +## Содержание последующих документов + +1. Executive Summary +2. Vision & Scope +3. Functional Requirements +4. Non-Functional Requirements +5. Domain Model +6. Architecture (C4) +7. Database Design +8. API Specification +9. Event Bus +10. Agent Protocol +11. Connector SDK +12. Security +13. Observability +14. Testing Strategy +15. Deployment +16. Roadmap +17. ADR +18. Appendices + +## Правила серии + +- Каждый документ является самостоятельной частью общей спецификации. +- Все документы имеют сквозную нумерацию. +- После завершения серии документы могут быть объединены в единую + спецификацию. diff --git a/docs/spec-series/02_Vision_and_Scope.md b/docs/spec-series/02_Vision_and_Scope.md new file mode 100644 index 0000000..874c9e1 --- /dev/null +++ b/docs/spec-series/02_Vision_and_Scope.md @@ -0,0 +1,79 @@ +# Документ 02. Vision & Scope + +## Назначение + +Документ определяет долгосрочное видение платформы Agent Control Center, +её границы, целевую аудиторию и принципы развития. + +## Vision + +Agent Control Center (ACC) --- единая платформа управления AI-агентами, +задачами, контекстом, памятью и исполнением, предназначенная для +разработки, эксплуатации и масштабирования мультиагентных систем. + +### Основные цели + +- Централизованное управление агентами. +- Повторное использование знаний и навыков. +- Безопасное выполнение задач. +- Поддержка локальных и облачных моделей. +- Масштабируемость и отказоустойчивость. + +## Scope + +### Входит в проект + +- Управление агентами. +- Управление проектами. +- Оркестрация задач. +- Handoff между агентами. +- Memory и Knowledge Base. +- Connector SDK. +- Execution Engine. +- Scheduler. +- Event Bus. +- REST API. +- Web UI. +- Audit. +- Observability. + +### Не входит в MVP + +- Marketplace. +- Mobile Client. +- Billing. +- Multi-region deployment. +- Enterprise SSO (планируется после MVP). + +## Пользователи + +- Developer +- Architect +- Team Lead +- Administrator +- Operator +- AI Agent + +## Ключевые принципы + +- API First +- Event Driven +- Security by Design +- Modular Architecture +- Extensibility +- Testability +- Observability +- Backward Compatibility + +## Критерии успеха + +- Полностью документированные API. +- Поддержка нескольких AI-провайдеров. +- Масштабирование по горизонтали. +- Высокая наблюдаемость. +- Возможность расширения через SDK. + +## Связанные документы + +01_Executive_Summary.md 03_Functional_Requirements.md +04_Non_Functional_Requirements.md diff --git a/docs/spec-series/03_Functional_Requirements.md b/docs/spec-series/03_Functional_Requirements.md new file mode 100644 index 0000000..f9de982 --- /dev/null +++ b/docs/spec-series/03_Functional_Requirements.md @@ -0,0 +1,198 @@ +# Документ 03. Functional Requirements + +## Назначение + +Документ определяет функциональные требования к платформе Agent Control +Center. Требования сгруппированы по подсистемам и будут использоваться +как основа для проектирования API, архитектуры и тестирования. + +------------------------------------------------------------------------ + +# FR-001 Управление пользователями + +Система должна обеспечивать: + +- регистрацию пользователей; +- аутентификацию; +- управление профилями; +- управление ролями; +- блокировку и восстановление доступа. + +------------------------------------------------------------------------ + +# FR-002 Организации и рабочие пространства + +Система должна поддерживать: + +- создание организаций; +- создание Workspace; +- приглашение участников; +- распределение ролей; +- управление квотами. + +------------------------------------------------------------------------ + +# FR-003 Проекты + +Пользователь должен иметь возможность: + +- создавать проекты; +- архивировать проекты; +- клонировать проекты; +- экспортировать проект; +- импортировать проект. + +------------------------------------------------------------------------ + +# FR-004 Управление агентами + +Поддерживается: + +- создание AI-агента; +- настройка модели; +- настройка памяти; +- выбор инструментов; +- управление жизненным циклом агента. + +------------------------------------------------------------------------ + +# FR-005 Выполнение задач + +Система должна: + +- создавать задачи; +- запускать задачи; +- приостанавливать выполнение; +- возобновлять выполнение; +- отменять выполнение; +- повторно запускать задачи. + +------------------------------------------------------------------------ + +# FR-006 Оркестрация + +Поддерживаются: + +- последовательное выполнение; +- параллельное выполнение; +- зависимые задачи; +- ручное подтверждение; +- автоматические сценарии. + +------------------------------------------------------------------------ + +# FR-007 Handoff + +Агенты должны передавать: + +- контекст; +- результаты; +- артефакты; +- историю; +- ограничения; +- критерии завершения. + +------------------------------------------------------------------------ + +# FR-008 Memory + +Поддерживаются: + +- долговременная память; +- кратковременная память; +- поиск; +- обновление; +- удаление; +- версионирование. + +------------------------------------------------------------------------ + +# FR-009 Knowledge Base + +Система должна: + +- хранить документы; +- индексировать документы; +- выполнять поиск; +- поддерживать категории; +- отслеживать версии. + +------------------------------------------------------------------------ + +# FR-010 Connector SDK + +Коннекторы должны поддерживать: + +- регистрацию; +- heartbeat; +- публикацию возможностей; +- передачу событий; +- загрузку артефактов; +- безопасную аутентификацию. + +------------------------------------------------------------------------ + +# FR-011 Event Bus + +Система должна публиковать события: + +- RunCreated; +- RunStarted; +- RunCompleted; +- RunFailed; +- ApprovalRequested; +- ConnectorOnline; +- ConnectorOffline. + +------------------------------------------------------------------------ + +# FR-012 API + +Все функции платформы должны быть доступны через REST API. + +API должно: + +- поддерживать OpenAPI; +- иметь версионирование; +- возвращать стандартизированные ошибки; +- поддерживать идемпотентность. + +------------------------------------------------------------------------ + +# FR-013 Audit + +Все критические действия должны журналироваться. + +------------------------------------------------------------------------ + +# FR-014 Notifications + +Поддерживаются: + +- уведомления пользователей; +- webhooks; +- email; +- интеграции с внешними системами. + +------------------------------------------------------------------------ + +# FR-015 Administration + +Администратор должен иметь возможность: + +- управлять пользователями; +- управлять ролями; +- просматривать аудит; +- управлять коннекторами; +- просматривать состояние платформы. + +------------------------------------------------------------------------ + +## Traceability + +Каждое требование должно иметь ссылку на: + +- архитектуру; +- API; +- тесты; +- критерии приемки. diff --git a/docs/spec-series/04_Non_Functional_Requirements.md b/docs/spec-series/04_Non_Functional_Requirements.md new file mode 100644 index 0000000..1e0c053 --- /dev/null +++ b/docs/spec-series/04_Non_Functional_Requirements.md @@ -0,0 +1,127 @@ +# Документ 04. Non-Functional Requirements + +## Назначение + +Документ определяет нефункциональные требования (NFR) к платформе Agent +Control Center. Они являются обязательными для всех компонентов системы +и используются как критерии архитектурных решений и приемки. + +------------------------------------------------------------------------ + +# NFR-001 Производительность + +Система должна: + +- поддерживать не менее 100 одновременных пользователей для MVP; +- обеспечивать время ответа API (P95) менее 500 мс для операций + чтения; +- запускать задачи без заметных задержек при штатной нагрузке; +- поддерживать горизонтальное масштабирование. + +------------------------------------------------------------------------ + +# NFR-002 Надежность + +Требования: + +- отсутствие единой точки отказа для критических компонентов; +- автоматическое восстановление после кратковременных сбоев; +- повторная обработка временных ошибок; +- сохранение состояния длительных задач. + +------------------------------------------------------------------------ + +# NFR-003 Масштабируемость + +Архитектура должна позволять: + +- масштабировать API независимо; +- масштабировать обработчики задач; +- подключать дополнительные коннекторы без изменения ядра; +- добавлять новые AI-провайдеры через адаптеры. + +------------------------------------------------------------------------ + +# NFR-004 Безопасность + +Обязательные требования: + +- TLS для всех сетевых соединений; +- безопасное хранение секретов; +- разграничение доступа по ролям; +- журналирование критических действий; +- защита от повторного выполнения чувствительных операций. + +------------------------------------------------------------------------ + +# NFR-005 Наблюдаемость + +Система должна предоставлять: + +- структурированные журналы; +- метрики; +- трассировку запросов; +- проверки состояния (health checks); +- мониторинг очередей и фоновых задач. + +------------------------------------------------------------------------ + +# NFR-006 Поддерживаемость + +Кодовая база должна: + +- иметь модульную структуру; +- сопровождаться документацией; +- покрываться автоматическими тестами; +- поддерживать обратную совместимость публичных API. + +------------------------------------------------------------------------ + +# NFR-007 Совместимость + +Платформа должна: + +- работать на Linux; +- поддерживать контейнеризацию; +- использовать PostgreSQL как основную СУБД; +- обеспечивать совместимость с OpenAPI 3.x. + +------------------------------------------------------------------------ + +# NFR-008 Тестируемость + +Для каждого функционального требования должны существовать: + +- unit-тесты; +- интеграционные тесты; +- контрактные тесты (при необходимости); +- критерии приемки. + +------------------------------------------------------------------------ + +# NFR-009 Эксплуатация + +Необходимо обеспечить: + +- централизованную конфигурацию; +- безопасное обновление компонентов; +- резервное копирование данных; +- документированные процедуры восстановления. + +------------------------------------------------------------------------ + +# NFR-010 Качество + +Все изменения должны проходить: + +- статический анализ; +- автоматические проверки; +- код-ревью; +- регрессионное тестирование. + +------------------------------------------------------------------------ + +## Traceability + +Каждое NFR должно иметь связь с: - архитектурными решениями; - +тестами; - эксплуатационной документацией; - критериями приемки. diff --git a/docs/spec-series/05_Domain_Model.md b/docs/spec-series/05_Domain_Model.md new file mode 100644 index 0000000..2ceefce --- /dev/null +++ b/docs/spec-series/05_Domain_Model.md @@ -0,0 +1,91 @@ +# Документ 05. Domain Model + +## Назначение + +Документ описывает модель предметной области Agent Control Center, +основные сущности, их связи и жизненный цикл. + +## Основные агрегаты + +### Organization + +Назначение: верхний уровень изоляции данных. + +Содержит: - Workspace - Users - Policies - Secrets + +### Workspace + +Логическая область работы команды. + +Содержит: - Projects - Agents - Connectors + +### Project + +Единица управления разработкой. + +Связан с: - Tasks - Runs - Artifacts - Knowledge Base + +### Task + +Описание работы для агента. + +Состояния: - Draft - Ready - Running - WaitingApproval - Completed - +Failed - Cancelled + +### Run + +Экземпляр выполнения задачи. + +Хранит: - входной контекст - журнал событий - результаты - метрики + +### Agent + +Конфигурация AI-агента. + +Свойства: - модель - инструменты - память - разрешения - лимиты + +### Connector + +Интеграция с внешними системами. + +### Artifact + +Файл или результат выполнения. + +### Memory + +Долговременная и кратковременная память. + +### Knowledge Base + +Коллекция документов с поиском и версионированием. + +### Approval + +Объект согласования действий. + +### Audit Event + +Неизменяемая запись о значимом событии. + +## Основные связи + +Organization → Workspace + +Workspace → Projects → Agents → Connectors + +Project → Tasks → Runs → Artifacts → Knowledge Base + +Run → Events → Metrics → Logs + +## Правила модели + +- Все сущности имеют UUID. +- Используется soft delete, если не указано иначе. +- Все изменения журналируются. +- Публичные объекты имеют версионирование. +- Между Workspace обеспечивается строгая изоляция. + +## Следующий документ + +06_Architecture_C4.md diff --git a/docs/spec-series/06_Architecture_C4.md b/docs/spec-series/06_Architecture_C4.md new file mode 100644 index 0000000..c96761b --- /dev/null +++ b/docs/spec-series/06_Architecture_C4.md @@ -0,0 +1,82 @@ +# Документ 06. Architecture (C4) + +## Назначение + +Документ описывает архитектуру системы по модели C4. + +# C1. System Context + +Внешние участники: - Пользователь - AI Provider - Git - CI/CD - +PostgreSQL - Object Storage - Message Broker + +# C2. Containers + +- Web UI +- REST API +- Run Orchestrator +- Scheduler +- Agent Runtime +- Connector Gateway +- Memory Service +- Knowledge Service +- Event Bus +- Audit Service + +# C3. Components + +## API + +- Auth +- Projects +- Runs +- Agents +- Connectors +- Admin + +## Orchestrator + +- Planner +- Executor +- Retry Manager +- Approval Manager + +## Memory + +- Vector Index +- Metadata Store +- Retrieval + +# C4. Code + +Рекомендуемая структура: + + app/ + core/ + api/ + services/ + repositories/ + models/ + workers/ + events/ + integrations/ + tests/ + +# Принципы + +- API First +- Event Driven +- Stateless сервисы +- Горизонтальное масштабирование +- Idempotency +- Dependency Injection + +# Масштабирование + +- API масштабируется независимо. +- Workers масштабируются по очередям. +- Memory Service выделяется в отдельный сервис. +- Event Bus поддерживает асинхронную обработку. + +## Следующий документ + +07_Database_Design.md diff --git a/docs/spec-series/07_Database_Design.md b/docs/spec-series/07_Database_Design.md new file mode 100644 index 0000000..da68a36 --- /dev/null +++ b/docs/spec-series/07_Database_Design.md @@ -0,0 +1,128 @@ +# Документ 07. Database Design + +## Назначение + +Документ описывает архитектуру базы данных Agent Control Center, модель +хранения данных, правила проектирования схем, миграции и требования к +производительности. + +# 1. Общие требования + +- Основная СУБД: PostgreSQL 16+ +- UUID в качестве первичных ключей. +- UTC для всех временных меток. +- Миграции через Alembic. +- Soft Delete по умолчанию. +- Поля created_at и updated_at обязательны. + +# 2. Основные таблицы + +## organizations + +Хранение организаций. + +Основные поля: - id (UUID) - name - slug - status - created_at - +updated_at + +## workspaces + +Связаны с organization. + +Поля: - id - organization_id - name - description + +## users + +Поля: - id - email - display_name - status + +## roles + +Поля: - id - name - description + +## projects + +Поля: - id - workspace_id - name - status - version + +## tasks + +Поля: - id - project_id - title - state - priority + +## runs + +Поля: - id - task_id - agent_id - state - started_at - finished_at + +## agents + +Поля: - id - workspace_id - provider - model - configuration_json + +## connectors + +Поля: - id - type - status - capabilities_json + +## artifacts + +Поля: - id - run_id - storage_uri - checksum - size_bytes + +## memories + +Поля: - id - workspace_id - memory_type - embedding_id - metadata_json + +## knowledge_documents + +Поля: - id - workspace_id - title - version - source + +## approvals + +Поля: - id - run_id - requested_by - approved_by - state + +## audit_events + +Поля: - id - actor_id - entity_type - entity_id - action - created_at + +# 3. Индексы + +Рекомендуемые индексы: + +- organization_id +- workspace_id +- project_id +- task_id +- run_id +- state +- created_at +- updated_at + +GIN: - metadata_json - capabilities_json + +# 4. Ограничения + +- Внешние ключи обязательны. +- CHECK для состояний. +- UNIQUE для slug и email. +- ON DELETE RESTRICT для критичных сущностей. + +# 5. Миграции + +Правила: + +- одна миграция --- одно изменение; +- обратимые миграции; +- автоматическая проверка в CI; +- тестирование миграций на пустой и заполненной БД. + +# 6. Производительность + +Целевые показатели: + +- поиск по PK \< 10 мс; +- типовые SELECT \< 100 мс; +- поддержка партиционирования для audit_events и artifacts. + +# 7. Архивирование + +- Архив завершённых Run. +- Политики хранения Audit. +- Очистка временных артефактов по TTL. + +## Следующий документ + +08_API_Specification.md diff --git a/docs/spec-series/08_API_Specification.md b/docs/spec-series/08_API_Specification.md new file mode 100644 index 0000000..1256a6c --- /dev/null +++ b/docs/spec-series/08_API_Specification.md @@ -0,0 +1,112 @@ +# Документ 08. API Specification + +## Назначение + +Документ определяет стандарты REST API платформы Agent Control Center, +правила проектирования endpoint'ов, форматы данных и требования к +совместимости. + +# 1. Общие принципы + +- REST API с JSON. +- OpenAPI 3.1. +- Версионирование через `/api/v1`. +- UTF-8. +- UTC для дат и времени. +- UUID как идентификаторы ресурсов. + +# 2. Аутентификация + +Поддерживаются: - OAuth2/OIDC; - Bearer Token; - API Keys (для сервисных +интеграций). + +Каждый запрос должен содержать корректные учетные данные, если ресурс не +является публичным. + +# 3. Структура URL + +Примеры: + +- GET /api/v1/projects +- POST /api/v1/projects +- GET /api/v1/projects/{project_id} +- PATCH /api/v1/projects/{project_id} +- DELETE /api/v1/projects/{project_id} + +Аналогичная структура используется для: - workspaces; - tasks; - runs; - +agents; - connectors; - artifacts; - memories; - approvals. + +# 4. Правила запросов + +- Использовать HTTP-методы по назначению. +- Поддерживать пагинацию. +- Поддерживать фильтрацию. +- Поддерживать сортировку. +- Поддерживать идемпотентность для повторяемых операций. + +# 5. Формат ответов + +Успешный ответ: + +``` json +{ + "data": {}, + "meta": { + "request_id": "uuid" + } +} +``` + +Ошибка: + +``` json +{ + "error": { + "code": "ACC-4001", + "message": "Validation failed" + }, + "meta": { + "request_id": "uuid" + } +} +``` + +# 6. Коды ошибок + +- 400 Bad Request +- 401 Unauthorized +- 403 Forbidden +- 404 Not Found +- 409 Conflict +- 422 Validation Error +- 429 Too Many Requests +- 500 Internal Server Error + +Коды ошибок должны соответствовать отдельному каталогу ошибок. + +# 7. Версионирование + +- `/api/v1` --- стабильная версия. +- Несовместимые изменения требуют новой версии API. +- Устаревшие версии сопровождаются периодом депрекации. + +# 8. Идемпотентность + +Для операций создания и запуска рекомендуется поддерживать заголовок +`Idempotency-Key`. + +# 9. Трассировка + +Каждый запрос должен иметь: - request_id; - correlation_id (при наличии +распределенных операций). + +# 10. Документация + +- OpenAPI спецификация генерируется автоматически. +- `/docs` --- Swagger UI. +- `/redoc` --- ReDoc. +- `/openapi.json` --- машинное описание API. + +## Следующий документ + +09_Event_Bus.md diff --git a/docs/spec-series/09_Event_Bus.md b/docs/spec-series/09_Event_Bus.md new file mode 100644 index 0000000..307e502 --- /dev/null +++ b/docs/spec-series/09_Event_Bus.md @@ -0,0 +1,89 @@ +# Документ 09. Event Bus + +## Назначение + +Документ описывает событийную архитектуру платформы Agent Control +Center, правила публикации и обработки событий. + +# 1. Принципы + +- Event Driven Architecture. +- Асинхронная обработка. +- Слабая связанность сервисов. +- Идемпотентные обработчики. +- Повторная доставка допустима. + +# 2. Категории событий + +## Lifecycle + +- RunCreated +- RunScheduled +- RunStarted +- RunPaused +- RunResumed +- RunCompleted +- RunFailed +- RunCancelled + +## Project + +- ProjectCreated +- ProjectUpdated +- ProjectArchived + +## Agent + +- AgentCreated +- AgentUpdated +- AgentDeleted + +## Connector + +- ConnectorRegistered +- ConnectorOnline +- ConnectorOffline +- ConnectorHeartbeat + +## Memory + +- MemoryCreated +- MemoryUpdated +- MemoryDeleted + +## Artifact + +- ArtifactUploaded +- ArtifactDeleted + +## Security + +- UserLoggedIn +- PermissionChanged +- ApprovalRequested +- ApprovalGranted +- ApprovalRejected + +# 3. Формат сообщения + +Каждое событие содержит: - event_id - event_type - event_version - +occurred_at - producer - correlation_id - payload + +# 4. Гарантии + +- At-least-once delivery. +- Идемпотентность обработчиков обязательна. +- Сохранение порядка в пределах одного aggregate. + +# 5. Повторная обработка + +Использовать: - retry policy; - dead-letter queue; - экспоненциальную +задержку. + +# 6. Наблюдаемость + +Каждое событие журналируется и имеет трассировку. + +## Следующий документ + +10_Agent_Protocol.md diff --git a/docs/spec-series/10_Agent_Protocol.md b/docs/spec-series/10_Agent_Protocol.md new file mode 100644 index 0000000..8389c03 --- /dev/null +++ b/docs/spec-series/10_Agent_Protocol.md @@ -0,0 +1,143 @@ +# Документ 10. Agent Protocol + +## Назначение + +Документ определяет протокол взаимодействия AI-агентов в платформе Agent +Control Center, включая регистрацию, выполнение задач, передачу +контекста и восстановление после сбоев. + +# 1. Цели протокола + +- Унифицированное взаимодействие агентов. +- Независимость от поставщика LLM. +- Поддержка распределенного выполнения. +- Безопасная передача контекста. +- Совместимость между версиями. + +# 2. Жизненный цикл агента + +Состояния: + +- Created +- Registered +- Idle +- Busy +- WaitingApproval +- Paused +- Resuming +- Completed +- Failed +- Offline +- Decommissioned + +Все переходы состояний должны журналироваться. + +# 3. Регистрация + +При регистрации агент обязан передать: + +- agent_id +- protocol_version +- provider +- model +- capabilities +- supported_tools +- max_context_size + +После успешной регистрации агент получает конфигурацию и политики +безопасности. + +# 4. Heartbeat + +Heartbeat отправляется периодически и содержит: + +- agent_id +- timestamp +- current_state +- active_run_id +- resource_usage +- protocol_version + +При отсутствии heartbeat в течение заданного интервала агент переводится +в состояние Offline. + +# 5. Выполнение задач + +Каждая задача содержит: + +- run_id +- task_id +- objective +- context +- constraints +- acceptance_criteria +- timeout +- priority + +# 6. Handoff + +При передаче задачи другому агенту передаются: + +- objective +- current_status +- completed_steps +- remaining_steps +- artifacts +- memory_links +- open_questions +- constraints +- acceptance_criteria + +Передача должна быть атомарной и журналируемой. + +# 7. Checkpoint + +Агент обязан поддерживать создание контрольных точек: + +- checkpoint_id +- run_id +- timestamp +- execution_state +- memory_snapshot +- artifact_references + +Checkpoint используется для восстановления после сбоя. + +# 8. Восстановление + +После восстановления агент: + +1. Загружает последний checkpoint. +2. Проверяет актуальность контекста. +3. Возобновляет выполнение. +4. Публикует событие RunResumed. + +# 9. Потоковые события + +Агент может публиковать: + +- progress; +- logs; +- warnings; +- partial_results; +- metrics. + +Все события содержат correlation_id и request_id. + +# 10. Совместимость + +- Обязательное указание protocol_version. +- Несовместимые изменения требуют новой версии протокола. +- Старые версии поддерживаются в течение периода депрекации. + +# 11. Требования безопасности + +- Все сообщения подписываются. +- Используется TLS. +- Проверяется авторизация агента. +- Ограничиваются разрешенные инструменты. +- Все критические действия записываются в Audit. + +## Следующий документ + +11_Connector_SDK.md diff --git a/docs/spec-series/11_Connector_SDK.md b/docs/spec-series/11_Connector_SDK.md new file mode 100644 index 0000000..f5e6502 --- /dev/null +++ b/docs/spec-series/11_Connector_SDK.md @@ -0,0 +1,77 @@ +# Документ 11. Connector SDK + +## Назначение + +Спецификация SDK для интеграции внешних систем с Agent Control Center. + +# 1. Требования + +Коннектор обязан: + +- поддерживать Protocol v1; +- проходить регистрацию; +- отправлять heartbeat; +- публиковать события; +- поддерживать безопасную аутентификацию. + +# 2. Жизненный цикл + +Created → Registered → Online → Busy → Offline → Retired + +# 3. Обязательные операции + +- register() +- heartbeat() +- capabilities() +- execute() +- cancel() +- upload_artifact() +- download_artifact() +- publish_event() + +# 4. Capability Discovery + +Коннектор публикует: + +- поддерживаемые инструменты; +- ограничения; +- максимальный размер данных; +- поддерживаемые версии протокола. + +# 5. Безопасность + +- TLS 1.3+ +- OAuth2/API Key +- Подпись сообщений +- Проверка разрешений +- Ограничение частоты запросов + +# 6. Обработка ошибок + +Категории: + +- Authentication +- Authorization +- Validation +- Network +- Timeout +- Internal + +Повторная отправка допускается только для идемпотентных операций. + +# 7. Совместимость + +SDK обязан поддерживать семантическое версионирование и публиковать +protocol_version. + +# 8. Рекомендации + +- Структурированное логирование +- Метрики Prometheus +- Health endpoint +- Graceful shutdown +- Автоматическое восстановление соединения + +## Следующий документ + +12_Security.md diff --git a/docs/spec-series/12_Security.md b/docs/spec-series/12_Security.md new file mode 100644 index 0000000..8b7cc85 --- /dev/null +++ b/docs/spec-series/12_Security.md @@ -0,0 +1,64 @@ +# Документ 12. Security + +## Назначение + +Определяет требования информационной безопасности платформы Agent +Control Center. + +# 1. Модель безопасности + +Основные принципы: - Security by Design - Least Privilege - Zero Trust - +Defense in Depth - Secure Defaults + +# 2. Аутентификация + +Поддерживается: - OAuth2/OIDC - SSO - MFA - Service Accounts - API Keys + +# 3. Авторизация + +Используются: - RBAC - ABAC (для расширенных сценариев) + +Роли: - Owner - Administrator - Architect - Developer - Operator - +Auditor - Viewer - Agent + +# 4. Управление секретами + +- хранение вне исходного кода; +- регулярная ротация; +- аудит использования; +- шифрование при хранении и передаче. + +# 5. Шифрование + +- TLS 1.3+ +- AES-256 для данных "на диске" +- Хэширование паролей Argon2id или bcrypt +- Управление ключами через KMS/HSM при наличии. + +# 6. Аудит + +Журналируются: - входы в систему; - изменения ролей; - операции с +секретами; - административные действия; - запуск и отмена Run. + +Журнал аудита неизменяем. + +# 7. Модель угроз + +Рассматривать: - Spoofing - Tampering - Repudiation - Information +Disclosure - Denial of Service - Elevation of Privilege + +# 8. Соответствие + +Архитектура должна допускать соответствие: - ISO/IEC 27001 - SOC 2 - +GDPR (при необходимости) - внутренним политикам организации. + +# 9. Реагирование + +- обнаружение инцидентов; +- оповещение; +- блокировка скомпрометированных учетных данных; +- журнал расследования. + +## Следующий документ + +13_Observability.md diff --git a/docs/spec-series/13_Observability.md b/docs/spec-series/13_Observability.md new file mode 100644 index 0000000..1f50be3 --- /dev/null +++ b/docs/spec-series/13_Observability.md @@ -0,0 +1,80 @@ +# Документ 13. Observability + +## Назначение + +Документ определяет требования к наблюдаемости (Observability) платформы +Agent Control Center: логирование, метрики, распределённую трассировку, +мониторинг и эксплуатационные показатели. + +# 1. Цели + +- Быстрое обнаружение проблем. +- Сокращение MTTR. +- Полная трассировка выполнения Run. +- Контроль производительности компонентов. +- Возможность анализа инцидентов. + +# 2. Логирование + +Все сервисы должны использовать структурированные JSON-логи. + +Минимальные поля: - timestamp - level - service - request_id - +correlation_id - run_id - user_id - message + +Уровни: - DEBUG - INFO - WARNING - ERROR - CRITICAL + +# 3. Метрики + +Экспорт через Prometheus. + +Основные метрики: - HTTP Requests/sec - Error Rate - P95/P99 Latency - +Active Runs - Queue Length - Memory Usage - CPU Usage - Connector +Availability + +# 4. Distributed Tracing + +Поддержка OpenTelemetry. + +Каждый запрос должен формировать Trace ID и Span ID. + +Трассируются: - API - Event Bus - Scheduler - Agent Runtime - Connector +SDK - Database + +# 5. Health Checks + +Обязательные endpoints: + +- /health/live +- /health/ready +- /metrics + +Проверяются: - PostgreSQL - Event Bus - Object Storage - AI Provider - +Memory Service + +# 6. Alerting + +Рекомендуемые правила: + +- высокая доля ошибок; +- рост задержек; +- отсутствие heartbeat; +- переполнение очередей; +- исчерпание дискового пространства. + +# 7. SLI / SLO + +Пример целевых значений: + +- API Availability ≥ 99.9% +- P95 API Latency \< 500 ms +- Error Rate \< 1% +- Recovery Time \< 15 min + +# 8. Эксплуатация + +Все сервисы должны поддерживать: - graceful shutdown; - readiness +probe; - liveness probe; - безопасный перезапуск. + +## Следующий документ + +14_Testing_Strategy.md diff --git a/docs/spec-series/ADR-DRAFTS.md b/docs/spec-series/ADR-DRAFTS.md new file mode 100644 index 0000000..d4a5af4 --- /dev/null +++ b/docs/spec-series/ADR-DRAFTS.md @@ -0,0 +1,157 @@ +# Черновики ADR по критичным пунктам из IMPROVEMENT-PROPOSALS.md + +**Статус:** proposed (не accepted). Формат — из `docs/OPEN-QUESTIONS.md` (Decision template). Каждый ADR ссылается на конкретный пункт `IMPROVEMENT-PROPOSALS.md` и, если принят, должен быть перенесён в `docs/adr/` с финальным номером, а также отражён в `docs/OPEN-QUESTIONS.md` и `docs/TRACEABILITY.md`. + +Отбор: сюда вынесены только пункты, которые (а) влияют на trust boundary/security invariants, либо (б) блокируют другие решения, либо (в) дешевле закрыть на уровне ADR сейчас, чем переделывать после M1. + +--- + +## ADR-101: Emergency stop (workspace/tenant-wide kill switch) + +``` +Status: proposed +Date: 2026-07-20 +Owners: Security, Architecture +Related: A1 (IMPROVEMENT-PROPOSALS.md), FR-RUN-005, NFR-REL-004, §11 State invariants +``` + +### Context +FR-RUN-005 определяет cancel только на уровне одного Attempt. При compromised skill, runaway agent или инциденте безопасности нет способа мгновенно остановить **все** active runs в workspace/tenant. Это блокирует раздел рисков E ("Runaway cost") и создаёт разрыв между заявленным Emergency access у Organization Owner (§2 SPECIFICATION) и реальной механикой. + +### Options and evidence +1. **Broadcast cancel** — Control Plane итерирует все active Attempt в scope и шлёт обычный cancel каждому. Просто, но не atomic: часть runs может успеть создать side effect до получения команды; нет единого "замка" против нового dispatch. +2. **Scope-level dispatch lock + broadcast cancel** — перед broadcast'ом сначала атомарно переводится workspace/tenant в `dispatch_locked`, что немедленно блокирует любой новый `start`/`resume`/`handoff`-dispatch на уровне Run Orchestrator, затем существующие Attempt получают priority cancel с укороченным grace period. +3. **Connector-level circuit breaker** — Emergency stop транслируется в команду самому Connector "отклоняй все новые native calls", независимо от Control Plane state — сильнее защищает от split-brain (Control Plane недоступен), но требует доверенного канала Control Plane → Connector даже в degraded state. + +### Decision (draft) +Рекомендуется комбинация 2+3: dispatch-lock на Control Plane для немедленной остановки нового dispatch + отдельная asynchronous команда Connector на circuit-breaker уровень, чтобы emergency stop работал даже при частичной недоступности Control Plane. Финальный выбор — за Architecture с учётом ADR-005 (Connector sandbox). + +### Security/privacy/operational consequences +- Требует нового state `dispatch_locked` на уровне workspace/tenant, отдельного от run-level state machine (§11 инвариантов не меняет, но добавляет). +- Emergency stop должен сам быть доступен ограниченному набору ролей (Org Owner, возможно Workspace Admin) и логироваться как security event высшего severity — пересекается с ADR-102 (break-glass). +- Ложное срабатывание (случайный emergency stop) само по себе operational risk — нужен confirmation step, но не настолько тяжёлый, чтобы блокировать реальный инцидент. + +### Migration and rollback +Аддитивно: новое requirement (**FR-SAF-001**), не меняет существующие FR-RUN-*. Rollback — просто не активировать функцию до готовности Connector circuit-breaker команды. + +### Validation +Требуется новый acceptance test: N параллельных runs в workspace останавливаются за bounded time (например ≤10с for dispatch-lock, отдельный SLA для полного cancel всех Attempt), без "zombie" writer lease (перепроверка NFR-REL-004). + +--- + +## ADR-102: Break-glass emergency access + +``` +Status: proposed +Date: 2026-07-20 +Owners: Security, Product +Related: H1 (IMPROVEMENT-PROPOSALS.md), FR-IAM-003/004, §2 роль Organization Owner +``` + +### Context +"Emergency access" заявлена как задача Organization Owner в таблице ролей §2, но нет FR, описывающего механику: обходит ли она обычный RBAC/ABAC-чек, есть ли TTL, обязателен ли post-use review. Сейчас это единственная роль-привилегия в спецификации без acceptance test. + +### Options and evidence +1. **Отдельный "break-glass" режим с explicit активацией** — Owner явно инициирует, система выдаёт time-boxed elevated token (например 30–60 минут), каждое действие в этом окне помечается `via_break_glass=true` в audit с severity=critical, окно нельзя продлить без повторной явной активации. +2. **Постоянно доступный "super-admin" bypass** — проще реализовать, но противоречит уже принятому в спецификации принципу (FR-IAM-003: каждая операция проходит RBAC+ABAC) и создаёт постоянный high-value target. +3. **Break-glass только через отдельный break-glass credential (не текущая сессия Owner)** — сильнее изолирует (компрометация обычной сессии Owner не даёт break-glass), но добавляет operational overhead (где хранится break-glass credential, как ротируется). + +### Decision (draft) +Рекомендуется вариант 1 как MVP-baseline, с явной пометкой, что вариант 3 (отдельный credential) рассматривается post-MVP по мере роста compliance требований (пересекается с OQ-019 compliance scope). + +### Security/privacy/operational consequences +- Every break-glass activation генерирует немедленный alert (не только audit-запись) ответственным ролям — иначе "emergency access" не будет обнаружен вовремя при злоупотреблении. +- Обязательный post-use review другим Admin/Owner (dual control post-factum, раз нельзя dual-control в моменте инцидента) — открытая запись до review блокирует, например, следующий billing cycle report или явно видна как "unreviewed break-glass" в security dashboard. +- Неиспользуемое право break-glass не должно молча "протухать" без напоминания — иначе Owner забывает, что оно вообще есть. + +### Migration and rollback +Новое **FR-IAM-006**; не меняет существующие IAM-инварианты, но требует добавить строку в §11 ("break-glass action не переживает TTL и обязана иметь compensating review record"). + +### Validation +Integration test: активация break-glass вне scope политики отклоняется; активация в рамках политики создаёт TTL-bounded token и alert; истечение TTL отзывает права без ручного действия; отсутствие post-use review видно в dashboard спустя configurable порог. + +--- + +## ADR-103: Модель классификации данных (data classification taxonomy) + +``` +Status: proposed +Date: 2026-07-20 +Owners: Security, Legal +Related: B1 (IMPROVEMENT-PROPOSALS.md), OQ-007, FR-PRJ-005 (sensitivity), FR-MEM-001 (sensitivity), NFR-SEC-004/007 +``` + +### Context +Четыре и более требования ссылаются на поле `sensitivity`/`classification`, но нигде не зафиксирован сам перечень допустимых значений и правил обращения с каждым. Без этого ADR реализация FR-PRJ-005/FR-MEM-001 будет придумывать enum ad hoc на этапе кода, что прямо противоречит "Definition of Ready" §15 SPECIFICATION ("входы... определены"). + +### Options and evidence +1. **Минимальная 3-уровневая модель**: `internal` / `confidential` / `restricted`. Просто, быстро внедряется, но не разделяет PII/regulated data как отдельный класс. +2. **4–5-уровневая модель** (например `public / internal / confidential / restricted / regulated`), где `regulated` явно триггерит дополнительные controls (data residency, DSAR eligibility) — точнее отражает связь с OQ-007/compliance, но требует явно определить, что относится к `regulated` до M1. +3. **Multi-dimensional tagging** (sensitivity level + data category: PII/financial/credentials/source-code) вместо одного enum — наиболее гибко, но заметно увеличивает сложность ACL/redaction логики на старте MVP. + +### Decision (draft) +Рекомендуется вариант 2 как MVP-baseline (закрывает большинство сценариев из FR-MEM-001/FR-PRJ-005 без чрезмерной сложности), с явным резервированием варианта 3 как post-MVP расширения, если PII-специфичные требования (DSAR, право на удаление) потребуют более гранулярного тэгирования. + +### Security/privacy/operational consequences +- `regulated` класс должен явно требовать более строгий default retention/export-контроль (пересекается с NFR-OPS-004, NFR-SEC-007). +- Неизвестный/незаданный класс не должен дефолтиться в `internal` молча — отсутствие классификации это отдельная, более строгая ветка (например блокирует indexing до классификации), а не "тихий default". + +### Migration and rollback +Требует нового документа `docs/DATA-CLASSIFICATION.md` (раздел C IMPROVEMENT-PROPOSALS.md) и явного enum, на который затем ссылаются существующие FR без изменения их ID. + +### Validation +Structural test (расширение `validate_spec.py`): каждое упоминание `sensitivity`/`classification` в SPECIFICATION.md резолвится к одному из объявленных в DATA-CLASSIFICATION.md значений. + +--- + +## ADR-104: Egress allowlist на уровне Agent (не только Connector) + +``` +Status: proposed +Date: 2026-07-20 +Owners: Security, Architecture +Related: G3 (IMPROVEMENT-PROPOSALS.md), FR-CON-004, §4.1 ARCHITECTURE trust boundary, ADR-005 (Connector sandbox, уже запланирован) +``` + +### Context +Connector как хост уже описан с explicit trust boundary (§4.1: только outbound, отдельные OS identities, redaction, spool). Но agent-specific network egress (какие внешние домены/IP конкретному agent разрешено вызывать через tools) не описан отдельно — сейчас предполагается, что весь egress, доступный Connector-хосту, доступен любому agent на нём, что избыточно широко относительно принципа least privilege, уже применённого к остальной системе (NFR-SEC-003 ASVS L2, §4.1 п.2 "минимальные права"). + +### Options and evidence +1. **Egress allowlist как часть Agent config** (аналогично `filesystem_scope` из FR-CON-004), enforced Connector-ом на уровне adapter process (например network namespace/firewall rule per agent process). +2. **Egress allowlist только на уровне Connector-хоста в целом** (текущее де-факто состояние) — минимум работы, но не масштабируется на multi-agent Connector хост с разными уровнями доверия к разным agent. +3. **Egress проверяется на уровне MCP/tool-declaration** (каждый MCP tool сам объявляет свой домен, Connector сверяет с allowlist per-tool, а не per-agent) — более гранулярно, но зависит от того, насколько MCP tools честно объявляют свои сетевые цели (недоверенный входной сигнал). + +### Decision (draft) +Рекомендуется вариант 1 как baseline с возможностью уточнения через вариант 3 там, где MCP tool capability позволяет декларативно объявить domain — то есть 1 как enforced fallback, 3 как более точный сигнал поверх него, никогда не единственный источник правды. + +### Security/privacy/operational consequences +Требует, чтобы ADR-005 (Connector sandbox baseline) явно включал network namespace/firewall enforcement per agent process, а не только filesystem/process isolation — стоит явно связать оба ADR при финализации ADR-005. + +### Migration and rollback +Новое **FR-CON-008**, аддитивно к FR-CON-004; rollback — allowlist по умолчанию "весь egress хоста" (текущее поведение), пока функция не готова, явно помечено как temporary weaker baseline в OPEN-QUESTIONS. + +### Validation +Adversarial test: agent с ограниченным allowlist не может инициировать соединение к произвольному внешнему домену через declared tool, попытка логируется как security event. + +--- + +## Дополнения к `docs/OPEN-QUESTIONS.md` (для внесения при принятии соответствующих ADR) + +| ID | Severity | Решение | Владелец | Deadline | Связано с | +|---|---|---|---|---|---| +| OQ-019 | BLOCKER | Compliance scope и юрисдикция (GDPR/CCPA/иное) | Security/Legal | До M1 | B2 | +| OQ-020 | MAJOR | Ownership/лицензия контента, сгенерированного агентами | Owner/Legal | До external distribution | G10 | +| OQ-021 | BLOCKER | Механика emergency stop (scope, кто активирует, circuit-breaker vs broadcast) | Security/Architecture | До M2 | A1 / ADR-101 | +| OQ-022 | BLOCKER | Break-glass access model (TTL, credential изоляция, review) | Security/Product | До M1 | H1 / ADR-102 | +| OQ-023 | BLOCKER | Таксономия классификации данных | Security/Legal | До M1 | B1 / ADR-103 | +| OQ-024 | MAJOR | Egress allowlist model для agent-level network scope | Security/Architecture | До M2 | G3 / ADR-104 | +| OQ-025 | MAJOR | Модель машинного доступа для внешних интеграций (API keys/OAuth) | Architecture/Security | До M3 | H4 | + +--- + +## Как использовать этот документ + +1. Каждый ADR здесь — draft для обсуждения, не решение. "Decision (draft)" — рекомендация автора ревью, не утверждённый выбор. +2. При принятии: перенести в `docs/adr/ADR-NNN-slug.md` с финальным номером (после того как заведена сама папка `docs/adr/`, см. раздел C `IMPROVEMENT-PROPOSALS.md`), проставить `Status: accepted`, добавить соответствующие FR/NFR/AT в `SPECIFICATION.md` и строки в `TRACEABILITY.md`. +3. Добавить соответствующие строки в `docs/OPEN-QUESTIONS.md` из таблицы выше (с исправленной опечаткой) и закрыть их по мере принятия ADR. +4. Прогнать `scripts/validate_spec.py` (и, если принято предложение F из `IMPROVEMENT-PROPOSALS.md`, — расширенную версию с проверкой traceability) перед commit. diff --git a/docs/spec-series/IMPROVEMENT-PROPOSALS.md b/docs/spec-series/IMPROVEMENT-PROPOSALS.md new file mode 100644 index 0000000..c00c009 --- /dev/null +++ b/docs/spec-series/IMPROVEMENT-PROPOSALS.md @@ -0,0 +1,230 @@ +# Предложения по доработке: Agent Control Center + +| Поле | Значение | +|---|---| +| Тип документа | Non-normative review — предложения к `SPECIFICATION.md` v0.1.0-draft | +| Дата | 2026-07-20 | +| Статус | Draft для рассмотрения владельцем продукта/архитектуры | +| Действие | Ничего из этого не является утверждённым требованием. Принятие пункта требует: присвоить ID (FR-.../NFR-...), добавить AT, обновить `TRACEABILITY.md`, при необходимости завести ADR/OQ | + +## 0. Общая оценка + +Спецификация уже необычно зрелая для draft-стадии: закрытый список ролей, явные non-goals, DAG-инварианты, отдельный AAP-контракт с capability negotiation, checkpoint/handoff вместо "магического" переноса сессии, разделение measured/estimated/unknown usage, машинно проверяемая traceability (`validate_spec.py`), запрет на реализацию до G0/G1. Это редко встречается в спецификациях такого размера. Предложения ниже — это **пробелы и усиления**, а не переработка существующей структуры. + +Категории: (A) отсутствующие функциональные возможности, (B) недостающие нефункциональные гарантии, (C) процессные/репозиторные документы, (D) уточнения к существующим требованиям, (E) риски, которые пока не названы, (G) второй проход по пробелам, (H) третий проход по пробелам. + +--- + +## A. Функциональные пробелы + +### A1. Emergency stop / global kill switch +Сейчас есть `cancel` на уровне одного Attempt (FR-RUN-005). Нет способа для Workspace Admin/Org Owner **мгновенно остановить все runs** в workspace/tenant (инцидент безопасности, скомпрометированный skill, runaway cost). +- Предлагаемое требование: **FR-SAF-001** — Admin может выполнить workspace-wide emergency stop; все active Attempt получают cancel c приоритетной lease-инвалидацией; новый dispatch блокируется до explicit unlock; действие само пишется в audit с наивысшим severity. +- Acceptance: emergency stop останавливает N параллельных runs за bounded time и не оставляет "zombie" writer lease. + +### A2. Pre-dispatch cost/impact preview +Preview стоимости описан только для **handoff** (§8.2 п.5, FR-RUN-007). Для обычного старта run (FR-RUN-001) нет обязательного показа estimated cost/usage impact до dispatch. +- Предлагаемое: **FR-RUN-010** — перед стартом run с известным usage-provider показывается estimated cost/usage range (measured/estimated/unknown, как в FR-OPS-001); запуск с `unknown` cost требует explicit acknowledgement, если budget policy это требует. + +### A3. Параллельная работа нескольких агентов над одной задачей +Текущая модель — один writable Attempt на TaskRun (инвариант §11) и последовательный handoff. Нет описания сценария "агент А делает backend, агент Б — тесты, для одной задачи параллельно" (multi-agent collaboration), который часто нужен именно в "control center" для агентов. +- Предлагаемое: явно закрепить как **non-goal MVP** (если это осознанный выбор) в §1.2, либо добавить **FR-RUN-011** (post-MVP) для параллельных sibling-Attempt с разделяемым read-only checkpoint и явным merge-review перед объединением в задачу. Сейчас это просто не упомянуто ни как non-goal, ни как roadmap-пункт — двусмысленность стоит закрыть явно. + +### A4. Dry-run / plan-only режим +Нет режима, где агент строит план и список предполагаемых действий (особенно destructive: git push, file delete, external API call) **без исполнения**, для approval до реального запуска. +- Предлагаемое: **FR-RUN-012** — если capability `plan_mode` присутствует в handshake, run может стартовать в `plan_only`; approval экрана показывает предполагаемые действия; переход в исполнение — отдельная explicit команда. + +### A5. Данные для чарджбэка/финансового учёта +OQ-012 фиксирует нормализацию usage/cost как открытый вопрос, но нет функционального требования на **cost attribution по project/workspace для финансовой отчётности** (не просто UI usage summary, а экспортируемый ledger). +- Предлагаемое: **FR-OPS-006** — Usage Service агрегирует normalized cost по project/workspace/agent за период и предоставляет exportable ledger с explicit confidence per entry; несопоставимые единицы не сворачиваются в одну сумму (согласуется с §11 инвариантом). + +### A6. Webhook-безопасность для Git-интеграции +FR-PRJ-006 упоминает webhook replay protection, но не описывает **verification механизм** (HMAC signature, source IP allowlist, timestamp window) как отдельное требование — сейчас это спрятано в "edge cases" одной строки. +- Предлагаемое: расширить FR-PRJ-006 или добавить **NFR-SEC-009** — входящие webhook проверяются подписью провайдера и временным окном до постановки в очередь; невалидная подпись логируется как security event, не как обычная ошибка. + +### A7. Explicit "definition of done" / task templates +Task хранит acceptance criteria как свободный текст (FR-PRJ-002). Нет structured template по типу задачи (bug/feature/research), что снижает единообразие качества handoff (FR-RUN-006 checkpoint зависит от чётких criteria). +- Предлагаемое: **FR-PRJ-007** (P1) — Project может определить task templates с обязательными полями acceptance criteria; создание задачи из template валидирует заполненность полей перед переводом в runnable-статус. + +### A8. Приостановка/пауза run без cancel +Есть только running → cancelling → cancelled и checkpoint/handoff. Нет "мягкой" паузы (agent просто ждёт, ресурсы не освобождаются, но и работа не идёт) для случаев "я сейчас проверю approval вручную, не хочу терять контекст, но и не хочу formal handoff". +- Предлагаемое: рассмотреть **FR-RUN-013** (P2) — pause/resume в рамках одного Attempt, если capability поддерживает; иначе явно закрыть вопрос как non-goal, чтобы не осталось implicit ожидания у пользователей. + +--- + +## B. Нефункциональные пробелы + +### B1. Классификация данных не определена +OQ-007 помечает "classification/retention" как blocker, но нигде в репозитории нет самого перечня классов (public/internal/confidential/restricted/secret) и их дефолтных правил обращения — на них ссылаются NFR-SEC-004/007, FR-PRJ-005 (`sensitivity`), FR-MEM-001 (`sensitivity`), но словарь классов не задан. +- Предлагаемое: новый документ `docs/DATA-CLASSIFICATION.md` (см. раздел C) + **NFR-SEC-009** — каждая сущность с полем sensitivity/classification обязана резолвиться к одному из объявленных enum-классов; неизвестный класс блокирует запись, а не дефолтится в "internal". + +### B2. Compliance framework не назван +Много "privacy/legal hold" ссылок (NFR-SEC-007, NFR-OPS-004), но нет явной привязки к конкретным режимам (GDPR/CCPA/аналог для целевого рынка), хотя это определяет DSAR-сроки, data residency и right-to-erasure semantics. +- Предлагаемое: добавить строку в §5 "Предпосылки" — целевой compliance scope определяется ADR до M1 (можно завести **OQ-019 BLOCKER** "Compliance scope и juridiction"). + +### B3. Целостность audit log не гарантирована криптографически +FR-OPS-004/NFR-OPS требуют "append-only" и "gap/tamper observable", но нет требования к **hash-chaining или WORM-хранилищу**, что обычно ожидается от audit trail в security-чувствительной системе такого рода. +- Предлагаемое: усилить NFR-SEC (например **NFR-SEC-010**) — audit events образуют verifiable hash chain или пишутся в WORM storage; периодическая integrity-проверка chain — отдельная runbook-процедура. + +### B4. Локализация как архитектурное, а не только продуктовое решение +OQ-017 — MINOR, "branding/localization". Но i18n-архитектура (строки, RTL, форматы дат/чисел, локализация error-messages из §9 "localized-safe message") влияет на API contract уже в MVP, не только на бренд. +- Предлагаемое: поднять степень серьёзности до **MAJOR** и явно связать с §9 (error envelope) и NFR-UX; либо явно зафиксировать "MVP UI — только английский/русский, error message localization post-MVP" как non-goal в §1.2, чтоббы не было implicit ожиданий. + +### B5. Red-teaming/adversarial testing cadence не определена +NFR-SEC-005 требует, чтобы prompt injection не повышал privilege, есть AT с "injection corpus". Но нет regular cadence (например quarterly red-team на новые skill/adapter версии) — только "release gate"-проверка. +- Предлагаемое: добавить в **NFR-OPS-005** (или новый NFR-SEC-011) периодический (например quarterly) adversarial review нового adapter/skill класса, не только at release. + +### B6. Доступность (accessibility) вне Web +NFR-UX-001 требует WCAG 2.2 AA только для Web, "native wrappers сохраняют semantics" — расплывчато для Desktop/Android, где нет измеримого acceptance theshold. +- Предлагаемое: уточнить NFR-UX-001 explicit acceptance для Desktop (платформенные accessibility API: UI Automation/NSAccessibility) и Android (TalkBack) с отдельным AT, а не общей фразой "сохраняют semantics". + +### B7. SLA на approval latency +FR-RUN-004/IAM-004 описывают механику approval, но нет требования к **времени ожидания и эскалации** (кто оповещается, если approval висит N минут на критичном run) — это либо в Notification Service, либо теряется. +- Предлагаемое: **NFR-OPS-006** — approval requests старше configurable threshold эскалируются дополнительному approver/on-call через notification; run остаётся blocked, но статус ожидания видим всем клиентам. + +--- + +## C. Документы, которых не хватает в репозитории + +| Файл | Зачем | Приоритет | +|---|---|---| +| `SECURITY.md` | Политика раскрытия уязвимостей (для приватного репо это тоже нужно на будущее external distribution по OQ-010); канал контакта, expected response time | до publish/G0 | +| `docs/DATA-CLASSIFICATION.md` | Перечень классов чувствительности и правил (см. B1), на который ссылаются уже 4+ FR/NFR | до M1 (закрывает OQ-007) | +| `docs/GLOSSARY.md` | §3 SPECIFICATION уже даёт термины, но по мере роста ADR/OQ словарь стоит вынести отдельно и валидировать, что новые термины не вводятся без определения | опционально, снижает риск дрейфа терминологии | +| `CHANGELOG.md` | Версия документа сейчас меняется (0.1.0-draft), но нет истории причин изменений — при частых ADR это станет проблемой ревью | с первого ADR | +| `docs/adr/ADR-000-template.md` + папка `docs/adr/` | ARCHITECTURE.md §11 перечисляет 6 обязательных ADR, но нет папки/шаблона под них — сейчас только generic decision template живёт в `OPEN-QUESTIONS.md` | до M0 | +| `CODE_OF_CONDUCT.md` | Не критично для solo-owner, но нужно до появления внешних контрибьюторов (упомянуто OQ-010 "third-party redistribution") | до external distribution | + +--- + +## D. Уточнения к существующим требованиям + +1. **FR-CON-007 (staged upgrade)** — не сказано, что происходит с in-flight approval token при upgrade adapter mid-flight; стоит явно указать, что approval digest инвалидируется при смене adapter_version, а не молча переносится. +2. **FR-MEM-004 (Context Broker bounded bundle)** — "сокращает низший приоритет" не определяет, как приоритет назначается по умолчанию (recency? verification_state? explicit pin?). Стоит зафиксировать default ranking algorithm хотя бы на уровне принципа (например: verified > unverified, explicit pin > recency > semantic score), иначе это будет решаться ad hoc при реализации. +3. **NFR-PERF-004 (context bundle p95 ≤3с)** — не указано поведение при превышении: жёсткий timeout с `unknown`-статусом или деградация до меньшего bundle. Стоит уточнить, что превышение timeout эквивалентно declared omission (согласуется с FR-MEM-004), а не silent failure. +4. **FR-SKL-002 (reviewer видит diff)** — "author self-approval запрещается policy" сформулирован как policy-требование, но не как system-enforced invariant в §11 (State invariants). Учитывая, что там уже есть похожий принцип для FR-IAM-004, стоит добавить строку в §11: "Skill version не может быть approved тем же actor, кто её опубликовал". +5. **§8.4 Offline/conflicts** — "Safe task/wiki draft edits" не перечисляет explicit whitelist того, что считается safe; в NFR-PORT-003 упомянуто "explicitly safe operations", но сам список не зафиксирован нигде как artifact — это ровно то, что должно быть в OQ-011, но сейчас там просто "exact allowlist TBD". Стоит добавить хотя бы starter-список (например: task description draft edit, comment draft, wiki draft paragraph) как non-blocking baseline, который OQ-011 может сузить/расширить, а не оставлять полностью пустым до M5. +6. **Capacity targets (§7.3)** — "10 000 000 run events... на deployment" — не указано ожидаемое **распределение по времени** (burst vs steady state), что важно для NFR-PERF-002 (reconnect catch-up 10k events ≤30с). Стоит явно указать, относится ли 10k к одному run или ко всему reconnect-объёму сразу после incident на нескольких runs. + +--- + +## E. Риски, которых нет в таблице §14 + +| Риск | Влияние | Предлагаемая мера | +|---|---|---| +| Runaway cost от зацикленного агента без hard stop (см. A1/A2) | Финансовый/репутационный ущерб | Emergency stop + pre-dispatch cost preview + hard budget ceiling независимо от soft/estimated confidence | +| Скрытый vendor lock-in через AAP-специфичные vendor_extension поля, на которые начинает молча полагаться UI | Потеря portability между runtime | Explicit lint/CI правило: UI core не может рендерить `vendor_extension` как first-class control без явной feature-flag маркировки как non-portable | +| Drift между `TRACEABILITY.md` и реальным содержимым SPECIFICATION.md при ручных правках | Ложное чувство полноты покрытия | Расширить `validate_spec.py`: проверять, что каждый FR/NFR ID из SPECIFICATION.md встречается хотя бы один раз в TRACEABILITY.md (сейчас скрипт не читает TRACEABILITY.md вообще) | +| Одна доминирующая роль (Org Owner) одновременно управляет billing, emergency access и retention — недостаточная segregation of duties | Insider risk / single point of failure для approvals | Явно рассмотреть в OQ-009 dual-control для emergency access/retention override, не только для "destructive actions" в общем смысле | + +--- + +## F. Небольшое расширение `validate_spec.py` (предложение, не реализовано) + +Валидатор уже проверяет FR/NFR ↔ AT соответствие внутри `SPECIFICATION.md`, но **не** проверяет: +1. что каждый ID из `SPECIFICATION.md` действительно упомянут в `TRACEABILITY.md` (см. риск в разделе E); +2. что каждый `OQ-###` из `OPEN-QUESTIONS.md` с severity `BLOCKER` привязан хотя бы к одному `FR-`/`NFR-`/ADR упоминанию где-либо в `docs/`; +3. что новые файлы из раздела C (если приняты) присутствуют, аналогично текущему `REQUIRED_FILES`. + +Это усиление логично сделать одним PR вместе с принятием любого пункта из разделов A–D, чтобы traceability не деградировала по мере роста количества требований. + +**Проверено на практике:** черновик такого расширенного валидатора (`validate_spec_extended_DRAFT.py`, приложен отдельным файлом) уже сейчас, без единой правки в `SPECIFICATION.md`, находит реальный дрейф в текущем репозитории: +- 15 NFR/FR-ID (`FR-OPS-003`, весь блок `NFR-OPS-*`, `NFR-PERF-*`, `NFR-REL-*`, `NFR-PORT-004`) присутствуют в `SPECIFICATION.md`, но не упомянуты явно в `TRACEABILITY.md` — то есть traceability matrix уже сейчас не 1:1 с требованиями, хотя её статус заявлен как "запрос → нормативные требования". +- 8 `BLOCKER`-вопросов (`OQ-001, 002, 003, 006, 007, 008, 009, 010`) нигде за пределами `OPEN-QUESTIONS.md` не упоминаются — ни в `SPECIFICATION.md`, ни в `ARCHITECTURE.md`, ни в `TRACEABILITY.md`, что делает их источник в спецификации непрослеживаемым: неясно, какая конкретно строка требований зависит от их закрытия. + +Это не гипотетический риск из раздела E — это уже так в текущей версии 0.1.0-draft, и стоит закрыть до G1. + +--- + +## G. Второй проход: ещё не названные пробелы + +### G1. Session recording / run replay для расследований +Audit (FR-OPS-004) фиксирует action/target/result, но нет требования к **полному воспроизведению** того, что именно видел агент в конкретном run (порядок событий, tool calls, approvals) для post-incident разбора — не как "лог одной строкой", а как replay в UI, эквивалентный тому, что видел оператор в реальном времени. +- Предлагаемое: **FR-OPS-007** — терминальный/активный run воспроизводим в Run Console read-only режиме из сохранённых `RunEvent` без повторного обращения к runtime; append-only инвариант уже задан §10, здесь нужен именно UI/API acceptance на replay. + +### G2. Rate limiting и anti-abuse для самого Control Plane API +NFR-PERF задаёт целевые p95, FR-OPS-002 — budget policy на agent usage. Но нет требования по **защите API Gateway от abuse** (brute-force login, scraping через list endpoints, chatty polling клиента) независимо от provider-квот. +- Предлагаемое: **NFR-SEC-012** — per-actor/per-IP rate limiting на auth и list/search endpoints с 429 и `retryable`, независимо от agent budget policy; порог конфигурируем per tenant tier. + +### G3. Egress-scope агента отдельно от Connector-scope +§4.1 ARCHITECTURE описывает trust boundary Connector (no secrets, redaction, sandbox), а capability `filesystem_scope` упомянута в §4.2. Но нет отдельного явного требования на **network egress allowlist на уровне конкретного Agent**, а не только Connector-хоста в целом — сейчас неверно настроенный/скомпрометированный агент может использовать любой egress, доступный Connector. +- Предлагаемое: расширить FR-CON-004 или добавить **FR-CON-008** — Agent конфигурация включает egress allowlist (domains/IP ranges), Connector enforces его на уровне adapter process, а не полагается на agent-level "честность" tool-вызовов. + +### G4. Провайдерская zero-retention / no-training гарантия как явный критерий выбора adapter +`RESEARCH.md` описывает интеграционные поверхности, но не фиксирует, обучается ли провайдер на переданных данных / retention policy провайдера — это важно для тенанта с чувствительными данными и должно влиять на выбор adapter в OQ-005. +- Предлагаемое: добавить колонку/пункт в `RESEARCH.md` "data retention / training use по провайдеру, дата проверки" и явное требование **NFR-SEC-013** — Agent registration отображает известный retention/training-статус провайдера (known/unknown), `unknown` не трактуется как "no training". + +### G5. Версионирование и аудит system prompt / инструкций агента +Skill версионируется (FR-SKL-*), но собственные instructions/system prompt конкретного Agent (не skill, а базовая конфигурация "как вести себя") нигде явно не версионируются и не проходят review — это тот же класс риска (poisoned instructions), что и skills, но без контроля. +- Предлагаемое: **FR-CON-009** — agent instructions/system prompt хранятся как immutable versioned config наравне с остальным agent config (FR-CON-004), изменение создаёт новую версию с diff, видимым Project Lead/Admin. + +### G6. Explicit человеческий takeover активного run +Есть approve/deny и cancel, но нет "взять управление вручную" — оператор временно перехватывает conversation/terminal конкретного Attempt, не создавая handoff и не отменяя run (частый сценарий: агент застрял, но контекст терять не хочется). +- Предлагаемое: **FR-RUN-014** (P1/P2) — если capability поддерживает interactive intervention, оператор может отправить direct message в активный Attempt вне обычного conversation flow, помечается как human-injected в audit/timeline. + +### G7. Outbound webhooks / события для внешних систем +Notification Service (§3 ARCHITECTURE) — только in-app/push/email. Нет исходящего webhook/интеграции с внешними системами (Slack/PagerDuty/generic HTTP) для critical events (approval needed, run failed, budget exceeded) — обычная потребность control-plane продукта такого рода. +- Предлагаемое: **FR-OPS-008** (P1, может быть post-MVP) — tenant может настроить outbound webhook subscription на подмножество событий с HMAC-подписью исходящего payload и retry/backoff; секреты webhook-получателя хранятся как reference, не в конфиге открытым текстом. + +### G8. Deprecation/sunset policy для adapters и AAP версий +§9 ARCHITECTURE описывает N-1 совместимость клиент/сервер, но нет аналогичной политики для **adapter/AAP версий**, когда vendor discontinues старую версию API/CLI раньше, чем ACC успевает мигрировать. +- Предлагаемое: добавить в §11 ARCHITECTURE явную политику: adapter version получает `deprecated` статус с обязательным migration window до `unsupported`; runs на deprecated adapter показывают предупреждение, а не просто продолжают работать до внезапного отказа. + +### G9. Демо/seed-данные и staging tenant +Delivery plan (§13 SPECIFICATION) не упоминает отдельный staging/sandbox tenant для тестирования upgrade Connector/adapter или демонстрации продукта без риска для production данных. +- Предлагаемое: **NFR-OPS-007** — deployment профиль поддерживает изолированный non-production tenant с synthetic seed-данными для staged upgrade validation перед production rollout (согласуется с "staged, signed, rollback-capable" из §9 ARCHITECTURE). + +### G10. IP-собственность artifacts, сгенерированных агентом +Ни одно требование не фиксирует, кому принадлежит контент, сгенерированный AI Agent (код, wiki-страницы, artifacts) — это скорее legal/OQ-вопрос, чем FR, но сейчас не упомянут вообще, а он напрямую завязан на OQ-010 (license/business model). +- Предлагаемое: добавить **OQ-020 (MAJOR)** — "Ownership/license сгенерированного агентами контента" с owner Legal, deadline до external distribution. + +--- + +## H. Третий проход: ещё не названные пробелы + +### H1. Break-glass emergency access — процедура, а не только роль +В §2 у Organization Owner заявлена "emergency access", но нигде не описано **как** он ей пользуется: обходит ли она RBAC/ABAC, логируется ли отдельно, есть ли time-boxing и обязательный post-use review. Сейчас это просто слово в таблице ролей. +- Предлагаемое: **FR-IAM-006** — break-glass доступ активируется explicit действием с ограниченным TTL, генерирует audit event высшего severity немедленно (не post-factum), и требует обязательного review другим Admin/Owner после использования; сам факт наличия неиспользованного break-glass доступа виден в security dashboard. + +### H2. Конфликт "policy заблокировала — человек хочет override" +FR-OPS-002 (budget) и общий approval flow подразумевают, что policy может заблокировать действие. Не описано, может ли уполномоченный человек **осознанно обойти** policy-блок (emergency override) и как это отличается от обычного approval — сейчас неясно, blocked означает "жёстко нельзя" или "нужен approval". +- Предлагаемое: уточнить в FR-OPS-002/FR-IAM-004, что policy-block и approval-required — разные состояния; override policy-block (не approval) требует отдельного явно более высокого права и создаёт audit-запись с пометкой "policy overridden by ", отличимую от обычного approval. + +### H3. Приватность staging/demo данных +G9 предложил staging tenant с synthetic-данными, но не сказано explicit, что **production данные не могут копироваться** в staging/demo без anonymization — иначе staging тихо становится вторым local production copy с более слабыми контролами. +- Предлагаемое: усилить NFR-OPS-007 (или новый NFR-SEC-014) — перенос данных production → non-production запрещён без документированной anonymization/synthetic-generation процедуры; сам перенос — auditable action. + +### H4. Программный доступ для внешних интеграций (developer API keys / OAuth) +Весь §9 API baseline описан в терминах клиентских сессий (device session, refresh credential). Нет отдельной модели для **машинного доступа третьих сторон** (CI pipeline дергает ACC API, внешний BI дергает Usage Service) — другая identity-модель, чем DeviceSession, и её просто нет. +- Предлагаемое: **FR-IAM-007** (P1) — tenant может выпускать scoped API keys/OAuth client credentials для service-to-service доступа, с собственным rate limit, expiry и revocation, отдельно от DeviceSession/refresh flow. + +### H5. Теневой (shadow) режим для новой версии adapter +FR-CON-007 покрывает staged upgrade с drain/rollback, но это переключение "было/стало". Нет режима, где новая версия adapter **параллельно** обрабатывает те же входы без реального effect (dry validation на реальном трафике) перед тем, как ей начинают доверять реальные commands. +- Предлагаемое: **FR-CON-010** (P2) — новая adapter version может быть активирована в shadow mode: получает copies команд, публикует события в отдельный non-authoritative канал для сравнения с текущей активной версией, не исполняя реальных side-effect действий. + +### H6. Внешняя status-страница инцидентов +NFR-OPS-002 покрывает alerts на on-call. Нет ничего про **внешнюю коммуникацию с тенантами** во время инцидента (status page, incident timeline, post-mortem publication) — обычно ожидаемая часть Operations для B2B control-plane продукта. +- Предлагаемое: **NFR-OPS-008** — production profile поддерживает публичный/tenant-facing status component с историей инцидентов и связкой к внутренним SLI (NFR-REL-001), без утечки internal diagnostic данных. + +### H7. Explicit единица версионирования самого AAP-протокола отдельно от adapter +§4.2 ARCHITECTURE вводит `schema_version` в envelope, но не описывает **политику эволюции самого AAP** (какие изменения minor/patch, какие требуют новой major-версии, сколько версий Connector Gateway обязан поддерживать одновременно) — это отдельная ось от "adapter version" (G8) и от "N-1 client/server" (§9). +- Предлагаемое: добавить в §11 ARCHITECTURE явную SemVer-политику для AAP schema с указанием, сколько major-версий Gateway поддерживает параллельно, и что breaking AAP change требует того же migration-guide процесса, что и API (§9 SPECIFICATION). + +### H8. Доверие к самоотчётной уверенности агента в checkpoint +FR-RUN-006 требует "verified facts" в checkpoint, FR-MEM-005 разделяет verified/unverified для memory. Но для checkpoint не сказано explicit, как система отличает "агент сам сказал, что уверен" от "человек/policy подтвердили" — тот же класс проблемы, что unverified memory, но применительно к checkpoint-fact. +- Предлагаемое: уточнить FR-RUN-006 — каждый verified fact в checkpoint несёт то же поле `verification_state`/provenance, что и MemoryEntry (§7 ARCHITECTURE), а не отдельную непересекающуюся модель доверия. + +### H9. Лимиты и autoarchival для артефактов на масштабе +Capacity targets (§7.3) считают tasks/events/revisions, но не artifacts (объём object storage) и не описывают tiering (hot/cold) при росте — для 10 000 проектов с бинарными artifacts это может быть доминирующей cost-статьёй, не отражённой ни в одном NFR. +- Предлагаемое: добавить target в §7.3 (например размер object storage на deployment) и **NFR-OPS-009** — artifacts старше configurable порога переводятся в cold storage tier автоматически, доступ остаётся, но с иной latency SLA, явно отличной от NFR-PERF-001. + +--- + +## Как использовать этот документ + +Ничего здесь не превращается в требование автоматически. Рекомендуемый процесс: +1. Владелец продукта/архитектуры помечает принимаемые пункты. +2. Для каждого принятого пункта — присвоить финальный ID, вставить в `SPECIFICATION.md`/`ARCHITECTURE.md` в соответствующий раздел, добавить AT. +3. Обновить `docs/TRACEABILITY.md`. +4. Если пункт меняет security boundary/API/data model — завести ADR или пункт в `OPEN-QUESTIONS.md` по правилам `CONTRIBUTING.md`. +5. Прогнать `scripts/validate_spec.py` — PASS обязателен перед commit.