agent-quality-kit 0.8.0 → 0.10.0

package/kit/gates/api-contract-has-arbiter/check.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env sh
+# Спецификация API лежит — а держит ли её кто-нибудь.
+#
+# ЗАЧЕМ ИМЕННО ЭТО. `openapi.yaml` — обещание чужому коду: вот поля, вот типы, вот что
+# обязательно. Обещание, которое никто не сверяет с сервером, расходится с ним молча и
+# обнаруживается у потребителя. Это наш центральный класс, только на уровне API.
+#
+# ЗАМЕР, ИЗ КОТОРОГО ВЗЯЛАСЬ ЗАПИСЬ (2026-09-09). Стенд: сервер врёт в каждом поле ответа —
+# `id` строкой вместо числа, обязательного `email` нет вовсе, `created_at` не дата. Пятисоток
+# при этом нет, коды ответа честные. Кто что сказал:
+#   spectral (spectral:oas)              -> код 0, три замечания: нет контакта, описания, тегов
+#   schemathesis, умолчания              -> код 1, три нарушения схемы в ответах
+#   schemathesis -c not_a_server_error   -> код 0, «18 из 18 прошли»
+# Отсюда обе красные ветки этой проверки: держать спецификацию некому — и держать поручено
+# тому, кто по построению не может покраснеть.
+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"
+
+# --- есть ли договор ----------------------------------------------------------
+# По имени файла, а не по расположению: спецификацию кладут в корень, в `docs/`, рядом с
+# приложением. Расширение обязательно разбираемое — `openapi.md` это рассказ о договоре.
+# `-print` в конце ОБЯЗАТЕЛЕН. Без него действие по умолчанию применяется ко всему выражению,
+# и ветка `-prune -o` печатает сами обойдённые каталоги: в списке спецификаций оказывались
+# `./.git` и `./.aqk`. Найдено аудитом фич 2026-09-09, образцами не ловилось.
+SPECS=$(find "$DIR" $(skip_find) -type f \
+  \( -iname 'openapi*.yaml' -o -iname 'openapi*.yml' -o -iname 'openapi*.json' \
+  -o -iname 'swagger*.yaml' -o -iname 'swagger*.yml' -o -iname 'swagger*.json' \
+  -o -iname 'asyncapi*.yaml' -o -iname 'asyncapi*.yml' -o -iname 'asyncapi*.json' \) \
+  -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$')
+[ -z "$SPECS" ] && { echo "спецификации API здесь нет — эта проверка не про тебя"; exit 0; }
+
+# --- кто её держит ------------------------------------------------------------
+# Четыре семьи держателей, и они отвечают на РАЗНЫЕ вопросы — подробности в README:
+#   сверка с сервером  schemathesis, dredd, portman, newman, pact — «документ не врёт»
+#   линт документа     spectral, redocly, vacuum, openapi-spec-validator, swagger-cli
+#   ломающие правки    oasdiff — «вчерашний клиент переживёт сегодняшний выпуск»
+#   потребитель        openapi-typescript, orval, oapi-codegen, openapi-generator, kubb —
+#                      типы порождены договором, и расхождение ломает сборку
+HOLDERS='schemathesis|dredd|portman|newman[[:space:]]+run|pact-broker|pact-verifier|can-i-deploy|spectral[[:space:]]+lint|redocly[[:space:]]+(lint|bundle)|vacuum[[:space:]]+(lint|report|html-report)|openapi-spec-validator|swagger-cli|oasdiff|openapi-typescript|orval|oapi-codegen|openapi-generator|kubb'
+# Ищем в том, что ЗАПУСКАЮТ: конвейер, оболочечные скрипты, сборочные файлы, объявления пакета
+# и манифест самого комплекта. Не в коде: упоминание инструмента в исходнике — не его запуск.
+FOUND=$(grep -rnE "$HOLDERS" $(skip_grep) \
+  --include=*.yml --include=*.yaml --include=*.sh --include=*.json --include=*.toml \
+  --include=*.ini --include=*.cfg --include=*.mk --include=Makefile --include=Justfile \
+  --include=justfile --include=Taskfile.yml --include=*.gradle --include=Jenkinsfile \
+  "$DIR" 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$')
+
+# ОПРЕДЕЛЕНИЕ ЗАПИСИ КАТАЛОГА — НЕ НАХОДКА, и это касается не только своей записи. Соседняя
+# запись `ci-actually-fails` держит в своём `check.sh` строку со списком запускалок, где
+# перечислены все инструменты про API разом. Проверка находила её и решала, что спецификацию
+# кто-то держит: договор не держал никто, а гейт был ЗЕЛЁНЫМ.
+#
+# Найдено аудитом фич 2026-09-09 — прогоном на настоящем проекте, а не образцами: красный и
+# зелёный образцы лежат по одному, а в проекте записи стоят рядом. Признак определения взят
+# самый надёжный: в той же папке лежит `gate.yml`.
+FOUND=$(printf '%s\n' "$FOUND" | while IFS= read -r L; do
+  F="${L%%:*}"
+  [ -n "$F" ] || continue
+  [ -f "$(dirname "$F")/gate.yml" ] && continue
+  printf '%s\n' "$L"
+done | grep -v '^$')
+
+if [ -z "$FOUND" ]; then
+  printf '%s\n' "$SPECS" | sed 's/$/: спецификацию не держит ни одна команда/'
+  echo "  почини: заведи арбитра, который краснеет, когда сервер ушёл от договора —"
+  echo "  «schemathesis run openapi.yaml --url <адрес>» в конвейере. Линтер спецификации"
+  echo "  (spectral, redocly, vacuum) этого НЕ заменяет: он читает документ, а не сервер,"
+  echo "  и на сервере, который врёт в каждом поле, остаётся зелёным."
+  exit 1
+fi
+
+# --- держит, но провалиться не может -------------------------------------------
+# `--checks not_a_server_error` (и короткое `-c`) оставляет от арбитра одну проверку: «не
+# пятисотка». На замере выше это ровно код 0 при сервере, который врёт в каждом поле. Умолчание
+# у schemathesis — ВСЕ проверки разом, поэтому такое сужение это не настройка, а отключение.
+# КАК ОБЕЗВРЕЖЕН АРБИТР — вопрос к ОБЪЯВЛЕНИЮ запуска, а не к любому файлу, где эта строка
+# встретилась. Граница взята не отсюда: `ci-actually-fails` уже проводит её теми же словами —
+# «провал, погашенный внутри скрипта, это логика скрипта, а не конфиг конвейера». Внутри
+# оболочечного скрипта вердикт решают `set -e`, `trap` и явный `exit`, и по одной строке о нём
+# судить нельзя.
+#
+# Поймано на себе в тот же день: наш `smoke.sh` держит образцы нарушений в heredoc — и новая
+# запись покраснела на собственном наборе проверок. Одна из трёх находок была вообще в
+# КОММЕНТАРИИ, поясняющем замер; отсюда же `drop_comments`.
+RUNS=$(printf '%s\n' "$FOUND" | grep -E '\.(ya?ml|toml|json|mk|gradle):|/(Makefile|Justfile|justfile|Jenkinsfile):' | drop_comments)
+
+NARROW=$(printf '%s\n' "$RUNS" | grep -E '(-c|--checks)[[:space:]=]+not_a_server_error([[:space:]]|$|")')
+
+# Вторая форма того же: `oasdiff breaking` БЕЗ `--fail-on`. Замер 2026-09-09 на паре
+# спецификаций, где из ответа убрано обязательное поле: инструмент печатает
+# «1 changes: 1 error … removed the required property `email`» — и выходит с НУЛЁМ. С
+# `--fail-on ERR` на той же паре код 1, а на паре без ломающих изменений снова 0.
+# Вывод громкий и красный на вид, конвейер зелёный — самая коварная форма молчания.
+#
+# Форма `uses: oasdiff/oasdiff-action/...` не считается находкой: действие роняет прогон само.
+# Подкоманда `changelog` тоже: она затем и нужна, чтобы напечатать, а не уронить.
+LOUD=$(printf '%s\n' "$RUNS" | grep -E 'oasdiff[[:space:]]+breaking' | grep -v 'oasdiff-action' | grep -v -- '--fail-on')
+
+if [ -n "$NARROW$LOUD" ]; then
+  [ -z "$NARROW" ] || printf '%s\n' "$NARROW" | sed 's/$/  <- арбитр сужен до «не пятисотка»/'
+  [ -z "$LOUD" ] || printf '%s\n' "$LOUD" | sed 's/$/  <- печатает ломающие изменения и выходит с нулём/'
+  [ -z "$NARROW" ] || {
+    echo "  почини: убери «--checks not_a_server_error» — у schemathesis по умолчанию включены"
+    echo "  ВСЕ проверки, включая response_schema_conformance. Сужение до одной оставляет"
+    echo "  зелёный прогон на сервере, который врёт в каждом поле ответа."
+  }
+  [ -z "$LOUD" ] || echo "  почини: добавь «--fail-on ERR» — без него oasdiff печатает находки и выходит с нулём."
+  echo "  провал, погашенный «|| true» или «continue-on-error», — это ci-actually-fails."
+  exit 1
+fi
+exit 0

package/kit/gates/api-contract-has-arbiter/gate.yml

@@ -0,0 +1,15 @@
+intent: у спецификации API есть арбитр, и он может провалиться
+intent_en: the API specification has an arbiter, and that arbiter can actually fail
+
+# Только там, где договор с чужим кодом уже есть. Библиотеке, консольной программе и монолиту
+# без внешнего интерфейса эта запись не нужна: показанной не тому записи не верят.
+trigger:
+  has_api_spec: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-09 «сузили арбитра до самой слабой проверки» — на стенде,
+  где сервер врёт в каждом поле ответа, schemathesis с умолчаниями даёт код 1 и три нарушения
+  схемы, он же с `-c not_a_server_error` — код 0 и «18 из 18 прошли»; spectral на той же
+  спецификации тоже код 0 и жалобы на отсутствие тегов

package/kit/gates/api-contract-has-arbiter/green/.github/workflows/ci.yml

@@ -0,0 +1,12 @@
+# Арбитр назван и может провалиться. Оба слова важны:
+#   schemathesis с умолчаниями сверяет ОТВЕТЫ сервера со схемой, а не только отсутствие пятисоток;
+#   oasdiff без «--fail-on ERR» печатает ломающие изменения и выходит с нулём — замерено.
+name: ci
+on: [push]
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: schemathesis run openapi.yaml --url http://localhost:8000
+      - run: oasdiff breaking base.yaml openapi.yaml --fail-on ERR

package/kit/gates/api-contract-has-arbiter/green/openapi.yaml

@@ -0,0 +1,18 @@
+openapi: 3.0.3
+info: { title: Заказы, version: 1.0.0 }
+paths:
+  /users/{id}:
+    get:
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer } }
+      responses:
+        '200':
+          description: Пользователь
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [id, email]
+                properties:
+                  id: { type: integer }
+                  email: { type: string }

package/kit/gates/api-contract-has-arbiter/red/.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+# Договор лежит, конвейер есть — и ни одна команда договора не касается. Спецификация здесь
+# документация, а не контракт: сервер уходит от неё молча.
+name: ci
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pytest
+      - run: ruff check .

package/kit/gates/api-contract-has-arbiter/red/openapi.yaml

@@ -0,0 +1,18 @@
+openapi: 3.0.3
+info: { title: Заказы, version: 1.0.0 }
+paths:
+  /users/{id}:
+    get:
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer } }
+      responses:
+        '200':
+          description: Пользователь
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [id, email]
+                properties:
+                  id: { type: integer }
+                  email: { type: string }

package/kit/gates/ci-actually-fails/check.sh

@@ -14,7 +14,15 @@ CI=$(find "$DIR/.github/workflows" "$DIR/.gitlab-ci.yml" "$DIR/.circleci" "$DIR/
 # Что считается ПРОВЕРКОЙ. Список намеренно закрытый: маскировка бывает законной — необязательная
 # выгрузка отчёта, публикация артефакта, уведомление. Красить всякий `continue-on-error` значит
 # получить гейт, который выключат первым. Красим только гашение того, что выносит вердикт.
-RUNNERS='aqk|doctor --run|pytest|tox|nox|unittest|jest|vitest|mocha|jasmine|karma|playwright|cypress|eslint|tsc|ruff|flake8|pylint|mypy|pyright|bandit|semgrep|gitleaks|trivy|rubocop|golangci-lint|golint|govet|go vet|go test|staticcheck|shellcheck|hadolint|actionlint|codespell|reviewdog|cargo test|cargo clippy|mvn|gradle|phpstan|psalm|npm test|npm run (test|lint|check|typecheck)|yarn (test|lint)|pnpm (test|lint)|make (test|lint|check)'
+# ПОЧЕМУ ЗДЕСЬ ЕСТЬ ИНСТРУМЕНТЫ ПРО API И ПОЧЕМУ НЕ ВСЕ ИХ ИМЕНА ЦЕЛИКОМ.
+# Замер 2026-09-09: три шага — фаззер спецификации, детектор ломающих изменений и сверка с
+# ожиданиями потребителей, — все три под `continue-on-error: true`, и эта проверка сказала
+# «чисто», код 0. Список знал `pytest` и `eslint` и не знал ни одного инструмента про API,
+# то есть самый дорогой класс проверок проходил как строка в логе.
+# Имена сокращены до подкоманды там, где слово обиходное: `vacuum` без `lint` совпадает с
+# обслуживанием базы (`psql -c 'VACUUM ANALYZE'`), а шаг обслуживания имеет полное право быть
+# прощающим. Ложный красный дороже пропуска: гейт, который врёт, выключают целиком.
+RUNNERS='aqk|doctor --run|pytest|tox|nox|unittest|jest|vitest|mocha|jasmine|karma|playwright|cypress|eslint|tsc|ruff|flake8|pylint|mypy|pyright|bandit|semgrep|gitleaks|trivy|rubocop|golangci-lint|golint|govet|go vet|go test|staticcheck|shellcheck|hadolint|actionlint|codespell|reviewdog|cargo test|cargo clippy|mvn|gradle|phpstan|psalm|npm test|npm run (test|lint|check|typecheck)|yarn (test|lint)|pnpm (test|lint)|make (test|lint|check)|schemathesis|dredd|oasdiff|spectral lint|redocly (lint|bundle)|vacuum (lint|report|html-report)|pact-broker|pact-verifier|can-i-deploy|portman|newman run|manage.py spectacular'
 
 # Закрытый список не поспевает: замер по чужим репозиториям нашёл шаг «Run reviewdog
 # (github-pr-check)» под `continue-on-error: true`, и ни одно имя из списка в нём не звучало.

package/kit/gates/color-from-token/check.sh

@@ -67,7 +67,11 @@ HITS=$(find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null \
         # Якорь ссылки «#defining-entry-points» начинается с «#def», за которым идёт «i»: по
         # прежнему правилу это был цвет. Замер 2026-09-08 по шести чужим репозиториям: в uv
         # ложным оказалось именно это, в docs/js/extra.js.
-        if (line ~ /#[0-9a-fA-F]{8}([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F]{6}([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F]{3}([^0-9a-zA-Z_-]|$)/)
+        # Цвет выписан поразрядно: часть сборок mawk повторители не понимает (в node:22-slim
+        # это mawk 1.3.4 20200120), а какая сборка у читателя — мы не знаем
+        # {3},{6},{8}, и это условие не срабатывало никогда — гейт молчал на красном образце.
+        # Поймано сборкой docker-образа 2026-09-08, а не прогоном: на хосте gawk.
+        if (line ~ /#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]([^0-9a-zA-Z_-]|$)|#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]([^0-9a-zA-Z_-]|$)/)
           print FILENAME ":" FNR ":" $0
       }
     ' 2>/dev/null \

package/kit/gates/commit-explains-itself/check.sh

@@ -65,6 +65,21 @@ else
   [ -z "$LESSONS" ] && LESSONS="incidents"
   case "$LESSONS" in http*) LESSONS="" ;; esac   # journal по адресу, а не путём — не применимо
   if [ -n "$LESSONS" ]; then
+    # СОСТАВ КОММИТА СЧИТАЕТСЯ ДИФФОМ С РОДИТЕЛЕМ, а родителя может не быть видно. При разборе
+    # предложения изменений GitHub выкладывает синтетический коммит слияния мелким клоном: сам
+    # коммит автора (`HEAD^2`) в клоне есть, а его родителя нет. `git show --name-only` в этом
+    # случае считает коммит КОРНЕВЫМ и выдаёт всё дерево — освобождение «трогает только журнал»
+    # переставало срабатывать МОЛЧА, и гейт требовал отчёт там, где не должен.
+    #
+    # Поймано конвейером на записи в собственный журнал 2026-09-09; опыт показал границу точно:
+    # глубина 2 — красный, глубина 3 — чисто. Молчать здесь нельзя: пропуск называет себя, иначе
+    # выключенная проверка неотличима от работающей.
+    if ! (cd "$DIR" && git rev-parse -q --verify "$REF^" >/dev/null 2>&1); then
+      echo "мелкий клон: у коммита не видно родителя — состав не определить, проверка пропущена"
+      echo "  чтобы она работала на предложении изменений:"
+      echo "  actions/checkout@v4 с fetch-depth: 3 (слияние, его родитель и родитель родителя)"
+      exit 0
+    fi
     FILES=$(cd "$DIR" && git show --pretty=format: --name-only "$REF" 2>/dev/null | grep -v '^$')
     if [ -n "$FILES" ]; then
       OUTSIDE=$(printf '%s\n' "$FILES" | grep -v "^$LESSONS/" | grep -v "^$LESSONS\$")

package/kit/gates/complexity-limit/red/deep.go

@@ -0,0 +1,17 @@
+package svc
+
+func Route(a, b, c, d int) int {
+	if a > 0 {
+		if b > 0 {
+			for i := 0; i < c; i++ {
+				switch d {
+				case 1:
+					if a > b {
+						return 1
+					}
+				}
+			}
+		}
+	}
+	return 0
+}

package/kit/gates/complexity-limit/red/deep.rs

@@ -0,0 +1,17 @@
+pub fn route(a: i32, b: i32, c: i32, d: i32) -> i32 {
+    if a > 0 {
+        if b > 0 {
+            for i in 0..c {
+                match d {
+                    1 => {
+                        if a > b {
+                            return 1;
+                        }
+                    }
+                    _ => {}
+                }
+            }
+        }
+    }
+    0
+}

package/kit/gates/gate-not-weakened/red/suppress.go

@@ -0,0 +1,5 @@
+package svc
+
+// Голый nolint гасит ВСЁ на строке: адреса у подавления нет.
+//nolint
+func Risky() error { return nil }

package/kit/gates/gate-not-weakened/red/suppress.rs

@@ -0,0 +1,3 @@
+// allow(warnings) гасит всё разом: это «выключено всё», а не «выключено вот это».
+#[allow(warnings)]
+pub fn risky() {}

package/kit/gates/lesson-has-outcome/check.sh

@@ -30,7 +30,11 @@ FILES=$(find "$DIR/$LESSONS" -type f -name '*.md' 2>/dev/null)
 # старые записи несут её строкой ">", новые — абзацем "**Вывод.**"; оба варианта законны.
 printf '%s\n' $FILES | while read -r F; do
   awk -v FILE="$F" '
-    /^## [0-9]{4}-[0-9]{2}-[0-9]{2}/ { flush(); title = $0; sub(/^## /, "", title); is_entry = 1; has_mark = 0; next }
+    # Дата выписана поразрядно, а не как [0-9]{4}: часть сборок mawk повторители не понимает
+    # повторители в регулярках, и такая строка не совпадала НИКОГДА. Гейт молча выходил с нулём
+    # на собственном красном образце. Поймано сборкой образа 2026-09-08: на хосте gawk, в образе
+    # mawk, и приёмка каталога внутри образа отклонила две записи из двадцати.
+    /^## [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/ { flush(); title = $0; sub(/^## /, "", title); is_entry = 1; has_mark = 0; next }
     /^## / { flush(); is_entry = 0; next }
     (/✅/ || /🔧/ || /📜/ || /👤/) { has_mark = 1 }
     END { flush() }

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/kit/gates/protection-not-removed/README.md

@@ -0,0 +1,67 @@
+# protection-not-removed
+
+**Набор объявленных гейтов может только расти.** Убрать гейт из `.aqk.yml` можно — но не молча.
+
+## Зачем
+
+Комплект ловит агента, когда тот выключает **сигнал**: `# noqa` ловит `gate-not-weakened`,
+`pytest || true` — `ci-actually-fails`, тест, зелёный при любых данных, — `test-has-assertion`.
+
+А главный рубильник — сам манифест — не сторожил никто. Замер 2026-09-09 на живой фикстуре:
+
+```console
+$ aqk doctor --run --min 1          # четыре гейта, настоящий секрет в коде
+  ✘ secrets-not-in-code   код 1
+код: 1
+
+$ grep -v "secrets-not-in-code:" .aqk.yml > tmp && mv tmp .aqk.yml
+$ aqk doctor --run --min 1
+  Порог AQK-1 пройден.
+код: 0                              # секрет на месте, файлы гейта на диске
+```
+
+Ни `doctor`, ни `report --since`, ни `vitals`, ни блок состояния для агента этого не заметили.
+Это `pytest || true` этажом выше. И бьёт сильнее обычного обхода: `# noqa` виден в коде, глаз за
+него цепляется, а удалённая строка — это **отсутствие**, а отсутствие не рецензируют.
+
+## Как устроено
+
+Рядом с реестрами долга лежит `gates-declared.txt` — снимок объявленной защиты. Проверка сверяет
+его с `gates:` манифеста:
+
+- имя из снимка пропало из манифеста → **красный**;
+- имя в снимке несёт причину после `#` → снятие названо, прогон зелёный, причина печатается;
+- новые гейты дописываются в снимок сами: набор растёт, укоротить его молча нельзя;
+- снимка нет, но он **был в истории git** → красный: удаление снимка снимает и саму проверку.
+
+Снять гейт по-прежнему можно. Требуется одно: назвать причину — как `deprecated` обязан нести
+`superseded_by`. Решение остаётся за человеком и перестаёт быть невидимым.
+
+## Готовый аналог
+
+**Есть похожие, и они про другое.** [`imbue-ai/ratchets`](https://github.com/imbue-ai/ratchets)
+и [`eslint-seatbelt`](https://www.notion.com/blog/how-we-evolved-our-code-notions-ratcheting-system-using-custom-eslint-rules)
+сторожат **число нарушений**: счётчик по правилу может только уменьшаться.
+
+Удаление самого правила они не ловят — и это не догадка, а их документация, проверено
+2026-09-09: «Counts for rules no longer in the resolved enabled set are kept dormant (no
+cleanup). `ratchets tighten` emits a stderr warning naming each orphan». То есть правило,
+убранное из конфига, оставляет счётчик дремать, печатается предупреждение в stderr — **удаление
+не блокируется и объяснения не требует**.
+
+Разница принципиальная: у счётчикового храповика удаление правила выглядит как **снижение до
+нуля**, то есть как успех. Ровно та подмена, против которой написан весь комплект.
+
+## Чего НЕ ловит
+
+- **Гейт, оставленный в манифесте, но выхолощенный до `true`.** Имя на месте, снимок доволен.
+  Это ловит `gates-are-runnable` (пустая команда) и `prove` (гейт не краснеет на красном
+  образце) — но `lint: "true"` пройдёт обе. Отдельной защиты от подмены команды здесь нет.
+- **Причину, написанную для отвода глаз.** «# снят: не нужен» — законная строка. Проверка
+  требует, чтобы решение было НАЗВАНО, а не чтобы оно было верным: верность оценивает человек
+  в дифе. Это сознательная граница, та же, что у `deprecated`.
+- **Удаление вместе со снимком в одном коммите на свежем клоне.** Свидетель — история git;
+  в репозитории без истории (или при `--depth 1` без этого файла) проверка скажет «снимок
+  снят заново», а не «удалён».
+- **Гейты, объявленные пустой командой.** Они не считаются объявленными — защиты они и не
+  давали.