agent-quality-kit 0.10.1 → 0.12.0

package/tool/i18n/ru.mjs

@@ -66,6 +66,9 @@ export const ru = {
     gitignore: "гигиена репозитория",
     git: "проект под контролем версий",
 
+    rulesByHuman: (total, machine, human) =>
+      `правил в точке входа: ${total}. Сторож — ЧЕЛОВЕК у ${human}, машина у ${machine}.`,
+    rulesByHumanWhy: "Правило со сторожем-человеком не сторожит никто в тот день, когда человек занят. Это та самая дыра, ради которой комплект и написан, — и напоминание про неё нужно человеку, а не только агенту. Считаны правила ТОЧКИ ВХОДА: обещание, живущее в любом другом файле, не проверяет вообще ничто, и комплект даже не скажет вам, что оно есть.",
     emptyCommands: (n) => `В AGENTS.md ${n} незаполненных команд.`,
     emptyCommandsWhy: "Агент не может выполнить пустую строку.",
 
@@ -102,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}`,
@@ -118,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} гейтов объявлено, но не запускалось.`,

package/tool/lib/adopt.mjs

@@ -0,0 +1,98 @@
+// 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"];
+
+export { proposeGates, ADOPT_FILES, ADOPT_SCRIPTS };

package/tool/lib/cadence.mjs

@@ -54,4 +54,39 @@ 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;
+}
+
+export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan };

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/history.mjs

@@ -9,7 +9,7 @@
 // брак возвращается; там и стоит спрашивать, смотрит ли на них хоть одна проверка.
 //
 // ЧТО ЭТО НЕ ЗНАЧИТ. Часто чинят и то, что часто меняют: рейтинг говорит «сюда возвращаются»,
-// а не «здесь плохо». Ответ на «прикрыто ли» даёт не он, а проба — см. probeVerdict.
+// а не «здесь плохо». Ответ на «прикрыто ли» даёт не он, а проба — см. probeVerdictPaired.
 
 // Признак починки берётся из ТЕМЫ коммита. Тема — единственное, что пишут все, и единственное,
 // что видно в `git log --oneline`.
@@ -71,12 +71,93 @@ function fixHotspots(raw, { isCode }) {
 // самый отказ, против которого написан весь комплект. Засчитать как «не прикрыто» — тоже
 // неправда: мы не знаем.
 //
-// Поймавший гейт сильнее непроверенного: класс закрыт, даже если рядом чего-то не хватает.
-function probeVerdict(results) {
-  if (results.some((r) => r.code === 1)) return "caught";
-  if (results.length === 0) return "unknown";
-  if (results.some((r) => r.code !== 0)) return "unknown";
-  return "blind";
+
+// Итог пробы по всем её исходам. Отдельная функция, а не тернарник на месте: исходов у
+// у пробы три, и пока веток было две, `unknown` молча падал в «поймано всё».
+//
+// Замер 2026-09-10 на проекте с чужими командами: единственная запись вернула «нечем
+// проверить — инструмент делегирован и не установлен», а итог сказал «каждый применимый
+// класс кем-то ловится». Ошибка запуска, выданная за чистоту, — то самое, ради чего
+// написан стандарт, в его собственной главной команде.
+//
+// Сочетания названы исчерпывающе. `partial` существует потому, что «поймано три, проверить
+// две не смогли» и «поймано три» — разные факты, и сливать их значит округлять в свою пользу.
+// `unprobed` — горячие файлы, которым проба не делалась ВОВСЕ: красного образца их расширения
+// в каталоге нет. Прогон на самом комплекте 2026-09-10: два `.mjs` из пяти горячих файлов не
+// пробовались никак, а итог говорил «каждый применимый класс кем-то ловится». Оговорка «в
+// пробованных местах» верна буквально и обманывает по смыслу — она молча сужает утверждение до
+// мест, где проба удалась. Поэтому «чисто» отвечается только при нуле пропущенных.
+function probeSummary({ caught = 0, blind = 0, unknown = 0, unprobed = 0 } = {}) {
+  if (blind) return "blind";
+  if (caught && (unknown || unprobed)) return "partial";
+  if (caught) return "clean";
+  if (unknown) return "nothing-ran";
+  return "nothing-probed";
+}
+
+// Парный вердикт: гейт прогнан ДВАЖДЫ — по чистой песочнице и по ней же с подсаженным
+// образцом. Так проба перестаёт зависеть от формы команды: `npm test`, `pytest`, `xo`,
+// `eslint lib/**/*.js` работают наравне с `bash check.sh .`.
+//
+// Замер 2026-09-10: у шести чужих репозиториев из семи команды каталогом не кончаются, и
+// старая проба на них не запускалась вовсе. Способ не выдуман — так устроено мутационное
+// тестирование: Stryker копирует проект во временный каталог, симлинкует `node_modules` и
+// гоняет РОДНУЮ команду; прогон по чистой копии там обязателен.
+//
+// Что исключается из суждения и почему:
+//   · сбой ЗАПУСКА (код не 0 и не 1) с любой стороны — про подсадку не сказано ничего;
+//   · гейт, красный ЕЩЁ ДО подсадки, — его краснота объясняется состоянием проекта, и
+//     засчитывать её за поимку значит выдавать чужой долг за свою заслугу;
+//   · гейт, ПОЗЕЛЕНЕВШИЙ от подсадки, — он смотрит не туда, и это тоже не поимка.
+// Исключены все — вердикт `unknown`, а не `blind`: «не по чему судить» и «никто не ловит»
+// разные факты, и молчание здесь и есть предмет спора.
+//
+// И ещё одно: гейт, СЛОМАННЫЙ подсадкой (работал до, не смог после), мог быть тем самым
+// ловцом. Пока никто другой не поймал, «слеп» про такой класс — неправда, и вердикт `unknown`.
+// Найдено пробой на самом комплекте 2026-09-11: образец лёг на место общей библиотеки
+// kit/gates/_skip.sh, двенадцать гейтов вышли с кодом 2 — включая тот, что этот образец в
+// отдельной папке ловит. Остальные молчали, и проба назвала класс слепым.
+function probeVerdictPaired(before, after) {
+  const byName = new Map(after.map((r) => [r.name, r]));
+  let usable = 0, alreadyRed = 0, failed = 0, caught = 0, brokenByPlant = 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++;
+      if (!broke(b)) brokenByPlant++;
+      continue;
+    }
+    if (b.code === 1) { alreadyRed++; continue; }
+    usable++;
+    if (a.code === 1) caught++;
+  }
+  const verdict = caught ? "caught" : !usable || brokenByPlant ? "unknown" : "blind";
+  return { verdict, usable, alreadyRed, failed, caught, brokenByPlant };
+}
+
+// Счёт непокрытого КЛАССАМИ, а не пробами. Замер на десяти живых репозиториях 2026-09-10:
+// у requests, click, flask и httpx проба сказала «непокрытых классов: 18», а различных классов
+// там ШЕСТЬ — повторены по трём горячим файлам. Втрое завышенное число, и завышали его мы сами
+// тем самым приёмом, который ловим у других: считали события, а называли их сущностями.
+//
+// Число проб остаётся отдельно: «шесть классов на трёх файлах» и «шесть на одном» — разные
+// факты. Класс, слепой ХОТЬ ГДЕ-ТО, считается непокрытым: «где-то ловится» не защищает то
+// место, где не ловится.
+function countProbe(records) {
+  const bins = { blind: new Set(), caught: new Set(), unknown: new Set() };
+  let probes = 0;
+  for (const { entry, verdict } of records) {
+    if (!bins[verdict]) continue;
+    bins[verdict].add(entry);
+    probes++;
+  }
+  return {
+    blindClasses: bins.blind.size,
+    caughtClasses: bins.caught.size,
+    unknownClasses: bins.unknown.size,
+    probes,
+  };
 }
 
-export { isFix, fixHotspots, probeVerdict };
+export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe };

package/tool/lib/prove.mjs

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { CWD, exists } from "./core.mjs";
 import { parseManifest, gateRequires } from "./manifest.mjs";
 import { whichSync } from "./repo.mjs";
-import { classify, findingCodes } from "./execution.mjs";
+import { classify, findingCodes, gateCommand } from "./execution.mjs";
 
 // Гейт можно доказать, если у него есть оба образца. Признак по образцам, а не по тексту
 // команды: запись, делегирующая готовому инструменту (`npx knip --directory .`), каталог
@@ -108,7 +108,7 @@ async function samplesForRecipe(samplesDir, name) {
 // «не знаем» — а вызывающий тут же считал его находкой. Опыт 2026-09-09: проверка, виснущая
 // на красном образце, получала вердикт «доказана».
 function run(cmd, timeoutMs, prog) {
-  const r = spawnSync(cmd, { shell: true, encoding: "utf8", cwd: CWD, timeout: timeoutMs });
+  const r = spawnSync(gateCommand(cmd), { shell: true, encoding: "utf8", cwd: CWD, timeout: timeoutMs });
   const out = `${r.stdout || ""}${r.stderr || ""}`.trim();
   return { ...classify(r, findingCodes(prog)), out };
 }

package/tool/lib/repo.mjs

@@ -265,6 +265,22 @@ function pickRecipe(rec, facts, missing) {
     console.log(c.dim(`  ${c.yellow("!")}  ${L.recipe.skipped(lang, prog)}`));
   }
 
+  // Безъязыковой родной рецепт. Ключи рецептов — языки, и это верно для линтеров, но неверно
+  // для инструментов, которым язык безразличен: `gitleaks` ищет ключи в любом файле, и
+  // `secrets-not-in-code` объявлен `always: true`. Без этого ключа выбор был из двух плохих —
+  // продублировать команду под восемь языков (тот самый повтор, против которого у нас гейт)
+  // или оставить запись без родного рецепта. Второе и было: замер на десяти чужих проектах
+  // 2026-09-10 дал секреты в НЕПОКРЫТЫХ у axios и у всех четырёх python-проектов, то есть там,
+  // где польза наибольшая, команды для вставки не существовало.
+  //
+  // Стоит ПОСЛЕ языков и ПЕРЕД переносимым: свой язык точнее, а родной сильнее переносимого —
+  // но только если его есть чем выполнить.
+  if (recipes.native) {
+    const prog = String(recipes.native).trim().split(/\s+/)[0];
+    if (runnable(recipes.native)) return recipes.native;
+    if (Array.isArray(missing) && !missing.includes(prog)) missing.push(prog);
+  }
+
   return recipes.any || null;
 }
 
@@ -362,9 +378,40 @@ async function matchCatalog(query) {
   return out;
 }
 
+// С ЧЕГО НАЧАТЬ: три записи вместо двадцати равнозначных крестов.
+//
+// Двадцать одинаковых требований — это ноль требований: закрывают первое попавшееся или не
+// закрывают ничего. Порядок НЕ по нашему вкусу; два признака, оба — факты, которые у нас уже
+// есть:
+//   · запись родилась из настоящего отказа (`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);
+}
+
 // Наружу — то, что действительно импортируют другие файлы и модульные проверки. Экспорт,
 // который никто не берёт, читается как часть договора и мешает менять внутренности.
 export {
   whichSync,
   EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor, browserServerAdvice, MARKS,
+  startWith,
   stems, overlap, matchCatalog, isApiSpec };