База знаний машиночитаема и длинна: чтобы ответить «что там вообще есть», приходилось читать файл целиком. Теперь есть отдельный вывод для человека. - `stewardship.kdb_table` - модуль, а не файл рядом со скиллом: `skills install` переносит только SKILL.md, поэтому скрипт в каталоге скилла не доехал бы до репозитория, куда скилл поставили. Как модуль он доступен везде, где есть repoctl: `python -m stewardship.kdb_table --repo <path>`. - Путь к базе знаний не угадывается: берётся `spec.knowledge.entrypoint` из `ops/contract.yaml` целевого репозитория, с откатом на `kdb/kdb.yaml`. Значит работает на любом adopted-репозитории, а не только там, где путь канонический. - Репозиторий без базы знаний получает одну строку и нулевой код возврата, а не трейсбек. - Читает через `stewardship.io`, то есть тем же ruamel, что и остальной код - новой зависимости нет. - Вне командной поверхности CLI намеренно: контракт `repoctl` - машинный вывод, а это пособие для чтения. Спецификацию менять не пришлось. Скилл `kdb-table` зарегистрирован в SKILLS, поэтому расходится штатным `repoctl skills install` вместе с остальными тремя. Он тонкий: зовёт модуль, печатает markdown как есть и отправляет за контекстом под задачу в `repoctl context --intent`. Проверено: 156 тестов, mypy strict чист, validate на самом репозитории success. Два новых теста закрепляют чтение entrypoint из контракта (включая нестандартный путь) и внятный отказ при отсутствии базы. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.8 KiB
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 |
Установка и запуск
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.
Как пользоваться содержимым
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/; 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.
Ближайший практический этап
- Провести реальные
assess/planpilots дляInfra/LXDиServices/Antivirus(read-only, безapply). - Собрать метрики time-to-context на нескольких повторяемых сценариях (см. guide.md, раздел 19).
- Зафиксировать L2 handler ABI и только затем добавить
inspect/diff/plan/verify/applyoperations. - Только после L2 рассматривать MCP adapter поверх той же модели.