agent-quality-kit 0.7.0 → 0.8.0

package/tool/i18n/en-docs.mjs

@@ -7,6 +7,90 @@
 // the second for one second in a terminal.
 
 const enDocs = {
+  // THE STATE BLOCK — the one text of ours whose reader is a machine, not a person.
+  // It goes into the agent's context via a SessionStart hook, so it is written as claims of
+  // fact: no politeness, no preamble, every line either a fact or an honest "unknown".
+  context: {
+    title: "AQK — the state of this repository right now. Only what a machine computed; where it\ndoes not know, it says \"unknown\" — which is not the same as \"fine\".",
+    level: (r, top, missing) =>
+      `Level: AQK-${r} of ${top}.` + (missing ? ` AQK-${r + 1} is missing: ${missing}.` : ""),
+    levelUnknown: "Level: not computed — there is no .aqk.yml here. The standard is not set up.",
+    rules: (total, machine, human) =>
+      `Rules in the entry point: ${total}. Held by a machine ${machine}, by a human ${human}.`,
+    rulesNobody: "A rule held by a human is held by nobody: no machine checks it.",
+    runNone:
+      "No run has been made — which checks are red is UNKNOWN. This is not \"clean\": `aqk doctor --run`.",
+    runStale: (when) =>
+      `The last run ${when} is OLDER than the last commit — it describes different code.`,
+    runClean: (when) => `Last run ${when} — nothing red.`,
+    runRed: (when, names) => `Last run ${when} — RED: ${names}.`,
+    andMore: (n) => `and ${n} more`,
+    skipped: (n) => `Not run: ${n} — the tool is absent on this machine, their state is unknown.`,
+    ratchets: (list) => `Ratchets: ${list}. The list may only get shorter, never longer.`,
+    where: (entry) => `The rulebook: ${entry}. What proves a diff: \`aqk report --since main\`.`,
+    mapTitle: "WHAT THIS TOOL CAN DO. The full list of commands — not a retelling, the same list\nthe help is built from:",
+    rulesTitle: (e) => `THE RULEBOOK OF THIS PROJECT (${e}) — verbatim, in full. This is not an invitation\nto read it: it is already here.`,
+    hookAlready: (p) => `the hook is already in ${p} — changing nothing.`,
+    hookAdded: (p) => `SessionStart hook appended to ${p}:`,
+    hookCreated: (p) => `created ${p} with a SessionStart hook:`,
+    hookBadJson: (p) => `${p} does not parse as JSON — leaving it alone. Fix it and retry.`,
+    hookWhat:
+      "the project state now reaches the agent's context before its first action, not at its discretion.",
+  },
+  // Форма отчёта переехала сюда из терминального каталога 2026-09-08: это текст, который
+  // программа ПИШЕТ в .aqk/report.md, а не говорит в терминал. Повод — тот же гейт
+  // file-size-limit, что развёл эти файлы в первый раз: терминальный каталог снова перерос
+  // 500 строк. Шов по смыслу, а не пополам.
+  report2: {
+    evidenceNamed: (who) => `named by: ${who}`,
+    evidenceSilent: (n) => `${n} check${n === 1 ? "" : "s"} walked past it and said nothing`,
+    evidenceTitle: "What proves this diff",
+    evidenceUncovered: "no check named this file",
+    evidenceBase: "base of comparison",
+    evidenceHash: "evidence fingerprint",
+    evidenceBadRef: (r) => `ref "${r}" could not be resolved — coverage not computed`,
+    evidenceNoFiles: (r) => `no code files in the diff against "${r}" — nothing to prove`,
+    evidenceWarn:
+      "◻️ means a check walked the directory and said nothing. \"Scanned and clean\" and " +
+      "\"never looked\" are indistinguishable from the output, and neither may be passed off " +
+      "as the other. " +
+      "The fingerprint covers the base, the set of commands and the contents of the files. " +
+      "Change any of them and this report is stale, so \"ran it, then edited three more files\" " +
+      "stops being indistinguishable from \"ran it\". Mechanism taken from donecheck (MIT).",
+    title: "AQK report",
+    noManifest: (cmd) => `No .aqk.yml — nothing to report on. Start with ${cmd}`,
+    level: "Level",
+    holdsTitle: "What a machine holds (from a run, not from the manifest)",
+    nothingRuns: "⬜ no gate is declared",
+    native: (prog) => `native recipe: ${prog}`,
+    portable: "portable check",
+    weakerTitle: "Weaker than it could be",
+    weaker: (progs) => `${progs} is available on this system, but the gate uses the portable check — it catches less`,
+    missingTitle: "What is missing",
+    nothingMissing: "✅ every applicable entry is installed",
+    needsTool: (prog) => `needs ${prog} — not on this system`,
+    notInstalled: "applicable, but not installed",
+    hiddenTitle: "Not applicable to this repository",
+    readTitle: "What the kit told you to read",
+    readWarn:
+      "The mark only means the file is on disk. Whether it was read, the machine does not know " +
+      "and does not pretend to: that is answered by whoever is reporting.",
+    ignoreTitle: "What .aqkignore hides",
+    ignoreNone: "no .aqkignore file — nothing is hidden",
+    ignoreWarn:
+      "Hiding things silently is the same class as a silent gate: the gates do not look at these " +
+      "paths at all. A line here means there is no protection there, and will not be.",
+    whyTitle: "Why this matters — briefly",
+    whyNothing: "nothing to add: everything applicable is in place",
+    saved: (path) => `Saved: ${path}`,
+    docs: {
+      baseline: "the minimum a project needs, independent of language",
+      readyMade: "the map of off-the-shelf rules: look for a ready one before writing your own",
+      rulesGeneral: "general working rules",
+      rulesTesting: "rules about tests",
+      rulesSecurity: "rules about security",
+    },
+  },
   manifestDoc: {
     head: [
       "# .aqk.yml — the Agent Quality Kit manifest",
@@ -15,7 +99,7 @@ const enDocs = {
       "# and that is honest: filling it with placeholders is pointless, files are checked, not words.",
     ],
     entry: "# AQK-0 — what the agent reads first.",
-    rules: "# AQK-1 — where the standards are and which checks are mandatory.",
+    rules: "# AQK-1 — where the standards are and which checks are mandatory. docs — where the\n# guides are: doctor reads both, so the kit may live anywhere you like.",
     gates: [
       "  # name: a command returning 0 or non-zero. An empty declaration protects nothing and is",
       '  # rejected by the "a declared gate runs" check — hence examples here, not placeholders.',

package/tool/i18n/en.mjs

@@ -8,6 +8,18 @@ import { enDocs } from "./en-docs.mjs";
 import { templates } from "./templates-en.mjs";
 
 export const en = {
+  learn: {
+    title: "Said out loud, never written down",
+    noLogs: (p) => `no logs for this project: ${p}\n  The command reads Claude Code transcripts on this machine. Empty means nobody worked here.`,
+    counted: (s, typed, said, fresh) =>
+      `sessions: ${s} · typed by a human: ${typed} · looks like an instruction: ${said} · not in the entry point: ${fresh}`,
+    nothing: "everything that looks like a rule is already in the entry point",
+    andMore: (n) => `… and ${n} more`,
+    warn:
+      "These are CANDIDATES, not findings: measured on 1619 messages, the markers returned 79, and " +
+      "about half of those are real rules. The human decides. Nothing was written to disk — the " +
+      "command reads transcripts and prints to the terminal only.",
+  },
   ...enDocs,
   templates,
   help: {
@@ -27,13 +39,20 @@ export const en = {
     new: "scaffold your own gate for the catalogue",
     note: "record a lesson in the shared bruise journal",
     blob: "assemble the guides into a single GOD_AI.md",
-    report: "the mandatory report form: what is in place, what is not, what was not read",
+    learn: "rule candidates from local transcripts: said out loud, never written down",
+    context: "the project state in one block — for an agent's context, not for reading",
+    contextInstall: "the same in full — the map and the rulebook — installed as a hook",
+    report: "the mandatory report form: what is in place, what is not, what was not read; --since <ref> adds what proves the diff",
     badge: "a level badge for your README — and a check that it does not lie",
     noInstall: "Without installing:  npx agent-quality-kit init",
     language: "Output language: AQK_LANG=ru (or en), otherwise your system locale",
   },
 
   doctor: {
+    baselineClash: (f) =>
+      `"--baseline" is an inspection, not a run: it always exits 0, so together with "${f}" it\n` +
+      "  gives you a pipeline that cannot go red.\n" +
+      "  fix: split it in two — \"doctor --baseline\" and \"doctor --run --min 1\".",
     docsKit: "guides — the originals live here, not a copy",
     docs: "guides",
     rulesKit: "standards — the originals live here, not a copy",
@@ -341,6 +360,7 @@ export const en = {
     n4c: ". A gate guards an artefact that exists:",
     n4d: "a check for code that is not written yet is a dead rule.",
     burned: (cmd) => `Got burned by something — write it down: ${cmd}`,
+    hookHint: (cmd) => `Claude Code: ${cmd} — the project state will reach the agent's context\n  by itself, before its first action. Other agents have no hook, and that is not an omission.`,
   },
 
   feedback: {
@@ -446,41 +466,6 @@ export const en = {
     checkOk: (level, where) => `Badge matches the run: AQK-${level} — ${where}`,
   },
 
-  report2: {
-    title: "AQK report",
-    noManifest: (cmd) => `No .aqk.yml — nothing to report on. Start with ${cmd}`,
-    level: "Level",
-    holdsTitle: "What a machine holds (from a run, not from the manifest)",
-    nothingRuns: "⬜ no gate is declared",
-    native: (prog) => `native recipe: ${prog}`,
-    portable: "portable check",
-    weakerTitle: "Weaker than it could be",
-    weaker: (progs) => `${progs} is available on this system, but the gate uses the portable check — it catches less`,
-    missingTitle: "What is missing",
-    nothingMissing: "✅ every applicable entry is installed",
-    needsTool: (prog) => `needs ${prog} — not on this system`,
-    notInstalled: "applicable, but not installed",
-    hiddenTitle: "Not applicable to this repository",
-    readTitle: "What the kit told you to read",
-    readWarn:
-      "The mark only means the file is on disk. Whether it was read, the machine does not know " +
-      "and does not pretend to: that is answered by whoever is reporting.",
-    ignoreTitle: "What .aqkignore hides",
-    ignoreNone: "no .aqkignore file — nothing is hidden",
-    ignoreWarn:
-      "Hiding things silently is the same class as a silent gate: the gates do not look at these " +
-      "paths at all. A line here means there is no protection there, and will not be.",
-    whyTitle: "Why this matters — briefly",
-    whyNothing: "nothing to add: everything applicable is in place",
-    saved: (path) => `Saved: ${path}`,
-    docs: {
-      baseline: "the minimum a project needs, independent of language",
-      readyMade: "the map of off-the-shelf rules: look for a ready one before writing your own",
-      rulesGeneral: "general working rules",
-      rulesTesting: "rules about tests",
-      rulesSecurity: "rules about security",
-    },
-  },
 
 
 };

package/tool/i18n/ru-docs.mjs

@@ -7,6 +7,92 @@
 // вторые — он же в терминале, одну секунду.
 
 const ruDocs = {
+  // БЛОК СОСТОЯНИЯ — единственный наш текст, у которого читатель машина, а не человек.
+  // Уходит в контекст агента хуком SessionStart, поэтому пишется как утверждения о факте:
+  // без вежливости, без вводных, каждая строка либо факт, либо честное «неизвестно».
+  // Замер 2026-09-08: блок ≈147 токенов против ≈3348 у AGENTS.md — и несёт то, чего в файле
+  // нет и быть не может, потому что меняется каждый день.
+  context: {
+    title: "AQK — состояние этого репозитория на сейчас. Ниже только вычисленное машиной; где\nмашина не знает — сказано «неизвестно», и это не «всё хорошо».",
+    level: (r, top, missing) =>
+      `Уровень: AQK-${r} из ${top}.` + (missing ? ` До AQK-${r + 1} не хватает: ${missing}.` : ""),
+    levelUnknown: "Уровень: не вычислен — в репозитории нет .aqk.yml. Стандарт здесь не заведён.",
+    rules: (total, machine, human) =>
+      `Правил в точке входа: ${total}. Держит машина ${machine}, держит человек ${human}.`,
+    rulesNobody: "Правило, которое держит человек, не держит никто: машина его не проверяет.",
+    runNone:
+      "Прогон не делался — какие проверки красные, НЕИЗВЕСТНО. Это не «чисто»: `aqk doctor --run`.",
+    runStale: (when) =>
+      `Последний прогон ${when} СТАРЕЕ последнего коммита — он описывает не тот код, что здесь.`,
+    runClean: (when) => `Последний прогон ${when} — красных нет.`,
+    runRed: (when, names) => `Последний прогон ${when} — КРАСНЫЕ: ${names}.`,
+    andMore: (n) => `и ещё ${n}`,
+    skipped: (n) => `Не запускались: ${n} — инструмента нет на этой машине, их состояние неизвестно.`,
+    ratchets: (list) => `Храповики: ${list}. Список может только укорачиваться, увеличивать нельзя.`,
+    where: (entry) => `Свод правил: ${entry}. Чем доказан диф: \`aqk report --since main\`.`,
+    mapTitle: "ЧТО УМЕЕТ ЭТОТ ИНСТРУМЕНТ. Полный список команд — не пересказ, а тот же список,\nиз которого собрана справка:",
+    rulesTitle: (e) => `СВОД ПРАВИЛ ЭТОГО ПРОЕКТА (${e}) — дословно, целиком. Это не приглашение\nпрочитать: он уже здесь.`,
+    hookAlready: (p) => `хук уже стоит в ${p} — ничего не меняю.`,
+    hookAdded: (p) => `хук SessionStart дописан в ${p}:`,
+    hookCreated: (p) => `создан ${p} с хуком SessionStart:`,
+    hookBadJson: (p) => `${p} не разбирается как JSON — не трогаю его. Почини файл и повтори.`,
+    hookWhat:
+      "теперь состояние проекта попадает в контекст агента до первого действия, а не по его желанию.",
+  },
+  // Форма отчёта переехала сюда из терминального каталога 2026-09-08: это текст, который
+  // программа ПИШЕТ в .aqk/report.md, а не говорит в терминал. Повод — тот же гейт
+  // file-size-limit, что развёл эти файлы в первый раз: терминальный каталог снова перерос
+  // 500 строк. Шов по смыслу, а не пополам.
+  report2: {
+    evidenceNamed: (who) => `назван проверками: ${who}`,
+    evidenceSilent: (n) => `${n} ${n === 1 ? "проверка прошла" : "проверок прошли"} мимо и промолчали`,
+    evidenceTitle: "Чем доказан этот диф",
+    evidenceUncovered: "ни одна проверка не назвала этот файл",
+    evidenceBase: "база сравнения",
+    evidenceHash: "отпечаток доказательства",
+    evidenceBadRef: (r) => `ссылка «${r}» не разобрана — покрытие не считано`,
+    evidenceNoFiles: (r) => `файлов кода в дифе с «${r}» нет — доказывать нечего`,
+    evidenceWarn:
+      "◻️ означает: проверка обошла каталог и ничего не сказала. «Просмотрен и чист» и «не " +
+      "просмотрен вовсе» по выводу неразличимы — и выдавать одно за другое нельзя ни в ту, ни " +
+      "в другую сторону. " +
+      "Отпечаток считается по базе, набору команд и содержимому файлов. Изменилось что-то из " +
+      "этого — отчёт устарел, и «прогнал, потом поправил ещё три файла» перестаёт быть " +
+      "неотличимым от «прогнал». Механизм взят у donecheck (MIT).",
+    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: "правила про безопасность",
+    },
+  },
   manifestDoc: {
     head: [
       "# .aqk.yml — манифест Agent Quality Kit",
@@ -15,7 +101,7 @@ const ruDocs = {
       "# и это честно: заполнять заглушками бессмысленно, проверяются файлы, а не слова.",
     ],
     entry: "# AQK-0 — что агент читает первым.",
-    rules: "# AQK-1 — где стандарты и какие проверки обязательны.",
+    rules: "# AQK-1 — где стандарты и какие проверки обязательны. docs — где методички:\n# оба пути читает doctor, так что комплект можно разложить куда угодно.",
     gates: [
       "  # Имя: команда, возвращающая 0 или не 0. Пустое объявление защиты не даёт и бракуется",
       "  # проверкой «объявленный гейт запускается» — поэтому здесь примеры, а не заготовки.",

package/tool/i18n/ru.mjs

@@ -9,6 +9,18 @@ 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: {
@@ -28,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: "стандарты — здесь оригиналы, а не копия",
@@ -347,6 +366,7 @@ export const ru = {
     n4c: ". Гейт стережёт существующий артефакт:",
     n4d: "проверка на код, которого ещё нет, — мёртвое правило.",
     burned: (cmd) => `Обжёгся на чём-то — запиши: ${cmd}`,
+    hookHint: (cmd) => `Claude Code: ${cmd} — состояние проекта будет попадать в контекст агента\n  само, до первого действия. Для других агентов хука нет, и это не недоделка.`,
   },
 
   feedback: {
@@ -452,41 +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: "правила про безопасность",
-    },
-  },
 
 
 };

package/tool/lib/core.mjs

@@ -57,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);
@@ -114,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", "advisory"];
+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 [];
@@ -215,5 +242,5 @@ function manifestWithGate(text, slug, cmd) {
 
 export {
   parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
-  entryLifecycle, advisorySet,
+  entryLifecycle, advisorySet, layoutChecks,
 };

package/tool/lib/prove.mjs

@@ -63,7 +63,19 @@ function targetIsLast(parts) {
   return last === "." || last === "./";
 }
 
-function commandFor(cmd, dir) {
+// Путь уходит в СТРОКУ КОМАНДЫ, а её исполняет `sh` — не Node. Для `sh` обратный слэш это
+// экранирование, а не разделитель: `gates\\x\\red` превращается в `gatesxred`, каталога с таким
+// именем нет, обход молчит, гейт выходит с нулём — и доказательство объявляет ИСПРАВНЫЙ гейт
+// сломанным. Найдено вторым пользователем 2026-09-08 на Windows: `path.join` там даёт `\\`,
+// и падали ровно те записи, что обходят дерево через `find`; на `grep -r` выживали, потому что
+// Windows разбирает слэши сам. Худший из возможных отказов: комплект против «зелёного, потому
+// что ничего не проверялось» сам выдал зелёное за красное и отобрал у проекта ступень.
+// Нормализация стоит ЗДЕСЬ, а не у сборщика пути: это единственная дверь из мира путей Node
+// в мир оболочки, и закрывать её надо один раз, кто бы путь ни собрал.
+const forShell = (p) => String(p).replace(/\\/g, "/");
+
+function commandFor(cmd, dirRaw) {
+  const dir = forShell(dirRaw);
   const { parts, nativeAt } = unwrap(cmd);
   const out = parts.slice();
   out[out.length - 1] = dir;