agent-quality-kit 0.7.0 → 0.9.0

package/tool/commands/vitals.mjs

@@ -0,0 +1,159 @@
+// tool/commands/vitals.mjs — «всё ли у самого комплекта подключено».
+//
+// ЗАЧЕМ ОТДЕЛЬНАЯ КОМАНДА. `doctor` смотрит на РЕПОЗИТОРИЙ, `prove` — на гейты, `context` —
+// на состояние. На саму обвязку не смотрит никто: стоят ли инструменты, которых требуют
+// объявленные гейты; прописан ли хук в `.git/hooks` НА САМОМ ДЕЛЕ, а не только в конфиге;
+// получает ли агент состояние. Сегодня это выясняется красным гейтом посреди коммита — в
+// худший момент из возможных, когда человек занят другим и просто выключит проверку.
+//
+// ЧЕТЫРЕ СОСТОЯНИЯ, А НЕ ДВА, И КАЖДОЕ ЗАРАБОТАНО.
+//   ✔  подключено;
+//   ✘  СЛОМАНО — объявленный гейт не состоится: нет инструмента, потеряна строка манифеста;
+//   ·  не подключено, и это выбор — хука pre-commit нет, потому что гоняют в конвейере;
+//   ~  посмотреть не смогли.
+//
+// Первая версия ставила `✘` хуку, которого нет. На нашем же репозитории вышло два креста за
+// сознательное решение: pre-commit локально мы не ставим, проверки идут в CI. Команда, которая
+// кричит «сломано» про выбор, — ровно та, которую выключают в первый день, и вместе с ней
+// перестают читать настоящие отказы. Кода возврата касается только `✘`.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CWD, MANIFEST, SELF, c, exists } from "../lib/core.mjs";
+import { readManifest, unparsedLines, gateRequires } from "../lib/manifest.mjs";
+import { whichSync } from "../lib/repo.mjs";
+import { updateWanted } from "../lib/brief.mjs";
+import { L } from "../i18n/index.mjs";
+
+// Чистая функция: на входе факты, на выходе строки. Отделена от чтения диска намеренно —
+// «неизвестно» проверяется перебором случаев, а не прогоном, потому что случай «не смогли
+// посмотреть» на исправной машине не воспроизвести.
+function vitalsRows(f) {
+  const t = L.vitals;
+  const missing = (f.tools || []).filter((x) => !x.found);
+  const rows = [
+    {
+      key: "tools",
+      ok: (f.tools || []).length === 0 ? null : missing.length === 0,
+      detail: missing.length
+        ? t.toolsMissing(missing.map((x) => `${x.prog} (${x.gate})`).join(", "))
+        : t.toolsOk((f.tools || []).length),
+    },
+    {
+      key: "manifest",
+      ok: f.unparsed > 0 ? false : true,
+      detail: f.unparsed > 0 ? t.manifestBad(f.unparsed) : t.manifestOk,
+    },
+    {
+      key: "preCommit",
+      ok: f.preCommit === null ? null : f.preCommit ? true : "no",
+      detail: f.preCommit === null ? t.unknownHook : f.preCommit ? t.preCommitOk : t.preCommitNo,
+    },
+    {
+      key: "sessionHook",
+      ok: f.sessionHook === null ? null : f.sessionHook ? true : "no",
+      detail: f.sessionHook === null ? t.unknownHook : f.sessionHook ? t.sessionOk : t.sessionNo(`${SELF} context --install`),
+    },
+  ];
+  // Устаревшая версия — не отказ: человек мог закрепить её сознательно, и ронять за это нельзя.
+  if (f.version) {
+    rows.push({
+      key: "version",
+      ok: null,
+      detail: f.version.latest && f.version.latest !== f.version.current
+        ? t.versionOld(f.version.latest, f.version.current)
+        : t.versionOk(f.version.current),
+    });
+  }
+  return rows;
+}
+
+function vitalsVerdict(rows) {
+  return rows.some((r) => r.ok === false) ? 1 : 0;
+}
+
+// Первое слово команды — та программа, без которой гейт не состоится. Обёртки снимаются:
+// `bash x.sh` требует bash, а не x.sh; `npx --yes knip@6` требует npx.
+function progOf(cmd) {
+  const parts = String(cmd || "").trim().split(/\s+/);
+  return parts[0] || "";
+}
+
+async function cmdVitals() {
+  const man = await readManifest();
+  const gates = man?.gates && typeof man.gates === "object" && !Array.isArray(man.gates) ? man.gates : {};
+
+  const seen = new Map();
+  for (const [gate, cmd] of Object.entries(gates)) {
+    const prog = progOf(cmd);
+    if (!prog || seen.has(prog)) continue;
+    seen.set(prog, { gate, prog, found: Boolean(whichSync(prog)) });
+  }
+
+  // Первого слова мало. Запись каталога бывает обёрткой: команда начинается с `bash`, который
+  // есть всегда, а работать без `slopcheck` или `zizmor` она не может — и `doctor --run`
+  // краснеет там, где `vitals` печатал «все инструменты на месте». Ровно тот разрыв, ради
+  // закрытия которого эта команда и заведена. Программа названа в `requires:` записи.
+  // Найдено 2026-09-09 сверкой вывода двух команд на одном репозитории.
+  const samplesDir = typeof man?.samples === "string" ? man.samples.trim() : "";
+  for (const gate of Object.keys(gates)) {
+    const missing = await gateRequires(samplesDir, gate, whichSync);
+    for (const prog of missing || []) {
+      if (seen.has(prog)) continue;
+      seen.set(prog, { gate, prog, found: false });
+    }
+  }
+
+  let unparsed = 0;
+  try { unparsed = unparsedLines(await readFile(join(CWD, MANIFEST), "utf8")).length; } catch { /* манифеста нет */ }
+
+  // Хук pre-commit проверяется в `.git/hooks`, а НЕ в `.pre-commit-config.yaml`. Запись в
+  // конфиге — это намерение; сработает только то, что лежит в самом гите. Ровно та разница,
+  // ради которой весь комплект: объявлено и работает — разные утверждения.
+  let preCommit = null;
+  const hook = join(CWD, ".git", "hooks", "pre-commit");
+  if (await exists(join(CWD, ".git"))) {
+    preCommit = false;
+    if (await exists(hook)) {
+      try { preCommit = /pre-commit|aqk/i.test(await readFile(hook, "utf8")); } catch { preCommit = null; }
+    }
+  }
+
+  let sessionHook = null;
+  const settings = join(CWD, ".claude", "settings.json");
+  if (await exists(join(CWD, ".claude"))) {
+    sessionHook = false;
+    if (await exists(settings)) {
+      try {
+        const s = JSON.parse(await readFile(settings, "utf8"));
+        sessionHook = JSON.stringify(s?.hooks?.SessionStart || []).includes("context");
+      } catch { sessionHook = null; }
+    }
+  }
+
+  let version = null;
+  if (updateWanted()) {
+    try {
+      const { PKG_ROOT } = await import("../lib/core.mjs");
+      const current = JSON.parse(await readFile(join(PKG_ROOT, "package.json"), "utf8")).version || "";
+      const r = await fetch("https://registry.npmjs.org/agent-quality-kit/latest", {
+        signal: AbortSignal.timeout(3000),
+        headers: { accept: "application/vnd.npm.install-v1+json" },
+      });
+      version = { current, latest: r.ok ? String((await r.json()).version || "") : "" };
+    } catch { /* сети нет — строку про версию просто не покажем */ }
+  }
+
+  const rows = vitalsRows({ tools: [...seen.values()], unparsed, preCommit, sessionHook, version });
+  console.log(c.bold(`\n  ${L.vitals.title}\n`));
+  for (const r of rows) {
+    const mark = r.ok === true ? c.green("✔")
+      : r.ok === false ? c.red("✘")
+      : r.ok === "no" ? c.yellow("·")
+      : c.dim("~");
+    console.log(`  ${mark}  ${L.vitals.names[r.key].padEnd(22)} ${r.ok === false ? r.detail : c.dim(r.detail)}`);
+  }
+  console.log("");
+  process.exit(vitalsVerdict(rows));
+}
+
+export { cmdVitals, vitalsRows, vitalsVerdict };

package/tool/i18n/en-docs.mjs

@@ -7,6 +7,130 @@
 // the second for one second in a terminal.
 
 const enDocs = {
+  // Блок vitals переехал сюда 2026-09-09 по той же причине, что и brief: терминальный
+  // каталог снова перерос 500 строк, и поймал это наш же file-size-limit.
+  vitals: {
+    title: "Is what the kit runs on actually wired up",
+    names: {
+      tools: "gate tools",
+      manifest: "manifest parsed",
+      preCommit: "pre-commit hook",
+      sessionHook: "state to the agent",
+      version: "version",
+    vitals: "is what the kit runs on wired up: tools, hooks, freshness",
+    },
+    toolsOk: (n) => `all ${n} present`,
+    toolsMissing: (l) => `NOT FOUND: ${l} — those gates will not happen`,
+    manifestOk: "parsed in full",
+    manifestBad: (n) => `${n} lines were not parsed and HAVE NO EFFECT — details in doctor`,
+    unknownHook: "could not look — unknown, not \"no\"",
+    preCommitOk: "wired in .git/hooks",
+    preCommitNo: "not in .git/hooks: a config entry is an intent, not a guard",
+    sessionOk: "the SessionStart hook hands the state to the agent",
+    sessionNo: (cmd) => `the agent gets no state: ${cmd}`,
+    versionOk: (v) => `${v}, current`,
+    versionOld: (l, cur) => `${l} is out, you have ${cur}`,
+  },
+  // Блок краткого вывода переехал сюда 2026-09-09: терминальный каталог снова перерос
+  // 500 строк, и поймал это наш же file-size-limit. Шов по смыслу условен — это всё-таки
+  // терминал, — но предел настоящий, а делить пополам хуже, чем делить по соседству.
+  brief: {
+    name: "AQK",
+    held: (n) => `holds ${n}`,
+    todo: (n) => `not installed ${n}`,
+    levelUnknown: "level unknown",
+    red: (l) => `     RED: ${l}`,
+    advise: (slug, why) => `     ↑ install: ${slug} — ${why}`,
+    adviseOff: (cmd, env) => `       not needed: ${cmd}, or ${env}`,
+    update: (l, c, how) => `version ${l} is out, you have ${c} — update: ${how}`,
+    updateHow: "npx agent-quality-kit@latest, or npm i -g agent-quality-kit",
+    updateHookHow: "pre-commit autoupdate",
+    updateOff: (env) => `       not needed: ${env}`,
+  },
+  // 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 +139,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,21 @@ 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",
+    version: "the banner and the version number — same as --version and -v",
     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",
@@ -68,6 +88,16 @@ export const en = {
     hasThings: "has",
     install: (cmd) => `install: ${cmd}`,
     notApplicable: (n) => `Not applicable to this repository (${n}):`,
+    noBrowserServer:
+      "this project has a UI, and the agent has no browser: it cannot look at its own change\n  and judges the work by what compiled. Those are different claims.",
+    noBrowserServerHow: (l) => `add an MCP server — works with any agent: ${l}`,
+    coveredBy: (n) => `held by another arbiter: ${n} — the portable entry is not needed`,
+    coveredByGate: (g) => `held by "${g}", declared in the manifest`,
+    coversUnknown: (l) => `covers names a gate absent from gates: ${l} — those entries are held by nothing`,
+    coversUnproven: (e, g, codes) =>
+      `claim unverified: "${e}" is declared held by gate "${g}", but neither its command nor the\n  linter config names rules ${codes} — the entry may be held by nothing`,
+    coversUnprovenHow: (cmd) => `settle it: add those rules to the linter, or install the entry — ${cmd}`,
+    totalCovered: (n) => `held by another arbiter ${n}`,
     total: "Total:",
     totalHeld: (n) => `held by a machine ${n}`,
     totalTodo: (n) => `applicable but not installed ${n}`,
@@ -77,6 +107,7 @@ export const en = {
     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})`,
+    advisoryQuiet: "(advisory — cannot fail the run)",
     advisoryMark: "advisory — shown, the run was not failed",
     advisorySummary: (names) =>
       `advisory and red: ${names.join(", ")}. These are switched-off checks: ` +
@@ -91,6 +122,9 @@ export const en = {
     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.`,
+    manifestUnparsed: (n, t) => `manifest line ${n} was not parsed and HAS NO EFFECT: ${t}`,
+    manifestUnparsedWhy:
+      "field and gate names use latin letters, digits, dash and underscore. What is declared here\n  does not run at all — while looking as if it does.",
     manifestKnown: (keys) => `Manifest fields: ${keys.join(", ")}`,
     thresholdPass: (min) => `Threshold AQK-${min} passed.`,
     thresholdFail: (min, now) => `Threshold AQK-${min} NOT passed: currently AQK-${now}.`,
@@ -145,6 +179,7 @@ export const en = {
       has_agent_config: ["the agent was never configured here", "agent settings exist"],
       has_agent_entry: ["no entry point for an agent here", "an entry point for an agent exists"],
       has_ui: ["no stylesheets or UI components in sight", "a UI exists: stylesheets or components"],
+      has_mcp: ["no MCP tools are wired up for the agent here", "MCP servers are declared"],
     },
   },
 
@@ -341,12 +376,14 @@ 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: {
     title: "If this was useful:",
     star: (url) => `Star it — ${url}`,
     issue: "Found a bug or it did not fit — open an issue; both are the most useful feedback there is.",
+    notRemembered: "could not remember this (home is not writable) — the message will appear again",
     once: "This message is shown once: it will not appear again on this machine.",
   },
 
@@ -428,6 +465,7 @@ export const en = {
     noTarget: "no place to substitute the sample directory — the command was written by hand",
     otherRecipe: (lang) => `the samples are written for the "${lang}" recipe, another one is installed — nothing to prove with`,
     noGates: "no gates declared — nothing to prove",
+    needsProgram: (progs) => `NOT CHECKED here — needs "${progs}"`,
     noSamplesDir: "the samples field in .aqk.yml is empty — nowhere to look for samples",
     nothingProven:
       "not a single gate is proven. A level above AQK-1 would mean trust in the author, not a fact:\n  a project whose gate is `true` would pass it exactly like a project with real protection.",
@@ -446,41 +484,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/index.mjs

@@ -11,23 +11,56 @@
 // хуже и расходятся молча. Каталоги лежат отдельно, и модульная проверка сверяет, что в них
 // одни и те же ключи: «поддерживаем два языка» — утверждение, которое обязана держать машина.
 
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { ru } from "./ru.mjs";
 import { en } from "./en.mjs";
 
 // Порядок: явная переменная окружения → системная локаль → английский. Английский последним
 // потому, что незнакомый язык интерфейса — это препятствие, а незнакомый английский в 2026-м
 // препятствие меньшее, чем незнакомая кириллица.
-function pickLang(env = process.env) {
+// Порядок: переменная окружения → ПОЛЕ МАНИФЕСТА → системная локаль → английский.
+//
+// Поле манифеста добавлено 2026-09-08 по просьбе первого чужого пользователя: «язык берётся из
+// LC_ALL/LANG, а на Windows их просто нет: русский проект получает английский вывод. AQK_LANG=ru
+// чинит, но у следующего человека будет своё». Он прав: язык репозитория — свойство репозитория,
+// а локаль — свойство машины, на которой его сегодня открыли.
+//
+// Переменная окружения оставлена ВЫШЕ манифеста намеренно: человек, набравший AQK_LANG=en
+// руками, хочет английский именно сейчас, и спорить с ним манифестом значит отнять у него
+// последнее средство. Манифест выше локали — он про проект, локаль про машину.
+function pickLang(env = process.env, man = null) {
   const forced = String(env.AQK_LANG || "").toLowerCase();
   if (forced.startsWith("ru")) return "ru";
   if (forced.startsWith("en")) return "en";
+  const declared = String(man?.lang || "").toLowerCase();
+  if (declared.startsWith("ru")) return "ru";
+  if (declared.startsWith("en")) return "en";
   const locale = String(env.LC_ALL || env.LC_MESSAGES || env.LANG || "").toLowerCase();
   if (locale.startsWith("ru")) return "ru";
   return "en";
 }
 
+// Язык читается СИНХРОННО и одним полем: каталог строк нужен раньше, чем что-либо успеет
+// прочитать манифест целиком, а полный разбор отсюда звать нельзя — manifest.mjs сам берёт
+// строки здесь, и вышло бы кольцо. Чтобы этот сокращённый разбор не разошёлся с настоящим,
+// модульная проверка сверяет их ответы на одном и том же тексте.
+function langFromText(text) {
+  const m = String(text).match(/^lang:[ \t]*["']?([A-Za-z][A-Za-z-]*)/m);
+  return m ? m[1] : "";
+}
+
+function manifestLang(cwd = process.cwd()) {
+  try {
+    return { lang: langFromText(readFileSync(join(cwd, ".aqk.yml"), "utf8")) };
+  } catch {
+    // Манифеста нет или он нечитаем — не повод падать: язык просто выберется дальше по порядку.
+    return null;
+  }
+}
+
 const CATALOGS = { ru, en };
-const LANG = pickLang();
+const LANG = pickLang(process.env, manifestLang());
 const L = CATALOGS[LANG];
 
-export { L, LANG, pickLang, CATALOGS };
+export { L, LANG, pickLang, langFromText, CATALOGS };