agent-quality-kit 0.13.0 → 0.14.0

package/tool/selfcheck/smoke.sh

@@ -16,6 +16,10 @@ set -uo pipefail
 # Язык вывода закреплён: проверки ниже сверяют русский текст, а без этой строки они зависели бы
 # от локали машины — на англоязычном раннере зелёное стало бы красным без единой правки в коде.
 export AQK_LANG=ru
+# Полный вывод: проверки этого файла написаны до того, как doctor стал сворачивать пройденное и
+# неприменимое, и ищут строки из этих списков — в том числе ОТСУТСТВИЕ строки, которое на
+# свёрнутом выводе прошло бы вхолостую. Свёртку проверяют файлы smoke/*.mjs, они флаг сбрасывают.
+export AQK_VERBOSE=1
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 CLI="$ROOT/tool/program.mjs"

package/tool/selfcheck/units-annotate.mjs

@@ -0,0 +1,67 @@
+// tool/selfcheck/units-annotate.mjs — находки гейтов пометками GitHub Actions.
+//
+// ЗАЧЕМ. Находка гейта видна только в логе конвейера, куда почти никто не заглядывает. Строка
+// `::error file=…,line=…,title=…::…` в выводе шага становится красной пометкой у строки файла в
+// pull request. Идея — из разбора AgentLint (research/competitors/agentlint-0xmariowu.md).
+// Формат — документация GitHub (workflow-commands); экранирование — официальный
+// @actions/core (packages/core/src/command.ts: escapeData, escapeProperty), а не чужой код.
+//
+//   node --test tool/selfcheck/units-annotate.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { locate, annotations } from "../lib/annotate.mjs";
+
+const exists = (f) => ["src/a.py", "AGENTS.md", "kit/x.sh"].includes(f);
+
+test("locate: «файл:строка: находка» и «файл: находка»; без пути — ничего", () => {
+  assert.deepEqual(locate("src/a.py:12: print(x) в прод-коде"), { file: "src/a.py", line: 12, message: "print(x) в прод-коде" });
+  assert.deepEqual(locate("./AGENTS.md: «npm run debug» — такого скрипта нет"), { file: "AGENTS.md", line: null, message: "«npm run debug» — такого скрипта нет" });
+  assert.deepEqual(locate("src/a.py:3:7: E501 line too long"), { file: "src/a.py", line: 3, message: "E501 line too long" });
+  assert.equal(locate("прогон красный: 2 находки"), null);
+  assert.equal(locate("  почини: убери print"), null, "совет — не находка");
+});
+
+test("упавший гейт — пометка у строки с советом; совещательный — предупреждение", () => {
+  const r = annotations([
+    { name: "no-print", ok: false, out: "src/a.py:12: print(x)\n  почини: замени на logger\n" },
+    { name: "todo", ok: false, advisory: true, out: "src/a.py:3: TODO без задачи\n" },
+    { name: "lint", ok: true, out: "src/a.py:1: не важно\n" },
+  ], { exists });
+  assert.equal(r.lines.length, 2, "зелёный гейт пометок не даёт");
+  assert.equal(r.lines[0], "::error file=src/a.py,line=12,title=aqk%3A no-print::print(x) — почини: замени на logger");
+  assert.match(r.lines[1], /^::warning file=src\/a\.py,line=3,/);
+});
+
+// Пометка на файл, которого нет, — пометка в никуда: GitHub повесит её на `.github`, и человек
+// будет искать то, чего не существует. Такая находка идёт общей пометкой гейта без файла.
+test("путь, которого нет в репозитории, и находка без пути — одна общая пометка гейта", () => {
+  const r = annotations([
+    { name: "gates-run-in-ci", ok: false, out: "гейт smoke не запускается конвейером\n" },
+    { name: "ghost", ok: false, out: "vendor/lib.js:4: чужой файл\n" },
+  ], { exists });
+  assert.deepEqual(r.lines, [
+    "::error title=aqk%3A gates-run-in-ci::гейт smoke не запускается конвейером",
+    "::error title=aqk%3A ghost::vendor/lib.js:4: чужой файл",
+  ]);
+});
+
+test("экранирование по @actions/core: % \\r \\n в тексте, ещё : и , в свойствах", () => {
+  const r = annotations([{ name: "a,b", ok: false, out: "src/a.py:1: 100% готово, но\r нет\n" }], { exists });
+  assert.equal(r.lines[0], "::error file=src/a.py,line=1,title=aqk%3A a%2Cb::100%25 готово, но%0D нет");
+});
+
+// Потолок. В документации GitHub лимита не нашли; в обсуждении сообщества 2020 года (#26680):
+// «10 warning annotations and 10 error annotations per step». Держимся его, остаток — числом.
+test("не больше 10 ошибок и 10 предупреждений; остаток назван числом", () => {
+  const out = Array.from({ length: 14 }, (_, i) => `src/a.py:${i + 1}: находка ${i + 1}`).join("\n");
+  const r = annotations([{ name: "g", ok: false, out }], { exists });
+  assert.equal(r.lines.filter((l) => l.startsWith("::error")).length, 10);
+  assert.equal(r.dropped, 4);
+});
+
+// Поймано конвейером на первом прогоне: при --since пометки вешались на находки ВНЕ дифа, потому
+// что брались из сырого вывода. Показанное прогоном — единственный источник.
+test("пометки берутся из показанного прогоном, а не из сырого вывода", () => {
+  const r = annotations([{ name: "g", ok: false, out: "src/a.py:1: в дифе\nkit/x.sh:2: вне дифа\n", shown: "src/a.py:1: в дифе" }], { exists });
+  assert.deepEqual(r.lines, ["::error file=src/a.py,line=1,title=aqk%3A g::в дифе"]);
+});

package/tool/selfcheck/units-cadence.mjs

@@ -7,7 +7,7 @@
 // незачем, а сто коммитов за день перепроверить надо.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed } from "../lib/cadence.mjs";
+import { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed, parseCounts, levelLimits } from "../lib/cadence.mjs";
 
 test("порог по умолчанию — сто коммитов, и он назван числом, а не спрятан", () => {
   assert.equal(PROBE_EVERY, 100);
@@ -117,3 +117,28 @@ test("проба сама не запускается в конвейере, в
   // Явное AQK_PROBE=1 включает и в конвейере: у всего, что решено за человека, есть способ решить иначе.
   assert.equal(autoProbeAllowed({ brief: false, env: { CI: "true", AQK_PROBE: "1" } }), true);
 });
+
+// --- чего уровень НЕ доказывает --------------------------------------------------
+// Отзыв с живого проекта 2026-09-11: «после одного --run у нас AQK-3, All levels reached. При
+// этом CI ни разу не запускался, а probe засчитывает всё подряд. Уровень меряет наличие
+// артефактов, а не то, что они работают». Смысл ступеней не меняем — поднимать планку молча
+// значит отнять опубликованный уровень у всех разом; вместо этого под уровнем стоит, чего он
+// не доказывает, и что про это знает последняя проба.
+test("отметка пробы несёт числа пойманных и недоказанных, старая — «не знаем»", () => {
+  assert.deepEqual(parseCounts("at: 5\nblind: 0\ncaught: 7\nunknown: 2\n"), { caught: 7, unknown: 2 });
+  assert.equal(parseCounts("at: 5\nblind: 0\n"), null, "старая отметка: чисел нет — это не ноль");
+});
+
+test("строка про брак в ваших файлах говорит ровно то, что знает проба", () => {
+  assert.equal(levelLimits(null).kind, "never");
+  assert.equal(levelLimits({ state: "never", behind: null, classes: [], ran: null }).kind, "never");
+  assert.equal(levelLimits({ state: "off" }).kind, "off");
+  const blind = levelLimits({ state: "fresh", behind: 3, classes: [{ slug: "swallowed-error", file: "a.py" }], ran: new Set(), counts: { caught: 4, unknown: 0 } });
+  assert.deepEqual([blind.kind, blind.names, blind.behind], ["blind", ["swallowed-error"], 3], "непойманное — первым, даже если пойманного больше");
+  const part = levelLimits({ state: "fresh", behind: 0, classes: [], ran: new Set(), counts: { caught: 4, unknown: 2 } });
+  assert.deepEqual([part.kind, part.caught, part.unknown], ["partial", 4, 2]);
+  assert.equal(levelLimits({ state: "stale", behind: 150, classes: [], ran: new Set(), counts: { caught: 5, unknown: 0 } }).kind, "caught");
+  assert.equal(levelLimits({ state: "fresh", behind: 1, classes: [], ran: new Set(), counts: { caught: 0, unknown: 0 } }).kind, "nothing");
+  assert.equal(levelLimits({ state: "fresh", behind: 1, classes: [], ran: new Set(), counts: null }).kind, "old", "старая отметка — «подробности в пробе», а не «всё поймано»");
+  assert.equal(levelLimits({ state: "unknown", behind: null, classes: [], ran: new Set(), counts: { caught: 2, unknown: 0 } }).kind, "caught", "без git отметка всё равно читается");
+});

package/tool/selfcheck/units-learn.mjs

@@ -86,3 +86,35 @@ test("typedFrom: реплика блоками собирается из тек
   });
   assert.equal(typedFrom(line)[0].text, "всегда так");
 });
+
+// ПОВТОР — СИГНАЛ, КОТОРЫЙ ДАЁТ САМ ЧЕЛОВЕК. Разбор AgentLint 2026-09-11: их SS2 сопоставляет
+// поправку с правилом свода по словам. Замер на логах владельца: из 45 поправок к записанным
+// правилам относятся от силы две — такой приём дал бы шум. Зато человек сам помечает повтор:
+// «я же говорил», «опять», «снова». Из 14 таких реплик в одном проекте настоящих норм 5–6, и
+// прежний отбор по маркерам наставления не ловил НИ ОДНОЙ.
+test("isRepeat: «я же говорил», «опять», «снова» — повтор; «опять же» и вопрос-недоумение — нет", async () => {
+  const { isRepeat } = await import("../commands/learn.mjs");
+  assert.equal(isRepeat("нет старые задачи не трогаем я же говорил только пусть новые так работают"), true);
+  assert.equal(isRepeat("стой зачем ты сумму убрал я же не просил этого ты опять не верно меня понял"), true);
+  assert.equal(isRepeat("ок давай запишем, только опять не хочу плодить файлы"), true);
+  assert.equal(isRepeat("I told you not to touch the lockfile"), true);
+  assert.equal(isRepeat("и сказать в чате, опять же, где что смотреть"), false, "«опять же» — связка, а не повтор");
+  assert.equal(isRepeat("ок го дальше"), false);
+  // Второй прогон на тех же логах: половина шума — вопросы-недоумения и вставленные цитаты агента.
+  assert.equal(isRepeat("не понял еще нужно что то опять в env добавить?"), false, "вопрос с «опять» — недоумение, а не норма");
+  assert.equal(isRepeat("⬜ Два мира ролей — всплывёт, если снова будем трогать роли. поясни"), false, "цитата ответа агента");
+  assert.equal(isRepeat("почему ты так долго тестируешь я же говорю не нужно столько тестов?"), true, "сильная пометка держится и с вопросом");
+});
+
+// Повтор, совпавший с правилом свода, — главное, что может сказать эта команда: правило
+// записано, а человек всё равно поправляет. Текстом оно не держится — ему нужен сторож.
+test("repeatedRules: повтор, совпавший с правилом свода, называет это правило", async () => {
+  const { repeatedRules } = await import("../commands/learn.mjs");
+  const entry = "# Правила\n\n- **Не плодить файлы.** Новый файл — только если без него нельзя. <!-- aqk: человек -->\n" +
+    "- **Секреты только в .env.** <!-- aqk: secrets-not-in-code -->\n- обычная строка списка без метки\n";
+  const hits = repeatedRules([{ text: "опять ты плодишь файлы, я же говорил", when: "2026-09-03" }], entry);
+  assert.equal(hits.length, 1);
+  assert.match(hits[0].rule, /Не плодить файлы/);
+  assert.equal(hits[0].arbiter, "человек");
+  assert.equal(repeatedRules([{ text: "опять не тот цвет кнопки", when: "x" }], entry).length, 0, "повтор не про правило — не сюда");
+});

package/tool/selfcheck/units-level.mjs

@@ -11,7 +11,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { commandFor, verdict } from "../lib/prove.mjs";
 import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS, parseManifest, coversOf, coversUnproven, unparsedLines } from "../lib/manifest.mjs";
-import { pickLang, langFromText } from "../i18n/index.mjs";
+import { pickLang, langFromText, langFromDocs } from "../i18n/index.mjs";
 import { progress, selectGates } from "../lib/run.mjs";
 
 // --- строка «идёт» во время прогона ---------------------------------------------------
@@ -214,6 +214,26 @@ test("мусор в поле lang не молчит, а просто не дей
   assert.equal(pickLang({}, { lang: "клингонский" }), "en");
 });
 
+// Отзыв с живого проекта 2026-09-11: свод правил и методички на русском, машина на Windows без
+// LANG — и весь вывод английский, пока руками не впишешь `lang:`. Язык текста, который проект
+// сам о себе написал, — свойство проекта; поэтому он выше локали и ниже манифеста.
+test("язык свода проекта сильнее локали и слабее манифеста", () => {
+  const ruDoc = "# Правила\n\nПеред коммитом запусти `npm run check` и `make gates`. Схемы живут в " +
+    "`packages/contract`, их проверяет сервер.\n\n```sh\nnpm run typecheck && npm run lint\n```\n" +
+    "Любое изменение договора проходит через ревью и фиксируется в журнале решений.\n";
+  const enDoc = "# Rules\n\nBefore committing run `npm run check`. Schemas live in packages/contract " +
+    "and the server validates them. Every contract change goes through review and is logged.\n";
+  assert.equal(langFromDocs(ruDoc.repeat(2)), "ru", "русский свод с кодом внутри не узнан");
+  assert.equal(langFromDocs(enDoc.repeat(2)), "en");
+  assert.equal(langFromDocs("# X\n\n`npm test`\n"), "", "по трём словам язык не решается");
+  assert.equal(pickLang({ LANG: "en_US.UTF-8" }, null, "ru"), "ru");
+  assert.equal(pickLang({}, null, "ru"), "ru", "Windows без LANG: свод решает");
+  assert.equal(pickLang({ LANG: "ru_RU.UTF-8" }, null, "en"), "en");
+  assert.equal(pickLang({}, { lang: "en" }, "ru"), "en", "манифест сильнее свода");
+  assert.equal(pickLang({ AQK_LANG: "en" }, null, "ru"), "en", "переменная сильнее свода");
+  assert.equal(pickLang({ LANG: "ru_RU.UTF-8" }, null, ""), "ru", "свод молчит — решает локаль");
+});
+
 // Сокращённый разбор языка в i18n/index.mjs существует потому, что каталог строк нужен раньше,
 // чем кто-либо успеет прочитать манифест целиком. Два разбора одного файла — то же, что два
 // свода правил: через месяц они расходятся, и непонятно, какой настоящий. Сверяем ответы.

package/tool/selfcheck/units-prompt.mjs

@@ -0,0 +1,106 @@
+// tool/selfcheck/units-prompt.mjs — задание для агента одним текстом (`aqk prompt`).
+//
+// ЗАЧЕМ. Между диагнозом и действием не было моста: `doctor` пишет человеку, `context` — «как
+// дела» агенту, а «почини вот это, это и это» человек пересказывал сам. Идея — из разбора
+// agentlint (research/competitors/agentlint.md, «Задание для агента»): правила поведения
+// сверху, исправления по весу, в конце — как проверить. Их слабость не берём: у них «проверь» —
+// это «балл вырос», у нас — команда, которая краснеет и зеленеет.
+//
+//   node --test tool/selfcheck/units-prompt.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { taskText } from "../commands/prompt.mjs";
+import { CATALOGS } from "../i18n/index.mjs";
+
+const T = CATALOGS.ru.prompt;
+const base = {
+  self: "aqk", manifest: true, run: { when: "2026-09-11 12:00", red: [], stale: false },
+  blind: [], adopt: [], shim: null, start: [],
+};
+const text = (s) => taskText({ ...base, ...s }, T).join("\n");
+const items = (s) => text(s).split("\n").filter((l) => /^\d+\. /.test(l));
+
+test("правила поведения сверху и проверка в конце — всегда, даже когда пунктов нет", () => {
+  const t = text({});
+  assert.ok(t.indexOf(T.rulesTitle) < t.indexOf(T.verifyTitle), "правила идут до проверки");
+  assert.match(t, /aqk doctor --run/, "без команды проверки «готово» ничем не доказано");
+  assert.match(t, new RegExp(T.empty.slice(0, 20)), "пустое задание сказано словами");
+});
+
+test("красный гейт — пункт с командой, которая его запускает одного", () => {
+  const it = items({ run: { when: "x", red: ["lint", "units"], stale: false } });
+  assert.equal(it.length, 2);
+  assert.match(it[0], /aqk doctor --run --only lint/);
+});
+
+// Прогона не было или он старше последнего коммита: список красных — про другой код. Первый
+// пункт — прогнать; пустое задание при этом было бы утверждением «чисто», которого никто не делал.
+test("нет прогона или он устарел — первый пункт «прогони», а не «всё чисто»", () => {
+  const none = text({ run: null });
+  assert.doesNotMatch(none, new RegExp(T.empty.slice(0, 20)), "без прогона задание не пустое");
+  assert.match(items({ run: null })[0], /aqk doctor --run/);
+  const stale = items({ run: { when: "x", red: ["lint"], stale: true } });
+  assert.match(stale[0], /aqk doctor --run/, "устаревший прогон — сначала прогнать заново");
+});
+
+test("порядок по весу: манифест → красное → брак из пробы → свои проверки → свод → начало", () => {
+  const it = items({
+    manifest: false,
+    run: { when: "x", red: ["lint"], stale: false },
+    blind: [{ slug: "swallowed-error", file: "src/a.py", command: "ruff check --select BLE ." }],
+    adopt: [{ name: "test", cmd: "npm test", source: "package.json" }],
+    shim: "missing",
+    start: [{ slug: "secrets-not-in-code", intent: "ключи не в коде", command: "gitleaks dir ." }],
+  });
+  assert.match(it[0], /aqk init/);
+  assert.match(it[1], /lint/);
+  assert.match(it[2], /swallowed-error.*src\/a\.py/);
+  assert.match(it[3], /npm test/);
+  assert.match(it[4], /@AGENTS\.md/);
+  assert.equal(it.length, 5, "больше пяти за раз агент не удержит");
+  assert.match(text({
+    manifest: false, run: { when: "x", red: ["lint"], stale: false },
+    blind: [{ slug: "s", file: "f", command: "" }], adopt: [{ name: "t", cmd: "c", source: "p" }],
+    shim: "missing", start: [{ slug: "x", intent: "y", command: "" }],
+  }), new RegExp(T.more(1).slice(0, 12)), "остаток назван числом, а не выброшен молча");
+});
+
+test("класс из пробы не повторяется в «начните с»; без готовой команды — aqk add", () => {
+  const it = items({
+    blind: [{ slug: "swallowed-error", file: "src/a.py", command: "" }],
+    start: [{ slug: "swallowed-error", intent: "i", command: "" }, { slug: "todo-without-task", intent: "i", command: "" }],
+  });
+  assert.equal(it.length, 2);
+  assert.match(it[0], /aqk add swallowed-error/);
+  assert.match(it[1], /todo-without-task/);
+});
+
+// Гейт стоит, проба его гоняла — и он пропустил. Не «поставь» (стоит), а «здесь он слеп».
+test("гейт стоит, но пропустил брак из пробы — пункт «разберись», сразу после красных", () => {
+  const it = items({
+    run: { when: "x", red: ["lint"], stale: false },
+    missed: [{ slug: "swallowed-error", file: "src/a.py" }],
+    start: [{ slug: "todo-without-task", intent: "i", command: "" }],
+  });
+  assert.match(it[1], /swallowed-error.*src\/a\.py/);
+  assert.doesNotMatch(it[1], /aqk add/, "гейт уже стоит — ставить его второй раз бессмысленно");
+});
+
+test("у каждого пункта — чем доказать, что готово", () => {
+  const it = items({
+    run: { when: "x", red: ["lint"], stale: false },
+    blind: [{ slug: "swallowed-error", file: "src/a.py", command: "" }],
+    missed: [{ slug: "complexity-limit", file: "src/b.py" }],
+    start: [{ slug: "todo-without-task", intent: "i", command: "" }],
+  });
+  for (const line of it) assert.match(line, new RegExp(T.done.slice(0, 6)), `пункт без арбитра: ${line}`);
+});
+
+test("оба языка несут одни и те же ключи задания", () => {
+  const keys = (o) => Object.keys(o).sort().join(",");
+  assert.equal(keys(CATALOGS.ru.prompt), keys(CATALOGS.en.prompt));
+  // Пункты лежат глубже — пропущенный в одном языке пункт упал бы ошибкой только у того, кто
+  // на этом языке работает.
+  assert.equal(keys(CATALOGS.ru.prompt.item), keys(CATALOGS.en.prompt.item));
+  assert.equal(keys(CATALOGS.ru.prompt.item.shim), keys(CATALOGS.en.prompt.item.shim));
+});

package/tool/selfcheck/units-repo.mjs

@@ -8,7 +8,7 @@
 //   node --test tool/selfcheck/units-repo.mjs
 import test from "node:test";
 import assert from "node:assert/strict";
-import { triggerVerdict, recipeFor, EXT_LANG, whichSync, browserServerAdvice, MARKS, isApiSpec } from "../lib/repo.mjs";
+import { triggerVerdict, recipeFor, EXT_LANG, whichSync, browserServerAdvice, MARKS, isApiSpec, claudeSeesRules } from "../lib/repo.mjs";
 import { startWith } from "../lib/advice.mjs";
 import { proposeGates } from "../lib/adopt.mjs";
 import { CATALOGS, L } from "../i18n/index.mjs";
@@ -308,3 +308,22 @@ test("совет проекту на Biome: команда Biome, а не eslint
   const none = blindAdvice({ ...entry, biome_rules: "none" }, { langs: new Set(["javascript"]), has_biome: true });
   assert.match(none.command, /^eslint /);
 });
+
+// --- свод виден Claude Code --------------------------------------------------------
+// Документация Claude Code (code.claude.com/docs/en/memory, раздел AGENTS.md, сверено
+// 2026-09-11): «Claude Code reads CLAUDE.md, not AGENTS.md». Рекомендовано: CLAUDE.md с
+// @AGENTS.md либо символическая ссылка. Проект, где Claude Code настроен, а свод лежит только
+// в AGENTS.md, пишет правила агенту, который их не читает.
+test("свод в AGENTS.md виден Claude Code только через CLAUDE.md с @AGENTS.md", () => {
+  const base = { agents: true, claude: null, claudeLink: false, dotClaude: false };
+  assert.equal(claudeSeesRules(base), null, "Claude Code не настроен — молчим: Codex и Cursor читают AGENTS.md сами");
+  assert.equal(claudeSeesRules({ ...base, dotClaude: true }), "missing");
+  assert.equal(claudeSeesRules({ ...base, claude: "# Rules\n\nSee AGENTS.md for everything.\n" }), "noImport",
+    "упоминание словами — не подключение: файл Claude Code в контекст не загрузит");
+  assert.equal(claudeSeesRules({ ...base, claude: "# CLAUDE.md\n\n@AGENTS.md\n" }), null);
+  assert.equal(claudeSeesRules({ ...base, claude: "@../AGENTS.md\n" }), null, "из .claude/CLAUDE.md свод подключают на уровень выше");
+  assert.equal(claudeSeesRules({ ...base, claude: "Правила — в `@AGENTS.md`.\n" }), "noImport",
+    "в обратных кавычках @ не подключает — так в документации");
+  assert.equal(claudeSeesRules({ ...base, claude: "x", claudeLink: true }), null, "ссылка на AGENTS.md — тот же файл");
+  assert.equal(claudeSeesRules({ ...base, agents: false, dotClaude: true }), null, "AGENTS.md нет — подключать нечего");
+});