agent-quality-kit 0.12.0 → 0.14.0

package/tool/i18n/en.mjs

@@ -7,14 +7,20 @@ import { enDocs } from "./en-docs.mjs";
 
 import { templates } from "./templates-en.mjs";
 
+const ago = (n) => (n === null || n === undefined ? "" : ` (${n} commit${n === 1 ? "" : "s"} ago)`);
+
 import { enGates } from "./en-gates.mjs";
 
 export const en = {
   learn: {
     title: "Said out loud, never written down",
     noLogs: (p) => `no logs for this project: ${p}\n  The command reads Claude Code transcripts on this machine. Empty means nobody worked here.`,
-    counted: (s, typed, said, fresh) =>
-      `sessions: ${s} · typed by a human: ${typed} · looks like an instruction: ${said} · not in the entry point: ${fresh}`,
+    counted: (s, typed, said, fresh, again) =>
+      `sessions: ${s} · typed by a human: ${typed} · looks like an instruction: ${said} · not in the entry point: ${fresh} · repeated: ${again}`,
+    ruleTitle: "Written down, yet you still have to correct it:",
+    ruleHow: "The rule is in the entry point, and you are repeating it to the agent again — text alone does not hold it. It needs a machine guard: aqk find \"…\" or aqk new <name>.",
+    repeatTitle: "Repeated — you have said this before (\"I told you\", \"again\"):",
+    restTitle: "The rest that looks like a rule and is not written down:",
     nothing: "everything that looks like a rule is already in the entry point",
     andMore: (n) => `… and ${n} more`,
     warn:
@@ -44,6 +50,8 @@ export const en = {
     blob: "assemble the guides into a single GOD_AI.md",
     learn: "rule candidates from local transcripts: said out loud, never written down",
     context: "the project state in one block — for an agent's context, not for reading",
+    vitals: "is what the kit runs on wired up: gate tools, hooks, version freshness",
+    prompt: "one task for the agent: what to fix, in order, and how to prove it is done",
     contextInstall: "the same in full — the map and the rulebook — installed as a hook",
     report: "the mandatory report form: what is in place, what is not, what was not read; --since <ref> adds what proves the diff",
     badge: "a level badge for your README — and a check that it does not lie",
@@ -65,6 +73,22 @@ export const en = {
     gitignore: "repository hygiene",
     git: "project under version control",
 
+    runtimeTracked: (f, cmd) => `${f} is tracked by git — every run rewrites it, and the tree always shows a modified file. Take it out: ${cmd}`,
+    runtimeNotIgnored: (f, cmd) => `${f} is this machine's state, yet git sees it: one \`git add .\` and it is in a commit. Hide it: ${cmd}`,
+    layoutAdvice: "missing — advice, it does not fail the run",
+    coversImpossible: (entry, gate, linter) => `the claim "${gate} holds ${entry}" is wrong: ${linter} has no rule for this class — there is nothing to hold it with`,
+    coversCantCheck: (entry, gate) => `cannot check the claim "${gate} holds ${entry}": the gate's linter is not recognised or the entry has no rules for it — taken on trust`,
+    selectUnknown: (names, groups) => `--only/--skip: "${names}" is neither a gate from gates: nor a group from groups:${groups ? ` (groups: ${groups})` : ""}. Running everything instead of skipping would be a lie, so stopping.`,
+    selectSkipped: (names) => `not run (by --only/--skip): ${names} — their state is unknown, they are not "green"`,
+    claudeShim: {
+      missing: "Claude Code is set up here (.claude/), but the rules live in AGENTS.md — it does not read that file. Fix: a CLAUDE.md with the single line \"@AGENTS.md\".",
+      noImport: "CLAUDE.md does not import AGENTS.md — Claude Code only sees CLAUDE.md. Fix: add the line \"@AGENTS.md\" to CLAUDE.md (mentioning the file in prose does not load it).",
+    },
+    annotDropped: (n, more) => `pull request annotations: ${n}, ${more} more not shown — GitHub takes about ten per step; every finding is in the log above`,
+    heldQuiet: (n, cmd) => `held by the machine: ${n} — by name: ${cmd}`,
+    skipQuiet: (n, cmd) => `not applicable to this repository: ${n} — by name and why: ${cmd}`,
+    passedQuiet: (n) => `${n} more passed — by name: --verbose`,
+    jobsBad: (v) => `--jobs expects a whole number from 1: "${v}" will not do. A one-by-one run passed off as parallel would be a lie, so stopping.`,
     rulesByHuman: (total, machine, human) =>
       `${human} of ${total} rules in the entry point are guarded by a HUMAN, ${machine} by a machine.`,
     rulesByHumanWhy: "A rule guarded by a human is guarded by nobody the day the human is busy. That is the hole this kit exists to close — and the reminder belongs to the human, not only to the agent. Counted in the ENTRY POINT only: a promise kept in any other file is checked by nothing at all, and this kit will not tell you it exists.",
@@ -86,6 +110,17 @@ export const en = {
     toReach: (n) => `To reach AQK-${n}:`,
     gives: (what) => `What it buys you: ${what}`,
     allDone: "All levels reached.",
+    limitsTitle: "A level measures tooling, not reliability. What it does not prove:",
+    limitsProbe: {
+      never: (_, cmd) => `defects in your files: the probe has never run — ${cmd}`,
+      off: () => "defects in your files: the probe is off (probe: 0) — whether your checks catch them is unknown",
+      blind: ({ names, behind }) => `defects in your files: the probe${ago(behind)} did NOT catch — ${names.join(", ")}`,
+      partial: ({ caught, unknown, behind }, cmd) => `defects in your files: the probe${ago(behind)} caught ${caught} classes, ${unknown} unproven (${cmd})`,
+      caught: ({ caught, behind }) => `defects in your files: the probe${ago(behind)} caught all ${caught} planted classes — only those the catalog has`,
+      nothing: ({ behind }, cmd) => `defects in your files: the probe${ago(behind)} planted nothing — ${cmd}`,
+      old: ({ behind }, cmd) => `defects in your files: the probe ran${ago(behind)}; ${cmd} shows the result`,
+    },
+    limitsCi: "pipeline: whether it passed is not visible from here — we only check that gates are declared in it",
 
     gatesHeading: "Gates",
     langs: "languages",
@@ -108,7 +143,9 @@ export const en = {
     blindRan: (g) => `gate ${g} is declared and was run — and still missed the defect in this file`,
     blindInstalled: "declared, but the probe did not run this gate (added later or too slow) — the next probe will show whether it catches",
     blindMore: (cmd) => `what was planted and where — ${cmd}`,
-    probeNever: (cmd) => `Whether your checks catch a real defect has not been tested yet: ${cmd} plants one in a copy of the project and shows (a minute or two, your files are not touched).`,
+    probeNever: (cmd) => `Whether your checks catch a real defect has not been tested yet: ${cmd} plants one in a copy of the project and shows (a minute or two, your project files are not changed).`,
+    todoRest: (n) => `The other entries that apply here (${n}):`,
+    todoRestHow: (self) => `install any: ${self} add <name> · what it catches and why: ${self} why <name>`,
     startWith: "Start with these three — born from a real failure, and each closes with one ready command:",
     startCmd: (cmd) => `one line, no kit needed:  ${cmd}`,
     startTool: (url) => `the tool: ${url}`,
@@ -199,12 +236,13 @@ export const en = {
       has_docker: ["no Dockerfile or compose", "docker is already here"],
       has_deps: ["no dependency file in sight", "dependencies are declared"],
       has_tests: ["no tests in sight", "tests exist"],
+      has_biome: ["the linter is not Biome", "the project's linter is Biome"],
       has_env: ["no environment file", "an environment file exists"],
       has_agent_config: ["the agent was never configured here", "agent settings exist"],
       has_agent_entry: ["no entry point for an agent here", "an entry point for an agent exists"],
       has_ui: ["no stylesheets or UI components in sight", "a UI exists: stylesheets or components"],
       has_mcp: ["no MCP tools are wired up for the agent here", "MCP servers are declared"],
-      has_api_spec: ["no API specification in sight", "an API specification exists"],
+      has_api_spec: ["no API contract in sight: no OpenAPI file, no tRPC, ts-rest or Fastify type provider", "an API contract exists: a specification file or schemas in code"],
     },
   },
 
@@ -230,5 +268,41 @@ export const en = {
     alreadyDeclared: "already declared",
   },
 
+  prompt: {
+    title: "# Task: get this project's checks actually working",
+    intro: "Written by AQK from the current state of the repository. Do the items in order.",
+    rulesTitle: "## Ground rules",
+    rules: [
+      "Use only commands from this task and from the repository. Do not invent any.",
+      "Run an item's check first and see it fail. Then fix. Done means the same command passes.",
+      "Fix the code, not the check: do not loosen a threshold, add exclusions or switch a gate off. If you think a check is wrong, stop and ask the owner.",
+      "A decision only the owner can make (what to add to the project, which rules to adopt) — ask, do not guess.",
+      "Change only what these items need.",
+    ],
+    tasksTitle: "## What to do",
+    empty: "Nothing to do: no gate is red, the probe found nothing, nothing to add. Still run the verification below.",
+    done: "Done —",
+    item: {
+      init: (s) => `Create the manifest: \`${s} init\` — without it the other commands refuse. Done — \`${s} doctor\` shows a level.`,
+      runNone: (s) => `There has been no run yet. Run \`${s} doctor --run\` and fix whatever turns red, one gate at a time: \`${s} doctor --run --only <name>\`. Done — the run passes.`,
+      runStale: (s, when) => `The run from ${when} is older than the last commit — the red list below may describe other code. Run \`${s} doctor --run\` again. Done — you have a fresh result and have checked the items below against it.`,
+      missed: ({ slug, file }, s) => `Gate \`${slug}\` is installed but missed the defect the probe planted into \`${file}\`. Find out why — a common cause is that the gate does not look at this file type or folder; \`${s} probe\` has the details. Done — \`${s} probe\` no longer names this class.`,
+      red: (name, s) => `Gate \`${name}\` is red. Run \`${s} doctor --run --only ${name}\`, read the findings and fix the code. Done — that command passes.`,
+      blind: ({ slug, file, command }, s) => `The probe planted a \`${slug}\` defect into \`${file}\` and the project's checks did not notice. Add a check: \`${s} add ${slug}\`${command ? ` (the same as one line, without the kit: \`${command}\`)` : ""}. Done — \`${s} doctor --run --only ${slug}\` passes and \`${s} probe\` no longer names this class.`,
+      adopt: (gates, s) => `The project already has its own checks: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Declare them under gates: in .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Done — \`${s} doctor --run\` runs them.`,
+      shim: {
+        missing: (s) => `Claude Code is set up here, but the rules live in AGENTS.md — it only reads CLAUDE.md. Create a CLAUDE.md with the single line \`@AGENTS.md\`. Done — \`${s} doctor\` no longer warns about it.`,
+        noImport: (s) => `CLAUDE.md does not import AGENTS.md — Claude Code only sees CLAUDE.md. Add the line \`@AGENTS.md\` to CLAUDE.md (mentioning the file in prose does not load it). Done — \`${s} doctor\` no longer warns about it.`,
+      },
+      start: ({ slug, intent, command }, s) => `Propose the \`${slug}\` check to the owner${intent ? ` — ${intent}` : ""}. If they agree — \`${s} add ${slug}\`${command ? ` (the same as one line, without the kit: \`${command}\`)` : ""}. If it fails on existing code, do not silence it — show the findings to the owner. Done — \`${s} doctor --run --only ${slug}\` passes and \`${s} prove\` shows it proven.`,
+    },
+    more: (n, s) => `And ${n} more — the full list: \`${s} doctor\`. Finish these first.`,
+    verifyTitle: "## How to verify it is done",
+    verify: (s) => [
+      `\`${s} doctor --run\` — the run passes.`,
+      `\`${s} prove\` — no gate is broken: each one fails on its own red sample.`,
+      "Name these commands and their results in your report. \"Looks like it works\" is not done.",
+    ],
+  },
   ...enGates,
 };

package/tool/i18n/index.mjs

@@ -29,13 +29,19 @@ import { en } from "./en.mjs";
 // Переменная окружения оставлена ВЫШЕ манифеста намеренно: человек, набравший AQK_LANG=en
 // руками, хочет английский именно сейчас, и спорить с ним манифестом значит отнять у него
 // последнее средство. Манифест выше локали — он про проект, локаль про машину.
-function pickLang(env = process.env, man = null) {
+//
+// Третьим — ЯЗЫК СВОДА ПРОЕКТА, между манифестом и локалью. Отзыв с живого проекта 2026-09-11:
+// свод и методички на русском, Windows без LANG — весь вывод английский, пока руками не впишешь
+// `lang:`. Текст, который проект сам о себе написал, — такое же свойство проекта, как поле
+// манифеста, только необъявленное: поэтому ниже поля и выше машины.
+function pickLang(env = process.env, man = null, docs = "") {
   const forced = String(env.AQK_LANG || "").toLowerCase();
   if (forced.startsWith("ru")) return "ru";
   if (forced.startsWith("en")) return "en";
   const declared = String(man?.lang || "").toLowerCase();
   if (declared.startsWith("ru")) return "ru";
   if (declared.startsWith("en")) return "en";
+  if (docs === "ru" || docs === "en") return docs;
   const locale = String(env.LC_ALL || env.LC_MESSAGES || env.LANG || "").toLowerCase();
   if (locale.startsWith("ru")) return "ru";
   return "en";
@@ -59,8 +65,41 @@ function manifestLang(cwd = process.cwd()) {
   }
 }
 
+// Язык прозы: код, пути и адреса вырезаются — в русском своде половина слов это `npm run check`
+// и `packages/contract`, и по всем буквам подряд он вышел бы английским. Порог с запасом в обе
+// стороны: кириллицы больше половины букв — русский, меньше десятой при хотя бы двухстах
+// буквах — английский; между ними и на коротком тексте свод молчит, и решает локаль.
+function langFromDocs(text) {
+  const prose = String(text)
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`\n]*`/g, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/https?:\/\/\S+/g, " ");
+  const cyr = (prose.match(/[а-яё]/gi) || []).length;
+  const lat = (prose.match(/[a-z]/gi) || []).length;
+  const all = cyr + lat;
+  if (all < 200) return "";
+  if (cyr / all >= 0.5) return "ru";
+  if (cyr / all <= 0.1) return "en";
+  return "";
+}
+
+// Первые 8 КБ каждого из трёх файлов: язык виден по первому экрану, а читать мегабайтный README
+// ради одной буквы в начале каждой команды — дорого.
+function docsLang(cwd = process.cwd()) {
+  let text = "";
+  for (const name of ["AGENTS.md", "CLAUDE.md", "README.md"]) {
+    try {
+      text += readFileSync(join(cwd, name), "utf8").slice(0, 8192) + "\n";
+    } catch {
+      // Файла нет — язык решат остальные.
+    }
+  }
+  return langFromDocs(text);
+}
+
 const CATALOGS = { ru, en };
-const LANG = pickLang(process.env, manifestLang());
+const LANG = pickLang(process.env, manifestLang(), docsLang());
 const L = CATALOGS[LANG];
 
-export { L, LANG, pickLang, langFromText, CATALOGS };
+export { L, LANG, pickLang, langFromText, langFromDocs, CATALOGS };

package/tool/i18n/ru-docs.mjs

@@ -68,7 +68,7 @@ const ruDocs = {
     runClean: (when) => `Последний прогон ${when} — красных нет.`,
     runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
     andMore: (n) => `и ещё ${n}`,
-    skipped: (n) => `Не запускались: ${n} — инструмента нет на этой машине, их состояние неизвестно.`,
+    skipped: (n) => `Не запускались: ${n} — пропущены по --only/--skip или инструмента нет на этой машине; их состояние неизвестно.`,
     probeNever: "Проба покрытия не делалась — что здесь не прикрыто ничем, НЕИЗВЕСТНО. Это не «прикрыто»: `aqk probe`.",
     probeOff: "Проба покрытия выключена в манифесте (`probe: 0`) — что здесь не прикрыто ничем, никто не считает.",
     probeUnknown: "Пробу покрытия провести не удалось — что здесь не прикрыто ничем, НЕИЗВЕСТНО. Это не «прикрыто».",
@@ -81,6 +81,28 @@ const ruDocs = {
       (behind ? ` (отстала на ${behind} коммитов)` : "") + ".",
     ratchets: (list) => `Храповики: ${list}. Список может только укорачиваться, увеличивать нельзя.`,
     where: (entry) => `Свод правил: ${entry}. Чем доказан диф: \`aqk report --since main\`.`,
+    nextTitle: "Дальше, по порядку — вычислено из этого репозитория, а не общий совет:",
+    // По виду шага — таблица, а не лесенка тернарников: её не держат в голове, и наш же
+    // 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\`.`,
+      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}\`)` : "") +
+        ", затем `aqk prove` — гейт обязан покраснеть на своём красном образце.",
+    },
+    nextMore: (n) => `И ещё ${n} — весь список: \`aqk doctor\`.`,
+    whenTitle: "Когда что делать:",
+    whenCommit: (hook) => hook === true
+      ? "Перед коммитом → хук `.git/hooks/pre-commit` прогонит проверки сам; не обходи его (`--no-verify`)."
+      : "Перед коммитом → `aqk doctor --run --since main`: хука перед коммитом нет, само это не случится.",
+    whenRules: [
+      "Добавил или поменял проверку → `aqk prove`: гейт обязан покраснеть на своём красном образце, иначе он не проверяет ничего.",
+      "Пишешь правило в свод → рядом метка арбитра `<!-- aqk: имя-гейта -->`; гейта нет — `<!-- aqk: человек -->`, и это признание, а не проверка.",
+      "Проверка мешает → не ослабляй её (`|| true`, `--exit-zero`, подавление без кода правила): остановись и спроси владельца.",
+      "Считаешь, что готово → `aqk report --since main`: каждый изменённый файл должен быть назван проверкой.",
+    ],
     mapTitle: "ЧТО УМЕЕТ ЭТОТ ИНСТРУМЕНТ. Полный список команд — не пересказ, а тот же список,\nиз которого собрана справка:",
     rulesTitle: (e) => `СВОД ПРАВИЛ ЭТОГО ПРОЕКТА (${e}) — дословно, целиком. Это не приглашение\nпрочитать: он уже здесь.`,
     hookAlready: (p) => `хук уже стоит в ${p} — ничего не меняю.`,
@@ -198,6 +220,7 @@ const ruDocs = {
     },
   ],
   report: {
+    skippedBySelect: "не запускался (по --only/--skip), состояние неизвестно",
     title: "aqk doctor --run",
     version: "версия",
     level: "уровень",

package/tool/i18n/ru-gates.mjs

@@ -160,6 +160,7 @@ export const ruGates = {
       "методички в .aqk/docs/ остаются на русском — решение, а не недоделка.",
     created: (n) => `создано (${n}):`,
     andMore: (n) => `… и ещё ${n}`,
+    ignored: (list) => `служебные файлы комплекта дописаны в .gitignore — это состояние машины, в git ему не место: ${list}`,
     kept: (n) => `уже были на месте, не тронуты (${n}):`,
     overwrite: (cmd) => `перезаписать: ${cmd}`,
     nextTitle: "Что дальше — по порядку:",
@@ -257,16 +258,20 @@ export const ruGates = {
     badEvery: (v) => `в манифесте probe: «${v}» — это не число коммитов. Проба НЕ делается: подставить умолчание значило бы делать не то, что написано.`,
     autoFirst: "пробы покрытия здесь ещё не делали — делаю её сам. Выключить: AQK_PROBE=0",
     auto: (n) => `прошло ${n} коммитов с прошлой пробы — делаю её сам. Выключить: AQK_PROBE=0`,
+    autoNotInCi: (cmd) => `в конвейере проба сама не запускается — это минуты сюрпризом в быстрой проверке; поставьте её отдельной задачей: ${cmd} (или AQK_PROBE=1)`,
     title: "aqk probe — чего объявленные проверки не видят",
     method: (files, entries, gates) =>
       `способ: красный образец записи каталога подсаживается в КОПИЮ проекта, и там гоняются ` +
       `ОБЪЯВЛЕННЫЕ гейты — команда берётся как написана, в неё ничего не подставляется. ` +
       `Файлов: ${files}, применимых записей: ${entries}, гейтов зелёных на чистом дереве: ${gates}. ` +
-      `Рабочее дерево не трогается.`,
+      `Файлы проекта не меняются; итог пробы пишется в .aqk/last-probe.md (он в .gitignore после init).`,
     fixes: (n) => `починок в истории: ${n}`,
     caught: (names) => `ловит: ${names}`,
     blind: "НЕ ЛОВИТ НИКТО",
     unknown: "проверить нечем — гейт не состоялся (нет делегированной программы)",
+    nameless: "не назвал подсаженный файл",
+    planting: "краснеет и на зелёном образце — падает от самой подсадки",
+    unattributed: (g) => `покраснело: ${g} — поимка не доказана`,
     blindWhere: (file, fixes) => `где: ${file} — починок в истории: ${fixes}`,
     blindWhat: "что подсадили в ваш файл:",
     blindFix: (cmd) => `поймать прямо сейчас, без комплекта:  ${cmd}`,

package/tool/i18n/ru.mjs

@@ -10,12 +10,20 @@ import { templates } from "./templates-ru.mjs";
 
 import { ruGates } from "./ru-gates.mjs";
 
+// «(коммитов с тех пор: 3)» — без склонений: число рядом со словом в родительном падеже
+// читается одинаково при любом числе.
+const ago = (n) => (n === null || n === undefined ? "" : ` (коммитов с тех пор: ${n})`);
+
 export const ru = {
   learn: {
     title: "Сказано вслух и не записано",
     noLogs: (p) => `логов этого проекта нет: ${p}\n  Команда читает переписку Claude Code на этой машине. Пусто — значит здесь не работали.`,
-    counted: (s, typed, said, fresh) =>
-      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh}`,
+    counted: (s, typed, said, fresh, again) =>
+      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh} · повторено: ${again}`,
+    ruleTitle: "Записано, а поправлять всё равно приходится:",
+    ruleHow: "Правило стоит в своде, а вы повторяете его агенту снова — текстом оно не держится. Ему нужен сторож-машина: aqk find \"…\" или aqk new <имя>.",
+    repeatTitle: "Повторено — вы говорили это не в первый раз («я же говорил», «опять», «снова»):",
+    restTitle: "Остальное, похожее на правило и не записанное:",
     nothing: "всё, что похоже на правило, уже стоит в точке входа",
     andMore: (n) => `… и ещё ${n}`,
     warn:
@@ -45,6 +53,8 @@ export const ru = {
     blob: "собрать методички в один файл GOD_AI.md",
     learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
     context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
+    vitals: "подключено ли то, чем комплект работает: инструменты гейтов, хуки, свежесть версии",
+    prompt: "одно задание для агента: что починить, по порядку, и чем доказать, что готово",
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
     report: "обязательная форма отчёта: что стоит, что нет, что не прочитано; --since <ссылка> — ещё и чем доказан диф",
     badge: "значок уровня для README — и проверка, что он не врёт",
@@ -66,6 +76,23 @@ export const ru = {
     gitignore: "гигиена репозитория",
     git: "проект под контролем версий",
 
+    runtimeTracked: (f, cmd) => `${f} отслеживается git — каждый прогон его переписывает, и в дереве вечно висит изменённый файл. Вынуть: ${cmd}`,
+    runtimeNotIgnored: (f, cmd) => `${f} — состояние этой машины, а git его видит: одно \`git add .\`, и он в коммите. Спрятать: ${cmd}`,
+    layoutAdvice: "нет — это совет, прогон не роняет",
+    coversImpossible: (entry, gate, linter) => `заявка «${gate} держит ${entry}» неверна: у ${linter} нет правила под этот класс — закрывать его нечем`,
+    coversCantCheck: (entry, gate) => `заявку «${gate} держит ${entry}» проверить не умею: линтер гейта не распознан или правил записи для него нет — принято на слово`,
+    selectUnknown: (names, groups) => `--only/--skip: не знаю «${names}» — это не гейт из gates: и не группа из groups:${groups ? ` (группы: ${groups})` : ""}. Прогон всего подряд вместо пропуска был бы неправдой, поэтому стоп.`,
+    selectSkipped: (names) => `не запускались (по --only/--skip): ${names} — их состояние неизвестно, это не «зелёные»`,
+    // Claude Code читает CLAUDE.md, а не AGENTS.md — документация Claude Code, раздел «AGENTS.md».
+    claudeShim: {
+      missing: "Claude Code здесь настроен (.claude/), а свод лежит в AGENTS.md — он его не читает. Почини: CLAUDE.md с одной строкой «@AGENTS.md».",
+      noImport: "CLAUDE.md не подключает AGENTS.md — Claude Code видит только CLAUDE.md. Почини: строка «@AGENTS.md» в CLAUDE.md (упоминание словами не загружает файл).",
+    },
+    annotDropped: (n, more) => `пометок в pull request: ${n}, ещё ${more} не показано — GitHub принимает около десяти за шаг; все находки — в логе выше`,
+    heldQuiet: (n, cmd) => `держит машина: ${n} — поимённо: ${cmd}`,
+    skipQuiet: (n, cmd) => `не применимо к этому репозиторию: ${n} — поимённо и почему: ${cmd}`,
+    passedQuiet: (n) => `прошли ещё ${n} — поимённо: --verbose`,
+    jobsBad: (v) => `--jobs ждёт целое число от 1: «${v}» не подходит. Прогон по одному под видом параллельного был бы неправдой, поэтому стоп.`,
     rulesByHuman: (total, machine, human) =>
       `правил в точке входа: ${total}. Сторож — ЧЕЛОВЕК у ${human}, машина у ${machine}.`,
     rulesByHumanWhy: "Правило со сторожем-человеком не сторожит никто в тот день, когда человек занят. Это та самая дыра, ради которой комплект и написан, — и напоминание про неё нужно человеку, а не только агенту. Считаны правила ТОЧКИ ВХОДА: обещание, живущее в любом другом файле, не проверяет вообще ничто, и комплект даже не скажет вам, что оно есть.",
@@ -87,6 +114,19 @@ export const ru = {
     toReach: (n) => `Чтобы достичь AQK-${n}:`,
     gives: (what) => `Что это даст: ${what}`,
     allDone: "Все ступени пройдены.",
+    // Чего уровень не доказывает. Ступени меряют оснащённость: гейты показаны на образцах
+    // каталога. Про файлы проекта знает только проба — строка говорит ровно то, что знает она.
+    limitsTitle: "Уровень — это оснащённость, а не надёжность. Чего он не доказывает:",
+    limitsProbe: {
+      never: (_, cmd) => `брак в ваших файлах: проба не запускалась — ${cmd}`,
+      off: () => "брак в ваших файлах: проба выключена (probe: 0) — ловят ли его проверки, неизвестно",
+      blind: ({ names, behind }) => `брак в ваших файлах: проба${ago(behind)} НЕ поймала — ${names.join(", ")}`,
+      partial: ({ caught, unknown, behind }, cmd) => `брак в ваших файлах: проба${ago(behind)} — поймано классов ${caught}, у ${unknown} поимка не доказана (${cmd})`,
+      caught: ({ caught, behind }) => `брак в ваших файлах: проба${ago(behind)} поймала все ${caught} подсаженных классов — только тех, что есть в каталоге`,
+      nothing: ({ behind }, cmd) => `брак в ваших файлах: проба${ago(behind)} ничего не подсадила — ${cmd}`,
+      old: ({ behind }, cmd) => `брак в ваших файлах: проба была${ago(behind)}, итог покажет ${cmd}`,
+    },
+    limitsCi: "конвейер: прошёл ли он, отсюда не видно — проверяется только, что гейты в нём объявлены",
 
     gatesHeading: "Гейты",
     langs: "языки",
@@ -109,7 +149,9 @@ export const ru = {
     blindRan: (g) => `гейт ${g} стоит и прогонялся — а брак в этом файле пропустил`,
     blindInstalled: "объявлено, но проба этот гейт не гоняла (поставлен позже или медленный) — поймает ли, покажет следующая",
     blindMore: (cmd) => `что именно подсадили и куда — ${cmd}`,
-    probeNever: (cmd) => `Ловят ли ваши проверки настоящий брак, ещё не проверялось: ${cmd} подсадит его в копию проекта и покажет (минута-две, рабочие файлы не трогает).`,
+    probeNever: (cmd) => `Ловят ли ваши проверки настоящий брак, ещё не проверялось: ${cmd} подсадит его в копию проекта и покажет (минута-две, файлы проекта не меняет).`,
+    todoRest: (n) => `Остальные записи, применимые у вас (${n}):`,
+    todoRestHow: (self) => `поставить любую: ${self} add <имя> · что она ловит и зачем: ${self} why <имя>`,
     startWith: "Начните с этих трёх — они родились из настоящего отказа и закрываются одной готовой командой:",
     startCmd: (cmd) => `одной строкой, без комплекта:  ${cmd}`,
     startTool: (url) => `инструмент: ${url}`,
@@ -205,12 +247,13 @@ export const ru = {
       has_docker: ["нет Dockerfile или compose", "docker уже есть"],
       has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
       has_tests: ["не видно тестов", "тесты есть"],
+      has_biome: ["линтер не Biome", "линтер проекта — Biome"],
       has_env: ["нет файла окружения", "файл окружения есть"],
       has_agent_config: ["агента здесь не настраивали", "настройки агента есть"],
       has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
       has_mcp: ["агенту здесь не подключали внешних инструментов через MCP", "MCP-серверы объявлены"],
-      has_api_spec: ["не видно спецификации API", "спецификация API есть"],
+      has_api_spec: ["не видно договора API: ни файла OpenAPI, ни tRPC, ts-rest или провайдера типов Fastify", "договор API есть: файл спецификации или схемы в коде"],
     },
   },
 
@@ -237,5 +280,45 @@ export const ru = {
     alreadyDeclared: "уже объявлен",
   },
 
+  // Задание агенту одним текстом (`aqk prompt`). У КАЖДОГО пункта хвост «Готово — …» с
+  // командой-арбитром: пункт без неё агент закроет словами «сделал» — это сторожит модульная проверка.
+  prompt: {
+    title: "# Задание: довести проверки проекта до рабочих",
+    intro: "Составлено AQK по состоянию репозитория. Выполняй пункты по порядку.",
+    rulesTitle: "## Правила",
+    rules: [
+      "Команды бери только из этого задания и из репозитория. Не выдумывай.",
+      "Сначала запусти проверку пункта и убедись, что она красная. Потом чини. Готово — когда та же команда зелёная.",
+      "Чини код, а не проверку: не ослабляй порог, не добавляй исключений, не выключай гейт. Считаешь проверку неправой — остановись и спроси владельца.",
+      "Решение, которое может принять только владелец (что ставить в проект, какие правила вводить), — спроси, а не угадывай.",
+      "Меняй только то, что нужно для этих пунктов.",
+    ],
+    tasksTitle: "## Что сделать",
+    empty: "Делать нечего: красных гейтов нет, проба ничего не нашла, ставить нечего. Всё равно выполни проверку ниже.",
+    done: "Готово —",
+    item: {
+      init: (s) => `Заведи манифест: \`${s} init\` — без него остальные команды отказывают. Готово — \`${s} doctor\` показывает уровень.`,
+      runNone: (s) => `Прогона ещё не было. Запусти \`${s} doctor --run\` и почини то, что покраснеет, по одному гейту: \`${s} doctor --run --only <имя>\`. Готово — прогон зелёный.`,
+      runStale: (s, when) => `Прогон ${when} старше последнего коммита — список красных ниже может быть про другой код. Запусти \`${s} doctor --run\` заново. Готово — у тебя свежий итог, и пункты ниже сверены с ним.`,
+      missed: ({ slug, file }, s) => `Гейт \`${slug}\` стоит, но пропустил брак, который проба подсадила в \`${file}\`. Разберись почему — частая причина: гейт не смотрит этот тип файлов или каталог; подробности даст \`${s} probe\`. Готово — \`${s} probe\` больше не называет этот класс.`,
+      red: (name, s) => `Гейт \`${name}\` красный. Запусти \`${s} doctor --run --only ${name}\`, прочитай находки и почини код. Готово — эта команда зелёная.`,
+      blind: ({ slug, file, command }, s) => `Проба подсадила брак класса \`${slug}\` в \`${file}\`, и проверки проекта его не заметили. Поставь проверку: \`${s} add ${slug}\`${command ? ` (то же одной строкой, без комплекта: \`${command}\`)` : ""}. Готово — \`${s} doctor --run --only ${slug}\` проходит, а \`${s} probe\` больше не называет этот класс.`,
+      adopt: (gates, s) => `У проекта уже есть свои проверки: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Впиши их в gates: манифеста .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Готово — \`${s} doctor --run\` их запускает.`,
+      shim: {
+        missing: (s) => `Claude Code здесь настроен, а правила лежат в AGENTS.md — он читает только CLAUDE.md. Создай CLAUDE.md с одной строкой \`@AGENTS.md\`. Готово — \`${s} doctor\` об этом больше не предупреждает.`,
+        noImport: (s) => `CLAUDE.md не подключает AGENTS.md — Claude Code видит только CLAUDE.md. Добавь в CLAUDE.md строку \`@AGENTS.md\` (упоминание словами файл не загружает). Готово — \`${s} doctor\` об этом больше не предупреждает.`,
+      },
+      // Запись каталога — предложение, а не факт о проекте: ставить или нет, решает владелец.
+      // Красный гейт и брак из пробы — факты, там «почини»; здесь — «предложи».
+      start: ({ slug, intent, command }, s) => `Предложи владельцу проверку \`${slug}\`${intent ? ` — ${intent}` : ""}. Согласен — \`${s} add ${slug}\`${command ? ` (то же одной строкой, без комплекта: \`${command}\`)` : ""}. Краснеет на существующем коде — не глуши её, покажи находки владельцу. Готово — \`${s} doctor --run --only ${slug}\` проходит, а \`${s} prove\` показывает её доказанной.`,
+    },
+    more: (n, s) => `И ещё ${n} — полный список: \`${s} doctor\`. Сначала закончи эти.`,
+    verifyTitle: "## Как проверить, что готово",
+    verify: (s) => [
+      `\`${s} doctor --run\` — прогон зелёный.`,
+      `\`${s} prove\` — ни один гейт не сломан: каждый краснеет на своём красном образце.`,
+      "В отчёте назови эти команды и их итог. «Выглядит рабочим» — не готово.",
+    ],
+  },
   ...ruGates,
 };

package/tool/lib/adopt.mjs

@@ -95,4 +95,18 @@ function proposeGates(files = {}) {
 const ADOPT_FILES = ["package.json", "Makefile", ".pre-commit-config.yaml", "tox.ini", "pyproject.toml"];
 const ADOPT_SCRIPTS = ["scripts/test", "scripts/check", "scripts/lint"];
 
-export { proposeGates, ADOPT_FILES, ADOPT_SCRIPTS };
+// Чтение с диска — отдельно от разбора: разбор проверяется перебором случаев, чтение — прогоном.
+async function readAdoptFiles(cwd) {
+  const { readFile, access } = await import("node:fs/promises");
+  const { join } = await import("node:path");
+  const files = {};
+  for (const n of ADOPT_FILES) {
+    try { files[n] = await readFile(join(cwd, n), "utf8"); } catch { /* нет — и ладно */ }
+  }
+  for (const n of ADOPT_SCRIPTS) {
+    try { await access(join(cwd, n)); files[n] = ""; } catch { /* нет — и ладно */ }
+  }
+  return files;
+}
+
+export { proposeGates, readAdoptFiles };

package/tool/lib/advice.mjs

@@ -0,0 +1,115 @@
+// tool/lib/advice.mjs — ЧТО СОВЕТОВАТЬ ПРОЕКТУ: какие записи каталога его касаются, с каких
+// начать и какой командой закрыть класс брака прямо сейчас, без комплекта.
+//
+// ОТДЕЛЬНЫМ ФАЙЛОМ, а не в repo.mjs: там осмотр репозитория (факты, триггеры, рецепты), здесь —
+// решение, что из этого сказать человеку и агенту. Одно знание на `doctor`, `probe` и блок для
+// агента: жило в двух файлах и росло в обоих; шов вскрыл наш же file-size-limit — repo.mjs
+// дорос до 494 строк при пределе 500.
+import { triggerVerdict } from "./repo.mjs";
+
+// Корзины каталога для ЭТОГО проекта: держит · к установке · закрыто другим арбитром ·
+// неприменимо. Одна раскладка на `doctor` и на блок для агента: жила внутри `doctor`, и блоку
+// пришлось бы завести вторую — а два счёта одного и того же расходятся первыми.
+function catalogBuckets(catalog, facts, covered = new Map()) {
+  const held = [], todo = [], skip = [], byOther = [];
+  for (const rec of catalog) {
+    const v = triggerVerdict(rec, facts);
+    if (!v.applies) skip.push([rec, v.why]);
+    else if (facts.gateKeys.includes(rec.slug)) held.push(rec);
+    else if (covered.has(rec.slug)) byOther.push([rec, covered.get(rec.slug)]);
+    else todo.push(rec);
+  }
+  return { held, todo, skip, byOther };
+}
+
+// С ЧЕГО НАЧАТЬ: три записи вместо двадцати равнозначных крестов.
+//
+// Двадцать одинаковых требований — это ноль требований: закрывают первое попавшееся или не
+// закрывают ничего. Порядок НЕ по нашему вкусу; два признака, оба — факты, которые у нас уже
+// есть:
+//   · запись родилась из настоящего отказа (`lifecycle: stable` — `proof` ссылается на журнал
+//     шишек), то есть она про боль, которая СЛУЧАЛАСЬ, а не про «хорошую практику»;
+//   · её можно закрыть одной готовой командой — цена входа минутная.
+// Сначала то, что и больно, и дёшево.
+//
+// При равенстве признаков — по имени: одинаковый ввод обязан давать одинаковый ответ, иначе
+// человек видит разный совет на двух прогонах подряд и перестаёт верить обоим.
+function startWith(entries, facts, n = 3) {
+  const langs = facts?.langs ? [...facts.langs] : [];
+  const cheap = (e) => {
+    const r = e?.recipes && typeof e.recipes === "object" ? e.recipes : {};
+    return [...langs, "native"].some((k) => r[k] && !/\{gate\}/.test(r[k])) ? 1 : 0;
+  };
+  // Зрелость НЕ поле записи, а вычисляемый признак: `proof` ссылается на журнал шишек. Тот же
+  // признак, которым каталог отделяет условную запись с первого дня (`entryLifecycle`).
+  // Заводить второй счёт нельзя: разъехавшись, они дали бы разные ответы про одну запись.
+  const hurt = (e) => (/incidents\//.test(String(e?.proof || "")) ? 1 : 0);
+  return [...entries]
+    .sort((a, b) =>
+      (hurt(b) + cheap(b)) - (hurt(a) + cheap(a)) ||
+      cheap(b) - cheap(a) ||
+      String(a.slug).localeCompare(String(b.slug)))
+    .slice(0, n);
+}
+
+// Адрес Biome сверен по реестру github 2026-09-11.
+const BIOME_URL = "https://github.com/biomejs/biome";
+
+// Совет по НЕПОКРЫТОМУ классу: команда, которую можно вставить прямо сейчас.
+//
+// Проба находит настоящие дыры и печатала про них «close it: aqk add <имя>» — то есть «поставь
+// нашу штуку». Человек, впервые увидевший комплект, закрывает окно. А готовая однострочная
+// команда под его стек У НАС УЖЕ ЛЕЖИТ в `recipes` записи каталога; мы её не показывали.
+//
+// Замер руками на `requests` (самый скачиваемый python-пакет) 2026-09-10: в
+// `src/requests/utils.py` — 75 коммитов-починок; дописана функция с `except Exception: pass`;
+// их собственные `ruff` и `pytest` дали 0 и на чистой копии, и на подсаженной. Строка, которая
+// поймала бы это, лежала в нашем каталоге всё это время.
+//
+// Переносимый рецепт (`any`) в совет НЕ идёт: он зовёт файл из комплекта, и человеку без
+// комплекта вставить его некуда. Нет родного рецепта под стек — команды нет, и это честнее
+// выдуманной.
+function blindAdvice(entry, facts, hot = {}) {
+  const recipes = entry?.recipes && typeof entry.recipes === "object" ? entry.recipes : {};
+  // `langs` приходит МНОЖЕСТВОМ, а не массивом — `Array.isArray` тихо давал пустой список, и
+  // совет не печатался вовсе. Поймано на живом `requests`: langs = Set(1) { python }.
+  const langs = facts?.langs ? [...facts.langs] : [];
+  // Тот же порядок, что у `pickRecipe`: свой язык → безъязыковой родной → ничего. Переносимый
+  // (`any`) сюда не идёт никогда: он зовёт файл из комплекта, и человеку без комплекта вставить
+  // его некуда.
+  // Проект на Biome — совет на языке Biome, а не eslint (отзыв с живого проекта 2026-09-11:
+  // «начни с трёх» советовал завести eslint проекту на Biome). Одно правило разово через `--only`;
+  // `--error-on-warnings` обязателен — правило вне рекомендованных Biome ставит на
+  // «предупреждение», и без флага команда выходила с нулём, напечатав находку (Biome 2.5.12).
+  const br = typeof entry?.biome_rules === "string" ? entry.biome_rules.trim() : "";
+  if (facts?.has_biome && br && br !== "none" && langs.some((l) => l === "javascript" || l === "typescript")) {
+    const only = br.split(",").map((x) => x.trim()).filter(Boolean).map((r) => `--only=${r}`).join(" ");
+    return { command: `npx @biomejs/biome lint --error-on-warnings ${only} .`, tool: BIOME_URL,
+      file: hot.file ?? null, fixes: hot.fixes ?? null, slug: entry?.slug ?? null };
+  }
+  let cmd = null;
+  for (const key of [...langs, "native"]) {
+    const r = recipes[key];
+    if (!r || /\{gate\}/.test(r)) continue;
+    cmd = String(r).replace(/\{dir\}/g, ".")
+      // Вычистить то, что относится к НАМ, а не к его проекту. Исключение наших красных
+      // образцов нужно УСТАНОВЛЕННОМУ гейту — рядом с ним лежат образцы. Человеку, который
+      // команду только копирует, этих каталогов не существует, и флаги про них подрывают
+      // доверие: инструмент говорит про чужое хозяйство вместо его кода.
+      .replace(/\s--ignore-pattern\s+'[^']*gates\/[^']*'/g, "")
+      .replace(/\s--ignore-paths=?\s*'[^']*gates\/[^']*'/g, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    break;
+  }
+  // Адрес — того инструмента, которым команда начинается: поле `tool` общее на все языки, и
+  // python-проекту показывалась ссылка на eslint. Первые три слова, а не одно: `npx knip`,
+  // `python -m vulture`. Не совпало — весь список: лишняя ссылка лучше, чем ни одной.
+  const urls = entry?.tool ? String(entry.tool).split(/\s+·\s+/) : [];
+  const head = cmd ? cmd.split(" ").slice(0, 3) : [];
+  const own = urls.find((u) => head.includes(u.replace(/\/+$/, "").split("/").pop()));
+  const tool = own ?? (entry?.tool ? String(entry.tool) : null);
+  return { command: cmd, tool, file: hot.file ?? null, fixes: hot.fixes ?? null, slug: entry?.slug ?? null };
+}
+
+export { catalogBuckets, startWith, blindAdvice };