agent-quality-kit 0.14.0 → 0.15.0

package/README.md

@@ -107,6 +107,8 @@ aqk context             the repository state in one block, for an agent's contex
 aqk prompt              one task to paste into an agent: what to fix, in order, and the
                         command that proves each item done
 aqk vitals              is what the kit runs on wired up: gate tools, hooks, freshness
+aqk feedback            feedback to the author: a report from the last run and probe,
+                        plus a prefilled link. No paths, no code; nothing is sent for you
 aqk doctor --run --brief  one line on success, the whole run on failure — for hooks
 aqk context --full      the same plus the command map and the rulebook verbatim (~7000
                         tokens against ~500: the price of an agent that does not guess)
@@ -351,7 +353,7 @@ Already using [pre-commit](https://pre-commit.com)? Three lines in the file you
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.14.0
+    rev: v0.15.0
     hooks:
       - id: aqk            # runs what the repository declares; blocks below AQK-1
       # - id: aqk-doctor   # read-only: the level and what is missing, blocks nothing
@@ -372,7 +374,7 @@ layer AQK adds.
 [![on the GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.14.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.15.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -431,12 +433,34 @@ files the diff touched:
 aqk doctor --run --since main    # only what this branch introduced
 ```
 
-Three outcomes, all of them said out loud. Findings inside the diff — red, as usual. Findings only
-outside it — green, with the number that was hidden, never a silent "all clear". And a gate whose
+Four outcomes, all of them said out loud. Findings inside the diff — red, as usual. Findings only
+outside it — green, with the number that was hidden, never a silent "all clear". A gate whose
 output carries no paths at all (a commit-message check, a CI-config check) **cannot** be narrowed:
-it stays red, and says why. Calling it green because there was nothing to narrow would be exactly
+it stays red, and says why. And a gate that **could not run at all** — no tool, an unexpected exit
+code, killed by a signal — is never narrowed by the diff: a failure has no place in the code, only
+itself. Calling either of the last two green because there was nothing to narrow would be exactly
 the silence this tool exists to remove.
 
+### The only payment: one answer
+
+The kit is free and collects nothing about you: it makes exactly one outgoing request — asking the
+npm registry whether a newer version exists. The payment is different: **one answer to the author**.
+So once per project, and only when there is something to tell, `doctor` or the agent block prints a
+line like "AQK could not check `smoke`; that is the most valuable thing to tell the author". Then:
+
+```bash
+aqk feedback     # builds the message and hands you a prefilled link — you send it, not us
+```
+
+The message carries: version, level, stack, what went red, what the kit could not check, which
+defect classes nobody catches here. **No paths, no code, no repository name** — you see every
+character you send. No GitHub? Forward the text as is. Not interested at all? `AQK_FEEDBACK=0`.
+
+Somewhere to say it in your own words:
+[where the kit was wrong](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/90) ·
+[what check is missing](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/91) ·
+[show your manifest](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/92).
+
 Every `doctor --run` rewrites `.aqk/last-run.md` — a short report of what actually ran and how
 long it took. The list of gates in the manifest says nothing about how many of them are alive
 right now; the report does. The file is ephemeral — keep it in your own `.gitignore`.

package/README.ru.md

@@ -109,6 +109,8 @@ aqk context             состояние репозитория одним б
 aqk prompt              одно задание для агента: что починить, по порядку, и у каждого
                         пункта команда, которая докажет «готово»
 aqk vitals              подключено ли то, чем комплект работает: инструменты, хуки, свежесть
+aqk feedback            отзыв автору: отчёт из последнего прогона и пробы плюс готовая
+                        ссылка. Без путей и без кода; ничего не отправляет само
 aqk doctor --run --brief  одна строка на успехе, весь прогон при провале — для хуков
 aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
                         против ≈500 — плата за то, чтобы агент не догадывался)
@@ -355,7 +357,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.14.0
+    rev: v0.15.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -374,7 +376,7 @@ repos:
 [![в GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.14.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.15.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -432,11 +434,34 @@ aqk ratchet no-print-in-prod  # старое — долг, новое не пу
 aqk doctor --run --since main    # только то, что внесла эта ветка
 ```
 
-Три исхода, и все три названы вслух. Находки внутри дифа — красный, как обычно. Находки только
-снаружи — зелёный, с числом того, что скрыто, а не молчаливое «всё чисто». А гейт, в выводе
+Четыре исхода, и все четыре названы вслух. Находки внутри дифа — красный, как обычно. Находки
+только снаружи — зелёный, с числом того, что скрыто, а не молчаливое «всё чисто». Гейт, в выводе
 которого путей нет вовсе (проверка сообщения коммита, проверка конфига конвейера), сузиться
-**не может**: он остаётся красным и говорит почему. Назвать его зелёным потому, что сужать было
-нечего, — ровно та тишина, ради устранения которой этот инструмент и написан.
+**не может**: он остаётся красным и говорит почему. А гейт, который вообще **не смог
+отработать** — нет инструмента, неожиданный код возврата, убит сигналом, — дифом не сужается
+никогда: у сбоя нет места в коде, есть только сам сбой. Назвать любой из двух последних зелёным
+потому, что сужать было нечего, — ровно та тишина, ради устранения которой этот инструмент и
+написан.
+
+### Единственная плата — один ответ
+
+Комплект бесплатный и ничего о вас не собирает: исходящий запрос у него ровно один — спросить
+реестр npm, не вышла ли версия свежее. Плата другая: **один ответ автору**. Поэтому один раз на
+проект — и только когда есть что рассказать — `doctor` или блок для агента печатают строку вроде
+«AQK не смог проверить `smoke`; автору это ценнее всего». Дальше:
+
+```bash
+aqk feedback     # соберёт письмо и даст готовую ссылку — отправляете вы, не мы
+```
+
+В письме: версия, уровень, стек, что покраснело, чего комплект не смог проверить, какие классы
+брака здесь не ловит никто. **Ни путей, ни кода, ни имени репозитория** — вы видите глазами всё,
+что отправляете. Не нужен GitHub — перешлите текст как есть. Не нужно вовсе: `AQK_FEEDBACK=0`.
+
+Где рассказать словами:
+[где комплект соврал](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/90) ·
+[какой проверки не хватает](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/91) ·
+[покажите свой манифест](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/92).
 
 Каждый `doctor --run` перезаписывает `.aqk/last-run.md` — короткий отчёт, что из объявленного
 реально сработало и за сколько. Список гейтов в манифесте молчит о том, сколько из них живы

package/llms.txt

@@ -76,7 +76,7 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
   the files `init` writes are owned by root, so you cannot edit your own manifest. Debian-based
   on purpose: the gates are `sh`, `grep`, `awk`, `find` — under alpine's busybox they behave
   differently, and an image where the gates behave differently is worse than no image
-- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.14.0` with `min: 1`
+- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.15.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.14.0",
+  "version": "0.15.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": {

package/tool/commands/context.mjs

@@ -21,14 +21,14 @@
 // а агент примет его за утверждение. Поэтому каждое незнание называется словом: прогона не было —
 // так и написано, прогон устарел — тоже, инструмента нет — тоже.
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { CWD, TARGET_DIR, SELF, c, exists, commandRows, preCommitHook } from "../lib/core.mjs";
+import { maybeAsk } from "./feedback.mjs";
 import { readManifest, assessLevel, coversOf } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog } from "../lib/repo.mjs";
 import { catalogBuckets, startWith, blindAdvice } from "../lib/advice.mjs";
 import { proposeGates, readAdoptFiles } from "../lib/adopt.mjs";
-import { declaredGates } from "../lib/run.mjs";
+import { declaredGates, readRun } from "../lib/run.mjs";
 import { probeStatus } from "./probe.mjs";
 import { L } from "../i18n/index.mjs";
 
@@ -73,11 +73,17 @@ function contextBlock(state, T = L.context) {
     out.push(T.runNone);
   } else {
     const red = state.run.red || [];
-    const shown = red.slice(0, MAX_RED);
-    const names = red.length > MAX_RED
-      ? `${shown.join(", ")} — ${T.andMore(red.length - MAX_RED)}`
-      : shown.join(", ");
-    out.push(red.length ? T.runRed(state.run.when, names) : T.runClean(state.run.when));
+    const cannot = state.run.cannot || [];
+    const short = (list) => (list.length > MAX_RED
+      ? `${list.slice(0, MAX_RED).join(", ")} — ${T.andMore(list.length - MAX_RED)}`
+      : list.join(", "));
+    if (red.length) out.push(T.runRed(state.run.when, short(red)));
+    // «НЕ СМОГЛИ ПРОВЕРИТЬ» — ОТДЕЛЬНОЙ СТРОКОЙ, И ЧИСТО ТОЛЬКО КОГДА ОБА СПИСКА ПУСТЫ.
+    // Гейт, который не сумел отработать, не находка о коде: агент, прочитавший его как находку,
+    // пойдёт чинить исправный файл. А если бы он не попал НИКУДА, прогон, где всё сломалось,
+    // читался бы как «чисто» — та же тишина, только внутри блока, который читает машина.
+    if (cannot.length) out.push(T.runCannot(short(cannot)));
+    if (!red.length && !cannot.length) out.push(T.runClean(state.run.when));
     if (state.run.stale) out.push(T.runStale(state.run.when));
     if (state.run.skipped) out.push(T.skipped(state.run.skipped));
   }
@@ -148,20 +154,13 @@ function contextBlock(state, T = L.context) {
   // чем промолчать: он пойдёт его читать и получит пустоту вместо правил. Замерено на шести
   // чужих проектах: на flask блок писал «Свод правил: AGENTS.md», которого там нет.
   if (state.entryExists !== false) out.push("", T.where(state.entry || "AGENTS.md"));
+  // ПРОСЬБА ОБ ОТЗЫВЕ — последней строкой и только при содержании (feedback.mjs). Последней
+  // потому, что это единственная строка блока, которая не про состояние проекта: ставить её
+  // выше значило бы отодвинуть работой то, ради чего блок и читают.
+  if (state.ask) out.push("", state.ask);
   return out;
 }
 
-// Разбор отчёта прошлого прогона. Формат кладёт сам `doctor` в .aqk/last-run.md; читаем его,
-// а не запускаем гейты заново: хук обязан укладываться в секунду-две, а прогон у нас идёт минуту.
-function parseLastRun(text) {
-  if (!text) return null;
-  const when = (text.match(/^# aqk doctor --run — (.+)$/m) || [])[1] || "";
-  const red = [];
-  for (const m of text.matchAll(/^✘ ([^\s—]+)/gm)) red.push(m[1]);
-  const skipped = (text.match(/^~ /gm) || []).length;
-  return { when: when.trim(), red, skipped, stale: false };
-}
-
 // Правила и их арбитры: отметка `<!-- aqk: имя -->` рядом с правилом. `человек` — честное
 // признание, что машина этого не держит; так его и считаем, отдельно от машинных.
 function countArbiters(text, humanWords) {
@@ -173,16 +172,6 @@ function countArbiters(text, humanWords) {
   return { total: marks.length, machine: marks.length - human, human };
 }
 
-// Прогон старше последнего коммита описывает не тот код, что лежит перед агентом. Молча выдать
-// его за свежий — соврать: именно так «зелёный месяц назад» превращается в «зелёный сейчас».
-function runIsStale(when) {
-  if (!when) return false;
-  const r = spawnSync("git", ["log", "-1", "--format=%cI"], { cwd: CWD, encoding: "utf8" });
-  if (r.status !== 0 || !r.stdout) return false;
-  const commit = Date.parse(r.stdout.trim());
-  const run = Date.parse(when.replace(" ", "T"));
-  return Number.isFinite(commit) && Number.isFinite(run) && run < commit;
-}
 
 
 // УСТАНОВКА ХУКА — отдельной командой, а не частью `init`, и это решение, а не лень. Комплект
@@ -260,16 +249,6 @@ async function installHook(full = false) {
   console.log(c.dim(`  ${T.hookWhat}`));
 }
 
-// Прошлый прогон — из отчёта, который кладёт `doctor --run`. Отдельной функцией: его читают и
-// `context`, и `prompt`, и два разбора одного файла разошлись бы.
-async function readRun() {
-  const lastRun = join(CWD, TARGET_DIR, "last-run.md");
-  if (!(await exists(lastRun))) return null;
-  const run = parseLastRun(await readFile(lastRun, "utf8"));
-  if (run) run.stale = runIsStale(run.when);
-  return run;
-}
-
 // Что советовать — теми же функциями, что у `doctor`: корзины каталога, «начните с трёх», совет
 // под язык, чужие проверки проекта. Одно место на `context` и `prompt`: второй расчёт того же
 // самого разошёлся бы с первым. Класс из пробы, чей гейт уже стоит, в совет не идёт — ставить
@@ -364,10 +343,27 @@ async function cmdContext(args = []) {
     next = nextSteps({ init: !man, adopt, blind, start });
   } catch { /* не посчитали — блок скажет остальное; выдумывать шаги нельзя */ }
 
+  // ЕДИНСТВЕННАЯ ПЛАТА ЗА КОМПЛЕКТ — один ответ автору, и просит о нём агент: он читает этот
+  // блок каждую сессию и передаёт человеку то, что в нём написано. Замер 2026-09-14: тысяча
+  // скачиваний в неделю и ноль отзывов за всё время — просьба печаталась только при `init`, то
+  // есть до того, как комплект сделал хоть что-то.
+  //
+  // ТРИ УСЛОВИЯ, И ВСЕ ТРИ ОБЯЗАТЕЛЬНЫ: не выключено человеком, не просили на этом проекте
+  // раньше, и ЕСТЬ О ЧЁМ рассказать. Без третьего это «оставьте отзыв» — шум, а шум выключают
+  // вместе с хуком, в котором он приехал.
+  //
+  // ЕДИНСТВЕННАЯ ЗАПИСЬ НА ДИСК В ЭТОЙ КОМАНДЕ, кроме `--install`. Без отметки просьба
+  // повторялась бы каждую сессию: красный гейт живёт в проекте днями, а блок читается заново
+  // при каждом запуске агента и после каждого сжатия контекста.
+  const ask = await maybeAsk({
+    cannot: run?.cannot || [], red: run?.red || [],
+    blind: (probe?.classes || []).map((b) => b.slug),
+  }, portableSelf(SELF), { agent: true });
+
   console.log(contextBlock({
     entry, entryExists: rules !== null, level, rules, run, ratchets, probe, full: fullPart,
-    next, when: { hook: await preCommitHook(CWD) },
+    next, when: { hook: await preCommitHook(CWD) }, ask,
   }).join("\n"));
 }
 
-export { cmdContext, contextBlock, nextSteps, parseLastRun, countArbiters, withHook, hasOurHook, portableSelf, readRun, readAdvice };
+export { cmdContext, contextBlock, nextSteps, countArbiters, withHook, hasOurHook, portableSelf, readAdvice };

package/tool/commands/doctor.mjs

@@ -4,6 +4,7 @@ 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, 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, layoutChecks, unparsedLines } from "../lib/manifest.mjs";
 import { proveGates } from "../lib/prove.mjs";
@@ -12,34 +13,9 @@ 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 { declaredGates, sinceRef, runGates, progress, listArg, writeRunReport } from "../lib/run.mjs";
 import { autoProbeAllowed, levelLimits } from "../lib/cadence.mjs";
 
-// Короткий отчёт «что из этого реально брали» — не для человека, а для агента в следующей
-// сессии и для самого владельца: список объявленных гейтов молчит о том, сколько из них
-// действительно стоят и работают именно СЕЙЧАС. Перезаписывается каждым прогоном, не копится:
-// история — дело 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");
-}
-
 // ПРОБА ЗАПУСКАЕТСЯ САМА, раз в сто коммитов, — кроме конвейера (там это минуты сюрпризом в
 // быстрой проверке, отзыв с живого проекта 2026-09-11). Не влияет на код возврата никогда: это
 // осмотр, а не порог. Отдельной функцией: внутри прогона эта лесенка дала вложенность 6, и наш же
@@ -229,6 +205,7 @@ async function cmdDoctor() {
   const gates = declaredGates(man);
   let gateFailed = 0;
   let failedNames = [];
+  let cannotNames = [];
   let skippedNames = [];
   if (wantRun) {
     // --jobs N: сколько гейтов одновременно. Без флага — по одному, как было: чужие гейты бывают
@@ -254,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)}`) +
@@ -261,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 };

package/tool/commands/project.mjs

@@ -6,7 +6,8 @@ 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_URL, c, exists, die,
-  copyDir, writeIfAbsent, FEEDBACK_MARK, docPath, ensureIgnored } from "../lib/core.mjs";
+  copyDir, writeIfAbsent, stateDirs, docPath, ensureIgnored } from "../lib/core.mjs";
+import { askAllowed, markAsked } from "../lib/ask.mjs";
 import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
 import { banner } from "../lib/banner.mjs";
 import { readManifest } from "../lib/manifest.mjs";
@@ -95,7 +96,10 @@ ${c.dim(L.init.burned(`${SELF} note "…"`))}
 // Ничего не постится само: ссылки печатаются, дальше решает человек. Обратная связь важнее
 // звезды, но без звезды меньше шансов, что кто-то вообще дойдёт до фидбека.
 async function maybeAskFeedback() {
-  if (await exists(FEEDBACK_MARK)) return;
+  // Ограничитель — общий на все обращения комплекта (ask.mjs). Вид `install` разовый и живёт
+  // в доме пользователя: второй init в другом репозитории на том же компьютере молчит.
+  const dirs = stateDirs();
+  if (!(await askAllowed("install", dirs))) return;
   const url = REPO_URL;
   console.log(`
 ${c.bold(L.feedback.title)}
@@ -104,20 +108,14 @@ ${c.bold(L.feedback.title)}
     ${url}/issues/new
 ${c.dim(`  ${L.feedback.once}`)}
 `);
-  // Пометка «уже показывали» — удобство, а не работа команды. Домашнего каталога может не быть
-  // записываемым вовсе: в контейнере, запущенном `--user 1001:127`, у этого uid нет записи в
-  // /etc/passwd, `homedir()` даёт «/», и запись падает с EACCES на `/.config`. До 2026-09-09
-  // это роняло ВЕСЬ `init` — то есть любого, кто набрал команду из нашей же документации по
-  // docker. Локально не воспроизводилось случайно: uid разработчика 1000 совпадает с
-  // пользователем `node` в образе, у которого дом есть. Нашёл конвейер, где uid 1001.
+  // Пометка «уже показывали» — удобство, а не работа команды: `markAsked` не бросает, а
+  // возвращает, записалось ли. Дом бывает недоступен для записи (в контейнере с `--user
+  // 1001:127` у этого uid нет записи в /etc/passwd, homedir() даёт «/»), и до 2026-09-09 это
+  // роняло ВЕСЬ `init` — то есть любого, кто набрал команду из нашей же документации по docker.
   //
   // Молча глотать нельзя — это то, что красит наш же swallowed-error. Поэтому вслух: не
   // запомнили, покажем снова. Установка при этом доходит до конца.
-  try {
-    await writeIfAbsent(FEEDBACK_MARK, "shown\n", { force: false });
-  } catch {
-    console.log(c.dim(`  ${L.feedback.notRemembered}`));
-  }
+  if (!(await markAsked("install", dirs))) console.log(c.dim(`  ${L.feedback.notRemembered}`));
 }
 
 function findJournal() {

package/tool/commands/prompt.mjs

@@ -15,7 +15,8 @@
 import { readManifest } from "../lib/manifest.mjs";
 import { claudeShimFor } from "../lib/repo.mjs";
 import { CWD, SELF } from "../lib/core.mjs";
-import { readRun, readAdvice, portableSelf } from "./context.mjs";
+import { readAdvice, portableSelf } from "./context.mjs";
+import { readRun } from "../lib/run.mjs";
 import { probeStatus } from "./probe.mjs";
 import { L } from "../i18n/index.mjs";
 

package/tool/i18n/en-docs.mjs

@@ -63,6 +63,7 @@ const enDocs = {
       "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.`,
+    runCannot: (names) => `COULD NOT CHECK (the checks themselves failed — not findings about the code): ${names}`,
     runClean: (when) => `Last run ${when} — nothing red.`,
     runRed: (when, names) => `Last run ${when} — RED: ${names}.`,
     andMore: (n) => `and ${n} more`,

package/tool/i18n/en-gates.mjs

@@ -185,6 +185,33 @@ export const enGates = {
     issue: "Found a bug or it did not fit — open an issue; both are the most useful feedback there is.",
     notRemembered: "could not remember this (home is not writable) — the message will appear again",
     once: "This message is shown once: it will not appear again on this machine.",
+
+    ask: {
+      cannot: (names, cmd) =>
+        `AQK could not check: ${names}. That is the most valuable thing to tell the author — ${cmd}`,
+      blind: (names, cmd) =>
+        `The probe found defect classes nobody catches here: ${names}. Does that match your experience? — ${cmd}`,
+      red: (names, cmd) =>
+        `The kit caught: ${names}. One line to the author — did it help: ${cmd}`,
+      once: "Asked once per project; switch it off with AQK_FEEDBACK=0",
+      agent: "Say this to the human in one sentence, and do not insist if they do not answer.",
+    },
+    how: "Sending is one click (a prefilled issue opens; the text stays editable):",
+    issueTitle: "Feedback on the kit",
+    nothingSent: "Nothing was sent: the kit makes no outgoing requests other than the version check.",
+    orPaste: (cmd) => `No GitHub? Forward the text above as is — all of it comes from ${cmd}`,
+    report: {
+      title: "### Feedback on the kit",
+      unknown: "unknown",
+      none: "none",
+      env: (v, node, os) => `version: ${v} · node: ${node} · system: ${os}`,
+      level: (x) => `level: ${x}`,
+      stack: (x) => `stack: ${x}`,
+      gates: (n, red, cannot) => `gates declared: ${n} · red: ${red} · could not check: ${cannot}`,
+      blind: (x) => `classes nobody catches here: ${x}`,
+      say: "What you would say in your own words (one line — the most useful part of the whole message):",
+      mark: (v) => `<!-- collected by "aqk feedback" ${v}: no paths, no code, no repository name -->`,
+    },
   },
 
   note: {