agent-quality-kit 0.15.0 → 0.16.0

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

@@ -1,33 +0,0 @@
-#!/usr/bin/env sh
-# Каждая ссылка на локальный файл из markdown-файлов каталога обязана вести на
-# существующий файл. Ссылка в никуда — это документ, утверждающий защиту,
-# которой нет: планирование опирается на неё и ломается молча.
-DIR="${1:-.}"
-MISS=0
-for MD in "$DIR"/*.md; do
-  [ -f "$MD" ] || continue
-  # вытащить цели ссылок вида [текст](путь)
-  # Строки со вставками в обратных кавычках чистятся ДО разбора: «`[name](url)`» — это пример
-  # оформления ссылки, а не ссылка. Замер 2026-09-08: в uv/STYLE.md именно так и было, и гейт
-  # требовал создать файл с именем «url».
-  TARGETS=$(sed 's/`[^`]*`//g' "$MD" | sed -n 's/.*](\([^)]*\)).*/\1/p')
-  for T in $TARGETS; do
-    # автоссылки бывают обёрнуты как <(https://...)> — искать http где угодно внутри,
-    # не только в начале строки.
-    case "$T" in *http://*|*https://*|\#*|mailto:*) continue ;; esac
-    T=${T%%#*}
-    [ -z "$T" ] && continue
-    # Путь, кончающийся косой чертой, — адрес страницы опубликованного сайта, а не файл на
-    # диске. Так ссылаются mkdocs, docusaurus и jekyll: `[руководство](tutorial/#install)`
-    # работает у читателя и не существует в репозитории. Найдено замером по fastapi — гейт
-    # объявлял битой рабочую ссылку из их README. Проверять такие адреса умеют lychee и
-    # markdown-link-check: они ходят в сеть, а мы смотрим только на диск.
-    case "$T" in */) continue ;; esac
-    if [ ! -e "$DIR/$T" ]; then
-      echo "$MD: ссылка в никуда — $T"
-      echo "  почини: создай файл или убери ссылку. Документ, обещающий несуществующее, хуже отсутствующего."
-      MISS=1
-    fi
-  done
-done
-exit $MISS

package/kit/gates/entry-links-exist/gate.yml

@@ -1,17 +0,0 @@
-# Запись каталога AQK. Норма и все поля — kit/gates/README.md.
-# Читается программой; всё, что нельзя выполнить, живёт в README.md рядом.
-
-intent: файлы, на которые ссылается точка входа, существуют на диске
-intent_en: files the entry point links to actually exist on disk
-
-# Когда запись показывается человеку. Отсутствие триггера сделало бы её шумом
-# для тех, кого она не касается.
-trigger:
-  always: true
-
-# Команда-арбитр под каждый стек. {dir} — каталог, который проверяют.
-# `any` — команда без зависимостей, работает везде, где есть sh и grep.
-recipes:
-  any: bash {gate}/check.sh {dir}
-
-proof: incidents/README.md — «2026-08-24 документ четыре недели утверждал защиту, которой не было»

package/kit/gates/entry-links-exist/green/AGENTS.md

@@ -1,10 +0,0 @@
-# Свод правил
-
-Стандарты: [общие правила](rules/general.md).
-Внешняя ссылка: [semver](https://semver.org).
-Автоссылка в скобках, как в CHANGELOG.md gin: [#1](<(https://example.com/pull/1)>).
-Ссылка на страницу сайта документации: [руководство](tutorial/#install) — путь опубликованного
-сайта, а не файл на диске. Найдено замером по fastapi: `[installation guide](tutorial/#install-fastapi)`
-в README читалась как битая, хотя на сайте работает. Так ссылаются mkdocs, docusaurus и jekyll.
-
-Пример оформления ссылки: `[name](url)` — это пример, а не ссылка.

package/kit/gates/entry-links-exist/green/rules/general.md

@@ -1,3 +0,0 @@
-# Общие правила
-
-Пусто, но файл существует.

package/kit/gates/entry-links-exist/red/AGENTS.md

@@ -1,3 +0,0 @@
-# Свод правил
-
-Стандарты: [общие правила](rules/nope.md).

package/kit/gates/no-phantom-package/README.md

@@ -1,84 +0,0 @@
-# Пакета с таким именем нет в реестре
-
-**Намерение.** Агент, не знающий инструмента, придумывает правдоподобное имя: `reactCodemodHelper`,
-`eslint-plugin-async-safe`, `@types/fetch-retry`. Имя попадает в `AGENTS.md`, в `SKILL.md`, в
-пример из README. Дальше его читает следующий агент — человек или машина — и выполняет
-`npm install`. Если к тому времени имя занято, в проект приезжает чужой код.
-
-**Какой отказ это поймало.** README самого `slopcheck` открывается историей: модель написала
-команду `npx` с именем `react-codeshift` в 47 файлах, пакета не существовало, кто-то его
-зарегистрировал, и 237 репозиториев уже на него ссылались. Имя намеренно оторвано здесь от слова
-`npx`: иначе эта строка стала бы находкой самой записи, а вердикт на `main` зависел бы от того,
-не снимет ли реестр захваченный пакет с публикации. Красный образец выбирается так, чтобы его
-нельзя было погасить снаружи, — и текст вокруг него тоже. Мы проверили этот пакет 2026-09-08:
-
-```
-react-codeshift  1.0.0  создан 2026-01-14  maintainer: debugducky
-```
-
-Доля: по [USENIX Security 2025](https://arxiv.org/abs/2406.10279) около 20% сгенерированного
-кода ссылается на несуществующие пакеты, и 58% выдуманных имён повторяются от запроса к
-запросу — то есть предсказуемы для того, кто захочет их занять.
-
-**Почему машина, а не внимательность.** Отличить `jscodeshift` от `reactCodemodHelper` глазами
-нельзя: оба выглядят как настоящие. Единственный арбитр — реестр.
-
-**Готовый аналог есть, и мы его зовём.**
-[`slopcheck`](https://github.com/mattschaller/slopcheck) (npm, MIT, ноль зависимостей) достаёт
-имена из команд установки в `.md`, `.mdc`, `.yml`, `.yaml`, `.json`, `.cursorrules` и сверяет с
-`registry.npmjs.org`. Своего разбора мы не писали. Обёртка отвечает за три вещи, которых он не
-делает: какие файлы ему дать (иначе он находит наши собственные образцы), что считать браком и
-что делать, когда реестр не ответил.
-
-**Почему обёртка, а не прямой вызов.** Без сети `slopcheck` печатает `? имя — validation error`
-и выходит **с нулём**. Для гейта это худший из возможных ответов: сборка зелёная, а не проверено
-ничего — ровно та тишина, ради запрета которой существует весь стандарт. Обёртка в этом случае
-выходит с кодом **2** и говорит «проверка не состоялась», отдельно от вердикта «брак».
-Тот же код — если счётчик находок ненулевой, а разобрать их не вышло: значит `slopcheck` сменил
-формат вывода, и молчать об этом нельзя. И тот же — если блока со счётчиками в ответе не нашлось
-вовсе: так будет, если он начнёт печатать JSON одной строкой. Эту ветку нашли прогоном
-подставного вывода **после** того, как написали «формат стабилен»: без неё все счётчики
-оставались нулями и гейт выходил с нулём, не проверив ничего.
-
-**Образцы.** В `red/AGENTS.md` кодмод вызван именем `reactCodemodHelper`. Имя выбрано не наугад: `npm`
-запрещает заглавные буквы в именах новых пакетов, и это подтверждает та же библиотека, которой
-пользуется реестр:
-
-```
-$ node -e "console.log(require('validate-npm-package-name')('reactCodemodHelper'))"
-validForNewPackages: false   errors: [ 'name can no longer contain capital letters' ]
-```
-
-Значит образец не сможет протухнуть: занять это имя нельзя никому, а выглядит оно как настоящая
-галлюцинация — модели постоянно пишут camelCase. `green/AGENTS.md` — тот же файл, где кодмод
-назван настоящим именем `jscodeshift`. Второй пакет, `prettier`, стоит в обоих: он показывает,
-что зелёным гейт становится не от пустоты.
-
-**Чего НЕ ловит.**
-
-- **Пакет, который сквоттер уже зарегистрировал.** Проверка спрашивает у реестра только «есть
-  ли», и гаснет ровно в тот момент, когда становится опасно: `react-codeshift` сегодня зелёный.
-  Это предел приёма, а не недоделка — «есть ли пакет» и «чей он» разные вопросы, и второй
-  решают Socket и Snyk, которых мы не дублируем. Смысл записи в другом: до регистрации проходит
-  время, и большинство выдуманных имён так и остаются свободными.
-- **Только npm.** PyPI, crates.io, Go-модули не проверяются: `slopcheck` их не умеет, а писать
-  своё — заводить второй разбор команд установки. Питоновский проект, где агент придумал имя
-  пакета, эта запись не прикроет.
-- **Имя из прозы, принятое за пакет.** Разбор берёт слово после `npm i`/`npx`/`yarn add` и
-  спотыкается о текст, где эти слова стоят не как команда. Проверено на README самого
-  `slopcheck`: слово `Commands`, стоящее в прозе после имени команды, даёт находку
-  `Commands — not found on npm`. На
-  нашем репозитории — 89 файлов, 9 имён — ложных нет, но на чужом такое встретится. Первым,
-  кого эта запись покрасила, был её собственный README: имена образцов стояли там рядом с
-  `npx`. Текст переписан, проверка — нет. Ослепить её на README записей каталога значило бы
-  перестать видеть настоящие команды установки, которых там хватает.
-- **Пакет, названный в исходнике, а не в документации.** `import` из несуществующего модуля —
-  предмет сборки, она об этом скажет сама.
-- **Сеть.** Запись — единственная в каталоге, которой нужен интернет. В конвейере без выхода
-  наружу она честно выйдет с кодом 2, а не соврёт зелёным. Тем же кодом отвечает ответ реестра
-  «слишком часто» (HTTP 429): снаружи он неотличим от обрыва связи, и сообщение называет обе
-  причины, а не выбирает одну наугад.
-- **Свой предел времени.** `doctor` даёт гейту 300 секунд, а здесь каждое имя — запрос наружу
-  (до трёх попыток по десять секунд, по десять имён разом). Проект с сотнями команд установки
-  при медленном реестре упрётся в предел и будет показан как `timeout` — не как «проверка не
-  состоялась». Эту разницу изнутри проверки не выразить: её съедает тот, кто её обрывает.

package/kit/gates/no-phantom-package/check.sh

@@ -1,168 +0,0 @@
-#!/usr/bin/env sh
-# Имена пакетов, названные в документации, сверяются с реестром npm.
-#
-# ЗАЧЕМ. Агент, не знающий инструмента, придумывает правдоподобное имя. Дальше его читает
-# другой агент и выполняет `npm install` — и если имя к тому времени кем-то занято, в проект
-# приезжает чужой код. Обычные проверки цепочки поставок смотрят на пакеты, которые ЕСТЬ;
-# здесь опасен как раз тот, которого пока нет.
-#
-# Работу делает slopcheck (MIT, ноль зависимостей). Мы отвечаем за три вещи, которых он не
-# делает: какие файлы ему дать, что считать браком и что делать, когда ответа не было.
-# Каждая ветка «ответа не было» кончается кодом 2 и словами «проверка не состоялась»: у
-# инструмента, написанного против молчаливого зелёного, своего молчаливого зелёного быть не может.
-DIR="${1:-.}"
-
-# Существование файла проверяется ДО `.`, а не запасной веткой после. В POSIX-оболочке (здесь
-# dash) неудачный `.` завершает скрипт немедленно — привычное «. файл || запасной_вариант» не
-# выполняется НИКОГДА, и гейт умирает с кодом 2 без единого слова о причине. Проверено прогоном
-# 2026-09-08; та же мёртвая ветка стоит ещё в девяти проверках каталога.
-SKIP_LIB="$(dirname "$0")/../_skip.sh"
-if [ ! -f "$SKIP_LIB" ]; then
-  echo "рядом с проверкой нет _skip.sh — обход не собран, проверка не состоялась"
-  echo "  почини: скопируй гейт вместе с файлом kit/gates/_skip.sh, он общий на весь каталог"
-  exit 2
-fi
-. "$SKIP_LIB"
-# Файл на месте — этого мало: подмена содержимого давала код 0. Метка стоит в КОНЦЕ _skip.sh,
-# поэтому проверка ловит и обрыв файла на середине.
-if [ "${AQK_SKIP_READY:-}" != 1 ]; then
-  echo "_skip.sh есть, но обход не собрался — проверка НЕ СОСТОЯЛАСЬ, а не прошла"
-  echo "  почини: замени kit/gates/_skip.sh целым файлом из каталога"
-  exit 2
-fi
-
-# Даже когда файл на месте, нужных функций в нём может не оказаться: без них конвейер ниже не
-# напечатает ни одного пути, список окажется пуст, а пустой список — это `exit 0`. Гейт вышел бы
-# зелёным, не посмотрев ни в один файл.
-if ! command -v own_samples_filter >/dev/null 2>&1; then
-  echo "в _skip.sh нет обхода own_samples_filter — проверка не состоялась"
-  echo "  почини: обнови kit/gates/_skip.sh до версии, идущей с этим гейтом"
-  exit 2
-fi
-
-if ! command -v slopcheck >/dev/null 2>&1; then
-  echo "не найден slopcheck — эта проверка делегирована ему"
-  echo "  почини: npm i -g slopcheck@0.2.0"
-  exit 2
-fi
-
-# Свой обход, а не встроенный в slopcheck: только так работает own_samples_filter. Без него
-# красный образец этой же записи выдаётся за находку, и гейт краснеет на самом комплекте.
-LIST=$(mktemp) || exit 2
-# shellcheck disable=SC2046
-find "$DIR" $(skip_find "$DIR") -type f \
-     \( -name '*.md' -o -name '*.mdc' -o -name '*.yml' -o -name '*.yaml' \
-        -o -name '*.json' -o -name '.cursorrules' \) -print 2>/dev/null \
-  | own_samples_filter "$DIR" > "$LIST"
-
-if [ ! -s "$LIST" ]; then rm -f "$LIST"; exit 0; fi
-
-# Через NUL, а не через $(...): путь с пробелом иначе распадается на два аргумента, slopcheck
-# не находит ни одного из них и молча выходит с нулём. Та же ловушка уже стоила нам зелёного
-# вердикта в hook-actually-fires.
-ERRF=$(mktemp) || { rm -f "$LIST"; exit 2; }
-OUT=$(tr '\n' '\0' < "$LIST" | xargs -0 slopcheck --json 2>"$ERRF")
-# Код xargs: 0 — все вызовы прошли, 123 — хотя бы один вернул 1..125. Именно 123 приходит и на
-# честной находке (slopcheck выходит с 1), поэтому сам по себе он ничего не значит. А вот всё
-# остальное — сбой обвязки, и его нельзя принимать за вердикт.
-XS=$?
-ERR=$(cat "$ERRF" 2>/dev/null)
-rm -f "$ERRF" "$LIST"
-
-# Файлов может оказаться больше, чем влезает в одну команду, и тогда xargs зовёт slopcheck
-# несколько раз. Упавший вызов пишет в stderr, а уцелевшие всё равно печатают свой JSON —
-# счётчики сходятся, и гейт вышел бы с нулём, не проверив целую партию файлов.
-if [ -n "$ERR" ] || { [ "$XS" -ne 0 ] && [ "$XS" -ne 123 ]; }; then
-  echo "slopcheck не отработал (код $XS) — проверка не состоялась, это не вердикт «чисто»"
-  [ -n "$ERR" ] && printf '%s\n' "$ERR" | head -5 | sed 's/^/  /'
-  echo "  почини: прогони «slopcheck --json .» руками и посмотри, на чём он споткнулся"
-  exit 2
-fi
-
-[ -n "$OUT" ] || {
-  echo "slopcheck ничего не ответил — проверка не состоялась, это не вердикт «чисто»"
-  echo "  почини: прогони «slopcheck --json .» руками и посмотри, на чём он споткнулся"
-  exit 2
-}
-
-printf '%s\n' "$OUT" | awk '
-  function val(s) { sub(/^[^:]*:[[:space:]]*/, "", s); sub(/,$/, "", s); gsub(/^"|"$/, "", s); return s }
-  function label(s) {
-    if (s == "not_found")     return "в реестре такого пакета нет"
-    if (s == "unpublished")   return "пакет был и снят с публикации — имя свободно для захвата"
-    if (s == "security_hold") return "реестр пометил пакет как вредоносный"
-    return ""
-  }
-  # xargs может позвать slopcheck несколько раз, если путей слишком много для одной команды.
-  # Тогда JSON-документов на входе будет несколько, и счётчики надо складывать, а не брать
-  # последний: иначе находки первой партии исчезнут.
-  /^  "packages"/            { inpkg = 1; sawpkg = 1; next }
-  inpkg && /^  \}/           { inpkg = 0; next }
-  inpkg && /"errors"/        { errs += val($0); next }
-  inpkg && /"notFound"/      { bad  += val($0); next }
-  inpkg && /"unpublished"/   { bad  += val($0); next }
-  inpkg && /"securityHold"/  { bad  += val($0); next }
-  /^      "package"/         { pkg = val($0); next }
-  /^      "status"/          { st  = val($0); next }
-  /^          "file"/        { f  = val($0); next }
-  /^          "line"/        { ln = val($0); next }
-  # Печатаем на «command»: он идёт последним в записи о месте, значит к этому моменту известны
-  # и пакет, и состояние, и файл со строкой.
-  /^          "command"/ {
-    cmd = val($0)
-    if (st == "error") next
-    # Состояние, которого мы не знаем. Раньше здесь стояло «всё, что не error, — брак», и
-    # новое состояние в следующей версии slopcheck превратило бы КАЖДУЮ команду установки в
-    # находку с английским словом вместо объяснения. Незнакомое состояние — повод сказать
-    # «не разобрали», а не вынести вердикт.
-    if (label(st) == "") { unknown = st; next }
-    if (shown < 20) print f ":" ln ": «" pkg "» — " label(st) " · " cmd
-    shown++
-    next
-  }
-  END {
-    if (unknown != "") {
-      print "slopcheck вернул незнакомое состояние «" unknown "» — разобрать ответ не вышло"
-      print "  почини: сверь версию slopcheck с той, что названа в gate.yml"
-      exit 2
-    }
-    if (shown > 20) print "  … и ещё " (shown - 20)
-    if (shown > 0) {
-      # Находки и «не проверено» показываются вместе. Свернуть второе в первое значило бы
-      # потерять ровно ту разницу, ради которой написана эта обёртка.
-      if (errs > 0) print "  кроме того, реестр не ответил по именам: " errs " — они НЕ проверены"
-      print "  почини: проверь имя в реестре и впиши настоящее. Если пакета нет, его может"
-      print "  зарегистрировать кто угодно — и следующий агент выполнит установку чужого кода."
-      exit 1
-    }
-    # Реестр не ответил. Молчать здесь нельзя: тишина неотличима от «всё хорошо», а именно
-    # это наш стандарт и запрещает. Красим отдельным кодом, чтобы вердикт не путали с браком.
-    # Причина названа обеими: slopcheck помечает так и недоступную сеть, и ответ 429 «слишком
-    # часто», и любой другой не-200 — снаружи они неразличимы, и врать про сеть мы не будем.
-    if (errs > 0) {
-      print "реестр npm не ответил: не проверено имён — " errs
-      print "  проверка не состоялась. Это не вердикт «чисто»."
-      print "  почини: если сети нет — прогони гейт там, где она есть. Если сеть есть, реестр"
-      print "  мог ограничить частоту запросов: повтори через минуту."
-      exit 2
-    }
-    # Блока со счётчиками не нашлось вовсе. Так будет, если slopcheck начнёт печатать JSON
-    # одной строкой: ни одно правило выше не сработает, все счётчики останутся нулями — и
-    # проверка выйдет с нулём, ничего не проверив. Нашли это прогоном подставного вывода уже
-    # после того, как записали «формат стабилен»: догадка о стабильности стоила бы молчаливого
-    # зелёного на каждом прогоне.
-    if (!sawpkg) {
-      print "ответ slopcheck не разобран: блока «packages» в нём нет"
-      print "  почини: сверь версию slopcheck с той, что названа в gate.yml"
-      exit 2
-    }
-    # Счётчик говорит о браке, а печатать нечего — значит мы разучились читать вывод slopcheck
-    # (сменился формат). Тоже не вердикт «чисто».
-    if (bad > 0) {
-      print "slopcheck насчитал находок: " bad ", но разобрать их не вышло — сменился формат"
-      print "  почини: сверь версию slopcheck с той, что названа в gate.yml"
-      exit 2
-    }
-    exit 0
-  }
-'

package/kit/gates/no-phantom-package/gate.yml

@@ -1,20 +0,0 @@
-intent: имя пакета, названное в документации, существует в реестре
-intent_en: a package name mentioned in the documentation exists in the registry
-
-# Там, где агента используют: предмет проверки — текст, который агент читает и по которому
-# выполняет установку. В проекте без такого текста ставить запись незачем.
-trigger:
-  has_agent_entry: true
-
-recipes:
-  any: bash {gate}/check.sh {dir}
-
-# Программа, без которой запись не работает. По первому слову команды этого не видно: обёртка
-# начинается с `bash`, который есть всегда. Версия названа: обёртка разбирает JSON slopcheck,
-# и смена формата обязана быть видимой, а не тихой.
-requires: slopcheck
-
-proof: incidents/README.md, 2026-09-08 «пакет-призрак из чужого README оказался
-  зарегистрирован» — `react-codeshift`, канонический пример slopsquatting из README самого
-  slopcheck, на 2026-09-08 существует в npm (создан 2026-01-14, maintainer debugducky);
-  доля выдуманных имён в сгенерированном коде — USENIX Security 2025, arxiv 2406.10279

package/kit/gates/no-phantom-package/green/AGENTS.md

@@ -1,15 +0,0 @@
-# Правила проекта
-
-## Как чинить импорты
-
-Перед коммитом прогони кодмод:
-
-```bash
-npx jscodeshift --fix src/
-```
-
-## Форматирование
-
-```bash
-npm install prettier
-```

package/kit/gates/no-phantom-package/red/AGENTS.md

@@ -1,15 +0,0 @@
-# Правила проекта
-
-## Как чинить импорты
-
-Перед коммитом прогони кодмод:
-
-```bash
-npx reactCodemodHelper --fix src/
-```
-
-## Форматирование
-
-```bash
-npm install prettier
-```