agent-quality-kit 0.11.0 → 0.13.0

package/tool/lib/adopt.mjs

@@ -0,0 +1,112 @@
+// tool/lib/adopt.mjs — проверки, которые у проекта УЖЕ ЕСТЬ. Читаются из его собственных
+// файлов, а не выдумываются.
+//
+// ЗАЧЕМ. Комплект, поставленный в `express` — проект с eslint, mocha и конвейером, — показывал
+// двадцать крестов подряд и «держит машина 0». С точки зрения владельца это неправда: его
+// проверки держат, просто мы считали только СВОИ записи. Мы видели, что конвейер ЕСТЬ
+// (`has_ci`), но не читали, что в нём, и человек должен был переписать в манифест руками то,
+// что мы могли прочитать сами. Отсюда и «не понимает, что у него хорошо»: хорошее уже есть, а
+// мы о нём молчим.
+//
+// ОТДЕЛЬНЫМ ФАЙЛОМ, а не в repo.mjs: там осмотр репозитория ради НАШЕГО каталога, здесь —
+// чтение ЧУЖИХ конфигов, и у каждого источника свой формат, который меняется по своим
+// причинам. Шов вскрыл наш же `file-size-limit`: с python-источниками repo.mjs перевалил бы
+// за 500 строк.
+//
+// ПРЕДЛАГАЕМ, А НЕ ОБЪЯВЛЯЕМ. Гейт, вписанный в чужой манифест без спроса, — это наше решение
+// в чужом файле; и человек обязан видеть ИСТОЧНИК, иначе предложение неотличимо от догадки.
+//
+// Сборка и запуск проверками не считаются: `build` собирает, `start` запускает, судит — ни тот
+// ни другой. Берём только то, что отвечает «прошло или нет».
+const CHECK_NAMES = new Set(["test", "tests", "lint", "typecheck", "type-check", "types", "check"]);
+
+// Окружения tox, которые судят, а не гоняют тесты под матрицей версий. Голый `tox` не
+// предлагаем: он проходит все интерпретаторы из envlist, и у человека без пяти питонов это
+// красный прогон на пустом месте. Имена сняты с живых tox-файлов (rich, click, flask).
+const TOX_CHECKS = new Set(["lint", "style", "typing", "types", "type", "mypy", "check", "typecheck"]);
+
+// Источники в порядке доверия: при совпадении имени берётся первый. Замер 2026-09-11 на
+// восьми python-проектах: package.json нет ни у кого, Makefile у трёх, `.pre-commit-config.yaml`
+// у семи, tox у пяти, scripts/ у httpx. Шаги конвейера НЕ читаются: там `${{ matrix.x }}`,
+// `PYTHONPATH=…` и обёртки `uv run --locked --group …` — строка, которая работает только в
+// том конвейере, предложенная как локальный гейт, покраснела бы у человека в первую же минуту.
+function proposeGates(files = {}) {
+  const out = [];
+  const seen = new Set();
+  const push = (name, cmd, source) => {
+    const key = name === "tests" ? "test" : name.replace(/^type-?check$|^types$/, "typecheck");
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ name: key, cmd, source });
+  };
+
+  const pkg = files["package.json"];
+  if (pkg) {
+    let scripts = null;
+    try { scripts = JSON.parse(pkg)?.scripts; } catch { scripts = null; }
+    if (scripts && typeof scripts === "object") {
+      for (const name of Object.keys(scripts)) {
+        if (!CHECK_NAMES.has(name)) continue;
+        // `npm test` — каноничное написание для теста, остальное через `run`.
+        push(name, name === "test" || name === "tests" ? "npm test" : `npm run ${name}`, "package.json");
+      }
+    }
+  }
+
+  const mk = files.Makefile;
+  if (typeof mk === "string") {
+    for (const m of mk.matchAll(/^([A-Za-z][\w-]*):/gm)) {
+      if (CHECK_NAMES.has(m[1])) push(m[1], `make ${m[1]}`, "Makefile");
+    }
+  }
+
+  // pre-commit — одна команда на всё, что в нём стоит. Хуки называются поимённо: «у вас есть
+  // .pre-commit-config.yaml» ничего не говорит, «у вас есть ruff-check и check-yaml» — говорит.
+  const pc = files[".pre-commit-config.yaml"];
+  if (typeof pc === "string") {
+    const ids = [...pc.matchAll(/^\s*-\s*id:\s*["']?([\w.-]+)/gm)].map((m) => m[1]);
+    if (ids.length) {
+      const shown = ids.slice(0, 4).join(", ") + (ids.length > 4 ? ` +${ids.length - 4}` : "");
+      push("pre-commit", "pre-commit run --all-files", `.pre-commit-config.yaml: ${shown}`);
+    }
+  }
+
+  // tox живёт в двух местах и двух синтаксисах: `[testenv:lint]` в tox.ini (и внутри
+  // legacy_tox_ini в pyproject), `[tool.tox.env.lint]` в pyproject.toml нового образца.
+  for (const src of ["tox.ini", "pyproject.toml"]) {
+    const t = files[src];
+    if (typeof t !== "string") continue;
+    for (const m of t.matchAll(/^\s*\[(?:testenv:|tool\.tox\.env\.)([\w-]+)\]/gm)) {
+      if (TOX_CHECKS.has(m[1])) push(m[1], `tox -e ${m[1]}`, src);
+    }
+  }
+
+  // Каталог scripts/ с исполняемыми test, check, lint — соглашение encode (httpx, starlette):
+  // конвейер зовёт ровно их. Содержимое не читаем, важно только, что файл есть.
+  for (const name of ["test", "check", "lint"]) {
+    if (`scripts/${name}` in files) push(name, `scripts/${name}`, "scripts/");
+  }
+
+  return out;
+}
+
+// Какие файлы читать — знает тот, кто их разбирает. Список в команде разошёлся бы с разбором
+// в первый же день, когда появится новый источник.
+const ADOPT_FILES = ["package.json", "Makefile", ".pre-commit-config.yaml", "tox.ini", "pyproject.toml"];
+const ADOPT_SCRIPTS = ["scripts/test", "scripts/check", "scripts/lint"];
+
+// Чтение с диска — отдельно от разбора: разбор проверяется перебором случаев, чтение — прогоном.
+async function readAdoptFiles(cwd) {
+  const { readFile, access } = await import("node:fs/promises");
+  const { join } = await import("node:path");
+  const files = {};
+  for (const n of ADOPT_FILES) {
+    try { files[n] = await readFile(join(cwd, n), "utf8"); } catch { /* нет — и ладно */ }
+  }
+  for (const n of ADOPT_SCRIPTS) {
+    try { await access(join(cwd, n)); files[n] = ""; } catch { /* нет — и ладно */ }
+  }
+  return files;
+}
+
+export { proposeGates, readAdoptFiles };

package/tool/lib/advice.mjs

@@ -0,0 +1,115 @@
+// tool/lib/advice.mjs — ЧТО СОВЕТОВАТЬ ПРОЕКТУ: какие записи каталога его касаются, с каких
+// начать и какой командой закрыть класс брака прямо сейчас, без комплекта.
+//
+// ОТДЕЛЬНЫМ ФАЙЛОМ, а не в repo.mjs: там осмотр репозитория (факты, триггеры, рецепты), здесь —
+// решение, что из этого сказать человеку и агенту. Одно знание на `doctor`, `probe` и блок для
+// агента: жило в двух файлах и росло в обоих; шов вскрыл наш же file-size-limit — repo.mjs
+// дорос до 494 строк при пределе 500.
+import { triggerVerdict } from "./repo.mjs";
+
+// Корзины каталога для ЭТОГО проекта: держит · к установке · закрыто другим арбитром ·
+// неприменимо. Одна раскладка на `doctor` и на блок для агента: жила внутри `doctor`, и блоку
+// пришлось бы завести вторую — а два счёта одного и того же расходятся первыми.
+function catalogBuckets(catalog, facts, covered = new Map()) {
+  const held = [], todo = [], skip = [], byOther = [];
+  for (const rec of catalog) {
+    const v = triggerVerdict(rec, facts);
+    if (!v.applies) skip.push([rec, v.why]);
+    else if (facts.gateKeys.includes(rec.slug)) held.push(rec);
+    else if (covered.has(rec.slug)) byOther.push([rec, covered.get(rec.slug)]);
+    else todo.push(rec);
+  }
+  return { held, todo, skip, byOther };
+}
+
+// С ЧЕГО НАЧАТЬ: три записи вместо двадцати равнозначных крестов.
+//
+// Двадцать одинаковых требований — это ноль требований: закрывают первое попавшееся или не
+// закрывают ничего. Порядок НЕ по нашему вкусу; два признака, оба — факты, которые у нас уже
+// есть:
+//   · запись родилась из настоящего отказа (`lifecycle: stable` — `proof` ссылается на журнал
+//     шишек), то есть она про боль, которая СЛУЧАЛАСЬ, а не про «хорошую практику»;
+//   · её можно закрыть одной готовой командой — цена входа минутная.
+// Сначала то, что и больно, и дёшево.
+//
+// При равенстве признаков — по имени: одинаковый ввод обязан давать одинаковый ответ, иначе
+// человек видит разный совет на двух прогонах подряд и перестаёт верить обоим.
+function startWith(entries, facts, n = 3) {
+  const langs = facts?.langs ? [...facts.langs] : [];
+  const cheap = (e) => {
+    const r = e?.recipes && typeof e.recipes === "object" ? e.recipes : {};
+    return [...langs, "native"].some((k) => r[k] && !/\{gate\}/.test(r[k])) ? 1 : 0;
+  };
+  // Зрелость НЕ поле записи, а вычисляемый признак: `proof` ссылается на журнал шишек. Тот же
+  // признак, которым каталог отделяет условную запись с первого дня (`entryLifecycle`).
+  // Заводить второй счёт нельзя: разъехавшись, они дали бы разные ответы про одну запись.
+  const hurt = (e) => (/incidents\//.test(String(e?.proof || "")) ? 1 : 0);
+  return [...entries]
+    .sort((a, b) =>
+      (hurt(b) + cheap(b)) - (hurt(a) + cheap(a)) ||
+      cheap(b) - cheap(a) ||
+      String(a.slug).localeCompare(String(b.slug)))
+    .slice(0, n);
+}
+
+// Адрес Biome сверен по реестру github 2026-09-11.
+const BIOME_URL = "https://github.com/biomejs/biome";
+
+// Совет по НЕПОКРЫТОМУ классу: команда, которую можно вставить прямо сейчас.
+//
+// Проба находит настоящие дыры и печатала про них «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`) сюда не идёт никогда: он зовёт файл из комплекта, и человеку без комплекта вставить
+  // его некуда.
+  // Проект на Biome — совет на языке Biome, а не eslint (отзыв с живого проекта 2026-09-11:
+  // «начни с трёх» советовал завести eslint проекту на Biome). Одно правило разово через `--only`;
+  // `--error-on-warnings` обязателен — правило вне рекомендованных Biome ставит на
+  // «предупреждение», и без флага команда выходила с нулём, напечатав находку (Biome 2.5.12).
+  const br = typeof entry?.biome_rules === "string" ? entry.biome_rules.trim() : "";
+  if (facts?.has_biome && br && br !== "none" && langs.some((l) => l === "javascript" || l === "typescript")) {
+    const only = br.split(",").map((x) => x.trim()).filter(Boolean).map((r) => `--only=${r}`).join(" ");
+    return { command: `npx @biomejs/biome lint --error-on-warnings ${only} .`, tool: BIOME_URL,
+      file: hot.file ?? null, fixes: hot.fixes ?? null, slug: entry?.slug ?? null };
+  }
+  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 };
+}
+
+export { catalogBuckets, startWith, blindAdvice };

package/tool/lib/brief.mjs

@@ -112,7 +112,9 @@ function beginBrief() {
 
 // Печать краткого итога. Совет — не чаще раза в сутки и с явным способом отказаться: то, что
 // видишь тридцатый раз, перестаёт читаться и пролистывается вместе с настоящими находками рядом.
-// Отметка времени лежит в .aqk/, который в .gitignore: это состояние машины, а не проекта.
+// Отметка времени лежит в .aqk/ и попадает в .gitignore при `init` (RUNTIME_FILES в core.mjs):
+// это состояние машины, а не проекта. Раньше здесь было написано «.aqk/ в .gitignore» — а
+// `init` туда ничего не клал, и на живом проекте служебный файл уехал в коммит.
 async function finishBrief(buf, state, todoRecs, ok) {
   if (!buf) return;
   buf.restore();

package/tool/lib/cadence.mjs

@@ -54,4 +54,49 @@ function probeEvery(man) {
   return n;
 }
 
-export { probeDue, probeState, probeEvery, PROBE_EVERY };
+// ИМЕНА непойманных классов в отметке. Хранилось одно число, `blind: 1`: агент в `context`
+// видел «один класс», человек в `doctor` не видел ничего, и чтобы узнать КАКОЙ, надо было снова
+// запускать пробу — ту самую команду, о которой не вспоминают. Находка, которую не показали,
+// ни от чего не предостерегает.
+//
+// Правило то же, что у `countProbe`: класс, слепой хоть где-то, — непокрыт, а «не смогли
+// проверить» слепотой не считается. Файл — первый, где слеп: пробы идут от самого горячего.
+function blindLines(records) {
+  const seen = new Set();
+  const out = [];
+  for (const { entry, file, verdict } of records || []) {
+    if (verdict !== "blind" || seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(`blind-class: ${entry} ${file}`);
+  }
+  return out;
+}
+
+// Отметка старого формата строк `blind-class:` не несёт — тогда список пуст, и это «имён не
+// знаем», а не «слепых нет»: число `blind:` читается отдельно и остаётся правдой.
+function parseBlind(text) {
+  return [...String(text || "").matchAll(/^blind-class:\s*(\S+)\s+(.+?)\s*$/gm)]
+    .map((m) => ({ slug: m[1], file: m[2] }));
+}
+
+// Какие гейты проба ПРОГОНЯЛА. Без этого «объявлен сейчас» читалось как «поставлен после
+// пробы» — а проба как раз и гоняет объявленные: гейт, стоявший ДО неё и брак пропустивший,
+// получал утешительное «поймает ли, покажет следующая» вместо «здесь не ловит». Именно
+// прогонявшиеся, а не объявленные: медленные проба пропускает, и про них «не поймал» — ложь.
+// Старая отметка строки не несёт — null: «не знаем», а не «ничего не прогонялось».
+function parseRan(text) {
+  const m = /^ran:[ \t]*(.*)$/m.exec(String(text || ""));
+  return m ? new Set(m[1].split(/\s+/).filter(Boolean)) : null;
+}
+
+// Запускаться ли пробе САМОЙ внутри `doctor --run`. Не в конвейере: там это +2–3 минуты сюрпризом
+// в случайном прогоне (отзыв с живого проекта 2026-09-11), и место пробы — отдельная задача. Не в
+// коротком режиме: там хук на воротах коммита. `AQK_PROBE=0` — выключить, `AQK_PROBE=1` — включить
+// и в конвейере.
+function autoProbeAllowed({ brief = false, env = process.env } = {}) {
+  if (env.AQK_PROBE === "0" || brief) return false;
+  if (env.AQK_PROBE === "1") return true;
+  return !(env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI || env.BUILDKITE || env.JENKINS_URL);
+}
+
+export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed };

package/tool/lib/core.mjs

@@ -142,9 +142,47 @@ async function writeIfAbsent(path, content, { force }) {
   return true;
 }
 
+// СЛУЖЕБНЫЕ ФАЙЛЫ: состояние ЭТОЙ машины, переписываются каждым прогоном — в git им не место.
+// Один список на `init` (кладёт в .gitignore), `doctor` (предупреждает, если git их видит) и
+// читателей. Отзыв с живого проекта 2026-09-11: `.aqk/last-run.md` однажды закоммитили, и каждый
+// `make check` оставлял изменённый файл. Целиком `.aqk/` не игнорируется: методички и правила в
+// нём — содержимое проекта.
+const RUNTIME_FILES = ["last-run.md", "last-probe.md", "advice-shown", "update-checked"];
+const L_IGNORE_NOTE = LANG === "en"
+  ? "# aqk: this machine's state — rewritten by every run, it does not belong in git"
+  : "# aqk: состояние этой машины — переписывается каждым прогоном, в git ему не место";
+
+// Дописать служебные файлы в .gitignore, не трогая чужих строк и не дублируя своих. Возвращает
+// список добавленных строк — `init` называет их вслух: правка чужого файла без слова была бы
+// тем самым «пишу в дерево без спроса».
+async function ensureIgnored(cwd = CWD) {
+  const { readFile, writeFile } = await import("node:fs/promises");
+  const file = join(cwd, ".gitignore");
+  let text = "";
+  try { text = await readFile(file, "utf8"); } catch { /* файла нет — создадим */ }
+  const have = new Set(text.split(/\r?\n/).map((l) => l.trim()));
+  const add = RUNTIME_FILES.map((f) => `${TARGET_DIR}/${f}`).filter((l) => !have.has(l) && !have.has(`/${l}`));
+  if (!add.length) return [];
+  const head = text && !text.endsWith("\n") ? "\n" : "";
+  await writeFile(file, `${text}${head}${text ? "\n" : ""}${L_IGNORE_NOTE}\n${add.join("\n")}\n`, "utf8");
+  return add;
+}
+
+// Стоит ли хук pre-commit НА САМОМ ДЕЛЕ — в `.git/hooks`, а не в `.pre-commit-config.yaml`:
+// запись в конфиге — намерение, сработает только то, что лежит в гите. Три ответа: true — стоит,
+// false — нет, null — не git или файл не прочитать («не знаем» не сливается с «нет»).
+// Одна функция на `vitals` (подключено ли) и `context` (что сказать агенту перед коммитом).
+async function preCommitHook(cwd = CWD) {
+  const { readFile } = await import("node:fs/promises");
+  if (!(await exists(join(cwd, ".git")))) return null;
+  const hook = join(cwd, ".git", "hooks", "pre-commit");
+  if (!(await exists(hook))) return false;
+  try { return /pre-commit|aqk/i.test(await readFile(hook, "utf8")); } catch { return null; }
+}
+
 export {
   copyDir, writeIfAbsent,
   PKG_ROOT, CWD, DOCS_SRC, RULES_SRC, TARGET_DIR, docPath,
   MANIFEST, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB,
-  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK, commandRows,
+  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK, commandRows, preCommitHook, RUNTIME_FILES, ensureIgnored,
 };

package/tool/lib/execution.mjs

@@ -27,6 +27,10 @@
 
 // Умолчание для незнакомой программы: ноль — чисто, единица — находка, остальное — сбой.
 // Это честнее догадки: неизвестный код становится «не знаем», а не «поймал».
+import { existsSync } from "node:fs";
+import { win32 } from "node:path";
+import { whichSync } from "./repo.mjs";
+
 const DEFAULT = (code) => code === 1;
 
 const ADAPTERS = {
@@ -64,4 +68,49 @@ function classify(r, isFinding = DEFAULT) {
   return { state: "infra_error", reason: "unexpected_exit", code };
 }
 
-export { classify, findingCodes };
+// КАКОЙ BASH ЗАПУСКАТЬ НА WINDOWS. В System32 лежит bash.exe — заглушка WSL, и в PATH она стоит
+// раньше Git Bash: установщик Git по умолчанию кладёт туда только Git\cmd. Команда гейта
+// `bash kit/gates/x/check.sh .` уезжала в Linux-подсистему — другие программы, другой git,
+// другие пути — и прогон краснел «не из-за кода». Отчёт с живого проекта 2026-09-11: «гейты
+// под Windows берут bash из WSL. Через Git Bash все проходят».
+//
+// Приём не выдуман: на ту же ловушку наступали Claude Code (anthropics/claude-code#23556) и
+// Archon (coleam00/Archon#1326), и общий ответ — не верить слову `bash` из PATH, а брать его
+// рядом с git. Git комплекту нужен всё равно. Явный путь — AQK_BASH: у всего, что мы решаем
+// сами, обязан быть способ решить иначе.
+//
+// Не нашли — null, и команда остаётся как есть. Подставлять заглушку WSL «за неимением» нельзя:
+// это ровно то, от чего мы уходим; `vitals` назовёт bash ненайденным.
+function gitBash({ platform = process.platform, env = process.env, which = whichSync, exists = existsSync } = {}) {
+  if (platform !== "win32") return null;
+  if (env.AQK_BASH) return env.AQK_BASH;
+  const cands = [];
+  const git = which("git", env);
+  if (git) {
+    // Git\cmd\git.exe и Git\mingw64\bin\git.exe — корень на два и на три уровня выше.
+    for (const root of [win32.dirname(win32.dirname(git)), win32.dirname(win32.dirname(win32.dirname(git)))]) {
+      cands.push(win32.join(root, "bin", "bash.exe"), win32.join(root, "usr", "bin", "bash.exe"));
+    }
+  }
+  for (const base of [env.ProgramFiles, env["ProgramFiles(x86)"], env.LOCALAPPDATA && win32.join(env.LOCALAPPDATA, "Programs")]) {
+    if (base) cands.push(win32.join(base, "Git", "bin", "bash.exe"));
+  }
+  return cands.find((p) => exists(p)) || null;
+}
+
+// Подменяется только ПЕРВОЕ слово: внутренний `bash` у обёртки храповика запускает уже Git Bash,
+// а у него свой PATH. Кавычки — путь почти всегда с пробелом («Program Files»).
+function launchable(cmd, bash) {
+  const s = String(cmd || "");
+  return bash && /^bash(\s|$)/.test(s) ? `"${bash}"${s.slice(4)}` : s;
+}
+
+// Одна точка для всех пяти мест, где запускается команда гейта: прогон, доказательство, проба,
+// храповик, `why`. Поиск делается раз на процесс — он смотрит на диск, а гейтов бывает тридцать.
+let cachedBash;
+function gateCommand(cmd) {
+  if (cachedBash === undefined) cachedBash = gitBash();
+  return launchable(cmd, cachedBash);
+}
+
+export { classify, findingCodes, gitBash, launchable, gateCommand };

package/tool/lib/gate-worker.mjs

@@ -0,0 +1,18 @@
+// tool/lib/gate-worker.mjs — рабочий поток параллельного прогона (`doctor --run --jobs N`).
+//
+// ПОЧЕМУ ПОТОК, А НЕ АСИНХРОННЫЙ ЗАПУСК. Прогон стоит на `spawnSync` с таймаутом: его поведение
+// на зависшем гейте замерено и описано (execution.mjs). Асинхронный `spawn` потребовал бы своего
+// убийства дерева процессов на таймауте — на Windows это отдельная история. Поток выполняет ТОТ ЖЕ
+// `spawnSync` с тем же таймаутом, и семантика прогона не меняется ни в чём, кроме одновременности.
+// Зависимостей это не добавляет: worker_threads встроены в Node.
+import { parentPort } from "node:worker_threads";
+import { spawnSync } from "node:child_process";
+import { gateCommand } from "./execution.mjs";
+
+parentPort.on("message", ({ id, cmd, cwd, timeout }) => {
+  const r = spawnSync(gateCommand(cmd), { shell: true, cwd, encoding: "utf8", timeout });
+  parentPort.postMessage({
+    id, status: r.status, stdout: r.stdout || "", stderr: r.stderr || "",
+    error: r.error ? { code: r.error.code || String(r.error.message || r.error) } : null,
+  });
+});

package/tool/lib/history.mjs

@@ -111,19 +111,58 @@ function probeSummary({ caught = 0, blind = 0, unknown = 0, unprobed = 0 } = {})
 //   · гейт, ПОЗЕЛЕНЕВШИЙ от подсадки, — он смотрит не туда, и это тоже не поимка.
 // Исключены все — вердикт `unknown`, а не `blind`: «не по чему судить» и «никто не ловит»
 // разные факты, и молчание здесь и есть предмет спора.
+//
+// И ещё одно: гейт, СЛОМАННЫЙ подсадкой (работал до, не смог после), мог быть тем самым
+// ловцом. Пока никто другой не поймал, «слеп» про такой класс — неправда, и вердикт `unknown`.
+// Найдено пробой на самом комплекте 2026-09-11: образец лёг на место общей библиотеки
+// kit/gates/_skip.sh, двенадцать гейтов вышли с кодом 2 — включая тот, что этот образец в
+// отдельной папке ловит. Остальные молчали, и проба назвала класс слепым.
+// «ПОКРАСНЕЛ» ≠ «ПОЙМАЛ». Отзыв с живого проекта 2026-09-11: класс «цвет из токена темы» отмечен
+// пойманным линтером, хотя Biome цвета не проверяет, — подсаженный кусок сломал форматирование.
+// Вердикт сравнивал коды возврата и выбрасывал вывод. Теперь гейт засчитывается, только если в
+// его выводе ПОСЛЕ подсадки подсаженный файл назван чаще, чем до неё. Путь ищется в любой
+// форме: `src/x`, `./src/x`, абсолютный из песочницы (подстрока), с обратными слешами Windows.
+// Одно имя файла без каталога не засчитывается: у двух файлов оно бывает одинаковым, и
+// поимка чужого файла выдалась бы за поимку нашего. Безымянное падение — «неизвестно».
+function namesPlant(before, after, rel) {
+  const forms = [rel, String(rel).replace(/\//g, "\\")];
+  const count = (s) => forms.reduce((n, f) => n + String(s || "").split(f).length - 1, 0);
+  return count(after) > count(before);
+}
+
+// ПАРА, А НЕ ОДИН ОБРАЗЕЦ. Имени файла мало: Biome, падая на форматировании, тоже называет файл.
+// Поэтому поимка подтверждается зелёным образцом той же записи, положенным в то же место, — тем
+// же приёмом, каким мы требуем от чужого гейта доказательства. Три исхода:
+//   caught   — на красном покраснел и назвал файл, на зелёном промолчал (или файла не назвал);
+//   nameless — покраснел, но подсаженного файла не назвал: упал по своей причине;
+//   planting — краснеет и на зелёном, называя тот же файл: падает от самой подсадки.
+// Зелёного образца под это расширение нет — судим по имени файла: пусть слабее, но это не
+// «поймано» на ровном месте, и в README записи такой случай назван.
+function catchVerdict(beforeOut, red, green, rel) {
+  if (!namesPlant(beforeOut, red?.out, rel)) return "nameless";
+  if (green && green.code === 1 && namesPlant(beforeOut, green.out, rel)) return "planting";
+  return "caught";
+}
+
 function probeVerdictPaired(before, after) {
   const byName = new Map(after.map((r) => [r.name, r]));
-  let usable = 0, alreadyRed = 0, failed = 0, caught = 0;
+  let usable = 0, alreadyRed = 0, failed = 0, caught = 0, brokenByPlant = 0, unattributed = 0;
   for (const b of before) {
     const a = byName.get(b.name);
     const broke = (r) => !r || (r.code !== 0 && r.code !== 1);
-    if (broke(b) || broke(a)) { failed++; continue; }
+    if (broke(b) || broke(a)) {
+      failed++;
+      if (!broke(b)) brokenByPlant++;
+      continue;
+    }
     if (b.code === 1) { alreadyRed++; continue; }
     usable++;
-    if (a.code === 1) caught++;
+    // `named === false` — покраснел, но подсаженного файла не назвал. `undefined` — вызывающий
+    // вывода не собирал (старые вызовы): тогда прежнее правило.
+    if (a.code === 1) { if (a.named === false) unattributed++; else caught++; }
   }
-  const verdict = !usable ? "unknown" : caught ? "caught" : "blind";
-  return { verdict, usable, alreadyRed, failed, caught };
+  const verdict = caught ? "caught" : !usable || brokenByPlant || unattributed ? "unknown" : "blind";
+  return { verdict, usable, alreadyRed, failed, caught, brokenByPlant, unattributed };
 }
 
 // Счёт непокрытого КЛАССАМИ, а не пробами. Замер на десяти живых репозиториях 2026-09-10:
@@ -150,4 +189,4 @@ function countProbe(records) {
   };
 }
 
-export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe };
+export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe, namesPlant, catchVerdict };

package/tool/lib/manifest.mjs

@@ -112,7 +112,7 @@ function unparsedLines(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "lang", "gates", "covers", "samples", "ratchets", "lessons", "advisory", "probe"];
+const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "lang", "gates", "covers", "samples", "ratchets", "lessons", "advisory", "probe", "groups"];
 
 // ГДЕ У ПРОЕКТА ЛЕЖИТ РАЗЛОЖЕННЫЙ КОМПЛЕКТ. Список для шапки `doctor`. До 2026-09-08 он был
 // литеральным: `.aqk/rules`, `.aqk/docs`, `AGENTS.md` — независимо от того, что написано в
@@ -132,12 +132,16 @@ function layoutChecks(man, inKit) {
   const entries = (Array.isArray(man?.entry) ? man.entry : [])
     .filter((e) => typeof e === "string" && e.trim())
     .map((e) => e.trim());
+  // Третий элемент — обязателен ли пункт. Методички и стандарты `init` кладёт как пособие: проект
+  // вправе держать их где-то ещё или не держать вовсе, и их отсутствие — совет, а не приговор
+  // прогону (отзыв с живого проекта 2026-09-11: прогон краснел только из-за `.aqk/docs`). Точка
+  // входа, .gitignore и .git — обязательны: на них стоит своя проверка вердикта.
   return [
-    [field("docs", inKit ? "kit/docs" : ".aqk/docs"), inKit ? L.doctor.docsKit : L.doctor.docs],
-    [field("rules", inKit ? "kit/rules" : ".aqk/rules"), inKit ? L.doctor.rulesKit : L.doctor.rules],
-    ...(entries.length ? entries : ["AGENTS.md"]).map((e) => [e, L.doctor.agents]),
-    [".gitignore", L.doctor.gitignore],
-    [".git", L.doctor.git],
+    [field("docs", inKit ? "kit/docs" : ".aqk/docs"), inKit ? L.doctor.docsKit : L.doctor.docs, false],
+    [field("rules", inKit ? "kit/rules" : ".aqk/rules"), inKit ? L.doctor.rulesKit : L.doctor.rules, false],
+    ...(entries.length ? entries : ["AGENTS.md"]).map((e) => [e, L.doctor.agents, true]),
+    [".gitignore", L.doctor.gitignore, true],
+    [".git", L.doctor.git, true],
   ];
 }
 
@@ -188,28 +192,68 @@ function coversOf(man) {
 // вывод перестают читать целиком, вместе с настоящими находками.
 const RULE_CODES = /--select[= ]([A-Za-z0-9,]+)/;
 
-function coversUnproven(man, catalog = [], linterConfigText = "") {
+// КАКИМ ЛИНТЕРОМ ЗАКРЫТ ГЕЙТ. Отзыв с живого проекта 2026-09-11 (TypeScript на Biome): заявка
+// «lint держит no-print-in-prod» всегда была «не подтверждена» — сверка искала коды ruff в
+// конфиге Biome, где их не бывает никогда. Поле, снимающее шум, само его производило.
+// Порядок: команда гейта; npm-скрипт, который она зовёт; единственный конфиг линтера в проекте.
+function linterOf(cmd, scripts = {}, present = []) {
+  let c = String(cmd || "");
+  const m = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?([\w:-]+)/.exec(c);
+  if (m && typeof scripts[m[1]] === "string") c += ` ${scripts[m[1]]}`;
+  if (/\bbiome\b/.test(c)) return "biome";
+  if (/\beslint\b/.test(c)) return "eslint";
+  if (/\bruff\b/.test(c)) return "ruff";
+  return present.length === 1 ? present[0] : null;
+}
+
+// Правила записи на языке ЭТОГО линтера. ruff — коды из `--select` рецептов; eslint — имена из
+// `--rule '{…}'`; Biome рецептов не имеет, у записи для него поле `biome_rules` (сверено по схеме
+// конфигурации Biome 2.5.12). `none` — у линтера такого правила нет вовсе. `null` — не знаем.
+function rulesFor(rec, linter) {
+  const recipes = Object.values(rec?.recipes && typeof rec.recipes === "object" ? rec.recipes : {}).map(String);
+  if (linter === "ruff") {
+    const codes = new Set();
+    for (const cmd of recipes) { const m = RULE_CODES.exec(cmd); if (m) for (const x of m[1].split(",")) if (x.trim()) codes.add(x.trim()); }
+    return codes.size ? [...codes] : null;
+  }
+  if (linter === "eslint") {
+    const names = new Set();
+    for (const cmd of recipes) for (const m of cmd.matchAll(/"([@a-z0-9/_-]+)"\s*:\s*\[?\s*"(?:error|warn)"/g)) names.add(m[1]);
+    return names.size ? [...names] : null;
+  }
+  if (linter === "biome") {
+    const v = typeof rec?.biome_rules === "string" ? rec.biome_rules.trim() : "";
+    if (!v) return null;
+    // Поле хранит `группа/правило` — так его ждёт `biome lint --only`; в biome.json правило
+    // лежит внутри объекта группы, поэтому ищется по имени без группы.
+    return v === "none" ? [] : v.split(",").map((x) => x.trim().split("/").pop()).filter(Boolean);
+  }
+  return null;
+}
+
+// `configs` — тексты конфигов по линтерам: { ruff, eslint, biome, scripts }. Строка (прежний вид
+// вызова) — один общий текст для всех. Исходы: unproven (линтер известен, его правил нет ни в
+// команде, ни в конфиге) · impossible (у линтера такого правила нет) · unknown (линтер не
+// распознан или правил записи для него мы не знаем — «не умею проверить», не обвинение).
+function coversUnproven(man, catalog = [], configs = "") {
   const { covered } = coversOf(man);
   if (!covered.size) return [];
   const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
-  const cfg = String(linterConfigText || "");
+  const cfg = typeof configs === "string" ? { ruff: configs, eslint: configs, biome: configs } : (configs || {});
+  const present = ["ruff", "eslint", "biome"].filter((k) => cfg[k] && String(cfg[k]).trim() && typeof configs !== "string");
   const out = [];
 
   for (const [entry, gate] of covered) {
     const rec = catalog.find((r) => r.slug === entry);
-    const recipes = rec?.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
-    // Коды берутся из любого рецепта записи: язык проекта здесь не важен, важно, что запись
-    // ВООБЩЕ выражается кодами правил. Если ни один рецепт их не называет — сверять нечего.
-    const codes = new Set();
-    for (const cmd of Object.values(recipes)) {
-      const m = RULE_CODES.exec(String(cmd || ""));
-      if (m) for (const c of m[1].split(",")) if (c.trim()) codes.add(c.trim());
-    }
-    if (!codes.size) continue;
-
-    const haystack = `${String(gates[gate] || "")}\n${cfg}`;
-    const missing = [...codes].filter((c) => !haystack.includes(c));
-    if (missing.length === codes.size) out.push({ entry, gate, codes: [...codes] });
+    // Запись, которая не выражается правилами НИ ОДНОГО линтера (переносимые проверки), не
+    // сверяется вовсе: сверять нечего, и выдумывать вердикт нельзя.
+    if (!["ruff", "eslint", "biome"].some((k) => rulesFor(rec, k) !== null)) continue;
+    const linter = linterOf(gates[gate], cfg.scripts || {}, present);
+    const rules = linter ? rulesFor(rec, linter) : null;
+    if (rules === null) { out.push({ entry, gate, codes: [], linter, kind: "unknown" }); continue; }
+    if (!rules.length) { out.push({ entry, gate, codes: [], linter, kind: "impossible" }); continue; }
+    const haystack = `${String(gates[gate] || "")}\n${String(cfg[linter] || "")}`;
+    if (rules.every((r) => !haystack.includes(r))) out.push({ entry, gate, codes: rules, linter, kind: "unproven" });
   }
   return out;
 }