agent-quality-kit 0.5.0 → 0.7.0

package/tool/i18n/en.mjs

@@ -3,9 +3,12 @@
 // Правка здесь обязана иметь пару в ru.mjs с тем же ключом: расхождение ловит модульная
 // проверка «оба каталога несут одни и те же ключи».
 
+import { enDocs } from "./en-docs.mjs";
+
 import { templates } from "./templates-en.mjs";
 
 export const en = {
+  ...enDocs,
   templates,
   help: {
     tagline: "tooling for building software with agents",
@@ -13,8 +16,10 @@ export const en = {
     init: "lay the rules and guides into the current project",
     initForce: "overwrite files that already exist",
     start: "no code yet: day-zero guards and the order of work",
+    prove: "prove the gates catch a defect: each against its own red and green sample",
     doctor: "check what is laid out and what is missing",
     doctorRun: "and also run the declared gates",
+    doctorSince: "the same, but show only what the diff against a ref introduced",
     add: "install a gate from the catalogue into the project",
     find: "is there already such a gate — matched by intent",
     why: "a bug slipped through — why did no guard catch it",
@@ -40,6 +45,8 @@ export const en = {
     emptyCommands: (n) => `AGENTS.md has ${n} unfilled commands.`,
     emptyCommandsWhy: "An agent cannot execute an empty line.",
 
+    levelUnproven: (cmd) => `not proven: ${cmd}`,
+    gatesDoNotCatch: (n, cmd) => `gates that do not catch a defect: ${n}. Details: ${cmd}`,
     levelHeading: "AQK compliance level",
     levelNone: "none",
     levelNotSet: "Level: the standard is not set up in this repository.",
@@ -66,6 +73,14 @@ export const en = {
     totalTodo: (n) => `applicable but not installed ${n}`,
     totalSkip: (n) => `hidden ${n}`,
 
+    sinceHeading: (ref, n) => `narrowed to the diff against ${ref}: ${n} files touched`,
+    sinceBadRef: (ref) => `cannot compare against "${ref}": no such ref, or this is not a git repository`,
+    notScopable: "output carries no paths — cannot be narrowed by diff, left red",
+    outsideDiff: (n) => `findings exist, but outside the diff (${n})`,
+    advisoryMark: "advisory — shown, the run was not failed",
+    advisorySummary: (names) =>
+      `advisory and red: ${names.join(", ")}. These are switched-off checks: ` +
+      `either fix them and drop them from advisory, or admit the rule does not exist.`,
     runHeading: "Running the declared gates",
     timeout: "did not finish within 5 minutes",
     exitCode: (code) => `exit ${code}`,
@@ -127,6 +142,8 @@ export const en = {
       has_deps: ["no dependency file in sight", "dependencies are declared"],
       has_tests: ["no tests in sight", "tests exist"],
       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"],
     },
   },
@@ -136,6 +153,18 @@ export const en = {
     none: "no recipe described",
   },
 
+  // Entry maturity. Computed from the entry's proof; it cannot be declared — see
+  // entryLifecycle in tool/lib/manifest.mjs.
+  lifecycle: {
+    stable: "proven by an incident from the journal",
+    experimental: "proof is not from the journal — the entry is provisional",
+    deprecated: "retired",
+    unknownReplacement: (v) => `superseded_by: ${v} — no such entry in the catalogue`,
+    noReplacement: "lifecycle: deprecated without superseded_by — no replacement is named",
+    notDeclarable: (v) => `lifecycle: ${v} cannot be declared — maturity is computed from the proof`,
+    unknown: (v) => `lifecycle: ${v} — no such state; only deprecated is declared`,
+    installDeprecated: (slug, by) => `entry ${slug} is retired, ${by} replaces it`,
+  },
   manifest: {
     noGatesBlock: "no gates: block in .aqk.yml",
     alreadyDeclared: "already declared",
@@ -143,7 +172,13 @@ export const en = {
 
   add: {
     noSuchGate: (slug, cmd) => `No such gate: ${slug}\nThe applicable ones — ${cmd}`,
-    noRecipe: (slug, stack) => `Entry ${slug} has no command for ${stack} and no portable one.`,
+    toolMissing: (slug, missing) =>
+      `Entry ${slug} needs ${missing.join(" and ")}, which is not on this machine.\n  fix: install ${missing.join(" and ")} and try again — this entry delegates to a ready-made tool by design and has no check of its own.`,
+    noRecipe: (slug, stack, missing) =>
+      `Entry ${slug} has no command for ${stack} and no portable one.` +
+      (Array.isArray(missing) && missing.length
+        ? `\n  fix: install ${missing.join(" or ")} and try again — this entry delegates to a ready-made tool by design and has no check of its own.`
+        : `\n  fix: add a recipe for your stack to this entry's gate.yml, or pick another entry.`),
     thisStack: "this stack",
     needName: (cmd, doctor) => `Name the gate: ${cmd}. The list — ${doctor}`,
     noManifest: (cmd) => `No .aqk.yml — run ${cmd} first`,
@@ -196,7 +231,14 @@ export const en = {
     registryHead: (slug, stamp) =>
       `# Debt registry: ${slug}\n` +
       `# Captured ${stamp}. This list may ONLY get shorter.\n` +
-      `# A new violation turns the gate red; a fixed one is struck out automatically.\n`,
+      `# A new violation turns the gate red; a fixed one is struck out automatically.\n` +
+      `#\n` +
+      `# Debt with no goal and no deadline never ends. The goal is how many violations count as\n` +
+      `# paid off; on reaching it the ratchet tells you to remove the wrapper. The deadline is\n` +
+      `# optional, but if set, debt still open past that date turns the gate red — a deadline\n` +
+      `# without a consequence is not a deadline.\n` +
+      `# aqk-goal: 0\n` +
+      `# aqk-deadline:\n`,
     recorded: (n) => `${n} violations recorded as debt`,
     libCopied: "wrapper copied into the project",
     wrapped: "command wrapped in the ratchet",
@@ -278,6 +320,8 @@ export const en = {
 
   init: {
     noDocs: (dir) => `Guides not found: ${dir}\nLooks like the package is not fully installed.`,
+    docsRu:
+      "the guides in .aqk/docs/ are in Russian — a deliberate decision, not a broken install.\n  The rules in .aqk/rules/ are in English; the guides are prose an agent may ignore anyway,\n  and what a machine holds lives in .aqk.yml and the gates. Translation waits for someone who needs it.",
     created: (n) => `created (${n}):`,
     andMore: (n) => `… and ${n} more`,
     kept: (n) => `already there, left untouched (${n}):`,
@@ -369,31 +413,27 @@ export const en = {
     nextWhy: "— run everything that is declared",
   },
 
-  manifestDoc: {
-    head: [
-      "# .aqk.yml — the Agent Quality Kit manifest",
-      "# What this is: a machine-readable description of how agents live in this repository.",
-      "# `aqk doctor` computes the compliance level. An empty field = the level is not reached,",
-      "# and that is honest: filling it with placeholders is pointless, files are checked, not words.",
-    ],
-    entry: "# AQK-0 — what the agent reads first.",
-    rules: "# AQK-1 — where the standards are and which checks are mandatory.",
-    gates: [
-      "  # name: a command returning 0 or non-zero. An empty declaration protects nothing and is",
-      '  # rejected by the "a declared gate runs" check — hence examples here, not placeholders.',
-      '  #   lint: "ruff check ."',
-      '  #   test: "pytest -q"',
-      "  # To install a ready entry from the catalogue together with its samples: aqk add <name>",
-    ],
-    samples: [
-      "# AQK-2 — what proves the gates work, and where the debt registries are.",
-      "# samples: the directory with red and green samples (a gate must go red on the first and",
-      "# stay quiet on the second). ratchets: lists of known violations that may only get",
-      "# shorter.",
-    ],
-    lessons: "# AQK-3 — where lessons accumulate. A path or an address.",
-  },
 
+  prove: {
+    title: "aqk prove — proving the gates",
+    running: "proving the gates against their samples…",
+    proven: (n) => `proven: ${n}`,
+    broken: (n) => `do not catch: ${n}`,
+    unprovable: (n) => `nothing to prove with: ${n}`,
+    okRed: "red on the red sample, silent on the green one",
+    redPassed: "stayed silent on the RED sample — the gate does not catch the defect",
+    greenFailed: "went red on the GREEN sample — the gate complains about working code",
+    empty: "the command is empty — a declaration without a command protects nothing",
+    noSamples: "no samples — nothing to prove with",
+    noTarget: "no place to substitute the sample directory — the command was written by hand",
+    otherRecipe: (lang) => `the samples are written for the "${lang}" recipe, another one is installed — nothing to prove with`,
+    noGates: "no gates declared — nothing to prove",
+    noSamplesDir: "the samples field in .aqk.yml is empty — nowhere to look for samples",
+    nothingProven:
+      "not a single gate is proven. A level above AQK-1 would mean trust in the author, not a fact:\n  a project whose gate is `true` would pass it exactly like a project with real protection.",
+    fix: (cmd) => `fix: install a catalogue entry together with its samples — ${cmd}`,
+    heading: "Proving the gates",
+  },
   badge: {
     noManifest: (cmd) => `No .aqk.yml — there is no level yet. Start with ${cmd}`,
     notReached: (cmd) => `AQK-0 is not reached — there is nothing to put on a badge. What is missing: ${cmd}`,
@@ -442,33 +482,5 @@ export const en = {
     },
   },
 
-  levels: [
-    {
-      title: "a manifest and an entry point",
-      need: "create .aqk.yml and point entry at the file an agent reads first (AGENTS.md)",
-      gives: "any tool understands what to read in this repository",
-    },
-    {
-      title: "rules and working gates",
-      need: "set rules (the standards directory) and fill at least one gate in gates with a real command",
-      gives: "checks are declared as commands, not described in prose",
-    },
-    {
-      title: "gates are proven, debt is under a ratchet",
-      need: "set samples (red and green gate samples) and ratchets (debt registries)",
-      gives: "the gate has proven it catches defects and stays quiet on correct code",
-    },
-    {
-      title: "lessons come back into the work",
-      need: "set lessons — the path or address of a journal where every incident yields a conclusion",
-      gives: "the project learns: the same bruise is not collected twice",
-    },
-  ],
 
-  report: {
-    title: "aqk doctor --run",
-    version: "version",
-    level: "level",
-    summary: (ok, all) => `total: ${ok} of ${all} green`,
-  },
 };

package/tool/i18n/ru-docs.mjs

@@ -0,0 +1,70 @@
+// tool/i18n/ru-docs.mjs — тексты, которые уходят В ФАЙЛ, а не в терминал.
+//
+// ЗАЧЕМ ОТДЕЛЬНО. Каталог строк перерос собственный предел в 500 строк — его поймал наш же
+// гейт file-size-limit. Шов выбран по смыслу, а не пополам: здесь то, что программа ПИШЕТ
+// (комментарии в .aqk.yml, названия ступеней, форма отчёта), а в ru.mjs — то, что она ГОВОРИТ.
+// У этих текстов разная жизнь: первые читает человек в своём репозитории месяцы спустя,
+// вторые — он же в терминале, одну секунду.
+
+const ruDocs = {
+  manifestDoc: {
+    head: [
+      "# .aqk.yml — манифест Agent Quality Kit",
+      "# Что это: машиночитаемое описание того, как в этом репозитории живут агенты.",
+      "# Уровень соответствия считает `aqk doctor`. Пустое поле = ступень не пройдена,",
+      "# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.",
+    ],
+    entry: "# AQK-0 — что агент читает первым.",
+    rules: "# AQK-1 — где стандарты и какие проверки обязательны.",
+    gates: [
+      "  # Имя: команда, возвращающая 0 или не 0. Пустое объявление защиты не даёт и бракуется",
+      "  # проверкой «объявленный гейт запускается» — поэтому здесь примеры, а не заготовки.",
+      '  #   lint: "ruff check ."',
+      '  #   test: "pytest -q"',
+      "  # Поставить готовую запись из каталога вместе с образцами: aqk add <имя>",
+    ],
+    samples: [
+      "# AQK-2 — чем доказано, что гейты работают, и где реестры долга.",
+      "# samples: каталог с красными и зелёными образцами (гейт обязан краснеть на первом",
+      "# и молчать на втором). ratchets: списки известных нарушений, которые могут только",
+      "# укорачиваться.",
+    ],
+    lessons: "# AQK-3 — где копятся уроки. Путь или адрес.",
+    advisory: [
+      "# Совещательные гейты: показывают находки, но не роняют прогон. Третий способ ввести",
+      "# правило — рядом с храповиком и с большой чисткой. Список называется в каждом прогоне:",
+      "# совещательный гейт, о котором забыли, — это выключенная проверка.",
+      "# advisory:",
+      "#   - complexity-limit",
+    ],
+  },
+  levels: [
+    {
+      title: "манифест и точка входа",
+      need: "создай .aqk.yml и укажи в entry файл, который агент читает первым (AGENTS.md)",
+      gives: "любой инструмент понимает, что читать в этом репозитории",
+    },
+    {
+      title: "правила и работающие гейты",
+      need: "укажи rules (каталог стандартов) и заполни хотя бы один гейт в gates реальной командой",
+      gives: "проверки объявлены командами, а не описаны словами",
+    },
+    {
+      title: "гейты доказаны, долг под храповиком",
+      need: "заведи samples (красные и зелёные образцы гейтов) и ratchets (реестры долга)",
+      gives: "гейт доказал, что ловит брак и молчит на исправном коде",
+    },
+    {
+      title: "уроки возвращаются в работу",
+      need: "укажи lessons — путь или адрес журнала, где каждый инцидент даёт вывод",
+      gives: "проект учится: одна и та же шишка не набивается дважды",
+    },
+  ],
+  report: {
+    title: "aqk doctor --run",
+    version: "версия",
+    level: "уровень",
+    summary: (ok, all) => `итого: ${ok} из ${all} зелёных`,
+  },
+};
+export { ruDocs };

package/tool/i18n/ru.mjs

@@ -4,9 +4,12 @@
 // проверка «оба каталога несут одни и те же ключи». Иначе один язык молча отстаёт, а
 // обещание «два языка» превращается в слова.
 
+import { ruDocs } from "./ru-docs.mjs";
+
 import { templates } from "./templates-ru.mjs";
 
 export const ru = {
+  ...ruDocs,
   templates,
   help: {
     tagline: "оснастка для разработки с агентами",
@@ -14,8 +17,10 @@ export const ru = {
     init: "разложить правила и методички в текущий проект",
     initForce: "перезаписать уже существующие файлы",
     start: "кода ещё нет: сторожа дня 0 и порядок работы",
+    prove: "доказать, что гейты ловят брак: каждый по своему красному и зелёному образцу",
     doctor: "проверить, что разложено и чего не хватает",
     doctorRun: "ещё и запустить объявленные гейты",
+    doctorSince: "то же, но показать только то, что внёс диф относительно ссылки",
     add: "поставить гейт из каталога в проект",
     find: "есть ли уже такой гейт — сверка по намерению",
     why: "поймал ошибку — почему её не поймал сторож",
@@ -41,6 +46,8 @@ export const ru = {
     emptyCommands: (n) => `В AGENTS.md ${n} незаполненных команд.`,
     emptyCommandsWhy: "Агент не может выполнить пустую строку.",
 
+    levelUnproven: (cmd) => `не доказано: ${cmd}`,
+    gatesDoNotCatch: (n, cmd) => `гейтов, не ловящих брак: ${n}. Подробности: ${cmd}`,
     levelHeading: "Уровень соответствия AQK",
     levelNone: "нет",
     levelNotSet: "Уровень: стандарт в этом репозитории не заведён.",
@@ -67,6 +74,14 @@ export const ru = {
     totalTodo: (n) => `применимо но не поставлено ${n}`,
     totalSkip: (n) => `скрыто ${n}`,
 
+    sinceHeading: (ref, n) => `сужено до дифа относительно ${ref}: файлов затронуто ${n}`,
+    sinceBadRef: (ref) => `не могу сравнить с «${ref}»: такой ссылки нет или это не репозиторий git`,
+    notScopable: "вывод без путей — дифом не сужается, оставлен красным",
+    outsideDiff: (n) => `находки есть, но вне дифа (${n})`,
+    advisoryMark: "совещательный — показано, прогон не уронен",
+    advisorySummary: (names) =>
+      `совещательные и красные: ${names.join(", ")}. Это выключенные проверки: ` +
+      `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
     exitCode: (code) => `код ${code}`,
@@ -133,6 +148,8 @@ export const ru = {
       has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
       has_tests: ["не видно тестов", "тесты есть"],
       has_env: ["нет файла окружения", "файл окружения есть"],
+      has_agent_config: ["агента здесь не настраивали", "настройки агента есть"],
+      has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
     },
   },
@@ -142,6 +159,19 @@ export const ru = {
     none: "рецепт не описан",
   },
 
+  // Зрелость записи каталога. Считается по доказательству; объявить её нельзя — см.
+  // entryLifecycle в tool/lib/manifest.mjs.
+  lifecycle: {
+    stable: "доказана шишкой из журнала",
+    experimental: "доказательство не из журнала — запись условная",
+    deprecated: "выведена из употребления",
+    unknownReplacement: (v) => `superseded_by: ${v} — такой записи в каталоге нет`,
+    noReplacement: "lifecycle: deprecated без superseded_by — не назван тот, кто заменяет",
+    notDeclarable: (v) => `lifecycle: ${v} объявлять нельзя — зрелость считается по доказательству`,
+    unknown: (v) => `lifecycle: ${v} — такого состояния нет; объявляется только deprecated`,
+    installDeprecated: (slug, by) =>
+      `запись ${slug} выведена из употребления, её заменяет ${by}`,
+  },
   manifest: {
     noGatesBlock: "в .aqk.yml нет блока gates:",
     alreadyDeclared: "уже объявлен",
@@ -149,7 +179,13 @@ export const ru = {
 
   add: {
     noSuchGate: (slug, cmd) => `Нет такого гейта: ${slug}\nСписок применимых — ${cmd}`,
-    noRecipe: (slug, stack) => `У записи ${slug} нет команды ни под ${stack}, ни общей.`,
+    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}`,
@@ -202,7 +238,13 @@ export const ru = {
     registryHead: (slug, stamp) =>
       `# Реестр долга: ${slug}\n` +
       `# Снят ${stamp}. Список разрешается ТОЛЬКО укорачивать.\n` +
-      `# Новое нарушение красит гейт; исправленное вычёркивается автоматически.\n`,
+      `# Новое нарушение красит гейт; исправленное вычёркивается автоматически.\n` +
+      `#\n` +
+      `# Долг без цели и срока не кончается. Цель — сколько нарушений считать погашенным долгом;\n` +
+      `# по достижении храповик скажет убрать обёртку. Срок необязателен, но если он есть,\n` +
+      `# после этой даты непогашенный долг красит гейт — срок без последствия не срок.\n` +
+      `# aqk-goal: 0\n` +
+      `# aqk-deadline:\n`,
     recorded: (n) => `${n} нарушений записано долгом`,
     libCopied: "обёртка скопирована в проект",
     wrapped: "команда завёрнута в храповик",
@@ -284,6 +326,8 @@ export const ru = {
 
   init: {
     noDocs: (dir) => `Не найден корпус методичек: ${dir}\nПохоже, пакет установлен не полностью.`,
+    docsRu:
+      "методички в .aqk/docs/ остаются на русском — решение, а не недоделка.",
     created: (n) => `создано (${n}):`,
     andMore: (n) => `… и ещё ${n}`,
     kept: (n) => `уже были на месте, не тронуты (${n}):`,
@@ -375,31 +419,27 @@ export const ru = {
     nextWhy: "— прогнать всё, что объявлено",
   },
 
-  manifestDoc: {
-    head: [
-      "# .aqk.yml — манифест Agent Quality Kit",
-      "# Что это: машиночитаемое описание того, как в этом репозитории живут агенты.",
-      "# Уровень соответствия считает `aqk doctor`. Пустое поле = ступень не пройдена,",
-      "# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.",
-    ],
-    entry: "# AQK-0 — что агент читает первым.",
-    rules: "# AQK-1 — где стандарты и какие проверки обязательны.",
-    gates: [
-      "  # Имя: команда, возвращающая 0 или не 0. Пустое объявление защиты не даёт и бракуется",
-      "  # проверкой «объявленный гейт запускается» — поэтому здесь примеры, а не заготовки.",
-      '  #   lint: "ruff check ."',
-      '  #   test: "pytest -q"',
-      "  # Поставить готовую запись из каталога вместе с образцами: aqk add <имя>",
-    ],
-    samples: [
-      "# AQK-2 — чем доказано, что гейты работают, и где реестры долга.",
-      "# samples: каталог с красными и зелёными образцами (гейт обязан краснеть на первом",
-      "# и молчать на втором). ratchets: списки известных нарушений, которые могут только",
-      "# укорачиваться.",
-    ],
-    lessons: "# AQK-3 — где копятся уроки. Путь или адрес.",
-  },
 
+  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}`,
@@ -448,33 +488,5 @@ export const ru = {
     },
   },
 
-  levels: [
-    {
-      title: "манифест и точка входа",
-      need: "создай .aqk.yml и укажи в entry файл, который агент читает первым (AGENTS.md)",
-      gives: "любой инструмент понимает, что читать в этом репозитории",
-    },
-    {
-      title: "правила и работающие гейты",
-      need: "укажи rules (каталог стандартов) и заполни хотя бы один гейт в gates реальной командой",
-      gives: "проверки объявлены командами, а не описаны словами",
-    },
-    {
-      title: "гейты доказаны, долг под храповиком",
-      need: "заведи samples (красные и зелёные образцы гейтов) и ratchets (реестры долга)",
-      gives: "гейт доказал, что ловит брак и молчит на исправном коде",
-    },
-    {
-      title: "уроки возвращаются в работу",
-      need: "укажи lessons — путь или адрес журнала, где каждый инцидент даёт вывод",
-      gives: "проект учится: одна и та же шишка не набивается дважды",
-    },
-  ],
 
-  report: {
-    title: "aqk doctor --run",
-    version: "версия",
-    level: "уровень",
-    summary: (ok, all) => `итого: ${ok} из ${all} зелёных`,
-  },
 };

package/tool/i18n/templates-en.mjs

@@ -11,17 +11,17 @@ const AGENTS_MD = `# AGENTS.md
 
 ## Hard rules
 
-- **A plan before code.** A non-trivial task starts with a plan a human approved in words.
-- **A red test before code.** First a check that fails, then the implementation.
-- **Three attempts maximum.** Not solved in three — stop and ask a human, not a fourth try.
-- **Secrets only in the environment.** Never in code, logs or commits.
-- **Only the files the task is about.** No fixing things "while we are here".
-- **Done = proven.** Name the arbiter: a test, a live run, a check against the source.
+- **A plan before code.** A non-trivial task starts with a plan a human approved in words.  <!-- aqk: human -->
+- **A red test before code.** First a check that fails, then the implementation.  <!-- aqk: human -->
+- **Three attempts maximum.** Not solved in three — stop and ask a human, not a fourth try.  <!-- aqk: human -->
+- **Secrets only in the environment.** Never in code, logs or commits.  <!-- aqk: secrets-not-in-code -->
+- **Only the files the task is about.** No fixing things "while we are here".  <!-- aqk: human -->
+- **Done = proven.** Name the arbiter: a test, a live run, a check against the source.  <!-- aqk: human -->
   "Looks like it works" is not done.
-- **Never swallow an error.** Either handled and logged, or re-raised.
-- **A fork in the road is a question for a human.** Departing from an agreed decision is not
+- **Never swallow an error.** Either handled and logged, or re-raised.  <!-- aqk: human -->
+- **A fork in the road is a question for a human.** Departing from an agreed decision is not  <!-- aqk: human -->
   documented with a code comment.
-- **Report on your work with the kit with a command, not with words.** When you are done, run
+- **Report on your work with the kit with a command, not with words.** When you are done, run  <!-- aqk: human -->
   \`aqk report\`. It is assembled from an actual run: a summary from memory always picks the
   convenient parts and stays quiet about a gate standing on the weakest recipe.
 

package/tool/i18n/templates-ru.mjs

@@ -16,17 +16,17 @@ const AGENTS_MD = `# AGENTS.md
 
 ## Железные правила
 
-- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.
-- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.
-- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.
-- **Секреты только в окружении.** Никогда в коде, логах и коммитах.
-- **Только файлы из задачи.** Заодно ничего не чиним.
-- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит
+- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.  <!-- aqk: человек -->
+- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.  <!-- aqk: человек -->
+- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.  <!-- aqk: человек -->
+- **Секреты только в окружении.** Никогда в коде, логах и коммитах.  <!-- aqk: secrets-not-in-code -->
+- **Только файлы из задачи.** Заодно ничего не чиним.  <!-- aqk: человек -->
+- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит  <!-- aqk: человек -->
   рабочим» — не готово.
-- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.
-- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием
+- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.  <!-- aqk: человек -->
+- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием  <!-- aqk: человек -->
   в коде.
-- **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.
+- **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.  <!-- aqk: человек -->
   Он собирается прогоном: пересказ по памяти всегда выбирает удобное и молчит о том, что гейт
   стоит на слабейшем рецепте.
 

package/tool/lib/core.mjs

@@ -4,6 +4,7 @@
 // пределе в 500. Разделена по назначению, а не пополам — так требует наше же правило про
 // размер файла. Зависимостей по-прежнему нет ни одной: только встроенные модули Node.
 
+import { LANG } from "../i18n/index.mjs";
 import { access, readdir, mkdir, copyFile, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -17,7 +18,12 @@ const PKG_ROOT = resolve(HERE, "..", "..");
 const CWD = process.cwd();
 
 const DOCS_SRC = join(PKG_ROOT, "kit", "docs");
-const RULES_SRC = join(PKG_ROOT, "kit", "rules");
+// Правила переносятся в проект НА ЯЗЫКЕ ВЫВОДА. Русский текст в англоязычном проекте — не
+// мелочь: это первое, что там откроет человек, и первое, чего он не прочитает. Русская версия
+// остаётся источником истины, английская — переводом; расходиться им нельзя, и совпадение
+// НАБОРА ФАЙЛОВ сторожит модульная проверка. Совпадение содержания машина не сторожит — это
+// названо в AGENTS.md, а не спрятано.
+const RULES_SRC = join(PKG_ROOT, "kit", LANG === "en" ? "rules-en" : "rules");
 const TARGET_DIR = ".aqk";
 
 const c = {