# Как починить согласование «спека/план → наставник → судья» — простыми словами

**Дата:** 2026-06-13. **Кодовая фраза:** «роутер-наставник».
**Решения владельца:** способ B + канал замечаний + эталонный поток + спека и план по одному
сценарию + счётчик на стэк (спека+план) + максимум тестов (протокол Р1/Р2/Р3 + ответы 06-13).
**Собирать только со снятой стеной (maintenance) + по TDD** — правим код самих хуков.

---

## 1. О чём речь {#about}

Чтобы что-то поправить в коде, я (контроллер) сначала пишу **спеку** (что и зачем меняем), потом
**план** (по шагам). Их одобряют двое:

- **Наставник** — мой старший коллега: смотрит вместе со мной, помогает довести до ума.
- **Судья** — независимый контролёр: выносит финальное «да/нет» и **ставит печать** (после печати
  можно выполнять).

**Один и тот же сценарий применяется ОДИНАКОВО к спеке и к плану.** Сначала так согласуется и
печатается спека, потом так же — план. Дальше для краткости пишу «план», но всё то же верно и для спеки.

## 2. Что сломано сейчас (на примере) {#problem}

Нажимаю «сохранить план». На самом деле (проверено по коду):

1. **Первым срабатывает СУДЬЯ** — ещё до наставника. Как будто экзаменатор ставит оценку раньше,
   чем преподаватель проверил черновик.
2. **Печать ставит наставник** (а не судья) — роли перепутаны.
3. Судью **дёргаю я сам** записью — хотя меня рядом с судьёй быть не должно.
4. **САМОЕ ВАЖНОЕ — я не вижу замечаний.** Сегодня: наставник дал разбор по 6 пунктам, судья —
   возражения. До меня **не дошло ничего** — узнал, **только когда ты открыл панель aitunnel**.
   Через нормальный канал тишина. Не вижу, что не так → **чинить нечего.** Вот корень всей муки.

## 3. Как должно быть (на примере) {#flow}

**Круг 1 — я и наставник (до 3 заходов):**

1. Я пишу план → видит **только наставник**. Судья пока не в курсе.
2. Наставник: «Шаг 2 трогает файл X, не написано зачем — допиши». Счётчик «круг 1» = **1**.
3. Я дописал → наставник снова: «теперь ок». Счётчик «круг 1» → **сброс**.
   - Не договорились за 3 захода → **карточка тебе** (обе позиции, реши).
4. Наставник доволен → **сам несёт план судье**. Судья видит план **впервые**.

**Круг 2 — наставник передал судье (до 3 заходов):**
5. Судья смотрит **свежим взглядом** (не зная, что наставник одобрил — чтобы судить честно):

- **«Да»** → судья **ставит печать**. План заморожен, мне приходит «GO, делай». ✅
- **«Нет»** → замечание **возвращается мне**. Счётчик «круг 2» = **1**. Переписываю → снова к
     наставнику (круг 1 заново) → одобрил → снова судье (круг 2 = 2)…
- 3 «нет» судьи подряд → **карточка тебе**.

1. Я **ни разу** не говорю с судьёй напрямую. **Печать ставит только судья.**

## 4. Главное правило: я ОБЯЗАН видеть замечания {#objection-channel}

Сердце починки. **Каждый раз, когда наставник или судья говорит «нет», полный текст замечания
должен прийти мне** — туда, где я его прочитаю.

- **Как должно:** судья сказал «нет» → у меня в чате появляется *«Судья: возражение — шаг 4
  трогает порог, не описано влияние; severity: heavy»*. Я знаю, что чинить, и переписываю.
- **Как НЕ должно (сейчас):** замечание уходит «в лог», который я читать не могу, или в никуда — и я вслепую.

**Первый шаг реализации — маленькая проверка (smoke):** убедиться, что выбранный канал (сообщение-
фидбэк от хука) реально доходит до меня. Если нет — придумаем другой. Без рабочего канала всё
остальное бессмысленно.

## 5. Каким способом собираем — «способ B» (аналогия) {#how}

Будильники на «сохранить план»:

- **Было:** два будильника, судья звонит **раньше** наставника. Бардак.
- **Будет (B):** два будильника по порядку — **сначала наставник, сразу за ним судья.** Судья
  смотрит, только если наставник одобрил. Наставник сказал «нет» → судья **молчит**.

**Защита от старой ловушки:** раньше ломалось из-за неверного порядка. Поэтому судья
**подстрахован**: нет одобрения наставника для этого плана → судья ничего не делает (не печатает,
не зависает). Даже если порядок собьётся — катастрофы не будет.

## 6. Что если по ходу реализации план надо поменять (re-plan) {#replan}

Бывает: судья поставил печать, я начал делать — и на шаге 3 выяснилось, что план неверный. Что
происходит (механизм в коде УЖЕ есть, `enforce-supreme-gate.mjs:198`):

1. Я пишу **новый план** (новым файлом). Стена разрешает это **даже в режиме реализации**.
2. Новый план проходит **то же согласование заново**: круг 1 (наставник) → круг 2 (судья) → печать.
3. Черновик нового плана **власти не даёт**, пока судья не запечатал.
4. Новый план запечатан → старая печать **заменяется**, выполняю **новый план с шага 1** (счётчик
   шагов сброшен, `resolveStepPtr` R-27).

В схеме B — так же: новый план просто заново запускает круг 1 → круг 2. (Минус: новый план = новый
файл, старый `.md` остаётся черновиком-сиротой — чистим потом.)

## 6.5. Чистое завершение плана — выход в разговорный {#clean-exit}

Сейчас (по коду) после выполнения плана контроллер ЗАСТРЕВАЕТ в режиме реализации: следующее
действие блокируется «план исчерпан» (`enforce-supreme-gate.mjs:217`), а выйти можно только удалив
`frozen-plan` вручную или новой сессией — стена сама печать не снимает.

**Чиним — добавляем чистое завершение:**

- последний шаг плана выполнен → стена САМА снимает печать (удаляет `frozen-plan`) → следующее
  действие уже в разговорном режиме;
- плюс владелец может **досрочно завершить** план («готово» / escape) → печать снимается.

Ручное удаление файла больше не нужно. (Read/Grep остаются свободны и так.)

## 7. Счётчики и карточка {#counters}

- **Счётчик — на стэк (спека+план) ОДНОЙ задачи**, а не на всю сессию. Если в одной сессии делаю
  две разные правки — у каждой свой счётчик. (Сейчас в коде счётчик per-session — **это правим**:
  привязываем к задаче через `task-id`, как уже сделано для журнала переговоров.)
- Счётчик круга 1 (наставник) и круга 2 (судья), оба до **3**, сброс на «да». Карточка
  переиспускается (`arbitration-card.mjs`): дословно обе позиции + 3 кнопки + «объясни подробнее».
  Решение владельца — через защищённый канал (escape/waiver), не «со слов» Claude.
- `round-control.mjs` не оживляем — он нигде не подключён; простого счётчика достаточно.

## 8. Что конкретно правим в коде {#components}

- **Хук наставника** (`enforce-mentor-on-plan-write.mjs`): убрать печать; оставить вердикт +
  счётчик; на «нет» — **отдавать мне полный текст замечания**; на «да» — записать «наставник
  одобрил этот план». **Расширить на спеку** (наставник смотрит и спеку, и план — один сценарий).
- **Хук судьи** (`enforce-judge-gate.mjs`): перевести с «звонит первым» на «после наставника»;
  судить/печатать **только если наставник одобрил**; на «да» — **самому ставить печать**; на «нет»
  — **отдавать мне полный текст замечания** + счётчик. Это и для спеки (gate1), и для плана (gate2).
- **Счётчики** (`mentor-nogo-counter.mjs` + `bumpJudgeNoGo`): привязать к **task-id** (стэк
  спека+план), а не к сессии.
- **Настройки** (`settings.json`): судья **после** наставника по порядку. (Твой шаг при возврате стены.)

## 9. Если что-то пойдёт не так {#failures}

- Нет одобрения наставника → судья молчит (не печатает, не зависает).
- ИИ наставника/судьи упал/таймаут → «не судил» → печати нет, мне приходит «не смог дозвониться»
  (а не тихий обман, что всё ок).
- Канал замечаний сбоит → я не молчу, а говорю «замечание есть, но не доставлено».

## 10. Как проверим — МАКСИМУМ тестов {#testing}

По TDD (сначала тест, потом код), тестов **как можно больше**. Покрываем:

- наставник раньше судьи; судья молчит без одобрения наставника (fail-safe);
- печать ставит судья, не наставник; судья судит, не видя мнения наставника (честно);
- **главное:** на «нет» текст замечания реально доходит до меня (отдельный тест на канал);
- спека и план идут по одному сценарию (тесты на оба);
- re-plan: новый план заново запускает круг 1 → круг 2, печать заменяется, шаги с начала;
- счётчики на стэк (спека+план), не на сессию; сброс/потолок 3 → карточка; карточка дословна;
- сбои: degraded-ИИ → нет печати + сообщение; битый счётчик → эскалация.
- Регрессия: весь набор зелёный (база ~3829).

## 11. Решения владельца (закрытые вопросы) {#decided}

- Спека и план — **один сценарий и принцип** (наставник→судья→печать судьи). ✅
- Тестов — **максимум**. ✅
- Счётчик — на **стэк (спека+план) одной задачи** (per-task), не на сессию. ✅
- Re-plan по ходу реализации — новый план через то же согласование (механизм уже в коде). ✅
- Чистое завершение: последний шаг выполнен (или владелец «готово») → стена сама снимает печать,
  возврат в разговорный (больше не ручное удаление файла). ✅

## Ссылки {#refs}

Прежняя спека `2026-06-12-router-mentor-two-level-negotiation-design-v2.md`. Протокол
`docs/superpowers/session-protocol-2026-06-13.md` (Р1/Р2/Р3). Код: `enforce-mentor-on-plan-write.mjs`,
`enforce-judge-gate.mjs`, `mentor-nogo-counter.mjs`, `arbitration-card.mjs`, `enforce-supreme-gate.mjs`
(re-plan :198), `settings.json`.
