# Дизайн: выделение «мозга» в отдельный проект `claude-brain` (v4)

**Дата:** 2026-06-15

## Цель

Разделить смешанный репозиторий `Документация` на два проекта:

1. **`claude-brain`** (новый, `C:\моя\проекты\claude-brain`) — дом дальнейшей разработки управляющего слоя Claude (router / mentor / observer / registry / enforcement-машинерия `tools/`).
2. **`Документация` (текущий)** — продукт **Лидерра** (Laravel + Vue CRM) плюс замороженная рабочая копия управляющего слоя, которая продолжает действовать. Дальнейшая работа в текущем репозитории — только над Лидеррой.

Управляющий слой **копируется** в `claude-brain` (не вырезается из текущего). В текущем репозитории он остаётся как замороженная рабочая копия. Жёсткое требование: `claude-brain` работает автономно (свои тесты зелёные, хуки исполняются), а рабочая копия в текущем репозитории не ломается.

## Решения {#D1}

- **Модель связи — снимок.** Текущий репозиторий держит замороженную рабочую копию управляющего слоя + Лидерру. `claude-brain` — дом разработки. Будущие улучшения вносятся в `claude-brain` и вручную переносятся в текущий репозиторий по отдельной команде. Автоматической синхронизации между репозиториями нет.
- **git у `claude-brain` — чистый старт.** Новый репозиторий, первый коммит = текущее состояние управляющего слоя. История остаётся в исходном репозитории: управляющий слой и Лидерра переплетены в общих коммитах, поэтому чистое разделение истории невозможно и не делается. Удалённый origin подключается позже (известное ограничение среды — GitHub-аккаунт временно недоступен).
- **Нормативный квартет — копия.** `claude-brain` получает копию `CLAUDE.md` / `Pravila_raboty_Claude_v1_1.md` / `Plugin_stack_rules_v1.md` / `Tooling_v8_3.md` / `CHANGELOG_claude_md.md` как есть. В текущем репозитории квартет остаётся как есть. Разбор содержимого на «управление vs продукт» — отдельная будущая задача, не эта.
- **Согласованность квартета между репозиториями (механизм против тихого дрейфа).** Снимок односторонний и асимметричный по роли. Канонический источник развития нормативки после разделения — копия в `claude-brain`; копия в текущем репозитории — замороженный снимок, который **не правится независимо**. Любая будущая правка governance делается в `claude-brain`, затем переносится в текущий репозиторий по явной команде; направление переноса всегда одно — `claude-brain` → текущий, встречных правок нет. Чтобы рассинхронизация была **видимой, а не тихой**, и **обратимой**:
  1. **Снимок-штамп.** Каждый перенос ставит в заголовок каждого файла квартета пометку «снимок: дата + исходный git-хэш `claude-brain`». Несовпадение штампов между репозиториями = явный сигнал расхождения, видимый при открытии файла.
  2. **Проверка дрейфа по запросу.** Расхождение детектируется текстовым `diff` двух копий квартета; ненулевой diff означает «текущий снимок отстал» → требуется ре-перенос из `claude-brain`.
  3. **Обратимость.** Каждая версия каждого файла восстановима из git-истории своего репозитория; односторонность переноса исключает конфликт встречных правок, поэтому «откатить дрейф» = заново скопировать канон из `claude-brain`. Необратимой потери смысла рантайма не возникает: рабочая нормативка, которую читает рантайм текущего репозитория, всегда есть в git этого же репозитория.
- **Тесты управляющего слоя — только в `claude-brain`.** ~3931 vitest-теста (`tools/*.test.mjs`) + `vitest.config.tools.mjs` (сейчас физически в `app/`) + скрипты `test:tools` / `eval:llm` / `brain:dashboard` переезжают в `claude-brain`. В текущем репозитории `test:tools` убирается из корневого `package.json`, `vitest.config.tools.mjs` выносится из `app/`. Рабочие модули `tools/*.mjs` в текущем репозитории остаются (их читает рантайм), исчезают только сами тест-файлы и тест-конфиг.

## Инвентарь — три корзины {#D2}

Источник: триангуляция нескольких независимых углов (граф проекта; карта импортов `tools/`; классификация конфигов; перекрёстные ссылки docs/memory; список активных runtime-процессов) + перепроверочный проход.

### A. Копируется в `claude-brain`

- `tools/*.mjs` (~180–190 рабочих модулей) + `tools/*.test.mjs` (~160–170 тестов) + данные `tools/` (`observer-chain-map.json`, `router-test-prompts.json`, `subagent-output-schema.json`, `.node-dormancy.json`, `enforce-override-vocab.json`, `observer-known-nodes.txt`). **Кроме** `tools/liderra-monitoring/` (это мониторинг продукта).
- `vitest.config.tools.mjs` (выносится из `app/` в корень `claude-brain`, с правкой относительных путей — {#D5}) + скрипты управляющего слоя (`test:tools` / `eval:llm` / `brain:dashboard`).
- `docs/observer/`, `docs/registry/`, `docs/router-procedure.md`, `docs/routing-off-phase.md`, `docs/discovery/`, управляющие руководства из `docs/superpowers/` (включая `router-mentor-wall-GUIDE.md`).
- управляющие specs/plans (правило ключевых слов — {#D3}), управляющие ADR (011, 016 + ADR off-phase-тулинга 003–010, 012–015, 017, 019).
- нормативный квартет (**копия** со снимок-штампом — {#D1}).
- память управляющего слоя + агенты `normative-sync`, `reviewer-agent`.
- подмножества общих конфигов: lefthook (управляющие job'ы), `.mcp.json` (управляющая часть — redis/perplexity/exa/firecrawl + общие github/semgrep), управляющая часть `package.json`, копии `cspell-words.txt` / `.gitignore`.

### B. Остаётся в текущем репозитории (Лидерра + замороженная рабочая копия)

- `app/`, `db/`, `web/`, `лендинг/`, `liderra_v8_handoff/`, `.github/workflows/`.
- Доки Лидерры: `docs/CRM_*`, `docs/Открытые_вопросы_*`, `docs/Analiz_*`, `docs/security/`, `docs/deploy/`, `docs/api/`, `docs/architecture/`, `docs/audit/`, `docs/ml/`, `docs/process/`, `docs/backend/`, `docs/projects/`, `docs/support/`.
- specs/plans Лидерры (billing / supplier / lead-region / slepok / audit / project / admin), ADR Лидерры (001, 002, 018).
- агенты `pest-parallel-debugger`, `rls-reviewer`, `prod-deploy-validator`, `tools/liderra-monitoring/`.
- Замороженная рабочая копия управляющего слоя: `tools/*.mjs` (полностью), `docs/observer/` + `docs/registry/`, квартет (как есть, со снимок-штампом). Тест-файлы `tools/*.test.mjs` здесь не нужны.
- Память Лидерры.

### C. Общее — расщепляется по факту

- `lefthook.yml` / `.mcp.json` / `package.json` / `.gitignore` — каждому репозиторию своё подмножество; общие job'ы (gitleaks / markdownlint / cspell) + общие MCP (github / semgrep) — в обоих.
- `cspell-words.txt` — неразделим → копия в обоих.
- скилы и плагины уровня пользователя (`~/.claude/skills/`, `~/.claude/plugins/`) — общая инфраструктура, вне git-дерева обоих репозиториев, не трогаются. `.claude/skills/` в репозитории — пусто (`.gitkeep`).

## Правило ключевых слов для specs/plans {#D3}

Контракт классификации файла `docs/superpowers/specs/*` и `docs/superpowers/plans/*` по подстроке имени:

- → `claude-brain`: `router-mentor`, `router-gate`, `router-discipline`, `judge`, `floor`, `escape`, `machine`, `observer`, `brain-governance`, `brain-factor`, `automation-graph`, `print-sanity`, `sealed-plan`, `safe-baseline`, `llm-first-router`, дизайны off-phase-тулинга.
- → остаётся: `billing`, `supplier`, `lead-region`, `slepok`, `audit`, `project`, `admin`, `deals`, `csv-reconcile`, `webhook`, `migrate`, `delete`, `parallel-sessions`, `controller-offload`.
- Спорные (`enforce-hard-rules`, `controller-offload-agents`, off-phase-тулинг) — в список ручной классификации перепроверочного прохода; по умолчанию при неоднозначности файл **копируется** в `claude-brain` и **остаётся** в текущем (дублируется, не теряется).

## Последовательность {#D4}

Безопасность гарантируется порядком «сначала собрать и проверить копию, потом удалять источник»:

1. **Сначала** собрать `claude-brain` (полная копия управляющего слоя) и **верифицировать автономно**: ~3931 vitest-теста проходят в `claude-brain`, хуки исполняются, gitleaks 0, отсутствуют данные/секреты Лидерры.
2. **Только после** автономной верификации `claude-brain` — удаление в текущем репозитории. Удаление **минимальное**: только артефакты разработки управляющего слоя, которые не читаются ни одним рабочим процессом (`tools/*.test.mjs`, управляющие design-specs/plans, заметки brain-retro, `vitest.config.tools.mjs` из `app/`, скрипт `test:tools` из корня). Рабочие входы (`tools/*.mjs`, `docs/observer/`, `docs/registry/`, квартет) — **не трогаются**.
3. **Перед удалением** в текущем репозитории — зафиксировать полный список активных runtime-процессов и то, какие пути они читают, чтобы не удалить нужное. До этой фиксации удаление не начинается. Фаза копирования (п.1) этим списком **не блокируется** — `claude-brain` получает всё.

## Крайние случаи и риски {#D5}

- **Относительные пути тест-конфига.** `vitest.config.tools.mjs` физически лежит в `app/` и адресует тесты как `include: ['../tools/*.test.mjs']` / `exclude: ['../tools/ruflo-*.test.mjs', '../tools/subagent-prompt-prefix.test.mjs']` (на уровень выше). При выносе в **корень** `claude-brain` (где `tools/` лежит рядом) эти пути обязаны стать `tools/*.test.mjs` / `tools/ruflo-*.test.mjs` / `tools/subagent-prompt-prefix.test.mjs` — иначе тесты не находятся. Это правка одного файла, выполняется при копировании.
- **Скрипт `test:tools` зависит от расположения конфига.** Текущая форма `cd app && npx vitest run --config vitest.config.tools.mjs` предполагает конфиг в `app/`. В `claude-brain` конфиг в корне → скрипт упрощается до `npx vitest run --config vitest.config.tools.mjs` без `cd app`.
- **Собственные зависимости рантайма `claude-brain`:** node_modules (`js-yaml`, `ajv`, `@xenova/transformers`, `undici`, `keytar`, `shell-quote`, `proper-lockfile`, `glob`, `natural`), внешний API-прокси, системное хранилище ключей, `git`, `powershell`. `claude-brain` нужен собственный `package.json` + `npm install` + lockfile; нельзя полагаться на `app/node_modules`.
- **Точный набор путей, читаемых рабочими процессами, фиксируется до фазы удаления** (см. {#D4} п.3); фаза копирования этим не блокируется.
- **Откат.** Удаление в текущем репозитории идёт в отдельной git-ветке/worktree — до слияния всё восстановимо `git restore`. `claude-brain` — новый каталог, на исходный репозиторий не влияет; при провале просто удаляется.

## Критерий готовности {#D6}

- `claude-brain`: `npm install` проходит; прогон тестов управляющего слоя даёт ту же зелёную сумму, что текущий `test:tools` в исходном репозитории (~3931 passed, с теми же exclude `ruflo-*` / `subagent-prompt-prefix`); хуки исполняются автономно; gitleaks 0; нет данных Лидерры (`app/`/`db/` отсутствуют).
- Текущий репозиторий **после** удаления: рабочая копия управляющего слоя по-прежнему действует (хуки срабатывают), регрессия Лидерры зелёная (Pest / Vitest frontend / Vite build), `git status` чист на ветке слияния.
- Согласованность квартета: оба снимка несут штамп (дата + git-хэш `claude-brain`); `diff` двух копий на момент завершения = 0 (свежий перенос).
- Независимая проверка: `claude-brain` полон (ничего несущего не забыто по корзине A) и рабочая копия в текущем репозитории не сломана.

```verified-context-json
[
  {"id": "vc-tools-data", "kind": "EXTRACTED", "ref": "tools/cost-pricing.mjs", "anchor": "export const PRICING = Object.freeze("},
  {"id": "vc-test-tools", "kind": "EXTRACTED", "ref": "package.json", "anchor": "\"test:tools\": \"cd app && npx vitest run"},
  {"id": "vc-vitest-config", "kind": "EXTRACTED", "ref": "app/vitest.config.tools.mjs", "anchor": "include: ['../tools/*.test.mjs']"},
  {"id": "vc-mcp-research", "kind": "EXTRACTED", "ref": ".mcp.json", "anchor": "\"firecrawl\": {"}
]
```
