agent-quality-kit 0.8.0 → 0.9.0

package/tool/lib/brief.mjs

@@ -0,0 +1,192 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { CWD, PKG_ROOT, TARGET_DIR, SELF, c } from "./core.mjs";
+import { L } from "../i18n/index.mjs";
+import { canDrawArt } from "./banner.mjs";
+// tool/lib/brief.mjs — короткая строка присутствия для прогона в хуке.
+//
+// ЗАЧЕМ ЭТО СУЩЕСТВУЕТ. Хук pre-commit молчит на успехе: вывод показывается только при провале
+// — это его умолчание, проверено по документации 2026-09-08. То есть комплект, который всё
+// держит, для человека НЕОТЛИЧИМ от невставленного: он поставил, поработал неделю и не увидел
+// ни строки. «Скачал и че дальше» — дословная жалоба владельца.
+//
+// Это ровно тот порок, против которого написан весь комплект, только у нас самих: тишина
+// неотличима от успеха. Поэтому строка печатается ВСЕГДА, в том числе — и особенно — когда
+// всё хорошо. Одна строка: присутствие видно, читать нечего.
+//
+// СОВЕТ ОТДЕЛЬНО И РЕДКО. Вторая строка называет ОДНУ непоставленную запись и способ отказаться.
+// Не список: список читается как «у вас всё плохо» и не помогает выбрать. Не каждый коммит:
+// то, что видишь тридцатый раз, перестаёт читаться — и пролистывается вместе с настоящими
+// находками, стоящими рядом.
+
+// Сутки. Не «раз в прогон» и не «раз в неделю»: за сутки человек успевает забыть, но не успевает
+// устать. Число здесь спорное — важно, что ограничитель есть и он машинный.
+const ADVICE_EVERY_MS = 24 * 60 * 60 * 1000;
+
+// ЗНАЧОК ПРИСУТСТВИЯ — здесь, а не в каталогах строк. Символ один на оба языка, и держать его
+// в двух местах значит однажды получить разные значки в ru и en: то же правило, по которому у
+// нас один свод правил на две точки входа. Выбран владельцем из пятидесяти семи вариантов.
+// В терминале без UTF-8 он превратится в мусор — там правило то же, что у заставки, и оно
+// одно на двоих: разойдись эти два условия, и значок рисовался бы там, где картинка уже нет.
+const MARK = "❖";
+
+function briefLine(state, L, env = process.env) {
+  const t = L.brief;
+  const mark = canDrawArt(env) ? `${MARK} ` : "";
+  const parts = [t.held(state.held), t.todo(state.todo)];
+  if (state.level >= 0) parts.push(`AQK-${state.level}`);
+  else parts.push(t.levelUnknown);
+  const head = `${mark}${t.name}  ${parts.join(" · ")}`;
+  if (!state.red || !state.red.length) return head;
+  return `${head}\n${t.red(state.red.join(", "))}`;
+}
+
+// «Не знаем, когда показывали» и «показывали давно» — одно и то же решение: показать.
+// Испорченная отметка попадает сюда же намеренно: молчать из-за нечитаемого файла состояния
+// значит потерять совет навсегда и не сказать почему.
+function adviceDue(lastIso, now = Date.now()) {
+  if (!lastIso) return true;
+  const t = Date.parse(String(lastIso));
+  if (!Number.isFinite(t)) return true;
+  return now - t >= ADVICE_EVERY_MS;
+}
+
+// Первая из непоставленных, а не «самая важная»: важность мы не считаем, а порядок каталога
+// осмыслен — записи в нём лежат от общего к частному. Выдавать порядок за приоритет нельзя.
+function pickAdvice(todo = []) {
+  return todo.length ? todo[0] : null;
+}
+
+// УВЕДОМЛЕНИЕ ОБ ОБНОВЛЕНИИ — и почему НЕ автообновление.
+//
+// Выпуски идут часто, а у половины способов установки версия закреплена и сама не двигается:
+// `rev:` у pre-commit, тег у GitHub Action. Человек ставит комплект, получает версию с уже
+// исправленной ошибкой и не узнаёт об этом никогда. У `npx` без версии проблемы нет — он берёт
+// свежее при каждом запуске.
+//
+// АВТООБНОВЛЕНИЯ НЕТ, И ЭТО РЕШЕНИЕ, А НЕ НЕДОДЕЛКА. В тот же день выпущена запись каталога,
+// краснеющая на `@latest`: «версия не закреплена — завтра приедет другая». Инструмент, который
+// молча подменяет себя, стоя на воротах коммита, делал бы ровно то, что мы запрещаем другим.
+// Первый же внешний читатель это заметит, и будет прав.
+//
+// СРАВНЕНИЕ ПО ЧИСЛАМ. Строкой «0.10.0» меньше «0.9.0», и уведомление пропало бы ровно на
+// десятом выпуске — тихо и надолго. Такие поломки не замечают месяцами.
+function cmpVer(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+// Совет зависит от способа установки: у pre-commit это `autoupdate`, а не npm. Совет мимо
+// способа человек не выполнит — и перестанет читать следующие.
+function updateNotice(current, latest, env = process.env, L) {
+  if (!current || !latest || cmpVer(latest, current) <= 0) return null;
+  const how = env.PRE_COMMIT ? L.brief.updateHookHow : L.brief.updateHow;
+  return `${L.brief.update(latest, current, how)}\n${L.brief.updateOff("AQK_UPDATE=0")}`;
+}
+
+// В конвейере не спрашиваем вовсе: там версия закреплена сознательно, читать уведомление
+// некому, а лишний исходящий запрос из инструмента, который иначе не делает ни одного, —
+// плохой размен. Отказ человека уважается тем же способом.
+function updateWanted(env = process.env) {
+  if (String(env.AQK_UPDATE || "") === "0") return false;
+  if (env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI) return false;
+  return true;
+}
+
+// КРАТКИЙ РЕЖИМ для хука. Вывод целиком БУФЕРИЗУЕТСЯ, а печатается одна строка присутствия —
+// и, при провале, весь буфер, чтобы человеку было что чинить. Перехват console.log выглядит
+// грубо, и это осознанный размен: альтернатива — протащить флаг через четыреста строк печати,
+// где каждая строка стала бы условной. Перехват локален, снимается в том же вызове и объяснён
+// здесь; условие в каждой строке объяснить было бы негде.
+function beginBrief() {
+  const lines = [];
+  const real = console.log;
+  console.log = (...a) => lines.push(a.join(" "));
+  return { lines, restore: () => { console.log = real; } };
+}
+
+// Печать краткого итога. Совет — не чаще раза в сутки и с явным способом отказаться: то, что
+// видишь тридцатый раз, перестаёт читаться и пролистывается вместе с настоящими находками рядом.
+// Отметка времени лежит в .aqk/, который в .gitignore: это состояние машины, а не проекта.
+async function finishBrief(buf, state, todoRecs, ok) {
+  if (!buf) return;
+  buf.restore();
+  console.log(briefLine(state, L));
+
+  // Уведомление об обновлении — ДО разбора вердикта: оно от него не зависит. Сначала было
+  // после, и у любого проекта, где чего-то не хватает, версия не спрашивалась никогда —
+  // то есть у всех, кому комплект и нужен. Поймано первым же живым запуском.
+  await maybeUpdateNotice();
+
+  // При провале печатаем ВЕСЬ буфер: человеку нужно чинить, а одной строкой не починишь.
+  if (!ok) { console.log(buf.lines.join("\n")); return; }
+
+  if (process.env.AQK_ADVICE === "0" || !state.todo) return;
+  const stampFile = join(CWD, TARGET_DIR, "advice-shown");
+  let last = null;
+  try { last = (await readFile(stampFile, "utf8")).trim(); } catch { /* не показывали ещё */ }
+  if (!adviceDue(last)) return;
+  const advice = pickAdvice(todoRecs);
+  if (!advice) return;
+  console.log(c.dim(L.brief.advise(advice.slug, advice.intent || "")));
+  console.log(c.dim(L.brief.adviseOff(`${SELF} why ${advice.slug}`, "AQK_ADVICE=0")));
+  try {
+    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+    await writeFile(stampFile, new Date().toISOString(), "utf8");
+  } catch { /* не смогли записать отметку — совет повторится, это не беда */ }
+}
+
+// Спрашивает реестр npm о своей версии. РАЗ В СУТКИ, НЕ В КОНВЕЙЕРЕ, С ТАЙМАУТОМ, И МОЛЧА
+// ПРИ ЛЮБОЙ ОШИБКЕ. До этой строки комплект не делал ни одного исходящего запроса — так
+// написано в README и SECURITY.md, и там же теперь написано про этот. Сделать тихо то, за что
+// мы ругаем других, нельзя: весь смысл в том, что заявленное совпадает с происходящим.
+//
+// Код возврата не меняется никогда: уведомление, роняющее коммит, выключат в тот же день —
+// и вместе с ним всё остальное, что печатает эта строка.
+async function maybeUpdateNotice() {
+  if (!updateWanted()) return;
+  const stamp = join(CWD, TARGET_DIR, "update-checked");
+  let last = null;
+  try { last = (await readFile(stamp, "utf8")).trim(); } catch { /* ещё не спрашивали */ }
+  if (!adviceDue(last)) return;
+
+  let current = "";
+  try { current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || ""; } catch { return; }
+
+  // ОТМЕТКА СТАВИТСЯ ДО ЗАПРОСА, а не после удачного ответа. Сперва было наоборот, и замер
+  // показал цену: человек без сети платил бы ожиданием на КАЖДОМ коммите, а не раз в сутки.
+  // Из двух ошибок выбрана дешёвая: пропущенное за день уведомление против ежедневного стопора.
+  try {
+    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+    await writeFile(stamp, new Date().toISOString(), "utf8");
+  } catch { /* не смогли записать — спросим ещё раз, это не беда */ }
+
+  let latest = "";
+  try {
+    // Три секунды, а не полторы. Замерено 2026-09-08: тёплый запрос к реестру — 533 мс,
+    // а первый, с разрешением имени и рукопожатием, в полторы секунды не уложился. Слишком
+    // тугой срок означал бы, что уведомление не приходит никогда и никто не знает почему.
+    const r = await fetch("https://registry.npmjs.org/agent-quality-kit/latest", {
+      signal: AbortSignal.timeout(3000),
+      headers: { accept: "application/vnd.npm.install-v1+json" },
+    });
+    if (!r.ok) return;
+    latest = String((await r.json()).version || "");
+  } catch {
+    // Сети нет, реестр молчит, таймаут — всё это НЕ повод сказать хоть слово. Инструмент,
+    // который жалуется на отсутствие интернета посреди коммита, выключают.
+    return;
+  }
+
+  const notice = updateNotice(current, latest, process.env, L);
+  if (notice) console.log(c.dim(notice));
+}
+
+// Наружу — только то, что зовут снаружи. `cmpVer` и `ADVICE_EVERY_MS` внутренние: экспорт,
+// который никто не импортирует, читается как часть договора и мешает менять внутренности.
+export { briefLine, adviceDue, pickAdvice, updateNotice, updateWanted, beginBrief, finishBrief };

package/tool/lib/core.mjs

@@ -83,6 +83,8 @@ function commandRows(L) {
     { name: "context", args: "", text: h.context },
     { name: "context", args: "--full --install", text: h.contextInstall },
     { name: "badge", args: "", text: h.badge },
+    { name: "vitals", args: "", text: h.vitals },
+    { name: "version", args: "", text: h.version },
   ];
 }
 

package/tool/lib/manifest.mjs

@@ -25,6 +25,14 @@ function stripComment(raw) {
   return raw[i] === "#" ? raw.slice(0, i) : raw.slice(0, i + 1);
 }
 
+// Список в одну строку: `[AGENTS.md, docs/START.md]`. Вынесен отдельно, потому что нужен на
+// двух уровнях, а два одинаковых куска разбора расходятся ровно так же, как два свода правил.
+function inlineList(v) {
+  const s = String(v).trim();
+  if (!s.startsWith("[") || !s.endsWith("]")) return null;
+  return s.slice(1, -1).split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+}
+
 function parseManifest(text) {
   const out = {};
   let section = null;
@@ -48,26 +56,51 @@ function parseManifest(text) {
 
     if (indented && section) {
       if (typeof out[section] !== "object" || Array.isArray(out[section])) out[section] = {};
-      out[section][key] = clean;
+      // Список в одну строку разбирается и на вложенном уровне: `covers:` ниже `  lint: [a, b]`.
+      // Раньше вложенное значение всегда оставалось строкой, и `[a, b]` превращалось в текст
+      // «[a, b]» — молча, как это умеет только разбор без схемы. Наверху такой список уже
+      // разбирался; расхождение между уровнями и есть источник тихой неправды.
+      out[section][key] = inlineList(clean) || clean;
       continue;
     }
     section = key;
     // Список в одну строку: entry: [AGENTS.md, docs/START.md]. Люди пишут именно так —
     // и раньше манифест молча читался как пустой, а проект получал вердикт «нет AQK-0».
     // Неверный вердикт хуже отсутствия вердикта: ему верят.
-    if (clean.startsWith("[") && clean.endsWith("]")) {
-      out[key] = clean
-        .slice(1, -1)
-        .split(",")
-        .map((v) => v.trim().replace(/^["']|["']$/g, ""))
-        .filter(Boolean);
-      continue;
-    }
+    const list = inlineList(clean);
+    if (list) { out[key] = list; continue; }
     out[key] = clean === "" ? {} : clean;
   }
   return out;
 }
 
+// СТРОКА, КОТОРУЮ РАЗБОР НЕ ПОНЯЛ, НЕ ИСЧЕЗАЕТ МОЛЧА.
+//
+// Найдено 2026-09-09 случайно: подсаживали падающий гейт с именем «плохой», чтобы посмотреть на
+// вывод, — и прогон вышел с НУЛЁМ. Гейт не упал: его не существовало. Имена разбираются только
+// латиницей, а строка, не подошедшая под это, выбрасывалась без единого слова.
+//
+// Это наш класс в чистом виде: человек объявил проверку, видит её в файле, а её нет. Хуже
+// опечатки в имени поля — ту мы называем с 2026-09-06, а эту не называли вовсе.
+//
+// ЧИНИТСЯ ГОЛОСОМ, А НЕ АЛФАВИТОМ. Расширить набор букв — залатать один случай; строк, которые
+// разбор не понимает, бывает больше (табуляция вместо пробелов, двоеточие в значении без
+// кавычек). Называется любая: разбор ограниченного подмножества YAML честен ровно до тех пор,
+// пока говорит, чего не взял.
+function unparsedLines(text) {
+  const out = [];
+  let n = 0;
+  for (const raw of String(text).split("\n")) {
+    n += 1;
+    const line = stripComment(raw).replace(/\s+$/, "");
+    if (!line.trim()) continue;
+    if (line.trim().startsWith("- ")) continue;
+    if (/^\s*[A-Za-z0-9_-]+:\s*(.*)$/.test(line)) continue;
+    out.push({ line: n, text: raw.trim() });
+  }
+  return out;
+}
+
 // Поля, которые манифест знает. Список здесь, а не в схеме-файле: зависимостей у программы
 // нет, а схема на восемь ключей, которую надо валидировать библиотекой, стоит дороже, чем
 // защищает.
@@ -79,7 +112,7 @@ function parseManifest(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "gates", "samples", "ratchets", "lessons", "advisory"];
+const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "lang", "gates", "covers", "samples", "ratchets", "lessons", "advisory"];
 
 // ГДЕ У ПРОЕКТА ЛЕЖИТ РАЗЛОЖЕННЫЙ КОМПЛЕКТ. Список для шапки `doctor`. До 2026-09-08 он был
 // литеральным: `.aqk/rules`, `.aqk/docs`, `AGENTS.md` — независимо от того, что написано в
@@ -108,6 +141,79 @@ function layoutChecks(man, inKit) {
   ];
 }
 
+// ЗАПИСЬ ЗАКРЫТА ДРУГИМ АРБИТРОМ. `covers: { lint: [no-print-in-prod, swallowed-error] }`
+// читается как «гейт lint держит эти записи каталога». Просьба первого чужого пользователя,
+// названная им первой: без этого `doctor` каждый прогон печатал «применимо, но не поставлено»
+// про то, что у него закрыто biome. Неправда в собственном выводе дороже всех остальных: весь
+// стандарт стоит на том, что вывод не врёт.
+//
+// НО ЭТО НЕ ПРИЗНАНИЕ НА СЛОВО. Закрывать может только гейт, ОБЪЯВЛЕННЫЙ в `gates:` непустой
+// командой. Иначе поле превращается в способ объявить защиту, которой нет, — ровно тот отказ,
+// против которого написан комплект. Необъявленные называются поимённо, а не отбрасываются молча.
+function coversOf(man) {
+  const covered = new Map();
+  const unknownGates = [];
+  const raw = man?.covers;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { covered, unknownGates };
+
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  const declared = new Set(Object.entries(gates).filter(([, cmd]) => String(cmd || "").trim()).map(([k]) => k));
+
+  for (const [gate, value] of Object.entries(raw)) {
+    const entries = Array.isArray(value)
+      ? value
+      : String(value || "").split(",").map((x) => x.trim()).filter(Boolean);
+    if (!declared.has(gate)) { if (entries.length) unknownGates.push(gate); continue; }
+    for (const e of entries) if (!covered.has(e)) covered.set(e, gate);
+  }
+  return { covered, unknownGates };
+}
+
+// ЗАЯВКА `covers` СВЕРЯЕТСЯ, А НЕ ПРИНИМАЕТСЯ НА СЛОВО — насколько это вообще возможно.
+//
+// Поле `covers` заведено 2026-09-08 утром, и тогда же в коммите было записано честное: «снимает
+// запись с долга по СЛОВУ человека; проверить, что чужой гейт ловит то же самое, машина не
+// может». К вечеру выяснилось, что это не теория. Запуск на настоящем `ruff.toml` из живого
+// проекта: девятнадцать групп правил в `extend-select`, а `print()` не ловится — группы `T20`
+// среди них нет. Заявка «no-print-in-prod держит наш lint» была бы ложной, а запись ушла бы из
+// долга. То есть поле, снимающее неправду из вывода, само стало бы способом её произвести.
+//
+// ЧТО СВЕРЯЕТСЯ. У записи каталога в рецепте стоят коды правил: `ruff check --select T20 {dir}`.
+// Если ни команда закрывающего гейта, ни конфиг линтера этих кодов не называют — заявка не
+// подтверждена. Записи без кодов в рецепте (переносимые проверки) не сверяются вовсе: там
+// сверять нечего, и выдумывать вердикт нельзя.
+//
+// ПОЧЕМУ «НЕ ПОДТВЕРЖДЕНО», А НЕ «ЛОЖЬ». Правило могло прийти из плагина, пресета или общего
+// конфига этажом выше. Объявлять такое ошибкой значит краснеть на нормальном укладе — а такой
+// вывод перестают читать целиком, вместе с настоящими находками.
+const RULE_CODES = /--select[= ]([A-Za-z0-9,]+)/;
+
+function coversUnproven(man, catalog = [], linterConfigText = "") {
+  const { covered } = coversOf(man);
+  if (!covered.size) return [];
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  const cfg = String(linterConfigText || "");
+  const out = [];
+
+  for (const [entry, gate] of covered) {
+    const rec = catalog.find((r) => r.slug === entry);
+    const recipes = rec?.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
+    // Коды берутся из любого рецепта записи: язык проекта здесь не важен, важно, что запись
+    // ВООБЩЕ выражается кодами правил. Если ни один рецепт их не называет — сверять нечего.
+    const codes = new Set();
+    for (const cmd of Object.values(recipes)) {
+      const m = RULE_CODES.exec(String(cmd || ""));
+      if (m) for (const c of m[1].split(",")) if (c.trim()) codes.add(c.trim());
+    }
+    if (!codes.size) continue;
+
+    const haystack = `${String(gates[gate] || "")}\n${cfg}`;
+    const missing = [...codes].filter((c) => !haystack.includes(c));
+    if (missing.length === codes.size) out.push({ entry, gate, codes: [...codes] });
+  }
+  return out;
+}
+
 function unknownKeys(man) {
   if (!man || typeof man !== "object" || Array.isArray(man)) return [];
   return Object.keys(man).filter((k) => !KNOWN_KEYS.includes(k));
@@ -146,16 +252,41 @@ function entryLifecycle(rec) {
   return { state, why, supersededBy: supersededBy || null, problem };
 }
 
-// СОВЕЩАТЕЛЬНЫЕ ГЕЙТЫ. Правило вводят в проект, где старый код ему не соответствует. Храповик
-// отвечает на это одним способом: старое становится долгом, новое блокируется. Второй способ —
-// показывать, не роняя, пока команда договаривается о правиле. Без него у человека остаётся
-// выбор из двух крайностей: включить и сломать сборку либо не включать вовсе.
+// Программа, без которой запись каталога не работает вовсе: поле `requires` в её `gate.yml`.
+// Возвращает список НЕДОСТАЮЩИХ программ или null.
 //
+// ЗАЧЕМ ОБЩИМ. Переносимый рецепт бывает обёрткой вокруг готового инструмента: первое слово
+// команды тогда `bash`, и по нему не видно, чего не хватает. Этот вопрос задают трое —
+// приёмка каталога, доказательство гейтов и осмотр обвязки, — и каждый отвечал на него
+// по-своему или не отвечал вовсе. 2026-09-09: `prove` объявлял такой гейт сломанным, а
+// `vitals` печатал «все инструменты на месте» ровно там, где прогон краснел.
+// `has` передаётся вызывающим, а не берётся отсюда: manifest.mjs не должен знать про осмотр
+// репозитория — импорт в обратную сторону завёл бы цикл. Заодно функция проверяема модульно.
+async function gateRequires(samplesDir, name, has) {
+  if (!samplesDir) return null;
+  const yml = join(CWD, samplesDir, name, "gate.yml");
+  if (!(await exists(yml))) return null;
+  try {
+    const rec = parseManifest(await readFile(yml, "utf8"));
+    const raw = typeof rec?.requires === "string" ? rec.requires.trim() : "";
+    if (!raw) return null;
+    const missing = raw.split(",").map((x) => x.trim()).filter(Boolean).filter((x) => !has(x));
+    return missing.length ? missing : null;
+  } catch {
+    return null;
+  }
+}
+
 // ПОЧЕМУ СПИСКОМ В МАНИФЕСТЕ, А НЕ ФЛАГОМ ПРОГОНА. Флаг «не роняй ничего» — это тот самый
 // `continue-on-error`, против которого написана наша запись ci-actually-fails: он понижает всё
 // разом, не виден в дифе и не назван в сводке. Список виден в манифесте, называется поимённо и
 // печатается КАЖДЫЙ прогон: совещательный гейт, о котором забыли, — это выключенная проверка,
 // и молчать о нём нельзя.
+// СОВЕЩАТЕЛЬНЫЕ ГЕЙТЫ. Правило вводят в проект, где старый код ему не соответствует. Храповик
+// отвечает на это одним способом: старое становится долгом, новое блокируется. Второй способ —
+// показывать, не роняя, пока команда договаривается о правиле. Без него у человека остаётся
+// выбор из двух крайностей: включить и сломать сборку либо не включать вовсе.
+//
 function advisorySet(man) {
   const v = man?.advisory;
   if (Array.isArray(v)) return new Set(v.map((x) => String(x).trim()).filter(Boolean));
@@ -242,5 +373,5 @@ function manifestWithGate(text, slug, cmd) {
 
 export {
   parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
-  entryLifecycle, advisorySet, layoutChecks,
+  entryLifecycle, advisorySet, gateRequires, layoutChecks, coversOf, coversUnproven, unparsedLines,
 };

package/tool/lib/prove.mjs

@@ -13,7 +13,8 @@ import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CWD, exists } from "./core.mjs";
-import { parseManifest } from "./manifest.mjs";
+import { parseManifest, gateRequires } from "./manifest.mjs";
+import { whichSync } from "./repo.mjs";
 
 // Гейт можно доказать, если у него есть оба образца. Признак по образцам, а не по тексту
 // команды: запись, делегирующая готовому инструменту (`npx knip --directory .`), каталог
@@ -128,6 +129,15 @@ async function proveGates(man, { timeoutMs = 300000 } = {}) {
       continue;
     }
 
+    // Программы, без которой запись не работает, может не быть на машине — тогда доказывать
+    // нечем, а не «гейт сломан». Проверяется ДО запуска: без неё обёртка краснеет на обоих
+    // образцах, и вердикт вышел бы «краснеет на исправном коде».
+    const missing = await gateRequires(samplesDir, name, whichSync);
+    if (missing) {
+      results.push({ name, state: "unprovable", why: "needs-program", missing });
+      continue;
+    }
+
     // Образцы бывают написаны под КОНКРЕТНЫЙ рецепт: запись без переносимой проверки называет
     // его полем `samples_for`. Если в проекте стоит рецепт под другой язык, гонять по этим
     // образцам нечего — они на чужом языке. Найдено первым же прогоном на своём репозитории:

package/tool/lib/repo.mjs

@@ -47,6 +47,10 @@ const MARKS = [
   // чем `has_agent_config`: настройки заводят не все, а свод — почти каждый, кто работает с
   // агентом. Записи про личные файлы касаются именно вторых.
   ["has_agent_entry", ["CLAUDE.md", "AGENTS.md", ".claude", ".cursor/rules", ".github/copilot-instructions.md"]],
+  // Агенту подключены внешние инструменты через MCP. Отдельный признак, а не часть
+  // `has_agent_config`: настройки заводят почти все, а MCP-серверы — те, кто дал агенту
+  // браузер, базу или трекер. Записи про мёртвый сервер касаются только вторых.
+  ["has_mcp", [".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json", ".claude/mcp.json"]],
 ];
 
 async function detectFacts(man) {
@@ -253,6 +257,32 @@ function pickRecipe(rec, facts, missing) {
   return recipes.any || null;
 }
 
+// БРАУЗЕР У АГЕНТА. Проект с интерфейсом, у которого агенту нечем посмотреть на собственное
+// изменение, — это §16 методички: «прогон на живой системе перед сдачей, как пользователь, через
+// настоящий вход». Без браузера агент судит о своей работе по тому, что компилируется, а это
+// разные утверждения; мок-тесты сюда же.
+//
+// СОВЕТ, А НЕ ЗАПИСЬ КАТАЛОГА, и разница принципиальная. Запись каталога — машинная проверка с
+// вердиктом; здесь вердикта нет: отсутствие браузерного сервера не дефект, а незанятая
+// возможность. Красить это в красное значит требовать поставить инструмент — мы так не делаем
+// ни с чем другим.
+//
+// НАЗЫВАЮТСЯ ДВА, а не один. `chrome-devtools-mcp` от Google — трассировка производительности,
+// Lighthouse, сеть, консоль; `@playwright/mcp` от Microsoft — прогон сценариев в трёх движках.
+// Назвать один значит выдать выбор за факт: они решают разные задачи, и выбирает человек.
+// Проверено по реестру npm 2026-09-08: 1.9.0 и 0.0.80, оба живые, оба от первых лиц.
+//
+// НЕ ВСЕМ. Проекту без интерфейса браузер не нужен, а совет, показанный не тому, стоит доверия
+// всем остальным советам — та же норма, что у записей каталога.
+const BROWSER_SERVERS = ["chrome-devtools-mcp", "@playwright/mcp", "playwright-mcp", "puppeteer-mcp", "puppeteer"];
+
+function browserServerAdvice(facts, mcpText = "") {
+  if (!facts?.has_ui) return null;
+  const text = String(mcpText || "");
+  if (BROWSER_SERVERS.some((n) => text.includes(n))) return null;
+  return { servers: ["chrome-devtools-mcp", "@playwright/mcp"] };
+}
+
 function recipeFor(rec, facts) {
   const cmd = pickRecipe(rec, facts);
   if (!cmd) return L.recipe.none;
@@ -325,6 +355,6 @@ async function matchCatalog(query) {
 // который никто не берёт, читается как часть договора и мешает менять внутренности.
 export {
   whichSync,
-  EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor,
+  EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor, browserServerAdvice, MARKS,
   stems, overlap, matchCatalog,
 };

package/tool/program.mjs

@@ -17,6 +17,7 @@
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { c, SELF, commandRows } from "./lib/core.mjs";
+import { banner } from "./lib/banner.mjs";
 import { L } from "./i18n/index.mjs";
 import { cmdInit, cmdNote, cmdBlob, cmdStart } from "./commands/project.mjs";
 import { cmdDoctor } from "./commands/doctor.mjs";
@@ -26,6 +27,7 @@ import { cmdLearn } from "./commands/learn.mjs";
 import { cmdBadge } from "./commands/badge.mjs";
 import { cmdProve } from "./commands/prove.mjs";
 import { cmdContext } from "./commands/context.mjs";
+import { cmdVitals } from "./commands/vitals.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -84,6 +86,30 @@ if (IS_MAIN) {
     // Печатает состояние репозитория для КОНТЕКСТА агента, а не для человека. Зовётся хуком
     // SessionStart, поэтому ничего не запускает и всегда выходит с нулём: хук, роняющий запуск
     // агента из-за неготового проекта, отключат в тот же день, и не станет ни хука, ни блока.
+    // Заставка по --version: одно из двух мест, где человек встречается с комплектом впервые.
+    case "--version":
+    case "-v":
+    case "version": {
+      const { readFile } = await import("node:fs/promises");
+      const { join, dirname } = await import("node:path");
+      const { fileURLToPath } = await import("node:url");
+      let v = "";
+      try {
+        const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+        v = JSON.parse(await readFile(join(root, "package.json"), "utf8")).version || "";
+      } catch { /* пакет без package.json — версия просто не покажется */ }
+      console.log(`\n${banner()}\n`);
+      if (v) console.log(c.dim(`   версия ${v}\n`));
+      break;
+    }
+
+    // Смотрит не на репозиторий, а на саму обвязку: стоят ли инструменты гейтов, прописан ли
+    // хук в .git/hooks, получает ли агент состояние. Без неё это выясняется красным гейтом
+    // посреди коммита — в момент, когда человек занят другим и просто выключит проверку.
+    case "vitals":
+      await cmdVitals();
+      break;
+
     case "context":
       await cmdContext(rest);
       break;