docs: baseline specification-only repository stewardship
This commit is contained in:
+119
@@ -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 сохраняются без изменений.
|
||||
@@ -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
@@ -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
Reference in New Issue
Block a user