--- documentId: repoctl-human-guide documentVersion: 0.1.0 schemaApiVersion: stewardship.corsus.ru/v1alpha1 status: draft normative: false language: ru companionDocument: docs/specification.md --- # repoctl: руководство для человека Этот документ объясняет `repoctl` — CLI Repository Stewardship — так, как его видит человек: зачем он нужен, как установить и вызвать его на конкретном репозитории, что означает каждая команда и как читать её вывод. Нормативные определения полей и правил остаются в [specification.md](specification.md); здесь — практика. ## Зачем нужен `repoctl` `repoctl` не заменяет Git, LXD, Docker, Terraform или ваши domain-инструменты. Его задача — единообразно ответить на четыре вопроса про любой репозиторий, оформленный по стандарту Repository Stewardship: 1. что это за репозиторий и кто его владелец (`ops/contract.yaml`); 2. какие знания нужны для конкретной задачи, а не вся документация целиком (`kdb/kdb.yaml` + `context`); 3. корректно ли он оформлен (`validate`); 4. как безопасно создать новый репозиторий по стандарту или подключить существующий (`init`, `adopt`) — только после явного просмотра плана и подтверждения его хэша. По умолчанию все команды **read-only**. Запись происходит только в `init --apply` и `adopt --mode apply`, и только после того, как вы одобрили ранее построенный план по его SHA-256. ## Модель установки: один инструмент — много репозиториев `repoctl` устанавливается один раз из репозитория `.repoctl` (этот репозиторий), а затем вызывается **из любого другого репозитория**, который вы хотите проверить, описать или подключить к стандарту. Сам `.repoctl` не обязан быть тем репозиторием, над которым вы сейчас работаете: ```bash # Один раз: установить repoctl из этого репозитория cd path/to/.repoctl uv tool install --editable . # Дальше: вызывать его из любого управляемого репозитория cd path/to/any-other-repo repoctl validate --repo . ``` Пока `repoctl` не установлен как инструмент, из исходников этого репозитория он запускается через `uv run repoctl ...` (см. README.md). Если репозиториев несколько и они лежат в общем каталоге, добавьте этот каталог как root один раз: ```bash repoctl config --output json add-root C:/Users/example/Git repoctl describe --repo some-repo-name --output json ``` Порядок разрешения имени репозитория: явный `--root` → переменная окружения `REPOCTL_ROOTS` → сохранённый `config add-root` → текущий репозиторий (если команда запущена изнутри него). `--output` — параметр конкретной подкоманды, а не общий флаг: он идёт **после** имени команды (`repoctl validate --output json ...`), а для `config` — сразу после `config`, перед `show`/`add-root`/`remove-root` (`repoctl config --output json add-root ...`). ## Команды по порядку знакомства ### `validate` — всё ли корректно ```bash repoctl validate --repo . --output json ``` Проверяет `ops/contract.yaml` и `kdb/kdb.yaml`: envelope, ID, типы, безопасность путей, ссылки между темами и документами, secret-shaped поля, отсутствие shell-строк в operations. Ничего не пишет. На чистом репозитории: ```json { "schema": "stewardship/repoctl-result@0.1", "command": "validate", "outcome": "success", "data": { "repository": "...", "valid": true }, "findings": [] } ``` При ошибке `outcome` становится `"failure"`, `findings` заполняется, а процесс завершается кодом `1`. ### `skills` — поставить агентские скиллы туда, где агент их ищет ```bash repoctl skills install --repo . # в этот репозиторий, .claude/skills/ repoctl skills install --global # в ~/.claude/skills/, для всех репозиториев repoctl skills status --repo . # что установлено и не разошлось ли ``` Ставит `repository-adoption`, `repository-bootstrap` и `repo-handoff`. Это точка входа: до появления команды скиллы записывал только `init`, то есть они попадали исключительно в **новые** репозитории, а для приёма существующего нужен был скилл, который туда нечем было положить. Область обязательно указывается явно — `--repo` или `--global`: локальная установка едет вместе с репозиторием и достаётся тому, кто его склонирует, глобальная следует за оператором в том числе в ещё не принятые репозитории. Угадывать между ними команда не будет (`SKILLS_SCOPE_MISSING`). Повторный запуск идемпотентен. Скилл, содержимое которого отличается от поставляемого этой версией, **не перезаписывается**: команда сообщает `SKILLS_MODIFIED` и завершается кодом `1`, заменить его можно явным `--force`. Различить «оператор поправил файл» и «repoctl ушёл вперёд» нельзя, поэтому оба случая требуют подтверждения. Проверка проходит по всем скиллам до первой записи, так что отказ не оставляет каталог наполовину обновлённым. В отличие от `init` и `adopt`, здесь нет плана и подтверждения по хэшу: эта дисциплина защищает содержимое репозитория, а команда пишет только файлы, принадлежащие инструменту, в фиксированный подкаталог. ### `discover` — что есть в каталоге репозиториев ```bash repoctl discover --root C:/Users/example/Git --output json ``` Обходит указанный каталог, находит все `ops/contract.yaml`, строит `CatalogIndex` — детерминированно отсортированный список репозиториев с их типом, lifecycle и hash контракта. Не следует по symlink, пропускает `.git`, `.venv`, `node_modules` и подобные. Дублирующиеся имена репозиториев — ошибка (`CATALOG_REPOSITORY_DUPLICATE`). Репозиторием считается корень git-репозитория. Контракт, лежащий внутри рабочего дерева другого репозитория — fixture, example, vendored copy — это его содержимое, а не равноправный сосед: такой путь в каталог не попадает и сообщается как `CATALOG_NESTED_CONTRACT_SKIPPED` (severity `info`). ### `describe` — паспорт одного репозитория ```bash repoctl describe --repo some-repo-name --output json ``` Возвращает нормализованный `RepositoryContract` — только контракт, без загрузки KDB. Полезно, чтобы быстро узнать тип, владельца и content roots репозитория, не читая ничего лишнего. ### `kdb` — что вообще есть в базе знаний ```bash repoctl kdb --repo . ``` Единственная команда, чей `--output human` печатает не строку статуса, а само содержимое: markdown-таблицу тем (id, объявленные intent-ы, документы, к которым тема маршрутизирует, и ключи верхнего уровня в `data`) и таблицу документов (id, путь, роль, статус; `stale` помечен `(!)`). Это сделано намеренно — вопрос «что в базе знаний» отвечается содержимым, а не статусом. Находки по-прежнему уходят в stderr, таблица в stdout, поэтому `repoctl kdb > kdb.md` даёт чистый markdown. `--output json` и `--output yaml` возвращают обычный конверт с `stewardship/knowledge-overview@0.1` внутри. Точка входа не угадывается: берётся `spec.knowledge.entrypoint` из `ops/contract.yaml`, с откатом на `kdb/kdb.yaml`. Репозиторий без базы знаний получает предупреждение `KNOWLEDGE_ENTRYPOINT_MISSING` и код возврата `3`. Таблица отвечает «что есть». Чтобы получить только нужное под конкретную задачу, возьмите intent из колонки Intents и спросите `context`. ### `context` — только нужные знания под задачу Главная команда для агента. Вместо чтения всей документации репозитория: ```bash repoctl context --repo . --intent domain.action --output json ``` Возвращает `ContextBundle`: подходящие темы (`topics`) по точному совпадению `intent`, связанные операции, content roots и — если передан `--materialize` — сами тексты нужных разделов, без остального репозитория. `--budget-bytes N` ограничивает объём материализованного текста; при превышении бюджета контент обрезается и в `warnings` появляется `CONTEXT_BUDGET_TRUNCATED`. Флаг `--strict` превращает такую усечённость (или устаревший/отсутствующий документ) в код возврата `4`, а не в тихое предупреждение — используйте его, когда неполный контекст недопустим для задачи. ### `init` — создать новый репозиторий по стандарту Двухшаговый процесс: сначала план, затем — только после ревью — применение. ```bash # Шаг 0: получить шаблон ответов — он называет все ключи и их допустимые значения repoctl init --answers-template > answers.yaml # Шаг 1: построить план (ничего не пишет на диск) repoctl init --repo ../new-repo --answers answers.yaml --output json > plan.json ``` Ключи файла ответов — не имена флагов (`--type` задаёт `repositoryType`), поэтому шаблон и существует. `summary` и `namespace` стоит заполнить сразу: они дёшевы, а иначе навсегда остаются заглушками в контракте. Файлы скиллов, оставленные `repoctl skills install`, коллизией **не** считаются: путь, уже содержащий ровно то, что план собирался записать, — не конфликт. Файл с другим содержимым конфликтом остаётся. Ответы проверяются до сборки плана, чтобы `init` не мог создать репозиторий, который не проходит собственный `validate`: | Код | Когда | |---|---| | `INIT_ANSWERS_INCOMPLETE` | нет `--name` или `--type` | | `INIT_NAME_INVALID` | имя не подходит под `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`; в сообщении есть готовая замена (`Services/Mail` → `services-mail`) | | `INIT_TYPE_UNKNOWN`, `INIT_LIFECYCLE_UNKNOWN`, `INIT_ACCESS_UNKNOWN` | значение вне enum схемы | | `INIT_OWNER_UNKNOWN` | владелец не подтверждён — та же граница, что у `adopt` | | `INIT_PATH_COLLISION` | каталог уже содержит один из создаваемых путей; для существующего репозитория нужен `adopt`, а не `init` | В ответе — полный список файлов, которые будут созданы (`ops/contract.yaml`, `kdb/kdb.yaml`, `AGENTS.md`, `CLAUDE.md`, `.claude/skills/*`, и т.д.) и `planHash`. Прочитайте план, убедитесь, что он ожидаем. ```bash # Шаг 2: применить план, явно подтвердив его хэш repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256: --output json ``` `--approve` должен побайтово совпасть с `planHash` — иначе команда завершится кодом `5` (approval required/denied) и ничего не запишет. `init` также повторно проверяет, что ни один из планируемых файлов не появился с момента построения плана — иначе откажется перезаписывать существующее. `--plan` принимает как файл, сохранённый напрямую из `--output json > plan.json` (полный envelope с `data`), так и голый объект плана — `repoctl` сам распознаёт и разворачивает envelope. ### `adopt` — подключить существующий репозиторий Четыре режима, соответствующие фазам runbook (см. [adoption-runbook.md](adoption-runbook.md)): ```bash repoctl adopt --repo ../legacy-repo --mode assess --output json # инвентаризация, ничего не пишет repoctl adopt --repo ../legacy-repo --mode plan --owner infra --output json # предлагаемый diff + planHash, ничего не пишет repoctl adopt --repo ../legacy-repo --mode apply --plan plan.json --approve sha256: --output json repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт о совместимости после apply ``` `plan` требует подтверждённого владельца — `--owner` (можно повторять) либо `owners:` в `--answers`; без него он отказывается строиться, а не выпускает контракт с пустым `owners`. Имя репозитория берётся из URL remote (последние два сегмента: `.../OpTools/LXD.git` → `optools-lxd`), либо задаётся `name:` в файле ответов. `plan` также отказывается строиться, пока `assess` оставил находку severity `error` — например, файл с живым credential в git. Принять такую находку осознанно можно в файле ответов; `reason` обязателен, а сам acknowledgement входит в `planHash`: ```yaml owners: [infrastructure] acknowledgedFindings: - code: ADOPT_SECRET_CONTENT_VERIFIED path: airflow/.env reason: rotation scheduled, tracked separately ``` По умолчанию используется стратегия `overlay`: existing domain-native layout (например, `profiles-source/`, существующий `kdb.yaml` в корне) не перемещается и не переписывается — поверх него добавляется только недостающая метадата Stewardship. Если в репозитории уже занят путь `kdb/kdb.yaml`, `adopt` предложит `ops/knowledge.yaml` вместо конфликта. `apply` никогда не делает `git commit`, `push` или `clone`. ## Коды возврата | Код | Значение | |---|---| | `0` | успех, ошибок нет | | `1` | ошибка валидации или операции | | `2` | некорректный вызов CLI или входные данные | | `3` | репозиторий или ресурс не найден | | `4` | неполный/устаревший context при `--strict` | | `5` | approval не совпал или отсутствует (`init`/`adopt --mode apply`) | Машинный вывод (`--output json` или `--output yaml`) всегда идёт в stdout как единый envelope `stewardship/repoctl-result@0.1` (`schema`, `command`, `outcome`, `data`, `findings`). Диагностика и предупреждения человеку — в stderr, вне зависимости от `--output`. ## Устранение неполадок - **`ERROR: No .git ancestor found`** — команда запущена вне git-репозитория и `--repo` не указан явно; передайте `--repo <путь>` или запустите `git init` в целевом каталоге. - **`APPROVAL_FAILED` при `init --apply`/`adopt --mode apply`** — переданный `--approve` не совпадает с `planHash` в файле плана; пересчитайте план заново (сравнение файла плана и `planHash` в нём — самопроверка от случайной правки плана вручную). - **`ADOPT_BASELINE_CHANGED`** — репозиторий изменился между `--mode plan` и `--mode apply` (кто-то создал файл из плана вручную); постройте план заново. - **`ADOPT_PATH_COLLISION` / `init` отказывается писать** — план целится в уже существующий файл; `repoctl` намеренно не перезаписывает существующее содержимое — удалите или переименуйте конфликтующий файл вручную и постройте план заново. `INIT_PATH_COLLISION` на этапе плана означает, что каталог уже является репозиторием: используйте `adopt`. - **`INIT_PATH_OUTSIDE_REPOSITORY`** — путь в файле плана ведёт наружу репозитория. План — обычный файл; если он был отредактирован вручную или перенесён между машинами, постройте его заново вместо правки. - **Windows: кириллица или спецсимволы искажены в выводе** — используйте актуальную версию `repoctl`; вывод принудительно кодируется в UTF-8 независимо от кодовой страницы консоли.