agent-quality-kit 0.12.0 → 0.13.0

package/tool/i18n/en-docs.mjs

@@ -66,7 +66,7 @@ const enDocs = {
     runClean: (when) => `Last run ${when} — nothing red.`,
     runRed: (when, names) => `Last run ${when} — RED: ${names}.`,
     andMore: (n) => `and ${n} more`,
-    skipped: (n) => `Not run: ${n} — the tool is absent on this machine, their state is unknown.`,
+    skipped: (n) => `Not run: ${n} — skipped by --only/--skip or the tool is absent on this machine; their state is unknown.`,
     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\".",
@@ -79,6 +79,26 @@ const enDocs = {
       (behind ? ` (${behind} commits behind)` : "") + ".",
     ratchets: (list) => `Ratchets: ${list}. The list may only get shorter, never longer.`,
     where: (entry) => `The rulebook: ${entry}. What proves a diff: \`aqk report --since main\`.`,
+    nextTitle: "Next, in order — computed from this repository, not generic advice:",
+    nextStep: {
+      init: () => "Set up the standard: `aqk init` — without .aqk.yml `aqk add` refuses.",
+      adopt: (s) => `Declare the checks this project already has: in .aqk.yml, under gates: ${s.gates.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Then \`aqk doctor --run\`.`,
+      blind: (s) => `The "${s.slug}" defect the probe planted in ${s.file} was NOT caught by your checks.` +
+        (s.command ? ` Catch it now: \`${s.command}\`.` : "") + ` Keep it caught: \`aqk add ${s.slug}\`.`,
+      start: (s) => `Install ${s.slug}: \`aqk add ${s.slug}\`` + (s.command ? ` (one line, no kit needed: \`${s.command}\`)` : "") +
+        ", then `aqk prove` — the gate must go red on its own red sample.",
+    },
+    nextMore: (n) => `And ${n} more — the full list: \`aqk doctor\`.`,
+    whenTitle: "When to do what:",
+    whenCommit: (hook) => hook === true
+      ? "Before a commit → the `.git/hooks/pre-commit` hook runs the checks itself; do not bypass it (`--no-verify`)."
+      : "Before a commit → `aqk doctor --run --since main`: there is no pre-commit hook, it will not happen by itself.",
+    whenRules: [
+      "Added or changed a check → `aqk prove`: the gate must go red on its own red sample, otherwise it checks nothing.",
+      "Writing a rule into the rulebook → put the arbiter mark next to it, `<!-- aqk: gate-name -->`; no gate — `<!-- aqk: human -->`, which is an admission, not a check.",
+      "A check is in your way → do not weaken it (`|| true`, `--exit-zero`, a suppression without a rule code): stop and ask the owner.",
+      "You think it is done → `aqk report --since main`: every changed file must be named by a check.",
+    ],
     mapTitle: "WHAT THIS TOOL CAN DO. The full list of commands — not a retelling, the same list\nthe help is built from:",
     rulesTitle: (e) => `THE RULEBOOK OF THIS PROJECT (${e}) — verbatim, in full. This is not an invitation\nto read it: it is already here.`,
     hookAlready: (p) => `the hook is already in ${p} — changing nothing.`,
@@ -196,6 +216,7 @@ const enDocs = {
     },
   ],
   report: {
+    skippedBySelect: "not run (by --only/--skip), state unknown",
     title: "aqk doctor --run",
     version: "version",
     level: "level",

package/tool/i18n/en-gates.mjs

@@ -158,6 +158,7 @@ export const enGates = {
       "the guides in .aqk/docs/ are in Russian — a deliberate decision, not a broken install.\n  The rules in .aqk/rules/ are in English; the guides are prose an agent may ignore anyway,\n  and what a machine holds lives in .aqk.yml and the gates. Translation waits for someone who needs it.",
     created: (n) => `created (${n}):`,
     andMore: (n) => `… and ${n} more`,
+    ignored: (list) => `the kit's runtime files were added to .gitignore — machine state, it does not belong in git: ${list}`,
     kept: (n) => `already there, left untouched (${n}):`,
     overwrite: (cmd) => `overwrite: ${cmd}`,
     nextTitle: "What to do next, in order:",
@@ -255,16 +256,20 @@ export const enGates = {
     badEvery: (v) => `the manifest says probe: "${v}", which is not a commit count. The probe does NOT run: silently using the default would mean doing something other than what is written.`,
     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`,
+    autoNotInCi: (cmd) => `in CI the probe does not run by itself — it would be minutes of surprise in a fast check; run it as a separate job: ${cmd} (or AQK_PROBE=1)`,
     title: "aqk probe — what the declared checks cannot see",
     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.`,
+      `Project files are not changed; the probe result goes to .aqk/last-probe.md (in .gitignore after init).`,
     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)",
+    nameless: "did not name the planted file",
+    planting: "goes red on the green sample too — fails from the planting itself",
+    unattributed: (g) => `went red: ${g} — the catch is not proven`,
     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}`,

package/tool/i18n/en.mjs

@@ -44,6 +44,7 @@ export const en = {
     blob: "assemble the guides into a single GOD_AI.md",
     learn: "rule candidates from local transcripts: said out loud, never written down",
     context: "the project state in one block — for an agent's context, not for reading",
+    vitals: "is what the kit runs on wired up: gate tools, hooks, version freshness",
     contextInstall: "the same in full — the map and the rulebook — installed as a hook",
     report: "the mandatory report form: what is in place, what is not, what was not read; --since <ref> adds what proves the diff",
     badge: "a level badge for your README — and a check that it does not lie",
@@ -65,6 +66,14 @@ export const en = {
     gitignore: "repository hygiene",
     git: "project under version control",
 
+    runtimeTracked: (f, cmd) => `${f} is tracked by git — every run rewrites it, and the tree always shows a modified file. Take it out: ${cmd}`,
+    runtimeNotIgnored: (f, cmd) => `${f} is this machine's state, yet git sees it: one \`git add .\` and it is in a commit. Hide it: ${cmd}`,
+    layoutAdvice: "missing — advice, it does not fail the run",
+    coversImpossible: (entry, gate, linter) => `the claim "${gate} holds ${entry}" is wrong: ${linter} has no rule for this class — there is nothing to hold it with`,
+    coversCantCheck: (entry, gate) => `cannot check the claim "${gate} holds ${entry}": the gate's linter is not recognised or the entry has no rules for it — taken on trust`,
+    selectUnknown: (names, groups) => `--only/--skip: "${names}" is neither a gate from gates: nor a group from groups:${groups ? ` (groups: ${groups})` : ""}. Running everything instead of skipping would be a lie, so stopping.`,
+    selectSkipped: (names) => `not run (by --only/--skip): ${names} — their state is unknown, they are not "green"`,
+    jobsBad: (v) => `--jobs expects a whole number from 1: "${v}" will not do. A one-by-one run passed off as parallel would be a lie, so stopping.`,
     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.",
@@ -108,7 +117,9 @@ export const en = {
     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).`,
+    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 project files are not changed).`,
+    todoRest: (n) => `The other entries that apply here (${n}):`,
+    todoRestHow: (self) => `install any: ${self} add <name> · what it catches and why: ${self} why <name>`,
     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}`,
@@ -199,6 +210,7 @@ export const en = {
       has_docker: ["no Dockerfile or compose", "docker is already here"],
       has_deps: ["no dependency file in sight", "dependencies are declared"],
       has_tests: ["no tests in sight", "tests exist"],
+      has_biome: ["the linter is not Biome", "the project's linter is Biome"],
       has_env: ["no environment file", "an environment file exists"],
       has_agent_config: ["the agent was never configured here", "agent settings exist"],
       has_agent_entry: ["no entry point for an agent here", "an entry point for an agent exists"],

package/tool/i18n/ru-docs.mjs

@@ -68,7 +68,7 @@ const ruDocs = {
     runClean: (when) => `Последний прогон ${when} — красных нет.`,
     runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
     andMore: (n) => `и ещё ${n}`,
-    skipped: (n) => `Не запускались: ${n} — инструмента нет на этой машине, их состояние неизвестно.`,
+    skipped: (n) => `Не запускались: ${n} — пропущены по --only/--skip или инструмента нет на этой машине; их состояние неизвестно.`,
     probeNever: "Проба покрытия не делалась — что здесь не прикрыто ничем, НЕИЗВЕСТНО. Это не «прикрыто»: `aqk probe`.",
     probeOff: "Проба покрытия выключена в манифесте (`probe: 0`) — что здесь не прикрыто ничем, никто не считает.",
     probeUnknown: "Пробу покрытия провести не удалось — что здесь не прикрыто ничем, НЕИЗВЕСТНО. Это не «прикрыто».",
@@ -81,6 +81,28 @@ const ruDocs = {
       (behind ? ` (отстала на ${behind} коммитов)` : "") + ".",
     ratchets: (list) => `Храповики: ${list}. Список может только укорачиваться, увеличивать нельзя.`,
     where: (entry) => `Свод правил: ${entry}. Чем доказан диф: \`aqk report --since main\`.`,
+    nextTitle: "Дальше, по порядку — вычислено из этого репозитория, а не общий совет:",
+    // По виду шага — таблица, а не лесенка тернарников: её не держат в голове, и наш же
+    // complexity-limit её поймал.
+    nextStep: {
+      init: () => "Заведи стандарт: `aqk init` — без .aqk.yml `aqk add` откажет.",
+      adopt: (s) => `Объяви проверки, которые у проекта уже есть: в .aqk.yml, в gates: ${s.gates.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Затем \`aqk doctor --run\`.`,
+      blind: (s) => `Брак «${s.slug}», подсаженный пробой в ${s.file}, ваши проверки НЕ поймали.` +
+        (s.command ? ` Поймать сейчас: \`${s.command}\`.` : "") + ` Держать всегда: \`aqk add ${s.slug}\`.`,
+      start: (s) => `Поставь ${s.slug}: \`aqk add ${s.slug}\`` + (s.command ? ` (одной строкой, без комплекта: \`${s.command}\`)` : "") +
+        ", затем `aqk prove` — гейт обязан покраснеть на своём красном образце.",
+    },
+    nextMore: (n) => `И ещё ${n} — весь список: \`aqk doctor\`.`,
+    whenTitle: "Когда что делать:",
+    whenCommit: (hook) => hook === true
+      ? "Перед коммитом → хук `.git/hooks/pre-commit` прогонит проверки сам; не обходи его (`--no-verify`)."
+      : "Перед коммитом → `aqk doctor --run --since main`: хука перед коммитом нет, само это не случится.",
+    whenRules: [
+      "Добавил или поменял проверку → `aqk prove`: гейт обязан покраснеть на своём красном образце, иначе он не проверяет ничего.",
+      "Пишешь правило в свод → рядом метка арбитра `<!-- aqk: имя-гейта -->`; гейта нет — `<!-- aqk: человек -->`, и это признание, а не проверка.",
+      "Проверка мешает → не ослабляй её (`|| true`, `--exit-zero`, подавление без кода правила): остановись и спроси владельца.",
+      "Считаешь, что готово → `aqk report --since main`: каждый изменённый файл должен быть назван проверкой.",
+    ],
     mapTitle: "ЧТО УМЕЕТ ЭТОТ ИНСТРУМЕНТ. Полный список команд — не пересказ, а тот же список,\nиз которого собрана справка:",
     rulesTitle: (e) => `СВОД ПРАВИЛ ЭТОГО ПРОЕКТА (${e}) — дословно, целиком. Это не приглашение\nпрочитать: он уже здесь.`,
     hookAlready: (p) => `хук уже стоит в ${p} — ничего не меняю.`,
@@ -198,6 +220,7 @@ const ruDocs = {
     },
   ],
   report: {
+    skippedBySelect: "не запускался (по --only/--skip), состояние неизвестно",
     title: "aqk doctor --run",
     version: "версия",
     level: "уровень",

package/tool/i18n/ru-gates.mjs

@@ -160,6 +160,7 @@ export const ruGates = {
       "методички в .aqk/docs/ остаются на русском — решение, а не недоделка.",
     created: (n) => `создано (${n}):`,
     andMore: (n) => `… и ещё ${n}`,
+    ignored: (list) => `служебные файлы комплекта дописаны в .gitignore — это состояние машины, в git ему не место: ${list}`,
     kept: (n) => `уже были на месте, не тронуты (${n}):`,
     overwrite: (cmd) => `перезаписать: ${cmd}`,
     nextTitle: "Что дальше — по порядку:",
@@ -257,16 +258,20 @@ export const ruGates = {
     badEvery: (v) => `в манифесте probe: «${v}» — это не число коммитов. Проба НЕ делается: подставить умолчание значило бы делать не то, что написано.`,
     autoFirst: "пробы покрытия здесь ещё не делали — делаю её сам. Выключить: AQK_PROBE=0",
     auto: (n) => `прошло ${n} коммитов с прошлой пробы — делаю её сам. Выключить: AQK_PROBE=0`,
+    autoNotInCi: (cmd) => `в конвейере проба сама не запускается — это минуты сюрпризом в быстрой проверке; поставьте её отдельной задачей: ${cmd} (или AQK_PROBE=1)`,
     title: "aqk probe — чего объявленные проверки не видят",
     method: (files, entries, gates) =>
       `способ: красный образец записи каталога подсаживается в КОПИЮ проекта, и там гоняются ` +
       `ОБЪЯВЛЕННЫЕ гейты — команда берётся как написана, в неё ничего не подставляется. ` +
       `Файлов: ${files}, применимых записей: ${entries}, гейтов зелёных на чистом дереве: ${gates}. ` +
-      `Рабочее дерево не трогается.`,
+      `Файлы проекта не меняются; итог пробы пишется в .aqk/last-probe.md (он в .gitignore после init).`,
     fixes: (n) => `починок в истории: ${n}`,
     caught: (names) => `ловит: ${names}`,
     blind: "НЕ ЛОВИТ НИКТО",
     unknown: "проверить нечем — гейт не состоялся (нет делегированной программы)",
+    nameless: "не назвал подсаженный файл",
+    planting: "краснеет и на зелёном образце — падает от самой подсадки",
+    unattributed: (g) => `покраснело: ${g} — поимка не доказана`,
     blindWhere: (file, fixes) => `где: ${file} — починок в истории: ${fixes}`,
     blindWhat: "что подсадили в ваш файл:",
     blindFix: (cmd) => `поймать прямо сейчас, без комплекта:  ${cmd}`,

package/tool/i18n/ru.mjs

@@ -45,6 +45,7 @@ export const ru = {
     blob: "собрать методички в один файл GOD_AI.md",
     learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
     context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
+    vitals: "подключено ли то, чем комплект работает: инструменты гейтов, хуки, свежесть версии",
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
     report: "обязательная форма отчёта: что стоит, что нет, что не прочитано; --since <ссылка> — ещё и чем доказан диф",
     badge: "значок уровня для README — и проверка, что он не врёт",
@@ -66,6 +67,14 @@ export const ru = {
     gitignore: "гигиена репозитория",
     git: "проект под контролем версий",
 
+    runtimeTracked: (f, cmd) => `${f} отслеживается git — каждый прогон его переписывает, и в дереве вечно висит изменённый файл. Вынуть: ${cmd}`,
+    runtimeNotIgnored: (f, cmd) => `${f} — состояние этой машины, а git его видит: одно \`git add .\`, и он в коммите. Спрятать: ${cmd}`,
+    layoutAdvice: "нет — это совет, прогон не роняет",
+    coversImpossible: (entry, gate, linter) => `заявка «${gate} держит ${entry}» неверна: у ${linter} нет правила под этот класс — закрывать его нечем`,
+    coversCantCheck: (entry, gate) => `заявку «${gate} держит ${entry}» проверить не умею: линтер гейта не распознан или правил записи для него нет — принято на слово`,
+    selectUnknown: (names, groups) => `--only/--skip: не знаю «${names}» — это не гейт из gates: и не группа из groups:${groups ? ` (группы: ${groups})` : ""}. Прогон всего подряд вместо пропуска был бы неправдой, поэтому стоп.`,
+    selectSkipped: (names) => `не запускались (по --only/--skip): ${names} — их состояние неизвестно, это не «зелёные»`,
+    jobsBad: (v) => `--jobs ждёт целое число от 1: «${v}» не подходит. Прогон по одному под видом параллельного был бы неправдой, поэтому стоп.`,
     rulesByHuman: (total, machine, human) =>
       `правил в точке входа: ${total}. Сторож — ЧЕЛОВЕК у ${human}, машина у ${machine}.`,
     rulesByHumanWhy: "Правило со сторожем-человеком не сторожит никто в тот день, когда человек занят. Это та самая дыра, ради которой комплект и написан, — и напоминание про неё нужно человеку, а не только агенту. Считаны правила ТОЧКИ ВХОДА: обещание, живущее в любом другом файле, не проверяет вообще ничто, и комплект даже не скажет вам, что оно есть.",
@@ -109,7 +118,9 @@ export const ru = {
     blindRan: (g) => `гейт ${g} стоит и прогонялся — а брак в этом файле пропустил`,
     blindInstalled: "объявлено, но проба этот гейт не гоняла (поставлен позже или медленный) — поймает ли, покажет следующая",
     blindMore: (cmd) => `что именно подсадили и куда — ${cmd}`,
-    probeNever: (cmd) => `Ловят ли ваши проверки настоящий брак, ещё не проверялось: ${cmd} подсадит его в копию проекта и покажет (минута-две, рабочие файлы не трогает).`,
+    probeNever: (cmd) => `Ловят ли ваши проверки настоящий брак, ещё не проверялось: ${cmd} подсадит его в копию проекта и покажет (минута-две, файлы проекта не меняет).`,
+    todoRest: (n) => `Остальные записи, применимые у вас (${n}):`,
+    todoRestHow: (self) => `поставить любую: ${self} add <имя> · что она ловит и зачем: ${self} why <имя>`,
     startWith: "Начните с этих трёх — они родились из настоящего отказа и закрываются одной готовой командой:",
     startCmd: (cmd) => `одной строкой, без комплекта:  ${cmd}`,
     startTool: (url) => `инструмент: ${url}`,
@@ -205,6 +216,7 @@ export const ru = {
       has_docker: ["нет Dockerfile или compose", "docker уже есть"],
       has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
       has_tests: ["не видно тестов", "тесты есть"],
+      has_biome: ["линтер не Biome", "линтер проекта — Biome"],
       has_env: ["нет файла окружения", "файл окружения есть"],
       has_agent_config: ["агента здесь не настраивали", "настройки агента есть"],
       has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],

package/tool/lib/adopt.mjs

@@ -95,4 +95,18 @@ function proposeGates(files = {}) {
 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 };
+// Чтение с диска — отдельно от разбора: разбор проверяется перебором случаев, чтение — прогоном.
+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

@@ -89,4 +89,14 @@ function parseRan(text) {
   return m ? new Set(m[1].split(/\s+/).filter(Boolean)) : null;
 }
 
-export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan };
+// Запускаться ли пробе САМОЙ внутри `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/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

@@ -117,9 +117,36 @@ function probeSummary({ caught = 0, blind = 0, unknown = 0, unprobed = 0 } = {})
 // Найдено пробой на самом комплекте 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, brokenByPlant = 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);
@@ -130,10 +157,12 @@ function probeVerdictPaired(before, after) {
     }
     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 = caught ? "caught" : !usable || brokenByPlant ? "unknown" : "blind";
-  return { verdict, usable, alreadyRed, failed, caught, brokenByPlant };
+  const verdict = caught ? "caught" : !usable || brokenByPlant || unattributed ? "unknown" : "blind";
+  return { verdict, usable, alreadyRed, failed, caught, brokenByPlant, unattributed };
 }
 
 // Счёт непокрытого КЛАССАМИ, а не пробами. Замер на десяти живых репозиториях 2026-09-10:
@@ -160,4 +189,4 @@ function countProbe(records) {
   };
 }
 
-export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe };
+export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe, namesPlant, catchVerdict };