agent-quality-kit 0.7.0 → 0.8.0

package/README.md

@@ -63,6 +63,48 @@ tooling: [the dark factory and the minimum that isn't optional](kit/docs/ai/proj
    a promise without an exit code is just a sentence
 ```
 
+## Every command
+
+```
+aqk doctor              what this repository is at, and what is missing
+aqk doctor --run        run every gate the manifest declares
+aqk doctor --run --since main    only what the diff introduced
+aqk doctor --run --min 1         fail a pipeline below a level
+aqk doctor --baseline   the minimum a project needs, confirmed by a run
+
+aqk init                lay the kit into an existing repository
+aqk start               start a new project from the kit
+aqk add <name>          install one guard from the catalogue
+aqk new <name>          scaffold a guard of your own
+aqk find <text>         find a guard by intent
+aqk why <name>          what failure this guard was written for
+
+aqk prove               run every declared gate against its own samples:
+                        red on the red one, quiet on the green one
+aqk report              the report form, assembled by a run
+aqk report --since main  ...plus what proves this diff, file by file
+aqk badge               write the level badge into the README
+aqk badge --check       fail if the badge disagrees with a run
+
+aqk context             the repository state in one block, for an agent's context:
+                        level, what is red now, rules nobody enforces, ratchets
+aqk context --full      the same plus the command map and the rulebook verbatim (~7000
+                        tokens against ~375: the price of an agent that does not guess)
+aqk context --install   put a SessionStart hook into .claude/settings.json
+                        (add --full to install the full block)
+
+aqk learn               rule candidates from local transcripts:
+                        said out loud, never written down
+aqk note "..."          write a bruise into the journal
+aqk ratchet <name>      a debt registry for a declared gate: may only get shorter
+aqk blob                every guide as a single file
+```
+
+Exit codes: `0` pass, `1` below the level or a gate failed. Two exceptions, both deliberate:
+`learn` never fails a build — it reads transcripts and prints to the terminal only, writing
+nothing. And `--baseline` is an inspection, not a run: it always exits `0`, so combining it with
+`--run` or `--min` is refused outright rather than handing you a pipeline that cannot go red.
+
 ## What this looks like
 
 Someone else's project, three files, nothing configured:
@@ -123,6 +165,7 @@ The whole standard is one `.aqk.yml` file in the repository root:
 aqk: 1
 entry:  [AGENTS.md]        # what the agent reads first
 rules:  .aqk/rules         # where the standards live
+docs:   .aqk/docs          # where the guides live (optional; this is the default)
 gates:                     # what must pass — as commands, not as prose
   lint: "npm run lint"
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
@@ -196,7 +239,7 @@ Already using [pre-commit](https://pre-commit.com)? Three lines in the file you
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.7.0
+    rev: v0.8.0
     hooks:
       - id: aqk            # runs what the repository declares; blocks below AQK-1
       # - id: aqk-doctor   # read-only: the level and what is missing, blocks nothing
@@ -217,7 +260,7 @@ layer AQK adds.
 [![on the GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.7.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.8.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```

package/README.ru.md

@@ -64,6 +64,48 @@ flowchart LR
    обещание без кода возврата — просто предложение
 ```
 
+## Все команды
+
+```
+aqk doctor              где этот репозиторий и чего в нём не хватает
+aqk doctor --run        прогнать все гейты, объявленные в манифесте
+aqk doctor --run --since main    только то, что внёс диф
+aqk doctor --run --min 1         уронить конвейер ниже ступени
+aqk doctor --baseline   обязательный минимум проекта, подтверждённый прогоном
+
+aqk init                разложить комплект в существующий репозиторий
+aqk start               начать новый проект с комплектом
+aqk add <имя>           поставить один гейт из каталога
+aqk new <имя>           завести свой гейт по форме
+aqk find <текст>        найти гейт по намерению
+aqk why <имя>           какой отказ этот гейт поймал
+
+aqk prove               прогнать каждый объявленный гейт по его образцам:
+                        красный на красном, тишина на зелёном
+aqk report              форма отчёта, собранная прогоном
+aqk report --since main  ...и чем доказан этот диф, файл за файлом
+aqk badge               вписать значок уровня в README
+aqk badge --check       упасть, если значок расходится с прогоном
+
+aqk context             состояние репозитория одним блоком, для контекста агента:
+                        уровень, что красное сейчас, правила без арбитра, храповики
+aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
+                        против ≈375 — плата за то, чтобы агент не догадывался)
+aqk context --install   поставить хук SessionStart в .claude/settings.json
+                        (с --full ставится полный блок)
+
+aqk learn               кандидаты в правила из локальной переписки:
+                        что сказано вслух и не записано
+aqk note "..."          записать шишку в журнал
+aqk ratchet <имя>       реестр долга для объявленного гейта: может только укорачиваться
+aqk blob                все методички одним файлом
+```
+
+Коды возврата: `0` — прошло, `1` — ниже ступени или упал гейт. Два исключения, оба намеренные:
+`learn` не роняет сборку никогда — он читает переписку и печатает только в терминал, не записывая
+ничего. А `--baseline` — осмотр, а не прогон: он выходит с нулём всегда, поэтому вместе с `--run`
+или `--min` он теперь отказывает вслух, а не выдаёт конвейер, который не может покраснеть.
+
 ## Что это выглядит так
 
 Чужой проект, три файла, ничего не настроено:
@@ -124,6 +166,7 @@ Issue» — ничего не постится сама, только текст
 aqk: 1
 entry:  [AGENTS.md]        # что агент читает первым
 rules:  .aqk/rules         # где стандарты
+docs:   .aqk/docs          # где методички (необязательно, это и есть умолчание)
 gates:                     # что обязано пройти — командами, не словами
   lint: "npm run lint"
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
@@ -198,7 +241,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.6.0
+    rev: v0.8.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -217,7 +260,7 @@ repos:
 [![в GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.5.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.8.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```

package/kit/gates/_skip.sh

@@ -72,8 +72,68 @@ include_code() {
 # Сгенерированный файл не правят руками — предъявлять его размер или сложность человеку
 # бессмысленно и вредно: он выключит проверку целиком.
 # Опознаём по общепринятой шапке в первых пяти строках.
+# Регистр кириллицы `grep -i` сворачивает НЕ ВЕЗДЕ: на linux сворачивает, в Git Bash под
+# Windows — нет. Шапка `// СГЕНЕРИРОВАН` там не находилась никогда, и узнали мы об этом только
+# 2026-09-08, когда нарочный набор впервые прогнали на windows-задании. Это не регрессия правки,
+# а старая дыра, которую нечем было увидеть: на живых шести проектах таких шапок не было.
+# Поэтому кириллица перечисляется явно, а не доверяется флагу: три написания, которые бывают
+# на деле, — строчное в комментарии, с заглавной в начале фразы и капсом в баннере.
+GENERATED_MARKERS='@generated|do not edit|autogenerated|auto-generated|generated by|сгенерирован|Сгенерирован|СГЕНЕРИРОВАН'
+
+# Один файл: сгенерирован ли он. Осталось для тех, кто спрашивает про ОДИН файл
+# (gate-not-weakened сверяет строку находки, а не список путей).
 is_generated() {
-  head -5 "$1" 2>/dev/null | grep -qiE '@generated|do not edit|autogenerated|auto-generated|generated by|сгенерирован'
+  head -5 "$1" 2>/dev/null | grep -qiE "$GENERATED_MARKERS"
+}
+
+# СПИСОК файлов на stdin (по пути в строке) → тот же список без сгенерированных.
+#
+# ЗАЧЕМ ОТДЕЛЬНО ОТ is_generated. Цикл `while read; do is_generated; done` запускает ДВА
+# процесса на каждый файл — head и grep. Замерено 2026-09-08 на 748 файлах проекта uv:
+# обход и отбор 12 мс, подсчёт строк одним wc 37 мс, а этот цикл — 3862 мс. Сто крат от
+# всего остального, и ни микросекунды из них не потрачено на сравнение строк: платили за
+# fork+exec. Медленным был не язык — медленным было количество запусков.
+#
+# ПОЧЕМУ ИМЕННО grep, А НЕ awk. Соблазн был собрать всё одним awk с `nextfile`. Отвергнуто:
+# `nextfile` — расширение, а `tolower` на кириллице врёт в mawk и busybox-awk, и «сгенерирован»
+# перестал бы находиться там, где сейчас находится. Здесь ТОТ ЖЕ grep с ТЕМИ ЖЕ флагами, что
+# и в is_generated, — значит совпадение считается ровно так же, как раньше, и меняется только
+# число запусков. Равенство вывода проверено на шести чужих проектах: 0 расхождений.
+#
+# `-m1` останавливает grep на первом совпадении в файле, `/dev/null` заставляет его печатать
+# имя файла даже когда xargs передал ровно один путь.
+drop_generated() {
+  LIST=$(mktemp) || { cat; return; }
+  GEN=$(mktemp) || { rm -f "$LIST"; cat; return; }
+  cat > "$LIST"
+  # Пути передаются через НОЛЬ-разделитель: xargs по умолчанию рвёт по пробелам, и файл
+  # «src/my component.tsx» уехал бы в grep двумя несуществующими путями. Поймано нарочным
+  # набором до выпуска: старый цикл `while read` пробелы держал, и потерять это было нельзя.
+  tr '\n' '\0' < "$LIST" \
+    | xargs -0 -r grep -niE -m1 -e "$GENERATED_MARKERS" /dev/null 2>/dev/null \
+    | awk -v list="$LIST" '
+        # Строка вывода grep — «путь:номер:текст», и разобрать её по первому двоеточию нельзя:
+        # в пути тоже бывает двоеточие, а в тексте находки — тем более. Поэтому путь не
+        # угадывается, а СВЕРЯЕТСЯ со списком, который мы сами и передали: идём по двоеточиям
+        # слева направо, пока префикс не совпадёт с известным путём. Двоеточие в имени файла
+        # редкость, но «редко» и «никогда» — разные вещи, а тихо оставленный сгенерированный
+        # файл даёт находки на чужом коде.
+        BEGIN { while ((getline l < list) > 0) known[l] = 1 }
+        {
+          rest = $0; prefix = ""
+          while ((i = index(rest, ":")) > 0) {
+            prefix = prefix substr(rest, 1, i - 1)
+            rest = substr(rest, i + 1)
+            if (prefix in known) {
+              if (match(rest, /^[0-9]+:/) && substr(rest, 1, RLENGTH - 1) + 0 <= 5) print prefix
+              break
+            }
+            prefix = prefix ":"
+          }
+        }
+      ' | sort -u > "$GEN"
+  if [ -s "$GEN" ]; then grep -vxF -f "$GEN" "$LIST"; else cat "$LIST"; fi
+  rm -f "$LIST" "$GEN"
 }
 
 # Для grep: --exclude-dir на каждое имя. Образцы гейтов сюда не входят — см. own_samples_filter:

package/kit/gates/ci-not-hijackable/README.md

@@ -0,0 +1,56 @@
+# Конвейер не отдаёт чужому коду свои права и секреты
+
+**Намерение.** Конвейер выполняется с правами репозитория и с доступом к его секретам. Три
+способа отдать их постороннему живут не в коде, а в двадцати строках yaml:
+
+- **подвижная метка вместо SHA.** `uses: some/action@v1` — это указатель, который владелец
+  действия может перевести на другой код в любой момент, и он же перевёдется у всех, кто на
+  метку сослался;
+- **`pull_request_target` вместе с выкачиванием ветки автора PR.** Триггер даёт секреты
+  основного репозитория, а код берётся у постороннего;
+- **`permissions: write-all`** на весь рабочий поток вместо нужного права нужному заданию.
+
+Ни одну из трёх обычная проверка кода не увидит: это не код, это настройка.
+
+**Какой отказ это поймало.** Собственный. На момент заведения записи у комплекта было **13
+находок высокой строгости и 5 средней**, среди них десять действий, закреплённых меткой вместо
+SHA, `id-token: write` на уровне всего потока и пять вызовов `checkout`, оставляющих учётные
+данные в `.git/config`.
+
+**Почему порог именно такой.** Замер 2026-09-08 по шести настоящим репозиториям:
+
+| проект | High | Medium |
+|---|---|---|
+| `express` | 0 | 0 |
+| `flask` | 0 | 0 |
+| `uv` | 0 | 0 |
+| `httpx` | 4 | 4 |
+| `gin` | 18 | 0 |
+| `ripgrep` | 19 | 8 |
+
+Половина держит ноль. Порог взят с тех, кто его держит, а не выдуман: он достижим, и это
+доказано чужой практикой, а не нашим мнением.
+
+**Готовый аналог есть, и мы его зовём.** [`zizmor`](https://github.com/zizmorcore/zizmor) (MIT,
+6459 звёзд, статический разбор GitHub Actions). Его же гоняет `flask` отдельным заданием
+конвейера. Своего разбора yaml мы не писали. Обёртка отвечает за порог (`--min-severity medium`)
+и за то, чтобы «не проверено» не выдавалось за «чисто»: `--no-exit-codes` разводит «нашлись
+находки» и «инструмент не отработал», а отсутствие итоговой строки в выводе даёт код 2.
+
+**Образцы.** `red/` — рабочий поток с `pull_request_target`, выкачиванием ветки автора PR,
+`permissions: write-all` и незакреплённым действием. `green/` — тот же поток на `pull_request`,
+с правами только на чтение, действием по SHA и `persist-credentials: false`.
+
+**Чего НЕ ловит.**
+
+- **Только GitHub Actions.** GitLab CI, Jenkins, Buildkite не проверяются: zizmor их не читает.
+- **Не выполняет конвейер.** Разбор статический: он видит опасный уклад, но не видит, что делает
+  скрипт внутри `run:`. Скачивание и выполнение чужого кода строкой `curl … | sh` внутри шага —
+  предмет другой проверки, и её у нас нет.
+- **Не сторожит SHA после закрепления.** Закреплённое действие может оказаться заброшенным или
+  уязвимым; «закреплено» и «безопасно» — разные утверждения. Обновление закреплённых SHA — работа
+  для dependabot, а не для этой записи.
+- **Точечное гашение с причиной остаётся возможным.** `# zizmor: ignore[правило] причина` снимает
+  находку, и это осознанный уклад: наш собственный `gate-not-weakened` требует, чтобы подавление
+  было точечным и с названной причиной, а не порогом на весь файл. Мы сами пользуемся этим дважды
+  и обе причины написали вслух.

package/kit/gates/ci-not-hijackable/check.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env sh
+# Конфигурация конвейера не отдаёт чужому коду права и секреты.
+#
+# ЗАЧЕМ. Конвейер выполняется с правами репозитория и с доступом к его секретам. Три способа
+# отдать их постороннему живут не в коде, а в двадцати строках yaml: триггер `pull_request_target`
+# вместе с выкачиванием ветки автора PR; действие, закреплённое подвижной МЕТКОЙ, которую владелец
+# действия может перевести на другой код; права `write-all`, выданные всему рабочему потоку.
+# Ни одну из трёх обычная проверка кода не увидит: это не код, это настройка.
+#
+# Работу делает zizmor (MIT, 6459 звёзд, статический разбор GitHub Actions). Мы отвечаем за
+# порог и за то, чтобы «не проверено» не выдавалось за «чисто».
+#
+# ПОЧЕМУ ПОРОГ ИМЕННО ТАКОЙ. Замер 2026-09-08 по шести настоящим репозиториям: express, flask и
+# uv держат НОЛЬ находок высокой и средней строгости; gin (18), ripgrep (19) и httpx (4) — нет.
+# Порог взят с тех, кто его держит, а не выдуман: он достижим, и это доказано чужой практикой.
+# Мы сами на момент заведения записи были на неправильной стороне — 13 высоких и 5 средних.
+DIR="${1:-.}"
+WF="$DIR/.github/workflows"
+
+# Нет конвейера — нечего проверять. Это не успех и не провал, это отсутствие предмета.
+[ -d "$WF" ] || exit 0
+
+if ! command -v zizmor >/dev/null 2>&1; then
+  echo "не найден zizmor — эта проверка делегирована ему"
+  echo "  почини: pipx install zizmor  (или uv tool install zizmor)"
+  exit 2
+fi
+
+# --no-exit-codes разводит два разных события, которые иначе слиплись бы в один ненулевой код:
+# «нашлись находки» и «инструмент не отработал». Первое читается из вывода, второе — из кода.
+# NO_COLOR и снятие управляющих последовательностей — вместе, а не по отдельности. Внутри
+# GitHub Actions zizmor КРАСИТ вывод (там цвет поддержан), и итоговая строка начинается с
+# escape-последовательности: правило «^[0-9]+ findings» её не видит, и гейт объявлял, что формат
+# сменился. Локально этого не воспроизвести — вне конвейера цвет выключается сам. Поймано
+# прогоном в конвейере 2026-09-08; тот же класс уже записан у нас в scope.mjs: «цвет снимается ДО
+# поиска». NO_COLOR — соглашение, его может не знать следующая версия; sed — страховка, которая
+# в отличие от NO_COLOR ни от кого не зависит.
+ESC=$(printf '\033')
+OUT=$(NO_COLOR=1 zizmor --no-online-audits --no-exit-codes --min-severity medium --format plain "$WF" 2>&1 \
+      | sed "s/${ESC}\[[0-9;]*[a-zA-Z]//g")
+CODE=$?
+if [ "$CODE" -ne 0 ]; then
+  echo "zizmor не отработал (код $CODE) — проверка не состоялась, это не вердикт «чисто»"
+  printf '%s\n' "$OUT" | grep -iE "error:|panic|not found" | head -3 | sed 's/^/  /'
+  echo "  почини: прогони «zizmor .github/workflows» руками и посмотри, на чём он споткнулся"
+  exit 2
+fi
+
+# Итоговая строка — единственное место, где сказано, сколько чего нашлось. Её отсутствие значит,
+# что формат сменился; молчать об этом нельзя, иначе смена формата станет вечным зелёным.
+SUM=$(printf '%s\n' "$OUT" | grep -E "^(No findings to report|[0-9]+ findings)" | tail -1)
+if [ -z "$SUM" ]; then
+  echo "ответ zizmor не разобран: итоговой строки в нём нет"
+  # Печатаем то, что пришло на самом деле. Без этого причина видна только тому, у кого есть та
+  # же машина: первый отказ этой ветки случился в конвейере, а локально не воспроизводился, и
+  # разбирать пришлось догадками. Сообщение, не показывающее свой ввод, лечится вторым прогоном.
+  echo "  вот последнее, что он напечатал:"
+  printf '%s\n' "$OUT" | tail -3 | sed 's/^/    /'
+  echo "  почини: сверь версию zizmor с той, что названа в gate.yml"
+  exit 2
+fi
+
+case "$SUM" in
+  "No findings to report"*) exit 0 ;;
+esac
+
+printf '%s\n' "$OUT" | grep -E "^(error|warning)\[" | head -20
+N=$(printf '%s\n' "$OUT" | grep -cE "^(error|warning)\[")
+[ "$N" -gt 20 ] && echo "  … и ещё $((N - 20))"
+echo "  почини: закрепи действия по SHA вместо метки, сузь permissions до нужного задания,"
+echo "  замени pull_request_target на pull_request там, где выполняется код автора PR."
+echo "  подробности по каждой находке: https://docs.zizmor.sh/audits/"
+exit 1

package/kit/gates/ci-not-hijackable/gate.yml

@@ -0,0 +1,19 @@
+intent: конвейер не отдаёт чужому коду свои права и секреты
+intent_en: the pipeline does not hand its permissions and secrets to somebody else's code
+
+# Там, где конвейер есть. Без него отдавать нечего.
+trigger:
+  has_ci: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+# Программа, без которой запись не работает. По первому слову команды этого не видно: обёртка
+# начинается с `bash`. Версия названа: обёртка читает итоговую строку вывода zizmor, и смена
+# формата обязана быть видимой, а не тихой.
+requires: zizmor
+
+proof: incidents/README.md, 2026-09-08 «конвейер отдавал права по подвижной метке» — замер по
+  шести настоящим репозиториям показал, что express, flask и uv держат ноль находок высокой и
+  средней строгости, а gin (18), ripgrep (19) и httpx (4) нет; сам комплект на момент заведения
+  записи имел 13 высоких и 5 средних, включая десять действий, закреплённых меткой вместо SHA

package/kit/gates/ci-not-hijackable/green/.github/workflows/triage.yml

@@ -0,0 +1,19 @@
+name: разбор входящих
+
+# pull_request вместо pull_request_target: код автора PR выполняется без доступа к секретам
+# основного репозитория.
+on:
+  pull_request:
+    types: [opened]
+
+permissions:
+  contents: read
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+      - run: echo "разбор без прав на запись"

package/kit/gates/ci-not-hijackable/red/.github/workflows/triage.yml

@@ -0,0 +1,18 @@
+name: разбор входящих
+
+# pull_request_target выполняется в контексте ОСНОВНОЙ ветки и с доступом к секретам,
+# а код берётся из ветки автора PR. Классическая дыра.
+on:
+  pull_request_target:
+    types: [opened]
+
+permissions: write-all
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - run: npm install && npm run build

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

@@ -40,7 +40,7 @@ EXT_RE="$(printf '%s' "$COLOR_EXT" | tr ' ' '|')"
 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 \
+  | drop_generated \
   | LC_ALL=C sort \
   | xargs -r awk '
       # Блочные комментарии вырезаются ПО СОСТОЯНИЮ, а не построчно. Однострочный фильтр
@@ -63,7 +63,11 @@ HITS=$(find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null \
           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]|$)/)
+        # Хвост — «не буква, не цифра, не дефис», а не просто «не шестнадцатеричный символ».
+        # Якорь ссылки «#defining-entry-points» начинается с «#def», за которым идёт «i»: по
+        # прежнему правилу это был цвет. Замер 2026-09-08 по шести чужим репозиториям: в uv
+        # ложным оказалось именно это, в docs/js/extra.js.
+        if (line ~ /#[0-9a-fA-F]{8}([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F]{6}([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F]{3}([^0-9a-zA-Z_-]|$)/)
           print FILENAME ":" FNR ":" $0
       }
     ' 2>/dev/null \

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

@@ -2,3 +2,5 @@ export function Button({ children }: { children: React.ReactNode }) {
   // Цвет приходит из темы: перекрашивается вместе с ней.
   return <button className="bg-[var(--color-accent)] text-[var(--color-on-accent)]">{children}</button>;
 }
+
+const DOC_ANCHOR = "concepts/projects/#defining-entry-points";

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

@@ -30,7 +30,7 @@ TESTS="-name test -prune -o -name tests -prune -o -name spec -prune -o -name __t
 find "$DIR" $(skip_find "$DIR") $TESTS -type f \
      ! -name 'test_*' ! -name '*_test.*' ! -name '*.test.*' ! -name '*.spec.*' \
      -print 2>/dev/null | only_code | own_samples_filter "$DIR" \
-  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | drop_generated \
   | xargs -r awk -v MAX="$MAX" '
         # Один обход на все файлы: процесс на каждый файл дал 19 секунд на 4000 файлов.
         # Разметка вложена по природе: пять уровней тегов — это не сложная логика, а обычная
@@ -40,12 +40,11 @@ find "$DIR" $(skip_find "$DIR") $TESTS -type f \
         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)
-          }
+          # ширина отступа: табуляция считается за четыре пробела. Отступ берётся ОДНИМ
+          # match, а не посимвольным циклом с substr: цикл выделял новую строку на каждый
+          # символ отступа и стоил больше, чем весь остальной разбор. Замер 2026-09-08 на uv.
+          match($0, /^[ \t]*/); ind = substr($0, 1, RLENGTH)
+          n = gsub(/\t/, "", ind) * 4 + length(ind)
           depth = int(n / 4)
           if (depth > worst) { worst = depth; wl = FNR }
         }

package/kit/gates/duplicate-code/check.sh

@@ -30,7 +30,7 @@ TESTS="-name test -prune -o -name tests -prune -o -name spec -prune -o -name __t
 find "$DIR" $(skip_find "$DIR") $TESTS -type f \
      ! -name 'test_*' ! -name '*_test.*' ! -name '*.test.*' ! -name '*.spec.*' \
      -print 2>/dev/null | only_code | own_samples_filter "$DIR" \
-  | while IFS= read -r F; do is_generated "$F" || printf '%s\n' "$F"; done \
+  | drop_generated \
   | LC_ALL=C sort \
   | xargs -r env LC_ALL=C awk -v WIN="$WIN" '
       # Строка-объявление ввоза: `import`, `from … import`, `use …;`, путь в кавычках внутри
@@ -54,6 +54,10 @@ find "$DIR" $(skip_find "$DIR") $TESTS -type f \
         buf[++n] = line
         imp[n] = isimport(line)
         if (n >= WIN) {
+          # Ключ и признак «есть ли код» собираются ОДНИМ проходом по окну. Разнести их на
+          # два цикла выглядело ускорением — окно из одного ввоза отбрасывалось бы до сборки
+          # ключа. Замерено 2026-09-08 на uv: стало 2791 мс против 1770. Второй обход окна
+          # дороже, чем сборка ключа, которую он экономит; правка откачена по замеру.
           key = ""; code = 0
           for (i = n - WIN + 1; i <= n; i++) { key = key buf[i] "\x1e"; if (!imp[i]) code = 1 }
           if (!code) next                               # окно целиком из ввоза — не дубль

package/kit/gates/entry-links-exist/check.sh

@@ -7,7 +7,10 @@ MISS=0
 for MD in "$DIR"/*.md; do
   [ -f "$MD" ] || continue
   # вытащить цели ссылок вида [текст](путь)
-  TARGETS=$(sed -n 's/.*](\([^)]*\)).*/\1/p' "$MD")
+  # Строки со вставками в обратных кавычках чистятся ДО разбора: «`[name](url)`» — это пример
+  # оформления ссылки, а не ссылка. Замер 2026-09-08: в uv/STYLE.md именно так и было, и гейт
+  # требовал создать файл с именем «url».
+  TARGETS=$(sed 's/`[^`]*`//g' "$MD" | sed -n 's/.*](\([^)]*\)).*/\1/p')
   for T in $TARGETS; do
     # автоссылки бывают обёрнуты как <(https://...)> — искать http где угодно внутри,
     # не только в начале строки.

package/kit/gates/entry-links-exist/green/AGENTS.md

@@ -6,3 +6,5 @@
 Ссылка на страницу сайта документации: [руководство](tutorial/#install) — путь опубликованного
 сайта, а не файл на диске. Найдено замером по fastapi: `[installation guide](tutorial/#install-fastapi)`
 в README читалась как битая, хотя на сайте работает. Так ссылаются mkdocs, docusaurus и jekyll.
+
+Пример оформления ссылки: `[name](url)` — это пример, а не ссылка.

package/kit/gates/file-size-limit/check.sh

@@ -23,7 +23,7 @@ fi
 # не укладывался в две минуты.
 # 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 \
+  | drop_generated \
   | xargs -r wc -l 2>/dev/null \
   | awk '
       $2 == "total" { next }

package/kit/gates/secrets-not-in-code/check.sh

@@ -18,9 +18,22 @@ fi
 # Красный образец — намеренно сломанный код в репозитории. Сканирующий гейт обязан его
 # пропускать, иначе будет вечно краснеть на том, что сам же и положил. Исключение снимается,
 # когда проверяют сам образец: тогда каталог red и есть цель проверки.
-HITS=$(grep -rInE $(skip_grep "$DIR") -e \
-  '-----BEGIN [A-Z ]*PRIVATE KEY-----|(sk|pk)_(live|test)_[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|xox[baprs]-[A-Za-z0-9-]{10,}' \
-  "$DIR" 2>/dev/null | grep -v '/\.git/' | own_samples_filter "$DIR")
+# Два прохода, а не один, и разница между ними измерена. Живой облачный ключ — находка везде,
+# включая тестовые каталоги: он открывает настоящий счёт. Приватный КЛЮЧ в тестовых данных —
+# норма: любой проект с проверками TLS кладёт туда сертификат, и Go так делает по соглашению.
+# Замер 2026-09-08 по шести чужим репозиториям: gin краснел на testdata/certificate/key.pem,
+# положенном туда намеренно. Гейт, краснеющий на нормальном укладе, выключают в первый день —
+# и тогда он не ловит уже НИЧЕГО, включая настоящий ключ.
+TOKENS='(sk|pk)_(live|test)_[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|xox[baprs]-[A-Za-z0-9-]{10,}'
+PRIVKEY='-----BEGIN [A-Z ]*PRIVATE KEY-----'
+# Каталоги образцов: только те, чьё имя не оставляет сомнений. `data` или `assets` сюда не
+# входят — там ключ вполне может оказаться настоящим.
+FIXTURES='(^|/)(testdata|fixtures|__fixtures__|test|tests|spec|__tests__)/'
+
+HITS=$(
+  { grep -rInE $(skip_grep "$DIR") -e "$TOKENS" "$DIR" 2>/dev/null
+    grep -rInE $(skip_grep "$DIR") -e "$PRIVKEY" "$DIR" 2>/dev/null | grep -vE "$FIXTURES"
+  } | grep -v '/\.git/' | own_samples_filter "$DIR" | sort -u)
 if [ -n "$HITS" ]; then
   echo "$HITS" | cut -c1-160
   echo "  почини: убери значение из файла, положи его в переменную окружения и отзови старый ключ."

package/kit/gates/secrets-not-in-code/green/testdata/certificate/key.pem

@@ -0,0 +1,3 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEowIBAAKCAQEA0Z3VS5JJcds3xfn/ygWyF32rHzS0AAAAAAAAAAAAAAAAAAAA
+-----END RSA PRIVATE KEY-----

package/kit/gates/todo-without-task/check.sh

@@ -21,7 +21,7 @@ fi
 # названием и на собственном шаблоне поиска — на том, что дефектом не является.
 # Сами эти слова здесь не пишем: гейт нашёл бы себя. Проверено — находил.
 HITS=$(grep -rnE $(skip_grep "$DIR") $(include_code) \
-  '(#|//|/\*|--|<!--)[^"'"'"']*(^|[^A-Za-z])(TODO|FIXME|HACK|XXX)([^A-Za-z]|$)' "$DIR" 2>/dev/null | own_samples_filter "$DIR")
+  '(#|//|/\*|--|<!--)[^"'"'"']*(^|[^A-Za-z0-9_])(TODO|FIXME|HACK|XXX)([^A-Za-z0-9_]|$)' "$DIR" 2>/dev/null | own_samples_filter "$DIR")
 if [ -n "$HITS" ]; then
   echo "$HITS"
   echo "  почини: заведи задачу в очереди работ, маркер убери."

package/kit/gates/todo-without-task/green/app.py

@@ -0,0 +1 @@
+UV_TEST_XXX = "имя переменной, а не маркер долга"

package/llms.txt

@@ -23,11 +23,32 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
   the other 36 are named as a number, not hidden)
 - Fail a pipeline below a level or on a failed gate: `npx agent-quality-kit doctor --run --min 1`
 - Show only what a diff introduced, so a legacy repo is usable from day one: `doctor --run --since main`
+- Prove the gates actually catch defects: `npx agent-quality-kit prove` — every *provable* gate is
+  run against its own red and green sample and must go red on the first and stay quiet on the
+  second. A gate with no samples, with samples written for another recipe, or whose command takes
+  no directory is reported as unprovable and named; the verdict is "nothing proven is broken, and
+  at least one gate is proven". Level AQK-2 and the badge depend on this, not on the presence of
+  files
+- See what proves a diff, file by file: `npx agent-quality-kit report --since main` — each changed
+  code file is named by a check, walked past in silence, or touched by nothing at all, plus a
+  fingerprint over the base, the commands and the file contents
+- Put the repository state into the agent's context instead of hoping it reads the files:
+  `npx agent-quality-kit context` — level, what is red right now, how many rules no machine
+  enforces, what the ratchets hold. Where it does not know, it says so: a run that never happened
+  is reported as unknown, never as clean. `context --install` writes a `SessionStart` hook into
+  `.claude/settings.json` (Claude Code only; the rest of the kit stays vendor-neutral). Measured:
+  the block is ~375 tokens, and carries what a file cannot — what changed today. `context --full`
+  adds the command map and the rulebook verbatim (~7000 tokens): a deliberate trade, chosen by
+  the owner after the objection about long inputs, on the grounds that an agent reads files
+  poorly and the tokens are the price of it not guessing
+- See what you told the agent and never wrote down: `npx agent-quality-kit learn` — reads Claude Code
+  transcripts for this project on this machine and prints rule candidates missing from the entry
+  point. Current project only, terminal only, writes nothing, always exits 0
 - Exit codes: 0 pass, 1 below the level or a gate failed
 - As a pre-commit hook: `repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit` with
   `id: aqk` (blocking), `aqk-doctor` (read-only) or `aqk-baseline`. pre-commit installs the
   package itself; there are no dependencies to pull in.
-- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.7.0` with `min: 1`
+- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.8.0` with `min: 1`
   (https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ## What makes it different