agent-quality-kit 0.12.0 → 0.13.0

package/README.md

@@ -102,11 +102,12 @@ 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
+                        level, what is red now, rules nobody enforces, ratchets,
+                        the next three steps with commands, and when to run what
 aqk vitals              is what the kit runs on wired up: gate tools, hooks, freshness
 aqk doctor --run --brief  one line on success, the whole run on failure — for hooks
 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)
+                        tokens against ~500: 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)
 
@@ -347,7 +348,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.12.0
+    rev: v0.13.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
@@ -368,7 +369,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.12.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.13.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -456,6 +457,27 @@ Otherwise a gate that cannot fail the build looks exactly like one that can, and
 is in `advisory:` only on the day it goes red. Red ones are additionally named by name in the
 summary: an advisory gate everyone forgot about is a switched-off check.
 
+**A gate that needs a live stack** (a cost check against a seeded database, e2e) goes into a group,
+and a fast run skips the group:
+
+```yaml
+groups:
+  stack: [cost, e2e]
+```
+
+```bash
+aqk doctor --run --skip stack     # everything except the stack
+aqk doctor --run --only stack     # only the stack, on the stand
+```
+
+Skipped gates are named in the output and written to the run report as "not run" — not as green.
+An unknown name after `--skip` is a refusal: a typo must not quietly mean "skipped nothing".
+
+**Independent gates can run in parallel:** `aqk doctor --run --jobs 4`. Off by default, on
+purpose: two gates writing into the same folder (`npm run build` twice into `dist/`) would fail
+at random when run together, and a flaky red is worse than a slow one. Output keeps the declared
+order. On this repository, 30 gates: about 110 s one by one, 68 s with `--jobs 3`.
+
 ## When a bug slips past the guards
 
 ```bash

package/README.ru.md

@@ -104,11 +104,12 @@ aqk badge               вписать значок уровня в README
 aqk badge --check       упасть, если значок расходится с прогоном
 
 aqk context             состояние репозитория одним блоком, для контекста агента:
-                        уровень, что красное сейчас, правила без арбитра, храповики
+                        уровень, что красное сейчас, правила без арбитра, храповики,
+                        три следующих шага с командами и когда что запускать
 aqk vitals              подключено ли то, чем комплект работает: инструменты, хуки, свежесть
 aqk doctor --run --brief  одна строка на успехе, весь прогон при провале — для хуков
 aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
-                        против ≈375 — плата за то, чтобы агент не догадывался)
+                        против ≈500 — плата за то, чтобы агент не догадывался)
 aqk context --install   поставить хук SessionStart в .claude/settings.json
                         (с --full ставится полный блок)
 
@@ -350,7 +351,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.12.0
+    rev: v0.13.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -369,7 +370,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.12.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.13.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -455,6 +456,27 @@ advisory:
 списке `advisory:` человек узнаёт только в день, когда гейт покраснел. Покрасневшие вдобавок
 названы в сводке поимённо: совещательный гейт, о котором забыли, — это выключенная проверка.
 
+**Гейт, которому нужен живой стенд** (цена на засеянной базе, e2e), кладётся в группу, и быстрый
+прогон группу пропускает:
+
+```yaml
+groups:
+  stack: [cost, e2e]
+```
+
+```bash
+aqk doctor --run --skip stack     # всё, кроме стенда
+aqk doctor --run --only stack     # только стенд, на стенде
+```
+
+Пропущенные названы в выводе и записаны в отчёт прогона как «не запускались» — не как зелёные.
+Неизвестное имя после `--skip` — отказ: опечатка не должна тихо означать «пропустили ничего».
+
+**Независимые гейты можно гнать параллельно:** `aqk doctor --run --jobs 4`. По умолчанию
+выключено намеренно: два гейта, пишущие в одну папку (`npm run build` дважды в `dist/`), вместе
+падали бы через раз, а плавающее красное хуже медленного. Вывод — в порядке объявления. На этом
+репозитории, 30 гейтов: около 110 с по одному, 68 с с `--jobs 3`.
+
 
 ## Поймал ошибку, которую не поймал сторож
 

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

@@ -17,3 +17,7 @@ recipes:
   typescript: eslint --no-config-lookup --ignore-pattern 'gates/*/red/**' --ignore-pattern 'gates/*/green/**' --rule '{"complexity":["error",10],"max-depth":["error",4]}' {dir}
 
 proof: incidents/README.md — «2026-08-27 ревизия гейтов», п. 6: 75 функций сложнее нормы, худшая с 29 ветвлениями
+
+# Правило Biome под эту запись — для сверки `covers:` (рецептов под Biome нет). Имя сверено по
+# схеме конфигурации Biome 2.5.12, а не по памяти.
+biome_rules: complexity/noExcessiveCognitiveComplexity

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

@@ -27,3 +27,7 @@ recipes:
 samples_for: python
 
 proof: incidents/README.md — «2026-08-27 ревизия гейтов», п. 5: мёртвые функции бэкенда не искал никто, реестр на 148 записей
+
+# Правило Biome под эту запись — для сверки `covers:` (рецептов под Biome нет). Имя сверено по
+# схеме конфигурации Biome 2.5.12, а не по памяти.
+biome_rules: correctness/noUnusedVariables, correctness/noUnusedImports

package/kit/gates/env-secrets-not-committed/README.md

@@ -0,0 +1,73 @@
+# Пароли из .env не лежат в git
+
+**Намерение.** Файл окружения с настоящими значениями, попав в git, раздаёт пароли и ключи
+каждому, кто склонировал репозиторий, — и из истории их уже не вычистить: ключ считается
+скомпрометированным, его остаётся только сменить.
+
+**Почему не «любой `.env` в git — брак».** Так было бы проще, и так было бы неверно. Сверено по
+первоисточникам 2026-09-11:
+
+- dotenv: «Should I commit my `.env` file? No. Unless you encrypt it with dotenvx. Then we
+  recommend you do» — зашифрованный файл коммитят намеренно;
+- Next.js: «`.env.test` file should be included in your repository, but `.env.test.local`
+  shouldn't, as `.env*.local` are intended to be ignored through `.gitignore`»;
+- Vite: «`.env.*.local` files are local-only and can contain sensitive variables. You should add
+  `*.local` to your `.gitignore`» — про обычный `.env` не сказано ничего, и во многих проектах
+  его коммитят с публичными настройками.
+
+Поэтому правил два:
+
+1. **`.env.local` и `.env.*.local` в git — находка всегда.** Здесь все сходятся: «local» — только
+   для этой машины, что бы в файле ни лежало.
+2. **Остальные `.env*` в git — находка, если внутри ключ-секрет с настоящим значением:** имя
+   содержит `PASSWORD`, `SECRET`, `TOKEN`, `API_KEY`, `PRIVATE_KEY`, `ACCESS_KEY`, `CREDENTIAL`,
+   либо значение — адрес с паролем (`схема://пользователь:пароль@хост`).
+
+**Значение секрета проверка не печатает.** Вывод гейта попадает в лог конвейера; напечатать
+пароль значило бы завести вторую утечку ради сообщения о первой. Называются файл, строка, ключ.
+
+**Готовый аналог — есть частично, и мы его замерили.** Закоммиченный `.env` с тремя секретами и
+`.env.local` с токеном (2026-09-11):
+
+| | пароль, придуманный человеком | случайная строка | ключ с форматом поставщика | `.env.local` |
+|---|---|---|---|---|
+| наш `secrets-not-in-code` | не видит | не видит | видит | не видит |
+| `gitleaks` 8.30.1 | не видит | видит (по энтропии) | видит | не видит |
+| [`detect-secrets`](https://github.com/Yelp/detect-secrets) 1.5.0 | видит | видит | видит | не видит |
+| эта запись | видит | видит | видит, если имя ключа говорящее | видит |
+
+`detect-secrets` сильнее нас во втором правиле: он читает имена ключей во всех файлах, а не
+только в `.env`. Если он у вас уже стоит в pre-commit с файлом-базой — второе правило закрыто
+им, первое остаётся за этой записью. Родным рецептом он не стал: в конвейере ему нужна база
+(`.secrets.baseline`), а запись ставится одной командой.
+
+**Чего НЕ ловит.**
+
+- **Секрет под неговорящим именем.** `STRIPE=…`, `DB=…`, `X_CONF=…` — ключ не называет себя
+  секретом. Такое ловит только сканер по формату значения (`secrets-not-in-code`, `gitleaks`).
+- **Короткий пароль.** Значения короче восьми знаков пропускаются: `dev`, `x`, `1234` в `.env`
+  для локального стенда встречаются куда чаще настоящих паролей такой длины.
+- **Пароль, совпавший со значением по умолчанию.** `postgres`, `root`, `admin`, `guest`,
+  `minioadmin` — стоят в каждом docker-compose для разработки, и считать их утечкой значит
+  краснеть на каждом втором проекте. Если такой пароль стоит на проде, это другая беда.
+- **Публичные переменные сборки.** `NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, `EXPO_PUBLIC_`,
+  `NUXT_PUBLIC_`, `GATSBY_` уезжают в браузер по устройству — секретом они быть не могут.
+- **Шаблоны и тестовые данные.** `.env.example`, `.env.sample`, `.env.template`, `.env.dist`,
+  `.env.test`, а также каталоги `templates/`, `examples/`, `fixtures/`, `testdata/`.
+- **`.env.local` в каталоге тестов и демо.** `tests/`, `test/`, `__tests__/`, `spec/`,
+  `playgrounds/`, `demos/` — там это фикстура: библиотека показывает или проверяет, что умеет
+  читать такой файл. Замер: оба ложных срабатывания были ровно такими. Пароль внутри тестового
+  `.env` при этом ловится — утечка в тестах остаётся утечкой.
+- **Историю.** Проверяется то, что лежит в git сейчас. Файл, удалённый из индекса, из истории не
+  исчез — это лечится сменой ключа, а не проверкой.
+- **Файл, который лежит на диске и в `.gitignore`.** Это норма, а не находка: проверка спрашивает
+  git, а не диск. (Ошибка соседа, agentlint, ровно в этом: он проверяет диск и кричит
+  «закоммичен» про файл из `.gitignore`.)
+
+**Образцы.** Настоящего git внутри каталога комплекта взять неоткуда, поэтому образцы кладут
+список отслеживаемых файлов в `.aqk-tracked`; в живом проекте его не бывает и спрашивается git.
+`red/` — `.env` с человеческими паролями (без формата и энтропии — ровно то, что сканеры
+пропускают) и `.env.local` в индексе. `green/` — `.env` с публичными переменными сборки,
+заглушками, ссылками `${…}`, паролями по умолчанию для локального стенда; `.env.production`,
+зашифрованный `dotenvx`; `.env.test` с тестовым паролем; `.env.local` в `tests/`; `.env` в
+`tests/fixtures/` и `templates/`. На всём этом арбитр обязан молчать.

package/kit/gates/env-secrets-not-committed/check.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env sh
+# Файл окружения с настоящими значениями лежит в git: пароль, токен или ключ разошёлся со всеми
+# клонами — и из истории его уже не вычистить.
+#
+# ЗАЧЕМ СВОЯ ПРОВЕРКА, если есть сканеры секретов. Замер 2026-09-11 на закоммиченном `.env`
+# (research/competitors/agentlint.md): наш `secrets-not-in-code` узнаёт секрет только по формату
+# поставщика (`sk_live_…`); `gitleaks` 8.30.1 — по формату и по ЭНТРОПИИ: случайную строку
+# (`wN7rQ2vLx9Tp`, энтропия 3,6) он ловит, а пароль, придуманный человеком (`Sup3rS3cret2024`,
+# `hunter2hunter2`), пропускает. У такого пароля нет ни формата, ни энтропии — его узнают
+# только по ИМЕНИ ключа. `detect-secrets` 1.5.0 имя ключа читает и оба ловит, но `.env.local`
+# не видит вовсе: такой файл личный по определению, что бы в нём ни лежало.
+#
+# ДВА ПРАВИЛА, и второе не шире, чем нужно.
+#   1. `.env.local` и `.env.*.local` в git — находка всегда. Документация Vite: «.env.*.local
+#      files are local-only and can contain sensitive variables. You should add `*.local` to your
+#      `.gitignore`»; Next.js: «.env*.local are intended to be ignored through .gitignore».
+#   2. Остальные `.env*` в git — находка, только если внутри ключ-секрет с НАСТОЯЩИМ значением.
+#      Не любой `.env`: Next.js велит коммитить `.env.test`, во многих проектах на Vite
+#      коммитят `.env` с публичными настройками, а зашифрованный `dotenvx` файл коммитить
+#      рекомендует сам dotenv («Should I commit my .env file? No. Unless you encrypt it with
+#      dotenvx»). Проверка «файл есть в git» без чтения значений врала бы на всех троих.
+#
+# ЗНАЧЕНИЕ НЕ ПЕЧАТАЕТСЯ. Вывод гейта попадает в лог конвейера; напечатать пароль значило бы
+# завести вторую утечку ради сообщения о первой. Называются файл, строка и имя ключа.
+DIR="${1:-.}"
+# Существование файла проверяется ДО `.`: под dash неудачный `.` завершает скрипт немедленно, и
+# запасная ветка не выполняется никогда (замерено 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"
+if [ "${AQK_SKIP_READY:-}" != 1 ]; then
+  echo "_skip.sh есть, но обход не собрался — проверка НЕ СОСТОЯЛАСЬ, а не прошла"
+  echo "  почини: замени kit/gates/_skip.sh целым файлом из каталога"
+  exit 2
+fi
+
+# Образцы (gates.sh) несут список отслеживаемых файлов в `.aqk-tracked`: вложенный .git внутри
+# каталога комплекта создал бы embedded-репозиторий. В настоящем проекте спрашиваем git.
+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: иначе путь с не-ASCII приходит в кавычках, и якорь «$» не совпадает.
+  LIST=$(cd "$DIR" && git -c core.quotePath=false ls-files 2>/dev/null)
+fi
+LIST=$(printf '%s\n' "$LIST" | tr -d '\r')
+
+# Кандидаты — файлы окружения по имени. Шаблоны (`.example`, `.sample`, `.template`, `.dist`) и
+# каталоги заготовок и тестовых данных — не утечка: их кладут намеренно, чтобы скопировать.
+# Замер на соседней записи: больше половины совпадений по имени были такими.
+ENVS=$(printf '%s\n' "$LIST" \
+  | grep -E '(^|/)\.env(\.[A-Za-z0-9_.-]+)?$' \
+  | grep -vE '\.(example|sample|template|dist|schema)$' \
+  | grep -vE '(^|/)(templates?|examples?|samples?|fixtures?|__fixtures__|testdata|test_data|dist)/' \
+  | grep -vE '(^|/)kit/gates/[^/]+/(red|green)(/|$)' \
+  || true)
+if command -v own_samples_filter >/dev/null 2>&1 || type own_samples_filter >/dev/null 2>&1; then
+  ENVS=$(printf '%s\n' "$ENVS" | own_samples_filter "$DIR" | grep -v '^$' || true)
+fi
+[ -z "$ENVS" ] && exit 0
+
+# Секрет узнаётся по имени ключа и по значению. Ложные — это то, что в git класть МОЖНО:
+#   · публичные по устройству переменные сборки (`NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, …) —
+#     они и так уезжают в браузер;
+#   · пустое значение, ссылка `${VAR}`/`$VAR`, заглушка (`changeme`, `<…>`, `your_…`);
+#   · значения по умолчанию для локального стенда (`postgres`, `root`, `admin`, `guest`…) —
+#     тот же пароль стоит в каждом docker-compose для разработки;
+#   · зашифрованное `dotenvx` (`encrypted:…`); числа и логические (`TOKEN_TTL=86400`);
+#   · короче восьми знаков — настоящий пароль короче почти не бывает, а «dev» и «x» бывают.
+# Интервалы `{n}` в регулярках НЕ использовать: mawk из node:22-slim их не понимает, и две
+# записи каталога однажды молчали на своих красных образцах ровно из-за этого.
+# Построчно, а не `for F in $ENVS`: путь с пробелом развалился бы на части. Цикл в конвейере
+# идёт в подоболочке, поэтому находки собираются в вывод, а не в переменную-флаг.
+OUT=$(printf '%s\n' "$ENVS" | while IFS= read -r F; do
+  BASE=${F##*/}
+  case "$BASE" in
+    .env.local|.env.*.local)
+      # В каталоге тестов и демо-приложений `.env.local` — фикстура: библиотека показывает или
+      # проверяет, что умеет его читать. Замер 2026-09-11: `tests/.env.local` у motdotla/dotenv
+      # и `playgrounds/*/.env.local` у инструментов для Next.js — обе находки ложные. Правило 2
+      # (настоящий пароль внутри) там действует: утечка в тестах остаётся утечкой.
+      if printf '%s\n' "$F" | grep -qE '(^|/)(tests?|__tests__|specs?|playgrounds?|demos?)/'; then :; else
+        echo "$F: личный файл окружения отслеживается git — «.local» по определению только для этой машины"
+        continue
+      fi ;;
+    # Next.js: «.env.test file should be included in your repository».
+    .env.test|.env.testing) continue ;;
+  esac
+  [ -f "$DIR/$F" ] || continue
+  HITS=$(tr -d '\r' < "$DIR/$F" | awk '
+    function placeholder(v, l) {
+      l = tolower(v)
+      if (l == "") return 1
+      if (l ~ /^encrypted:/) return 1
+      if (l ~ /^\$/) return 1
+      if (l ~ /^<.*>$/) return 1
+      if (l ~ /^(your|example|dummy|placeholder|replace|change)[-_ a-z0-9]*$/) return 1
+      if (l ~ /^(changeme|todo|none|null|secret|password|test|dev|development|local|localhost)$/) return 1
+      if (l ~ /^(postgres|mysql|root|admin|guest|redis|minioadmin|user|pass)$/) return 1
+      if (l ~ /^x+$/ || l ~ /^\*+$/ || l ~ /^\.+$/) return 1
+      if (l ~ /^[0-9]+$/ || l ~ /^(true|false|yes|no|on|off)$/) return 1
+      return 0
+    }
+    /^[ \t]*#/ || /^[ \t]*$/ { next }
+    {
+      line = $0
+      sub(/^[ \t]*export[ \t]+/, "", line)
+      eq = index(line, "=")
+      if (eq == 0) next
+      key = substr(line, 1, eq - 1); val = substr(line, eq + 1)
+      gsub(/^[ \t]+|[ \t]+$/, "", key); gsub(/^[ \t]+|[ \t]+$/, "", val)
+      sub(/[ \t]+#.*$/, "", val)
+      if (val ~ /^".*"$/ || val ~ /^\047.*\047$/) val = substr(val, 2, length(val) - 2)
+      k = toupper(key)
+      if (k ~ /^(NEXT_PUBLIC_|VITE_|REACT_APP_|PUBLIC_|EXPO_PUBLIC_|NUXT_PUBLIC_|GATSBY_)/) next
+      # Пароль внутри адреса: схема://пользователь:пароль@хост.
+      if (match(val, /:\/\/[^\/:@ ]+:[^\/@ ]+@/)) {
+        cred = substr(val, RSTART + 3, RLENGTH - 4); pw = substr(cred, index(cred, ":") + 1)
+        if (!placeholder(pw)) { print NR ": " key " — пароль внутри адреса"; next }
+      }
+      if (k !~ /(PASSWORD|PASSWD|SECRET|TOKEN|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY|CREDENTIAL)/) next
+      if (placeholder(val) || length(val) < 8) next
+      print NR ": " key " — похоже на настоящее значение"
+    }')
+  [ -n "$HITS" ] && printf '%s\n' "$HITS" | sed "s|^|$F:|; s|\$| (само значение не печатаю)|"
+done)
+
+[ -z "$OUT" ] && exit 0
+printf '%s\n' "$OUT"
+echo "  почини: git rm --cached <файл> и добавь его в .gitignore; в git оставь .env.example с пустыми"
+echo "  значениями. И смени эти пароли и ключи: из истории git их уже не вычистить."
+exit 1

package/kit/gates/env-secrets-not-committed/gate.yml

@@ -0,0 +1,21 @@
+intent: личные файлы окружения и настоящие пароли из .env не попадают в git
+intent_en: personal environment files and real passwords from .env do not end up in git
+
+# Только там, где файлом окружения пользуются: признак считает `.env`, `.env.example`,
+# `.env.sample` в корне. Проекту без них запись показывать незачем.
+trigger:
+  has_env: true
+
+# Переносимая проверка — единственный рецепт, и это решение, а не пробел. Готовый `detect-secrets`
+# ловит пароли по имени ключа, но не видит `.env.local` (личный по определению, что бы в нём ни
+# лежало) и требует файла-базы для работы в конвейере; `gitleaks` пропускает человеческие пароли.
+# Замер и таблица — в README записи.
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+tool: https://github.com/Yelp/detect-secrets
+
+proof: incidents/README.md, 2026-09-11 «пароль из .env, которого не видит ни один сканер» —
+  пять репозиториев с закоммиченным .env.production.local из поиска кода GitHub: гейт краснеет на
+  всех пяти, четыре находки настоящие; контрольные — одиннадцать репозиториев, ложных после
+  исключения ноль

package/kit/gates/env-secrets-not-committed/green/.aqk-tracked

@@ -0,0 +1,10 @@
+README.md
+.env
+.env.example
+.env.production
+.env.test
+tests/fixtures/.env
+templates/.env
+src/app.py
+tests/.env.local
+playgrounds/app/.env.local

package/kit/gates/env-secrets-not-committed/green/.env

@@ -0,0 +1,10 @@
+# Значения по умолчанию, которые коммитят намеренно: секретов здесь нет
+APP_ENV=development
+VITE_API_KEY=pk_demo_public_1234567
+DB_PASSWORD=
+API_TOKEN=changeme
+SECRET_KEY=${APP_SECRET}
+REDIS_PASSWORD=<set-in-vault>
+TOKEN_TTL_SECONDS=86400000
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/app
+RABBITMQ_URL=amqp://guest:guest@localhost:5672/

package/kit/gates/env-secrets-not-committed/green/.env.production

@@ -0,0 +1,5 @@
+#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
+#/            public-key encryption for .env files          /
+#/----------------------------------------------------------/
+DOTENV_PUBLIC_KEY_PRODUCTION="03f8b0c2d1e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1"
+DB_PASSWORD="encrypted:BG8M6U+GKJGwpGA42ml2erb9+T2NBX6Z2JkBLynDy21poz0UfF5aPxCgRbIyhnQFdWKd0C9GZ7lM5PeL86xghoMcWvvPpkyQ0yaD2pZ64RzoxFGB1lTZYlEgQOxTDJnWxODHfuQcFY10uA=="

package/kit/gates/env-secrets-not-committed/green/.env.test

@@ -0,0 +1,2 @@
+# Next.js: .env.test положено держать в репозитории — значения для тестов
+DB_PASSWORD=testonly-9Xk2mQ

package/kit/gates/env-secrets-not-committed/red/.aqk-tracked

@@ -0,0 +1,5 @@
+README.md
+.env
+.env.local
+.env.example
+src/app.py

package/kit/gates/env-secrets-not-committed/red/.env

@@ -0,0 +1,7 @@
+# Настройки прода, закоммиченные по ошибке. Пароли — человеческие, без узнаваемого формата:
+# ровно то, что сканеры по форме и энтропии пропускают.
+APP_ENV=production
+DB_HOST=db.internal
+DB_PASSWORD=Sup3rS3cret2024
+DATABASE_URL=postgres://app:Winter2024Pass@db.internal:5432/app
+export JWT_SECRET="hunter2hunter2"

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

@@ -27,3 +27,7 @@ samples_for: python
 
 proof: incidents/README.md, 2026-09-07 «замер по пяти стекам вынес приговор пяти записям» —
   434 находки переносимой проверки на пяти чужих репозиториях, настоящих ноль
+
+# Правило Biome под эту запись — для сверки `covers:` (рецептов под Biome нет). Имя сверено по
+# схеме конфигурации Biome 2.5.12, а не по памяти.
+biome_rules: suspicious/noConsole

package/kit/gates/swallowed-error/gate.yml

@@ -26,3 +26,7 @@ proof: incidents/README.md, 2026-09-07 «замер по пяти стекам
   переносимая версия дала 46 находок на пяти чужих репозиториях, настоящими оказались только
   пустые `catch {}` в zod; весь питоновский класс `except ImportError: pass` и растовый
   `let _ = write(..)?` были ложными
+
+# Правило Biome под эту запись — для сверки `covers:` (рецептов под Biome нет). Имя сверено по
+# схеме конфигурации Biome 2.5.12, а не по памяти.
+biome_rules: suspicious/noEmptyBlockStatements

package/kit/gates/todo-without-task/gate.yml

@@ -16,3 +16,7 @@ recipes:
   typescript: eslint --no-config-lookup --ignore-pattern 'gates/*/red/**' --ignore-pattern 'gates/*/green/**' --rule '{"no-warning-comments":["error",{"terms":["todo","fixme","hack","xxx"]}]}' {dir}
 
 proof: incidents/README.md — «2026-08-25 разбор 1069 коммитов»: 416 коммитов из 1069 оказались стабилизацией уже выкаченного
+
+# У Biome правила под TODO нет вовсе — сверено по схеме конфигурации Biome 2.5.12. Заявка
+# «lint (biome) держит эту запись» поэтому заведомо неверна, и doctor так и говорит.
+biome_rules: none

package/llms.txt

@@ -40,7 +40,9 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
   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`
+  the block is ~500 tokens, and carries what a file cannot — what changed today, the next three
+  steps with ready commands, and when to run which command (before a commit, after changing a
+  check, when a check is in the way). `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
@@ -70,7 +72,7 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
   the files `init` writes are owned by root, so you cannot edit your own manifest. Debian-based
   on purpose: the gates are `sh`, `grep`, `awk`, `find` — under alpine's busybox they behave
   differently, and an image where the gates behave differently is worse than no image
-- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.12.0` with `min: 1`
+- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.13.0` with `min: 1`
   (https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ## What makes it different

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Turns the rules an agent is supposed to follow into commands with exit codes, and reports which of them actually run. Zero dependencies.",
   "type": "module",
   "bin": {

package/tool/commands/badge.mjs

@@ -45,7 +45,7 @@ async function cmdBadge(args = []) {
   // Прогон, а не манифест. Значок при красном гейте — это и есть недоказанное утверждение.
   const gates = declaredGates(man);
   if (gates.length) {
-    const run = runGates(man);
+    const run = await runGates(man);
     if (run.failed) {
       const red = run.results.filter((r) => !r.ok).map((r) => r.name).join(", ");
       die(`\n  ${L.badge.redGates(run.failed, red)}\n`);

package/tool/commands/context.mjs

@@ -23,8 +23,12 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
-import { CWD, TARGET_DIR, SELF, c, exists, commandRows } from "../lib/core.mjs";
-import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { CWD, TARGET_DIR, SELF, c, exists, commandRows, preCommitHook } from "../lib/core.mjs";
+import { readManifest, assessLevel, coversOf } from "../lib/manifest.mjs";
+import { detectFacts, readCatalog } from "../lib/repo.mjs";
+import { catalogBuckets, startWith, blindAdvice } from "../lib/advice.mjs";
+import { proposeGates, readAdoptFiles } from "../lib/adopt.mjs";
+import { declaredGates } from "../lib/run.mjs";
 import { probeStatus } from "./probe.mjs";
 import { L } from "../i18n/index.mjs";
 
@@ -33,6 +37,23 @@ import { L } from "../i18n/index.mjs";
 const MAX_RED = 5;
 const MAX_RATCHETS = 3;
 
+// ЧТО ДЕЛАТЬ ДАЛЬШЕ — не больше трёх шагов, по убыванию того, насколько это ФАКТ о проекте:
+//   1. объявить проверки, которые у проекта уже есть: дешевле всего, и это его собственное;
+//   2. классы брака, которые проба подсадила в ЕГО файлы и ЕГО проверки не поймали;
+//   3. «начните с этих трёх» из каталога.
+// Класс, названный пробой, в третьем списке не повторяется: один шаг, а не два. Остаток —
+// числом: молчание о нём прочиталось бы как «больше делать нечего».
+function nextSteps({ init = false, adopt = [], blind = [], start = [] } = {}, max = 3) {
+  const all = [];
+  // Без манифеста `aqk add` отказывает — остальные шаги без этого невыполнимы.
+  if (init) all.push({ kind: "init" });
+  if (adopt.length) all.push({ kind: "adopt", gates: adopt });
+  for (const b of blind) all.push({ kind: "blind", ...b });
+  const seen = new Set(blind.map((b) => b.slug));
+  for (const st of start) if (!seen.has(st.slug)) all.push({ kind: "start", ...st });
+  return { steps: all.slice(0, max), rest: Math.max(0, all.length - max) };
+}
+
 // Чистая функция: на входе состояние, на выходе строки. Отделена от чтения диска намеренно —
 // это единственное место комплекта, чей текст читает машина, и проверять его надо не прогоном,
 // а перебором случаев, включая те, которых на нашем репозитории не бывает.
@@ -86,6 +107,22 @@ function contextBlock(state, T = L.context) {
     else out.push(T.probeClean(pr.state === "stale" ? pr.behind : 0));
   }
 
+  // ДАЛЬШЕ — то, что `doctor` знает, а агенту не говорилось: блок отвечал только «как дела».
+  // Шаги вычислены, а не пожелания: у каждого команда, которую можно выполнить сейчас.
+  const nx = state.next;
+  if (nx && nx.steps && nx.steps.length) {
+    out.push("", T.nextTitle);
+    nx.steps.forEach((st, i) => out.push(`${i + 1}. ${T.nextStep[st.kind](st)}`));
+    if (nx.rest) out.push(T.nextMore(nx.rest));
+  }
+
+  // КОГДА ЧТО — правила вида «ситуация → команда». Общий совет («тестируй изменения») агент
+  // пролистывает; проверяемый («перед коммитом — вот эта команда») выполняет. Первое правило
+  // зависит от факта: стоит хук — сказать не обходить его; нет — дать команду, само не случится.
+  if (state.when) {
+    out.push("", T.whenTitle, `- ${T.whenCommit(state.when.hook)}`, ...T.whenRules.map((r) => `- ${r}`));
+  }
+
   // ПОЛНЫЙ БЛОК — решение владельца от 2026-09-08, принятое ПОСЛЕ возражения и вопреки ему.
   // Возражение было такое: вход, растущий в длину, роняет качество у всех проверенных моделей,
   // и свод, влитый целиком, даёт правило, которое в контексте есть и не выполняется. Ответ
@@ -293,9 +330,25 @@ async function cmdContext(args = []) {
     fullPart = { entry, rows, text };
   }
 
+  // ДАЛЬШЕ — теми же функциями, что у `doctor`: корзины каталога, «начните с трёх», совет под
+  // язык, чужие проверки проекта. Второй расчёт того же самого разошёлся бы с первым.
+  let next = null;
+  try {
+    const facts = await detectFacts(man);
+    const catalog = await readCatalog();
+    const { todo } = catalogBuckets(catalog, facts, coversOf(man).covered);
+    const adopt = declaredGates(man).length ? [] : proposeGates(await readAdoptFiles(CWD));
+    const blind = (probe?.classes || [])
+      .filter((b) => !facts.gateKeys.includes(b.slug))
+      .map((b) => ({ ...b, command: blindAdvice(catalog.find((r) => r.slug === b.slug), facts, {}).command }));
+    const start = startWith(todo, facts, 3).map((rec) => ({ slug: rec.slug, command: blindAdvice(rec, facts, {}).command }));
+    next = nextSteps({ init: !man, adopt, blind, start });
+  } catch { /* не посчитали — блок скажет остальное; выдумывать шаги нельзя */ }
+
   console.log(contextBlock({
     entry, entryExists: rules !== null, level, rules, run, ratchets, probe, full: fullPart,
+    next, when: { hook: await preCommitHook(CWD) },
   }).join("\n"));
 }
 
-export { cmdContext, contextBlock, parseLastRun, countArbiters, withHook, hasOurHook, portableSelf };
+export { cmdContext, contextBlock, nextSteps, parseLastRun, countArbiters, withHook, hasOurHook, portableSelf };