agent-quality-kit 0.12.0 → 0.14.0

package/tool/lib/run.mjs

@@ -9,11 +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";
 
 
 // «Гейт объявлен» и «гейт работает» — разные утверждения. Первое читается из манифеста,
@@ -65,9 +69,73 @@ function progress({ tty = process.stdout.isTTY, write = (s) => process.stdout.wr
   };
 }
 
-function runGates(man, opts = {}) {
-  const gates = declaredGates(man);
-  if (!gates.length) return { failed: 0, ran: 0, results: [] };
+// ГРУППЫ И --only / --skip. Отзыв с живого проекта 2026-09-11: гейт цены меряет план на
+// засеянной базе — объявишь, и он валит прогон без стенда; уберёшь, и promise-has-gate справедливо
+// ругается. Прогон бывал только «всё или ничего». `groups:` в манифесте называет смысл
+// («этим нужен стенд»), флаги выбирают. Неизвестное имя — ошибка: опечатка `--skip stak` не
+// должна тихо превращаться в «пропустили ничего». Пропущенные называются, а не исчезают.
+function listArg(argv, flag) {
+  const out = [];
+  argv.forEach((a, i) => { if (a === flag && argv[i + 1] && !argv[i + 1].startsWith("--")) out.push(...argv[i + 1].split(",")); });
+  return out.map((x) => x.trim()).filter(Boolean);
+}
+
+function selectGates(gates, man, { only = [], skip = [] } = {}) {
+  const groups = man?.groups && typeof man.groups === "object" && !Array.isArray(man.groups) ? man.groups : {};
+  const declared = new Set(gates.map(([n]) => n));
+  const unknown = [];
+  const expand = (list) => {
+    const out = new Set();
+    for (const name of list) {
+      const g = groups[name];
+      const members = Array.isArray(g) ? g : typeof g === "string" && g ? [g] : null;
+      if (members) for (const m of members) (declared.has(m) ? out.add(m) : unknown.push(m));
+      else if (declared.has(name)) out.add(name);
+      else unknown.push(name);
+    }
+    return out;
+  };
+  const onlySet = only.length ? expand(only) : null;
+  const skipSet = expand(skip);
+  const run = gates.filter(([n]) => (!onlySet || onlySet.has(n)) && !skipSet.has(n));
+  const kept = new Set(run.map(([n]) => n));
+  return { run, skipped: gates.map(([n]) => n).filter((n) => !kept.has(n)), unknown: [...new Set(unknown)] };
+}
+
+const GATE_TIMEOUT = 300000;
+
+// Один гейт в этом потоке — прежний путь, без `--jobs`.
+function spawnGate(cmd) {
+  return spawnSync(gateCommand(cmd), { shell: true, cwd: CWD, encoding: "utf8", timeout: GATE_TIMEOUT });
+}
+
+// ПАРАЛЛЕЛЬНО — ПО ФЛАГУ. Отзыв с живого проекта 2026-09-11: 34 независимых гейта шли друг за
+// другом больше минуты. Но у чужих проектов гейты бывают зависимыми — два `npm run build` в одну
+// папку `dist/` при одновременном запуске дадут плавающие падения, а плавающее красное хуже
+// медленного. Поэтому без флага всё как было, по одному. Результаты — массив обещаний в порядке
+// объявления: вывод печатается по порядку, какой бы гейт ни кончился первым.
+function startPool(cmds, jobs) {
+  const url = new URL("./gate-worker.mjs", import.meta.url);
+  const results = cmds.map(() => { let res; const pr = new Promise((r) => { res = r; }); pr.res = res; return pr; });
+  let next = 0;
+  const feed = (w) => {
+    if (next >= cmds.length) { w.terminate(); return; }
+    const id = next++;
+    const onErr = (e) => { results[id].res({ status: null, stdout: "", stderr: String(e?.message || e), error: { code: "WORKER" } }); };
+    w.once("error", onErr);
+    w.once("message", (m) => { w.off("error", onErr); results[id].res(m); feed(w); });
+    w.postMessage({ id, cmd: cmds[id], cwd: CWD, timeout: GATE_TIMEOUT });
+  };
+  for (let i = 0; i < Math.min(jobs, cmds.length); i++) feed(new Worker(url));
+  return results;
+}
+
+async function runGates(man, opts = {}) {
+  const all = declaredGates(man);
+  if (!all.length) return { failed: 0, ran: 0, results: [], skipped: [] };
+  const sel = selectGates(all, man, opts);
+  if (sel.unknown.length) die(L.doctor.selectUnknown(sel.unknown.join(", "), Object.keys(man?.groups || {}).join(", ")));
+  const gates = sel.run;
   const advisory = advisorySet(man);
   const bar = progress();
 
@@ -79,14 +147,21 @@ function runGates(man, opts = {}) {
   if (scoped) console.log(c.dim(`\n  ${L.doctor.sinceHeading(opts.since, scoped.size)}`));
 
   console.log(c.bold(`\n  ${L.doctor.runHeading}\n`));
+  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;
+  const tStart = Date.now();
   for (const [i, [name, cmd]] of gates.entries()) {
     bar.show(`  ${c.dim("⋯")}  ${name.padEnd(14)} ${c.dim(L.doctor.running(i + 1, gates.length))}`);
-    const t0 = Date.now();
-    const r = spawnSync(gateCommand(cmd), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+    const t0 = pooled ? tStart : Date.now();
+    const r = pooled ? await pooled[i] : spawnGate(cmd);
     bar.clear();
+    // При --jobs время гейта от начала прогона: точнее не узнать без часов в потоке, и честнее
+    // так и считать, чем приписать гейту чужое ожидание в очереди.
     const secs = (Math.max(0, Date.now() - t0) / 1000).toFixed(1);
     // Вывод гейта запоминается целиком (с потолком, чтобы болтливый инструмент не съел память):
     // по нему считается покрытие дифа — какой файл вообще был назван хоть одной проверкой.
@@ -107,12 +182,16 @@ 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 {
@@ -181,14 +260,24 @@ 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))}`);
-  return { failed, ran: gates.length, results, 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 };
+export { declaredGates, sinceRef, runGates, progress, selectGates, listArg };

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

@@ -0,0 +1,144 @@
+// Первый запуск: главное — вверху, а не после двадцати крестов.
+//
+// НАЙДЕНО РАЗБОРОМ СОСЕДА 2026-09-11 (research/competitors/agentlint.md). На requests `doctor`
+// печатал 36 строк крестов — у каждой из 18 записей своя строка «поставить: aqk add …», — и
+// только со строки 84 из 102 шли «у вас уже есть» и «начните с этих трёх». Человек читает
+// сверху и закрывает раньше, чем доходит до того, ради чего вывод написан. agentlint в том же
+// месте печатает пять главных исправлений первыми.
+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, run } from "./_fixture.mjs";
+
+// Цвет снимается до разбора: заголовок жирный, значки цветные, и регулярка по сырому выводу
+// не узнаёт ни то, ни другое.
+const plain = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+// Проект, где применимо больше трёх записей: иначе блока «начните с трёх» нет вовсе.
+const FILES = {
+  "package.json": JSON.stringify({ name: "x", scripts: { test: "node --test", lint: "eslint ." } }),
+  "src/app.js": "export function f(a) {\n  return a + 1;\n}\n",
+  "src/util.py": "def g(x):\n    return x * 2\n",
+  "tests/app.test.js": "import test from 'node:test';\ntest('x', () => {});\n",
+};
+
+test("первый запуск: «начните с трёх» стоит выше списка остальных записей", (t) => {
+  const p = project(t, FILES);
+  const out = plain(aqk(p, "doctor").out);
+  const lines = out.split("\n");
+  const start = lines.findIndex((l) => /Начните с этих трёх/.test(l));
+  assert.ok(start > -1, `блока «начните с трёх» нет:\n${out}`);
+  // Кресты каталога — строки «✘  <slug>» ниже заголовка «Гейты»; кресты раскладки (.aqk/docs,
+  // AGENTS.md) стоят выше него и к делу не относятся.
+  const heading = lines.findIndex((l) => /^\s*Гейты\s*$/.test(l));
+  const firstCross = lines.findIndex((l, i) => i > heading && /^\s*○\s+[a-z][a-z-]+\s/.test(l));
+  assert.ok(firstCross > -1, `список записей пропал:\n${out}`);
+  assert.ok(start < firstCross, `«начните с трёх» на строке ${start + 1}, а первый крест — на ${firstCross + 1}`);
+});
+
+test("первый запуск: «поставить: aqk add» не повторяется у каждой записи, записи не теряются", (t) => {
+  const p = project(t, FILES);
+  const out = plain(aqk(p, "doctor").out);
+  const hints = out.split("\n").filter((l) => /поставить:/.test(l));
+  // Одна общая подсказка и те, что стоят у находок пробы, — но не по строке на каждую запись.
+  assert.ok(hints.length <= 3, `подсказок «поставить» ${hints.length} — по одной на запись:\n${hints.join("\n")}`);
+  const crosses = out.split("\n").filter((l) => /^\s*○\s+[a-z][a-z-]+\s/.test(l));
+  assert.ok(crosses.length >= 4, `записей к установке ${crosses.length} — список сократили вместо того, чтобы сжать:\n${out}`);
+});
+
+// СЛУЖЕБНЫЕ ФАЙЛЫ НЕ ПОПАДАЮТ В GIT. Отзыв с живого проекта 2026-09-11: `.aqk/last-run.md`
+// однажды закоммитили, и с тех пор каждый `make check` оставляет изменённый файл. А проба
+// печатала «рабочее дерево не трогается», записывая `.aqk/last-probe.md`. В коде лежал
+// комментарий «.aqk/ в .gitignore» — только `init` его туда не клал. Целиком `.aqk/`
+// игнорировать нельзя: методички и правила в нём — содержимое проекта, их коммитят.
+test("init кладёт служебные файлы .aqk в .gitignore, повторный init строк не дублирует", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n", ".gitignore": "node_modules/\n" });
+  aqk(p, "init");
+  aqk(p, "init");
+  const gi = readFileSync(join(p.dir, ".gitignore"), "utf8");
+  for (const f of ["last-run.md", "last-probe.md", "advice-shown", "update-checked"]) {
+    const n = gi.split("\n").filter((l) => l.trim() === `.aqk/${f}`).length;
+    assert.equal(n, 1, `.aqk/${f} в .gitignore ${n} раз(а):\n${gi}`);
+  }
+  assert.match(gi, /^node_modules\/$/m, "чужие строки .gitignore не тронуты");
+  // И методички при этом не спрятаны: их коммитят.
+  assert.equal(run(p, "git", ["check-ignore", "-q", ".aqk/docs"]).code, 1, ".aqk/docs оказался в игноре");
+});
+
+test("doctor называет служебный файл, который отслеживает git, — с командой, как вынуть", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n", ".aqk/last-run.md": "# старый отчёт\n" });
+  run(p, "git", ["add", "-A"]);
+  run(p, "git", ["commit", "-qm", "init"]);
+  const out = plain(aqk(p, "doctor").out);
+  assert.match(out, /\.aqk\/last-run\.md/, `служебный файл в git не назван:\n${out}`);
+  assert.match(out, /git rm --cached \.aqk\/last-run\.md/, "нет готовой команды");
+});
+
+// ✘ — ТОЛЬКО ДЛЯ НАСТОЯЩЕГО ПАДЕНИЯ. Отзыв с живого проекта 2026-09-11: в зелёном прогоне висели
+// девять крестов — записи каталога, которые просто не установлены. Глаз читает их как провал, и
+// через неделю человек перестаёт смотреть на красное вообще. Неустановленное — своим знаком.
+test("неустановленная запись — ○, а не ✘: крест значит «упало», и больше ничего", (t) => {
+  const p = project(t, FILES);
+  const out = plain(aqk(p, "doctor").out);
+  const lines = out.split("\n");
+  const heading = lines.findIndex((l) => /^\s*Гейты\s*$/.test(l));
+  const crosses = lines.filter((l, i) => i > heading && /^\s*✘\s/.test(l));
+  assert.deepEqual(crosses, [], `в осмотре без прогона стоят кресты:\n${crosses.join("\n")}`);
+});
+
+// МЕТОДИЧКИ — СОВЕТ, А НЕ ПРИГОВОР. Отзыв с живого проекта 2026-09-11: первый `doctor --run`
+// покраснел только из-за отсутствия `.aqk/docs` — «files from the header are missing». Проект
+// вправе держать пособия где-то ещё или не держать вовсе; гейты при этом зелёные. Точка входа,
+// .gitignore и .git остаются обязательными: на них стоит своя проверка вердикта.
+test("нет .aqk/docs и .aqk/rules — прогон всё равно зелёный, пункт назван советом", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n", ".gitignore": "x\n" });
+  aqk(p, "init");
+  rmSync(join(p.dir, ".aqk", "docs"), { recursive: true, force: true });
+  rmSync(join(p.dir, ".aqk", "rules"), { recursive: true, force: true });
+  const man = join(p.dir, ".aqk.yml");
+  writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m, 'gates:\n  тихий: "true"'), "utf8");
+  const r = aqk(p, "doctor", "--run");
+  const tail = plain(r.out).trimEnd().split("\n").slice(-4).join("\n");
+  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\[/, "задание уходит агенту текстом — без цветовых кодов");
+});