@rt-tools/agent-kit 0.8.1 → 0.8.3

package/assets/commands/skill-curator.md

@@ -6,8 +6,14 @@ argument-hint: '[пусто | <акцент, на что смотреть в п
 Запусти агента `skill-curator` на разбор только что закрытой задачи. Акцент от пользователя:
 `$ARGUMENTS`
 
-Вызывается **после того, как задача сделана и проверена**, до перехода к следующей. Агент ничего
-не правит — приносит готовые формулировки, а решение вставлять их принимает пользователь.
+Вызывается **сразу за открытием PR** — тем же ходом, которым работа отдана на разбор. Агент
+ничего не правит: он приносит готовые формулировки, а решение вставлять их принимает
+пользователь.
+
+**Запуск фоновый, и ход на нём не кончается.** Пока агент работает, берётся следующая задача:
+он ничего не спрашивает и быстрее от ожидания не идёт. Шаги 1 и 2 делаются до запуска — пока
+задача ещё в голове; шаги 4–6 принимают вернувшийся ответ одним ходом и возвращают исполнителя
+к прежней работе.
 
 ## 1. Найди список загруженного
 
@@ -42,48 +48,61 @@ ls -t "${TMPDIR}claude-skill-gate/"*.loaded | head -5
 которой не было» — ровно то, из чего получаются правила. Приглаженная сводка даёт приглаженный
 разбор.
 
-## 3. Запусти агента
+## 3. Запусти агента в фон и вернись к работе
 
 Инструментом `Agent`, `subagent_type: 'skill-curator'`. В промпт — путь к `.loaded` и сводку
 целиком.
 
-## 4. Выгрузи предложения файлом
+Ход на этом не кончается: пока агент работает, берётся следующая задача. Ответ придёт
+уведомлением, и тогда идут шаги 4–6 — один ход, после которого исполнитель возвращается к тому,
+что делал.
+
+## 4. Положи находки в папку задачи
 
-Ответ роли живёт в переписке и умирает вместе с ней, а правки в пакет идут из другого дерева и
-в другой день. Поэтому предложения ложатся на диск — их пишешь ты, не роль: файлов она не
-пишет вовсе.
+Ответ роли живёт в переписке и умирает вместе с ней, поэтому он сразу ложится на диск — рядом с
+ходом работы, в папку задачи. Пишешь его ты, не роль: файлов она не пишет вовсе.
 
 ```bash
-mkdir -p .claude/rt-kit/proposals
-cp .claude/rt-kit/templates/proposal.md .claude/rt-kit/proposals/$(date +%F)-<ветка>.md
+cat > docs/tasks/<ветка>/curator.md    # заголовок блока — «## <адрес> · <ресурс>»
 ```
 
-Дальше — по блоку на предложение, заголовком `## <адрес> · <ресурс>`. Адрес роль уже поставила,
-твоё дело — не потерять его и не переписать текст своими словами.
+Адрес у каждого блока роль уже поставила — «пакет», «компаньон» или «дерево». Твоё дело — не
+потерять его и не переписать текст своими словами.
 
-Файл читает `agent-kit propose`: по заголовку он отбирает то, что уезжает в репозиторий пакета.
-Блок без адреса в заголовке не уедет никуда и останется лежать молча.
+Папка задачи умирает со слиянием, а находки должны пережить весь эпик: владелец читает их
+разом, когда эпик кончился. Поэтому при разборе папки файл находок не удаляется, а переезжает к
+замыслу эпика — паттерн закрытия работы. Работа вне эпика показывает находки владельцу сразу.
 
-## 5. Отправь то, что адресовано пакету
+## 5. Отправь сводку наблюдений — и только её
 
 ```bash
 npx agent-kit propose --dry-run     # что уехало бы
-npx agent-kit propose               # завести запись в очереди работ пакета
+npx agent-kit propose               # отправить груз в приём
 ```
 
-Уезжают только блоки с адресом «пакет», и вместе с ними — сводка наблюдений: без цифр
-предложение читается как мнение. Отправленное помечается ссылкой в том же файле и второй раз
-не уезжает.
+Груз уезжает при каждом прогоне: сводка наблюдений со снимком надстроек, разборы происшествий и
+предложения, лежащие в каталоге предложений. Сводка — факт: чем пользовались, чем не
+пользовались ни разу, что дерево переопределило. Она уезжает всегда и слова владельца не ждёт.
+
+**Находки разбора в каталог предложений сами не ложатся, и потому не уезжают.** Предложение —
+заготовка правки чужого дерева, и часть заготовок отпадает при первом же чтении; уехавшая без
+разбора, она становится работой того, кто её не заказывал. В каталог предложений переносится
+только то, что владелец назвал верным, — и тогда же уезжает.
+
+Отправка отказывает, если адрес этого дерева нашёлся в сводке или в тексте предложения — путь,
+имя корня, чужой репозиторий. Это не придирка: груз уезжает наружу целиком. Правь текст, а не
+обходи проверку. Разбор происшествия проверкой не накрыт: он по устройству называет файлы
+дерева, где промах случился.
 
-Отправка отказывает, если в тексте предложения нашёлся адрес этого дерева — путь, имя корня,
-чужой репозиторий. Это не придирка: файл уезжает в чужой репозиторий целиком. Правь текст, а не
-обходи проверку.
+## 6. Отдай находки владельцу — по концу эпика
 
-## 6. Отдай результат владельцу
+Покажи находки **как есть**: роль пишет готовый текст для вставки, и пересказ его портит. По
+каждой скажи своё — согласен или нет и почему; правило, с которым ты не согласен, вставлять не
+надо.
 
-Покажи предложения агента **как есть**: он пишет готовый текст для вставки, и пересказ его
-портит. По каждому скажи своё — согласен или нет и почему; правило, с которым ты не согласен,
-вставлять не надо.
+Работа в эпике показывает их не сразу: находки копятся у замысла эпика и читаются разом, когда
+эпик кончился, — так владелец видит повторяющееся, а не разрозненные заметки. Названное им
+верным переносится в каталог предложений и уезжает шагом 5.
 
 У каждого предложения агент ставит пометку «пакет», «компаньон» или «дерево»: тексты приезжают
 из `@rt-tools/agent-kit`, и правка разложенного файла на месте теряется на следующем

package/assets/defaults/gate-map.sh

@@ -40,6 +40,13 @@ skill_for_default() {
     case "$kind" in
         edit)
             case "$target" in
+                # Надстройка над разложенным текстом — правка того же текста: путь другой, а
+                # предмет тот же. Ветка стоит первой, потому что путь надстройки кончается тем
+                # же именем файла, что и разложенная копия, и ветки ниже разобрали бы её по
+                # расширению — то есть правилом формулировок вместо правила устройства.
+                */.claude/rt-kit/overrides/laws/* | */.claude/rt-kit/overrides/rules/* | */.claude/rt-kit/overrides/patterns/*)
+                    printf '%s\n' 'spec-driven' ;;
+
                 # Правило и паттерн — такая же договорённость, как спек: обязательные разделы,
                 # утверждение с привязкой, граница между статьёй закона и утверждением правила.
                 # Ветка стоит раньше общего исключения и раньше `*.md`: под исключением текст
@@ -138,9 +145,9 @@ skill_for_default() {
                 || rt_gate_invokes "$target" "[^[:space:]]*task:new" \
                 || rt_gate_invokes "$target" "prisma[[:space:]]+(migrate|db)"; then
                 printf '%s\n' 'git-workflow'
-            # Правка тела отчёта через клиент хостинга ловится двумя признаками сразу — вызовом
+            # Правка тела PR через клиент хостинга ловится двумя признаками сразу — вызовом
             # клиента И адресом запроса: одного слова о заявке мало, оно попадает в строку любой
-            # команды, которая о ней пишет. Тело отчёта не читает ни одна проверка, и утверждение
+            # команды, которая о ней пишет. Тело PR не читает ни одна проверка, и утверждение
             # о дереве стареет в нём молча.
             elif rt_gate_invokes "$target" "(gh|glab)[[:space:]]+api" \
                 && printf '%s' "$target" | grep -qE '(-X|--method)[[:space:]]+(PATCH|PUT).*(pulls|merge_requests)/[0-9]+'; then
@@ -154,8 +161,8 @@ skill_for_default() {
                 printf '%s\n' 'git-workflow'
             fi
 
-            # Слияние отчёта — последний момент, когда папку закрытой задачи ещё можно разобрать
-            # тем же отчётом: после слияния сверка очереди её видит, а отвечать за неё уже
+            # Слияние PR — последний момент, когда папку закрытой задачи ещё можно разобрать
+            # тем же PR: после слияния сверка очереди её видит, а отвечать за неё уже
             # некому. Требуется ВТОРЫМ слоем, дополнительно к правилу поставки.
             rt_gate_invokes "$target" "(gh[[:space:]]+pr|glab[[:space:]]+mr)[[:space:]]+merge" \
                 && printf '%s\n' 'task-flow'

package/assets/defaults/project.sh

@@ -166,6 +166,36 @@ rt_is_app_code_default() {
     esac
 }
 
+# Пишет ли команда оболочки файл. Успех — да, и тогда пути из неё судятся тем же признаком,
+# что и путь из вызова инструмента правки.
+#
+# Гарды подписаны на инструменты правки файла, и этого мало: ту же правку кладут командой —
+# перенаправлением, `tee`, `sed -i`, интерпретатором с heredoc. Отбитая правка дважды за один
+# заход легла именно так, и не увидел этого никто: в дереве она неотличима от положенной
+# инструментом. Разбор — `2026-08-15-guard-denied-shell-wrote-anyway.md`.
+#
+# Список намеренно широк, и цена этого названа: команда чтения, в которой стоит имя
+# интерпретатора, будет отбита наравне с командой правки. Узкий список стоил бы дороже —
+# пропущенная форма записи возвращает обход целиком, а найти её можно только промахом.
+rt_shell_writes_default() {
+    printf '%s' "$1" | grep -Eq \
+        '>>?[[:space:]]*[^|&>[:space:]]|\btee\b|\bsed\b[^|]*-i|\bperl\b[^|]*-i|\bpython3?\b|\bnode\b|\bruby\b|\bdd\b[^|]*of=|\bcp\b|\bmv\b|\brm\b|\btouch\b|\btruncate\b|\binstall\b|\bpatch\b|\bgit[[:space:]]+(checkout|restore|apply|stash)\b'
+}
+
+# Пути, названные командой оболочки. Печатает по одному в строке; судит их зовущий.
+#
+# Разбирать оболочку по-настоящему нечем — здесь и не разбирают: из текста вынимается всё, что
+# похоже на путь, и каждое отдаётся признаку. Лишнее он отсеет сам, а пропущенное вернуло бы
+# обход. Кавычки и heredoc снимаются заменой на пробел: путь внутри них тот же самый.
+rt_shell_paths_default() {
+    printf '%s' "$1" \
+        | tr "\"'\`(),;=" '        ' \
+        | tr '[:space:]' '\n' \
+        | grep -E '^[A-Za-z0-9_@.-]*/[A-Za-z0-9_@./-]+$' \
+        | sed 's|^\./||' \
+        | sort -u
+}
+
 # Имя ветки, с которой разрешено открывать заявку на слияние: в имени стоит номер задачи.
 # Приставка — либо род правки, либо метка очереди работ: обе формы носят номер, а он и нужен.
 #
@@ -201,6 +231,20 @@ RT_BOARD_CHECK_CMD="${RT_BOARD_CHECK_CMD:-npm run check:board}"
 # Учётная запись, которую ставят исполнителем. Умолчание молчит: у каждого дерева она своя.
 RT_TASK_BOT="${RT_TASK_BOT:-}"
 
+# Почта, которой подписан коммит машинной учётной записи. Целым значением, а не образцом:
+# служебный адрес хостинга состоит из числа, логина и домена, а сопоставляется по числу — логин
+# рядом с ним не сверяет никто. Образец «число, плюс, логин» прошёл бы с чужим числом, то есть
+# ровно с тем промахом, ради которого гард поставки подпись и читает.
+#
+# Отсюда же он берёт логин машинной записи — левой частью адреса, до собаки и после плюса.
+# Вторым свойством логин не объявляется: два объявления одного имени разошлись бы молча.
+# Исполнитель задачи для этого не годится — там, где хостинг ограничил машинную запись,
+# исполнителем ставят человека, а коммит остаётся машинным.
+#
+# Умолчание молчит, и тогда подпись не судится: своей машинной записи у пакета нет, а выдуманная
+# отбивала бы работу в чужом дереве.
+RT_COMMIT_EMAIL="${RT_COMMIT_EMAIL:-}"
+
 # Состояние задачи одним объектом: exists, open, onBoard, assigned, numbered. Спрашивает
 # помощника очереди работ — того же, которым пользуются сверка и команда заведения, чтобы
 # гард и очередь одинаково понимали «задача в порядке». Нет узла, нет помощника, нет сети —
@@ -259,6 +303,8 @@ 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_shell_writes() { rt_shell_writes_default "$@"; }
+rt_shell_paths() { rt_shell_paths_default "$@"; }
 rt_qa_decorative() { rt_qa_decorative_default "$@"; }
 rt_task_state() { rt_task_state_default "$@"; }
 rt_report_body() { rt_report_body_default "$@"; }

package/assets/docs/GLOSSARY.md

@@ -1,7 +1,7 @@
 # Словарь проекта
 
 Слова, которые в этом дереве значат что-то определённое. Читается перед тем, как написать спек,
-правило, комментарий, тело коммита или описание отчёта: слово отсюда употребляется в том
+правило, комментарий, тело коммита или описание PR: слово отсюда употребляется в том
 значении, что здесь, а слово не отсюда либо заводится здесь же, либо заменяется простым.
 
 Термины одного домена живут в разделе «Терминология» его спека — здесь только те, что проходят
@@ -13,44 +13,45 @@
 
 ## Слой правил
 
-| Термин                    | Что это                                                                                                                                                     |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Закон                     | Файл в каталоге конституции. Говорит, что должно быть верно, и не знает ни путей, ни имён файлов. Верен для любого приложения этого класса                  |
-| Законы приложения         | Слой законов, верных только для этого приложения: деньги, локали, доступ. Предметность в них законна — она их предмет                                       |
-| Правило                   | Скил с `kind: rule`. Привязывает закон к этому дереву: чем это здесь названо и где лежит                                                                    |
-| Паттерн                   | Скил с `kind: pattern`. Готовый код и порядок действий; стоит при правиле                                                                                   |
-| Компаньон                 | Файл `implementation.md` рядом с правилом: имена и пути этого дерева. Пакет знает приём, но не знает имён — их пишет проект                                 |
-| Спек                      | Описание домена: как он работает. Говорит об установившемся, а не о предстоящем                                                                             |
-| Домен                     | Предмет, у которого свой спек. Выросший домен делится на поддомены, а не на соседние домены                                                                 |
-| Сценарий                  | Наблюдаемое поведение под номером `SC-<ПРЕФИКС>-<НОМЕР>`. Номер стоит в заголовке теста                                                                     |
-| Привязка                  | Строка `` `файл:символ` `` в компаньоне или в спутнике спека — место, где утверждение исполняется                                                           |
-| Спутник                   | Файл рядом со спеком или правилом: компаньон, перечень сценариев                                                                                            |
-| Договорённость о продукте | Как продукт себя поведёт, записанное до кода. Единственное место, где спек говорит о будущем; после выкатки вливается в спек домена, а директория удаляется |
-| Ресурс                    | Единица того, что везёт пакет правил: закон, правило, паттерн, гард, проверка, роль, команда, конвейер, шаблон, умолчание, документ                         |
-| Раскладка                 | Перенос ресурса из пакета в дерево по его роду и настройке слоя                                                                                             |
-| Разложенный файл          | Файл в дереве с шапкой пакета. Правится не на месте, а надстройкой: правка на месте теряется на следующей раскладке                                         |
-| Надстройка                | Файл дерева, который сливается с разложенным по заголовкам разделов                                                                                         |
-| Наблюдение                | Строка о событии слоя правил: правило загружено, гейт отбил, гард отказал. Пишет гард, живёт в дереве, наружу уезжает счётчиками. Журналом не называется    |
-| Сводка                    | Что наблюдения говорят за отрезок дней: чем пользовались, чем ни разу, обо что спотыкались                                                                  |
-| Предложение               | Готовая формулировка правки правил с адресом: пакет, компаньон или дерево. Приносит разбор закрытой задачи, отправляет человек командой                     |
+| Термин                    | Что это                                                                                                                                                          |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Закон                     | Файл в каталоге конституции. Говорит, что должно быть верно, и не знает ни путей, ни имён файлов. Верен для любого приложения этого класса                       |
+| Законы приложения         | Слой законов, верных только для этого приложения: деньги, локали, доступ. Предметность в них законна — она их предмет                                            |
+| Правило                   | Скил с `kind: rule`. Привязывает закон к этому дереву: чем это здесь названо и где лежит                                                                         |
+| Паттерн                   | Скил с `kind: pattern`. Готовый код и порядок действий; стоит при правиле                                                                                        |
+| Компаньон                 | Файл `implementation.md` рядом с правилом: имена и пути этого дерева. Пакет знает приём, но не знает имён — их пишет проект                                      |
+| Спек                      | Описание домена: как он работает. Говорит об установившемся, а не о предстоящем                                                                                  |
+| Домен                     | Предмет, у которого свой спек. Выросший домен делится на поддомены, а не на соседние домены                                                                      |
+| Сценарий                  | Наблюдаемое поведение под номером `SC-<ПРЕФИКС>-<НОМЕР>`. Номер стоит в заголовке теста                                                                          |
+| Привязка                  | Строка `` `файл:символ` `` в компаньоне или в спутнике спека — место, где утверждение исполняется                                                                |
+| Спутник                   | Файл рядом со спеком или правилом: компаньон, перечень сценариев                                                                                                 |
+| Договорённость о продукте | Как продукт себя поведёт, записанное до кода. Единственное место, где спек говорит о будущем; после выкатки вливается в спек домена, а директория удаляется      |
+| Ресурс                    | Единица того, что везёт пакет правил: закон, правило, паттерн, гард, проверка, роль, команда, конвейер, шаблон, умолчание, документ                              |
+| Раскладка                 | Перенос ресурса из пакета в дерево по его роду и настройке слоя                                                                                                  |
+| Разложенный файл          | Файл в дереве с шапкой пакета. Правится не на месте, а надстройкой: правка на месте теряется на следующей раскладке                                              |
+| Надстройка                | Файл дерева, который сливается с разложенным по заголовкам разделов                                                                                              |
+| Наблюдение                | Строка о событии слоя правил: правило загружено, гейт отбил, гард отказал. Пишет гард, живёт в дереве, наружу уезжает счётчиками. Журналом не называется         |
+| Сводка                    | Что наблюдения говорят за отрезок дней: чем пользовались, чем ни разу, обо что спотыкались                                                                       |
+| Предложение               | Готовая формулировка правки правил с адресом: пакет, компаньон или дерево. Приносит разбор закрытой задачи или слово посреди работы, отправляет человек командой |
+| Слово                     | Реплика человека посреди работы о слое правил: что мешает, чего не хватило, что сработало не так. Ложится блоком в файл предложений, а не живёт до конца захода  |
 
 ## Работа
 
-| Термин          | Что это                                                                                                                                                                                      |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Задача          | Единица работы в очереди работ. Заводится до ветки, и номер её стоит в имени ветки и в заголовке отчёта                                                                                      |
-| Отчёт           | Заявка на слияние: то же название, что у задачи, переведённое в сделанное                                                                                                                    |
-| Очередь работ   | Доска, на которой видно состояние каждой задачи. Ветки она не видит                                                                                                                          |
-| Папка задачи    | Одна работа от разбора до слияния: разбор просьбы, замысел, ход работы. Умирает со слиянием — разбирается, и объясняющее решение уезжает в архив                                             |
-| Разбор          | Расспрос владельца до первой правки. Записывается его словами и задним числом не переписывается                                                                                              |
-| Замысел         | Файл папки задачи: след задачи и этапы с признаками готовности. После написания не правится — с ним сверяют результат при приёмке                                                            |
-| Ход работы      | Файл папки задачи: «Где стоим», решения по ходу с причинами, записи заходов. Единственное место, где отмечается сделанное. Журналом не называется                                            |
-| След задачи     | Раздел замысла: какие спеки, законы, правила и части кода работа задевает                                                                                                                    |
-| Заход           | Одна сессия работы над задачей. Работа живёт дольше одного захода, и между ними её состояние держит только ход работы                                                                        |
-| Заполнение окна | Доля места захода, которую он уже занял: вход, запись в кэш, прочитанное из кэша и вывод последнего ответа, делённые на размер окна. Не «расход» и не «бюджет»: речь о месте, а не о деньгах |
-| Передача        | Текст, которым заход закрывается: рабочее дерево, ветка, задача, где лежит ход работы, что сделано, следующий шаг, особенности захода. Кладётся вне дерева и не коммитится                   |
-| Линия работ     | Файл с порядком задач и зависимостями между ними, когда из одного разбора вышло несколько задач. Шире одной ветки                                                                            |
-| Архив           | Записи о состоявшемся: что объясняет закрытое решение. После выкатки не правится                                                                                                             |
+| Термин          | Что это                                                                                                                                                                                                                                                                       |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Задача          | Единица работы в очереди работ. Заводится до ветки, и номер её стоит в имени ветки и в заголовке PR                                                                                                                                                                           |
+| PR              | Заявка на слияние: то же название, что у задачи, переведённое в сделанное. Отчётом, пул-реквестом и мёрдж-реквестом не называется — ни в файлах, ни в разговоре                                                                                                               |
+| Очередь работ   | Доска, на которой видно состояние каждой задачи. Ветки она не видит                                                                                                                                                                                                           |
+| Папка задачи    | Одна работа от разбора до слияния: разбор просьбы, замысел, ход работы. Умирает со слиянием — разбирается, и объясняющее решение уезжает в архив                                                                                                                              |
+| Разбор          | Расспрос владельца до первой правки. Записывается его словами и задним числом не переписывается                                                                                                                                                                               |
+| Замысел         | Файл папки задачи: след задачи и этапы с признаками готовности. После написания не правится — с ним сверяют результат при приёмке                                                                                                                                             |
+| Ход работы      | Файл папки задачи: «Где стоим», решения по ходу с причинами, записи заходов. Единственное место, где отмечается сделанное. Журналом не называется                                                                                                                             |
+| След задачи     | Раздел замысла: какие спеки, законы, правила и части кода работа задевает                                                                                                                                                                                                     |
+| Заход           | Одна сессия работы над задачей. Работа живёт дольше одного захода, и между ними её состояние держит только ход работы                                                                                                                                                         |
+| Заполнение окна | Доля места захода, которую он уже занял: вход, запись в кэш, прочитанное из кэша и вывод последнего ответа, делённые на размер окна. Не «расход» и не «бюджет»: речь о месте, а не о деньгах                                                                                  |
+| Передача        | Текст, которым заход закрывается: рабочее дерево, ветка, задача, где лежит ход работы, что сделано, следующий шаг, особенности захода. Кладётся вне дерева и не коммитится                                                                                                    |
+| Эпик            | Серия задач одной темы, выполняемых в назначенном порядке. Живёт в двух местах сразу: карточка в очереди работ с меткой эпика и замысел рядом с ней — что за возможность разрабатывается, какие задачи входят и в каком порядке. Шире одной ветки. Линией работ не называется |
+| Архив           | Записи о состоявшемся: что объясняет закрытое решение. После выкатки не правится                                                                                                                                                                                              |
 
 ## Проверки
 
@@ -65,13 +66,15 @@
 
 ## Так не пишем
 
-| Так не пишем               | Пишем так                                                                                      |
-| -------------------------- | ---------------------------------------------------------------------------------------------- |
-| спека (о тесте)            | тест — файл рядом с исходником; спек — документ. Одна буква разницы, а значения противоположны |
-| таска, тикет               | задача                                                                                         |
-| пул-реквест, мёрдж-реквест | отчёт, а действие — слияние                                                                    |
-| джоба, пайплайн            | конвейер и его шаг                                                                             |
-| хендофф                    | передача                                                                                       |
-| бэклог                     | очередь работ                                                                                  |
-| контекст-виндоу            | окно захода, а его доля — заполнение окна                                                      |
-| скилл, скилы               | правило, паттерн или скил без закона — по тому, что это на самом деле                          |
+| Так не пишем                | Пишем так                                                                                      |
+| --------------------------- | ---------------------------------------------------------------------------------------------- |
+| спека (о тесте)             | тест — файл рядом с исходником; спек — документ. Одна буква разницы, а значения противоположны |
+| таска, тикет                | задача                                                                                         |
+| пул-реквест, мёрдж-реквест  | PR, а действие — слияние                                                                       |
+| отчёт (о заявке на слияние) | PR; отчёт — сводка данных, и слово занято ею                                                   |
+| джоба, пайплайн             | конвейер и его шаг                                                                             |
+| хендофф                     | передача                                                                                       |
+| бэклог                      | очередь работ                                                                                  |
+| линия работ                 | эпик                                                                                           |
+| контекст-виндоу             | окно захода, а его доля — заполнение окна                                                      |
+| скилл, скилы                | правило, паттерн или скил без закона — по тому, что это на самом деле                          |

package/assets/hooks/docs-guard.sh

@@ -17,8 +17,8 @@
 #
 # Отдельно — законы. Совпал ли код с законом, машина не знает: правка файла, на который закон
 # ссылается якорем, поэтому не отклоняется, а выносится вопросом владельцу. Тем же вопросом
-# встречается и правка самого закона: закон описывает договорённость о продукте, и менять её
-# молча гард не даёт.
+# встречается и правка самого закона — как на месте, так и надстройкой над ним: закон описывает
+# договорённость о продукте, и менять её молча гард не даёт.
 #
 # Обход — строка `Docs-skip: <причина>` в теле коммита. Причина остаётся в истории и видна при
 # разборе ветки; пустая не принимается.
@@ -66,11 +66,18 @@ command -v rt_needs >/dev/null 2>&1 || rt_needs() { command -v "$1" >/dev/null 2
 
 laws_dir="${RT_LAWS_DIR:-docs/constitution}"
 lib_marker="${RT_LIB_MARKER:-project.json}"
+overrides_dir="${RT_OVERRIDES_DIR:-.claude/rt-kit/overrides}"
 
 # ── Правка закона спрашивает владельца ────────────────────────────────────────
 #
 # Спутник рядом с законом — привязка статей к коду, она устаревает при каждом переименовании и
 # правится свободно. Спрашивается только сам текст закона.
+#
+# Путей к тексту закона два, и ходят чаще вторым. Разложенный закон на месте не правится вовсе:
+# правка теряется на следующей раскладке, а сама раскладка на неё отказывает, — поэтому правят
+# надстройку, и файл закона переписывает раскладка. Гард, знающий один каталог законов, сторожит
+# ровно тот путь, которым к закону и не ходят: чем сложнее надстройка дерева, тем реже закон
+# правят на месте. Спрашивается и надстройка — по содержанию это правка закона, а не обвязки.
 case "$tool" in
     Edit | Write | MultiEdit | NotebookEdit | mcp__webstorm__create_new_file)
         target="$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.filePath // .tool_input.path // .tool_input.pathInProject // empty' 2>/dev/null)"
@@ -79,6 +86,10 @@ case "$tool" in
             */"$laws_dir"/*.md | "$laws_dir"/*.md)
                 decide ask "Правка закона: \`${target##*/}\`. Закон описывает договорённость о продукте, а не устройство кода, — назови владельцу, что и почему меняешь, и дождись ответа. Если правка уже согласована, подтверди вызов."
                 ;;
+            */"$overrides_dir"/laws/*.implementation.md | "$overrides_dir"/laws/*.implementation.md) exit 0 ;;
+            */"$overrides_dir"/laws/*.md | "$overrides_dir"/laws/*.md)
+                decide ask "Правка закона надстройкой: \`${target##*/}\`. Разложенный файл переписывает раскладка, поэтому правка надстройки — это правка самого закона: назови владельцу, что и почему меняешь, и дождись ответа. Если правка уже согласована, подтверди вызов."
+                ;;
         esac
         exit 0
         ;;
@@ -112,7 +123,12 @@ esac
 
 # Причина обхода остаётся в истории, поэтому обход законен. Пустая строка обходом не считается:
 # «Docs-skip:» без причины — это тот же молчаливый пропуск, только с двоеточием.
-if printf '%s' "$cmd" | grep -qiE 'Docs-skip:[[:space:]]*[^[:space:]"'"'"']{3,}'; then
+#
+# Строка начинает строку — свою в теле коммита или комментарий в конце команды — и подстановки
+# не принимает. То же условие, что у обхода при слиянии: иначе текст, который ОБЪЯСНЯЕТ обход,
+# снимает требование сам собой. Тело коммита о правке гарда как раз называет эту строку, и без
+# привязки к началу гард пропускал бы такой коммит молча.
+if printf '%s' "$cmd" | grep -qiE '(^|#)[[:space:]]*Docs-skip:[[:space:]]*[^[:space:]<"'"'"'][^[:space:]"'"'"']{2,}'; then
     exit 0
 fi