docs: baseline specification-only repository stewardship

This commit is contained in:
Alexander Baranov
2026-08-24 14:39:09 +03:00
commit 9a39b8a941
11 changed files with 4191 additions and 0 deletions
+119
View File
@@ -0,0 +1,119 @@
# Реализация 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 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](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 покрывают 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 сохраняются без изменений.