agent-quality-kit 0.14.0 → 0.16.0

package/README.md

@@ -5,27 +5,56 @@
 [![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
 [![checks](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
 [![MIT licence](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
-[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
-**Check whether a repository is ready to have its code written by AI coding agents — and turn
-the rules it promises to follow into commands with exit codes.**
+**A check that cannot fail looks exactly like a check that passes.**
+
+`|| true`, `continue-on-error: true`, a linter pointed at an empty directory, a test with no
+assertion, a hook nobody ever installed, a command your `AGENTS.md` names that no longer exists —
+every one of them prints a green tick. AQK plants a known defect into a **copy** of your code,
+runs the checks your repository **declares**, and says which of them noticed and which stayed
+silent.
+
+It never reads "nothing printed" as "nothing wrong". Three outcomes, never two:
 
-Your `AGENTS.md` says what the project promises. Nothing checks that those promises are true, or
-that the commands it lists even run. AQK is that missing layer: one command reads the repository,
-reports a level from AQK-0 to AQK-3, and names every guard that is missing.
+| `✔` | `✘` | `?` |
+|---|---|---|
+| ran and found nothing | a finding about the code | **the check itself failed** — fix the tooling, not the file it named while dying |
 
-And one step further than the tools next door: `probe` plants a known defect into a copy of your
-project and checks whether your **declared** guards actually go red. "Tests exist" and "tests
-catch" are different claims — readiness scores measure the first one.
+The third one is the whole point. Counting it as either of the other two is how a repository ends
+up protected by checks that cannot go red.
 
 ```bash
-npx agent-quality-kit doctor    # code already exists: your level and what to install
+npx agent-quality-kit doctor    # code already exists: what it declares, what nothing is watching
 npx agent-quality-kit start     # no code yet: day-zero guards, right away
 ```
 
+Here is the first run on a repository whose pipeline is green and whose checks cannot go red.
+Nothing declared, nothing installed, no config written — it read the project's own `package.json`:
+
+```text
+Checks you ALREADY have (3) — found in your own files, not invented:
+✘  test         npm test   ← package.json
+   cannot fail: the verdict is swallowed right in the script — «|| true»
+✔  lint         npm run lint   ← package.json
+✘  typecheck    npm run typecheck   ← package.json
+   proves nothing: the whole script is a printout — «echo 'todo: turn this on'»
+
+2 of them cannot go red. Declaring a check that cannot fail only makes the silence
+machine-readable — fix the command first, then declare it.
+```
+
 `doctor` only reads. It writes no file and sends nothing anywhere — safe to point at a repository
-you have decided nothing about yet. Nothing to install: `npx` fetches the package (574.1 kB, measured 2026-09-10 — nothing guards this number, so check it
-when it matters).
+you have decided nothing about yet. Nothing to install: `npx` fetches the package — **≈0.7 MB**,
+a number a machine re-checks on every run rather than our memory.
+
+For Claude Code there is a plugin: the repository's real state reaches the agent's context before
+its first action, plus two skills — whether the declared checks can actually fail, and what to fix
+first. Installable from our own marketplace, with nobody's approval to wait for:
+
+```bash
+/plugin marketplace add arsen-ask-lx/Agent_Quality_Kit
+/plugin install aqk@agent-quality-kit
+```
 
 The one exception, named here because it is the only one: with `--brief` (how the hooks run it)
 `doctor` asks the npm registry for its own latest version — **at most once a day, never in CI**,
@@ -107,6 +136,10 @@ aqk context             the repository state in one block, for an agent's contex
 aqk prompt              one task to paste into an agent: what to fix, in order, and the
                         command that proves each item done
 aqk vitals              is what the kit runs on wired up: gate tools, hooks, freshness
+aqk feedback            feedback to the author: a report from the last run and probe,
+                        plus a prefilled link. No paths, no code; nothing is sent for you
+aqk feedback --send     send it in one command — with your own gh account, as a comment
+                        in an open discussion. Without the flag nothing ever leaves
 aqk doctor --run --brief  one line on success, the whole run on failure — for hooks
 aqk context --full      the same plus the command map and the rulebook verbatim (~7000
                         tokens against ~500: the price of an agent that does not guess)
@@ -146,7 +179,7 @@ $ npx agent-quality-kit doctor --run # runs them
         ./src/api/mailer.py:8:    print("sent", to)
   ✘  todo-without-task     exit 1
         ./src/web/app.js:1:// TODO: rewrite this
-  ✔  file-size-limit · entry-links-exist · complexity-limit
+  ✔  file-size-limit · deps-are-pinned · complexity-limit
 ```
 
 The failure text is written for an agent: it says **what exactly to do**. The exit code is for
@@ -193,6 +226,8 @@ gates:                     # what must pass — as commands, not as prose
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
 covers:                    # what a declared gate already holds — not counted as debt
   lint: [no-print-in-prod, swallowed-error]
+requires:                  # what a gate runs on, when the command does not show it
+  secrets-not-in-code: gitleaks
 samples:  gates            # a red and a green sample for every entry
 ratchets: ratchets         # debt registries: the list may only get shorter
 probe: 100                 # run the probe itself every N commits; 0 turns it off
@@ -222,6 +257,13 @@ catches things" are different claims, and the output says so out loud.
 
 ## Four levels
 
+[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
+
+**A level measures equipment, not quality.** It says which guards a repository has and has proven
+on samples — not that the code is good, and not that the guards caught anything in *your* files.
+That is what `probe` is for, and `doctor` prints what the level does **not** prove right under it.
+The badge above is this repository's own, kept honest by `aqk badge --check` in its pipeline.
+
 | Level | Required | What it proves |
 |---|---|---|
 | **AQK-0** | a manifest and an entry point | the tooling knows what to read |
@@ -351,7 +393,7 @@ Already using [pre-commit](https://pre-commit.com)? Three lines in the file you
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.14.0
+    rev: v0.16.0
     hooks:
       - id: aqk            # runs what the repository declares; blocks below AQK-1
       # - id: aqk-doctor   # read-only: the level and what is missing, blocks nothing
@@ -372,7 +414,7 @@ layer AQK adds.
 [![on the GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.14.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.16.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -431,12 +473,34 @@ files the diff touched:
 aqk doctor --run --since main    # only what this branch introduced
 ```
 
-Three outcomes, all of them said out loud. Findings inside the diff — red, as usual. Findings only
-outside it — green, with the number that was hidden, never a silent "all clear". And a gate whose
+Four outcomes, all of them said out loud. Findings inside the diff — red, as usual. Findings only
+outside it — green, with the number that was hidden, never a silent "all clear". A gate whose
 output carries no paths at all (a commit-message check, a CI-config check) **cannot** be narrowed:
-it stays red, and says why. Calling it green because there was nothing to narrow would be exactly
+it stays red, and says why. And a gate that **could not run at all** — no tool, an unexpected exit
+code, killed by a signal — is never narrowed by the diff: a failure has no place in the code, only
+itself. Calling either of the last two green because there was nothing to narrow would be exactly
 the silence this tool exists to remove.
 
+### The only payment: one answer
+
+The kit is free and collects nothing about you: it makes exactly one outgoing request — asking the
+npm registry whether a newer version exists. The payment is different: **one answer to the author**.
+So once per project, and only when there is something to tell, `doctor` or the agent block prints a
+line like "AQK could not check `smoke`; that is the most valuable thing to tell the author". Then:
+
+```bash
+aqk feedback     # builds the message and hands you a prefilled link — you send it, not us
+```
+
+The message carries: version, level, stack, what went red, what the kit could not check, which
+defect classes nobody catches here. **No paths, no code, no repository name** — you see every
+character you send. No GitHub? Forward the text as is. Not interested at all? `AQK_FEEDBACK=0`.
+
+Somewhere to say it in your own words:
+[where the kit was wrong](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/90) ·
+[what check is missing](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/91) ·
+[show your manifest](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/92).
+
 Every `doctor --run` rewrites `.aqk/last-run.md` — a short report of what actually ran and how
 long it took. The list of gates in the manifest says nothing about how many of them are alive
 right now; the report does. The file is ephemeral — keep it in your own `.gitignore`.
@@ -572,6 +636,12 @@ aqk blob     # assembles GOD_AI.md out of kit/docs — to hand the guides to a c
 The file is **assembled, not stored**: edit the originals. A hand-edited copy drifts from its
 source within a week, and then nobody knows which one is real.
 
+A single gate is waited on for **five minutes**; past that it is "could not check", not
+"clean". Change it with `AQK_GATE_TIMEOUT` (seconds): `AQK_GATE_TIMEOUT=900 aqk doctor --run`.
+The default is not arbitrary — SonarQube waits exactly as long for its quality gate. There is
+deliberately no per-gate `timeout` field in the manifest: neither pre-commit nor lefthook has
+one, and a long check is more honestly declared as a separate command than allowed to hang.
+
 ## Contributing a gate
 
 The catalogue lives on other people's bruises. The procedure and the bar are in

package/README.ru.md

@@ -5,28 +5,57 @@
 [![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
 [![проверки](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
 [![лицензия MIT](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
-[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
-**Проверить, готов ли репозиторий к тому, что код в нём пишет ИИ-агент — и превратить правила,
-которые проект обещает соблюдать, в команды с кодом возврата.**
+**Проверка, которая не может провалиться, выглядит точно так же, как проверка, которая прошла.**
+
+`|| true`, `continue-on-error: true`, линтер, направленный в пустой каталог, тест без единого
+утверждения, хук, который никто не поставил, команда из вашего же `AGENTS.md`, которой больше не
+существует, — каждое печатает зелёную галочку. AQK подсаживает заведомый дефект в **копию** вашего
+кода, запускает проверки, которые репозиторий **объявил**, и говорит, какая из них заметила, а
+какая промолчала.
+
+Он никогда не читает «ничего не напечатано» как «ничего страшного». Три исхода, а не два:
 
-`AGENTS.md` говорит, что проект обещает. Никто не проверяет, правда ли это и запускаются ли
-вообще перечисленные там команды. AQK — тот самый недостающий слой: одна команда читает
-репозиторий, называет ступень от AQK-0 до AQK-3 и перечисляет каждого недостающего сторожа.
+| `✔` | `✘` | `?` |
+|---|---|---|
+| отработала, чисто | находка о коде | **сама проверка не смогла** — чинить инструмент, а не файл, который она назвала, падая |
 
-И один шаг дальше, чем соседние инструменты: `probe` подсаживает заведомый дефект в копию вашего
-проекта и смотрит, покраснеет ли **объявленная** защита. «Тесты есть» и «тесты ловят» — разные
-утверждения, и оценки готовности меряют первое.
+Третий и есть весь смысл. Считать его одним из первых двух — так и получается репозиторий,
+защищённый проверками, которые не умеют покраснеть.
 
 ```bash
-npx agent-quality-kit doctor    # код уже есть: уровень и что поставить
+npx agent-quality-kit doctor    # код уже есть: что объявлено и чего не сторожит никто
 npx agent-quality-kit start     # кода ещё нет: сторожа дня 0 сразу
 ```
 
+Вот первый запуск на репозитории, где конвейер зелёный, а покраснеть не может ни одна проверка.
+Ничего не объявлено, ничего не поставлено, ни одного файла не записано — прочитан его же
+`package.json`:
+
+```text
+Проверки, которые у вас УЖЕ ЕСТЬ (3) — прочитаны в ваших файлах, не выдуманы:
+✘  test         npm test   ← package.json
+   не может провалиться: исход погашен прямо в скрипте — «|| true»
+✔  lint         npm run lint   ← package.json
+✘  typecheck    npm run typecheck   ← package.json
+   ничего не доказывает: всё тело скрипта — печать — «echo 'todo: turn this on'»
+
+из них 2 покраснеть не могут. Объявить проверку, которая не может провалиться, — значит
+сделать молчание машинно-читаемым. Сначала почините команду.
+```
+
 `doctor` только читает: ни одного файла не пишет и никуда ничего не отправляет — его можно
 направить на репозиторий, о котором ещё ничего не решено. Ставить ничего не нужно, `npx` скачает
-пакет сам (574.1 kB, замер 2026-09-10 — это число не сторожит никто, так что при случае
-перемерьте).
+пакет сам — **≈0,7 МБ**; это число сверяет машина при каждом прогоне, а не наша память.
+
+Для Claude Code есть плагин — состояние репозитория попадает в контекст агента до его первого
+действия, плюс два умения: «работают ли проверки» и «что чинить по порядку». Ставится из нашей
+же витрины, без ожидания чьего-либо одобрения:
+
+```bash
+/plugin marketplace add arsen-ask-lx/Agent_Quality_Kit
+/plugin install aqk@agent-quality-kit
+```
 
 Единственное исключение, и названо оно здесь именно потому, что единственное: с `--brief`
 (так его запускают хуки) `doctor` спрашивает у реестра npm свою последнюю версию — **не чаще
@@ -109,6 +138,10 @@ aqk context             состояние репозитория одним б
 aqk prompt              одно задание для агента: что починить, по порядку, и у каждого
                         пункта команда, которая докажет «готово»
 aqk vitals              подключено ли то, чем комплект работает: инструменты, хуки, свежесть
+aqk feedback            отзыв автору: отчёт из последнего прогона и пробы плюс готовая
+                        ссылка. Без путей и без кода; ничего не отправляет само
+aqk feedback --send     отправить его одной командой — вашей же учётной записью gh,
+                        комментарием в открытое обсуждение. Без флага не уходит ничего
 aqk doctor --run --brief  одна строка на успехе, весь прогон при провале — для хуков
 aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
                         против ≈500 — плата за то, чтобы агент не догадывался)
@@ -149,7 +182,7 @@ $ npx agent-quality-kit doctor --run # запускает их
         ./src/api/mailer.py:8:    print("sent", to)
   ✘  todo-without-task     код 1
         ./src/web/app.js:1:// TODO: переписать
-  ✔  file-size-limit · entry-links-exist · complexity-limit
+  ✔  file-size-limit · deps-are-pinned · complexity-limit
 ```
 
 Текст отказа написан для агента: в нём сказано, **что именно сделать**. Код возврата — для
@@ -196,6 +229,8 @@ gates:                     # что обязано пройти — команд
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
 covers:                    # что уже держит объявленный гейт — в долг не пишется
   lint: [no-print-in-prod, swallowed-error]
+requires:                  # чем гейт работает, если по команде этого не видно
+  secrets-not-in-code: gitleaks
 samples:  gates            # красный и зелёный образец каждой записи
 ratchets: ratchets         # реестры долга: список может только укорачиваться
 probe: 100                 # раз во столько коммитов проба делается сама; 0 — не делать
@@ -225,6 +260,14 @@ aqk doctor --baseline   # ✔/✘ по пунктам, которые машин
 
 ## Четыре ступени
 
+[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
+
+**Ступень меряет оснащённость, а не качество.** Она говорит, какие сторожа у репозитория есть и
+доказаны на образцах, — но не что код хорош и не что сторожа поймали хоть что-то в **ваших**
+файлах. Для этого есть `probe`, а `doctor` прямо под ступенью печатает, чего она **не**
+доказывает. Значок выше — наш собственный, и его правдивость держит `aqk badge --check` в
+конвейере.
+
 | Уровень | Требуется | Что доказано |
 |---|---|---|
 | **AQK-0** | манифест и точка входа | инструмент знает, что читать |
@@ -355,7 +398,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.14.0
+    rev: v0.16.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -374,7 +417,7 @@ repos:
 [![в GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.14.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.16.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -432,11 +475,34 @@ aqk ratchet no-print-in-prod  # старое — долг, новое не пу
 aqk doctor --run --since main    # только то, что внесла эта ветка
 ```
 
-Три исхода, и все три названы вслух. Находки внутри дифа — красный, как обычно. Находки только
-снаружи — зелёный, с числом того, что скрыто, а не молчаливое «всё чисто». А гейт, в выводе
+Четыре исхода, и все четыре названы вслух. Находки внутри дифа — красный, как обычно. Находки
+только снаружи — зелёный, с числом того, что скрыто, а не молчаливое «всё чисто». Гейт, в выводе
 которого путей нет вовсе (проверка сообщения коммита, проверка конфига конвейера), сузиться
-**не может**: он остаётся красным и говорит почему. Назвать его зелёным потому, что сужать было
-нечего, — ровно та тишина, ради устранения которой этот инструмент и написан.
+**не может**: он остаётся красным и говорит почему. А гейт, который вообще **не смог
+отработать** — нет инструмента, неожиданный код возврата, убит сигналом, — дифом не сужается
+никогда: у сбоя нет места в коде, есть только сам сбой. Назвать любой из двух последних зелёным
+потому, что сужать было нечего, — ровно та тишина, ради устранения которой этот инструмент и
+написан.
+
+### Единственная плата — один ответ
+
+Комплект бесплатный и ничего о вас не собирает: исходящий запрос у него ровно один — спросить
+реестр npm, не вышла ли версия свежее. Плата другая: **один ответ автору**. Поэтому один раз на
+проект — и только когда есть что рассказать — `doctor` или блок для агента печатают строку вроде
+«AQK не смог проверить `smoke`; автору это ценнее всего». Дальше:
+
+```bash
+aqk feedback     # соберёт письмо и даст готовую ссылку — отправляете вы, не мы
+```
+
+В письме: версия, уровень, стек, что покраснело, чего комплект не смог проверить, какие классы
+брака здесь не ловит никто. **Ни путей, ни кода, ни имени репозитория** — вы видите глазами всё,
+что отправляете. Не нужен GitHub — перешлите текст как есть. Не нужно вовсе: `AQK_FEEDBACK=0`.
+
+Где рассказать словами:
+[где комплект соврал](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/90) ·
+[какой проверки не хватает](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/91) ·
+[покажите свой манифест](https://github.com/arsen-ask-lx/Agent_Quality_Kit/discussions/92).
 
 Каждый `doctor --run` перезаписывает `.aqk/last-run.md` — короткий отчёт, что из объявленного
 реально сработало и за сколько. Список гейтов в манифесте молчит о том, сколько из них живы
@@ -569,6 +635,12 @@ aqk blob     # собирает GOD_AI.md из kit/docs — чтобы разо
 Файл **собирается, а не хранится**: править надо оригиналы. Копия, которую правят руками, через
 неделю расходится с источником, и непонятно, какая настоящая.
 
+Один гейт ждут **пять минут**, дальше это «не смогли проверить», а не «чисто». Срок меняется
+переменной `AQK_GATE_TIMEOUT` (в секундах): `AQK_GATE_TIMEOUT=900 aqk doctor --run`. Умолчание
+взято не с потолка — столько же ждёт quality gate у SonarQube. Поля `timeout` у гейта в
+манифесте нет намеренно: его нет ни у pre-commit, ни у lefthook, а долгую проверку честнее
+объявить отдельной командой, чем разрешить ей висеть.
+
 ## Принести свой гейт
 
 Каталог живёт чужими шишками. Порядок и порог — в [`CONTRIBUTING.md`](CONTRIBUTING.md):

package/kit/docs/ai/index.md

@@ -26,6 +26,7 @@
 
 | Документ | О чём | Класс |
 |---|---|---|
+| [`operational-gates.md`](operational-gates.md) | актуальная карта OOM, N+1, Celery, метрик и нагрузки: что закрыто, что только видно и как подключать через AQK без дублей | PORTABLE |
 | [`agent-harness-playbook.md`](agent-harness-playbook.md) | чек-лист «День 0»: конфиги, линтеры, хуки, CI, Docker. Раздел 18 — дисциплина в каждой задаче | PORTABLE |
 | [`project-baseline.md`](project-baseline.md) | что обязано быть на любом проекте, чтобы работу можно было отдать машине. Назначение без названий инструментов | PORTABLE |
 | [`ai-sdlc.md`](ai-sdlc.md) | процесс по этапам: от «зачем» до эксплуатации. Отвечает «в каком порядке», а не «каким инструментом» | CURRENT |