agent-quality-kit 0.7.0 → 0.9.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
@@ -63,6 +69,50 @@ tooling: [the dark factory and the minimum that isn't optional](kit/docs/ai/proj
    a promise without an exit code is just a sentence
 ```
 
+## Every command
+
+```
+aqk doctor              what this repository is at, and what is missing
+aqk doctor --run        run every gate the manifest declares
+aqk doctor --run --since main    only what the diff introduced
+aqk doctor --run --min 1         fail a pipeline below a level
+aqk doctor --baseline   the minimum a project needs, confirmed by a run
+
+aqk init                lay the kit into an existing repository
+aqk start               start a new project from the kit
+aqk add <name>          install one guard from the catalogue
+aqk new <name>          scaffold a guard of your own
+aqk find <text>         find a guard by intent
+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 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
+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
+                        (add --full to install the full block)
+
+aqk learn               rule candidates from local transcripts:
+                        said out loud, never written down
+aqk note "..."          write a bruise into the journal
+aqk ratchet <name>      a debt registry for a declared gate: may only get shorter
+aqk blob                every guide as a single file
+```
+
+Exit codes: `0` pass, `1` below the level or a gate failed. Two exceptions, both deliberate:
+`learn` never fails a build — it reads transcripts and prints to the terminal only, writing
+nothing. And `--baseline` is an inspection, not a run: it always exits `0`, so combining it with
+`--run` or `--min` is refused outright rather than handing you a pipeline that cannot go red.
+
 ## What this looks like
 
 Someone else's project, three files, nothing configured:
@@ -123,9 +173,13 @@ The whole standard is one `.aqk.yml` file in the repository root:
 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
 lessons:  incidents        # where lessons accumulate
@@ -177,6 +231,43 @@ 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.
+
 ## The badge
 
 ```bash
@@ -196,7 +287,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.7.0
+    rev: v0.9.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
@@ -217,7 +308,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.7.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.9.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -229,6 +320,27 @@ 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 build -t aqk .                                   # from this repository
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" aqk doctor
+```
+
+From v0.9.0 the image is pushed to the registry by the same run that publishes the package, so
+there is nothing to build: `ghcr.io/arsen-ask-lx/aqk`. Before that tag the registry holds no
+image, and this says so plainly: a command that points at nothing is worse than no command.
+
+**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
@@ -273,8 +385,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
 
@@ -369,8 +490,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:
@@ -380,7 +506,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
@@ -388,7 +514,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,
@@ -64,6 +71,50 @@ flowchart LR
    обещание без кода возврата — просто предложение
 ```
 
+## Все команды
+
+```
+aqk doctor              где этот репозиторий и чего в нём не хватает
+aqk doctor --run        прогнать все гейты, объявленные в манифесте
+aqk doctor --run --since main    только то, что внёс диф
+aqk doctor --run --min 1         уронить конвейер ниже ступени
+aqk doctor --baseline   обязательный минимум проекта, подтверждённый прогоном
+
+aqk init                разложить комплект в существующий репозиторий
+aqk start               начать новый проект с комплектом
+aqk add <имя>           поставить один гейт из каталога
+aqk new <имя>           завести свой гейт по форме
+aqk find <текст>        найти гейт по намерению
+aqk why <имя>           какой отказ этот гейт поймал
+
+aqk prove               прогнать каждый объявленный гейт по его образцам:
+                        красный на красном, тишина на зелёном
+aqk report              форма отчёта, собранная прогоном
+aqk report --since main  ...и чем доказан этот диф, файл за файлом
+aqk badge               вписать значок уровня в README
+aqk badge --check       упасть, если значок расходится с прогоном
+
+aqk context             состояние репозитория одним блоком, для контекста агента:
+                        уровень, что красное сейчас, правила без арбитра, храповики
+aqk vitals              подключено ли то, чем комплект работает: инструменты, хуки, свежесть
+aqk doctor --run --brief  одна строка на успехе, весь прогон при провале — для хуков
+aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
+                        против ≈375 — плата за то, чтобы агент не догадывался)
+aqk context --install   поставить хук SessionStart в .claude/settings.json
+                        (с --full ставится полный блок)
+
+aqk learn               кандидаты в правила из локальной переписки:
+                        что сказано вслух и не записано
+aqk note "..."          записать шишку в журнал
+aqk ratchet <имя>       реестр долга для объявленного гейта: может только укорачиваться
+aqk blob                все методички одним файлом
+```
+
+Коды возврата: `0` — прошло, `1` — ниже ступени или упал гейт. Два исключения, оба намеренные:
+`learn` не роняет сборку никогда — он читает переписку и печатает только в терминал, не записывая
+ничего. А `--baseline` — осмотр, а не прогон: он выходит с нулём всегда, поэтому вместе с `--run`
+или `--min` он теперь отказывает вслух, а не выдаёт конвейер, который не может покраснеть.
+
 ## Что это выглядит так
 
 Чужой проект, три файла, ничего не настроено:
@@ -124,9 +175,13 @@ Issue» — ничего не постится сама, только текст
 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         # реестры долга: список может только укорачиваться
 lessons:  incidents        # где копятся уроки
@@ -178,6 +233,43 @@ 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`.
+
 ## Значок
 
 ```bash
@@ -198,7 +290,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.6.0
+    rev: v0.9.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -217,7 +309,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.5.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.9.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -229,6 +321,27 @@ repos:
 - run: npx agent-quality-kit doctor --run --min 1
 ```
 
+## Без Node вовсе
+
+Проект на Python, Go или Rust, где Node никто не ставил и не поставит:
+
+```bash
+docker build -t aqk .                                   # из этого репозитория
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" aqk doctor
+```
+
+С версии 0.9.0 образ выкладывается в реестр тем же прогоном, что и пакет, — тогда собирать не
+нужно: `ghcr.io/arsen-ask-lx/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
@@ -236,13 +349,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
@@ -304,22 +459,6 @@ Ruff, ESLint и gitleaks и так находят плохой код — AQK з
 [`agents-lint`](https://github.com/giacomo/agents-lint) делает это лучше, другую — потому что
 91 находка из 120 оказалась законным приёмом.
 
-### Как ввести правило в живой проект
-
-Три способа, и у каждого своя цена. Большая чистка откладывается навсегда, потому что она
-большая. Храповик превращает старые нарушения в долг и блокирует новые — верно, когда правило
-уже принято. А пока о правиле спорят, совещательный гейт показывает находки, не роняя прогон:
-
-```yaml
-advisory:
-  - complexity-limit
-```
-
-Объявлением в манифесте, а не флагом. Флаг «не роняй ничего» понижает все проверки разом, не
-виден в дифе и не назван в итоге — это тот самый `continue-on-error`, который мы сами красим.
-Список печатается **каждый** прогон: совещательный гейт, о котором забыли, — это выключенная
-проверка.
-
 ## Методички одним файлом
 
 ```bash
@@ -347,8 +486,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). Это ровно то, ради чего нужен посторонний, — но это
+один отзыв, а не сложившееся пользование. Пока за инструментом не вернулись второй раз, о
+работоспособности стандарта на чужих проектах говорить рано.
 
 **Стандарт нельзя выпустить первым.** Спецификация раньше практики — это тридцать первый
 заброшенный репозиторий с манифестом и нулём пользователей. Порядок обратный:
@@ -358,7 +502,7 @@ aqk note "гейт краснел на правильном коде"    # за
 | 1 | живём по этому на своих проектах | ⬜ измерено: у трёх своих проектов манифеста нет, уровень не заведён |
 | 2 | `doctor` считает уровень | ✅ сделано |
 | 3 | сложившееся записано как короткая спецификация | ✅ [`SPEC.md`](SPEC.md) |
-| 4 | третий проект — **чужой** | ❌ первый честный сигнал, его ещё нет |
+| 4 | третий проект — **чужой** | 🟡 один посторонний прогон и разбор, 2026-09-08; повторного пользования ещё нет |
 | 5 | значок, сайт, разговор с людьми | ❌ только после четвёртого шага |
 
 ## Очередь работ
@@ -366,7 +510,7 @@ aqk note "гейт краснел на правильном коде"    # за
 Живёт в одном месте — [`PROJECT.md` §9](PROJECT.md). Список здесь не повторяется: два списка через месяц
 расходятся, и непонятно, какой настоящий.
 
-Чего нет: второго пользователя; покрытия команд, которые пишут на диск (проверены прогоном на
-чистой папке, но не по отдельности); третьего — чужого — проекта.
+Чего нет: пользователя, вернувшегося за инструментом второй раз; покрытия команд, которые пишут
+на диск (проверены прогоном на чистой папке, но не по отдельности).
 
 MIT.

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. **Правила живут в репозитории и версионируются** вместе с кодом. Правило в переписке не

package/kit/docs/ready-made-rules.md

@@ -197,6 +197,58 @@ npm install -g agnix && agnix --strict .
 настройкам нашёл шесть таких хуков в четырёх репозиториях — среди них `typecheck && test` перед
 коммитом, не запускавшийся ни разу. Это запись `hook-actually-fires`.
 
+Тот же класс у MCP: объявленный сервер, который не поднимается, агенту не виден никак — у него просто нет этих инструментов. Запись `mcp-server-resolves` ловит две самые частые смерти без запуска: команды по абсолютному пути, которой больше нет, и версии, которая не закреплена и приезжает новая при каждом запуске.
+
+## Поиск на большом репозитории: `tgrep`, и как им пользоваться правильно
+
+Переносимые проверки каталога ищут через `grep`. На проекте до нескольких тысяч файлов это
+десятки миллисекунд, и менять там нечего. **От десятка тысяч файлов картина другая.**
+
+[`tgrep`](https://github.com/microsoft/tgrep) — Microsoft, MIT, Rust: строит триграммный индекс
+и держит фоновый сервер, следящий за изменениями. Замер 2026-09-09 на настоящем проекте, один
+и тот же набор файлов, одна и та же регулярка:
+
+| файлов в проекте | `grep` | `tgrep` |
+|---|---|---|
+| 277 | **6 мс** | индекс строится дольше, чем идёт поиск |
+| 1 737 | **39 мс** | 77 мс |
+| 37 760 | 96 мс | **16 мс**, полнота полная |
+
+Перелом между двумя и десятью тысячами файлов. Их собственные замеры — на 96 000, 388 000 и
+504 000 файлов, где выигрыш доходит до пятидесяти раз; заявка честная и подтверждается.
+
+### Две грабли, на которые мы наступили сами
+
+**Первая: по умолчанию он не видит точечные каталоги.** Индекс строится по видимым файлам, и
+`.claude/`, `.github/`, `.env.example` для него не существуют. На нашем замере это было 32
+найденных файла вместо 55 — и узнали мы это только сверкой со списком `grep`, а не из вывода.
+Лечится флагом **при индексации**, а не при поиске:
+
+```bash
+tgrep index . --hidden     # без --hidden точечные каталоги не попадут в индекс
+tgrep serve .              # демон следит за изменениями
+tgrep "что ищем" .         # мгновенно, полнота как у grep
+```
+
+**Вторая: `--hidden` при ПОИСКЕ отключает индекс.** Это написано в их документации, раздел
+«Flags that bypass the index», и мы это пропустили: первый замер дал «7 секунд, медленнее
+grep» — потому что мерили обход дерева, а не индекс. Флаг ставится один раз, на `index`.
+
+### Почему он не годится арбитром гейта
+
+Проверено опытом: секрет, записанный **после** индексации, при запросе к устаревшему индексу
+не находится, и код возврата — «совпадений нет». Для гейта секретов это молчаливое зелёное на
+самом опасном месте. С работающим `tgrep serve` находится сразу — но тогда условие правильности
+гейта звучит как «на машине поднят фоновый процесс», а гейт обязан быть прав без предварительных
+условий.
+
+Плюс два расхождения, о которых стоит знать: **коды возврата как у ripgrep** (`0` — совпадение
+найдено, у гейтов наоборот) и **файлы больше 64 МиБ пропускаются** по умолчанию.
+
+Вывод простой: **инструмент для человека, а не для ворот.** Ищете руками по большому
+репозиторию — ставьте. Проверяете код перед коммитом — `grep` честнее, потому что не зависит ни
+от чего.
+
 ## А если проект не на Python?
 
 Ничего не меняется. Запись каталога держит **одно намерение и несколько исполнителей**, и
@@ -226,6 +278,57 @@ npm install -g agnix && agnix --strict .
 | подавление проверки без адреса | наш `gate-not-weakened` плюс `eslint-plugin-eslint-comments`, `flake8-noqa` |
 | шаг конвейера, который не может провалиться | наш `ci-actually-fails`; у `checkwash` есть смежный `CI_WORKFLOW_TOUCHED` |
 
+## Три сверки под три предложенные записи — 2026-09-09
+
+Второй пользователь предложил три записи каталога (issue #46). Прежде чем писать код, проверено
+снаружи, есть ли готовое. Ответ вышел **разный по всем трём** — записано здесь, чтобы поиск не
+повторяли.
+
+### Миграция, не попавшая в журнал инструмента
+
+**Похоже, готовое есть, и запись остановлена до замера.**
+
+| Инструмент | Что делает | Закрывает ли класс |
+|---|---|---|
+| `drizzle-kit check` | согласованность истории миграций: коллизии снимков, дубли `idx` в `_journal`, непоследовательные номера | **неизвестно** — про написанный руками `.sql` без записи в журнале в документации не сказано |
+| `alembic check` | сравнивает МОДЕЛИ с миграциями: «есть ли изменения без ревизии» | нет, это другой вопрос |
+
+Замер, который решает: положить руками `migrations/9999_test.sql`, в `_journal.json` не вписывать,
+запустить `npx drizzle-kit check`. Красный — записи не надо вовсе, надо строка «поставь эту
+команду в конвейер». Зелёный — запись законна и сразу с доказательством.
+
+**Это тот случай, ради которого правило и написано:** одна команда решает, будет папка или строка.
+
+### Команда сборки, заглушившая свой отказ
+
+**Готового нет, и это проверено — причём показательно.**
+
+Ближайшее — `shellcheck SC2312`, и оно про другое: маскировку кода возврата в подстановке
+команды. Мало того, что не ловит `>/dev/null 2>&1` у сборки, — в собственном тексте правила
+`|| true` предложен **как способ подавления**:
+
+> Consider invoking this command separately to avoid masking its return value (or use `|| true`
+> to ignore).
+
+Источник: <https://www.shellcheck.net/wiki/SC2312>
+
+То есть общепринятый линтер оболочки считает `|| true` намеренным приёмом — и он прав в своей
+области. Наша запись про **место**: команда, выносящая вердикт, не имеет права молчать о своём
+отказе. `Makefile`, `package.json`, скрипты развёртывания — там `|| true` частый гость, а сторожа
+нет ни одного.
+
+### Починка без арбитра
+
+**Готовое есть, и его обязательно называть.** `danger-js` делает этот класс типовым правилом
+(«app changes without tests»), есть и плагины. Источник: <https://danger.systems/js/>
+
+Отличия настоящие, но их всего два: `danger-js` работает на уровне PR и требует GitHub плюс
+`Dangerfile`. Запись каталога смотрела бы **коммит** и не была бы привязана к площадке —
+прецедент есть, `commit-explains-itself` читает историю, а не дерево файлов.
+
+Это ровно тот случай, когда своя запись законна, но раздел «готовый аналог» обязан назвать
+чужой инструмент и сказать, **почему не он**.
+
 ## Если готового нет
 
 Тогда свой гейт — и в его `README.md` пишется, **что именно проверено**: какой инструмент