agent-quality-kit 0.14.0 → 0.16.0

package/tool/commands/feedback.mjs

@@ -0,0 +1,231 @@
+// tool/commands/feedback.mjs — `aqk feedback`: единственная плата за комплект — один ответ.
+//
+// ЗАЧЕМ. Замер 2026-09-14: 1342 скачивания в неделю в npm и ни одного пользователя — версии
+// качаются равномерно, включая прожившую двадцать пять минут, то есть это зеркала и сканеры. На
+// GitHub за две недели семь уникальных посетителей, две звезды, ноль чужих комментариев за всё
+// время. Обратной связи нет не потому, что люди молчат: просить мы не умеем. Единственная
+// просьба печаталась при `init` — ДО того, как комплект сделал хоть что-то полезное, — и звала
+// поставить звезду, то есть просила у человека, которому ещё ничего не дали.
+//
+// ЧТО ЗДЕСЬ ДРУГОЕ. Просим, только когда есть что рассказать, и рассказ уже собран: версия,
+// уровень, стек, что покраснело, чего комплект НЕ СМОГ проверить, какие классы брака не ловит
+// никто. Человеку остаётся одна строка своими словами.
+//
+// ЧЕГО ЗДЕСЬ НЕТ И НЕ БУДЕТ. Ничего не отправляется само. Исходящий запрос у комплекта ровно
+// один — про свежесть версии, он описан в README и SECURITY.md. Отчёт печатается и отдаётся
+// человеку: он видит глазами всё, что отправляет. Ни путей, ни содержимого файлов, ни имени
+// репозитория в отчёте нет — иначе первый же внимательный читатель назовёт это телеметрией,
+// и будет прав.
+import { readFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { PKG_ROOT, SELF, REPO_URL, c, stateDirs } from "../lib/core.mjs";
+import { askAllowed, markAsked } from "../lib/ask.mjs";
+import { join } from "node:path";
+import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { detectFacts } from "../lib/repo.mjs";
+import { declaredGates, readRun } from "../lib/run.mjs";
+import { probeStatus } from "./probe.mjs";
+import { L } from "../i18n/index.mjs";
+
+// О ЧЁМ ПРОСИТЬ — чистая функция от состояния. Порядок не по нашему удобству, а по ценности
+// ответа для того, кто чинит комплект:
+//   1. НЕ СМОГЛИ ПРОВЕРИТЬ — отказ самого прибора. Это жалоба, а жалоба даётся людям легче
+//      похвалы, и она же показывает, где инструмент врёт. Дороже всего остального.
+//   2. СЛЕПОЙ КЛАСС — проба подсадила брак, и его не поймал никто. Рассказ об этом проверяет
+//      главное наше утверждение: что проба находит настоящие дыры, а не выдуманные.
+//   3. КРАСНЫЙ ГЕЙТ — комплект поймал то, ради чего его ставят. Момент пользы, но самый частый,
+//      поэтому последний.
+// Ничего из перечисленного нет — просьбы нет вовсе. «Оставьте отзыв» без содержания это шум,
+// а шум выключают вместе с хуком, в котором он приехал.
+function feedbackAsk(state = {}) {
+  const pick = (kind, list) => (list && list.length ? { reason: kind, names: [...list] } : null);
+  return pick("cannot", state.cannot) || pick("blind", state.blind) || pick("red", state.red) || null;
+}
+
+// ОТЧЁТ. Каждая строка — либо факт, либо слово «неизвестно»: пустое место в письме читается как
+// «всё хорошо» ровно так же, как пустой вывод проверки, и это тот же порок, только у нас самих.
+//
+// Слепые классы называются именем класса, без файла. Файл знает проба («blind-class: slug path»), и
+// соблазн положить его сюда велик — он объясняет находку. Нельзя: путь внутри чужого
+// репозитория рассказывает о чужом проекте больше, чем его владелец собирался рассказать.
+function reportText(state = {}, T = L.feedback.report) {
+  const u = T.unknown;
+  const list = (xs) => (xs && xs.length ? xs.join(", ") : T.none);
+  return [
+    T.title,
+    "",
+    T.env(state.version || u, state.node || u, state.platform || u),
+    T.level(state.level === null || state.level === undefined ? u : `AQK-${state.level}`),
+    T.stack(state.langs && state.langs.length ? state.langs.join(", ") : u),
+    T.gates(state.gates === undefined ? u : state.gates, list(state.red), list(state.cannot)),
+    // `null` — проба не делалась: это НЕИЗВЕСТНО, а не «нет». Пустой список означал бы, что
+    // проба прошла и ничего не нашла, — и автор письма прочитал бы чужое незнание как чистоту.
+    T.blind(state.blind === null || state.blind === undefined
+      ? u
+      : list(state.blind.map((b) => (typeof b === "string" ? b : b.slug)))),
+    "",
+    T.say,
+    "",
+    // Слова человека — туда же, где приглашение их написать. Пусто — остаётся приглашение:
+    // отправленное письмо без единой своей строки всё равно полезно, но сказать об этом надо.
+    ...(state.note ? [state.note, ""] : []),
+    T.mark(state.version || u),
+  ];
+}
+
+// КАК ЭТО ЗВУЧИТ — один текст на два места: `context` кладёт его агенту, `doctor` печатает
+// человеку. Собери строку в каждом месте отдельно — и через месяц они разойдутся, как разошлись
+// бы `context` и `prompt` без общего `readAdvice`.
+//
+// АГЕНТУ — ОТДЕЛЬНАЯ ОГОВОРКА, и она не вежливость. Строка ложится в контекст ЧУЖОГО агента, а
+// он исполняет написанное: без «скажи один раз и не настаивай» это реклама в чужом окне, и хук,
+// которым она приехала, снесут в первый же день вместе со всей затеей. Человеку вместо неё —
+// как выключить: у всего, что случается само, обязан быть выключатель.
+function askLine(ask, self = "aqk", { agent = false } = {}, T = L.feedback.ask) {
+  if (!ask || !ask.reason) return null;
+  const say = T[ask.reason];
+  if (!say) return null;
+  // Перенос, а не пробел: команда обязана оставаться ПОСЛЕДНЕЙ в своей строке — иначе
+  // следующее слово приклеится к ней при копировании, и человек выполнит не то.
+  return `${say(ask.names.join(", "), `${self} feedback`)}\n${agent ? T.agent : T.once}`;
+}
+
+// Выключатель — тот же, что у совета (AQK_ADVICE=0), пробы (AQK_PROBE=0) и проверки версии
+// (AQK_UPDATE=0). Молчаливой просьбы, которую нельзя отменить, у нас не будет.
+function feedbackWanted(env = process.env) {
+  return String(env.AQK_FEEDBACK || "") !== "0";
+}
+
+// ОДНА ПРОСЬБА НА ПРОЕКТ — и решение, и ограничитель, и отметка здесь. `doctor` и `context`
+// только печатают: разведи это по двум командам, и они разойдутся в условиях, а человек получит
+// просьбу дважды. Кто первым дошёл, тот и спросил.
+//
+// Ничего не роняет: просьба об одолжении не имеет права стоить человеку прогона.
+async function maybeAsk(state, self, { agent = false } = {}) {
+  if (!feedbackWanted()) return null;
+  try {
+    const dirs = stateDirs();
+    if (!(await askAllowed("value", dirs))) return null;
+    const line = askLine(feedbackAsk(state), self, { agent });
+    if (line) await markAsked("value", dirs);
+    return line;
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ОТПРАВКА — ТОЛЬКО ПО ЯВНОМУ СЛОВУ, И СЛОВО ЭТО `--send`.
+//
+// Владелец 2026-09-14 спросил, нельзя ли отправлять отзыв «без согласия пользователя, чтобы
+// агент мог быстро сообщить». Нельзя, и не из вежливости: в README и SECURITY.md написано, что
+// исходящий запрос у комплекта ровно один — про версию. Инструмент, который втихую шлёт что-то
+// из ЧУЖОГО репозитория, становится ровно тем, что мы критикуем, а наша аудитория — это те, кто
+// проверяет инструменты на вранье. Одного внимательного читателя хватит.
+//
+// Поэтому согласие живёт в самом флаге: `--send` не набирают случайно, а агенту в умениях
+// сказано показать текст человеку и спросить. Утверждение «без флага не уходит ничего» держит
+// машина — smoke/feedback-send.test.mjs, — а не наше обещание в документации.
+//
+// ОТ ЧЬЕГО ИМЕНИ. От самого человека, его же `gh`. Своего сервера у нас нет и не будет: он
+// означал бы приём чужих данных, а значит и ответственность за них.
+const DISCUSSION = 90;
+
+function sendWanted(argv = process.argv) {
+  return argv.includes("--send");
+}
+
+// Своя строка человека — самое ценное во всём письме. Берём всё, что не флаг.
+function userNote(argv = process.argv) {
+  const i = argv.indexOf("feedback");
+  return (i === -1 ? [] : argv.slice(i + 1)).filter((a) => !a.startsWith("-")).join(" ").trim();
+}
+
+// Чем звать gh. Подменяется `AQK_GH` — тот же приём, что у `AQK_BASH` в execution.mjs: у всего,
+// что мы решаем сами, обязан быть способ решить иначе. Через него же проверки подставляют
+// поддельный gh и убеждаются, что без флага его не зовут вовсе.
+function ghArgs(env = process.env) {
+  return String(env.AQK_GH || "gh").split(/\s+/).filter(Boolean);
+}
+
+// Запуск БЕЗ оболочки: в теле отзыва переносы строк, кавычки и обратные апострофы, и оболочка
+// разобрала бы их как свои. Доводы уходят массивом — разбирать нечего.
+function gh(args, timeout = 30000) {
+  const [bin, ...pre] = ghArgs();
+  return spawnSync(bin, [...pre, ...args], { encoding: "utf8", timeout });
+}
+
+const Q_ID = `query($o:String!,$n:String!){repository(owner:$o,name:$n){discussion(number:${DISCUSSION}){id}}}`;
+const Q_ADD = "mutation($id:ID!,$body:String!){addDiscussionComment(input:{discussionId:$id,body:$body}){comment{url}}}";
+
+// Три исхода, как везде: отправлено · не смогли и сказали почему · входа нет. Молчаливый отказ
+// означал бы, что человек считает отзыв ушедшим, а его нет.
+function postComment(body, repo) {
+  if (gh(["auth", "status"], 15000).status !== 0) return { ok: false, reason: "no-auth" };
+  const [owner, name] = repo;
+  const one = gh(["api", "graphql", "-f", `query=${Q_ID}`, "-f", `o=${owner}`, "-f", `n=${name}`]);
+  let id = "";
+  try { id = JSON.parse(one.stdout || "{}").data.repository.discussion.id; } catch { /* разберём ниже */ }
+  if (!id) return { ok: false, reason: "no-thread" };
+  const two = gh(["api", "graphql", "-f", `query=${Q_ADD}`, "-f", `id=${id}`, "-f", `body=${body}`]);
+  let url = "";
+  try { url = JSON.parse(two.stdout || "{}").data.addDiscussionComment.comment.url; } catch { /* разберём ниже */ }
+  return url ? { ok: true, url } : { ok: false, reason: "failed" };
+}
+
+// Предзаполненная ссылка. Параметры `title` и `body` — документация GitHub («Creating an issue
+// from a URL query», сверено 2026-09-14). Кодируется ВСЁ: в теле переносы строк, решётки и
+// пробелы, и незакодированная ссылка обрывается на первом же из них — а всё после решётки
+// браузер считает якорем и не передаёт вовсе.
+function issueUrl(repo, title, body) {
+  const q = `title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`;
+  return `${String(repo).replace(/\/+$/, "")}/issues/new?${q}`;
+}
+
+async function cmdFeedback() {
+  const T = L.feedback;
+  const man = await readManifest();
+  let version = "";
+  try { version = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || ""; } catch { /* версия просто не покажется */ }
+
+  const run = await readRun();
+  let facts = null;
+  try { facts = await detectFacts(man); } catch { /* стек не определили — скажем «неизвестно» */ }
+  let level = null;
+  if (man?.aqk) { try { level = (await assessLevel(man, null)).reached; } catch { /* уровень не посчитали */ } }
+  // Классы известны только когда проба ДЕЙСТВИТЕЛЬНО проходила. «Никогда», «выключена» и «не
+  // знаем» — это null, то есть «неизвестно»: см. договор в reportText.
+  let blind = null;
+  try {
+    const st = await probeStatus();
+    if (st.state === "fresh" || st.state === "stale") blind = st.classes || [];
+  } catch { /* пробы не было — так и скажем */ }
+
+  const lines = reportText({
+    version, node: process.version, platform: process.platform, level,
+    langs: facts?.langs ? [...facts.langs] : [],
+    gates: declaredGates(man).length,
+    red: run?.red || [], cannot: run?.cannot || [], blind, note: userNote(),
+  });
+  const body = lines.join("\n");
+  console.log(`\n${body}\n`);
+
+  // ОТПРАВКА — ТОЛЬКО ПО ФЛАГУ. Без него ниже печатается ссылка, и это весь путь наружу.
+  if (sendWanted()) {
+    console.log(c.dim(`  ${T.sending}`));
+    const repo = REPO_URL.replace(/^https?:\/\/github\.com\//, "").split("/");
+    const r = postComment(body, repo);
+    if (r.ok) { console.log(c.green(`  ${T.sent(r.url)}\n`)); return; }
+    console.log(c.yellow(`  ${T.sendFailed[r.reason] || T.sendFailed.failed}\n`));
+  }
+
+  console.log(c.bold(`  ${T.how}`));
+  console.log(`  ${issueUrl(REPO_URL, T.issueTitle, body)}\n`);
+  console.log(c.dim(`  ${T.nothingSent}`));
+  console.log(c.dim(`  ${T.sendHow(`${SELF} feedback --send`)}`));
+  console.log(c.dim(`  ${T.orPaste(`${SELF} feedback`)}\n`));
+  // Код возврата всегда 0: команда, которая просит об одолжении и роняет при этом конвейер, —
+  // последнее, что человек стерпит.
+}
+
+export { cmdFeedback, feedbackAsk, reportText, issueUrl, askLine, feedbackWanted, maybeAsk };

package/tool/commands/gates.mjs

@@ -15,7 +15,7 @@ import {
 } from "../lib/repo.mjs";
 import { GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE } from "../lib/templates.mjs";
 import { L } from "../i18n/index.mjs";
-import { gateCommand } from "../lib/execution.mjs";
+import { gateCommand, gateTimeout } from "../lib/execution.mjs";
 
 // Ставит гейт из каталога в проект. Проверка КОПИРУЕТСЯ в репозиторий, а не остаётся
 // ссылкой в пакет: при установке через npx пакет временный, и завтра команда в манифесте
@@ -43,7 +43,11 @@ async function installGate(slug, man, facts) {
 
   // Общий список исключений едет вместе с проверкой: без него она читает окружение и
   // зависимости, и человек получает тысячу чужих нарушений вместо сотни своих.
-  for (const helper of ["_skip.sh", "_native.sh"]) {
+  // `_target.sh` добавлен 2026-09-15 вместе с общим швом «судим только то, что можем разрешить».
+  // Без него скопированный гейт выходит с кодом 2 — это честно, но у человека он не работает.
+  // Поймано нашим же смоуком в день правки: список помощников тут — единственное место, и
+  // забыть его значит выпустить гейт, который у чужого проекта не запускается вовсе.
+  for (const helper of ["_skip.sh", "_native.sh", "_target.sh"]) {
     const from = join(GATES_SRC, helper);
     if (await exists(from)) await copyFile(from, join(CWD, PROJECT_GATES, helper));
   }
@@ -170,8 +174,10 @@ async function cmdNew(args) {
   // зовут установленные записи каталога. В самом комплекте оригинал уже лежит на месте (../),
   // в чужом проекте его никто не клал, пока не было ни одной установленной записи через `add`.
   if (!inKit) {
-    const skipSrc = join(GATES_SRC, "_skip.sh");
-    if (await exists(skipSrc)) await copyFile(skipSrc, join(CWD, PROJECT_GATES, "_skip.sh"));
+    for (const helper of ["_skip.sh", "_target.sh"]) {
+      const from = join(GATES_SRC, helper);
+      if (await exists(from)) await copyFile(from, join(CWD, PROJECT_GATES, helper));
+    }
   }
 
   console.log(c.bold(`\naqk new ${slug}\n`));
@@ -231,7 +237,7 @@ async function cmdRatchet(args) {
 
   // Снимок текущих нарушений — это и есть долг. Ключ без номера строки: правка соседней
   // строки не должна читаться как новое нарушение.
-  const r = spawnSync(gateCommand(inner), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+  const r = spawnSync(gateCommand(inner), { shell: true, cwd: CWD, encoding: "utf8", timeout: gateTimeout().ms });
   if (r.status === 127 || (r.error && r.error.code === "ENOENT")) {
     die(L.ratchet.notRunnable(slug, inner));
   }
@@ -439,7 +445,7 @@ async function cmdWhy(args) {
 
   // --- 3. объявлен: спрашиваем у него самого ---------------------------------
   console.log(c.dim(`  ${L.why.declaredAs(cmd)}`));
-  const r = spawnSync(gateCommand(String(cmd)), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+  const r = spawnSync(gateCommand(String(cmd)), { shell: true, cwd: CWD, encoding: "utf8", timeout: gateTimeout().ms });
   const ci = await runsInCi(slug, String(cmd));
 
   if (r.status === 127 || (r.error && r.error.code === "ENOENT")) {

package/tool/commands/project.mjs

@@ -6,7 +6,8 @@ import { spawnSync } from "node:child_process";
 import { join, dirname, relative } from "node:path";
 import {
   CWD, PKG_ROOT, DOCS_SRC, RULES_SRC, TARGET_DIR, MANIFEST, SELF, REPO_URL, c, exists, die,
-  copyDir, writeIfAbsent, FEEDBACK_MARK, docPath, ensureIgnored } from "../lib/core.mjs";
+  copyDir, writeIfAbsent, stateDirs, docPath, ensureIgnored } from "../lib/core.mjs";
+import { askAllowed, markAsked } from "../lib/ask.mjs";
 import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
 import { banner } from "../lib/banner.mjs";
 import { readManifest } from "../lib/manifest.mjs";
@@ -95,7 +96,10 @@ ${c.dim(L.init.burned(`${SELF} note "…"`))}
 // Ничего не постится само: ссылки печатаются, дальше решает человек. Обратная связь важнее
 // звезды, но без звезды меньше шансов, что кто-то вообще дойдёт до фидбека.
 async function maybeAskFeedback() {
-  if (await exists(FEEDBACK_MARK)) return;
+  // Ограничитель — общий на все обращения комплекта (ask.mjs). Вид `install` разовый и живёт
+  // в доме пользователя: второй init в другом репозитории на том же компьютере молчит.
+  const dirs = stateDirs();
+  if (!(await askAllowed("install", dirs))) return;
   const url = REPO_URL;
   console.log(`
 ${c.bold(L.feedback.title)}
@@ -104,20 +108,14 @@ ${c.bold(L.feedback.title)}
     ${url}/issues/new
 ${c.dim(`  ${L.feedback.once}`)}
 `);
-  // Пометка «уже показывали» — удобство, а не работа команды. Домашнего каталога может не быть
-  // записываемым вовсе: в контейнере, запущенном `--user 1001:127`, у этого uid нет записи в
-  // /etc/passwd, `homedir()` даёт «/», и запись падает с EACCES на `/.config`. До 2026-09-09
-  // это роняло ВЕСЬ `init` — то есть любого, кто набрал команду из нашей же документации по
-  // docker. Локально не воспроизводилось случайно: uid разработчика 1000 совпадает с
-  // пользователем `node` в образе, у которого дом есть. Нашёл конвейер, где uid 1001.
+  // Пометка «уже показывали» — удобство, а не работа команды: `markAsked` не бросает, а
+  // возвращает, записалось ли. Дом бывает недоступен для записи (в контейнере с `--user
+  // 1001:127` у этого uid нет записи в /etc/passwd, homedir() даёт «/»), и до 2026-09-09 это
+  // роняло ВЕСЬ `init` — то есть любого, кто набрал команду из нашей же документации по docker.
   //
   // Молча глотать нельзя — это то, что красит наш же swallowed-error. Поэтому вслух: не
   // запомнили, покажем снова. Установка при этом доходит до конца.
-  try {
-    await writeIfAbsent(FEEDBACK_MARK, "shown\n", { force: false });
-  } catch {
-    console.log(c.dim(`  ${L.feedback.notRemembered}`));
-  }
+  if (!(await markAsked("install", dirs))) console.log(c.dim(`  ${L.feedback.notRemembered}`));
 }
 
 function findJournal() {

package/tool/commands/prompt.mjs

@@ -15,7 +15,8 @@
 import { readManifest } from "../lib/manifest.mjs";
 import { claudeShimFor } from "../lib/repo.mjs";
 import { CWD, SELF } from "../lib/core.mjs";
-import { readRun, readAdvice, portableSelf } from "./context.mjs";
+import { readAdvice, portableSelf } from "./context.mjs";
+import { readRun } from "../lib/run.mjs";
 import { probeStatus } from "./probe.mjs";
 import { L } from "../i18n/index.mjs";
 

package/tool/commands/report.mjs

@@ -215,11 +215,27 @@ async function cmdReport() {
 
   const text = lines.join("\n") + "\n";
   const dst = join(CWD, TARGET_DIR, "report.md");
-  await mkdir(join(CWD, TARGET_DIR), { recursive: true });
-  await writeFile(dst, text, "utf8");
+
+  // ОТЧЁТ — ЭТО ЧТЕНИЕ, И ПАДАТЬ ЕМУ НЕ НА ЧЕМ. Разбор чужой интеграции 2026-09-16: в рабочей
+  // области, где `.aqk/` не создать, команда падала с EROFS, не напечатав ни строки. То есть
+  // побочное действие, о котором не просили, отменяло то, ради чего команду звали. Такие
+  // области бывают не по недосмотру: read-only контейнер, чужой конвейер, каталог под ревью.
+  //
+  // Молчать о несохранённом тоже нельзя: человек, увидевший отчёт, вправе считать, что файл
+  // лежит на диске, — если ему не сказали иначе. Тот же принцип, что и везде: не смогли —
+  // назови, а не выдавай за сделанное.
+  let saveError = null;
+  try {
+    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+    await writeFile(dst, text, "utf8");
+  } catch (e) {
+    saveError = e?.code || String(e?.message || e);
+  }
 
   console.log("\n" + text);
-  console.log(c.dim(`  ${L.report2.saved(join(TARGET_DIR, "report.md"))}\n`));
+  console.log(saveError
+    ? c.yellow(`  ${L.report2.notSaved(join(TARGET_DIR, "report.md"), saveError)}\n`)
+    : c.dim(`  ${L.report2.saved(join(TARGET_DIR, "report.md"))}\n`));
 
   // Код возврата — для конвейера и для агента: отчёт с красным гейтом не должен читаться
   // как «всё в порядке» только потому, что команда выполнилась.

package/tool/commands/vitals.mjs

@@ -45,10 +45,16 @@ function vitalsRows(f) {
       ok: f.unparsed > 0 ? false : true,
       detail: f.unparsed > 0 ? t.manifestBad(f.unparsed) : t.manifestOk,
     },
+    // ЧЕТЫРЕ ОТВЕТА ПРО ХУК. «Хук чужой» — не «хука нет»: в одном случае ставить нечего, в
+    // другом дописать строку в уже стоящий. Совет разный, значит и строка разная. Ни то ни
+    // другое не отказ: AQK могут сознательно гонять в конвейере.
     {
       key: "preCommit",
-      ok: f.preCommit === null ? null : f.preCommit ? true : "no",
-      detail: f.preCommit === null ? t.unknownHook : f.preCommit ? t.preCommitOk : t.preCommitNo,
+      ok: f.preCommit === null ? null : f.preCommit === true ? true : "no",
+      detail: f.preCommit === null ? t.unknownHook
+        : f.preCommit === true ? t.preCommitOk
+        : f.preCommit === "other" ? t.preCommitOther
+        : t.preCommitNo,
     },
     {
       key: "sessionHook",
@@ -110,7 +116,7 @@ async function cmdVitals() {
   // Найдено 2026-09-09 сверкой вывода двух команд на одном репозитории.
   const samplesDir = typeof man?.samples === "string" ? man.samples.trim() : "";
   for (const gate of Object.keys(gates)) {
-    const missing = await gateRequires(samplesDir, gate, whichSync);
+    const missing = await gateRequires(man, samplesDir, gate, whichSync);
     for (const prog of missing || []) {
       if (seen.has(prog)) continue;
       seen.set(prog, { gate, prog, found: false });

package/tool/i18n/en-docs.mjs

@@ -26,6 +26,9 @@ const enDocs = {
     unknownHook: "could not look — unknown, not \"no\"",
     preCommitOk: "wired in .git/hooks",
     preCommitNo: "not in .git/hooks: a config entry is an intent, not a guard",
+    // A hook IS there, but not ours: nothing to install, something to add — a different
+    // remedy, hence a different line. Until 2026-09-16 this case printed as "wired".
+    preCommitOther: "a .git/hooks hook exists, but AQK is not called from it — check .pre-commit-config.yaml or the hook body",
     sessionOk: "the SessionStart hook hands the state to the agent",
     sessionNo: (cmd) => `the agent gets no state: ${cmd}`,
     versionOk: (v) => `${v}, current`,
@@ -63,6 +66,7 @@ const enDocs = {
       "No run has been made — which checks are red is UNKNOWN. This is not \"clean\": `aqk doctor --run`.",
     runStale: (when) =>
       `The last run ${when} is OLDER than the last commit — it describes different code.`,
+    runCannot: (names) => `COULD NOT CHECK (the checks themselves failed — not findings about the code): ${names}`,
     runClean: (when) => `Last run ${when} — nothing red.`,
     runRed: (when, names) => `Last run ${when} — RED: ${names}.`,
     andMore: (n) => `and ${n} more`,
@@ -82,7 +86,16 @@ const enDocs = {
     nextTitle: "Next, in order — computed from this repository, not generic advice:",
     nextStep: {
       init: () => "Set up the standard: `aqk init` — without .aqk.yml `aqk add` refuses.",
-      adopt: (s) => `Declare the checks this project already has: in .aqk.yml, under gates: ${s.gates.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Then \`aqk doctor --run\`.`,
+      // Слабые НЕ ПОПАДАЮТ в «впиши в манифест»: агент исполняет написанное, и объявленная
+      // проверка с `|| true` — это дыра, за которую с этого дня ручается машина.
+      adopt: (s) => {
+        const ok = s.gates.filter((g) => !g.weak);
+        const weak = s.gates.filter((g) => g.weak);
+        const out = [];
+        if (ok.length) out.push(`Declare the checks this project already has: in .aqk.yml, under gates: ${ok.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Then \`aqk doctor --run\`.`);
+        if (weak.length) out.push(`These cannot go red as written — ${weak.map((g) => `${g.cmd} (${g.weak.text})`).join(", ")} — so do not declare them yet: tell the owner and fix the command first.`);
+        return out.join(" ");
+      },
       blind: (s) => `The "${s.slug}" defect the probe planted in ${s.file} was NOT caught by your checks.` +
         (s.command ? ` Catch it now: \`${s.command}\`.` : "") + ` Keep it caught: \`aqk add ${s.slug}\`.`,
       start: (s) => `Install ${s.slug}: \`aqk add ${s.slug}\`` + (s.command ? ` (one line, no kit needed: \`${s.command}\`)` : "") +
@@ -92,7 +105,9 @@ const enDocs = {
     whenTitle: "When to do what:",
     whenCommit: (hook) => hook === true
       ? "Before a commit → the `.git/hooks/pre-commit` hook runs the checks itself; do not bypass it (`--no-verify`)."
-      : "Before a commit → `aqk doctor --run --since main`: there is no pre-commit hook, it will not happen by itself.",
+      : hook === "other"
+        ? "Before a commit → `aqk doctor --run --since main`: a hook is installed in `.git/hooks`, but AQK is not called from it — the run will not happen by itself."
+        : "Before a commit → `aqk doctor --run --since main`: there is no pre-commit hook, it will not happen by itself.",
     whenRules: [
       "Added or changed a check → `aqk prove`: the gate must go red on its own red sample, otherwise it checks nothing.",
       "Writing a rule into the rulebook → put the arbiter mark next to it, `<!-- aqk: gate-name -->`; no gate — `<!-- aqk: human -->`, which is an admission, not a check.",
@@ -154,6 +169,7 @@ const enDocs = {
     whyTitle: "Why this matters — briefly",
     whyNothing: "nothing to add: everything applicable is in place",
     saved: (path) => `Saved: ${path}`,
+    notSaved: (f, why) => `could not save to ${f} (${why}) — the report is above, there is no file on disk. The command only reports state, so a failed write does not fail it.`,
     docs: {
       baseline: "the minimum a project needs, independent of language",
       readyMade: "the map of off-the-shelf rules: look for a ready one before writing your own",
@@ -217,6 +233,7 @@ const enDocs = {
   ],
   report: {
     skippedBySelect: "not run (by --only/--skip), state unknown",
+    notWritten: (f, why) => `could not write the run report to ${f} (${why}) — the gates did run, but the next session and the hook will read this as "no run happened".`,
     title: "aqk doctor --run",
     version: "version",
     level: "level",

package/tool/i18n/en-gates.mjs

@@ -185,6 +185,41 @@ export const enGates = {
     issue: "Found a bug or it did not fit — open an issue; both are the most useful feedback there is.",
     notRemembered: "could not remember this (home is not writable) — the message will appear again",
     once: "This message is shown once: it will not appear again on this machine.",
+
+    ask: {
+      cannot: (names, cmd) =>
+        `AQK could not check: ${names}. That is the most valuable thing to tell the author — ${cmd}`,
+      blind: (names, cmd) =>
+        `The probe found defect classes nobody catches here: ${names}. Does that match your experience? — ${cmd}`,
+      red: (names, cmd) =>
+        `The kit caught: ${names}. One line to the author — did it help: ${cmd}`,
+      once: "Asked once per project; switch it off with AQK_FEEDBACK=0",
+      agent: "Say this to the human in one sentence, and do not insist if they do not answer. If they want to send it, add `--send`; never add the flag on your own.",
+    },
+    sending: "sending on your behalf — with your own gh account…",
+    sent: (url) => `sent: ${url}\n  That is the whole price of this kit. Thank you.`,
+    sendFailed: {
+      "no-auth": "could not send: gh is missing or you are not logged in (`gh auth login`). The link below always works.",
+      "no-thread": "could not send: the discussion was not found. Use the link below.",
+      failed: "could not send. The link below always works.",
+    },
+    sendHow: (cmd) => `Send it in one command, with your own GitHub account: ${cmd}`,
+    how: "Sending is one click (a prefilled issue opens; the text stays editable):",
+    issueTitle: "Feedback on the kit",
+    nothingSent: "Nothing was sent: the kit makes no outgoing requests other than the version check.",
+    orPaste: (cmd) => `No GitHub? Forward the text above as is — all of it comes from ${cmd}`,
+    report: {
+      title: "### Feedback on the kit",
+      unknown: "unknown",
+      none: "none",
+      env: (v, node, os) => `version: ${v} · node: ${node} · system: ${os}`,
+      level: (x) => `level: ${x}`,
+      stack: (x) => `stack: ${x}`,
+      gates: (n, red, cannot) => `gates declared: ${n} · red: ${red} · could not check: ${cannot}`,
+      blind: (x) => `classes nobody catches here: ${x}`,
+      say: "What you would say in your own words (one line — the most useful part of the whole message):",
+      mark: (v) => `<!-- collected by "aqk feedback" ${v}: no paths, no code, no repository name -->`,
+    },
   },
 
   note: {

package/tool/i18n/en.mjs

@@ -50,6 +50,8 @@ export const en = {
     blob: "assemble the guides into a single GOD_AI.md",
     learn: "rule candidates from local transcripts: said out loud, never written down",
     context: "the project state in one block — for an agent's context, not for reading",
+    feedback: "a report on how the kit worked plus a prefilled link — the only payment it asks",
+    feedbackSend: "send the feedback in one command — with your own gh account; without the flag nothing leaves",
     vitals: "is what the kit runs on wired up: gate tools, hooks, version freshness",
     prompt: "one task for the agent: what to fix, in order, and how to prove it is done",
     contextInstall: "the same in full — the map and the rulebook — installed as a hook",
@@ -152,7 +154,17 @@ export const en = {
     startHook: "Running these by hand is a one-off. To have them run before every push: pre-commit (repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit, hooks aqk / aqk-doctor), or a plain .git/hooks/pre-push.",
     haveAlready: (n) => `Checks you ALREADY have (${n}) — found in your own files, not invented:`,
     haveAlreadyHow: (line) => `declare them and a machine holds them, not your attention. In .aqk.yml, under gates:  ${line}`,
-    total: "Total:",
+    // Проверка, которая у проекта ЕСТЬ и провалиться НЕ МОЖЕТ. Самое ценное, что мы знаем о
+    // чужом репозитории в первые пять секунд, — и до 2026-09-14 мы об этом молчали.
+    weakOff: (text) => `cannot fail: the verdict is swallowed right in the script — «${text}»`,
+    weakZero: () => "cannot fail: --exit-zero tells the tool to exit 0 whatever it finds",
+    weakStub: (text) => `proves nothing: the whole script is a printout — «${text}»`,
+    weakHow: (n) => `${n} of them cannot go red. Declaring a check that cannot fail only makes the ` +
+      "silence machine-readable — fix the command first, then declare it.",
+    // Counted over the AQK CATALOGUE, and the line says so: a project gate named its own way
+    // closes none of our entries by name, and "held by a machine 0" read as a verdict on a
+    // repository with thirty checks of its own. Measured 2026-09-16 across twelve repositories.
+    total: "AQK catalogue totals:",
     totalHeld: (n) => `held by a machine ${n}`,
     totalTodo: (n) => `applicable but not installed ${n}`,
     totalSkip: (n) => `hidden ${n}`,
@@ -167,7 +179,12 @@ export const en = {
       `advisory and red: ${names.join(", ")}. These are switched-off checks: ` +
       `either fix them and drop them from advisory, or admit the rule does not exist.`,
     runHeading: "Running the declared gates",
+    timeoutBadEnv: (raw, secs) => `AQK_GATE_TIMEOUT="${raw}" is not a number of seconds above zero; waiting ${secs}s as before. Zero and garbage mean "wait forever" to spawnSync, and a hung gate looks exactly like a working one.`,
     timeout: "did not finish within 5 minutes",
+    cannotCheck: (why) => `could not check: ${why}`,
+    whySpawn: (code) => `failed to start${code ? ` (${code})` : ""}`,
+    whySignal: (sig) => `killed by signal ${sig || "?"}`,
+    whyExit: (code) => `exit ${code} — for this command that is a failure, not a finding`,
     running: (i, n) => `[${i}/${n}] running…`,
     proving: "checking that the gates catch defects on their own samples…",
     exitCode: (code) => `exit ${code}`,
@@ -289,7 +306,17 @@ export const en = {
       missed: ({ slug, file }, s) => `Gate \`${slug}\` is installed but missed the defect the probe planted into \`${file}\`. Find out why — a common cause is that the gate does not look at this file type or folder; \`${s} probe\` has the details. Done — \`${s} probe\` no longer names this class.`,
       red: (name, s) => `Gate \`${name}\` is red. Run \`${s} doctor --run --only ${name}\`, read the findings and fix the code. Done — that command passes.`,
       blind: ({ slug, file, command }, s) => `The probe planted a \`${slug}\` defect into \`${file}\` and the project's checks did not notice. Add a check: \`${s} add ${slug}\`${command ? ` (the same as one line, without the kit: \`${command}\`)` : ""}. Done — \`${s} doctor --run --only ${slug}\` passes and \`${s} probe\` no longer names this class.`,
-      adopt: (gates, s) => `The project already has its own checks: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Declare them under gates: in .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Done — \`${s} doctor --run\` runs them.`,
+      // СЛАБЫЕ ОТДЕЛЯЮТСЯ ОТ РАБОЧИХ, и это не украшение вывода. Агент исполняет написанное:
+      // велеть ему «впиши эти проверки в манифест», когда одна из них `… || true`, значит руками
+      // агента превратить дыру в зелёную галочку — и с этого дня её будет держать машина.
+      adopt: (gates, s) => {
+        const weak = gates.filter((g) => g.weak);
+        const ok = gates.filter((g) => !g.weak);
+        const out = [];
+        if (ok.length) out.push(`The project already has its own checks: ${ok.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Declare them under gates: in .aqk.yml — ${ok.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Done — \`${s} doctor --run\` runs them.`);
+        if (weak.length) out.push(`These CANNOT go red as written: ${weak.map((g) => `\`${g.cmd}\` — ${g.weak.text}`).join(", ")}. Fix the command before declaring it: a declared check that cannot fail turns a hole into a green tick, and from then on a machine vouches for it. This is the owner's call, not yours — say what you found.`);
+        return out.join(" ");
+      },
       shim: {
         missing: (s) => `Claude Code is set up here, but the rules live in AGENTS.md — it only reads CLAUDE.md. Create a CLAUDE.md with the single line \`@AGENTS.md\`. Done — \`${s} doctor\` no longer warns about it.`,
         noImport: (s) => `CLAUDE.md does not import AGENTS.md — Claude Code only sees CLAUDE.md. Add the line \`@AGENTS.md\` to CLAUDE.md (mentioning the file in prose does not load it). Done — \`${s} doctor\` no longer warns about it.`,