brain/docs/architecture.md

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, 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	266 строк	Оперативная карта Claude Code
Rules	docs/Pravila_raboty_Claude_v1_1.md	720 строк	13 продуктовых правил Claude
Rules	docs/Plugin_stack_rules_v1.md	916 строк	16 правил координации плагинов
Tooling	docs/Tooling_v8_3.md	613 строк	Реестр 33 инструментов
Changelog	docs/CHANGELOG_claude_md.md	n/a	История правок CLAUDE.md
Viz	docs/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 (playwright, github, semgrep)	~17 строк из 28	Универсальные MCP — переезжают в brain как project-mcp-universal.template.json
MCP project (Лидерра)	.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:

./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.

Алгоритм:

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):

# 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):

# 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.

Алгоритм:

# 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
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'а.