agent-quality-kit 0.8.0 → 0.10.0

package/tool/commands/probe.mjs

@@ -0,0 +1,228 @@
+// tool/commands/probe.mjs — `aqk probe`: чего объявленные проверки НЕ видят.
+//
+// ЗАЧЕМ ЭТО ОТДЕЛЬНАЯ КОМАНДА. `doctor` отвечает «держит машина 21». Двадцать один из чего?
+// Знаменателя нет: 21 — это то, что мы успели написать в каталог, а не то, что важно в этом
+// проекте. `prove` доказывает, что гейт ловит брак НА СВОЁМ образце. Ни один из них не
+// отвечает на вопрос владельца: «что у меня не прикрыто вообще».
+//
+// Замер, с которого команда началась, — на самом комплекте, 2026-09-09. Взят настоящий файл
+// проекта, в копию подсажены проглоченная ошибка и отладочная печать, прогнаны ВСЕ 21
+// сканирующих гейта из манифеста. Покраснело: ноль. У проекта с AQK-3 есть брак, невидимый
+// всем его проверкам, — и узнать об этом было нечем.
+//
+// КАК УСТРОЕНО. Два источника, и оба — факты, а не наш вкус:
+//   1. история репозитория: где брак ВОЗВРАЩАЕТСЯ (коммиты-починки, `history.mjs`);
+//   2. красные образцы каталога: каждый доказан прогоном, каждый — настоящий брак.
+// Образец кладётся во временный каталог по пути горячего файла, и по нему прогоняются
+// ОБЪЯВЛЕННЫЕ гейты проекта. Никто не покраснел — класс не прикрыт, и это доказано, а не
+// выведено из списка.
+//
+// ЧЕГО КОМАНДА НЕ ДЕЛАЕТ. Не трогает рабочее дерево: проба живёт в каталоге mkdtemp и
+// удаляется. Не меняет манифест. Не роняет прогон: код возврата всегда 0 — это осмотр, а
+// не порог. Порог — у `doctor --run --min`.
+import { spawnSync } from "node:child_process";
+import { mkdtemp, mkdir, copyFile, rm, readdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname, extname } from "node:path";
+import { readManifest } from "../lib/manifest.mjs";
+import { commandFor } from "../lib/prove.mjs";
+import { fixHotspots, probeVerdict } from "../lib/history.mjs";
+import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
+import { CWD, GATES_SRC, TARGET_DIR, c, SELF, exists } from "../lib/core.mjs";
+import { probeState, probeEvery, PROBE_EVERY } from "../lib/cadence.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Тот же набор расширений, что у привязки доказательства к дифу. Список один на программу:
+// второй через месяц разошёлся бы с первым.
+const CODE_EXT = new Set([
+  "c", "cjs", "cpp", "cs", "css", "go", "h", "java", "js", "json", "jsx", "kt", "mjs", "mts",
+  "php", "pl", "py", "rb", "rs", "scala", "sh", "sql", "swift", "ts", "tsx", "vue",
+]);
+
+const isCode = (p) =>
+  CODE_EXT.has(extname(p).slice(1).toLowerCase()) &&
+  !/(^|\/)gates\/[^/]+\/(red|green)(\/|$)/.test(p);
+
+// Мелкий клон истории не содержит. `fetch-depth: 2` в конвейере — обычная настройка, и на нём
+// рейтинг починок пуст ВСЕГДА. Сказать там «коммитов-починок не найдено» значит выдать
+// отсутствие данных за факт о репозитории: та же подмена, что «зелено, потому что не
+// проверялось». Найдено собственным конвейером 2026-09-09.
+function isShallow() {
+  const r = spawnSync("git", ["rev-parse", "--is-shallow-repository"], { cwd: CWD, encoding: "utf8" });
+  return r.status === 0 && String(r.stdout || "").trim() === "true";
+}
+
+// История берётся одним вызовом: тема коммита и его файлы. Слияния исключены — в них файлы
+// второй ветки, а починку делали не в них.
+function gitLog(limit) {
+  const r = spawnSync(
+    "git",
+    ["log", "--no-merges", `--max-count=${limit}`, "--format=%s", "--name-only"],
+    { cwd: CWD, encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
+  );
+  return r.status === 0 ? r.stdout || "" : null;
+}
+
+// Сколько коммитов в репозитории сейчас. Единица каденции — коммиты, а не сутки: месяц без
+// работы перепроверять незачем, а сто коммитов за день — надо.
+function commitCount() {
+  const r = spawnSync("git", ["rev-list", "--count", "HEAD"], { cwd: CWD, encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const n = Number(String(r.stdout || "").trim());
+  return Number.isFinite(n) ? n : null;
+}
+
+const MARK = () => join(CWD, TARGET_DIR, "last-probe.md");
+
+// Отметка о прошлой пробе. Формат человеческий намеренно: файл читают глазами и агентом,
+// а не только программой. Разбирается одна строка — та, что несёт число коммитов.
+async function readMark() {
+  try {
+    const text = await readFile(MARK(), "utf8");
+    const m = /^at:\s*(\d+)/m.exec(text);
+    return m ? { at: Number(m[1]), text } : {};
+  } catch { return null; }
+}
+
+async function writeMark(now, blind, lines) {
+  await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+  const body = [
+    "# Проба покрытия — что объявленные проверки НЕ видят",
+    "",
+    `at: ${now === null ? "?" : now}`,
+    `blind: ${blind}`,
+    "",
+    ...lines,
+    "",
+    "Файл эфемерный: его переписывает каждая проба. В .gitignore его стоит держать самому.",
+  ].join("\n");
+  await writeFile(MARK(), body + "\n", "utf8");
+}
+
+// Гейты, которым можно подставить каталог. Команда записи каталога кончается каталогом
+// проверки; написанная руками — чем угодно, и подставлять там некуда. Ровно то же правило,
+// по которому `prove` объявляет запись недоказуемой, а не сломанной.
+function scanningGates(man) {
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  return Object.entries(gates)
+    .map(([name, raw]) => [name, String(raw || "").trim()])
+    .filter(([, cmd]) => cmd && /(\.|\.\/)$/.test(cmd));
+}
+
+// Красный образец записи, подходящий по расширению горячего файла. Расширение обязано
+// совпадать: питоновский образец в проекте на TypeScript не проверит ничего, а покажет
+// «не прикрыто» — ложная тревога того же класса, что молчащий гейт, только наоборот.
+async function redSampleFor(entry, ext) {
+  const dir = join(GATES_SRC, entry, "red");
+  if (!(await exists(dir))) return null;
+  let names = [];
+  try { names = await readdir(dir); } catch { return null; }
+  const hit = names.find((n) => extname(n).toLowerCase() === ext);
+  return hit ? join(dir, hit) : null;
+}
+
+// Проба: временный каталог, в нём образец по пути горячего файла. Путь сохраняется целиком —
+// правила, привязанные к путям (`.aqkignore`, исключения гейтов), обязаны действовать так же,
+// как в настоящем репозитории. Без этого проба отвечала бы про несуществующее место.
+async function buildProbe(relPath, sample) {
+  const root = await mkdtemp(join(tmpdir(), "aqk-probe-"));
+  const dest = join(root, relPath);
+  await mkdir(dirname(dest), { recursive: true });
+  await copyFile(sample, dest);
+  // Переносится ТОЛЬКО .aqkignore: правила, привязанные к путям, обязаны действовать так же,
+  // как в настоящем репозитории. Манифест НЕ переносится намеренно — иначе записи, читающие
+  // `.aqk.yml` (`gates-are-runnable`, `gate-has-samples`, `protection-not-removed`), краснеют
+  // на том, что в пробе нет объявленных ими файлов, и проба объявляет класс прикрытым, хотя
+  // на подсаженный брак не отреагировал никто. Ошибка в сторону «прикрыто» — это тишина,
+  // а тишина здесь и есть предмет спора. Поймано первым же прогоном на своём репозитории.
+  if (await exists(join(CWD, ".aqkignore"))) {
+    await copyFile(join(CWD, ".aqkignore"), join(root, ".aqkignore"));
+  }
+  return root;
+}
+
+function runGates(gates, dir) {
+  const out = [];
+  for (const [name, cmd] of gates) {
+    const r = spawnSync(commandFor(cmd, dir), { shell: true, cwd: CWD, encoding: "utf8", timeout: 120000 });
+    out.push({ name, code: r.status === null ? 2 : r.status });
+  }
+  return out;
+}
+
+// `auto` — проба запущена САМА, по каденции, из `doctor --run`. Тогда она короче и говорит
+// вслух, почему случилась: команда, возникшая без спроса, обязана объяснить себя, иначе её
+// читают как сбой.
+async function cmdProbe(args, { auto = false } = {}) {
+  const P = L.probe;
+  const topArg = Number(args[args.indexOf("--top") + 1]);
+  const TOP = args.includes("--top") && Number.isFinite(topArg) && topArg > 0 ? topArg : (auto ? 3 : 5);
+
+  console.log(c.bold(`\n${P.title}\n`));
+
+  const man = await readManifest();
+  const gates = scanningGates(man);
+  if (!gates.length) { console.log(c.yellow(`  ${P.noGates(`${SELF} add <имя>`)}\n`)); return; }
+
+  const raw = gitLog(2000);
+  if (raw === null) { console.log(c.yellow(`  ${P.noGit}\n`)); return; }
+  const hot = fixHotspots(raw, { isCode }).slice(0, TOP);
+  if (!hot.length) { console.log(c.yellow(`  ${isShallow() ? P.shallow : P.noFixes}\n`)); return; }
+
+  // Записи каталога, применимые к ЭТОМУ репозиторию. Показывать пробы записей, которые
+  // проекту не подходят, значит советовать закрыть дыру, которой нет.
+  const facts = await detectFacts();
+  const catalog = await readCatalog();
+  const entries = catalog.filter((e) => triggerVerdict(e, facts).applies);
+
+  console.log(c.dim(`  ${P.method(hot.length, entries.length)}\n`));
+
+  let blind = 0;
+  for (const { path: rel, fixes } of hot) {
+    console.log(`  ${c.bold(rel)}  ${c.dim(P.fixes(fixes))}`);
+    const ext = extname(rel).toLowerCase();
+    let probed = 0;
+
+    for (const e of entries) {
+      const sample = await redSampleFor(e.slug, ext);
+      if (!sample) continue;
+      probed++;
+      const dir = await buildProbe(rel, sample);
+      let results;
+      try { results = runGates(gates, dir); } finally { await rm(dir, { recursive: true, force: true }); }
+      const verdict = probeVerdict(results);
+      const caught = results.filter((r) => r.code === 1).map((r) => r.name);
+      if (verdict === "caught") {
+        console.log(`    ${c.green("✔")}  ${e.intent.padEnd(48)} ${c.dim(P.caught(caught.join(", ")))}`);
+      } else if (verdict === "blind") {
+        blind++;
+        console.log(`    ${c.red("✘")}  ${e.intent.padEnd(48)} ${c.red(P.blind)}`);
+        console.log(c.dim(`         ${P.install(`${SELF} add ${e.slug}`)}`));
+      } else {
+        console.log(`    ${c.dim("~")}  ${c.dim(e.intent.padEnd(48))} ${c.dim(P.unknown)}`);
+      }
+    }
+    if (!probed) console.log(c.dim(`    ${P.noSampleFor(ext || "—")}`));
+  }
+
+  console.log(blind ? c.yellow(`\n  ${P.summaryBlind(blind)}\n`) : c.green(`\n  ${P.summaryClean}\n`));
+
+  // Отметка нужна не для отчёта, а для КАДЕНЦИИ: по ней следующий прогон поймёт, что пора.
+  // Без неё команда снова становится тем, о чём надо вспомнить.
+  await writeMark(commitCount(), blind, hot.map(({ path: p2, fixes }) => `- ${p2} (${P.fixes(fixes)})`));
+}
+
+// Состояние пробы для тех, кто только ПОКАЗЫВАЕТ его: прогон и блок для агента.
+//
+// Порог берётся из манифеста (`probe: 250`), умолчание — PROBE_EVERY. Непонятое значение не
+// подменяется умолчанием молча: в манифесте было бы написано одно, а происходило бы другое.
+// Возвращается пометка `badEvery`, и вызывающий говорит о ней вслух.
+async function probeStatus() {
+  const man = await readManifest();
+  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);
+}
+
+export { cmdProbe, probeStatus, scanningGates, isCode };

package/tool/commands/project.mjs

@@ -8,6 +8,7 @@ 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";
 import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
+import { banner } from "../lib/banner.mjs";
 import { readManifest } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
 import { installGate } from "./gates.mjs";
@@ -40,7 +41,9 @@ async function cmdInit(args) {
   const claude = join(CWD, "CLAUDE.md");
   track(await writeIfAbsent(claude, CLAUDE_MD, { force }), claude);
 
-  console.log(c.bold("\naqk init\n"));
+  // Заставка в начале init — первая встреча человека с комплектом. Второй раз он увидит её
+  // только если сам спросит `--version`: то, что видишь тридцатый раз, перестаёт читаться.
+  console.log(`\n${banner()}\n`);
   if (created.length) {
     console.log(c.green(`  ${L.init.created(created.length)}`));
     for (const f of created.slice(0, 8)) console.log(`    ${f}`);
@@ -96,7 +99,20 @@ ${c.bold(L.feedback.title)}
     ${url}/issues/new
 ${c.dim(`  ${L.feedback.once}`)}
 `);
-  await writeIfAbsent(FEEDBACK_MARK, "shown\n", { force: false });
+  // Пометка «уже показывали» — удобство, а не работа команды. Домашнего каталога может не быть
+  // записываемым вовсе: в контейнере, запущенном `--user 1001:127`, у этого uid нет записи в
+  // /etc/passwd, `homedir()` даёт «/», и запись падает с EACCES на `/.config`. До 2026-09-09
+  // это роняло ВЕСЬ `init` — то есть любого, кто набрал команду из нашей же документации по
+  // docker. Локально не воспроизводилось случайно: uid разработчика 1000 совпадает с
+  // пользователем `node` в образе, у которого дом есть. Нашёл конвейер, где uid 1001.
+  //
+  // Молча глотать нельзя — это то, что красит наш же swallowed-error. Поэтому вслух: не
+  // запомнили, покажем снова. Установка при этом доходит до конца.
+  try {
+    await writeIfAbsent(FEEDBACK_MARK, "shown\n", { force: false });
+  } catch {
+    console.log(c.dim(`  ${L.feedback.notRemembered}`));
+  }
 }
 
 function findJournal() {

package/tool/commands/prove.mjs

@@ -17,6 +17,7 @@ function line(r) {
       r.why === "no-samples" ? P.noSamples
       : r.why === "other-recipe" ? P.otherRecipe(r.forRecipe.lang)
       : r.why === "no-target" ? P.noTarget
+      : r.why === "needs-program" ? P.needsProgram(r.missing.join(", "))
       : P.empty;
     return `  ${c.dim("~")}  ${c.dim(pad)} ${c.dim(why)}`;
   }

package/tool/commands/vitals.mjs

@@ -0,0 +1,167 @@
+// tool/commands/vitals.mjs — «всё ли у самого комплекта подключено».
+//
+// ЗАЧЕМ ОТДЕЛЬНАЯ КОМАНДА. `doctor` смотрит на РЕПОЗИТОРИЙ, `prove` — на гейты, `context` —
+// на состояние. На саму обвязку не смотрит никто: стоят ли инструменты, которых требуют
+// объявленные гейты; прописан ли хук в `.git/hooks` НА САМОМ ДЕЛЕ, а не только в конфиге;
+// получает ли агент состояние. Сегодня это выясняется красным гейтом посреди коммита — в
+// худший момент из возможных, когда человек занят другим и просто выключит проверку.
+//
+// ЧЕТЫРЕ СОСТОЯНИЯ, А НЕ ДВА, И КАЖДОЕ ЗАРАБОТАНО.
+//   ✔  подключено;
+//   ✘  СЛОМАНО — объявленный гейт не состоится: нет инструмента, потеряна строка манифеста;
+//   ·  не подключено, и это выбор — хука pre-commit нет, потому что гоняют в конвейере;
+//   ~  посмотреть не смогли.
+//
+// Первая версия ставила `✘` хуку, которого нет. На нашем же репозитории вышло два креста за
+// сознательное решение: pre-commit локально мы не ставим, проверки идут в CI. Команда, которая
+// кричит «сломано» про выбор, — ровно та, которую выключают в первый день, и вместе с ней
+// перестают читать настоящие отказы. Кода возврата касается только `✘`.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CWD, MANIFEST, SELF, c, exists } from "../lib/core.mjs";
+import { readManifest, unparsedLines, gateRequires } from "../lib/manifest.mjs";
+import { whichSync } from "../lib/repo.mjs";
+import { updateWanted } from "../lib/brief.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Чистая функция: на входе факты, на выходе строки. Отделена от чтения диска намеренно —
+// «неизвестно» проверяется перебором случаев, а не прогоном, потому что случай «не смогли
+// посмотреть» на исправной машине не воспроизвести.
+function vitalsRows(f) {
+  const t = L.vitals;
+  const missing = (f.tools || []).filter((x) => !x.found);
+  const rows = [
+    {
+      key: "tools",
+      ok: (f.tools || []).length === 0 ? null : missing.length === 0,
+      detail: missing.length
+        ? t.toolsMissing(missing.map((x) => `${x.prog} (${x.gate})`).join(", "))
+        : t.toolsOk((f.tools || []).length),
+    },
+    {
+      key: "manifest",
+      ok: f.unparsed > 0 ? false : true,
+      detail: f.unparsed > 0 ? t.manifestBad(f.unparsed) : t.manifestOk,
+    },
+    {
+      key: "preCommit",
+      ok: f.preCommit === null ? null : f.preCommit ? true : "no",
+      detail: f.preCommit === null ? t.unknownHook : f.preCommit ? t.preCommitOk : t.preCommitNo,
+    },
+    {
+      key: "sessionHook",
+      ok: f.sessionHook === null ? null : f.sessionHook ? true : "no",
+      detail: f.sessionHook === null ? t.unknownHook : f.sessionHook ? t.sessionOk : t.sessionNo(`${SELF} context --install`),
+    },
+  ];
+  // Устаревшая версия — не отказ: человек мог закрепить её сознательно, и ронять за это нельзя.
+  //
+  // СОСТОЯНИЙ ТРИ, А НЕ ДВА. Реестр может ответить ошибкой — не упасть, а вернуть не-200; тогда
+  // `latest` пустой, и прежняя ветка печатала «свежая». Посмотреть не смогли, а сказали «всё
+  // хорошо»: тот самый грех, против которого написан весь комплект, у него самого. Найдено
+  // аудитом фич 2026-09-09.
+  if (f.version) {
+    const latest = String(f.version.latest || "");
+    rows.push({
+      key: "version",
+      ok: null,
+      detail: !latest
+        ? t.versionUnknown(f.version.current)
+        : latest !== f.version.current
+          ? t.versionOld(latest, f.version.current)
+          : t.versionOk(f.version.current),
+    });
+  }
+  return rows;
+}
+
+function vitalsVerdict(rows) {
+  return rows.some((r) => r.ok === false) ? 1 : 0;
+}
+
+// Первое слово команды — та программа, без которой гейт не состоится. Обёртки снимаются:
+// `bash x.sh` требует bash, а не x.sh; `npx --yes knip@6` требует npx.
+function progOf(cmd) {
+  const parts = String(cmd || "").trim().split(/\s+/);
+  return parts[0] || "";
+}
+
+async function cmdVitals() {
+  const man = await readManifest();
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+
+  const seen = new Map();
+  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)) });
+  }
+
+  // Первого слова мало. Запись каталога бывает обёрткой: команда начинается с `bash`, который
+  // есть всегда, а работать без `slopcheck` или `zizmor` она не может — и `doctor --run`
+  // краснеет там, где `vitals` печатал «все инструменты на месте». Ровно тот разрыв, ради
+  // закрытия которого эта команда и заведена. Программа названа в `requires:` записи.
+  // Найдено 2026-09-09 сверкой вывода двух команд на одном репозитории.
+  const samplesDir = typeof man?.samples === "string" ? man.samples.trim() : "";
+  for (const gate of Object.keys(gates)) {
+    const missing = await gateRequires(samplesDir, gate, whichSync);
+    for (const prog of missing || []) {
+      if (seen.has(prog)) continue;
+      seen.set(prog, { gate, prog, found: false });
+    }
+  }
+
+  let unparsed = 0;
+  try { unparsed = unparsedLines(await readFile(join(CWD, MANIFEST), "utf8")).length; } catch { /* манифеста нет */ }
+
+  // Хук 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; }
+    }
+  }
+
+  let sessionHook = null;
+  const settings = join(CWD, ".claude", "settings.json");
+  if (await exists(join(CWD, ".claude"))) {
+    sessionHook = false;
+    if (await exists(settings)) {
+      try {
+        const s = JSON.parse(await readFile(settings, "utf8"));
+        sessionHook = JSON.stringify(s?.hooks?.SessionStart || []).includes("context");
+      } catch { sessionHook = null; }
+    }
+  }
+
+  let version = null;
+  if (updateWanted()) {
+    try {
+      const { PKG_ROOT } = await import("../lib/core.mjs");
+      const 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 { /* сети нет — строку про версию просто не покажем */ }
+  }
+
+  const rows = vitalsRows({ tools: [...seen.values()], unparsed, preCommit, sessionHook, version });
+  console.log(c.bold(`\n  ${L.vitals.title}\n`));
+  for (const r of rows) {
+    const mark = r.ok === true ? c.green("✔")
+      : r.ok === false ? c.red("✘")
+      : r.ok === "no" ? c.yellow("·")
+      : c.dim("~");
+    console.log(`  ${mark}  ${L.vitals.names[r.key].padEnd(22)} ${r.ok === false ? r.detail : c.dim(r.detail)}`);
+  }
+  console.log("");
+  process.exit(vitalsVerdict(rows));
+}
+
+export { cmdVitals, vitalsRows, vitalsVerdict };

package/tool/i18n/en-docs.mjs

@@ -7,6 +7,47 @@
 // the second for one second in a terminal.
 
 const enDocs = {
+  // Блок vitals переехал сюда 2026-09-09 по той же причине, что и brief: терминальный
+  // каталог снова перерос 500 строк, и поймал это наш же file-size-limit.
+  vitals: {
+    title: "Is what the kit runs on actually wired up",
+    names: {
+      tools: "gate tools",
+      manifest: "manifest parsed",
+      preCommit: "pre-commit hook",
+      sessionHook: "state to the agent",
+      version: "version",
+    vitals: "is what the kit runs on wired up: tools, hooks, freshness",
+    },
+    toolsOk: (n) => `all ${n} present`,
+    toolsMissing: (l) => `NOT FOUND: ${l} — those gates will not happen`,
+    manifestOk: "parsed in full",
+    manifestBad: (n) => `${n} lines were not parsed and HAVE NO EFFECT — details in doctor`,
+    unknownHook: "could not look — unknown, not \"no\"",
+    preCommitOk: "wired in .git/hooks",
+    preCommitNo: "not in .git/hooks: a config entry is an intent, not a guard",
+    sessionOk: "the SessionStart hook hands the state to the agent",
+    sessionNo: (cmd) => `the agent gets no state: ${cmd}`,
+    versionOk: (v) => `${v}, current`,
+    versionUnknown: (v) => `${v}, could not reach the registry — freshness unknown`,
+    versionOld: (l, cur) => `${l} is out, you have ${cur}`,
+  },
+  // Блок краткого вывода переехал сюда 2026-09-09: терминальный каталог снова перерос
+  // 500 строк, и поймал это наш же file-size-limit. Шов по смыслу условен — это всё-таки
+  // терминал, — но предел настоящий, а делить пополам хуже, чем делить по соседству.
+  brief: {
+    name: "AQK",
+    held: (n) => `holds ${n}`,
+    todo: (n) => `not installed ${n}`,
+    levelUnknown: "level unknown",
+    red: (l) => `     RED: ${l}`,
+    advise: (slug, why) => `     ↑ install: ${slug} — ${why}`,
+    adviseOff: (cmd, env) => `       not needed: ${cmd}, or ${env}`,
+    update: (l, c, how) => `version ${l} is out, you have ${c} — update: ${how}`,
+    updateHow: "npx agent-quality-kit@latest, or npm i -g agent-quality-kit",
+    updateHookHow: "pre-commit autoupdate",
+    updateOff: (env) => `       not needed: ${env}`,
+  },
   // THE STATE BLOCK — the one text of ours whose reader is a machine, not a person.
   // It goes into the agent's context via a SessionStart hook, so it is written as claims of
   // fact: no politeness, no preamble, every line either a fact or an honest "unknown".
@@ -26,6 +67,13 @@ const enDocs = {
     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.`,
+    probeNever: "No coverage probe has run — what is covered by nothing here is UNKNOWN. That is not \"covered\": `aqk probe`.",
+    probeBlind: (n, behind) =>
+      `Covered by nothing: ${n} defect classes in the places people most often come back to fix` +
+      (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\`.`,
     mapTitle: "WHAT THIS TOOL CAN DO. The full list of commands — not a retelling, the same list\nthe help is built from:",