agent-quality-kit 0.14.0 → 0.16.0

package/tool/selfcheck/smoke/first-run.test.mjs

@@ -9,7 +9,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { project, aqk, run } from "./_fixture.mjs";
+import { project, aqk, run, tail } from "./_fixture.mjs";
 
 // Цвет снимается до разбора: заголовок жирный, значки цветные, и регулярка по сырому выводу
 // не узнаёт ни то, ни другое.
@@ -99,8 +99,8 @@ test("нет .aqk/docs и .aqk/rules — прогон всё равно зелё
   const man = join(p.dir, ".aqk.yml");
   writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m, 'gates:\n  тихий: "true"'), "utf8");
   const r = aqk(p, "doctor", "--run");
-  const tail = plain(r.out).trimEnd().split("\n").slice(-4).join("\n");
-  assert.equal(r.code, 0, `прогон покраснел из-за методичек:\n${tail}`);
+  const last = tail(plain(r.out), 4);
+  assert.equal(r.code, 0, `прогон покраснел из-за методичек:\n${last}`);
   assert.match(plain(r.out), /\.aqk\/docs/, "отсутствие методичек не названо вовсе");
 });
 
@@ -142,3 +142,67 @@ test("prompt: задание без прогона начинается с пр
   assert.match(r.out, /(Как проверить, что готово|How to verify)/);
   assert.doesNotMatch(r.out, /\x1b\[/, "задание уходит агенту текстом — без цветовых кодов");
 });
+
+// ВЫКЛЮЧЕННАЯ ПРОВЕРКА НАЗЫВАЕТСЯ ВЫКЛЮЧЕННОЙ — В ПЕРВЫЕ ПЯТЬ СЕКУНД.
+//
+// Найдено 2026-09-14 живым прогоном на репозитории, где выключено всё: `"test": "node --test ||
+// true"`, `"lint": "ruff check . --exit-zero"`, шаг конвейера под `continue-on-error`. `doctor`
+// печатал «Проверки, которые у вас УЖЕ ЕСТЬ (2)» с двумя ЗЕЛЁНЫМИ галочками: мы читали ИМЯ
+// скрипта и ни разу не заглядывали в его тело. Тот самый класс отказа, ради которого написан
+// комплект, — в нашем собственном первом экране.
+//
+// Это главная встреча постороннего с инструментом: ноль настройки, одна команда. Если здесь мы
+// подтверждаем ложное «у вас всё хорошо», второго запуска не будет.
+test("проверка, которую нельзя провалить, названа находкой, а не зелёной галочкой", (t) => {
+  const p = project(t, {
+    ...FILES,
+    "package.json": JSON.stringify({ name: "x", scripts: { test: "node --test || true", lint: "ruff check . --exit-zero" } }),
+  });
+  const out = plain(aqk(p, "doctor").out);
+  const block = out.slice(out.indexOf("УЖЕ ЕСТЬ"));
+  assert.ok(block, "блок «проверки, которые уже есть» пропал совсем");
+  assert.doesNotMatch(block.split("\n").slice(0, 3).join("\n"), /✔/,
+    `выключенная проверка получила зелёную галочку — это ложное «у вас всё хорошо»:\n${block.slice(0, 400)}`);
+  assert.match(block, /\|\| true/, "человеку не показали строку, по которой он найдёт выключатель у себя");
+  assert.match(block, /--exit-zero/, "флаг, гасящий исход, не назван");
+
+  // И то же знание — агенту: иначе он впишет дыру в манифест, и с этого дня за неё ручается машина.
+  const ctx = plain(aqk(p, "context").out);
+  assert.match(ctx, /покраснеть не могут/,
+    `блок для агента велит объявить проверки, которые не могут провалиться:\n${ctx.slice(0, 600)}`);
+});
+
+// ЗРЕЛЫЙ ПРОЕКТ НЕ ТЕРЯЕТ СВОИ ПРОВЕРКИ ИЗ ВИДА, КОГДА ОБЪЯВИЛ ГЕЙТ.
+//
+// Замер 2026-09-16 по двенадцати чужим репозиториям: у шести зрелых (requests, httpx, fastapi,
+// black, express, flask) блок «у вас уже есть» исчезал целиком, стоило объявить один гейт, —
+// и итог печатал «держит машина 0» проекту с настоящим pre-commit и Makefile. Чем больше
+// человек настроил, тем меньше мы о нём знали: условие показывало чужие проверки только тому,
+// у кого гейтов нет вовсе.
+test("объявленный гейт не прячет проверки, которые у проекта уже есть", (t) => {
+  const p = project(t, {
+    ...FILES,
+    Makefile: "test:\n\tpytest -q\n\nlint:\n\truff check .\n",
+    ".aqk.yml": 'aqk: 1\nentry: [AGENTS.md]\ngates:\n  project-verify: "bash scripts/verify.sh"\n',
+    "AGENTS.md": "# вход\n",
+  });
+  const out = plain(aqk(p, "doctor").out);
+  assert.match(out, /УЖЕ ЕСТЬ/,
+    `проект объявил один гейт — и его собственные проверки пропали из вывода:\n${out.slice(-1500)}`);
+  assert.match(out, /make test|npm test/, "найденная команда не названа человеку");
+});
+
+// И обратное: то, что УЖЕ объявлено, вторым списком не повторяется. Иначе вывод советует
+// поставить то, что стоит, — и человек перестаёт читать этот блок целиком.
+test("объявленная проверка не советуется второй раз", (t) => {
+  const p = project(t, {
+    ...FILES,
+    Makefile: "test:\n\tpytest -q\n",
+    ".aqk.yml": 'aqk: 1\nentry: [AGENTS.md]\ngates:\n  test: "make test"\n  lint: "npm run lint"\n',
+    "AGENTS.md": "# вход\n",
+  });
+  const out = plain(aqk(p, "doctor").out);
+  const block = out.includes("УЖЕ ЕСТЬ") ? out.slice(out.indexOf("УЖЕ ЕСТЬ")) : "";
+  assert.doesNotMatch(block.split("\n").slice(0, 6).join("\n"), /make test/,
+    `«make test» уже объявлен гейтом, а мы советуем его снова:\n${block.slice(0, 400)}`);
+});

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

@@ -0,0 +1,83 @@
+// Прогон, который не может состояться, обязан сказать это, а не показать пятнадцать крестов.
+//
+// НАЙДЕНО ЧУЖИМ РАЗБОРОМ 2026-09-16. `smoke.sh`, запущенный внутри песочницы 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).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const SMOKE = join(ROOT, "tool", "selfcheck", "smoke.sh");
+
+const WIN = process.platform === "win32";
+
+// Заглушка вместо настоящей программы: выходит кодом 126 — «найдено, но запустить нельзя».
+// Ровно то, чем для нас выглядел запрет песочницы.
+//
+// ДВА ФАЙЛА, А НЕ ОДИН. Поймано windows-заданием конвейера: скрипт без расширения там не
+// перехватывает ничего — CreateProcess ищет `.exe`/`.cmd` по PATHEXT, а Git Bash понимает
+// shebang. Значит нужны обе заглушки сразу, иначе проверка молча меряет настоящий git и
+// краснеет на исправной машине — то есть сама становится тем ложным красным, против которого
+// написан предполёт.
+function stubDir(t, name) {
+  const dir = mkdtempSync(join(tmpdir(), "aqk-stub-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  writeFileSync(join(dir, name), "#!/bin/sh\nexit 126\n", "utf8");
+  chmodSync(join(dir, name), 0o755);
+  if (WIN) writeFileSync(join(dir, `${name}.cmd`), "@echo off\r\nexit /b 126\r\n", "utf8");
+  return dir;
+}
+
+// PATH СОБИРАЕТСЯ ЧЕРЕЗ `delimiter`, А НЕ ЧЕРЕЗ ДВОЕТОЧИЕ. На Windows разделитель — точка с
+// запятой, а сам путь вида `C:\Users\…` содержит двоеточие внутри: строка `"C:\...:" + PATH`
+// разваливается на первом же символе, заглушка в PATH не попадает, и проверка меряет настоящий
+// git. Поймано windows-заданием дважды подряд — первый раз я починил вызов, а не сборку пути.
+const withStub = (dir) => (dir ? `${dir}${delimiter}${process.env.PATH}` : process.env.PATH);
+
+const runPreflight = (extraPath) => spawnSync("bash", [SMOKE, "--preflight-only"], {
+  encoding: "utf8", timeout: 60000,
+  env: { ...process.env, PATH: withStub(extraPath), AQK_LANG: "ru" },
+});
+
+test("предполёт: исправная машина проходит и ничего не ломает", () => {
+  const r = runPreflight(null);
+  assert.equal(r.status, 0, `предполёт отказал на исправной машине:\n${r.stdout}${r.stderr}`);
+});
+
+test("предполёт: недоступный git — это «не смогли проверить», а не падения проверок", (t) => {
+  const r = runPreflight(stubDir(t, "git"));
+  assert.equal(r.status, 3,
+    `код ${r.status}: запрет среды неотличим от провала проверок. Нужен 3 — тот же, которым pytest отделяет внутреннюю ошибку от провала теста`);
+  const out = `${r.stdout || ""}${r.stderr || ""}`;
+  assert.match(out, /git/i, "не сказано, ЧТО именно недоступно");
+  assert.doesNotMatch(out, /✘/, `предполёт напечатал крест — значит выдал сбой среды за находку:\n${out}`);
+});
+
+// Тот самый случай из отчёта: сам шелл git видит, а подпроцессы Node — нет. Проверять только
+// первое значило бы пройти предполёт и упасть пятнадцатью крестами следом.
+test("предполёт: git виден шеллу, но не подпроцессу Node — тоже отказ", (t) => {
+  const dir = stubDir(t, "git");
+  // `shell` — тот же, что в самом предполёте: на Windows без оболочки Node не видит ни `.cmd`
+  // заглушки, ни настоящего `npm`. Проверка обязана звать так же, как зовёт код, иначе она
+  // проверяет не его. Ровно на этом конвейер и поймал первую версию.
+  // Node зовётся НАПРЯМУЮ, без оболочки-посредника: подстановка пути в строку `bash -c` — это
+  // ещё один способ потерять заглушку, и именно так эта проверка уже ошиблась.
+  const probe = `const r=require("node:child_process").spawnSync("git",["--version"],{shell:${WIN}}); process.exit(r.status===0?0:3)`;
+  const r = spawnSync(process.execPath, ["-e", probe],
+    { encoding: "utf8", timeout: 30000, env: { ...process.env, PATH: withStub(dir) } });
+  assert.equal(r.status, 3, "оснастка проверки неверна: заглушка не перехватывает git у Node");
+});

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 не расходятся структурно --------------------------------