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.