agent-quality-kit 0.12.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

@@ -26,10 +26,11 @@ import { readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, extname } from "node:path";
 import { readManifest } from "../lib/manifest.mjs";
-import { fixHotspots, probeSummary, probeVerdictPaired, countProbe } from "../lib/history.mjs";
+import { fixHotspots, probeSummary, probeVerdictPaired, countProbe, namesPlant, catchVerdict } from "../lib/history.mjs";
 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";
 
@@ -95,7 +96,7 @@ async function writeMark(now, blind, lines) {
     "",
     ...lines,
     "",
-    "Файл эфемерный: его переписывает каждая проба. В .gitignore его стоит держать самому.",
+    "Файл эфемерный: его переписывает каждая проба. `aqk init` кладёт его в .gitignore.",
   ].join("\n");
   await writeFile(MARK(), body + "\n", "utf8");
 }
@@ -156,58 +157,11 @@ function sampleLines(path, max = 4) {
     .map((l) => l.slice(0, 88));
 }
 
-// Совет по НЕПОКРЫТОМУ классу: команда, которую можно вставить прямо сейчас.
-//
-// Проба находит настоящие дыры и печатала про них «close it: aqk add <имя>» — то есть «поставь
-// нашу штуку». Человек, впервые увидевший комплект, закрывает окно. А готовая однострочная
-// команда под его стек У НАС УЖЕ ЛЕЖИТ в `recipes` записи каталога; мы её не показывали.
-//
-// Замер руками на `requests` (самый скачиваемый python-пакет) 2026-09-10: в
-// `src/requests/utils.py` — 75 коммитов-починок; дописана функция с `except Exception: pass`;
-// их собственные `ruff` и `pytest` дали 0 и на чистой копии, и на подсаженной. Строка, которая
-// поймала бы это, лежала в нашем каталоге всё это время.
-//
-// Переносимый рецепт (`any`) в совет НЕ идёт: он зовёт файл из комплекта, и человеку без
-// комплекта вставить его некуда. Нет родного рецепта под стек — команды нет, и это честнее
-// выдуманной.
-function blindAdvice(entry, facts, hot = {}) {
-  const recipes = entry?.recipes && typeof entry.recipes === "object" ? entry.recipes : {};
-  // `langs` приходит МНОЖЕСТВОМ, а не массивом — `Array.isArray` тихо давал пустой список, и
-  // совет не печатался вовсе. Поймано на живом `requests`: langs = Set(1) { python }.
-  const langs = facts?.langs ? [...facts.langs] : [];
-  // Тот же порядок, что у `pickRecipe`: свой язык → безъязыковой родной → ничего. Переносимый
-  // (`any`) сюда не идёт никогда: он зовёт файл из комплекта, и человеку без комплекта вставить
-  // его некуда.
-  let cmd = null;
-  for (const key of [...langs, "native"]) {
-    const r = recipes[key];
-    if (!r || /\{gate\}/.test(r)) continue;
-    cmd = String(r).replace(/\{dir\}/g, ".")
-      // Вычистить то, что относится к НАМ, а не к его проекту. Исключение наших красных
-      // образцов нужно УСТАНОВЛЕННОМУ гейту — рядом с ним лежат образцы. Человеку, который
-      // команду только копирует, этих каталогов не существует, и флаги про них подрывают
-      // доверие: инструмент говорит про чужое хозяйство вместо его кода.
-      .replace(/\s--ignore-pattern\s+'[^']*gates\/[^']*'/g, "")
-      .replace(/\s--ignore-paths=?\s*'[^']*gates\/[^']*'/g, "")
-      .replace(/\s+/g, " ")
-      .trim();
-    break;
-  }
-  // Адрес — того инструмента, которым команда начинается: поле `tool` общее на все языки, и
-  // python-проекту показывалась ссылка на eslint. Первые три слова, а не одно: `npx knip`,
-  // `python -m vulture`. Не совпало — весь список: лишняя ссылка лучше, чем ни одной.
-  const urls = entry?.tool ? String(entry.tool).split(/\s+·\s+/) : [];
-  const head = cmd ? cmd.split(" ").slice(0, 3) : [];
-  const own = urls.find((u) => head.includes(u.replace(/\/+$/, "").split("/").pop()));
-  const tool = own ?? (entry?.tool ? String(entry.tool) : null);
-  return { command: cmd, tool, file: hot.file ?? null, fixes: hot.fixes ?? null, slug: entry?.slug ?? null };
-}
-
 // Красный образец записи, подходящий по расширению горячего файла. Расширение обязано
 // совпадать: питоновский образец в проекте на TypeScript не проверит ничего, а покажет
 // «не прикрыто» — ложная тревога того же класса, что молчащий гейт, только наоборот.
-async function redSampleFor(entry, ext) {
-  const dir = join(GATES_SRC, entry, "red");
+async function sampleFor(entry, ext, kind = "red") {
+  const dir = join(GATES_SRC, entry, kind);
   if (!(await exists(dir))) return null;
   let names = [];
   try { names = await readdir(dir); } catch { return null; }
@@ -226,7 +180,8 @@ async function redSampleFor(entry, ext) {
 //
 // Способ взят из мутационного тестирования, где та же задача решена двадцать лет назад: Stryker
 // копирует проект во временный каталог, СИМЛИНКУЕТ `node_modules` и гоняет там родную команду.
-// Копируются только ОТСЛЕЖИВАЕМЫЕ файлы (`git archive HEAD`) — рабочее дерево не трогается, а
+// Копируются отслеживаемые и неигнорируемые файлы (`git ls-files --cached --others
+// --exclude-standard`) — файлы проекта не меняются (итог пишется в .aqk/last-probe.md), а
 // мусор сборки не тащится; тяжёлые каталоги зависимостей симлинкуются, иначе `npm test` в
 // песочнице падал бы с «модуль не найден», и это читалось бы как сбой инструмента.
 const DEP_DIRS = ["node_modules", ".venv", "venv", "vendor", "target", ".tox", ".bundle"];
@@ -284,20 +239,44 @@ async function plant(root, relPath, sample) {
 // Гейт запускается В ПЕСОЧНИЦЕ и командой КАК ЕСТЬ — ничего в неё не подставляется. Именно это
 // и делает пробу независимой от формы команды.
 //
-// `stopOnRed` — ранний выход: как только гейт покраснел, вердикт «поймано» уже получен, и гонять
-// остальные незачем. На сухом прогоне выхода нет: там нужны ВСЕ длительности и все коды.
-function runGates(gates, sandbox, { stopOnRed = false } = {}) {
+// Вывод гейта сохраняется: по нему видно, ИЗ-ЗА ЧЕГО он покраснел (см. catchVerdict).
+function runGates(gates, sandbox) {
   const out = [];
   for (const [name, cmd] of gates) {
     const t0 = Date.now();
     const r = spawnSync(gateCommand(cmd), { shell: true, cwd: sandbox, encoding: "utf8", timeout: 120000 });
     const code = r.status === null ? 2 : r.status;
-    out.push({ name, code, ms: Date.now() - t0 });
-    if (stopOnRed && code === 1) break;
+    out.push({ name, code, ms: Date.now() - t0, out: `${r.stdout || ""}${r.stderr || ""}`.slice(0, 200000) });
   }
   return out;
 }
 
+// Один класс брака на одном файле: гейты по одному, в порядке плана. Покраснел и назвал файл —
+// контроль ЗЕЛЁНЫМ образцом той же записи в том же месте (catchVerdict). Ранний выход — только на
+// ПОДТВЕРЖДЁННОЙ поимке: первым мог покраснеть форматтер, и остановка на нём скрыла бы линтер,
+// который брак действительно поймал.
+async function probeOne({ sandbox, rel, red, green, gates, baseOut }) {
+  const after = [];
+  let restore = await plant(sandbox, rel, red);
+  try {
+    for (const g of gates) {
+      const [res] = runGates([g], sandbox);
+      after.push(res);
+      if (res.code !== 1) continue;
+      let ctl = null;
+      if (green && namesPlant(baseOut(res.name), res.out, rel)) {
+        await restore(); restore = await plant(sandbox, rel, green);
+        [ctl] = runGates([g], sandbox);
+        await restore(); restore = await plant(sandbox, rel, red);
+      }
+      res.why = catchVerdict(baseOut(res.name), res, ctl, rel);
+      res.named = res.why === "caught";
+      if (res.named) break;
+    }
+  } finally { await restore(); }
+  return after;
+}
+
 // Каким гейтом пробовать и в каком порядке.
 //
 // Цена пробы = (файлы × записи) × сумма длительностей гейтов. На самом комплекте после перехода
@@ -368,7 +347,8 @@ async function cmdProbe(args, { auto = false } = {}) {
   // Пробуем только запланированными, в порядке плана.
   const byName = new Map(gates);
   const probeGates = plan.use.map((g) => [g.name, byName.get(g.name)]);
-  const baseline = plan.use.map((g) => ({ name: g.name, code: g.code }));
+  const baseline = plan.use.map((g) => ({ name: g.name, code: g.code, out: g.out }));
+  const baseOut = (name) => baseline.find((b) => b.name === name)?.out || "";
 
   console.log(c.dim(`  ${P.method(hot.length, entries.length, plan.use.length)}\n`));
   if (plan.tooSlow.length) {
@@ -385,20 +365,20 @@ async function cmdProbe(args, { auto = false } = {}) {
     let probed = 0;
 
     for (const e of entries) {
-      const sample = await redSampleFor(e.slug, ext);
+      const sample = await sampleFor(e.slug, ext, "red");
       if (!sample) continue;
       probed++;
-      const restore = await plant(sandbox, rel, sample);
-      let after;
-      try { after = runGates(probeGates, sandbox, { stopOnRed: true }); } finally { await restore(); }
+      const green = await sampleFor(e.slug, ext, "green");
+      const after = await probeOne({ sandbox, rel, red: sample, green, gates: probeGates, baseOut });
       // Ранний выход обрывает список: гейты, до которых не дошли, считаются такими же, как на
       // сухом прогоне. Иначе их отсутствие прочиталось бы как сбой запуска.
       const seen = new Set(after.map((a) => a.name));
       const full = after.concat(baseline.filter((b) => !seen.has(b.name)));
       const r = probeVerdictPaired(baseline, full);
       const verdict = r.verdict;
-      const caught = full.filter((a) => a.code === 1 && baseline.find((b) => b.name === a.name)?.code === 0)
-        .map((a) => a.name);
+      const redNow = full.filter((a) => a.code === 1 && baseline.find((b) => b.name === a.name)?.code === 0);
+      const caught = redNow.filter((a) => a.named !== false).map((a) => a.name);
+      const nameless = redNow.filter((a) => a.named === false).map((a) => `${a.name} (${a.why === "planting" ? P.planting : P.nameless})`);
       records.push({ entry: e.slug, file: rel, verdict });
       if (verdict === "caught") {
         console.log(`    ${c.green("✔")}  ${e.intent.padEnd(48)} ${c.dim(P.caught(caught.join(", ")))}`);
@@ -419,7 +399,7 @@ async function cmdProbe(args, { auto = false } = {}) {
         if (adv.tool) console.log(c.dim(`         ${P.blindTool(adv.tool)}`));
         console.log(c.dim(`         ${P.install(`${SELF} add ${e.slug}`)}`));
       } else {
-        console.log(`    ${c.dim("~")}  ${c.dim(e.intent.padEnd(48))} ${c.dim(P.unknown)}`);
+        console.log(`    ${c.dim("~")}  ${c.dim(e.intent.padEnd(48))} ${c.dim(nameless.length ? P.unattributed(nameless.join(", ")) : P.unknown)}`);
       }
     }
     if (!probed) { unprobedN++; console.log(c.dim(`    ${P.noSampleFor(ext || "—")}`)); }
@@ -442,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)})`),
@@ -462,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, blindAdvice, isCode };
+export { cmdProbe, probeStatus, probeableGates, gatesState, extAlternatives, planProbeGates, isCode };

package/tool/commands/project.mjs

@@ -6,7 +6,7 @@ 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 } from "../lib/core.mjs";
+  copyDir, writeIfAbsent, FEEDBACK_MARK, docPath, ensureIgnored } from "../lib/core.mjs";
 import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
 import { banner } from "../lib/banner.mjs";
 import { readManifest } from "../lib/manifest.mjs";
@@ -41,6 +41,10 @@ async function cmdInit(args) {
   const claude = join(CWD, "CLAUDE.md");
   track(await writeIfAbsent(claude, CLAUDE_MD, { force }), claude);
 
+  // Служебные файлы — в .gitignore сразу, до первого прогона: иначе первый же `doctor --run`
+  // оставит в дереве файл, который попадёт в коммит (так и случилось на живом проекте).
+  const ignored = await ensureIgnored(CWD);
+
   // Заставка в начале init — первая встреча человека с комплектом. Второй раз он увидит её
   // только если сам спросит `--version`: то, что видишь тридцатый раз, перестаёт читаться.
   console.log(`\n${banner()}\n`);
@@ -56,6 +60,7 @@ async function cmdInit(args) {
   if (LANG === "en" && created.some((f) => f.includes(`${TARGET_DIR}/docs/`) || f.includes(`${TARGET_DIR}\\docs\\`))) {
     console.log(c.dim(`\n  ${L.init.docsRu}`));
   }
+  if (ignored.length) console.log(c.dim(`\n  ${L.init.ignored(ignored.join(", "))}`));
   if (skipped.length) {
     console.log(c.yellow(`\n  ${L.init.kept(skipped.length)}`));
     for (const f of skipped) console.log(`    ${f}`);

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/commands/report.mjs

@@ -86,7 +86,7 @@ async function cmdReport() {
 
   // Прогон, а не чтение манифеста: «объявлен» и «работает» — разные утверждения, и весь
   // смысл этой команды в том, чтобы в отчёт попало второе.
-  const run = declared.length ? runGates(man) : { results: [], failed: 0 };
+  const run = declared.length ? await runGates(man) : { results: [], failed: 0 };
 
   const held = [], broken = [], todo = [], skip = [];
   for (const res of run.results) {

package/tool/commands/vitals.mjs

@@ -16,9 +16,10 @@
 // сознательное решение: pre-commit локально мы не ставим, проверки идут в CI. Команда, которая
 // кричит «сломано» про выбор, — ровно та, которую выключают в первый день, и вместе с ней
 // перестают читать настоящие отказы. Кода возврата касается только `✘`.
+import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CWD, MANIFEST, SELF, c, exists } from "../lib/core.mjs";
+import { CWD, MANIFEST, SELF, c, exists, preCommitHook } from "../lib/core.mjs";
 import { readManifest, unparsedLines, gateRequires } from "../lib/manifest.mjs";
 import { whichSync } from "../lib/repo.mjs";
 import { gitBash } from "../lib/execution.mjs";
@@ -122,14 +123,7 @@ async function cmdVitals() {
   // Хук pre-commit проверяется в `.git/hooks`, а НЕ в `.pre-commit-config.yaml`. Запись в
   // конфиге — это намерение; сработает только то, что лежит в самом гите. Ровно та разница,
   // ради которой весь комплект: объявлено и работает — разные утверждения.
-  let preCommit = null;
-  const hook = join(CWD, ".git", "hooks", "pre-commit");
-  if (await exists(join(CWD, ".git"))) {
-    preCommit = false;
-    if (await exists(hook)) {
-      try { preCommit = /pre-commit|aqk/i.test(await readFile(hook, "utf8")); } catch { preCommit = null; }
-    }
-  }
+  const preCommit = await preCommitHook(CWD);
 
   let sessionHook = null;
   const settings = join(CWD, ".claude", "settings.json");
@@ -145,15 +139,25 @@ async function cmdVitals() {
 
   let version = null;
   if (updateWanted()) {
+    let current = "";
     try {
       const { PKG_ROOT } = await import("../lib/core.mjs");
-      const current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || "";
+      current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || "";
       const r = await fetch("https://registry.npmjs.org/agent-quality-kit/latest", {
         signal: AbortSignal.timeout(3000),
         headers: { accept: "application/vnd.npm.install-v1+json" },
       });
       version = { current, latest: r.ok ? String((await r.json()).version || "") : "" };
-    } catch { /* сети нет — строку про версию просто не покажем */ }
+    } catch { /* прямой запрос не прошёл — ниже спросим npm */ }
+    // ПРЯМОЙ ЗАПРОС НЕ ПРОШЁЛ — СПРОСИТЬ NPM. Отзыв с живого проекта 2026-09-11: vitals писал «не
+    // достучался до реестра», а `npm view` на той же машине работал. `fetch` в Node не знает
+    // прокси и зеркала из .npmrc, а npm знает. Только здесь, не в хуке: там секунды дороже.
+    if (current && !version?.latest) {
+      const r = spawnSync("npm", ["view", "agent-quality-kit", "version"],
+        { encoding: "utf8", timeout: 10000, shell: process.platform === "win32" });
+      const latest = r.status === 0 ? String(r.stdout || "").trim().split("\n").pop() : "";
+      version = { current, latest };
+    }
   }
 
   const rows = vitalsRows({ tools: [...seen.values()], unparsed, preCommit, sessionHook, version });

package/tool/i18n/en-docs.mjs

@@ -66,7 +66,7 @@ const enDocs = {
     runClean: (when) => `Last run ${when} — nothing red.`,
     runRed: (when, names) => `Last run ${when} — RED: ${names}.`,
     andMore: (n) => `and ${n} more`,
-    skipped: (n) => `Not run: ${n} — the tool is absent on this machine, their state is unknown.`,
+    skipped: (n) => `Not run: ${n} — skipped by --only/--skip or the tool is absent on this machine; their state is unknown.`,
     probeNever: "No coverage probe has run — what is covered by nothing here is UNKNOWN. That is not \"covered\": `aqk probe`.",
     probeOff: "The coverage probe is switched off in the manifest (`probe: 0`) — nobody counts what is covered by nothing here.",
     probeUnknown: "The coverage probe could not run — what is covered by nothing here is UNKNOWN. That is not \"covered\".",
@@ -79,6 +79,26 @@ const enDocs = {
       (behind ? ` (${behind} commits behind)` : "") + ".",
     ratchets: (list) => `Ratchets: ${list}. The list may only get shorter, never longer.`,
     where: (entry) => `The rulebook: ${entry}. What proves a diff: \`aqk report --since main\`.`,
+    nextTitle: "Next, in order — computed from this repository, not generic advice:",
+    nextStep: {
+      init: () => "Set up the standard: `aqk init` — without .aqk.yml `aqk add` refuses.",
+      adopt: (s) => `Declare the checks this project already has: in .aqk.yml, under gates: ${s.gates.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Then \`aqk doctor --run\`.`,
+      blind: (s) => `The "${s.slug}" defect the probe planted in ${s.file} was NOT caught by your checks.` +
+        (s.command ? ` Catch it now: \`${s.command}\`.` : "") + ` Keep it caught: \`aqk add ${s.slug}\`.`,
+      start: (s) => `Install ${s.slug}: \`aqk add ${s.slug}\`` + (s.command ? ` (one line, no kit needed: \`${s.command}\`)` : "") +
+        ", then `aqk prove` — the gate must go red on its own red sample.",
+    },
+    nextMore: (n) => `And ${n} more — the full list: \`aqk doctor\`.`,
+    whenTitle: "When to do what:",
+    whenCommit: (hook) => hook === true
+      ? "Before a commit → the `.git/hooks/pre-commit` hook runs the checks itself; do not bypass it (`--no-verify`)."
+      : "Before a commit → `aqk doctor --run --since main`: there is no pre-commit hook, it will not happen by itself.",
+    whenRules: [
+      "Added or changed a check → `aqk prove`: the gate must go red on its own red sample, otherwise it checks nothing.",
+      "Writing a rule into the rulebook → put the arbiter mark next to it, `<!-- aqk: gate-name -->`; no gate — `<!-- aqk: human -->`, which is an admission, not a check.",
+      "A check is in your way → do not weaken it (`|| true`, `--exit-zero`, a suppression without a rule code): stop and ask the owner.",
+      "You think it is done → `aqk report --since main`: every changed file must be named by a check.",
+    ],
     mapTitle: "WHAT THIS TOOL CAN DO. The full list of commands — not a retelling, the same list\nthe help is built from:",
     rulesTitle: (e) => `THE RULEBOOK OF THIS PROJECT (${e}) — verbatim, in full. This is not an invitation\nto read it: it is already here.`,
     hookAlready: (p) => `the hook is already in ${p} — changing nothing.`,
@@ -196,6 +216,7 @@ const enDocs = {
     },
   ],
   report: {
+    skippedBySelect: "not run (by --only/--skip), state unknown",
     title: "aqk doctor --run",
     version: "version",
     level: "level",

package/tool/i18n/en-gates.mjs

@@ -158,6 +158,7 @@ export const enGates = {
       "the guides in .aqk/docs/ are in Russian — a deliberate decision, not a broken install.\n  The rules in .aqk/rules/ are in English; the guides are prose an agent may ignore anyway,\n  and what a machine holds lives in .aqk.yml and the gates. Translation waits for someone who needs it.",
     created: (n) => `created (${n}):`,
     andMore: (n) => `… and ${n} more`,
+    ignored: (list) => `the kit's runtime files were added to .gitignore — machine state, it does not belong in git: ${list}`,
     kept: (n) => `already there, left untouched (${n}):`,
     overwrite: (cmd) => `overwrite: ${cmd}`,
     nextTitle: "What to do next, in order:",
@@ -255,16 +256,20 @@ export const enGates = {
     badEvery: (v) => `the manifest says probe: "${v}", which is not a commit count. The probe does NOT run: silently using the default would mean doing something other than what is written.`,
     autoFirst: "no coverage probe has ever run here — running it myself. Turn off: AQK_PROBE=0",
     auto: (n) => `${n} commits since the last probe — running it myself. Turn off: AQK_PROBE=0`,
+    autoNotInCi: (cmd) => `in CI the probe does not run by itself — it would be minutes of surprise in a fast check; run it as a separate job: ${cmd} (or AQK_PROBE=1)`,
     title: "aqk probe — what the declared checks cannot see",
     method: (files, entries, gates) =>
       `method: a red sample from a catalogue entry is planted into a COPY of the project, then the ` +
       `DECLARED gates are run there — the command is used as written, nothing is substituted into it. ` +
       `Files: ${files}, applicable entries: ${entries}, gates green on a clean checkout: ${gates}. ` +
-      `The working tree is not touched.`,
+      `Project files are not changed; the probe result goes to .aqk/last-probe.md (in .gitignore after init).`,
     fixes: (n) => `fixes in history: ${n}`,
     caught: (names) => `caught by: ${names}`,
     blind: "NOTHING CATCHES IT",
     unknown: "nothing to check with — the gate did not run (delegated tool missing)",
+    nameless: "did not name the planted file",
+    planting: "goes red on the green sample too — fails from the planting itself",
+    unattributed: (g) => `went red: ${g} — the catch is not proven`,
     blindWhere: (file, fixes) => `where: ${file} — ${fixes} fix commits in its history`,
     blindWhat: "what we planted into your file:",
     blindFix: (cmd) => `catch it right now, no kit needed:  ${cmd}`,