agent-quality-kit 0.2.4 → 0.3.0

package/README.md

@@ -1,160 +1,184 @@
 # AQK — Agent Quality Kit
 
+**English** · [Русский](README.ru.md)
+
 [![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
-[![проверки](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
-[![лицензия MIT](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
+[![checks](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
+[![MIT licence](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
 
-**Стандарт готовности репозитория к тому, что код в нём пишет агент.** Обещание проекта
-становится командой с кодом возврата — и его держит машина, а не чья-то добрая воля.
+**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.
 
-Что вообще должно быть на проекте, чтобы это было возможно, — словами, без привязки к языку и
-инструменту: [«тёмная фабрика» и обязательный минимум](kit/docs/ai/project-baseline.md).
+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).
 
 ```bash
-npx agent-quality-kit start     # кода ещё нет: сторожа дня 0 сразу
-npx agent-quality-kit doctor    # код уже есть: уровень и что поставить
+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` скачает пакет сам (230 КБ). Свежая версия прямо из репозитория —
-`npx github:arsen-ask-lx/Agent_Quality_Kit doctor`, но первый запуск такого вида молчит две-три
-минуты: он клонирует репозиторий целиком.
+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.
 
-**Что нужно.** Node 18+ и оболочка `sh` — она есть в macOS, Linux и WSL; на Windows подойдёт
-Git Bash. Переносимые проверки написаны на `sh` намеренно: он есть везде, где собирают код.
+**Requirements.** Node 18+ and an `sh` shell — present on macOS, Linux and WSL; Git Bash works on
+Windows. The portable checks are written in `sh` on purpose: it exists everywhere code is built.
 
-**Не зависит от инструмента:** Claude Code, Codex, Cursor — и без ИИ тоже.
+**Tool-agnostic:** Claude Code, Codex, Cursor — and without AI at all.
 
-При первой установке на машине `init`/`start` один раз печатают ссылку на звезду и на «завести
-Issue» — ничего не постится сама, только текст для человека, и больше не повторяется.
+The first time you run `init`/`start` on a machine, it prints a link to star the repo and to open
+an issue, once. Nothing is posted anywhere — it is text for a human, and it never repeats.
 
-**Готовые правила ставятся отдельно и по желанию.** Переносимая проверка работает без них
-всегда; если в проекте стоит `ruff`, `eslint` или `vulture`, запись возьмёт готовое правило —
-оно точнее. Одна запись, `dead-code`, без готового инструмента не работает вовсе и честно
-скрывается: граф вызовов поиском по тексту не построить.
+**Off-the-shelf rules are optional and installed separately.** The portable check always works
+without them; if the project already has `ruff`, `eslint` or `vulture`, the entry will use the
+native rule instead — it is more precise. One entry, `dead-code`, does not work at all without a
+real tool and honestly hides itself: you cannot build a call graph with a text search.
 
-## Как устроено
+## How it works
 
-Весь стандарт — файл `.aqk.yml` в корне:
+The whole standard is one `.aqk.yml` file in the repository root:
 
 ```yaml
 aqk: 1
-entry:  [AGENTS.md]        # что агент читает первым
-rules:  .aqk/rules         # где стандарты
-gates:                     # что обязано пройти — командами, не словами
+entry:  [AGENTS.md]        # what the agent reads first
+rules:  .aqk/rules         # where the standards live
+gates:                     # what must pass — as commands, not as prose
   lint: "npm run lint"
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
-samples:  gates            # красный и зелёный образец каждой записи
-ratchets: ratchets         # реестры долга: список может только укорачиваться
-lessons:  incidents        # где копятся уроки
+samples:  gates            # a red and a green sample for every entry
+ratchets: ratchets         # debt registries: the list may only get shorter
+lessons:  incidents        # where lessons accumulate
 ```
 
-Пустое поле — не заглушка, а честный ответ «ступень не пройдена»: `init` кладёт их пустыми,
-а заполняются они по мере того, как появляется чем их заполнить.
+An empty field is not a placeholder — it is an honest "this level is not reached". `init` writes
+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.
 
-## Четыре ступени
+## Four levels
 
-| Уровень | Требуется | Что доказано |
+| Level | Required | What it proves |
 |---|---|---|
-| **AQK-0** | манифест и точка входа | инструмент знает, что читать |
-| **AQK-1** | правила есть, гейты объявлены командами | проверки исполняются |
-| **AQK-2** | у гейтов красные и зелёные образцы, долг под храповиком | гейт ловит брак и молчит на исправном коде |
-| **AQK-3** | журнал уроков с выводами | шишка не набивается дважды |
+| **AQK-0** | a manifest and an entry point | the tooling knows what to read |
+| **AQK-1** | rules exist, gates declared as commands | the checks are executable |
+| **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 |
 
 ```bash
-aqk doctor --run --min 1   # в конвейере: ошибка, если ниже AQK-1 ИЛИ упал хоть один гейт
+aqk doctor --run --min 1   # in CI: fails below AQK-1 OR if any gate failed
 ```
 
-## Поставить гейт
+## Installing a gate
 
 ```bash
-aqk find "печать в проде"     # есть ли уже такой гейт — сверка по намерению
-aqk doctor                    # что применимо к этому репозиторию и чего нет
-aqk add secrets-not-in-code   # копирует проверку и образцы в проект, объявляет в манифесте
-aqk doctor --run              # запускает объявленные гейты и показывает результат
-aqk ratchet no-print-in-prod  # старое — долг, новое не пускать
+aqk find "print statements in production"   # is there already such a gate — matched by intent
+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 ratchet no-print-in-prod                # existing violations become debt, new ones are blocked
 ```
 
-Каждый `doctor --run` перезаписывает `.aqk/last-run.md` — короткий отчёт, что из объявленного
-реально сработало и за сколько. Список гейтов в манифесте молчит о том, сколько из них живы
-именно сейчас; отчёт — нет. Файл эфемерный, в `.gitignore` его стоит держать самому.
+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`.
 
-## Поймал ошибку, которую не поймал сторож
+## When a bug slips past the guards
 
 ```bash
-aqk why "файл вырос до девяти тысяч строк"
+aqk why "a file grew to nine thousand lines"
 ```
 
-Ответ один из трёх, и выбирает его прогон, а не память: **сторожа не было** · **сторож есть,
-но эту поломку не видит** · **сторож есть и ловит — значит его обошли**. Разница решает, что
-чинить: саму проверку или её место в конвейере. Без прогона эти два случая неразличимы, и
-чинят обычно не тот. При неуверенном совпадении команда не выбирает за тебя, а спрашивает.
+The answer is one of three, and it is chosen by an actual run rather than by memory: **there was
+no guard** · **the guard exists but does not see this failure** · **the guard exists and catches
+it — so it was bypassed**. The difference decides what to fix: the check itself, or its place in
+the pipeline. Without a run those two are indistinguishable, and people usually fix the wrong
+one. On an uncertain match the command asks instead of choosing for you.
+
+**The ratchet** is for introducing a rule into a project whose existing code violates it. The
+violations are captured into a registry; the gate lets that list get **shorter** and refuses to
+let it grow. The rule applies from the day it is installed — the old code stays untouched.
+
+`add` **copies the check into your repository** rather than referencing the package: installed
+via `npx` the package is temporary, and tomorrow the command in your manifest would point at
+nothing.
+
+## Third-party code inside the repository
 
-**Храповик** нужен, когда правило вводят в проект, где старый код ему не соответствует.
-Список нарушений снимается в реестр, гейт разрешает его **укорачивать** и запрещает удлинять.
-Правило действует со дня установки, старый код трогать не надо.
+A reference copy, vendored code, generated clients — code that lives here but was not written
+here. The scanning checks will skip it if you add `.aqkignore` in the root: one pattern per line,
+`#` starts a comment, and `*` does not cross `/`.
 
-`add` **копирует проверку в репозиторий**, а не ссылается на пакет: при установке через `npx`
-пакет временный, и завтра команда в манифесте указывала бы в никуда.
+```
+# brought in from another repository
+third-party/
+vendor/
+*.generated.js
+```
 
-## Каталог обещаний
+`aqk report` prints the contents of this file as its own section. Hiding things silently is the
+same class as a silent gate: a line here means there is no protection along that path, and will
+not be.
 
-`doctor` смотрит на репозиторий — языки, наличие гейтов — и показывает **только применимое**:
-что уже держит машина, что применимо и не поставлено, что скрыто и почему. Каталог может
-вырасти до сотен записей, конкретный проект по-прежнему увидит десяток.
+## The catalogue of promises
 
-Запись принимается, только если её арбитр краснеет на красном образце, молчит на зелёном и
-назван реальный отказ, который она поймала. Проверяет это машина: `bash tool/selfcheck/gates.sh`.
+`doctor` inspects the repository — languages, existing gates — and shows **only what applies**:
+what a machine already holds, what applies but is not installed, and what is hidden and why. The
+catalogue may grow to hundreds of entries; a given project still sees about a dozen.
 
-## Методички одним файлом
+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`.
+
+## The guides as a single file
 
 ```bash
-aqk blob     # собирает GOD_AI.md из kit/docs — чтобы разом отдать методички в чат
+aqk blob     # assembles GOD_AI.md out of kit/docs — to hand the guides to a chat in one go
 ```
 
-Файл **собирается, а не хранится**: править надо оригиналы. Копия, которую правят руками, через
-неделю расходится с источником, и непонятно, какая настоящая.
+The file is **assembled, not stored**: edit the originals. A hand-edited copy drifts from its
+source within a week, and then nobody knows which one is real.
 
-## Принести свой гейт
+## Contributing a gate
 
-Каталог живёт чужими шишками. Порядок и порог — в [`CONTRIBUTING.md`](CONTRIBUTING.md):
-сверься `aqk find`, заведи заготовку `aqk new`, положи два образца, заполни четыре поля,
-прогони машиной. Отбор делает `tool/selfcheck/gates.sh`, а не рецензент.
+The catalogue lives on other people's bruises. The procedure and the bar are in
+[`CONTRIBUTING.md`](CONTRIBUTING.md): check for duplicates with `aqk find`, scaffold with
+`aqk new`, add two samples, fill in four fields, run the machine. The filtering is done by
+`tool/selfcheck/gates.sh`, not by a reviewer.
 
-## Журнал шишек
+## The bruise journal
 
 ```bash
-aqk note "гейт краснел на правильном коде"    # запись без раздела «Вывод» не принимается
+aqk note "the gate went red on correct code"   # an entry without a conclusion is rejected
 ```
 
-## Честно о состоянии
-
-Задача целиком — в [`PROJECT.md`](PROJECT.md): что строим, четыре сценария, критерий успеха, что осталось.
+## Honestly, where this stands
 
+The full brief is in [`PROJECT.md`](PROJECT.md) (in Russian): what is being built, the four
+scenarios, the success criterion, and what is left.
 
-Версия 1, один автор. Сам комплект держит **AQK-3**: девятнадцать проверок объявлено и
-прогоняется конвейером, два реестра долга под храповиком. Пока комплектом пользуется один
-человек, AQK — красивое слово в README. Он начнёт работать, когда появится чужой третий проект.
+Version 1, one author. The kit holds **AQK-3** on itself: everything declared is executed by CI
+on every push, two debt registries under a ratchet — `node tool/program.mjs doctor --run --min 1`.
+As long as one person uses it, AQK is a nice acronym in a README. It starts being real when a
+third, foreign project appears.
 
-**Стандарт нельзя выпустить первым.** Спецификация раньше практики — это тридцать первый
-заброшенный репозиторий с манифестом и нулём пользователей. Порядок обратный:
+**A standard cannot be shipped first.** A specification ahead of practice is the thirty-first
+abandoned repository with a manifest and zero users. The order is the other way round:
 
-| # | Шаг | Состояние |
+| # | Step | State |
 |---|---|---|
-| 1 | живём по этому на своих проектах | ⬜ измерено: у трёх своих проектов манифеста нет, уровень не заведён |
-| 2 | `doctor` считает уровень | ✅ сделано |
-| 3 | сложившееся записано как короткая спецификация | ✅ [`SPEC.md`](SPEC.md) |
-| 4 | третий проект — **чужой** | ❌ первый честный сигнал, его ещё нет |
-| 5 | значок, сайт, разговор с людьми | ❌ только после четвёртого шага |
+| 1 | live by this on our own projects | ⬜ measured: three of our own projects have no manifest |
+| 2 | `doctor` computes the level | ✅ done |
+| 3 | what settled is written up as a short spec | ✅ [`SPEC.md`](SPEC.md) |
+| 4 | a third project — **someone else's** | ❌ the first honest signal, still missing |
+| 5 | badge, site, talking to people | ❌ only after step four |
 
-## Очередь работ
+## The work queue
 
-Живёт в одном месте — [`PROJECT.md` §9](PROJECT.md). Список здесь не повторяется: два списка через месяц
-расходятся, и непонятно, какой настоящий.
+Lives in one place — [`PROJECT.md` §9](PROJECT.md). It is not repeated here: two lists drift
+apart within a month, and then nobody knows which is real.
 
-Чего нет: второго пользователя; покрытия команд, которые пишут на диск (проверены прогоном на
-чистой папке, но не по отдельности); третьего — чужого — проекта.
+What is missing: a second user; per-command coverage of the commands that write to disk (they are
+exercised by a clean-folder run, but not individually); a third — foreign — project.
 
 MIT.

package/README.ru.md

@@ -0,0 +1,178 @@
+# AQK — Agent Quality Kit
+
+[English](README.md) · **Русский**
+
+[![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
+[![проверки](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
+[![лицензия MIT](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
+
+**Стандарт готовности репозитория к тому, что код в нём пишет агент.** Обещание проекта
+становится командой с кодом возврата — и его держит машина, а не чья-то добрая воля.
+
+Что вообще должно быть на проекте, чтобы это было возможно, — словами, без привязки к языку и
+инструменту: [«тёмная фабрика» и обязательный минимум](kit/docs/ai/project-baseline.md).
+
+```bash
+npx agent-quality-kit start     # кода ещё нет: сторожа дня 0 сразу
+npx agent-quality-kit doctor    # код уже есть: уровень и что поставить
+```
+
+Ставить ничего не нужно, `npx` скачает пакет сам (230 КБ). Свежая версия прямо из репозитория —
+`npx github:arsen-ask-lx/Agent_Quality_Kit doctor`, но первый запуск такого вида молчит две-три
+минуты: он клонирует репозиторий целиком.
+
+**Что нужно.** Node 18+ и оболочка `sh` — она есть в macOS, Linux и WSL; на Windows подойдёт
+Git Bash. Переносимые проверки написаны на `sh` намеренно: он есть везде, где собирают код.
+
+**Не зависит от инструмента:** Claude Code, Codex, Cursor — и без ИИ тоже.
+
+При первой установке на машине `init`/`start` один раз печатают ссылку на звезду и на «завести
+Issue» — ничего не постится сама, только текст для человека, и больше не повторяется.
+
+**Готовые правила ставятся отдельно и по желанию.** Переносимая проверка работает без них
+всегда; если в проекте стоит `ruff`, `eslint` или `vulture`, запись возьмёт готовое правило —
+оно точнее. Одна запись, `dead-code`, без готового инструмента не работает вовсе и честно
+скрывается: граф вызовов поиском по тексту не построить.
+
+## Как устроено
+
+Весь стандарт — файл `.aqk.yml` в корне:
+
+```yaml
+aqk: 1
+entry:  [AGENTS.md]        # что агент читает первым
+rules:  .aqk/rules         # где стандарты
+gates:                     # что обязано пройти — командами, не словами
+  lint: "npm run lint"
+  secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
+samples:  gates            # красный и зелёный образец каждой записи
+ratchets: ratchets         # реестры долга: список может только укорачиваться
+lessons:  incidents        # где копятся уроки
+```
+
+Пустое поле — не заглушка, а честный ответ «ступень не пройдена»: `init` кладёт их пустыми,
+а заполняются они по мере того, как появляется чем их заполнить.
+
+**Если утверждение нельзя проверить машиной — его в стандарте нет.** Иначе значок означает
+доверие к автору, а не факт.
+
+## Четыре ступени
+
+| Уровень | Требуется | Что доказано |
+|---|---|---|
+| **AQK-0** | манифест и точка входа | инструмент знает, что читать |
+| **AQK-1** | правила есть, гейты объявлены командами | проверки исполняются |
+| **AQK-2** | у гейтов красные и зелёные образцы, долг под храповиком | гейт ловит брак и молчит на исправном коде |
+| **AQK-3** | журнал уроков с выводами | шишка не набивается дважды |
+
+```bash
+aqk doctor --run --min 1   # в конвейере: ошибка, если ниже AQK-1 ИЛИ упал хоть один гейт
+```
+
+## Поставить гейт
+
+```bash
+aqk find "печать в проде"     # есть ли уже такой гейт — сверка по намерению
+aqk doctor                    # что применимо к этому репозиторию и чего нет
+aqk add secrets-not-in-code   # копирует проверку и образцы в проект, объявляет в манифесте
+aqk doctor --run              # запускает объявленные гейты и показывает результат
+aqk ratchet no-print-in-prod  # старое — долг, новое не пускать
+```
+
+Каждый `doctor --run` перезаписывает `.aqk/last-run.md` — короткий отчёт, что из объявленного
+реально сработало и за сколько. Список гейтов в манифесте молчит о том, сколько из них живы
+именно сейчас; отчёт — нет. Файл эфемерный, в `.gitignore` его стоит держать самому.
+
+## Поймал ошибку, которую не поймал сторож
+
+```bash
+aqk why "файл вырос до девяти тысяч строк"
+```
+
+Ответ один из трёх, и выбирает его прогон, а не память: **сторожа не было** · **сторож есть,
+но эту поломку не видит** · **сторож есть и ловит — значит его обошли**. Разница решает, что
+чинить: саму проверку или её место в конвейере. Без прогона эти два случая неразличимы, и
+чинят обычно не тот. При неуверенном совпадении команда не выбирает за тебя, а спрашивает.
+
+**Храповик** нужен, когда правило вводят в проект, где старый код ему не соответствует.
+Список нарушений снимается в реестр, гейт разрешает его **укорачивать** и запрещает удлинять.
+Правило действует со дня установки, старый код трогать не надо.
+
+`add` **копирует проверку в репозиторий**, а не ссылается на пакет: при установке через `npx`
+пакет временный, и завтра команда в манифесте указывала бы в никуда.
+
+## Чужой код в репозитории
+
+Референс, вендоринг, сгенерированные клиенты — код лежит здесь, но написан не здесь. Сканирующие
+проверки по нему не пойдут, если завести `.aqkignore` в корне: по шаблону на строку, `#` —
+комментарий, звёздочка не переходит через `/`.
+
+```
+# принесено из другого репозитория
+third-party/
+vendor/
+*.generated.js
+```
+
+`aqk report` печатает содержимое этого файла отдельным разделом. Скрытое молча — тот же класс,
+что молчащий гейт: строка здесь означает, что защиты по этому пути нет и не будет.
+
+## Каталог обещаний
+
+`doctor` смотрит на репозиторий — языки, наличие гейтов — и показывает **только применимое**:
+что уже держит машина, что применимо и не поставлено, что скрыто и почему. Каталог может
+вырасти до сотен записей, конкретный проект по-прежнему увидит десяток.
+
+Запись принимается, только если её арбитр краснеет на красном образце, молчит на зелёном и
+назван реальный отказ, который она поймала. Проверяет это машина: `bash tool/selfcheck/gates.sh`.
+
+## Методички одним файлом
+
+```bash
+aqk blob     # собирает GOD_AI.md из kit/docs — чтобы разом отдать методички в чат
+```
+
+Файл **собирается, а не хранится**: править надо оригиналы. Копия, которую правят руками, через
+неделю расходится с источником, и непонятно, какая настоящая.
+
+## Принести свой гейт
+
+Каталог живёт чужими шишками. Порядок и порог — в [`CONTRIBUTING.md`](CONTRIBUTING.md):
+сверься `aqk find`, заведи заготовку `aqk new`, положи два образца, заполни четыре поля,
+прогони машиной. Отбор делает `tool/selfcheck/gates.sh`, а не рецензент.
+
+## Журнал шишек
+
+```bash
+aqk note "гейт краснел на правильном коде"    # запись без вывода не принимается
+```
+
+## Честно о состоянии
+
+Задача целиком — в [`PROJECT.md`](PROJECT.md): что строим, четыре сценария, критерий успеха, что осталось.
+
+Версия 1, один автор. Сам комплект держит **AQK-3**: всё объявленное прогоняется конвейером при
+каждом пуше, два реестра долга под храповиком — `node tool/program.mjs doctor --run --min 1`.
+Пока комплектом пользуется один человек, AQK — красивое слово в README. Он начнёт работать,
+когда появится чужой третий проект.
+
+**Стандарт нельзя выпустить первым.** Спецификация раньше практики — это тридцать первый
+заброшенный репозиторий с манифестом и нулём пользователей. Порядок обратный:
+
+| # | Шаг | Состояние |
+|---|---|---|
+| 1 | живём по этому на своих проектах | ⬜ измерено: у трёх своих проектов манифеста нет, уровень не заведён |
+| 2 | `doctor` считает уровень | ✅ сделано |
+| 3 | сложившееся записано как короткая спецификация | ✅ [`SPEC.md`](SPEC.md) |
+| 4 | третий проект — **чужой** | ❌ первый честный сигнал, его ещё нет |
+| 5 | значок, сайт, разговор с людьми | ❌ только после четвёртого шага |
+
+## Очередь работ
+
+Живёт в одном месте — [`PROJECT.md` §9](PROJECT.md). Список здесь не повторяется: два списка через месяц
+расходятся, и непонятно, какой настоящий.
+
+Чего нет: второго пользователя; покрытия команд, которые пишут на диск (проверены прогоном на
+чистой папке, но не по отдельности); третьего — чужого — проекта.
+
+MIT.

package/kit/gates/_skip.sh

@@ -21,11 +21,39 @@ migrations"
 # (red-team тесты, что угодно) становился невидим для secrets-not-in-code во всех проектах,
 # куда ставили гейт. Фильтр ниже смотрит на путь целиком: только `gates/<имя>/red|green/`,
 # а не голое имя каталога.
+# Список исключений САМОГО ПРОЕКТА: файл .aqkignore в корне, по шаблону на строку, «#» —
+# комментарий. Нужен для кода, который лежит в репозитории, но написан не здесь: референс,
+# вендоринг, сгенерированные клиенты. Без него единственным способом настройки была правка
+# КОПИИ этого файла в проекте — то есть настройка правкой чужого файла, которую затирает
+# следующий `aqk add`. Найдено первым чужим прогоном.
+#
+# Шаблон — фрагмент пути: `vendor/`, `apps/legacy`, `*.generated.js`. Звёздочка не переходит
+# через «/», как в .gitignore, — иначе «src/*» прятало бы весь проект.
+aqkignore_re() {
+  F="${1:-.}/.aqkignore"
+  [ -f "$F" ] || return 1
+  sed -e 's/#.*$//' -e 's|/*[[:space:]]*$||' -e 's/^[[:space:]]*//' "$F" |
+    grep -v '^$' |
+    sed -e 's/[][(){}.^$+?|\\]/\\&/g' -e 's/\*/[^\/]*/g' |
+    tr '\n' '|' | sed 's/|$//'
+}
+
+# Один фильтр на два дела, и это осознанно: его зовут все семь сканирующих проверок, а их
+# копии уже лежат в чужих проектах. Добавить сюда — значит, что обновление комплекта включает
+# .aqkignore и у тех, кто ставил гейты раньше, без перекопирования их check.sh.
 own_samples_filter() {
-  case "${1:-}" in
-    */red|*/red/|*/green|*/green/) cat ;;
-    *) grep -vE '/gates/[^/]+/(red|green)(/|$)' ;;
+  DIR0="${1:-}"
+  RE="$(aqkignore_re "$DIR0")"
+  case "$DIR0" in
+    # Цель проверки — сам образец: тогда прятать его нельзя, иначе гейт «пройдёт» на красном.
+    */red|*/red/|*/green|*/green/) SAMPLES="cat" ;;
+    *) SAMPLES="grep -vE /gates/[^/]+/(red|green)(/|\$)" ;;
   esac
+  if [ -n "$RE" ]; then
+    $SAMPLES | grep -vE "(^|/)($RE)(/|:|\$)"
+  else
+    $SAMPLES
+  fi
 }
 
 # Расширения, где `print` и маркеры долга — конструкции языка, а не текст. Проверять по ним

package/kit/gates/commit-explains-itself/gate.yml

@@ -1,4 +1,5 @@
 intent: коммит несёт мини-отчёт — что сделано и в чём агент не уверен
+intent_en: the commit carries a mini-report — what was done and what the agent is unsure about
 
 trigger:
   always: true

package/kit/gates/complexity-limit/gate.yml

@@ -1,4 +1,5 @@
 intent: функция не вырастает до сложности, в которой её нельзя удержать в голове
+intent_en: a function does not grow past the complexity you can hold in your head
 
 trigger:
   always: true

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

@@ -1,4 +1,5 @@
 intent: код, который никто не вызывает, не остаётся в проекте
+intent_en: code nobody calls does not stay in the project
 
 # Только там, где есть готовый инструмент: переносимой проверки здесь быть не может, а
 # показывать запись тем, кому её нечем исполнить, — значит показывать работу, которую

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

@@ -1,4 +1,5 @@
 intent: версии зависимостей закреплены — сборка воспроизводима
+intent_en: dependency versions are pinned — the build is reproducible
 
 trigger:
   has_deps: true

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

@@ -1,4 +1,5 @@
 intent: один и тот же код не размножается по проекту копиями
+intent_en: the same code does not multiply into copies across the project
 
 trigger:
   files_gt: 20

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

@@ -2,6 +2,7 @@
 # Читается программой; всё, что нельзя выполнить, живёт в README.md рядом.
 
 intent: файлы, на которые ссылается точка входа, существуют на диске
+intent_en: files the entry point links to actually exist on disk
 
 # Когда запись показывается человеку. Отсутствие триггера сделало бы её шумом
 # для тех, кого она не касается.

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

@@ -1,4 +1,5 @@
 intent: файл не вырастает до размера, в котором агент теряется
+intent_en: a file does not grow to a size where the agent gets lost
 
 trigger:
   always: true

package/kit/gates/gate-has-samples/gate.yml

@@ -1,4 +1,5 @@
 intent: у каждого объявленного гейта есть красный и зелёный образец
+intent_en: every declared gate has a red and a green sample
 
 trigger:
   has_gates: true

package/kit/gates/gates-are-runnable/gate.yml

@@ -1,4 +1,5 @@
 intent: каждый гейт, объявленный в манифесте, существует и запускается
+intent_en: every gate declared in the manifest exists and runs
 
 trigger:
   has_gates: true

package/kit/gates/gates-run-in-ci/gate.yml

@@ -1,4 +1,5 @@
 intent: каждый объявленный гейт запускается конвейером, а не только руками
+intent_en: every declared gate runs in the pipeline, not only by hand
 
 # Условия складываются: запись касается только тех, у кого есть и гейты, и конвейер.
 # Нет конвейера — сначала он, а не эта проверка.

package/kit/gates/lesson-has-outcome/gate.yml

@@ -1,4 +1,5 @@
 intent: каждая записанная шишка кончается решением, а не рассказом
+intent_en: every recorded bruise ends in a decision, not a story
 
 # Проверять нечего там, где журнала нет: запись сама скажет об этом и промолчит.
 trigger: