The stewardship skills were written by exactly one code path: `init`, which
only runs on a new repository. Adopting an existing one starts from the
repository-adoption skill, and nothing could put that skill there -- so the
entry point to the procedure depended on the operator already having it
from somewhere else. Services/Monitoring carries three domain skills of its
own and no stewardship skill; `adopt` lists `.claude/skills` among its
collision paths and installs nothing.
repoctl skills install --repo . # travels with the repository
repoctl skills install --global # follows the operator everywhere
repoctl skills status --repo .
Scope is stated, never guessed: the two answers differ in who ends up with
the skills, and neither is the obvious default.
No plan and no approval hash. That discipline protects a repository's own
content; this writes only tool-owned files, in a fixed subdirectory, whose
content is fully determined by the installed version. The house rule it
does keep is that a write never destroys what it did not author: a skill
whose content differs is reported as SKILLS_MODIFIED and left alone until
`--force` says otherwise, and the check covers every skill before the first
byte is written, so a refusal leaves nothing half-updated.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
18 KiB
documentId, documentVersion, schemaApiVersion, status, normative, language, companionDocument
| documentId | documentVersion | schemaApiVersion | status | normative | language | companionDocument |
|---|---|---|---|---|---|---|
| repoctl-human-guide | 0.1.0 | stewardship.corsus.ru/v1alpha1 | draft | false | ru | docs/specification.md |
repoctl: руководство для человека
Этот документ объясняет repoctl — CLI Repository Stewardship — так, как его видит человек: зачем он нужен, как установить и вызвать его на конкретном репозитории, что означает каждая команда и как читать её вывод. Нормативные определения полей и правил остаются в specification.md; здесь — практика.
Зачем нужен repoctl
repoctl не заменяет Git, LXD, Docker, Terraform или ваши domain-инструменты. Его задача — единообразно ответить на четыре вопроса про любой репозиторий, оформленный по стандарту Repository Stewardship:
- что это за репозиторий и кто его владелец (
ops/contract.yaml); - какие знания нужны для конкретной задачи, а не вся документация целиком (
kdb/kdb.yaml+context); - корректно ли он оформлен (
validate); - как безопасно создать новый репозиторий по стандарту или подключить существующий (
init,adopt) — только после явного просмотра плана и подтверждения его хэша.
По умолчанию все команды read-only. Запись происходит только в init --apply и adopt --mode apply, и только после того, как вы одобрили ранее построенный план по его SHA-256.
Модель установки: один инструмент — много репозиториев
repoctl устанавливается один раз из репозитория .repoctl (этот репозиторий), а затем вызывается из любого другого репозитория, который вы хотите проверить, описать или подключить к стандарту. Сам .repoctl не обязан быть тем репозиторием, над которым вы сейчас работаете:
# Один раз: установить 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 один раз:
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 — всё ли корректно
repoctl validate --repo . --output json
Проверяет ops/contract.yaml и kdb/kdb.yaml: envelope, ID, типы, безопасность путей, ссылки между темами и документами, secret-shaped поля, отсутствие shell-строк в operations. Ничего не пишет. На чистом репозитории:
{
"schema": "stewardship/repoctl-result@0.1",
"command": "validate",
"outcome": "success",
"data": { "repository": "...", "valid": true },
"findings": []
}
При ошибке outcome становится "failure", findings заполняется, а процесс завершается кодом 1.
skills — поставить агентские скиллы туда, где агент их ищет
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 — что есть в каталоге репозиториев
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 — паспорт одного репозитория
repoctl describe --repo some-repo-name --output json
Возвращает нормализованный RepositoryContract — только контракт, без загрузки KDB. Полезно, чтобы быстро узнать тип, владельца и content roots репозитория, не читая ничего лишнего.
context — только нужные знания под задачу
Главная команда для агента. Вместо чтения всей документации репозитория:
repoctl context --repo . --intent domain.action --output json
Возвращает ContextBundle: подходящие темы (topics) по точному совпадению intent, связанные операции, content roots и — если передан --materialize — сами тексты нужных разделов, без остального репозитория. --budget-bytes N ограничивает объём материализованного текста; при превышении бюджета контент обрезается и в warnings появляется CONTEXT_BUDGET_TRUNCATED. Флаг --strict превращает такую усечённость (или устаревший/отсутствующий документ) в код возврата 4, а не в тихое предупреждение — используйте его, когда неполный контекст недопустим для задачи.
init — создать новый репозиторий по стандарту
Двухшаговый процесс: сначала план, затем — только после ревью — применение.
# Шаг 1: построить план (ничего не пишет на диск)
repoctl init --repo ../new-repo --name new-repo --type project --owner team-name --output json > plan.json
Ответы проверяются до сборки плана, чтобы 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. Прочитайте план, убедитесь, что он ожидаем.
# Шаг 2: применить план, явно подтвердив его хэш
repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256:<planHash-из-плана> --output json
--approve должен побайтово совпасть с planHash — иначе команда завершится кодом 5 (approval required/denied) и ничего не запишет. init также повторно проверяет, что ни один из планируемых файлов не появился с момента построения плана — иначе откажется перезаписывать существующее. --plan принимает как файл, сохранённый напрямую из --output json > plan.json (полный envelope с data), так и голый объект плана — repoctl сам распознаёт и разворачивает envelope.
adopt — подключить существующий репозиторий
Четыре режима, соответствующие фазам runbook (см. adoption-runbook.md):
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:<planHash> --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:
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 независимо от кодовой страницы консоли.