# Spec Delta: dsh-install

## Purpose

Слой установки DSH-обвязки: откуда берутся superpowers-скиллы и роли, что
делает `dsh/install.sh --skills/--roles`, какие пути попадают в установленные
инструкции. В Claude Code источником служит кэш плагина в `~/.claude`; в DSH
источник задаётся установщиком явно (аргумент, переменная или пиннинг в
`~/.dsh`), а `~/.claude` остаётся только legacy-fallback'ом с предупреждением.
Контракт нужен, чтобы свежая установка на машине без Claude Code проходила
полный цикл #48 и чтобы путь `~/.claude` не возвращался в runtime незаметно.

## ADDED Requirements

### Requirement: Источник superpowers задаётся при установке
`dsh/install.sh --skills` SHALL разрешать источник superpowers-скиллов в
порядке приоритета и MUST NOT исполнять `git clone` и любые сетевые операции.

- Порядок: `--superpowers-from <dir>` → `$DSH_SUPERPOWERS_SOURCE` →
  `$DSH_HOME/superpowers/skills` (пиннинг; допускается и корень
  `$DSH_HOME/superpowers` с подкаталогом `skills/`) → legacy-кэш Claude Code →
  legacy `~/.claude/skills`.
- Для явного источника (`--superpowers-from`, `$DSH_SUPERPOWERS_SOURCE`)
  допускаются обе формы: корень superpowers (есть `skills/using-superpowers/SKILL.md`)
  или сам каталог `skills`.
- Явно заданный, но невалидный источник MUST приводить к `FAIL` и коду
  возврата 1: тихий откат на legacy запрещён.
- Копирование MUST быть заменой каталога назначения (`rm -rf` + `cp -R`), а не
  симлинком: `~/.dsh/skills` не должен зависеть от каталога-источника.

#### Scenario: Явный источник без ~/.claude
- **WHEN** `HOME` — пустой temp-каталог без `~/.claude`, а `--superpowers-from`
  указывает на каталог superpowers
- **THEN** `--skills` копирует скиллы в `$DSH_HOME/skills`, печатает источник и
  завершается кодом 0

#### Scenario: Переменная окружения вместо флага
- **WHEN** задан `DSH_SUPERPOWERS_SOURCE=<dir>` и флаг `--superpowers-from` не передан
- **THEN** источник берётся из переменной; поведение совпадает с флагом

#### Scenario: Флаг важнее переменной
- **WHEN** заданы и `--superpowers-from`, и `DSH_SUPERPOWERS_SOURCE`
- **THEN** используется каталог из флага

#### Scenario: Невалидный явный источник
- **WHEN** `--superpowers-from` указывает на каталог без
  `using-superpowers/SKILL.md`
- **THEN** `--skills` печатает `FAIL` с ожидаемой структурой и завершается
  кодом 1, ничего не копируя из legacy-источников

#### Scenario: Пиннинг в ~/.dsh
- **WHEN** существует `$DSH_HOME/superpowers/skills/using-superpowers/SKILL.md`
  и флаг/переменная не заданы
- **THEN** источником служит этот каталог, `--check` печатает
  `ok: superpowers source (<path>)`

### Requirement: Отсутствие источника не бывает тихим
Если источник superpowers не найден, `--skills` MUST различать первичную и
повторную установку и MUST NOT завершаться успехом молча.

- Если `$DSH_HOME/skills/using-superpowers/SKILL.md` уже существует —
  `WARN` «источник не найден, копии сохранены» и код 0 (идемпотентный повтор).
- Если копий нет — `FAIL` с готовой командой получения источника
  (`git clone --depth 1 https://github.com/obra/superpowers ~/.dsh/superpowers`)
  и код возврата 1.
- Локальные скиллы обвязки (`dsh/skills/*`: `role`, `sdd`) MUST ставиться в
  обоих случаях: они не зависят от superpowers.

#### Scenario: Первая установка без источника
- **WHEN** `HOME` пуст, `$DSH_HOME/skills` не существует, источника нет
- **THEN** `--skills` печатает `FAIL`, код 1, но `$DSH_HOME/skills/role/SKILL.md`
  и `$DSH_HOME/skills/sdd/SKILL.md` на месте

#### Scenario: Повторная установка без источника
- **WHEN** `$DSH_HOME/skills/using-superpowers/SKILL.md` уже есть, источника нет
- **THEN** `--skills` печатает `WARN`, код 0, установленные скиллы не удалены

### Requirement: ~/.claude — только legacy-fallback с предупреждением
superpowers-скиллы и роли MUST иметь рабочий путь `~/.dsh`; пути `~/.claude`
SHALL оставаться fallback'ом для машин, где `--skills --roles` ещё не
перезапускали, и MUST сопровождаться предупреждением.

- Установка: legacy-кэш Claude Code и `~/.claude/skills` допустимы как
  источник, но `--skills` печатает `WARN: legacy superpowers source` с
  подсказкой перейти на пиннинг/флаг.
- `--check`: legacy-источник — `WARN`, явный/пиннинг — `ok`, отсутствие —
  `WARN` с подсказкой, невалидный явный источник — `FAIL` и код 1
  (пользователь задал его сам, подсказка «нет источника» здесь неверна).
- Runtime: bootstrap и резолвер ролей сохраняют порядок `~/.dsh` → `~/.claude`,
  но при выборе legacy-пути один раз за процесс пишут в лог предупреждение.
- Удаление fallback'ов — отдельное изменение; в этом change они не удаляются.

#### Scenario: Legacy-кэш как источник установки
- **WHEN** в `HOME` есть только кэш Claude Code с superpowers, `$DSH_HOME` пуст
- **THEN** `--skills` копирует скиллы и печатает `WARN: legacy superpowers source`

#### Scenario: Runtime-предупреждение
- **WHEN** bootstrap резолвит `using-superpowers` из `~/.claude/...`
- **THEN** в лог один раз за процесс попадает предупреждение с предложением
  выполнить `dsh/install.sh --skills`

#### Scenario: ~/.dsh приоритетнее
- **WHEN** существуют и `~/.dsh/skills/using-superpowers/SKILL.md`, и legacy-копия
- **THEN** используется `~/.dsh`, предупреждения нет

### Requirement: Установленные инструкции DSH не ссылаются на ~/.claude
`dsh/install.sh --global` MUST писать `$DSH_HOME/AGENTS.md` так, чтобы пути
ролей указывали на DSH-слой, а формат инструкций не выдавался за runtime
Claude Code.

- Строки `~/.claude/roles` в установленной копии MUST заменяться на
  `~/.dsh/roles`, а adapter-шапка MUST NOT называть пути `~/.claude`: в
  установленном файле не остаётся ни одного такого пути. `global/CLAUDE.md` в
  репозитории MUST NOT меняться (его читает Claude Code).
- Шапка установленного файла MUST говорить, что проектный `CLAUDE.md` /
  `AGENTS.md` — это формат файлов инструкций DSH, а не запущенный Claude Code,
  и что роли лежат в `~/.dsh/roles` (`--roles`), а superpowers-скиллы — в
  `~/.dsh/skills` (`--skills`).
- Повторный `--global` обязан делать бэкап прежнего `AGENTS.md` (как сейчас).

#### Scenario: Пути ролей после установки
- **WHEN** выполнен `--global` во временный `DSH_HOME`
- **THEN** в `AGENTS.md` есть `~/.dsh/roles/dev.md` и нет ни одного пути
  `~/.claude`

#### Scenario: global/CLAUDE.md не тронут
- **WHEN** выполнен `--global`
- **THEN** `global/CLAUDE.md` в репозитории побайтно не изменился

### Requirement: Чистый HOME без ~/.claude проходит установку
Установка, bootstrap и skill `role` MUST работать на машине, где Claude Code
никогда не устанавливался.

- `--global --skills --roles` с явным источником superpowers в пустом `HOME`
  MUST создавать `$DSH_HOME/{AGENTS.md,skills/using-superpowers/SKILL.md,skills/role/SKILL.md,skills/sdd/SKILL.md,roles/dev.md}`.
- bootstrap MUST резолвить скилл из `$DSH_HOME/skills` при `home` этого HOME и
  MUST NOT обращаться к `~/.claude`.
- Резолвер ролей MUST находить `$DSH_HOME/roles` при `home` этого HOME.

#### Scenario: Установка в чистый HOME
- **WHEN** `HOME` — пустой temp-каталог, `DSH_HOME=$HOME/.dsh`,
  `--superpowers-from` указывает на каталог superpowers
- **THEN** `--global --skills --roles` завершается кодом 0, все перечисленные
  файлы на месте, `--check` зелёный по skills и roles

#### Scenario: Bootstrap в чистом HOME
- **WHEN** `prepareBootstrap({ home: <temp HOME> })` вызывается после установки
- **THEN** выбранный путь — `$HOME/.dsh/skills/using-superpowers/SKILL.md`,
  текст содержит маркер `<!-- DSH-HARNESS-BOOTSTRAP:... -->`, предупреждений о
  legacy нет