agent-quality-kit 0.5.0 → 0.7.0

package/kit/gates/no-phantom-package/check.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env sh
+# Имена пакетов, названные в документации, сверяются с реестром npm.
+#
+# ЗАЧЕМ. Агент, не знающий инструмента, придумывает правдоподобное имя. Дальше его читает
+# другой агент и выполняет `npm install` — и если имя к тому времени кем-то занято, в проект
+# приезжает чужой код. Обычные проверки цепочки поставок смотрят на пакеты, которые ЕСТЬ;
+# здесь опасен как раз тот, которого пока нет.
+#
+# Работу делает slopcheck (MIT, ноль зависимостей). Мы отвечаем за три вещи, которых он не
+# делает: какие файлы ему дать, что считать браком и что делать, когда ответа не было.
+# Каждая ветка «ответа не было» кончается кодом 2 и словами «проверка не состоялась»: у
+# инструмента, написанного против молчаливого зелёного, своего молчаливого зелёного быть не может.
+DIR="${1:-.}"
+
+# Существование файла проверяется ДО `.`, а не запасной веткой после. В POSIX-оболочке (здесь
+# dash) неудачный `.` завершает скрипт немедленно — привычное «. файл || запасной_вариант» не
+# выполняется НИКОГДА, и гейт умирает с кодом 2 без единого слова о причине. Проверено прогоном
+# 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"
+
+# Даже когда файл на месте, нужных функций в нём может не оказаться: без них конвейер ниже не
+# напечатает ни одного пути, список окажется пуст, а пустой список — это `exit 0`. Гейт вышел бы
+# зелёным, не посмотрев ни в один файл.
+if ! command -v own_samples_filter >/dev/null 2>&1; then
+  echo "в _skip.sh нет обхода own_samples_filter — проверка не состоялась"
+  echo "  почини: обнови kit/gates/_skip.sh до версии, идущей с этим гейтом"
+  exit 2
+fi
+
+if ! command -v slopcheck >/dev/null 2>&1; then
+  echo "не найден slopcheck — эта проверка делегирована ему"
+  echo "  почини: npm i -g slopcheck@0.2.0"
+  exit 2
+fi
+
+# Свой обход, а не встроенный в slopcheck: только так работает own_samples_filter. Без него
+# красный образец этой же записи выдаётся за находку, и гейт краснеет на самом комплекте.
+LIST=$(mktemp) || exit 2
+# shellcheck disable=SC2046
+find "$DIR" $(skip_find "$DIR") -type f \
+     \( -name '*.md' -o -name '*.mdc' -o -name '*.yml' -o -name '*.yaml' \
+        -o -name '*.json' -o -name '.cursorrules' \) -print 2>/dev/null \
+  | own_samples_filter "$DIR" > "$LIST"
+
+if [ ! -s "$LIST" ]; then rm -f "$LIST"; exit 0; fi
+
+# Через NUL, а не через $(...): путь с пробелом иначе распадается на два аргумента, slopcheck
+# не находит ни одного из них и молча выходит с нулём. Та же ловушка уже стоила нам зелёного
+# вердикта в hook-actually-fires.
+ERRF=$(mktemp) || { rm -f "$LIST"; exit 2; }
+OUT=$(tr '\n' '\0' < "$LIST" | xargs -0 slopcheck --json 2>"$ERRF")
+# Код xargs: 0 — все вызовы прошли, 123 — хотя бы один вернул 1..125. Именно 123 приходит и на
+# честной находке (slopcheck выходит с 1), поэтому сам по себе он ничего не значит. А вот всё
+# остальное — сбой обвязки, и его нельзя принимать за вердикт.
+XS=$?
+ERR=$(cat "$ERRF" 2>/dev/null)
+rm -f "$ERRF" "$LIST"
+
+# Файлов может оказаться больше, чем влезает в одну команду, и тогда xargs зовёт slopcheck
+# несколько раз. Упавший вызов пишет в stderr, а уцелевшие всё равно печатают свой JSON —
+# счётчики сходятся, и гейт вышел бы с нулём, не проверив целую партию файлов.
+if [ -n "$ERR" ] || { [ "$XS" -ne 0 ] && [ "$XS" -ne 123 ]; }; then
+  echo "slopcheck не отработал (код $XS) — проверка не состоялась, это не вердикт «чисто»"
+  [ -n "$ERR" ] && printf '%s\n' "$ERR" | head -5 | sed 's/^/  /'
+  echo "  почини: прогони «slopcheck --json .» руками и посмотри, на чём он споткнулся"
+  exit 2
+fi
+
+[ -n "$OUT" ] || {
+  echo "slopcheck ничего не ответил — проверка не состоялась, это не вердикт «чисто»"
+  echo "  почини: прогони «slopcheck --json .» руками и посмотри, на чём он споткнулся"
+  exit 2
+}
+
+printf '%s\n' "$OUT" | awk '
+  function val(s) { sub(/^[^:]*:[[:space:]]*/, "", s); sub(/,$/, "", s); gsub(/^"|"$/, "", s); return s }
+  function label(s) {
+    if (s == "not_found")     return "в реестре такого пакета нет"
+    if (s == "unpublished")   return "пакет был и снят с публикации — имя свободно для захвата"
+    if (s == "security_hold") return "реестр пометил пакет как вредоносный"
+    return ""
+  }
+  # xargs может позвать slopcheck несколько раз, если путей слишком много для одной команды.
+  # Тогда JSON-документов на входе будет несколько, и счётчики надо складывать, а не брать
+  # последний: иначе находки первой партии исчезнут.
+  /^  "packages"/            { inpkg = 1; sawpkg = 1; next }
+  inpkg && /^  \}/           { inpkg = 0; next }
+  inpkg && /"errors"/        { errs += val($0); next }
+  inpkg && /"notFound"/      { bad  += val($0); next }
+  inpkg && /"unpublished"/   { bad  += val($0); next }
+  inpkg && /"securityHold"/  { bad  += val($0); next }
+  /^      "package"/         { pkg = val($0); next }
+  /^      "status"/          { st  = val($0); next }
+  /^          "file"/        { f  = val($0); next }
+  /^          "line"/        { ln = val($0); next }
+  # Печатаем на «command»: он идёт последним в записи о месте, значит к этому моменту известны
+  # и пакет, и состояние, и файл со строкой.
+  /^          "command"/ {
+    cmd = val($0)
+    if (st == "error") next
+    # Состояние, которого мы не знаем. Раньше здесь стояло «всё, что не error, — брак», и
+    # новое состояние в следующей версии slopcheck превратило бы КАЖДУЮ команду установки в
+    # находку с английским словом вместо объяснения. Незнакомое состояние — повод сказать
+    # «не разобрали», а не вынести вердикт.
+    if (label(st) == "") { unknown = st; next }
+    if (shown < 20) print f ":" ln ": «" pkg "» — " label(st) " · " cmd
+    shown++
+    next
+  }
+  END {
+    if (unknown != "") {
+      print "slopcheck вернул незнакомое состояние «" unknown "» — разобрать ответ не вышло"
+      print "  почини: сверь версию slopcheck с той, что названа в gate.yml"
+      exit 2
+    }
+    if (shown > 20) print "  … и ещё " (shown - 20)
+    if (shown > 0) {
+      # Находки и «не проверено» показываются вместе. Свернуть второе в первое значило бы
+      # потерять ровно ту разницу, ради которой написана эта обёртка.
+      if (errs > 0) print "  кроме того, реестр не ответил по именам: " errs " — они НЕ проверены"
+      print "  почини: проверь имя в реестре и впиши настоящее. Если пакета нет, его может"
+      print "  зарегистрировать кто угодно — и следующий агент выполнит установку чужого кода."
+      exit 1
+    }
+    # Реестр не ответил. Молчать здесь нельзя: тишина неотличима от «всё хорошо», а именно
+    # это наш стандарт и запрещает. Красим отдельным кодом, чтобы вердикт не путали с браком.
+    # Причина названа обеими: slopcheck помечает так и недоступную сеть, и ответ 429 «слишком
+    # часто», и любой другой не-200 — снаружи они неразличимы, и врать про сеть мы не будем.
+    if (errs > 0) {
+      print "реестр npm не ответил: не проверено имён — " errs
+      print "  проверка не состоялась. Это не вердикт «чисто»."
+      print "  почини: если сети нет — прогони гейт там, где она есть. Если сеть есть, реестр"
+      print "  мог ограничить частоту запросов: повтори через минуту."
+      exit 2
+    }
+    # Блока со счётчиками не нашлось вовсе. Так будет, если slopcheck начнёт печатать JSON
+    # одной строкой: ни одно правило выше не сработает, все счётчики останутся нулями — и
+    # проверка выйдет с нулём, ничего не проверив. Нашли это прогоном подставного вывода уже
+    # после того, как записали «формат стабилен»: догадка о стабильности стоила бы молчаливого
+    # зелёного на каждом прогоне.
+    if (!sawpkg) {
+      print "ответ slopcheck не разобран: блока «packages» в нём нет"
+      print "  почини: сверь версию slopcheck с той, что названа в gate.yml"
+      exit 2
+    }
+    # Счётчик говорит о браке, а печатать нечего — значит мы разучились читать вывод slopcheck
+    # (сменился формат). Тоже не вердикт «чисто».
+    if (bad > 0) {
+      print "slopcheck насчитал находок: " bad ", но разобрать их не вышло — сменился формат"
+      print "  почини: сверь версию slopcheck с той, что названа в gate.yml"
+      exit 2
+    }
+    exit 0
+  }
+'

package/kit/gates/no-phantom-package/gate.yml

@@ -0,0 +1,20 @@
+intent: имя пакета, названное в документации, существует в реестре
+intent_en: a package name mentioned in the documentation exists in the registry
+
+# Там, где агента используют: предмет проверки — текст, который агент читает и по которому
+# выполняет установку. В проекте без такого текста ставить запись незачем.
+trigger:
+  has_agent_entry: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+# Программа, без которой запись не работает. По первому слову команды этого не видно: обёртка
+# начинается с `bash`, который есть всегда. Версия названа: обёртка разбирает JSON slopcheck,
+# и смена формата обязана быть видимой, а не тихой.
+requires: slopcheck
+
+proof: incidents/README.md, 2026-09-08 «пакет-призрак из чужого README оказался
+  зарегистрирован» — `react-codeshift`, канонический пример slopsquatting из README самого
+  slopcheck, на 2026-09-08 существует в npm (создан 2026-01-14, maintainer debugducky);
+  доля выдуманных имён в сгенерированном коде — USENIX Security 2025, arxiv 2406.10279

package/kit/gates/no-phantom-package/green/AGENTS.md

@@ -0,0 +1,15 @@
+# Правила проекта
+
+## Как чинить импорты
+
+Перед коммитом прогони кодмод:
+
+```bash
+npx jscodeshift --fix src/
+```
+
+## Форматирование
+
+```bash
+npm install prettier
+```

package/kit/gates/no-phantom-package/red/AGENTS.md

@@ -0,0 +1,15 @@
+# Правила проекта
+
+## Как чинить импорты
+
+Перед коммитом прогони кодмод:
+
+```bash
+npx reactCodemodHelper --fix src/
+```
+
+## Форматирование
+
+```bash
+npm install prettier
+```

package/kit/gates/no-print-in-prod/README.md

@@ -3,42 +3,36 @@
 **Намерение.** `print` и `console.log` не попадают в прод: они проходят мимо системы логов,
 не имеют уровня и могут вынести наружу то, чего в выводе быть не должно.
 
-**Какой отказ это поймало.** Прогон по `audit_project`: 40 находок, из них **5 настоящих** —
-отладочный хук `useScrollDebugger.ts`, уехавший во фронтенд и печатавший размеры окна в консоль
-пользователя. Остальные 35 разобраны поимённо и оказались законной печатью или шумом проверки.
-Запись в журнале: `incidents/README.md`, 2026-09-03.
-
-До этого прогона доказательства у записи не было, и она полтора месяца висела условной. Так и
-надо: каталог не выбрасывает слабое доказательство и не делает вид, что оно сильное, — он его
-помечает и ждёт факта.
-
-**Для программы командной строки печать — это интерфейс.** В `main` консольной утилиты
-`fmt.Println` или `println!` — не забытая отладка, а способ выдать результат. Такие каталоги
-проект называет сам, рядом с командой в манифесте:
-
-```yaml
-no-print-in-prod: "AQK_PRINT_OK_DIRS=cli bash .aqk/gates/no-print-in-prod/check.sh ."
-```
-
-**Не храповиком.** Сначала мы записали такие места долгом — и каждая новая строка вывода красила
-проверку, требуя переснять реестр. Долг — это то, что собираются погасить; печать из программы
-командной строки убирать никто не будет. Долг, который нельзя погасить работой, — не долг, а
-неверная мера. Храповик остаётся для настоящего долга: печати в прод-коде, которую уберут, но
-не сегодня.
-
-**Где печать законна.** Вспомогательные скрипты, оснастка агента, примеры, записные книжки,
-миграции — там печать это способ говорить с человеком, а не забытая отладка. Эти каталоги
-проверка пропускает. Различие важное: секрет в `scripts/` — такой же секрет, а печать — нет.
-
-**Готовый аналог есть и он точнее.** В Python это `ruff --select T20`, в TypeScript — правило
-`no-console` в eslint. Рецепты под эти стеки берут готовое; переносимая проверка остаётся для
-Go, Rust и всего остального, где готового под рукой нет.
-
-**Чего НЕ ловит.** Печать через обёртку — `myprint(x)`, `logger.print`, свой хелпер — проверка не
-видит: она ищет известные конструкции языка, а не «вывод в поток». Не видит и печать в строке,
-собранной по частям. Найдено на комментариях: печать внутри `//`, `#` и `/* */` отбрасывается,
-потому что комментарий не выполняется.
-
-**Образцы.** `red/` — модуль с отладочной печатью на трёх языках. `green/` — тот же модуль через
-систему логов, плюс пример в JSDoc и закомментированная строка, на которых проверка обязана
-молчать.
+**Своей проверки здесь больше нет — и это результат замера, а не вкуса.** Переносимая версия
+искала конструкции печати по тексту. Прогон по пяти чужим репозиториям (`httpx`, `fastapi`,
+`zod`, `cobra`, `ripgrep`) дал **434 находки, настоящих — ноль**:
+
+| Где нашлось | Что это было на самом деле |
+|---|---|
+| `zod/packages/bench` — 231 | бенчмарки, где печать и есть предмет |
+| `fastapi/docs_src` | примеры кода в документации |
+| `httpx/_exceptions.py` | печать **внутри строки документации**, между ``` |
+| `fastapi/cli.py` | вывод программы командной строки — это интерфейс |
+| `httpx/tests` | тесты |
+
+Отличить это от забытой отладки можно только разбором кода, а не поиском по тексту. Разбор
+уже написан и поддерживается: `ruff` и `eslint`. Наш поиск по тексту не приближался к ним и не
+мог приблизиться.
+
+**Готовый аналог — это и есть он сам.** `ruff --select T20` для Python, правило `no-console`
+в eslint для JavaScript и TypeScript. Триггер записи сужен ровно до этих трёх языков: показывать
+её проекту на Go, которому мы не можем дать ни инструмента, ни своей проверки, — значит показывать
+работу, которую человек сделать не сможет.
+
+**Чего НЕ ловит.** Печать через обёртку — `myprint(x)`, свой хелпер — не видит ни один из двоих:
+они знают конструкции языка, а не «вывод в поток». Печать из программы командной строки оба
+считают нарушением, хотя там она законна; такие каталоги исключают настройкой самого
+инструмента (`per-file-ignores` в `ruff`, `overrides` в eslint), а не нашим кодом.
+
+**Чем это оплачено.** Проект на Go, Rust, Java, Ruby по этому пункту не получает ничего. Так
+честнее: проверка, которая на живом коде ошибается в ста процентах случаев, не «лучше, чем
+ничего» — она хуже. Её выключают целиком, а вместе с ней и те, что работают.
+
+**Образцы.** `red/service.py` — модуль с отладочной печатью. `green/service.py` — тот же модуль
+через систему логов. `green/legacy.py` — закомментированная печать, на которой арбитр обязан
+молчать. Проверяются рецептом `python` (`samples_for`), потому что переносимого рецепта нет.

package/kit/gates/no-print-in-prod/gate.yml

@@ -1,16 +1,24 @@
 intent: отладочная печать не доезжает до прод-кода
 intent_en: debug printing does not reach production code
 
-# Запись касается только языков, где есть эта конструкция. В проекте на Go или
-# Rust она не показывается вовсе.
+# Запись касается только языков, где под неё есть готовый инструмент. В проекте
+# на Go или Rust она не показывается вовсе — и переносимого рецепта здесь больше нет.
 trigger:
   langs: python, javascript, typescript
 
+# Переносимого рецепта нет намеренно. Он был, и замер по пяти чужим репозиториям
+# (httpx, fastapi, zod, cobra, ripgrep) дал 434 находки, из которых настоящих — ноль:
+# печать в примерах документации, в тестах, в бенчмарках и в выводе командной строки.
+# Отличить их от отладки можно только разбором кода, а не поиском по тексту, — и это
+# ровно то, что уже делают ruff и eslint.
 recipes:
-  any: bash {gate}/check.sh {dir}
   python: ruff check --select T20 {dir}
   typescript: eslint --rule '{"no-console":"error"}' {dir}
+  javascript: eslint --rule '{"no-console":"error"}' {dir}
 
-proof: incidents/README.md, 2026-09-03 «печать внутри комментария считалась печатью» —
-  прогон по audit_project: 40 находок, из них 5 настоящих (отладочный хук во фронтенде,
-  печатавший размеры окна в консоль пользователя)
+# Каким рецептом написаны образцы: без переносимого рецепта проверка обязана знать это точно,
+# иначе питоновские образцы поедут проверяться фронтовым инструментом.
+samples_for: python
+
+proof: incidents/README.md, 2026-09-07 «замер по пяти стекам вынес приговор пяти записям» —
+  434 находки переносимой проверки на пяти чужих репозиториях, настоящих ноль

package/kit/gates/personal-config-not-shared/README.md

@@ -0,0 +1,66 @@
+# Личное не раздаётся всему проекту
+
+**Намерение.** `CLAUDE.local.md` и `.claude/settings.local.json` по устройству личные. Попав в
+git, они становятся обязательными для всех — и при этом их никто не рецензирует, потому что
+туда их никто и не звал.
+
+**Дело не в опрятности.** Документация Claude Code, дословно:
+
+> Within each directory, `CLAUDE.local.md` is appended after `CLAUDE.md`, so your personal notes
+> are the last thing Claude reads at that level.
+
+То есть личные заметки одного человека читаются **последними** и перекрывают общие правила
+команды — молча, у каждого. С правами то же самое: разрешения, которые человек выдал себе,
+достаются всем, кто склонировал репозиторий.
+
+Оба файла документация прямо велит не коммитить:
+
+> For private per-project preferences that shouldn't be checked into version control… Add
+> `CLAUDE.local.md` to your `.gitignore` so it isn't committed.
+
+> Claude Code keeps it out of git when it creates the file; if you create it by hand, add it to
+> `.gitignore` yourself.
+
+(`code.claude.com/docs/en/memory` и `/settings`, сверено 2026-09-07.)
+
+**Какой отказ это поймало.** Замер по тринадцати чужим репозиториям: шесть настоящих находок в
+пяти, ноль ложных на семи контрольных. Самая наглядная — `shacker/django-todo`:
+
+```json
+"allow": [
+  "Read(//Users/shacker/**)",
+  "Bash(/Users/shacker/dev/home/django-todo/.venv/bin/python -m pytest …)"
+]
+```
+
+Домашний каталог автора и абсолютные пути с его машины раздаются всем, кто клонирует проект.
+На чужой машине они не работают, а разрешение на чтение чужого домашнего каталога — работает.
+
+**Готовый аналог есть, и он не роняет прогон.** У [`AgentLint`](https://github.com/0xmariowu/AgentLint)
+есть проверка C5 «`CLAUDE.local.md` not in git». Прогнали живьём (`npx -p agentlint-ai agentlint
+check`, 2026-09-07) на репозитории, где в git лежат и `CLAUDE.local.md`, и
+`.claude/settings.local.json`: он выдал **61/100** и **код возврата 0**. Флага порога в его
+README нет, `--help` вывода не дал. Это оценка, а не гейт: в конвейере такой прогон зелёный.
+Разница ровно та, ради которой существует наш стандарт. `claudelint` этой проверки не имеет.
+
+**Чего НЕ ловит.**
+
+- **Файл, лежащий на диске и не отслеживаемый git.** Он и не должен ловиться: это норма.
+- **Репозиторий-заготовку проекта.** Если в корне лежит `cookiecutter.json`, `copier.yml` или
+  `.copier-answers.yml`, все файлы в нём — рыба для будущего проекта, а не чьи-то личные.
+  Проверка молча пропускает такой репозиторий, назвав причину вслух. Найдено замером:
+  в `Frojd/Wagtail-Pipit` обе находки были ровно такими, и обе ложные.
+- **Заготовки по имени и по месту:** `*.example`, `*.template`, каталоги `templates/`,
+  `examples/`, `samples/`, `fixtures/`, а также подстановки генератора `{{…}}` в пути.
+- **Личный свод под чужим именем.** Файл, названный `CLAUDE.md`, но содержащий личные заметки,
+  проверка не отличит: она смотрит на имя и на git, а не на смысл текста.
+- **Файлы других агентов.** `.cursor/rules` и инструкции copilot своего «личного» уровня не
+  имеют — проверять там нечего.
+
+**Образцы.** Настоящего git внутри каталога комплекта взять неоткуда, поэтому образцы кладут
+список отслеживаемых файлов в `.aqk-tracked`; в живом проекте такого файла не бывает и список
+спрашивается у git. Имя с точкой намеренно: файл `TRACKED` в корне чужого проекта — вещь
+возможная, и он молча подменял бы собой список git. `red/` — оба личных файла в индексе.
+`green/` — заготовки по имени, по каталогу и с подстановкой генератора, плюс `settings.local.json`
+в `.vscode/` и `node_modules/`, на которых арбитр обязан молчать: личным этот файл считается
+только внутри `.claude/`.

package/kit/gates/personal-config-not-shared/check.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env sh
+# Личный файл агента, попавший в git: то, что человек писал для себя, становится обязательным
+# для всех и никем не рецензируется.
+#
+# ЗАЧЕМ. Дело не в опрятности. `CLAUDE.local.md` дописывается ПОСЛЕ общего свода — дословно из
+# документации: "Within each directory, `CLAUDE.local.md` is appended after `CLAUDE.md`, so your
+# personal notes are the last thing Claude reads at that level"
+# (code.claude.com/docs/en/memory, сверено 2026-09-07). Значит личные заметки одного человека
+# читаются последними и перекрывают общие правила команды — у всех, молча.
+# `.claude/settings.local.json` — то же самое для прав: разрешения, которые один человек выдал
+# себе, достаются всем, кто склонировал репозиторий.
+#
+# Оба файла по устройству личные, и документация говорит об этом прямо: "For private
+# per-project preferences that shouldn't be checked into version control… Add `CLAUDE.local.md`
+# to your `.gitignore` so it isn't committed" и "Claude Code keeps it out of git when it creates
+# the file; if you create it by hand, add it to `.gitignore` yourself".
+DIR="${1:-.}"
+# Существование файла проверяется ДО `.`, а не запасной веткой после. Прежняя строка
+# `. файл 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"
+
+# Образцы (gates.sh) читают список отслеживаемых файлов из `.aqk-tracked`: настоящего git внутри
+# каталога комплекта взять неоткуда, а вложенный .git создал бы embedded-репозиторий.
+# В настоящем проекте такого файла не бывает — спрашиваем сам git.
+# Имя с точкой намеренно: файл `TRACKED` в корне проекта — вещь возможная, и он молча
+# подменял бы собой список git. Найдено код-ревью 2026-09-07.
+if [ -f "$DIR/.aqk-tracked" ]; then
+  LIST=$(cat "$DIR/.aqk-tracked")
+else
+  if ! (cd "$DIR" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1); then
+    echo "не git-репозиторий — проверять нечего"
+    exit 0
+  fi
+  # core.quotePath=false ОБЯЗАТЕЛЕН. По умолчанию git заворачивает путь с не-ASCII в кавычки
+  # («"\320\264\320\276\320\272/CLAUDE.local.md"»), и якорь «$» в шаблоне ниже не совпадал:
+  # личный свод в каталоге с русским именем пропускался молча. Тот же класс, что CRLF ниже.
+  # Найдено код-ревью 2026-09-07.
+  LIST=$(cd "$DIR" && git -c core.quotePath=false ls-files 2>/dev/null)
+fi
+# Перевод строки Windows. Без снятия «\r» якорь «$» в шаблоне ниже не совпадал, и красный
+# образец с CRLF становился зелёным. Поймано мутационной проверкой до единого прогона в чужом
+# проекте — ровно то, ради чего она написана.
+LIST=$(printf '%s\n' "$LIST" | tr -d '\r')
+[ -z "$LIST" ] && exit 0
+
+# Репозиторий, который целиком является заготовкой проекта, проверять нечем: все файлы в нём —
+# не чьи-то личные, а рыба для будущего проекта. Признак — файл настроек генератора в корне.
+# Замер: в `Frojd/Wagtail-Pipit` обе находки были такими, и обе ложные.
+# `.copier-answers.yml` в этот список НЕ входит, хотя выглядит родственником: copier кладёт его
+# в СГЕНЕРИРОВАННЫЙ проект, а не в шаблон. Шаблон несёт `copier.yml`. Найдено код-ревью
+# 2026-09-07: обычный рабочий репозиторий, собранный из copier-шаблона, целиком выпадал из
+# проверки — молчаливый отказ по причине, не имеющей отношения к предмету.
+for GEN in cookiecutter.json copier.yml copier.yaml; do
+  if [ -f "$DIR/$GEN" ]; then
+    echo "репозиторий — заготовка проекта ($GEN), личных файлов в нём нет по устройству"
+    exit 0
+  fi
+done
+
+# Заготовки — не личные файлы. Замер по выдаче поиска: из двадцати совпадений по имени
+# `CLAUDE.local.md` больше половины оказались `*.example`, `*.template` и файлами внутри
+# `templates/` — их кладут в репозиторий намеренно, чтобы человек скопировал себе.
+# Подстановки генератора (`{{cookiecutter.project_name}}/…`) — оттуда же.
+# `settings.local.json` считается личным ТОЛЬКО внутри `.claude/`: это единственное место,
+# откуда Claude Code его читает. Без привязки к каталогу под проверку попадали
+# `.vscode/settings.local.json` и `node_modules/…/settings.local.json` — чужие файлы с
+# совпавшим именем. Найдено код-ревью 2026-09-07.
+HITS=$(printf '%s\n' "$LIST" \
+  | grep -E '(^|/)(CLAUDE\.local\.md|\.claude/settings\.local\.json)$' \
+  | grep -vE '(^|/)(templates?|examples?|samples?|dist|fixtures?)/' \
+  | grep -vF '{{' \
+  || true)
+
+# Образцы гейтов — не личные файлы. В красном образце другой записи может лежать настоящий
+# `settings.local.json`, и это её предмет, а не наш. Поймано на собственном репозитории:
+# первой находкой стал зелёный образец `hook-actually-fires`.
+if command -v own_samples_filter >/dev/null 2>&1 || type own_samples_filter >/dev/null 2>&1; then
+  HITS=$(printf '%s\n' "$HITS" | own_samples_filter "$DIR" | grep -v '^$' || true)
+fi
+# Каталог самого комплекта: у нас образцы лежат не в `gates/`, а в `kit/gates/`.
+HITS=$(printf '%s\n' "$HITS" | grep -vE '(^|/)kit/gates/[^/]+/(red|green)(/|$)' | grep -v '^$' || true)
+
+[ -z "$HITS" ] && exit 0
+
+printf '%s\n' "$HITS" | while IFS= read -r F; do
+  case "$F" in
+    *CLAUDE.local.md) echo "$F: личный свод отслеживается git — он дописывается ПОСЛЕ общего и перекрывает его у всех" ;;
+    *)                echo "$F: личные права отслеживаются git — разрешения одного человека достались всем" ;;
+  esac
+done
+echo "  почини: убери файл из индекса — git rm --cached <файл> — и добавь его в .gitignore."
+echo "  личное, попавшее в общий репозиторий, никто не рецензирует: его туда никто и не звал."
+exit 1

package/kit/gates/personal-config-not-shared/gate.yml

@@ -0,0 +1,16 @@
+intent: личные файлы агента не раздаются всему проекту через git
+intent_en: an agent's personal files are not shared with the whole project through git
+
+# Там, где агента используют: есть свод, который он читает при запуске. Признак шире, чем
+# `has_agent_config`: настройки заводят не все, а свод — почти каждый.
+trigger:
+  has_agent_entry: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-07 «личное, попавшее в общий репозиторий» — замер по
+  тринадцати чужим репозиториям: шесть настоящих находок в пяти (`shacker/django-todo` раздаёт
+  всем `Read(//Users/shacker/**)` и абсолютные пути со своей машины; `modu-ai/moai-adk`,
+  `garrynewman/Control4.Jailbreak`, `AmyangXYZ/reze-mipo`, `shuigedeng/taotao-cloud-project`),
+  ноль ложных на семи контрольных

package/kit/gates/personal-config-not-shared/green/.aqk-tracked

@@ -0,0 +1,9 @@
+README.md
+CLAUDE.md
+CLAUDE.local.md.example
+templates/CLAUDE.local.md
+docs/settings.local.json.template
+{{cookiecutter.project_name}}/CLAUDE.local.md
+.vscode/settings.local.json
+node_modules/foo/settings.local.json
+src/app.py

package/kit/gates/personal-config-not-shared/red/.aqk-tracked

@@ -0,0 +1,6 @@
+README.md
+CLAUDE.md
+CLAUDE.local.md
+.claude/settings.json
+.claude/settings.local.json
+src/app.py

package/kit/gates/promise-has-gate/README.md

@@ -0,0 +1,50 @@
+# У правила виден сторож
+
+**Намерение.** Это центральный вопрос всего комплекта. `AGENTS.md` — обычный текст: «никогда не
+коммитим секреты» и «мы очень стараемся» выглядят одинаково и стоят одинаково, пока никто не
+спросил, чем первое отличается от второго.
+
+**Какой отказ это поймало.** Свой собственный. Прогон по нашему же `AGENTS.md`: тринадцать
+железных правил, и **ни одно** не говорило, кто за ним следит. После разметки выяснилось, что
+одиннадцать из тринадцати исполняет человек, а не машина. Это не стало хуже — стало видно.
+Правило, за которым следит человек, законно; правило, о котором никто не знает, кто за ним
+следит, через месяц отличается от лозунга только длиной. Запись в журнале:
+`incidents/README.md`, 2026-09-06.
+
+**Что именно проверяется.** Каждый пункт списка в точке входа, который выглядит правилом
+(выделен жирным либо содержит слово долженствования или запрета), обязан нести пометку:
+
+```markdown
+- **Секреты не в коде.**  <!-- aqk: secrets-not-in-code -->
+- **План до кода.**       <!-- aqk: человек -->
+```
+
+Имя гейта сверяется с блоком `gates:` манифеста: пометка, ведущая в никуда, — тоже красное.
+Пометка живёт в комментарии разметки, поэтому в готовом документе её не видно.
+
+**Почему пометка, а не угадывание.** Сопоставлять обещание с гейтом по совпадению слов — значит
+выдавать вердикт по догадке; догадка, выданная за факт, и есть то, против чего построен весь
+стандарт. Пометка ставится один раз и делает документ честнее: у каждого правила видно, кто его
+сторожит.
+
+**Первый прогон в зрелом проекте покрасит всё.** Так и задумано, и лечится одной командой:
+`aqk ratchet promise-has-gate` — существующие правила становятся долгом, который может только
+сокращаться, а новое правило без сторожа краснеет сразу.
+
+**Готовый аналог.** Не нашли, и искали внимательно. К осени 2026 появился целый класс линтеров
+агентского обвеса — [`agnix`](https://github.com/agent-sh/agnix) (455 правил, активен),
+[`agents-lint`](https://github.com/giacomo/agents-lint), ctxlint, AgentLint. Все они проверяют
+**документ**: формат, живые ли ссылки, существуют ли упомянутые скрипты. Ни один не спрашивает,
+**исполнимо** ли обещание. Ставь `agnix` рядом — он закрывает то, чего не делаем мы, а мы
+закрываем то, чего не делает он.
+
+**Чего НЕ ловит.**
+
+- **Не проверяет, что гейт делает то, что обещано.** Пометка `<!-- aqk: secrets-not-in-code -->`
+  на правиле про длину функций пройдёт. Связь объявляет человек; машина сторожит только то, что
+  связь есть и ведёт в существующий гейт.
+- **`<!-- aqk: человек -->` не проверяется ничем** — это признание, а не проверка. Его ценность
+  в том, что признание сделано вслух и его видно в дифе, когда правил становится больше.
+- **Правило, не оформленное пунктом списка**, не опознаётся: абзац прозы обещанием не считается.
+- **Только точка входа**, объявленная в `entry:`. Правила, разложенные по десяти файлам
+  документации, эта запись не обойдёт.