Добавлена спецификация и навыки для codex и kimi-code

openspec/specs/deployment/spec.md

@@ -0,0 +1,51 @@
+# Deployment
+
+## Purpose
+
+Определяет воспроизводимый запуск LWC в локальной или контейнерной среде, выбор физического робота или Webots и правила загрузки единой конфигурации.
+
+## Requirements
+
+### Requirement: Целевая платформа
+Система SHALL поддерживать нативный запуск на Ubuntu 24.04 с ROS 2 Jazzy и отдельный Docker-сценарий на совместимом Linux-хосте.
+
+#### Scenario: Локальная подготовка
+- **WHEN** пользователь запускает `cobot local-setup` на поддерживаемом хосте
+- **THEN** мастер проверяет зависимости ROS 2 и Webots и собирает workspace из `src/`
+
+### Requirement: Явный выбор режима
+Команда `cobot run` SHALL предлагать среду запуска и режим контроллера или Webots; режим Webots SHALL передавать launch-аргумент `simulate:=1`.
+
+#### Scenario: Выбор симуляции
+- **WHEN** пользователь выбирает «Симулятор Webots»
+- **THEN** запускается общее дерево `iiwa.launch.py` с симуляционной аппаратной моделью и временем `/clock`
+
+#### Scenario: Выбор контроллера
+- **WHEN** пользователь выбирает «Контроллер»
+- **THEN** запускается то же дерево с FRI hardware interface и системным временем
+
+### Requirement: Единый файл настроек
+Основной launch SHALL загружать путь из аргумента `setting`, разрешать `pkg://` пути и передавать параметры подсистемам из загруженной структуры.
+
+#### Scenario: Пользовательская конфигурация
+- **WHEN** задан `setting:=/path/to/cobot-setting.yaml`
+- **THEN** launch использует этот файл для параметров робота, симуляции, планирования, веб-сервера и Foxglove
+
+### Requirement: Ошибка конфигурации до движения
+Система MUST отклонять некорректные обязательные параметры и отсутствующие обязательные файлы конфигурации до начала командного движения.
+
+#### Scenario: Неверный период FRI
+- **WHEN** `fri_cycle_ms` находится вне диапазона 1–100 мс
+- **THEN** запуск аппаратного контроллера завершается ошибкой конфигурации
+
+#### Scenario: Неверные параметры TCP-гизмы
+- **WHEN** значение тайм-аута или скорости TCP-гизмы неположительно либо не является конечным числом
+- **THEN** загрузчик настроек отвергает конфигурацию
+
+### Requirement: Состав запуска
+Основной launch SHALL поднимать публикацию состояния робота, контроллеры, MoveIt и сервер движения; Webots, RViz, веб-сервер и Foxglove SHALL включаться согласно режиму и настройкам.
+
+#### Scenario: Отключён веб-сервер
+- **WHEN** `web.enabled` имеет значение `false`
+- **THEN** узел `iiwa_web_server` не добавляется в launch
+

openspec/specs/direct-trajectories/spec.md

@@ -0,0 +1,54 @@
+# Direct Trajectories
+
+## Purpose
+
+Описывает приём готовых суставных траекторий из JSON и CSV, их проверку перед публикацией и поведение остановки.
+
+## Requirements
+
+### Requirement: Форматы ввода
+HTTP API SHALL принимать JSON-точки через `POST /trajectory/send` и CSV-файл через `POST /trajectory/send_csv` с семью суставными колонками и временем от начала.
+
+#### Scenario: CSV с вариантами имён
+- **WHEN** CSV использует заголовки `joint_1`–`joint_7` и `time_from_start`
+- **THEN** колонки сопоставляются с `joint1`–`joint7` и временем `t` независимо от порядка
+
+### Requirement: Конечные и допустимые точки
+Каждая точка MUST содержать семь конечных углов и допустимое время; траектория MUST укладываться в позиционные, скоростные, ускорительные и рывковые ограничения из конфигурации.
+
+#### Scenario: Недопустимый сустав
+- **WHEN** точка выходит за допустимый диапазон сустава
+- **THEN** HTTP API возвращает 422 и не публикует траекторию
+
+### Requirement: Свежий неподвижный старт
+Прямая траектория MUST начинаться со свежего полного `/joint_states` и неподвижного робота; при ненулевом времени первой точки система SHALL добавить стартовую точку текущего положения.
+
+#### Scenario: Устаревшая обратная связь
+- **WHEN** возраст или временная метка `/joint_states` превышают настроенный предел
+- **THEN** запрос отклоняется с 409 без публикации
+
+#### Scenario: Нулевая первая точка не совпадает
+- **WHEN** первая точка имеет `t=0`, но отличается от измеренного положения больше допуска
+- **THEN** запрос отклоняется с 422
+
+### Requirement: Пересчёт времени
+Система SHALL при необходимости растягивать время траектории для соблюдения динамических ограничений и возвращать фактическую длительность и коэффициент масштабирования.
+
+#### Scenario: Быстрый сегмент
+- **WHEN** исходный интервал между точками требует превышения настроенных динамических лимитов
+- **THEN** опубликованная траектория имеет увеличенные интервалы и ответ сообщает `time_scale`
+
+### Requirement: Граница проверки прямого пути
+Прямой траекторный API SHALL проверять суставные и динамические ограничения, но не SHALL заявлять проверку столкновений для промежуточного пути.
+
+#### Scenario: Траектория в допустимых суставных лимитах
+- **WHEN** клиент отправляет валидные точки без подтверждённой проверки сцены
+- **THEN** API может опубликовать траекторию, а ответственность за оценку столкновений остаётся вне этого API
+
+### Requirement: Защита от замены и остановка
+Система MUST отвергать новую прямую траекторию во время ещё активной и MUST не публиковать подготовленную цель, если в ходе подготовки пришла остановка.
+
+#### Scenario: Остановка во время подготовки
+- **WHEN** `POST /stop` вызывается до публикации подготовленной траектории
+- **THEN** подготовка инвалидируется, а эта траектория не отправляется контроллеру
+

openspec/specs/external-api/spec.md

@@ -0,0 +1,54 @@
+# External API
+
+## Purpose
+
+Фиксирует доступные внешним клиентам HTTP и MCP операции для чтения состояния и отправки команд роботу, включая типы данных, проверку ввода и ошибки зависимостей ROS.
+
+## Requirements
+
+### Requirement: Включаемый сервер
+При `web.enabled=true` система SHALL запускать FastAPI на настроенных `host` и `port`, предоставлять OpenAPI-описание и монтировать MCP-приложение по `/mcp`.
+
+#### Scenario: Веб-сервер включён
+- **WHEN** основной launch загружает `web.enabled=true`
+- **THEN** запускается `iiwa_web_server` с путями к конфигурации эндпоинтов и суставных лимитов
+
+### Requirement: Конфигурируемые маршруты
+Маршруты из `api_endpoints.yaml` SHALL создавать HTTP обработчики типов `topic`, `service`, `action`, `fk` и `tf` с описанными полями и тайм-аутами.
+
+#### Scenario: Отключённый маршрут
+- **WHEN** запись маршрута имеет `enabled=false`
+- **THEN** маршрут не появляется в доступном HTTP API
+
+### Requirement: Чтение состояния
+`GET /robot/joint_states` SHALL возвращать имена, положения, скорости и усилия из `/joint_states`; `GET /robot/pose` SHALL возвращать TCP относительно `base_link`, XYZ в метрах, кватернион и KUKA ABC в радианах и градусах.
+
+#### Scenario: Нет сообщения суставов
+- **WHEN** `/joint_states` не поступает до тайм-аута маршрута
+- **THEN** запрос чтения состояния возвращает HTTP 503
+
+### Requirement: Команды движения через HTTP
+`POST /robot/move/joints`, `/robot/move/pose` и `/robot/move/named` SHALL передавать проверенные цели в соответствующие ROS action или service и возвращать `success` и `message`.
+
+#### Scenario: Некорректная длина суставов
+- **WHEN** тело запроса `/robot/move/joints` содержит не семь углов
+- **THEN** запрос получает 422 и ROS action не вызывается
+
+#### Scenario: Нет ROS-сервера
+- **WHEN** соответствующий ROS action или service недоступен до тайм-аута
+- **THEN** HTTP обработчик возвращает 503
+
+### Requirement: Единицы HTTP-позы
+`POST /robot/move/pose` SHALL принимать XYZ в метрах и A/B/C в радианах по соглашению ZYX; `speed` SHALL лежать в `[0.01, 1.0]`.
+
+#### Scenario: Выбор планировщика без учёта регистра
+- **WHEN** клиент указывает `planner="PTP"`
+- **THEN** маршрут нормализует ключ до `ptp` до отправки action-цели
+
+### Requirement: MCP-представление
+MCP-приложение SHALL строиться из тех же FastAPI-маршрутов, которые зарегистрированы для HTTP управления и чтения.
+
+#### Scenario: Запрос каталога инструментов MCP
+- **WHEN** MCP-клиент подключается к `/mcp`
+- **THEN** операции, выведенные из маршрутов FastAPI, доступны через MCP-приложение
+

openspec/specs/fri-control/spec.md

@@ -0,0 +1,51 @@
+# FRI Control
+
+## Purpose
+
+Описывает контракт управления физическим iiwa 7 через Sunrise FRI 1.16 и `ros2_control`, включая синхронизацию циклов, допустимые команды и отказ при потере надёжной связи.
+
+## Requirements
+
+### Requirement: Разделение циклов
+FRI-клиент SHALL выполнять отдельный циклический обмен с Sunrise и синхронизировать его с блокирующим циклом `controller_manager`.
+
+#### Scenario: Согласованный период
+- **WHEN** аппаратный режим запускается с `robot.fri_cycle_ms=10`
+- **THEN** частота `controller_manager` задаётся равной 100 Гц
+
+#### Scenario: Несовпадение периода
+- **WHEN** Sunrise сообщает период, отличный от настроенного FRI-периода
+- **THEN** обмен фиксирует ошибку вместо продолжения движения
+
+### Requirement: Позиционный интерфейс
+Аппаратный интерфейс SHALL предоставлять команду положения для семи суставов и публиковать измеренные положение, скорость, усилие и внешний момент там, где доступны данные FRI.
+
+#### Scenario: Активное позиционное управление
+- **WHEN** FRI находится в `COMMANDING_ACTIVE` с `POSITION` и `JOINT` overlay
+- **THEN** клиент передаёт полный массив семи суставных положений в радианах
+
+### Requirement: Проверка режима и телеметрии
+Система MUST отвергать командование при неверном режиме, недостаточном качестве связи, нарушении safety-состояния, неактивных приводах или нечисловой телеметрии.
+
+#### Scenario: Неверный FRI-режим
+- **WHEN** Sunrise сообщает командный режим, отличный от `POSITION` с `JOINT` overlay
+- **THEN** цикл командования завершается ошибкой и не принимает новую цель приложения
+
+### Requirement: Ограничение команды
+Клиент MUST проверять конечность каждого целевого угла и допустимый диапазон до отправки; между циклами он SHALL ограничивать шаг по настроенной скорости и применять настроенное сглаживание положения.
+
+#### Scenario: Цель за пределом
+- **WHEN** получена суставная цель вне настроенных пределов
+- **THEN** команда отвергается до вызова FRI `setJointPosition`
+
+### Requirement: Остановка при нарушении цикла
+Система MUST считать пропуск FRI-пакета, отсутствие продвижения временной метки, истечение watchdog и выход из `COMMANDING_ACTIVE` отказом, требующим явного восстановления.
+
+#### Scenario: Застывший цикл ros2_control
+- **WHEN** FRI-цикл не завершён `ros2_control` за 100 мс
+- **THEN** FRI worker отмечает отказ и прекращает дальнейшую нормальную выдачу целей
+
+#### Scenario: Нет готовой сессии
+- **WHEN** сессия не достигла `MONITORING_READY` за 15 секунд после начала обмена
+- **THEN** инициализация завершается ошибкой
+

openspec/specs/motion-arbitration/spec.md

@@ -0,0 +1,47 @@
+# Motion Arbitration
+
+## Purpose
+
+Определяет согласование конкурирующих источников движения, интерактивное управление TCP в Webots и семантику общей команды остановки.
+
+## Requirements
+
+### Requirement: Приоритет обычного движения
+При включённой TCP-гизме цели обычного траекторного action SHALL иметь приоритет над низкоприоритетной командой гизмы.
+
+#### Scenario: Цель MoveIt при активности гизмы
+- **WHEN** поступает обычная цель `FollowJointTrajectory`
+- **THEN** выдача новых низкоприоритетных целей блокируется до терминального результата контроллера
+
+### Requirement: Аренда приоритета
+Сервис `/cobot/tcp_gizmo/priority` SHALL выдавать именованную аренду на конечный TTL по настенным часам и поддерживать продление и освобождение.
+
+#### Scenario: Некорректный TTL
+- **WHEN** владелец пуст или TTL не находится в допустимом интервале `(0, 60]` секунд
+- **THEN** запрос аренды отклоняется
+
+#### Scenario: Потеря аренды
+- **WHEN** продление аренды из сервера движения не подтверждено
+- **THEN** текущая операция движения прерывается с ошибкой приоритета
+
+### Requirement: Одна команда на жест
+Гизма SHALL преобразовывать отпускание маркера в одну цель TCP с текущей эпохой состояния и SHALL отвергать устаревшую эпоху или недоступную обратную связь.
+
+#### Scenario: Устаревшая эпоха
+- **WHEN** команда содержит эпоху, отличную от опубликованной в `GizmoState`
+- **THEN** цель не отправляется контроллеру и публикуется причина отклонения
+
+### Requirement: Безопасный переход приоритета
+Новая высокоприоритетная команда SHALL ждать терминального результата уже переданной низкоприоритетной траектории до отправки контроллеру.
+
+#### Scenario: Низкая цель ещё исполняется
+- **WHEN** поступает высокая цель во время исполнения цели гизмы
+- **THEN** высокая цель ожидает подтверждённого завершения низкой цели
+
+### Requirement: Общая остановка
+`/cobot/stop` SHALL отменять текущую операцию планировщика и инвалидировать ожидающие операции; `POST /stop` дополнительно SHALL останавливать runner и прямую траекторию.
+
+#### Scenario: HTTP остановка
+- **WHEN** клиент вызывает `POST /stop`
+- **THEN** веб-сервер останавливает последовательность, отправляет удержание/сброс прямой траектории и вызывает ROS-сервис остановки
+

openspec/specs/motion-planning/spec.md

@@ -0,0 +1,50 @@
+# Motion Planning
+
+## Purpose
+
+Определяет публичные ROS-контракты планирования и исполнения суставных, декартовых и именованных движений через MoveIt 2.
+
+## Requirements
+
+### Requirement: Суставная цель
+Action `cobot/move_to_joints` SHALL принимать ровно семь углов в радианах и коэффициент скорости, а результат SHALL содержать `success` и `message`.
+
+#### Scenario: Допустимая цель
+- **WHEN** клиент отправляет семь суставных координат и скорость
+- **THEN** сервер планирует движение группы `iiwa_arm` от текущего состояния и сообщает стадии `planning` и `executing`
+
+### Requirement: Декартова цель
+Action `cobot/move_to_pose` SHALL принимать XYZ в метрах, KUKA ABC в радианах, скорость, планировщик и `frame_id`; ориентация SHALL интерпретироваться как ZYX: A=yaw, B=pitch, C=roll.
+
+#### Scenario: Цель без frame_id
+- **WHEN** action-цель содержит пустой `frame_id`
+- **THEN** сервер использует `planning.default_frame` и планирует движение TCP из `planning.pose_link`
+
+### Requirement: Выбор планировщика
+Декартово движение SHALL поддерживать ключи `ompl`, `ptp`, `lin`, `circ`, `chomp` и отвергать неизвестный ключ с отрицательным результатом.
+
+#### Scenario: Неизвестный планировщик
+- **WHEN** получен ключ, отсутствующий в списке поддерживаемых
+- **THEN** результат action содержит `success=false` и объяснение ошибки
+
+### Requirement: Именованная цель
+Сервис `cobot/move_to_named` SHALL принимать имя `group_state` из SRDF, масштаб скорости и ускорения; нулевой `accel_scale` SHALL означать масштаб, равный скорости.
+
+#### Scenario: Неизвестное имя
+- **WHEN** имя отсутствует в SRDF
+- **THEN** ответ сервиса содержит `success=false` и сообщение об неизвестном состоянии
+
+### Requirement: Сериализация операций
+Сервер движения SHALL выполнять не более одной операции планирования и исполнения через общий планирующий компонент одновременно.
+
+#### Scenario: Два запроса одновременно
+- **WHEN** одновременно поступают две команды движения
+- **THEN** операции сериализуются, а состояние одной операции не подменяет состояние другой
+
+### Requirement: Результат исполнения
+Сервер MUST различать успех, отказ планирования, ошибку исполнения и отмену; успешное построение плана само по себе не SHALL считаться успешным движением.
+
+#### Scenario: План не исполнен
+- **WHEN** контроллер возвращает ошибку исполнения траектории
+- **THEN** результат команды содержит `success=false` с диагностическим сообщением
+

openspec/specs/motion-sequences/spec.md

@@ -0,0 +1,55 @@
+# Motion Sequences
+
+## Purpose
+
+Описывает запуск последовательности суставных и декартовых целей, контроль её состояния и прекращение исполнения через веб-интерфейс.
+
+## Requirements
+
+### Requirement: Конфигурация последовательности
+Runner SHALL читать JSON-файл с точками движения и параметрами выполнения и различать суставные и декартовы точки.
+
+#### Scenario: Суставная точка
+- **WHEN** точка конфигурации содержит суставные координаты
+- **THEN** runner отправляет цель `MoveToJoints` и ожидает её результата перед следующей точкой
+
+#### Scenario: Декартова точка
+- **WHEN** точка конфигурации задаёт декартову позу
+- **THEN** runner отправляет цель `MoveToPose` с заданным планировщиком и ожидает результата
+
+### Requirement: Контроль последовательности через HTTP
+`POST /sequences/start` SHALL запускать отдельный процесс последовательности, а `GET /sequences/status` и `GET /sequences/logs` SHALL показывать её состояние и ограниченный журнал.
+
+#### Scenario: Запущенный процесс
+- **WHEN** runner исполняется
+- **THEN** `/sequences/status` возвращает `running` и идентификатор процесса
+
+### Requirement: Повторы и запись
+Runner SHALL выполнять заданное число итераций последовательности `home → waypoints → home`, выдерживать паузу между итерациями и при заданном `bag_path` записывать выбранные ROS-топики в MCAP.
+
+#### Scenario: Две итерации без записи
+- **WHEN** клиент задаёт `n_iterations=2` и пустой `bag_path`
+- **THEN** последовательность из начальной, промежуточных и конечной целей выполняется дважды без записи rosbag
+
+#### Scenario: Второй запуск при активном runner
+- **WHEN** `POST /sequences/start` вызывается при работающем процессе
+- **THEN** сервер отвечает 409 и не создаёт второй процесс
+
+#### Scenario: Путь записи уже существует
+- **WHEN** заданный `bag_path` указывает на существующий каталог
+- **THEN** runner удаляет каталог перед созданием новой записи MCAP
+
+### Requirement: Ошибка точки прерывает выполнение
+Runner MUST прекращать последовательность при неуспехе цели и инициировать остановку движения, вместо перехода к следующей точке.
+
+#### Scenario: Отказ action
+- **WHEN** одна из целей возвращает отрицательный результат
+- **THEN** остальные точки не отправляются, а runner завершает выполнение с ошибкой
+
+### Requirement: Остановка активного процесса
+Общая веб-команда остановки SHALL завершать активный процесс runner и предотвращать дальнейшую отправку точек.
+
+#### Scenario: Остановка во время последовательности
+- **WHEN** вызывается `POST /stop` во время работы runner
+- **THEN** процесс останавливается до выполнения оставшихся точек
+

openspec/specs/observability/spec.md

@@ -0,0 +1,43 @@
+# Observability
+
+## Purpose
+
+Определяет доступные оператору средства наблюдения за состоянием робота и симуляции и требования к диагностике отказов без сокрытия ошибок связи или движения.
+
+## Requirements
+
+### Requirement: Суставная телеметрия
+Активный контроллер SHALL публиковать измеренное состояние семи суставов через `joint_state_broadcaster` для планирования и внешнего чтения.
+
+#### Scenario: Работа контроллера
+- **WHEN** аппаратный или симуляционный контроллер активен
+- **THEN** `/joint_states` доступен серверу движения, веб-мосту и визуализации
+
+### Requirement: RViz по запросу
+Основной launch SHALL поддерживать отдельный аргумент `rviz` для визуализации модели и планирования.
+
+#### Scenario: RViz включён
+- **WHEN** launch получает `rviz:=true`
+- **THEN** запускаются RViz-узлы с конфигурацией из `digital_twin.rviz.config`
+
+### Requirement: Foxglove bridge по настройке
+При `foxglove.enabled=true` система SHALL запускать `foxglove_bridge` с настроенными портом, адресом, TLS и списками разрешённых топиков, сервисов и параметров.
+
+#### Scenario: Foxglove отключён
+- **WHEN** `foxglove.enabled=false`
+- **THEN** bridge не запускается основным launch
+
+### Requirement: Явное сообщение об отказе FRI
+Аппаратная подсистема MUST сообщать диагностическую причину ошибки FRI, включая ошибки SDK, тайм-аут цикла, неверный период и потерю сессии.
+
+#### Scenario: Ошибка FRI step
+- **WHEN** FRI `step()` завершается неуспешно
+- **THEN** worker отмечает отказ, прекращает нормальный обмен и выводит сообщение об ошибке
+
+### Requirement: Различение состояний движения
+Action движения SHALL публиковать обратную связь `planning` и `executing`, а окончательный результат SHALL содержать сообщение, пригодное для диагностики.
+
+#### Scenario: Планирование цели
+- **WHEN** сервер начал обработку action-цели
+- **THEN** клиент получает стадию `planning`, затем `executing` до вызова планирования и исполнения
+

openspec/specs/project-tooling/spec.md

@@ -0,0 +1,43 @@
+# Project Tooling
+
+## Purpose
+
+Описывает операторские команды для настройки, сборки, запуска и локального просмотра документации проекта без прямого вмешательства в циклическое управление.
+
+## Requirements
+
+### Requirement: Мастер первичной настройки
+`cobot setup` SHALL последовательно предлагать настройку документации, параметров робота и среды сборки.
+
+#### Scenario: Первый запуск
+- **WHEN** пользователь вызывает `cobot setup`
+- **THEN** получает отдельный выбор для локальной документации, `cobot-setting.yaml` и среды ROS 2 или Docker
+
+### Requirement: Редактирование конфигурации
+`cobot robot-setup` SHALL сохранять редактируемые значения в `cobot-setting.yaml` и применять выбранный из реестра инструмент к модели робота.
+
+#### Scenario: Выбор другого инструмента
+- **WHEN** пользователь меняет `tool.active`
+- **THEN** конфигурация и генерируемые Xacro/SRDF файлы соответствуют выбранному инструменту
+
+### Requirement: Сборка из src
+`cobot rebuild` SHALL запускать `colcon build --base-paths src` для всех пакетов или выбранного подмножества и поддерживать `--symlink-install`.
+
+#### Scenario: Пересборка одного пакета
+- **WHEN** пользователь задаёт `cobot rebuild iiwa_controller --symlink-install`
+- **THEN** CLI передаёт пакет и флаг символьной установки в colcon
+
+### Requirement: Локальная документация
+`cobot doc-setup` SHALL предоставлять запуск документации, сборку статического сайта и PDF, пересборку и остановку сервера.
+
+#### Scenario: Сборка документации
+- **WHEN** пользователь вызывает `cobot doc-setup build`
+- **THEN** создаются статическая документация и PDF из исходников `doc/lwc-doc/`
+
+### Requirement: Разделение файлов Sunrise и colcon
+ROS workspace MUST исключать `src/iiwa_sunrise` из colcon-сборки, оставляя Java-исходники для отдельной сборки в Sunrise Workbench.
+
+#### Scenario: Сборка рабочего пространства
+- **WHEN** выполняется `colcon build --base-paths src`
+- **THEN** пакет контроллерных Java-программ не собирается colcon
+

openspec/specs/robot-model/spec.md

@@ -0,0 +1,47 @@
+# Robot Model
+
+## Purpose
+
+Фиксирует кинематическую модель семиосевого iiwa 7, систему координат TCP, ограничения суставов и зависимость модели от выбранного инструмента.
+
+## Requirements
+
+### Requirement: Семь осей и единицы
+Модель SHALL содержать суставы `joint1`–`joint7` в заданном порядке; суставные положения SHALL выражаться в радианах, скорости в радианах в секунду.
+
+#### Scenario: Публикация состояния
+- **WHEN** запущен `joint_state_broadcaster`
+- **THEN** `/joint_states` содержит имена и значения всех семи управляемых суставов
+
+### Requirement: Согласованные лимиты
+URDF, `ros2_control`, MoveIt и проверка внешних суставных команд MUST брать границы из `joint_limits.yaml` с учётом мягкого диапазона там, где он предусмотрен.
+
+#### Scenario: Суставная цель вне мягкой границы
+- **WHEN** HTTP-запрос суставного движения содержит угол за допустимой границей
+- **THEN** запрос отклоняется до отправки ROS action с кодом 422
+
+### Requirement: Активный инструмент
+Конфигурация инструмента SHALL определять Xacro-описание, конечное звено кинематической цепи, TCP и пары отключённых самоколлизий.
+
+#### Scenario: Выбор инструмента из реестра
+- **WHEN** `cobot robot-setup` применяет инструмент из `tools.yaml`
+- **THEN** обновляются `tool_active.xacro` и `iiwa7.srdf`, сохраняя существующие именованные положения
+
+#### Scenario: Нет инструмента
+- **WHEN** выбран `none`
+- **THEN** TCP совпадает с `link_ee` через фиксированное соединение
+
+### Requirement: Декартова система координат
+Декартово движение SHALL задавать целевую позу TCP относительно указанного `frame_id`, по умолчанию `base_link`.
+
+#### Scenario: Рамка не указана
+- **WHEN** клиент оставляет `frame_id` пустым
+- **THEN** сервер движения использует `planning.default_frame`
+
+### Requirement: Именованные положения
+Именованные положения SHALL определяться `group_state` в SRDF и предоставляться клиенту вместе с именами и углами суставов.
+
+#### Scenario: Запрос каталога
+- **WHEN** клиент вызывает `GET /robot/positions`
+- **THEN** возвращаются доступные `group_state` с именем, группой, описанием и суставными углами
+

openspec/specs/simulation/spec.md

@@ -0,0 +1,43 @@
+# Simulation
+
+## Purpose
+
+Описывает цифровой двойник в Webots для проверки запуска, суставного управления, объектов сцены, камер и интерактивного TCP без подключения к физическому роботу.
+
+## Requirements
+
+### Requirement: Симуляционный контроллер
+Режим `simulate` SHALL создавать модель iiwa в Webots и использовать `webots_ros2_control` вместо FRI hardware interface.
+
+#### Scenario: Запуск Webots
+- **WHEN** launch получает `simulate:=true`
+- **THEN** создаётся робот в выбранном world, а контроллеры запускаются с симуляционным временем
+
+### Requirement: Начальное состояние и геометрия
+Симуляция SHALL загружать начальные суставные положения, ограничения, инструмент и преобразование размещения робота из конфигурации.
+
+#### Scenario: Изменён активный инструмент
+- **WHEN** инструмент применён до нового запуска Webots
+- **THEN** URDF модели содержит соответствующую геометрию и TCP
+
+### Requirement: Объекты сцены
+При включённых `digital_twin.webots.objects` система SHALL размещать заданное число объектов из перечисленных OBJ-моделей в настроенной области относительно основания робота.
+
+#### Scenario: Повтор моделей
+- **WHEN** число объектов больше числа доступных моделей
+- **THEN** модели могут повторяться, а общее число создаваемых объектов соответствует `count`
+
+### Requirement: Камеры
+Камеры Webots SHALL загружаться из файлов конфигурации; включённый драйвер SHALL публиковать изображения и `CameraInfo`, а для датчика глубины — предусмотренные глубинные данные.
+
+#### Scenario: Настроена D455
+- **WHEN** в списке камер указан `d455_top.yaml`
+- **THEN** симуляционный запуск создаёт камеру с именами топиков и параметрами из этого файла
+
+### Requirement: Симуляционный TCP-инструмент
+TCP-гизма SHALL запускаться только при включённом флаге и в режиме симуляции.
+
+#### Scenario: Физический режим
+- **WHEN** запуск выполняется с `simulate:=false`
+- **THEN** узлы интерактивной TCP-гизмы не активируются
+

openspec/specs/sunrise-program/spec.md

@@ -0,0 +1,54 @@
+# Sunrise Program
+
+## Purpose
+
+Определяет обязанности программы на контроллере KUKA при установлении FRI-сессии и ограничения выбранного сетевого и управляющего режима.
+
+## Requirements
+
+### Requirement: Отдельное развёртывание
+`ServerFriRos2` SHALL собираться и развёртываться в Sunrise Workbench отдельно от ROS workspace; физический запуск MUST сверять адрес ПК, порт FRI, инструмент и Load Data с конфигурацией ячейки.
+
+#### Scenario: Новый контроллер
+- **WHEN** программа переносится на другую ячейку
+- **THEN** оператор проверяет сетевые константы, имя инструмента и его данные нагрузки перед FRI-сессией
+
+### Requirement: Выбор интерфейса сети
+Программа SHALL предлагать KONI или KLI и использовать адрес ПК выбранной сети при создании FRI-конфигурации.
+
+#### Scenario: Выбран KLI
+- **WHEN** оператор выбирает KLI
+- **THEN** период отправки устанавливается в 10 мс и режим ручного ведения недоступен в меню
+
+### Requirement: Подъезд до запуска FRI
+Программа SHALL перемещать робот в предварительно заданное суставное положение до открытия FRI-сессии; оператор MUST проверять это положение для своей ячейки и инструмента.
+
+#### Scenario: Запуск физической программы
+- **WHEN** оператор начинает `ServerFriRos2`
+- **THEN** робот выполняет настроенный подъезд до входа в позиционный или мониторинговый режим FRI
+
+### Requirement: Выбор командного режима
+Для позиционного управления программа SHALL создавать FRI-сессию с позиционными суставными командами; выбранный режим управления SHALL соответствовать возможностям клиентского аппаратного интерфейса.
+
+#### Scenario: Позиционный режим
+- **WHEN** оператор выбирает Position или JointImpedance для командного движения
+- **THEN** клиент ROS получает сессию с `POSITION` command mode и `JOINT` overlay
+
+### Requirement: Мониторинг без команд
+Режим Monitor SHALL быть доступен только при выборе KONI; перед ручным ведением программа SHALL проверить данные нагрузки инструмента и предупредить оператора, если проверка не прошла.
+
+#### Scenario: Попытка Monitor на KLI
+- **WHEN** оператор выбирает KLI
+- **THEN** программа не предлагает Monitor как режим запуска
+
+#### Scenario: Неверные Load Data
+- **WHEN** проверка нагрузки инструмента в Monitor не проходит
+- **THEN** программа показывает предупреждение и предоставляет оператору выбор остановить запуск или явно продолжить
+
+### Requirement: Завершение сессии
+Программа MUST закрывать FRI-сессию при штатном окончании и при освобождении приложения, включая ошибки соединения.
+
+#### Scenario: Нет клиента
+- **WHEN** FRI-клиент не подключается в отведённые 30 секунд
+- **THEN** программа сообщает тайм-аут и закрывает сессию
+