Alexander BaranovandClaude Sonnet 5 96d4d08230 feat: implement repoctl L1 core (models, schemas, validate, discover, context, init, adopt)
Adds the repository-stewardship Python package (src/stewardship) with:
- JSON Schemas (Draft 2020-12) for RepositoryContract, KnowledgeBase, CatalogIndex,
  ContextBundle, BootstrapPlan, AdoptionAssessment/Plan/Report, user config and the
  repoctl-result envelope.
- Safe YAML I/O, path confinement, deterministic clock and canonical-JSON hashing.
- validate: schema, ID uniqueness, path safety, KDB references, freshness, secret-shaped
  fields, shell-string detection, and Markdown frontmatter/fence/link checks.
- discover/CatalogIndex with deterministic sorting and duplicate-name detection.
- describe (contract-only) and context (intent-scoped ContextBundle with budgeted
  materialization and --strict truncation).
- init: plan-then-apply bootstrap with SHA-256 plan-hash approval, no fake domain
  artifacts, bundled Claude skills.
- adopt: assess/plan/apply/verify overlay workflow per docs/adoption-runbook.md,
  preserving legacy content roots and KDB, with baseline-hash re-check and rollback.
- argparse-based `repoctl` CLI with human/yaml/json output and spec exit codes.
- pytest suite (39 tests) covering positive/negative fixtures, discovery, context,
  bootstrap and adoption (including LXD- and Antivirus-shaped legacy layouts).

Managed with uv (.venv), ruff clean, mypy --strict clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-24 14:57:34 +03:00

Repository Stewardship

Этот репозиторий разрабатывает стандарт и будущий инструментарий для единообразной работы с Git-репозиториями при помощи людей и любых AI-агентов.

Основная идея: каждый репозиторий сам сообщает, что он содержит, где лежит его реальный результат, какие знания нужны для конкретной задачи и какие действия допустимы. Claude является основным агентом, но модель не зависит от Claude, LLM, skill format или MCP.

Текущее состояние

Сейчас здесь находятся спецификация, руководство и adoption runbook. CLI repoctl, handlers и MCP server ещё не реализованы; команды в документации определяют целевой интерфейс.

Точка входа Назначение
ops/contract.yaml машиночитаемый паспорт этого репозитория
kdb/kdb.yaml маршрутизация знаний по intent
CLAUDE.md основная точка входа Claude
AGENTS.md переносимые инструкции для агентов
docs/specification.md нормативная спецификация
docs/guide.md объяснение модели для человека
docs/adoption-runbook.md перевод существующих репозиториев на стандарт
docs/research/ исходные архитектурные исследования

Как пользоваться содержимым

flowchart LR
    TASK["Задача"] --> CONTRACT["ops/contract.yaml"]
    CONTRACT --> KDB["kdb/kdb.yaml"]
    KDB --> TOPIC["Тема по exact intent"]
    TOPIC --> SECTIONS["Только нужные документы и разделы"]
    SECTIONS --> RESULT["Решение или proposed change"]

Для понимания модели начните с руководства. Для реализации форматов используйте спецификацию. Для подключения существующего репозитория следуйте adoption runbook.

Почему структура минимальна

Репозиторий применяет собственную концепцию без декоративной унификации:

  • действующие документы собраны в одном content root docs/, а исходное исследование отделено в docs/research/;
  • не созданы пустые templates/, schemas/, src/ или ops/handlers/;
  • не объявлены исполняемые operations, поскольку handlers ещё отсутствуют;
  • template lineage не записан, потому что этот repository не был создан из готового versioned template;
  • будущий код добавит собственный content root тогда, когда он действительно появится.

Ближайший практический этап

  1. Зафиксировать schemas и fixtures четырёх типов репозиториев.
  2. Реализовать read-only validate, discover, describe и context.
  3. Выполнить plan-only adoption для Infra/LXD и Services/Antivirus.
  4. После пилотов реализовать init, adopt и тонкий Claude skill.
S
Description
No description provided
Readme
562 KiB
Languages
Python 100%