agent-quality-kit 0.2.4 → 0.3.0

package/tool/commands/project.mjs

@@ -5,13 +5,14 @@ import { readdir, mkdir, writeFile, readFile } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import { join, dirname, relative } from "node:path";
 import {
-  CWD, PKG_ROOT, DOCS_SRC, RULES_SRC, TARGET_DIR, MANIFEST, SELF, REPO, c, exists, die,
+  CWD, PKG_ROOT, DOCS_SRC, RULES_SRC, TARGET_DIR, MANIFEST, SELF, REPO_URL, c, exists, die,
   copyDir, writeIfAbsent, FEEDBACK_MARK,
 } from "../lib/core.mjs";
 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";
 
 async function cmdInit(args) {
   const force = args.includes("--force");
@@ -21,7 +22,7 @@ async function cmdInit(args) {
   const track = (ok, path) => (ok ? created : skipped).push(relative(CWD, path));
 
   if (!(await exists(DOCS_SRC))) {
-    die(`Не найден корпус методичек: ${DOCS_SRC}\nПохоже, пакет установлен не полностью.`);
+    die(L.init.noDocs(DOCS_SRC));
   }
 
   const refs = await copyDir(DOCS_SRC, join(CWD, TARGET_DIR, "docs"), { force });
@@ -42,14 +43,14 @@ async function cmdInit(args) {
 
   console.log(c.bold("\naqk init\n"));
   if (created.length) {
-    console.log(c.green(`  создано (${created.length}):`));
+    console.log(c.green(`  ${L.init.created(created.length)}`));
     for (const f of created.slice(0, 8)) console.log(`    ${f}`);
-    if (created.length > 8) console.log(c.dim(`    … и ещё ${created.length - 8}`));
+    if (created.length > 8) console.log(c.dim(`    ${L.init.andMore(created.length - 8)}`));
   }
   if (skipped.length) {
-    console.log(c.yellow(`\n  уже были на месте, не тронуты (${skipped.length}):`));
+    console.log(c.yellow(`\n  ${L.init.kept(skipped.length)}`));
     for (const f of skipped) console.log(`    ${f}`);
-    console.log(c.dim(`  перезаписать: ${SELF} init --force`));
+    console.log(c.dim(`  ${L.init.overwrite(`${SELF} init --force`)}`));
   }
 
   // Путь ищем, а не пишем: раскладка внутри .aqk — дело владельца комплекта, и жёстко
@@ -58,18 +59,18 @@ async function cmdInit(args) {
   for (const f of created) if (f.endsWith("project-baseline.md")) baseline = f;
 
   console.log(`
-${c.bold("Что дальше — по порядку:")}
-
-  1. Открой ${c.bold("AGENTS.md")} и заполни раздел «Команды». Команда, которую нельзя
-     скопировать и выполнить, — не команда, а пожелание.
-  2. Прочитай ${c.bold(baseline)} — это обязательный минимум
-     проекта без привязки к языку. Пройди сверху вниз и отметь, чего нет.
-  3. Заполни ${c.bold(".aqk.yml")} — гейты, образцы, журнал. Уровень соответствия AQK
-     считается по нему: ${c.bold(`${SELF} doctor`)}.
-  4. Поднимайся по ступеням ${c.bold("по одной")}. Гейт стережёт существующий артефакт:
-     проверка на код, которого ещё нет, — мёртвое правило.
-
-${c.dim(`Обжёгся на чём-то — запиши: ${SELF} note "что случилось"`)}
+${c.bold(L.init.nextTitle)}
+
+  1. ${L.init.n1a} ${c.bold("AGENTS.md")} ${L.init.n1b}
+     ${L.init.n1c}
+  2. ${L.init.n2a} ${c.bold(baseline)} ${L.init.n2b}
+     ${L.init.n2c}
+  3. ${L.init.n3a} ${c.bold(".aqk.yml")} ${L.init.n3b}
+     ${L.init.n3c(c.bold(`${SELF} doctor`))}
+  4. ${L.init.n4a} ${c.bold(L.init.n4b)}${L.init.n4c}
+     ${L.init.n4d}
+
+${c.dim(L.init.burned(`${SELF} note "…"`))}
 `);
   await maybeAskFeedback();
 }
@@ -80,13 +81,13 @@ ${c.dim(`Обжёгся на чём-то — запиши: ${SELF} note "что
 // звезды, но без звезды меньше шансов, что кто-то вообще дойдёт до фидбека.
 async function maybeAskFeedback() {
   if (await exists(FEEDBACK_MARK)) return;
-  const url = `https://github.com/${REPO.replace(/^github:/, "")}`;
+  const url = REPO_URL;
   console.log(`
-${c.bold("Если пригодилось:")}
-  Поставь звезду — ${url}
-  Нашёл баг или не подошло — заведи Issue, самая полезная обратная связь: и то и другое.
+${c.bold(L.feedback.title)}
+  ${L.feedback.star(url)}
+  ${L.feedback.issue}
     ${url}/issues/new
-${c.dim("  Это разовое сообщение: больше не покажется на этой машине.")}
+${c.dim(`  ${L.feedback.once}`)}
 `);
   await writeIfAbsent(FEEDBACK_MARK, "shown\n", { force: false });
 }
@@ -107,19 +108,34 @@ function findJournal() {
 
 async function cmdNote(args) {
   const title = args.find((a) => !a.startsWith("--"));
-  if (!title) die(`Нужен заголовок: ${SELF} note "что произошло"`);
+  if (!title) die(L.note.needTitle(`${SELF} note "…"`));
+
+  // Сначала журнал ЭТОГО проекта: `lessons:` в манифесте — это и есть ответ на вопрос «куда
+  // складывать уроки», данный владельцем репозитория. Пока команда его игнорировала, она
+  // требовала клон нашего репозитория и писала урок туда — то есть в чужой проект. Найдено
+  // первым же чужим прогоном: человек завёл журнал руками, потому что команда не сработала.
+  const man = await readManifest();
+  const own = String(man?.lessons || "").trim();
+  let home = null;
+  let journal = null;
+  if (own && !/^https?:/i.test(own)) {
+    const dir = join(CWD, own);
+    if (await exists(dir)) {
+      home = CWD;
+      journal = join(dir, "README.md");
+      // Журнал объявлен, но файла нет — заводим, а не отказываем: пустой журнал это норма
+      // первого дня, и отказ на нём отучает пользоваться командой.
+      if (!(await exists(journal))) await writeFile(journal, `# ${L.note.journalTitle}\n`, "utf8");
+    }
+  }
 
-  const home = findJournal();
   if (!home) {
-    die(`Клон журнала не найден.
-Сделай один раз:
-  git clone https://github.com/arsen-ask-lx/Agent_Quality_Kit.git ~/projects/aqk
-или укажи путь: export AQK_HOME=/путь/к/aqk`);
+    home = findJournal();
+    if (!home) die(L.note.noJournal(REPO_URL));
+    journal = join(home, "incidents", "README.md");
+    if (!(await exists(journal))) die(L.note.journalMissing(journal));
   }
 
-  const journal = join(home, "incidents", "README.md");
-  if (!(await exists(journal))) die(`Журнал не найден: ${journal}`);
-
   let body = "";
   if (!process.stdin.isTTY) {
     body = await new Promise((res) => {
@@ -131,14 +147,7 @@ async function cmdNote(args) {
   }
 
   if (!body.trim()) {
-    die(`Тело записи пустое. Передай его на стандартный ввод, например:
-
-  aqk note "заголовок" <<'EOF'
-  **Класс:** гейт молчал
-  **Что случилось.** ...
-  **Чем это стоило.** ...
-  **Вывод.** 🔧 ...
-  EOF`);
+    die(L.note.emptyBody);
   }
 
   // ГЕЙТ. Урок без вывода — это история, а не урок: в следующий раз обожжёмся так же.
@@ -146,18 +155,12 @@ async function cmdNote(args) {
   // тексте не значит вывод, если рядом нет одной из трёх настоящих отметок. Запись проходила бы
   // здесь и тут же краснела на doctor --run — разные требования в двух местах одного правила.
   if (!/[✅🔧📜👤]/.test(body)) {
-    die(
-      "В записи нет отметки решения. Урок без вывода — это история, а не урок.\n" +
-        "Припиши одну из трёх:\n" +
-        "  ✅ **Стало гейтом:** <имя записи каталога>\n" +
-        "  🔧 **Стало правкой оснастки:** <что именно изменено>\n" +
-        "  👤 **Гейтом не станет:** <почему>"
-    );
+    die(L.note.noOutcome);
   }
 
   const date = new Date().toISOString().slice(0, 10);
-  const project = CWD.split("/").filter(Boolean).pop() || "неизвестно";
-  const entry = `\n## ${date} — ${title}\n\n**Проект:** ${project}\n\n${body.trim()}\n`;
+  const project = CWD.split("/").filter(Boolean).pop() || L.note.unknownProject;
+  const entry = `\n## ${date} — ${title}\n\n**${L.note.projectField}:** ${project}\n\n${body.trim()}\n`;
 
   const prev = await readFile(journal, "utf8");
   await writeFile(journal, prev + entry, "utf8");
@@ -168,8 +171,8 @@ async function cmdNote(args) {
   const pushed = run("push", "-q");
   console.log(
     pushed.status === 0
-      ? c.green(`Записано и отправлено: ${title}`)
-      : c.yellow(`Записано локально, push не прошёл. Отправить: git -C ${home} push`)
+      ? c.green(L.note.pushed(title))
+      : c.yellow(L.note.localOnly(`git -C ${home} push`))
   );
 }
 
@@ -179,13 +182,10 @@ async function cmdNote(args) {
 
 async function cmdBlob() {
   const dir = join(PKG_ROOT, "kit", "docs");
-  if (!(await exists(dir))) die(`Не найдены методички: ${dir}`);
+  if (!(await exists(dir))) die(L.blob.noDocs(dir));
 
   const stamp = new Date().toISOString().slice(0, 10);
-  let out =
-    `<!-- СОБРАНО КОМАНДОЙ aqk blob ${stamp} из kit/docs. Не править руками:\n` +
-    `     правки затрёт следующая сборка. Источник — отдельные файлы. -->\n\n` +
-    `# AQK — методички одним файлом\n`;
+  let out = L.blob.header(stamp);
 
   // Методички могут лежать в подпапках — обходим дерево, порядок стабильный.
   const found = [];
@@ -199,7 +199,7 @@ async function cmdBlob() {
   await walk(dir);
 
   for (const full of found) {
-    out += `\n\n${"=".repeat(78)}\n<!-- источник: ${relative(PKG_ROOT, full)} -->\n${"=".repeat(78)}\n\n`;
+    out += `\n\n${"=".repeat(78)}\n<!-- ${L.blob.source(relative(PKG_ROOT, full))} -->\n${"=".repeat(78)}\n\n`;
     // Ссылки на соседние файлы в склейке ведут в никуда: соседей рядом больше нет,
     // все они внутри этого же текста. Оставляем подпись, снимаем разметку.
     const body = (await readFile(full, "utf8")).replace(
@@ -212,10 +212,9 @@ async function cmdBlob() {
   const dst = join(CWD, "GOD_AI.md");
   await writeFile(dst, out, "utf8");
   console.log(
-    `\n  ${c.green("✔")}  GOD_AI.md — ${found.length} файлов, ` +
-      `${Math.round(Buffer.byteLength(out) / 1024)} КБ\n`
+    `\n  ${c.green("✔")}  ${L.blob.done(found.length, Math.round(Buffer.byteLength(out) / 1024))}\n`
   );
-  console.log(c.dim("  Собирается заново каждой командой. Править надо оригиналы в kit/docs.\n"));
+  console.log(c.dim(`  ${L.blob.rebuilt}\n`));
 }
 
 
@@ -234,19 +233,19 @@ async function cmdStart(args) {
   if (!man) {
     await cmdInit(args.filter((a) => a !== "--force"));
     man = await readManifest();
-    if (!man) die(`Не получилось разложить комплект. Начни с ${SELF} init`);
+    if (!man) die(L.start.initFailed(`${SELF} init`));
   }
 
   const facts = await detectFacts(man);
   console.log(c.bold("\naqk start\n"));
 
   if (facts.files > 30 && !force) {
-    console.log(c.yellow(`  В репозитории уже ${facts.files} файлов кода — это другой сценарий.\n`));
-    console.log(`  ${c.bold(`${SELF} doctor`)} осмотрит, что есть, и разделит записи на три списка:`);
-    console.log(c.dim("  держит машина · применимо и не поставлено · не применимо и почему.\n"));
-    console.log(c.dim(`  Всё равно поставить сторожей дня 0: ${SELF} start --force`));
-    console.log(c.dim("  Готовься к красному: сторож, поставленный на живой код, краснеет на нём весь."));
-    console.log(c.dim(`  Это лечится храповиком — ${SELF} ratchet <имя>, — а не отключением.\n`));
+    console.log(c.yellow(`  ${L.start.tooManyFiles(facts.files)}\n`));
+    console.log(`  ${L.start.useDoctor(c.bold(`${SELF} doctor`))}`);
+    console.log(c.dim(`  ${L.start.threeLists}\n`));
+    console.log(c.dim(`  ${L.start.anyway(`${SELF} start --force`)}`));
+    console.log(c.dim(`  ${L.start.expectRed}`));
+    console.log(c.dim(`  ${L.start.expectRedFix(`${SELF} ratchet ${L.help.name}`)}\n`));
     return;
   }
 
@@ -280,35 +279,35 @@ async function cmdStart(args) {
   }
 
   if (put.length) {
-    console.log(c.green(`  Поставлено сторожей дня 0: ${put.length}\n`));
+    console.log(c.green(`  ${L.start.installed(put.length)}\n`));
     for (const [slug, , intent] of put) console.log(`  ${c.green("✔")}  ${slug.padEnd(22)} ${c.dim(intent)}`);
-    console.log(c.dim("\n  Долга нет: на пустом проекте им нечего пропускать. Тот же сторож, поставленный"));
-    console.log(c.dim("  через полгода, покраснел бы на всём старом коде — и его бы выключили.\n"));
+    console.log(c.dim(`\n  ${L.start.noDebt1}`));
+    console.log(c.dim(`  ${L.start.noDebt2}\n`));
   } else {
-    console.log(c.dim("  Все применимые записи уже объявлены.\n"));
+    console.log(c.dim(`  ${L.start.allDeclared}\n`));
   }
   if (skipped.length) {
-    console.log(c.dim("  Не применимо пока:"));
+    console.log(c.dim(`  ${L.start.notYet}`));
     for (const [slug, why] of skipped.slice(0, 6)) console.log(c.dim(`    ${slug.padEnd(22)} ${why}`));
-    console.log(c.dim("  Появится признак — запись покажется сама.\n"));
+    console.log(c.dim(`  ${L.start.notYetWhy}\n`));
   }
 
   // --- порядок работы --------------------------------------------------------
-  console.log(`${c.bold("Порядок, в котором это делают:")}
+  console.log(`${c.bold(L.start.orderTitle)}
 
-  1. ${c.bold("Задача словами.")} Что и кому, без единого технического слова.
-     ${c.dim("Пока задача не описана словами, любая архитектура защищает неизвестно что.")}
-  2. ${c.bold("Ограничения.")} Сроки, деньги, нагрузка, чем нельзя пользоваться.
-     ${c.dim("Ограничения выбирают решение куда чаще, чем вкус: без них выбирают вкусом.")}
-  3. ${c.bold("Сайзинг.")} Сколько данных, запросов, людей — числами, хотя бы порядком.
-     ${c.dim("Число отделяет «нужна очередь» от «хватит таблицы». Без него спорят словами.")}
-  4. ${c.bold("Архитектура.")} И только теперь — из первых трёх, а не до них.
+  1. ${c.bold(L.start.o1)} ${L.start.o1What}
+     ${c.dim(L.start.o1Why)}
+  2. ${c.bold(L.start.o2)} ${L.start.o2What}
+     ${c.dim(L.start.o2Why)}
+  3. ${c.bold(L.start.o3)} ${L.start.o3What}
+     ${c.dim(L.start.o3Why)}
+  4. ${c.bold(L.start.o4)} ${L.start.o4What}
 
-  ${c.dim("Этот порядок программа не проверяет: он в .aqk/docs/, и агент может его")}
-  ${c.dim("проигнорировать. Машина держит другое — сторожей выше. Разница между")}
-  ${c.dim("мягким и жёстким тут ровно такая: текст просят, команду выполняют.")}
+  ${c.dim(L.start.softNote1)}
+  ${c.dim(L.start.softNote2)}
+  ${c.dim(L.start.softNote3)}
 
-${c.bold("Дальше:")}  ${c.bold(`${SELF} doctor --run`)}  ${c.dim("— прогнать всё, что объявлено")}
+${c.bold(L.start.next)}  ${c.bold(`${SELF} doctor --run`)}  ${c.dim(L.start.nextWhy)}
 `);
   await maybeAskFeedback();
 }

package/tool/commands/report.mjs

@@ -0,0 +1,194 @@
+// tool/commands/report.mjs — обязательная форма отчёта после работы с комплектом.
+//
+// ЗАЧЕМ ОТДЕЛЬНАЯ КОМАНДА, А НЕ ПРАВИЛО В ТЕКСТЕ. Первый чужой прогон дал отчёт, в котором
+// «12 гейтов зелёные» стояло рядом с тем фактом, что все 12 встали на слабейший рецепт, а
+// половина методичек, на которые указал сам `init`, не была прочитана. Агент не соврал — он
+// пересказал по памяти то, что счёл главным. Пересказ по памяти всегда выбирает удобное.
+//
+// Поэтому отчёт СОБИРАЕТСЯ ПРОГОНОМ. Всё, что в нём написано, — результат запуска здесь и
+// сейчас: какой рецепт реально выбран, что зелёное, что красное, что применимо и не стоит,
+// какие документы комплект велел прочитать и лежат ли они на диске.
+//
+// Чего команда НЕ умеет и не делает вид, что умеет: проверить, что документ прочитали.
+// Она печатает список — дальше отвечает человек или агент. Разница между «не прочитал» и
+// «прочитал и решил не применять» машине не видна, и притворяться иначе было бы враньём.
+
+import { mkdir, writeFile, readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { CWD, TARGET_DIR, SELF, c, exists } from "../lib/core.mjs";
+import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { detectFacts, readCatalog, triggerVerdict, whichSync } from "../lib/repo.mjs";
+import { runGates, declaredGates } from "./doctor.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Каким рецептом стоит гейт: родным инструментом или переносимой проверкой. Именно это
+// различие потерялось в первом чужом отчёте, и именно оно решает, что гейт на самом деле ловит.
+function recipeKind(cmd, rec) {
+  const recipes = rec?.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
+  const norm = (x) => String(x || "").replace(/\{gate\}|\{dir\}/g, "").replace(/\s+/g, " ").trim();
+  const c0 = norm(cmd);
+  for (const [lang, r] of Object.entries(recipes)) {
+    if (lang === "any") continue;
+    const prog = String(r).trim().split(/\s+/)[0];
+    if (c0.includes(norm(r)) || c0.startsWith(prog)) return { native: true, how: lang, prog };
+  }
+  // Родной рецепт есть в записи, но стоит переносимый — назвать это вслух: разница измерима.
+  const alt = Object.entries(recipes).filter(([k]) => k !== "any");
+  return { native: false, alternatives: alt.map(([lang, r]) => [lang, String(r).trim().split(/\s+/)[0]]) };
+}
+
+// Документы, на которые комплект указывает сам. Список не выдуман здесь: это те же файлы,
+// которые `init` кладёт в проект и на которые ссылается его же вывод.
+const REQUIRED_DOCS = [
+  ["project-baseline.md", "baseline"],
+  ["ready-made-rules.md", "readyMade"],
+  ["general.md", "rulesGeneral"],
+  ["testing.md", "rulesTesting"],
+  ["security.md", "rulesSecurity"],
+];
+
+// Путь ИЩЕМ, а не пишем. Жёстко вписанный `.aqk/docs/project-baseline.md` уже соврал в первой
+// же версии этой команды: файл лежит в подпапке `ai/`, и отчёт сообщил «не разложен» о том,
+// что разложено. Раскладка внутри .aqk — дело владельца комплекта, а не наше знание.
+async function findDoc(name) {
+  const root = join(CWD, TARGET_DIR);
+  if (!(await exists(root))) return null;
+  const walk = async (dir) => {
+    let entries = [];
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return null; }
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) { const hit = await walk(full); if (hit) return hit; }
+      else if (e.name === name) return relative(CWD, full);
+    }
+    return null;
+  };
+  return walk(root);
+}
+
+async function cmdReport() {
+  const man = await readManifest();
+  if (!man) {
+    console.log(c.red(`\n  ${L.report2.noManifest(`${SELF} init`)}\n`));
+    process.exit(1);
+  }
+
+  const { reached } = await assessLevel(man);
+  const facts = await detectFacts(man);
+  const catalog = await readCatalog();
+  const bySlug = Object.fromEntries(catalog.map((r) => [r.slug, r]));
+  const declared = declaredGates(man);
+
+  // Прогон, а не чтение манифеста: «объявлен» и «работает» — разные утверждения, и весь
+  // смысл этой команды в том, чтобы в отчёт попало второе.
+  const run = declared.length ? runGates(man) : { results: [], failed: 0 };
+
+  const held = [], broken = [], todo = [], skip = [];
+  for (const res of run.results) {
+    const rec = bySlug[res.name];
+    const kind = recipeKind(res.cmd, rec);
+    (res.ok ? held : broken).push({ ...res, kind, rec });
+  }
+  for (const rec of catalog) {
+    if (declared.some(([n]) => n === rec.slug)) continue;
+    const v = triggerVerdict(rec, facts);
+    if (!v.applies) { skip.push([rec, v.why]); continue; }
+    // Запись применима, но её родного инструмента нет — это другая причина, чем «не поставили».
+    const recipes = rec.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
+    const needs = recipes.any ? null : Object.values(recipes).map((r) => String(r).trim().split(/\s+/)[0]).find((prog) => !whichSync(prog));
+    todo.push([rec, needs]);
+  }
+
+  const lines = [];
+  const say = (s = "") => { lines.push(s); };
+
+  say(`# ${L.report2.title} — ${new Date().toISOString().slice(0, 16).replace("T", " ")}`);
+  say("");
+  say(`${L.report2.level}: AQK-${reached < 0 ? L.doctor.levelNone : reached}`);
+  say("");
+
+  say(`## ${L.report2.holdsTitle}`);
+  say("");
+  if (!held.length && !broken.length) say(`- ${L.report2.nothingRuns}`);
+  for (const g of held) {
+    const how = g.kind.native ? L.report2.native(g.kind.prog) : L.report2.portable;
+    say(`- ✅ ${g.name} — ${how}, ${g.secs}s`);
+  }
+  for (const g of broken) {
+    const how = g.kind.native ? L.report2.native(g.kind.prog) : L.report2.portable;
+    say(`- ❌ ${g.name} — ${how}, ${g.note || L.doctor.exitCode(g.code)}`);
+  }
+  // Гейт стоит на переносимом, хотя родной инструмент есть в системе: слабее, чем возможно.
+  const weaker = [...held, ...broken].filter(
+    (g) => !g.kind.native && (g.kind.alternatives || []).some(([, prog]) => whichSync(prog))
+  );
+  if (weaker.length) {
+    say("");
+    say(`### ${L.report2.weakerTitle}`);
+    say("");
+    for (const g of weaker) {
+      const have = (g.kind.alternatives || []).filter(([, prog]) => whichSync(prog)).map(([, prog]) => prog);
+      say(`- ⚠️ ${g.name} — ${L.report2.weaker(have.join(", "))}`);
+    }
+  }
+
+  say("");
+  say(`## ${L.report2.missingTitle}`);
+  say("");
+  if (!todo.length) say(`- ${L.report2.nothingMissing}`);
+  for (const [rec, needs] of todo) {
+    say(`- ❌ ${rec.slug} — ${needs ? L.report2.needsTool(needs) : L.report2.notInstalled}`);
+  }
+  if (skip.length) {
+    say("");
+    say(`### ${L.report2.hiddenTitle}`);
+    say("");
+    for (const [rec, why] of skip) say(`- ⬜ ${rec.slug} — ${why}`);
+  }
+
+  say("");
+  say(`## ${L.report2.readTitle}`);
+  say("");
+  for (const [name, key] of REQUIRED_DOCS) {
+    const found = await findDoc(name);
+    say(`- ${found ? "📖" : "⬜"} ${found || name} — ${L.report2.docs[key]}`);
+  }
+  say("");
+  say(`> ${L.report2.readWarn}`);
+
+  say("");
+  say(`## ${L.report2.ignoreTitle}`);
+  say("");
+  // Читаем тем же способом, каким это делает _skip.sh: комментарии и пустые строки прочь.
+  let ignored = [];
+  try {
+    ignored = (await readFile(join(CWD, ".aqkignore"), "utf8"))
+      .split("\n").map((l) => l.replace(/#.*$/, "").trim()).filter(Boolean);
+  } catch { /* файла нет — это норма, а не ошибка */ }
+  if (!ignored.length) say(`- ✅ ${L.report2.ignoreNone}`);
+  for (const pat of ignored) say(`- 🚫 ${pat}`);
+  if (ignored.length) {
+    say("");
+    say(`> ${L.report2.ignoreWarn}`);
+  }
+
+  say("");
+  say(`## ${L.report2.whyTitle}`);
+  say("");
+  for (const [rec] of todo.slice(0, 6)) say(`- **${rec.slug}** — ${rec.intent || ""}`);
+  if (!todo.length) say(`- ${L.report2.whyNothing}`);
+
+  const text = lines.join("\n") + "\n";
+  const dst = join(CWD, TARGET_DIR, "report.md");
+  await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+  await writeFile(dst, text, "utf8");
+
+  console.log("\n" + text);
+  console.log(c.dim(`  ${L.report2.saved(join(TARGET_DIR, "report.md"))}\n`));
+
+  // Код возврата — для конвейера и для агента: отчёт с красным гейтом не должен читаться
+  // как «всё в порядке» только потому, что команда выполнилась.
+  process.exit(broken.length ? 1 : 0);
+}
+
+export { cmdReport };