agent-quality-kit 0.13.0 → 0.15.0

package/tool/i18n/ru.mjs

@@ -10,12 +10,20 @@ import { templates } from "./templates-ru.mjs";
 
 import { ruGates } from "./ru-gates.mjs";
 
+// «(коммитов с тех пор: 3)» — без склонений: число рядом со словом в родительном падеже
+// читается одинаково при любом числе.
+const ago = (n) => (n === null || n === undefined ? "" : ` (коммитов с тех пор: ${n})`);
+
 export const ru = {
   learn: {
     title: "Сказано вслух и не записано",
     noLogs: (p) => `логов этого проекта нет: ${p}\n  Команда читает переписку Claude Code на этой машине. Пусто — значит здесь не работали.`,
-    counted: (s, typed, said, fresh) =>
-      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh}`,
+    counted: (s, typed, said, fresh, again) =>
+      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh} · повторено: ${again}`,
+    ruleTitle: "Записано, а поправлять всё равно приходится:",
+    ruleHow: "Правило стоит в своде, а вы повторяете его агенту снова — текстом оно не держится. Ему нужен сторож-машина: aqk find \"…\" или aqk new <имя>.",
+    repeatTitle: "Повторено — вы говорили это не в первый раз («я же говорил», «опять», «снова»):",
+    restTitle: "Остальное, похожее на правило и не записанное:",
     nothing: "всё, что похоже на правило, уже стоит в точке входа",
     andMore: (n) => `… и ещё ${n}`,
     warn:
@@ -45,7 +53,9 @@ export const ru = {
     blob: "собрать методички в один файл GOD_AI.md",
     learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
     context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
+    feedback: "отчёт о работе комплекта и готовая ссылка — единственная плата за него",
     vitals: "подключено ли то, чем комплект работает: инструменты гейтов, хуки, свежесть версии",
+    prompt: "одно задание для агента: что починить, по порядку, и чем доказать, что готово",
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
     report: "обязательная форма отчёта: что стоит, что нет, что не прочитано; --since <ссылка> — ещё и чем доказан диф",
     badge: "значок уровня для README — и проверка, что он не врёт",
@@ -74,6 +84,15 @@ export const ru = {
     coversCantCheck: (entry, gate) => `заявку «${gate} держит ${entry}» проверить не умею: линтер гейта не распознан или правил записи для него нет — принято на слово`,
     selectUnknown: (names, groups) => `--only/--skip: не знаю «${names}» — это не гейт из gates: и не группа из groups:${groups ? ` (группы: ${groups})` : ""}. Прогон всего подряд вместо пропуска был бы неправдой, поэтому стоп.`,
     selectSkipped: (names) => `не запускались (по --only/--skip): ${names} — их состояние неизвестно, это не «зелёные»`,
+    // Claude Code читает CLAUDE.md, а не AGENTS.md — документация Claude Code, раздел «AGENTS.md».
+    claudeShim: {
+      missing: "Claude Code здесь настроен (.claude/), а свод лежит в AGENTS.md — он его не читает. Почини: CLAUDE.md с одной строкой «@AGENTS.md».",
+      noImport: "CLAUDE.md не подключает AGENTS.md — Claude Code видит только CLAUDE.md. Почини: строка «@AGENTS.md» в CLAUDE.md (упоминание словами не загружает файл).",
+    },
+    annotDropped: (n, more) => `пометок в pull request: ${n}, ещё ${more} не показано — GitHub принимает около десяти за шаг; все находки — в логе выше`,
+    heldQuiet: (n, cmd) => `держит машина: ${n} — поимённо: ${cmd}`,
+    skipQuiet: (n, cmd) => `не применимо к этому репозиторию: ${n} — поимённо и почему: ${cmd}`,
+    passedQuiet: (n) => `прошли ещё ${n} — поимённо: --verbose`,
     jobsBad: (v) => `--jobs ждёт целое число от 1: «${v}» не подходит. Прогон по одному под видом параллельного был бы неправдой, поэтому стоп.`,
     rulesByHuman: (total, machine, human) =>
       `правил в точке входа: ${total}. Сторож — ЧЕЛОВЕК у ${human}, машина у ${machine}.`,
@@ -96,6 +115,19 @@ export const ru = {
     toReach: (n) => `Чтобы достичь AQK-${n}:`,
     gives: (what) => `Что это даст: ${what}`,
     allDone: "Все ступени пройдены.",
+    // Чего уровень не доказывает. Ступени меряют оснащённость: гейты показаны на образцах
+    // каталога. Про файлы проекта знает только проба — строка говорит ровно то, что знает она.
+    limitsTitle: "Уровень — это оснащённость, а не надёжность. Чего он не доказывает:",
+    limitsProbe: {
+      never: (_, cmd) => `брак в ваших файлах: проба не запускалась — ${cmd}`,
+      off: () => "брак в ваших файлах: проба выключена (probe: 0) — ловят ли его проверки, неизвестно",
+      blind: ({ names, behind }) => `брак в ваших файлах: проба${ago(behind)} НЕ поймала — ${names.join(", ")}`,
+      partial: ({ caught, unknown, behind }, cmd) => `брак в ваших файлах: проба${ago(behind)} — поймано классов ${caught}, у ${unknown} поимка не доказана (${cmd})`,
+      caught: ({ caught, behind }) => `брак в ваших файлах: проба${ago(behind)} поймала все ${caught} подсаженных классов — только тех, что есть в каталоге`,
+      nothing: ({ behind }, cmd) => `брак в ваших файлах: проба${ago(behind)} ничего не подсадила — ${cmd}`,
+      old: ({ behind }, cmd) => `брак в ваших файлах: проба была${ago(behind)}, итог покажет ${cmd}`,
+    },
+    limitsCi: "конвейер: прошёл ли он, отсюда не видно — проверяется только, что гейты в нём объявлены",
 
     gatesHeading: "Гейты",
     langs: "языки",
@@ -143,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}`,
@@ -222,7 +260,7 @@ export const ru = {
       has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
       has_mcp: ["агенту здесь не подключали внешних инструментов через MCP", "MCP-серверы объявлены"],
-      has_api_spec: ["не видно спецификации API", "спецификация API есть"],
+      has_api_spec: ["не видно договора API: ни файла OpenAPI, ни tRPC, ts-rest или провайдера типов Fastify", "договор API есть: файл спецификации или схемы в коде"],
     },
   },
 
@@ -249,5 +287,45 @@ export const ru = {
     alreadyDeclared: "уже объявлен",
   },
 
+  // Задание агенту одним текстом (`aqk prompt`). У КАЖДОГО пункта хвост «Готово — …» с
+  // командой-арбитром: пункт без неё агент закроет словами «сделал» — это сторожит модульная проверка.
+  prompt: {
+    title: "# Задание: довести проверки проекта до рабочих",
+    intro: "Составлено AQK по состоянию репозитория. Выполняй пункты по порядку.",
+    rulesTitle: "## Правила",
+    rules: [
+      "Команды бери только из этого задания и из репозитория. Не выдумывай.",
+      "Сначала запусти проверку пункта и убедись, что она красная. Потом чини. Готово — когда та же команда зелёная.",
+      "Чини код, а не проверку: не ослабляй порог, не добавляй исключений, не выключай гейт. Считаешь проверку неправой — остановись и спроси владельца.",
+      "Решение, которое может принять только владелец (что ставить в проект, какие правила вводить), — спроси, а не угадывай.",
+      "Меняй только то, что нужно для этих пунктов.",
+    ],
+    tasksTitle: "## Что сделать",
+    empty: "Делать нечего: красных гейтов нет, проба ничего не нашла, ставить нечего. Всё равно выполни проверку ниже.",
+    done: "Готово —",
+    item: {
+      init: (s) => `Заведи манифест: \`${s} init\` — без него остальные команды отказывают. Готово — \`${s} doctor\` показывает уровень.`,
+      runNone: (s) => `Прогона ещё не было. Запусти \`${s} doctor --run\` и почини то, что покраснеет, по одному гейту: \`${s} doctor --run --only <имя>\`. Готово — прогон зелёный.`,
+      runStale: (s, when) => `Прогон ${when} старше последнего коммита — список красных ниже может быть про другой код. Запусти \`${s} doctor --run\` заново. Готово — у тебя свежий итог, и пункты ниже сверены с ним.`,
+      missed: ({ slug, file }, s) => `Гейт \`${slug}\` стоит, но пропустил брак, который проба подсадила в \`${file}\`. Разберись почему — частая причина: гейт не смотрит этот тип файлов или каталог; подробности даст \`${s} probe\`. Готово — \`${s} probe\` больше не называет этот класс.`,
+      red: (name, s) => `Гейт \`${name}\` красный. Запусти \`${s} doctor --run --only ${name}\`, прочитай находки и почини код. Готово — эта команда зелёная.`,
+      blind: ({ slug, file, command }, s) => `Проба подсадила брак класса \`${slug}\` в \`${file}\`, и проверки проекта его не заметили. Поставь проверку: \`${s} add ${slug}\`${command ? ` (то же одной строкой, без комплекта: \`${command}\`)` : ""}. Готово — \`${s} doctor --run --only ${slug}\` проходит, а \`${s} probe\` больше не называет этот класс.`,
+      adopt: (gates, s) => `У проекта уже есть свои проверки: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Впиши их в gates: манифеста .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Готово — \`${s} doctor --run\` их запускает.`,
+      shim: {
+        missing: (s) => `Claude Code здесь настроен, а правила лежат в AGENTS.md — он читает только CLAUDE.md. Создай CLAUDE.md с одной строкой \`@AGENTS.md\`. Готово — \`${s} doctor\` об этом больше не предупреждает.`,
+        noImport: (s) => `CLAUDE.md не подключает AGENTS.md — Claude Code видит только CLAUDE.md. Добавь в CLAUDE.md строку \`@AGENTS.md\` (упоминание словами файл не загружает). Готово — \`${s} doctor\` об этом больше не предупреждает.`,
+      },
+      // Запись каталога — предложение, а не факт о проекте: ставить или нет, решает владелец.
+      // Красный гейт и брак из пробы — факты, там «почини»; здесь — «предложи».
+      start: ({ slug, intent, command }, s) => `Предложи владельцу проверку \`${slug}\`${intent ? ` — ${intent}` : ""}. Согласен — \`${s} add ${slug}\`${command ? ` (то же одной строкой, без комплекта: \`${command}\`)` : ""}. Краснеет на существующем коде — не глуши её, покажи находки владельцу. Готово — \`${s} doctor --run --only ${slug}\` проходит, а \`${s} prove\` показывает её доказанной.`,
+    },
+    more: (n, s) => `И ещё ${n} — полный список: \`${s} doctor\`. Сначала закончи эти.`,
+    verifyTitle: "## Как проверить, что готово",
+    verify: (s) => [
+      `\`${s} doctor --run\` — прогон зелёный.`,
+      `\`${s} prove\` — ни один гейт не сломан: каждый краснеет на своём красном образце.`,
+      "В отчёте назови эти команды и их итог. «Выглядит рабочим» — не готово.",
+    ],
+  },
   ...ruGates,
 };

package/tool/lib/annotate.mjs

@@ -0,0 +1,66 @@
+// tool/lib/annotate.mjs — находки упавших гейтов пометками GitHub Actions.
+//
+// ЗАЧЕМ. Находка видна только в логе конвейера, куда почти никто не заглядывает. Строка
+// `::error file=…,line=…,title=…::…` в выводе шага становится красной пометкой у строки файла
+// прямо в pull request. Идея — из разбора AgentLint (research/competitors/agentlint-0xmariowu.md);
+// формат — документация GitHub «Workflow commands»; экранирование — официальный @actions/core
+// (packages/core/src/command.ts, escapeData и escapeProperty), а не их код.
+//
+// ЧТО НЕ ДЕЛАЕТСЯ НИКОГДА: пометка не меняет вердикт. Это печать того же, что уже решил прогон.
+import { splitAdvice, normPath } from "./scope.mjs";
+
+const ANSI = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*[a-zA-Z]", "g");
+
+// Потолок. В документации GitHub лимита не нашли; в обсуждении сообщества 2020 года
+// (github.com/orgs/community/discussions/26680): «10 warning annotations and 10 error annotations
+// per step». Прогон `doctor` — один шаг, поэтому потолок на весь прогон, а остаток — числом в лог.
+const LIMIT = 10;
+
+// Путь с расширением или с косой чертой — как в scope.mjs. Две формы строки находки: «файл:строка:
+// текст» (grep -n, линтеры, иногда ещё «:колонка») и «файл: текст» (наши записи каталога).
+const PATH = "(?:\\.\\/)?((?:[\\w.@+-]+\\/)*[\\w.@+-]+\\.[A-Za-z][A-Za-z0-9]{0,9})";
+const WITH_LINE = new RegExp(`^${PATH}:(\\d+)(?::\\d+)?:\\s*([\\s\\S]*)$`);
+const NO_LINE = new RegExp(`^${PATH}:\\s+([\\s\\S]+)$`);
+
+function locate(raw) {
+  const plain = String(raw).replace(ANSI, "").trim();
+  if (/^(почини|fix)\s*:/i.test(plain)) return null;
+  let m = WITH_LINE.exec(plain);
+  if (m) return { file: normPath(m[1]), line: Number(m[2]), message: m[3] || plain };
+  m = NO_LINE.exec(plain);
+  if (m) return { file: normPath(m[1]), line: null, message: m[2] };
+  return null;
+}
+
+const escData = (s) => String(s).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const escProp = (s) => escData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+
+// results — те же записи, что возвращает runGates: { name, ok, advisory, out, shown }. Берётся
+// `shown` — показанное прогоном после сужения по дифу; сырой `out` — только если его нет. exists(путь) —
+// есть ли файл в репозитории: пометка на несуществующий файл GitHub вешает на `.github`, и
+// человек ищет то, чего нет. Такая находка идёт общей пометкой гейта без файла.
+function annotations(results, { exists = () => true, limit = LIMIT } = {}) {
+  const lines = [];
+  const used = { error: 0, warning: 0 };
+  let dropped = 0;
+  const emit = (level, title, message, loc = null) => {
+    if (used[level] >= limit) { dropped++; return; }
+    used[level]++;
+    const props = loc ? [`file=${escProp(loc.file)}`, ...(loc.line ? [`line=${loc.line}`] : [])] : [];
+    props.push(`title=${escProp(title)}`);
+    lines.push(`::${level} ${props.join(",")}::${escData(message)}`);
+  };
+  for (const r of results || []) {
+    if (r.ok) continue;
+    const level = r.advisory ? "warning" : "error";
+    const title = `aqk: ${r.name}`;
+    const { findings, advice } = splitAdvice(String(r.shown ?? r.out ?? "").split("\n").filter((l) => l.trim()));
+    const fix = advice.length ? ` — ${String(advice[0]).replace(ANSI, "").trim()}` : "";
+    const located = findings.map(locate).filter((f) => f && exists(f.file));
+    for (const f of located) emit(level, title, `${f.message}${fix}`, f);
+    if (!located.length) emit(level, title, `${String(findings[0] || r.note || "").replace(ANSI, "").trim()}${fix}`);
+  }
+  return { lines, dropped };
+}
+
+export { locate, annotations };

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/cadence.mjs

@@ -99,4 +99,33 @@ function autoProbeAllowed({ brief = false, env = process.env } = {}) {
   return !(env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI || env.BUILDKITE || env.JENKINS_URL);
 }
 
-export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed };
+// Сколько классов проба поймала и у скольких поимка не доказана. Старая отметка чисел не несёт —
+// null: «не знаем», а не «ноль пойманных».
+function parseCounts(text) {
+  const caught = /^caught:[ \t]*(\d+)/m.exec(String(text || ""));
+  const unknown = /^unknown:[ \t]*(\d+)/m.exec(String(text || ""));
+  return caught && unknown ? { caught: Number(caught[1]), unknown: Number(unknown[1]) } : null;
+}
+
+// Чего уровень НЕ доказывает — строкой под ним. Отзыв с живого проекта 2026-09-11: «AQK-3, All
+// levels reached» при конвейере, который ни разу не запускался. Ступени меряют оснащённость:
+// гейты показаны на образцах КАТАЛОГА. Ловят ли они брак в файлах ПРОЕКТА, знает только проба —
+// и строка говорит ровно то, что знает она. Непойманное идёт первым, даже если пойманного
+// больше: «четыре из пяти» глаз читает как «всё хорошо».
+//
+// Планку ступеней не подняли намеренно: отметка пробы лежит в .gitignore, в конвейере её нет, и
+// «AQK-2 только после пробы» уронило бы уровень и `badge --check` у всех разом.
+function levelLimits(st) {
+  if (st?.state === "off") return { kind: "off" };
+  const behind = Number.isFinite(st?.behind) ? st.behind : null;
+  if (st?.classes?.length) return { kind: "blind", names: st.classes.map((x) => x.slug), behind };
+  if (st?.counts) {
+    const { caught, unknown } = st.counts;
+    if (unknown > 0) return { kind: "partial", caught, unknown, behind };
+    return caught > 0 ? { kind: "caught", caught, behind } : { kind: "nothing", behind };
+  }
+  if (st?.ran) return { kind: "old", behind };
+  return { kind: "never" };
+}
+
+export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed, parseCounts, levelLimits };

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";
@@ -83,8 +84,10 @@ function commandRows(L) {
     { name: "learn", args: "", text: h.learn },
     { name: "context", args: "", text: h.context },
     { name: "context", args: "--full --install", text: h.contextInstall },
+    { 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 },
   ];
 }
@@ -104,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»:
@@ -147,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 ему не место";
@@ -184,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,
   });
 });