agent-quality-kit 0.8.0 → 0.9.0

package/tool/selfcheck/smoke.sh

@@ -1437,6 +1437,355 @@ else
 fi
 rm -rf "$GENP"
 
+# --- 95. covers: запись закрыта другим арбитром, но только объявленным ---------
+# Просьба первого чужого пользователя, названная им первой: у него complexity-limit,
+# no-print-in-prod и swallowed-error держит biome, а doctor каждый прогон печатал «применимо,
+# но не поставлено: 5» — неправду. Неправда в СОБСТВЕННОМ выводе дороже всех прочих: весь
+# стандарт стоит на том, что вывод не врёт. Но поле не признание на слово: гейт, который
+# «закрывает», обязан быть объявлен в gates:, иначе covers становится способом объявить защиту,
+# которой нет. Проверяются оба конца сразу.
+COVP="$(mktemp -d)"
+( cd "$COVP" && git init -q . && mkdir -p src rules &&
+  printf 'const x=1;\n' > src/a.ts && printf '# вход\n' > AGENTS.md &&
+  printf 'правило\n' > rules/r.md && printf '.x\n' > .gitignore &&
+  printf 'aqk: 1\nentry: [AGENTS.md]\nrules: rules\ngates:\n  lint: "true"\ncovers:\n  lint: [no-print-in-prod, swallowed-error]\n  biome: [duplicate-code]\n' > .aqk.yml ) >/dev/null 2>&1
+COV=$( cd "$COVP" && AQK_LANG=ru node "$CLI" doctor 2>&1 )
+if printf '%s' "$COV" | grep -q "закрыто другим арбитром 2" &&
+   printf '%s' "$COV" | grep -q "covers называет гейт, которого нет" &&
+   printf '%s' "$COV" | grep -q "biome" &&
+   ! printf '%s' "$COV" | grep -q "неизвестное поле"; then
+  ok "covers снимает запись с долга — и только когда закрывающий гейт объявлен"
+else
+  bad "covers посчитан неверно" "$(printf '%s' "$COV" | grep -E 'Итого|covers' | head -3)"
+fi
+rm -rf "$COVP"
+
+# --- 96. язык вывода — настройка проекта, а не машины -------------------------
+# Просьба первого чужого пользователя: «язык берётся из LC_ALL/LANG, а на Windows их просто нет:
+# русский проект получает английский вывод». Проверяются оба конца порядка сразу: манифест
+# сильнее локали, но переменная окружения сильнее манифеста — иначе у человека, набравшего
+# AQK_LANG=en руками, не остаётся способа получить английский.
+LNGP="$(mktemp -d)"
+( cd "$LNGP" && git init -q . && printf '# вход\n' > AGENTS.md &&
+  printf 'aqk: 1\nlang: ru\nentry: [AGENTS.md]\n' > .aqk.yml ) >/dev/null 2>&1
+BY_MAN=$( cd "$LNGP" && env -u AQK_LANG LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 node "$CLI" context 2>&1 | head -1 )
+BY_ENV=$( cd "$LNGP" && AQK_LANG=en node "$CLI" context 2>&1 | head -1 )
+if printf '%s' "$BY_MAN" | grep -q "состояние этого репозитория" &&
+   printf '%s' "$BY_ENV" | grep -q "the state of this repository"; then
+  ok "язык берётся из манифеста поверх локали, а переменная окружения — поверх манифеста"
+else
+  bad "порядок выбора языка нарушен" "по манифесту: $BY_MAN | по окружению: $BY_ENV"
+fi
+rm -rf "$LNGP"
+
+# --- 97. совет про браузер у агента — только тому, кому он нужен --------------
+# Решение владельца 2026-09-08: инструмент, дающий агенту браузер, надо рекомендовать. Но совет,
+# показанный не тому, стоит доверия всем остальным советам — та же норма, что у записей каталога.
+# Проверяются все три конца: интерфейс есть и сервера нет → совет; интерфейса нет → тишина;
+# сервер уже стоит → тишина.
+BRWP="$(mktemp -d)"
+( cd "$BRWP" && git init -q . && mkdir -p src && printf 'body{color:#fff}\n' > src/a.css &&
+  printf 'export const A=1\n' > src/a.tsx && printf '# вход\n' > AGENTS.md ) >/dev/null 2>&1
+WITH_UI=$( cd "$BRWP" && AQK_LANG=ru node "$CLI" doctor 2>&1 )
+( cd "$BRWP" && printf '{"mcpServers":{"b":{"command":"npx","args":["-y","chrome-devtools-mcp@1.9.0"]}}}\n' > .mcp.json )
+WITH_SRV=$( cd "$BRWP" && AQK_LANG=ru node "$CLI" doctor 2>&1 )
+NOUIP="$(mktemp -d)"
+( cd "$NOUIP" && git init -q . && printf 'print(1)\n' > a.py && printf '# вход\n' > AGENTS.md ) >/dev/null 2>&1
+NO_UI=$( cd "$NOUIP" && AQK_LANG=ru node "$CLI" doctor 2>&1 )
+if printf '%s' "$WITH_UI" | grep -q "нет браузера" &&
+   ! printf '%s' "$WITH_SRV" | grep -q "нет браузера" &&
+   ! printf '%s' "$NO_UI" | grep -q "нет браузера"; then
+  ok "совет про браузер даётся проекту с интерфейсом и молчит, когда сервер уже есть"
+else
+  bad "совет про браузер показан не тому" "с ui: $(printf '%s' "$WITH_UI" | grep -c 'нет браузера'), с сервером: $(printf '%s' "$WITH_SRV" | grep -c 'нет браузера'), без ui: $(printf '%s' "$NO_UI" | grep -c 'нет браузера')"
+fi
+rm -rf "$BRWP" "$NOUIP"
+
+# --- 98. заявка covers сверяется, а не принимается на слово -------------------
+# Поле covers завели утром того же дня, и тогда же честно записали: оно снимает запись с долга
+# ПО СЛОВУ человека. К вечеру это перестало быть теорией: запуск на настоящем ruff.toml из живого
+# проекта показал девятнадцать групп правил в extend-select и НЕ пойманный print() — группы T20
+# среди них нет. Заявка «no-print-in-prod держит наш lint» была бы ложной, а запись ушла бы из
+# долга. Поле, снимающее неправду из вывода, само стало бы способом её произвести.
+CVUP="$(mktemp -d)"
+( cd "$CVUP" && git init -q . && printf 'x=1\n' > a.py && printf '# вход\n' > AGENTS.md &&
+  printf 'aqk: 1\nentry: [AGENTS.md]\ngates:\n  lint: "ruff check ."\ncovers:\n  lint: [no-print-in-prod]\n' > .aqk.yml ) >/dev/null 2>&1
+( cd "$CVUP" && printf 'extend-select = ["I","B","UP","SIM"]\n' > ruff.toml )
+WITHOUT=$( cd "$CVUP" && AQK_LANG=ru node "$CLI" doctor 2>&1 )
+( cd "$CVUP" && printf 'extend-select = ["I","B","UP","SIM","T20"]\n' > ruff.toml )
+WITHT20=$( cd "$CVUP" && AQK_LANG=ru node "$CLI" doctor 2>&1 )
+if printf '%s' "$WITHOUT" | grep -q "заявка не подтверждена" &&
+   printf '%s' "$WITHOUT" | grep -q "T20" &&
+   ! printf '%s' "$WITHT20" | grep -q "заявка не подтверждена"; then
+  ok "covers сверяется с кодами правил: без T20 говорит вслух, с T20 молчит"
+else
+  bad "сверка заявки covers не работает" "без T20: $(printf '%s' "$WITHOUT" | grep -c 'не подтверждена'), с T20: $(printf '%s' "$WITHT20" | grep -c 'не подтверждена')"
+fi
+rm -rf "$CVUP"
+
+# --- 99. краткий режим: присутствие видно, совет не надоедает -----------------
+# Хук pre-commit молчит на успехе — это его умолчание. Комплект, который всё держит, для
+# человека неотличим от невставленного: «скачал и че дальше» — дословная жалоба владельца.
+# Это ровно тот порок, против которого написан комплект, только у нас самих.
+# Проверяются три вещи сразу: строка есть всегда; совет приходит один раз, а не на каждый
+# прогон; переменная его выключает.
+BRFP="$(mktemp -d)"
+( cd "$BRFP" && git init -q . && printf 'x=1\n' > a.py && printf '# вход\n' > AGENTS.md &&
+  printf '.x\n' > .gitignore && mkdir -p rules .aqk/docs && printf 'п\n' > rules/r.md &&
+  printf 'aqk: 1\nentry: [AGENTS.md]\nrules: rules\ngates:\n  ok: "true"\n' > .aqk.yml ) >/dev/null 2>&1
+B1=$( cd "$BRFP" && AQK_LANG=ru node "$CLI" doctor --run --min 1 --brief 2>&1 ); B1C=$?
+B2=$( cd "$BRFP" && AQK_LANG=ru node "$CLI" doctor --run --min 1 --brief 2>&1 )
+rm -f "$BRFP/.aqk/advice-shown"
+B3=$( cd "$BRFP" && AQK_ADVICE=0 AQK_LANG=ru node "$CLI" doctor --run --min 1 --brief 2>&1 )
+if [ "$B1C" -eq 0 ] &&
+   printf '%s' "$B1" | grep -qE "^(❖ )?AQK  держит" &&
+   printf '%s' "$B1" | grep -q "поставить:" &&
+   printf '%s' "$B2" | grep -qE "^(❖ )?AQK  держит" &&
+   ! printf '%s' "$B2" | grep -q "поставить:" &&
+   ! printf '%s' "$B3" | grep -q "поставить:" &&
+   [ "$(printf '%s\n' "$B2" | wc -l)" -le 2 ]; then
+  ok "краткий режим: строка есть всегда, совет один раз в сутки и выключается"
+else
+  bad "краткий режим ведёт себя не так" "первый: $(printf '%s' "$B1" | head -1) · второй строк: $(printf '%s\n' "$B2" | wc -l)"
+fi
+rm -rf "$BRFP"
+
+# --- 100. в awk-программах гейтов нет повторителей {n} ------------------------
+# Часть сборок mawk не понимает повторители в регулярках. Условие с {4} не
+# совпадает НИКОГДА, и гейт молча выходит с нулём на собственном красном образце: ровно тот
+# отказ, против которого написан комплект. Поймано сборкой docker-образа 2026-09-08 — на хосте
+# gawk, и ни один прогон не краснел. Проверка статическая и потому дешёвая; настоящий прогон
+# под старым awk делает задание `image` в конвейере — там образ, в котором дефект и нашёлся.
+# ВАЖНО, ЧТО ИМЕННО СБОРКА: mawk 1.3.4 20240123 (ubuntu-latest, эта машина) повторители
+# ПОНИМАЕТ, mawk 1.3.4 20200120 (node:22-slim) — нет. Замерено 2026-09-09. Поэтому «прогнать
+# под mawk» ничего не значит без указания, под каким,
+# а прочитать исходники — можем.
+AWKBAD=""
+for G in "$ROOT"/kit/gates/*/check.sh "$ROOT"/kit/gates/_skip.sh; do
+  [ -f "$G" ] || continue
+  # Только строки внутри awk-программ; комментарии оболочки (#) не считаем.
+  # Только регулярки AWK: `t ~ /…/` и образец-действие `/…/ {`. Шаблоны для grep, лежащие в
+  # переменных оболочки, сюда не попадают намеренно — GNU grep и busybox grep повторители
+  # понимают оба, и краснеть на них значит краснеть на нормальном укладе.
+  HIT=$(sed 's/^[[:space:]]*#.*$//' "$G" | grep -nE '(~[[:space:]]*/|^[[:space:]]*/)' \
+        | grep -E '\{[0-9]+(,[0-9]*)?\}' | head -2)
+  [ -n "$HIT" ] && AWKBAD="${AWKBAD:+$AWKBAD; }$(basename "$(dirname "$G")"): $(printf '%s' "$HIT" | head -1 | cut -c1-60)"
+done
+if [ -z "$AWKBAD" ]; then
+  ok "в проверках каталога нет повторителей {n} — они не работают под mawk"
+else
+  bad "повторитель {n} в проверке: под mawk она молчит" "$AWKBAD"
+fi
+
+# --- 101. проверка версии: раз в сутки, не в конвейере, молча при отказе ------
+# До этой строки комплект не делал ни одного исходящего запроса. Раз делает — обязан делать
+# ровно то, что о нём написано: спрашивать реестр не чаще раза в сутки и НЕ спрашивать в
+# конвейере. Само наличие новой версии здесь не проверяется — она зависит от реестра, а
+# проверка, зависящая от чужого сервера, краснеет по чужой воле. Сравнение версий проверено
+# модульно; здесь — то, что вокруг него.
+UPDP="$(mktemp -d)"
+( cd "$UPDP" && git init -q . && printf 'x=1\n' > a.py && printf '# вход\n' > AGENTS.md &&
+  printf '.x\n' > .gitignore && mkdir -p rules .aqk/docs && printf 'п\n' > rules/r.md &&
+  printf 'aqk: 1\nentry: [AGENTS.md]\nrules: rules\ngates:\n  ok: "true"\n' > .aqk.yml ) >/dev/null 2>&1
+( cd "$UPDP" && env -u CI -u GITHUB_ACTIONS AQK_LANG=ru node "$CLI" doctor --run --min 1 --brief ) >/dev/null 2>&1
+ASKED=$([ -f "$UPDP/.aqk/update-checked" ] && echo да || echo нет)
+rm -f "$UPDP/.aqk/update-checked"
+( cd "$UPDP" && CI=true AQK_LANG=ru node "$CLI" doctor --run --min 1 --brief ) >/dev/null 2>&1
+IN_CI=$([ -f "$UPDP/.aqk/update-checked" ] && echo да || echo нет)
+rm -f "$UPDP/.aqk/update-checked"
+( cd "$UPDP" && env -u CI AQK_UPDATE=0 AQK_LANG=ru node "$CLI" doctor --run --min 1 --brief ) >/dev/null 2>&1
+OFF=$([ -f "$UPDP/.aqk/update-checked" ] && echo да || echo нет)
+# «нет сети» — тоже допустимый исход первого случая: молчание при отказе и есть требование.
+if [ "$IN_CI" = "нет" ] && [ "$OFF" = "нет" ]; then
+  ok "версия спрашивается вне конвейера ($ASKED), не спрашивается в конвейере и при AQK_UPDATE=0"
+else
+  bad "проверка версии спрашивает там, где не должна" "вне CI: $ASKED, в CI: $IN_CI, выключено: $OFF"
+fi
+rm -rf "$UPDP"
+
+# --- 102. строка манифеста, которую разбор не понял, называется вслух ---------
+# Найдено случайно 2026-09-09: подсадили падающий гейт с именем «плохой», чтобы посмотреть на
+# вывод, — прогон вышел с НУЛЁМ. Гейт не упал: его не существовало. Разбор берёт имена только
+# латиницей, а строку, не подошедшую под это, выбрасывал без единого слова. Человек видит
+# проверку в файле, а её нет — наш класс в чистом виде, и хуже опечатки в имени поля: ту мы
+# называем с 2026-09-06, а эту не называли вовсе.
+UNPP="$(mktemp -d)"
+( cd "$UNPP" && git init -q . && printf '# вход\n' > AGENTS.md &&
+  printf 'aqk: 1\nentry: [AGENTS.md]\nlang: ru\ngates:\n  ok: "true"\n  плохой: "false"\n' > .aqk.yml ) >/dev/null 2>&1
+UNP=$( cd "$UNPP" && node "$CLI" doctor 2>&1 )
+( cd "$UNPP" && printf 'aqk: 1\nentry: [AGENTS.md]\nlang: ru\ngates:\n  ok: "true"\n  bad: "false"\n' > .aqk.yml )
+OKM=$( cd "$UNPP" && node "$CLI" doctor 2>&1 )
+if printf '%s' "$UNP" | grep -q "НЕ ДЕЙСТВУЕТ" &&
+   printf '%s' "$UNP" | grep -q "строка 6" &&
+   ! printf '%s' "$OKM" | grep -q "НЕ ДЕЙСТВУЕТ"; then
+  ok "непонятая строка манифеста называется с номером, понятая — молчит"
+else
+  bad "потерянная строка манифеста не названа" "$(printf '%s' "$UNP" | grep -c 'НЕ ДЕЙСТВУЕТ') на кириллице, $(printf '%s' "$OKM" | grep -c 'НЕ ДЕЙСТВУЕТ') на латинице"
+fi
+rm -rf "$UNPP"
+
+# --- 103. vitals: отказ роняет, выбор и незнание — нет ------------------------
+# `doctor` смотрит на репозиторий, `prove` — на гейты, `context` — на состояние. На саму
+# обвязку не смотрел никто: стоят ли инструменты объявленных гейтов, прописан ли хук в
+# .git/hooks НА САМОМ ДЕЛЕ. Раньше это выяснялось красным гейтом посреди коммита.
+# Первая версия ставила крест хуку, которого нет, — и на нашем же репозитории вышло два креста
+# за сознательное решение (pre-commit локально не ставим, гоняем в CI). Команда, которая кричит
+# «сломано» про выбор, перестаёт читаться вместе с настоящими отказами. Проверяются оба конца.
+VITP="$(mktemp -d)"
+( cd "$VITP" && git init -q . && printf '# вход\n' > AGENTS.md &&
+  printf 'aqk: 1\nentry: [AGENTS.md]\nlang: ru\ngates:\n  ok: "true"\n' > .aqk.yml ) >/dev/null 2>&1
+VOK=$( cd "$VITP" && AQK_LANG=ru node "$CLI" vitals 2>&1 ); VOK_C=$?
+( cd "$VITP" && printf 'aqk: 1\nentry: [AGENTS.md]\nlang: ru\ngates:\n  lint: "инструментакоторогонет ."\n' > .aqk.yml )
+VBAD=$( cd "$VITP" && AQK_LANG=ru node "$CLI" vitals 2>&1 ); VBAD_C=$?
+if [ "$VOK_C" -eq 0 ] && [ "$VBAD_C" -eq 1 ] &&
+   printf '%s' "$VBAD" | grep -q "НЕ НАЙДЕНЫ" &&
+   printf '%s' "$VOK" | grep -q "хук pre-commit"; then
+  ok "vitals: пропавший инструмент роняет прогон, отсутствие хука — нет"
+else
+  bad "vitals путает отказ с выбором" "исправный код $VOK_C, сломанный код $VBAD_C"
+fi
+rm -rf "$VITP"
+
+# --- 106. совещательный гейт назван всегда и не роняет прогон никогда ---------
+# Два отказа, найденные 2026-09-09 сверкой документации с кодом. ПЕРВЫЙ: зелёный совещательный
+# печатался обычной галочкой — гейт, который уронить сборку НЕ МОЖЕТ, по выводу неотличим от
+# того, который может, и список `advisory:` был виден только в день, когда он покраснел. Ровно
+# та тишина, против которой написан стандарт, только про сам прибор. ВТОРОЙ: при `--since` гейт,
+# чей вывод не содержит путей, шёл через ветку «сузить нечем» с безусловным failed++ — то есть
+# совещательный ронял прогон. Проверено сравнением с кодом до починки: было 1, стало 0.
+# Команда гейта — ФАЙЛ, а не строка с `;`. На windows `spawnSync(shell: true)` запускает
+# cmd.exe, а не sh: там `echo x; exit 1` печатается целиком и выходит с НУЛЁМ. Первая версия
+# этой проверки так и провалилась в конвейере на windows — фикстура, а не код. Заодно урок про
+# сам тест: утверждение «зелёный помечен» искало подстроку «совещательный», которая есть и в
+# пометке КРАСНОГО совещательного, — то есть проходило бы и при полном отсутствии починки.
+# Теперь ищется текст, который бывает только на зелёной строке.
+ADVP="$(mktemp -d)"
+(
+  cd "$ADVP" && git init -q . && git config user.email a@b && git config user.name a
+  printf '# вход\n' > AGENTS.md && mkdir -p r && printf 'x\n' > r/a.md
+  printf '#!/bin/sh\necho "вердикт без путей"\nexit 1\n' > noscope.sh
+  printf '#!/bin/sh\nexit 0\n' > quiet.sh
+  printf 'aqk: 1\nentry: [AGENTS.md]\nrules: r\ngates:\n  adv: "bash quiet.sh"\nadvisory:\n  - adv\n' > .aqk.yml
+  git add -A && git commit -qm "Сделано: основа. Не уверен: ничего"
+) >/dev/null 2>&1
+ADVBASE=$( cd "$ADVP" && git rev-parse --abbrev-ref HEAD )
+( cd "$ADVP" && git checkout -qb feat && printf 'y\n' > r/b.md && git add -A &&
+  git commit -qm "Сделано: файл. Не уверен: ничего" ) >/dev/null 2>&1
+ADVGREEN=$( cd "$ADVP" && AQK_LANG=ru node "$CLI" doctor --run --min 1 2>&1 )
+( cd "$ADVP" && printf 'aqk: 1\nentry: [AGENTS.md]\nrules: r\ngates:\n  adv: "bash noscope.sh"\nadvisory:\n  - adv\n' > .aqk.yml )
+( cd "$ADVP" && node "$CLI" doctor --run --min 1 --since "$ADVBASE" >/dev/null 2>&1 ); ADV_C=$?
+( cd "$ADVP" && printf 'aqk: 1\nentry: [AGENTS.md]\nrules: r\ngates:\n  adv: "bash noscope.sh"\n' > .aqk.yml )
+( cd "$ADVP" && node "$CLI" doctor --run --min 1 --since "$ADVBASE" >/dev/null 2>&1 ); BLOCK_C=$?
+if printf '%s' "$ADVGREEN" | grep -q "уронить прогон не может" && [ "$ADV_C" -eq 0 ] && [ "$BLOCK_C" -eq 1 ]; then
+  ok "совещательный назван и на зелёном, и не роняет прогон даже когда сузить нечем"
+else
+  bad "совещательный гейт неотличим или роняет прогон" "зелёный помечен: $(printf '%s' "$ADVGREEN" | grep -c 'уронить прогон не может'), код совещательного $ADV_C, код блокирующего $BLOCK_C"
+fi
+rm -rf "$ADVP"
+
+# --- 107. prove пропускает запись без её программы, а не обвиняет её ----------
+# ТО ЖЕ, ЧТО НАШЁЛ ВТОРОЙ ПОЛЬЗОВАТЕЛЬ, ТОЛЬКО ДРУГОЙ ДВЕРЬЮ. Переносимый рецепт бывает обёрткой
+# вокруг готового инструмента: первое слово команды тогда `bash`, и по нему не видно, чего не
+# хватает. Без программы обёртка краснеет на ОБОИХ образцах, и prove объявлял исправный гейт
+# сломанным — «краснеет на исправном коде». От prove зависят ступень AQK-2 и значок, то есть
+# отсутствие чужой программы отбирало у проекта уровень. Обвинение вместо диагноза.
+# Приёмка (gates.sh) и мутационная проверка поле `requires` читают давно; prove — не читал.
+# Проверено 2026-09-09 на своём же репозитории: не стояли slopcheck и zizmor, prove дал два
+# обвинения и код 1. Проверяются ОБА конца: без поля — обвинение и код 1, с полем — пропуск и 0.
+PRVP="$(mktemp -d)"
+(
+  cd "$PRVP" && git init -q . && printf '# вход\n' > AGENTS.md && mkdir -p r s/wrap/red s/wrap/green
+  printf 'x\n' > s/wrap/red/a.txt && printf 'x\n' > s/wrap/green/a.txt
+  # Обёртка вокруг программы, которой на машине нет: краснеет на обоих образцах.
+  printf '#!/bin/sh\nпрограммыкоторойнет "$1" || exit 2\n' > wrap.sh
+  # Настоящая проверка: prove требует, чтобы хоть один гейт был ДОКАЗАН, иначе проект,
+  # у которого всё недоказуемо, получал бы уровень ни за что. Команда обязана кончаться
+  # каталогом — иначе подставлять образец некуда, и гейт сам станет недоказуемым.
+  printf '#!/bin/sh\ngrep -rq НЕЛЬЗЯ "$1" && exit 1\nexit 0\n' > real.sh
+  printf 'aqk: 1\nentry: [AGENTS.md]\nrules: r\nsamples: s\ngates:\n  wrap: "sh wrap.sh ."\n  real: "sh real.sh ."\n' > .aqk.yml
+) >/dev/null 2>&1
+# Второй гейт обязан быть доказуемым: prove требует хотя бы одного доказанного.
+( cd "$PRVP" && mkdir -p s/real/red s/real/green &&
+  printf 'НЕЛЬЗЯ\n' > s/real/red/a.txt && printf 'можно\n' > s/real/green/a.txt )
+PRV_NOREQ=$( cd "$PRVP" && AQK_LANG=ru node "$CLI" prove 2>&1 ); PRV_NOREQ_C=$?
+( cd "$PRVP" && printf 'intent: обёртка\nrequires: программыкоторойнет\nrecipes:\n  any: "sh wrap.sh {dir}"\n' > s/wrap/gate.yml )
+PRV_REQ=$( cd "$PRVP" && AQK_LANG=ru node "$CLI" prove 2>&1 ); PRV_REQ_C=$?
+# Тот же вопрос задаёт `vitals`, и до 2026-09-09 он отвечал на него иначе: печатал «все
+# инструменты на месте», потому что смотрел только на ПЕРВОЕ СЛОВО команды — `sh`, который есть
+# всегда. Две команды об одном репозитории говорили разное; читатель верил той, что зеленее.
+PRV_VIT=$( cd "$PRVP" && AQK_LANG=ru node "$CLI" vitals 2>&1 )
+if [ "$PRV_NOREQ_C" -ne 0 ] && [ "$PRV_REQ_C" -eq 0 ] &&
+   printf '%s' "$PRV_REQ" | grep -q "НЕ ПРОВЕРЕНА здесь" &&
+   printf '%s' "$PRV_VIT" | grep -q "программыкоторойнет"; then
+  ok "prove и vitals одинаково видят программу из requires: пропуск, а не обвинение"
+else
+  bad "prove путает «нечем проверить» со «сломан», либо vitals её не видит" \
+      "без поля код $PRV_NOREQ_C, с полем код $PRV_REQ_C, vitals назвал: $(printf '%s' "$PRV_VIT" | grep -c 'программыкоторойнет')"
+fi
+rm -rf "$PRVP"
+
+# --- 104. опись в AGENTS.md покрывает все исходники ---------------------------
+# AGENTS.md — первое, что читает агент, и раздел «Где что лежит» для него карта. Карта,
+# отставшая от дерева, хуже её отсутствия: агент уверен, что видел всё. Проверено 2026-09-09 —
+# в описи не было восьми файлов из четырнадцати добавленных за неделю (`brief.mjs`, `banner.mjs`
+# и шесть `units-*.mjs`), и заметить это можно было только сверкой руками. Тот же класс, что
+# «гейт объявлен и не существует»: расхождение молчит.
+MISSING=""
+for F in "$ROOT"/tool/lib/*.mjs "$ROOT"/tool/commands/*.mjs "$ROOT"/tool/selfcheck/*; do
+  B=$(basename "$F")
+  grep -qF "$B" "$ROOT/AGENTS.md" || MISSING="$MISSING $B"
+done
+if [ -z "$MISSING" ]; then
+  ok "опись «Где что лежит» называет каждый исходник"
+else
+  bad "AGENTS.md не называет файлы" "$MISSING"
+fi
+
+# --- 105. два README не расходятся структурно --------------------------------
+# AGENTS.md требует, чтобы README и его перевод не расходились, и до сегодня требование не
+# работало: на 2026-09-09 в английском было 23 раздела, в русском 22 — «Первый прогон на
+# настоящем проекте» отсутствовал целиком, а «Как ввести правило» стояло в другом разделе.
+# Читатель одного языка получал инструкцию, которой у читателя другого не было. Сверяется
+# ПОСЛЕДОВАТЕЛЬНОСТЬ уровней, а не тексты: заголовки на разных языках сравнивать нельзя.
+# Строки внутри ``` не считаются: в примере .aqkignore есть строка, начинающаяся с #.
+levels() {
+  awk '/^```/ { inf = !inf; next } !inf && /^#/ { sub(/[^#].*/, ""); print }' "$1"
+}
+if [ "$(levels "$ROOT/README.md")" = "$(levels "$ROOT/README.ru.md")" ]; then
+  ok "README.md и README.ru.md несут одни и те же разделы ($(levels "$ROOT/README.md" | wc -l | tr -d ' '))"
+else
+  bad "README и перевод разошлись структурно" \
+      "англ. $(levels "$ROOT/README.md" | wc -l | tr -d ' '), рус. $(levels "$ROOT/README.ru.md" | wc -l | tr -d ' ')"
+fi
+
+# --- 108. init доходит до конца, когда дом недоступен для записи ---------------
+# НАШЁЛ КОНВЕЙЕР, А НЕ ПРОГОН. Одноразовая пометка «просьбу про звезду уже показывали» пишется
+# в $HOME/.config/aqk. В контейнере, запущенном `--user 1001:127`, у этого uid нет записи в
+# /etc/passwd, homedir() даёт «/», и mkdir падает с EACCES на «/.config» — роняя ВЕСЬ init.
+# То есть любой, кто набрал команду из нашей же документации по docker, получал падение вместо
+# установки. Локально не воспроизводилось по случайности: uid разработчика 1000 совпадает с
+# пользователем `node` в образе, у которого дом есть; на раннере uid 1001 — не совпадает.
+# Удобство не имеет права ронять работу команды. Молчать о нём тоже нельзя — это swallowed-error.
+HOMEP="$(mktemp -d)"; HOMEH="$(mktemp -d)"
+chmod 500 "$HOMEH" 2>/dev/null
+# На windows chmod прав не отнимает: там эта проверка ничего не проверяет и говорит об этом,
+# а не зеленеет молча. Тот же приём, что «НЕ ПРОВЕРЕНА здесь» в приёмке каталога.
+if ( : > "$HOMEH/проба" ) 2>/dev/null; then
+  rm -f "$HOMEH/проба"
+  ok "init при недоступном доме — НЕ ПРОВЕРЕНА здесь: chmod прав не отнимает"
+else
+  ( cd "$HOMEP" && git init -q . ) >/dev/null 2>&1
+  HOMEOUT=$( cd "$HOMEP" && HOME="$HOMEH" AQK_LANG=ru node "$CLI" init 2>&1 ); HOME_C=$?
+  if [ "$HOME_C" -eq 0 ] && [ -f "$HOMEP/.aqk.yml" ] &&
+     printf '%s' "$HOMEOUT" | grep -q "запомнить не удалось"; then
+    ok "init доходит до конца при недоступном доме и называет, чего не смог"
+  else
+    bad "init падает или молчит, когда дом недоступен для записи" \
+        "код $HOME_C, манифест $([ -f "$HOMEP/.aqk.yml" ] && echo есть || echo нет)"
+  fi
+fi
+chmod 700 "$HOMEH" 2>/dev/null; rm -rf "$HOMEP" "$HOMEH"
+
 # --- итог -------------------------------------------------------------------
 printf '\n'
 if [ "$FAIL" -eq 0 ]; then
@@ -1445,5 +1794,5 @@ else
   printf '  \033[31mпровалено: %s из %s\033[0m\n\n' "$FAIL" "$((PASS + FAIL))"
 fi
 
-printf '  \033[2mне покрыто: содержание документов, установка с GitHub через npx\033[0m\n\n'
+printf '  \033[2mне покрыто: СОДЕРЖАНИЕ документов (сверяется опись и структура, не текст),\n  установка с GitHub через npx\033[0m\n\n'
 exit "$FAIL"

package/tool/selfcheck/units-banner.mjs

@@ -0,0 +1,65 @@
+// tool/selfcheck/units-banner.mjs — заставка: первая и почти единственная встреча с человеком.
+//
+// ЗАЧЕМ ПРОВЕРЯТЬ КАРТИНКУ. Не ради красоты. Заставка шириной больше окна разъезжается в кашу
+// и портит именно то впечатление, ради которого её и добавили. А в терминале без UTF-8 графика
+// Брайлем превращается в вопросительные знаки — и человек решает, что инструмент сломан.
+//
+//   node --test tool/selfcheck/units-banner.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { banner, BANNER_WIDTH } from "../lib/banner.mjs";
+
+test("заставка влезает в узкое окно", () => {
+  const w = Math.max(...banner().split("\n").map((l) => [...l].length));
+  assert.ok(w <= 40, `ширина ${w}, а бывают окна и в 40 колонок`);
+  assert.equal(w, BANNER_WIDTH, "объявленная ширина обязана совпадать с настоящей");
+});
+
+// Версии в заставке НЕТ намеренно — решение владельца: выпуски частые, и номер в картинке
+// устаревает быстрее всего остального. За версией есть `--version`, она печатается отдельно.
+test("версии в заставке нет", () => {
+  assert.doesNotMatch(banner(), /\d+\.\d+\.\d+/);
+});
+
+// Терминал без UTF-8 превратит Брайль в мусор. Тогда честнее короткая строка, чем каша,
+// по которой человек решит, что инструмент сломан.
+test("без UTF-8 вместо графики короткая строка", () => {
+  const plain = banner({ LANG: "C" });
+  assert.doesNotMatch(plain, /[⣿█]/);
+  assert.match(plain, /aqk/i);
+});
+
+test("отказ от графики уважается переменной", () => {
+  assert.doesNotMatch(banner({ LANG: "ru_RU.UTF-8", AQK_NO_ART: "1" }), /[⣿█]/);
+});
+
+// Кошка центрируется по ВИДИМОЙ части, а не по началу строки: пустой Брайль `⠀` занимает место
+// и ничего не рисует. При равных отступах рисунок выглядел сдвинутым вправо на целый знак —
+// поймано глазом владельца, а не прогоном, и потому закреплено здесь.
+test("кошка стоит по центру надписи", () => {
+  const lines = banner().split("\n");
+  const visible = (l, blanks) => {
+    const a = [...l];
+    let lo = -1, hi = -1;
+    a.forEach((ch, i) => { if (!blanks.has(ch)) { if (lo < 0) lo = i; hi = i; } });
+    return lo < 0 ? null : (lo + hi) / 2;
+  };
+  const catMid = Math.max(...lines.slice(0, 6).map((l) => visible(l, new Set([" ", "⠀"]))));
+  const artMid = Math.max(...lines.slice(7, 13).map((l) => visible(l, new Set([" "]))));
+  assert.ok(Math.abs(catMid - artMid) <= 1, `центры разошлись: кошка ${catMid}, буквы ${artMid}`);
+});
+
+// Подпись центрируется по видимому центру букв, а не по краю строки. Отступ, подобранный на
+// глаз, держится до первой правки рисунка — посчитанный переживёт её.
+test("подпись стоит по центру надписи", () => {
+  const lines = banner().split("\n");
+  const mid = (l, blanks) => {
+    const a = [...l];
+    let lo = -1, hi = -1;
+    a.forEach((ch, i) => { if (!blanks.has(ch)) { if (lo < 0) lo = i; hi = i; } });
+    return lo < 0 ? null : (lo + hi) / 2;
+  };
+  const letters = Math.max(...lines.slice(7, 13).map((l) => mid(l, new Set([" "]))));
+  const tag = mid(lines[lines.length - 1], new Set([" "]));
+  assert.ok(Math.abs(letters - tag) <= 1, `подпись не по центру: буквы ${letters}, подпись ${tag}`);
+});

package/tool/selfcheck/units-brief.mjs

@@ -0,0 +1,97 @@
+// tool/selfcheck/units-brief.mjs — короткая строка присутствия и её ограничитель.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ. Владелец: «скачал и че дальше, не понятно, работает он вообще или нет».
+// Хук pre-commit молчит на успехе — это его умолчание, проверено по документации: вывод
+// показывается только при провале. То есть комплект, который всё держит, для человека
+// неотличим от невставленного. Это ровно наш собственный порок: тишина неотличима от успеха.
+//
+//   node --test tool/selfcheck/units-brief.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { briefLine, adviceDue, pickAdvice, updateNotice, updateWanted } from "../lib/brief.mjs";
+import { CATALOGS } from "../i18n/index.mjs";
+
+const T = CATALOGS.ru;
+
+// Строка присутствия печатается ВСЕГДА, в том числе когда всё хорошо: именно тогда она и нужна.
+test("строка присутствия несёт числа и уровень", () => {
+  const s = briefLine({ held: 12, todo: 3, level: 2, red: [] }, T);
+  assert.match(s, /12/);
+  assert.match(s, /3/);
+  assert.match(s, /AQK-2/);
+});
+
+// Красное называется первым и поимённо: человек должен видеть, что чинить, не листая вывод.
+test("упавшие гейты названы в самой строке", () => {
+  const s = briefLine({ held: 12, todo: 0, level: 1, red: ["file-size-limit", "duplicate-code"] }, T);
+  assert.match(s, /file-size-limit/);
+  assert.match(s, /duplicate-code/);
+});
+
+// Уровень может быть не вычислен — и тогда так и говорим, а не подставляем ноль.
+test("невычисленный уровень не выдумывается", () => {
+  const s = briefLine({ held: 0, todo: 5, level: -1, red: [] }, T);
+  assert.doesNotMatch(s, /AQK--1|AQK-0/);
+});
+
+// --- ограничитель совета -----------------------------------------------------
+// Совет на КАЖДОМ коммите превращается в шум, а шум пролистывают вместе с настоящими
+// находками. Раз в сутки — это заметно и не мешает.
+test("совет не повторяется чаще раза в сутки", () => {
+  const now = Date.parse("2026-09-08T20:00:00Z");
+  assert.equal(adviceDue(null, now), true, "первый раз показывается");
+  assert.equal(adviceDue("2026-09-08T19:00:00Z", now), false, "час назад — рано");
+  assert.equal(adviceDue("2026-09-07T19:00:00Z", now), true, "сутки прошли");
+});
+
+test("испорченная отметка времени не мешает показать совет", () => {
+  assert.equal(adviceDue("не дата", Date.parse("2026-09-08T20:00:00Z")), true);
+});
+
+// --- выбор совета ------------------------------------------------------------
+// Один совет за раз, а не список: список читается как «у вас всё плохо» и не помогает выбрать.
+test("советуется одна запись, самая первая из непоставленных", () => {
+  const a = pickAdvice([{ slug: "secrets-not-in-code" }, { slug: "file-size-limit" }]);
+  assert.equal(a.slug, "secrets-not-in-code");
+});
+
+test("советовать нечего — совета нет, а не пустая строка", () => {
+  assert.equal(pickAdvice([]), null);
+});
+
+// --- уведомление об обновлении -----------------------------------------------
+// Владелец: «выпускаем часто, никто не будет обновлять — скачают старую версию, а мы там уже
+// ошибки исправили». Верно: у pre-commit версия закреплена в rev:, у GitHub Action в теге,
+// и сами они не двигаются. У `npx` без версии проблемы нет — он всегда берёт свежее.
+//
+// АВТООБНОВЛЕНИЯ НЕТ НАМЕРЕННО. В этот же день выпущена запись, краснеющая на `@latest`:
+// «версия не закреплена, завтра приедет другая». Инструмент, который сам себя подменяет, стоя
+// на воротах коммита, делал бы ровно то, что мы запрещаем другим.
+test("новая версия называется, старая не тревожит", () => {
+  assert.ok(updateNotice("0.8.0", "0.9.0", {}, T));
+  assert.equal(updateNotice("0.9.0", "0.9.0", {}, T), null);
+  assert.equal(updateNotice("0.9.0", "0.8.0", {}, T), null, "откат назад — не обновление");
+});
+
+// Сравнение по числам, а не по строкам: «0.10.0» строкой меньше «0.9.0», и уведомление
+// пропало бы ровно на десятом выпуске — тихо и надолго.
+test("версии сравниваются числами, а не как текст", () => {
+  assert.ok(updateNotice("0.9.0", "0.10.0", {}, T));
+  assert.equal(updateNotice("0.10.0", "0.9.0", {}, T), null);
+  assert.ok(updateNotice("1.2.9", "1.10.0", {}, T));
+});
+
+// Способ обновления зависит от того, как поставлено: у pre-commit это autoupdate, а не npm.
+// Совет «сделай npm i -g» человеку, у которого хук, — это совет мимо, и он его не выполнит.
+test("совет об обновлении соответствует способу установки", () => {
+  assert.match(updateNotice("0.8.0", "0.9.0", { PRE_COMMIT: "1" }, T), /autoupdate/);
+  assert.doesNotMatch(updateNotice("0.8.0", "0.9.0", {}, T), /autoupdate/);
+});
+
+// В конвейере уведомление — шум и лишний запрос: там версия закреплена сознательно, и человека,
+// который бы его прочитал, у экрана нет.
+test("в конвейере и при отказе проверять не спрашиваем вовсе", () => {
+  assert.equal(updateWanted({ CI: "true" }), false);
+  assert.equal(updateWanted({ AQK_UPDATE: "0" }), false);
+  assert.equal(updateWanted({}), true);
+});

package/tool/selfcheck/units-context.mjs

@@ -163,7 +163,9 @@ test("чужие настройки переживают установку ху
 // не отстал от диспетчера: команда, добавленная в switch и забытая в списке, роняет её.
 test("карта команд не отстаёт от диспетчера", async () => {
   const src = await readFile(new URL("../program.mjs", import.meta.url), "utf8");
-  const dispatched = [...src.matchAll(/^\s{4}case "([a-z-]+)":/gm)].map((m) => m[1]);
+  // Флаговые формы (`--version`, `-v`) в карту не входят: карта перечисляет КОМАНДЫ, а флаг —
+  // второе имя той же команды. Требовать их здесь значило бы дублировать строку справки.
+  const dispatched = [...src.matchAll(/^\s{4}case "([a-z][a-z-]*)":/gm)].map((m) => m[1]);
   assert.ok(dispatched.length >= 10, `в диспетчере найдено ${dispatched.length} команд — разбор сломался`);
   const listed = new Set(commandRows(CATALOGS.ru).map((r) => r.name));
   const missing = dispatched.filter((n) => !listed.has(n));