agent-quality-kit 0.12.0 → 0.14.0

package/tool/lib/annotate.mjs

@@ -0,0 +1,66 @@
+// tool/lib/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), а не их код.
+//
+// ЧТО НЕ ДЕЛАЕТСЯ НИКОГДА: пометка не меняет вердикт. Это печать того же, что уже решил прогон.
+import { splitAdvice, normPath } from "./scope.mjs";
+
+const ANSI = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*[a-zA-Z]", "g");
+
+// Потолок. В документации GitHub лимита не нашли; в обсуждении сообщества 2020 года
+// (github.com/orgs/community/discussions/26680): «10 warning annotations and 10 error annotations
+// per step». Прогон `doctor` — один шаг, поэтому потолок на весь прогон, а остаток — числом в лог.
+const LIMIT = 10;
+
+// Путь с расширением или с косой чертой — как в scope.mjs. Две формы строки находки: «файл:строка:
+// текст» (grep -n, линтеры, иногда ещё «:колонка») и «файл: текст» (наши записи каталога).
+const PATH = "(?:\\.\\/)?((?:[\\w.@+-]+\\/)*[\\w.@+-]+\\.[A-Za-z][A-Za-z0-9]{0,9})";
+const WITH_LINE = new RegExp(`^${PATH}:(\\d+)(?::\\d+)?:\\s*([\\s\\S]*)$`);
+const NO_LINE = new RegExp(`^${PATH}:\\s+([\\s\\S]+)$`);
+
+function locate(raw) {
+  const plain = String(raw).replace(ANSI, "").trim();
+  if (/^(почини|fix)\s*:/i.test(plain)) return null;
+  let m = WITH_LINE.exec(plain);
+  if (m) return { file: normPath(m[1]), line: Number(m[2]), message: m[3] || plain };
+  m = NO_LINE.exec(plain);
+  if (m) return { file: normPath(m[1]), line: null, message: m[2] };
+  return null;
+}
+
+const escData = (s) => String(s).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const escProp = (s) => escData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+
+// results — те же записи, что возвращает runGates: { name, ok, advisory, out, shown }. Берётся
+// `shown` — показанное прогоном после сужения по дифу; сырой `out` — только если его нет. exists(путь) —
+// есть ли файл в репозитории: пометка на несуществующий файл GitHub вешает на `.github`, и
+// человек ищет то, чего нет. Такая находка идёт общей пометкой гейта без файла.
+function annotations(results, { exists = () => true, limit = LIMIT } = {}) {
+  const lines = [];
+  const used = { error: 0, warning: 0 };
+  let dropped = 0;
+  const emit = (level, title, message, loc = null) => {
+    if (used[level] >= limit) { dropped++; return; }
+    used[level]++;
+    const props = loc ? [`file=${escProp(loc.file)}`, ...(loc.line ? [`line=${loc.line}`] : [])] : [];
+    props.push(`title=${escProp(title)}`);
+    lines.push(`::${level} ${props.join(",")}::${escData(message)}`);
+  };
+  for (const r of results || []) {
+    if (r.ok) continue;
+    const level = r.advisory ? "warning" : "error";
+    const title = `aqk: ${r.name}`;
+    const { findings, advice } = splitAdvice(String(r.shown ?? r.out ?? "").split("\n").filter((l) => l.trim()));
+    const fix = advice.length ? ` — ${String(advice[0]).replace(ANSI, "").trim()}` : "";
+    const located = findings.map(locate).filter((f) => f && exists(f.file));
+    for (const f of located) emit(level, title, `${f.message}${fix}`, f);
+    if (!located.length) emit(level, title, `${String(findings[0] || r.note || "").replace(ANSI, "").trim()}${fix}`);
+  }
+  return { lines, dropped };
+}
+
+export { locate, annotations };

package/tool/lib/brief.mjs

@@ -112,7 +112,9 @@ function beginBrief() {
 
 // Печать краткого итога. Совет — не чаще раза в сутки и с явным способом отказаться: то, что
 // видишь тридцатый раз, перестаёт читаться и пролистывается вместе с настоящими находками рядом.
-// Отметка времени лежит в .aqk/, который в .gitignore: это состояние машины, а не проекта.
+// Отметка времени лежит в .aqk/ и попадает в .gitignore при `init` (RUNTIME_FILES в core.mjs):
+// это состояние машины, а не проекта. Раньше здесь было написано «.aqk/ в .gitignore» — а
+// `init` туда ничего не клал, и на живом проекте служебный файл уехал в коммит.
 async function finishBrief(buf, state, todoRecs, ok) {
   if (!buf) return;
   buf.restore();

package/tool/lib/cadence.mjs

@@ -89,4 +89,43 @@ function parseRan(text) {
   return m ? new Set(m[1].split(/\s+/).filter(Boolean)) : null;
 }
 
-export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan };
+// Запускаться ли пробе САМОЙ внутри `doctor --run`. Не в конвейере: там это +2–3 минуты сюрпризом
+// в случайном прогоне (отзыв с живого проекта 2026-09-11), и место пробы — отдельная задача. Не в
+// коротком режиме: там хук на воротах коммита. `AQK_PROBE=0` — выключить, `AQK_PROBE=1` — включить
+// и в конвейере.
+function autoProbeAllowed({ brief = false, env = process.env } = {}) {
+  if (env.AQK_PROBE === "0" || brief) return false;
+  if (env.AQK_PROBE === "1") return true;
+  return !(env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI || env.BUILDKITE || env.JENKINS_URL);
+}
+
+// Сколько классов проба поймала и у скольких поимка не доказана. Старая отметка чисел не несёт —
+// null: «не знаем», а не «ноль пойманных».
+function parseCounts(text) {
+  const caught = /^caught:[ \t]*(\d+)/m.exec(String(text || ""));
+  const unknown = /^unknown:[ \t]*(\d+)/m.exec(String(text || ""));
+  return caught && unknown ? { caught: Number(caught[1]), unknown: Number(unknown[1]) } : null;
+}
+
+// Чего уровень НЕ доказывает — строкой под ним. Отзыв с живого проекта 2026-09-11: «AQK-3, All
+// levels reached» при конвейере, который ни разу не запускался. Ступени меряют оснащённость:
+// гейты показаны на образцах КАТАЛОГА. Ловят ли они брак в файлах ПРОЕКТА, знает только проба —
+// и строка говорит ровно то, что знает она. Непойманное идёт первым, даже если пойманного
+// больше: «четыре из пяти» глаз читает как «всё хорошо».
+//
+// Планку ступеней не подняли намеренно: отметка пробы лежит в .gitignore, в конвейере её нет, и
+// «AQK-2 только после пробы» уронило бы уровень и `badge --check` у всех разом.
+function levelLimits(st) {
+  if (st?.state === "off") return { kind: "off" };
+  const behind = Number.isFinite(st?.behind) ? st.behind : null;
+  if (st?.classes?.length) return { kind: "blind", names: st.classes.map((x) => x.slug), behind };
+  if (st?.counts) {
+    const { caught, unknown } = st.counts;
+    if (unknown > 0) return { kind: "partial", caught, unknown, behind };
+    return caught > 0 ? { kind: "caught", caught, behind } : { kind: "nothing", behind };
+  }
+  if (st?.ran) return { kind: "old", behind };
+  return { kind: "never" };
+}
+
+export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed, parseCounts, levelLimits };

package/tool/lib/core.mjs

@@ -83,6 +83,7 @@ function commandRows(L) {
     { name: "learn", args: "", text: h.learn },
     { name: "context", args: "", text: h.context },
     { name: "context", args: "--full --install", text: h.contextInstall },
+    { name: "prompt", args: "", text: h.prompt },
     { name: "badge", args: "", text: h.badge },
     { name: "vitals", args: "", text: h.vitals },
     { name: "version", args: "", text: h.version },
@@ -142,9 +143,47 @@ async function writeIfAbsent(path, content, { force }) {
   return true;
 }
 
+// СЛУЖЕБНЫЕ ФАЙЛЫ: состояние ЭТОЙ машины, переписываются каждым прогоном — в git им не место.
+// Один список на `init` (кладёт в .gitignore), `doctor` (предупреждает, если git их видит) и
+// читателей. Отзыв с живого проекта 2026-09-11: `.aqk/last-run.md` однажды закоммитили, и каждый
+// `make check` оставлял изменённый файл. Целиком `.aqk/` не игнорируется: методички и правила в
+// нём — содержимое проекта.
+const RUNTIME_FILES = ["last-run.md", "last-probe.md", "advice-shown", "update-checked"];
+const L_IGNORE_NOTE = LANG === "en"
+  ? "# aqk: this machine's state — rewritten by every run, it does not belong in git"
+  : "# aqk: состояние этой машины — переписывается каждым прогоном, в git ему не место";
+
+// Дописать служебные файлы в .gitignore, не трогая чужих строк и не дублируя своих. Возвращает
+// список добавленных строк — `init` называет их вслух: правка чужого файла без слова была бы
+// тем самым «пишу в дерево без спроса».
+async function ensureIgnored(cwd = CWD) {
+  const { readFile, writeFile } = await import("node:fs/promises");
+  const file = join(cwd, ".gitignore");
+  let text = "";
+  try { text = await readFile(file, "utf8"); } catch { /* файла нет — создадим */ }
+  const have = new Set(text.split(/\r?\n/).map((l) => l.trim()));
+  const add = RUNTIME_FILES.map((f) => `${TARGET_DIR}/${f}`).filter((l) => !have.has(l) && !have.has(`/${l}`));
+  if (!add.length) return [];
+  const head = text && !text.endsWith("\n") ? "\n" : "";
+  await writeFile(file, `${text}${head}${text ? "\n" : ""}${L_IGNORE_NOTE}\n${add.join("\n")}\n`, "utf8");
+  return add;
+}
+
+// Стоит ли хук pre-commit НА САМОМ ДЕЛЕ — в `.git/hooks`, а не в `.pre-commit-config.yaml`:
+// запись в конфиге — намерение, сработает только то, что лежит в гите. Три ответа: true — стоит,
+// false — нет, null — не git или файл не прочитать («не знаем» не сливается с «нет»).
+// Одна функция на `vitals` (подключено ли) и `context` (что сказать агенту перед коммитом).
+async function preCommitHook(cwd = CWD) {
+  const { readFile } = await import("node:fs/promises");
+  if (!(await exists(join(cwd, ".git")))) return null;
+  const hook = join(cwd, ".git", "hooks", "pre-commit");
+  if (!(await exists(hook))) return false;
+  try { return /pre-commit|aqk/i.test(await readFile(hook, "utf8")); } catch { return null; }
+}
+
 export {
   copyDir, writeIfAbsent,
   PKG_ROOT, CWD, DOCS_SRC, RULES_SRC, TARGET_DIR, docPath,
   MANIFEST, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB,
-  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK, commandRows,
+  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK, commandRows, preCommitHook, RUNTIME_FILES, ensureIgnored,
 };

package/tool/lib/gate-worker.mjs

@@ -0,0 +1,18 @@
+// tool/lib/gate-worker.mjs — рабочий поток параллельного прогона (`doctor --run --jobs N`).
+//
+// ПОЧЕМУ ПОТОК, А НЕ АСИНХРОННЫЙ ЗАПУСК. Прогон стоит на `spawnSync` с таймаутом: его поведение
+// на зависшем гейте замерено и описано (execution.mjs). Асинхронный `spawn` потребовал бы своего
+// убийства дерева процессов на таймауте — на Windows это отдельная история. Поток выполняет ТОТ ЖЕ
+// `spawnSync` с тем же таймаутом, и семантика прогона не меняется ни в чём, кроме одновременности.
+// Зависимостей это не добавляет: worker_threads встроены в Node.
+import { parentPort } from "node:worker_threads";
+import { spawnSync } from "node:child_process";
+import { gateCommand } from "./execution.mjs";
+
+parentPort.on("message", ({ id, cmd, cwd, timeout }) => {
+  const r = spawnSync(gateCommand(cmd), { shell: true, cwd, encoding: "utf8", timeout });
+  parentPort.postMessage({
+    id, status: r.status, stdout: r.stdout || "", stderr: r.stderr || "",
+    error: r.error ? { code: r.error.code || String(r.error.message || r.error) } : null,
+  });
+});

package/tool/lib/history.mjs

@@ -117,9 +117,36 @@ function probeSummary({ caught = 0, blind = 0, unknown = 0, unprobed = 0 } = {})
 // Найдено пробой на самом комплекте 2026-09-11: образец лёг на место общей библиотеки
 // kit/gates/_skip.sh, двенадцать гейтов вышли с кодом 2 — включая тот, что этот образец в
 // отдельной папке ловит. Остальные молчали, и проба назвала класс слепым.
+// «ПОКРАСНЕЛ» ≠ «ПОЙМАЛ». Отзыв с живого проекта 2026-09-11: класс «цвет из токена темы» отмечен
+// пойманным линтером, хотя Biome цвета не проверяет, — подсаженный кусок сломал форматирование.
+// Вердикт сравнивал коды возврата и выбрасывал вывод. Теперь гейт засчитывается, только если в
+// его выводе ПОСЛЕ подсадки подсаженный файл назван чаще, чем до неё. Путь ищется в любой
+// форме: `src/x`, `./src/x`, абсолютный из песочницы (подстрока), с обратными слешами Windows.
+// Одно имя файла без каталога не засчитывается: у двух файлов оно бывает одинаковым, и
+// поимка чужого файла выдалась бы за поимку нашего. Безымянное падение — «неизвестно».
+function namesPlant(before, after, rel) {
+  const forms = [rel, String(rel).replace(/\//g, "\\")];
+  const count = (s) => forms.reduce((n, f) => n + String(s || "").split(f).length - 1, 0);
+  return count(after) > count(before);
+}
+
+// ПАРА, А НЕ ОДИН ОБРАЗЕЦ. Имени файла мало: Biome, падая на форматировании, тоже называет файл.
+// Поэтому поимка подтверждается зелёным образцом той же записи, положенным в то же место, — тем
+// же приёмом, каким мы требуем от чужого гейта доказательства. Три исхода:
+//   caught   — на красном покраснел и назвал файл, на зелёном промолчал (или файла не назвал);
+//   nameless — покраснел, но подсаженного файла не назвал: упал по своей причине;
+//   planting — краснеет и на зелёном, называя тот же файл: падает от самой подсадки.
+// Зелёного образца под это расширение нет — судим по имени файла: пусть слабее, но это не
+// «поймано» на ровном месте, и в README записи такой случай назван.
+function catchVerdict(beforeOut, red, green, rel) {
+  if (!namesPlant(beforeOut, red?.out, rel)) return "nameless";
+  if (green && green.code === 1 && namesPlant(beforeOut, green.out, rel)) return "planting";
+  return "caught";
+}
+
 function probeVerdictPaired(before, after) {
   const byName = new Map(after.map((r) => [r.name, r]));
-  let usable = 0, alreadyRed = 0, failed = 0, caught = 0, brokenByPlant = 0;
+  let usable = 0, alreadyRed = 0, failed = 0, caught = 0, brokenByPlant = 0, unattributed = 0;
   for (const b of before) {
     const a = byName.get(b.name);
     const broke = (r) => !r || (r.code !== 0 && r.code !== 1);
@@ -130,10 +157,12 @@ function probeVerdictPaired(before, after) {
     }
     if (b.code === 1) { alreadyRed++; continue; }
     usable++;
-    if (a.code === 1) caught++;
+    // `named === false` — покраснел, но подсаженного файла не назвал. `undefined` — вызывающий
+    // вывода не собирал (старые вызовы): тогда прежнее правило.
+    if (a.code === 1) { if (a.named === false) unattributed++; else caught++; }
   }
-  const verdict = caught ? "caught" : !usable || brokenByPlant ? "unknown" : "blind";
-  return { verdict, usable, alreadyRed, failed, caught, brokenByPlant };
+  const verdict = caught ? "caught" : !usable || brokenByPlant || unattributed ? "unknown" : "blind";
+  return { verdict, usable, alreadyRed, failed, caught, brokenByPlant, unattributed };
 }
 
 // Счёт непокрытого КЛАССАМИ, а не пробами. Замер на десяти живых репозиториях 2026-09-10:
@@ -160,4 +189,4 @@ function countProbe(records) {
   };
 }
 
-export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe };
+export { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe, namesPlant, catchVerdict };

package/tool/lib/manifest.mjs

@@ -112,7 +112,7 @@ function unparsedLines(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "lang", "gates", "covers", "samples", "ratchets", "lessons", "advisory", "probe"];
+const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "lang", "gates", "covers", "samples", "ratchets", "lessons", "advisory", "probe", "groups"];
 
 // ГДЕ У ПРОЕКТА ЛЕЖИТ РАЗЛОЖЕННЫЙ КОМПЛЕКТ. Список для шапки `doctor`. До 2026-09-08 он был
 // литеральным: `.aqk/rules`, `.aqk/docs`, `AGENTS.md` — независимо от того, что написано в
@@ -132,12 +132,16 @@ function layoutChecks(man, inKit) {
   const entries = (Array.isArray(man?.entry) ? man.entry : [])
     .filter((e) => typeof e === "string" && e.trim())
     .map((e) => e.trim());
+  // Третий элемент — обязателен ли пункт. Методички и стандарты `init` кладёт как пособие: проект
+  // вправе держать их где-то ещё или не держать вовсе, и их отсутствие — совет, а не приговор
+  // прогону (отзыв с живого проекта 2026-09-11: прогон краснел только из-за `.aqk/docs`). Точка
+  // входа, .gitignore и .git — обязательны: на них стоит своя проверка вердикта.
   return [
-    [field("docs", inKit ? "kit/docs" : ".aqk/docs"), inKit ? L.doctor.docsKit : L.doctor.docs],
-    [field("rules", inKit ? "kit/rules" : ".aqk/rules"), inKit ? L.doctor.rulesKit : L.doctor.rules],
-    ...(entries.length ? entries : ["AGENTS.md"]).map((e) => [e, L.doctor.agents]),
-    [".gitignore", L.doctor.gitignore],
-    [".git", L.doctor.git],
+    [field("docs", inKit ? "kit/docs" : ".aqk/docs"), inKit ? L.doctor.docsKit : L.doctor.docs, false],
+    [field("rules", inKit ? "kit/rules" : ".aqk/rules"), inKit ? L.doctor.rulesKit : L.doctor.rules, false],
+    ...(entries.length ? entries : ["AGENTS.md"]).map((e) => [e, L.doctor.agents, true]),
+    [".gitignore", L.doctor.gitignore, true],
+    [".git", L.doctor.git, true],
   ];
 }
 
@@ -188,28 +192,68 @@ function coversOf(man) {
 // вывод перестают читать целиком, вместе с настоящими находками.
 const RULE_CODES = /--select[= ]([A-Za-z0-9,]+)/;
 
-function coversUnproven(man, catalog = [], linterConfigText = "") {
+// КАКИМ ЛИНТЕРОМ ЗАКРЫТ ГЕЙТ. Отзыв с живого проекта 2026-09-11 (TypeScript на Biome): заявка
+// «lint держит no-print-in-prod» всегда была «не подтверждена» — сверка искала коды ruff в
+// конфиге Biome, где их не бывает никогда. Поле, снимающее шум, само его производило.
+// Порядок: команда гейта; npm-скрипт, который она зовёт; единственный конфиг линтера в проекте.
+function linterOf(cmd, scripts = {}, present = []) {
+  let c = String(cmd || "");
+  const m = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?([\w:-]+)/.exec(c);
+  if (m && typeof scripts[m[1]] === "string") c += ` ${scripts[m[1]]}`;
+  if (/\bbiome\b/.test(c)) return "biome";
+  if (/\beslint\b/.test(c)) return "eslint";
+  if (/\bruff\b/.test(c)) return "ruff";
+  return present.length === 1 ? present[0] : null;
+}
+
+// Правила записи на языке ЭТОГО линтера. ruff — коды из `--select` рецептов; eslint — имена из
+// `--rule '{…}'`; Biome рецептов не имеет, у записи для него поле `biome_rules` (сверено по схеме
+// конфигурации Biome 2.5.12). `none` — у линтера такого правила нет вовсе. `null` — не знаем.
+function rulesFor(rec, linter) {
+  const recipes = Object.values(rec?.recipes && typeof rec.recipes === "object" ? rec.recipes : {}).map(String);
+  if (linter === "ruff") {
+    const codes = new Set();
+    for (const cmd of recipes) { const m = RULE_CODES.exec(cmd); if (m) for (const x of m[1].split(",")) if (x.trim()) codes.add(x.trim()); }
+    return codes.size ? [...codes] : null;
+  }
+  if (linter === "eslint") {
+    const names = new Set();
+    for (const cmd of recipes) for (const m of cmd.matchAll(/"([@a-z0-9/_-]+)"\s*:\s*\[?\s*"(?:error|warn)"/g)) names.add(m[1]);
+    return names.size ? [...names] : null;
+  }
+  if (linter === "biome") {
+    const v = typeof rec?.biome_rules === "string" ? rec.biome_rules.trim() : "";
+    if (!v) return null;
+    // Поле хранит `группа/правило` — так его ждёт `biome lint --only`; в biome.json правило
+    // лежит внутри объекта группы, поэтому ищется по имени без группы.
+    return v === "none" ? [] : v.split(",").map((x) => x.trim().split("/").pop()).filter(Boolean);
+  }
+  return null;
+}
+
+// `configs` — тексты конфигов по линтерам: { ruff, eslint, biome, scripts }. Строка (прежний вид
+// вызова) — один общий текст для всех. Исходы: unproven (линтер известен, его правил нет ни в
+// команде, ни в конфиге) · impossible (у линтера такого правила нет) · unknown (линтер не
+// распознан или правил записи для него мы не знаем — «не умею проверить», не обвинение).
+function coversUnproven(man, catalog = [], configs = "") {
   const { covered } = coversOf(man);
   if (!covered.size) return [];
   const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
-  const cfg = String(linterConfigText || "");
+  const cfg = typeof configs === "string" ? { ruff: configs, eslint: configs, biome: configs } : (configs || {});
+  const present = ["ruff", "eslint", "biome"].filter((k) => cfg[k] && String(cfg[k]).trim() && typeof configs !== "string");
   const out = [];
 
   for (const [entry, gate] of covered) {
     const rec = catalog.find((r) => r.slug === entry);
-    const recipes = rec?.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
-    // Коды берутся из любого рецепта записи: язык проекта здесь не важен, важно, что запись
-    // ВООБЩЕ выражается кодами правил. Если ни один рецепт их не называет — сверять нечего.
-    const codes = new Set();
-    for (const cmd of Object.values(recipes)) {
-      const m = RULE_CODES.exec(String(cmd || ""));
-      if (m) for (const c of m[1].split(",")) if (c.trim()) codes.add(c.trim());
-    }
-    if (!codes.size) continue;
-
-    const haystack = `${String(gates[gate] || "")}\n${cfg}`;
-    const missing = [...codes].filter((c) => !haystack.includes(c));
-    if (missing.length === codes.size) out.push({ entry, gate, codes: [...codes] });
+    // Запись, которая не выражается правилами НИ ОДНОГО линтера (переносимые проверки), не
+    // сверяется вовсе: сверять нечего, и выдумывать вердикт нельзя.
+    if (!["ruff", "eslint", "biome"].some((k) => rulesFor(rec, k) !== null)) continue;
+    const linter = linterOf(gates[gate], cfg.scripts || {}, present);
+    const rules = linter ? rulesFor(rec, linter) : null;
+    if (rules === null) { out.push({ entry, gate, codes: [], linter, kind: "unknown" }); continue; }
+    if (!rules.length) { out.push({ entry, gate, codes: [], linter, kind: "impossible" }); continue; }
+    const haystack = `${String(gates[gate] || "")}\n${String(cfg[linter] || "")}`;
+    if (rules.every((r) => !haystack.includes(r))) out.push({ entry, gate, codes: rules, linter, kind: "unproven" });
   }
   return out;
 }

package/tool/lib/repo.mjs

@@ -2,9 +2,8 @@
 // триггера, выбор рецепта, сверка по намерению.
 
 import { readdir, readFile } from "node:fs/promises";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, statSync, lstatSync, realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
 import { CWD, GATES_SRC, c, exists } from "./core.mjs";
 import { parseManifest } from "./manifest.mjs";
 import { L, LANG } from "../i18n/index.mjs";
@@ -34,6 +33,18 @@ function isApiSpec(name) {
   return /^(openapi|swagger|asyncapi)[^/]*\.(ya?ml|json)$/i.test(name);
 }
 
+// Тот же договор без файла: схемы в коде, типы общие у сервера и клиента. Список — тот же, что
+// в `api-contract-has-arbiter/check.sh`; разойдутся — запись покажут не тому проекту, и это
+// сторожит проверка прогона. Один `zod` договором не считается: им разбирают и формы.
+const CODE_CONTRACT = /"(@trpc\/server|@ts-rest\/core|@hono\/zod-openapi|@fastify\/type-provider-[a-z0-9-]+|fastify-type-provider-zod)"\s*:/;
+async function isCodeContract(path) {
+  try {
+    return CODE_CONTRACT.test(await readFile(path, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
 const SKIP_DIRS = new Set([".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__", ".aqk"]);
 
 // Факты о репозитории. Только то, что видно машине: спрашивать человека анкетой
@@ -46,6 +57,8 @@ const MARKS = [
   ["has_docker", ["Dockerfile", "compose.yml", "compose.yaml", "docker-compose.yml", "docker-compose.yaml"]],
   ["has_deps", ["package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml", "Gemfile", "pom.xml", "composer.json"]],
   ["has_env", [".env", ".env.example", ".env.sample"]],
+  // Линтер проекта — Biome: совет даётся на его языке, а не на языке eslint.
+  ["has_biome", ["biome.json", "biome.jsonc"]],
   // Обвес самого агента: настройки, хуки, права. Отдельный признак нужен, потому что записи
   // про него не касаются проектов, где агента не настраивали вовсе, — а таких большинство.
   // Файл `.claude/settings.json` есть и у того, кто настроил один только список разрешений;
@@ -100,7 +113,7 @@ async function detectFacts(man) {
         if (/\.(test|spec)\.[a-z]+$/i.test(it.name) || /^test_.*\.py$/i.test(it.name) || /_test\.go$/i.test(it.name)) hasTests = true;
         if (it.name.endsWith(".sql")) hasDb = true;
         if (/\.(css|scss|sass|less|styl|vue|svelte|astro)$/i.test(it.name)) hasUi = true;
-        if (isApiSpec(it.name)) hasApiSpec = true;
+        if (isApiSpec(it.name) || (!hasApiSpec && it.name === "package.json" && (await isCodeContract(full)))) hasApiSpec = true;
         const dot = it.name.lastIndexOf(".");
         if (dot > 0) {
           const lang = EXT_LANG[it.name.slice(dot)];
@@ -310,6 +323,36 @@ function browserServerAdvice(facts, mcpText = "") {
   return { servers: ["chrome-devtools-mcp", "@playwright/mcp"] };
 }
 
+// Свод в AGENTS.md и 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, пишет их агенту, который их не читает.
+// Молчим, где Claude Code нет вовсе: Codex и Cursor читают AGENTS.md сами. Упоминание словами
+// («see AGENTS.md») — не подключение: файл в контекст не попадёт, агент дочитает или нет по
+// настроению. `@` в обратных кавычках документация прямо называет «не импорт».
+// Исходы: null — всё видно или нечего видеть; "missing" — CLAUDE.md нет; "noImport" — есть, но
+// AGENTS.md не подключает.
+function claudeSeesRules({ agents, claude, claudeLink, dotClaude }) {
+  if (!agents || claudeLink) return null;
+  if (claude === null) return dotClaude ? "missing" : null;
+  const prose = String(claude).replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
+  return /(^|\s)@(\.{1,2}\/)*AGENTS\.md\b/.test(prose) ? null : "noImport";
+}
+
+// То же, прочитанное с диска: одно место на `doctor` и `prompt`. Оба места CLAUDE.md —
+// документация называет и ./CLAUDE.md, и ./.claude/CLAUDE.md; подключение в любом засчитывается.
+async function claudeShimFor(cwd = CWD) {
+  const readOr = async (rel) => { try { return await readFile(join(cwd, rel), "utf8"); } catch { return null; } };
+  let claudeLink = false;
+  try { claudeLink = lstatSync(join(cwd, "CLAUDE.md")).isSymbolicLink() && /AGENTS\.md$/i.test(realpathSync(join(cwd, "CLAUDE.md"))); } catch { /* файла нет */ }
+  return claudeSeesRules({
+    agents: await exists(join(cwd, "AGENTS.md")),
+    claude: [await readOr("CLAUDE.md"), await readOr(".claude/CLAUDE.md")].filter((t) => t !== null).join("\n") || null,
+    claudeLink,
+    dotClaude: await exists(join(cwd, ".claude")),
+  });
+}
+
 function recipeFor(rec, facts) {
   const cmd = pickRecipe(rec, facts);
   if (!cmd) return L.recipe.none;
@@ -378,40 +421,9 @@ async function matchCatalog(query) {
   return out;
 }
 
-// С ЧЕГО НАЧАТЬ: три записи вместо двадцати равнозначных крестов.
-//
-// Двадцать одинаковых требований — это ноль требований: закрывают первое попавшееся или не
-// закрывают ничего. Порядок НЕ по нашему вкусу; два признака, оба — факты, которые у нас уже
-// есть:
-//   · запись родилась из настоящего отказа (`lifecycle: stable` — `proof` ссылается на журнал
-//     шишек), то есть она про боль, которая СЛУЧАЛАСЬ, а не про «хорошую практику»;
-//   · её можно закрыть одной готовой командой — цена входа минутная.
-// Сначала то, что и больно, и дёшево.
-//
-// При равенстве признаков — по имени: одинаковый ввод обязан давать одинаковый ответ, иначе
-// человек видит разный совет на двух прогонах подряд и перестаёт верить обоим.
-function startWith(entries, facts, n = 3) {
-  const langs = facts?.langs ? [...facts.langs] : [];
-  const cheap = (e) => {
-    const r = e?.recipes && typeof e.recipes === "object" ? e.recipes : {};
-    return [...langs, "native"].some((k) => r[k] && !/\{gate\}/.test(r[k])) ? 1 : 0;
-  };
-  // Зрелость НЕ поле записи, а вычисляемый признак: `proof` ссылается на журнал шишек. Тот же
-  // признак, которым каталог отделяет условную запись с первого дня (`entryLifecycle`).
-  // Заводить второй счёт нельзя: разъехавшись, они дали бы разные ответы про одну запись.
-  const hurt = (e) => (/incidents\//.test(String(e?.proof || "")) ? 1 : 0);
-  return [...entries]
-    .sort((a, b) =>
-      (hurt(b) + cheap(b)) - (hurt(a) + cheap(a)) ||
-      cheap(b) - cheap(a) ||
-      String(a.slug).localeCompare(String(b.slug)))
-    .slice(0, n);
-}
-
 // Наружу — то, что действительно импортируют другие файлы и модульные проверки. Экспорт,
 // который никто не берёт, читается как часть договора и мешает менять внутренности.
 export {
   whichSync,
   EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor, browserServerAdvice, MARKS,
-  startWith,
-  stems, overlap, matchCatalog, isApiSpec };
+  stems, overlap, matchCatalog, isApiSpec, claudeSeesRules, claudeShimFor };