# 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` обновляет.