agent-quality-kit 0.3.0 → 0.4.1

package/README.md

@@ -5,6 +5,7 @@
 [![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
 [![checks](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
 [![MIT licence](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
+[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
 **A standard for whether a repository is ready to have its code written by agents.** Every
 promise the project makes turns into a command with an exit code — held by a machine, not by
@@ -18,10 +19,40 @@ npx agent-quality-kit start     # no code yet: day-zero guards, right away
 npx agent-quality-kit doctor    # code already exists: your level and what to install
 ```
 
+`doctor` only reads: it writes no file and sends nothing anywhere. It is safe to point at
+a repository you have not decided anything about yet.
+
 Nothing to install — `npx` fetches the package itself (230 KB). The bleeding edge straight from
 the repository is `npx github:arsen-ask-lx/Agent_Quality_Kit doctor`, but the first run that way
 stays silent for two or three minutes: it clones the whole repository.
 
+## What this looks like
+
+Someone else's project, three files, nothing configured:
+
+```console
+$ npx agent-quality-kit start        # installs the guards and declares them in the manifest
+$ npx agent-quality-kit doctor --run # runs them
+
+  ✘  secrets-not-in-code   exit 1
+        ./src/api/mailer.py:1:API_KEY = "sk_live_51Hxx…"
+          fix: take the value out of the file, put it in an environment variable
+          and revoke the old key. it cannot be scrubbed from history any more.
+  ✘  swallowed-error       exit 1
+        ./src/api/mailer.py:7: caught and dropped — except Exception:
+          fix: either handle it and log it, or re-raise.
+  ✘  no-print-in-prod      exit 1
+        ./src/web/app.js:3:  console.log("debug", x);
+        ./src/api/mailer.py:8:    print("sent", to)
+  ✘  todo-without-task     exit 1
+        ./src/web/app.js:1:// TODO: rewrite this
+  ✔  file-size-limit · entry-links-exist · complexity-limit
+```
+
+The failure text is written for an agent: it says **what exactly to do**. The exit code is for
+your pipeline. Not one finding inside the kit's own samples: the native tool runs through the
+same filter as the portable check.
+
 **Requirements.** Node 18+ and an `sh` shell — present on macOS, Linux and WSL; Git Bash works on
 Windows. The portable checks are written in `sh` on purpose: it exists everywhere code is built.
 
@@ -35,6 +66,18 @@ without them; if the project already has `ruff`, `eslint` or `vulture`, the entr
 native rule instead — it is more precise. One entry, `dead-code`, does not work at all without a
 real tool and honestly hides itself: you cannot build a call graph with a text search.
 
+## What this is not
+
+| Looks like | The difference |
+|---|---|
+| **a linter** (`ruff`, `eslint`) | AQK does not replace them, it **uses** them: if the tool is on the system, the entry takes its rule — it is more precise. A linter answers "this code is clean"; AQK answers "in this repository, this particular promise is held by a machine, and here is the proof" |
+| **`pre-commit` and hooks** | they run checks. AQK answers a different question: which checks exist here at all, whether they work, and what this project has already been burned by — machine-readably, for an agent, a pipeline and a newcomer |
+| **a checklist or an awesome list** | an entry is accepted only if it names a **real failure** it caught, and its arbiter goes red on the red sample and stays quiet on the green one. A machine checks that, not a reviewer |
+| **a repository scorecard** (compliance badges) | they measure maturity and hand out a grade. The AQK level measures how **machine-readable** your practice is, and says outright that it is not a verdict on the project: a hundred working checks with no manifest is AQK-0 |
+
+In one sentence: **a promise the project makes turns into a command with an exit code, and from
+then on a machine holds it, not somebody's attention.**
+
 ## How it works
 
 The whole standard is one `.aqk.yml` file in the repository root:
@@ -70,6 +113,33 @@ would mean trust in the author rather than a fact.
 aqk doctor --run --min 1   # in CI: fails below AQK-1 OR if any gate failed
 ```
 
+## The badge
+
+```bash
+aqk badge          # runs the declared gates, prints the markdown — only if every one is green
+aqk badge --check  # in CI: exit 1 the day the badge in your README stops matching the run
+```
+
+A badge nobody re-computes is a claim, not a fact — which is the very thing this project
+replaces. So `aqk badge` prints nothing over a red gate, and `aqk badge --check` fails your
+pipeline on the day the README and the repository part ways. The badge at the top of this file
+is checked that way on every push.
+
+## In your pipeline
+
+```yaml
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.4.1
+  with:
+    min: 1   # the build fails below AQK-1, or if any declared gate failed
+```
+
+The action is a thin wrapper around one command and holds no logic of its own — without it,
+the same thing in a single line:
+
+```yaml
+- run: npx agent-quality-kit doctor --run --min 1
+```
+
 ## Installing a gate
 
 ```bash

package/README.ru.md

@@ -5,6 +5,7 @@
 [![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
 [![проверки](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
 [![лицензия MIT](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
+[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
 **Стандарт готовности репозитория к тому, что код в нём пишет агент.** Обещание проекта
 становится командой с кодом возврата — и его держит машина, а не чья-то добрая воля.
@@ -17,10 +18,40 @@ npx agent-quality-kit start     # кода ещё нет: сторожа дня
 npx agent-quality-kit doctor    # код уже есть: уровень и что поставить
 ```
 
+`doctor` только читает: ни одного файла не пишет и никуда ничего не отправляет. Его можно
+направить на репозиторий, о котором ещё ничего не решено.
+
 Ставить ничего не нужно, `npx` скачает пакет сам (230 КБ). Свежая версия прямо из репозитория —
 `npx github:arsen-ask-lx/Agent_Quality_Kit doctor`, но первый запуск такого вида молчит две-три
 минуты: он клонирует репозиторий целиком.
 
+## Что это выглядит так
+
+Чужой проект, три файла, ничего не настроено:
+
+```console
+$ npx agent-quality-kit start        # ставит сторожей и объявляет их в манифесте
+$ npx agent-quality-kit doctor --run # запускает их
+
+  ✘  secrets-not-in-code   код 1
+        ./src/api/mailer.py:1:API_KEY = "sk_live_51Hxx…"
+          почини: убери значение из файла, положи его в переменную окружения
+          и отзови старый ключ. из истории секрет уже не вычистить.
+  ✘  swallowed-error       код 1
+        ./src/api/mailer.py:7: перехват без обработки — except Exception:
+          почини: либо обработай и запиши в лог, либо пробрось дальше.
+  ✘  no-print-in-prod      код 1
+        ./src/web/app.js:3:  console.log("debug", x);
+        ./src/api/mailer.py:8:    print("sent", to)
+  ✘  todo-without-task     код 1
+        ./src/web/app.js:1:// TODO: переписать
+  ✔  file-size-limit · entry-links-exist · complexity-limit
+```
+
+Текст отказа написан для агента: в нём сказано, **что именно сделать**. Код возврата — для
+конвейера. Ни одной находки в самих образцах комплекта: родной инструмент запускается через
+тот же фильтр, что и переносимая проверка.
+
 **Что нужно.** Node 18+ и оболочка `sh` — она есть в macOS, Linux и WSL; на Windows подойдёт
 Git Bash. Переносимые проверки написаны на `sh` намеренно: он есть везде, где собирают код.
 
@@ -34,6 +65,18 @@ Issue» — ничего не постится сама, только текст
 оно точнее. Одна запись, `dead-code`, без готового инструмента не работает вовсе и честно
 скрывается: граф вызовов поиском по тексту не построить.
 
+## Чем это не является
+
+| Похоже на | В чём разница |
+|---|---|
+| **линтер** (`ruff`, `eslint`) | AQK их не заменяет, а **берёт**: если инструмент есть в системе, запись возьмёт его правило — оно точнее. Линтер отвечает «этот код чист», AQK — «в этом репозитории такое-то обещание держит машина, и вот доказательство» |
+| **`pre-commit` и хуки** | они запускают проверки. AQK отвечает на другой вопрос: какие проверки тут вообще есть, работают ли они и на чём здесь уже обжигались — машиночитаемо, для агента, конвейера и нового человека |
+| **чек-лист или awesome-список** | пункт принимается, только если назван **реальный отказ**, который он поймал, и его арбитр краснеет на красном образце и молчит на зелёном. Проверяет это машина, а не рецензент |
+| **скоринг репозитория** (значки соответствия) | они мерят зрелость и дают оценку. Уровень AQK мерит **машиночитаемость** практики и прямо говорит, что это не оценка проекта: сотня работающих проверок без манифеста — это AQK-0 |
+
+Одно предложение: **обещание проекта превращается в команду с кодом возврата, и дальше его
+держит машина, а не чья-то внимательность.**
+
 ## Как устроено
 
 Весь стандарт — файл `.aqk.yml` в корне:
@@ -69,6 +112,33 @@ lessons:  incidents        # где копятся уроки
 aqk doctor --run --min 1   # в конвейере: ошибка, если ниже AQK-1 ИЛИ упал хоть один гейт
 ```
 
+## Значок
+
+```bash
+aqk badge          # прогоняет объявленные гейты и печатает строку — только если все зелёные
+aqk badge --check  # в конвейере: код 1 в тот день, когда значок в README разошёлся с прогоном
+```
+
+Значок, который никто не пересчитывает, — это заявление, а не факт: ровно то, что этот проект
+и заменяет. Поэтому при красном гейте `aqk badge` не печатает ничего, а `aqk badge --check`
+роняет конвейер в тот день, когда README и репозиторий разошлись. Значок в начале этого файла
+проверяется так на каждом пуше.
+
+## В твоём конвейере
+
+```yaml
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.4.1
+  with:
+    min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
+```
+
+Действие — тонкая обёртка над одной командой и своей логики не имеет; без него то же самое
+одной строкой:
+
+```yaml
+- run: npx agent-quality-kit doctor --run --min 1
+```
+
 ## Поставить гейт
 
 ```bash

package/kit/gates/_native.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env sh
+# Запуск РОДНОГО инструмента (ruff, vulture, eslint, jscpd) через тот же фильтр образцов,
+# которым пользуются переносимые проверки.
+#
+# ЗАЧЕМ. Переносимая проверка прячет `gates/<имя>/red|green` — искусственный код, положенный
+# самим комплектом. Родной инструмент о них не знает и выдаёт их как находки: в любом проекте,
+# куда поставили гейты, `ruff --select T20 .` покажет печать из нашего же красного образца.
+# Гейт, который на девять десятых состоит из собственных образцов, читать не будут — его
+# выключат целиком. Ровно так же выключают гейт, где 94% находок пришли из чужого кода.
+#
+# ПОЧЕМУ ФИЛЬТР ВЫВОДА, А НЕ ФЛАГ ИСКЛЮЧЕНИЯ У КАЖДОГО ИНСТРУМЕНТА. Флаг у всех свой
+# (`--exclude`, `--ignore-pattern`, `--ignore`), синтаксис шаблона у всех разный, а главное —
+# статичный флаг нельзя снять, когда проверяют САМ образец: тогда инструмент спрячет ровно то,
+# что должен найти, и запись пройдёт приёмку зелёной на красном образце. Фильтр вывода знает,
+# что за каталог ему дали, и снимает исключение сам — та же логика, что в own_samples_filter.
+#
+#   bash gates/_native.sh <каталог> <команда инструмента…>
+
+DIR="${1:-.}"
+shift || true
+[ "$#" -gt 0 ] || { echo "нечего запускать: не передана команда инструмента"; exit 2; }
+
+. "$(dirname "$0")/_skip.sh" 2>/dev/null || { echo "не найден _skip.sh рядом с _native.sh"; exit 2; }
+
+OUT="$("$@" 2>&1)"; CODE=$?
+LEFT="$(printf '%s' "$OUT" | own_samples_filter "$DIR")"
+
+# Отказ не выдумываем: если инструмент завершился успешно, результат успешен, что бы ни
+# осталось в выводе. Красным делаем только то, что инструмент И счёл отказом, И что пережило
+# фильтр — иначе спрятанный образец превратился бы в неустранимый красный.
+if [ "$CODE" -ne 0 ] && [ -n "$LEFT" ]; then
+  printf '%s\n' "$LEFT"
+  exit "$CODE"
+fi
+exit 0

package/kit/gates/_skip.sh

@@ -47,7 +47,10 @@ own_samples_filter() {
   case "$DIR0" in
     # Цель проверки — сам образец: тогда прятать его нельзя, иначе гейт «пройдёт» на красном.
     */red|*/red/|*/green|*/green/) SAMPLES="cat" ;;
-    *) SAMPLES="grep -vE /gates/[^/]+/(red|green)(/|\$)" ;;
+    # «(^|/)» обязательно: переносимые проверки печатают «./gates/…», а родной инструмент —
+    # «gates/…» без точки. Пока шаблон требовал ведущий «/», образцы прятались только от
+    # первых, и родной рецепт выдавал их как находки.
+    *) SAMPLES="grep -vE (^|/)gates/[^/]+/(red|green)(/|\$)" ;;
   esac
   if [ -n "$RE" ]; then
     $SAMPLES | grep -vE "(^|/)($RE)(/|:|\$)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "AQK — Agent Quality Kit: переносимый комплект, приводящий проект в состояние, пригодное для работы агентов. Правила, механические упоры, накопленные уроки. Одна команда, любой инструмент.",
   "type": "module",
   "bin": {

package/tool/commands/badge.mjs

@@ -0,0 +1,79 @@
+// tool/commands/badge.mjs — значок уровня для чужого README и команда, которая держит его правдой.
+//
+// ЗАЧЕМ. Значок в README — обычно заявление автора: нарисовал один раз, дальше он живёт своей
+// жизнью и через месяц врёт. Здесь он выдаётся только после прогона объявленных гейтов, а
+// `--check` роняет конвейер, когда README разошёлся с фактом. Иначе мы раздавали бы ровно ту
+// самую картинку-обещание, против которой весь стандарт.
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CWD, SELF, REPO_URL, c, exists, die } from "../lib/core.mjs";
+import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { runGates, declaredGates } from "./doctor.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Один разбор на запись и на чтение: значок, который мы печатаем, обязан читаться нами же.
+const BADGE_RE = /img\.shields\.io\/badge\/AQK-(\d)-/;
+
+function badgeMarkdown(level) {
+  const color = level >= 3 ? "2ea44f" : level >= 2 ? "blue" : "orange";
+  return `[![AQK-${level}](https://img.shields.io/badge/AQK-${level}-${color})](${REPO_URL})`;
+}
+
+// Где искать значок: точка входа для агента и README на виду у человека. Список короткий
+// намеренно — обход всего дерева нашёл бы значок в чужой копии и посчитал бы его нашим.
+function placesToCheck(man) {
+  const entry = Array.isArray(man?.entry) ? man.entry.map(String) : [];
+  return [...new Set([...entry, "README.md", "README.ru.md"])];
+}
+
+async function cmdBadge(args = []) {
+  const check = args.includes("--check");
+
+  const man = await readManifest();
+  if (!man) die(`\n  ${L.badge.noManifest(`${SELF} init`)}\n`);
+
+  const { reached } = await assessLevel(man);
+  if (reached < 0) die(`\n  ${L.badge.notReached(`${SELF} doctor`)}\n`);
+
+  // Прогон, а не манифест. Значок при красном гейте — это и есть недоказанное утверждение.
+  const gates = declaredGates(man);
+  if (gates.length) {
+    const run = runGates(man);
+    if (run.failed) {
+      const red = run.results.filter((r) => !r.ok).map((r) => r.name).join(", ");
+      die(`\n  ${L.badge.redGates(run.failed, red)}\n`);
+    }
+  }
+
+  const markdown = badgeMarkdown(reached);
+
+  if (!check) {
+    console.log(`\n${markdown}\n`);
+    console.log(c.dim(`  ${L.badge.hint(gates.length)}`));
+    console.log(c.dim(`  ${L.badge.keepTrue(`${SELF} badge --check`)}\n`));
+    process.exit(0);
+  }
+
+  const places = placesToCheck(man);
+  const found = [];
+  for (const rel of places) {
+    const p = join(CWD, rel);
+    if (!(await exists(p))) continue;
+    const m = BADGE_RE.exec(await readFile(p, "utf8"));
+    if (m) found.push({ rel, level: Number(m[1]) });
+  }
+
+  if (!found.length) die(`\n  ${L.badge.checkMissing(places.join(", "))}\n     ${markdown}\n`);
+
+  const wrong = found.filter((f) => f.level !== reached);
+  if (wrong.length) {
+    const where = wrong.map((f) => `${f.rel} (AQK-${f.level})`).join(", ");
+    die(`\n  ${L.badge.checkMismatch(where, reached)}\n     ${markdown}\n`);
+  }
+
+  console.log(c.green(`\n  ${L.badge.checkOk(reached, found.map((f) => f.rel).join(", "))}\n`));
+  process.exit(0);
+}
+
+export { cmdBadge, badgeMarkdown, BADGE_RE, placesToCheck };

package/tool/commands/gates.mjs

@@ -34,15 +34,30 @@ async function installGate(slug, man, facts) {
 
   // Общий список исключений едет вместе с проверкой: без него она читает окружение и
   // зависимости, и человек получает тысячу чужих нарушений вместо сотни своих.
-  const skipSrc = join(GATES_SRC, "_skip.sh");
-  if (await exists(skipSrc)) await copyFile(skipSrc, join(CWD, PROJECT_GATES, "_skip.sh"));
+  for (const helper of ["_skip.sh", "_native.sh"]) {
+    const from = join(GATES_SRC, helper);
+    if (await exists(from)) await copyFile(from, join(CWD, PROJECT_GATES, helper));
+  }
 
   // Команда под стек проекта, с путями внутри репозитория, а не внутри пакета.
-  const cmd = String(pickRecipe(rec, facts) || "")
+  const picked = String(pickRecipe(rec, facts) || "");
+  let cmd = picked
     .replace(/\{gate\}/g, `${PROJECT_GATES}/${slug}`)
     .replace(/\{dir\}/g, ".");
   if (!cmd) die(L.add.noRecipe(slug, [...facts.langs].join("/") || L.add.thisStack));
 
+  // Родной инструмент не знает про наши образцы и выдаёт их как находки — в любом проекте,
+  // куда поставили гейты. Заворачиваем его в общий фильтр. Переносимая проверка фильтрует
+  // себя сама, её заворачивать незачем.
+  //
+  // Обёртка ставится ЗДЕСЬ, а не в самом рецепте, ровно по одной причине: приёмка каталога
+  // (`gates.sh`) гоняет рецепт по красному образцу напрямую, без обёртки, — и продолжает
+  // видеть то, что должна. Статичный флаг исключения в рецепте спрятал бы образец от
+  // приёмки, и запись прошла бы зелёной на красном.
+  const recipes = rec.recipes && typeof rec.recipes === "object" ? rec.recipes : {};
+  const isPortable = picked === String(recipes.any || "");
+  if (!isPortable) cmd = `bash ${PROJECT_GATES}/_native.sh . ${cmd}`;
+
   const manPath = join(CWD, MANIFEST);
   const { text, why } = manifestWithGate(await readFile(manPath, "utf8"), slug, cmd);
   if (text) await writeFile(manPath, text, "utf8");

package/tool/i18n/en.mjs

@@ -23,6 +23,7 @@ export const en = {
     note: "record a lesson in the shared bruise journal",
     blob: "assemble the guides into a single GOD_AI.md",
     report: "the mandatory report form: what is in place, what is not, what was not read",
+    badge: "a level badge for your README — and a check that it does not lie",
     noInstall: "Without installing:  npx agent-quality-kit init",
     language: "Output language: AQK_LANG=ru (or en), otherwise your system locale",
   },
@@ -355,6 +356,18 @@ export const en = {
     lessons: "# AQK-3 — where lessons accumulate. A path or an address.",
   },
 
+  badge: {
+    noManifest: (cmd) => `No .aqk.yml — there is no level yet. Start with ${cmd}`,
+    notReached: (cmd) => `AQK-0 is not reached — there is nothing to put on a badge. What is missing: ${cmd}`,
+    redGates: (n, names) =>
+      `Red gates: ${n} (${names}). A badge issued over a red gate is the author's claim, not a machine's fact.`,
+    hint: (n) => `Proven by a run. Green gates: ${n}. Paste the line above into your README.`,
+    keepTrue: (cmd) => `To keep the badge from turning into a lie, put this in your pipeline: ${cmd}`,
+    checkMissing: (places) => `No AQK badge in any of: ${places}. This is the line to paste:`,
+    checkMismatch: (where, level) => `The badge lies: ${where}, while the run says AQK-${level}. Replace it with:`,
+    checkOk: (level, where) => `Badge matches the run: AQK-${level} — ${where}`,
+  },
+
   report2: {
     title: "AQK report",
     noManifest: (cmd) => `No .aqk.yml — nothing to report on. Start with ${cmd}`,

package/tool/i18n/ru.mjs

@@ -24,6 +24,7 @@ export const ru = {
     note: "записать урок в общий журнал шишек",
     blob: "собрать методички в один файл GOD_AI.md",
     report: "обязательная форма отчёта: что стоит, что нет, что не прочитано",
+    badge: "значок уровня для README — и проверка, что он не врёт",
     noInstall: "Без установки:  npx agent-quality-kit init",
     language: "Язык вывода: AQK_LANG=en (или ru), иначе по системной локали",
   },
@@ -356,6 +357,18 @@ export const ru = {
     lessons: "# AQK-3 — где копятся уроки. Путь или адрес.",
   },
 
+  badge: {
+    noManifest: (cmd) => `Нет .aqk.yml — уровня ещё нет. Начни с ${cmd}`,
+    notReached: (cmd) => `AQK-0 не достигнут — значок выдавать не за что. Чего не хватает: ${cmd}`,
+    redGates: (n, names) =>
+      `Красных гейтов: ${n} (${names}). Значок при красном гейте — заявление автора, а не факт машины.`,
+    hint: (n) => `Проверено прогоном. Зелёных гейтов: ${n}. Строку выше — в README.`,
+    keepTrue: (cmd) => `Чтобы значок не превратился во враньё, поставь в конвейер: ${cmd}`,
+    checkMissing: (places) => `Значка AQK нет ни в одном из файлов: ${places}. Вставить нужно этот:`,
+    checkMismatch: (where, level) => `Значок врёт: ${where}, а прогон говорит AQK-${level}. Заменить на:`,
+    checkOk: (level, where) => `Значок совпал с прогоном: AQK-${level} — ${where}`,
+  },
+
   report2: {
     title: "Отчёт AQK",
     noManifest: (cmd) => `Нет .aqk.yml — отчитываться не о чем. Начни с ${cmd}`,

package/tool/i18n/templates-en.mjs

@@ -42,6 +42,7 @@ Running them is your job. The human looks at the list of holes and decides which
 | \`aqk find "…"\` | searches by meaning for an existing check | before inventing your own |
 | \`aqk note "…"\` | writes a lesson into the shared journal | the process or an instrument let you down: a check lied, a rule was bypassed |
 | \`aqk report\` | assembles a report from an actual run: what is in place and with which recipe, what is missing, what the kit told you to read | **mandatory** at the end of working with the kit — instead of a summary from memory |
+| \`aqk badge\` | prints a level badge for the README — but only after running the declared gates, and stays silent over a red one; \`--check\` fails the pipeline when the badge stops matching the run | the human asked to show the level, or you are setting up CI |
 
 If there is no \`aqk\` command on the system, the kit was used without installing. Then write
 \`npx agent-quality-kit\` instead of \`aqk\`. Every command prints the invocation that will

package/tool/i18n/templates-ru.mjs

@@ -47,6 +47,7 @@ const AGENTS_MD = `# AGENTS.md
 | \`aqk find "…"\` | ищет по смыслу, есть ли уже такая проверка | прежде чем изобретать свою |
 | \`aqk note "…"\` | пишет урок в общий журнал | процесс или прибор подвели: проверка соврала, правило обошли |
 | \`aqk report\` | собирает прогоном отчёт: что стоит и каким рецептом, чего нет, что комплект велел прочитать | **обязательно** в конце работы с комплектом — вместо пересказа по памяти |
+| \`aqk badge\` | печатает значок уровня для README — но только после прогона объявленных гейтов, а при красном молчит; \`--check\` роняет конвейер, когда значок разошёлся с прогоном | человек попросил показать уровень; настраиваешь конвейер |
 
 Если команды \`aqk\` нет в системе — комплект ставили разово, без установки. Тогда вместо
 \`aqk\` пиши \`npx agent-quality-kit\`. Любая команда сама печатает тот

package/tool/program.mjs

@@ -22,6 +22,7 @@ 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";
 import { cmdReport } from "./commands/report.mjs";
+import { cmdBadge } from "./commands/badge.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -68,6 +69,9 @@ if (IS_MAIN) {
     case "report":
       await cmdReport();
       break;
+    case "badge":
+      await cmdBadge(rest);
+      break;
     default: {
       // Ширина колонки считается, а не подбирается пробелами: строки в двух языках разной
       // длины, и вручную выровненная справка на втором языке разъезжается.
@@ -86,6 +90,7 @@ if (IS_MAIN) {
         [`${SELF} note "…"`, h.note],
         [`${SELF} blob`, h.blob],
         [`${SELF} report`, h.report],
+        [`${SELF} badge`, h.badge],
       ];
       const width = Math.max(...rows.map(([cmdText]) => cmdText.length));
       const lines = rows.map(([cmdText, text]) => `  ${c.bold(cmdText.padEnd(width))}   ${text}`);

package/tool/selfcheck/smoke.sh

@@ -624,6 +624,78 @@ else
 fi
 rm -rf "$IGNDIR"
 
+# --- 37. родной рецепт не ругается на образцы гейтов --------------------------
+# ЗАЧЕМ. Переносимая проверка прячет gates/<имя>/red|green через own_samples_filter, а родной
+# инструмент о них не знает и выдаёт их как находки — в ЛЮБОМ проекте, куда поставили гейты.
+# Всплыло, только когда починка поиска программ в PATH сделала родные рецепты достижимыми:
+# до этого они молча не запускались. Гейт, который на 90% состоит из своих же образцов,
+# выключают целиком — см. журнал, 2026-09-04.
+if command -v vulture >/dev/null 2>&1; then
+  NATDIR="$(mktemp -d)"
+  (
+    cd "$NATDIR" && git init -q . && git config user.email t@t && git config user.name t &&
+    mkdir -p src && printf 'def used():\n    return 1\n\nprint(used())\n' > src/ok.py &&
+    node "$CLI" init >/dev/null 2>&1 && node "$CLI" add dead-code >/dev/null 2>&1
+  )
+  NAT_CMD=$(sed -n 's/^  dead-code: "\(.*\)"$/\1/p' "$NATDIR/.aqk.yml")
+  NAT_OUT=$( cd "$NATDIR" && eval "$NAT_CMD" 2>&1 )
+  if printf '%s' "$NAT_OUT" | grep -q 'gates/'; then
+    bad "родной рецепт выдаёт образцы гейтов как находки" "$(printf '%s' "$NAT_OUT" | head -2)"
+  else
+    ok "родной рецепт не ругается на образцы гейтов"
+  fi
+  rm -rf "$NATDIR"
+else
+  ok "родной рецепт не проверен здесь — нет vulture"
+fi
+
+# --- 38. badge выдаёт значок с тем же уровнем, что и doctor -------------------
+# ЗАЧЕМ. Значок в чужом README — единственное, что делает стандарт видимым за пределами
+# нашего репозитория. Если он покажет уровень, отличный от того, что считает doctor, это
+# ровно то враньё, против которого весь стандарт.
+BDIR="$(mktemp -d)"
+(
+  cd "$BDIR" && git init -q . && git config user.email t@t && git config user.name t &&
+  mkdir -p src && printf 'def f():\n    return 1\n' > src/a.py &&
+  node "$CLI" init >/dev/null 2>&1 && node "$CLI" add file-size-limit >/dev/null 2>&1
+)
+B_OUT=$( cd "$BDIR" && node "$CLI" badge 2>&1 )
+B_LVL=$(printf '%s' "$B_OUT" | sed -n 's|.*img.shields.io/badge/AQK-\([0-9]\)-.*|\1|p' | head -1)
+D_LVL=$( cd "$BDIR" && node "$CLI" doctor 2>&1 | sed -n 's/.*Уровень: AQK-\([0-9]\).*/\1/p' | head -1 )
+if [ -n "$B_LVL" ] && [ "$B_LVL" = "$D_LVL" ]; then
+  ok "badge выдаёт значок с уровнем doctor (AQK-$B_LVL)"
+else
+  bad "badge и doctor разошлись в уровне" "badge=[$B_LVL] doctor=[$D_LVL]"
+fi
+
+# --- 39. badge молчит, когда гейт красный ------------------------------------
+# ЗАЧЕМ. Значок, выданный при красном гейте, — это заявление автора, а не факт машины.
+sed -i.bak 's|^  file-size-limit: .*|&\n  broken: "sh -c '"'"'exit 1'"'"'"|' "$BDIR/.aqk.yml"
+B_RED=$( cd "$BDIR" && node "$CLI" badge 2>&1 ); B_RED_CODE=$?
+# Условие «нет значка» само по себе зелёное и у несуществующей команды — поэтому здесь
+# требуется ещё и названный виновник: иначе проверка не умеет краснеть.
+if [ "$B_RED_CODE" -ne 0 ] && ! printf '%s' "$B_RED" | grep -q 'img.shields.io' &&
+   printf '%s' "$B_RED" | grep -q 'broken'; then
+  ok "badge отказывает при красном гейте"
+else
+  bad "badge выдал значок при красном гейте" "код=$B_RED_CODE $(printf '%s' "$B_RED" | head -2)"
+fi
+mv "$BDIR/.aqk.yml.bak" "$BDIR/.aqk.yml"
+
+# --- 40. badge --check ловит устаревший значок в README ----------------------
+# ЗАЧЕМ. Значок, который никто не пересчитывает, через месяц врёт. Смысл он приобретает
+# только вместе с командой, которая роняет конвейер, когда README разошёлся с фактом.
+printf '# проект\n\n[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://x)\n' > "$BDIR/README.md"
+( cd "$BDIR" && node "$CLI" badge --check >/dev/null 2>&1 ); CHK_LIE=$?
+printf '# проект\n\n[![AQK-%s](https://img.shields.io/badge/AQK-%s-2ea44f)](https://x)\n' "$D_LVL" "$D_LVL" > "$BDIR/README.md"
+( cd "$BDIR" && node "$CLI" badge --check >/dev/null 2>&1 ); CHK_TRUE=$?
+if [ "$CHK_LIE" -ne 0 ] && [ "$CHK_TRUE" -eq 0 ]; then
+  ok "badge --check ловит устаревший значок и пропускает верный"
+else
+  bad "badge --check не различает верный и устаревший значок" "врущий=$CHK_LIE верный=$CHK_TRUE"
+fi
+rm -rf "$BDIR"
+
 # --- итог -------------------------------------------------------------------
 printf '\n'
 if [ "$FAIL" -eq 0 ]; then

package/tool/selfcheck/units.mjs

@@ -14,6 +14,7 @@ import assert from "node:assert/strict";
 import { parseManifest, manifestWithGate } from "../lib/manifest.mjs";
 import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG, whichSync } from "../lib/repo.mjs";
 import { CATALOGS, pickLang, L } from "../i18n/index.mjs";
+import { badgeMarkdown, BADGE_RE, placesToCheck } from "../commands/badge.mjs";
 import { dirname } from "node:path";
 
 const facts = (over = {}) => ({ langs: new Set(), files: 0, ...over });
@@ -178,3 +179,23 @@ test("команда путём, а не именем, ищется на дис
   assert.ok(whichSync(process.execPath));
   assert.equal(whichSync("./нет-такого-файла.sh"), null);
 });
+
+// --- значок уровня ------------------------------------------------------------
+// ЗАЧЕМ. Значок печатает одна функция, а читает его обратно другое выражение — в том же
+// файле, но независимо. Разойдись они, и `badge --check` перестал бы узнавать собственный
+// значок: конвейер молча зеленел бы на любом README. Тишина, неотличимая от успеха.
+test("значок читается тем же разбором, каким печатается", () => {
+  for (const level of [0, 1, 2, 3]) {
+    const found = BADGE_RE.exec(badgeMarkdown(level));
+    assert.ok(found, `значок AQK-${level} не разобрался`);
+    assert.equal(Number(found[1]), level);
+  }
+});
+
+test("значок ищется в точке входа и в README, без повторов", () => {
+  const places = placesToCheck({ entry: ["AGENTS.md", "README.md"] });
+  assert.ok(places.includes("AGENTS.md"));
+  assert.ok(places.includes("README.md"));
+  assert.equal(places.filter((p) => p === "README.md").length, 1);
+  assert.ok(placesToCheck({}).includes("README.md"), "без entry README всё равно проверяется");
+});