docs: baseline specification-only repository stewardship
This commit is contained in:
+934
@@ -0,0 +1,934 @@
|
||||
---
|
||||
documentId: repository-stewardship-guide
|
||||
documentVersion: 0.2.0
|
||||
status: draft
|
||||
normative: false
|
||||
language: ru
|
||||
machineSpecification: docs/specification.md
|
||||
architectureSource: docs/research/infrastructure-operations-architecture-options.md
|
||||
---
|
||||
|
||||
# Универсальная работа с репозиториями: руководство для человека
|
||||
|
||||
Модель называется **Repository Stewardship**: ответственное и долговременное ведение структуры, знаний, связей и способов работы репозитория. `repoctl` — её локальный командный интерфейс.
|
||||
|
||||
## 1. Коротко о результате
|
||||
|
||||
Каждый управляемый репозиторий получает:
|
||||
|
||||
1. короткий машиночитаемый паспорт — `ops/contract.yaml`;
|
||||
2. индекс знаний — `kdb/kdb.yaml`;
|
||||
3. явные указатели на места реального результата работы — `contentRoots`;
|
||||
4. короткие точки входа `CLAUDE.md` и `AGENTS.md`;
|
||||
5. при необходимости — собственные безопасные operations и handlers.
|
||||
|
||||
Общий инструмент `repoctl` умеет найти эти файлы, проверить их, построить каталог и передать агенту только контекст, необходимый для конкретной задачи.
|
||||
|
||||
Так получается «MCP-подобный» инструментарий без обязательного MCP server: репозитории уже предоставляют ресурсы, знания и операции через общий контракт, а CLI, Claude skills, другие агенты и будущий MCP становятся сменными интерфейсами.
|
||||
|
||||
Машинные поля и правила определены в [specification.md](specification.md). Этот документ объясняет ту же модель простым языком. Процедура подключения существующих репозиториев описана в [adoption-runbook.md](adoption-runbook.md). Исходные архитектурные варианты и исследование сохранены в [research/infrastructure-operations-architecture-options.md](research/infrastructure-operations-architecture-options.md).
|
||||
|
||||
## 2. Главные принципы
|
||||
|
||||
### 2.1. Репозиторий сам описывает себя
|
||||
|
||||
Центральная база не должна вручную хранить копии сведений обо всех репозиториях. Каждый repository contract находится рядом с материалами, которые он описывает. Центральный каталог можно полностью перестроить.
|
||||
|
||||
### 2.2. Одинаков интерфейс, а не физическое дерево
|
||||
|
||||
LXD profiles могут оставаться в `profiles-source/`, Docker stacks — в каталогах стеков, код — в `src/`, а проектные результаты — в `deliverables/`.
|
||||
|
||||
Контракт просто называет эти места и объясняет их роль. Агент больше не выясняет структуру заново, но репозитории не ломаются ради искусственной унификации.
|
||||
|
||||
### 2.3. Знание загружается по задаче
|
||||
|
||||
`CLAUDE.md` не превращается в энциклопедию. Пользовательская задача преобразуется в intent, например `container.deploy`. По intent выбираются только связанные темы KDB, документы, content roots и operations.
|
||||
|
||||
### 2.4. Потребитель формулирует потребность, провайдер реализует её
|
||||
|
||||
Antivirus знает, какой сервис ему нужен и как проверить его работу. LXD знает, как создать контейнер. Network знает, как предоставить сеть. Ни один из них не должен копировать authoritative configuration другого.
|
||||
|
||||
### 2.5. Сначала безопасная семантика, затем выполнение
|
||||
|
||||
Первая версия только обнаруживает, валидирует и выдаёт контекст. Затем добавляются единый handler protocol, Plan, approval, apply и evidence. MCP появляется последним как транспорт над уже проверенной моделью.
|
||||
|
||||
## 3. Общая архитектура
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U["Пользователь"] --> A["Claude или другой AI-агент"]
|
||||
A --> E["CLAUDE.md / AGENTS.md / skill"]
|
||||
E --> R["repoctl"]
|
||||
|
||||
R --> C["RepositoryContract"]
|
||||
R --> K["KnowledgeBase"]
|
||||
R --> G["Производный CatalogIndex"]
|
||||
|
||||
C --> CR["contentRoots"]
|
||||
C --> O["operations"]
|
||||
C --> REL["requirements / capabilities / bindings"]
|
||||
K --> T["topics по intent"]
|
||||
T --> D["Markdown и vendor sources"]
|
||||
|
||||
O -. "после L2" .-> H["Repo-local handlers"]
|
||||
H -. "domain API/CLI" .-> X["LXD / Docker / AD / Network / Monitoring"]
|
||||
|
||||
R -. "после L3" .-> P["Plan / approval / RunEvidence"]
|
||||
R -. "опционально" .-> M["MCP adapter"]
|
||||
```
|
||||
|
||||
Важное разделение:
|
||||
|
||||
- contract и KDB принадлежат репозиторию;
|
||||
- catalog и context bundle вычисляются `repoctl`;
|
||||
- handler принадлежит своему техническому домену;
|
||||
- skill и MCP только помогают вызвать тот же интерфейс.
|
||||
|
||||
## 4. Минимальная структура репозитория
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
ROOT["repository root"] --> CONTRACT["ops/contract.yaml"]
|
||||
ROOT --> KDB["kdb/kdb.yaml"]
|
||||
ROOT --> AGENTS["AGENTS.md"]
|
||||
ROOT --> CLAUDE["CLAUDE.md"]
|
||||
ROOT --> DOCS["docs/"]
|
||||
ROOT --> OPS["ops/"]
|
||||
ROOT --> DOMAIN["domain-native content"]
|
||||
|
||||
OPS --> HANDLERS["handlers/ — после L2"]
|
||||
OPS --> SCHEMAS["schemas/ — по необходимости"]
|
||||
OPS --> RUNS["runs/ — локальные планы и evidence"]
|
||||
|
||||
DOMAIN --> EX1["profiles-source/"]
|
||||
DOMAIN --> EX2["stacks/"]
|
||||
DOMAIN --> EX3["src/"]
|
||||
DOMAIN --> EX4["deliverables/"]
|
||||
```
|
||||
|
||||
Обязательная часть проста:
|
||||
|
||||
- `ops/contract.yaml` — паспорт;
|
||||
- `kdb/kdb.yaml` — индекс знаний;
|
||||
- `AGENTS.md` — переносимые инструкции;
|
||||
- `CLAUDE.md` — вход для основного агента Claude.
|
||||
|
||||
Остальные каталоги создаются только при реальной необходимости.
|
||||
|
||||
## 5. Четыре типа репозиториев
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
R["Repository"] --> I["Infrastructure configuration"]
|
||||
R --> S["Service configuration"]
|
||||
R --> C["Software / code"]
|
||||
R --> P["Project / non-code"]
|
||||
|
||||
I --> I1["desired state"]
|
||||
I --> I2["inventory / profiles / stacks"]
|
||||
I --> I3["observed state / evidence"]
|
||||
|
||||
S --> S1["service definition"]
|
||||
S --> S2["policies / requirements"]
|
||||
S --> S3["acceptance / runbooks"]
|
||||
|
||||
C --> C1["source"]
|
||||
C --> C2["tests / build"]
|
||||
C --> C3["packages / deployment"]
|
||||
|
||||
P --> P1["deliverables"]
|
||||
P --> P2["sources / working"]
|
||||
P --> P3["decisions / archive"]
|
||||
```
|
||||
|
||||
| Тип | За что отвечает | Что особенно важно |
|
||||
|---|---|---|
|
||||
| Infrastructure configuration | контейнеры, сеть, серверы, платформенная конфигурация | разделить desired и observed state; иметь diff/plan/verify |
|
||||
| Service configuration | продуктовая конфигурация и правила эксплуатации сервиса | владеть requirements и acceptance, не копировать provider configuration |
|
||||
| Software/code | исходники, тесты, сборка и выпуск | следовать conventions своего ecosystem, явно отделить deployment artifacts |
|
||||
| Project/non-code | документы, исследования, планы и результаты | явно назвать deliverables, sources и decisions |
|
||||
|
||||
Организационный путь, уровень доступа и lifecycle не определяют тип. Например, репозиторий в `Services/` может содержать software, а архивный инфраструктурный repository остаётся типом `infrastructure-config`.
|
||||
|
||||
## 6. Карта сущностей
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
REPOSITORY ||--|| REPOSITORY_CONTRACT : publishes
|
||||
REPOSITORY ||--o| KNOWLEDGE_BASE : owns
|
||||
REPOSITORY_CONTRACT ||--o{ CONTENT_ROOT : declares
|
||||
REPOSITORY_CONTRACT ||--o{ OPERATION : exposes
|
||||
REPOSITORY_CONTRACT ||--o{ CAPABILITY : provides
|
||||
REPOSITORY_CONTRACT ||--o{ REQUIREMENT : requires
|
||||
REPOSITORY_CONTRACT ||--o{ BINDING : records
|
||||
KNOWLEDGE_BASE ||--o{ TOPIC : routes
|
||||
KNOWLEDGE_BASE ||--o{ KNOWLEDGE_DOCUMENT : indexes
|
||||
TOPIC }o--o{ KNOWLEDGE_DOCUMENT : selects
|
||||
REQUIREMENT }o--o{ CAPABILITY : matches
|
||||
BINDING }o--|| REQUIREMENT : fulfills
|
||||
OPERATION ||--o| HANDLER : implemented_by
|
||||
INTENT }o--o{ TOPIC : selects
|
||||
INTENT }o--o{ OPERATION : selects
|
||||
PLAN ||--o{ OPERATION : orders
|
||||
RUN_EVIDENCE }o--|| PLAN : proves
|
||||
```
|
||||
|
||||
Дальше сущности объясняются в том порядке, в котором они встречаются при работе.
|
||||
|
||||
## 7. Сущности: от входа в репозиторий до понимания задачи
|
||||
|
||||
### 7.1. Репозиторий
|
||||
|
||||
Отдельная область ответственности и отдельный источник истины.
|
||||
|
||||
Примеры:
|
||||
|
||||
- `Infra/LXD` отвечает за контейнеры и LXD profiles;
|
||||
- `Services/Antivirus` отвечает за требования и правила приёмки антивируса;
|
||||
- software repository отвечает за код;
|
||||
- project repository отвечает за результаты проекта.
|
||||
|
||||
### 7.2. RepositoryContract
|
||||
|
||||
Короткий машиночитаемый паспорт репозитория в `ops/contract.yaml`.
|
||||
|
||||
Он отвечает на вопросы:
|
||||
|
||||
- что это за репозиторий;
|
||||
- кто его владелец;
|
||||
- где лежит результат работы;
|
||||
- что он предоставляет и что требует;
|
||||
- какие операции публично разрешены;
|
||||
- где находится его KDB.
|
||||
|
||||
Контракт не заменяет документацию. Это оглавление, интерфейс и граница ответственности.
|
||||
|
||||
### 7.3. Metadata
|
||||
|
||||
Стабильное имя, отображаемое название, владельцы, labels и annotations.
|
||||
|
||||
Стабильное имя вроде `infra-lxd` важнее физического пути. Репозиторий можно переместить, не меняя ссылки в requirements и bindings.
|
||||
|
||||
### 7.4. Repository type
|
||||
|
||||
Один из четырёх функциональных типов. Он определяет хорошие практики организации, но не заставляет использовать одно дерево каталогов.
|
||||
|
||||
### 7.5. Lifecycle
|
||||
|
||||
Текущее состояние репозитория:
|
||||
|
||||
- `production`;
|
||||
- `active`;
|
||||
- `experimental`;
|
||||
- `stub`;
|
||||
- `archive`;
|
||||
- `external`.
|
||||
|
||||
Lifecycle помогает агенту не принять эксперимент или архив за production source.
|
||||
|
||||
### 7.6. ContentRoot
|
||||
|
||||
Явный указатель на место, где лежит настоящий результат работы.
|
||||
|
||||
Content root имеет:
|
||||
|
||||
- стабильный ID;
|
||||
- роль;
|
||||
- путь;
|
||||
- природу данных (`authority`);
|
||||
- политику записи;
|
||||
- при необходимости selector.
|
||||
|
||||
Например, `profiles-source/` может быть source, а `profiles/` — generated mirror. Оба содержат YAML, но обращаться с ними нужно по-разному.
|
||||
|
||||
### 7.7. Authority
|
||||
|
||||
Объясняет природу содержимого:
|
||||
|
||||
- `source` — первоисточник;
|
||||
- `generated` — автоматически созданное;
|
||||
- `observed` — полученное из runtime;
|
||||
- `mirror` — копия другого источника;
|
||||
- `evidence` — историческое доказательство.
|
||||
|
||||
## 8. Сущности: от пользовательского запроса до нужного знания
|
||||
|
||||
### 8.1. Intent
|
||||
|
||||
Краткое имя цели пользователя, а не техническая команда.
|
||||
|
||||
Например, запрос:
|
||||
|
||||
> Разверни новый контейнер LXD для антивируса.
|
||||
|
||||
преобразуется в intent:
|
||||
|
||||
```text
|
||||
container.deploy
|
||||
```
|
||||
|
||||
Intent помогает выбрать репозитории, темы KDB и операции. В нём нет hostname, пароля или shell-команды.
|
||||
|
||||
### 8.2. CatalogIndex
|
||||
|
||||
Производная телефонная книга репозиториев.
|
||||
|
||||
Она позволяет найти:
|
||||
|
||||
- какой repository предоставляет LXD containers;
|
||||
- где находится Antivirus;
|
||||
- какие requirements ещё не имеют bindings;
|
||||
- какие repositories являются архивными.
|
||||
|
||||
Каталог можно удалить и пересобрать из contracts.
|
||||
|
||||
### 8.3. Entity и relation
|
||||
|
||||
Entity — объект каталога: repository, capability, requirement, binding или operation.
|
||||
|
||||
Relation — связь между объектами:
|
||||
|
||||
```text
|
||||
Antivirus requires LXD container
|
||||
LXD provides LXD container
|
||||
Binding fulfills Antivirus requirement
|
||||
```
|
||||
|
||||
Совокупность relations образует граф, по которому агент переходит между репозиториями без угадывания путей.
|
||||
|
||||
### 8.4. KnowledgeBase
|
||||
|
||||
Машиночитаемый индекс знаний в `kdb/kdb.yaml`.
|
||||
|
||||
KDB не обязана содержать весь текст. Она хранит:
|
||||
|
||||
- темы;
|
||||
- соответствующие intents;
|
||||
- машиночитаемые constraints и facts;
|
||||
- ссылки на Markdown;
|
||||
- сведения о vendor sources;
|
||||
- provenance и freshness.
|
||||
|
||||
### 8.5. Topic
|
||||
|
||||
Тематический маршрут знаний.
|
||||
|
||||
Например:
|
||||
|
||||
- `container-deployment`;
|
||||
- `network-attachment`;
|
||||
- `profile-management`;
|
||||
- `backup-and-restore`.
|
||||
|
||||
Для `container.deploy` агент получает первые нужные темы, но не читает всю документацию про backup, clustering и обновление платформы.
|
||||
|
||||
### 8.6. KnowledgeDocument
|
||||
|
||||
Конкретный Markdown, YAML, PDF, HTML snapshot, runbook или внешний URL.
|
||||
|
||||
Один документ может использоваться несколькими topics. Поэтому documents хранятся единым реестром, а topics ссылаются на их IDs.
|
||||
|
||||
### 8.7. Provenance
|
||||
|
||||
Ответ на вопрос «откуда это известно»:
|
||||
|
||||
- исходный URL;
|
||||
- vendor;
|
||||
- версия;
|
||||
- дата получения;
|
||||
- hash локальной копии;
|
||||
- способ проверки.
|
||||
|
||||
Provenance отделяет официальную vendor information от локального правила и от наблюдаемого runtime fact.
|
||||
|
||||
### 8.8. Freshness
|
||||
|
||||
Ответ на вопрос «можно ли ещё доверять этим данным».
|
||||
|
||||
Если срок проверки истёк, информация не удаляется. Она помечается stale, а агент перед важным действием должен обновить или проверить её.
|
||||
|
||||
### 8.9. ContextBundle
|
||||
|
||||
Минимальный пакет контекста, который `repoctl` сформировал для одного intent.
|
||||
|
||||
Он содержит только:
|
||||
|
||||
- краткое описание contract;
|
||||
- нужные content roots;
|
||||
- подходящие operations;
|
||||
- выбранные topics и documents;
|
||||
- warnings о stale или missing information.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Q["Запрос пользователя"] --> I["Intent"]
|
||||
I --> C["Contract operations"]
|
||||
I --> T["KDB topics"]
|
||||
C --> B["ContextBundle"]
|
||||
T --> B
|
||||
B --> A["Небольшой контекст агента"]
|
||||
|
||||
ALL["Весь репозиторий и вся KDB"] -. "не загружаются" .-> A
|
||||
```
|
||||
|
||||
Это основной механизм экономии времени и токенов.
|
||||
|
||||
## 9. Сущности: взаимодействие репозиториев
|
||||
|
||||
### 9.1. Consumer
|
||||
|
||||
Репозиторий, которому что-то нужно.
|
||||
|
||||
В примере с антивирусом consumer — `Services/Antivirus`. Он знает требования продукта и критерии успешности.
|
||||
|
||||
### 9.2. Provider
|
||||
|
||||
Репозиторий, предоставляющий техническую возможность.
|
||||
|
||||
В примере:
|
||||
|
||||
- LXD предоставляет контейнер;
|
||||
- Network предоставляет сетевое подключение;
|
||||
- Monitoring предоставляет наблюдаемость.
|
||||
|
||||
### 9.3. Capability
|
||||
|
||||
Тип возможности провайдера.
|
||||
|
||||
Пример: `compute.lxd-container` означает «этот repository умеет предоставлять управляемые LXD containers». Это ещё не конкретный контейнер.
|
||||
|
||||
### 9.4. Requirement
|
||||
|
||||
Потребность consumer repository.
|
||||
|
||||
Antivirus может потребовать:
|
||||
|
||||
- 4 CPU;
|
||||
- 8 GiB memory;
|
||||
- подключение к services network;
|
||||
- определённые acceptance operations.
|
||||
|
||||
Requirement принадлежит Antivirus, потому что LXD не должен угадывать потребности продукта.
|
||||
|
||||
### 9.5. Binding
|
||||
|
||||
Связь requirement с конкретным реализованным ресурсом.
|
||||
|
||||
Например:
|
||||
|
||||
```text
|
||||
Antivirus requirement
|
||||
→ lxd://drweb/dwcp
|
||||
```
|
||||
|
||||
Binding принадлежит provider repository. Он появляется после выбора или создания target и становится active только после verification и acceptance.
|
||||
|
||||
### 9.6. Acceptance
|
||||
|
||||
Проверки, доказывающие, что задача consumer решена.
|
||||
|
||||
LXD может подтвердить, что контейнер запущен и имеет правильный профиль. Только Antivirus может подтвердить, что базы обновляются и control plane действительно работает.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S["Service consumer"] --> R["Requirement"]
|
||||
P["Infrastructure provider"] --> C["Capability"]
|
||||
R --> M{"Совместимы?"}
|
||||
C --> M
|
||||
M -->|"да"| B["Binding to concrete target"]
|
||||
B --> V["Provider verification"]
|
||||
V --> A["Consumer acceptance"]
|
||||
A -->|"успех"| ACTIVE["Active binding"]
|
||||
```
|
||||
|
||||
## 10. Сущности: безопасное выполнение
|
||||
|
||||
### 10.1. Operation
|
||||
|
||||
Публично объявленное действие репозитория.
|
||||
|
||||
Примеры:
|
||||
|
||||
- `container.inspect`;
|
||||
- `container.plan`;
|
||||
- `container.apply`;
|
||||
- `container.verify`;
|
||||
- `knowledge.validate`.
|
||||
|
||||
Operation сообщает назначение, intent, фазу, effect, risk, schemas, preconditions и канонический handler.
|
||||
|
||||
### 10.2. Handler
|
||||
|
||||
Единственная исполняемая реализация operation.
|
||||
|
||||
Это может быть Python, PowerShell, shell, Terraform или Ansible. Важно не средство, а то, что handler лежит в одном каноническом месте и ограничен своим доменом.
|
||||
|
||||
Skill не копирует handler. Claude не конструирует произвольные команды, если существует operation.
|
||||
|
||||
### 10.3. Effect и risk
|
||||
|
||||
Effect описывает, что операция способна изменить:
|
||||
|
||||
- `read-only`;
|
||||
- `local-write`;
|
||||
- `external-write`;
|
||||
- `disruptive`;
|
||||
- `destructive`.
|
||||
|
||||
Risk показывает серьёзность возможных последствий: `low`, `medium`, `high`, `critical`.
|
||||
|
||||
Effect и risk нужны для автоматического выбора approval policy.
|
||||
|
||||
### 10.4. Preconditions
|
||||
|
||||
Проверяемые условия до запуска:
|
||||
|
||||
- contract валиден;
|
||||
- знания не stale;
|
||||
- target входит в разрешённую область;
|
||||
- revision не изменилась;
|
||||
- binding существует;
|
||||
- approval относится к текущему plan.
|
||||
|
||||
При нарушении precondition операция останавливается, а не «пробует всё равно».
|
||||
|
||||
## 11. Desired, observed, status и drift
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
G["Git desired state"] --> D["Diff"]
|
||||
R["Runtime observed state"] --> D
|
||||
R --> S["Immutable snapshot"]
|
||||
S --> D
|
||||
D --> DRIFT{"Drift exists?"}
|
||||
DRIFT -->|"нет"| READY["Ready condition"]
|
||||
DRIFT -->|"да"| PLAN["Plan or warning"]
|
||||
PLAN -. "только после approval" .-> APPLY["Apply"]
|
||||
APPLY --> VERIFY["Verify"]
|
||||
VERIFY --> R
|
||||
```
|
||||
|
||||
### 11.1. Desired state
|
||||
|
||||
То, что должно быть. Хранится в authored files в Git.
|
||||
|
||||
### 11.2. Observed state
|
||||
|
||||
То, что фактически обнаружено в LXD, Docker, AD, Network или другой системе. Всегда имеет время наблюдения и provenance.
|
||||
|
||||
### 11.3. Snapshot
|
||||
|
||||
Неизменяемая историческая копия observed state. Snapshot полезен для diff, plan, расследования и rollback, но не является desired state.
|
||||
|
||||
### 11.4. Status и condition
|
||||
|
||||
Status — краткое производное состояние сущности.
|
||||
|
||||
Condition — отдельный стандартизованный факт, например:
|
||||
|
||||
- `ContractValid=True`;
|
||||
- `KnowledgeFresh=False`;
|
||||
- `DriftDetected=True`;
|
||||
- `Ready=Unknown`.
|
||||
|
||||
Condition содержит reason, message, observed revision и время.
|
||||
|
||||
### 11.5. Drift
|
||||
|
||||
Разница между desired и observed state. Наличие drift не даёт автоматического разрешения на исправление: иногда нужен только warning, иногда — новый Plan.
|
||||
|
||||
## 12. Plan, apply и доказательство результата
|
||||
|
||||
### 12.1. Plan
|
||||
|
||||
Неизменяемое описание точных будущих изменений.
|
||||
|
||||
Plan фиксирует:
|
||||
|
||||
- intent;
|
||||
- Git revisions;
|
||||
- snapshots;
|
||||
- targets;
|
||||
- порядок operations;
|
||||
- effects и risks;
|
||||
- checkpoints;
|
||||
- verification;
|
||||
- rollback;
|
||||
- собственный hash.
|
||||
|
||||
### 12.2. Revision и plan hash
|
||||
|
||||
Revision указывает точную версию входных данных. Plan hash идентифицирует точный план.
|
||||
|
||||
Если после планирования contract, desired state или важный snapshot изменился, старое approval больше не должно разрешать apply.
|
||||
|
||||
### 12.3. Approval
|
||||
|
||||
Разрешение конкретного пользователя на конкретный plan hash и targets. Approval не является общим разрешением «делать любые изменения в LXD».
|
||||
|
||||
### 12.4. Apply
|
||||
|
||||
Выполняет сохранённый Plan. Он не должен заново придумывать операции или расширять scope.
|
||||
|
||||
### 12.5. Checkpoint
|
||||
|
||||
Промежуточная остановка и проверка. Следующий шаг выполняется только после успешного результата предыдущего provider change и его проверки.
|
||||
|
||||
### 12.6. Verify
|
||||
|
||||
Проверяет технический результат provider. Успешный exit code apply ещё не доказывает правильность состояния.
|
||||
|
||||
### 12.7. Run и RunEvidence
|
||||
|
||||
Run — одно конкретное выполнение workflow.
|
||||
|
||||
RunEvidence — структурированное доказательство:
|
||||
|
||||
- какой plan выполнялся;
|
||||
- кем и когда;
|
||||
- какие шаги прошли;
|
||||
- что проверил provider;
|
||||
- прошла ли consumer acceptance;
|
||||
- какой target был создан;
|
||||
- что было redacted.
|
||||
|
||||
### 12.8. Reconcile и rollback
|
||||
|
||||
Reconcile повторно сравнивает desired и observed state и решает, нужен ли warning или новый Plan.
|
||||
|
||||
Rollback восстанавливает предыдущее состояние либо выполняет компенсирующее действие. Не все изменения полностью обратимы, поэтому невозможность rollback должна быть указана честно.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Describe
|
||||
Describe --> Inspect
|
||||
Inspect --> Validate
|
||||
Validate --> Diff
|
||||
Diff --> Plan: change required
|
||||
Diff --> Verify: no change required
|
||||
Plan --> AwaitApproval: write effect
|
||||
Plan --> Apply: local safe operation
|
||||
AwaitApproval --> Apply: approved plan hash
|
||||
AwaitApproval --> [*]: denied or stale
|
||||
Apply --> Verify
|
||||
Verify --> Accepted: provider and consumer checks pass
|
||||
Verify --> Rollback: failed and rollback available
|
||||
Verify --> Reconcile: drift remains
|
||||
Rollback --> Verify
|
||||
Reconcile --> Inspect
|
||||
Accepted --> [*]
|
||||
```
|
||||
|
||||
## 13. Workflow
|
||||
|
||||
Workflow связывает несколько operations ради пользовательского результата. Он координирует репозитории, но не копирует реализации handlers.
|
||||
|
||||
Пример: развернуть контейнер для антивируса.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User as Пользователь
|
||||
participant Agent as Claude
|
||||
participant Repoctl as repoctl
|
||||
participant AV as Services/Antivirus
|
||||
participant LXD as Infra/LXD
|
||||
participant Runtime as LXD runtime
|
||||
|
||||
User->>Agent: Разверни контейнер для антивируса
|
||||
Agent->>Repoctl: context(intent=container.deploy)
|
||||
Repoctl->>AV: Read contract and selected KDB topics
|
||||
Repoctl->>LXD: Read contract and selected KDB topics
|
||||
AV-->>Repoctl: Requirement and acceptance operation
|
||||
LXD-->>Repoctl: Capability and provider operations
|
||||
Repoctl-->>Agent: ContextBundle and relation graph
|
||||
|
||||
Agent->>Repoctl: inspect and build Plan
|
||||
Repoctl->>Runtime: Read observed state
|
||||
Runtime-->>Repoctl: Snapshot
|
||||
Repoctl-->>User: Exact Plan, risk and plan hash
|
||||
User->>Repoctl: Approve plan hash
|
||||
|
||||
Repoctl->>LXD: Apply provider step
|
||||
LXD->>Runtime: Create or update container
|
||||
Runtime-->>LXD: Result
|
||||
LXD-->>Repoctl: Provider verification
|
||||
Repoctl->>AV: Run consumer acceptance
|
||||
AV-->>Repoctl: Acceptance passed
|
||||
Repoctl-->>Agent: Active binding and RunEvidence
|
||||
Agent-->>User: Container deployed and verified
|
||||
```
|
||||
|
||||
Cross-repository workflow не является атомарной транзакцией. Безопасность достигается immutable Plan, последовательными checkpoints, verification, acceptance и evidence.
|
||||
|
||||
## 14. Интерфейсы для агентов и людей
|
||||
|
||||
### 14.1. `repoctl`
|
||||
|
||||
Общий диспетчер. Он не заменяет LXD, Docker, Git, Terraform или Ansible.
|
||||
|
||||
MVP-команды:
|
||||
|
||||
```text
|
||||
repoctl init
|
||||
repoctl adopt
|
||||
repoctl validate
|
||||
repoctl discover
|
||||
repoctl describe
|
||||
repoctl context
|
||||
```
|
||||
|
||||
### 14.2. `AGENTS.md`
|
||||
|
||||
Короткая переносимая инструкция: что это за repository, где contract, как получить контекст и какие safety rules обязательны.
|
||||
|
||||
### 14.3. `CLAUDE.md`
|
||||
|
||||
Главный runtime entrypoint, потому что основной агент — Claude. Он импортирует `AGENTS.md` и содержит только Claude-specific дополнения.
|
||||
|
||||
### 14.4. Skill
|
||||
|
||||
Удобная команда или инструкция для типового intent, например `repository-adoption` или `repo-handoff`. Skill выбирает нужную операцию, но не реализует её заново. Для adoption источником истины остаётся [runbook](adoption-runbook.md), поэтому процедура переносима между Claude и другими агентами.
|
||||
|
||||
### 14.5. Adapter
|
||||
|
||||
Тонкий слой для конкретного harness: Claude skill, Codex skill, IDE command, CI job или MCP tool.
|
||||
|
||||
### 14.6. MCP
|
||||
|
||||
Будущий сетевой transport. Он публикует те же contracts, context bundles и operations. Добавление MCP не меняет владельца данных и не даёт write permission само по себе.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
CORE["Contract + KDB + repo-local handlers"] --> CLI["repoctl CLI"]
|
||||
CORE --> CLAUDE["Claude adapter"]
|
||||
CORE --> OTHER["Other agent adapter"]
|
||||
CORE --> CI["CI validation"]
|
||||
CORE -. "позже" .-> MCP["MCP server"]
|
||||
|
||||
CLI --> SAME["Одинаковая семантика"]
|
||||
CLAUDE --> SAME
|
||||
OTHER --> SAME
|
||||
CI --> SAME
|
||||
MCP --> SAME
|
||||
```
|
||||
|
||||
## 15. Простая первая версия
|
||||
|
||||
Первая версия намеренно read-only вне явно подтверждённых `init` и `adopt --mode apply`.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Phase A: schema/parser"] --> B["Phase B: validate/discover/describe/context"]
|
||||
B --> C["Phase C: bootstrap, adoption and template lineage"]
|
||||
C --> D["Phase D: LXD + Antivirus pilots"]
|
||||
D --> E["Phase E: operation ABI and Plan"]
|
||||
E --> F["Scoped apply and optional MCP"]
|
||||
```
|
||||
|
||||
### 15.1. Что реализуем сейчас
|
||||
|
||||
- parser для `RepositoryContract` и `KnowledgeBase`;
|
||||
- validation;
|
||||
- безопасную работу с repo-relative paths;
|
||||
- discovery и производный catalog;
|
||||
- `describe` без чтения всей KDB;
|
||||
- `context` с exact intent routing и budget;
|
||||
- bootstrap четырёх repository types;
|
||||
- adoption существующих репозиториев через assess → plan → apply → verify;
|
||||
- compatibility index для legacy KDB без массовой конвертации;
|
||||
- template ID/version/revision;
|
||||
- генерацию `AGENTS.md` и `CLAUDE.md`;
|
||||
- YAML и JSON output;
|
||||
- тестовые fixtures.
|
||||
|
||||
### 15.2. Что оставляем на следующий этап
|
||||
|
||||
- единый ABI для существующих handlers;
|
||||
- фактический вызов operations;
|
||||
- immutable Plan hashing;
|
||||
- approvals;
|
||||
- apply;
|
||||
- RunEvidence storage;
|
||||
- continuous reconciliation;
|
||||
- MCP server.
|
||||
|
||||
При этом IDs, envelope и связи уже совместимы с этими расширениями.
|
||||
|
||||
## 16. Предлагаемая внутренняя структура `repoctl`
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
CLI["cli"] --> MODEL["model"]
|
||||
CLI --> COMMANDS["commands"]
|
||||
COMMANDS --> VALIDATE["validation"]
|
||||
COMMANDS --> DISCOVERY["discovery"]
|
||||
COMMANDS --> CATALOG["catalog"]
|
||||
COMMANDS --> CONTEXT["context selection"]
|
||||
COMMANDS --> BOOTSTRAP["templates/bootstrap"]
|
||||
COMMANDS --> ADOPTION["adoption"]
|
||||
|
||||
VALIDATE --> IO["YAML/JSON I/O"]
|
||||
DISCOVERY --> IO
|
||||
CATALOG --> MODEL
|
||||
CONTEXT --> MODEL
|
||||
BOOTSTRAP --> MODEL
|
||||
ADOPTION --> MODEL
|
||||
|
||||
MODEL --> SCHEMA["versioned schemas"]
|
||||
```
|
||||
|
||||
Модули должны оставаться независимыми:
|
||||
|
||||
- `model` не знает о CLI;
|
||||
- `discovery` ничего не исполняет;
|
||||
- `catalog` только агрегирует contracts;
|
||||
- `context` выполняет детерминированный выбор;
|
||||
- `bootstrap` сначала строит preview/diff;
|
||||
- `adoption` сохраняет существующие authoritative paths и сначала строит assessment/plan;
|
||||
- будущий `runner` добавляется отдельно и не расширяет права read-only команд.
|
||||
|
||||
## 17. Bootstrap нового и adoption существующего репозитория
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User as Пользователь
|
||||
participant Init as repoctl init
|
||||
participant Template as Template registry
|
||||
participant Repo as New repository
|
||||
participant Validate as Validator
|
||||
|
||||
User->>Init: type, name, owner, lifecycle
|
||||
Init->>Template: Load trusted template version
|
||||
Template-->>Init: Skeleton and defaults
|
||||
Init-->>User: Preview files and optional SSH recommendation
|
||||
User->>Init: Confirm local write
|
||||
Init->>Repo: Write contract, KDB and entrypoints
|
||||
Init->>Validate: Validate generated repository
|
||||
Validate-->>User: Findings and final diff
|
||||
```
|
||||
|
||||
Bootstrap предлагает, но не навязывает:
|
||||
|
||||
- уникальный SSH deploy key для repository-scoped automation;
|
||||
- read-only доступ по умолчанию;
|
||||
- отдельное безопасное место private key вне Git;
|
||||
- CODEOWNERS/branch policy;
|
||||
- type-specific content roots.
|
||||
|
||||
Он обязательно записывает происхождение шаблона, чтобы стандартную часть можно было обновить позднее.
|
||||
|
||||
Для существующего репозитория используется другая операция — `repoctl adopt`. Она не раскладывает старый repository как новый шаблон, а сначала картографирует уже существующие источники истины, agent instructions, KDB и штатные места результата.
|
||||
|
||||
По умолчанию adoption добавляет overlay и ничего не переносит. Если владелец отдельно просит упорядочить дерево, используется именованная normalization recipe. Например, `documents-to-content-root` оставляет в корне `README.md`, `AGENTS.md` и `CLAUDE.md`, переносит только подтверждённые длинные документы и одновременно переписывает contract, KDB, frontmatter и Markdown links.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
EXISTING["Существующий repository"] --> ASSESS["Assess: только чтение"]
|
||||
ASSESS --> PLAN["Plan: contract, roots, KDB adapter"]
|
||||
PLAN --> REVIEW{"Владелец согласен?"}
|
||||
REVIEW -->|нет| REFINE["Уточнить классификацию"]
|
||||
REFINE --> PLAN
|
||||
REVIEW -->|overlay| APPLY["Apply: только metadata layer"]
|
||||
REVIEW -->|normalize| NORMALIZE["Approved recipe and rename map"]
|
||||
NORMALIZE --> APPLY
|
||||
APPLY --> VERIFY["Validate and verify"]
|
||||
VERIFY --> PILOT["Добавить в catalog как pilot"]
|
||||
```
|
||||
|
||||
Подробные правила, включая legacy KDB и существующие `CLAUDE.md`/`AGENTS.md`, находятся в [adoption-runbook.md](adoption-runbook.md).
|
||||
|
||||
## 18. Проверки MVP
|
||||
|
||||
Минимальный тестовый набор должен включать:
|
||||
|
||||
| Область | Позитивный тест | Негативный тест |
|
||||
|---|---|---|
|
||||
| Contract | четыре repository types | неизвестный type |
|
||||
| Paths | repo-relative path | `../outside` и absolute path |
|
||||
| IDs | уникальные stable IDs | duplicate repository/content/topic IDs |
|
||||
| KDB routing | exact intent selects expected topics | нерелевантные topics не загружаются |
|
||||
| Freshness | current verified source | expired source создаёт warning |
|
||||
| Catalog | воспроизводимая пересборка | duplicate repository name |
|
||||
| Relations | requirement находит capability | unresolved requirement создаёт warning |
|
||||
| Security | harmless metadata | secret-shaped fields и shell string |
|
||||
| Context budget | deterministic truncation | тихое усечение без warning запрещено |
|
||||
| Agent entrypoint | Claude imports portable instructions | длинная копия KDB в `CLAUDE.md` |
|
||||
| Adoption | legacy layout объявлен без перемещения | перезапись существующего KDB или domain content |
|
||||
|
||||
## 19. Как измерять пользу
|
||||
|
||||
Цель — не просто создать новые YAML-файлы. Пользу нужно измерять на реальных задачах.
|
||||
|
||||
Рекомендуемые метрики:
|
||||
|
||||
- время до первой правильной команды;
|
||||
- количество файлов, прочитанных до начала работы;
|
||||
- tokens/bytes загруженного repository context;
|
||||
- количество повторных объяснений структуры пользователем;
|
||||
- доля stale knowledge, обнаруженного до действия;
|
||||
- доля operations с успешным verify;
|
||||
- количество несовместимых или orphan bindings;
|
||||
- количество разных копий одного handler;
|
||||
- время onboarding нового repository;
|
||||
- время обновления repository template.
|
||||
|
||||
Для проверки достаточно нескольких одинаковых сценариев до и после внедрения:
|
||||
|
||||
1. найти LXD profiles;
|
||||
2. подготовить новый container для Antivirus;
|
||||
3. найти все Docker stacks;
|
||||
4. проверить monitoring configuration;
|
||||
5. начать работу в незнакомом software repository;
|
||||
6. найти deliverables и sources в project repository.
|
||||
|
||||
## 20. Как модель связана с внешними практиками
|
||||
|
||||
Эта схема не копирует один конкретный продукт. Она соединяет несколько зрелых подходов, оставляя их независимыми от выбранного agent harness.
|
||||
|
||||
| Наша часть | Близкая внешняя практика | Что заимствовано |
|
||||
|---|---|---|
|
||||
| Repo-local contract и производный catalog | [Backstage Software Catalog](https://backstage.io/docs/features/software-catalog/) | descriptor хранится рядом с repository content, catalog является проекцией |
|
||||
| Bootstrap и обновление стандартной части | [Backstage Software Templates](https://backstage.io/docs/features/software-templates/), [Copier updates](https://copier.readthedocs.io/en/stable/updating/) | typed inputs, preview, template version, migrations |
|
||||
| Desired/observed state и reconciliation | [OpenGitOps](https://opengitops.dev/), [Kubernetes API conventions](https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md) | декларативность, разделение spec/status, conditions и observed revision |
|
||||
| Requirements и capabilities | [Crossplane composite resources](https://docs.crossplane.io/latest/composition/composite-resources/), [Score](https://docs.score.dev/docs/) | отделение потребности consumer от реализации provider |
|
||||
| Operations и workflows | [OpenAPI](https://spec.openapis.org/oas/latest.html), [Arazzo](https://spec.openapis.org/arazzo/latest.html) | стабильные operation IDs, schemas, dependencies, outputs и success criteria |
|
||||
| Claude и переносимые agent instructions | [Claude memory](https://code.claude.com/docs/en/memory), [AGENTS.md](https://agents.md/) | короткий постоянный entrypoint и on-demand подробности |
|
||||
| Опциональный transport | [MCP server primitives](https://modelcontextprotocol.io/specification/2025-06-18/server/index) | resources, tools и prompts как адаптеры над общей моделью |
|
||||
| KDB и provenance | [Data Package](https://specs.frictionlessdata.io/guides/data-package/), [W3C PROV](https://www.w3.org/TR/prov-o/), [Diátaxis](https://diataxis.fr/) | human/machine index, происхождение знания и типы документации |
|
||||
| Repository security | [OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md), [SLSA provenance](https://slsa.dev/spec/v1.2/provenance), [SPDX](https://spdx.github.io/spdx-spec/v3.0.1/scope/) | ownership, protected changes, integrity и supply-chain provenance |
|
||||
| Domain-native content roots | [Flux repository layouts](https://fluxcd.io/flux/guides/repository-structure/), [Terraform module structure](https://developer.hashicorp.com/terraform/language/modules/develop/structure), [Docker Compose project directory](https://docs.docker.com/reference/cli/docker/compose/) | стандартное место результата задаётся доменом, а contract только объявляет его |
|
||||
|
||||
Уникальная часть нашей модели — сочетание intent-based KDB routing, typed content roots, consumer-owned acceptance, provider-owned bindings и immutable cross-repository Plan. Внешние практики подтверждают отдельные элементы, но не дают эту комбинацию целиком.
|
||||
|
||||
## 21. Итоговая модель одной фразой
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
REQUEST["Что хочет пользователь"] --> INTENT["Intent"]
|
||||
INTENT --> CONTRACT["Кто отвечает и что умеет"]
|
||||
INTENT --> KDB["Что нужно знать"]
|
||||
CONTRACT --> ROOTS["Где лежит результат"]
|
||||
CONTRACT --> RELATIONS["Кто от кого зависит"]
|
||||
CONTRACT --> OPERATIONS["Что разрешено сделать"]
|
||||
KDB --> CONTEXT["Минимальный нужный контекст"]
|
||||
ROOTS --> CONTEXT
|
||||
RELATIONS --> CONTEXT
|
||||
OPERATIONS --> CONTEXT
|
||||
CONTEXT --> PLAN["Что именно изменится"]
|
||||
PLAN --> RESULT["Проверенный результат и evidence"]
|
||||
```
|
||||
|
||||
В коротком виде:
|
||||
|
||||
- **Contract** — кто мы и как с нами работать;
|
||||
- **Intent** — чего хочет пользователь;
|
||||
- **KDB** — что нужно знать для этой цели;
|
||||
- **ContentRoot** — где находится реальный результат;
|
||||
- **Requirement** — что нужно consumer;
|
||||
- **Capability** — что умеет provider;
|
||||
- **Binding** — какой конкретный target удовлетворил requirement;
|
||||
- **Operation** — что разрешено сделать;
|
||||
- **Handler** — как это технически выполняется;
|
||||
- **Plan** — какие точные изменения подтверждаются;
|
||||
- **RunEvidence** — чем доказан итог;
|
||||
- **repoctl / skill / MCP** — разные интерфейсы над одной моделью.
|
||||
Reference in New Issue
Block a user