The tables in sections 11.1 and 11.2 were right and the code was wrong, so most of this is recording how a row is decided rather than changing the rule: format comes from validating content against the KnowledgeBase schema, never from the path a file happens to occupy. Section 13 promised thirteen verify checks and ran none of the specific ones. Rather than let the list keep implying coverage that does not exist, it now separates what L1 checks from what waits on normalization and L3, and states plainly that an unscoped report proves nothing. - document the managed-block markers, insertion point and idempotence - mark normalization and its recipes as not implemented, matching the CLI - record that migrate does not exist, which is why post-adoption edits to a contract currently fall outside plan/approve - add the finding codes introduced with the safety and verify work, and explain why a tracked secret and an ignored one are no longer the same code - PLAN.md: Antivirus is a Wave 1 pilot the owner adopts deliberately; LXD stays read-only. Normalization test row follows the feature into deferral Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
12 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 [--answers FILE] [--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] [--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:
- собирает ответы через 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 не переписывает;
- tracked secret является blocker; untracked secret-shaped paths показываются path-only без содержимого;
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используется только для read-onlyassessиplan; 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 сохраняются без изменений.