agent-quality-kit 0.2.5 → 0.3.0

package/tool/i18n/templates-ru.mjs

@@ -0,0 +1,170 @@
+// tool/i18n/templates-ru.mjs — русские тексты, которые программа кладёт в чужой проект.
+//
+// ЗАЧЕМ ОТДЕЛЬНО ОТ ru.mjs. Шаблоны — это целые файлы, а не строки вывода: вместе они пробили
+// бы собственный предел размера файла в 500 строк. Ключи всё равно сверяются с английскими:
+// каталог подмешивает их к себе полем templates, и модульная проверка заходит внутрь.
+
+
+// ОДИН источник правил, НЕСКОЛЬКО входов. Каждый инструмент читает свой файл, но оба ведут в
+// .aqk/. Два расходящихся свода правил — худшее, что можно сделать: через месяц они врут
+// по-разному, и никто не знает, какой настоящий.
+
+const AGENTS_MD = `# AGENTS.md
+
+> Точка входа для агента. Держи файл коротким: раздутый свод правил вытесняет саму задачу из
+> контекста, и тогда игнорируются все правила разом. Всё длинное — по ссылкам ниже.
+
+## Железные правила
+
+- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.
+- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.
+- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.
+- **Секреты только в окружении.** Никогда в коде, логах и коммитах.
+- **Только файлы из задачи.** Заодно ничего не чиним.
+- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит
+  рабочим» — не готово.
+- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.
+- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием
+  в коде.
+- **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.
+  Он собирается прогоном: пересказ по памяти всегда выбирает удобное и молчит о том, что гейт
+  стоит на слабейшем рецепте.
+
+## Оснастка AQK — это твои команды, а не человека
+
+В репозитории стоит комплект AQK. Его смысл: **обещание проекта превращается в команду с кодом
+возврата**, и дальше его держит машина, а не чья-то внимательность. «Не оставляем отладочную
+печать» — текст, который можно проигнорировать; команда, возвращающая не ноль, — нельзя.
+
+Запускать их — твоя работа. Человек смотрит на список дыр и решает, какие закрывать.
+
+| Команда | Что делает | Когда звать |
+|---|---|---|
+| \`aqk doctor\` | смотрит репозиторий и печатает три списка: что уже держит машина, чего не хватает, что этому проекту не нужно и почему | начало работы над качеством; «что тут вообще есть» |
+| \`aqk doctor --run\` | **запускает** объявленные проверки и показывает, кто нашёл брак | перед сдачей; после правок; всегда, когда нужен факт, а не обещание |
+| \`aqk add <имя>\` | ставит проверку из каталога: копирует её и образцы в проект, объявляет в манифесте | человек согласился закрыть дыру из списка \`doctor\` |
+| \`aqk ratchet <имя>\` | старые нарушения записывает долгом, новые перестаёт пускать | проверка краснеет на старом коде, и чинить его сейчас никто не будет |
+| \`aqk find "…"\` | ищет по смыслу, есть ли уже такая проверка | прежде чем изобретать свою |
+| \`aqk note "…"\` | пишет урок в общий журнал | процесс или прибор подвели: проверка соврала, правило обошли |
+| \`aqk report\` | собирает прогоном отчёт: что стоит и каким рецептом, чего нет, что комплект велел прочитать | **обязательно** в конце работы с комплектом — вместо пересказа по памяти |
+
+Если команды \`aqk\` нет в системе — комплект ставили разово, без установки. Тогда вместо
+\`aqk\` пиши \`npx agent-quality-kit\`. Любая команда сама печатает тот
+вызов, который сработает у тебя.
+
+**Три вещи, которые надо понимать, а не запоминать:**
+
+1. **«Объявлен» и «работает» — разные утверждения.** \`doctor\` без \`--run\` честно говорит, что
+   проверки не запускал. Не выдавай объявленное за работающее.
+2. **Проверка без двух образцов ничего не доказывает.** Красный — код, на котором она обязана
+   сработать; зелёный — правильный, на котором обязана молчать. Зелёный важнее: без него однажды
+   она покраснеет на верном коде, и её выключат вместе с остальными.
+3. **Правило вводится храповиком, а не большой чисткой.** Чистка откладывается навсегда, потому
+   что она большая. Храповик даёт действующее правило со дня установки.
+
+**Повторился дефект того же класса — это не повод быть внимательнее, а повод завести проверку.**
+Дисциплина не масштабируется, механика — да.
+
+## Чужой код в репозитории
+
+Код, который лежит здесь, но написан не здесь (референс, вендоринг, генерация),
+исключается файлом \`.aqkignore\` в корне — по шаблону на строку. Правка копии \`_skip.sh\`
+не настройка: её затрёт следующий \`aqk add\`.
+
+## Где что лежит
+
+- \`.aqk/rules/\` — стандарты: общие, тесты, безопасность
+- \`.aqk/docs/\` — методички: минимум проекта, харнес, процесс, исследования
+- \`.aqk/docs/project-baseline.md\` — **начни отсюда**, если проект новый
+
+## Команды
+
+<!-- Заполни под свой проект. Команда, которую нельзя скопировать и выполнить, — не команда. -->
+
+- сборка: \`\`
+- тесты: \`\`
+- линтер: \`\`
+- всё разом перед пушем: \`\`
+
+## Чего в этом проекте нет
+
+<!-- Пиши сюда честно. Ненаписанное «нет» агент додумает как «есть». -->
+`;
+
+const CLAUDE_MD = `# CLAUDE.md
+
+Правила этого проекта живут в \`AGENTS.md\` — читай его.
+
+Один свод правил, несколько точек входа: \`AGENTS.md\` для агентов, понимающих его,
+\`CLAUDE.md\` — для Claude Code. Держать два расходящихся свода нельзя: через месяц они врут
+по-разному, и непонятно, какой настоящий.
+
+@AGENTS.md
+`;
+
+// Манифест — единственный машиночитаемый файл стандарта. Всё остальное человекочитаемо.
+// Пустые значения оставлены НАМЕРЕННО: заполненная заглушка врала бы про уровень.
+
+const GATE_YML_TEMPLATE = (slug) => `# Запись каталога AQK. Норма и все поля — kit/gates/README.md
+# Пока строки ниже не заполнены, проверка отклонит эту запись — так и задумано.
+
+# Одной фразой: какой класс брака ловит. По этому полю идёт сверка «есть ли уже такое».
+intent: ЗАПОЛНИ — какой класс брака ловит
+
+# Когда запись показывается человеку. Условие обязано быть запросом к репозиторию,
+# который умеет вычислить программа: always | langs: python, go | has_gates: true
+trigger:
+  always: true
+
+# Команда-арбитр под каждый стек. {gate} — папка записи, {dir} — что проверяем.
+# any — переносимая команда без сторонних программ.
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+# Реальный отказ, который эта проверка поймала. «Хорошая практика» не принимается:
+# ссылайся на запись журнала — incidents/README.md
+proof: ЗАПОЛНИ — какой отказ поймала и чего он стоил
+`;
+
+const CHECK_SH_TEMPLATE = `#!/usr/bin/env sh
+# Проверка. Возвращает 0 — чисто, не 0 — брак. В тексте отказа должно быть НАПИСАНО,
+# что сделать: он попадает прямо в контекст агента, и с инструкцией он чинит сам.
+DIR="\${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+
+# own_samples_filter прячет ТОЛЬКО gates/<имя>/red|green/ — не любую папку с таким именем
+# в проекте. --exclude-dir=red по голому имени однажды спрятал бы настоящую пользовательскую
+# папку red/ (нашли на secrets-not-in-code — kit/docs/ai/... журнал, 2026-09-04).
+HITS=$(grep -rnE $(skip_grep "$DIR") 'ЗАПОЛНИ_ШАБЛОН_ПОИСКА' "$DIR" 2>/dev/null | own_samples_filter "$DIR")
+if [ -n "$HITS" ]; then
+  echo "$HITS"
+  echo "  почини: ЗАПОЛНИ — что именно сделать"
+  exit 1
+fi
+exit 0
+`;
+
+const README_TEMPLATE = (slug) => `# ЗАПОЛНИ — заголовок одной строкой
+
+**Намерение.** Что и почему не должно попадать в код.
+
+**Какой отказ это поймало.** Что сломалось, в каком проекте, чего это стоило. Без этого
+запись не принимается: «это хорошая практика» набирает сотни пунктов, среди которых нельзя
+выбрать.
+
+**Почему машина, а не внимательность.** В какой момент человек это пропускает.
+
+**Готовый аналог.** Есть ли такая проверка в ruff, eslint, semgrep? Если есть — рецепт под этот
+язык обязан брать её, а своя проверка остаётся запасной. Если нет — написать, что именно
+проверено: «не искал» и «нет» — разные утверждения.
+
+**Чего НЕ ловит.** Честно назвать границу. Гейт, о пределах которого умалчивают, опаснее
+отсутствующего: на него понадеются.
+
+**Образцы.** \`red/\` — что здесь нарушено. \`green/\` — то же самое, но правильно.
+`;
+
+export const templates = {
+  AGENTS_MD, CLAUDE_MD,
+  GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE,
+};

package/tool/lib/core.mjs

@@ -36,6 +36,10 @@ const exists = async (p) => access(p, constants.F_OK).then(() => true, () => fal
 // Имя в реестре, а не адрес репозитория: короче, скачивается 230 КБ вместо клона всего
 // репозитория и не заставляет человека ждать три минуты в тишине на первой же команде.
 const REPO = "agent-quality-kit";
+// Адрес репозитория отдельно от имени пакета. Когда имя стало коротким, ссылка «поставь
+// звезду» собиралась из него и вела на github.com/agent-quality-kit — несуществующую
+// страницу. Два разных адреса, собранные из одной строки, однажды разъезжаются.
+const REPO_URL = "https://github.com/arsen-ask-lx/Agent_Quality_Kit";
 
 function selfCmd() {
   const p = process.argv[1] || "";
@@ -96,5 +100,5 @@ export {
   copyDir, writeIfAbsent,
   PKG_ROOT, CWD, DOCS_SRC, RULES_SRC, TARGET_DIR,
   MANIFEST, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB,
-  SELF, REPO, c, exists, die, FEEDBACK_MARK,
+  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK,
 };

package/tool/lib/manifest.mjs

@@ -3,6 +3,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CWD, MANIFEST, PROJECT_GATES, exists } from "./core.mjs";
+import { L } from "../i18n/index.mjs";
 
 // СТАНДАРТ. Уровень — не самооценка и не галочка в README, а вычисляемое утверждение:
 // каждая ступень проверяется файлами на диске. Утверждение, которое нельзя проверить
@@ -75,36 +76,16 @@ async function assessLevel(man) {
   const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
   const filledGates = Object.entries(gates).filter(([, cmd]) => String(cmd || "").trim());
 
-  const steps = [
-    {
-      level: 0,
-      title: "манифест и точка входа",
-      ok: Boolean(man?.aqk) && entriesExist,
-      need: "создай .aqk.yml и укажи в entry файл, который агент читает первым (AGENTS.md)",
-      gives: "любой инструмент понимает, что читать в этом репозитории",
-    },
-    {
-      level: 1,
-      title: "правила и работающие гейты",
-      ok: (await has(man?.rules)) && filledGates.length > 0,
-      need: "укажи rules (каталог стандартов) и заполни хотя бы один гейт в gates реальной командой",
-      gives: "проверки объявлены командами, а не описаны словами",
-    },
-    {
-      level: 2,
-      title: "гейты доказаны, долг под храповиком",
-      ok: (await has(man?.samples)) && (await has(man?.ratchets)),
-      need: "заведи samples (красные и зелёные образцы гейтов) и ratchets (реестры долга)",
-      gives: "гейт доказал, что ловит брак и молчит на исправном коде",
-    },
-    {
-      level: 3,
-      title: "уроки возвращаются в работу",
-      ok: isUrl(man?.lessons) || (await has(man?.lessons)),
-      need: "укажи lessons — путь или адрес журнала, где каждый инцидент даёт вывод",
-      gives: "проект учится: одна и та же шишка не набивается дважды",
-    },
+  // Условие ступени — здесь, её описание — в каталоге строк: текст переводится, условие нет.
+  // Разложить их по разным файлам стоило того, чтобы перевод не мог случайно поменять смысл
+  // проверки; порядок ступеней связывает их по индексу и сверяется модульной проверкой.
+  const conditions = [
+    Boolean(man?.aqk) && entriesExist,
+    (await has(man?.rules)) && filledGates.length > 0,
+    (await has(man?.samples)) && (await has(man?.ratchets)),
+    isUrl(man?.lessons) || (await has(man?.lessons)),
   ];
+  const steps = conditions.map((ok, level) => ({ level, ok, ...L.levels[level] }));
 
   let reached = -1;
   for (const s of steps) {
@@ -120,8 +101,8 @@ function manifestWithGate(text, slug, cmd) {
   const entry = `  ${slug}: "${cmd}"`;
 
   const gi = lines.findIndex((l) => /^gates:\s*$/.test(l));
-  if (gi === -1) return { text: null, why: "в .aqk.yml нет блока gates:" };
-  if (lines.some((l) => new RegExp(`^\\s+${slug}:`).test(l))) return { text: null, why: "уже объявлен" };
+  if (gi === -1) return { text: null, why: L.manifest.noGatesBlock };
+  if (lines.some((l) => new RegExp(`^\\s+${slug}:`).test(l))) return { text: null, why: L.manifest.alreadyDeclared };
 
   let last = gi;
   for (let i = gi + 1; i < lines.length; i++) {

package/tool/lib/repo.mjs

@@ -2,10 +2,12 @@
 // триггера, выбор рецепта, сверка по намерению.
 
 import { readdir, readFile } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { CWD, GATES_SRC, c, exists } from "./core.mjs";
 import { parseManifest } from "./manifest.mjs";
+import { L, LANG } from "../i18n/index.mjs";
 
 // Каталог лежит в комплекте, а не в проекте: записи общие для всех, проект лишь
 // решает, какие из них у него стоят. Показывать все подряд нельзя — это и есть
@@ -103,7 +105,11 @@ async function readCatalog() {
     const yml = join(GATES_SRC, name.name, "gate.yml");
     if (!(await exists(yml))) continue;
     const rec = parseManifest(await readFile(yml, "utf8"));
-    out.push({ slug: name.name, ...rec });
+    // Намерение показывается на языке вывода. Английское поле необязательно: запись, принесённая
+    // без него, покажет русское намерение — это хуже перевода, но честнее пустой строки, и
+    // не закрывает вклад тому, кто пишет на одном языке.
+    const intent = (LANG === "en" ? rec.intent_en : rec.intent) || rec.intent || rec.intent_en || "";
+    out.push({ slug: name.name, ...rec, intent });
   }
   return out.sort((a, b) => a.slug.localeCompare(b.slug));
 }
@@ -121,30 +127,22 @@ const CONDITIONS = {
     const want = String(val).split(",").map((x) => x.trim()).filter(Boolean);
     return want.some((l) => f.langs.has(l))
       ? { ok: true }
-      : { ok: false, why: `нет языков: ${want.join(", ")}` };
+      : { ok: false, why: L.trigger.noLangs(want.join(", ")) };
   },
 
   files_gt: (val, f) =>
-    f.files > Number(val) ? { ok: true } : { ok: false, why: `меньше ${val} файлов — рано` },
+    f.files > Number(val) ? { ok: true } : { ok: false, why: L.trigger.tooFewFiles(val) },
 
   files_lt: (val, f) =>
-    f.files < Number(val) ? { ok: true } : { ok: false, why: `больше ${val} файлов` },
+    f.files < Number(val) ? { ok: true } : { ok: false, why: L.trigger.tooManyFiles(val) },
 };
 
-const FLAG_WHY = {
-  has_gates: ["в манифесте не объявлено ни одного гейта", "гейты уже объявлены"],
-  has_ci: ["в репозитории нет конвейера", "конвейер уже есть"],
-  has_db: ["не видно базы данных: ни миграций, ни sql", "база данных есть"],
-  has_docker: ["нет Dockerfile или compose", "docker уже есть"],
-  has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
-  has_tests: ["не видно тестов", "тесты есть"],
-  has_env: ["нет файла окружения", "файл окружения есть"],
-};
+const FLAG_WHY = L.trigger.flags;
 
 function triggerVerdict(rec, facts) {
   const t = rec.trigger && typeof rec.trigger === "object" && !Array.isArray(rec.trigger) ? rec.trigger : {};
   const keys = Object.keys(t);
-  if (!keys.length) return { applies: false, why: "триггер не задан" };
+  if (!keys.length) return { applies: false, why: L.trigger.notSet };
 
   for (const key of keys) {
     const raw = String(t[key]).trim();
@@ -166,11 +164,39 @@ function triggerVerdict(rec, facts) {
       continue;
     }
 
-    return { applies: false, why: `условие «${key}» программа не умеет считать` };
+    return { applies: false, why: L.trigger.unknown(key) };
   }
   return { applies: true };
 }
 
+// Есть ли такая программа в PATH. Своим обходом, а не `command -v`: на Windows оболочка —
+// cmd.exe, где такой команды нет вовсе, и проверка возвращала «не установлено» ДЛЯ ЛЮБОЙ
+// программы. Следствие было тихим и потому худшим: родной рецепт (ruff, eslint, jscpd) там
+// недостижим в принципе, гейт молча вставал на слабейший переносимый вариант, а `doctor --run`
+// показывал зелёное. Нашлось только на чужом прогоне — журнал, 2026-09-04.
+function whichSync(prog, env = process.env) {
+  if (!prog) return null;
+  // Путь, а не имя: команду вроде ./scripts/check.sh искать в PATH бессмысленно.
+  if (prog.includes("/") || prog.includes("\\")) return existsSync(prog) ? prog : null;
+
+  const sep = process.platform === "win32" ? ";" : ":";
+  const dirs = String(env.PATH || env.Path || "").split(sep).filter(Boolean);
+  // На Windows исполняемость задаёт расширение, а не флаг доступа: ruff — это ruff.exe.
+  const exts = process.platform === "win32"
+    ? String(env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+    : [""];
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const full = join(dir.replace(/^"|"$/g, ""), prog + ext);
+      try {
+        if (statSync(full).isFile()) return full;
+      } catch { /* нет такого файла — идём дальше, это не ошибка */ }
+    }
+  }
+  return null;
+}
+
 // Арбитр под стек этого проекта: сначала родной рецепт, иначе — переносимый `any`.
 // Подсказка, которую нельзя скопировать и выполнить, бесполезна.
 // Выбор рецепта под стек проекта. Одна логика на два места: и `doctor`, и `add` показывают
@@ -182,21 +208,18 @@ function pickRecipe(rec, facts) {
   // Родной рецепт лучше переносимого — но только если его есть чем выполнить. Поставить
   // команду с неустановленной программой значит завести гейт, который встаёт с «not found»:
   // отсутствие сигнала неотличимо от успеха.
-  const runnable = (c0) => {
-    const prog = String(c0).trim().split(/\s+/)[0];
-    return spawnSync(`command -v ${prog}`, { shell: true, stdio: "ignore" }).status === 0;
-  };
+  const runnable = (c0) => Boolean(whichSync(String(c0).trim().split(/\s+/)[0]));
   for (const lang of facts.langs) {
     if (!recipes[lang]) continue;
     if (runnable(recipes[lang])) return recipes[lang];
-    console.log(c.dim(`  ${c.yellow("!")}  рецепт под ${lang} пропущен: «${String(recipes[lang]).split(/\s+/)[0]}» не установлен`));
+    console.log(c.dim(`  ${c.yellow("!")}  ${L.recipe.skipped(lang, String(recipes[lang]).split(/\s+/)[0])}`));
   }
   return recipes.any || null;
 }
 
 function recipeFor(rec, facts) {
   const cmd = pickRecipe(rec, facts);
-  if (!cmd) return "рецепт не описан";
+  if (!cmd) return L.recipe.none;
   return String(cmd)
     .replace(/\{gate\}/g, join(GATES_SRC, rec.slug))
     .replace(/\{dir\}/g, ".");
@@ -265,6 +288,7 @@ async function matchCatalog(query) {
 // Наружу — то, что действительно импортируют другие файлы и модульные проверки. Экспорт,
 // который никто не берёт, читается как часть договора и мешает менять внутренности.
 export {
+  whichSync,
   EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor,
   stems, overlap, matchCatalog,
 };

package/tool/lib/templates.mjs

@@ -1,187 +1,43 @@
 // tool/lib/templates.mjs — тексты, которые программа кладёт в чужой проект.
 //
 // ЗАЧЕМ ОТДЕЛЬНО. Это не код, а содержимое: правят его чаще и по другим причинам, чем логику.
-// Лёжа вперемешку с логикой, они мешали читать и то, и другое.
-
-import { SELF } from "./core.mjs";
-
-// ОДИН источник правил, НЕСКОЛЬКО входов. Каждый инструмент читает свой файл, но оба ведут в
-// .aqk/. Два расходящихся свода правил — худшее, что можно сделать: через месяц они врут
-// по-разному, и никто не знает, какой настоящий.
-
-const AGENTS_MD = `# AGENTS.md
-
-> Точка входа для агента. Держи файл коротким: раздутый свод правил вытесняет саму задачу из
-> контекста, и тогда игнорируются все правила разом. Всё длинное — по ссылкам ниже.
-
-## Железные правила
-
-- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.
-- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.
-- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.
-- **Секреты только в окружении.** Никогда в коде, логах и коммитах.
-- **Только файлы из задачи.** Заодно ничего не чиним.
-- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит
-  рабочим» — не готово.
-- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.
-- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием
-  в коде.
-
-## Оснастка AQK — это твои команды, а не человека
-
-В репозитории стоит комплект AQK. Его смысл: **обещание проекта превращается в команду с кодом
-возврата**, и дальше его держит машина, а не чья-то внимательность. «Не оставляем отладочную
-печать» — текст, который можно проигнорировать; команда, возвращающая не ноль, — нельзя.
-
-Запускать их — твоя работа. Человек смотрит на список дыр и решает, какие закрывать.
-
-| Команда | Что делает | Когда звать |
-|---|---|---|
-| \`aqk doctor\` | смотрит репозиторий и печатает три списка: что уже держит машина, чего не хватает, что этому проекту не нужно и почему | начало работы над качеством; «что тут вообще есть» |
-| \`aqk doctor --run\` | **запускает** объявленные проверки и показывает, кто нашёл брак | перед сдачей; после правок; всегда, когда нужен факт, а не обещание |
-| \`aqk add <имя>\` | ставит проверку из каталога: копирует её и образцы в проект, объявляет в манифесте | человек согласился закрыть дыру из списка \`doctor\` |
-| \`aqk ratchet <имя>\` | старые нарушения записывает долгом, новые перестаёт пускать | проверка краснеет на старом коде, и чинить его сейчас никто не будет |
-| \`aqk find "…"\` | ищет по смыслу, есть ли уже такая проверка | прежде чем изобретать свою |
-| \`aqk note "…"\` | пишет урок в общий журнал | процесс или прибор подвели: проверка соврала, правило обошли |
-
-Если команды \`aqk\` нет в системе — комплект ставили разово, без установки. Тогда вместо
-\`aqk\` пиши \`npx agent-quality-kit\`. Любая команда сама печатает тот
-вызов, который сработает у тебя.
-
-**Три вещи, которые надо понимать, а не запоминать:**
-
-1. **«Объявлен» и «работает» — разные утверждения.** \`doctor\` без \`--run\` честно говорит, что
-   проверки не запускал. Не выдавай объявленное за работающее.
-2. **Проверка без двух образцов ничего не доказывает.** Красный — код, на котором она обязана
-   сработать; зелёный — правильный, на котором обязана молчать. Зелёный важнее: без него однажды
-   она покраснеет на верном коде, и её выключат вместе с остальными.
-3. **Правило вводится храповиком, а не большой чисткой.** Чистка откладывается навсегда, потому
-   что она большая. Храповик даёт действующее правило со дня установки.
-
-**Повторился дефект того же класса — это не повод быть внимательнее, а повод завести проверку.**
-Дисциплина не масштабируется, механика — да.
-
-## Где что лежит
-
-- \`.aqk/rules/\` — стандарты: общие, тесты, безопасность
-- \`.aqk/docs/\` — методички: минимум проекта, харнес, процесс, исследования
-- \`.aqk/docs/project-baseline.md\` — **начни отсюда**, если проект новый
-
-## Команды
-
-<!-- Заполни под свой проект. Команда, которую нельзя скопировать и выполнить, — не команда. -->
-
-- сборка: \`\`
-- тесты: \`\`
-- линтер: \`\`
-- всё разом перед пушем: \`\`
-
-## Чего в этом проекте нет
-
-<!-- Пиши сюда честно. Ненаписанное «нет» агент додумает как «есть». -->
-`;
-
-const CLAUDE_MD = `# CLAUDE.md
-
-Правила этого проекта живут в \`AGENTS.md\` — читай его.
-
-Один свод правил, несколько точек входа: \`AGENTS.md\` для агентов, понимающих его,
-\`CLAUDE.md\` — для Claude Code. Держать два расходящихся свода нельзя: через месяц они врут
-по-разному, и непонятно, какой настоящий.
-
-@AGENTS.md
-`;
-
-// Манифест — единственный машиночитаемый файл стандарта. Всё остальное человекочитаемо.
-// Пустые значения оставлены НАМЕРЕННО: заполненная заглушка врала бы про уровень.
-const MANIFEST_YML = `# .aqk.yml — манифест Agent Quality Kit
-# Что это: машиночитаемое описание того, как в этом репозитории живут агенты.
-# Уровень соответствия считает \`aqk doctor\`. Пустое поле = ступень не пройдена,
-# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.
-
-aqk: 1
-
-# AQK-0 — что агент читает первым.
-entry:
-  - AGENTS.md
-
-# AQK-1 — где стандарты и какие проверки обязательны.
-rules: .aqk/rules
-gates:
-  # Имя: команда, возвращающая 0 или не 0. Пустое объявление защиты не даёт и бракуется
-  # проверкой «объявленный гейт запускается» — поэтому здесь примеры, а не заготовки.
-  #   lint: "ruff check ."
-  #   test: "pytest -q"
-  # Поставить готовую запись из каталога вместе с образцами: aqk add <имя>
-
-# AQK-2 — чем доказано, что гейты работают, и где реестры долга.
-# samples: каталог с красными и зелёными образцами (гейт обязан краснеть на первом
-# и молчать на втором). ratchets: списки известных нарушений, которые могут только
-# укорачиваться.
-samples: ""
-ratchets: ""
-
-# AQK-3 — где копятся уроки. Путь или адрес.
-lessons: ""
-`;
-
-const GATE_YML_TEMPLATE = (slug) => `# Запись каталога AQK. Норма и все поля — kit/gates/README.md
-# Пока строки ниже не заполнены, проверка отклонит эту запись — так и задумано.
-
-# Одной фразой: какой класс брака ловит. По этому полю идёт сверка «есть ли уже такое».
-intent: ЗАПОЛНИ — какой класс брака ловит
-
-# Когда запись показывается человеку. Условие обязано быть запросом к репозиторию,
-# который умеет вычислить программа: always | langs: python, go | has_gates: true
-trigger:
-  always: true
-
-# Команда-арбитр под каждый стек. {gate} — папка записи, {dir} — что проверяем.
-# any — переносимая команда без сторонних программ.
-recipes:
-  any: bash {gate}/check.sh {dir}
-
-# Реальный отказ, который эта проверка поймала. «Хорошая практика» не принимается:
-# ссылайся на запись журнала — incidents/README.md
-proof: ЗАПОЛНИ — какой отказ поймала и чего он стоил
-`;
-
-const CHECK_SH_TEMPLATE = `#!/usr/bin/env sh
-# Проверка. Возвращает 0 — чисто, не 0 — брак. В тексте отказа должно быть НАПИСАНО,
-# что сделать: он попадает прямо в контекст агента, и с инструкцией он чинит сам.
-DIR="\${1:-.}"
-. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
-
-# own_samples_filter прячет ТОЛЬКО gates/<имя>/red|green/ — не любую папку с таким именем
-# в проекте. --exclude-dir=red по голому имени однажды спрятал бы настоящую пользовательскую
-# папку red/ (нашли на secrets-not-in-code — kit/docs/ai/... журнал, 2026-09-04).
-HITS=$(grep -rnE $(skip_grep "$DIR") 'ЗАПОЛНИ_ШАБЛОН_ПОИСКА' "$DIR" 2>/dev/null | own_samples_filter "$DIR")
-if [ -n "$HITS" ]; then
-  echo "$HITS"
-  echo "  почини: ЗАПОЛНИ — что именно сделать"
-  exit 1
-fi
-exit 0
-`;
-
-const README_TEMPLATE = (slug) => `# ЗАПОЛНИ — заголовок одной строкой
-
-**Намерение.** Что и почему не должно попадать в код.
-
-**Какой отказ это поймало.** Что сломалось, в каком проекте, чего это стоило. Без этого
-запись не принимается: «это хорошая практика» набирает сотни пунктов, среди которых нельзя
-выбрать.
-
-**Почему машина, а не внимательность.** В какой момент человек это пропускает.
-
-**Готовый аналог.** Есть ли такая проверка в ruff, eslint, semgrep? Если есть — рецепт под этот
-язык обязан брать её, а своя проверка остаётся запасной. Если нет — написать, что именно
-проверено: «не искал» и «нет» — разные утверждения.
-
-**Чего НЕ ловит.** Честно назвать границу. Гейт, о пределах которого умалчивают, опаснее
-отсутствующего: на него понадеются.
-
-**Образцы.** \`red/\` — что здесь нарушено. \`green/\` — то же самое, но правильно.
-`;
+// Сами тексты живут в tool/i18n/templates-{ru,en}.mjs — здесь только выбор языка. Человек,
+// пришедший с англоязычной страницы пакета, получал английский интерфейс и русский AGENTS.md
+// у себя в репозитории: файл, который он и его агент читают первым.
+
+import { L } from "../i18n/index.mjs";
+
+const {
+  AGENTS_MD, CLAUDE_MD,
+  GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE,
+} = L.templates;
+
+// Схема манифеста — ОДНА на все языки, переводятся только комментарии. Пока схема лежала в
+// двух языковых файлах, гейт дублей поймал её сам: добавь кто-то ключ в один шаблон и забудь
+// про другой — англоязычный пользователь получил бы другой манифест. Ключи машиночитаемы,
+// расходиться им нельзя; комментарии человекочитаемы, им положено.
+const d = L.manifestDoc;
+const MANIFEST_YML = [
+  ...d.head,
+  "",
+  "aqk: 1",
+  "",
+  d.entry,
+  "entry:",
+  "  - AGENTS.md",
+  "",
+  d.rules,
+  "rules: .aqk/rules",
+  "gates:",
+  ...d.gates,
+  "",
+  ...d.samples,
+  'samples: ""',
+  'ratchets: ""',
+  "",
+  d.lessons,
+  'lessons: ""',
+  "",
+].join("\n");
 
 export { AGENTS_MD, CLAUDE_MD, MANIFEST_YML, GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE };