agent-quality-kit 0.13.0 → 0.15.0

package/tool/commands/doctor.mjs

@@ -3,243 +3,18 @@
 import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { scopeOutput, splitAdvice, changedFiles } from "../lib/scope.mjs";
 import { CWD, PKG_ROOT, TARGET_DIR, MANIFEST, SELF, c, exists, die, RUNTIME_FILES } from "../lib/core.mjs";
+import { maybeAsk } from "./feedback.mjs";
 import { cmdProbe, probeStatus } from "./probe.mjs";
-import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS, advisorySet, layoutChecks, coversOf, coversUnproven, unparsedLines } from "../lib/manifest.mjs";
+import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS, layoutChecks, unparsedLines } from "../lib/manifest.mjs";
 import { proveGates } from "../lib/prove.mjs";
-import { detectFacts, readCatalog, browserServerAdvice } from "../lib/repo.mjs";
-import { startWith, catalogBuckets, blindAdvice } from "../lib/advice.mjs";
-import { proposeGates, readAdoptFiles } from "../lib/adopt.mjs";
-import { assessBaseline, DEP_FILES, BASELINE_TOTAL } from "../lib/baseline.mjs";
+import { detectFacts, claudeShimFor } from "../lib/repo.mjs";
+import { reportBaseline, reportCatalog } from "./doctor-catalog.mjs";
 import { L } from "../i18n/index.mjs";
 import { countArbiters } from "./context.mjs";
 import { beginBrief, finishBrief } from "../lib/brief.mjs";
-import { declaredGates, sinceRef, runGates, progress, listArg } from "../lib/run.mjs";
-import { autoProbeAllowed } from "../lib/cadence.mjs";
-
-// Обязательный минимум проекта — прогоном, а не по памяти. До сих пор это было единственное
-// место, где комплект просил верить на слово, что человек прочитал методичку и сверился.
-async function reportBaseline(man, facts) {
-  const { readdir, readFile } = await import("node:fs/promises");
-  let files = [];
-  try {
-    files = (await readdir(CWD, { withFileTypes: true })).map((d) => d.name);
-  } catch { /* пустой список честнее выдуманного: ни один пункт не подтвердится */ }
-
-  // Файлы зависимостей читаются целиком и склеиваются: трекер ошибок объявляют по-разному в
-  // каждой экосистеме, а искать его надо одинаково.
-  let depsText = "";
-  for (const f of DEP_FILES) {
-    if (!files.some((n) => n.toLowerCase() === f)) continue;
-    try { depsText += (await readFile(join(CWD, f), "utf8")).toLowerCase() + "\n"; } catch { /* нечитаемый файл — просто не признак */ }
-  }
-
-  const rows = assessBaseline({ files, gateKeys: facts.gateKeys, facts, manifest: man || {}, depsText });
-  const okCount = rows.filter((r) => r.ok).length;
-
-  console.log(c.bold(`\n  ${L.baseline.heading}\n`));
-  console.log(c.dim(`  ${L.baseline.intro(rows.length, BASELINE_TOTAL)}`));
-  console.log(c.dim(`  ${L.baseline.caveat}\n`));
-  for (const r of rows) {
-    const mark = r.ok ? c.green("✔") : c.yellow("✘");
-    const title = L.baseline.titles[r.key] || r.key;
-    console.log(`  ${mark}  ${String(r.n).padStart(2)}. ${title}`);
-    console.log(c.dim(`        ${r.ok ? L.baseline.by(r.by) : L.baseline.none}`));
-  }
-  console.log(
-    "\n  " + (okCount === rows.length ? c.green(`${okCount}/${rows.length}`) : c.yellow(`${okCount}/${rows.length}`)) +
-      c.dim(`  ·  ${L.baseline.eyes(BASELINE_TOTAL - rows.length, "kit/docs/ai/project-baseline.md")}\n`)
-  );
-}
-
-async function reportCatalog(man, facts, probe = null) {
-  const catalog = await readCatalog();
-  if (!catalog.length) return;
-
-  // Четвёртая корзина, а не третья: «закрыто другим арбитром» — это НЕ «не поставлено».
-  // Пока их считали вместе, вывод каждый прогон называл долгом то, что уже держит biome или
-  // ruff. Просьба первого чужого пользователя; она же — наша собственная норма про вывод.
-  const { covered, unknownGates } = coversOf(man);
-  const { held, todo, skip, byOther } = catalogBuckets(catalog, facts, covered);
-
-  console.log(c.bold(`\n  ${L.doctor.gatesHeading}\n`));
-  const marks = ["has_ci", "has_db", "has_docker", "has_tests", "has_deps"]
-    .filter((k) => facts[k])
-    .map((k) => k.replace("has_", ""));
-  console.log(
-    c.dim(`  ${L.doctor.langs}: ${[...facts.langs].join(", ") || L.doctor.langsUnknown} · ${L.doctor.files}: ${facts.files}` +
-      (marks.length ? ` · ${L.doctor.hasThings}: ${marks.join(", ")}` : "") + "\n")
-  );
-
-  for (const rec of held) console.log(`  ${c.green("✔")}  ${rec.slug.padEnd(22)} ${c.dim(rec.intent || "")}`);
-  // ЧТО У ВАС УЖЕ ЕСТЬ — до итога и до списка крестов. Комплект, поставленный в проект с
-  // eslint, mocha и конвейером, показывал двадцать крестов и «держит машина 0»: мы считали
-  // только СВОИ записи, а чужие проверки не читали вовсе. С точки зрения владельца это
-  // неправда, и первое, что он видел, было обвинением. Предлагаем, а не вписываем: гейт в
-  // чужом манифесте без спроса — наше решение в чужом файле.
-  if (!declaredGates(man).length) {
-    const found = proposeGates(await readAdoptFiles(CWD));
-    if (found.length) {
-      console.log(`\n  ${c.bold(L.doctor.haveAlready(found.length))}`);
-      for (const g of found) {
-        console.log(`  ${c.green("✔")}  ${g.name.padEnd(12)} ${c.dim(`${g.cmd}   ← ${g.source}`)}`);
-      }
-      console.log(c.dim(`     ${L.doctor.haveAlreadyHow(found.map((g) => `${g.name}: "${g.cmd}"`).join("  "))}`));
-    }
-  }
-
-  // ЧТО ВАШИ ПРОВЕРКИ ПРОПУСТИЛИ. Проба знала имена непойманных классов и писала в отметку одно
-  // число; человек в `doctor` не видел ничего. Это самое конкретное, что мы знаем о проекте, —
-  // не «хорошая практика», а брак, подсаженный в ЕГО файл и ЕГО проверками не замеченный, —
-  // поэтому стоит выше списка «с чего начать». Читается из файла: ничего не запускает.
-  const blindOnes = (probe?.classes || []).map((b) => [b, catalog.find((r) => r.slug === b.slug)]).filter(([, r]) => r);
-  if (blindOnes.length) {
-    console.log(`\n  ${c.yellow("⚠")}  ${c.bold(L.doctor.blindHeading(probe.behind))}`);
-    for (const [b, rec] of blindOnes) {
-      // Три случая, и сливать их нельзя. Гейт стоял и проба его ГОНЯЛА — «стоит, но здесь не
-      // ловит», самое ценное. Гейт объявлен, но проба его не гоняла (поставлен позже или
-      // медленный) — «поймает ли, покажет следующая», а не «пойман». Гейта нет — совет.
-      const ranIt = probe.ran?.has(rec.slug);
-      const now = facts.gateKeys.includes(rec.slug);
-      console.log(`  ${now && !ranIt ? c.dim("~") : c.red("✘")}  ${rec.slug.padEnd(22)} ${c.dim(`${rec.intent || ""}  ← ${b.file}`)}`);
-      if (ranIt) { console.log(c.dim(`     ${L.doctor.blindRan(rec.slug)}`)); continue; }
-      if (now) { console.log(c.dim(`     ${L.doctor.blindInstalled}`)); continue; }
-      const adv = blindAdvice(rec, facts, {});
-      if (adv.command) console.log(c.dim(`     ${L.doctor.startCmd(adv.command)}`));
-      else console.log(c.dim(`     ${L.doctor.install(`${SELF} add ${rec.slug}`)}`));
-    }
-    console.log(c.dim(`     ${L.doctor.blindMore(`${SELF} probe`)}`));
-  } else if (probe?.state === "never" && declaredGates(man).length) {
-    console.log(c.dim(`\n  ${L.doctor.probeNever(`${SELF} probe`)}`));
-  }
-
-  // С ЧЕГО НАЧАТЬ. Двадцать одинаковых крестов — это ноль требований: закрывают первое
-  // попавшееся или не закрывают ничего. Порядок не по нашему вкусу: сперва то, что родилось из
-  // настоящего отказа И закрывается одной готовой командой.
-  const first = todo.length > 3 ? startWith(todo, facts, 3) : [];
-  if (first.length) {
-    console.log(`\n  ${c.bold(L.doctor.startWith)}`);
-    for (const rec of first) {
-      const adv = blindAdvice(rec, facts, {});
-      console.log(`  ${c.yellow("→")}  ${rec.slug.padEnd(22)} ${c.dim(rec.intent || "")}`);
-      if (adv.command) console.log(c.dim(`     ${L.doctor.startCmd(adv.command)}`));
-      if (adv.tool) console.log(c.dim(`     ${L.doctor.startTool(adv.tool)}`));
-    }
-    // Одна проверка руками — это разовый героизм. Сказать про хук здесь, а не в конце: человек
-    // читает первые строки и закрывает, а именно сейчас у него в руках список того, что стоит
-    // повесить перед пушем.
-    console.log(c.dim(`\n     ${L.doctor.startHook}`));
-  }
-
-  // ОСТАЛЬНОЕ — ПОСЛЕ ГЛАВНОГО И СЖАТО. Список шёл первым, по две строки на запись (вторая —
-  // «поставить: aqk add …»), и на requests главное начиналось со строки 84 из 102: человек
-  // читает сверху и закрывает раньше. Разбор соседа 2026-09-11 (research/competitors/agentlint.md):
-  // там первыми идут пять главных исправлений. Записи не теряются — теряется повтор подсказки.
-  const rest = todo.filter((r) => !first.includes(r));
-  if (rest.length) {
-    if (first.length) console.log(`\n  ${c.bold(L.doctor.todoRest(rest.length))}`);
-    else console.log("");
-    // ○, а не ✘: запись не установлена — это не падение. Крест в зелёном прогоне глаз читает
-    // как провал, и через неделю человек перестаёт смотреть на красное вообще (отзыв с живого
-    // проекта 2026-09-11). ✘ остаётся за тем, что упало или пропустило брак.
-    for (const rec of rest) console.log(`  ${c.dim("○")}  ${rec.slug.padEnd(22)} ${rec.intent || ""}`);
-    console.log(c.dim(`     ${L.doctor.todoRestHow(SELF)}`));
-  }
-
-  // Второстепенное — в конце: что закрыто чужим арбитром, что неприменимо, советы без вердикта.
-  if (byOther.length) {
-    console.log(c.dim(`\n  ${L.doctor.coveredBy(byOther.length)}`));
-    for (const [rec, gate] of byOther) console.log(c.dim(`  ~  ${rec.slug.padEnd(22)} ${L.doctor.coveredByGate(gate)}`));
-  }
-  // Гейт, которого нет в gates:, не закрывает ничего — и молчать об этом нельзя: человек
-  // считает запись закрытой, а её не держит никто. Называется поимённо, жёлтым.
-  if (unknownGates.length) {
-    console.log(c.yellow(`\n  ${L.doctor.coversUnknown(unknownGates.join(", "))}`));
-  }
-  // Заявка «эту запись держит наш линтер» сверяется с кодами правил из рецепта записи.
-  // Замерено на живом ruff.toml: девятнадцать групп правил, а print() не ловится — и заявка
-  // сняла бы запись с долга, не закрыв её ничем.
-  // Конфиги — ПО ЛИНТЕРАМ, а не одной склейкой: заявка сверяется правилами того линтера,
-  // которым закрыт гейт (отзыв с живого проекта 2026-09-11 — коды ruff искались в biome.json).
-  const readAll = async (names) => {
-    let t = "";
-    for (const f of names) { try { t += await readFile(join(CWD, f), "utf8") + "\n"; } catch { /* нет файла */ } }
-    return t;
-  };
-  let scripts = {}, pkgText = "";
-  try { pkgText = await readFile(join(CWD, "package.json"), "utf8"); scripts = JSON.parse(pkgText)?.scripts || {}; } catch { /* нет или не JSON */ }
-  const configs = {
-    // ruff.toml и .ruff.toml — конфиг ruff целиком, слово «ruff» в них писать незачем (поймал наш же
-    // smoke: `extend-select = [..., "T20"]` выбрасывался). pyproject.toml — только если в нём есть
-    // раздел ruff: он есть почти у каждого python-проекта и без ruff.
-    ruff: (await readAll(["ruff.toml", ".ruff.toml"])) +
-      ((await readAll(["pyproject.toml"])).match(/^\[tool\.ruff[\s\S]*/m)?.[0] || ""),
-    eslint: (await readAll([".eslintrc", ".eslintrc.json", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.yml", "eslint.config.js", "eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts"])) +
-      (/"eslintConfig"/.test(pkgText) ? pkgText : ""),
-    biome: await readAll(["biome.json", "biome.jsonc"]),
-    scripts,
-  };
-  for (const u of coversUnproven(man, catalog, configs)) {
-    if (u.kind === "unproven") {
-      console.log(c.yellow(`\n  ${L.doctor.coversUnproven(u.entry, u.gate, u.codes.join(", "))}`));
-      console.log(c.dim(`  ${L.doctor.coversUnprovenHow(`${SELF} add ${u.entry}`)}`));
-    } else if (u.kind === "impossible") {
-      console.log(c.yellow(`\n  ${L.doctor.coversImpossible(u.entry, u.gate, u.linter)}`));
-      console.log(c.dim(`  ${L.doctor.coversUnprovenHow(`${SELF} add ${u.entry}`)}`));
-    } else {
-      console.log(c.dim(`\n  ${L.doctor.coversCantCheck(u.entry, u.gate)}`));
-    }
-  }
-  // Не вердикт, а совет: отсутствие браузерного сервера — незанятая возможность, а не дефект.
-  // Поэтому строка тусклая и без значка, и её нет у проекта без интерфейса.
-  let mcpText = "";
-  for (const f of [".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json", ".claude/mcp.json"]) {
-    try { mcpText += await readFile(join(CWD, f), "utf8"); } catch { /* нет файла — нечего читать */ }
-  }
-  const browser = browserServerAdvice(facts, mcpText);
-  if (browser) {
-    console.log(c.dim(`\n  ${L.doctor.noBrowserServer}`));
-    console.log(c.dim(`  ${L.doctor.noBrowserServerHow(browser.servers.join("  ·  "))}`));
-  }
-  if (skip.length) {
-    console.log(c.dim(`\n  ${L.doctor.notApplicable(skip.length)}`));
-    for (const [rec, why] of skip) console.log(c.dim(`  ·  ${rec.slug.padEnd(22)} ${why}`));
-  }
-  console.log(
-    `\n  ${c.bold(L.doctor.total)} ${L.doctor.totalHeld(held.length)}, ${L.doctor.totalTodo(c.yellow(todo.length))}, ` +
-      (byOther.length ? `${L.doctor.totalCovered(byOther.length)}, ` : "") +
-      c.dim(L.doctor.totalSkip(skip.length)) + "\n"
-  );
-  // Числа отдаются наружу, а не пересчитываются второй раз: два счёта одного и того же
-  // расходятся ровно так же, как два списка команд.
-  return { held: held.length, todo: todo.length, todoRecs: todo };
-}
-
-// Короткий отчёт «что из этого реально брали» — не для человека, а для агента в следующей
-// сессии и для самого владельца: список объявленных гейтов молчит о том, сколько из них
-// действительно стоят и работают именно СЕЙЧАС. Перезаписывается каждым прогоном, не копится:
-// история — дело git-лога коммитов с этим отчётом, если владелец решит его коммитить.
-async function writeRunReport({ version, reached, results, skipped = [] }) {
-  const stamp = new Date().toISOString().replace("T", " ").slice(0, 16);
-  const ok = results.filter((r) => r.ok).length;
-  const lines = [
-    `# ${L.report.title} — ${stamp}`,
-    version ? `${L.report.version}: ${version}` : null,
-    `${L.report.level}: AQK-${reached < 0 ? L.doctor.levelNone : reached}`,
-    "",
-    ...results.map((r) => `${r.ok ? "✔" : "✘"} ${r.name} — ${r.secs}s${r.ok ? "" : ` (${r.note || L.doctor.exitCode(r.code)})`}`),
-    // Пропущенные по --skip/--only — строкой «~»: блок для агента читает их как «не запускались»,
-    // а не как зелёные. Молчание о них прочиталось бы как «проверено».
-    ...skipped.map((n) => `~ ${n} — ${L.report.skippedBySelect}`),
-    "",
-    L.report.summary(ok, results.length),
-  ].filter((l) => l !== null);
-
-  const dst = join(CWD, TARGET_DIR, "last-run.md");
-  await mkdir(join(CWD, TARGET_DIR), { recursive: true });
-  await writeFile(dst, lines.join("\n") + "\n", "utf8");
-}
+import { declaredGates, sinceRef, runGates, progress, listArg, writeRunReport } from "../lib/run.mjs";
+import { autoProbeAllowed, levelLimits } from "../lib/cadence.mjs";
 
 // ПРОБА ЗАПУСКАЕТСЯ САМА, раз в сто коммитов, — кроме конвейера (там это минуты сюрпризом в
 // быстрой проверке, отзыв с живого проекта 2026-09-11). Не влияет на код возврата никогда: это
@@ -259,6 +34,12 @@ async function autoProbe(brief) {
 
 async function cmdDoctor() {
   const brief = process.argv.includes("--brief");
+  // Коротко по умолчанию, поимённо по `--verbose`. Отзыв с живого проекта 2026-09-11: вывод на
+  // сто строк, из них семьдесят — зелёные галочки, и красное теряется между ними. Сворачивается
+  // только то, что ничего не требует: пройденное, неприменимое, пояснения. Упавшее, совет и
+  // «что поставить» печатаются всегда.
+  // AQK_VERBOSE=1 — то же для конвейера, где лог читают потом и целиком.
+  const verbose = process.argv.includes("--verbose") || process.env.AQK_VERBOSE === "1";
   const buf = brief ? beginBrief() : null;
   // Версия в шапке — единственное, что привязывает баг-репорт к коммиту, если ставили не из
   // релиза: без неё "у меня не работает" ничем не отличается от любой другой версии за год.
@@ -301,6 +82,11 @@ async function cmdDoctor() {
     }
   }
 
+  // СВОД, КОТОРОГО НЕ ВИДИТ CLAUDE CODE. Он читает CLAUDE.md, а не AGENTS.md (документация,
+  // сверено 2026-09-11); подробности и исходы — claudeSeesRules.
+  const shim = await claudeShimFor(CWD);
+  if (shim) console.log(`\n  ${c.yellow("!")}  ${L.doctor.claudeShim[shim]}`);
+
   // Команды в точке входа заполнены или остались пустыми заготовками? Файл берётся тот же,
   // что проверен выше, — иначе проект на `CLAUDE.md` этой проверки не получал вовсе.
   const entryFile = (Array.isArray(man?.entry) ? man.entry : []).find((e) => typeof e === "string" && e.trim())?.trim() || "AGENTS.md";
@@ -319,7 +105,7 @@ async function cmdDoctor() {
     const arb = countArbiters(text, ["человек", "human", "nobody"]);
     if (arb.total && arb.human) {
       console.log(`\n  ${c.yellow("!")}  ${L.doctor.rulesByHuman(arb.total, arb.machine, arb.human)}`);
-      console.log(c.dim(`     ${L.doctor.rulesByHumanWhy}`));
+      if (verbose) console.log(c.dim(`     ${L.doctor.rulesByHumanWhy}`));
     }
 
     const emptyCommands = (text.match(/^- [^:]+: ``$/gm) || []).length;
@@ -390,6 +176,16 @@ async function cmdDoctor() {
   } else {
     console.log(c.green(`  ${L.doctor.allDone}\n`));
   }
+  // Состояние пробы — из файла отметки, миллисекунды. Нет его — блок про пробу просто молчит.
+  let probe = null;
+  try { probe = await probeStatus(); } catch { /* пробы нет — и ладно */ }
+  // Чего уровень НЕ доказывает — сразу под ним, пока глаз на нём (см. levelLimits).
+  if (reached >= 1) {
+    const lim = levelLimits(probe);
+    console.log(c.dim(`  ${L.doctor.limitsTitle}`));
+    console.log(`    ${L.doctor.limitsProbe[lim.kind](lim, `${SELF} probe`)}`);
+    console.log(`    ${L.doctor.limitsCi}\n`);
+  }
 
   const facts = await detectFacts(man);
   if (process.argv.includes("--baseline")) {
@@ -402,16 +198,14 @@ async function cmdDoctor() {
     await reportBaseline(man, facts);
     process.exit(0);
   }
-  // Состояние пробы — из файла отметки, миллисекунды. Нет его — блок про пробу просто молчит.
-  let probe = null;
-  try { probe = await probeStatus(); } catch { /* пробы нет — и ладно */ }
-  const cat = (await reportCatalog(man, facts, probe)) || { held: 0, todo: 0, todoRecs: [] };
+  const cat = (await reportCatalog(man, facts, probe, verbose)) || { held: 0, todo: 0, todoRecs: [] };
 
   // «Объявлен» ≠ «работает». Без --run говорим это вслух, а не молчим.
   const wantRun = process.argv.includes("--run");
   const gates = declaredGates(man);
   let gateFailed = 0;
   let failedNames = [];
+  let cannotNames = [];
   let skippedNames = [];
   if (wantRun) {
     // --jobs N: сколько гейтов одновременно. Без флага — по одному, как было: чужие гейты бывают
@@ -420,7 +214,7 @@ async function cmdDoctor() {
     const ji = process.argv.indexOf("--jobs");
     const jobs = ji > -1 ? Number(process.argv[ji + 1]) : 1;
     if (!Number.isInteger(jobs) || jobs < 1) die(L.doctor.jobsBad(process.argv[ji + 1] ?? ""));
-    const run = await runGates(man, { since: sinceRef(), only: listArg(process.argv, "--only"), skip: listArg(process.argv, "--skip"), jobs });
+    const run = await runGates(man, { since: sinceRef(), only: listArg(process.argv, "--only"), skip: listArg(process.argv, "--skip"), jobs, verbose });
     gateFailed = run.failed;
     failedNames = run.results.filter((r) => !r.ok).map((r) => r.name);
     skippedNames = run.skipped || [];
@@ -437,6 +231,7 @@ async function cmdDoctor() {
     // стоят дороже. Не влияет на код возврата НИКОГДА — это осмотр, а не порог.
     // Выключается AQK_PROBE=0 — у всего, что случается само, обязан быть выключатель.
     if (!brief && process.env.AQK_PROBE !== "0") await autoProbe(brief);
+    cannotNames = run.results.filter((r) => r.cannot).map((r) => r.name);
   } else if (gates.length) {
     console.log(
       c.yellow(`  ${L.doctor.declaredNotRun(gates.length)}`) +
@@ -444,6 +239,20 @@ async function cmdDoctor() {
     );
   }
 
+  // ЕДИНСТВЕННАЯ ПЛАТА ЗА КОМПЛЕКТ — один ответ автору. Человеку говорим здесь, агенту — в
+  // блоке `context`; текст и решение «есть ли о чём просить» одни на оба места (feedback.mjs),
+  // отметка одна на проект (ask.mjs): кто первым дошёл, тот и спросил, второй раз не спрашивает
+  // никто. В кратком режиме молчим — там ворота коммита, и лишняя строка там дороже всего.
+  const askText = brief ? null : await maybeAsk({
+    cannot: cannotNames,
+    red: failedNames.filter((n) => !cannotNames.includes(n)),
+    blind: (probe?.classes || []).map((b) => b.slug),
+  }, SELF);
+  if (askText) {
+    for (const l of askText.split("\n")) console.log(c.dim(`  ${l}`));
+    console.log("");
+  }
+
   // Код возврата — для конвейера. Порог задаётся так: aqk doctor --min 1
   const minIdx = process.argv.indexOf("--min");
   const min = minIdx > -1 ? Number(process.argv[minIdx + 1]) : null;

package/tool/commands/feedback.mjs

@@ -0,0 +1,157 @@
+// tool/commands/feedback.mjs — `aqk feedback`: единственная плата за комплект — один ответ.
+//
+// ЗАЧЕМ. Замер 2026-09-14: 1342 скачивания в неделю в npm и ни одного пользователя — версии
+// качаются равномерно, включая прожившую двадцать пять минут, то есть это зеркала и сканеры. На
+// GitHub за две недели семь уникальных посетителей, две звезды, ноль чужих комментариев за всё
+// время. Обратной связи нет не потому, что люди молчат: просить мы не умеем. Единственная
+// просьба печаталась при `init` — ДО того, как комплект сделал хоть что-то полезное, — и звала
+// поставить звезду, то есть просила у человека, которому ещё ничего не дали.
+//
+// ЧТО ЗДЕСЬ ДРУГОЕ. Просим, только когда есть что рассказать, и рассказ уже собран: версия,
+// уровень, стек, что покраснело, чего комплект НЕ СМОГ проверить, какие классы брака не ловит
+// никто. Человеку остаётся одна строка своими словами.
+//
+// ЧЕГО ЗДЕСЬ НЕТ И НЕ БУДЕТ. Ничего не отправляется само. Исходящий запрос у комплекта ровно
+// один — про свежесть версии, он описан в README и SECURITY.md. Отчёт печатается и отдаётся
+// человеку: он видит глазами всё, что отправляет. Ни путей, ни содержимого файлов, ни имени
+// репозитория в отчёте нет — иначе первый же внимательный читатель назовёт это телеметрией,
+// и будет прав.
+import { readFile } from "node:fs/promises";
+import { PKG_ROOT, SELF, REPO_URL, c, stateDirs } from "../lib/core.mjs";
+import { askAllowed, markAsked } from "../lib/ask.mjs";
+import { join } from "node:path";
+import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { detectFacts } from "../lib/repo.mjs";
+import { declaredGates, readRun } from "../lib/run.mjs";
+import { probeStatus } from "./probe.mjs";
+import { L } from "../i18n/index.mjs";
+
+// О ЧЁМ ПРОСИТЬ — чистая функция от состояния. Порядок не по нашему удобству, а по ценности
+// ответа для того, кто чинит комплект:
+//   1. НЕ СМОГЛИ ПРОВЕРИТЬ — отказ самого прибора. Это жалоба, а жалоба даётся людям легче
+//      похвалы, и она же показывает, где инструмент врёт. Дороже всего остального.
+//   2. СЛЕПОЙ КЛАСС — проба подсадила брак, и его не поймал никто. Рассказ об этом проверяет
+//      главное наше утверждение: что проба находит настоящие дыры, а не выдуманные.
+//   3. КРАСНЫЙ ГЕЙТ — комплект поймал то, ради чего его ставят. Момент пользы, но самый частый,
+//      поэтому последний.
+// Ничего из перечисленного нет — просьбы нет вовсе. «Оставьте отзыв» без содержания это шум,
+// а шум выключают вместе с хуком, в котором он приехал.
+function feedbackAsk(state = {}) {
+  const pick = (kind, list) => (list && list.length ? { reason: kind, names: [...list] } : null);
+  return pick("cannot", state.cannot) || pick("blind", state.blind) || pick("red", state.red) || null;
+}
+
+// ОТЧЁТ. Каждая строка — либо факт, либо слово «неизвестно»: пустое место в письме читается как
+// «всё хорошо» ровно так же, как пустой вывод проверки, и это тот же порок, только у нас самих.
+//
+// Слепые классы называются именем класса, без файла. Файл знает проба («blind-class: slug path»), и
+// соблазн положить его сюда велик — он объясняет находку. Нельзя: путь внутри чужого
+// репозитория рассказывает о чужом проекте больше, чем его владелец собирался рассказать.
+function reportText(state = {}, T = L.feedback.report) {
+  const u = T.unknown;
+  const list = (xs) => (xs && xs.length ? xs.join(", ") : T.none);
+  return [
+    T.title,
+    "",
+    T.env(state.version || u, state.node || u, state.platform || u),
+    T.level(state.level === null || state.level === undefined ? u : `AQK-${state.level}`),
+    T.stack(state.langs && state.langs.length ? state.langs.join(", ") : u),
+    T.gates(state.gates === undefined ? u : state.gates, list(state.red), list(state.cannot)),
+    // `null` — проба не делалась: это НЕИЗВЕСТНО, а не «нет». Пустой список означал бы, что
+    // проба прошла и ничего не нашла, — и автор письма прочитал бы чужое незнание как чистоту.
+    T.blind(state.blind === null || state.blind === undefined
+      ? u
+      : list(state.blind.map((b) => (typeof b === "string" ? b : b.slug)))),
+    "",
+    T.say,
+    "",
+    T.mark(state.version || u),
+  ];
+}
+
+// КАК ЭТО ЗВУЧИТ — один текст на два места: `context` кладёт его агенту, `doctor` печатает
+// человеку. Собери строку в каждом месте отдельно — и через месяц они разойдутся, как разошлись
+// бы `context` и `prompt` без общего `readAdvice`.
+//
+// АГЕНТУ — ОТДЕЛЬНАЯ ОГОВОРКА, и она не вежливость. Строка ложится в контекст ЧУЖОГО агента, а
+// он исполняет написанное: без «скажи один раз и не настаивай» это реклама в чужом окне, и хук,
+// которым она приехала, снесут в первый же день вместе со всей затеей. Человеку вместо неё —
+// как выключить: у всего, что случается само, обязан быть выключатель.
+function askLine(ask, self = "aqk", { agent = false } = {}, T = L.feedback.ask) {
+  if (!ask || !ask.reason) return null;
+  const say = T[ask.reason];
+  if (!say) return null;
+  // Перенос, а не пробел: команда обязана оставаться ПОСЛЕДНЕЙ в своей строке — иначе
+  // следующее слово приклеится к ней при копировании, и человек выполнит не то.
+  return `${say(ask.names.join(", "), `${self} feedback`)}\n${agent ? T.agent : T.once}`;
+}
+
+// Выключатель — тот же, что у совета (AQK_ADVICE=0), пробы (AQK_PROBE=0) и проверки версии
+// (AQK_UPDATE=0). Молчаливой просьбы, которую нельзя отменить, у нас не будет.
+function feedbackWanted(env = process.env) {
+  return String(env.AQK_FEEDBACK || "") !== "0";
+}
+
+// ОДНА ПРОСЬБА НА ПРОЕКТ — и решение, и ограничитель, и отметка здесь. `doctor` и `context`
+// только печатают: разведи это по двум командам, и они разойдутся в условиях, а человек получит
+// просьбу дважды. Кто первым дошёл, тот и спросил.
+//
+// Ничего не роняет: просьба об одолжении не имеет права стоить человеку прогона.
+async function maybeAsk(state, self, { agent = false } = {}) {
+  if (!feedbackWanted()) return null;
+  try {
+    const dirs = stateDirs();
+    if (!(await askAllowed("value", dirs))) return null;
+    const line = askLine(feedbackAsk(state), self, { agent });
+    if (line) await markAsked("value", dirs);
+    return line;
+  } catch {
+    return null;
+  }
+}
+
+// Предзаполненная ссылка. Параметры `title` и `body` — документация GitHub («Creating an issue
+// from a URL query», сверено 2026-09-14). Кодируется ВСЁ: в теле переносы строк, решётки и
+// пробелы, и незакодированная ссылка обрывается на первом же из них — а всё после решётки
+// браузер считает якорем и не передаёт вовсе.
+function issueUrl(repo, title, body) {
+  const q = `title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`;
+  return `${String(repo).replace(/\/+$/, "")}/issues/new?${q}`;
+}
+
+async function cmdFeedback() {
+  const T = L.feedback;
+  const man = await readManifest();
+  let version = "";
+  try { version = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || ""; } catch { /* версия просто не покажется */ }
+
+  const run = await readRun();
+  let facts = null;
+  try { facts = await detectFacts(man); } catch { /* стек не определили — скажем «неизвестно» */ }
+  let level = null;
+  if (man?.aqk) { try { level = (await assessLevel(man, null)).reached; } catch { /* уровень не посчитали */ } }
+  // Классы известны только когда проба ДЕЙСТВИТЕЛЬНО проходила. «Никогда», «выключена» и «не
+  // знаем» — это null, то есть «неизвестно»: см. договор в reportText.
+  let blind = null;
+  try {
+    const st = await probeStatus();
+    if (st.state === "fresh" || st.state === "stale") blind = st.classes || [];
+  } catch { /* пробы не было — так и скажем */ }
+
+  const lines = reportText({
+    version, node: process.version, platform: process.platform, level,
+    langs: facts?.langs ? [...facts.langs] : [],
+    gates: declaredGates(man).length,
+    red: run?.red || [], cannot: run?.cannot || [], blind,
+  });
+  const body = lines.join("\n");
+  console.log(`\n${body}\n`);
+  console.log(c.bold(`  ${T.how}`));
+  console.log(`  ${issueUrl(REPO_URL, T.issueTitle, body)}\n`);
+  console.log(c.dim(`  ${T.nothingSent}`));
+  console.log(c.dim(`  ${T.orPaste(`${SELF} feedback`)}\n`));
+  // Код возврата всегда 0: команда, которая просит об одолжении и роняет при этом конвейер, —
+  // последнее, что человек стерпит.
+}
+
+export { cmdFeedback, feedbackAsk, reportText, issueUrl, askLine, feedbackWanted, maybeAsk };