agent-quality-kit 0.6.0 → 0.8.0

package/tool/selfcheck/units-context.mjs

@@ -0,0 +1,186 @@
+// 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");
+  const dispatched = [...src.matchAll(/^\s{4}case "([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, "всегда так");
+});

package/tool/selfcheck/units-level.mjs

@@ -0,0 +1,122 @@
+// tool/selfcheck/units-level.mjs — проверки уровня и доказательства гейтов.
+//
+// ОТДЕЛЬНЫМ ФАЙЛОМ, а не в units.mjs: тот перерос собственный предел в 500 строк, и поймал
+// это наш же гейт `file-size-limit` на прогоне. Шов по смыслу: здесь всё, что программа
+// вычитывает ИЗ МАНИФЕСТА и объявляет о проекте, — ступень, доказательство гейтов и раскладка
+// (где правила, методички, точка входа). Общее у них одно и важное: ответ обязан приходить из
+// манифеста, а не из умолчаний, совпадающих с нашими собственными значениями.
+//
+//   node --test tool/selfcheck/units-level.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { commandFor } from "../lib/prove.mjs";
+import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS } from "../lib/manifest.mjs";
+
+// --- доказательство гейтов ------------------------------------------------------------
+// ЗАЧЕМ. Ступень AQK-2 называлась «гейты доказаны» и проверяла существование двух папок.
+// Проект с тремя гейтами `true` проходил порог AQK-3 — проверено прогоном на пустой папке.
+test("обёртка храповика снимается перед подстановкой каталога", () => {
+  // Иначе доказательство гоняет гейт вместе с реестром долга, и реестр перезаписывается
+  // находками из ОБРАЗЦА. На живом проекте это стёрло бы долг целиком.
+  const cmd = "bash ratchets/_ratchet.sh ratchets/x.txt bash gates/x/check.sh .";
+  assert.equal(commandFor(cmd, "gates/x/red"), "bash gates/x/check.sh gates/x/red");
+});
+
+test("каталог подставляется вместо последнего слова команды", () => {
+  assert.equal(commandFor("bash gates/x/check.sh .", "gates/x/green"), "bash gates/x/check.sh gates/x/green");
+  assert.equal(commandFor("ruff check --select T20 .", "gates/x/red"), "ruff check --select T20 gates/x/red");
+});
+
+test("ступень выше первой не берётся без доказательства", async () => {
+  const man = {
+    aqk: "0.6.0", entry: [], rules: ".", samples: ".", ratchets: ".", lessons: ".",
+    gates: { lint: "true" },
+  };
+  const withoutProof = await assessLevel(man, null);
+  const withFailedProof = await assessLevel(man, { ok: false });
+  const withProof = await assessLevel(man, { ok: true });
+  // Без доказательства ступень не выполнена, но помечена «не проверяли» — это разные состояния.
+  assert.equal(withoutProof.steps[2].ok, false);
+  assert.equal(withoutProof.steps[2].needsProof, true);
+  assert.equal(withFailedProof.steps[2].ok, false);
+  assert.equal(withFailedProof.steps[2].needsProof, false);
+  assert.equal(withProof.steps[2].ok, true);
+});
+
+test("обёртка родного инструмента едет вместе с каталогом образца", () => {
+  // `_native.sh <каталог> <команда…>` прячет пути gates/*/red|green. Оставленный «.» спрятал бы
+  // ровно то, что образец обязан показать, — красный прошёл бы зелёным.
+  const cmd = "bash gates/_native.sh . ruff check --select T20 .";
+  assert.equal(
+    commandFor(cmd, "gates/x/red"),
+    "bash gates/_native.sh gates/x/red ruff check --select T20 gates/x/red"
+  );
+});
+
+test("обе обёртки снимаются вместе", () => {
+  const cmd = "bash ratchets/_ratchet.sh ratchets/x.txt bash gates/_native.sh . ruff check .";
+  assert.equal(
+    commandFor(cmd, "gates/x/green"),
+    "bash gates/_native.sh gates/x/green ruff check gates/x/green"
+  );
+});
+
+// Отзыв второго пользователя, 2026-09-08: на Windows `prove` объявил два ИСПРАВНЫХ гейта
+// сломанными. Путь к образцу собирался `path.join`, то есть `gates\x\red`, и уезжал в строку
+// команды — а её исполняет `sh`, который обратный слэш съедает как экранирование: остаётся
+// `gatesxred`. Каталога нет → `find` молчит → код 0 → «промолчал на КРАСНОМ образце».
+// Проверка идёт здесь, а не в самом сборщике пути: `commandFor` — единственная дверь, через
+// которую каталог попадает в оболочку, и закрывать её надо там, кто бы путь ни собрал.
+test("каталог образца уходит в оболочку с прямыми слэшами", () => {
+  assert.equal(
+    commandFor("bash gates/x/check.sh .", "gates\\x\\red"),
+    "bash gates/x/check.sh gates/x/red",
+  );
+});
+
+// Тот же путь едет ВТОРЫМ адресом — первым аргументом фильтра образцов. Пропустить его значит
+// починить половину: фильтр не узнает образец и спрячет ровно то, что образец обязан показать.
+test("обёртка родного инструмента тоже получает прямые слэши", () => {
+  assert.equal(
+    commandFor("bash gates/_native.sh . npx knip --directory .", "gates\\x\\red"),
+    "bash gates/_native.sh gates/x/red npx knip --directory gates/x/red",
+  );
+});
+
+// --- где у проекта лежат правила и методички ----------------------------------
+// Отзыв второго пользователя, 2026-09-08: `doctor` рисовал два красных креста за сделанное.
+// У проекта `rules: .temper/rules`, правила на месте, гейт entry-links-exist их видит, уровень
+// AQK-1 считается ПО МАНИФЕСТУ — а список в шапке проверял литеральные `.aqk/rules` и
+// `.aqk/docs` и советовал сделать сделанное. Уровень и вывод расходились в разные стороны:
+// хуже неверного вывода только вывод, который расходится с собственным вердиктом.
+test("каталог правил берётся из манифеста, а не из умолчания", () => {
+  const paths = layoutChecks({ rules: ".temper/rules" }, false).map(([p]) => p);
+  assert.ok(paths.includes(".temper/rules"), "путь из манифеста обязан попасть в список");
+  assert.ok(!paths.includes(".aqk/rules"), "умолчание обязано уступить манифесту");
+});
+
+// Поля `docs:` не было вовсе: перенести методички было НЕКУДА, и проект, разложивший их иначе,
+// получал крест без единого способа его снять. Умолчание остаётся для тех, кто поля не завёл.
+test("каталог методичек тоже берётся из манифеста", () => {
+  const paths = layoutChecks({ docs: ".temper/docs" }, false).map(([p]) => p);
+  assert.ok(paths.includes(".temper/docs"));
+  assert.ok(!paths.includes(".aqk/docs"));
+});
+
+test("без манифеста остаются умолчания", () => {
+  const paths = layoutChecks(null, false).map(([p]) => p);
+  assert.ok(paths.includes(".aqk/rules") && paths.includes(".aqk/docs"));
+});
+
+// В самом комплекте лежат оригиналы, а не разложенная копия: копия завтра разошлась бы с ними.
+test("внутри комплекта проверяются его собственные каталоги", () => {
+  const paths = layoutChecks({ rules: "kit/rules" }, true).map(([p]) => p);
+  assert.ok(paths.includes("kit/rules") && paths.includes("kit/docs"));
+});
+
+// Поле, которое программа читает, обязано быть в списке известных: иначе манифест с ним
+// получает предупреждение «неизвестное поле» за то, что работает.
+test("docs — известное поле манифеста", () => {
+  assert.ok(KNOWN_KEYS.includes("docs"));
+  assert.deepEqual(unknownKeys({ docs: ".aqk/docs" }), []);
+});

package/tool/selfcheck/units.mjs

@@ -11,9 +11,9 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { parseManifest, manifestWithGate, unknownKeys, entryLifecycle } from "../lib/manifest.mjs";
+import { parseManifest, manifestWithGate, unknownKeys, entryLifecycle, advisorySet, KNOWN_KEYS } from "../lib/manifest.mjs";
 import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG, whichSync } from "../lib/repo.mjs";
-import { scopeOutput } from "../lib/scope.mjs";
+import { scopeOutput, splitAdvice } from "../lib/scope.mjs";
 import { assessBaseline, ITEMS, BASELINE_TOTAL } from "../lib/baseline.mjs";
 import { CATALOGS, pickLang, L } from "../i18n/index.mjs";
 import { badgeMarkdown, BADGE_RE, placesToCheck } from "../commands/badge.mjs";
@@ -358,3 +358,115 @@ test("сужение по дифу: гейт без путей в выводе
   assert.equal(r.scopable, false);
   assert.equal(scopeOutput(["src/old.py:1: печать"], new Set(["src/new.py"])).scopable, true);
 });
+
+
+// --- совет по починке не теряется в обрезке ----------------------------------
+// ЗАЧЕМ. Все девятнадцать записей каталога печатают строку «почини: …» последней. `doctor --run`
+// показывает три первые строки вывода и обрезает остальное — то есть ровно ту строку, ради
+// которой человек и смотрит на красное, он не видит никогда. Находка без действия — это повод
+// закрыть окно, а не починить.
+test("совет по починке отделяется от находок и не обрезается", () => {
+  const out = [
+    "src/a.py:3: печать",
+    "src/b.py:9: печать",
+    "src/c.py:1: печать",
+    "src/d.py:7: печать",
+    "  почини: замени на вызов системы логов",
+    "  тогда запись попадёт в общий журнал",
+  ];
+  const r = splitAdvice(out);
+  assert.equal(r.findings.length, 4);
+  assert.equal(r.advice.length, 2);
+  // Продолжение совета едет вместе с ним: без второй строки первая обрывается на полуслове.
+  assert.equal(r.advice[1].includes("общий журнал"), true);
+});
+
+test("совет по починке опознаётся на обоих языках", () => {
+  assert.equal(splitAdvice(["a.py:1: x", "  fix: replace with a logger call"]).advice.length, 1);
+  assert.equal(splitAdvice(["a.py:1: x", "  почини: замени на логгер"]).advice.length, 1);
+});
+
+// Вывод без совета — это не ошибка разбора, а признак записи, которая не говорит, что делать.
+// Разбор обязан вернуть пустой совет, а не выдумать его из последней строки.
+test("вывод без совета не превращается в совет", () => {
+  const r = splitAdvice(["src/a.py:3: печать", "src/b.py:9: печать"]);
+  assert.equal(r.advice.length, 0);
+  assert.equal(r.findings.length, 2);
+});
+
+
+// Совет бывает не только в конце: `deps-are-pinned` печатает его внутри вспомогательной
+// функции, вызываемой шесть раз, и находки идут ПОСЛЕ. Пока советом считалось «всё от первой
+// метки до конца», сорок находок уезжали в жёлтый список без обрезки — ровно та стена красного,
+// против которой написан этот модуль. Найдено ревью 2026-09-06.
+test("совет, вставленный посреди вывода, не проглатывает находки", () => {
+  const r = splitAdvice([
+    "  почини: закрепи версии",
+    "src/a.py:1: x",
+    "src/b.py:2: x",
+    "src/c.py:3: x",
+    "  почини: и вот это тоже",
+    "    вторая строка совета",
+  ]);
+  assert.equal(r.findings.length, 3);
+  assert.equal(r.advice.length, 3);
+});
+
+// Продолжение совета не должно съедать находку, стоящую сразу за ним.
+test("находка сразу после совета остаётся находкой", () => {
+  const r = splitAdvice(["  почини: сделай так", "    пояснение", "src/z.py:9: x"]);
+  assert.equal(r.findings.length, 1);
+  assert.equal(r.findings[0].includes("src/z.py"), true);
+});
+
+
+// --- правило, введённое совещательным ----------------------------------------
+// ЗАЧЕМ. Правило вводят в проект, где старый код ему не соответствует. Храповик отвечает на
+// это одним способом: старое становится долгом. Второй способ — показывать, не роняя, пока
+// команда договаривается. Сегодня его нет вовсе: находка либо роняет сборку, либо не существует.
+//
+// ПОЧЕМУ ОБЪЯВЛЕНИЕМ, А НЕ ФЛАГОМ ПРОГОНА. Флаг «не роняй ничего» — это `continue-on-error`,
+// против которого написана наша же запись ci-actually-fails: он понижает всё разом, не виден
+// в дифе и не назван в сводке. Список в манифесте виден, именуется и считается всегда.
+test("совещательные гейты читаются из манифеста списком", () => {
+  const man = parseManifest("aqk: 1\nadvisory:\n  - complexity-limit\n  - duplicate-code\n");
+  const a = advisorySet(man);
+  assert.equal(a.has("complexity-limit"), true);
+  assert.equal(a.has("duplicate-code"), true);
+  assert.equal(a.has("secrets-not-in-code"), false);
+});
+
+test("список в одну строку читается так же", () => {
+  const a = advisorySet(parseManifest("advisory: [complexity-limit, duplicate-code]\n"));
+  assert.equal(a.size, 2);
+});
+
+// Отсутствие блока — это ноль совещательных, а не «все совещательные».
+test("без блока advisory совещательных нет", () => {
+  assert.equal(advisorySet(parseManifest("aqk: 1\n")).size, 0);
+  assert.equal(advisorySet(null).size, 0);
+});
+
+// Поле обязано быть известным манифесту: иначе опечатка «advisery:» молча означала бы
+// «совещательных нет», и правило, которое человек считал введённым, роняло бы сборку.
+test("advisory — известное поле манифеста", () => {
+  assert.equal(KNOWN_KEYS.includes("advisory"), true);
+  assert.deepEqual(unknownKeys({ aqk: 1, advisory: [] }), []);
+});
+
+
+// --- правила на языке проекта ------------------------------------------------
+// ЗАЧЕМ. Русский текст правил в англоязычном проекте — это первое, что там откроет человек,
+// и первое, чего он не прочитает. Русская версия остаётся источником истины, английская —
+// переводом. Совпадение содержания машина не сторожит, а вот НАБОР ФАЙЛОВ обязана: добавили
+// правило на одном языке и забыли про другой — половина мира получит комплект без него.
+test("наборы файлов правил совпадают на обоих языках", async () => {
+  const { readdir } = await import("node:fs/promises");
+  const { fileURLToPath } = await import("node:url");
+  const at = (d) => fileURLToPath(new URL(`../../kit/${d}`, import.meta.url));
+  const ru = (await readdir(at("rules"))).filter((f) => f.endsWith(".md")).sort();
+  const en = (await readdir(at("rules-en"))).filter((f) => f.endsWith(".md")).sort();
+  assert.deepEqual(en, ru);
+  assert.equal(ru.length > 0, true);
+});
+