Files
repoctl/docs/PLAN.md
T
Alexander BaranovandClaude Opus 5 1974155281 docs: align the runbook with what adoption actually does
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>
2026-08-24 18:52:43 +03:00

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 отложены вместе с самой normalization: --strategy normalize и recipes не реализованы и не предлагаются CLI.
  • Самопроверка: repoctl validate --repo ., unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
  • Infra/LXD используется только для read-only assess и 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 сохраняются без изменений.