The rule that a knowledge file's format comes from validating it, never from the path it occupies, was applied to `kdb/kdb.yaml` and stopped there. The first branch of _plan_knowledge declared `ops/knowledge.yaml` the entrypoint without ever looking at its assessed action, so a repository holding a non-conformant file at the adapter path was adopted with the contract pointing straight at something that fails the KnowledgeBase schema -- the same defect, one path over, with the same consequence: it surfaces only at verify and gets repaired by hand outside the approved plan hash. assess had the answer all along and build_plan discarded it. Choosing the free canonical slot makes several legacy sources reachable at once, so the generated index registers all of them rather than the first; indexing one and dropping the rest in silence would be a new instance of the omission runbook 11.1 exists to prevent. That also implements the table's last row, which had no branch until now. When both canonical paths hold non-conformant files there is no free slot and neither occupant may be overwritten, so adoption refuses to plan. The plan schema is closed and carries no findings field, which leaves nowhere to record a decision left unresolved -- the same reason malformed markers raise instead of being guessed at. - gate the adapter branch on the assessed action, not on the file existing - give each indexed document an id derived from its own path - add ADOPT_KNOWLEDGE_UNRESOLVED for the dead end, and document it - bind the four previously untested rows of 11.1 to the parametrized table 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 поверх той же модели.