agent-quality-kit 0.13.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/cadence.mjs

@@ -99,4 +99,33 @@ function autoProbeAllowed({ brief = false, env = process.env } = {}) {
   return !(env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI || env.BUILDKITE || env.JENKINS_URL);
 }
 
-export { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed };
+// Сколько классов проба поймала и у скольких поимка не доказана. Старая отметка чисел не несёт —
+// 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 },

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,15 @@
 // файл был полон, и любая следующая правка ложилась туда просто потому, что «так ближе по
 // контексту». Ровно то, о чём предупреждает совет самого гейта.
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+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 { advisorySet } from "./manifest.mjs";
 import { L } from "../i18n/index.mjs";
 import { gateCommand } from "./execution.mjs";
+import { annotations } from "./annotate.mjs";
 
 
 // «Гейт объявлен» и «гейт работает» — разные утверждения. Первое читается из манифеста,
@@ -147,6 +150,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;
@@ -178,12 +182,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,13 +260,23 @@ 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 };
 }
 

package/tool/program.mjs

@@ -28,6 +28,7 @@ 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";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
@@ -120,6 +121,9 @@ if (IS_MAIN) {
     case "context":
       await cmdContext(rest);
       break;
+    case "prompt":
+      await cmdPrompt();
+      break;
     case "badge":
       await cmdBadge(rest);
       break;

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")}`);
+  });
+}

package/tool/selfcheck/smoke/first-run.test.mjs

@@ -103,3 +103,42 @@ test("нет .aqk/docs и .aqk/rules — прогон всё равно зелё
   assert.equal(r.code, 0, `прогон покраснел из-за методичек:\n${tail}`);
   assert.match(plain(r.out), /\.aqk\/docs/, "отсутствие методичек не названо вовсе");
 });
+
+// Отзыв с живого проекта 2026-09-11: «AQK-3, All levels reached» при конвейере, который ни разу
+// не запускался. Под уровнем — чего он не доказывает, и что про это знает проба. Здесь пробы
+// не было: строка обязана это сказать, а не промолчать — тишину глаз читает как «всё хорошо».
+test("под уровнем стоит, чего он не доказывает", (t) => {
+  const p = project(t, {
+    ".aqk.yml": 'aqk: 1\nentry: [AGENTS.md]\nrules: rules\ngates:\n  lint: "true"\n',
+    "AGENTS.md": "# rules\n",
+    "rules/a.md": "# a\n",
+  });
+  const r = aqk(p, "doctor");
+  assert.match(r.out, /AQK-1/, r.out);
+  assert.match(r.out, /(оснащённость, а не надёжность|tooling, not reliability)/, `нет оговорки под уровнем:\n${r.out}`);
+  assert.match(r.out, /(проба не запускалась|probe has never run)/, `про пробу — тишина:\n${r.out}`);
+  assert.match(r.out, /(конвейер: прошёл ли он|pipeline: whether it passed)/, r.out);
+});
+
+// Claude Code читает CLAUDE.md, а не AGENTS.md (документация, сверено 2026-09-11). Проект с
+// .claude/ и сводом только в AGENTS.md пишет правила агенту, который их не читает.
+test("doctor называет свод, которого не видит Claude Code, и молчит, когда он подключён", (t) => {
+  const p = project(t, { ".claude/settings.json": "{}\n", "AGENTS.md": "# Rules\n\n- run tests\n" });
+  assert.match(plain(aqk(p, "doctor").out), /(Claude Code здесь настроен|Claude Code is set up here)/);
+  writeFileSync(join(p.dir, "CLAUDE.md"), "@AGENTS.md\n", "utf8");
+  assert.doesNotMatch(plain(aqk(p, "doctor").out), /(Claude Code здесь настроен|не подключает AGENTS|Claude Code is set up|does not import AGENTS)/);
+});
+
+// `aqk prompt` на свежем проекте: прогона не было — задание так и говорит и первым пунктом
+// велит прогнать, а не выдаёт пустой список за «всё чисто». Ничего не пишет на диск.
+test("prompt: задание без прогона начинается с прогона и кончается проверкой", (t) => {
+  const p = project(t, FILES);
+  aqk(p, "init");
+  const r = aqk(p, "prompt");
+  assert.equal(r.code, 0, r.out);
+  const items = r.out.split("\n").filter((l) => /^\d+\. /.test(l));
+  assert.match(items[0] || "", /(Прогона ещё не было|no run yet)/, `первый пункт не про прогон:\n${r.out}`);
+  assert.ok(items.length <= 5, "больше пяти пунктов за раз");
+  assert.match(r.out, /(Как проверить, что готово|How to verify)/);
+  assert.doesNotMatch(r.out, /\x1b\[/, "задание уходит агенту текстом — без цветовых кодов");
+});

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

@@ -8,7 +8,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { project, aqk } from "./_fixture.mjs";
+import { project, aqk, aqkEnv } from "./_fixture.mjs";
 
 test("прогон называет свой вердикт словами в обоих исходах", (t) => {
   const p = project(t, { "src/a.py": "def s():\n    return 1\n" });
@@ -71,7 +71,8 @@ test("--jobs 3: три секундных гейта идут одновреме
   writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m,
     'gates:\n  a: "sleep 1"\n  b: "sleep 1; exit 1"\n  c: "sleep 1"'), "utf8");
   const t0 = Date.now();
-  const r = aqk(p, "doctor", "--run", "--jobs", "3");
+  // --verbose: зелёные a и c без него свёрнуты в одну строку, а проверяется порядок всех трёх.
+  const r = aqk(p, "doctor", "--run", "--jobs", "3", "--verbose");
   const secs = (Date.now() - t0) / 1000;
   assert.notEqual(r.code, 0, "упавший гейт b не уронил прогон");
   const order = [...r.out.matchAll(/^\s+\S+\s+([abc])\s/gm)].map((m) => m[1]);
@@ -87,3 +88,41 @@ test("--jobs без числа или с нулём — отказ с причи
   assert.notEqual(r.code, 0);
   assert.match(r.out, /--jobs/);
 });
+
+// Коротко по умолчанию. Отзыв с живого проекта 2026-09-11: сто строк вывода, семьдесят из них —
+// зелёные галочки, и красное теряется между ними. Свёрнуто только то, что ничего не требует;
+// упавший и совещательный видны всегда, поимённо — по --verbose.
+test("зелёные гейты свёрнуты в строку, упавший и совещательный видны; --verbose — все", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n", ".gitignore": "x\n" });
+  aqk(p, "init");
+  const man = join(p.dir, ".aqk.yml");
+  writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m,
+    'gates:\n  green1: "true"\n  green2: "true"\n  broken: "false"\n  advice: "true"') + "advisory: [advice]\n", "utf8");
+  const short = aqk(p, "doctor", "--run").out;
+  assert.doesNotMatch(short, /^\s+\S+\s+green1\s/m, `зелёный гейт не свёрнут:\n${short}`);
+  assert.match(short, /^\s+\S+\s+broken\s/m, "упавший гейт спрятан");
+  assert.match(short, /^\s+\S+\s+advice\s/m, "совещательный обязан быть назван каждый прогон");
+  assert.match(short, /(прошли ещё 2|2 more passed)/, `нет строки со счётом свёрнутых:\n${short}`);
+  const full = aqk(p, "doctor", "--run", "--verbose").out;
+  assert.match(full, /^\s+\S+\s+green1\s/m, "--verbose не показал зелёный гейт");
+  assert.doesNotMatch(full, /(прошли ещё|more passed)/);
+});
+
+// Находки — пометками у строк файла в pull request, но только в GitHub Actions: в терминале
+// строка `::error …` — мусор. Вердикт от пометок не меняется.
+test("в GitHub Actions упавший гейт даёт пометку у строки файла; вне его — нет", (t) => {
+  // Гейт — файлом через bash: строку «echo …; exit 1» Node на Windows отдаёт cmd.exe, где точка с
+  // запятой не разделяет команды, — код 0, и проверка падала на оснастке (поймано конвейером).
+  const p = project(t, {
+    "src/a.py": "x = 1\n", ".gitignore": "x\n",
+    "bad.sh": "echo 'src/a.py:1: x — плохо'\necho '  почини: убери x'\nexit 1\n",
+  });
+  aqk(p, "init");
+  const man = join(p.dir, ".aqk.yml");
+  writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m, 'gates:\n  bad: "bash bad.sh"'), "utf8");
+  const gh = aqkEnv(p, { GITHUB_ACTIONS: "true" }, "doctor", "--run");
+  assert.notEqual(gh.code, 0, "пометки не должны менять вердикт");
+  assert.match(gh.out, /^::error file=src\/a\.py,line=1,title=aqk%3A bad::x — плохо — почини: убери x$/m, gh.out);
+  const local = aqkEnv(p, { GITHUB_ACTIONS: "" }, "doctor", "--run");
+  assert.doesNotMatch(local.out, /^::error/m, "вне GitHub Actions пометок нет");
+});