brain/docs/adr/ADR-020-split-control-layer-into-claude-brain.md

ADR-020 Split the Claude control layer into a dedicated claude-brain repository

Status

Accepted. Date: 2026-06-15.

Decision Maker: User: Дмитрий (владелец Лидерры и управляющего слоя).

Context

Управляющий слой Claude (router / mentor / observer / registry / enforcement-машинерия tools/ — далее «мозг») и продукт Лидерра (Laravel + Vue CRM) много месяцев разрабатывались в одном репозитории Документация. Они переплетены в общих коммитах: governance-правила, гейт-хуки, observer-эпизоды и реестр инструментов жили рядом с кодом приложения, миграциями БД и доками продукта.

Это создало три проблемы. (1) Когнитивный шум: оперативная карта CLAUDE.md (~352 KB) описывает продукт Лидерру, хотя мозг — самостоятельная система; новый разработчик/сессия не отличает «дом мозга» от «дома продукта». (2) Связанность тестов и рантайма: ~3931 vitest-тест мозга (tools/*.test.mjs) и тест-конфиг физически лежали в app/ Лидерры, смешивая регрессии двух систем. (3) Нет дома развития: улучшения мозга нельзя было вести и версионировать отдельно от продуктового цикла Лидерры.

Триггер решения — намерение владельца развивать мозг как отдельный продукт, не ломая работающую рабочую копию в репозитории Лидерры.

Decision

Управляющий слой копируется (не вырезается) в новый репозиторий claude-brain (C:\моя\проекты\claude-brain), который становится единственным домом дальнейшей разработки мозга; в репозитории Документация копия остаётся как замороженный рабочий снимок, продолжающий действовать, а связь между репозиториями — односторонний снимок без автоматической синхронизации.

Развёртка решения:

• Модель связи — снимок, односторонний. Канон развивается в claude-brain; переносится в Документация только по явной команде владельца. Встречных правок нет — направление всегда claude-brain → Документация.
• Граница копирования задана инвентарём «три корзины» дизайна v5 ({#D2}): A — копируется в claude-brain (рабочие tools/*.mjs, их тесты, docs/observer/, docs/registry/, router-procedure.md, routing-off-phase.md, docs/discovery/, управляющие specs/plans по правилу ключевых слов {#D3}, управляющие ADR, нормативный квинтет, память мозга, агенты normative-sync + reviewer-agent); B — остаётся в Документация (Лидерра + замороженная рабочая копия мозга); C — общие конфиги расщепляются по подмножествам.
• Безопасность через порядок ({#D4}): сначала собрать и автономно верифицировать claude-brain, и только после — минимальное удаление в Документация (лишь dev-артефакты, которые не читает ни один рабочий процесс).

Alternatives Considered

Alternative A: Вырезать мозг из Документация (move, не copy) с чистым разделением git-истории

Разрезать историю по путям (git filter-repo) так, чтобы каждый репозиторий получил только свои коммиты. Отвергнуто: мозг и Лидерра переплетены в общих коммитах — один коммит часто трогает и tools/, и app/. Чистое разделение истории технически невозможно без потери атомарности или ручного переписывания сотен коммитов. Плюс move оставил бы рабочую копию Лидерры без действующих гейт-хуков до момента переноса — окно, в котором стена опущена.

Alternative B: Монорепо с пакетами (workspace) внутри одного репозитория

Оставить один репозиторий, выделить мозг в отдельный npm-workspace/пакет с собственным package.json и тестами. Отвергнуто: не решает когнитивный шум (всё ещё один CLAUDE.md, одна оперативная карта на два продукта) и сохраняет продуктово-связанный релизный цикл. Workspace-граница — внутрикодовая, а владельцу нужна репозиторная (разные удалённые, разные истории развития, разный доступ).

Alternative C: Ничего не делать — оставить смешанный репозиторий

Отвергнуто: три проблемы из Context остаются и усугубляются с каждым off-phase-эпиком (квинтет растёт, CLAUDE.md уже ~352 KB). Стоимость бездействия растёт нелинейно.

Consequences

Benefits

• claude-brain собран и верифицирован автономно: npm install чисто, npx vitest run --config vitest.config.tools.mjs = 231 файл / 3931 passed / 2 skipped; данных Лидерры нет (app//db//web/ отсутствуют — проверено рекурсивным glob). См. docs/superpowers/specs/2026-06-15-claude-brain-split-status-handoff.md {#H1}.
• Рабочая копия мозга в Документация не сломана: удалены только dev-артефакты (227 tools/*.test.mjs + тест-конфиг, commit 3aeedb8a, 28326 удалений); рабочие tools/*.mjs и квинтет нетронуты.
• Дом развития мозга отделён: собственный package.json (brain-зависимости), vitest.config.tools.mjs в корне, собственный git и origin github.com/CoralMinister/claude-brain.git.

Trade-offs

• Дублирование квинтета (5 нормативных файлов копируются как есть). Принятая цена за нерискованное разделение: разбор «управление vs продукт» внутри квинтета отложен как отдельная будущая задача.
• Ручной перенос правок governance вместо автосинхронизации — каждое улучшение требует явной команды копирования claude-brain → Документация.
• История развития мозга остаётся в Документация (чистого разреза нет); claude-brain стартует без неё.

Risks and mitigations

• Risk: тихий дрейф квинтета между репозиториями (копии расходятся незаметно). Mitigation ({#D1}): снимок-штамп «дата + git-хэш claude-brain» в заголовке каждого из пяти файлов делает расхождение видимым при открытии; текстовый diff двух копий детектирует дрейф по запросу; односторонность переноса делает откат = повторное копирование канона.
• Risk: удалить в Документация путь, который читает рабочий процесс. Mitigation ({#D4} п.3): до удаления фиксируется полный список активных runtime-процессов и читаемых ими путей; удаление идёт в отдельной ветке/worktree (восстановимо git restore).
• Risk: claude-brain зависит от app/node_modules Лидерры. Mitigation ({#D5}): собственный package.json + npm install + lockfile; автономная верификация подтвердила независимость.
• Risk (известное отклонение от дизайна v5): git-репозиторий claude-brain стартовал не с чистого старта — новый управляющий слой свален поверх истории старого brain-installer v1.3 (HEAD 7351f03), старые файлы помечены D в рабочем дереве, но не закоммичены. Mitigation: зафиксировано здесь как известное состояние; решение о санации git-истории (чистый initial-коммит vs принять наследие) остаётся за владельцем и в этот ADR не входит.

Related Decisions

• ADR-011 (Brain governance): разделяемая система (observer / router-procedure / контролёры) — её артефакты входят в корзину A и переезжают в claude-brain.
• ADR-016 (Universal skill-coverage): классификатор-роутер мозга — также корзина A.
• ADR-003…010, 012…015, 017, 019 (off-phase tooling): ADR управляющего тулинга копируются в claude-brain; ADR-001/002/018 (Лидерра) остаются в Документация.

References

• Дизайн: docs/superpowers/specs/2026-06-15-claude-brain-split-design-v5.md (решения {#D1}–{#D6}, инвентарь корзин).
• Статус и handoff: docs/superpowers/specs/2026-06-15-claude-brain-split-status-handoff.md (сделано {#H1}, хвост {#H2}, механика стены {#H3}, баг наставника {#H4}).
• Снимок-штамп и diff-проверка квинтета: дизайн v5 {#D1}.
• Прун-коммит в Документация: 3aeedb8a (227 тест-файлов + тест-конфиг, 28326 удалений).
• Тест-конфиг и пути: vitest.config.tools.mjs (include: ['tools/*.test.mjs'] после правки из ../tools/* — дизайн v5 {#D5}).

Enforcement

Code-surface нет — это governance/process-решение. Механически проверяемая граница (согласованность квинтета) распределена между двумя репозиториями и выражается процедурно: снимок-штамп в заголовках пяти файлов + diff двух копий по запросу ({#D1}). Декларативный adr-judge-блок здесь не задаётся: правило «канон правится только в claude-brain, переносится односторонне» — организационное, не выразимо regex-проверкой staged-diff в одном репозитории. Контроль — через снимок-штамп (видимое расхождение) и ре-перенос канона.