agent-quality-kit 0.6.0 → 0.8.0

package/tool/lib/prove.mjs

@@ -0,0 +1,172 @@
+// 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 === "./";
+}
+
+// Путь уходит в СТРОКУ КОМАНДЫ, а её исполняет `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;
+  // Фильтр образцов узнаёт, что ему дали именно образец, по своему первому аргументу.
+  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

@@ -1,4 +1,4 @@
-// tool/lib/scope.mjs — сужение вывода гейта до того, что внёс диф.
+// tool/lib/scope.mjs — разбор вывода гейта: сужение до дифа и отделение совета от находок.
 //
 // ЗАЧЕМ. Первый прогон в живом проекте показывает долг, накопленный годами: на репозитории в
 // 36 тысяч файлов это тысячи находок. Человек видит стену красного, понимает, что разобрать её
@@ -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;
@@ -75,6 +84,41 @@ function scopeOutput(lines, files) {
   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) {
@@ -93,4 +137,4 @@ function changedFiles(ref, cwd) {
   );
 }
 
-export { scopeOutput, 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,
   "",
@@ -38,6 +39,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

@@ -16,13 +16,16 @@
 
 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 { 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";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -66,42 +69,40 @@ 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, поэтому ничего не запускает и всегда выходит с нулём: хук, роняющий запуск
+    // агента из-за неготового проекта, отключат в тот же день, и не станет ни хука, ни блока.
+    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} 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);
     }

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)); }
@@ -30,6 +39,22 @@ printf '\n\033[1mtool/selfcheck/gates.sh\033[0m\n\n'
 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"
@@ -98,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)"
@@ -138,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
@@ -154,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"

package/tool/selfcheck/mutation.sh

@@ -19,11 +19,14 @@
 set -uo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 CAT="$ROOT/kit/gates"
-PASS=0; FAIL=0; SKIP=0
+PASS=0; FAIL=0; SKIP=0; UNVERIFIED=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)); }
 skip() { printf '  \033[2m·\033[0m  %s\n' "$1"; SKIP=$((SKIP+1)); }
+# «Нечем проверить здесь» — не то же, что «переносимого рецепта нет». Первое зависит от машины
+# и лечится установкой; второе — свойство записи. Счётчики разные, чтобы итог не врал о причине.
+unverified() { printf '  \033[33m~\033[0m  %s\n' "$1"; UNVERIFIED=$((UNVERIFIED+1)); }
 
 printf '\n\033[1mtool/selfcheck/mutation.sh\033[0m\n\n'
 [ -d "$CAT" ] || { echo "  каталога гейтов нет"; exit 1; }
@@ -54,6 +57,22 @@ for GATE in "$CAT"/*/; do
   # машине без неё «не проверено» было бы неотличимо от «проверено»: ровно та тишина, против
   # которой всё это написано. Записи без `any` называются вслух, а не пропускаются молча.
   RECIPE="$(sed -n 's/^[[:space:]]*any:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1)"
+  # Запись может назвать нужную ей программу полем `requires`: по первому слову команды этого
+  # не видно, обёртка вокруг готового инструмента начинается с `bash`. Без этой поправки
+  # `test-not-adjusted` на машине без `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
+  # Два разных состояния и два разных счётчика: «переносимого рецепта нет вовсе» и «рецепт есть,
+  # но нужного инструмента нет здесь». Один счётчик на оба означал бы, что итог врёт про причину
+  # — ровно то, что мы не прощаем гейтам. Найдено код-ревью 2026-09-07.
+  if [ -n "$LACK" ]; then
+    unverified "$SLUG: НЕ ПРОВЕРЕНА здесь — нужен «$LACK»"
+    continue
+  fi
   if [ -z "$RECIPE" ]; then
     skip "$SLUG: нет переносимого рецепта — мутации проверять нечем"
     continue
@@ -91,5 +110,6 @@ else
   printf '  \033[31mвердикт поплыл: %s\033[0m' "$FAIL"
 fi
 [ "$SKIP" -gt 0 ] && printf '  \033[2m(без переносимого рецепта: %s)\033[0m' "$SKIP"
+[ "$UNVERIFIED" -gt 0 ] && printf '  \033[33m(не проверено здесь: %s)\033[0m' "$UNVERIFIED"
 printf '\n\n'
 exit "$FAIL"