agent-quality-kit 0.5.0 → 0.6.0

package/README.md

@@ -196,7 +196,7 @@ Already using [pre-commit](https://pre-commit.com)? Three lines in the file you
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.5.0
+    rev: v0.6.0
     hooks:
       - id: aqk            # runs what the repository declares; blocks below AQK-1
       # - id: aqk-doctor   # read-only: the level and what is missing, blocks nothing
@@ -236,9 +236,26 @@ aqk find "print statements in production"   # is there already such a gate — m
 aqk doctor                                  # what applies to this repository and what is missing
 aqk add secrets-not-in-code                 # copies the check and its samples in, declares it
 aqk doctor --run                            # runs the declared gates and shows the result
+aqk doctor --run --since main               # ... but only what the diff introduced
 aqk ratchet no-print-in-prod                # existing violations become debt, new ones are blocked
 ```
 
+### The first run on a real project
+
+An established repository carries years of debt. Run every gate over all of it and you get a wall
+of red that nobody reads — so the tool gets switched off. `--since <ref>` narrows the output to
+files the diff touched:
+
+```bash
+aqk doctor --run --since main    # only what this branch introduced
+```
+
+Three outcomes, all of them said out loud. Findings inside the diff — red, as usual. Findings only
+outside it — green, with the number that was hidden, never a silent "all clear". And a gate whose
+output carries no paths at all (a commit-message check, a CI-config check) **cannot** be narrowed:
+it stays red, and says why. Calling it green because there was nothing to narrow would be exactly
+the silence this tool exists to remove.
+
 Every `doctor --run` rewrites `.aqk/last-run.md` — a short report of what actually ran and how
 long it took. The list of gates in the manifest says nothing about how many of them are alive
 right now; the report does. The file is ephemeral — keep it in your own `.gitignore`.
@@ -289,6 +306,24 @@ catalogue may grow to hundreds of entries; a given project still sees about a do
 An entry is accepted only if its arbiter goes red on the red sample, stays quiet on the green
 one, and names a real failure it caught. A machine checks this: `bash tool/selfcheck/gates.sh`.
 
+### Four entries that watch the agent, not the code
+
+Ruff, ESLint and gitleaks already find bad code, and AQK calls them where it can rather than
+reinventing them. These four look elsewhere — at the moment the **signal** about bad code is
+switched off, which is what a coding agent does when the task is phrased as "make it pass":
+
+| Entry | What it catches |
+|---|---|
+| `gate-not-weakened` | the fix was a suppression, not a fix: bare `# noqa`, `eslint-disable` with no rule named, `@ts-ignore`, `--no-verify` |
+| `ci-actually-fails` | a pipeline step that renders a verdict but cannot fail — `run: pytest \|\| true`, `continue-on-error: true` |
+| `test-has-assertion` | a test that cannot fail: empty body, `assert True`, a skip with no reason given |
+| `promise-has-gate` | a rule in `AGENTS.md` with no enforcer named — neither a gate nor, honestly, a human |
+
+Each was measured on nineteen third-party repositories (~25 000 files) before it entered the
+catalogue, and two further entries were **cancelled by that measurement**: one because
+[`agents-lint`](https://github.com/giacomo/agents-lint) already does it better, one because
+91 of its 120 findings turned out to be a legitimate pattern.
+
 ## The guides as a single file
 
 ```bash

package/README.ru.md

@@ -198,7 +198,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.5.0
+    rev: v0.6.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -286,6 +286,24 @@ vendor/
 Запись принимается, только если её арбитр краснеет на красном образце, молчит на зелёном и
 назван реальный отказ, который она поймала. Проверяет это машина: `bash tool/selfcheck/gates.sh`.
 
+### Четыре записи, которые смотрят на агента, а не на код
+
+Ruff, ESLint и gitleaks и так находят плохой код — AQK зовёт их, где может, вместо того чтобы
+писать своё. Эти четыре смотрят в другое место: на момент, когда **сигнал** о плохом коде
+выключают. Именно это делает агент, когда задача сформулирована как «сделай, чтобы прошло»:
+
+| Запись | Что ловит |
+|---|---|
+| `gate-not-weakened` | починкой было подавление: голый `# noqa`, `eslint-disable` без имени правила, `@ts-ignore`, `--no-verify` |
+| `ci-actually-fails` | шаг конвейера, который выносит вердикт, но не может провалиться — `run: pytest \|\| true`, `continue-on-error: true` |
+| `test-has-assertion` | тест, который не может провалиться: пустое тело, `assert True`, пропуск без причины |
+| `promise-has-gate` | правило в `AGENTS.md`, у которого не назван сторож — ни гейт, ни, честно, человек |
+
+Каждая измерена на девятнадцати чужих репозиториях (~25 000 файлов) до внесения в каталог, и ещё
+две записи этот же замер **отменил**: одну — потому что
+[`agents-lint`](https://github.com/giacomo/agents-lint) делает это лучше, другую — потому что
+91 находка из 120 оказалась законным приёмом.
+
 ## Методички одним файлом
 
 ```bash

package/kit/docs/ready-made-rules.md

@@ -149,6 +149,46 @@ ruff check --select TRY400 --statistics .     # сколько находок У
 
 ---
 
+## Заглушка вместо реализации: почти всё уже покрыто
+
+Самый ожидаемый способ, которым агент «заканчивает» задачу, — подпись без работы. Мы собирались
+писать на это запись каталога и не стали: замер по девятнадцати репозиториям (~25 000 файлов)
+показал, что своей доли почти не остаётся.
+
+| Что | Чем ловится | Не забыть |
+|---|---|---|
+| пустое тело функции в JS и TS | `eslint` [`no-empty-function`](https://eslint.org/docs/latest/rules/no-empty-function) | функция с комментарием внутри не считается пустой |
+| абстрактный метод, не переопределённый в конкретном классе | `pylint` [`W0223`](https://pylint.readthedocs.io/en/latest/user_guide/messages/warning/abstract-method.html) | `--disable=all --enable=W0223` — остальное берёт ruff |
+| `raise NotImplemented` вместо `NotImplementedError` | `ruff` [`F901`](https://docs.astral.sh/ruff/rules/raise-not-implemented/) | входит в группу `F` |
+| лишний `pass` рядом с настоящим кодом | `ruff` `PIE790` | |
+
+**Чего мы НЕ стали делать и почему.** Пустое тело (`pass`) — не признак недоделки: из 120 находок
+первой версии 91 оказалась законной. Это null-объекты (`NoOpSpan` в sentry-python), безопасные
+заглушки провайдера в pr-agent — там прямо стоит комментарий «safe no-op stubs», —
+необязательные обработчики. А `raise NotImplementedError` в методе класса и есть питоновский
+способ объявить абстракцию, даже без `abc`: так написаны `ContentDecoder` в httpx и интерфейс
+плагина в pre-commit. За вычетом этих двух классов на 25 000 файлах не осталось ни одной находки.
+
+## Обвес самого агента: тоже есть готовое
+
+К осени 2026 появился отдельный класс инструментов — линтеры не кода, а того, что читает агент:
+`AGENTS.md`, `CLAUDE.md`, файлы навыков, конфиги хуков и MCP. Писать своё здесь незачем.
+
+| Инструмент | Что проверяет | Состояние на 2026-09-06 |
+|---|---|---|
+| [`agnix`](https://github.com/agent-sh/agnix) | 455 правил: структура `CLAUDE.md`/`AGENTS.md`/`SKILL.md`, синтаксис конфигов MCP и хуков, соглашения об именах, **мёртвые ссылки на файлы**. Есть автопочинка и LSP | 404 ⭐, Rust, активен. `npm i -g agnix`, `brew`, `pip`, `cargo` |
+| [`agents-lint`](https://github.com/giacomo/agents-lint) | мёртвые npm-скрипты, упомянутые в `AGENTS.md`, устаревшие рамки, деревья каталогов в контексте | 13 ⭐, TypeScript, последний коммит март 2026 |
+
+```bash
+npm install -g agnix && agnix --strict .
+```
+
+**Чего они НЕ делают — и почему у AQK остаётся своя половина.** Все они проверяют документ:
+формат, существование путей, наличие скриптов. Ни один не спрашивает, **подкреплено ли обещание
+командой с кодом возврата**. «Мы никогда не коммитим секреты» — грамматически безупречная
+строка, на которую ни один из них ничего не скажет. Разделение простое: обвес агента проверяет
+`agnix`, исполнимость обещаний — `promise-has-gate`.
+
 ## А если проект не на Python?
 
 Ничего не меняется. Запись каталога держит **одно намерение и несколько исполнителей**, и

package/kit/gates/README.md

@@ -70,6 +70,26 @@
 Плюс шестое, без которого запись не принимается: **доказательство** — реальный отказ, который
 она поймала. «Это хорошая практика» не принимается.
 
+## Зрелость записи не пишут руками
+
+Седьмого поля нет: зрелость **считается** из доказательства. Ссылается `proof` на журнал шишек —
+запись зрелая; не ссылается — условная, и это видно в приёмке каталога. Написать себе
+`lifecycle: stable` нельзя, приёмка такую запись отклонит.
+
+Это не придирка к форме. У всех трёх соседей, чей каталог мы разбирали, поле зрелости есть, и
+у всех троих его заполняет автор: `lifecycle` у зондов Scorecard, `future`/`obsolete` у
+критериев значка OpenSSF. Значение, написанное автором, означает доверие к автору. Каталог, где
+зрелость объявляют, к сотне записей превращается в список, в котором нельзя выбрать.
+
+Объявляется ровно одно состояние — **`deprecated`**, потому что «эту запись больше не ставят»
+из её файлов не выводится никак. Вместе с ним обязателен `superseded_by` с именем существующей
+записи, и `aqk add` тогда отказывает в установке, назвав преемника:
+
+```yaml
+lifecycle: deprecated
+superseded_by: no-print-in-prod
+```
+
 ## Запись без переносимого рецепта
 
 Иногда переносимой проверки быть не может: чтобы понять, вызывают ли функцию, нужен граф

package/kit/gates/ci-actually-fails/README.md

@@ -0,0 +1,42 @@
+# Проверка в конвейере может провалиться
+
+**Намерение.** Шаг выполнен, круг зелёный, проверка не сработала. `run: pytest || true` —
+это строка в логе, а не проверка.
+
+**Какой отказ это поймало.** Дыру нашли у себя. Запись `gates-run-in-ci` отвечает на вопрос
+«упомянут ли гейт в конфиге конвейера» и на этом останавливается — то есть конфиг с
+`run: pytest || true` проходил её зелёным. «Упомянут» и «работает» — разные утверждения, и весь
+этот стандарт стоит на том, чтобы их не путать; у себя мы их спутали.
+
+Замер по пятнадцати чужим репозиториям подтвердил, что класс живой: у `reviewdog` два шага с
+его собственными линтерами идут под `continue-on-error: true`. Запись в журнале:
+`incidents/README.md`, 2026-09-06.
+
+**Что именно проверяется.** Конфиг разбирается по шагам. Шаг красный, если он **и** выносит
+вердикт, **и** не может провалиться.
+
+| Выносит вердикт, если | Не может провалиться, если |
+|---|---|
+| команда есть в списке запускалок (`pytest`, `eslint`, `go test`, `golangci-lint`, `mypy`, `cargo clippy`, …) | шаг помечен `continue-on-error: true` |
+| команда объявлена гейтом в `.aqk.yml` **этого** проекта | задача помечена `allow_failure: true` (gitlab) |
+| в **имени шага** стоит слово `lint`, `test`, `check`, `verify`, `audit`, `scan`, `coverage` | провал погашен в самой команде: `\|\| true`, `\|\| :`, `\|\| exit 0` |
+
+Гашение прямо в команде красится только для закрытого списка запускалок: `docker network create … || true` — это идемпотентность, а не выключенная проверка.
+
+**Готовый аналог.** Не нашли. [`actionlint`](https://github.com/rhysd/actionlint) разбирает
+синтаксис workflow, [`zizmor`](https://github.com/woodruffw/zizmor) ищет в них дыры
+безопасности — ни тот, ни другой не спрашивает, может ли шаг провалиться. `continue-on-error`
+для них — законная настройка, каковой она и является: незаконной её делает то, ЧТО под ней
+стоит, а это знает только проект.
+
+**Чего НЕ ловит.**
+
+- **Проверку, которую не по чему опознать.** Задача `mutation-diff` с именем «Mutation score on
+  changed files» под `continue-on-error` (нашлась в `kodus-ai`, автор сам пометил её «advisory —
+  does not block») не опознаётся: в имени нет слова-приметы, а команда не из списка. Объяви такую
+  проверку гейтом в `.aqk.yml` — тогда она станет видна точно, а не по догадке.
+- **Провал, погашенный внутри скрипта.** `set +e`, `trap`, `exit 0` в конце `run: |` — это уже
+  логика скрипта, а не конфиг конвейера.
+- **Шаг, который проходит по другой причине.** Тест, всегда возвращающий 0, — не эта запись,
+  а `test-has-assertion`.
+- **`if: always()`** маскировкой не считается: он про порядок выполнения, а не про вердикт.

package/kit/gates/ci-actually-fails/check.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env sh
+# Конвейер, который гасит провал проверки: шаг выполнен, круг зелёный, проверка не сработала.
+#
+# ЗАЧЕМ ОТДЕЛЬНО ОТ «гейт запускается конвейером». Та проверка отвечает на вопрос «упомянут ли»,
+# и на этом останавливается. Мы нашли дыру в собственной оснастке: конфиг с `run: pytest || true`
+# проходил её зелёным — команда упомянута, а провалиться не может никогда. «Упомянут» и
+# «работает» — разные утверждения, и весь этот стандарт стоит на том, чтобы их не путать.
+DIR="${1:-.}"
+
+CI=$(find "$DIR/.github/workflows" "$DIR/.gitlab-ci.yml" "$DIR/.circleci" "$DIR/Jenkinsfile" \
+     -type f 2>/dev/null)
+[ -z "$CI" ] && { echo "конвейера нет — эта проверка не про тебя"; exit 0; }
+
+# Что считается ПРОВЕРКОЙ. Список намеренно закрытый: маскировка бывает законной — необязательная
+# выгрузка отчёта, публикация артефакта, уведомление. Красить всякий `continue-on-error` значит
+# получить гейт, который выключат первым. Красим только гашение того, что выносит вердикт.
+RUNNERS='aqk|doctor --run|pytest|tox|nox|unittest|jest|vitest|mocha|jasmine|karma|playwright|cypress|eslint|tsc|ruff|flake8|pylint|mypy|pyright|bandit|semgrep|gitleaks|trivy|rubocop|golangci-lint|golint|govet|go vet|go test|staticcheck|shellcheck|hadolint|actionlint|codespell|reviewdog|cargo test|cargo clippy|mvn|gradle|phpstan|psalm|npm test|npm run (test|lint|check|typecheck)|yarn (test|lint)|pnpm (test|lint)|make (test|lint|check)'
+
+# Закрытый список не поспевает: замер по чужим репозиториям нашёл шаг «Run reviewdog
+# (github-pr-check)» под `continue-on-error: true`, и ни одно имя из списка в нём не звучало.
+# Поэтому вторая примета — СЛОВО в имени шага или в команде. Целым словом: «checkout» не
+# «check», иначе первый же `actions/checkout` красил бы каждый конвейер на свете.
+WORDS='([Ll]int|[Tt]est|[Cc]heck|[Vv]erify|[Aa]udit|[Ss]can|[Tt]ypecheck|[Cc]overage)([^A-Za-z]|$)'
+
+# Проверка из манифеста — тоже проверка, как бы она ни называлась в этом проекте.
+MAN="$DIR/.aqk.yml"
+if [ -f "$MAN" ]; then
+  KEYS=$(tr -d '\r' < "$MAN" | awk '/^gates:/{g=1;next} /^[A-Za-z]/{g=0} g && /^[[:space:]]+[A-Za-z0-9_-]+:/{
+      sub(/^[[:space:]]*[A-Za-z0-9_-]*:[[:space:]]*/,""); gsub(/^"|"$/,"");
+      n=split($0,w," "); for(i=1;i<=n;i++) if (index(w[i],"/")) { print w[i]; break }
+    }')
+fi
+
+BAD=""
+for F in $CI; do
+  # Разбор ПО ШАГАМ, а не по строкам. Построчно проверка врала в обе стороны: законный
+  # `continue-on-error` на шаге выгрузки отчёта красил соседний шаг с тестами, а слово «test»
+  # внутри перечисления типов коммита («feat|fix|test|chore») делало проверкой строку, которая
+  # ничего не проверяет. Замер по чужим конвейерам дал 4 ложных из 10 — переписано на блоки.
+  #
+  # Шаг начинается элементом списка («- ») или ключом верхнего уровня: так устроен и github,
+  # и gitlab, где `allow_failure` живёт на уровне задачи.
+  RES=$(tr -d '\r' < "$F" | awk -v runners="$RUNNERS" -v words="$WORDS" -v keys="$KEYS" -v file="$F" '
+    function isComment(l) { return l ~ /^[[:space:]]*#/ }
+    function looksLikeCheck(l,   j, nk) {
+      if (isComment(l)) return 0
+      # `uses:` — чужое действие. Его провал бывает законно необязательным: выгрузка отчёта,
+      # комментарий в пул-реквест, уведомление. Вердикт выносит то, что ЗАПУСКАЮТ.
+      if (l ~ /^[[:space:]]*(-[[:space:]]+)?uses[[:space:]]*:/) return 0
+      if (l ~ runners) return 1
+      # Проверка, объявленная в манифесте ЭТОГО проекта, — тоже проверка, как бы она ни
+      # называлась. Это самая точная примета из трёх: не догадка по имени, а список, который
+      # проект написал сам.
+      nk = split(keys, K, "\n")
+      for (j = 1; j <= nk; j++) if (K[j] != "" && index(l, K[j])) return 1
+      # Слово-примета — ТОЛЬКО в имени шага. В теле команды оно ловит своё же упоминание:
+      # «grep -oE (feat|fix|test|chore)» — это разбор заголовка коммита, а не проверка.
+      if (l ~ /^[[:space:]]*(-[[:space:]]+)?name[[:space:]]*:/ && l ~ words) return 1
+      return 0
+    }
+    function isMask(l) {
+      return !isComment(l) && l ~ /^[[:space:]]*(continue-on-error|allow_failure|ignore_failure)[[:space:]]*:[[:space:]]*(true|yes)/
+    }
+    function isBoundary(l) { return l ~ /^[[:space:]]*-[[:space:]]/ || l ~ /^[A-Za-z_.-]+[[:space:]]*:/ }
+    function flush(   ) {
+      if (blockStart && blockCheck && blockMask)
+        printf "%s:%d: проверка не может провалиться — шаг под %s\n", file, blockCheckLine, blockMaskText
+      blockStart = 0; blockCheck = 0; blockMask = 0
+    }
+    {
+      # Гашение прямо в команде красится только для ЗАКРЫТОГО списка запускалок: «|| true» на
+      # вспомогательной команде внутри скрипта (`docker network create … || true`) — это
+      # идемпотентность, а не выключенная проверка.
+      if (!isComment($0) && $0 ~ runners && $0 ~ /\|\|[[:space:]]*(true|:|exit[[:space:]]+0)/) {
+        line = $0; sub(/^[[:space:]]+/, "", line)
+        printf "%s:%d: провал погашен прямо в команде: %s\n", file, NR, substr(line, 1, 90)
+      }
+      if (isBoundary($0)) flush()
+      if (!blockStart) blockStart = NR
+      if (!blockCheck && looksLikeCheck($0)) { blockCheck = 1; blockCheckLine = NR }
+      if (isMask($0)) { blockMask = 1; blockMaskText = $0; sub(/^[[:space:]]+/, "", blockMaskText) }
+    }
+    END { flush() }' 2>/dev/null)
+  [ -z "$RES" ] || BAD="$BAD$RES
+"
+done
+
+LEFT="$(printf '%s' "$BAD" | grep -v '^$')"
+[ -z "$LEFT" ] && exit 0
+printf '%s\n' "$LEFT"
+echo "  почини: убери «|| true» и «continue-on-error» с шага, который выносит вердикт."
+echo "  шаг, который не может провалиться, — это не проверка, а строка в логе."
+exit 1

package/kit/gates/ci-actually-fails/gate.yml

@@ -0,0 +1,14 @@
+intent: шаг конвейера, выносящий вердикт, может провалиться — а не только выполниться
+intent_en: a pipeline step that renders a verdict can actually fail, not merely run
+
+# Только там, где конвейер есть. Проверять его отсутствие — дело другой записи.
+trigger:
+  has_ci: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-06 «упомянут и работает — разные утверждения» — дыра
+  найдена в собственной оснастке (`gates-run-in-ci` пропускал `pytest || true` зелёным),
+  замер по пятнадцати чужим репозиториям подтвердил класс: у `reviewdog` два шага
+  собственных линтеров идут под `continue-on-error: true`

package/kit/gates/ci-actually-fails/green/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: ci
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm ci
+      - name: тесты
+        run: pytest
+      - name: типы
+        run: tsc --noEmit
+      - name: выгрузить отчёт
+        run: bash scripts/upload-report.sh
+        continue-on-error: true

package/kit/gates/ci-actually-fails/red/.github/workflows/ci.yml

@@ -0,0 +1,12 @@
+name: ci
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm ci
+      - name: тесты
+        run: pytest || true
+      - name: типы
+        run: tsc --noEmit
+        continue-on-error: true

package/kit/gates/gate-not-weakened/README.md

@@ -0,0 +1,54 @@
+# Подавление проверки — точечное и с причиной
+
+**Намерение.** Когда проверка краснеет, у пишущего два выхода: починить код или заглушить
+проверку. Второй дешевле и с виду неотличим от первого — конвейер зелёный, диф маленький.
+
+Для агента это выход по умолчанию: задача сформулирована как «сделай, чтобы прошло», и
+`@ts-ignore` решает её буквально. Дефект при этом остаётся, а сигнал о нём исчезает навсегда —
+это тот же класс, что молчащий гейт, только оплаченный одной строкой.
+
+**Какой отказ это поймало.** Замер по пятнадцати чужим репозиториям (20 774 файла): 22 находки,
+19 настоящих. Среди них — `// @ts-nocheck` первой строкой боевой страницы в `kodus-ai`
+(проверка типов выключена для целого файла), `# noqa E501` без двоеточия в `pr-agent`
+(flake8 такую форму читает как безадресный `# noqa`: погашено не одно правило, а все),
+`/** @ts-ignore */` и `.strict().argv // eslint-disable-line` без имени правила в `repolinter`.
+Запись в журнале: `incidents/README.md`, 2026-09-06.
+
+**Что именно проверяется.** Красным делается только **безадресное** подавление:
+
+| Красное | Зелёное |
+|---|---|
+| `# noqa` | `# noqa: F401  — причина` |
+| `# type: ignore` | `# type: ignore[no-any-return]` |
+| `# flake8: noqa`, `# ruff: noqa`, `# mypy: ignore-errors`, `# pylint: disable=all` | точечная форма с кодом |
+| `/* eslint-disable */`, `// eslint-disable-next-line` без правила | `// eslint-disable-next-line no-console -- причина` |
+| `// @ts-ignore`, `// @ts-nocheck` | `// @ts-expect-error -- причина` |
+| `#[allow(warnings)]`, `@SuppressWarnings("all")`, `//nolint`, `rubocop:disable all`, `shellcheck disable` без `=SC…` | те же с именем правила |
+| `--no-verify` в скрипте или конфиге конвейера | обычный коммит |
+
+`@ts-ignore` красный всегда — единственное исключение из правила «безадресное». У него есть
+строго лучший брат: `@ts-expect-error` краснеет сам, как только становится не нужен, то есть
+не переживает починку кода. `@ts-ignore` переживает и молчит дальше.
+
+**Готовый аналог.** Есть, и под каждый язык свой:
+[`eslint-plugin-eslint-comments`](https://github.com/mysticatea/eslint-plugin-eslint-comments)
+с правилом `require-description` — для JavaScript и TypeScript;
+[`flake8-noqa`](https://github.com/plinss/flake8-noqa) — для Python, он же ловит сломанную форму
+`# noqa E501`. Если проект на одном языке — ставь их, они точнее: разбирают код, а не текст.
+Эта запись нужна там, где языков несколько или где ставить нечего: она переносима, ничего не
+требует установить и покрывает то, чего нет ни у одного из двоих — `@ts-ignore` как класс,
+`--no-verify` в конвейере, `@SuppressWarnings("all")`.
+
+**Чего НЕ ловит.**
+
+- **Подавление внутри строкового литерала считается настоящим.** Фикстуры инструментов, которые
+  сами обрабатывают подавления, дают ложные срабатывания: 3 из 22 на замере — тесты
+  `react-doctor` и `ratchets`. Отличить строку от комментария надёжно можно только разбором
+  языка, а его у переносимой проверки нет. Такие места — в `.aqkignore` или под храповик.
+- **Точечное подавление без причины проходит.** `# noqa: E501` принимается, даже если рядом нет
+  ни слова о том, зачем. Требовать объяснение от каждой строки значит получить гейт, который
+  выключат целиком; за объяснением — к `require-description` из `eslint-plugin-eslint-comments`.
+- **Не видит настройку в конфиге.** Правило, выключенное в `.eslintrc` или `pyproject.toml`, —
+  такое же ослабление, но это уже не подавление в коде, а решение проекта, записанное явно.
+- **Не знает, было ли подавление оправдано.** Проверка отвечает на вопрос «названо ли, что
+  именно погашено», а не «стоило ли гасить».

package/kit/gates/gate-not-weakened/check.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env sh
+# Подавление проверки без адреса: «выключено всё» вместо «выключено вот это».
+#
+# ЗАЧЕМ ИМЕННО ЭТО. Когда проверка краснеет, у пишущего два выхода: починить код или заглушить
+# проверку. Второй дешевле и с виду неотличим от первого — конвейер зелёный, диф маленький.
+# Для агента это выход по умолчанию: ему поставлена задача «сделай, чтобы прошло».
+#
+# ГРАНИЦА НАМЕРЕННО УЗКАЯ. Красным делается не всякое подавление, а безадресное: `# noqa` без
+# кода, `eslint-disable` без имени правила, `@SuppressWarnings("all")`. Точечное подавление с
+# названным правилом — законный инструмент, и требовать объяснения от каждого значит получить
+# гейт, который выключат. Одно исключение — `@ts-ignore`: у него есть строго лучший брат
+# `@ts-expect-error`, который сам краснеет, когда становится не нужен.
+DIR="${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+
+OUT=""
+add() { [ -z "$1" ] || OUT="$OUT$1
+"; }
+
+# --- безадресные подавления в коде -------------------------------------------
+# `# noqa` без двоеточия с кодом; `type: ignore` без [кода]; файловые выключатели целиком.
+add "$(grep -rnE '(^|[^A-Za-z0-9_])#[[:space:]]*(noqa|type:[[:space:]]*ignore)([[:space:]]*$|[[:space:]]+[^:[])' \
+  $(skip_grep) $(include_code) "$DIR" 2>/dev/null)"
+add "$(grep -rnE '#[[:space:]]*(flake8:[[:space:]]*noqa[[:space:]]*$|ruff:[[:space:]]*noqa[[:space:]]*$|mypy:[[:space:]]*ignore-errors|pylint:[[:space:]]*(skip-file|disable=all))' \
+  $(skip_grep) $(include_code) "$DIR" 2>/dev/null)"
+
+# eslint-disable без имени правила: голая директива гасит ВСЁ в файле или на строке.
+#
+# ВЕДУЩИЙ КОММЕНТАРИЙ ОБЯЗАТЕЛЕН — «(//|/\*|\*)[^\"']*». Замер по пятнадцати чужим
+# репозиториям показал целый класс ложных: строка ПРО подавление внутри кавычек
+# («title: 'No @ts-ignore'», текст правила в наборе тестов) читалась как подавление.
+# Директива живёт в комментарии; упоминание в строковом литерале — не она.
+add "$(grep -rnE '(//|/\*|\*)[^\"'"'"']*eslint-disable(-next-line|-line)?[[:space:]]*(\*/|$|--)' \
+  $(skip_grep) $(include_code) "$DIR" 2>/dev/null)"
+
+# @ts-ignore и @ts-nocheck. Первый гасит ошибку молча и остаётся, когда ошибки уже нет;
+# @ts-expect-error на его месте краснеет, как только становится лишним.
+add "$(grep -rnE '(//|/\*|\*)[^\"'"'"']*@ts-(ignore|nocheck)' \
+  $(skip_grep) $(include_code) "$DIR" 2>/dev/null)"
+
+# Остальные экосистемы — только безадресная форма.
+add "$(grep -rnE '#!?\[allow\((warnings|unused)\)\]|@SuppressWarnings\((\{[^}]*)?"all"|//[[:space:]]*nolint[[:space:]]*($|//)|rubocop:disable[[:space:]]+all|shellcheck[[:space:]]+disable[[:space:]]*($|[^=])' \
+  $(skip_grep) $(include_code) "$DIR" 2>/dev/null)"
+
+# --- обход самого конвейера ---------------------------------------------------
+# `--no-verify` пропускает хуки коммита. В committed-скрипте или конфиге конвейера это не
+# настройка, а выключенная защита: смотрим шире кода — в оболочечные скрипты и конфиги.
+# `-e`, а НЕ `--`. Двойное тире завершает разбор опций, и все флаги `--include` после него
+# grep считает именами файлов: проверка читала весь репозиторий вместо оболочечных скриптов и
+# конфигов. Нашлось замером — в выдаче оказались CHANGELOG чужих проектов.
+add "$(grep -rnE -e '--no-verify' $(skip_grep) \
+  --include=*.sh --include=*.yml --include=*.yaml --include=*.json --include=*.toml \
+  --include=*.mk --include=Makefile "$DIR" 2>/dev/null)"
+
+# Собственное определение записи — не подавление, а перечень того, что ищется. Без этого
+# проверка находит сама себя в любом проекте, куда её поставили: `check.sh` содержит все
+# образцы разом. Тот же класс, что образцы red/green, только файл другой.
+SELFDIR="$(basename "$(dirname "$0")")"
+LEFT="$(printf '%s' "$OUT" | grep -v '^$' | own_samples_filter "$DIR" \
+  | grep -vE "(^|/)$SELFDIR/(check\.sh|README\.md)")"
+# Сгенерированные файлы правят не руками: подавление в них поставил инструмент.
+LEFT="$(printf '%s\n' "$LEFT" | while IFS= read -r L; do
+  F="${L%%:*}"
+  [ -n "$F" ] || continue
+  is_generated "$F" || printf '%s\n' "$L"
+done | grep -v '^$')"
+
+[ -z "$LEFT" ] && exit 0
+printf '%s\n' "$LEFT"
+echo "  почини: назови, ЧТО подавляешь и зачем — «# noqa: E501», «eslint-disable-next-line no-console -- причина»,"
+echo "  «@ts-expect-error» вместо «@ts-ignore». Безадресное подавление гасит и то, что сломается завтра."
+exit 1

package/kit/gates/gate-not-weakened/gate.yml

@@ -0,0 +1,15 @@
+intent: проверка выключается точечно и с причиной, а не целиком
+intent_en: a check is suppressed narrowly and with a reason, never wholesale
+
+# Применимо везде, где есть код: подавление проверки — приём, а не язык. Список маркеров
+# покрывает python, typescript, javascript, go, rust, java, ruby и оболочку сразу.
+trigger:
+  always: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-06 «замер по пятнадцати чужим репозиториям» — 22 находки
+  на 20 774 файлах, из них 19 настоящих: `@ts-nocheck` на боевой странице в kodus-ai,
+  сломанный `# noqa E501` без двоеточия в pr-agent (flake8 читает его как безадресный),
+  `/** @ts-ignore */` и `eslint-disable-line` без имени правила в repolinter

package/kit/gates/gate-not-weakened/green/checkout.ts

@@ -0,0 +1,8 @@
+// @ts-expect-error -- у gateway нет типов; строка покраснеет сама, когда они появятся
+import { pay } from "./gateway";
+
+export async function checkout(cart: unknown) {
+  // eslint-disable-next-line no-console -- это программа командной строки, вывод и есть интерфейс
+  console.log(cart);
+  return pay(cart as never);
+}

package/kit/gates/gate-not-weakened/green/payments.py

@@ -0,0 +1,6 @@
+import json  # noqa: F401  — реэкспорт для обратной совместимости, убрать в 2.0
+from decimal import Decimal
+
+
+def total(order):  # type: ignore[no-any-return]  — форма заказа приходит из внешнего API
+    return sum(Decimal(i["price"]) for i in order["items"])

package/kit/gates/gate-not-weakened/green/release.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+git commit -m "release"

package/kit/gates/gate-not-weakened/red/checkout.ts

@@ -0,0 +1,9 @@
+/* eslint-disable */
+// @ts-ignore
+import { pay } from "./gateway";
+
+export async function checkout(cart: unknown) {
+  // eslint-disable-next-line
+  console.log(cart);
+  return pay(cart as never);
+}

package/kit/gates/gate-not-weakened/red/payments.py

@@ -0,0 +1,6 @@
+import json  # noqa
+from decimal import Decimal
+
+
+def total(order):  # type: ignore
+    return sum(Decimal(i["price"]) for i in order["items"])

package/kit/gates/gate-not-weakened/red/release.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+git commit -m "release" --no-verify

package/kit/gates/promise-has-gate/README.md

@@ -0,0 +1,50 @@
+# У правила виден сторож
+
+**Намерение.** Это центральный вопрос всего комплекта. `AGENTS.md` — обычный текст: «никогда не
+коммитим секреты» и «мы очень стараемся» выглядят одинаково и стоят одинаково, пока никто не
+спросил, чем первое отличается от второго.
+
+**Какой отказ это поймало.** Свой собственный. Прогон по нашему же `AGENTS.md`: тринадцать
+железных правил, и **ни одно** не говорило, кто за ним следит. После разметки выяснилось, что
+одиннадцать из тринадцати исполняет человек, а не машина. Это не стало хуже — стало видно.
+Правило, за которым следит человек, законно; правило, о котором никто не знает, кто за ним
+следит, через месяц отличается от лозунга только длиной. Запись в журнале:
+`incidents/README.md`, 2026-09-06.
+
+**Что именно проверяется.** Каждый пункт списка в точке входа, который выглядит правилом
+(выделен жирным либо содержит слово долженствования или запрета), обязан нести пометку:
+
+```markdown
+- **Секреты не в коде.**  <!-- aqk: secrets-not-in-code -->
+- **План до кода.**       <!-- aqk: человек -->
+```
+
+Имя гейта сверяется с блоком `gates:` манифеста: пометка, ведущая в никуда, — тоже красное.
+Пометка живёт в комментарии разметки, поэтому в готовом документе её не видно.
+
+**Почему пометка, а не угадывание.** Сопоставлять обещание с гейтом по совпадению слов — значит
+выдавать вердикт по догадке; догадка, выданная за факт, и есть то, против чего построен весь
+стандарт. Пометка ставится один раз и делает документ честнее: у каждого правила видно, кто его
+сторожит.
+
+**Первый прогон в зрелом проекте покрасит всё.** Так и задумано, и лечится одной командой:
+`aqk ratchet promise-has-gate` — существующие правила становятся долгом, который может только
+сокращаться, а новое правило без сторожа краснеет сразу.
+
+**Готовый аналог.** Не нашли, и искали внимательно. К осени 2026 появился целый класс линтеров
+агентского обвеса — [`agnix`](https://github.com/agent-sh/agnix) (455 правил, активен),
+[`agents-lint`](https://github.com/giacomo/agents-lint), ctxlint, AgentLint. Все они проверяют
+**документ**: формат, живые ли ссылки, существуют ли упомянутые скрипты. Ни один не спрашивает,
+**исполнимо** ли обещание. Ставь `agnix` рядом — он закрывает то, чего не делаем мы, а мы
+закрываем то, чего не делает он.
+
+**Чего НЕ ловит.**
+
+- **Не проверяет, что гейт делает то, что обещано.** Пометка `<!-- aqk: secrets-not-in-code -->`
+  на правиле про длину функций пройдёт. Связь объявляет человек; машина сторожит только то, что
+  связь есть и ведёт в существующий гейт.
+- **`<!-- aqk: человек -->` не проверяется ничем** — это признание, а не проверка. Его ценность
+  в том, что признание сделано вслух и его видно в дифе, когда правил становится больше.
+- **Правило, не оформленное пунктом списка**, не опознаётся: абзац прозы обещанием не считается.
+- **Только точка входа**, объявленная в `entry:`. Правила, разложенные по десяти файлам
+  документации, эта запись не обойдёт.