Running a full assess -> plan -> apply -> verify against Infra/LXD and Infra/Docker in throwaway worktrees, and a bootstrap into a scratch directory, surfaced the same two mistakes repeated across both commands: a shape was read where evidence was available, and a missing answer became a silent default rather than a refusal. adopt: - classify secret-shaped paths by content, not by filename. A live credential blocks; a file tracked against the repository's own ignore rules and a name-only match are warnings; findings name keys, never values. In Infra/Docker this turned 14 false blockers into 2 true ones and surfaced 14 files committed despite `**/.env`. - carry assess findings into the plan and refuse while an error-severity finding is unresolved. An owner may accept one through `acknowledgedFindings` with a reason; the acknowledgement enters the plan and therefore planHash, so approval covers it. - derive metadata.name from the git remote instead of the clone directory, and refuse to plan without a confirmed owner (runbook section 9). - propose content roots from the whole content vocabulary rather than the winning type's markers, and recognise N sibling directories sharing a marker file as one file-set root with a selector, as runbook 7.2 already specified. Authority defaulted rather than derived now asks. init: apply the guards adopt already had. Answers are validated against the vocabularies that already existed in constants (name, type, lifecycle, access) so init can no longer create a repository that fails its own validate; owners are required; a directory that already holds the planned paths is refused at plan time and pointed at adopt; and every path from a plan is confined before the first byte is written -- init wrote outside the repository from an edited plan. validate: mask fenced blocks and inline code spans before scanning for Markdown links. A PowerShell snippet in Infra/Docker's CLAUDE.md parsed as a link and kept validate red for a reason unrelated to the repository. paths: allow "." as a whole content-root path, never as a segment, so the file-set root runbook 7.2 describes can be declared. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
15 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.
discover — что есть в каталоге репозиториев
repoctl discover --root C:/Users/example/Git --output json
Обходит указанный каталог, находит все ops/contract.yaml, строит CatalogIndex — детерминированно отсортированный список репозиториев с их типом, lifecycle и hash контракта. Не следует по symlink, пропускает .git, .venv, node_modules и подобные. Дублирующиеся имена репозиториев — ошибка (CATALOG_REPOSITORY_DUPLICATE).
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 независимо от кодовой страницы консоли.