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>
121 lines
12 KiB
Markdown
121 lines
12 KiB
Markdown
# Реализация 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 отложены вместе с самой 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 сохраняются без изменений.
|