portal/docs/superpowers/router-mentor-wall-GUIDE.md

Как работать под стеной «роутер-наставник» (шпаргалка для сессий)

Читать ПЕРЕД работой под стеной. Обновлено 16.06.2026 — Фикс 1/2/3 (видимость вердикта, память кругов, owner-seal арбитраж) + находки F-J/F-K. Цель — не разбираться по исходникам.

Суть: под стеной реальная работа (Edit/Write/Bash по коду) проходит ТОЛЬКО как шаг опечатанного плана. Поток: спека → (печать) → план → (печать) → шаги по порядку → авто-завершение. Печать встаёт за ОДИН заход.

Рецепт церемонии (точные форматы — иначе печать не встанет)

1. СПЕКА — Write НОВОГО файла в docs/superpowers/specs/<уникальное-имя>.md:

• якорные секции ## Заголовок {#D1} … с непустым телом (контракт, edge-cases, конвенция, критерий);
• блок ```verified-context-json``` — массив с ≥1 EXTRACTED: {"id":"…","kind":"EXTRACTED","ref":"<существующий файл>","anchor":"<реальная подстрока ≥4 симв>"}. Готовый якорь: ref tools/cost-pricing.mjs, anchor export const PRICING = Object.freeze(;
• секцию ## Цель;
• НИКАКОЙ мета-болтовни (про печать/хеши/оркестратор/обход стены) — судья судит вслепую и завернёт fatal.

2. ПЛАН — Write НОВОГО файла в docs/superpowers/plans/<уникальное-имя>.md:

• ## Цель;
• ```skills-json``` — объявленные навыки, напр. ["test-driven-development"];
• ```steps-json``` — массив {op, object, ref}: op ∈ Write|Edit|Bash|MultiEdit (Task запрещён); object = путь к файлу или точная строка команды (Bash); ref = якорь спеки (D1..Dn), непустой;
• ```verified-context-json``` (план тоже требует ≥1 EXTRACTED);
• без мета-болтовни.
• Раздел ## Переговоры → ### Круг N — сюда контроллер пишет дословные доводы на возражения (Фикс 2 их подаёт судье/наставнику в следующих кругах).

3. Реализация — шаги по порядку, каждый Edit/Write/Bash совпадает с текущим шагом (op+object). Стена двигает указатель по одному. После последнего шага печать снимается сама → разговорный режим.

Частые ошибки (учись на чужих шишках)

• Ловушка устаревшего указателя. Повторный план байт-в-байт = тот же plan_id → старая позиция НЕ сбрасывается → застреваешь. Лечение: другой план (другое имя/шаги → новый plan_id) ИЛИ FLOOR-ESCAPE: plan-done (см. ниже). Удаление файлов НЕ помогает (позиция в runtime).
• Авторская запись. Свободно пишется только НОВЫЙ .md в specs//plans/. Существующий файл и код — только как шаг плана (либо escape, см. F-K).
• Чтение кода. В режиме реализации чтение вне путей текущего шага блокируется. Свободно — в разговорном режиме (нет печати).
• Bash-цепочки. ;/&&/||/| с мутирующей частью hard-блокируются. Только одиночные команды.
• Floor-safe планы. НЕ ставь floor-опасные Bash-шаги: node -e/curl/install/eval, rm -rf/ git push --force/migrate:fresh, PowerShell-записи, запись в ~/.claude/runtime/секреты. Пол их рубит, стена не двигает указатель → план встаёт колом. Файловые операции — через Write/Edit, не node -e.
• Десинк указателя (F-J, 16.06). Если PreToolUse-блокер (тупой судья навыков / normative §6) роняет действие exit-2, а enforce-supreme-gate (раньше в цепочке) УЖЕ сдвинул указатель — план застревает (указатель уехал, действие не прошло). Сброс: FLOOR-ESCAPE: plan-done ИЛИ новый план с другим именем. (Корень для brain: supreme-gate не должен двигать указатель, если со-хук блокнёт.)
• Наставник/судья async (~25-32с). Печать встаёт не мгновенно. Per-attempt таймаут 90с (HEAVY_LLM_TIMEOUT_MS). degraded («не дозвонился») → просто повтор.

⛔ Правка машинерии стены под стеной — НЕЛЬЗЯ (F-K, 16.06)

Файлы tools/enforce-*.mjs, judge-*, mentor-*, floor-*, escape-grant, plan-lock и т.п. — discipline-source: enforce-normative-content-rules §6 блокирует их правку под стеной как «ЗАКОН», и write-escape её НЕ снимает (в отличие от обычных файлов — у supreme-gate тот же escape работает). CARD-путь (sealedPlanCoversEdit под опечатанным планом) тоже ненадёжен. Правь такие файлы в ТЕРМИНАЛЕ (node-скрипт string-replace по точным якорям + бэкап + verify) и сразу коммить — несохранённые правки tracked-файлов теряются на git restore (инцидент 16.06).

Видимость вердикта (Фикс 1, 16.06) — лог антитуннеля больше НЕ нужен

Исход судьи/наставника на каждой судимой записи теперь виден контроллеру: хук enforce-verdict-surface (UserPromptSubmit) показывает строку ✅ GO — опечатано / 🚫 NO-GO: <дословно> / ⚠ не дозвонился (<причина>) / ⏭ пропуск (<причина>) в начале СЛЕДУЮЩЕГО хода. Требует регистрации хука в settings.json (UserPromptSubmit). Чтение ~/.claude/runtime по-прежнему закрыто — но вердикт спрашивать у владельца больше не надо.

Память кругов (Фикс 2, 16.06)

• Судья: круг 1 слеп (чистый суд продукт-против-цели); круг 2+ видит СВОИ прошлые претензии дословной цитатой + как контроллер их закрыл (из ## Переговоры) → не противоречит себе.
• Наставник: видит свои прошлые претензии + доводы контроллера, обязан переоценить ТЕКУЩИЙ план (снятое не повторять). (Полный «единый цикл» спека=план — в дизайн-доке для brain.)

Арбитраж — owner-seal (Фикс 3, 16.06)

На тупике (3-й круг подряд NO-GO) карточка даёт 3 кнопки:

• Держусь контроллера → план/спека опечатывается как есть (owner-seal, перевешивает NO-GO судьи И наставника);
• Согласен с замечанием → контроллер переделывает, счётчик сброшен;
• Своё решение → владелец вписывает указание → правка → печать.

«Держусь/Своё» владелец подписывает кликом FLOOR-ESCAPE: owner-seal:<hash> — путь печати (sealOnWiredGo) ставит frozenPlan/frozenArtifact несмотря на NO-GO (минуя и mentor freeze-gate).

Как узнать состояние (одна проба)

Безобидный не-readonly Bash, напр. node --version (echo режет router-gate как не-whitelist):

• блок «разговорный режим» → стена включена, чисто (нет печати);
• блок «ожидался шаг N: …» → ты в середине плана на шаге N (возможно, застрял — см. F-J);
• выполнилось → стена снята (или открыт escape).

Аварийный выход владельца (escape) — разовое подписанное разрешение

Владелец в ответе на AskUserQuestion пишет метку FLOOR-ESCAPE: <action> — каноническая строка (tools/escape-grant.mjs):

• Bash → bash:<норм. команда> · PowerShell → powershell:<норм. команда>
• Skill → skill:<имя в нижнем регистре> · Write/Edit → write:<путь, lowercase + прямые слэши>
• MCP → mcp:<имя>:<args-json>
• Завершить застрявший план → plan-done (резерв-метка, не от реального действия)
• Опечатать на арбитраже → owner-seal:<hash> (Фикс 3)

Среда (enforce-askuser-answer-parser, PostToolUse) пишет и подписывает пропуск ключом владельца (router-mentor-receipts); одноразовый, окно 5 минут, точное совпадение canonicalAction. Применяй escape СРАЗУ (дитёж → истечение окна).

Активация (обязательна в settings.json): PostToolUse AskUserQuestion → enforce-askuser-answer-parser (writer) + Edit|Write|MultiEdit|Bash|PowerShell → enforce-floor-escape-consume (one-shot). Без них клик уходит «в никуда».

Что escape чтит: стена М2 / пол М5 / судья М4 / гейт памяти (память/нормативка). НЕ чтит: router-gate (git — отдельный канал) и normative §6 для discipline-source (F-K — правь терминалом).

Коммит

• Через стену — частокол гейтов: enforce-router-gate (git-approval) + enforce-criterion-gate (по-критерийный GREEN) + enforce-verify-before-push (свежий полный прогон <30 мин). Доступно: git status/diff/log/add. НЕ доступно: restore/stash/reset/checkout.
• Чище — терминал владельца (минует ВСЕ гейты стены): $env:LEFTHOOK="0"; git commit … ; $env:LEFTHOOK=$null. Нужен полный LEFTHOOK=0 — частичный LEFTHOOK_EXCLUDE=cspell НЕ помогает (markdownlint --fix правит .md и рвёт git-stash). Сообщение paren-free, трейлер Co-Authored-By: Claude Opus 4.8.
• git auto-gc на Windows может зациклить Unlink … .idx failed. Try again? (y/n) (pack держит др. процесс — VSCode Git / gitea) → жми n; коммит уже создан. Профилактика: git config gc.auto 0.

Что под капотом

• Стена = enforce-supreme-gate (PreToolUse на всё); оркестратор = enforce-mentor-then-judge (PostToolUse Write) гонит наставника → судью по очереди.
• Фикс 1: enforce-verdict-surface + verdict-surface-store + verdict-outcome-line. Фикс 2: round-memory-store + блоки памяти в buildJudgePrompt/buildMentorVerdictPrompt. Фикс 3: seal-override + owner-seal в sealOnWiredGo/sealTurnProd.
• Живой шов: env ROUTER_MENTOR_SEAM_ENABLED=1, ROUTER_MENTOR_JUDGE_ENABLED=1, ROUTER_MENTOR_JUDGE_MODE=block + ключи наставника/судьи/роутера.

Минимальный пример церемонии

Задача: чистый модуль tools/<имя>.mjs через TDD. Спека: 5 секций {#D1..D5} + verified-context (якорь на cost-pricing.mjs) + ## Цель. План: skills-json ["test-driven-development"]; шаги тест-RED → vitest-RED → модуль → vitest-GREEN → … → регрессия. Регрессия (одиночная команда): npx vitest run --root app --config vitest.config.tools.mjs.

Судьи-машины

• Тупой судья навыков (enforce-domain-skill-discipline). Навыки из skills-json опломбированного плана обязаны быть РЕАЛЬНО вызваны (по журналу M1) до первого мутирующего шага, иначе блок. Объявленный навык стена пустит к вызову (isPlanDeclaredSkill).
• Критерий-судья (enforce-criterion-gate). На git commit/push через Claude требует по-критерийный GREEN (тест прошёл И мутация убита). Коммиты в своём терминале его минуют.

Правки памяти/CLAUDE.md под стеной: объяви claude-md-management в skills-json И реально вызови до записи — иначе гейт памяти/судья навыков заблокируют.