Running a full assess -> plan -> apply -> verify against Infra/LXD and Infra/Docker in throwaway worktrees, and a bootstrap into a scratch directory, surfaced the same two mistakes repeated across both commands: a shape was read where evidence was available, and a missing answer became a silent default rather than a refusal. adopt: - classify secret-shaped paths by content, not by filename. A live credential blocks; a file tracked against the repository's own ignore rules and a name-only match are warnings; findings name keys, never values. In Infra/Docker this turned 14 false blockers into 2 true ones and surfaced 14 files committed despite `**/.env`. - carry assess findings into the plan and refuse while an error-severity finding is unresolved. An owner may accept one through `acknowledgedFindings` with a reason; the acknowledgement enters the plan and therefore planHash, so approval covers it. - derive metadata.name from the git remote instead of the clone directory, and refuse to plan without a confirmed owner (runbook section 9). - propose content roots from the whole content vocabulary rather than the winning type's markers, and recognise N sibling directories sharing a marker file as one file-set root with a selector, as runbook 7.2 already specified. Authority defaulted rather than derived now asks. init: apply the guards adopt already had. Answers are validated against the vocabularies that already existed in constants (name, type, lifecycle, access) so init can no longer create a repository that fails its own validate; owners are required; a directory that already holds the planned paths is refused at plan time and pointed at adopt; and every path from a plan is confined before the first byte is written -- init wrote outside the repository from an edited plan. validate: mask fenced blocks and inline code spans before scanning for Markdown links. A PowerShell snippet in Infra/Docker's CLAUDE.md parsed as a link and kept validate red for a reason unrelated to the repository. paths: allow "." as a whole content-root path, never as a segment, so the file-set root runbook 7.2 describes can be declared. 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 поверх той же модели.