agent-quality-kit 0.6.0 → 0.8.0

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

@@ -5,7 +5,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"
 
 # Расширения, где живёт ТЕМИЗИРУЕМЫЙ интерфейс. Своё, а не общий CODE_EXT: там нет ни css, ни
 # vue — они не код в смысле «отладочная печать», но именно в них живёт цвет.
@@ -28,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 '
       # Блочные комментарии вырезаются ПО СОСТОЯНИЮ, а не построчно. Однострочный фильтр
@@ -51,7 +63,11 @@ 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.
+        if (line ~ /#[0-9a-fA-F]{8}([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F]{6}([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F]{3}([^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/commit-explains-itself/README.md

@@ -12,8 +12,18 @@
 **Почему машина, а не внимательность.** Написать отчёт «на будущее» — первое, что пропускают под
 давлением дедлайна. Гейт делает это ценой, а не пожеланием.
 
-**Готовый аналог.** Не искал: это не класс проверок, который держат готовые линтеры — они читают
-код, а не историю коммитов.
+**Готовый аналог есть, и раньше здесь было написано «не искал».** Искали 2026-09-07, при ревизии
+каталога. Историю коммитов держат [`gitlint`](https://jorisroovers.com/gitlint/) и
+[`commitlint`](https://commitlint.js.org/): проверяют форму заголовка, тип по Conventional
+Commits, длину строк, пустую строку между заголовком и телом; у `gitlint` есть даже
+`body-min-length` и возможность дописать своё правило на Python.
+
+**Почему рецепта под них здесь нет.** Оба проверяют, что тело **есть** и как оно оформлено. Эта
+запись требует другого: чтобы в теле стояли два названных раздела — что сделано и **в чём агент
+не уверен**. Второго нет ни в Conventional Commits, ни во встроенных правилах обоих. Написать
+своё правило `gitlint` можно, но это код на Python в проекте, который может быть не на Python, —
+и он всё равно наш, только в чужой обёртке. Если `commitlint` у вас уже стоит — он закрывает
+форму заголовка, чего не делаем мы; записи это не отменяет.
 
 **Чего НЕ ловит.** Не проверяет качество отчёта, только его наличие — «Сделано: починил» и «Не
 уверен: не знаю» формально пройдут. Не проверяет, что отчёт правдив. Это ограничение того же
@@ -39,7 +49,7 @@
 
 Гейт всё-таки местный: подсказка «допиши в тело коммита» выполнима до пуша, а не после.
 
-**Образцы.** `red/COMMIT_MSG` — обычное тело коммита без отчёта. `green/COMMIT_MSG` — то же самое
+**Образцы.** `red/.aqk-commit-msg` — обычное тело коммита без отчёта. `green/.aqk-commit-msg` — то же самое
 плюс `Сделано:` и `Не уверен:`. Образцы — текстовые файлы, а не настоящий git: арбитр в реальном
 проекте читает `git log -1`, а вложенный `.git` внутри каталога комплекта создал бы embedded-
 репозиторий, который сам по себе стал бы проблемой версионирования.

package/kit/gates/commit-explains-itself/check.sh

@@ -4,11 +4,15 @@
 # оставляет след для человека, читающего историю позже.
 DIR="${1:-.}"
 
-# Образцы (gates.sh) читают тело коммита из файла — реальный git log там взять неоткуда, а
+# Образцы (gates.sh) читают тело коммита из `.aqk-commit-msg` — реальный git log там взять неоткуда, а
 # вложенный .git внутри каталога комплекта сам по себе создал бы embedded-репозиторий.
-# В настоящем проекте COMMIT_MSG не бывает — читается последний реальный коммит.
-if [ -f "$DIR/COMMIT_MSG" ]; then
-  MSG=$(cat "$DIR/COMMIT_MSG")
+# В настоящем проекте такого файла не бывает — читается последний реальный коммит.
+# Имя с точкой намеренно: `COMMIT_MSG` в корне проекта — вещь возможная (так зовут заготовку
+# сообщения многие обёртки над git), и такой файл молча подменял бы собой настоящий коммит.
+# Тот же дефект нашло ревью у `personal-config-not-shared` 2026-09-07; здесь он был с самого
+# начала и не всплывал.
+if [ -f "$DIR/.aqk-commit-msg" ]; then
+  MSG=$(cat "$DIR/.aqk-commit-msg")
 else
   if ! (cd "$DIR" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1); then
     echo "не git-репозиторий — проверять нечего"

package/kit/gates/complexity-limit/README.md

@@ -33,5 +33,10 @@
 считает только глубину. Не различает функции внутри файла: меряется худшее место файла, а не
 каждая функция отдельно. Готовые правила умеют и то, и другое.
 
+**Тесты не проверяются.** Глубокая вложенность в тесте — это обход таблицы ожиданий, а не
+сложная логика. Замер по `fastapi` дал 303 находки, из которых **101 в `tests/`**; после
+исключения тестов осталось 10. Гейт, который краснеет в основном на тестах, выключают целиком —
+тот же довод и по той же причине, что в `duplicate-code`.
+
 **Образцы.** `red/` — восемь уровней вложенности. `green/` — тот же смысл, разбитый на две
 функции с ранним выходом.

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

@@ -6,12 +6,31 @@
 # ЗАЧЕМ ВООБЩЕ. 29 ветвлений в одной функции — это код, который никто не держит в голове
 # целиком: ни человек, ни агент. Агент в таком месте начинает переписывать вместо правки.
 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"
 MAX="${AQK_MAX_DEPTH:-5}"
 
+# Тесты исключены намеренно — тем же списком, что и в duplicate-code. Глубокая вложенность в
+# тесте это обход таблицы ожиданий, а не сложная логика: замер по fastapi дал 303 находки, из
+# которых 101 в tests/. Гейт, который краснеет в основном на тестах, выключают целиком.
+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") -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 \
+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" \
+  | drop_generated \
   | xargs -r awk -v MAX="$MAX" '
         # Один обход на все файлы: процесс на каждый файл дал 19 секунд на 4000 файлов.
         # Разметка вложена по природе: пять уровней тегов — это не сложная логика, а обычная
@@ -21,12 +40,11 @@ find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null | only_code | own_sam
         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/complexity-limit/green/test_fixtures.py

@@ -0,0 +1,14 @@
+# Тест с глубокой вложенностью — не сложная логика, а разбор дерева ожиданий. Найдено замером
+# по fastapi: 101 находка из 303 пришлась на tests/, и все они — таблицы ожидаемых ответов,
+# которые никто не станет «упрощать». Гейт, который краснеет в основном на тестах, выключат.
+def test_openapi_schema(client):
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    schema = response.json()
+    for path, methods in schema["paths"].items():
+        for method, spec in methods.items():
+            for code, resp in spec["responses"].items():
+                if "content" in resp:
+                    for media, body in resp["content"].items():
+                        if "schema" in body:
+                            assert body["schema"] is not None

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

@@ -26,4 +26,17 @@
 **Готового аналога нет** — ни в линтерах, ни в пакетных менеджерах: они
 умеют создать файл версий, но не умеют требовать, чтобы он существовал и лежал в репозитории.
 
-**Образцы.** `red/` — объявление зависимостей без закрепления. `green/` — с ним.
+**Закрепляют не только poetry и uv.** Для `pyproject.toml` файлом закрепления считается и
+`requirements.txt` — но только если он сам проходит проверку, то есть все версии в нём стоят
+через `==`. Иначе «есть requirements.txt» стало бы способом обойти гейт пустым файлом.
+Найдено замером по `httpx`: там инструменты закреплены до патча прямо в `requirements.txt`,
+а гейт требовал ещё и `poetry.lock`, которого в этом укладе не бывает вовсе.
+
+**Не различает библиотеку и приложение.** Библиотека намеренно оставляет
+границы своих зависимостей широкими — закрепив их у себя, она ломает сборку всем, кто её
+ставит. Гейт смотрит только на то, закреплено ли окружение самого проекта, и правильно молчит,
+когда библиотека закрепила инструменты и не закрепила зависимости.
+
+**Образцы.** `red/` — объявление зависимостей без закрепления, плюс `pyproject.toml` рядом с
+незакреплённым `requirements.txt`. `green/` — с закреплением, включая уклад «pyproject плюс
+requirements.txt с точными версиями».

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

@@ -30,7 +30,12 @@ need() {
 }
 
 need package.json  package-lock.json yarn.lock pnpm-lock.yaml npm-shrinkwrap.json
-need pyproject.toml poetry.lock uv.lock pdm.lock
+# requirements.txt считается закреплением для pyproject.toml наравне с файлами блокировки:
+# закрепляют не только poetry и uv. Замер по httpx: инструменты там закреплены до патча
+# прямо в requirements.txt, а гейт требовал ещё и poetry.lock, которого в этом укладе не
+# бывает вовсе. Файл засчитывается только если он сам проходит проверку ниже — иначе
+# «есть requirements.txt» стало бы способом обойти гейт пустым файлом.
+need pyproject.toml poetry.lock uv.lock pdm.lock requirements.txt
 need go.mod        go.sum
 need Cargo.toml    Cargo.lock
 need Gemfile       Gemfile.lock

package/kit/gates/deps-are-pinned/green/pyproject-with-requirements/pyproject.toml

@@ -0,0 +1,12 @@
+# Питоновская библиотека, которая закрепляет версии не файлом блокировки, а точными версиями
+# в requirements.txt. Так делает httpx и весь класс проектов, живущих без poetry и uv:
+# инструменты закреплены до патча, а границы зависимостей самой библиотеки оставлены широкими
+# намеренно — библиотека, закрепившая их у себя, ломает сборку всем, кто её ставит.
+[project]
+name = "sample-lib"
+version = "1.0.0"
+dependencies = ["httpx"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

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

@@ -0,0 +1,3 @@
+-e .
+pytest==8.4.1
+ruff==0.16.6

package/kit/gates/deps-are-pinned/red/pyproject-loose/pyproject.toml

@@ -0,0 +1,12 @@
+# Питоновская библиотека, которая закрепляет версии не файлом блокировки, а точными версиями
+# в requirements.txt. Так делает httpx и весь класс проектов, живущих без poetry и uv:
+# инструменты закреплены до патча, а границы зависимостей самой библиотеки оставлены широкими
+# намеренно — библиотека, закрепившая их у себя, ломает сборку всем, кто её ставит.
+[project]
+name = "sample-lib"
+version = "1.0.0"
+dependencies = ["httpx"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

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

@@ -0,0 +1,3 @@
+-e .
+pytest>=8
+ruff

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

@@ -12,13 +12,22 @@
 **Почему агенты плодят дубли особенно охотно.** Скопировать из соседнего файла дешевле, чем
 найти общее место и вынести туда: копия точно работает, вынесение может что-то сломать.
 
-**Готовый аналог есть.** `jscpd` умеет и Python, и TypeScript одним прогоном и считает
-**похожесть**, а не только точное совпадение. Рецепты под фронтовые стеки берут его.
+**Готовый аналог есть, и под каждый стек свой.** `jscpd` для фронта — считает **похожесть**, а не
+только точное совпадение. `pylint --enable=R0801` для Python — сравнивает разобранный код, и
+переименованная переменная его не обманет. Рецепт под Python появился только 2026-09-07: до
+ревизии каталога его не было вовсе, и питоновский проект получал нашу побайтовую самоделку,
+хотя родной инструмент стоял у него уже установленным.
 
 **Переносимая проверка грубее.** Она ищет одинаковые восемь строк подряд после снятия отступов —
 совпадение байт в байт. Копия с переименованной переменной её не насторожит. Это запасной
 вариант, а не замена.
 
+**Одинаковые импорты — не дубль.** Окно, в котором нет ни одной строки кроме ввоза (`import`,
+`use`, `require`, путь в кавычках внутри `import (…)` в Go) и одиноких скобок, находкой не
+считается. Найдено замером по `cobra`: гейт краснел на `doc/man_docs.go` и `doc/md_docs.go`,
+где совпадали восемь строк подряд из списка импортов и ни одной строки логики. В Go, Java и Rust
+ввоз стоит по одной строке на строку, и в соседних файлах одного пакета он совпадает всегда.
+
 **Тесты не проверяются.** Повтор в тестах часто осознанный: читаемость важнее сухости, и три
 похожих теста лучше одного хитрого. Случай «три однотипных — свести в один с набором входов»
 решается по правилам тестирования и глазами. На живом проекте **все двадцать находок были в

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

@@ -5,7 +5,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"
 WIN="${AQK_DUP_LINES:-8}"
 
 # Тесты исключены намеренно. Повтор в тестах часто осознанный: читаемость там важнее сухости,
@@ -18,18 +30,37 @@ 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" '
-      FNR == 1 { n = 0; delete buf }
+      # Строка-объявление ввоза: `import`, `from … import`, `use …;`, путь в кавычках внутри
+      # блока `import (…)` в Go, `require(…)`, а также одинокие скобки и точки с запятой.
+      # ЗАЧЕМ. Восемь одинаковых строк ввоза подряд — форма языка, а не размноженный код: в Go,
+      # Java и Rust список ввоза стоит по одной строке и в соседних файлах одного пакета
+      # совпадает целиком. Замер по cobra: обе находки в doc/ были ровно этим — ни одной
+      # строки логики. Окно, где нет ни одной строки кроме ввоза, дублем не считается.
+      function isimport(s) {
+        return s ~ /^(import|from|use|export|require|package|#include|using)([[:space:](]|$)/ ||
+               s ~ /^[A-Za-z_][A-Za-z0-9_]*[[:space:]]+"[^"]*"$/ ||
+               s ~ /^[_.]?[[:space:]]*"[^"]*"[,;]?$/ ||
+               s ~ /^(const|let|var)[[:space:]].*require\(/ ||
+               s ~ /^[(){}\[\];,]+$/
+      }
+      FNR == 1 { n = 0; delete buf; delete imp }
       {
         line = $0
         gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
         if (line == "" || line ~ /^([#]|\/\/)/) next     # пустые и комментарии не считаем
         buf[++n] = line
+        imp[n] = isimport(line)
         if (n >= WIN) {
-          key = ""
-          for (i = n - WIN + 1; i <= n; i++) key = key buf[i] "\x1e"
+          # Ключ и признак «есть ли код» собираются ОДНИМ проходом по окну. Разнести их на
+          # два цикла выглядело ускорением — окно из одного ввоза отбрасывалось бы до сборки
+          # ключа. Замерено 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                               # окно целиком из ввоза — не дубль
           if (key in seen && seen[key] != FILENAME ":" (FNR - WIN + 1)) {
             print seen[key] " и " FILENAME ":" (FNR - WIN + 1) ": одинаковые " WIN " строк"
           } else if (!(key in seen)) {

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

@@ -16,7 +16,15 @@ recipes:
   #
   # «c#» в списке нет намеренно: разбор манифеста режет строку по «#», и рецепт обрывался бы
   # на «c». Обёртку _native.sh не пишем — её добавляет сама программа при установке гейта.
+  #
+  # Рецепт стоял только под javascript и typescript, хотя список --format покрывает и Python,
+  # и Go. Питоновский проект получал переносимую самоделку вместо готового инструмента —
+  # найдено ревизией каталога 2026-09-07, замером по пяти стекам.
   javascript: npx --yes jscpd@5 --min-lines 8 --threshold 1 --format "javascript,jsx,typescript,tsx,vue,python,go,ruby,java,php,rust,kotlin,swift,scala" {dir}
   typescript: npx --yes jscpd@5 --min-lines 8 --threshold 1 --format "javascript,jsx,typescript,tsx,vue,python,go,ruby,java,php,rust,kotlin,swift,scala" {dir}
+  # Родной инструмент стека, а не jscpd: питоновскому проекту незачем ставить Node ради одной
+  # проверки. R0801 сравнивает не байты, а разобранный код — переименованная переменная его
+  # не обманет, в отличие от переносимого рецепта.
+  python: pylint --disable=all --enable=R0801 --min-similarity-lines=8 {dir}
 
 proof: incidents/README.md — «2026-08-25 разбор 1069 коммитов»: число моделей захардкожено в четырёх местах четырьмя разными значениями

package/kit/gates/duplicate-code/green/imports_a.go

@@ -0,0 +1,20 @@
+// Одинаковый блок импортов в двух файлах одного пакета — не дубль кода, а форма языка.
+// Найдено замером по cobra: гейт краснел на doc/man_docs.go и doc/md_docs.go, где совпадали
+// восемь строк подряд из списка импортов, и ни одной строки логики.
+package doc
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+func RenderMan(w io.Writer, name string) error {
+	_, err := fmt.Fprintf(w, "man page for %s", name)
+	return err
+}

package/kit/gates/duplicate-code/green/imports_b.go

@@ -0,0 +1,19 @@
+package doc
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+func RenderMarkdown(w io.Writer, name string) error {
+	var buf bytes.Buffer
+	buf.WriteString(strings.ToUpper(name))
+	_, err := w.Write(buf.Bytes())
+	return err
+}

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

@@ -15,6 +15,11 @@
 выбираются **по языку проекта**, а эти инструменты к языку не привязаны. Если такой инструмент у
 вас стоит — он лучше нашего.
 
+**Адрес страницы сайта не считается битой ссылкой.** Путь, кончающийся косой чертой —
+`[руководство](tutorial/#install)`, — это адрес на опубликованном сайте, а не файл в
+репозитории. Так ссылаются mkdocs, docusaurus и jekyll. Найдено замером по `fastapi`: гейт
+объявлял битой рабочую ссылку из их README.
+
 **Чего НЕ ловит.** Только файлы `*.md` в самом каталоге, без обхода вложенных: намерение записи —
 точка входа, а не вся документация. Не проверяет внешние адреса (сеть) и якоря внутри файла.
 

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

@@ -7,13 +7,22 @@ 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 где угодно внутри,
     # не только в начале строки.
     case "$T" in *http://*|*https://*|\#*|mailto:*) continue ;; esac
     T=${T%%#*}
     [ -z "$T" ] && continue
+    # Путь, кончающийся косой чертой, — адрес страницы опубликованного сайта, а не файл на
+    # диске. Так ссылаются mkdocs, docusaurus и jekyll: `[руководство](tutorial/#install)`
+    # работает у читателя и не существует в репозитории. Найдено замером по fastapi — гейт
+    # объявлял битой рабочую ссылку из их README. Проверять такие адреса умеют lychee и
+    # markdown-link-check: они ходят в сеть, а мы смотрим только на диск.
+    case "$T" in */) continue ;; esac
     if [ ! -e "$DIR/$T" ]; then
       echo "$MD: ссылка в никуда — $T"
       echo "  почини: создай файл или убери ссылку. Документ, обещающий несуществующее, хуже отсутствующего."

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

@@ -3,3 +3,8 @@
 Стандарты: [общие правила](rules/general.md).
 Внешняя ссылка: [semver](https://semver.org).
 Автоссылка в скобках, как в CHANGELOG.md gin: [#1](<(https://example.com/pull/1)>).
+Ссылка на страницу сайта документации: [руководство](tutorial/#install) — путь опубликованного
+сайта, а не файл на диске. Найдено замером по fastapi: `[installation guide](tutorial/#install-fastapi)`
+в README читалась как битая, хотя на сайте работает. Так ссылаются mkdocs, docusaurus и jekyll.
+
+Пример оформления ссылки: `[name](url)` — это пример, а не ссылка.