agent-quality-kit 0.7.0 → 0.9.0

package/tool/i18n/ru-docs.mjs

@@ -7,6 +7,132 @@
 // вторые — он же в терминале, одну секунду.
 
 const ruDocs = {
+  // Блок vitals переехал сюда 2026-09-09 по той же причине, что и brief: терминальный
+  // каталог снова перерос 500 строк, и поймал это наш же file-size-limit.
+  vitals: {
+    title: "Подключено ли то, чем комплект работает",
+    names: {
+      tools: "инструменты гейтов",
+      manifest: "манифест разобран",
+      preCommit: "хук pre-commit",
+      sessionHook: "состояние агенту",
+      version: "версия",
+    vitals: "подключено ли то, чем комплект работает: инструменты, хуки, свежесть",
+    },
+    toolsOk: (n) => `все ${n} на месте`,
+    toolsMissing: (l) => `НЕ НАЙДЕНЫ: ${l} — эти гейты не состоятся`,
+    manifestOk: "разобран целиком",
+    manifestBad: (n) => `${n} строк не разобраны и НЕ ДЕЙСТВУЮТ — подробности в doctor`,
+    unknownHook: "посмотреть не смогли — неизвестно, а не «нет»",
+    preCommitOk: "прописан в .git/hooks",
+    preCommitNo: "в .git/hooks его нет: запись в конфиге — намерение, а не защита",
+    sessionOk: "хук SessionStart отдаёт состояние агенту",
+    sessionNo: (cmd) => `агент не получает состояние: ${cmd}`,
+    versionOk: (v) => `${v}, свежая`,
+    versionOld: (l, cur) => `есть ${l}, у вас ${cur}`,
+  },
+  // Блок краткого вывода переехал сюда 2026-09-09: терминальный каталог снова перерос
+  // 500 строк, и поймал это наш же file-size-limit. Шов по смыслу условен — это всё-таки
+  // терминал, — но предел настоящий, а делить пополам хуже, чем делить по соседству.
+  brief: {
+    name: "AQK",
+    held: (n) => `держит ${n}`,
+    todo: (n) => `не поставлено ${n}`,
+    levelUnknown: "уровень неизвестен",
+    red: (l) => `     КРАСНЫЕ: ${l}`,
+    advise: (slug, why) => `     ↑ поставить: ${slug} — ${why}`,
+    adviseOff: (cmd, env) => `       не нужно: ${cmd}, либо ${env}`,
+    update: (l, c, how) => `новая версия ${l}, у вас ${c} — обновить: ${how}`,
+    updateHow: "npx agent-quality-kit@latest, либо npm i -g agent-quality-kit",
+    updateHookHow: "pre-commit autoupdate",
+    updateOff: (env) => `       не нужно: ${env}`,
+  },
+  // БЛОК СОСТОЯНИЯ — единственный наш текст, у которого читатель машина, а не человек.
+  // Уходит в контекст агента хуком SessionStart, поэтому пишется как утверждения о факте:
+  // без вежливости, без вводных, каждая строка либо факт, либо честное «неизвестно».
+  // Замер 2026-09-08: блок ≈147 токенов против ≈3348 у AGENTS.md — и несёт то, чего в файле
+  // нет и быть не может, потому что меняется каждый день.
+  context: {
+    title: "AQK — состояние этого репозитория на сейчас. Ниже только вычисленное машиной; где\nмашина не знает — сказано «неизвестно», и это не «всё хорошо».",
+    level: (r, top, missing) =>
+      `Уровень: AQK-${r} из ${top}.` + (missing ? ` До AQK-${r + 1} не хватает: ${missing}.` : ""),
+    levelUnknown: "Уровень: не вычислен — в репозитории нет .aqk.yml. Стандарт здесь не заведён.",
+    rules: (total, machine, human) =>
+      `Правил в точке входа: ${total}. Держит машина ${machine}, держит человек ${human}.`,
+    rulesNobody: "Правило, которое держит человек, не держит никто: машина его не проверяет.",
+    runNone:
+      "Прогон не делался — какие проверки красные, НЕИЗВЕСТНО. Это не «чисто»: `aqk doctor --run`.",
+    runStale: (when) =>
+      `Последний прогон ${when} СТАРЕЕ последнего коммита — он описывает не тот код, что здесь.`,
+    runClean: (when) => `Последний прогон ${when} — красных нет.`,
+    runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
+    andMore: (n) => `и ещё ${n}`,
+    skipped: (n) => `Не запускались: ${n} — инструмента нет на этой машине, их состояние неизвестно.`,
+    ratchets: (list) => `Храповики: ${list}. Список может только укорачиваться, увеличивать нельзя.`,
+    where: (entry) => `Свод правил: ${entry}. Чем доказан диф: \`aqk report --since main\`.`,
+    mapTitle: "ЧТО УМЕЕТ ЭТОТ ИНСТРУМЕНТ. Полный список команд — не пересказ, а тот же список,\nиз которого собрана справка:",
+    rulesTitle: (e) => `СВОД ПРАВИЛ ЭТОГО ПРОЕКТА (${e}) — дословно, целиком. Это не приглашение\nпрочитать: он уже здесь.`,
+    hookAlready: (p) => `хук уже стоит в ${p} — ничего не меняю.`,
+    hookAdded: (p) => `хук SessionStart дописан в ${p}:`,
+    hookCreated: (p) => `создан ${p} с хуком SessionStart:`,
+    hookBadJson: (p) => `${p} не разбирается как JSON — не трогаю его. Почини файл и повтори.`,
+    hookWhat:
+      "теперь состояние проекта попадает в контекст агента до первого действия, а не по его желанию.",
+  },
+  // Форма отчёта переехала сюда из терминального каталога 2026-09-08: это текст, который
+  // программа ПИШЕТ в .aqk/report.md, а не говорит в терминал. Повод — тот же гейт
+  // file-size-limit, что развёл эти файлы в первый раз: терминальный каталог снова перерос
+  // 500 строк. Шов по смыслу, а не пополам.
+  report2: {
+    evidenceNamed: (who) => `назван проверками: ${who}`,
+    evidenceSilent: (n) => `${n} ${n === 1 ? "проверка прошла" : "проверок прошли"} мимо и промолчали`,
+    evidenceTitle: "Чем доказан этот диф",
+    evidenceUncovered: "ни одна проверка не назвала этот файл",
+    evidenceBase: "база сравнения",
+    evidenceHash: "отпечаток доказательства",
+    evidenceBadRef: (r) => `ссылка «${r}» не разобрана — покрытие не считано`,
+    evidenceNoFiles: (r) => `файлов кода в дифе с «${r}» нет — доказывать нечего`,
+    evidenceWarn:
+      "◻️ означает: проверка обошла каталог и ничего не сказала. «Просмотрен и чист» и «не " +
+      "просмотрен вовсе» по выводу неразличимы — и выдавать одно за другое нельзя ни в ту, ни " +
+      "в другую сторону. " +
+      "Отпечаток считается по базе, набору команд и содержимому файлов. Изменилось что-то из " +
+      "этого — отчёт устарел, и «прогнал, потом поправил ещё три файла» перестаёт быть " +
+      "неотличимым от «прогнал». Механизм взят у donecheck (MIT).",
+    title: "Отчёт AQK",
+    noManifest: (cmd) => `Нет .aqk.yml — отчитываться не о чем. Начни с ${cmd}`,
+    level: "Уровень",
+    holdsTitle: "Что держит машина (прогон, а не манифест)",
+    nothingRuns: "⬜ ни один гейт не объявлен",
+    native: (prog) => `родной рецепт: ${prog}`,
+    portable: "переносимая проверка",
+    weakerTitle: "Стоит слабее возможного",
+    weaker: (progs) => `в системе есть ${progs}, но гейт стоит на переносимой проверке — она ловит меньше`,
+    missingTitle: "Чего нет",
+    nothingMissing: "✅ все применимые записи поставлены",
+    needsTool: (prog) => `нужен ${prog} — его нет в системе`,
+    notInstalled: "применимо, но не поставлено",
+    hiddenTitle: "Не применимо к этому репозиторию",
+    readTitle: "Что комплект велел прочитать",
+    readWarn:
+      "Значок означает только наличие файла на диске. Прочитан он или нет, машина не знает и " +
+      "не притворяется, что знает: это отвечает тот, кто отчитывается.",
+    ignoreTitle: "Что спрятано .aqkignore",
+    ignoreNone: "файла .aqkignore нет — ничего не спрятано",
+    ignoreWarn:
+      "Скрытое молча — тот же класс, что молчащий гейт: гейты по этим путям не смотрят вовсе. " +
+      "Строка здесь означает, что защиты там нет и не будет.",
+    whyTitle: "Зачем это нужно — коротко",
+    whyNothing: "нечего добавлять: применимое уже стоит",
+    saved: (path) => `Сохранено: ${path}`,
+    docs: {
+      baseline: "обязательный минимум проекта, без привязки к языку",
+      readyMade: "карта готовых правил: сперва ищи готовое, потом пиши своё",
+      rulesGeneral: "общие правила работы",
+      rulesTesting: "правила про тесты",
+      rulesSecurity: "правила про безопасность",
+    },
+  },
   manifestDoc: {
     head: [
       "# .aqk.yml — манифест Agent Quality Kit",
@@ -15,7 +141,7 @@ const ruDocs = {
       "# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.",
     ],
     entry: "# AQK-0 — что агент читает первым.",
-    rules: "# AQK-1 — где стандарты и какие проверки обязательны.",
+    rules: "# AQK-1 — где стандарты и какие проверки обязательны. docs — где методички:\n# оба пути читает doctor, так что комплект можно разложить куда угодно.",
     gates: [
       "  # Имя: команда, возвращающая 0 или не 0. Пустое объявление защиты не даёт и бракуется",
       "  # проверкой «объявленный гейт запускается» — поэтому здесь примеры, а не заготовки.",

package/tool/i18n/ru.mjs

@@ -9,6 +9,18 @@ import { ruDocs } from "./ru-docs.mjs";
 import { templates } from "./templates-ru.mjs";
 
 export const ru = {
+  learn: {
+    title: "Сказано вслух и не записано",
+    noLogs: (p) => `логов этого проекта нет: ${p}\n  Команда читает переписку Claude Code на этой машине. Пусто — значит здесь не работали.`,
+    counted: (s, typed, said, fresh) =>
+      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh}`,
+    nothing: "всё, что похоже на правило, уже стоит в точке входа",
+    andMore: (n) => `… и ещё ${n}`,
+    warn:
+      "Это КАНДИДАТЫ, а не находки: на замере из 1619 реплик маркеры дали 79, и настоящих правил " +
+      "среди них примерно половина. Решает человек. Ничего не записано на диск — команда читает " +
+      "переписку и печатает только в терминал.",
+  },
   ...ruDocs,
   templates,
   help: {
@@ -28,13 +40,21 @@ export const ru = {
     new: "заготовка своего гейта для каталога",
     note: "записать урок в общий журнал шишек",
     blob: "собрать методички в один файл GOD_AI.md",
-    report: "обязательная форма отчёта: что стоит, что нет, что не прочитано",
+    learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
+    context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
+    contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
+    report: "обязательная форма отчёта: что стоит, что нет, что не прочитано; --since <ссылка> — ещё и чем доказан диф",
     badge: "значок уровня для README — и проверка, что он не врёт",
+    version: "заставка и номер версии — то же по --version и -v",
     noInstall: "Без установки:  npx agent-quality-kit init",
     language: "Язык вывода: AQK_LANG=en (или ru), иначе по системной локали",
   },
 
   doctor: {
+    baselineClash: (f) =>
+      `«--baseline» — осмотр, а не прогон: он выходит с нулём всегда, и вместе с «${f}» даёт\n` +
+      "  конвейер, который не может покраснеть.\n" +
+      "  почини: раздели на две команды — «doctor --baseline» и «doctor --run --min 1».",
     docsKit: "методички — здесь оригиналы, а не копия",
     docs: "методички",
     rulesKit: "стандарты — здесь оригиналы, а не копия",
@@ -69,6 +89,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}`,
@@ -78,6 +108,7 @@ export const ru = {
     sinceBadRef: (ref) => `не могу сравнить с «${ref}»: такой ссылки нет или это не репозиторий git`,
     notScopable: "вывод без путей — дифом не сужается, оставлен красным",
     outsideDiff: (n) => `находки есть, но вне дифа (${n})`,
+    advisoryQuiet: "(совещательный — уронить прогон не может)",
     advisoryMark: "совещательный — показано, прогон не уронен",
     advisorySummary: (names) =>
       `совещательные и красные: ${names.join(", ")}. Это выключенные проверки: ` +
@@ -92,6 +123,9 @@ export const ru = {
     manifestUnknown: (keys) =>
       `В манифесте поля, которых стандарт не знает: ${keys.join(", ")}. Похоже на опечатку — ` +
       `такое поле молча читается как отсутствующее, и вердикт выходит неверным.`,
+    manifestUnparsed: (n, t) => `строка ${n} манифеста не разобрана и НЕ ДЕЙСТВУЕТ: ${t}`,
+    manifestUnparsedWhy:
+      "имена полей и гейтов пишутся латиницей, цифрами, дефисом и подчёркиванием. Объявленное\n  здесь не выполняется вовсе — а выглядит так, будто выполняется.",
     manifestKnown: (keys) => `Поля манифеста: ${keys.join(", ")}`,
     thresholdPass: (min) => `Порог AQK-${min} пройден.`,
     thresholdFail: (min, now) => `Порог AQK-${min} НЕ пройден: сейчас AQK-${now}.`,
@@ -151,6 +185,7 @@ export const ru = {
       has_agent_config: ["агента здесь не настраивали", "настройки агента есть"],
       has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
+      has_mcp: ["агенту здесь не подключали внешних инструментов через MCP", "MCP-серверы объявлены"],
     },
   },
 
@@ -347,12 +382,14 @@ export const ru = {
     n4c: ". Гейт стережёт существующий артефакт:",
     n4d: "проверка на код, которого ещё нет, — мёртвое правило.",
     burned: (cmd) => `Обжёгся на чём-то — запиши: ${cmd}`,
+    hookHint: (cmd) => `Claude Code: ${cmd} — состояние проекта будет попадать в контекст агента\n  само, до первого действия. Для других агентов хука нет, и это не недоделка.`,
   },
 
   feedback: {
     title: "Если пригодилось:",
     star: (url) => `Поставь звезду — ${url}`,
     issue: "Нашёл баг или не подошло — заведи Issue, самая полезная обратная связь: и то и другое.",
+    notRemembered: "запомнить не удалось (дом недоступен для записи) — сообщение появится снова",
     once: "Это разовое сообщение: больше не покажется на этой машине.",
   },
 
@@ -434,6 +471,7 @@ export const ru = {
     noTarget: "не видно, куда подставить каталог образца — команда написана руками",
     otherRecipe: (lang) => `образцы написаны под рецепт «${lang}», а стоит другой — доказать нечем`,
     noGates: "гейтов не объявлено — доказывать нечего",
+    needsProgram: (progs) => `НЕ ПРОВЕРЕНА здесь — нужен «${progs}»`,
     noSamplesDir: "в .aqk.yml не заполнено поле samples — образцы искать негде",
     nothingProven:
       "ни один гейт не доказан. Уровень выше AQK-1 означал бы доверие к автору, а не факт:\n  проект с гейтом «true» прошёл бы его так же, как проект с настоящей защитой.",
@@ -452,41 +490,6 @@ export const ru = {
     checkOk: (level, where) => `Значок совпал с прогоном: AQK-${level} — ${where}`,
   },
 
-  report2: {
-    title: "Отчёт AQK",
-    noManifest: (cmd) => `Нет .aqk.yml — отчитываться не о чем. Начни с ${cmd}`,
-    level: "Уровень",
-    holdsTitle: "Что держит машина (прогон, а не манифест)",
-    nothingRuns: "⬜ ни один гейт не объявлен",
-    native: (prog) => `родной рецепт: ${prog}`,
-    portable: "переносимая проверка",
-    weakerTitle: "Стоит слабее возможного",
-    weaker: (progs) => `в системе есть ${progs}, но гейт стоит на переносимой проверке — она ловит меньше`,
-    missingTitle: "Чего нет",
-    nothingMissing: "✅ все применимые записи поставлены",
-    needsTool: (prog) => `нужен ${prog} — его нет в системе`,
-    notInstalled: "применимо, но не поставлено",
-    hiddenTitle: "Не применимо к этому репозиторию",
-    readTitle: "Что комплект велел прочитать",
-    readWarn:
-      "Значок означает только наличие файла на диске. Прочитан он или нет, машина не знает и " +
-      "не притворяется, что знает: это отвечает тот, кто отчитывается.",
-    ignoreTitle: "Что спрятано .aqkignore",
-    ignoreNone: "файла .aqkignore нет — ничего не спрятано",
-    ignoreWarn:
-      "Скрытое молча — тот же класс, что молчащий гейт: гейты по этим путям не смотрят вовсе. " +
-      "Строка здесь означает, что защиты там нет и не будет.",
-    whyTitle: "Зачем это нужно — коротко",
-    whyNothing: "нечего добавлять: применимое уже стоит",
-    saved: (path) => `Сохранено: ${path}`,
-    docs: {
-      baseline: "обязательный минимум проекта, без привязки к языку",
-      readyMade: "карта готовых правил: сперва ищи готовое, потом пиши своё",
-      rulesGeneral: "общие правила работы",
-      rulesTesting: "правила про тесты",
-      rulesSecurity: "правила про безопасность",
-    },
-  },
 
 
 };

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 };

package/tool/lib/core.mjs

@@ -57,6 +57,37 @@ function selfCmd() {
 
 const SELF = selfCmd();
 
+// КАРТА КОМАНД — ОДИН список на справку в терминале и на карту, уходящую в контекст агента.
+// Два списка рядом через месяц врут по-разному, и непонятно, какой настоящий: это записано
+// у нас в CLAUDE.md про своды правил и верно здесь буквально так же. Модульная проверка
+// сторожит, что список не отстал от диспетчера в program.mjs.
+function commandRows(L) {
+  const h = L.help;
+  return [
+    { name: "init", args: "", text: h.init },
+    { name: "init", args: "--force", text: h.initForce },
+    { name: "start", args: "", text: h.start },
+    { name: "doctor", args: "", text: h.doctor },
+    { name: "doctor", args: "--run", text: h.doctorRun },
+    { name: "doctor", args: "--run --since main", text: h.doctorSince },
+    { name: "prove", args: "", text: h.prove },
+    { name: "add", args: h.name, text: h.add },
+    { name: "find", args: '"…"', text: h.find },
+    { name: "why", args: '"…"', text: h.why },
+    { name: "ratchet", args: h.name, text: h.ratchet },
+    { name: "new", args: h.name, text: h.new },
+    { name: "note", args: '"…"', text: h.note },
+    { name: "blob", args: "", text: h.blob },
+    { name: "report", args: "", text: h.report },
+    { name: "learn", args: "", text: h.learn },
+    { name: "context", args: "", text: h.context },
+    { name: "context", args: "--full --install", text: h.contextInstall },
+    { name: "badge", args: "", text: h.badge },
+    { name: "vitals", args: "", text: h.vitals },
+    { name: "version", args: "", text: h.version },
+  ];
+}
+
 function die(msg) {
   console.error(c.red(msg));
   process.exit(1);
@@ -114,5 +145,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,
+  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK, commandRows,
 };