docs: baseline specification-only repository stewardship

This commit is contained in:
Alexander Baranov
2026-08-24 14:39:09 +03:00
commit 9a39b8a941
11 changed files with 4191 additions and 0 deletions
+934
View File
@@ -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** — разные интерфейсы над одной моделью.