Files
repoctl/README.md
T
Alexander BaranovandClaude Opus 5 39c7da3eb1 feat(kdb-table): render a knowledge base as a table a human can read
База знаний машиночитаема и длинна: чтобы ответить «что там вообще есть»,
приходилось читать файл целиком. Теперь есть отдельный вывод для человека.

- `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>
2026-08-27 12:23:32 +03:00

5.8 KiB
Raw Blame History

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.

Ближайший практический этап

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