agent-quality-kit 0.7.0 → 0.8.0

package/tool/lib/scope.mjs

@@ -33,6 +33,15 @@ const ANSI = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*[a-zA-Z]", "g");
 // принималась бы за находку и отбрасывалась.
 const CANDIDATE = /[\w.@+-]+(?:\/[\w.@+-]+)*\.[A-Za-z][A-Za-z0-9]{0,9}/g;
 
+// Все пути, названные в тексте. Тот же разбор, что при сужении: цвет снимается, вид пути
+// нормализуется. Вынесено отдельно, потому что покрытие спрашивает у вывода обратное:
+// не «попадает ли находка в диф», а «назвал ли гейт этот файл».
+function pathsIn(text) {
+  const out = new Set();
+  for (const m of String(text).replace(ANSI, "").matchAll(CANDIDATE)) out.add(normPath(m[0]));
+  return out;
+}
+
 function inScope(candidate, files) {
   const c = normPath(candidate);
   if (files.has(c)) return true;
@@ -128,4 +137,4 @@ function changedFiles(ref, cwd) {
   );
 }
 
-export { scopeOutput, splitAdvice, changedFiles };
+export { scopeOutput, splitAdvice, changedFiles, pathsIn, normPath };

package/tool/lib/templates.mjs

@@ -28,6 +28,7 @@ const MANIFEST_YML = [
   "",
   d.rules,
   "rules: .aqk/rules",
+  "docs: .aqk/docs",
   "gates:",
   ...d.gates,
   "",

package/tool/program.mjs

@@ -16,14 +16,16 @@
 
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { c, SELF } from "./lib/core.mjs";
+import { c, SELF, commandRows } from "./lib/core.mjs";
 import { L } from "./i18n/index.mjs";
 import { cmdInit, cmdNote, cmdBlob, cmdStart } from "./commands/project.mjs";
 import { cmdDoctor } from "./commands/doctor.mjs";
 import { cmdAdd, cmdNew, cmdRatchet, cmdFind, cmdWhy } from "./commands/gates.mjs";
 import { cmdReport } from "./commands/report.mjs";
+import { cmdLearn } from "./commands/learn.mjs";
 import { cmdBadge } from "./commands/badge.mjs";
 import { cmdProve } from "./commands/prove.mjs";
+import { cmdContext } from "./commands/context.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -67,46 +69,40 @@ if (IS_MAIN) {
     case "blob":
       await cmdBlob();
       break;
+    // Читает локальную переписку — поэтому только в терминал и всегда с кодом 0. Подробности
+    // и замер, на котором стоит отбор, — в шапке tool/commands/learn.mjs.
+    case "learn":
+      await cmdLearn();
+      break;
+
     case "report":
       await cmdReport();
       break;
     case "prove":
       await cmdProve();
       break;
+    // Печатает состояние репозитория для КОНТЕКСТА агента, а не для человека. Зовётся хуком
+    // SessionStart, поэтому ничего не запускает и всегда выходит с нулём: хук, роняющий запуск
+    // агента из-за неготового проекта, отключат в тот же день, и не станет ни хука, ни блока.
+    case "context":
+      await cmdContext(rest);
+      break;
     case "badge":
       await cmdBadge(rest);
       break;
     default: {
       // Ширина колонки считается, а не подбирается пробелами: строки в двух языках разной
       // длины, и вручную выровненная справка на втором языке разъезжается.
-      const h = L.help;
-      const rows = [
-        [`${SELF} init`, h.init],
-        [`${SELF} init --force`, h.initForce],
-        [`${SELF} start`, h.start],
-        [`${SELF} doctor`, h.doctor],
-        [`${SELF} doctor --run`, h.doctorRun],
-        [`${SELF} doctor --run --since main`, h.doctorSince],
-        [`${SELF} prove`, h.prove],
-        [`${SELF} add ${h.name}`, h.add],
-        [`${SELF} find "…"`, h.find],
-        [`${SELF} why "…"`, h.why],
-        [`${SELF} ratchet ${h.name}`, h.ratchet],
-        [`${SELF} new ${h.name}`, h.new],
-        [`${SELF} note "…"`, h.note],
-        [`${SELF} blob`, h.blob],
-        [`${SELF} report`, h.report],
-        [`${SELF} badge`, h.badge],
-      ];
+      const rows = commandRows(L).map((r) => [`${SELF} ${r.name}${r.args ? " " + r.args : ""}`, r.text]);
       const width = Math.max(...rows.map(([cmdText]) => cmdText.length));
       const lines = rows.map(([cmdText, text]) => `  ${c.bold(cmdText.padEnd(width))}   ${text}`);
       console.log(`
-  ${c.bold("aqk")} — ${h.tagline}
+  ${c.bold("aqk")} — ${L.help.tagline}
 
 ${lines.join("\n")}
 
-  ${c.dim(h.noInstall)}
-  ${c.dim(h.language)}
+  ${c.dim(L.help.noInstall)}
+  ${c.dim(L.help.language)}
   `);
       process.exit(cmd ? 1 : 0);
     }

package/tool/selfcheck/smoke.sh

@@ -25,6 +25,13 @@ FAIL=0
 ok()   { printf '  \033[32m✔\033[0m  %s\n' "$1"; PASS=$((PASS + 1)); }
 bad()  { printf '  \033[31m✘\033[0m  %s\n' "$1"; printf '      %s\n' "${2:-}"; FAIL=$((FAIL + 1)); }
 
+# Node на Windows видит мир глазами Windows, а Git Bash — глазами POSIX: путь вида
+# /tmp/tmp.XXXX, отданный в `node -e`, там не существует, и проверка падает не на том, что
+# проверяет. Поймано дважды на windows-прогоне — сперва на `learn`, потом на установке хука.
+# Поэтому node запускается ИЗ каталога и получает относительный путь: помощник, а не памятка,
+# потому что памятку третий раз забудут ровно так же, как забыли второй.
+node_in() { D="$1"; shift; ( cd "$D" && node "$@" ); }
+
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 
@@ -1183,7 +1190,11 @@ rm -rf "$VDIR"
 # v0.4.2, отставание на два выпуска. Проверка сравнивает обе с package.json, а не друг с другом:
 # совпасть друг с другом они могут и будучи одинаково устаревшими.
 VERS_BAD=""
-for VF in README.md llms.txt; do
+# README.ru.md попал сюда 2026-09-08, при выпуске 0.8.0: в нём стояли v0.6.0 и v0.5.0 —
+# отставание на два и на три выпуска. Проверка его не смотрела, и русский читатель ставил
+# прошлогодний комплект молча. Ровно та же дыра, ради которой проверку и заводили, — просто
+# в файле, который забыли перечислить.
+for VF in README.md README.ru.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" \
@@ -1192,11 +1203,240 @@ for VF in README.md llms.txt; do
   done
 done
 if [ -z "$VERS_BAD" ]; then
-  ok "версия в README и llms.txt совпадает с package.json (v$PKGVER)"
+  ok "версия в обоих README и llms.txt совпадает с package.json (v$PKGVER)"
 else
   bad "версия в документах разошлась с package.json" "package.json: v$PKGVER; найдено — $VERS_BAD"
 fi
 
+# --- 82. report --since называет, чем доказан диф ---------------------------
+# Три состояния у файла, и разница между вторым и третьим — весь смысл раздела: «проверка
+# обошла и промолчала» не то же самое, что «никто не смотрел». Двух состояний хватило ровно до
+# первого прогона — `tool/commands/doctor.mjs` попал в «никем не проверен», хотя его обходят
+# пять проверок; они молчали, потому что нашли чисто.
+EVDIR="$(mktemp -d)"
+(
+  cd "$EVDIR" || exit 1
+  git init -q . && git config user.email a@b.c && git config user.name t
+  mkdir -p src gates/noisy
+  printf 'x = 1\n' > src/kept.py
+  # Гейт, который печатает путь: по нему файл становится «назван».
+  printf '#!/usr/bin/env sh\necho "src/kept.py:1: нашёл"\nexit 0\n' > gates/noisy/check.sh
+  printf 'aqk: "1"\nentry: [AGENTS.md]\ngates:\n  noisy: "sh gates/noisy/check.sh ."\n' > .aqk.yml
+  printf '# правила\n' > AGENTS.md
+  git add -A >/dev/null 2>&1 && git commit -qm base >/dev/null 2>&1
+  printf 'y = 2\n' > src/quiet.py
+  git add -A >/dev/null 2>&1 && git commit -qm second >/dev/null 2>&1
+) >/dev/null 2>&1
+EV_OUT=$( cd "$EVDIR" && AQK_LANG=ru node "$CLI" report --since HEAD~1 2>&1 )
+EV_FILE="$EVDIR/.aqk/report.md"
+if [ -f "$EV_FILE" ] && grep -q "src/quiet.py" "$EV_FILE" && grep -q "Чем доказан" "$EV_FILE"; then
+  ok "report --since называет, чем доказан диф"
+else
+  bad "report --since не отчитался о покрытии" "$(printf '%s' "$EV_OUT" | tail -2 | head -1)"
+fi
+# Ссылка, которой нет, обязана быть названа: «сравнили не с тем» не должно читаться как «чисто».
+EV_BAD=$( cd "$EVDIR" && AQK_LANG=ru node "$CLI" report --since no-such-ref 2>&1 )
+if printf '%s' "$EV_BAD" | grep -q "no-such-ref"; then
+  ok "report --since называет неразобранную ссылку"
+else
+  bad "report --since проглотил неверную ссылку" "$(printf '%s' "$EV_BAD" | tail -2 | head -1)"
+fi
+rm -rf "$EVDIR"
+
+# --- 84. learn читает только напечатанное человеком --------------------------
+# Поле promptSource отделяет реплику от результата инструмента. Без него первая версия отбора
+# выдавала вставленные пути и ссылки вместо правил — «agent quality kit» 44 раза.
+# Каталог логов кладём ВНУТРЬ проекта и передаём относительным путём. Абсолютный сюда не
+# годится: Git Bash на Windows отдаёт «/tmp/…», а Node в том же окружении читает это как
+# «C:\tmp\…» — переменная указывает в никуда, и проверка падает не по делу.
+LRNP="$(mktemp -d)"; LRN=".cfg"
+# Имя каталога логов спрашиваем у самой программы, а не считаем здесь. На Windows оболочка
+# отдаёт «/tmp/…», а Node видит «C:\Users\…» — две разные строки, и тест падал не по делу.
+# Правило перевода пути в имя сторожит модульная проверка logSlug, здесь проверяется конвейер.
+SLUG=$( cd "$LRNP" && node -e "const {pathToFileURL}=require('node:url');import(pathToFileURL(process.argv[1]).href).then(m=>console.log(m.logSlug(process.cwd())))" "$ROOT/tool/commands/learn.mjs" )
+mkdir -p "$LRNP/$LRN/projects/$SLUG"
+{
+  printf '{"type":"user","promptSource":"typed","timestamp":"2026-09-08T10:00:00Z","message":{"role":"user","content":"никогда не коммить прямо в основную ветку"}}\n'
+  printf '{"type":"user","promptSource":"typed","timestamp":"2026-09-08T10:01:00Z","message":{"role":"user","content":"ок го дальше"}}\n'
+  printf '{"type":"user","timestamp":"2026-09-08T10:02:00Z","message":{"role":"user","content":[{"type":"tool_result","content":"нельзя обязательно всегда"}]}}\n'
+} > "$LRNP/$LRN/projects/$SLUG/s1.jsonl"
+printf '# правила\n- Ничего особенного.\n' > "$LRNP/AGENTS.md"
+printf 'aqk: "1"\nentry: [AGENTS.md]\n' > "$LRNP/.aqk.yml"
+LRN_OUT=$( cd "$LRNP" && CLAUDE_CONFIG_DIR="$LRN" AQK_LANG=ru node "$CLI" learn 2>&1 )
+if printf '%s' "$LRN_OUT" | grep -q "основную ветку" &&
+   ! printf '%s' "$LRN_OUT" | grep -q "го дальше" &&
+   printf '%s' "$LRN_OUT" | grep -q "напечатано человеком: 2"; then
+  ok "learn берёт напечатанное человеком и не берёт вывод инструментов"
+else
+  bad "learn отобрал не то" "$(printf '%s' "$LRN_OUT" | tr '\n' ' ' | cut -c1-150)"
+fi
+# Правило, уже стоящее в точке входа, показывать незачем: команда не пересказывает свод.
+printf '# правила\n- Никогда не коммить прямо в основную ветку.\n' > "$LRNP/AGENTS.md"
+LRN_W=$( cd "$LRNP" && CLAUDE_CONFIG_DIR="$LRN" AQK_LANG=ru node "$CLI" learn 2>&1 )
+if printf '%s' "$LRN_W" | grep -q "уже стоит в точке входа"; then
+  ok "learn молчит о правиле, которое уже записано"
+else
+  bad "learn повторил записанное правило" "$(printf '%s' "$LRN_W" | tr '\n' ' ' | cut -c1-150)"
+fi
+# Читает переписку — значит на диск не пишет ничего. Проверяем буквально.
+if [ ! -d "$LRNP/.aqk" ] || [ -z "$(ls -A "$LRNP/.aqk" 2>/dev/null)" ]; then
+  ok "learn ничего не записал на диск"
+else
+  bad "learn создал файлы" "$(ls -A "$LRNP/.aqk" | tr '\n' ' ')"
+fi
+rm -rf "$LRNP"
+
+# --- 87. --baseline не совмещается с --run и --min ---------------------------
+# `--baseline` выходит с нулём всегда: это осмотр, а не прогон. Совмещённый с порогом он давал
+# конвейер, который НЕ МОЖЕТ покраснеть — порог назван, гейты не запущены, код нулевой. Найдено
+# ревью 2026-09-08. Отказ должен быть громким: молчаливое зелёное здесь дороже сломанной команды.
+BLP="$(mktemp -d)"
+( cd "$BLP" && git init -q . && printf 'aqk: "1"\nentry: [AGENTS.md]\n' > .aqk.yml && printf '# правила\n' > AGENTS.md ) >/dev/null 2>&1
+BL_OK=$( cd "$BLP" && AQK_LANG=ru node "$CLI" doctor --baseline 2>&1 ); BL_OK_C=$?
+BL_BAD=$( cd "$BLP" && AQK_LANG=ru node "$CLI" doctor --baseline --min 1 2>&1 ); BL_BAD_C=$?
+BL_RUN=$( cd "$BLP" && AQK_LANG=ru node "$CLI" doctor --baseline --run 2>&1 ); BL_RUN_C=$?
+if [ "$BL_OK_C" -eq 0 ] && [ "$BL_BAD_C" -ne 0 ] && [ "$BL_RUN_C" -ne 0 ] &&
+   printf '%s' "$BL_BAD" | grep -q "не может покраснеть"; then
+  ok "--baseline с --min и --run отказывает вслух, сам по себе работает"
+else
+  bad "--baseline не отказал на пороге" "коды: сам $BL_OK_C, с --min $BL_BAD_C, с --run $BL_RUN_C"
+fi
+rm -rf "$BLP"
+
+# --- 88. записи каталога не ломаются от цвета в выводе арбитра ---------------
+# Внутри GitHub Actions чужие инструменты КРАСЯТ вывод: там цвет поддержан, вне конвейера они
+# его выключают сами. Разбор по началу строки тогда промахивается — строка начинается с
+# escape-последовательности. Поймано конвейером 2026-09-08 на записи ci-not-hijackable: локально
+# зелёная, в конвейере «формат сменился». Тот же класс уже записан в scope.mjs.
+CLR_BAD=""
+for CG in kit/gates/*/check.sh; do
+  CS=$(basename "$(dirname "$CG")")
+  # Только записи с готовым арбитром: у них вывод чужой, и красит его не наш код.
+  grep -q "^requires:" "$(dirname "$CG")/gate.yml" 2>/dev/null || continue
+  command -v "$(sed -n 's/^requires:[[:space:]]*//p' "$(dirname "$CG")/gate.yml" | head -1 | awk '{print $1}')" >/dev/null 2>&1 || continue
+  PLAIN=$(bash "$CG" "$(dirname "$CG")/green" >/dev/null 2>&1; echo $?)
+  COLOR=$(GITHUB_ACTIONS=true CI=true bash "$CG" "$(dirname "$CG")/green" >/dev/null 2>&1; echo $?)
+  [ "$PLAIN" = "$COLOR" ] || CLR_BAD="${CLR_BAD:+$CLR_BAD, }$CS ($PLAIN vs $COLOR)"
+done
+if [ -z "$CLR_BAD" ]; then
+  ok "вердикт записи не зависит от того, красит ли арбитр вывод"
+else
+  bad "цвет в выводе арбитра меняет вердикт" "$CLR_BAD"
+fi
+
+# --- 89. шапка doctor читает манифест, а не литеральные пути ------------------
+# Отзыв второго пользователя 2026-09-08: у проекта `rules: .temper/rules`, правила на месте,
+# СТУПЕНЬ по манифесту берётся — а шапка рисовала кресты за `.aqk/rules` и `.aqk/docs` и
+# советовала сделать сделанное. Вывод расходился с собственным вердиктом программы, напечатанным
+# на десять строк ниже. Модульная проверка сторожит функцию; эта — то, что её кто-то зовёт.
+LYP="$(mktemp -d)"
+( cd "$LYP" && git init -q . && mkdir -p .temper/rules .temper/docs &&
+  printf 'правило\n' > .temper/rules/r.md && printf 'методичка\n' > .temper/docs/d.md &&
+  printf '# вход\n' > CLAUDE.md && printf '.x\n' > .gitignore &&
+  printf 'aqk: 1\nentry:\n  - CLAUDE.md\nrules: .temper/rules\ndocs: .temper/docs\ngates:\n  smoke: "true"\n' > .aqk.yml ) >/dev/null 2>&1
+LY=$( cd "$LYP" && AQK_LANG=ru node "$CLI" doctor 2>&1 )
+if printf '%s' "$LY" | grep -q "\.temper/rules" &&
+   printf '%s' "$LY" | grep -q "\.temper/docs" &&
+   printf '%s' "$LY" | grep -q "CLAUDE\.md" &&
+   ! printf '%s' "$LY" | grep -q "\.aqk/rules" &&
+   ! printf '%s' "$LY" | grep -q "неизвестное поле"; then
+  ok "шапка doctor берёт правила, методички и вход из манифеста"
+else
+  bad "doctor проверил не то, что объявлено в манифесте" "$(printf '%s' "$LY" | head -8)"
+fi
+rm -rf "$LYP"
+
+# --- 90. блок состояния: тишина не выдаётся за «чисто» -----------------------
+# Читатель этого блока — машина. Человек, увидев пустое место, переспросит; агент примет его
+# за утверждение и пойдёт писать код по несуществующему разрешению. Поэтому главное здесь одно:
+# без прогона блок обязан сказать «неизвестно» СЛОВОМ.
+CTXP="$(mktemp -d)"
+( cd "$CTXP" && git init -q . ) >/dev/null 2>&1
+CTX=$( cd "$CTXP" && AQK_LANG=ru node "$CLI" context 2>&1 ); CTX_C=$?
+if [ "$CTX_C" -eq 0 ] &&
+   printf '%s' "$CTX" | grep -q "НЕИЗВЕСТНО" &&
+   printf '%s' "$CTX" | grep -q "не вычислен" &&
+   ! printf '%s' "$CTX" | grep -q "AGENTS.md"; then
+  ok "context без прогона говорит «неизвестно» и не называет несуществующий свод"
+else
+  bad "context выдал незнание за чистоту" "код $CTX_C: $(printf '%s' "$CTX" | head -5)"
+fi
+
+# --- 91. хук ставится в общий файл и не затирает чужие настройки --------------
+mkdir -p "$CTXP/.claude"
+printf '{ "permissions": { "deny": ["Read(./.env)"] } }\n' > "$CTXP/.claude/settings.json"
+( cd "$CTXP" && AQK_LANG=ru node "$CLI" context --install ) >/dev/null 2>&1
+AGAIN=$( cd "$CTXP" && AQK_LANG=ru node "$CLI" context --install 2>&1 )
+HOOKS=$(node_in "$CTXP" -e 'const s=require("./.claude/settings.json");
+  console.log([s.hooks?.SessionStart?.length, s.permissions?.deny?.length,
+    /[/\\]program\.mjs/.test(JSON.stringify(s.hooks?.SessionStart||[]))].join(" "))' 2>&1)
+if [ "$HOOKS" = "1 1 false" ] && printf '%s' "$AGAIN" | grep -q "уже стоит"; then
+  ok "хук ставится один раз, переносимой командой, чужие настройки целы"
+else
+  bad "установка хука испортила настройки или задвоилась" "разбор: $HOOKS"
+fi
+rm -rf "$CTXP"
+
+# --- 92. полный блок: карта и свод дословно ----------------------------------
+# Решение владельца 2026-09-08, принятое ПОСЛЕ возражения про длину входа: агент читает файлы
+# плохо, и лишние токены — плата за то, чтобы он не ошибался. Раз плата внесена, товар обязан
+# быть доставлен: свод дословно, а не пересказ, и карта команд, а не половина карты.
+FULP="$(mktemp -d)"
+( cd "$FULP" && git init -q . &&
+  printf '# Свод\n\n- Правило-маячок-для-проверки. <!-- aqk: человек -->\n' > AGENTS.md &&
+  printf 'aqk: 1\nentry:\n  - AGENTS.md\n' > .aqk.yml ) >/dev/null 2>&1
+FUL=$( cd "$FULP" && AQK_LANG=ru node "$CLI" context --full 2>&1 )
+SHORT=$( cd "$FULP" && AQK_LANG=ru node "$CLI" context 2>&1 )
+if printf '%s' "$FUL" | grep -q "Правило-маячок-для-проверки" &&
+   printf '%s' "$FUL" | grep -q "doctor --run --since main" &&
+   printf '%s' "$FUL" | grep -q "ЧТО УМЕЕТ ЭТОТ ИНСТРУМЕНТ" &&
+   ! printf '%s' "$SHORT" | grep -q "Правило-маячок-для-проверки"; then
+  ok "context --full несёт карту и свод дословно, обычный — нет"
+else
+  bad "полный блок не донёс свод или карту" "$(printf '%s' "$FUL" | head -4)"
+fi
+
+# --- 93. хук с --full ставится именно с флагом -------------------------------
+( cd "$FULP" && AQK_LANG=ru node "$CLI" context --full --install ) >/dev/null 2>&1
+FLAG=$(node_in "$FULP" -e 'const s=require("./.claude/settings.json");
+  console.log(JSON.stringify(s.hooks?.SessionStart||[]).includes("--full"))' 2>&1)
+if [ "$FLAG" = "true" ]; then
+  ok "хук, поставленный с --full, зовёт полный блок, а не короткий"
+else
+  bad "хук потерял --full — вливался бы короткий блок" "разбор: $FLAG"
+fi
+rm -rf "$FULP"
+
+# --- 94. отсев сгенерированных файлов: края, а не середина -------------------
+# `drop_generated` заменил цикл `while read; do is_generated; done` — два процесса на файл.
+# Замер на шести чужих проектах дал ноль расхождений, но отсеяно там было 5 файлов из 1242:
+# такая сверка почти ничего не доказывает. Набор ниже нарочный, и он сразу нашёл ДВА
+# расхождения, которых на живых проектах не было, — пробел и двоеточие в имени файла.
+GENP="$(mktemp -d)"
+mkg() { printf '%b' "$2" > "$GENP/$1"; }
+mkg 'l1.js'        '// @generated\ncode\n'
+mkg 'l5.js'        'a\nb\nc\nd\n// @generated\n'
+mkg 'l6.js'        'a\nb\nc\nd\ne\n// @generated\n'
+mkg 'upper.js'     '// @GENERATED\n'
+mkg 'donotedit.js' '// Do Not Edit\n'
+mkg 'autogen.js'   '// auto-generated by tool\n'
+mkg 'genby.js'     '// Generated by protoc\n'
+mkg 'cyr.js'       '// сгенерирован автоматически\n'
+mkg 'cyrup.js'     '// СГЕНЕРИРОВАН\n'
+mkg 'with space.js' '// @generated\n'
+mkg 'with:colon.js' '// @generated\n'
+mkg 'clean.js'     'const x = 1;\n'
+: > "$GENP/empty.js"
+KEPT=$( . "$ROOT/kit/gates/_skip.sh"; find "$GENP" -type f | sort | drop_generated | sed "s#$GENP/##" | sort | tr '\n' ' ' )
+# Ожидания абсолютные, а не «как было раньше»: старая функция однажды уйдёт, а края останутся.
+# l6 остаётся намеренно: маркер на шестой строке — это уже не шапка файла.
+if [ "$KEPT" = "clean.js empty.js l6.js " ]; then
+  ok "сгенерированные отсеяны по всем маркерам; пробел, двоеточие и граница 5-й строки учтены"
+else
+  bad "отсев сгенерированных изменился" "осталось: $KEPT"
+fi
+rm -rf "$GENP"
+
 # --- итог -------------------------------------------------------------------
 printf '\n'
 if [ "$FAIL" -eq 0 ]; then

package/tool/selfcheck/units-context.mjs

@@ -0,0 +1,186 @@
+// tool/selfcheck/units-context.mjs — блок состояния, который уходит В КОНТЕКСТ агента.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫМ ФАЙЛОМ. У этого текста единственный читатель — машина, и цена ошибки другая,
+// чем у терминального вывода: человек, увидев пустую строку, переспросит, а агент примет её за
+// утверждение. Поэтому главная проверка здесь одна и та же во всех видах: **тишина не означает
+// «чисто»**. Блок обязан говорить «неизвестно» там, где не знает, — иначе он врёт ровно тем
+// способом, против которого написан весь комплект.
+//
+//   node --test tool/selfcheck/units-context.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { contextBlock, countArbiters, parseLastRun, withHook, hasOurHook, portableSelf } from "../commands/context.mjs";
+import { CATALOGS } from "../i18n/index.mjs";
+import { commandRows } from "../lib/core.mjs";
+import { readFile } from "node:fs/promises";
+
+const T = CATALOGS.ru.context;
+const base = {
+  entry: "AGENTS.md",
+  level: { reached: 1, top: 3, missing: "гейты не доказаны" },
+  rules: { total: 14, machine: 2, human: 12 },
+  run: { when: "2026-09-08 11:00", red: [], skipped: 0, stale: false },
+  ratchets: [],
+};
+const text = (over = {}) => contextBlock({ ...base, ...over }, T).join("\n");
+
+// ГЛАВНАЯ. Прогона не было — сказать «неизвестно» словом. Пустая строка на этом месте
+// прочитается агентом как «красных нет», и он пойдёт писать код по несуществующему разрешению.
+test("без прогона блок говорит «неизвестно», а не молчит", () => {
+  const t = text({ run: null });
+  assert.match(t, /НЕИЗВЕСТНО/);
+  assert.doesNotMatch(t, /красных нет/);
+});
+
+test("красные гейты названы поимённо", () => {
+  const t = text({ run: { ...base.run, red: ["file-size-limit", "duplicate-code"] } });
+  assert.match(t, /file-size-limit/);
+  assert.match(t, /duplicate-code/);
+});
+
+// Проект с двадцатью красными не должен вытеснять собой весь контекст: ровно та деградация,
+// ради избежания которой блок и делается коротким.
+test("длинный список красных обрезается и называет остаток числом", () => {
+  const red = Array.from({ length: 20 }, (_, i) => `гейт-${i}`);
+  const t = text({ run: { ...base.run, red } });
+  assert.match(t, /ещё 15/);
+  assert.ok(!t.includes("гейт-9"), "шестой и дальше в список не попадают");
+});
+
+// Прогон, сделанный до последнего коммита, описывает не тот код, что лежит перед агентом.
+test("устаревший прогон помечен, а не выдан за свежий", () => {
+  const t = text({ run: { ...base.run, stale: true } });
+  assert.match(t, /СТАРЕЕ/);
+});
+
+// То, ради чего второй пользователь и оценил promise-has-gate: «держит человек» значит
+// «не держит никто», и это обязано быть сказано словами, а не выведено читателем из цифр.
+test("правила без машинного арбитра названы прямо", () => {
+  const t = text({ rules: { total: 12, machine: 0, human: 12 } });
+  assert.match(t, /не держит никто/);
+});
+
+test("нет манифеста — уровень не выдумывается", () => {
+  const t = text({ level: null });
+  assert.match(t, /не вычислен/);
+  assert.doesNotMatch(t, /AQK-0 из/);
+});
+
+// Потолок: блок влезает в глаза целиком. Замер 2026-09-08 — вход целиком в контекст роняет
+// точность у всех проверенных моделей по мере роста, поэтому предел здесь предмет проверки,
+// а не пожелание.
+test("блок не разрастается даже на худшем входе", () => {
+  const lines = contextBlock({
+    ...base,
+    run: { when: "…", red: Array.from({ length: 40 }, (_, i) => `г-${i}`), skipped: 9, stale: true },
+    ratchets: Array.from({ length: 12 }, (_, i) => ({ name: `р-${i}`, count: i })),
+  }, T);
+  assert.ok(lines.length <= 16, `строк ${lines.length}, предел 16`);
+});
+
+// --- разбор источников -------------------------------------------------------
+// Имя арбитра — это имя гейта, а в именах гейтов есть дефисы. Класс `[^\s>-]` обрывал их
+// молча: первый же живой запуск показал 13 правил вместо 14 и одного машинного вместо двух.
+// Молча — потому что число выглядит правдоподобным, пока его не с чем сверить.
+test("имя арбитра с дефисом считается машинным, а не теряется", () => {
+  const md = [
+    "- Правило один. <!-- aqk: deps-are-pinned -->",
+    "- Правило два. <!-- aqk: человек -->",
+    "- Правило три. <!-- aqk: gates -->",
+  ].join("\n");
+  assert.deepEqual(countArbiters(md, ["человек"]), { total: 3, machine: 2, human: 1 });
+});
+
+test("отчёт прошлого прогона отдаёт красные и число непроверенных", () => {
+  const r = parseLastRun([
+    "# aqk doctor --run — 2026-09-08 11:00",
+    "level: AQK-1",
+    "✔ smoke — 1.0s",
+    "✘ file-size-limit — 0.1s",
+    "~ dead-code — нет инструмента",
+  ].join("\n"));
+  assert.equal(r.when, "2026-09-08 11:00");
+  assert.deepEqual(r.red, ["file-size-limit"]);
+  assert.equal(r.skipped, 1);
+});
+
+test("пустой отчёт — это не «чисто», а отсутствие данных", () => {
+  assert.equal(parseLastRun(""), null);
+});
+
+// Найдено ЗАМЕРОМ на шести чужих проектах, до того как хук попал в init: на `flask`, где нет
+// ни .aqk.yml, ни AGENTS.md, блок всё равно писал «Свод правил: AGENTS.md». Тот же класс, что
+// у doctor неделей раньше: умолчание выдаётся за факт, потому что на нашем репозитории
+// умолчание и факт совпадают. Назвать агенту несуществующий файл хуже, чем промолчать: он
+// пойдёт его читать и получит пустоту вместо правил.
+test("несуществующая точка входа не называется как свод правил", () => {
+  const t = text({ level: null, run: null, rules: null, entryExists: false });
+  assert.doesNotMatch(t, /AGENTS\.md/);
+});
+
+test("существующая точка входа называется", () => {
+  const t = text({ entryExists: true });
+  assert.match(t, /AGENTS\.md/);
+});
+
+// --- хук уходит в ОБЩИЙ файл настроек ----------------------------------------
+// `.claude/settings.json` кладут в git: он общий на команду, в отличие от settings.local.json.
+// Значит команда внутри него обязана работать не только на той машине, где её записали.
+// На машине разработчика SELF — абсолютный путь; у соседа такого пути нет, и хук молча
+// не сработает. Молча — то есть блок состояния просто не появится, и никто не узнает.
+test("абсолютный путь заменяется переносимым вызовом", () => {
+  assert.equal(portableSelf("node /home/x/aqk/tool/program.mjs"), "npx agent-quality-kit");
+  assert.equal(portableSelf("node C:\\x\\aqk\\tool\\program.mjs"), "npx agent-quality-kit");
+});
+
+test("переносимые вызовы остаются как есть", () => {
+  assert.equal(portableSelf("aqk"), "aqk");
+  assert.equal(portableSelf("npx agent-quality-kit"), "npx agent-quality-kit");
+  assert.equal(portableSelf("node tool/program.mjs"), "node tool/program.mjs");
+});
+
+// Второй такой же хук — блок в контексте дважды: вдвое больше токенов и ровно ноль пользы.
+test("хук не задваивается", () => {
+  const once = withHook({}, "aqk context");
+  assert.ok(hasOurHook(once, "aqk context"));
+  assert.equal(once.hooks.SessionStart.length, 1);
+});
+
+// Чужие настройки в том же файле — права доступа, другие хуки — обязаны пережить установку.
+test("чужие настройки переживают установку хука", () => {
+  const before = { permissions: { deny: ["Read(./.env)"] }, hooks: { Stop: [{ hooks: [] }] } };
+  const after = withHook(before, "aqk context");
+  assert.deepEqual(after.permissions, before.permissions);
+  assert.equal(after.hooks.Stop.length, 1);
+  assert.equal(after.hooks.SessionStart.length, 1);
+});
+
+// --- карта команд ------------------------------------------------------------
+// Владелец: «агент плохо читает инструкцию — нужно влить карту и сам свод». Карта имеет смысл
+// ровно до тех пор, пока она не отстала от программы. Второй список, живущий рядом с первым,
+// через месяц врёт — это записано у нас в README про храповики и верно здесь буквально так же.
+// Поэтому карта и справка собираются ИЗ ОДНОГО списка, а эта проверка сторожит, что список
+// не отстал от диспетчера: команда, добавленная в 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]);
+  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));
+  assert.deepEqual(missing, [], `в карте нет: ${missing.join(", ")}`);
+});
+
+// Полный блок — то, за что владелец согласился платить токенами: свод правил дословно, а не
+// ссылка на него. Если он не дословный, плата внесена, а товар не получен.
+test("полный блок несёт свод правил дословно", () => {
+  const rules = "- Правило одно. <!-- aqk: человек -->\n- Правило два.";
+  const t = contextBlock({ ...base, entryExists: true, full: { entry: "AGENTS.md", rows: [{ cmd: "aqk context", text: "состояние" }], text: rules } }, T).join("\n");
+  assert.ok(t.includes(rules), "текст свода обязан войти целиком");
+  assert.match(t, /aqk context/);
+});
+
+test("без --full свод не вливается — только ссылка на него", () => {
+  const t = text({ entryExists: true });
+  assert.doesNotMatch(t, /Правило одно/);
+  assert.match(t, /AGENTS\.md/);
+});