agent-quality-kit 0.13.0 → 0.15.0

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"]);
 
 // Факты о репозитории. Только то, что видно машине: спрашивать человека анкетой
@@ -102,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)];
@@ -312,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;
@@ -385,4 +426,4 @@ async function matchCatalog(query) {
 export {
   whichSync,
   EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor, browserServerAdvice, MARKS,
-  stems, overlap, matchCatalog, isApiSpec };
+  stems, overlap, matchCatalog, isApiSpec, claudeSeesRules, claudeShimFor };

package/tool/lib/run.mjs

@@ -9,12 +9,16 @@
 // файл был полон, и любая следующая правка ложилась туда просто потому, что «так ближе по
 // контексту». Ровно то, о чём предупреждает совет самого гейта.
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
 import { Worker } from "node:worker_threads";
 import { scopeOutput, splitAdvice, changedFiles } from "./scope.mjs";
-import { CWD, c, die } from "./core.mjs";
+import { CWD, TARGET_DIR, c, die, exists } from "./core.mjs";
 import { advisorySet } from "./manifest.mjs";
 import { L } from "../i18n/index.mjs";
-import { gateCommand } from "./execution.mjs";
+import { gateCommand, classify, findingCodes } from "./execution.mjs";
+import { annotations } from "./annotate.mjs";
 
 
 // «Гейт объявлен» и «гейт работает» — разные утверждения. Первое читается из манифеста,
@@ -147,6 +151,7 @@ async function runGates(man, opts = {}) {
   if (sel.skipped.length) console.log(c.yellow(`  ${L.doctor.selectSkipped(sel.skipped.join(", "))}\n`));
   let failed = 0;
   const results = [];
+  const quietOk = [];
 
   const jobs = Math.max(1, Number(opts.jobs) || 1);
   const pooled = jobs > 1 ? startPool(gates.map(([, cmd]) => cmd), jobs) : null;
@@ -164,10 +169,46 @@ async function runGates(man, opts = {}) {
     // Без этого «готово = доказано» остаётся правилом, за которым следит только человек.
     const outAll = `${r.stdout || ""}${r.stderr || ""}`.slice(0, 200000);
 
-    if (r.error && r.error.code === "ETIMEDOUT") {
-      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.timeout)}`);
-      failed++;
-      results.push({ name, cmd, ok: false, secs, note: L.doctor.timeout, out: outAll });
+    // ИСХОД ЗАПУСКА — ДО РАЗБОРА ВЫВОДА И ДО СУЖЕНИЯ. Состояний три, а не два: clean · finding
+    // · infra_error. Знание о кодах живёт рядом с инструментом (`execution.mjs`): у vulture
+    // находка это 3, у pylint — битовая маска, а у незнакомой программы находка только 1.
+    //
+    // ЗАЧЕМ ЗДЕСЬ. Прежде прогон ловил один лишь ETIMEDOUT, а любой другой ненулевой код шёл в
+    // разбор находок — и `--since` фильтровал его ПО ПУТЯМ. Гейт, который НЕ СМОГ отработать,
+    // называл путь вне дифа и печатался зелёным: проверка сломалась, прогон сказал «чисто».
+    // Найдено внешним разбором 2026-09-13 (аудит Runcap), воспроизведено проверкой
+    // `fail-closed`. Сужать дифом можно только НАХОДКУ: у сбоя нет места в коде, которое он
+    // называет, — есть только сам сбой.
+    const verdict = classify(r, findingCodes(String(cmd).trim().split(/\s+/)[0]));
+    if (verdict.state === "infra_error") {
+      const why =
+        verdict.reason === "timeout" ? L.doctor.timeout
+        : verdict.reason === "spawn_error" ? L.doctor.whySpawn(r.error?.code || "")
+        : verdict.reason === "signal" ? L.doctor.whySignal(r.signal)
+        : L.doctor.whyExit(verdict.code);
+      // Совещательный не роняет прогон НИКОГДА — в том числе своим сбоем: список `advisory:`
+      // означает «эта проверка не имеет права останавливать работу», и причина остановки тут
+      // ни при чём. Но НАЗВАН он обязан быть: «не смогли» и «чисто» неразличимы только там,
+      // где о них молчат. Раньше таймаут ронял прогон и у совещательного — тот же класс, что
+      // измеренный 2026-09-09 случай с гейтом без путей в выводе.
+      const adv = advisory.has(name);
+      const note = L.doctor.cannotCheck(why);
+      const paint = adv ? c.yellow : c.red;
+      console.log(`  ${adv ? c.yellow("!") : c.red("✘")}  ${name.padEnd(14)} ${paint(note)} ${c.dim(`· ${secs}s · ${cmd}`)}`);
+      // Вывод сбоя показывается тоже. «Не смогли проверить: код 127» без строки
+      // «command not found: ruff» не говорит, ЧТО чинить, — а чинить тут надо инструмент,
+      // и первые строки обычно и есть его жалоба.
+      for (const line of outAll.trim().split("\n").filter(Boolean).slice(0, 3)) {
+        console.log(c.dim(`        ${line.slice(0, 100)}`));
+      }
+      if (!adv) failed++;
+      // В pull request это ОБЩАЯ пометка гейта, а не пометка у строки файла: `shown` — то, что
+      // прогон показал, и у сбоя это причина, а не путь. Иначе «не смогли проверить» повисло бы
+      // на первом файле, который гейт успел назвать перед падением, — то есть на невиновном.
+      // Сырой `out` не трогаем: по нему считается покрытие дифа.
+      // `cannot` — не украшение: по нему отчёт прогона отличает сбой от находки одним знаком,
+      // а блок для агента и просьба об отзыве читают это из файла, ничего не запуская.
+      results.push({ name, cmd, ok: false, cannot: true, secs, code: verdict.code, advisory: adv, note, out: outAll, shown: note });
       continue;
     }
     const code = r.status;
@@ -178,12 +219,16 @@ async function runGates(man, opts = {}) {
       // совещательный печатался обычной галочкой, а README обещал, что список назван каждый
       // прогон. Тот же класс, что молчащий гейт, только про сам прибор.
       const quiet = advisory.has(name) ? ` ${c.yellow(L.doctor.advisoryQuiet)}` : "";
-      console.log(`  ${c.green("✔")}  ${name.padEnd(14)}${quiet} ${c.dim(`${secs}s · ${cmd}`)}`);
       // Зелёный гейт иногда всё-таки говорит человеку что-то важное: храповик, дошедший до цели,
       // просит убрать обёртку. Вывод успешного гейта не показывался вовсе, и это сообщение
       // уходило в никуда — тот же класс, что обрезанный совет у красного, только тише.
       // Показываем ровно строки с меткой совета: остальной вывод успешной проверки — шум.
       const okAdvice = splitAdvice(`${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean)).advice;
+      // Без `--verbose` зелёный гейт своей строки не получает — если ему нечего сказать. Совещательный
+      // и гейт с советом печатаются всегда: первый обязан быть назван каждый прогон (см. выше),
+      // второй несёт строку, ради которой человек и смотрит.
+      if (opts.verbose || quiet || okAdvice.length) console.log(`  ${c.green("✔")}  ${name.padEnd(14)}${quiet} ${c.dim(`${secs}s · ${cmd}`)}`);
+      else quietOk.push(name);
       for (const line of okAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
       results.push({ name, cmd, ok: true, secs, advisory: advisory.has(name), out: outAll });
     } else {
@@ -252,14 +297,100 @@ async function runGates(man, opts = {}) {
       }
       // Совет тоже не бесконечен: гейт, зовущий помощник шесть раз, печатает его шесть раз.
       for (const line of alwaysAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
-      results.push({ name, cmd, ok: false, secs, code, advisory: isAdvisory, out: outAll });
+      // `shown` — то, что прогон ПОКАЗАЛ: после сужения по дифу и с советом. Пометки в pull request
+      // берутся отсюда, а не из сырого вывода: иначе при --since они вешались бы на файлы вне
+      // дифа — поймано конвейером на первом же прогоне (smoke: «--since сузил не то»).
+      results.push({ name, cmd, ok: false, secs, code, advisory: isAdvisory, out: outAll, shown: [...out, ...alwaysAdvice].join("\n") });
     }
   }
   // Совещательные, которые покраснели, называются вслух ВСЕГДА. Молчание о них — ровно та
   // тишина, против которой построен стандарт: проверка выключена, а выглядит как её отсутствие.
+  if (quietOk.length) console.log(`  ${c.green("✔")}  ${L.doctor.passedQuiet(quietOk.length)}`);
   const advisoryFailed = results.filter((x) => x.advisory && !x.ok).map((x) => x.name);
   if (advisoryFailed.length) console.log(`\n  ${c.yellow(L.doctor.advisorySummary(advisoryFailed))}`);
+  // В GitHub Actions — те же находки пометками у строк файла в pull request. Вердикт не меняется.
+  if (process.env.GITHUB_ACTIONS === "true") {
+    const ann = annotations(results, { exists: (f) => existsSync(join(CWD, f)) });
+    for (const line of ann.lines) console.log(line);
+    if (ann.dropped) console.log(c.dim(`  ${L.doctor.annotDropped(ann.lines.length, ann.dropped)}`));
+  }
   return { failed, ran: gates.length, results, advisoryFailed, skipped: sel.skipped };
 }
 
-export { declaredGates, sinceRef, runGates, progress, selectGates, listArg };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ОТЧЁТ ПРОГОНА: пишется здесь же, где прогон, и читается здесь же. Раньше `doctor` его ПИСАЛ,
+// а `context` РАЗБИРАЛ — два файла, которые друг о друге не знают, держали один формат. Третий
+// знак («?» — не смогли проверить) пришлось заводить в обоих, и это ровно тот случай, когда
+// одно знание живёт в двух местах: правишь одно, второе молча расходится.
+//
+// Читателей у отчёта трое — блок для агента, задание и просьба об отзыве, — и ни один не
+// запускает гейты заново: хук обязан укладываться в секунду, а прогон идёт минуту.
+// Короткий отчёт «что из этого реально брали» — не для человека, а для агента в следующей
+// сессии и для самого владельца: список объявленных гейтов молчит о том, сколько из них
+// действительно стоят и работают именно СЕЙЧАС. Перезаписывается каждым прогоном, не копится:
+// история — дело git-лога коммитов с этим отчётом, если владелец решит его коммитить.
+async function writeRunReport({ version, reached, results, skipped = [] }) {
+  const stamp = new Date().toISOString().replace("T", " ").slice(0, 16);
+  const ok = results.filter((r) => r.ok).length;
+  const lines = [
+    `# ${L.report.title} — ${stamp}`,
+    version ? `${L.report.version}: ${version}` : null,
+    `${L.report.level}: AQK-${reached < 0 ? L.doctor.levelNone : reached}`,
+    "",
+    // ТРИ ЗНАКА, А НЕ ДВА: ✔ прошло · ✘ находка · ? НЕ СМОГЛИ ПРОВЕРИТЬ. Отчёт читает не только
+    // человек: из него блок для агента и просьба об отзыве узнают, что случилось, ничего не
+    // запуская. Слив «не смогли» с находкой означал бы, что агент чинит код там, где сломан
+    // инструмент, — и никогда не узнает, что инструмент сломан.
+    ...results.map((r) => `${r.ok ? "✔" : r.cannot ? "?" : "✘"} ${r.name} — ${r.secs}s${r.ok ? "" : ` (${r.note || L.doctor.exitCode(r.code)})`}`),
+    // Пропущенные по --skip/--only — строкой «~»: блок для агента читает их как «не запускались»,
+    // а не как зелёные. Молчание о них прочиталось бы как «проверено».
+    ...skipped.map((n) => `~ ${n} — ${L.report.skippedBySelect}`),
+    "",
+    L.report.summary(ok, results.length),
+  ].filter((l) => l !== null);
+
+  const dst = join(CWD, TARGET_DIR, "last-run.md");
+  await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+  await writeFile(dst, lines.join("\n") + "\n", "utf8");
+}
+
+// Разбор отчёта прошлого прогона. Формат кладёт сам `doctor` в .aqk/last-run.md; читаем его,
+// а не запускаем гейты заново: хук обязан укладываться в секунду-две, а прогон у нас идёт минуту.
+function parseLastRun(text) {
+  if (!text) return null;
+  const when = (text.match(/^# aqk doctor --run — (.+)$/m) || [])[1] || "";
+  const red = [];
+  for (const m of text.matchAll(/^✘ ([^\s—]+)/gm)) red.push(m[1]);
+  // «Не смогли проверить» — свой знак и свой список. Гейт, который не сумел отработать, не
+  // находка о коде: агент, прочитавший его как находку, пойдёт чинить исправный файл, а
+  // сломанный инструмент останется сломанным. Слить их в один список было бы той же тишиной,
+  // только наоборот.
+  const cannot = [];
+  for (const m of text.matchAll(/^\? ([^\s—]+)/gm)) cannot.push(m[1]);
+  const skipped = (text.match(/^~ /gm) || []).length;
+  return { when: when.trim(), red, cannot, skipped, stale: false };
+}
+
+// Прогон старше последнего коммита описывает не тот код, что лежит перед агентом. Молча выдать
+// его за свежий — соврать: именно так «зелёный месяц назад» превращается в «зелёный сейчас».
+function runIsStale(when) {
+  if (!when) return false;
+  const r = spawnSync("git", ["log", "-1", "--format=%cI"], { cwd: CWD, encoding: "utf8" });
+  if (r.status !== 0 || !r.stdout) return false;
+  const commit = Date.parse(r.stdout.trim());
+  const run = Date.parse(when.replace(" ", "T"));
+  return Number.isFinite(commit) && Number.isFinite(run) && run < commit;
+}
+
+// Прошлый прогон — из отчёта, который кладёт `doctor --run`. Отдельной функцией: его читают и
+// `context`, и `prompt`, и два разбора одного файла разошлись бы.
+async function readRun() {
+  const lastRun = join(CWD, TARGET_DIR, "last-run.md");
+  if (!(await exists(lastRun))) return null;
+  const run = parseLastRun(await readFile(lastRun, "utf8"));
+  if (run) run.stale = runIsStale(run.when);
+  return run;
+}
+
+export { declaredGates, sinceRef, runGates, progress, selectGates, listArg, writeRunReport, parseLastRun, readRun };

package/tool/program.mjs

@@ -28,7 +28,9 @@ import { cmdBadge } from "./commands/badge.mjs";
 import { cmdProve } from "./commands/prove.mjs";
 import { cmdProbe } from "./commands/probe.mjs";
 import { cmdContext } from "./commands/context.mjs";
+import { cmdPrompt } from "./commands/prompt.mjs";
 import { cmdVitals } from "./commands/vitals.mjs";
+import { cmdFeedback } from "./commands/feedback.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -120,9 +122,17 @@ if (IS_MAIN) {
     case "context":
       await cmdContext(rest);
       break;
+    case "prompt":
+      await cmdPrompt();
+      break;
     case "badge":
       await cmdBadge(rest);
       break;
+    // Собирает отчёт о работе комплекта и даёт готовую ссылку. Ничего не отправляет: исходящий
+    // запрос у комплекта ровно один — про свежесть версии.
+    case "feedback":
+      await cmdFeedback();
+      break;
     default: {
       // Ширина колонки считается, а не подбирается пробелами: строки в двух языках разной
       // длины, и вручную выровненная справка на втором языке разъезжается.

package/tool/selfcheck/smoke/_fixture.mjs

@@ -55,6 +55,9 @@ function env(home, dir) {
     // Сеть в тестах — отдельный класс флейков, и у нас она включалась ТОЛЬКО вне конвейера:
     // локально проверки были сетевыми, в конвейере нет. Две разные среды по построению.
     AQK_UPDATE: "0",
+    // Вывод — как у пользователя, короткий. `smoke.sh` включает AQK_VERBOSE=1 для СВОИХ
+    // проверок, написанных до свёртки, и без сброса здесь проверки свёртки его унаследовали бы.
+    AQK_VERBOSE: "",
   };
 }
 
@@ -82,14 +85,16 @@ function project(t, files = {}, { git = true } = {}) {
 // Запуск чего угодно в каталоге проекта. Возвращается И код, И вывод: проверка, смотрящая
 // только на код, не умеет объяснить провал, а смотрящая только на вывод — не умеет заметить,
 // что команда не роняет прогон.
-function run({ dir, home }, cmd, args = []) {
+// `extra` — переменные поверх песочницы, когда проверка про само окружение (GITHUB_ACTIONS).
+function run({ dir, home }, cmd, args = [], extra = {}) {
   const r = spawnSync(cmd, args, {
-    cwd: dir, encoding: "utf8", timeout: TIMEOUT_MS, env: env(home, dir),
+    cwd: dir, encoding: "utf8", timeout: TIMEOUT_MS, env: { ...env(home, dir), ...extra },
   });
   return { code: r.status, out: `${r.stdout || ""}${r.stderr || ""}` };
 }
 
 const aqk = (p, ...args) => run(p, process.execPath, [CLI, ...args]);
+const aqkEnv = (p, extra, ...args) => run(p, process.execPath, [CLI, ...args], extra);
 
 // ПОЧЕМУ ГЕЙТ ЗОВЁТСЯ ТОЧКОЙ, А НЕ ПУТЁМ, И ПОЧЕМУ ПУТЬ ЧЕРЕЗ КОСУЮ.
 // Node на Windows отдаёт `C:\Users\…\Temp\aqk-smoke-x`, а Git Bash живёт в POSIX-мире и
@@ -108,4 +113,4 @@ const gate = (p, name, sub = ".") =>
 // никто не берёт, читается как часть договора и мешает менять внутренности — поймал наш же
 // dead-code через минуту после того, как файл был написан. `run` вернулся, когда появилась
 // проверка, которой нужен сырой git: экспорт заводится под потребителя, а не про запас.
-export { project, run, aqk, gate };
+export { project, run, aqk, aqkEnv, gate };

package/tool/selfcheck/smoke/api-contract.test.mjs

@@ -77,3 +77,40 @@ test("держателем не считается определение сос
   // Второй дефект того же прогона: `find` без завершающего -print печатал обойдённые каталоги.
   assert.doesNotMatch(r.out, /\.git|\.aqk/, `в списке спецификаций каталоги:\n${r.out}`);
 });
+
+// ДОГОВОР В КОДЕ. Отзыв с живого проекта 2026-09-11: схемы zod запросов и ответов в общем
+// пакете, сервер на `@fastify/type-provider-zod` — а кит писал «спецификации API не видно»,
+// потому что узнавал договор только по имени файла `openapi*`. У такого договора арбитр —
+// проверка типов: разошлись сервер и клиент — `tsc` краснеет. Не запускает её никто — договор
+// не держит никто, ровно как файл OpenAPI без schemathesis.
+test("договор в коде без проверки типов — находка, с tsc — чисто, zod один — не договор", (t) => {
+  const provider = { "backend/package.json": '{ "dependencies": { "@fastify/type-provider-zod": "1.0.0", "zod": "4.5.4" } }\n' };
+  const bare = gate(project(t, provider), "api-contract-has-arbiter");
+  assert.equal(bare.code, 1, `договор без арбитра прошёл зелёным:\n${bare.out}`);
+  assert.match(bare.out, /backend\/package\.json/, `находка не называет, где договор:\n${bare.out}`);
+
+  const held = gate(project(t, {
+    ...provider,
+    "package.json": '{ "scripts": { "typecheck": "tsc --build" } }\n',
+  }), "api-contract-has-arbiter");
+  assert.equal(held.code, 0, `tsc в scripts не признан арбитром:\n${held.out}`);
+
+  for (const dep of ["@trpc/server", "@ts-rest/core", "@hono/zod-openapi", "fastify-type-provider-zod"]) {
+    const r = gate(project(t, { "package.json": `{ "dependencies": { "${dep}": "1.0.0" } }\n` }), "api-contract-has-arbiter");
+    assert.equal(r.code, 1, `${dep} не опознан как договор:\n${r.out}`);
+  }
+
+  // zod сам по себе — разбор входа, а не договор с чужим кодом: так его зовут и формы, и конфиги.
+  const zod = gate(project(t, { "package.json": '{ "dependencies": { "zod": "4.5.4" } }\n' }), "api-contract-has-arbiter");
+  assert.equal(zod.code, 0, `один zod объявлен договором:\n${zod.out}`);
+});
+
+test("doctor видит договор в коде: запись применима, а не «спецификации не видно»", (t) => {
+  const p = project(t, { "package.json": '{ "dependencies": { "@trpc/server": "11.18.0" } }\n' });
+  aqk(p, "init");
+  // --verbose: без него неприменимые свёрнуты в счёт, причин в выводе нет вовсе — и проверка
+  // прошла бы вхолостую при любом опознании.
+  const r = aqk(p, "doctor", "--verbose");
+  assert.match(r.out, /api-contract-has-arbiter/, `запись не названа вовсе:\n${r.out}`);
+  assert.doesNotMatch(r.out, /не видно (спецификации|договора) API|no API (specification|contract) in sight/, `договор в коде не опознан:\n${r.out}`);
+});

package/tool/selfcheck/smoke/corpus.test.mjs

@@ -0,0 +1,151 @@
+// Набор настоящих случаев: то, что мы нашли на живых проектах, в журнале и в разборах соседей,
+// — минимальными воспроизведениями с ожидаемым ответом комплекта.
+//
+// ЗАЧЕМ. Образцы red/green проверяют запись В ОДИНОЧКУ, на примере, написанном под неё. Ломается
+// же комплект на целых проектах, где записи стоят рядом: «определение соседней записи —
+// находка» (журнал, 2026-09-09) образцы не поймали ни разу. Разбор AgentLint 2026-09-11 показал
+// другую половину: их «точность 99%» мерила согласие сканера с собственным пересказом правил.
+// Здесь разметка — по СВОЙСТВУ проекта: у каждого случая назван источник, где это свойство
+// видели на деле. Файлы случаев живут внутри проверки, а не в дереве: иначе наши же гейты
+// находили бы в них «находки» у нас в репозитории.
+//
+// Каждый случай — минимальное воспроизведение, а не копия: чужой код переносить нельзя по
+// лицензии, и копия в тысячи строк проверяла бы то же самое, только медленнее.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { project, aqk, aqkEnv, gate } from "./_fixture.mjs";
+
+const KIT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "kit", "gates");
+
+const TWIN = (fake) => ({
+  "CLAUDE.md": "# Shop API\n\nSmall HTTP API.\n\n## Commands\n- Test: `npm test`\n",
+  "package.json": JSON.stringify({ name: "shop", type: "module", scripts: { test: fake ? "node --test || true" : "node --test" } }),
+  "src/cart.js": "export function total(items) {\n  return items.reduce((s, i) => s + i.price, 0);\n}\n",
+  "test/cart.test.js": fake
+    ? "import test from 'node:test';\nimport { total } from '../src/cart.js';\ntest('total', () => { total([{ price: 2 }]); });\n"
+    : "import test from 'node:test';\nimport assert from 'node:assert';\nimport { total } from '../src/cart.js';\ntest('total', () => { assert.equal(total([{ price: 2 }]), 2); });\n",
+  ".github/workflows/ci.yml": "name: ci\non: [push]\npermissions:\n  contents: read\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n" +
+    "      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262\n      - run: npm test\n" +
+    (fake ? "        continue-on-error: true\n" : ""),
+});
+
+const CASES = [
+  {
+    name: "близнец с настоящими воротами",
+    source: "research/competitors/agentlint-0xmariowu.md, «Близнецы»: AgentLint дал 71 обоим",
+    files: TWIN(false),
+    gates: { "ci-actually-fails": 0, "test-has-assertion": 0 },
+  },
+  {
+    name: "близнец с поддельными воротами",
+    source: "там же; test-has-assertion молчит намеренно — «вызов без утверждения» у нас не находка (.aqk.yml)",
+    files: TWIN(true),
+    gates: { "ci-actually-fails": 1, "test-has-assertion": 0 },
+  },
+  {
+    name: "ворота в check.yml под continue-on-error, «exit 1» в комментарии",
+    source: "agentlint-0xmariowu.md, H7: их проверка назвала такие ворота блокирующими",
+    files: {
+      ".github/workflows/check.yml": "name: check\non: [push]\npermissions:\n  contents: read\njobs:\n  t:\n    runs-on: ubuntu-latest\n    steps:\n" +
+        "      - run: npm test\n        continue-on-error: true\n# on failure the step does exit 1\n",
+      "package.json": JSON.stringify({ name: "x", scripts: { test: "node --test" } }),
+    },
+    gates: { "ci-actually-fails": 1 },
+  },
+  {
+    name: "свод велит удалённый скрипт, а debug остался в зависимостях",
+    source: "incidents/README.md 2026-09-11; JonnyKreng/pebble-navi 757c563",
+    files: {
+      "AGENTS.md": "# Rules\n\n```sh\nnpm run debug        # build + install + logs\n```\n",
+      "package.json": JSON.stringify({ name: "x", scripts: { build: "tsc" }, dependencies: { debug: "4.3.4" } }, null, 2),
+    },
+    gates: { "entry-commands-exist": 1 },
+  },
+  {
+    name: "цели make в коде свода, «make sure» в прозе",
+    source: "живой проект на TypeScript и Biome: шестнадцать целей make в AGENTS.md, все на месте",
+    files: {
+      "AGENTS.md": "# Rules\n\nMake sure the tree is clean.\n\n- проверка: `make check`\n- типы: `make typecheck`\n",
+      "Makefile": ".PHONY: check typecheck\ncheck:\n\tnpm run lint\ntypecheck:\n\tnpx tsc --noEmit\n",
+      "package.json": JSON.stringify({ name: "x", scripts: { lint: "biome lint ." } }),
+    },
+    gates: { "entry-commands-exist": 0 },
+  },
+  {
+    name: "договор в коде (провайдер типов Fastify) без проверки типов",
+    source: "отзыв с живого проекта 2026-09-11: «спецификации API не видно» при zod-схемах в общем пакете",
+    files: { "backend/package.json": JSON.stringify({ dependencies: { "@fastify/type-provider-zod": "1.0.0", zod: "4.5.4" } }) },
+    gates: { "api-contract-has-arbiter": 1 },
+  },
+  {
+    name: "тот же договор, tsc --build в scripts",
+    source: "там же: на живом проекте запись применима и зелёная",
+    files: {
+      "backend/package.json": JSON.stringify({ dependencies: { "@fastify/type-provider-zod": "1.0.0" } }),
+      "package.json": JSON.stringify({ scripts: { typecheck: "tsc --build" } }),
+    },
+    gates: { "api-contract-has-arbiter": 0 },
+  },
+  {
+    name: "CLAUDE.md с windows-переносами подключает AGENTS.md",
+    source: "живой проект на Windows; AgentLint (F7) объявил подключение битым",
+    files: {
+      "CLAUDE.md": "# CLAUDE.md\r\n\r\nПравила — в AGENTS.md.\r\n\r\n@AGENTS.md\r\n",
+      "AGENTS.md": "# Правила\n\n- тесты перед коммитом\n",
+      ".claude/settings.json": "{}\n",
+    },
+    doctorNot: /(не подключает AGENTS|does not import AGENTS|Claude Code здесь настроен|Claude Code is set up)/,
+  },
+  {
+    name: "русский свод, машина без LANG",
+    source: "отзыв с живого проекта 2026-09-11: Windows без LANG — весь вывод английский",
+    files: {
+      "AGENTS.md": "# Правила проекта\n\n" + "Перед коммитом запусти проверку и убедись, что она проходит. Изменение договора проходит через ревью и фиксируется в журнале решений. ".repeat(3) + "\n",
+    },
+    env: { AQK_LANG: "", LANG: "", LC_ALL: "", LC_MESSAGES: "" },
+    doctorHas: /Уровень/,
+  },
+  {
+    name: "определения записей, разложенные в проект, — не находки",
+    source: "incidents/README.md 2026-09-09 «аудит фич нашёл то, чего не нашли образцы»; AgentLint S6/S7 краснеют на таком же",
+    files: { "src/app.py": "def f():\n    return 1\n" },
+    before: [["init"], ["add", "secrets-not-in-code"], ["add", "personal-config-not-shared"], ["add", "env-secrets-not-committed"]],
+    gates: { "secrets-not-in-code": 0, "personal-config-not-shared": 0, "env-secrets-not-committed": 0 },
+  },
+];
+
+// Записи, которые работают на одном `sh` и дают один и тот же ответ на любой машине: без
+// `requires:` (нет чужого инструмента — ответ зависел бы от установленного) и без сети.
+const NETWORK = new Set(["no-phantom-package"]);
+const PORTABLE = readdirSync(KIT, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && existsSync(join(KIT, d.name, "gate.yml")))
+  .map((d) => d.name)
+  .filter((slug) => {
+    const yml = readFileSync(join(KIT, slug, "gate.yml"), "utf8");
+    return !NETWORK.has(slug) && /any:\s*bash \{gate\}\/check\.sh \{dir\}/.test(yml) && !/^requires:/m.test(yml);
+  });
+
+for (const c of CASES) {
+  test(`случай: ${c.name}`, (t) => {
+    const p = project(t, c.files);
+    for (const args of c.before || []) aqk(p, ...args);
+    for (const [slug, want] of Object.entries(c.gates || {})) {
+      const r = gate(p, slug);
+      assert.equal(r.code, want, `${slug}: ждали ${want}, получили ${r.code}. Источник: ${c.source}\n${r.out}`);
+    }
+    if (c.doctorNot || c.doctorHas) {
+      if (!c.before) aqk(p, "init");
+      const r = c.env ? aqkEnv(p, c.env, "doctor") : aqk(p, "doctor");
+      if (c.doctorNot) assert.doesNotMatch(r.out, c.doctorNot, `источник: ${c.source}\n${r.out}`);
+      if (c.doctorHas) assert.match(r.out, c.doctorHas, `источник: ${c.source}\n${r.out}`);
+    }
+    // Перекрёстная проверка: на обычном проекте ни одна переносимая запись не отвечает «не смогли
+    // проверить». Код 2 здесь — сбой записи на чужой раскладке, а не свойство проекта.
+    const broken = PORTABLE.map((slug) => [slug, gate(p, slug)]).filter(([, r]) => r.code !== 0 && r.code !== 1);
+    assert.deepEqual(broken.map(([s, r]) => `${s}: код ${r.code}`), [],
+      `записи не смогли проверить обычный проект:\n${broken.map(([s, r]) => `${s}:\n${r.out}`).join("\n")}`);
+  });
+}