agent-quality-kit 0.4.2 → 0.6.0

package/tool/i18n/templates-ru.mjs

@@ -16,17 +16,17 @@ const AGENTS_MD = `# AGENTS.md
 
 ## Железные правила
 
-- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.
-- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.
-- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.
-- **Секреты только в окружении.** Никогда в коде, логах и коммитах.
-- **Только файлы из задачи.** Заодно ничего не чиним.
-- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит
+- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.  <!-- aqk: человек -->
+- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.  <!-- aqk: человек -->
+- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.  <!-- aqk: человек -->
+- **Секреты только в окружении.** Никогда в коде, логах и коммитах.  <!-- aqk: secrets-not-in-code -->
+- **Только файлы из задачи.** Заодно ничего не чиним.  <!-- aqk: человек -->
+- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит  <!-- aqk: человек -->
   рабочим» — не готово.
-- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.
-- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием
+- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.  <!-- aqk: swallowed-error -->
+- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием  <!-- aqk: человек -->
   в коде.
-- **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.
+- **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.  <!-- aqk: человек -->
   Он собирается прогоном: пересказ по памяти всегда выбирает удобное и молчит о том, что гейт
   стоит на слабейшем рецепте.
 

package/tool/lib/baseline.mjs

@@ -0,0 +1,87 @@
+// tool/lib/baseline.mjs — обязательный минимум проекта, проверяемый прогоном.
+//
+// ЗАЧЕМ. `kit/docs/ai/project-baseline.md` — 50 пунктов «что обязано быть, чтобы работу можно
+// было отдать агентам». До сих пор это было единственное место, где комплект просил верить на
+// слово, что человек прочитал и сверился. Ручной проход по живому проекту нашёл настоящее:
+// логирование не задано вовсе, трекера ошибок нет, задачи конвейера не запускались ни разу.
+// Дисциплина не масштабируется — то, что проверяется машиной, проверяет машина.
+//
+// ЧЕСТНАЯ ГРАНИЦА. Машина проверяет НАЛИЧИЕ, а не работоспособность: «линтер настроен» — не то
+// же, что «линтер ловит». Поэтому вывод говорит, чем именно доказан пункт, а непроверяемые
+// пункты называются числом, а не прячутся.
+//
+// НЕЙТРАЛЬНОСТЬ К СТЕКУ — условие, а не пожелание. Каждый признак — это семейство маркеров
+// разных экосистем; пункт засчитывается по любому из них. Список, знающий только про npm,
+// объявил бы половину мира несоответствующей.
+
+// Совпадение по имени файла в корне: точное имя, либо имя, начинающееся с образца (`.eslintrc*`).
+function hit(files, names) {
+  const low = files.map((f) => f.toLowerCase());
+  return names.find((n) => {
+    const k = n.toLowerCase();
+    return k.endsWith("*") ? low.some((f) => f.startsWith(k.slice(0, -1))) : low.includes(k);
+  });
+}
+
+// Пункты, которые машина может подтвердить фактом, а не мнением. Остальные сорок с лишним
+// остаются человеку — и называются вслух, чтобы «не проверено» не читалось как «в порядке».
+const ITEMS = [
+  { n: 1, key: "oneCommand", files: ["makefile", "justfile", "taskfile.yml", "taskfile.yaml", "rakefile", "docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml", "package.json", "mise.toml", "pixi.toml"] },
+  { n: 2, key: "lockfile", files: ["package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb", "poetry.lock", "pipfile.lock", "uv.lock", "requirements.txt", "go.sum", "cargo.lock", "gemfile.lock", "composer.lock", "gradle.lockfile", "packages.lock.json", "pubspec.lock", "mix.lock"] },
+  { n: 3, key: "sameEnv", files: ["dockerfile", "containerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml", ".devcontainer", "devcontainer.json", "flake.nix", "shell.nix", ".tool-versions", ".nvmrc", ".python-version", ".ruby-version", ".sdkmanrc", "mise.toml", "asdf.toml"] },
+  { n: 6, key: "formatter", files: [".editorconfig", ".prettierrc*", "prettier.config*", "rustfmt.toml", ".rustfmt.toml", ".clang-format", ".scalafmt.conf", ".rubocop.yml", "biome.json", "biome.jsonc", ".dprint.json", "dprint.json"] },
+  { n: 7, key: "linter", files: [".eslintrc*", "eslint.config*", "ruff.toml", ".ruff.toml", ".flake8", ".pylintrc", ".golangci.yml", ".golangci.yaml", "clippy.toml", ".rubocop.yml", "phpstan.neon", "psalm.xml", "detekt.yml", ".swiftlint.yml", "biome.json", ".credo.exs", "checkstyle.xml"] },
+  { n: 8, key: "types", files: ["tsconfig.json", "jsconfig.json", "mypy.ini", ".mypy.ini", "pyrightconfig.json", "sorbet", "go.mod", "cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts", "stack.yaml", "dune-project"] },
+  { n: 9, key: "secretScan", files: [".gitleaks.toml", "gitleaks.toml", ".secrets.baseline", ".trufflehogignore", ".talismanrc", ".gitguardian.yml", ".gitguardian.yaml"], gate: "secrets-not-in-code" },
+  { n: 10, key: "fileSize", gate: "file-size-limit" },
+  { n: 11, key: "ownInvariants", gate: "no-print-in-prod" },
+  { n: 13, key: "tests", fact: "has_tests" },
+  { n: 19, key: "pipeline", fact: "has_ci" },
+  { n: 30, key: "errorTracker", deps: ["sentry", "rollbar", "bugsnag", "honeybadger", "airbrake", "appsignal", "datadog", "newrelic", "new-relic", "elastic-apm", "opentelemetry", "glitchtip"] },
+  { n: 39, key: "machineReadable", manifestField: "entry" },
+  { n: 42, key: "rulesInRepo", manifestField: "rules" },
+];
+
+// Файлы, в которых объявляют зависимости. Один список на все экосистемы: пункт про трекер
+// ошибок нейтрален, а знать про один только npm — значит объявить половину мира несоответствующей.
+const DEP_FILES = [
+  "package.json", "requirements.txt", "pyproject.toml", "pipfile", "poetry.lock", "uv.lock",
+  "go.mod", "cargo.toml", "gemfile", "composer.json", "build.gradle", "build.gradle.kts",
+  "pom.xml", "mix.exs", "pubspec.yaml", "project.clj", "deps.edn",
+];
+
+// Чем подтверждён пункт, возвращается СТРУКТУРОЙ, а не готовой фразой: текст переводится,
+// а факт — нет. Собранная здесь строка утекла бы в английский вывод по-русски; так и вышло.
+/**
+ * Вход — только факты, никакого ввода-вывода: функция чистая и проверяется модульно.
+ *   files      — имена файлов и каталогов в корне репозитория
+ *   gateKeys   — гейты, объявленные в манифесте
+ *   facts      — то, что уже насчитал осмотр репозитория (has_ci, has_tests)
+ *   manifest   — разобранный .aqk.yml
+ *   depsText   — склеенное содержимое файлов зависимостей, в нижнем регистре
+ */
+function assessBaseline({ files = [], gateKeys = [], facts = {}, manifest = {}, depsText = "" }) {
+  return ITEMS.map((it) => {
+    if (it.gate && gateKeys.includes(it.gate)) return { n: it.n, key: it.key, ok: true, by: { kind: "gate", value: it.gate } };
+    if (it.fact) return { n: it.n, key: it.key, ok: Boolean(facts[it.fact]), by: { kind: "fact", value: it.fact } };
+    if (it.manifestField) {
+      const v = manifest?.[it.manifestField];
+      const filled = Array.isArray(v) ? v.length > 0 : Boolean(String(v || "").trim());
+      return { n: it.n, key: it.key, ok: filled, by: { kind: "manifest", value: it.manifestField } };
+    }
+    if (it.deps) {
+      const found = it.deps.find((d) => depsText.includes(d));
+      return { n: it.n, key: it.key, ok: Boolean(found), by: found ? { kind: "dep", value: found } : null };
+    }
+    const f = hit(files, it.files || []);
+    return { n: it.n, key: it.key, ok: Boolean(f), by: f ? { kind: "file", value: f } : null };
+  });
+}
+
+// Всего пунктов в методичке. Число не выводится из кода: методичка — текст, и её длину знает
+// только она сама. Сверяется проверкой, чтобы не разошлось молча.
+const BASELINE_TOTAL = 50;
+
+// Наружу — только то, что зовут. Экспорт, который никто не импортирует, читается как «это
+// часть договора» и мешает менять внутренности; `hit` остался внутри. Поймал наш же dead-code.
+export { assessBaseline, ITEMS, DEP_FILES, BASELINE_TOTAL };

package/tool/lib/core.mjs

@@ -7,7 +7,7 @@
 import { access, readdir, mkdir, copyFile, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join, resolve, relative } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -71,6 +71,14 @@ const RATCHET_LIB = `${RATCHET_DIR}/_ratchet.sh`;
 // то и другое врёт о том, видел человек просьбу или нет.
 const FEEDBACK_MARK = join(homedir(), ".config", "aqk", "feedback-shown");
 
+// Путь, попадающий в ДОКУМЕНТ, всегда пишется через «/». `relative()` отдаёт разделитель
+// платформы, и на Windows склейка методичек и отчёт получались с «kit\\docs» вместо «kit/docs»:
+// артефакт, который человек читает и пересылает, оказывался разным на разных системах. Найдено
+// заданием конвейера на windows-latest — шестьдесят шесть проверок на Linux этого не видели.
+function docPath(from, to) {
+  return relative(from, to).split(sep).join("/");
+}
+
 async function copyDir(src, dst, { force }) {
   await mkdir(dst, { recursive: true });
   const entries = await readdir(src, { withFileTypes: true });
@@ -98,7 +106,7 @@ async function writeIfAbsent(path, content, { force }) {
 
 export {
   copyDir, writeIfAbsent,
-  PKG_ROOT, CWD, DOCS_SRC, RULES_SRC, TARGET_DIR,
+  PKG_ROOT, CWD, DOCS_SRC, RULES_SRC, TARGET_DIR, docPath,
   MANIFEST, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB,
   SELF, REPO_URL, c, exists, die, FEEDBACK_MARK,
 };

package/tool/lib/manifest.mjs

@@ -12,11 +12,24 @@ import { L } from "../i18n/index.mjs";
 // Разбор ограниченного подмножества YAML: ключ, вложенный на один уровень ключ, список.
 // НАМЕРЕННО без библиотеки: манифест обязан быть настолько простым, чтобы его разбирал
 // кусок кода, который читается за минуту. Сложный манифест никто не заполнит.
+// Срезает комментарий по правилу YAML: решётка начинает комментарий только с начала строки
+// или после пробела. Безусловное `replace(/#.*$/)` молча обрезало команду
+// `npx jscpd --format "java,c#,php"` на «c» — гейт запускал не то, что объявлено, и об этом
+// никто не узнавал. Объявленное и исполняемое обязаны совпадать: на этом стоит весь стандарт.
+//
+// Пары кавычек не отслеживаем намеренно: в рецептах кавычки соседние, а не вложенные
+// (`"bash x.sh --format "a,b" ."`), и подсчёт пар решил бы, что «c#» стоит снаружи.
+function stripComment(raw) {
+  const i = raw.search(/(^|\s)#/);
+  if (i < 0) return raw;
+  return raw[i] === "#" ? raw.slice(0, i) : raw.slice(0, i + 1);
+}
+
 function parseManifest(text) {
   const out = {};
   let section = null;
   for (const raw of text.split("\n")) {
-    const line = raw.replace(/#.*$/, "").replace(/\s+$/, "");
+    const line = stripComment(raw).replace(/\s+$/, "");
     if (!line.trim()) continue;
     const indented = /^\s/.test(line);
     const listItem = line.trim().startsWith("- ");
@@ -55,6 +68,57 @@ function parseManifest(text) {
   return out;
 }
 
+// Поля, которые манифест знает. Список здесь, а не в схеме-файле: зависимостей у программы
+// нет, а схема на восемь ключей, которую надо валидировать библиотекой, стоит дороже, чем
+// защищает.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ. Разбор принимает любое имя поля. Опечатка `gate:` вместо `gates:` молча
+// означала «гейтов не объявлено»: вердикт выдавался неверный, а причина не называлась. Это
+// ровно тот класс, против которого построен стандарт — тишина неотличима от успеха, — только
+// внутри самой программы.
+// Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
+// лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
+// только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
+const KNOWN_KEYS = ["aqk", "entry", "rules", "gates", "samples", "ratchets", "lessons"];
+
+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 };
+}
+
 async function readManifest() {
   const p = join(CWD, MANIFEST);
   if (!(await exists(p))) return null;
@@ -118,4 +182,7 @@ function manifestWithGate(text, slug, cmd) {
   return { text: out, why: null };
 }
 
-export { parseManifest, readManifest, assessLevel, manifestWithGate };
+export {
+  parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
+  entryLifecycle,
+};

package/tool/lib/repo.mjs

@@ -49,6 +49,11 @@ async function detectFacts(man) {
   let files = 0;
   let hasDb = false;
   let hasTests = false;
+  // Признак интерфейса: стили или однофайловые компоненты. Нужен записям про внешний вид —
+  // без него запрет литерального цвета показывался бы каждому бэкенду, библиотеке и CLI на
+  // JS, где интерфейса нет вовсе. Записи, показанной не тому, не верят, и каталог теряет
+  // доверие целиком, а не одной строкой.
+  let hasUi = false;
 
   async function walk(dir, depth) {
     if (depth > 4 || files > 4000) return;
@@ -72,6 +77,7 @@ async function detectFacts(man) {
         files++;
         if (/\.(test|spec)\.[a-z]+$/i.test(it.name) || /^test_.*\.py$/i.test(it.name) || /_test\.go$/i.test(it.name)) hasTests = true;
         if (it.name.endsWith(".sql")) hasDb = true;
+        if (/\.(css|scss|sass|less|styl|vue|svelte|astro)$/i.test(it.name)) hasUi = true;
         const dot = it.name.lastIndexOf(".");
         if (dot > 0) {
           const lang = EXT_LANG[it.name.slice(dot)];
@@ -88,6 +94,7 @@ async function detectFacts(man) {
     files,
     has_db: hasDb,
     has_tests: hasTests,
+    has_ui: hasUi,
     has_gates: Object.values(gates).some((c) => String(c || "").trim()),
     gateKeys: Object.keys(gates),
   };

package/tool/lib/scope.mjs

@@ -0,0 +1,96 @@
+// 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 };
+}
+
+// Файлы, изменённые относительно ссылки. Новые файлы, ещё не добавленные в индекс, тоже входят:
+// их код так же нов, как и остальной диф, а из `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, changedFiles };

package/tool/program.mjs

@@ -82,6 +82,7 @@ if (IS_MAIN) {
         [`${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],

package/tool/selfcheck/gates.sh

@@ -22,6 +22,14 @@ 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}'; }
+
 for GATE in "$CAT"/*/; do
   SLUG="$(basename "$GATE")"
   YML="$GATE/gate.yml"
@@ -59,14 +67,30 @@ for GATE in "$CAT"/*/; do
   # Два раздела README обязательны нормой каталога. Пока их не проверяла машина, четыре записи
   # из четырнадцати жили без раздела про готовый аналог и четыре — без «чего НЕ ловит».
   # Правило нормы, за которым не следит машина, — это пожелание.
-  grep -qiE 'готовы(й аналог|й инструмент|е правил)|готового аналога' "$GATE/README.md" 2>/dev/null \
+  # Без `-i` и через `tr -d '\r'`. На Windows этот шаг отклонял ВЕСЬ каталог — 32 из 47 —
+  # то есть первый же прогон комплекта у человека на Windows выглядел как «здесь всё сломано».
+  # Две причины сняты разом, потому что порознь ни одна локально не воспроизводится: markdown
+  # приезжает туда с CRLF (`.gitattributes` держит LF только для `*.sh`), а `grep -i` с
+  # кириллицей в сборке MSYS ведёт себя не так, как GNU grep. Регистр первой буквы назван
+  # явно — это дешевле, чем полагаться на сворачивание регистра в чужой сборке grep.
+  README_TEXT="$(tr -d '\r' < "$GATE/README.md" 2>/dev/null)"
+  printf '%s\n' "$README_TEXT" | grep -qE '[Гг]отовы(й аналог|й инструмент|е правил)|[Гг]отового аналога' \
     || bad "$SLUG: в README нет раздела про готовый аналог — «не искал» и «нет» разные утверждения"
-  grep -qiE 'чего НЕ ловит' "$GATE/README.md" 2>/dev/null \
+  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
 
   # --- образцы ---------------------------------------------------------------

package/tool/selfcheck/lifecycle.mjs

@@ -0,0 +1,29 @@
+// tool/selfcheck/lifecycle.mjs — зрелость записей каталога, одной таблицей.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫМ ФАЙЛОМ, А НЕ КУСКОМ gates.sh. Правило зрелости живёт в `entryLifecycle`
+// (tool/lib/manifest.mjs) и оттуда же читается программой. Повторить его на sh значило бы
+// завести второй источник истины: через месяц приёмка и отчёт расходятся, и про одну и ту же
+// запись машина говорит разное. Здесь — только печать; решение принимает та же функция.
+//
+//   node tool/selfcheck/lifecycle.mjs        → slug|состояние|замена|проблема
+//
+// Код возврата — число записей с проблемой объявления.
+
+import { readCatalog } from "../lib/repo.mjs";
+import { entryLifecycle } from "../lib/manifest.mjs";
+import { L } from "../i18n/index.mjs";
+
+const catalog = await readCatalog();
+const slugs = new Set(catalog.map((r) => r.slug));
+let bad = 0;
+
+for (const rec of catalog) {
+  const { state, supersededBy, problem } = entryLifecycle(rec);
+  // Замена, которой нет в каталоге, — это ответ «а что теперь», ведущий в никуда. Проверяется
+  // здесь, а не в чистой функции: та не знает про остальные записи и не должна знать.
+  const why = problem || (supersededBy && !slugs.has(supersededBy) ? L.lifecycle.unknownReplacement(supersededBy) : "");
+  if (why) bad++;
+  console.log(`${rec.slug}|${state}|${supersededBy || ""}|${why}`);
+}
+
+process.exit(bad);

package/tool/selfcheck/mutation.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# tool/selfcheck/mutation.sh — доказывает, что гейт краснеет на КЛАССЕ примеров, а не на одном.
+#
+# ЗАЧЕМ. Пара образцов red/green доказывает ровно одно срабатывание. Одна проверка `.aqkignore`
+# была написана так, что не могла покраснеть, и это заметили случайно; сколько таких ещё —
+# неизвестно (PROJECT.md §9 п.4). Гейт, который не может упасть, неотличим от работающего.
+#
+# КАК. Образец меняется так, что вердикт МЕНЯТЬСЯ НЕ ОБЯЗАН: сдвиг строк, перевод строк в
+# windows-формат. Если после такой правки красный позеленел или зелёный покраснел — гейт
+# опирался не на то, что заявляет. Идея взята из мутационного тестирования правил в
+# millionco/react-doctor (packages/fuzz), приёмы — свои, зависимостей не добавлено.
+#
+# ПОЧЕМУ ИМЕННО ЭТИ ДВЕ. Обе сохраняют смысл по построению и обе бьют по настоящим болям:
+# сдвиг строк ловит проверки, привязанные к номеру строки; CRLF ловит те, что сломаются на
+# windows-чекауте, — а конвейера на Windows у нас до сих пор нет (PROJECT.md §9 п.2).
+#
+#   bash tool/selfcheck/mutation.sh
+
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CAT="$ROOT/kit/gates"
+PASS=0; FAIL=0; SKIP=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)); }
+
+printf '\n\033[1mtool/selfcheck/mutation.sh\033[0m\n\n'
+[ -d "$CAT" ] || { echo "  каталога гейтов нет"; exit 1; }
+
+# Сдвиг строк: три пустые строки в начало каждого файла. Номера всех строк меняются, смысл —
+# нет. Проверка, которая помнит номер, а не содержание, здесь и ломается.
+mutate_blank_lines() {
+  find "$1" -type f 2>/dev/null | while IFS= read -r F; do
+    { printf '\n\n\n'; cat "$F"; } > "$F.mut" && mv "$F.mut" "$F"
+  done
+}
+
+# Перевод строк в windows-формат. Смысл файла тот же, но у проверки, которая ищет по «конец
+# строки», перед ним оказывается \r — и она перестаёт видеть то, что видела.
+mutate_crlf() {
+  find "$1" -type f 2>/dev/null | while IFS= read -r F; do
+    sed 's/$/\r/' "$F" > "$F.mut" && mv "$F.mut" "$F"
+  done
+}
+
+for GATE in "$CAT"/*/; do
+  SLUG="$(basename "$GATE")"
+  YML="$GATE/gate.yml"
+  [ -f "$YML" ] || continue
+  [ -d "$GATE/red" ] && [ -d "$GATE/green" ] || continue
+
+  # Только переносимый рецепт. Родные инструменты требуют установленной программы, и на
+  # машине без неё «не проверено» было бы неотличимо от «проверено»: ровно та тишина, против
+  # которой всё это написано. Записи без `any` называются вслух, а не пропускаются молча.
+  RECIPE="$(sed -n 's/^[[:space:]]*any:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1)"
+  if [ -z "$RECIPE" ]; then
+    skip "$SLUG: нет переносимого рецепта — мутации проверять нечем"
+    continue
+  fi
+
+  GATE_FAILED=0
+  for MUT in blank_lines crlf; do
+    for KIND in red green; do
+      TMP="$(mktemp -d)"
+      cp -r "$GATE/$KIND" "$TMP/$KIND"
+      "mutate_$MUT" "$TMP/$KIND"
+
+      # {gate} остаётся настоящим каталогом гейта: мутируется ОБРАЗЕЦ, а не сама проверка.
+      CMD="$(echo "$RECIPE" | sed "s|{gate}|$GATE|; s|{dir}|$TMP/$KIND|")"
+      OUT="$(eval "$CMD" 2>&1)"; CODE=$?
+      rm -rf "$TMP"
+
+      if [ "$KIND" = red ] && [ "$CODE" -eq 0 ]; then
+        bad "$SLUG / $MUT: красный образец позеленел — гейт держался за то, чего не заявляет"
+        GATE_FAILED=1
+      elif [ "$KIND" = green ] && [ "$CODE" -ne 0 ]; then
+        bad "$SLUG / $MUT: зелёный образец покраснел — гейт ругается на исправный код"
+        printf '     \033[2m%s\033[0m\n' "$(printf '%s' "$OUT" | head -1 | cut -c1-100)"
+        GATE_FAILED=1
+      fi
+    done
+  done
+  [ "$GATE_FAILED" -eq 0 ] && ok "$SLUG: вердикт пережил сдвиг строк и windows-переносы"
+done
+
+printf '\n'
+if [ "$FAIL" -eq 0 ]; then
+  printf '  \033[32mвердикт устойчив: %s гейтов\033[0m' "$PASS"
+else
+  printf '  \033[31mвердикт поплыл: %s\033[0m' "$FAIL"
+fi
+[ "$SKIP" -gt 0 ] && printf '  \033[2m(без переносимого рецепта: %s)\033[0m' "$SKIP"
+printf '\n\n'
+exit "$FAIL"