docs: серия спецификации (13 документов) + ADR-Drafts + Improvement Proposals

2026-07-20 19:10:35 +07:00 · 2026-07-20 19:10:35 +07:00 · 282e85808d
commit 282e85808d
parent f97afdc399
16 changed files with 1713 additions and 0 deletions
--- 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)
--- a/docs/spec-series/01_Executive_Summary.md
+++ 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
 ## Правила серии
 -   Каждый документ является самостоятельной частью общей спецификации.
 -   Все документы имеют сквозную нумерацию.
 -   После завершения серии документы могут быть объединены в единую
    спецификацию.
--- a/docs/spec-series/02_Vision_and_Scope.md
+++ 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
--- a/docs/spec-series/03_Functional_Requirements.md
+++ 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;
 -   тесты;
 -   критерии приемки.
--- a/docs/spec-series/04_Non_Functional_Requirements.md
+++ 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 должно иметь связь с: - архитектурными решениями; -
 тестами; - эксплуатационной документацией; - критериями приемки.
--- a/docs/spec-series/05_Domain_Model.md
+++ 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
--- a/docs/spec-series/06_Architecture_C4.md
+++ 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
--- a/docs/spec-series/07_Database_Design.md
+++ 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
--- a/docs/spec-series/08_API_Specification.md
+++ 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
--- a/docs/spec-series/09_Event_Bus.md
+++ 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
--- a/docs/spec-series/10_Agent_Protocol.md
+++ 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
--- a/docs/spec-series/11_Connector_SDK.md
+++ 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
--- a/docs/spec-series/12_Security.md
+++ 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
--- a/docs/spec-series/13_Observability.md
+++ 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
--- a/docs/spec-series/ADR-DRAFTS.md
+++ 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.
--- a/docs/spec-series/IMPROVEMENT-PROPOSALS.md
+++ 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 <actor>", отличимую от обычного 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.