agent-quality-kit 0.8.0 → 0.10.0

package/tool/i18n/ru.mjs

@@ -8,6 +8,8 @@ import { ruDocs } from "./ru-docs.mjs";
 
 import { templates } from "./templates-ru.mjs";
 
+import { ruGates } from "./ru-gates.mjs";
+
 export const ru = {
   learn: {
     title: "Сказано вслух и не записано",
@@ -29,6 +31,7 @@ export const ru = {
     init: "разложить правила и методички в текущий проект",
     initForce: "перезаписать уже существующие файлы",
     start: "кода ещё нет: сторожа дня 0 и порядок работы",
+    probe: "чего объявленные проверки не видят: подсадка брака в горячие по истории файлы",
     prove: "доказать, что гейты ловят брак: каждый по своему красному и зелёному образцу",
     doctor: "проверить, что разложено и чего не хватает",
     doctorRun: "ещё и запустить объявленные гейты",
@@ -45,6 +48,7 @@ export const ru = {
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
     report: "обязательная форма отчёта: что стоит, что нет, что не прочитано; --since <ссылка> — ещё и чем доказан диф",
     badge: "значок уровня для README — и проверка, что он не врёт",
+    version: "заставка и номер версии — то же по --version и -v",
     noInstall: "Без установки:  npx agent-quality-kit init",
     language: "Язык вывода: AQK_LANG=en (или ru), иначе по системной локали",
   },
@@ -88,6 +92,16 @@ export const ru = {
     hasThings: "есть",
     install: (cmd) => `поставить: ${cmd}`,
     notApplicable: (n) => `Не применимо к этому репозиторию (${n}):`,
+    noBrowserServer:
+      "у проекта есть интерфейс, а у агента нет браузера: посмотреть на своё изменение глазами\n  он не может и судит о работе по тому, что собралось. Это разные утверждения.",
+    noBrowserServerHow: (l) => `подключается MCP-сервером, любым агентом: ${l}`,
+    coveredBy: (n) => `закрыто другим арбитром: ${n} — переносимую запись ставить незачем`,
+    coveredByGate: (g) => `держит «${g}», объявленный в манифесте`,
+    coversUnknown: (l) => `covers называет гейт, которого нет в gates: ${l} — эти записи не закрыты ничем`,
+    coversUnproven: (e, g, codes) =>
+      `заявка не подтверждена: «${e}» объявлена закрытой гейтом «${g}», но ни его команда, ни\n  конфиг линтера не называют правил ${codes} — запись может быть не закрыта ничем`,
+    coversUnprovenHow: (cmd) => `подтверди: добавь эти правила в линтер, либо поставь запись — ${cmd}`,
+    totalCovered: (n) => `закрыто другим арбитром ${n}`,
     total: "Итого:",
     totalHeld: (n) => `держит машина ${n}`,
     totalTodo: (n) => `применимо но не поставлено ${n}`,
@@ -97,6 +111,7 @@ export const ru = {
     sinceBadRef: (ref) => `не могу сравнить с «${ref}»: такой ссылки нет или это не репозиторий git`,
     notScopable: "вывод без путей — дифом не сужается, оставлен красным",
     outsideDiff: (n) => `находки есть, но вне дифа (${n})`,
+    advisoryQuiet: "(совещательный — уронить прогон не может)",
     advisoryMark: "совещательный — показано, прогон не уронен",
     advisorySummary: (names) =>
       `совещательные и красные: ${names.join(", ")}. Это выключенные проверки: ` +
@@ -111,7 +126,15 @@ export const ru = {
     manifestUnknown: (keys) =>
       `В манифесте поля, которых стандарт не знает: ${keys.join(", ")}. Похоже на опечатку — ` +
       `такое поле молча читается как отсутствующее, и вердикт выходит неверным.`,
+    manifestUnparsed: (n, t) => `строка ${n} манифеста не разобрана и НЕ ДЕЙСТВУЕТ: ${t}`,
+    manifestUnparsedWhy:
+      "имена полей и гейтов пишутся латиницей, цифрами, дефисом и подчёркиванием. Объявленное\n  здесь не выполняется вовсе — а выглядит так, будто выполняется.",
     manifestKnown: (keys) => `Поля манифеста: ${keys.join(", ")}`,
+    runVerdictOk: "Всё объявленное зелёное.",
+    runVerdictFail: (why) => `Прогон красный: ${why}.`,
+    whyMissing: "не хватает файлов из шапки",
+    whyLevel: "ступень не взята",
+    whyGates: (n, names) => `красных гейтов ${n}${names ? ` (${names})` : ""}`,
     thresholdPass: (min) => `Порог AQK-${min} пройден.`,
     thresholdFail: (min, now) => `Порог AQK-${min} НЕ пройден: сейчас AQK-${now}.`,
     // Ступень взята, но прогон красный — это другое утверждение, и виновника называем сразу:
@@ -170,6 +193,8 @@ export const ru = {
       has_agent_config: ["агента здесь не настраивали", "настройки агента есть"],
       has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
+      has_mcp: ["агенту здесь не подключали внешних инструментов через MCP", "MCP-серверы объявлены"],
+      has_api_spec: ["не видно спецификации API", "спецификация API есть"],
     },
   },
 
@@ -196,282 +221,5 @@ export const ru = {
     alreadyDeclared: "уже объявлен",
   },
 
-  add: {
-    noSuchGate: (slug, cmd) => `Нет такого гейта: ${slug}\nСписок применимых — ${cmd}`,
-    toolMissing: (slug, missing) =>
-      `Записи ${slug} нужен ${missing.join(" и ")}, а его нет на этой машине.\n  почини: поставь ${missing.join(" и ")} и повтори — запись делегирует готовому инструменту по устройству, своей проверки у неё нет.`,
-    noRecipe: (slug, stack, missing) =>
-      `У записи ${slug} нет команды ни под ${stack}, ни общей.` +
-      (Array.isArray(missing) && missing.length
-        ? `\n  почини: поставь ${missing.join(" или ")} и повтори — запись делегирует готовому инструменту по устройству, своей проверки у неё нет.`
-        : `\n  почини: добавь рецепт под свой стек в gate.yml этой записи либо возьми другую.`),
-    thisStack: "этот стек",
-    needName: (cmd, doctor) => `Укажи имя гейта: ${cmd}. Список — ${doctor}`,
-    noManifest: (cmd) => `Нет .aqk.yml — сначала ${cmd}`,
-    notApplicable: (why) => `Этот гейт к репозиторию не применим: ${why}`,
-    installAnyway: "Ставлю всё равно — решение твоё, но сторожить ему нечего.",
-    copied: (n) => `${n} файлов: проверка и образцы`,
-    declared: (cmd) => `гейт объявлен: ${cmd}`,
-    notDeclared: (why, slug, cmd) => `не тронут (${why}). Впиши сам: ${slug}: "${cmd}"`,
-    nextTitle: "Дальше:",
-    next1: "Проверь, что он краснеет и молчит там, где должен:",
-    expectFail: "→ ожидается отказ",
-    expectSilence: "→ ожидается тишина",
-    next2: "Впиши команду в хук коммита и в конвейер.",
-    next2Why: "Гейт, который никто не запускает, — не гейт.",
-    next3: (cmd) => `Прогон всех объявленных: ${cmd}`,
-  },
-
-  gnew: {
-    needName: (cmd) => `Укажи имя: ${cmd}`,
-    badName: (slug) => `Имя «${slug}» не годится: латиница через дефис, например secrets-not-in-code.\nИмя читают в чужих проектах — оно часть словаря.`,
-    looksExisting: (slug) => `Похоже, такое уже есть: ${slug}`,
-    recipeNotGate: "Рецепт под другой стек — это строка в recipes существующей записи.",
-    forceHint: (cmd) => `Всё равно завести новую: ${cmd}`,
-    exists: (path) => `${path} уже существует.`,
-    nextTitle: "Дальше — по порядку:",
-    n1: "Проверь, нет ли готового правила",
-    n1Where: "в ruff, eslint, semgrep.",
-    n1Why: "Готовое точнее, подробнее и его поддерживают без тебя. Своя проверка — запасная.",
-    n2: "Положи образцы.",
-    n2Red: "— код, на котором проверка обязана сработать.",
-    n2Green: "— тот же код, но правильный.",
-    n2Why: "Зелёный важнее: он ловит проверку, которая краснеет на исправном коде.",
-    n3: "Напиши проверку",
-    n3Where: "в check.sh. В тексте отказа — что именно сделать.",
-    n4: "Заполни gate.yml:",
-    n4What: "намерение, триггер, доказательство отказом.",
-    n5: "Прогони:",
-    n5Why: "Арбитр обязан покраснеть на red/ и промолчать на green/. Не прошло — не запись.",
-  },
-
-  ratchet: {
-    needName: (cmd) => `Укажи гейт: ${cmd}. Он должен быть уже объявлен в .aqk.yml`,
-    noManifest: (cmd) => `Нет .aqk.yml — сначала ${cmd}`,
-    notDeclared: (slug, cmd) => `Гейт «${slug}» не объявлен в .aqk.yml. Сначала: ${cmd}`,
-    already: (slug) => `На гейте «${slug}» храповик уже стоит.`,
-    notRunnable: (slug, cmd) =>
-      `Гейт «${slug}» не запускается: ${cmd}\n` +
-      `Снимать долг с несуществующего сторожа нельзя — в реестр попадут его же сообщения\n` +
-      `об ошибке, и он станет разрешением. Сначала почини команду.`,
-    registryHead: (slug, stamp) =>
-      `# Реестр долга: ${slug}\n` +
-      `# Снят ${stamp}. Список разрешается ТОЛЬКО укорачивать.\n` +
-      `# Новое нарушение красит гейт; исправленное вычёркивается автоматически.\n` +
-      `#\n` +
-      `# Долг без цели и срока не кончается. Цель — сколько нарушений считать погашенным долгом;\n` +
-      `# по достижении храповик скажет убрать обёртку. Срок необязателен, но если он есть,\n` +
-      `# после этой даты непогашенный долг красит гейт — срок без последствия не срок.\n` +
-      `# aqk-goal: 0\n` +
-      `# aqk-deadline:\n`,
-    recorded: (n) => `${n} нарушений записано долгом`,
-    libCopied: "обёртка скопирована в проект",
-    wrapped: "команда завёрнута в храповик",
-    changesTitle: "Что это меняет:",
-    fromToday: "со дня установки",
-    changes1: (fromToday) => `Правило действует ${fromToday}. Старый код трогать не надо, но новое`,
-    changes2: "нарушение того же класса гейт не пропустит.",
-    test1: "Проверка, что это храповик, а не советчик: «может ли новый код добавить нарушение",
-    test2: "и пройти?» Может — значит гейта нет.",
-    run: (cmd) => `Прогнать: ${cmd}`,
-  },
-
-  find: {
-    needQuery: (cmd) => `Опиши намерение словами: ${cmd}`,
-    example: 'find "отладочная печать не доезжает до прода"',
-    exists: "Такое уже есть — новую запись заводить не надо:",
-    match: (pct) => `совпадение ${pct}%`,
-    recipes: (langs) => `рецепты: ${langs}общий`,
-    existsWhy1: "Если у тебя рецепт под другой стек — это строка в recipes существующей",
-    existsWhy2: "записи, а не новый гейт. Намерение одно, исполнителей может быть много.",
-    near: "Точного совпадения нет, но рядом лежит:",
-    nearWhy: "Прочитай их README. Если намерение то же — дополняй, а не заводи новое.",
-    none: "Такого намерения в каталоге нет.",
-    journal: "В журнале есть шишка на эту тему:",
-    journalWhy: "Шишка записана — значит доказательство для новой записи уже есть.",
-    howTitle: "Как добавить свой гейт:",
-    how1: "Назови отказ.",
-    how1What: "Какой конкретный брак он поймал в живом проекте, чего это стоило.",
-    how1Why: "«Это хорошая практика» не принимается: так каталог набирает сотни пунктов и умирает.",
-    how2: "Заведи папку",
-    how2What: "— gate.yml, red/, green/, README.md.",
-    how2Why: "Норма записи со всеми полями — kit/gates/README.md",
-    how3: "Проверь машиной:",
-    how3Why: "Арбитр обязан покраснеть на red/ и промолчать на green/. Не прошло — не запись.",
-    how4: "Пришли изменением",
-    how4What: "в репозиторий комплекта.",
-  },
-
-  why: {
-    needQuery: (cmd) => `Опиши, что пропустили: ${cmd}`,
-    example: 'why "файл вырос до девяти тысяч строк"',
-    ciAtOnce: "разом: doctor --run",
-    ciOwnStep: "отдельным шагом",
-    unsure: "Уверенного совпадения нет. Похоже на эти записи:",
-    unsureByName: (cmd) => `Назови запись именем: ${cmd}`,
-    unsureNone: (cmd) => `Ни одна не подходит — значит сторожа не было: ${cmd}`,
-    decideTitle: "Дальше решаешь ты:",
-    decideQ: "это твоя частность или общий случай?",
-    decideWhy: "Общий — идёт в каталог и достаётся всем. Частный — остаётся у тебя.",
-    decideNote: (cmd) => `Урок в общий журнал в любом случае: ${cmd}`,
-    fix: "Почини так:",
-    noGuard: "Сторожа не было.",
-    noGuardWhy: "В каталоге нет записи с таким намерением.",
-    noGuardFix: (cmd) => `заведи запись — ${cmd}`,
-    noGuardHint: "Красный образец бери прямо из этой поломки: она уже случилась, выдумывать нечего.",
-    closest: (slug, pct) => `Ближайшая запись каталога: ${slug}  совпадение ${pct}%`,
-    notInstalled: "Сторож есть в каталоге, но в этом проекте не поставлен.",
-    notInstalledHint1: "Он покраснеет на старом коде — это нормально: старое закрывается храповиком,",
-    notInstalledHint2: (cmd) => `новое ловится со дня установки. ${cmd}`,
-    declaredAs: (cmd) => `Объявлен: ${cmd}`,
-    notRunning: "Сторож объявлен, но не запускается.",
-    notRunningWhy: "Худший случай: тишина читается как успех.",
-    notRunningFix: "путь или программа из команды не существуют — проверь их.",
-    notRunningHint: "Отсутствие сигнала неотличимо от успеха, поэтому это не «мелочь в конфиге».",
-    bypassed: "Сторож есть и эту поломку ловит — значит его обошли.",
-    noCiFix: "конвейера нет. Проверка, которую гоняет только человек,",
-    noCiHint: "работает ровно до первого «забыл».",
-    notInCiFix: "конвейер есть, но этот гейт в нём не запускается.",
-    notInCiHint: (cmd) => `Дешевле всего одним шагом: ${cmd} — он гоняет всё объявленное.`,
-    inCiFix: (how) => `конвейер его гоняет (${how}) — значит красный прогон`,
-    inCiHint1: "кто-то пропустил или обошёл. Перенеси правило из текста в механику:",
-    inCiHint2: "блокирующий шаг, а не необязательный; запрет слияния при красном.",
-    blind: "Сторож есть, стоит и запускается — но этой поломки не видит.",
-    blindFix: (dir) => `положи в ${dir} кусок кода из этой поломки`,
-    blindHint1: "и доведи проверку до красного на нём. Порядок обратный привычному: сначала",
-    blindHint2: "образец, потом правка — иначе непонятно, что именно починено.",
-    blindCheck: "Проверить после правки: bash tool/selfcheck/gates.sh",
-  },
-
-  init: {
-    noDocs: (dir) => `Не найден корпус методичек: ${dir}\nПохоже, пакет установлен не полностью.`,
-    docsRu:
-      "методички в .aqk/docs/ остаются на русском — решение, а не недоделка.",
-    created: (n) => `создано (${n}):`,
-    andMore: (n) => `… и ещё ${n}`,
-    kept: (n) => `уже были на месте, не тронуты (${n}):`,
-    overwrite: (cmd) => `перезаписать: ${cmd}`,
-    nextTitle: "Что дальше — по порядку:",
-    n1a: "Открой",
-    n1b: "и заполни раздел «Команды». Команда, которую нельзя",
-    n1c: "скопировать и выполнить, — не команда, а пожелание.",
-    n2a: "Прочитай",
-    n2b: "— это обязательный минимум",
-    n2c: "проекта без привязки к языку. Пройди сверху вниз и отметь, чего нет.",
-    n3a: "Заполни",
-    n3b: "— гейты, образцы, журнал. Уровень соответствия AQK",
-    n3c: (cmd) => `считается по нему: ${cmd}.`,
-    n4a: "Поднимайся по ступеням",
-    n4b: "по одной",
-    n4c: ". Гейт стережёт существующий артефакт:",
-    n4d: "проверка на код, которого ещё нет, — мёртвое правило.",
-    burned: (cmd) => `Обжёгся на чём-то — запиши: ${cmd}`,
-    hookHint: (cmd) => `Claude Code: ${cmd} — состояние проекта будет попадать в контекст агента\n  само, до первого действия. Для других агентов хука нет, и это не недоделка.`,
-  },
-
-  feedback: {
-    title: "Если пригодилось:",
-    star: (url) => `Поставь звезду — ${url}`,
-    issue: "Нашёл баг или не подошло — заведи Issue, самая полезная обратная связь: и то и другое.",
-    once: "Это разовое сообщение: больше не покажется на этой машине.",
-  },
-
-  note: {
-    journalTitle: "Журнал шишек",
-    needTitle: (cmd) => `Нужен заголовок: ${cmd}`,
-    noJournal: (url) => `Клон журнала не найден.\nСделай один раз:\n  git clone ${url}.git ~/projects/aqk\nили укажи путь: export AQK_HOME=/путь/к/aqk`,
-    journalMissing: (path) => `Журнал не найден: ${path}`,
-    emptyBody: `Тело записи пустое. Передай его на стандартный ввод, например:\n\n  aqk note "заголовок" <<'EOF'\n  **Что случилось.** ...\n  **Чем это стоило.** ...\n  **Вывод.** 🔧 ...\n  EOF`,
-    noOutcome:
-      "В записи нет отметки решения. Урок без вывода — это история, а не урок.\n" +
-      "Припиши одну из трёх:\n" +
-      "  ✅ **Стало гейтом:** <имя записи каталога>\n" +
-      "  🔧 **Стало правкой оснастки:** <что именно изменено>\n" +
-      "  👤 **Гейтом не станет:** <почему>",
-    unknownProject: "неизвестно",
-    projectField: "Проект",
-    pushed: (title) => `Записано и отправлено: ${title}`,
-    localOnly: (cmd) => `Записано локально, push не прошёл. Отправить: ${cmd}`,
-  },
-
-  blob: {
-    noDocs: (dir) => `Не найдены методички: ${dir}`,
-    header: (stamp) =>
-      `<!-- СОБРАНО КОМАНДОЙ aqk blob ${stamp} из kit/docs. Не править руками:\n` +
-      `     правки затрёт следующая сборка. Источник — отдельные файлы. -->\n\n` +
-      `# AQK — методички одним файлом\n`,
-    source: (path) => `источник: ${path}`,
-    done: (n, kb) => `GOD_AI.md — ${n} файлов, ${kb} КБ`,
-    rebuilt: "Собирается заново каждой командой. Править надо оригиналы в kit/docs.",
-  },
-
-  start: {
-    noRecipeHere: "нужен инструмент, которого нет на этой машине",
-    initFailed: (cmd) => `Не получилось разложить комплект. Начни с ${cmd}`,
-    tooManyFiles: (n) => `В репозитории уже ${n} файлов кода — это другой сценарий.`,
-    useDoctor: (cmd) => `${cmd} осмотрит, что есть, и разделит записи на три списка:`,
-    threeLists: "держит машина · применимо и не поставлено · не применимо и почему.",
-    anyway: (cmd) => `Всё равно поставить сторожей дня 0: ${cmd}`,
-    expectRed: "Готовься к красному: сторож, поставленный на живой код, краснеет на нём весь.",
-    expectRedFix: (cmd) => `Это лечится храповиком — ${cmd}, — а не отключением.`,
-    installed: (n) => `Поставлено сторожей дня 0: ${n}`,
-    noDebt1: "Долга нет: на пустом проекте им нечего пропускать. Тот же сторож, поставленный",
-    noDebt2: "через полгода, покраснел бы на всём старом коде — и его бы выключили.",
-    allDeclared: "Все применимые записи уже объявлены.",
-    notYet: "Не применимо пока:",
-    notYetWhy: "Появится признак — запись покажется сама.",
-    orderTitle: "Порядок, в котором это делают:",
-    o1: "Задача словами.",
-    o1What: "Что и кому, без единого технического слова.",
-    o1Why: "Пока задача не описана словами, любая архитектура защищает неизвестно что.",
-    o2: "Ограничения.",
-    o2What: "Сроки, деньги, нагрузка, чем нельзя пользоваться.",
-    o2Why: "Ограничения выбирают решение куда чаще, чем вкус: без них выбирают вкусом.",
-    o3: "Сайзинг.",
-    o3What: "Сколько данных, запросов, людей — числами, хотя бы порядком.",
-    o3Why: "Число отделяет «нужна очередь» от «хватит таблицы». Без него спорят словами.",
-    o4: "Архитектура.",
-    o4What: "И только теперь — из первых трёх, а не до них.",
-    softNote1: "Этот порядок программа не проверяет: он в .aqk/docs/, и агент может его",
-    softNote2: "проигнорировать. Машина держит другое — сторожей выше. Разница между",
-    softNote3: "мягким и жёстким тут ровно такая: текст просят, команду выполняют.",
-    next: "Дальше:",
-    nextWhy: "— прогнать всё, что объявлено",
-  },
-
-
-  prove: {
-    title: "aqk prove — доказательство гейтов",
-    running: "доказываю гейты по их образцам…",
-    proven: (n) => `доказано: ${n}`,
-    broken: (n) => `не ловят: ${n}`,
-    unprovable: (n) => `нечем доказать: ${n}`,
-    okRed: "краснеет на красном, молчит на зелёном",
-    redPassed: "промолчал на КРАСНОМ образце — гейт не ловит брак",
-    greenFailed: "покраснел на ЗЕЛЁНОМ образце — гейт ругается на исправный код",
-    empty: "команда пустая — объявление без команды защиты не даёт",
-    noSamples: "нет образцов — доказать нечем",
-    noTarget: "не видно, куда подставить каталог образца — команда написана руками",
-    otherRecipe: (lang) => `образцы написаны под рецепт «${lang}», а стоит другой — доказать нечем`,
-    noGates: "гейтов не объявлено — доказывать нечего",
-    noSamplesDir: "в .aqk.yml не заполнено поле samples — образцы искать негде",
-    nothingProven:
-      "ни один гейт не доказан. Уровень выше AQK-1 означал бы доверие к автору, а не факт:\n  проект с гейтом «true» прошёл бы его так же, как проект с настоящей защитой.",
-    fix: (cmd) => `почини: поставь запись каталога вместе с образцами — ${cmd}`,
-    heading: "Доказательство гейтов",
-  },
-  badge: {
-    noManifest: (cmd) => `Нет .aqk.yml — уровня ещё нет. Начни с ${cmd}`,
-    notReached: (cmd) => `AQK-0 не достигнут — значок выдавать не за что. Чего не хватает: ${cmd}`,
-    redGates: (n, names) =>
-      `Красных гейтов: ${n} (${names}). Значок при красном гейте — заявление автора, а не факт машины.`,
-    hint: (n) => `Проверено прогоном. Зелёных гейтов: ${n}. Строку выше — в README.`,
-    keepTrue: (cmd) => `Чтобы значок не превратился во враньё, поставь в конвейер: ${cmd}`,
-    checkMissing: (places) => `Значка AQK нет ни в одном из файлов: ${places}. Вставить нужно этот:`,
-    checkMismatch: (where, level) => `Значок врёт: ${where}, а прогон говорит AQK-${level}. Заменить на:`,
-    checkOk: (level, where) => `Значок совпал с прогоном: AQK-${level} — ${where}`,
-  },
-
-
-
+  ...ruGates,
 };

package/tool/lib/banner.mjs

@@ -0,0 +1,59 @@
+// tool/lib/banner.mjs — заставка. Первая встреча человека с комплектом.
+//
+// ЗАЧЕМ ОНА ЕСТЬ. Жалоба владельца: «скачал и че дальше, не понятно, работает он вообще или
+// нет». Строка присутствия в прогоне отвечает на «работает ли», а заставка — на «что это
+// вообще такое»: она показывается там, где человек встречается с инструментом впервые.
+//
+// ПОКАЗЫВАЕТСЯ ДВАЖДЫ ЗА ВСЮ ЖИЗНЬ: при `init` и по `--version`. На каждой команде — нет:
+// то, что видишь тридцатый раз, перестаёт читаться, а рядом стоят находки, которые читать надо.
+//
+// РИСУНОК — СВОЙ. Готовые работы из чужих подборок красивы, но у них нет ни автора, ни
+// лицензии, а пакет уезжает в npm под MIT. Вставить чужое молча — сделать ровно то, за что мы
+// ругаем других. Этот прислан владельцем; надпись собрана шрифтом ANSI Shadow, к шрифтам
+// вопросов о правах нет.
+// Отступ у кошки ОДИН пробел, у букв — два, и это не опечатка. Пустой Брайль `⠀` занимает
+// место, но ничего не рисует: у рисунка видимая часть начинается со второго знака, и при
+// одинаковом отступе кошка выглядела сдвинутой вправо на целый знак. Центры сведены по
+// ВИДИМОЙ части, а не по началу строки.
+const ART = [
+  " ⠀⠀⠀⠀⢀⣾⢷⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣼⢧⡀",
+  " ⠀⠀⠀⠀⠀⢀⣾⠃⢘⣷⣀⣀⣤⣤⣤⣄⣀⢸⡏⠈⢷⡀",
+  " ⠀⠀⠀⠀⠀⣼⣷⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣬⣷",
+  " ⠀⠀⠀⠀⢰⣿⣿⣿⣿⠁⠸⠗⢹⣿⡟⠰⠷⠈⢻⣿⣿⣿⡇",
+  " ⠀⠀⢐⣒⣺⣿⣿⣿⣿⣀⠀⣀⣼⠛⢷⣄⠀⢀⣼⣿⣿⣿⣿⣉⡁",
+  " ⠀⠀⠀⠤⢺⣿⣿⣿⣿⣿⣿⣿⣿⡇⣿⣿⣿⣿⣿⣿⣿⣿⣿⠢",
+  "",
+  "   █████╗  ██████╗ ██╗  ██╗",
+  "  ██╔══██╗██╔═══██╗██║ ██╔╝",
+  "  ███████║██║   ██║█████╔╝",
+  "  ██╔══██║██║▄▄ ██║██╔═██╗",
+  "  ██║  ██║╚██████╔╝██║  ██╗",
+  "  ╚═╝  ╚═╝ ╚══▀▀═╝ ╚═╝  ╚═╝",
+];
+
+// Объявленная ширина сверяется с настоящей модульной проверкой: правка рисунка, разъехавшаяся
+// с этим числом, роняет её. Иначе число здесь через месяц врёт, как всякая цифра в комментарии.
+const BANNER_WIDTH = 27;
+
+// Терминал без UTF-8 превратит Брайль в вопросительные знаки, и человек решит, что инструмент
+// сломан. Тогда честнее короткая строка: она несёт то же самое, только буквами.
+function canDrawArt(env) {
+  if (String(env.AQK_NO_ART || "") === "1") return false;
+  const loc = `${env.LC_ALL || ""}${env.LC_CTYPE || ""}${env.LANG || ""}`.toLowerCase();
+  // Windows-терминалы локаль обычно не выставляют вовсе, а UTF-8 там с 2019 года есть.
+  // Поэтому пусто — рисуем; явно не-UTF-8 — не рисуем.
+  if (!loc) return true;
+  return loc.includes("utf-8") || loc.includes("utf8");
+}
+
+// ВЕРСИИ В ЗАСТАВКЕ НЕТ — решение владельца. Выпуски идут часто, и номер в картинке устаревает
+// быстрее всего остального; за версией есть `--version`, где она и печатается отдельной строкой.
+function banner(env = process.env) {
+  if (!canDrawArt(env)) return "  aqk — agent quality kit";
+  // Отступ подписи — шесть, а не три: он посчитан от ВИДИМОГО центра букв (со 2-го знака по
+  // 26-й, центр 14), а не подобран на глаз. Подобранный на глаз держался до первой правки
+  // рисунка; посчитанный переживёт её, а проверка ниже покажет, если разъедется.
+  return `${ART.join("\n")}\n      agent quality kit`;
+}
+
+export { banner, BANNER_WIDTH, canDrawArt };

package/tool/lib/brief.mjs

@@ -0,0 +1,192 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { CWD, PKG_ROOT, TARGET_DIR, SELF, c } from "./core.mjs";
+import { L } from "../i18n/index.mjs";
+import { canDrawArt } from "./banner.mjs";
+// tool/lib/brief.mjs — короткая строка присутствия для прогона в хуке.
+//
+// ЗАЧЕМ ЭТО СУЩЕСТВУЕТ. Хук pre-commit молчит на успехе: вывод показывается только при провале
+// — это его умолчание, проверено по документации 2026-09-08. То есть комплект, который всё
+// держит, для человека НЕОТЛИЧИМ от невставленного: он поставил, поработал неделю и не увидел
+// ни строки. «Скачал и че дальше» — дословная жалоба владельца.
+//
+// Это ровно тот порок, против которого написан весь комплект, только у нас самих: тишина
+// неотличима от успеха. Поэтому строка печатается ВСЕГДА, в том числе — и особенно — когда
+// всё хорошо. Одна строка: присутствие видно, читать нечего.
+//
+// СОВЕТ ОТДЕЛЬНО И РЕДКО. Вторая строка называет ОДНУ непоставленную запись и способ отказаться.
+// Не список: список читается как «у вас всё плохо» и не помогает выбрать. Не каждый коммит:
+// то, что видишь тридцатый раз, перестаёт читаться — и пролистывается вместе с настоящими
+// находками, стоящими рядом.
+
+// Сутки. Не «раз в прогон» и не «раз в неделю»: за сутки человек успевает забыть, но не успевает
+// устать. Число здесь спорное — важно, что ограничитель есть и он машинный.
+const ADVICE_EVERY_MS = 24 * 60 * 60 * 1000;
+
+// ЗНАЧОК ПРИСУТСТВИЯ — здесь, а не в каталогах строк. Символ один на оба языка, и держать его
+// в двух местах значит однажды получить разные значки в ru и en: то же правило, по которому у
+// нас один свод правил на две точки входа. Выбран владельцем из пятидесяти семи вариантов.
+// В терминале без UTF-8 он превратится в мусор — там правило то же, что у заставки, и оно
+// одно на двоих: разойдись эти два условия, и значок рисовался бы там, где картинка уже нет.
+const MARK = "❖";
+
+function briefLine(state, L, env = process.env) {
+  const t = L.brief;
+  const mark = canDrawArt(env) ? `${MARK} ` : "";
+  const parts = [t.held(state.held), t.todo(state.todo)];
+  if (state.level >= 0) parts.push(`AQK-${state.level}`);
+  else parts.push(t.levelUnknown);
+  const head = `${mark}${t.name}  ${parts.join(" · ")}`;
+  if (!state.red || !state.red.length) return head;
+  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 = []) {
+  return todo.length ? todo[0] : null;
+}
+
+// УВЕДОМЛЕНИЕ ОБ ОБНОВЛЕНИИ — и почему НЕ автообновление.
+//
+// Выпуски идут часто, а у половины способов установки версия закреплена и сама не двигается:
+// `rev:` у pre-commit, тег у GitHub Action. Человек ставит комплект, получает версию с уже
+// исправленной ошибкой и не узнаёт об этом никогда. У `npx` без версии проблемы нет — он берёт
+// свежее при каждом запуске.
+//
+// АВТООБНОВЛЕНИЯ НЕТ, И ЭТО РЕШЕНИЕ, А НЕ НЕДОДЕЛКА. В тот же день выпущена запись каталога,
+// краснеющая на `@latest`: «версия не закреплена — завтра приедет другая». Инструмент, который
+// молча подменяет себя, стоя на воротах коммита, делал бы ровно то, что мы запрещаем другим.
+// Первый же внешний читатель это заметит, и будет прав.
+//
+// СРАВНЕНИЕ ПО ЧИСЛАМ. Строкой «0.10.0» меньше «0.9.0», и уведомление пропало бы ровно на
+// десятом выпуске — тихо и надолго. Такие поломки не замечают месяцами.
+function cmpVer(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+// Совет зависит от способа установки: у pre-commit это `autoupdate`, а не npm. Совет мимо
+// способа человек не выполнит — и перестанет читать следующие.
+function updateNotice(current, latest, env = process.env, L) {
+  if (!current || !latest || cmpVer(latest, current) <= 0) return null;
+  const how = env.PRE_COMMIT ? L.brief.updateHookHow : L.brief.updateHow;
+  return `${L.brief.update(latest, current, how)}\n${L.brief.updateOff("AQK_UPDATE=0")}`;
+}
+
+// В конвейере не спрашиваем вовсе: там версия закреплена сознательно, читать уведомление
+// некому, а лишний исходящий запрос из инструмента, который иначе не делает ни одного, —
+// плохой размен. Отказ человека уважается тем же способом.
+function updateWanted(env = process.env) {
+  if (String(env.AQK_UPDATE || "") === "0") return false;
+  if (env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI) return false;
+  return true;
+}
+
+// КРАТКИЙ РЕЖИМ для хука. Вывод целиком БУФЕРИЗУЕТСЯ, а печатается одна строка присутствия —
+// и, при провале, весь буфер, чтобы человеку было что чинить. Перехват console.log выглядит
+// грубо, и это осознанный размен: альтернатива — протащить флаг через четыреста строк печати,
+// где каждая строка стала бы условной. Перехват локален, снимается в том же вызове и объяснён
+// здесь; условие в каждой строке объяснить было бы негде.
+function beginBrief() {
+  const lines = [];
+  const real = console.log;
+  console.log = (...a) => lines.push(a.join(" "));
+  return { lines, restore: () => { console.log = real; } };
+}
+
+// Печать краткого итога. Совет — не чаще раза в сутки и с явным способом отказаться: то, что
+// видишь тридцатый раз, перестаёт читаться и пролистывается вместе с настоящими находками рядом.
+// Отметка времени лежит в .aqk/, который в .gitignore: это состояние машины, а не проекта.
+async function finishBrief(buf, state, todoRecs, ok) {
+  if (!buf) return;
+  buf.restore();
+  console.log(briefLine(state, L));
+
+  // Уведомление об обновлении — ДО разбора вердикта: оно от него не зависит. Сначала было
+  // после, и у любого проекта, где чего-то не хватает, версия не спрашивалась никогда —
+  // то есть у всех, кому комплект и нужен. Поймано первым же живым запуском.
+  await maybeUpdateNotice();
+
+  // При провале печатаем ВЕСЬ буфер: человеку нужно чинить, а одной строкой не починишь.
+  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;
+  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 { /* не смогли записать отметку — совет повторится, это не беда */ }
+}
+
+// Спрашивает реестр npm о своей версии. РАЗ В СУТКИ, НЕ В КОНВЕЙЕРЕ, С ТАЙМАУТОМ, И МОЛЧА
+// ПРИ ЛЮБОЙ ОШИБКЕ. До этой строки комплект не делал ни одного исходящего запроса — так
+// написано в README и SECURITY.md, и там же теперь написано про этот. Сделать тихо то, за что
+// мы ругаем других, нельзя: весь смысл в том, что заявленное совпадает с происходящим.
+//
+// Код возврата не меняется никогда: уведомление, роняющее коммит, выключат в тот же день —
+// и вместе с ним всё остальное, что печатает эта строка.
+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;
+
+  let current = "";
+  try { current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || ""; } catch { return; }
+
+  // ОТМЕТКА СТАВИТСЯ ДО ЗАПРОСА, а не после удачного ответа. Сперва было наоборот, и замер
+  // показал цену: человек без сети платил бы ожиданием на КАЖДОМ коммите, а не раз в сутки.
+  // Из двух ошибок выбрана дешёвая: пропущенное за день уведомление против ежедневного стопора.
+  try {
+    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+    await writeFile(stamp, new Date().toISOString(), "utf8");
+  } catch { /* не смогли записать — спросим ещё раз, это не беда */ }
+
+  let latest = "";
+  try {
+    // Три секунды, а не полторы. Замерено 2026-09-08: тёплый запрос к реестру — 533 мс,
+    // а первый, с разрешением имени и рукопожатием, в полторы секунды не уложился. Слишком
+    // тугой срок означал бы, что уведомление не приходит никогда и никто не знает почему.
+    const r = await fetch("https://registry.npmjs.org/agent-quality-kit/latest", {
+      signal: AbortSignal.timeout(3000),
+      headers: { accept: "application/vnd.npm.install-v1+json" },
+    });
+    if (!r.ok) return;
+    latest = String((await r.json()).version || "");
+  } catch {
+    // Сети нет, реестр молчит, таймаут — всё это НЕ повод сказать хоть слово. Инструмент,
+    // который жалуется на отсутствие интернета посреди коммита, выключают.
+    return;
+  }
+
+  const notice = updateNotice(current, latest, process.env, L);
+  if (notice) console.log(c.dim(notice));
+}
+
+// Наружу — только то, что зовут снаружи. `cmpVer` и `ADVICE_EVERY_MS` внутренние: экспорт,
+// который никто не импортирует, читается как часть договора и мешает менять внутренности.
+export { briefLine, adviceDue, pickAdvice, updateNotice, updateWanted, beginBrief, finishBrief };