agent-quality-kit 0.14.0 → 0.16.0

package/tool/i18n/ru-docs.mjs

@@ -26,6 +26,10 @@ const ruDocs = {
     unknownHook: "посмотреть не смогли — неизвестно, а не «нет»",
     preCommitOk: "прописан в .git/hooks",
     preCommitNo: "в .git/hooks его нет: запись в конфиге — намерение, а не защита",
+    // ХУК ЕСТЬ, НО НЕ НАШ. Ставить нечего — надо дописать: совет другой, значит и строка
+    // другая. До 2026-09-16 этот случай печатался как «прописан», и репозиторий, где AQK не
+    // вызывался ни разу, выглядел подключённым.
+    preCommitOther: "хук в .git/hooks есть, но AQK в нём не вызывается — проверьте .pre-commit-config.yaml либо само тело хука",
     sessionOk: "хук SessionStart отдаёт состояние агенту",
     sessionNo: (cmd) => `агент не получает состояние: ${cmd}`,
     versionOk: (v) => `${v}, свежая`,
@@ -65,6 +69,7 @@ const ruDocs = {
       "Прогон не делался — какие проверки красные, НЕИЗВЕСТНО. Это не «чисто»: `aqk doctor --run`.",
     runStale: (when) =>
       `Последний прогон ${when} СТАРЕЕ последнего коммита — он описывает не тот код, что здесь.`,
+    runCannot: (names) => `НЕ СМОГЛИ ПРОВЕРИТЬ (сбой самих проверок, а не находки о коде): ${names}`,
     runClean: (when) => `Последний прогон ${when} — красных нет.`,
     runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
     andMore: (n) => `и ещё ${n}`,
@@ -86,7 +91,14 @@ const ruDocs = {
     // complexity-limit её поймал.
     nextStep: {
       init: () => "Заведи стандарт: `aqk init` — без .aqk.yml `aqk add` откажет.",
-      adopt: (s) => `Объяви проверки, которые у проекта уже есть: в .aqk.yml, в gates: ${s.gates.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Затем \`aqk doctor --run\`.`,
+      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(`Объяви проверки, которые у проекта уже есть: в .aqk.yml, в gates: ${ok.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Затем \`aqk doctor --run\`.`);
+        if (weak.length) out.push(`А эти в нынешнем виде покраснеть не могут — ${weak.map((g) => `${g.cmd} (${g.weak.text})`).join(", ")} — и объявлять их пока нельзя: скажи владельцу и почини команду.`);
+        return out.join(" ");
+      },
       blind: (s) => `Брак «${s.slug}», подсаженный пробой в ${s.file}, ваши проверки НЕ поймали.` +
         (s.command ? ` Поймать сейчас: \`${s.command}\`.` : "") + ` Держать всегда: \`aqk add ${s.slug}\`.`,
       start: (s) => `Поставь ${s.slug}: \`aqk add ${s.slug}\`` + (s.command ? ` (одной строкой, без комплекта: \`${s.command}\`)` : "") +
@@ -96,7 +108,9 @@ const ruDocs = {
     whenTitle: "Когда что делать:",
     whenCommit: (hook) => hook === true
       ? "Перед коммитом → хук `.git/hooks/pre-commit` прогонит проверки сам; не обходи его (`--no-verify`)."
-      : "Перед коммитом → `aqk doctor --run --since main`: хука перед коммитом нет, само это не случится.",
+      : hook === "other"
+        ? "Перед коммитом → `aqk doctor --run --since main`: хук в `.git/hooks` стоит, но AQK из него не вызывается — сам собой прогон не случится."
+        : "Перед коммитом → `aqk doctor --run --since main`: хука перед коммитом нет, само это не случится.",
     whenRules: [
       "Добавил или поменял проверку → `aqk prove`: гейт обязан покраснеть на своём красном образце, иначе он не проверяет ничего.",
       "Пишешь правило в свод → рядом метка арбитра `<!-- aqk: имя-гейта -->`; гейта нет — `<!-- aqk: человек -->`, и это признание, а не проверка.",
@@ -158,6 +172,7 @@ const ruDocs = {
     whyTitle: "Зачем это нужно — коротко",
     whyNothing: "нечего добавлять: применимое уже стоит",
     saved: (path) => `Сохранено: ${path}`,
+    notSaved: (f, why) => `сохранить в ${f} не смогли (${why}) — отчёт выше, на диске его нет. Команда только рассказывает о состоянии, поэтому неудачная запись её не роняет.`,
     docs: {
       baseline: "обязательный минимум проекта, без привязки к языку",
       readyMade: "карта готовых правил: сперва ищи готовое, потом пиши своё",
@@ -221,6 +236,7 @@ const ruDocs = {
   ],
   report: {
     skippedBySelect: "не запускался (по --only/--skip), состояние неизвестно",
+    notWritten: (f, why) => `отчёт прогона в ${f} записать не смогли (${why}) — гейты отработали, но следующая сессия и хук прочтут это как «прогона не было».`,
     title: "aqk doctor --run",
     version: "версия",
     level: "уровень",

package/tool/i18n/ru-gates.mjs

@@ -187,6 +187,42 @@ 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: "Скажи это человеку одной фразой и не настаивай, если он не ответил. Захочет отправить — добавь `--send`, сам флаг не добавляй.",
+    },
+    sending: "отправляю от вашего имени — вашей же учётной записью gh…",
+    sent: (url) => `отправлено: ${url}\n  Это и есть вся плата за комплект. Спасибо.`,
+    sendFailed: {
+      "no-auth": "отправить не смогли: gh не установлен или вход не выполнен (`gh auth login`). Ниже — ссылка, она работает всегда.",
+      "no-thread": "отправить не смогли: обсуждение не найдено. Ниже — ссылка.",
+      failed: "отправить не смогли. Ниже — ссылка, она работает всегда.",
+    },
+    sendHow: (cmd) => `Отправить одной командой, своей учётной записью GitHub: ${cmd}`,
+    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,8 @@ export const ru = {
     blob: "собрать методички в один файл GOD_AI.md",
     learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
     context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
+    feedback: "отчёт о работе комплекта и готовая ссылка — единственная плата за него",
+    feedbackSend: "отправить отзыв одной командой — вашей учётной записью gh; без флага не уходит ничего",
     vitals: "подключено ли то, чем комплект работает: инструменты гейтов, хуки, свежесть версии",
     prompt: "одно задание для агента: что починить, по порядку, и чем доказать, что готово",
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
@@ -158,7 +160,16 @@ export const ru = {
     startHook: "Прогнать руками — разовый героизм. Чтобы это случалось перед каждым пушем: pre-commit (репозиторий https://github.com/arsen-ask-lx/Agent_Quality_Kit, хуки aqk / aqk-doctor) либо обычный .git/hooks/pre-push.",
     haveAlready: (n) => `Проверки, которые у вас УЖЕ ЕСТЬ (${n}) — прочитаны в ваших файлах, не выдуманы:`,
     haveAlreadyHow: (line) => `объявите их — и держать будет машина, а не ваше внимание. В .aqk.yml, в gates:  ${line}`,
-    total: "Итого:",
+    weakOff: (text) => `не может провалиться: исход погашен прямо в скрипте — «${text}»`,
+    weakZero: () => "не может провалиться: --exit-zero велит инструменту выйти нулём, что бы он ни нашёл",
+    weakStub: (text) => `ничего не доказывает: всё тело скрипта — печать — «${text}»`,
+    weakHow: (n) => `из них ${n} покраснеть не могут. Объявить проверку, которая не может ` +
+      "провалиться, — значит сделать молчание машинно-читаемым. Сначала почините команду.",
+    // «Итого» — ПО КАТАЛОГУ AQK, и это сказано словом. Считаются наши записи: гейт проекта,
+    // названный по-своему (`project-verify`), ни одну из них по имени не закрывает, и строка
+    // «держит машина 0» у проекта с тридцатью собственными проверками читалась как приговор
+    // ему, а не как счёт наших записей. Замер 2026-09-16 по двенадцати репозиториям.
+    total: "Итого по каталогу AQK:",
     totalHeld: (n) => `держит машина ${n}`,
     totalTodo: (n) => `применимо но не поставлено ${n}`,
     totalSkip: (n) => `скрыто ${n}`,
@@ -173,7 +184,14 @@ export const ru = {
       `совещательные и красные: ${names.join(", ")}. Это выключенные проверки: ` +
       `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
+    timeoutBadEnv: (raw, secs) => `AQK_GATE_TIMEOUT=«${raw}» — это не число секунд больше нуля; жду как прежде, ${secs}с. Ноль и мусор у spawnSync означают «ждать вечно», а висящий гейт неотличим от работающего.`,
     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}`,
@@ -303,7 +321,14 @@ export const ru = {
       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\` их запускает.`,
+      adopt: (gates, s) => {
+        const weak = gates.filter((g) => g.weak);
+        const ok = gates.filter((g) => !g.weak);
+        const out = [];
+        if (ok.length) out.push(`У проекта уже есть свои проверки: ${ok.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Впиши их в gates: манифеста .aqk.yml — ${ok.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Готово — \`${s} doctor --run\` их запускает.`);
+        if (weak.length) out.push(`А эти в нынешнем виде покраснеть НЕ МОГУТ: ${weak.map((g) => `\`${g.cmd}\` — ${g.weak.text}`).join(", ")}. Не вписывай их, пока не починена команда: объявленная проверка, которая не может провалиться, превращает дыру в зелёную галочку, и с этого дня за неё ручается машина. Это решение владельца, а не твоё, — скажи ему, что нашёл.`);
+        return out.join(" ");
+      },
       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\` об этом больше не предупреждает.`,

package/tool/lib/adopt.mjs

@@ -20,24 +20,77 @@
 // ни другой. Берём только то, что отвечает «прошло или нет».
 const CHECK_NAMES = new Set(["test", "tests", "lint", "typecheck", "type-check", "types", "check"]);
 
+// ПРОВЕРКА, КОТОРАЯ ЕСТЬ И НЕ МОЖЕТ ПРОВАЛИТЬСЯ. До 2026-09-14 мы читали ИМЯ скрипта и печатали
+// каноничную команду `npm test` с зелёной галочкой, ни разу не заглянув в его ТЕЛО. А выключатель
+// стоит именно там: `node --test || true`. На репозитории, где выключено всё, первый экран
+// говорил «у вас уже есть 2 проверки» — ровно та ошибка, ради которой написан весь комплект.
+//
+// ГРАНИЦА ВЗЯТА У ГЕЙТА `ci-actually-fails`, дословно его довод: `|| true` в СЕРЕДИНЕ команды —
+// это идемпотентность вспомогательного шага (`mkdir -p … || true`), а не выключенная проверка.
+// Поэтому красным делается только то, под что попадает ВЕСЬ исход: гашение в конце тела либо
+// флаг, у которого другого назначения нет.
+const OFF_TAIL = /(\|\|\s*(?:true|:|exit\s+0)|;\s*(?:true|exit\s+0))\s*$/;
+const ZERO_FLAG = /(?:^|\s)--exit-zero(?:\s|$)/;
+
+function cannotFail(body) {
+  if (typeof body !== "string") return undefined;
+  // Комментарий — не команда. `\s#` (а не просто `#`): в `echo "#1"` решётка стоит внутри строки.
+  const code = body.replace(/\s#[^"']*$/, "").trim();
+  if (!code) return undefined;
+  const off = OFF_TAIL.exec(code);
+  if (off) return { kind: "off", text: off[1].trim() };
+  if (ZERO_FLAG.test(code)) return { kind: "zero", text: "--exit-zero" };
+  // Заглушка: всё тело — печать и ничего больше. Заготовка npm
+  // (`echo "Error: no test specified" && exit 1`) провалиться МОЖЕТ — её обвинять нельзя,
+  // и её отсекает связка `&&`.
+  if (/^echo\b/.test(code) && !/[&|;]/.test(code)) return { kind: "stub", text: code.slice(0, 60) };
+  return undefined;
+}
+
 // Окружения tox, которые судят, а не гоняют тесты под матрицей версий. Голый `tox` не
 // предлагаем: он проходит все интерпретаторы из envlist, и у человека без пяти питонов это
 // красный прогон на пустом месте. Имена сняты с живых tox-файлов (rich, click, flask).
 const TOX_CHECKS = new Set(["lint", "style", "typing", "types", "type", "mypy", "check", "typecheck"]);
 
+// ОДНА И ТА ЖЕ КОМАНДА, ЗАПИСАННАЯ ПО-РАЗНОМУ. Сравнивать надо КОМАНДЫ, а не имена: гейт в
+// чужом манифесте зовётся как хочет его владелец (`project-verify`), и по именам совпадения не
+// будет никогда. Обёртка снимается: `bash scripts/check` и `scripts/check` — это одно, и
+// советовать второе тому, у кого объявлено первое, значит советовать уже сделанное.
+//
+// Вхождение подстрокой здесь НЕ годится, хотя и соблазняет: `true` содержится в половине
+// команд, и любой гейт-заглушка съел бы весь список. Равенство после нормализации ошибается
+// в одну сторону — покажет лишнее, — и это дешевле молчания.
+const WRAPPER = /^(?:bash|sh)\s+/;
+
+function sameCommand(a, b) {
+  const norm = (s) => String(s || "").trim().replace(/\s+/g, " ");
+  const bare = (s) => norm(s).replace(WRAPPER, "");
+  return (norm(a) && norm(a) === norm(b)) || (bare(a) && bare(a) === bare(b));
+}
+
 // Источники в порядке доверия: при совпадении имени берётся первый. Замер 2026-09-11 на
 // восьми python-проектах: package.json нет ни у кого, Makefile у трёх, `.pre-commit-config.yaml`
 // у семи, tox у пяти, scripts/ у httpx. Шаги конвейера НЕ читаются: там `${{ matrix.x }}`,
 // `PYTHONPATH=…` и обёртки `uv run --locked --group …` — строка, которая работает только в
 // том конвейере, предложенная как локальный гейт, покраснела бы у человека в первую же минуту.
-function proposeGates(files = {}) {
+//
+// `declared` — команды, УЖЕ объявленные в манифесте. Приходят списком строк, а не манифестом:
+// иначе чтение чужих конфигов начало бы зависеть от нашего формата, и файл, заведённый ради
+// разбора ЧУЖИХ источников, получил бы вторую причину меняться.
+function proposeGates(files = {}, declared = []) {
   const out = [];
   const seen = new Set();
-  const push = (name, cmd, source) => {
+  const already = (cmd) => (declared || []).some((d) => sameCommand(d, cmd));
+  // ТЕЛО передаётся отдельно от команды: человеку показывается каноничная `npm test`, а судим
+  // мы по тому, что за ней стоит. Где тела у нас нет (Makefile, tox, scripts/) — там и суждения
+  // нет: молчание тут честнее догадки.
+  const push = (name, cmd, source, body) => {
     const key = name === "tests" ? "test" : name.replace(/^type-?check$|^types$/, "typecheck");
     if (seen.has(key)) return;
     seen.add(key);
-    out.push({ name: key, cmd, source });
+    if (already(cmd)) return;
+    const weak = cannotFail(body);
+    out.push(weak ? { name: key, cmd, source, weak } : { name: key, cmd, source });
   };
 
   const pkg = files["package.json"];
@@ -48,7 +101,8 @@ function proposeGates(files = {}) {
       for (const name of Object.keys(scripts)) {
         if (!CHECK_NAMES.has(name)) continue;
         // `npm test` — каноничное написание для теста, остальное через `run`.
-        push(name, name === "test" || name === "tests" ? "npm test" : `npm run ${name}`, "package.json");
+        push(name, name === "test" || name === "tests" ? "npm test" : `npm run ${name}`,
+          "package.json", scripts[name]);
       }
     }
   }

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";
@@ -39,8 +40,16 @@ const exists = async (p) => access(p, constants.F_OK).then(() => true, () => fal
 // Как звать программу — зависит от того, как её запустили. Через npx команды `aqk` в системе
 // нет: подсказка «aqk doctor» отправляет человека в «команда не найдена» на первом же шаге.
 // Печатаем то, что можно скопировать и выполнить прямо сейчас.
-// Имя в реестре, а не адрес репозитория: короче, скачивается 230 КБ вместо клона всего
-// репозитория и не заставляет человека ждать три минуты в тишине на первой же команде.
+// Имя в реестре, а не адрес репозитория: короче, тянет пакет вместо клона всего репозитория и
+// не заставляет человека ждать три минуты в тишине на первой же команде.
+//
+// ЧИСЛА ЗДЕСЬ БОЛЬШЕ НЕТ, И ЭТО РЕШЕНИЕ. Стояло «230 КБ»; замер 2026-09-10 дал 574 КБ, замер
+// 2026-09-14 — 692 КБ. Число, которое никто не сторожит, врёт тем сильнее, чем дольше живёт, —
+// наше же правило про утверждение без арбитра, нарушенное в собственном комментарии. Текущий
+// размер считается одной командой: `npm pack --dry-run`. Из 2,2 МБ распакованного 584 КБ — это
+// `tool/selfcheck`, то есть наши собственные тесты, уезжающие каждому пользователю; вырезать их
+// из `files` можно только после проверки, что собранный пакет работает, — иначе поломка
+// установки обойдётся дороже сэкономленного.
 const REPO = "agent-quality-kit";
 // Адрес репозитория отдельно от имени пакета. Когда имя стало коротким, ссылка «поставь
 // звезду» собиралась из него и вела на github.com/agent-quality-kit — несуществующую
@@ -86,6 +95,8 @@ 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: "feedback", args: "--send", text: h.feedbackSend },
     { name: "version", args: "", text: h.version },
   ];
 }
@@ -105,10 +116,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 +158,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 ему не место";
@@ -170,20 +180,47 @@ async function ensureIgnored(cwd = CWD) {
 }
 
 // Стоит ли хук pre-commit НА САМОМ ДЕЛЕ — в `.git/hooks`, а не в `.pre-commit-config.yaml`:
-// запись в конфиге — намерение, сработает только то, что лежит в гите. Три ответа: true — стоит,
-// false — нет, null — не git или файл не прочитать («не знаем» не сливается с «нет»).
-// Одна функция на `vitals` (подключено ли) и `context` (что сказать агенту перед коммитом).
+// запись в конфиге — намерение, сработает только то, что лежит в гите.
+//
+// ЧЕТЫРЕ ОТВЕТА, А НЕ ТРИ. Раньше тело хука проверялось регуляркой `/pre-commit|aqk/i`, то есть
+// ПО ИМЕНИ: у любого проекта с фреймворком pre-commit слово «pre-commit» в хуке есть всегда, и
+// `vitals` печатал «прописан в .git/hooks» репозиторию, где AQK не вызывался ни разу. Разбор
+// живой интеграции 2026-09-16: человек прочитал это как «обвязка на месте» и ушёл. Наш
+// собственный класс «объявлено ≠ работает», у нас самих.
+//
+//   null    — не git либо файл не прочитать («не знаем» не сливается с «нет»);
+//   false   — хука нет;
+//   "other" — хук есть, но AQK в нём не участвует: ставить не надо, надо дописать;
+//   true    — AQK участвует.
+//
+// КАК ЭТО ДЕЛАЮТ СНАРУЖИ. pre-commit узнаёт свой хук функцией `is_our_script()` — ищет в теле
+// собственный маркер (CURRENT_HASH плюс пять PRIOR_HASHES), а не имя. У них же есть режим
+// миграции: при установке поверх чужого хука запускаются оба, старый уезжает в `.legacy`. То
+// есть «в теле есть слово pre-commit» не доказывает даже, что хук ихний.
+//
+// ДВА ПУТИ ПОДКЛЮЧЕНИЯ, И СЧИТАТЬ НАДО ОБА. Прямой вызов в теле хука — и наш хук из
+// `.pre-commit-hooks.yaml`, поставленный через фреймворк: там в `.git/hooks/pre-commit` лежит
+// диспетчер, а что он запустит, написано в `.pre-commit-config.yaml` проекта. Смотреть только в
+// тело значило бы соврать в обратную сторону — сказать «AQK не подключён» тому, кто подключил.
+const AQK_IN_HOOK = /\baqk\b|agent[-_]quality[-_]kit/i;
+const AQK_IN_CONFIG = /agent[-_]quality[-_]kit|Agent_Quality_Kit|(?:^|\s)-\s*id:\s*["']?aqk\b/im;
+
 async function preCommitHook(cwd = CWD) {
   const { readFile } = await import("node:fs/promises");
   if (!(await exists(join(cwd, ".git")))) return null;
   const hook = join(cwd, ".git", "hooks", "pre-commit");
   if (!(await exists(hook))) return false;
-  try { return /pre-commit|aqk/i.test(await readFile(hook, "utf8")); } catch { return null; }
+  let body = "";
+  try { body = await readFile(hook, "utf8"); } catch { return null; }
+  if (AQK_IN_HOOK.test(body)) return true;
+  let config = "";
+  try { config = await readFile(join(cwd, ".pre-commit-config.yaml"), "utf8"); } catch { /* нет конфига — значит подключения через фреймворк нет */ }
+  return AQK_IN_CONFIG.test(config) ? true : "other";
 }
 
 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,
 };