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>
14 KiB
Реализация Repository Stewardship и repoctl L1
Результат
В этом репозитории появится рабочий кроссплатформенный CLI repoctl, который станет единым интерфейсом для людей, Claude и других агентов:
- обнаруживает и описывает репозитории;
- валидирует contract, KDB, пути и документацию;
- выдаёт минимальный контекст по intent;
- создаёт новые репозитории;
- безопасно подключает существующие;
- строит каталог и связи между репозиториями;
- не выполняет инфраструктурные операции и не обращается к внешним системам.
Реализация — Python 3.11+, управление через uv, пакет repository-stewardship, модуль stewardship, команда repoctl. Используются ruamel.yaml для безопасного YAML и сохранения форматирования, jsonschema Draft 2020-12 для публичных схем и стандартный argparse без тяжёлого CLI-фреймворка. Структура src/ и uv_build соответствует рекомендациям uv.
Архитектура и публичные интерфейсы
- Разделить код на независимые слои: модели и схемы, безопасный I/O, validation, discovery/catalog, context selection, bootstrap, adoption, CLI rendering. CLI остаётся тонким адаптером; эти же функции позднее сможет вызвать MCP server.
- Хранить versioned schemas и шаблоны как package resources, доступные и из исходников, и из установленного wheel.
- Добавить JSON Schemas для:
RepositoryContract,KnowledgeBase,CatalogIndex,ContextBundle;BootstrapPlan;AdoptionAssessment,AdoptionPlan,AdoptionReport;- пользовательской конфигурации и общего результата CLI.
- Ввести стабильный machine-output envelope
stewardship/repoctl-result@0.1с полямиcommand,outcome,data,findings. Вdataостаётся соответствующий protocol resource. - Все команды поддерживают
--output human|yaml|json. Machine output идёт только в stdout, диагностика процесса — в stderr. - Неизвестные нормативные поля отклоняются;
x-*,metadata.annotations, открытые content roles и domain data сохраняются. - Зафиксировать exit codes из спецификации:
0success,1validation failure,2invalid input,3repository not found,4incomplete/stale strict context,5approval failure.
Командный интерфейс:
repoctl config show|add-root|remove-root
repoctl validate [--repo PATH]
repoctl discover [--root PATH ...]
repoctl describe --repo NAME|PATH [--root PATH ...]
repoctl context --repo NAME|PATH --intent INTENT
[--include-related] [--materialize]
[--budget-bytes N] [--strict]
repoctl init --repo PATH --name NAME --type TYPE --owner NAME
[--answers FILE] [--title T] [--lifecycle L]
[--git-init|--no-git-init]
repoctl init --repo PATH --apply --plan FILE --approve SHA256
repoctl adopt --repo PATH --mode assess|plan|apply|verify
[--answers FILE] [--owner NAME] [--type TYPE]
[--strategy overlay|normalize]
[--recipe ID] [--plan FILE] [--approve SHA256]
Разрешение имени репозитория выполняется в порядке: явные --root → REPOCTL_ROOTS → пользовательский config → текущий repository. Config хранится в %APPDATA%\RepositoryStewardship\config.yaml на Windows и в XDG config directory на Unix. Его изменение выполняется только явными config add-root/remove-root; скрытый cache по умолчанию не создаётся.
Поведение инструментов
validateпроверяет schemas, IDs, ссылки, content roots, path/symlink confinement, freshness, provenance, secret-shaped поля, operations без shell strings, Markdown links/frontmatter/YAML fences, сбалансированные code fences и статический синтаксис Mermaid.discoverищетops/contract.yaml, не следует по symlink/junction, пропускает.git, virtual environments и dependency caches, строит детерминированныйCatalogIndex, capability/requirement/binding relations и выявляет дубликаты repository ID.describeчитает только contract и никогда не загружает KDB.contextпо умолчанию возвращает компактный bundle: topic data, document metadata, selectors/headings, operations и content roots.--materializeизвлекает только явно выбранные Markdown-разделы или ограниченные YAML key paths; сеть не используется.- Budget считается в UTF-8 bytes только для materialized content. Элементы сортируются детерминированно; усечение всегда отражается warning и при
--strictдаёт exit4. - Для хешей ресурсов используется canonical JSON representation, а не платформенные окончания строк. Время передаётся через clock abstraction, чтобы тестовые результаты были воспроизводимыми.
init проверяет ответы до сборки плана (name против ID_PATTERN, type/lifecycle/access против enum, обязательный owner), отказывается планировать в каталог, где уже лежит любой из создаваемых путей, и confine'ит каждый путь плана при записи. Отказы — конверты с кодами INIT_*, а не строки в stderr.
init:
- собирает ответы через CLI или YAML answers file; CLI имеет приоритет;
- предлагает type-specific content roots, но не создаёт фиктивные domain artifacts;
- создаёт contract, KDB,
AGENTS.md, импортирующий егоCLAUDE.md, template answers,.gitignoreи три Claude skills; - записывает template ID/version и SHA-256 revision шаблона;
- при необходимости включает
git init, но не создаёт remote, commit или push; - выдаёт структурированную рекомендацию отдельного repository-scoped SSH key, не генерируя и не сохраняя secret;
- сначала возвращает полный
BootstrapPlan; запись возможна только по plan-файлу и его SHA-256.
adopt:
- реализует runbook
assess → plan → apply → verify; - различает detected, inferred и confirmed данные;
- фиксирует HEAD либо состояние
unborn, dirty paths и hashes всех входных/touched файлов; - по умолчанию использует overlay и сохраняет domain-native layout;
- для legacy root
kdb.yamlпредлагает небольшойkdb/kdb.yamladapter; - если legacy KDB уже занимает
kdb/kdb.yaml, предлагаетops/knowledge.yaml; - существующие skills, handlers, KDB и agent instructions не переписывает;
- secret-shaped путь классифицируется по содержимому: живой credential — blocker, tracked вопреки ignore-правилам и совпадение только по имени — warnings, untracked — info; наружу выходят имена ключей, не значения;
planтребует подтверждённого owner и отказывается строиться при неразрешённой находке severityerror; принятие находки явное, с причиной, и входит вplanHash;- имя репозитория выводится из remote, а не из имени каталога клона;
- content roots предлагаются по всему словарю содержимого; репозиторий из однотипных каталогов объявляется одним
file-setкорнем с селектором; documents-to-content-rootвыполняется только как явно выбранная normalization recipe с rename map, conservative Markdown/frontmatter/YAML rewrites и collision checks;- apply повторно проверяет baseline и plan hash, пишет только перечисленные paths, использует временные файлы и восстанавливает исходное состояние при локальной ошибке;
- никогда не делает commit, push, clone или external operation.
Claude и self-hosting
Добавить три коротких project skills:
repository-bootstrap;repository-adoption;repo-handoff.
Они размещаются в .claude/skills/<name>/SKILL.md, как предусмотрено Claude Code, и только собирают недостающие решения, вызывают repoctl с machine output и объясняют findings. Логика CLI в skills не дублируется. Те же skills входят в bootstrap templates; остальные агенты используют команды из AGENTS.md.
Сам репозиторий переводится из specification-only в l1-implemented:
- contract получает реальные content roots для исходников, schemas/templates и Claude adapters;
- KDB индексирует новую справку
repoctlи handoff intents; - README, specification, guide, adoption runbook и agent instructions обновляются под фактический CLI;
- фиктивные handlers и operations не объявляются;
- MCP, L2 handler ABI и инфраструктурный apply остаются отложенными.
Проверки и приёмка
- Fixtures четырёх repository types и отрицательные fixtures для неизвестных полей,
x-*, duplicate IDs, Windows/Unix traversal, UNC/absolute paths, symlink escape, secrets и shell strings. - Golden tests одинакового YAML/JSON output и exit codes.
- Context tests для exact intent, related topics, Markdown headings, legacy YAML selectors, stale/missing sources и byte-budget.
- Catalog tests для стабильной сортировки, hashes, duplicate repositories и capability matching.
- Init/adoption tests подтверждают отсутствие записей до approval, отказ при неверном hash или изменившемся baseline и отсутствие commit/push.
- LXD fixture сохраняет
profiles-source/,profiles/и rootkdb.yaml. - Antivirus fixture сохраняет custom
kdb/kdb.yamlи предлагаетops/knowledge.yaml. - Normalization tests отложены вместе с самой normalization:
--strategy normalizeи recipes не реализованы и не предлагаются CLI. - Самопроверка:
repoctl validate --repo ., unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates. Infra/LXDиInfra/Dockerиспользуются только для read-onlyassessиplan, либо для полного цикла в одноразовомgit worktree; Git status рабочего дерева до и после должен совпасть.Services/Antivirus— пилот Wave 1, adopted по решению владельца.applyк нему выполняется осознанно: через утверждённыйplanHash, с предварительным прогоном на копии и последующимverify --plan. Остальные реальные репозитории остаются read-only до расширения wave.
Зафиксированные ограничения
- Версия пакета и шаблонов начинается с
0.1.0; protocol остаётсяstewardship.corsus.ru/v1alpha1. - Первая версия работает только с уже доступными локальными repositories; clone по URL отложен.
- Не реализуются handlers, execution runner, внешние credentials, immutable cross-repository L3 Plan, MCP server и автоматический catalog daemon.
- Пользовательские и пилотные dirty worktrees сохраняются без изменений.