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>
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 поверх той же модели.