agent-quality-kit 0.6.0 → 0.8.0

package/tool/i18n/ru.mjs

@@ -4,9 +4,24 @@
 // проверка «оба каталога несут одни и те же ключи». Иначе один язык молча отстаёт, а
 // обещание «два языка» превращается в слова.
 
+import { ruDocs } from "./ru-docs.mjs";
+
 import { templates } from "./templates-ru.mjs";
 
 export const ru = {
+  learn: {
+    title: "Сказано вслух и не записано",
+    noLogs: (p) => `логов этого проекта нет: ${p}\n  Команда читает переписку Claude Code на этой машине. Пусто — значит здесь не работали.`,
+    counted: (s, typed, said, fresh) =>
+      `сессий: ${s} · напечатано человеком: ${typed} · похоже на наставление: ${said} · нет в точке входа: ${fresh}`,
+    nothing: "всё, что похоже на правило, уже стоит в точке входа",
+    andMore: (n) => `… и ещё ${n}`,
+    warn:
+      "Это КАНДИДАТЫ, а не находки: на замере из 1619 реплик маркеры дали 79, и настоящих правил " +
+      "среди них примерно половина. Решает человек. Ничего не записано на диск — команда читает " +
+      "переписку и печатает только в терминал.",
+  },
+  ...ruDocs,
   templates,
   help: {
     tagline: "оснастка для разработки с агентами",
@@ -14,6 +29,7 @@ export const ru = {
     init: "разложить правила и методички в текущий проект",
     initForce: "перезаписать уже существующие файлы",
     start: "кода ещё нет: сторожа дня 0 и порядок работы",
+    prove: "доказать, что гейты ловят брак: каждый по своему красному и зелёному образцу",
     doctor: "проверить, что разложено и чего не хватает",
     doctorRun: "ещё и запустить объявленные гейты",
     doctorSince: "то же, но показать только то, что внёс диф относительно ссылки",
@@ -24,13 +40,20 @@ export const ru = {
     new: "заготовка своего гейта для каталога",
     note: "записать урок в общий журнал шишек",
     blob: "собрать методички в один файл GOD_AI.md",
-    report: "обязательная форма отчёта: что стоит, что нет, что не прочитано",
+    learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
+    context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
+    contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
+    report: "обязательная форма отчёта: что стоит, что нет, что не прочитано; --since <ссылка> — ещё и чем доказан диф",
     badge: "значок уровня для README — и проверка, что он не врёт",
     noInstall: "Без установки:  npx agent-quality-kit init",
     language: "Язык вывода: AQK_LANG=en (или ru), иначе по системной локали",
   },
 
   doctor: {
+    baselineClash: (f) =>
+      `«--baseline» — осмотр, а не прогон: он выходит с нулём всегда, и вместе с «${f}» даёт\n` +
+      "  конвейер, который не может покраснеть.\n" +
+      "  почини: раздели на две команды — «doctor --baseline» и «doctor --run --min 1».",
     docsKit: "методички — здесь оригиналы, а не копия",
     docs: "методички",
     rulesKit: "стандарты — здесь оригиналы, а не копия",
@@ -42,6 +65,8 @@ export const ru = {
     emptyCommands: (n) => `В AGENTS.md ${n} незаполненных команд.`,
     emptyCommandsWhy: "Агент не может выполнить пустую строку.",
 
+    levelUnproven: (cmd) => `не доказано: ${cmd}`,
+    gatesDoNotCatch: (n, cmd) => `гейтов, не ловящих брак: ${n}. Подробности: ${cmd}`,
     levelHeading: "Уровень соответствия AQK",
     levelNone: "нет",
     levelNotSet: "Уровень: стандарт в этом репозитории не заведён.",
@@ -72,6 +97,10 @@ export const ru = {
     sinceBadRef: (ref) => `не могу сравнить с «${ref}»: такой ссылки нет или это не репозиторий git`,
     notScopable: "вывод без путей — дифом не сужается, оставлен красным",
     outsideDiff: (n) => `находки есть, но вне дифа (${n})`,
+    advisoryMark: "совещательный — показано, прогон не уронен",
+    advisorySummary: (names) =>
+      `совещательные и красные: ${names.join(", ")}. Это выключенные проверки: ` +
+      `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
     exitCode: (code) => `код ${code}`,
@@ -138,6 +167,8 @@ export const ru = {
       has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
       has_tests: ["не видно тестов", "тесты есть"],
       has_env: ["нет файла окружения", "файл окружения есть"],
+      has_agent_config: ["агента здесь не настраивали", "настройки агента есть"],
+      has_agent_entry: ["свода для агента здесь нет", "свод для агента есть"],
       has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
     },
   },
@@ -167,7 +198,13 @@ export const ru = {
 
   add: {
     noSuchGate: (slug, cmd) => `Нет такого гейта: ${slug}\nСписок применимых — ${cmd}`,
-    noRecipe: (slug, stack) => `У записи ${slug} нет команды ни под ${stack}, ни общей.`,
+    toolMissing: (slug, missing) =>
+      `Записи ${slug} нужен ${missing.join(" и ")}, а его нет на этой машине.\n  почини: поставь ${missing.join(" и ")} и повтори — запись делегирует готовому инструменту по устройству, своей проверки у неё нет.`,
+    noRecipe: (slug, stack, missing) =>
+      `У записи ${slug} нет команды ни под ${stack}, ни общей.` +
+      (Array.isArray(missing) && missing.length
+        ? `\n  почини: поставь ${missing.join(" или ")} и повтори — запись делегирует готовому инструменту по устройству, своей проверки у неё нет.`
+        : `\n  почини: добавь рецепт под свой стек в gate.yml этой записи либо возьми другую.`),
     thisStack: "этот стек",
     needName: (cmd, doctor) => `Укажи имя гейта: ${cmd}. Список — ${doctor}`,
     noManifest: (cmd) => `Нет .aqk.yml — сначала ${cmd}`,
@@ -220,7 +257,13 @@ export const ru = {
     registryHead: (slug, stamp) =>
       `# Реестр долга: ${slug}\n` +
       `# Снят ${stamp}. Список разрешается ТОЛЬКО укорачивать.\n` +
-      `# Новое нарушение красит гейт; исправленное вычёркивается автоматически.\n`,
+      `# Новое нарушение красит гейт; исправленное вычёркивается автоматически.\n` +
+      `#\n` +
+      `# Долг без цели и срока не кончается. Цель — сколько нарушений считать погашенным долгом;\n` +
+      `# по достижении храповик скажет убрать обёртку. Срок необязателен, но если он есть,\n` +
+      `# после этой даты непогашенный долг красит гейт — срок без последствия не срок.\n` +
+      `# aqk-goal: 0\n` +
+      `# aqk-deadline:\n`,
     recorded: (n) => `${n} нарушений записано долгом`,
     libCopied: "обёртка скопирована в проект",
     wrapped: "команда завёрнута в храповик",
@@ -302,6 +345,8 @@ export const ru = {
 
   init: {
     noDocs: (dir) => `Не найден корпус методичек: ${dir}\nПохоже, пакет установлен не полностью.`,
+    docsRu:
+      "методички в .aqk/docs/ остаются на русском — решение, а не недоделка.",
     created: (n) => `создано (${n}):`,
     andMore: (n) => `… и ещё ${n}`,
     kept: (n) => `уже были на месте, не тронуты (${n}):`,
@@ -321,6 +366,7 @@ export const ru = {
     n4c: ". Гейт стережёт существующий артефакт:",
     n4d: "проверка на код, которого ещё нет, — мёртвое правило.",
     burned: (cmd) => `Обжёгся на чём-то — запиши: ${cmd}`,
+    hookHint: (cmd) => `Claude Code: ${cmd} — состояние проекта будет попадать в контекст агента\n  само, до первого действия. Для других агентов хука нет, и это не недоделка.`,
   },
 
   feedback: {
@@ -393,31 +439,27 @@ export const ru = {
     nextWhy: "— прогнать всё, что объявлено",
   },
 
-  manifestDoc: {
-    head: [
-      "# .aqk.yml — манифест Agent Quality Kit",
-      "# Что это: машиночитаемое описание того, как в этом репозитории живут агенты.",
-      "# Уровень соответствия считает `aqk doctor`. Пустое поле = ступень не пройдена,",
-      "# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.",
-    ],
-    entry: "# AQK-0 — что агент читает первым.",
-    rules: "# AQK-1 — где стандарты и какие проверки обязательны.",
-    gates: [
-      "  # Имя: команда, возвращающая 0 или не 0. Пустое объявление защиты не даёт и бракуется",
-      "  # проверкой «объявленный гейт запускается» — поэтому здесь примеры, а не заготовки.",
-      '  #   lint: "ruff check ."',
-      '  #   test: "pytest -q"',
-      "  # Поставить готовую запись из каталога вместе с образцами: aqk add <имя>",
-    ],
-    samples: [
-      "# AQK-2 — чем доказано, что гейты работают, и где реестры долга.",
-      "# samples: каталог с красными и зелёными образцами (гейт обязан краснеть на первом",
-      "# и молчать на втором). ratchets: списки известных нарушений, которые могут только",
-      "# укорачиваться.",
-    ],
-    lessons: "# AQK-3 — где копятся уроки. Путь или адрес.",
-  },
 
+  prove: {
+    title: "aqk prove — доказательство гейтов",
+    running: "доказываю гейты по их образцам…",
+    proven: (n) => `доказано: ${n}`,
+    broken: (n) => `не ловят: ${n}`,
+    unprovable: (n) => `нечем доказать: ${n}`,
+    okRed: "краснеет на красном, молчит на зелёном",
+    redPassed: "промолчал на КРАСНОМ образце — гейт не ловит брак",
+    greenFailed: "покраснел на ЗЕЛЁНОМ образце — гейт ругается на исправный код",
+    empty: "команда пустая — объявление без команды защиты не даёт",
+    noSamples: "нет образцов — доказать нечем",
+    noTarget: "не видно, куда подставить каталог образца — команда написана руками",
+    otherRecipe: (lang) => `образцы написаны под рецепт «${lang}», а стоит другой — доказать нечем`,
+    noGates: "гейтов не объявлено — доказывать нечего",
+    noSamplesDir: "в .aqk.yml не заполнено поле samples — образцы искать негде",
+    nothingProven:
+      "ни один гейт не доказан. Уровень выше AQK-1 означал бы доверие к автору, а не факт:\n  проект с гейтом «true» прошёл бы его так же, как проект с настоящей защитой.",
+    fix: (cmd) => `почини: поставь запись каталога вместе с образцами — ${cmd}`,
+    heading: "Доказательство гейтов",
+  },
   badge: {
     noManifest: (cmd) => `Нет .aqk.yml — уровня ещё нет. Начни с ${cmd}`,
     notReached: (cmd) => `AQK-0 не достигнут — значок выдавать не за что. Чего не хватает: ${cmd}`,
@@ -430,69 +472,6 @@ export const ru = {
     checkOk: (level, where) => `Значок совпал с прогоном: AQK-${level} — ${where}`,
   },
 
-  report2: {
-    title: "Отчёт AQK",
-    noManifest: (cmd) => `Нет .aqk.yml — отчитываться не о чем. Начни с ${cmd}`,
-    level: "Уровень",
-    holdsTitle: "Что держит машина (прогон, а не манифест)",
-    nothingRuns: "⬜ ни один гейт не объявлен",
-    native: (prog) => `родной рецепт: ${prog}`,
-    portable: "переносимая проверка",
-    weakerTitle: "Стоит слабее возможного",
-    weaker: (progs) => `в системе есть ${progs}, но гейт стоит на переносимой проверке — она ловит меньше`,
-    missingTitle: "Чего нет",
-    nothingMissing: "✅ все применимые записи поставлены",
-    needsTool: (prog) => `нужен ${prog} — его нет в системе`,
-    notInstalled: "применимо, но не поставлено",
-    hiddenTitle: "Не применимо к этому репозиторию",
-    readTitle: "Что комплект велел прочитать",
-    readWarn:
-      "Значок означает только наличие файла на диске. Прочитан он или нет, машина не знает и " +
-      "не притворяется, что знает: это отвечает тот, кто отчитывается.",
-    ignoreTitle: "Что спрятано .aqkignore",
-    ignoreNone: "файла .aqkignore нет — ничего не спрятано",
-    ignoreWarn:
-      "Скрытое молча — тот же класс, что молчащий гейт: гейты по этим путям не смотрят вовсе. " +
-      "Строка здесь означает, что защиты там нет и не будет.",
-    whyTitle: "Зачем это нужно — коротко",
-    whyNothing: "нечего добавлять: применимое уже стоит",
-    saved: (path) => `Сохранено: ${path}`,
-    docs: {
-      baseline: "обязательный минимум проекта, без привязки к языку",
-      readyMade: "карта готовых правил: сперва ищи готовое, потом пиши своё",
-      rulesGeneral: "общие правила работы",
-      rulesTesting: "правила про тесты",
-      rulesSecurity: "правила про безопасность",
-    },
-  },
 
-  levels: [
-    {
-      title: "манифест и точка входа",
-      need: "создай .aqk.yml и укажи в entry файл, который агент читает первым (AGENTS.md)",
-      gives: "любой инструмент понимает, что читать в этом репозитории",
-    },
-    {
-      title: "правила и работающие гейты",
-      need: "укажи rules (каталог стандартов) и заполни хотя бы один гейт в gates реальной командой",
-      gives: "проверки объявлены командами, а не описаны словами",
-    },
-    {
-      title: "гейты доказаны, долг под храповиком",
-      need: "заведи samples (красные и зелёные образцы гейтов) и ratchets (реестры долга)",
-      gives: "гейт доказал, что ловит брак и молчит на исправном коде",
-    },
-    {
-      title: "уроки возвращаются в работу",
-      need: "укажи lessons — путь или адрес журнала, где каждый инцидент даёт вывод",
-      gives: "проект учится: одна и та же шишка не набивается дважды",
-    },
-  ],
 
-  report: {
-    title: "aqk doctor --run",
-    version: "версия",
-    level: "уровень",
-    summary: (ok, all) => `итого: ${ok} из ${all} зелёных`,
-  },
 };

package/tool/i18n/templates-en.mjs

@@ -18,7 +18,7 @@ const AGENTS_MD = `# AGENTS.md
 - **Only the files the task is about.** No fixing things "while we are here".  <!-- aqk: human -->
 - **Done = proven.** Name the arbiter: a test, a live run, a check against the source.  <!-- aqk: human -->
   "Looks like it works" is not done.
-- **Never swallow an error.** Either handled and logged, or re-raised.  <!-- aqk: swallowed-error -->
+- **Never swallow an error.** Either handled and logged, or re-raised.  <!-- aqk: human -->
 - **A fork in the road is a question for a human.** Departing from an agreed decision is not  <!-- aqk: human -->
   documented with a code comment.
 - **Report on your work with the kit with a command, not with words.** When you are done, run  <!-- aqk: human -->

package/tool/i18n/templates-ru.mjs

@@ -23,7 +23,7 @@ const AGENTS_MD = `# AGENTS.md
 - **Только файлы из задачи.** Заодно ничего не чиним.  <!-- aqk: человек -->
 - **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит  <!-- aqk: человек -->
   рабочим» — не готово.
-- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.  <!-- aqk: swallowed-error -->
+- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.  <!-- aqk: человек -->
 - **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием  <!-- aqk: человек -->
   в коде.
 - **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.  <!-- aqk: человек -->

package/tool/lib/core.mjs

@@ -4,6 +4,7 @@
 // пределе в 500. Разделена по назначению, а не пополам — так требует наше же правило про
 // размер файла. Зависимостей по-прежнему нет ни одной: только встроенные модули Node.
 
+import { LANG } from "../i18n/index.mjs";
 import { access, readdir, mkdir, copyFile, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -17,7 +18,12 @@ const PKG_ROOT = resolve(HERE, "..", "..");
 const CWD = process.cwd();
 
 const DOCS_SRC = join(PKG_ROOT, "kit", "docs");
-const RULES_SRC = join(PKG_ROOT, "kit", "rules");
+// Правила переносятся в проект НА ЯЗЫКЕ ВЫВОДА. Русский текст в англоязычном проекте — не
+// мелочь: это первое, что там откроет человек, и первое, чего он не прочитает. Русская версия
+// остаётся источником истины, английская — переводом; расходиться им нельзя, и совпадение
+// НАБОРА ФАЙЛОВ сторожит модульная проверка. Совпадение содержания машина не сторожит — это
+// названо в AGENTS.md, а не спрятано.
+const RULES_SRC = join(PKG_ROOT, "kit", LANG === "en" ? "rules-en" : "rules");
 const TARGET_DIR = ".aqk";
 
 const c = {
@@ -51,6 +57,35 @@ function selfCmd() {
 
 const SELF = selfCmd();
 
+// КАРТА КОМАНД — ОДИН список на справку в терминале и на карту, уходящую в контекст агента.
+// Два списка рядом через месяц врут по-разному, и непонятно, какой настоящий: это записано
+// у нас в CLAUDE.md про своды правил и верно здесь буквально так же. Модульная проверка
+// сторожит, что список не отстал от диспетчера в program.mjs.
+function commandRows(L) {
+  const h = L.help;
+  return [
+    { name: "init", args: "", text: h.init },
+    { name: "init", args: "--force", text: h.initForce },
+    { name: "start", args: "", text: h.start },
+    { name: "doctor", args: "", text: h.doctor },
+    { name: "doctor", args: "--run", text: h.doctorRun },
+    { name: "doctor", args: "--run --since main", text: h.doctorSince },
+    { name: "prove", args: "", text: h.prove },
+    { name: "add", args: h.name, text: h.add },
+    { name: "find", args: '"…"', text: h.find },
+    { name: "why", args: '"…"', text: h.why },
+    { name: "ratchet", args: h.name, text: h.ratchet },
+    { name: "new", args: h.name, text: h.new },
+    { name: "note", args: '"…"', text: h.note },
+    { name: "blob", args: "", text: h.blob },
+    { name: "report", args: "", text: h.report },
+    { name: "learn", args: "", text: h.learn },
+    { name: "context", args: "", text: h.context },
+    { name: "context", args: "--full --install", text: h.contextInstall },
+    { name: "badge", args: "", text: h.badge },
+  ];
+}
+
 function die(msg) {
   console.error(c.red(msg));
   process.exit(1);
@@ -108,5 +143,5 @@ export {
   copyDir, writeIfAbsent,
   PKG_ROOT, CWD, DOCS_SRC, RULES_SRC, TARGET_DIR, docPath,
   MANIFEST, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB,
-  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK,
+  SELF, REPO_URL, c, exists, die, FEEDBACK_MARK, commandRows,
 };

package/tool/lib/evidence.mjs

@@ -0,0 +1,124 @@
+// tool/lib/evidence.mjs — привязка доказательства к дифу.
+//
+// ЗАЧЕМ. «Готово = доказано» — центральное правило свода, и оно единственное из четырнадцати,
+// за которым не следила машина: в `AGENTS.md` его сторожем честно записан человек. Цена этого
+// измерена 2026-09-08 прогоном чужого инструмента по восьми нашим коммитам: `publish.yml`
+// менялся и не был назван ни одной командой проверки — и именно он оказался сломан. Коммит при
+// этом говорил «прогон: units 51, smoke 81». Утверждение было правдой и не относилось к делу.
+//
+// Механизм взят у [donecheck](https://github.com/AtharvaMaik/donecheck) (MIT, ноль
+// зависимостей). Своего разбора команд не пишем — берём идею, а не код: donecheck САМ запускает
+// команды проверки, а `doctor --run` их уже запустил, и обёртка означала бы двойной прогон
+// всего набора гейтов. Здесь данные уже есть.
+//
+// ОДНО ОТЛИЧИЕ, И ОНО НАМЕРЕННОЕ. donecheck считает файл покрытым и по голому имени. В нашем
+// каталоге имя `check.sh` носят два десятка разных файлов: мягкое сравнение объявило бы
+// покрытым каждый из них, стоит любому гейту напечатать это слово. Ошибка в сторону «покрыто»
+// — это тишина, а тишина здесь и есть предмет спора. Сравниваем строго, по полному пути.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { changedFiles, pathsIn, normPath } from "./scope.mjs";
+
+// Расширения, для которых «никто не проверил» — утверждение о деле. Документ не проверяется
+// прогоном по своей природе, и требовать этого значило бы красить каждую правку README.
+const CODE_EXT = new Set([
+  "c", "cjs", "cpp", "cs", "css", "go", "h", "java", "js", "json", "jsx", "kt", "mjs", "mts",
+  "php", "pl", "py", "rb", "rs", "scala", "sh", "sql", "swift", "toml", "ts", "tsx", "vue",
+  "yaml", "yml",
+]);
+
+// Образцы гейтов исключены по той же причине, по какой их исключает каждая сканирующая
+// проверка каталога: они существуют, чтобы быть неправильными, и командой проверки покрыты
+// быть не могут. Без этого замер дал восемь ложных находок из шестнадцати.
+function isSample(p) {
+  return /(^|\/)gates\/[^/]+\/(red|green)(\/|$)/.test(p);
+}
+
+function ext(p) {
+  const m = /\.([A-Za-z0-9]+)$/.exec(p);
+  return m ? m[1].toLowerCase() : "";
+}
+
+// Файлы кода, которые внёс диф. null — если ссылка не разобрана: «сравнили не с тем» обязано
+// отличаться от «изменений нет».
+function changedCode(ref, cwd) {
+  const all = changedFiles(ref, cwd);
+  if (all === null) return null;
+  return [...all].map(normPath).filter((p) => CODE_EXT.has(ext(p)) && !isSample(p)).sort();
+}
+
+// Куда гейт был НАПРАВЛЕН: цели из его команды. Проверка, обошедшая каталог и не нашедшая
+// ничего, файла не назовёт — и «просмотрен и чист» стало бы неотличимо от «никто не смотрел».
+// Различить это по выводу нельзя, а по команде можно: она говорит, куда гейт направляли.
+function targetsOf(cmd, isDir) {
+  const out = [];
+  for (const tok of String(cmd || "").split(/\s+/)) {
+    if (tok.startsWith("-")) continue;
+    const t = normPath(tok);
+    if (tok === "." || tok === "./") { out.push(""); continue; }
+    if (t && !t.includes("*") && isDir(t)) out.push(t.replace(/\/$/, ""));
+  }
+  return out;
+}
+
+// Три состояния, а не два, и это главное в этой функции.
+//
+//   named   — гейт напечатал путь файла: он его точно видел и что-то о нём сказал;
+//   silent  — гейт был направлен в каталог с этим файлом, но ничего не напечатал. Просмотрен и
+//             чист либо не просмотрен вовсе — по выводу это неразличимо, и выдавать одно за
+//             другое нельзя ни в ту, ни в другую сторону;
+//   none    — ни одна команда даже не была направлена туда, где файл лежит.
+//
+// Двух состояний хватило ровно до первого прогона: `tool/commands/doctor.mjs` попал в «никем
+// не проверен», хотя его обходят пять проверок — они просто промолчали, потому что нашли
+// чисто. Замеряно 2026-09-08.
+function coverage(files, results, isDir = () => false) {
+  const seen = results.map((r) => ({
+    name: r.name,
+    paths: pathsIn(`${r.cmd || ""}\n${r.out || ""}`),
+    targets: targetsOf(r.cmd, isDir),
+  }));
+  const covered = new Map();
+  const silent = new Map();
+  const uncovered = [];
+  for (const raw of files) {
+    const f = normPath(raw);
+    const by = seen.filter((n) => n.paths.has(f)).map((n) => n.name);
+    if (by.length) { covered.set(raw, by); continue; }
+    const aimed = seen
+      .filter((n) => n.targets.some((t) => t === "" || f === t || f.startsWith(`${t}/`)))
+      .map((n) => n.name);
+    if (aimed.length) silent.set(raw, aimed);
+    else uncovered.push(raw);
+  }
+  return { covered, silent, uncovered };
+}
+
+// Отпечаток того, о чём отчитывается расписка: базовый коммит, набор команд, содержимое файлов.
+// Изменилось что угодно из этого — расписка устарела, и «прогнал, потом поправил ещё три файла»
+// перестаёт быть неотличимым от «прогнал».
+//
+// files — пары [путь, содержимое]. Содержимое передаётся, а не читается здесь: вызывающий уже
+// держит файлы в руках, а функция без ввода-вывода проверяется модульно.
+function evidenceHash(base, commands, files) {
+  const h = createHash("sha256");
+  h.update(`base:${base || ""}\0`);
+  for (const c of commands) h.update(`cmd:${c?.cmd ?? c}\0`);
+  for (const [p, body] of [...files].sort((a, b) => String(a[0]).localeCompare(String(b[0])))) {
+    h.update(`path:${normPath(p)}\0`);
+    h.update(body === null || body === undefined ? "<missing>" : String(body));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+// Читает содержимое для отпечатка. Отсутствующий файл — тоже факт: удаление меняет расписку.
+function readForHash(files, cwd) {
+  return files.map((p) => {
+    try { return [p, readFileSync(join(cwd, p), "utf8")]; } catch { return [p, null]; }
+  });
+}
+
+export { changedCode, coverage, evidenceHash, readForHash };

package/tool/lib/manifest.mjs

@@ -79,7 +79,34 @@ function parseManifest(text) {
 // Список обязан совпадать с тем, что программа РЕАЛЬНО читает (`man?.<поле>` в tool/):
 // лишнее имя здесь молча узаконивает поле, которое ни на что не влияет, — та же тишина,
 // только с другой стороны. Сверено обходом: aqk, entry, rules, gates, samples, ratchets, lessons.
-const KNOWN_KEYS = ["aqk", "entry", "rules", "gates", "samples", "ratchets", "lessons"];
+const KNOWN_KEYS = ["aqk", "entry", "rules", "docs", "gates", "samples", "ratchets", "lessons", "advisory"];
+
+// ГДЕ У ПРОЕКТА ЛЕЖИТ РАЗЛОЖЕННЫЙ КОМПЛЕКТ. Список для шапки `doctor`. До 2026-09-08 он был
+// литеральным: `.aqk/rules`, `.aqk/docs`, `AGENTS.md` — независимо от того, что написано в
+// манифесте. Второй пользователь прислал разбор: у него `rules: .temper/rules`, правила на
+// месте, гейт entry-links-exist их видит, СТУПЕНЬ считается по манифесту и берётся — а шапка
+// рисует два креста и советует сделать сделанное. Вывод расходился с собственным вердиктом
+// программы; это хуже, чем просто неверный вывод, потому что оба напечатаны рядом.
+// Поля `docs:` не существовало вовсе: методички было некуда перенести, и крест за них снять
+// было нельзя ничем. Умолчания остаются для тех, кто полей не завёл, — это большинство.
+function layoutChecks(man, inKit) {
+  const field = (name, dflt) => {
+    const v = man && typeof man === "object" && !Array.isArray(man) ? man[name] : null;
+    return typeof v === "string" && v.trim() ? v.trim() : dflt;
+  };
+  // Точка входа — тоже поле манифеста, и по той же причине: проект на `CLAUDE.md` получал крест
+  // за `AGENTS.md`, которого у него намеренно нет. Класс дефекта один, чинится он один раз.
+  const entries = (Array.isArray(man?.entry) ? man.entry : [])
+    .filter((e) => typeof e === "string" && e.trim())
+    .map((e) => e.trim());
+  return [
+    [field("docs", inKit ? "kit/docs" : ".aqk/docs"), inKit ? L.doctor.docsKit : L.doctor.docs],
+    [field("rules", inKit ? "kit/rules" : ".aqk/rules"), inKit ? L.doctor.rulesKit : L.doctor.rules],
+    ...(entries.length ? entries : ["AGENTS.md"]).map((e) => [e, L.doctor.agents]),
+    [".gitignore", L.doctor.gitignore],
+    [".git", L.doctor.git],
+  ];
+}
 
 function unknownKeys(man) {
   if (!man || typeof man !== "object" || Array.isArray(man)) return [];
@@ -119,6 +146,22 @@ function entryLifecycle(rec) {
   return { state, why, supersededBy: supersededBy || null, problem };
 }
 
+// СОВЕЩАТЕЛЬНЫЕ ГЕЙТЫ. Правило вводят в проект, где старый код ему не соответствует. Храповик
+// отвечает на это одним способом: старое становится долгом, новое блокируется. Второй способ —
+// показывать, не роняя, пока команда договаривается о правиле. Без него у человека остаётся
+// выбор из двух крайностей: включить и сломать сборку либо не включать вовсе.
+//
+// ПОЧЕМУ СПИСКОМ В МАНИФЕСТЕ, А НЕ ФЛАГОМ ПРОГОНА. Флаг «не роняй ничего» — это тот самый
+// `continue-on-error`, против которого написана наша запись ci-actually-fails: он понижает всё
+// разом, не виден в дифе и не назван в сводке. Список виден в манифесте, называется поимённо и
+// печатается КАЖДЫЙ прогон: совещательный гейт, о котором забыли, — это выключенная проверка,
+// и молчать о нём нельзя.
+function advisorySet(man) {
+  const v = man?.advisory;
+  if (Array.isArray(v)) return new Set(v.map((x) => String(x).trim()).filter(Boolean));
+  return new Set();
+}
+
 async function readManifest() {
   const p = join(CWD, MANIFEST);
   if (!(await exists(p))) return null;
@@ -130,7 +173,11 @@ async function readManifest() {
 }
 
 // Каждая ступень: что требуется, как проверяется, и что это даёт человеку.
-async function assessLevel(man) {
+// `proof` — результат `proveGates`: { ok } либо null, если доказательства не было. Ступень
+// AQK-2 требует его прямо: до 2026-09-07 она проверяла, что папки образцов и храповиков
+// СУЩЕСТВУЮТ, и проект с тремя гейтами `true` проходил порог AQK-3 с зелёным значком.
+// Проверено прогоном на пустой папке. Наличие папки — не защита; уровень обязан означать факт.
+async function assessLevel(man, proof = null) {
   const has = async (rel) => Boolean(rel) && (await exists(join(CWD, String(rel))));
   const isUrl = (v) => typeof v === "string" && /^https?:\/\//.test(v);
 
@@ -146,10 +193,21 @@ async function assessLevel(man) {
   const conditions = [
     Boolean(man?.aqk) && entriesExist,
     (await has(man?.rules)) && filledGates.length > 0,
-    (await has(man?.samples)) && (await has(man?.ratchets)),
+    (await has(man?.samples)) && (await has(man?.ratchets)) && proof?.ok === true,
     isUrl(man?.lessons) || (await has(man?.lessons)),
   ];
-  const steps = conditions.map((ok, level) => ({ level, ok, ...L.levels[level] }));
+  // Ступени, которым нужно доказательство, помечаются отдельно: «не выполнено» и «не проверяли»
+  // — разные состояния, и печатать их одинаково значит врать ровно тем способом, против
+  // которого весь комплект.
+  const NEEDS_PROOF = 2;
+  const steps = conditions.map((ok, level) => ({
+    level,
+    ok,
+    // Ровно вторая: третья ступень проверяет журнал, и посылать за доказательством там
+    // значит указать не на ту недостачу. Найдено код-ревью 2026-09-07.
+    needsProof: level === NEEDS_PROOF && proof === null,
+    ...L.levels[level],
+  }));
 
   let reached = -1;
   for (const s of steps) {
@@ -184,5 +242,5 @@ function manifestWithGate(text, slug, cmd) {
 
 export {
   parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
-  entryLifecycle,
+  entryLifecycle, advisorySet, layoutChecks,
 };