docs(brain-plugin): session-2 handoff — Task 1-2 + Task 4 benign + wall learnings

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/superpowers/specs/2026-06-15-brain-as-plugin-session-handoff-2.md

@@ -0,0 +1,161 @@
+# Brain-as-plugin — handoff сессии №2 (закрытие 2026-06-15)
+
+**Кодовая фраза стены:** «роутер-наставник». **Канон дизайна:** `2026-06-15-brain-as-plugin-design-v6.md`.
+**Канон плана Фазы 1:** `2026-06-15-brain-plugin-phase1-config-seam.md`. **Предыдущий handoff:**
+`2026-06-15-brain-as-plugin-session-handoff.md` (handoff №1). Этот файл — продолжение №1: что сделано
+во второй сессии, новые уроки про стену, драфты памяти, обновления GUIDE, промт для сессии №3.
+
+---
+
+## 1. Что сделано в этой сессии (всё закоммичено)
+
+- **Фаза 1, Задачи 1–2 — DONE, коммит `b9730af`.** Чистый модуль `tools/brain-config.mjs`
+  (`parseBrainConfig` парсер frontmatter + `resolveConfig` fail-safe дефолты §D3 + `loadConfig`
+  I/O-обёртка) + `tools/brain-config.test.mjs` (13 тестов). Модуль новый, ни к чему ещё не подключён
+  (подключение по ключам — Задачи 4–7). Спека `2026-06-15-brain-config-module-spec.md`, план-церемония
+  `...task1-ceremony-v3.md`.
+- **Фаза 1, Задача 4 (benign-часть) — DONE, коммит `97985b4`.** `tools/cross-ref-checker.mjs`:
+  `extractCrossRefs(text, opts={})` + `detectMismatches(files, opts={})` принимают `opts` (переопределение
+  `pathToName/linkRe/crossRe/normalizeName/normativeFiles`), **дефолт = текущие константы** (backward-compat,
+  байт-в-байт). +2 config-seam теста. Регрессия **3946 passed | 2 skipped, 0 failed** (в терминале владельца).
+  Спека `2026-06-15-crossref-config-seam-spec.md`, план `...crossref-config-seam-ceremony-v7.md`.
+
+---
+
+## 2. Решение по Task 4: benign vs security (fail-CLOSED) — согласовано с владельцем
+
+Task 4 (`normative_files`) расщеплён надвое (файлы вплетают пути нормативки в регэкспы/protected-списки,
+не «swap константы»):
+
+- **Benign (предупреждалки дрейфа):** `cross-ref-checker` (✅ сделано), `l1-watcher` (один путь Tooling в
+  I/O-функции `loadInputs`, тестов на неё нет → **отложен в Задачу 7 wiring**, где `loadConfig` всё равно
+  прокидывается в хуки).
+- **Security (write-защита, риск fail-open) — НЕ сделано:** `enforce-normative-content-rules`
+  (`NORMATIVE_PATTERNS`/`PROTECTIVE_NORMATIVE_PATTERNS`) + `shell-content-rules` (`DEFAULT_PROTECTED_PATTERNS`).
+  **Согласованный дизайн fail-CLOSED:** базовые паттерны остаются хардкодом и неизменны; config-ключ
+  `protected_paths` только **ДОБАВЛЯЕТ** (union), никогда не убирает. Пусто/нет config → база защищает
+  полностью. В тестах — явный fail-CLOSED кейс. Два config-ключа: `normative_files` (benign дрейф-чекеры) +
+  `protected_paths` (security augment). claude-brain: `protected_paths: []` → защита байт-в-байт как сейчас.
+
+---
+
+## 3. УРОКИ ПРО СТЕНУ (это «инструкция к мозгу» — занести в GUIDE, см. §6)
+
+Критичные находки этой сессии — без них следующая сессия повторит наши круги:
+
+1. **Спор с судьёй (L2 арбитраж) разрешается разделом «Переговоры» в ПЛАНЕ, а НЕ escape'ом.**
+   Когда `enforce-mentor-then-judge` выдаёт «Арбитраж (L2): тупик после N кругов» и пишет
+   «Позиция контроллера: (не указана в разделе «Переговоры» плана)» — это прямой намёк: добавь в план
+   секцию `## Переговоры` с позицией контроллера (разбери замечания судьи по пунктам). После этого судья
+   пропускает. **Проверено:** v7 cross-ref прошёл сразу после добавления «Переговоров»; v3–v6 без них
+   деадлочились.
+2. **`FLOOR-ESCAPE: write:…` НЕ открывает судью-ворота.** Escape чтут пол (M5) / стена (M2) / гейт памяти,
+   но **НЕ judge-gate** (аналогия: router-gate тоже floor_escape не читает). Для спора с судьёй escape
+   бесполезен — нужны «Переговоры». (Память: [[feedback-routing-tag-broken]], [[commit-via-wall-owner-terminal]].)
+3. **Полный `npx vitest run` ЧЕРЕЗ инструмент Bash рушится** («Cannot read properties of undefined
+   (reading 'config')» на 60+ несвязанных файлах, воркеры крашатся) под нагрузкой сессии (куча node-процессов
+   судьи/наставника). **Тот же прогон в терминале владельца — чистый** (3946 passed). **Вывод:** полную
+   регрессию верифицировать ТОЛЬКО в терминале владельца; прогон через Claude-Bash недостоверен.
+4. **MultiEdit в этом харнессе НЕДОСТУПЕН** (нет в инструментах; ToolSearch для его загрузки стена блокирует
+   как «не шаг плана»). В `steps-json` использовать только `Write`/`Edit`/`Bash`. Я заложил MultiEdit в план →
+   шаг стал неисполним → пришлось делать v3+.
+5. **Одиночный прогон тест-файла позиционно** (`npx vitest run --config … tools/X.test.mjs`) + явный
+   `import { describe, it, expect } from 'vitest'` в тесте **ломает сбор** («reading config» на `describe`).
+   Полный свод — работает. Лечение: опираться на `globals: true` из конфига (НЕ импортировать) ИЛИ всегда
+   гонять полный свод. (Корень не на 100% ясен — вероятно кэш/контекст воркера.)
+6. **Коммит — в терминале владельца** (минует `enforce-criterion-gate`, который на коммите через Claude
+   требует доказательство «мутация убита»). Команда `git add <явные пути>; git commit -m … -m "Co-Authored-By:
+   Claude Opus 4.8 <noreply@anthropic.com>"`.
+7. **Судья эскалирует осторожность к правке СУЩЕСТВУЮЩИХ файлов** (Edit → «устаревший контекст»; Write →
+   «без бэкапа»). Рецепт, прошедший судью: **Write-overwrite полного содержимого + шаг бэкапа `.bak` до него +
+   полный-свод RED→GREEN + раздел «Переговоры»**. Файл прочитать целиком в разговорном режиме заранее.
+
+---
+
+## 4. Драфты memory-записей (следующая сессия персистит штатно — escape владельца или claude-md-management)
+
+> Запись в `memory/*.md` гейтится `enforce-normative-content-rules` (Layer 5). Гейт памяти ЧТИТ escape
+> владельца (в отличие от судьи-ворот). Канал: `FLOOR-ESCAPE: write:<path>` per-file ИЛИ claude-md-management
+> в skills-json опломбированного плана + реальный вызов до шага записи.
+
+- **feedback_wall_judge_negotiation_not_escape.md** (feedback) — «Спор с судьёй (judge-gate L2 арбитраж)
+  разрешается разделом `## Переговоры` в плане с позицией контроллера, НЕ floor_escape. Арбитраж сам пишет
+  «Позиция контроллера: не указана». **Why:** floor_escape чтут пол/стена/память, не judge-gate. **How:**
+  при «тупик после N кругов» — добавь в новый план `## Переговоры`, разбери замечания судьи по пунктам.»
+- **feedback_vitest_harness_collapse_vs_terminal.md** (feedback) — «Полный `npx vitest run` через Claude-Bash
+  рушит воркеры (reading config на 60+ файлах) под нагрузкой сессии; тот же прогон в терминале владельца
+  чистый. **How:** полную регрессию верифицировать в терминале владельца, не через Claude-Bash.»
+- **feedback_multiedit_unavailable.md** (feedback) — «MultiEdit недоступен в харнессе. В steps-json только
+  Write/Edit/Bash.»
+- **feedback_vitest_single_file_import_break.md** (feedback) — «Одиночный прогон тест-файла позиционно + явный
+  vitest-импорт ломает сбор (reading config). Лечение: globals:true без импорта ИЛИ полный свод.»
+- **project_brain_plugin_phase1_progress.md** (project) — «Фаза 1 config-seam: Задачи 1–2 brain-config.mjs
+  (коммит b9730af); Задача 4 benign cross-ref-checker opts (коммит 97985b4); l1-watcher → Задача 7. Остаток:
+  Task 4 security (fail-CLOSED augment `protected_paths` для enforce-normative-content-rules +
+  shell-content-rules), Tasks 5–7 (registry_path/state_dir, project_url_whitelist/classifier_context, wiring).
+  Канон — design v6 + план Фазы 1 + handoff №2.»
+
+---
+
+## 5. Остатки по поиску (из handoff №1 §3 — актуальны)
+
+1. Полный per-file инвентарь слоя 1. 2. Задача 4 плагин-смоук (owner-gated). 3. Судьба неподключённых
+   v4-хуков. 4. Инлайн `node -e` хуки. 5. Минимум документации в поставке + чистка Лидерра-примеров в GUIDE.
+   6. Единый user-manual по всему мозгу. 7. **Баг наставника / трение судьи** (теперь понятнее — см. §3 п.1:
+   «Переговоры» снимают деадлок; но судья всё равно перестраховывается на каждой правке существующего файла —
+   кандидат сгладить). 8. Канал in-place правки артефакта. 9. Уборка версий (spec v1–v5 + черновики планов
+   crossref v1–v6 + brain-config v1–v2 + `cross-ref-checker.mjs.bak` — стрелять под escape/ceremony).
+
+---
+
+## 6. Обновить GUIDE (`docs/superpowers/router-mentor-wall-GUIDE.md`) — задача со звёздочкой
+
+Внести в GUIDE уроки §3 (правка существующего файла → нужна церемония, gated). Минимум — новая секция
+**«Разрешение спора с судьёй (L2 арбитраж)»**: «тупик после N кругов» → добавь `## Переговоры` в новый план
+(escape не работает для судьи). Плюс заметки: полный свод верифицировать в терминале владельца (Claude-Bash
+рушит воркеры); MultiEdit недоступен; одиночный vitest+импорт ломает сбор. Делать ceremony'ей (Edit
+существующего GUIDE гейтится стеной) ИЛИ owner-escape на `write:<guide-path>` (GUIDE не нормативка, но Edit
+существующего файла под стеной — шаг плана).
+
+---
+
+## 7. Скилл-цепочка (как и в №1)
+
+1. `using-superpowers` — всегда первым (авто на старте).
+2. Дизайн новых остатков → `brainstorming` → `writing-plans`.
+3. Исполнение Фазы 1 → `executing-plans` ИНЛАЙН (субагенты под стеной запрещены, VA-4) + `test-driven-development`.
+   Предусловие: план опломбировать; при деадлоке судьи — раздел `## Переговоры` (§3 п.1).
+4. Память/нормативка → `claude-md-management` (skills-json плана + вызов) ИЛИ owner escape.
+5. Трение судьи (§5 п.7) → `systematic-debugging`.
+
+---
+
+## 8. Промт для следующей сессии (копировать целиком)
+
+```
+Продолжаем эпик «Мозг как плагин Claude Code» в проекте claude-brain. Кодовая фраза стены — «роутер-наставник», работаем ПО ПРАВИЛАМ (authoring-канал для новых .md в docs/superpowers/{specs,plans}; escape/память — только с моего разрешения; субагенты под стеной запрещены — инлайн; коммит — в моём терминале).
+
+Сначала прочитай (разговорный режим, чтение свободно):
+- docs/superpowers/specs/2026-06-15-brain-as-plugin-design-v6.md (канон дизайна)
+- docs/superpowers/plans/2026-06-15-brain-plugin-phase1-config-seam.md (план Фазы 1)
+- docs/superpowers/specs/2026-06-15-brain-as-plugin-session-handoff-2.md (ЭТОТ handoff №2 — сделано, УРОКИ ПРО СТЕНУ §3, драфты памяти §4, обновить GUIDE §6, скилл-цепочка §7)
+- docs/superpowers/specs/2026-06-15-brain-as-plugin-session-handoff.md (handoff №1 — контекст)
+- docs/superpowers/router-mentor-wall-GUIDE.md (как работать под стеной)
+
+ВАЖНО про стену (handoff №2 §3): спор с судьёй (L2 арбитраж «тупик после N кругов») разрешается разделом `## Переговоры` в плане, НЕ escape'ом; полную регрессию vitest верифицировать в МОЁМ терминале (через Claude-Bash воркеры рушатся); MultiEdit недоступен; одиночный vitest+импорт ломает сбор → globals/полный свод.
+
+Скилл-цепочка (§7): using-superpowers → (brainstorming → writing-plans для дизайна) → executing-plans ИНЛАЙН + test-driven-development для Фазы 1 → claude-md-management для памяти → systematic-debugging для трения судьи.
+
+Сделай в начале:
+1. Залей драфты памяти (handoff №2 §4) в memory-store + строки в MEMORY.md (через claude-md-management или мой escape — спроси).
+2. Спроси меня, что берём дальше: Task 4 security-часть (fail-CLOSED augment) / обновить GUIDE §6 / сгладить трение судьи / Tasks 5–7 / уборка версий (escape).
+
+Не пломбируй и не коммить без моего клика. Все находки фиксируй в authoring-доки, в память — только по правилам.
+```
+
+---
+
+## 9. По правилам — напоминания
+- Новые `.md` в `specs/`/`plans/` — стена пускает свободно (authoring). Правка существующего / память / settings / код — гейтится.
+- Коммит этой сессии: `b9730af` (Задачи 1–2) + `97985b4` (Задача 4 benign) — оба в терминале владельца.
+- Стрелять под escape/ceremony позже: `cross-ref-checker.mjs.bak` + черновики планов (crossref v1–v6, brain-config v1–v2) — мусор уборки версий.