agent-quality-kit 0.4.2 → 0.5.0

package/README.md

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

package/README.ru.md

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

package/kit/gates/README.md

@@ -113,6 +113,20 @@ samples_for: python
 если завтра поправят источник?» Правильный ответ — «результат изменится сам», а не «нужно
 поправить ещё и здесь».
 
+Седьмой, с прогона по живому проекту: **гейт, тонущий в собственном шуме.** Родной инструмент
+не получал общий список исключений и читал `.aqk/` — каталог, который положил сам комплект. Из
+1846 находок 435 были не про код вовсе. Гейт остаётся правильным и становится нечитаемым, а
+нечитаемый выключают целиком. Мера здесь — доля находок не по делу, а не длина вывода.
+
+Восьмой, оттуда же: **родной и переносимый рецепты одной записи мерят разное.** Переносимый
+смотрел только в расширения кода, родной — во всё подряд. Один гейт означал разное на разных
+машинах, и какое именно — зависело от того, что стоит в системе.
+
+Девятый, найденный мутационной проверкой: **гейт держится за то, чего не заявляет.** Четыре
+записи переставали работать на windows-переносах строк — жадный захват в `sed` проглатывал
+`\r`. Красный образец зеленел, зелёный краснел. Пара образцов этого не видит: она доказывает
+одно срабатывание, а не класс. Ловит `tool/selfcheck/mutation.sh`.
+
 Зелёный образец закрывает третий способ, и он важнее красного: что гейт ловит брак, проверяют
 при установке; что он молчит на исправном коде — не проверяют почти никогда.
 
@@ -159,6 +173,7 @@ samples_for: python
 | `has_deps: true` | есть файл зависимостей |
 | `has_tests: true` | есть каталог тестов или файлы вида `*_test.*` |
 | `has_env: true` | есть файл окружения |
+| `has_ui: true` | есть стили или однофайловые компоненты (`.css`, `.scss`, `.vue`, `.svelte`, `.astro`) |
 
 Любое из `has_*` принимает и `false` — «показывать тем, у кого этого нет». Условие, которого
 программа не знает, отклоняется явно, а не пропускается молча.

package/kit/gates/_native.sh

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

package/kit/gates/_skip.sh

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

package/kit/gates/color-from-token/README.md

@@ -0,0 +1,52 @@
+# Цвет приходит из токена темы, а не литералом в компоненте
+
+**Намерение.** Литеральный цвет тема не перекрашивает. В проекте с несколькими темами экран,
+свёрстанный литералами, в тёмной теме остаётся светлым пятном — и видит это не автор, а
+пользователь, который тему переключил. Дефект тихий по построению: в теме автора всё правильно.
+
+**Какой отказ это поймало.** Живой проект на React с двенадцатью темами. Запрет на сырой цвет
+там оказался проверкой №8 из семнадцати в собственной оснастке — и завели его не из вкуса, а
+после экранов, не переживших переключение темы. Запись в журнале: `incidents/README.md`,
+2026-09-06, там же измерено соотношение, ради которого запись переносили в каталог: из тридцати
+с лишним запретов интерфейса машина ловила одиннадцать, остальные держались на глазах человека.
+
+**Файл-источник значений называет проект.** Где-то литерал обязан быть — иначе токену неоткуда
+взяться. По умолчанию проверка пропускает файлы, чьё имя содержит `tokens`, `theme`, `palette`,
+`colors`, `variables`, `design-system`. Своё имя проект называет сам, рядом с командой в
+манифесте — тем же приёмом, что каталоги с законной печатью в `no-print-in-prod`:
+
+```yaml
+color-from-token: "AQK_COLOR_SOURCE='tokens|brand' bash .aqk/gates/color-from-token/check.sh ."
+```
+
+**Готовый аналог есть, но он покрывает меньше, и поэтому его здесь нет.** У `stylelint` есть
+правило `color-no-hex`, и для файлов стилей оно точнее нашего поиска. Но оно видит только стили,
+а литерал в компоненте — `style={{ background: "#2563EB" }}`, `className="bg-[#2563EB]"` —
+остаётся вне его. Родной рецепт покрывал бы половину предмета, и запись означала бы разное в
+зависимости от того, что стоит в системе. Урок этого же дня: родной и переносимый рецепты одной
+записи обязаны мерить одно и то же. Поэтому рецепт один, переносимый; кому нужна точность по
+стилям — ставит `stylelint` отдельно, это не отменяет запись.
+
+**Замер на живом проекте.** React, двенадцать тем, 2750 файлов кода. Первый прогон дал 20
+находок, и **все 20 были чужими** — литералы в отдельных html-документах внутри `.claude/`:
+отчёты и справочники оснастки агента. Отдельный html-документ темы не имеет и иметь не может,
+литерал там законен; `.html` убран из списка расширений — не на вкус, а по этому замеру.
+Второй прогон: одна находка во фронтенде — палитра диаграммы загрузки, где цвета треков вписаны
+литералами Tailwind-500 и потому не меняются вместе с темой. Ложных срабатываний: **одно**, и
+оно тоже исправлено — цвет, упомянутый внутри многострочного комментария, читался как находка.
+
+**Чего НЕ ловит.**
+
+- Цвет, собранный по частям: `"#" + hex`, `rgb(37, 99, 235)`, `hsl(...)`, именованные `red` и
+  `white`. Проверка ищет литерал в форме `#rgb`, `#rrggbb`, `#rrggbbaa`, а не «цвет вообще».
+- Селектор по идентификатору, записанный шестнадцатеричными буквами (`#abcdef { … }`), и якорь
+  в ссылке той же формы читаются как цвет. Это цена простоты; лечится именем в allowlist.
+- Литерал в разметке и в документации: расширений `.md` и `.html` в списке нет намеренно.
+  В разметке цвет упоминают, а не применяют; отдельный html-документ не имеет темы, и литерал
+  в нём законен — как печать в скрипте для `no-print-in-prod`.
+- Цвет, вычисленный в рантайме: `lighten(base, 0.2)`, значение из ответа сервера, инлайн-стиль,
+  собранный из переменной. Проверка читает исходник, а не то, что окажется в браузере.
+
+**Образцы.** `red/` — три стека, где цвет вписан литералом: React со `style`, обычный CSS,
+однофайловый компонент Vue. `green/` — то же самое через токены, плюс `tokens.css`, где литерал
+законен, и заметка в разметке, на которой проверка обязана молчать.

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env sh
+# Цвет приходит из токена темы, а не из литерала в компоненте.
+#
+# ЗАЧЕМ. Литеральный цвет тема не перекрашивает. Проект с несколькими темами получает экран,
+# который в тёмной теме остаётся светлым пятном, — и это видно не автору, а пользователю,
+# который переключил тему. Дефект тихий: в теме автора всё выглядит правильно.
+DIR="${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+
+# Расширения, где живёт ТЕМИЗИРУЕМЫЙ интерфейс. Своё, а не общий CODE_EXT: там нет ни css, ни
+# vue — они не код в смысле «отладочная печать», но именно в них живёт цвет.
+#
+# `.html` в списке НЕТ, и это измерено, а не выбрано на вкус. Первый прогон по живому проекту
+# (React, 12 тем) дал 20 находок, и ВСЕ 20 — в отдельных html-документах внутри `.claude/`:
+# отчёты и справочники оснастки агента. Во фронтенде — ноль. Отдельный html-документ не имеет
+# темы и не может её иметь: литерал там законен, как печать в скрипте. Гейт, на 100%
+# состоящий из чужих находок, выключают в первый день — см. шапку `_skip.sh`.
+COLOR_EXT="css scss sass less styl ts tsx js jsx mjs cjs vue svelte astro"
+
+# Файлы-ИСТОЧНИКИ значений: там литерал законен, иначе токену неоткуда взяться. Имя источника
+# проект называет сам — как и каталоги с законной печатью в no-print-in-prod. По умолчанию
+# общепринятые имена; свои задаются переменной, рядом с командой в манифесте.
+SOURCE_RE="${AQK_COLOR_SOURCE:-tokens|theme|themes|palette|colors|colours|variables|design-system}"
+
+EXT_RE="$(printf '%s' "$COLOR_EXT" | tr ' ' '|')"
+
+# shellcheck disable=SC2086
+HITS=$(find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null \
+  | grep -E "\.($EXT_RE)$" \
+  | grep -viE "(^|/)[^/]*($SOURCE_RE)[^/]*\.($EXT_RE)$" \
+  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | LC_ALL=C sort \
+  | xargs -r awk '
+      # Блочные комментарии вырезаются ПО СОСТОЯНИЮ, а не построчно. Однострочный фильтр
+      # смотрит только на начало строки, и цвет, упомянутый в середине многострочного
+      # пояснения, читался как находка: на живом проекте так и вышло — единственное
+      # ложное срабатывание пришло из строки внутри /* … */. Тот же класс, что запись
+      # журнала «печать внутри комментария считалась печатью».
+      FNR == 1 { inblock = 0 }
+      {
+        line = $0
+        if (inblock) {
+          i = index(line, "*/")
+          if (i == 0) next
+          line = substr(line, i + 2); inblock = 0
+        }
+        # Вырезаем закрытые /* … */ внутри строки, затем открытый хвост.
+        while ((s = index(line, "/*")) > 0) {
+          rest = substr(line, s + 2)
+          e = index(rest, "*/")
+          if (e == 0) { line = substr(line, 1, s - 1); inblock = 1; break }
+          line = substr(line, 1, s - 1) substr(rest, e + 2)
+        }
+        if (line ~ /#[0-9a-fA-F]{8}([^0-9a-fA-F]|$)|#[0-9a-fA-F]{6}([^0-9a-fA-F]|$)|#[0-9a-fA-F]{3}([^0-9a-fA-F]|$)/)
+          print FILENAME ":" FNR ":" $0
+      }
+    ' 2>/dev/null \
+  | drop_comments \
+  | own_samples_filter "$DIR")
+
+if [ -n "$HITS" ]; then
+  printf '%s\n' "$HITS" | head -20
+  N=$(printf '%s\n' "$HITS" | grep -c .); [ "$N" -gt 20 ] && echo "  … и ещё $((N - 20))"
+  echo "  почини: замени литерал на токен темы — var(--color-…), theme('colors.…'), \$color-…"
+  echo "  литеральный цвет тема не перекрашивает: в другой теме экран останется чужим пятном."
+  echo "  файл-источник значений называется сам: AQK_COLOR_SOURCE='tokens|brand' перед командой."
+  exit 1
+fi
+exit 0

package/kit/gates/color-from-token/gate.yml

@@ -0,0 +1,15 @@
+intent: цвет приходит из токена темы, а не литералом в компоненте
+intent_en: colour comes from a theme token, not a literal in the component
+
+# Не по языку, а по наличию интерфейса. Триггер `langs: javascript, typescript` показывал бы
+# запись каждому бэкенду, библиотеке и утилите командной строки на JS — а их большинство, и
+# интерфейса там нет. Записи, показанной не тому, не верят, и это стоит доверия всему каталогу.
+trigger:
+  has_ui: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-06 «из тридцати с лишним запретов интерфейса гейт ловил
+  одиннадцать» — прогон по audit_project (Django + React, 12 тем): проверка №8 в собственной
+  оснастке проекта родилась после экранов, остававшихся светлыми в тёмной теме

package/kit/gates/color-from-token/green/Button.tsx

@@ -0,0 +1,4 @@
+export function Button({ children }: { children: React.ReactNode }) {
+  // Цвет приходит из темы: перекрашивается вместе с ней.
+  return <button className="bg-[var(--color-accent)] text-[var(--color-on-accent)]">{children}</button>;
+}

package/kit/gates/color-from-token/green/Panel.vue

@@ -0,0 +1,4 @@
+<template><div class="panel">панель</div></template>
+<style scoped>
+.panel { background: var(--surface-base); box-shadow: 0 1px 2px var(--shadow-sm); }
+</style>

package/kit/gates/color-from-token/green/card.css

@@ -0,0 +1,5 @@
+.card {
+  background: var(--surface-elevated);
+  border: 1px solid var(--border-hairline);
+  color: var(--text-primary);
+}

package/kit/gates/color-from-token/green/notes.md

@@ -0,0 +1,2 @@
+Заметка рядом с кодом: цвет `#2563EB` упоминается в тексте, а не применяется.
+Разметка в список расширений не входит — проверка сюда не смотрит.

package/kit/gates/color-from-token/green/tokens.css

@@ -0,0 +1,7 @@
+/* Файл-ИСТОЧНИК значений: здесь литерал законен, иначе токену неоткуда взяться.
+   Имя распознаётся по умолчанию; своё задаётся переменной AQK_COLOR_SOURCE. */
+:root {
+  --color-accent: #2563EB;
+  --surface-base: #0B0B0B;
+  --text-primary: #F4F1EA;
+}

package/kit/gates/color-from-token/red/Button.tsx

@@ -0,0 +1,4 @@
+export function Button({ children }: { children: React.ReactNode }) {
+  // Литерал: в тёмной теме кнопка останется светлой.
+  return <button style={{ background: "#2563EB", color: "#fff" }}>{children}</button>;
+}

package/kit/gates/color-from-token/red/Panel.vue

@@ -0,0 +1,4 @@
+<template><div class="panel">панель</div></template>
+<style scoped>
+.panel { background: #1a1a1a; box-shadow: 0 1px 2px #00000022; }
+</style>

package/kit/gates/color-from-token/red/card.css

@@ -0,0 +1,5 @@
+.card {
+  background: #F4F1EA;
+  border: 1px solid #ddd;
+  color: #0B0B0B;
+}

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

@@ -26,7 +26,30 @@ else
     exit 0
   fi
 
-  MSG=$(cd "$DIR" && git log -1 --format=%B 2>/dev/null)
+  # Сообщение слияния сочиняет не автор, а инструмент. GitHub делает это дважды и по-разному:
+  # при разборе предложения изменений выкладывает синтетический коммит «Merge <sha> into <sha>»,
+  # а кнопка Merge на сайте пишет «Merge pull request #N from …». Первую форму гейт научился
+  # различать вчера по словам — и на второй покраснел бы снова.
+  #
+  # Поэтому смотрим не на слова, а на форму: у слияния два родителя. Если при этом в сообщении
+  # нет разделов отчёта — его писал инструмент, и спрашивать надо второго родителя, последний
+  # коммит автора. Слияние, которое автор описал сам, проходит по HEAD и ничего не теряет.
+  REF=HEAD
+  PARENTS=$(cd "$DIR" && git rev-list --parents -n 1 HEAD 2>/dev/null | wc -w)
+  HEADMSG=$(cd "$DIR" && git log -1 --format=%B 2>/dev/null)
+  if [ "${PARENTS:-0}" -ge 3 ] &&
+     ! printf '%s\n' "$HEADMSG" | grep -q "^Сделано:" &&
+     ! printf '%s\n' "$HEADMSG" | grep -q "^Не уверен:"; then
+    if (cd "$DIR" && git rev-parse -q --verify HEAD^2 >/dev/null 2>&1); then
+      REF=HEAD^2
+    else
+      echo "слияние без отчёта, второго родителя не видно — проверка пропущена"
+      echo "  дай конвейеру два коммита истории: actions/checkout@v4 с fetch-depth: 2"
+      exit 0
+    fi
+  fi
+
+  MSG=$(cd "$DIR" && git log -1 --format=%B "$REF" 2>/dev/null)
 
   # Коммит, который трогает только журнал, отчёта в теле не требует: сама запись и есть отчёт,
   # причём подробнее — и её сторожит `lesson-has-outcome`. Иначе гейт воюет с командой `note`,
@@ -38,7 +61,7 @@ else
   [ -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 '^$')
+    FILES=$(cd "$DIR" && git show --pretty=format: --name-only "$REF" 2>/dev/null | grep -v '^$')
     if [ -n "$FILES" ]; then
       OUTSIDE=$(printf '%s\n' "$FILES" | grep -v "^$LESSONS/" | grep -v "^$LESSONS\$")
       if [ -z "$OUTSIDE" ]; then