agent-quality-kit 0.6.0 → 0.7.0

package/tool/i18n/en-docs.mjs

@@ -0,0 +1,70 @@
+// tool/i18n/en-docs.mjs — text that ends up IN A FILE, not in the terminal.
+//
+// WHY SEPARATE. The string catalogue outgrew its own 500-line limit — caught by our own
+// file-size-limit gate. The seam follows meaning rather than the midpoint: here is what the
+// program WRITES (comments in .aqk.yml, level names, the report form), and in en.mjs what it
+// SAYS. These texts live differently: the first is read months later in someone's repository,
+// the second for one second in a terminal.
+
+const enDocs = {
+  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.",
+    advisory: [
+      "# Advisory gates: they show findings but do not fail the run. The third way to introduce",
+      "# a rule, next to the ratchet and the big clean-up. The list is named on every run:",
+      "# an advisory gate everyone forgot about is a switched-off check.",
+      "# advisory:",
+      "#   - complexity-limit",
+    ],
+  },
+  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`,
+  },
+};
+export { enDocs };

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,6 +16,7 @@ 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",
@@ -41,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.",
@@ -71,6 +77,10 @@ export const en = {
     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}`,
@@ -132,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"],
     },
   },
@@ -160,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`,
@@ -213,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",
@@ -295,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}):`,
@@ -386,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}`,
@@ -459,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,6 +17,7 @@ export const ru = {
     init: "разложить правила и методички в текущий проект",
     initForce: "перезаписать уже существующие файлы",
     start: "кода ещё нет: сторожа дня 0 и порядок работы",
+    prove: "доказать, что гейты ловят брак: каждый по своему красному и зелёному образцу",
     doctor: "проверить, что разложено и чего не хватает",
     doctorRun: "ещё и запустить объявленные гейты",
     doctorSince: "то же, но показать только то, что внёс диф относительно ссылки",
@@ -42,6 +46,8 @@ export const ru = {
     emptyCommands: (n) => `В AGENTS.md ${n} незаполненных команд.`,
     emptyCommandsWhy: "Агент не может выполнить пустую строку.",
 
+    levelUnproven: (cmd) => `не доказано: ${cmd}`,
+    gatesDoNotCatch: (n, cmd) => `гейтов, не ловящих брак: ${n}. Подробности: ${cmd}`,
     levelHeading: "Уровень соответствия AQK",
     levelNone: "нет",
     levelNotSet: "Уровень: стандарт в этом репозитории не заведён.",
@@ -72,6 +78,10 @@ export const ru = {
     sinceBadRef: (ref) => `не могу сравнить с «${ref}»: такой ссылки нет или это не репозиторий git`,
     notScopable: "вывод без путей — дифом не сужается, оставлен красным",
     outsideDiff: (n) => `находки есть, но вне дифа (${n})`,
+    advisoryMark: "совещательный — показано, прогон не уронен",
+    advisorySummary: (names) =>
+      `совещательные и красные: ${names.join(", ")}. Это выключенные проверки: ` +
+      `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
     exitCode: (code) => `код ${code}`,
@@ -138,6 +148,8 @@ export const ru = {
       has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
       has_tests: ["не видно тестов", "тесты есть"],
       has_env: ["нет файла окружения", "файл окружения есть"],
+      has_agent_config: ["агента здесь не настраивали", "настройки агента есть"],
+      has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
     },
   },
@@ -167,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}`,
@@ -220,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: "команда завёрнута в храповик",
@@ -302,6 +326,8 @@ export const ru = {
 
   init: {
     noDocs: (dir) => `Не найден корпус методичек: ${dir}\nПохоже, пакет установлен не полностью.`,
+    docsRu:
+      "методички в .aqk/docs/ остаются на русском — решение, а не недоделка.",
     created: (n) => `создано (${n}):`,
     andMore: (n) => `… и ещё ${n}`,
     kept: (n) => `уже были на месте, не тронуты (${n}):`,
@@ -393,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}`,
@@ -466,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

@@ -18,7 +18,7 @@ const AGENTS_MD = `# AGENTS.md
 - **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.  <!-- aqk: swallowed-error -->
+- **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  <!-- aqk: human -->

package/tool/i18n/templates-ru.mjs

@@ -23,7 +23,7 @@ const AGENTS_MD = `# AGENTS.md
 - **Только файлы из задачи.** Заодно ничего не чиним.  <!-- aqk: человек -->
 - **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит  <!-- aqk: человек -->
   рабочим» — не готово.
-- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.  <!-- aqk: swallowed-error -->
+- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.  <!-- aqk: человек -->
 - **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием  <!-- aqk: человек -->
   в коде.
 - **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`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 = {

package/tool/lib/manifest.mjs

@@ -79,7 +79,7 @@ function parseManifest(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "gates", "samples", "ratchets", "lessons"];
+const KNOWN_KEYS = ["aqk", "entry", "rules", "gates", "samples", "ratchets", "lessons", "advisory"];
 
 function unknownKeys(man) {
   if (!man || typeof man !== "object" || Array.isArray(man)) return [];
@@ -119,6 +119,22 @@ function entryLifecycle(rec) {
   return { state, why, supersededBy: supersededBy || null, problem };
 }
 
+// СОВЕЩАТЕЛЬНЫЕ ГЕЙТЫ. Правило вводят в проект, где старый код ему не соответствует. Храповик
+// отвечает на это одним способом: старое становится долгом, новое блокируется. Второй способ —
+// показывать, не роняя, пока команда договаривается о правиле. Без него у человека остаётся
+// выбор из двух крайностей: включить и сломать сборку либо не включать вовсе.
+//
+// ПОЧЕМУ СПИСКОМ В МАНИФЕСТЕ, А НЕ ФЛАГОМ ПРОГОНА. Флаг «не роняй ничего» — это тот самый
+// `continue-on-error`, против которого написана наша запись ci-actually-fails: он понижает всё
+// разом, не виден в дифе и не назван в сводке. Список виден в манифесте, называется поимённо и
+// печатается КАЖДЫЙ прогон: совещательный гейт, о котором забыли, — это выключенная проверка,
+// и молчать о нём нельзя.
+function advisorySet(man) {
+  const v = man?.advisory;
+  if (Array.isArray(v)) return new Set(v.map((x) => String(x).trim()).filter(Boolean));
+  return new Set();
+}
+
 async function readManifest() {
   const p = join(CWD, MANIFEST);
   if (!(await exists(p))) return null;
@@ -130,7 +146,11 @@ async function readManifest() {
 }
 
 // Каждая ступень: что требуется, как проверяется, и что это даёт человеку.
-async function assessLevel(man) {
+// `proof` — результат `proveGates`: { ok } либо null, если доказательства не было. Ступень
+// AQK-2 требует его прямо: до 2026-09-07 она проверяла, что папки образцов и храповиков
+// СУЩЕСТВУЮТ, и проект с тремя гейтами `true` проходил порог AQK-3 с зелёным значком.
+// Проверено прогоном на пустой папке. Наличие папки — не защита; уровень обязан означать факт.
+async function assessLevel(man, proof = null) {
   const has = async (rel) => Boolean(rel) && (await exists(join(CWD, String(rel))));
   const isUrl = (v) => typeof v === "string" && /^https?:\/\//.test(v);
 
@@ -146,10 +166,21 @@ async function assessLevel(man) {
   const conditions = [
     Boolean(man?.aqk) && entriesExist,
     (await has(man?.rules)) && filledGates.length > 0,
-    (await has(man?.samples)) && (await has(man?.ratchets)),
+    (await has(man?.samples)) && (await has(man?.ratchets)) && proof?.ok === true,
     isUrl(man?.lessons) || (await has(man?.lessons)),
   ];
-  const steps = conditions.map((ok, level) => ({ level, ok, ...L.levels[level] }));
+  // Ступени, которым нужно доказательство, помечаются отдельно: «не выполнено» и «не проверяли»
+  // — разные состояния, и печатать их одинаково значит врать ровно тем способом, против
+  // которого весь комплект.
+  const NEEDS_PROOF = 2;
+  const steps = conditions.map((ok, level) => ({
+    level,
+    ok,
+    // Ровно вторая: третья ступень проверяет журнал, и посылать за доказательством там
+    // значит указать не на ту недостачу. Найдено код-ревью 2026-09-07.
+    needsProof: level === NEEDS_PROOF && proof === null,
+    ...L.levels[level],
+  }));
 
   let reached = -1;
   for (const s of steps) {
@@ -184,5 +215,5 @@ function manifestWithGate(text, slug, cmd) {
 
 export {
   parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
-  entryLifecycle,
+  entryLifecycle, advisorySet,
 };