agent-quality-kit 0.7.0 → 0.9.0

package/tool/selfcheck/units-banner.mjs

@@ -0,0 +1,65 @@
+// tool/selfcheck/units-banner.mjs — заставка: первая и почти единственная встреча с человеком.
+//
+// ЗАЧЕМ ПРОВЕРЯТЬ КАРТИНКУ. Не ради красоты. Заставка шириной больше окна разъезжается в кашу
+// и портит именно то впечатление, ради которого её и добавили. А в терминале без UTF-8 графика
+// Брайлем превращается в вопросительные знаки — и человек решает, что инструмент сломан.
+//
+//   node --test tool/selfcheck/units-banner.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { banner, BANNER_WIDTH } from "../lib/banner.mjs";
+
+test("заставка влезает в узкое окно", () => {
+  const w = Math.max(...banner().split("\n").map((l) => [...l].length));
+  assert.ok(w <= 40, `ширина ${w}, а бывают окна и в 40 колонок`);
+  assert.equal(w, BANNER_WIDTH, "объявленная ширина обязана совпадать с настоящей");
+});
+
+// Версии в заставке НЕТ намеренно — решение владельца: выпуски частые, и номер в картинке
+// устаревает быстрее всего остального. За версией есть `--version`, она печатается отдельно.
+test("версии в заставке нет", () => {
+  assert.doesNotMatch(banner(), /\d+\.\d+\.\d+/);
+});
+
+// Терминал без UTF-8 превратит Брайль в мусор. Тогда честнее короткая строка, чем каша,
+// по которой человек решит, что инструмент сломан.
+test("без UTF-8 вместо графики короткая строка", () => {
+  const plain = banner({ LANG: "C" });
+  assert.doesNotMatch(plain, /[⣿█]/);
+  assert.match(plain, /aqk/i);
+});
+
+test("отказ от графики уважается переменной", () => {
+  assert.doesNotMatch(banner({ LANG: "ru_RU.UTF-8", AQK_NO_ART: "1" }), /[⣿█]/);
+});
+
+// Кошка центрируется по ВИДИМОЙ части, а не по началу строки: пустой Брайль `⠀` занимает место
+// и ничего не рисует. При равных отступах рисунок выглядел сдвинутым вправо на целый знак —
+// поймано глазом владельца, а не прогоном, и потому закреплено здесь.
+test("кошка стоит по центру надписи", () => {
+  const lines = banner().split("\n");
+  const visible = (l, blanks) => {
+    const a = [...l];
+    let lo = -1, hi = -1;
+    a.forEach((ch, i) => { if (!blanks.has(ch)) { if (lo < 0) lo = i; hi = i; } });
+    return lo < 0 ? null : (lo + hi) / 2;
+  };
+  const catMid = Math.max(...lines.slice(0, 6).map((l) => visible(l, new Set([" ", "⠀"]))));
+  const artMid = Math.max(...lines.slice(7, 13).map((l) => visible(l, new Set([" "]))));
+  assert.ok(Math.abs(catMid - artMid) <= 1, `центры разошлись: кошка ${catMid}, буквы ${artMid}`);
+});
+
+// Подпись центрируется по видимому центру букв, а не по краю строки. Отступ, подобранный на
+// глаз, держится до первой правки рисунка — посчитанный переживёт её.
+test("подпись стоит по центру надписи", () => {
+  const lines = banner().split("\n");
+  const mid = (l, blanks) => {
+    const a = [...l];
+    let lo = -1, hi = -1;
+    a.forEach((ch, i) => { if (!blanks.has(ch)) { if (lo < 0) lo = i; hi = i; } });
+    return lo < 0 ? null : (lo + hi) / 2;
+  };
+  const letters = Math.max(...lines.slice(7, 13).map((l) => mid(l, new Set([" "]))));
+  const tag = mid(lines[lines.length - 1], new Set([" "]));
+  assert.ok(Math.abs(letters - tag) <= 1, `подпись не по центру: буквы ${letters}, подпись ${tag}`);
+});

package/tool/selfcheck/units-brief.mjs

@@ -0,0 +1,97 @@
+// tool/selfcheck/units-brief.mjs — короткая строка присутствия и её ограничитель.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ. Владелец: «скачал и че дальше, не понятно, работает он вообще или нет».
+// Хук pre-commit молчит на успехе — это его умолчание, проверено по документации: вывод
+// показывается только при провале. То есть комплект, который всё держит, для человека
+// неотличим от невставленного. Это ровно наш собственный порок: тишина неотличима от успеха.
+//
+//   node --test tool/selfcheck/units-brief.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { briefLine, adviceDue, pickAdvice, updateNotice, updateWanted } from "../lib/brief.mjs";
+import { CATALOGS } from "../i18n/index.mjs";
+
+const T = CATALOGS.ru;
+
+// Строка присутствия печатается ВСЕГДА, в том числе когда всё хорошо: именно тогда она и нужна.
+test("строка присутствия несёт числа и уровень", () => {
+  const s = briefLine({ held: 12, todo: 3, level: 2, red: [] }, T);
+  assert.match(s, /12/);
+  assert.match(s, /3/);
+  assert.match(s, /AQK-2/);
+});
+
+// Красное называется первым и поимённо: человек должен видеть, что чинить, не листая вывод.
+test("упавшие гейты названы в самой строке", () => {
+  const s = briefLine({ held: 12, todo: 0, level: 1, red: ["file-size-limit", "duplicate-code"] }, T);
+  assert.match(s, /file-size-limit/);
+  assert.match(s, /duplicate-code/);
+});
+
+// Уровень может быть не вычислен — и тогда так и говорим, а не подставляем ноль.
+test("невычисленный уровень не выдумывается", () => {
+  const s = briefLine({ held: 0, todo: 5, level: -1, red: [] }, T);
+  assert.doesNotMatch(s, /AQK--1|AQK-0/);
+});
+
+// --- ограничитель совета -----------------------------------------------------
+// Совет на КАЖДОМ коммите превращается в шум, а шум пролистывают вместе с настоящими
+// находками. Раз в сутки — это заметно и не мешает.
+test("совет не повторяется чаще раза в сутки", () => {
+  const now = Date.parse("2026-09-08T20:00:00Z");
+  assert.equal(adviceDue(null, now), true, "первый раз показывается");
+  assert.equal(adviceDue("2026-09-08T19:00:00Z", now), false, "час назад — рано");
+  assert.equal(adviceDue("2026-09-07T19:00:00Z", now), true, "сутки прошли");
+});
+
+test("испорченная отметка времени не мешает показать совет", () => {
+  assert.equal(adviceDue("не дата", Date.parse("2026-09-08T20:00:00Z")), true);
+});
+
+// --- выбор совета ------------------------------------------------------------
+// Один совет за раз, а не список: список читается как «у вас всё плохо» и не помогает выбрать.
+test("советуется одна запись, самая первая из непоставленных", () => {
+  const a = pickAdvice([{ slug: "secrets-not-in-code" }, { slug: "file-size-limit" }]);
+  assert.equal(a.slug, "secrets-not-in-code");
+});
+
+test("советовать нечего — совета нет, а не пустая строка", () => {
+  assert.equal(pickAdvice([]), null);
+});
+
+// --- уведомление об обновлении -----------------------------------------------
+// Владелец: «выпускаем часто, никто не будет обновлять — скачают старую версию, а мы там уже
+// ошибки исправили». Верно: у pre-commit версия закреплена в rev:, у GitHub Action в теге,
+// и сами они не двигаются. У `npx` без версии проблемы нет — он всегда берёт свежее.
+//
+// АВТООБНОВЛЕНИЯ НЕТ НАМЕРЕННО. В этот же день выпущена запись, краснеющая на `@latest`:
+// «версия не закреплена, завтра приедет другая». Инструмент, который сам себя подменяет, стоя
+// на воротах коммита, делал бы ровно то, что мы запрещаем другим.
+test("новая версия называется, старая не тревожит", () => {
+  assert.ok(updateNotice("0.8.0", "0.9.0", {}, T));
+  assert.equal(updateNotice("0.9.0", "0.9.0", {}, T), null);
+  assert.equal(updateNotice("0.9.0", "0.8.0", {}, T), null, "откат назад — не обновление");
+});
+
+// Сравнение по числам, а не по строкам: «0.10.0» строкой меньше «0.9.0», и уведомление
+// пропало бы ровно на десятом выпуске — тихо и надолго.
+test("версии сравниваются числами, а не как текст", () => {
+  assert.ok(updateNotice("0.9.0", "0.10.0", {}, T));
+  assert.equal(updateNotice("0.10.0", "0.9.0", {}, T), null);
+  assert.ok(updateNotice("1.2.9", "1.10.0", {}, T));
+});
+
+// Способ обновления зависит от того, как поставлено: у pre-commit это autoupdate, а не npm.
+// Совет «сделай npm i -g» человеку, у которого хук, — это совет мимо, и он его не выполнит.
+test("совет об обновлении соответствует способу установки", () => {
+  assert.match(updateNotice("0.8.0", "0.9.0", { PRE_COMMIT: "1" }, T), /autoupdate/);
+  assert.doesNotMatch(updateNotice("0.8.0", "0.9.0", {}, T), /autoupdate/);
+});
+
+// В конвейере уведомление — шум и лишний запрос: там версия закреплена сознательно, и человека,
+// который бы его прочитал, у экрана нет.
+test("в конвейере и при отказе проверять не спрашиваем вовсе", () => {
+  assert.equal(updateWanted({ CI: "true" }), false);
+  assert.equal(updateWanted({ AQK_UPDATE: "0" }), false);
+  assert.equal(updateWanted({}), true);
+});

package/tool/selfcheck/units-context.mjs

@@ -0,0 +1,188 @@
+// tool/selfcheck/units-context.mjs — блок состояния, который уходит В КОНТЕКСТ агента.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫМ ФАЙЛОМ. У этого текста единственный читатель — машина, и цена ошибки другая,
+// чем у терминального вывода: человек, увидев пустую строку, переспросит, а агент примет её за
+// утверждение. Поэтому главная проверка здесь одна и та же во всех видах: **тишина не означает
+// «чисто»**. Блок обязан говорить «неизвестно» там, где не знает, — иначе он врёт ровно тем
+// способом, против которого написан весь комплект.
+//
+//   node --test tool/selfcheck/units-context.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { contextBlock, countArbiters, parseLastRun, withHook, hasOurHook, portableSelf } from "../commands/context.mjs";
+import { CATALOGS } from "../i18n/index.mjs";
+import { commandRows } from "../lib/core.mjs";
+import { readFile } from "node:fs/promises";
+
+const T = CATALOGS.ru.context;
+const base = {
+  entry: "AGENTS.md",
+  level: { reached: 1, top: 3, missing: "гейты не доказаны" },
+  rules: { total: 14, machine: 2, human: 12 },
+  run: { when: "2026-09-08 11:00", red: [], skipped: 0, stale: false },
+  ratchets: [],
+};
+const text = (over = {}) => contextBlock({ ...base, ...over }, T).join("\n");
+
+// ГЛАВНАЯ. Прогона не было — сказать «неизвестно» словом. Пустая строка на этом месте
+// прочитается агентом как «красных нет», и он пойдёт писать код по несуществующему разрешению.
+test("без прогона блок говорит «неизвестно», а не молчит", () => {
+  const t = text({ run: null });
+  assert.match(t, /НЕИЗВЕСТНО/);
+  assert.doesNotMatch(t, /красных нет/);
+});
+
+test("красные гейты названы поимённо", () => {
+  const t = text({ run: { ...base.run, red: ["file-size-limit", "duplicate-code"] } });
+  assert.match(t, /file-size-limit/);
+  assert.match(t, /duplicate-code/);
+});
+
+// Проект с двадцатью красными не должен вытеснять собой весь контекст: ровно та деградация,
+// ради избежания которой блок и делается коротким.
+test("длинный список красных обрезается и называет остаток числом", () => {
+  const red = Array.from({ length: 20 }, (_, i) => `гейт-${i}`);
+  const t = text({ run: { ...base.run, red } });
+  assert.match(t, /ещё 15/);
+  assert.ok(!t.includes("гейт-9"), "шестой и дальше в список не попадают");
+});
+
+// Прогон, сделанный до последнего коммита, описывает не тот код, что лежит перед агентом.
+test("устаревший прогон помечен, а не выдан за свежий", () => {
+  const t = text({ run: { ...base.run, stale: true } });
+  assert.match(t, /СТАРЕЕ/);
+});
+
+// То, ради чего второй пользователь и оценил promise-has-gate: «держит человек» значит
+// «не держит никто», и это обязано быть сказано словами, а не выведено читателем из цифр.
+test("правила без машинного арбитра названы прямо", () => {
+  const t = text({ rules: { total: 12, machine: 0, human: 12 } });
+  assert.match(t, /не держит никто/);
+});
+
+test("нет манифеста — уровень не выдумывается", () => {
+  const t = text({ level: null });
+  assert.match(t, /не вычислен/);
+  assert.doesNotMatch(t, /AQK-0 из/);
+});
+
+// Потолок: блок влезает в глаза целиком. Замер 2026-09-08 — вход целиком в контекст роняет
+// точность у всех проверенных моделей по мере роста, поэтому предел здесь предмет проверки,
+// а не пожелание.
+test("блок не разрастается даже на худшем входе", () => {
+  const lines = contextBlock({
+    ...base,
+    run: { when: "…", red: Array.from({ length: 40 }, (_, i) => `г-${i}`), skipped: 9, stale: true },
+    ratchets: Array.from({ length: 12 }, (_, i) => ({ name: `р-${i}`, count: i })),
+  }, T);
+  assert.ok(lines.length <= 16, `строк ${lines.length}, предел 16`);
+});
+
+// --- разбор источников -------------------------------------------------------
+// Имя арбитра — это имя гейта, а в именах гейтов есть дефисы. Класс `[^\s>-]` обрывал их
+// молча: первый же живой запуск показал 13 правил вместо 14 и одного машинного вместо двух.
+// Молча — потому что число выглядит правдоподобным, пока его не с чем сверить.
+test("имя арбитра с дефисом считается машинным, а не теряется", () => {
+  const md = [
+    "- Правило один. <!-- aqk: deps-are-pinned -->",
+    "- Правило два. <!-- aqk: человек -->",
+    "- Правило три. <!-- aqk: gates -->",
+  ].join("\n");
+  assert.deepEqual(countArbiters(md, ["человек"]), { total: 3, machine: 2, human: 1 });
+});
+
+test("отчёт прошлого прогона отдаёт красные и число непроверенных", () => {
+  const r = parseLastRun([
+    "# aqk doctor --run — 2026-09-08 11:00",
+    "level: AQK-1",
+    "✔ smoke — 1.0s",
+    "✘ file-size-limit — 0.1s",
+    "~ dead-code — нет инструмента",
+  ].join("\n"));
+  assert.equal(r.when, "2026-09-08 11:00");
+  assert.deepEqual(r.red, ["file-size-limit"]);
+  assert.equal(r.skipped, 1);
+});
+
+test("пустой отчёт — это не «чисто», а отсутствие данных", () => {
+  assert.equal(parseLastRun(""), null);
+});
+
+// Найдено ЗАМЕРОМ на шести чужих проектах, до того как хук попал в init: на `flask`, где нет
+// ни .aqk.yml, ни AGENTS.md, блок всё равно писал «Свод правил: AGENTS.md». Тот же класс, что
+// у doctor неделей раньше: умолчание выдаётся за факт, потому что на нашем репозитории
+// умолчание и факт совпадают. Назвать агенту несуществующий файл хуже, чем промолчать: он
+// пойдёт его читать и получит пустоту вместо правил.
+test("несуществующая точка входа не называется как свод правил", () => {
+  const t = text({ level: null, run: null, rules: null, entryExists: false });
+  assert.doesNotMatch(t, /AGENTS\.md/);
+});
+
+test("существующая точка входа называется", () => {
+  const t = text({ entryExists: true });
+  assert.match(t, /AGENTS\.md/);
+});
+
+// --- хук уходит в ОБЩИЙ файл настроек ----------------------------------------
+// `.claude/settings.json` кладут в git: он общий на команду, в отличие от settings.local.json.
+// Значит команда внутри него обязана работать не только на той машине, где её записали.
+// На машине разработчика SELF — абсолютный путь; у соседа такого пути нет, и хук молча
+// не сработает. Молча — то есть блок состояния просто не появится, и никто не узнает.
+test("абсолютный путь заменяется переносимым вызовом", () => {
+  assert.equal(portableSelf("node /home/x/aqk/tool/program.mjs"), "npx agent-quality-kit");
+  assert.equal(portableSelf("node C:\\x\\aqk\\tool\\program.mjs"), "npx agent-quality-kit");
+});
+
+test("переносимые вызовы остаются как есть", () => {
+  assert.equal(portableSelf("aqk"), "aqk");
+  assert.equal(portableSelf("npx agent-quality-kit"), "npx agent-quality-kit");
+  assert.equal(portableSelf("node tool/program.mjs"), "node tool/program.mjs");
+});
+
+// Второй такой же хук — блок в контексте дважды: вдвое больше токенов и ровно ноль пользы.
+test("хук не задваивается", () => {
+  const once = withHook({}, "aqk context");
+  assert.ok(hasOurHook(once, "aqk context"));
+  assert.equal(once.hooks.SessionStart.length, 1);
+});
+
+// Чужие настройки в том же файле — права доступа, другие хуки — обязаны пережить установку.
+test("чужие настройки переживают установку хука", () => {
+  const before = { permissions: { deny: ["Read(./.env)"] }, hooks: { Stop: [{ hooks: [] }] } };
+  const after = withHook(before, "aqk context");
+  assert.deepEqual(after.permissions, before.permissions);
+  assert.equal(after.hooks.Stop.length, 1);
+  assert.equal(after.hooks.SessionStart.length, 1);
+});
+
+// --- карта команд ------------------------------------------------------------
+// Владелец: «агент плохо читает инструкцию — нужно влить карту и сам свод». Карта имеет смысл
+// ровно до тех пор, пока она не отстала от программы. Второй список, живущий рядом с первым,
+// через месяц врёт — это записано у нас в README про храповики и верно здесь буквально так же.
+// Поэтому карта и справка собираются ИЗ ОДНОГО списка, а эта проверка сторожит, что список
+// не отстал от диспетчера: команда, добавленная в switch и забытая в списке, роняет её.
+test("карта команд не отстаёт от диспетчера", async () => {
+  const src = await readFile(new URL("../program.mjs", import.meta.url), "utf8");
+  // Флаговые формы (`--version`, `-v`) в карту не входят: карта перечисляет КОМАНДЫ, а флаг —
+  // второе имя той же команды. Требовать их здесь значило бы дублировать строку справки.
+  const dispatched = [...src.matchAll(/^\s{4}case "([a-z][a-z-]*)":/gm)].map((m) => m[1]);
+  assert.ok(dispatched.length >= 10, `в диспетчере найдено ${dispatched.length} команд — разбор сломался`);
+  const listed = new Set(commandRows(CATALOGS.ru).map((r) => r.name));
+  const missing = dispatched.filter((n) => !listed.has(n));
+  assert.deepEqual(missing, [], `в карте нет: ${missing.join(", ")}`);
+});
+
+// Полный блок — то, за что владелец согласился платить токенами: свод правил дословно, а не
+// ссылка на него. Если он не дословный, плата внесена, а товар не получен.
+test("полный блок несёт свод правил дословно", () => {
+  const rules = "- Правило одно. <!-- aqk: человек -->\n- Правило два.";
+  const t = contextBlock({ ...base, entryExists: true, full: { entry: "AGENTS.md", rows: [{ cmd: "aqk context", text: "состояние" }], text: rules } }, T).join("\n");
+  assert.ok(t.includes(rules), "текст свода обязан войти целиком");
+  assert.match(t, /aqk context/);
+});
+
+test("без --full свод не вливается — только ссылка на него", () => {
+  const t = text({ entryExists: true });
+  assert.doesNotMatch(t, /Правило одно/);
+  assert.match(t, /AGENTS\.md/);
+});

package/tool/selfcheck/units-evidence.mjs

@@ -0,0 +1,83 @@
+// tool/selfcheck/units-evidence.mjs — проверки привязки доказательства к дифу.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫМ ФАЙЛОМ. `units.mjs` во второй раз перерос собственный предел в 500 строк —
+// его поймал наш же гейт file-size-limit, и это уже второй такой развод (первым был
+// `units-level.mjs`). Шов по смыслу: здесь всё про то, чем доказан диф, и ничего больше.
+//
+//   node --test tool/selfcheck/units-evidence.mjs
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+// --- покрытие дифа доказательством ------------------------------------------
+//
+// ЗАЧЕМ. Правило «готово = доказано» было единственным центральным правилом свода, за которым
+// не следила машина: сторожем стоял человек. Прогон donecheck по восьми нашим коммитам показал,
+// чего это стоило: `.github/workflows/publish.yml` менялся и не был назван ни одной командой
+// проверки — и именно он оказался сломан. Механизм взят оттуда (AtharvaMaik/donecheck, MIT),
+// сопоставление сделано СТРОГИМ, в отличие от него: он считает файл покрытым и по голому имени,
+// а имя `check.sh` в нашем каталоге носят двадцать разных файлов.
+test("покрытие: файл считается доказанным, только если гейт назвал ЕГО путь", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  const res = [
+    { name: "tests", cmd: "node --test", out: "ok 1 - src/pay.js:12 покрыт" },
+    { name: "lint", cmd: "bash kit/gates/x/check.sh .", out: "" },
+  ];
+  const cov = coverage(["src/pay.js", "src/refund.js"], res);
+  assert.deepEqual(cov.covered.get("src/pay.js"), ["tests"]);
+  // refund.js не назван никем, но `lint` был направлен в корень — значит он в «молчании»,
+  // а не в «никто не смотрел». Разница между этими двумя и есть смысл третьего состояния.
+  assert.deepEqual(cov.silent.get("src/refund.js"), ["lint"]);
+  assert.deepEqual(cov.uncovered, []);
+});
+
+test("покрытие: голое имя файла не считается доказательством", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  // «check.sh» в выводе не означает, что проверен ИМЕННО kit/gates/todo/check.sh: этим именем
+  // в каталоге зовутся два десятка разных файлов. Мягкое сравнение дало бы тишину — то есть
+  // ровно тот отказ, против которого написана вся эта проверка.
+  const res = [{ name: "g", cmd: "bash run.sh", out: "проверено check.sh" }];
+  const cov = coverage(["kit/gates/todo/check.sh"], res);
+  assert.deepEqual(cov.uncovered, ["kit/gates/todo/check.sh"]);
+});
+
+test("покрытие: путь с ./ и цветом в выводе всё равно засчитывается", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  const esc = String.fromCharCode(27);
+  const res = [{ name: "g", cmd: "x", out: `${esc}[31m./src/pay.js:9${esc}[0m нашлось` }];
+  const cov = coverage(["src/pay.js"], res);
+  assert.deepEqual(cov.uncovered, []);
+});
+
+// Расписка обязана меняться, когда меняется хоть что-то из того, о чём она отчитывается:
+// базовый коммит, набор команд, содержимое файлов. Иначе «прогнал, потом поправил ещё три
+// файла» неотличимо от «прогнал».
+test("расписка: хеш доказательства меняется от правки файла и от смены команды", async () => {
+  const { evidenceHash } = await import("../lib/evidence.mjs");
+  const a = evidenceHash("base1", [{ cmd: "t" }], [["f.js", "one"]]);
+  assert.equal(evidenceHash("base1", [{ cmd: "t" }], [["f.js", "one"]]), a);
+  assert.notEqual(evidenceHash("base1", [{ cmd: "t" }], [["f.js", "two"]]), a);
+  assert.notEqual(evidenceHash("base1", [{ cmd: "u" }], [["f.js", "one"]]), a);
+  assert.notEqual(evidenceHash("base2", [{ cmd: "t" }], [["f.js", "one"]]), a);
+});
+
+test("покрытие: молчащая проверка отличается и от назвавшей, и от не смотревшей", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  const res = [
+    { name: "size", cmd: "bash check.sh .", out: "" },              // направлен в корень, промолчал
+    { name: "tests", cmd: "node --test", out: "src/pay.js:1 ок" },  // назвал файл
+  ];
+  const dirs = new Set(["."]);
+  const cov = coverage(["src/pay.js", "src/quiet.js"], res, (p) => dirs.has(p));
+  assert.deepEqual(cov.covered.get("src/pay.js"), ["tests"]);
+  assert.deepEqual(cov.silent.get("src/quiet.js"), ["size"]);
+  assert.deepEqual(cov.uncovered, []);
+});
+
+test("покрытие: файл вне всех целей остаётся не тронутым никем", async () => {
+  const { coverage } = await import("../lib/evidence.mjs");
+  const res = [{ name: "size", cmd: "bash check.sh tool", out: "" }];
+  const cov = coverage(["tool/a.js", ".github/workflows/ci.yml"], res, (p) => p === "tool");
+  assert.deepEqual(cov.silent.get("tool/a.js"), ["size"]);
+  assert.deepEqual(cov.uncovered, [".github/workflows/ci.yml"]);
+});

package/tool/selfcheck/units-learn.mjs

@@ -0,0 +1,88 @@
+// tool/selfcheck/units-learn.mjs — проверки разбора локальных логов сессий.
+//
+// ЗАЧЕМ ОТДЕЛЬНО. Файл модульных проверок разводится по смыслу третий раз (после units-level и
+// units-evidence) — предел в 500 строк держит наш же гейт file-size-limit. Здесь всё про то,
+// как из переписки достаются кандидаты в правила, и ничего больше.
+//
+//   node --test tool/selfcheck/units-learn.mjs
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+// Каталог логов зовётся по рабочему пути, где всё, кроме букв и цифр, заменено на дефис.
+// Проверено на живой машине: /home/ser/projects/aqk → -home-ser-projects-aqk,
+// /home/ser/projects/audit_project → -home-ser-projects-audit-project.
+test("logSlug: путь проекта превращается в имя каталога логов", async () => {
+  const { logSlug } = await import("../commands/learn.mjs");
+  assert.equal(logSlug("/home/ser/projects/aqk"), "-home-ser-projects-aqk");
+  assert.equal(logSlug("/home/ser/projects/audit_project"), "-home-ser-projects-audit-project");
+  assert.equal(logSlug("C:\\work\\my.app"), "c-work-my-app");
+});
+
+// Отбор наставлений. Меряно на 1619 уникальных напечатанных репликах: маркеры дают 79 штук,
+// то есть 4%. Точность неполная и названа вслух — это список кандидатов, а не находок.
+test("looksLikeRule: наставление отличается от обычной реплики", async () => {
+  const { looksLikeRule } = await import("../commands/learn.mjs");
+  assert.equal(looksLikeRule("файл не трогай AI_main_inst.md"), true);
+  assert.equal(looksLikeRule("делай прогон с базой обязательно"), true);
+  assert.equal(looksLikeRule("never commit secrets"), true);
+  assert.equal(looksLikeRule("ок го дальше"), false);
+  assert.equal(looksLikeRule("а что там по отчёту"), false);
+});
+
+// Длинная вставка наставлением не считается: в логе лежат и вставленный вывод команд, и куски
+// файлов. Первый прогон без этого отсева выдал «agent quality kit» 44 раза — то есть пути и
+// ссылки, а не правила.
+test("looksLikeRule: длинная вставка и код не считаются правилом", async () => {
+  const { looksLikeRule } = await import("../commands/learn.mjs");
+  assert.equal(looksLikeRule("никогда " + "x".repeat(500)), false);
+  assert.equal(looksLikeRule("нельзя\n```\ncode\n```"), false);
+});
+
+// Главное утверждение команды: сказано вслух и НЕ записано. Слово из наставления, которого нет
+// в точке входа, — повод завести правило; совпавшее — повод не шуметь.
+test("saidNotWritten: правило, уже стоящее в точке входа, не показывается", async () => {
+  const { saidNotWritten } = await import("../commands/learn.mjs");
+  const entry = "# правила\n- Секреты никогда не попадают в код.\n";
+  assert.equal(saidNotWritten("никогда не коммить секреты в код", entry), false);
+  assert.equal(saidNotWritten("делай прогон с базой обязательно", entry), true);
+});
+
+// Русский язык склоняет. «локальный костыль» в реплике и «до местного костыля» в своде — одно и
+// то же правило, и по целому слову они не совпадают. Найдено живым прогоном: без сверки по
+// основе первым же кандидатом вышло правило, внесённое в точку входа в тот же день.
+test("saidNotWritten: склонение не делает записанное правило незаписанным", async () => {
+  const { saidNotWritten } = await import("../commands/learn.mjs");
+  const entry = "- Любое сомнение проверяется снаружи, чтобы не выдумать местного костыля.";
+  assert.equal(saidNotWritten("любое сомнение проверяем всегда чтобы не сделать костыль", entry), false);
+});
+
+// Отбор по promptSource — то, ради чего команда вообще работает. В логе 25 353 записи `user`,
+// из них человеком напечатано 1912; остальное результаты инструментов, служебные вставки и
+// принятые подсказки. Первая версия отбирала по длине и языку и выдавала вставленные пути.
+test("typedFrom: берётся только напечатанное человеком", async () => {
+  const { typedFrom } = await import("../commands/learn.mjs");
+  const lines = [
+    JSON.stringify({ type: "user", promptSource: "typed", timestamp: "2026-09-08T10:00:00Z", message: { role: "user", content: "никогда так не делай" } }),
+    JSON.stringify({ type: "user", promptSource: "system", message: { role: "user", content: "служебное" } }),
+    JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "tool_result", content: "вывод" }] } }),
+    JSON.stringify({ type: "assistant", message: { role: "assistant", content: "ответ" } }),
+    "не json вовсе",
+    "",
+  ].join("\n");
+  const got = typedFrom(lines);
+  assert.equal(got.length, 1);
+  assert.equal(got[0].text, "никогда так не делай");
+  assert.equal(got[0].when, "2026-09-08");
+});
+
+// Текст блоками, а не строкой: так приходит реплика с приложенным файлом. Берём текстовые
+// блоки и только их — картинка и результат инструмента правилом быть не могут.
+test("typedFrom: реплика блоками собирается из текстовых блоков", async () => {
+  const { typedFrom } = await import("../commands/learn.mjs");
+  const line = JSON.stringify({
+    type: "user", promptSource: "typed", timestamp: "2026-09-08T11:00:00Z",
+    message: { role: "user", content: [{ type: "image" }, { type: "text", text: "всегда так" }] },
+  });
+  assert.equal(typedFrom(line)[0].text, "всегда так");
+});