agent-quality-kit 0.8.0 → 0.9.0

package/kit/gates/mcp-server-resolves/README.md

@@ -0,0 +1,62 @@
+# mcp-server-resolves
+
+**Что ловит.** Объявленный MCP-сервер, которого на деле нет: команда указывает на несуществующий
+файл, либо версия не закреплена и завтра приедет другая.
+
+**Почему это отдельная запись.** Сервер, который не поднялся, агенту **никак не виден**: у него
+просто нет этих инструментов, и он молча работает без них. Ни ошибки, ни строки в журнале.
+Это тот же класс, что хук с опечаткой в имени события: настройка выглядит как возможность и
+возможностью не является.
+
+## Шишка, из которой она выросла
+
+2026-09-08. В проект записали настройку `chrome-devtools-mcp` — выглядела безупречно:
+
+```json
+"chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@1.9.0"] }
+```
+
+Сервер был мёртв. Puppeteer подхватывал Windows-овый Chrome из `/mnt/c/` и падал с
+`Target closed`. Узнали только потому, что запустили руками и прочитали журнал — обычно так не
+делают: записали конфиг, увидели «сохранено», пошли дальше.
+
+## Замер
+
+Двадцать настоящих настроек `.mcp.json`, взятых поиском по GitHub 2026-09-08.
+
+| | |
+|---|---|
+| конфигов проверено | 20 |
+| покраснело | 9 |
+| находок | 14 |
+| ложных срабатываний | **0** |
+
+Все находки — чужие серверы, которые тянутся незакреплёнными при каждом запуске:
+`@modelcontextprotocol/server-github`, `firecrawl-mcp`, `mcp-server-postgres`, `@upstash/context7-mcp`.
+Серверу с таким доступом «сегодня одна версия, завтра другая» — открытая дверь в цепочке поставок.
+
+Замер тут же нашёл и два ложных срабатывания, оба починены до объявления записи рабочей:
+
+1. `npx tsx rag/src/index.ts` — сервер **свой**, лежит в репозитории и уже под версией. Требовать
+   закрепить `tsx` значит краснеть на нормальном укладе, а такой гейт выключают в первый день.
+2. Починка первого съела настоящую находку: `@meridian/docs-mcp` — имя пакета со слэшем, а слэш
+   считался признаком локального файла. Видно было только построчным сравнением до и после.
+
+## Готовый аналог
+
+Готового аналога нет. Проверено 2026-09-08 поиском: линтеры настроек агента существуют
+(`claudelint`, `agent-lint`), но смотрят на права и хуки, а не на MCP. Ближайшее по смыслу —
+наш собственный `deps-are-pinned`: там то же правило про версии, но для зависимостей сборки,
+и файла `.mcp.json` он не видит.
+
+## Чего НЕ ловит
+
+- **Не запускает серверы.** Мёртвый по любой другой причине сервер — как в шишке выше, где путь
+  и версия были верны, а падал сам браузер, — эта проверка не увидит. Запуск чужих команд на
+  каждый коммит означает скачивание пакетов и минуты ожидания; такую проверку выключают сразу.
+  Живое рукопожатие — то, что делают руками при подключении сервера, и это записано в методичке,
+  а не в гейте.
+- **Не судит об относительных путях.** `"command": "./bin/server"` не проверяется: рабочий
+  каталог сервера задаётся полем `cwd`, и проверить существование без запуска нельзя.
+- **Не знает, что пакет существует в реестре.** Это делает `no-phantom-package`, но только для
+  того, что упомянуто в документации.

package/kit/gates/mcp-server-resolves/check.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env sh
+# Объявленный MCP-сервер, которого на деле нет: команда указывает на файл, которого не
+# существует, либо версия не закреплена и завтра приедет другая.
+#
+# ЗАЧЕМ. Сервер, который не поднялся, агенту НИКАК не виден: у него просто нет этих
+# инструментов, и он молча работает без них. Ни ошибки, ни строки в журнале — та же тишина,
+# что у хука с опечаткой в имени события. Настройка выглядит как возможность и возможностью
+# не является.
+#
+# ПРОВЕРЕНО НА СЕБЕ 2026-09-08. Записали в проект настройку chrome-devtools-mcp, выглядела
+# безупречно. Сервер был мёртв: puppeteer подхватывал Windows-овый Chrome из /mnt/c/ и падал
+# с «Target closed». Узнали только потому, что запустили руками и прочитали журнал; обычно
+# так не делают — записали конфиг, увидели «сохранено», пошли дальше.
+#
+# ЧТО ЭТА ПРОВЕРКА НЕ ДЕЛАЕТ. Она НЕ запускает серверы. Запуск — это исполнение чужих команд
+# на каждый коммит, скачивание пакетов и минуты ожидания; такую проверку выключают в первый
+# день. Здесь ловится только то, что видно без запуска, и этого достаточно для двух самых
+# частых смертей: файла нет и версия плавает.
+DIR="${1:-.}"
+SKIP_LIB="$(dirname "$0")/../_skip.sh"
+if [ ! -f "$SKIP_LIB" ]; then
+  echo "рядом с проверкой нет _skip.sh — обход не собран, проверка не состоялась"
+  echo "  почини: скопируй гейт вместе с файлом kit/gates/_skip.sh, он общий на весь каталог"
+  exit 2
+fi
+. "$SKIP_LIB"
+
+OUT=""
+for F in "$DIR/.mcp.json" "$DIR/.cursor/mcp.json" "$DIR/.vscode/mcp.json" "$DIR/.claude/mcp.json"; do
+  [ -f "$F" ] || continue
+  RES=$(awk -v file="$F" -v dir="$DIR" '
+    # Номера строк с командой копятся отдельно от текста: разбор идёт в END по всему файлу
+    # одной строкой (иначе минифицированный JSON не разобрать), а находку надо привязать к
+    # строке — без неё `--since` не сверит путь с дифом и гейт зазеленеет на чужом дифе.
+    /"command"[ \t]*:/ { cline[++ci] = NR }
+    { buf = buf $0 " " }
+    END {
+      n = split(buf, part, /"command"[ \t]*:/)
+      for (i = 2; i <= n; i++) {
+        chunk = part[i]
+        if (!match(chunk, /"[^"]*"/)) continue
+        cmd = substr(chunk, RSTART + 1, RLENGTH - 2)
+        line = cline[i - 1] ? cline[i - 1] : 1
+
+        # 1. Абсолютный путь, которого нет. Самая частая смерть у пакетов, чья версия вшита
+        # в имя файла: обновились — старый файл удалён, сервер умер, никто не заметил.
+        if (substr(cmd, 1, 1) == "/") {
+          if (system("test -e \"" cmd "\"") != 0)
+            print file ":" line ": команда сервера не существует: " cmd
+          continue
+        }
+
+        # 2. Скачивающий запуск без точной версии. `@latest` и голое имя означают «сегодня
+        # одно, завтра другое», а для сервера, которому доверен браузер и файлы, это дверь
+        # в цепочке поставок. Правило то же, что у нас для зависимостей.
+        if (cmd == "npx" || cmd == "uvx" || cmd == "pipx" || cmd == "bunx" || cmd == "pnpm") {
+          args = ""
+          if (match(chunk, /"args"[ \t]*:[ \t]*\[[^]]*\]/)) args = substr(chunk, RSTART, RLENGTH)
+          if (args == "") continue
+          if (args ~ /@latest/) {
+            print file ":" line ": версия сервера не закреплена (@latest): " cmd
+            continue
+          }
+          # Имя пакета — первый довод, не начинающийся с дефиса. Точная версия пишется как
+          # name@1.2.3 (npm) или name==1.2.3 (python); без неё запуск невоспроизводим.
+          m = args
+          gsub(/"args"[ \t]*:[ \t]*\[/, "", m); gsub(/\]/, "", m)
+          k = split(m, tok, ",")
+
+          # СЕРВЕР ИЗ СВОЕГО РЕПОЗИТОРИЯ — не находка. `npx tsx rag/src/index.ts` запускает
+          # СВОЙ файл, а npx здесь только запускалка: код сервера лежит в репозитории и уже
+          # под версией — той же, что и весь проект. Требовать закрепить `tsx` значит краснеть
+          # на нормальном укладе, а такой гейт выключают в первый день. Найдено замером по
+          # двадцати чужим настройкам с GitHub 2026-09-08: две из десяти находок были ровно
+          # этим. Тот же класс, что четыре ложных срабатывания на чужом коде до этого.
+          local_entry = 0
+          for (j = 1; j <= k; j++) {
+            t = tok[j]; gsub(/^[ \t"]+|[ \t"]+$/, "", t)
+            # Признак локального входа — расширение файла или явно относительный путь.
+            # Просто «есть слэш» не годится: `@scope/name` — это имя пакета в npm, и первая
+            # версия этой проверки съела настоящую находку `npx @meridian/docs-mcp`. Поймано
+            # тем же замером по двадцати чужим настройкам: находок стало восемь вместо девяти,
+            # и пропажу было видно только построчным сравнением до и после.
+            if (t ~ /\.(ts|js|mjs|cjs|py|rb|sh)$/ || t ~ /^\//  || t ~ /^\.\// || t ~ /^\.\.\//) { local_entry = 1; break }
+          }
+          if (local_entry) continue
+
+          for (j = 1; j <= k; j++) {
+            t = tok[j]; gsub(/^[ \t"]+|[ \t"]+$/, "", t)
+            if (t == "" || substr(t, 1, 1) == "-") continue
+            if (t ~ /@[0-9]/ || t ~ /==[0-9]/) break
+            print file ":" line ": версия сервера не закреплена: " cmd " " t
+            break
+          }
+        }
+      }
+    }
+  ' "$F")
+  [ -n "$RES" ] && OUT="${OUT}${RES}
+"
+done
+
+OUT=$(printf '%s' "$OUT" | own_samples_filter "$DIR" | sed '/^$/d')
+if [ -n "$OUT" ]; then
+  printf '%s\n' "$OUT"
+  echo "  почини: закрепи точную версию (пакет@1.2.3) и убедись, что файл команды существует."
+  echo "  мёртвый сервер агенту не виден: он просто работает без этих инструментов и молчит."
+  exit 1
+fi
+exit 0

package/kit/gates/mcp-server-resolves/gate.yml

@@ -0,0 +1,18 @@
+intent: объявленный MCP-сервер существует и закреплён по версии — иначе агент молча работает без него
+intent_en: a declared MCP server exists and is version-pinned — otherwise the agent silently works without it
+
+# Только там, где агенту подключали внешние инструменты. В проекте без `.mcp.json` проверять
+# нечего, а запись, показанная не тому, стоит доверия всему каталогу.
+trigger:
+  has_mcp: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+samples_for: any
+
+proof: incidents/README.md, 2026-09-08 «конфиг был написан верно, а сервер мёртв» — в проект
+  записали настройку `chrome-devtools-mcp`, выглядела безупречно; сервер падал с «Target closed»,
+  потому что puppeteer подхватывал Windows-овый Chrome из `/mnt/c/`. Узнали только запуском
+  руками и чтением журнала: агенту мёртвый сервер не виден вовсе — у него просто нет этих
+  инструментов, и он молча работает без них

package/kit/gates/mcp-server-resolves/green/.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "browser": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@1.9.0"]
+    },
+    "search": {
+      "command": "uvx",
+      "args": ["some-search-mcp==0.4.1"]
+    },
+    "local": {
+      "command": "node",
+      "args": ["scripts/mcp-server.mjs"]
+    },
+    "own-code": {
+      "command": "npx",
+      "args": ["tsx", "rag/src/index.ts"]
+    }
+  }
+}

package/kit/gates/mcp-server-resolves/red/.mcp.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "browser": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    },
+    "memory": {
+      "command": "/opt/tools/memory-mcp-v0.10.8/bin/memory",
+      "args": []
+    },
+    "search": {
+      "command": "npx",
+      "args": ["-y", "some-search-mcp"]
+    }
+  }
+}

package/llms.txt

@@ -25,8 +25,9 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
 - Show only what a diff introduced, so a legacy repo is usable from day one: `doctor --run --since main`
 - Prove the gates actually catch defects: `npx agent-quality-kit prove` — every *provable* gate is
   run against its own red and green sample and must go red on the first and stay quiet on the
-  second. A gate with no samples, with samples written for another recipe, or whose command takes
-  no directory is reported as unprovable and named; the verdict is "nothing proven is broken, and
+  second. A gate with no samples, with samples written for another recipe, whose command takes
+  no directory, or whose `requires:` program is not installed is reported as unprovable and
+  named — never as broken; the verdict is "nothing proven is broken, and
   at least one gate is proven". Level AQK-2 and the badge depend on this, not on the presence of
   files
 - See what proves a diff, file by file: `npx agent-quality-kit report --since main` — each changed
@@ -41,6 +42,11 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
   adds the command map and the rulebook verbatim (~7000 tokens): a deliberate trade, chosen by
   the owner after the objection about long inputs, on the grounds that an agent reads files
   poorly and the tokens are the price of it not guessing
+- Check that the kit's own wiring is actually connected: `npx agent-quality-kit vitals` — are the
+  tools the declared gates need installed, is the hook present in `.git/hooks` (a line in the
+  config is an intention, not a guard), does the agent receive the state, is the version current.
+  Four states, not two: connected · BROKEN · not connected and that is a choice · could not look.
+  Only BROKEN affects the exit code
 - See what you told the agent and never wrote down: `npx agent-quality-kit learn` — reads Claude Code
   transcripts for this project on this machine and prints rule candidates missing from the entry
   point. Current project only, terminal only, writes nothing, always exits 0
@@ -48,7 +54,15 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
 - 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.8.0` with `min: 1`
+- Without Node at all (a Python, Go or Rust project where nobody installed it):
+  `docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/arsen-ask-lx/aqk doctor`.
+  Published from v0.9.0 onward, by the same run that publishes the package; before that tag,
+  build it from the repository: `docker build -t aqk . && docker run --rm -u "$(id -u):$(id -g)"
+  -v "$PWD:/work" aqk doctor`. Keep the `--user` flag: without it the container runs as root and
+  the files `init` writes are owned by root, so you cannot edit your own manifest. Debian-based
+  on purpose: the gates are `sh`, `grep`, `awk`, `find` — under alpine's busybox they behave
+  differently, and an image where the gates behave differently is worse than no image
+- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.9.0` with `min: 1`
   (https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ## What makes it different
@@ -64,7 +78,8 @@ Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.
 ## 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
+- `.aqk.yml` — the manifest: entry, rules, docs, lang, gates as commands, covers (what a
+  declared gate already holds, so it is not reported as debt), samples, ratchets, lessons
 - `.aqkignore` — paths the scanning checks must not read (brought-in code, vendored, generated)
 
 ## Documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.8.0",
+  "version": "0.9.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": {
@@ -43,11 +43,7 @@
   ],
   "knip": {
     "entry": [
-      "tool/selfcheck/units.mjs",
-      "tool/selfcheck/units-level.mjs",
-      "tool/selfcheck/units-evidence.mjs",
-      "tool/selfcheck/units-learn.mjs",
-      "tool/selfcheck/units-context.mjs",
+      "tool/selfcheck/units*.mjs",
       "tool/selfcheck/lifecycle.mjs"
     ],
     "project": [

package/tool/commands/context.mjs

@@ -130,11 +130,15 @@ function runIsStale(when) {
 // `SessionStart` — принадлежность одного Claude Code, и класть его всем подряд значило бы
 // объявить нейтральность и нарушить её в первой же команде.
 //
-// БЕЗ MATCHER НАМЕРЕННО. Справочник на сайте перечисляет у SessionStart значения matcher
-// (startup, resume, clear, compact), а таблица событий, ВШИТАЯ в установленную версию 2.1.263,
-// показывает в колонке matcher прочерк. Одно из двух неверно, и выяснить это гаданием нельзя.
-// Хук без matcher верен при любом из двух чтений: где matcher поддержан — сработает на всех
-// источниках, где не поддержан — на всех тоже. Проверено чтением бинаря, не памятью.
+// БЕЗ MATCHER НАМЕРЕННО, и теперь по установленной причине, а не из осторожности.
+// 2026-09-08 расхождение разрешено: в бинаре установленной версии 2.1.263 лежит буквальное
+// перечисление источников — "startup","resume","clear","compact","fork" — и вызов
+// {kind:"session-start", source:"startup"}. То есть у SessionStart источники ЕСТЬ, и `compact`
+// среди них: хук срабатывает и после сжатия контекста. Это важнее, чем кажется: сжатие —
+// ровно тот момент, когда состояние вылетает из окна, и без повторного срабатывания вся
+// затея работала бы до первого /compact.
+// Matcher не ставим потому, что нужны ВСЕ источники: и старт, и продолжение, и очистка, и
+// сжатие. Отсутствие matcher означает «на любой источник» — это и требуется.
 const HOOK_FILE = [".claude", "settings.json"];
 
 // Команда, которая пойдёт В ОБЩИЙ файл настроек, а значит и в чужие руки через git. `SELF`

package/tool/commands/doctor.mjs

@@ -4,12 +4,13 @@ import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { scopeOutput, splitAdvice, 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, advisorySet, layoutChecks } from "../lib/manifest.mjs";
+import { CWD, PKG_ROOT, TARGET_DIR, MANIFEST, SELF, c, exists, die } from "../lib/core.mjs";
+import { readManifest, assessLevel, unknownKeys, KNOWN_KEYS, advisorySet, layoutChecks, coversOf, coversUnproven, unparsedLines } from "../lib/manifest.mjs";
 import { proveGates } from "../lib/prove.mjs";
-import { detectFacts, readCatalog, triggerVerdict, recipeFor } from "../lib/repo.mjs";
+import { detectFacts, readCatalog, triggerVerdict, browserServerAdvice } from "../lib/repo.mjs";
 import { assessBaseline, DEP_FILES, BASELINE_TOTAL } from "../lib/baseline.mjs";
 import { L } from "../i18n/index.mjs";
+import { beginBrief, finishBrief } from "../lib/brief.mjs";
 
 // Обязательный минимум проекта — прогоном, а не по памяти. До сих пор это было единственное
 // место, где комплект просил верить на слово, что человек прочитал методичку и сверился.
@@ -50,11 +51,16 @@ async function reportCatalog(man, facts) {
   const catalog = await readCatalog();
   if (!catalog.length) return;
 
-  const held = [], todo = [], skip = [];
+  // Четвёртая корзина, а не третья: «закрыто другим арбитром» — это НЕ «не поставлено».
+  // Пока их считали вместе, вывод каждый прогон называл долгом то, что уже держит biome или
+  // ruff. Просьба первого чужого пользователя; она же — наша собственная норма про вывод.
+  const { covered, unknownGates } = coversOf(man);
+  const held = [], todo = [], skip = [], byOther = [];
   for (const rec of catalog) {
     const v = triggerVerdict(rec, facts);
     if (!v.applies) skip.push([rec, v.why]);
     else if (facts.gateKeys.includes(rec.slug)) held.push(rec);
+    else if (covered.has(rec.slug)) byOther.push([rec, covered.get(rec.slug)]);
     else todo.push(rec);
   }
 
@@ -72,14 +78,50 @@ async function reportCatalog(man, facts) {
     console.log(`  ${c.yellow("✘")}  ${rec.slug.padEnd(22)} ${rec.intent || ""}`);
     console.log(c.dim(`      ${L.doctor.install(`${SELF} add ${rec.slug}`)}`));
   }
+  if (byOther.length) {
+    console.log(c.dim(`\n  ${L.doctor.coveredBy(byOther.length)}`));
+    for (const [rec, gate] of byOther) console.log(c.dim(`  ~  ${rec.slug.padEnd(22)} ${L.doctor.coveredByGate(gate)}`));
+  }
+  // Гейт, которого нет в gates:, не закрывает ничего — и молчать об этом нельзя: человек
+  // считает запись закрытой, а её не держит никто. Называется поимённо, жёлтым.
+  if (unknownGates.length) {
+    console.log(c.yellow(`\n  ${L.doctor.coversUnknown(unknownGates.join(", "))}`));
+  }
+  // Заявка «эту запись держит наш линтер» сверяется с кодами правил из рецепта записи.
+  // Замерено на живом ruff.toml: девятнадцать групп правил, а print() не ловится — и заявка
+  // сняла бы запись с долга, не закрыв её ничем.
+  let linterCfg = "";
+  for (const f of ["ruff.toml", ".ruff.toml", "pyproject.toml", ".eslintrc.json", "eslint.config.js", "eslint.config.mjs", "biome.json"]) {
+    try { linterCfg += await readFile(join(CWD, f), "utf8"); } catch { /* нет файла — нечего читать */ }
+  }
+  const unproven = coversUnproven(man, catalog, linterCfg);
+  for (const u of unproven) {
+    console.log(c.yellow(`\n  ${L.doctor.coversUnproven(u.entry, u.gate, u.codes.join(", "))}`));
+    console.log(c.dim(`  ${L.doctor.coversUnprovenHow(`${SELF} add ${u.entry}`)}`));
+  }
+  // Не вердикт, а совет: отсутствие браузерного сервера — незанятая возможность, а не дефект.
+  // Поэтому строка тусклая и без значка, и её нет у проекта без интерфейса.
+  let mcpText = "";
+  for (const f of [".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json", ".claude/mcp.json"]) {
+    try { mcpText += await readFile(join(CWD, f), "utf8"); } catch { /* нет файла — нечего читать */ }
+  }
+  const browser = browserServerAdvice(facts, mcpText);
+  if (browser) {
+    console.log(c.dim(`\n  ${L.doctor.noBrowserServer}`));
+    console.log(c.dim(`  ${L.doctor.noBrowserServerHow(browser.servers.join("  ·  "))}`));
+  }
   if (skip.length) {
     console.log(c.dim(`\n  ${L.doctor.notApplicable(skip.length)}`));
     for (const [rec, why] of skip) console.log(c.dim(`  ·  ${rec.slug.padEnd(22)} ${why}`));
   }
   console.log(
     `\n  ${c.bold(L.doctor.total)} ${L.doctor.totalHeld(held.length)}, ${L.doctor.totalTodo(c.yellow(todo.length))}, ` +
+      (byOther.length ? `${L.doctor.totalCovered(byOther.length)}, ` : "") +
       c.dim(L.doctor.totalSkip(skip.length)) + "\n"
   );
+  // Числа отдаются наружу, а не пересчитываются второй раз: два счёта одного и того же
+  // расходятся ровно так же, как два списка команд.
+  return { held: held.length, todo: todo.length, todoRecs: todo };
 }
 
 // «Гейт объявлен» и «гейт работает» — разные утверждения. Первое читается из манифеста,
@@ -139,14 +181,20 @@ function runGates(man, opts = {}) {
     }
     const code = r.status;
     if (code === 0) {
-      console.log(`  ${c.green("✔")}  ${name.padEnd(14)} ${c.dim(`${secs}s · ${cmd}`)}`);
+      // Совещательный называется и когда он зелёный. Иначе гейт, который уронить прогон НЕ
+      // МОЖЕТ, по выводу неотличим от того, который может, — и список `advisory:` в манифесте
+      // виден только в тот день, когда он покраснел. Измерено 2026-09-09: зелёный
+      // совещательный печатался обычной галочкой, а README обещал, что список назван каждый
+      // прогон. Тот же класс, что молчащий гейт, только про сам прибор.
+      const quiet = advisory.has(name) ? ` ${c.yellow(L.doctor.advisoryQuiet)}` : "";
+      console.log(`  ${c.green("✔")}  ${name.padEnd(14)}${quiet} ${c.dim(`${secs}s · ${cmd}`)}`);
       // Зелёный гейт иногда всё-таки говорит человеку что-то важное: храповик, дошедший до цели,
       // просит убрать обёртку. Вывод успешного гейта не показывался вовсе, и это сообщение
       // уходило в никуда — тот же класс, что обрезанный совет у красного, только тише.
       // Показываем ровно строки с меткой совета: остальной вывод успешной проверки — шум.
       const okAdvice = splitAdvice(`${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean)).advice;
       for (const line of okAdvice.slice(0, 6)) console.log(c.yellow(`        ${line.trim().slice(0, 110)}`));
-      results.push({ name, cmd, ok: true, secs, out: outAll });
+      results.push({ name, cmd, ok: true, secs, advisory: advisory.has(name), out: outAll });
     } else {
       const raw = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
       // Совет отделяется ДО сужения. Иначе он сам попадает под фильтр по путям: сообщение
@@ -165,16 +213,23 @@ function runGates(man, opts = {}) {
         if (!s.scopable || out.length === 0) {
           // Гейт печатает вердикт без путей — сузить нечем. Признать его успешным значило бы
           // выдать провал за тишину; остаётся красным, и причина названа.
-          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, out: outAll });
+          // Совещательный не роняет прогон НИКОГДА — в том числе здесь. Раньше failed++ стоял
+          // безусловно, и гейт, объявленный совещательным, валил сборку с `--since` только
+          // потому, что в его выводе нет путей. Измерено 2026-09-09.
+          const nsAdv = advisory.has(name);
+          const nsMark = nsAdv ? c.yellow("!") : c.red("✘");
+          const nsVerdict = nsAdv ? c.yellow(L.doctor.advisoryMark) : c.red(L.doctor.exitCode(code));
+          console.log(`  ${nsMark}  ${name.padEnd(14)} ${nsVerdict} ${c.dim(`· ${L.doctor.notScopable}`)}`);
+          if (!nsAdv) failed++;
+          results.push({ name, cmd, ok: false, secs, code, advisory: nsAdv, note: L.doctor.notScopable, out: outAll });
           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, out: outAll });
+          const sQuiet = advisory.has(name) ? ` ${c.yellow(L.doctor.advisoryQuiet)}` : "";
+          console.log(`  ${c.green("✔")}  ${name.padEnd(14)}${sQuiet} ${c.dim(`${secs}s · ${L.doctor.outsideDiff(out.length)}`)}`);
+          results.push({ name, cmd, ok: true, secs, advisory: advisory.has(name), scopedAway: out.length, out: outAll });
           continue;
         }
         out = s.kept;
@@ -200,7 +255,7 @@ function runGates(man, opts = {}) {
   }
   // Совещательные, которые покраснели, называются вслух ВСЕГДА. Молчание о них — ровно та
   // тишина, против которой построен стандарт: проверка выключена, а выглядит как её отсутствие.
-  const advisoryFailed = results.filter((x) => x.advisory).map((x) => x.name);
+  const advisoryFailed = results.filter((x) => x.advisory && !x.ok).map((x) => x.name);
   if (advisoryFailed.length) console.log(`\n  ${c.yellow(L.doctor.advisorySummary(advisoryFailed))}`);
   return { failed, ran: gates.length, results, advisoryFailed };
 }
@@ -228,6 +283,8 @@ async function writeRunReport({ version, reached, results }) {
 }
 
 async function cmdDoctor() {
+  const brief = process.argv.includes("--brief");
+  const buf = brief ? beginBrief() : null;
   // Версия в шапке — единственное, что привязывает баг-репорт к коммиту, если ставили не из
   // релиза: без неё "у меня не работает" ничем не отличается от любой другой версии за год.
   let version = "";
@@ -270,6 +327,15 @@ async function cmdDoctor() {
 
   // Опечатка в имени поля означала «поля нет»: вердикт выдавался неверный, а причина молчала.
   // Называем поле и говорим, какие бывают — иначе человек ищет ошибку в проекте, а она в файле.
+  // Строка, которую разбор не понял, называется ПЕРВОЙ и жёлтым: человек видит проверку в
+  // файле, а её не существует. До 2026-09-09 такая строка исчезала без слова — найдено
+  // случайно, гейтом с кириллическим именем, который «прошёл», не запустившись.
+  try {
+    const bad = unparsedLines(await readFile(join(CWD, MANIFEST), "utf8"));
+    for (const b of bad) console.log(c.yellow(`\n  ${L.doctor.manifestUnparsed(b.line, b.text)}`));
+    if (bad.length) console.log(c.dim(`  ${L.doctor.manifestUnparsedWhy}`));
+  } catch { /* манифеста нет — про строки в нём говорить нечего */ }
+
   const unknown = unknownKeys(man);
   if (unknown.length) {
     console.log(c.yellow(`\n  ${L.doctor.manifestUnknown(unknown)}`));
@@ -326,7 +392,7 @@ async function cmdDoctor() {
     await reportBaseline(man, facts);
     process.exit(0);
   }
-  await reportCatalog(man, facts);
+  const cat = (await reportCatalog(man, facts)) || { held: 0, todo: 0, todoRecs: [] };
 
   // «Объявлен» ≠ «работает». Без --run говорим это вслух, а не молчим.
   const wantRun = process.argv.includes("--run");
@@ -359,9 +425,12 @@ async function cmdDoctor() {
     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);
+    await finishBrief(buf, { held: cat.held, todo: cat.todo, level: reached, red: failedNames ? String(failedNames).split(", ").filter(Boolean) : [] }, cat.todoRecs, pass);
     process.exit(pass ? 0 : 1);
   }
-  process.exit(missing || reached < 0 || gateFailed ? 1 : 0);
+  const ok = !(missing || reached < 0 || gateFailed);
+  await finishBrief(buf, { held: cat.held, todo: cat.todo, level: reached, red: [] }, cat.todoRecs, ok);
+  process.exit(ok ? 0 : 1);
 }
 
 // Наружу — только команда. Остальное здесь же и используется: экспорт, который никто не

package/tool/commands/project.mjs

@@ -8,6 +8,7 @@ import {
   CWD, PKG_ROOT, DOCS_SRC, RULES_SRC, TARGET_DIR, MANIFEST, SELF, REPO_URL, c, exists, die,
   copyDir, writeIfAbsent, FEEDBACK_MARK, docPath } from "../lib/core.mjs";
 import { AGENTS_MD, CLAUDE_MD, MANIFEST_YML } from "../lib/templates.mjs";
+import { banner } from "../lib/banner.mjs";
 import { readManifest } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict } from "../lib/repo.mjs";
 import { installGate } from "./gates.mjs";
@@ -40,7 +41,9 @@ async function cmdInit(args) {
   const claude = join(CWD, "CLAUDE.md");
   track(await writeIfAbsent(claude, CLAUDE_MD, { force }), claude);
 
-  console.log(c.bold("\naqk init\n"));
+  // Заставка в начале init — первая встреча человека с комплектом. Второй раз он увидит её
+  // только если сам спросит `--version`: то, что видишь тридцатый раз, перестаёт читаться.
+  console.log(`\n${banner()}\n`);
   if (created.length) {
     console.log(c.green(`  ${L.init.created(created.length)}`));
     for (const f of created.slice(0, 8)) console.log(`    ${f}`);
@@ -96,7 +99,20 @@ ${c.bold(L.feedback.title)}
     ${url}/issues/new
 ${c.dim(`  ${L.feedback.once}`)}
 `);
-  await writeIfAbsent(FEEDBACK_MARK, "shown\n", { force: false });
+  // Пометка «уже показывали» — удобство, а не работа команды. Домашнего каталога может не быть
+  // записываемым вовсе: в контейнере, запущенном `--user 1001:127`, у этого uid нет записи в
+  // /etc/passwd, `homedir()` даёт «/», и запись падает с EACCES на `/.config`. До 2026-09-09
+  // это роняло ВЕСЬ `init` — то есть любого, кто набрал команду из нашей же документации по
+  // docker. Локально не воспроизводилось случайно: uid разработчика 1000 совпадает с
+  // пользователем `node` в образе, у которого дом есть. Нашёл конвейер, где uid 1001.
+  //
+  // Молча глотать нельзя — это то, что красит наш же swallowed-error. Поэтому вслух: не
+  // запомнили, покажем снова. Установка при этом доходит до конца.
+  try {
+    await writeIfAbsent(FEEDBACK_MARK, "shown\n", { force: false });
+  } catch {
+    console.log(c.dim(`  ${L.feedback.notRemembered}`));
+  }
 }
 
 function findJournal() {

package/tool/commands/prove.mjs

@@ -17,6 +17,7 @@ function line(r) {
       r.why === "no-samples" ? P.noSamples
       : r.why === "other-recipe" ? P.otherRecipe(r.forRecipe.lang)
       : r.why === "no-target" ? P.noTarget
+      : r.why === "needs-program" ? P.needsProgram(r.missing.join(", "))
       : P.empty;
     return `  ${c.dim("~")}  ${c.dim(pad)} ${c.dim(why)}`;
   }