agent-quality-kit 0.14.0 → 0.15.0

package/tool/i18n/en.mjs

@@ -50,6 +50,7 @@ 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",
     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",
@@ -168,6 +169,10 @@ export const en = {
       `either fix them and drop them from advisory, or admit the rule does not exist.`,
     runHeading: "Running the declared gates",
     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}`,

package/tool/i18n/ru-docs.mjs

@@ -65,6 +65,7 @@ const ruDocs = {
       "Прогон не делался — какие проверки красные, НЕИЗВЕСТНО. Это не «чисто»: `aqk doctor --run`.",
     runStale: (when) =>
       `Последний прогон ${when} СТАРЕЕ последнего коммита — он описывает не тот код, что здесь.`,
+    runCannot: (names) => `НЕ СМОГЛИ ПРОВЕРИТЬ (сбой самих проверок, а не находки о коде): ${names}`,
     runClean: (when) => `Последний прогон ${when} — красных нет.`,
     runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
     andMore: (n) => `и ещё ${n}`,

package/tool/i18n/ru-gates.mjs

@@ -187,6 +187,34 @@ export const ruGates = {
     issue: "Нашёл баг или не подошло — заведи Issue, самая полезная обратная связь: и то и другое.",
     notRemembered: "запомнить не удалось (дом недоступен для записи) — сообщение появится снова",
     once: "Это разовое сообщение: больше не покажется на этой машине.",
+
+    // Просьба ПО ДЕЛУ: у неё всегда есть содержание, иначе её нет вовсе.
+    ask: {
+      cannot: (names, cmd) =>
+        `AQK не смог проверить: ${names}. Это самое ценное, что можно рассказать автору — ${cmd}`,
+      blind: (names, cmd) =>
+        `Проба нашла классы брака, которые здесь не ловит никто: ${names}. Совпало с вашим опытом? — ${cmd}`,
+      red: (names, cmd) =>
+        `Комплект поймал: ${names}. Одна строка автору — помогло или нет: ${cmd}`,
+      once: "Спрашиваем один раз на проект; выключить: AQK_FEEDBACK=0",
+      agent: "Скажи это человеку одной фразой и не настаивай, если он не ответил.",
+    },
+    how: "Отправить — одно нажатие (откроется готовая задача, текст можно править):",
+    issueTitle: "Отзыв о работе комплекта",
+    nothingSent: "Ничего не отправлено: комплект не делает исходящих запросов, кроме проверки версии.",
+    orPaste: (cmd) => `Не хочется GitHub — перешлите текст выше как есть: он весь собран ${cmd}`,
+    report: {
+      title: "### Отзыв о комплекте",
+      unknown: "неизвестно",
+      none: "нет",
+      env: (v, node, os) => `версия: ${v} · node: ${node} · система: ${os}`,
+      level: (x) => `уровень: ${x}`,
+      stack: (x) => `стек: ${x}`,
+      gates: (n, red, cannot) => `гейтов объявлено: ${n} · красных: ${red} · не смогли проверить: ${cannot}`,
+      blind: (x) => `классы, которые здесь не ловит никто: ${x}`,
+      say: "Что сказать своими словами (одна строка — самое полезное во всём письме):",
+      mark: (v) => `<!-- собрано «aqk feedback» ${v}: без путей, без кода, без имени репозитория -->`,
+    },
   },
 
   note: {

package/tool/i18n/ru.mjs

@@ -53,6 +53,7 @@ export const ru = {
     blob: "собрать методички в один файл GOD_AI.md",
     learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
     context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
+    feedback: "отчёт о работе комплекта и готовая ссылка — единственная плата за него",
     vitals: "подключено ли то, чем комплект работает: инструменты гейтов, хуки, свежесть версии",
     prompt: "одно задание для агента: что починить, по порядку, и чем доказать, что готово",
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
@@ -174,6 +175,12 @@ export const ru = {
       `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
+    // «Не смогли проверить» — третье состояние, и оно обязано звучать иначе, чем находка:
+    // «код 2» человек читает как приговор коду, а это приговор запуску.
+    cannotCheck: (why) => `не смогли проверить: ${why}`,
+    whySpawn: (code) => `запустить не удалось${code ? ` (${code})` : ""}`,
+    whySignal: (sig) => `убит сигналом ${sig || "?"}`,
+    whyExit: (code) => `код ${code} — у этой команды это сбой, а не находка`,
     running: (i, n) => `[${i}/${n}] идёт…`,
     proving: "проверяю, что гейты ловят брак на своих образцах…",
     exitCode: (code) => `код ${code}`,

package/tool/lib/ask.mjs

@@ -0,0 +1,118 @@
+// tool/lib/ask.mjs — КОГДА КОМПЛЕКТ ОБРАЩАЕТСЯ К ЧЕЛОВЕКУ, и как он помнит, что уже обращался.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫЙ МОДУЛЬ. Знание «мы это показывали» жило в комплекте дважды и по-разному:
+//   · `~/.config/aqk/feedback-shown` — файл-флаг, раз на машину: заведён в `core.mjs`,
+//     прочитан в `project.mjs`;
+//   · `.aqk/advice-shown`, `.aqk/update-checked` — отметка временем плюс `adviceDue()` на
+//     сутки: заведены и прочитаны в `brief.mjs`.
+// Одно решение — «не долби человека» — в двух местах и в двух форматах. Третье обращение
+// завело бы третий формат, и дальше они расходятся молча.
+//
+// ЧТО ЗДЕСЬ ЕСТЬ И ЧЕГО НЕТ. Здесь только ОГРАНИЧИТЕЛЬ: можно ли сейчас обратиться и чем это
+// запомнить. Чего здесь нет — текста обращения и решения, есть ли о чём говорить: текст живёт
+// в каталогах строк, решение — у того, кто знает состояние проекта. Иначе модуль про «когда»
+// начал бы меняться вместе с каждой правкой формулировки.
+//
+// ЛИСТ ДЕРЕВА: импортируются только встроенные модули Node. Каталоги передаются вызывающим, а
+// не берутся из `core.mjs`, — иначе получилось бы кольцо: `core.mjs` берёт отсюда список
+// служебных файлов для `.gitignore`.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const DAY = 24 * 60 * 60 * 1000;
+
+// ТАБЛИЦА ВИДОВ. Вид объявляет две вещи, и обе нельзя угадать по имени:
+//   where — «project» (отметка про ЭТОТ репозиторий, лежит в его служебном каталоге) или
+//           «home» (отметка про ЭТУ МАШИНУ, лежит в доме пользователя);
+//   every — через сколько можно повторить; `null` означает «никогда», а не «очень нескоро».
+//
+// Имена файлов — прежние, до единой буквы: человек, у которого отметка уже лежит, не должен
+// получить обращение заново только потому, что мы переставили код.
+const ASKS = {
+  // Совет про непоставленную запись каталога — в короткой строке хука.
+  advice: { where: "project", file: "advice-shown", every: DAY },
+  // Проверка свежести версии — единственный исходящий запрос комплекта.
+  update: { where: "project", file: "update-checked", every: DAY },
+  // Просьба об отзыве после установки — раз на машину: второй `init` в другом репозитории на
+  // том же компьютере её не повторяет.
+  install: { where: "home", file: "feedback-shown", every: null },
+  // Просьба об отзыве ПО ДЕЛУ — раз на проект. Объявлена здесь до первого использования
+  // намеренно: строка в `.gitignore` обязана появиться РАНЬШЕ, чем файл будет записан, иначе
+  // отметка уедет в чужой коммит у всех, кто поставил комплект между двумя выпусками.
+  value: { where: "project", file: "feedback-asked", every: null },
+};
+
+// Опечатка в виде обращения обязана падать. Оба молчаливых умолчания неверны в половине
+// случаев: «показывать всегда» превращает ограничитель в шум, «не показывать» — выключает
+// обращение навсегда, и никто об этом не узнает.
+function askKind(kind) {
+  const a = ASKS[kind];
+  if (!a) throw new Error(`неизвестный вид обращения: ${kind}. Известны: ${Object.keys(ASKS).join(", ")}`);
+  return a;
+}
+
+// Служебные файлы ЭТОГО проекта — для `.gitignore`. Домашние сюда не идут: их git не видит.
+const ASK_FILES = Object.values(ASKS).filter((a) => a.where === "project").map((a) => a.file);
+
+// `project` — служебный каталог репозитория (тот самый `.aqk`), `home` — дом пользователя.
+// Каталог передаётся целиком, а не собирается здесь: имя `.aqk` знает `core.mjs`, и второй
+// его экземпляр однажды разошёлся бы с первым.
+function askFile(kind, { project, home } = {}) {
+  const a = askKind(kind);
+  return a.where === "home" ? join(String(home ?? ""), ".config", "aqk", a.file) : join(String(project ?? ""), a.file);
+}
+
+// Пора ли обращаться. `stamp` — содержимое отметки или null, если её нет.
+//
+// Разовое обращение: отметка есть — значит было, и повторить нельзя никогда, что бы в ней ни
+// лежало. Старый формат хранил слово «shown», а не дату: читать его как испорченную дату и
+// показывать заново значило бы повторить просьбу у всех, кто поставил комплект раньше.
+//
+// Суточное: «не знаем, когда показывали» и «показывали давно» — одно и то же решение, показать.
+// Молчать из-за нечитаемого файла состояния значит потерять обращение навсегда и не сказать
+// почему.
+function askDue(kind, stamp, now = Date.now()) {
+  const a = askKind(kind);
+  if (stamp === null || stamp === undefined || String(stamp).trim() === "") return true;
+  if (a.every === null) return false;
+  const t = Date.parse(String(stamp).trim());
+  if (!Number.isFinite(t)) return true;
+  return now - t >= a.every;
+}
+
+// Отметка с диска: строка или null. Файла нет, каталог не читается, прав не хватило — всё это
+// «не показывали»: потерять обращение из-за нечитаемой отметки дешевле, чем молчать.
+async function readStamp(kind, dirs) {
+  try {
+    return (await readFile(askFile(kind, dirs), "utf8")).trim();
+  } catch {
+    return null;
+  }
+}
+
+// Запомнить обращение. Возвращает true, если записали, — СЛОВО О НЕУДАЧЕ ГОВОРИТ ВЫЗЫВАЮЩИЙ:
+// у совета повтор это мелочь, а у разовой просьбы — та же просьба завтра, и человеку надо
+// сказать, почему она вернулась. Дом бывает недоступен для записи: в контейнере, запущенном
+// `--user 1001:127`, у этого uid нет записи в /etc/passwd, `homedir()` даёт «/», и запись
+// падает на `/.config`. До 2026-09-09 это роняло весь `init` — то есть любого, кто набрал
+// команду из нашей же документации по docker.
+async function markAsked(kind, dirs, now = new Date()) {
+  const path = askFile(kind, dirs);
+  try {
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, `${now.toISOString()}\n`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Пора ли обращаться, с чтением отметки. Две трети вызывающих хотят именно этого; чистый
+// `askDue` остаётся для перебора случаев, которых на диске не бывает.
+async function askAllowed(kind, dirs, now = Date.now()) {
+  return askDue(kind, await readStamp(kind, dirs), now);
+}
+
+// Наружу — то, что зовут снаружи. `readStamp` внутренний: снаружи спрашивают «пора ли»,
+// а не «что лежит в файле», и лишний экспорт читается как часть договора.
+export { ASKS, ASK_FILES, askDue, askFile, markAsked, askAllowed };

package/tool/lib/brief.mjs

@@ -1,6 +1,7 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CWD, PKG_ROOT, TARGET_DIR, SELF, c } from "./core.mjs";
+import { PKG_ROOT, SELF, c, stateDirs } from "./core.mjs";
+import { askAllowed, markAsked } from "./ask.mjs";
 import { L } from "../i18n/index.mjs";
 import { canDrawArt } from "./banner.mjs";
 // tool/lib/brief.mjs — короткая строка присутствия для прогона в хуке.
@@ -19,10 +20,6 @@ import { canDrawArt } from "./banner.mjs";
 // то, что видишь тридцатый раз, перестаёт читаться — и пролистывается вместе с настоящими
 // находками, стоящими рядом.
 
-// Сутки. Не «раз в прогон» и не «раз в неделю»: за сутки человек успевает забыть, но не успевает
-// устать. Число здесь спорное — важно, что ограничитель есть и он машинный.
-const ADVICE_EVERY_MS = 24 * 60 * 60 * 1000;
-
 // ЗНАЧОК ПРИСУТСТВИЯ — здесь, а не в каталогах строк. Символ один на оба языка, и держать его
 // в двух местах значит однажды получить разные значки в ru и en: то же правило, по которому у
 // нас один свод правил на две точки входа. Выбран владельцем из пятидесяти семи вариантов.
@@ -41,16 +38,6 @@ function briefLine(state, L, env = process.env) {
   return `${head}\n${t.red(state.red.join(", "))}`;
 }
 
-// «Не знаем, когда показывали» и «показывали давно» — одно и то же решение: показать.
-// Испорченная отметка попадает сюда же намеренно: молчать из-за нечитаемого файла состояния
-// значит потерять совет навсегда и не сказать почему.
-function adviceDue(lastIso, now = Date.now()) {
-  if (!lastIso) return true;
-  const t = Date.parse(String(lastIso));
-  if (!Number.isFinite(t)) return true;
-  return now - t >= ADVICE_EVERY_MS;
-}
-
 // Первая из непоставленных, а не «самая важная»: важность мы не считаем, а порядок каталога
 // осмыслен — записи в нём лежат от общего к частному. Выдавать порядок за приоритет нельзя.
 function pickAdvice(todo = []) {
@@ -112,9 +99,7 @@ function beginBrief() {
 
 // Печать краткого итога. Совет — не чаще раза в сутки и с явным способом отказаться: то, что
 // видишь тридцатый раз, перестаёт читаться и пролистывается вместе с настоящими находками рядом.
-// Отметка времени лежит в .aqk/ и попадает в .gitignore при `init` (RUNTIME_FILES в core.mjs):
-// это состояние машины, а не проекта. Раньше здесь было написано «.aqk/ в .gitignore» — а
-// `init` туда ничего не клал, и на живом проекте служебный файл уехал в коммит.
+// Сам ограничитель и отметка — в `ask.mjs`, общие на все обращения комплекта к человеку.
 async function finishBrief(buf, state, todoRecs, ok) {
   if (!buf) return;
   buf.restore();
@@ -129,18 +114,16 @@ async function finishBrief(buf, state, todoRecs, ok) {
   if (!ok) { console.log(buf.lines.join("\n")); return; }
 
   if (process.env.AQK_ADVICE === "0" || !state.todo) return;
-  const stampFile = join(CWD, TARGET_DIR, "advice-shown");
-  let last = null;
-  try { last = (await readFile(stampFile, "utf8")).trim(); } catch { /* не показывали ещё */ }
-  if (!adviceDue(last)) return;
+  // Ограничитель — общий на все обращения комплекта к человеку (ask.mjs): совет, проверка
+  // версии и просьба об отзыве считают «уже показывали» одним кодом и одним форматом.
+  const dirs = stateDirs();
+  if (!(await askAllowed("advice", dirs))) return;
   const advice = pickAdvice(todoRecs);
   if (!advice) return;
   console.log(c.dim(L.brief.advise(advice.slug, advice.intent || "")));
   console.log(c.dim(L.brief.adviseOff(`${SELF} why ${advice.slug}`, "AQK_ADVICE=0")));
-  try {
-    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
-    await writeFile(stampFile, new Date().toISOString(), "utf8");
-  } catch { /* не смогли записать отметку — совет повторится, это не беда */ }
+  // Не записалось — совет повторится завтра, и это не беда: молчать об этом человеку незачем.
+  await markAsked("advice", dirs);
 }
 
 // Спрашивает реестр npm о своей версии. РАЗ В СУТКИ, НЕ В КОНВЕЙЕРЕ, С ТАЙМАУТОМ, И МОЛЧА
@@ -152,10 +135,8 @@ async function finishBrief(buf, state, todoRecs, ok) {
 // и вместе с ним всё остальное, что печатает эта строка.
 async function maybeUpdateNotice() {
   if (!updateWanted()) return;
-  const stamp = join(CWD, TARGET_DIR, "update-checked");
-  let last = null;
-  try { last = (await readFile(stamp, "utf8")).trim(); } catch { /* ещё не спрашивали */ }
-  if (!adviceDue(last)) return;
+  const dirs = stateDirs();
+  if (!(await askAllowed("update", dirs))) return;
 
   let current = "";
   try { current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || ""; } catch { return; }
@@ -163,10 +144,7 @@ async function maybeUpdateNotice() {
   // ОТМЕТКА СТАВИТСЯ ДО ЗАПРОСА, а не после удачного ответа. Сперва было наоборот, и замер
   // показал цену: человек без сети платил бы ожиданием на КАЖДОМ коммите, а не раз в сутки.
   // Из двух ошибок выбрана дешёвая: пропущенное за день уведомление против ежедневного стопора.
-  try {
-    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
-    await writeFile(stamp, new Date().toISOString(), "utf8");
-  } catch { /* не смогли записать — спросим ещё раз, это не беда */ }
+  await markAsked("update", dirs);
 
   let latest = "";
   try {
@@ -189,6 +167,7 @@ async function maybeUpdateNotice() {
   if (notice) console.log(c.dim(notice));
 }
 
-// Наружу — только то, что зовут снаружи. `cmpVer` и `ADVICE_EVERY_MS` внутренние: экспорт,
-// который никто не импортирует, читается как часть договора и мешает менять внутренности.
-export { briefLine, adviceDue, pickAdvice, updateNotice, updateWanted, beginBrief, finishBrief };
+// Наружу — только то, что зовут снаружи. `cmpVer` внутренний: экспорт, который никто не
+// импортирует, читается как часть договора и мешает менять внутренности. Ограничитель обращений
+// уехал целиком в `ask.mjs` — вместе с проверками, которые его сторожили.
+export { briefLine, pickAdvice, updateNotice, updateWanted, beginBrief, finishBrief };

package/tool/lib/core.mjs

@@ -5,6 +5,7 @@
 // размер файла. Зависимостей по-прежнему нет ни одной: только встроенные модули Node.
 
 import { LANG } from "../i18n/index.mjs";
+import { ASK_FILES } from "./ask.mjs";
 import { access, readdir, mkdir, copyFile, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -86,6 +87,7 @@ function commandRows(L) {
     { name: "prompt", args: "", text: h.prompt },
     { name: "badge", args: "", text: h.badge },
     { name: "vitals", args: "", text: h.vitals },
+    { name: "feedback", args: "", text: h.feedback },
     { name: "version", args: "", text: h.version },
   ];
 }
@@ -105,10 +107,9 @@ const RATCHET_DIR = "ratchets";
 // обёртка плюс реестр, и разносить их по разным каталогам значит прятать половину механизма.
 const RATCHET_LIB = `${RATCHET_DIR}/_ratchet.sh`;
 
-// Отметка «просьбу про звезду уже показали» — вне репозитория, в доме пользователя. Внутри
-// .aqk/ она либо закоммитится в чужой проект как наш мусор, либо пропадёт при init --force:
-// то и другое врёт о том, видел человек просьбу или нет.
-const FEEDBACK_MARK = join(homedir(), ".config", "aqk", "feedback-shown");
+// Служебный каталог этого проекта и дом пользователя — два места, где комплект держит
+// состояние. Кто и как часто туда пишет, решает `ask.mjs`; здесь только адреса.
+const stateDirs = () => ({ project: join(CWD, TARGET_DIR), home: homedir() });
 
 // Путь, попадающий в ДОКУМЕНТ, всегда пишется через «/». `relative()` отдаёт разделитель
 // платформы, и на Windows склейка методичек и отчёт получались с «kit\\docs» вместо «kit/docs»:
@@ -148,7 +149,7 @@ async function writeIfAbsent(path, content, { force }) {
 // читателей. Отзыв с живого проекта 2026-09-11: `.aqk/last-run.md` однажды закоммитили, и каждый
 // `make check` оставлял изменённый файл. Целиком `.aqk/` не игнорируется: методички и правила в
 // нём — содержимое проекта.
-const RUNTIME_FILES = ["last-run.md", "last-probe.md", "advice-shown", "update-checked"];
+const RUNTIME_FILES = ["last-run.md", "last-probe.md", ...ASK_FILES];
 const L_IGNORE_NOTE = LANG === "en"
   ? "# aqk: this machine's state — rewritten by every run, it does not belong in git"
   : "# aqk: состояние этой машины — переписывается каждым прогоном, в git ему не место";
@@ -185,5 +186,5 @@ export {
   copyDir, writeIfAbsent,
   PKG_ROOT, CWD, DOCS_SRC, RULES_SRC, TARGET_DIR, docPath,
   MANIFEST, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB,
-  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK, commandRows, preCommitHook, RUNTIME_FILES, ensureIgnored,
+  SELF, REPO_URL, c, exists, die, stateDirs, commandRows, preCommitHook, RUNTIME_FILES, ensureIgnored,
 };

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/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 } from "./execution.mjs";
 import { annotations } from "./annotate.mjs";
 
 
@@ -168,10 +169,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 +317,80 @@ 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);
+
+  const dst = join(CWD, TARGET_DIR, "last-run.md");
+  await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+  await writeFile(dst, lines.join("\n") + "\n", "utf8");
+}
+
+// Разбор отчёта прошлого прогона. Формат кладёт сам `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: {
       // Ширина колонки считается, а не подбирается пробелами: строки в двух языках разной
       // длины, и вручную выровненная справка на втором языке разъезжается.