@rt-tools/agent-kit 0.1.0 → 0.3.0

package/README.md

@@ -9,19 +9,21 @@
 соседнего они устаревают молча: правку в исходнике никто не переносит, а расхождение видно
 только по последствиям.
 
-Пакет разделяет текст на два слоя. **Закон** — что должно быть верно; он не знает ни путей, ни
-имён файлов и потому переносится целиком. **Правило** — чем это названо в конкретном дереве;
-оно остаётся в проекте, потому что только там имеет смысл.
+Пакет разделяет текст на три слоя. **Закон** — что должно быть верно; он не знает ни путей, ни
+имён файлов. **Правило** — каким приёмом это делается; приём переносится между репозиториями
+так же, как закон. **Паттерн** — готовый код приёма.
 
-Везёт пакет законы. Правила, паттерны и привязки к коду пишет проект.
+Все три везёт пакет. В проекте остаётся то, чего пакет знать не может: имена этого дерева. Они
+живут при каждом правиле отдельным файлом — `implementation.md`, — и пишет его проект.
 
 ## Как пользоваться
 
 ```bash
 pnpm add -D @rt-tools/agent-kit
 
-npx agent-kit init      # завести .claude/rt-kit.json и каталог надстроек
-npx agent-kit sync      # разложить законы в docs/constitution/
+npx agent-kit list      # что везёт пакет и что из этого взято здесь
+npx agent-kit init      # спросить законы галочками и завести .claude/rt-kit.json
+npx agent-kit sync      # разложить выбранное в docs/constitution/
 npx agent-kit doctor    # что разложено, что отстало, чего не хватает
 ```
 
@@ -34,6 +36,76 @@ npx agent-kit sync --check
 Команда ничего не пишет и отказывает, если разложенное отстало от пакета или его правили
 руками.
 
+## Что где лежит
+
+| Род | Куда ложится | Что это |
+| --- | --- | --- |
+| `laws` | `docs/constitution/` | что должно быть верно |
+| `rules` | `.claude/skills/<имя>/SKILL.md` | каким приёмом это делается |
+| `patterns` | `.claude/skills/<имя>/SKILL.md` | готовый код приёма |
+| `hooks` | `.claude/hooks/` | что не даёт нарушить |
+| `agents`, `commands`, `workflows` | `.claude/` | роли, слеш-команды и многошаговые прогоны |
+| `checks` | `tools/` | проверки, которые зовёт гейт |
+| `templates` | `.claude/rt-kit/templates/` | формы правила, паттерна, компаньона и карты гейта |
+
+Правило и паттерн ложатся одинаково — оба скилы; различает их `kind` во вступлении файла.
+
+## Правило и его компаньон
+
+Правило говорит приёмом и потому переносимо. Всё, что знает только это дерево — как что здесь
+называется, где лежит, чем проверяется, — живёт рядом с ним в `implementation.md`.
+
+Черновик компаньона `sync` кладёт **один раз**, при первой раскладке правила, и больше к нему
+не возвращается: своего текста у пакета там нет, а перекладывать значило бы стирать написанное
+проектом. Пока в черновике осталась метка `<!-- заполняет проект -->`, `sync --check` отказывает:
+правило без имён этого дерева — это закон, и агент по нему работать не может.
+
+## Хуки
+
+Закон и правило, которых никто не открывает, не действуют, поэтому пакет везёт и хуки, которые
+их зовут.
+
+**Гейт правил.** `skill-gate.sh` отбивает правку, пока не загружено правило под неё,
+`skill-loaded.sh` записывает загрузку, `skill-gate-rearm.sh` взводит гейт заново после сжатия
+контекста, `constitution-index.sh` печатает указатель законов на старте сессии.
+
+**Сторожевые хуки.** Главная ветка, поставка, документ в одном коммите с правкой, проверки
+перед пушем, линтер по следам правки, пишущие запросы к хранилищу, второй сервер разработки,
+якорь для спек, переизобретение готового, формат сообщения коммита, закреплённый профиль
+браузера.
+
+**Что при этом остаётся проекту.** Хуки везут механизм, но не знают ни путей, ни команд, ни
+инвентаря — это дерево знает только оно само:
+
+| Файл проекта | Что в нём | Кто читает |
+| --- | --- | --- |
+| `.claude/rt-kit/gate-map.sh` | что правится — какое правило | гейт правил |
+| `.claude/rt-kit/project.sh` | команды, стенды, пары «правка — документ», форма имени ветки | сторожевые хуки |
+| `.claude/rt-kit/browser-device-id` | закреплённый профиль браузера этой машины | браузерные гарды |
+
+Формы первых двух лежат в шаблонах. Нет файла — хук пропускает: пустой гард лучше гарда,
+отбивающего наугад, и это же правило действует на каждую отдельную функцию профиля.
+
+## Выбор законов
+
+Половина законов пакета про то, чего в конкретном приложении нет вовсе: у сервиса без админки
+нет ни её списков, ни её навигации. Поэтому `init` спрашивает, какие законы брать, а не кладёт
+все пятнадцать молча.
+
+```bash
+npx agent-kit init                       # спросить галочками
+npx agent-kit init --all                 # взять все, ни о чём не спрашивая
+npx agent-kit init --laws access,delivery,verifiability
+```
+
+Без терминала — в CI, в конвейере, в чужом скрипте — спрашивать некого, и `init` без флага
+отказывает вместо того, чтобы решить за проект: «взять всё» тоже решение, и принимать его
+молча он не вправе.
+
+Выбор уезжает в конфиг ключом `only` и оттуда же правится потом: `init` заведённый конфиг не
+трогает. Имена законов — из `agent-kit list`, там же видно, что взято, что не выбрано и что
+пропущено.
+
 ## Конфиг
 
 `.claude/rt-kit.json` коммитится: раскладка обязана повторяться на чужой машине без вопросов.
@@ -42,6 +114,7 @@ npx agent-kit sync --check
 {
     "vars": { "mainBranch": "main" },
     "layout": { "laws": "docs/constitution" },
+    "only": ["laws/access.md", "laws/delivery.md"],
     "skip": ["laws/admin-lists.md"]
 }
 ```
@@ -52,7 +125,11 @@ npx agent-kit sync --check
   посреди правила агент прочтёт как имя.
 - **`layout`** — куда класть каждый род ресурса. Умолчания менять без нужды не стоит: правила
   ссылаются на законы теми же путями.
-- **`skip`** — ресурсы, от которых проект отказался, идентификаторами вида `laws/<закон>.md`.
+- **`only`** — что проект выбрал, идентификаторами вида `laws/<закон>.md`. Пусто — берётся всё.
+  Ограничивает только те роды, которые сам называет: перечислив законы, проект говорит о
+  законах, а не обо всём, что пакет везёт, — шаблоны при нём остаются.
+- **`skip`** — ресурсы, от которых проект отказался, теми же идентификаторами. Вычитает из
+  выбранного, поэтому отказ от одного закона не требует переписывать список из пятнадцати.
 
 ## Надстройки
 
@@ -81,5 +158,7 @@ npx agent-kit sync --check
 
 ## Чего в пакете пока нет
 
-Хуков, проверок, агентов и пресетов карты гейта он не везёт — только законы и шаблоны правила и
-паттерна. Генератора черновиков правил по закону тоже нет.
+Проверок, ролей, слеш-команд и воркфлоу он не везёт: роды заведены, ресурсов в них ещё нет.
+Пресета карты хуков для настроек агента тоже нет — раскладка кладёт файлы, а карта хуков живёт
+разделом в чужом JSON, и сливать его она пока не умеет. Генератора черновиков правил по закону
+нет.

package/assets/hooks/browser-device-id.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Общий помощник: печатает идентификатор закреплённого профиля браузера.
+#
+# Идентификатор локален для машины и в пакет не едет вовсе. Он берётся из переменной окружения,
+# а если её нет — из файла рядом с конфигом раскладки. Ни там ни там ничего нет — помощник
+# молчит, и все браузерные гарды пропускают: гард, который не может назвать нужный профиль,
+# ничего не предлагает взамен, и слепой отказ только заводил бы работу в тупик.
+#
+# Файл с идентификатором в репозиторий не коммитится: у каждой машины он свой.
+
+if [ -n "${RT_BROWSER_DEVICE_ID:-}" ]; then
+    printf '%s\n' "$RT_BROWSER_DEVICE_ID"
+    exit 0
+fi
+
+file="${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/browser-device-id"
+[ -f "$file" ] || exit 0
+
+tr -d '[:space:]' <"$file"
+printf '\n'

package/assets/hooks/browser-guard-device-id.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Гард выбора браузера. PreToolUse на выборе браузера расширением.
+#
+# Отклоняет любой профиль, кроме закреплённого: чужой стоит лишнего круга и приводит в браузер,
+# где сессий этого проекта нет вовсе.
+#
+# На совпадении ставит метку сессии. Гард свежести читает ВОЗРАСТ этой метки — она и делает
+# законной всю дальнейшую работу с браузером.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: помощник не назвал профиль — пропуск.
+
+input="$(cat 2>/dev/null)"
+
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+[ -z "$device_id" ] && exit 0
+
+requested="$(printf '%s' "$input" | jq -r '.tool_input.deviceId // empty' 2>/dev/null)"
+
+if [ "$requested" = "$device_id" ]; then
+    sid="$(printf '%s' "$input" | jq -r '.session_id // "nosession"' 2>/dev/null)"
+    marker_dir="${TMPDIR:-/tmp}/claude-browser-guard"
+    mkdir -p "$marker_dir" 2>/dev/null && : >"$marker_dir/${sid}" 2>/dev/null
+    exit 0
+fi
+
+echo "Профиль «${requested}» не тот, что закреплён за проектом. Бери ${device_id} — единственный профиль, где сделан вход." >&2
+exit 2

package/assets/hooks/browser-guard-no-listing.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Гард перечисления и переключения браузеров. PreToolUse.
+#
+# Сессии проекта живут в одном закреплённом профиле. Перечисление и переключение отдают общие
+# неустойчивые имена, которые не опознают ничего, а выбор из них приводит в профиль без входа —
+# поэтому единственный поддержанный путь — выбор по закреплённому идентификатору.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: помощник не назвал профиль — пропуск. Гард, который не может назвать
+# нужный профиль, ничего не предлагает взамен, и слепой отказ только заводил бы работу в тупик.
+
+cat >/dev/null 2>&1
+
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+[ -z "$device_id" ] && exit 0
+
+echo "Не перечисляй и не переключай браузеры. Вызови выбор браузера с профилем ${device_id} — единственным, где сделан вход." >&2
+exit 2

package/assets/hooks/browser-guard-no-other-drivers.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Гард обходных путей к браузеру. PreToolUse.
+#
+# Закрепление профиля чего-то стоит только тогда, когда дверь одна. Здесь перечислены двери,
+# которые обходят её целиком и закреплённый профиль не спрашивают вовсе: второй драйвер,
+# третий драйвер, открытие ссылки средствами системы, управление браузером через сценарий
+# автоматизации, отдельная утилита и прямой запуск бинарника.
+#
+# Написание сквозных спек при этом остаётся законным: прогон спеки не выдаёт агенту
+# интерактивный браузер. Отбиваются только глаголы вождения.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: помощник не назвал профиль — пропуск.
+
+input="$(cat 2>/dev/null)"
+
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+[ -z "$device_id" ] && exit 0
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+
+deny() {
+    echo "$1 Води браузер закреплённым расширением: выбери профиль ${device_id} и работай его инструментами." >&2
+    exit 2
+}
+
+case "$tool" in
+    mcp__playwright__*)
+        deny "Второй драйвер браузера в этом проекте не используется — в его профиле вход не сделан." ;;
+    mcp__chrome-devtools__*)
+        deny "Третий драйвер браузера в этом проекте не используется — закреплённый профиль он не спрашивает." ;;
+esac
+
+# Терминал среды разработки запускает те же драйверы той же командной строкой.
+case "$tool" in
+    Bash | mcp__webstorm__execute_terminal_command | mcp__webstorm__execute_tool) ;;
+    *) exit 0 ;;
+esac
+
+cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)"
+[ -z "$cmd" ] && exit 0
+
+if [ "$tool" = "mcp__webstorm__execute_tool" ] && command -v perl >/dev/null 2>&1; then
+    inner="$(printf '%s' "$cmd" | perl -0ne '
+        if (/--command(?:=|\s+)(?:"((?:[^"\\]|\\.)*)"|\x27([^\x27]*)\x27|(.+))/s) {
+            print defined $1 ? $1 : (defined $2 ? $2 : $3);
+        }
+    ' 2>/dev/null)"
+    [ -n "$inner" ] && cmd="$inner"
+fi
+
+# Прогон сквозных спек — законный путь, и он не отбивается никогда.
+case "$cmd" in
+    *playwright\ open*|*playwright\ codegen*|*playwright\ screenshot*|*playwright\ cr*)
+        deny "Вождение браузера из командной строки драйвера обходит закреплённый профиль." ;;
+esac
+
+case "$cmd" in
+    *open\ http*|*open\ -a\ *Chrome*|*open\ -a\ *chrome*)
+        deny "Открытие адреса средствами системы поднимает браузер по умолчанию, а не закреплённый профиль." ;;
+    *osascript*Chrome*|*osascript*chrome*)
+        deny "Управление браузером сценарием автоматизации обходит закреплённый профиль." ;;
+    *chrome-cli*)
+        deny "Эта утилита обходит закреплённый профиль." ;;
+esac
+
+# Бинарник браузера — и только в позиции команды.
+#
+# Голый образец с именем движка здесь непригоден: он совпадает и со значением флага, которым
+# помечают движок в прогоне сквозных спек, — такой образец отбил бы сам прогон в день, когда
+# появился. Поэтому якорь на границе команды и требование похожего на исполняемый файл слова,
+# а не значения флага.
+printf '%s' "$cmd" | grep -qE '(^|[;&|(]|[[:space:]]&&|[[:space:]]\|\|)[[:space:]]*(/[^[:space:]]*/)?(google-chrome|chromium)([[:space:]]|$)' \
+    && deny "Прямой запуск бинарника браузера обходит закреплённый профиль."
+
+printf '%s' "$cmd" | grep -qF 'Google Chrome.app/Contents/MacOS' \
+    && deny "Прямой запуск бинарника браузера обходит закреплённый профиль."
+
+exit 0

package/assets/hooks/browser-guard-require-select.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Гард свежести выбора браузера. PreToolUse на всех остальных вызовах расширения.
+#
+# ЗАЧЕМ ОН ЕСТЬ — отказ, из которого он вырос: расширение действует на тот браузер, который
+# считает активным сейчас, и этот выбор ПЛЫВЁТ. Выбор, сделанный в начале сессии, не держится:
+# после долгого перерыва на работу без браузера следующий же вызов открыл вкладку в другом
+# профиле — молча. Гард на самом выборе такого не ловит: в этот момент выбор никто не вызывает,
+# а тот, что был сделан раньше, был верным.
+#
+# Поэтому гард про СВЕЖЕСТЬ, а не про «выбирали ли вообще»:
+#   - гард выбора ставит метку на каждом принятом выборе;
+#   - каждый прошедший здесь вызов метку обновляет, поэтому непрерывная работа идёт свободно;
+#   - как только метка старше окна, следующий вызов отбивается и требует выбрать заново.
+#     Перерыв — это ровно то, когда выбор уплывает, поэтому перерыв гард и взводит.
+#
+# Выбор — один дешёвый повторяемый вызов, и повторить его стоит несравнимо меньше, чем попасть
+# не в тот браузер.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: помощник не назвал профиль — пропуск.
+
+input="$(cat 2>/dev/null)"
+
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+[ -z "$device_id" ] && exit 0
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+# У перечисления, переключения и самого выбора свои гарды.
+case "$tool" in
+    *list_connected_browsers|*switch_browser|*select_browser) exit 0 ;;
+esac
+
+ttl=300
+
+sid="$(printf '%s' "$input" | jq -r '.session_id // "nosession"' 2>/dev/null)"
+marker="${TMPDIR:-/tmp}/claude-browser-guard/${sid}"
+
+if [ ! -f "$marker" ]; then
+    echo "В этой сессии браузер не выбран. Вызови выбор браузера с профилем ${device_id} до любого другого вызова." >&2
+    exit 2
+fi
+
+now="$(date +%s)"
+stamped="$(stat -f %m "$marker" 2>/dev/null || stat -c %Y "$marker" 2>/dev/null || echo 0)"
+age=$(( now - stamped ))
+
+if [ "$age" -gt "$ttl" ]; then
+    rm -f "$marker" 2>/dev/null
+    echo "Последний выбор браузера был ${age} с назад (предел ${ttl} с) — на таких перерывах активный браузер расширения уплывает, и это может быть уже не закреплённый профиль. Вызови выбор с профилем ${device_id} заново и повтори." >&2
+    exit 2
+fi
+
+: >"$marker" 2>/dev/null
+exit 0

package/assets/hooks/commit-msg.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Проверка сообщения коммита. Хук самого гита, а не агента.
+#
+# Версионируемый шаблон: рабочая копия хуков гита не версионируется, поэтому файл ставится в
+# неё отдельно — скриптом подготовки при установке зависимостей. Переустановка руками, если
+# подготовка почему-то не отработала:
+#   cp {{hooksDir}}/commit-msg.sh .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+#
+# Намеренно НЕ через обёртку, подменяющую путь хуков: подмена уводит гит в свой каталог и рвёт
+# остальные хуки, уже лежащие в рабочей копии. Родной путь оставляет их нетронутыми.
+#
+# Разобранный по типу и области заголовок читается списком, а свободный текст — только
+# целиком; поэтому формат и проверяется здесь, на месте, а не глазами на разборе.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: проверяльщика нет (свежий клон без установленных зависимостей) —
+# пропуск. Формат тогда не проверяется, и это лучше, чем заклинивший коммит.
+
+msg_file="$1"
+[ -z "$msg_file" ] && exit 0
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+cd "$repo_root" 2>/dev/null || exit 0
+
+[ -x node_modules/.bin/commitlint ] || exit 0
+
+node_modules/.bin/commitlint --edit "$msg_file"

package/assets/hooks/constitution-index.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Вход в слой законов. SessionStart.
+#
+# Файл закона сам по себе не приносит в контекст ничего — его читают, только когда за ним
+# пошли. Хук печатает указатель (имя файла и его заголовок) один раз за сессию: слой известен,
+# что существует, и открывается, когда решение его задевает.
+#
+# Указатель ЧИТАЕТСЯ ИЗ КАТАЛОГА, а не выписан руками: выписанный разошёлся бы с тем, что
+# разложено на самом деле, и сказать об этом было бы нечем.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: любая ошибка начинает сессию без добавленного контекста (exit 0).
+# Сломанный вход не имеет права остановить сессию.
+
+dir="${CLAUDE_PROJECT_DIR:-.}/{{lawsDir}}"
+[ -d "$dir" ] || exit 0
+
+index=""
+for law in "$dir"/*.md; do
+    [ -f "$law" ] || continue
+    title="$(grep -m1 '^# ' "$law" 2>/dev/null | sed 's/^# //')"
+    [ -z "$title" ] && continue
+    index="${index}  {{lawsDir}}/$(basename "$law") — ${title}"$'\n'
+done
+[ -z "$index" ] && exit 0
+
+read -r -d '' context <<EOF
+ЗАКОНЫ ПРОЕКТА (слой @rt-tools/agent-kit, разложен в {{lawsDir}}/).
+
+Закон говорит, ЧТО должно быть верно, и не знает ни путей, ни имён файлов. Правило — каким
+приёмом это делается — живёт в {{rulesDir}}/, а имена этого дерева при нём — в
+implementation.md рядом. Закон не отменяет правила и не заменяется им: перед решением, которое
+закон задевает, читается закон целиком, правило — как обычно.
+
+${index}
+Разложенные файлы правятся не руками, а надстройкой в .claude/rt-kit/overrides/<ресурс>:
+правка на месте теряется на следующем \`agent-kit sync\`, и он на неё отказывает. Сверить
+разложенное с пакетом: \`agent-kit sync --check\`.
+EOF
+
+jq -n --arg c "$context" '{hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:$c}}' 2>/dev/null || exit 0
+
+exit 0

package/assets/hooks/dev-server-guard.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Гард второго сервера разработки. PreToolUse.
+#
+# Приложения уже подняты владельцем, и всякая проверка через браузер идёт туда. Второй
+# экземпляр занимает лишний порт, отдаёт другую сборку и уводит разбор в сторону: расхождение
+# между двумя серверами читается как дефект правки. Вдобавок сборка, запущенная между делом,
+# гасит уже поднятый сервер молча.
+#
+# Отбивается всё, что ПОДНИМАЕТ сервер. Сборка, тесты, линтеры, запросы к поднятым портам и
+# осмотр слушателей проходят.
+#
+# Где именно подняты приложения, знает профиль проекта: {{projectProfile}}, переменная
+# RT_STANDS. Нет профиля — текст отказа остаётся общим, сам гард работает.
+
+input="$(cat 2>/dev/null)"
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+case "$tool" in
+    Bash | mcp__webstorm__execute_terminal_command | mcp__webstorm__execute_tool) ;;
+    # Готовая конфигурация запуска командной строки не показывает — видно только её имя.
+    # Отсюда правило: «serve», «dev» и «start» в имени отклоняются, потому что проверить, что
+    # за ними стоит, гард не может, а второй сервер стоит дороже лишнего отказа.
+    mcp__webstorm__execute_run_configuration)
+        name="$(printf '%s' "$input" | jq -r '.tool_input.configurationName // empty' 2>/dev/null)"
+        # Второй режим инструмента — временная конфигурация из пары «файл и строка»: имени у
+        # неё нет вовсе, и проверка по имени её пропускала. Именно так поднимается скрипт из
+        # манифеста пакета.
+        if [ -z "$name" ]; then
+            file="$(printf '%s' "$input" | jq -r '.tool_input.filePath // empty' 2>/dev/null)"
+            case "$file" in
+                */package.json|package.json)
+                    echo "Запуск скрипта прямо из манифеста: гард видит только файл и строку, а не сам скрипт, поэтому не может отличить подъём сервера от сборки. Приложения уже подняты владельцем — если нужна сборка или тест, запусти их командой в терминале." >&2
+                    exit 2 ;;
+            esac
+            exit 0
+        fi
+        # Слово «start» без границы ловило и «restart», который сервер не поднимает.
+        case "$(printf '%s' "$name" | tr '[:upper:]' '[:lower:]')" in
+            *serve*|*dev*|start*|*\ start*|*:start*)
+                echo "Конфигурация «${name}» похожа на подъём сервера разработки, а приложения уже подняты владельцем — проверяй их. Если конфигурация делает другое, запусти это командой: по имени гард содержимого не видит." >&2
+                exit 2 ;;
+        esac
+        exit 0 ;;
+    *) exit 0 ;;
+esac
+
+cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)"
+[ -z "$cmd" ] && exit 0
+
+# Универсальный исполнитель среды передаёт настоящую команду вложенной строкой. Разбирать надо
+# её, а не обёртку: иначе имя раннера стоит сразу за кавычкой и ни одно правило до него не
+# дотягивается.
+if [ "$tool" = "mcp__webstorm__execute_tool" ] && command -v perl >/dev/null 2>&1; then
+    inner="$(printf '%s' "$cmd" | perl -0ne '
+        if (/--command(?:=|\s+)(?:"((?:[^"\\]|\\.)*)"|\x27([^\x27]*)\x27|(.+))/s) {
+            print defined $1 ? $1 : (defined $2 ? $2 : $3);
+        }
+    ' 2>/dev/null)"
+    [ -n "$inner" ] && cmd="$inner"
+fi
+
+# Гит ничего не слушает на портах, а тексты сообщений и веток свободно содержат слова вроде
+# «serve» — без этой ветки гард ловит собственный коммит про себя же.
+case "$cmd" in
+    git\ *|*/git\ *)
+        printf '%s' "$cmd" | grep -qE '(^|[[:space:]])git[[:space:]]+daemon([[:space:]]|$)' || exit 0 ;;
+esac
+
+stands=""
+profile="${CLAUDE_PROJECT_DIR:-.}/{{projectProfile}}"
+if [ -f "$profile" ]; then
+    # shellcheck disable=SC1090
+    . "$profile" 2>/dev/null && stands="${RT_STANDS:-}"
+fi
+
+deny() {
+    if [ -n "$stands" ]; then
+        echo "$1 Приложения уже подняты владельцем: ${stands} — проверяй их. Свой экземпляр не поднимай; если порт не отвечает, скажи владельцу, а не запускай второй." >&2
+    else
+        echo "$1 Приложения уже подняты владельцем — проверяй их. Свой экземпляр не поднимай; если порт не отвечает, скажи владельцу, а не запускай второй." >&2
+    fi
+    exit 2
+}
+
+# Раннеры перечисляются явно. Группа «любое слово перед именем» отклоняла даже заметку о том,
+# что сервер поднимает владелец.
+RUNNER='((npx|pnpm|yarn|bun|npm)([[:space:]]+(exec|run|dlx))?[[:space:]]+)?'
+
+# Начало вызова: начало строки или разделитель команд. Кавычку в границы вносить нельзя — тогда
+# поиск по тексту и снятие процесса по шаблону читаются как запуск.
+BOUND='(^|[;&|(]|&&|\|\|)[[:space:]]*'
+
+printf '%s' "$cmd" | grep -qE "${BOUND}${RUNNER}(nx|ng)[[:space:]]+(run[[:space:]]+[^[:space:]]*:)?(serve|dev)" \
+    && deny "Запуск ещё одного сервера разработки через каркас."
+
+# Требование пробела сразу после имени рвало совпадение на двоеточии: скрипты вида «serve:site»
+# гард пропускал — то есть ровно те команды, ради которых написан.
+printf '%s' "$cmd" | grep -qE "${BOUND}(npm|pnpm|yarn|bun)([[:space:]]+run)?[[:space:]]+(dev|start|serve)([:._-][A-Za-z0-9:._-]*)?([[:space:]]|\$)" \
+    && deny "Запуск ещё одного сервера разработки через пакетный раннер."
+
+# Подкоманда обязательна: пока она была необязательной, под правило попадало голое слово
+# сборщика — то есть любой однострочник, где оно встречается внутри текста.
+printf '%s' "$cmd" | grep -qE "${BOUND}${RUNNER}vite([[:space:]]+(dev|serve|preview))?[[:space:]]*(\$|[;&|\"'])" \
+    && deny "Запуск ещё одного сервера разработки."
+printf '%s' "$cmd" | grep -qE "${BOUND}${RUNNER}(next|astro|nuxt)[[:space:]]+(dev|start|preview)([[:space:]]|\$)" \
+    && deny "Запуск ещё одного сервера разработки."
+
+# Статика поверх сборки — тот же второй экземпляр. Каждое имя под общим якорем начала команды:
+# без него перечисление пакетов и поиск по документам читались как запуск.
+printf '%s' "$cmd" | grep -qE "${BOUND}(python3?[[:space:]]+-m[[:space:]]+http\.server|${RUNNER}(http-server|live-server|serve)([[:space:]]|\$))" \
+    && deny "Подъём статического сервера поверх сборки — тот же второй экземпляр."
+
+exit 0

package/assets/hooks/docs-guard.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Гард пары «правка и её документ». PreToolUse.
+#
+# Расхождение кода с текстом беззвучно. Ни линтер, ни сборка, ни тесты не читают правила,
+# спеки и README, поэтому текст, описывающий прежнее устройство, живёт дальше и выглядит
+# действующей справкой — тем убедительнее, чем он старше. Ловится это только чтением, и ловит
+# обычно владелец, а не проверка.
+#
+# Гард требует ровно тех пар, где связь механическая и спорить не о чем. Какие это пары, знает
+# профиль проекта: {{projectProfile}}, функция `rt_docs_pair_for <файл>` — печатает образец
+# пути, который обязан ехать тем же коммитом, или молчит.
+#
+# Отдельно — законы. Совпал ли код с законом, машина не знает, поэтому правка самого закона не
+# отклоняется, а выносится вопросом владельцу: закон описывает договорённость о продукте, и
+# менять её молча гард не даёт.
+#
+# Обход — строка `Docs-skip: <причина>` в теле коммита. Причина остаётся в истории и видна при
+# разборе ветки; пустая не принимается.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: не репозиторий, нет разборщика, битый ввод, пустой список файлов —
+# пропуск.
+
+input="$(cat 2>/dev/null)"
+[ -z "$input" ] && exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+
+decide() {
+    jq -n --arg d "$1" --arg r "$2" \
+        '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:$d,permissionDecisionReason:$r}}' 2>/dev/null \
+        || printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Документ едет тем же коммитом."}}\n'
+    exit 0
+}
+
+# ── Правка закона спрашивает владельца ────────────────────────────────────────
+case "$tool" in
+    Edit | Write | MultiEdit | mcp__webstorm__create_new_file)
+        target="$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.pathInProject // empty' 2>/dev/null)"
+        case "$target" in
+            */{{lawsDir}}/*.md | {{lawsDir}}/*.md)
+                decide ask "Правка закона: \`${target##*/}\`. Закон описывает договорённость о продукте, а не устройство кода, — назови владельцу, что и почему меняешь, и дождись ответа. Если правка уже согласована, подтверди вызов." ;;
+        esac
+        exit 0 ;;
+esac
+
+# ── Коммит: пара обязана ехать тем же коммитом ───────────────────────────────
+case "$tool" in
+    Bash | mcp__webstorm__execute_terminal_command | mcp__webstorm__execute_tool) ;;
+    *) exit 0 ;;
+esac
+
+cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)"
+case "$cmd" in
+    *git\ commit*) ;;
+    *) exit 0 ;;
+esac
+
+# Обход с причиной. Пустая причина не принимается: «Docs-skip:» без слов означает только то,
+# что строку дописали, чтобы пройти гард.
+if printf '%s' "$cmd" | grep -qE 'Docs-skip:[[:space:]]*[^[:space:]]'; then
+    exit 0
+fi
+
+workdir="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null)"
+[ -z "$workdir" ] && workdir="${CLAUDE_PROJECT_DIR:-.}"
+cd "$workdir" 2>/dev/null || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+profile="${CLAUDE_PROJECT_DIR:-.}/{{projectProfile}}"
+[ -f "$profile" ] || exit 0
+# shellcheck disable=SC1090
+. "$profile" 2>/dev/null || exit 0
+command -v rt_docs_pair_for >/dev/null 2>&1 || exit 0
+
+staged="$(git diff --cached --name-only 2>/dev/null)"
+[ -z "$staged" ] && exit 0
+
+missing=""
+while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    want="$(rt_docs_pair_for "$file" 2>/dev/null)"
+    [ -z "$want" ] && continue
+    # Пара считается приехавшей, если хоть один подготовленный файл подходит под образец.
+    printf '%s\n' "$staged" | grep -qE "$want" && continue
+    missing="${missing}  ${file} — ждёт документ: ${want}"$'\n'
+done <<EOF
+$staged
+EOF
+
+[ -z "$missing" ] && exit 0
+
+decide deny "Документ едет в том же коммите, что и правка, которую он описывает. Не хватает пар:
+
+${missing}
+Если документа здесь правда не нужно — строка «Docs-skip: <причина>» в теле коммита; пустая причина не принимается."