agent-quality-kit 0.6.0 → 0.8.0

package/tool/i18n/en-docs.mjs

@@ -0,0 +1,154 @@
+// 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 = {
+  // THE STATE BLOCK — the one text of ours whose reader is a machine, not a person.
+  // It goes into the agent's context via a SessionStart hook, so it is written as claims of
+  // fact: no politeness, no preamble, every line either a fact or an honest "unknown".
+  context: {
+    title: "AQK — the state of this repository right now. Only what a machine computed; where it\ndoes not know, it says \"unknown\" — which is not the same as \"fine\".",
+    level: (r, top, missing) =>
+      `Level: AQK-${r} of ${top}.` + (missing ? ` AQK-${r + 1} is missing: ${missing}.` : ""),
+    levelUnknown: "Level: not computed — there is no .aqk.yml here. The standard is not set up.",
+    rules: (total, machine, human) =>
+      `Rules in the entry point: ${total}. Held by a machine ${machine}, by a human ${human}.`,
+    rulesNobody: "A rule held by a human is held by nobody: no machine checks it.",
+    runNone:
+      "No run has been made — which checks are red is UNKNOWN. This is not \"clean\": `aqk doctor --run`.",
+    runStale: (when) =>
+      `The last run ${when} is OLDER than the last commit — it describes different code.`,
+    runClean: (when) => `Last run ${when} — nothing red.`,
+    runRed: (when, names) => `Last run ${when} — RED: ${names}.`,
+    andMore: (n) => `and ${n} more`,
+    skipped: (n) => `Not run: ${n} — the tool is absent on this machine, their state is unknown.`,
+    ratchets: (list) => `Ratchets: ${list}. The list may only get shorter, never longer.`,
+    where: (entry) => `The rulebook: ${entry}. What proves a diff: \`aqk report --since main\`.`,
+    mapTitle: "WHAT THIS TOOL CAN DO. The full list of commands — not a retelling, the same list\nthe help is built from:",
+    rulesTitle: (e) => `THE RULEBOOK OF THIS PROJECT (${e}) — verbatim, in full. This is not an invitation\nto read it: it is already here.`,
+    hookAlready: (p) => `the hook is already in ${p} — changing nothing.`,
+    hookAdded: (p) => `SessionStart hook appended to ${p}:`,
+    hookCreated: (p) => `created ${p} with a SessionStart hook:`,
+    hookBadJson: (p) => `${p} does not parse as JSON — leaving it alone. Fix it and retry.`,
+    hookWhat:
+      "the project state now reaches the agent's context before its first action, not at its discretion.",
+  },
+  // Форма отчёта переехала сюда из терминального каталога 2026-09-08: это текст, который
+  // программа ПИШЕТ в .aqk/report.md, а не говорит в терминал. Повод — тот же гейт
+  // file-size-limit, что развёл эти файлы в первый раз: терминальный каталог снова перерос
+  // 500 строк. Шов по смыслу, а не пополам.
+  report2: {
+    evidenceNamed: (who) => `named by: ${who}`,
+    evidenceSilent: (n) => `${n} check${n === 1 ? "" : "s"} walked past it and said nothing`,
+    evidenceTitle: "What proves this diff",
+    evidenceUncovered: "no check named this file",
+    evidenceBase: "base of comparison",
+    evidenceHash: "evidence fingerprint",
+    evidenceBadRef: (r) => `ref "${r}" could not be resolved — coverage not computed`,
+    evidenceNoFiles: (r) => `no code files in the diff against "${r}" — nothing to prove`,
+    evidenceWarn:
+      "◻️ means a check walked the directory and said nothing. \"Scanned and clean\" and " +
+      "\"never looked\" are indistinguishable from the output, and neither may be passed off " +
+      "as the other. " +
+      "The fingerprint covers the base, the set of commands and the contents of the files. " +
+      "Change any of them and this report is stale, so \"ran it, then edited three more files\" " +
+      "stops being indistinguishable from \"ran it\". Mechanism taken from donecheck (MIT).",
+    title: "AQK report",
+    noManifest: (cmd) => `No .aqk.yml — nothing to report on. Start with ${cmd}`,
+    level: "Level",
+    holdsTitle: "What a machine holds (from a run, not from the manifest)",
+    nothingRuns: "⬜ no gate is declared",
+    native: (prog) => `native recipe: ${prog}`,
+    portable: "portable check",
+    weakerTitle: "Weaker than it could be",
+    weaker: (progs) => `${progs} is available on this system, but the gate uses the portable check — it catches less`,
+    missingTitle: "What is missing",
+    nothingMissing: "✅ every applicable entry is installed",
+    needsTool: (prog) => `needs ${prog} — not on this system`,
+    notInstalled: "applicable, but not installed",
+    hiddenTitle: "Not applicable to this repository",
+    readTitle: "What the kit told you to read",
+    readWarn:
+      "The mark only means the file is on disk. Whether it was read, the machine does not know " +
+      "and does not pretend to: that is answered by whoever is reporting.",
+    ignoreTitle: "What .aqkignore hides",
+    ignoreNone: "no .aqkignore file — nothing is hidden",
+    ignoreWarn:
+      "Hiding things silently is the same class as a silent gate: the gates do not look at these " +
+      "paths at all. A line here means there is no protection there, and will not be.",
+    whyTitle: "Why this matters — briefly",
+    whyNothing: "nothing to add: everything applicable is in place",
+    saved: (path) => `Saved: ${path}`,
+    docs: {
+      baseline: "the minimum a project needs, independent of language",
+      readyMade: "the map of off-the-shelf rules: look for a ready one before writing your own",
+      rulesGeneral: "general working rules",
+      rulesTesting: "rules about tests",
+      rulesSecurity: "rules about security",
+    },
+  },
+  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. docs — where the\n# guides are: doctor reads both, so the kit may live anywhere you like.",
+    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,24 @@
 // Правка здесь обязана иметь пару в ru.mjs с тем же ключом: расхождение ловит модульная
 // проверка «оба каталога несут одни и те же ключи».
 
+import { enDocs } from "./en-docs.mjs";
+
 import { templates } from "./templates-en.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}`,
+    nothing: "everything that looks like a rule is already in the entry point",
+    andMore: (n) => `… and ${n} more`,
+    warn:
+      "These are CANDIDATES, not findings: measured on 1619 messages, the markers returned 79, and " +
+      "about half of those are real rules. The human decides. Nothing was written to disk — the " +
+      "command reads transcripts and prints to the terminal only.",
+  },
+  ...enDocs,
   templates,
   help: {
     tagline: "tooling for building software with agents",
@@ -13,6 +28,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",
@@ -23,13 +39,20 @@ export const en = {
     new: "scaffold your own gate for the catalogue",
     note: "record a lesson in the shared bruise journal",
     blob: "assemble the guides into a single GOD_AI.md",
-    report: "the mandatory report form: what is in place, what is not, what was not read",
+    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",
+    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",
     noInstall: "Without installing:  npx agent-quality-kit init",
     language: "Output language: AQK_LANG=ru (or en), otherwise your system locale",
   },
 
   doctor: {
+    baselineClash: (f) =>
+      `"--baseline" is an inspection, not a run: it always exits 0, so together with "${f}" it\n` +
+      "  gives you a pipeline that cannot go red.\n" +
+      "  fix: split it in two — \"doctor --baseline\" and \"doctor --run --min 1\".",
     docsKit: "guides — the originals live here, not a copy",
     docs: "guides",
     rulesKit: "standards — the originals live here, not a copy",
@@ -41,6 +64,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 +96,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 +161,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 +191,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 +250,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 +339,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}):`,
@@ -314,6 +360,7 @@ export const en = {
     n4c: ". A gate guards an artefact that exists:",
     n4d: "a check for code that is not written yet is a dead rule.",
     burned: (cmd) => `Got burned by something — write it down: ${cmd}`,
+    hookHint: (cmd) => `Claude Code: ${cmd} — the project state will reach the agent's context\n  by itself, before its first action. Other agents have no hook, and that is not an omission.`,
   },
 
   feedback: {
@@ -386,31 +433,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}`,
@@ -423,69 +466,6 @@ export const en = {
     checkOk: (level, where) => `Badge matches the run: AQK-${level} — ${where}`,
   },
 
-  report2: {
-    title: "AQK report",
-    noManifest: (cmd) => `No .aqk.yml — nothing to report on. Start with ${cmd}`,
-    level: "Level",
-    holdsTitle: "What a machine holds (from a run, not from the manifest)",
-    nothingRuns: "⬜ no gate is declared",
-    native: (prog) => `native recipe: ${prog}`,
-    portable: "portable check",
-    weakerTitle: "Weaker than it could be",
-    weaker: (progs) => `${progs} is available on this system, but the gate uses the portable check — it catches less`,
-    missingTitle: "What is missing",
-    nothingMissing: "✅ every applicable entry is installed",
-    needsTool: (prog) => `needs ${prog} — not on this system`,
-    notInstalled: "applicable, but not installed",
-    hiddenTitle: "Not applicable to this repository",
-    readTitle: "What the kit told you to read",
-    readWarn:
-      "The mark only means the file is on disk. Whether it was read, the machine does not know " +
-      "and does not pretend to: that is answered by whoever is reporting.",
-    ignoreTitle: "What .aqkignore hides",
-    ignoreNone: "no .aqkignore file — nothing is hidden",
-    ignoreWarn:
-      "Hiding things silently is the same class as a silent gate: the gates do not look at these " +
-      "paths at all. A line here means there is no protection there, and will not be.",
-    whyTitle: "Why this matters — briefly",
-    whyNothing: "nothing to add: everything applicable is in place",
-    saved: (path) => `Saved: ${path}`,
-    docs: {
-      baseline: "the minimum a project needs, independent of language",
-      readyMade: "the map of off-the-shelf rules: look for a ready one before writing your own",
-      rulesGeneral: "general working rules",
-      rulesTesting: "rules about tests",
-      rulesSecurity: "rules about security",
-    },
-  },
 
-  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,156 @@
+// tool/i18n/ru-docs.mjs — тексты, которые уходят В ФАЙЛ, а не в терминал.
+//
+// ЗАЧЕМ ОТДЕЛЬНО. Каталог строк перерос собственный предел в 500 строк — его поймал наш же
+// гейт file-size-limit. Шов выбран по смыслу, а не пополам: здесь то, что программа ПИШЕТ
+// (комментарии в .aqk.yml, названия ступеней, форма отчёта), а в ru.mjs — то, что она ГОВОРИТ.
+// У этих текстов разная жизнь: первые читает человек в своём репозитории месяцы спустя,
+// вторые — он же в терминале, одну секунду.
+
+const ruDocs = {
+  // БЛОК СОСТОЯНИЯ — единственный наш текст, у которого читатель машина, а не человек.
+  // Уходит в контекст агента хуком SessionStart, поэтому пишется как утверждения о факте:
+  // без вежливости, без вводных, каждая строка либо факт, либо честное «неизвестно».
+  // Замер 2026-09-08: блок ≈147 токенов против ≈3348 у AGENTS.md — и несёт то, чего в файле
+  // нет и быть не может, потому что меняется каждый день.
+  context: {
+    title: "AQK — состояние этого репозитория на сейчас. Ниже только вычисленное машиной; где\nмашина не знает — сказано «неизвестно», и это не «всё хорошо».",
+    level: (r, top, missing) =>
+      `Уровень: AQK-${r} из ${top}.` + (missing ? ` До AQK-${r + 1} не хватает: ${missing}.` : ""),
+    levelUnknown: "Уровень: не вычислен — в репозитории нет .aqk.yml. Стандарт здесь не заведён.",
+    rules: (total, machine, human) =>
+      `Правил в точке входа: ${total}. Держит машина ${machine}, держит человек ${human}.`,
+    rulesNobody: "Правило, которое держит человек, не держит никто: машина его не проверяет.",
+    runNone:
+      "Прогон не делался — какие проверки красные, НЕИЗВЕСТНО. Это не «чисто»: `aqk doctor --run`.",
+    runStale: (when) =>
+      `Последний прогон ${when} СТАРЕЕ последнего коммита — он описывает не тот код, что здесь.`,
+    runClean: (when) => `Последний прогон ${when} — красных нет.`,
+    runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
+    andMore: (n) => `и ещё ${n}`,
+    skipped: (n) => `Не запускались: ${n} — инструмента нет на этой машине, их состояние неизвестно.`,
+    ratchets: (list) => `Храповики: ${list}. Список может только укорачиваться, увеличивать нельзя.`,
+    where: (entry) => `Свод правил: ${entry}. Чем доказан диф: \`aqk report --since main\`.`,
+    mapTitle: "ЧТО УМЕЕТ ЭТОТ ИНСТРУМЕНТ. Полный список команд — не пересказ, а тот же список,\nиз которого собрана справка:",
+    rulesTitle: (e) => `СВОД ПРАВИЛ ЭТОГО ПРОЕКТА (${e}) — дословно, целиком. Это не приглашение\nпрочитать: он уже здесь.`,
+    hookAlready: (p) => `хук уже стоит в ${p} — ничего не меняю.`,
+    hookAdded: (p) => `хук SessionStart дописан в ${p}:`,
+    hookCreated: (p) => `создан ${p} с хуком SessionStart:`,
+    hookBadJson: (p) => `${p} не разбирается как JSON — не трогаю его. Почини файл и повтори.`,
+    hookWhat:
+      "теперь состояние проекта попадает в контекст агента до первого действия, а не по его желанию.",
+  },
+  // Форма отчёта переехала сюда из терминального каталога 2026-09-08: это текст, который
+  // программа ПИШЕТ в .aqk/report.md, а не говорит в терминал. Повод — тот же гейт
+  // file-size-limit, что развёл эти файлы в первый раз: терминальный каталог снова перерос
+  // 500 строк. Шов по смыслу, а не пополам.
+  report2: {
+    evidenceNamed: (who) => `назван проверками: ${who}`,
+    evidenceSilent: (n) => `${n} ${n === 1 ? "проверка прошла" : "проверок прошли"} мимо и промолчали`,
+    evidenceTitle: "Чем доказан этот диф",
+    evidenceUncovered: "ни одна проверка не назвала этот файл",
+    evidenceBase: "база сравнения",
+    evidenceHash: "отпечаток доказательства",
+    evidenceBadRef: (r) => `ссылка «${r}» не разобрана — покрытие не считано`,
+    evidenceNoFiles: (r) => `файлов кода в дифе с «${r}» нет — доказывать нечего`,
+    evidenceWarn:
+      "◻️ означает: проверка обошла каталог и ничего не сказала. «Просмотрен и чист» и «не " +
+      "просмотрен вовсе» по выводу неразличимы — и выдавать одно за другое нельзя ни в ту, ни " +
+      "в другую сторону. " +
+      "Отпечаток считается по базе, набору команд и содержимому файлов. Изменилось что-то из " +
+      "этого — отчёт устарел, и «прогнал, потом поправил ещё три файла» перестаёт быть " +
+      "неотличимым от «прогнал». Механизм взят у donecheck (MIT).",
+    title: "Отчёт AQK",
+    noManifest: (cmd) => `Нет .aqk.yml — отчитываться не о чем. Начни с ${cmd}`,
+    level: "Уровень",
+    holdsTitle: "Что держит машина (прогон, а не манифест)",
+    nothingRuns: "⬜ ни один гейт не объявлен",
+    native: (prog) => `родной рецепт: ${prog}`,
+    portable: "переносимая проверка",
+    weakerTitle: "Стоит слабее возможного",
+    weaker: (progs) => `в системе есть ${progs}, но гейт стоит на переносимой проверке — она ловит меньше`,
+    missingTitle: "Чего нет",
+    nothingMissing: "✅ все применимые записи поставлены",
+    needsTool: (prog) => `нужен ${prog} — его нет в системе`,
+    notInstalled: "применимо, но не поставлено",
+    hiddenTitle: "Не применимо к этому репозиторию",
+    readTitle: "Что комплект велел прочитать",
+    readWarn:
+      "Значок означает только наличие файла на диске. Прочитан он или нет, машина не знает и " +
+      "не притворяется, что знает: это отвечает тот, кто отчитывается.",
+    ignoreTitle: "Что спрятано .aqkignore",
+    ignoreNone: "файла .aqkignore нет — ничего не спрятано",
+    ignoreWarn:
+      "Скрытое молча — тот же класс, что молчащий гейт: гейты по этим путям не смотрят вовсе. " +
+      "Строка здесь означает, что защиты там нет и не будет.",
+    whyTitle: "Зачем это нужно — коротко",
+    whyNothing: "нечего добавлять: применимое уже стоит",
+    saved: (path) => `Сохранено: ${path}`,
+    docs: {
+      baseline: "обязательный минимум проекта, без привязки к языку",
+      readyMade: "карта готовых правил: сперва ищи готовое, потом пиши своё",
+      rulesGeneral: "общие правила работы",
+      rulesTesting: "правила про тесты",
+      rulesSecurity: "правила про безопасность",
+    },
+  },
+  manifestDoc: {
+    head: [
+      "# .aqk.yml — манифест Agent Quality Kit",
+      "# Что это: машиночитаемое описание того, как в этом репозитории живут агенты.",
+      "# Уровень соответствия считает `aqk doctor`. Пустое поле = ступень не пройдена,",
+      "# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.",
+    ],
+    entry: "# AQK-0 — что агент читает первым.",
+    rules: "# AQK-1 — где стандарты и какие проверки обязательны. docs — где методички:\n# оба пути читает doctor, так что комплект можно разложить куда угодно.",
+    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 };