agent-quality-kit 0.11.0 → 0.12.0

package/README.md

@@ -46,6 +46,8 @@ Go, Rust, Java, Ruby, PHP, C#, Kotlin, Swift, Scala. Where the project already h
 says so out loud when it falls back.
 
 **Requirements:** Node 18+ and an `sh` shell. Present on macOS, Linux and WSL; Git Bash on Windows.
+On Windows the gates run through Git Bash even when `bash` on your PATH is the WSL stub in
+`System32` — it is found next to `git.exe`; set `AQK_BASH` to point elsewhere.
 
 ### One movement, and everything follows from it
 
@@ -345,7 +347,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.11.0
+    rev: v0.12.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
@@ -366,7 +368,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.11.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.12.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```

package/README.ru.md

@@ -48,6 +48,8 @@ TypeScript, Go, Rust, Java, Ruby, PHP, C#, Kotlin, Swift, Scala. Там, где
 сообщает, когда откатилась на переносимый.
 
 **Требуется:** Node 18+ и оболочка `sh`. Есть на macOS, Linux и в WSL; на Windows — Git Bash.
+На Windows гейты идут через Git Bash, даже если `bash` в PATH — заглушка WSL из `System32`:
+он ищется рядом с `git.exe`; другой путь задаётся `AQK_BASH`.
 
 ### Одно движение, из которого следует всё остальное
 
@@ -348,7 +350,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.11.0
+    rev: v0.12.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -367,7 +369,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.11.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.12.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```

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

@@ -4,6 +4,11 @@ intent_en: a function does not grow past the complexity you can hold in your hea
 trigger:
   always: true
 
+# Домашние страницы готовых инструментов, которые зовут рецепты ниже. Адреса сверены
+# по реестру github 2026-09-10, а не написаны по памяти: три выдуманных адреса чужих
+# репозиториев — записанная шишка комплекта.
+tool: https://github.com/astral-sh/ruff · https://github.com/eslint/eslint
+
 recipes:
   # Переносимая мера грубая — глубина вложенности. Готовые правила считают ветвления и
   # инструкции, это точнее; см. kit/docs/ready-made-rules.md

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

@@ -10,6 +10,11 @@ trigger:
 # Переносимого рецепта здесь нет намеренно: чтобы понять, вызывают ли функцию, нужен граф
 # вызовов, а не поиск по тексту. Это тот случай, когда без готового инструмента не обойтись —
 # и он есть под каждый распространённый стек.
+# Домашние страницы готовых инструментов, которые зовут рецепты ниже. Адреса сверены
+# по реестру github 2026-09-10, а не написаны по памяти: три выдуманных адреса чужих
+# репозиториев — записанная шишка комплекта.
+tool: https://github.com/jendrikseipp/vulture · https://github.com/webpro-nl/knip
+
 recipes:
   python: vulture --min-confidence 60 {dir}
   typescript: npx --yes knip@6 --directory {dir}

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

@@ -4,6 +4,11 @@ intent_en: the same code does not multiply into copies across the project
 trigger:
   files_gt: 20
 
+# Домашние страницы готовых инструментов, которые зовут рецепты ниже. Адреса сверены
+# по реестру github 2026-09-10, а не написаны по памяти: три выдуманных адреса чужих
+# репозиториев — записанная шишка комплекта.
+tool: https://github.com/kucherenko/jscpd · https://github.com/pylint-dev/pylint
+
 recipes:
   any: bash {gate}/check.sh {dir}
   # jscpd умеет и Python, и TypeScript одним прогоном и считает похожесть, а не совпадение.

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

@@ -11,6 +11,11 @@ trigger:
 # печать в примерах документации, в тестах, в бенчмарках и в выводе командной строки.
 # Отличить их от отладки можно только разбором кода, а не поиском по тексту, — и это
 # ровно то, что уже делают ruff и eslint.
+# Домашние страницы готовых инструментов, которые зовут рецепты ниже. Адреса сверены
+# по реестру github 2026-09-10, а не написаны по памяти: три выдуманных адреса чужих
+# репозиториев — записанная шишка комплекта.
+tool: https://github.com/astral-sh/ruff · https://github.com/eslint/eslint
+
 recipes:
   python: ruff check -q --output-format=concise --select T20 {dir}
   typescript: eslint --no-config-lookup --ignore-pattern 'gates/*/red/**' --ignore-pattern 'gates/*/green/**' --rule '{"no-console":"error"}' {dir}

package/kit/gates/secrets-not-in-code/gate.yml

@@ -4,7 +4,27 @@ intent_en: keys, passwords and private keys do not end up in the code
 trigger:
   always: true
 
+# Домашние страницы готовых инструментов, которые зовут рецепты ниже. Адреса сверены
+# по реестру github 2026-09-10, а не написаны по памяти: три выдуманных адреса чужих
+# репозиториев — записанная шишка комплекта.
+tool: https://github.com/gitleaks/gitleaks
+
 recipes:
+  # Готовый аналог сильнее нашего, и об этом прямо сказано в README записи: `gitleaks` знает
+  # сотни форматов токенов и умеет читать историю, а не только рабочее дерево. Наша проверка —
+  # запасная, для тех, кто не хочет ставить лишний бинарь.
+  #
+  # Ключ `native`, а не язык: секреты ищутся в любом файле, и раскладывать одну команду по
+  # восьми языкам значило бы завести ровно тот повтор, против которого у нас есть гейт.
+  #
+  # `dir` — рабочее дерево; чтение истории (`gitleaks git`) сюда не берём: гейт обязан отвечать
+  # про ТЕКУЩЕЕ состояние, а прошлое лечится не проверкой, а ротацией ключа.
+  #
+  # ОСТОРОЖНО С КОДОМ ВОЗВРАТА: у `gitleaks` 1 означает «нашёл ЛИБО сломался» — по документации,
+  # проверено 2026-09-10. То есть для него «находка» и «сбой инструмента» неразличимы, и это
+  # ровно тот класс, который мы разделяем у себя. Пока принимаем как есть и говорим об этом
+  # вслух, а не делаем вид, что кодов три.
+  native: gitleaks dir --no-banner {dir}
   any: bash {gate}/check.sh {dir}
 
 proof: kit/docs/ai/project-baseline.md, пункт 5 — «секреты не хранятся в коде вообще: ни в истории, ни в примерах, ни в тестах»

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

@@ -7,6 +7,11 @@ intent_en: an error is not silently swallowed — it is handled and logged, or r
 trigger:
   langs: python, javascript, typescript, go
 
+# Домашние страницы готовых инструментов, которые зовут рецепты ниже. Адреса сверены
+# по реестру github 2026-09-10, а не написаны по памяти: три выдуманных адреса чужих
+# репозиториев — записанная шишка комплекта.
+tool: https://github.com/astral-sh/ruff · https://github.com/eslint/eslint · https://github.com/kisielk/errcheck
+
 recipes:
   # BLE — ловля голого исключения, TRY400 — запись без трейса, SIM105 — перехват ради тишины.
   python: ruff check -q --output-format=concise --select BLE,TRY400,SIM105 {dir}

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

@@ -4,6 +4,11 @@ intent_en: "fix later" markers are absent from finished code — a filed task re
 trigger:
   always: true
 
+# Домашние страницы готовых инструментов, которые зовут рецепты ниже. Адреса сверены
+# по реестру github 2026-09-10, а не написаны по памяти: три выдуманных адреса чужих
+# репозиториев — записанная шишка комплекта.
+tool: https://github.com/astral-sh/ruff · https://github.com/eslint/eslint
+
 recipes:
   any: bash {gate}/check.sh {dir}
   # Готовое правило точнее самописного и не требует поддержки.

package/llms.txt

@@ -70,7 +70,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.11.0` with `min: 1`
+- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.12.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.11.0",
+  "version": "0.12.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/context.mjs

@@ -80,7 +80,9 @@ function contextBlock(state, T = L.context) {
     if (pr.state === "never") out.push(T.probeNever);
     else if (pr.state === "off") out.push(T.probeOff);
     else if (pr.state === "unknown") out.push(T.probeUnknown);
-    else if (pr.blind > 0) out.push(T.probeBlind(pr.blind, pr.state === "stale" ? pr.behind : 0));
+    // Имена — агенту они нужнее числа: «один класс» не говорит, какой файл трогать осторожно.
+    else if (pr.blind > 0) out.push(T.probeBlind(pr.blind, pr.state === "stale" ? pr.behind : 0,
+      (pr.classes || []).map((b) => `${b.slug} (${b.file})`).join(", ")));
     else out.push(T.probeClean(pr.state === "stale" ? pr.behind : 0));
   }
 

package/tool/commands/doctor.mjs

@@ -5,15 +5,16 @@ import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { scopeOutput, splitAdvice, changedFiles } from "../lib/scope.mjs";
 import { CWD, PKG_ROOT, TARGET_DIR, MANIFEST, SELF, c, exists, die } from "../lib/core.mjs";
-import { cmdProbe, probeStatus } from "./probe.mjs";
+import { cmdProbe, probeStatus, blindAdvice } from "./probe.mjs";
 import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS, advisorySet, layoutChecks, coversOf, coversUnproven, unparsedLines } from "../lib/manifest.mjs";
 import { proveGates } from "../lib/prove.mjs";
-import { detectFacts, readCatalog, triggerVerdict, browserServerAdvice } from "../lib/repo.mjs";
+import { detectFacts, readCatalog, triggerVerdict, browserServerAdvice, startWith } from "../lib/repo.mjs";
+import { proposeGates, ADOPT_FILES, ADOPT_SCRIPTS } from "../lib/adopt.mjs";
 import { assessBaseline, DEP_FILES, BASELINE_TOTAL } from "../lib/baseline.mjs";
 import { L } from "../i18n/index.mjs";
 import { countArbiters } from "./context.mjs";
 import { beginBrief, finishBrief } from "../lib/brief.mjs";
-import { declaredGates, sinceRef, runGates } from "../lib/run.mjs";
+import { declaredGates, sinceRef, runGates, progress } from "../lib/run.mjs";
 
 // Обязательный минимум проекта — прогоном, а не по памяти. До сих пор это было единственное
 // место, где комплект просил верить на слово, что человек прочитал методичку и сверился.
@@ -50,7 +51,7 @@ async function reportBaseline(man, facts) {
   );
 }
 
-async function reportCatalog(man, facts) {
+async function reportCatalog(man, facts, probe = null) {
   const catalog = await readCatalog();
   if (!catalog.length) return;
 
@@ -117,6 +118,70 @@ async function reportCatalog(man, facts) {
     console.log(c.dim(`\n  ${L.doctor.notApplicable(skip.length)}`));
     for (const [rec, why] of skip) console.log(c.dim(`  ·  ${rec.slug.padEnd(22)} ${why}`));
   }
+  // ЧТО У ВАС УЖЕ ЕСТЬ — до итога и до списка крестов. Комплект, поставленный в проект с
+  // eslint, mocha и конвейером, показывал двадцать крестов и «держит машина 0»: мы считали
+  // только СВОИ записи, а чужие проверки не читали вовсе. С точки зрения владельца это
+  // неправда, и первое, что он видел, было обвинением. Предлагаем, а не вписываем: гейт в
+  // чужом манифесте без спроса — наше решение в чужом файле.
+  if (!declaredGates(man).length) {
+    const files = {};
+    for (const n of ADOPT_FILES) {
+      try { files[n] = await readFile(join(CWD, n), "utf8"); } catch { /* нет — и ладно */ }
+    }
+    for (const n of ADOPT_SCRIPTS) if (await exists(join(CWD, n))) files[n] = "";
+    const found = proposeGates(files);
+    if (found.length) {
+      console.log(`\n  ${c.bold(L.doctor.haveAlready(found.length))}`);
+      for (const g of found) {
+        console.log(`  ${c.green("✔")}  ${g.name.padEnd(12)} ${c.dim(`${g.cmd}   ← ${g.source}`)}`);
+      }
+      console.log(c.dim(`     ${L.doctor.haveAlreadyHow(found.map((g) => `${g.name}: "${g.cmd}"`).join("  "))}`));
+    }
+  }
+
+  // ЧТО ВАШИ ПРОВЕРКИ ПРОПУСТИЛИ. Проба знала имена непойманных классов и писала в отметку одно
+  // число; человек в `doctor` не видел ничего. Это самое конкретное, что мы знаем о проекте, —
+  // не «хорошая практика», а брак, подсаженный в ЕГО файл и ЕГО проверками не замеченный, —
+  // поэтому стоит выше списка «с чего начать». Читается из файла: ничего не запускает.
+  const blindOnes = (probe?.classes || []).map((b) => [b, catalog.find((r) => r.slug === b.slug)]).filter(([, r]) => r);
+  if (blindOnes.length) {
+    console.log(`\n  ${c.yellow("⚠")}  ${c.bold(L.doctor.blindHeading(probe.behind))}`);
+    for (const [b, rec] of blindOnes) {
+      // Три случая, и сливать их нельзя. Гейт стоял и проба его ГОНЯЛА — «стоит, но здесь не
+      // ловит», самое ценное. Гейт объявлен, но проба его не гоняла (поставлен позже или
+      // медленный) — «поймает ли, покажет следующая», а не «пойман». Гейта нет — совет.
+      const ranIt = probe.ran?.has(rec.slug);
+      const now = facts.gateKeys.includes(rec.slug);
+      console.log(`  ${now && !ranIt ? c.dim("~") : c.red("✘")}  ${rec.slug.padEnd(22)} ${c.dim(`${rec.intent || ""}  ← ${b.file}`)}`);
+      if (ranIt) { console.log(c.dim(`     ${L.doctor.blindRan(rec.slug)}`)); continue; }
+      if (now) { console.log(c.dim(`     ${L.doctor.blindInstalled}`)); continue; }
+      const adv = blindAdvice(rec, facts, {});
+      if (adv.command) console.log(c.dim(`     ${L.doctor.startCmd(adv.command)}`));
+      else console.log(c.dim(`     ${L.doctor.install(`${SELF} add ${rec.slug}`)}`));
+    }
+    console.log(c.dim(`     ${L.doctor.blindMore(`${SELF} probe`)}`));
+  } else if (probe?.state === "never" && declaredGates(man).length) {
+    console.log(c.dim(`\n  ${L.doctor.probeNever(`${SELF} probe`)}`));
+  }
+
+  // С ЧЕГО НАЧАТЬ. Двадцать одинаковых крестов — это ноль требований: закрывают первое
+  // попавшееся или не закрывают ничего. Порядок не по нашему вкусу: сперва то, что родилось из
+  // настоящего отказа И закрывается одной готовой командой.
+  if (todo.length > 3) {
+    const first = startWith(todo, facts, 3);
+    console.log(`\n  ${c.bold(L.doctor.startWith)}`);
+    for (const rec of first) {
+      const adv = blindAdvice(rec, facts, {});
+      console.log(`  ${c.yellow("→")}  ${rec.slug.padEnd(22)} ${c.dim(rec.intent || "")}`);
+      if (adv.command) console.log(c.dim(`     ${L.doctor.startCmd(adv.command)}`));
+      if (adv.tool) console.log(c.dim(`     ${L.doctor.startTool(adv.tool)}`));
+    }
+    // Одна проверка руками — это разовый героизм. Сказать про хук здесь, а не в конце: человек
+    // читает первые строки и закрывает, а именно сейчас у него в руках список того, что стоит
+    // повесить перед пушем.
+    console.log(c.dim(`\n     ${L.doctor.startHook}`));
+  }
+
   console.log(
     `\n  ${c.bold(L.doctor.total)} ${L.doctor.totalHeld(held.length)}, ${L.doctor.totalTodo(c.yellow(todo.length))}, ` +
       (byOther.length ? `${L.doctor.totalCovered(byOther.length)}, ` : "") +
@@ -227,7 +292,11 @@ async function cmdDoctor() {
   // Доказательство считается только при прогоне: узнать, ловит ли гейт брак, нельзя иначе как
   // запустив его по образцу. Без прогона ступени со второй помечаются «не доказано» — это
   // честнее, чем показывать их выполненными по наличию папок.
+  // Доказательство — секунды тишины до первой строки уровня; строка «идёт» их называет.
+  const bar = progress();
+  if (process.argv.includes("--run")) bar.show(c.dim(`  ⋯  ${L.doctor.proving}`));
   const proof = process.argv.includes("--run") ? await proveGates(man) : null;
+  bar.clear();
   const { reached, steps } = await assessLevel(man, proof);
 
   console.log(c.bold(`\n  ${L.doctor.levelHeading}\n`));
@@ -274,7 +343,10 @@ async function cmdDoctor() {
     await reportBaseline(man, facts);
     process.exit(0);
   }
-  const cat = (await reportCatalog(man, facts)) || { held: 0, todo: 0, todoRecs: [] };
+  // Состояние пробы — из файла отметки, миллисекунды. Нет его — блок про пробу просто молчит.
+  let probe = null;
+  try { probe = await probeStatus(); } catch { /* пробы нет — и ладно */ }
+  const cat = (await reportCatalog(man, facts, probe)) || { held: 0, todo: 0, todoRecs: [] };
 
   // «Объявлен» ≠ «работает». Без --run говорим это вслух, а не молчим.
   const wantRun = process.argv.includes("--run");

package/tool/commands/gates.mjs

@@ -15,6 +15,7 @@ import {
 } from "../lib/repo.mjs";
 import { GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE } from "../lib/templates.mjs";
 import { L } from "../i18n/index.mjs";
+import { gateCommand } from "../lib/execution.mjs";
 
 // Ставит гейт из каталога в проект. Проверка КОПИРУЕТСЯ в репозиторий, а не остаётся
 // ссылкой в пакет: при установке через npx пакет временный, и завтра команда в манифесте
@@ -230,7 +231,7 @@ async function cmdRatchet(args) {
 
   // Снимок текущих нарушений — это и есть долг. Ключ без номера строки: правка соседней
   // строки не должна читаться как новое нарушение.
-  const r = spawnSync(inner, { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+  const r = spawnSync(gateCommand(inner), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
   if (r.status === 127 || (r.error && r.error.code === "ENOENT")) {
     die(L.ratchet.notRunnable(slug, inner));
   }
@@ -438,7 +439,7 @@ async function cmdWhy(args) {
 
   // --- 3. объявлен: спрашиваем у него самого ---------------------------------
   console.log(c.dim(`  ${L.why.declaredAs(cmd)}`));
-  const r = spawnSync(String(cmd), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+  const r = spawnSync(gateCommand(String(cmd)), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
   const ci = await runsInCi(slug, String(cmd));
 
   if (r.status === 127 || (r.error && r.error.code === "ENOENT")) {

package/tool/commands/probe.mjs

@@ -22,14 +22,16 @@
 // не порог. Порог — у `doctor --run --min`.
 import { spawnSync } from "node:child_process";
 import { mkdtemp, mkdir, copyFile, rm, readdir, writeFile, readFile, symlink } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, extname } from "node:path";
 import { readManifest } from "../lib/manifest.mjs";
 import { fixHotspots, probeSummary, probeVerdictPaired, countProbe } from "../lib/history.mjs";
 import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
 import { CWD, GATES_SRC, TARGET_DIR, c, SELF, exists } from "../lib/core.mjs";
-import { probeState, probeEvery, PROBE_EVERY } from "../lib/cadence.mjs";
+import { probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan } from "../lib/cadence.mjs";
 import { L } from "../i18n/index.mjs";
+import { gateCommand } from "../lib/execution.mjs";
 
 // Тот же набор расширений, что у привязки доказательства к дифу. Список один на программу:
 // второй через месяц разошёлся бы с первым.
@@ -137,6 +139,70 @@ function extAlternatives(ext) {
   return fam ? [ext, ...fam.filter((e) => e !== ext)] : [ext];
 }
 
+// Показать САМ ОБРАЗЕЦ, а не пересказ. «Класс не прикрыт» остаётся словами, пока человек не
+// увидел, что именно мы подсадили в его файл.
+//
+// Первая версия печатала одну «показательную» строку — и угадывала плохо: у мёртвого кода дефект
+// во ВТОРОЙ функции, у отладочной печати во второй строке тела. Угадывать не надо: образцы
+// каталога маленькие по норме, и четырёх строк хватает, чтобы стало видно. Комментарии
+// выброшены: в наших образцах они объясняют замысел коллеге, а не показывают дефект.
+function sampleLines(path, max = 4) {
+  let text = "";
+  try { text = readFileSync(path, "utf8"); } catch { return []; }
+  return text.split("\n")
+    .map((l) => l.replace(/\s+$/, ""))
+    .filter((l) => l.trim() && !/^\s*(#|\/\/|\/\*|\*|--|<!--)/.test(l))
+    .slice(0, max)
+    .map((l) => l.slice(0, 88));
+}
+
+// Совет по НЕПОКРЫТОМУ классу: команда, которую можно вставить прямо сейчас.
+//
+// Проба находит настоящие дыры и печатала про них «close it: aqk add <имя>» — то есть «поставь
+// нашу штуку». Человек, впервые увидевший комплект, закрывает окно. А готовая однострочная
+// команда под его стек У НАС УЖЕ ЛЕЖИТ в `recipes` записи каталога; мы её не показывали.
+//
+// Замер руками на `requests` (самый скачиваемый python-пакет) 2026-09-10: в
+// `src/requests/utils.py` — 75 коммитов-починок; дописана функция с `except Exception: pass`;
+// их собственные `ruff` и `pytest` дали 0 и на чистой копии, и на подсаженной. Строка, которая
+// поймала бы это, лежала в нашем каталоге всё это время.
+//
+// Переносимый рецепт (`any`) в совет НЕ идёт: он зовёт файл из комплекта, и человеку без
+// комплекта вставить его некуда. Нет родного рецепта под стек — команды нет, и это честнее
+// выдуманной.
+function blindAdvice(entry, facts, hot = {}) {
+  const recipes = entry?.recipes && typeof entry.recipes === "object" ? entry.recipes : {};
+  // `langs` приходит МНОЖЕСТВОМ, а не массивом — `Array.isArray` тихо давал пустой список, и
+  // совет не печатался вовсе. Поймано на живом `requests`: langs = Set(1) { python }.
+  const langs = facts?.langs ? [...facts.langs] : [];
+  // Тот же порядок, что у `pickRecipe`: свой язык → безъязыковой родной → ничего. Переносимый
+  // (`any`) сюда не идёт никогда: он зовёт файл из комплекта, и человеку без комплекта вставить
+  // его некуда.
+  let cmd = null;
+  for (const key of [...langs, "native"]) {
+    const r = recipes[key];
+    if (!r || /\{gate\}/.test(r)) continue;
+    cmd = String(r).replace(/\{dir\}/g, ".")
+      // Вычистить то, что относится к НАМ, а не к его проекту. Исключение наших красных
+      // образцов нужно УСТАНОВЛЕННОМУ гейту — рядом с ним лежат образцы. Человеку, который
+      // команду только копирует, этих каталогов не существует, и флаги про них подрывают
+      // доверие: инструмент говорит про чужое хозяйство вместо его кода.
+      .replace(/\s--ignore-pattern\s+'[^']*gates\/[^']*'/g, "")
+      .replace(/\s--ignore-paths=?\s*'[^']*gates\/[^']*'/g, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    break;
+  }
+  // Адрес — того инструмента, которым команда начинается: поле `tool` общее на все языки, и
+  // python-проекту показывалась ссылка на eslint. Первые три слова, а не одно: `npx knip`,
+  // `python -m vulture`. Не совпало — весь список: лишняя ссылка лучше, чем ни одной.
+  const urls = entry?.tool ? String(entry.tool).split(/\s+·\s+/) : [];
+  const head = cmd ? cmd.split(" ").slice(0, 3) : [];
+  const own = urls.find((u) => head.includes(u.replace(/\/+$/, "").split("/").pop()));
+  const tool = own ?? (entry?.tool ? String(entry.tool) : null);
+  return { command: cmd, tool, file: hot.file ?? null, fixes: hot.fixes ?? null, slug: entry?.slug ?? null };
+}
+
 // Красный образец записи, подходящий по расширению горячего файла. Расширение обязано
 // совпадать: питоновский образец в проекте на TypeScript не проверит ничего, а покажет
 // «не прикрыто» — ложная тревога того же класса, что молчащий гейт, только наоборот.
@@ -224,7 +290,7 @@ function runGates(gates, sandbox, { stopOnRed = false } = {}) {
   const out = [];
   for (const [name, cmd] of gates) {
     const t0 = Date.now();
-    const r = spawnSync(cmd, { shell: true, cwd: sandbox, encoding: "utf8", timeout: 120000 });
+    const r = spawnSync(gateCommand(cmd), { shell: true, cwd: sandbox, encoding: "utf8", timeout: 120000 });
     const code = r.status === null ? 2 : r.status;
     out.push({ name, code, ms: Date.now() - t0 });
     if (stopOnRed && code === 1) break;
@@ -338,6 +404,19 @@ async function cmdProbe(args, { auto = false } = {}) {
         console.log(`    ${c.green("✔")}  ${e.intent.padEnd(48)} ${c.dim(P.caught(caught.join(", ")))}`);
       } else if (verdict === "blind") {
         console.log(`    ${c.red("✘")}  ${e.intent.padEnd(48)} ${c.red(P.blind)}`);
+        // Объяснить, а не назвать. Три строки, каждая отвечает на свой вопрос человека:
+        // «почему именно здесь», «что вы вообще подсадили» и «что мне сделать ПРЯМО СЕЙЧАС».
+        // Последняя обязана работать БЕЗ комплекта: польза до установки — единственный
+        // способ заслужить установку.
+        const adv = blindAdvice(e, facts, { file: rel, fixes });
+        console.log(c.dim(`         ${P.blindWhere(rel, fixes)}`));
+        const lines = sampleLines(sample);
+        if (lines.length) {
+          console.log(c.dim(`         ${P.blindWhat}`));
+          for (const l of lines) console.log(c.dim(`           ${l}`));
+        }
+        if (adv.command) console.log(`         ${c.yellow(P.blindFix(adv.command))}`);
+        if (adv.tool) console.log(c.dim(`         ${P.blindTool(adv.tool)}`));
         console.log(c.dim(`         ${P.install(`${SELF} add ${e.slug}`)}`));
       } else {
         console.log(`    ${c.dim("~")}  ${c.dim(e.intent.padEnd(48))} ${c.dim(P.unknown)}`);
@@ -362,7 +441,11 @@ async function cmdProbe(args, { auto = false } = {}) {
 
   // Отметка нужна не для отчёта, а для КАДЕНЦИИ: по ней следующий прогон поймёт, что пора.
   // Без неё команда снова становится тем, о чём надо вспомнить.
-  await writeMark(commitCount(), blind, hot.map(({ path: p2, fixes }) => `- ${p2} (${P.fixes(fixes)})`));
+  await writeMark(commitCount(), blind, [
+    `ran: ${probeGates.map(([name]) => name).join(" ")}`, "",
+    ...blindLines(records), "",
+    ...hot.map(({ path: p2, fixes }) => `- ${p2} (${P.fixes(fixes)})`),
+  ]);
   } finally {
     await rm(sandbox, { recursive: true, force: true });
   }
@@ -378,7 +461,8 @@ async function probeStatus() {
   const every = probeEvery(man);
   if (every === null) return { state: "unknown", behind: null, badEvery: String(man?.probe) };
   if (every === 0) return { state: "off", behind: null };
-  return probeState(await readMark(), commitCount(), every);
+  const mark = await readMark();
+  return { ...probeState(mark, commitCount(), every), classes: parseBlind(mark?.text), ran: parseRan(mark?.text) };
 }
 
-export { cmdProbe, probeStatus, probeableGates, gatesState, extAlternatives, planProbeGates, isCode };
+export { cmdProbe, probeStatus, probeableGates, gatesState, extAlternatives, planProbeGates, blindAdvice, isCode };

package/tool/commands/vitals.mjs

@@ -21,6 +21,7 @@ import { join } from "node:path";
 import { CWD, MANIFEST, SELF, c, exists } from "../lib/core.mjs";
 import { readManifest, unparsedLines, gateRequires } from "../lib/manifest.mjs";
 import { whichSync } from "../lib/repo.mjs";
+import { gitBash } from "../lib/execution.mjs";
 import { updateWanted } from "../lib/brief.mjs";
 import { L } from "../i18n/index.mjs";
 
@@ -94,7 +95,11 @@ async function cmdVitals() {
   for (const [gate, cmd] of Object.entries(gates)) {
     const prog = progOf(cmd);
     if (!prog || seen.has(prog)) continue;
-    seen.set(prog, { gate, prog, found: Boolean(whichSync(prog)) });
+    // На Windows слово `bash` в PATH — часто заглушка WSL, и «найден» было бы неправдой: гейт
+    // запустится через Git Bash (gateCommand) или не запустится вовсе. Спрашиваем того же, кого
+    // спросит прогон, — иначе vitals и doctor --run снова разойдутся.
+    const found = prog === "bash" && process.platform === "win32" ? Boolean(gitBash()) : Boolean(whichSync(prog));
+    seen.set(prog, { gate, prog, found });
   }
 
   // Первого слова мало. Запись каталога бывает обёрткой: команда начинается с `bash`, который

package/tool/i18n/en-docs.mjs

@@ -70,8 +70,9 @@ const enDocs = {
     probeNever: "No coverage probe has run — what is covered by nothing here is UNKNOWN. That is not \"covered\": `aqk probe`.",
     probeOff: "The coverage probe is switched off in the manifest (`probe: 0`) — nobody counts what is covered by nothing here.",
     probeUnknown: "The coverage probe could not run — what is covered by nothing here is UNKNOWN. That is not \"covered\".",
-    probeBlind: (n, behind) =>
+    probeBlind: (n, behind, names = "") =>
       `Covered by nothing: ${n} defect classes in the places people most often come back to fix` +
+      (names ? ` — ${names}` : "") +
       (behind ? ` (the probe is ${behind} commits behind)` : "") + ". Details: `aqk probe`.",
     probeClean: (behind) =>
       "Coverage probe: in the places probed, every applicable class is caught by something" +

package/tool/i18n/en-gates.mjs

@@ -265,6 +265,10 @@ export const enGates = {
     caught: (names) => `caught by: ${names}`,
     blind: "NOTHING CATCHES IT",
     unknown: "nothing to check with — the gate did not run (delegated tool missing)",
+    blindWhere: (file, fixes) => `where: ${file} — ${fixes} fix commits in its history`,
+    blindWhat: "what we planted into your file:",
+    blindFix: (cmd) => `catch it right now, no kit needed:  ${cmd}`,
+    blindTool: (url) => `the tool: ${url}`,
     install: (cmd) => `close it: ${cmd}`,
     noSampleFor: (ext) => `the catalogue has no red sample for "${ext}" — nothing to check with`,
     noGates: (cmd) => `no gates declared — nothing to probe with. First: ${cmd}`,

package/tool/i18n/en.mjs

@@ -104,6 +104,17 @@ export const en = {
       `claim unverified: "${e}" is declared held by gate "${g}", but neither its command nor the\n  linter config names rules ${codes} — the entry may be held by nothing`,
     coversUnprovenHow: (cmd) => `settle it: add those rules to the linter, or install the entry — ${cmd}`,
     totalCovered: (n) => `held by another arbiter ${n}`,
+    blindHeading: (behind) => `The probe${behind ? ` (${behind} commits ago)` : ""} planted defects in your files — your checks did NOT catch them:`,
+    blindRan: (g) => `gate ${g} is declared and was run — and still missed the defect in this file`,
+    blindInstalled: "declared, but the probe did not run this gate (added later or too slow) — the next probe will show whether it catches",
+    blindMore: (cmd) => `what was planted and where — ${cmd}`,
+    probeNever: (cmd) => `Whether your checks catch a real defect has not been tested yet: ${cmd} plants one in a copy of the project and shows (a minute or two, your files are not touched).`,
+    startWith: "Start with these three — born from a real failure, and each closes with one ready command:",
+    startCmd: (cmd) => `one line, no kit needed:  ${cmd}`,
+    startTool: (url) => `the tool: ${url}`,
+    startHook: "Running these by hand is a one-off. To have them run before every push: pre-commit (repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit, hooks aqk / aqk-doctor), or a plain .git/hooks/pre-push.",
+    haveAlready: (n) => `Checks you ALREADY have (${n}) — found in your own files, not invented:`,
+    haveAlreadyHow: (line) => `declare them and a machine holds them, not your attention. In .aqk.yml, under gates:  ${line}`,
     total: "Total:",
     totalHeld: (n) => `held by a machine ${n}`,
     totalTodo: (n) => `applicable but not installed ${n}`,
@@ -120,6 +131,8 @@ export const en = {
       `either fix them and drop them from advisory, or admit the rule does not exist.`,
     runHeading: "Running the declared gates",
     timeout: "did not finish within 5 minutes",
+    running: (i, n) => `[${i}/${n}] running…`,
+    proving: "checking that the gates catch defects on their own samples…",
     exitCode: (code) => `exit ${code}`,
     moreLines: (n) => `… and ${n} more lines`,
     declaredNotRun: (n) => `${n} gates declared, but never run.`,

package/tool/i18n/ru-docs.mjs

@@ -72,8 +72,9 @@ const ruDocs = {
     probeNever: "Проба покрытия не делалась — что здесь не прикрыто ничем, НЕИЗВЕСТНО. Это не «прикрыто»: `aqk probe`.",
     probeOff: "Проба покрытия выключена в манифесте (`probe: 0`) — что здесь не прикрыто ничем, никто не считает.",
     probeUnknown: "Пробу покрытия провести не удалось — что здесь не прикрыто ничем, НЕИЗВЕСТНО. Это не «прикрыто».",
-    probeBlind: (n, behind) =>
+    probeBlind: (n, behind, names = "") =>
       `Не прикрыто ничем: ${n} классов брака в местах, куда чаще всего возвращаются с починкой` +
+      (names ? ` — ${names}` : "") +
       (behind ? ` (проба отстала на ${behind} коммитов)` : "") + ". Подробно: `aqk probe`.",
     probeClean: (behind) =>
       "Проба покрытия: в проверенных местах каждый применимый класс кто-то ловит" +

package/tool/i18n/ru-gates.mjs

@@ -267,6 +267,10 @@ export const ruGates = {
     caught: (names) => `ловит: ${names}`,
     blind: "НЕ ЛОВИТ НИКТО",
     unknown: "проверить нечем — гейт не состоялся (нет делегированной программы)",
+    blindWhere: (file, fixes) => `где: ${file} — починок в истории: ${fixes}`,
+    blindWhat: "что подсадили в ваш файл:",
+    blindFix: (cmd) => `поймать прямо сейчас, без комплекта:  ${cmd}`,
+    blindTool: (url) => `инструмент: ${url}`,
     install: (cmd) => `закрыть: ${cmd}`,
     noSampleFor: (ext) => `в каталоге нет красного образца под «${ext}» — проверить нечем`,
     noGates: (cmd) => `гейтов не объявлено — пробовать нечем. Сначала: ${cmd}`,

package/tool/i18n/ru.mjs

@@ -105,6 +105,17 @@ export const ru = {
       `заявка не подтверждена: «${e}» объявлена закрытой гейтом «${g}», но ни его команда, ни\n  конфиг линтера не называют правил ${codes} — запись может быть не закрыта ничем`,
     coversUnprovenHow: (cmd) => `подтверди: добавь эти правила в линтер, либо поставь запись — ${cmd}`,
     totalCovered: (n) => `закрыто другим арбитром ${n}`,
+    blindHeading: (behind) => `Проба${behind ? ` (коммитов с тех пор: ${behind})` : ""} подсадила брак в ваши файлы — ваши проверки его НЕ ПОЙМАЛИ:`,
+    blindRan: (g) => `гейт ${g} стоит и прогонялся — а брак в этом файле пропустил`,
+    blindInstalled: "объявлено, но проба этот гейт не гоняла (поставлен позже или медленный) — поймает ли, покажет следующая",
+    blindMore: (cmd) => `что именно подсадили и куда — ${cmd}`,
+    probeNever: (cmd) => `Ловят ли ваши проверки настоящий брак, ещё не проверялось: ${cmd} подсадит его в копию проекта и покажет (минута-две, рабочие файлы не трогает).`,
+    startWith: "Начните с этих трёх — они родились из настоящего отказа и закрываются одной готовой командой:",
+    startCmd: (cmd) => `одной строкой, без комплекта:  ${cmd}`,
+    startTool: (url) => `инструмент: ${url}`,
+    startHook: "Прогнать руками — разовый героизм. Чтобы это случалось перед каждым пушем: pre-commit (репозиторий https://github.com/arsen-ask-lx/Agent_Quality_Kit, хуки aqk / aqk-doctor) либо обычный .git/hooks/pre-push.",
+    haveAlready: (n) => `Проверки, которые у вас УЖЕ ЕСТЬ (${n}) — прочитаны в ваших файлах, не выдуманы:`,
+    haveAlreadyHow: (line) => `объявите их — и держать будет машина, а не ваше внимание. В .aqk.yml, в gates:  ${line}`,
     total: "Итого:",
     totalHeld: (n) => `держит машина ${n}`,
     totalTodo: (n) => `применимо но не поставлено ${n}`,
@@ -121,6 +132,8 @@ export const ru = {
       `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
+    running: (i, n) => `[${i}/${n}] идёт…`,
+    proving: "проверяю, что гейты ловят брак на своих образцах…",
     exitCode: (code) => `код ${code}`,
     moreLines: (n) => `… и ещё ${n} строк`,
     declaredNotRun: (n) => `${n} гейтов объявлено, но не запускалось.`,