agent-quality-kit 0.4.2 → 0.6.0

package/README.md

@@ -7,24 +7,61 @@
 [![MIT licence](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
 [![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
-**A standard for whether a repository is ready to have its code written by agents.** Every
-promise the project makes turns into a command with an exit code — held by a machine, not by
-someone's good intentions.
+**Check whether a repository is ready to have its code written by AI coding agents — and turn
+the rules it promises to follow into commands with exit codes.**
 
-What a project needs before that is even possible, in plain words, independent of language and
-tooling: [the dark factory and the minimum that isn't optional](kit/docs/ai/project-baseline.md).
+Your `AGENTS.md` says what the project promises. Nothing checks that those promises are true, or
+that the commands it lists even run. AQK is that missing layer: one command reads the repository,
+reports a level from AQK-0 to AQK-3, and names every guard that is missing.
 
 ```bash
-npx agent-quality-kit start     # no code yet: day-zero guards, right away
 npx agent-quality-kit doctor    # code already exists: your level and what to install
+npx agent-quality-kit start     # no code yet: day-zero guards, right away
+```
+
+`doctor` only reads. It writes no file and sends nothing anywhere — safe to point at a repository
+you have decided nothing about yet. Nothing to install: `npx` fetches the package (230 KB).
+
+### Works with any agent, any language
+
+**Any agent.** Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Aider, OpenCode
+— and with no AI at all. AQK reads and writes plain files (`AGENTS.md`, `.aqk.yml`); it calls no
+vendor API, needs no key, and is tied to no model. A promise only one tool can keep is not a
+promise.
+
+**Any language.** The portable checks are plain `sh` and work on any stack — Python, TypeScript,
+Go, Rust, Java, Ruby, PHP, C#, Kotlin, Swift, Scala. Where the project already has a native tool
+(`ruff`, `eslint`, `knip`, `jscpd`), the check uses it instead, because it is more precise — and
+says so out loud when it falls back.
+
+**Requirements:** Node 18+ and an `sh` shell. Present on macOS, Linux and WSL; Git Bash on Windows.
+
+### One movement, and everything follows from it
+
+```mermaid
+flowchart LR
+    A["<b>AGENTS.md</b><br/>“never commit secrets”<br/><br/><i>a human reads it<br/>and may ignore it</i>"]
+    B["<b>.aqk.yml</b><br/>secrets-not-in-code:<br/>bash gates/…/check.sh<br/><br/><i>a machine holds it<br/>and cannot forget</i>"]
+    C["<b>exit code</b><br/>0 or 1<br/><br/><i>CI acts on it<br/>and cannot argue</i>"]
+    A -- "declare" --> B
+    B -- "run" --> C
 ```
 
-`doctor` only reads: it writes no file and sends nothing anywhere. It is safe to point at
-a repository you have not decided anything about yet.
+A promise the project makes turns into a command with an exit code. From then on a machine holds
+it, not somebody's attention.
+
+What a project needs before that is even possible, in plain words, independent of language and
+tooling: [the dark factory and the minimum that isn't optional](kit/docs/ai/project-baseline.md).
 
-Nothing to install — `npx` fetches the package itself (230 KB). The bleeding edge straight from
-the repository is `npx github:arsen-ask-lx/Agent_Quality_Kit doctor`, but the first run that way
-stays silent for two or three minutes: it clones the whole repository.
+```
+ █████╗   ██████╗ ██╗  ██╗
+██╔══██╗ ██╔═══██╗██║ ██╔╝
+███████║ ██║   ██║█████╔╝
+██╔══██║ ██║▄▄ ██║██╔═██╗
+██║  ██║ ╚██████╔╝██║  ██╗
+╚═╝  ╚═╝  ╚══▀▀═╝ ╚═╝  ╚═╝
+   a promise without an exit code is just a sentence
+```
 
 ## What this looks like
 
@@ -100,6 +137,21 @@ them empty, and they fill in as there becomes something real to put in them.
 **If a claim cannot be checked by a machine, it is not in this standard.** Otherwise the badge
 would mean trust in the author rather than a fact.
 
+### The minimum a project needs
+
+```bash
+aqk doctor --baseline   # ✔/✘ over the points a machine can confirm
+```
+
+The guide [project-baseline.md](kit/docs/ai/project-baseline.md) lists 50 points a project needs
+before the work can be handed to agents. Fourteen of them a machine can confirm from the
+repository — a lockfile of any ecosystem, a linter config of any language, an error tracker in
+the dependencies, a pipeline, tests. It says what proved each one. The remaining 36 are named as
+a number rather than hidden: they are for your eyes.
+
+Presence is what gets checked, not whether it works: "a linter is configured" and "a linter
+catches things" are different claims, and the output says so out loud.
+
 ## Four levels
 
 | Level | Required | What it proves |
@@ -109,6 +161,18 @@ would mean trust in the author rather than a fact.
 | **AQK-2** | gates have red and green samples, debt under a ratchet | the gate catches defects and stays quiet on correct code |
 | **AQK-3** | a lesson journal with conclusions | the same bruise is not collected twice |
 
+```mermaid
+flowchart LR
+    L0["<b>AQK-0</b><br/>a manifest<br/>and an entry point"]
+    L1["<b>AQK-1</b><br/>rules exist,<br/>gates are commands"]
+    L2["<b>AQK-2</b><br/>red and green samples,<br/>debt under a ratchet"]
+    L3["<b>AQK-3</b><br/>a lesson journal<br/>with conclusions"]
+    L0 --> L1 --> L2 --> L3
+```
+
+A level is not a verdict on the project — it measures how **machine-readable** the practice is.
+A hundred working checks with no manifest is AQK-0, and that is honest: nothing can read them.
+
 ```bash
 aqk doctor --run --min 1   # in CI: fails below AQK-1 OR if any gate failed
 ```
@@ -125,10 +189,35 @@ replaces. So `aqk badge` prints nothing over a red gate, and `aqk badge --check`
 pipeline on the day the README and the repository part ways. The badge at the top of this file
 is checked that way on every push.
 
+## As a pre-commit hook
+
+Already using [pre-commit](https://pre-commit.com)? Three lines in the file you already have:
+
+```yaml
+repos:
+  - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
+    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
+      # - id: aqk-baseline # the minimum a project needs, confirmed by a run
+```
+
+`pre-commit` installs the package itself — there is nothing else to set up, and the package has
+no dependencies.
+
+**This does not replace pre-commit, it sits on top of it.** pre-commit runs checks; it says
+nothing about *which* checks exist here, whether they work, and what this project has already
+been burned by. Its own documentation is explicit about both gaps: no built-in compliance levels,
+scoring or reporting — and it does not verify that a hook catches what it claims. That is the
+layer AQK adds.
+
 ## In your pipeline
 
+[![on the GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
+
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.4.1
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.5.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -147,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`.
@@ -200,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

@@ -7,23 +7,62 @@
 [![лицензия MIT](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
 [![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
-**Стандарт готовности репозитория к тому, что код в нём пишет агент.** Обещание проекта
-становится командой с кодом возврата — и его держит машина, а не чья-то добрая воля.
+**Проверить, готов ли репозиторий к тому, что код в нём пишет ИИ-агент — и превратить правила,
+которые проект обещает соблюдать, в команды с кодом возврата.**
 
-Что вообще должно быть на проекте, чтобы это было возможно, — словами, без привязки к языку и
-инструменту: [«тёмная фабрика» и обязательный минимум](kit/docs/ai/project-baseline.md).
+`AGENTS.md` говорит, что проект обещает. Никто не проверяет, правда ли это и запускаются ли
+вообще перечисленные там команды. AQK — тот самый недостающий слой: одна команда читает
+репозиторий, называет ступень от AQK-0 до AQK-3 и перечисляет каждого недостающего сторожа.
 
 ```bash
-npx agent-quality-kit start     # кода ещё нет: сторожа дня 0 сразу
 npx agent-quality-kit doctor    # код уже есть: уровень и что поставить
+npx agent-quality-kit start     # кода ещё нет: сторожа дня 0 сразу
 ```
 
-`doctor` только читает: ни одного файла не пишет и никуда ничего не отправляет. Его можно
-направить на репозиторий, о котором ещё ничего не решено.
+`doctor` только читает: ни одного файла не пишет и никуда ничего не отправляет — его можно
+направить на репозиторий, о котором ещё ничего не решено. Ставить ничего не нужно, `npx` скачает
+пакет сам (230 КБ).
+
+### Работает с любым агентом и любым языком
 
-Ставить ничего не нужно, `npx` скачает пакет сам (230 КБ). Свежая версия прямо из репозитория —
-`npx github:arsen-ask-lx/Agent_Quality_Kit doctor`, но первый запуск такого вида молчит две-три
-минуты: он клонирует репозиторий целиком.
+**Любой агент.** Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Aider,
+OpenCode — и вообще без ИИ. AQK читает и пишет обычные файлы (`AGENTS.md`, `.aqk.yml`), не
+обращается ни к одному API вендора, не требует ключа и не привязан к модели. Обещание, которое
+держит только один инструмент, — не обещание.
+
+**Любой язык.** Переносимые проверки написаны на `sh` и работают на любом стеке — Python,
+TypeScript, Go, Rust, Java, Ruby, PHP, C#, Kotlin, Swift, Scala. Там, где у проекта уже есть
+родной инструмент (`ruff`, `eslint`, `knip`, `jscpd`), проверка берёт его — он точнее, — и вслух
+сообщает, когда откатилась на переносимый.
+
+**Требуется:** Node 18+ и оболочка `sh`. Есть на macOS, Linux и в WSL; на Windows — Git Bash.
+
+### Одно движение, из которого следует всё остальное
+
+```mermaid
+flowchart LR
+    A["<b>AGENTS.md</b><br/>«не коммить секреты»<br/><br/><i>читает человек<br/>и может забыть</i>"]
+    B["<b>.aqk.yml</b><br/>secrets-not-in-code:<br/>bash gates/…/check.sh<br/><br/><i>держит машина<br/>и забыть не может</i>"]
+    C["<b>код возврата</b><br/>0 или 1<br/><br/><i>знает конвейер<br/>и спорить не станет</i>"]
+    A -- "объявили" --> B
+    B -- "запустили" --> C
+```
+
+Обещание проекта становится командой с кодом возврата. Дальше его держит машина, а не чьё-то
+внимание.
+
+Что вообще должно быть на проекте, чтобы это было возможно, — словами, без привязки к языку и
+инструменту: [«тёмная фабрика» и обязательный минимум](kit/docs/ai/project-baseline.md).
+
+```
+ █████╗   ██████╗ ██╗  ██╗
+██╔══██╗ ██╔═══██╗██║ ██╔╝
+███████║ ██║   ██║█████╔╝
+██╔══██║ ██║▄▄ ██║██╔═██╗
+██║  ██║ ╚██████╔╝██║  ██╗
+╚═╝  ╚═╝  ╚══▀▀═╝ ╚═╝  ╚═╝
+   обещание без кода возврата — просто предложение
+```
 
 ## Что это выглядит так
 
@@ -99,6 +138,21 @@ lessons:  incidents        # где копятся уроки
 **Если утверждение нельзя проверить машиной — его в стандарте нет.** Иначе значок означает
 доверие к автору, а не факт.
 
+### Обязательный минимум проекта
+
+```bash
+aqk doctor --baseline   # ✔/✘ по пунктам, которые машина может подтвердить
+```
+
+Методичка [project-baseline.md](kit/docs/ai/project-baseline.md) перечисляет 50 пунктов, без
+которых работу нельзя отдать агентам. Четырнадцать из них машина подтверждает по репозиторию —
+файл-замок любой экосистемы, конфиг линтера любого языка, трекер ошибок в зависимостях,
+конвейер, тесты. И называет, чем именно подтвердила. Оставшиеся 36 названы числом, а не спрятаны:
+они — глазами.
+
+Проверяется НАЛИЧИЕ признака, а не то, что он работает: «линтер настроен» и «линтер ловит» —
+разные утверждения, и вывод говорит это вслух.
+
 ## Четыре ступени
 
 | Уровень | Требуется | Что доказано |
@@ -108,6 +162,18 @@ lessons:  incidents        # где копятся уроки
 | **AQK-2** | у гейтов красные и зелёные образцы, долг под храповиком | гейт ловит брак и молчит на исправном коде |
 | **AQK-3** | журнал уроков с выводами | шишка не набивается дважды |
 
+```mermaid
+flowchart LR
+    L0["<b>AQK-0</b><br/>манифест<br/>и точка входа"]
+    L1["<b>AQK-1</b><br/>правила есть,<br/>гейты — команды"]
+    L2["<b>AQK-2</b><br/>красный и зелёный образцы,<br/>долг под храповиком"]
+    L3["<b>AQK-3</b><br/>журнал шишек<br/>с выводами"]
+    L0 --> L1 --> L2 --> L3
+```
+
+Ступень — не приговор проекту: она мерит, насколько практика **машиночитаема**. Сто работающих
+проверок без манифеста — это AQK-0, и это честно: их никто не может прочитать.
+
 ```bash
 aqk doctor --run --min 1   # в конвейере: ошибка, если ниже AQK-1 ИЛИ упал хоть один гейт
 ```
@@ -124,10 +190,34 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 роняет конвейер в тот день, когда README и репозиторий разошлись. Значок в начале этого файла
 проверяется так на каждом пуше.
 
+## Как хук pre-commit
+
+Уже пользуешься [pre-commit](https://pre-commit.com)? Три строки в файл, который у тебя и так
+лежит:
+
+```yaml
+repos:
+  - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
+    rev: v0.6.0
+    hooks:
+      - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
+      # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
+      # - id: aqk-baseline # обязательный минимум проекта, подтверждённый прогоном
+```
+
+`pre-commit` ставит пакет сам — настраивать больше нечего, зависимостей у пакета нет.
+
+**Это не замена pre-commit, а слой над ним.** pre-commit запускает проверки, но ничего не
+говорит о том, **какие** проверки в репозитории есть, работают ли они и на чём здесь уже
+обжигались. Его собственная документация признаёт обе дыры прямо: нет ни уровней, ни оценки, ни
+отчётности — и он не проверяет, что хук ловит то, что заявляет. Этот слой и добавляет AQK.
+
 ## В твоём конвейере
 
+[![в GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
+
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.4.1
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.5.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -196,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
+```
+
 ## Запись без переносимого рецепта
 
 Иногда переносимой проверки быть не может: чтобы понять, вызывают ли функцию, нужен граф
@@ -113,6 +133,20 @@ samples_for: python
 если завтра поправят источник?» Правильный ответ — «результат изменится сам», а не «нужно
 поправить ещё и здесь».
 
+Седьмой, с прогона по живому проекту: **гейт, тонущий в собственном шуме.** Родной инструмент
+не получал общий список исключений и читал `.aqk/` — каталог, который положил сам комплект. Из
+1846 находок 435 были не про код вовсе. Гейт остаётся правильным и становится нечитаемым, а
+нечитаемый выключают целиком. Мера здесь — доля находок не по делу, а не длина вывода.
+
+Восьмой, оттуда же: **родной и переносимый рецепты одной записи мерят разное.** Переносимый
+смотрел только в расширения кода, родной — во всё подряд. Один гейт означал разное на разных
+машинах, и какое именно — зависело от того, что стоит в системе.
+
+Девятый, найденный мутационной проверкой: **гейт держится за то, чего не заявляет.** Четыре
+записи переставали работать на windows-переносах строк — жадный захват в `sed` проглатывал
+`\r`. Красный образец зеленел, зелёный краснел. Пара образцов этого не видит: она доказывает
+одно срабатывание, а не класс. Ловит `tool/selfcheck/mutation.sh`.
+
 Зелёный образец закрывает третий способ, и он важнее красного: что гейт ловит брак, проверяют
 при установке; что он молчит на исправном коде — не проверяют почти никогда.
 
@@ -159,6 +193,7 @@ samples_for: python
 | `has_deps: true` | есть файл зависимостей |
 | `has_tests: true` | есть каталог тестов или файлы вида `*_test.*` |
 | `has_env: true` | есть файл окружения |
+| `has_ui: true` | есть стили или однофайловые компоненты (`.css`, `.scss`, `.vue`, `.svelte`, `.astro`) |
 
 Любое из `has_*` принимает и `false` — «показывать тем, у кого этого нет». Условие, которого
 программа не знает, отклоняется явно, а не пропускается молча.

package/kit/gates/_native.sh

@@ -22,8 +22,24 @@ shift || true
 
 . "$(dirname "$0")/_skip.sh" 2>/dev/null || { echo "не найден _skip.sh рядом с _native.sh"; exit 2; }
 
-OUT="$("$@" 2>&1)"; CODE=$?
-LEFT="$(printf '%s' "$OUT" | own_samples_filter "$DIR")"
+# Два фильтра, а не один: own_samples_filter прячет образцы гейтов и то, что назвал проект
+# в .aqkignore, а skip_paths_filter — общий список каталогов, который переносимые проверки
+# получают при обходе. Родному инструменту он не доставался вовсе, и он читал `.aqk/`,
+# `node_modules` и `.venv`. На живом проекте это дало 5597 строк вывода, где первой находкой
+# были методички самого комплекта.
+# Цвет снимается ДО фильтров. Родные инструменты печатают путь внутри escape-последовательности
+# («\033[32m.aqk/docs/…»), и тогда имя каталога стоит не после «/» и не с начала строки — фильтр
+# по границе пути его не видит. На живом проекте это выглядело как работающая правка: вывод
+# сократился с 5597 строк до 5505, то есть не сократился. Заодно лог конвейера читается глазами.
+# Код возврата берётся у САМОГО инструмента, до всякой обработки: в конвейере `$?` — это код
+# последней команды, и снятие цвета молча делало бы любой прогон успешным.
+OUT_RAW="$("$@" 2>&1)"; CODE=$?
+
+# ESC подставляется через printf, а не пишется как \x1b: это расширение GNU sed, а гейты
+# обязаны работать на любом sh.
+ESC="$(printf '\033')"
+OUT="$(printf '%s' "$OUT_RAW" | sed -e "s/${ESC}\[[0-9;]*[a-zA-Z]//g")"
+LEFT="$(printf '%s' "$OUT" | skip_paths_filter | own_samples_filter "$DIR")"
 
 # Отказ не выдумываем: если инструмент завершился успешно, результат успешен, что бы ни
 # осталось в выводе. Красным делаем только то, что инструмент И счёл отказом, И что пережило

package/kit/gates/_skip.sh

@@ -82,6 +82,24 @@ skip_grep() {
   for N in $SKIP_NAMES; do printf -- '--exclude-dir=%s ' "$N"; done
 }
 
+# Для вывода родного инструмента: отбрасывает строки, чей путь лежит внутри пропускаемого
+# каталога. Переносимые проверки получают этот список при обходе (skip_grep/skip_find), а
+# родному инструменту он не доставался вовсе: на живом проекте первой находкой duplicate-code
+# оказались методички самого комплекта в `.aqk/docs`, которые туда положил `init`.
+#
+# По сегменту пути, а не по подстроке — тот же урок, что с папкой `red`: имя «build» встречается
+# и внутри слова, и файл `src/rebuild.py` прятать нельзя.
+skip_paths_filter() {
+  RE_SKIP="$(printf '%s' "$SKIP_NAMES" | tr '\n' ' ' | sed -e 's/^ *//' -e 's/ *$//' \
+    -e 's/\./\\./g' -e 's/  */|/g')"
+  [ -n "$RE_SKIP" ] || { cat; return; }
+  # Граница слева — начало строки, «/» или любой символ, которого не бывает внутри имени пути.
+  # Родные инструменты печатают путь не с начала строки: у jscpd это « - путь». Пока требовалось
+  # начало строки или «/», такие строки не отсеивались вовсе. Буквы, цифры, «_», «.» и «-»
+  # границей не считаются — иначе «build/» отсеяло бы и «rebuild/».
+  grep -vE "(^|/|[^[:alnum:]_.-])($RE_SKIP)/"
+}
+
 # Для find: -name X -prune -o …
 skip_find() {
   for N in $SKIP_NAMES; do printf -- '-name %s -prune -o ' "$N"; done

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()`** маскировкой не считается: он про порядок выполнения, а не про вердикт.