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
+119
View File
@@ -0,0 +1,119 @@
# Реализация Repository Stewardship и `repoctl` L1
## Результат
В этом репозитории появится рабочий кроссплатформенный CLI `repoctl`, который станет единым интерфейсом для людей, Claude и других агентов:
- обнаруживает и описывает репозитории;
- валидирует contract, KDB, пути и документацию;
- выдаёт минимальный контекст по intent;
- создаёт новые репозитории;
- безопасно подключает существующие;
- строит каталог и связи между репозиториями;
- не выполняет инфраструктурные операции и не обращается к внешним системам.
Реализация — Python 3.11+, управление через `uv`, пакет `repository-stewardship`, модуль `stewardship`, команда `repoctl`. Используются `ruamel.yaml` для безопасного YAML и сохранения форматирования, `jsonschema` Draft 2020-12 для публичных схем и стандартный `argparse` без тяжёлого CLI-фреймворка. Структура `src/` и `uv_build` соответствует рекомендациям [uv](https://docs.astral.sh/uv/concepts/projects/init/).
## Архитектура и публичные интерфейсы
- Разделить код на независимые слои: модели и схемы, безопасный I/O, validation, discovery/catalog, context selection, bootstrap, adoption, CLI rendering. CLI остаётся тонким адаптером; эти же функции позднее сможет вызвать MCP server.
- Хранить versioned schemas и шаблоны как package resources, доступные и из исходников, и из установленного wheel.
- Добавить JSON Schemas для:
- `RepositoryContract`, `KnowledgeBase`, `CatalogIndex`, `ContextBundle`;
- `BootstrapPlan`;
- `AdoptionAssessment`, `AdoptionPlan`, `AdoptionReport`;
- пользовательской конфигурации и общего результата CLI.
- Ввести стабильный machine-output envelope `stewardship/repoctl-result@0.1` с полями `command`, `outcome`, `data`, `findings`. В `data` остаётся соответствующий protocol resource.
- Все команды поддерживают `--output human|yaml|json`. Machine output идёт только в stdout, диагностика процесса — в stderr.
- Неизвестные нормативные поля отклоняются; `x-*`, `metadata.annotations`, открытые content roles и domain data сохраняются.
- Зафиксировать exit codes из спецификации: `0` success, `1` validation failure, `2` invalid input, `3` repository not found, `4` incomplete/stale strict context, `5` approval failure.
Командный интерфейс:
```text
repoctl config show|add-root|remove-root
repoctl validate [--repo PATH]
repoctl discover [--root PATH ...]
repoctl describe --repo NAME|PATH [--root PATH ...]
repoctl context --repo NAME|PATH --intent INTENT
[--include-related] [--materialize]
[--budget-bytes N] [--strict]
repoctl init --repo PATH [--answers FILE] [--git-init|--no-git-init]
repoctl init --repo PATH --apply --plan FILE --approve SHA256
repoctl adopt --repo PATH --mode assess|plan|apply|verify
[--answers FILE] [--strategy overlay|normalize]
[--recipe ID] [--plan FILE] [--approve SHA256]
```
Разрешение имени репозитория выполняется в порядке: явные `--root` → `REPOCTL_ROOTS` → пользовательский config → текущий repository. Config хранится в `%APPDATA%\RepositoryStewardship\config.yaml` на Windows и в XDG config directory на Unix. Его изменение выполняется только явными `config add-root/remove-root`; скрытый cache по умолчанию не создаётся.
## Поведение инструментов
- `validate` проверяет schemas, IDs, ссылки, content roots, path/symlink confinement, freshness, provenance, secret-shaped поля, operations без shell strings, Markdown links/frontmatter/YAML fences, сбалансированные code fences и статический синтаксис Mermaid.
- `discover` ищет `ops/contract.yaml`, не следует по symlink/junction, пропускает `.git`, virtual environments и dependency caches, строит детерминированный `CatalogIndex`, capability/requirement/binding relations и выявляет дубликаты repository ID.
- `describe` читает только contract и никогда не загружает KDB.
- `context` по умолчанию возвращает компактный bundle: topic data, document metadata, selectors/headings, operations и content roots. `--materialize` извлекает только явно выбранные Markdown-разделы или ограниченные YAML key paths; сеть не используется.
- Budget считается в UTF-8 bytes только для materialized content. Элементы сортируются детерминированно; усечение всегда отражается warning и при `--strict` даёт exit `4`.
- Для хешей ресурсов используется canonical JSON representation, а не платформенные окончания строк. Время передаётся через clock abstraction, чтобы тестовые результаты были воспроизводимыми.
`init`:
- собирает ответы через CLI или YAML answers file; CLI имеет приоритет;
- предлагает type-specific content roots, но не создаёт фиктивные domain artifacts;
- создаёт contract, KDB, `AGENTS.md`, импортирующий его `CLAUDE.md`, template answers, `.gitignore` и три Claude skills;
- записывает template ID/version и SHA-256 revision шаблона;
- при необходимости включает `git init`, но не создаёт remote, commit или push;
- выдаёт структурированную рекомендацию отдельного repository-scoped SSH key, не генерируя и не сохраняя secret;
- сначала возвращает полный `BootstrapPlan`; запись возможна только по plan-файлу и его SHA-256.
`adopt`:
- реализует runbook `assess → plan → apply → verify`;
- различает detected, inferred и confirmed данные;
- фиксирует HEAD либо состояние `unborn`, dirty paths и hashes всех входных/touched файлов;
- по умолчанию использует overlay и сохраняет domain-native layout;
- для legacy root `kdb.yaml` предлагает небольшой `kdb/kdb.yaml` adapter;
- если legacy KDB уже занимает `kdb/kdb.yaml`, предлагает `ops/knowledge.yaml`;
- существующие skills, handlers, KDB и agent instructions не переписывает;
- tracked secret является blocker; untracked secret-shaped paths показываются path-only без содержимого;
- `documents-to-content-root` выполняется только как явно выбранная normalization recipe с rename map, conservative Markdown/frontmatter/YAML rewrites и collision checks;
- apply повторно проверяет baseline и plan hash, пишет только перечисленные paths, использует временные файлы и восстанавливает исходное состояние при локальной ошибке;
- никогда не делает commit, push, clone или external operation.
## Claude и self-hosting
Добавить три коротких project skills:
- `repository-bootstrap`;
- `repository-adoption`;
- `repo-handoff`.
Они размещаются в `.claude/skills/<name>/SKILL.md`, как предусмотрено [Claude Code](https://code.claude.com/docs/en/skills), и только собирают недостающие решения, вызывают `repoctl` с machine output и объясняют findings. Логика CLI в skills не дублируется. Те же skills входят в bootstrap templates; остальные агенты используют команды из `AGENTS.md`.
Сам репозиторий переводится из `specification-only` в `l1-implemented`:
- contract получает реальные content roots для исходников, schemas/templates и Claude adapters;
- KDB индексирует новую справку `repoctl` и handoff intents;
- README, specification, guide, adoption runbook и agent instructions обновляются под фактический CLI;
- фиктивные handlers и operations не объявляются;
- MCP, L2 handler ABI и инфраструктурный apply остаются отложенными.
## Проверки и приёмка
- Fixtures четырёх repository types и отрицательные fixtures для неизвестных полей, `x-*`, duplicate IDs, Windows/Unix traversal, UNC/absolute paths, symlink escape, secrets и shell strings.
- Golden tests одинакового YAML/JSON output и exit codes.
- Context tests для exact intent, related topics, Markdown headings, legacy YAML selectors, stale/missing sources и byte-budget.
- Catalog tests для стабильной сортировки, hashes, duplicate repositories и capability matching.
- Init/adoption tests подтверждают отсутствие записей до approval, отказ при неверном hash или изменившемся baseline и отсутствие commit/push.
- LXD fixture сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml`.
- Antivirus fixture сохраняет custom `kdb/kdb.yaml` и предлагает `ops/knowledge.yaml`.
- Normalization tests покрывают exclusions, case-insensitive collisions, reference rewrites и rollback.
- Самопроверка: `repoctl validate --repo .`, unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
- Реальные `Infra/LXD` и `Services/Antivirus` используются только для read-only `assess` и `plan`; Git status до и после должен совпасть. Никакие планы к ним не применяются.
## Зафиксированные ограничения
- Версия пакета и шаблонов начинается с `0.1.0`; protocol остаётся `stewardship.corsus.ru/v1alpha1`.
- Первая версия работает только с уже доступными локальными repositories; clone по URL отложен.
- Не реализуются handlers, execution runner, внешние credentials, immutable cross-repository L3 Plan, MCP server и автоматический catalog daemon.
- Пользовательские и пилотные dirty worktrees сохраняются без изменений.
+660
View File
@@ -0,0 +1,660 @@
---
documentId: repository-adoption-runbook
documentVersion: 0.1.0
protocol: Repository Stewardship
schemaApiVersion: stewardship.corsus.ru/v1alpha1
status: proposed
normative: false
language: ru
machineSpecification: docs/specification.md
humanGuide: docs/guide.md
defaultStrategy: overlay
primaryAgent: Claude
portable: true
---
# Repository Adoption Runbook
## 0. Назначение и решение
Этот runbook подключает существующий Git-репозиторий к Repository Stewardship без перестройки его полезного содержимого.
Рекомендованная реализация состоит из двух слоёв:
1. этот runbook — переносимый источник истины для человека и любого агента;
2. тонкий skill `repository-adoption` — удобный Claude-интерфейс, который следует runbook и позднее вызывает `repoctl adopt`.
Skill не должен содержать отдельную логику классификации, генерации или проверки. Иначе Claude и другие агенты начнут переводить репозитории по разным правилам.
## 1. Термины
| Термин | Значение |
|---|---|
| `init` | создание нового репозитория из шаблона |
| `adopt` | первое подключение существующего репозитория к стандарту |
| `migrate` | обновление уже подключённого репозитория между версиями schema/template |
| `overlay` | добавляем stewardship metadata, не перемещая domain content |
| `normalize` | отдельно согласованное перемещение или переименование существующих файлов |
| `assessment` | только факты и выводы, полученные без записи |
| `adoption plan` | точный предлагаемый набор repository-local изменений |
`adopt` MUST NOT неявно превращаться в `normalize` или `migrate`.
## 2. Почему стратегия overlay используется по умолчанию
В обследованных `Infra` и `Services` встречаются разные, но уже осмысленные структуры:
- `Infra/LXD`: `profiles-source/` является source of truth, `profiles/` — mirror, KDB находится в корне, а существующие skills уже управляют профилями;
- `Infra/Docker`: stack directories находятся непосредственно в корне и не должны быть перенесены в общий `payload/`;
- `Infra/Network`: собственные зоны `shared/`, `clients/`, `egress/`, `wan/`, `wifi/`;
- `Services/Antivirus`: большой custom `kdb/kdb.yaml`, vendor sources, policies и ссылки на authoritative artifacts в LXD/Network/Docker;
- `Services/Monitoring` и `Services/Surveillance`: уже имеют KDB и domain-specific tools, но не одинаковые agent entrypoints.
Общий интерфейс здесь полезнее общего физического дерева. Adoption объявляет существующие места через contract и compatibility index.
```mermaid
flowchart LR
LEGACY["Существующий layout"] --> OVERLAY["Stewardship overlay"]
OVERLAY --> CONTRACT["ops/contract.yaml"]
OVERLAY --> KNOWLEDGE["KnowledgeBase index or adapter"]
OVERLAY --> ENTRY["CLAUDE.md + AGENTS.md pointers"]
CONTRACT --> ROOTS["Existing contentRoots stay in place"]
KNOWLEDGE --> SOURCES["Existing KDB and vendor sources stay in place"]
```
## 3. Safety invariants
Во время adoption агент или инструмент MUST:
- выполнять `assess` и `plan` только на чтение;
- не читать и не выводить содержимое private keys, tokens, passwords, `.env` и secret stores;
- не выполнять обнаруженные scripts, hooks, skills или operations;
- не подключаться к серверам и не изменять external systems;
- не перемещать, не удалять и не переименовывать существующие файлы;
- не переписывать существующие KDB и agent instructions целиком;
- не менять Git remote, default branch, history, permissions или access scope;
- не коммитить и не отправлять изменения без отдельного запроса;
- показать proposed diff до `apply`;
- остановить `apply`, если baseline revision изменился после `plan`;
- сохранять неизвестные `x-*` поля и существующие пользовательские секции.
Dirty working tree не мешает `assess`, но MUST быть явно отмечен. Для `apply` SHOULD использоваться чистая отдельная ветка либо подтверждённый набор непересекающихся paths.
## 4. Режимы adoption
```yaml
adoptionModes:
assess:
writes: false
output: AdoptionAssessment
plan:
writes: false
output: AdoptionPlan
apply:
writes: repository-local
approvalRequired: true
allowedScope: proposedPathsOnly
verify:
writes: false
output: AdoptionReport
```
До реализации CLI эти режимы являются логическими этапами runbook. После реализации им соответствуют:
```text
repoctl adopt --repo PATH --mode assess --output yaml
repoctl adopt --repo PATH --mode plan --output yaml
repoctl adopt --repo PATH --mode apply --plan PLAN --approve PLAN_HASH
repoctl adopt --repo PATH --mode verify --output yaml
```
## 5. Входные данные
Минимально необходимы:
- локальный путь или repository URL;
- read access;
- ожидаемый owner, если он уже известен;
- scope: один repository или явно перечисленная rollout wave.
Полезны, но не обязательны:
- предполагаемый repository type;
- ссылка на Git hosting project;
- известные связанные repositories;
- выбранный template version;
- сведения о protected branch/CODEOWNERS.
Отсутствующие сведения становятся questions, а не догадками, записанными как fact.
## 6. Phase 1 — preflight
### 6.1. Найти границу репозитория
Определить ближайший корень с `.git`. Nested repositories оцениваются отдельно. Каталог, содержащий несколько repositories, не получает один общий contract вместо них.
### 6.2. Зафиксировать Git baseline
Собрать без изменения состояния:
- current branch;
- HEAD revision;
- наличие staged, modified и untracked paths;
- remotes без credentials;
- tracked/untracked status будущих stewardship paths.
Не включать содержимое diff в централизованный отчёт без необходимости: для планирования достаточно списка paths и локального review.
### 6.3. Проверить collisions
Проверить существование:
```text
ops/contract.yaml
kdb/kdb.yaml
kdb.yaml
CLAUDE.md
AGENTS.md
.claude/skills/
.agents/skills/
ops/handlers/
ops/template-answers.yaml
```
Существующий path никогда не считается свободным только потому, что его формат неизвестен.
## 7. Phase 2 — assessment
### 7.1. Определить repository type
Тип выбирается по основному результату работы, а не по имени родительского каталога.
| Основной результат | Type |
|---|---|
| desired infrastructure state, inventory, profiles, networks, stacks | `infrastructure-config` |
| конфигурация и эксплуатационная модель конкретного сервиса | `service-config` |
| компилируемый/исполняемый код, library или application | `software` |
| документы, решения, datasets и deliverables проекта | `project` |
Если evidence указывает на два типа, выбрать владельца основного результата, а второй аспект отразить labels/content roots. Не создавать новый type только из-за смешанного layout.
### 7.2. Найти authoritative content
Для каждого значимого path определить:
- role;
- `source`, `generated`, `observed`, `mirror` или `evidence`;
- write policy;
- selector;
- кто реально владеет изменением.
Примеры:
```yaml
contentRoots:
- id: lxd-profile-sources
role: profiles
path: profiles-source
kind: file-set
authority: source
writePolicy: managed
selector: "*.yaml"
- id: lxd-live-profile-mirror
role: observed
path: profiles
kind: file-set
authority: mirror
writePolicy: generated
selector: "*.yaml"
- id: docker-stacks
role: stacks
path: .
kind: file-set
authority: source
writePolicy: managed
selector: "*/compose.y*ml"
```
Нельзя объявлять mirror как source только потому, что его YAML выглядит полнее.
### 7.3. Найти знания и provenance
Для каждого KDB/document source записать:
- path или URI;
- фактический формат;
- размер и верхнеуровневую структуру без загрузки всего содержимого в agent context;
- наличие index/routing;
- authority и status;
- vendor/local/observed provenance;
- freshness signals;
- наличие потенциальных secret-shaped paths или keys без вывода values.
### 7.4. Найти agent entrypoints и automation
Определить:
- какой файл сейчас является фактическим источником инструкций;
- есть ли противоречия или циклические ссылки между `CLAUDE.md` и `AGENTS.md`;
- какие skills/handlers каноничны;
- какие команды являются read-only, а какие меняют local/external state;
- где описан verify.
Наличие Claude-specific skill не делает его переносимым handler. В contract сначала регистрируется семантика операции, а адаптация skill выполняется позднее на L2.
### 7.5. Найти cross-repository relations
Записывать отношения по authority, а не по случайным относительным путям:
- service requirement → infrastructure capability;
- local pointer → authoritative artifact in provider repository;
- generated mirror → source root;
- runbook → operation/handler;
- vendor source → derived local knowledge.
## 8. Машиночитаемый результат assessment
До появления стабильного protocol kind используется versioned runbook output. Он не коммитится в целевой repository по умолчанию.
```yaml
runbookOutput:
schema: stewardship/adoption-assessment@0.1
repository:
path: Infra/LXD
baselineRevision: 0123456789abcdef
dirty: false
classification:
proposedType: infrastructure-config
confidence: high
evidence:
- profiles-source/*.yaml
- scripts/sync-from-cluster.sh
confirmationRequired: true
entrypoints:
claude: CLAUDE.md
portable: AGENTS.md
canonicalDirection: legacy-claude-to-agents
knowledge:
- path: kdb.yaml
format: legacy-yaml
action: wrap
proposedContentRoots:
- id: lxd-profile-sources
path: profiles-source
role: profiles
authority: source
collisions: []
findings:
- severity: warning
code: ADOPT_ENTRYPOINT_DIRECTION_LEGACY
path: AGENTS.md
questions:
- Confirm owner and lifecycle
```
Assessment MUST distinguish `detected`, `inferred` and `confirmed` values.
## 9. Phase 3 — confirmation boundary
До построения финального plan владелец должен подтвердить только решения, которые нельзя надёжно вывести:
- repository type при confidence ниже `high`;
- owner;
- lifecycle/access;
- какие paths являются source of truth;
- спорные cross-repository ownership boundaries;
- допустимость изменения существующих entrypoints.
Остальные безопасные defaults могут быть предложены в plan без отдельного диалога.
## 10. Phase 4 — adoption plan
Plan строится относительно immutable baseline revision и содержит только операции `create`, `patch-managed-block` или `preserve`.
```yaml
runbookOutput:
schema: stewardship/adoption-plan@0.1
repository: repo:infra-lxd
baselineRevision: 0123456789abcdef
strategy: overlay
changes:
- action: create
path: ops/contract.yaml
ownership: stewardship
- action: create
path: kdb/kdb.yaml
ownership: stewardship
reason: Compatibility index for legacy root kdb.yaml
- action: preserve
path: kdb.yaml
ownership: repository
- action: patch-managed-block
path: CLAUDE.md
ownership: shared
optional: true
forbiddenChanges:
- profiles-source/**
- profiles/**
- .ssh/**
validations:
- stewardship-schema
- path-confinement
- knowledge-references
- agent-entrypoint-cycle
approval:
required: true
planHash: sha256:0123456789abcdef
```
Plan MUST содержать rendered file contents или exact patch для каждого `create`/`patch-managed-block`, а не только словесное описание.
## 11. Compatibility rules
### 11.1. KDB
| Состояние | Действие |
|---|---|
| KDB отсутствует | создать `kdb/kdb.yaml` |
| `kdb/kdb.yaml` уже соответствует Stewardship | использовать без переписывания |
| legacy KDB находится в другом path | создать `kdb/kdb.yaml` как небольшой index/adapter |
| legacy/custom KDB уже занимает `kdb/kdb.yaml` | создать `ops/knowledge.yaml` и указать его в contract |
| несколько knowledge sources | index с topics/documents и явным authority |
Compatibility index MAY ссылаться на legacy YAML sections через `Topic.data.x-selector`, но не должен копировать весь legacy source.
```yaml
apiVersion: stewardship.corsus.ru/v1alpha1
kind: KnowledgeBase
metadata:
name: antivirus-knowledge-index
spec:
repository: repo:services-antivirus
defaultLanguage: ru
topics:
- id: windows-agent-rollout
summary: Verified Windows agent rollout
intents: [endpoint.deploy]
documents: [legacy-antivirus-kdb]
data:
x-selector:
format: yaml-path
value: $.windows_agent_rollout
documents:
- id: legacy-antivirus-kdb
title: Existing Antivirus knowledge base
role: reference
path: kdb/kdb.yaml
mediaType: application/yaml
authority: local-canonical
status: verified
```
### 11.2. `CLAUDE.md` и `AGENTS.md`
| Состояние | Действие |
|---|---|
| оба отсутствуют | создать короткий `AGENTS.md` и импортирующий его `CLAUDE.md` |
| только `AGENTS.md` | создать короткий `CLAUDE.md` с импортом |
| только `CLAUDE.md` | сохранить; предложить минимальный portable `AGENTS.md` |
| оба есть и согласованы | сохранить, добавить только contract pointer при необходимости |
| `AGENTS.md` ссылается на `CLAUDE.md` | не создавать обратный импорт; зарегистрировать legacy direction warning |
| файлы противоречат друг другу | остановить автоматическую консолидацию и запросить owner decision |
Изменение shared entrypoint SHOULD выполняться через ограниченный managed block с markers, а не заменой всего файла.
### 11.3. Existing skills and handlers
- сохранить paths;
- не копировать implementation между `.claude/skills`, `.agents/skills` и `ops/handlers`;
- на L1 только описать существование и safety boundary;
- переносить implementation в canonical handler только отдельным L2 plan.
### 11.4. SSH и secrets
- записывать только факт наличия path и назначение, если оно уже документировано;
- не вычислять fingerprints private keys без явной необходимости;
- не переносить keys в стандартный каталог;
- рекомендовать repository-scoped key как отдельную follow-up задачу;
- найденный tracked secret является blocker, но его remediation не входит автоматически в adoption apply.
### 11.5. Normalization recipe `documents-to-content-root`
Эта recipe MAY использоваться только по явному запросу владельца. Она не является частью default overlay.
```yaml
normalizationRecipe:
id: documents-to-content-root
strategy: normalize
sourceScope: repository-root
targetRoot: docs
filenameStyle: kebab-case
preserveAtRoot:
- README.md
- AGENTS.md
- CLAUDE.md
- CONTRIBUTING.md
- SECURITY.md
- CODE_OF_CONDUCT.md
- LICENSE
- LICENSE.*
- CHANGELOG.md
authorityPartitions:
canonical: docs
research: docs/research
rewriteReferences:
- ops/contract.yaml
- kdb/kdb.yaml
- Markdown links
- Markdown frontmatter
- managed agent instruction blocks
approvalRequired: true
```
Алгоритм recipe:
1. Найти project-specific long-form documents в корне, но не считать любой `*.md` кандидатом на перенос.
2. Оставить universal entrypoints, license/community files и tool-required root manifests на месте.
3. Классифицировать каждый кандидат как canonical, runbook, research или `preserve`.
4. Построить явный `oldPath → newPath` map. Переименование в kebab-case является отдельной видимой частью plan.
5. Проверить collisions с учётом case-insensitive filesystems и уже существующих targets.
6. Построить reference index до записи.
7. Переписать repo-relative ссылки в contract, KDB, frontmatter, Markdown и managed instruction blocks.
8. Не переписывать произвольные совпадения в source code, logs, vendor snapshots или evidence без отдельного правила.
9. Показать rename map и exact patches владельцу.
10. После approval выполнить moves и reference rewrites как один local change set.
Пример plan fragment:
```yaml
normalization:
recipe: documents-to-content-root
moves:
- from: REPOSITORY_STEWARDSHIP_SPEC.md
to: docs/specification.md
authority: canonical
- from: INFRASTRUCTURE_OPERATIONS_ARCHITECTURE_OPTIONS.md
to: docs/research/infrastructure-operations-architecture-options.md
authority: research
referenceUpdates:
- ops/contract.yaml
- kdb/kdb.yaml
- README.md
- AGENTS.md
preservedRootEntrypoints:
- README.md
- AGENTS.md
- CLAUDE.md
```
Recipe MUST завершиться проверкой отсутствующих targets, старых broken references, Markdown links, frontmatter paths и KDB document paths. Она MUST NOT перемещать domain-native artifacts под `docs/`.
## 12. Phase 5 — apply
Перед записью повторно проверить HEAD и status. Если baseline изменился, plan считается stale и строится заново.
Apply выполняет только подтверждённые changes:
1. создаёт `ops/contract.yaml`;
2. создаёт новый KDB index/adapter только в свободном path;
3. создаёт или патчит ограниченные managed blocks entrypoints;
4. записывает template lineage с `mode: adopted-overlay` и точным `managedPaths`;
5. не вызывает external operations;
6. показывает итоговый diff.
При `strategy: normalize` apply дополнительно выполняет только rename map и reference rewrites именованной recipe. Любой новый move инвалидирует approval и требует нового plan hash.
Apply не делает commit или push, если пользователь не запросил это отдельно.
## 13. Phase 6 — verify
Обязательные проверки:
- YAML parse и schema validation;
- repo-relative path confinement;
- существование всех content roots и documents;
- отсутствие циклов entrypoint imports;
- intent выбирает ожидаемые topics, но не весь KDB;
- selector находит ожидаемые domain artifacts;
- source/mirror authority не перепутаны;
- legacy files byte-identical, если plan обещал `preserve`;
- old paths из rename map больше не используются в active references;
- все new paths из rename map существуют;
- diff ограничен approved paths;
- catalog rebuild детерминирован;
- external state не изменялся.
Результат:
```yaml
runbookOutput:
schema: stewardship/adoption-report@0.1
repository: repo:infra-lxd
baselineRevision: 0123456789abcdef
compatibilityLevel: L1
outcome: pass-with-warnings
changedPaths:
- ops/contract.yaml
- kdb/kdb.yaml
preservedPaths:
- profiles-source
- profiles
- kdb.yaml
unresolvedFindings:
- ADOPT_ENTRYPOINT_DIRECTION_LEGACY
```
## 14. Finding codes
```yaml
findingCodes:
ADOPT_TYPE_AMBIGUOUS: confirmation-required
ADOPT_OWNER_UNKNOWN: confirmation-required
ADOPT_WORKTREE_DIRTY: warning
ADOPT_PATH_COLLISION: blocker
ADOPT_KDB_LEGACY: info
ADOPT_KDB_CANONICAL_PATH_OCCUPIED: warning
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
ADOPT_ENTRYPOINT_CONFLICT: blocker
ADOPT_SECRET_TRACKED: blocker
ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
ADOPT_BASELINE_CHANGED: blocker
ADOPT_EXTERNAL_WRITE_DETECTED: blocker
ADOPT_VALIDATION_FAILED: blocker
ADOPT_ROOT_DOCUMENT_CANDIDATE: info
ADOPT_MOVE_COLLISION: blocker
ADOPT_REFERENCE_REWRITE_INCOMPLETE: blocker
```
Коды стабильнее текстов и пригодны для CLI, CI и каталога.
## 15. Rollout waves
Начинать следует не с самых простых репозиториев, а с двух репрезентативных сложных cases — это раньше выявит недостатки модели.
```mermaid
flowchart LR
W0["Wave 0: fixtures"] --> W1["Wave 1: LXD + Antivirus"]
W1 --> G1{"Schema holds?"}
G1 -->|нет| FIX["Исправить schema/runbook"]
FIX --> W1
G1 -->|да| W2["Wave 2: Docker, Network, Monitoring, Surveillance"]
W2 --> W3["Wave 3: remaining Infra and Services"]
W3 --> W4["Wave 4: software and project repositories"]
```
Для каждой wave:
1. выполнить assessment всех repositories;
2. сгруппировать одинаковые findings;
3. обновить runbook/template один раз;
4. построить отдельный plan для каждого repository;
5. применить через reviewable branch/PR;
6. измерить time-to-context и объём прочитанного контекста;
7. только затем расширять следующую wave.
Outliers с неясным owner, secrets или конфликтующей authority помечаются `deferred` и не блокируют rollout остальных.
## 16. Предлагаемый Claude skill
После стабилизации первых двух pilot plans создать skill `repository-adoption`.
```yaml
skillProposal:
name: repository-adoption
purpose: Assess and prepare an existing repository for Repository Stewardship
canonicalProcedure: docs/adoption-runbook.md
defaultMode: plan
allowedByDefault:
- read repository metadata
- classify repository
- produce assessment
- produce proposed diff
approvalRequired:
- write files
- move or delete files
- commit or push
- access secrets
- contact external systems
forbidden:
- duplicate repoctl logic
- silently rewrite legacy KDB
- execute discovered handlers during assessment
```
Предлагаемый вызов для Claude:
```text
/repository-adoption C:\Users\alexander.baranov\Git\Infra\LXD --mode plan
```
До появления `repoctl adopt` skill выполняет runbook напрямую. После появления CLI он становится тонким wrapper: собирает недостающие решения пользователя, запускает команду и объясняет findings.
## 17. Что заимствовано из внешних практик
| Практика | Что используем |
|---|---|
| [Backstage component registration](https://backstage.io/docs/getting-started/register-a-component/) | сначала анализ существующего repository, затем review/import; descriptor добавляется PR |
| [Backstage catalog graph](https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph/) | repo-local YAML как source of truth; автоматическая классификация только начальная, metadata управляет человек |
| [Renovate onboarding](https://docs.renovatebot.com/getting-started/installing-onboarding/) | onboarding PR является безопасным gate; до merge другие изменения не выполняются |
| [Copier updates](https://copier.readthedocs.io/en/stable/updating/) | template lineage, сохранённые answers, versioned update и явная обработка conflicts |
| [OpenRewrite dry run](https://docs.openrewrite.org/reference/rewrite-maven-plugin) | recipe discovery, dry-run patch, review перед применением и возможность CI gate |
| [GitHub organization rulesets](https://docs.github.com/en/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) | rollout waves можно выбирать по repository properties, а enforcement включать после пилота |
Вывод из сравнения: adoption должен быть не генератором файлов, а повторяемым конвейером `discover → assess → plan → review → apply → verify`, где до review нет записи, а полезное содержимое репозитория не становится собственностью шаблона.
## 18. Definition of done
Repository считается adopted, когда:
- существует валидный `ops/contract.yaml`;
- тип, owner, lifecycle и content roots подтверждены;
- агент находит authoritative result paths без полного обхода дерева;
- intent получает небольшой релевантный KDB context;
- legacy KDB и domain content сохранены;
- `CLAUDE.md` остаётся основной Claude-точкой входа;
- portable instructions доступны через `AGENTS.md`, без import cycle;
- contract виден в производном catalog;
- unresolved warnings перечислены, имеют owner или осознанно deferred;
- diff и validation evidence доступны для review.
L2 operations, нормализация дерева, замена credentials и исправление найденных domain problems являются отдельными follow-up changes, а не скрытой частью adoption.
+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** — разные интерфейсы над одной моделью.
@@ -0,0 +1,692 @@
---
documentId: infrastructure-operations-architecture-options
documentVersion: 0.1.0
status: research
normative: false
language: ru
---
# Единый контракт сервисов и инфраструктуры: три варианта архитектуры
**Дата исследования:** 2026-08-19
**Статус:** концепция, изменений в исследованных репозиториях и системах не выполнялось
**Рекомендация:** вариант 1 — федеративный GitOps-контракт с единым протоколом операций; затем, при необходимости, поверх него вариант 3 — MCP-интерфейс.
## 1. Короткий вывод
Здесь уже есть почти все строительные блоки нужной системы, но они реализованы локально и несовместимо:
- сервисные репозитории Antivirus и GuardPlus хорошо отделяют знание о продукте от способа его размещения;
- LXD уже имеет машинную базу знаний с `constraints`, `tooling`, `workflows` и исполняемый handler с `validate`, `audit`, `diff`, `pull`, `push --dry-run`;
- Monitoring уже разделяет read-only audit, проверку дрейфа KDB и безопасный provisioning;
- AD уже использует правильную модель «несколько источников истины, каждый отвечает за свою грань» и отдельную reconciliation-операцию;
- Network уже использует inventory, dry-run, diff и специализированные drivers;
- Docker уже имеет достаточно устойчивые соглашения для стеков, но почти не имеет машинного контракта уровня всего репозитория.
Главный вывод: не следует начинать с общего сервера, которому разрешён произвольный SSH. Сначала нужно стандартизировать **описание сущностей, отношений, требований и операций** в Git. Исполнение должно оставаться в доменных адаптерах LXD, Docker, AD, Network и Monitoring.
Получится «MCP без транспорта»:
1. каждый репозиторий публикует одинаково устроенный контракт;
2. общий `opsctl` умеет найти контракты, построить граф и вызвать объявленную операцию;
3. операции имеют единый жизненный цикл `inspect → validate → plan → apply → verify → reconcile/rollback`;
4. skills лишь объясняют агенту, какую операцию выбрать, и не дублируют изменчивые факты;
5. позже тот же registry операций можно без переделки handlers опубликовать как настоящий MCP server.
## 2. Что было исследовано
### 2.1. Локальные репозитории
Проверены структура, управляющие документы, KDB, скрипты, skills и перекрёстные ссылки в:
- `Infra/Docker`;
- `Infra/LXD`;
- `Infra/AD`;
- `Infra/Network`;
- `Infra/Server-Hardware`;
- `Services/Antivirus`;
- `Services/GuardPlus`;
- `Services/Monitoring`;
- обзорно — остальные прямые подпапки `Infra/` и `Services/`.
В 14 прямых репозиториях/каталогах под `Infra/` и `Services/` соглашения распределены неравномерно: только 3 имеют корневой `AGENTS.md`, 4 — корневую или каталожную KDB, 4 — repo-local skills. Даже имя и положение базы знаний расходятся: `LXD/kdb.yaml`, `Antivirus/kdb/kdb.yaml`, набор отдельных файлов в `AD/kdb/` и `Monitoring/kdb/`.
### 2.2. Read-only SSH-проверка
Проверка выполнялась без копирования файлов, изменения конфигураций, рестартов и других записей.
- `cloud1`: Ubuntu 24.04.4 LTS, оба члена LXD-кластера ONLINE, предупреждений нет, ZFS-пулы healthy;
- LXD live inventory: 35 инстансов и новый проект `drweb`; документация от 2026-08-18 ещё содержит 34 инстанса и 9 проектов;
- `docker-manager0`: 6 Swarm-узлов Ready/Active, live-лидер — `docker-manager1`, 53 сервиса в 17 стеках;
- `dc01`: Debian 10, 26 GPO.
Эти расхождения не являются признаком плохой документации. Они показывают, что live-состояние по природе изменчиво и не должно копироваться в несколько README, skills и снимков без явной provenance и срока актуальности.
### 2.3. Внешние первичные источники
- MCP задаёт JSON-RPC base protocol, capability negotiation и раздельные server features: resources, prompts и tools. Для tools предусмотрены input/output schemas, структурированный результат, ошибки исполнения и подтверждение чувствительных операций клиентом: [MCP specification — Overview](https://modelcontextprotocol.io/specification/2025-11-25/basic), [MCP specification — Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
- Backstage показывает полезный, но более тяжёлый паттерн: YAML-descriptor хранится рядом с кодом, центральный каталог его агрегирует, а сам каталог не считается первоисточником. Отдельные сущности и relations формируют граф: [Software Catalog](https://backstage.io/docs/features/software-catalog/), [Creating the Catalog Graph](https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph/), [Descriptor Format](https://backstage.io/docs/features/software-catalog/descriptor-format/).
## 3. Наблюдения, которые определяют архитектуру
### 3.1. Граница ответственности уже найдена
GuardPlus формулирует её особенно удачно:
- чтобы **поднять контейнер** — артефакт принадлежит LXD;
- чтобы **понять или наполнить СКУД** — артефакт принадлежит GuardPlus.
Antivirus следует тому же принципу:
- продуктовые факты, проверенные пути, принятие сервиса и rollout — в `Services/Antivirus`;
- LXD profiles — в `Infra/LXD`;
- IP/DNS/firewall — в `Infra/Network`;
- proxy stack — в `Infra/Docker`;
- rollout Windows agent — в `Infra/AD`;
- наблюдаемость должна связываться с `Services/Monitoring`.
Эту границу не надо размывать общим монорепозиторием. Надо сделать её машинно-читаемой.
### 3.2. Единственной «истины обо всём» быть не должно
Для одного объекта существуют разные авторитетные грани:
| Грань | Кто владеет | Пример |
|---|---|---|
| Назначение и продуктовые требования | service repo | Antivirus знает порты DWCP, лицензию и правильный health probe |
| Желаемая инфраструктурная конфигурация | infra repo | LXD владеет profiles, Docker — stack spec, AD — GPO |
| Фактическое состояние | runtime API/CLI | `lxc list`, Docker API, Samba/UDM, Zabbix API |
| Исторический снимок | dated report | `reports/*-YYYY-MM-DD.md`, `instances.yaml` |
| Проверенные особенности продукта | KDB | provenance `VERIFIED/MANUAL/DRAFT/STALE` |
| Связь requirement → implementation | consumer + provider binding | Antivirus требует instance; LXD фиксирует, чем требование выполнено |
Центральный каталог может агрегировать эти грани, но не должен становиться ещё одним местом ручного редактирования тех же фактов.
### 3.3. Повторяющийся протокол операций уже сложился
Реальные handlers используют почти одинаковые понятия:
| Домен | Уже существующие операции |
|---|---|
| LXD | `list`, `pull`, `validate`, `audit`, `diff`, `push --dry-run`, `push` |
| Monitoring | read-only `audit --json`, KDB `validate/stale/drift`, provisioning `check/plan/apply/prune` |
| Network | inventory, discover, `check --diff`, `apply --dry-run`, `apply`, status |
| Docker | compose validation, stack deploy, service/stack inspection |
| AD | backup, apply via управляющий слой, reconciliation AD × audit × Fleet × assets |
Нужно унифицировать **семантику**, но не заменять эти handlers одним универсальным shell runner.
### 3.4. Skills не могут быть источником изменчивых фактов
В LXD одновременно отслеживаются `.agents/skills/lxd-profiles` и `.claude/skills/lxd-profiles`. Они уже различаются:
- старый handler: около 12.6 КБ;
- актуальный handler: около 29.9 КБ;
- актуальная версия добавила `audit`, JSON output, secret placeholders и cloud-init replay guard;
- обе копии отслеживаются Git и имеют разные SHA-256.
Это не косметический drift: агент, выбравший старую копию, получает менее безопасное поведение. Аналогично длинный Docker agent содержит снимочные сведения о topology, а `CLUSTER_STATE.md` уже отстал от live-лидера.
Следствие: skill должен быть тонким UX-слоем, а исполняемый код, constraints и registry операций — иметь ровно одну каноническую копию.
### 3.5. Cross-repo транзакции невозможны, но возможен проверяемый план
Добавление сервиса часто меняет LXD, Network, Docker, AD и Monitoring. Git и эти runtime не поддерживают общую транзакцию. Поэтому правильная единица работы — не «одна атомарная команда», а **неизменяемый план с checkpoints**:
1. зафиксировать revisions входных репозиториев и live snapshots;
2. построить план и dependency order;
3. применить один provider change;
4. выполнить provider verification;
5. выполнить service acceptance;
6. только затем перейти к следующему шагу;
7. хранить run evidence и явно указывать, где rollback невозможен.
## 4. Общая модель, одинаковая для всех трёх вариантов
### 4.1. Минимальный шаблон репозитория
Не нужно немедленно переносить существующие `profiles-source/`, Docker stack folders или `endpoint-management/`. Контракт декларирует их как domain-native paths.
```text
repo/
├── README.md # вход для человека, без дублирования live-снимков
├── AGENTS.md # короткий pointer: прочитать ops/contract + constraints
├── ops/
│ ├── contract.yaml # канонический repo/service/infra contract
│ ├── handlers/ # исполняемая реализация операций
│ ├── schemas/ # repo-specific input/output schemas при необходимости
│ ├── templates/ # scaffolds новых компонентов/ресурсов
│ └── tests/ # contract, safety и handler tests
├── kdb/
│ ├── index.yaml # навигация, provenance и routing вопросов
│ └── *.yaml # проверенные факты и ограничения по подсистемам
├── docs/
│ ├── architecture/ # живые объяснения и ADR
│ ├── runbooks/ # процедуры и rollback
│ └── reports/ # датированные, неизменяемые snapshots/evidence
├── <domain-native paths>/ # profiles-source, stacks, endpoint-management и т. п.
├── .agents/skills/ # тонкие adapters для агента; без handlers и live facts
└── .secrets.example # только схема/имена, без значений
```
Для постепенного внедрения допустимо оставить текущую KDB на месте и указать её через `spec.knowledge.entrypoint`. Стандартизировать путь можно позже; семантика важнее миграции каталогов.
### 4.2. Контракт репозитория
Пример намеренно сокращён. Реальная схема должна валидироваться JSON Schema и иметь versioning.
```yaml
apiVersion: ops.corsus.pro/v1alpha1
kind: RepositoryContract
metadata:
name: antivirus
repo: Services/Antivirus
class: service # service | infrastructure | platform | data
lifecycle: production
owners: [corsus-it]
spec:
authority:
owns:
- product.requirements
- product.knowledge
- service.acceptance
doesNotOwn:
- lxd.profile
- network.ipam
- docker.stack
- ad.gpo
knowledge:
entrypoint: kdb/kdb.yaml
provenance: [VERIFIED, MANUAL, DRAFT, STALE]
requires:
- id: ess-compute
capability: compute.lxd.instance
constraints:
environment: production
placement: cloud1
- id: ess-address
capability: network.static-address
- id: ess-dns
capability: network.dns-record
- id: windows-rollout
capability: identity.software-rollout
- id: service-monitoring
capability: observability.service
provides:
- id: drweb-control-plane
capability: antivirus.endpoint-control
operations:
- id: service.inspect
summary: Read deployed state without trusting the SysV-generated systemd status
effect: read
risk: low
handler: ops/handlers/service.py
args: [inspect]
outputSchema: ops/schemas/service-state.json
- id: service.accept
summary: Verify process, listeners, API and licence after an infrastructure change
effect: read
risk: low
handler: ops/handlers/service.py
args: [accept]
outputSchema: ops/schemas/acceptance-result.json
secrets:
policy: references-only
allowedRefs: [repo-local-env, runtime-secret]
```
Provider repo публикует capabilities и bindings, а не копирует требования сервиса:
```yaml
spec:
provides:
- capability: compute.lxd.instance
bindings:
- id: drweb-ess-lxd
fulfills: repo:Services/Antivirus#requirement/ess-compute
implementation:
project: drweb
instance: drweb-ess
profiles: [default, drweb-base, drweb-server]
desiredStatePaths:
- projects/drweb/
- profiles-source/drweb-base.yaml
- profiles-source/drweb-server.yaml
inspectOperation: lxd.instance.inspect
```
Правило владения связью:
- consumer владеет `requires` и acceptance criteria;
- provider владеет `bindings` и инфраструктурной реализацией;
- агрегатор строит relation только если обе стороны совместимы;
- unresolved requirement и orphan binding являются диагностируемым drift.
### 4.3. Унифицированный жизненный цикл операций
| Фаза | Семантика | Разрешённый эффект |
|---|---|---|
| `describe` | показать контракт, capabilities, constraints, schemas | read |
| `inspect` | получить live state из авторитетного API/CLI | read |
| `snapshot` | записать датированное evidence | local-write |
| `validate` | проверить source, schema, policy и preconditions | read/local temp |
| `diff` | сравнить desired ↔ live ↔ last verified | read |
| `plan` | построить точный change set и verification plan | read/local artifact |
| `apply` | применить ровно сохранённый plan | external-write |
| `verify` | platform checks + service acceptance | read |
| `reconcile` | классифицировать drift и предложить направление исправления | read; apply отдельно |
| `rollback` | восстановить snapshot или выполнить compensating action | external-write/disruptive |
Не каждый домен обязан поддерживать все verbs. Неподдерживаемая операция объявляется явно, как сейчас в LXD объявлены out-of-scope instance lifecycle и project management.
### 4.4. Обязательные поля операции
Каждая исполняемая операция должна объявлять:
- стабильный `id` и краткое назначение;
- input/output JSON Schema;
- `effect`: `read`, `local-write`, `external-write`, `disruptive`, `destructive`;
- `risk`: `low`, `medium`, `high`, `critical`;
- target selector и границы допустимого scope;
- credential references без значений;
- preconditions;
- поддержку `dryRun` и idempotency, если она реальна;
- `mutates`: какие repo paths и runtime objects могут измениться;
- confirmation policy;
- verification operation;
- rollback/compensation или явное `rollback: unavailable`;
- timeout и exit-code semantics;
- redaction policy;
- evidence, которое записывается после запуска.
Нельзя объявлять произвольную shell-строку как публичную операцию. Registry должен ссылаться на allowlisted handler и argv; handler сам ограничивает команды и targets.
### 4.5. Формат plan и run evidence
`plan` должен быть самостоятельным артефактом, например `ops-plan.json`:
```json
{
"apiVersion": "ops.corsus.pro/v1alpha1",
"operation": "lxd.instance.migrate",
"createdAt": "2026-08-19T12:00:00Z",
"inputsHash": "sha256:...",
"repoRevisions": {
"Infra/LXD": "<git-sha>",
"Services/Antivirus": "<git-sha>"
},
"liveSnapshotHash": "sha256:...",
"targets": ["lxd:drweb/drweb-ess"],
"steps": [],
"verification": [],
"rollback": {},
"risk": "high"
}
```
`apply` принимает plan hash и отказывается работать, если revisions, targets или критичные live preconditions изменились. Это защищает от применения старого dry-run к уже изменившейся среде.
### 4.6. Базовый набор skills
Skills должны быть короткими orchestrators, а не вторыми README или копиями Python handlers.
| Skill | Задача |
|---|---|
| `ops-discover` | найти contracts под `~/Git`, построить catalog и relation graph |
| `ops-repo-onboard` | проверить/сгенерировать минимальный contract для существующего repo |
| `ops-change-plan` | разрешить requirements к providers и построить cross-repo plan |
| `ops-drift-audit` | вызвать domain inspect/diff и классифицировать drift |
| `ops-safe-apply` | проверить plan hash, approval и вызвать domain apply |
| `ops-verify` | собрать provider verification и service acceptance |
| `ops-reconcile` | найти unresolved requirements, orphan bindings, stale facts и snapshots |
| `ops-incident-snapshot` | read-only evidence из нескольких providers с redaction |
| `ops-service-integrate` | сценарий «новый компонент сервиса → инфраструктурные bindings» |
| `ops-workload-migrate` | сценарий «инфраструктурное перемещение → service-aware plan» |
Domain skills остаются, но становятся adapters:
- `lxd-ops`;
- `swarm-ops`;
- `ad-ops`;
- `network-ops`;
- `monitoring-ops`;
- `hardware-ops`.
Каждый такой skill обязан сначала читать `ops/contract.yaml` и KDB constraints, затем вызывать канонический handler. Hostnames, current leaders, instance counts и версии в skill не помещаются.
### 4.7. Два ключевых сценария
#### Сервис добавляет компонент
Пример: Antivirus добавляет proxy и rollout endpoints.
1. Service repo добавляет/уточняет requirements и acceptance criteria.
2. `ops-change-plan` находит providers:
- LXD — server instance;
- Docker — proxy на NAS02;
- Network — route/IP/DNS/firewall;
- AD — Windows rollout;
- Monitoring — service checks.
3. Каждый provider возвращает свой `validate/diff/plan`.
4. Общий plan строит dependency order, но не склеивает changes в одну непрозрачную команду.
5. После каждого apply выполняется provider verify.
6. В конце Antivirus выполняет end-to-end acceptance.
7. Providers записывают bindings; service repo не копирует их конфигурацию.
#### Инфраструктура переносит сервисы на новые хосты
1. LXD выбирает candidate instances и публикует proposed placement plan.
2. Catalog находит связанные service contracts и их требования: downtime, backup, affinity, address stability, health/acceptance operations.
3. Capacity/placement validation выполняется инфраструктурой; service impact validation — сервисом.
4. Миграция идёт batch-ами с checkpoints.
5. После platform verification выполняются service acceptance и monitoring verification.
6. Binding обновляется только после успешной проверки; старый host остаётся в evidence, а не в актуальном contract.
```mermaid
flowchart LR
S[Service requires + acceptance] --> C[Catalog / relation graph]
I[Infrastructure capabilities + bindings] --> C
C --> P[Immutable cross-repo plan]
P --> L[LXD adapter]
P --> D[Docker adapter]
P --> N[Network adapter]
P --> A[AD adapter]
P --> M[Monitoring adapter]
L --> V[Provider verification]
D --> V
N --> V
A --> V
M --> V
V --> E[Service end-to-end acceptance]
```
## 5. Вариант 1 — федеративный GitOps-контракт + общий CLI
**Рейтинг: 9.2/10 — рекомендуемый первый этап и основная архитектура.**
### Суть
Каждый repo хранит `ops/contract.yaml`, свои handlers и свои authoritative artifacts. Небольшой общий `opsctl` сканирует `~/Git/Infra` и `~/Git/Services`, валидирует contracts, строит relation graph и вызывает repo-local operations.
Центрального постоянно работающего сервера нет. Catalog — производный локальный JSON/SQLite cache, который всегда можно перестроить из Git.
Пример UX:
```text
opsctl catalog build ~/Git/Infra ~/Git/Services
opsctl entity show service:antivirus
opsctl operations list --entity service:antivirus
opsctl plan service.integrate --service antivirus --component drweb-proxy
opsctl apply --plan .ops/runs/<id>/plan.json --confirm "APPLY <id>"
opsctl verify --run <id>
opsctl reconcile --all
```
### Сильные стороны
- совпадает с текущей границей ответственности repo;
- не требует переносить domain-native конфигурацию;
- минимальная blast radius: handler работает только в своём домене;
- Git остаётся источником desired state и review trail;
- можно внедрять по одному repo;
- работает без отдельной платформы, БД, OAuth и высокой доступности;
- создаёт правильный фундамент для будущего MCP;
- легче всего автоматизировать CI-проверки contracts, duplicate skills и stale facts.
### Слабые стороны
- первый catalog/graph будет CLI, без красивого портала;
- cross-repo plan требует дисциплины versioning и стабильных IDs;
- локальный запуск зависит от доступности нескольких repos и credentials;
- нужно поддержать Windows и Linux execution paths.
### Как устроены skills
- общий набор orchestration skills устанавливается один раз;
- domain skills остаются рядом с repo;
- handlers лежат только в `ops/handlers`, а `.agents/skills` содержит инструкции и ссылки;
- если нужна совместимость `.agents` и `.claude`, wrapper-файлы генерируются из одного template, а CI сравнивает их hash/semantic version.
### Когда выбирать
Сейчас. Это наименьшее изменение, которое решает реальные проблемы ownership, drift, discoverability и безопасного исполнения.
## 6. Вариант 2 — центральный Ops Catalog / Ops Hub
**Рейтинг: 7.4/10 — полезен для обзора, слабее как первичный control plane.**
### Суть
Создаётся отдельный repo, например `Ops/Catalog`, содержащий registry всех entities, operations, templates и связей. В более полном виде рядом разворачивается web UI по модели Backstage-lite.
Есть два подварианта:
1. центральные descriptor files редактируются вручную;
2. рекомендуемый — repo-local contracts остаются первоисточниками, а hub только harvest/cache/UI.
Только второй подвариант приемлем: официальный Backstage также рекомендует считать Git descriptor files первоисточником, а catalog — агрегатором.
### Сильные стороны
- лучший обзор ownership, lifecycle, dependencies и незакрытых требований;
- удобная точка входа для людей;
- templates и onboarding новых repos можно сделать через формы;
- проще строить отчёты: orphan services, stale verification, неподключённый monitoring;
- хорошо масштабируется, если репозиториев станет много.
### Слабые стороны
- отдельный сервис, БД, auth, backup и upgrade lifecycle;
- соблазн начать редактировать runtime facts в каталоге и получить ещё один источник drift;
- центральная команда/схема становится bottleneck;
- custom actions с правом SSH/API резко увеличивают blast radius;
- для текущих 14 прямых repos полноценный Backstage, вероятно, преждевременен.
### Как устроены skills
- skills сначала спрашивают catalog API о relations и operation endpoints;
- исполнение всё равно делегируется domain adapters;
- hub не получает универсального `run_shell`;
- templates создают merge requests в owning repos, а не меняют live напрямую.
### Когда выбирать
После варианта 1, если CLI-каталог перестанет удовлетворять людей или появится необходимость в self-service portal. Как замена repo-local contracts этот вариант не рекомендуется.
## 7. Вариант 3 — полноценный Ops MCP control plane
**Рейтинг сейчас: 6.8/10. Потенциал после варианта 1: 9.0/10.**
### Суть
Registry операций публикуется через настоящий MCP server:
- **resources**: entities, contracts, KDB sections, plans, run evidence, live read-only snapshots;
- **tools**: `catalog.search`, `entity.describe`, `operation.plan`, `operation.apply`, `operation.verify`, `drift.inspect`;
- **prompts**: типовые сценарии onboarding, migration, incident triage;
- tool schemas автоматически выводятся из того же contract schema.
MCP является транспортом и discovery layer, но не заменяет GitOps, domain handlers и safety policy.
### Сильные стороны
- естественный discovery операций для Codex/Claude и других клиентов;
- строгие schemas вместо разбора текстового CLI output;
- единый structured result и actionable tool errors;
- можно централизовать audit events, rate limits и policy checks;
- удобно подключать уже существующие Grafana/Prometheus MCP servers как read-only providers;
- отличный long-term интерфейс поверх стабильного operation registry.
### Слабые стороны
- высокий начальный объём: server, authorization, scopes, audit, secrets broker, availability;
- опасно публиковать write-tools до формализации effects, plan hashes и approvals;
- MCP tool annotations нельзя считать достаточной защитой: сервер обязан валидировать input и access сам;
- один компрометированный control plane может получить доступ сразу к LXD, Docker, AD и Network;
- без варианта 1 MCP server быстро превратится в набор hand-written tools с разными semantics;
- transport/API versioning добавится к contract и handler versioning.
### Рекомендуемые scopes
```text
catalog:read
state:read
plan:create
evidence:write
lxd:apply
docker:apply
network:apply
ad:apply
monitoring:apply
destructive:approve
```
Write scopes должны быть domain-specific. Нельзя выдавать один общий `infra:write`. Credentials downstream-систем не должны передаваться MCP client: server использует отдельные audience-bound credentials для каждого provider.
### Как устроены skills
Skills становятся в основном routing/policy инструкциями:
- какие resources сначала прочитать;
- когда разрешён только `plan`;
- какой confirmation нужен;
- как объединить provider verification с service acceptance.
Вся фактическая schema операции и её execution остаются на server/handler side.
### Когда выбирать
После того как минимум LXD, Docker, Network, AD и один service repo реализовали вариант 1 и показали одинаковые semantics на реальных сценариях. Начинать сразу с write-capable MCP не рекомендуется; допустим ранний read-only MCP для catalog/search/inspect.
## 8. Сравнение вариантов
Вес критериев отражает текущую ситуацию: безопасность и устойчивость к drift важнее UI.
| Критерий | Вес | Вариант 1: federated CLI | Вариант 2: Ops Hub | Вариант 3: MCP сейчас |
|---|---:|---:|---:|---:|
| Соответствие существующим repos и ownership | 25% | 9.5 | 7.5 | 8.0 |
| Безопасность исполнения | 25% | 9.5 | 7.5 | 5.5 |
| Устойчивость к drift | 20% | 9.5 | 6.5 | 7.0 |
| Стоимость запуска | 15% | 8.5 | 6.5 | 4.5 |
| Расширяемость и discoverability | 15% | 8.5 | 9.0 | 10.0 |
| **Итог** | **100%** | **9.2/10** | **7.4/10** | **6.8/10** |
MCP получает 9.0/10 как следующий слой после варианта 1, потому что к тому времени самые сложные части — ownership, schemas, effects, handlers и safety — уже проверены независимо от транспорта.
## 9. Рекомендуемая последовательность внедрения
### Фаза 0 — договориться о semantics
Зафиксировать один schema package:
- `RepositoryContract`;
- `Requirement`;
- `Capability`;
- `Binding`;
- `Operation`;
- `Plan`;
- `RunEvidence`.
Стабильные IDs важнее полноты первой версии. Начать с `v1alpha1`, не обещая обратную совместимость до двух пилотов.
### Фаза 1 — два вертикальных пилота
Пилот A, service-driven:
- `Services/Antivirus` как consumer;
- `Infra/LXD`, `Infra/Network`, `Infra/AD`, `Services/Monitoring` как providers;
- сценарий: описать уже работающий `drweb-ess`, обнаружить fulfilled и unresolved requirements, выполнить read-only acceptance.
Пилот B, infrastructure-driven:
- `Infra/LXD`;
- выбрать тестовый workload;
- построить migration plan с service-owned acceptance;
- apply пока не выполнять — проверить полноту plan, preconditions и rollback.
### Фаза 2 — канонические handlers и thin skills
- перенести LXD handler в единственное каноническое место;
- убрать код и volatile facts из skills;
- добавить одинаковый `--json` envelope и exit codes;
- покрыть safety self-tests;
- добавить CI-проверку, запрещающую drift между compatibility wrappers;
- адаптировать Monitoring audit/provisioning как эталон разделения read/write;
- формализовать Docker repository-level KDB и operations, не копируя stack facts в agent text.
### Фаза 3 — локальный catalog и reconciliation
- `opsctl catalog build`;
- graph requirements/bindings;
- `opsctl validate --all`;
- `opsctl reconcile --all`;
- отчёт по stale verified facts, unresolved requirements, orphan bindings и unsupported operations.
### Фаза 4 — только затем интерфейс
Выбор по фактической потребности:
- достаточно CLI — остаться на варианте 1;
- нужен human portal — добавить вариант 2 как derived UI;
- нужен agent/tool interoperability — добавить read-only MCP, затем строго scoped write-tools.
## 10. Что принципиально не делать
- Не создавать центральный YAML со всеми IP, hostnames, versions и counts вручную.
- Не считать snapshot desired state.
- Не помещать live topology в `SKILL.md` или `AGENTS.md`.
- Не дублировать один handler под `.agents` и `.claude` без generation/hash check.
- Не давать общему агенту произвольный SSH/shell как «универсальную операцию».
- Не считать `--dry-run` безопасным без измерения before/after, как уже правильно делает Monitoring.
- Не считать source автоматически правильнее live: LXD уже знает случаи intentional drift.
- Не выполнять cross-repo apply без сохранённого plan, revisions и checkpoints.
- Не требовать rollback там, где он физически невозможен; объявлять compensating action и остаточный риск.
- Не хранить secret values в contract, KDB, evidence или MCP result.
- Не делать catalog новым источником истины: это rebuildable projection.
## 11. Критерии готовности первой версии
Первая версия считается полезной, если выполняются все условия:
1. `opsctl` находит contracts минимум Antivirus, LXD, Network, AD и Monitoring.
2. Contract validation работает полностью offline.
3. Catalog показывает requirement `Antivirus → LXD` и соответствующий provider binding.
4. Read-only `inspect` выдаёт единый JSON envelope независимо от домена.
5. LXD и Monitoring поддерживают `validate/diff-or-drift/plan/verify` с одинаковой семантикой exit codes.
6. Ни один mutating handler не доступен без plan и явного approval.
7. Service acceptance живёт в service repo и вызывается после provider verification.
8. Stale snapshot не выглядит как current state: есть `observedAt`, provenance и probe reference.
9. Две agent ecosystems не могут незаметно получить разные handlers.
10. `reconcile` обнаруживает как минимум:
- unresolved requirement;
- orphan binding;
- stale verified fact;
- desired/live drift;
- отсутствующую verification operation.
## 12. Итоговое решение
Рекомендуемая архитектура — **вариант 1 как ядро, вариант 3 как будущий транспорт**.
Ключевая идея не в едином инструменте, который умеет всё, а в едином договоре о том:
- как repo сообщает, чем он владеет;
- что сервис требует от инфраструктуры;
- чем provider это требование выполнил;
- какие операции доступны;
- что операция читает и меняет;
- как строится план;
- как проверяется результат;
- где лежит rollback;
- откуда взят каждый факт и когда он был проверен.
После этого локальный CLI, портал и MCP становятся взаимозаменяемыми интерфейсами над одной моделью. Без этого любой «импровизированный MCP» лишь централизует текущую неоднородность и увеличит blast radius.
File diff suppressed because it is too large Load Diff