agent-quality-kit 0.12.0 → 0.14.0

package/kit/gates/entry-commands-exist/red/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "sample",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "debug": "4.3.4"
+  }
+}

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,10 +40,16 @@ 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
+- Hand the agent one task instead of retelling the diagnosis: `npx agent-quality-kit prompt` —
+  ground rules on top, at most five items by weight (red gates, defects the probe planted and no
+  check caught, the project's own checks to declare, rules Claude Code cannot see, catalog
+  entries to propose), and for every item the command that proves it done. Nothing is run
 - Check that the kit's own wiring is actually connected: `npx agent-quality-kit vitals` — are the
   tools the declared gates need installed, is the hook present in `.git/hooks` (a line in the
   config is an intention, not a guard), does the agent receive the state, is the version current.
@@ -70,7 +76,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.14.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.14.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, принятое ПОСЛЕ возражения и вопреки ему.
   // Возражение было такое: вход, растущий в длину, роняет качество у всех проверенных моделей,
   // и свод, влитый целиком, даёт правило, которое в контексте есть и не выполняется. Ответ
@@ -223,6 +260,37 @@ async function installHook(full = false) {
   console.log(c.dim(`  ${T.hookWhat}`));
 }
 
+// Прошлый прогон — из отчёта, который кладёт `doctor --run`. Отдельной функцией: его читают и
+// `context`, и `prompt`, и два разбора одного файла разошлись бы.
+async function readRun() {
+  const lastRun = join(CWD, TARGET_DIR, "last-run.md");
+  if (!(await exists(lastRun))) return null;
+  const run = parseLastRun(await readFile(lastRun, "utf8"));
+  if (run) run.stale = runIsStale(run.when);
+  return run;
+}
+
+// Что советовать — теми же функциями, что у `doctor`: корзины каталога, «начните с трёх», совет
+// под язык, чужие проверки проекта. Одно место на `context` и `prompt`: второй расчёт того же
+// самого разошёлся бы с первым. Класс из пробы, чей гейт уже стоит, в совет не идёт — ставить
+// его второй раз бессмысленно.
+async function readAdvice(man, probe) {
+  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, intent: rec.intent || "", command: blindAdvice(rec, facts, {}).command }));
+  // Гейт стоит, проба его ГОНЯЛА — и брак он пропустил. Самое ценное, что проба знает: не
+  // «поставь», а «твоя проверка здесь слепа». Гейт, поставленный после пробы, сюда не идёт —
+  // поймает ли, покажет следующая.
+  const missed = (probe?.classes || []).filter((b) => facts.gateKeys.includes(b.slug) && probe?.ran?.has(b.slug));
+  return { adopt, blind, start, missed };
+}
+
 async function cmdContext(args = []) {
   const full = args.includes("--full");
   if (args.includes("--install")) return installHook(full);
@@ -249,12 +317,7 @@ async function cmdContext(args = []) {
     rules = countArbiters(await readFile(join(CWD, entry), "utf8"), ["человек", "human", "nobody"]);
   }
 
-  let run = null;
-  const lastRun = join(CWD, TARGET_DIR, "last-run.md");
-  if (await exists(lastRun)) {
-    run = parseLastRun(await readFile(lastRun, "utf8"));
-    if (run) run.stale = runIsStale(run.when);
-  }
+  const run = await readRun();
 
   // Проба: сколько классов не ловит никто и насколько отметка отстала. Читается из файла,
   // ничего не запускает — блок обязан укладываться в секунду.
@@ -293,9 +356,18 @@ async function cmdContext(args = []) {
     fullPart = { entry, rows, text };
   }
 
+  // ДАЛЬШЕ — теми же функциями, что у `doctor`: корзины каталога, «начните с трёх», совет под
+  // язык, чужие проверки проекта. Второй расчёт того же самого разошёлся бы с первым.
+  let next = null;
+  try {
+    const { adopt, blind, start } = await readAdvice(man, probe);
+    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, readRun, readAdvice };