agent-quality-kit 0.15.0 → 0.16.0

package/tool/commands/feedback.mjs

@@ -17,6 +17,7 @@
 // репозитория в отчёте нет — иначе первый же внимательный читатель назовёт это телеметрией,
 // и будет прав.
 import { readFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
 import { PKG_ROOT, SELF, REPO_URL, c, stateDirs } from "../lib/core.mjs";
 import { askAllowed, markAsked } from "../lib/ask.mjs";
 import { join } from "node:path";
@@ -65,6 +66,9 @@ function reportText(state = {}, T = L.feedback.report) {
     "",
     T.say,
     "",
+    // Слова человека — туда же, где приглашение их написать. Пусто — остаётся приглашение:
+    // отправленное письмо без единой своей строки всё равно полезно, но сказать об этом надо.
+    ...(state.note ? [state.note, ""] : []),
     T.mark(state.version || u),
   ];
 }
@@ -110,6 +114,65 @@ async function maybeAsk(state, self, { agent = false } = {}) {
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// ОТПРАВКА — ТОЛЬКО ПО ЯВНОМУ СЛОВУ, И СЛОВО ЭТО `--send`.
+//
+// Владелец 2026-09-14 спросил, нельзя ли отправлять отзыв «без согласия пользователя, чтобы
+// агент мог быстро сообщить». Нельзя, и не из вежливости: в README и SECURITY.md написано, что
+// исходящий запрос у комплекта ровно один — про версию. Инструмент, который втихую шлёт что-то
+// из ЧУЖОГО репозитория, становится ровно тем, что мы критикуем, а наша аудитория — это те, кто
+// проверяет инструменты на вранье. Одного внимательного читателя хватит.
+//
+// Поэтому согласие живёт в самом флаге: `--send` не набирают случайно, а агенту в умениях
+// сказано показать текст человеку и спросить. Утверждение «без флага не уходит ничего» держит
+// машина — smoke/feedback-send.test.mjs, — а не наше обещание в документации.
+//
+// ОТ ЧЬЕГО ИМЕНИ. От самого человека, его же `gh`. Своего сервера у нас нет и не будет: он
+// означал бы приём чужих данных, а значит и ответственность за них.
+const DISCUSSION = 90;
+
+function sendWanted(argv = process.argv) {
+  return argv.includes("--send");
+}
+
+// Своя строка человека — самое ценное во всём письме. Берём всё, что не флаг.
+function userNote(argv = process.argv) {
+  const i = argv.indexOf("feedback");
+  return (i === -1 ? [] : argv.slice(i + 1)).filter((a) => !a.startsWith("-")).join(" ").trim();
+}
+
+// Чем звать gh. Подменяется `AQK_GH` — тот же приём, что у `AQK_BASH` в execution.mjs: у всего,
+// что мы решаем сами, обязан быть способ решить иначе. Через него же проверки подставляют
+// поддельный gh и убеждаются, что без флага его не зовут вовсе.
+function ghArgs(env = process.env) {
+  return String(env.AQK_GH || "gh").split(/\s+/).filter(Boolean);
+}
+
+// Запуск БЕЗ оболочки: в теле отзыва переносы строк, кавычки и обратные апострофы, и оболочка
+// разобрала бы их как свои. Доводы уходят массивом — разбирать нечего.
+function gh(args, timeout = 30000) {
+  const [bin, ...pre] = ghArgs();
+  return spawnSync(bin, [...pre, ...args], { encoding: "utf8", timeout });
+}
+
+const Q_ID = `query($o:String!,$n:String!){repository(owner:$o,name:$n){discussion(number:${DISCUSSION}){id}}}`;
+const Q_ADD = "mutation($id:ID!,$body:String!){addDiscussionComment(input:{discussionId:$id,body:$body}){comment{url}}}";
+
+// Три исхода, как везде: отправлено · не смогли и сказали почему · входа нет. Молчаливый отказ
+// означал бы, что человек считает отзыв ушедшим, а его нет.
+function postComment(body, repo) {
+  if (gh(["auth", "status"], 15000).status !== 0) return { ok: false, reason: "no-auth" };
+  const [owner, name] = repo;
+  const one = gh(["api", "graphql", "-f", `query=${Q_ID}`, "-f", `o=${owner}`, "-f", `n=${name}`]);
+  let id = "";
+  try { id = JSON.parse(one.stdout || "{}").data.repository.discussion.id; } catch { /* разберём ниже */ }
+  if (!id) return { ok: false, reason: "no-thread" };
+  const two = gh(["api", "graphql", "-f", `query=${Q_ADD}`, "-f", `id=${id}`, "-f", `body=${body}`]);
+  let url = "";
+  try { url = JSON.parse(two.stdout || "{}").data.addDiscussionComment.comment.url; } catch { /* разберём ниже */ }
+  return url ? { ok: true, url } : { ok: false, reason: "failed" };
+}
+
 // Предзаполненная ссылка. Параметры `title` и `body` — документация GitHub («Creating an issue
 // from a URL query», сверено 2026-09-14). Кодируется ВСЁ: в теле переносы строк, решётки и
 // пробелы, и незакодированная ссылка обрывается на первом же из них — а всё после решётки
@@ -142,13 +205,24 @@ async function cmdFeedback() {
     version, node: process.version, platform: process.platform, level,
     langs: facts?.langs ? [...facts.langs] : [],
     gates: declaredGates(man).length,
-    red: run?.red || [], cannot: run?.cannot || [], blind,
+    red: run?.red || [], cannot: run?.cannot || [], blind, note: userNote(),
   });
   const body = lines.join("\n");
   console.log(`\n${body}\n`);
+
+  // ОТПРАВКА — ТОЛЬКО ПО ФЛАГУ. Без него ниже печатается ссылка, и это весь путь наружу.
+  if (sendWanted()) {
+    console.log(c.dim(`  ${T.sending}`));
+    const repo = REPO_URL.replace(/^https?:\/\/github\.com\//, "").split("/");
+    const r = postComment(body, repo);
+    if (r.ok) { console.log(c.green(`  ${T.sent(r.url)}\n`)); return; }
+    console.log(c.yellow(`  ${T.sendFailed[r.reason] || T.sendFailed.failed}\n`));
+  }
+
   console.log(c.bold(`  ${T.how}`));
   console.log(`  ${issueUrl(REPO_URL, T.issueTitle, body)}\n`);
   console.log(c.dim(`  ${T.nothingSent}`));
+  console.log(c.dim(`  ${T.sendHow(`${SELF} feedback --send`)}`));
   console.log(c.dim(`  ${T.orPaste(`${SELF} feedback`)}\n`));
   // Код возврата всегда 0: команда, которая просит об одолжении и роняет при этом конвейер, —
   // последнее, что человек стерпит.

package/tool/commands/gates.mjs

@@ -15,7 +15,7 @@ import {
 } from "../lib/repo.mjs";
 import { GATE_YML_TEMPLATE, CHECK_SH_TEMPLATE, README_TEMPLATE } from "../lib/templates.mjs";
 import { L } from "../i18n/index.mjs";
-import { gateCommand } from "../lib/execution.mjs";
+import { gateCommand, gateTimeout } from "../lib/execution.mjs";
 
 // Ставит гейт из каталога в проект. Проверка КОПИРУЕТСЯ в репозиторий, а не остаётся
 // ссылкой в пакет: при установке через npx пакет временный, и завтра команда в манифесте
@@ -43,7 +43,11 @@ async function installGate(slug, man, facts) {
 
   // Общий список исключений едет вместе с проверкой: без него она читает окружение и
   // зависимости, и человек получает тысячу чужих нарушений вместо сотни своих.
-  for (const helper of ["_skip.sh", "_native.sh"]) {
+  // `_target.sh` добавлен 2026-09-15 вместе с общим швом «судим только то, что можем разрешить».
+  // Без него скопированный гейт выходит с кодом 2 — это честно, но у человека он не работает.
+  // Поймано нашим же смоуком в день правки: список помощников тут — единственное место, и
+  // забыть его значит выпустить гейт, который у чужого проекта не запускается вовсе.
+  for (const helper of ["_skip.sh", "_native.sh", "_target.sh"]) {
     const from = join(GATES_SRC, helper);
     if (await exists(from)) await copyFile(from, join(CWD, PROJECT_GATES, helper));
   }
@@ -170,8 +174,10 @@ async function cmdNew(args) {
   // зовут установленные записи каталога. В самом комплекте оригинал уже лежит на месте (../),
   // в чужом проекте его никто не клал, пока не было ни одной установленной записи через `add`.
   if (!inKit) {
-    const skipSrc = join(GATES_SRC, "_skip.sh");
-    if (await exists(skipSrc)) await copyFile(skipSrc, join(CWD, PROJECT_GATES, "_skip.sh"));
+    for (const helper of ["_skip.sh", "_target.sh"]) {
+      const from = join(GATES_SRC, helper);
+      if (await exists(from)) await copyFile(from, join(CWD, PROJECT_GATES, helper));
+    }
   }
 
   console.log(c.bold(`\naqk new ${slug}\n`));
@@ -231,7 +237,7 @@ async function cmdRatchet(args) {
 
   // Снимок текущих нарушений — это и есть долг. Ключ без номера строки: правка соседней
   // строки не должна читаться как новое нарушение.
-  const r = spawnSync(gateCommand(inner), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+  const r = spawnSync(gateCommand(inner), { shell: true, cwd: CWD, encoding: "utf8", timeout: gateTimeout().ms });
   if (r.status === 127 || (r.error && r.error.code === "ENOENT")) {
     die(L.ratchet.notRunnable(slug, inner));
   }
@@ -439,7 +445,7 @@ async function cmdWhy(args) {
 
   // --- 3. объявлен: спрашиваем у него самого ---------------------------------
   console.log(c.dim(`  ${L.why.declaredAs(cmd)}`));
-  const r = spawnSync(gateCommand(String(cmd)), { shell: true, cwd: CWD, encoding: "utf8", timeout: 300000 });
+  const r = spawnSync(gateCommand(String(cmd)), { shell: true, cwd: CWD, encoding: "utf8", timeout: gateTimeout().ms });
   const ci = await runsInCi(slug, String(cmd));
 
   if (r.status === 127 || (r.error && r.error.code === "ENOENT")) {

package/tool/commands/report.mjs

@@ -215,11 +215,27 @@ async function cmdReport() {
 
   const text = lines.join("\n") + "\n";
   const dst = join(CWD, TARGET_DIR, "report.md");
-  await mkdir(join(CWD, TARGET_DIR), { recursive: true });
-  await writeFile(dst, text, "utf8");
+
+  // ОТЧЁТ — ЭТО ЧТЕНИЕ, И ПАДАТЬ ЕМУ НЕ НА ЧЕМ. Разбор чужой интеграции 2026-09-16: в рабочей
+  // области, где `.aqk/` не создать, команда падала с EROFS, не напечатав ни строки. То есть
+  // побочное действие, о котором не просили, отменяло то, ради чего команду звали. Такие
+  // области бывают не по недосмотру: read-only контейнер, чужой конвейер, каталог под ревью.
+  //
+  // Молчать о несохранённом тоже нельзя: человек, увидевший отчёт, вправе считать, что файл
+  // лежит на диске, — если ему не сказали иначе. Тот же принцип, что и везде: не смогли —
+  // назови, а не выдавай за сделанное.
+  let saveError = null;
+  try {
+    await mkdir(join(CWD, TARGET_DIR), { recursive: true });
+    await writeFile(dst, text, "utf8");
+  } catch (e) {
+    saveError = e?.code || String(e?.message || e);
+  }
 
   console.log("\n" + text);
-  console.log(c.dim(`  ${L.report2.saved(join(TARGET_DIR, "report.md"))}\n`));
+  console.log(saveError
+    ? c.yellow(`  ${L.report2.notSaved(join(TARGET_DIR, "report.md"), saveError)}\n`)
+    : c.dim(`  ${L.report2.saved(join(TARGET_DIR, "report.md"))}\n`));
 
   // Код возврата — для конвейера и для агента: отчёт с красным гейтом не должен читаться
   // как «всё в порядке» только потому, что команда выполнилась.

package/tool/commands/vitals.mjs

@@ -45,10 +45,16 @@ function vitalsRows(f) {
       ok: f.unparsed > 0 ? false : true,
       detail: f.unparsed > 0 ? t.manifestBad(f.unparsed) : t.manifestOk,
     },
+    // ЧЕТЫРЕ ОТВЕТА ПРО ХУК. «Хук чужой» — не «хука нет»: в одном случае ставить нечего, в
+    // другом дописать строку в уже стоящий. Совет разный, значит и строка разная. Ни то ни
+    // другое не отказ: AQK могут сознательно гонять в конвейере.
     {
       key: "preCommit",
-      ok: f.preCommit === null ? null : f.preCommit ? true : "no",
-      detail: f.preCommit === null ? t.unknownHook : f.preCommit ? t.preCommitOk : t.preCommitNo,
+      ok: f.preCommit === null ? null : f.preCommit === true ? true : "no",
+      detail: f.preCommit === null ? t.unknownHook
+        : f.preCommit === true ? t.preCommitOk
+        : f.preCommit === "other" ? t.preCommitOther
+        : t.preCommitNo,
     },
     {
       key: "sessionHook",
@@ -110,7 +116,7 @@ async function cmdVitals() {
   // Найдено 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);
+    const missing = await gateRequires(man, samplesDir, gate, whichSync);
     for (const prog of missing || []) {
       if (seen.has(prog)) continue;
       seen.set(prog, { gate, prog, found: false });

package/tool/i18n/en-docs.mjs

@@ -26,6 +26,9 @@ const enDocs = {
     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",
+    // A hook IS there, but not ours: nothing to install, something to add — a different
+    // remedy, hence a different line. Until 2026-09-16 this case printed as "wired".
+    preCommitOther: "a .git/hooks hook exists, but AQK is not called from it — check .pre-commit-config.yaml or the hook body",
     sessionOk: "the SessionStart hook hands the state to the agent",
     sessionNo: (cmd) => `the agent gets no state: ${cmd}`,
     versionOk: (v) => `${v}, current`,
@@ -83,7 +86,16 @@ const enDocs = {
     nextTitle: "Next, in order — computed from this repository, not generic advice:",
     nextStep: {
       init: () => "Set up the standard: `aqk init` — without .aqk.yml `aqk add` refuses.",
-      adopt: (s) => `Declare the checks this project already has: in .aqk.yml, under gates: ${s.gates.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Then \`aqk doctor --run\`.`,
+      // Слабые НЕ ПОПАДАЮТ в «впиши в манифест»: агент исполняет написанное, и объявленная
+      // проверка с `|| true` — это дыра, за которую с этого дня ручается машина.
+      adopt: (s) => {
+        const ok = s.gates.filter((g) => !g.weak);
+        const weak = s.gates.filter((g) => g.weak);
+        const out = [];
+        if (ok.length) out.push(`Declare the checks this project already has: in .aqk.yml, under gates: ${ok.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Then \`aqk doctor --run\`.`);
+        if (weak.length) out.push(`These cannot go red as written — ${weak.map((g) => `${g.cmd} (${g.weak.text})`).join(", ")} — so do not declare them yet: tell the owner and fix the command first.`);
+        return out.join(" ");
+      },
       blind: (s) => `The "${s.slug}" defect the probe planted in ${s.file} was NOT caught by your checks.` +
         (s.command ? ` Catch it now: \`${s.command}\`.` : "") + ` Keep it caught: \`aqk add ${s.slug}\`.`,
       start: (s) => `Install ${s.slug}: \`aqk add ${s.slug}\`` + (s.command ? ` (one line, no kit needed: \`${s.command}\`)` : "") +
@@ -93,7 +105,9 @@ const enDocs = {
     whenTitle: "When to do what:",
     whenCommit: (hook) => hook === true
       ? "Before a commit → the `.git/hooks/pre-commit` hook runs the checks itself; do not bypass it (`--no-verify`)."
-      : "Before a commit → `aqk doctor --run --since main`: there is no pre-commit hook, it will not happen by itself.",
+      : hook === "other"
+        ? "Before a commit → `aqk doctor --run --since main`: a hook is installed in `.git/hooks`, but AQK is not called from it — the run will not happen by itself."
+        : "Before a commit → `aqk doctor --run --since main`: there is no pre-commit hook, it will not happen by itself.",
     whenRules: [
       "Added or changed a check → `aqk prove`: the gate must go red on its own red sample, otherwise it checks nothing.",
       "Writing a rule into the rulebook → put the arbiter mark next to it, `<!-- aqk: gate-name -->`; no gate — `<!-- aqk: human -->`, which is an admission, not a check.",
@@ -155,6 +169,7 @@ const enDocs = {
     whyTitle: "Why this matters — briefly",
     whyNothing: "nothing to add: everything applicable is in place",
     saved: (path) => `Saved: ${path}`,
+    notSaved: (f, why) => `could not save to ${f} (${why}) — the report is above, there is no file on disk. The command only reports state, so a failed write does not fail it.`,
     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",
@@ -218,6 +233,7 @@ const enDocs = {
   ],
   report: {
     skippedBySelect: "not run (by --only/--skip), state unknown",
+    notWritten: (f, why) => `could not write the run report to ${f} (${why}) — the gates did run, but the next session and the hook will read this as "no run happened".`,
     title: "aqk doctor --run",
     version: "version",
     level: "level",

package/tool/i18n/en-gates.mjs

@@ -194,8 +194,16 @@ export const enGates = {
       red: (names, cmd) =>
         `The kit caught: ${names}. One line to the author — did it help: ${cmd}`,
       once: "Asked once per project; switch it off with AQK_FEEDBACK=0",
-      agent: "Say this to the human in one sentence, and do not insist if they do not answer.",
+      agent: "Say this to the human in one sentence, and do not insist if they do not answer. If they want to send it, add `--send`; never add the flag on your own.",
     },
+    sending: "sending on your behalf — with your own gh account…",
+    sent: (url) => `sent: ${url}\n  That is the whole price of this kit. Thank you.`,
+    sendFailed: {
+      "no-auth": "could not send: gh is missing or you are not logged in (`gh auth login`). The link below always works.",
+      "no-thread": "could not send: the discussion was not found. Use the link below.",
+      failed: "could not send. The link below always works.",
+    },
+    sendHow: (cmd) => `Send it in one command, with your own GitHub account: ${cmd}`,
     how: "Sending is one click (a prefilled issue opens; the text stays editable):",
     issueTitle: "Feedback on the kit",
     nothingSent: "Nothing was sent: the kit makes no outgoing requests other than the version check.",

package/tool/i18n/en.mjs

@@ -51,6 +51,7 @@ export const en = {
     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",
     feedback: "a report on how the kit worked plus a prefilled link — the only payment it asks",
+    feedbackSend: "send the feedback in one command — with your own gh account; without the flag nothing leaves",
     vitals: "is what the kit runs on wired up: gate tools, hooks, version freshness",
     prompt: "one task for the agent: what to fix, in order, and how to prove it is done",
     contextInstall: "the same in full — the map and the rulebook — installed as a hook",
@@ -153,7 +154,17 @@ export const en = {
     startHook: "Running these by hand is a one-off. To have them run before every push: pre-commit (repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit, hooks aqk / aqk-doctor), or a plain .git/hooks/pre-push.",
     haveAlready: (n) => `Checks you ALREADY have (${n}) — found in your own files, not invented:`,
     haveAlreadyHow: (line) => `declare them and a machine holds them, not your attention. In .aqk.yml, under gates:  ${line}`,
-    total: "Total:",
+    // Проверка, которая у проекта ЕСТЬ и провалиться НЕ МОЖЕТ. Самое ценное, что мы знаем о
+    // чужом репозитории в первые пять секунд, — и до 2026-09-14 мы об этом молчали.
+    weakOff: (text) => `cannot fail: the verdict is swallowed right in the script — «${text}»`,
+    weakZero: () => "cannot fail: --exit-zero tells the tool to exit 0 whatever it finds",
+    weakStub: (text) => `proves nothing: the whole script is a printout — «${text}»`,
+    weakHow: (n) => `${n} of them cannot go red. Declaring a check that cannot fail only makes the ` +
+      "silence machine-readable — fix the command first, then declare it.",
+    // Counted over the AQK CATALOGUE, and the line says so: a project gate named its own way
+    // closes none of our entries by name, and "held by a machine 0" read as a verdict on a
+    // repository with thirty checks of its own. Measured 2026-09-16 across twelve repositories.
+    total: "AQK catalogue totals:",
     totalHeld: (n) => `held by a machine ${n}`,
     totalTodo: (n) => `applicable but not installed ${n}`,
     totalSkip: (n) => `hidden ${n}`,
@@ -168,6 +179,7 @@ export const en = {
       `advisory and red: ${names.join(", ")}. These are switched-off checks: ` +
       `either fix them and drop them from advisory, or admit the rule does not exist.`,
     runHeading: "Running the declared gates",
+    timeoutBadEnv: (raw, secs) => `AQK_GATE_TIMEOUT="${raw}" is not a number of seconds above zero; waiting ${secs}s as before. Zero and garbage mean "wait forever" to spawnSync, and a hung gate looks exactly like a working one.`,
     timeout: "did not finish within 5 minutes",
     cannotCheck: (why) => `could not check: ${why}`,
     whySpawn: (code) => `failed to start${code ? ` (${code})` : ""}`,
@@ -294,7 +306,17 @@ export const en = {
       missed: ({ slug, file }, s) => `Gate \`${slug}\` is installed but missed the defect the probe planted into \`${file}\`. Find out why — a common cause is that the gate does not look at this file type or folder; \`${s} probe\` has the details. Done — \`${s} probe\` no longer names this class.`,
       red: (name, s) => `Gate \`${name}\` is red. Run \`${s} doctor --run --only ${name}\`, read the findings and fix the code. Done — that command passes.`,
       blind: ({ slug, file, command }, s) => `The probe planted a \`${slug}\` defect into \`${file}\` and the project's checks did not notice. Add a check: \`${s} add ${slug}\`${command ? ` (the same as one line, without the kit: \`${command}\`)` : ""}. Done — \`${s} doctor --run --only ${slug}\` passes and \`${s} probe\` no longer names this class.`,
-      adopt: (gates, s) => `The project already has its own checks: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Declare them under gates: in .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Done — \`${s} doctor --run\` runs them.`,
+      // СЛАБЫЕ ОТДЕЛЯЮТСЯ ОТ РАБОЧИХ, и это не украшение вывода. Агент исполняет написанное:
+      // велеть ему «впиши эти проверки в манифест», когда одна из них `… || true`, значит руками
+      // агента превратить дыру в зелёную галочку — и с этого дня её будет держать машина.
+      adopt: (gates, s) => {
+        const weak = gates.filter((g) => g.weak);
+        const ok = gates.filter((g) => !g.weak);
+        const out = [];
+        if (ok.length) out.push(`The project already has its own checks: ${ok.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Declare them under gates: in .aqk.yml — ${ok.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Done — \`${s} doctor --run\` runs them.`);
+        if (weak.length) out.push(`These CANNOT go red as written: ${weak.map((g) => `\`${g.cmd}\` — ${g.weak.text}`).join(", ")}. Fix the command before declaring it: a declared check that cannot fail turns a hole into a green tick, and from then on a machine vouches for it. This is the owner's call, not yours — say what you found.`);
+        return out.join(" ");
+      },
       shim: {
         missing: (s) => `Claude Code is set up here, but the rules live in AGENTS.md — it only reads CLAUDE.md. Create a CLAUDE.md with the single line \`@AGENTS.md\`. Done — \`${s} doctor\` no longer warns about it.`,
         noImport: (s) => `CLAUDE.md does not import AGENTS.md — Claude Code only sees CLAUDE.md. Add the line \`@AGENTS.md\` to CLAUDE.md (mentioning the file in prose does not load it). Done — \`${s} doctor\` no longer warns about it.`,

package/tool/i18n/ru-docs.mjs

@@ -26,6 +26,10 @@ const ruDocs = {
     unknownHook: "посмотреть не смогли — неизвестно, а не «нет»",
     preCommitOk: "прописан в .git/hooks",
     preCommitNo: "в .git/hooks его нет: запись в конфиге — намерение, а не защита",
+    // ХУК ЕСТЬ, НО НЕ НАШ. Ставить нечего — надо дописать: совет другой, значит и строка
+    // другая. До 2026-09-16 этот случай печатался как «прописан», и репозиторий, где AQK не
+    // вызывался ни разу, выглядел подключённым.
+    preCommitOther: "хук в .git/hooks есть, но AQK в нём не вызывается — проверьте .pre-commit-config.yaml либо само тело хука",
     sessionOk: "хук SessionStart отдаёт состояние агенту",
     sessionNo: (cmd) => `агент не получает состояние: ${cmd}`,
     versionOk: (v) => `${v}, свежая`,
@@ -87,7 +91,14 @@ const ruDocs = {
     // complexity-limit её поймал.
     nextStep: {
       init: () => "Заведи стандарт: `aqk init` — без .aqk.yml `aqk add` откажет.",
-      adopt: (s) => `Объяви проверки, которые у проекта уже есть: в .aqk.yml, в gates: ${s.gates.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Затем \`aqk doctor --run\`.`,
+      adopt: (s) => {
+        const ok = s.gates.filter((g) => !g.weak);
+        const weak = s.gates.filter((g) => g.weak);
+        const out = [];
+        if (ok.length) out.push(`Объяви проверки, которые у проекта уже есть: в .aqk.yml, в gates: ${ok.map((g) => `${g.name}: "${g.cmd}"`).join(", ")}. Затем \`aqk doctor --run\`.`);
+        if (weak.length) out.push(`А эти в нынешнем виде покраснеть не могут — ${weak.map((g) => `${g.cmd} (${g.weak.text})`).join(", ")} — и объявлять их пока нельзя: скажи владельцу и почини команду.`);
+        return out.join(" ");
+      },
       blind: (s) => `Брак «${s.slug}», подсаженный пробой в ${s.file}, ваши проверки НЕ поймали.` +
         (s.command ? ` Поймать сейчас: \`${s.command}\`.` : "") + ` Держать всегда: \`aqk add ${s.slug}\`.`,
       start: (s) => `Поставь ${s.slug}: \`aqk add ${s.slug}\`` + (s.command ? ` (одной строкой, без комплекта: \`${s.command}\`)` : "") +
@@ -97,7 +108,9 @@ const ruDocs = {
     whenTitle: "Когда что делать:",
     whenCommit: (hook) => hook === true
       ? "Перед коммитом → хук `.git/hooks/pre-commit` прогонит проверки сам; не обходи его (`--no-verify`)."
-      : "Перед коммитом → `aqk doctor --run --since main`: хука перед коммитом нет, само это не случится.",
+      : hook === "other"
+        ? "Перед коммитом → `aqk doctor --run --since main`: хук в `.git/hooks` стоит, но AQK из него не вызывается — сам собой прогон не случится."
+        : "Перед коммитом → `aqk doctor --run --since main`: хука перед коммитом нет, само это не случится.",
     whenRules: [
       "Добавил или поменял проверку → `aqk prove`: гейт обязан покраснеть на своём красном образце, иначе он не проверяет ничего.",
       "Пишешь правило в свод → рядом метка арбитра `<!-- aqk: имя-гейта -->`; гейта нет — `<!-- aqk: человек -->`, и это признание, а не проверка.",
@@ -159,6 +172,7 @@ const ruDocs = {
     whyTitle: "Зачем это нужно — коротко",
     whyNothing: "нечего добавлять: применимое уже стоит",
     saved: (path) => `Сохранено: ${path}`,
+    notSaved: (f, why) => `сохранить в ${f} не смогли (${why}) — отчёт выше, на диске его нет. Команда только рассказывает о состоянии, поэтому неудачная запись её не роняет.`,
     docs: {
       baseline: "обязательный минимум проекта, без привязки к языку",
       readyMade: "карта готовых правил: сперва ищи готовое, потом пиши своё",
@@ -222,6 +236,7 @@ const ruDocs = {
   ],
   report: {
     skippedBySelect: "не запускался (по --only/--skip), состояние неизвестно",
+    notWritten: (f, why) => `отчёт прогона в ${f} записать не смогли (${why}) — гейты отработали, но следующая сессия и хук прочтут это как «прогона не было».`,
     title: "aqk doctor --run",
     version: "версия",
     level: "уровень",

package/tool/i18n/ru-gates.mjs

@@ -197,8 +197,16 @@ export const ruGates = {
       red: (names, cmd) =>
         `Комплект поймал: ${names}. Одна строка автору — помогло или нет: ${cmd}`,
       once: "Спрашиваем один раз на проект; выключить: AQK_FEEDBACK=0",
-      agent: "Скажи это человеку одной фразой и не настаивай, если он не ответил.",
+      agent: "Скажи это человеку одной фразой и не настаивай, если он не ответил. Захочет отправить — добавь `--send`, сам флаг не добавляй.",
     },
+    sending: "отправляю от вашего имени — вашей же учётной записью gh…",
+    sent: (url) => `отправлено: ${url}\n  Это и есть вся плата за комплект. Спасибо.`,
+    sendFailed: {
+      "no-auth": "отправить не смогли: gh не установлен или вход не выполнен (`gh auth login`). Ниже — ссылка, она работает всегда.",
+      "no-thread": "отправить не смогли: обсуждение не найдено. Ниже — ссылка.",
+      failed: "отправить не смогли. Ниже — ссылка, она работает всегда.",
+    },
+    sendHow: (cmd) => `Отправить одной командой, своей учётной записью GitHub: ${cmd}`,
     how: "Отправить — одно нажатие (откроется готовая задача, текст можно править):",
     issueTitle: "Отзыв о работе комплекта",
     nothingSent: "Ничего не отправлено: комплект не делает исходящих запросов, кроме проверки версии.",

package/tool/i18n/ru.mjs

@@ -54,6 +54,7 @@ export const ru = {
     learn: "кандидаты в правила из локальной переписки: сказано вслух и не записано",
     context: "состояние проекта одним блоком — для контекста агента, а не для чтения",
     feedback: "отчёт о работе комплекта и готовая ссылка — единственная плата за него",
+    feedbackSend: "отправить отзыв одной командой — вашей учётной записью gh; без флага не уходит ничего",
     vitals: "подключено ли то, чем комплект работает: инструменты гейтов, хуки, свежесть версии",
     prompt: "одно задание для агента: что починить, по порядку, и чем доказать, что готово",
     contextInstall: "то же самое, но целиком — карта и свод правил — и хуком в контекст",
@@ -159,7 +160,16 @@ export const ru = {
     startHook: "Прогнать руками — разовый героизм. Чтобы это случалось перед каждым пушем: pre-commit (репозиторий https://github.com/arsen-ask-lx/Agent_Quality_Kit, хуки aqk / aqk-doctor) либо обычный .git/hooks/pre-push.",
     haveAlready: (n) => `Проверки, которые у вас УЖЕ ЕСТЬ (${n}) — прочитаны в ваших файлах, не выдуманы:`,
     haveAlreadyHow: (line) => `объявите их — и держать будет машина, а не ваше внимание. В .aqk.yml, в gates:  ${line}`,
-    total: "Итого:",
+    weakOff: (text) => `не может провалиться: исход погашен прямо в скрипте — «${text}»`,
+    weakZero: () => "не может провалиться: --exit-zero велит инструменту выйти нулём, что бы он ни нашёл",
+    weakStub: (text) => `ничего не доказывает: всё тело скрипта — печать — «${text}»`,
+    weakHow: (n) => `из них ${n} покраснеть не могут. Объявить проверку, которая не может ` +
+      "провалиться, — значит сделать молчание машинно-читаемым. Сначала почините команду.",
+    // «Итого» — ПО КАТАЛОГУ AQK, и это сказано словом. Считаются наши записи: гейт проекта,
+    // названный по-своему (`project-verify`), ни одну из них по имени не закрывает, и строка
+    // «держит машина 0» у проекта с тридцатью собственными проверками читалась как приговор
+    // ему, а не как счёт наших записей. Замер 2026-09-16 по двенадцати репозиториям.
+    total: "Итого по каталогу AQK:",
     totalHeld: (n) => `держит машина ${n}`,
     totalTodo: (n) => `применимо но не поставлено ${n}`,
     totalSkip: (n) => `скрыто ${n}`,
@@ -174,6 +184,7 @@ export const ru = {
       `совещательные и красные: ${names.join(", ")}. Это выключенные проверки: ` +
       `либо почини и убери из advisory, либо признай, что правила нет.`,
     runHeading: "Прогон объявленных гейтов",
+    timeoutBadEnv: (raw, secs) => `AQK_GATE_TIMEOUT=«${raw}» — это не число секунд больше нуля; жду как прежде, ${secs}с. Ноль и мусор у spawnSync означают «ждать вечно», а висящий гейт неотличим от работающего.`,
     timeout: "не уложился в 5 минут",
     // «Не смогли проверить» — третье состояние, и оно обязано звучать иначе, чем находка:
     // «код 2» человек читает как приговор коду, а это приговор запуску.
@@ -310,7 +321,14 @@ export const ru = {
       missed: ({ slug, file }, s) => `Гейт \`${slug}\` стоит, но пропустил брак, который проба подсадила в \`${file}\`. Разберись почему — частая причина: гейт не смотрит этот тип файлов или каталог; подробности даст \`${s} probe\`. Готово — \`${s} probe\` больше не называет этот класс.`,
       red: (name, s) => `Гейт \`${name}\` красный. Запусти \`${s} doctor --run --only ${name}\`, прочитай находки и почини код. Готово — эта команда зелёная.`,
       blind: ({ slug, file, command }, s) => `Проба подсадила брак класса \`${slug}\` в \`${file}\`, и проверки проекта его не заметили. Поставь проверку: \`${s} add ${slug}\`${command ? ` (то же одной строкой, без комплекта: \`${command}\`)` : ""}. Готово — \`${s} doctor --run --only ${slug}\` проходит, а \`${s} probe\` больше не называет этот класс.`,
-      adopt: (gates, s) => `У проекта уже есть свои проверки: ${gates.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Впиши их в gates: манифеста .aqk.yml — ${gates.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Готово — \`${s} doctor --run\` их запускает.`,
+      adopt: (gates, s) => {
+        const weak = gates.filter((g) => g.weak);
+        const ok = gates.filter((g) => !g.weak);
+        const out = [];
+        if (ok.length) out.push(`У проекта уже есть свои проверки: ${ok.map((g) => `\`${g.cmd}\` (${g.source})`).join(", ")}. Впиши их в gates: манифеста .aqk.yml — ${ok.map((g) => `\`${g.name}: "${g.cmd}"\``).join(", ")}. Готово — \`${s} doctor --run\` их запускает.`);
+        if (weak.length) out.push(`А эти в нынешнем виде покраснеть НЕ МОГУТ: ${weak.map((g) => `\`${g.cmd}\` — ${g.weak.text}`).join(", ")}. Не вписывай их, пока не починена команда: объявленная проверка, которая не может провалиться, превращает дыру в зелёную галочку, и с этого дня за неё ручается машина. Это решение владельца, а не твоё, — скажи ему, что нашёл.`);
+        return out.join(" ");
+      },
       shim: {
         missing: (s) => `Claude Code здесь настроен, а правила лежат в AGENTS.md — он читает только CLAUDE.md. Создай CLAUDE.md с одной строкой \`@AGENTS.md\`. Готово — \`${s} doctor\` об этом больше не предупреждает.`,
         noImport: (s) => `CLAUDE.md не подключает AGENTS.md — Claude Code видит только CLAUDE.md. Добавь в CLAUDE.md строку \`@AGENTS.md\` (упоминание словами файл не загружает). Готово — \`${s} doctor\` об этом больше не предупреждает.`,

package/tool/lib/adopt.mjs

@@ -20,24 +20,77 @@
 // ни другой. Берём только то, что отвечает «прошло или нет».
 const CHECK_NAMES = new Set(["test", "tests", "lint", "typecheck", "type-check", "types", "check"]);
 
+// ПРОВЕРКА, КОТОРАЯ ЕСТЬ И НЕ МОЖЕТ ПРОВАЛИТЬСЯ. До 2026-09-14 мы читали ИМЯ скрипта и печатали
+// каноничную команду `npm test` с зелёной галочкой, ни разу не заглянув в его ТЕЛО. А выключатель
+// стоит именно там: `node --test || true`. На репозитории, где выключено всё, первый экран
+// говорил «у вас уже есть 2 проверки» — ровно та ошибка, ради которой написан весь комплект.
+//
+// ГРАНИЦА ВЗЯТА У ГЕЙТА `ci-actually-fails`, дословно его довод: `|| true` в СЕРЕДИНЕ команды —
+// это идемпотентность вспомогательного шага (`mkdir -p … || true`), а не выключенная проверка.
+// Поэтому красным делается только то, под что попадает ВЕСЬ исход: гашение в конце тела либо
+// флаг, у которого другого назначения нет.
+const OFF_TAIL = /(\|\|\s*(?:true|:|exit\s+0)|;\s*(?:true|exit\s+0))\s*$/;
+const ZERO_FLAG = /(?:^|\s)--exit-zero(?:\s|$)/;
+
+function cannotFail(body) {
+  if (typeof body !== "string") return undefined;
+  // Комментарий — не команда. `\s#` (а не просто `#`): в `echo "#1"` решётка стоит внутри строки.
+  const code = body.replace(/\s#[^"']*$/, "").trim();
+  if (!code) return undefined;
+  const off = OFF_TAIL.exec(code);
+  if (off) return { kind: "off", text: off[1].trim() };
+  if (ZERO_FLAG.test(code)) return { kind: "zero", text: "--exit-zero" };
+  // Заглушка: всё тело — печать и ничего больше. Заготовка npm
+  // (`echo "Error: no test specified" && exit 1`) провалиться МОЖЕТ — её обвинять нельзя,
+  // и её отсекает связка `&&`.
+  if (/^echo\b/.test(code) && !/[&|;]/.test(code)) return { kind: "stub", text: code.slice(0, 60) };
+  return undefined;
+}
+
 // Окружения tox, которые судят, а не гоняют тесты под матрицей версий. Голый `tox` не
 // предлагаем: он проходит все интерпретаторы из envlist, и у человека без пяти питонов это
 // красный прогон на пустом месте. Имена сняты с живых tox-файлов (rich, click, flask).
 const TOX_CHECKS = new Set(["lint", "style", "typing", "types", "type", "mypy", "check", "typecheck"]);
 
+// ОДНА И ТА ЖЕ КОМАНДА, ЗАПИСАННАЯ ПО-РАЗНОМУ. Сравнивать надо КОМАНДЫ, а не имена: гейт в
+// чужом манифесте зовётся как хочет его владелец (`project-verify`), и по именам совпадения не
+// будет никогда. Обёртка снимается: `bash scripts/check` и `scripts/check` — это одно, и
+// советовать второе тому, у кого объявлено первое, значит советовать уже сделанное.
+//
+// Вхождение подстрокой здесь НЕ годится, хотя и соблазняет: `true` содержится в половине
+// команд, и любой гейт-заглушка съел бы весь список. Равенство после нормализации ошибается
+// в одну сторону — покажет лишнее, — и это дешевле молчания.
+const WRAPPER = /^(?:bash|sh)\s+/;
+
+function sameCommand(a, b) {
+  const norm = (s) => String(s || "").trim().replace(/\s+/g, " ");
+  const bare = (s) => norm(s).replace(WRAPPER, "");
+  return (norm(a) && norm(a) === norm(b)) || (bare(a) && bare(a) === bare(b));
+}
+
 // Источники в порядке доверия: при совпадении имени берётся первый. Замер 2026-09-11 на
 // восьми python-проектах: package.json нет ни у кого, Makefile у трёх, `.pre-commit-config.yaml`
 // у семи, tox у пяти, scripts/ у httpx. Шаги конвейера НЕ читаются: там `${{ matrix.x }}`,
 // `PYTHONPATH=…` и обёртки `uv run --locked --group …` — строка, которая работает только в
 // том конвейере, предложенная как локальный гейт, покраснела бы у человека в первую же минуту.
-function proposeGates(files = {}) {
+//
+// `declared` — команды, УЖЕ объявленные в манифесте. Приходят списком строк, а не манифестом:
+// иначе чтение чужих конфигов начало бы зависеть от нашего формата, и файл, заведённый ради
+// разбора ЧУЖИХ источников, получил бы вторую причину меняться.
+function proposeGates(files = {}, declared = []) {
   const out = [];
   const seen = new Set();
-  const push = (name, cmd, source) => {
+  const already = (cmd) => (declared || []).some((d) => sameCommand(d, cmd));
+  // ТЕЛО передаётся отдельно от команды: человеку показывается каноничная `npm test`, а судим
+  // мы по тому, что за ней стоит. Где тела у нас нет (Makefile, tox, scripts/) — там и суждения
+  // нет: молчание тут честнее догадки.
+  const push = (name, cmd, source, body) => {
     const key = name === "tests" ? "test" : name.replace(/^type-?check$|^types$/, "typecheck");
     if (seen.has(key)) return;
     seen.add(key);
-    out.push({ name: key, cmd, source });
+    if (already(cmd)) return;
+    const weak = cannotFail(body);
+    out.push(weak ? { name: key, cmd, source, weak } : { name: key, cmd, source });
   };
 
   const pkg = files["package.json"];
@@ -48,7 +101,8 @@ function proposeGates(files = {}) {
       for (const name of Object.keys(scripts)) {
         if (!CHECK_NAMES.has(name)) continue;
         // `npm test` — каноничное написание для теста, остальное через `run`.
-        push(name, name === "test" || name === "tests" ? "npm test" : `npm run ${name}`, "package.json");
+        push(name, name === "test" || name === "tests" ? "npm test" : `npm run ${name}`,
+          "package.json", scripts[name]);
       }
     }
   }