agent-quality-kit 0.2.2

package/kit/gates/README.md

@@ -0,0 +1,231 @@
+# Каталог обещаний — норма записи
+
+Каталог хранит обещания проекта, превращённые в команды. Здесь — правило, по которому запись
+принимается или отклоняется. Проверяет это машина: `bash tool/selfcheck/gates.sh`.
+
+## Сперва ищи готовое правило, потом пиши своё
+
+**Прежде чем заводить запись — проверь, нет ли такой проверки в готовом инструменте.** У `ruff`
+964 правила в 61 группе, у `eslint` сотни, у `semgrep` — реестр чужих. Мы знаем от силы два
+процента.
+
+**Где искать и какими командами — `kit/docs/ready-made-rules.md`.** Там карта всех 61 группы,
+список инструментов по языкам и команда, которая считает находки по группе в вашем репозитории.
+
+Цена этого правила измерена. Разбор синтаксического дерева по всему проекту искал места, где
+ошибку записывают в лог без трейса: час работы, 80 находок. Существует правило `TRY400`, которое
+находит их одной строкой в конфиге и точнее.
+
+**Готовое лучше своего не потому, что чужое, а потому что** его поддерживают без нас, оно
+подробнее (три правила там, где у нас одно) и его знают в лицо в чужих проектах.
+
+Поэтому в записи **рецепт под язык берёт готовое правило**, а своя переносимая проверка остаётся
+запасной — для стеков, где готового нет.
+
+### Три ступени выбора — как это работает на любом языке
+
+Запись каталога описывает **одно намерение и несколько исполнителей**. Программа выбирает так:
+
+1. **готовый инструмент под язык проекта** — если он установлен. Точнее и подробнее;
+2. **переносимая проверка** `any` — наша, без сторонних программ, работает где угодно;
+3. **ничего** — тогда запись честно скрывается, а не притворяется работающей.
+
+Поэтому проект на Rust, Go или C++ не остаётся без сторожа: пока рецепта `rust: cargo clippy …`
+в записи нет, работает переносимая проверка. Появится рецепт — она уступит место готовому.
+
+**Принести рецепт под новый язык — самый дешёвый и самый ценный вклад:** намерение уже доказано,
+образцы уже лежат, нужна одна строка.
+
+**Ограничение формата:** рецепты выбираются **по языку проекта**, поэтому инструмент, к языку не
+привязанный, рецептом не выражается. Пример — проверка ссылок в документации: `lychee` сильнее
+нашей переносимой проверки, но ключа под него в записи нет. Такие инструменты называются в README
+записи словами, и это честнее, чем прятать их отсутствие.
+
+### И обратная половина, без которой правило вредно
+
+**Свой гейт законен, когда он про НАШЕ решение.** Паритет очередей, свежесть карты проекта,
+неизменяемость применённой миграции, реестр долга — этого в библиотеках нет и быть не может:
+они не знают, как устроен ваш проект.
+
+Проверять надо оба направления. Пример из практики: неразрывный пробел не ловит **ни одно** из
+964 правил `ruff` — там свой гейт единственный способ. А запрет отладочной печати дублировал
+готовое `T20` годами.
+
+**В README каждой записи обязан быть раздел «готовый аналог»**: есть он или нет, и если нет — что
+именно проверено. «Не искал» и «нет» — разные утверждения.
+
+## Пять полей записи
+
+Галочка «внедрено» отвечает не на тот вопрос: она означает «пакет стоит», а нужно «сторож
+работает». Поэтому запись — не галочка, а пять полей:
+
+| Поле | Что в нём | Файл |
+|---|---|---|
+| **намерение** | какой класс дефекта ловит, одной фразой | `intent` в `gate.yml` |
+| **арбитр** | команда, возвращающая 0 или не 0, под каждый стек | `recipes` в `gate.yml` |
+| **триггер** | условие, при котором запись касается репозитория | `trigger` в `gate.yml` |
+| **красный образец** | код, на котором гейт обязан сработать | каталог `red/` |
+| **зелёный образец** | правильный код, на котором обязан молчать | каталог `green/` |
+
+Плюс шестое, без которого запись не принимается: **доказательство** — реальный отказ, который
+она поймала. «Это хорошая практика» не принимается.
+
+## Запись без переносимого рецепта
+
+Иногда переносимой проверки быть не может: чтобы понять, вызывают ли функцию, нужен граф
+вызовов, а не поиск по тексту. Такая запись законна — но обязана сказать, **каким рецептом
+написаны её образцы**:
+
+```yaml
+samples_for: python
+```
+
+Без этого поля проверка отклонит запись: угадывать нельзя. В системе может стоять `npx`, и
+питоновские образцы поедут проверяться фронтовым инструментом — так и вышло при первой попытке.
+
+Где нужного инструмента нет, проверка каталога говорит «НЕ ПРОВЕРЕНА здесь — нужен такой-то» и
+считает это **отдельно** от принятых и от отклонённых. «Условная запись» и «нечем проверить
+здесь» — разные состояния.
+
+Конвейер такие инструменты ставит: «не проверено» не должно становиться нормой именно на той
+машине, где проверка обязана быть строгой.
+
+Триггер у такой записи — по языкам, а не `always`: показывать её тому, кому её нечем исполнить,
+значит показывать работу, которую он сделать не сможет.
+
+## Четыре способа, которыми гейт врёт
+
+Все примеры настоящие, из `audit_project`:
+
+| Как врёт | Живой пример |
+|---|---|
+| **Зомби** — стоит, не вызывается | четыре пакета в зависимостях с нулём упоминаний в коде |
+| **Декоративный** — работает, ничего не доказывает | фаззер API: только `GET`, 5 примеров, единственная проверка «не 500», да ещё необязательный |
+| **Врущий** — краснеет на правильном коде | правило ругалось на то написание, которое само предписывает |
+| **Устаревшая запись** — файл утверждает то, чего нет | раздел числил защиту работающей через три недели после её отключения |
+
+Пятый способ: **гейт, который не запускается.** Проверка жила только в конвейере, а правка её
+конфига конвейер вообще не создавала — пути не были в белом списке.
+
+Шестой, из разбора другого проекта: **гейт, скопировавший чужое решение вместо ссылки на него.**
+Список того, что считается тестом, был записан в `pytest.ini` — и ещё раз, вручную, в пяти разных
+проверках. Копии разъезжались годами и тихо. Проверка одним вопросом: «что будет с этим гейтом,
+если завтра поправят источник?» Правильный ответ — «результат изменится сам», а не «нужно
+поправить ещё и здесь».
+
+Зелёный образец закрывает третий способ, и он важнее красного: что гейт ловит брак, проверяют
+при установке; что он молчит на исправном коде — не проверяют почти никогда.
+
+## Красный образец проверяется по выводу, а не по коду возврата
+
+Отсутствующий скрипт тоже даёт ненулевой код: «гейт покраснел» неотличимо от «гейта нет».
+Поэтому фильтр различает три случая — арбитр не запускается, арбитр промолчал на красном,
+арбитр покраснел на красном молча.
+
+Дефект не ждут — его **изготавливают нарочно**. И если образец не краснеет, первым делом
+доказывают, что он вообще нарушает правило: трижды подряд «дефект гейта» оказывался неверным
+образцом.
+
+## Сканирующий гейт пропускает красные образцы
+
+Красный образец — намеренно сломанный код, лежащий в репозитории. Проверка, которая ходит по
+всему проекту, обязана его исключать, иначе будет вечно краснеть на том, что сама же и положила,
+и её начнут обходить вместе со всеми остальными.
+
+Исключение снимается, когда проверяют сам образец: тогда каталог `red` и есть цель проверки.
+
+## Сканирующий гейт не проверяет чужое и служебное
+
+Кроме красных образцов исключаются: каталог, разложенный самим комплектом; история версий;
+всё, что принесли пакетный менеджер и сборка. Гейт, краснеющий на том, что положил не человек,
+выключат вместе со всеми остальными.
+
+Проверка на отладочную печать вдобавок не читает прозу: упоминание `print(` в методичке — это
+текст про печать, а не печать.
+
+## Какие условия программа умеет считать
+
+Все условия внутри `trigger` складываются: запись показывается, когда выполнены **все**.
+
+| Условие | Что значит |
+|---|---|
+| `always: true` | касается любого репозитория |
+| `langs: python, go` | есть файлы хотя бы одного из этих языков |
+| `files_gt: 200` / `files_lt: 50` | размер репозитория |
+| `has_gates: true` | в манифесте объявлен хотя бы один гейт |
+| `has_ci: true` | есть конфиг конвейера |
+| `has_db: true` | есть миграции или файлы `.sql` |
+| `has_docker: true` | есть Dockerfile или compose |
+| `has_deps: true` | есть файл зависимостей |
+| `has_tests: true` | есть каталог тестов или файлы вида `*_test.*` |
+| `has_env: true` | есть файл окружения |
+
+Любое из `has_*` принимает и `false` — «показывать тем, у кого этого нет». Условие, которого
+программа не знает, отклоняется явно, а не пропускается молча.
+
+Признаки берутся **осмотром файлов, а не анкетой**. Ответы человека — это мнение; файлы — факт.
+
+## Два разных списка исключений
+
+**Общий** (`_skip.sh`) — чужое и служебное: окружение, зависимости, сборка, история версий.
+Один на все проверки: разъехавшись, он однажды окажется полным в одной и дырявым в другой. Там же
+живёт единый список расширений кода (`only_code`) и фильтр комментариев (`drop_comments`).
+Не «для порядка»: пока список расширений был переписан в каждой проверке заново, четыре из них
+разошлись, и `.mjs` не оказалось ни в одной — предел размера файла молчал на программе самого
+комплекта.
+
+**Свой у каждой проверки** — места, где эта конкретная конструкция законна. Печать в
+вспомогательном скрипте — способ говорить с человеком, а не забытая отладка; секрет в том же
+скрипте — такой же секрет. Общим этот список быть не может.
+
+Мера обоих одна: **гейт, который на 86% состоит из ложных сработок, выключают целиком.**
+Цифра не выдумана — столько дал первый прогон по настоящему проекту.
+
+## Триггер, записанный словами, — это не триггер
+
+«Внедрить при условии X» не сработает: никто не сравнивает список с реальностью. Условие обязано
+быть **запросом к репозиторию**, который умеет вычислить программа: «есть файлы `*.py` и нет
+проверки печати» — а не «когда появится питон».
+
+Живой пример провала: модели одной технологии в проекте были, линтера под неё не было, запись
+лежала с формулировкой «когда появятся модели». Условие наступило давно, никто не заметил.
+
+## Область гейта решается замером, а не планом
+
+План исключал один каталог из проверки; замер показал, что там лежит самая сложная функция.
+Гейт написан в тот же день по факту, а не по замыслу.
+
+## Инструкция по починке в тексте ошибки
+
+Гейт пишет не «нарушение правила X», а **что именно сделать** и куда посмотреть.
+
+> **ПОЧЕМУ.** Текст ошибки попадает прямо в контекст агента. С инструкцией он чинит сам; без неё
+> — гадает, тратит контекст и часто чинит не то.
+
+## Храповик для долга
+
+Если правило вводится в проект, где старый код ему не соответствует, — заведи файл со списком
+текущих нарушений. Гейт разрешает список **укорачивать** и запрещает **удлинять**.
+
+> **ПОЧЕМУ не «большая чистка» и не advisory.** Чистка откладывается навсегда, потому что она
+> большая. Advisory не блокирует ничего, его листают, и правило не действует. Храповик даёт
+> действующее правило со дня установки, не требуя трогать старый код.
+>
+> **Проверка, что это храповик, а не советчик:** «может ли новый код добавить нарушение и пройти?»
+> Может — значит, гейта нет.
+
+**Чего храповик не ловит.** Он держит **множество** нарушений, а не их величину: нарушение, уже
+лежащее в реестре, может усугубляться незаметно. Файл на 1357 строк при пределе 500 записан
+долгом — и вырастет до трёх тысяч, не покраснев. Поэтому число в сообщении гейта ставят в позицию
+номера строки (`файл:1357: длиннее предела`): ключ реестра эту часть отбрасывает, и запись не
+дёргается от каждой правки. Цена решения — рост в реестре не виден. Величину долга держат глазами
+при разборе реестра, а не храповиком.
+
+## Срок годности у режима предупреждения
+
+Если гейт временно не блокирует — рядом стоит **дата**, после которой он либо блокирует, либо
+удаляется. Не «когда-нибудь ужесточим».
+
+> **ПОЧЕМУ.** Условие, записанное словами («внедрим, когда появятся модели данных»), не
+> срабатывает: никто не сравнивает список с реальностью. Срабатывает только то, что умеет
+> вычислить машина, — дата или запрос к репозиторию.

package/kit/gates/_skip.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env sh
+# Что сканирующие проверки не читают. Общий список: разъехавшись по шести проверкам, он
+# однажды окажется полным в одной и дырявым в другой.
+#
+# ПОЧЕМУ ЭТО ВАЖНЕЕ, ЧЕМ КАЖЕТСЯ. На настоящем проекте из 36 тысяч файлов 1722 находки из 1831
+# пришли из чужого кода в окружении. Гейт, который на 94% состоит из чужих нарушений, читать
+# никто не будет — его выключат.
+
+SKIP_NAMES=".git .aqk node_modules .venv venv env __pycache__ .mypy_cache .pytest_cache
+.tox .ruff_cache site-packages dist build target out .next .nuxt .svelte-kit coverage
+htmlcov staticfiles vendor bower_components .gradle .idea .vscode
+playwright-report test-results storybook-static .turbo .cache .parcel-cache
+migrations"
+
+# Образцы гейтов — искусственный код по построению: красный сломан нарочно, зелёный бывает
+# вырожденным (двести одинаковых строк, чтобы показать предел размера). Сканировать их — значит
+# ловить то, что положил не человек. Исключение снимается, когда цель проверки — сам образец.
+#
+# ПОЧЕМУ ПО ПУТИ, А НЕ ПО ИМЕНИ. `--exclude-dir=red`/`-name red -prune` совпадают с ЛЮБОЙ папкой
+# red в проекте — а это имя не выдуманное: реальный секрет в пользовательской папке `red/`
+# (red-team тесты, что угодно) становился невидим для secrets-not-in-code во всех проектах,
+# куда ставили гейт. Фильтр ниже смотрит на путь целиком: только `gates/<имя>/red|green/`,
+# а не голое имя каталога.
+own_samples_filter() {
+  case "${1:-}" in
+    */red|*/red/|*/green|*/green/) cat ;;
+    *) grep -vE '/gates/[^/]+/(red|green)(/|$)' ;;
+  esac
+}
+
+# Расширения, где `print` и маркеры долга — конструкции языка, а не текст. Проверять по ним
+# файлы настроек, разметку и отчёты бессмысленно: там те же слова означают другое.
+# Модульные варианты перечислены наравне с обычными: без .mjs проверки молча не смотрели
+# в программу самого aqk, целиком написанную в этом расширении.
+CODE_EXT="py js jsx mjs cjs ts tsx mts cts vue go rb java cs php rs kt swift scala"
+
+include_code() {
+  for E in $CODE_EXT; do printf -- '--include=*.%s ' "$E"; done
+}
+
+# Сгенерированный файл не правят руками — предъявлять его размер или сложность человеку
+# бессмысленно и вредно: он выключит проверку целиком.
+# Опознаём по общепринятой шапке в первых пяти строках.
+is_generated() {
+  head -5 "$1" 2>/dev/null | grep -qiE '@generated|do not edit|autogenerated|auto-generated|generated by|сгенерирован'
+}
+
+# Для grep: --exclude-dir на каждое имя. Образцы гейтов сюда не входят — см. own_samples_filter:
+# у --exclude-dir нет способа смотреть на путь целиком, только на голое имя папки.
+skip_grep() {
+  for N in $SKIP_NAMES; do printf -- '--exclude-dir=%s ' "$N"; done
+}
+
+# Для find: -name X -prune -o …
+skip_find() {
+  for N in $SKIP_NAMES; do printf -- '-name %s -prune -o ' "$N"; done
+}
+
+# Отбрасывает находки, сделанные в строках-комментариях. Вход — вывод `grep -rn` в виде
+# «файл:строка:код». Комментарий не выполняется: находка в нём означает, что проверка читает
+# текст, а не код. Найдено прогоном по audit_project: семь находок из JSDoc и закомментированных
+# строк. Проверкам, которые ищут ИМЕННО в комментариях (маркеры долга), этот фильтр не нужен.
+drop_comments() { grep -vE '^[^:]*:[0-9]+:[[:space:]]*(//|\*|#|/\*|--)' ; }
+
+# Отбор файлов кода из потока путей. Один список на все проверки: раньше каждая несла свой,
+# переписанный заново, и они разошлись — четыре проверки, четыре разных набора, и `.mjs` не было
+# ни в одном. Программа самого комплекта целиком в `.mjs`: предел размера файла молчал на ней
+# при 1366 строках и пределе 500.
+#
+# Почему фильтром потока, а не выражением для find: набор `-name *.py` пришлось бы подставлять
+# без кавычек, и оболочка развернула бы звёздочку по файлам текущего каталога.
+#
+# `sh` в списке нет намеренно: печать в скрипте — его способ говорить с человеком, и запрет
+# отладочной печати покрасил бы каждый из них.
+only_code() { grep -E "\.($(printf '%s' "$CODE_EXT" | tr ' ' '|'))$"; }

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

@@ -0,0 +1,45 @@
+# Коммит несёт мини-отчёт
+
+**Намерение.** Дифф показывает, ЧТО изменилось. Он не показывает, понял ли автор — человек или
+агент — замысел, и в чём остаются сомнения. Тест проверяет реализацию против спеки; сам замысел
+он проверить не может.
+
+**Какой отказ это поймало.** Разбор чужого корпуса практик (журнал, 2026-09-04): 416 из 1069
+коммитов одного проекта за 90 дней оказались `fix` — не фичей, а стабилизацией уже выкаченного;
+диагноз владельца — «долг копится там, где человека убрали из центра принятия решений». Дешёвый
+артефакт-привычка снижает шанс, что решение принято и забыто без следа.
+
+**Почему машина, а не внимательность.** Написать отчёт «на будущее» — первое, что пропускают под
+давлением дедлайна. Гейт делает это ценой, а не пожеланием.
+
+**Готовый аналог.** Не искал: это не класс проверок, который держат готовые линтеры — они читают
+код, а не историю коммитов.
+
+**Чего НЕ ловит.** Не проверяет качество отчёта, только его наличие — «Сделано: починил» и «Не
+уверен: не знаю» формально пройдут. Не проверяет, что отчёт правдив. Это ограничение того же
+рода, что у любого чек-листа: полнота формы, а не смысл. Проверяет только последний коммит, а не
+всю историю — если гейт поставили посреди работы, старые коммиты не переписывает и не осуждает.
+
+**Когда не применяется.** Коммит, который трогает только журнал уроков (`lessons:` из манифеста,
+по умолчанию `incidents/`), отчёта в теле не требует: сама запись и есть отчёт, причём подробнее,
+и её сторожит `lesson-has-outcome`. Без этого исключения гейт краснел на каждой записи, сделанной
+командой `aqk note`, — то есть инструмент воевал сам с собой. Исключение узкое: достаточно одного
+файла за пределами журнала, чтобы требование вернулось.
+
+Второй случай — **мелкий клон**. `actions/checkout` по умолчанию берёт один коммит; у него не
+видно родителя, и git выдаёт всё дерево как изменённое. Состав коммита в таком клоне не
+определить, поэтому гейт пропускает себя, напечатав причину и способ починки. Если хочешь, чтобы
+он работал и в конвейере, дай тому два коммита истории:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 2
+```
+
+Гейт всё-таки местный: подсказка «допиши в тело коммита» выполнима до пуша, а не после.
+
+**Образцы.** `red/COMMIT_MSG` — обычное тело коммита без отчёта. `green/COMMIT_MSG` — то же самое
+плюс `Сделано:` и `Не уверен:`. Образцы — текстовые файлы, а не настоящий git: арбитр в реальном
+проекте читает `git log -1`, а вложенный `.git` внутри каталога комплекта создал бы embedded-
+репозиторий, который сам по себе стал бы проблемой версионирования.

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env sh
+# Коммит без мини-отчёта — риск того же класса, что несоответствие спеки коду: диффом можно
+# проверить реализацию, но не то, понял ли автор замысел. Отчёт — дешёвый артефакт, который
+# оставляет след для человека, читающего историю позже.
+DIR="${1:-.}"
+
+# Образцы (gates.sh) читают тело коммита из файла — реальный git log там взять неоткуда, а
+# вложенный .git внутри каталога комплекта сам по себе создал бы embedded-репозиторий.
+# В настоящем проекте COMMIT_MSG не бывает — читается последний реальный коммит.
+if [ -f "$DIR/COMMIT_MSG" ]; then
+  MSG=$(cat "$DIR/COMMIT_MSG")
+else
+  if ! (cd "$DIR" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1); then
+    echo "не git-репозиторий — проверять нечего"
+    exit 0
+  fi
+  # Мелкий клон: у коммита не видно родителя, и git выдаёт всё дерево как изменённое. Состав
+  # коммита в этом случае не определить, а требовать отчёт вслепую нельзя — конвейер краснел бы
+  # на каждой записи журнала. Пропускаем, назвав причину: гейт этот всё равно местный, чинят его
+  # до пуша, а не после. Причина печатается, а не прячется.
+  if [ "$(cd "$DIR" && git rev-parse --is-shallow-repository 2>/dev/null)" = "true" ] &&
+     ! (cd "$DIR" && git rev-parse -q --verify HEAD^ >/dev/null 2>&1); then
+    echo "мелкий клон: состав коммита не определить — проверка пропущена"
+    echo "  чтобы она работала в конвейере, дай ему два коммита истории:"
+    echo "  actions/checkout@v4 с fetch-depth: 2"
+    exit 0
+  fi
+
+  MSG=$(cd "$DIR" && git log -1 --format=%B 2>/dev/null)
+
+  # Коммит, который трогает только журнал, отчёта в теле не требует: сама запись и есть отчёт,
+  # причём подробнее — и её сторожит `lesson-has-outcome`. Иначе гейт воюет с командой `note`,
+  # которая коммитит запись сама. Путь журнала берётся из манифеста, а не угадывается.
+  # «#…» режется так же, как это делает сама программа при разборе манифеста
+  # (tool/lib/manifest.mjs): один файл обязан читаться по одним правилам.
+  LESSONS=$(sed -n 's/^lessons:[[:space:]]*//p' "$DIR/.aqk.yml" 2>/dev/null | head -1 |
+    sed 's/#.*$//' | tr -d '"'"'"' \r' | sed 's/[[:space:]]*$//')
+  [ -z "$LESSONS" ] && LESSONS="incidents"
+  case "$LESSONS" in http*) LESSONS="" ;; esac   # journal по адресу, а не путём — не применимо
+  if [ -n "$LESSONS" ]; then
+    FILES=$(cd "$DIR" && git show --pretty=format: --name-only HEAD 2>/dev/null | grep -v '^$')
+    if [ -n "$FILES" ]; then
+      OUTSIDE=$(printf '%s\n' "$FILES" | grep -v "^$LESSONS/" | grep -v "^$LESSONS\$")
+      if [ -z "$OUTSIDE" ]; then
+        echo "коммит трогает только журнал ($LESSONS) — запись и есть отчёт"
+        exit 0
+      fi
+    fi
+  fi
+fi
+[ -z "$MSG" ] && { echo "нет ни одного коммита — проверять нечего"; exit 0; }
+
+MISSING=""
+printf '%s\n' "$MSG" | grep -q "^Сделано:" || MISSING="$MISSING «Сделано:»"
+printf '%s\n' "$MSG" | grep -q "^Не уверен:" || MISSING="$MISSING «Не уверен:»"
+
+if [ -n "$MISSING" ]; then
+  echo "последний коммит без мини-отчёта — не хватает:$MISSING"
+  echo "  почини: допиши в тело коммита короткие разделы Сделано: / Не уверен: —"
+  echo "  не пересказ диффа, а что понял и в чём сомневаешься."
+  exit 1
+fi
+exit 0

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

@@ -0,0 +1,10 @@
+intent: коммит несёт мини-отчёт — что сделано и в чём агент не уверен
+
+trigger:
+  always: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md — «2026-09-04 — дифф проверяет реализацию, но не замысел»: 416 из 1069
+  коммитов чужого проекта за 90 дней оказались fix — стабилизацией уже выкаченного, не фичей

package/kit/gates/commit-explains-itself/green/COMMIT_MSG

@@ -0,0 +1,6 @@
+fix: починил парсер дат
+
+Разобрался, почему падало на високосных годах.
+
+Сделано: добавлена проверка длины месяца по году в parse_date().
+Не уверен: не проверил часовые пояса — не было времени на живой тест.

package/kit/gates/commit-explains-itself/red/COMMIT_MSG

@@ -0,0 +1,3 @@
+fix: починил парсер дат
+
+Разобрался, почему падало на високосных годах.

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

@@ -0,0 +1,37 @@
+# Функция не вырастает до сложности, в которой её нельзя удержать в голове
+
+**Намерение.** Ограничить сложность одной функции: сколько в ней ветвлений, инструкций и
+уровней вложенности.
+
+**Какой отказ это поймало.** Ревизия гейтов в `audit_project` показала: **сложность функций не
+мерил никто**. Нашлось 75 функций сложнее нормы, худшая — с **29 ветвлениями**, и лежала она в
+контуре проверки целостности файлов. Запись в журнале: `incidents/README.md`, 2026-08-27.
+
+**Почему машина, а не внимательность.** Сложность растёт по одному условию за раз. Ни одна
+правка не выглядит как «пора выделять функцию», а момент, когда стало поздно, проходит незаметно.
+Для агента это дороже, чем для человека: в таком месте он начинает переписывать вместо правки.
+
+**Готовый аналог есть, и он точнее.** В Python это `ruff --select C901,PLR0912,PLR0915`:
+цикломатическая сложность, число ветвлений, число инструкций. В TypeScript — правила `complexity`
+и `max-depth` в eslint. Рецепты под эти стеки берут готовое.
+
+**Переносимая проверка грубее, и это признаётся.** Она меряет только **глубину вложенности** —
+косвенный признак: функция может иметь двадцать ветвлений подряд без единого вложения и проверку
+пройти. Она для стеков, где готового инструмента нет, а не замена ему.
+
+**Разметке предел мягче.** В `.jsx`, `.tsx`, `.vue` и `.svelte` пять уровней вложенности — это
+обычная вёрстка, а не сложная логика. Там предел выше на три. Без этой поправки проверка краснела
+на нормальных компонентах живого проекта — шесть находок из девяти были именно такими.
+
+**Предел настраивается** переменной `AQK_MAX_DEPTH`, по умолчанию пять уровней.
+
+**Тяжёлая проверка.** На проекте в четыре тысячи файлов — около семи секунд. Место такой
+проверки — перед пушем и в конвейере, а не на каждый коммит: гейт, который заставляет ждать,
+начинают обходить.
+
+**Чего НЕ ловит.** Функцию с двадцатью ветвлениями подряд без вложенности — переносимая мера
+считает только глубину. Не различает функции внутри файла: меряется худшее место файла, а не
+каждая функция отдельно. Готовые правила умеют и то, и другое.
+
+**Образцы.** `red/` — восемь уровней вложенности. `green/` — тот же смысл, разбитый на две
+функции с ранним выходом.

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env sh
+# Грубая мера сложности: глубина вложенности. Это НЕ замена цикломатической сложности —
+# готовые правила считают ветвления и инструкции и делают это точнее. Здесь запасной вариант
+# для стеков, где готового инструмента нет.
+#
+# ЗАЧЕМ ВООБЩЕ. 29 ветвлений в одной функции — это код, который никто не держит в голове
+# целиком: ни человек, ни агент. Агент в таком месте начинает переписывать вместо правки.
+DIR="${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+MAX="${AQK_MAX_DEPTH:-5}"
+
+# shellcheck disable=SC2046
+find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null | only_code | own_samples_filter "$DIR" \
+  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | xargs -r awk -v MAX="$MAX" '
+        # Один обход на все файлы: процесс на каждый файл дал 19 секунд на 4000 файлов.
+        # Разметка вложена по природе: пять уровней тегов — это не сложная логика, а обычная
+        # вёрстка. Меряя её тем же пределом, гейт краснеет на нормальном коде и его выключают.
+        function limit() { return (wf ~ /\.(jsx|tsx|vue|svelte)$/) ? MAX + 3 : MAX }
+        function flush() { if (worst > limit()) print wf ":" wl ": вложенность " worst ", предел " limit() }
+        FNR == 1 { flush(); worst = 0; wl = 0; wf = FILENAME }
+        /^[[:space:]]*$/ { next }
+        {
+          # ширина отступа: табуляция считается за четыре пробела
+          line = $0; n = 0
+          while (match(line, /^[ \t]/)) {
+            n += (substr(line, 1, 1) == "\t") ? 4 : 1
+            line = substr(line, 2)
+          }
+          depth = int(n / 4)
+          if (depth > worst) { worst = depth; wl = FNR }
+        }
+        END { flush() }
+      ' > /tmp/.cplx.$$ 2>/dev/null
+
+if [ -s /tmp/.cplx.$$ ]; then
+  cat /tmp/.cplx.$$; rm -f /tmp/.cplx.$$
+  echo "  почини: выдели вложенные ветки в отдельные функции или выйди раньше."
+  echo "  такой код не держат в голове целиком — ни человек, ни агент; агент начинает"
+  echo "  переписывать его вместо правки."
+  exit 1
+fi
+rm -f /tmp/.cplx.$$
+exit 0

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

@@ -0,0 +1,13 @@
+intent: функция не вырастает до сложности, в которой её нельзя удержать в голове
+
+trigger:
+  always: true
+
+recipes:
+  # Переносимая мера грубая — глубина вложенности. Готовые правила считают ветвления и
+  # инструкции, это точнее; см. kit/docs/ready-made-rules.md
+  any: bash {gate}/check.sh {dir}
+  python: ruff check --select C901,PLR0912,PLR0915 {dir}
+  typescript: eslint --rule '{"complexity":["error",10],"max-depth":["error",4]}' {dir}
+
+proof: incidents/README.md — «2026-08-27 ревизия гейтов», п. 6: 75 функций сложнее нормы, худшая с 29 ветвлениями

package/kit/gates/complexity-limit/green/flat.py

@@ -0,0 +1,10 @@
+def handle(items):
+    if not items:
+        return 0
+    return sum(step(i) for i in items)
+
+
+def step(i):
+    if i < 0:
+        return 0
+    return i * 2

package/kit/gates/complexity-limit/red/deep.py

@@ -0,0 +1,9 @@
+def handle(items):
+    if cond0:
+        if cond1:
+            if cond2:
+                if cond3:
+                    if cond4:
+                        if cond5:
+                            if cond6:
+                                return 1

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

@@ -0,0 +1,30 @@
+# Код, который никто не вызывает, не остаётся в проекте
+
+**Намерение.** Функции, классы и переменные без единого обращения удаляются, а не копятся.
+
+**Какой отказ это поймало.** Ревизия гейтов в `audit_project`: **мёртвые функции бэкенда не искал
+никто.** Импорты закрывал линтер, фронт закрывал `knip`, бэкенд был пуст. Первый же прогон дал
+реестр на **148 записей**. Запись в журнале: `incidents/README.md`, 2026-08-27.
+
+**Почему это про агентов особенно.** Агенты **не удаляют код** — обучение награждает за
+написанное, не за удалённое. Отсюда мёртвые области, которые не ловит даже беглый взгляд: код
+выглядит рабочим, он просто никому не нужен.
+
+**Переносимой проверки здесь нет намеренно.** Чтобы понять, вызывают ли функцию, нужен граф
+вызовов, а не поиск по тексту. Проверка на `grep` давала бы ложные срабатывания на каждом
+динамическом вызове — и её выключили бы в первый день.
+
+Это тот случай, когда без готового инструмента не обойтись. Под каждый распространённый стек он
+есть: `vulture` для Python, `knip` для TypeScript и JavaScript, `staticcheck -checks U1000` для
+Go, `dead_code` в clippy для Rust.
+
+**Что это значит на практике.** На машине без нужного инструмента проверка каталога скажет
+«не проверена — нужен один из: vulture, npx, staticcheck, cargo» и не выдаст её за рабочую.
+
+**Чего НЕ ловит.** Динамические вызовы: то, что зовут по имени из строки, из настроек или через
+отражение. Поэтому у `vulture` есть уровень уверенности, а находки читают глазами прежде, чем
+удалять. Первый прогон такого инструмента — **лавина**, и разбирают её по частям, а не разом.
+
+**Готовый аналог — это и есть он сам.** Своей проверки здесь не будет.
+
+**Образцы.** `red/` — функция, которую никто не зовёт. `green/` — та же функция, вызванная.

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

@@ -0,0 +1,23 @@
+intent: код, который никто не вызывает, не остаётся в проекте
+
+# Только там, где есть готовый инструмент: переносимой проверки здесь быть не может, а
+# показывать запись тем, кому её нечем исполнить, — значит показывать работу, которую
+# человек сделать не сможет.
+trigger:
+  langs: python, typescript, javascript, go, rust
+
+# Переносимого рецепта здесь нет намеренно: чтобы понять, вызывают ли функцию, нужен граф
+# вызовов, а не поиск по тексту. Это тот случай, когда без готового инструмента не обойтись —
+# и он есть под каждый распространённый стек.
+recipes:
+  python: vulture --min-confidence 60 {dir}
+  typescript: npx --yes knip@6 --directory {dir}
+  javascript: npx --yes knip@6 --directory {dir}
+  go: staticcheck -checks U1000 {dir}/...
+  rust: cargo clippy --manifest-path {dir}/Cargo.toml -- -D dead_code
+
+# Каким рецептом написаны образцы: без переносимого рецепта проверка обязана знать это точно,
+# иначе питоновские образцы поедут проверяться фронтовым инструментом.
+samples_for: python
+
+proof: incidents/README.md — «2026-08-27 ревизия гейтов», п. 5: мёртвые функции бэкенда не искал никто, реестр на 148 записей