agent-quality-kit 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# AQK — Agent Quality Kit
+
+**Стандарт готовности репозитория к тому, что код в нём пишет агент.** Обещание проекта
+становится командой с кодом возврата — и его держит машина, а не чья-то добрая воля.
+
+Что вообще должно быть на проекте, чтобы это было возможно, — словами, без привязки к языку и
+инструменту: [«тёмная фабрика» и обязательный минимум](kit/docs/ai/project-baseline.md).
+
+```bash
+npx github:arsen-ask-lx/Agent_Quality_Kit start     # кода ещё нет: сторожа дня 0 сразу
+npx github:arsen-ask-lx/Agent_Quality_Kit doctor    # код уже есть: уровень и что поставить
+```
+
+**Первый запуск молчит две-три минуты** — `npx` скачивает репозиторий целиком и до конца не
+печатает ничего. Это не зависание, подожди. Дальше команды работают мгновенно.
+
+**Что нужно.** Node 18+ и оболочка `sh` — она есть в macOS, Linux и WSL; на Windows подойдёт
+Git Bash. Переносимые проверки написаны на `sh` намеренно: он есть везде, где собирают код.
+
+**Не зависит от инструмента:** Claude Code, Codex, Cursor — и без ИИ тоже.
+
+При первой установке на машине `init`/`start` один раз печатают ссылку на звезду и на «завести
+Issue» — ничего не постится сама, только текст для человека, и больше не повторяется.
+
+**Готовые правила ставятся отдельно и по желанию.** Переносимая проверка работает без них
+всегда; если в проекте стоит `ruff`, `eslint` или `vulture`, запись возьмёт готовое правило —
+оно точнее. Одна запись, `dead-code`, без готового инструмента не работает вовсе и честно
+скрывается: граф вызовов поиском по тексту не построить.
+
+## Как устроено
+
+Весь стандарт — файл `.aqk.yml` в корне:
+
+```yaml
+aqk: 1
+entry:  [AGENTS.md]        # что агент читает первым
+rules:  .aqk/rules         # где стандарты
+gates:                     # что обязано пройти — командами, не словами
+  lint: "npm run lint"
+  secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
+samples:  gates            # красный и зелёный образец каждой записи
+ratchets: ratchets         # реестры долга: список может только укорачиваться
+lessons:  incidents        # где копятся уроки
+```
+
+Пустое поле — не заглушка, а честный ответ «ступень не пройдена»: `init` кладёт их пустыми,
+а заполняются они по мере того, как появляется чем их заполнить.
+
+**Если утверждение нельзя проверить машиной — его в стандарте нет.** Иначе значок означает
+доверие к автору, а не факт.
+
+## Четыре ступени
+
+| Уровень | Требуется | Что доказано |
+|---|---|---|
+| **AQK-0** | манифест и точка входа | инструмент знает, что читать |
+| **AQK-1** | правила есть, гейты объявлены командами | проверки исполняются |
+| **AQK-2** | у гейтов красные и зелёные образцы, долг под храповиком | гейт ловит брак и молчит на исправном коде |
+| **AQK-3** | журнал уроков с выводами | шишка не набивается дважды |
+
+```bash
+aqk doctor --run --min 1   # в конвейере: ошибка, если ниже AQK-1 ИЛИ упал хоть один гейт
+```
+
+## Поставить гейт
+
+```bash
+aqk find "печать в проде"     # есть ли уже такой гейт — сверка по намерению
+aqk doctor                    # что применимо к этому репозиторию и чего нет
+aqk add secrets-not-in-code   # копирует проверку и образцы в проект, объявляет в манифесте
+aqk doctor --run              # запускает объявленные гейты и показывает результат
+aqk ratchet no-print-in-prod  # старое — долг, новое не пускать
+```
+
+Каждый `doctor --run` перезаписывает `.aqk/last-run.md` — короткий отчёт, что из объявленного
+реально сработало и за сколько. Список гейтов в манифесте молчит о том, сколько из них живы
+именно сейчас; отчёт — нет. Файл эфемерный, в `.gitignore` его стоит держать самому.
+
+## Поймал ошибку, которую не поймал сторож
+
+```bash
+aqk why "файл вырос до девяти тысяч строк"
+```
+
+Ответ один из трёх, и выбирает его прогон, а не память: **сторожа не было** · **сторож есть,
+но эту поломку не видит** · **сторож есть и ловит — значит его обошли**. Разница решает, что
+чинить: саму проверку или её место в конвейере. Без прогона эти два случая неразличимы, и
+чинят обычно не тот. При неуверенном совпадении команда не выбирает за тебя, а спрашивает.
+
+**Храповик** нужен, когда правило вводят в проект, где старый код ему не соответствует.
+Список нарушений снимается в реестр, гейт разрешает его **укорачивать** и запрещает удлинять.
+Правило действует со дня установки, старый код трогать не надо.
+
+`add` **копирует проверку в репозиторий**, а не ссылается на пакет: при установке через `npx`
+пакет временный, и завтра команда в манифесте указывала бы в никуда.
+
+## Каталог обещаний
+
+`doctor` смотрит на репозиторий — языки, наличие гейтов — и показывает **только применимое**:
+что уже держит машина, что применимо и не поставлено, что скрыто и почему. Каталог может
+вырасти до сотен записей, конкретный проект по-прежнему увидит десяток.
+
+Запись принимается, только если её арбитр краснеет на красном образце, молчит на зелёном и
+назван реальный отказ, который она поймала. Проверяет это машина: `bash tool/selfcheck/gates.sh`.
+
+## Методички одним файлом
+
+```bash
+aqk blob     # собирает GOD_AI.md из kit/docs — чтобы разом отдать методички в чат
+```
+
+Файл **собирается, а не хранится**: править надо оригиналы. Копия, которую правят руками, через
+неделю расходится с источником, и непонятно, какая настоящая.
+
+## Принести свой гейт
+
+Каталог живёт чужими шишками. Порядок и порог — в [`CONTRIBUTING.md`](CONTRIBUTING.md):
+сверься `aqk find`, заведи заготовку `aqk new`, положи два образца, заполни четыре поля,
+прогони машиной. Отбор делает `tool/selfcheck/gates.sh`, а не рецензент.
+
+## Журнал шишек
+
+```bash
+aqk note "гейт краснел на правильном коде"    # запись без раздела «Вывод» не принимается
+```
+
+## Честно о состоянии
+
+Задача целиком — в [`PROJECT.md`](PROJECT.md): что строим, четыре сценария, критерий успеха, что осталось.
+
+
+Версия 1, один автор. Сам комплект держит **AQK-3**: девятнадцать проверок объявлено и
+прогоняется конвейером, два реестра долга под храповиком. Пока комплектом пользуется один
+человек, AQK — красивое слово в README. Он начнёт работать, когда появится чужой третий проект.
+
+**Стандарт нельзя выпустить первым.** Спецификация раньше практики — это тридцать первый
+заброшенный репозиторий с манифестом и нулём пользователей. Порядок обратный:
+
+| # | Шаг | Состояние |
+|---|---|---|
+| 1 | живём по этому на своих проектах | ⬜ измерено: у трёх своих проектов манифеста нет, уровень не заведён |
+| 2 | `doctor` считает уровень | ✅ сделано |
+| 3 | сложившееся записано как короткая спецификация | ✅ [`SPEC.md`](SPEC.md) |
+| 4 | третий проект — **чужой** | ❌ первый честный сигнал, его ещё нет |
+| 5 | значок, сайт, разговор с людьми | ❌ только после четвёртого шага |
+
+## Очередь работ
+
+Живёт в одном месте — [`PROJECT.md` §9](PROJECT.md). Список здесь не повторяется: два списка через месяц
+расходятся, и непонятно, какой настоящий.
+
+Чего нет: второго пользователя; покрытия команд, которые пишут на диск (проверены прогоном на
+чистой папке, но не по отдельности); третьего — чужого — проекта.
+
+MIT.