agent-quality-kit 0.5.0 → 0.7.0

package/llms.txt

@@ -22,11 +22,12 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
   `npx agent-quality-kit doctor --baseline` (14 of 50 points confirmed by a run, ecosystem-neutral;
   the other 36 are named as a number, not hidden)
 - Fail a pipeline below a level or on a failed gate: `npx agent-quality-kit doctor --run --min 1`
+- Show only what a diff introduced, so a legacy repo is usable from day one: `doctor --run --since main`
 - Exit codes: 0 pass, 1 below the level or a gate failed
 - As a pre-commit hook: `repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit` with
   `id: aqk` (blocking), `aqk-doctor` (read-only) or `aqk-baseline`. pre-commit installs the
   package itself; there are no dependencies to pull in.
-- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.4.2` with `min: 1`
+- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.7.0` with `min: 1`
   (https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ## What makes it different

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Turns the rules an agent is supposed to follow into commands with exit codes, and reports which of them actually run. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -43,7 +43,9 @@
   ],
   "knip": {
     "entry": [
-      "tool/selfcheck/units.mjs"
+      "tool/selfcheck/units.mjs",
+      "tool/selfcheck/units-level.mjs",
+      "tool/selfcheck/lifecycle.mjs"
     ],
     "project": [
       "tool/**/*.mjs"

package/tool/commands/badge.mjs

@@ -9,6 +9,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CWD, SELF, REPO_URL, c, exists, die } from "../lib/core.mjs";
 import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { proveGates } from "../lib/prove.mjs";
 import { runGates, declaredGates } from "./doctor.mjs";
 import { L } from "../i18n/index.mjs";
 
@@ -33,7 +34,12 @@ async function cmdBadge(args = []) {
   const man = await readManifest();
   if (!man) die(`\n  ${L.badge.noManifest(`${SELF} init`)}\n`);
 
-  const { reached } = await assessLevel(man);
+  // Значок — самое громкое утверждение комплекта, и доказывать его обязательно. Без этого
+  // проект с гейтом «true» получал AQK-3 и зелёную картинку в README: проверено прогоном.
+  // Сказать вслух, что идёт: доказательство гоняет каждый гейт по двум образцам, и молчащая
+  // пауза читается как зависание. Найдено код-ревью 2026-09-07.
+  console.log(c.dim(`  ${L.prove.running}`));
+  const { reached } = await assessLevel(man, await proveGates(man));
   if (reached < 0) die(`\n  ${L.badge.notReached(`${SELF} doctor`)}\n`);
 
   // Прогон, а не манифест. Значок при красном гейте — это и есть недоказанное утверждение.

package/tool/commands/doctor.mjs

@@ -3,8 +3,10 @@
 import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists } from "../lib/core.mjs";
-import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS } from "../lib/manifest.mjs";
+import { scopeOutput, splitAdvice, changedFiles } from "../lib/scope.mjs";
+import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists, die } from "../lib/core.mjs";
+import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS, advisorySet } from "../lib/manifest.mjs";
+import { proveGates } from "../lib/prove.mjs";
 import { detectFacts, readCatalog, triggerVerdict, recipeFor } from "../lib/repo.mjs";
 import { assessBaseline, DEP_FILES, BASELINE_TOTAL } from "../lib/baseline.mjs";
 import { L } from "../i18n/index.mjs";
@@ -94,9 +96,27 @@ function declaredGates(man) {
     .filter(([, cmd]) => cmd);
 }
 
-function runGates(man) {
+// Ссылка, относительно которой сужается вывод: `--since main`, `--since HEAD~5`.
+// Без значения флаг бессмыслен — молча взять умолчание нельзя: «сужено не тем» неотличимо
+// от «не сужено».
+function sinceRef(argv = process.argv) {
+  const i = argv.indexOf("--since");
+  if (i === -1) return null;
+  const v = argv[i + 1];
+  return v && !v.startsWith("-") ? v : null;
+}
+
+function runGates(man, opts = {}) {
   const gates = declaredGates(man);
   if (!gates.length) return { failed: 0, ran: 0, results: [] };
+  const advisory = advisorySet(man);
+
+  // Сужение по дифу — договор с человеком, и он должен видеть, ЧТО именно сужено. Пустой диф
+  // называется вслух: иначе «все гейты зелёные» означало бы «сравнили не с тем» и читалось бы
+  // как успех. Это тот же класс, что и весь стандарт, только внутри нашего флага.
+  const scoped = opts.since ? changedFiles(opts.since, CWD) : null;
+  if (opts.since && scoped === null) die(L.doctor.sinceBadRef(opts.since));
+  if (scoped) console.log(c.dim(`\n  ${L.doctor.sinceHeading(opts.since, scoped.size)}`));
 
   console.log(c.bold(`\n  ${L.doctor.runHeading}\n`));
   let failed = 0;
@@ -116,17 +136,69 @@ function runGates(man) {
     const code = r.status;
     if (code === 0) {
       console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${cmd}`)}`);
+      // Зелёный гейт иногда всё-таки говорит человеку что-то важное: храповик, дошедший до цели,
+      // просит убрать обёртку. Вывод успешного гейта не показывался вовсе, и это сообщение
+      // уходило в никуда — тот же класс, что обрезанный совет у красного, только тише.
+      // Показываем ровно строки с меткой совета: остальной вывод успешной проверки — шум.
+      const okAdvice = splitAdvice(`${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean)).advice;
+      for (const line of okAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
       results.push({ name, cmd, ok: true, secs });
     } else {
+      const raw = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
+      // Совет отделяется ДО сужения. Иначе он сам попадает под фильтр по путям: сообщение
+      // храповика про вышедший срок называет путь к реестру, реестра в дифе нет, и гейт,
+      // обязанный краснеть по сроку, печатался зелёным с пометкой «находки вне дифа».
+      // Ровно то, что стандарт запрещает: срок без последствия. Найдено ревью 2026-09-06.
+      const parted = splitAdvice(raw);
+      let out = parted.findings;
+      const alwaysAdvice = parted.advice;
+
+      // Сужение до дифа. Три исхода, и все три называются вслух.
+      if (scoped) {
+        const s = scopeOutput(out, scoped);
+        // Гейт, у которого находок нет вовсе, а есть только совет, сузить нечем: его вердикт
+        // не про файлы. Признать такой успешным — вернуть ту же тишину другим путём.
+        if (!s.scopable || out.length === 0) {
+          // Гейт печатает вердикт без путей — сузить нечем. Признать его успешным значило бы
+          // выдать провал за тишину; остаётся красным, и причина названа.
+          console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${L.doctor.notScopable}`)}`);
+          failed++;
+          results.push({ name, cmd, ok: false, secs, code, note: L.doctor.notScopable });
+          continue;
+        }
+        if (s.findings === 0) {
+          // Долг есть, но не в том, что внёс диф. Зелёный — но с числом спрятанного: молчаливое
+          // «всё хорошо» здесь было бы неправдой.
+          console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${L.doctor.outsideDiff(out.length)}`)}`);
+          results.push({ name, cmd, ok: true, secs, scopedAway: out.length });
+          continue;
+        }
+        out = s.kept;
+      }
+
       failed++;
-      const out = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
-      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${secs}s · ${cmd}`)}`);
+      // Находки обрезаются, совет — никогда. Все записи каталога печатают «почини: …» последней
+      // строкой, и при обрезке до трёх строк человек не видел именно её: находка без действия
+      // закрывает окно, а не дефект.
+      // Совещательный гейт показывает находки и не роняет прогон. Знак другой, чтобы «показано»
+      // и «провалено» не читались одинаково; в сводке ниже он назван поимённо.
+      const isAdvisory = advisory.has(name);
+      if (isAdvisory) failed--;
+      const mark = isAdvisory ? c.yellow("!") : c.red("✘");
+      const verdict = isAdvisory ? c.yellow(L.doctor.advisoryMark) : c.red(L.doctor.exitCode(code));
+      console.log(`  ${mark}  ${name.padEnd(14)} ${verdict} ${c.dim(`· ${secs}s · ${cmd}`)}`);
       for (const line of out.slice(0, 3)) console.log(c.dim(`        ${line.slice(0, 100)}`));
       if (out.length > 3) console.log(c.dim(`        ${L.doctor.moreLines(out.length - 3)}`));
-      results.push({ name, cmd, ok: false, secs, code });
+      // Совет тоже не бесконечен: гейт, зовущий помощник шесть раз, печатает его шесть раз.
+      for (const line of alwaysAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
+      results.push({ name, cmd, ok: false, secs, code, advisory: isAdvisory });
     }
   }
-  return { failed, ran: gates.length, results };
+  // Совещательные, которые покраснели, называются вслух ВСЕГДА. Молчание о них — ровно та
+  // тишина, против которой построен стандарт: проверка выключена, а выглядит как её отсутствие.
+  const advisoryFailed = results.filter((x) => x.advisory).map((x) => x.name);
+  if (advisoryFailed.length) console.log(`\n  ${c.yellow(L.doctor.advisorySummary(advisoryFailed))}`);
+  return { failed, ran: gates.length, results, advisoryFailed };
 }
 
 // Короткий отчёт «что из этого реально брали» — не для человека, а для агента в следующей
@@ -203,12 +275,20 @@ async function cmdDoctor() {
     console.log(c.dim(`  ${L.doctor.manifestKnown(KNOWN_KEYS)}\n`));
   }
 
-  const { reached, steps } = await assessLevel(man);
+  // Доказательство считается только при прогоне: узнать, ловит ли гейт брак, нельзя иначе как
+  // запустив его по образцу. Без прогона ступени со второй помечаются «не доказано» — это
+  // честнее, чем показывать их выполненными по наличию папок.
+  const proof = process.argv.includes("--run") ? await proveGates(man) : null;
+  const { reached, steps } = await assessLevel(man, proof);
 
   console.log(c.bold(`\n  ${L.doctor.levelHeading}\n`));
   for (const s of steps) {
     const mark = s.ok ? c.green("✔") : reached + 1 === s.level ? c.yellow("→") : c.dim("·");
-    console.log(`  ${mark}  AQK-${s.level}  ${s.title}`);
+    const note = !s.ok && s.needsProof ? c.dim(`  · ${L.doctor.levelUnproven(`${SELF} prove`)}`) : "";
+    console.log(`  ${mark}  AQK-${s.level}  ${s.title}${note}`);
+  }
+  if (proof && proof.broken) {
+    console.log(c.red(`\n  ${L.doctor.gatesDoNotCatch(proof.broken, `${SELF} prove`)}`));
   }
 
   const next = steps.find((s) => !s.ok);
@@ -247,7 +327,7 @@ async function cmdDoctor() {
   let gateFailed = 0;
   let failedNames = [];
   if (wantRun) {
-    const run = runGates(man);
+    const run = runGates(man, { since: sinceRef() });
     gateFailed = run.failed;
     failedNames = run.results.filter((r) => !r.ok).map((r) => r.name);
     await writeRunReport({ version, reached, results: run.results });

package/tool/commands/gates.mjs

@@ -8,7 +8,7 @@ import {
   CWD, PKG_ROOT, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB, MANIFEST, SELF, c, exists, die,
   copyDir,
 } from "../lib/core.mjs";
-import { parseManifest, readManifest, manifestWithGate } from "../lib/manifest.mjs";
+import { parseManifest, readManifest, manifestWithGate, entryLifecycle } from "../lib/manifest.mjs";
 import {
   detectFacts, readCatalog, pickRecipe, triggerVerdict, stems, overlap, matchCatalog,
 } from "../lib/repo.mjs";
@@ -28,6 +28,13 @@ async function installGate(slug, man, facts) {
   if (!(await exists(src))) die(L.add.noSuchGate(slug, `${SELF} doctor`));
 
   const rec = { slug, ...parseManifest(await readFile(join(src, "gate.yml"), "utf8")) };
+
+  // Выведенную запись не ставим. Молча пропустить нельзя — человек пришёл за конкретной
+  // проверкой и обязан узнать, кто её заменил; ответ «а что теперь» и есть цена вывода.
+  // Проверка ДО копирования: иначе в проекте остаётся папка гейта, которого не будет в манифесте.
+  const life = entryLifecycle(rec);
+  if (life.state === "deprecated") return { rec, cmd: null, copied: [], declared: false, why: null, retired: life.supersededBy || "" };
+
   const dst = join(CWD, PROJECT_GATES, slug);
   await mkdir(dst, { recursive: true });
   const copied = await copyDir(src, dst, { force: false });
@@ -40,7 +47,8 @@ async function installGate(slug, man, facts) {
   }
 
   // Команда под стек проекта, с путями внутри репозитория, а не внутри пакета.
-  const picked = String(pickRecipe(rec, facts) || "");
+  const missing = [];
+  const picked = String(pickRecipe(rec, facts, missing) || "");
   let cmd = picked
     .replace(/\{gate\}/g, `${PROJECT_GATES}/${slug}`)
     .replace(/\{dir\}/g, ".");
@@ -50,7 +58,7 @@ async function installGate(slug, man, facts) {
   // ни `ruff`, ни `vulture`, и установка обрывалась на записи `dead-code`, которой нужен
   // настоящий инструмент. Отсутствие сигнала неотличимо от успеха — здесь оно было внутри
   // самой установки.
-  if (!cmd) return { rec, cmd: null, copied, declared: false, why: null, noRecipe: true };
+  if (!cmd) return { rec, cmd: null, copied, declared: false, why: null, noRecipe: true, missing };
 
   // Родной инструмент не знает про наши образцы и выдаёт их как находки — в любом проекте,
   // куда поставили гейты. Заворачиваем его в общий фильтр. Переносимая проверка фильтрует
@@ -87,8 +95,14 @@ async function cmdAdd(args) {
     console.log(c.dim(`  ${L.add.installAnyway}\n`));
   }
 
-  const { cmd, copied, declared, why, noRecipe } = await installGate(slug, man, facts);
-  if (noRecipe) die(L.add.noRecipe(slug, [...facts.langs].join("/") || L.add.thisStack));
+  const { cmd, copied, declared, why, noRecipe, retired, missing } = await installGate(slug, man, facts);
+  if (retired !== undefined) die(L.lifecycle.installDeprecated(slug, retired ? `${SELF} add ${retired}` : "—"));
+  // «Рецепта нет» и «рецепт есть, а инструмента нет» — разные причины и разные починки.
+  // Диагноз, противоречащий gate.yml, стоит доверия всему выводу. Найдено код-ревью 2026-09-07.
+  if (noRecipe) {
+    if (missing && missing.length) die(L.add.toolMissing(slug, missing));
+    die(L.add.noRecipe(slug, [...facts.langs].join("/") || L.add.thisStack, missing));
+  }
 
   console.log(c.bold(`\naqk add ${slug}\n`));
   console.log(`  ${c.green("✔")}  ${PROJECT_GATES}/${slug}/  ${c.dim(L.add.copied(copied.length))}`);

package/tool/commands/project.mjs

@@ -11,7 +11,7 @@ import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
 import { readManifest } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
 import { installGate } from "./gates.mjs";
-import { L } from "../i18n/index.mjs";
+import { L, LANG } from "../i18n/index.mjs";
 
 async function cmdInit(args) {
   const force = args.includes("--force");
@@ -46,6 +46,13 @@ async function cmdInit(args) {
     for (const f of created.slice(0, 8)) console.log(`    ${f}`);
     if (created.length > 8) console.log(c.dim(`    ${L.init.andMore(created.length - 8)}`));
   }
+  // Методички остаются на русском — решение владельца, принятое 2026-09-07, а не недоделка.
+  // Сказать об этом обязательно: человек, открывший `.aqk/docs/` и увидевший чужой язык, иначе
+  // решит, что установка сломалась. Правила переведены, методички нет; молчать об этом значит
+  // выдать решение за оплошность.
+  if (LANG === "en" && created.some((f) => f.includes(`${TARGET_DIR}/docs/`) || f.includes(`${TARGET_DIR}\\docs\\`))) {
+    console.log(c.dim(`\n  ${L.init.docsRu}`));
+  }
   if (skipped.length) {
     console.log(c.yellow(`\n  ${L.init.kept(skipped.length)}`));
     for (const f of skipped) console.log(`    ${f}`);
@@ -267,7 +274,13 @@ async function cmdStart(args) {
       if (declared.has(rec.slug)) continue;
       const v = triggerVerdict(rec, facts0);
       if (!v.applies) { skipped.push([rec.slug, v.why]); continue; }
-      const { cmd, noRecipe } = await installGate(rec.slug, man, facts0);
+      const { cmd, noRecipe, retired } = await installGate(rec.slug, man, facts0);
+      // Выведенная запись в пачку не идёт, но и молчать о ней нельзя: она попадает в тот же
+      // список пропущенного с названным преемником.
+      if (retired !== undefined) {
+        skipped.push([rec.slug, L.lifecycle.installDeprecated(rec.slug, retired || "—")]);
+        declared.add(rec.slug); continue;
+      }
       // Записи, которой нужен инструмент, а его на машине нет, здесь не место — но и вся
       // установка из-за неё останавливаться не должна. Причина называется вслух и попадает
       // в тот же список пропущенного, что и записи, не подошедшие по триггеру.

package/tool/commands/prove.mjs

@@ -0,0 +1,67 @@
+// tool/commands/prove.mjs — `aqk prove`: доказать, что гейты проекта ловят брак.
+//
+// Отдельная команда, а не флаг: вопрос «работают ли мои проверки» задают сам по себе, и ответ
+// на него нужен раньше, чем прогон по коду. Прогон говорит «сегодня чисто»; доказательство —
+// «а если бы было грязно, я бы это увидел».
+import { readManifest } from "../lib/manifest.mjs";
+import { proveGates } from "../lib/prove.mjs";
+import { c, SELF } from "../lib/core.mjs";
+import { L } from "../i18n/index.mjs";
+
+function line(r) {
+  const P = L.prove;
+  const pad = r.name.padEnd(22);
+  if (r.state === "proven") return `  ${c.green("✔")}  ${pad} ${c.dim(P.okRed)}`;
+  if (r.state === "unprovable") {
+    const why =
+      r.why === "no-samples" ? P.noSamples
+      : r.why === "other-recipe" ? P.otherRecipe(r.forRecipe.lang)
+      : r.why === "no-target" ? P.noTarget
+      : P.empty;
+    return `  ${c.dim("~")}  ${c.dim(pad)} ${c.dim(why)}`;
+  }
+  const why = r.why === "red-passed" ? P.redPassed : r.why === "green-failed" ? P.greenFailed : P.empty;
+  return `  ${c.red("✘")}  ${pad} ${c.red(why)}`;
+}
+
+async function cmdProve() {
+  const man = await readManifest();
+  const P = L.prove;
+  console.log(c.bold(`\n${P.title}\n`));
+
+  // «Манифеста нет» и «гейтов не объявлено» — разные причины и разные починки. Остальные
+  // команды это различают; здесь не различалось. Найдено код-ревью 2026-09-07.
+  if (!man) {
+    console.log(`  ${c.red(L.ratchet.noManifest(`${SELF} init`))}\n`);
+    process.exit(1);
+  }
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  if (!Object.keys(gates).length) {
+    console.log(`  ${P.noGates}\n`);
+    process.exit(1);
+  }
+  if (!String(man?.samples || "").trim()) {
+    console.log(`  ${c.red(P.noSamplesDir)}\n`);
+    process.exit(1);
+  }
+
+  const res = await proveGates(man);
+  // Сначала сломанные: красное называется первым, иначе его не читают.
+  for (const r of res.results.filter((x) => x.state === "broken")) console.log(line(r));
+  for (const r of res.results.filter((x) => x.state === "proven")) console.log(line(r));
+  for (const r of res.results.filter((x) => x.state === "unprovable")) console.log(line(r));
+
+  const parts = [c.green(P.proven(res.proven))];
+  if (res.broken) parts.push(c.red(P.broken(res.broken)));
+  if (res.unprovable) parts.push(c.dim(P.unprovable(res.unprovable)));
+  console.log(`\n  ${parts.join("  ")}`);
+
+  if (!res.ok && res.proven === 0 && res.broken === 0) {
+    console.log(`\n  ${c.yellow(P.nothingProven)}`);
+    console.log(`  ${c.dim(P.fix(`${SELF} add ${L.help.name}`))}`);
+  }
+  console.log("");
+  process.exit(res.ok ? 0 : 1);
+}
+
+export { cmdProve };

package/tool/commands/report.mjs

@@ -17,6 +17,7 @@ import { mkdir, writeFile, readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { CWD, TARGET_DIR, SELF, c, exists, docPath } from "../lib/core.mjs";
 import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { proveGates } from "../lib/prove.mjs";
 import { detectFacts, readCatalog, triggerVerdict, whichSync } from "../lib/repo.mjs";
 import { runGates, declaredGates } from "./doctor.mjs";
 import { L } from "../i18n/index.mjs";
@@ -73,7 +74,9 @@ async function cmdReport() {
     process.exit(1);
   }
 
-  const { reached } = await assessLevel(man);
+  // Значок — самое громкое утверждение комплекта, и доказывать его обязательно. Без этого
+  // проект с гейтом «true» получал AQK-3 и зелёную картинку в README: проверено прогоном.
+  const { reached } = await assessLevel(man, await proveGates(man));
   const facts = await detectFacts(man);
   const catalog = await readCatalog();
   const bySlug = Object.fromEntries(catalog.map((r) => [r.slug, r]));

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 };