agent-quality-kit 0.13.0 → 0.15.0

package/README.md

@@ -104,15 +104,20 @@ 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,
                         the next three steps with commands, and when to run what
+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 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)
 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 learn               rule candidates from local transcripts: said out loud, never
+                        written down — and what you had to repeat ("I told you",
+                        "again"), first of all a written rule the agent still breaks
 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
@@ -184,7 +189,7 @@ 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
+lang:   en                 # output language; without it — the language of AGENTS.md/README
 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 ."
@@ -348,7 +353,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.13.0
+    rev: v0.15.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
@@ -369,7 +374,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.13.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.15.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -381,6 +386,12 @@ the same thing in a single line:
 - run: npx agent-quality-kit doctor --run --min 1
 ```
 
+**Findings show up in the pull request itself.** Inside GitHub Actions a failed gate's finding
+that names a file — `src/a.py:12: …` — becomes a red annotation on that line of the diff, with the
+gate's "fix:" advice attached; an advisory gate gives a yellow one. At most ten of each per run
+(the limit GitHub is reported to take per step); the rest are counted in the log. The verdict
+does not change — annotations print what the run already decided.
+
 ## Without Node at all
 
 A Python, Go or Rust project where nobody installed Node and nobody will:
@@ -422,12 +433,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`.
@@ -478,6 +511,11 @@ purpose: two gates writing into the same folder (`npm run build` twice into `dis
 at random when run together, and a flaky red is worse than a slow one. Output keeps the declared
 order. On this repository, 30 gates: about 110 s one by one, 68 s with `--jobs 3`.
 
+**Output is short by default.** A passed gate, an entry the machine already holds and an entry that
+does not apply fold into one counted line each; a failed gate, an advisory one, advice and "what to
+add" always print in full. `aqk doctor --verbose` lists everything by name; in a pipeline whose log
+is read later, set `AQK_VERBOSE=1`.
+
 ## When a bug slips past the guards
 
 ```bash

package/README.ru.md

@@ -106,15 +106,21 @@ aqk badge --check       упасть, если значок расходится
 aqk context             состояние репозитория одним блоком, для контекста агента:
                         уровень, что красное сейчас, правила без арбитра, храповики,
                         три следующих шага с командами и когда что запускать
+aqk prompt              одно задание для агента: что починить, по порядку, и у каждого
+                        пункта команда, которая докажет «готово»
 aqk vitals              подключено ли то, чем комплект работает: инструменты, хуки, свежесть
+aqk feedback            отзыв автору: отчёт из последнего прогона и пробы плюс готовая
+                        ссылка. Без путей и без кода; ничего не отправляет само
 aqk doctor --run --brief  одна строка на успехе, весь прогон при провале — для хуков
 aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
                         против ≈500 — плата за то, чтобы агент не догадывался)
 aqk context --install   поставить хук SessionStart в .claude/settings.json
                         (с --full ставится полный блок)
 
-aqk learn               кандидаты в правила из локальной переписки:
-                        что сказано вслух и не записано
+aqk learn               кандидаты в правила из локальной переписки: что сказано
+                        вслух и не записано — и что пришлось повторять («я же
+                        говорил», «опять»), прежде всего записанное правило,
+                        которое агент всё равно нарушает
 aqk note "..."          записать шишку в журнал
 aqk ratchet <имя>       реестр долга для объявленного гейта: может только укорачиваться
 aqk blob                все методички одним файлом
@@ -186,7 +192,7 @@ aqk: 1
 entry:  [AGENTS.md]        # что агент читает первым
 rules:  .aqk/rules         # где стандарты
 docs:   .aqk/docs          # где методички (необязательно, это и есть умолчание)
-lang:   ru                 # язык вывода для ЭТОГО репозитория, поверх локали машины
+lang:   ru                 # язык вывода; без поля — язык AGENTS.md/README, потом локаль
 gates:                     # что обязано пройти — командами, не словами
   lint: "npm run lint"
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
@@ -351,7 +357,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.13.0
+    rev: v0.15.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -370,7 +376,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.13.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.15.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -382,6 +388,12 @@ repos:
 - run: npx agent-quality-kit doctor --run --min 1
 ```
 
+**Находки видны прямо в pull request.** В GitHub Actions находка упавшего гейта, которая называет
+файл, — `src/a.py:12: …` — становится красной пометкой у этой строки дифа, вместе с советом
+«почини» того же гейта; совещательный гейт даёт жёлтую. Не больше десяти каждого вида за прогон
+(столько GitHub, по имеющимся данным, принимает за шаг), остальное — числом в логе. Вердикт от
+пометок не меняется: они печатают то, что прогон уже решил.
+
 ## Без Node вовсе
 
 Проект на Python, Go или Rust, где Node никто не ставил и не поставит:
@@ -422,11 +434,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` — короткий отчёт, что из объявленного
 реально сработало и за сколько. Список гейтов в манифесте молчит о том, сколько из них живы
@@ -477,6 +512,11 @@ aqk doctor --run --only stack     # только стенд, на стенде
 падали бы через раз, а плавающее красное хуже медленного. Вывод — в порядке объявления. На этом
 репозитории, 30 гейтов: около 110 с по одному, 68 с с `--jobs 3`.
 
+**Вывод короткий по умолчанию.** Прошедший гейт, запись, которую уже держит машина, и
+неприменимая запись сворачиваются в одну строку со счётом; упавший гейт, совещательный, совет и
+«что поставить» печатаются всегда. `aqk doctor --verbose` — всё поимённо; в конвейере, где лог
+читают потом, — `AQK_VERBOSE=1`.
+
 
 ## Поймал ошибку, которую не поймал сторож
 

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

@@ -16,7 +16,7 @@
 
 Отсюда обе красные ветки. Замер целиком — `incidents/README.md`, 2026-09-09.
 
-**Что именно проверяется.** Записи две, и вторая тоньше первой.
+**Что именно проверяется.** Записи три; вторая тоньше первой, третья — тот же договор без файла.
 
 1. **Спецификацию не держит ни одна команда.** Файл `openapi*.{yaml,yml,json}` (и `swagger*`,
    `asyncapi*`) в репозитории есть, а ни в конвейере, ни в сборочных файлах, ни в скриптах, ни
@@ -24,6 +24,14 @@
 2. **Арбитр сужен до «не пятисотка».** `schemathesis --checks not_a_server_error` (или `-c`).
    У `schemathesis` по умолчанию включены **все** проверки, включая
    `response_schema_conformance`; сужение до одной — не настройка, а отключение.
+3. **Договор в коде, а проверку типов не запускает никто.** В `package.json` стоит `@trpc/server`,
+   `@ts-rest/core`, `@hono/zod-openapi` или провайдер типов Fastify (`@fastify/type-provider-*`,
+   `fastify-type-provider-zod`), а `tsc`, `vue-tsc` или `tsgo` не зовёт ни одна команда. У такого
+   договора арбитр — типы: разошлись сервер и клиент, краснеет сборка типов. Отзыв с живого
+   проекта 2026-09-11: схемы zod в общем пакете, сервер на `@fastify/type-provider-zod` — а
+   запись писала «спецификации не видно». Один `zod` договором не считается: им разбирают и
+   формы, и конфиги. Файлы блокировки (`package-lock.json`) запуском не считаются — там
+   `"bin": { "tsc": … }` у любого проекта на TypeScript.
 
 Четыре семьи держателей отвечают на **разные** вопросы, и подменять один другим нельзя:
 
@@ -61,3 +69,10 @@
   запись. Красным сделано только то, у чего законного применения нет.
 - **Что спецификация вообще описывает этот сервер.** Файл может описывать чужой API; сверять
   их машина не умеет.
+- **Что договор в коде проверяется ВО ВРЕМЯ РАБОТЫ.** Типы сходятся — а ответ сервер отдаёт
+  непроверенным: у tRPC без `.output()`, у ts-rest без `responseValidation` на сервере, у Fastify без
+  сериализатора схемы ответа. Это расхождение `tsc` не видит по построению: типы описывают
+  намерение, а не то, что ушло по сети. Сверять настройку каждой библиотеки — десять правил
+  ради одной записи; запись держит то, что одинаково у всех: проверку типов кто-то запускает.
+- **Договор в коде у других библиотек.** `zod` плюс рукописный клиент, GraphQL-схема в коде,
+  gRPC — не опознаются. Список взят с живого проекта и с реестра npm, а не для полноты.

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

@@ -40,23 +40,36 @@ SPECS=$(find "$DIR" $(skip_find) -type f \
   -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 '^$')
+# ДОГОВОР В КОДЕ — тот же договор без файла. Отзыв с живого проекта 2026-09-11: схемы zod
+# запросов и ответов в общем пакете, сервер на `@fastify/type-provider-zod` — а проверка писала
+# «спецификации нет», потому что знала только имя `openapi*`. Опознаём по зависимости в
+# `package.json`: tRPC, ts-rest, Hono с zod-openapi, провайдеры типов Fastify (официальные
+# `@fastify/type-provider-*` и `fastify-type-provider-zod`). Один `zod` — НЕ договор: им
+# разбирают формы и конфиги. Имена сверены с реестром npm 2026-09-11, а не по памяти: по
+# памяти был назван `fastify-type-provider-zod`, а на живом проекте стоял `@fastify/...`.
+CODE_DEPS='@trpc/server|@ts-rest/core|@hono/zod-openapi|@fastify/type-provider-[a-z0-9-]+|fastify-type-provider-zod'
+CODE=$(find "$DIR" $(skip_find) -type f -name package.json -print 2>/dev/null \
+  | own_samples_filter "$DIR" | grep -v '^$' \
+  | while IFS= read -r F; do grep -qE "\"($CODE_DEPS)\"[[:space:]]*:" "$F" && printf '%s\n' "$F"; done)
+
+[ -z "$SPECS$CODE" ] && {
+  echo "договора API здесь нет — ни файла OpenAPI, ни tRPC, ts-rest или провайдера типов"
+  echo "Fastify; эта проверка не про тебя"
+  exit 0
+}
+
+# Где искать запуск: конвейер, оболочечные скрипты, сборочные файлы, объявления пакета и
+# манифест самого комплекта. Не в коде: упоминание инструмента в исходнике — не его запуск.
+# Файлы блокировки — не запуск тоже: `package-lock.json` держит `"bin": { "tsc": … }` у
+# каждого проекта на TypeScript, и без исключения арбитр находился бы всегда.
+run_grep() {
+  grep -rnE "$1" $(skip_grep) --exclude=package-lock.json --exclude=npm-shrinkwrap.json \
+    --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 '^$' | drop_definitions
+}
 
 # ОПРЕДЕЛЕНИЕ ЗАПИСИ КАТАЛОГА — НЕ НАХОДКА, и это касается не только своей записи. Соседняя
 # запись `ci-actually-fails` держит в своём `check.sh` строку со списком запускалок, где
@@ -66,12 +79,42 @@ FOUND=$(grep -rnE "$HOLDERS" $(skip_grep) \
 # Найдено аудитом фич 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 '^$')
+drop_definitions() {
+  while IFS= read -r L; do
+    F="${L%%:*}"
+    [ -n "$F" ] || continue
+    [ -f "$(dirname "$F")/gate.yml" ] && continue
+    printf '%s\n' "$L"
+  done | grep -v '^$'
+}
+
+# Арбитр договора в коде — проверка типов: разошлись сервер и клиент, `tsc` краснеет. Слово
+# целиком: `tsc-alias` и `typescript` запуском проверки типов не являются.
+RC=0
+if [ -n "$CODE" ]; then
+  TYPED=$(run_grep '(^|[^a-zA-Z0-9_-])(vue-tsc|tsc|tsgo)([[:space:]]|"|$)')
+  if [ -z "$TYPED" ]; then
+    printf '%s\n' "$CODE" | while IFS= read -r F; do
+      D=$(grep -oE "\"($CODE_DEPS)\"" "$F" | head -1 | tr -d '"')
+      echo "$F: договор API в коде ($D) — проверку типов не запускает ни одна команда"
+    done
+    echo "  почини: заведи «tsc --noEmit» (или «tsc --build») в конвейере или в гейтах"
+    echo "  манифеста. Договор в коде держат типы: разошлись сервер и клиент — краснеет сборка"
+    echo "  типов. Никто её не запускает — договор расходится молча, как файл OpenAPI без сверки."
+    RC=1
+  fi
+fi
+[ -z "$SPECS" ] && exit "$RC"
+
+# --- кто её держит ------------------------------------------------------------
+# Четыре семьи держателей, и они отвечают на РАЗНЫЕ вопросы — подробности в 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=$(run_grep "$HOLDERS")
 
 if [ -z "$FOUND" ]; then
   printf '%s\n' "$SPECS" | sed 's/$/: спецификацию не держит ни одна команда/'
@@ -121,4 +164,4 @@ if [ -n "$NARROW$LOUD" ]; then
   echo "  провал, погашенный «|| true» или «continue-on-error», — это ci-actually-fails."
   exit 1
 fi
-exit 0
+exit "$RC"

package/kit/gates/entry-commands-exist/README.md

@@ -0,0 +1,64 @@
+# Команды из свода существуют
+
+**Намерение.** Агент берёт команды из свода дословно. Свод, который велит `npm run lint:cli`,
+когда такого скрипта нет, отправляет агента в «Missing script» — и дальше тот либо чинит не то,
+либо докладывает «проверил» про проверку, которой нет. Соседняя запись `entry-links-exist` ловит
+в своде несуществующие ФАЙЛЫ; эта — КОМАНДЫ.
+
+**Какой отказ это поймало.** Выборка 2026-09-11: 99 публичных репозиториев с `AGENTS.md`, где
+упомянут `npm run`. В 9 свод называет скрипт, которого нет ни в одном `package.json`
+репозитория. В двух история показывает механизм:
+
+| Репозиторий | Что было | Что осталось |
+|---|---|---|
+| `notefig/notefig` | `lint:cli` добавлен в `cbb21a4c` вместе со строкой в своде, удалён в тот же день в `ffaf7d8c` | `npm run lint:cli` в `AGENTS.md` |
+| `JonnyKreng/pebble-navi` | `debug` добавлен в `1630de8` вместе со строкой в своде, удалён через два дня в `757c563` | `npm run debug  # build + install + logs` |
+
+Замер целиком — `incidents/README.md`, 2026-09-11.
+
+**Почему машина, а не внимательность.** Скрипт удаляют в одном файле, свод живёт в другом, и
+правка «fix(ci): resolve GitHub Actions failures» о своде не думает. Ровно как у
+`entry-links-exist`: расхождение появляется не при написании свода, а через дни, в другой задаче.
+
+**Что именно сверяется.**
+
+| В своде | С чем |
+|---|---|
+| `npm run X`, `pnpm run X`, `yarn run X`, `bun run X` | ключи блока `"scripts"` всех `package.json` репозитория, кроме `node_modules` |
+| `make X` (и `make -j4 X`) | цели всех `Makefile`, `makefile`, `GNUmakefile`, `*.mk` |
+| `just X` | рецепты и псевдонимы `justfile` |
+
+Скрипты берутся только из блока `"scripts"`: в `pebble-navi` `debug` — ещё и имя зависимости, и
+поиск любого `"debug":` в файле сказал бы «есть». Все `package.json` репозитория, а не только
+корневой: команда из свода часто живёт в пакете рабочего пространства.
+
+**Какие файлы.** Только своды агента: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` в корне (регистр
+имени не важен), `.claude/CLAUDE.md`, `.github/copilot-instructions.md`. README не берётся: там
+пишут и команды для ЧУЖОГО проекта — «в своём проекте запусти `npm run aqk`».
+
+**Готовый аналог.** agentlint, правило `cmd-cross-reference`, — только npm-скрипты и только
+корневой `package.json`. На живом проекте, где свод называет шестнадцать целей `make` и ни
+одного `npm run`, оно молчит по построению.
+
+**Чего НЕ ловит.**
+
+- **`make` и `just` в прозе.** Ищутся только внутри кода — в обратных кавычках и блоках: «make
+  sure the tree is clean» — не команда. Свод, где команда написана прозой без кавычек, сверен не
+  будет. `npm run` однозначен и ищется везде.
+- **Шаблоны и присваивания.** `npm run build:*`, `npm run cms:<имя>`, `make <цель>`, `make test
+  V=1` не называют одну команду и пропускаются. Отсюда же: свод, говорящий «скрипты `dev:local*`
+  сняты», находкой не считается.
+- **Команды с каталогом.** `make -C docs html`, `make -f other.mk x`, `npm --prefix web run x`,
+  `pnpm --filter web run x` — цель живёт в чужом файле, по одной строке его не определить.
+  Пропускаются целиком.
+- **Сокращения и прочие запускалки.** `yarn build` без `run`, `tox -e lint`, `task lint`,
+  `cargo xtask`, `uv run x` — не сверяются. Список взят из случаев, а не для полноты.
+- **Цели из шаблонных правил make.** `%.o: %.c` покрывает `make foo.o`; такая цель будет названа
+  несуществующей. В своде агента такое встречается редко.
+- **Что команда делает то, что обещает свод.** Скрипт `lint` может ничего не проверять — это
+  вопрос уже к нему, а не к своду.
+
+**Образцы.** `red/` — свод велит `npm run debug`, а `debug` в `package.json` есть только в
+зависимостях; и `make deploy` при `Makefile` с одной целью `test`: гейт обязан краснеть. `green/`
+— те же имена существуют, `make -j4 lint` с флагом, `just fmt`, «make sure» в прозе, шаблоны
+`npm run gen:*` и `make <target>`, `VERSION := 1.0` в `Makefile`: гейт обязан молчать.

package/kit/gates/entry-commands-exist/check.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env sh
+# Команда, которую свод велит запускать, существует в проекте.
+#
+# ЗАЧЕМ ИМЕННО ЭТО. Агент берёт команды из свода дословно. Скрипт переименовали или удалили —
+# свод продолжает велеть «npm run lint:cli», агент зовёт несуществующее, получает «Missing
+# script» и дальше либо чинит не то, либо сообщает «проверил» про проверку, которой нет.
+# Соседняя запись `entry-links-exist` ловит в своде несуществующие ФАЙЛЫ; эта — КОМАНДЫ.
+#
+# СЛУЧАИ, ИЗ КОТОРЫХ ВЗЯЛАСЬ ЗАПИСЬ (2026-09-11, выборка из 99 публичных репозиториев с
+# AGENTS.md, где упомянут «npm run»; подробности — incidents/README.md):
+#   notefig/notefig      скрипт lint:cli появился в cbb21a4c вместе со строкой в своде и в тот
+#                        же день удалён в ffaf7d8c; свод всё ещё велит «npm run lint:cli»
+#   JonnyKreng/pebble-navi  скрипт debug добавлен в 1630de8 вместе со строкой в своде, удалён
+#                        через два дня в 757c563; строка «npm run debug» в своде осталась
+# Во втором случае `debug` есть в зависимостях — поэтому скрипты берутся из блока "scripts",
+# а не любым «"debug":» в файле: иначе ложное «есть».
+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"
+# Файл на месте — этого мало: подмена содержимого давала код 0. Метка стоит в КОНЦЕ _skip.sh,
+# поэтому проверка ловит и обрыв файла на середине.
+if [ "${AQK_SKIP_READY:-}" != 1 ]; then
+  echo "_skip.sh есть, но обход не собрался — проверка НЕ СОСТОЯЛАСЬ, а не прошла"
+  echo "  почини: замени kit/gates/_skip.sh целым файлом из каталога"
+  exit 2
+fi
+
+# --- своды агента ---------------------------------------------------------------
+# То, что агент читает при запуске. README не берём: там пишут и команды для ЧУЖОГО проекта
+# («в своём проекте запусти npm run aqk»). Регистр имени не важен: `agents.md` встречается.
+ENTRIES=$( { find "$DIR" -maxdepth 1 -type f \( -iname 'agents.md' -o -iname 'claude.md' -o -iname 'gemini.md' \) -print
+  for F in .claude/CLAUDE.md .github/copilot-instructions.md; do [ -f "$DIR/$F" ] && printf '%s\n' "$DIR/$F"; done
+} 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$')
+[ -z "$ENTRIES" ] && { echo "свода агента здесь нет — сверять нечего"; exit 0; }
+
+# --- что в проекте есть ---------------------------------------------------------
+# Скрипты — только из блока "scripts" каждого package.json (рабочие пространства тоже: команда
+# из свода часто живёт в пакете, а не в корне). Файл склеивается в строку: блок бывает и в одну.
+SCRIPTS=$(find "$DIR" $(skip_find) -type f -name package.json -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$' \
+  | while IFS= read -r P; do
+      tr '\r\n' '  ' < "$P" | sed -n 's/.*"scripts"[[:space:]]*:[[:space:]]*{\([^}]*\)}.*/\1/p' \
+        | grep -oE '"[^"]+"[[:space:]]*:' | sed 's/^"//; s/"[[:space:]]*:$//'
+    done)
+HAS_PKG=$(find "$DIR" $(skip_find) -type f -name package.json -print 2>/dev/null | own_samples_filter "$DIR" | grep -v '^$' | head -1)
+
+# Цели make: строка вне рецепта, слова до двоеточия; «VAR := x» — присваивание, не цель.
+TARGETS=$(find "$DIR" $(skip_find) -type f \( -name Makefile -o -name makefile -o -name GNUmakefile -o -name '*.mk' \) -print 2>/dev/null \
+  | own_samples_filter "$DIR" | grep -v '^$' | while IFS= read -r M; do
+      awk '/^[^\t#][^=]*:([^=]|$)/ { sub(/:.*/, ""); n = split($0, a, /[ \t]+/); for (i = 1; i <= n; i++) if (a[i] != "") print a[i] }' "$M"
+    done)
+
+# Рецепты just: «имя:», «@имя арг:», «alias имя := …».
+RECIPES=$(find "$DIR" $(skip_find) -type f \( -name justfile -o -name Justfile -o -name .justfile \) -print 2>/dev/null \
+  | own_samples_filter "$DIR" | grep -v '^$' | while IFS= read -r J; do
+      awk '/^alias[ \t]+/ { print $2; next }
+           /^@?[A-Za-z_][A-Za-z0-9_-]*([ \t][^:=]*)?:([^=]|$)/ { sub(/^@/, ""); sub(/[ \t:].*/, ""); print }' "$J"
+    done)
+
+has() { printf '%s\n' "$2" | grep -qxF -- "$1"; }
+
+# --- что свод велит запускать ---------------------------------------------------
+# «npm run X» однозначен где угодно. «make X» и «just X» — только внутри кода (обратные кавычки,
+# блоки): в прозе «make sure» — не команда. Шаблоны («npm run build:*», «make <цель>») и
+# присваивания («make test V=1») пропускаются: они не называют одну команду.
+MISS=0
+# Список команд — через файл, а не через трубу: цикл в трубе идёт в подоболочке, и отметка
+# о находке из него не возвращается.
+TMP=$(mktemp) || exit 2
+trap 'rm -f "$TMP"' EXIT
+report() {
+  echo "$1: «$2» — $3"
+  MISS=1
+}
+while IFS= read -r E; do
+  [ -n "$E" ] || continue
+  # Код свода: строки блоков целиком, вне блоков — только вставки в обратных кавычках.
+  CODE=$(awk '/^[ \t]*(```|~~~)/ { f = !f; next }
+    f { print; next }
+    { while (match($0, /`[^`]+`/)) { print substr($0, RSTART + 1, RLENGTH - 2); $0 = substr($0, RSTART + RLENGTH) } }' "$E")
+  grep -oE '(npm|pnpm|yarn|bun)[[:space:]]+run[[:space:]]+[A-Za-z][A-Za-z0-9_:.-]*[*<{]?' "$E" \
+    | grep -v '[*<{:]$' | sed 's/\.$//; s/[[:space:]][[:space:]]*/ /g' | sort -u > "$TMP"
+  while IFS= read -r CMD; do
+    N=${CMD##* }
+    has "$N" "$SCRIPTS" && continue
+    if [ -n "$HAS_PKG" ]; then report "$E" "$CMD" "такого скрипта нет ни в одном package.json"
+    else report "$E" "$CMD" "package.json в репозитории нет вовсе"; fi
+  done < "$TMP"
+  for N in $(printf '%s\n' "$CODE" | grep -E '(^|[^A-Za-z0-9_-])make[[:space:]]' | grep -vE -- '-C|--directory|-f[[:space:]]|--file' \
+      | grep -oE '(^|[^A-Za-z0-9_-])make([[:space:]]+-[A-Za-z0-9]+)*[[:space:]]+[A-Za-z][A-Za-z0-9_.-]*=?' \
+      | grep -v '=$' | sed 's/.*[[:space:]]//' | sort -u); do
+    has "$N" "$TARGETS" || report "$E" "make $N" "такой цели нет ни в одном Makefile"
+  done
+  for N in $(printf '%s\n' "$CODE" | grep -oE '(^|[^A-Za-z0-9_-])just[[:space:]]+[A-Za-z][A-Za-z0-9_-]*' \
+      | sed 's/.*[[:space:]]//' | sort -u); do
+    has "$N" "$RECIPES" || report "$E" "just $N" "такого рецепта нет в justfile"
+  done
+done <<EOF
+$ENTRIES
+EOF
+
+if [ "$MISS" = 1 ]; then
+  echo "  почини: верни команду в проект или исправь свод. Агент берёт команды из свода дословно:"
+  echo "  несуществующая команда — это «Missing script» у агента и «проверил» про проверку, которой нет."
+fi
+exit "$MISS"

package/kit/gates/entry-commands-exist/gate.yml

@@ -0,0 +1,19 @@
+# Запись каталога AQK. Норма и все поля — kit/gates/README.md.
+# Читается программой; всё, что нельзя выполнить, живёт в README.md рядом.
+
+intent: команды, которые свод велит запускать, существуют в проекте
+intent_en: commands the agent rules tell it to run actually exist in the project
+
+# Только там, где агенту вообще пишут свод. Проекту без AGENTS.md/CLAUDE.md сверять нечего.
+trigger:
+  has_agent_entry: true
+
+# Переносимая проверка — единственный рецепт. Готовое правило есть у agentlint
+# (`cmd-cross-reference`), но оно знает только npm-скрипты; на живом проекте, где свод называет
+# шестнадцать целей make, оно молчит по построению. Разбор — research/competitors/agentlint.md.
+recipes:
+  any: bash {gate}/check.sh {dir}
+
+proof: incidents/README.md, 2026-09-11 «свод велит команду, которой в проекте больше нет» —
+  9 из 99 публичных репозиториев с AGENTS.md называют скрипт, которого нет ни в одном
+  package.json; в двух история показывает, как: скрипт удалён, строка в своде осталась

package/kit/gates/entry-commands-exist/green/AGENTS.md

@@ -0,0 +1,13 @@
+# Rules
+
+Make sure the tree is clean, then build and check before every commit:
+
+```sh
+npm run build
+npm run debug        # build + install + logs
+make test
+make -j4 lint
+just fmt
+```
+
+Scripts named like `npm run gen:*` are generated; run `make <target>` for anything else.

package/kit/gates/entry-commands-exist/green/Makefile

@@ -0,0 +1,6 @@
+.PHONY: test lint
+VERSION := 1.0
+test:
+	node --test
+lint: test
+	echo ok

package/kit/gates/entry-commands-exist/green/justfile

@@ -0,0 +1,2 @@
+fmt:
+    echo fmt

package/kit/gates/entry-commands-exist/green/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "sample",
+  "scripts": {
+    "build": "tsc",
+    "debug": "npm run build && node dist/index.js"
+  },
+  "dependencies": {
+    "debug": "4.3.4"
+  }
+}