claude-harness/openspec/changes/dsh-superpowers-git/design.md

Design: install тянет superpowers с git

Issue: #67. Спека: openspec/changes/dsh-superpowers-git/specs/dsh-install/spec.md. Контекст: #49 (dsh-install-source) — источник был явным, сеть в установке запрещена; это решение пересматривается по команде владельца 24.10.2026.

1. Что меняется в контракте #49

	#49	#67
Источник по умолчанию	ручной клон/флаг	git: клон в $DSH_HOME/superpowers
Обновление	нет	fetch --depth 1 + reset --hard FETCH_HEAD при каждом --skills
Сеть в установке	запрещена	разрешена только для git-источника
Явный источник	главнее	главнее, сеть не трогает
--check	офлайн	офлайн + git sha
Офлайн-машина	явный источник	кэш клона (WARN) → legacy (WARN) → FAIL

2. Решения

D-7 (решение владельца). Git — источник по умолчанию

--skills без флага/переменной клонирует репозиторий и обновляет его при следующих запусках. Обоснование владельца: ручной клон не обновляется и оставляет WARN: legacy superpowers source навсегда. Цена: установка требует сеть (кроме явного источника и кэша), а свежий апстрим может принести несовместимость — она лечится --superpowers-from на любой коммит.

D-8. Явный источник полностью отключает сеть

--superpowers-from и $DSH_SUPERPOWERS_SOURCE проверяются первыми и, если валидны, git не вызывается вообще. Это и офлайн-путь, и отладка, и пиннинг на конкретную версию. Цена: две ветки кода, покрыты тестами, включая «явный источник не создаёт $DSH_HOME/superpowers».

D-9. Офлайн не ломает установку, если есть чем ставить

Порядок при недоступном git: существующий клон (в т.ч. с неудачным fetch) → legacy-кэш CC → ~/.claude/skills → FAIL. Первые два шага печатают WARN с причиной (репозиторий), чтобы деградация была видна, но машина без сети продолжала работать. Цена: опечатка в DSH_SUPERPOWERS_REPO может привести к legacy-источнику — сообщение называет репозиторий и путь кэша.

D-10. Ручная копия без .git — пиннинг, а не ошибка

Если $DSH_HOME/superpowers существует, валиден, но не является git-клоном, он используется как есть с WARN, что обновляться не будет. Это совместимость с #49: у кого уже лежит ручная копия, после обновления обвязки установка не падает. Цена: такой каталог стареет молча — предупреждение на каждом --skills.

D-11. --check остаётся офлайновым

--check — диагностика; клонировать или обновлять из него нельзя (в #42 уже принято: --check не должен иметь побочных эффектов). Он показывает ok: superpowers source (<path>, git <sha>) для клона, WARN для ручной копии и для legacy, и подсказку про --skills/DSH_SUPERPOWERS_REPO, когда клона нет. Цена: --check не скажет, доступен ли репозиторий; это выясняется при установке.

D-12. Тесты идут через локальный file://-репозиторий

DSH_SUPERPOWERS_REPO — не только фича для зеркал, но и тестовый шов: набор не ходит в GitHub. Тестовый хелпер создаёт git-репозиторий с skills/*/SKILL.md, запускает --skills с DSH_SUPERPOWERS_REPO=file://<путь>, затем добавляет коммит и проверяет обновление копий. Офлайн-кейс — репозиторий, которого нет.

3. Решения, принятые без обсуждения

• 2026-10-24. --depth 1 и reset --hard FETCH_HEAD, без тегов и подписей. «Свежая версия» = последний коммит default-ветки; глубина 1 экономит сеть, reset --hard гарантирует чистое управляемое дерево. Цена: локальные правки в ~/.dsh/superpowers теряются, подлинность апстрима не проверяется (TLS и доверие к GitHub); откат — --superpowers-from на известный коммит.
• 2026-10-24. Неудачный первый клон удаляет каталог. rm -rf $DSH_HOME/superpowers после неудачи, чтобы следующий запуск снова клонировал, а не принимал половину за кэш. Цена: если пользователь положил туда что-то своё и не было .git — этот путь не трогается (D-10), удаление только для созданного нами каталога в текущем запуске.
• 2026-10-24. Отдельного флага --offline нет. Офлайн покрыт существующим клоном (D-9) и явным источником (D-8). Цена: нет способа гарантированно запретить сеть, кроме явного источника; для установки это приемлемо.
• 2026-10-24. DSH_SUPERPOWERS_REPO виден и в --check. В WARN/FAIL печатается фактический репозиторий, чтобы зеркало и опечатка различались. Цена: строка вывода зависит от env — приемлемо.
• 2026-10-24. tasks.md OpenSpec не заполняется (как в прошлых change): задачи в плане superpowers.

4. Риски

• Свежий апстрим ломает установку. --skills тянет последний коммит; если superpowers переименует skills/using-superpowers, FAIL скажет, что искать. Обход — --superpowers-from с проверенной копией; sha в выводе помогает зафиксировать версию.
• Сеть в установке. Машины без доступа к GitHub должны использовать DSH_SUPERPOWERS_REPO (зеркало) или --superpowers-from; ошибка клона называет репозиторий и оба пути.
• Тесты и сеть. Любой тест, забывший выставить DSH_SUPERPOWERS_REPO, уйдёт в GitHub. Поэтому installerEnv в тестах задаёт недоступный repo по умолчанию, а тесты git-источника — file://-фикстуру; проверяется, что --check не создаёт клон.
• Офлайн-деградация незаметна. WARN есть на каждом шаге деградации; --check показывает, какой источник будет использован при следующем --skills.
• Совместимость с #49. Ручная копия без .git и legacy-кэш остаются рабочими; тесты #49 переиспользуются, меняются только ожидания сообщений.

5. Приёмка

• openspec validate dsh-superpowers-git --strict — change валиден.
• bash dsh/tests/run.sh — зелёный, включая клон/обновление/офлайн/--check.
• bash tests/run.sh — регрессий в CC-контуре нет.
• Живой прогон на машине владельца: --skills клонирует GitHub-репозиторий, --check показывает git <sha>, повторный --skills обновляет.

Приёмка: прогон 24.10.2026

• openspec validate dsh-superpowers-git --strict — change валиден.
• bash dsh/tests/run.sh — 71/71 pass; bash tests/run.sh — см. PR.
• Живой клон GitHub в temp HOME без ~/.claude: --skills → 15 superpowers-скиллов, source: .../.dsh/superpowers/skills, git 2ce8aa1; повторный --skills → обновление того же клона, снова git 2ce8aa1; --check → ok: superpowers source (.../.dsh/superpowers/skills, git 2ce8aa1).
• Тесты сети не касаются: installerEnv подставляет недоступный DSH_SUPERPOWERS_REPO, git-кейсы — локальный file://-репозиторий; мутацией проверено, что --check never clones on an empty HOME падает, если вернуть --check на сетевой резолвер.