agent-quality-kit 0.5.0 → 0.7.0

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

@@ -0,0 +1,74 @@
+# Хук агента правда срабатывает
+
+**Намерение.** Человек заводит хук, чтобы машина держала то, что он держать не может: не дать
+сделать `git push --force`, отформатировать после правки, не отпустить работу с красным
+линтером. Ошибку в имени события Claude Code **не показывает** — хук просто никогда не
+вызывается. Настройка выглядит как защита и защитой не является.
+
+**Какой отказ это поймало.** Замер по 48 чужим настройкам `.claude/settings.json`, снятым с
+GitHub 2026-09-07. Шесть настоящих находок в четырёх репозиториях:
+
+```json
+"PreToolCall": [
+  { "matcher": "Bash(git commit*)",
+    "command": "npm run typecheck && npm run test",
+    "description": "Run typecheck and tests before committing to ensure CI checks will pass" }
+]
+```
+
+События `PreToolCall` у Claude Code нет. Человек написал в описании, ради чего это стоит, — и не
+запускается оно никогда. Такие же `PostToolCall` и `preToolCall` нашлись ещё в трёх проектах.
+
+**Вторая половина записи — `matcher`, которого нет.** Документация дословно: *«If you add a
+`matcher` field to an event without matcher support, it is silently ignored.»* События без
+поддержки `matcher` — `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`,
+`TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay`, `CwdChanged`. Написав
+`"Stop": [{ "matcher": "Bash" }]`, автор думает, что отобрал, а хук срабатывает на всём.
+
+**Готовый аналог есть, и он этого не ловит — проверено прогоном.**
+[`claudelint`](https://github.com/pdugan20/claudelint) (npm `claude-code-lint`, MIT, обновлялся
+вчера) проверяет схему `settings.json`, синтаксис прав и ловит `"allow": ["*"]` — это мы не
+дублируем, ставьте его рядом. В его исходниках есть и правило `hooks-invalid-event`, но живой
+прогон версии 0.8.0 на файле с `"PoToolUse"` даёт «No problems found»: категория `hooks` на
+`.claude/settings.json` не срабатывает. Причина найдена в их исходнике 2026-09-08 — правила
+категории `Hooks` запускает только `HooksValidator` (`src/validators/hooks.ts`), а он ищет файлы
+по единственному образцу `hooks/hooks.json` (`src/utils/filesystem/patterns.ts:45`). Сообщено:
+[issue #217](https://github.com/pdugan20/claudelint/issues/217). [`cclint`](https://github.com/carlrannaberg/cclint)
+последний раз трогали в сентябре 2025 и лицензии у него нет. `AgentLint` знает 12 событий из 33.
+
+**Почему список, а не «похоже на опечатку».** Первая версия краснела только на близких промахах —
+чтобы не объявить опечаткой событие, появившееся после нас. Замер эту конструкцию убил:
+`PreToolCall` отстоит от `PreToolUse` на четыре правки, и проверка его пропускала. Правило,
+красящее **всё** незнакомое, на 39 случайных чужих настройках дало **ноль** ложных.
+
+Размен назван вслух: событие, добавленное в Claude Code после нас, эта проверка объявит
+незнакомым. Такое ложное срабатывание видно, оно громкое и чинится одной строкой в списке.
+Пропуск не виден никак — хук молчит, и молчание неотличимо от того, что всё хорошо. Из двух
+ошибок выбираем шумную.
+
+**Откуда список.** https://code.claude.com/docs/en/hooks — раздел Configuration, таблица
+«Each event type matches on a different field» и заголовки разделов событий. Снято 2026-09-07,
+33 события. Дата стоит в самой проверке: список устареет, и это должно быть видно.
+
+**Чего НЕ ловит.**
+
+- **Хук с верным именем, который падает или ничего не делает.** Проверяется только то, что он
+  будет вызван, а не то, что он работает. Вызванный и сломанный хук — предмет другой записи.
+- **Права.** `"allow": ["*"]`, слишком широкие разрешения, ошибки в синтаксисе правил — это
+  `claudelint`, и он делает это лучше.
+- **Команду хука, указывающую на несуществующий скрипт.** Искали и **не нашли материала**:
+  шесть чужих репозиториев склонированы целиком, 30 путей к скриптам хуков проверены на диске,
+  несуществующих — ноль. Это не «не искали»: выборка содержала предмет, и предмет оказался
+  здоров. Запись не начата. У `claudelint` правило `hooks-missing-script` есть, но на
+  `.claude/settings.json` оно, как и `hooks-invalid-event`, не срабатывает — проверено прогоном
+  версии 0.8.0.
+- **Хуки в плагинах и в `~/.claude/`.** Смотрим только настройки проекта: домашний каталог не
+  лежит в репозитории и в дифе не виден.
+- **`stop_hook_active`.** Хук на `Stop`, не проверяющий это поле, зациклится — но Claude Code
+  сам обрывает его после восьми подряд блокировок, так что цена ошибки восемь ходов, а не
+  вечность. Проверять содержимое скрипта на любом языке дороже, чем стоит.
+
+**Образцы.** `red/` — опечатка (`PoToolUse`), чужое написание (`post_tool_use`), незнакомое имя
+(`PreToolCall`) и `matcher` на `Stop`. `green/` — те же хуки с верными именами, `matcher: ""` и
+`matcher: "*"` на событиях без поддержки matcher (они означают «всё» — ровно то, что и
+происходит, автор не обманут).

package/kit/gates/hook-actually-fires/check.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env sh
+# Хук, который не сработает никогда: имя события с опечаткой, либо `matcher` на событии,
+# которое его не поддерживает.
+#
+# ЗАЧЕМ. Человек заводит хук, чтобы машина держала то, что он держать не может: не дать
+# сделать force-push, отформатировать после правки, не отпустить работу с красным линтером.
+# Ошибку в имени события Claude Code НЕ показывает — хук просто никогда не вызывается.
+# Настройка выглядит как защита и защитой не является. Это тот же класс, что `pytest || true`:
+# зелёное, полученное по причине, не имеющей отношения к предмету.
+#
+# ОТКУДА СПИСОК СОБЫТИЙ. https://code.claude.com/docs/en/hooks — раздел Configuration, таблица
+# «Each event type matches on a different field» и заголовки разделов. Снято 2026-09-07.
+# Дословно оттуда же про matcher: "If you add a `matcher` field to an event without matcher
+# support, it is silently ignored."
+#
+# ПОЧЕМУ ВСЁ-ТАКИ СПИСОК, А НЕ «БЛИЗКИЙ ПРОМАХ». Первая версия краснела только на именах,
+# отличающихся от известного одной-двумя буквами: список стареет, и не хотелось объявлять
+# опечаткой событие, появившееся после нас. Замер эту конструкцию убил. В `kevinreber/watch-party`
+# лежит `"PreToolCall"` — хук, гоняющий typecheck и тесты перед `git commit` и `git push`,
+# который не срабатывает никогда. От `PreToolUse` это имя отстоит на четыре правки, и проверка
+# по близости его пропускала. Правило же, красящее всё незнакомое, на 39 чужих настройках дало
+# ноль ложных.
+#
+# Размен назван вслух: событие, добавленное в Claude Code после нас, эта проверка объявит
+# незнакомым. Это ложное срабатывание — видимое, громкое и чинится одной строкой здесь. Пропуск
+# же не виден никак: хук молчит, и молчание неотличимо от того, что всё хорошо. Из двух ошибок
+# мы выбираем шумную.
+DIR="${1:-.}"
+
+# ПО ОДНОМУ ФАЙЛУ ЗА ПРОХОД, а не списком в один awk. Разбор идёт в END по накопленному тексту:
+# при нескольких файлах в общем буфере FILENAME остаётся последним, а счётчик строк — сквозным,
+# и находка из `settings.json` печаталась как `settings.local.json:71` вместо `settings.json:8`.
+# Мало того что путь чужой: `--since` сверяет напечатанный путь с дифом, не находит его и
+# считает находок ноль — гейт зеленеет. Найдено код-ревью 2026-09-07.
+OUT=""
+ERR=""
+FOUND=0
+for F in "$DIR/.claude/settings.json" "$DIR/.claude/settings.local.json" \
+         "$DIR/.claude/hooks/hooks.json" "$DIR/.claude/hooks.json"; do
+  [ -f "$F" ] || continue
+  FOUND=1
+
+  # Файл хуков без обёртки `"hooks": { … }` держит карту событий прямо в корне. Такой уклад
+  # встречается в `hooks.json`, и без этой поправки триггер срабатывал, а проверять было нечего:
+  # тишина неотличима от чистой настройки. В `settings.json` корневые ключи — `permissions`,
+  # `env`, `model`, — и считать их событиями нельзя, поэтому послабление только для hooks.json.
+  ROOT=0
+  # Ищем именно ОБЪЕКТ на верхнем уровне: `"hooks": {`. Просто `"hooks":` не годится — этот же
+  # ключ стоит внутри каждой группы («"matcher": "Bash", "hooks": [ … ]»), и грубый греп находил
+  # его всегда, из-за чего поблажка не включалась никогда. Найдено прогоном образца.
+  case "$F" in
+    *hooks.json) tr -d '\n' < "$F" | grep -q '"hooks"[[:space:]]*:[[:space:]]*{' || ROOT=1 ;;
+  esac
+
+  RES=$(awk -v rootIsHooks="$ROOT" '
+    BEGIN {
+      split("SessionStart Setup InstructionsLoaded UserPromptSubmit UserPromptExpansion " \
+            "MessageDisplay PreToolUse PermissionRequest PermissionDenied PostToolUse " \
+            "PostToolUseFailure PostToolBatch Notification SubagentStart SubagentStop " \
+            "TaskCreated TaskCompleted Stop StopFailure TeammateIdle ConfigChange CwdChanged " \
+            "DirectoryAdded FileChanged WorktreeCreate WorktreeRemove PreCompact PostCompact " \
+            "PreModelSwitch PostModelSwitch Elicitation ElicitationResult SessionEnd", KNOWN, " ")
+      # События, у которых matcher не поддерживается вовсе: он молча игнорируется, и хук
+      # срабатывает на каждом событии — шире, чем думает автор.
+      split("UserPromptSubmit PostToolBatch Stop TeammateIdle TaskCreated TaskCompleted " \
+            "WorktreeCreate WorktreeRemove MessageDisplay CwdChanged", NOMATCH, " ")
+      for (i in NOMATCH) NOMATCHER[NOMATCH[i]] = 1
+      for (i in KNOWN) NORM[normalize(KNOWN[i])] = KNOWN[i]
+    }
+    function normalize(s,   t) { t = tolower(s); gsub(/[^a-z0-9]/, "", t); return t }
+    function min3(a, b, c) { if (a <= b && a <= c) return a; if (b <= c) return b; return c }
+    function edit(a, b,   la, lb, i, j, prev, cur, cost) {
+      la = length(a); lb = length(b)
+      if (la == 0) return lb
+      if (lb == 0) return la
+      for (j = 0; j <= lb; j++) prev[j] = j
+      for (i = 1; i <= la; i++) {
+        cur[0] = i
+        for (j = 1; j <= lb; j++) {
+          cost = (substr(a, i, 1) == substr(b, j, 1)) ? 0 : 1
+          cur[j] = min3(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
+        }
+        for (j = 0; j <= lb; j++) prev[j] = cur[j]
+      }
+      return prev[lb]
+    }
+    function judge(ev, ln,   nz, best, bestName, d, i) {
+      for (i in KNOWN) if (KNOWN[i] == ev) return
+      nz = normalize(ev)
+      if (nz in NORM) {
+        printf "%s:%d: событие «%s» написано не так, как его зовёт Claude Code — «%s». Хук не сработает никогда\n", file, ln, ev, NORM[nz]
+        return
+      }
+      best = 99; bestName = ""
+      for (i in KNOWN) { d = edit(nz, normalize(KNOWN[i])); if (d < best) { best = d; bestName = KNOWN[i] } }
+      if (best <= 3)
+        printf "%s:%d: событие «%s» Claude Code не знает — похоже на «%s». Хук не сработает никогда\n", file, ln, ev, bestName
+      else
+        printf "%s:%d: событие «%s» Claude Code не знает — хук не сработает никогда. Либо опечатка, либо событие новее этой проверки (список снят 2026-09-07)\n", file, ln, ev
+    }
+    # Разбор посимвольный с учётом строк и экранирования: `{` внутри строкового значения не
+    # меняет глубину. Построчный греп здесь врал бы на любом однострочном json.
+    FNR == 1 { file = FILENAME }
+    { text = text $0 "\n" }
+    END {
+      n = length(text); depth = 0; instr = 0; esc = 0; line = 1
+      hooksDepth = -1; evDepth = -1; ev = ""; key = ""; buf = ""; awaitMatcher = 0
+      for (p = 1; p <= n; p++) {
+        c = substr(text, p, 1)
+        if (c == "\n") { line++; continue }
+        if (instr) {
+          if (esc) { esc = 0; buf = buf c; continue }
+          if (c == "\\") { esc = 1; continue }
+          if (c == "\"") {
+            instr = 0; pending = buf; pendingLine = line
+            # Значение matcher прочитано. Красим ТОЛЬКО осмысленный фильтр: пустая строка и «*»
+            # означают «всё» — ровно то, что и происходит на событии без поддержки matcher, то
+            # есть автор не обманут. Замер по 39 чужим настройкам: без этого сужения гейт краснел
+            # на четырёх, и все четыре были «matcher»: "" либо "*", то есть шум.
+            if (awaitMatcher) {
+              awaitMatcher = 0
+              if (pending != "" && pending != "*" && pending != ".*")
+                printf "%s:%d: у события «%s» matcher не поддерживается — «%s» молча игнорируется, и хук срабатывает на каждом событии, а не на отобранных\n", file, matcherLine, matcherEv, pending
+            }
+            continue
+          }
+          buf = buf c; continue
+        }
+        if (c == "\"") { instr = 1; buf = ""; continue }
+        if (c == ":") {
+          key = pending; keyLine = pendingLine
+          if (ev != "" && key == "matcher" && (ev in NOMATCHER)) { awaitMatcher = 1; matcherLine = keyLine; matcherEv = ev }
+          continue
+        }
+        # ЛЮБОЙ структурный символ снимает ожидание значения matcher. Без этого нестроковое
+        # значение (`"matcher": null`, число, массив) оставляло флаг взведённым, и первая же
+        # следующая строка документа — обычно ключ «hooks» — печаталась как значение matcher.
+        # Найдено код-ревью 2026-09-07.
+        if (c == "{" || c == "[") {
+          awaitMatcher = 0
+          depth++
+          if (c == "{" && rootIsHooks == 1 && depth == 1 && hooksDepth == -1) hooksDepth = 1
+          else if (c == "{" && key == "hooks" && hooksDepth == -1) hooksDepth = depth
+          else if (hooksDepth != -1 && depth == hooksDepth + 1 && key != "") { ev = key; evDepth = depth; judge(key, keyLine) }
+          key = ""; continue
+        }
+        if (c == "}" || c == "]") {
+          awaitMatcher = 0
+          if (depth == evDepth) { ev = ""; evDepth = -1 }
+          if (depth == hooksDepth) hooksDepth = -1
+          depth--; key = ""; continue
+        }
+        if (c == ",") { awaitMatcher = 0; key = ""; continue }
+      }
+    }
+  ' "$F" 2>/tmp/.hookerr.$$)
+  CODE=$?
+  E=$(cat /tmp/.hookerr.$$ 2>/dev/null); rm -f /tmp/.hookerr.$$
+  # Отказ инструмента и чистая настройка дают одинаково пустой вывод и противоположные выводы.
+  # Разделяем их кодом возврата: «не смогли разобрать» — это 2, а не молчаливый ноль.
+  if [ "$CODE" -ne 0 ] || [ -n "$E" ]; then
+    ERR="$ERR$F: разобрать не удалось${E:+ — }$E
+"
+  fi
+  [ -n "$RES" ] && OUT="$OUT$RES
+"
+done
+
+[ "$FOUND" -eq 0 ] && exit 0
+
+if [ -n "$ERR" ]; then
+  printf '%s' "$ERR"
+  echo "  почини: покажи файл настроек глазами — проверка не смогла его разобрать."
+  echo "  «не смогли проверить» и «нарушений нет» дают одинаково пустой список и разные выводы."
+  exit 2
+fi
+
+ALL=$(printf '%s' "$OUT" | grep -v '^$')
+[ -z "$ALL" ] && exit 0
+printf '%s\n' "$ALL"
+echo "  почини: сверь имя события с https://code.claude.com/docs/en/hooks и убери matcher там, где его нет."
+echo "  хук с неверным именем не вызывается и об этом не сообщается — защита существует только на бумаге."
+exit 1

package/kit/gates/hook-actually-fires/gate.yml

@@ -0,0 +1,15 @@
+intent: хук агента правда срабатывает — имя события известно, matcher не игнорируется молча
+intent_en: an agent hook actually fires — the event name is real and the matcher is not silently ignored
+
+# Только там, где агента настраивали. В проекте без `.claude/settings.json` проверять нечего,
+# а запись, показанная не тому, стоит доверия всему каталогу.
+trigger:
+  has_agent_config: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-07 «хук, которого никогда не было» — замер по 48 чужим
+  настройкам: ноль ложных на 39 случайных и шесть настоящих находок в четырёх репозиториях
+  (`PreToolCall`, `PostToolCall`, `preToolCall` — событий с такими именами у Claude Code нет,
+  и хуки, гоняющие typecheck и тесты перед коммитом, не срабатывают там никогда)

package/kit/gates/hook-actually-fires/green/.claude/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "guard.sh" } ] } ]
+}

package/kit/gates/hook-actually-fires/green/.claude/settings.json

@@ -0,0 +1,74 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(./.env)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/block-dangerous.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/auto-format.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/stop-gate.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/prompt.sh"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/done.sh"
+          }
+        ]
+      }
+    ],
+    "TeammateIdle": [
+      {
+        "matcher": null,
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/idle.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/kit/gates/hook-actually-fires/green/.claude/settings.local.json

@@ -0,0 +1,74 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(./.env)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/block-dangerous.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/auto-format.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/stop-gate.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/prompt.sh"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/done.sh"
+          }
+        ]
+      }
+    ],
+    "TeammateIdle": [
+      {
+        "matcher": null,
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/idle.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/kit/gates/hook-actually-fires/red/.claude/hooks/hooks.json

@@ -0,0 +1,4 @@
+{
+  "matcher_ne_stroka": "образец против дефекта, найденного ревью 2026-09-07",
+  "PoToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "x.sh" } ] } ]
+}

package/kit/gates/hook-actually-fires/red/.claude/settings.json

@@ -0,0 +1,53 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(./.env)"
+    ]
+  },
+  "hooks": {
+    "PoToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/block-dangerous.sh"
+          }
+        ]
+      }
+    ],
+    "post_tool_use": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/auto-format.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/stop-gate.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolCall": [
+      {
+        "matcher": "Bash(git commit*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npm run typecheck && npm test"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,84 @@
+# Пакета с таким именем нет в реестре
+
+**Намерение.** Агент, не знающий инструмента, придумывает правдоподобное имя: `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` — не как «проверка не
+  состоялась». Эту разницу изнутри проверки не выразить: её съедает тот, кто её обрывает.