agent-quality-kit 0.9.0 → 0.10.0

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/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}`);
+});

package/tool/selfcheck/smoke.sh

@@ -23,7 +23,15 @@ PASS=0
 FAIL=0
 
 ok()   { printf '  \033[32m✔\033[0m  %s\n' "$1"; PASS=$((PASS + 1)); }
-bad()  { printf '  \033[31m✘\033[0m  %s\n' "$1"; printf '      %s\n' "${2:-}"; FAIL=$((FAIL + 1)); }
+# Упавшие называются ПОИМЁННО И С ПРИЧИНОЙ в итоге, а не только по ходу. Прогон запускают гейтом, а вывод
+# упавшего гейта обрезается — и причина, напечатанная в середине двухсот строк, до глаз не
+# доезжает. Час поисков в конвейере 2026-09-09 стоил ровно этого: список красных был, а увидеть
+# его было нельзя. Имени мало: следующий круг конвейера показал имя и не показал причину —
+# она печатается сразу под находкой, то есть в середине, которую обрезка и съедает.
+FAILED_NAMES=""
+bad()  { printf '  \033[31m✘\033[0m  %s\n' "$1"; printf '      %s\n' "${2:-}"; FAIL=$((FAIL + 1));
+         FAILED_NAMES="${FAILED_NAMES:+$FAILED_NAMES
+  }$1 — ${2:-без пояснения}"; }
 
 # Node на Windows видит мир глазами Windows, а Git Bash — глазами POSIX: путь вида
 # /tmp/tmp.XXXX, отданный в `node -e`, там не существует, и проверка падает не на том, что
@@ -35,6 +43,26 @@ node_in() { D="$1"; shift; ( cd "$D" && node "$@" ); }
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 
+# ГЕРМЕТИЧНОСТЬ. Три строки, каждая закрывает свой класс отказов, найденный сплошным чтением
+# и замерами 2026-09-09. Прогон обязан давать один и тот же ответ на любой машине и в любой
+# день — иначе «116 зелёных» означает не «работает», а «сегодня совпало».
+#
+# 1. TMPDIR внутрь $WORK. В файле 65 вызовов `mktemp -d` и ОДИН trap — на $WORK. Прерванный
+#    прогон оставлял 64 каталога, а два из них несут по копии всего дерева (`cp -r tool kit`,
+#    ≈4000 файлов). Одна строка вместо правки шестидесяти пяти: mktemp читает TMPDIR, и вся
+#    временная работа попадает под уже существующую уборку.
+# 2. HOME в песочницу. Комплект пишет `~/.config/aqk/feedback-shown` — просьбу про звезду
+#    показывают один раз НА МАШИНУ. Из 65 фикстур свой HOME задавали 8. Значит на машине
+#    разработчика (отметка лежит с сентября) `init` молчит, а на свежем раннере — говорит:
+#    один и тот же прогон получает РАЗНЫЙ ввод. Плюс прогон гадил в настоящий домашний каталог.
+# 3. AQK_UPDATE=0. `doctor --brief` ходит в реестр npm по сети с таймаутом 3 с — и только вне
+#    конвейера (`updateWanted` выключается при CI). То есть локально тесты сетевые, а в
+#    конвейере нет. Сеть в тестах — отдельный класс флейков во всех разборах; здесь она ещё и
+#    делает две среды разными по построению.
+export TMPDIR="$WORK/tmp"; mkdir -p "$TMPDIR"
+export HOME="$WORK/home"; export USERPROFILE="$HOME"; mkdir -p "$HOME"
+export AQK_UPDATE=0
+
 printf '\n\033[1mtool/selfcheck/smoke.sh\033[0m\n\n'
 
 # --- 1. синтаксис самой программы ------------------------------------------
@@ -345,10 +373,24 @@ if [ -f "$BLOBDIR/GOD_AI.md" ]; then
     bad "blob собрал не все методички" "в kit/docs $EXPECT_MD, в склейке $GOT_MD"
   fi
   # Ссылки на соседние файлы внутри склейки ведут в никуда: соседей рядом больше нет.
-  if grep -qE '\]\((?!https?:)[^)]*\.md\)' "$BLOBDIR/GOD_AI.md" 2>/dev/null; then
+  #
+  # ДВА ПРОХОДА, А НЕ ОПЕРЕЖАЮЩАЯ ПРОВЕРКА. Здесь стояло `grep -qE '...(?!https?:)...'`, и это
+  # была ЛОЖЬ: `(?!` — синтаксис PCRE, в POSIX ERE его нет. GNU grep печатает предупреждение и
+  # не находит ничего, ugrep падает с ошибкой разбора — в обоих случаях `if` уходит в `else`, и
+  # проверка печатала зелёное НА ЛЮБЫХ ДАННЫХ. Ровно тот грех, ради поимки которого написан весь
+  # комплект, внутри прибора, который его ищет. Найдено сплошным чтением 2026-09-09.
+  #
+  # Поэтому же ниже проверяется САМА ПРОВЕРКА: подделываем склейку с относительной ссылкой и
+  # требуем, чтобы её нашли. Без этого следующая такая опечатка снова проедет зелёной.
+  rel_links() { grep -oE '\]\([^)]+\.md[^)]*\)' "$1" 2>/dev/null | grep -vE '^\]\(https?:' | grep -q .; }
+  printf '%s' "$(cat "$BLOBDIR/GOD_AI.md")" > "$BLOBDIR/doctored.md"
+  printf '\nсм. [соседний файл](other.md)\n' >> "$BLOBDIR/doctored.md"
+  if rel_links "$BLOBDIR/GOD_AI.md"; then
     bad "в склейке остались ссылки на соседние файлы" "внутри одного файла они ведут в никуда"
+  elif ! rel_links "$BLOBDIR/doctored.md"; then
+    bad "проверка ссылок не может покраснеть" "подделанная склейка с относительной ссылкой прошла"
   else
-    ok "ссылки на соседние файлы в склейке сняты"
+    ok "ссылки на соседние файлы сняты, и проверка это умеет заметить"
   fi
 else
   bad "blob не создал GOD_AI.md" "$BLOBDIR"
@@ -579,7 +621,7 @@ REPDIR="$(mktemp -d)"
 (
   cd "$REPDIR" && git init -q . && mkdir -p src &&
   printf 'a = 1  # noqa\n' > src/a.py &&
-  node "$CLI" start > /tmp/aqk-start.log 2>&1
+  node "$CLI" start > "$WORK/start.log" 2>&1
 )
 REP_OUT=$( cd "$REPDIR" && node "$CLI" report 2>&1 ); REP_CODE=$?
 if [ "$REP_CODE" -ne 0 ] && printf '%s' "$REP_OUT" | grep -q '❌ gate-not-weakened'; then
@@ -591,7 +633,7 @@ else
   G_LS=$( cd "$REPDIR" && ls gates 2>&1 | tr '\n' ' ' )
   G_DECL=$( cd "$REPDIR" && sed -n '/^gates:/,$p' .aqk.yml 2>/dev/null | grep -cE '^[[:space:]]+[A-Za-z0-9_-]+:' )
   G_OUT=$( cd "$REPDIR" && bash gates/gate-not-weakened/check.sh . 2>&1 | head -2 ); G_CODE=$?
-  bad "report не отличает красное от зелёного" "код отчёта $REP_CODE; гейт напрямую: код $G_CODE, вывод «$(printf '%s' "$G_OUT" | tr '\n' ' ')»; в gates/: «$G_LS»; объявлено гейтов: $G_DECL; хвост start: «$(tail -4 /tmp/aqk-start.log 2>/dev/null | tr '\n' ' ')»"
+  bad "report не отличает красное от зелёного" "код отчёта $REP_CODE; гейт напрямую: код $G_CODE, вывод «$(printf '%s' "$G_OUT" | tr '\n' ' ')»; в gates/: «$G_LS»; объявлено гейтов: $G_DECL; хвост start: «$(tail -4 "$WORK/start.log" 2>/dev/null | tr '\n' ' ')»"
 fi
 if [ -f "$REPDIR/.aqk/report.md" ] && grep -q '^## ' "$REPDIR/.aqk/report.md"; then
   ok "report сохраняет .aqk/report.md"
@@ -1731,7 +1773,7 @@ rm -rf "$PRVP"
 # и шесть `units-*.mjs`), и заметить это можно было только сверкой руками. Тот же класс, что
 # «гейт объявлен и не существует»: расхождение молчит.
 MISSING=""
-for F in "$ROOT"/tool/lib/*.mjs "$ROOT"/tool/commands/*.mjs "$ROOT"/tool/selfcheck/*; do
+for F in "$ROOT"/tool/lib/*.mjs "$ROOT"/tool/commands/*.mjs "$ROOT"/tool/selfcheck/* "$ROOT"/tool/selfcheck/*/*; do
   B=$(basename "$F")
   grep -qF "$B" "$ROOT/AGENTS.md" || MISSING="$MISSING $B"
 done
@@ -1786,6 +1828,132 @@ else
 fi
 chmod 700 "$HOMEH" 2>/dev/null; rm -rf "$HOMEP" "$HOMEH"
 
+# --- 109. probe: находит слепоту и не выдаёт её за покрытие ---------------------
+# ЗАЧЕМ КОМАНДА. `doctor` говорит «держит машина N» — N из чего? `prove` доказывает, что гейт
+# ловит брак НА СВОЁМ образце. Ни один не отвечает: что в ЭТОМ репозитории не прикрыто ничем.
+# Замер 2026-09-09 на самом комплекте: настоящий файл, подсаженные проглоченная ошибка и печать,
+# 21 объявленный гейт — покраснело НОЛЬ. Узнать об этом было нечем.
+# Проверяются ОБА конца: класс, который объявленный гейт ловит, обязан быть зелёным, а тот,
+# которого не ловит никто, — красным. Проверка одного конца пропустила бы команду, которая
+# всегда говорит «не прикрыто», и команду, которая всегда говорит «прикрыто».
+PRBP="$(mktemp -d)"
+(
+  cd "$PRBP" && git init -q . && git config user.email a@b && git config user.name a
+  mkdir -p src && printf 'def send(to):\n    return 1\n' > src/mailer.py
+  git add -A && git commit -qm "feat: почта"
+  printf '# правка\n' >> src/mailer.py && git add -A && git commit -qm "fix: письма не уходили"
+  node "$CLI" init && node "$CLI" add todo-without-task
+  # Коммитим ВСЁ, что положили init и add: иначе дерево грязное ещё до пробы, и проверка
+  # «probe ничего не пишет» меряла бы мою же фикстуру, а не команду.
+  git add -A && git commit -qm "Сделано: комплект. Не уверен: ничего"
+) >/dev/null 2>&1
+PRB=$( cd "$PRBP" && AQK_LANG=ru node "$CLI" probe --top 1 2>&1 ); PRB_C=$?
+# Слепое: secrets-not-in-code не объявлен, образец под .py у него есть — обязан быть красным.
+# Прикрытое: todo-without-task объявлен — обязан быть зелёным и назвать, кто поймал.
+if [ "$PRB_C" -eq 0 ] &&
+   printf '%s' "$PRB" | grep -q "НЕ ЛОВИТ НИКТО" &&
+   printf '%s' "$PRB" | grep -q "ловит: todo-without-task" &&
+   printf '%s' "$PRB" | grep -q "починок в истории: 1"; then
+  ok "probe: слепые классы названы, прикрытый назван поимённо, прогон не уронен"
+else
+  bad "probe не различает слепое и прикрытое" "код $PRB_C, слепых $(printf '%s' "$PRB" | grep -c 'НЕ ЛОВИТ'), пойманных $(printf '%s' "$PRB" | grep -c 'ловит:')"
+fi
+# КОД человека проба не трогает: образец живёт во временном каталоге. Если бы он попал в
+# репозиторий, команда осмотра стала бы командой правки — и её выключили бы в тот же день.
+# Своя отметка каденции — исключение, и единственное: она лежит в `.aqk/`, там же, где отчёт
+# прогона, и без неё каденция невозможна (следующий прогон не узнает, что проба была).
+# Проверяется именно это разделение: за пределами `.aqk/` — ни следа.
+DIRTY=$( cd "$PRBP" && git status --porcelain | grep -cv ' \.aqk/' )
+if [ "$DIRTY" -eq 0 ]; then
+  ok "probe не трогает код: пишет только свою отметку в .aqk/"
+else
+  bad "probe оставил следы вне .aqk/" "$(cd "$PRBP" && git status --porcelain | grep -v ' \.aqk/' | head -3 | tr '\n' ' ')"
+fi
+rm -rf "$PRBP"
+
+# --- 111. проба случается САМА, один раз, и попадает агенту в контекст -----------
+# ГЛАВНОЕ В ЭТОЙ ПРОВЕРКЕ — не механика, а замысел. Владелец сформулировал так: «команду, о
+# которой надо вспомнить, агент не вспомнит, а человек о ней не узнает». Это тот же класс, что
+# файл, который можно не прочитать, — и весь комплект написан против него. Значит `probe`,
+# оставленная ручной, отвечает на важнейший вопрос и не задаётся никем.
+# Проверяются три вещи, и каждая — отдельный способ провалиться:
+#   1. прогон делает пробу САМ, когда её не делали;
+#   2. второй прогон подряд её НЕ повторяет — иначе каденция превращается в шум;
+#   3. агент узнаёт результат из блока состояния, не зная про команду.
+CADP="$(mktemp -d)"
+(
+  cd "$CADP" && git init -q . && git config user.email a@b && git config user.name a
+  mkdir -p src && printf 'def s():\n    return 1\n' > src/a.py
+  git add -A && git commit -qm "feat: старт"
+  printf '# п\n' >> src/a.py && git add -A && git commit -qm "fix: не работало"
+  node "$CLI" init && node "$CLI" add todo-without-task
+) >/dev/null 2>&1
+CTX0=$( cd "$CADP" && AQK_LANG=ru node "$CLI" context 2>&1 )
+RUN1=$( cd "$CADP" && AQK_LANG=ru node "$CLI" doctor --run 2>&1 )
+RUN2=$( cd "$CADP" && AQK_LANG=ru node "$CLI" doctor --run 2>&1 )
+CTX1=$( cd "$CADP" && AQK_LANG=ru node "$CLI" context 2>&1 )
+if printf '%s' "$CTX0" | grep -q "НЕИЗВЕСТНО" &&
+   printf '%s' "$RUN1" | grep -q "ещё не делали" &&
+   ! printf '%s' "$RUN2" | grep -q "ещё не делали" &&
+   printf '%s' "$CTX1" | grep -q "Не прикрыто ничем"; then
+  ok "проба запускается прогоном сама, не повторяется и попадает агенту в контекст"
+else
+  bad "каденция пробы не работает" \
+      "до: $(printf '%s' "$CTX0" | grep -c 'НЕИЗВЕСТНО'), первый: $(printf '%s' "$RUN1" | grep -c 'ещё не делали'), второй: $(printf '%s' "$RUN2" | grep -c 'ещё не делали'), после: $(printf '%s' "$CTX1" | grep -c 'Не прикрыто')"
+fi
+# Выключатель обязан быть у всего, что случается само: иначе первый же, кому это помешало,
+# выключит весь прогон, а не одну пробу.
+CADP2="$(mktemp -d)"
+( cd "$CADP2" && git init -q . && git config user.email a@b && git config user.name a
+  mkdir -p src && printf 'def s():\n    return 1\n' > src/a.py
+  git add -A && git commit -qm "feat: старт"
+  node "$CLI" init && node "$CLI" add todo-without-task ) >/dev/null 2>&1
+OFF=$( cd "$CADP2" && AQK_PROBE=0 AQK_LANG=ru node "$CLI" doctor --run 2>&1 )
+if ! printf '%s' "$OFF" | grep -q "ещё не делали"; then
+  ok "AQK_PROBE=0 выключает пробу, не трогая прогон"
+else
+  bad "проба игнорирует выключатель" "AQK_PROBE=0 не подействовал"
+fi
+rm -rf "$CADP" "$CADP2"
+
+# --- переехавшие проверки: встроенный раннер --------------------------------
+# ПОЧЕМУ ЗДЕСЬ МОСТ, А НЕ ВТОРАЯ КОМАНДА. Проверки переезжают на `node --test` по одной, и всё
+# это время у прогона обязана оставаться ОДНА точка входа и ОДИН счётчик: два числа в двух
+# местах через месяц разойдутся, и никто не заметит, что половина не запускается.
+#
+# ЗАЧЕМ ПЕРЕЕЗД. У встроенного раннера есть то, чего нет у этого файла и не появится: свой
+# каталог и уборка на каждую проверку, таймаут на каждую, точечный перезапуск одной по имени
+# (`--test-name-pattern`). Диагностика отказа падает с сорока секунд до одной. Проверено на
+# Node 20.20.2 — той версии, что стоит в конвейере.
+NODE_SMOKE="$ROOT/tool/selfcheck/smoke"
+if [ -d "$NODE_SMOKE" ]; then
+  NS_OUT=$(cd "$ROOT" && node --test --test-reporter=tap "$NODE_SMOKE"/*.test.mjs 2>&1)
+  # Разбираем только верхний уровень TAP: вложенные строки идут с отступом.
+  while IFS= read -r NS_LINE; do
+    case "$NS_LINE" in
+      "ok "*)     ok "${NS_LINE#*- }" ;;
+      "not ok "*)
+        # ОБЪЯСНЕНИЕ ОБЯЗАНО ДОЕХАТЬ. Первая редакция моста печатала только «не прошло» и совет
+        # запустить вручную — то есть отправляла гадать ровно там, где ответ уже был получен.
+        # Стоило это трёх кругов конвейера: проверка падала только на раннере, а сообщение
+        # утверждения оставалось в выводе, который мост выбрасывал. TAP кладёт его в блок после
+        # строки `not ok`, полем `error:`.
+        # TAP кладёт многострочное сообщение блочным скаляром: строка `error: |-`, а сам текст
+        # идёт следующими строками с отступом. Первая редакция брала только строку `error:` и
+        # печатала «|-» — то есть снова ничего.
+        NS_WHY=$(printf '%s\n' "$NS_OUT" | awk '
+          /^[[:space:]]+error:/ { inerr = 1; sub(/^[[:space:]]*error:[[:space:]]*/, ""); if ($0 != "|-" && $0 != "") print; next }
+          inerr && /^[[:space:]]+(code|stack|failureType|type|duration_ms):/ { inerr = 0 }
+          inerr && /^[[:space:]]*\.\.\.[[:space:]]*$/ { inerr = 0 }
+          inerr { sub(/^[[:space:]]+/, ""); print }
+        ' | head -6 | tr '\n' ' ')
+        bad "${NS_LINE#*- }" "${NS_WHY:-подробности: node --test $NODE_SMOKE/*.test.mjs}" ;;
+    esac
+  done <<EOF
+$(printf '%s\n' "$NS_OUT" | grep -E '^(ok|not ok) ')
+EOF
+fi
+
 # --- итог -------------------------------------------------------------------
 printf '\n'
 if [ "$FAIL" -eq 0 ]; then
@@ -1795,4 +1963,9 @@ else
 fi
 
 printf '  \033[2mне покрыто: СОДЕРЖАНИЕ документов (сверяется опись и структура, не текст),\n  установка с GitHub через npx\033[0m\n\n'
+
+# ИМЕНА УПАВШИХ — САМОЙ ПОСЛЕДНЕЙ СТРОКОЙ, и это не косметика. Прогон запускают гейтом, а вывод
+# упавшего гейта обрезается: видно голову и хвост. Значит единственное место, где список
+# гарантированно доедет до глаз, — конец. Проверено прогоном с нарочно сломанной проверкой.
+[ "$FAIL" -eq 0 ] || printf '  \033[31mупало: %s\033[0m\n\n' "$FAILED_NAMES"
 exit "$FAIL"

package/tool/selfcheck/units-cadence.mjs

@@ -0,0 +1,69 @@
+// Проверки каденции пробы. Написаны ДО кода.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ. Владелец сформулировал точнее, чем было в замысле: «команду, о которой надо
+// вспомнить, агент не вспомнит, а человек о ней не узнает». Это тот же класс, что файл, который
+// можно не прочитать, — и решать его надо так же: не напоминанием, а тем, что оно случается
+// само. Единица — коммиты, а не сутки: репозиторий, в котором месяц не работали, перепроверять
+// незачем, а сто коммитов за день перепроверить надо.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { probeDue, probeState, probeEvery, PROBE_EVERY } from "../lib/cadence.mjs";
+
+test("порог по умолчанию — сто коммитов, и он назван числом, а не спрятан", () => {
+  assert.equal(PROBE_EVERY, 100);
+});
+
+test("проба нужна, когда с прошлой прошло не меньше порога", () => {
+  assert.equal(probeDue({ at: 100 }, 199, 100), false);
+  assert.equal(probeDue({ at: 100 }, 200, 100), true);
+  assert.equal(probeDue({ at: 100 }, 350, 100), true);
+});
+
+// Пробы не было НИКОГДА — это не «свежая». Молчание здесь означало бы «всё прикрыто»,
+// а прикрыто ли — неизвестно.
+test("если пробы не было вовсе — она нужна", () => {
+  assert.equal(probeDue(null, 1, 100), true);
+  assert.equal(probeDue({}, 500, 100), true);
+});
+
+// История короче порога: проба всё равно нужна один раз, иначе новый репозиторий узнает,
+// чего он не видит, только на сто первом коммите.
+test("в молодом репозитории проба нужна сразу, а не после сотого коммита", () => {
+  assert.equal(probeDue(null, 3, 100), true);
+});
+
+test("счётчик коммитов неизвестен — состояние неизвестно, а не «свежо»", () => {
+  assert.equal(probeDue({ at: 10 }, null, 100), false);
+});
+
+// Состояние для человека и для агента: три исхода, и они не сливаются.
+test("состояние пробы: не делалась, устарела, свежая", () => {
+  assert.deepEqual(probeState(null, 40, 100), { state: "never", behind: null });
+  assert.deepEqual(probeState({ at: 10 }, 40, 100), { state: "fresh", behind: 30 });
+  assert.deepEqual(probeState({ at: 10 }, 210, 100), { state: "stale", behind: 200 });
+  assert.deepEqual(probeState({ at: 10 }, null, 100), { state: "unknown", behind: null });
+});
+
+// Порог — свойство ПРОЕКТА, а не наше: сто коммитов на репозитории с десятком коммитов в час
+// это трижды в день, а на редком проекте столько не наберётся никогда.
+test("порог берётся из манифеста, умолчание остаётся при пустом поле", () => {
+  assert.equal(probeEvery({ probe: "250" }), 250);
+  assert.equal(probeEvery({ probe: 250 }), 250);
+  assert.equal(probeEvery({}), PROBE_EVERY);
+  assert.equal(probeEvery(null), PROBE_EVERY);
+  assert.equal(probeEvery({ probe: "" }), PROBE_EVERY);
+});
+
+// Ноль — это «не делать», а не «делать всегда»: выключатель в манифесте нужен тому, кто не
+// может передать переменную окружения, — например конвейеру чужой площадки.
+test("ноль выключает пробу", () => {
+  assert.equal(probeEvery({ probe: 0 }), 0);
+  assert.equal(probeDue(null, 5, 0), true);
+});
+
+// Неразобранное значение обязано быть НАЗВАНО, а не подменено умолчанием: иначе в манифесте
+// написано одно, а происходит другое — ровно та тихая неправда, против которой весь комплект.
+test("непонятое значение порога — null, а не тихое умолчание", () => {
+  assert.equal(probeEvery({ probe: "часто" }), null);
+  assert.equal(probeEvery({ probe: -5 }), null);
+});