agent-quality-kit 0.14.0 → 0.16.0

package/kit/docs/ai/operational-gates.md

@@ -0,0 +1,275 @@
+# Эксплуатационные гейты из живого AI-проекта: что переносить, а что не притворять универсальным
+
+> Проверено по коду `audit_project` 15.09.2026, ссылки на первоисточники сверены 16.09.2026. Это актуальная карта практики, а не ручной
+> снимок production-метрик. Живые значения остаются в Prometheus, логах и отчётах прогонов.
+>
+> Главная граница: здесь описаны **намерения и устройство арбитров**. Реализация конкретного
+> Django/Celery/Compose-проекта остаётся в его репозитории и объявляется в `.aqk.yml` командой,
+> а не копируется в AQK.
+
+## Один вывод
+
+Зелёная фича ещё не означает зелёную систему. Query budget одной ручки, memory budget одной
+задачи и тест одного worker не отвечают на вопрос, выдержит ли одновременно работающий флот
+общую RAM, PostgreSQL, Redis, диск и очередь.
+
+Поэтому бюджетов всегда два:
+
+1. **локальный** — SQL, время, память и корректность одного endpoint/task;
+2. **системный** — p95, error rate, суммарный working set, очереди и OOM под смешанной нагрузкой.
+
+## Карта по факту
+
+| Область | Что действительно держит машина | Честная граница |
+|---|---|---|
+| N+1 | 21 тестовый файл и 63 вызова `assertNumQueries` / `django_assert_max_num_queries`; полный pytest блокирует рост известных бюджетов | нет требования, что **каждая новая** list/paginated-ручка получила budget-тест |
+| DirectPG N+1 | отдельный тест проверяет не только число запросов, но и отсутствие линейного роста на увеличенном наборе | это проектный арбитр, обычный Django-счётчик его не заменяет |
+| OOM после факта | `ContainerOOM` на росте `container_oom_events_total`; выражение имеет firing и quiet сценарии `promtool` | cAdvisor в основном описывает работающие контейнеры; история exited/restart требует отдельного источника |
+| Лимиты observability | тест разбирает Compose и держит сумму лимитов tier под явным капом | это кап одного tier, не бюджет всего production-флота и не резерв RAM хоста |
+| Celery topology | объявленные/используемые очереди сравниваются с `worker -Q` в production Compose | имена и структура конфигурации проектные |
+| Celery redelivery | `visibility_timeout` сравнивается с максимальным hard time limit и запасом | длинный timeout ухудшает скорость возврата работы после принудительной смерти worker |
+| Публичные метрики | publisher обязан попасть в реестр; быстрый pre-commit ловит забытое имя, pytest проверяет глубокую проводку | наличие имени не доказывает, что production реально его собирает |
+| Prometheus rules | синтаксис и выбранная семантика правил проверяются `promtool`; после deploy сверяется набор реально загруженных правил | не каждое правило уже имеет отдельные firing/quiet samples |
+| Скрипты-гейты | `check-gate-wiring.py` требует автоматический запуск либо честную запись в реестре ручных инструментов | «запускается» не означает «полезен»; это другой вопрос |
+| Ошибки и trace | GlitchTip, Sentry SDK, Loki/Alloy и `request_id` связывают исключение с окружением запроса | доступность самой цепочки также нуждается в heartbeat/alert |
+| Backup | расписание, ротация, метрика успеха, `BackupStale` и тесты скрипта | копия на том же сервере не переживёт потерю сервера; restore надо репетировать отдельно |
+
+## Что ещё только видно, но не закрыто
+
+Наличие графика или Telegram-alert не равно предотвращению.
+
+### Память
+
+- нет ранней полосы «контейнер долго держится выше доли своего лимита»;
+- нет отношения `sum(container working_set) / host RAM` для всего флота;
+- нет host-level RAM/swap/PSI прибора уровня node exporter;
+- нет долговечной истории OOM/restart для уже остановившихся контейнеров;
+- нет memory budgets для всех тяжёлых pytest-сценариев;
+- сумма отдельных потолков не является резервированием общей памяти.
+
+Последний пункт особенно важен. Docker ограничивает отдельный сервис, но несколько сервисов
+могут одновременно приблизиться к своим пределам и исчерпать хост. Поэтому static Compose gate
+и runtime fleet gate решают разные задачи; один нельзя выдавать за другой.
+
+### PostgreSQL и Redis
+
+Экспортёры есть, но нужны отдельные решения по сигналам:
+
+- насыщение соединений и ожидание PgBouncer;
+- длинные транзакции, deadlocks, temp bytes и блокировки;
+- память Redis broker при `noeviction`;
+- rejected writes, а не только evictions;
+- возраст старейшей работы и ожидаемое время разбора очереди, а не одна глубина.
+
+### Нагрузка
+
+- Python load harness измеряет p50/p95/p99 и RPS, но плохие числа сами не дают красный код;
+- k6 thresholds существуют лишь у отдельных ручных сценариев;
+- нет обязательного смешанного прогона HTTP + Celery + отчёты + документы + интеграции;
+- нет nightly/pre-release запуска;
+- нет регулярного soak для утечек, high-watermark процессов и накопления соединений.
+
+## Как строится честный OOM-контур
+
+Одного правила `any OOM` мало. Нужны пять независимых слоёв.
+
+### 1. Статические лимиты сервисов
+
+Production Compose задаёт `deploy.resources.limits.memory` или эквивалент. Проверка разбирает
+эффективную конфигурацию, а не ищет слово `memory` grep-ом. Для каждого обязательного сервиса
+должно быть ясно, почему лимит такой и каким замером он получен.
+
+### 2. Конфигурационный бюджет
+
+Сумма лимитов выбранного tier не растёт молча. Это храповик конфигурации, а не обещание, что RAM
+зарезервирована. Поднять кап можно только вместе с измерением хоста и записанной причиной.
+
+### 3. Runtime budget флота
+
+Под смешанной нагрузкой считается:
+
+```text
+max_over_time((sum(container_memory_working_set_bytes))[15m:1m]) / host_memory_bytes
+```
+
+Точный PromQL зависит от labels и источника host memory. Порог нельзя копировать вслепую; для
+малого сервера разумная стартовая красная полоса должна оставлять запас ядру, Docker, page cache
+и пикам PostgreSQL. В исследованном проекте рабочей гипотезой остаётся 70%, но она ещё не стала
+доказанным гейтом.
+
+### 4. Раннее предупреждение контейнера
+
+Устойчивое превышение доли лимита предупреждает до OOM. Рабочая гипотеза проекта — около 85%,
+но её надо откалибровать по пикам и шуму. Мгновенный spike и десять минут давления — разные
+события.
+
+### 5. OOM и restart после факта
+
+Рост `container_oom_events_total` — critical. Но исчезновение ряда остановленного контейнера не
+должно превратить аварию в тишину: Docker events/inspect или другой collector хранит exit reason,
+restart count и timestamp независимо от текущей жизни контейнера.
+
+### Доказательство правила
+
+Для alert нужны минимум два `promtool`-сценария:
+
+- counter вырос внутри окна → alert firing с ожидаемыми labels/annotations;
+- counter не растёт → alert отсутствует.
+
+Синтаксически корректное выражение `vector(0)` обязано сделать первый сценарий красным. Если вся
+батарея остаётся зелёной, семантика OOM не проверяется.
+
+## Как строится N+1-гейт
+
+Один статический поиск `select_related` ничего не доказывает. Арбитр должен наблюдать полный
+операционный путь.
+
+1. Создать больше одного связанного объекта; для list endpoint обычно нужны десятки строк.
+2. Выполнить настоящий HTTP-запрос или функцию задачи.
+3. Зафиксировать постоянный максимум SQL, а не `текущее число + 1`.
+4. Увеличить объём fixture и проверить, что число запросов не растёт линейно.
+5. Запускать тест в общей блокирующей батарее.
+
+Django официально предоставляет `assertNumQueries`. Для pytest допустима обёртка с верхним
+пределом, если она печатает выполненные запросы при превышении. Direct SQL, Trino и внешние базы
+нуждаются в своём счётчике — ORM-инструмент не видит их по построению.
+
+Честная граница: наличие двадцати одного budget-теста не доказывает покрытие двадцать второй ручки.
+Отдельный coverage-gate возможен только тогда, когда проект умеет машинно определить множество
+ручек, для которых budget обязателен. Проверять слово в имени теста недостаточно.
+
+## Два инварианта Celery
+
+### Очередь имеет потребителя
+
+Сопоставляются три факта:
+
+- очереди, объявленные в настройках;
+- очереди, используемые routes, task decorators и `apply_async`;
+- очереди, которые реально слушают production workers.
+
+Новая очередь без consumer красит CI. Документ или диаграмма не являются источником истины.
+
+### Доставка не опережает hard timeout
+
+Redis visibility timeout определяет, когда неacknowledged message возвращается в очередь. Если
+задача законно выполняется дольше, второй worker может получить её повторно. Проектный гейт
+сравнивает отношения настроек и fail-closed обрабатывает неразрешимые значения.
+
+Это не универсальная формула для всех Celery-систем: ETA/retry и принудительное завершение
+создают обратную цену слишком большого timeout. Инвариант должен учитывать модель задач проекта.
+
+## Метрика и алерт — это цепочка, а не файл
+
+Полный путь выглядит так:
+
+```text
+код публикует имя
+  → exporter его принимает
+  → Prometheus scrape видит ряд
+  → правило вычисляется правильно
+  → Alertmanager маршрутизирует
+  → человек получает сообщение
+  → runbook говорит, что делать
+```
+
+Для каждого шва нужен свой арбитр. Unit-test publisher не доказывает scrape. `promtool check`
+не доказывает смысл выражения. Тест выражения не доказывает, что production загрузил новый файл.
+После deploy полезна read-only сверка repo rule names с Prometheus API.
+
+## Нагрузочный гейт и soak
+
+Короткий mixed scenario должен иметь код возврата и одновременно держать:
+
+- error rate;
+- p95 ключевых пользовательских путей;
+- throughput или время разбора очередей;
+- суммарный working set флота;
+- отсутствие OOM/restart;
+- при необходимости соединения PostgreSQL и rejected writes Redis.
+
+Короткий прогон не ловит медленную утечку. Soak запускается отдельно и реже, с теми же
+инвариантами, но с проверкой тренда памяти, соединений и очередей во времени. Смешивать soak с
+каждым pre-push нельзя: дорогой гейт начнут обходить.
+
+## Где здесь агент
+
+Агент не должен решать, случилась ли аномалия. Сначала детерминированный detector:
+
+```text
+Prometheus rule или baseline script
+  → фильтрация и группировка события
+  → краткоживущий read-only агент
+  → гипотеза + evidence + confidence + связанный deploy
+  → issue / intent / merge request
+  → решение человека
+```
+
+По расписанию работает baseline script. Модель вызывается только по нарушению полосы. На первом
+этапе ей достаточно read-only доступа к Prometheus, Loki, error tracker и истории deploy; права
+на production DB, Docker socket, merge и произвольный runbook не нужны.
+
+## Как подключать это через AQK без дублей
+
+AQK-манифест объявляет **существующую команду проекта**:
+
+```yaml
+gates:
+  project-verify: "bash scripts/verify.sh"
+  prometheus-rules: "docker run --rm ... promtool test rules alerts_test.yml"
+groups:
+  code: [project-verify]
+  observability: [prometheus-rules]
+```
+
+Внутренние шаги `project-verify` не перечисляются второй раз в манифесте. При падении агрегатор
+обязан назвать конкретный шаг. Отдельным gate становится только команда, которую агрегатор
+честно не запускает.
+
+Один gate AQK получает не больше пяти минут. Если полный verifier проекта дольше, в манифесте
+нужен его быстрый блокирующий режим, а `--full` — отдельный прямой или CI-прогон. Иначе AQK будет
+честно возвращать «не смог проверить: timeout», но интеграция не станет рабочим локальным gate.
+
+Не надо:
+
+- копировать project-specific Python checks в `kit/gates`;
+- объявлять grep по словам `memory` или `assertNumQueries` доказательством;
+- указывать похожий каталог как `samples`, если структура AQK red/green там отсутствует;
+- повышать уровень AQK заглушками;
+- запускать `aqk init --force` поверх зрелого корпуса правил без review.
+
+Новая запись каталога AQK появляется после трёх доказательств: устойчиво опознаваемая конструкция,
+red/green samples и переносимый рецепт с понятной границей ложных срабатываний. До этого это
+методика или собственный gate проекта — и это честное состояние.
+
+## Порядок для нового проекта
+
+1. До кода записать измеримые AC: SQL, p95, error rate, memory, очередь, идемпотентность.
+2. Быструю детерминированную статику поставить в pre-commit.
+3. Query и task budgets поставить в обычный CI.
+4. Compose limits и alert rules проверять нативными валидаторами.
+5. Mixed load запускать nightly и перед релизом; soak — отдельно, например еженедельно.
+6. Любой OOM сделать красным исходом и сохранить причину после смерти контейнера.
+7. Только после стабилизации сигналов подключать read-only агента к нескольким critical alerts.
+
+## Официальные источники
+
+- [Django 5.2: `assertNumQueries`](https://docs.djangoproject.com/en/5.2/topics/testing/tools/#django.test.TransactionTestCase.assertNumQueries)
+- [Prometheus: unit testing rules через `promtool`](https://prometheus.io/docs/prometheus/latest/configuration/unit_testing_rules/)
+- [cAdvisor: Prometheus metrics, включая `container_oom_events_total`](https://github.com/google/cadvisor/blob/master/docs/storage/prometheus.md)
+- [Docker Compose: resource limits](https://docs.docker.com/reference/compose-file/deploy/#resources)
+- Docker про то, что сумма отдельных limits не гарантирует запас хоста — дословно:
+  «Using `--reserve-memory` and `--limit-memory` does not guarantee that Docker will not use more
+  memory on your host than you want», страница
+  [`docker service create`](https://docs.docker.com/reference/cli/docker/service/create/).
+  Якорь раздела не указан намеренно: страница собирается на стороне браузера, и проверить
+  существование якоря запросом нельзя — а ссылка на несуществующий якорь молча ведёт наверх.
+- [Celery Redis: visibility timeout и redelivery](https://docs.celeryq.dev/en/main/getting-started/backends-and-brokers/redis.html#visibility-timeout)
+
+## Финальный принцип
+
+> Сначала детерминированный сигнал и ограничение. Потом агент. Никогда наоборот.
+
+Повторившаяся ошибка должна оставлять после себя не ещё один абзац, а арбитр с кодом возврата.
+Если переносимого арбитра пока нет, граница называется вслух — текст не получает фальшивое имя
+«гейт».

package/kit/gates/_target.sh

@@ -0,0 +1,53 @@
+# Общий шов для проверок, судящих ПУТЬ, взятый из текста.
+#
+# ЗАЧЕМ ЭТОТ ФАЙЛ. Замеры 14-15 сентября 2026 по 290 чужим репозиториям нашли у нас двенадцать
+# ложных срабатываний. Разбор показал, что это не двенадцать ошибок, а ОДНА, повторённая
+# двенадцатью способами: мы судили строку как путь на диске, не зная, чем она разрешается.
+# Разрешало её то, чего у нас нет, — адрес на github.com, переменная окружения, генератор сайта,
+# соседний репозиторий вики, проза вокруг.
+#
+# Чинить такое по одному значит растить в каждом гейте свой список исключений; через три правки
+# списки разойдутся, и дважды пойманная беда вернётся через тот гейт, куда её не дописали.
+# Поэтому решение одно и здесь.
+#
+# ТРИ ИСХОДА, А НЕ ДВА — тот же договор, что у всего комплекта:
+#   disk        путь ведёт на файл в этом каталоге, судить можно
+#   unresolved  разрешается чем-то, чего у нас нет: МОЛЧАТЬ НЕЛЬЗЯ, но и обвинять нельзя
+#   skip        не путь вовсе (сеть, почта, якорь) — говорить не о чем
+
+# Якорь и строка запроса — не часть имени файла. `assets/x.gif?raw=1` лежит на диске как
+# `assets/x.gif`, `tutorial/#install` — это адрес страницы. Чистится ЗДЕСЬ, а не у зовущего:
+# иначе каждый гейт будет чистить по-своему, и один забудет.
+clean_target() {
+  T="${1%%#*}"
+  printf '%s' "${T%%\?*}"
+}
+
+# Возвращает слово исхода, а для unresolved — ещё и причину через двоеточие.
+classify_target() {
+  T="$1"
+  case "$T" in
+    ""|\#*) echo "skip"; return ;;
+    # ЛЮБАЯ СХЕМА, В ЛЮБОМ РЕГИСТРЕ. Замер 2026-09-15: `file://Users/...` и
+    # `Https://conventionalcommits.org` с заглавной H объявлены битыми файлами. Раньше узнавались
+    # только `http://` и `https://` строчными — и это была догадка о том, как люди пишут.
+    *://*|mailto:*|MAILTO:*) echo "skip"; return ;;
+    # Адрес почты целью ссылки без «mailto:». Замер: три таких объявлены битыми файлами.
+    *@*.*) echo "skip"; return ;;
+  esac
+  case "$T" in
+    # Путь, уходящий выше корня: так сам GitHub предлагает ссылаться на выпуски и задачи —
+    # `../../releases` считается от адреса файла в вебе. Проверено: страница отдаёт 200.
+    ../*) echo "unresolved:адрес на github.com" ;;
+    # Путь от корня САЙТА, а не репозитория.
+    /*) echo "unresolved:адрес на github.com" ;;
+    # Страница вики живёт в отдельном репозитории `<репо>.wiki`, которого мы не скачиваем.
+    wiki/*) echo "unresolved:вики в отдельном репозитории" ;;
+    # Путь с косой чертой на конце и страница `.html` — это адрес опубликованного сайта:
+    # mkdocs, docusaurus, pkgdown собирают их при публикации. Проверено: 200 на их сайтах.
+    */|*.html|*.htm) echo "unresolved:страницу собирает генератор сайта" ;;
+    # Нераскрытая переменная: значение задаётся снаружи.
+    *'$'*) echo "unresolved:путь зависит от переменной" ;;
+    *) echo "disk" ;;
+  esac
+}

package/kit/gates/ci-actually-fails/check.sh

@@ -90,6 +90,12 @@ for F in $CI; do
       for (j = 1; j <= nr; j++) if (R[j] != "" && R[j] == id) return 1
       return 0
     }
+    # Погашенная команда, о которой ещё не решено. Печатается, когда стало видно, что после неё
+    # в блоке ничего нет: тогда исход шага действительно погашен.
+    function reportMask(   ) {
+      if (maskLine) printf "%s:%d: провал погашен прямо в команде: %s\n", file, maskLine, substr(maskText, 1, 90)
+      maskLine = 0
+    }
     function flush(   ) {
       if (blockStart && blockCheck && blockMask && !isRedeemed(blockId))
         printf "%s:%d: проверка не может провалиться — шаг под %s\n", file, blockCheckLine, blockMaskText
@@ -100,8 +106,17 @@ for F in $CI; do
       # вспомогательной команде внутри скрипта (`docker network create … || true`) — это
       # идемпотентность, а не выключенная проверка.
       if (!isComment($0) && $0 ~ runners && $0 ~ /\|\|[[:space:]]*(true|:|exit[[:space:]]+0)/) {
-        line = $0; sub(/^[[:space:]]+/, "", line)
-        printf "%s:%d: провал погашен прямо в команде: %s\n", file, NR, substr(line, 1, 90)
+        # ОБВИНЯЕМ, ТОЛЬКО ЕСЛИ ПОГАШЕННАЯ КОМАНДА — ПОСЛЕДНЯЯ В БЛОКЕ. Замер 2026-09-14 по
+        # семидесяти чужим конвейерам дал одно-единственное срабатывание, и оно было ЛОЖНЫМ:
+        # `pnpm eslint src > out.txt || true` строкой ниже сверяется `diff` с эталоном —
+        # инструмент ОБЯЗАН выйти ненулевым, а вердикт выносит следующая команда. Шаг
+        # проваливается прекрасно. Инструмент, который обвиняет напрасно, выключают целиком,
+        # поэтому здесь молчание честнее догадки.
+        maskLine = NR; maskText = $0; sub(/^[[:space:]]+/, "", maskText)
+      } else if (maskLine && !isComment($0) && $0 !~ /^[[:space:]]*$/) {
+        # Печать вердикта не выносит: `echo` после гашения ничего не меняет.
+        if ($0 ~ /^[[:space:]]*(-[[:space:]]+)?[A-Za-z0-9_.-]+[[:space:]]*:/) reportMask()
+        else if ($0 !~ /^[[:space:]]*(echo|printf|cat|ls)[[:space:]]/) maskLine = 0
       }
       if (isBoundary($0)) flush()
       if (!blockStart) blockStart = NR
@@ -111,7 +126,7 @@ for F in $CI; do
         blockId = $0; sub(/^[^:]*:[[:space:]]*/, "", blockId); gsub(/[[:space:]"'"'"']/, "", blockId)
       }
     }
-    END { flush() }' 2>/dev/null)
+    END { reportMask(); flush() }' 2>/dev/null)
   [ -z "$RES" ] || BAD="$BAD$RES
 "
 done

package/kit/gates/ci-actually-fails/green/.github/workflows/ci.yml

@@ -28,3 +28,13 @@ jobs:
       - name: провалить сборку, если линтер был красным
         if: steps.lint.outcome == 'failure'
         run: exit 1
+
+      # ЗАКОННОЕ ГАШЕНИЕ: инструмент ОБЯЗАН выйти ненулевым, а вердикт выносит следующая
+      # команда того же блока. Найдено замером 2026-09-14 по семидесяти чужим конвейерам:
+      # это было ЕДИНСТВЕННОЕ срабатывание гейта на всём замере — и оно оказалось ложным
+      # (HorusGoul/eslint-plugin-react-render-types, .github/workflows/ci.yml:51). Снимок
+      # вывода линтера сверяется с эталоном, шаг проваливается на `diff`.
+      - name: линтер как снимок
+        run: |
+          pnpm eslint src > /tmp/lint-output.txt || true
+          diff lint-snapshot.txt /tmp/lint-output.txt

package/kit/gates/entry-commands-exist/check.sh

@@ -41,12 +41,28 @@ ENTRIES=$( { find "$DIR" -maxdepth 1 -type f \( -iname 'agents.md' -o -iname 'cl
 # --- что в проекте есть ---------------------------------------------------------
 # Скрипты — только из блока "scripts" каждого package.json (рабочие пространства тоже: команда
 # из свода часто живёт в пакете, а не в корне). Файл склеивается в строку: блок бывает и в одну.
-SCRIPTS=$(find "$DIR" $(skip_find) -type f -name package.json -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$' \
-  | while IFS= read -r P; do
-      tr '\r\n' '  ' < "$P" | sed -n 's/.*"scripts"[[:space:]]*:[[:space:]]*{\([^}]*\)}.*/\1/p' \
-        | grep -oE '"[^"]+"[[:space:]]*:' | sed 's/^"//; s/"[[:space:]]*:$//'
-    done)
+# ИМЕНА СКРИПТОВ ЧИТАЕТ РАЗБОРЩИК JSON, А НЕ РЕГУЛЯРКА. Найдено 2026-09-15 на
+# `jantimon/web-performance-debugger`: их скрипт `prebuild` содержит
+# `rmSync('dist',{recursive:true,force:true})` — фигурная скобка ВНУТРИ значения. Прежний разбор
+# `[^}]*` обрывался на ней, и шесть существующих скриптов объявлялись несуществующими. Письмо
+# ушло бы живому человеку с неправдой.
+#
+# Структуру разбирает тот, кто умеет её разбирать. `package.json` означает проект на Node, и node
+# там почти наверняка есть; но «почти» нам не годится — без него мы НЕ ПРОВЕРЯЕМ скрипты и
+# говорим об этом, а не додумываем регуляркой.
+NPM_BLIND=""
+if command -v node >/dev/null 2>&1; then
+  SCRIPTS=$(find "$DIR" $(skip_find) -type f -name package.json -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$' \
+    | while IFS= read -r P; do
+        node -e 'try{const s=require("fs").readFileSync(process.argv[1],"utf8");const j=JSON.parse(s);for(const k of Object.keys(j.scripts||{}))console.log(k)}catch(e){}' "$P"
+      done)
+else
+  SCRIPTS=""
+  NPM_BLIND=1
+fi
 HAS_PKG=$(find "$DIR" $(skip_find) -type f -name package.json -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$' | head -1)
+HAS_JUST=$(find "$DIR" $(skip_find) -type f \( -name justfile -o -name Justfile -o -name .justfile \) -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$' | head -1)
+HAS_MK=$(find "$DIR" $(skip_find) -type f \( -name Makefile -o -name makefile -o -name GNUmakefile -o -name '*.mk' \) -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$' | head -1)
 
 # Цели make: строка вне рецепта, слова до двоеточия; «VAR := x» — присваивание, не цель.
 TARGETS=$(find "$DIR" $(skip_find) -type f \( -name Makefile -o -name makefile -o -name GNUmakefile -o -name '*.mk' \) -print 2>/dev/null \
@@ -54,11 +70,35 @@ TARGETS=$(find "$DIR" $(skip_find) -type f \( -name Makefile -o -name makefile -
       awk '/^[^\t#][^=]*:([^=]|$)/ { sub(/:.*/, ""); n = split($0, a, /[ \t]+/); for (i = 1; i <= n; i++) if (a[i] != "") print a[i] }' "$M"
     done)
 
+# ПОДКЛЮЧЁННЫЙ ФАЙЛ, КОТОРОГО У НАС НЕТ, ДЕЛАЕТ ПЕРЕЧЕНЬ ЦЕЛЕЙ НЕПОЛНЫМ. Найдено 2026-09-15 на
+# `exoscale/cli`: их Makefile начинается с `include go.mk/init.mk`, а `go.mk` — подмодуль git,
+# которого в клоне нет. Цели `build` и `test-verbose` объявлены там, и наше «такой цели нет» было
+# бы письмом с неправдой в живую компанию.
+#
+# Молчим ОБО ВСЕХ целях make, а не о конкретной: какая именно объявлена в неподключённом файле,
+# мы знать не можем. Это третий исход — «не смогли проверить», и он назван вслух, а не спрятан.
+MK_BLIND=""
+for M in $(find "$DIR" $(skip_find) -type f \( -name Makefile -o -name makefile -o -name GNUmakefile -o -name '*.mk' \) -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$'); do
+  for INC in $(sed -n 's/^[[:space:]]*-\{0,1\}include[[:space:]]\{1,\}//p' "$M" 2>/dev/null | tr ' ' '\n' | grep -v '^$'); do
+    case "$INC" in
+      *'$'*) continue ;;
+    esac
+    [ -e "$(dirname "$M")/$INC" ] || MK_BLIND="$MK_BLIND$INC
+"
+  done
+done
+
 # Рецепты just: «имя:», «@имя арг:», «alias имя := …».
 RECIPES=$(find "$DIR" $(skip_find) -type f \( -name justfile -o -name Justfile -o -name .justfile \) -print 2>/dev/null \
   | own_samples_filter "$DIR" | grep -v '^$' | while IFS= read -r J; do
+      # ПАРАМЕТР РЕЦЕПТА СОДЕРЖИТ ЗНАК РАВЕНСТВА. Найдено 2026-09-15 на `2mawi2/para`: их
+      # `release BUMP="patch":` — обычный рецепт со значением по умолчанию. Прежнее правило
+      # требовало `[^:=]*` до двоеточия и такой рецепт не видело: существующая команда
+      # объявлялась несуществующей. Присваивание (`version := "1.0"`) отсекается отдельно —
+      # у него двоеточие СРАЗУ перед равенством, а у рецепта равенство стоит до двоеточия.
       awk '/^alias[ \t]+/ { print $2; next }
-           /^@?[A-Za-z_][A-Za-z0-9_-]*([ \t][^:=]*)?:([^=]|$)/ { sub(/^@/, ""); sub(/[ \t:].*/, ""); print }' "$J"
+           /^@?[A-Za-z_][A-Za-z0-9_-]*[ \t]*:=/ { next }
+           /^@?[A-Za-z_][A-Za-z0-9_-]*([ \t][^:]*)?:/ { sub(/^@/, ""); sub(/[ \t:].*/, ""); print }' "$J"
     done)
 
 has() { printf '%s\n' "$2" | grep -qxF -- "$1"; }
@@ -82,20 +122,41 @@ while IFS= read -r E; do
   CODE=$(awk '/^[ \t]*(```|~~~)/ { f = !f; next }
     f { print; next }
     { while (match($0, /`[^`]+`/)) { print substr($0, RSTART + 1, RLENGTH - 2); $0 = substr($0, RSTART + RLENGTH) } }' "$E")
-  grep -oE '(npm|pnpm|yarn|bun)[[:space:]]+run[[:space:]]+[A-Za-z][A-Za-z0-9_:.-]*[*<{]?' "$E" \
-    | grep -v '[*<{:]$' | sed 's/\.$//; s/[[:space:]][[:space:]]*/ /g' | sort -u > "$TMP"
+  # «BUN RUN <ФАЙЛ>» — ЗАПУСК ФАЙЛА, А НЕ СКРИПТА. Найдено 2026-09-15 на `Gerstep/HumanCompiler`:
+  # `bun run scripts/generate-plugin.ts <profile>` — путь прочитался как имя скрипта «scripts».
+  # Отсекаем по признаку пути: косая черта или расширение исполняемого файла.
+  grep -oE '(npm|pnpm|yarn|bun)[[:space:]]+run[[:space:]]+[A-Za-z][A-Za-z0-9_:./-]*[*<{]?' "$E" \
+    | grep -v '[*<{:]$' | grep -vE '[[:space:]][A-Za-z0-9_.-]*/' \
+    | grep -vE '\.(ts|js|mjs|cjs|tsx|jsx|py|sh)$' \
+    | sed 's/\.$//; s/[[:space:]][[:space:]]*/ /g' | sort -u > "$TMP"
   while IFS= read -r CMD; do
+    # Без разборщика JSON перечень скриптов неполон, и «такого скрипта нет» — догадка.
+    [ -n "$NPM_BLIND" ] && continue
     N=${CMD##* }
     has "$N" "$SCRIPTS" && continue
-    if [ -n "$HAS_PKG" ]; then report "$E" "$CMD" "такого скрипта нет ни в одном package.json"
-    else report "$E" "$CMD" "package.json в репозитории нет вовсе"; fi
+    # СОБСТВЕННОЙ СБОРКИ У РЕПОЗИТОРИЯ НЕТ — значит свод, скорее всего, описывает ДРУГОЙ проект.
+    # Найдено 2026-09-15 на `Aurealibe/claude-config` и `Weaverse/.agents`: это сборники правил,
+    # которые ставят в проект-получатель, и своего package.json у них нет и не должно быть.
+    # Про какой проект написано «npm run build», снаружи не видно — обвинять нельзя.
+    [ -n "$HAS_PKG" ] || { NO_BUILD=1; continue; }
+    report "$E" "$CMD" "такого скрипта нет ни в одном package.json"
   done < "$TMP"
-  for N in $(printf '%s\n' "$CODE" | grep -E '(^|[^A-Za-z0-9_-])make[[:space:]]' | grep -vE -- '-C|--directory|-f[[:space:]]|--file' \
+  # «MAKE» — ОБЫЧНЫЙ АНГЛИЙСКИЙ ГЛАГОЛ, как и «just». Найдено 2026-09-15 на
+  # `andyhartzler/my-bluebubbles-web`: «make it go away», «make one of these go away» дали цели
+  # «it» и «one». У них выше по файлу незакрытый блок кода, и весь текст после него читается как
+  # команды — но чинить надо не разбор блоков, а предмет обвинения: Makefile в репозитории нет
+  # вовсе, сравнивать не с чем.
+  [ -n "$HAS_MK" ] && for N in $(printf '%s\n' "$CODE" | grep -E '(^|[^A-Za-z0-9_-])make[[:space:]]' | grep -vE -- '-C|--directory|-f[[:space:]]|--file' \
       | grep -oE '(^|[^A-Za-z0-9_-])make([[:space:]]+-[A-Za-z0-9]+)*[[:space:]]+[A-Za-z][A-Za-z0-9_.-]*=?' \
       | grep -v '=$' | sed 's/.*[[:space:]]//' | sort -u); do
+    [ -n "$MK_BLIND" ] && continue
     has "$N" "$TARGETS" || report "$E" "make $N" "такой цели нет ни в одном Makefile"
   done
-  for N in $(printf '%s\n' "$CODE" | grep -oE '(^|[^A-Za-z0-9_-])just[[:space:]]+[A-Za-z][A-Za-z0-9_-]*' \
+  # «JUST» — ОБЫЧНОЕ АНГЛИЙСКОЕ СЛОВО, и в прозе оно стоит чаще, чем в роли запускалки. Найдено
+  # 2026-09-15: «I just uploaded a new video» и «fuzzy output (`just over`)» дали находки
+  # «рецепт uploaded» и «рецепт over» в репозиториях, где justfile нет вовсе. Без justfile
+  # сравнивать не с чем — обвинение без предмета.
+  [ -n "$HAS_JUST" ] && for N in $(printf '%s\n' "$CODE" | grep -oE '(^|[^A-Za-z0-9_-])just[[:space:]]+[A-Za-z][A-Za-z0-9_-]*' \
       | sed 's/.*[[:space:]]//' | sort -u); do
     has "$N" "$RECIPES" || report "$E" "just $N" "такого рецепта нет в justfile"
   done
@@ -107,4 +168,19 @@ if [ "$MISS" = 1 ]; then
   echo "  почини: верни команду в проект или исправь свод. Агент берёт команды из свода дословно:"
   echo "  несуществующая команда — это «Missing script» у агента и «проверил» про проверку, которой нет."
 fi
+# ЧТО МЫ НЕ СМОГЛИ ПОСМОТРЕТЬ — говорится вслух и при находках, и без них. Молчание здесь
+# означало бы «цели make проверены», а они не проверены вовсе.
+if [ -n "$NO_BUILD" ]; then
+  echo "  не проверено: команды npm. Своего package.json у репозитория нет — похоже, свод описывает"
+  echo "    другой проект, в который его ставят. Про какой именно, снаружи не видно."
+fi
+if [ -n "$NPM_BLIND" ]; then
+  echo "  не проверено: скрипты npm. Разобрать package.json нечем — на этой машине нет node."
+  echo "    почини: поставь node либо прогони проверку там, где он есть."
+fi
+if [ -n "$MK_BLIND" ]; then
+  echo "  не проверено: цели make. Makefile подключает файлы, которых нет в этом каталоге:"
+  printf '%s' "$MK_BLIND" | sort -u | sed 's/^/    /'
+  echo "    обычно это подмодуль git — тогда проверять надо там, где он выгружен."
+fi
 exit "$MISS"

package/kit/gates/hook-actually-fires/README.md

@@ -5,6 +5,18 @@
 линтером. Ошибку в имени события Claude Code **не показывает** — хук просто никогда не
 вызывается. Настройка выглядит как защита и защитой не является.
 
+**Третий класс, добавленный 2026-09-14 — и нашёл его чужой инструмент.** `agnix`, прогнанный по
+нашему же репозиторию, сказал «Script file not found» о **шести** хуках в нашем **зелёном**
+образце: гейт с именем «хук правда срабатывает» говорил «чисто» о настройке, где ни один хук
+сработать не мог, потому что ни одного из шести файлов не существовало. Теперь команда хука
+сверяется с диском.
+
+Граница узкая: красится только **относительный путь со слэшем** (`.claude/hooks/x.sh`,
+`scripts/guard.sh`). Программа из PATH (`npx`, `prettier`, `bash -c …`) не судится — у неё нет
+пути, и «не нашли» было бы обвинением по догадке. Абсолютный путь пропускается: он про чужую
+машину, а не про этот репозиторий. `$CLAUDE_PROJECT_DIR` снимается как приставка — это и есть
+корень проекта.
+
 **Какой отказ это поймало.** Замер по 48 чужим настройкам `.claude/settings.json`, снятым с
 GitHub 2026-09-07. Шесть настоящих находок в четырёх репозиториях: