agent-quality-kit 0.12.0 → 0.13.0

package/tool/lib/manifest.mjs

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

package/tool/lib/repo.mjs

@@ -46,6 +46,8 @@ const MARKS = [
   ["has_docker", ["Dockerfile", "compose.yml", "compose.yaml", "docker-compose.yml", "docker-compose.yaml"]],
   ["has_deps", ["package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml", "Gemfile", "pom.xml", "composer.json"]],
   ["has_env", [".env", ".env.example", ".env.sample"]],
+  // Линтер проекта — Biome: совет даётся на его языке, а не на языке eslint.
+  ["has_biome", ["biome.json", "biome.jsonc"]],
   // Обвес самого агента: настройки, хуки, права. Отдельный признак нужен, потому что записи
   // про него не касаются проектов, где агента не настраивали вовсе, — а таких большинство.
   // Файл `.claude/settings.json` есть и у того, кто настроил один только список разрешений;
@@ -378,40 +380,9 @@ async function matchCatalog(query) {
   return out;
 }
 
-// С ЧЕГО НАЧАТЬ: три записи вместо двадцати равнозначных крестов.
-//
-// Двадцать одинаковых требований — это ноль требований: закрывают первое попавшееся или не
-// закрывают ничего. Порядок НЕ по нашему вкусу; два признака, оба — факты, которые у нас уже
-// есть:
-//   · запись родилась из настоящего отказа (`lifecycle: stable` — `proof` ссылается на журнал
-//     шишек), то есть она про боль, которая СЛУЧАЛАСЬ, а не про «хорошую практику»;
-//   · её можно закрыть одной готовой командой — цена входа минутная.
-// Сначала то, что и больно, и дёшево.
-//
-// При равенстве признаков — по имени: одинаковый ввод обязан давать одинаковый ответ, иначе
-// человек видит разный совет на двух прогонах подряд и перестаёт верить обоим.
-function startWith(entries, facts, n = 3) {
-  const langs = facts?.langs ? [...facts.langs] : [];
-  const cheap = (e) => {
-    const r = e?.recipes && typeof e.recipes === "object" ? e.recipes : {};
-    return [...langs, "native"].some((k) => r[k] && !/\{gate\}/.test(r[k])) ? 1 : 0;
-  };
-  // Зрелость НЕ поле записи, а вычисляемый признак: `proof` ссылается на журнал шишек. Тот же
-  // признак, которым каталог отделяет условную запись с первого дня (`entryLifecycle`).
-  // Заводить второй счёт нельзя: разъехавшись, они дали бы разные ответы про одну запись.
-  const hurt = (e) => (/incidents\//.test(String(e?.proof || "")) ? 1 : 0);
-  return [...entries]
-    .sort((a, b) =>
-      (hurt(b) + cheap(b)) - (hurt(a) + cheap(a)) ||
-      cheap(b) - cheap(a) ||
-      String(a.slug).localeCompare(String(b.slug)))
-    .slice(0, n);
-}
-
 // Наружу — то, что действительно импортируют другие файлы и модульные проверки. Экспорт,
 // который никто не берёт, читается как часть договора и мешает менять внутренности.
 export {
   whichSync,
   EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor, browserServerAdvice, MARKS,
-  startWith,
   stems, overlap, matchCatalog, isApiSpec };

package/tool/lib/run.mjs

@@ -9,6 +9,7 @@
 // файл был полон, и любая следующая правка ложилась туда просто потому, что «так ближе по
 // контексту». Ровно то, о чём предупреждает совет самого гейта.
 import { spawnSync } from "node:child_process";
+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";
@@ -65,9 +66,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 +144,20 @@ 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 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);
     // Вывод гейта запоминается целиком (с потолком, чтобы болтливый инструмент не съел память):
     // по нему считается покрытие дифа — какой файл вообще был назван хоть одной проверкой.
@@ -188,7 +259,7 @@ function runGates(man, opts = {}) {
   // тишина, против которой построен стандарт: проверка выключена, а выглядит как её отсутствие.
   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 };
+  return { failed, ran: gates.length, results, advisoryFailed, skipped: sel.skipped };
 }
 
-export { declaredGates, sinceRef, runGates, progress };
+export { declaredGates, sinceRef, runGates, progress, selectGates, listArg };

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

@@ -0,0 +1,105 @@
+// Первый запуск: главное — вверху, а не после двадцати крестов.
+//
+// НАЙДЕНО РАЗБОРОМ СОСЕДА 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/, "отсутствие методичек не названо вовсе");
+});

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

@@ -6,7 +6,7 @@
 // Обратная сторона нашего же принципа: молчание неотличимо не только от успеха, но и от отказа.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { project, aqk } from "./_fixture.mjs";
 
@@ -23,7 +23,10 @@ test("прогон называет свой вердикт словами в о
   const man = join(p.dir, ".aqk.yml");
   writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m, 'gates:\n  тихий: "true"'), "utf8");
 
-  // .gitignore нет — прогон красный, и обязан сказать, из-за чего именно.
+  // .gitignore нет — прогон красный, и обязан сказать, из-за чего именно. Удаляется ЯВНО:
+  // `init` с 2026-09-11 сам создаёт .gitignore под служебные файлы, и прежняя посылка теста
+  // («после init его нет») перестала быть правдой.
+  rmSync(join(p.dir, ".gitignore"), { force: true });
   const red = aqk(p, "doctor", "--run");
   // Сообщение утверждения обязано нести ВЕСЬ хвост: проверка, которая говорит только «не
   // совпало», отправляет читателя гадать — ровно то, за что мы ругаем чужие проверки.
@@ -38,3 +41,49 @@ test("прогон называет свой вердикт словами в о
   assert.equal(green.code, 0, `прогон остался красным:\n${greenTail}`);
   assert.match(greenTail, /зелён/, `успех не назван словами:\n${greenTail}`);
 });
+
+// --skip ГРУППОЙ: гейт, которому нужен стенд, в быстром прогоне не идёт — и это СКАЗАНО, а не
+// скрыто. Отзыв с живого проекта 2026-09-11 (гейт цены без стенда валил прогон).
+test("--skip группой: прогон зелёный, пропущенный назван в выводе и в отчёте", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n" });
+  aqk(p, "init");
+  const man = join(p.dir, ".aqk.yml");
+  writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m, 'gates:\n  тихий: "true"\n  cost: "false"') +
+    "groups:\n  stack: [cost]\n", "utf8");
+  const r = aqk(p, "doctor", "--run", "--skip", "stack");
+  assert.equal(r.code, 0, `прогон без стенда покраснел:\n${r.out.slice(-600)}`);
+  assert.match(r.out, /cost/, "пропущенный гейт не назван");
+  const report = readFileSync(join(p.dir, ".aqk", "last-run.md"), "utf8");
+  assert.match(report, /^~ cost/m, `в отчёте для агента пропущенный не отмечен:\n${report}`);
+  // Опечатка в имени группы — отказ с названной причиной, а не прогон всего подряд.
+  const typo = aqk(p, "doctor", "--run", "--skip", "stak");
+  assert.notEqual(typo.code, 0);
+  assert.match(typo.out, /stak/);
+});
+
+// --jobs N: независимые гейты параллельно. Отзыв с живого проекта 2026-09-11: 34 гейта идут
+// друг за другом больше минуты, «а быструю проверку, которую долго ждать, перестают запускать».
+// Параллельность — по флагу: гейты, пишущие в одни файлы (общий dist/), иначе плавали бы.
+test("--jobs 3: три секундных гейта идут одновременно, порядок и вердикт прежние", (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  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");
+  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]);
+  assert.deepEqual(order, ["a", "b", "c"], `порядок вывода не по объявлению: ${order}`);
+  // Три секунды последовательно; параллельно — одна плюс запуск node. Запас на медленную машину.
+  assert.ok(secs < 2.8, `прогон шёл ${secs.toFixed(1)} с — параллельности нет`);
+});
+
+test("--jobs без числа или с нулём — отказ с причиной, а не тихий последовательный прогон", (t) => {
+  const p = project(t, { "src/a.py": "x = 1\n" });
+  aqk(p, "init");
+  const r = aqk(p, "doctor", "--run", "--jobs", "0");
+  assert.notEqual(r.code, 0);
+  assert.match(r.out, /--jobs/);
+});

package/tool/selfcheck/smoke.sh

@@ -1903,8 +1903,12 @@ CADP="$(mktemp -d)"
   node "$CLI" init && node "$CLI" add todo-without-task
 ) >/dev/null 2>&1
 CTX0=$( cd "$CADP" && AQK_LANG=ru node "$CLI" context 2>&1 )
-RUN1=$( cd "$CADP" && AQK_LANG=ru node "$CLI" doctor --run 2>&1 )
-RUN2=$( cd "$CADP" && AQK_LANG=ru node "$CLI" doctor --run 2>&1 )
+# Путь ЧЕЛОВЕКА: переменные конвейера сняты. С 2026-09-11 в конвейере проба сама не идёт (минуты
+# сюрпризом в быстрой проверке), и без `env -u` эта проверка была зелёной у нас и красной в CI —
+# она проверяла бы окружение, а не каденцию. Поведение в конвейере сторожит units-cadence.mjs.
+NOCI="env -u CI -u GITHUB_ACTIONS -u GITLAB_CI -u BUILDKITE -u JENKINS_URL"
+RUN1=$( cd "$CADP" && $NOCI AQK_LANG=ru node "$CLI" doctor --run 2>&1 )
+RUN2=$( cd "$CADP" && $NOCI AQK_LANG=ru node "$CLI" doctor --run 2>&1 )
 CTX1=$( cd "$CADP" && AQK_LANG=ru node "$CLI" context 2>&1 )
 if printf '%s' "$CTX0" | grep -q "НЕИЗВЕСТНО" &&
    printf '%s' "$RUN1" | grep -q "ещё не делали" &&

package/tool/selfcheck/units-cadence.mjs

@@ -7,7 +7,7 @@
 // незачем, а сто коммитов за день перепроверить надо.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan } from "../lib/cadence.mjs";
+import { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed } from "../lib/cadence.mjs";
 
 test("порог по умолчанию — сто коммитов, и он назван числом, а не спрятан", () => {
   assert.equal(PROBE_EVERY, 100);
@@ -103,3 +103,17 @@ test("отметка помнит, какие гейты проба ПРОГОН
   assert.equal(parseRan("at: 5\nblind: 1\n"), null);
   assert.deepEqual([...parseRan("ran:\n")], []);
 });
+
+// Проба, встроенная в `doctor --run`, в конвейере — это +2–3 минуты в случайном прогоне раз в
+// сто коммитов. Отзыв с живого проекта 2026-09-11: «пусть probe будет отдельной командой или
+// задачей, а не сюрпризом внутри быстрой проверки». В конвейере она сама не запускается; у
+// человека — по-прежнему сама: там её и надо не забыть.
+test("проба сама не запускается в конвейере, в коротком режиме и при AQK_PROBE=0", () => {
+  assert.equal(autoProbeAllowed({ brief: false, env: {} }), true);
+  assert.equal(autoProbeAllowed({ brief: false, env: { CI: "true" } }), false);
+  assert.equal(autoProbeAllowed({ brief: false, env: { GITHUB_ACTIONS: "true" } }), false);
+  assert.equal(autoProbeAllowed({ brief: true, env: {} }), false);
+  assert.equal(autoProbeAllowed({ brief: false, env: { AQK_PROBE: "0" } }), false);
+  // Явное AQK_PROBE=1 включает и в конвейере: у всего, что решено за человека, есть способ решить иначе.
+  assert.equal(autoProbeAllowed({ brief: false, env: { CI: "true", AQK_PROBE: "1" } }), true);
+});

package/tool/selfcheck/units-context.mjs

@@ -9,7 +9,7 @@
 //   node --test tool/selfcheck/units-context.mjs
 import test from "node:test";
 import assert from "node:assert/strict";
-import { contextBlock, countArbiters, parseLastRun, withHook, hasOurHook, portableSelf } from "../commands/context.mjs";
+import { contextBlock, countArbiters, parseLastRun, withHook, hasOurHook, portableSelf, nextSteps } from "../commands/context.mjs";
 import { CATALOGS } from "../i18n/index.mjs";
 import { commandRows } from "../lib/core.mjs";
 import { readFile } from "node:fs/promises";
@@ -210,3 +210,66 @@ test("выключенная и несостоявшаяся проба не в
   const unknown = text({ probe: { state: "unknown", behind: null, blind: 0 } });
   assert.match(unknown, /НЕИЗВЕСТНО|неизвестн/i, `несостоявшаяся проба не названа: ${unknown}`);
 });
+
+// --- «Дальше» и «Когда что» ------------------------------------------------------------
+// ЗАЧЕМ. Блок отвечал только на «как дела»: уровень, красное, проба. Что делать ДАЛЬШЕ, `doctor`
+// знал — три первых шага, непойманные пробой классы, чужие проверки проекта, — а в контекст это
+// не попадало. Карта «какую команду когда» жила только в полной версии, в восьми тысячах
+// токенов, где агент её пролистывал. Владелец 2026-09-11: «агент читает половину и не
+// пользуется всем функционалом». Документация Claude Code (code.claude.com/docs/en/memory):
+// «The more specific and concise your instructions, the more consistently Claude follows them»;
+// «"Run `npm test` before committing" instead of "Test your changes"».
+test("дальше: не больше трёх шагов, остаток назван числом, свои проверки проекта — первыми", () => {
+  const adopt = [{ name: "test", cmd: "make test" }];
+  const blind = [
+    { slug: "swallowed-error", file: "src/a.py", command: "ruff check --select BLE ." },
+    { slug: "no-print-in-prod", file: "src/b.py", command: null },
+  ];
+  const start = [
+    { slug: "complexity-limit", command: "ruff check --select C901 ." },
+    { slug: "swallowed-error", command: "ruff check --select BLE ." },
+    { slug: "dead-code", command: "vulture ." },
+  ];
+  const { steps, rest } = nextSteps({ adopt, blind, start });
+  assert.deepEqual(steps.map((s) => s.kind), ["adopt", "blind", "blind"]);
+  // Класс из пробы и тот же класс в «начните с трёх» — один шаг, а не два.
+  assert.equal(rest, 2, "complexity-limit и dead-code остаются; swallowed-error уже учтён пробой");
+  assert.deepEqual(nextSteps({}), { steps: [], rest: 0 });
+});
+
+test("дальше: блок печатает шаги по номерам, с командами; пусто — заголовка нет", () => {
+  const next = nextSteps({ start: [{ slug: "dead-code", command: "vulture ." }] });
+  const t = text({ next });
+  assert.match(t, new RegExp(T.nextTitle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  assert.match(t, /1\. .*dead-code/);
+  assert.match(t, /vulture \./, "команда, которую можно выполнить сейчас, обязана быть в шаге");
+  assert.doesNotMatch(text({ next: { steps: [], rest: 0 } }), new RegExp(T.nextTitle.slice(0, 12)));
+});
+
+test("когда что: правило про коммит зависит от того, стоит ли хук", () => {
+  const withHook = text({ when: { hook: true } });
+  const noHook = text({ when: { hook: false } });
+  assert.match(withHook, /--no-verify/, "хук стоит — агенту сказано не обходить его");
+  assert.match(noHook, /doctor --run --since main/, "хука нет — агенту дана команда");
+  assert.notEqual(withHook, noHook);
+  // Каждое правило — «ситуация → команда»: без команды в строке правило непроверяемо.
+  for (const line of T.whenRules) assert.match(line, /`[^`]+`/, `в правиле нет команды: ${line}`);
+});
+
+// Без манифеста `aqk add` отказывает («сначала init») — шаг «поставь запись» на таком проекте
+// отправлял агента в ошибку. Найдено живым прогоном блока на requests 2026-09-11.
+test("дальше: манифеста нет — первый шаг `aqk init`, остальные после него", () => {
+  const { steps } = nextSteps({ init: true, start: [{ slug: "dead-code", command: null }] });
+  assert.equal(steps[0].kind, "init");
+  assert.equal(steps[1].kind, "start");
+  assert.match(T.nextStep.init(steps[0]), /`aqk init`/);
+});
+
+// Отзыв с живого проекта 2026-09-11: в `aqk help` у `vitals` вместо описания стояло `undefined` —
+// команду добавили в список, а текст справки забыли. Сторож на весь список, на оба языка.
+test("у каждой команды в справке есть описание на обоих языках", () => {
+  for (const lang of ["ru", "en"]) {
+    const empty = commandRows(CATALOGS[lang]).filter((r) => typeof r.text !== "string" || !r.text.trim()).map((r) => r.name);
+    assert.deepEqual(empty, [], `${lang}: нет описания у ${empty.join(", ")}`);
+  }
+});