claude-harness/openspec/changes/dsh-sdd/design.md

Design: DSH-native SDD

Context

Claude-SDD (~/.dsh/skills/subagent-driven-development/SKILL.md) опирается на синхронный Task: контроллер вызвал implementer'а и в том же ходе получил отчёт. DSH так не умеет — и это не деталь, а другая форма исполнения.

Что измерено в DSH 0.2.1-rc.3 (@deepseek-ai/dsh-tool-subagent, dsh-subagent, dsh-tool-workflow, dsh-workflow-ptc):

Свойство	Значение в DSH	Следствие для SDD
subagent возвращает	started subagent <id> сразу, результат — уведомлением позже	нет синхронного ожидания; ход контроллера заканчивается
Продолжение ребёнка	send_message (провайдер spawn continuable)	раунды фикса идут в того же implementer'а
subagent_fork	наследует завершённые ходы родителя	для implementer'а не годится: нужен свежий контекст
subagent.maxDepth	по умолчанию 1 (настройка сервиса, volatile)	контроллер-сабагент не позовёт implementer'а, пока не поднято до 2
Выбор модели у subagent	только при modelSelectionSettings: true на строке tool-subagent; иначе ребёнок наследует модель сессии	«укажи модель в dispatch» невыполнимо без правки профиля
workflow	синхронный, один вызов инструмента; agent(prompt, {schema, provider, model, label, phase})	годится для детерминированного fan-out с выбором модели без настроек
Кэпы workflow	maxTotalAgents, maxConcurrentAgents, maxItemsPerCall	backstop для веера; для 3 задач не упираемся
Наблюдение за детьми	list_agents, interrupt_agent, уведомления	«дождаться» = закончить ход и проснуться от уведомления
Модели в окружении	deepseek-official/deepseek-flash, deepseek-official/deepseek-v4-pro	три тира роли схлопываются в два

Строка subagent-model-selection-settings есть в web/desktop-профиле и отсутствует в headless. Поэтому флаг modelSelectionSettings нельзя ставить в бандл: headless упадёт на загрузке с «requires … in the Host scope». Он живёт в opt-in overlay профиля.

Goals / Non-Goals

Goals

• Инструкция, по которой DSH-сессия исполняет план без вранья о возможностях платформы: два режима контроллера, протокол отчётов, ревью задачи, fix-loop, ledger с ## Findings, финальное ревью.
• Проверяемый прогон: план из 3 задач в temp-репозитории, дефект найден ревьюером и закрыт в fix-loop.
• Тесты, идущие без DSH runtime.
• Явная таблица отличий от Claude-SDD.

Non-Goals

• Паритет с Task: его не будет, и это фиксируется, а не имитируется.
• Переписывание ~/.dsh/skills/subagent-driven-development/ — skill superpowers остаётся как есть; DSH-семантика живёт в отдельном skill.
• Правка roles/dev.md в общем слое: роль для DSH — слой ~/.dsh/roles.
• Автоматическое включение выбора модели и глубины: это решение владельца.

Решения владельца (brainstorming 24.10.2026)

• Режим контроллера зависит от контекста, а не один на всех. Одна сложная задача — контроллер главная сессия. Несколько задач параллельно, каждая по SDD, — контроллер фоновый сабагент на задачу.

Design

Режим 1 — главная сессия контроллер

Главная сессия читает план, ведёт ledger, диспатчит subagent (depth 1, укладывается в дефолтный maxDepth: 1), получает уведомление, диспатчит ревьюера, при находках — send_message implementer'у. Плюс: рулинги по конфликтам плана принимает тот, у кого есть спека и контекст. Минус: контекст главной сессии растёт, поэтому отчёты — файлами, а в контекст возвращается только статус, коммиты и одна строка тестов.

Режим 2 — фоновый контроллер

Один subagent на план, maxDepth: 2. Контроллер не блокируется: диспатч implementer'а возвращает id, ход заканчивается, уведомление о завершении начинает следующий ход. Пропущенное уведомление ловится list_agents перед следующим диспатчем. Главная сессия в это время свободна для другой задачи.

Протокол (общий для обоих режимов)

1. Setup: ledger .superpowers/sdd/<plan>/progress.md, первая строка — путь плана; скан плана на конфликты (таблица в ledger, рулинги до Task 1).
2. Dispatch implementer'а: brief файлом, отчёт файлом, контракт — DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED.
3. Ревью задачи: пакет диффа файлом, вердикт по спеке и по качеству, находки T<n>.<k>.
4. Fix-loop до 5 раундов: раунды 1–3 — тот же implementer через send_message, 4–5 — свежий и на тир выше; затем адъюдикация.
5. Финальное ревью ветки: C-n/I-n/M-n, один fix-диспатч, одно скоуп-ревью.
6. Ledger: ## Findings с маркером и статусом; рулинги R-n (design #n).

Модели

Два маршрута вместо трёх тиров:

Роль в SDD	Маршрут	Почему
implementer по готовому коду из плана	deepseek-official/deepseek-flash	транскрипция + тесты
implementer по прозе, интеграция	deepseek-official/deepseek-v4-pro	решение в нескольких файлах
ревью задачи, ре-ревью	deepseek-official/deepseek-v4-pro	вердикт важнее цены
финальное ревью ветки	deepseek-official/deepseek-v4-pro	самый широкий дифф

Без overlay всё идёт на модели сессии (deepseek-flash); тиры становятся недоступны, и инструкция это явно говорит, а не молча игнорирует.

Где живёт

dsh/skills/sdd/SKILL.md — в репозитории обвязки, ставится dsh/install.sh --skills в ~/.dsh/skills. Claude Code его не получает: DoD порта требует, чтобы CC-харнес не менялся.

Альтернативы

• Только workflow. Детерминированный fan-out силён для независимых задач, но решения по конфликтам плана, адъюдикация находок и «стоп, план врёт» требуют суждения в моменте. Скрипт может ветвиться по структурному ответу ревьюера, но не может решить, что находка неверна.
• Только фоновый контроллер. Дороже на одну задачу и требует поднятой глубины; для одиночной задачи лишний уровень.
• Гибрид. workflow — для веера независимых задач внутри плана, контроллер — для последовательной петли. Держим как расширение, в первой версии не включаем: веер ещё не встречался в планах этого репозитория.

Риски

• Уведомление о завершении ребёнка не пришло (обрыв, компакция) — контроллер обязан сверяться с list_agents и git, а не с памятью.
• maxDepth: 2 не поднят, а режим 2 выбран — диспатч упадёт subagent depth 2 exceeds maxDepth 1; инструкция требует проверить до старта и откатиться в режим 1 с записью рулинга.
• Ledger лежит в git-ignored scratch: git clean -fdx его уничтожает; восстановление — по git log.
• Модели две: «haiku» из Claude-текста не существует, перенос формулировок тиров без таблицы превратится в фикцию.

Что должен доказать пробный прогон

Пункт приёмки #41	Чем доказывается
3 задачи не теряются	ledger: три Task N: complete, три коммита
отчёты собираются	файлы отчётов implementer'ов + строки в ledger
ревьюер находит дефект	T1.1 с fixed <commit>
fix-loop завершается	раунд в ledger, ре-ревью чистое
ledger содержит ## Findings со статусами	сам файл
отличие от Claude-SDD указано	таблица выше + раздел в skill

Decisions made without discussion

• 24.10.2026 — overlay вместо флага в бандле. Обоснование: headless-профиль не содержит строку subagent-model-selection-settings, включённый флаг роняет загрузку. Цена ошибки: владельцу нужно скопировать три записи в профиль руками; забыл — работает на модели сессии.
• 24.10.2026 — карта тиров. flash — транскрипция и механика, v4-pro — интеграция и все ревью. Цена ошибки: дороже прогон или слабее ревью; правится одной таблицей в skill.
• 24.10.2026 — skill ставится только в ~/.dsh. Обоснование: DoD порта запрещает менять CC-харнес. Цена ошибки: в Claude-сессиях инструкции про DSH-режимы нет — там работает исходный subagent-driven-development.
• 24.10.2026 — гибрид отложен. workflow описан как расширение, не реализуется в этом change. Цена ошибки: веер задач придётся ввести позже отдельной правкой skill.

Открытые вопросы

• Нужно ли после приёмки добавить в ~/.dsh/roles/dev.md строку «в DSH исполнение плана — skill sdd» (сейчас роль ссылается на superpowers-SDD).