agent-quality-kit 0.8.0 → 0.10.0

package/tool/lib/cadence.mjs

@@ -0,0 +1,57 @@
+// tool/lib/cadence.mjs — когда комплект делает работу САМ, не дожидаясь, что о ней вспомнят.
+//
+// ЗАЧЕМ. Владелец сформулировал точнее, чем было в замысле: «команду, о которой надо вспомнить,
+// агент не вспомнит, а человек о ней не узнает». Это тот же класс, что файл, который можно не
+// прочитать, — и весь комплект написан против него. Команда `probe`, которую надо запускать
+// руками, наполовину бесполезна по построению: она отвечает на важнейший вопрос («что здесь не
+// прикрыто ничем») и не задаётся никем.
+//
+// РЕШЕНИЕ ТО ЖЕ, ЧТО У СОВЕТА И ПРОВЕРКИ ВЕРСИИ: не напоминать, а делать. Разница в единице.
+// Совет считает сутки — он про внимание человека. Проба считает КОММИТЫ: репозиторий, в котором
+// месяц не работали, перепроверять незачем, а сто коммитов за день перепроверить надо. Время
+// здесь не при чём, при чём — сколько кода написано с прошлого раза.
+//
+// ПОЧЕМУ СТО. Число выбрано так, чтобы проба не мешала: на нашем репозитории это примерно
+// две недели работы, а сама проба идёт секунды. Порог виден в выводе и меняется числом, а не
+// прячется: правило, которого не видно, через месяц читается как случайность.
+const PROBE_EVERY = 100;
+
+// `last` — то, что записала прошлая проба: { at: <число коммитов на тот момент> }.
+// `now` — сколько коммитов в репозитории сейчас; null, если счётчик взять не удалось.
+//
+// Пробы не было ВОВСЕ — она нужна, и нужна сразу, а не на сто первом коммите: молодой проект
+// узнал бы о своих дырах позже всех, хотя закрывать их дешевле всего именно в начале.
+function probeDue(last, now, every = PROBE_EVERY) {
+  if (now === null || now === undefined) return false;
+  const at = Number(last?.at);
+  if (!Number.isFinite(at)) return true;
+  return now - at >= every;
+}
+
+// Состояние для человека и для агента. ЧЕТЫРЕ исхода, и сливать их нельзя — по той же причине,
+// по которой их четыре у `vitals`: «не делалась» и «свежая» различаются тем, что в первом
+// случае мы ничего не знаем, а молчание читается как «всё хорошо».
+function probeState(last, now, every = PROBE_EVERY) {
+  if (now === null || now === undefined) return { state: "unknown", behind: null };
+  const at = Number(last?.at);
+  if (!Number.isFinite(at)) return { state: "never", behind: null };
+  const behind = now - at;
+  return { state: behind >= every ? "stale" : "fresh", behind };
+}
+
+// Порог из манифеста: `probe: 250` — раз в двести пятьдесят коммитов, `probe: 0` — не делать
+// вовсе. Число выбирается проектом, а не нами: сто коммитов на репозитории с десятком коммитов
+// в час — это трижды в день, а на редком проекте они не наберутся никогда.
+//
+// Неразобранное значение НЕ молчит: строка `probe: часто` означала бы «человек настроил», а
+// работал бы умолчательный порог — расхождение между написанным и происходящим, то самое,
+// против чего весь комплект. Возвращается null, и вызывающий говорит об этом вслух.
+function probeEvery(man) {
+  const raw = man?.probe;
+  if (raw === undefined || raw === null || String(raw).trim() === "") return PROBE_EVERY;
+  const n = Number(String(raw).trim());
+  if (!Number.isFinite(n) || n < 0) return null;
+  return n;
+}
+
+export { probeDue, probeState, probeEvery, PROBE_EVERY };

package/tool/lib/core.mjs

@@ -71,6 +71,7 @@ function commandRows(L) {
     { name: "doctor", args: "--run", text: h.doctorRun },
     { name: "doctor", args: "--run --since main", text: h.doctorSince },
     { name: "prove", args: "", text: h.prove },
+    { name: "probe", args: "", text: h.probe },
     { name: "add", args: h.name, text: h.add },
     { name: "find", args: '"…"', text: h.find },
     { name: "why", args: '"…"', text: h.why },
@@ -83,6 +84,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/history.mjs

@@ -0,0 +1,82 @@
+// tool/lib/history.mjs — что в ЭТОМ репозитории ломается на самом деле.
+//
+// ЗАЧЕМ. `doctor` говорит «держит машина 21». Двадцать один из чего? Знаменателя нет: 21 —
+// это то, что мы успели написать в каталог, а не то, что важно в конкретном проекте. Каталог
+// у нас — наш вкус; история проекта — его факты.
+//
+// Замер 2026-09-09 на самом комплекте: 45 коммитов-починок из 181, и рейтинг однозначный —
+// `tool/selfcheck/smoke.sh` чинили 22 раза, `tool/lib/manifest.mjs` — 5. Это те места, где
+// брак возвращается; там и стоит спрашивать, смотрит ли на них хоть одна проверка.
+//
+// ЧТО ЭТО НЕ ЗНАЧИТ. Часто чинят и то, что часто меняют: рейтинг говорит «сюда возвращаются»,
+// а не «здесь плохо». Ответ на «прикрыто ли» даёт не он, а проба — см. probeVerdict.
+
+// Признак починки берётся из ТЕМЫ коммита. Тема — единственное, что пишут все, и единственное,
+// что видно в `git log --oneline`.
+//
+// Три написания, потому что репозитории бывают на двух языках и с conventional commits. Якорь
+// на начало обязателен: без него «feat: prefix для путей» попадает в рейтинг из-за подстроки
+// «fix», и рейтинг перестаёт что-либо значить.
+const FIX_RE = /^\s*(fix|fixes|fixed|bugfix|hotfix|исправ|почин)/i;
+
+function isFix(subject) {
+  return FIX_RE.test(String(subject || ""));
+}
+
+// Разбор вывода `git log --format=%s --name-only`. Формат снят с живого репозитория, а не
+// придуман: ТЕМА, затем ПУСТАЯ строка, затем пути — и сразу следующая тема, без пустой строки
+// перед ней.
+//
+//   fix: разбор манифеста
+//   <пусто>
+//   tool/lib/manifest.mjs
+//   feat: новая запись
+//   <пусто>
+//   kit/gates/x/check.sh
+//
+// Отсюда единственный надёжный признак темы: за ней идёт пустая строка. По позиции её не
+// отличить — после последнего пути соседнего коммита тема начинается без разделителя.
+// Первая версия разбирала по выдуманному формату («пустая строка ПОСЛЕ файлов») и нашла ноль
+// починок там, где их сорок пять: ошибка молчала, потому что пустой рейтинг выглядит как
+// «история чистая». Тот же класс, что дважды поймал меня в тот же день.
+//
+// `isCode` передаётся вызывающим, а не берётся отсюда: набор расширений кода живёт в
+// evidence.mjs, и второй его список через месяц разошёлся бы с первым.
+function fixHotspots(raw, { isCode }) {
+  const counts = new Map();
+  const lines = String(raw || "").split("\n");
+  let inFix = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === "") continue;
+    if (lines[i + 1] === "") { inFix = isFix(line); continue; }
+    if (!inFix) continue;
+    const p = line.trim();
+    if (!p || !isCode(p)) continue;
+    counts.set(p, (counts.get(p) || 0) + 1);
+  }
+
+  return [...counts.entries()]
+    .map(([path, fixes]) => ({ path, fixes }))
+    // При равном числе починок — по алфавиту: вывод обязан быть одинаковым между прогонами,
+    // иначе его нельзя сравнить с прошлым и нельзя проверить машиной.
+    .sort((a, b) => b.fixes - a.fixes || a.path.localeCompare(b.path));
+}
+
+// Вердикт пробы по кодам возврата объявленных гейтов. ТРИ состояния, и сливать их нельзя.
+//
+// `2` у наших записей означает «проверка не состоялась» — делегированной программы нет на
+// машине. Засчитать это как «прикрыто» значило бы выдать отсутствие сигнала за успех: тот
+// самый отказ, против которого написан весь комплект. Засчитать как «не прикрыто» — тоже
+// неправда: мы не знаем.
+//
+// Поймавший гейт сильнее непроверенного: класс закрыт, даже если рядом чего-то не хватает.
+function probeVerdict(results) {
+  if (results.some((r) => r.code === 1)) return "caught";
+  if (results.length === 0) return "unknown";
+  if (results.some((r) => r.code !== 0)) return "unknown";
+  return "blind";
+}
+
+export { isFix, fixHotspots, probeVerdict };

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", "probe"];
 
 // ГДЕ У ПРОЕКТА ЛЕЖИТ РАЗЛОЖЕННЫЙ КОМПЛЕКТ. Список для шапки `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

@@ -26,6 +26,14 @@ const EXT_LANG = {
   ".cs": "csharp", ".sh": "shell", ".kt": "kotlin", ".swift": "swift", ".scala": "scala",
 };
 
+// Спецификация API — договор с чужим кодом. Опознаётся ПО ИМЕНИ ФАЙЛА, а не по расположению:
+// его кладут в корень, в `docs/`, рядом с приложением, — фиксированный список путей промахнулся
+// бы на большинстве проектов. Расширение обязательно разбираемое: `openapi.md` — это рассказ о
+// договоре, а не договор, и держать его нечем.
+function isApiSpec(name) {
+  return /^(openapi|swagger|asyncapi)[^/]*\.(ya?ml|json)$/i.test(name);
+}
+
 const SKIP_DIRS = new Set([".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__", ".aqk"]);
 
 // Факты о репозитории. Только то, что видно машине: спрашивать человека анкетой
@@ -47,6 +55,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) {
@@ -63,6 +75,7 @@ async function detectFacts(man) {
   // JS, где интерфейса нет вовсе. Записи, показанной не тому, не верят, и каталог теряет
   // доверие целиком, а не одной строкой.
   let hasUi = false;
+  let hasApiSpec = false;
 
   async function walk(dir, depth) {
     if (depth > 4 || files > 4000) return;
@@ -87,6 +100,7 @@ async function detectFacts(man) {
         if (/\.(test|spec)\.[a-z]+$/i.test(it.name) || /^test_.*\.py$/i.test(it.name) || /_test\.go$/i.test(it.name)) hasTests = true;
         if (it.name.endsWith(".sql")) hasDb = true;
         if (/\.(css|scss|sass|less|styl|vue|svelte|astro)$/i.test(it.name)) hasUi = true;
+        if (isApiSpec(it.name)) hasApiSpec = true;
         const dot = it.name.lastIndexOf(".");
         if (dot > 0) {
           const lang = EXT_LANG[it.name.slice(dot)];
@@ -104,6 +118,7 @@ async function detectFacts(man) {
     has_db: hasDb,
     has_tests: hasTests,
     has_ui: hasUi,
+    has_api_spec: hasApiSpec,
     has_gates: Object.values(gates).some((c) => String(c || "").trim()),
     gateKeys: Object.keys(gates),
   };
@@ -253,6 +268,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 +366,5 @@ async function matchCatalog(query) {
 // который никто не берёт, читается как часть договора и мешает менять внутренности.
 export {
   whichSync,
-  EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor,
-  stems, overlap, matchCatalog,
-};
+  EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor, browserServerAdvice, MARKS,
+  stems, overlap, matchCatalog, isApiSpec };

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";
@@ -25,7 +26,9 @@ import { cmdReport } from "./commands/report.mjs";
 import { cmdLearn } from "./commands/learn.mjs";
 import { cmdBadge } from "./commands/badge.mjs";
 import { cmdProve } from "./commands/prove.mjs";
+import { cmdProbe } from "./commands/probe.mjs";
 import { cmdContext } from "./commands/context.mjs";
+import { cmdVitals } from "./commands/vitals.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -81,9 +84,39 @@ if (IS_MAIN) {
     case "prove":
       await cmdProve();
       break;
+    // Осмотр, а не порог: всегда выходит с нулём. Отвечает на вопрос, которого нет ни у
+    // doctor («держит машина 21» — из чего?), ни у prove («гейт ловит брак на СВОЁМ образце»):
+    // что в ЭТОМ репозитории не прикрыто ничем.
+    case "probe":
+      await cmdProbe(rest);
+      break;
     // Печатает состояние репозитория для КОНТЕКСТА агента, а не для человека. Зовётся хуком
     // 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;