docs(openspec): change dsh-port-v2 — дизайн варианта C, решения владельца (#69)

openspec/changes/dsh-port-v2/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-24

openspec/changes/dsh-port-v2/design.md

@@ -0,0 +1,67 @@
+# Design: DSH port v2 — вариант C
+
+Issue: #69. Статус: **черновик**, ждёт builder-check и утверждения владельца.
+
+## Контекст
+
+Ревью 24.10.2026: RV-1 (своя доставка superpowers без пина и адаптации),
+RV-6 (legacy-фолбэки как техдолг), RV-11 (нет compat-чека против DSH SDK).
+Владелец выбрал вариант C: машинерию готового порта
+[LayneChai/superpowers-dsh](https://github.com/LayneChai/superpowers-dsh)
+взять как форк/вендор, sync гонять самим. Чистка трекера подтверждена и
+выполнена 24.10.2026 (см. комментарий в #69; сводная — #70).
+
+## Что вендорим
+
+Из LayneChai/superpowers-dsh (MIT):
+
+- `scripts/sync-from-upstream.mjs` — ассертные transform-ы (якорь не совпал
+  ровно один раз → FAIL), skip-список чужих harness-референсов,
+  staging-swap (назначение меняется только при всех пройденных ассертах),
+  проверка «невзорвавшихся» transform-ов, сверка набора скиллов;
+- `scripts/verify-skills.mjs` — provider видит все скиллы, frontmatter
+  валиден, нет висячих ссылок;
+- `scripts/check-dsh-compat.mjs` — **не вендорим как есть**: он написан под
+  SkillProvider LayneChai (у нас его нет — скиллы читает встроенный
+  skill-filesystem) и требует SDK вне app.asar (терминал всегда SKIPPED);
+  его идея — сверка контракта с установленным DSH — переезжает в
+  самопроверку бандла (D-6).
+
+Адаптация под нас:
+
+- наши transform-ы, где их текст расходится с нашим (главное: их
+  `using-superpowers`-rewrite остаётся, но reference указывает на наш
+  `dsh-tools.md` из `dsh/bundle/`, а не на их `port/overrides/`);
+- пути — `dsh/sync/`; скиллы кладутся не в пакет, а в
+  `$DSH_HOME/skills` (источник текста для bootstrap-инъекции бандла
+  остаётся единым — как сейчас).
+
+## Decisions made without discussion
+
+| # | Решение | Обоснование | Цена ошибки |
+|---|---|---|---|
+| D-1 | Вендор в `dsh/sync/`, не зависимость от npm-пакета LayneChai | MIT разрешает; их каденс не наш (уже на патч позади: v7.0.0 при свежем v7.0.1); форк-стоимость мала (~3 скрипта) | Содержим sync-скрипты сами; escape-люк на их пакет остаётся |
+| D-2 | Пин на тег (v7.0.1) через `DSH_SUPERPOWERS_REF`; #67 — rejected | Воспроизводимость; unpinned HEAD = случайная семантика | Каждый релиз upstream — свой issue+PR; пропустили релиз = молча старый текст (митигируется `--check`) |
+| D-3 | Результат sync — в `$DSH_HOME/skills`; bootstrap бандла не меняется | Один источник текста; install.sh остаётся инсталлятором, а не публикуемым пакетом | Нет |
+| D-4 | Legacy-фолбэки `~/.claude/*` живут до #66, удаляются им | #49 уже ввёл их с WARN; рубить сейчас = сломать машины без переустановки | Техдолг висит дольше; контракт удаления — в #66 |
+| D-5 | `dsh/sync/` и `dsh/bundle/` добавляются в `.claude/code-paths` | Сейчас require-plan защищает только `hooks/` и `skills/`; вендоримый код обязан быть под хук | Без этого правки sync-скриптов не гейтятся планом |
+| D-6 | Compat-чек (решение владельца 24.10.2026): **самопроверка бандла внутри DSH** — при активации и по команде проверяет контракт, на который бандл опирается (`ctx.tools.guard`, `agent/pre-step`, `session.surface.nodes`, `ctx.commands`, `workingDirectory`); терминальный `--check` гоняет только verify synced-скиллов (frontmatter, префиксы, висячие ссылки) и окружение | SDK DSH лежит в app.asar, терминал до него не дотягивается — проверка контракта возможна только изнутри DSH; это закрывает RV-11 по-настоящему | Бандл тронут аддитивно (активационный assert + команда) — «не трогаем бандл» смягчено до «без изменения существующего поведения» |
+| D-7 | Каденс: issue на каждый релиз obra/superpowers; compat — после апгрейда DSH | Ритм без напоминаний; влезает в обычный цикл фичи | Пропущенный релиз не виден между ретро — добавить строку в `--check`/doctor (#44) |
+| D-8 | Болевые точки эксплуатации заранее не фиксируются: ответ владельца 24.10.2026 — «пока трудно сказать, идёт разработка только самого харнеса». План сосредоточен на машинерии порта; первые реальные затыки DSH-сессий копятся в #69 и двигают приоритеты | Не выдумывать боли за владельца, пока нет сигнала | Задачи плана упорядочены без пользовательского приоритета — по зависимостям и P-классам находок |
+| D-9 | Модели исполнителей (указание владельца 24.10.2026 «простые задачи — дешёвой модели»): механика и простые правки — `deepseek-official/deepseek-flash`, интеграция и ревью — `deepseek-official/deepseek-v4-pro`; фиксируется в брифах плана | Экономия на рутине без потери качества ревью | Сложность недооценена → flash не справился, fix-loop дороже; страхуется ревьюером на v4-pro |
+| D-10 | #63 (ложный блок worktree-цепочки, O-4) — bounded-задача **до старта плана** (решение владельца 24.10.2026); CC-сторона хуков входит в скоуп только этим исключением | Блок бьёт по каждому чеклисту закрытия; фикс маленький и независим от dsh/ | Два параллельных потока правок в claude-harness (#63 и дизайн #69) — не пересекаются по файлам: #63 — `hooks/` + тесты, #69 — `dsh/` |
+
+## Открытые вопросы (к владельцу) — решены 24.10.2026
+
+1. ~~Момент в DSH-сессии, когда обвязка споткнула~~ — ответ «пока трудно
+   сказать» → D-8.
+2. ~~Подтверждение схемы чистки трекера~~ — подтверждено и выполнено
+   (#70, закрытия, парковки).
+3. ~~#63 bounded-задачей до плана~~ — да → D-10, выполняется отдельным
+   PR до плана.
+
+## На потом (в план, не в дизайн)
+
+- Разбивка задач: sync-вендор и пин → install.sh переделка → verify
+  скиллов в `--check` → самопроверка бандла → сводная follow-ups (#70) →
+  #59 → #43–#46 → удаление legacy (#66).

openspec/changes/dsh-port-v2/proposal.md

@@ -0,0 +1,84 @@
+# Proposal: DSH port v2 — доставка superpowers вариантом C и чистка трекера
+
+Issue: #69. Источники: ревью обвязки 24.10.2026 (находки RV-1, RV-6, RV-11),
+[LayneChai/superpowers-dsh](https://github.com/LayneChai/superpowers-dsh) (MIT),
+решение владельца 24.10.2026 «вариант C».
+
+Статус: **черновик** — ждёт ответов владельца (раздел «Открытые вопросы»).
+
+## Why
+
+Доставка superpowers-скиллов в DSH изобретена заново: `dsh/install.sh --skills`
+копирует клонированный апстрим **без пина и без адаптации текста** (RV-1).
+Следствия:
+
+- установка невоспроизводима: семантика скиллов меняется между релизами
+  obra/superpowers, у нас нет ни пина, ни сверки;
+- текст скиллов не адаптирован под DSH: внутри остаются
+  `superpowers:`-префиксы и ссылки на чужие harness-ы, которые закрывает
+  только наш runtime-append `dsh-tools.md`;
+- нет compat-чека против установленного DSH SDK (RV-11): после апгрейда DSH
+  перепроверка ручная;
+- apстрим уже выпустил v7.0.1, а существующий готовый порт
+  LayneChai/superpowers-dsh пинится на v7.0.0 — зависеть от его каденса
+  значит застрять (замерено 24.10.2026: теги upstream — v7.0.1 свежий);
+- трекер зарос: 23 открытых issue, 2 открытых PR, 4 worktree, из них
+  2 парковки без PR; roadmap #48 и хвосты #5/#13/#21/#28/#31 дублируют
+  друг друга.
+
+## What Changes
+
+**Вариант C** — взять машинерию готового порта как форк/вендор, но sync
+гонять самим по своему каденсу:
+
+- В `dsh/sync/` вендорятся `scripts/sync-from-upstream.mjs`,
+  `scripts/verify-skills.mjs`, `scripts/check-dsh-compat.mjs` из
+  LayneChai/superpowers-dsh (MIT) с адаптацией путей и transform-ов под
+  наш `dsh-tools.md`.
+- Пин на тег obra/superpowers (v7.0.1 на момент плана) живёт в репозитории,
+  а не в голове: `DSH_SUPERPOWERS_REF`, переменная в `dsh/install.sh` и в
+  sync-скрипте. #67 (авто-pull unpinned HEAD) отменяется — rejected.
+- `dsh/install.sh --skills` перестаёт копировать сырой апстрим: fetch
+  пина → прогон sync с ассертами → копирование адаптированного дерева.
+  `--superpowers-from` остаётся для офлайна и разработки. Legacy-фолбэки
+  `~/.claude/*` остаются до #66 и удаляются по нему.
+- Bootstrap-инъекция `using-superpowers` остаётся в нашем бандле; источник
+  текста — synced-копия `$DSH_HOME/skills` (единая точка, как сейчас).
+- Compat-чек (решение владельца): **самопроверка бандла внутри DSH**
+  (активация + команда; контракт guard/pre-step/commands/surface) +
+  терминальный verify synced-скиллов в `--check`. Вендорный
+  check-dsh-compat не берём (SDK в asar, терминал всегда SKIPPED).
+- Ритм: issue на каждый релиз upstream (sync → тесты → PR), самопроверка
+  после каждого апгрейда DSH.
+
+**Чистка трекера** (схема на подтверждение, issue #69):
+
+- закрыть #48 (заменён #69), #67 (rejected), #47 (решение зафиксировано
+  в design.md);
+- свести follow-ups #5/#13/#21/#28/#31 в одну сводную issue «Сводка
+  отложенных находок обвязки» (это же закрывает B16);
+- #43–#46, #59, #62, #63, #66 становятся задачами плана; #63 — кандидат
+  в bounded-задачу до старта плана;
+- судьба PR #18/#8 и парковок `.wt/guard`, `.wt/aura-design`,
+  `.wt/feature-pane`, `dsh-superpowers-git` — за владельцем.
+
+## Impact
+
+- Affected: `dsh/install.sh`, `dsh/sync/` (новое), `dsh/README.md`,
+  `dsh/PORT.md`, `openspec/specs/dsh-install` (дельта), трекер Gitea,
+  бандл (аддитивно: активационный assert + команда самопроверки,
+  существующее поведение не меняется).
+- CC-сторона хуков — вне скоупа, кроме #63 (bounded-задача до плана,
+  решение владельца 24.10.2026).
+- Breaking: `--skills` начинает требовать сеть для fetch пина (кроме
+  `--superpowers-from`); #67 отменён.
+- Риски: см. design.md.
+
+## Открытые вопросы (к владельцу) — решены 24.10.2026
+
+1. ~~Что в DSH-сессии спотыкало сильнее всего~~ — ответ «пока трудно
+   сказать, идёт разработка только самого харнеса» → design.md D-8.
+2. ~~Подтверждение схемы чистки трекера~~ — подтверждено («чисти»),
+   выполнено 24.10.2026: #70, закрыты #5/#13/#21/#28/#31/#48/#47/#67,
+   парковки удалены.
+3. ~~#63 bounded-задачей до плана~~ — да → design.md D-10.