agent-quality-kit 0.10.1 → 0.12.0

package/tool/commands/probe.mjs

@@ -21,16 +21,17 @@
 // удаляется. Не меняет манифест. Не роняет прогон: код возврата всегда 0 — это осмотр, а
 // не порог. Порог — у `doctor --run --min`.
 import { spawnSync } from "node:child_process";
-import { mkdtemp, mkdir, copyFile, rm, readdir, writeFile, readFile } from "node:fs/promises";
+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 { commandFor } from "../lib/prove.mjs";
-import { fixHotspots, probeVerdict } from "../lib/history.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";
 
 // Тот же набор расширений, что у привязки доказательства к дифу. Список один на программу:
 // второй через месяц разошёлся бы с первым.
@@ -99,14 +100,107 @@ async function writeMark(now, blind, lines) {
   await writeFile(MARK(), body + "\n", "utf8");
 }
 
-// Гейты, которым можно подставить каталог. Команда записи каталога кончается каталогом
-// проверки; написанная руками — чем угодно, и подставлять там некуда. Ровно то же правило,
-// по которому `prove` объявляет запись недоказуемой, а не сломанной.
-function scanningGates(man) {
+
+// Отчего проба не состоялась. Раньше здесь было три состояния: гейты, чья команда не кончается
+// каталогом, объявлялись непригодными — подставить образец было некуда. С песочницей подставлять
+// в команду больше не нужно: образец кладётся в КОПИЮ ПРОЕКТА, а гейт запускается в ней как есть.
+// Поэтому пригодна любая непустая команда, и состояний осталось два.
+function gatesState(man) {
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  const declared = Object.entries(gates)
+    .map(([name, raw]) => [name, String(raw || "").trim()])
+    .filter(([, cmd]) => cmd);
+  if (!declared.length) return { state: "none", declared: 0, probeable: 0 };
+  return { state: "ok", declared: declared.length, probeable: declared.length };
+}
+
+// Гейты, пригодные для пробы: все объявленные с непустой командой.
+function probeableGates(man) {
   const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
   return Object.entries(gates)
     .map(([name, raw]) => [name, String(raw || "").trim()])
-    .filter(([, cmd]) => cmd && /(\.|\.\/)$/.test(cmd));
+    .filter(([, cmd]) => cmd);
+}
+
+// Семьи расширений. Образец подбирается по ТОЧНОМУ расширению, и правило верное: питоновский
+// образец в проекте на TypeScript не проверит ничего, а покажет «не прикрыто» — ложная тревога
+// того же класса, что молчащий гейт, только наоборот.
+//
+// Но `.js` и `.mjs` — одно и то же содержимое, а не два языка. Прогон на самом комплекте
+// 2026-09-10: два горячих файла из пяти — `.mjs`, и обоим ответили «нет образца под .mjs»;
+// комплект целиком написан в этом расширении, то есть проба была слепа к собственному коду.
+// Заводить второй набор файлов ради той же строчки — дублирование, которое разойдётся.
+//
+// Семьи узкие намеренно: `.jsx`/`.tsx` сюда не входят, у них своя разметка.
+const EXT_FAMILIES = [[".js", ".mjs", ".cjs"], [".ts", ".mts", ".cts"]];
+
+function extAlternatives(ext) {
+  const fam = EXT_FAMILIES.find((f) => f.includes(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 };
 }
 
 // Красный образец записи, подходящий по расширению горячего файла. Расширение обязано
@@ -117,39 +211,114 @@ async function redSampleFor(entry, ext) {
   if (!(await exists(dir))) return null;
   let names = [];
   try { names = await readdir(dir); } catch { return null; }
-  const hit = names.find((n) => extname(n).toLowerCase() === ext);
-  return hit ? join(dir, hit) : null;
+  for (const want of extAlternatives(ext)) {
+    const hit = names.find((n) => extname(n).toLowerCase() === want);
+    if (hit) return join(dir, hit);
+  }
+  return null;
 }
 
-// Проба: временный каталог, в нём образец по пути горячего файла. Путь сохраняется целиком —
-// правила, привязанные к путям (`.aqkignore`, исключения гейтов), обязаны действовать так же,
-// как в настоящем репозитории. Без этого проба отвечала бы про несуществующее место.
-async function buildProbe(relPath, sample) {
-  const root = await mkdtemp(join(tmpdir(), "aqk-probe-"));
+// Песочница: КОПИЯ ПРОЕКТА, в которую подсаживается образец. Раньше здесь был временный каталог
+// с одним файлом, а путь к нему подставлялся в команду гейта — отчего пробовать можно было
+// только команды, кончающиеся каталогом. Замер 2026-09-10 на семи чужих репозиториях: у шести
+// команды такие (`xo`, `eslint lib/**/*.js`, `mocha --require…`, `pytest`), и проба не
+// запускалась вовсе.
+//
+// Способ взят из мутационного тестирования, где та же задача решена двадцать лет назад: Stryker
+// копирует проект во временный каталог, СИМЛИНКУЕТ `node_modules` и гоняет там родную команду.
+// Копируются только ОТСЛЕЖИВАЕМЫЕ файлы (`git archive HEAD`) — рабочее дерево не трогается, а
+// мусор сборки не тащится; тяжёлые каталоги зависимостей симлинкуются, иначе `npm test` в
+// песочнице падал бы с «модуль не найден», и это читалось бы как сбой инструмента.
+const DEP_DIRS = ["node_modules", ".venv", "venv", "vendor", "target", ".tox", ".bundle"];
+
+async function buildSandbox() {
+  // Копируется РАБОЧЕЕ ДЕРЕВО, а не HEAD. Первая версия брала `git archive HEAD`, и это было
+  // неверно: комплект зовут из хука ДО коммита, и пользователь пробует то, что у него сейчас,
+  // а не то, что уже записано. На свежем `init` + `add` без коммита проба вообще ничего не
+  // видела — гейты в песочнице отсутствовали и «не запускались».
+  //
+  // Список — `git ls-files --cached --others --exclude-standard`: отслеживаемые плюс новые, но
+  // БЕЗ игнорируемых. Игнорируемое — это сборка и зависимости; первое пробе не нужно, второе
+  // приходит симлинком.
+  //
+  // Копирование средствами node, а не `tar`: у конвейера есть windows-задание, и полагаться на
+  // ключи GNU tar там нельзя.
+  const r = spawnSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+    cwd: CWD, encoding: "utf8", timeout: 60000, maxBuffer: 64 * 1024 * 1024,
+  });
+  if (r.status !== 0) return null;
+  const files = String(r.stdout || "").split("\0").filter(Boolean);
+  if (!files.length) return null;
+
+  const root = await mkdtemp(join(tmpdir(), "aqk-sandbox-"));
+  const made = new Set();
+  for (const rel of files) {
+    const dest = join(root, rel);
+    const dir = dirname(dest);
+    if (!made.has(dir)) { await mkdir(dir, { recursive: true }); made.add(dir); }
+    // Файл мог исчезнуть между списком и копией, а каталог — оказаться подмодулем.
+    try { await copyFile(join(CWD, rel), dest); } catch { /* пропускаем, не роняя пробу */ }
+  }
+  for (const dep of DEP_DIRS) {
+    const from = join(CWD, dep);
+    if (await exists(from)) { try { await symlink(from, join(root, dep), "junction"); } catch { /* уже есть */ } }
+  }
+  return root;
+}
+
+// Подсадка образца на место горячего файла и возврат как было. Файл СНАЧАЛА удаляется:
+// в песочнице он может быть жёсткой ссылкой, и запись поверх задела бы оригинал.
+async function plant(root, relPath, sample) {
   const dest = join(root, relPath);
   await mkdir(dirname(dest), { recursive: true });
+  let backup = null;
+  try { backup = await readFile(dest); } catch { /* файла может не быть */ }
+  await rm(dest, { force: true });
   await copyFile(sample, dest);
-  // Переносится ТОЛЬКО .aqkignore: правила, привязанные к путям, обязаны действовать так же,
-  // как в настоящем репозитории. Манифест НЕ переносится намеренно — иначе записи, читающие
-  // `.aqk.yml` (`gates-are-runnable`, `gate-has-samples`, `protection-not-removed`), краснеют
-  // на том, что в пробе нет объявленных ими файлов, и проба объявляет класс прикрытым, хотя
-  // на подсаженный брак не отреагировал никто. Ошибка в сторону «прикрыто» — это тишина,
-  // а тишина здесь и есть предмет спора. Поймано первым же прогоном на своём репозитории.
-  if (await exists(join(CWD, ".aqkignore"))) {
-    await copyFile(join(CWD, ".aqkignore"), join(root, ".aqkignore"));
-  }
-  return root;
+  return async () => {
+    await rm(dest, { force: true });
+    if (backup !== null) await writeFile(dest, backup);
+  };
 }
 
-function runGates(gates, dir) {
+// Гейт запускается В ПЕСОЧНИЦЕ и командой КАК ЕСТЬ — ничего в неё не подставляется. Именно это
+// и делает пробу независимой от формы команды.
+//
+// `stopOnRed` — ранний выход: как только гейт покраснел, вердикт «поймано» уже получен, и гонять
+// остальные незачем. На сухом прогоне выхода нет: там нужны ВСЕ длительности и все коды.
+function runGates(gates, sandbox, { stopOnRed = false } = {}) {
   const out = [];
   for (const [name, cmd] of gates) {
-    const r = spawnSync(commandFor(cmd, dir), { shell: true, cwd: CWD, encoding: "utf8", timeout: 120000 });
-    out.push({ name, code: r.status === null ? 2 : r.status });
+    const t0 = Date.now();
+    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;
   }
   return out;
 }
 
+// Каким гейтом пробовать и в каком порядке.
+//
+// Цена пробы = (файлы × записи) × сумма длительностей гейтов. На самом комплекте после перехода
+// на песочницу это стало больше десяти минут и упёрлось в таймаут: среди тридцати гейтов есть
+// `smoke` на 58 секунд, и он гонялся заново на каждую подсадку. Команда, идущая четверть часа,
+// не запускается никем.
+//
+// Длительности берутся из сухого прогона, который и так обязателен. Порядок — от быстрых к
+// медленным, чтобы ранний выход срабатывал раньше. Слишком медленные исключаются, но НЕ молча:
+// их имена обязаны попасть в вывод, иначе «никто не ловит» будет означать «никто из тех, кого
+// мы решили спросить».
+const SLOW_MS = 20000;
+
+function planProbeGates(before, { slowMs = SLOW_MS } = {}) {
+  const usable = before.filter((r) => r.code === 0).sort((a, b) => (a.ms || 0) - (b.ms || 0));
+  return {
+    use: usable.filter((r) => (r.ms || 0) <= slowMs),
+    tooSlow: usable.filter((r) => (r.ms || 0) > slowMs),
+  };
+}
+
 // `auto` — проба запущена САМА, по каденции, из `doctor --run`. Тогда она короче и говорит
 // вслух, почему случилась: команда, возникшая без спроса, обязана объяснить себя, иначе её
 // читают как сбой.
@@ -161,8 +330,9 @@ async function cmdProbe(args, { auto = false } = {}) {
   console.log(c.bold(`\n${P.title}\n`));
 
   const man = await readManifest();
-  const gates = scanningGates(man);
-  if (!gates.length) { console.log(c.yellow(`  ${P.noGates(`${SELF} add <имя>`)}\n`)); return; }
+  const gates = probeableGates(man);
+  const gs = gatesState(man);
+  if (gs.state === "none") { console.log(c.yellow(`  ${P.noGates(`${SELF} add <имя>`)}\n`)); return; }
 
   const raw = gitLog(2000);
   if (raw === null) { console.log(c.yellow(`  ${P.noGit}\n`)); return; }
@@ -175,9 +345,40 @@ async function cmdProbe(args, { auto = false } = {}) {
   const catalog = await readCatalog();
   const entries = catalog.filter((e) => triggerVerdict(e, facts).applies);
 
-  console.log(c.dim(`  ${P.method(hot.length, entries.length)}\n`));
+  // ПЕСОЧНИЦА строится ОДИН раз на прогон, а не на каждую пробу: копия отслеживаемых файлов
+  // стоит доли секунды, но умножать её на файлы × записи незачем — между пробами меняется
+  // ровно один файл.
+  const sandbox = await buildSandbox();
+  if (!sandbox) { console.log(c.yellow(`  ${P.noSandbox}\n`)); return; }
+
+  try {
+  // СУХОЙ ПРОГОН по чистой песочнице. Без него «покраснел от подсадки» неотличимо от «был
+  // красным и до неё»: у чужого проекта гейты краснеют на своём накопленном долге, и
+  // засчитывать эту красноту за поимку значит выдавать чужой долг за свою заслугу.
+  // В мутационном тестировании этот прогон обязателен по той же причине.
+  const before = runGates(gates, sandbox);
+  const plan = planProbeGates(before);
+  if (!plan.use.length) {
+    const red = before.filter((r) => r.code === 1).map((r) => r.name);
+    const broke = before.filter((r) => r.code !== 0 && r.code !== 1).map((r) => r.name);
+    if (plan.tooSlow.length) console.log(c.yellow(`  ${P.allSlow(plan.tooSlow.map((g) => g.name))}\n`));
+    else console.log(c.yellow(`  ${P.noBaseline(red, broke)}\n`));
+    return;
+  }
+  // Пробуем только запланированными, в порядке плана.
+  const byName = new Map(gates);
+  const probeGates = plan.use.map((g) => [g.name, byName.get(g.name)]);
+  const baseline = plan.use.map((g) => ({ name: g.name, code: g.code }));
 
-  let blind = 0;
+  console.log(c.dim(`  ${P.method(hot.length, entries.length, plan.use.length)}\n`));
+  if (plan.tooSlow.length) {
+    console.log(c.dim(`  ${P.tooSlow(plan.tooSlow.map((g) => `${g.name} (${Math.round(g.ms / 1000)}s)`))}\n`));
+  }
+
+  // Записи проб: по ним считаются КЛАССЫ, а не события. Счётчики на месте были
+  // событиями и втрое завышали итог — см. countProbe.
+  const records = [];
+  let unprobedN = 0;
   for (const { path: rel, fixes } of hot) {
     console.log(`  ${c.bold(rel)}  ${c.dim(P.fixes(fixes))}`);
     const ext = extname(rel).toLowerCase();
@@ -187,29 +388,67 @@ async function cmdProbe(args, { auto = false } = {}) {
       const sample = await redSampleFor(e.slug, ext);
       if (!sample) continue;
       probed++;
-      const dir = await buildProbe(rel, sample);
-      let results;
-      try { results = runGates(gates, dir); } finally { await rm(dir, { recursive: true, force: true }); }
-      const verdict = probeVerdict(results);
-      const caught = results.filter((r) => r.code === 1).map((r) => r.name);
+      const restore = await plant(sandbox, rel, sample);
+      let after;
+      try { after = runGates(probeGates, sandbox, { stopOnRed: true }); } finally { await restore(); }
+      // Ранний выход обрывает список: гейты, до которых не дошли, считаются такими же, как на
+      // сухом прогоне. Иначе их отсутствие прочиталось бы как сбой запуска.
+      const seen = new Set(after.map((a) => a.name));
+      const full = after.concat(baseline.filter((b) => !seen.has(b.name)));
+      const r = probeVerdictPaired(baseline, full);
+      const verdict = r.verdict;
+      const caught = full.filter((a) => a.code === 1 && baseline.find((b) => b.name === a.name)?.code === 0)
+        .map((a) => a.name);
+      records.push({ entry: e.slug, file: rel, verdict });
       if (verdict === "caught") {
         console.log(`    ${c.green("✔")}  ${e.intent.padEnd(48)} ${c.dim(P.caught(caught.join(", ")))}`);
       } else if (verdict === "blind") {
-        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)}`);
       }
     }
-    if (!probed) console.log(c.dim(`    ${P.noSampleFor(ext || "—")}`));
+    if (!probed) { unprobedN++; console.log(c.dim(`    ${P.noSampleFor(ext || "—")}`)); }
   }
 
-  console.log(blind ? c.yellow(`\n  ${P.summaryBlind(blind)}\n`) : c.green(`\n  ${P.summaryClean}\n`));
+  const n = countProbe(records);
+  const blind = n.blindClasses;
+  const state = probeSummary({
+    caught: n.caughtClasses, blind, unknown: n.unknownClasses, unprobed: unprobedN,
+  });
+  const say = {
+    blind: () => c.yellow(P.summaryBlind(blind, n.probes)),
+    partial: () => c.yellow(P.summaryPartial(n.caughtClasses, n.unknownClasses, unprobedN)),
+    clean: () => c.green(P.summaryClean),
+    "nothing-ran": () => c.yellow(P.summaryNothingRan(n.unknownClasses)),
+    "nothing-probed": () => c.yellow(P.summaryNothingProbed(unprobedN)),
+  };
+  console.log(`\n  ${say[state]()}\n`);
 
   // Отметка нужна не для отчёта, а для КАДЕНЦИИ: по ней следующий прогон поймёт, что пора.
   // Без неё команда снова становится тем, о чём надо вспомнить.
-  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 });
+  }
 }
 
 // Состояние пробы для тех, кто только ПОКАЗЫВАЕТ его: прогон и блок для агента.
@@ -222,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, scanningGates, isCode };
+export { cmdProbe, probeStatus, probeableGates, gatesState, extAlternatives, planProbeGates, blindAdvice, isCode };

package/tool/commands/report.mjs

@@ -21,7 +21,7 @@ import { readManifest, assessLevel } from "../lib/manifest.mjs";
 import { proveGates } from "../lib/prove.mjs";
 import { detectFacts, readCatalog, triggerVerdict, whichSync } from "../lib/repo.mjs";
 import { changedCode, coverage, evidenceHash, readForHash } from "../lib/evidence.mjs";
-import { runGates, declaredGates, sinceRef } from "./doctor.mjs";
+import { runGates, declaredGates, sinceRef } from "../lib/run.mjs";
 import { L } from "../i18n/index.mjs";
 
 // Каким рецептом стоит гейт: родным инструментом или переносимой проверкой. Именно это

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

@@ -256,23 +256,41 @@ export const enGates = {
     autoFirst: "no coverage probe has ever run here — running it myself. Turn off: AQK_PROBE=0",
     auto: (n) => `${n} commits since the last probe — running it myself. Turn off: AQK_PROBE=0`,
     title: "aqk probe — what the declared checks cannot see",
-    method: (files, entries) =>
-      `method: a red sample from a catalogue entry is planted into a copy of each file, ` +
-      `then the DECLARED gates are run against it. Files: ${files}, applicable entries: ${entries}. ` +
+    method: (files, entries, gates) =>
+      `method: a red sample from a catalogue entry is planted into a COPY of the project, then the ` +
+      `DECLARED gates are run there — the command is used as written, nothing is substituted into it. ` +
+      `Files: ${files}, applicable entries: ${entries}, gates green on a clean checkout: ${gates}. ` +
       `The working tree is not touched.`,
     fixes: (n) => `fixes in history: ${n}`,
     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}`,
+    noSandbox: "could not build a sandbox: `git archive HEAD` failed. The probe needs a copy of the tracked files to plant a sample into — it never touches the working tree.",
+    noBaseline: (red, broke) =>
+      `nothing to judge by: on a CLEAN checkout ${red.length ? `these gates are ALREADY red (${red.join(", ")})` : ""}${red.length && broke.length ? " and " : ""}${broke.length ? `these failed to run (${broke.join(", ")})` : ""}. A gate that is red before the sample is planted says nothing about the sample. Get the pipeline green first, then repeat.`,
+    tooSlow: (names) => `not probed with (too slow to run on every planting): ${names.join(", ")}. If a class below is caught by nobody, one of these may still catch it — run them by hand.`,
+    allSlow: (names) => `every gate that is green on a clean checkout is too slow to probe with: ${names.join(", ")}. Probing would re-run them for every planting. Declare a fast gate, or run these by hand.`,
     noGit: "not a git repository — there is no fix history to read",
     noFixes: "no fix commits found: the subject starts with fix / bugfix / hotfix",
-    summaryBlind: (n) =>
-      `classes left uncovered: ${n}. This is not a judgement of the code: these are the places ` +
+    summaryBlind: (n, probes) =>
+      `classes caught by nobody: ${n}` +
+      (probes ? ` (over ${probes} plantings — one class repeated across several hot files is still ONE class)` : "") +
+      `. This is not a judgement of the code: these are the places ` +
       `people come back to with a fix, and defects none of your checks would see there.`,
     summaryClean: "in the places probed, every applicable class is caught by something.",
+    summaryPartial: (caught, unknown, unprobed) =>
+      `caught: ${caught}. Could NOT be checked: ${unknown} (the tool is missing, not the protection). Not probed at all: ${unprobed} file(s) — the catalogue has no red sample for their type. "Checked and clean", "not checked" and "not looked at" are three different facts and are not merged here.`,
+    summaryNothingRan: (n) =>
+      `NOTHING was checked: all ${n} probe(s) failed to run — the delegated tools are missing. This is not a clean result, it is the absence of a result. Install the tools, then repeat.`,
+    summaryNothingProbed: (unprobed) =>
+      `not a single probe was made${unprobed ? ` — ${unprobed} hot file(s) have no red sample for their type in the catalogue` : ""}. Nothing is known about coverage: this is the absence of a measurement, not a clean result.`,
   },
   prove: {
     title: "aqk prove — proving the gates",

package/tool/i18n/en.mjs

@@ -65,6 +65,9 @@ export const en = {
     gitignore: "repository hygiene",
     git: "project under version control",
 
+    rulesByHuman: (total, machine, human) =>
+      `${human} of ${total} rules in the entry point are guarded by a HUMAN, ${machine} by a machine.`,
+    rulesByHumanWhy: "A rule guarded by a human is guarded by nobody the day the human is busy. That is the hole this kit exists to close — and the reminder belongs to the human, not only to the agent. Counted in the ENTRY POINT only: a promise kept in any other file is checked by nothing at all, and this kit will not tell you it exists.",
     emptyCommands: (n) => `AGENTS.md has ${n} unfilled commands.`,
     emptyCommandsWhy: "An agent cannot execute an empty line.",
 
@@ -101,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}`,
@@ -117,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

@@ -258,23 +258,41 @@ export const ruGates = {
     autoFirst: "пробы покрытия здесь ещё не делали — делаю её сам. Выключить: AQK_PROBE=0",
     auto: (n) => `прошло ${n} коммитов с прошлой пробы — делаю её сам. Выключить: AQK_PROBE=0`,
     title: "aqk probe — чего объявленные проверки не видят",
-    method: (files, entries) =>
-      `метод: в копию каждого файла подсаживается красный образец записи каталога, ` +
-      `по нему прогоняются ОБЪЯВЛЕННЫЕ гейты. Файлов: ${files}, применимых записей: ${entries}. ` +
+    method: (files, entries, gates) =>
+      `способ: красный образец записи каталога подсаживается в КОПИЮ проекта, и там гоняются ` +
+      `ОБЪЯВЛЕННЫЕ гейты — команда берётся как написана, в неё ничего не подставляется. ` +
+      `Файлов: ${files}, применимых записей: ${entries}, гейтов зелёных на чистом дереве: ${gates}. ` +
       `Рабочее дерево не трогается.`,
     fixes: (n) => `починок в истории: ${n}`,
     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}`,
+    noSandbox: "не удалось построить песочницу: `git archive HEAD` не отработал. Пробе нужна копия отслеживаемых файлов, чтобы подсадить в неё образец, — рабочее дерево она не трогает никогда.",
+    noBaseline: (red, broke) =>
+      `судить не по чему: на ЧИСТОМ дереве ${red.length ? `уже красные (${red.join(", ")})` : ""}${red.length && broke.length ? ", а " : ""}${broke.length ? `не запустились (${broke.join(", ")})` : ""}. Гейт, красный ДО подсадки, о подсадке не говорит ничего. Сначала позеленить конвейер, потом повторить.`,
+    tooSlow: (names) => `не пробовали ими (слишком долго гонять на каждую подсадку): ${names.join(", ")}. Если класс ниже не ловит никто — может ловить кто-то из них, проверьте руками.`,
+    allSlow: (names) => `все гейты, зелёные на чистом дереве, слишком медленны для пробы: ${names.join(", ")}. Проба гоняла бы их заново на каждую подсадку. Объявите быстрый гейт или прогоните эти руками.`,
     noGit: "это не репозиторий git — истории починок взять неоткуда",
     noFixes: "в истории не нашлось коммитов-починок: тема начинается с fix / исправ / почин",
-    summaryBlind: (n) =>
-      `не прикрыто классов: ${n}. Это не оценка кода: это места, куда возвращаются с починкой, ` +
-      `и брак, которого там не увидит ни одна ваша проверка.`,
+    summaryBlind: (n, probes) =>
+      `классов не ловит никто: ${n}` +
+      (probes ? ` (на ${probes} подсадках — один класс, повторённый по нескольким горячим файлам, остаётся ОДНИМ)` : "") +
+      `. Это не приговор коду: это места, куда возвращаются с починкой, и дефекты, ` +
+      `которых там не увидела бы ни одна ваша проверка.`,
     summaryClean: "в проверенных местах каждый применимый класс кто-то ловит.",
+    summaryPartial: (caught, unknown, unprobed) =>
+      `поймано: ${caught}. Проверить НЕ смогли: ${unknown} (не хватает инструмента, а не защиты). Не пробовали вовсе: файлов ${unprobed} — в каталоге нет красного образца их типа. «Проверено и чисто», «не проверено» и «не смотрели» — три разных факта, и здесь они не сливаются.`,
+    summaryNothingRan: (n) =>
+      `НЕ проверено ничего: все ${n} пробы не смогли запуститься — делегированные инструменты не установлены. Это не чистый результат, это отсутствие результата. Поставьте инструменты и повторите.`,
+    summaryNothingProbed: (unprobed) =>
+      `не сделано ни одной пробы${unprobed ? `: у ${unprobed} горячих файлов нет в каталоге красного образца их типа` : ""}. О прикрытии не известно ничего — это отсутствие замера, а не чистый результат.`,
   },
   prove: {
     title: "aqk prove — доказательство гейтов",