claude-harness/openspec/changes/archive/2026-10-24-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

Результаты пробного прогона 24.10.2026

Площадка — /tmp/dsh-sdd-trial: отдельный git-репозиторий, ветка feat/trial, база main; модуль src/stats.py из трёх задач. Контроллер — главная сессия (Режим 1), overlay профиля включён (model selection + maxDepth: 2), deepseek-flash — implementer'ы, deepseek-v4-pro — все ревью. Артефакты скопированы в trial/: SPEC.md, plan.md, брифы, отчёты implementer'ов и ревьюеров, ledger.md (первая строка — путь плана, ## Findings, ## Rulings).

Диспатчи

Шаг	Агент	Маршрут	Результат
Task 1 implementer	1c906f6f	flash	DONE, dc1670f, 2 теста OK
Task 1 review	68a1aeb4	v4-pro	APPROVED, находок нет
Task 2 implementer	1ec8f7fc	flash	DONE, 836a730, 4 теста OK, concern: план противоречит спеке на чётной длине
Task 2 review	e50c74d2	v4-pro	CHANGES_REQUESTED: T2.1, T2.2 (проверено независимо от concerns)
Task 2 fix, раунд 1	1ec8f7fc (send_message)	flash	186575c, 6 тестов OK
Task 2 re-review (скоуп)	7912c16b	v4-pro	APPROVED: T2.1 fixed 186575c, T2.2 fixed 186575c
Task 3 implementer	6ca07edc	flash	DONE, 7cb0383, 7 тестов OK
Task 3 review	f10e3165	v4-pro	APPROVED, находок нет
Final branch review	0fec8102	v4-pro	APPROVED, находок нет

Приёмка #41

Пункт приёмки	Чем доказан	Статус
3 задачи не теряются	ledger Task 1..3: complete, 4 коммита dc1670f/836a730/186575c/7cb0383	выполнен
отчёты собираются	9 файлов в trial/reports/, статус первой строкой у каждого	выполнен
ревьюер находит и проверяет дефект	T2.1 найден независимо (median([1,2]) == 2.0 вместо 1.5), T2.2 — отсутствие теста; оба fixed 186575c, ре-ревью APPROVED	выполнен
fix-loop завершается	раунд 1 из 5, ре-ревью чистое	выполнен
ledger содержит ## Findings со статусами	trial/ledger.md	выполнен
итоговый прогон зелёный	python3 -m unittest discover -s tests → 7 тестов OK; bash dsh/tests/run.sh и bash tests/run.sh зелёные	выполнен
отличие от Claude-SDD указано	таблица в dsh/skills/sdd/SKILL.md	выполнен

Находки и наблюдения прогона

Маркер	Что	Статус
T2.1	median на чётной длине возвращал верхний средний элемент вместо среднего двух	fixed 186575c
T2.2	не было теста на чётную длину	fixed 186575c
O-1	«Interfaces» плана обещают аннотации типов, «Exact code» их не содержит; SPEC аннотаций не требует	rejected (правка плана в прогоне не даёт результата)
O-2, O-3	первый вызов subagent с переданными provider/model вернул «child LLM provider and model must be supplied together»; немедленный повтор тем же вызовом проходит (2 раза за прогон)	deferred (наблюдение о стабильности валидации DSH; повтор в skill)
O-4	ожидаемое число тестов в плане (5) устарело после fix-раунда Task 2 (фактически 7)	fixed — в skill добавлено правило «число тестов в плане — ориентир»
O-5	тест describe([1,2,3]) на симметричном входе не отличил бы перестановку mean/median	deferred (реализация верна, слабость плана)

Отдельно: implementer Task 2 заметил расхождение плана со спекой, но поставил DONE, а не DONE_WITH_CONCERNS; ревью дефект всё равно поймало, потому что ревьюер проверял по SPEC.md, а не по отчёту. Правило уточнено в skill: замеченное расхождение с брифом — это DONE_WITH_CONCERNS.

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

Отдельная площадка /tmp/dsh-sdd-mode2. Контроллер afe886e5 (flash) вызвал subagent (flash) и получил id; ход закончился, уведомление о завершении пришло отдельным сообщением, после чего контроллер проверил отчёт, коммит 0601d6e и тесты независимо. Глубина 2 работает с overlay; синхронного ожидания нет.

Отличия от дизайна, обнаруженные прогоном

• Число тестов в плане — ориентир: fix-раунд добавляет тесты, и расхождение вверх не дефект (O-4).
• Ошибка валидации provider/model нестабильна; лечится повтором, а не пересмотром маршрутов (O-2/O-3).
• Ревьюер, проверяющий по спеке, а не по отчёту implementer'а, ловит дефекты, даже если implementer промолчал бы.

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).