agent-quality-kit 0.14.0 → 0.16.0

package/tool/lib/execution.mjs

@@ -105,6 +105,37 @@ function launchable(cmd, bash) {
   return bash && /^bash(\s|$)/.test(s) ? `"${bash}"${s.slice(4)}` : s;
 }
 
+// СКОЛЬКО ЖДАТЬ ЧУЖУЮ КОМАНДУ. Знание лежит здесь, рядом с остальным протоколом запуска: до
+// 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 (весь их список
+// ключей проверен 2026-09-16), ни у pre-commit — поэтому в манифест мы его не заводим:
+// соглашения снаружи нет, а просьба была одна. Заведём, когда попросят второй раз.
+//
+// ПРОБА ЖИВЁТ ПО СВОИМ ЧАСАМ намеренно (`probe.mjs`): она гоняет десятки гейтов на подсаженном
+// дефекте, и её минута-две — осознанный предел выборки, а не «сколько ждать эту проверку».
+const GATE_TIMEOUT_DEFAULT = 300000;
+
+// Возвращается ОБЪЕКТ, а не число: мусор в переменной нельзя проглотить молча — человек задал
+// её и ждёт действия, — но и печатать отсюда нельзя, функция чистая. Поэтому «исправно ли» едет
+// рядом со значением, а говорит об этом тот, у кого есть экран (`run.mjs`).
+function gateTimeout(env = process.env) {
+  const raw = String(env?.AQK_GATE_TIMEOUT ?? "").trim();
+  if (!raw) return { ms: GATE_TIMEOUT_DEFAULT, raw: "", ok: true };
+  const secs = Number(raw);
+  // Ноль и отрицательное у spawnSync означают «ждать вечно» — то есть висящий гейт вместо
+  // честного «не смогли проверить». Ровно тот исход, ради различения которого написан файл.
+  if (!Number.isFinite(secs) || secs <= 0) return { ms: GATE_TIMEOUT_DEFAULT, raw, ok: false };
+  return { ms: Math.round(secs * 1000), raw, ok: true };
+}
+
 // Одна точка для всех пяти мест, где запускается команда гейта: прогон, доказательство, проба,
 // храповик, `why`. Поиск делается раз на процесс — он смотрит на диск, а гейтов бывает тридцать.
 let cachedBash;
@@ -113,4 +144,4 @@ function gateCommand(cmd) {
   return launchable(cmd, cachedBash);
 }
 
-export { classify, findingCodes, gitBash, launchable, gateCommand };
+export { classify, findingCodes, gitBash, launchable, gateCommand, gateTimeout, GATE_TIMEOUT_DEFAULT };

package/tool/lib/gate-worker.mjs

@@ -12,7 +12,10 @@ import { gateCommand } from "./execution.mjs";
 parentPort.on("message", ({ id, cmd, cwd, timeout }) => {
   const r = spawnSync(gateCommand(cmd), { shell: true, cwd, encoding: "utf8", timeout });
   parentPort.postMessage({
-    id, status: r.status, stdout: r.stdout || "", stderr: r.stderr || "",
+    // `signal` передаётся наравне со статусом: по нему исход отличает наш срок (SIGTERM) от
+    // чужого убийства. Без него параллельный прогон объяснял бы сбой иначе, чем одиночный, —
+    // а одно и то же событие обязано называться одним словом в обоих.
+    id, status: r.status, signal: r.signal || null, stdout: r.stdout || "", stderr: r.stderr || "",
     error: r.error ? { code: r.error.code || String(r.error.message || r.error) } : null,
   });
 });

package/tool/lib/manifest.mjs

@@ -112,7 +112,7 @@ function unparsedLines(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "lang", "gates", "covers", "samples", "ratchets", "lessons", "advisory", "probe", "groups"];
+const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "lang", "gates", "covers", "requires", "samples", "ratchets", "lessons", "advisory", "probe", "groups"];
 
 // ГДЕ У ПРОЕКТА ЛЕЖИТ РАЗЛОЖЕННЫЙ КОМПЛЕКТ. Список для шапки `doctor`. До 2026-09-08 он был
 // литеральным: `.aqk/rules`, `.aqk/docs`, `AGENTS.md` — независимо от того, что написано в
@@ -306,19 +306,45 @@ function entryLifecycle(rec) {
 // `vitals` печатал «все инструменты на месте» ровно там, где прогон краснел.
 // `has` передаётся вызывающим, а не берётся отсюда: manifest.mjs не должен знать про осмотр
 // репозитория — импорт в обратную сторону завёл бы цикл. Заодно функция проверяема модульно.
-async function gateRequires(samplesDir, name, has) {
-  if (!samplesDir) return null;
-  const yml = join(CWD, samplesDir, name, "gate.yml");
-  if (!(await exists(yml))) return null;
-  try {
-    const rec = parseManifest(await readFile(yml, "utf8"));
-    const raw = typeof rec?.requires === "string" ? rec.requires.trim() : "";
-    if (!raw) return null;
-    const missing = raw.split(",").map((x) => x.trim()).filter(Boolean).filter((x) => !has(x));
-    return missing.length ? missing : null;
-  } catch {
-    return null;
+// ДВА ИСТОЧНИКА, А НЕ ОДИН. Поле читалось только из `<samples>/<гейт>/gate.yml`, то есть было
+// доступно НАШИМ записям и недоступно гейтам проекта. Разбор чужой интеграции 2026-09-16: гейт
+// объявлен как `docker run --rm … promtool test rules …`, `vitals` смотрит первое слово, видит
+// `docker` и говорит «инструменты на месте». У проекта с чужими командами `samples` пуст по
+// построению, и сказать «этому гейту нужен docker» было нечем.
+//
+// СНАРУЖИ СОГЛАШЕНИЯ НЕТ — проверено 2026-09-16, и это сказано вслух, а не выдано за
+// общепринятое. У pre-commit ровно эта просьба закрыта нерешённой (issue #2042: трактовать
+// `additional_dependencies` как список программ в $PATH и пропускать хук, если программы нет;
+// ответ — `system`-хуки окружения не ставят). У lefthook такого ключа нет вовсе. Поэтому мы не
+// копируем чужую форму, а распространяем свою: то же имя поля и та же форма «имя гейта →
+// значение», что у `covers:` и `groups:`. Новых понятий в манифесте не появляется.
+//
+// ГРАНИЦА НАЗЫВАЕТСЯ ВСЛУХ: «программа есть в PATH» и «программа сможет отработать» — разные
+// утверждения. `docker` в PATH при мёртвом демоне по-прежнему считается найденным; это не
+// ложь vitals, а предел того, что видно без запуска. Запускать чужой инструмент ради осмотра
+// мы не будем: осмотр обязан быть дешёвым и без побочных действий.
+function requiredBy(man, name) {
+  const r = man?.requires && typeof man.requires === "object" && !Array.isArray(man.requires) ? man.requires : null;
+  const v = r ? r[name] : null;
+  if (Array.isArray(v)) return v.map((x) => String(x).trim()).filter(Boolean);
+  return typeof v === "string" ? v.split(",").map((x) => x.trim()).filter(Boolean) : [];
+}
+
+async function gateRequires(man, samplesDir, name, has) {
+  const names = [...requiredBy(man, name)];
+  if (samplesDir) {
+    const yml = join(CWD, samplesDir, name, "gate.yml");
+    if (await exists(yml)) {
+      try {
+        const rec = parseManifest(await readFile(yml, "utf8"));
+        const raw = typeof rec?.requires === "string" ? rec.requires.trim() : "";
+        for (const x of raw.split(",").map((s) => s.trim()).filter(Boolean)) names.push(x);
+      } catch { /* нечитаемая запись — не повод обвинять гейт */ }
+    }
   }
+  if (!names.length) return null;
+  const missing = [...new Set(names)].filter((x) => !has(x));
+  return missing.length ? missing : null;
 }
 
 // ПОЧЕМУ СПИСКОМ В МАНИФЕСТЕ, А НЕ ФЛАГОМ ПРОГОНА. Флаг «не роняй ничего» — это тот самый

package/tool/lib/prove.mjs

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { CWD, exists } from "./core.mjs";
 import { parseManifest, gateRequires } from "./manifest.mjs";
 import { whichSync } from "./repo.mjs";
-import { classify, findingCodes, gateCommand } from "./execution.mjs";
+import { classify, findingCodes, gateCommand, gateTimeout } from "./execution.mjs";
 
 // Гейт можно доказать, если у него есть оба образца. Признак по образцам, а не по тексту
 // команды: запись, делегирующая готовому инструменту (`npx knip --directory .`), каталог
@@ -115,7 +115,7 @@ function run(cmd, timeoutMs, prog) {
 
 // Возвращает { proven, broken, unprovable, results } — числами и списком, чтобы вызывающий
 // сам решал, что печатать и чем краснеть.
-async function proveGates(man, { timeoutMs = 300000 } = {}) {
+async function proveGates(man, { timeoutMs = gateTimeout().ms } = {}) {
   const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
   const samplesDir = typeof man?.samples === "string" ? man.samples.trim() : "";
   const results = [];
@@ -135,7 +135,7 @@ async function proveGates(man, { timeoutMs = 300000 } = {}) {
     // Программы, без которой запись не работает, может не быть на машине — тогда доказывать
     // нечем, а не «гейт сломан». Проверяется ДО запуска: без неё обёртка краснеет на обоих
     // образцах, и вердикт вышел бы «краснеет на исправном коде».
-    const missing = await gateRequires(samplesDir, name, whichSync);
+    const missing = await gateRequires(man, samplesDir, name, whichSync);
     if (missing) {
       results.push({ name, state: "unprovable", why: "needs-program", missing });
       continue;

package/tool/lib/run.mjs

@@ -10,13 +10,14 @@
 // контексту». Ровно то, о чём предупреждает совет самого гейта.
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Worker } from "node:worker_threads";
 import { scopeOutput, splitAdvice, changedFiles } from "./scope.mjs";
-import { CWD, c, die } from "./core.mjs";
+import { CWD, TARGET_DIR, c, die, exists } from "./core.mjs";
 import { advisorySet } from "./manifest.mjs";
 import { L } from "../i18n/index.mjs";
-import { gateCommand } from "./execution.mjs";
+import { gateCommand, classify, findingCodes, gateTimeout } from "./execution.mjs";
 import { annotations } from "./annotate.mjs";
 
 
@@ -102,11 +103,12 @@ function selectGates(gates, man, { only = [], skip = [] } = {}) {
   return { run, skipped: gates.map(([n]) => n).filter((n) => !kept.has(n)), unknown: [...new Set(unknown)] };
 }
 
-const GATE_TIMEOUT = 300000;
+// Сколько ждать — знает `execution.mjs`, там же, где всё остальное про запуск чужой команды.
+// Число жило здесь и ещё в трёх местах; переопределяется переменной AQK_GATE_TIMEOUT.
 
 // Один гейт в этом потоке — прежний путь, без `--jobs`.
 function spawnGate(cmd) {
-  return spawnSync(gateCommand(cmd), { shell: true, cwd: CWD, encoding: "utf8", timeout: GATE_TIMEOUT });
+  return spawnSync(gateCommand(cmd), { shell: true, cwd: CWD, encoding: "utf8", timeout: gateTimeout().ms });
 }
 
 // ПАРАЛЛЕЛЬНО — ПО ФЛАГУ. Отзыв с живого проекта 2026-09-11: 34 независимых гейта шли друг за
@@ -124,7 +126,7 @@ function startPool(cmds, jobs) {
     const onErr = (e) => { results[id].res({ status: null, stdout: "", stderr: String(e?.message || e), error: { code: "WORKER" } }); };
     w.once("error", onErr);
     w.once("message", (m) => { w.off("error", onErr); results[id].res(m); feed(w); });
-    w.postMessage({ id, cmd: cmds[id], cwd: CWD, timeout: GATE_TIMEOUT });
+    w.postMessage({ id, cmd: cmds[id], cwd: CWD, timeout: gateTimeout().ms });
   };
   for (let i = 0; i < Math.min(jobs, cmds.length); i++) feed(new Worker(url));
   return results;
@@ -139,6 +141,12 @@ async function runGates(man, opts = {}) {
   const advisory = advisorySet(man);
   const bar = progress();
 
+  // Мусор в AQK_GATE_TIMEOUT называется вслух ОДИН раз за прогон. Молча вернуть умолчание
+  // значило бы, что человек задал переменную, ничего не получил и об этом не узнал, — та же
+  // тишина, против которой написан комплект, только в его собственной настройке.
+  const t = gateTimeout();
+  if (!t.ok) console.log(c.yellow(`  ${L.doctor.timeoutBadEnv(t.raw, Math.round(t.ms / 1000))}`));
+
   // Сужение по дифу — договор с человеком, и он должен видеть, ЧТО именно сужено. Пустой диф
   // называется вслух: иначе «все гейты зелёные» означало бы «сравнили не с тем» и читалось бы
   // как успех. Это тот же класс, что и весь стандарт, только внутри нашего флага.
@@ -168,10 +176,46 @@ async function runGates(man, opts = {}) {
     // Без этого «готово = доказано» остаётся правилом, за которым следит только человек.
     const outAll = `${r.stdout || ""}${r.stderr || ""}`.slice(0, 200000);
 
-    if (r.error && r.error.code === "ETIMEDOUT") {
-      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.timeout)}`);
-      failed++;
-      results.push({ name, cmd, ok: false, secs, note: L.doctor.timeout, out: outAll });
+    // ИСХОД ЗАПУСКА — ДО РАЗБОРА ВЫВОДА И ДО СУЖЕНИЯ. Состояний три, а не два: clean · finding
+    // · infra_error. Знание о кодах живёт рядом с инструментом (`execution.mjs`): у vulture
+    // находка это 3, у pylint — битовая маска, а у незнакомой программы находка только 1.
+    //
+    // ЗАЧЕМ ЗДЕСЬ. Прежде прогон ловил один лишь ETIMEDOUT, а любой другой ненулевой код шёл в
+    // разбор находок — и `--since` фильтровал его ПО ПУТЯМ. Гейт, который НЕ СМОГ отработать,
+    // называл путь вне дифа и печатался зелёным: проверка сломалась, прогон сказал «чисто».
+    // Найдено внешним разбором 2026-09-13 (аудит Runcap), воспроизведено проверкой
+    // `fail-closed`. Сужать дифом можно только НАХОДКУ: у сбоя нет места в коде, которое он
+    // называет, — есть только сам сбой.
+    const verdict = classify(r, findingCodes(String(cmd).trim().split(/\s+/)[0]));
+    if (verdict.state === "infra_error") {
+      const why =
+        verdict.reason === "timeout" ? L.doctor.timeout
+        : verdict.reason === "spawn_error" ? L.doctor.whySpawn(r.error?.code || "")
+        : verdict.reason === "signal" ? L.doctor.whySignal(r.signal)
+        : L.doctor.whyExit(verdict.code);
+      // Совещательный не роняет прогон НИКОГДА — в том числе своим сбоем: список `advisory:`
+      // означает «эта проверка не имеет права останавливать работу», и причина остановки тут
+      // ни при чём. Но НАЗВАН он обязан быть: «не смогли» и «чисто» неразличимы только там,
+      // где о них молчат. Раньше таймаут ронял прогон и у совещательного — тот же класс, что
+      // измеренный 2026-09-09 случай с гейтом без путей в выводе.
+      const adv = advisory.has(name);
+      const note = L.doctor.cannotCheck(why);
+      const paint = adv ? c.yellow : c.red;
+      console.log(`  ${adv ? c.yellow("!") : c.red("✘")}  ${name.padEnd(14)} ${paint(note)} ${c.dim(`· ${secs}s · ${cmd}`)}`);
+      // Вывод сбоя показывается тоже. «Не смогли проверить: код 127» без строки
+      // «command not found: ruff» не говорит, ЧТО чинить, — а чинить тут надо инструмент,
+      // и первые строки обычно и есть его жалоба.
+      for (const line of outAll.trim().split("\n").filter(Boolean).slice(0, 3)) {
+        console.log(c.dim(`        ${line.slice(0, 100)}`));
+      }
+      if (!adv) failed++;
+      // В pull request это ОБЩАЯ пометка гейта, а не пометка у строки файла: `shown` — то, что
+      // прогон показал, и у сбоя это причина, а не путь. Иначе «не смогли проверить» повисло бы
+      // на первом файле, который гейт успел назвать перед падением, — то есть на невиновном.
+      // Сырой `out` не трогаем: по нему считается покрытие дифа.
+      // `cannot` — не украшение: по нему отчёт прогона отличает сбой от находки одним знаком,
+      // а блок для агента и просьба об отзыве читают это из файла, ничего не запуская.
+      results.push({ name, cmd, ok: false, cannot: true, secs, code: verdict.code, advisory: adv, note, out: outAll, shown: note });
       continue;
     }
     const code = r.status;
@@ -280,4 +324,92 @@ async function runGates(man, opts = {}) {
   return { failed, ran: gates.length, results, advisoryFailed, skipped: sel.skipped };
 }
 
-export { declaredGates, sinceRef, runGates, progress, selectGates, listArg };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ОТЧЁТ ПРОГОНА: пишется здесь же, где прогон, и читается здесь же. Раньше `doctor` его ПИСАЛ,
+// а `context` РАЗБИРАЛ — два файла, которые друг о друге не знают, держали один формат. Третий
+// знак («?» — не смогли проверить) пришлось заводить в обоих, и это ровно тот случай, когда
+// одно знание живёт в двух местах: правишь одно, второе молча расходится.
+//
+// Читателей у отчёта трое — блок для агента, задание и просьба об отзыве, — и ни один не
+// запускает гейты заново: хук обязан укладываться в секунду, а прогон идёт минуту.
+// Короткий отчёт «что из этого реально брали» — не для человека, а для агента в следующей
+// сессии и для самого владельца: список объявленных гейтов молчит о том, сколько из них
+// действительно стоят и работают именно СЕЙЧАС. Перезаписывается каждым прогоном, не копится:
+// история — дело git-лога коммитов с этим отчётом, если владелец решит его коммитить.
+async function writeRunReport({ version, reached, results, skipped = [] }) {
+  const stamp = new Date().toISOString().replace("T", " ").slice(0, 16);
+  const ok = results.filter((r) => r.ok).length;
+  const lines = [
+    `# ${L.report.title} — ${stamp}`,
+    version ? `${L.report.version}: ${version}` : null,
+    `${L.report.level}: AQK-${reached < 0 ? L.doctor.levelNone : reached}`,
+    "",
+    // ТРИ ЗНАКА, А НЕ ДВА: ✔ прошло · ✘ находка · ? НЕ СМОГЛИ ПРОВЕРИТЬ. Отчёт читает не только
+    // человек: из него блок для агента и просьба об отзыве узнают, что случилось, ничего не
+    // запуская. Слив «не смогли» с находкой означал бы, что агент чинит код там, где сломан
+    // инструмент, — и никогда не узнает, что инструмент сломан.
+    ...results.map((r) => `${r.ok ? "✔" : r.cannot ? "?" : "✘"} ${r.name} — ${r.secs}s${r.ok ? "" : ` (${r.note || L.doctor.exitCode(r.code)})`}`),
+    // Пропущенные по --skip/--only — строкой «~»: блок для агента читает их как «не запускались»,
+    // а не как зелёные. Молчание о них прочиталось бы как «проверено».
+    ...skipped.map((n) => `~ ${n} — ${L.report.skippedBySelect}`),
+    "",
+    L.report.summary(ok, results.length),
+  ].filter((l) => l !== null);
+
+  // ЗАПИСЬ ОТЧЁТА НЕ РОНЯЕТ ПРОГОН. Тот же класс, что у `report` (разбор 2026-09-16): в рабочей
+  // области, где `.aqk/` не создать — read-only контейнер, чужой конвейер, каталог под
+  // ревью, — прогон падал уже ПОСЛЕ того, как все гейты отработали, и человек не получал ни
+  // вердикта, ни кода возврата. Побочное действие отменяло то, ради чего команду звали.
+  //
+  // Но молчать нельзя: отчёт читают `context` и `prompt`, и его отсутствие они прочтут как
+  // «прогона не было». Разница между «не было» и «был, записать не смогли» — ровно та, которую
+  // весь комплект и защищает, поэтому она называется вслух.
+  const dst = join(CWD, TARGET_DIR, "last-run.md");
+  try {
+    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+    await writeFile(dst, lines.join("\n") + "\n", "utf8");
+  } catch (e) {
+    console.log(c.yellow(`  ${L.report.notWritten(join(TARGET_DIR, "last-run.md"), e?.code || String(e?.message || e))}`));
+  }
+}
+
+// Разбор отчёта прошлого прогона. Формат кладёт сам `doctor` в .aqk/last-run.md; читаем его,
+// а не запускаем гейты заново: хук обязан укладываться в секунду-две, а прогон у нас идёт минуту.
+function parseLastRun(text) {
+  if (!text) return null;
+  const when = (text.match(/^# aqk doctor --run — (.+)$/m) || [])[1] || "";
+  const red = [];
+  for (const m of text.matchAll(/^✘ ([^\s—]+)/gm)) red.push(m[1]);
+  // «Не смогли проверить» — свой знак и свой список. Гейт, который не сумел отработать, не
+  // находка о коде: агент, прочитавший его как находку, пойдёт чинить исправный файл, а
+  // сломанный инструмент останется сломанным. Слить их в один список было бы той же тишиной,
+  // только наоборот.
+  const cannot = [];
+  for (const m of text.matchAll(/^\? ([^\s—]+)/gm)) cannot.push(m[1]);
+  const skipped = (text.match(/^~ /gm) || []).length;
+  return { when: when.trim(), red, cannot, skipped, stale: false };
+}
+
+// Прогон старше последнего коммита описывает не тот код, что лежит перед агентом. Молча выдать
+// его за свежий — соврать: именно так «зелёный месяц назад» превращается в «зелёный сейчас».
+function runIsStale(when) {
+  if (!when) return false;
+  const r = spawnSync("git", ["log", "-1", "--format=%cI"], { cwd: CWD, encoding: "utf8" });
+  if (r.status !== 0 || !r.stdout) return false;
+  const commit = Date.parse(r.stdout.trim());
+  const run = Date.parse(when.replace(" ", "T"));
+  return Number.isFinite(commit) && Number.isFinite(run) && run < commit;
+}
+
+// Прошлый прогон — из отчёта, который кладёт `doctor --run`. Отдельной функцией: его читают и
+// `context`, и `prompt`, и два разбора одного файла разошлись бы.
+async function readRun() {
+  const lastRun = join(CWD, TARGET_DIR, "last-run.md");
+  if (!(await exists(lastRun))) return null;
+  const run = parseLastRun(await readFile(lastRun, "utf8"));
+  if (run) run.stale = runIsStale(run.when);
+  return run;
+}
+
+export { declaredGates, sinceRef, runGates, progress, selectGates, listArg, writeRunReport, parseLastRun, readRun };

package/tool/program.mjs

@@ -30,6 +30,7 @@ import { cmdProbe } from "./commands/probe.mjs";
 import { cmdContext } from "./commands/context.mjs";
 import { cmdPrompt } from "./commands/prompt.mjs";
 import { cmdVitals } from "./commands/vitals.mjs";
+import { cmdFeedback } from "./commands/feedback.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -127,6 +128,11 @@ if (IS_MAIN) {
     case "badge":
       await cmdBadge(rest);
       break;
+    // Собирает отчёт о работе комплекта и даёт готовую ссылку. Ничего не отправляет: исходящий
+    // запрос у комплекта ровно один — про свежесть версии.
+    case "feedback":
+      await cmdFeedback();
+      break;
     default: {
       // Ширина колонки считается, а не подбирается пробелами: строки в двух языках разной
       // длины, и вручную выровненная справка на втором языке разъезжается.

package/tool/selfcheck/smoke/_fixture.mjs

@@ -93,6 +93,18 @@ function run({ dir, home }, cmd, args = [], extra = {}) {
   return { code: r.status, out: `${r.stdout || ""}${r.stderr || ""}` };
 }
 
+// ХВОСТ ВЫВОДА — последние N строк. Знание «как взять хвост» лежало в трёх проверках тремя
+// одинаковыми цепочками; сообщение утверждения без хвоста отправляет читателя гадать, поэтому
+// хвост берут все, кто что-то утверждает о выводе.
+//
+// Попутно это уводит наши файлы из-под чужого дефекта: `checkwash` (0.2.13 и 0.3.4 одинаково)
+// принимает строковый литерал `"\n"` за ИМЯ тестового юнита, и файл, где таких литералов два,
+// на любом сдвиге строк получает `TEST_DISABLED — test unit disappeared` уровня high. То есть
+// наш собственный гейт `test-not-adjusted` краснел на добавленном комментарии. Воспроизведение
+// в шесть строк отправлено автору; здесь не обход ради обхода, а устранение настоящего повтора,
+// у которого этот эффект оказался побочным.
+const tail = (out, n = 6) => String(out).trimEnd().split("\n").slice(-n).join("\n");
+
 const aqk = (p, ...args) => run(p, process.execPath, [CLI, ...args]);
 const aqkEnv = (p, extra, ...args) => run(p, process.execPath, [CLI, ...args], extra);
 
@@ -113,4 +125,4 @@ const gate = (p, name, sub = ".") =>
 // никто не берёт, читается как часть договора и мешает менять внутренности — поймал наш же
 // dead-code через минуту после того, как файл был написан. `run` вернулся, когда появилась
 // проверка, которой нужен сырой git: экспорт заводится под потребителя, а не про запас.
-export { project, run, aqk, aqkEnv, gate };
+export { project, run, aqk, aqkEnv, gate, tail };

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

@@ -20,7 +20,7 @@ import assert from "node:assert/strict";
 import { cpSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { project, run, aqk } from "./_fixture.mjs";
+import { project, run, aqk, aqkEnv } from "./_fixture.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 const posix = (p) => String(p).replace(/\\/g, "/");
@@ -110,3 +110,98 @@ test("doctor называет человеку, сколько правил не
   assert.ok(/человек/i.test(r.out),
     `doctor не сказал про сторожа-человека ни слова, хотя таких правил здесь два.\n${r.out}`);
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// СБОЙ САМОЙ ПРОВЕРКИ НЕ СУЖАЕТСЯ ДИФОМ. Написано ДО кода 2026-09-14.
+//
+// ЗАЧЕМ. Внешний разбор (аудит Runcap, 2026-09-13) искал у нас тот же класс отказа, что нашёл
+// у соседа, и нашёл: `--since` фильтрует вывод ПО ПУТЯМ, и гейт, который НЕ СМОГ отработать,
+// печатался зелёным, если названный им путь в диф не попал. То есть
+//
+//   проверка сломалась → прогон говорит «чисто»
+//
+// — ровно та тишина, против которой построен весь стандарт, только внутри нашего же флага.
+// Договор уже записан в `execution.mjs` и уже соблюдается в `prove`: 0 чисто, 1 находка (у
+// vulture 3, у pylint битовой маской), ВСЁ ОСТАЛЬНОЕ — «не смогли». Сужать дифом можно только
+// НАХОДКУ: у сбоя нет места в коде, которое он называет, — есть только сам сбой.
+// Цвет снимается: в терминале между знаком и именем гейта стоит управляющая
+// последовательность, и проверка, написанная «по глазам», не совпала бы ни разу.
+const plain = (s) => String(s).replace(/\u001b\[[0-9;]*m/g, "");
+
+function scopeProject(t, { code, path }) {
+  const p = project(t, {
+    "AGENTS.md": "# проект\n",
+    ".aqk.yml": 'aqk: 1\nentry:\n  - AGENTS.md\ngates:\n  broken: "bash broken.sh"\n',
+    // Команда — ФАЙЛОМ, а не строкой `echo …; exit 2`: на Windows строку исполняет cmd.exe,
+    // где `;` не разделитель, и гейт выходит нулём. Поймано конвейером 2026-09-11.
+    "broken.sh": `echo "${path}: infrastructure failure"\nexit ${code}\n`,
+  });
+  run(p, "git", ["add", "-A"]);
+  run(p, "git", ["commit", "-qm", "база"]);
+  // Изменение ПОСЛЕ коммита: ровно один файл в дифе, и путь из вывода гейта в него не входит.
+  mkdirSync(join(p.dir, "src"), { recursive: true });
+  writeFileSync(join(p.dir, "src", "a.mjs"), "export const a = 1;\n", "utf8");
+  return p;
+}
+
+test("гейт, выпавший с непонятным кодом, остаётся красным и при --since", (t) => {
+  const p = scopeProject(t, { code: 2, path: "outside/old.mjs:1" });
+  const r = aqk(p, "doctor", "--run", "--since", "HEAD");
+  assert.match(plain(r.out), /✘\s+broken/,
+    "гейт вышел с кодом 2 — «не смогли проверить» — и показан зелёным, потому что названный " +
+    `им путь не попал в диф. Вывод:\n${r.out}`);
+});
+
+test("контроль: НАХОДКА вне дифа по-прежнему сужается", (t) => {
+  const p = scopeProject(t, { code: 1, path: "outside/old.mjs:1" });
+  const r = aqk(p, "doctor", "--run", "--since", "HEAD");
+  assert.match(plain(r.out), /✔\s+broken/,
+    `находка вне дифа обязана сужаться — иначе --since не делает ничего. Вывод:\n${r.out}`);
+});
+
+test("контроль: находка ВНУТРИ дифа остаётся красной", (t) => {
+  const p = scopeProject(t, { code: 1, path: "src/a.mjs:1" });
+  const r = aqk(p, "doctor", "--run", "--since", "HEAD");
+  assert.match(plain(r.out), /✘\s+broken/, `находка в изменённом файле пропала. Вывод:\n${r.out}`);
+});
+
+test("контроль: нулевой код остаётся «чисто»", (t) => {
+  const p = scopeProject(t, { code: 0, path: "outside/old.mjs:1" });
+  const r = aqk(p, "doctor", "--run", "--since", "HEAD", "--verbose");
+  assert.match(plain(r.out), /✔\s+broken/, `нулевой код перестал означать «чисто». Вывод:\n${r.out}`);
+});
+
+test("параллельный прогон говорит о сбое то же самое, что одиночный", (t) => {
+  const p = scopeProject(t, { code: 2, path: "outside/old.mjs:1" });
+  const one = plain(aqk(p, "doctor", "--run", "--since", "HEAD").out);
+  const many = plain(aqk(p, "doctor", "--run", "--since", "HEAD", "--jobs", "2").out);
+  const line = (out) => (out.split("\n").find((l) => /broken/.test(l) && /[✘✔!]/.test(l)) || "").trim();
+  assert.match(line(many), /✘/, `при --jobs сбой не покраснел. Вывод:\n${many}`);
+  assert.equal(line(many).replace(/\d+\.\ds/, ""), line(one).replace(/\d+\.\ds/, ""),
+    `одно и то же событие названо по-разному в одиночном и параллельном прогоне:\n${line(one)}\n${line(many)}`);
+});
+
+// Совещательный — это «показать, но не останавливать». Причина остановки тут ни при чём: сбой
+// такой проверки обязан быть НАЗВАН и обязан не ронять прогон. Раньше на таймауте ронял.
+test("сбой СОВЕЩАТЕЛЬНОГО гейта назван, но прогон не уронен", (t) => {
+  const p = scopeProject(t, { code: 2, path: "outside/old.mjs:1" });
+  writeFileSync(join(p.dir, ".aqk.yml"),
+    'aqk: 1\nentry:\n  - AGENTS.md\ngates:\n  broken: "bash broken.sh"\nadvisory:\n  - broken\n', "utf8");
+  const r = aqk(p, "doctor", "--run", "--since", "HEAD");
+  const out = plain(r.out);
+  assert.match(out, /!\s+broken/, `совещательный сбой не назван вовсе. Вывод:\n${out}`);
+  assert.match(out, /не смогли проверить/, `сбой назван находкой, а не «не смогли». Вывод:\n${out}`);
+  assert.doesNotMatch(out, /красных гейтов/,
+    `совещательный уронил прогон — список advisory перестал что-либо значить. Вывод:\n${out}`);
+});
+
+// Пометка в pull request у сбоя — ОБЩАЯ, без file=: путь из вывода упавшего гейта назвал не
+// виноватого, а того, до кого гейт успел дойти.
+test("в GitHub Actions сбой помечается гейтом, а не строкой чужого файла", (t) => {
+  const p = scopeProject(t, { code: 2, path: "outside/old.mjs:1" });
+  const r = aqkEnv(p, { GITHUB_ACTIONS: "true" }, "doctor", "--run", "--since", "HEAD");
+  const ann = plain(r.out).split("\n").filter((l) => l.startsWith("::error"));
+  assert.equal(ann.length, 1, `пометок про сбой не одна:\n${ann.join("\n")}`);
+  assert.doesNotMatch(ann[0], /file=/, `пометка повешена на файл, которого сбой не касается: ${ann[0]}`);
+  assert.match(ann[0], /title=aqk%3A broken/, `пометка не называет гейт: ${ann[0]}`);
+});

package/tool/selfcheck/smoke/feedback-send.test.mjs

@@ -0,0 +1,87 @@
+// tool/selfcheck/smoke/feedback-send.test.mjs — ОТПРАВКА ТОЛЬКО ПО ЯВНОМУ СЛОВУ.
+//
+// ЗАЧЕМ ЭТО ГЛАВНАЯ ПРОВЕРКА ФАЙЛА. Владелец 2026-09-14 спросил, нельзя ли отправлять отзыв
+// «без согласия пользователя, чтобы агент мог быстро сообщить». Ответ — нет, и не из вежливости:
+// в README и SECURITY.md написано, что исходящий запрос у комплекта ровно один, про версию.
+// Инструмент, который втихую шлёт что-то из чужого репозитория, становится ровно тем, что мы
+// критикуем, — а наша аудитория это те, кто проверяет инструменты на вранье.
+//
+// Поэтому согласие живёт В САМОМ ФЛАГЕ: `--send` не набирают случайно. И это утверждение обязана
+// держать машина, а не наше обещание в документации, — иначе однажды рефакторинг отправит письмо
+// из команды, которая всю жизнь только печатала.
+//
+// КАК ПРОВЕРЯЕТСЯ. `AQK_GH` подменяет программу `gh` на скрипт, который записывает сам факт
+// вызова в файл. Запуск через `node`, а не через оболочку: то же решение, что у `AQK_BASH` в
+// execution.mjs, и оно работает и на windows-задании конвейера.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { project, aqkEnv } from "./_fixture.mjs";
+
+// Поддельный `gh`: пишет, с какими доводами его позвали, и отвечает так, чтобы отправка дошла
+// до конца. Чего он НЕ делает — ничего наружу.
+function fakeGh(p) {
+  const log = join(p.dir, "gh-calls.txt");
+  const script = join(p.dir, "fake-gh.mjs");
+  writeFileSync(script, `
+import { appendFileSync } from "node:fs";
+const args = process.argv.slice(2);
+appendFileSync(${JSON.stringify(log)}, args.join(" ") + "\\n");
+if (args[0] === "auth") process.exit(0);
+const all = args.join(" ");
+if (all.includes("addDiscussionComment")) { console.log(JSON.stringify({ data: { addDiscussionComment: { comment: { url: "https://example.invalid/c/1" } } } })); process.exit(0); }
+console.log(JSON.stringify({ data: { repository: { discussion: { id: "D_test" } } } }));
+`, "utf8");
+  return { log, env: { AQK_GH: `node ${script.replace(/\\\\/g, "/")}` } };
+}
+
+const posix = (s) => String(s).replace(/\\/g, "/");
+
+// ГЛАВНОЕ УТВЕРЖДЕНИЕ ФАЙЛА.
+test("без --send команда не зовёт gh ни разу", (t) => {
+  const p = project(t, { "AGENTS.md": "# проект\n", ".aqk.yml": 'aqk: 1\nentry:\n  - AGENTS.md\ngates:\n  lint: "true"\n' });
+  const g = fakeGh(p);
+  const r = aqkEnv(p, g.env, "feedback");
+  assert.ok(!existsSync(g.log),
+    `команда без --send позвала gh — то есть отправила что-то наружу без слова человека. Вывод:\n${r.out}`);
+  assert.match(r.out, /###/, `отчёт не напечатан вовсе. Вывод:\n${r.out}`);
+});
+
+test("и с чужими доводами рядом — тоже не зовёт", (t) => {
+  const p = project(t, { "AGENTS.md": "# проект\n" });
+  const g = fakeGh(p);
+  aqkEnv(p, g.env, "feedback", "--verbose", "что-то своими словами");
+  assert.ok(!existsSync(g.log), "слово без флага прочиталось как разрешение отправить");
+});
+
+test("с --send отправка происходит и адрес показан человеку", (t) => {
+  const p = project(t, { "AGENTS.md": "# проект\n", ".aqk.yml": 'aqk: 1\nentry:\n  - AGENTS.md\ngates:\n  lint: "true"\n' });
+  const g = fakeGh(p);
+  const r = aqkEnv(p, g.env, "feedback", "--send");
+  assert.ok(existsSync(g.log), `с --send gh не позвался вовсе. Вывод:\n${r.out}`);
+  const calls = readFileSync(g.log, "utf8");
+  assert.match(calls, /auth/, "вход не проверялся — отправили бы вслепую");
+  assert.match(calls, /addDiscussionComment/, `комментарий не отправлялся. Вызовы:\n${calls}`);
+  assert.match(r.out, /example\.invalid/, `человеку не показали, куда ушёл отзыв. Вывод:\n${r.out}`);
+});
+
+// Своя строка — самое ценное во всём письме, и она обязана доехать целиком.
+test("слова человека попадают в отправленное", (t) => {
+  const p = project(t, { "AGENTS.md": "# проект\n" });
+  const g = fakeGh(p);
+  aqkEnv(p, g.env, "feedback", "--send", "у меня не нашёл ни одного гейта");
+  const calls = readFileSync(g.log, "utf8");
+  assert.match(calls, /не нашёл ни одного гейта/, `строка человека потерялась. Вызовы:\n${calls}`);
+});
+
+// «Не смогли» и «отправлено» обязаны различаться: молчаливый отказ здесь означал бы, что человек
+// считает отзыв ушедшим, а его нет. Тот же договор, что у гейтов.
+test("без входа в gh команда говорит это вслух и не молчит", (t) => {
+  const p = project(t, { "AGENTS.md": "# проект\n" });
+  const script = join(p.dir, "no-auth.mjs");
+  writeFileSync(script, 'process.exit(1);\n', "utf8");
+  const r = aqkEnv(p, { AQK_GH: `node ${posix(script)}` }, "feedback", "--send");
+  assert.doesNotMatch(r.out, /example\.invalid/, "сказали, что отправили, хотя не смогли");
+  assert.match(r.out, /github\.com/, `не дали запасного пути — человек остался ни с чем. Вывод:\n${r.out}`);
+});