agent-quality-kit 0.5.0 → 0.7.0

package/tool/lib/manifest.mjs

@@ -79,13 +79,62 @@ function parseManifest(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "gates", "samples", "ratchets", "lessons"];
+const KNOWN_KEYS = ["aqk", "entry", "rules", "gates", "samples", "ratchets", "lessons", "advisory"];
 
 function unknownKeys(man) {
   if (!man || typeof man !== "object" || Array.isArray(man)) return [];
   return Object.keys(man).filter((k) => !KNOWN_KEYS.includes(k));
 }
 
+// ЗРЕЛОСТЬ ЗАПИСИ. Каталог без зрелости — это список, в котором нельзя отличить проверенное от
+// свежего; при шестнадцати записях это держится на памяти, при чужих записях — уже нет.
+//
+// ПОЧЕМУ ВЫЧИСЛЯЕТСЯ, А НЕ ОБЪЯВЛЯЕТСЯ. Поле зрелости есть у всех троих соседей — `lifecycle`
+// у зондов Scorecard, `future`/`obsolete` у критериев значка OpenSSF — и у всех троих его
+// заполняет автор. Значение, которое написал автор, означает доверие к автору, а не факт: это
+// ровно тот способ, которым «зелёный» перестаёт что-либо значить. Здесь зрелость считается по
+// доказательству записи, и объявить её нельзя — попытка отклоняется приёмкой каталога.
+//
+// Исключение одно: `deprecated`. «Запись больше не ставят» из её собственных файлов не выводится
+// никак — это решение, а не факт. Цена решения — обязательная замена: запись, выведенная в
+// никуда, оставляет человека без ответа на вопрос «а что теперь».
+const LIFECYCLE_COMPUTED = ["stable", "experimental"];
+
+function entryLifecycle(rec) {
+  const declared = typeof rec?.lifecycle === "string" ? rec.lifecycle.trim() : "";
+  const supersededBy = typeof rec?.superseded_by === "string" ? rec.superseded_by.trim() : "";
+  // Тот же признак, которым каталог отделяет условную запись с первого дня: доказательство
+  // ссылается на журнал шишек — значит, запись родилась из настоящей поломки, а не из
+  // «это хорошая практика». Признак один на всю программу: разъехавшись, он дал бы приёмке
+  // и отчёту разные ответы про одну и ту же запись.
+  const proven = /incidents\//.test(String(rec?.proof || ""));
+  const state = declared === "deprecated" ? "deprecated" : proven ? "stable" : "experimental";
+  const why = L.lifecycle[state];
+
+  let problem = null;
+  if (declared === "deprecated" && !supersededBy) problem = L.lifecycle.noReplacement;
+  else if (LIFECYCLE_COMPUTED.includes(declared)) problem = L.lifecycle.notDeclarable(declared);
+  else if (declared && declared !== "deprecated") problem = L.lifecycle.unknown(declared);
+
+  return { state, why, supersededBy: supersededBy || null, problem };
+}
+
+// СОВЕЩАТЕЛЬНЫЕ ГЕЙТЫ. Правило вводят в проект, где старый код ему не соответствует. Храповик
+// отвечает на это одним способом: старое становится долгом, новое блокируется. Второй способ —
+// показывать, не роняя, пока команда договаривается о правиле. Без него у человека остаётся
+// выбор из двух крайностей: включить и сломать сборку либо не включать вовсе.
+//
+// ПОЧЕМУ СПИСКОМ В МАНИФЕСТЕ, А НЕ ФЛАГОМ ПРОГОНА. Флаг «не роняй ничего» — это тот самый
+// `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));
+  return new Set();
+}
+
 async function readManifest() {
   const p = join(CWD, MANIFEST);
   if (!(await exists(p))) return null;
@@ -97,7 +146,11 @@ async function readManifest() {
 }
 
 // Каждая ступень: что требуется, как проверяется, и что это даёт человеку.
-async function assessLevel(man) {
+// `proof` — результат `proveGates`: { ok } либо null, если доказательства не было. Ступень
+// AQK-2 требует его прямо: до 2026-09-07 она проверяла, что папки образцов и храповиков
+// СУЩЕСТВУЮТ, и проект с тремя гейтами `true` проходил порог AQK-3 с зелёным значком.
+// Проверено прогоном на пустой папке. Наличие папки — не защита; уровень обязан означать факт.
+async function assessLevel(man, proof = null) {
   const has = async (rel) => Boolean(rel) && (await exists(join(CWD, String(rel))));
   const isUrl = (v) => typeof v === "string" && /^https?:\/\//.test(v);
 
@@ -113,10 +166,21 @@ async function assessLevel(man) {
   const conditions = [
     Boolean(man?.aqk) && entriesExist,
     (await has(man?.rules)) && filledGates.length > 0,
-    (await has(man?.samples)) && (await has(man?.ratchets)),
+    (await has(man?.samples)) && (await has(man?.ratchets)) && proof?.ok === true,
     isUrl(man?.lessons) || (await has(man?.lessons)),
   ];
-  const steps = conditions.map((ok, level) => ({ level, ok, ...L.levels[level] }));
+  // Ступени, которым нужно доказательство, помечаются отдельно: «не выполнено» и «не проверяли»
+  // — разные состояния, и печатать их одинаково значит врать ровно тем способом, против
+  // которого весь комплект.
+  const NEEDS_PROOF = 2;
+  const steps = conditions.map((ok, level) => ({
+    level,
+    ok,
+    // Ровно вторая: третья ступень проверяет журнал, и посылать за доказательством там
+    // значит указать не на ту недостачу. Найдено код-ревью 2026-09-07.
+    needsProof: level === NEEDS_PROOF && proof === null,
+    ...L.levels[level],
+  }));
 
   let reached = -1;
   for (const s of steps) {
@@ -149,4 +213,7 @@ function manifestWithGate(text, slug, cmd) {
   return { text: out, why: null };
 }
 
-export { parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS };
+export {
+  parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
+  entryLifecycle, advisorySet,
+};

package/tool/lib/prove.mjs

@@ -0,0 +1,160 @@
+// tool/lib/prove.mjs — доказательство гейтов проекта: краснеет ли гейт на своём красном
+// образце и молчит ли на зелёном.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ СУЩЕСТВУЕТ. Уровень AQK до 2026-09-07 считался наличием файлов: есть папка
+// правил, объявлен хоть один гейт, существуют папки образцов и храповиков, есть журнал. Проект
+// с тремя гейтами `true` — командой, которая всегда отвечает «ок», — проходил порог AQK-3 и
+// получал значок. Проверено прогоном на пустой папке; три «гейта», ноль защиты, высший уровень.
+//
+// Это ровно тот класс, против которого весь комплект: `pytest || true`, только на уровне всего
+// стандарта. Наше же правило гласит: «если утверждение не проверяется машиной — его в стандарте
+// нет». Уровень был самым громким нашим утверждением, и машина проверяла у него `exists()`.
+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";
+
+// Гейт можно доказать, если у него есть оба образца. Признак по образцам, а не по тексту
+// команды: запись, делегирующая готовому инструменту (`npx knip --directory .`), каталог
+// образцов в команде не упоминает, но образцы у неё есть — их кладёт `aqk add`.
+async function samplesFor(samplesDir, name) {
+  if (!samplesDir) return null;
+  const red = join(CWD, samplesDir, name, "red");
+  const green = join(CWD, samplesDir, name, "green");
+  if (!(await exists(red)) || !(await exists(green))) return null;
+  return { red: join(samplesDir, name, "red"), green: join(samplesDir, name, "green") };
+}
+
+// Команда записи всегда кончается каталогом проверки: рецепт пишется как `… {dir}`, и при
+// установке `{dir}` превращается в «.». Чтобы прогнать гейт по образцу, подменяем ПОСЛЕДНЕЕ
+// слово команды. Делается это только для гейтов, у которых образцы есть, — то есть для
+// установленных из каталога, где форма команды наша и известна.
+// Обёртки снимаются ПЕРЕД тем, как решать что-либо о команде. Их две, и обе меняют смысл
+// первых слов:
+//
+//   `bash …/ratchet.sh <реестр> <команда…>` — мера постепенности. Без снятия доказательство
+//   гоняет гейт ВМЕСТЕ с реестром долга, и реестр перезаписывается находками из ОБРАЗЦА:
+//   на живом проекте это стёрло бы долг целиком. Поймано прогоном комплекта.
+//
+//   `bash gates/_native.sh <каталог> <команда…>` — фильтр образцов для родного инструмента.
+//   Его первый аргумент обязан ехать вместе с каталогом проверки: фильтр прячет пути
+//   `gates/*/red|green`, и оставленный «.» спрятал бы ровно то, что образец обязан показать, —
+//   красный образец прошёл бы зелёным.
+function unwrap(cmd) {
+  let parts = String(cmd).trim().split(/\s+/);
+  let nativeAt = -1;
+  for (let guard = 0; guard < 4; guard++) {
+    const r = parts.findIndex((p) => /ratchet\.sh$/.test(p));
+    if (r !== -1 && parts.length > r + 2) { parts = parts.slice(r + 2); continue; }
+    const n = parts.findIndex((p) => /_native\.sh$/.test(p));
+    if (n !== -1 && parts.length > n + 2) { nativeAt = n; break; }
+    break;
+  }
+  return { parts, nativeAt };
+}
+
+// Куда подставлять каталог образца. Рецепт каталога всегда кончается `{dir}`, и при установке
+// это превращается в «.». Если последнее слово не похоже на каталог проверки, подставлять
+// некуда: команда написана руками, и угадывать значит объявить исправный гейт сломанным.
+// Найдено код-ревью 2026-09-07 на примере `eslint . --max-warnings 0`.
+function targetIsLast(parts) {
+  const last = parts[parts.length - 1];
+  return last === "." || last === "./";
+}
+
+function commandFor(cmd, dir) {
+  const { parts, nativeAt } = unwrap(cmd);
+  const out = parts.slice();
+  out[out.length - 1] = dir;
+  // Фильтр образцов узнаёт, что ему дали именно образец, по своему первому аргументу.
+  if (nativeAt !== -1) out[nativeAt + 1] = dir;
+  return out.join(" ");
+}
+
+// Каким рецептом написаны образцы. Читается из `gate.yml`, который `aqk add` кладёт в проект
+// рядом с проверкой; если файла нет — молчим, значит запись не из каталога.
+async function samplesForRecipe(samplesDir, name) {
+  const yml = join(CWD, samplesDir, name, "gate.yml");
+  if (!(await exists(yml))) return null;
+  try {
+    const rec = parseManifest(await readFile(yml, "utf8"));
+    const lang = typeof rec?.samples_for === "string" ? rec.samples_for.trim() : "";
+    if (!lang) return null;
+    const recipe = String(rec?.recipes?.[lang] || "").trim();
+    if (!recipe) return null;
+    return { lang, prog: recipe.split(/\s+/)[0] };
+  } catch {
+    return null;
+  }
+}
+
+function run(cmd, timeoutMs) {
+  const r = spawnSync(cmd, { shell: true, encoding: "utf8", cwd: CWD, timeout: timeoutMs });
+  const out = `${r.stdout || ""}${r.stderr || ""}`.trim();
+  // Убитый по таймауту процесс возвращает null — это не «ноль», а «не знаем».
+  const code = r.status === null ? 124 : r.status;
+  return { code, out };
+}
+
+// Возвращает { proven, broken, unprovable, results } — числами и списком, чтобы вызывающий
+// сам решал, что печатать и чем краснеть.
+async function proveGates(man, { timeoutMs = 300000 } = {}) {
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  const samplesDir = typeof man?.samples === "string" ? man.samples.trim() : "";
+  const results = [];
+
+  for (const [name, rawCmd] of Object.entries(gates)) {
+    const cmd = String(rawCmd || "").trim();
+    if (!cmd) {
+      results.push({ name, state: "broken", why: "empty" });
+      continue;
+    }
+    const s = await samplesFor(samplesDir, name);
+    if (!s) {
+      results.push({ name, state: "unprovable", why: "no-samples" });
+      continue;
+    }
+
+    // Образцы бывают написаны под КОНКРЕТНЫЙ рецепт: запись без переносимой проверки называет
+    // его полем `samples_for`. Если в проекте стоит рецепт под другой язык, гонять по этим
+    // образцам нечего — они на чужом языке. Найдено первым же прогоном на своём репозитории:
+    // `dead-code` стоит у нас рецептом под JS (`knip`), а образцы у него питоновские, и
+    // «доказательство» объявляло исправный гейт сломанным.
+    // Сравниваем с командой БЕЗ обёрток: установленная запись выглядит как
+    // `bash gates/_native.sh . ruff check …`, и проверка по сырой строке объявляла бы
+    // «стоит другой рецепт» у каждой обёрнутой записи. Найдено код-ревью 2026-09-07:
+    // проект, поставивший `no-print-in-prod` с `ruff`, терял AQK-2 целиком.
+    const { parts: bare, nativeAt } = unwrap(cmd);
+    const effective = nativeAt === -1 ? bare : bare.slice(nativeAt + 2);
+    const forRecipe = await samplesForRecipe(samplesDir, name);
+    if (forRecipe && effective[0] !== forRecipe.prog) {
+      results.push({ name, state: "unprovable", why: "other-recipe", forRecipe });
+      continue;
+    }
+    if (!targetIsLast(bare)) {
+      results.push({ name, state: "unprovable", why: "no-target" });
+      continue;
+    }
+
+    const red = run(commandFor(cmd, s.red), timeoutMs);
+    const green = run(commandFor(cmd, s.green), timeoutMs);
+    if (red.code === 0) {
+      results.push({ name, state: "broken", why: "red-passed", red, green });
+    } else if (green.code !== 0) {
+      results.push({ name, state: "broken", why: "green-failed", red, green });
+    } else {
+      results.push({ name, state: "proven", red, green });
+    }
+  }
+
+  const proven = results.filter((r) => r.state === "proven").length;
+  const broken = results.filter((r) => r.state === "broken").length;
+  const unprovable = results.filter((r) => r.state === "unprovable").length;
+  // Доказательство состоялось, если ни один доказуемый гейт не сломан И хоть один доказан.
+  // Второе условие обязательно: проект, у которого все гейты недоказуемы, ничего не доказал —
+  // именно так выглядит подделка с тремя `true`.
+  return { proven, broken, unprovable, ok: broken === 0 && proven > 0, results };
+}
+
+export { proveGates, commandFor };

package/tool/lib/repo.mjs

@@ -38,6 +38,15 @@ const MARKS = [
   ["has_docker", ["Dockerfile", "compose.yml", "compose.yaml", "docker-compose.yml", "docker-compose.yaml"]],
   ["has_deps", ["package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml", "Gemfile", "pom.xml", "composer.json"]],
   ["has_env", [".env", ".env.example", ".env.sample"]],
+  // Обвес самого агента: настройки, хуки, права. Отдельный признак нужен, потому что записи
+  // про него не касаются проектов, где агента не настраивали вовсе, — а таких большинство.
+  // Файл `.claude/settings.json` есть и у того, кто настроил один только список разрешений;
+  // записи этой группы сами промолчат, если проверять в нём нечего.
+  ["has_agent_config", [".claude/settings.json", ".claude/settings.local.json", ".claude/hooks.json", ".claude/hooks/hooks.json"]],
+  // Агента здесь вообще используют: есть свод, который он читает при запуске. Признак шире,
+  // чем `has_agent_config`: настройки заводят не все, а свод — почти каждый, кто работает с
+  // агентом. Записи про личные файлы касаются именно вторых.
+  ["has_agent_entry", ["CLAUDE.md", "AGENTS.md", ".claude", ".cursor/rules", ".github/copilot-instructions.md"]],
 ];
 
 async function detectFacts(man) {
@@ -209,18 +218,38 @@ function whichSync(prog, env = process.env) {
 // Выбор рецепта под стек проекта. Одна логика на два места: и `doctor`, и `add` показывают
 // команду, но подставляют в неё разные пути — один в каталог пакета, другой в каталог проекта.
 // Пока это были две копии, правка доезжала до одной из них — нашёл собственный гейт дублей.
-function pickRecipe(rec, facts) {
+// `missing` — необязательный массив: сюда складываются имена программ, которых не хватило.
+// Без него отказ установки был тупиком: «нет команды ни под python, ни общей» — диагноз без
+// действия. Правило «находка без действия закрывает окно, а не дефект» мы требуем от записей
+// каталога; к собственной программе оно относится так же. Найдено первым прогоном в чужом
+// репозитории (httpx) 2026-09-07.
+function pickRecipe(rec, facts, missing) {
   const recipes = rec.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
 
   // Родной рецепт лучше переносимого — но только если его есть чем выполнить. Поставить
   // команду с неустановленной программой значит завести гейт, который встаёт с «not found»:
   // отсутствие сигнала неотличимо от успеха.
   const runnable = (c0) => Boolean(whichSync(String(c0).trim().split(/\s+/)[0]));
+
+  // `requires` проверяется ПЕРВЫМ. Раньше он стоял после перебора родных рецептов, и запись с
+  // рабочим родным рецептом и неудовлетворённым требованием ставилась как ни в чём не бывало —
+  // ровно тот отказ, ради которого поле и заведено. Приёмка и мутационная проверка применяют
+  // его безусловно; три реализации расходились. Найдено код-ревью 2026-09-07.
+  const needs = String(rec?.requires || "").trim().split(/[\s,]+/).filter(Boolean);
+  const lacking = needs.filter((p) => !whichSync(p));
+  if (lacking.length) {
+    for (const p of lacking) if (Array.isArray(missing) && !missing.includes(p)) missing.push(p);
+    return null;
+  }
+
   for (const lang of facts.langs) {
     if (!recipes[lang]) continue;
+    const prog = String(recipes[lang]).trim().split(/\s+/)[0];
     if (runnable(recipes[lang])) return recipes[lang];
-    console.log(c.dim(`  ${c.yellow("!")}  ${L.recipe.skipped(lang, String(recipes[lang]).split(/\s+/)[0])}`));
+    if (Array.isArray(missing) && !missing.includes(prog)) missing.push(prog);
+    console.log(c.dim(`  ${c.yellow("!")}  ${L.recipe.skipped(lang, prog)}`));
   }
+
   return recipes.any || null;
 }
 

package/tool/lib/scope.mjs

@@ -0,0 +1,131 @@
+// tool/lib/scope.mjs — разбор вывода гейта: сужение до дифа и отделение совета от находок.
+//
+// ЗАЧЕМ. Первый прогон в живом проекте показывает долг, накопленный годами: на репозитории в
+// 36 тысяч файлов это тысячи находок. Человек видит стену красного, понимает, что разобрать её
+// нельзя, и выключает проверку целиком. Это причина номер один, по которой такие инструменты
+// снимают, — и три независимых проекта из нашего разбора умеют показывать только внесённое
+// (reviewdog, `--since` у ratchets, четыре режима шума у react-doctor).
+//
+// ПОЧЕМУ ФИЛЬТР ВЫВОДА, А НЕ СПИСОК ФАЙЛОВ ГЕЙТУ. Гейт — произвольная команда оболочки: у
+// каждого инструмента свой способ принять список файлов, а у переносимых проверок его нет
+// вовсе. Фильтр вывода работает с любым гейтом, ничего не требуя от записи каталога.
+//
+// ЧЕГО ЭТОТ ФИЛЬТР НЕ УМЕЕТ И НЕ ДЕЛАЕТ ВИД, ЧТО УМЕЕТ. Он сужает до ФАЙЛА, а не до строки.
+// Находка в файле, который диф трогал, показывается целиком, даже если она в нетронутой строке.
+// Сужение до строки требует разбора формата каждого инструмента — то есть ровно той привязки
+// к инструменту, которой у нас нет.
+
+import { spawnSync } from "node:child_process";
+
+// Один и тот же файл приезжает в трёх видах: `src/a.py`, `./src/a.py` и `src\a.py` на Windows.
+function normPath(p) {
+  return String(p).replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+// Цвет снимается ДО поиска путей. Родные инструменты печатают путь внутри
+// escape-последовательности, и сравнение видит не «src/a.py», а обрывок с управляющими
+// символами. На живом проекте это уже стоило одной починки, которая выглядела работающей:
+// вывод «сократился» с 5597 строк до 5505, то есть не сократился.
+const ANSI = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*[a-zA-Z]", "g");
+
+// Кандидат в путь: слово с расширением, начинающимся с БУКВЫ. Требование буквы отсекает номера
+// версий — «0.5.0» иначе читается как файл с расширением «0», и строка итога про версию
+// принималась бы за находку и отбрасывалась.
+const CANDIDATE = /[\w.@+-]+(?:\/[\w.@+-]+)*\.[A-Za-z][A-Za-z0-9]{0,9}/g;
+
+function inScope(candidate, files) {
+  const c = normPath(candidate);
+  if (files.has(c)) return true;
+  // Совпадение по хвосту в обе стороны: инструмент печатает то абсолютный путь, то голое имя
+  // файла. Здесь лучше ошибиться в сторону «показать»: спрятанная находка — это тишина,
+  // а лишняя показанная — просто шум, который человек отметает глазами.
+  for (const f of files) {
+    if (c.endsWith(`/${f}`) || f.endsWith(`/${c}`)) return true;
+  }
+  return false;
+}
+
+// Возвращает: что осталось показать, сколько среди этого НАХОДОК и можно ли этот гейт сузить.
+//
+// `scopable: false` — важнее всего остального. Гейт, который печатает вердикт без путей
+// (проверка сообщения коммита, проверка конфига конвейера), сузить дифом нельзя. Признать его
+// успешным на этом основании значило бы получить зелёное молчание там, где проверка провалилась,
+// — ровно та тишина, против которой построен весь стандарт. Вызывающий обязан оставить такой
+// гейт красным и сказать, почему он не сужен.
+function scopeOutput(lines, files) {
+  const kept = [];
+  let findings = 0;
+  let scopable = false;
+
+  for (const raw of lines) {
+    const plain = String(raw).replace(ANSI, "");
+    const candidates = plain.match(CANDIDATE) || [];
+    if (!candidates.length) {
+      // Строка без пути — это шапка, итог или пояснение. Показываем: без неё находка теряет
+      // контекст. Находкой не считаем: иначе гейт никогда не сузился бы до нуля.
+      kept.push(raw);
+      continue;
+    }
+    scopable = true;
+    if (candidates.some((c) => inScope(c, files))) {
+      kept.push(raw);
+      findings++;
+    }
+  }
+  return { kept, findings, scopable };
+}
+
+// СОВЕТ ПО ПОЧИНКЕ — ЭТО НЕ ХВОСТ ВЫВОДА, А ЕГО ГЛАВНАЯ ЧАСТЬ.
+//
+// Все записи каталога печатают последней строкой «почини: …». `doctor --run` показывал три
+// первые строки и обрезал остальное — то есть ровно эту строку человек не видел никогда.
+// Находка без действия закрывает окно, а не дефект. Отделяем совет от находок, чтобы находки
+// можно было обрезать, а совет — нет.
+//
+// Опознаётся по метке в начале строки на любом из двух языков; продолжение совета — все строки
+// после метки. Без метки совет не выдумывается: вывод, где не сказано, что делать, — это признак
+// записи, которой нечего ответить, и приёмка каталога такую запись отклоняет.
+const ADVICE_RE = /^\s*(почини|fix)\s*:/i;
+
+// Находка опознаётся по «путь:строка:» — тем же признаком, что и при сужении по дифу.
+// Нужен здесь, чтобы отличить продолжение совета от находки, стоящей сразу за ним.
+const FINDING_RE = /:\d+:/;
+
+function splitAdvice(lines) {
+  const findings = [];
+  const advice = [];
+  let inAdvice = false;
+
+  for (const raw of Array.isArray(lines) ? lines : []) {
+    const plain = String(raw).replace(ANSI, "");
+    if (ADVICE_RE.test(plain)) { inAdvice = true; advice.push(raw); continue; }
+    // Продолжение совета — строка с отступом, в которой нет находки. Всё остальное закрывает
+    // совет: иначе первая же метка утаскивала бы в жёлтое весь оставшийся вывод, а гейты
+    // печатают совет и посреди находок тоже. На живом выводе это давало сорок строк без
+    // обрезки — ровно ту стену, против которой написан весь модуль.
+    if (inAdvice && /^\s/.test(plain) && !FINDING_RE.test(plain)) { advice.push(raw); continue; }
+    inAdvice = false;
+    findings.push(raw);
+  }
+  return { findings, advice };
+}
+
+// Файлы, изменённые относительно ссылки. Новые файлы, ещё не добавленные в индекс, тоже входят:
+// их код так же нов, как и остальной диф, а из `git diff` они не видны.
+function changedFiles(ref, cwd) {
+  const git = (args) => {
+    const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return r.status === 0 ? String(r.stdout || "") : null;
+  };
+  // Точка расхождения, а не сама ссылка: сравнение с веткой, ушедшей вперёд, показало бы
+  // чужие изменения как свои. Если базы нет (ссылка — коммит в той же линии), берём её саму.
+  const base = (git(["merge-base", ref, "HEAD"]) || "").trim() || ref;
+  const diff = git(["diff", "--name-only", base]);
+  if (diff === null) return null;
+  const untracked = git(["ls-files", "--others", "--exclude-standard"]) || "";
+  return new Set(
+    `${diff}\n${untracked}`.split("\n").map((l) => normPath(l.trim())).filter(Boolean)
+  );
+}
+
+export { scopeOutput, splitAdvice, changedFiles };

package/tool/lib/templates.mjs

@@ -38,6 +38,8 @@ const MANIFEST_YML = [
   d.lessons,
   'lessons: ""',
   "",
+  ...d.advisory,
+  "",
 ].join("\n");
 
 export { AGENTS_MD, CLAUDE_MD, MANIFEST_YML, GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE };

package/tool/program.mjs

@@ -23,6 +23,7 @@ import { cmdDoctor } from "./commands/doctor.mjs";
 import { cmdAdd, cmdNew, cmdRatchet, cmdFind, cmdWhy } from "./commands/gates.mjs";
 import { cmdReport } from "./commands/report.mjs";
 import { cmdBadge } from "./commands/badge.mjs";
+import { cmdProve } from "./commands/prove.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -69,6 +70,9 @@ if (IS_MAIN) {
     case "report":
       await cmdReport();
       break;
+    case "prove":
+      await cmdProve();
+      break;
     case "badge":
       await cmdBadge(rest);
       break;
@@ -82,6 +86,8 @@ if (IS_MAIN) {
         [`${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],

package/tool/selfcheck/gates.sh

@@ -11,6 +11,15 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 CAT="$ROOT/kit/gates"
 PASS=0; FAIL=0; WARN=0; UNVERIFIED=0
 
+# СТРОГИЙ РЕЖИМ. «Не проверена здесь» — законное состояние на чужой машине, где нужного
+# инструмента нет: требовать ruff от каждого, кто склонировал репозиторий, значит закрыть вклад.
+# Но на НАШЕЙ машине, где инструменты ставятся отдельным шагом, это состояние означает, что шаг
+# не сработал, — и жёлтая тильда неотличима от успеха ровно так же, как `pytest || true`.
+# Проверено 2026-09-07: шаг `pipx install vulture` стоял в конвейере с самого его появления,
+# ставил vulture исправно и клал его в каталог, которого нет в PATH задания. Запись dead-code не
+# проверялась конвейером ни разу, и об этом никто не узнал.
+STRICT="${AQK_GATES_STRICT:-0}"
+
 ok()   { printf '  \033[32m✔\033[0m  %s\n' "$1"; PASS=$((PASS+1)); }
 bad()  { printf '  \033[31m✘\033[0m  %s\n' "$1"; FAIL=$((FAIL+1)); }
 warn() { printf '  \033[33m!\033[0m  %s\n' "$1"; WARN=$((WARN+1)); }
@@ -22,6 +31,30 @@ field() { sed -n "s/^$2:[[:space:]]*\(.*\)$/\1/p" "$1" | head -1; }
 printf '\n\033[1mtool/selfcheck/gates.sh\033[0m\n\n'
 [ -d "$CAT" ] || { echo "  каталога гейтов нет"; exit 1; }
 
+# Зрелость каждой записи одной таблицей. Правило живёт в entryLifecycle (tool/lib/manifest.mjs);
+# повторять его здесь на sh нельзя — второй источник истины расходится с первым молча.
+# Язык принудительно русский: это внутренняя проверка комплекта, и её вывод целиком русский.
+# Без этого на машине с английской локалью половина строки печаталась по-русски, половина —
+# по-английски, в одном предложении.
+LIFE="$(AQK_LANG=ru node "$ROOT/tool/selfcheck/lifecycle.mjs" 2>/dev/null)"
+life_field() { printf '%s\n' "$LIFE" | awk -F'|' -v s="$1" -v n="$2" '$1==s{print $n}'; }
+
+# Запускает ОДИНОКУЮ копию check.sh — без соседнего _skip.sh — на зелёном образце записи.
+# Успех означает провал приёмки: проверка, потерявшая свою библиотеку, обязана сказать об этом,
+# а не выдать вердикт «чисто». Зелёный образец взят намеренно: на нём одинокая копия и раньше
+# «проходила», так что разницу даёт именно потеря библиотеки, а не наличие нарушения.
+lonely_copy_fails() {
+  _g="$1"
+  [ -f "$_g/check.sh" ] || return 0
+  _t="$(mktemp -d)" || return 0
+  mkdir -p "$_t/lone"
+  cp "$_g/check.sh" "$_t/lone/check.sh"
+  bash "$_t/lone/check.sh" "$_g/green" >/dev/null 2>&1
+  _c=$?
+  rm -rf "$_t"
+  [ "$_c" -ne 0 ]
+}
+
 for GATE in "$CAT"/*/; do
   SLUG="$(basename "$GATE")"
   YML="$GATE/gate.yml"
@@ -71,9 +104,18 @@ for GATE in "$CAT"/*/; do
   printf '%s\n' "$README_TEXT" | grep -qE 'чего НЕ ловит|Чего НЕ ловит|чего не ловит|Чего не ловит' \
     || bad "$SLUG: в README нет раздела «чего НЕ ловит» — граница записи обязана быть названа"
 
-  case "$PROOF" in
-    *incidents/*) : ;;
-    *) warn "$SLUG: доказательство не ссылается на журнал шишек — запись условная" ;;
+  # Зрелость не объявляют — её считают. Попытка написать `lifecycle: stable` руками отклоняется:
+  # поле, которое заполняет автор, означает доверие к автору, а не факт. Это ровно тот способ,
+  # которым «зелёный» у соседей перестал что-либо значить, — см. kit/gates/README.md.
+  LIFE_PROBLEM="$(life_field "$SLUG" 4)"
+  # continue, а не просто отметка: запись с неверным объявлением уже отклонена, и гонять по ней
+  # образцы значит посчитать её и в отклонённых, и в принятых — итог начинает врать.
+  [ -n "$LIFE_PROBLEM" ] && { bad "$SLUG: $LIFE_PROBLEM"; continue; }
+
+  STATE="$(life_field "$SLUG" 2)"
+  case "$STATE" in
+    experimental) warn "$SLUG: доказательство не ссылается на журнал шишек — запись условная" ;;
+    deprecated)   warn "$SLUG: выведена из употребления, заменяет её «$(life_field "$SLUG" 3)»" ;;
   esac
 
   # --- образцы ---------------------------------------------------------------
@@ -81,7 +123,22 @@ for GATE in "$CAT"/*/; do
   # чью программу видно в системе: запись, которой нужен готовый инструмент, законна (правило
   # «сперва готовое»), но проверить её можно только там, где инструмент стоит.
   RECIPE="$(sed -n 's/^[[:space:]]*any:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1)"
+  PORTABLE=1
+
+  # Программа, названная полем `requires`. Нужна там, где переносимый рецепт — обёртка вокруг
+  # готового инструмента: первое слово команды тогда `bash`, и по нему не видно, чего не хватает.
+  # Без этой поправки отсутствие `checkwash` читалось как «гейт ругается на исправный код».
+  NEEDS="$(sed -n 's/^requires:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1 | tr ',' ' ')"
+  LACK=""
+  for PROG in $NEEDS; do
+    command -v "$PROG" >/dev/null 2>&1 || LACK="${LACK:+$LACK, }$PROG"
+  done
+  if [ -n "$LACK" ]; then
+    skip "$SLUG: НЕ ПРОВЕРЕНА здесь — нужен «$LACK»"
+    continue
+  fi
   if [ -z "$RECIPE" ]; then
+    PORTABLE=0
     # Каким рецептом написаны образцы — говорит сама запись. Угадывать нельзя: в системе может
     # стоять npx, и питоновские образцы поедут проверяться фронтовым инструментом. Так и вышло.
     FOR="$(sed -n 's/^samples_for:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1)"
@@ -121,8 +178,28 @@ for GATE in "$CAT"/*/; do
     bad "$SLUG: арбитр промолчал на КРАСНОМ образце — гейт не ловит брак"
   elif [ -z "$RED_OUT" ]; then
     bad "$SLUG: арбитр покраснел на красном молча — по коду возврата не видно, ту ли поломку он нашёл"
+  # Находка без действия закрывает окно, а не дефект. Строка «почини: …» была у всех записей и
+  # раньше — но обрезалась в выводе прогона, то есть существовала для приёмки и не существовала
+  # для человека. Теперь она обязательна и здесь: правило, за которым не следит машина, — это
+  # пожелание, и через месяц запись без совета проедет незамеченной.
+  #
+  # ТОЛЬКО ДЛЯ ПЕРЕНОСИМОГО РЕЦЕПТА. Запись, целиком делегирующая готовому инструменту
+  # (`dead-code` — vulture, knip, staticcheck), печатает вывод ЭТОГО инструмента. Требовать от
+  # чужого вывода нашу строку — значит требовать невозможного, а невыполнимое требование норма
+  # либо обходит молча, либо ломает всем.
+  elif [ "$PORTABLE" -eq 1 ] && ! printf '%s\n' "$RED_OUT" | grep -qiE '^[[:space:]]*(почини|fix)[[:space:]]*:'; then
+    bad "$SLUG: на красном образце не сказано, ЧТО делать — нужна строка «почини: …»"
   elif [ "$GRN_CODE" -ne 0 ]; then
     bad "$SLUG: арбитр покраснел на ЗЕЛЁНОМ образце — гейт ругается на исправный код"
+  # Проверка без своей библиотеки обязана краснеть, а не молчать. Найдено 2026-09-08: строка
+  # `. _skip.sh 2>/dev/null || SKIP_NAMES=…` стояла в десяти записях и страховкой не была.
+  # Под bash — а гейты запускаются именно им — она подставляла только ПЕРЕМЕННУЮ; функции
+  # обхода оставались неопределёнными, конвейер печатал пустоту, и гейт выходил с НУЛЁМ на
+  # файле с настоящим нарушением. Худший из возможных отказов: проверка объявляет «чисто»,
+  # не посмотрев никуда. Ставим прибор, чтобы это не вернулось молча.
+  elif [ "$PORTABLE" -eq 1 ] && grep -q '_skip.sh' "$GATE/check.sh" 2>/dev/null &&
+       ! lonely_copy_fails "$GATE"; then
+    bad "$SLUG: копия проверки без _skip.sh выходит с нулём — молчит вместо того, чтобы краснеть"
   else
     ok "$SLUG"
   fi
@@ -137,4 +214,10 @@ fi
 [ "$WARN" -gt 0 ] && printf '  \033[33m(условных: %s)\033[0m' "$WARN"
 [ "$UNVERIFIED" -gt 0 ] && printf '  \033[33m(не проверено здесь: %s)\033[0m' "$UNVERIFIED"
 printf '\n\n'
+
+if [ "$STRICT" = "1" ] && [ "$UNVERIFIED" -gt 0 ]; then
+  printf '  \033[31mстрогий режим: %s записей не проверено, а здесь это обязано быть ошибкой\033[0m\n' "$UNVERIFIED"
+  printf '  почини: поставь названные инструменты и убедись, что они видны в PATH этого шага.\n\n'
+  exit $((FAIL + UNVERIFIED))
+fi
 exit "$FAIL"