agent-quality-kit 0.11.0 → 0.13.0

package/tool/lib/prove.mjs

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { CWD, exists } from "./core.mjs";
 import { parseManifest, gateRequires } from "./manifest.mjs";
 import { whichSync } from "./repo.mjs";
-import { classify, findingCodes } from "./execution.mjs";
+import { classify, findingCodes, gateCommand } from "./execution.mjs";
 
 // Гейт можно доказать, если у него есть оба образца. Признак по образцам, а не по тексту
 // команды: запись, делегирующая готовому инструменту (`npx knip --directory .`), каталог
@@ -108,7 +108,7 @@ async function samplesForRecipe(samplesDir, name) {
 // «не знаем» — а вызывающий тут же считал его находкой. Опыт 2026-09-09: проверка, виснущая
 // на красном образце, получала вердикт «доказана».
 function run(cmd, timeoutMs, prog) {
-  const r = spawnSync(cmd, { shell: true, encoding: "utf8", cwd: CWD, timeout: timeoutMs });
+  const r = spawnSync(gateCommand(cmd), { shell: true, encoding: "utf8", cwd: CWD, timeout: timeoutMs });
   const out = `${r.stdout || ""}${r.stderr || ""}`.trim();
   return { ...classify(r, findingCodes(prog)), 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` есть и у того, кто настроил один только список разрешений;
@@ -265,6 +267,22 @@ function pickRecipe(rec, facts, missing) {
     console.log(c.dim(`  ${c.yellow("!")}  ${L.recipe.skipped(lang, prog)}`));
   }
 
+  // Безъязыковой родной рецепт. Ключи рецептов — языки, и это верно для линтеров, но неверно
+  // для инструментов, которым язык безразличен: `gitleaks` ищет ключи в любом файле, и
+  // `secrets-not-in-code` объявлен `always: true`. Без этого ключа выбор был из двух плохих —
+  // продублировать команду под восемь языков (тот самый повтор, против которого у нас гейт)
+  // или оставить запись без родного рецепта. Второе и было: замер на десяти чужих проектах
+  // 2026-09-10 дал секреты в НЕПОКРЫТЫХ у axios и у всех четырёх python-проектов, то есть там,
+  // где польза наибольшая, команды для вставки не существовало.
+  //
+  // Стоит ПОСЛЕ языков и ПЕРЕД переносимым: свой язык точнее, а родной сильнее переносимого —
+  // но только если его есть чем выполнить.
+  if (recipes.native) {
+    const prog = String(recipes.native).trim().split(/\s+/)[0];
+    if (runnable(recipes.native)) return recipes.native;
+    if (Array.isArray(missing) && !missing.includes(prog)) missing.push(prog);
+  }
+
   return recipes.any || null;
 }
 

package/tool/lib/run.mjs

@@ -9,10 +9,12 @@
 // файл был полон, и любая следующая правка ложилась туда просто потому, что «так ближе по
 // контексту». Ровно то, о чём предупреждает совет самого гейта.
 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";
 import { L } from "../i18n/index.mjs";
+import { gateCommand } from "./execution.mjs";
 
 
 // «Гейт объявлен» и «гейт работает» — разные утверждения. Первое читается из манифеста,
@@ -39,10 +41,100 @@ function sinceRef(argv = process.argv) {
   return v && !v.startsWith("-") ? v : null;
 }
 
-function runGates(man, opts = {}) {
-  const gates = declaredGates(man);
-  if (!gates.length) return { failed: 0, ran: 0, results: [] };
+// СТРОКА «ИДЁТ». Гейт идёт через spawnSync, и строка про него печаталась только по завершении:
+// минута `smoke` — минута пустого экрана, «работает» неотличимо от «повисло», и человек пишет
+// сам, не дождавшись. Просьба владельца 2026-09-10: «я запустил и должен видеть, как идёт».
+//
+// Только в терминал. В пайп и в конвейер — ни байта: лог там читают глазами и разбирают
+// машиной, и строка, переписанная возвратом каретки, в файле превращается в мусор.
+// Секунды не тикают: для этого нужен асинхронный запуск и убийство группы процессов на
+// таймауте, а у нас windows в конвейере. Имя и номер гейта отвечают на вопрос и без них.
+function progress({ tty = process.stdout.isTTY, write = (s) => process.stdout.write(s) } = {}) {
+  let shown = false;
+  return {
+    show(text) {
+      if (!tty) return;
+      if (shown) write("\r\x1b[K");
+      write(text);
+      shown = true;
+    },
+    clear() {
+      if (!tty || !shown) return;
+      write("\r\x1b[K");
+      shown = false;
+    },
+  };
+}
+
+// ГРУППЫ И --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();
 
   // Сужение по дифу — договор с человеком, и он должен видеть, ЧТО именно сужено. Пустой диф
   // называется вслух: иначе «все гейты зелёные» означало бы «сравнили не с тем» и читалось бы
@@ -52,12 +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 = [];
 
-  for (const [name, cmd] of gates) {
-    const t0 = Date.now();
-    const r = spawnSync(cmd, { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+  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 = 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);
     // Вывод гейта запоминается целиком (с потолком, чтобы болтливый инструмент не съел память):
     // по нему считается покрытие дифа — какой файл вообще был назван хоть одной проверкой.
@@ -159,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 };
+export { declaredGates, sinceRef, runGates, progress, selectGates, listArg };

package/tool/selfcheck/gates.sh

@@ -118,14 +118,24 @@ for GATE in "$CAT"/*/; do
   # наблюдался трижды под тяжёлой параллельной нагрузкой, каждый раз на РАЗНОЙ записи, README
   # которой на месте и раздел содержит; воспроизвести в покое не удалось за сорок прогонов.
   # Причина не доказана — но обвинять запись в том, чего не проверяли, нельзя в любом случае.
-  printf '%s\n' "$README_TEXT" | grep -qE '[Гг]отовы(й аналог|й инструмент|е правил)|[Гг]отового аналога'
+  # ПОЧЕМУ ЗДЕСЬ НЕТ КОНВЕЙЕРА. Было `printf … | grep -qE …`, и это давало ПЛАВАЮЩИЙ отказ,
+  # который мы ловили трижды и не могли объяснить: запись обвинялась в отсутствии раздела,
+  # который у неё есть. Причина найдена 2026-09-10 тем самым сообщением «grep вышел с кодом
+  # 141», ради которого исход и был разложен на три. 141 = 128 + 13 = SIGPIPE: `grep -q`
+  # выходит на ПЕРВОМ совпадении и закрывает трубу, а `printf` в этот момент ещё пишет и
+  # умирает от сигнала. При `set -o pipefail` (строка 9) статусом конвейера становится 141.
+  # Воспроизведено 100 из 100, когда совпадение в НАЧАЛЕ текста, — оттого и «случайная»
+  # запись: у одних раздел в начале README, у других в конце.
+  # Здесь-строка конвейера не создаёт, и гонки не существует.
+  grep -qE '[Гг]отовы(й аналог|й инструмент|е правил)|[Гг]отового аналога' <<< "$README_TEXT"
   case $? in
     0) : ;;
     1) bad "$SLUG: в README нет раздела про готовый аналог — «не искал» и «нет» разные утверждения" ;;
     *) bad "$SLUG: поиск раздела про готовый аналог НЕ СОСТОЯЛСЯ (grep вышел с кодом $?) — это не приговор записи" ;;
   esac
   # Те же три исхода, что и у поиска выше, и по той же причине.
-  printf '%s\n' "$README_TEXT" | grep -qE 'чего НЕ ловит|Чего НЕ ловит|чего не ловит|Чего не ловит'
+  # Тот же довод, что у поиска выше: конвейер + `grep -q` = гонка с SIGPIPE.
+  grep -qE 'чего НЕ ловит|Чего НЕ ловит|чего не ловит|Чего не ловит' <<< "$README_TEXT"
   case $? in
     0) : ;;
     1) bad "$SLUG: в README нет раздела «чего НЕ ловит» — граница записи обязана быть названа" ;;

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 } from "../lib/cadence.mjs";
+import { probeDue, probeState, probeEvery, PROBE_EVERY, blindLines, parseBlind, parseRan, autoProbeAllowed } from "../lib/cadence.mjs";
 
 test("порог по умолчанию — сто коммитов, и он назван числом, а не спрятан", () => {
   assert.equal(PROBE_EVERY, 100);
@@ -67,3 +67,53 @@ test("непонятое значение порога — null, а не тих
   assert.equal(probeEvery({ probe: "часто" }), null);
   assert.equal(probeEvery({ probe: -5 }), null);
 });
+
+// --- отметка несёт ИМЕНА непойманных классов ------------------------------------------
+// ЗАЧЕМ. Отметка хранила одно число — `blind: 1`. Агент в `context` видел «один класс», человек
+// в `doctor` не видел ничего, и чтобы узнать КАКОЙ, надо было снова запускать пробу — ту самую
+// команду, о которой никто не вспоминает. Находка, которую не показали, не предостерегает.
+test("отметка пробы: по строке на слепой класс, в самом горячем файле, где он слеп", () => {
+  const recs = [
+    { entry: "swallowed-error", file: "src/a.py", verdict: "blind" },
+    { entry: "swallowed-error", file: "src/b.py", verdict: "blind" },
+    { entry: "no-print-in-prod", file: "src/a.py", verdict: "caught" },
+    { entry: "dead-code", file: "src/b.py", verdict: "unknown" },
+  ];
+  const lines = blindLines(recs);
+  // То же правило, что у countProbe: класс, слепой хоть где-то, — непокрыт; «не смогли» — не слеп.
+  assert.deepEqual(lines, ["blind-class: swallowed-error src/a.py"]);
+  const text = ["at: 5", "blind: 1", "", ...lines, "- src/a.py (fixes: 3)"].join("\n");
+  assert.deepEqual(parseBlind(text), [{ slug: "swallowed-error", file: "src/a.py" }]);
+});
+
+test("отметка старого формата и пустая — пустой список, а не падение", () => {
+  assert.deepEqual(parseBlind("at: 5\nblind: 1\n"), []);
+  assert.deepEqual(parseBlind(""), []);
+  assert.deepEqual(parseBlind(null), []);
+});
+
+// «Объявлен сейчас» не значит «поставлен после пробы»: проба и гоняет объявленные гейты.
+// Первая версия так и решила — и на самом комплекте написала «поставлено после пробы» про
+// gate-not-weakened, который стоял ДО неё и в kit/gates/_skip.sh брак пропустил. Самое ценное
+// сообщение («объявлен, но здесь не ловит») подменилось утешительным. Поймано живым прогоном.
+test("отметка помнит, какие гейты проба ПРОГОНЯЛА", () => {
+  const text = "at: 5\nblind: 1\nran: smoke gate-not-weakened units\n\nblind-class: x a.sh\n";
+  assert.deepEqual([...parseRan(text)].sort(), ["gate-not-weakened", "smoke", "units"]);
+  // Старая отметка этой строки не несёт: «не знаем», а не «ничего не было объявлено».
+  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(", ")}`);
+  }
+});