agent-quality-kit 0.13.0 → 0.15.0

package/tool/commands/learn.mjs

@@ -13,10 +13,16 @@
 //     настоящие правила («файл не трогай», «делай прогон с базой обязательно», «никаких
 //     обходных временных путей») и разговорная шелуха примерно поровну.
 //
-// ЧЕГО ЗДЕСЬ НАМЕРЕННО НЕТ. Поиска ПОВТОРОВ — приёма, на котором построен session-analyzer у
-// agent-lint. Замер его не подтвердил: на 67 сессиях владелец не повторяет правило дословно, он
-// говорит его один раз и каждый раз иначе. Те «повторы», что нашлись, оказались задвоением
-// одной реплики в самом логе.
+// ЧЕГО ЗДЕСЬ НАМЕРЕННО НЕТ. Поиска повторов ПО СХОДСТВУ ТЕКСТА — приёма, на котором построен
+// session-analyzer у agent-lint. Замер его не подтвердил: на 67 сессиях владелец не повторяет
+// правило дословно, он говорит его один раз и каждый раз иначе. Те «повторы», что нашлись,
+// оказались задвоением одной реплики в самом логе.
+//
+// ЧТО ЕСТЬ ВМЕСТО НЕГО (2026-09-11). Повтор, который помечает САМ человек: «я же говорил»,
+// «опять», «снова». Не угадывание, что две реплики об одном, а слова «это уже было». На логах
+// двух проектов — 7 и 1 такая реплика, настоящих норм среди них 6 и 1; отбор по маркерам
+// наставления не ловил ни одной. Такой повтор, совпавший с правилом свода, — «записано, а
+// поправлять всё равно приходится»: правилу нужен сторож, текстом оно не держится.
 //
 // ПРИВАТНОСТЬ. Команда читает переписку. Поэтому: только логи ТЕКУЩЕГО проекта (или явно
 // названного), только в терминал, ни строки на диск, код возврата всегда 0. Отчёт, который
@@ -47,14 +53,86 @@ const MARKERS = new RegExp(
 
 // Признаки вставки, а не реплики: длина, код в тройных кавычках, много переносов, пути, ссылки.
 // Каждый добавлен по итогу прогона, а не на всякий случай.
+function isPaste(text) {
+  const t = String(text || "").trim();
+  if (!t || t.length > 400) return true;
+  if (t.includes("```")) return true;
+  if ((t.match(/\n/g) || []).length > 6) return true;
+  if (/https?:\/\//.test(t)) return true;
+  return (t.match(/\S+\/\S+/g) || []).length >= 3;
+}
+
 function looksLikeRule(text) {
+  return !isPaste(text) && MARKERS.test(String(text));
+}
+
+// ПОВТОР — сигнал, который даёт сам человек: «я же говорил», «опять», «снова». Разбор AgentLint
+// 2026-09-11 (research/competitors/agentlint-0xmariowu.md): их SS2 сопоставляет поправку с
+// правилом свода по словам. Замер на логах владельца: из 45 поправок к записанным правилам
+// относятся от силы две — такой приём дал бы шум. А реплик с пометкой повтора в том же проекте
+// 14, настоящих норм среди них 5–6 («опять не хочу плодить файлы», «я же не просил, ты опять не
+// так понял») — и отбор по маркерам наставления выше не ловил НИ ОДНОЙ: слов «всегда»/«никогда»
+// в них нет. `\b` здесь не годится — в JavaScript он не видит границ кириллических слов.
+// Две силы пометки. Сильная — «я же говорил», «сколько раз» — повтор при любой форме реплики.
+// Слабая — «опять», «снова» — только в утверждении: второй прогон на тех же логах показал, что
+// вопрос с ней — недоумение («че опять rust?», «опять в env добавить?»), а не норма. Реплика со
+// значка статуса (⬜ ✅ ❌) — вставленная цитата ответа агента, а не слова человека.
+const STRONG = new RegExp(
+  "(^|[^а-яёa-z])(я же (говорил|говорю|просил|сказал|писал)|говорил же|сколько (раз|можно)|" +
+  "в который раз|(ещё|еще) раз говорю|i (already )?told you)([^а-яёa-z]|$)",
+  "i",
+);
+const WEAK = /(^|[^а-яёa-z])(опять(?! же)|снова|again)([^а-яёa-z]|$)/i;
+
+function isRepeat(text) {
   const t = String(text || "").trim();
-  if (!t || t.length > 400) return false;
-  if (t.includes("```")) return false;
-  if ((t.match(/\n/g) || []).length > 6) return false;
-  if (/https?:\/\//.test(t)) return false;
-  if ((t.match(/\S+\/\S+/g) || []).length >= 3) return false;
-  return MARKERS.test(t);
+  if (isPaste(t) || /^[⬜✅❌☐☑]/u.test(t)) return false;
+  return STRONG.test(t) || (WEAK.test(t) && !t.includes("?"));
+}
+
+// Правила свода: пункты списка с меткой сторожа `<!-- aqk: … -->` — так их размечает комплект.
+// Свод без меток — пункты под заголовком про правила. Заголовок правила — жирное начало или
+// часть до двоеточия: по нему и сверяем, хвост пояснения совпал бы с чем угодно.
+function entryRules(entryText) {
+  const items = [];
+  let cur = null;
+  let section = "";
+  for (const line of String(entryText).split(/\r?\n/)) {
+    const h = /^#{1,4}\s+(.+)$/.exec(line);
+    if (h) { section = h[1]; cur = null; continue; }
+    const b = /^[-*]\s+(.+)$/.exec(line);
+    if (b) { cur = { text: b[1], section }; items.push(cur); continue; }
+    if (cur && /^\s{2,}\S/.test(line)) cur.text += ` ${line.trim()}`;
+    else cur = null;
+  }
+  const marked = items.filter((r) => /<!--\s*aqk:/.test(r.text));
+  const pool = marked.length ? marked : items.filter((r) => /правил|rules|constraints|запрет/i.test(r.section));
+  return pool.map((r) => {
+    const body = r.text.replace(/<!--[\s\S]*?-->/g, "").trim();
+    const title = (/^\*\*([^*]+)\*\*/.exec(body) || /^([^:]{3,60}):/.exec(body) || [, body.slice(0, 100)])[1].trim();
+    return { title, arbiter: (/<!--\s*aqk:\s*(\S+?)\s*-->/.exec(r.text) || [])[1] || null };
+  });
+}
+
+// Слова-пометки повтора и служебные слова по правилу не сверяются: иначе «опять» совпало бы с
+// любым правилом, где оно встретилось.
+const NOT_TOPIC = new Set(["опять", "снова", "говор", "проси", "сказа", "писал", "тольк", "всегд",
+  "никог", "нужно", "можно", "котор", "когда", "чтобы", "этого", "again", "told", "always", "never"]);
+const topic = (t) => new Set(keyWords(t).map(stem).filter((s) => !NOT_TOPIC.has(s)));
+
+// Записано, а поправлять всё равно приходится: повтор, у которого с заголовком правила совпали
+// две основы — или все, если заголовок короче трёх слов.
+function repeatedRules(repeats, entryText) {
+  const out = [];
+  for (const r of entryRules(entryText)) {
+    const t = topic(r.title);
+    if (!t.size) continue;
+    for (const m of repeats) {
+      const common = [...topic(m.text)].filter((s) => t.has(s)).length;
+      if (common >= 2 || (t.size <= 2 && common === t.size)) out.push({ rule: r.title, arbiter: r.arbiter, ...m });
+    }
+  }
+  return out;
 }
 
 // Слова, по которым сверяем сказанное с записанным. Короткие отброшены: на них совпадёт что
@@ -127,6 +205,7 @@ async function cmdLearn(argv = process.argv) {
   try { files = (await readdir(root)).filter((f) => f.endsWith(".jsonl")); } catch { files = []; }
   const seen = new Set();
   const said = [];
+  const repeats = [];
   let typedTotal = 0;
   for (const f of files) {
     let raw = "";
@@ -136,24 +215,45 @@ async function cmdLearn(argv = process.argv) {
       const key = m.text.toLowerCase().slice(0, 200);
       if (seen.has(key)) continue;
       seen.add(key);
-      if (looksLikeRule(m.text)) said.push(m);
+      if (isRepeat(m.text)) repeats.push(m);
+      else if (looksLikeRule(m.text)) said.push(m);
     }
   }
 
   const entry = await readEntry(await readManifest());
-  const fresh = said.filter((m) => saidNotWritten(m.text, entry));
-  fresh.sort((a, b) => String(b.when).localeCompare(String(a.when)));
+  const byDate = (a, b) => String(b.when).localeCompare(String(a.when));
+  const fresh = said.filter((m) => saidNotWritten(m.text, entry)).sort(byDate);
+  const ruleHits = repeatedRules(repeats, entry).sort(byDate);
+  const onRule = new Set(ruleHits.map((h) => h.text));
+  const again = repeats.filter((m) => !onRule.has(m.text)).sort(byDate);
 
-  console.log(`  ${c.dim(L.learn.counted(files.length, typedTotal, said.length, fresh.length))}\n`);
-  if (!fresh.length) {
+  console.log(`  ${c.dim(L.learn.counted(files.length, typedTotal, said.length, fresh.length, repeats.length))}\n`);
+  if (!fresh.length && !repeats.length) {
     console.log(`  ${L.learn.nothing}\n`);
     return;
   }
-  for (const m of fresh.slice(0, limit)) {
-    console.log(`  ${c.dim(m.when)}  ${m.text.slice(0, 150)}`);
+  const show = (m) => console.log(`  ${c.dim(m.when)}  ${m.text.slice(0, 150)}`);
+  // Первым — правило, которое ЗАПИСАНО, а человек всё равно поправляет: текстом оно не держится.
+  if (ruleHits.length) {
+    console.log(`  ${c.bold(L.learn.ruleTitle)}`);
+    for (const h of ruleHits.slice(0, limit)) {
+      console.log(`  ${c.yellow("!")}  ${h.rule}${h.arbiter ? c.dim(`  · aqk: ${h.arbiter}`) : ""}`);
+      console.log(`     ${c.dim(h.when)}  ${h.text.slice(0, 140)}`);
+    }
+    console.log(c.dim(`     ${L.learn.ruleHow}\n`));
+  }
+  if (again.length) {
+    console.log(`  ${c.bold(L.learn.repeatTitle)}`);
+    again.slice(0, limit).forEach(show);
+    if (again.length > limit) console.log(c.dim(`  ${L.learn.andMore(again.length - limit)}`));
+    console.log("");
+  }
+  if (fresh.length) {
+    if (repeats.length) console.log(`  ${c.bold(L.learn.restTitle)}`);
+    fresh.slice(0, limit).forEach(show);
+    if (fresh.length > limit) console.log(c.dim(`\n  ${L.learn.andMore(fresh.length - limit)}`));
   }
-  if (fresh.length > limit) console.log(c.dim(`\n  ${L.learn.andMore(fresh.length - limit)}`));
   console.log(`\n  ${c.yellow(L.learn.warn)}\n`);
 }
 
-export { cmdLearn, logSlug, looksLikeRule, saidNotWritten, typedFrom };
+export { cmdLearn, logSlug, looksLikeRule, saidNotWritten, typedFrom, isRepeat, repeatedRules };

package/tool/commands/probe.mjs

@@ -30,7 +30,7 @@ import { fixHotspots, probeSummary, probeVerdictPaired, countProbe, namesPlant,
 import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
 import { blindAdvice } from "../lib/advice.mjs";
 import { CWD, GATES_SRC, TARGET_DIR, c, SELF, exists } from "../lib/core.mjs";
-import { probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan } from "../lib/cadence.mjs";
+import { probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, parseCounts } from "../lib/cadence.mjs";
 import { L } from "../i18n/index.mjs";
 import { gateCommand } from "../lib/execution.mjs";
 
@@ -422,6 +422,7 @@ async function cmdProbe(args, { auto = false } = {}) {
   // Отметка нужна не для отчёта, а для КАДЕНЦИИ: по ней следующий прогон поймёт, что пора.
   // Без неё команда снова становится тем, о чём надо вспомнить.
   await writeMark(commitCount(), blind, [
+    `caught: ${n.caughtClasses}`, `unknown: ${n.unknownClasses}`,
     `ran: ${probeGates.map(([name]) => name).join(" ")}`, "",
     ...blindLines(records), "",
     ...hot.map(({ path: p2, fixes }) => `- ${p2} (${P.fixes(fixes)})`),
@@ -442,7 +443,8 @@ async function probeStatus() {
   if (every === null) return { state: "unknown", behind: null, badEvery: String(man?.probe) };
   if (every === 0) return { state: "off", behind: null };
   const mark = await readMark();
-  return { ...probeState(mark, commitCount(), every), classes: parseBlind(mark?.text), ran: parseRan(mark?.text) };
+  const text = mark?.text;
+  return { ...probeState(mark, commitCount(), every), classes: parseBlind(text), ran: parseRan(text), counts: parseCounts(text) };
 }
 
 export { cmdProbe, probeStatus, probeableGates, gatesState, extAlternatives, planProbeGates, isCode };

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

@@ -0,0 +1,70 @@
+// tool/commands/prompt.mjs — `aqk prompt`: одно задание для агента — «почини вот это, это и это».
+//
+// ЗАЧЕМ. Между диагнозом и действием не было моста. `doctor` пишет человеку, `context` говорит
+// агенту «как дела», а задание «сделай вот это» человек пересказывал сам — и пересказ терял
+// команды. Идея — из разбора agentlint (research/competitors/agentlint.md, «Задание для агента»):
+// правила поведения сверху, исправления по весу, в конце — как проверить.
+//
+// ЧЕГО У НИХ НЕ БЕРЁМ. У них «проверь» — это «балл вырос». У нас у КАЖДОГО пункта свой арбитр:
+// команда, которая сейчас красная и должна стать зелёной. Иначе агент доложит «сделал» про
+// пункт, который ничем не доказан, — тот самый отказ, против которого весь комплект.
+//
+// НИЧЕГО НЕ ЗАПУСКАЕТ. Читает то же, что `context`: манифест, `.aqk/last-run.md`, отметку пробы,
+// каталог. Задание пишется за секунду, а прогон — работа агента, и она в задании первой строкой,
+// если прогона нет или он устарел: иначе пустое задание прочиталось бы как «всё чисто».
+import { readManifest } from "../lib/manifest.mjs";
+import { claudeShimFor } from "../lib/repo.mjs";
+import { CWD, SELF } from "../lib/core.mjs";
+import { readAdvice, portableSelf } from "./context.mjs";
+import { readRun } from "../lib/run.mjs";
+import { probeStatus } from "./probe.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Больше пяти пунктов за раз агент не удержит — как и человек; остальное называется числом.
+const MAX_ITEMS = 5;
+
+// Чистая функция: состояние → строки задания. Порядок — по тому, насколько пункт ФАКТ о проекте
+// и насколько без него невыполнимы остальные: манифест → прогон → красное → гейт стоит, но
+// пропустил брак из пробы → брак, для которого гейта нет → проверки, которые у проекта уже есть
+// → свод, невидимый Claude Code → «начните с этих трёх» из каталога. Класс из пробы в последнем
+// списке не повторяется.
+function taskText(st, T = L.prompt) {
+  const self = st.self || "aqk";
+  const it = [];
+  if (!st.manifest) it.push(T.item.init(self));
+  if (!st.run) it.push(T.item.runNone(self));
+  else if (st.run.stale) it.push(T.item.runStale(self, st.run.when));
+  for (const name of st.run?.red || []) it.push(T.item.red(name, self));
+  for (const m of st.missed || []) it.push(T.item.missed(m, self));
+  for (const b of st.blind || []) it.push(T.item.blind(b, self));
+  if ((st.adopt || []).length) it.push(T.item.adopt(st.adopt, self));
+  if (st.shim) it.push(T.item.shim[st.shim](self));
+  const seen = new Set((st.blind || []).map((b) => b.slug));
+  for (const s of st.start || []) if (!seen.has(s.slug)) it.push(T.item.start(s, self));
+
+  const out = [T.title, "", T.intro, "", T.rulesTitle, ...T.rules.map((r) => `- ${r}`), "", T.tasksTitle];
+  if (!it.length) out.push(T.empty);
+  it.slice(0, MAX_ITEMS).forEach((line, i) => out.push(`${i + 1}. ${line}`));
+  if (it.length > MAX_ITEMS) out.push(T.more(it.length - MAX_ITEMS, self));
+  out.push("", T.verifyTitle, ...T.verify(self).map((r) => `- ${r}`));
+  return out;
+}
+
+async function cmdPrompt() {
+  const man = await readManifest();
+  let probe = null;
+  try { probe = await probeStatus(); } catch { /* пробы нет — пунктов из неё не будет */ }
+  let advice = { adopt: [], blind: [], start: [], missed: [] };
+  try { advice = await readAdvice(man, probe); } catch { /* не посчитали — выдумывать пункты нельзя */ }
+  // Команда уходит в чужой контекст и, возможно, в чужие руки: абсолютный путь к нашей
+  // программе там не сработает — тот же довод, что у хука `context --install`.
+  console.log(taskText({
+    self: portableSelf(SELF),
+    manifest: Boolean(man),
+    run: await readRun(),
+    shim: await claudeShimFor(CWD),
+    ...advice,
+  }).join("\n"));
+}
+
+export { cmdPrompt, taskText };

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: {

package/tool/i18n/en.mjs

@@ -7,14 +7,20 @@ import { enDocs } from "./en-docs.mjs";
 
 import { templates } from "./templates-en.mjs";
 
+const ago = (n) => (n === null || n === undefined ? "" : ` (${n} commit${n === 1 ? "" : "s"} ago)`);
+
 import { enGates } from "./en-gates.mjs";
 
 export const en = {
   learn: {
     title: "Said out loud, never written down",
     noLogs: (p) => `no logs for this project: ${p}\n  The command reads Claude Code transcripts on this machine. Empty means nobody worked here.`,
-    counted: (s, typed, said, fresh) =>
-      `sessions: ${s} · typed by a human: ${typed} · looks like an instruction: ${said} · not in the entry point: ${fresh}`,
+    counted: (s, typed, said, fresh, again) =>
+      `sessions: ${s} · typed by a human: ${typed} · looks like an instruction: ${said} · not in the entry point: ${fresh} · repeated: ${again}`,
+    ruleTitle: "Written down, yet you still have to correct it:",
+    ruleHow: "The rule is in the entry point, and you are repeating it to the agent again — text alone does not hold it. It needs a machine guard: aqk find \"…\" or aqk new <name>.",
+    repeatTitle: "Repeated — you have said this before (\"I told you\", \"again\"):",
+    restTitle: "The rest that looks like a rule and is not written down:",
     nothing: "everything that looks like a rule is already in the entry point",
     andMore: (n) => `… and ${n} more`,
     warn:
@@ -44,7 +50,9 @@ export const en = {
     blob: "assemble the guides into a single GOD_AI.md",
     learn: "rule candidates from local transcripts: said out loud, never written down",
     context: "the project state in one block — for an agent's context, not for reading",
+    feedback: "a report on how the kit worked plus a prefilled link — the only payment it asks",
     vitals: "is what the kit runs on wired up: gate tools, hooks, version freshness",
+    prompt: "one task for the agent: what to fix, in order, and how to prove it is done",
     contextInstall: "the same in full — the map and the rulebook — installed as a hook",
     report: "the mandatory report form: what is in place, what is not, what was not read; --since <ref> adds what proves the diff",
     badge: "a level badge for your README — and a check that it does not lie",
@@ -73,6 +81,14 @@ export const en = {
     coversCantCheck: (entry, gate) => `cannot check the claim "${gate} holds ${entry}": the gate's linter is not recognised or the entry has no rules for it — taken on trust`,
     selectUnknown: (names, groups) => `--only/--skip: "${names}" is neither a gate from gates: nor a group from groups:${groups ? ` (groups: ${groups})` : ""}. Running everything instead of skipping would be a lie, so stopping.`,
     selectSkipped: (names) => `not run (by --only/--skip): ${names} — their state is unknown, they are not "green"`,
+    claudeShim: {
+      missing: "Claude Code is set up here (.claude/), but the rules live in AGENTS.md — it does not read that file. Fix: a CLAUDE.md with the single line \"@AGENTS.md\".",
+      noImport: "CLAUDE.md does not import AGENTS.md — Claude Code only sees CLAUDE.md. Fix: add the line \"@AGENTS.md\" to CLAUDE.md (mentioning the file in prose does not load it).",
+    },
+    annotDropped: (n, more) => `pull request annotations: ${n}, ${more} more not shown — GitHub takes about ten per step; every finding is in the log above`,
+    heldQuiet: (n, cmd) => `held by the machine: ${n} — by name: ${cmd}`,
+    skipQuiet: (n, cmd) => `not applicable to this repository: ${n} — by name and why: ${cmd}`,
+    passedQuiet: (n) => `${n} more passed — by name: --verbose`,
     jobsBad: (v) => `--jobs expects a whole number from 1: "${v}" will not do. A one-by-one run passed off as parallel would be a lie, so stopping.`,
     rulesByHuman: (total, machine, human) =>
       `${human} of ${total} rules in the entry point are guarded by a HUMAN, ${machine} by a machine.`,
@@ -95,6 +111,17 @@ export const en = {
     toReach: (n) => `To reach AQK-${n}:`,
     gives: (what) => `What it buys you: ${what}`,
     allDone: "All levels reached.",
+    limitsTitle: "A level measures tooling, not reliability. What it does not prove:",
+    limitsProbe: {
+      never: (_, cmd) => `defects in your files: the probe has never run — ${cmd}`,
+      off: () => "defects in your files: the probe is off (probe: 0) — whether your checks catch them is unknown",
+      blind: ({ names, behind }) => `defects in your files: the probe${ago(behind)} did NOT catch — ${names.join(", ")}`,
+      partial: ({ caught, unknown, behind }, cmd) => `defects in your files: the probe${ago(behind)} caught ${caught} classes, ${unknown} unproven (${cmd})`,
+      caught: ({ caught, behind }) => `defects in your files: the probe${ago(behind)} caught all ${caught} planted classes — only those the catalog has`,
+      nothing: ({ behind }, cmd) => `defects in your files: the probe${ago(behind)} planted nothing — ${cmd}`,
+      old: ({ behind }, cmd) => `defects in your files: the probe ran${ago(behind)}; ${cmd} shows the result`,
+    },
+    limitsCi: "pipeline: whether it passed is not visible from here — we only check that gates are declared in it",
 
     gatesHeading: "Gates",
     langs: "languages",
@@ -142,6 +169,10 @@ export const en = {
       `either fix them and drop them from advisory, or admit the rule does not exist.`,
     runHeading: "Running the declared gates",
     timeout: "did not finish within 5 minutes",
+    cannotCheck: (why) => `could not check: ${why}`,
+    whySpawn: (code) => `failed to start${code ? ` (${code})` : ""}`,
+    whySignal: (sig) => `killed by signal ${sig || "?"}`,
+    whyExit: (code) => `exit ${code} — for this command that is a failure, not a finding`,
     running: (i, n) => `[${i}/${n}] running…`,
     proving: "checking that the gates catch defects on their own samples…",
     exitCode: (code) => `exit ${code}`,
@@ -216,7 +247,7 @@ export const en = {
       has_agent_entry: ["no entry point for an agent here", "an entry point for an agent exists"],
       has_ui: ["no stylesheets or UI components in sight", "a UI exists: stylesheets or components"],
       has_mcp: ["no MCP tools are wired up for the agent here", "MCP servers are declared"],
-      has_api_spec: ["no API specification in sight", "an API specification exists"],
+      has_api_spec: ["no API contract in sight: no OpenAPI file, no tRPC, ts-rest or Fastify type provider", "an API contract exists: a specification file or schemas in code"],
     },
   },
 
@@ -242,5 +273,41 @@ export const en = {
     alreadyDeclared: "already declared",
   },
 
+  prompt: {
+    title: "# Task: get this project's checks actually working",
+    intro: "Written by AQK from the current state of the repository. Do the items in order.",
+    rulesTitle: "## Ground rules",
+    rules: [
+      "Use only commands from this task and from the repository. Do not invent any.",
+      "Run an item's check first and see it fail. Then fix. Done means the same command passes.",
+      "Fix the code, not the check: do not loosen a threshold, add exclusions or switch a gate off. If you think a check is wrong, stop and ask the owner.",
+      "A decision only the owner can make (what to add to the project, which rules to adopt) — ask, do not guess.",
+      "Change only what these items need.",
+    ],
+    tasksTitle: "## What to do",
+    empty: "Nothing to do: no gate is red, the probe found nothing, nothing to add. Still run the verification below.",
+    done: "Done —",
+    item: {
+      init: (s) => `Create the manifest: \`${s} init\` — without it the other commands refuse. Done — \`${s} doctor\` shows a level.`,
+      runNone: (s) => `There has been no run yet. Run \`${s} doctor --run\` and fix whatever turns red, one gate at a time: \`${s} doctor --run --only <name>\`. Done — the run passes.`,
+      runStale: (s, when) => `The run from ${when} is older than the last commit — the red list below may describe other code. Run \`${s} doctor --run\` again. Done — you have a fresh result and have checked the items below against it.`,
+      missed: ({ slug, file }, s) => `Gate \`${slug}\` is installed but missed the defect the probe planted into \`${file}\`. Find out why — a common cause is that the gate does not look at this file type or folder; \`${s} probe\` has the details. Done — \`${s} probe\` no longer names this class.`,
+      red: (name, s) => `Gate \`${name}\` is red. Run \`${s} doctor --run --only ${name}\`, read the findings and fix the code. Done — that command passes.`,
+      blind: ({ slug, file, command }, s) => `The probe planted a \`${slug}\` defect into \`${file}\` and the project's checks did not notice. Add a check: \`${s} add ${slug}\`${command ? ` (the same as one line, without the kit: \`${command}\`)` : ""}. Done — \`${s} doctor --run --only ${slug}\` passes and \`${s} probe\` no longer names this class.`,
+      adopt: (gates, s) => `The project already has its own checks: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Declare them under gates: in .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Done — \`${s} doctor --run\` runs them.`,
+      shim: {
+        missing: (s) => `Claude Code is set up here, but the rules live in AGENTS.md — it only reads CLAUDE.md. Create a CLAUDE.md with the single line \`@AGENTS.md\`. Done — \`${s} doctor\` no longer warns about it.`,
+        noImport: (s) => `CLAUDE.md does not import AGENTS.md — Claude Code only sees CLAUDE.md. Add the line \`@AGENTS.md\` to CLAUDE.md (mentioning the file in prose does not load it). Done — \`${s} doctor\` no longer warns about it.`,
+      },
+      start: ({ slug, intent, command }, s) => `Propose the \`${slug}\` check to the owner${intent ? ` — ${intent}` : ""}. If they agree — \`${s} add ${slug}\`${command ? ` (the same as one line, without the kit: \`${command}\`)` : ""}. If it fails on existing code, do not silence it — show the findings to the owner. Done — \`${s} doctor --run --only ${slug}\` passes and \`${s} prove\` shows it proven.`,
+    },
+    more: (n, s) => `And ${n} more — the full list: \`${s} doctor\`. Finish these first.`,
+    verifyTitle: "## How to verify it is done",
+    verify: (s) => [
+      `\`${s} doctor --run\` — the run passes.`,
+      `\`${s} prove\` — no gate is broken: each one fails on its own red sample.`,
+      "Name these commands and their results in your report. \"Looks like it works\" is not done.",
+    ],
+  },
   ...enGates,
 };

package/tool/i18n/index.mjs

@@ -29,13 +29,19 @@ import { en } from "./en.mjs";
 // Переменная окружения оставлена ВЫШЕ манифеста намеренно: человек, набравший AQK_LANG=en
 // руками, хочет английский именно сейчас, и спорить с ним манифестом значит отнять у него
 // последнее средство. Манифест выше локали — он про проект, локаль про машину.
-function pickLang(env = process.env, man = null) {
+//
+// Третьим — ЯЗЫК СВОДА ПРОЕКТА, между манифестом и локалью. Отзыв с живого проекта 2026-09-11:
+// свод и методички на русском, Windows без LANG — весь вывод английский, пока руками не впишешь
+// `lang:`. Текст, который проект сам о себе написал, — такое же свойство проекта, как поле
+// манифеста, только необъявленное: поэтому ниже поля и выше машины.
+function pickLang(env = process.env, man = null, docs = "") {
   const forced = String(env.AQK_LANG || "").toLowerCase();
   if (forced.startsWith("ru")) return "ru";
   if (forced.startsWith("en")) return "en";
   const declared = String(man?.lang || "").toLowerCase();
   if (declared.startsWith("ru")) return "ru";
   if (declared.startsWith("en")) return "en";
+  if (docs === "ru" || docs === "en") return docs;
   const locale = String(env.LC_ALL || env.LC_MESSAGES || env.LANG || "").toLowerCase();
   if (locale.startsWith("ru")) return "ru";
   return "en";
@@ -59,8 +65,41 @@ function manifestLang(cwd = process.cwd()) {
   }
 }
 
+// Язык прозы: код, пути и адреса вырезаются — в русском своде половина слов это `npm run check`
+// и `packages/contract`, и по всем буквам подряд он вышел бы английским. Порог с запасом в обе
+// стороны: кириллицы больше половины букв — русский, меньше десятой при хотя бы двухстах
+// буквах — английский; между ними и на коротком тексте свод молчит, и решает локаль.
+function langFromDocs(text) {
+  const prose = String(text)
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`\n]*`/g, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/https?:\/\/\S+/g, " ");
+  const cyr = (prose.match(/[а-яё]/gi) || []).length;
+  const lat = (prose.match(/[a-z]/gi) || []).length;
+  const all = cyr + lat;
+  if (all < 200) return "";
+  if (cyr / all >= 0.5) return "ru";
+  if (cyr / all <= 0.1) return "en";
+  return "";
+}
+
+// Первые 8 КБ каждого из трёх файлов: язык виден по первому экрану, а читать мегабайтный README
+// ради одной буквы в начале каждой команды — дорого.
+function docsLang(cwd = process.cwd()) {
+  let text = "";
+  for (const name of ["AGENTS.md", "CLAUDE.md", "README.md"]) {
+    try {
+      text += readFileSync(join(cwd, name), "utf8").slice(0, 8192) + "\n";
+    } catch {
+      // Файла нет — язык решат остальные.
+    }
+  }
+  return langFromDocs(text);
+}
+
 const CATALOGS = { ru, en };
-const LANG = pickLang(process.env, manifestLang());
+const LANG = pickLang(process.env, manifestLang(), docsLang());
 const L = CATALOGS[LANG];
 
-export { L, LANG, pickLang, langFromText, CATALOGS };
+export { L, LANG, pickLang, langFromText, langFromDocs, CATALOGS };

package/tool/i18n/ru-docs.mjs

@@ -65,6 +65,7 @@ const ruDocs = {
       "Прогон не делался — какие проверки красные, НЕИЗВЕСТНО. Это не «чисто»: `aqk doctor --run`.",
     runStale: (when) =>
       `Последний прогон ${when} СТАРЕЕ последнего коммита — он описывает не тот код, что здесь.`,
+    runCannot: (names) => `НЕ СМОГЛИ ПРОВЕРИТЬ (сбой самих проверок, а не находки о коде): ${names}`,
     runClean: (when) => `Последний прогон ${when} — красных нет.`,
     runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
     andMore: (n) => `и ещё ${n}`,

package/tool/i18n/ru-gates.mjs

@@ -187,6 +187,34 @@ export const ruGates = {
     issue: "Нашёл баг или не подошло — заведи Issue, самая полезная обратная связь: и то и другое.",
     notRemembered: "запомнить не удалось (дом недоступен для записи) — сообщение появится снова",
     once: "Это разовое сообщение: больше не покажется на этой машине.",
+
+    // Просьба ПО ДЕЛУ: у неё всегда есть содержание, иначе её нет вовсе.
+    ask: {
+      cannot: (names, cmd) =>
+        `AQK не смог проверить: ${names}. Это самое ценное, что можно рассказать автору — ${cmd}`,
+      blind: (names, cmd) =>
+        `Проба нашла классы брака, которые здесь не ловит никто: ${names}. Совпало с вашим опытом? — ${cmd}`,
+      red: (names, cmd) =>
+        `Комплект поймал: ${names}. Одна строка автору — помогло или нет: ${cmd}`,
+      once: "Спрашиваем один раз на проект; выключить: AQK_FEEDBACK=0",
+      agent: "Скажи это человеку одной фразой и не настаивай, если он не ответил.",
+    },
+    how: "Отправить — одно нажатие (откроется готовая задача, текст можно править):",
+    issueTitle: "Отзыв о работе комплекта",
+    nothingSent: "Ничего не отправлено: комплект не делает исходящих запросов, кроме проверки версии.",
+    orPaste: (cmd) => `Не хочется GitHub — перешлите текст выше как есть: он весь собран ${cmd}`,
+    report: {
+      title: "### Отзыв о комплекте",
+      unknown: "неизвестно",
+      none: "нет",
+      env: (v, node, os) => `версия: ${v} · node: ${node} · система: ${os}`,
+      level: (x) => `уровень: ${x}`,
+      stack: (x) => `стек: ${x}`,
+      gates: (n, red, cannot) => `гейтов объявлено: ${n} · красных: ${red} · не смогли проверить: ${cannot}`,
+      blind: (x) => `классы, которые здесь не ловит никто: ${x}`,
+      say: "Что сказать своими словами (одна строка — самое полезное во всём письме):",
+      mark: (v) => `<!-- собрано «aqk feedback» ${v}: без путей, без кода, без имени репозитория -->`,
+    },
   },
 
   note: {