agent-quality-kit 0.15.0 → 0.16.0

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

@@ -6,9 +6,11 @@
 // Обратная сторона нашего же принципа: молчание неотличимо не только от успеха, но и от отказа.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync, writeFileSync, rmSync } from "node:fs";
+import { readFileSync, writeFileSync, rmSync, chmodSync } from "node:fs";
 import { join } from "node:path";
-import { project, aqk, aqkEnv } from "./_fixture.mjs";
+import { project, aqk, aqkEnv, tail } from "./_fixture.mjs";
+
+const plainText = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, "");
 
 test("прогон называет свой вердикт словами в обоих исходах", (t) => {
   const p = project(t, { "src/a.py": "def s():\n    return 1\n" });
@@ -30,14 +32,14 @@ test("прогон называет свой вердикт словами в о
   const red = aqk(p, "doctor", "--run");
   // Сообщение утверждения обязано нести ВЕСЬ хвост: проверка, которая говорит только «не
   // совпало», отправляет читателя гадать — ровно то, за что мы ругаем чужие проверки.
-  const redTail = red.out.trimEnd().split("\n").slice(-6).join("\n");
+  const redTail = tail(red.out);
   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");
+  const greenTail = tail(green.out);
   assert.equal(green.code, 0, `прогон остался красным:\n${greenTail}`);
   assert.match(greenTail, /зелён/, `успех не назван словами:\n${greenTail}`);
 });
@@ -126,3 +128,47 @@ test("в GitHub Actions упавший гейт даёт пометку у ст
   const local = aqkEnv(p, { GITHUB_ACTIONS: "" }, "doctor", "--run");
   assert.doesNotMatch(local.out, /^::error/m, "вне GitHub Actions пометок нет");
 });
+
+// ОТЧЁТ — ЭТО ЧТЕНИЕ, И ПАДАТЬ ЕМУ НЕ НА ЧЕМ.
+//
+// Разбор чужой интеграции 2026-09-16: `aqk report` в рабочей области, где `.aqk/` не создать,
+// упал с EROFS — не напечатав ничего. Команда, которая ТОЛЬКО рассказывает о состоянии,
+// перестала работать из-за побочного действия, о котором её не просили. Такие рабочие области
+// бывают не по недосмотру: read-only контейнер, чужой CI, каталог под ревью.
+//
+// Отчёт обязан уехать в stdout, а невозможность сохранить — быть названной, а не проглоченной:
+// человек, увидевший отчёт, вправе думать, что файл на диске, если ему не сказали иначе.
+// ПРОПУСК НА WINDOWS — С ПРИЧИНОЙ, А НЕ МОЛЧА. Там POSIX-права ничего не запрещают: каталог
+// с `chmod 0555` остаётся записываемым, отчёт сохраняется, и проверка краснеет на исправном
+// коде. Настоящий read-only там делается через `icacls` и ACL — это оснастка дороже самой
+// проверки. Пропуск назван вслух: «не смогли проверить» и «проверено» — разные слова, и
+// раннер печатает SKIP с этой причиной.
+test("report печатает отчёт и тогда, когда сохранить его некуда", (t) => {
+  // Пропуск через `t.skip`, а НЕ третьим аргументом `test(name, {skip}, fn)`. Форма с объектом
+  // законна в Node, но меняет сигнатуру вызова, и арбитр подгонки тестов прочитал это как
+  // «тест исчез» (checkwash, TEST_DISABLED). Спорить с чужим инструментом здесь нечем и незачем:
+  // привычная форма стоит дешевле, чем подавление находки, которое пришлось бы объяснять вечно.
+  if (process.platform === "win32") {
+    return t.skip("chmod 0555 на Windows прав не отнимает — каталог остаётся записываемым, проверить нечем");
+  }
+  const p = project(t, {
+    "AGENTS.md": "# вход\n",
+    ".aqk.yml": 'aqk: 1\nentry: [AGENTS.md]\nlang: ru\ngates:\n  ok: "true"\n',
+    "src/a.js": "export const a = 1;\n",
+  });
+  // Права возвращаются ЗДЕСЬ, а не через `t.after`: уборка фикстуры зарегистрирована раньше
+  // нашей и сносит каталог первой — на каталоге 0555 её `rmSync` падает сам, и проверка
+  // краснеет не тем, что проверяет. Поймано первым же прогоном.
+  let r;
+  chmodSync(p.dir, 0o555);
+  try { r = aqk(p, "report"); } finally { chmodSync(p.dir, 0o755); }
+  const out = plainText(r.out);
+  // Ищется НЕОБРАБОТАННОЕ падение — трассировка Node, — а не слово «EACCES»: код ошибки в
+  // сообщении «сохранить не смогли (EACCES)» стоит законно и человеку нужен. Первая версия
+  // этой проверки запрещала само слово и краснела на исправном выводе.
+  assert.doesNotMatch(out, /node:internal|\bat Object\.|\bthrow err\b/,
+    `команда упала вместо того, чтобы напечатать отчёт:\n${out.slice(0, 600)}`);
+  assert.match(out, /aqk report|Отчёт|отчёт/i, `отчёта в выводе нет:\n${out.slice(0, 600)}`);
+  assert.match(out, /сохранить|не записан|read-only|только для чтения/i,
+    `отчёт не сохранён, и об этом не сказано — человек решит, что файл на диске:\n${out.slice(-600)}`);
+});

package/tool/selfcheck/smoke/version-sync.test.mjs

@@ -0,0 +1,140 @@
+// tool/selfcheck/smoke/version-sync.test.mjs — ВЕРСИЯ ОБЪЯВЛЕНА В ПЯТИ МЕСТАХ, И ОНИ ОБЯЗАНЫ
+// СОВПАДАТЬ.
+//
+// ЗАЧЕМ. Выпуск поднимает номер руками в `package.json`, обоих README (`rev:` для pre-commit и
+// `uses: …@vX` для действия), `llms.txt` и манифесте плагина. Пять мест, одно знание, и ни одно
+// из них до сегодня не сторожила машина: забытая строка в README означает, что человек закрепит
+// `v0.14.0` на день после выхода 0.15.0 и не получит ни одной правки, а забытая строка в манифесте
+// плагина — что витрина Claude Code раздаёт версию, которой уже нет.
+//
+// Ровно тот класс, ради которого написан весь комплект: утверждение («это версия 0.15.0»), которое
+// никто не проверяет. Найдено 2026-09-14, когда к четырём местам добавилось пятое.
+//
+// ПОЧЕМУ НЕ «ЛЮБОЕ ЧИСЛО ВИДА vX.Y.Z». Ищем только строки, которые ОБЕЩАЮТ ТЕКУЩУЮ версию:
+// закрепление в примере установки. Номера в журнале изменений — это история, они обязаны
+// оставаться прежними, и требовать от них свежести значило бы переписывать прошлое.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const read = (rel) => readFileSync(join(ROOT, rel), "utf8");
+
+const VERSION = JSON.parse(read("package.json")).version;
+
+// Каждое место — файл и то, чем из него достаётся ОБЕЩАНИЕ версии. Список здесь, а не в коде
+// выпуска: список, который знает только тот, кто выпускает, живёт в его памяти, а не в машине.
+const PLACES = [
+  { file: "README.md", why: "закрепление pre-commit и действия в примере установки" },
+  { file: "README.ru.md", why: "то же по-русски" },
+  { file: "llms.txt", why: "выжимка для агента: `uses: …@vX.Y.Z`" },
+];
+
+test(`версия в package.json — ${VERSION}, и она непустая`, () => {
+  assert.match(VERSION, /^\d+\.\d+\.\d+$/, `странный номер версии: ${VERSION}`);
+});
+
+for (const { file, why } of PLACES) {
+  test(`«${file}» обещает текущую версию (${why})`, () => {
+    const text = read(file);
+    const pinned = [...text.matchAll(/v(\d+\.\d+\.\d+)/g)].map((m) => m[1]);
+    assert.ok(pinned.length, `в ${file} нет ни одного закрепления вида vX.Y.Z — пример установки исчез?`);
+    const stale = [...new Set(pinned.filter((v) => v !== VERSION))];
+    assert.equal(stale.length, 0,
+      `${file} закрепляет ${stale.join(", ")}, а пакет уже ${VERSION}: человек, скопировавший ` +
+      `пример, получит старую версию и ни одной правки из новой`);
+  });
+}
+
+// Манифест плагина — пятое место, и самое тихое: его читает витрина Claude Code, а не человек.
+// Расхождение здесь никто не заметит глазами.
+test("манифест плагина обещает ту же версию", () => {
+  const man = JSON.parse(read("plugin/.claude-plugin/plugin.json"));
+  assert.equal(man.version, VERSION,
+    `плагин объявляет ${man.version}, пакет ${VERSION}: витрина будет раздавать версию, ` +
+    "которой в npm уже нет. Обновления у плагина приходят только по смене этого поля");
+});
+
+// Плагин — тонкая обёртка над той же программой, и она не имеет права разойтись с ней. Если
+// когда-нибудь здесь появится собственная логика, эта проверка о ней скажет.
+test("плагин остаётся обёрткой: команды зовут ту же программу из реестра", () => {
+  const hooks = read("plugin/hooks/hooks.json");
+  assert.match(hooks, /agent-quality-kit/, "хук плагина зовёт не наш пакет");
+  assert.doesNotMatch(hooks, /node\s+\//, "в хук плагина попал абсолютный путь — у чужого его нет");
+});
+
+// РАЗМЕР ПАКЕТА — ЧИСЛО, КОТОРОЕ ДО СЕГОДНЯ НЕ СТОРОЖИЛ НИКТО, и оно врало трижды: «230 КБ» в
+// core.mjs при настоящих 692, «574.1 kB» в обоих README при тех же 692. В самом README рядом
+// стояла честная приписка «это число не сторожит никто» — вот она и есть признание, что
+// утверждение без арбитра живёт ровно до первой правки.
+//
+// СВЕРЯЕТСЯ ОКРУГЛЁННОЕ до десятой доли мегабайта: точный байт меняется от версии npm и от
+// сжатия, и требовать его совпадения значило бы получить красное на пустом месте. А вот переход
+// через десятую долю — это уже рост, о котором человек обязан узнать и либо признать его в
+// тексте, либо остановить.
+test("обещанный в README размер пакета совпадает с настоящим", () => {
+  // WINDOWS, ДВА ШАГА, И ОБА ПОЙМАЛ КОНВЕЙЕР В ДЕНЬ НАПИСАНИЯ ПРОВЕРКИ. Сперва `npm` дал
+  // ENOENT — там программа называется `npm.cmd`. Потом `npm.cmd` дал EINVAL: Node отказывается
+  // запускать `.cmd` без оболочки, это его защита от подстановки через аргументы. Значит
+  // оболочка нужна, и она здесь безопасна: доводы постоянные, снаружи в них ничего не приходит.
+  // Тот же класс, что записан у нас про `bash` в execution.mjs, — и снова на Linux его не видно.
+  const win = process.platform === "win32";
+  const out = execFileSync(win ? "npm.cmd" : "npm", ["pack", "--dry-run", "--json"],
+    { cwd: ROOT, encoding: "utf8", shell: win });
+  const bytes = JSON.parse(out)[0].size;
+  const real = (Math.round(bytes / 1024 / 1024 * 10) / 10).toFixed(1);
+  for (const [file, re] of [["README.md", /≈([\d.]+) MB/], ["README.ru.md", /≈([\d,]+) МБ/]]) {
+    const m = re.exec(read(file));
+    assert.ok(m, `в ${file} нет обещания размера пакета — строка «≈… МБ» пропала`);
+    const said = m[1].replace(",", ".");
+    assert.equal(said, real,
+      `${file} обещает ≈${said} МБ, а пакет весит ${real} МБ (${bytes} байт). ` +
+      "Либо поправьте текст, либо остановите рост — молча расходиться этим двум нельзя");
+  }
+});
+
+// УСТАНОВКА ПЛАГИНА — ЕЩЁ ОДНО ОБЕЩАНИЕ БЕЗ АРБИТРА, и оно уже соврало. Найдено 2026-09-14:
+// `plugin/README.md` — файл, который человек видит первым, открыв папку плагина на GitHub, —
+// велел `/plugin marketplace add anthropics/claude-plugins-community` и
+// `/plugin install aqk@claude-community`. В той витрине нас нет: заявка туда даже не подана.
+// То есть пришедший по нашей же ссылке получал бы «плагин не найден» — и уходил, решив, что
+// сломан инструмент, а не строчка в документации.
+//
+// Класс тот же самый, ради которого написан комплект: утверждение, выглядящее рабочим, потому
+// что его никто не пробовал. Здесь его держит машина: витрина названа в `marketplace.json`,
+// и всякая напечатанная команда установки обязана называть ЕЁ.
+test("всякая напечатанная команда установки ведёт в существующую витрину", () => {
+  const market = JSON.parse(read(".claude-plugin/marketplace.json"));
+  const names = market.plugins.map((p) => p.name);
+  const repo = "arsen-ask-lx/Agent_Quality_Kit";
+
+  // Перебираем ТО, ЧТО ЛЕЖИТ В РЕПОЗИТОРИИ, а не заранее выписанный список файлов: список
+  // пришлось бы помнить человеку, а забытый файл — это ровно тот файл, который соврёт.
+  //
+  // КРОМЕ ЗАПИСЕЙ О ПРОШЛОМ. Журнал шишек и разборы ЦИТИРУЮТ неверную команду — в этом их работа:
+  // запись от 2026-09-14 приводит дословно ту строку, которая вела в чужую витрину. Требовать от
+  // истории свежести значит переписывать её, и это тот же довод, что абзацем выше про номера
+  // версий в журнале изменений. Здесь проверяется то, что читатель воспримет как УКАЗАНИЕ.
+  const HISTORY = ["incidents/", "research/", "CHANGELOG.md"];
+  const files = execFileSync("git", ["ls-files", "-z", "*.md", "*.txt"], { cwd: ROOT, encoding: "utf8" })
+    .split("\0").filter(Boolean)
+    .filter((f) => !HISTORY.some((h) => f.startsWith(h)));
+
+  const bad = [];
+  for (const f of files) {
+    const text = read(f);
+    for (const m of text.matchAll(/\/plugin\s+marketplace\s+add\s+([\w./-]+)/g)) {
+      if (m[1] !== repo) bad.push(`${f}: витрина «${m[1]}», а наша — ${repo}`);
+    }
+    for (const m of text.matchAll(/\/plugin\s+install\s+([\w.-]+)@([\w.-]+)/g)) {
+      if (!names.includes(m[1])) bad.push(`${f}: плагин «${m[1]}», а в витрине ${names.join(", ")}`);
+      if (m[2] !== market.name) bad.push(`${f}: витрина «${m[2]}», а называется она «${market.name}»`);
+    }
+  }
+  assert.equal(bad.length, 0,
+    "команда установки ведёт туда, где нас нет — пришедший получит «плагин не найден»:\n" +
+    bad.map((b) => "  · " + b).join("\n"));
+});

package/tool/selfcheck/smoke.sh

@@ -44,6 +44,62 @@ bad()  { printf '  \033[31m✘\033[0m  %s\n' "$1"; printf '      %s\n' "${2:-}";
 # потому что памятку третий раз забудут ровно так же, как забыли второй.
 node_in() { D="$1"; shift; ( cd "$D" && node "$@" ); }
 
+# ПРЕДПОЛЁТ: МОЖНО ЛИ ВООБЩЕ МЕРИТЬ.
+#
+# Чужой разбор 2026-09-16: этот файл, запущенный в песочнице Codex, дал 15 падений из 123.
+# Настоящая причина — дочерним процессам Node запрещалось запускать git и npm, `spawnSync`
+# возвращал EPERM. Проверки об этом не знали и печатали обычные кресты; человек час разбирал
+# несуществующие дефекты, а «дефекты AQK 0.15.0» уехало в чужой отчёт.
+#
+# ИРОНИЯ, РАДИ КОТОРОЙ ЭТО НАПИСАНО. `tool/lib/execution.mjs` различает три исхода —
+# clean · finding · infra_error — ровно затем, чтобы сбой инструмента не выдавался за приговор
+# коду. Своей собственной оснастке мы это правило не применили.
+#
+# ОТКАЗ ЦЕЛИКОМ, А НЕ ЧАСТИЧНЫЙ ПРОГОН. 108 зелёных из 123 при недоступном git — это не «почти
+# всё хорошо», это «мерить было нечем»; такое число вводит в заблуждение сильнее, чем молчание.
+# Код возврата 3 — тем же pytest отделяет INTERNAL_ERROR от провала теста (у него провал это 1).
+#
+# СПРАШИВАЕМ ТОГО ЖЕ, КОГО СПРОСИТ ПРОГОН. Мало проверить git в этом шелле: ломалось именно у
+# подпроцессов Node, и предполёт, смотрящий только на шелл, прошёл бы, а кресты пришли следом.
+preflight() {
+  WHY=""
+  PT="$(mktemp -d 2>/dev/null)" || WHY="mktemp не создаёт временный каталог"
+  if [ -z "$WHY" ]; then
+    git init -q "$PT" >/dev/null 2>&1 || WHY="git init не отработал — без него большинство проверок меряет пустоту"
+    rm -rf "$PT"
+  fi
+  if [ -z "$WHY" ]; then
+    #
+    # ЧЕРЕЗ ОБОЛОЧКУ НА WINDOWS. Поймано конвейером в первый же прогон: `npm` там — это
+    # `npm.cmd`, и `spawnSync("npm")` без оболочки даёт ENOENT на исправной машине. Предполёт
+    # отказал на windows-задании, то есть сам стал тем ложным красным, против которого написан.
+    # Приём в комплекте уже дважды применён — `vitals.mjs` (shell при win32) и
+    # `smoke/version-sync.test.mjs` (`npm.cmd`); здесь он был потерян.
+    ERR=$(node -e '
+      const { spawnSync } = require("node:child_process");
+      const win = process.platform === "win32";
+      for (const p of ["git", "npm"]) {
+        const r = spawnSync(p, ["--version"], { encoding: "utf8", shell: win });
+        if (r.error || r.status !== 0) {
+          console.error(p + ": " + (r.error ? r.error.code : "код " + r.status));
+          process.exit(1);
+        }
+      }
+    ' 2>&1) || WHY="из подпроцесса Node не запускается то, чем мы меряем — $ERR"
+  fi
+  [ -z "$WHY" ] && return 0
+  printf '\n  \033[33m~\033[0m  прогон невозможен: %s\n' "$WHY"
+  printf '      Это НЕ «проверки упали»: мерить было нечем, и частичный прогон ничего не доказывает.\n'
+  printf '      Код возврата 3 — «не смогли проверить», как INTERNAL_ERROR у pytest.\n\n'
+  return 1
+}
+
+preflight || exit 3
+if [ "${1:-}" = "--preflight-only" ]; then
+  printf '  предполёт пройден: git и npm доступны и шеллу, и подпроцессам Node\n'
+  exit 0
+fi
+
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 
@@ -101,7 +157,7 @@ fi
 for f in .aqk.yml AGENTS.md CLAUDE.md; do
   [ -f "$f" ] || bad "не создан обязательный файл" "$f"
 done
-for n in general.md index.md project-baseline.md; do
+for n in general.md index.md project-baseline.md operational-gates.md; do
   find .aqk -type f -name "$n" | grep -q . || bad "не создан обязательный файл" "$n"
 done
 ok "обязательные файлы на месте"
@@ -1706,6 +1762,52 @@ else
 fi
 rm -rf "$VITP"
 
+# --- 112. vitals: чужой хук не выдаётся за подключённый AQK -------------------
+# Разбор живой интеграции 2026-09-16: в репозитории стоял диспетчер фреймворка pre-commit, AQK
+# из него не вызывался ни разу, а `vitals` печатал «хук pre-commit прописан в .git/hooks».
+# Человек прочитал это как «обвязка на месте». Проверялось ИМЯ в теле хука (`/pre-commit|aqk/i`),
+# а слово «pre-commit» у такого хука есть всегда. Наш собственный класс «объявлено ≠ работает».
+#
+# Проверяются три конца сразу, иначе починка соврёт в обратную сторону: чужой хук; наш хук,
+# подключённый через `.pre-commit-config.yaml` (там в .git/hooks лежит диспетчер, а решает
+# конфиг); прямой вызов в теле хука.
+HKP="$(mktemp -d)"
+( cd "$HKP" && git init -q . && printf '# вход
+' > AGENTS.md &&
+  printf 'aqk: 1
+entry: [AGENTS.md]
+lang: ru
+gates:
+  ok: "true"
+' > .aqk.yml &&
+  printf '#!/usr/bin/env bash
+# File generated by pre-commit: https://pre-commit.com
+ARGS=(hook-impl --hook-type=pre-commit)
+' > .git/hooks/pre-commit &&
+  chmod +x .git/hooks/pre-commit ) >/dev/null 2>&1
+HK_OTHER=$( cd "$HKP" && AQK_LANG=ru node "$CLI" vitals 2>&1 )
+( cd "$HKP" && printf 'repos:
+  - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
+    rev: v0.15.0
+    hooks:
+      - id: aqk
+' > .pre-commit-config.yaml )
+HK_OURS=$( cd "$HKP" && AQK_LANG=ru node "$CLI" vitals 2>&1 )
+( cd "$HKP" && rm -f .pre-commit-config.yaml &&
+  printf '#!/usr/bin/env bash
+exec aqk doctor --run --min 1 --brief
+' > .git/hooks/pre-commit )
+HK_DIRECT=$( cd "$HKP" && AQK_LANG=ru node "$CLI" vitals 2>&1 )
+if printf '%s' "$HK_OTHER" | grep -q "AQK в нём не вызывается" &&
+   ! printf '%s' "$HK_OURS" | grep -q "AQK в нём не вызывается" &&
+   ! printf '%s' "$HK_DIRECT" | grep -q "AQK в нём не вызывается"; then
+  ok "vitals: чужой хук назван чужим, наш — нашим, и оба пути подключения сочтены"
+else
+  bad "vitals путает чужой хук с подключённым AQK" \
+      "чужой: $(printf '%s' "$HK_OTHER" | grep -c 'не вызывается'), через конфиг: $(printf '%s' "$HK_OURS" | grep -c 'не вызывается'), прямой: $(printf '%s' "$HK_DIRECT" | grep -c 'не вызывается')"
+fi
+rm -rf "$HKP"
+
 # --- 106. совещательный гейт назван всегда и не роняет прогон никогда ---------
 # Два отказа, найденные 2026-09-09 сверкой документации с кодом. ПЕРВЫЙ: зелёный совещательный
 # печатался обычной галочкой — гейт, который уронить сборку НЕ МОЖЕТ, по выводу неотличим от
@@ -1784,7 +1886,7 @@ else
 fi
 rm -rf "$PRVP"
 
-# --- 104. опись в AGENTS.md покрывает все исходники ---------------------------
+# --- 104. опись в MAP.md покрывает все исходники ------------------------------
 # AGENTS.md — первое, что читает агент, и раздел «Где что лежит» для него карта. Карта,
 # отставшая от дерева, хуже её отсутствия: агент уверен, что видел всё. Проверено 2026-09-09 —
 # в описи не было восьми файлов из четырнадцати добавленных за неделю (`brief.mjs`, `banner.mjs`
@@ -1793,12 +1895,12 @@ rm -rf "$PRVP"
 MISSING=""
 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"
+  grep -qF "$B" "$ROOT/MAP.md" || MISSING="$MISSING $B"
 done
 if [ -z "$MISSING" ]; then
   ok "опись «Где что лежит» называет каждый исходник"
 else
-  bad "AGENTS.md не называет файлы" "$MISSING"
+  bad "MAP.md не называет файлы" "$MISSING"
 fi
 
 # --- 105. два README не расходятся структурно --------------------------------

package/tool/selfcheck/units-execution.mjs

@@ -17,7 +17,7 @@
 // рядом с инструментом — нормализующим адаптером, а протокол остаётся простым.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { classify, findingCodes, gitBash, launchable, gateCommand } from "../lib/execution.mjs";
+import { classify, findingCodes, gitBash, launchable, gateCommand, gateTimeout, GATE_TIMEOUT_DEFAULT } from "../lib/execution.mjs";
 
 // Вход — то, что отдаёт spawnSync: { status, signal, error }.
 const R = (over = {}) => ({ status: 0, signal: null, error: undefined, ...over });
@@ -163,3 +163,39 @@ test("Windows: команда гейта со словом bash отвечает
   assert.equal(r.status, 0, r.stderr);
   assert.match(r.stdout, /MINGW|MSYS/, `ответил не Git Bash: ${r.stdout}`);
 });
+
+// СКОЛЬКО ЖДАТЬ ЧУЖУЮ КОМАНДУ — ОДНО ЗНАНИЕ, А НЕ ПЯТЬ КОПИЙ.
+//
+// До 2026-09-16 число 300000 было вписано в четырёх местах: run.mjs, prove.mjs и дважды в
+// gates.mjs. Это не похожие строки, а одно знание в четырёх файлах, и правится оно по одному.
+//
+// СПОСОБ РЕШИТЬ ИНАЧЕ ОБЯЗАН БЫТЬ. Он записан в соседнем файле про выбор bash: «у всего, что мы
+// решаем сами, обязан быть способ решить иначе». У таймаута его не было, и живой проект с
+// verify-прогоном длиннее пяти минут просто выкинул свою главную проверку из манифеста.
+//
+// ПЯТЬ МИНУТ ПО УМОЛЧАНИЮ НЕ ВЫДУМАНЫ: у SonarQube SONAR_QUALITY_GATE_TIMEOUT ровно 300 секунд.
+// Переопределение переменной среды — тоже их способ, и GitLab делает так же
+// (RUNNER_AFTER_SCRIPT_TIMEOUT). Поля «timeout» у команды нет ни у lefthook, ни у pre-commit,
+// поэтому в манифест мы его не заводим: соглашения нет, а просьба была одна.
+test("без переменной среды — прежние пять минут", () => {
+  assert.equal(gateTimeout({}).ms, GATE_TIMEOUT_DEFAULT);
+  assert.equal(GATE_TIMEOUT_DEFAULT, 300000);
+  assert.equal(gateTimeout({ AQK_GATE_TIMEOUT: "" }).ms, GATE_TIMEOUT_DEFAULT);
+});
+
+test("переменная задаёт срок в секундах", () => {
+  assert.equal(gateTimeout({ AQK_GATE_TIMEOUT: "900" }).ms, 900000);
+  assert.equal(gateTimeout({ AQK_GATE_TIMEOUT: " 60 " }).ms, 60000);
+});
+
+// МУСОР НЕ ПРЕВРАЩАЕТСЯ В «БЕЗ ПРЕДЕЛА». Ноль или буквы в NaN дали бы spawnSync поведение
+// «ждать вечно» — то есть висящий гейт вместо честного «не смогли проверить». И молчать об
+// этом нельзя: человек задал переменную и ждёт от неё действия.
+test("мусор в переменной — прежний срок и слово об этом, а не вечное ожидание", () => {
+  for (const bad of ["abc", "0", "-5", "NaN", "1e999"]) {
+    const t = gateTimeout({ AQK_GATE_TIMEOUT: bad });
+    assert.equal(t.ms, GATE_TIMEOUT_DEFAULT, `«${bad}» изменило срок`);
+    assert.equal(t.ok, false, `«${bad}» принято за исправное значение`);
+    assert.equal(t.raw, bad);
+  }
+});

package/tool/selfcheck/units-level.mjs

@@ -10,7 +10,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { commandFor, verdict } from "../lib/prove.mjs";
-import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS, parseManifest, coversOf, coversUnproven, unparsedLines } from "../lib/manifest.mjs";
+import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS, parseManifest, coversOf, coversUnproven, unparsedLines, gateRequires } from "../lib/manifest.mjs";
 import { pickLang, langFromText, langFromDocs } from "../i18n/index.mjs";
 import { progress, selectGates } from "../lib/run.mjs";
 
@@ -415,3 +415,43 @@ test("выбор гейтов: без флагов гоняется всё, ка
   assert.equal(s.run.length, 2);
   assert.deepEqual(s.skipped, []);
 });
+
+// ЧЕМ ГЕЙТ РАБОТАЕТ — МОЖЕТ СКАЗАТЬ И САМ ПРОЕКТ, НЕ ТОЛЬКО ЗАПИСЬ КАТАЛОГА.
+//
+// Разбор чужой интеграции 2026-09-16: гейт объявлен как
+// `docker run --rm … promtool test rules …`. `vitals` смотрит ПЕРВОЕ СЛОВО, находит `docker` и
+// говорит «инструменты на месте». Поле `requires` для такого случая у нас уже есть — но
+// читалось оно только из `<samples>/<гейт>/gate.yml`, то есть было доступно нашим записям и
+// недоступно гейтам проекта. У проекта с чужими командами `samples` пуст по построению, и
+// сказать «этому гейту нужен docker» было нечем.
+//
+// СНАРУЖИ СОГЛАШЕНИЯ НЕТ — проверено 2026-09-16. У pre-commit ровно эта просьба (issue #2042:
+// трактовать `additional_dependencies` как список программ в $PATH и пропускать хук, если
+// программы нет) закрыта нерешённой: `system`-хуки окружения не ставят. У lefthook такого поля
+// нет вовсе. Поэтому мы не копируем чужую форму, а распространяем СВОЮ, уже существующую, —
+// и это сказано вслух, а не выдано за общепринятое.
+test("requires в манифесте проекта называет программу гейта", async () => {
+  const man = parseManifest('gates:\n  rules: "docker run x"\nrequires:\n  rules: docker\n');
+  assert.deepEqual(await gateRequires(man, "", "rules", () => false), ["docker"]);
+  assert.equal(await gateRequires(man, "", "rules", () => true), null, "программа на месте — жаловаться не на что");
+});
+
+test("requires принимает и список, и перечисление через запятую", async () => {
+  const list = parseManifest('gates:\n  g: "x"\nrequires:\n  g: [docker, jq]\n');
+  assert.deepEqual(await gateRequires(list, "", "g", () => false), ["docker", "jq"]);
+  const csv = parseManifest('gates:\n  g: "x"\nrequires:\n  g: docker, jq\n');
+  assert.deepEqual(await gateRequires(csv, "", "g", () => false), ["docker", "jq"]);
+});
+
+// Гейт, про который в манифесте ничего не сказано, остаётся как был: молчание — не требование.
+test("без requires поведение прежнее", async () => {
+  const man = parseManifest('gates:\n  g: "x"\n');
+  assert.equal(await gateRequires(man, "", "g", () => false), null);
+  assert.equal(await gateRequires(null, "", "g", () => false), null);
+});
+
+// Иначе `doctor` напечатает «неизвестное поле» на том, что сам же и читает.
+test("requires — известное поле манифеста", () => {
+  assert.ok(KNOWN_KEYS.includes("requires"));
+  assert.deepEqual(unknownKeys({ requires: { g: "docker" } }), []);
+});

package/tool/selfcheck/units-repo.mjs

@@ -327,3 +327,78 @@ test("свод в AGENTS.md виден Claude Code только через CLAUD
   assert.equal(claudeSeesRules({ ...base, claude: "x", claudeLink: true }), null, "ссылка на AGENTS.md — тот же файл");
   assert.equal(claudeSeesRules({ ...base, agents: false, dotClaude: true }), null, "AGENTS.md нет — подключать нечего");
 });
+
+// --- проверка, которая у проекта есть и не может провалиться -----------------------
+//
+// САМЫЙ ЦЕННЫЙ ОТВЕТ В ПЕРВЫЕ ПЯТЬ СЕКУНД, и до 2026-09-14 мы его не давали. `doctor` читал
+// ИМЯ скрипта («test», «lint») и печатал каноничную команду `npm test` с зелёной галочкой,
+// ни разу не заглянув в ТЕЛО скрипта. А выключатель стоит именно там: `node --test || true`.
+// То есть на репозитории, где выключено всё, мы говорили «у вас уже есть 2 проверки» —
+// ровно та ошибка, ради которой написан весь комплект, в нашем собственном первом экране.
+//
+// ГРАНИЦА НАМЕРЕННО УЗКАЯ, и она взята у гейта `ci-actually-fails`: `|| true` в СЕРЕДИНЕ
+// команды — это идемпотентность вспомогательного шага (`mkdir -p … || true`), а не выключенная
+// проверка. Красным делается только гашение, под которое попадает ВЕСЬ исход: в конце тела
+// либо флаг, у которого другого назначения нет.
+test("выключатель в теле скрипта виден, а не прячется за каноничной командой", () => {
+  const pkg = (scripts) => ({ "package.json": JSON.stringify({ scripts }) });
+  const one = (scripts) => proposeGates(pkg(scripts))[0];
+
+  assert.equal(one({ test: "node --test" }).weak, undefined, "рабочая проверка не должна обвиняться");
+  assert.equal(one({ test: "node --test || true" }).weak?.kind, "off", "«|| true» в конце гасит весь исход");
+  assert.equal(one({ test: "node --test || :" }).weak?.kind, "off");
+  assert.equal(one({ test: "node --test || exit 0" }).weak?.kind, "off");
+  assert.equal(one({ lint: "ruff check . --exit-zero" }).weak?.kind, "zero", "флаг, у которого нет другого назначения");
+  assert.equal(one({ test: 'echo "no tests yet"' }).weak?.kind, "stub", "заглушка проходит всегда");
+  assert.equal(one({ test: 'echo "Error: no test specified" && exit 1' }).weak, undefined,
+    "заготовка npm провалиться МОЖЕТ — обвинять её нельзя");
+
+  // Ложные, на которых узость границы и проверяется.
+  assert.equal(one({ test: "mkdir -p tmp || true && node --test" }).weak, undefined,
+    "гашение вспомогательного шага в середине — идемпотентность, а не выключенная проверка");
+  assert.equal(one({ test: "node --test # было || true" }).weak, undefined, "упоминание в комментарии — не выключатель");
+
+  // Своя строка доезжает до человека целиком: без неё он не поверит и не найдёт, что чинить.
+  assert.match(one({ test: "node --test || true" }).weak.text, /\|\| true/);
+});
+
+// ОБЪЯВЛЕННЫЙ ГЕЙТ НЕ ДЕЛАЕТ ЧУЖИЕ ПРОВЕРКИ НЕВИДИМЫМИ.
+//
+// ЗАМЕР 2026-09-16 по двенадцати чужим репозиториям. У шести зрелых (requests, httpx, fastapi,
+// black, express, flask) `doctor` без манифеста читал в их файлах от одной до трёх настоящих
+// проверок. Стоило объявить ОДИН гейт — блок «у вас уже есть» исчезал у всех шести, и итог
+// говорил «держит машина 0». То есть чем больше проект настроил, тем меньше мы о нём знали.
+//
+// Это ВТОРАЯ встреча с тем же классом: первый чужой пользователь 2026-09-08 назвал «применимо,
+// но не поставлено: 5» неправдой, и ответом стало поле `covers`. Оно заполняется руками — и в
+// зрелом проекте с двумя десятками записей его не заполнил никто. Лекарство, которое просит
+// человека делать то, что умеет машина, не работает.
+//
+// Сравнение — ПО КОМАНДЕ, а не по имени: имена гейтов у проекта свои (`project-verify`), и по
+// ним совпадения не будет никогда.
+test("чужие проверки видны и тогда, когда гейты уже объявлены", () => {
+  const files = { Makefile: "test:\n\tpytest -q\n\nlint:\n\truff check .\n" };
+  const got = proposeGates(files, ["bash scripts/verify.sh"]);
+  assert.deepEqual(got.map((g) => g.name).sort(), ["lint", "test"],
+    "объявленный гейт с ДРУГОЙ командой скрыл чужие проверки");
+});
+
+test("уже объявленная проверка второй раз не предлагается", () => {
+  const files = { Makefile: "test:\n\tpytest -q\n\nlint:\n\truff check .\n" };
+  const got = proposeGates(files, ["make test"]);
+  assert.deepEqual(got.map((g) => g.name), ["lint"], "`make test` объявлен, а мы советуем его снова");
+});
+
+// Обёртка снимается: человек пишет `bash scripts/check`, мы нашли `scripts/check` — это одно и
+// то же, и предлагать его второй раз значит советовать то, что уже стоит.
+test("обёртка bash/sh не мешает узнать объявленную команду", () => {
+  const got = proposeGates({ "scripts/check": "" }, ["bash scripts/check"]);
+  assert.deepEqual(got, [], "`bash scripts/check` и `scripts/check` не узнаны как одна команда");
+});
+
+// Пустой список объявленных — прежнее поведение до последней запятой: ничего не фильтруем.
+test("без объявленных гейтов список тот же, что и раньше", () => {
+  const files = { Makefile: "test:\n\tpytest -q\n" };
+  assert.deepEqual(proposeGates(files).map((g) => g.name), ["test"]);
+  assert.deepEqual(proposeGates(files, []).map((g) => g.name), ["test"]);
+});

package/tool/selfcheck/units-vitals.mjs

@@ -79,3 +79,30 @@ test("старая версия сообщается, но не роняет", (
   assert.match(v.detail, /0\.9\.0/);
   assert.equal(vitalsVerdict(rows), 0);
 });
+
+// ЧУЖОЙ ХУК — НЕ НАША ОБВЯЗКА. ЧЕТВЁРТОЕ СОСТОЯНИЕ, И ОНО ЗАРАБОТАНО.
+//
+// Разбор интеграции в живом проекте 2026-09-16: vitals печатал «хук pre-commit прописан в
+// .git/hooks», а AQK внутри этого хука не вызывался вовсе — там стоял диспетчер фреймворка
+// pre-commit. Человек прочитал строку как «обвязка на месте» и ушёл; на деле ни один коммит в
+// том репозитории AQK не запускал. Это ровно наш собственный класс «объявлено ≠ работает»,
+// только у нас самих, — и цена ему та же, что мы называем чужим инструментам.
+//
+// Как это делают снаружи: pre-commit узнаёт свой хук функцией `is_our_script()` — ищет в теле
+// файла собственный маркер (CURRENT_HASH и пять PRIOR_HASHES), а не имя. Имя чужого
+// инструмента в теле хука не значит ничего: у них же есть режим миграции, в котором рядом
+// живут оба хука сразу.
+test("хук стоит, но AQK в нём не вызывается — это не «подключено»", () => {
+  const rows = vitalsRows({ ...ok, preCommit: "other" });
+  const hook = rows.find((r) => r.key === "preCommit");
+  assert.notEqual(hook.ok, true, "чужой хук засчитан как подключённый AQK");
+  assert.match(hook.detail, /AQK|aqk/, `в строке не сказано, чего именно нет: ${hook.detail}`);
+
+  // И это НЕ то же самое, что «хука нет вовсе»: в одном случае ставить нечего, в другом —
+  // дописать строку в уже стоящий хук. Совет разный, значит и строки разные.
+  const none = vitalsRows({ ...ok, preCommit: false }).find((r) => r.key === "preCommit");
+  assert.notEqual(hook.detail, none.detail, "«хук чужой» и «хука нет» неразличимы по выводу");
+
+  // Чужой хук — не поломка: человек мог сознательно гонять AQK в конвейере.
+  assert.equal(vitalsVerdict(rows), 0, "команда кричит «сломано» про чужой выбор");
+});

package/kit/gates/entry-links-exist/README.md

@@ -1,27 +0,0 @@
-# Ссылки точки входа ведут на существующие файлы
-
-**Намерение.** Свод правил, который ссылается на несуществующий файл, утверждает то, чего нет.
-
-**Какой отказ это поймало.** В `audit_project` чек-лист гейтов четыре недели числил работающими
-изоляцию исполнителя и генерацию контрактов. Обе были отключены владельцем за три недели до
-этого — инструмент ломал файлы. Планирование опиралось на защиту, которой не существовало.
-Запись в журнале: `incidents/README.md`, 2026-08-24.
-
-**Почему машина, а не внимательность.** Расхождение появляется не в момент написания документа, а
-через недели, когда файл удалили в другой задаче. Человек в этот момент смотрит не сюда.
-
-**Готовый аналог есть и он сильнее.** `lychee` и `markdown-link-check` проверяют ещё и внешние
-адреса, и якоря внутри страницы. Рецепта под них в записи нет по устройству формата: рецепты
-выбираются **по языку проекта**, а эти инструменты к языку не привязаны. Если такой инструмент у
-вас стоит — он лучше нашего.
-
-**Адрес страницы сайта не считается битой ссылкой.** Путь, кончающийся косой чертой —
-`[руководство](tutorial/#install)`, — это адрес на опубликованном сайте, а не файл в
-репозитории. Так ссылаются mkdocs, docusaurus и jekyll. Найдено замером по `fastapi`: гейт
-объявлял битой рабочую ссылку из их README.
-
-**Чего НЕ ловит.** Только файлы `*.md` в самом каталоге, без обхода вложенных: намерение записи —
-точка входа, а не вся документация. Не проверяет внешние адреса (сеть) и якоря внутри файла.
-
-**Образцы.** `red/` — свод ссылается на `rules/nope.md`, которого нет: гейт обязан краснеть.
-`green/` — ссылается на существующий `rules/general.md`: гейт обязан молчать.