agent-quality-kit 0.5.0 → 0.6.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/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,194 @@
+#!/usr/bin/env sh
+# Тест, который не может провалиться: прогон зелёный, покрытие выросло, проверено ничего.
+#
+# ЗАЧЕМ ИМЕННО ЭТО. «Почини тесты» агент решает буквально: тело теста пустеет, утверждение
+# заменяется тавтологией, тест помечается пропуском. Все три способа дают ровно то, что просили
+# — зелёный прогон, — и ни один не виден в сводке. Это тот же класс, что молчащий гейт: сигнал
+# исчез, а уверенность осталась.
+#
+# ГРАНИЦА НАЙДЕНА ЗАМЕРОМ, А НЕ ВЫДУМАНА. Первая версия красила «тест без утверждения» и дала
+# 186 находок в двух зрелых проектах — все до одной оказались тестами вида «вызвали и проверили,
+# что не упало». Это законный и распространённый стиль: утверждение там в самом отсутствии
+# исключения. Гейт, спорящий о стиле, выключают целиком, поэтому здесь остались только
+# безусловные случаи — те, где тест не может провалиться ни при каких данных.
+DIR="${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+
+# Только файлы тестов. Слово «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

package/kit/rules/general.md

@@ -7,6 +7,20 @@
 - **Ни одного тихого отказа.** Ошибка обработана и записана либо проброшена.
 - **Границы явные.** На стыках — проверка входа, а не доверие.
 
+## Сомнение — повод посмотреть наружу
+
+Агент отвечает уверенно всегда: и когда знает, и когда достраивает по памяти. Со стороны это
+неотличимо, а цена разная. Поэтому четыре случая обязаны кончаться поиском, а не догадкой:
+
+| Случай | Что происходит без поиска |
+|---|---|
+| не знаешь, как принято **сейчас** | пишется то, что было принято на момент обучения |
+| не знаешь, есть ли **готовое** | пишется свой велосипед, который потом чинить самому |
+| собираешься написать распространённую вещь | половина работы уже сделана кем-то и проверена |
+| помнишь ответ, но **из обучения, а не из проверки** | вспомненный API мог быть переименован или убран |
+
+Правило дешевле, чем кажется: поиск стоит минуту, а неверная догадка — правку, ревью и шишку.
+
 ## Запрещено в готовом коде
 
 - отладочная печать;

package/llms.txt

@@ -22,6 +22,7 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
   `npx agent-quality-kit doctor --baseline` (14 of 50 points confirmed by a run, ecosystem-neutral;
   the other 36 are named as a number, not hidden)
 - Fail a pipeline below a level or on a failed gate: `npx agent-quality-kit doctor --run --min 1`
+- Show only what a diff introduced, so a legacy repo is usable from day one: `doctor --run --since main`
 - Exit codes: 0 pass, 1 below the level or a gate failed
 - As a pre-commit hook: `repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit` with
   `id: aqk` (blocking), `aqk-doctor` (read-only) or `aqk-baseline`. pre-commit installs the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Turns the rules an agent is supposed to follow into commands with exit codes, and reports which of them actually run. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -43,7 +43,8 @@
   ],
   "knip": {
     "entry": [
-      "tool/selfcheck/units.mjs"
+      "tool/selfcheck/units.mjs",
+    "tool/selfcheck/lifecycle.mjs"
     ],
     "project": [
       "tool/**/*.mjs"

package/tool/commands/doctor.mjs

@@ -3,7 +3,8 @@
 import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists } from "../lib/core.mjs";
+import { scopeOutput, changedFiles } from "../lib/scope.mjs";
+import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists, die } from "../lib/core.mjs";
 import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict, recipeFor } from "../lib/repo.mjs";
 import { assessBaseline, DEP_FILES, BASELINE_TOTAL } from "../lib/baseline.mjs";
@@ -94,10 +95,27 @@ function declaredGates(man) {
     .filter(([, cmd]) => cmd);
 }
 
-function runGates(man) {
+// Ссылка, относительно которой сужается вывод: `--since main`, `--since HEAD~5`.
+// Без значения флаг бессмыслен — молча взять умолчание нельзя: «сужено не тем» неотличимо
+// от «не сужено».
+function sinceRef(argv = process.argv) {
+  const i = argv.indexOf("--since");
+  if (i === -1) return null;
+  const v = argv[i + 1];
+  return v && !v.startsWith("-") ? v : null;
+}
+
+function runGates(man, opts = {}) {
   const gates = declaredGates(man);
   if (!gates.length) return { failed: 0, ran: 0, results: [] };
 
+  // Сужение по дифу — договор с человеком, и он должен видеть, ЧТО именно сужено. Пустой диф
+  // называется вслух: иначе «все гейты зелёные» означало бы «сравнили не с тем» и читалось бы
+  // как успех. Это тот же класс, что и весь стандарт, только внутри нашего флага.
+  const scoped = opts.since ? changedFiles(opts.since, CWD) : null;
+  if (opts.since && scoped === null) die(L.doctor.sinceBadRef(opts.since));
+  if (scoped) console.log(c.dim(`\n  ${L.doctor.sinceHeading(opts.since, scoped.size)}`));
+
   console.log(c.bold(`\n  ${L.doctor.runHeading}\n`));
   let failed = 0;
   const results = [];
@@ -118,8 +136,30 @@ function runGates(man) {
       console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${cmd}`)}`);
       results.push({ name, cmd, ok: true, secs });
     } else {
+      let out = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
+
+      // Сужение до дифа. Три исхода, и все три называются вслух.
+      if (scoped) {
+        const s = scopeOutput(out, scoped);
+        if (!s.scopable) {
+          // Гейт печатает вердикт без путей — сузить нечем. Признать его успешным значило бы
+          // выдать провал за тишину; остаётся красным, и причина названа.
+          console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${L.doctor.notScopable}`)}`);
+          failed++;
+          results.push({ name, cmd, ok: false, secs, code, note: L.doctor.notScopable });
+          continue;
+        }
+        if (s.findings === 0) {
+          // Долг есть, но не в том, что внёс диф. Зелёный — но с числом спрятанного: молчаливое
+          // «всё хорошо» здесь было бы неправдой.
+          console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${L.doctor.outsideDiff(out.length)}`)}`);
+          results.push({ name, cmd, ok: true, secs, scopedAway: out.length });
+          continue;
+        }
+        out = s.kept;
+      }
+
       failed++;
-      const out = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
       console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${secs}s · ${cmd}`)}`);
       for (const line of out.slice(0, 3)) console.log(c.dim(`        ${line.slice(0, 100)}`));
       if (out.length > 3) console.log(c.dim(`        ${L.doctor.moreLines(out.length - 3)}`));
@@ -247,7 +287,7 @@ async function cmdDoctor() {
   let gateFailed = 0;
   let failedNames = [];
   if (wantRun) {
-    const run = runGates(man);
+    const run = runGates(man, { since: sinceRef() });
     gateFailed = run.failed;
     failedNames = run.results.filter((r) => !r.ok).map((r) => r.name);
     await writeRunReport({ version, reached, results: run.results });

package/tool/commands/gates.mjs

@@ -8,7 +8,7 @@ import {
   CWD, PKG_ROOT, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB, MANIFEST, SELF, c, exists, die,
   copyDir,
 } from "../lib/core.mjs";
-import { parseManifest, readManifest, manifestWithGate } from "../lib/manifest.mjs";
+import { parseManifest, readManifest, manifestWithGate, entryLifecycle } from "../lib/manifest.mjs";
 import {
   detectFacts, readCatalog, pickRecipe, triggerVerdict, stems, overlap, matchCatalog,
 } from "../lib/repo.mjs";
@@ -28,6 +28,13 @@ async function installGate(slug, man, facts) {
   if (!(await exists(src))) die(L.add.noSuchGate(slug, `${SELF} doctor`));
 
   const rec = { slug, ...parseManifest(await readFile(join(src, "gate.yml"), "utf8")) };
+
+  // Выведенную запись не ставим. Молча пропустить нельзя — человек пришёл за конкретной
+  // проверкой и обязан узнать, кто её заменил; ответ «а что теперь» и есть цена вывода.
+  // Проверка ДО копирования: иначе в проекте остаётся папка гейта, которого не будет в манифесте.
+  const life = entryLifecycle(rec);
+  if (life.state === "deprecated") return { rec, cmd: null, copied: [], declared: false, why: null, retired: life.supersededBy || "" };
+
   const dst = join(CWD, PROJECT_GATES, slug);
   await mkdir(dst, { recursive: true });
   const copied = await copyDir(src, dst, { force: false });
@@ -87,7 +94,8 @@ async function cmdAdd(args) {
     console.log(c.dim(`  ${L.add.installAnyway}\n`));
   }
 
-  const { cmd, copied, declared, why, noRecipe } = await installGate(slug, man, facts);
+  const { cmd, copied, declared, why, noRecipe, retired } = await installGate(slug, man, facts);
+  if (retired !== undefined) die(L.lifecycle.installDeprecated(slug, retired ? `${SELF} add ${retired}` : "—"));
   if (noRecipe) die(L.add.noRecipe(slug, [...facts.langs].join("/") || L.add.thisStack));
 
   console.log(c.bold(`\naqk add ${slug}\n`));