Files
repoctl/docs/repoctl.md
T
Alexander BaranovandClaude Opus 5 5b9c97fdcd fix(init): stop the entry point from disabling the command it reaches
A field report from bootstrapping Services/Vault: ~20 CLI calls produced
three productive writes, and four of those calls were deliberate failures
sent only to discover a vocabulary.

The worst of it was self-inflicted and new. `repoctl skills install` is the
documented way to make the bootstrap skill reachable, and it writes the
three skill files -- which `init` then reported as INIT_PATH_COLLISION and
redirected to `adopt`. Every skill-driven bootstrap of an empty repository
was pushed onto the adoption path. The collision check exists to protect
content the tool did not author, and identical bytes are nothing to
protect: a path already holding exactly what the plan would write is no
longer a collision, at plan time or at write time, while a file whose
content differs still is. `init` reports only the files it actually wrote.

`--lifecycle` advertised no choices, so its vocabulary was reachable only
by sending a wrong value and reading the refusal; it now carries `choices`
like `--type` does.

`--answers-template` prints a commented answers file naming every key, its
allowed values and its default. The answers keys are not the flag names
(`--type` sets `repositoryType`) and nothing printed the mapping. It lists
`summary` and `namespace` too, which are cheap to answer once and otherwise
survive as generated placeholders in the contract.

`--repo .` proposed the name `adopted-repository`: `Path(".").name` is the
empty string, so the ordinary way to name the current repository fell
through to the generic fallback. Resolve before deriving.

Both skills gained what the report had to discover by hand: that `--plan`
already unwraps a saved result envelope, and that sibling repositories are
where a naming convention comes from.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-26 14:56:49 +03:00

19 KiB
Raw Blame History

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:

  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 не обязан быть тем репозиторием, над которым вы сейчас работаете:

# Один раз: установить 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 — создать новый репозиторий по стандарту

Двухшаговый процесс: сначала план, затем — только после ревью — применение.

# Шаг 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. Прочитайте план, убедитесь, что он ожидаем.

# Шаг 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 независимо от кодовой страницы консоли.