agent-quality-kit 0.10.1 → 0.12.0

package/tool/lib/run.mjs

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

package/tool/selfcheck/gates.sh

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

package/tool/selfcheck/smoke/_fixture.mjs

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

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

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

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/units-cadence.mjs

@@ -7,7 +7,7 @@
 // незачем, а сто коммитов за день перепроверить надо.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { probeDue, probeState, probeEvery, PROBE_EVERY } from "../lib/cadence.mjs";
+import { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan } from "../lib/cadence.mjs";
 
 test("порог по умолчанию — сто коммитов, и он назван числом, а не спрятан", () => {
   assert.equal(PROBE_EVERY, 100);
@@ -67,3 +67,39 @@ test("непонятое значение порога — null, а не тих
   assert.equal(probeEvery({ probe: "часто" }), null);
   assert.equal(probeEvery({ probe: -5 }), null);
 });
+
+// --- отметка несёт ИМЕНА непойманных классов ------------------------------------------
+// ЗАЧЕМ. Отметка хранила одно число — `blind: 1`. Агент в `context` видел «один класс», человек
+// в `doctor` не видел ничего, и чтобы узнать КАКОЙ, надо было снова запускать пробу — ту самую
+// команду, о которой никто не вспоминает. Находка, которую не показали, не предостерегает.
+test("отметка пробы: по строке на слепой класс, в самом горячем файле, где он слеп", () => {
+  const recs = [
+    { entry: "swallowed-error", file: "src/a.py", verdict: "blind" },
+    { entry: "swallowed-error", file: "src/b.py", verdict: "blind" },
+    { entry: "no-print-in-prod", file: "src/a.py", verdict: "caught" },
+    { entry: "dead-code", file: "src/b.py", verdict: "unknown" },
+  ];
+  const lines = blindLines(recs);
+  // То же правило, что у countProbe: класс, слепой хоть где-то, — непокрыт; «не смогли» — не слеп.
+  assert.deepEqual(lines, ["blind-class: swallowed-error src/a.py"]);
+  const text = ["at: 5", "blind: 1", "", ...lines, "- src/a.py (fixes: 3)"].join("\n");
+  assert.deepEqual(parseBlind(text), [{ slug: "swallowed-error", file: "src/a.py" }]);
+});
+
+test("отметка старого формата и пустая — пустой список, а не падение", () => {
+  assert.deepEqual(parseBlind("at: 5\nblind: 1\n"), []);
+  assert.deepEqual(parseBlind(""), []);
+  assert.deepEqual(parseBlind(null), []);
+});
+
+// «Объявлен сейчас» не значит «поставлен после пробы»: проба и гоняет объявленные гейты.
+// Первая версия так и решила — и на самом комплекте написала «поставлено после пробы» про
+// gate-not-weakened, который стоял ДО неё и в kit/gates/_skip.sh брак пропустил. Самое ценное
+// сообщение («объявлен, но здесь не ловит») подменилось утешительным. Поймано живым прогоном.
+test("отметка помнит, какие гейты проба ПРОГОНЯЛА", () => {
+  const text = "at: 5\nblind: 1\nran: smoke gate-not-weakened units\n\nblind-class: x a.sh\n";
+  assert.deepEqual([...parseRan(text)].sort(), ["gate-not-weakened", "smoke", "units"]);
+  // Старая отметка этой строки не несёт: «не знаем», а не «ничего не было объявлено».
+  assert.equal(parseRan("at: 5\nblind: 1\n"), null);
+  assert.deepEqual([...parseRan("ran:\n")], []);
+});