# Реализация 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](https://docs.astral.sh/uv/concepts/projects/init/). ## Архитектура и публичные интерфейсы - Разделить код на независимые слои: модели и схемы, безопасный 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 из спецификации: `0` success, `1` validation failure, `2` invalid input, `3` repository not found, `4` incomplete/stale strict context, `5` approval failure. Командный интерфейс: ```text 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 skills install --repo PATH | --global [--force] repoctl skills status --repo PATH | --global 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, не считает репозиторием контракт, лежащий внутри рабочего дерева другого репозитория (fixture, example, vendored copy — это его содержимое, а не равноправный сосед; такой путь сообщается как `CATALOG_NESTED_CONTRACT_SKIPPED`), строит детерминированный `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` даёт exit `4`. - Для хешей ресурсов используется 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.yaml` adapter; - если legacy KDB уже занимает `kdb/kdb.yaml`, предлагает `ops/knowledge.yaml`; - существующие skills, handlers, KDB и agent instructions не переписывает; - secret-shaped путь классифицируется по содержимому: живой credential — blocker, tracked вопреки ignore-правилам и совпадение только по имени — warnings, untracked — info; наружу выходят имена ключей, не значения; - `plan` требует подтверждённого owner и отказывается строиться при неразрешённой находке severity `error`; принятие находки явное, с причиной, и входит в `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//SKILL.md`, как предусмотрено [Claude Code](https://code.claude.com/docs/en/skills), и только собирают недостающие решения, вызывают `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/` и root `kdb.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-only `assess` и `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 сохраняются без изменений.