# Repository Stewardship Этот репозиторий разрабатывает стандарт и будущий инструментарий для единообразной работы с Git-репозиториями при помощи людей и любых AI-агентов. Основная идея: каждый репозиторий сам сообщает, что он содержит, где лежит его реальный результат, какие знания нужны для конкретной задачи и какие действия допустимы. Claude является основным агентом, но модель не зависит от Claude, LLM, skill format или MCP. ## Текущее состояние Реализация достигла уровня совместимости `L1`: CLI `repoctl` (`repository-stewardship` Python-пакет, модуль `stewardship`) реализует `validate`, `discover`, `describe`, `context`, `init` и `adopt` как read-only-by-default команды с plan-then-apply approval для любых записей. `ops/handlers/`, execution runner и MCP server остаются отложенными: этот репозиторий не объявляет ни одной executable operation. | Точка входа | Назначение | |---|---| | `ops/contract.yaml` | машиночитаемый паспорт этого репозитория | | `kdb/kdb.yaml` | маршрутизация знаний по intent | | `CLAUDE.md` | основная точка входа Claude | | `AGENTS.md` | переносимые инструкции для агентов | | `docs/specification.md` | нормативная спецификация | | `docs/guide.md` | объяснение модели для человека | | `docs/adoption-runbook.md` | перевод существующих репозиториев на стандарт | | `docs/repoctl.md` | руководство по `repoctl` для человека: установка, команды, коды возврата | | `docs/research/` | исходные архитектурные исследования | | `src/stewardship/` | реализация `repoctl` (модели, schemas, CLI) | | `src/stewardship/schemas/` | JSON Schemas (Draft 2020-12) для всех kinds | | `tests/` | unit pytest-набор (позитивные, негативные, adoption fixtures) | | `tests-universal/` | spec-driven CLI-контрактный набор, независимый от реализации | | `.claude/skills/` | три тонких Claude skill-адаптера над `repoctl` | ### Установка и запуск ```bash uv sync uv run repoctl validate --repo . uv run pytest uv run pytest tests-universal ``` `uv sync` создаёт `.venv` в корне репозитория; все команды выполняются через `uv run`. `tests-universal` — отдельный набор: он вызывает `repoctl` только как внешний процесс и сверяется исключительно с `docs/specification.md`, поэтому им можно проверить любую совместимую реализацию, а не только эту. Практическое руководство по самому CLI — в [docs/repoctl.md](docs/repoctl.md). ## Как пользоваться содержимым ```mermaid flowchart LR TASK["Задача"] --> CONTRACT["ops/contract.yaml"] CONTRACT --> KDB["kdb/kdb.yaml"] KDB --> TOPIC["Тема по exact intent"] TOPIC --> SECTIONS["Только нужные документы и разделы"] SECTIONS --> RESULT["Решение или proposed change"] ``` Для понимания модели начните с [руководства](docs/guide.md). Для реализации форматов используйте [спецификацию](docs/specification.md). Для подключения существующего репозитория следуйте [adoption runbook](docs/adoption-runbook.md). ## Почему структура минимальна Репозиторий применяет собственную концепцию без декоративной унификации: - действующие документы собраны в одном content root `docs/`, а исходное исследование отделено в `docs/research/`; - `src/`, `src/stewardship/schemas/` и `.claude/skills/` появились только тогда, когда за ними встал реальный код; - `ops/handlers/` по-прежнему не создан: этот репозиторий не объявляет ни одной executable operation, поэтому L2 handler ABI остаётся отложенным; - template lineage не записан, потому что этот repository не был создан из готового versioned template; - Plan/RunEvidence (L3), MCP server и catalog daemon намеренно не реализованы — см. "Зафиксированные ограничения" в [PLAN.md](docs/PLAN.md). ## Ближайший практический этап 1. Провести реальные `assess`/`plan` pilots для `Infra/LXD` и `Services/Antivirus` (read-only, без `apply`). 2. Собрать метрики time-to-context на нескольких повторяемых сценариях (см. guide.md, раздел 19). 3. Зафиксировать L2 handler ABI и только затем добавить `inspect`/`diff`/`plan`/`verify`/`apply` operations. 4. Только после L2 рассматривать MCP adapter поверх той же модели.