agent-quality-kit 0.2.5 → 0.4.0

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,18 @@ 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.
+
 ## Installing a gate
 
 ```bash
@@ -104,6 +159,23 @@ let it grow. The rule applies from the day it is installed — the old code stay
 via `npx` the package is temporary, and tomorrow the command in your manifest would point at
 nothing.
 
+## Third-party code inside the repository
+
+A reference copy, vendored code, generated clients — code that lives here but was not written
+here. The scanning checks will skip it if you add `.aqkignore` in the root: one pattern per line,
+`#` starts a comment, and `*` does not cross `/`.
+
+```
+# brought in from another repository
+third-party/
+vendor/
+*.generated.js
+```
+
+`aqk report` prints the contents of this file as its own section. Hiding things silently is the
+same class as a silent gate: a line here means there is no protection along that path, and will
+not be.
+
 ## The catalogue of promises
 
 `doctor` inspects the repository — languages, existing gates — and shows **only what applies**:

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,18 @@ lessons:  incidents        # где копятся уроки
 aqk doctor --run --min 1   # в конвейере: ошибка, если ниже AQK-1 ИЛИ упал хоть один гейт
 ```
 
+## Значок
+
+```bash
+aqk badge          # прогоняет объявленные гейты и печатает строку — только если все зелёные
+aqk badge --check  # в конвейере: код 1 в тот день, когда значок в README разошёлся с прогоном
+```
+
+Значок, который никто не пересчитывает, — это заявление, а не факт: ровно то, что этот проект
+и заменяет. Поэтому при красном гейте `aqk badge` не печатает ничего, а `aqk badge --check`
+роняет конвейер в тот день, когда README и репозиторий разошлись. Значок в начале этого файла
+проверяется так на каждом пуше.
+
 ## Поставить гейт
 
 ```bash
@@ -101,6 +156,22 @@ aqk why "файл вырос до девяти тысяч строк"
 `add` **копирует проверку в репозиторий**, а не ссылается на пакет: при установке через `npx`
 пакет временный, и завтра команда в манифесте указывала бы в никуда.
 
+## Чужой код в репозитории
+
+Референс, вендоринг, сгенерированные клиенты — код лежит здесь, но написан не здесь. Сканирующие
+проверки по нему не пойдут, если завести `.aqkignore` в корне: по шаблону на строку, `#` —
+комментарий, звёздочка не переходит через `/`.
+
+```
+# принесено из другого репозитория
+third-party/
+vendor/
+*.generated.js
+```
+
+`aqk report` печатает содержимое этого файла отдельным разделом. Скрытое молча — тот же класс,
+что молчащий гейт: строка здесь означает, что защиты по этому пути нет и не будет.
+
 ## Каталог обещаний
 
 `doctor` смотрит на репозиторий — языки, наличие гейтов — и показывает **только применимое**:

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

@@ -21,11 +21,42 @@ migrations"
 # (red-team тесты, что угодно) становился невидим для secrets-not-in-code во всех проектах,
 # куда ставили гейт. Фильтр ниже смотрит на путь целиком: только `gates/<имя>/red|green/`,
 # а не голое имя каталога.
+# Список исключений САМОГО ПРОЕКТА: файл .aqkignore в корне, по шаблону на строку, «#» —
+# комментарий. Нужен для кода, который лежит в репозитории, но написан не здесь: референс,
+# вендоринг, сгенерированные клиенты. Без него единственным способом настройки была правка
+# КОПИИ этого файла в проекте — то есть настройка правкой чужого файла, которую затирает
+# следующий `aqk add`. Найдено первым чужим прогоном.
+#
+# Шаблон — фрагмент пути: `vendor/`, `apps/legacy`, `*.generated.js`. Звёздочка не переходит
+# через «/», как в .gitignore, — иначе «src/*» прятало бы весь проект.
+aqkignore_re() {
+  F="${1:-.}/.aqkignore"
+  [ -f "$F" ] || return 1
+  sed -e 's/#.*$//' -e 's|/*[[:space:]]*$||' -e 's/^[[:space:]]*//' "$F" |
+    grep -v '^$' |
+    sed -e 's/[][(){}.^$+?|\\]/\\&/g' -e 's/\*/[^\/]*/g' |
+    tr '\n' '|' | sed 's/|$//'
+}
+
+# Один фильтр на два дела, и это осознанно: его зовут все семь сканирующих проверок, а их
+# копии уже лежат в чужих проектах. Добавить сюда — значит, что обновление комплекта включает
+# .aqkignore и у тех, кто ставил гейты раньше, без перекопирования их check.sh.
 own_samples_filter() {
-  case "${1:-}" in
-    */red|*/red/|*/green|*/green/) cat ;;
-    *) grep -vE '/gates/[^/]+/(red|green)(/|$)' ;;
+  DIR0="${1:-}"
+  RE="$(aqkignore_re "$DIR0")"
+  case "$DIR0" in
+    # Цель проверки — сам образец: тогда прятать его нельзя, иначе гейт «пройдёт» на красном.
+    */red|*/red/|*/green|*/green/) SAMPLES="cat" ;;
+    # «(^|/)» обязательно: переносимые проверки печатают «./gates/…», а родной инструмент —
+    # «gates/…» без точки. Пока шаблон требовал ведущий «/», образцы прятались только от
+    # первых, и родной рецепт выдавал их как находки.
+    *) SAMPLES="grep -vE (^|/)gates/[^/]+/(red|green)(/|\$)" ;;
   esac
+  if [ -n "$RE" ]; then
+    $SAMPLES | grep -vE "(^|/)($RE)(/|:|\$)"
+  else
+    $SAMPLES
+  fi
 }
 
 # Расширения, где `print` и маркеры долга — конструкции языка, а не текст. Проверять по ним

package/kit/gates/commit-explains-itself/gate.yml

@@ -1,4 +1,5 @@
 intent: коммит несёт мини-отчёт — что сделано и в чём агент не уверен
+intent_en: the commit carries a mini-report — what was done and what the agent is unsure about
 
 trigger:
   always: true

package/kit/gates/complexity-limit/gate.yml

@@ -1,4 +1,5 @@
 intent: функция не вырастает до сложности, в которой её нельзя удержать в голове
+intent_en: a function does not grow past the complexity you can hold in your head
 
 trigger:
   always: true

package/kit/gates/dead-code/gate.yml

@@ -1,4 +1,5 @@
 intent: код, который никто не вызывает, не остаётся в проекте
+intent_en: code nobody calls does not stay in the project
 
 # Только там, где есть готовый инструмент: переносимой проверки здесь быть не может, а
 # показывать запись тем, кому её нечем исполнить, — значит показывать работу, которую

package/kit/gates/deps-are-pinned/gate.yml

@@ -1,4 +1,5 @@
 intent: версии зависимостей закреплены — сборка воспроизводима
+intent_en: dependency versions are pinned — the build is reproducible
 
 trigger:
   has_deps: true

package/kit/gates/duplicate-code/gate.yml

@@ -1,4 +1,5 @@
 intent: один и тот же код не размножается по проекту копиями
+intent_en: the same code does not multiply into copies across the project
 
 trigger:
   files_gt: 20

package/kit/gates/entry-links-exist/gate.yml

@@ -2,6 +2,7 @@
 # Читается программой; всё, что нельзя выполнить, живёт в README.md рядом.
 
 intent: файлы, на которые ссылается точка входа, существуют на диске
+intent_en: files the entry point links to actually exist on disk
 
 # Когда запись показывается человеку. Отсутствие триггера сделало бы её шумом
 # для тех, кого она не касается.

package/kit/gates/file-size-limit/gate.yml

@@ -1,4 +1,5 @@
 intent: файл не вырастает до размера, в котором агент теряется
+intent_en: a file does not grow to a size where the agent gets lost
 
 trigger:
   always: true

package/kit/gates/gate-has-samples/gate.yml

@@ -1,4 +1,5 @@
 intent: у каждого объявленного гейта есть красный и зелёный образец
+intent_en: every declared gate has a red and a green sample
 
 trigger:
   has_gates: true

package/kit/gates/gates-are-runnable/gate.yml

@@ -1,4 +1,5 @@
 intent: каждый гейт, объявленный в манифесте, существует и запускается
+intent_en: every gate declared in the manifest exists and runs
 
 trigger:
   has_gates: true

package/kit/gates/gates-run-in-ci/gate.yml

@@ -1,4 +1,5 @@
 intent: каждый объявленный гейт запускается конвейером, а не только руками
+intent_en: every declared gate runs in the pipeline, not only by hand
 
 # Условия складываются: запись касается только тех, у кого есть и гейты, и конвейер.
 # Нет конвейера — сначала он, а не эта проверка.

package/kit/gates/lesson-has-outcome/gate.yml

@@ -1,4 +1,5 @@
 intent: каждая записанная шишка кончается решением, а не рассказом
+intent_en: every recorded bruise ends in a decision, not a story
 
 # Проверять нечего там, где журнала нет: запись сама скажет об этом и промолчит.
 trigger:

package/kit/gates/no-print-in-prod/check.sh

@@ -14,7 +14,9 @@ DIR="${1:-.}"
 #
 # На настоящем проекте без этого различия 285 находок из 330 пришли из scripts/ и оснастки.
 # Гейт, который на 86% состоит из ложных сработок, выключают целиком.
-TOOLING="--exclude-dir=scripts --exclude-dir=tools --exclude-dir=bin --exclude-dir=examples --exclude-dir=notebooks --exclude-dir=docs --exclude-dir=.claude --exclude-dir=gates --exclude-dir=gates-reference"
+TOOLING="--exclude-dir=scripts --exclude-dir=tools --exclude-dir=bin --exclude-dir=examples --exclude-dir=notebooks --exclude-dir=docs --exclude-dir=.claude --exclude-dir=gates"
+# `gates-reference` отсюда убран: это имя каталога ОДНОГО проекта, зашитое в общий
+# инструмент. Такому место в .aqkignore самого проекта — он появился позже этой строки.
 
 # Проект называет СВОИ каталоги, где печать — интерфейс, а не отладка: у программы командной
 # строки это её исходники целиком. Объявляется в манифесте, рядом с командой, и потому видно

package/kit/gates/no-print-in-prod/gate.yml

@@ -1,4 +1,5 @@
 intent: отладочная печать не доезжает до прод-кода
+intent_en: debug printing does not reach production code
 
 # Запись касается только языков, где есть эта конструкция. В проекте на Go или
 # Rust она не показывается вовсе.

package/kit/gates/secrets-not-in-code/gate.yml

@@ -1,4 +1,5 @@
 intent: ключи, пароли и приватные ключи не попадают в код
+intent_en: keys, passwords and private keys do not end up in the code
 
 trigger:
   always: true

package/kit/gates/swallowed-error/gate.yml

@@ -1,4 +1,5 @@
 intent: ошибка не глушится молча — она обработана и записана либо проброшена
+intent_en: an error is not silently swallowed — it is handled and logged, or re-raised
 
 trigger:
   always: true

package/kit/gates/todo-without-task/gate.yml

@@ -1,4 +1,5 @@
 intent: маркеров «доделать потом» нет в готовом коде — вместо них заведённая задача
+intent_en: "fix later" markers are absent from finished code — a filed task replaces them
 
 trigger:
   always: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "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 };