agent-quality-kit 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Turns the rules an agent is supposed to follow into commands with exit codes, and reports which of them actually run. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -45,6 +45,9 @@
     "entry": [
       "tool/selfcheck/units.mjs",
       "tool/selfcheck/units-level.mjs",
+      "tool/selfcheck/units-evidence.mjs",
+      "tool/selfcheck/units-learn.mjs",
+      "tool/selfcheck/units-context.mjs",
       "tool/selfcheck/lifecycle.mjs"
     ],
     "project": [

package/tool/commands/context.mjs

@@ -0,0 +1,260 @@
+// tool/commands/context.mjs — состояние репозитория одним коротким блоком, для КОНТЕКСТА агента.
+//
+// ЗАЧЕМ ЭТА КОМАНДА ВООБЩЕ. Первый чужой отзыв, 2026-09-08, раздел «где я сам применил неверно»:
+// «ставил записи, не читая их gate.yml», «не знал, как устроен prove», «не пользовался половиной
+// команд». Файлы лежали. Агент до них не дошёл. Файл — приглашение прочитать, и агент вправе им
+// не воспользоваться; хук `SessionStart` кладёт текст в контекст ДО первого действия, и отказаться
+// от него нельзя. Это и есть вся разница.
+//
+// ПОЧЕМУ НЕ ВЕСЬ СВОД. Соблазн влить в контекст всё правила целиком. Замерено чужими руками и
+// не нами: вход, растущий в длину, роняет качество у ВСЕХ проверенных передовых моделей — модель
+// с окном 200K заметно деградирует уже на 50K, а ближние токены выигрывают у дальних. То есть
+// «влить всё вперёд» даёт обратный результат: правило в контексте есть и не выполняется — ровно
+// тот отказ, против которого весь комплект. Наш замер: этот блок ≈147 токенов, AGENTS.md ≈3348.
+//
+// ПОЭТОМУ ЗДЕСЬ СОСТОЯНИЕ, А НЕ ПРАВИЛА. Свод статичен и лежит в файле — агент его прочитает по
+// ссылке. А вот чего из файла не узнать никогда: какой сейчас уровень, что красное ПРЯМО СЕЙЧАС,
+// сколько правил не держит никто, что лежит в храповике. Это меняется каждый день, и записать
+// это в AGENTS.md значит завести второй список, который через месяц врёт.
+//
+// ТИШИНА НЕ ОЗНАЧАЕТ «ЧИСТО». Читатель здесь машина: человек, увидев пустое место, переспросит,
+// а агент примет его за утверждение. Поэтому каждое незнание называется словом: прогона не было —
+// так и написано, прогон устарел — тоже, инструмента нет — тоже.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { CWD, TARGET_DIR, SELF, c, exists, commandRows } from "../lib/core.mjs";
+import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Больше пяти имён подряд агент всё равно не удержит, а блок ради них раздувается. Остаток
+// называется числом: «и ещё 15» — это факт, а молчание про них было бы враньём.
+const MAX_RED = 5;
+const MAX_RATCHETS = 3;
+
+// Чистая функция: на входе состояние, на выходе строки. Отделена от чтения диска намеренно —
+// это единственное место комплекта, чей текст читает машина, и проверять его надо не прогоном,
+// а перебором случаев, включая те, которых на нашем репозитории не бывает.
+function contextBlock(state, T = L.context) {
+  const out = [T.title, ""];
+
+  out.push(state.level
+    ? T.level(state.level.reached, state.level.top, state.level.missing)
+    : T.levelUnknown);
+
+  if (state.rules && state.rules.total) {
+    const { total, machine, human } = state.rules;
+    out.push(T.rules(total, machine, human) + (human > 0 ? ` ${T.rulesNobody}` : ""));
+  }
+
+  if (!state.run) {
+    out.push(T.runNone);
+  } else {
+    const red = state.run.red || [];
+    const shown = red.slice(0, MAX_RED);
+    const names = red.length > MAX_RED
+      ? `${shown.join(", ")} — ${T.andMore(red.length - MAX_RED)}`
+      : shown.join(", ");
+    out.push(red.length ? T.runRed(state.run.when, names) : T.runClean(state.run.when));
+    if (state.run.stale) out.push(T.runStale(state.run.when));
+    if (state.run.skipped) out.push(T.skipped(state.run.skipped));
+  }
+
+  const rat = (state.ratchets || []).slice(0, MAX_RATCHETS);
+  if (rat.length) out.push(T.ratchets(rat.map((r) => `${r.name} (${r.count})`).join(", ")));
+
+  // ПОЛНЫЙ БЛОК — решение владельца от 2026-09-08, принятое ПОСЛЕ возражения и вопреки ему.
+  // Возражение было такое: вход, растущий в длину, роняет качество у всех проверенных моделей,
+  // и свод, влитый целиком, даёт правило, которое в контексте есть и не выполняется. Ответ
+  // владельца: агент читает файлы плохо, это видно на живых примерах, и лишние токены — плата
+  // за то, чтобы он не ошибался. Решение записано здесь, а не спрятано в истории команд,
+  // потому что через месяц «почему тут вливается всё» будет непонятно никому.
+  //
+  // Умолчание осталось коротким: платит тот, кто выбрал платить.
+  if (state.full) {
+    out.push("", T.mapTitle);
+    // Ширина колонки считается, а не подбирается: имена команд разной длины в двух языках,
+    // и вручную выставленный отступ разъезжается на первом же переводе. Та же причина, что
+    // в справке program.mjs, — и это ещё один довод держать список общим.
+    const w = Math.max(...state.full.rows.map((r) => r.cmd.length));
+    for (const r of state.full.rows) out.push(`  ${r.cmd.padEnd(w)}  ${r.text}`);
+    if (state.full.text) {
+      out.push("", T.rulesTitle(state.full.entry), "");
+      out.push(state.full.text.trimEnd());
+    }
+  }
+
+  // Ссылка на свод даётся, только если файл ЕСТЬ. Назвать агенту несуществующий файл хуже,
+  // чем промолчать: он пойдёт его читать и получит пустоту вместо правил. Замерено на шести
+  // чужих проектах: на flask блок писал «Свод правил: AGENTS.md», которого там нет.
+  if (state.entryExists !== false) out.push("", T.where(state.entry || "AGENTS.md"));
+  return out;
+}
+
+// Разбор отчёта прошлого прогона. Формат кладёт сам `doctor` в .aqk/last-run.md; читаем его,
+// а не запускаем гейты заново: хук обязан укладываться в секунду-две, а прогон у нас идёт минуту.
+function parseLastRun(text) {
+  if (!text) return null;
+  const when = (text.match(/^# aqk doctor --run — (.+)$/m) || [])[1] || "";
+  const red = [];
+  for (const m of text.matchAll(/^✘ ([^\s—]+)/gm)) red.push(m[1]);
+  const skipped = (text.match(/^~ /gm) || []).length;
+  return { when: when.trim(), red, skipped, stale: false };
+}
+
+// Правила и их арбитры: отметка `<!-- aqk: имя -->` рядом с правилом. `человек` — честное
+// признание, что машина этого не держит; так его и считаем, отдельно от машинных.
+function countArbiters(text, humanWords) {
+  // Имя арбитра — это имя гейта, а в нём дефисы: `deps-are-pinned`. Класс исключения `[^\s>-]`
+  // обрывал такое имя и не считал его вовсе. Найдено первым же живым запуском: на нашем своде
+  // блок показал 13 правил вместо 14 и одного машинного арбитра вместо двух.
+  const marks = [...String(text).matchAll(/<!--\s*aqk:\s*(\S+?)\s*-->/g)].map((m) => m[1]);
+  const human = marks.filter((w) => humanWords.includes(w.toLowerCase())).length;
+  return { total: marks.length, machine: marks.length - human, human };
+}
+
+// Прогон старше последнего коммита описывает не тот код, что лежит перед агентом. Молча выдать
+// его за свежий — соврать: именно так «зелёный месяц назад» превращается в «зелёный сейчас».
+function runIsStale(when) {
+  if (!when) return false;
+  const r = spawnSync("git", ["log", "-1", "--format=%cI"], { cwd: CWD, encoding: "utf8" });
+  if (r.status !== 0 || !r.stdout) return false;
+  const commit = Date.parse(r.stdout.trim());
+  const run = Date.parse(when.replace(" ", "T"));
+  return Number.isFinite(commit) && Number.isFinite(run) && run < commit;
+}
+
+
+// УСТАНОВКА ХУКА — отдельной командой, а не частью `init`, и это решение, а не лень. Комплект
+// нейтрален к вендору: правила и гейты не зависят от того, какой нейросетью пишут код. Хук
+// `SessionStart` — принадлежность одного Claude Code, и класть его всем подряд значило бы
+// объявить нейтральность и нарушить её в первой же команде.
+//
+// БЕЗ MATCHER НАМЕРЕННО. Справочник на сайте перечисляет у SessionStart значения matcher
+// (startup, resume, clear, compact), а таблица событий, ВШИТАЯ в установленную версию 2.1.263,
+// показывает в колонке matcher прочерк. Одно из двух неверно, и выяснить это гаданием нельзя.
+// Хук без matcher верен при любом из двух чтений: где matcher поддержан — сработает на всех
+// источниках, где не поддержан — на всех тоже. Проверено чтением бинаря, не памятью.
+const HOOK_FILE = [".claude", "settings.json"];
+
+// Команда, которая пойдёт В ОБЩИЙ файл настроек, а значит и в чужие руки через git. `SELF`
+// печатается для человека здесь и сейчас и на машине разработчика равен АБСОЛЮТНОМУ пути —
+// у соседа по команде такого пути нет, и хук у него молча не сработает. Абсолютный путь
+// заменяется на переносимый вызов из реестра; `aqk` и `npx …` переносимы сами и остаются.
+function portableSelf(self = SELF) {
+  return /^node\s+[/\\]|^node\s+[A-Za-z]:/.test(self) ? "npx agent-quality-kit" : self;
+}
+
+function hookEntry(cmd) {
+  return { hooks: [{ type: "command", command: cmd }] };
+}
+
+// Уже стоит? Тогда ничего не трогаем. Второй такой же хук значит блок в контексте дважды —
+// вдвое больше токенов и ровно ноль пользы.
+function hasOurHook(settings, cmd) {
+  const list = settings?.hooks?.SessionStart;
+  if (!Array.isArray(list)) return false;
+  return list.some((g) => (g?.hooks || []).some((h) => String(h?.command || "").includes(cmd)));
+}
+
+function withHook(settings, cmd) {
+  const next = { ...(settings || {}) };
+  const hooks = { ...(next.hooks || {}) };
+  hooks.SessionStart = [...(Array.isArray(hooks.SessionStart) ? hooks.SessionStart : []), hookEntry(cmd)];
+  next.hooks = hooks;
+  return next;
+}
+
+async function installHook(full = false) {
+  const T = L.context;
+  const path = join(CWD, ...HOOK_FILE);
+  const cmd = `${portableSelf()} context${full ? " --full" : ""}`;
+
+  let settings = {};
+  let existed = false;
+  if (await exists(path)) {
+    existed = true;
+    try {
+      settings = JSON.parse(await readFile(path, "utf8"));
+    } catch {
+      // Чужой файл с испорченным JSON перезаписывать нельзя: там могут быть чьи-то права
+      // доступа, и молча стереть их дороже, чем не поставить хук.
+      console.log(c.red(`  ${T.hookBadJson(path)}`));
+      return;
+    }
+  }
+
+  if (hasOurHook(settings, cmd)) {
+    console.log(c.dim(`  ${T.hookAlready(path)}`));
+    return;
+  }
+
+  await mkdir(join(CWD, HOOK_FILE[0]), { recursive: true });
+  await writeFile(path, JSON.stringify(withHook(settings, cmd), null, 2) + "\n", "utf8");
+  console.log(c.green(`  ${existed ? T.hookAdded(path) : T.hookCreated(path)}`));
+  console.log(c.dim(`    ${JSON.stringify({ SessionStart: [hookEntry(cmd)] })}`));
+  console.log(c.dim(`  ${T.hookWhat}`));
+}
+
+async function cmdContext(args = []) {
+  const full = args.includes("--full");
+  if (args.includes("--install")) return installHook(full);
+
+  const man = await readManifest();
+  const entry = (Array.isArray(man?.entry) ? man.entry : []).find((e) => typeof e === "string" && e.trim())?.trim()
+    || "AGENTS.md";
+
+  let level = null;
+  if (man?.aqk) {
+    const { reached, steps } = await assessLevel(man, null);
+    const next = steps.find((s) => !s.ok);
+    // `assessLevel` без прогона помечает вторую ступень `needsProof`: файлы на месте, а гейты
+    // не доказаны. Сказать здесь «заведи samples и ratchets» значит послать чинить сделанное —
+    // ровно та жалоба, с которой пришёл первый чужой отзыв, только в другом месте программы.
+    const missing = !next ? ""
+      : next.needsProof ? L.doctor.levelUnproven(`${SELF} prove`)
+      : next.need || next.title || "";
+    level = { reached, top: steps.length - 1, missing };
+  }
+
+  let rules = null;
+  if (await exists(join(CWD, entry))) {
+    rules = countArbiters(await readFile(join(CWD, entry), "utf8"), ["человек", "human", "nobody"]);
+  }
+
+  let run = null;
+  const lastRun = join(CWD, TARGET_DIR, "last-run.md");
+  if (await exists(lastRun)) {
+    run = parseLastRun(await readFile(lastRun, "utf8"));
+    if (run) run.stale = runIsStale(run.when);
+  }
+
+  const ratchets = [];
+  const dir = typeof man?.ratchets === "string" ? man.ratchets.trim() : "";
+  if (dir && (await exists(join(CWD, dir)))) {
+    const { readdir } = await import("node:fs/promises");
+    for (const f of (await readdir(join(CWD, dir))).filter((n) => n.endsWith(".txt")).sort()) {
+      const body = await readFile(join(CWD, dir, f), "utf8");
+      const count = body.split("\n").filter((l) => l.trim() && !l.trim().startsWith("#")).length;
+      ratchets.push({ name: f.replace(/\.txt$/, ""), count });
+    }
+  }
+
+  // Свод читается ЦЕЛИКОМ и дословно: пересказ был бы третьим списком рядом с двумя.
+  let fullPart = null;
+  if (full) {
+    const rows = commandRows(L).map((r) => ({
+      cmd: `${portableSelf()} ${r.name}${r.args ? ` ${r.args}` : ""}`,
+      text: r.text,
+    }));
+    let text = "";
+    if (rules !== null) { try { text = await readFile(join(CWD, entry), "utf8"); } catch { text = ""; } }
+    fullPart = { entry, rows, text };
+  }
+
+  console.log(contextBlock({
+    entry, entryExists: rules !== null, level, rules, run, ratchets, full: fullPart,
+  }).join("\n"));
+}
+
+export { cmdContext, contextBlock, parseLastRun, countArbiters, withHook, hasOurHook, portableSelf };

package/tool/commands/doctor.mjs

@@ -5,7 +5,7 @@ import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { scopeOutput, splitAdvice, changedFiles } from "../lib/scope.mjs";
 import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists, die } from "../lib/core.mjs";
-import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS, advisorySet } from "../lib/manifest.mjs";
+import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS, advisorySet, layoutChecks } from "../lib/manifest.mjs";
 import { proveGates } from "../lib/prove.mjs";
 import { detectFacts, readCatalog, triggerVerdict, recipeFor } from "../lib/repo.mjs";
 import { assessBaseline, DEP_FILES, BASELINE_TOTAL } from "../lib/baseline.mjs";
@@ -126,11 +126,15 @@ function runGates(man, opts = {}) {
     const t0 = Date.now();
     const r = spawnSync(cmd, { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
     const secs = (Math.max(0, Date.now() - t0) / 1000).toFixed(1);
+    // Вывод гейта запоминается целиком (с потолком, чтобы болтливый инструмент не съел память):
+    // по нему считается покрытие дифа — какой файл вообще был назван хоть одной проверкой.
+    // Без этого «готово = доказано» остаётся правилом, за которым следит только человек.
+    const outAll = `${r.stdout || ""}${r.stderr || ""}`.slice(0, 200000);
 
     if (r.error && r.error.code === "ETIMEDOUT") {
       console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.timeout)}`);
       failed++;
-      results.push({ name, cmd, ok: false, secs, note: L.doctor.timeout });
+      results.push({ name, cmd, ok: false, secs, note: L.doctor.timeout, out: outAll });
       continue;
     }
     const code = r.status;
@@ -142,7 +146,7 @@ function runGates(man, opts = {}) {
       // Показываем ровно строки с меткой совета: остальной вывод успешной проверки — шум.
       const okAdvice = splitAdvice(`${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean)).advice;
       for (const line of okAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
-      results.push({ name, cmd, ok: true, secs });
+      results.push({ name, cmd, ok: true, secs, out: outAll });
     } else {
       const raw = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
       // Совет отделяется ДО сужения. Иначе он сам попадает под фильтр по путям: сообщение
@@ -163,14 +167,14 @@ function runGates(man, opts = {}) {
           // выдать провал за тишину; остаётся красным, и причина названа.
           console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${L.doctor.notScopable}`)}`);
           failed++;
-          results.push({ name, cmd, ok: false, secs, code, note: L.doctor.notScopable });
+          results.push({ name, cmd, ok: false, secs, code, note: L.doctor.notScopable, out: outAll });
           continue;
         }
         if (s.findings === 0) {
           // Долг есть, но не в том, что внёс диф. Зелёный — но с числом спрятанного: молчаливое
           // «всё хорошо» здесь было бы неправдой.
           console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${L.doctor.outsideDiff(out.length)}`)}`);
-          results.push({ name, cmd, ok: true, secs, scopedAway: out.length });
+          results.push({ name, cmd, ok: true, secs, scopedAway: out.length, out: outAll });
           continue;
         }
         out = s.kept;
@@ -191,7 +195,7 @@ function runGates(man, opts = {}) {
       if (out.length > 3) console.log(c.dim(`        ${L.doctor.moreLines(out.length - 3)}`));
       // Совет тоже не бесконечен: гейт, зовущий помощник шесть раз, печатает его шесть раз.
       for (const line of alwaysAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
-      results.push({ name, cmd, ok: false, secs, code, advisory: isAdvisory });
+      results.push({ name, cmd, ok: false, secs, code, advisory: isAdvisory, out: outAll });
     }
   }
   // Совещательные, которые покраснели, называются вслух ВСЕГДА. Молчание о них — ровно та
@@ -237,13 +241,10 @@ async function cmdDoctor() {
   // а копия завтра разошлась бы с ними. Без этого различия `doctor` краснел на собственном
   // репозитории и требовал разложить комплект в комплект.
   const inKit = resolve(CWD) === resolve(PKG_ROOT);
-  const checks = [
-    inKit ? ["kit/docs", L.doctor.docsKit] : [".aqk/docs", L.doctor.docs],
-    inKit ? ["kit/rules", L.doctor.rulesKit] : [".aqk/rules", L.doctor.rules],
-    ["AGENTS.md", L.doctor.agents],
-    [".gitignore", L.doctor.gitignore],
-    [".git", L.doctor.git],
-  ];
+  const man = await readManifest();
+  // Что именно проверять — решает манифест: где у ЭТОГО проекта правила, методички и точка
+  // входа. Литеральный список стоял здесь до 2026-09-08 и печатал кресты за сделанное.
+  const checks = layoutChecks(man, inKit);
 
   let missing = 0;
   for (const [path, what] of checks) {
@@ -252,8 +253,10 @@ async function cmdDoctor() {
     console.log(`  ${ok ? c.green("✔") : c.red("✘")}  ${path.padEnd(22)} ${c.dim(what)}`);
   }
 
-  // Команды в AGENTS.md заполнены или остались пустыми заготовками?
-  const agents = join(CWD, "AGENTS.md");
+  // Команды в точке входа заполнены или остались пустыми заготовками? Файл берётся тот же,
+  // что проверен выше, — иначе проект на `CLAUDE.md` этой проверки не получал вовсе.
+  const entryFile = (Array.isArray(man?.entry) ? man.entry : []).find((e) => typeof e === "string" && e.trim())?.trim() || "AGENTS.md";
+  const agents = join(CWD, entryFile);
   if (await exists(agents)) {
     const text = await readFile(agents, "utf8");
     const emptyCommands = (text.match(/^- [^:]+: ``$/gm) || []).length;
@@ -265,8 +268,6 @@ async function cmdDoctor() {
     }
   }
 
-  const man = await readManifest();
-
   // Опечатка в имени поля означала «поля нет»: вердикт выдавался неверный, а причина молчала.
   // Называем поле и говорим, какие бывают — иначе человек ищет ошибку в проекте, а она в файле.
   const unknown = unknownKeys(man);
@@ -316,6 +317,12 @@ async function cmdDoctor() {
 
   const facts = await detectFacts(man);
   if (process.argv.includes("--baseline")) {
+    // `--baseline` — осмотр, а не прогон: он выходит с нулём всегда. Совмещённый с `--run` или
+    // `--min` он давал конвейер, который НЕ МОЖЕТ покраснеть: порог назван, гейты не запущены,
+    // код нулевой. Человек, собравший такую строку, считает, что порог держится. Отказываемся
+    // вслух — молчаливое зелёное здесь дороже сломанной команды. Найдено ревью 2026-09-08.
+    const clash = ["--run", "--min"].filter((f) => process.argv.includes(f));
+    if (clash.length) die(L.doctor.baselineClash(clash.join(", ")));
     await reportBaseline(man, facts);
     process.exit(0);
   }
@@ -359,4 +366,4 @@ async function cmdDoctor() {
 
 // Наружу — только команда. Остальное здесь же и используется: экспорт, который никто не
 // импортирует, читается как «это часть договора» и мешает менять внутренности.
-export { cmdDoctor, runGates, declaredGates };
+export { cmdDoctor, runGates, declaredGates, sinceRef };

package/tool/commands/learn.mjs

@@ -0,0 +1,159 @@
+// tool/commands/learn.mjs — кандидаты в правила из локальных логов сессий.
+//
+// ЗАЧЕМ. Тезис комплекта: обещание обязано стать командой. Но сначала обещание обязано быть
+// ЗАПИСАНО, а половина того, что человек требует от агента, живёт только в переписке. Здесь
+// комплект смотрит туда, где эти требования лежат, и показывает те, которых нет в точке входа.
+//
+// ЧТО ИЗМЕРЕНО ДО КОДА (2026-09-08, 67 сессий на машине владельца):
+//   · 25 353 записи `user` — из них человеком напечатано 1912. Остальное результаты
+//     инструментов. Отличает их поле `promptSource: "typed"`, и оно точнее любой эвристики:
+//     первая версия отбирала по длине и языку и выдавала «agent quality kit» 44 раза — то есть
+//     вставленные пути, а не правила;
+//   · из 1619 уникальных напечатанных реплик маркеры наставления дают 79, это 4%. Среди них
+//     настоящие правила («файл не трогай», «делай прогон с базой обязательно», «никаких
+//     обходных временных путей») и разговорная шелуха примерно поровну.
+//
+// ЧЕГО ЗДЕСЬ НАМЕРЕННО НЕТ. Поиска ПОВТОРОВ — приёма, на котором построен session-analyzer у
+// agent-lint. Замер его не подтвердил: на 67 сессиях владелец не повторяет правило дословно, он
+// говорит его один раз и каждый раз иначе. Те «повторы», что нашлись, оказались задвоением
+// одной реплики в самом логе.
+//
+// ПРИВАТНОСТЬ. Команда читает переписку. Поэтому: только логи ТЕКУЩЕГО проекта (или явно
+// названного), только в терминал, ни строки на диск, код возврата всегда 0. Отчёт, который
+// можно закоммитить, из переписки не собирается — это решение, а не недоделка.
+
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CWD, c, exists } from "../lib/core.mjs";
+import { readManifest } from "../lib/manifest.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Каталог логов зовётся по рабочему пути, где всё, кроме букв и цифр, заменено на дефис.
+// Правило снято с живой машины, а не угадано: /home/ser/projects/audit_project лежит в
+// -home-ser-projects-audit-project, то есть подчёркивание тоже становится дефисом.
+function logSlug(cwd) {
+  return String(cwd).toLowerCase().replace(/[^a-z0-9]+/g, "-");
+}
+
+// Маркеры наставления на двух языках. Список короткий намеренно: каждый лишний маркер добавляет
+// шума больше, чем находок, а разбирать этот список человеку.
+const MARKERS = new RegExp(
+  "(всегда|никогда|не надо|не нужно|обязательно|запомни|больше не|каждый раз|нельзя|" +
+  "только после|перед тем|сначала|не забывай|не трогай|как договорились|" +
+  "always|never|don'?t|do not|make sure|remember to|must not)",
+  "i",
+);
+
+// Признаки вставки, а не реплики: длина, код в тройных кавычках, много переносов, пути, ссылки.
+// Каждый добавлен по итогу прогона, а не на всякий случай.
+function looksLikeRule(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);
+}
+
+// Слова, по которым сверяем сказанное с записанным. Короткие отброшены: на них совпадёт что
+// угодно, и любое правило показалось бы уже записанным — то есть команда молчала бы всегда.
+function keyWords(text) {
+  return [...new Set(String(text).toLowerCase().match(/[а-яёa-z]{4,}/g) || [])];
+}
+
+// Сверяем по ОСНОВЕ, а не по слову целиком. Русский язык склоняет: в реплике «локальный
+// костыль», в своде «до местного костыля» — по целому слову это промах, и правило, записанное
+// час назад, показалось бы незаписанным. Проверено на живом логе: без основы первым же пунктом
+// вышло правило, внесённое в AGENTS.md в тот же день.
+function stem(w) {
+  return w.length > 5 ? w.slice(0, 5) : w;
+}
+
+// Сказано вслух и НЕ записано. Порог половинный: правило, у которого хотя бы половина значимых
+// слов уже стоит в точке входа, считаем записанным — иначе команда повторяла бы владельцу его
+// же свод. Порог назван здесь, а не спрятан: он произвольный, и это видно.
+function saidNotWritten(text, entryText) {
+  const words = keyWords(text);
+  if (!words.length) return false;
+  const hay = String(entryText || "").toLowerCase();
+  const hit = words.filter((w) => hay.includes(stem(w))).length;
+  return hit / words.length < 0.5;
+}
+
+// Напечатанные человеком реплики одной сессии. Всё прочее — результаты инструментов, служебные
+// вставки и подсказки — отбрасывается по полю promptSource.
+function typedFrom(jsonl) {
+  const out = [];
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    let d;
+    try { d = JSON.parse(line); } catch { continue; }
+    if (d?.type !== "user" || d?.promptSource !== "typed") continue;
+    const cont = d?.message?.content;
+    const text = typeof cont === "string"
+      ? cont
+      : Array.isArray(cont)
+        ? cont.filter((b) => b?.type === "text").map((b) => b.text || "").join(" ")
+        : "";
+    const t = String(text).replace(/\s+/g, " ").trim();
+    if (t) out.push({ text: t, when: String(d.timestamp || "").slice(0, 10) });
+  }
+  return out;
+}
+
+async function readEntry(man) {
+  const names = Array.isArray(man?.entry) && man.entry.length ? man.entry : ["AGENTS.md", "CLAUDE.md"];
+  let all = "";
+  for (const n of names) {
+    try { all += `\n${await readFile(join(CWD, String(n)), "utf8")}`; } catch { /* нет файла — не беда */ }
+  }
+  return all;
+}
+
+async function cmdLearn(argv = process.argv) {
+  const limitAt = argv.indexOf("--limit");
+  const limit = limitAt !== -1 && /^\d+$/.test(argv[limitAt + 1] || "") ? Number(argv[limitAt + 1]) : 20;
+  const root = join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects", logSlug(CWD));
+
+  console.log(c.bold(`\n  ${L.learn.title}\n`));
+  if (!(await exists(root))) {
+    console.log(`  ${L.learn.noLogs(root)}\n`);
+    return;
+  }
+
+  let files = [];
+  try { files = (await readdir(root)).filter((f) => f.endsWith(".jsonl")); } catch { files = []; }
+  const seen = new Set();
+  const said = [];
+  let typedTotal = 0;
+  for (const f of files) {
+    let raw = "";
+    try { raw = await readFile(join(root, f), "utf8"); } catch { continue; }
+    for (const m of typedFrom(raw)) {
+      typedTotal++;
+      const key = m.text.toLowerCase().slice(0, 200);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      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)));
+
+  console.log(`  ${c.dim(L.learn.counted(files.length, typedTotal, said.length, fresh.length))}\n`);
+  if (!fresh.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)}`);
+  }
+  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 };

package/tool/commands/project.mjs

@@ -76,6 +76,7 @@ ${c.bold(L.init.nextTitle)}
   4. ${L.init.n4a} ${c.bold(L.init.n4b)}${L.init.n4c}
      ${L.init.n4d}
 
+${c.dim(L.init.hookHint(`${SELF} context --install`))}
 ${c.dim(L.init.burned(`${SELF} note "…"`))}
 `);
   await maybeAskFeedback();

package/tool/commands/report.mjs

@@ -15,11 +15,13 @@
 
 import { mkdir, writeFile, readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
+import { statSync } from "node:fs";
 import { CWD, TARGET_DIR, SELF, c, exists, docPath } from "../lib/core.mjs";
 import { readManifest, assessLevel } from "../lib/manifest.mjs";
 import { proveGates } from "../lib/prove.mjs";
 import { detectFacts, readCatalog, triggerVerdict, whichSync } from "../lib/repo.mjs";
-import { runGates, declaredGates } from "./doctor.mjs";
+import { changedCode, coverage, evidenceHash, readForHash } from "../lib/evidence.mjs";
+import { runGates, declaredGates, sinceRef } from "./doctor.mjs";
 import { L } from "../i18n/index.mjs";
 
 // Каким рецептом стоит гейт: родным инструментом или переносимой проверкой. Именно это
@@ -175,6 +177,36 @@ async function cmdReport() {
     say(`> ${L.report2.ignoreWarn}`);
   }
 
+  // --- чем доказан этот диф -------------------------------------------------
+  // Раздел появляется только с `--since`: без базы сравнения говорить о покрытии нечего, а
+  // молчаливо взять умолчание нельзя — «сравнили не с тем» неотличимо от «всё покрыто».
+  const since = sinceRef();
+  if (since) {
+    const changed = changedCode(since, CWD);
+    say("");
+    say(`## ${L.report2.evidenceTitle}`);
+    say("");
+    if (changed === null) {
+      say(`- ⚠️ ${L.report2.evidenceBadRef(since)}`);
+    } else if (!changed.length) {
+      say(`- ${L.report2.evidenceNoFiles(since)}`);
+    } else {
+      // Каталог ли это — спрашиваем у диска: цель гейта «tool» и файл «tool.js» иначе
+      // неразличимы, и второй попал бы в «просмотрен» ни за что.
+      const isDir = (rel) => { try { return statSync(join(CWD, rel)).isDirectory(); } catch { return false; } };
+      const cov = coverage(changed, run.results, isDir);
+      const hash = evidenceHash(since, run.results, readForHash(changed, CWD));
+      for (const [f, by] of cov.covered) say(`- ✅ ${f} — ${L.report2.evidenceNamed(by.join(", "))}`);
+      for (const [f, by] of cov.silent) say(`- ◻️ ${f} — ${L.report2.evidenceSilent(by.length)}`);
+      for (const f of cov.uncovered) say(`- ❌ ${f} — ${L.report2.evidenceUncovered}`);
+      say("");
+      say(`- ${L.report2.evidenceBase}: \`${since}\``);
+      say(`- ${L.report2.evidenceHash}: \`${hash}\``);
+      say("");
+      say(`> ${L.report2.evidenceWarn}`);
+    }
+  }
+
   say("");
   say(`## ${L.report2.whyTitle}`);
   say("");