agent-quality-kit 0.9.0 → 0.10.1

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/repo.mjs

@@ -26,6 +26,14 @@ const EXT_LANG = {
   ".cs": "csharp", ".sh": "shell", ".kt": "kotlin", ".swift": "swift", ".scala": "scala",
 };
 
+// Спецификация API — договор с чужим кодом. Опознаётся ПО ИМЕНИ ФАЙЛА, а не по расположению:
+// его кладут в корень, в `docs/`, рядом с приложением, — фиксированный список путей промахнулся
+// бы на большинстве проектов. Расширение обязательно разбираемое: `openapi.md` — это рассказ о
+// договоре, а не договор, и держать его нечем.
+function isApiSpec(name) {
+  return /^(openapi|swagger|asyncapi)[^/]*\.(ya?ml|json)$/i.test(name);
+}
+
 const SKIP_DIRS = new Set([".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__", ".aqk"]);
 
 // Факты о репозитории. Только то, что видно машине: спрашивать человека анкетой
@@ -67,6 +75,7 @@ async function detectFacts(man) {
   // JS, где интерфейса нет вовсе. Записи, показанной не тому, не верят, и каталог теряет
   // доверие целиком, а не одной строкой.
   let hasUi = false;
+  let hasApiSpec = false;
 
   async function walk(dir, depth) {
     if (depth > 4 || files > 4000) return;
@@ -91,6 +100,7 @@ async function detectFacts(man) {
         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;
+        if (isApiSpec(it.name)) hasApiSpec = true;
         const dot = it.name.lastIndexOf(".");
         if (dot > 0) {
           const lang = EXT_LANG[it.name.slice(dot)];
@@ -108,6 +118,7 @@ async function detectFacts(man) {
     has_db: hasDb,
     has_tests: hasTests,
     has_ui: hasUi,
+    has_api_spec: hasApiSpec,
     has_gates: Object.values(gates).some((c) => String(c || "").trim()),
     gateKeys: Object.keys(gates),
   };
@@ -356,5 +367,4 @@ async function matchCatalog(query) {
 export {
   whichSync,
   EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor, browserServerAdvice, MARKS,
-  stems, overlap, matchCatalog,
-};
+  stems, overlap, matchCatalog, isApiSpec };

package/tool/program.mjs

@@ -26,6 +26,7 @@ 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 { cmdProbe } from "./commands/probe.mjs";
 import { cmdContext } from "./commands/context.mjs";
 import { cmdVitals } from "./commands/vitals.mjs";
 
@@ -83,6 +84,12 @@ if (IS_MAIN) {
     case "prove":
       await cmdProve();
       break;
+    // Осмотр, а не порог: всегда выходит с нулём. Отвечает на вопрос, которого нет ни у
+    // doctor («держит машина 21» — из чего?), ни у prove («гейт ловит брак на СВОЁМ образце»):
+    // что в ЭТОМ репозитории не прикрыто ничем.
+    case "probe":
+      await cmdProbe(rest);
+      break;
     // Печатает состояние репозитория для КОНТЕКСТА агента, а не для человека. Зовётся хуком
     // SessionStart, поэтому ничего не запускает и всегда выходит с нулём: хук, роняющий запуск
     // агента из-за неготового проекта, отключат в тот же день, и не станет ни хука, ни блока.

package/tool/selfcheck/smoke/_fixture.mjs

@@ -0,0 +1,89 @@
+// tool/selfcheck/smoke/_fixture.mjs — общая оснастка проверок, гоняющих сам инструмент.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫЙ ФАЙЛ. В `smoke.sh` фикстура «временный проект под git» написана сорок раз
+// подряд одними и теми же четырьмя строками. Это не похожие строки, а ОДНО знание в сорока
+// местах: меняется устройство подопытного проекта — правится сорок мест, и они расходятся.
+//
+// ЧТО ЗДЕСЬ ЗАКРЫТО, кроме дублирования (всё — из разборов флейков и из нашего же опыта):
+//   · СВОЙ каталог на проверку и уборка после неё — через `t.after`, а не «не забыть rm»;
+//   · ТАЙМАУТ на каждый запуск: висящий подпроцесс иначе держит конвейер до его предела;
+//   · ГЕРМЕТИЧНОСТЬ: HOME и TMPDIR в песочнице, сеть выключена. Прогон обязан давать один
+//     ответ на любой машине и в любой день — иначе зелёное значит «сегодня совпало».
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const CLI = join(ROOT, "tool", "program.mjs");
+
+// Предел на один запуск. Тридцать секунд — с запасом: самый долгий наш прогон в фикстуре
+// (`start` со всеми записями) укладывается в единицы секунд. Предел нужен не ради скорости,
+// а ради того, чтобы висящий процесс называл себя, а не съедал бюджет задания молча.
+const TIMEOUT_MS = 30000;
+
+function env(home) {
+  return {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home,
+    TMPDIR: join(home, "tmp"),
+    AQK_LANG: "ru",
+    // Сеть в тестах — отдельный класс флейков, и у нас она включалась ТОЛЬКО вне конвейера:
+    // локально проверки были сетевыми, в конвейере нет. Две разные среды по построению.
+    AQK_UPDATE: "0",
+  };
+}
+
+// Подопытный проект: свой каталог, свой git, свой дом. Файлы задаются картой «путь → текст»,
+// потому что имя файла в такой проверке — часть утверждения, а не деталь.
+function project(t, files = {}, { git = true } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "aqk-smoke-"));
+  const home = join(dir, ".home");
+  mkdirSync(join(home, "tmp"), { recursive: true });
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  for (const [rel, text] of Object.entries(files)) {
+    const full = join(dir, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text, "utf8");
+  }
+  const p = { dir, home };
+  if (git) {
+    run(p, "git", ["init", "-q", "."]);
+    run(p, "git", ["config", "user.email", "t@t"]);
+    run(p, "git", ["config", "user.name", "t"]);
+  }
+  return p;
+}
+
+// Запуск чего угодно в каталоге проекта. Возвращается И код, И вывод: проверка, смотрящая
+// только на код, не умеет объяснить провал, а смотрящая только на вывод — не умеет заметить,
+// что команда не роняет прогон.
+function run({ dir, home }, cmd, args = []) {
+  const r = spawnSync(cmd, args, {
+    cwd: dir, encoding: "utf8", timeout: TIMEOUT_MS, env: env(home),
+  });
+  return { code: r.status, out: `${r.stdout || ""}${r.stderr || ""}` };
+}
+
+const aqk = (p, ...args) => run(p, process.execPath, [CLI, ...args]);
+
+// ПОЧЕМУ ГЕЙТ ЗОВЁТСЯ ТОЧКОЙ, А НЕ ПУТЁМ, И ПОЧЕМУ ПУТЬ ЧЕРЕЗ КОСУЮ.
+// Node на Windows отдаёт `C:\Users\…\Temp\aqk-smoke-x`, а Git Bash живёт в POSIX-мире и
+// такого пути не знает: проверка искала спецификации в несуществующем каталоге, не находила
+// ничего и выходила с нулём — то есть краснела не на дефекте, а на переносимости. Поймано
+// конвейером на windows-задании в тот же день, когда файл был написан.
+// Лечится двумя приёмами сразу: каталог отдаётся как «.» вместе с cwd (переводить нечего),
+// а путь до самого скрипта — с прямыми косыми, их Git Bash понимает.
+const posix = (p) => String(p).replace(/\\/g, "/");
+// Подкаталог нужен там, где проверяется не сам проект, а его клон: мелкий клон предложения
+// изменений ведёт себя иначе, чем полная история, и это отдельный класс отказов.
+const gate = (p, name, sub = ".") =>
+  run(p, "bash", [posix(join(ROOT, "kit", "gates", name, "check.sh")), sub]);
+
+// Наружу — только то, что зовут проверки. `ROOT` и `CLI` остаются внутри: экспорт, который
+// никто не берёт, читается как часть договора и мешает менять внутренности — поймал наш же
+// dead-code через минуту после того, как файл был написан. `run` вернулся, когда появилась
+// проверка, которой нужен сырой git: экспорт заводится под потребителя, а не про запас.
+export { project, run, aqk, gate };

package/tool/selfcheck/smoke/api-contract.test.mjs

@@ -0,0 +1,79 @@
+// Проверки про договор с чужим кодом: кто держит спецификацию API и умеет ли держатель
+// провалиться. Переехали из smoke.sh 2026-09-09 первыми — как доказательство переезда.
+//
+// ЗАМЕР, ИЗ КОТОРОГО ОНИ ВЗЯЛИСЬ. Стенд, где сервер врёт в каждом поле ответа:
+//   spectral (spectral:oas)             код 0  — нет контакта, описания, тегов
+//   schemathesis, умолчания             код 1  — три нарушения схемы в ответах
+//   schemathesis -c not_a_server_error  код 0  — «18 из 18 прошли»
+//   oasdiff breaking без --fail-on      код 0  — печатает ломающую правку и молчит кодом
+import test from "node:test";
+import assert from "node:assert/strict";
+import { project, aqk, gate } from "./_fixture.mjs";
+
+const SPEC = "openapi: 3.0.3\ninfo: { title: t, version: 1.0.0 }\npaths: {}\n";
+const workflow = (steps) =>
+  `name: ci\non: [push]\njobs:\n  contract:\n    runs-on: ubuntu-latest\n    steps:\n${steps}`;
+
+// ЛОВУШКА, ИЗ-ЗА КОТОРОЙ ЗАМЕР ЧУТЬ НЕ ОКАЗАЛСЯ ЛОЖНО-ЗЕЛЁНЫМ: шаг с именем «Spec lint»
+// краснеет не потому, что узнали инструмент, а потому что в имени есть слово-примета.
+// Поэтому здесь у шагов НЕТ слов-подсказок — проверяется опознание инструмента.
+test("обезвреженные проверки контракта API опознаются как проверки", (t) => {
+  const p = project(t, {
+    ".github/workflows/api.yml": workflow(
+      "      - name: соответствие сервера схеме\n" +
+      "        continue-on-error: true\n" +
+      "        run: schemathesis run openapi.yaml --url http://localhost:8000\n" +
+      "      - name: ломающие изменения\n" +
+      "        continue-on-error: true\n" +
+      "        run: oasdiff breaking base.yaml openapi.yaml --fail-on ERR\n" +
+      "      - name: ожидания потребителей\n" +
+      "        continue-on-error: true\n" +
+      "        run: pact-broker can-i-deploy --pacticipant web\n"),
+  });
+  const r = gate(p, "ci-actually-fails");
+  assert.equal(r.code, 1, `три шага под continue-on-error прошли как чистые:\n${r.out}`);
+});
+
+// У записи две красные ветки, и вторая тоньше первой. Проверяются ОБЕ формы сужения и
+// мутация: снял сужение — гейт обязан замолчать, иначе краснеет он не от этого.
+test("арбитр, который не может провалиться, краснеет в обеих формах", (t) => {
+  const mk = (tail) => ({
+    "openapi.yaml": SPEC,
+    ".github/workflows/ci.yml": workflow(
+      `      - run: schemathesis run openapi.yaml --url http://localhost:8000${tail}\n`),
+  });
+  for (const narrow of [" -c not_a_server_error", " --checks not_a_server_error"]) {
+    const p = project(t, mk(narrow));
+    assert.equal(gate(p, "api-contract-has-arbiter").code, 1, `сужение «${narrow}» не опознано`);
+  }
+  const full = project(t, mk(""));
+  assert.equal(gate(full, "api-contract-has-arbiter").code, 0, "полный арбитр покраснел");
+
+  const loud = project(t, {
+    "openapi.yaml": SPEC,
+    ".github/workflows/ci.yml": workflow(
+      "      - run: schemathesis run openapi.yaml --url http://localhost:8000\n" +
+      "      - run: oasdiff breaking base.yaml openapi.yaml\n"),
+  });
+  assert.equal(gate(loud, "api-contract-has-arbiter").code, 1,
+    "oasdiff без --fail-on печатает находки и выходит с нулём — это не проверка");
+});
+
+// НАЙДЕНО АУДИТОМ ФИЧ, а не образцами: красный и зелёный образцы лежат по одному, а в
+// настоящем проекте записи стоят рядом — и соседняя `ci-actually-fails` держит в своём
+// check.sh список запускалок со ВСЕМИ инструментами про API разом. Проверка находила её и
+// выдавала ложное ЗЕЛЁНОЕ там, где договор не держал никто.
+test("держателем не считается определение соседней записи", (t) => {
+  const p = project(t, {
+    "src/a.py": "def s():\n    return 1\n",
+    "openapi.yaml": SPEC,
+    ".github/workflows/ci.yml": workflow("      - run: pytest\n"),
+  });
+  aqk(p, "init");
+  aqk(p, "add", "ci-actually-fails");
+  aqk(p, "add", "api-contract-has-arbiter");
+  const r = gate(p, "api-contract-has-arbiter");
+  assert.equal(r.code, 1, `договор без держателя прошёл зелёным:\n${r.out}`);
+  // Второй дефект того же прогона: `find` без завершающего -print печатал обойдённые каталоги.
+  assert.doesNotMatch(r.out, /\.git|\.aqk/, `в списке спецификаций каталоги:\n${r.out}`);
+});

package/tool/selfcheck/smoke/commit-report.test.mjs

@@ -0,0 +1,47 @@
+// Мини-отчёт в коммите: где его требовать, а где состав коммита определить нельзя.
+//
+// НАЙДЕНО КОНВЕЙЕРОМ 2026-09-09. Коммит, трогающий ТОЛЬКО журнал, отчёта не требует — сама
+// запись и есть отчёт. Локально так и было. В конвейере тот же коммит покраснел, и причина
+// тоньше, чем кажется:
+//   · при разборе предложения изменений GitHub выкладывает синтетический коммит слияния,
+//     и гейт правильно спрашивает второго родителя — коммит автора;
+//   · но выкладка идёт МЕЛКИМ клоном, и родителя второго родителя в нём нет;
+//   · `git show --name-only` на коммите без родителя считает его корневым и выдаёт ВСЁ дерево;
+//   · значит «трогает только журнал» перестаёт срабатывать — молча, — и гейт требует отчёт там,
+//     где не должен.
+// Проверено опытом: глубина 2 — красный, глубина 3 — чисто.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { project, run, gate } from "./_fixture.mjs";
+
+function repoWithJournalMerge(t) {
+  const p = project(t, {
+    "incidents/README.md": "# журнал\n",
+    "src/a.py": "код\n",
+    ".aqk.yml": "lessons: incidents\n",
+  });
+  run(p, "git", ["add", "-A"]);
+  run(p, "git", ["commit", "-q", "-m", "feat: первый", "-m", "Сделано: завёл", "-m", "Не уверен: ни в чём"]);
+  run(p, "git", ["checkout", "-q", "-b", "feature"]);
+  run(p, "bash", ["-c", "printf '## запись\\n' >> incidents/README.md"]);
+  run(p, "git", ["add", "-A"]);
+  // Тело НАРОЧНО без «Сделано:»: если освобождение для журнала перестанет работать, гейт
+  // покраснеет — то есть проверка умеет отличить исправное от сломанного.
+  run(p, "git", ["commit", "-q", "-m", "docs: урок", "-m", "Не уверен: ничего не сломано"]);
+  const main = run(p, "bash", ["-c", "git checkout -q master 2>/dev/null || git checkout -q main; git rev-parse --short HEAD"]);
+  run(p, "git", ["merge", "-q", "--no-ff", "feature", "-m", `Merge feature into ${main.out.trim()}`]);
+  return p;
+}
+
+test("коммит только в журнал не требует отчёта и в мелком клоне слияния", (t) => {
+  const p = repoWithJournalMerge(t);
+  assert.equal(gate(p, "commit-explains-itself").code, 0, "полная история: журнальный коммит покраснел");
+
+  // Ровно то, что делает конвейер при разборе предложения изменений.
+  run(p, "bash", ["-c", "git clone -q --depth 2 file://$PWD shallow2 2>/dev/null"]);
+  const r = gate(p, "commit-explains-itself", "shallow2");
+  assert.equal(r.code, 0, `мелкий клон: гейт требует отчёт там, где состав определить нельзя:\n${r.out}`);
+  // Молчать в этом случае нельзя: пропуск обязан называть себя, иначе выключенная проверка
+  // неотличима от работающей — тот самый класс, ради которого весь комплект.
+  assert.match(r.out, /не определить|журнал/, `пропуск не назвал причину:\n${r.out}`);
+});

package/tool/selfcheck/smoke/protection.test.mjs

@@ -0,0 +1,101 @@
+// Снимок объявленной защиты: проверка ТОЛЬКО СРАВНИВАЕТ, а пишет его отдельная явная операция.
+// Написаны ДО правки.
+//
+// ОПЫТ, ИЗ КОТОРОГО ОНИ ВЗЯЛИСЬ (2026-09-09). Проверка при отсутствии реестра создавала его
+// сама и выходила с нулём. В мелком клоне, где удаление реестра лежит ГЛУБЖЕ выкладки, свидетель
+// (история git) слеп — и проверка записала УЖЕ ОСЛАБЛЕННЫЙ набор как новый эталон:
+//
+//   снят снимок объявленной защиты: 2 гейтов → ratchets/gates-declared.txt
+//   код: 0                                   ← гейт «secrets» исчез и УЗАКОНЕН
+//
+// Храповик крутился назад. Отсюда правило: отсутствующий снимок — не зелёное, и проверка,
+// выносящая вердикт, не имеет права менять то, о чём судит.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { project, run, aqk, gate } from "./_fixture.mjs";
+
+const MAN = (gates) =>
+  `aqk: 1\nentry: [AGENTS.md]\nratchets: ratchets\ngates:\n${gates.map((g) => `  ${g}: "true"\n`).join("")}`;
+const REG = "# Снимок объявленной защиты. Набор может только РАСТИ.\n";
+
+test("отсутствующий снимок — не зелёное, и проверка его не создаёт", (t) => {
+  const p = project(t, { ".aqk.yml": MAN(["lint", "secrets"]), "AGENTS.md": "# свод\n" });
+  const r = gate(p, "protection-not-removed");
+  assert.notEqual(r.code, 0, `снимка нет, а проверка зелёная:\n${r.out}`);
+  assert.equal(existsSync(join(p.dir, "ratchets", "gates-declared.txt")), false,
+    "проверка создала файл, о котором судит");
+});
+
+test("мелкий клон не узаконивает ослабленный набор", (t) => {
+  const p = project(t, {
+    ".aqk.yml": MAN(["lint", "secrets", "tests"]),
+    "AGENTS.md": "# свод\n",
+    "ratchets/gates-declared.txt": `${REG}lint\nsecrets\ntests\n`,
+  });
+  run(p, "git", ["add", "-A"]);
+  run(p, "git", ["commit", "-q", "-m", "первый", "-m", "Сделано: x", "-m", "Не уверен: y"]);
+  // Обход: убрали гейт И удалили снимок.
+  run(p, "bash", ["-c", `printf '%s' '${MAN(["lint", "tests"])}' > .aqk.yml && git rm -q ratchets/gates-declared.txt`]);
+  run(p, "git", ["commit", "-qam", "обход", "-m", "Сделано: x", "-m", "Не уверен: y"]);
+  // ...и ушли вперёд, чтобы удаление оказалось глубже выкладки конвейера.
+  for (let i = 0; i < 5; i++) {
+    run(p, "bash", ["-c", `echo ${i} > f${i}.txt`]);
+    run(p, "git", ["add", "-A"]);
+    run(p, "git", ["commit", "-qm", `работа ${i}`, "-m", "Сделано: x", "-m", "Не уверен: y"]);
+  }
+  run(p, "bash", ["-c", "git clone -q --depth 3 file://$PWD shallow 2>/dev/null"]);
+  const r = gate(p, "protection-not-removed", "shallow");
+  assert.notEqual(r.code, 0, `мелкий клон получил зелёное на ослабленном наборе:\n${r.out}`);
+  const reg = join(p.dir, "shallow", "ratchets", "gates-declared.txt");
+  assert.equal(existsSync(reg), false, "проверка записала ослабленный набор новым эталоном");
+});
+
+// Снимок, отставший от манифеста, — тоже расхождение: иначе гейт, добавленный и убранный до
+// обновления снимка, уходит незамеченным. Храповик обязан требовать записи, а не догонять сам.
+test("снимок, отставший от манифеста, — не зелёное и не дописывается молча", (t) => {
+  const p = project(t, {
+    ".aqk.yml": MAN(["lint", "secrets"]),
+    "AGENTS.md": "# свод\n",
+    "ratchets/gates-declared.txt": `${REG}lint\n`,
+  });
+  const r = gate(p, "protection-not-removed");
+  assert.notEqual(r.code, 0, `снимок отстал, а проверка зелёная:\n${r.out}`);
+  const body = readFileSync(join(p.dir, "ratchets", "gates-declared.txt"), "utf8");
+  assert.doesNotMatch(body, /secrets/, "проверка дописала снимок сама");
+});
+
+test("совпадающий снимок — зелёное; снятый без причины — красное", (t) => {
+  const ok = project(t, {
+    ".aqk.yml": MAN(["lint", "secrets"]),
+    "AGENTS.md": "# свод\n",
+    "ratchets/gates-declared.txt": `${REG}lint\nsecrets\n`,
+  });
+  assert.equal(gate(ok, "protection-not-removed").code, 0, "совпадающий снимок покраснел");
+
+  const gone = project(t, {
+    ".aqk.yml": MAN(["lint"]),
+    "AGENTS.md": "# свод\n",
+    "ratchets/gates-declared.txt": `${REG}lint\nsecrets\n`,
+  });
+  assert.equal(gate(gone, "protection-not-removed").code, 1, "снятый без причины прошёл");
+
+  const named = project(t, {
+    ".aqk.yml": MAN(["lint"]),
+    "AGENTS.md": "# свод\n",
+    "ratchets/gates-declared.txt": `${REG}lint\nsecrets  # снят: закрыт гейтом lint\n`,
+  });
+  assert.equal(gate(named, "protection-not-removed").code, 0, "снятый с причиной покраснел");
+});
+
+// Писать снимок — дело явной операции, а не проверки. `add` и есть эта операция: он уже меняет
+// манифест, и запись в снимок — часть того же действия.
+test("aqk add записывает гейт в снимок", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n" });
+  aqk(p, "init");
+  aqk(p, "add", "todo-without-task");
+  const reg = join(p.dir, "ratchets", "gates-declared.txt");
+  assert.equal(existsSync(reg), true, "add не создал снимок");
+  assert.match(readFileSync(reg, "utf8"), /todo-without-task/, "add не записал гейт в снимок");
+});

package/tool/selfcheck/smoke/release-tools.test.mjs

@@ -0,0 +1,55 @@
+// Конвейер выпуска обязан ставить всё, что нужно ОБЪЯВЛЕННЫМ гейтам.
+//
+// ЗАЧЕМ. Шаг выпуска гоняет `doctor --run --min 1`. Гейт, чьей программы нет, выходит с кодом
+// 2 «не найден инструмент» — и выпуск встаёт на ровном месте, уже после метки. Так и вышло
+// 2026-09-10: объявили `test-not-adjusted`, его арбитр `checkwash` в publish.yml не ставился,
+// и выпуск 0.10.1 упал между меткой и публикацией.
+//
+// В самом publish.yml написано: «этот файл однажды уже разошёлся с ci.yml». Разошёлся второй
+// раз — значит нужен сторож, а не третья правка руками. Список выводится из МАНИФЕСТА: какие
+// программы объявленные записи называют полем `requires`, те и обязаны ставиться.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+// Имена объявленных гейтов — из .aqk.yml, а не из каталога: ставить нужно то, что гоняется.
+function declaredGates() {
+  const man = readFileSync(join(ROOT, ".aqk.yml"), "utf8").split("\n");
+  const out = [];
+  let inGates = false;
+  for (const line of man) {
+    if (/^gates:/.test(line)) { inGates = true; continue; }
+    if (/^[A-Za-z]/.test(line)) inGates = false;
+    const m = inGates && /^\s+([A-Za-z0-9_-]+):\s*\S/.exec(line);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
+function requiredProgram(slug) {
+  const yml = join(ROOT, "kit", "gates", slug, "gate.yml");
+  if (!existsSync(yml)) return null;
+  const m = /^requires:\s*(\S+)/m.exec(readFileSync(yml, "utf8"));
+  return m ? m[1] : null;
+}
+
+test("конвейер выпуска ставит программы всех объявленных записей", () => {
+  // ЧИТАЮТСЯ ТОЛЬКО СТРОКИ УСТАНОВКИ, а не файл целиком. Первая редакция искала имя по всему
+  // тексту — и нашла `checkwash` В КОММЕНТАРИИ, объявив сторожа зелёным ровно тогда, когда
+  // выпуск падал. Тот же грех, что ловим весь день, в проверке, написанной против него.
+  const wf = readFileSync(join(ROOT, ".github", "workflows", "publish.yml"), "utf8");
+  const installed = wf
+    .split("\n")
+    .filter((l) => /^\s*(pipx install|npm i -g|uv tool install)\s/.test(l))
+    .join("\n");
+  const missing = declaredGates()
+    .map((g) => requiredProgram(g))
+    .filter(Boolean)
+    .filter((prog) => !installed.includes(prog));
+  assert.deepEqual(missing, [],
+    `publish.yml не ставит: ${missing.join(", ")} — выпуск встанет после метки`);
+});

package/tool/selfcheck/smoke/verdict.test.mjs

@@ -0,0 +1,40 @@
+// Прогон обязан называть свой вердикт СЛОВАМИ, а не только кодом возврата.
+//
+// НАЙДЕНО АУДИТОМ ФИЧ 2026-09-09. `doctor --run` выходил с единицей и в конце не говорил ни
+// слова о причине: она оставалась в шапке, а внизу человек видел список зелёных гейтов и шёл
+// искать несуществующую поломку. С `--min` вердикт печатался всегда, без него — никогда.
+// Обратная сторона нашего же принципа: молчание неотличимо не только от успеха, но и от отказа.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { project, aqk } from "./_fixture.mjs";
+
+test("прогон называет свой вердикт словами в обоих исходах", (t) => {
+  const p = project(t, { "src/a.py": "def s():\n    return 1\n" });
+  aqk(p, "init");
+  // Гейт объявляется ПРЯМО, а не через `add`, и это не лень. `add` выбирает рецепт по тому,
+  // что установлено на машине: где есть ruff, у `todo-without-task` берётся родной
+  // `ruff check --select FIX,TD`, где нет — переносимый. Значит один и тот же проект получает
+  // РАЗНУЮ объявленную команду на разных машинах, и проверка про ВЕРДИКТ начинала зависеть от
+  // чужого инструмента. Поймано конвейером: локально зелено, на раннере красно.
+  // Здесь проверяется строка вердикта, а не поведение записи каталога, — гейту довольно быть
+  // заведомо тихим.
+  const man = join(p.dir, ".aqk.yml");
+  writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m, 'gates:\n  тихий: "true"'), "utf8");
+
+  // .gitignore нет — прогон красный, и обязан сказать, из-за чего именно.
+  const red = aqk(p, "doctor", "--run");
+  // Сообщение утверждения обязано нести ВЕСЬ хвост: проверка, которая говорит только «не
+  // совпало», отправляет читателя гадать — ровно то, за что мы ругаем чужие проверки.
+  const redTail = red.out.trimEnd().split("\n").slice(-6).join("\n");
+  assert.notEqual(red.code, 0, `прогон без .gitignore прошёл зелёным:\n${redTail}`);
+  assert.match(redTail, /красн/, `вердикт не назван в конце вывода (код ${red.code}):\n${redTail}`);
+
+  // Причина устранена — и «ничего не сказал» обязано отличаться от «всё проверено».
+  writeFileSync(join(p.dir, ".gitignore"), "x\n", "utf8");
+  const green = aqk(p, "doctor", "--run");
+  const greenTail = green.out.trimEnd().split("\n").slice(-6).join("\n");
+  assert.equal(green.code, 0, `прогон остался красным:\n${greenTail}`);
+  assert.match(greenTail, /зелён/, `успех не назван словами:\n${greenTail}`);
+});