docs(dsh): git-источник superpowers — README, PORT, приёмка (#67)

dsh/PORT.md

@@ -210,11 +210,14 @@ with "requires ... in the Host scope".
 real files there; the Claude Code locations are a legacy fallback and the
 bundle logs one warning per process when it resolves one of them.
 
-Install-time source resolution is separate and stricter (change
-`dsh-install-source`): `--superpowers-from` → `$DSH_SUPERPOWERS_SOURCE` →
-`$DSH_HOME/superpowers/skills` → the legacy cache → `~/.claude/skills`. An
-invalid explicit source is a hard `FAIL`; no source at all is a `FAIL` on a
-fresh install and a `WARN` when `~/.dsh/skills` already holds the skills.
+Install-time source resolution is separate and stricter (changes
+`dsh-install-source` and `dsh-superpowers-git`): `--superpowers-from` →
+`$DSH_SUPERPOWERS_SOURCE` → the managed git checkout `$DSH_HOME/superpowers`
+(clone or `fetch`+`reset` from `$DSH_SUPERPOWERS_REPO`) → the legacy cache →
+`~/.claude/skills`. An invalid explicit source is a hard `FAIL`; a failed git
+update reuses the cached checkout (`WARN`); no source at all is a `FAIL` on a
+fresh install and a `WARN` when `~/.dsh/skills` already holds the skills. The
+git sha of the checkout is printed by `--skills` and by the offline `--check`.
 
 ### OpenSpec skills
 
@@ -243,20 +246,21 @@ openspec archive <id> -y
 
 ## 6. Install and verify
 
-Prerequisites: the `claude-harness` checkout, a superpowers source, DSH
-0.2.1-rc.3, `python3`, `git`, Node. Claude Code is not required at all: get the
-superpowers source once with
-`git clone --depth 1 https://github.com/obra/superpowers ~/.dsh/superpowers`,
-then `--skills --roles` copy everything into `~/.dsh`; the hooks come from this
-checkout.
+Prerequisites: the `claude-harness` checkout, DSH 0.2.1-rc.3, `python3`, `git`,
+Node, and network access for the superpowers checkout. Claude Code is not
+required at all: `--skills` clones `https://github.com/obra/superpowers` into
+`~/.dsh/superpowers` on the first run and updates it on later runs
+(`DSH_SUPERPOWERS_REPO` for a mirror); `--superpowers-from` /
+`DSH_SUPERPOWERS_SOURCE` skip the network. `--roles` copies roles; the hooks
+come from this checkout.
 
 ```bash
 # 1. Static checks
 bash dsh/install.sh --check
 
 # 2. Global instructions, skills, and roles (run from a terminal; writes
-#    outside the session workspace). The superpowers source comes from
-#    --superpowers-from, DSH_SUPERPOWERS_SOURCE, or ~/.dsh/superpowers.
+#    outside the session workspace). --skills clones/updates ~/.dsh/superpowers;
+#    --superpowers-from or DSH_SUPERPOWERS_SOURCE skip the network.
 bash dsh/install.sh --global
 bash dsh/install.sh --skills                      # or: --skills --superpowers-from DIR
 bash dsh/install.sh --roles
@@ -361,6 +365,11 @@ profile was removed; the real `desktop` profile was not touched.
 - **Model tiers.** `sonnet`/`haiku`/`opus` are not DSH models. The port uses two
   live routes (`deepseek-flash`, `deepseek-v4-pro`) from the opt-in overlay in
   `dsh/subagent-models.yml`; without it every dispatch runs on the session model.
+- **Install needs network (or a source).** `--skills` clones/fetches from
+  `DSH_SUPERPOWERS_REPO`; on an air-gapped or rate-limited machine use a mirror
+  or `--superpowers-from`. The checkout is shallow and updated by
+  `fetch`+`reset --hard`, so local edits inside it are lost; a fresh upstream
+  commit is taken as-is, and `--superpowers-from` pins a known-good copy.
 - **`~/.claude` dependence.** No longer needed for install, bootstrap, or
   roles: the install-time source is explicit, and `--skills --roles` copy real
   files into `~/.dsh`. The Claude Code locations remain a **legacy migration
@@ -398,3 +407,6 @@ profile was removed; the real `desktop` profile was not touched.
    `--superpowers-from`/`DSH_SUPERPOWERS_SOURCE`/`~/.dsh/superpowers`, hard
    `FAIL` instead of a silent empty bootstrap, DSH-owned role paths in the
    installed `AGENTS.md`, legacy warnings at install and runtime.
+10. Install pulls superpowers from git — **done** (change `dsh-superpowers-git`):
+   clone/update `$DSH_HOME/superpowers` from `DSH_SUPERPOWERS_REPO`, `--check`
+   stays offline and reports the sha, explicit sources skip the network.

dsh/README.md

@@ -33,19 +33,19 @@ risks.
 # Static check
 bash dsh/install.sh --check
 
-# Superpowers source: get it once per machine. install.sh never downloads
-# anything and no longer depends on ~/.claude.
-git clone --depth 1 https://github.com/obra/superpowers ~/.dsh/superpowers
-# ...or point at any checkout of the superpowers repo / its skills directory:
-bash dsh/install.sh --skills --superpowers-from /path/to/superpowers
-# ...or export DSH_SUPERPOWERS_SOURCE=/path/to/superpowers
-
 # Global instructions, superpowers skills, local role skill, and roles
-# (run from a terminal; these write outside the session workspace)
+# (run from a terminal; these write outside the session workspace).
+# --skills clones https://github.com/obra/superpowers into ~/.dsh/superpowers
+# on the first run and updates that checkout on every later run.
 bash dsh/install.sh --global
 bash dsh/install.sh --skills
 bash dsh/install.sh --roles
 
+# Offline, mirror, or pinned version: skip the network entirely.
+bash dsh/install.sh --skills --superpowers-from /path/to/superpowers
+# or: DSH_SUPERPOWERS_SOURCE=/path/to/superpowers bash dsh/install.sh --skills
+# or: DSH_SUPERPOWERS_REPO=https://mirror/superpowers.git bash dsh/install.sh --skills
+
 # В корне проекта, где уже есть openspec/: добавить agents-скиллы
 bash <harness>/dsh/install.sh --openspec
 
@@ -55,10 +55,11 @@ bash <harness>/dsh/install.sh --openspec
 ```
 
 `--skills` resolves superpowers in this order: `--superpowers-from` →
-`$DSH_SUPERPOWERS_SOURCE` → `~/.dsh/superpowers` → the Claude Code plugin cache
-(legacy, warns). A clean HOME with no source and no installed copy fails with
-the clone command above instead of pretending success; the local `role` and
-`sdd` skills are copied either way.
+`$DSH_SUPERPOWERS_SOURCE` → the git checkout `~/.dsh/superpowers` (clone or
+`fetch`+`reset` from `$DSH_SUPERPOWERS_REPO`) → the Claude Code plugin cache
+(legacy, warns). With no network and no other source, an existing checkout is
+reused with a warning and a fresh install fails instead of pretending success;
+the local `role` and `sdd` skills are copied either way.
 
 Do not hand-edit `$DSH_HOME/profiles/desktop/package.json` or
 `cordis.patch.yml`: the Desktop profile is Electron-managed and the plugin
@@ -156,11 +157,13 @@ repository layout:
   bundle needs a real copy of `hooks/` (already listed in `package.json`
   `files`).
 - `using-superpowers` is read from `~/.dsh/skills` after `--skills`. The
-  install-time source is `--superpowers-from`, `DSH_SUPERPOWERS_SOURCE`, or
-  `~/.dsh/superpowers`; Claude Code locations are a **legacy migration
-  fallback** and log one warning per process when used, so a partial Claude
-  Code rollback does not break the bootstrap. Set `bootstrapSkillPath` or
-  `DSH_SUPERPOWERS_SKILL` for another layout.
+  install-time source is `--superpowers-from`, `DSH_SUPERPOWERS_SOURCE`, or the
+  managed git checkout `~/.dsh/superpowers` (`DSH_SUPERPOWERS_REPO`, default
+  GitHub), which `--skills` clones/updates and reports as `git <sha>`. `--check`
+  is offline and reports that sha. A manual copy of `~/.dsh/superpowers` without
+  `.git` is used as-is and never updated. Claude Code locations are a **legacy
+  migration fallback** and log one warning per process when used. Set
+  `bootstrapSkillPath` or `DSH_SUPERPOWERS_SKILL` for another layout.
 - Roles resolve `~/.dsh/roles` first; `~/.claude/roles` and the repository
   `roles/` are fallbacks. After `--roles` the runtime never needs `~/.claude`.
 - Role loading is model-driven through the `role` skill; there is no automatic

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

@@ -109,3 +109,16 @@ legacy-источнику — сообщение называет репозит
 - `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` на сетевой резолвер.