Files
repoctl/docs/PLAN.md
T

12 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 [--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 даёт exit 4.
  • Для хешей ресурсов используется 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.yaml adapter;
  • если 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/ и root kdb.yaml.
  • Antivirus fixture сохраняет custom kdb/kdb.yaml и предлагает ops/knowledge.yaml.
  • Normalization tests покрывают exclusions, case-insensitive collisions, reference rewrites и rollback.
  • Самопроверка: repoctl validate --repo ., unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
  • Реальные Infra/LXD и Services/Antivirus используются только для read-only assess и plan; Git status до и после должен совпасть. Никакие планы к ним не применяются.

Зафиксированные ограничения

  • Версия пакета и шаблонов начинается с 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 сохраняются без изменений.