288 lines
22 KiB
Markdown
288 lines
22 KiB
Markdown
# DSH port v2 (вариант C) Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use the `sdd` skill (DSH) to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Перевести доставку superpowers-скиллов на вариант C: вендор sync-машинерии LayneChai, пин на тег v7.0.1, install.sh гоняет sync→verify→copy, бандл получает аддитивную самопроверку контракта.
|
||
|
||
**Architecture:** `dsh/sync/` — два вендорённых Node-скрипта (только stdlib): `sync-from-upstream.mjs` (ассертные transform-ы + staging-swap + override нашего `dsh-tools.md`) и `verify-skills.mjs` (frontmatter/префиксы/ссылки). `dsh/install.sh` оркестрирует: resolve источника (explicit/env → клон по пину → legacy сырой+WARN) → sync → verify → копирование в `$DSH_HOME/skills`. Бандл получает `lib/selfcheck.js` (чистые чекеры контракта ctx) и команду `dsh-harness-check`; существующее поведение бандла не меняется.
|
||
|
||
**Tech Stack:** bash (`set -euo pipefail`), Node builtins (без `@deepseek-ai/*`-импортов), git, python3 для существующих хуков. DSH pinned 0.2.1-rc.3.
|
||
|
||
**Spec:** `openspec/changes/dsh-port-v2/` — [proposal.md](../openspec/changes/dsh-port-v2/proposal.md) + [design.md](../openspec/changes/dsh-port-v2/design.md) (D-1…D-10; план спорит от них).
|
||
|
||
**Models (D-9):** Tasks 1, 2, 5 — `deepseek-official/deepseek-flash` (механика, готовый код); Tasks 3, 4 — `deepseek-official/deepseek-v4-pro` (интеграция); ревью каждой задачи и финальное ревью ветки — `deepseek-official/deepseek-v4-pro`.
|
||
|
||
## Global Constraints
|
||
|
||
- Runtime-зависимости sync и бандла — только Node builtins; запрещён импорт `@deepseek-ai/*` (ловит `dsh/tests/package.test.mjs`).
|
||
- `dsh/install.sh` идемпотентен; `--check` никогда не ходит в сеть; невалидный явный источник — FAIL (exit 1), не молчаливый фолбэк.
|
||
- Пин: `DSH_SUPERPOWERS_REF=v7.0.1`, репозиторий `DSH_SUPERPOWERS_REPO` (default `https://github.com/obra/superpowers`).
|
||
- Legacy-фолбэки `~/.claude/*` остаются (сырой копией + WARN) до #66 — в этой работе не удаляются.
|
||
- Тесты — `node --test` через `bash dsh/tests/run.sh`; весь набор зелёный, плюс `bash tests/run.sh` (CC-сторона) не ломается.
|
||
- Маркировка: находки с маркером и статусом; коммиты со ссылкой на issue (`(#69)`).
|
||
- Язык субагентов (решение владельца 24.10.2026): брифы и отчёты implementer'ов — на английском; маркеры, статусы, термины обвязки и слэш-команды не переводятся; финальные отчёты контроллера владельцу — по-русски.
|
||
- Синхронизация апстрима — только по тегу; HEAD не используется нигде.
|
||
|
||
## Review Focus
|
||
|
||
| # | Вход/условие | Ожидаемое поведение |
|
||
|---|---|---|
|
||
| RF1 | Sync против checkout не v7.0.1 (якорь изменился/исчез) | FAIL loudly (exit 1), staging не подменяет назначение |
|
||
| RF2 | `--skills` без сети и без клона/источника | FAIL с готовой подсказкой, не «пустой успех» |
|
||
| RF3 | Повторный `--skills` (идемпотентность) | Повторный прогон не ломает установленное; нет мусора staging |
|
||
| RF4 | Бандл активируется без `ctx.tools.guard` (сломан контракт DSH) | Самопроверка помечает guards not-ok, остальное живо; бандл не падает целиком |
|
||
| RF5 | Недоклонированный каталог на месте клона | FAIL без оставленного полусостояния |
|
||
|
||
---
|
||
|
||
### Task 1: Вендор sync-from-upstream
|
||
|
||
**Files:**
|
||
- Create: `dsh/sync/sync-from-upstream.mjs`
|
||
- Create: `dsh/tests/fixtures/superpowers-min/` (минимальное дерево: `using-superpowers/SKILL.md` с якорями transform-ов, `brainstorming/SKILL.md` с `superpowers:`-префиксами и висячими harness-референсами, `references/claude-code-tools.md`, `.claude-plugin/plugin.json` с `"version": "7.0.1"`)
|
||
- Create: `dsh/tests/sync.test.mjs`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `dsh/bundle/dsh-tools.md` (единственный источник маппинга).
|
||
- Produces: CLI `node dsh/sync/sync-from-upstream.mjs <upstream-checkout> [--out <dir>] [--ref <tag>]`; exit 0 — печать `synced N files…`, exit 1 — FAIL с именем упавшего transform/якоря; `--out` по умолчанию `<checkout>/.sync-out`; staging-каталог `<out>.tmp-<pid>`; `--out` подменяется только после всех ассертов; в `--out/.sync-meta.json` пишется `{"ref": "<tag|unknown>", "version": "<plugin.json version>"}`.
|
||
|
||
- [ ] **Step 1: Напиши падающие тесты** в `dsh/tests/sync.test.mjs` (helpers: `tempDir`, `write`, `spawnSync` из `./helpers.mjs`; фикстура — копия `dsh/tests/fixtures/superpowers-min/`):
|
||
|
||
```js
|
||
test('sync happy path: transforms, namespace strip, override, meta', ...)
|
||
// assert: exit 0; out/using-superpowers/SKILL.md содержит 'references/dsh-tools.md'
|
||
// и НЕ содержит 'superpowers:'; out/using-superpowers/references/dsh-tools.md
|
||
// == dsh/bundle/dsh-tools.md; out/.sync-meta.json.ref === 'v7.0.1'
|
||
// (запуск с --ref v7.0.1); references/claude-code-tools.md отсутствует (SKIP).
|
||
|
||
test('sync fails loud on broken anchor', ...)
|
||
// испортить якорь в копии фикстуры (replace уникального фрагмента);
|
||
// assert: exit 1, stderr содержит имя transform-а; существующий --out не тронут.
|
||
|
||
test('sync fails on changed skill set', ...)
|
||
// удалить один skill-каталог из копии; assert: exit 1, stderr содержит added/removed.
|
||
|
||
test('sync fails when no skills/ dir', ...) // assert: exit 1.
|
||
```
|
||
|
||
- [ ] **Step 2: Прогони — ожидай FAIL** (скрипта нет)
|
||
|
||
Run: `node --test dsh/tests/sync.test.mjs`
|
||
Expected: FAIL (module not found / exit не 1).
|
||
|
||
- [ ] **Step 3: Реализуй `dsh/sync/sync-from-upstream.mjs`** — перенос из LayneChai/superpowers-dsh `scripts/sync-from-upstream.mjs` с адаптациями:
|
||
- без `package.json`-привязки: `upstreamRoot = resolve(argv[2])`, `--out` из argv;
|
||
- `SKIP`-список чужих harness-референсов — как у оригинала (7 файлов: copilot-tools.md в v7.0.1 нет; T1.3);
|
||
- `TRANSFORMS` — как у оригинала, кроме: их `using-superpowers`-rewrite сохраняется как есть (указывает на `references/dsh-tools.md`);
|
||
- override: после копирования дерева — скопировать `dsh/bundle/dsh-tools.md` → `using-superpowers/references/dsh-tools.md` (путь до бандла — `resolve(import.meta.url, '../../bundle/dsh-tools.md')`);
|
||
- namespace-strip `superpowers:` → `''` и сверка набора скиллов (15 имён) — как у оригинала;
|
||
- staging-swap и «unfired transforms» — как у оригинала; `--ref`/`plugin.json`-версия — в `.sync-meta.json`.
|
||
- Только Node builtins.
|
||
|
||
- [ ] **Step 4: Прогони — ожидай PASS**
|
||
|
||
Run: `node --test dsh/tests/sync.test.mjs`
|
||
Expected: все 4 теста PASS.
|
||
|
||
- [ ] **Step 5: Весь набор + коммит**
|
||
|
||
Run: `bash dsh/tests/run.sh`
|
||
Expected: весь набор зелёный.
|
||
```bash
|
||
git add dsh/sync/sync-from-upstream.mjs dsh/tests/sync.test.mjs dsh/tests/fixtures/superpowers-min
|
||
git commit -m "feat(dsh): вендор sync-from-upstream — ассертные transform-ы, staging-swap, override dsh-tools.md (#69)"
|
||
```
|
||
|
||
### Task 2: Вендор verify-skills
|
||
|
||
**Files:**
|
||
- Create: `dsh/sync/verify-skills.mjs`
|
||
- Create: `dsh/tests/verify.test.mjs`
|
||
|
||
**Interfaces:**
|
||
- Consumes: synced-каталог из Task 1 (формат `<skill>/SKILL.md`).
|
||
- Produces: CLI `node dsh/sync/verify-skills.mjs <skills-dir>`; exit 0 — `ok: <name>` на каждый скилл; exit 1 — первая ошибка с `<skill>/SKILL.md: <reason>`; проверки: YAML frontmatter с `name`+`description`, без остаточного `superpowers:`-префикса в теле, все относительные ссылки вида `../<skill>/…`/`references/…` из тела резолвятся в `<skills-dir>`.
|
||
|
||
- [ ] **Step 1: Напиши падающие тесты** в `dsh/tests/verify.test.mjs` (фикстура — результат sync из Task 1, плюс испорченные копии):
|
||
|
||
```js
|
||
test('verify ok on synced tree', ...) // exit 0, stdout содержит 'ok: using-superpowers'.
|
||
test('verify fails on missing description', ...) // exit 1, stderr содержит путь и reason.
|
||
test('verify fails on leftover superpowers: prefix', ...)
|
||
test('verify fails on dangling relative reference', ...) // ссылка ../brainstorming/x.md без файла.
|
||
```
|
||
|
||
- [ ] **Step 2: Прогони — ожидай FAIL**
|
||
|
||
Run: `node --test dsh/tests/verify.test.mjs`
|
||
Expected: FAIL.
|
||
|
||
- [ ] **Step 3: Реализуй `dsh/sync/verify-skills.mjs`** — перенос идеи LayneChai `verify-skills.mjs`, без provider-части: только проверки выше, чистый Node. Парсер frontmatter — как в их `parseFrontmatter` (скалярные поля).
|
||
|
||
- [ ] **Step 4: Прогони — ожидай PASS**
|
||
|
||
Run: `node --test dsh/tests/verify.test.mjs`
|
||
Expected: все тесты PASS.
|
||
|
||
- [ ] **Step 5: Весь набор + коммит**
|
||
|
||
Run: `bash dsh/tests/run.sh`
|
||
Expected: зелёный.
|
||
```bash
|
||
git add dsh/sync/verify-skills.mjs dsh/tests/verify.test.mjs
|
||
git commit -m "feat(dsh): вендор verify-skills — frontmatter, префиксы, висячие ссылки (#69)"
|
||
```
|
||
|
||
### Task 3: install.sh — пин, fetch, sync-оркестрация
|
||
|
||
**Files:**
|
||
- Modify: `dsh/install.sh`
|
||
- Modify: `dsh/tests/install.test.mjs`
|
||
- Modify: `dsh/README.md`, `dsh/PORT.md` (разделы установки/источника)
|
||
|
||
**Interfaces:**
|
||
- Consumes: `dsh/sync/sync-from-upstream.mjs` (Task 1), `dsh/sync/verify-skills.mjs` (Task 2); env `DSH_SUPERPOWERS_REF` (default `v7.0.1`), `DSH_SUPERPOWERS_REPO` (default `https://github.com/obra/superpowers`), `DSH_SUPERPOWERS_SOURCE`, `--superpowers-from`.
|
||
- Produces: поток `--skills`: resolve (explicit/env → клон `$DSH_HOME/superpowers` на пине → legacy сырой+WARN) → `node dsh/sync/sync-from-upstream.mjs <source> --out "$DSH_HOME/superpowers/skills.synced" --ref "$REF"` → `node dsh/sync/verify-skills.mjs <out>` → копирование `<out>/*` в `$DSH_HOME/skills` (как текущий цикл) → local skills (role, sdd) без изменений. `--check`: строка `ok: superpowers source (<dir>, git <sha>, ref <ref>)`, сети нет.
|
||
|
||
- [ ] **Step 1: Напиши падающие тесты** в `dsh/tests/install.test.mjs` (helpers уже есть; локальный git-репозиторий: `git init` + коммит фикстуры `dsh/tests/fixtures/superpowers-min` + `git tag v7.0.1`; env `DSH_SUPERPOWERS_REPO=file://<repo>`):
|
||
|
||
```js
|
||
test('--skills clones pinned ref, syncs, verifies and installs adapted skills', ...)
|
||
// fresh HOME: exit 0; $DSH_HOME/skills/using-superpowers/SKILL.md содержит 'references/dsh-tools.md'
|
||
// и НЕ содержит 'superpowers:'; references/dsh-tools.md установлен; stdout содержит 'synced' и 'copied N superpowers skills'.
|
||
|
||
test('--skills offline without source fails with hint', ...)
|
||
// fresh HOME, DSH_SUPERPOWERS_REPO=file:///nonexistent, без explicit: exit 1,
|
||
// stderr содержит 'git clone' hint; $DSH_HOME/skills не создан с пустыми скиллами.
|
||
|
||
test('--skills removes failed empty clone dir (RF5)', ...)
|
||
// fresh HOME, DSH_SUPERPOWERS_REPO=file:///nonexistent, предварительно mkdir $DSH_HOME/superpowers (пустой):
|
||
// exit 1; existsSync($DSH_HOME/superpowers) === false (полусостояния не остаётся).
|
||
|
||
test('--skills re-run updates from moved tag', ...)
|
||
// второй прогон после 'git commit --amend' + 'git tag -f v7.0.1': установленный текст обновился (маркер из amend).
|
||
|
||
test('--skills leaves no staging garbage', ...)
|
||
// после прогона: в $DSH_HOME/superpowers нет *.tmp-*; existsSync skills.synced — допустимо, но .sync-meta.json.ref==='v7.0.1'.
|
||
|
||
test('--check is offline and reports ref', ...)
|
||
// env DSH_SUPERPOWERS_REPO=file:///nonexistent: exit 0; stdout содержит 'ref v7.0.1' или 'no superpowers source'.
|
||
|
||
test('.claude/code-paths содержит dsh/', ...)
|
||
// readFileSync('../../.claude/code-paths') содержит строку 'dsh/' (D-5).
|
||
```
|
||
|
||
- [ ] **Step 2: Прогони — ожидай FAIL**
|
||
|
||
Run: `node --test dsh/tests/install.test.mjs`
|
||
Expected: новые тесты FAIL (clone-логики нет), старые — PASS.
|
||
|
||
- [ ] **Step 3: Реализуй в `dsh/install.sh`** — только `superpowers_source()`/`check()`/`install_skills()`:
|
||
- новая ветка resolve: explicit (`--superpowers-from`/`DSH_SUPERPOWERS_SOURCE`) → **sync от этого каталога без сети**; иначе `ensure_pinned_clone`: если `$DSH_HOME/superpowers` уже клон на `$REF` — использовать (WARN при отсутствии сети); иначе `git clone --depth 1 --branch "$REF" "$REPO" "$DSH_HOME/superpowers"`; при неудаче и существующем каталоге без `.git` — FAIL с подсказкой, каталог не трогать; при неудаче и пустом месте — удалить недоклон и FAIL (RF5);
|
||
- `install_skills()`: sync → verify → копирование из `--out`; legacy-источник — прежний сырой путь с WARN (без sync);
|
||
- `--check`: офлайн, печатает источник/ref/sha из `.sync-meta.json` или git;
|
||
- `usage()` — новые переменные.
|
||
- Bash с python3-вставками в прежнем стиле.
|
||
|
||
- [ ] **Step 4: Прогони — ожидай PASS**
|
||
|
||
Run: `node --test dsh/tests/install.test.mjs`
|
||
Expected: все тесты (старые и новые) PASS.
|
||
|
||
- [ ] **Step 5: Доки + весь набор + коммит** — обнови `dsh/README.md` (Quick start: `--skills` сам тянет пин, переменные, офлайн-кейсы) и `dsh/PORT.md` (§3 убрать «Vendored superpowers»-абзац как устаревший, §6 команды установки).
|
||
|
||
Run: `bash dsh/tests/run.sh && bash tests/run.sh`
|
||
Expected: оба набора зелёные.
|
||
```bash
|
||
git add dsh/install.sh dsh/tests/install.test.mjs dsh/README.md dsh/PORT.md
|
||
git commit -m "feat(dsh): --skills гоняет sync/verify по пину v7.0.1, офлайн-кейсы (#69)"
|
||
```
|
||
|
||
### Task 4: Самопроверка бандла + команда dsh-harness-check
|
||
|
||
**Files:**
|
||
- Create: `dsh/bundle/lib/selfcheck.js`
|
||
- Modify: `dsh/bundle/index.js` (аддитивно)
|
||
- Create: `dsh/bundle/command-check.js`
|
||
- Create: `dsh/tests/selfcheck.test.mjs`
|
||
- Modify: `dsh/README.md` (Known limits → самопроверка), `dsh/PORT.md` (§7 риск → чем закрыт)
|
||
|
||
**Interfaces:**
|
||
- Consumes: `ctx`-форма из `dsh/bundle/index.js` (`tools.guard`, `on`, `inject`, `commands`, `workingDirectory.get`).
|
||
- Produces: `collectSelfCheck(ctxLike) -> [{ feature: 'guards'|'bootstrap'|'commands'|'workingDirectory', ok: boolean, detail: string }]` — чистая функция, без вызовов ctx; `registerCheckCommand({ commands, collect, logger })` — регистрирует команду `dsh-harness-check`, которая собирает чек и возвращает текст-отчёт; в `index.js`: конфиг-ключи `selfCheck: true` (default) и `checkCommand: true` (default); после wiring — прогон `collectSelfCheck`, при not-ok критической службы (guards) — `ctx.logger.error` + пропуск только этой фичи (существующие фичи при их службах на месте работают как раньше).
|
||
|
||
- [ ] **Step 1: Напиши падающие тесты** в `dsh/tests/selfcheck.test.mjs`:
|
||
|
||
```js
|
||
test('collectSelfCheck ok on full ctx-like', ...) // все features ok:true.
|
||
test('collectSelfCheck flags missing tools.guard', ...) // guards ok:false, detail содержит 'tools.guard'; остальные ok:true.
|
||
test('collectSelfCheck flags missing on()', ...) // bootstrap ok:false.
|
||
test('registerCheckCommand builds report text', ...)
|
||
// fake commands.register(name, handler) — вызвать handler с fake collect, вернуть текст:
|
||
// содержит 'guards: not-ok' и имя фичи; ok-ветка содержит 'ok'.
|
||
```
|
||
|
||
- [ ] **Step 2: Прогони — ожидай FAIL**
|
||
|
||
Run: `node --test dsh/tests/selfcheck.test.mjs`
|
||
Expected: FAIL.
|
||
|
||
- [ ] **Step 3: Реализуй** `lib/selfcheck.js` и `command-check.js` по интерфейсам; в `index.js` добавь в `DEFAULTS` ключи и вызовы после существующих блоков (порядок: guards → bootstrap → roleCommand → selfcheck/command), чтобы при отсутствии `ctx.tools.guard` guard-блок пропускался с `ctx.logger.error('[dsh-harness] self-check: guards not-ok: …')`, а bootstrap/command оставались.
|
||
|
||
- [ ] **Step 4: Прогони — ожидай PASS**
|
||
|
||
Run: `node --test dsh/tests/selfcheck.test.mjs`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Весь набор + доки + коммит** — `dsh/README.md` (Known limits: самопроверка при активации + команда `dsh-harness-check`), `dsh/PORT.md` §7 (риск контракта → закрыт самопроверкой).
|
||
|
||
Run: `bash dsh/tests/run.sh`
|
||
Expected: зелёный (package.test.mjs без `@deepseek-ai/*` тоже).
|
||
```bash
|
||
git add dsh/bundle/lib/selfcheck.js dsh/bundle/command-check.js dsh/bundle/index.js dsh/tests/selfcheck.test.mjs dsh/README.md dsh/PORT.md
|
||
git commit -m "feat(dsh): самопроверка контракта бандла при активации + команда dsh-harness-check (#69)"
|
||
```
|
||
|
||
### Task 5: Спека-дельта dsh-install и проверка code-paths
|
||
|
||
**Files:**
|
||
- Modify: `openspec/changes/dsh-port-v2/specs/dsh-install/spec.md` (delta)
|
||
- Modify: `dsh/PORT.md` (§1 таблица, §3: строка «Vendored superpowers» → «Pinned sync (v7.0.1)»)
|
||
- Modify: `openspec/changes/dsh-port-v2/design.md` (D-5 — статус «выполнено в этой ветке» после Task 3; D-6 — ссылки на selfcheck)
|
||
|
||
**Interfaces:**
|
||
- Consumes: поведение из Tasks 3–4.
|
||
- Produces: spec-delta: REQUIREMENT `sync-по-пину` (ADDED: `--skills` без явного источника клонирует `DSH_SUPERPOWERS_REPO` на `DSH_SUPERPOWERS_REF`, sync+verify обязательны, FAIL на несовпадении якорей; MODIFIED: сценарии «нет сети» — FAIL с подсказкой вместо тихого legacy; legacy — только WARN-путь), `selfcheck` (ADDED: активационный чек + команда).
|
||
|
||
- [ ] **Step 1: Напиши падающую проверку** — в `dsh/tests/install.test.mjs` уже есть тест `.claude/code-paths содержит dsh/` (Task 3); добавь в `dsh/tests/sync.test.mjs`:
|
||
|
||
```js
|
||
test('sync meta records ref and version', ...) // .sync-meta.json: ref==='v7.0.1', version==='7.0.1'.
|
||
```
|
||
|
||
Run: `node --test dsh/tests/sync.test.mjs`
|
||
Expected: FAIL, если Task 1 не писал `version` (иначе шаг помечается как уже зелёный и пропускается).
|
||
|
||
- [ ] **Step 2: Напиши дельту** `openspec/changes/dsh-port-v2/specs/dsh-install/spec.md` — прочитай `openspec/specs/dsh-install/spec.md` и оформи ADDED/MODIFIED по формату; BREAKING отметить в `## MODIFIED Requirements` (сеть для `--skills`).
|
||
|
||
Run: `openspec validate dsh-port-v2 --strict`
|
||
Expected: `Change 'dsh-port-v2' is valid`.
|
||
|
||
- [ ] **Step 3: Обнови** `dsh/PORT.md` §1/§3, `dsh/README.md` (раздел «Обновление»: каденс D-7 — issue на каждый релиз obra/superpowers, команда sync→verify→--skills, проверка `--check`) и `design.md` (D-5/D-6 статусы).
|
||
|
||
- [ ] **Step 4: Оба набора + коммит**
|
||
|
||
Run: `bash dsh/tests/run.sh && bash tests/run.sh && openspec validate dsh-port-v2 --strict`
|
||
Expected: всё зелёное.
|
||
```bash
|
||
git add openspec/changes/dsh-port-v2/specs/dsh-install/spec.md openspec/changes/dsh-port-v2/design.md dsh/PORT.md dsh/tests/sync.test.mjs
|
||
git commit -m "docs(openspec): дельта dsh-install под sync-по-пину и самопроверку (#69)"
|
||
```
|
||
|
||
## Предусловия окружения (проверяются контроллером один раз до Task 1)
|
||
|
||
- `python3`, `git`, `node` в PATH; `bash dsh/tests/run.sh` зелёный на входной точке ветки.
|
||
- Сеть не нужна для тестов: все прогоны используют `DSH_SUPERPOWERS_REPO=file://…` или temp-HOME; реальный `~/.dsh` не трогается (тесты — temp `DSH_HOME`).
|
||
- Ключи Gitea доступны только для `tea` (PR), не в переменных окружения сессий.
|
||
- Ветка: `feat/69-dsh-port-v2`, worktree `.claude/worktrees/dsh-port-v2`; `#63` идёт отдельной веткой `feat/63-guard-worktree-chain` и не пересекается по файлам.
|