agent-quality-kit 0.5.0 → 0.7.0

package/kit/gates/promise-has-gate/check.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env sh
+# Обещание в точке входа подкреплено командой с кодом возврата — или честно помечено как
+# исполняемое человеком.
+#
+# ЗАЧЕМ. Это центральный вопрос всего комплекта. `AGENTS.md` — обычный текст: «никогда не
+# коммитим секреты» и «мы очень стараемся» выглядят одинаково и стоят одинаково, пока никто не
+# спросил, чем первое отличается от второго. Осенью 2026 появился целый класс линтеров обвеса
+# (agnix — 455 правил, agents-lint), и все они проверяют ДОКУМЕНТ: формат, живые ли ссылки,
+# существуют ли скрипты. Ни один не спрашивает, ИСПОЛНИМО ли обещание.
+#
+# ПОЧЕМУ ЯВНАЯ ПОМЕТКА, А НЕ УГАДЫВАНИЕ. Сопоставлять обещание с гейтом по совпадению слов —
+# значит выдавать вердикт по догадке. Пометка ставится один раз и делает документ честнее:
+# у каждого правила видно, кто его сторожит — машина или человек.
+#
+#   - **Секреты не в коде.** <!-- aqk: secrets-not-in-code -->
+#   - **План до кода.**      <!-- aqk: человек -->
+DIR="${1:-.}"
+MAN="$DIR/.aqk.yml"
+[ -f "$MAN" ] || { echo "нет .aqk.yml — проверять нечего"; exit 0; }
+MANTEXT="$(tr -d '\r' < "$MAN")"
+
+ENTRIES=$(printf '%s\n' "$MANTEXT" | awk '
+  /^entry:/ { if ($0 ~ /\[/) { s=$0; sub(/^entry:[[:space:]]*\[/,"",s); sub(/\].*$/,"",s);
+                gsub(/[[:space:]]/,"",s); n=split(s,a,","); for(i=1;i<=n;i++) print a[i]; next }
+              g=1; next }
+  /^[A-Za-z]/ { g=0 }
+  g && /^[[:space:]]*-[[:space:]]/ { s=$0; sub(/^[[:space:]]*-[[:space:]]*/,"",s);
+                gsub(/^["\x27]|["\x27]$/,"",s); print s }')
+[ -z "$ENTRIES" ] && { echo "точка входа не объявлена — проверять нечего"; exit 0; }
+
+# Объявленные гейты: их имена и есть словарь допустимых пометок.
+GATES=$(printf '%s\n' "$MANTEXT" | awk '/^gates:/{g=1;next} /^[A-Za-z]/{g=0}
+  g && /^[[:space:]]+[A-Za-z0-9_-]+:/ { sub(/^[[:space:]]*/,""); sub(/:.*$/,""); print }')
+
+OUT=""
+for E in $ENTRIES; do
+  F="$DIR/$E"
+  [ -f "$F" ] || continue
+  R=$(tr -d '\r' < "$F" | awk -v file="$E" -v gates="$GATES" '
+    # Внутри блока кода правил не бывает — там примеры.
+    /^[[:space:]]*```/ { code = !code; next }
+    code { next }
+    {
+      # Обещание — пункт списка, который либо выделен жирным (обычная форма правила), либо
+      # содержит слово долженствования или запрета. Пункт-перечисление файлов обещанием не
+      # считается: он ничего не утверждает о поведении.
+      # Только маркированный пункт. Нумерованный список — это шаги или пояснения, а не свод
+      # правил: «три вещи, которые надо понимать» в нашем же шаблоне выглядели обещаниями и
+      # требовали сторожа для утверждения о том, как устроен инструмент.
+      if ($0 !~ /^[[:space:]]*[-*][[:space:]]+/) next
+      body = $0; sub(/^[[:space:]]*[-*][[:space:]]+/, "", body)
+      isRule = (body ~ /^\*\*/) ||
+               (body ~ /никогда|всегда|обязан|обязательн|запрещ|нельзя|не должн|каждый|каждая|каждое/) ||
+               (body ~ /(^|[^a-z])(must|never|always|required|forbidden|shall)([^a-z]|$)/)
+      # Пункт-команда — не обещание. «обязательный минимум проекта прогоном: `aqk doctor`»
+      # содержит слово долженствования, но ничего не обещает: это строка справочника.
+      if (body ~ /`(node|bash|sh|npx|npm|aqk|make|python|go|cargo) /) next
+      if (!isRule) next
+
+      # Пометка: <!-- aqk: имя-гейта --> или <!-- aqk: человек -->
+      # Берём всё до закрывающей скобки комментария и уже потом обрезаем. Класс символов
+      # с исключением «-» съедал имя гейта на первом же дефисе: «deps-are-pinned» читалось
+      # как «deps», и верная пометка объявлялась ведущей в никуда.
+      if (match($0, /<!--[[:space:]]*aqk:[^>]*-->/)) {
+        tag = substr($0, RSTART, RLENGTH)
+        sub(/^<!--[[:space:]]*aqk:[[:space:]]*/, "", tag)
+        sub(/[[:space:]]*-->$/, "", tag)
+        sub(/[[:space:]]+$/, "", tag)
+        if (tag == "человек" || tag == "human") next
+        n = split(gates, G, "\n")
+        for (i = 1; i <= n; i++) if (G[i] != "" && G[i] == tag) next
+        printf "%s:%d: пометка ведёт в никуда — гейта «%s» нет в манифесте\n", file, FNR, tag
+        next
+      }
+      t = body; sub(/[[:space:]]+$/, "", t)
+      printf "%s:%d: обещание ничем не подкреплено: %s\n", file, FNR, substr(t, 1, 90)
+    }' 2>/dev/null)
+  [ -z "$R" ] || OUT="$OUT$R
+"
+done
+
+LEFT="$(printf '%s' "$OUT" | grep -v '^$')"
+[ -z "$LEFT" ] && exit 0
+printf '%s\n' "$LEFT"
+echo "  почини: у каждого правила должен быть виден сторож."
+echo "  машина: <!-- aqk: имя-гейта -->    человек: <!-- aqk: человек -->"
+echo "  правило, за которым не следит никто, через месяц отличается от лозунга только длиной."
+exit 1

package/kit/gates/promise-has-gate/gate.yml

@@ -0,0 +1,14 @@
+intent: у каждого правила в точке входа виден сторож — команда или названный человек
+intent_en: every rule in the entry point names its enforcer — a command or, honestly, a human
+
+# Там, где уже есть манифест и объявленные гейты: без них сопоставлять нечего.
+trigger:
+  has_gates: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-06 «тринадцать собственных правил без сторожа» — прогон по
+  своему же AGENTS.md показал, что ни одно из тринадцати железных правил не называет, кто за
+  ним следит; после разметки одиннадцать оказались исполняемыми человеком, и это стало видно
+  впервые

package/kit/gates/promise-has-gate/green/.aqk.yml

@@ -0,0 +1,6 @@
+aqk: 1
+entry:
+  - AGENTS.md
+rules: rules
+gates:
+  secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."

package/kit/gates/promise-has-gate/green/AGENTS.md

@@ -0,0 +1,7 @@
+# Как мы работаем
+
+## Правила
+
+- **Секреты никогда не попадают в код.** Ключи живут в окружении.  <!-- aqk: secrets-not-in-code -->
+- **Каждая функция короче пятидесяти строк.**  <!-- aqk: человек -->
+- **Обзор кода делает второй человек.** Автор не вливает сам.  <!-- aqk: человек -->

package/kit/gates/promise-has-gate/red/.aqk.yml

@@ -0,0 +1,6 @@
+aqk: 1
+entry:
+  - AGENTS.md
+rules: rules
+gates:
+  secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."

package/kit/gates/promise-has-gate/red/AGENTS.md

@@ -0,0 +1,7 @@
+# Как мы работаем
+
+## Правила
+
+- **Секреты никогда не попадают в код.** Ключи живут в окружении.
+- **Каждая функция короче пятидесяти строк.**
+- **Обзор кода делает второй человек.** Автор не вливает сам.

package/kit/gates/secrets-not-in-code/check.sh

@@ -2,7 +2,19 @@
 # Секрет, попавший в историю, из неё уже не убрать: ветку перепишут, а копии останутся у всех,
 # кто её тянул. Поэтому проверка стоит до коммита, а не «иногда руками».
 DIR="${1:-.}"
-. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+# Существование файла проверяется ДО `.`, а не запасной веткой после. Прежняя строка
+# `. файл 2>/dev/null || запасной_вариант` выглядела страховкой и ею не была: под `sh` (dash)
+# неудачный `.` завершает скрипт немедленно, и ветка после `||` не выполняется никогда; под
+# `bash`, которым гейты и запускаются из манифеста, она выполняется, но подставляет только
+# ПЕРЕМЕННУЮ — функции обхода остаются неопределёнными, конвейер печатает пустоту, и проверка
+# выходит с НУЛЁМ. Замерено 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"
 # Красный образец — намеренно сломанный код в репозитории. Сканирующий гейт обязан его
 # пропускать, иначе будет вечно краснеть на том, что сам же и положил. Исключение снимается,
 # когда проверяют сам образец: тогда каталог red и есть цель проверки.

package/kit/gates/swallowed-error/README.md

@@ -1,26 +1,44 @@
 # Ошибка не глушится молча
 
-**Намерение.** Ошибка либо обработана и записана в лог, либо проброшена дальше. Третьего нет.
+**Намерение.** Перехваченная и выброшенная ошибка — это отказ, о котором никто не узнал.
+Система продолжает работать «как будто всё хорошо», а причина всплывает через недели и в другом
+месте. Ошибка либо обработана и записана, либо проброшена дальше.
 
-**Какой отказ это поймало.** В разборе 1069 коммитов за 90 дней: **1436 блоков перехвата, из
-которых лишь около 10% пробрасывают ошибку дальше.** Остальные глушат её в лог или возвращают
-пустоту. Цена — три недели поиска источника отказов, которые гасились на месте.
-Запись в журнале: `incidents/README.md`, 2026-08-25.
+**Своей проверки здесь больше нет — так решил замер.** Переносимая версия искала перехват по
+тексту. Прогон по пяти чужим репозиториям (`httpx`, `fastapi`, `zod`, `cobra`, `ripgrep`) дал
+46 находок, и настоящим оказался ровно один класс — пустые `catch (_) {}` в `zod`. Остальное:
 
-**Почему машина, а не внимательность.** Пустой перехват выглядит безобидно и пишется быстрее
-правильного. В ревью на 400 строк он не читается как дефект — он читается как аккуратность.
+```python
+try:
+    if sniffio.current_async_library() == "trio":
+        return True
+except ImportError:   # библиотеки нет — значит не trio. Это не глушение, это ветвление.
+    pass
+```
 
-**Что именно ищется.** Перехват с пустым телом: `except …: pass` и `…: ...` в Python, пустой
-`catch (…) { }`, пустой `.catch(() => {})`.
+```rust
+let _ = self.wtr.write(b"\n")?;   // «?» пробрасывает ошибку. Отброшено только число байт.
+```
 
-**Чего НЕ ловит.** Перехват, который что-то делает, но не то: записал в лог на уровне `debug` и
-вернул пустоту — формально не пустой, по сути тот же тихий отказ. Это остаётся человеку.
+Питоновский `except <узкое исключение>: pass` — законный приём: ловят не ошибку, а её отсутствие.
+Растовый `let _ = …?` вообще ничего не глушит. Отличить это от настоящего глушения можно только
+разбором кода — а разбор уже написан.
 
-**Готовый аналог есть, и он подробнее.** В Python три правила `ruff`
-покрывают разные оттенки: `BLE` — ловля голого исключения, `TRY400` — запись в лог без трейса,
-`SIM105` — перехват ради тишины. В TypeScript — `no-empty` с запретом пустого перехвата.
-Измерено на живом проекте: `TRY400` нашёл 47 мест, которые самописный разбор искал час.
-Рецепты под эти стеки берут готовое; своя проверка — запасная.
+**Готовый аналог — это и есть он сам.**
 
-**Образцы.** `red/` — Python и JavaScript с пустым перехватом. `green/` — тот же код: запись в
-лог и проброс.
+| Стек | Чем |
+|---|---|
+| Python | `ruff --select BLE,TRY400,SIM105` |
+| JavaScript, TypeScript | `eslint no-empty` с `allowEmptyCatch: false` |
+| Go | [`errcheck`](https://github.com/kisielk/errcheck) — канонический инструмент под этот предмет |
+
+**Чего НЕ ловит.** Перехват, который что-то делает, но делает не то: `except: return None`,
+`catch { return [] }`. Формально обработка есть, по сути ошибка потеряна так же. Это видно
+только глазами и на ревью. Для Rust рецепта нет: у `clippy` есть близкие правила
+(`let_underscore_must_use`), но мы их не замеряли, а рецепт без замера — та же догадка,
+из-за которой эта запись и лишилась своей проверки.
+
+**Чем это оплачено.** Проект на Rust, Java, Ruby, PHP по этому пункту не получает ничего.
+
+**Образцы.** `red/loader.py` — `except Exception: pass`. `green/loader.py` — узкое исключение,
+запись в журнал и проброс. Проверяются рецептом `python` (`samples_for`).

package/kit/gates/swallowed-error/gate.yml

@@ -1,13 +1,23 @@
 intent: ошибка не глушится молча — она обработана и записана либо проброшена
 intent_en: an error is not silently swallowed — it is handled and logged, or re-raised
 
+# Только языки, под которые есть готовый разбор кода. Переносимой проверки здесь больше нет:
+# отличить «перехват ради тишины» от законного `except ImportError: pass` можно разбором,
+# а не поиском по тексту.
 trigger:
-  always: true
+  langs: python, javascript, typescript, go
 
 recipes:
-  any: bash {gate}/check.sh {dir}
   # BLE — ловля голого исключения, TRY400 — запись без трейса, SIM105 — перехват ради тишины.
   python: ruff check --select BLE,TRY400,SIM105 {dir}
   typescript: eslint --rule '{"no-empty":["error",{"allowEmptyCatch":false}]}' {dir}
+  javascript: eslint --rule '{"no-empty":["error",{"allowEmptyCatch":false}]}' {dir}
+  # errcheck — канонический инструмент Go под этот же предмет: ошибка присвоена и не проверена.
+  go: errcheck -blank {dir}/...
 
-proof: incidents/README.md — «2026-08-25 разбор 1069 коммитов»: 1436 блоков перехвата, лишь 10% пробрасывают ошибку
+samples_for: python
+
+proof: incidents/README.md, 2026-09-07 «замер по пяти стекам вынес приговор пяти записям» —
+  переносимая версия дала 46 находок на пяти чужих репозиториях, настоящими оказались только
+  пустые `catch {}` в zod; весь питоновский класс `except ImportError: pass` и растовый
+  `let _ = write(..)?` были ложными

package/kit/gates/test-has-assertion/README.md

@@ -0,0 +1,47 @@
+# Тест умеет провалиться
+
+**Намерение.** «Почини тесты» агент решает буквально: тело теста пустеет, утверждение
+заменяется тавтологией, тест помечается пропуском. Все три способа дают ровно то, что просили —
+зелёный прогон, — и ни один не виден в сводке. Покрытие при этом растёт.
+
+**Какой отказ это поймало.** Замер по девятнадцати чужим репозиториям (15 инструментов и 4
+прикладных, около 25 000 файлов): 8 находок. Шесть — выключенные тесты без единого слова
+о причине в `swr`, библиотеке с тридцатью тысячами звёзд; два — в `kodus-ai`. Запись в журнале:
+`incidents/README.md`, 2026-09-06.
+
+**Что именно проверяется.** Три случая, в которых тест не может провалиться ни при каких данных:
+
+| Красное | Почему |
+|---|---|
+| тело теста пустое (`pass`, `...`, только докстрока, пустые фигурные скобки) | выполнять нечего |
+| утверждение-тавтология (`assert True`, `expect(true).toBe(true)`, `assert 1 == 1`) | истинно всегда |
+| пропуск без причины (`@pytest.mark.skip`, `it.skip(…)`, `xit(…)`, `@Ignore`) | тест выключен, и неизвестно, до каких пор |
+
+Причина у пропуска засчитывается в трёх формах: `reason=` в той же строке, `reason=` в
+продолжении многострочного декоратора и объясняющий комментарий над тестом. Это не придирка к
+форме: комментарий сверху — самая частая запись причины, и на замере все находки такого вида
+оказались законными.
+
+**Готовый аналог.** Есть, и частями:
+[`flake8-pytest-style`](https://github.com/m-burst/flake8-pytest-style) и
+[`pylint`](https://pylint.readthedocs.io/) ловят часть питоновских случаев;
+[`eslint-plugin-jest`](https://github.com/jest-community/eslint-plugin-jest) — правила
+`expect-expect`, `no-disabled-tests`, `valid-expect` — заметно точнее нас на JavaScript, потому
+что разбирает синтаксис. Если проект на одном языке — ставь их. Эта запись нужна там, где
+языков несколько или где ставить нечего.
+
+**Чего НЕ ловит.**
+
+- **Тест без утверждения, но с телом.** Вызвали код, проверили, что не упал, — законный стиль:
+  утверждение там в самом отсутствии исключения. Первая версия красила такие тесты и дала
+  186 находок в двух зрелых проектах — все до одной ложные. Правило снято намеренно.
+- **Тест, утверждающий не то.** `assert response.status_code` вместо `== 200` — проверка
+  отвечает на вопрос «может ли тест провалиться», а не «то ли он проверяет».
+- **Языки, кроме python, javascript и typescript, — только частично.** Пустое тело в Go или Ruby
+  не разбирается; тавтологии и пропуски ловятся во всех перечисленных расширениях.
+- **Голый `t.Skip()` в Go.** На замере 9 находок из 13 оказались условным пропуском по
+  переменной окружения — это управление прогоном, а не выключенный тест. Правило снято.
+- **Скобки внутри строковых литералов считаются наравне с настоящими.** Границы тела теста
+  определяются балансом скобок; точный ответ требует разбора языка, а его у переносимой
+  проверки нет. Строки внутри незакрытых шаблонных литералов пропускаются целиком — иначе
+  тесты, лежащие в фикстурах как текст, читались бы как настоящие.

package/kit/gates/test-has-assertion/check.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env sh
+# Тест, который не может провалиться: прогон зелёный, покрытие выросло, проверено ничего.
+#
+# ЗАЧЕМ ИМЕННО ЭТО. «Почини тесты» агент решает буквально: тело теста пустеет, утверждение
+# заменяется тавтологией, тест помечается пропуском. Все три способа дают ровно то, что просили
+# — зелёный прогон, — и ни один не виден в сводке. Это тот же класс, что молчащий гейт: сигнал
+# исчез, а уверенность осталась.
+#
+# ГРАНИЦА НАЙДЕНА ЗАМЕРОМ, А НЕ ВЫДУМАНА. Первая версия красила «тест без утверждения» и дала
+# 186 находок в двух зрелых проектах — все до одной оказались тестами вида «вызвали и проверили,
+# что не упало». Это законный и распространённый стиль: утверждение там в самом отсутствии
+# исключения. Гейт, спорящий о стиле, выключают целиком, поэтому здесь остались только
+# безусловные случаи — те, где тест не может провалиться ни при каких данных.
+DIR="${1:-.}"
+# Существование файла проверяется ДО `.`, а не запасной веткой после. Прежняя строка
+# `. файл 2>/dev/null || запасной_вариант` выглядела страховкой и ею не была: под `sh` (dash)
+# неудачный `.` завершает скрипт немедленно, и ветка после `||` не выполняется никогда; под
+# `bash`, которым гейты и запускаются из манифеста, она выполняется, но подставляет только
+# ПЕРЕМЕННУЮ — функции обхода остаются неопределёнными, конвейер печатает пустоту, и проверка
+# выходит с НУЛЁМ. Замерено 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"
+
+# Только файлы тестов. Слово «assert» в обычном коде — не тест, а проверка входа.
+FILES=$(find "$DIR" $(skip_find) -type f \( \
+    -name 'test_*.py' -o -name '*_test.py' -o -name 'tests.py' \
+    -o -name '*.test.js' -o -name '*.test.jsx' -o -name '*.test.ts' -o -name '*.test.tsx' \
+    -o -name '*.test.mjs' -o -name '*.spec.js' -o -name '*.spec.jsx' -o -name '*.spec.ts' \
+    -o -name '*.spec.tsx' -o -name '*.spec.mjs' \
+    -o -name '*_test.go' -o -name '*_test.rb' -o -name '*_spec.rb' \) -print 2>/dev/null)
+[ -z "$FILES" ] && { echo "файлов тестов не нашлось — эта проверка не про тебя"; exit 0; }
+
+# Сгенерированный файл правят не руками: тест в нём написал инструмент. Признак проверяется
+# внутри awk по первым строкам, а не циклом с `head` на файл.
+#
+# ПОЧЕМУ БЕЗ ЦИКЛА. Накопление списка строкой («KEEP="$KEEP $F"») — квадрат по длине: оболочка
+# копирует растущую строку на каждой итерации. На соседней проверке это дало 44 секунды вместо
+# одной на том же репозитории.
+
+# Тройная одинарная кавычка нужна разбору докстрок, но написать её внутри awk-программы нельзя:
+# она закроет кавычки самой программы. Передаём переменной.
+Q3="'''"
+
+# ОДИН вызов awk на все файлы, а не по вызову на файл: запуск процесса стоит дороже разбора.
+# На репозитории в 7128 файлов проверка занимала 49 секунд, и почти всё это были запуски.
+# shellcheck disable=SC2086
+OUT=$(awk -v q3="$Q3" '
+  # --- что считается безусловно сломанным ------------------------------------
+  function tautology(l) {
+    return l ~ /assert[[:space:]]+(True|true|1)[[:space:]]*($|#)/ ||
+           l ~ /assert(True|Equal)\((True|true|1)([[:space:]]*,[[:space:]]*(True|true|1))?\)/ ||
+           l ~ /expect\((true|1)\)\.(toBe|toEqual)\((true|1)\)/ ||
+           l ~ /assert[[:space:]]+[0-9]+[[:space:]]*==[[:space:]]*[0-9]+/
+  }
+  # Пропуск без причины. С причиной — законный приём: тест ждёт починки, и это записано.
+  # Голый `t.Skip()` из Go сюда НЕ входит: на замере 9 находок из 13 оказались условным
+  # пропуском по переменной окружения — это управление прогоном, а не выключенный тест.
+  function bareSkip(l) {
+    return (l ~ /@(pytest\.mark\.)?skip([[:space:]]*$|\()/ && !reasonNear(l)) ||
+           (l ~ /(^|[^a-zA-Z])(x?it|x?describe|test)\.skip\(/ && l !~ /--|TODO|[Ii]ssue|#[0-9]/) ||
+           (l ~ /(^|[^a-zA-Z])(xit|xdescribe)\(/) ||
+           (l ~ /@Ignore([[:space:]]*$|\(\))/)
+  }
+  # Строка, которая ничего не делает: заглушка, докстрока, комментарий, хвост из скобок.
+  # Сравнением строк, а не регулярным выражением: тройная одинарная кавычка внутри
+  # awk-программы закрыла бы кавычки оболочки.
+  function isNoop(b,   t) {
+    t = b; sub(/^[[:space:]]+/, "", t); sub(/[[:space:]]+$/, "", t)
+    if (t == "" || t == "pass" || t == "..." || t == "return") return 1
+    if (substr(t, 1, 1) == "#") return 1
+    if (substr(t, 1, 3) == "\"\"\"" || substr(t, 1, 3) == q3) return 1
+    if (substr(t, 1, 2) == "//" || substr(t, 1, 2) == "/*" || substr(t, 1, 1) == "*") return 1
+    if (t ~ /^[])};,[:space:]]+$/) return 1
+    return 0
+  }
+  function trim(x) { sub(/^[[:space:]]+/, "", x); return substr(x, 1, 80) }
+  # Причина, записанная комментарием НАД пропуском, — нормальная форма, и она встречается чаще
+  # инлайновой: на замере все 4 оставшиеся находки оказались именно такими, с подробным
+  # объяснением в трёх строках выше. Требование писать причину в той же строке — придирка к
+  # форме, а придирки к форме и есть то, из-за чего гейты выключают.
+  # Причина у пропуска может стоять на следующей строке: многострочный декоратор
+  # «@pytest.mark.skip(\n  reason="…"\n)» — обычная форма, когда причина длинная.
+  function reasonNear(l,   k) {
+    if (l ~ /reason[[:space:]]*=/) return 1
+    if (l !~ /\($/ && l !~ /\([[:space:]]*$/) return 0
+    for (k = cursor + 1; k <= n && k <= cursor + 4; k++) {
+      if (line[k] ~ /reason[[:space:]]*=/) return 1
+      if (line[k] ~ /^[[:space:]]*\)/) return 0
+    }
+    return 0
+  }
+  function explainedAbove(i,   k, t, w) {
+    for (k = i - 1; k >= 1 && k >= i - 4; k--) {
+      t = line[k]; sub(/^[[:space:]]+/, "", t)
+      if (t == "") continue
+      if (substr(t, 1, 2) != "//" && substr(t, 1, 1) != "#" && substr(t, 1, 1) != "*") return 0
+      w = split(t, _unused, /[[:space:]]+/)
+      if (w >= 4) return 1
+    }
+    return 0
+  }
+  # Баланс круглых скобок со строки a по строку b, через префиксные суммы. Пересчёт от a при
+  # каждом обращении давал кубическую сложность и не укладывался в две минуты на большом
+  # репозитории. Приближение: скобки внутри строковых литералов считаются наравне с
+  # настоящими — точный ответ требует разбора языка, а его у переносимой проверки нет.
+  function bal(a, b) { return pre[b] - pre[a - 1] }
+  function balBrace(a, b) { return prb[b] - prb[a - 1] }
+
+  # Границы файла: awk без gawk не знает ENDFILE, поэтому предыдущий файл разбирается на первой
+  # строке следующего, а последний — в END. Буферы обнуляются вместе с именем: общий буфер
+  # склеил бы скобки соседних файлов и сдвинул все границы.
+  FNR == 1 { if (n > 0) report(); n = 0; delete line; delete pre; delete prb; delete tck; cur = FILENAME; skipFile = 0 }
+  FNR <= 5 && /@[Gg]enerated|[Dd]o not edit|DO NOT EDIT|[Aa]utogenerated|[Aa]uto-generated|[Gg]enerated by|сгенерирован/ { skipFile = 1 }
+  {
+    n++; line[n] = $0
+    t = $0; o = gsub(/\(/, "(", t); t = $0; c = gsub(/\)/, ")", t)
+    pre[n] = pre[n - 1] + o - c
+    t = $0; o = gsub(/\{/, "{", t); t = $0; c = gsub(/\}/, "}", t)
+    prb[n] = prb[n - 1] + o - c
+    # Чётность обратных кавычек. Строка внутри незакрытого шаблонного литерала — это ДАННЫЕ,
+    # а не код: проекты, которые проверяют чужой код, держат в таких литералах целые файлы с
+    # тестами внутри. Три находки из четырёх на замере пришли ровно оттуда.
+    t = $0; tck[n] = tck[n - 1] + gsub(/`/, "`", t)
+  }
+  END { if (n > 0) report() }
+
+  function report(   i, j, l, t0, e, ind, start, found, hasBody, b, bi) {
+    if (skipFile) return
+    for (i = 1; i <= n; i++) {
+      l = line[i]; cursor = i
+      if (l ~ /^[[:space:]]*(#|\/\/|\*)/) continue
+      if (tautology(l) && !explainedAbove(i)) {
+        printf "%s:%d: утверждение-тавтология: %s\n", cur, i, trim(l); continue
+      }
+      if (bareSkip(l) && !explainedAbove(i)) {
+        printf "%s:%d: тест пропущен без названной причины: %s\n", cur, i, trim(l); continue
+      }
+
+      # --- python: тело ограничено отступом -----------------------------------
+      if (l ~ /^[[:space:]]*(async[[:space:]]+)?def[[:space:]]+test[_A-Za-z0-9]*[[:space:]]*\(/) {
+        # Тело в той же строке — это не тест, а вложенная функция-фикстура: «def test_function():
+        # ...» внутри настоящего теста. Настоящий тест так не пишут. Найдено замером на
+        # sentry-python, где такая фикстура объявлялась пустым тестом.
+        if (bal(i, i) <= 0 && l !~ /:[[:space:]]*(#.*)?$/) continue
+        match(l, /^[[:space:]]*/); ind = RLENGTH; found = 0
+        # Подпись бывает на несколько строк, и её закрывающая «):» стоит на отступе самого def.
+        # Пока тело искали прямо со следующей строки, эта скобка обрывала поиск: тест объявляли
+        # пустым, ни разу не заглянув внутрь. 142 ложных в одном pre-commit.
+        start = i
+        for (j = i; j <= n; j++) { start = j; if (bal(i, j) <= 0 && line[j] ~ /:[[:space:]]*(#.*)?$/) break }
+
+        for (j = start + 1; j <= n; j++) {
+          b = line[j]
+          if (b ~ /^[[:space:]]*$/) continue
+          match(b, /^[[:space:]]*/); bi = RLENGTH
+          if (bi <= ind) break
+          if (!isNoop(b)) { found = 1; break }
+        }
+        if (!found) printf "%s:%d: тело теста пустое — он не может провалиться: %s\n", cur, i, trim(l)
+        continue
+      }
+
+      # --- javascript и typescript: тело ограничено круглой скобкой вызова ----
+      # ВЫЗОВ В НАЧАЛЕ СТРОКИ, а не слово «test» где угодно. Пока проверялось вхождение,
+      # красным становилось всё подряд: объявление обычной функции с таким именем, тот же текст
+      # внутри строковой фикстуры с дифом, он же аргументом в toContain. 51 ложная из 60.
+      if (tck[i - 1] % 2 == 1) continue
+      t0 = l; sub(/^[[:space:]]+/, "", t0)
+      if (t0 ~ /^(await[[:space:]]+)?(it|test)(\.[A-Za-z]+)?[[:space:]]*\(/) {
+        # Границей служит КРУГЛАЯ скобка вызова, а не фигурная скобка тела: многострочный вызов
+        # с объектом настроек между именем и телом обрывался на этом объекте — скобка
+        # открылась и закрылась, тело сочли пустым. 1460 ложных из 1843.
+        # Конец вызова — когда закрылись И круглые, И фигурные скобки. По одним круглым
+        # строка `for (const p of ["a)b"]) {` закрывала вызов раньше времени: скобка внутри
+        # строкового литерала считается наравне с настоящей. Фигурная скобка тела там ещё
+        # открыта, и это отличает настоящий конец от мнимого.
+        e = i
+        for (j = i; j <= n; j++) { e = j; if (bal(i, j) <= 0 && balBrace(i, j) <= 0) break }
+        hasBody = 0
+        for (j = i; j <= e; j++) if (line[j] ~ /=>|function/) hasBody = 1
+        if (!hasBody) continue
+        found = 0
+        # Однострочная запись: тело живёт на той же строке («it("…", () => expectPass(…));»).
+        # Пока сканировали только следующие строки, такой тест объявлялся пустым.
+        if (e == i && t0 ~ /=>[^)]*[A-Za-z]/) continue
+        # Включая строку e: у стрелочной функции без фигурных скобок тело живёт ровно на ней
+        # («it("…", () =>\n  expectPass(…));»). Пока сканировали до e-1, такие тесты объявлялись
+        # пустыми — 15 ложных из 21 на замере.
+        for (j = i + 1; j <= e; j++) if (!isNoop(line[j])) { found = 1; break }
+        if (!found) printf "%s:%d: тело теста пустое — он не может провалиться: %s\n", cur, i, trim(l)
+      }
+    }
+  }
+' $FILES 2>/dev/null)
+
+LEFT="$(printf '%s' "$OUT" | grep -v '^$' | own_samples_filter "$DIR")"
+[ -z "$LEFT" ] && exit 0
+printf '%s\n' "$LEFT"
+echo "  почини: тест обязан уметь провалиться. Пропуск — с названной причиной («reason=…», ссылка на задачу)."
+echo "  зелёный прогон без проверки — это уверенность без основания, худший из возможных исходов."
+exit 1

package/kit/gates/test-has-assertion/gate.yml

@@ -0,0 +1,15 @@
+intent: тест умеет провалиться — тело не пустое, утверждение не тавтология, пропуск с причиной
+intent_en: a test can actually fail — no empty body, no tautology, no skip without a reason
+
+# Там, где есть тесты. Триггер по наличию, а не по языку: разбор покрывает python, javascript
+# и typescript, а пропуски и тавтологии ловятся во всех перечисленных расширениях.
+trigger:
+  has_tests: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-06 «граница проверки найдена замером» — прогон по
+  девятнадцати чужим репозиториям (около 25 000 файлов) даёт 8 находок: шесть выключенных
+  тестов без причины в `swr` (30 000 звёзд) и два в `kodus-ai`. Первая версия давала 1843
+  находки, из них 1843 ложных

package/kit/gates/test-has-assertion/green/checkout.test.ts

@@ -0,0 +1,9 @@
+import { checkout } from "./checkout";
+
+it("считает корзину", async () => {
+  expect(await checkout({ items: [1, 2] })).toEqual({ total: 3 });
+});
+
+it("не падает на пустой корзине", async () => {
+  await checkout({ items: [] });
+});

package/kit/gates/test-has-assertion/green/test_billing.py

@@ -0,0 +1,17 @@
+import pytest
+
+
+def test_total_is_summed():
+    order = {"items": [{"price": "1.50"}, {"price": "2.50"}]}
+    assert total(order) == 4
+
+
+# Тест, который проверяет «не падает», — законный стиль: утверждение здесь в самом отсутствии
+# исключения. Эта запись про выключенный тест, а не про то, как его следует писать.
+def test_import_does_not_explode():
+    build_report({"items": []})
+
+
+@pytest.mark.skip(reason="ждёт песочницы платёжного шлюза, задача PAY-214")
+def test_refund_is_reversible():
+    assert refund(pay(100)) == 0

package/kit/gates/test-has-assertion/red/checkout.test.ts

@@ -0,0 +1,8 @@
+import { checkout } from "./checkout";
+
+it("считает корзину", async () => {
+});
+
+it("не пускает пустую корзину", () => {
+  expect(true).toBe(true);
+});

package/kit/gates/test-has-assertion/red/test_billing.py

@@ -0,0 +1,14 @@
+import pytest
+
+
+def test_total_is_summed():
+    pass
+
+
+def test_currency_is_kept():
+    assert True
+
+
+@pytest.mark.skip
+def test_refund_is_reversible():
+    assert refund(pay(100)) == 0