# KAgent — протокол работы для воркера Hermes

Этот текст вставляется в начало каждого задания по KAgent либо читается воркером как
часть карточки. Он описывает, как работать в этом репозитории.

## Репозиторий и ветки

- рабочая копия: `C:\Users\Ochenstarik\kagent`, проект Hermes `kagent`;
- удалённый: `https://github.com/ochenstarik-ui/kagent`, база — `main`;
- каждая задача работает в своём worktree на своей ветке, ветка указана в карточке;
- прямой push в `main` запрещён. Результат — ветка и pull request;
- перед началом: `git fetch origin` и rebase ветки на `origin/main`.

## Инструменты на машине

Доступны и работают: `node` 24, `pnpm`, `corepack`, `cargo`, `rustc`, `rustup`,
`python`, `ruff`, `git`.

**Docker в PATH Windows отсутствует** — он живёт внутри WSL и засыпает вместе с ней.
Ничего, что требует `docker compose`, в задачи этого этапа не входит. Если задача упирается
в Docker — останавливайся и сообщай, а не изобретай обход.

Python в PATH — 3.11 из venv Hermes, тогда как сервисы нацелены на 3.12. Для линта и
модульных тестов это неважно, для чего-то другого — уточняй.

## Размер задачи

У воркера ограниченный бюджет итераций. Задача в этом репозитории считается правильно
нарезанной, если она:

- трогает один-два файла;
- проверяется одной командой;
- завершается за один прогон без ожидания внешних событий.

Если по ходу выясняется, что задача больше — **не растягивай прогон**. Сделай ту часть,
которая помещается, зафиксируй результат, опиши остаток комментарием к карточке и предложи
отдельную карточку. Незаконченная работа, честно описанная, полезнее исчерпанного бюджета.

## Что запрещено

- **менять существующие тесты**, чтобы сборка стала зелёной. Мешает тест — объясни почему и
  остановись. Причина — `docs/adr/0005-test-oracle-integrity.md`;
- **отмечать пункты roadmap выполненными.** Статусы будут вычисляться из артефактов CI,
  см. `docs/adr/0016-computed-stage-status.md`. Ровно из-за ручных галочек этапы 0.2–0.8
  отмечены завершёнными при неработающем коде;
- **выходить за рамки карточки.** Заметил соседний дефект — комментарий к карточке или
  новая карточка, но не правка в этой ветке;
- **добавлять зависимость без проверки лицензии** и без упоминания в отчёте;
- **копировать исходный код** из Hermes, n8n, Prime Agent и других агентских платформ.
  Архитектуру заимствовать можно, файлы — нет;
- помещать секреты в файлы под контролем версий;
- `git push --force`, переписывание истории, `--no-verify`.

## Порядок источников истины

1. `docs/KAGENT_FULL_PRODUCT_SPEC.md`
2. `docs/THREAT_MODEL.md`
3. `docs/adr/`
4. контракты в `packages/contracts/`
5. текст карточки
6. существующий код

Код последний осознанно: он местами противоречит ТЗ, и это известно.

Разделы ТЗ 35–51 и ADR-0004…0020 находятся на ветке
`docs/adr-0004-0016-trust-verification-economics` (PR #2), в `main` их нет.

## Проверка результата

Запускай ровно то, что указано в карточке как критерий приёмки, и приводи вывод команды в
отчёте. Формулировки «должно работать» и «выглядит корректно» результатом не считаются.

Полезные команды:

```bash
cargo fmt --manifest-path services/gateway/Cargo.toml --check
cargo clippy --manifest-path services/gateway/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path services/gateway/Cargo.toml
pnpm --filter @kagent/control-plane typecheck
pnpm --filter @kagent/control-plane test
ruff check services scripts
python scripts/validate_repository.py
```

## Отчёт

Комментарием к карточке, коротко:

1. что изменено, файлами;
2. вывод проверочных команд;
3. что не сделано и почему;
4. что замечено рядом и стоит отдельной карточки.

Коммит: первая строка до 72 символов, повелительное наклонение, без эмодзи, с указанием
идентификатора карточки в теле.