agent-quality-kit 0.2.2

package/tool/lib/repo.mjs

@@ -0,0 +1,270 @@
+// tool/lib/repo.mjs — осмотр репозитория и каталог обещаний: языки и признаки, условия
+// триггера, выбор рецепта, сверка по намерению.
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { CWD, GATES_SRC, c, exists } from "./core.mjs";
+import { parseManifest } from "./manifest.mjs";
+
+// Каталог лежит в комплекте, а не в проекте: записи общие для всех, проект лишь
+// решает, какие из них у него стоят. Показывать все подряд нельзя — это и есть
+// разница между каталогом и списком: у каждой записи обязателен триггер, и до
+// глаз человека доходит только применимое к его репозиторию.
+
+// Расширения перечислены полностью, включая модульные варианты: .mjs пропускался, и на самом
+// aqk — где вся программа лежит в .mjs — запись про отладочную печать пряталась с пояснением
+// «нет языков: javascript». Гейт, спрятанный по неверно опознанному языку, молчит так же, как
+// отсутствующий.
+const EXT_LANG = {
+  ".py": "python", ".js": "javascript", ".jsx": "javascript",
+  ".mjs": "javascript", ".cjs": "javascript",
+  ".ts": "typescript", ".tsx": "typescript", ".mts": "typescript", ".cts": "typescript",
+  ".go": "go", ".rs": "rust", ".rb": "ruby", ".java": "java", ".php": "php",
+  ".cs": "csharp", ".sh": "shell", ".kt": "kotlin", ".swift": "swift", ".scala": "scala",
+};
+
+const SKIP_DIRS = new Set([".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__", ".aqk"]);
+
+// Факты о репозитории. Только то, что видно машине: спрашивать человека анкетой
+// значит снова получить мнение вместо факта.
+// Признаки репозитория — по файлам, а не по анкете. Ответы человека это мнение;
+// файлы — факт. Каждый признак нужен какому-то триггеру: признак, который никто не
+// спрашивает, — это лишний обход дерева.
+const MARKS = [
+  ["has_ci", [".github/workflows", ".gitlab-ci.yml", ".circleci", "Jenkinsfile", "azure-pipelines.yml"]],
+  ["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"]],
+];
+
+async function detectFacts(man) {
+  // Каталог образцов самого проекта: туда `add` копирует красные и зелёные примеры записей.
+  // Считать их кодом проекта значит врать о репозитории — после установки сторожей пустой
+  // проект «становился» проектом на Python, и ему показывались записи про мёртвый код.
+  const samplesDir = man?.samples ? resolve(CWD, String(man.samples)) : null;
+  const langs = new Set();
+  let files = 0;
+  let hasDb = false;
+  let hasTests = false;
+
+  async function walk(dir, depth) {
+    if (depth > 4 || files > 4000) return;
+    let items;
+    try {
+      items = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const it of items) {
+      const full = join(dir, it.name);
+      if (it.isDirectory()) {
+        if (SKIP_DIRS.has(it.name)) continue;
+        // Образцы каталога — код специально сломанный и специально исправный.
+        // Считать его языками проекта значит врать о репозитории.
+        if (full === GATES_SRC || (samplesDir && full === samplesDir)) continue;
+        if (/^(tests?|spec|__tests__)$/i.test(it.name)) hasTests = true;
+        if (/^migrations?$/i.test(it.name)) hasDb = true;
+        await walk(full, depth + 1);
+      } else {
+        files++;
+        if (/\.(test|spec)\.[a-z]+$/i.test(it.name) || /^test_.*\.py$/i.test(it.name) || /_test\.go$/i.test(it.name)) hasTests = true;
+        if (it.name.endsWith(".sql")) hasDb = true;
+        const dot = it.name.lastIndexOf(".");
+        if (dot > 0) {
+          const lang = EXT_LANG[it.name.slice(dot)];
+          if (lang) langs.add(lang);
+        }
+      }
+    }
+  }
+  await walk(CWD, 0);
+
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+  const facts = {
+    langs,
+    files,
+    has_db: hasDb,
+    has_tests: hasTests,
+    has_gates: Object.values(gates).some((c) => String(c || "").trim()),
+    gateKeys: Object.keys(gates),
+  };
+  for (const [name, paths] of MARKS) {
+    facts[name] = false;
+    for (const rel of paths) if (await exists(join(CWD, rel))) { facts[name] = true; break; }
+  }
+  return facts;
+}
+
+async function readCatalog() {
+  if (!(await exists(GATES_SRC))) return [];
+  const out = [];
+  for (const name of (await readdir(GATES_SRC, { withFileTypes: true })).filter((d) => d.isDirectory())) {
+    const yml = join(GATES_SRC, name.name, "gate.yml");
+    if (!(await exists(yml))) continue;
+    const rec = parseManifest(await readFile(yml, "utf8"));
+    out.push({ slug: name.name, ...rec });
+  }
+  return out.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+// Применима ли запись к этому репозиторию — и если нет, то почему.
+// Причина обязательна: «скрыто без объяснения» неотличимо от «потеряно».
+// Все условия триггера должны выполниться разом. Раньше проверялось первое попавшееся —
+// значит «есть база И нет конвейера» читалось как «есть база», и запись показывалась не тем.
+//
+// Причина отказа обязательна: скрытое без объяснения неотличимо от потерянного.
+const CONDITIONS = {
+  always: () => ({ ok: true }),
+
+  langs: (val, f) => {
+    const want = String(val).split(",").map((x) => x.trim()).filter(Boolean);
+    return want.some((l) => f.langs.has(l))
+      ? { ok: true }
+      : { ok: false, why: `нет языков: ${want.join(", ")}` };
+  },
+
+  files_gt: (val, f) =>
+    f.files > Number(val) ? { ok: true } : { ok: false, why: `меньше ${val} файлов — рано` },
+
+  files_lt: (val, f) =>
+    f.files < Number(val) ? { ok: true } : { ok: false, why: `больше ${val} файлов` },
+};
+
+const FLAG_WHY = {
+  has_gates: ["в манифесте не объявлено ни одного гейта", "гейты уже объявлены"],
+  has_ci: ["в репозитории нет конвейера", "конвейер уже есть"],
+  has_db: ["не видно базы данных: ни миграций, ни sql", "база данных есть"],
+  has_docker: ["нет Dockerfile или compose", "docker уже есть"],
+  has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
+  has_tests: ["не видно тестов", "тесты есть"],
+  has_env: ["нет файла окружения", "файл окружения есть"],
+};
+
+function triggerVerdict(rec, facts) {
+  const t = rec.trigger && typeof rec.trigger === "object" && !Array.isArray(rec.trigger) ? rec.trigger : {};
+  const keys = Object.keys(t);
+  if (!keys.length) return { applies: false, why: "триггер не задан" };
+
+  for (const key of keys) {
+    const raw = String(t[key]).trim();
+
+    if (CONDITIONS[key]) {
+      // always: false — не «условие отсутствует», а «запись никогда не применима». Раньше
+      // continue пропускал ключ молча, и `always: false` читалось как отсутствие ограничения.
+      if (key === "always" && raw !== "true") return { applies: false, why: "always: false" };
+      const r = CONDITIONS[key](raw, facts);
+      if (!r.ok) return { applies: false, why: r.why };
+      continue;
+    }
+
+    if (key in FLAG_WHY) {
+      const want = raw === "true";
+      if (Boolean(facts[key]) !== want) {
+        return { applies: false, why: FLAG_WHY[key][want ? 0 : 1] };
+      }
+      continue;
+    }
+
+    return { applies: false, why: `условие «${key}» программа не умеет считать` };
+  }
+  return { applies: true };
+}
+
+// Арбитр под стек этого проекта: сначала родной рецепт, иначе — переносимый `any`.
+// Подсказка, которую нельзя скопировать и выполнить, бесполезна.
+// Выбор рецепта под стек проекта. Одна логика на два места: и `doctor`, и `add` показывают
+// команду, но подставляют в неё разные пути — один в каталог пакета, другой в каталог проекта.
+// Пока это были две копии, правка доезжала до одной из них — нашёл собственный гейт дублей.
+function pickRecipe(rec, facts) {
+  const recipes = rec.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
+
+  // Родной рецепт лучше переносимого — но только если его есть чем выполнить. Поставить
+  // команду с неустановленной программой значит завести гейт, который встаёт с «not found»:
+  // отсутствие сигнала неотличимо от успеха.
+  const runnable = (c0) => {
+    const prog = String(c0).trim().split(/\s+/)[0];
+    return spawnSync(`command -v ${prog}`, { shell: true, stdio: "ignore" }).status === 0;
+  };
+  for (const lang of facts.langs) {
+    if (!recipes[lang]) continue;
+    if (runnable(recipes[lang])) return recipes[lang];
+    console.log(c.dim(`  ${c.yellow("!")}  рецепт под ${lang} пропущен: «${String(recipes[lang]).split(/\s+/)[0]}» не установлен`));
+  }
+  return recipes.any || null;
+}
+
+function recipeFor(rec, facts) {
+  const cmd = pickRecipe(rec, facts);
+  if (!cmd) return "рецепт не описан";
+  return String(cmd)
+    .replace(/\{gate\}/g, join(GATES_SRC, rec.slug))
+    .replace(/\{dir\}/g, ".");
+}
+
+const STOP = new Set([
+  "и","в","на","не","что","с","по","для","как","из","от","до","за","при","или","а","но","же",
+  "это","то","так","бы","бы","ли","у","о","об","под","над","без","есть","быть","был","была",
+  "если","чтобы","только","уже","ещё","еще","мы","он","она","они","их","его","её","ее","все",
+  "всё","код","кода","коде","проект","проекта","должен","должна","должно","надо","нужно",
+  // Латинские связки из имён записей: no-print-IN-prod, secrets-NOT-IN-code. Без них
+  // «dead-code-not-shipped» совпадает с «secrets-not-in-code» по служебным словам.
+  "not","in","on","of","to","and","or","the","a","an","is","are","be","with","for","no","has",
+]);
+
+const stems = (text) =>
+  new Set(
+    String(text || "")
+      .toLowerCase()
+      .replace(/[^a-zа-яё0-9\s-]/gi, " ")
+      .split(/\s+/)
+      .filter((w) => w.length >= 3 && !STOP.has(w))
+      .map((w) => w.slice(0, 4))
+  );
+
+function overlap(query, target) {
+  if (!query.size) return 0;
+  let hit = 0;
+  for (const q of query) if (target.has(q)) hit++;
+  return hit / query.size;
+}
+
+
+// Сверка запроса с каталогом ПО НАМЕРЕНИЮ. Одна логика на три места: `find` показывает
+// человеку, `new` не даёт завести дубль, `why` выясняет, был ли вообще такой сторож. Пока это
+// были две копии с разными порогами, «нашлось» в одной команде означало «не нашлось» в другой.
+//
+// Заголовок README считается наравне с intent: это такое же формулирование намерения, написанное
+// человеком. Остальной текст пояснения весит впятеро меньше — слова «гейт», «проверка»,
+// «образец» есть в каждой записи, и по ним совпало бы что угодно с чем угодно.
+async function matchCatalog(query) {
+  const q = stems(query);
+  const out = [];
+  for (const rec of await readCatalog()) {
+    const readme = join(GATES_SRC, rec.slug, "README.md");
+    const text = (await exists(readme)) ? await readFile(readme, "utf8") : "";
+    const title = (text.match(/^#\s+(.+)$/m) || [, ""])[1];
+    const head = stems(`${rec.slug.replace(/-/g, " ")} ${rec.intent || ""} ${title}`);
+    const body = stems(text.slice(0, 1200));
+
+    // Одно совпавшее слово — совпадение обрезки, а не смысла: «обратимы» и «образец» дают
+    // одно и то же начало. Считаем ещё и сколько слов совпало, и требуем минимум два.
+    let hits = 0;
+    for (const w of q) if (head.has(w)) hits++;
+    // Правило «минимум два совпавших слова» защищает от совпадения обрезки. Для уверенного
+    // вывода оно нужно; для подсказки «посмотри вот на эти» — нет: там человек решает сам,
+    // и одно совпавшее слово лучше, чем «ничего не найдено» при существующей записи.
+    const ok = hits >= 2 || q.size < 2;
+    const raw = 0.8 * overlap(q, head) + 0.2 * overlap(q, body);
+    out.push({ rec, hits, rawScore: raw, headScore: ok ? overlap(q, head) : 0, score: ok ? raw : 0 });
+  }
+  out.sort((a, b) => b.score - a.score);
+  return out;
+}
+
+// Наружу — то, что действительно импортируют другие файлы и модульные проверки. Экспорт,
+// который никто не берёт, читается как часть договора и мешает менять внутренности.
+export {
+  EXT_LANG, detectFacts, readCatalog, triggerVerdict, pickRecipe, recipeFor,
+  stems, overlap, matchCatalog,
+};

package/tool/lib/templates.mjs

@@ -0,0 +1,187 @@
+// tool/lib/templates.mjs — тексты, которые программа кладёт в чужой проект.
+//
+// ЗАЧЕМ ОТДЕЛЬНО. Это не код, а содержимое: правят его чаще и по другим причинам, чем логику.
+// Лёжа вперемешку с логикой, они мешали читать и то, и другое.
+
+import { SELF } from "./core.mjs";
+
+// ОДИН источник правил, НЕСКОЛЬКО входов. Каждый инструмент читает свой файл, но оба ведут в
+// .aqk/. Два расходящихся свода правил — худшее, что можно сделать: через месяц они врут
+// по-разному, и никто не знает, какой настоящий.
+
+const AGENTS_MD = `# AGENTS.md
+
+> Точка входа для агента. Держи файл коротким: раздутый свод правил вытесняет саму задачу из
+> контекста, и тогда игнорируются все правила разом. Всё длинное — по ссылкам ниже.
+
+## Железные правила
+
+- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.
+- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.
+- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.
+- **Секреты только в окружении.** Никогда в коде, логах и коммитах.
+- **Только файлы из задачи.** Заодно ничего не чиним.
+- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит
+  рабочим» — не готово.
+- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.
+- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием
+  в коде.
+
+## Оснастка AQK — это твои команды, а не человека
+
+В репозитории стоит комплект AQK. Его смысл: **обещание проекта превращается в команду с кодом
+возврата**, и дальше его держит машина, а не чья-то внимательность. «Не оставляем отладочную
+печать» — текст, который можно проигнорировать; команда, возвращающая не ноль, — нельзя.
+
+Запускать их — твоя работа. Человек смотрит на список дыр и решает, какие закрывать.
+
+| Команда | Что делает | Когда звать |
+|---|---|---|
+| \`aqk doctor\` | смотрит репозиторий и печатает три списка: что уже держит машина, чего не хватает, что этому проекту не нужно и почему | начало работы над качеством; «что тут вообще есть» |
+| \`aqk doctor --run\` | **запускает** объявленные проверки и показывает, кто нашёл брак | перед сдачей; после правок; всегда, когда нужен факт, а не обещание |
+| \`aqk add <имя>\` | ставит проверку из каталога: копирует её и образцы в проект, объявляет в манифесте | человек согласился закрыть дыру из списка \`doctor\` |
+| \`aqk ratchet <имя>\` | старые нарушения записывает долгом, новые перестаёт пускать | проверка краснеет на старом коде, и чинить его сейчас никто не будет |
+| \`aqk find "…"\` | ищет по смыслу, есть ли уже такая проверка | прежде чем изобретать свою |
+| \`aqk note "…"\` | пишет урок в общий журнал | процесс или прибор подвели: проверка соврала, правило обошли |
+
+Если команды \`aqk\` нет в системе — комплект ставили разово, без установки. Тогда вместо
+\`aqk\` пиши \`npx github:arsen-ask-lx/Agent_Quality_Kit\`. Любая команда сама печатает тот
+вызов, который сработает у тебя.
+
+**Три вещи, которые надо понимать, а не запоминать:**
+
+1. **«Объявлен» и «работает» — разные утверждения.** \`doctor\` без \`--run\` честно говорит, что
+   проверки не запускал. Не выдавай объявленное за работающее.
+2. **Проверка без двух образцов ничего не доказывает.** Красный — код, на котором она обязана
+   сработать; зелёный — правильный, на котором обязана молчать. Зелёный важнее: без него однажды
+   она покраснеет на верном коде, и её выключат вместе с остальными.
+3. **Правило вводится храповиком, а не большой чисткой.** Чистка откладывается навсегда, потому
+   что она большая. Храповик даёт действующее правило со дня установки.
+
+**Повторился дефект того же класса — это не повод быть внимательнее, а повод завести проверку.**
+Дисциплина не масштабируется, механика — да.
+
+## Где что лежит
+
+- \`.aqk/rules/\` — стандарты: общие, тесты, безопасность
+- \`.aqk/docs/\` — методички: минимум проекта, харнес, процесс, исследования
+- \`.aqk/docs/project-baseline.md\` — **начни отсюда**, если проект новый
+
+## Команды
+
+<!-- Заполни под свой проект. Команда, которую нельзя скопировать и выполнить, — не команда. -->
+
+- сборка: \`\`
+- тесты: \`\`
+- линтер: \`\`
+- всё разом перед пушем: \`\`
+
+## Чего в этом проекте нет
+
+<!-- Пиши сюда честно. Ненаписанное «нет» агент додумает как «есть». -->
+`;
+
+const CLAUDE_MD = `# CLAUDE.md
+
+Правила этого проекта живут в \`AGENTS.md\` — читай его.
+
+Один свод правил, несколько точек входа: \`AGENTS.md\` для агентов, понимающих его,
+\`CLAUDE.md\` — для Claude Code. Держать два расходящихся свода нельзя: через месяц они врут
+по-разному, и непонятно, какой настоящий.
+
+@AGENTS.md
+`;
+
+// Манифест — единственный машиночитаемый файл стандарта. Всё остальное человекочитаемо.
+// Пустые значения оставлены НАМЕРЕННО: заполненная заглушка врала бы про уровень.
+const MANIFEST_YML = `# .aqk.yml — манифест Agent Quality Kit
+# Что это: машиночитаемое описание того, как в этом репозитории живут агенты.
+# Уровень соответствия считает \`aqk doctor\`. Пустое поле = ступень не пройдена,
+# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.
+
+aqk: 1
+
+# AQK-0 — что агент читает первым.
+entry:
+  - AGENTS.md
+
+# AQK-1 — где стандарты и какие проверки обязательны.
+rules: .aqk/rules
+gates:
+  # Имя: команда, возвращающая 0 или не 0. Пустое объявление защиты не даёт и бракуется
+  # проверкой «объявленный гейт запускается» — поэтому здесь примеры, а не заготовки.
+  #   lint: "ruff check ."
+  #   test: "pytest -q"
+  # Поставить готовую запись из каталога вместе с образцами: aqk add <имя>
+
+# AQK-2 — чем доказано, что гейты работают, и где реестры долга.
+# samples: каталог с красными и зелёными образцами (гейт обязан краснеть на первом
+# и молчать на втором). ratchets: списки известных нарушений, которые могут только
+# укорачиваться.
+samples: ""
+ratchets: ""
+
+# AQK-3 — где копятся уроки. Путь или адрес.
+lessons: ""
+`;
+
+const GATE_YML_TEMPLATE = (slug) => `# Запись каталога AQK. Норма и все поля — kit/gates/README.md
+# Пока строки ниже не заполнены, проверка отклонит эту запись — так и задумано.
+
+# Одной фразой: какой класс брака ловит. По этому полю идёт сверка «есть ли уже такое».
+intent: ЗАПОЛНИ — какой класс брака ловит
+
+# Когда запись показывается человеку. Условие обязано быть запросом к репозиторию,
+# который умеет вычислить программа: always | langs: python, go | has_gates: true
+trigger:
+  always: true
+
+# Команда-арбитр под каждый стек. {gate} — папка записи, {dir} — что проверяем.
+# any — переносимая команда без сторонних программ.
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+# Реальный отказ, который эта проверка поймала. «Хорошая практика» не принимается:
+# ссылайся на запись журнала — incidents/README.md
+proof: ЗАПОЛНИ — какой отказ поймала и чего он стоил
+`;
+
+const CHECK_SH_TEMPLATE = `#!/usr/bin/env sh
+# Проверка. Возвращает 0 — чисто, не 0 — брак. В тексте отказа должно быть НАПИСАНО,
+# что сделать: он попадает прямо в контекст агента, и с инструкцией он чинит сам.
+DIR="\${1:-.}"
+. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
+
+# own_samples_filter прячет ТОЛЬКО gates/<имя>/red|green/ — не любую папку с таким именем
+# в проекте. --exclude-dir=red по голому имени однажды спрятал бы настоящую пользовательскую
+# папку red/ (нашли на secrets-not-in-code — kit/docs/ai/... журнал, 2026-09-04).
+HITS=$(grep -rnE $(skip_grep "$DIR") 'ЗАПОЛНИ_ШАБЛОН_ПОИСКА' "$DIR" 2>/dev/null | own_samples_filter "$DIR")
+if [ -n "$HITS" ]; then
+  echo "$HITS"
+  echo "  почини: ЗАПОЛНИ — что именно сделать"
+  exit 1
+fi
+exit 0
+`;
+
+const README_TEMPLATE = (slug) => `# ЗАПОЛНИ — заголовок одной строкой
+
+**Намерение.** Что и почему не должно попадать в код.
+
+**Какой отказ это поймало.** Что сломалось, в каком проекте, чего это стоило. Без этого
+запись не принимается: «это хорошая практика» набирает сотни пунктов, среди которых нельзя
+выбрать.
+
+**Почему машина, а не внимательность.** В какой момент человек это пропускает.
+
+**Готовый аналог.** Есть ли такая проверка в ruff, eslint, semgrep? Если есть — рецепт под этот
+язык обязан брать её, а своя проверка остаётся запасной. Если нет — написать, что именно
+проверено: «не искал» и «нет» — разные утверждения.
+
+**Чего НЕ ловит.** Честно назвать границу. Гейт, о пределах которого умалчивают, опаснее
+отсутствующего: на него понадеются.
+
+**Образцы.** \`red/\` — что здесь нарушено. \`green/\` — то же самое, но правильно.
+`;
+
+export { AGENTS_MD, CLAUDE_MD, MANIFEST_YML, GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE };

package/tool/program.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// aqk — разложить оснастку в проект и вести общий журнал шишек.
+//
+// ЗАЧЕМ ЭТО, А НЕ ПЛАГИН. Плагин Claude Code работает только в Claude Code. Правила, документация
+// и гейты не зависят от того, какой нейросетью пишут код, — значит и способ установки не должен
+// зависеть. `npx` есть везде, где есть Node.
+//
+// ЗАВИСИМОСТЕЙ НЕТ НАМЕРЕННО. Каждая чужая библиотека — лишний узел надёжности и лишняя дверь в
+// цепочке поставок. Инструмент, который ставят одной командой в чужой проект, обязан быть
+// проверяемым глазами за один присест.
+//
+//   npx github:arsen-ask-lx/Agent_Quality_Kit init     разложить комплект в текущий проект
+//   npx github:arsen-ask-lx/Agent_Quality_Kit init --force   перезаписать уже существующие файлы
+//   npx github:arsen-ask-lx/Agent_Quality_Kit note "..."     записать урок в общий журнал
+//   npx github:arsen-ask-lx/Agent_Quality_Kit doctor   проверить, что разложено и чего не хватает
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { c, SELF } from "./lib/core.mjs";
+import { cmdInit, cmdNote, cmdBlob, cmdStart } from "./commands/project.mjs";
+import { cmdDoctor } from "./commands/doctor.mjs";
+import { cmdAdd, cmdNew, cmdRatchet, cmdFind, cmdWhy } from "./commands/gates.mjs";
+
+// Разбор аргументов выполняется только при запуске файла как программы. При импорте —
+// а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
+// Сравниваем по реальному пути: npx ставит `aqk` симлинком, и без realpath запуск через него
+// программой считаться перестал бы.
+let IS_MAIN = false;
+try {
+  IS_MAIN = !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+} catch { IS_MAIN = false; }
+
+if (IS_MAIN) {
+  const [, , cmd, ...rest] = process.argv;
+  switch (cmd) {
+    case "init":
+      await cmdInit(rest);
+      break;
+    case "start":
+      await cmdStart(rest);
+      break;
+    case "doctor":
+      await cmdDoctor();
+      break;
+    case "note":
+      await cmdNote(rest);
+      break;
+    case "add":
+      await cmdAdd(rest);
+      break;
+    case "find":
+      await cmdFind(rest);
+      break;
+    case "why":
+      await cmdWhy(rest);
+      break;
+    case "ratchet":
+      await cmdRatchet(rest);
+      break;
+    case "new":
+      await cmdNew(rest);
+      break;
+    case "blob":
+      await cmdBlob();
+      break;
+    default:
+      console.log(`
+  ${c.bold("aqk")} — оснастка для разработки с агентами
+
+    ${c.bold(`${SELF} init`)}            разложить правила и методички в текущий проект
+    ${c.bold(`${SELF} init --force`)}    перезаписать уже существующие файлы
+  ${c.bold(`${SELF} start`)}           кода ещё нет: сторожа дня 0 и порядок работы
+    ${c.bold(`${SELF} doctor`)}          проверить, что разложено и чего не хватает\n  ${c.bold(`${SELF} doctor --run`)}    ещё и запустить объявленные гейты\n  ${c.bold(`${SELF} add`)} <имя>       поставить гейт из каталога в проект\n  ${c.bold(`${SELF} find`)} "…"       есть ли уже такой гейт — сверка по намерению\n  ${c.bold(`${SELF} why`)} "…"        поймал ошибку — почему её не поймал сторож\n  ${c.bold(`${SELF} ratchet`)} <имя>   храповик: старые нарушения — долг, новые не пускать\n  ${c.bold(`${SELF} new`)} <имя>       заготовка своего гейта для каталога
+    ${c.bold(`${SELF} note`)} "…"        записать урок в общий журнал шишек
+    ${c.bold(`${SELF} blob`)}            собрать методички в один файл GOD_AI.md
+
+  ${c.dim("Без установки:  npx github:arsen-ask-lx/Agent_Quality_Kit init")}
+  `);
+      process.exit(cmd ? 1 : 0);
+  }
+}

package/tool/selfcheck/conditional.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Записи каталога, чьё доказательство не ссылается на журнал шишек.
+#
+# ЗАЧЕМ ОТДЕЛЬНОЙ ПРОВЕРКОЙ. «Это хорошая практика» — самый частый способ, которым каталог
+# набирает пункты, среди которых нельзя выбрать. Условная запись допустима как долг, но их
+# число не должно расти: список под храповиком может только укорачиваться.
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+for GATE in "$ROOT"/kit/gates/*/; do
+  YML="$GATE/gate.yml"
+  [ -f "$YML" ] || continue
+  PROOF="$(sed -n 's/^proof:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1)"
+  case "$PROOF" in
+    *incidents/*) ;;
+    *)
+      # Ключом служит только имя: правка формулировки доказательства не должна читаться
+      # как новое нарушение. Сам текст — отступом, такие строки в ключ не идут.
+      echo "$(basename "$GATE"): доказательство не ссылается на журнал шишек"
+      echo "    сейчас: $PROOF"
+      ;;
+  esac
+done
+exit 0