@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/defaults/project.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# Профиль дерева: чем здесь проверяется правка и что считается переизобретением.
+#
+# Умолчание пакета. Всё, что общего у деревьев этой мастерской, живёт здесь: запускатель Nx,
+# линтер кода, линтер стилей, набор образцов переизобретения. Своё дерево дописывает
+# надстройкой — `.claude/rt-kit/project.sh`: она грузится второй, объявляет ту же функцию
+# заново и вправе позвать отсюда её же с суффиксом `_default`.
+#
+# Каждая функция вправе промолчать. Молчание значит «правила на это нет», и хук пропускает.
+
+# Запускатель пакетов — по локфайлу, а не по договорённости: деревья с pnpm и с npm лежат в
+# одной мастерской, и зашитый здесь `npm` в первом же из них печатал бы команду, которой нет.
+rt_runner() {
+    root="${CLAUDE_PROJECT_DIR:-.}"
+    if [ -f "$root/pnpm-lock.yaml" ]; then
+        printf '%s' 'pnpm exec'
+    elif [ -f "$root/yarn.lock" ]; then
+        printf '%s' 'yarn'
+    else
+        printf '%s' 'npx'
+    fi
+}
+
+# Где подняты приложения. Идёт в текст отказа, когда кто-то поднимает второй экземпляр.
+# Порты у каждого дерева свои, поэтому умолчание молчит: назвать чужой порт хуже, чем не назвать.
+RT_STANDS="${RT_STANDS:-}"
+
+# Команды, которые обязаны пройти перед пушем. По одной на строку; первая упавшая отбивает пуш.
+# Линтер стилей отдельной строкой: линтер кода файлы стилей не читает вовсе.
+#
+# Первый параметр — база: ветка, относительно которой считается вклад. Пустая означает, что
+# удалённого нет, и тогда гоняется всё: набор строже нужного безопасен, набор уже нужного — нет.
+rt_push_checks_default() {
+    runner="$(rt_runner)"
+    if [ -n "$1" ]; then
+        printf '%s\n' "$runner nx affected -t lint test --base=$1"
+    else
+        printf '%s\n' "$runner nx run-many -t lint test --all"
+    fi
+    [ -f "${CLAUDE_PROJECT_DIR:-.}/stylelint.config.js" ] && printf '%s\n' "$runner stylelint \"**/*.scss\" --max-warnings 0"
+
+    return 0
+}
+
+# Какой документ обязан ехать тем же коммитом, что и этот файл. Печатает образец пути или молчит.
+rt_docs_pair_for_default() {
+    case "$1" in
+        # Тест — не описание кода: он его проверяет.
+        *.spec.ts) return 0 ;;
+        # Контракт правится вместе со спеком домена: разошедшись, они врут оба.
+        *.proto) printf '%s' 'docs/specs/.*/spec\.md' ;;
+        # Правило и его спутник здесь не называются: их пару держит сам гард, и держит точнее —
+        # он сверяет раздел с утверждениями, а не факт правки файла.
+        # Хук и набор его сценариев: гард разбирает текст команд, и уточнение шаблона обычно
+        # смещает границу, а не сужает.
+        .claude/hooks/*.sh) printf '%s' '.claude/hooks/tests/.*' ;;
+    esac
+}
+
+# Чем линтуется этот файл сразу после правки. Печатает команду или молчит.
+#
+# Путь подставляется здесь, а не оставляется позиционным параметром: хук исполняет напечатанное
+# вычислением строки, и `$1` в нём разрешился бы в параметр самого хука, то есть в пустоту.
+rt_lint_for_default() {
+    runner="$(rt_runner)"
+    case "$1" in
+        *.scss) printf '%s stylelint --max-warnings 0 "%s"' "$runner" "$1" ;;
+        *.ts | *.html) printf '%s eslint "%s"' "$runner" "$1" ;;
+    esac
+}
+
+# Каталог папок задач. Пусто — ведения работы папкой в дереве нет, и гард замысла молчит.
+RT_TASKS_DIR="${RT_TASKS_DIR:-docs/tasks}"
+
+# Каталог записей о законченных работах. Туда переносят то, что объясняет решения закрытой
+# задачи. Гард поставки требует, чтобы ветка, удалившая папку задачи, что-то сюда добавила:
+# удалить проще, чем разобрать, а слова владельца больше нигде не записаны.
+RT_ARCHIVE_DIR="${RT_ARCHIVE_DIR:-docs/archive}"
+
+# Где лежат тексты, которые читают до вопроса владельцу: законы, правила и договорённости о
+# продукте. По ним гард разговора судит, читалось ли за ход хоть что-то, и их же называет в
+# подсказке. Пусто у законов и правил разом — дерево этого требования не получает: читать
+# нечего.
+RT_LAWS_DIR="${RT_LAWS_DIR:-docs/constitution}"
+RT_RULES_DIR="${RT_RULES_DIR:-.claude/skills}"
+RT_SPECS_DIR="${RT_SPECS_DIR:-docs/specs}"
+
+# Главная ветка. Гарду она нужна, чтобы найти общего предка и понять, что ветка сделала с
+# папкой задачи и с архивом. Если общего предка нет, сравнивать не с чем — проверка молчит.
+RT_MAIN_BRANCH="${RT_MAIN_BRANCH:-main}"
+
+# Тело PR по его номеру. Обход требования пишут в PR, а в команде слияния его нет — там только
+# номер. Пустой ответ значит «спросить не у кого»: тогда обход ищется только в тексте команды.
+rt_report_body_default() {
+    command -v gh >/dev/null 2>&1 || return 1
+    gh pr view "$1" --json body -q '.body' 2>/dev/null
+}
+
+# Код приложения ли это. Успех — да, и тогда правка требует замысла на диске.
+#
+# Признак — путь, а не оценка на глаз: оценку назначает тот, кому она мешает, и порог плывёт.
+# Правила, тексты, обвязка и зависимости под требование не попадают — иначе разбор задачи
+# нельзя было бы вести до заведения ветки.
+rt_is_app_code_default() {
+    case "$1" in
+        */apps/* | */libs/* | */projects/*) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+# Имя ветки, с которой разрешено открывать заявку на слияние: в имени стоит номер задачи.
+# Приставка — либо род правки, либо метка очереди работ: обе формы носят номер, а он и нужен.
+#
+# Хвост после номера — строчными и через дефис. Имя ветки читают глазами в списке и набирают
+# руками, а регистр в нём различает две ветки, отличающиеся только им, — и та, что нужна, при
+# переключении находится не с первого раза.
+rt_task_branch_ok_default() {
+    printf '%s' "$1" \
+        | grep -qE '^([A-Z]+-)?[0-9]+-[a-z0-9][a-z0-9-]*$|^(feat|fix|refactor|docs|chore|style|perf|test|build|ci)/[0-9]+-[a-z0-9][a-z0-9-]*$'
+}
+
+# Адрес боевого хранилища: образец, по которому его узнают в командной строке — порт туннеля,
+# хост, домен. Любая запись по нему отбивается совсем, и опт-аут не действует. Умолчание
+# молчит: чужой адрес здесь опаснее неназванного — он отбивал бы работу с локальной базой.
+RT_PROD_DSN="${RT_PROD_DSN:-}"
+
+# Подключения среды разработки в лицо: по одному тексту запроса бой от локальной копии не
+# отличить, база выбирается идентификатором подключения. Идентификаторы локальны для машины.
+RT_PROD_CONNECTIONS="${RT_PROD_CONNECTIONS:-}"
+RT_LOCAL_CONNECTIONS="${RT_LOCAL_CONNECTIONS:-}"
+
+# Порты одноразовых баз: по ним вопрос не задаётся. Не назван — исключения нет вовсе.
+RT_SCRATCH_PORT_RE="${RT_SCRATCH_PORT_RE:-}"
+
+# Форма номера в заголовке заявки на слияние. Тот же номер стоит у задачи и у ветки.
+RT_TASK_TITLE_RE="${RT_TASK_TITLE_RE:-^\[[A-Za-z]+-[0-9]+\][[:space:]]+[^[:space:]]}"
+
+# Чем заводится задача и чем сверяется очередь работ. Идут в текст отказа гарда поставки:
+# отказ без действия обходят, а не исполняют.
+RT_TASK_NEW_CMD="${RT_TASK_NEW_CMD:-npm run task:new}"
+RT_BOARD_CHECK_CMD="${RT_BOARD_CHECK_CMD:-npm run check:board}"
+
+# Учётная запись, которую ставят исполнителем. Умолчание молчит: у каждого дерева она своя.
+RT_TASK_BOT="${RT_TASK_BOT:-}"
+
+# Состояние задачи одним объектом: exists, open, onBoard, assigned, numbered. Спрашивает
+# помощника очереди работ — того же, которым пользуются сверка и команда заведения, чтобы
+# гард и очередь одинаково понимали «задача в порядке». Нет узла, нет помощника, нет сети —
+# молчание, и ярус состояния пропускается: проверять нечем.
+rt_task_state_default() {
+    command -v node >/dev/null 2>&1 || return 1
+    [ -f "${RT_BOARD_HELPER:-tools/board.mjs}" ] || return 1
+    state="$(node "${RT_BOARD_HELPER:-tools/board.mjs}" task "$1" 2>/dev/null)" || return 1
+    [ -z "$state" ] && return 1
+    # Ответ с меткой «сети не было» состоянием не является: по нему нельзя отличить задачу,
+    # которой нет, от задачи, о которой не спросили.
+    printf '%s' "$state" | jq -e 'has("offline") | not' >/dev/null 2>&1 || return 1
+    printf '%s' "$state"
+}
+
+# Что в этом дереве считается переизобретением. По строке «образец<таб>чем заменить».
+# Образцы узкие намеренно: гард сверяет только НОВЫЙ текст, и широкий образец отбивал бы
+# правку, которая ничего нового не заводит.
+rt_reinvented_in_default() {
+    case "$1" in
+        *.ts)
+            printf '%s\t%s\n' '@(Input|Output|ViewChild|ViewChildren|ContentChild)\(' 'input(), output(), viewChild(), contentChild() — реактивный вход и выход'
+            printf '%s\t%s\n' 'get [a-zA-Z]+\(\)[[:space:]]*(:|\{)' 'computed(): производное значение сигналом, а не геттером'
+            ;;
+        *.html)
+            printf '%s\t%s\n' '\[ngClass\]|\[class\.' 'директивы класса кита'
+            ;;
+        *.scss)
+            printf '%s\t%s\n' '#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?\b' 'токен оформления вместо записанного цвета'
+            ;;
+    esac
+}
+
+# Где якорь для спек не требуется. Витрина, корневая разметка и сборка — общее у всех деревьев;
+# своё дерево дописывает надстройкой.
+RT_QA_SKIP_RE="${RT_QA_SKIP_RE:-/node_modules/|/dist/|\.stories\.html\$|/src/index\.html\$}"
+
+# По какому имени тег опознаётся компонентом этого дерева. Умолчание — составной тег: имя с
+# дефисом принадлежит компоненту, а не разметке, и это верно везде, где есть свои компоненты.
+RT_QA_COMPONENT_RE="${RT_QA_COMPONENT_RE:--}"
+
+# Теги, которые спека не нажимает: оформление, разметка страницы, индикаторы. Перечисляются
+# именами через пробел. Умолчание молчит: у каждого кита свои, а чужое имя здесь глушило бы
+# проверку на теге, которого в этом дереве нет.
+rt_qa_decorative_default() {
+    return 0
+}
+
+# Умолчания под общими именами. Надстройка проекта объявит любое из них заново — и позовёт
+# отсюда то же имя с суффиксом `_default` для всего, чего не назвала сама.
+rt_push_checks() { rt_push_checks_default "$@"; }
+rt_docs_pair_for() { rt_docs_pair_for_default "$@"; }
+rt_lint_for() { rt_lint_for_default "$@"; }
+rt_task_branch_ok() { rt_task_branch_ok_default "$@"; }
+rt_reinvented_in() { rt_reinvented_in_default "$@"; }
+rt_is_app_code() { rt_is_app_code_default "$@"; }
+rt_qa_decorative() { rt_qa_decorative_default "$@"; }
+rt_task_state() { rt_task_state_default "$@"; }
+rt_report_body() { rt_report_body_default "$@"; }

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# rt-hook: PreToolUse mcp__claude-in-chrome__select_browser
 # Гард выбора браузера. PreToolUse на выборе браузера расширением.
 #
 # Отклоняет любой профиль, кроме закреплённого: чужой стоит лишнего круга и приводит в браузер,
@@ -11,7 +12,7 @@
 
 input="$(cat 2>/dev/null)"
 
-device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/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)"

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# rt-hook: PreToolUse AskUserQuestion
+# PreToolUse guard for AskUserQuestion.
+#
+# The browser choice is already made and pinned in browser-device-id.sh — asking again is noise, and the
+# answer could only ever be the pinned profile. Only questions actually about PICKING a browser
+# are blocked; every other question passes untouched.
+#
+# A bare "browser"/"браузер" substring is too broad for a web-dev project: questions about
+# client-side code, user agents, cross-browser bugs etc. legitimately use the word without
+# being about which Chrome profile to automate. Anchor on selection phrasing instead
+# (deviceId, "which/what browser", "какой браузер").
+#
+# FAIL-OPEN when browser-device-id.sh prints nothing.
+
+input="$(cat 2>/dev/null)"
+
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/browser-device-id.sh" 2>/dev/null)"
+[ -z "$device_id" ] && exit 0
+
+questions="$(printf '%s' "$input" | jq -r '[.tool_input.questions[]? | .question, .header, (.options[]?.label)] | join(" ")' 2>/dev/null)"
+[ -z "$questions" ] && exit 0
+
+printf '%s' "$questions" | grep -qiE 'deviceid|device id|(which|what|pick|choose|select)[^.]{0,25}\bbrowser\b|\bbrowser\b[^.]{0,25}(profile|to use)|как(ой|ую)?[^.]{0,15}браузер|брауз[а-я]*[^.]{0,20}(использовать|выбрать|выбор|нужен|запустить)' || exit 0
+
+echo "Do not ask which browser to use — the profile is pinned. Call select_browser with deviceId ${device_id} ('Main' profile)." >&2
+exit 2

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# rt-hook: PreToolUse mcp__claude-in-chrome__(list_connected_browsers|switch_browser)
 # Гард перечисления и переключения браузеров. PreToolUse.
 #
 # Сессии проекта живут в одном закреплённом профиле. Перечисление и переключение отдают общие
@@ -10,7 +11,7 @@
 
 cat >/dev/null 2>&1
 
-device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/browser-device-id.sh" 2>/dev/null)"
 [ -z "$device_id" ] && exit 0
 
 echo "Не перечисляй и не переключай браузеры. Вызови выбор браузера с профилем ${device_id} — единственным, где сделан вход." >&2

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# rt-hook: PreToolUse mcp__playwright__.*|mcp__chrome-devtools__.*|Bash
 # Гард обходных путей к браузеру. PreToolUse.
 #
 # Закрепление профиля чего-то стоит только тогда, когда дверь одна. Здесь перечислены двери,
@@ -13,7 +14,7 @@
 
 input="$(cat 2>/dev/null)"
 
-device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/browser-device-id.sh" 2>/dev/null)"
 [ -z "$device_id" ] && exit 0
 
 tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# rt-hook: PreToolUse mcp__claude-in-chrome__.*
 # Гард свежести выбора браузера. PreToolUse на всех остальных вызовах расширения.
 #
 # ЗАЧЕМ ОН ЕСТЬ — отказ, из которого он вырос: расширение действует на тот браузер, который
@@ -20,7 +21,7 @@
 
 input="$(cat 2>/dev/null)"
 
-device_id="$("${CLAUDE_PROJECT_DIR:-.}/{{hooksDir}}/browser-device-id.sh" 2>/dev/null)"
+device_id="$("${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/browser-device-id.sh" 2>/dev/null)"
 [ -z "$device_id" ] && exit 0
 
 tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"

package/assets/hooks/commit-msg.sh

@@ -4,7 +4,7 @@
 # Версионируемый шаблон: рабочая копия хуков гита не версионируется, поэтому файл ставится в
 # неё отдельно — скриптом подготовки при установке зависимостей. Переустановка руками, если
 # подготовка почему-то не отработала:
-#   cp {{hooksDir}}/commit-msg.sh .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+#   cp .claude/hooks/commit-msg.sh .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
 #
 # Намеренно НЕ через обёртку, подменяющую путь хуков: подмена уводит гит в свой каталог и рвёт
 # остальные хуки, уже лежащие в рабочей копии. Родной путь оставляет их нетронутыми.

package/assets/hooks/constitution-index.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# rt-hook: SessionStart startup|resume|compact|clear
 # Вход в слой законов. SessionStart.
 #
 # Файл закона сам по себе не приносит в контекст ничего — его читают, только когда за ним
@@ -11,7 +12,7 @@
 # ОТКАЗ В ПОЛЬЗУ РАБОТЫ: любая ошибка начинает сессию без добавленного контекста (exit 0).
 # Сломанный вход не имеет права остановить сессию.
 
-dir="${CLAUDE_PROJECT_DIR:-.}/{{lawsDir}}"
+dir="${CLAUDE_PROJECT_DIR:-.}/docs/constitution"
 [ -d "$dir" ] || exit 0
 
 index=""
@@ -19,15 +20,15 @@ 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'
+    index="${index}  docs/constitution/$(basename "$law") — ${title}"$'\n'
 done
 [ -z "$index" ] && exit 0
 
 read -r -d '' context <<EOF
-ЗАКОНЫ ПРОЕКТА (слой @rt-tools/agent-kit, разложен в {{lawsDir}}/).
+ЗАКОНЫ ПРОЕКТА (слой @rt-tools/agent-kit, разложен в docs/constitution/).
 
 Закон говорит, ЧТО должно быть верно, и не знает ни путей, ни имён файлов. Правило — каким
-приёмом это делается — живёт в {{rulesDir}}/, а имена этого дерева при нём — в
+приёмом это делается — живёт в .claude/skills/, а имена этого дерева при нём — в
 implementation.md рядом. Закон не отменяет правила и не заменяется им: перед решением, которое
 закон задевает, читается закон целиком, правило — как обычно.
 

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# rt-hook: PreToolUse Bash|mcp__webstorm__execute_terminal_command|mcp__webstorm__execute_run_configuration|mcp__webstorm__execute_tool
 # Гард второго сервера разработки. PreToolUse.
 #
 # Приложения уже подняты владельцем, и всякая проверка через браузер идёт туда. Второй
@@ -9,7 +10,7 @@
 # Отбивается всё, что ПОДНИМАЕТ сервер. Сборка, тесты, линтеры, запросы к поднятым портам и
 # осмотр слушателей проходят.
 #
-# Где именно подняты приложения, знает профиль проекта: {{projectProfile}}, переменная
+# Где именно подняты приложения, знает профиль проекта: .claude/rt-kit/project.sh, переменная
 # RT_STANDS. Нет профиля — текст отказа остаётся общим, сам гард работает.
 
 input="$(cat 2>/dev/null)"
@@ -66,12 +67,13 @@ case "$cmd" in
         printf '%s' "$cmd" | grep -qE '(^|[[:space:]])git[[:space:]]+daemon([[:space:]]|$)' || exit 0 ;;
 esac
 
-stands=""
-profile="${CLAUDE_PROJECT_DIR:-.}/{{projectProfile}}"
-if [ -f "$profile" ]; then
+# Профиль дерева: сперва умолчание пакета, поверх него — надстройка проекта, если она есть.
+rt_hooks_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+for profile in "$rt_hooks_dir/../rt-kit/defaults/project.sh" "$rt_hooks_dir/../defaults/project.sh" "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/defaults/project.sh" "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/project.sh"; do
     # shellcheck disable=SC1090
-    . "$profile" 2>/dev/null && stands="${RT_STANDS:-}"
-fi
+    [ -f "$profile" ] && . "$profile" 2>/dev/null
+done
+stands="${RT_STANDS:-}"
 
 deny() {
     if [ -n "$stands" ]; then