База знаний машиночитаема и длинна: чтобы ответить «что там вообще есть», приходилось читать файл целиком. Теперь есть отдельный вывод для человека. - `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>
72 lines
5.8 KiB
Markdown
72 lines
5.8 KiB
Markdown
# 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` |
|
||
|
||
### Установка и запуск
|
||
|
||
```bash
|
||
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](docs/repoctl.md).
|
||
|
||
## Как пользоваться содержимым
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
TASK["Задача"] --> CONTRACT["ops/contract.yaml"]
|
||
CONTRACT --> KDB["kdb/kdb.yaml"]
|
||
KDB --> TOPIC["Тема по exact intent"]
|
||
TOPIC --> SECTIONS["Только нужные документы и разделы"]
|
||
SECTIONS --> RESULT["Решение или proposed change"]
|
||
```
|
||
|
||
Для понимания модели начните с [руководства](docs/guide.md). Для реализации форматов используйте [спецификацию](docs/specification.md). Для подключения существующего репозитория следуйте [adoption runbook](docs/adoption-runbook.md).
|
||
|
||
## Почему структура минимальна
|
||
|
||
Репозиторий применяет собственную концепцию без декоративной унификации:
|
||
|
||
- действующие документы собраны в одном 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](docs/PLAN.md).
|
||
|
||
## Ближайший практический этап
|
||
|
||
1. Провести реальные `assess`/`plan` pilots для `Infra/LXD` и `Services/Antivirus` (read-only, без `apply`).
|
||
2. Собрать метрики time-to-context на нескольких повторяемых сценариях (см. guide.md, раздел 19).
|
||
3. Зафиксировать L2 handler ABI и только затем добавить `inspect`/`diff`/`plan`/`verify`/`apply` operations.
|
||
4. Только после L2 рассматривать MCP adapter поверх той же модели.
|