agent-quality-kit 0.7.0 → 0.9.0

package/tool/lib/evidence.mjs

@@ -0,0 +1,124 @@
+// tool/lib/evidence.mjs — привязка доказательства к дифу.
+//
+// ЗАЧЕМ. «Готово = доказано» — центральное правило свода, и оно единственное из четырнадцати,
+// за которым не следила машина: в `AGENTS.md` его сторожем честно записан человек. Цена этого
+// измерена 2026-09-08 прогоном чужого инструмента по восьми нашим коммитам: `publish.yml`
+// менялся и не был назван ни одной командой проверки — и именно он оказался сломан. Коммит при
+// этом говорил «прогон: units 51, smoke 81». Утверждение было правдой и не относилось к делу.
+//
+// Механизм взят у [donecheck](https://github.com/AtharvaMaik/donecheck) (MIT, ноль
+// зависимостей). Своего разбора команд не пишем — берём идею, а не код: donecheck САМ запускает
+// команды проверки, а `doctor --run` их уже запустил, и обёртка означала бы двойной прогон
+// всего набора гейтов. Здесь данные уже есть.
+//
+// ОДНО ОТЛИЧИЕ, И ОНО НАМЕРЕННОЕ. donecheck считает файл покрытым и по голому имени. В нашем
+// каталоге имя `check.sh` носят два десятка разных файлов: мягкое сравнение объявило бы
+// покрытым каждый из них, стоит любому гейту напечатать это слово. Ошибка в сторону «покрыто»
+// — это тишина, а тишина здесь и есть предмет спора. Сравниваем строго, по полному пути.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { changedFiles, pathsIn, normPath } from "./scope.mjs";
+
+// Расширения, для которых «никто не проверил» — утверждение о деле. Документ не проверяется
+// прогоном по своей природе, и требовать этого значило бы красить каждую правку README.
+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", "toml", "ts", "tsx", "vue",
+  "yaml", "yml",
+]);
+
+// Образцы гейтов исключены по той же причине, по какой их исключает каждая сканирующая
+// проверка каталога: они существуют, чтобы быть неправильными, и командой проверки покрыты
+// быть не могут. Без этого замер дал восемь ложных находок из шестнадцати.
+function isSample(p) {
+  return /(^|\/)gates\/[^/]+\/(red|green)(\/|$)/.test(p);
+}
+
+function ext(p) {
+  const m = /\.([A-Za-z0-9]+)$/.exec(p);
+  return m ? m[1].toLowerCase() : "";
+}
+
+// Файлы кода, которые внёс диф. null — если ссылка не разобрана: «сравнили не с тем» обязано
+// отличаться от «изменений нет».
+function changedCode(ref, cwd) {
+  const all = changedFiles(ref, cwd);
+  if (all === null) return null;
+  return [...all].map(normPath).filter((p) => CODE_EXT.has(ext(p)) && !isSample(p)).sort();
+}
+
+// Куда гейт был НАПРАВЛЕН: цели из его команды. Проверка, обошедшая каталог и не нашедшая
+// ничего, файла не назовёт — и «просмотрен и чист» стало бы неотличимо от «никто не смотрел».
+// Различить это по выводу нельзя, а по команде можно: она говорит, куда гейт направляли.
+function targetsOf(cmd, isDir) {
+  const out = [];
+  for (const tok of String(cmd || "").split(/\s+/)) {
+    if (tok.startsWith("-")) continue;
+    const t = normPath(tok);
+    if (tok === "." || tok === "./") { out.push(""); continue; }
+    if (t && !t.includes("*") && isDir(t)) out.push(t.replace(/\/$/, ""));
+  }
+  return out;
+}
+
+// Три состояния, а не два, и это главное в этой функции.
+//
+//   named   — гейт напечатал путь файла: он его точно видел и что-то о нём сказал;
+//   silent  — гейт был направлен в каталог с этим файлом, но ничего не напечатал. Просмотрен и
+//             чист либо не просмотрен вовсе — по выводу это неразличимо, и выдавать одно за
+//             другое нельзя ни в ту, ни в другую сторону;
+//   none    — ни одна команда даже не была направлена туда, где файл лежит.
+//
+// Двух состояний хватило ровно до первого прогона: `tool/commands/doctor.mjs` попал в «никем
+// не проверен», хотя его обходят пять проверок — они просто промолчали, потому что нашли
+// чисто. Замеряно 2026-09-08.
+function coverage(files, results, isDir = () => false) {
+  const seen = results.map((r) => ({
+    name: r.name,
+    paths: pathsIn(`${r.cmd || ""}\n${r.out || ""}`),
+    targets: targetsOf(r.cmd, isDir),
+  }));
+  const covered = new Map();
+  const silent = new Map();
+  const uncovered = [];
+  for (const raw of files) {
+    const f = normPath(raw);
+    const by = seen.filter((n) => n.paths.has(f)).map((n) => n.name);
+    if (by.length) { covered.set(raw, by); continue; }
+    const aimed = seen
+      .filter((n) => n.targets.some((t) => t === "" || f === t || f.startsWith(`${t}/`)))
+      .map((n) => n.name);
+    if (aimed.length) silent.set(raw, aimed);
+    else uncovered.push(raw);
+  }
+  return { covered, silent, uncovered };
+}
+
+// Отпечаток того, о чём отчитывается расписка: базовый коммит, набор команд, содержимое файлов.
+// Изменилось что угодно из этого — расписка устарела, и «прогнал, потом поправил ещё три файла»
+// перестаёт быть неотличимым от «прогнал».
+//
+// files — пары [путь, содержимое]. Содержимое передаётся, а не читается здесь: вызывающий уже
+// держит файлы в руках, а функция без ввода-вывода проверяется модульно.
+function evidenceHash(base, commands, files) {
+  const h = createHash("sha256");
+  h.update(`base:${base || ""}\0`);
+  for (const c of commands) h.update(`cmd:${c?.cmd ?? c}\0`);
+  for (const [p, body] of [...files].sort((a, b) => String(a[0]).localeCompare(String(b[0])))) {
+    h.update(`path:${normPath(p)}\0`);
+    h.update(body === null || body === undefined ? "<missing>" : String(body));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+// Читает содержимое для отпечатка. Отсутствующий файл — тоже факт: удаление меняет расписку.
+function readForHash(files, cwd) {
+  return files.map((p) => {
+    try { return [p, readFileSync(join(cwd, p), "utf8")]; } catch { return [p, null]; }
+  });
+}
+
+export { changedCode, coverage, evidenceHash, readForHash };

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,107 @@ function parseManifest(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "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` — независимо от того, что написано в
+// манифесте. Второй пользователь прислал разбор: у него `rules: .temper/rules`, правила на
+// месте, гейт entry-links-exist их видит, СТУПЕНЬ считается по манифесту и берётся — а шапка
+// рисует два креста и советует сделать сделанное. Вывод расходился с собственным вердиктом
+// программы; это хуже, чем просто неверный вывод, потому что оба напечатаны рядом.
+// Поля `docs:` не существовало вовсе: методички было некуда перенести, и крест за них снять
+// было нельзя ничем. Умолчания остаются для тех, кто полей не завёл, — это большинство.
+function layoutChecks(man, inKit) {
+  const field = (name, dflt) => {
+    const v = man && typeof man === "object" && !Array.isArray(man) ? man[name] : null;
+    return typeof v === "string" && v.trim() ? v.trim() : dflt;
+  };
+  // Точка входа — тоже поле манифеста, и по той же причине: проект на `CLAUDE.md` получал крест
+  // за `AGENTS.md`, которого у него намеренно нет. Класс дефекта один, чинится он один раз.
+  const entries = (Array.isArray(man?.entry) ? man.entry : [])
+    .filter((e) => typeof e === "string" && e.trim())
+    .map((e) => e.trim());
+  return [
+    [field("docs", inKit ? "kit/docs" : ".aqk/docs"), inKit ? L.doctor.docsKit : L.doctor.docs],
+    [field("rules", inKit ? "kit/rules" : ".aqk/rules"), inKit ? L.doctor.rulesKit : L.doctor.rules],
+    ...(entries.length ? entries : ["AGENTS.md"]).map((e) => [e, L.doctor.agents]),
+    [".gitignore", L.doctor.gitignore],
+    [".git", L.doctor.git],
+  ];
+}
+
+// ЗАПИСЬ ЗАКРЫТА ДРУГИМ АРБИТРОМ. `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 [];
@@ -119,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));
@@ -215,5 +373,5 @@ function manifestWithGate(text, slug, cmd) {
 
 export {
   parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
-  entryLifecycle, advisorySet,
+  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 .`), каталог
@@ -63,7 +64,19 @@ function targetIsLast(parts) {
   return last === "." || last === "./";
 }
 
-function commandFor(cmd, dir) {
+// Путь уходит в СТРОКУ КОМАНДЫ, а её исполняет `sh` — не Node. Для `sh` обратный слэш это
+// экранирование, а не разделитель: `gates\\x\\red` превращается в `gatesxred`, каталога с таким
+// именем нет, обход молчит, гейт выходит с нулём — и доказательство объявляет ИСПРАВНЫЙ гейт
+// сломанным. Найдено вторым пользователем 2026-09-08 на Windows: `path.join` там даёт `\\`,
+// и падали ровно те записи, что обходят дерево через `find`; на `grep -r` выживали, потому что
+// Windows разбирает слэши сам. Худший из возможных отказов: комплект против «зелёного, потому
+// что ничего не проверялось» сам выдал зелёное за красное и отобрал у проекта ступень.
+// Нормализация стоит ЗДЕСЬ, а не у сборщика пути: это единственная дверь из мира путей Node
+// в мир оболочки, и закрывать её надо один раз, кто бы путь ни собрал.
+const forShell = (p) => String(p).replace(/\\/g, "/");
+
+function commandFor(cmd, dirRaw) {
+  const dir = forShell(dirRaw);
   const { parts, nativeAt } = unwrap(cmd);
   const out = parts.slice();
   out[out.length - 1] = dir;
@@ -116,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/lib/scope.mjs

@@ -33,6 +33,15 @@ const ANSI = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*[a-zA-Z]", "g");
 // принималась бы за находку и отбрасывалась.
 const CANDIDATE = /[\w.@+-]+(?:\/[\w.@+-]+)*\.[A-Za-z][A-Za-z0-9]{0,9}/g;
 
+// Все пути, названные в тексте. Тот же разбор, что при сужении: цвет снимается, вид пути
+// нормализуется. Вынесено отдельно, потому что покрытие спрашивает у вывода обратное:
+// не «попадает ли находка в диф», а «назвал ли гейт этот файл».
+function pathsIn(text) {
+  const out = new Set();
+  for (const m of String(text).replace(ANSI, "").matchAll(CANDIDATE)) out.add(normPath(m[0]));
+  return out;
+}
+
 function inScope(candidate, files) {
   const c = normPath(candidate);
   if (files.has(c)) return true;
@@ -128,4 +137,4 @@ function changedFiles(ref, cwd) {
   );
 }
 
-export { scopeOutput, splitAdvice, changedFiles };
+export { scopeOutput, splitAdvice, changedFiles, pathsIn, normPath };

package/tool/lib/templates.mjs

@@ -28,6 +28,7 @@ const MANIFEST_YML = [
   "",
   d.rules,
   "rules: .aqk/rules",
+  "docs: .aqk/docs",
   "gates:",
   ...d.gates,
   "",

package/tool/program.mjs

@@ -16,14 +16,18 @@
 
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { c, SELF } from "./lib/core.mjs";
+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";
 import { cmdAdd, cmdNew, cmdRatchet, cmdFind, cmdWhy } from "./commands/gates.mjs";
 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 { cmdContext } from "./commands/context.mjs";
+import { cmdVitals } from "./commands/vitals.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -67,46 +71,64 @@ if (IS_MAIN) {
     case "blob":
       await cmdBlob();
       break;
+    // Читает локальную переписку — поэтому только в терминал и всегда с кодом 0. Подробности
+    // и замер, на котором стоит отбор, — в шапке tool/commands/learn.mjs.
+    case "learn":
+      await cmdLearn();
+      break;
+
     case "report":
       await cmdReport();
       break;
     case "prove":
       await cmdProve();
       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;
     case "badge":
       await cmdBadge(rest);
       break;
     default: {
       // Ширина колонки считается, а не подбирается пробелами: строки в двух языках разной
       // длины, и вручную выровненная справка на втором языке разъезжается.
-      const h = L.help;
-      const rows = [
-        [`${SELF} init`, h.init],
-        [`${SELF} init --force`, h.initForce],
-        [`${SELF} start`, h.start],
-        [`${SELF} doctor`, h.doctor],
-        [`${SELF} doctor --run`, h.doctorRun],
-        [`${SELF} doctor --run --since main`, h.doctorSince],
-        [`${SELF} prove`, h.prove],
-        [`${SELF} add ${h.name}`, h.add],
-        [`${SELF} find "…"`, h.find],
-        [`${SELF} why "…"`, h.why],
-        [`${SELF} ratchet ${h.name}`, h.ratchet],
-        [`${SELF} new ${h.name}`, h.new],
-        [`${SELF} note "…"`, h.note],
-        [`${SELF} blob`, h.blob],
-        [`${SELF} report`, h.report],
-        [`${SELF} badge`, h.badge],
-      ];
+      const rows = commandRows(L).map((r) => [`${SELF} ${r.name}${r.args ? " " + r.args : ""}`, r.text]);
       const width = Math.max(...rows.map(([cmdText]) => cmdText.length));
       const lines = rows.map(([cmdText, text]) => `  ${c.bold(cmdText.padEnd(width))}   ${text}`);
       console.log(`
-  ${c.bold("aqk")} — ${h.tagline}
+  ${c.bold("aqk")} — ${L.help.tagline}
 
 ${lines.join("\n")}
 
-  ${c.dim(h.noInstall)}
-  ${c.dim(h.language)}
+  ${c.dim(L.help.noInstall)}
+  ${c.dim(L.help.language)}
   `);
       process.exit(cmd ? 1 : 0);
     }