agent-quality-kit 0.8.0 → 0.10.0

package/README.md

@@ -22,6 +22,12 @@ npx agent-quality-kit start     # no code yet: day-zero guards, right away
 `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 (230 KB).
 
+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**,
+with a 3-second timeout, silent on any failure, and never affecting the exit code. Turn it off
+with `AQK_UPDATE=0`. There is no auto-update: a tool that silently replaces itself while
+standing on the commit gate is exactly the door this kit teaches you to close.
+
 ### Works with any agent, any language
 
 **Any agent.** Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Aider, OpenCode
@@ -81,6 +87,8 @@ aqk why <name>          what failure this guard was written for
 
 aqk prove               run every declared gate against its own samples:
                         red on the red one, quiet on the green one
+aqk probe               what the declared checks CANNOT see: plant a defect
+                        into files the fix history calls hot
 aqk report              the report form, assembled by a run
 aqk report --since main  ...plus what proves this diff, file by file
 aqk badge               write the level badge into the README
@@ -88,6 +96,8 @@ aqk badge --check       fail if the badge disagrees with a run
 
 aqk context             the repository state in one block, for an agent's context:
                         level, what is red now, rules nobody enforces, ratchets
+aqk vitals              is what the kit runs on wired up: gate tools, hooks, freshness
+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 ~375: the price of an agent that does not guess)
 aqk context --install   put a SessionStart hook into .claude/settings.json
@@ -166,11 +176,15 @@ aqk: 1
 entry:  [AGENTS.md]        # what the agent reads first
 rules:  .aqk/rules         # where the standards live
 docs:   .aqk/docs          # where the guides live (optional; this is the default)
+lang:   en                 # output language for THIS repo, over the machine locale
 gates:                     # what must pass — as commands, not as prose
   lint: "npm run lint"
   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]
 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
 lessons:  incidents        # where lessons accumulate
 ```
 
@@ -220,6 +234,93 @@ A hundred working checks with no manifest is AQK-0, and that is honest: nothing
 aqk doctor --run --min 1   # in CI: fails below AQK-1 OR if any gate failed
 ```
 
+### How a gate is proven — what `prove` actually does
+
+Level AQK-2 and the badge rest on one command, so here it is in full: the first outside user
+tripped over it three times, and all three times this page was to blame.
+
+```bash
+aqk prove
+```
+
+For every gate in `gates:` its samples are taken — `<samples>/<name>/red` and `/green` — and the
+gate is run against each. **The directory is substituted for the LAST word of the command:**
+catalogue recipes are written as `… {dir}`, and on install `{dir}` becomes `.`. Wrappers are
+stripped first: `ratchet.sh` (otherwise the debt registry is rewritten with findings from the
+sample) and `_native.sh` (otherwise the filter hides exactly what the sample must show).
+
+Each entry gets one of three verdicts:
+
+| Verdict | What it means |
+|---|---|
+| **proven** | exit ≠ 0 on `red/` and exit 0 on `green/` |
+| **does not catch** | stayed quiet on the red one, or went red on the green one |
+| **nothing to prove with** | four different reasons, and each is named out loud |
+
+The four reasons: no samples · samples written for another recipe (`samples_for`) while a
+different one is installed · the command does not end in a directory, so it was written by hand
+and there is nowhere to substitute · **the program named in `requires:` is not on the machine.**
+
+That last reason was added 2026-09-09 and deserves a word. A portable recipe is sometimes a
+wrapper around a ready-made tool: the first word of the command is then `bash`, and nothing in it
+shows what is missing. Without the program the wrapper goes red on **both** samples — and `prove`
+declared a working gate broken, taking a level away from a project because somebody else's tool
+was not installed. An accusation instead of a diagnosis; the same class as the Windows paths.
+
+The level is granted when **no provable gate is broken AND at least one is proven**. The second
+condition is not optional: a project where everything is unprovable has proven nothing — that is
+exactly what the forgery with three `true` gates looks like.
+
+### What your checks cannot see — `probe`
+
+`doctor` says "held by a machine 21". **Twenty-one out of what?** There is no denominator: 21 is
+what we happened to write into the catalogue, not what matters in your project. `prove` shows a
+gate catches a defect **on its own** sample. Neither answers the owner's question: what here is
+covered by nothing.
+
+```bash
+aqk probe
+```
+
+Two sources, both facts rather than our taste: **your repository's history** (where defects come
+back — fix commits) and the **red samples of the catalogue** (each one proven by a run). The
+sample is placed in a temporary directory at the hot file's path, and **your declared** gates are
+run against it.
+
+```
+src/mailer.py  fixes in history: 3
+  ✘  keys and passwords do not end up in the code   NOTHING CATCHES IT
+       close it: aqk add secrets-not-in-code
+  ✘  an error is not silently swallowed             NOTHING CATCHES IT
+       close it: aqk add swallowed-error
+  ✔  no "fix later" markers in finished code        caught by: todo-without-task
+```
+
+**Coverage is not declared, it is proven by planting.** This is the kit's own principle turned on
+the whole repository: a check that cannot go red is indistinguishable from an absent one. We
+demand that of every catalogue entry — and until `probe` never demanded it of a project.
+
+The measurement the command grew from, taken on the kit itself: a real source file, a swallowed
+error and a debug print planted into a copy, 21 declared gates. **Red: none.**
+
+Three states, and they do not merge: caught · **nothing catches it** · nothing to check with (the
+gate did not run, or the catalogue has no sample for that extension). The working tree is not
+touched and the exit code is always 0 — this is a look, not a threshold.
+
+**The command does not need to be remembered — that is half the design.** Once every hundred
+commits — or whatever `probe:` in the manifest says, `0` turning it off — `doctor --run` runs the
+probe **itself**, unprompted. A command you have to remember is
+the same class as a file you can fail to read: the agent will not recall it, and the human will
+never learn it exists. The unit is commits, not days: a repository nobody touched for a month
+needs no re-probe, a hundred commits in a day does. Turn it off with `AQK_PROBE=0`.
+
+The result also lands in the state block the agent reads by construction, without knowing the
+command. If no probe has ever run, it says **UNKNOWN** rather than staying silent: silence would
+read as "everything is covered".
+
+Your code is not touched — the sample lives in a temporary directory. The probe's own mark goes
+to `.aqk/last-probe.md`, next to the run report; it is ephemeral, keep it in your `.gitignore`.
+
 ## The badge
 
 ```bash
@@ -239,7 +340,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.8.0
+    rev: v0.10.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
@@ -260,7 +361,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.8.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.10.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -272,6 +373,26 @@ the same thing in a single line:
 - run: npx agent-quality-kit doctor --run --min 1
 ```
 
+## Without Node at all
+
+A Python, Go or Rust project where nobody installed Node and nobody will:
+
+```bash
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/arsen-ask-lx/aqk doctor
+```
+
+The image is pushed to the registry by the same run, from the same tag, that publishes the
+package — there is nothing to build. You can still build it yourself: `docker build -t aqk .`
+from this repository.
+
+**The `--user` flag is not decoration.** Without it the container runs as root and the files
+`init` writes end up owned by root — you cannot edit your own manifest. Measured 2026-09-09:
+`.aqk.yml` and `AGENTS.md` came out `root:root`.
+
+Debian-slim on purpose, not alpine: the gates are `sh`, `grep`, `awk`, `find`, and in alpine
+those are busybox, whose `awk` differs. An image where the gates behave differently from the
+machine the person is on is worse than no image: it hands out a green that means nothing.
+
 ## Installing a gate
 
 ```bash
@@ -316,8 +437,17 @@ advisory:
 
 Declared in the manifest, not passed as a flag. A flag that says "fail nothing" downgrades every
 check at once, is invisible in the diff, and is never named in the summary — that is
-`continue-on-error`, which this tool marks red elsewhere. The list is printed on **every** run:
-an advisory gate everyone forgot about is a switched-off check.
+`continue-on-error`, which this tool marks red elsewhere.
+
+**An advisory gate is marked on EVERY run, including when it is green:**
+
+```
+✔  complexity-limit  (advisory — cannot fail the run)  0.4s · …
+```
+
+Otherwise a gate that cannot fail the build looks exactly like one that can, and you learn what
+is in `advisory:` only on the day it goes red. Red ones are additionally named by name in the
+summary: an advisory gate everyone forgot about is a switched-off check.
 
 ## When a bug slips past the guards
 
@@ -365,10 +495,10 @@ catalogue may grow to hundreds of entries; a given project still sees about a do
 An entry is accepted only if its arbiter goes red on the red sample, stays quiet on the green
 one, and names a real failure it caught. A machine checks this: `bash tool/selfcheck/gates.sh`.
 
-### Four entries that watch the agent, not the code
+### Five entries that watch the agent, not the code
 
 Ruff, ESLint and gitleaks already find bad code, and AQK calls them where it can rather than
-reinventing them. These four look elsewhere — at the moment the **signal** about bad code is
+reinventing them. These five look elsewhere — at the moment the **signal** about bad code is
 switched off, which is what a coding agent does when the task is phrased as "make it pass":
 
 | Entry | What it catches |
@@ -377,8 +507,15 @@ switched off, which is what a coding agent does when the task is phrased as "mak
 | `ci-actually-fails` | a pipeline step that renders a verdict but cannot fail — `run: pytest \|\| true`, `continue-on-error: true` |
 | `test-has-assertion` | a test that cannot fail: empty body, `assert True`, a skip with no reason given |
 | `promise-has-gate` | a rule in `AGENTS.md` with no enforcer named — neither a gate nor, honestly, a human |
+| `protection-not-removed` | **the instrument itself was switched off**: a gate vanished from the manifest. The declared set may only grow; removing one is allowed, but must be named |
 
-Each was measured on nineteen third-party repositories (~25 000 files) before it entered the
+The fifth was added later, and from a bruise of our own. The first four catch the agent switching
+off a **signal**. The master switch — the manifest itself — was guarded by nothing: a measurement
+on 2026-09-09 showed that deleting one line from `.aqk.yml` turns the run green while a real
+secret sits in the code, and neither `doctor`, `report --since`, `vitals` nor the state block the
+agent reads noticed anything.
+
+The first four were measured on nineteen third-party repositories (~25 000 files) before entering the
 catalogue, and two further entries were **cancelled by that measurement**: one because
 [`agents-lint`](https://github.com/giacomo/agents-lint) already does it better, one because
 91 of its 120 findings turned out to be a legitimate pattern.
@@ -412,8 +549,13 @@ scenarios, the success criterion, and what is left.
 
 Version 1, one author. The kit holds **AQK-3** on itself: everything declared is executed by CI
 on every push, two debt registries under a ratchet — `node tool/program.mjs doctor --run --min 1`.
-As long as one person uses it, AQK is a nice acronym in a README. It starts being real when a
-third, foreign project appears.
+
+**The first outside user arrived on 2026-09-08** — ran the kit on their own project (28 gates,
+AQK-1) and sent back a review. That review found two defects ninety-odd checks of our own had
+missed: both live only on Windows, or only on somebody else's directory layout (bruise journal,
+entry of 2026-09-08). That is exactly what an outsider is for — but it is one review, not settled
+use. Until somebody comes back to the tool a second time, the standard is unproven on foreign
+projects.
 
 **A standard cannot be shipped first.** A specification ahead of practice is the thirty-first
 abandoned repository with a manifest and zero users. The order is the other way round:
@@ -423,7 +565,7 @@ abandoned repository with a manifest and zero users. The order is the other way
 | 1 | live by this on our own projects | ⬜ measured: three of our own projects have no manifest |
 | 2 | `doctor` computes the level | ✅ done |
 | 3 | what settled is written up as a short spec | ✅ [`SPEC.md`](SPEC.md) |
-| 4 | a third project — **someone else's** | ❌ the first honest signal, still missing |
+| 4 | a third project — **someone else's** | 🟡 one outside run and review, 2026-09-08; no repeat use yet |
 | 5 | badge, site, talking to people | ❌ only after step four |
 
 ## The work queue
@@ -431,7 +573,7 @@ abandoned repository with a manifest and zero users. The order is the other way
 Lives in one place — [`PROJECT.md` §9](PROJECT.md). It is not repeated here: two lists drift
 apart within a month, and then nobody knows which is real.
 
-What is missing: a second user; per-command coverage of the commands that write to disk (they are
-exercised by a clean-folder run, but not individually); a third — foreign — project.
+What is missing: a user who came back a second time; per-command coverage of the commands that
+write to disk (they are exercised by a clean-folder run, but not individually).
 
 MIT.

package/README.ru.md

@@ -23,6 +23,13 @@ npx agent-quality-kit start     # кода ещё нет: сторожа дня
 направить на репозиторий, о котором ещё ничего не решено. Ставить ничего не нужно, `npx` скачает
 пакет сам (230 КБ).
 
+Единственное исключение, и названо оно здесь именно потому, что единственное: с `--brief`
+(так его запускают хуки) `doctor` спрашивает у реестра npm свою последнюю версию — **не чаще
+раза в сутки и никогда в конвейере**, с таймаутом в три секунды, молча при любой ошибке и
+не влияя на код возврата. Выключается `AQK_UPDATE=0`. Автообновления нет: инструмент,
+который молча подменяет себя, стоя на воротах коммита, — ровно та дверь, которую комплект
+учит закрывать.
+
 ### Работает с любым агентом и любым языком
 
 **Любой агент.** Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Aider,
@@ -82,6 +89,8 @@ aqk why <имя>           какой отказ этот гейт поймал
 
 aqk prove               прогнать каждый объявленный гейт по его образцам:
                         красный на красном, тишина на зелёном
+aqk probe               чего объявленные проверки НЕ видят: подсадка брака
+                        в файлы, горячие по истории починок
 aqk report              форма отчёта, собранная прогоном
 aqk report --since main  ...и чем доказан этот диф, файл за файлом
 aqk badge               вписать значок уровня в README
@@ -89,6 +98,8 @@ aqk badge --check       упасть, если значок расходится
 
 aqk context             состояние репозитория одним блоком, для контекста агента:
                         уровень, что красное сейчас, правила без арбитра, храповики
+aqk vitals              подключено ли то, чем комплект работает: инструменты, хуки, свежесть
+aqk doctor --run --brief  одна строка на успехе, весь прогон при провале — для хуков
 aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
                         против ≈375 — плата за то, чтобы агент не догадывался)
 aqk context --install   поставить хук SessionStart в .claude/settings.json
@@ -167,11 +178,15 @@ aqk: 1
 entry:  [AGENTS.md]        # что агент читает первым
 rules:  .aqk/rules         # где стандарты
 docs:   .aqk/docs          # где методички (необязательно, это и есть умолчание)
+lang:   ru                 # язык вывода для ЭТОГО репозитория, поверх локали машины
 gates:                     # что обязано пройти — командами, не словами
   lint: "npm run lint"
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
+covers:                    # что уже держит объявленный гейт — в долг не пишется
+  lint: [no-print-in-prod, swallowed-error]
 samples:  gates            # красный и зелёный образец каждой записи
 ratchets: ratchets         # реестры долга: список может только укорачиваться
+probe: 100                 # раз во столько коммитов проба делается сама; 0 — не делать
 lessons:  incidents        # где копятся уроки
 ```
 
@@ -221,6 +236,93 @@ flowchart LR
 aqk doctor --run --min 1   # в конвейере: ошибка, если ниже AQK-1 ИЛИ упал хоть один гейт
 ```
 
+### Как гейт доказывается — устройство `prove`
+
+Ступень AQK-2 и значок держатся на одной команде, поэтому она описана здесь целиком: первый
+чужой пользователь споткнулся об неё трижды, и все три раза виновата была эта страница.
+
+```bash
+aqk prove
+```
+
+Для каждого гейта из `gates:` берутся его образцы — `<samples>/<имя>/red` и `/green` — и гейт
+запускается по каждому. **Каталог подставляется на место ПОСЛЕДНЕГО слова команды:** рецепты
+каталога пишутся как `… {dir}`, и при установке `{dir}` превращается в `.`. Обёртки снимаются
+заранее: `ratchet.sh` (иначе реестр долга перепишется находками из образца) и `_native.sh`
+(иначе фильтр спрячет ровно то, что образец обязан показать).
+
+Вердикт у каждой записи один из трёх:
+
+| Вердикт | Что значит |
+|---|---|
+| **доказан** | код ≠ 0 на `red/` и код 0 на `green/` |
+| **не ловит** | промолчал на красном, либо покраснел на зелёном |
+| **доказывать нечем** | и вот здесь четыре разные причины, и они называются вслух |
+
+Причин «доказывать нечем» четыре: образцов нет · образцы написаны под другой рецепт
+(`samples_for`), а в проекте стоит не он · команда не кончается каталогом — значит написана
+руками, и подставлять некуда · **программы, названной в `requires:`, нет на машине.**
+
+Последняя причина заведена 2026-09-09 и стоит отдельного слова. Переносимый рецепт бывает
+обёрткой вокруг готового инструмента: первое слово команды тогда `bash`, и по нему не видно,
+чего не хватает. Без программы обёртка краснеет на **обоих** образцах — и `prove` объявлял
+исправный гейт сломанным, отбирая у проекта ступень за то, что на машине нет чужого
+инструмента. Обвинение вместо диагноза; ровно тот же класс, что windows-пути.
+
+Ступень берётся, когда **ни один доказуемый гейт не сломан И доказан хотя бы один**. Второе
+условие обязательно: проект, у которого все гейты недоказуемы, не доказал ничего — именно так
+выглядит подделка с тремя гейтами `true`.
+
+### Чего ваши проверки не видят — `probe`
+
+`doctor` говорит «держит машина 21». **Двадцать один из чего?** Знаменателя нет: 21 — это то,
+что мы успели написать в каталог, а не то, что важно в вашем проекте. `prove` доказывает, что
+гейт ловит брак **на своём** образце. Ни один из них не отвечает на вопрос владельца: что здесь
+не прикрыто ничем.
+
+```bash
+aqk probe
+```
+
+Два источника, и оба — факты, а не наш вкус: **история вашего репозитория** (где брак
+возвращается — коммиты-починки) и **красные образцы каталога** (каждый доказан прогоном).
+Образец кладётся во временный каталог по пути горячего файла, и по нему прогоняются
+**объявленные вами** гейты.
+
+```
+src/mailer.py  починок в истории: 3
+  ✘  ключи и пароли не попадают в код              НЕ ЛОВИТ НИКТО
+       закрыть: aqk add secrets-not-in-code
+  ✘  ошибка не глушится молча                      НЕ ЛОВИТ НИКТО
+       закрыть: aqk add swallowed-error
+  ✔  маркеров «доделать потом» нет в готовом коде   ловит: todo-without-task
+```
+
+**Покрытие не заявлено, а доказано подсадкой.** Это наш собственный принцип, наведённый на весь
+репозиторий: проверка, которая не может покраснеть, неотличима от отсутствующей. Мы требуем
+этого от каждой записи каталога — и до `probe` ни разу не потребовали от проекта целиком.
+
+Замер, с которого команда началась, — на самом комплекте: настоящий файл, подсаженные
+проглоченная ошибка и отладочная печать, 21 объявленный гейт. **Покраснело: ноль.**
+
+Три состояния, и они не сливаются: ловит · **не ловит никто** · нечем проверить (гейт не
+состоялся, или в каталоге нет образца под это расширение). Рабочее дерево не трогается, код
+возврата всегда 0 — это осмотр, а не порог.
+
+**Команду не нужно помнить — и это половина замысла.** Раз в сто коммитов (`probe:` в манифесте — своё число, `0` — не делать) `doctor --run`
+запускает пробу **сам**, без напоминания. Команда, о которой надо вспомнить, — тот же класс,
+что файл, который можно не прочитать: агент не вспомнит, а человек не узнает, что она есть.
+Единица — коммиты, а не сутки: репозиторий, в котором месяц не работали, перепроверять незачем,
+а сто коммитов за день — надо. Выключается `AQK_PROBE=0`.
+
+Результат попадает и в блок состояния для агента: он читает его по построению, не зная про
+команду. Пробы не было — там сказано **НЕИЗВЕСТНО**, а не пропущено: молчание прочиталось бы
+как «всё прикрыто».
+
+Ваш код проба не трогает: образец живёт во временном каталоге. Своя отметка ложится в
+`.aqk/last-probe.md` — там же, где отчёт прогона; файл эфемерный, в `.gitignore` его стоит
+держать самому.
+
 ## Значок
 
 ```bash
@@ -241,7 +343,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.8.0
+    rev: v0.10.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -260,7 +362,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.8.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.10.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -272,6 +374,25 @@ repos:
 - run: npx agent-quality-kit doctor --run --min 1
 ```
 
+## Без Node вовсе
+
+Проект на Python, Go или Rust, где Node никто не ставил и не поставит:
+
+```bash
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/arsen-ask-lx/aqk doctor
+```
+
+Образ выкладывается в реестр тем же прогоном и из того же тега, что и пакет, — собирать ничего
+не нужно. Собрать у себя тоже можно: `docker build -t aqk .` из этого репозитория.
+
+**Ключ `--user` не украшение.** Без него контейнер работает от root, и файлы, которые пишет
+`init`, достаются root — человек не может править собственный манифест. Проверено 2026-09-09:
+`.aqk.yml` и `AGENTS.md` вышли с владельцем `root:root`.
+
+Образ на debian-slim намеренно, а не на alpine: гейты — это `sh`, `grep`, `awk`, `find`, а в
+alpine это busybox, и его `awk` другой. Образ, в котором гейты ведут себя не так, как на машине
+человека, хуже отсутствия образа: он даёт зелёное, которое ничего не значит.
+
 ## Поставить гейт
 
 ```bash
@@ -279,13 +400,55 @@ aqk find "печать в проде"     # есть ли уже такой ге
 aqk doctor                    # что применимо к этому репозиторию и чего нет
 aqk add secrets-not-in-code   # копирует проверку и образцы в проект, объявляет в манифесте
 aqk doctor --run              # запускает объявленные гейты и показывает результат
+aqk doctor --run --since main  # ...но только то, что внёс диф
 aqk ratchet no-print-in-prod  # старое — долг, новое не пускать
 ```
 
+### Первый прогон на настоящем проекте
+
+У сложившегося репозитория за плечами годы долга. Прогони все гейты по всему коду — получишь
+стену красного, которую никто не читает, и инструмент выключат. `--since <ref>` сужает вывод до
+файлов, которых коснулся диф:
+
+```bash
+aqk doctor --run --since main    # только то, что внесла эта ветка
+```
+
+Три исхода, и все три названы вслух. Находки внутри дифа — красный, как обычно. Находки только
+снаружи — зелёный, с числом того, что скрыто, а не молчаливое «всё чисто». А гейт, в выводе
+которого путей нет вовсе (проверка сообщения коммита, проверка конфига конвейера), сузиться
+**не может**: он остаётся красным и говорит почему. Назвать его зелёным потому, что сужать было
+нечего, — ровно та тишина, ради устранения которой этот инструмент и написан.
+
 Каждый `doctor --run` перезаписывает `.aqk/last-run.md` — короткий отчёт, что из объявленного
 реально сработало и за сколько. Список гейтов в манифесте молчит о том, сколько из них живы
 именно сейчас; отчёт — нет. Файл эфемерный, в `.gitignore` его стоит держать самому.
 
+### Как ввести правило в живой проект
+
+Три способа, и у каждого своя цена. Большая чистка откладывается навсегда, потому что она
+большая. Храповик превращает старые нарушения в долг и блокирует новые — верно, когда правило
+уже принято. А пока о правиле спорят, совещательный гейт показывает находки, не роняя прогон:
+
+```yaml
+advisory:
+  - complexity-limit
+```
+
+Объявлением в манифесте, а не флагом. Флаг «не роняй ничего» понижает все проверки разом, не
+виден в дифе и не назван в итоге — это тот самый `continue-on-error`, который мы сами красим.
+
+**Совещательный помечается в КАЖДОМ прогоне, в том числе когда он зелёный:**
+
+```
+✔  complexity-limit  (совещательный — уронить прогон не может)  0.4s · …
+```
+
+Иначе гейт, который уронить сборку не может, по выводу неотличим от того, который может, и о
+списке `advisory:` человек узнаёт только в день, когда гейт покраснел. Покрасневшие вдобавок
+названы в сводке поимённо: совещательный гейт, о котором забыли, — это выключенная проверка.
+
+
 ## Поймал ошибку, которую не поймал сторож
 
 ```bash
@@ -329,10 +492,10 @@ vendor/
 Запись принимается, только если её арбитр краснеет на красном образце, молчит на зелёном и
 назван реальный отказ, который она поймала. Проверяет это машина: `bash tool/selfcheck/gates.sh`.
 
-### Четыре записи, которые смотрят на агента, а не на код
+### Пять записей, которые смотрят на агента, а не на код
 
 Ruff, ESLint и gitleaks и так находят плохой код — AQK зовёт их, где может, вместо того чтобы
-писать своё. Эти четыре смотрят в другое место: на момент, когда **сигнал** о плохом коде
+писать своё. Эти пять смотрят в другое место: на момент, когда **сигнал** о плохом коде
 выключают. Именно это делает агент, когда задача сформулирована как «сделай, чтобы прошло»:
 
 | Запись | Что ловит |
@@ -341,28 +504,18 @@ Ruff, ESLint и gitleaks и так находят плохой код — AQK з
 | `ci-actually-fails` | шаг конвейера, который выносит вердикт, но не может провалиться — `run: pytest \|\| true`, `continue-on-error: true` |
 | `test-has-assertion` | тест, который не может провалиться: пустое тело, `assert True`, пропуск без причины |
 | `promise-has-gate` | правило в `AGENTS.md`, у которого не назван сторож — ни гейт, ни, честно, человек |
+| `protection-not-removed` | **сам прибор выключили**: гейт исчез из манифеста. Набор объявленной защиты может только расти; снять можно, но названно |
 
-Каждая измерена на девятнадцати чужих репозиториях (~25 000 файлов) до внесения в каталог, и ещё
-две записи этот же замер **отменил**: одну — потому что
+Пятая заведена позже остальных и по собственной шишке. Четыре первых ловят агента, когда он
+выключает **сигнал**. А главный рубильник — сам манифест — не сторожил никто: замер 2026-09-09
+показал, что удаление одной строки из `.aqk.yml` даёт зелёный прогон при секрете в коде, и этого
+не заметили ни `doctor`, ни `report`, ни `vitals`, ни блок состояния для агента.
+
+Первые четыре измерены на девятнадцати чужих репозиториях (~25 000 файлов) до внесения в каталог,
+и ещё две записи этот же замер **отменил**: одну — потому что
 [`agents-lint`](https://github.com/giacomo/agents-lint) делает это лучше, другую — потому что
 91 находка из 120 оказалась законным приёмом.
 
-### Как ввести правило в живой проект
-
-Три способа, и у каждого своя цена. Большая чистка откладывается навсегда, потому что она
-большая. Храповик превращает старые нарушения в долг и блокирует новые — верно, когда правило
-уже принято. А пока о правиле спорят, совещательный гейт показывает находки, не роняя прогон:
-
-```yaml
-advisory:
-  - complexity-limit
-```
-
-Объявлением в манифесте, а не флагом. Флаг «не роняй ничего» понижает все проверки разом, не
-виден в дифе и не назван в итоге — это тот самый `continue-on-error`, который мы сами красим.
-Список печатается **каждый** прогон: совещательный гейт, о котором забыли, — это выключенная
-проверка.
-
 ## Методички одним файлом
 
 ```bash
@@ -390,8 +543,13 @@ aqk note "гейт краснел на правильном коде"    # за
 
 Версия 1, один автор. Сам комплект держит **AQK-3**: всё объявленное прогоняется конвейером при
 каждом пуше, два реестра долга под храповиком — `node tool/program.mjs doctor --run --min 1`.
-Пока комплектом пользуется один человек, AQK — красивое слово в README. Он начнёт работать,
-когда появится чужой третий проект.
+
+**Первый посторонний пользователь появился 2026-09-08** — прогнал комплект на своём проекте
+(28 гейтов, AQK-1) и прислал разбор. Он же нашёл два дефекта, которых не видели девяносто с
+лишним наших собственных проверок: оба живут только на Windows или только на чужой раскладке
+каталогов (журнал, запись от 2026-09-08). Это ровно то, ради чего нужен посторонний, — но это
+один отзыв, а не сложившееся пользование. Пока за инструментом не вернулись второй раз, о
+работоспособности стандарта на чужих проектах говорить рано.
 
 **Стандарт нельзя выпустить первым.** Спецификация раньше практики — это тридцать первый
 заброшенный репозиторий с манифестом и нулём пользователей. Порядок обратный:
@@ -401,7 +559,7 @@ aqk note "гейт краснел на правильном коде"    # за
 | 1 | живём по этому на своих проектах | ⬜ измерено: у трёх своих проектов манифеста нет, уровень не заведён |
 | 2 | `doctor` считает уровень | ✅ сделано |
 | 3 | сложившееся записано как короткая спецификация | ✅ [`SPEC.md`](SPEC.md) |
-| 4 | третий проект — **чужой** | ❌ первый честный сигнал, его ещё нет |
+| 4 | третий проект — **чужой** | 🟡 один посторонний прогон и разбор, 2026-09-08; повторного пользования ещё нет |
 | 5 | значок, сайт, разговор с людьми | ❌ только после четвёртого шага |
 
 ## Очередь работ
@@ -409,7 +567,7 @@ aqk note "гейт краснел на правильном коде"    # за
 Живёт в одном месте — [`PROJECT.md` §9](PROJECT.md). Список здесь не повторяется: два списка через месяц
 расходятся, и непонятно, какой настоящий.
 
-Чего нет: второго пользователя; покрытия команд, которые пишут на диск (проверены прогоном на
-чистой папке, но не по отдельности); третьего — чужого — проекта.
+Чего нет: пользователя, вернувшегося за инструментом второй раз; покрытия команд, которые пишут
+на диск (проверены прогоном на чистой папке, но не по отдельности).
 
 MIT.

package/kit/docs/ai/index.md

@@ -19,6 +19,7 @@
 | хотите понять, **как работать каждый день** | [Плейбук харнеса](agent-harness-playbook.md), раздел 18 |
 | хотите увидеть **процесс по этапам** | [SDLC эпохи агентов](ai-sdlc.md) |
 | ищете **готовое правило**, прежде чем писать своё | [Готовые правила](../ready-made-rules.md) |
+| делаете **e2e для API** и хотите, чтобы он что-то доказывал | [Контракт API и e2e](../api-e2e.md) |
 | ставите **гейты** и хотите отличить работающий от мёртвого | `kit/gates/README.md` — норма записи, храповик, четыре способа вранья |
 
 ## 1. Наше — применяется в работе

package/kit/docs/ai/project-baseline.md

@@ -189,6 +189,20 @@ tags:
 40. **У агента есть способ проверить себя**: запустить тесты, поднять приложение, прочитать логи,
     посмотреть метрики. Без этого он вынужден заканчивать словами «готово», и это слово ничего не
     стоит.
+
+    **Если у проекта есть интерфейс — сюда же браузер.** Агент, который не может открыть страницу,
+    судит о своей работе по тому, что собралось; «собралось» и «работает» — разные утверждения,
+    и первое он выдаёт за второе не по злому умыслу, а потому что другого у него нет. Подключается
+    MCP-сервером, и это межвендорный протокол: одинаково работает с Claude Code, Cursor, Codex.
+    Два первых лица, оба проверены по реестру npm 2026-09-08:
+    [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) от Google —
+    Lighthouse, трассировка производительности, сеть, консоль, память;
+    [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) от Microsoft — прогон
+    сценариев в трёх движках. Задачи разные, выбирает человек.
+
+    **Версию закрепить.** Сервер запускается командой вида `npx -y пакет@1.9.0`; без точной
+    версии при каждом запуске приезжает новая — а этому серверу отдан браузер со всем, что в нём
+    открыто. Это проверяет запись `mcp-server-resolves`.
 41. **Сообщение об ошибке — это подсказка агенту.** Инструкция в тексте отказа стоит дешевле, чем
     любые объяснения в документации: она приходит ровно в тот момент, когда нужна.
 42. **Правила живут в репозитории и версионируются** вместе с кодом. Правило в переписке не