agent-quality-kit 0.11.0 → 0.13.0

package/tool/commands/probe.mjs

@@ -22,14 +22,17 @@
 // не порог. Порог — у `doctor --run --min`.
 import { spawnSync } from "node:child_process";
 import { mkdtemp, mkdir, copyFile, rm, readdir, writeFile, readFile, symlink } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, extname } from "node:path";
 import { readManifest } from "../lib/manifest.mjs";
-import { fixHotspots, probeSummary, probeVerdictPaired, countProbe } from "../lib/history.mjs";
+import { fixHotspots, probeSummary, probeVerdictPaired, countProbe, namesPlant, catchVerdict } from "../lib/history.mjs";
 import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
+import { blindAdvice } from "../lib/advice.mjs";
 import { CWD, GATES_SRC, TARGET_DIR, c, SELF, exists } from "../lib/core.mjs";
-import { probeState, probeEvery, PROBE_EVERY } from "../lib/cadence.mjs";
+import { probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan } from "../lib/cadence.mjs";
 import { L } from "../i18n/index.mjs";
+import { gateCommand } from "../lib/execution.mjs";
 
 // Тот же набор расширений, что у привязки доказательства к дифу. Список один на программу:
 // второй через месяц разошёлся бы с первым.
@@ -93,7 +96,7 @@ async function writeMark(now, blind, lines) {
     "",
     ...lines,
     "",
-    "Файл эфемерный: его переписывает каждая проба. В .gitignore его стоит держать самому.",
+    "Файл эфемерный: его переписывает каждая проба. `aqk init` кладёт его в .gitignore.",
   ].join("\n");
   await writeFile(MARK(), body + "\n", "utf8");
 }
@@ -137,11 +140,28 @@ function extAlternatives(ext) {
   return fam ? [ext, ...fam.filter((e) => e !== ext)] : [ext];
 }
 
+// Показать САМ ОБРАЗЕЦ, а не пересказ. «Класс не прикрыт» остаётся словами, пока человек не
+// увидел, что именно мы подсадили в его файл.
+//
+// Первая версия печатала одну «показательную» строку — и угадывала плохо: у мёртвого кода дефект
+// во ВТОРОЙ функции, у отладочной печати во второй строке тела. Угадывать не надо: образцы
+// каталога маленькие по норме, и четырёх строк хватает, чтобы стало видно. Комментарии
+// выброшены: в наших образцах они объясняют замысел коллеге, а не показывают дефект.
+function sampleLines(path, max = 4) {
+  let text = "";
+  try { text = readFileSync(path, "utf8"); } catch { return []; }
+  return text.split("\n")
+    .map((l) => l.replace(/\s+$/, ""))
+    .filter((l) => l.trim() && !/^\s*(#|\/\/|\/\*|\*|--|<!--)/.test(l))
+    .slice(0, max)
+    .map((l) => l.slice(0, 88));
+}
+
 // Красный образец записи, подходящий по расширению горячего файла. Расширение обязано
 // совпадать: питоновский образец в проекте на TypeScript не проверит ничего, а покажет
 // «не прикрыто» — ложная тревога того же класса, что молчащий гейт, только наоборот.
-async function redSampleFor(entry, ext) {
-  const dir = join(GATES_SRC, entry, "red");
+async function sampleFor(entry, ext, kind = "red") {
+  const dir = join(GATES_SRC, entry, kind);
   if (!(await exists(dir))) return null;
   let names = [];
   try { names = await readdir(dir); } catch { return null; }
@@ -160,7 +180,8 @@ async function redSampleFor(entry, ext) {
 //
 // Способ взят из мутационного тестирования, где та же задача решена двадцать лет назад: Stryker
 // копирует проект во временный каталог, СИМЛИНКУЕТ `node_modules` и гоняет там родную команду.
-// Копируются только ОТСЛЕЖИВАЕМЫЕ файлы (`git archive HEAD`) — рабочее дерево не трогается, а
+// Копируются отслеживаемые и неигнорируемые файлы (`git ls-files --cached --others
+// --exclude-standard`) — файлы проекта не меняются (итог пишется в .aqk/last-probe.md), а
 // мусор сборки не тащится; тяжёлые каталоги зависимостей симлинкуются, иначе `npm test` в
 // песочнице падал бы с «модуль не найден», и это читалось бы как сбой инструмента.
 const DEP_DIRS = ["node_modules", ".venv", "venv", "vendor", "target", ".tox", ".bundle"];
@@ -218,20 +239,44 @@ async function plant(root, relPath, sample) {
 // Гейт запускается В ПЕСОЧНИЦЕ и командой КАК ЕСТЬ — ничего в неё не подставляется. Именно это
 // и делает пробу независимой от формы команды.
 //
-// `stopOnRed` — ранний выход: как только гейт покраснел, вердикт «поймано» уже получен, и гонять
-// остальные незачем. На сухом прогоне выхода нет: там нужны ВСЕ длительности и все коды.
-function runGates(gates, sandbox, { stopOnRed = false } = {}) {
+// Вывод гейта сохраняется: по нему видно, ИЗ-ЗА ЧЕГО он покраснел (см. catchVerdict).
+function runGates(gates, sandbox) {
   const out = [];
   for (const [name, cmd] of gates) {
     const t0 = Date.now();
-    const r = spawnSync(cmd, { shell: true, cwd: sandbox, encoding: "utf8", timeout: 120000 });
+    const r = spawnSync(gateCommand(cmd), { shell: true, cwd: sandbox, encoding: "utf8", timeout: 120000 });
     const code = r.status === null ? 2 : r.status;
-    out.push({ name, code, ms: Date.now() - t0 });
-    if (stopOnRed && code === 1) break;
+    out.push({ name, code, ms: Date.now() - t0, out: `${r.stdout || ""}${r.stderr || ""}`.slice(0, 200000) });
   }
   return out;
 }
 
+// Один класс брака на одном файле: гейты по одному, в порядке плана. Покраснел и назвал файл —
+// контроль ЗЕЛЁНЫМ образцом той же записи в том же месте (catchVerdict). Ранний выход — только на
+// ПОДТВЕРЖДЁННОЙ поимке: первым мог покраснеть форматтер, и остановка на нём скрыла бы линтер,
+// который брак действительно поймал.
+async function probeOne({ sandbox, rel, red, green, gates, baseOut }) {
+  const after = [];
+  let restore = await plant(sandbox, rel, red);
+  try {
+    for (const g of gates) {
+      const [res] = runGates([g], sandbox);
+      after.push(res);
+      if (res.code !== 1) continue;
+      let ctl = null;
+      if (green && namesPlant(baseOut(res.name), res.out, rel)) {
+        await restore(); restore = await plant(sandbox, rel, green);
+        [ctl] = runGates([g], sandbox);
+        await restore(); restore = await plant(sandbox, rel, red);
+      }
+      res.why = catchVerdict(baseOut(res.name), res, ctl, rel);
+      res.named = res.why === "caught";
+      if (res.named) break;
+    }
+  } finally { await restore(); }
+  return after;
+}
+
 // Каким гейтом пробовать и в каком порядке.
 //
 // Цена пробы = (файлы × записи) × сумма длительностей гейтов. На самом комплекте после перехода
@@ -302,7 +347,8 @@ async function cmdProbe(args, { auto = false } = {}) {
   // Пробуем только запланированными, в порядке плана.
   const byName = new Map(gates);
   const probeGates = plan.use.map((g) => [g.name, byName.get(g.name)]);
-  const baseline = plan.use.map((g) => ({ name: g.name, code: g.code }));
+  const baseline = plan.use.map((g) => ({ name: g.name, code: g.code, out: g.out }));
+  const baseOut = (name) => baseline.find((b) => b.name === name)?.out || "";
 
   console.log(c.dim(`  ${P.method(hot.length, entries.length, plan.use.length)}\n`));
   if (plan.tooSlow.length) {
@@ -319,28 +365,41 @@ async function cmdProbe(args, { auto = false } = {}) {
     let probed = 0;
 
     for (const e of entries) {
-      const sample = await redSampleFor(e.slug, ext);
+      const sample = await sampleFor(e.slug, ext, "red");
       if (!sample) continue;
       probed++;
-      const restore = await plant(sandbox, rel, sample);
-      let after;
-      try { after = runGates(probeGates, sandbox, { stopOnRed: true }); } finally { await restore(); }
+      const green = await sampleFor(e.slug, ext, "green");
+      const after = await probeOne({ sandbox, rel, red: sample, green, gates: probeGates, baseOut });
       // Ранний выход обрывает список: гейты, до которых не дошли, считаются такими же, как на
       // сухом прогоне. Иначе их отсутствие прочиталось бы как сбой запуска.
       const seen = new Set(after.map((a) => a.name));
       const full = after.concat(baseline.filter((b) => !seen.has(b.name)));
       const r = probeVerdictPaired(baseline, full);
       const verdict = r.verdict;
-      const caught = full.filter((a) => a.code === 1 && baseline.find((b) => b.name === a.name)?.code === 0)
-        .map((a) => a.name);
+      const redNow = full.filter((a) => a.code === 1 && baseline.find((b) => b.name === a.name)?.code === 0);
+      const caught = redNow.filter((a) => a.named !== false).map((a) => a.name);
+      const nameless = redNow.filter((a) => a.named === false).map((a) => `${a.name} (${a.why === "planting" ? P.planting : P.nameless})`);
       records.push({ entry: e.slug, file: rel, verdict });
       if (verdict === "caught") {
         console.log(`    ${c.green("✔")}  ${e.intent.padEnd(48)} ${c.dim(P.caught(caught.join(", ")))}`);
       } else if (verdict === "blind") {
         console.log(`    ${c.red("✘")}  ${e.intent.padEnd(48)} ${c.red(P.blind)}`);
+        // Объяснить, а не назвать. Три строки, каждая отвечает на свой вопрос человека:
+        // «почему именно здесь», «что вы вообще подсадили» и «что мне сделать ПРЯМО СЕЙЧАС».
+        // Последняя обязана работать БЕЗ комплекта: польза до установки — единственный
+        // способ заслужить установку.
+        const adv = blindAdvice(e, facts, { file: rel, fixes });
+        console.log(c.dim(`         ${P.blindWhere(rel, fixes)}`));
+        const lines = sampleLines(sample);
+        if (lines.length) {
+          console.log(c.dim(`         ${P.blindWhat}`));
+          for (const l of lines) console.log(c.dim(`           ${l}`));
+        }
+        if (adv.command) console.log(`         ${c.yellow(P.blindFix(adv.command))}`);
+        if (adv.tool) console.log(c.dim(`         ${P.blindTool(adv.tool)}`));
         console.log(c.dim(`         ${P.install(`${SELF} add ${e.slug}`)}`));
       } else {
-        console.log(`    ${c.dim("~")}  ${c.dim(e.intent.padEnd(48))} ${c.dim(P.unknown)}`);
+        console.log(`    ${c.dim("~")}  ${c.dim(e.intent.padEnd(48))} ${c.dim(nameless.length ? P.unattributed(nameless.join(", ")) : P.unknown)}`);
       }
     }
     if (!probed) { unprobedN++; console.log(c.dim(`    ${P.noSampleFor(ext || "—")}`)); }
@@ -362,7 +421,11 @@ async function cmdProbe(args, { auto = false } = {}) {
 
   // Отметка нужна не для отчёта, а для КАДЕНЦИИ: по ней следующий прогон поймёт, что пора.
   // Без неё команда снова становится тем, о чём надо вспомнить.
-  await writeMark(commitCount(), blind, hot.map(({ path: p2, fixes }) => `- ${p2} (${P.fixes(fixes)})`));
+  await writeMark(commitCount(), blind, [
+    `ran: ${probeGates.map(([name]) => name).join(" ")}`, "",
+    ...blindLines(records), "",
+    ...hot.map(({ path: p2, fixes }) => `- ${p2} (${P.fixes(fixes)})`),
+  ]);
   } finally {
     await rm(sandbox, { recursive: true, force: true });
   }
@@ -378,7 +441,8 @@ async function probeStatus() {
   const every = probeEvery(man);
   if (every === null) return { state: "unknown", behind: null, badEvery: String(man?.probe) };
   if (every === 0) return { state: "off", behind: null };
-  return probeState(await readMark(), commitCount(), every);
+  const mark = await readMark();
+  return { ...probeState(mark, commitCount(), every), classes: parseBlind(mark?.text), ran: parseRan(mark?.text) };
 }
 
 export { cmdProbe, probeStatus, probeableGates, gatesState, extAlternatives, planProbeGates, isCode };

package/tool/commands/project.mjs

@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
 import { join, dirname, relative } from "node:path";
 import {
   CWD, PKG_ROOT, DOCS_SRC, RULES_SRC, TARGET_DIR, MANIFEST, SELF, REPO_URL, c, exists, die,
-  copyDir, writeIfAbsent, FEEDBACK_MARK, docPath } from "../lib/core.mjs";
+  copyDir, writeIfAbsent, FEEDBACK_MARK, docPath, ensureIgnored } from "../lib/core.mjs";
 import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
 import { banner } from "../lib/banner.mjs";
 import { readManifest } from "../lib/manifest.mjs";
@@ -41,6 +41,10 @@ async function cmdInit(args) {
   const claude = join(CWD, "CLAUDE.md");
   track(await writeIfAbsent(claude, CLAUDE_MD, { force }), claude);
 
+  // Служебные файлы — в .gitignore сразу, до первого прогона: иначе первый же `doctor --run`
+  // оставит в дереве файл, который попадёт в коммит (так и случилось на живом проекте).
+  const ignored = await ensureIgnored(CWD);
+
   // Заставка в начале init — первая встреча человека с комплектом. Второй раз он увидит её
   // только если сам спросит `--version`: то, что видишь тридцатый раз, перестаёт читаться.
   console.log(`\n${banner()}\n`);
@@ -56,6 +60,7 @@ async function cmdInit(args) {
   if (LANG === "en" && created.some((f) => f.includes(`${TARGET_DIR}/docs/`) || f.includes(`${TARGET_DIR}\\docs\\`))) {
     console.log(c.dim(`\n  ${L.init.docsRu}`));
   }
+  if (ignored.length) console.log(c.dim(`\n  ${L.init.ignored(ignored.join(", "))}`));
   if (skipped.length) {
     console.log(c.yellow(`\n  ${L.init.kept(skipped.length)}`));
     for (const f of skipped) console.log(`    ${f}`);

package/tool/commands/report.mjs

@@ -86,7 +86,7 @@ async function cmdReport() {
 
   // Прогон, а не чтение манифеста: «объявлен» и «работает» — разные утверждения, и весь
   // смысл этой команды в том, чтобы в отчёт попало второе.
-  const run = declared.length ? runGates(man) : { results: [], failed: 0 };
+  const run = declared.length ? await runGates(man) : { results: [], failed: 0 };
 
   const held = [], broken = [], todo = [], skip = [];
   for (const res of run.results) {

package/tool/commands/vitals.mjs

@@ -16,11 +16,13 @@
 // сознательное решение: pre-commit локально мы не ставим, проверки идут в CI. Команда, которая
 // кричит «сломано» про выбор, — ровно та, которую выключают в первый день, и вместе с ней
 // перестают читать настоящие отказы. Кода возврата касается только `✘`.
+import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CWD, MANIFEST, SELF, c, exists } from "../lib/core.mjs";
+import { CWD, MANIFEST, SELF, c, exists, preCommitHook } from "../lib/core.mjs";
 import { readManifest, unparsedLines, gateRequires } from "../lib/manifest.mjs";
 import { whichSync } from "../lib/repo.mjs";
+import { gitBash } from "../lib/execution.mjs";
 import { updateWanted } from "../lib/brief.mjs";
 import { L } from "../i18n/index.mjs";
 
@@ -94,7 +96,11 @@ async function cmdVitals() {
   for (const [gate, cmd] of Object.entries(gates)) {
     const prog = progOf(cmd);
     if (!prog || seen.has(prog)) continue;
-    seen.set(prog, { gate, prog, found: Boolean(whichSync(prog)) });
+    // На Windows слово `bash` в PATH — часто заглушка WSL, и «найден» было бы неправдой: гейт
+    // запустится через Git Bash (gateCommand) или не запустится вовсе. Спрашиваем того же, кого
+    // спросит прогон, — иначе vitals и doctor --run снова разойдутся.
+    const found = prog === "bash" && process.platform === "win32" ? Boolean(gitBash()) : Boolean(whichSync(prog));
+    seen.set(prog, { gate, prog, found });
   }
 
   // Первого слова мало. Запись каталога бывает обёрткой: команда начинается с `bash`, который
@@ -117,14 +123,7 @@ async function cmdVitals() {
   // Хук pre-commit проверяется в `.git/hooks`, а НЕ в `.pre-commit-config.yaml`. Запись в
   // конфиге — это намерение; сработает только то, что лежит в самом гите. Ровно та разница,
   // ради которой весь комплект: объявлено и работает — разные утверждения.
-  let preCommit = null;
-  const hook = join(CWD, ".git", "hooks", "pre-commit");
-  if (await exists(join(CWD, ".git"))) {
-    preCommit = false;
-    if (await exists(hook)) {
-      try { preCommit = /pre-commit|aqk/i.test(await readFile(hook, "utf8")); } catch { preCommit = null; }
-    }
-  }
+  const preCommit = await preCommitHook(CWD);
 
   let sessionHook = null;
   const settings = join(CWD, ".claude", "settings.json");
@@ -140,15 +139,25 @@ async function cmdVitals() {
 
   let version = null;
   if (updateWanted()) {
+    let current = "";
     try {
       const { PKG_ROOT } = await import("../lib/core.mjs");
-      const current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || "";
+      current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || "";
       const r = await fetch("https://registry.npmjs.org/agent-quality-kit/latest", {
         signal: AbortSignal.timeout(3000),
         headers: { accept: "application/vnd.npm.install-v1+json" },
       });
       version = { current, latest: r.ok ? String((await r.json()).version || "") : "" };
-    } catch { /* сети нет — строку про версию просто не покажем */ }
+    } catch { /* прямой запрос не прошёл — ниже спросим npm */ }
+    // ПРЯМОЙ ЗАПРОС НЕ ПРОШЁЛ — СПРОСИТЬ NPM. Отзыв с живого проекта 2026-09-11: vitals писал «не
+    // достучался до реестра», а `npm view` на той же машине работал. `fetch` в Node не знает
+    // прокси и зеркала из .npmrc, а npm знает. Только здесь, не в хуке: там секунды дороже.
+    if (current && !version?.latest) {
+      const r = spawnSync("npm", ["view", "agent-quality-kit", "version"],
+        { encoding: "utf8", timeout: 10000, shell: process.platform === "win32" });
+      const latest = r.status === 0 ? String(r.stdout || "").trim().split("\n").pop() : "";
+      version = { current, latest };
+    }
   }
 
   const rows = vitalsRows({ tools: [...seen.values()], unparsed, preCommit, sessionHook, version });

package/tool/i18n/en-docs.mjs

@@ -66,18 +66,39 @@ 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\".",
-    probeBlind: (n, behind) =>
+    probeBlind: (n, behind, names = "") =>
       `Covered by nothing: ${n} defect classes in the places people most often come back to fix` +
+      (names ? ` — ${names}` : "") +
       (behind ? ` (the probe is ${behind} commits behind)` : "") + ". Details: `aqk probe`.",
     probeClean: (behind) =>
       "Coverage probe: in the places probed, every applicable class is caught by something" +
       (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.`,
@@ -195,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,24 @@ 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}`,
+    blindTool: (url) => `the tool: ${url}`,
     install: (cmd) => `close it: ${cmd}`,
     noSampleFor: (ext) => `the catalogue has no red sample for "${ext}" — nothing to check with`,
     noGates: (cmd) => `no gates declared — nothing to probe with. First: ${cmd}`,

package/tool/i18n/en.mjs

@@ -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.",
@@ -104,6 +113,19 @@ export const en = {
       `claim unverified: "${e}" is declared held by gate "${g}", but neither its command nor the\n  linter config names rules ${codes} — the entry may be held by nothing`,
     coversUnprovenHow: (cmd) => `settle it: add those rules to the linter, or install the entry — ${cmd}`,
     totalCovered: (n) => `held by another arbiter ${n}`,
+    blindHeading: (behind) => `The probe${behind ? ` (${behind} commits ago)` : ""} planted defects in your files — your checks did NOT catch them:`,
+    blindRan: (g) => `gate ${g} is declared and was run — and still missed the defect in this file`,
+    blindInstalled: "declared, but the probe did not run this gate (added later or too slow) — the next probe will show whether it catches",
+    blindMore: (cmd) => `what was planted and where — ${cmd}`,
+    probeNever: (cmd) => `Whether your checks catch a real defect has not been tested yet: ${cmd} plants one in a copy of the project and shows (a minute or two, your 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}`,
+    startHook: "Running these by hand is a one-off. To have them run before every push: pre-commit (repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit, hooks aqk / aqk-doctor), or a plain .git/hooks/pre-push.",
+    haveAlready: (n) => `Checks you ALREADY have (${n}) — found in your own files, not invented:`,
+    haveAlreadyHow: (line) => `declare them and a machine holds them, not your attention. In .aqk.yml, under gates:  ${line}`,
     total: "Total:",
     totalHeld: (n) => `held by a machine ${n}`,
     totalTodo: (n) => `applicable but not installed ${n}`,
@@ -120,6 +142,8 @@ export const en = {
       `either fix them and drop them from advisory, or admit the rule does not exist.`,
     runHeading: "Running the declared gates",
     timeout: "did not finish within 5 minutes",
+    running: (i, n) => `[${i}/${n}] running…`,
+    proving: "checking that the gates catch defects on their own samples…",
     exitCode: (code) => `exit ${code}`,
     moreLines: (n) => `… and ${n} more lines`,
     declaredNotRun: (n) => `${n} gates declared, but never run.`,
@@ -186,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,18 +68,41 @@ 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: "Пробу покрытия провести не удалось — что здесь не прикрыто ничем, НЕИЗВЕСТНО. Это не «прикрыто».",
-    probeBlind: (n, behind) =>
+    probeBlind: (n, behind, names = "") =>
       `Не прикрыто ничем: ${n} классов брака в местах, куда чаще всего возвращаются с починкой` +
+      (names ? ` — ${names}` : "") +
       (behind ? ` (проба отстала на ${behind} коммитов)` : "") + ". Подробно: `aqk probe`.",
     probeClean: (behind) =>
       "Проба покрытия: в проверенных местах каждый применимый класс кто-то ловит" +
       (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} — ничего не меняю.`,
@@ -197,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,24 @@ 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}`,
+    blindTool: (url) => `инструмент: ${url}`,
     install: (cmd) => `закрыть: ${cmd}`,
     noSampleFor: (ext) => `в каталоге нет красного образца под «${ext}» — проверить нечем`,
     noGates: (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: "Правило со сторожем-человеком не сторожит никто в тот день, когда человек занят. Это та самая дыра, ради которой комплект и написан, — и напоминание про неё нужно человеку, а не только агенту. Считаны правила ТОЧКИ ВХОДА: обещание, живущее в любом другом файле, не проверяет вообще ничто, и комплект даже не скажет вам, что оно есть.",
@@ -105,6 +114,19 @@ 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} подсадит его в копию проекта и покажет (минута-две, файлы проекта не меняет).`,
+    todoRest: (n) => `Остальные записи, применимые у вас (${n}):`,
+    todoRestHow: (self) => `поставить любую: ${self} add <имя> · что она ловит и зачем: ${self} why <имя>`,
+    startWith: "Начните с этих трёх — они родились из настоящего отказа и закрываются одной готовой командой:",
+    startCmd: (cmd) => `одной строкой, без комплекта:  ${cmd}`,
+    startTool: (url) => `инструмент: ${url}`,
+    startHook: "Прогнать руками — разовый героизм. Чтобы это случалось перед каждым пушем: pre-commit (репозиторий https://github.com/arsen-ask-lx/Agent_Quality_Kit, хуки aqk / aqk-doctor) либо обычный .git/hooks/pre-push.",
+    haveAlready: (n) => `Проверки, которые у вас УЖЕ ЕСТЬ (${n}) — прочитаны в ваших файлах, не выдуманы:`,
+    haveAlreadyHow: (line) => `объявите их — и держать будет машина, а не ваше внимание. В .aqk.yml, в gates:  ${line}`,
     total: "Итого:",
     totalHeld: (n) => `держит машина ${n}`,
     totalTodo: (n) => `применимо но не поставлено ${n}`,
@@ -121,6 +143,8 @@ export const ru = {
       `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
+    running: (i, n) => `[${i}/${n}] идёт…`,
+    proving: "проверяю, что гейты ловят брак на своих образцах…",
     exitCode: (code) => `код ${code}`,
     moreLines: (n) => `… и ещё ${n} строк`,
     declaredNotRun: (n) => `${n} гейтов объявлено, но не запускалось.`,
@@ -192,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: ["свода для агента здесь нет", "свод для агента есть"],