agent-quality-kit 0.4.2 → 0.6.0

package/kit/ratchet/ratchet.sh

@@ -17,7 +17,12 @@ REG="${1:-}"; shift || true
 
 # Ключ нарушения обязан переживать правку соседних строк, иначе сдвиг на строку читается
 # как новое нарушение. Поэтому номер строки из ключа убирается.
-keys() { grep -E '^[^[:space:]].*:' | sed -E 's/:[0-9]+:/:/' | sort -u; }
+#
+# Два шаблона, а не один: у гейта duplicate-code строка несёт ДВА места — «a:171 и b:188: …»,
+# и за номером первого идёт не двоеточие, а пробел. Шаблон с двоеточием убирал номер только
+# у второго файла пары, и сдвиг кода в первом читался как новое нарушение — ровно то, от чего
+# храповик защищает.
+keys() { grep -E '^[^[:space:]].*:' | sed -E 's/:[0-9]+:/:/g; s/:[0-9]+( |$)/:\1/g' | LC_ALL=C sort -u; }
 
 OUT="$("$@" 2>&1)"
 NOW="$(printf '%s\n' "$OUT" | keys)"
@@ -26,7 +31,9 @@ if [ ! -f "$REG" ]; then
   echo "нет реестра $REG — сначала: aqk ratchet <гейт>"
   exit 2
 fi
-WAS="$(grep -vE '^\s*(#|$)' "$REG" | sort -u)"
+# Та же сортировка, что в keys(): comm сравнивает построчно и требует, чтобы оба входа были
+# упорядочены одинаково. Разная локаль у двух сторон — это тихо разъехавшееся сравнение.
+WAS="$(grep -vE '^\s*(#|$)' "$REG" | LC_ALL=C sort -u)"
 
 NEW="$(comm -23 <(printf '%s\n' "$NOW") <(printf '%s\n' "$WAS"))"
 GONE="$(comm -13 <(printf '%s\n' "$NOW") <(printf '%s\n' "$WAS"))"

package/kit/rules/general.md

@@ -7,6 +7,20 @@
 - **Ни одного тихого отказа.** Ошибка обработана и записана либо проброшена.
 - **Границы явные.** На стыках — проверка входа, а не доверие.
 
+## Сомнение — повод посмотреть наружу
+
+Агент отвечает уверенно всегда: и когда знает, и когда достраивает по памяти. Со стороны это
+неотличимо, а цена разная. Поэтому четыре случая обязаны кончаться поиском, а не догадкой:
+
+| Случай | Что происходит без поиска |
+|---|---|
+| не знаешь, как принято **сейчас** | пишется то, что было принято на момент обучения |
+| не знаешь, есть ли **готовое** | пишется свой велосипед, который потом чинить самому |
+| собираешься написать распространённую вещь | половина работы уже сделана кем-то и проверена |
+| помнишь ответ, но **из обучения, а не из проверки** | вспомненный API мог быть переименован или убран |
+
+Правило дешевле, чем кажется: поиск стоит минуту, а неверная догадка — правку, ревью и шишку.
+
 ## Запрещено в готовом коде
 
 - отладочная печать;

package/llms.txt

@@ -0,0 +1,58 @@
+# AQK — Agent Quality Kit
+
+> A standard and a CLI that check whether a repository is ready to have its code written by AI
+> coding agents. Every rule the project promises to follow becomes a command with an exit code,
+> so a machine holds the promise instead of somebody's attention. Reports a level from AQK-0 to
+> AQK-3, computed by a run — never by a questionnaire and never by a model's opinion.
+
+Vendor-neutral: works with any coding agent (Claude Code, Codex, Cursor, Gemini CLI, GitHub
+Copilot, Windsurf, Aider, OpenCode) and with no AI at all. It calls no vendor API and needs no
+key. Stack-neutral: portable checks are plain `sh`; where the project already has a native tool
+(ruff, eslint, knip, jscpd) the check uses it instead and says so when it falls back.
+
+Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
+
+## Use it
+
+- Check an existing repository: `npx agent-quality-kit doctor` (read-only: writes nothing, sends
+  nothing)
+- Start a new one: `npx agent-quality-kit start`
+- Install one guard from the catalogue: `npx agent-quality-kit add <name>`
+- Check the minimum a project needs before agents can be handed the work:
+  `npx agent-quality-kit doctor --baseline` (14 of 50 points confirmed by a run, ecosystem-neutral;
+  the other 36 are named as a number, not hidden)
+- Fail a pipeline below a level or on a failed gate: `npx agent-quality-kit doctor --run --min 1`
+- Show only what a diff introduced, so a legacy repo is usable from day one: `doctor --run --since main`
+- Exit codes: 0 pass, 1 below the level or a gate failed
+- As a pre-commit hook: `repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit` with
+  `id: aqk` (blocking), `aqk-doctor` (read-only) or `aqk-baseline`. pre-commit installs the
+  package itself; there are no dependencies to pull in.
+- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.4.2` with `min: 1`
+  (https://github.com/marketplace/actions/agent-quality-kit-aqk)
+
+## What makes it different
+
+- The level is computed by running what the repository declares — not from a self-assessment
+  questionnaire, not from the presence of a config file, not from a language model's judgement.
+- Every guard must ship a red and a green sample, and a machine checks that the guard goes red on
+  the red one and stays quiet on the green one. A check that cannot fail is indistinguishable
+  from a check that works; this is the only place that requirement is enforced.
+- An entry enters the catalogue only when it names a real failure it caught, recorded in the
+  bruise journal.
+
+## Files it reads and writes
+
+- `AGENTS.md` — what the agent reads first (the entry point; `CLAUDE.md` and others work too)
+- `.aqk.yml` — the manifest: entry, rules, gates as commands, samples, ratchets, lessons
+- `.aqkignore` — paths the scanning checks must not read (brought-in code, vendored, generated)
+
+## Documentation
+
+- [README](README.md): what it is, how to install, the catalogue, the badge, CI
+- [SPEC.md](SPEC.md): the standard itself — levels, manifest, how an entry is accepted
+- [Project baseline](kit/docs/ai/project-baseline.md): what a project needs before agents can be
+  handed the work, in plain words, independent of language and tooling
+- [The gate catalogue](kit/gates/README.md): what a gate is and the bar an entry must clear
+- [The bruise journal](incidents/README.md): every defect found, and what was made of it
+- [CONTRIBUTING.md](CONTRIBUTING.md): how to bring a gate
+- [SECURITY.md](SECURITY.md): reporting a vulnerability, and the trust model of the manifest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Turns the rules an agent is supposed to follow into commands with exit codes, and reports which of them actually run. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "kit",
     "README.md",
     "README.ru.md",
+    "llms.txt",
     "LICENSE"
   ],
   "engines": {
@@ -42,7 +43,8 @@
   ],
   "knip": {
     "entry": [
-      "tool/selfcheck/units.mjs"
+      "tool/selfcheck/units.mjs",
+    "tool/selfcheck/lifecycle.mjs"
     ],
     "project": [
       "tool/**/*.mjs"

package/tool/commands/doctor.mjs

@@ -3,11 +3,48 @@
 import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists } from "../lib/core.mjs";
-import { readManifest, assessLevel } from "../lib/manifest.mjs";
+import { scopeOutput, changedFiles } from "../lib/scope.mjs";
+import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists, die } from "../lib/core.mjs";
+import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict, recipeFor } from "../lib/repo.mjs";
+import { assessBaseline, DEP_FILES, BASELINE_TOTAL } from "../lib/baseline.mjs";
 import { L } from "../i18n/index.mjs";
 
+// Обязательный минимум проекта — прогоном, а не по памяти. До сих пор это было единственное
+// место, где комплект просил верить на слово, что человек прочитал методичку и сверился.
+async function reportBaseline(man, facts) {
+  const { readdir, readFile } = await import("node:fs/promises");
+  let files = [];
+  try {
+    files = (await readdir(CWD, { withFileTypes: true })).map((d) => d.name);
+  } catch { /* пустой список честнее выдуманного: ни один пункт не подтвердится */ }
+
+  // Файлы зависимостей читаются целиком и склеиваются: трекер ошибок объявляют по-разному в
+  // каждой экосистеме, а искать его надо одинаково.
+  let depsText = "";
+  for (const f of DEP_FILES) {
+    if (!files.some((n) => n.toLowerCase() === f)) continue;
+    try { depsText += (await readFile(join(CWD, f), "utf8")).toLowerCase() + "\n"; } catch { /* нечитаемый файл — просто не признак */ }
+  }
+
+  const rows = assessBaseline({ files, gateKeys: facts.gateKeys, facts, manifest: man || {}, depsText });
+  const okCount = rows.filter((r) => r.ok).length;
+
+  console.log(c.bold(`\n  ${L.baseline.heading}\n`));
+  console.log(c.dim(`  ${L.baseline.intro(rows.length, BASELINE_TOTAL)}`));
+  console.log(c.dim(`  ${L.baseline.caveat}\n`));
+  for (const r of rows) {
+    const mark = r.ok ? c.green("✔") : c.yellow("✘");
+    const title = L.baseline.titles[r.key] || r.key;
+    console.log(`  ${mark}  ${String(r.n).padStart(2)}. ${title}`);
+    console.log(c.dim(`        ${r.ok ? L.baseline.by(r.by) : L.baseline.none}`));
+  }
+  console.log(
+    "\n  " + (okCount === rows.length ? c.green(`${okCount}/${rows.length}`) : c.yellow(`${okCount}/${rows.length}`)) +
+      c.dim(`  ·  ${L.baseline.eyes(BASELINE_TOTAL - rows.length, "kit/docs/ai/project-baseline.md")}\n`)
+  );
+}
+
 async function reportCatalog(man, facts) {
   const catalog = await readCatalog();
   if (!catalog.length) return;
@@ -58,10 +95,27 @@ function declaredGates(man) {
     .filter(([, cmd]) => cmd);
 }
 
-function runGates(man) {
+// Ссылка, относительно которой сужается вывод: `--since main`, `--since HEAD~5`.
+// Без значения флаг бессмыслен — молча взять умолчание нельзя: «сужено не тем» неотличимо
+// от «не сужено».
+function sinceRef(argv = process.argv) {
+  const i = argv.indexOf("--since");
+  if (i === -1) return null;
+  const v = argv[i + 1];
+  return v && !v.startsWith("-") ? v : null;
+}
+
+function runGates(man, opts = {}) {
   const gates = declaredGates(man);
   if (!gates.length) return { failed: 0, ran: 0, results: [] };
 
+  // Сужение по дифу — договор с человеком, и он должен видеть, ЧТО именно сужено. Пустой диф
+  // называется вслух: иначе «все гейты зелёные» означало бы «сравнили не с тем» и читалось бы
+  // как успех. Это тот же класс, что и весь стандарт, только внутри нашего флага.
+  const scoped = opts.since ? changedFiles(opts.since, CWD) : null;
+  if (opts.since && scoped === null) die(L.doctor.sinceBadRef(opts.since));
+  if (scoped) console.log(c.dim(`\n  ${L.doctor.sinceHeading(opts.since, scoped.size)}`));
+
   console.log(c.bold(`\n  ${L.doctor.runHeading}\n`));
   let failed = 0;
   const results = [];
@@ -82,8 +136,30 @@ function runGates(man) {
       console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${cmd}`)}`);
       results.push({ name, cmd, ok: true, secs });
     } else {
+      let out = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
+
+      // Сужение до дифа. Три исхода, и все три называются вслух.
+      if (scoped) {
+        const s = scopeOutput(out, scoped);
+        if (!s.scopable) {
+          // Гейт печатает вердикт без путей — сузить нечем. Признать его успешным значило бы
+          // выдать провал за тишину; остаётся красным, и причина названа.
+          console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${L.doctor.notScopable}`)}`);
+          failed++;
+          results.push({ name, cmd, ok: false, secs, code, note: L.doctor.notScopable });
+          continue;
+        }
+        if (s.findings === 0) {
+          // Долг есть, но не в том, что внёс диф. Зелёный — но с числом спрятанного: молчаливое
+          // «всё хорошо» здесь было бы неправдой.
+          console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${L.doctor.outsideDiff(out.length)}`)}`);
+          results.push({ name, cmd, ok: true, secs, scopedAway: out.length });
+          continue;
+        }
+        out = s.kept;
+      }
+
       failed++;
-      const out = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
       console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${secs}s · ${cmd}`)}`);
       for (const line of out.slice(0, 3)) console.log(c.dim(`        ${line.slice(0, 100)}`));
       if (out.length > 3) console.log(c.dim(`        ${L.doctor.moreLines(out.length - 3)}`));
@@ -158,6 +234,15 @@ async function cmdDoctor() {
   }
 
   const man = await readManifest();
+
+  // Опечатка в имени поля означала «поля нет»: вердикт выдавался неверный, а причина молчала.
+  // Называем поле и говорим, какие бывают — иначе человек ищет ошибку в проекте, а она в файле.
+  const unknown = unknownKeys(man);
+  if (unknown.length) {
+    console.log(c.yellow(`\n  ${L.doctor.manifestUnknown(unknown)}`));
+    console.log(c.dim(`  ${L.doctor.manifestKnown(KNOWN_KEYS)}\n`));
+  }
+
   const { reached, steps } = await assessLevel(man);
 
   console.log(c.bold(`\n  ${L.doctor.levelHeading}\n`));
@@ -190,15 +275,21 @@ async function cmdDoctor() {
   }
 
   const facts = await detectFacts(man);
+  if (process.argv.includes("--baseline")) {
+    await reportBaseline(man, facts);
+    process.exit(0);
+  }
   await reportCatalog(man, facts);
 
   // «Объявлен» ≠ «работает». Без --run говорим это вслух, а не молчим.
   const wantRun = process.argv.includes("--run");
   const gates = declaredGates(man);
   let gateFailed = 0;
+  let failedNames = [];
   if (wantRun) {
-    const run = runGates(man);
+    const run = runGates(man, { since: sinceRef() });
     gateFailed = run.failed;
+    failedNames = run.results.filter((r) => !r.ok).map((r) => r.name);
     await writeRunReport({ version, reached, results: run.results });
   } else if (gates.length) {
     console.log(
@@ -211,12 +302,16 @@ async function cmdDoctor() {
   const minIdx = process.argv.indexOf("--min");
   const min = minIdx > -1 ? Number(process.argv[minIdx + 1]) : null;
   if (min !== null) {
-    const pass = reached >= min && gateFailed === 0;
-    console.log(
-      pass
-        ? c.green(`  ${L.doctor.thresholdPass(min)}\n`)
-        : c.red(`  ${L.doctor.thresholdFail(min, reached < 0 ? L.doctor.levelNone : reached)}\n`)
-    );
+    const levelOk = reached >= min;
+    const pass = levelOk && gateFailed === 0;
+    // Две разные развилки, и сообщение обязано их различать. «Порог не пройден: сейчас AQK-1»
+    // при пороге AQK-1 противоречит само себе и отправляет чинить манифест, когда падал гейт.
+    const now = reached < 0 ? L.doctor.levelNone : reached;
+    let line;
+    if (pass) line = c.green(`  ${L.doctor.thresholdPass(min)}\n`);
+    else if (!levelOk) line = c.red(`  ${L.doctor.thresholdFail(min, now)}\n`);
+    else line = c.red(`  ${L.doctor.thresholdGateFail(min, now, failedNames)}\n`);
+    console.log(line);
     process.exit(pass ? 0 : 1);
   }
   process.exit(missing || reached < 0 || gateFailed ? 1 : 0);

package/tool/commands/gates.mjs

@@ -8,7 +8,7 @@ import {
   CWD, PKG_ROOT, GATES_SRC, PROJECT_GATES, RATCHET_DIR, RATCHET_LIB, MANIFEST, SELF, c, exists, die,
   copyDir,
 } from "../lib/core.mjs";
-import { parseManifest, readManifest, manifestWithGate } from "../lib/manifest.mjs";
+import { parseManifest, readManifest, manifestWithGate, entryLifecycle } from "../lib/manifest.mjs";
 import {
   detectFacts, readCatalog, pickRecipe, triggerVerdict, stems, overlap, matchCatalog,
 } from "../lib/repo.mjs";
@@ -28,6 +28,13 @@ async function installGate(slug, man, facts) {
   if (!(await exists(src))) die(L.add.noSuchGate(slug, `${SELF} doctor`));
 
   const rec = { slug, ...parseManifest(await readFile(join(src, "gate.yml"), "utf8")) };
+
+  // Выведенную запись не ставим. Молча пропустить нельзя — человек пришёл за конкретной
+  // проверкой и обязан узнать, кто её заменил; ответ «а что теперь» и есть цена вывода.
+  // Проверка ДО копирования: иначе в проекте остаётся папка гейта, которого не будет в манифесте.
+  const life = entryLifecycle(rec);
+  if (life.state === "deprecated") return { rec, cmd: null, copied: [], declared: false, why: null, retired: life.supersededBy || "" };
+
   const dst = join(CWD, PROJECT_GATES, slug);
   await mkdir(dst, { recursive: true });
   const copied = await copyDir(src, dst, { force: false });
@@ -44,7 +51,13 @@ async function installGate(slug, man, facts) {
   let cmd = picked
     .replace(/\{gate\}/g, `${PROJECT_GATES}/${slug}`)
     .replace(/\{dir\}/g, ".");
-  if (!cmd) die(L.add.noRecipe(slug, [...facts.langs].join("/") || L.add.thisStack));
+  // Отказ, а не смерть. `add` ставит одну запись — там смерть уместна и остаётся в вызывающем.
+  // `start` ставит пачку, и падение на одной записи оставляло проект с тремя сторожами вместо
+  // двенадцати, без единого слова про остальные девять. Найдено прогоном на Windows: там нет
+  // ни `ruff`, ни `vulture`, и установка обрывалась на записи `dead-code`, которой нужен
+  // настоящий инструмент. Отсутствие сигнала неотличимо от успеха — здесь оно было внутри
+  // самой установки.
+  if (!cmd) return { rec, cmd: null, copied, declared: false, why: null, noRecipe: true };
 
   // Родной инструмент не знает про наши образцы и выдаёт их как находки — в любом проекте,
   // куда поставили гейты. Заворачиваем его в общий фильтр. Переносимая проверка фильтрует
@@ -81,7 +94,9 @@ async function cmdAdd(args) {
     console.log(c.dim(`  ${L.add.installAnyway}\n`));
   }
 
-  const { cmd, copied, declared, why } = await installGate(slug, man, facts);
+  const { cmd, copied, declared, why, noRecipe, retired } = await installGate(slug, man, facts);
+  if (retired !== undefined) die(L.lifecycle.installDeprecated(slug, retired ? `${SELF} add ${retired}` : "—"));
+  if (noRecipe) die(L.add.noRecipe(slug, [...facts.langs].join("/") || L.add.thisStack));
 
   console.log(c.bold(`\naqk add ${slug}\n`));
   console.log(`  ${c.green("✔")}  ${PROJECT_GATES}/${slug}/  ${c.dim(L.add.copied(copied.length))}`);

package/tool/commands/project.mjs

@@ -6,8 +6,7 @@ import { spawnSync } from "node:child_process";
 import { join, dirname, relative } from "node:path";
 import {
   CWD, PKG_ROOT, DOCS_SRC, RULES_SRC, TARGET_DIR, MANIFEST, SELF, REPO_URL, c, exists, die,
-  copyDir, writeIfAbsent, FEEDBACK_MARK,
-} from "../lib/core.mjs";
+  copyDir, writeIfAbsent, FEEDBACK_MARK, docPath } from "../lib/core.mjs";
 import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
 import { readManifest } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
@@ -199,7 +198,7 @@ async function cmdBlob() {
   await walk(dir);
 
   for (const full of found) {
-    out += `\n\n${"=".repeat(78)}\n<!-- ${L.blob.source(relative(PKG_ROOT, full))} -->\n${"=".repeat(78)}\n\n`;
+    out += `\n\n${"=".repeat(78)}\n<!-- ${L.blob.source(docPath(PKG_ROOT, full))} -->\n${"=".repeat(78)}\n\n`;
     // Ссылки на соседние файлы в склейке ведут в никуда: соседей рядом больше нет,
     // все они внутри этого же текста. Оставляем подпись, снимаем разметку.
     const body = (await readFile(full, "utf8")).replace(
@@ -268,7 +267,17 @@ async function cmdStart(args) {
       if (declared.has(rec.slug)) continue;
       const v = triggerVerdict(rec, facts0);
       if (!v.applies) { skipped.push([rec.slug, v.why]); continue; }
-      const { cmd } = await installGate(rec.slug, man, facts0);
+      const { cmd, noRecipe, retired } = await installGate(rec.slug, man, facts0);
+      // Выведенная запись в пачку не идёт, но и молчать о ней нельзя: она попадает в тот же
+      // список пропущенного с названным преемником.
+      if (retired !== undefined) {
+        skipped.push([rec.slug, L.lifecycle.installDeprecated(rec.slug, retired || "—")]);
+        declared.add(rec.slug); continue;
+      }
+      // Записи, которой нужен инструмент, а его на машине нет, здесь не место — но и вся
+      // установка из-за неё останавливаться не должна. Причина называется вслух и попадает
+      // в тот же список пропущенного, что и записи, не подошедшие по триггеру.
+      if (noRecipe) { skipped.push([rec.slug, L.start.noRecipeHere]); declared.add(rec.slug); continue; }
       put.push([rec.slug, cmd, rec.intent || ""]);
       declared.add(rec.slug);
       added++;

package/tool/commands/report.mjs

@@ -15,7 +15,7 @@
 
 import { mkdir, writeFile, readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
-import { CWD, TARGET_DIR, SELF, c, exists } from "../lib/core.mjs";
+import { CWD, TARGET_DIR, SELF, c, exists, docPath } from "../lib/core.mjs";
 import { readManifest, assessLevel } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict, whichSync } from "../lib/repo.mjs";
 import { runGates, declaredGates } from "./doctor.mjs";
@@ -59,7 +59,7 @@ async function findDoc(name) {
     for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
       const full = join(dir, e.name);
       if (e.isDirectory()) { const hit = await walk(full); if (hit) return hit; }
-      else if (e.name === name) return relative(CWD, full);
+      else if (e.name === name) return docPath(CWD, full);
     }
     return null;
   };

package/tool/i18n/en.mjs

@@ -15,6 +15,7 @@ export const en = {
     start: "no code yet: day-zero guards and the order of work",
     doctor: "check what is laid out and what is missing",
     doctorRun: "and also run the declared gates",
+    doctorSince: "the same, but show only what the diff against a ref introduced",
     add: "install a gate from the catalogue into the project",
     find: "is there already such a gate — matched by intent",
     why: "a bug slipped through — why did no guard catch it",
@@ -66,6 +67,10 @@ export const en = {
     totalTodo: (n) => `applicable but not installed ${n}`,
     totalSkip: (n) => `hidden ${n}`,
 
+    sinceHeading: (ref, n) => `narrowed to the diff against ${ref}: ${n} files touched`,
+    sinceBadRef: (ref) => `cannot compare against "${ref}": no such ref, or this is not a git repository`,
+    notScopable: "output carries no paths — cannot be narrowed by diff, left red",
+    outsideDiff: (n) => `findings exist, but outside the diff (${n})`,
     runHeading: "Running the declared gates",
     timeout: "did not finish within 5 minutes",
     exitCode: (code) => `exit ${code}`,
@@ -73,8 +78,44 @@ export const en = {
     declaredNotRun: (n) => `${n} gates declared, but never run.`,
     declaredNotRunWhy: (cmd) => ` "declared" and "works" are different claims: ${cmd}`,
 
+    manifestUnknown: (keys) =>
+      `The manifest has fields the standard does not know: ${keys.join(", ")}. Looks like a typo — ` +
+      `such a field is silently read as absent, and the verdict comes out wrong.`,
+    manifestKnown: (keys) => `Manifest fields: ${keys.join(", ")}`,
     thresholdPass: (min) => `Threshold AQK-${min} passed.`,
     thresholdFail: (min, now) => `Threshold AQK-${min} NOT passed: currently AQK-${now}.`,
+    thresholdGateFail: (min, now, names) =>
+      `Threshold AQK-${min} passed (currently AQK-${now}), but a gate failed: ${names.join(", ")}.`,
+  },
+
+  baseline: {
+    heading: "The minimum a project needs",
+    intro: (checked, total) =>
+      `a machine confirms ${checked} of ${total} points; the rest are for your eyes, in the guide`,
+    eyes: (n, path) => `${n} points a machine cannot check — they live in ${path}`,
+    caveat: "presence is what gets checked, not whether it works: \"a linter is configured\" and \"a linter catches things\" are different claims",
+    by: (b) =>
+      "proven by: " +
+      ({ gate: `gate ${b.value}`, fact: `repository scan: ${b.value}`,
+         manifest: `field ${b.value} in the manifest`, dep: `dependency ${b.value}`,
+         file: b.value }[b.kind] || b.value),
+    none: "no conventional marker — check by eye, it may be done another way",
+    titles: {
+      oneCommand: "one command brings the whole project up",
+      lockfile: "exact versions pinned in a lockfile",
+      sameEnv: "the environment is the same for everyone and in CI",
+      formatter: "formatting is uniform and applied automatically",
+      linter: "a linter is configured",
+      types: "type checking exists",
+      secretScan: "secret scanning",
+      fileSize: "a file size limit",
+      ownInvariants: "the project's own invariants",
+      tests: "arbiters of correctness: tests exist",
+      pipeline: "a pipeline exists",
+      errorTracker: "errors are collected separately from logs",
+      machineReadable: "the project is machine-readable",
+      rulesInRepo: "rules live in the repository and are versioned",
+    },
   },
 
   trigger: {
@@ -91,6 +132,7 @@ export const en = {
       has_deps: ["no dependency file in sight", "dependencies are declared"],
       has_tests: ["no tests in sight", "tests exist"],
       has_env: ["no environment file", "an environment file exists"],
+      has_ui: ["no stylesheets or UI components in sight", "a UI exists: stylesheets or components"],
     },
   },
 
@@ -99,6 +141,18 @@ export const en = {
     none: "no recipe described",
   },
 
+  // Entry maturity. Computed from the entry's proof; it cannot be declared — see
+  // entryLifecycle in tool/lib/manifest.mjs.
+  lifecycle: {
+    stable: "proven by an incident from the journal",
+    experimental: "proof is not from the journal — the entry is provisional",
+    deprecated: "retired",
+    unknownReplacement: (v) => `superseded_by: ${v} — no such entry in the catalogue`,
+    noReplacement: "lifecycle: deprecated without superseded_by — no replacement is named",
+    notDeclarable: (v) => `lifecycle: ${v} cannot be declared — maturity is computed from the proof`,
+    unknown: (v) => `lifecycle: ${v} — no such state; only deprecated is declared`,
+    installDeprecated: (slug, by) => `entry ${slug} is retired, ${by} replaces it`,
+  },
   manifest: {
     noGatesBlock: "no gates: block in .aqk.yml",
     alreadyDeclared: "already declared",
@@ -299,6 +353,7 @@ export const en = {
   },
 
   start: {
+    noRecipeHere: "needs a tool that is not on this machine",
     initFailed: (cmd) => `Could not lay out the kit. Start with ${cmd}`,
     tooManyFiles: (n) => `This repository already has ${n} code files — that is a different scenario.`,
     useDoctor: (cmd) => `${cmd} will inspect what is here and split the entries into three lists:`,

package/tool/i18n/ru.mjs

@@ -16,6 +16,7 @@ export const ru = {
     start: "кода ещё нет: сторожа дня 0 и порядок работы",
     doctor: "проверить, что разложено и чего не хватает",
     doctorRun: "ещё и запустить объявленные гейты",
+    doctorSince: "то же, но показать только то, что внёс диф относительно ссылки",
     add: "поставить гейт из каталога в проект",
     find: "есть ли уже такой гейт — сверка по намерению",
     why: "поймал ошибку — почему её не поймал сторож",
@@ -67,6 +68,10 @@ export const ru = {
     totalTodo: (n) => `применимо но не поставлено ${n}`,
     totalSkip: (n) => `скрыто ${n}`,
 
+    sinceHeading: (ref, n) => `сужено до дифа относительно ${ref}: файлов затронуто ${n}`,
+    sinceBadRef: (ref) => `не могу сравнить с «${ref}»: такой ссылки нет или это не репозиторий git`,
+    notScopable: "вывод без путей — дифом не сужается, оставлен красным",
+    outsideDiff: (n) => `находки есть, но вне дифа (${n})`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
     exitCode: (code) => `код ${code}`,
@@ -74,8 +79,49 @@ export const ru = {
     declaredNotRun: (n) => `${n} гейтов объявлено, но не запускалось.`,
     declaredNotRunWhy: (cmd) => ` «Объявлен» и «работает» — разные утверждения: ${cmd}`,
 
+    manifestUnknown: (keys) =>
+      `В манифесте поля, которых стандарт не знает: ${keys.join(", ")}. Похоже на опечатку — ` +
+      `такое поле молча читается как отсутствующее, и вердикт выходит неверным.`,
+    manifestKnown: (keys) => `Поля манифеста: ${keys.join(", ")}`,
     thresholdPass: (min) => `Порог AQK-${min} пройден.`,
     thresholdFail: (min, now) => `Порог AQK-${min} НЕ пройден: сейчас AQK-${now}.`,
+    // Ступень взята, но прогон красный — это другое утверждение, и виновника называем сразу:
+    // иначе его ищут глазами выше по логу конвейера.
+    thresholdGateFail: (min, now, names) =>
+      `Порог AQK-${min} пройден (сейчас AQK-${now}), но упал гейт: ${names.join(", ")}.`,
+  },
+
+  baseline: {
+    heading: "Обязательный минимум проекта",
+    intro: (checked, total) =>
+      `машина подтверждает ${checked} пунктов из ${total}; остальные — глазами, по методичке`,
+    eyes: (n, path) => `${n} пунктов машина проверить не может — они в ${path}`,
+    caveat: "проверяется НАЛИЧИЕ признака, а не то, что он работает: «линтер настроен» и «линтер ловит» — разные утверждения",
+    by: (b) =>
+      "подтверждено: " +
+      ({ gate: `гейт ${b.value}`, fact: `осмотр репозитория: ${b.value}`,
+         manifest: `поле ${b.value} в манифесте`, dep: `зависимость ${b.value}`,
+         file: b.value }[b.kind] || b.value),
+    // «Не найдено» и «нет» — разные утверждения. Признак ищется по общепринятым именам; проект
+    // может делать то же самое своим способом, и тогда пункт остаётся человеку, а не считается
+    // проваленным. Иначе прибор врёт на первом же нестандартном проекте — на нас самих и врал.
+    none: "общепринятого признака нет — проверь глазами, возможно сделано иначе",
+    titles: {
+      oneCommand: "одна команда поднимает проект целиком",
+      lockfile: "точные версии записаны в файл-замок",
+      sameEnv: "среда одинакова у всех и в конвейере",
+      formatter: "форматирование единое и применяется автоматически",
+      linter: "линтер настроен",
+      types: "проверка типов есть",
+      secretScan: "поиск секретов",
+      fileSize: "ограничение размера файла",
+      ownInvariants: "свои инварианты проекта",
+      tests: "арбитры правильности: тесты есть",
+      pipeline: "конвейер есть",
+      errorTracker: "ошибки собираются отдельно от логов",
+      machineReadable: "проект читается машиной",
+      rulesInRepo: "правила живут в репозитории и версионируются",
+    },
   },
 
   trigger: {
@@ -92,6 +138,7 @@ export const ru = {
       has_deps: ["не видно файла зависимостей", "зависимости объявлены"],
       has_tests: ["не видно тестов", "тесты есть"],
       has_env: ["нет файла окружения", "файл окружения есть"],
+      has_ui: ["не видно стилей и компонентов интерфейса", "интерфейс есть: стили или компоненты"],
     },
   },
 
@@ -100,6 +147,19 @@ export const ru = {
     none: "рецепт не описан",
   },
 
+  // Зрелость записи каталога. Считается по доказательству; объявить её нельзя — см.
+  // entryLifecycle в tool/lib/manifest.mjs.
+  lifecycle: {
+    stable: "доказана шишкой из журнала",
+    experimental: "доказательство не из журнала — запись условная",
+    deprecated: "выведена из употребления",
+    unknownReplacement: (v) => `superseded_by: ${v} — такой записи в каталоге нет`,
+    noReplacement: "lifecycle: deprecated без superseded_by — не назван тот, кто заменяет",
+    notDeclarable: (v) => `lifecycle: ${v} объявлять нельзя — зрелость считается по доказательству`,
+    unknown: (v) => `lifecycle: ${v} — такого состояния нет; объявляется только deprecated`,
+    installDeprecated: (slug, by) =>
+      `запись ${slug} выведена из употребления, её заменяет ${by}`,
+  },
   manifest: {
     noGatesBlock: "в .aqk.yml нет блока gates:",
     alreadyDeclared: "уже объявлен",
@@ -300,6 +360,7 @@ export const ru = {
   },
 
   start: {
+    noRecipeHere: "нужен инструмент, которого нет на этой машине",
     initFailed: (cmd) => `Не получилось разложить комплект. Начни с ${cmd}`,
     tooManyFiles: (n) => `В репозитории уже ${n} файлов кода — это другой сценарий.`,
     useDoctor: (cmd) => `${cmd} осмотрит, что есть, и разделит записи на три списка:`,

package/tool/i18n/templates-en.mjs

@@ -11,17 +11,17 @@ const AGENTS_MD = `# AGENTS.md
 
 ## Hard rules
 
-- **A plan before code.** A non-trivial task starts with a plan a human approved in words.
-- **A red test before code.** First a check that fails, then the implementation.
-- **Three attempts maximum.** Not solved in three — stop and ask a human, not a fourth try.
-- **Secrets only in the environment.** Never in code, logs or commits.
-- **Only the files the task is about.** No fixing things "while we are here".
-- **Done = proven.** Name the arbiter: a test, a live run, a check against the source.
+- **A plan before code.** A non-trivial task starts with a plan a human approved in words.  <!-- aqk: human -->
+- **A red test before code.** First a check that fails, then the implementation.  <!-- aqk: human -->
+- **Three attempts maximum.** Not solved in three — stop and ask a human, not a fourth try.  <!-- aqk: human -->
+- **Secrets only in the environment.** Never in code, logs or commits.  <!-- aqk: secrets-not-in-code -->
+- **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.
-- **A fork in the road is a question for a human.** Departing from an agreed decision is not
+- **Never swallow an error.** Either handled and logged, or re-raised.  <!-- aqk: swallowed-error -->
+- **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
+- **Report on your work with the kit with a command, not with words.** When you are done, run  <!-- aqk: human -->
   \`aqk report\`. It is assembled from an actual run: a summary from memory always picks the
   convenient parts and stays quiet about a gate standing on the weakest recipe.