agent-quality-kit 0.10.0 → 0.11.0

package/tool/selfcheck/smoke/own-samples.test.mjs

@@ -0,0 +1,131 @@
+// tool/selfcheck/smoke/own-samples.test.mjs — запись каталога не смеет выдавать СВОИ ЖЕ красные
+// образцы за находки пользователя.
+//
+// ЗАЧЕМ. `aqk add` кладёт в чужой проект гейт ВМЕСТЕ с образцами: без них `prove` ничего не
+// докажет. Образцы существуют, чтобы быть неправильными. Значит любой сканирующий гейт обязан их
+// не замечать — иначе человек ставит защиту и получает вечно красный конвейер на файлах, которые
+// положили МЫ. Обход для этого есть давно (`own_samples_filter`), и переносимые рецепты им
+// пользуются.
+//
+// ЧТО СЛОМАЛОСЬ. Обход построчный: он вырезает строки, содержащие путь образца. `ruff` перешёл на
+// многострочные блоки — путь уехал в отдельную строку («--> путь:строка:колонка»), а сообщение и
+// кусок исходника остались, и вырезать их фильтру нечем. Найдено 2026-09-10 на фикстуре пробы:
+// переносимый рецепт на том же проекте молчит, родной краснеет.
+//
+// ПОЧЕМУ ПРОВЕРКА, А НЕ ТОЛЬКО ПРАВКА. Правка чинит `ruff` сегодня. Формат вывода меняет любой
+// инструмент и не предупреждает — без этой проверки та же дыра вернётся молча и с другим именем.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { project, run, aqk } from "./_fixture.mjs";
+
+// Записи с РОДНЫМ рецептом. Дыра была не в ruff: она в том, что общий обход построчный, а вывод
+// инструмента — нет. Значит проверять надо не один инструмент, а каждый, который каталог зовёт.
+//
+// Таблица, а не список из четырёх имён: рецепт добавляют в каталог, и покрытие обязано
+// появляться вместе с ним, а не через месяц. Каждая строка — чем наполнить проект, чтобы
+// `aqk add` выбрал ИМЕННО этот рецепт, и какой командой её видно.
+//
+// Инструмента нет на машине — проверка ПРОПУСКАЕТСЯ вслух, а не зеленеет: «нечем проверить
+// здесь» и «проверено» разные факты, и весь комплект написан про эту разницу.
+const NATIVE = [
+  { entry: "todo-without-task", tool: "ruff", files: { "src/app.py": "def add(a, b):\n    return a + b\n" } },
+  { entry: "no-print-in-prod", tool: "ruff", files: { "src/app.py": "def add(a, b):\n    return a + b\n" } },
+  { entry: "swallowed-error", tool: "ruff", files: { "src/app.py": "def add(a, b):\n    return a + b\n" } },
+  { entry: "complexity-limit", tool: "ruff", files: { "src/app.py": "def add(a, b):\n    return a + b\n" } },
+  { entry: "dead-code", tool: "vulture", files: { "src/app.py": "def add(a, b):\n    return a + b\n\n\nprint(add(1, 2))\n" } },
+  { entry: "duplicate-code", tool: "pylint", files: { "src/app.py": "def add(a, b):\n    return a + b\n" } },
+  // javascript/typescript: eslint зовут четыре записи. Проект наполняется .js, чтобы `add`
+  // выбрал именно родной рецепт, а не переносимый.
+  { entry: "todo-without-task", tool: "eslint", files: { "src/app.js": "export const add = (a, b) => a + b;\n" } },
+  { entry: "no-print-in-prod", tool: "eslint", files: { "src/app.js": "export const add = (a, b) => a + b;\n" } },
+  { entry: "swallowed-error", tool: "eslint", files: { "src/app.js": "export const add = (a, b) => a + b;\n" } },
+  { entry: "complexity-limit", tool: "eslint", files: { "src/app.js": "export const add = (a, b) => a + b;\n" } },
+];
+
+const RUFF_ENTRIES = NATIVE.filter((n) => n.tool === "ruff").map((n) => n.entry);
+
+// Наличие инструмента спрашивается в НАСТОЯЩЕЙ среде, а не в песочнице проекта. Песочница
+// подменяет HOME, а инструменты, поставленные `pip --user` (vulture, pylint), — это python-
+// скрипты, которые ищут свои модули в $HOME/.local/lib. С чужим HOME импорт падает, и
+// установленный инструмент объявлялся отсутствующим: проверка молча пропускалась вместо того,
+// чтобы что-то проверить. Та же шишка записана в шапке `smoke.sh` про PYTHONUSERBASE.
+const have = (cmd) => spawnSync(cmd, ["--version"], { encoding: "utf8", timeout: 30000 }).status === 0;
+
+function declaredCommand(p, name) {
+  const man = readFileSync(join(p.dir, ".aqk.yml"), "utf8");
+  // Жадно и до КОНЦА СТРОКИ: команда рецепта сама содержит кавычки (`eslint --rule '{"x":1}'`),
+  // и нежадный разбор обрывал её на первой внутренней — тест падал на своей же выборке, а
+  // винил рецепт.
+  const m = man.match(new RegExp(`^\\s*${name}:\\s*"(.*)"\\s*$`, "m"));
+  return m ? m[1] : null;
+}
+
+for (const name of RUFF_ENTRIES) {
+  test(`«${name}»: родной рецепт не краснеет на СВОИХ образцах`, (t) => {
+    if (!have("ruff")) return t.skip("ruff не установлен — проверить нечем");
+    // Чистый python-файл: находок у пользователя нет по построению, и всё красное может прийти
+    // только из образцов, которые положил `add`.
+    const p = project(t, { "src/app.py": "def add(a, b):\n    return a + b\n" });
+    const init = aqk(p, "init");
+    assert.equal(init.code, 0, init.out);
+    const add = aqk(p, "add", name);
+    assert.equal(add.code, 0, add.out);
+
+    const cmd = declaredCommand(p, name);
+    assert.ok(cmd, `в манифесте нет команды для «${name}»`);
+    if (!/ruff/.test(cmd)) return t.skip(`выбран не ruff, а «${cmd}» — эта проверка про родной рецепт`);
+
+    const r = run(p, "bash", ["-c", cmd]);
+    assert.equal(r.code, 0,
+      `гейт покраснел на проекте без единой находки пользователя — значит выдал наши образцы ` +
+      `за его код.\nкоманда: ${cmd}\nвывод:\n${r.out}`);
+  });
+}
+
+// КОНТРОЛЬНАЯ. Заглушить чужой вывод легко — и так же легко заглушить его весь. Проверка выше
+// одна означала бы «гейт молчит», а не «гейт молчит О НАШИХ ОБРАЗЦАХ»: инструмент, лишённый
+// голоса, проходит её идеально. Поэтому тот же проект, но с НАСТОЯЩЕЙ находкой пользователя.
+// Маркер долга собирается ИЗ КУСКОВ намеренно. Написанный целиком, он живёт в исходнике
+// комплекта — и наш собственный `todo-without-task` считает его нашим долгом. Поймано этим же
+// гейтом через минуту после того, как файл был написан.
+const MARKER = ["TO", "DO"].join("");
+for (const [name, file, code] of [
+  ["todo-without-task", "src/debt.py", `def f():\n    # ${MARKER}: переписать\n    return 1\n`],
+  ["no-print-in-prod", "src/loud.py", "def f():\n    print('привет')\n    return 1\n"],
+]) {
+  test(`«${name}»: на находке ПОЛЬЗОВАТЕЛЯ тот же рецепт краснеет`, (t) => {
+    if (!have("ruff")) return t.skip("ruff не установлен — проверить нечем");
+    const p = project(t, { "src/app.py": "def add(a, b):\n    return a + b\n", [file]: code });
+    assert.equal(aqk(p, "init").code, 0);
+    assert.equal(aqk(p, "add", name).code, 0);
+    const cmd = declaredCommand(p, name);
+    if (!/ruff/.test(cmd)) return t.skip(`выбран не ruff, а «${cmd}»`);
+    const r = run(p, "bash", ["-c", cmd]);
+    assert.notEqual(r.code, 0,
+      `гейт промолчал о настоящей находке — значит его заглушили целиком.\nкоманда: ${cmd}\nвывод:\n${r.out}`);
+    assert.ok(r.out.includes(file.split("/").pop()),
+      `гейт покраснел, но не назвал файл ${file}. Вывод:\n${r.out}`);
+  });
+}
+
+// Общая проверка по ТАБЛИЦЕ: любой родной рецепт, чей инструмент здесь есть, обязан молчать на
+// проекте, где единственные «нарушения» — образцы, которые положил `add`.
+for (const { entry, tool, files } of NATIVE) {
+  test(`«${entry}» (${tool}): родной рецепт молчит о наших образцах`, (t) => {
+    if (!have(tool)) return t.skip(`${tool} не установлен — проверить нечем, и это НЕ «проверено»`);
+    const p = project(t, files);
+    assert.equal(aqk(p, "init").code, 0);
+    const add = aqk(p, "add", entry);
+    if (add.code !== 0) return t.skip(`запись не ставится здесь: ${add.out.trim().split("\n")[0]}`);
+    const cmd = declaredCommand(p, entry);
+    assert.ok(cmd, `в манифесте нет команды для «${entry}»`);
+    if (!cmd.includes(tool)) return t.skip(`выбран не ${tool}, а «${cmd}» — эта проверка про родной рецепт`);
+    const r = run(p, "bash", ["-c", cmd]);
+    assert.equal(r.code, 0,
+      `гейт покраснел на проекте без единой находки пользователя — значит выдал наши образцы ` +
+      `за его код.\nкоманда: ${cmd}\nвывод:\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.sh

@@ -60,6 +60,15 @@ trap 'rm -rf "$WORK"' EXIT
 #    конвейере нет. Сеть в тестах — отдельный класс флейков во всех разборах; здесь она ещё и
 #    делает две среды разными по построению.
 export TMPDIR="$WORK/tmp"; mkdir -p "$TMPDIR"
+# PYTHONUSERBASE — ДО подмены HOME и из-за неё. Инструменты, поставленные `pip --user`
+# (`vulture`, `checkwash`), это python-скрипты, которые ищут свои модули в
+# `$HOME/.local/lib/python*/site-packages`. С песочницей вместо HOME импорт падает, а гейт,
+# чей арбитр упал, печатает «арбитр покраснел на ЗЕЛЁНОМ образце» — то есть проверка врёт о
+# записи каталога, а не о своей поломке. Найдено 2026-09-09 в тот же час, когда инструменты
+# были поставлены: до установки этот путь кода не исполнялся вовсе.
+# Переменная — штатный способ указать python, где искать пользовательские пакеты; бинарям
+# (`ruff`, `zizmor`, `slopcheck`) она не нужна, и им песочница не мешала.
+export PYTHONUSERBASE="${PYTHONUSERBASE:-$HOME/.local}"
 export HOME="$WORK/home"; export USERPROFILE="$HOME"; mkdir -p "$HOME"
 export AQK_UPDATE=0
 
@@ -723,7 +732,12 @@ BDIR="$(mktemp -d)"
 )
 B_OUT=$( cd "$BDIR" && node "$CLI" badge 2>&1 )
 B_LVL=$(printf '%s' "$B_OUT" | sed -n 's|.*img.shields.io/badge/AQK-\([0-9]\)-.*|\1|p' | head -1)
-D_LVL=$( cd "$BDIR" && node "$CLI" doctor 2>&1 | sed -n 's/.*Уровень: AQK-\([0-9]\).*/\1/p' | head -1 )
+# ЗНАЧОК СВЕРЯЕТСЯ С ДОКАЗАННЫМ УРОВНЕМ. `badge` гоняет доказательство сам, а `doctor` без
+# `--run` его не гоняет и честно говорит «не доказано» — это РАЗНЫЕ вопросы, и сравнивать их
+# нельзя. Пока доказательство ни на что не влияло в этой фикстуре, оба ответа совпадали
+# случайно; как только у проекта появился храповик, они разошлись, и проверка обвинила
+# исправную программу. Найдено 2026-09-10 правкой, не трогавшей ни значок, ни уровень.
+D_LVL=$( cd "$BDIR" && node "$CLI" doctor --run 2>&1 | sed -n 's/.*Уровень: AQK-\([0-9]\).*/\1/p' | head -1 )
 if [ -n "$B_LVL" ] && [ "$B_LVL" = "$D_LVL" ]; then
   ok "badge выдаёт значок с уровнем doctor (AQK-$B_LVL)"
 else

package/tool/selfcheck/units-context.mjs

@@ -186,3 +186,27 @@ test("без --full свод не вливается — только ссылк
   assert.doesNotMatch(t, /Правило одно/);
   assert.match(t, /AGENTS\.md/);
 });
+
+// --- СОСТОЯНИЯ ПРОБЫ: пять, а веток было три ---------------------------------------------
+// ЗАЧЕМ. Блок читает машина: пустое место и «всё прикрыто» она примет за разрешение. Состояний
+// у пробы пять — `never`, `off`, `unknown`, `stale`, `fresh`, — а печатались три ветки: «не
+// делалась», «есть непрокрытое», иначе «всё прикрыто». В последнюю падали ДВА состояния, где мы
+// как раз ничего не знаем:
+//   off      — пробу выключили в манифесте (`probe: 0`);
+//   unknown  — счётчик коммитов не взять либо в манифесте непонятое значение.
+// Обе печатались как «в местах пробы всё прикрыто» — то есть выключенная и несостоявшаяся
+// проверка выдавались за проверку, сказавшую «чисто».
+test("выключенная и несостоявшаяся проба не выдаются за «всё прикрыто»", () => {
+  // Якорь берётся из САМОГО текста, а не из представления о нём: первая редакция искала слово
+  // «прикрыт», которого в строке про чистую пробу нет, — и краснела на исправном выводе.
+  const clean = text({ probe: { state: "fresh", behind: 3, blind: 0 } });
+  assert.match(clean, /каждый применимый класс/, "строка про чистую пробу пропала");
+
+  const off = text({ probe: { state: "off", behind: null, blind: 0 } });
+  assert.doesNotMatch(off, /всё прикрыто|прикрыто ничем нет/,
+    `выключенная проба выдана за покрытие: ${off}`);
+  assert.match(off, /выключен|отключен/i, `не сказано, что проба выключена: ${off}`);
+
+  const unknown = text({ probe: { state: "unknown", behind: null, blind: 0 } });
+  assert.match(unknown, /НЕИЗВЕСТНО|неизвестн/i, `несостоявшаяся проба не названа: ${unknown}`);
+});

package/tool/selfcheck/units-evidence.mjs

@@ -81,3 +81,37 @@ test("покрытие: файл вне всех целей остаётся н
   assert.deepEqual(cov.silent.get("tool/a.js"), ["size"]);
   assert.deepEqual(cov.uncovered, [".github/workflows/ci.yml"]);
 });
+
+// --- НАЗВАН ПРОВЕРКОЙ — ЭТО ТОЛЬКО ВЫВОД ------------------------------------------------
+// ЗАЧЕМ. Пути брались из КОМАНДЫ и вывода разом: `pathsIn(cmd + "\n" + out)`. Гейт, не
+// напечатавший ни слова, делал «названным» любой файл, упомянутый в строке запуска. Опыт
+// 2026-09-09: молчащая проверка `sh checks/quiet.sh .` дала
+//   названо проверкой: [ 'checks/quiet.sh' ]
+// Так «доказывалась» у нас каждая правка `kit/gates/*/check.sh` и `tool/selfcheck/*.sh` —
+// то есть самих проверок, где правда важнее всего.
+//
+// Но и выбросить команду нельзя: она отвечает на ДРУГОЙ вопрос — куда гейт был направлен.
+// Файл, названный в команде и не упомянутый в выводе, — это «обойдён молча», а не «никто не
+// смотрел»: разница между «просмотрен и чист» и «не просмотрен» и есть предмет этого модуля.
+test("молчащий гейт не «называет» файл из своей команды, но и не теряет его", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  const results = [{ name: "тихий", cmd: "sh checks/quiet.sh .", out: "" }];
+  const r = coverage(["checks/quiet.sh"], results, () => false);
+  assert.deepEqual([...r.covered.keys()], [], "путь из команды выдан за находку проверки");
+  assert.deepEqual([...r.silent.keys()], ["checks/quiet.sh"], "файл, куда гейт направлен, потерян");
+});
+
+test("гейт, направленный на конкретный файл, накрывает именно его", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  const results = [{ name: "линт", cmd: "eslint src/a.js", out: "" }];
+  const r = coverage(["src/a.js", "src/b.js"], results, () => false);
+  assert.deepEqual([...r.silent.keys()], ["src/a.js"]);
+  assert.deepEqual(r.uncovered, ["src/b.js"]);
+});
+
+test("напечатанный путь по-прежнему означает «названо»", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  const results = [{ name: "линт", cmd: "eslint .", out: "src/a.js:3: находка" }];
+  const r = coverage(["src/a.js"], results, () => false);
+  assert.deepEqual([...r.covered.keys()], ["src/a.js"]);
+});

package/tool/selfcheck/units-execution.mjs

@@ -0,0 +1,88 @@
+// tool/selfcheck/units-execution.mjs — исход ЗАПУСКА процесса, отдельно от смысла находки.
+// Написаны ДО реализации.
+//
+// ЗАЧЕМ. `prove.mjs` считал находкой ЛЮБОЙ ненулевой код на красном образце. Опыт 2026-09-09:
+// проверка, которая ВИСНЕТ на красном образце и молчит на зелёном, получала вердикт
+// `proven: 1, ok: true` — то есть зависший гейт объявлялся ловящим брак. Это `pytest || true`
+// в функции, которая считает наш главный уровень.
+//
+// ПОЧЕМУ НЕЛЬЗЯ ОДНИМ ПРАВИЛОМ «1 — находка, 2+ — сбой». Замер по настоящим инструментам:
+//   ruff     чисто 0 · находка 1 (и синтаксическая ошибка тоже 1) · неверный флаг 2
+//            · НЕСУЩЕСТВУЮЩИЙ ПУТЬ → 0 и «All checks passed!»
+//   eslint   чисто 0 · находка 1 · настройка или внутренняя ошибка 2
+//   vulture  чисто 0 · НАХОДКА 3 · плохой ввод 1 · ошибка CLI 2
+//   pylint   чисто 0 · находка битовой маской (2 ошибка, 4 предупреждение, 8, 16)
+//            · ОШИБКА ВЫЗОВА 32
+// Общее правило переврало бы vulture и pylint в обе стороны. Значит знание о кодах живёт
+// рядом с инструментом — нормализующим адаптером, а протокол остаётся простым.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { classify, findingCodes } from "../lib/execution.mjs";
+
+// Вход — то, что отдаёт spawnSync: { status, signal, error }.
+const R = (over = {}) => ({ status: 0, signal: null, error: undefined, ...over });
+
+test("ноль — чисто, объявленный код находки — находка", () => {
+  assert.equal(classify(R({ status: 0 })).state, "clean");
+  assert.equal(classify(R({ status: 1 })).state, "finding");
+});
+
+// Убитый по таймауту процесс отдаёт status null. Прежний код превращал его в 124 и считал
+// находкой — а сам же комментарий рядом называл это «не знаем».
+test("таймаут — не находка, а сбой инструмента", () => {
+  const r = classify(R({ status: null, signal: "SIGTERM" }));
+  assert.equal(r.state, "infra_error");
+  assert.equal(r.reason, "timeout");
+});
+
+test("убийство сигналом — сбой инструмента", () => {
+  const r = classify(R({ status: null, signal: "SIGKILL" }));
+  assert.equal(r.state, "infra_error");
+  assert.match(r.reason, /timeout|signal/);
+});
+
+// Процесс не запустился вовсе: нет программы, нет прав, нет каталога.
+// Node при истечении срока ставит И signal, И error с кодом ETIMEDOUT. Если смотреть на
+// error первым и не различать его код, таймаут называется «ошибкой запуска»: состояние верное,
+// причина ложная. Поймано первым же контрпримером после правки — вердикт стал верным, а
+// объяснение врало.
+test("таймаут не выдаётся за ошибку запуска: у Node при сроке стоит и signal, и error", () => {
+  const timedOut = { status: null, signal: "SIGTERM",
+    error: Object.assign(new Error("spawnSync /bin/sh ETIMEDOUT"), { code: "ETIMEDOUT" }) };
+  assert.equal(classify(timedOut).reason, "timeout");
+  const notFound = { status: null, signal: null,
+    error: Object.assign(new Error("spawnSync ENOENT"), { code: "ENOENT" }) };
+  assert.equal(classify(notFound).reason, "spawn_error");
+});
+
+test("ошибка запуска — сбой инструмента, а не находка", () => {
+  const r = classify(R({ status: null, signal: null, error: new Error("spawn ENOENT") }));
+  assert.equal(r.state, "infra_error");
+  assert.equal(r.reason, "spawn_error");
+});
+
+test("неожиданный код — сбой инструмента, а не находка", () => {
+  const r = classify(R({ status: 2 }));
+  assert.equal(r.state, "infra_error");
+  assert.equal(r.reason, "unexpected_exit");
+  assert.equal(r.code, 2);
+});
+
+// Знание о кодах живёт рядом с инструментом. Числа — из замера, а не из памяти.
+test("адаптеры знают свои коды: vulture 3 — находка, pylint 32 — ошибка вызова", () => {
+  assert.equal(classify(R({ status: 3 }), findingCodes("vulture")).state, "finding");
+  assert.equal(classify(R({ status: 1 }), findingCodes("vulture")).state, "infra_error");
+
+  assert.equal(classify(R({ status: 2 }), findingCodes("pylint")).state, "finding");
+  assert.equal(classify(R({ status: 24 }), findingCodes("pylint")).state, "finding");
+  assert.equal(classify(R({ status: 32 }), findingCodes("pylint")).state, "infra_error");
+
+  // Незнакомая программа — умолчание: 0 чисто, 1 находка, остальное сбой. Это ЧЕСТНЕЕ, чем
+  // догадка: неизвестный код становится «не знаем», а не «поймал».
+  assert.equal(classify(R({ status: 1 }), findingCodes("неизвестный-инструмент")).state, "finding");
+  assert.equal(classify(R({ status: 3 }), findingCodes("неизвестный-инструмент")).state, "infra_error");
+});
+
+test("наши собственные обёртки: 2 — «нет инструмента», а не находка", () => {
+  assert.equal(classify(R({ status: 2 }), findingCodes("bash")).state, "infra_error");
+});

package/tool/selfcheck/units-level.mjs

@@ -9,7 +9,7 @@
 //   node --test tool/selfcheck/units-level.mjs
 import test from "node:test";
 import assert from "node:assert/strict";
-import { commandFor } from "../lib/prove.mjs";
+import { commandFor, verdict } from "../lib/prove.mjs";
 import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS, parseManifest, coversOf, coversUnproven, unparsedLines } from "../lib/manifest.mjs";
 import { pickLang, langFromText } from "../i18n/index.mjs";
 
@@ -266,3 +266,34 @@ test("правильный манифест не порождает жалоб",
 test("комментарии и пустые строки не считаются потерянными", () => {
   assert.deepEqual(unparsedLines("# заметка\n\naqk: 1\n   # ещё\n"), []);
 });
+
+// --- ВЕРДИКТ ДОКАЗАТЕЛЬСТВА: один доказанный гейт не покрывает недоказанный -------------
+// ЗАЧЕМ. Прежнее правило было `broken === 0 && proven > 0`. Оно позволяло ОДНОМУ доказанному
+// гейту компенсировать сколько угодно недоказанных: проект с пятью объявленными проверками,
+// из которых четыре не смогли отработать, получал AQK-2 за счёт пятой. Ступень называется
+// «гейты доказаны», а доказан был один.
+//
+// Различие тонкое и обязательное: «нечем доказывать» бывает ЗАКОННЫМ (нет образцов, нет
+// программы на этой машине, стоит рецепт под другой язык) — такое ступень не отнимает.
+// А «запускали и не смогло отработать» — это сбой, и он ступень отнимает: иначе таймаут
+// арбитра снова становится способом получить зелёное.
+test("сбой арбитра отнимает ступень, законная недоказуемость — нет", () => {
+  assert.equal(verdict([{ state: "proven" }]).ok, true);
+  assert.equal(verdict([]).ok, false, "доказывать нечего — не доказано");
+  assert.equal(verdict([{ state: "unprovable", why: "no-samples" }]).ok, false,
+    "ни один гейт не доказан");
+
+  // Законная недоказуемость рядом с доказанным гейтом ступень не отнимает.
+  assert.equal(verdict([
+    { state: "proven" },
+    { state: "unprovable", why: "needs-program" },
+  ]).ok, true);
+
+  // А вот сбой арбитра — отнимает, сколько бы соседей ни было доказано.
+  assert.equal(verdict([
+    { state: "proven" },
+    { state: "unprovable", why: "infra", reason: "timeout" },
+  ]).ok, false, "таймаут арбитра компенсирован соседним гейтом");
+
+  assert.equal(verdict([{ state: "proven" }, { state: "broken" }]).ok, false);
+});