agent-quality-kit 0.7.0 → 0.9.0

package/kit/gates/_skip.sh

@@ -72,8 +72,68 @@ include_code() {
 # Сгенерированный файл не правят руками — предъявлять его размер или сложность человеку
 # бессмысленно и вредно: он выключит проверку целиком.
 # Опознаём по общепринятой шапке в первых пяти строках.
+# Регистр кириллицы `grep -i` сворачивает НЕ ВЕЗДЕ: на linux сворачивает, в Git Bash под
+# Windows — нет. Шапка `// СГЕНЕРИРОВАН` там не находилась никогда, и узнали мы об этом только
+# 2026-09-08, когда нарочный набор впервые прогнали на windows-задании. Это не регрессия правки,
+# а старая дыра, которую нечем было увидеть: на живых шести проектах таких шапок не было.
+# Поэтому кириллица перечисляется явно, а не доверяется флагу: три написания, которые бывают
+# на деле, — строчное в комментарии, с заглавной в начале фразы и капсом в баннере.
+GENERATED_MARKERS='@generated|do not edit|autogenerated|auto-generated|generated by|сгенерирован|Сгенерирован|СГЕНЕРИРОВАН'
+
+# Один файл: сгенерирован ли он. Осталось для тех, кто спрашивает про ОДИН файл
+# (gate-not-weakened сверяет строку находки, а не список путей).
 is_generated() {
-  head -5 "$1" 2>/dev/null | grep -qiE '@generated|do not edit|autogenerated|auto-generated|generated by|сгенерирован'
+  head -5 "$1" 2>/dev/null | grep -qiE "$GENERATED_MARKERS"
+}
+
+# СПИСОК файлов на stdin (по пути в строке) → тот же список без сгенерированных.
+#
+# ЗАЧЕМ ОТДЕЛЬНО ОТ is_generated. Цикл `while read; do is_generated; done` запускает ДВА
+# процесса на каждый файл — head и grep. Замерено 2026-09-08 на 748 файлах проекта uv:
+# обход и отбор 12 мс, подсчёт строк одним wc 37 мс, а этот цикл — 3862 мс. Сто крат от
+# всего остального, и ни микросекунды из них не потрачено на сравнение строк: платили за
+# fork+exec. Медленным был не язык — медленным было количество запусков.
+#
+# ПОЧЕМУ ИМЕННО grep, А НЕ awk. Соблазн был собрать всё одним awk с `nextfile`. Отвергнуто:
+# `nextfile` — расширение, а `tolower` на кириллице врёт в mawk и busybox-awk, и «сгенерирован»
+# перестал бы находиться там, где сейчас находится. Здесь ТОТ ЖЕ grep с ТЕМИ ЖЕ флагами, что
+# и в is_generated, — значит совпадение считается ровно так же, как раньше, и меняется только
+# число запусков. Равенство вывода проверено на шести чужих проектах: 0 расхождений.
+#
+# `-m1` останавливает grep на первом совпадении в файле, `/dev/null` заставляет его печатать
+# имя файла даже когда xargs передал ровно один путь.
+drop_generated() {
+  LIST=$(mktemp) || { cat; return; }
+  GEN=$(mktemp) || { rm -f "$LIST"; cat; return; }
+  cat > "$LIST"
+  # Пути передаются через НОЛЬ-разделитель: xargs по умолчанию рвёт по пробелам, и файл
+  # «src/my component.tsx» уехал бы в grep двумя несуществующими путями. Поймано нарочным
+  # набором до выпуска: старый цикл `while read` пробелы держал, и потерять это было нельзя.
+  tr '\n' '\0' < "$LIST" \
+    | xargs -0 -r grep -niE -m1 -e "$GENERATED_MARKERS" /dev/null 2>/dev/null \
+    | awk -v list="$LIST" '
+        # Строка вывода grep — «путь:номер:текст», и разобрать её по первому двоеточию нельзя:
+        # в пути тоже бывает двоеточие, а в тексте находки — тем более. Поэтому путь не
+        # угадывается, а СВЕРЯЕТСЯ со списком, который мы сами и передали: идём по двоеточиям
+        # слева направо, пока префикс не совпадёт с известным путём. Двоеточие в имени файла
+        # редкость, но «редко» и «никогда» — разные вещи, а тихо оставленный сгенерированный
+        # файл даёт находки на чужом коде.
+        BEGIN { while ((getline l < list) > 0) known[l] = 1 }
+        {
+          rest = $0; prefix = ""
+          while ((i = index(rest, ":")) > 0) {
+            prefix = prefix substr(rest, 1, i - 1)
+            rest = substr(rest, i + 1)
+            if (prefix in known) {
+              if (match(rest, /^[0-9]+:/) && substr(rest, 1, RLENGTH - 1) + 0 <= 5) print prefix
+              break
+            }
+            prefix = prefix ":"
+          }
+        }
+      ' | sort -u > "$GEN"
+  if [ -s "$GEN" ]; then grep -vxF -f "$GEN" "$LIST"; else cat "$LIST"; fi
+  rm -f "$LIST" "$GEN"
 }
 
 # Для grep: --exclude-dir на каждое имя. Образцы гейтов сюда не входят — см. own_samples_filter:

package/kit/gates/ci-not-hijackable/README.md

@@ -0,0 +1,56 @@
+# Конвейер не отдаёт чужому коду свои права и секреты
+
+**Намерение.** Конвейер выполняется с правами репозитория и с доступом к его секретам. Три
+способа отдать их постороннему живут не в коде, а в двадцати строках yaml:
+
+- **подвижная метка вместо SHA.** `uses: some/action@v1` — это указатель, который владелец
+  действия может перевести на другой код в любой момент, и он же перевёдется у всех, кто на
+  метку сослался;
+- **`pull_request_target` вместе с выкачиванием ветки автора PR.** Триггер даёт секреты
+  основного репозитория, а код берётся у постороннего;
+- **`permissions: write-all`** на весь рабочий поток вместо нужного права нужному заданию.
+
+Ни одну из трёх обычная проверка кода не увидит: это не код, это настройка.
+
+**Какой отказ это поймало.** Собственный. На момент заведения записи у комплекта было **13
+находок высокой строгости и 5 средней**, среди них десять действий, закреплённых меткой вместо
+SHA, `id-token: write` на уровне всего потока и пять вызовов `checkout`, оставляющих учётные
+данные в `.git/config`.
+
+**Почему порог именно такой.** Замер 2026-09-08 по шести настоящим репозиториям:
+
+| проект | High | Medium |
+|---|---|---|
+| `express` | 0 | 0 |
+| `flask` | 0 | 0 |
+| `uv` | 0 | 0 |
+| `httpx` | 4 | 4 |
+| `gin` | 18 | 0 |
+| `ripgrep` | 19 | 8 |
+
+Половина держит ноль. Порог взят с тех, кто его держит, а не выдуман: он достижим, и это
+доказано чужой практикой, а не нашим мнением.
+
+**Готовый аналог есть, и мы его зовём.** [`zizmor`](https://github.com/zizmorcore/zizmor) (MIT,
+6459 звёзд, статический разбор GitHub Actions). Его же гоняет `flask` отдельным заданием
+конвейера. Своего разбора yaml мы не писали. Обёртка отвечает за порог (`--min-severity medium`)
+и за то, чтобы «не проверено» не выдавалось за «чисто»: `--no-exit-codes` разводит «нашлись
+находки» и «инструмент не отработал», а отсутствие итоговой строки в выводе даёт код 2.
+
+**Образцы.** `red/` — рабочий поток с `pull_request_target`, выкачиванием ветки автора PR,
+`permissions: write-all` и незакреплённым действием. `green/` — тот же поток на `pull_request`,
+с правами только на чтение, действием по SHA и `persist-credentials: false`.
+
+**Чего НЕ ловит.**
+
+- **Только GitHub Actions.** GitLab CI, Jenkins, Buildkite не проверяются: zizmor их не читает.
+- **Не выполняет конвейер.** Разбор статический: он видит опасный уклад, но не видит, что делает
+  скрипт внутри `run:`. Скачивание и выполнение чужого кода строкой `curl … | sh` внутри шага —
+  предмет другой проверки, и её у нас нет.
+- **Не сторожит SHA после закрепления.** Закреплённое действие может оказаться заброшенным или
+  уязвимым; «закреплено» и «безопасно» — разные утверждения. Обновление закреплённых SHA — работа
+  для dependabot, а не для этой записи.
+- **Точечное гашение с причиной остаётся возможным.** `# zizmor: ignore[правило] причина` снимает
+  находку, и это осознанный уклад: наш собственный `gate-not-weakened` требует, чтобы подавление
+  было точечным и с названной причиной, а не порогом на весь файл. Мы сами пользуемся этим дважды
+  и обе причины написали вслух.

package/kit/gates/ci-not-hijackable/check.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env sh
+# Конфигурация конвейера не отдаёт чужому коду права и секреты.
+#
+# ЗАЧЕМ. Конвейер выполняется с правами репозитория и с доступом к его секретам. Три способа
+# отдать их постороннему живут не в коде, а в двадцати строках yaml: триггер `pull_request_target`
+# вместе с выкачиванием ветки автора PR; действие, закреплённое подвижной МЕТКОЙ, которую владелец
+# действия может перевести на другой код; права `write-all`, выданные всему рабочему потоку.
+# Ни одну из трёх обычная проверка кода не увидит: это не код, это настройка.
+#
+# Работу делает zizmor (MIT, 6459 звёзд, статический разбор GitHub Actions). Мы отвечаем за
+# порог и за то, чтобы «не проверено» не выдавалось за «чисто».
+#
+# ПОЧЕМУ ПОРОГ ИМЕННО ТАКОЙ. Замер 2026-09-08 по шести настоящим репозиториям: express, flask и
+# uv держат НОЛЬ находок высокой и средней строгости; gin (18), ripgrep (19) и httpx (4) — нет.
+# Порог взят с тех, кто его держит, а не выдуман: он достижим, и это доказано чужой практикой.
+# Мы сами на момент заведения записи были на неправильной стороне — 13 высоких и 5 средних.
+DIR="${1:-.}"
+WF="$DIR/.github/workflows"
+
+# Нет конвейера — нечего проверять. Это не успех и не провал, это отсутствие предмета.
+[ -d "$WF" ] || exit 0
+
+if ! command -v zizmor >/dev/null 2>&1; then
+  echo "не найден zizmor — эта проверка делегирована ему"
+  echo "  почини: pipx install zizmor  (или uv tool install zizmor)"
+  exit 2
+fi
+
+# --no-exit-codes разводит два разных события, которые иначе слиплись бы в один ненулевой код:
+# «нашлись находки» и «инструмент не отработал». Первое читается из вывода, второе — из кода.
+# NO_COLOR и снятие управляющих последовательностей — вместе, а не по отдельности. Внутри
+# GitHub Actions zizmor КРАСИТ вывод (там цвет поддержан), и итоговая строка начинается с
+# escape-последовательности: правило «^[0-9]+ findings» её не видит, и гейт объявлял, что формат
+# сменился. Локально этого не воспроизвести — вне конвейера цвет выключается сам. Поймано
+# прогоном в конвейере 2026-09-08; тот же класс уже записан у нас в scope.mjs: «цвет снимается ДО
+# поиска». NO_COLOR — соглашение, его может не знать следующая версия; sed — страховка, которая
+# в отличие от NO_COLOR ни от кого не зависит.
+ESC=$(printf '\033')
+OUT=$(NO_COLOR=1 zizmor --no-online-audits --no-exit-codes --min-severity medium --format plain "$WF" 2>&1 \
+      | sed "s/${ESC}\[[0-9;]*[a-zA-Z]//g")
+CODE=$?
+if [ "$CODE" -ne 0 ]; then
+  echo "zizmor не отработал (код $CODE) — проверка не состоялась, это не вердикт «чисто»"
+  printf '%s\n' "$OUT" | grep -iE "error:|panic|not found" | head -3 | sed 's/^/  /'
+  echo "  почини: прогони «zizmor .github/workflows» руками и посмотри, на чём он споткнулся"
+  exit 2
+fi
+
+# Итоговая строка — единственное место, где сказано, сколько чего нашлось. Её отсутствие значит,
+# что формат сменился; молчать об этом нельзя, иначе смена формата станет вечным зелёным.
+SUM=$(printf '%s\n' "$OUT" | grep -E "^(No findings to report|[0-9]+ findings)" | tail -1)
+if [ -z "$SUM" ]; then
+  echo "ответ zizmor не разобран: итоговой строки в нём нет"
+  # Печатаем то, что пришло на самом деле. Без этого причина видна только тому, у кого есть та
+  # же машина: первый отказ этой ветки случился в конвейере, а локально не воспроизводился, и
+  # разбирать пришлось догадками. Сообщение, не показывающее свой ввод, лечится вторым прогоном.
+  echo "  вот последнее, что он напечатал:"
+  printf '%s\n' "$OUT" | tail -3 | sed 's/^/    /'
+  echo "  почини: сверь версию zizmor с той, что названа в gate.yml"
+  exit 2
+fi
+
+case "$SUM" in
+  "No findings to report"*) exit 0 ;;
+esac
+
+printf '%s\n' "$OUT" | grep -E "^(error|warning)\[" | head -20
+N=$(printf '%s\n' "$OUT" | grep -cE "^(error|warning)\[")
+[ "$N" -gt 20 ] && echo "  … и ещё $((N - 20))"
+echo "  почини: закрепи действия по SHA вместо метки, сузь permissions до нужного задания,"
+echo "  замени pull_request_target на pull_request там, где выполняется код автора PR."
+echo "  подробности по каждой находке: https://docs.zizmor.sh/audits/"
+exit 1

package/kit/gates/ci-not-hijackable/gate.yml

@@ -0,0 +1,19 @@
+intent: конвейер не отдаёт чужому коду свои права и секреты
+intent_en: the pipeline does not hand its permissions and secrets to somebody else's code
+
+# Там, где конвейер есть. Без него отдавать нечего.
+trigger:
+  has_ci: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+# Программа, без которой запись не работает. По первому слову команды этого не видно: обёртка
+# начинается с `bash`. Версия названа: обёртка читает итоговую строку вывода zizmor, и смена
+# формата обязана быть видимой, а не тихой.
+requires: zizmor
+
+proof: incidents/README.md, 2026-09-08 «конвейер отдавал права по подвижной метке» — замер по
+  шести настоящим репозиториям показал, что express, flask и uv держат ноль находок высокой и
+  средней строгости, а gin (18), ripgrep (19) и httpx (4) нет; сам комплект на момент заведения
+  записи имел 13 высоких и 5 средних, включая десять действий, закреплённых меткой вместо SHA

package/kit/gates/ci-not-hijackable/green/.github/workflows/triage.yml

@@ -0,0 +1,19 @@
+name: разбор входящих
+
+# pull_request вместо pull_request_target: код автора PR выполняется без доступа к секретам
+# основного репозитория.
+on:
+  pull_request:
+    types: [opened]
+
+permissions:
+  contents: read
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+      - run: echo "разбор без прав на запись"

package/kit/gates/ci-not-hijackable/red/.github/workflows/triage.yml

@@ -0,0 +1,18 @@
+name: разбор входящих
+
+# pull_request_target выполняется в контексте ОСНОВНОЙ ветки и с доступом к секретам,
+# а код берётся из ветки автора PR. Классическая дыра.
+on:
+  pull_request_target:
+    types: [opened]
+
+permissions: write-all
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - run: npm install && npm run build

package/kit/gates/color-from-token/check.sh

@@ -40,7 +40,7 @@ EXT_RE="$(printf '%s' "$COLOR_EXT" | tr ' ' '|')"
 HITS=$(find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null \
   | grep -E "\.($EXT_RE)$" \
   | grep -viE "(^|/)[^/]*($SOURCE_RE)[^/]*\.($EXT_RE)$" \
-  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | drop_generated \
   | LC_ALL=C sort \
   | xargs -r awk '
       # Блочные комментарии вырезаются ПО СОСТОЯНИЮ, а не построчно. Однострочный фильтр
@@ -63,7 +63,15 @@ HITS=$(find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null \
           if (e == 0) { line = substr(line, 1, s - 1); inblock = 1; break }
           line = substr(line, 1, s - 1) substr(rest, e + 2)
         }
-        if (line ~ /#[0-9a-fA-F]{8}([^0-9a-fA-F]|$)|#[0-9a-fA-F]{6}([^0-9a-fA-F]|$)|#[0-9a-fA-F]{3}([^0-9a-fA-F]|$)/)
+        # Хвост — «не буква, не цифра, не дефис», а не просто «не шестнадцатеричный символ».
+        # Якорь ссылки «#defining-entry-points» начинается с «#def», за которым идёт «i»: по
+        # прежнему правилу это был цвет. Замер 2026-09-08 по шести чужим репозиториям: в uv
+        # ложным оказалось именно это, в docs/js/extra.js.
+        # Цвет выписан поразрядно: часть сборок mawk повторители не понимает (в node:22-slim
+        # это mawk 1.3.4 20200120), а какая сборка у читателя — мы не знаем
+        # {3},{6},{8}, и это условие не срабатывало никогда — гейт молчал на красном образце.
+        # Поймано сборкой docker-образа 2026-09-08, а не прогоном: на хосте gawk.
+        if (line ~ /#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]([^0-9a-zA-Z_-]|$)/)
           print FILENAME ":" FNR ":" $0
       }
     ' 2>/dev/null \

package/kit/gates/color-from-token/green/Button.tsx

@@ -2,3 +2,5 @@ export function Button({ children }: { children: React.ReactNode }) {
   // Цвет приходит из темы: перекрашивается вместе с ней.
   return <button className="bg-[var(--color-accent)] text-[var(--color-on-accent)]">{children}</button>;
 }
+
+const DOC_ANCHOR = "concepts/projects/#defining-entry-points";

package/kit/gates/complexity-limit/check.sh

@@ -30,7 +30,7 @@ TESTS="-name test -prune -o -name tests -prune -o -name spec -prune -o -name __t
 find "$DIR" $(skip_find "$DIR") $TESTS -type f \
      ! -name 'test_*' ! -name '*_test.*' ! -name '*.test.*' ! -name '*.spec.*' \
      -print 2>/dev/null | only_code | own_samples_filter "$DIR" \
-  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | drop_generated \
   | xargs -r awk -v MAX="$MAX" '
         # Один обход на все файлы: процесс на каждый файл дал 19 секунд на 4000 файлов.
         # Разметка вложена по природе: пять уровней тегов — это не сложная логика, а обычная
@@ -40,12 +40,11 @@ find "$DIR" $(skip_find "$DIR") $TESTS -type f \
         FNR == 1 { flush(); worst = 0; wl = 0; wf = FILENAME }
         /^[[:space:]]*$/ { next }
         {
-          # ширина отступа: табуляция считается за четыре пробела
-          line = $0; n = 0
-          while (match(line, /^[ \t]/)) {
-            n += (substr(line, 1, 1) == "\t") ? 4 : 1
-            line = substr(line, 2)
-          }
+          # ширина отступа: табуляция считается за четыре пробела. Отступ берётся ОДНИМ
+          # match, а не посимвольным циклом с substr: цикл выделял новую строку на каждый
+          # символ отступа и стоил больше, чем весь остальной разбор. Замер 2026-09-08 на uv.
+          match($0, /^[ \t]*/); ind = substr($0, 1, RLENGTH)
+          n = gsub(/\t/, "", ind) * 4 + length(ind)
           depth = int(n / 4)
           if (depth > worst) { worst = depth; wl = FNR }
         }

package/kit/gates/duplicate-code/check.sh

@@ -30,7 +30,7 @@ TESTS="-name test -prune -o -name tests -prune -o -name spec -prune -o -name __t
 find "$DIR" $(skip_find "$DIR") $TESTS -type f \
      ! -name 'test_*' ! -name '*_test.*' ! -name '*.test.*' ! -name '*.spec.*' \
      -print 2>/dev/null | only_code | own_samples_filter "$DIR" \
-  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | drop_generated \
   | LC_ALL=C sort \
   | xargs -r env LC_ALL=C awk -v WIN="$WIN" '
       # Строка-объявление ввоза: `import`, `from … import`, `use …;`, путь в кавычках внутри
@@ -54,6 +54,10 @@ find "$DIR" $(skip_find "$DIR") $TESTS -type f \
         buf[++n] = line
         imp[n] = isimport(line)
         if (n >= WIN) {
+          # Ключ и признак «есть ли код» собираются ОДНИМ проходом по окну. Разнести их на
+          # два цикла выглядело ускорением — окно из одного ввоза отбрасывалось бы до сборки
+          # ключа. Замерено 2026-09-08 на uv: стало 2791 мс против 1770. Второй обход окна
+          # дороже, чем сборка ключа, которую он экономит; правка откачена по замеру.
           key = ""; code = 0
           for (i = n - WIN + 1; i <= n; i++) { key = key buf[i] "\x1e"; if (!imp[i]) code = 1 }
           if (!code) next                               # окно целиком из ввоза — не дубль

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

@@ -7,7 +7,10 @@ MISS=0
 for MD in "$DIR"/*.md; do
   [ -f "$MD" ] || continue
   # вытащить цели ссылок вида [текст](путь)
-  TARGETS=$(sed -n 's/.*](\([^)]*\)).*/\1/p' "$MD")
+  # Строки со вставками в обратных кавычках чистятся ДО разбора: «`[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 где угодно внутри,
     # не только в начале строки.

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

@@ -6,3 +6,5 @@
 Ссылка на страницу сайта документации: [руководство](tutorial/#install) — путь опубликованного
 сайта, а не файл на диске. Найдено замером по fastapi: `[installation guide](tutorial/#install-fastapi)`
 в README читалась как битая, хотя на сайте работает. Так ссылаются mkdocs, docusaurus и jekyll.
+
+Пример оформления ссылки: `[name](url)` — это пример, а не ссылка.

package/kit/gates/file-size-limit/check.sh

@@ -23,7 +23,7 @@ fi
 # не укладывался в две минуты.
 # shellcheck disable=SC2046
 find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null | only_code | own_samples_filter "$DIR" \
-  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | drop_generated \
   | xargs -r wc -l 2>/dev/null \
   | awk '
       $2 == "total" { next }

package/kit/gates/lesson-has-outcome/check.sh

@@ -30,7 +30,11 @@ FILES=$(find "$DIR/$LESSONS" -type f -name '*.md' 2>/dev/null)
 # старые записи несут её строкой ">", новые — абзацем "**Вывод.**"; оба варианта законны.
 printf '%s\n' $FILES | while read -r F; do
   awk -v FILE="$F" '
-    /^## [0-9]{4}-[0-9]{2}-[0-9]{2}/ { flush(); title = $0; sub(/^## /, "", title); is_entry = 1; has_mark = 0; next }
+    # Дата выписана поразрядно, а не как [0-9]{4}: часть сборок mawk повторители не понимает
+    # повторители в регулярках, и такая строка не совпадала НИКОГДА. Гейт молча выходил с нулём
+    # на собственном красном образце. Поймано сборкой образа 2026-09-08: на хосте gawk, в образе
+    # mawk, и приёмка каталога внутри образа отклонила две записи из двадцати.
+    /^## [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/ { flush(); title = $0; sub(/^## /, "", title); is_entry = 1; has_mark = 0; next }
     /^## / { flush(); is_entry = 0; next }
     (/✅/ || /🔧/ || /📜/ || /👤/) { has_mark = 1 }
     END { flush() }

package/kit/gates/mcp-server-resolves/README.md

@@ -0,0 +1,62 @@
+# mcp-server-resolves
+
+**Что ловит.** Объявленный MCP-сервер, которого на деле нет: команда указывает на несуществующий
+файл, либо версия не закреплена и завтра приедет другая.
+
+**Почему это отдельная запись.** Сервер, который не поднялся, агенту **никак не виден**: у него
+просто нет этих инструментов, и он молча работает без них. Ни ошибки, ни строки в журнале.
+Это тот же класс, что хук с опечаткой в имени события: настройка выглядит как возможность и
+возможностью не является.
+
+## Шишка, из которой она выросла
+
+2026-09-08. В проект записали настройку `chrome-devtools-mcp` — выглядела безупречно:
+
+```json
+"chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@1.9.0"] }
+```
+
+Сервер был мёртв. Puppeteer подхватывал Windows-овый Chrome из `/mnt/c/` и падал с
+`Target closed`. Узнали только потому, что запустили руками и прочитали журнал — обычно так не
+делают: записали конфиг, увидели «сохранено», пошли дальше.
+
+## Замер
+
+Двадцать настоящих настроек `.mcp.json`, взятых поиском по GitHub 2026-09-08.
+
+| | |
+|---|---|
+| конфигов проверено | 20 |
+| покраснело | 9 |
+| находок | 14 |
+| ложных срабатываний | **0** |
+
+Все находки — чужие серверы, которые тянутся незакреплёнными при каждом запуске:
+`@modelcontextprotocol/server-github`, `firecrawl-mcp`, `mcp-server-postgres`, `@upstash/context7-mcp`.
+Серверу с таким доступом «сегодня одна версия, завтра другая» — открытая дверь в цепочке поставок.
+
+Замер тут же нашёл и два ложных срабатывания, оба починены до объявления записи рабочей:
+
+1. `npx tsx rag/src/index.ts` — сервер **свой**, лежит в репозитории и уже под версией. Требовать
+   закрепить `tsx` значит краснеть на нормальном укладе, а такой гейт выключают в первый день.
+2. Починка первого съела настоящую находку: `@meridian/docs-mcp` — имя пакета со слэшем, а слэш
+   считался признаком локального файла. Видно было только построчным сравнением до и после.
+
+## Готовый аналог
+
+Готового аналога нет. Проверено 2026-09-08 поиском: линтеры настроек агента существуют
+(`claudelint`, `agent-lint`), но смотрят на права и хуки, а не на MCP. Ближайшее по смыслу —
+наш собственный `deps-are-pinned`: там то же правило про версии, но для зависимостей сборки,
+и файла `.mcp.json` он не видит.
+
+## Чего НЕ ловит
+
+- **Не запускает серверы.** Мёртвый по любой другой причине сервер — как в шишке выше, где путь
+  и версия были верны, а падал сам браузер, — эта проверка не увидит. Запуск чужих команд на
+  каждый коммит означает скачивание пакетов и минуты ожидания; такую проверку выключают сразу.
+  Живое рукопожатие — то, что делают руками при подключении сервера, и это записано в методичке,
+  а не в гейте.
+- **Не судит об относительных путях.** `"command": "./bin/server"` не проверяется: рабочий
+  каталог сервера задаётся полем `cwd`, и проверить существование без запуска нельзя.
+- **Не знает, что пакет существует в реестре.** Это делает `no-phantom-package`, но только для
+  того, что упомянуто в документации.

package/kit/gates/mcp-server-resolves/check.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env sh
+# Объявленный MCP-сервер, которого на деле нет: команда указывает на файл, которого не
+# существует, либо версия не закреплена и завтра приедет другая.
+#
+# ЗАЧЕМ. Сервер, который не поднялся, агенту НИКАК не виден: у него просто нет этих
+# инструментов, и он молча работает без них. Ни ошибки, ни строки в журнале — та же тишина,
+# что у хука с опечаткой в имени события. Настройка выглядит как возможность и возможностью
+# не является.
+#
+# ПРОВЕРЕНО НА СЕБЕ 2026-09-08. Записали в проект настройку chrome-devtools-mcp, выглядела
+# безупречно. Сервер был мёртв: puppeteer подхватывал Windows-овый Chrome из /mnt/c/ и падал
+# с «Target closed». Узнали только потому, что запустили руками и прочитали журнал; обычно
+# так не делают — записали конфиг, увидели «сохранено», пошли дальше.
+#
+# ЧТО ЭТА ПРОВЕРКА НЕ ДЕЛАЕТ. Она НЕ запускает серверы. Запуск — это исполнение чужих команд
+# на каждый коммит, скачивание пакетов и минуты ожидания; такую проверку выключают в первый
+# день. Здесь ловится только то, что видно без запуска, и этого достаточно для двух самых
+# частых смертей: файла нет и версия плавает.
+DIR="${1:-.}"
+SKIP_LIB="$(dirname "$0")/../_skip.sh"
+if [ ! -f "$SKIP_LIB" ]; then
+  echo "рядом с проверкой нет _skip.sh — обход не собран, проверка не состоялась"
+  echo "  почини: скопируй гейт вместе с файлом kit/gates/_skip.sh, он общий на весь каталог"
+  exit 2
+fi
+. "$SKIP_LIB"
+
+OUT=""
+for F in "$DIR/.mcp.json" "$DIR/.cursor/mcp.json" "$DIR/.vscode/mcp.json" "$DIR/.claude/mcp.json"; do
+  [ -f "$F" ] || continue
+  RES=$(awk -v file="$F" -v dir="$DIR" '
+    # Номера строк с командой копятся отдельно от текста: разбор идёт в END по всему файлу
+    # одной строкой (иначе минифицированный JSON не разобрать), а находку надо привязать к
+    # строке — без неё `--since` не сверит путь с дифом и гейт зазеленеет на чужом дифе.
+    /"command"[ \t]*:/ { cline[++ci] = NR }
+    { buf = buf $0 " " }
+    END {
+      n = split(buf, part, /"command"[ \t]*:/)
+      for (i = 2; i <= n; i++) {
+        chunk = part[i]
+        if (!match(chunk, /"[^"]*"/)) continue
+        cmd = substr(chunk, RSTART + 1, RLENGTH - 2)
+        line = cline[i - 1] ? cline[i - 1] : 1
+
+        # 1. Абсолютный путь, которого нет. Самая частая смерть у пакетов, чья версия вшита
+        # в имя файла: обновились — старый файл удалён, сервер умер, никто не заметил.
+        if (substr(cmd, 1, 1) == "/") {
+          if (system("test -e \"" cmd "\"") != 0)
+            print file ":" line ": команда сервера не существует: " cmd
+          continue
+        }
+
+        # 2. Скачивающий запуск без точной версии. `@latest` и голое имя означают «сегодня
+        # одно, завтра другое», а для сервера, которому доверен браузер и файлы, это дверь
+        # в цепочке поставок. Правило то же, что у нас для зависимостей.
+        if (cmd == "npx" || cmd == "uvx" || cmd == "pipx" || cmd == "bunx" || cmd == "pnpm") {
+          args = ""
+          if (match(chunk, /"args"[ \t]*:[ \t]*\[[^]]*\]/)) args = substr(chunk, RSTART, RLENGTH)
+          if (args == "") continue
+          if (args ~ /@latest/) {
+            print file ":" line ": версия сервера не закреплена (@latest): " cmd
+            continue
+          }
+          # Имя пакета — первый довод, не начинающийся с дефиса. Точная версия пишется как
+          # name@1.2.3 (npm) или name==1.2.3 (python); без неё запуск невоспроизводим.
+          m = args
+          gsub(/"args"[ \t]*:[ \t]*\[/, "", m); gsub(/\]/, "", m)
+          k = split(m, tok, ",")
+
+          # СЕРВЕР ИЗ СВОЕГО РЕПОЗИТОРИЯ — не находка. `npx tsx rag/src/index.ts` запускает
+          # СВОЙ файл, а npx здесь только запускалка: код сервера лежит в репозитории и уже
+          # под версией — той же, что и весь проект. Требовать закрепить `tsx` значит краснеть
+          # на нормальном укладе, а такой гейт выключают в первый день. Найдено замером по
+          # двадцати чужим настройкам с GitHub 2026-09-08: две из десяти находок были ровно
+          # этим. Тот же класс, что четыре ложных срабатывания на чужом коде до этого.
+          local_entry = 0
+          for (j = 1; j <= k; j++) {
+            t = tok[j]; gsub(/^[ \t"]+|[ \t"]+$/, "", t)
+            # Признак локального входа — расширение файла или явно относительный путь.
+            # Просто «есть слэш» не годится: `@scope/name` — это имя пакета в npm, и первая
+            # версия этой проверки съела настоящую находку `npx @meridian/docs-mcp`. Поймано
+            # тем же замером по двадцати чужим настройкам: находок стало восемь вместо девяти,
+            # и пропажу было видно только построчным сравнением до и после.
+            if (t ~ /\.(ts|js|mjs|cjs|py|rb|sh)$/ || t ~ /^\//  || t ~ /^\.\// || t ~ /^\.\.\//) { local_entry = 1; break }
+          }
+          if (local_entry) continue
+
+          for (j = 1; j <= k; j++) {
+            t = tok[j]; gsub(/^[ \t"]+|[ \t"]+$/, "", t)
+            if (t == "" || substr(t, 1, 1) == "-") continue
+            if (t ~ /@[0-9]/ || t ~ /==[0-9]/) break
+            print file ":" line ": версия сервера не закреплена: " cmd " " t
+            break
+          }
+        }
+      }
+    }
+  ' "$F")
+  [ -n "$RES" ] && OUT="${OUT}${RES}
+"
+done
+
+OUT=$(printf '%s' "$OUT" | own_samples_filter "$DIR" | sed '/^$/d')
+if [ -n "$OUT" ]; then
+  printf '%s\n' "$OUT"
+  echo "  почини: закрепи точную версию (пакет@1.2.3) и убедись, что файл команды существует."
+  echo "  мёртвый сервер агенту не виден: он просто работает без этих инструментов и молчит."
+  exit 1
+fi
+exit 0

package/kit/gates/mcp-server-resolves/gate.yml

@@ -0,0 +1,18 @@
+intent: объявленный MCP-сервер существует и закреплён по версии — иначе агент молча работает без него
+intent_en: a declared MCP server exists and is version-pinned — otherwise the agent silently works without it
+
+# Только там, где агенту подключали внешние инструменты. В проекте без `.mcp.json` проверять
+# нечего, а запись, показанная не тому, стоит доверия всему каталогу.
+trigger:
+  has_mcp: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+samples_for: any
+
+proof: incidents/README.md, 2026-09-08 «конфиг был написан верно, а сервер мёртв» — в проект
+  записали настройку `chrome-devtools-mcp`, выглядела безупречно; сервер падал с «Target closed»,
+  потому что puppeteer подхватывал Windows-овый Chrome из `/mnt/c/`. Узнали только запуском
+  руками и чтением журнала: агенту мёртвый сервер не виден вовсе — у него просто нет этих
+  инструментов, и он молча работает без них

package/kit/gates/mcp-server-resolves/green/.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "browser": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@1.9.0"]
+    },
+    "search": {
+      "command": "uvx",
+      "args": ["some-search-mcp==0.4.1"]
+    },
+    "local": {
+      "command": "node",
+      "args": ["scripts/mcp-server.mjs"]
+    },
+    "own-code": {
+      "command": "npx",
+      "args": ["tsx", "rag/src/index.ts"]
+    }
+  }
+}