agent-quality-kit 0.9.0 → 0.10.0

package/kit/gates/README.md

@@ -128,6 +128,28 @@ requires: checkwash
 (`AQK_GATES_STRICT=1`, поднят в нашем конвейере) делает такой пропуск ошибкой: на машине,
 которая инструменты сама и ставит, «нечем проверить» обязано быть красным.
 
+## Образец про секреты обязан быть узнаваем НАМИ и не узнаваем сканерами
+
+Красный образец для записи про секреты — правдоподобный ключ. Слишком правдоподобный отправить
+нельзя: защита GitHub от секретов отклоняет push целиком.
+
+```
+remote: —— Stripe API Key ——
+remote:      path: kit/gates/secrets-not-in-code/red/leak.go:4
+remote: Push cannot contain secrets
+```
+
+Проверено 2026-09-09: `sk_live_` плюс тридцать четыре знака совпало с настоящим форматом Stripe,
+и ветка не ушла вовсе. Работающий образец короче настоящего ключа: наш гейт узнаёт его по
+префиксу, а чужой сканер по длине и форме — нет.
+
+**Правило: образец подбирается так, чтобы краснел НАШ гейт и молчал чужой сканер.** Иначе запись
+нельзя ни отправить, ни принять — и автор узнаёт об этом только на push, потратив работу.
+
+**И не цитируй значение в документации.** Запись журнала, процитировавшая образец дословно,
+уронила наш же `secrets-not-in-code` — текст о секрете попал под правило о секретах. В прозе
+нужен рассказ о форме («тот же префикс, вдвое меньше знаков»), а не сама форма.
+
 ## Запись без переносимого рецепта
 
 Иногда переносимой проверки быть не может: чтобы понять, вызывают ли функцию, нужен граф

package/kit/gates/api-contract-has-arbiter/README.md

@@ -0,0 +1,63 @@
+# У спецификации 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 прошли» — ни одной находки |
+
+Отсюда обе красные ветки. Замер целиком — `incidents/README.md`, 2026-09-09.
+
+**Что именно проверяется.** Записи две, и вторая тоньше первой.
+
+1. **Спецификацию не держит ни одна команда.** Файл `openapi*.{yaml,yml,json}` (и `swagger*`,
+   `asyncapi*`) в репозитории есть, а ни в конвейере, ни в сборочных файлах, ни в скриптах, ни
+   в объявлении пакета нет ни одного инструмента из четырёх семей ниже.
+2. **Арбитр сужен до «не пятисотка».** `schemathesis --checks not_a_server_error` (или `-c`).
+   У `schemathesis` по умолчанию включены **все** проверки, включая
+   `response_schema_conformance`; сужение до одной — не настройка, а отключение.
+
+Четыре семьи держателей отвечают на **разные** вопросы, и подменять один другим нельзя:
+
+| Семья | Инструменты | Вопрос |
+|---|---|---|
+| сверка с сервером | `schemathesis`, `dredd`, `portman`, `newman`, `pact` | документ не врёт? |
+| линт документа | `spectral`, `redocly`, `vacuum`, `openapi-spec-validator`, `swagger-cli` | документ хорошо написан? |
+| ломающие правки | `oasdiff` | вчерашний клиент переживёт сегодняшний выпуск? |
+| потребитель | `openapi-typescript`, `orval`, `oapi-codegen`, `openapi-generator`, `kubb` | типы порождены договором, а не переписаны руками? |
+
+**Готовый аналог.** Не нашли, и это проверено. Все четыре семьи предполагают, что их **уже
+запускают**: `spectral` читает документ, `schemathesis` — сервер, `oasdiff` — две версии
+документа. Ни один не задаёт вопрос «а меня вообще кто-нибудь запускает». Это ровно форма
+записи `promise-has-gate`: обещание, у которого не назван сторож.
+
+**Чего НЕ ловит.**
+
+- **Что арбитр проверяет ПРАВИЛЬНЫЕ вещи.** Один только линтер спецификации считается
+  держателем, хотя на сервере, который врёт в каждом поле, он остаётся зелёным. Красить за это
+  нельзя: репозиторий, который публикует чужую спецификацию (клиентский SDK, описание чужого
+  API), сервером не владеет вовсе. Разбор — `kit/docs/api-e2e.md`.
+- **Провал, погашенный `|| true` или `continue-on-error`.** Это `ci-actually-fails` — там же
+  теперь опознаются и инструменты про API.
+- **Обезвреженного арбитра внутри оболочечного скрипта.** Держателя ищем и в `*.sh`, а вопрос
+  «может ли он провалиться» задаём только объявлениям запуска: конвейеру, `Makefile`,
+  `justfile`, `package.json`. Внутри скрипта вердикт решают `set -e`, `trap` и явный `exit`, и
+  по одной строке о нём судить нельзя — ту же границу проводит `ci-actually-fails`. Поймано на
+  себе: наш `smoke.sh` держит образцы в heredoc, и запись покраснела на собственном наборе
+  проверок, причём одна находка была в комментарии.
+- **Спецификацию с нестандартным именем.** `docs/api/spec.yaml` не опознаётся: имя файла —
+  единственный надёжный признак, а `spec.yaml` встречается у чего угодно. Переименуй в
+  `openapi.yaml` — так его найдут и чужие инструменты, а не только этот.
+- **Сужение другими способами.** Ограничение одним методом (`--include-method GET`), крошечное
+  число примеров, выборка путей. Это законные настройки: у проекта бывает причина не трогать
+  запись. Красным сделано только то, у чего законного применения нет.
+- **Что спецификация вообще описывает этот сервер.** Файл может описывать чужой API; сверять
+  их машина не умеет.

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/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/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` без этого файла) проверка скажет «снимок
+  снят заново», а не «удалён».
+- **Гейты, объявленные пустой командой.** Они не считаются объявленными — защиты они и не
+  давали.

package/kit/gates/protection-not-removed/check.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env sh
+# Набор объявленных гейтов может только РАСТИ. Убрать гейт можно, но не молча.
+#
+# ЗАЧЕМ. Комплект ловит агента, когда тот выключает сигнал: `# noqa`, `pytest || true`,
+# ослабленный тест. А главный рубильник — сам манифест — не сторожил никто. Замер 2026-09-09:
+# четыре гейта и настоящий секрет в коде дают код 1; убираешь ОДНУ строку из `.aqk.yml` —
+# `Порог AQK-1 пройден`, код 0, секрет на месте, файлы гейта на диске. Ни `doctor`, ни `report`,
+# ни `vitals`, ни блок состояния для агента этого не заметили.
+#
+# Это `pytest || true` этажом выше. И бьёт сильнее обычного обхода: `# noqa` виден в коде, а
+# удалённая строка — это ОТСУТСТВИЕ, а отсутствие не рецензируют.
+#
+# ЧТО ЭТО НЕ ЗАПРЕЩАЕТ. Снять гейт по-прежнему можно — но названно. Причина пишется в реестре
+# после `#`, как `deprecated` обязан нести `superseded_by`: решение остаётся за человеком и
+# перестаёт быть невидимым.
+DIR="${1:-.}"
+MAN="$DIR/.aqk.yml"
+[ -f "$MAN" ] || { echo "нет .aqk.yml — проверять нечего"; exit 0; }
+
+MANTEXT="$(tr -d '\r' < "$MAN")"
+
+# Имена гейтов из блока gates:. Пустая команда защиты не даёт — такие не считаем объявленными.
+DECLARED="$(printf '%s\n' "$MANTEXT" \
+  | awk '/^gates:/{g=1;next} /^[A-Za-z]/{g=0} g && /^[[:space:]]+[A-Za-z0-9_-]+:[[:space:]]*[^[:space:]]/{print}' \
+  | sed 's/^[[:space:]]*\([A-Za-z0-9_-]*\):.*/\1/' | LC_ALL=C sort -u)"
+[ -z "$DECLARED" ] && { echo "гейтов не объявлено — сторожить нечего"; exit 0; }
+
+# Кавычки снимаются, и ПУСТОЕ значение считается отсутствующим. `init` кладёт `ratchets: ""`
+# намеренно — пустое поле честнее заглушки, — и без снятия кавычек путь получался «""/…»:
+# сообщение с таким путём человек не может выполнить. Найдено первым же прогоном в чужом
+# проекте, а не на нашем репозитории, где поле заполнено.
+RDIR="$(printf '%s\n' "$MANTEXT" | sed -n 's/^ratchets:[[:space:]]*//p' | head -1 \
+  | sed 's/^"//; s/"$//; s/^'"'"'//; s/'"'"'$//; s/[[:space:]]*$//')"
+[ -z "$RDIR" ] && RDIR="ratchets"
+REG="$DIR/$RDIR/gates-declared.txt"
+REL="$RDIR/gates-declared.txt"
+
+if [ ! -f "$REG" ]; then
+  # Реестра нет. Два разных случая, и путать их нельзя: снимка ещё не снимали — или его
+  # УДАЛИЛИ, что и есть тот самый обход, только другим файлом. Свидетель — git: если у пути
+  # есть история, файл существовал.
+  if git -C "$DIR" log -1 --format=%H -- "$REL" 2>/dev/null | grep -q .; then
+    echo "$REL был в истории и удалён — снимок объявленной защиты уничтожен"
+    echo "  почини: верни файл (git checkout -- $REL). Удаление снимка снимает и саму проверку —"
+    echo "  почини: это тот же обход, что удаление гейта, только через соседний файл."
+    exit 1
+  fi
+  mkdir -p "$DIR/$RDIR" || { echo "не создать $RDIR"; exit 2; }
+  printf '# Снимок объявленной защиты. Набор может только РАСТИ.\n' > "$REG"
+  printf '# Убрал гейт — напиши причину после # в его строке, иначе проверка краснеет.\n' >> "$REG"
+  printf '%s\n' "$DECLARED" >> "$REG"
+  echo "снят снимок объявленной защиты: $(printf '%s\n' "$DECLARED" | wc -l | tr -d ' ') гейтов → $REL"
+  echo "  почини: закоммить этот файл — без него проверка не знает, что защита была."
+  exit 0
+fi
+
+# Имя без причины — строка реестра, где после имени НЕТ решётки. Имя с причиной — снятое
+# осознанно; печатаем его отдельно, но прогон не роняем.
+GONE=""
+NAMED=""
+while IFS= read -r LINE; do
+  case "$LINE" in ''|'#'*) continue ;; esac
+  NAME=$(printf '%s' "$LINE" | sed 's/[[:space:]]*#.*//; s/[[:space:]]*$//')
+  [ -z "$NAME" ] && continue
+  printf '%s\n' "$DECLARED" | grep -qx "$NAME" && continue
+  case "$LINE" in
+    *'#'*) NAMED="$NAMED $NAME" ;;
+    *)     GONE="$GONE $NAME" ;;
+  esac
+done < "$REG"
+
+[ -n "$NAMED" ] && echo "совет: снято осознанно и названо в $REL:$NAMED"
+
+if [ -n "$GONE" ]; then
+  for N in $GONE; do
+    echo "$REL: гейт «$N» был объявлен и исчез из .aqk.yml"
+  done
+  echo "  почини: верни строку в gates: — либо, если снял намеренно, напиши причину в $REL"
+  echo "  почини: после имени через #, например «$N  # снят: закрыт гейтом lint»."
+  exit 1
+fi
+
+# Всё на месте — дописываем новые. Набор растёт сам; укоротить его молча нельзя.
+NEW=""
+for N in $DECLARED; do
+  sed 's/[[:space:]]*#.*//; s/[[:space:]]*$//' "$REG" | grep -qx "$N" || NEW="$NEW $N"
+done
+if [ -n "$NEW" ]; then
+  for N in $NEW; do printf '%s\n' "$N" >> "$REG"; done
+  echo "совет: в снимок дописаны новые гейты:$NEW"
+fi
+exit 0

package/kit/gates/protection-not-removed/gate.yml

@@ -0,0 +1,10 @@
+intent: объявленная защита не исчезает молча — набор гейтов в манифесте может только расти
+intent_en: declared protection does not vanish silently — the set of gates in the manifest may only grow
+
+trigger:
+  has_gates: true
+
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md — «2026-09-09 сигнализация построена, выключатель оставлен снаружи без пломбы»

package/kit/gates/protection-not-removed/green/.aqk.yml

@@ -0,0 +1,7 @@
+aqk: 1
+entry:
+  - AGENTS.md
+rules: .aqk/rules
+ratchets: .
+gates:
+  lint: "true"

package/kit/gates/protection-not-removed/green/gates-declared.txt

@@ -0,0 +1,4 @@
+# Снимок объявленной защиты. Набор может только РАСТИ.
+# Убрал гейт — напиши причину после # в его строке, иначе проверка краснеет.
+lint
+secrets-not-in-code  # снят 2026-09-09: закрыт гейтом lint, см. covers в манифесте

package/kit/gates/protection-not-removed/red/.aqk.yml

@@ -0,0 +1,7 @@
+aqk: 1
+entry:
+  - AGENTS.md
+rules: .aqk/rules
+ratchets: .
+gates:
+  lint: "true"

package/kit/gates/protection-not-removed/red/gates-declared.txt

@@ -0,0 +1,4 @@
+# Снимок объявленной защиты. Набор может только РАСТИ.
+# Убрал гейт — напиши причину после # в его строке, иначе проверка краснеет.
+lint
+secrets-not-in-code

package/kit/gates/secrets-not-in-code/red/leak.go

@@ -0,0 +1,9 @@
+package config
+
+// Ключ в коде: он уедет в историю git и останется там навсегда.
+//
+// Строка намеренно КОРОЧЕ настоящего ключа Stripe и повторяет ту, что лежит в settings.py:
+// правдоподобный ключ блокирует защита GitHub от секретов, и образец нельзя отправить в
+// репозиторий вовсе. Красный образец обязан быть узнаваем НАШИМ гейтом и не узнаваем чужими
+// сканерами — проверено 2026-09-09: push отклонён на «Stripe API Key».
+const StripeKey = "sk_live_51HxxQwErTyUiOpAsDfGh"

package/kit/gates/secrets-not-in-code/red/leak.rs

@@ -0,0 +1,5 @@
+// Ключ в коде: он уедет в историю git и останется там навсегда.
+//
+// Строка намеренно короче настоящего ключа Stripe — см. комментарий в leak.go: правдоподобный
+// ключ блокирует защита GitHub от секретов, и образец не отправить.
+pub const STRIPE_KEY: &str = "sk_live_51HxxQwErTyUiOpAsDfGh";

package/kit/gates/todo-without-task/red/later.go

@@ -0,0 +1,6 @@
+package svc
+
+func Send(to string) error {
+	// TODO: переписать на очередь
+	return deliver(to)
+}