agent-quality-kit 0.7.0 → 0.8.0

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

@@ -1,14 +1,16 @@
 // tool/selfcheck/units-level.mjs — проверки уровня и доказательства гейтов.
 //
 // ОТДЕЛЬНЫМ ФАЙЛОМ, а не в units.mjs: тот перерос собственный предел в 500 строк, и поймал
-// это наш же гейт `file-size-limit` на прогоне. Шов по смыслу: здесь всё про то, чем ступень
-// отличается от заявления, — остальное осталось на месте.
+// это наш же гейт `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 } from "../lib/manifest.mjs";
+import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS } from "../lib/manifest.mjs";
 
 // --- доказательство гейтов ------------------------------------------------------------
 // ЗАЧЕМ. Ступень AQK-2 называлась «гейты доказаны» и проверяла существование двух папок.
@@ -58,3 +60,63 @@ test("обе обёртки снимаются вместе", () => {
     "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

@@ -469,3 +469,4 @@ test("наборы файлов правил совпадают на обоих
   assert.deepEqual(en, ru);
   assert.equal(ru.length > 0, true);
 });
+