agent-quality-kit 0.2.2

package/kit/gates/dead-code/green/mod.py

@@ -0,0 +1,9 @@
+def used():
+    return 1
+
+
+def also_used():
+    return 2
+
+
+print(used(), also_used())

package/kit/gates/dead-code/red/mod.py

@@ -0,0 +1,9 @@
+def used():
+    return 1
+
+
+def never_called():
+    return 2
+
+
+print(used())

package/kit/gates/deps-are-pinned/README.md

@@ -0,0 +1,29 @@
+# Версии зависимостей закреплены
+
+**Намерение.** Рядом с объявлением зависимостей лежит файл с точными версиями, и он в
+репозитории.
+
+**Какой отказ это поймало.** Обязательный минимум проекта требует точных версий всего, что
+участвует в сборке. Проверки на это не стояло нигде.
+Запись в журнале: `incidents/README.md`, 2026-08-27.
+
+**Почему это важнее, чем кажется.** Без закреплённых версий среда разъезжается между машиной
+разработчика, конвейером и сервером. Это класс ошибок, который **невозможно поймать тестами**:
+тесты зелёные у всех, а падает у одного. «У меня работает» становится неопровержимым, потому что
+сравнить нечего.
+
+**Что именно проверяется.** Для каждого найденного объявления зависимостей — наличие
+соответствующего файла с закреплёнными версиями. Для `requirements.txt` иначе: там закрепление
+живёт в самом файле, поэтому проверяется, что версии указаны через `==`, а не «не ниже такой-то».
+
+**Пустое объявление пропускается.** Проект без единой зависимости закреплять нечем: пакетный
+менеджер не создаст файл версий там, где версий нет. Требовать его значило бы красить гейт на
+пустом месте — а такой гейт выключают.
+
+**Чего НЕ ловит.** Что файл свежий: он может быть от прошлого года и не совпадать с объявлением.
+Это ловится командой пакетного менеджера, а не наличием файла.
+
+**Готового аналога нет** — ни в линтерах, ни в пакетных менеджерах: они
+умеют создать файл версий, но не умеют требовать, чтобы он существовал и лежал в репозитории.
+
+**Образцы.** `red/` — объявление зависимостей без закрепления. `green/` — с ним.

package/kit/gates/deps-are-pinned/check.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env sh
+# Рядом с объявлением зависимостей обязан лежать файл с закреплёнными версиями. Без него
+# завтрашняя сборка соберёт другое, и «у меня работает» становится неопровержимым: сравнить
+# нечего.
+DIR="${1:-.}"
+BAD=0
+
+# Объявление без единой зависимости закреплять нечем и незачем: пакетный менеджер не создаст
+# файл версий там, где версий нет. Требовать его — красить гейт на пустом месте.
+has_deps_declared() {
+  case "$1" in
+    package.json)  grep -qE '"(dependencies|devDependencies|peerDependencies)"[[:space:]]*:[[:space:]]*\{[[:space:]]*"' "$DIR/$1" ;;
+    # go.sum вообще не создаётся, если модуль использует только стандартную библиотеку —
+    # требовать его там означает красить гейт на пустом месте, а не ловить нарушение.
+    go.mod)        grep -qE '^require\b' "$DIR/$1" ;;
+    *)             return 0 ;;
+  esac
+}
+
+need() {
+  MANIFEST="$1"; shift
+  [ -f "$DIR/$MANIFEST" ] || return 0
+  has_deps_declared "$MANIFEST" || return 0
+  for LOCK in "$@"; do
+    [ -f "$DIR/$LOCK" ] && return 0
+  done
+  echo "$MANIFEST: нет файла с закреплёнными версиями (ожидался один из: $*)"
+  echo "  почини: создай его командой пакетного менеджера и положи в репозиторий."
+  BAD=1
+}
+
+need package.json  package-lock.json yarn.lock pnpm-lock.yaml npm-shrinkwrap.json
+need pyproject.toml poetry.lock uv.lock pdm.lock
+need go.mod        go.sum
+need Cargo.toml    Cargo.lock
+need Gemfile       Gemfile.lock
+need composer.json composer.lock
+
+# requirements.txt закрепляют не отдельным файлом, а точными версиями в самом файле
+if [ -f "$DIR/requirements.txt" ]; then
+  LOOSE=$(grep -nE '^[A-Za-z0-9_.-]+([[:space:]]*(>=|<=|>|<|~=|\^)|[[:space:]]*$)' "$DIR/requirements.txt" 2>/dev/null)
+  if [ -n "$LOOSE" ]; then
+    echo "$LOOSE" | sed 's|^|requirements.txt:|'
+    echo "  почини: закрепи точные версии через ==, иначе сборка завтра соберёт другое."
+    BAD=1
+  fi
+fi
+
+exit $BAD

package/kit/gates/deps-are-pinned/gate.yml

@@ -0,0 +1,9 @@
+intent: версии зависимостей закреплены — сборка воспроизводима
+
+trigger:
+  has_deps: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md — «2026-08-27 сборка невоспроизводима: версии не закреплены»

package/kit/gates/deps-are-pinned/green/nodep-go/go.mod

@@ -0,0 +1,3 @@
+module example.com/nodep
+
+go 1.22

package/kit/gates/deps-are-pinned/green/package-lock.json

@@ -0,0 +1,3 @@
+{
+  "lockfileVersion": 3
+}

package/kit/gates/deps-are-pinned/green/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "x",
+  "dependencies": { "left-pad": "1.3.0" }
+}

package/kit/gates/deps-are-pinned/green/requirements.txt

@@ -0,0 +1,2 @@
+requests==2.31.0
+flask==3.0.0

package/kit/gates/deps-are-pinned/red/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "x",
+  "dependencies": { "left-pad": "^1.0.0" }
+}

package/kit/gates/deps-are-pinned/red/requirements.txt

@@ -0,0 +1,2 @@
+requests>=2
+flask

package/kit/gates/deps-are-pinned/red/withdep-go/go.mod

@@ -0,0 +1,5 @@
+module example.com/withdep
+
+go 1.22
+
+require github.com/example/x v1.0.0

package/kit/gates/duplicate-code/README.md

@@ -0,0 +1,40 @@
+# Один и тот же код не размножается копиями
+
+**Намерение.** Одинаковые куски не лежат в нескольких местах.
+
+**Какой отказ это поймало.** В разборе 1069 коммитов: **число моделей захардкожено в четырёх
+местах четырьмя разными значениями** — 10, 13, 14 и 30. Копии разъехались, и никто не заметил.
+Запись в журнале: `incidents/README.md`, 2026-08-25.
+
+**Почему это опаснее длины.** Правку вносят в одну копию из четырёх. Три остаются со старым
+поведением, и расхождение всплывает не сразу и не там, где его сделали.
+
+**Почему агенты плодят дубли особенно охотно.** Скопировать из соседнего файла дешевле, чем
+найти общее место и вынести туда: копия точно работает, вынесение может что-то сломать.
+
+**Готовый аналог есть.** `jscpd` умеет и Python, и TypeScript одним прогоном и считает
+**похожесть**, а не только точное совпадение. Рецепты под фронтовые стеки берут его.
+
+**Переносимая проверка грубее.** Она ищет одинаковые восемь строк подряд после снятия отступов —
+совпадение байт в байт. Копия с переименованной переменной её не насторожит. Это запасной
+вариант, а не замена.
+
+**Тесты не проверяются.** Повтор в тестах часто осознанный: читаемость важнее сухости, и три
+похожих теста лучше одного хитрого. Случай «три однотипных — свести в один с набором входов»
+решается по правилам тестирования и глазами. На живом проекте **все двадцать находок были в
+тестах** — гейт, который краснеет только на них, выключат целиком.
+
+**Предел настраивается** переменной `AQK_DUP_LINES`, по умолчанию восемь строк.
+
+**Триггер — от двадцати файлов.** В проекте на пять файлов дубли ищут глазами, и проверка была бы
+шумом.
+
+**Самая тяжёлая из наших.** На проекте в четыре тысячи файлов — порядка пятнадцати секунд:
+она держит в памяти все восьмистрочные окна. Место такой проверки — перед пушем, в конвейере
+или по расписанию, но не на каждый коммит.
+
+**Чего НЕ ловит.** Копию с переименованной переменной, изменённым порядком строк или другим
+форматированием — сравнение идёт байт в байт после снятия отступов. Не смотрит в тесты и в
+сгенерированные файлы. Куски короче восьми строк не считает вовсе.
+
+**Образцы.** `red/` — один блок в двух файлах. `green/` — блок вынесен в общую функцию.

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

@@ -0,0 +1,58 @@
+#!/usr/bin/env sh
+# Ищет одинаковые блоки по восемь строк. Мера грубая — совпадение байт в байт после снятия
+# отступов, — но именно так размножается код, который агент копирует из соседнего файла.
+#
+# ЗАЧЕМ. Дубль опаснее длины: правку вносят в одну копию из четырёх, три остаются со старым
+# поведением, и расхождение всплывает через недели в другом месте.
+DIR="${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+WIN="${AQK_DUP_LINES:-8}"
+
+# Тесты исключены намеренно. Повтор в тестах часто осознанный: читаемость там важнее сухости,
+# и три похожих теста лучше одного хитрого. Случай «три однотипных — свести в один с набором
+# входов» решается глазами по правилам тестирования, а не этим гейтом. На живом проекте все
+# двадцать находок были в тестах — гейт, который краснеет только на них, выключат.
+TESTS="-name test -prune -o -name tests -prune -o -name spec -prune -o -name __tests__ -prune -o"
+
+# shellcheck disable=SC2046
+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 \
+  | xargs -r awk -v WIN="$WIN" '
+      FNR == 1 { n = 0; delete buf }
+      {
+        line = $0
+        gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
+        if (line == "" || line ~ /^([#]|\/\/)/) next     # пустые и комментарии не считаем
+        buf[++n] = line
+        if (n >= WIN) {
+          key = ""
+          for (i = n - WIN + 1; i <= n; i++) key = key buf[i] "\x1e"
+          if (key in seen && seen[key] != FILENAME ":" (FNR - WIN + 1)) {
+            print seen[key] " и " FILENAME ":" (FNR - WIN + 1) ": одинаковые " WIN " строк"
+          } else if (!(key in seen)) {
+            seen[key] = FILENAME ":" (FNR - WIN + 1)
+          }
+        }
+      }
+    ' 2>/dev/null | sort -u \
+  | awk -F' и |: ' '
+      # Один повторённый кусок даёт столько сообщений, на сколько окон он делится: восемь
+      # строк — восемь почти одинаковых строк отчёта. Схлопываем в одну на пару файлов.
+      { split($1, a, ":"); split($2, b, ":"); pair = a[1] " и " b[1]
+        if (!(pair in seen)) { seen[pair] = $1 " и " $2 }
+        cnt[pair]++ }
+      END { for (p in seen) print seen[p] ": одинаковый кусок" (cnt[p] > 1 ? " (окон: " cnt[p] ")" : "") }
+    ' | sort > /tmp/.dup.$$
+
+if [ -s /tmp/.dup.$$ ]; then
+  head -20 /tmp/.dup.$$
+  N=$(wc -l < /tmp/.dup.$$); [ "$N" -gt 20 ] && echo "  … и ещё $((N - 20))"
+  rm -f /tmp/.dup.$$
+  echo "  почини: вынеси общее в одно место. Правку вносят в одну копию из четырёх —"
+  echo "  остальные остаются со старым поведением, и это всплывает не сразу и не здесь."
+  exit 1
+fi
+rm -f /tmp/.dup.$$
+exit 0

package/kit/gates/duplicate-code/gate.yml

@@ -0,0 +1,12 @@
+intent: один и тот же код не размножается по проекту копиями
+
+trigger:
+  files_gt: 20
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+  # jscpd умеет и Python, и TypeScript одним прогоном и считает похожесть, а не совпадение.
+  javascript: npx --yes jscpd@5 --min-lines 8 --threshold 1 {dir}
+  typescript: npx --yes jscpd@5 --min-lines 8 --threshold 1 {dir}
+
+proof: incidents/README.md — «2026-08-25 разбор 1069 коммитов»: число моделей захардкожено в четырёх местах четырьмя разными значениями

package/kit/gates/duplicate-code/green/common.py

@@ -0,0 +1,9 @@
+def accumulate(rows, count):
+    total = 0
+    for row in rows:
+        for i in range(count):
+            value = compute(row[i])
+            if value is None:
+                continue
+            total += value
+    return total

package/kit/gates/duplicate-code/green/use.py

@@ -0,0 +1,9 @@
+from common import accumulate
+
+
+def sum_a(rows):
+    return accumulate(rows, 2)
+
+
+def sum_b(rows):
+    return accumulate(rows, 2)

package/kit/gates/duplicate-code/red/a.py

@@ -0,0 +1,12 @@
+def sum_a(rows):
+    total = 0
+    for row in rows:
+    value = compute(row[0])
+    if value is None:
+        continue
+    total += value
+    value = compute(row[1])
+    if value is None:
+        continue
+    total += value
+    return total

package/kit/gates/duplicate-code/red/b.py

@@ -0,0 +1,12 @@
+def sum_b(rows):
+    total = 0
+    for row in rows:
+    value = compute(row[0])
+    if value is None:
+        continue
+    total += value
+    value = compute(row[1])
+    if value is None:
+        continue
+    total += value
+    return total

package/kit/gates/entry-links-exist/README.md

@@ -0,0 +1,22 @@
+# Ссылки точки входа ведут на существующие файлы
+
+**Намерение.** Свод правил, который ссылается на несуществующий файл, утверждает то, чего нет.
+
+**Какой отказ это поймало.** В `audit_project` чек-лист гейтов четыре недели числил работающими
+изоляцию исполнителя и генерацию контрактов. Обе были отключены владельцем за три недели до
+этого — инструмент ломал файлы. Планирование опиралось на защиту, которой не существовало.
+Запись в журнале: `incidents/README.md`, 2026-08-24.
+
+**Почему машина, а не внимательность.** Расхождение появляется не в момент написания документа, а
+через недели, когда файл удалили в другой задаче. Человек в этот момент смотрит не сюда.
+
+**Готовый аналог есть и он сильнее.** `lychee` и `markdown-link-check` проверяют ещё и внешние
+адреса, и якоря внутри страницы. Рецепта под них в записи нет по устройству формата: рецепты
+выбираются **по языку проекта**, а эти инструменты к языку не привязаны. Если такой инструмент у
+вас стоит — он лучше нашего.
+
+**Чего НЕ ловит.** Только файлы `*.md` в самом каталоге, без обхода вложенных: намерение записи —
+точка входа, а не вся документация. Не проверяет внешние адреса (сеть) и якоря внутри файла.
+
+**Образцы.** `red/` — свод ссылается на `rules/nope.md`, которого нет: гейт обязан краснеть.
+`green/` — ссылается на существующий `rules/general.md`: гейт обязан молчать.

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# Каждая ссылка на локальный файл из markdown-файлов каталога обязана вести на
+# существующий файл. Ссылка в никуда — это документ, утверждающий защиту,
+# которой нет: планирование опирается на неё и ломается молча.
+DIR="${1:-.}"
+MISS=0
+for MD in "$DIR"/*.md; do
+  [ -f "$MD" ] || continue
+  # вытащить цели ссылок вида [текст](путь)
+  TARGETS=$(sed -n 's/.*](\([^)]*\)).*/\1/p' "$MD")
+  for T in $TARGETS; do
+    # автоссылки бывают обёрнуты как <(https://...)> — искать http где угодно внутри,
+    # не только в начале строки.
+    case "$T" in *http://*|*https://*|\#*|mailto:*) continue ;; esac
+    T=${T%%#*}
+    [ -z "$T" ] && continue
+    if [ ! -e "$DIR/$T" ]; then
+      echo "$MD: ссылка в никуда — $T"
+      echo "  почини: создай файл или убери ссылку. Документ, обещающий несуществующее, хуже отсутствующего."
+      MISS=1
+    fi
+  done
+done
+exit $MISS

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

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

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

@@ -0,0 +1,5 @@
+# Свод правил
+
+Стандарты: [общие правила](rules/general.md).
+Внешняя ссылка: [semver](https://semver.org).
+Автоссылка в скобках, как в CHANGELOG.md gin: [#1](<(https://example.com/pull/1)>).

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

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

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

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

package/kit/gates/file-size-limit/README.md

@@ -0,0 +1,22 @@
+# Файл не вырастает до размера, в котором агент теряется
+
+**Намерение.** Прод-код не длиннее 500 строк, компонент интерфейса — 300, тест — 800.
+
+**Какой отказ это поймало.** В разборе 1069 коммитов за 90 дней работы с агентами нашёлся
+**один файл маршрутов на 6305 строк**. Дословно: «не потому что так задумано, а потому что каждую
+новую фичу дописывали туда же — агенту так ближе по контексту».
+Запись в журнале: `incidents/README.md`, 2026-08-25.
+
+**Почему машина, а не внимательность.** Файл растёт по одной строке за раз, и ни одна правка не
+выглядит как «пора делить». Момент, когда стало поздно, не наступает — он проходит незаметно.
+
+**Числа спорные, предел — нет.** Можно спорить, 500 или 700; нельзя работать без предела вообще.
+Свои числа правятся в `check.sh` одной строкой.
+
+**Чего НЕ ловит.** Длину функции и вложенность: файл на 200 строк с одной функцией в 180 строк
+проверку пройдёт. Это отдельная мера — цикломатическая сложность.
+
+**Готового аналога нет.** Проверено: среди 964 правил `ruff` предела на
+размер файла нет ни одного. Это тот случай, когда свой гейт законен.
+
+**Образцы.** `red/` — прод-файл на 600 строк. `green/` — тот же код, разделённый надвое.

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

@@ -0,0 +1,34 @@
+#!/usr/bin/env sh
+# Пределы: прод-код 500 строк, компонент интерфейса 300, тест 800.
+#
+# ЗАЧЕМ. Агент теряется в больших файлах и начинает переписывать вместо правки. И растут они
+# не по замыслу: каждую новую фичу дописывают в тот же файл, потому что агенту так ближе по
+# контексту. Числа спорные — важно, что предел существует и его считает машина.
+DIR="${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+
+# Один обход и один wc на все файлы разом: на проекте в 36 тысяч файлов цикл с wc на каждый
+# не укладывался в две минуты.
+# 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 \
+  | xargs -r wc -l 2>/dev/null \
+  | awk '
+      $2 == "total" { next }
+      {
+        n = $1; f = $2
+        limit = 500; kind = "прод-код"
+        if (f ~ /(test|spec)/)        { limit = 800; kind = "тест" }
+        else if (f ~ /\.(jsx|tsx|vue)$/) { limit = 300; kind = "компонент" }
+        # Число строк стоит в позиции номера строки нарочно: храповик вырезает «:N:» из ключа,
+        # и запись о нарушении не меняется от каждой добавленной строки. Иначе рост файла на
+        # строку читался бы как новое нарушение, а сокращение — тоже как новое.
+        if (n > limit) { print f ":" n ": длиннее предела для «" kind "» — " limit " строк"; bad = 1 }
+      }
+      END { exit bad ? 1 : 0 }
+    ' || {
+      echo "  почини: раздели по смыслу, а не пополам. Файл растёт не по замыслу — в него"
+      echo "  дописывают каждую новую правку, потому что так ближе по контексту."
+      exit 1
+    }
+exit 0

package/kit/gates/file-size-limit/gate.yml

@@ -0,0 +1,9 @@
+intent: файл не вырастает до размера, в котором агент теряется
+
+trigger:
+  always: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md — «2026-08-25 разбор 1069 коммитов»: один файл маршрутов на 6305 строк