agent-quality-kit 0.14.0 → 0.16.0

package/tool/selfcheck/units-ask.mjs

@@ -0,0 +1,85 @@
+// tool/selfcheck/units-ask.mjs — КОГДА КОМПЛЕКТ ОБРАЩАЕТСЯ К ЧЕЛОВЕКУ: ограничитель обращений.
+//
+// ЗАЧЕМ ЭТОТ ФАЙЛ И ЭТОТ МОДУЛЬ. Знание «мы это человеку уже показывали» жило в комплекте
+// ДВАЖДЫ и по-разному: `~/.config/aqk/feedback-shown` — файл-флаг, раз на машину, заведён в
+// core.mjs и прочитан в project.mjs; `.aqk/advice-shown` и `.aqk/update-checked` — отметка
+// временем плюс `adviceDue()` на сутки, заведённые в brief.mjs. Одно решение — «не долби» — в
+// двух местах с двумя форматами хранения. Третье обращение (просьба об отзыве по делу) завело
+// бы третий формат, и дальше они расходятся молча: именно так и умирает ограничитель.
+//
+// Поэтому здесь один модуль на все обращения и таблица видов. Вид объявляет ДВЕ вещи, и обе
+// нельзя угадать по имени: где живёт отметка (проект или дом) и как часто можно повторять.
+//
+//   node --test tool/selfcheck/units-ask.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { askDue, askFile, ASKS, ASK_FILES } from "../lib/ask.mjs";
+import { RUNTIME_FILES } from "../lib/core.mjs";
+
+const NOW = Date.parse("2026-09-14T20:00:00Z");
+
+// --- «раз в сутки»: совет и проверка версии ----------------------------------
+// Тот же договор, что был у adviceDue, и он обязан остаться прежним: совет на каждом коммите
+// превращается в шум, а шум пролистывают вместе с настоящими находками.
+test("суточное обращение: не показывали — пора", () => {
+  assert.equal(askDue("advice", null, NOW), true);
+});
+
+test("суточное обращение: час назад — рано, сутки назад — пора", () => {
+  assert.equal(askDue("advice", "2026-09-14T19:00:00Z", NOW), false);
+  assert.equal(askDue("advice", "2026-09-13T19:00:00Z", NOW), true);
+});
+
+// Испорченная отметка — это «не знаем, когда показывали». Молчать из-за нечитаемого файла
+// состояния значит потерять обращение навсегда и не сказать почему.
+test("испорченная отметка читается как «не знаем» и обращение показывается", () => {
+  assert.equal(askDue("advice", "не дата", NOW), true);
+});
+
+// --- «один раз»: просьба об отзыве -------------------------------------------
+// Разовое обращение отличается от суточного не числом, а СМЫСЛОМ: его нельзя повторить никогда,
+// сколько бы времени ни прошло. Считать его «раз в очень много часов» — значит однажды получить
+// повтор у человека, который поставил комплект год назад.
+test("разовое обращение: без отметки — пора, с любой отметкой — никогда", () => {
+  assert.equal(askDue("install", null, NOW), true);
+  assert.equal(askDue("install", "shown\n", NOW), false);
+  assert.equal(askDue("install", "2020-01-01T00:00:00Z", NOW), false);
+  assert.equal(askDue("install", "мусор", NOW), false);
+});
+
+// --- опечатка в виде обращения -----------------------------------------------
+// Неизвестный вид обязан падать, а не превращаться в «показывать всегда» или «не показывать
+// никогда». Оба умолчания — молчаливый выбор за человека, и оба неверны в половине случаев.
+test("неизвестный вид обращения — отказ, а не тихое умолчание", () => {
+  assert.throws(() => askDue("опечатка", null, NOW), /опечатка/);
+  assert.throws(() => askFile("опечатка", { project: "/p", home: "/h" }), /опечатка/);
+});
+
+// --- где лежит отметка --------------------------------------------------------
+// Разовая на машину отметка НЕ ИМЕЕТ ПРАВА лежать в проекте: внутри `.aqk/` она либо уедет в
+// чужой git как наш мусор, либо пропадёт при `init --force` — и то и другое врёт о том, видел
+// человек обращение или нет. Довод записан в core.mjs с 2026-09; проверки у него не было.
+test("разовая на машину отметка лежит вне проекта", () => {
+  const p = askFile("install", { project: "/p", home: "/h" });
+  assert.ok(!p.startsWith("/p"), `отметка машины уехала в проект: ${p}`);
+  assert.ok(p.startsWith("/h"), `отметка машины легла мимо дома: ${p}`);
+});
+
+test("отметки про этот проект лежат в проекте", () => {
+  for (const kind of Object.keys(ASKS).filter((k) => ASKS[k].where === "project")) {
+    const p = askFile(kind, { project: "/p", home: "/h" });
+    assert.ok(p.startsWith("/p"), `${kind}: отметка проекта легла мимо проекта: ${p}`);
+  }
+});
+
+// --- СВЯЗЬ ДВУХ СПИСКОВ, КОТОРУЮ ИНАЧЕ НЕ СТОРОЖИТ НИКТО ----------------------
+// Отметка, лежащая в `.aqk/` и не названная в RUNTIME_FILES, не попадёт в .gitignore — и уедет
+// в чужой коммит. Это уже случалось с `.aqk/last-run.md` на живом проекте 2026-09-11, и оттуда
+// же взялся сам список. Список и таблица видов — два разных файла, и связь между ними держится
+// только этой проверкой.
+test("каждая отметка проекта названа в RUNTIME_FILES — иначе уедет в чужой git", () => {
+  for (const f of ASK_FILES) {
+    assert.ok(RUNTIME_FILES.includes(f),
+      `«${f}» не назван в RUNTIME_FILES: init не положит его в .gitignore, и отметка уедет в коммит`);
+  }
+});

package/tool/selfcheck/units-brief.mjs

@@ -8,7 +8,7 @@
 //   node --test tool/selfcheck/units-brief.mjs
 import test from "node:test";
 import assert from "node:assert/strict";
-import { briefLine, adviceDue, pickAdvice, updateNotice, updateWanted } from "../lib/brief.mjs";
+import { briefLine, pickAdvice, updateNotice, updateWanted } from "../lib/brief.mjs";
 import { CATALOGS } from "../i18n/index.mjs";
 
 const T = CATALOGS.ru;
@@ -35,18 +35,8 @@ test("невычисленный уровень не выдумывается",
 });
 
 // --- ограничитель совета -----------------------------------------------------
-// Совет на КАЖДОМ коммите превращается в шум, а шум пролистывают вместе с настоящими
-// находками. Раз в сутки — это заметно и не мешает.
-test("совет не повторяется чаще раза в сутки", () => {
-  const now = Date.parse("2026-09-08T20:00:00Z");
-  assert.equal(adviceDue(null, now), true, "первый раз показывается");
-  assert.equal(adviceDue("2026-09-08T19:00:00Z", now), false, "час назад — рано");
-  assert.equal(adviceDue("2026-09-07T19:00:00Z", now), true, "сутки прошли");
-});
-
-test("испорченная отметка времени не мешает показать совет", () => {
-  assert.equal(adviceDue("не дата", Date.parse("2026-09-08T20:00:00Z")), true);
-});
+// Сам ограничитель переехал в `ask.mjs` — он общий на все обращения комплекта к человеку, и
+// проверки на него лежат в units-ask.mjs. Здесь остаётся то, что про краткий режим.
 
 // --- выбор совета ------------------------------------------------------------
 // Один совет за раз, а не список: список читается как «у вас всё плохо» и не помогает выбрать.

package/tool/selfcheck/units-context.mjs

@@ -9,7 +9,8 @@
 //   node --test tool/selfcheck/units-context.mjs
 import test from "node:test";
 import assert from "node:assert/strict";
-import { contextBlock, countArbiters, parseLastRun, withHook, hasOurHook, portableSelf, nextSteps } from "../commands/context.mjs";
+import { contextBlock, countArbiters, withHook, hasOurHook, portableSelf, nextSteps } from "../commands/context.mjs";
+import { parseLastRun } from "../lib/run.mjs";
 import { CATALOGS } from "../i18n/index.mjs";
 import { commandRows } from "../lib/core.mjs";
 import { readFile } from "node:fs/promises";

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-feedback.mjs

@@ -0,0 +1,137 @@
+// tool/selfcheck/units-feedback.mjs — О ЧЁМ комплект просит человека и что кладёт в отчёт.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ. Замер 2026-09-14: 1342 скачивания в неделю в npm, из них ни одного
+// пользователя — версии качаются равномерно, включая прожившую двадцать пять минут, то есть это
+// зеркала и сканеры. На GitHub за две недели семь уникальных посетителей, две звезды, ноль чужих
+// комментариев за всё время. Обратной связи нет не потому, что люди молчат, — её не у кого
+// просить, и просить мы не умеем: единственная просьба печаталась при `init`, то есть ДО того,
+// как комплект сделал хоть что-то полезное.
+//
+// ПОЭТОМУ ЗДЕСЬ ДВЕ ЧИСТЫЕ ФУНКЦИИ И ДВА ПРАВИЛА.
+//   1. Просим, ТОЛЬКО когда есть что рассказать. «Оставьте отзыв» без содержания — шум, а шум
+//      выключают вместе с хуком, в котором он приехал. Самое ценное — «AQK не смог»: жалоба
+//      даётся людям легче похвалы, и она же говорит нам, где инструмент врёт.
+//   2. Отчёт не несёт ни путей, ни кода. Человек отправляет его сам, и он обязан видеть глазами
+//      всё, что отправляет, — иначе первый же внимательный читатель назовёт это телеметрией.
+//
+//   node --test tool/selfcheck/units-feedback.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { feedbackAsk, reportText, issueUrl, askLine, feedbackWanted } from "../commands/feedback.mjs";
+
+// --- о чём просим ------------------------------------------------------------
+
+// Рассказывать нечего — не просим. Это главное правило: просьба без содержания превращает
+// ограничитель в шум, а следующую просьбу — в то, что пролистывают не читая.
+test("сказать нечего — просьбы нет", () => {
+  assert.equal(feedbackAsk({ cannot: [], blind: [], red: [] }), null);
+  assert.equal(feedbackAsk({}), null);
+});
+
+// «Не смогли проверить» — самое ценное, что у нас бывает: это отказ прибора, а не находка о
+// коде. Такое человек рассказывает охотнее, чем похвалу, и чинить надо именно это.
+test("«не смогли проверить» важнее всего остального", () => {
+  const a = feedbackAsk({ cannot: ["smoke"], blind: ["swallowed-error"], red: ["lint"] });
+  assert.equal(a.reason, "cannot");
+  assert.deepEqual(a.names, ["smoke"]);
+});
+
+test("слепой класс важнее просто красного гейта", () => {
+  const a = feedbackAsk({ cannot: [], blind: ["swallowed-error"], red: ["lint"] });
+  assert.equal(a.reason, "blind");
+  assert.deepEqual(a.names, ["swallowed-error"]);
+});
+
+// Красный гейт — это момент, когда комплект принёс пользу: он поймал то, ради чего стоит.
+test("пойманное красным — тоже повод, но последний", () => {
+  const a = feedbackAsk({ cannot: [], blind: [], red: ["lint", "smoke"] });
+  assert.equal(a.reason, "red");
+  assert.deepEqual(a.names, ["lint", "smoke"]);
+});
+
+// --- что в отчёте ------------------------------------------------------------
+
+// ПУТЕЙ НЕ БЫВАЕТ. Проба знает файл, в который подсаживала брак («blind-class: slug path»), и
+// соблазн положить его в отчёт велик — он же объясняет находку. Нельзя: путь внутри чужого
+// репозитория рассказывает о чужом проекте больше, чем его владелец собирался рассказать.
+test("отчёт называет класс, но не файл, в котором его нашли", () => {
+  const text = reportText({
+    version: "0.15.0", node: "v22.0.0", platform: "linux", level: 3,
+    langs: ["javascript"], gates: 31, red: ["lint"], cannot: [],
+    blind: [{ slug: "swallowed-error", file: "src/secret/internal.js" }],
+  }).join("\n");
+  assert.match(text, /swallowed-error/, "класс не назван — отчёт бесполезен");
+  assert.doesNotMatch(text, /src\/secret\/internal\.js/, "в отчёт попал путь из чужого репозитория");
+  assert.doesNotMatch(text, /internal/, "в отчёт попал кусок пути из чужого репозитория");
+});
+
+// МЕТКА ИСТОЧНИКА. Отзыв в GitHub ничем не связан с просьбой, и понять, работает ли канал,
+// иначе нельзя. Метка видна человеку в том же тексте, который он отправляет: это не слежка,
+// а подпись. Слежки у комплекта нет и не будет — исходящий запрос ровно один, про версию.
+test("отчёт подписан командой и версией — иначе не узнать, работает ли канал", () => {
+  const text = reportText({ version: "0.15.0", node: "v22.0.0", platform: "linux" }).join("\n");
+  assert.match(text, /aqk feedback/, "нет метки источника");
+  assert.match(text, /0\.15\.0/, "нет версии");
+});
+
+// Незнание называется словом, а не пропускается: пустая строка в отчёте читается как «всё
+// хорошо» — тот же порок, против которого написан весь комплект, только в нашем же письме.
+test("чего не знаем — сказано словом, а не пустым местом", () => {
+  const text = reportText({ version: "0.15.0", node: "v22.0.0", platform: "linux", level: null }).join("\n");
+  assert.doesNotMatch(text, /уровень:\s*$/m, "уровень пропущен молча");
+});
+
+// --- ссылка ------------------------------------------------------------------
+
+// Предзаполнение задачи параметрами `title` и `body` описано в документации GitHub (Creating an
+// issue from a URL query, сверено 2026-09-14). Кодирование обязательно: в теле переносы строк,
+// решётки и пробелы, и незакодированная ссылка обрывается на первом же из них.
+test("ссылка предзаполнена и закодирована", () => {
+  const u = issueUrl("https://github.com/o/r", "Заголовок про AQK", "строка\nвторая #2");
+  assert.ok(u.startsWith("https://github.com/o/r/issues/new?"), `не та ссылка: ${u}`);
+  assert.match(u, /title=/);
+  assert.match(u, /body=/);
+  assert.doesNotMatch(u, /\n/, "перенос строки не закодирован — ссылка оборвётся");
+  assert.doesNotMatch(u, /#2/, "решётка не закодирована — всё после неё отвалится как якорь");
+});
+
+// --- как это звучит ----------------------------------------------------------
+// Строку строит feedback.mjs, а печатают её `context` (агенту) и `doctor` (человеку): один
+// текст на два места. Собери его в каждом месте отдельно — и через месяц они разойдутся, как
+// разошлись бы `context` и `prompt` без общего `readAdvice`.
+test("строка называет причину, имена и команду", () => {
+  const s = askLine({ reason: "cannot", names: ["smoke"] }, "npx agent-quality-kit");
+  assert.match(s, /smoke/, "не названо, что именно не смогли");
+  assert.match(s, /npx agent-quality-kit feedback/, "нет команды — просьбу нечем выполнить");
+});
+
+// АГЕНТУ — ОТДЕЛЬНАЯ ОГОВОРКА. Мы кладём строку в контекст ЧУЖОГО агента, и он исполнит то, что
+// там написано. Без «не настаивай» это превращается в рекламу в чужом окне — и хук, которым она
+// приехала, снесут в первый же день вместе со всей затеей.
+test("агенту сказано не настаивать, человеку — как выключить", () => {
+  const forAgent = askLine({ reason: "red", names: ["lint"] }, "aqk", { agent: true });
+  const forHuman = askLine({ reason: "red", names: ["lint"] }, "aqk", { agent: false });
+  assert.notEqual(forAgent, forHuman, "агенту и человеку сказано одно и то же");
+  assert.match(forHuman, /AQK_FEEDBACK=0/, "человеку не сказано, как это выключить");
+});
+
+test("просить нечего — строки нет, а не пустая", () => {
+  assert.equal(askLine(null, "aqk"), null);
+});
+
+// У всего, что случается само, обязан быть выключатель — то же правило, что у совета
+// (AQK_ADVICE=0), у пробы (AQK_PROBE=0) и у проверки версии (AQK_UPDATE=0).
+test("выключатель уважается", () => {
+  assert.equal(feedbackWanted({ AQK_FEEDBACK: "0" }), false);
+  assert.equal(feedbackWanted({}), true);
+});
+
+// ПРОБА НЕ ДЕЛАЛАСЬ — «НЕИЗВЕСТНО», А НЕ «НЕТ». Поймано на первом же живом запуске команды:
+// в письме стояло «классы, которые здесь не ловит никто: нет», хотя проба не запускалась ни
+// разу. То есть наш собственный отчёт об инструменте против тишины сам выдавал незнание за
+// чистоту — и автор, читающий такое письмо, сделал бы неверный вывод о чужом проекте.
+test("проба не делалась — в отчёте «неизвестно», а не «нет»", () => {
+  const text = reportText({ version: "0.15.0", blind: null }).join("\n");
+  assert.doesNotMatch(text, /не ловит никто: нет/, "незнание выдано за чистоту");
+  assert.match(text, /не ловит никто: неизвестно/, "незнание не названо словом");
+});

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`: гейт обязан молчать.

package/kit/gates/entry-links-exist/check.sh

@@ -1,33 +0,0 @@
-#!/usr/bin/env sh
-# Каждая ссылка на локальный файл из markdown-файлов каталога обязана вести на
-# существующий файл. Ссылка в никуда — это документ, утверждающий защиту,
-# которой нет: планирование опирается на неё и ломается молча.
-DIR="${1:-.}"
-MISS=0
-for MD in "$DIR"/*.md; do
-  [ -f "$MD" ] || continue
-  # вытащить цели ссылок вида [текст](путь)
-  # Строки со вставками в обратных кавычках чистятся ДО разбора: «`[name](url)`» — это пример
-  # оформления ссылки, а не ссылка. Замер 2026-09-08: в uv/STYLE.md именно так и было, и гейт
-  # требовал создать файл с именем «url».
-  TARGETS=$(sed 's/`[^`]*`//g' "$MD" | sed -n 's/.*](\([^)]*\)).*/\1/p')
-  for T in $TARGETS; do
-    # автоссылки бывают обёрнуты как <(https://...)> — искать http где угодно внутри,
-    # не только в начале строки.
-    case "$T" in *http://*|*https://*|\#*|mailto:*) continue ;; esac
-    T=${T%%#*}
-    [ -z "$T" ] && continue
-    # Путь, кончающийся косой чертой, — адрес страницы опубликованного сайта, а не файл на
-    # диске. Так ссылаются mkdocs, docusaurus и jekyll: `[руководство](tutorial/#install)`
-    # работает у читателя и не существует в репозитории. Найдено замером по fastapi — гейт
-    # объявлял битой рабочую ссылку из их README. Проверять такие адреса умеют lychee и
-    # markdown-link-check: они ходят в сеть, а мы смотрим только на диск.
-    case "$T" in */) continue ;; esac
-    if [ ! -e "$DIR/$T" ]; then
-      echo "$MD: ссылка в никуда — $T"
-      echo "  почини: создай файл или убери ссылку. Документ, обещающий несуществующее, хуже отсутствующего."
-      MISS=1
-    fi
-  done
-done
-exit $MISS

package/kit/gates/entry-links-exist/gate.yml

@@ -1,17 +0,0 @@
-# Запись каталога AQK. Норма и все поля — kit/gates/README.md.
-# Читается программой; всё, что нельзя выполнить, живёт в README.md рядом.
-
-intent: файлы, на которые ссылается точка входа, существуют на диске
-intent_en: files the entry point links to actually exist on disk
-
-# Когда запись показывается человеку. Отсутствие триггера сделало бы её шумом
-# для тех, кого она не касается.
-trigger:
-  always: true
-
-# Команда-арбитр под каждый стек. {dir} — каталог, который проверяют.
-# `any` — команда без зависимостей, работает везде, где есть sh и grep.
-recipes:
-  any: bash {gate}/check.sh {dir}
-
-proof: incidents/README.md — «2026-08-24 документ четыре недели утверждал защиту, которой не было»

package/kit/gates/entry-links-exist/green/AGENTS.md

@@ -1,10 +0,0 @@
-# Свод правил
-
-Стандарты: [общие правила](rules/general.md).
-Внешняя ссылка: [semver](https://semver.org).
-Автоссылка в скобках, как в CHANGELOG.md gin: [#1](<(https://example.com/pull/1)>).
-Ссылка на страницу сайта документации: [руководство](tutorial/#install) — путь опубликованного
-сайта, а не файл на диске. Найдено замером по fastapi: `[installation guide](tutorial/#install-fastapi)`
-в README читалась как битая, хотя на сайте работает. Так ссылаются mkdocs, docusaurus и jekyll.
-
-Пример оформления ссылки: `[name](url)` — это пример, а не ссылка.

package/kit/gates/entry-links-exist/green/rules/general.md

@@ -1,3 +0,0 @@
-# Общие правила
-
-Пусто, но файл существует.

package/kit/gates/entry-links-exist/red/AGENTS.md

@@ -1,3 +0,0 @@
-# Свод правил
-
-Стандарты: [общие правила](rules/nope.md).