agent-quality-kit 0.5.0 → 0.7.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.7.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
@@ -217,7 +217,7 @@ layer AQK adds.
 [![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.5.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.7.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -236,13 +236,46 @@ 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`.
 
+### Introducing a rule into a live project
+
+Three ways, and each has a price. A big clean-up is put off forever because it is big. The
+ratchet turns existing violations into debt and blocks new ones — right once the rule is agreed.
+And while it is still being argued about, an advisory gate shows findings without failing the run:
+
+```yaml
+advisory:
+  - complexity-limit
+```
+
+Declared in the manifest, not passed as a flag. A flag that says "fail nothing" downgrades every
+check at once, is invisible in the diff, and is never named in the summary — that is
+`continue-on-error`, which this tool marks red elsewhere. The list is printed on **every** run:
+an advisory gate everyone forgot about is a switched-off check.
+
 ## When a bug slips past the guards
 
 ```bash
@@ -289,6 +322,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,40 @@ 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 оказалась законным приёмом.
+
+### Как ввести правило в живой проект
+
+Три способа, и у каждого своя цена. Большая чистка откладывается навсегда, потому что она
+большая. Храповик превращает старые нарушения в долг и блокирует новые — верно, когда правило
+уже принято. А пока о правиле спорят, совещательный гейт показывает находки, не роняя прогон:
+
+```yaml
+advisory:
+  - complexity-limit
+```
+
+Объявлением в манифесте, а не флагом. Флаг «не роняй ничего» понижает все проверки разом, не
+виден в дифе и не назван в итоге — это тот самый `continue-on-error`, который мы сами красим.
+Список печатается **каждый** прогон: совещательный гейт, о котором забыли, — это выключенная
+проверка.
+
 ## Методички одним файлом
 
 ```bash

package/kit/docs/ai/agent-harness-playbook.md

@@ -193,7 +193,7 @@
 |---|---|---|---|
 | `block-dangerous-commands.sh` | PreToolUse (Bash **и** PowerShell) | exit 2 + причина в stderr на необратимое: force-push, reset --hard, `DROP DATABASE`, `TRUNCATE`, `docker volume rm`, `rm -rf /` | fail-safe: не распарсил JSON → грепай сырой ввод. Штатный сброс дев-БД (`compose down -v`) — НЕ блокировать |
 | `auto-format.sh` | PostToolUse (Write\|Edit) | `ruff format` + `ruff check --fix` на изменённый `.py` | агент физически не оставляет неотформатированный код, контекст не тратится |
-| `stop-gate.sh` | Stop | красный `ruff` по прод-путям → exit 2 + хвост ошибок → агент чинит, а не «сдаёт» | обязателен гард `stop_hook_active` (иначе вечный цикл); проверять только СВОЙ домен, не параллельную работу человека |
+| `stop-gate.sh` | Stop | красный `ruff` по прод-путям → exit 2 + хвост ошибок → агент чинит, а не «сдаёт» | обязателен гард `stop_hook_active`; проверять только СВОЙ домен, не параллельную работу человека. Поле настоящее — Stop и SubagentStop получают его на вход; но вечного цикла не будет и без гарда: «Claude Code overrides the hook and ends the turn after 8 consecutive blocks» (code.claude.com/docs/en/hooks, раздел Stop input, сверено 2026-09-07). Цена ошибки — восемь ходов, а не вечность |
 
 - [ ] ⚠️ **Грабля №1 (Windows): `jq` нет в Git Bash.** Хук с `command -v jq || exit 0` молча
       превращается в no-op — защита «есть», но не работает. Парсить JSON через

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

@@ -149,6 +149,54 @@ 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. Писать своё здесь незачем.
+
+| Инструмент | Что проверяет | Состояние — дата замера в самой ячейке |
+|---|---|---|
+| [`agnix`](https://github.com/agent-sh/agnix) | 455 правил: структура `CLAUDE.md`/`AGENTS.md`/`SKILL.md`, синтаксис конфигов MCP и хуков, соглашения об именах, **мёртвые ссылки на файлы**. Есть автопочинка и LSP | 404 ⭐, Rust, активен на 2026-09-06. `npm i -g agnix`, `brew`, `pip`, `cargo` |
+| [`agents-lint`](https://github.com/giacomo/agents-lint) | мёртвые npm-скрипты, упомянутые в `AGENTS.md`, устаревшие рамки, деревья каталогов в контексте | 13 ⭐, TypeScript, последний коммит март 2026 — снято 2026-09-06 |
+| [`claudelint`](https://github.com/pdugan20/claudelint) | 116 правил: схема `.claude/settings.json`, синтаксис правил доступа, имена переменных окружения, ссылки на несуществующие файлы, разбор навыков, плагинов, MCP и LSP. Ловит `"allow": ["*"]` | TypeScript, MIT, коммит 2026-09-08. `npx claude-code-lint`. **Код возврата 0 даже на находке**, если её строгость — `warn`: блокирует только `--strict`. Проверено прогоном 0.8.0 |
+| [`slopcheck`](https://github.com/mattschaller/slopcheck) — **не путать с `0xToxSec/slopcheck`, это разные проекты** | имена npm-пакетов из команд установки в `.md`, `.mdc`, `.yml`, `.yaml`, `.json`, `.cursorrules` сверяет с реестром: пакет, которого не существует, — приманка для захвата имени | MIT, ноль зависимостей, TypeScript, пуш 2026-09-06. `npx slopcheck .`, код возврата 1 на находке — проверено прогоном 0.2.0 от 2026-09-08. Без сети выходит с нулём: «не проверено» у него неотличимо от «чисто» |
+
+```bash
+npm install -g agnix && agnix --strict .
+```
+
+**Чего они НЕ делают — и почему у AQK остаётся своя половина.** Все они проверяют документ:
+формат, существование путей, наличие скриптов. Ни один не спрашивает, **подкреплено ли обещание
+командой с кодом возврата**. «Мы никогда не коммитим секреты» — грамматически безупречная
+строка, на которую ни один из них ничего не скажет. Разделение простое: обвес агента проверяет
+`agnix`, права и схему настроек — `claudelint`, исполнимость обещаний — `promise-has-gate`.
+
+**Одну дыру в обвесе пришлось закрыть самим.** Имя события хука: ошибка в нём не показывается,
+хук просто не вызывается. У `claudelint` правило `hooks-invalid-event` есть в исходниках, но
+живой прогон версии 0.8.0 на файле с `"PoToolUse"` даёт «No problems found». Замер по 48 чужим
+настройкам нашёл шесть таких хуков в четырёх репозиториях — среди них `typecheck && test` перед
+коммитом, не запускавшийся ни разу. Это запись `hook-actually-fires`.
+
 ## А если проект не на Python?
 
 Ничего не меняется. Запись каталога держит **одно намерение и несколько исполнителей**, и
@@ -161,6 +209,23 @@ ruff check --select TRY400 --statistics .     # сколько находок У
 **Одна строка в существующей записи — самый дешёвый и самый ценный вклад.** Намерение уже
 доказано отказом, образцы уже лежат, проверять нечего кроме самой команды.
 
+## Приёмы агента, названные практиками: чем закрыт каждый
+
+Список взят из разбора 1154 обсуждений с r/programming, r/learnprogramming, r/ExperiencedDevs
+и Hacker News (Baltes, Cheong, Treude, «An Endless Stream of AI Slop», arxiv 2603.27249,
+январь–сентябрь 2025). Это не подборка мнений, а размеченный корпус.
+
+| Приём | Чем закрыт |
+|---|---|
+| «test subversion»: правка теста, чтобы прошёл сломанный код | [`checkwash`](https://github.com/taipei49314/checkwash) — запись `test-not-adjusted` делегирует ему целиком |
+| «deleting methods instead of fixing them» | он же, детектор `TEST_DISABLED` |
+| «casting to `any` to silence type errors» | `@typescript-eslint/no-explicit-any`. Своей записи нет намеренно: замер по `zod` — 769 вхождений на 501 файл, первый прогон даёт стену |
+| «using `setTimeout` as a band-aid fix» | ничем. Замера нет, риск ложных высок: `setTimeout` законен сплошь и рядом |
+| «hallucinating external services, then mocking» | ничем. Отличить выдуманную службу от настоящей статически нечем |
+| выдуманная зависимость (slopsquatting) | [`slopcheck`](https://github.com/mattschaller/slopcheck) — тот, что лежит в npm под этим именем; на нём стоит запись `no-phantom-package`. **Проектов с именем `slopcheck` два**: [`0xToxSec/slopcheck`](https://github.com/0xToxSec/slopcheck) тоже MIT, но последний пуш апрель 2026 и в npm его нет. Проверено 2026-09-08 |
+| подавление проверки без адреса | наш `gate-not-weakened` плюс `eslint-plugin-eslint-comments`, `flake8-noqa` |
+| шаг конвейера, который не может провалиться | наш `ci-actually-fails`; у `checkwash` есть смежный `CI_WORKFLOW_TOUCHED` |
+
 ## Если готового нет
 
 Тогда свой гейт — и в его `README.md` пишется, **что именно проверено**: какой инструмент

package/kit/gates/README.md

@@ -70,6 +70,64 @@
 Плюс шестое, без которого запись не принимается: **доказательство** — реальный отказ, который
 она поймала. «Это хорошая практика» не принимается.
 
+## Находка обязана кончаться действием
+
+Проверка, покрасневшая молча, ничем не лучше молчащей. Проверка, сказавшая «плохо» и не
+сказавшая «делай так», — немногим лучше: человек, открывший тридцать находок, хочет команду,
+а не оценку.
+
+Поэтому последняя строка вывода — совет, и он начинается с метки:
+
+```
+  почини: замени на вызов системы логов — тогда запись попадёт в общий журнал
+```
+
+Приёмка требует эту строку на красном образце, а `doctor --run` печатает её **всегда**: находки
+обрезаются до трёх, совет не обрезается никогда. До этой правки строка существовала для приёмки
+и не существовала для человека — обрезка съедала ровно её.
+
+Требование действует для записей с переносимым рецептом. Запись, целиком делегирующая готовому
+инструменту, печатает вывод этого инструмента, и требовать от чужого вывода нашу строку значит
+требовать невозможного.
+
+## Зрелость записи не пишут руками
+
+Седьмого поля нет: зрелость **считается** из доказательства. Ссылается `proof` на журнал шишек —
+запись зрелая; не ссылается — условная, и это видно в приёмке каталога. Написать себе
+`lifecycle: stable` нельзя, приёмка такую запись отклонит.
+
+Это не придирка к форме. У всех трёх соседей, чей каталог мы разбирали, поле зрелости есть, и
+у всех троих его заполняет автор: `lifecycle` у зондов Scorecard, `future`/`obsolete` у
+критериев значка OpenSSF. Значение, написанное автором, означает доверие к автору. Каталог, где
+зрелость объявляют, к сотне записей превращается в список, в котором нельзя выбрать.
+
+Объявляется ровно одно состояние — **`deprecated`**, потому что «эту запись больше не ставят»
+из её файлов не выводится никак. Вместе с ним обязателен `superseded_by` с именем существующей
+записи, и `aqk add` тогда отказывает в установке, назвав преемника:
+
+```yaml
+lifecycle: deprecated
+superseded_by: no-print-in-prod
+```
+
+## Программа, без которой запись не работает
+
+**`requires:`** называет её явно. Нужно там, где переносимый рецепт — обёртка вокруг готового
+инструмента: первое слово команды тогда `bash`, который есть всегда, и по нему не видно, чего
+не хватает. Без этого поля гейт ставился бы и вставал при первом же запуске с «not found» —
+отсутствие сигнала неотличимо от успеха.
+
+```yaml
+recipes:
+  any: bash {gate}/check.sh {dir}
+requires: checkwash
+```
+
+`add` отказывает с названной причиной и говорит, что поставить. Приёмка и мутационная проверка
+пропускают запись со словами «НЕ ПРОВЕРЕНА здесь — нужен «…»». Строгий режим
+(`AQK_GATES_STRICT=1`, поднят в нашем конвейере) делает такой пропуск ошибкой: на машине,
+которая инструменты сама и ставит, «нечем проверить» обязано быть красным.
+
 ## Запись без переносимого рецепта
 
 Иногда переносимой проверки быть не может: чтобы понять, вызывают ли функцию, нужен граф
@@ -173,6 +231,8 @@ samples_for: python
 | `has_deps: true` | есть файл зависимостей |
 | `has_tests: true` | есть каталог тестов или файлы вида `*_test.*` |
 | `has_env: true` | есть файл окружения |
+| `has_agent_entry: true` | агента здесь используют: есть `CLAUDE.md`, `AGENTS.md`, каталог `.claude`, `.cursor/rules` или инструкции copilot |
+| `has_agent_config: true` | есть настройки самого агента: `.claude/settings.json`, `.claude/settings.local.json`, `.claude/hooks.json`, `.claude/hooks/hooks.json`. Второй файл лежит в `.gitignore` — признак сработает у человека и не сработает в конвейере |
 | `has_ui: true` | есть стили или однофайловые компоненты (`.css`, `.scss`, `.vue`, `.svelte`, `.astro`) |
 
 Любое из `has_*` принимает и `false` — «показывать тем, у кого этого нет». Условие, которого

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

@@ -0,0 +1,54 @@
+# Проверка в конвейере может провалиться
+
+**Намерение.** Шаг выполнен, круг зелёный, проверка не сработала. `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`
+для них — законная настройка, каковой она и является: незаконной её делает то, ЧТО под ней
+стоит, а это знает только проект.
+
+**Исход переспрашивают — маска законна.** `continue-on-error` иногда стоит не ради прощения
+провала, а чтобы дать выполниться шагам ПОСЛЕ проверки; вердикт выносится отдельным шагом
+`if: steps.<id>.outcome == 'failure'` → `exit 1`. Так устроен `pre-commit.yml` в `fastapi`:
+проверка идёт под маской, потом чинит файлы и пушит их в ветку, и только в конце роняет
+сборку. Такой шаг больше не находка. Условие узкое: в файле должна быть И ссылка на исход,
+И падение — переспросить исход и ничего с ним не сделать значит простить провал длиннее на
+три строки, и это по-прежнему красное (образец `red/.github/workflows/soft.yml`).
+
+Замер 2026-09-07 по пяти чужим репозиториям: молчал на всех пяти. На `fastapi` — по
+случайности, слово-примета не совпало с именем шага «Run prek - pre-commit»; назови они его
+«Run lint», гейт покрасил бы законный уклад. Дефект найден разбором молчания, а не находки.
+
+**Чего НЕ ловит.**
+
+- **Проверку, которую не по чему опознать.** Задача `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,116 @@
+#!/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` на них стоит не ради прощения
+  # провала, а чтобы дали выполниться шагам после — а вердикт выносится отдельным шагом
+  # `if: steps.<id>.outcome == 'failure'` → `exit 1`. Найдено замером по fastapi
+  # (`.github/workflows/pre-commit.yml`): проверка идёт под маской, потом чинит файлы и пушит
+  # их в ветку, и только в конце роняет сборку. Гейт молчал там по случайности — слово-примета
+  # не совпало; назови они шаг «lint», он покрасил бы законный уклад.
+  #
+  # Засчитывается только когда в файле есть И ссылка на исход, И падение: переспросить исход и
+  # ничего с ним не сделать — то же самое прощение, только длиннее.
+  REDEEMED=""
+  if tr -d '\r' < "$F" | grep -qE '^[[:space:]]*(-[[:space:]]+)?run[[:space:]]*:.*(exit[[:space:]]+1|^[[:space:]]*false[[:space:]]*$)'; then
+    REDEEMED=$(tr -d '\r' < "$F" | sed -n "s/.*steps\.\([A-Za-z0-9_-]*\)\.\(outcome\|conclusion\|result\).*/\1/p" | sort -u)
+  fi
+  # Разбор ПО ШАГАМ, а не по строкам. Построчно проверка врала в обе стороны: законный
+  # `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" -v redeemed="$REDEEMED" '
+    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 isRedeemed(id,   j, nr) {
+      if (id == "") return 0
+      nr = split(redeemed, R, "\n")
+      for (j = 1; j <= nr; j++) if (R[j] != "" && R[j] == id) return 1
+      return 0
+    }
+    function flush(   ) {
+      if (blockStart && blockCheck && blockMask && !isRedeemed(blockId))
+        printf "%s:%d: проверка не может провалиться — шаг под %s\n", file, blockCheckLine, blockMaskText
+      blockStart = 0; blockCheck = 0; blockMask = 0; blockId = ""
+    }
+    {
+      # Гашение прямо в команде красится только для ЗАКРЫТОГО списка запускалок: «|| 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) }
+      if (!isComment($0) && $0 ~ /^[[:space:]]*(-[[:space:]]+)?id[[:space:]]*:/) {
+        blockId = $0; sub(/^[^:]*:[[:space:]]*/, "", blockId); gsub(/[[:space:]"'"'"']/, "", blockId)
+      }
+    }
+    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,30 @@
+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
+
+      # Законный уклад: шаг помечен continue-on-error не для того, чтобы простить провал, а
+      # чтобы дать выполниться шагам после него; вердикт выносится ниже, по его исходу.
+      # Найдено замером по fastapi (.github/workflows/pre-commit.yml): проверка прогоняется
+      # под continue-on-error, потом чинит файлы и пушит их в ветку, а в конце падает, если
+      # проверка была красной. Гейт, красящий такое, требует убрать то, без чего уклад не
+      # работает, — и его выключат целиком.
+      - name: линтер
+        id: lint
+        run: ruff check .
+        continue-on-error: true
+      - name: применить починки и запушить
+        run: bash scripts/push-fixes.sh
+      - name: провалить сборку, если линтер был красным
+        if: steps.lint.outcome == 'failure'
+        run: exit 1

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/ci-actually-fails/red/.github/workflows/soft.yml

@@ -0,0 +1,15 @@
+# Исход проверки переспрашивают — и ничего с ним не делают. Ровно то же прощение, что и
+# голый continue-on-error, только длиннее на три строки и убедительнее на вид.
+name: soft
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: линтер
+        id: lint
+        run: ruff check .
+        continue-on-error: true
+      - name: сказать вслух
+        if: steps.lint.outcome == 'failure'
+        run: echo "линтер был красным"

package/kit/gates/color-from-token/check.sh

@@ -5,7 +5,19 @@
 # который в тёмной теме остаётся светлым пятном, — и это видно не автору, а пользователю,
 # который переключил тему. Дефект тихий: в теме автора всё выглядит правильно.
 DIR="${1:-.}"
-. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+# Существование файла проверяется ДО `.`, а не запасной веткой после. Прежняя строка
+# `. файл 2>/dev/null || запасной_вариант` выглядела страховкой и ею не была: под `sh` (dash)
+# неудачный `.` завершает скрипт немедленно, и ветка после `||` не выполняется никогда; под
+# `bash`, которым гейты и запускаются из манифеста, она выполняется, но подставляет только
+# ПЕРЕМЕННУЮ — функции обхода остаются неопределёнными, конвейер печатает пустоту, и проверка
+# выходит с НУЛЁМ. Замерено 2026-09-08 на файле с настоящим нарушением: гейт сказал «чисто».
+SKIP_LIB="$(dirname "$0")/../_skip.sh"
+if [ ! -f "$SKIP_LIB" ]; then
+  echo "рядом с проверкой нет _skip.sh — обход не собран, проверка не состоялась"
+  echo "  почини: скопируй гейт вместе с файлом kit/gates/_skip.sh, он общий на весь каталог"
+  exit 2
+fi
+. "$SKIP_LIB"
 
 # Расширения, где живёт ТЕМИЗИРУЕМЫЙ интерфейс. Своё, а не общий CODE_EXT: там нет ни css, ни
 # vue — они не код в смысле «отладочная печать», но именно в них живёт цвет.

package/kit/gates/commit-explains-itself/README.md

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