git:20260923.38682bd to git:20260925.fe73195

21 added, 13 removed. Audit A to A.

# AGENTS.md

Инструкции для ИИ-агентов, которые работают с этим репозиторием.

## Что это

- Русская адаптация скилла [avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing): два скилла (`skills/avoid-ai-writing-russian`, `skills/antiplagiat`) и детектор на TypeScript для Bun (`src/`). Всё пишется на русском: документация, комментарии, сообщения коммитов. Идентификаторы в коде — на английском.

+ Русская адаптация скилла [avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing): два скилла (`skills/avoid-ai-writing-russian`, `skills/antiplagiat`) и детектор на Python (пакет `aiw_ru` в `src/`, команда `aiw-ru`). Всё пишется на русском: документация, комментарии, сообщения коммитов. Идентификаторы в коде — на английском.

## Устройство

- `skills/avoid-ai-writing-russian/SKILL.md` — точка входа скилла: договор о правке, режимы, уровни серьёзности, формат ответа, «никогда не добавляй». Держать короче 500 строк.

- `skills/avoid-ai-writing-russian/references/patterns.md` — каталог примет, профили контекста и голоса.

- `skills/antiplagiat/SKILL.md` — под-скилл подготовки к «Антиплагиату».

- - `src/text.ts` — нормализация (невидимые символы, подмена букв, ё→е) с картой смещений, маскирование защищённых областей, разбиение на блоки и предложения.

- - `src/lexicon.ts` — словари примет на мини-языке фраз (`*` — любое окончание).

- - `src/detect.ts` — детектор: словари, отпечатки, типографика, структура, стилометрия, оценка.

- - `src/antiplagiat.ts` — оценка по фрагментам и калибровка.

- - `src/validate.ts` — проверка сохранности правки.

- - `src/cli.ts` — команда `aiw-ru`.

+ - `src/aiw_ru/text.py` — нормализация (невидимые символы, подмена букв, ё→е) с картой смещений, маскирование защищённых областей, разбиение на блоки и предложения.

+ - `src/aiw_ru/lexicon.py` — словари примет на мини-языке фраз (`*` — любое окончание).

+ - `src/aiw_ru/detect.py` — детектор: словари, отпечатки, типографика, структура, стилометрия, оценка.

+ - `src/aiw_ru/antiplagiat.py` — оценка по фрагментам и калибровка.

+ - `src/aiw_ru/validate.py` — проверка сохранности правки.

+ - `src/aiw_ru/types.py` — результаты для JSON (модели pydantic: поля в snake_case, в JSON — camelCase).

+ - `src/aiw_ru/compat.py` — семантика JavaScript, с которой переносился детектор: регулярные выражения, округление, trim.

+ - `src/aiw_ru/features.py`, `src/aiw_ru/models.py` — признаки и необязательная модель LightGBM с Hugging Face.

+ - `src/aiw_ru/cli.py` — команда `aiw-ru` (вывод через rich).

+ - `scripts/llmtrace.py`, `scripts/train.py`, `scripts/hub.py` — замер детектора на корпусе LLMTrace, обучение LightGBM и выкладка модели с карточкой на Hugging Face. Подробности в CONTRIBUTING.md, разделы «Замеры на корпусах» и «Модель LightGBM».

+ - `scripts/release.py` и соседние — выпуск версий, проверки версий, коммитов и невидимых символов; `evals/` — поведенческие проверки скиллов.

## Правила

- Любое правило детектора должно быть описано в `patterns.md`. Обратное не обязательно: правила на суждение живут только в каталоге.

- Новый тип находки получает вес в `WEIGHTS`, подпись в `TYPE_LABELS` и тест.

- - Правило не должно срабатывать на `test/fixtures/corpus/human/`; точность важнее полноты.

- - Не писать невидимые символы в исходники буквально: только `\uXXXX`.

+ - Правило не должно срабатывать на `tests/fixtures/corpus/human/`; точность важнее полноты.

+ - Не писать невидимые символы в исходники буквально: только `\uXXXX` или `chr()`.

- Скилл помогает автору с его собственным текстом и с оформлением заимствований как цитирований. Не добавлять приёмы, которые маскируют чужой текст или обманывают проверку техническими уловками.

- - Документация проекта должна проходить `bun run selfscan` без находок P0 и P1.

+ - Документация проекта должна проходить самопроверку детектором (хук `selfscan`) без находок P0 и P1.

+ - Только абсолютные импорты: `from aiw_ru.text import words`. Относительные запрещены правилом ruff TID252.

+ - Замеры и обучение живут только в `scripts/`, не в `skills/`; их зависимости в группе `train` (дообучение трансформера — в группе `transformer`), инструменты разработки — в группе `dev`. По умолчанию группы не ставятся: `uv run --project ../..` из скилла получает только детектор. Для разработки `uv sync --group dev --group train`. Корпуса, кэши и обученные модели хранятся вне репозитория (`~/.cache/aiw-ru`, модели — на Hugging Face), в git их не класть.

+ - Модели необязательны: скиллы и детектор работают без них, а ставить модель агент предлагает пользователю и ставит только с его согласия.

## Команды

```bash

- bun test

+ uv run pytest

```

```bash

- bun run typecheck

+ uv run ty check

```

```bash

- bun run selfscan

+ uv run prek run --all-files

```