agent-quality-kit 0.10.0 → 0.11.0

package/tool/lib/history.mjs

@@ -9,7 +9,7 @@
 // брак возвращается; там и стоит спрашивать, смотрит ли на них хоть одна проверка.
 //
 // ЧТО ЭТО НЕ ЗНАЧИТ. Часто чинят и то, что часто меняют: рейтинг говорит «сюда возвращаются»,
-// а не «здесь плохо». Ответ на «прикрыто ли» даёт не он, а проба — см. probeVerdict.
+// а не «здесь плохо». Ответ на «прикрыто ли» даёт не он, а проба — см. probeVerdictPaired.
 
 // Признак починки берётся из ТЕМЫ коммита. Тема — единственное, что пишут все, и единственное,
 // что видно в `git log --oneline`.
@@ -71,12 +71,83 @@ function fixHotspots(raw, { isCode }) {
 // самый отказ, против которого написан весь комплект. Засчитать как «не прикрыто» — тоже
 // неправда: мы не знаем.
 //
-// Поймавший гейт сильнее непроверенного: класс закрыт, даже если рядом чего-то не хватает.
-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";
+
+// Итог пробы по всем её исходам. Отдельная функция, а не тернарник на месте: исходов у
+// у пробы три, и пока веток было две, `unknown` молча падал в «поймано всё».
+//
+// Замер 2026-09-10 на проекте с чужими командами: единственная запись вернула «нечем
+// проверить — инструмент делегирован и не установлен», а итог сказал «каждый применимый
+// класс кем-то ловится». Ошибка запуска, выданная за чистоту, — то самое, ради чего
+// написан стандарт, в его собственной главной команде.
+//
+// Сочетания названы исчерпывающе. `partial` существует потому, что «поймано три, проверить
+// две не смогли» и «поймано три» — разные факты, и сливать их значит округлять в свою пользу.
+// `unprobed` — горячие файлы, которым проба не делалась ВОВСЕ: красного образца их расширения
+// в каталоге нет. Прогон на самом комплекте 2026-09-10: два `.mjs` из пяти горячих файлов не
+// пробовались никак, а итог говорил «каждый применимый класс кем-то ловится». Оговорка «в
+// пробованных местах» верна буквально и обманывает по смыслу — она молча сужает утверждение до
+// мест, где проба удалась. Поэтому «чисто» отвечается только при нуле пропущенных.
+function probeSummary({ caught = 0, blind = 0, unknown = 0, unprobed = 0 } = {}) {
+  if (blind) return "blind";
+  if (caught && (unknown || unprobed)) return "partial";
+  if (caught) return "clean";
+  if (unknown) return "nothing-ran";
+  return "nothing-probed";
+}
+
+// Парный вердикт: гейт прогнан ДВАЖДЫ — по чистой песочнице и по ней же с подсаженным
+// образцом. Так проба перестаёт зависеть от формы команды: `npm test`, `pytest`, `xo`,
+// `eslint lib/**/*.js` работают наравне с `bash check.sh .`.
+//
+// Замер 2026-09-10: у шести чужих репозиториев из семи команды каталогом не кончаются, и
+// старая проба на них не запускалась вовсе. Способ не выдуман — так устроено мутационное
+// тестирование: Stryker копирует проект во временный каталог, симлинкует `node_modules` и
+// гоняет РОДНУЮ команду; прогон по чистой копии там обязателен.
+//
+// Что исключается из суждения и почему:
+//   · сбой ЗАПУСКА (код не 0 и не 1) с любой стороны — про подсадку не сказано ничего;
+//   · гейт, красный ЕЩЁ ДО подсадки, — его краснота объясняется состоянием проекта, и
+//     засчитывать её за поимку значит выдавать чужой долг за свою заслугу;
+//   · гейт, ПОЗЕЛЕНЕВШИЙ от подсадки, — он смотрит не туда, и это тоже не поимка.
+// Исключены все — вердикт `unknown`, а не `blind`: «не по чему судить» и «никто не ловит»
+// разные факты, и молчание здесь и есть предмет спора.
+function probeVerdictPaired(before, after) {
+  const byName = new Map(after.map((r) => [r.name, r]));
+  let usable = 0, alreadyRed = 0, failed = 0, caught = 0;
+  for (const b of before) {
+    const a = byName.get(b.name);
+    const broke = (r) => !r || (r.code !== 0 && r.code !== 1);
+    if (broke(b) || broke(a)) { failed++; continue; }
+    if (b.code === 1) { alreadyRed++; continue; }
+    usable++;
+    if (a.code === 1) caught++;
+  }
+  const verdict = !usable ? "unknown" : caught ? "caught" : "blind";
+  return { verdict, usable, alreadyRed, failed, caught };
+}
+
+// Счёт непокрытого КЛАССАМИ, а не пробами. Замер на десяти живых репозиториях 2026-09-10:
+// у requests, click, flask и httpx проба сказала «непокрытых классов: 18», а различных классов
+// там ШЕСТЬ — повторены по трём горячим файлам. Втрое завышенное число, и завышали его мы сами
+// тем самым приёмом, который ловим у других: считали события, а называли их сущностями.
+//
+// Число проб остаётся отдельно: «шесть классов на трёх файлах» и «шесть на одном» — разные
+// факты. Класс, слепой ХОТЬ ГДЕ-ТО, считается непокрытым: «где-то ловится» не защищает то
+// место, где не ловится.
+function countProbe(records) {
+  const bins = { blind: new Set(), caught: new Set(), unknown: new Set() };
+  let probes = 0;
+  for (const { entry, verdict } of records) {
+    if (!bins[verdict]) continue;
+    bins[verdict].add(entry);
+    probes++;
+  }
+  return {
+    blindClasses: bins.blind.size,
+    caughtClasses: bins.caught.size,
+    unknownClasses: bins.unknown.size,
+    probes,
+  };
 }
 
-export { isFix, fixHotspots, probeVerdict };
+export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe };

package/tool/lib/protection.mjs

@@ -0,0 +1,52 @@
+// tool/lib/protection.mjs — снимок объявленной защиты: кто его пишет и в каком виде.
+//
+// ОТДЕЛЬНЫМ МОДУЛЕМ, а не строкой в `add`: у формата снимка два читателя — эта запись и
+// проверка `kit/gates/protection-not-removed/check.sh`. Знание об одном файле, размазанное по
+// двум местам, однажды разъедется; здесь оно собрано с той стороны, где на JS.
+// Вторая копия неизбежна: проверка написана на POSIX sh и разделить с ней код нельзя —
+// поэтому шапка ниже и текст в её сообщении «почини» обязаны меняться вместе.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CWD, RATCHET_DIR, MANIFEST } from "./core.mjs";
+
+const HEADER =
+  "# Снимок объявленной защиты. Набор может только РАСТИ.\n" +
+  "# Убрал гейт — напиши причину после # в его строке, иначе проверка краснеет.\n";
+
+// СНИМОК ОБЪЯВЛЕННОЙ ЗАЩИТЫ ПИШЕТ УСТАНОВКА, А НЕ ПРОВЕРКА.
+//
+// Раньше его вёл сам гейт `protection-not-removed`: при отсутствии создавал, при появлении новых
+// имён дописывал. То есть проверка меняла то, о чём судит. Опыт 2026-09-09: в мелком клоне, где
+// удаление снимка лежит глубже выкладки, свидетель (история git) слеп — и проверка записала уже
+// ОСЛАБЛЕННЫЙ набор новым эталоном, вернув ноль. Храповик крутился назад.
+//
+// Здесь этому место по смыслу: `add` уже меняет манифест, и запись в снимок — часть того же
+// действия. Проверка теперь только сравнивает.
+async function recordProtection(man, slug) {
+  // `init` кладёт `ratchets: ""` намеренно: пустое поле честнее заглушки. Заполняем его при
+  // первой записи — ровно так же поступает `ratchet`. Иначе источников истины два: пустой
+  // манифест и умолчание внутри проверки, — и они однажды разойдутся.
+  let rdir = typeof man?.ratchets === "string" ? man.ratchets.trim() : "";
+  const manPath = join(CWD, MANIFEST);
+  if (!rdir) {
+    rdir = RATCHET_DIR;
+    try {
+      const t = await readFile(manPath, "utf8");
+      if (/^ratchets:\s*""\s*$/m.test(t)) {
+        await writeFile(manPath, t.replace(/^ratchets:\s*""\s*$/m, `ratchets: ${RATCHET_DIR}`), "utf8");
+      }
+    } catch { /* манифест не прочитан — снимок всё равно заведём в умолчательном каталоге */ }
+  }
+  const file = join(CWD, rdir, "gates-declared.txt");
+  let body = "";
+  try { body = await readFile(file, "utf8"); } catch { /* снимка ещё нет — заведём */ }
+  const names = body.split("\n").map((l) => l.replace(/\s*#.*$/, "").trim()).filter(Boolean);
+  if (names.includes(slug)) return;
+  const head = body ? body.replace(/\n?$/, "\n") : HEADER;
+  await mkdir(join(CWD, rdir), { recursive: true });
+  await writeFile(file, `${head}${slug}\n`, "utf8");
+}
+
+// Наружу — только запись. `HEADER` остаётся внутри: экспорт, который никто не берёт, читается
+// как часть договора и мешает менять внутренности. Поймал наш же dead-code.
+export { recordProtection };

package/tool/lib/prove.mjs

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { CWD, exists } from "./core.mjs";
 import { parseManifest, gateRequires } from "./manifest.mjs";
 import { whichSync } from "./repo.mjs";
+import { classify, findingCodes } from "./execution.mjs";
 
 // Гейт можно доказать, если у него есть оба образца. Признак по образцам, а не по тексту
 // команды: запись, делегирующая готовому инструменту (`npx knip --directory .`), каталог
@@ -102,12 +103,14 @@ async function samplesForRecipe(samplesDir, name) {
   }
 }
 
-function run(cmd, timeoutMs) {
+// Запуск возвращает РАЗОБРАННЫЙ исход, а не сырой код. Прежде здесь стояло
+// `code = r.status === null ? 124 : r.status`, и комментарий рядом честно называл 124
+// «не знаем» — а вызывающий тут же считал его находкой. Опыт 2026-09-09: проверка, виснущая
+// на красном образце, получала вердикт «доказана».
+function run(cmd, timeoutMs, prog) {
   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 };
+  return { ...classify(r, findingCodes(prog)), out };
 }
 
 // Возвращает { proven, broken, unprovable, results } — числами и списком, чтобы вызывающий
@@ -159,24 +162,48 @@ async function proveGates(man, { timeoutMs = 300000 } = {}) {
       continue;
     }
 
-    const red = run(commandFor(cmd, s.red), timeoutMs);
-    const green = run(commandFor(cmd, s.green), timeoutMs);
-    if (red.code === 0) {
+    // Программа, чьи коды разбираем: первое слово команды БЕЗ обёрток. У обёрнутой записи
+    // это ruff/vulture, а не bash, — иначе адаптер брался бы для оболочки.
+    const prog = effective[0];
+    const red = run(commandFor(cmd, s.red), timeoutMs, prog);
+    const green = run(commandFor(cmd, s.green), timeoutMs, prog);
+
+    // СБОЙ АРБИТРА — НЕ ВЕРДИКТ О ЗАПИСИ, ни в ту сторону, ни в другую. Раньше сбой на красном
+    // читался как «поймал», а сбой на зелёном — как «ругается на исправный код»: инструмент
+    // ломался, а обвиняли запись каталога. Оба случая теперь «доказать не смогли», и причина
+    // названа.
+    if (red.state === "infra_error" || green.state === "infra_error") {
+      const side = red.state === "infra_error" ? "red" : "green";
+      const bad = side === "red" ? red : green;
+      results.push({ name, state: "unprovable", why: "infra", side, reason: bad.reason, red, green });
+    } else if (red.state === "clean") {
       results.push({ name, state: "broken", why: "red-passed", red, green });
-    } else if (green.code !== 0) {
+    } else if (green.state === "finding") {
       results.push({ name, state: "broken", why: "green-failed", red, green });
     } else {
       results.push({ name, state: "proven", red, green });
     }
   }
 
+  return { ...verdict(results), results };
+}
+
+// ВЕРДИКТ ОТДЕЛЁН ОТ ПРОГОНА — чтобы правило можно было проверить без запуска процессов.
+//
+// Прежнее правило было `broken === 0 && proven > 0`, и оно позволяло ОДНОМУ доказанному гейту
+// компенсировать сколько угодно недоказанных: проект с пятью объявленными проверками, из
+// которых четыре не смогли отработать, получал AQK-2 за счёт пятой.
+//
+// Различие тонкое и обязательное. «Нечем доказывать» бывает ЗАКОННЫМ: нет образцов, нет
+// программы на этой машине, стоит рецепт под другой язык — ступень за это не отнимают, иначе
+// уровень стал бы зависеть от того, что установлено. А «запускали и не смогло отработать» —
+// сбой, и он ступень отнимает: иначе таймаут арбитра снова становится способом получить зелёное.
+function verdict(results) {
   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 };
+  const infra = results.filter((r) => r.state === "unprovable" && r.why === "infra").length;
+  return { proven, broken, unprovable, infra, ok: broken === 0 && infra === 0 && proven > 0 };
 }
 
-export { proveGates, commandFor };
+export { proveGates, commandFor, verdict };

package/tool/lib/run.mjs

@@ -0,0 +1,165 @@
+// tool/lib/run.mjs — ПРОГОН объявленных гейтов, отдельно от команды, которая его показывает.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫЙ ФАЙЛ. Прогон жил внутри `doctor.mjs`, и `report.mjs` с `badge.mjs` лезли за
+// ним ИЗ КОМАНДЫ В КОМАНДУ. Это не деталь: команда — это то, что человек набирает, а прогон —
+// то, что делает машина; у них разные причины меняться, и импорт команды из команды прятал
+// этот шов.
+//
+// Вскрылось 2026-09-10 нашим же гейтом: `doctor.mjs` дорос до 508 строк при пределе 500 —
+// файл был полон, и любая следующая правка ложилась туда просто потому, что «так ближе по
+// контексту». Ровно то, о чём предупреждает совет самого гейта.
+import { spawnSync } from "node:child_process";
+import { scopeOutput, splitAdvice, changedFiles } from "./scope.mjs";
+import { CWD, c, die } from "./core.mjs";
+import { advisorySet } from "./manifest.mjs";
+import { L } from "../i18n/index.mjs";
+
+
+// «Гейт объявлен» и «гейт работает» — разные утверждения. Первое читается из манифеста,
+// второе узнаётся только запуском. Пока doctor верил манифесту на слово, уровень означал
+// добросовестность автора, а не факт — ровно то, от чего мы защищаемся.
+//
+// Запуск чужих команд — по явной просьбе (--run), а не втихую: гейт бывает долгим и с
+// побочными действиями. Без флага doctor честно говорит, что не проверял.
+
+function declaredGates(man) {
+  const g = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  return Object.entries(g)
+    .map(([name, cmd]) => [name, String(cmd || "").trim()])
+    .filter(([, cmd]) => cmd);
+}
+
+// Ссылка, относительно которой сужается вывод: `--since main`, `--since HEAD~5`.
+// Без значения флаг бессмыслен — молча взять умолчание нельзя: «сужено не тем» неотличимо
+// от «не сужено».
+function sinceRef(argv = process.argv) {
+  const i = argv.indexOf("--since");
+  if (i === -1) return null;
+  const v = argv[i + 1];
+  return v && !v.startsWith("-") ? v : null;
+}
+
+function runGates(man, opts = {}) {
+  const gates = declaredGates(man);
+  if (!gates.length) return { failed: 0, ran: 0, results: [] };
+  const advisory = advisorySet(man);
+
+  // Сужение по дифу — договор с человеком, и он должен видеть, ЧТО именно сужено. Пустой диф
+  // называется вслух: иначе «все гейты зелёные» означало бы «сравнили не с тем» и читалось бы
+  // как успех. Это тот же класс, что и весь стандарт, только внутри нашего флага.
+  const scoped = opts.since ? changedFiles(opts.since, CWD) : null;
+  if (opts.since && scoped === null) die(L.doctor.sinceBadRef(opts.since));
+  if (scoped) console.log(c.dim(`\n  ${L.doctor.sinceHeading(opts.since, scoped.size)}`));
+
+  console.log(c.bold(`\n  ${L.doctor.runHeading}\n`));
+  let failed = 0;
+  const results = [];
+
+  for (const [name, cmd] of gates) {
+    const t0 = Date.now();
+    const r = spawnSync(cmd, { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+    const secs = (Math.max(0, Date.now() - t0) / 1000).toFixed(1);
+    // Вывод гейта запоминается целиком (с потолком, чтобы болтливый инструмент не съел память):
+    // по нему считается покрытие дифа — какой файл вообще был назван хоть одной проверкой.
+    // Без этого «готово = доказано» остаётся правилом, за которым следит только человек.
+    const outAll = `${r.stdout || ""}${r.stderr || ""}`.slice(0, 200000);
+
+    if (r.error && r.error.code === "ETIMEDOUT") {
+      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.timeout)}`);
+      failed++;
+      results.push({ name, cmd, ok: false, secs, note: L.doctor.timeout, out: outAll });
+      continue;
+    }
+    const code = r.status;
+    if (code === 0) {
+      // Совещательный называется и когда он зелёный. Иначе гейт, который уронить прогон НЕ
+      // МОЖЕТ, по выводу неотличим от того, который может, — и список `advisory:` в манифесте
+      // виден только в тот день, когда он покраснел. Измерено 2026-09-09: зелёный
+      // совещательный печатался обычной галочкой, а README обещал, что список назван каждый
+      // прогон. Тот же класс, что молчащий гейт, только про сам прибор.
+      const quiet = advisory.has(name) ? ` ${c.yellow(L.doctor.advisoryQuiet)}` : "";
+      console.log(`  ${c.green("✔")}  ${name.padEnd(14)}${quiet} ${c.dim(`${secs}s · ${cmd}`)}`);
+      // Зелёный гейт иногда всё-таки говорит человеку что-то важное: храповик, дошедший до цели,
+      // просит убрать обёртку. Вывод успешного гейта не показывался вовсе, и это сообщение
+      // уходило в никуда — тот же класс, что обрезанный совет у красного, только тише.
+      // Показываем ровно строки с меткой совета: остальной вывод успешной проверки — шум.
+      const okAdvice = splitAdvice(`${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean)).advice;
+      for (const line of okAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
+      results.push({ name, cmd, ok: true, secs, advisory: advisory.has(name), out: outAll });
+    } else {
+      const raw = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
+      // Совет отделяется ДО сужения. Иначе он сам попадает под фильтр по путям: сообщение
+      // храповика про вышедший срок называет путь к реестру, реестра в дифе нет, и гейт,
+      // обязанный краснеть по сроку, печатался зелёным с пометкой «находки вне дифа».
+      // Ровно то, что стандарт запрещает: срок без последствия. Найдено ревью 2026-09-06.
+      const parted = splitAdvice(raw);
+      let out = parted.findings;
+      const alwaysAdvice = parted.advice;
+
+      // Сужение до дифа. Три исхода, и все три называются вслух.
+      if (scoped) {
+        const s = scopeOutput(out, scoped);
+        // Гейт, у которого находок нет вовсе, а есть только совет, сузить нечем: его вердикт
+        // не про файлы. Признать такой успешным — вернуть ту же тишину другим путём.
+        if (!s.scopable || out.length === 0) {
+          // Гейт печатает вердикт без путей — сузить нечем. Признать его успешным значило бы
+          // выдать провал за тишину; остаётся красным, и причина названа.
+          // Совещательный не роняет прогон НИКОГДА — в том числе здесь. Раньше failed++ стоял
+          // безусловно, и гейт, объявленный совещательным, валил сборку с `--since` только
+          // потому, что в его выводе нет путей. Измерено 2026-09-09.
+          const nsAdv = advisory.has(name);
+          const nsMark = nsAdv ? c.yellow("!") : c.red("✘");
+          const nsVerdict = nsAdv ? c.yellow(L.doctor.advisoryMark) : c.red(L.doctor.exitCode(code));
+          console.log(`  ${nsMark}  ${name.padEnd(14)} ${nsVerdict} ${c.dim(`· ${L.doctor.notScopable}`)}`);
+          if (!nsAdv) failed++;
+          results.push({ name, cmd, ok: false, secs, code, advisory: nsAdv, note: L.doctor.notScopable, out: outAll });
+          continue;
+        }
+        if (s.findings === 0) {
+          // Долг есть, но не в том, что внёс диф. Зелёный — но с числом спрятанного: молчаливое
+          // «всё хорошо» здесь было бы неправдой.
+          const sQuiet = advisory.has(name) ? ` ${c.yellow(L.doctor.advisoryQuiet)}` : "";
+          console.log(`  ${c.green("✔")}  ${name.padEnd(14)}${sQuiet} ${c.dim(`${secs}s · ${L.doctor.outsideDiff(out.length)}`)}`);
+          results.push({ name, cmd, ok: true, secs, advisory: advisory.has(name), scopedAway: out.length, out: outAll });
+          continue;
+        }
+        out = s.kept;
+      }
+
+      failed++;
+      // Находки обрезаются, совет — никогда. Все записи каталога печатают «почини: …» последней
+      // строкой, и при обрезке до трёх строк человек не видел именно её: находка без действия
+      // закрывает окно, а не дефект.
+      // Совещательный гейт показывает находки и не роняет прогон. Знак другой, чтобы «показано»
+      // и «провалено» не читались одинаково; в сводке ниже он назван поимённо.
+      const isAdvisory = advisory.has(name);
+      if (isAdvisory) failed--;
+      const mark = isAdvisory ? c.yellow("!") : c.red("✘");
+      const verdict = isAdvisory ? c.yellow(L.doctor.advisoryMark) : c.red(L.doctor.exitCode(code));
+      console.log(`  ${mark}  ${name.padEnd(14)} ${verdict} ${c.dim(`· ${secs}s · ${cmd}`)}`);
+      // ГОЛОВА И ХВОСТ, А НЕ ТОЛЬКО ГОЛОВА. Гейт, который сам является прогоном (наш `smoke`),
+      // печатает сотни строк, и вердикт у него в конце — при обрезке до первых трёх человек
+      // видел «программа разбирается» и ни слова о том, что упало. Час поисков в конвейере
+      // 2026-09-09 стоил ровно этого. Голова нужна тоже: у сканирующих записей находки идут
+      // с первой строки.
+      const HEAD = 3, TAIL = 2;
+      for (const line of out.slice(0, HEAD)) console.log(c.dim(`        ${line.slice(0, 100)}`));
+      if (out.length > HEAD + TAIL) {
+        console.log(c.dim(`        ${L.doctor.moreLines(out.length - HEAD - TAIL)}`));
+        for (const line of out.slice(-TAIL)) console.log(c.dim(`        ${line.slice(0, 100)}`));
+      } else {
+        for (const line of out.slice(HEAD)) console.log(c.dim(`        ${line.slice(0, 100)}`));
+      }
+      // Совет тоже не бесконечен: гейт, зовущий помощник шесть раз, печатает его шесть раз.
+      for (const line of alwaysAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
+      results.push({ name, cmd, ok: false, secs, code, advisory: isAdvisory, out: outAll });
+    }
+  }
+  // Совещательные, которые покраснели, называются вслух ВСЕГДА. Молчание о них — ровно та
+  // тишина, против которой построен стандарт: проверка выключена, а выглядит как её отсутствие.
+  const advisoryFailed = results.filter((x) => x.advisory && !x.ok).map((x) => x.name);
+  if (advisoryFailed.length) console.log(`\n  ${c.yellow(L.doctor.advisorySummary(advisoryFailed))}`);
+  return { failed, ran: gates.length, results, advisoryFailed };
+}
+
+export { declaredGates, sinceRef, runGates };

package/tool/selfcheck/gates.sh

@@ -98,11 +98,39 @@ for GATE in "$CAT"/*/; do
   # приезжает туда с CRLF (`.gitattributes` держит LF только для `*.sh`), а `grep -i` с
   # кириллицей в сборке MSYS ведёт себя не так, как GNU grep. Регистр первой буквы назван
   # явно — это дешевле, чем полагаться на сворачивание регистра в чужой сборке grep.
+  # «Файла нет» и «раздела нет» — РАЗНЫЕ приговоры, а до 2026-09-10 оба звучали одинаково:
+  # `tr` из недоступного файла даёт пустую строку, grep по ней молчит, и запись обвинялась в
+  # том, чего не делала. Дважды наблюдался плавающий отказ этой самой проверки на записи,
+  # README которой на месте и раздел содержит; воспроизвести за сорок прогонов не удалось.
+  # Пока причина неизвестна, сообщение обязано называть, что именно случилось, — иначе
+  # следующий раз снова будет ложным обвинением вместо улики.
+  if [ ! -s "$GATE/README.md" ]; then
+    bad "$SLUG: README.md записи отсутствует или пуст — проверить разделы НЕЧЕМ, а не «их нет»"
+    continue
+  fi
   README_TEXT="$(tr -d '\r' < "$GATE/README.md" 2>/dev/null)"
-  printf '%s\n' "$README_TEXT" | grep -qE '[Гг]отовы(й аналог|й инструмент|е правил)|[Гг]отового аналога' \
-    || bad "$SLUG: в README нет раздела про готовый аналог — «не искал» и «нет» разные утверждения"
-  printf '%s\n' "$README_TEXT" | grep -qE 'чего НЕ ловит|Чего НЕ ловит|чего не ловит|Чего не ловит' \
-    || bad "$SLUG: в README нет раздела «чего НЕ ловит» — граница записи обязана быть названа"
+  if [ -z "$README_TEXT" ]; then
+    bad "$SLUG: README.md есть, но прочитать не удалось — проверка НЕ СОСТОЯЛАСЬ"
+    continue
+  fi
+  # Три исхода, а не два. `grep` отвечает 0 «нашёл», 1 «не нашёл» и 2+ «не смог»: при нехватке
+  # памяти или процессов он не запускается вовсе, и его код неотличим от «раздела нет». Отказ
+  # наблюдался трижды под тяжёлой параллельной нагрузкой, каждый раз на РАЗНОЙ записи, README
+  # которой на месте и раздел содержит; воспроизвести в покое не удалось за сорок прогонов.
+  # Причина не доказана — но обвинять запись в том, чего не проверяли, нельзя в любом случае.
+  printf '%s\n' "$README_TEXT" | grep -qE '[Гг]отовы(й аналог|й инструмент|е правил)|[Гг]отового аналога'
+  case $? in
+    0) : ;;
+    1) bad "$SLUG: в README нет раздела про готовый аналог — «не искал» и «нет» разные утверждения" ;;
+    *) bad "$SLUG: поиск раздела про готовый аналог НЕ СОСТОЯЛСЯ (grep вышел с кодом $?) — это не приговор записи" ;;
+  esac
+  # Те же три исхода, что и у поиска выше, и по той же причине.
+  printf '%s\n' "$README_TEXT" | grep -qE 'чего НЕ ловит|Чего НЕ ловит|чего не ловит|Чего не ловит'
+  case $? in
+    0) : ;;
+    1) bad "$SLUG: в README нет раздела «чего НЕ ловит» — граница записи обязана быть названа" ;;
+    *) bad "$SLUG: поиск раздела «чего НЕ ловит» НЕ СОСТОЯЛСЯ (grep вышел с кодом $?) — это не приговор записи" ;;
+  esac
 
   # Зрелость не объявляют — её считают. Попытка написать `lifecycle: stable` руками отклоняется:
   # поле, которое заполняет автор, означает доверие к автору, а не факт. Это ровно тот способ,

package/tool/selfcheck/smoke/_fixture.mjs

@@ -23,12 +23,34 @@ const CLI = join(ROOT, "tool", "program.mjs");
 // а ради того, чтобы висящий процесс называл себя, а не съедал бюджет задания молча.
 const TIMEOUT_MS = 30000;
 
-function env(home) {
+// Настоящий дом СНИМАЕТСЯ ОДИН РАЗ, до всякой подмены: из него берётся PYTHONUSERBASE.
+const REAL_HOME = process.env.HOME || process.env.USERPROFILE || "";
+
+function env(home, dir) {
   return {
     ...process.env,
+    // PYTHONUSERBASE — ИЗ-ЗА подмены HOME и до неё. Инструменты, поставленные `pip --user`
+    // (`vulture`, `pylint`), это python-скрипты, которые ищут свои модули в
+    // $HOME/.local/lib. С песочницей вместо HOME импорт падает, инструмент выходит ненулевым,
+    // и обёртка родного рецепта читает это как НАХОДКУ. То есть проверка краснела не на
+    // дефекте, а на собственной оснастке. Тот же довод дословно записан в шапке `smoke.sh`;
+    // здесь он был потерян при переезде на встроенный раннер.
+    PYTHONUSERBASE: process.env.PYTHONUSERBASE || `${REAL_HOME}/.local`,
     HOME: home,
     USERPROFILE: home,
     TMPDIR: join(home, "tmp"),
+    // ПОТОЛОК ПОИСКА РЕПОЗИТОРИЯ. Без него `git: false` не означает «вне репозитория»: git
+    // идёт вверх по дереву, и если ЛЮБОЙ предок временного каталога окажется репозиторием,
+    // подопытный проект молча получит чужую историю. Поймано 2026-09-10: проверка «гейт без
+    // репозитория обязан сказать "не смогли"» проходила поодиночке и падала внутри `smoke.sh`,
+    // потому что там над TMPDIR оказывался git. Один и тот же тест давал разные ответы в
+    // зависимости от того, чем занят каталог этажом выше, — то есть герметичность, ради
+    // которой этот файл написан, держалась на случайности.
+    //
+    // Указывается РОДИТЕЛЬ, а не сам каталог: git не поднимается ВЫШЕ потолка, но от стартового
+    // каталога до него доходит. С потолком, равным проекту, репозиторий этажом выше находился
+    // по-прежнему — проверено прямым опытом, а не выведено из документации.
+    GIT_CEILING_DIRECTORIES: dirname(dir),
     AQK_LANG: "ru",
     // Сеть в тестах — отдельный класс флейков, и у нас она включалась ТОЛЬКО вне конвейера:
     // локально проверки были сетевыми, в конвейере нет. Две разные среды по построению.
@@ -62,7 +84,7 @@ function project(t, files = {}, { git = true } = {}) {
 // что команда не роняет прогон.
 function run({ dir, home }, cmd, args = []) {
   const r = spawnSync(cmd, args, {
-    cwd: dir, encoding: "utf8", timeout: TIMEOUT_MS, env: env(home),
+    cwd: dir, encoding: "utf8", timeout: TIMEOUT_MS, env: env(home, dir),
   });
   return { code: r.status, out: `${r.stdout || ""}${r.stderr || ""}` };
 }

package/tool/selfcheck/smoke/fail-closed.test.mjs

@@ -0,0 +1,112 @@
+// tool/selfcheck/smoke/fail-closed.test.mjs — проверка, которая НЕ МОЖЕТ работать, обязана
+// сказать это, а не позеленеть.
+//
+// ЗАЧЕМ. Весь стандарт написан против одного: тишина читается как «чисто». Три раза подряд
+// он нарушен в нём самом — найдено 2026-09-10, когда проба впервые начала гонять гейты по
+// КОПИИ проекта и увидела их так же, как видит пользователь:
+//
+//   1. Подмена общей библиотеки `kit/gates/_skip.sh` даёт код 0. Гейт печатает
+//      «command not found» и объявляет проект чистым. Библиотеку подключает КАЖДАЯ запись
+//      каталога, то есть одним испорченным файлом гасится весь набор защит.
+//   2. Гейт, читающий историю, в каталоге без git возвращает 0 за ноль секунд. Он не прошёл —
+//      он не смог посмотреть, и разницы в выводе нет никакой.
+//
+// Обе — отказ В ОТКРЫТУЮ сторону: чем сильнее сломано, тем зеленее ответ. Договор один и тот
+// же, он уже записан в комплекте: 0 — проверено и чисто, 1 — находка, ВСЁ ОСТАЛЬНОЕ — «не
+// смогли проверить». Именно так `prove` и `execution.mjs` разбирают исход, и гейты обязаны
+// говорить на том же языке.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { cpSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { project, run, aqk } from "./_fixture.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const posix = (p) => String(p).replace(/\\/g, "/");
+
+// Ставит запись каталога В ПРОЕКТ вместе с общей библиотекой — так же, как это делает `aqk add`.
+// Библиотеку кладём отдельно, чтобы проверка могла её испортить: в исходном каталоге её портить
+// нельзя, там она общая на весь набор.
+function installGate(p, name, { skipLib } = {}) {
+  const dest = join(p.dir, "gates", name);
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(join(ROOT, "kit", "gates", name), dest, { recursive: true });
+  const lib = join(p.dir, "gates", "_skip.sh");
+  if (skipLib === undefined) cpSync(join(ROOT, "kit", "gates", "_skip.sh"), lib);
+  else writeFileSync(lib, skipLib, "utf8");
+  return posix(join("gates", name, "check.sh"));
+}
+
+test("гейт с ИСПОРЧЕННОЙ общей библиотекой не смеет отвечать «чисто»", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n" });
+  const check = installGate(p, "complexity-limit", { skipLib: "мусор вместо библиотеки\n" });
+  const r = run(p, "bash", [check, "."]);
+  assert.notEqual(r.code, 0,
+    `гейт вернул 0 при нерабочей библиотеке обхода. Вывод:\n${r.out}`);
+});
+
+test("та же запись с ЦЕЛОЙ библиотекой на том же проекте молчит — значит дело в поломке", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n" });
+  const check = installGate(p, "complexity-limit");
+  const r = run(p, "bash", [check, "."]);
+  assert.equal(r.code, 0, `гейт покраснел на исправном проекте. Вывод:\n${r.out}`);
+});
+
+// Второй отказ: истории нет — смотреть не на что. «Не смогли» и «чисто» обязаны различаться,
+// иначе проект без git получает зелёный прогон по построению.
+for (const name of ["commit-explains-itself", "test-not-adjusted"]) {
+  test(`«${name}» без репозитория говорит «не смогли», а не «чисто»`, (t) => {
+    const p = project(t, { "src/a.py": "x = 1\n" }, { git: false });
+    const check = installGate(p, name);
+    const r = run(p, "bash", [check, "."]);
+    assert.notEqual(r.code, 0,
+      `гейт вернул 0 там, где истории нет и посмотреть было не на что. Вывод:\n${r.out}`);
+  });
+}
+
+// У `protection-not-removed` свидетель — тоже история, но выходит он раньше: на отсутствии
+// манифеста. Поэтому проект здесь С манифестом и объявленными гейтами: сторожить есть что,
+// а посмотреть нечем.
+test("«protection-not-removed» без репозитория говорит «не смогли», а не «чисто»", (t) => {
+  const p = project(t, {
+    "src/a.py": "x = 1\n",
+    ".aqk.yml": "aqk: 1\nentry:\n  - AGENTS.md\ngates:\n  lint: \"true\"\n",
+    "AGENTS.md": "# проект\n",
+  }, { git: false });
+  const check = installGate(p, "protection-not-removed");
+  const r = run(p, "bash", [check, "."]);
+  assert.notEqual(r.code, 0,
+    `гейт вернул 0 там, где снимок сторожить нечем. Вывод:\n${r.out}`);
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Правило со сторожем-человеком обязано быть названо ЧЕЛОВЕКУ. Написано ДО кода 2026-09-10.
+//
+// ЗАЧЕМ. Отчёт живого проекта: «всё, что касается масштаба, помечено `aqk: человек`. AQK
+// отработал честно: потребовал назвать сторожа, мы назвали — и сторож не проверил». Пометка
+// `человек` — не сторож, а расписка в том, что сторожа нет: гейт `promise-has-gate` видит её
+// и идёт дальше (`if (tag == "человек") next`).
+//
+// Числа уже считаются и уже печатаются — но только в блоке `context`, который читает АГЕНТ.
+// Человеку, который и назначен сторожем, `doctor` про это не говорит ни слова. То есть
+// единственный, кто обязан помнить о непроверяемом обещании, — единственный, кому о нём не
+// сообщают. В нашем собственном своде так помечено 12 правил из 14.
+test("doctor называет человеку, сколько правил не сторожит машина", (t) => {
+  const p = project(t, {
+    "AGENTS.md": [
+      "# проект",
+      "## Правила",
+      "- **Секреты не в коде.** <!-- aqk: secrets-not-in-code -->",
+      "- **План до кода.** <!-- aqk: человек -->",
+      "- **Три попытки.** <!-- aqk: человек -->",
+      "",
+    ].join("\n"),
+    ".aqk.yml": 'aqk: 1\nentry:\n  - AGENTS.md\ngates:\n  lint: "true"\n',
+  });
+  const r = aqk(p, "doctor");
+  assert.match(r.out, /2/,
+    `doctor не назвал число правил со сторожем-человеком. Вывод:\n${r.out}`);
+  assert.ok(/человек/i.test(r.out),
+    `doctor не сказал про сторожа-человека ни слова, хотя таких правил здесь два.\n${r.out}`);
+});