diff --git a/docs/superpowers/specs/2026-05-12-brain-v2-phase-1-design.md b/docs/superpowers/specs/2026-05-12-brain-v2-phase-1-design.md new file mode 100644 index 0000000..0b320f9 --- /dev/null +++ b/docs/superpowers/specs/2026-05-12-brain-v2-phase-1-design.md @@ -0,0 +1,533 @@ +# Brain v2 Phase 1 — Consumer-Universal Plugins + Context7 Activation (design) + +**Дата:** 12.05.2026 +**Brain version target:** v1.2 → v1.3 +**Routing.md target:** v1.1 → v1.2 +**Связанные документы:** +- [docs/brain-plugin-routing.md](../../brain-plugin-routing.md) (v1.1, будет bump v1.2) +- [docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md](2026-05-11-brain-plugin-routing-design.md) (предыдущий spec) +- [CLAUDE.md](../../../CLAUDE.md) (operational map brain'а) + +--- + +## §1. Цель и scope + +Phase 1 — следующий шаг brain v2 после Phase 0 (мета-foundation). Цель: распространить через brain'а в consumer'ы (Liderra и будущие) 5 плагинов категории `consumer-universal` из shortlist'а 17 (см. [memory: project_brain_v2_phase0.md](../../../../../C:/Users/Administrator/.claude/projects/c--------------claude-brain/memory/project_brain_v2_phase0.md)). + +**Что внутри scope:** +1. Регистрация 4 plugin'ов в `plugins-manifest.json` (target=consumer, не активируются в brain runtime). +2. Активация 1 plugin'а (Context7) на user-level brain'а через `settings-fragment.json` + cache cp. +3. Закрытие техдолга `install-plugins.sh` — фильтрация по `target` ENUM (введён в v1.1, но не операционализирован в коде). +4. Bump `docs/brain-plugin-routing.md` v1.1 → v1.2 с новыми rows. +5. Release brain v1.2 → v1.3 + git tag. + +**Что вне scope:** +- Реальный deploy в Liderra (блокирован outstanding'ом v1.0: lychee 33 broken links + Liderra main не запушен). Это Phase 1C / отдельный chat. +- Phase 2 stack-gated плагины (figma, vercel, supabase, huggingface, data-engineering) — ждут ответов по стеку. +- Кастомные brain skills (skill-creator output) — отдельная инициатива. +- Pravila v2 bump — отложен до накопления изменений. + +--- + +## §2. 5 артефактов Phase 1 + +| # | Plugin | Marketplace | Тип | Author | Target | Active in brain? | +|---|---|---|---|---|---|---| +| 1 | `code-review` | `anthropics/claude-plugins-official` | pure plugin | Anthropic | `consumer` | ✗ | +| 2 | `security-guidance` | `anthropics/claude-plugins-official` | plugin + hooks | Anthropic | `consumer` | ✗ | +| 3 | `pr-review-toolkit` | `anthropics/claude-plugins-official` | plugin (multi-agent) | Anthropic | `consumer` | ✗ | +| 4 | `telegram` | `anthropics/claude-plugins-official` (external_plugins/) | plugin + bundled MCP | community-managed | `consumer` | ✗ | +| 5 | `context7` | `anthropics/claude-plugins-official` (external_plugins/) | plugin + bundled MCP | Upstash (community-managed) | `user-level+consumer` | ✓ | + +**Marketplace HEAD SHA для pinning:** `00679aef889efe36bb0389f81d70b6229a2013ee` (commit 2026-05-09 21:40 +0100; тот же SHA, что у plugin-dev и hookify в Phase 0 install). + +### §2.1. Reality check фактических плагинов + +Все 5 верифицированы в локальном marketplace cache (`~/.claude/plugins/marketplaces/claude-plugins-official/`): +- Plugin manifests прочитаны: `plugins/code-review/.claude-plugin/plugin.json`, `plugins/security-guidance/.claude-plugin/plugin.json`, `plugins/pr-review-toolkit/.claude-plugin/plugin.json`, `external_plugins/telegram/.claude-plugin/plugin.json`, `external_plugins/context7/.claude-plugin/plugin.json`. +- Marketplace entries в `.claude-plugin/marketplace.json` подтверждены (lines 528-538, 572-581, 1455-1465, 1712-1722, 1962-1967 файла marketplace.json — текст `"name": ""`). +- Bundled MCP в Context7: [external_plugins/context7/.mcp.json](../../../../../C:/Users/Administrator/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/context7/.mcp.json) — `{"context7": {"command": "npx", "args": ["-y", "@upstash/context7-mcp"]}}`. +- Bundled MCP в Telegram: [external_plugins/telegram/.mcp.json](../../../../../C:/Users/Administrator/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/telegram/.mcp.json) — `{"mcpServers": {"telegram": {"command": "bun", "args": [...]}}}`. + +### §2.2. Categorization rationale + +**Почему Context7 = `user-level+consumer` (активен в brain):** +- Brain dev = ежедневное чтение Anthropic SDK / claude-plugins / marketplace specs. Context7 даёт авторитетный structured doc lookup без сёрфинга по GitHub raw url'ам. +- Не дублирует существующий tool — нет default'а на «docs API/SDK lookup» в routing.md §3.1; Context7 заполняет новый класс задачи, не overlap'ит. + +**Почему остальные 4 = `consumer-universal` (только в consumer):** +- `code-review`: conflict с `superpowers:requesting-code-review` (default routing.md §3.1 line 69). Активация в brain создаст ambiguity «который plugin использовать». +- `security-guidance`: conflict с built-in `/security-review` command + bundled `hooks.json` плагина может конфликтовать с brain'овыми 7 economy-hooks. +- `pr-review-toolkit`: для brain (1 maintainer, простой PR workflow) overkill. В Liderra (команда) полезен. +- `telegram`: brain не имеет need в notifications (локальная работа, нет long-running CI). В Liderra при deploy/CI полезен. + +--- + +## §3. Архитектура и data flow + +### §3.1. Unified plugin track (вместо двойного track A/B) + +Все 5 артефактов — **plugin'ы**. Context7 и telegram несут `.mcp.json` внутри plugin'а (bundled MCP), который автоматически регистрируется как MCP-сервер при включении plugin'а в `enabledPlugins`. Никаких отдельных правок `mcp-user.template.json` или `.mcp.json.template` для них **не требуется**. + +**Distribute pipeline (brain → consumer):** + +``` +brain/user-level-files/plugins-manifest.json + │ + │ scripts/install.sh --target= --version=brain-v1.3 --with-plugins=yes + │ + ▼ +scripts/lib/install-plugins.sh --install-target=consumer + │ + │ jq filter: target ∈ {"consumer", "user-level+consumer"} + │ + ▼ +claude plugin install @claude-plugins-official (или JSON fallback) + │ + ▼ +consumer ~/.claude/plugins/cache/claude-plugins-official/// +consumer ~/.claude/settings.json enabledPlugins.=true (если CLI / manual edit) +``` + +**Brain runtime pipeline:** + +``` +brain/user-level-files/plugins-manifest.json → 13 entries (8 existing + 5 new) +brain/user-level-files/settings-fragment.json → 9 enabledPlugins (8 existing + context7) + │ + │ scripts/install.sh --target=$HOME/.claude --version=brain-v1.3 + │ + ▼ +install.sh detects mode=user; --install-target=user + │ + ▼ +filter target ∈ {"user-level", "user-level+consumer"} + │ + │ 9 plugins pass: 6 existing user-level (claude-md-management, superpowers, skill-creator, + │ claude-code-setup, plugin-dev, hookify) + 2 existing user-level+consumer + │ (ui-ux-pro-max, frontend-design) + new context7 + │ + │ 4 filtered out: code-review, security-guidance, pr-review-toolkit, telegram + │ + ▼ +merge-settings.sh: brain ~/.claude/settings.json enabledPlugins replaced с 9 entries +cache cp: ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/ создан +``` + +### §3.2. Track unified rationale + +Раньше (раннее brainstorming) я различал «Track A — plugins» и «Track B — MCP-серверы через `.mcp templates`». Reality check показал, что Context7 и Telegram — **plugin'ы**, которые **внутри** содержат `.mcp.json`. Claude Code автоматически регистрирует bundled MCP при enabling plugin'а. Это упрощает архитектуру до одного track'а. + +Корректировка: поле `kind: "plugin" | "mcp"` в plugins-manifest **не нужно** — все entries plugin'ы. MCP-only артефакты (например, `magic` 21st.dev в `mcp-user.template.json`) остаются отдельной концепцией для **legacy** случаев, когда есть raw MCP-сервер без plugin wrapper. + +--- + +## §4. Изменения по файлам (deliverables) + +### §4.1. `user-level-files/plugins-manifest.json` (+5 entries) + +Сейчас 8 entries в [plugins-manifest.json](../../../user-level-files/plugins-manifest.json). Добавляются 5 новых после `hookify` блока (line 102), перед закрывающим `}`. + +**Template entry для 4 consumer-only (code-review, security-guidance, pr-review-toolkit, telegram):** + +```json +"@claude-plugins-official": [ + { + "scope": "user", + "installPath": null, + "version": "00679aef889e", + "installedAt": null, + "lastUpdated": "2026-05-12T00:00:00.000Z", + "gitCommitSha": "00679aef889efe36bb0389f81d70b6229a2013ee", + "installMethod": "registered-only-not-cached", + "target": "consumer", + "category": "consumer-universal" + } +] +``` + +**Entry для Context7 (cached + active):** + +```json +"context7@claude-plugins-official": [ + { + "scope": "user", + "installPath": "C:\\Users\\Administrator\\.claude\\plugins\\cache\\claude-plugins-official\\context7\\00679aef889e", + "version": "00679aef889e", + "installedAt": "2026-05-12TZ", + "lastUpdated": "2026-05-12TZ", + "gitCommitSha": "00679aef889efe36bb0389f81d70b6229a2013ee", + "installMethod": "manual-cp-from-marketplace-Path2", + "target": "user-level+consumer", + "category": "consumer-universal" + } +] +``` + +**Verification после Edit:** +- `jq empty user-level-files/plugins-manifest.json` exit 0 +- `jq '.plugins | length'` == 13 +- Per-plugin target check (см. §6.1) + +### §4.2. `user-level-files/settings-fragment.json` (+1 ключ) + +Сейчас 8 keys в `enabledPlugins` ([settings-fragment.json:2-11](../../../user-level-files/settings-fragment.json#L2-L11)). Добавляется: + +```json +"context7@claude-plugins-official": true +``` + +**4 consumer-only НЕ добавляются** — они не активируются в brain runtime. + +### §4.3. `scripts/lib/install-plugins.sh` (рефакторинг) + +**Текущее поведение (line 61):** +```bash +for plugin in $(jq -r '.plugins | keys[]' "$manifest"); do +``` +Берёт все entries без фильтрации. + +**Новое поведение:** + +```bash +# New flag parsing (после строки 28) +case "$1" in + --marketplaces=*) marketplaces="${1#--marketplaces=}" ;; + --manifest=*) manifest="${1#--manifest=}" ;; + --install-target=*) install_target="${1#--install-target=}" ;; + *) log_error "Unknown arg: $1"; exit 1 ;; +esac + +# Fallback default (backwards-compat для прямых вызовов из тестов) +if [ -z "${install_target:-}" ]; then + log_warn "--install-target not specified, defaulting to 'user' (deprecated path)" + install_target="user" +fi + +# Filter expression +case "$install_target" in + user) + filter='.plugins | to_entries[] | select(.value[0].target == "user-level" or .value[0].target == "user-level+consumer") | .key' + ;; + consumer) + filter='.plugins | to_entries[] | select(.value[0].target == "consumer" or .value[0].target == "user-level+consumer") | .key' + ;; + *) + log_error "--install-target must be 'user' or 'consumer', got: $install_target"; exit 1 ;; +esac + +# Use filter +for plugin in $(jq -r "$filter" "$manifest"); do + # ... rest unchanged from current line 62-74 +done +``` + +**Также корректировка `scripts/install.sh` line 145-150:** + +```bash +if [ "$with_plugins" = "yes" ]; then + if [ -f "$src/marketplaces.json" ] && [ -f "$src/plugins-manifest.json" ]; then + # Map detected $mode (user|project) to --install-target (user|consumer) + plugin_target=$([ "$mode" = "user" ] && echo "user" || echo "consumer") + bash "$SCRIPT_DIR/lib/install-plugins.sh" \ + --marketplaces="$src/marketplaces.json" \ + --manifest="$src/plugins-manifest.json" \ + --install-target="$plugin_target" || exit 6 + fi +fi +``` + +**Verification после Edit:** +- `bash -n scripts/lib/install-plugins.sh scripts/install.sh` exit 0 +- Regression: `bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2` exit 0 +- Functional filter test (см. §6.3) + +### §4.4. `docs/brain-plugin-routing.md` (v1.1 → v1.2) + +**Header:** +```diff +- # Brain Plugin Routing Rules (v1.1) ++ # Brain Plugin Routing Rules (v1.2) +- **Дата:** 11.05.2026 ++ **Дата:** 12.05.2026 +``` + +**§2.1 — +1 row Context7 (после строки hookify):** + +```markdown +| **context7** | `anthropics/claude-plugins-official` | `consumer-universal` (active in brain via target=user-level+consumer) | docs lookup для API/SDK/marketplaces (Anthropic SDK, claude-plugins, future Vue/Vuetify Liderra); plugin bundles MCP via `npx @upstash/context7-mcp` | каждодневный код-write (не doc-lookup) | +``` + +**§3.1 — +1 row (после строки «Запутался — какой плагин брать»):** + +```markdown +| Документация API/SDK/marketplace (Anthropic SDK, claude-plugins-official, Vue/Vuetify в Liderra) | `context7` MCP (через plugin context7 enabledPlugins) | `WebFetch` если context7 npx down/offline ИЛИ источник вне SDK doc trees (общая статья, blog post) | структурированный version-pinned lookup vs unstructured web scrape | +``` + +**§3.2 — +1 tie-breaker (после №3 «User написал /skill-name явно»):** + +```markdown +4. **Community-managed plugin предложен для активного use** — добавить в `enabledPlugins` только если: (a) Anthropic-маркетплейс с явной верификацией (community-managed tag там есть, но Anthropic git-hosted), ИЛИ (b) user явно проаппрувил риск, ИЛИ (c) plugin изолирован (read-only queries без PII). Иначе оставить `registered-only-not-cached` для consumer-distribute, не активируя в brain. +``` + +**§4.2 — +5 rows (после строки #18 hookify):** + +```markdown +| #1 | `context7` | `consumer-universal` (active in brain user-level via target=user-level+consumer) | installed brain v1.3 (manual-cp-from-marketplace-Path2); **community-managed** (Upstash) + npx runtime dep | +| #2 | `code-review` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); Anthropic-authored | +| #7 | `security-guidance` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); Anthropic-authored; plugin несёт own hooks.json — потенциальный конфликт с brain economy-hooks при activation | +| #10 | `pr-review-toolkit` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); Anthropic-authored | +| #12 | `telegram` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); **community-managed** + bun runtime dep + post-install pairing required | +``` + +**История версий — +1 entry в начало (между v1.1 и v1.0):** + +```markdown +- **v1.2 от 2026-05-12** — Brain v1.3 release: Phase 1 deliverables. Added 5 plugins (#1 context7 active-in-brain, #2 code-review, #7 security-guidance, #10 pr-review-toolkit, #12 telegram — все consumer-universal через target=consumer ИЛИ user-level+consumer). install-plugins.sh learned `--install-target` flag + filter по `target` ENUM (closing tech-debt unmentioned-but-implicit из v1.0). §2.1 +1 row, §3.1 +1 row (docs lookup новый класс задачи), §3.2 +1 tie-breaker (community-managed), §4.2 +5 rows. +``` + +### §4.5. `.brain-version` (v1.2 → v1.3) + +```diff +- v1.2 +- sha: 276a47f ++ v1.3 ++ sha: +``` + +### §4.6. Cache cp Context7 (filesystem side-effect, не git-tracked в brain repo) + +Действие при execution commit 4: + +```bash +cp -r ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/context7/ \ + ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/ +``` + +Соответствует pattern'у Phase 0 plugin-dev/hookify cache cp ([plugins-manifest.json:81-89](../../../user-level-files/plugins-manifest.json#L81-L89)). + +--- + +## §5. Conflicts и mitigation + +| ID | Конфликт | Mitigation | Where it lives | +|---|---|---|---| +| **C1** | `code-review` plugin vs `superpowers:requesting-code-review` | Не активировать code-review в brain. Routing.md §3.1 line 69 default остаётся superpowers | settings-fragment.json НЕ содержит ключ | +| **C2** | `security-guidance` bundled hooks.json vs brain economy-hooks | Не активировать security-guidance в brain. Built-in `/security-review` команда покрывает need | settings-fragment.json НЕ содержит ключ | +| **C3** | `pr-review-toolkit` agents vs `superpowers:requesting-code-review` agents | В brain оба не активны (no conflict). В consumer — задача PSR template'а | вне scope brain routing.md | +| **C4** | `telegram` notifications vs brain (нет аналога) | No conflict в brain | — | +| **C5** | `context7` MCP vs `WebFetch` для docs | Routing.md §3.1 +1 row: Context7 default for API/SDK; WebFetch fallback | docs/brain-plugin-routing.md v1.2 §3.1 | +| **C6** | Context7 npx runtime требование | Pre-install dep check (см. §7); если npx absent — Context7 entry остаётся, но enabledPlugins=false до решения dep | plan execution (Phase 1B) | +| **C7** | Telegram bun runtime требование (для consumer) | Pre-distribute dep check для Liderra; bun на Windows — отдельная установка. Spec помечает: telegram опционален для consumer без bun | — (не блокер brain v1.3) | +| **C8** | Context7 MCP coexistence c `magic` (21st.dev) MCP в `~/.claude.json:mcpServers` | merge-mcp.sh идемпотентно добавит context7 entry рядом с magic. **Не верифицировано** — verify-checkpoint в plan | plan execution | +| **C9** | Community-managed plugin'ы (Context7, telegram) vs brain до v1.2 — только Anthropic-authored | Spec disclaimer + routing.md §3.2 tie-breaker #4 | docs/brain-plugin-routing.md v1.2 §3.2 | +| **C10** | install-plugins.sh refactor ломает обратную совместимость (флаг `--install-target`) | Fallback-to-user with warning (см. §4.3) для прямых вызовов | scripts/lib/install-plugins.sh | + +--- + +## §6. Verification (как проверять каждый артефакт в Phase 1B) + +### §6.1. Per-file verification + +**A. plugins-manifest.json:** +```bash +jq empty user-level-files/plugins-manifest.json +jq '.plugins | length' user-level-files/plugins-manifest.json # → 13 +for p in code-review security-guidance pr-review-toolkit telegram context7; do + jq -r ".plugins[\"$p@claude-plugins-official\"][0].target" user-level-files/plugins-manifest.json +done +# Expected: consumer, consumer, consumer, consumer, user-level+consumer +``` + +**B. settings-fragment.json:** +```bash +jq empty user-level-files/settings-fragment.json +jq '.enabledPlugins | length' user-level-files/settings-fragment.json # → 9 +jq '.enabledPlugins["context7@claude-plugins-official"]' user-level-files/settings-fragment.json # → true +``` + +**C. install-plugins.sh:** +```bash +bash -n scripts/lib/install-plugins.sh scripts/install.sh +# Functional dry-run regression +bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2 # exit 0 +# Filter functional test +BRAIN_ROOT=$PWD bash scripts/lib/install-plugins.sh \ + --marketplaces=user-level-files/marketplaces.json \ + --manifest=user-level-files/plugins-manifest.json \ + --install-target=user 2>&1 | grep "Installing" # → 9 plugins +``` + +**D. routing.md:** +```bash +grep -E "^# Brain Plugin Routing Rules \(v1\.2\)$" docs/brain-plugin-routing.md +grep -c "^| **context7**" docs/brain-plugin-routing.md # → 1+ (в §2.1) +grep -cE "^\| #(1|2|7|10|12) \|" docs/brain-plugin-routing.md # → ≥5 +``` + +**E. .brain-version:** +```bash +head -1 .brain-version # → v1.3 +``` + +**F. Context7 cache:** +```bash +test -d ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e +jq empty ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/.claude-plugin/plugin.json +jq -r .name ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/.claude-plugin/plugin.json +# Expected: context7 +``` + +### §6.2. Runtime smoke test (после install.sh + restart) + +```bash +jq '.enabledPlugins["context7@claude-plugins-official"]' ~/.claude/settings.json # → true +npx -y @upstash/context7-mcp --help 2>&1 | head -5 # exit 0 +``` + +Manual: открыть новую сессию, проверить что Skill tool / mcpServers видит context7. + +### §6.3. Regression check (existing 8 plugins после install-plugins.sh refactor) + +```bash +# До refactor (commit 1 в HEAD) +git stash +git checkout HEAD~1 -- scripts/lib/install-plugins.sh scripts/install.sh +bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2 | tee before.txt + +# После refactor +git stash pop +bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2 | tee after.txt + +diff before.txt after.txt # diff не должен содержать added/removed plugins из 8 existing +``` + +### §6.4. Final verification gate + +Перед claim «Phase 1 готов» — обязательно invoke `superpowers:verification-before-completion`. Skill сам проверит: +- atomic commits sequence (5 commits) в git log +- git tag `brain-v1.3` создан +- `.brain-version` соответствует git rev-parse HEAD +- verify.sh exit 0 +- runtime smoke test (Context7 в новой сессии) — verified или явно «не верифицировал X» + +--- + +## §7. Runtime dependencies (pre-install checks) + +Phase 1B execution (writing-plans) обязан включить pre-install dep check как отдельный helper. Возможный артефакт `scripts/verify-deps.sh`: + +```bash +require_runtime() { + local cmd="$1"; local plugin="$2" + if ! command -v "$cmd" >/dev/null 2>&1; then + log_warn "$plugin requires '$cmd' — not in PATH" + return 1 + fi + log_info "$plugin runtime OK: $cmd ($(command -v "$cmd"))" + return 0 +} + +require_runtime npx context7 || log_warn "context7 будет в manifest но enabledPlugins=false" +require_runtime bun telegram || log_warn "telegram остаётся registered-only для consumer без bun" +``` + +Не верифицировал, что `npx` и `bun` присутствуют на машине Дмитрия — это входит в Phase 1B как первый шаг execution. + +--- + +## §8. Atomic commits sequence (Phase 1B execution) + +5 коммитов, каждый — один логический change, self-contained, reversible. + +| # | Commit message | Files modified | Verify gate | +|---|---|---|---| +| 1 | `feat(brain-spec): Phase 1 design (consumer-universal plugins + context7 activation)` | spec doc (this file) | markdown self-review | +| 2 | `refactor(brain-install): filter plugins by target ENUM in install-plugins.sh` | scripts/lib/install-plugins.sh, scripts/install.sh | bash -n + regression dry-run | +| 3 | `feat(brain-plugins): register 4 consumer-universal plugins (code-review, security-guidance, pr-review-toolkit, telegram)` | plugins-manifest.json (+4) | jq schema + target check | +| 4 | `feat(brain-plugins): register and activate context7 user-level+consumer` | plugins-manifest.json (+1), settings-fragment.json (+1), cache cp side-effect | jq + cache dir + runtime smoke | +| 5 | `docs(brain-routing): bump v1.1 → v1.2 with Phase 1 entries; chore brain-version v1.2 → v1.3` | docs/brain-plugin-routing.md, .brain-version | grep version + verify.sh | + +После commit 5: `git tag brain-v1.3` (не амендится; следующие итерации — `brain-v1.3.1` per memory project_outstanding_items rule). + +**Push на origin/main:** ТОЛЬКО после явного user-approve, не auto. + +### §8.1. Rollback strategy + +| Что сломалось | Rollback | +|---|---| +| Spec self-review выявил противоречие (commit 1) | Amend commit 1 (изолирован) | +| install-plugins.sh регрессия (commit 2) | `git revert ` — manifest и spec остаются | +| 4 entries малформированы (commit 3) | `git revert ` — install-plugins.sh уже умеет filter | +| Context7 cache cp fail / npx broken (commit 4) | `git revert ` + `rm -rf ~/.claude/plugins/cache/claude-plugins-official/context7/` | +| routing.md mismatch (commit 5) | `git revert ` | + +--- + +## §9. Открытые риски + +### §9.1. Технические + +- **C6 npx availability** — не верифицировано на машине Дмитрия. Если npx absent → Context7 в brain runtime не работает; деградация до registered-only. +- **C7 bun availability** — не верифицировано для Liderra deploy; не блокер brain v1.3, но блокер Liderra distribute telegram. +- **C8 MCP coexistence** — merge-mcp.sh не тестировался на сценарии «magic + context7 одновременно». Verify-checkpoint в plan. +- **lychee/markdownlint** — не верифицировано наличие на машине. +- **shellcheck** — не верифицировано наличие. + +### §9.2. Документационные + +- Spec self-review (§10) может выявить ambiguity, требующую правки до Phase 1B start'а. +- routing.md changes v1.2 могут потребовать обновления `Plugin_stack_rules.template.md` для consumer'ов (PSR template), но это вне scope brain v1.3 — будет в Phase 1C / Liderra integration. + +### §9.3. Risk acknowledgment community-managed + +Phase 1 вводит **первые** community-managed plugin'ы в brain distribute (Context7 — Upstash, telegram — community). До v1.2 brain содержал только Anthropic-authored + 2 marketplace с vetted-репутацией (FD/UPM через `nextlevelbuilder/ui-ux-pro-max-skill`, superpowers через `obra/superpowers`). + +Для **Liderra (152-ФЗ персданные):** +- Context7 → шлёт только docs queries (не PII). Acceptable. +- Telegram → обмен сообщениями через бота. Перед production-use Liderra — обязательная allowlist policy в `/telegram:access`, явное согласование с заказчиком на data flows. + +--- + +## §10. Spec self-review (выполняется автором перед user review) + +**Placeholders scan:** +- `` в §4.1 (Context7 entry) — будет подставлен в Phase 1B при actual commit. Это placeholder с явной семантикой, не TODO. +- `` в §4.5 — то же самое. +- `` в §4.5 (sha plug) — phasing, означает «текущий sha brain-v1.2». +- Других TBD / TODO в тексте нет. + +**Internal consistency:** +- §2 таблица 5 артефактов согласована с §4.1-§4.5 файловыми изменениями (5 plugins ↔ 5 entries в manifest). +- §3.1 архитектурная диаграмма соответствует §4.3 install-plugins.sh filter logic. +- §5 C1-C10 не противоречат §6 verification (каждый conflict либо mitigated через config, либо имеет verify-checkpoint). +- §8 atomic commits sequence согласован с §4 deliverables (commit N → file group N). + +**Scope check:** +- Фокусирован на одну задачу — Phase 1 release с 5 plugins + install-sh fix. +- НЕ включает Phase 2 stack-gated, custom skills, Liderra deploy — явно вынесено в out-of-scope §1. +- Готов под один writing-plans → executing-plans cycle. + +**Ambiguity check:** +- `community-managed` — однозначно определено как «не Anthropic-authored, поддержка третьей стороной» (см. marketplace.json tag). +- `target` ENUM — три значения определены в routing.md v1.1 §4.1 (`user-level`, `consumer`, `user-level+consumer`). +- `installMethod` — два значения используются (`manual-cp-from-marketplace-Path2`, `registered-only-not-cached`), оба явно описаны. + +**Известные ограничения (не верифицировано):** +- npx availability в env Дмитрия +- bun availability +- shellcheck, markdownlint, lychee availability +- Точное поведение Claude Code при enabling plugin'а с bundled `.mcp.json` — auto-register или нужна manual edit `~/.claude/.claude.json`? Documenting как assumption, verify-checkpoint в Phase 1B commit 4. + +--- + +## §11. Что после этого spec'а + +1. **User review этого файла** — phase 1A gate. +2. После approve → invoke `superpowers:writing-plans` для детального implementation plan'а Phase 1B (5 атомарных коммитов по §8). +3. Plan review с пользователем. +4. Invoke `superpowers:executing-plans` для выполнения plan'а с verification checkpoints (§6). +5. Final invoke `superpowers:verification-before-completion` перед claim «Phase 1 brain v1.3 готов». +6. (Опционально, после user-approve) push на origin/main + git tag brain-v1.3. + +**Brain v1.3 release не требует Liderra deploy** — это отдельный Phase 1C (или часть Phase 2 при decision point).