# Design Spec — Claude Brain Extraction

**Источник:** этот документ — копия design spec'а из Лидерры (2026-05-10-claude-brain-extraction-design.md) на момент bootstrap brain v1.0. Hard-link для future-reference.

**Дата:** 2026-05-10 (поздний вечер) / 2026-05-11 (создание spec)
**Автор:** Claude Code (под mode 0%)
**Статус:** Draft → ожидает review заказчика
**Связано:** [feedback_superpowers_hard_rule.md](../../../../.claude/projects/c---------------------crm-------------/memory/feedback_superpowers_hard_rule.md), [project_state.md](../../../../.claude/projects/c---------------------crm-------------/memory/project_state.md)

---

## §1. Цели

**Главная цель:** выделить «мозг Claude» — переиспользуемый набор правил, хуков, плагинов и визуализаций — из репозитория Лидерры в **независимый артефакт**, чтобы:

1. **Лидерра не страдает.** Текущий код, схема, тесты и нормативка Лидерры остаются на месте без изменений (кроме одного маркер-файла `.brain-version`).
2. **Мозг развивается отдельно.** Эксперименты над хуками, новыми правилами, новыми плагинами идут в песочнице мозга и не ломают релизный пайплайн Лидерры.
3. **Мозг переиспользуется.** Будущие проекты Дмитрия подключают мозг через one-command sync и получают полный стек правил без копипаста.
4. **Версионируется.** Каждая ревизия мозга — теговая, с CHANGELOG, с обратимостью.

**Не цели (явно):**
- Не превращаем мозг в коммерческий продукт (private repo, только для Дмитрия).
- Не делаем мозг universal-for-any-team (правила содержат явные предпочтения Дмитрия — стиль коммуникации, mode 0% паттерн).
- Не автоматизируем продакшен-deploy мозга (sync ручной по команде).

---

## §2. Scope

### §2.1. В scope

**Артефакты, которые переезжают в brain repo (v1.0):**

| Тип | Файл сейчас (Лидерра) | Размер | Назначение |
|---|---|---|---|
| Meta | [CLAUDE.md](../../../../../CLAUDE.md) | 266 строк | Оперативная карта Claude Code |
| Rules | [docs/Pravila_raboty_Claude_v1_1.md](../../Pravila_raboty_Claude_v1_1.md) | 720 строк | 13 продуктовых правил Claude |
| Rules | [docs/Plugin_stack_rules_v1.md](../../Plugin_stack_rules_v1.md) | 916 строк | 16 правил координации плагинов |
| Tooling | [docs/Tooling_v8_3.md](../../Tooling_v8_3.md) | 613 строк | Реестр 33 инструментов |
| Changelog | [docs/CHANGELOG_claude_md.md](../../CHANGELOG_claude_md.md) | n/a | История правок CLAUDE.md |
| Viz | [docs/visualizations/hooks-skills-plugins-map.html](../../visualizations/hooks-skills-plugins-map.html) | 3122 строки | Интерактивная карта мозга |
| Hook | `~/.claude/hooks/skill-marker.py` | 710 B | PreToolUse:Skill marker |
| Hook | `~/.claude/hooks/skill-check.py` | 2521 B | §12 reminder |
| Hook | `~/.claude/hooks/economy-mode.py` | 15081 B | UserPromptSubmit parser «экономия N%» |
| Hook | `~/.claude/hooks/economy-mode-test.py` | 6882 B | Тесты парсера |
| Hook | `~/.claude/hooks/economy-self-check.py` | 2191 B | SessionStart infrastructure-check |
| Hook | `~/.claude/hooks/economy-self-check-test.py` | 4244 B | Тесты self-check |
| Hook | `~/.claude/hooks/economy-state-guard.py` | 3872 B | PreToolUse in-turn state-guard |
| Hook | `~/.claude/hooks/economy-state-guard-test.py` | 3597 B | Тесты state-guard |
| Hook | `~/.claude/hooks/economy-postcompact.py` | 2138 B | PostCompact re-inject |
| Hook | `~/.claude/hooks/economy-verifier.py` | 1329 B | Stop wrapper для agent verifier |
| Config | `~/.claude/settings.json` (фрагмент) | 145 строк | `enabledPlugins` + `permissions` + `hooks` (без `theme`, без paths-специфики) |
| **Plugins** | `~/.claude/settings.json:22-27` (enabledPlugins) | 6 строк | 4 включённых плагина: superpowers, claude-md-management, frontend-design, ui-ux-pro-max |
| **Marketplaces** | `~/.claude/plugins/known_marketplaces.json` | 26 строк | 3 источника: anthropics/claude-plugins-official, obra/superpowers, nextlevelbuilder/ui-ux-pro-max-skill |
| **Plugin manifest** | `~/.claude/plugins/installed_plugins.json` | 45 строк | Pinned versions + gitCommitSha для 4 плагинов (для воспроизводимости) |
| **MCP user** | `~/.claude.json:535-548` (mcpServers) | 14 строк | `magic` (21st.dev) — в brain как **template с placeholder'ом для API_KEY** |
| **MCP project (universal)** | [`.mcp.json`](../../../.mcp.json) (playwright, github, semgrep) | ~17 строк из 28 | Универсальные MCP — переезжают в brain как `project-mcp-universal.template.json` |
| **MCP project (Лидерра)** | [`.mcp.json`](../../../.mcp.json) (`laravel-boost`) | ~5 строк из 28 | Лидерра-only (зависит от `app/artisan boost:mcp`) — **остаётся в Лидерре**, не в brain |

**Итого в brain v1.0:** 6 markdown/html artifacts (~5637 строк) + 10 Python hook-скриптов (~42 KB) + 1 settings-фрагмент (3 секции) + 3 plugin/marketplace manifest файла + 2 MCP template файла (user-level + project-level-universal).

### §2.2. Вне scope

- **Не переезжает:** `db/schema.sql`, ТЗ Лидерры, brandbook, handoff, supplier-specs, реализация моделей/views/тестов Лидерры — это **content проекта**, не «мозг».
- **Не переезжает:** memory-файлы (`~/.claude/projects/<liderra-hash>/memory/*.md`) — они per-project per-conversation, не часть мозга.
- **Не переезжает:** `~/.claude/plugins/cache/` — десятки MB бинарников плагинов. Восстанавливаются автоматически из `claude plugin install` после прописывания enables+marketplaces (см. §6.6).
- **Не переезжает:** `~/.claude/sessions/`, `~/.claude/shell-snapshots/`, `~/.claude/telemetry/`, `~/.claude/file-history/`, `~/.claude/ide/`, `~/.claude/.last-cleanup`, `~/.claude/backups/`, `~/.claude/.credentials.json` — runtime-данные машины, не «мозг».
- **Не переезжает:** `~/.claude.json` целиком (581 строк проектных preferences, usageCount, oauthAccount, etc.) — машинно-локальный + user-account-specific. Из него извлекается **только** секция `mcpServers` (как template).
- **Не переезжает:** Лидерра-специфичный MCP `laravel-boost` из `.mcp.json` — его команда `php app/artisan boost:mcp` требует Laravel-приложения в `app/`.
- **Не переезжает:** GITHUB_TOKEN, API_KEY для magic — секреты. Документируются в README.md brain'а как env-vars/interactive prompt.
- **Не переезжает:** настройки Claude Code GUI (theme, editorMode, statusLine) — машинно-локальное предпочтение.
- **Не переезжает:** ТЗ рекламного лендинга, supplier integration plan — content Лидерры.

### §2.3. Спорные кейсы (зафиксированные решения)

| Кейс | Решение v1.0 | Обоснование |
|---|---|---|
| CLAUDE.md содержит и универсальные правила, и Liderra-specific tech stack | Целиком в brain как `CLAUDE.md.template`, секции §2 (стек), §6 (фаза), §7 (Boost detail) маркируются как `<!-- PROJECT-SPECIFIC -->` блоки | Чистого разделения нет; маркеры позволяют будущему generator'у фильтровать |
| Pravila содержит cross-refs на CRM_bp-gr_Инструкция_v8_5.md, schema.sql, ТЗ | Целиком в brain как `Pravila.template`; cross-refs остаются как «пример проекта» с явным `<!-- EXAMPLE: liderra -->` | Удалять примеры → теряем context для брайншторминга; помечаем |
| Plugin_stack_rules — на 100% project-agnostic? | Да, 916 строк правил → brain без изменений | Все 16 правил говорят о Vue/Vuetify/Brandbook абстрактно; конкретный Brandbook — content проекта |
| Tooling_v8_3.md упоминает Liderra-специфичный db/schema.sql v8.11 | В brain template; раздел «Текущая фаза проекта» маркируется PROJECT-SPECIFIC | Tooling registry — мозг (структура реестра + 33 слота + матрица конфликтов), но фазовая раскладка — content |
| Visualization HTML содержит 50 узлов с именами реальных хуков мозга | В brain без изменений — она и описывает мозг | Visualization — это визуальное представление brain'а самого |
| `magic` MCP содержит API_KEY = `da9dbfbdd4ad...` в plaintext | В brain как `mcp-user.template.json` с placeholder `<<MAGIC_API_KEY>>`; install.sh при первом запуске prompt'ит и подставляет | API_KEY — секрет; нельзя в repo даже private (gitleaks pre-commit отловит) |
| `.mcp.json` смешивает универсальный (playwright, github, semgrep) и Лидерра-only (laravel-boost) | Разделить на 2 файла: `project-mcp-universal.template.json` в brain + `project-mcp-project-specific.json` (laravel-boost) остаётся в Лидерре | laravel-boost требует Laravel-приложения; новый консьюмер без Laravel не сможет его запустить |
| Plugin marketplaces — отдельный JSON или встроить в `installed_plugins.json`? | Отдельный `marketplaces.json` (формат как `~/.claude/plugins/known_marketplaces.json`) | Сохраняет совместимость с нативным форматом Claude Code; install.sh просто `cp` его в нужное место |
| Plugin pinning через gitCommitSha — обязателен или мягкий? | Жёсткое pinning v1.0: install.sh после `claude plugin install` проверяет фактический SHA против manifest, fail если mismatch | Воспроизводимость = brain v1.0 гарантирует ту же версию superpowers 5.1.0 + SHA `f2cbfbef` на всех консьюмерах |

---

## §3. Архитектура

### §3.1. Три физических артефакта

```
┌───────────────────────────────────────────────────────────────┐
│  АРТЕФАКТ A: claude-brain repo (новый, отдельный)             │
│  Путь:    c:/моя/проекты/claude-brain/                        │
│  GitHub:  CoralMinister/claude-brain (private)                │
│  Роль:    Source of truth для всех brain artifacts            │
│  Edit:    Только в этом репозитории (sandbox-friendly)        │
└───────────────────────────────────────────────────────────────┘
                            │
                            │ install.sh --target=<path> --version=<tag>
                            ▼
┌───────────────────────────────────────────────────────────────┐
│  АРТЕФАКТ B: consumer-проект (например, Лидерра)              │
│  Путь:    c:/моя/проекты/портал crm/Документация/             │
│  GitHub:  CoralMinister/lidpotok (private, существующий)      │
│  Роль:    Потребитель мозга через sync                        │
│  Edit:    Brain-файлы НЕ редактируются вручную здесь;         │
│           правки = редактируй в brain repo → sync             │
│  Маркер:  .brain-version (содержит tag + SHA brain'а)         │
└───────────────────────────────────────────────────────────────┘
                            │
                            │ scripts/install.sh --target=$HOME/.claude
                            ▼
┌───────────────────────────────────────────────────────────────┐
│  АРТЕФАКТ C: ~/.claude/ (user-level config)                   │
│  Путь:    C:/Users/Administrator/.claude/                     │
│  Роль:    Где живут хуки и settings.json при runtime          │
│  Edit:    sync из brain repo (через install.sh)               │
│  Маркер:  ~/.claude/.brain-version                            │
└───────────────────────────────────────────────────────────────┘
```

### §3.2. Поток данных

**Развитие мозга (нормальный цикл):**

```
1. Дмитрий редактирует в claude-brain/ (через VSCode + Claude)
2. Эксперимент в claude-brain/experiments/ (не релизится)
3. Когда стабилизировалось → промоут в claude-brain/project-files/ или user-level-files/
4. git commit + git tag brain-vX.Y
5. (опционально) git push CoralMinister/claude-brain
6. В Лидерре: cd c:/моя/проекты/claude-brain && ./scripts/install.sh --target=/c/моя/проекты/портал\ crm/Документация --version=brain-vX.Y
7. Лидерра получает обновлённые brain artifacts; .brain-version обновляется
8. В Лидерре: git commit -m "chore: bump brain to vX.Y (SHA abc1234)"
```

**Песочница (эксперимент, не задевающий Лидерру):**

```
1. Дмитрий: cd c:/моя/проекты/claude-brain
2. git checkout -b experiment/new-hook
3. Создаёт/правит в claude-brain/experiments/new-hook.py
4. Тестирует через временный symlink или прямой запуск
5. Если ОК → промоут в user-level-files/hooks/new-hook.py + bump version
6. Если плохо → git branch -D experiment/new-hook (без следов в Лидерре)
```

**Обратное извлечение (rescue из Лидерры):**

```
Если brain artifact был ошибочно отредактирован в Лидерре через claude-md-management:
1. cd c:/моя/проекты/claude-brain
2. ./scripts/extract.sh --source=/c/моя/проекты/портал\ crm/Документация --file=CLAUDE.md
3. Скрипт делает diff между текущим brain CLAUDE.md.template и Лидерра-CLAUDE.md
4. Показывает diff, спрашивает: применить? merge? reject?
5. После применения — bump brain version, commit
```

### §3.3. Маркер `.brain-version` (контракт)

**Формат:** plain text, 2 строки

```
brain-v1.0
sha: 8a1f2c3d4e5b6789abcdef0123456789abcdef01
```

**Где живёт:**
- В consumer-проекте: `<repo-root>/.brain-version`
- В user-level: `$HOME/.claude/.brain-version`

**Контракт:**
- Скрипт `install.sh` пишет файл атомарно (tmp + mv).
- Скрипт `verify.sh` проверяет соответствие: ожидаемый tag/SHA = фактический.
- Lefthook hook (опционально, v1.1+) в Лидерре: при commit с изменёнными brain-файлами — fail если `.brain-version` не bumped.

---

## §4. Структура brain repo

```
c:/моя/проекты/claude-brain/
├── README.md                          # Что это, как использовать
├── CLAUDE.md                          # Meta — описание brain'а для самого Claude
├── manifest.json                      # version, list of artifacts, hash sums
├── CHANGELOG.md                       # История версий brain'а
├── .brain-version                     # self-marker (для verify)
│
├── project-files/                     # → копируется в <consumer-repo>/
│   ├── CLAUDE.md.template
│   ├── .mcp.json.template             # project-mcp-universal: playwright + github + semgrep
│   ├── docs/
│   │   ├── Pravila_raboty_Claude.template.md
│   │   ├── Plugin_stack_rules.template.md
│   │   ├── Tooling.template.md
│   │   ├── CHANGELOG_claude_md.template.md
│   │   └── visualizations/
│   │       └── hooks-skills-plugins-map.html
│   └── README.md                      # Что лежит в этой папке (для разработчика)
│
├── user-level-files/                  # → копируется в $HOME/.claude/ и $HOME/.claude.json
│   ├── hooks/
│   │   ├── skill-marker.py
│   │   ├── skill-check.py
│   │   ├── economy-mode.py
│   │   ├── economy-mode-test.py
│   │   ├── economy-self-check.py
│   │   ├── economy-self-check-test.py
│   │   ├── economy-state-guard.py
│   │   ├── economy-state-guard-test.py
│   │   ├── economy-postcompact.py
│   │   └── economy-verifier.py
│   ├── settings-fragment.json         # enabledPlugins + permissions + hooks секции
│   ├── plugins-manifest.json          # Pinned plugin versions + gitCommitSha (4 плагина)
│   ├── marketplaces.json              # 3 marketplace sources (anthropics, obra, nextlevelbuilder)
│   ├── mcp-user.template.json         # `magic` MCP с <<MAGIC_API_KEY>> placeholder
│   └── README.md
│
├── experiments/                       # Песочница, НЕ синкается
│   ├── README.md                      # Правила песочницы
│   └── .gitkeep
│
├── scripts/                           # Sync-инструментарий
│   ├── install.sh                     # Главный sync скрипт
│   ├── extract.sh                     # Reverse sync (brain ← consumer)
│   ├── verify.sh                      # Проверка целостности после install
│   └── lib/
│       ├── common.sh                  # Shared helpers (logging, color, exit)
│       └── merge-settings.sh          # JSON merge для settings.json
│
├── docs/                              # Документация brain'а самого
│   ├── architecture.md                # Эта spec в финальной форме
│   ├── how-to-use-brain.md            # User guide
│   ├── how-to-experiment.md           # Sandbox workflow
│   ├── adding-new-hook.md             # Гайд по добавлению нового хука в реестр
│   └── consumer-projects.md           # Список known consumer projects + их versions
│
└── .github/                           # CI на brain (lint Python, lint markdown)
    └── workflows/
        └── ci.yml
```

**Файлов всего на v1.0:** ~30 файлов + 10 hooks + 1 visualization + 4 plugin/MCP конфига. Размер репо ~270 KB.

---

## §5. Initial bootstrap (one-time)

**Цель:** создать brain repo на основе текущего состояния (Лидерра + ~/.claude/) и зафиксировать как `brain-v1.0`.

### §5.1. Шаги bootstrap (атомарные)

| # | Действие | Команда / файлы | Verification |
|---|---|---|---|
| 1 | Создать директорию | `mkdir -p c:/моя/проекты/claude-brain` | `ls -la` |
| 2 | git init | `cd c:/моя/проекты/claude-brain && git init` | `.git/` существует |
| 3 | Создать структуру каталогов | `mkdir -p project-files/docs/visualizations user-level-files/hooks experiments scripts/lib docs .github/workflows` | `tree -L 3` |
| 4 | Скопировать CLAUDE.md как template | `cp 'c:/моя/проекты/портал crm/Документация/CLAUDE.md' project-files/CLAUDE.md.template` | diff показывает 0 |
| 5 | Скопировать Pravila как template | `cp '.../docs/Pravila_raboty_Claude_v1_1.md' project-files/docs/Pravila_raboty_Claude.template.md` | diff показывает 0 |
| 6 | Аналогично — Plugin_stack_rules, Tooling, CHANGELOG_claude_md | через `cp` | diff проверки |
| 7 | Скопировать visualization | `cp '.../docs/visualizations/hooks-skills-plugins-map.html' project-files/docs/visualizations/` | diff показывает 0 |
| 8 | Скопировать все 10 хуков | `cp $HOME/.claude/hooks/*.py user-level-files/hooks/` | `ls user-level-files/hooks` = 10 файлов |
| 9 | Извлечь `enabledPlugins` + `permissions` + `hooks` из settings.json | `jq '{enabledPlugins, permissions, hooks}' $HOME/.claude/settings.json > user-level-files/settings-fragment.json` | `jq` валидируется как JSON; содержит ровно 3 ключа |
| 10 | Скопировать marketplaces.json | `cp $HOME/.claude/plugins/known_marketplaces.json user-level-files/marketplaces.json` | 3 marketplace в JSON |
| 11 | Извлечь plugin manifest | `cp $HOME/.claude/plugins/installed_plugins.json user-level-files/plugins-manifest.json` | 4 плагина с pinned versions + gitCommitSha |
| 12 | Извлечь user-level MCP с masking API_KEY | `jq '.mcpServers \| with_entries(.value.args \|= map(if test("API_KEY=") then "API_KEY=<<MAGIC_API_KEY>>" else . end))' $HOME/.claude.json > user-level-files/mcp-user.template.json` | API_KEY заменён placeholder'ом; gitleaks-сканирование показывает 0 secrets |
| 13 | Извлечь project-level universal MCP | Скопировать `.mcp.json`, удалить блок `laravel-boost` (Лидерра-only) → `project-files/.mcp.json.template` | jq показывает 3 server'а (playwright, github, semgrep), 0 laravel-boost |
| 14 | Написать meta-CLAUDE.md (brain'а) | Новый файл, объясняет что brain — ~30 строк | Markdown OK |
| 15 | Написать manifest.json | version=brain-v1.0, список ВСЕХ artifacts с sha256 (включая plugin/MCP конфиги), + min-python-version, + required-tools (`jq`, `gh`, `git`, `python3`) | JSON валиден, sha256 совпадает с реальными файлами |
| 16 | Написать README.md (root brain'а) | Quick start: install + extract + experiments + plugin install flow + secret setup | Markdown OK |
| 17 | Написать CHANGELOG.md | v1.0 entry с датой и составом (включая «plugins layer + MCP templates added») | Markdown OK |
| 18 | Написать scripts/install.sh | Контракт см. §6 (включая режимы `--with-plugins`, `--with-mcp`, secret prompt) | shellcheck OK |
| 19 | Написать scripts/extract.sh | Контракт см. §6.4 | shellcheck OK |
| 20 | Написать scripts/verify.sh | Проверка `.brain-version` + sha256 + plugin SHA pinning + MCP secrets resolved | shellcheck OK |
| 21 | Написать scripts/lib/install-plugins.sh | `claude plugin install` для каждой строки в `plugins-manifest.json`; verify SHA match | shellcheck OK |
| 22 | Написать scripts/lib/setup-secrets.sh | Interactive prompt для `<<MAGIC_API_KEY>>` (или GITHUB_TOKEN env-var hint) | shellcheck OK |
| 23 | Написать docs/* | architecture.md, how-to-use, how-to-experiment, consumer-projects.md, secrets-and-tokens.md | Markdown OK |
| 24 | Написать .gitignore | Исключить `experiments/*` (кроме `.gitkeep` и `README.md`), `__pycache__`, `*.pyc`, **`*-resolved.json`** (файлы с подставленными секретами после install) | OK |
| 25 | Написать CI workflow | actions/checkout + python lint + markdown lint + **gitleaks scan (secret check)** + jq validate всех JSON | YAML валиден |
| 26 | **Gitleaks self-scan** перед первым коммитом | `gitleaks detect --source=.` на свежем brain repo | 0 findings (или whitelist documented exclusions) |
| 27 | git add . && git commit -m "feat: initial brain v1.0 extracted from Liderra" | atomic commit | `git log` 1 entry |
| 28 | git tag brain-v1.0 | теговая ревизия | `git tag` показывает |
| 29 | Создать GitHub repo CoralMinister/claude-brain (private) | gh repo create | curl 200 OK |
| 30 | git push origin main --tags | публикация | gh repo view OK |
| 31 | В Лидерре: создать `.brain-version` файл | `echo "brain-v1.0\nsha: <SHA>" > .brain-version` | cat OK |
| 32 | В Лидерре: git add .brain-version && commit -m "chore: declare brain v1.0 installed" | atomic | git log OK |

**Critical:** шаги 4–13 — **копирование/извлечение**, не перемещение. После bootstrap brain artifacts в Лидерре и в `~/.claude/` остаются на месте. Удалять оригиналы **не нужно** для v1.0 — они становятся «installed copy». Sync direction после bootstrap: brain → консьюмер (one-way override).

**Шаг 26 (gitleaks self-scan) — критичный gate:** если в brain repo попал реальный API_KEY (например, забыли применить шаг 12 masking), commit/push не делается до фикса. Это защита от R13 в §9.

### §5.2. Что НЕ делаем при bootstrap

- ❌ Не удаляем CLAUDE.md / Pravila / Tooling / `.mcp.json` из Лидерры — остаются как «текущая installed копия».
- ❌ Не правим `~/.claude/settings.json` / `~/.claude.json` — остаются рабочими; sync произойдёт когда install.sh запустится с `--target=$HOME/.claude`.
- ❌ Не удаляем `~/.claude/hooks/*.py` — работающие; sync их обновит позже.
- ❌ Не делаем `claude plugin uninstall` для существующих плагинов — они уже установлены, brain v1.0 их только pin'ит для воспроизводимости на других машинах.
- ❌ Не пушим API_KEY / GITHUB_TOKEN в repo даже private — gitleaks self-scan (шаг 26) — обязательный gate.
- ❌ Не пушим в GitHub до явного approval от заказчика (шаги 29–30 опциональны на этапе bootstrap).

### §5.3. Rollback bootstrap

Если bootstrap пошёл не так:
```
rm -rf c:/моя/проекты/claude-brain
rm c:/моя/проекты/портал\ crm/Документация/.brain-version
# В Лидерре: git reset --hard HEAD~1 (если коммит «declare brain» уже сделан)
```

Brain repo полностью изолирован; снос не задевает Лидерру.

---

## §6. Sync workflow и контракты скриптов

### §6.1. `scripts/install.sh` — главный sync

**Signature:**
```bash
./scripts/install.sh --target=<path> --version=<tag> [--dry-run] [--force] \
                     [--with-plugins=yes|no] [--with-mcp=yes|no] [--skip-secrets]
```

**Параметры:**
- `--target=<path>` — куда синкать; **обязательный**. Два режима:
  - Если `<path>` содержит `.git/` ИЛИ если в `<path>/docs/` есть Pravila — режим **project-files** (синкается `project-files/*` включая `.mcp.json.template`)
  - Если `<path>` = `$HOME/.claude` ИЛИ содержит `hooks/` ИЛИ `settings.json` — режим **user-level-files** (синкается `user-level-files/*` включая plugins/MCP)
  - Любой другой `<path>` → exit 1 с пояснением.
- `--version=<tag>` — какую версию brain'а накатывать; **обязательный**.
- `--dry-run` — показать что было бы скопировано, не копировать.
- `--force` — пропустить confirmation prompt и backup'ы (для CI).
- `--with-plugins=yes|no` — устанавливать ли плагины через `claude plugin install`. По умолчанию `yes` для user-level mode, `no` для project-files mode.
- `--with-mcp=yes|no` — копировать ли MCP-конфиги. По умолчанию `yes`.
- `--skip-secrets` — не запускать interactive prompt для API_KEY (для CI или повторного запуска). Файлы остаются с `<<MAGIC_API_KEY>>` placeholder; consumer должен resolve вручную.

**Поведение:**
1. Валидация: brain repo clean (no uncommitted), tag существует, `command -v jq python3 git` — все есть.
2. Detection режима по `<target>`.
3. Backup существующих файлов: `<target>/.brain-backup-<timestamp>/`.
4. Копирование (cp -p — сохранить mtime).
5. Для settings-fragment.json (user-level mode): JSON merge с существующим settings.json через `scripts/lib/merge-settings.sh` (заменяет ключи `enabledPlugins` + `permissions` + `hooks`, остальное оставляет).
6. **(user-level mode + --with-mcp=yes)** Merge `mcp-user.template.json` в `~/.claude.json` (ключ `mcpServers`) через `scripts/lib/merge-mcp.sh`. Если placeholder `<<MAGIC_API_KEY>>` всё ещё в файле — запустить `setup-secrets.sh` (если не `--skip-secrets`).
7. **(project mode + --with-mcp=yes)** Если `<target>/.mcp.json` уже существует — `merge-mcp.sh` добавляет только universal-серверы (playwright, github, semgrep), оставляя project-specific (например, laravel-boost в Лидерре). Иначе — `cp .mcp.json.template <target>/.mcp.json`.
8. **(user-level mode + --with-plugins=yes)** Запуск `scripts/lib/install-plugins.sh`:
   - Прочитать `marketplaces.json` → для каждого marketplace: `claude marketplace add <repo>` если ещё нет
   - Прочитать `plugins-manifest.json` → для каждого плагина: `claude plugin install <name>@<marketplace>`
   - После каждого install: сравнить фактический gitCommitSha с pinned в manifest. Mismatch → warn (но не fail; marketplace мог обновиться, что норма)
9. Запись `.brain-version` в `<target>`.
10. Запуск `scripts/verify.sh --target=<target>`.

**Exit codes:**
- 0 — успех
- 1 — параметры неверны или prereqs отсутствуют (jq/python3/git)
- 2 — brain repo dirty (требует stash или commit)
- 3 — tag не существует
- 4 — target unrecognised
- 5 — verification после copy не прошла → автоматический rollback из backup
- 6 — `claude plugin install` упал (network / marketplace 404)
- 7 — secret prompt отменён юзером (Ctrl+C) и нет `--skip-secrets`

### §6.2. `scripts/verify.sh` — проверка целостности

**Signature:** `./scripts/verify.sh --target=<path> [--strict-secrets]`

**Что проверяет:**
1. `.brain-version` существует и парсится.
2. Tag в `.brain-version` существует в brain repo.
3. Для каждого файла из `manifest.json` соответствующего режима: sha256 файла в `<target>` == ожидаемого sha256 в manifest. **MCP/secrets файлы исключены** — их sha256 отличается после secret resolution.
4. Для user-level mode: settings.json валидный JSON, содержит ожидаемые секции `enabledPlugins.{4 плагина}`, `permissions.allow`, `permissions.deny`, `permissions.ask`, `hooks.{SessionStart,PreToolUse,UserPromptSubmit,PostCompact,Stop}`.
5. Для user-level mode: все 10 hooks исполняемые (`-x`), Python синтаксис OK (`python -m py_compile`).
6. **Plugin check:** для каждого плагина из `plugins-manifest.json` — `claude plugin list` показывает его установленным и enabled.
7. **MCP check:** в `~/.claude.json:mcpServers` есть `magic`; в `<consumer>/.mcp.json` есть playwright/github/semgrep.
8. **`--strict-secrets`:** ни один файл в `<target>` не содержит placeholder'ов `<<*>>` (значит все секреты resolved). По умолчанию OFF — placeholder допустим в `.mcp.json.template` копиях.

**Exit codes:**
- 0 — все ОК
- 1 — `.brain-version` нет или невалидный
- 2 — sha256 mismatch (с указанием файла)
- 3 — settings.json повреждён
- 4 — hook script невалидный
- 5 — плагин из manifest не установлен
- 6 — MCP-сервер из ожидаемых не найден
- 7 — `--strict-secrets` и найден unresolved placeholder

### §6.3. `scripts/lib/merge-settings.sh` — JSON merge для settings.json

**Зачем нужен:** `~/.claude/settings.json` в Лидерра-машине содержит `theme`, `editorMode`, `statusLine` и т.п., что **не часть мозга**. Brain владеет только `enabledPlugins` + `permissions` + `hooks`. При sync нельзя просто `cp` settings — затрётся theme.

**Алгоритм:**
```bash
jq -s '.[0] * {enabledPlugins: .[1].enabledPlugins, permissions: .[1].permissions, hooks: .[1].hooks}' \
  <target>/settings.json \
  <brain>/user-level-files/settings-fragment.json \
  > <target>/settings.json.tmp
mv <target>/settings.json.tmp <target>/settings.json
```

**Edge case:** если `<target>/settings.json` не существует → копируется `settings-fragment.json` целиком.

### §6.3a. `scripts/lib/merge-mcp.sh` — JSON merge для MCP-конфигов

**Зачем нужен:** два source'а MCP — user-level (`~/.claude.json:mcpServers`) и project-level (`<repo>/.mcp.json:mcpServers`). Brain владеет subset'ом (magic в user, playwright/github/semgrep в project); консьюмер может иметь свои дополнительные (Лидерра имеет `laravel-boost`).

**Алгоритм (user-level):**
```bash
# Merge: brain MCP-servers поверх consumer's, оставляя дополнительные
jq -s '.[0] | .mcpServers = ((.mcpServers // {}) * .[1].mcpServers)' \
  <target>/.claude.json \
  <brain>/user-level-files/mcp-user.template.json \
  > <target>/.claude.json.tmp
mv <target>/.claude.json.tmp <target>/.claude.json
```

**Алгоритм (project-level):**
```bash
# Merge: brain universal MCP + consumer's existing (например, laravel-boost)
jq -s '.[0] | .mcpServers = ((.[0].mcpServers // {}) * .[1].mcpServers)' \
  <target>/.mcp.json \
  <brain>/project-files/.mcp.json.template \
  > <target>/.mcp.json.tmp
mv <target>/.mcp.json.tmp <target>/.mcp.json
```

**Edge case:** если target-файл не существует → создаётся из template.

### §6.3b. `scripts/lib/setup-secrets.sh` — interactive secret resolution

**Зачем нужен:** brain хранит template с `<<MAGIC_API_KEY>>` placeholder'ом. Реальный API_KEY — у пользователя в голове / в KeePass / в env.

**Алгоритм:**
1. Сканировать `<target>/.claude.json` на placeholder'ы `<<*>>`.
2. Для каждого — prompt: «Введите значение для `<<MAGIC_API_KEY>>` (или ENTER для пропуска):»
3. Если введено — `sed -i "s|<<MAGIC_API_KEY>>|$INPUT|"`.
4. Если пропущено — оставить placeholder + добавить в `.brain-deferred-secrets.txt` (для последующего напоминания).

**Альтернатива:** `--secret=MAGIC_API_KEY=<value>` через CLI (non-interactive режим для CI).

**Secrets list для v1.0:**
- `<<MAGIC_API_KEY>>` — API_KEY для 21st.dev Magic MCP
- `GITHUB_TOKEN` — НЕ через placeholder, через env-var (документировано в `docs/secrets-and-tokens.md`)

### §6.3c. `scripts/lib/install-plugins.sh` — Claude Code plugin installer

**Зачем нужен:** brain хранит `plugins-manifest.json` (4 плагина с pinned versions). После копирования файлов нужно реально установить плагины через CLI Claude Code.

**Алгоритм:**
```bash
# 1. Add marketplaces from marketplaces.json
for marketplace in $(jq -r 'keys[]' <brain>/user-level-files/marketplaces.json); do
  repo=$(jq -r ".[\"$marketplace\"].source.repo" <brain>/user-level-files/marketplaces.json)
  if ! claude marketplace list | grep -q "$marketplace"; then
    claude marketplace add "$repo"
  fi
done

# 2. Install plugins from plugins-manifest.json
for plugin_key in $(jq -r '.plugins | keys[]' <brain>/user-level-files/plugins-manifest.json); do
  expected_sha=$(jq -r ".plugins[\"$plugin_key\"][0].gitCommitSha" <brain>/user-level-files/plugins-manifest.json)
  expected_ver=$(jq -r ".plugins[\"$plugin_key\"][0].version" <brain>/user-level-files/plugins-manifest.json)
  
  claude plugin install "$plugin_key"
  
  # Verify SHA pinning (warn if mismatch — marketplace might have updated)
  actual_sha=$(claude plugin info "$plugin_key" --json | jq -r '.gitCommitSha')
  if [[ "$actual_sha" != "$expected_sha" ]]; then
    log_warn "Plugin $plugin_key: expected SHA $expected_sha, got $actual_sha (marketplace updated)"
  fi
done
```

**Edge case:** если `claude` CLI не в PATH → exit 1 с инструкцией установить Claude Code сначала.

### §6.4. `scripts/extract.sh` — обратный sync (rescue)

**Signature:** `./scripts/extract.sh --source=<consumer-path> --file=<relative-path>`

**Зачем нужен:** Лидерра редактирует brain-файлы через плагин `claude-md-management` (правило §5 п.10 текущего CLAUDE.md). Если правка прошла в Лидерре, brain про неё не знает. extract.sh показывает diff и предлагает merge.

**Поведение:**
1. Найти файл в `<source>` по relative path (например, `CLAUDE.md`).
2. Найти соответствующий template в brain (`project-files/CLAUDE.md.template`).
3. Запустить `diff -u`.
4. Спросить: `[a]pply / [m]erge / [r]eject / [q]uit`.
5. Если apply — заменить template содержимым из consumer; не commit'ить (даёт юзеру review).
6. Если merge — открыть в `git mergetool` или fallback `code --diff`.

**Не запускается автоматически** — только по явной команде пользователя.

### §6.5. Идемпотентность install.sh

Запуск `install.sh --target=X --version=Y` **дважды подряд** = no-op после первого (всё уже на месте; backup перезаписывается). Защита от случайного двойного выполнения — через `.brain-version` check на старте: если tag совпадает и sha256 всех файлов уже совпадают — exit 0 с сообщением «уже установлено». Override через `--force`.

---

## §7. Brain dev workflow

### §7.1. Нормальный цикл «улучшить хук»

```
# 1. Открыть brain repo
cd c:/моя/проекты/claude-brain

# 2. Создать feature branch
git checkout -b feat/improve-economy-mode

# 3. Редактировать user-level-files/hooks/economy-mode.py
# (Claude может работать в этом репо так же как в Лидерре)

# 4. Запустить локально тесты
python user-level-files/hooks/economy-mode-test.py

# 5. Commit + push
git add user-level-files/hooks/economy-mode.py user-level-files/hooks/economy-mode-test.py
git commit -m "feat(economy-mode): handle multi-line prompts correctly"
git push origin feat/improve-economy-mode

# 6. Когда стабильно — merge в main, bump version
git checkout main && git merge feat/improve-economy-mode
# Обновить manifest.json (sha256 economy-mode.py)
# Обновить CHANGELOG.md (новая entry brain-v1.1)
git commit -m "chore: bump to brain-v1.1"
git tag brain-v1.1

# 7. Накатить в Лидерре (или $HOME/.claude)
./scripts/install.sh --target=$HOME/.claude --version=brain-v1.1

# 8. В Лидерре обновить .brain-version (если затронуло project-files)
./scripts/install.sh --target=/c/моя/проекты/портал\ crm/Документация --version=brain-v1.1
cd /c/моя/проекты/портал\ crm/Документация
git add .brain-version && git commit -m "chore: bump brain to v1.1"
```

### §7.2. Песочница (experiments/)

**Правило:** всё в `experiments/` — work-in-progress, не часть релиза, **не синкается** в consumer projects.

**Use case 1:** новый хук, неясно нужен ли вообще.
```
mkdir experiments/2026-05-15-syntax-check-hook
# Прототипировать в experiments/2026-05-15-syntax-check-hook/hook.py
# Тестировать через symlink: ln -s "$(pwd)/experiments/.../hook.py" $HOME/.claude/hooks/_experimental-syntax-check.py
# Когда зрелое — переезжает в user-level-files/hooks/syntax-check.py + manifest update + tests
```

**Use case 2:** альтернативная редакция Pravila.
```
mkdir experiments/2026-05-15-pravila-v1-11-draft
cp project-files/docs/Pravila_raboty_Claude.template.md experiments/2026-05-15-pravila-v1-11-draft/
# Редактировать draft независимо
# Когда готов — заменить template + version bump
```

**Гарантия:** `.gitignore` исключает `experiments/*` кроме `experiments/README.md` и `experiments/.gitkeep`. Эксперименты commit'ятся, но не уходят в публичный output sync.

### §7.3. Когда промоут из experiments → user-level-files

**Чеклист «зрелости»:**
- [ ] Имеет тесты, тесты проходят
- [ ] Не ломает существующие хуки (запустить `economy-self-check.py` после установки)
- [ ] Описан в `docs/` если меняет поведение
- [ ] manifest.json обновлён (новый sha256)
- [ ] CHANGELOG.md обновлён
- [ ] Локально протестирован на Лидерре в течение ≥1 рабочей сессии без проблем

Только после всех галочек → `git mv experiments/.../hook.py user-level-files/hooks/hook.py` + tag bump.

---

## §8. Границы редактирования (matrix)

| Файл | Где живёт source of truth | Где можно править | Где НЕЛЬЗЯ править |
|---|---|---|---|
| `CLAUDE.md` (в Лидерре) | `claude-brain/project-files/CLAUDE.md.template` | brain repo через `claude-md-management:claude-md-improver` (как сейчас) | прямой Edit в Лидерре |
| `docs/Pravila_raboty_Claude_v1_1.md` (в Лидерре) | `claude-brain/project-files/docs/Pravila*.template.md` | brain repo | Лидерра |
| `docs/Tooling_v8_3.md` (в Лидерре) | `claude-brain/project-files/docs/Tooling.template.md` | brain repo | Лидерра |
| `docs/Plugin_stack_rules_v1.md` (в Лидерре) | `claude-brain/project-files/docs/Plugin_stack_rules.template.md` | brain repo | Лидерра |
| `~/.claude/hooks/*.py` | `claude-brain/user-level-files/hooks/*.py` | brain repo | ~/.claude/hooks/ напрямую |
| `~/.claude/settings.json` (секции `enabledPlugins` + `permissions` + `hooks`) | `claude-brain/user-level-files/settings-fragment.json` | brain repo | ~/.claude/settings.json напрямую |
| `~/.claude/settings.json` (секции `theme`, `editorMode`, `statusLine`) | `~/.claude/settings.json` (consumer-machine) | ~/.claude/settings.json | brain repo |
| `~/.claude/plugins/known_marketplaces.json` | `claude-brain/user-level-files/marketplaces.json` | brain repo | ~/.claude/plugins/ напрямую (install.sh пишет) |
| `~/.claude/plugins/installed_plugins.json` | `claude-brain/user-level-files/plugins-manifest.json` (pinned) | brain repo (для bump'а версий) | ~/.claude/plugins/ напрямую |
| `~/.claude.json` (секция `mcpServers`) | `claude-brain/user-level-files/mcp-user.template.json` (с placeholder) | brain repo template | ~/.claude.json напрямую (install.sh merge'ит) |
| `~/.claude.json` (всё кроме `mcpServers`) | `~/.claude.json` (consumer-machine) | ~/.claude.json | brain repo |
| `<consumer>/.mcp.json` (universal: playwright, github, semgrep) | `claude-brain/project-files/.mcp.json.template` | brain repo | напрямую `<consumer>/.mcp.json` (install.sh merge'ит) |
| `<consumer>/.mcp.json` (project-specific: laravel-boost) | консьюмер (например, Лидерра) | консьюмер | brain repo |
| **Secrets:** API_KEY для magic, GITHUB_TOKEN | НЕ в brain repo; локально у юзера | env-vars или setup-secrets.sh prompt | brain repo любой ценой (gitleaks gate) |
| `db/schema.sql`, ТЗ Лидерры, brandbook, web/v8 | Лидерра | Лидерра | brain repo |
| `experiments/*` | brain repo | brain repo, без sync | consumer projects |
| `.brain-version` (в Лидерре) | пишется install.sh | только install.sh | ручное редактирование |

### §8.1. Migration story (после bootstrap)

**Старый workflow (текущий):**
1. Дмитрий: «правь CLAUDE.md»
2. Claude: invoke `claude-md-management:claude-md-improver` → правит CLAUDE.md в Лидерре
3. Commit в Лидерра

**Новый workflow (после bootstrap brain v1.0):**
1. Дмитрий: «правь CLAUDE.md»
2. Claude: `cd c:/моя/проекты/claude-brain && invoke claude-md-management:claude-md-improver` → правит `claude-brain/project-files/CLAUDE.md.template`
3. Commit в brain
4. `./scripts/install.sh --target=<liderra> --version=<new-tag>` → синкает в Лидерру
5. Commit в Лидерра: bump `.brain-version`

**Transition strategy:** v1.0 — оба workflow работают (sync пока ручной, claude-md-management всё ещё может править Лидерра-файлы). v1.1+ — добавляется guard-хук, который блокирует Edit на brain-файлах в Лидерре, перенаправляя в brain repo.

---

## §9. Риски и митигации

| # | Риск | Вероятность | Импакт | Митигация |
|---|---|---|---|---|
| R1 | Sync затирает локальные правки в Лидерре, сделанные через claude-md-management до bootstrap | Средняя | Высокий (потеря работы) | install.sh делает backup в `.brain-backup-<timestamp>/` перед любым cp; verify.sh показывает diff между будущим состоянием и текущим в режиме `--dry-run` |
| R2 | Brain дрейфует от Лидерры — extracted templates устаревают, в Лидерре есть новые правки | Высокая (особенно при активной работе через claude-md-management) | Средний | extract.sh для periodic rescue; `verify.sh` показывает «extraneous changes detected» если sha256 mismatch; CI алерт |
| R3 | Hook несовместим с новым consumer проектом (например, тестовый проект где economy-mode не нужен) | Низкая | Средний | install.sh `--target=<X>` поддерживает фильтрацию через `manifest.json` поле `optional: true` (v1.1+); v1.0 — все или ничего |
| R4 | Циркулярная зависимость: brain содержит ссылку на Pravila §12.3 «список skills exclusions», который меняется | Средняя | Низкий | Pravila template параметризуется (`{{SKILL_LIST}}` placeholders, заполняется при install). v1.0 — без параметризации, copy as-is |
| R5 | settings.json merge через jq падает на edge cases (escaped quotes в commands) | Низкая | Высокий (`~/.claude` сломан) | merge-settings.sh делает backup settings.json.bak перед merge; verify.sh запускается обязательно после; на ошибке rollback |
| R6 | GitHub repo CoralMinister/claude-brain не создаётся (PAT expire / 404) | Низкая | Низкий | bootstrap шаги 22–23 опциональны; brain repo работает локально без GitHub до момента готовности |
| R7 | На другой машине bash/jq/python не установлен — install.sh падает | Высокая (если когда-то развернётся не на dev-машине) | Средний | scripts/install.sh в начале делает `command -v jq python3 git || exit 1` с явным сообщением; в README.md — список prereqs |
| R8 | Cyrillic path `c:/моя/проекты/...` ломает install.sh (bash в Windows ≠ POSIX) | Средняя | Высокий | Все скрипты использовать `"$1"` quoted переменные; тестировать на кириллических target из bootstrap |
| R9 | Лидерра-разработчик случайно отредактирует CLAUDE.md в Лидерре, sync затрёт | Высокая (особенно в первые недели после bootstrap) | Средний | v1.1+ — git pre-commit hook в Лидерре, который алертит на изменения brain-файлов с подсказкой «правь в claude-brain»; v1.0 — только документация |
| R10 | Brain repo grows uncontrollably (experiments не чистятся) | Низкая | Низкий | `experiments/` в .gitignore (всё кроме README.md); CI алерт если в commit включён `experiments/*` |
| R11 | Версии brain'а несовместимы (например, hook v1.2 требует Python feature которого нет на machine) | Низкая | Высокий | verify.sh проверяет Python version compatibility (`python --version >= 3.10`); manifest.json содержит min-python-version |
| R12 | Дмитрий начинает терять trust «brain — лишний слой, можно же напрямую» | Средняя (если value не очевиден в первый месяц) | Высокий (откат всей затеи) | v1.0 даёт сразу 1 visible win: возможность экспериментировать без страха за Лидерру; docs/how-to-experiment.md показывает конкретный кейс |
| R13 | API_KEY для `magic` MCP попадает в brain repo как plaintext (масштаб leak: 21st.dev account compromise) | Средняя (легко забыть применить шаг 12 masking) | **Критический** (security incident) | Bootstrap шаг 26 — обязательный gitleaks self-scan перед commit; CI workflow брена запускает gitleaks на каждый push; в `~/.claude.json` reference сейчас уже viewable, при extraction обязательное замещение через jq на `<<MAGIC_API_KEY>>`. README brain'а — explicit warning «никогда не cp без masking» |
| R14 | `claude plugin install` упал — marketplace 404, network down, версия более не существует | Средняя (open-source plugins могут breaking-change) | Высокий (полный stack не работает на новом консьюмере) | install.sh exit code 6 + fallback: список плагинов попадает в `<target>/.brain-pending-plugins.txt`, юзер ставит вручную позже; verify.sh покажет «5 plugins expected, 3 installed»; manifest содержит SHA для воспроизводимости |
| R15 | Project-level MCP конфликтует: Лидерра имеет `laravel-boost`, новый консьюмер без Laravel — install копирует и ломает | Средняя | Средний | `merge-mcp.sh` для project-mode merge'ит только universal-серверы (playwright/github/semgrep) поверх существующих; никогда не удаляет project-specific (laravel-boost остаётся). Новый консьюмер начинает с пустого `.mcp.json` → получает только universal |
| R16 | Plugin SHA pinning не работает — `claude plugin install` не поддерживает `@<sha>` | Средняя (зависит от Claude Code CLI features) | Низкий | install.sh после `claude plugin install <name>@<marketplace>` сравнивает фактический SHA с manifest и логирует warning (не fail). Воспроизводимость достигается на best-effort; v1.1+ может ввести `claude plugin install --pin=<sha>` если CLI поддержит |
| R17 | Marketplace плагин (например, superpowers) обновился между brain v1.0 и v1.1 — старый pin SHA не существует на marketplace | Низкая (marketplace история git — никогда не удаляется) | Средний | manifest хранит и version (`5.1.0`) и SHA. При install — fallback на version pinning если SHA не найден. README документирует marketplace stability |
| R18 | Brain extraction шага 12 (jq masking) затирает API_KEY, но в `~/.claude/backups/` остаётся незамаскированная копия (auto-backup Claude Code) | Низкая | Средний (потенциальный secondary leak) | Bootstrap шаг включает `find $HOME/.claude/backups/ -name "*.json" -newer 2026-05-10 -exec gitleaks detect --source={} \;` — алертит если backup содержит API_KEY; remediation — ротировать API_KEY |

### §9.1. Что НЕ риск, но часто кажется

- ❌ «Brain repo на GitHub утечёт» — repo private; **после применения R13 mitigation** (masking) нет credentials/PII; сами хуки и правила не secrets.
- ❌ «Sync рушит Claude Code сессию» — install.sh не трогает запущенные процессы; settings.json reload — встроенная feature Claude Code, тестировалось при economy hook setup (10.05.2026).
- ❌ «Claude путается какой brain версии» — `.brain-version` файл + verify.sh даёт явный однозначный ответ.
- ❌ «Plugin cache десятки MB — надо хранить в brain» — нет; cache восстанавливается из marketplace через `claude plugin install`. Manifest pinning обеспечивает версию.
- ❌ «GITHUB_TOKEN надо в brain как secret» — нет; это env-var (`${GITHUB_TOKEN}` в `.mcp.json` resolution — runtime Claude Code), документируется в `secrets-and-tokens.md`.

---

## §10. Success criteria (acceptance)

### §10.1. Bootstrap (v1.0) принят, если:

1. **Brain repo существует** в `c:/моя/проекты/claude-brain/` с git history и тегом `brain-v1.0`.
2. **Все brain artifacts извлечены** — 6 markdown/html templates + 10 Python hooks + 1 settings-fragment + 3 plugin/marketplace JSON-конфига + 2 MCP template файла в правильных папках.
3. **`.brain-version` в Лидерре** содержит `brain-v1.0` и SHA коммита.
4. **install.sh успешно прогоняется** `--dry-run` на Лидерре (показывает «no changes needed» — потому что Лидерра уже содержит исходники).
5. **verify.sh возвращает 0** на Лидерре и на `$HOME/.claude/`.
6. **Лидерра не пострадала:** Pest 545+/547 проходит как до bootstrap (на момент plan'а; экономия hooks отдельным spec'ом отслеживается); git log Лидерры показывает только +1 commit «declare brain v1.0 installed».
7. **Эксперимент проверен:** в `experiments/test-experiment/` создан тестовый файл, commit'нут, верифицировано что он НЕ попадает в Лидерру после sync.
8. **Gitleaks self-scan brain repo passes:** 0 findings (`gitleaks detect --source=c:/моя/проекты/claude-brain` → exit 0); если есть findings — bootstrap не принят до фикса masking.
9. **Plugin pinning corrected:** `manifest.json` содержит `gitCommitSha` для всех 4 плагинов из `installed_plugins.json`; verify.sh на `$HOME/.claude/` подтверждает что все 4 плагина установлены и enabled.
10. **MCP templates корректные:** `mcp-user.template.json` содержит `<<MAGIC_API_KEY>>` placeholder вместо реального API_KEY; `.mcp.json.template` содержит 3 universal-сервера (playwright/github/semgrep) и **НЕ содержит** `laravel-boost`.

### §10.2. Brain переиспользуем (доказательство), если:

1. На второй (тестовой) папке-консьюмере (например `c:/tmp/test-consumer/`) запуск `install.sh --target=/c/tmp/test-consumer --version=brain-v1.0` создаёт ту же структуру brain artifacts.
2. `verify.sh` на тестовой папке возвращает 0.
3. **Plugin install reproduced:** на тестовой папке + чистом `$HOME/.claude/` (или контейнере) — `install.sh --target=$HOME/.claude --version=brain-v1.0 --with-plugins=yes` ставит 4 плагина из marketplaces; `claude plugin list` показывает все 4 enabled.
4. **MCP secret prompt работает:** при первом `install.sh` с `--with-mcp=yes` без `--skip-secrets` — interactive prompt запрашивает MAGIC_API_KEY; после ввода — placeholder в `.claude.json` заменён реальным значением.
5. (Опционально, v1.1+) на полностью чистой Windows-машине без существующего проекта — bootstrap brain'а + install в новый dir даёт рабочий стек.

### §10.3. Brain рабочий (живая верификация), если:

1. Дмитрий просит правку CLAUDE.md → Claude правит template в brain repo → install.sh синкает → правка появляется в Лидерре корректно.
2. Дмитрий просит эксперимент с новым хуком → создаётся в `experiments/` → не задевает Лидерру → промоут после стабилизации → следующий sync обновляет.
3. **Plugin update flow:** superpowers релизит 5.2.0 → Дмитрий правит `plugins-manifest.json` в brain (version + новый SHA) → bump brain v1.1 → install.sh синкает → `claude plugin update superpowers@superpowers-dev` ставит новую версию; old plugin SHA пишется в CHANGELOG.md brain'а.
4. **MCP добавление:** Дмитрий хочет добавить новый MCP-сервер `foo` в стек — правит `mcp-user.template.json` (или `.mcp.json.template`) в brain → bump → install.sh синкает; merge сохраняет уже существующие MCP в `~/.claude.json`.

---

## §11. Multi-project capability (future, v1.1+)

### §11.1. Что будет работать

- **N consumer projects** одновременно: brain v1.0 → Лидерра + Project-B + Project-C.
- Каждый consumer имеет свой `.brain-version`; могут быть разными (Лидерра на brain-v1.0, Project-B на brain-v1.1).
- `docs/consumer-projects.md` в brain repo ведёт learnyrecord: какие projects, какие versions.

### §11.2. Что потребует доработки (v1.1+)

- **Параметризация templates:** `{{PROJECT_NAME}}`, `{{TECH_STACK}}`, `{{CURRENT_PHASE}}` placeholder'ы. install.sh принимает `--project-config=<path>` с overrides.
- **Selective install:** только определённые хуки (например, без `economy-mode.py` для проекта, который не использует mode-режим).
- **Brain registry:** опциональный публичный реестр в `~/.claude/brain-registry.json` где список всех known consumer projects + их brain versions.

### §11.3. Гарантия совместимости

- Brain v1.0 — single consumer (Лидерра); v1.1+ multi-consumer без breaking changes для существующих consumer'ов (`install.sh --version=brain-v1.0` всегда работает как раньше).

---

## §12. Открытые вопросы

| # | Вопрос | Предлагаемый default (если не уточнить) |
|---|---|---|
| Q1 | Создавать ли GitHub repo на этапе bootstrap (шаги 22–23) или отложить? | Отложить; локального brain достаточно для v1.0 acceptance. |
| Q2 | Удалять ли оригиналы brain artifacts из Лидерры после sync? | Нет, v1.0 — оставить как «installed copy». v1.1+ может ввести `--move-mode`. |
| Q3 | Кто пишет meta `CLAUDE.md` brain'а (не template, а meta-описание самого brain repo)? | Claude в bootstrap, на основе этого spec'а. Дмитрий ревьюит. |
| Q4 | Шаг 9 (jq extraction permissions/hooks) — какие именно ключи входят в brain settings-fragment? | `permissions.allow`, `permissions.deny`, `permissions.ask`, `hooks` целиком. Остальное (theme, editorMode, MCP enables, statusLine) — машинно-локальное. |
| Q5 | Версионирование templates: brain v1.0 содержит Pravila v1.10 — что когда Pravila обновится? | Brain bump (v1.1) поверх template; cross-ref в CHANGELOG.md brain'а указывает на Pravila версию. |
| Q6 | Эксперименты могут использовать install в "test mode" (отдельный target dir для проверки)? | Да; install.sh уже поддерживает любой `<target>`. Spec README.md показывает пример. |
| Q7 | Pre-commit hook в Лидерре, блокирующий правки brain-файлов (R9 mitigation) — в bootstrap или отложить? | Отложить v1.1. v1.0 — только документация в .brain-version comment. |
| Q8 | Brain CI (lint Python, markdown) — обязателен v1.0 или v1.1? | v1.0 — минимальный workflow (Python syntax check + markdownlint). Полные проверки v1.1+. |
| Q9 | Backup retention (`.brain-backup-<timestamp>/`) — сколько хранить? | Все, не чистим автоматически; ручное удаление через `find -mtime +30 -delete` если нужно. v1.1+ — keep-last-5 policy. |
| Q10 | Возможно ли откатить sync без brain repo? | Через `.brain-backup-<timestamp>/` — да; `install.sh --rollback` команда v1.1+. v1.0 — ручной cp из backup. |
| Q11 | Где впервые ввести MAGIC_API_KEY при bootstrap? Или сразу его ротировать (старый дискомпрометирован показом в текущей сессии)? | **Ротировать API_KEY на 21st.dev до bootstrap** (текущий показан в этом spec'е выше — формально compromised); новый держать только в KeePass; setup-secrets.sh prompt запрашивает при первом install. |
| Q12 | `laravel-boost` MCP в Лидерре — оставить там в локальном `.mcp.json`, не в brain? | Да, остаётся в Лидерре `.mcp.json`. Когда install.sh синкает universal-MCP — merge-mcp.sh не трогает laravel-boost. В brain documentation добавить как «project-specific MCP example». |
| Q13 | Plugin pinning через `gitCommitSha` — fail или warn при mismatch? | **Warn по умолчанию** (marketplace может обновиться, что норма); `--strict-plugin-sha` flag — fail. Воспроизводимость = best-effort, не absolute (open-source marketplace может удалить commit). |
| Q14 | Где список Claude Code CLI команд для `claude plugin install` / `claude marketplace add` — задокументирован ли? | **Не верифицировано** что CLI Claude Code имеет именно такие команды (или они другие). Перед bootstrap — `claude --help` + `claude plugin --help`; alternative — править файлы напрямую (`installed_plugins.json` + `known_marketplaces.json` + `~/.claude/settings.json:enabledPlugins`) и просить юзера restart Claude Code. |
| Q15 | Project-level `.mcp.json` в новом консьюмере (без существующего файла) — нужно ли создавать его? | Да, install.sh в project-mode копирует `.mcp.json.template` → `<consumer>/.mcp.json` если файла нет. Новый консьюмер получает 3 universal-MCP сразу. |
| Q16 | На какой стадии brain bootstrap пользователь должен ротировать compromised API_KEY? Перед bootstrap или после первого install? | **Перед bootstrap**: чтобы шаг 12 (jq masking) и шаг 26 (gitleaks scan) проверяли уже неважный плейстекст. После — устанавливать новый через setup-secrets.sh prompt. |
| Q17 | `claude plugin install <name>@<marketplace>` — нужен ли подтверждающий prompt от Claude Code (untrusted plugin warning) при первом запуске? | **Не верифицировано** что новый marketplace требует trust dialog. Из памяти `feedback_environment.md` (квирк auto-mode classifier блокировал untrusted plugin install) — вероятно да. install.sh может попросить юзера один раз подтвердить через `/plugin` UI. |

**Принцип:** все Q* перед началом bootstrap — либо ответ от заказчика, либо явный «default OK». В spec фиксируем default — Дмитрий может override любой пункт.

---

## §13. Что НЕ верифицировано (mode 0% honesty)

- ❌ **Не верифицировано** что `jq` установлен на dev-машине Windows. План считает что есть; если нет — install.sh падает с понятной ошибкой (R7 мит). Bootstrap шаг должен включать `command -v jq` check.
- ❌ **Не верифицировано** что bash на Windows (Git Bash) корректно обрабатывает кириллические paths в `cp` и `git`. Был успех в текущей сессии (мы работаем в `c:/моя/проекты/...`), но скрипты с `set -e` могут падать на edge cases. R8 — открытый риск.
- ❌ **Не верифицировано** что `gh repo create` доступна с текущим PAT (fine-grained, scope «repositories: write»). Шаги 22–23 опциональны до подтверждения.
- ❌ **Не верифицировано** что extract.sh на текущий brain template и Лидерра-CLAUDE.md покажет нулевой diff (они должны быть идентичны после bootstrap; перед commit'ом — обязательная проверка через `diff -u`).
- ❌ **Не верифицировано** что после sync hooks в `$HOME/.claude/hooks/` Claude Code их **перечитывает** без рестарта. Из памяти `feedback_environment.md` известно что settings.json reload требует `/hooks` UI или restart; для hook scripts (только содержимое .py) — `os.path` resolve каждый раз, теоретически live-reload работает, но не проверено явно.
- ❌ **Не верифицировано** что текущий `~/.claude/settings.json` имеет именно те `enabledPlugins` + `permissions` + `hooks` секции, которые описаны в реестре v1.86 шапки. Частично проверено в этой сессии — enabledPlugins имеет 4 плагина (lines 22-27); полное описание секций будет в шаге 9 bootstrap'а.
- ❌ **Не верифицировано** что Claude Code CLI имеет команды `claude marketplace add <repo>`, `claude plugin install <name>@<marketplace>`, `claude plugin list`, `claude plugin info --json`. Перед bootstrap — выполнить `claude --help` и `claude plugin --help`; если команд нет, fallback на прямое редактирование JSON-конфигов + restart Claude Code (Q14).
- ❌ **Не верифицировано** что `claude plugin install` поддерживает SHA pinning (`--pin=<sha>` или `<plugin>@<sha>` syntax). Default поведение в spec'е — warn при SHA mismatch (Q13), не fail.
- ❌ **Не верифицировано** что после copying hooks в `$HOME/.claude/hooks/` и обновления settings.json через merge-settings.sh — Claude Code их auto-reload без рестарта IDE. Из памяти `feedback_environment.md` известна потенциальная проблема с watchers (создание новой `.claude/` директории требует `/hooks` UI открыть или restart). install.sh должен предупреждать.
- ❌ **Не верифицировано** что `gitleaks` установлен на dev-машине. Из памяти известно — есть `bin/gitleaks.exe` в Лидерра repo; brain repo должен ссылаться на тот же или иметь свой; bootstrap шаг 26 уточняет: запускать через `bin/gitleaks.exe detect --source=<brain-path>`.
- ❌ **Не верифицировано** что в `~/.claude/backups/` нет копий settings.json с историческим API_KEY (R18 риск). Перед bootstrap — `find $HOME/.claude/backups/ -name "*.json" | xargs gitleaks detect --source` для понимания scope leak'а.
- ❌ **Не верифицировано** что `jq` `*` оператор корректно merge'ит nested объекты (`.mcpServers.magic` ≠ `.mcpServers.{magic, playwright}` после merge). На сложных edge cases (вложенные массивы) `jq` может deep-merge или shallow-merge — нужно тестировать на реальном `~/.claude.json` перед finalize merge-mcp.sh.
- ❌ **Не верифицировано** что `claude plugin install` доступен **в текущей VSCode-extension Claude Code** (vs CLI). Из памяти известна квирка «`/plugin` недоступен в VSCode-extension — через ~/.claude/settings.json». Возможно потребуется CLI Claude Code отдельно или править файлы напрямую.

Все эти открытые места — **не блокеры spec'а**; будут проверены во время bootstrap implementation как explicit verification steps в plan'е. Конкретно для Q14/Q17 — первые 2 шага плана: discovery (`claude --help`) перед началом extraction.

---

## §14. Связанные документы

- **Этот spec:** `docs/superpowers/specs/2026-05-10-claude-brain-extraction-design.md`
- **Будущий plan:** `docs/superpowers/plans/2026-05-10-claude-brain-extraction.md` (создаётся через `superpowers:writing-plans` после approve этого spec'а)
- **Pravila §11** (override §2.2 / §4.5 / §8.4 разрешён только через explicit brainstorming): использовалось при design discussion
- **Plugin_stack_rules R10.1** (claude-md-management в брене инфраструктурный): обоснование почему #33 переезжает в brain
- **CLAUDE.md §5 п.10** (правки CLAUDE.md только через claude-md-management): требует обновления после bootstrap — «правки через brain repo + sync»
- **memory/feedback_superpowers_hard_rule.md**: содержит описание 6-component economy hook architecture — это часть brain'а

---

## §15. Self-review (по brainstorming skill checklist)

| Чек | Статус | Комментарий |
|---|---|---|
| Placeholder scan (TBD/TODO/«fill later») | ✅ | 0 найдено (только placeholder'ы для secrets — `<<MAGIC_API_KEY>>` — это intended design, не TBD) |
| Internal consistency: §3.1 артефакты ↔ §4 структура | ✅ | 3 артефакта (A/B/C) описаны в обеих секциях согласованно; §4 расширена 4 новыми файлами (plugins-manifest, marketplaces, mcp-user.template, .mcp.json.template) |
| Internal consistency: §5 bootstrap steps ↔ §6 install.sh контракт | ✅ | Шаги 18–22 (создание скриптов install + lib/install-plugins + lib/setup-secrets) согласованы с §6.1/§6.3a/§6.3b/§6.3c |
| Internal consistency: §8 matrix ↔ §6 поведение | ✅ | Matrix добавлены 6 новых строк (plugins/marketplaces/MCP user/MCP project/secrets); install.sh merge-mcp.sh обеспечивает «universal vs project-specific» разделение из matrix |
| Internal consistency: §2.1 inventory ↔ §10.1 success criteria | ✅ | §2.1 говорит 6 markdown + 10 hooks + 1 settings-fragment + 3 plugin/MCP конфига + 2 MCP template = §10.1 пункт 2 |
| Scope check: достаточно ли узок для одного plan'а | ✅ | v1.0 фокус: single consumer (Лидерра), single user-machine; полный stack (правила + хуки + плагины + MCP); multi-project отложен в §11 |
| Ambiguity check #1 | ✅ | §2.3 — маркеры `<!-- PROJECT-SPECIFIC -->`: v1.0 = HTML-комментарии в templates, без обработки |
| Ambiguity check #2 | ✅ | §6.3a merge-mcp.sh — `jq` оператор `*` deep vs shallow merge: помечено в §13 как «не верифицировано», план должен включать тест |
| Ambiguity check #3 | ✅ | §6.1 `--with-plugins` defaults: явно зафиксировано — `yes` для user-level, `no` для project-mode |
| Risks coverage | ✅ | 18 рисков (R1-R18) с явными митигациями; 5 «not-actually-risks» развенчаны. Критический R13 (API_KEY leak) имеет три уровня защиты: masking при extraction + gitleaks self-scan gate + CI scan на push |
| Success criteria measurable | ✅ | 10+5+4 conditions, все проверяемые `verify.sh` / `claude plugin list` / `gitleaks detect` / `git log` |
| Open questions complete | ✅ | 17 вопросов (Q1-Q17) с предложенными defaults; Q11, Q14, Q17 — explicit «не верифицировано» (помечены в §13) |
| Security: secret handling | ✅ | API_KEY никогда в repo (masking + gitleaks gate + .brain-deferred-secrets для tracking); GITHUB_TOKEN через env-var; ротация compromised key — explicit pre-bootstrap step (Q11, Q16) |
| Scalability: extra MCP servers | ✅ | merge-mcp.sh deep-merge сохраняет существующие MCP в `~/.claude.json`; новые brain MCP добавляются, старые user MCP остаются |

**Self-review итог:** spec готов к user review v2 (расширенный с plugins/MCP/secrets). Все ambiguity-фиксы применены inline. Версия spec'а — extended A (полный охват согласно решению пользователя).

---

**Конец spec'а.**