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
+12
View File
@@ -0,0 +1,12 @@
.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.mypy_cache/
.ruff_cache/
dist/
build/
*.egg-info/
coverage.xml
.coverage
+56
View File
@@ -0,0 +1,56 @@
# Repository instructions
## Purpose
This repository defines Repository Stewardship: harness-neutral contracts, knowledge routing, templates and adoption practices for managing Git repositories with humans and AI agents.
It currently contains specifications and runbooks. `repoctl`, executable handlers and an MCP server are planned interfaces, not implemented tools in this repository.
## Start here
1. Read `ops/contract.yaml` to identify the repository and authoritative content roots.
2. Read the small index in `kdb/kdb.yaml`.
3. Match the task to an exact topic intent.
4. Open only the documents and headings named by that topic's `data.readHints`.
Do not load every design document by default.
## Authority order
- `docs/specification.md` is normative for fields, invariants and compatibility.
- `docs/adoption-runbook.md` is the canonical procedure for existing repositories.
- `docs/guide.md` explains the same model for people.
- `docs/research/` preserves earlier research and alternatives; it is not the current contract.
If documents disagree, follow this order and record the discrepancy instead of silently merging meanings.
## Repository boundaries
- Keep domain-neutral standards here.
- Do not copy LXD, Docker, Antivirus or other domain handlers into this repository.
- Skills and MCP adapters must remain thin interfaces over the same model and future `repoctl` behavior.
- Do not claim an operation exists until a canonical handler and validation path exist.
- Keep canonical long-form documents under `docs/`; use deeper nesting only for a distinct authority class such as `docs/research/`.
## Editing rules
- Keep YAML examples machine-parseable.
- Use `stewardship.corsus.ru/v1alpha1`; do not introduce an alternative API group without a versioned migration.
- Keep Claude as the primary agent while preserving portable instructions in this file.
- A normative schema change must update affected examples, the human guide, KDB routing and adoption rules in the same change.
- Use Mermaid for architecture and workflow diagrams.
- Preserve unrelated user changes and do not modify other repositories unless the task explicitly includes them.
- Never place secrets, private keys, tokens or live credentials in contracts, KDB, examples or evidence.
## Validation before completion
- Parse Markdown frontmatter and every fenced YAML block.
- Validate `ops/contract.yaml` and `kdb/kdb.yaml` as YAML resources.
- Check KDB topic-to-document references and repo-relative paths.
- Check local Markdown links and balanced code fences.
- Statically check Mermaid block headers; render them when a Mermaid renderer is available.
- Confirm changed paths match the requested scope.
## Self-hosting rule
This repository should follow its own standard only where that adds discovery, safety or maintainability. Avoid placeholder directories, fake handlers, fictional capabilities and duplicated documentation created only for visual symmetry.
+10
View File
@@ -0,0 +1,10 @@
# CLAUDE.md
@AGENTS.md
## Claude-specific guidance
- Treat `kdb/kdb.yaml` as the routing index, not as a request to read every linked document.
- For bootstrap or adoption work, produce assessment and proposed diff before writing.
- Ask only for decisions that cannot be established from repository evidence, such as ambiguous ownership or source-of-truth conflicts.
- Do not invoke future `repoctl` commands as if they already exist; follow the documented procedure manually until the CLI is implemented.
+50
View File
@@ -0,0 +1,50 @@
# Repository Stewardship
Этот репозиторий разрабатывает стандарт и будущий инструментарий для единообразной работы с Git-репозиториями при помощи людей и любых AI-агентов.
Основная идея: каждый репозиторий сам сообщает, что он содержит, где лежит его реальный результат, какие знания нужны для конкретной задачи и какие действия допустимы. Claude является основным агентом, но модель не зависит от Claude, LLM, skill format или MCP.
## Текущее состояние
Сейчас здесь находятся спецификация, руководство и adoption runbook. CLI `repoctl`, handlers и MCP server ещё не реализованы; команды в документации определяют целевой интерфейс.
| Точка входа | Назначение |
|---|---|
| `ops/contract.yaml` | машиночитаемый паспорт этого репозитория |
| `kdb/kdb.yaml` | маршрутизация знаний по intent |
| `CLAUDE.md` | основная точка входа Claude |
| `AGENTS.md` | переносимые инструкции для агентов |
| `docs/specification.md` | нормативная спецификация |
| `docs/guide.md` | объяснение модели для человека |
| `docs/adoption-runbook.md` | перевод существующих репозиториев на стандарт |
| `docs/research/` | исходные архитектурные исследования |
## Как пользоваться содержимым
```mermaid
flowchart LR
TASK["Задача"] --> CONTRACT["ops/contract.yaml"]
CONTRACT --> KDB["kdb/kdb.yaml"]
KDB --> TOPIC["Тема по exact intent"]
TOPIC --> SECTIONS["Только нужные документы и разделы"]
SECTIONS --> RESULT["Решение или proposed change"]
```
Для понимания модели начните с [руководства](docs/guide.md). Для реализации форматов используйте [спецификацию](docs/specification.md). Для подключения существующего репозитория следуйте [adoption runbook](docs/adoption-runbook.md).
## Почему структура минимальна
Репозиторий применяет собственную концепцию без декоративной унификации:
- действующие документы собраны в одном content root `docs/`, а исходное исследование отделено в `docs/research/`;
- не созданы пустые `templates/`, `schemas/`, `src/` или `ops/handlers/`;
- не объявлены исполняемые operations, поскольку handlers ещё отсутствуют;
- template lineage не записан, потому что этот repository не был создан из готового versioned template;
- будущий код добавит собственный content root тогда, когда он действительно появится.
## Ближайший практический этап
1. Зафиксировать schemas и fixtures четырёх типов репозиториев.
2. Реализовать read-only `validate`, `discover`, `describe` и `context`.
3. Выполнить plan-only adoption для `Infra/LXD` и `Services/Antivirus`.
4. После пилотов реализовать `init`, `adopt` и тонкий Claude skill.
+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
+186
View File
@@ -0,0 +1,186 @@
apiVersion: stewardship.corsus.ru/v1alpha1
kind: KnowledgeBase
metadata:
name: repository-stewardship-kdb
title: Repository Stewardship knowledge index
spec:
repository: repo:repository-stewardship
defaultLanguage: ru
topics:
- id: repository-bootstrap
title: Bootstrap a new repository
summary: Choose a repository type and create the minimal Stewardship layer without inventing domain content
intents:
- repository.initialize
- repository.bootstrap
keywords:
- init
- template
- ssh
- contract
priority: 90
documents:
- stewardship-specification
- stewardship-guide
data:
loadPolicy: headings-only
readHints:
- document: stewardship-specification
headings:
- 1. Цели и границы
- 3. Каноническое обнаружение
- 5. RepositoryContract
- 6. ContentRoot
- 17. Agent entrypoints и adapters
- 18. Bootstrap, adoption и template update
- document: stewardship-guide
headings:
- 4. Минимальная структура репозитория
- 5. Четыре типа репозиториев
- 17. Bootstrap нового и adoption существующего репозитория
- id: repository-adoption
title: Adopt an existing repository
summary: Assess, plan and apply a metadata overlay while preserving existing authoritative content
intents:
- repository.adopt
- repository.standardize
- repository.normalize
keywords:
- assess
- overlay
- legacy
- migration
priority: 100
documents:
- adoption-runbook
- stewardship-specification
data:
loadPolicy: runbook-first
phases:
- assess
- plan
- review
- apply
- verify
readHints:
- document: adoption-runbook
headings:
- 3. Safety invariants
- 6. Phase 1 — preflight
- 7. Phase 2 — assessment
- 10. Phase 4 — adoption plan
- 11. Compatibility rules
- 11.5. Normalization recipe documents-to-content-root
- 12. Phase 5 — apply
- 13. Phase 6 — verify
- id: stewardship-model
title: Understand or evolve the model
summary: Definitions, invariants, schemas and the reasoning behind Repository Stewardship
intents:
- repository.model.explain
- repository.model.change
- repository.standard.design
keywords:
- contract
- intent
- capability
- requirement
- binding
- kdb
priority: 80
documents:
- stewardship-specification
- stewardship-guide
- architecture-options
data:
loadPolicy: specification-first
authorityOrder:
- stewardship-specification
- stewardship-guide
- architecture-options
- id: tooling-implementation
title: Implement repoctl or an adapter
summary: Implementation boundary, commands, validation rules and harness-neutral adapter design
intents:
- repository.tooling.implement
- repository.tooling.test
- repository.adapter.create
keywords:
- repoctl
- parser
- schema
- validator
- skill
- mcp
priority: 85
documents:
- stewardship-specification
- adoption-runbook
- stewardship-guide
data:
loadPolicy: selected-sections
readHints:
- document: stewardship-specification
headings:
- 19. Команды MVP
- 20. Validation rules MVP
- 21. Security invariants
- 22. Versioning и расширения
- 23. Порядок реализации
- 24. Acceptance criteria MVP
- document: stewardship-guide
headings:
- 14. Интерфейсы для агентов и людей
- 15. Простая первая версия
- 16. Предлагаемая внутренняя структура repoctl
- id: architecture-research
title: Revisit architecture choices
summary: Earlier alternatives, trade-offs and external design lineage
intents:
- repository.architecture.research
- repository.architecture.compare
keywords:
- architecture
- alternatives
- backstage
- gitops
- mcp
priority: 50
documents:
- architecture-options
- stewardship-specification
data:
loadPolicy: research-on-demand
readHints:
- document: stewardship-specification
headings:
- 28. Design lineage
documents:
- id: stewardship-specification
title: Repository Stewardship Protocol
role: reference
path: docs/specification.md
mediaType: text/markdown
authority: local-canonical
status: draft
- id: stewardship-guide
title: Repository Stewardship human guide
role: explanation
path: docs/guide.md
mediaType: text/markdown
authority: local-canonical
status: draft
- id: adoption-runbook
title: Repository Adoption Runbook
role: runbook
path: docs/adoption-runbook.md
mediaType: text/markdown
authority: local-canonical
status: draft
- id: architecture-options
title: Infrastructure operations architecture options
role: explanation
path: docs/research/infrastructure-operations-architecture-options.md
mediaType: text/markdown
authority: manual
status: draft
+47
View File
@@ -0,0 +1,47 @@
apiVersion: stewardship.corsus.ru/v1alpha1
kind: RepositoryContract
metadata:
name: repository-stewardship
title: Repository Stewardship standards and templates
owners:
- alexander.baranov
labels:
domain: repository-management
role: standards-and-templates
annotations:
stewardship.corsus.ru/bootstrap-mode: self-hosted
stewardship.corsus.ru/implementation-status: specification-only
spec:
summary: Standards, templates and adoption guidance for AI-assisted repository management
repository:
type: project
lifecycle: active
agent:
primary: CLAUDE.md
portable: AGENTS.md
knowledge:
entrypoint: kdb/kdb.yaml
contentRoots:
- id: canonical-documents
role: documentation
path: docs
kind: file-set
authority: source
writePolicy: managed
selector: "*.md"
format: text/markdown
- id: architecture-research
role: design-source
path: docs/research
kind: file-set
authority: source
writePolicy: managed
selector: "**/*.md"
format: text/markdown
provides:
- id: stewardship-model
capability: repository.stewardship-model
summary: Versioned contract and knowledge model for managed repositories
- id: adoption-procedure
capability: repository.adoption-procedure
summary: Safe overlay procedure for bringing existing repositories into the model