Files
repoctl/docs/PLAN.md
T
Alexander BaranovandClaude Opus 5 c21ffceef3 fix(discover): a contract inside another repository is not a repository
`tests/fixtures/positive/` holds four valid contracts. Running `discover`
over the machine's Git directory returned six repositories: two real ones
and those four, with nothing in the output to tell them apart. Any
catalog-wide question -- which repositories lack an owner, which are
behind the template version -- was answered over a set that included this
project's own test material.

A repository is the root of a git repository. A directory holding
ops/contract.yaml somewhere inside another repository's working tree is
that repository's content: a fixture, an example, a vendored copy. Skip
it, and say so with CATALOG_NESTED_CONTRACT_SKIPPED rather than silently,
so a genuinely misplaced contract is still visible.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 18:17:11 +03:00

14 KiB
Raw Blame History

Реализация 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 из спецификации: 0 success, 1 validation failure, 2 invalid input, 3 repository not found, 4 incomplete/stale strict context, 5 approval 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, не считает репозиторием контракт, лежащий внутри рабочего дерева другого репозитория (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/<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/ и 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 сохраняются без изменений.