From 4ff8f2b41865c08c04e8136c3db636afe6c08141 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Mon, 15 Jun 2026 11:56:09 +0300 Subject: [PATCH] =?UTF-8?q?docs(brain-plugin):=20session-2=20handoff=20?= =?UTF-8?q?=E2=80=94=20Task=201-2=20+=20Task=204=20benign=20+=20wall=20lea?= =?UTF-8?q?rnings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- ...06-15-brain-as-plugin-session-handoff-2.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-15-brain-as-plugin-session-handoff-2.md diff --git a/docs/superpowers/specs/2026-06-15-brain-as-plugin-session-handoff-2.md b/docs/superpowers/specs/2026-06-15-brain-as-plugin-session-handoff-2.md new file mode 100644 index 0000000..292a83a --- /dev/null +++ b/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 "`. +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:` 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 не нормативка, но 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) — мусор уборки версий.