agent-quality-kit 0.13.0 → 0.14.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/prompt.mjs

@@ -0,0 +1,69 @@
+// 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 { readRun, readAdvice, portableSelf } from "./context.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.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:
@@ -45,6 +51,7 @@ export const en = {
     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",
     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 +80,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 +110,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",
@@ -216,7 +242,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 +268,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.mjs

@@ -10,12 +10,20 @@ import { templates } from "./templates-ru.mjs";
 
 import { ruGates } from "./ru-gates.mjs";
 
+// «(коммитов с тех пор: 3)» — без склонений: число рядом со словом в родительном падеже
+// читается одинаково при любом числе.
+const ago = (n) => (n === null || n === undefined ? "" : ` (коммитов с тех пор: ${n})`);
+
 export const ru = {
   learn: {
     title: "Сказано вслух и не записано",
     noLogs: (p) => `логов этого проекта нет: ${p}\n  Команда читает переписку Claude Code на этой машине. Пусто — значит здесь не работали.`,
-    counted: (s, typed, said, fresh) =>
-      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh}`,
+    counted: (s, typed, said, fresh, again) =>
+      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh} · повторено: ${again}`,
+    ruleTitle: "Записано, а поправлять всё равно приходится:",
+    ruleHow: "Правило стоит в своде, а вы повторяете его агенту снова — текстом оно не держится. Ему нужен сторож-машина: aqk find \"…\" или aqk new <имя>.",
+    repeatTitle: "Повторено — вы говорили это не в первый раз («я же говорил», «опять», «снова»):",
+    restTitle: "Остальное, похожее на правило и не записанное:",
     nothing: "всё, что похоже на правило, уже стоит в точке входа",
     andMore: (n) => `… и ещё ${n}`,
     warn:
@@ -46,6 +54,7 @@ export const ru = {
     learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
     context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
     vitals: "подключено ли то, чем комплект работает: инструменты гейтов, хуки, свежесть версии",
+    prompt: "одно задание для агента: что починить, по порядку, и чем доказать, что готово",
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
     report: "обязательная форма отчёта: что стоит, что нет, что не прочитано; --since <ссылка> — ещё и чем доказан диф",
     badge: "значок уровня для README — и проверка, что он не врёт",
@@ -74,6 +83,15 @@ export const ru = {
     coversCantCheck: (entry, gate) => `заявку «${gate} держит ${entry}» проверить не умею: линтер гейта не распознан или правил записи для него нет — принято на слово`,
     selectUnknown: (names, groups) => `--only/--skip: не знаю «${names}» — это не гейт из gates: и не группа из groups:${groups ? ` (группы: ${groups})` : ""}. Прогон всего подряд вместо пропуска был бы неправдой, поэтому стоп.`,
     selectSkipped: (names) => `не запускались (по --only/--skip): ${names} — их состояние неизвестно, это не «зелёные»`,
+    // Claude Code читает CLAUDE.md, а не AGENTS.md — документация Claude Code, раздел «AGENTS.md».
+    claudeShim: {
+      missing: "Claude Code здесь настроен (.claude/), а свод лежит в AGENTS.md — он его не читает. Почини: CLAUDE.md с одной строкой «@AGENTS.md».",
+      noImport: "CLAUDE.md не подключает AGENTS.md — Claude Code видит только CLAUDE.md. Почини: строка «@AGENTS.md» в CLAUDE.md (упоминание словами не загружает файл).",
+    },
+    annotDropped: (n, more) => `пометок в pull request: ${n}, ещё ${more} не показано — GitHub принимает около десяти за шаг; все находки — в логе выше`,
+    heldQuiet: (n, cmd) => `держит машина: ${n} — поимённо: ${cmd}`,
+    skipQuiet: (n, cmd) => `не применимо к этому репозиторию: ${n} — поимённо и почему: ${cmd}`,
+    passedQuiet: (n) => `прошли ещё ${n} — поимённо: --verbose`,
     jobsBad: (v) => `--jobs ждёт целое число от 1: «${v}» не подходит. Прогон по одному под видом параллельного был бы неправдой, поэтому стоп.`,
     rulesByHuman: (total, machine, human) =>
       `правил в точке входа: ${total}. Сторож — ЧЕЛОВЕК у ${human}, машина у ${machine}.`,
@@ -96,6 +114,19 @@ export const ru = {
     toReach: (n) => `Чтобы достичь AQK-${n}:`,
     gives: (what) => `Что это даст: ${what}`,
     allDone: "Все ступени пройдены.",
+    // Чего уровень не доказывает. Ступени меряют оснащённость: гейты показаны на образцах
+    // каталога. Про файлы проекта знает только проба — строка говорит ровно то, что знает она.
+    limitsTitle: "Уровень — это оснащённость, а не надёжность. Чего он не доказывает:",
+    limitsProbe: {
+      never: (_, cmd) => `брак в ваших файлах: проба не запускалась — ${cmd}`,
+      off: () => "брак в ваших файлах: проба выключена (probe: 0) — ловят ли его проверки, неизвестно",
+      blind: ({ names, behind }) => `брак в ваших файлах: проба${ago(behind)} НЕ поймала — ${names.join(", ")}`,
+      partial: ({ caught, unknown, behind }, cmd) => `брак в ваших файлах: проба${ago(behind)} — поймано классов ${caught}, у ${unknown} поимка не доказана (${cmd})`,
+      caught: ({ caught, behind }) => `брак в ваших файлах: проба${ago(behind)} поймала все ${caught} подсаженных классов — только тех, что есть в каталоге`,
+      nothing: ({ behind }, cmd) => `брак в ваших файлах: проба${ago(behind)} ничего не подсадила — ${cmd}`,
+      old: ({ behind }, cmd) => `брак в ваших файлах: проба была${ago(behind)}, итог покажет ${cmd}`,
+    },
+    limitsCi: "конвейер: прошёл ли он, отсюда не видно — проверяется только, что гейты в нём объявлены",
 
     gatesHeading: "Гейты",
     langs: "языки",
@@ -222,7 +253,7 @@ export const ru = {
       has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
       has_mcp: ["агенту здесь не подключали внешних инструментов через MCP", "MCP-серверы объявлены"],
-      has_api_spec: ["не видно спецификации API", "спецификация API есть"],
+      has_api_spec: ["не видно договора API: ни файла OpenAPI, ни tRPC, ts-rest или провайдера типов Fastify", "договор API есть: файл спецификации или схемы в коде"],
     },
   },
 
@@ -249,5 +280,45 @@ export const ru = {
     alreadyDeclared: "уже объявлен",
   },
 
+  // Задание агенту одним текстом (`aqk prompt`). У КАЖДОГО пункта хвост «Готово — …» с
+  // командой-арбитром: пункт без неё агент закроет словами «сделал» — это сторожит модульная проверка.
+  prompt: {
+    title: "# Задание: довести проверки проекта до рабочих",
+    intro: "Составлено AQK по состоянию репозитория. Выполняй пункты по порядку.",
+    rulesTitle: "## Правила",
+    rules: [
+      "Команды бери только из этого задания и из репозитория. Не выдумывай.",
+      "Сначала запусти проверку пункта и убедись, что она красная. Потом чини. Готово — когда та же команда зелёная.",
+      "Чини код, а не проверку: не ослабляй порог, не добавляй исключений, не выключай гейт. Считаешь проверку неправой — остановись и спроси владельца.",
+      "Решение, которое может принять только владелец (что ставить в проект, какие правила вводить), — спроси, а не угадывай.",
+      "Меняй только то, что нужно для этих пунктов.",
+    ],
+    tasksTitle: "## Что сделать",
+    empty: "Делать нечего: красных гейтов нет, проба ничего не нашла, ставить нечего. Всё равно выполни проверку ниже.",
+    done: "Готово —",
+    item: {
+      init: (s) => `Заведи манифест: \`${s} init\` — без него остальные команды отказывают. Готово — \`${s} doctor\` показывает уровень.`,
+      runNone: (s) => `Прогона ещё не было. Запусти \`${s} doctor --run\` и почини то, что покраснеет, по одному гейту: \`${s} doctor --run --only <имя>\`. Готово — прогон зелёный.`,
+      runStale: (s, when) => `Прогон ${when} старше последнего коммита — список красных ниже может быть про другой код. Запусти \`${s} doctor --run\` заново. Готово — у тебя свежий итог, и пункты ниже сверены с ним.`,
+      missed: ({ slug, file }, s) => `Гейт \`${slug}\` стоит, но пропустил брак, который проба подсадила в \`${file}\`. Разберись почему — частая причина: гейт не смотрит этот тип файлов или каталог; подробности даст \`${s} probe\`. Готово — \`${s} probe\` больше не называет этот класс.`,
+      red: (name, s) => `Гейт \`${name}\` красный. Запусти \`${s} doctor --run --only ${name}\`, прочитай находки и почини код. Готово — эта команда зелёная.`,
+      blind: ({ slug, file, command }, s) => `Проба подсадила брак класса \`${slug}\` в \`${file}\`, и проверки проекта его не заметили. Поставь проверку: \`${s} add ${slug}\`${command ? ` (то же одной строкой, без комплекта: \`${command}\`)` : ""}. Готово — \`${s} doctor --run --only ${slug}\` проходит, а \`${s} probe\` больше не называет этот класс.`,
+      adopt: (gates, s) => `У проекта уже есть свои проверки: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Впиши их в gates: манифеста .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Готово — \`${s} doctor --run\` их запускает.`,
+      shim: {
+        missing: (s) => `Claude Code здесь настроен, а правила лежат в AGENTS.md — он читает только CLAUDE.md. Создай CLAUDE.md с одной строкой \`@AGENTS.md\`. Готово — \`${s} doctor\` об этом больше не предупреждает.`,
+        noImport: (s) => `CLAUDE.md не подключает AGENTS.md — Claude Code видит только CLAUDE.md. Добавь в CLAUDE.md строку \`@AGENTS.md\` (упоминание словами файл не загружает). Готово — \`${s} doctor\` об этом больше не предупреждает.`,
+      },
+      // Запись каталога — предложение, а не факт о проекте: ставить или нет, решает владелец.
+      // Красный гейт и брак из пробы — факты, там «почини»; здесь — «предложи».
+      start: ({ slug, intent, command }, s) => `Предложи владельцу проверку \`${slug}\`${intent ? ` — ${intent}` : ""}. Согласен — \`${s} add ${slug}\`${command ? ` (то же одной строкой, без комплекта: \`${command}\`)` : ""}. Краснеет на существующем коде — не глуши её, покажи находки владельцу. Готово — \`${s} doctor --run --only ${slug}\` проходит, а \`${s} prove\` показывает её доказанной.`,
+    },
+    more: (n, s) => `И ещё ${n} — полный список: \`${s} doctor\`. Сначала закончи эти.`,
+    verifyTitle: "## Как проверить, что готово",
+    verify: (s) => [
+      `\`${s} doctor --run\` — прогон зелёный.`,
+      `\`${s} prove\` — ни один гейт не сломан: каждый краснеет на своём красном образце.`,
+      "В отчёте назови эти команды и их итог. «Выглядит рабочим» — не готово.",
+    ],
+  },
   ...ruGates,
 };