agent-quality-kit 0.5.0 → 0.7.0

package/tool/selfcheck/lifecycle.mjs

@@ -0,0 +1,29 @@
+// tool/selfcheck/lifecycle.mjs — зрелость записей каталога, одной таблицей.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫМ ФАЙЛОМ, А НЕ КУСКОМ gates.sh. Правило зрелости живёт в `entryLifecycle`
+// (tool/lib/manifest.mjs) и оттуда же читается программой. Повторить его на sh значило бы
+// завести второй источник истины: через месяц приёмка и отчёт расходятся, и про одну и ту же
+// запись машина говорит разное. Здесь — только печать; решение принимает та же функция.
+//
+//   node tool/selfcheck/lifecycle.mjs        → slug|состояние|замена|проблема
+//
+// Код возврата — число записей с проблемой объявления.
+
+import { readCatalog } from "../lib/repo.mjs";
+import { entryLifecycle } from "../lib/manifest.mjs";
+import { L } from "../i18n/index.mjs";
+
+const catalog = await readCatalog();
+const slugs = new Set(catalog.map((r) => r.slug));
+let bad = 0;
+
+for (const rec of catalog) {
+  const { state, supersededBy, problem } = entryLifecycle(rec);
+  // Замена, которой нет в каталоге, — это ответ «а что теперь», ведущий в никуда. Проверяется
+  // здесь, а не в чистой функции: та не знает про остальные записи и не должна знать.
+  const why = problem || (supersededBy && !slugs.has(supersededBy) ? L.lifecycle.unknownReplacement(supersededBy) : "");
+  if (why) bad++;
+  console.log(`${rec.slug}|${state}|${supersededBy || ""}|${why}`);
+}
+
+process.exit(bad);

package/tool/selfcheck/mutation.sh

@@ -19,11 +19,14 @@
 set -uo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 CAT="$ROOT/kit/gates"
-PASS=0; FAIL=0; SKIP=0
+PASS=0; FAIL=0; SKIP=0; UNVERIFIED=0
 
 ok()   { printf '  \033[32m✔\033[0m  %s\n' "$1"; PASS=$((PASS+1)); }
 bad()  { printf '  \033[31m✘\033[0m  %s\n' "$1"; FAIL=$((FAIL+1)); }
 skip() { printf '  \033[2m·\033[0m  %s\n' "$1"; SKIP=$((SKIP+1)); }
+# «Нечем проверить здесь» — не то же, что «переносимого рецепта нет». Первое зависит от машины
+# и лечится установкой; второе — свойство записи. Счётчики разные, чтобы итог не врал о причине.
+unverified() { printf '  \033[33m~\033[0m  %s\n' "$1"; UNVERIFIED=$((UNVERIFIED+1)); }
 
 printf '\n\033[1mtool/selfcheck/mutation.sh\033[0m\n\n'
 [ -d "$CAT" ] || { echo "  каталога гейтов нет"; exit 1; }
@@ -54,6 +57,22 @@ for GATE in "$CAT"/*/; do
   # машине без неё «не проверено» было бы неотличимо от «проверено»: ровно та тишина, против
   # которой всё это написано. Записи без `any` называются вслух, а не пропускаются молча.
   RECIPE="$(sed -n 's/^[[:space:]]*any:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1)"
+  # Запись может назвать нужную ей программу полем `requires`: по первому слову команды этого
+  # не видно, обёртка вокруг готового инструмента начинается с `bash`. Без этой поправки
+  # `test-not-adjusted` на машине без `checkwash` выглядел как «зелёный образец покраснел», хотя
+  # покраснел он от отсутствия инструмента, а не от мутации.
+  NEEDS="$(sed -n 's/^requires:[[:space:]]*\(.*\)$/\1/p' "$YML" | head -1 | tr ',' ' ')"
+  LACK=""
+  for PROG in $NEEDS; do
+    command -v "$PROG" >/dev/null 2>&1 || LACK="${LACK:+$LACK, }$PROG"
+  done
+  # Два разных состояния и два разных счётчика: «переносимого рецепта нет вовсе» и «рецепт есть,
+  # но нужного инструмента нет здесь». Один счётчик на оба означал бы, что итог врёт про причину
+  # — ровно то, что мы не прощаем гейтам. Найдено код-ревью 2026-09-07.
+  if [ -n "$LACK" ]; then
+    unverified "$SLUG: НЕ ПРОВЕРЕНА здесь — нужен «$LACK»"
+    continue
+  fi
   if [ -z "$RECIPE" ]; then
     skip "$SLUG: нет переносимого рецепта — мутации проверять нечем"
     continue
@@ -91,5 +110,6 @@ else
   printf '  \033[31mвердикт поплыл: %s\033[0m' "$FAIL"
 fi
 [ "$SKIP" -gt 0 ] && printf '  \033[2m(без переносимого рецепта: %s)\033[0m' "$SKIP"
+[ "$UNVERIFIED" -gt 0 ] && printf '  \033[33m(не проверено здесь: %s)\033[0m' "$UNVERIFIED"
 printf '\n\n'
 exit "$FAIL"

package/tool/selfcheck/smoke.sh

@@ -164,12 +164,18 @@ done
 # --- 8. храповик: старое пропускает, новое не пускает ------------------------
 # Главный вопрос к храповику: «может ли новый код добавить нарушение и пройти?»
 # Может — значит это советчик, а не гейт.
+# ПОЧЕМУ ПРИМАНКА ИМЕННО gate-not-weakened. У записи должен быть ТОЛЬКО переносимый рецепт:
+# иначе на машине, где стоит ruff или eslint, установка возьмёт рецепт под язык, и проверка
+# станет печатать чужой формат вывода. Так и вышло — прогон был зелёным локально и красным в
+# конвейере ровно потому, что в конвейер добавили ruff: четыре проверки искали в выводе наши
+# «почини: …» и «путь:строка», а получали формат ruff. Прогон, чей исход зависит от того, что
+# случайно стоит на машине, не проверяет ничего.
 R="$WORK/ratchet"; mkdir -p "$R"; cd "$R" || exit 1
 git init -q .
-printf 'def a():\n    print("старое")\n' > old.py
+printf 'x = 1  # noqa\n' > old.py
 node "$CLI" init >/dev/null 2>&1
-node "$CLI" add no-print-in-prod >/dev/null 2>&1
-node "$CLI" ratchet no-print-in-prod >/dev/null 2>&1
+node "$CLI" add gate-not-weakened >/dev/null 2>&1
+node "$CLI" ratchet gate-not-weakened >/dev/null 2>&1
 
 # Судим по вердикту гейта, а не по коду возврата doctor: он ненулевой и по другим
 # причинам (в свежей папке нет .gitignore), и проверка бы врала о храповике.
@@ -179,7 +185,7 @@ case "$OUT" in
   *) ok "храповик пропустил старое нарушение" ;;
 esac
 
-printf 'def b():\n    print("новое")\n' > new.py
+printf 'y = 2  # noqa\n' > new.py
 OUT="$(node "$CLI" doctor --run 2>&1)"
 case "$OUT" in
   *"новых нарушений"*) ok "храповик не пустил новое нарушение" ;;
@@ -189,7 +195,7 @@ esac
 # Второй прогон с тем же новым нарушением обязан краснеть так же. Пока реестр перезаписывался
 # всем текущим списком, одно исправленное нарушение затягивало в долг ВСЕ новые: один красный
 # прогон — и дальше зелено навсегда. «Может ли новый код добавить нарушение и пройти?» — мог.
-printf 'def c():\n    print("ещё одно")\n' > another.py
+printf 'z = 3  # noqa\n' > another.py
 node "$CLI" doctor --run >/dev/null 2>&1
 rm old.py
 OUT="$(node "$CLI" doctor --run 2>&1)"
@@ -199,12 +205,12 @@ case "$OUT2" in
   *) bad "исправление одного нарушения затянуло новые в долг" "второй прогон зелёный" ;;
 esac
 rm -f another.py
-printf 'def a():\n    print("старое")\n' > old.py
-node "$CLI" ratchet no-print-in-prod >/dev/null 2>&1 || true
+printf 'x = 1  # noqa\n' > old.py
+node "$CLI" ratchet gate-not-weakened >/dev/null 2>&1 || true
 
 rm -f new.py old.py
 node "$CLI" doctor --run >/dev/null 2>&1
-if grep -q 'old.py' ratchets/no-print-in-prod.txt; then
+if grep -q 'old.py' ratchets/gate-not-weakened.txt; then
   bad "исправленное осталось в реестре — храповик не затягивается"
 else
   ok "исправленное вычеркнуто из реестра"
@@ -250,27 +256,13 @@ case "$OUT" in
 esac
 cd "$WORK" || exit 1
 
-# --- 8б. проект называет свои каталоги, где печать — интерфейс ---------------
-# Исключение объявляется В МАНИФЕСТЕ и потому видно глазами. Проверяем обе стороны: названный
-# каталог пропускается, все остальные — нет. Исключение, которое прячет всё, бесполезно.
-P="$WORK/printok"; mkdir -p "$P/cli" "$P/src"; cd "$P" || exit 1
-printf 'def a():\n    print("вывод программы")\n' > cli/main.py
-printf 'def b():\n    print("забытая отладка")\n' > src/service.py
-OUT="$(AQK_PRINT_OK_DIRS=cli bash "$ROOT/kit/gates/no-print-in-prod/check.sh" . 2>&1)"
-case "$OUT" in
-  *"cli/main.py"*) bad "названный каталог не исключён" "$OUT" ;;
-  *"src/service.py"*) ok "названный каталог пропущен, остальные проверяются" ;;
-  *) bad "проверка печати не нашла отладку вне названного каталога" "$OUT" ;;
-esac
-cd "$WORK" || exit 1
-
 # --- 9. разбор ошибки: три случая различаются прогоном, а не памятью ---------
 # «Сторожа не было», «сторож был и не сработал», «сторож был и его обошли» — разные починки.
 # Пока их различает человек по памяти, чинят обычно не то. Здесь их различает прогон.
 Y="$WORK/why"; mkdir -p "$Y"; cd "$Y" || exit 1
 git init -q .
 node "$CLI" init >/dev/null 2>&1
-printf 'def a():\n    print("отладка")\n' > x.py
+printf 'q = 1  # noqa\n' > x.py
 
 OUT="$(node "$CLI" why "миграция базы применена задом наперёд" 2>&1)"
 case "$OUT" in
@@ -278,21 +270,21 @@ case "$OUT" in
   *) bad "why не сказал, что сторожа не было" "$OUT" ;;
 esac
 
-OUT="$(node "$CLI" why "отладочная печать уехала в прод" 2>&1)"
+OUT="$(node "$CLI" why "подавление проверки целиком без причины" 2>&1)"
 case "$OUT" in
   *"не поставлен"*) ok "why: запись есть в каталоге, но в проекте не поставлена" ;;
   *) bad "why не отличил «не поставлен» от «не было»" "$OUT" ;;
 esac
 
-node "$CLI" add no-print-in-prod >/dev/null 2>&1
-OUT="$(node "$CLI" why "отладочная печать уехала в прод" 2>&1)"
+node "$CLI" add gate-not-weakened >/dev/null 2>&1
+OUT="$(node "$CLI" why "подавление проверки целиком без причины" 2>&1)"
 case "$OUT" in
   *"его обошли"*) ok "why: сторож стоит и ловит — значит его обошли" ;;
   *) bad "why не отличил «обошли» от «не сработал»" "$OUT" ;;
 esac
 
 rm x.py
-OUT="$(node "$CLI" why "отладочная печать уехала в прод" 2>&1)"
+OUT="$(node "$CLI" why "подавление проверки целиком без причины" 2>&1)"
 case "$OUT" in
   *"этой поломки не видит"*) ok "why: сторож стоит, а поломки не видит" ;;
   *) bad "why не отличил «не сработал» от «обошли»" "$OUT" ;;
@@ -579,11 +571,11 @@ rm -rf "$FBDIR" "$FBPROJ"
 REPDIR="$(mktemp -d)"
 (
   cd "$REPDIR" && git init -q . && mkdir -p src &&
-  printf 'def f():\n    print("debug")\n' > src/a.py &&
+  printf 'a = 1  # noqa\n' > src/a.py &&
   node "$CLI" start > /tmp/aqk-start.log 2>&1
 )
 REP_OUT=$( cd "$REPDIR" && node "$CLI" report 2>&1 ); REP_CODE=$?
-if [ "$REP_CODE" -ne 0 ] && printf '%s' "$REP_OUT" | grep -q '❌ no-print-in-prod'; then
+if [ "$REP_CODE" -ne 0 ] && printf '%s' "$REP_OUT" | grep -q '❌ gate-not-weakened'; then
   ok "report краснеет кодом возврата и называет упавший гейт"
 else
   # Код возврата отчёта не говорит, ПОЧЕМУ он ноль: гейт не сработал, не установился или
@@ -591,7 +583,7 @@ else
   # и «проверка не ловит на этой системе».
   G_LS=$( cd "$REPDIR" && ls gates 2>&1 | tr '\n' ' ' )
   G_DECL=$( cd "$REPDIR" && sed -n '/^gates:/,$p' .aqk.yml 2>/dev/null | grep -cE '^[[:space:]]+[A-Za-z0-9_-]+:' )
-  G_OUT=$( cd "$REPDIR" && bash gates/no-print-in-prod/check.sh . 2>&1 | head -2 ); G_CODE=$?
+  G_OUT=$( cd "$REPDIR" && bash gates/gate-not-weakened/check.sh . 2>&1 | head -2 ); G_CODE=$?
   bad "report не отличает красное от зелёного" "код отчёта $REP_CODE; гейт напрямую: код $G_CODE, вывод «$(printf '%s' "$G_OUT" | tr '\n' ' ')»; в gates/: «$G_LS»; объявлено гейтов: $G_DECL; хвост start: «$(tail -4 /tmp/aqk-start.log 2>/dev/null | tr '\n' ' ')»"
 fi
 if [ -f "$REPDIR/.aqk/report.md" ] && grep -q '^## ' "$REPDIR/.aqk/report.md"; then
@@ -631,11 +623,11 @@ rm -rf "$NOTEDIR" "$NOTEHOME"
 # то есть настройка правкой чужого файла, которую затрёт следующий `aqk add`.
 IGNDIR="$(mktemp -d)"
 mkdir -p "$IGNDIR/third-party/inner" "$IGNDIR/src"
-printf 'def f():\n    print("свой")\n' > "$IGNDIR/src/mine.py"
-printf 'def f():\n    print("чужой")\n' > "$IGNDIR/third-party/inner/theirs.py"
-OUT_BEFORE="$(bash "$ROOT/kit/gates/no-print-in-prod/check.sh" "$IGNDIR" 2>&1)"
+printf 'mine = 1  # noqa\n' > "$IGNDIR/src/mine.py"
+printf 'theirs = 1  # noqa\n' > "$IGNDIR/third-party/inner/theirs.py"
+OUT_BEFORE="$(bash "$ROOT/kit/gates/gate-not-weakened/check.sh" "$IGNDIR" 2>&1)"
 printf '# принесено из другого репозитория\nthird-party/\n' > "$IGNDIR/.aqkignore"
-OUT_AFTER="$(bash "$ROOT/kit/gates/no-print-in-prod/check.sh" "$IGNDIR" 2>&1)"
+OUT_AFTER="$(bash "$ROOT/kit/gates/gate-not-weakened/check.sh" "$IGNDIR" 2>&1)"
 if printf '%s' "$OUT_BEFORE" | grep -q 'theirs.py' &&
    ! printf '%s' "$OUT_AFTER" | grep -q 'theirs.py' &&
    printf '%s' "$OUT_AFTER" | grep -q 'mine.py'; then
@@ -893,17 +885,318 @@ rm -rf "$BDIR2"
 # Воспроизводим без Windows: урезаем PATH до одного node — инструментов не видно так же.
 NRDIR="$(mktemp -d)"; NRBIN="$(mktemp -d)"
 ln -sf "$(command -v node)" "$NRBIN/node"
-( cd "$NRDIR" && git init -q . && mkdir -p src && printf 'def f():\n    print("debug")\n' > src/a.py )
+( cd "$NRDIR" && git init -q . && mkdir -p src && printf 'a = 1  # noqa\n' > src/a.py )
 NR_OUT=$( cd "$NRDIR" && PATH="$NRBIN" node "$CLI" start 2>&1 ); NR_CODE=$?
 NR_GATES=$( ls "$NRDIR/gates" 2>/dev/null | grep -cv '^_' )
 if [ "$NR_CODE" -eq 0 ] && [ "$NR_GATES" -ge 5 ] &&
-   [ -f "$NRDIR/gates/no-print-in-prod/check.sh" ]; then
+   [ -f "$NRDIR/gates/gate-not-weakened/check.sh" ]; then
   ok "start пропускает запись без пригодного инструмента и ставит остальные ($NR_GATES)"
 else
   bad "start бросил установку из-за одной записи" "код $NR_CODE, поставлено $NR_GATES, хвост: $(printf '%s' "$NR_OUT" | tail -2 | tr '\n' ' ')"
 fi
 rm -rf "$NRDIR" "$NRBIN"
 
+# --- 48г. подделка не берёт уровень выше первого -------------------------------
+# ЗАЧЕМ. Ступень AQK-2 называлась «гейты доказаны» и проверяла, что существуют две папки.
+# Проект с гейтами `true` — командой, которая всегда отвечает «ок», — проходил порог AQK-3 и
+# получал зелёный значок в README. Проверено прогоном 2026-09-07: три «гейта», ноль защиты,
+# высший уровень. Это `pytest || true` на уровне всего стандарта.
+FAKEDIR="$(mktemp -d)"
+(
+  cd "$FAKEDIR" && git init -q .
+  mkdir -p gates ratchets incidents && printf '# Журнал\n' > incidents/README.md
+  # Манифест пишется целиком, а не правится python-ом: проверка, которая на машине без python3
+  # молча собирает ДРУГОЙ проект, доказывает не то, что называет. Найдено код-ревью 2026-09-07.
+  {
+    echo 'aqk: "0.6.0"'
+    echo 'entry:'
+    echo '  - AGENTS.md'
+    echo 'rules: .aqk/rules'
+    echo 'gates:'
+    echo '  lint: "true"'
+    echo '  test: "true"'
+    echo '  security: "true"'
+    echo 'samples: gates'
+    echo 'ratchets: ratchets'
+    echo 'lessons: incidents'
+  } > .aqk.yml
+  printf '# Свод\n' > AGENTS.md
+  mkdir -p .aqk/rules && printf '# правила\n' > .aqk/rules/general.md
+)
+FAKE_OUT=$( cd "$FAKEDIR" && node "$CLI" doctor --run --min 3 2>&1 ); FAKE_CODE=$?
+FAKE_PROVE=$( cd "$FAKEDIR" && node "$CLI" prove 2>&1 ); FAKE_PCODE=$?
+# Проверяем ИМЕННО ту ступень, что назначена: без этого `grep 'AQK-1|AQK-3'` совпадал всегда,
+# потому что doctor печатает все четыре строки в любом исходе. Пустая проверка хуже отсутствующей.
+if [ "$FAKE_CODE" -ne 0 ] && [ "$FAKE_PCODE" -ne 0 ] &&
+   printf '%s' "$FAKE_OUT" | grep -qE 'AQK-1\.?$|AQK-1[^0-9]' &&
+   printf '%s' "$FAKE_OUT" | grep -qiE '(НЕ пройден|not passed|not reached)'; then
+  ok "гейт «true» не берёт уровень выше первого"
+else
+  bad "подделка получила уровень" "порог: код $FAKE_CODE, доказательство: код $FAKE_PCODE, хвост: $(printf '%s' "$FAKE_OUT" | tail -2 | tr '\n' ' ')"
+fi
+rm -rf "$FAKEDIR"
+
+# --- 48в. отказ установки называет, что поставить ------------------------------
+# ЗАЧЕМ. Запись, у которой остался только рецепт под язык (`no-print-in-prod`, `swallowed-error`,
+# `dead-code`), на машине без нужного инструмента ставиться не может — и это законно. Но отказ
+# обязан быть действием, а не тупиком: «нет команды ни под python, ни общей» не говорит человеку
+# ничего. Правило «находка без действия закрывает окно, а не дефект» — то же самое, что мы
+# требуем от записей каталога, и к собственной программе оно относится так же.
+# Найдено первым прогоном в чужом репозитории (httpx), 2026-09-07.
+NODIR="$(mktemp -d)"; NOBIN="$(mktemp -d)"
+ln -sf "$(command -v node)" "$NOBIN/node"
+( cd "$NODIR" && git init -q . && mkdir -p src && printf 'x = 1\n' > src/a.py && PATH="$NOBIN" node "$CLI" init >/dev/null 2>&1 )
+NO_OUT=$( cd "$NODIR" && PATH="$NOBIN" node "$CLI" add no-print-in-prod 2>&1 ); NO_CODE=$?
+# Имя инструмента в отказе БЫЛО и до этой проверки — не хватало действия. Требуем оба:
+# «ruff не установлен» — это диагноз, «поставь ruff» — это то, ради чего человек читает.
+if [ "$NO_CODE" -ne 0 ] &&
+   printf '%s' "$NO_OUT" | grep -q 'ruff' &&
+   printf '%s' "$NO_OUT" | grep -qiE '(почини|поставь|install)'; then
+  ok "отказ установки называет инструмент И что с ним делать"
+else
+  bad "отказ установки — тупик" "код $NO_CODE, вывод: $(printf '%s' "$NO_OUT" | tr '\n' ' ' | tail -c 200)"
+fi
+rm -rf "$NODIR" "$NOBIN"
+
+# --- 48б. строгий режим приёмки: «не проверено» становится ошибкой -------------
+# ЗАЧЕМ. «Записи не проверить, нет инструмента» — законное состояние на чужой машине и
+# недопустимое на нашей: там инструменты ставит отдельный шаг, и жёлтая тильда вместо красного
+# означает, что шаг не сработал. Ровно так и было: `pipx install vulture` стоял в конвейере с
+# самого его появления, ставил vulture в каталог вне PATH, и запись dead-code не проверялась
+# конвейером ни разу. Проверяем сам переключатель: на записи с заведомо отсутствующим
+# инструментом обычный прогон зелёный, строгий — красный.
+STPKG="$(mktemp -d)"
+cp -r "$ROOT/tool" "$ROOT/kit" "$ROOT/package.json" "$STPKG/" 2>/dev/null
+# Ломаем рецепт одной записи: программы с таким именем на машине нет ни у кого.
+sed -i.bak 's|^  python: vulture .*|  python: aqk-nesuschestvuyuschiy-instrument {dir}|' \
+  "$STPKG/kit/gates/dead-code/gate.yml" 2>/dev/null
+# Переключатель задаётся явно в ОБЕ стороны. Без этого проверка наследовала AQK_GATES_STRICT
+# из окружения — и в конвейере, где он поднят, «обычный» прогон был бы строгим, а проверка
+# переключателя проверяла бы одно и то же дважды.
+ST_SOFT_OUT=$(AQK_GATES_STRICT=0 bash "$STPKG/tool/selfcheck/gates.sh" 2>&1); ST_SOFT=$?
+ST_HARD_OUT=$(AQK_GATES_STRICT=1 bash "$STPKG/tool/selfcheck/gates.sh" 2>&1); ST_HARD=$?
+if [ "$ST_SOFT" -eq 0 ] && [ "$ST_HARD" -ne 0 ] &&
+   printf '%s' "$ST_HARD_OUT" | grep -q 'строгий режим'; then
+  ok "строгий режим делает «не проверено» ошибкой, обычный — нет"
+else
+  bad "строгий режим приёмки не работает" "обычный: $ST_SOFT, строгий: $ST_HARD"
+fi
+rm -rf "$STPKG"
+
+# --- 49. выведенную запись не ставят, а называют преемника --------------------
+# ЗАЧЕМ. Зрелость записи считается по доказательству, и объявить её нельзя — кроме одного
+# состояния: `deprecated`. Оно объявляется, и весь его смысл в отказе: запись, которую всё ещё
+# можно поставить одной командой, не выведена, а просто помечена. Проверяем сам отказ и то, что
+# папка гейта в проекте НЕ появилась: половина установки хуже, чем её отсутствие.
+#
+# Каталог мутируем в КОПИИ пакета, а не в этом репозитории: проверка, которая правит собственные
+# исходники, однажды упадёт посередине и оставит дерево грязным.
+DEPKG="$(mktemp -d)"; DEPRJ="$(mktemp -d)"
+cp -r "$ROOT/tool" "$ROOT/kit" "$ROOT/package.json" "$DEPKG/" 2>/dev/null
+printf 'lifecycle: deprecated\nsuperseded_by: no-print-in-prod\n' >> "$DEPKG/kit/gates/todo-without-task/gate.yml"
+( cd "$DEPRJ" && git init -q . && printf 'x = 1\n' > a.py && node "$DEPKG/tool/program.mjs" init >/dev/null 2>&1 )
+DE_OUT=$( cd "$DEPRJ" && node "$DEPKG/tool/program.mjs" add todo-without-task 2>&1 ); DE_CODE=$?
+if [ "$DE_CODE" -ne 0 ] &&
+   printf '%s' "$DE_OUT" | grep -q 'no-print-in-prod' &&
+   [ ! -d "$DEPRJ/gates/todo-without-task" ]; then
+  ok "add отказывает в выведенной записи и называет ту, что её заменяет"
+else
+  bad "выведенная запись установилась или преемник не назван" "код $DE_CODE, папка: $([ -d "$DEPRJ/gates/todo-without-task" ] && echo есть || echo нет)"
+fi
+rm -rf "$DEPKG" "$DEPRJ"
+
+# --- 50. --since показывает только то, что внёс диф ---------------------------
+# ЗАЧЕМ. Первый прогон в живом проекте показывает долг за все годы. Стену красного не разбирают
+# — проверку выключают целиком. Проверяем три исхода разом: старый долг молчит, новый краснеет,
+# а гейт, который печатает вердикт без путей, НЕ становится зелёным от того, что его нечем сузить.
+SCDIR="$(mktemp -d)"
+(
+  cd "$SCDIR" && git init -q . && git config user.email t@t && git config user.name t
+  mkdir -p src && printf 'old = 1  # noqa\n' > src/old.py
+  node "$CLI" init >/dev/null 2>&1
+  node "$CLI" add gate-not-weakened >/dev/null 2>&1
+  git add -A && git commit -qm "база" >/dev/null 2>&1
+  printf 'fresh = 1  # noqa\n' > src/fresh.py
+)
+SC_WIDE=$( cd "$SCDIR" && node "$CLI" doctor --run 2>&1 )
+SC_NARROW=$( cd "$SCDIR" && node "$CLI" doctor --run --since HEAD 2>&1 )
+if printf '%s' "$SC_WIDE"   | grep -q 'old.py' &&
+   printf '%s' "$SC_NARROW" | grep -q 'fresh.py' &&
+   ! printf '%s' "$SC_NARROW" | grep -q 'old.py'; then
+  ok "--since прячет старый долг и показывает внесённый дифом"
+else
+  bad "--since сузил не то" "широкий: $(printf '%s' "$SC_WIDE" | grep -c 'py:'), узкий: $(printf '%s' "$SC_NARROW" | grep -c 'py:')"
+fi
+# Несуществующая ссылка обязана быть отказом, а не тихим «сравнили с ничем».
+SC_BAD=$( cd "$SCDIR" && node "$CLI" doctor --run --since net-takoy-vetki 2>&1 ); SC_BADCODE=$?
+if [ "$SC_BADCODE" -ne 0 ] && printf '%s' "$SC_BAD" | grep -qi 'net-takoy-vetki'; then
+  ok "--since с несуществующей ссылкой — отказ, а не тихое сравнение с ничем"
+else
+  bad "--since проглотил неверную ссылку" "код $SC_BADCODE"
+fi
+rm -rf "$SCDIR"
+
+# --- 52. совет по починке не теряется в обрезке --------------------------------
+# ЗАЧЕМ. Все записи каталога печатают «почини: …» последней строкой, а прогон показывал три
+# первые и обрезал остальное — то есть ровно ту строку, ради которой человек смотрит на красное,
+# он не видел никогда. Находка без действия закрывает окно, а не дефект.
+ADIR="$(mktemp -d)"
+(
+  cd "$ADIR" && git init -q . && mkdir -p src
+  for n in a b c d e; do printf '%s = 1  # noqa\n' "$n" > "src/$n.py"; done
+  node "$CLI" init >/dev/null 2>&1
+  node "$CLI" add gate-not-weakened >/dev/null 2>&1
+)
+A_OUT=$( cd "$ADIR" && node "$CLI" doctor --run 2>&1 )
+if printf '%s' "$A_OUT" | grep -qiE '(почини|fix)[[:space:]]*:' &&
+   printf '%s' "$A_OUT" | grep -qE 'py:[0-9]+'; then
+  ok "совет по починке виден при обрезанных находках"
+else
+  bad "совет по починке потерялся" "находок в выводе: $(printf '%s' "$A_OUT" | grep -c 'py:')"
+fi
+rm -rf "$ADIR"
+
+# --- 53. у долга есть цель и срок, и оба с последствием ------------------------
+# ЗАЧЕМ. Реестр, который может только сокращаться, всё равно не знает, когда кончится, — и
+# потому не кончается. Цель и срок без машинного последствия были бы украшением, поэтому
+# проверяем ровно последствия: срок вышел — красное; цель достигнута — сказано вслух.
+RDIR="$(mktemp -d)"
+(
+  cd "$RDIR" && git init -q . && mkdir -p src && printf 'a = 1  # noqa\n' > src/a.py
+  node "$CLI" init >/dev/null 2>&1
+  node "$CLI" add gate-not-weakened >/dev/null 2>&1
+  node "$CLI" ratchet gate-not-weakened >/dev/null 2>&1
+)
+R_REG="$RDIR/ratchets/gate-not-weakened.txt"
+if [ -f "$R_REG" ] && grep -q 'aqk-goal' "$R_REG"; then
+  # Долг снят, новых нарушений нет — зелено.
+  R_BASE=$( cd "$RDIR" && node "$CLI" doctor --run 2>&1 ); R_BASE_CODE=$?
+  # Срок в прошлом — обязано покраснеть без единого нового нарушения.
+  sed -i.bak 's/^# aqk-deadline:.*/# aqk-deadline: 2020-01-01/' "$R_REG"
+  R_LATE=$( cd "$RDIR" && node "$CLI" doctor --run 2>&1 )
+  if printf '%s' "$R_LATE" | grep -qi 'срок\|deadline'; then
+    ok "срок долга вышел — храповик краснеет без новых нарушений"
+  else
+    bad "просроченный долг прошёл молча" "код базового прогона $R_BASE_CODE"
+  fi
+  # Цель заведомо достигнута — храповик обязан сказать, что обёртку пора убрать.
+  sed -i.bak 's/^# aqk-deadline:.*/# aqk-deadline:/; s/^# aqk-goal:.*/# aqk-goal: 99/' "$R_REG"
+  R_DONE=$( cd "$RDIR" && node "$CLI" doctor --run 2>&1 )
+  if printf '%s' "$R_DONE" | grep -qi 'погашен\|paid off'; then
+    ok "цель достигнута — храповик говорит убрать обёртку"
+  else
+    bad "погашенный долг не назван" "$(printf '%s' "$R_DONE" | grep -i ratchet | head -1)"
+  fi
+else
+  bad "реестр долга не создан или без цели" "$R_REG"
+fi
+rm -rf "$RDIR"
+
+# --- 54. упавший гейт не стирает реестр долга ----------------------------------
+# ЗАЧЕМ. Провал без единой разобранной находки — это отказ инструмента, а не чистый прогон.
+# Храповик вычёркивал ВЕСЬ реестр как исправленный, возвращал ноль и — после появления цели —
+# предлагал снять защиту: «долг погашен, убери обёртку». Снятие защиты по итогам прогона,
+# которого не было. Найдено ревью 2026-09-06.
+WDIR="$(mktemp -d)"
+mkdir -p "$WDIR/ratchets"
+printf '# Реестр долга: проба\n# aqk-goal: 0\nsrc/a.py: печать\n' > "$WDIR/ratchets/t.txt"
+W_OUT=$( cd "$WDIR" && bash "$ROOT/kit/ratchet/ratchet.sh" ratchets/t.txt sh -c 'exit 3' 2>&1 ); W_CODE=$?
+W_LEFT=$(grep -c 'src/a.py' "$WDIR/ratchets/t.txt" || true)
+if [ "$W_CODE" -ne 0 ] && [ "$W_LEFT" -eq 1 ] &&
+   ! printf '%s' "$W_OUT" | grep -qi 'погашен'; then
+  ok "упавший гейт не стирает реестр и не предлагает снять защиту"
+else
+  bad "упавший гейт съел реестр" "код $W_CODE, строк долга осталось $W_LEFT"
+fi
+# Директива с опечаткой обязана быть слышной: молчаливо отключённая цель — та же тишина.
+printf '# Реестр\n# aqk-goal: скоро\nsrc/a.py: печать\n' > "$WDIR/ratchets/t.txt"
+W_BAD=$( cd "$WDIR" && bash "$ROOT/kit/ratchet/ratchet.sh" ratchets/t.txt sh -c 'echo "src/a.py: печать"' 2>&1 )
+if printf '%s' "$W_BAD" | grep -qi 'не число'; then
+  ok "опечатка в директиве храповика названа, а не проглочена"
+else
+  bad "нечисловая цель отключилась молча" "$(printf '%s' "$W_BAD" | head -1)"
+fi
+rm -rf "$WDIR"
+
+# --- 55. просроченный долг краснеет и при сужении по дифу ----------------------
+# ЗАЧЕМ. Сообщение храповика про срок называет путь к реестру, а реестра в дифе нет: фильтр по
+# путям отбрасывал единственную строку, находок не оставалось, и гейт печатался зелёным с
+# пометкой «находки вне дифа». То есть `--since` отменял правило SPEC.md §7.6 ровно в том
+# режиме, в котором его и запускают. Найдено ревью 2026-09-06.
+DDIR="$(mktemp -d)"
+(
+  cd "$DDIR" && git init -q . && git config user.email t@t && git config user.name t
+  mkdir -p src && printf 'a = 1  # noqa\n' > src/a.py
+  node "$CLI" init >/dev/null 2>&1
+  node "$CLI" add gate-not-weakened >/dev/null 2>&1
+  node "$CLI" ratchet gate-not-weakened >/dev/null 2>&1
+  sed -i.bak 's/^# aqk-deadline:.*/# aqk-deadline: 2020-01-01/' ratchets/gate-not-weakened.txt
+  git add -A >/dev/null 2>&1 && git commit -qm base >/dev/null 2>&1
+)
+D_WIDE=$( cd "$DDIR" && node "$CLI" doctor --run 2>&1 )
+D_NARROW=$( cd "$DDIR" && node "$CLI" doctor --run --since HEAD 2>&1 )
+if printf '%s' "$D_WIDE" | grep -q 'gate-not-weakened' &&
+   printf '%s' "$D_NARROW" | grep -qE 'gate-not-weakened.*(код|exit)' ; then
+  ok "просроченный долг краснеет и при --since"
+else
+  bad "--since отменил срок долга" "узкий прогон: $(printf '%s' "$D_NARROW" | grep no-print | head -1 | cut -c1-90)"
+fi
+rm -rf "$DDIR"
+
+# --- 56. совещательный гейт показан, но прогон не уронен -----------------------
+# ЗАЧЕМ. Правило вводят в проект, где старый код ему не соответствует. Без третьего пути выбор
+# из двух крайностей: включить и сломать сборку либо не включать вовсе. Проверяем обе стороны:
+# без списка — роняет; со списком — показано и НАЗВАНО, а прогон зелёный. Молчание о
+# совещательном гейте было бы выключенной проверкой, притворяющейся отсутствующей.
+VDIR="$(mktemp -d)"
+(
+  cd "$VDIR" && git init -q . && mkdir -p src && printf 'a = 1  # noqa\n' > src/a.py
+  node "$CLI" init >/dev/null 2>&1
+  node "$CLI" add gate-not-weakened >/dev/null 2>&1
+)
+( cd "$VDIR" && node "$CLI" doctor --run --min 1 >/dev/null 2>&1 ); V_HARD=$?
+printf '\nadvisory:\n  - gate-not-weakened\n' >> "$VDIR/.aqk.yml"
+V_OUT=$( cd "$VDIR" && node "$CLI" doctor --run --min 1 2>&1 ); V_SOFT=$?
+if [ "$V_HARD" -ne 0 ] && [ "$V_SOFT" -eq 0 ] &&
+   printf '%s' "$V_OUT" | grep -qE 'advisory|совещательн' &&
+   printf '%s' "$V_OUT" | grep -q 'src/a.py'; then
+  ok "совещательный гейт показывает находки, называется и не роняет прогон"
+else
+  bad "совещательный режим работает не так" "обычный код $V_HARD, совещательный $V_SOFT"
+fi
+# Опечатка в имени поля обязана быть названа: «advisery:» молча означало бы «совещательных нет»,
+# и правило, которое человек считал введённым, роняло бы сборку.
+sed -i.bak 's/^advisory:/advisery:/' "$VDIR/.aqk.yml"
+V_TYPO=$( cd "$VDIR" && node "$CLI" doctor 2>&1 )
+if printf '%s' "$V_TYPO" | grep -qi 'advisery'; then
+  ok "опечатка в имени поля манифеста названа"
+else
+  bad "опечатка в advisory проглочена" "$(printf '%s' "$V_TYPO" | tail -2 | head -1)"
+fi
+rm -rf "$VDIR"
+
+# --- 81. версия в README и llms.txt та же, что в package.json ---------------
+# Обе строки — инструкция по установке для постороннего: `rev:` для pre-commit и `@vX.Y.Z` для
+# GitHub Action. Устаревшая ставит человеку не тот комплект и молчит об этом: команда проходит,
+# ставится прошлогодняя версия. AGENTS.md требует, чтобы README и llms.txt не расходились, —
+# и без прибора требование не работало: на 2026-09-08 в README стояло v0.6.0, а в llms.txt
+# v0.4.2, отставание на два выпуска. Проверка сравнивает обе с package.json, а не друг с другом:
+# совпасть друг с другом они могут и будучи одинаково устаревшими.
+VERS_BAD=""
+for VF in README.md llms.txt; do
+  [ -f "$ROOT/$VF" ] || continue
+  # Берём только версии AQK — «v1.2.3» в примерах чужих действий (actions/checkout@v4) не наши.
+  for V in $(grep -oE '(rev:[[:space:]]*|Agent_Quality_Kit@)v[0-9]+\.[0-9]+\.[0-9]+' "$ROOT/$VF" \
+             | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | sort -u); do
+    [ "$V" = "v$PKGVER" ] || VERS_BAD="${VERS_BAD:+$VERS_BAD, }$VF: $V"
+  done
+done
+if [ -z "$VERS_BAD" ]; then
+  ok "версия в README и llms.txt совпадает с package.json (v$PKGVER)"
+else
+  bad "версия в документах разошлась с package.json" "package.json: v$PKGVER; найдено — $VERS_BAD"
+fi
+
 # --- итог -------------------------------------------------------------------
 printf '\n'
 if [ "$FAIL" -eq 0 ]; then

package/tool/selfcheck/units-level.mjs

@@ -0,0 +1,60 @@
+// tool/selfcheck/units-level.mjs — проверки уровня и доказательства гейтов.
+//
+// ОТДЕЛЬНЫМ ФАЙЛОМ, а не в units.mjs: тот перерос собственный предел в 500 строк, и поймал
+// это наш же гейт `file-size-limit` на прогоне. Шов по смыслу: здесь всё про то, чем ступень
+// отличается от заявления, — остальное осталось на месте.
+//
+//   node --test tool/selfcheck/units-level.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { commandFor } from "../lib/prove.mjs";
+import { assessLevel } from "../lib/manifest.mjs";
+
+// --- доказательство гейтов ------------------------------------------------------------
+// ЗАЧЕМ. Ступень AQK-2 называлась «гейты доказаны» и проверяла существование двух папок.
+// Проект с тремя гейтами `true` проходил порог AQK-3 — проверено прогоном на пустой папке.
+test("обёртка храповика снимается перед подстановкой каталога", () => {
+  // Иначе доказательство гоняет гейт вместе с реестром долга, и реестр перезаписывается
+  // находками из ОБРАЗЦА. На живом проекте это стёрло бы долг целиком.
+  const cmd = "bash ratchets/_ratchet.sh ratchets/x.txt bash gates/x/check.sh .";
+  assert.equal(commandFor(cmd, "gates/x/red"), "bash gates/x/check.sh gates/x/red");
+});
+
+test("каталог подставляется вместо последнего слова команды", () => {
+  assert.equal(commandFor("bash gates/x/check.sh .", "gates/x/green"), "bash gates/x/check.sh gates/x/green");
+  assert.equal(commandFor("ruff check --select T20 .", "gates/x/red"), "ruff check --select T20 gates/x/red");
+});
+
+test("ступень выше первой не берётся без доказательства", async () => {
+  const man = {
+    aqk: "0.6.0", entry: [], rules: ".", samples: ".", ratchets: ".", lessons: ".",
+    gates: { lint: "true" },
+  };
+  const withoutProof = await assessLevel(man, null);
+  const withFailedProof = await assessLevel(man, { ok: false });
+  const withProof = await assessLevel(man, { ok: true });
+  // Без доказательства ступень не выполнена, но помечена «не проверяли» — это разные состояния.
+  assert.equal(withoutProof.steps[2].ok, false);
+  assert.equal(withoutProof.steps[2].needsProof, true);
+  assert.equal(withFailedProof.steps[2].ok, false);
+  assert.equal(withFailedProof.steps[2].needsProof, false);
+  assert.equal(withProof.steps[2].ok, true);
+});
+
+test("обёртка родного инструмента едет вместе с каталогом образца", () => {
+  // `_native.sh <каталог> <команда…>` прячет пути gates/*/red|green. Оставленный «.» спрятал бы
+  // ровно то, что образец обязан показать, — красный прошёл бы зелёным.
+  const cmd = "bash gates/_native.sh . ruff check --select T20 .";
+  assert.equal(
+    commandFor(cmd, "gates/x/red"),
+    "bash gates/_native.sh gates/x/red ruff check --select T20 gates/x/red"
+  );
+});
+
+test("обе обёртки снимаются вместе", () => {
+  const cmd = "bash ratchets/_ratchet.sh ratchets/x.txt bash gates/_native.sh . ruff check .";
+  assert.equal(
+    commandFor(cmd, "gates/x/green"),
+    "bash gates/_native.sh gates/x/green ruff check gates/x/green"
+  );
+});