@spec-box/sdd 0.10.0 → 0.11.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 |
@@ -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` и варианты профилей; скиллы подключаются полем skills. Для Codex генерируются 28 standalone TOML-файлов `.codex/agents/sbox-<role>[-<profile>].toml`: семь активных ролей, базовое имя и три профиля. Имя, описание, model, model_reasoning_effort, sandbox_mode и developer_instructions задаются явно. Скиллы роли фильтруются по хосту и перечисляются путями в инструкциях. Шаблоны живут в 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 зависит от версии клиента; доступность конкретной модели проверяет провайдер при запуске.
 
 ### Отчёты тестов
 
@@ -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.11.0",
   "description": "@spec-box/sdd: автономная реализация продуктовых фич ИИ-агентами",
   "type": "module",
   "license": "MIT",