@spec-box/sdd 0.10.0 → 0.12.0

package/docs/design.md

@@ -97,7 +97,8 @@
 | intake | CLI | Папка `changes/<id>/`, `change.yaml`, `request.md` с исходным описанием; при создании из брифа сюда же копируются дельты и решения | Всегда |
 | research | Роль researcher | `evidence/research.md`: факты о текущем поведении, границы, затронутые спецификации и код, пробелы; первый раздел «Разбор запроса» повторяет явные утверждения запроса дословными цитатами со статусом `подтверждено`, `противоречит` или `не проверено`, CLI сверяет цитаты с текстом запроса. При создании из брифа проверяет, что бриф не устарел | Пробелов, меняющих решение, нет |
 | propose | Роль planner | `proposal.md` с разделом «Расхождения с запросом» (решение по каждому отступлению от запроса или evidence), размер изменения, сложность реализации и ревью. При создании из брифа берётся из него | Гейт `proposal`, если включён |
-| plan | Роль planner, для `large` роль challenger | Дельты `specs/` (при создании из брифа проверяются, а не пишутся), `design.md` с решениями и вопросами, `tasks.md`, `evidence/challenge.md` | `sbox validate` без ошибок, нет вопросов P0, гейт `plan`, если включён |
+| plan | Роль planner | Дельты `specs/` (при создании из брифа проверяются, а не пишутся), `design.md` с решениями и вопросами, `tasks.md` | `sbox validate` без ошибок, нет вопросов P0, гейт `plan`, если включён |
+| challenge | Роль challenger | `evidence/challenge-N.md` (сохраняет CLI) | findings присутствует, нет blocking; иначе возврат в plan |
 | cover | Роль tester, затем роль reviewer в режиме ревью тестов | Автотесты по сценариям, `coverage.yaml`, `test-plan.md` при необходимости; тесты прошли ИИ-ревью с автоисправлением, запущены и падают по ожидаемой причине | Гейт `tests`, если включён |
 | implement | Роль implementer, затем CLI | Код, отмеченные задачи в `tasks.md`, узкие проверки; CLI запечатывает change-set: список изменённых путей и дайджест дифа в `changeset.json` | Все задачи отмечены, все тесты из `coverage.yaml` зелёные, защищённые файлы не тронуты |
 | verify | CLI и роль verifier | `evidence/verify-N.md`: отчёты тестов, покрытие сценариев, соответствие дизайну и правилам, проверки проекта, дымовой запуск по `testing.md`; каждый пункт со статусом PASS, FAIL, PARTIAL или NOT_RUN и список пробелов (manual/CI gaps). если в `design.md` объявлен образец, CLI передаёт верификатору кандидатов подключения нового модуля (`sbox wiring`), а нерассмотренные добавляет в отчёт пунктами PARTIAL для ревьюера | Нет пунктов FAIL, дайджест change-set не изменился |
@@ -114,7 +115,7 @@
 |---|---|---|
 | `small` | Поведение продукта не меняется: рефакторинг, инфраструктура, документация | `proposal.md`, `tasks.md`; в `change.yaml` стоит `skip_specs: true`; фаза cover ограничена регрессионными тестами |
 | `normal` | Меняется поведение в пределах одной-двух capability | `proposal.md`, дельты `specs/`, `design.md`, `tasks.md`, тесты |
-| `large` | Несколько capability, новые контракты, миграции, безопасность | Все артефакты плюс аудит плана ролью challenger |
+| `large` | Несколько capability, новые контракты, миграции, безопасность | Все артефакты; аудит плана обязателен при любом размере |
 
 ### Гейты, профили и каналы
 
@@ -126,6 +127,10 @@
 | `checkpoint` | Нет | Да | Нет | Да |
 | `autonomous` | Нет | Нет | Нет | Да |
 
+Фаза challenge следует после гейта plan, учитывает ответы человека и обязательна для всех размеров и уровней автономности. Challenger не меняет артефакты, CLI сохраняет каждый отчёт отдельно. Даже при статусе «готово» blocking findings возвращают в plan; отсутствие findings отклоняет отчёт. Возврат в plan сбрасывает прежние утверждения plan и tests (состояние skipped с reason: plan_changed), сохраняя ответы человека, и требует повторных гейтов, если они включены. Это не отклонение тестов человеком, поэтому tests_review не пропускается при testing.reviewReworks=false. Общий лимит возвратов ограничивает повторные аудиты.
+
+При обновлении существующие изменения сохраняют текущую фазу: ожидающий гейт plan после утверждения ведёт в challenge; уже прошедшие планирование не перематываются. Любой последующий возврат в plan включает аудит.
+
 Гейт `plan` стоит до фазы cover: человек смотрит дизайн и спецификации раньше, чем тестировщик потратит запуск на отклонённый дизайн. ИИ-ревью тестов с автоисправлением выполняется при любом профиле. Для пилотов начинаем с `supervised`. Изменение, созданное из брифа дискавери, по умолчанию получает профиль `autonomous`, потому что спецификации и решения уже прошли ревью человека на дискавери.
 
 Независимо от профиля инструмент останавливается на вопросе приоритета P0: без ответа нельзя писать спецификации и тесты. Вопросы P1 останавливают только на включённом гейте `plan`, иначе принимается рекомендованный вариант и записывается как допущение. Вопросы P2 не останавливают никогда.
@@ -156,7 +161,7 @@
 
 | Категория блокера | Кто выставил | Куда возвращается |
 |---|---|---|
-| `артефакт <id>` | tester, implementer, reviewer, verifier | В фазу plan к планировщику. Если изменились дельты, фаза cover повторяется |
+| `артефакт <id>` | challenger, tester, implementer, reviewer, verifier | В фазу plan к планировщику. Если изменились дельты, фаза cover повторяется |
 | `тесты` | implementer, reviewer, verifier | В фазу cover к тестировщику |
 | `реализация` | verifier, reviewer | В фазу implement к реализатору с текстом замечаний; после исправления фазы verify и review повторяются |
 | `внешний` | Любая роль | Запуск завершается со статусом `blocked`, повтор по внешнему событию или вручную |
@@ -171,7 +176,7 @@
 ### Схема состояний
 
 ```text
-discover → intake → research → propose → [proposal] → plan → [plan] → cover → [tests] → implement → verify → review → deliver → (merge) → post-merge
+discover → intake → research → propose → [proposal] → plan → [plan] → challenge → cover → [tests] → implement → verify → review → deliver → (merge) → post-merge
                           ▲                             ▲                 ▲                  ▲           │         │
                           │ пробел в фактах             │ артефакт        │ тесты            │ реализация│         │
                           └─────────────────────────────┴─────────────────┴──────────────────┴───────────┴─────────┘
@@ -201,7 +206,7 @@ discover → intake → research → propose → [proposal] → plan → [plan]
 |---|---|---|---|---|
 | researcher | Только чтение | Проектную документацию, спецификации, код | `evidence/research.md` | обычный |
 | planner | Артефакты изменения | Исходный запрос или бриф, evidence, спецификации, правила проекта, код при необходимости | `proposal.md`, `specs/`, `design.md`, `tasks.md` | обычный, pro |
-| challenger | Только чтение | Замороженный план или бриф, evidence, правила проекта; в режиме аудита документации всю `.sbox/project/` и код | `evidence/challenge.md`, отчёт `doctor --deep` | pro |
+| challenger | Только чтение | Замороженный план или бриф, evidence, правила проекта; в режиме аудита документации всю `.sbox/project/` и код | `evidence/challenge-N.md`, отчёт `doctor --deep` | pro |
 | tester | Тестовые файлы и тестовая инфраструктура | Дельты, дизайн, `testing.md`, существующие тесты | Тесты, `coverage.yaml`, `test-plan.md` | обычный, pro |
 | implementer | Продуктовый код и отметки в `tasks.md`; тестовые файлы защищены | Артефакты изменения, проектную документацию, правила, код | Код | обычный, pro |
 | reviewer | Только чтение; вердикт привязан к дайджесту change-set | Артефакты, правила, диф, отчёт верификатора; в фазе cover тесты и `coverage.yaml` | `evidence/review-N.md` с disposition и `delivery_narrative`, `evidence/tests-review-N.md` | обычный, pro |
@@ -212,9 +217,9 @@ discover → intake → research → propose → [proposal] → plan → [plan]
 
 ### Контракт роли
 
-Определение роли лежит в пакете инструмента в виде Markdown с четырьмя разделами: правила, вход, этапы, содержимое resultFile (ответ роли; сообщение хосту содержит только путь к нему и статус). Проект может переопределить или дополнить роль файлом в `.sbox/roles/<role>.md`. Раздел «правила» перечисляет, что роль делает и чего не делает. Раздел «вход» описывает пакет от CLI. Раздел «выход» задаёт шаблон ответа.
+Определение роли лежит в пакете инструмента в виде Markdown с тремя разделами: правила, этапы, содержимое resultFile (ответ роли; сообщение хосту содержит только путь к нему и статус). Проект может переопределить или дополнить роль файлом в `.sbox/roles/<role>.md`. Раздел «правила» перечисляет, что роль делает и чего не делает. Раздел «вход» описывает пакет от CLI. Раздел «выход» задаёт шаблон ответа.
 
-Пакет от CLI содержит девять полей: цель, вопрос или зона владения, допущенные файлы, ограничения, правила проекта, полномочия, способ проверки, форма результата, условие остановки. Восемь из них взяты из практики sarah, где такой пакет показал себя пригодным для делегирования без потери контекста; поле «правила проекта» добавлено для постоянных архитектурных правил.
+Пакет от CLI содержит девять полей: цель, вопрос или зона владения, допущенные файлы, ограничения, правила проекта, полномочия, способ проверки, форма результата, условие остановки. Восемь из них взяты из практики sarah, где такой пакет показал себя пригодным для делегирования без потери контекста; поле «правила проекта» добавлено для постоянных архитектурных правил. Файл `packet.json` не содержит текста роли: агент хоста уже получил его системным промптом, а headless-раннер добавляет его в промпт сам; поле `resultFormat` отсылает к разделу «Содержимое resultFile» роли и к `sbox help result`, инструкции к артефактам фазы лежат в `instructions`, поэтому роль не запрашивает их командой повторно. Указатель `tools` перечисляет инструменты, доступные роли: когда инструмент нужен, команда справки и одна-три самые частые команды дословно; состав берётся из `metadata.roles` и `metadata.commands` скиллов, поэтому проект управляет им файлами `.sbox/skills/`, а остальные команды роль читает через `help` тогда, когда инструмент понадобился.
 
 Ответ роли состоит из человекочитаемого Markdown и завершающего машиночитаемого блока:
 
@@ -225,9 +230,9 @@ blocker:
   category: артефакт | тесты | реализация | внешний | пользователь | нет
   artifact: tasks            # только для категории артефакт
   message: ...
-complexity:                  # только planner на фазе propose
-  implementation: обычная | высокая
-  review: обычная | высокая
+complexity:                  # planner; challenger может повысить оценку после аудита
+  implementation: простая | обычная | высокая
+  review: простая | обычная | высокая
 size: small | normal | large # только planner на фазе propose
 request:                     # только researcher: разбор запроса, цитаты сверяются с request.md
   - { quote: ..., status: подтверждено | противоречит | не проверено, evidence: ... }
@@ -268,7 +273,7 @@ Delivery narrative. При вердикте `готово` ревьюер пиш
 
 ### Уровни модели и продолжение сессий
 
-Планировщик оценивает сложность реализации и ревью. По оценке CLI выбирает обычную или pro-модель для тестировщика, реализатора и ревьюера из таблицы в конфиге. Оценка может расти при возвратах, но не снижаться.
+Планировщик отдельно оценивает сложность реализации и ревью: простая, обычная, высокая, учитывая неопределённость и последствия ошибки. Общая функция выбора сопоставляет сложность реализации с simple, medium, complex для implementer/tester, затем берёт model и effort из профиля конкретного раннера. Независимое ревью по умолчанию всегда complex. Оценка может расти при возвратах, но не снижаться; размер изменения не заменяет сложность. Подробная политика и настройка — раздел 18.
 
 При возврате к роли CLI продолжает её прошлую сессию по идентификатору, если адаптер среды это умеет. Если нет, создаётся новая сессия, и в неё передаются исходный пакет и текст возврата вместе. Идентификаторы сессий хранятся в `runs/`.
 
@@ -302,7 +307,7 @@ Delivery narrative. При вердикте `готово` ревьюер пиш
         test-plan.md         # при необходимости
         evidence/
           research.md
-          challenge.md
+          challenge-1.md
           tests-review-1.md
           review-1.md
           verify-1.md
@@ -706,7 +711,7 @@ interface AgentRunner {
 }
 ```
 
-Реализации: `claude` через Claude Agent SDK (управляемые сессии, разрешения на инструменты, учёт стоимости), `codex` через `codex exec` в неинтерактивном режиме. Если Codex не умеет продолжать сессию, возврат к роли идёт через новую сессию с полным контекстом. Разрешения на команды и пути берутся из `workflow.md`, `testing.md` и списка защищённых файлов.
+Реализации: `claude` через Claude Agent SDK (управляемые сессии, разрешения на инструменты, учёт стоимости), `codex` через `codex exec` в неинтерактивном режиме. Поддержка продолжения проверяется по возможностям CLI; если её нет, возврат к роли идёт через новую сессию с полным контекстом. Разрешения на команды и пути берутся из `workflow.md`, `testing.md` и списка защищённых файлов.
 
 Рецепт вызова Codex повторяет проверенный в Suite:
 
@@ -739,7 +744,13 @@ interface HostMaterials {
 }
 ```
 
-Команда `sbox host install --target claude | codex` копирует скиллы из единого источника `assets/skills` (`sbox-run`, `sbox-approve`, `sbox-browser`) в раскладку хоста и генерирует агентов: для Claude Code `.claude/agents/sbox-<role>.md`, где скиллы из `metadata.roles` подключены полем `skills`, потому что субагенты не видят скиллы проекта сами; для Codex сейчас ставятся только скиллы без привязки к хосту (`sbox-approve`, `sbox-browser`) в `.agents/skills`, а `sbox-run` помечен `metadata.hosts: [claude]`, потому что его текст опирается на субагентов Claude Code; агенты ролей и раздел `AGENTS.md` для Codex появятся на этапе 4. Описания агентов берутся из фронтматтера `description` файлов ролей, каркас агента из `assets/hosts/claude/agent.md`, набор инструментов из `runner.claude.allowedTools` и `readOnlyTools` конфига, как в headless-режиме. Все сгенерированные файлы тонкие: они вызывают `sbox next` и `sbox report`, а определения ролей остаются в одном месте. Повторный запуск обновляет файлы, ручные правки в них не предполагаются.
+Команда `sbox host install --target claude | codex` и `sbox init --host` копируют общие скиллы из `assets/skills` без изменений. Для Claude Code генерируются `.claude/agents/sbox-<role>.md` и варианты профилей; скиллы в агентов не предзагружаются. Для Codex генерируются 28 standalone TOML-файлов `.codex/agents/sbox-<role>[-<profile>].toml`: семь активных ролей, базовое имя и три профиля. Имя, описание, model, model_reasoning_effort, sandbox_mode и developer_instructions задаются явно. Скиллы копируются для оркестратора и человека, а в инструкции агентов их пути не входят: роль видит инструменты в указателе `tools` пакета и читает руководство через `help`, когда инструмент понадобился. Шаблоны живут в assets/hosts; определения ролей и переопределения .sbox/roles общие.
+
+Codex получает раздел AGENTS.md между маркерами `<!-- sbox:begin -->` / `<!-- sbox:end -->`; остальной текст сохраняется дословно, повторная установка идемпотентна. Повреждённые маркеры, AGENTS.md-ссылка и чужой файл с именем генерируемого агента останавливают установку до записи материалов. Пользовательский .codex/config.toml не меняется, глобальные настройки и доверие проекту не переключаются. После установки нужна новая сессия Codex; проектные материалы должны быть доверенными средствами хоста. Настройки доступа родительской сессии могут ограничивать или переопределять sandbox агента; инструкции ownership действуют независимо от них.
+
+Скилл sbox-run общий: next вызывается с текущим хостом явно. В нативном Codex пользовательский агент возвращает полный ответ родителю, который дословно сохраняет resultFile и сдаёт report; read-only роль не получает запись ради отчёта. CLI сохраняет requested_execution отдельно от фактических данных раннера. Повторное использование агента возможно только внутри того же изменения при совпадении runner/agent/model/effort и доступной функции продолжения. Если клиент не умеет выбирать пользовательских агентов, скилл выполняет один шаг через `sbox run --runner codex --max-runs 1`; headless сам принимает отчёт, поэтому повторный report запрещён. CodexRunner сохраняет thread_id из событий thread.started и продолжает нужную сессию через exec resume <id> при совпадении роли, модели, effort и профиля. Поддержка resume со структурированным выводом проверяется по справке CLI; старый клиент начинает свежую сессию с полным пакетом. Никогда не используется --last. Для resume рабочая директория задаётся cwd процесса, sandbox — через config override. Нативный и headless пути используют один resolver и одинаковый жизненный цикл, включая challenger. Гейты и доставка не утверждаются оркестратором автоматически.
+
+Формат Codex сверён с [официальной документацией Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) 2026-09-28. Поддержка standalone agents зависит от версии клиента; доступность конкретной модели проверяет провайдер при запуске.
 
 ### Отчёты тестов
 
@@ -759,7 +770,7 @@ interface TestReportAdapter {
 - **Сессия.** Первая команда страницы поднимает демон: фоновый процесс с браузером и локальным сокетом (unix-сокет, на Windows именованный канал) в `~/.sbox/browser/sessions/<имя>`. Клиент отправляет одну команду в JSON-строке и получает ответ; демон исполняет команды последовательно. Между вызовами сохраняются вкладки, страница, куки, буферы консоли и сети. Демон завершается по `stop`, по простою между командами (`browser.idleMinutes`, по умолчанию 30; во время долгой команды таймер не срабатывает, значения больше 35791 минут отключают самозавершение) или при потере браузера. Имя сессии занимается атомарной блокировкой до запуска браузера, поэтому два одновременных автозапуска не поднимают два Chrome; `ping` и `stop` отвечают вне очереди команд, так что занятый демон не считается мёртвым, а `stop` прерывает долгое ожидание. Уход клиента (таймаут, Ctrl+C) отменяет его команду в очереди. След мёртвого процесса удаляется при следующем обращении, а `stop` посылает сигнал только процессу, чья командная строка это демон данной сессии. `--session <имя>` даёт независимые браузеры.
 - **Вход человеком.** `sbox-browser login <url> --profile <имя>` открывает окно с постоянным профилем (user-data-dir в `~/.sbox/browser/profiles/<имя>`), человек входит и подтверждает Enter, либо `--until <селектор>` / `--until-url <шаблон>` завершают вход автоматически. Дальше та же сессия работает под входом, а после `stop` любая headless-сессия с этим профилем (флаг `--profile` или `browser.profile` в конфиге) получает те же куки. Перенос входа в CI или на другую машину: `state save <файл>` выгружает куки браузера и storage текущей страницы, `state load` восстанавливает; файл содержит секреты и не коммитится.
 - **Команды для агента.** `goto`, `back`, `reload`, `snapshot` (дерево доступности с ролями, именами, состояниями и ссылками `[eN]` на интерактивные элементы), действия `click`, `fill`, `type`, `press`, `select`, `check`, `upload`, `hover`, `scroll`, ожидания `wait` (элемент, текст, адрес, условие, пауза), чтение `text`, `html`, `attr`, `value`, `count`, `exists`, `eval`, доказательства `screenshot`, `console --errors`, `requests` (ответы 4xx/5xx и неудачные запросы), окружение `cookies`, `viewport`, `dialog`, `auth`, `headers`, вкладки `pages` и `page new | switch | close`. Цель действия это ссылка из снимка либо селектор: CSS, `text=`, `aria=`, `xpath=`. Ссылки нумеруются при каждом снимке; исчезнувший элемент даёт ошибку `BROWSER_REF_STALE` с подсказкой сделать снимок заново, `exists` по ссылке проверяет живой элемент. Диалог `beforeunload` подтверждается всегда, иначе политика `dismiss` отменяла бы любую навигацию. `eval` сначала исполняет код как есть (выражение или список инструкций), а при синтаксической ошибке из-за `return` или `await` как тело async-функции. Все команды поддерживают `--json`, ошибки приходят в общем конверте диагностики с кодами `BROWSER_*`.
-- **В процессе изменения.** Верификатор обязан проверить затронутую страницу через `sbox-browser`, если `testing.md` описывает запуск: ошибки консоли и ответы 4xx/5xx на ней это FAIL, скриншот прикладывается как доказательство; без профиля для страницы, требующей входа, это пробел с окружением «вход в приложение». Исследователь и тестировщик используют снимок, чтобы зафиксировать тексты, элементы и маршруты; автотесты пишутся на инструментах проекта. Пакет каждой роли содержит подсказку `commands.browser`. Категория `testing.md` получила раздел «Проверка интерфейса в браузере»: базовый URL, профиль входа, дымовые маршруты.
+- **В процессе изменения.** Верификатор обязан проверить затронутую страницу через `sbox-browser`, если `testing.md` описывает запуск: ошибки консоли и ответы 4xx/5xx на ней это FAIL, скриншот прикладывается как доказательство; без профиля для страницы, требующей входа, это пробел с окружением «вход в приложение». Исследователь и тестировщик используют снимок, чтобы зафиксировать тексты, элементы и маршруты; автотесты пишутся на инструментах проекта. Пакет каждой роли содержит подсказку `tools`. Категория `testing.md` получила раздел «Проверка интерфейса в браузере»: базовый URL, профиль входа, дымовые маршруты.
 - **Безопасность.** Профили, файлы состояния, скриншоты и журналы демонов лежат в `~/.sbox/browser`, вне репозитория продукта; в репозиторий попадает только конфиг без секретов. Демон слушает локальный сокет, доступный только пользователю.
 
 ## 12. CLI и архитектура кода
@@ -768,7 +779,7 @@ interface TestReportAdapter {
 
 | Группа | Команды | Назначение |
 |---|---|---|
-| Проект | `init`, `doctor [--deep]`, `host install` | Настройка проекта, проверка документации и конфига, материалы для хостов |
+| Проект | `init`, `doctor [--deep]`, `host install`, `help [тема]` | Настройка проекта, проверка документации и конфига, материалы для хостов; `help` печатает справку для агентов и людей: без аргумента указатель тем, с темой руководство (`contract`, `wiki`, `browser` те же, что `sbox-contract help`, `sbox-wiki help`, `sbox-browser help`; `result`, `log`, `packet` из `assets/help/`) |
 | Дискавери | `discover`, `discover validate` | Бриф, дельты и решения, достаточные для автономной реализации; проверка чужого брифа |
 | Изменение | `change new [--from-brief]`, `change list`, `change show`, `change resume [--returns N]`, `change reopen`, `change link` | Жизненный цикл изменения; `resume` продолжает `parked`, `blocked` и `delivery_unknown` с явным намерением человека; `link` связывает изменения партнёров общим идентификатором координации |
 | Протокол | `next`, `report`, `approve`, `reject` | Выдать пакет следующей роли, принять ответ, решить гейт и ответить на вопросы |
@@ -811,7 +822,7 @@ packages/
 
 - Node.js 22 LTS, TypeScript в strict-режиме, ESM.
 - Схема артефактов, роли и категории документации хранятся как данные (YAML и Markdown), а не как код, чтобы проект мог их переопределять без сборки.
-- Скиллы хостов тоже данные: единый источник `assets/skills/<имя>.md` с фронтматтером `name`, `description` и `metadata.roles`. Адаптер хоста при `init --host` и `host install` копирует файл без изменений в раскладку хоста (Claude Code: `.claude/skills/<имя>/SKILL.md`, Codex: `.agents/skills/<имя>/SKILL.md`) и подключает скилл ролям из `metadata.roles` средствами хоста. Текст скилла в коде адаптера запрещён; новый хост это новая строка в таблице раскладок, а не новый текст. Проект заменяет или добавляет скилл файлом `.sbox/skills/<имя>.md`. Хосты равноправны: возможность, сделанная для одного хоста, либо покрывает остальные, либо явно записана в план.
+- Скиллы хостов тоже данные: единый источник `assets/skills/<имя>.md` с фронтматтером `name`, `description` и `metadata.roles`. Адаптер хоста при `init --host` и `host install` копирует файл без изменений в раскладку хоста (Claude Code: `.claude/skills/<имя>/SKILL.md`, Codex: `.agents/skills/<имя>/SKILL.md`) ; `metadata.roles` определяет, каким ролям инструмент показывается в указателе `tools` пакета, `metadata.commands` даёт его частые команды, а в контекст агента скиллы не предзагружаются. Текст скилла в коде адаптера запрещён; новый хост это новая строка в таблице раскладок, а не новый текст. Проект заменяет или добавляет скилл файлом `.sbox/skills/<имя>.md`. Хосты равноправны: возможность, сделанная для одного хоста, либо покрывает остальные, либо явно записана в план. Та же разметка служит справкой по требованию: `sbox help <тема>` и `<инструмент> help` печатают тело скилла без фронтматтера, темы `result`, `log`, `packet` лежат в `assets/help/`, проект добавляет или заменяет тему файлом `.sbox/help/<тема>.md`. Шаблоны агентов называют справку одной фразой, чтобы роль читала руководство инструмента тогда, когда он понадобился.
 - Парсер spec-box-YAML переиспользует модель из `@spec-box/sync`, парсер OpenSpec-Markdown свой, без зависимости от пакета `@fission-ai/openspec`: он меняет формат каждые несколько недель, а нам нужен стабильный внутренний контракт. Если `openspec` установлен в проекте, `sbox validate` дополнительно вызывает `openspec validate` и показывает его диагностику.
 - Тесты ядра на фикстурах: репозиторий-образец в каждом формате спецификаций, прогон машины состояний с записанными ответами ролей. Адаптеры сред тестируются контрактными тестами с заглушками.
 
@@ -846,7 +857,7 @@ packages/
 | 1. Ядро и interactive-режим | Конфиг, `change.yaml`, машина состояний, `next` и `report`, адаптер spec-box, категории документации и структурный `doctor`, формат дизайна с вопросами и правилами, материалы для Claude Code | В репозитории `sync` разработчик проводит одно изменение до пул-реквеста из Claude Code, фазу cover выполняет вручную |
 | 2. Тесты и headless на GitHub | Роль tester, ИИ-ревью тестов, защита тестов, `coverage.yaml`, верификатор с отчётами до ревьюера, контракт ревьюера с disposition и `delivery_narrative`, запечатывание change-set и привязка вердиктов к дайджесту, ревизия и lock `change.yaml`, receipt запусков, политика одного транспортного повтора, статусы `parked`, `stopped`, `delivery_unknown`, адаптеры сред Claude и Codex с надзором за процессами, `run`, `stop`, `watch`, адаптер GitHub с `git worktree` и идемпотентной доставкой, каналы `cli` и `pr-comments`, архивация в пул-реквесте, CI `sync` на GitHub Actions, Docker-образ и GitHub Action | Изменение в `sync` проходит от тикета до готового к влитию пул-реквеста, человек участвует только на гейтах |
 | 3. Дискавери и правила | `discover` с дельтами и решениями, критерии достаточности, `discover validate`, повышение решений и проверка правил, `doctor --deep` | Изменение в `sync` по брифу проходит профиль `autonomous` без блокера `пользователь` |
-| 4. Arcadia и Magic | Адаптер Arcadia с отдельным `arc mount` на изменение и идемпотентной доставкой в Arcanum, канал `tracker` с проекцией статуса тегами, материалы для Codex | Изменение в Magic проходит headless до готового к влитию пул-реквеста |
+| 4. Arcadia и Magic | Адаптер Arcadia с отдельным `arc mount` на изменение и идемпотентной доставкой в Arcanum, канал `tracker` с проекцией статуса тегами (материалы Codex реализованы отдельно) | Изменение в Magic проходит headless до готового к влитию пул-реквеста |
 | 5. Несколько репозиториев | Координация, события, опрос и `github-dispatch` | Согласованное изменение в двух репозиториях доходит до двух пул-реквестов с правильным порядком мержа; проект для проверки выбирается, когда он появится |
 | 6. Расширения | Схема `bugfix` с причинным контрактом и RED-оракулом, wiki и дистилляция, шина событий для Arcadia (адаптер OpenSpec реализован досрочно) | Порядок определяют потребности пилотов |
 
@@ -904,3 +915,17 @@ summary и read_when пишет автор или агент: CLI не гене
 Применение сериализуется файлом `.sbox-contract.lock` в корне проекта с PID владельца. При аварийном завершении lock остаётся: после проверки завершения процесса его можно удалить. Сервис повторно читает состояние под блокировкой, проверяет revision и валидацию, снимает копию затрагиваемых файлов, применяет и проверяет результат. При исключении файлы восстанавливаются, новые удаляются. Запись через симлинки и за пределы корня проекта запрещена. Эта блокировка общая для standalone CLI и доставки SDD; внешние редакторы её не соблюдают. Это откат при обработанной ошибке, не crash-safe транзакция файловой системы.
 
 В текущую версию не входят межформатная конвертация, семантический поиск, автоматический merge конкурирующих дельт и выгрузка во внешнюю систему. Архивация задачи и принятие решения о готовности остаются в SDD.
+
+## 18. Профили моделей по раннерам
+
+Единый модуль `src/core/model-policy.ts` содержит профили simple/medium/complex, дефолты и функцию resolveModel. Роль определяет профиль, раннер — пару model + effort. Настройки находятся в `runner.claude.profiles` и `runner.codex.profiles`; частично заданные профили дополняются дефолтами. extraConfig Codex не может переопределять model/model_reasoning_effort в обход профиля. Уровни effort проверяются по раннеру (Claude: low/medium/high/xhigh/max; Codex: none/minimal/low/medium/high/xhigh); доступность модели и поддержка конкретного сочетания на стороне провайдера локально не проверяются.
+
+Порядок выбора: явный `runner.roleProfiles[role]`; иначе complexity.implementation для implementer/tester (простая → simple, обычная → medium, высокая → complex); иначе дефолт роли. Planner, challenger и reviewer по умолчанию complex, distiller simple, остальные medium. RoleProfiles фиксирует профиль даже при повышенной оценке сложности. Автоматические возвраты только повышают complexity; размер small/normal/large управляет артефактами, а не бюджетом модели. Профиль не назначает модель другому раннеру.
+
+Пакет и `sbox next --brief` содержат execution: runner, profile, model, effort, agent. `--runner` у next выбирает среду явно, без флага используется runner.default. Headless передаёт model и effort из того же пакета адаптеру. `sbox models [--runner claude|codex] [--change id]` показывает выбор всех ролей; без --change используются дефолты ролей/явные roleProfiles.
+
+Для Claude Code `host install` создаёт по три варианта каждой активной роли (`sbox-<role>-simple|medium|complex`) и базовое имя с дефолтным профилем роли. Model сохраняется точно, без замены полного идентификатора псевдонимом opus/sonnet. Скилл sbox-run вызывает next с --runner текущего хоста и запускает имя из execution.agent. После изменения конфига нужно обновить материалы хоста. Для Codex генерируются TOML-агенты тех же ролей и профилей; execution.agent содержит их имя. Headless использует ту же политику.
+
+Headless рассматривает последнюю сессию роли и продолжает её только при совпадении роли, раннера, модели, профиля и effort. Старые записи без профиля/effort не используются для resume. Выбор сохраняется в receipt и истории запусков, в журнале печатаются профиль, модель и effort. Для интерактивного отчёта отдельно сохраняется requested_execution из выданного пакета: это запрошенные настройки, а не подтверждение фактического исполнения хостом. Поля фактического раннера/модели остаются необязательными.
+
+Общие runner.models, runner.efforts, runner.defaultEffort отклоняются с инструкцией перейти на профили. Они не игнорируются и автоматически не переносятся, поскольку старая таблица не определяет принадлежность модели раннеру. Базовые идентификаторы моделей SDD сохранены; simple использует прежнюю обычную модель с low, medium — с medium, complex — прежнюю сильную с high. Явные настройки проекта сохраняют приоритет. Это начальная политика качества, не результат измерения качества моделей. complexity.review сохраняется для анализа рисков, но не снижает профиль reviewer. Референс и отличия: docs/research/agentic-openspec-models.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-box/sdd",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "@spec-box/sdd: автономная реализация продуктовых фич ИИ-агентами",
   "type": "module",
   "license": "MIT",